User Story

As an operator who has just generated a PRD via /write-spec, an audit via /threat-model, or an architecture vision via /tech-vision, I want to export that doc to PDF with a single command — and at export time, I want to be asked where the PDF lands, because the answer depends on whether the doc should follow the code (project repo's docs/) or stay in ApexYard's view of the project (projects/<name>/).

Context

Framework-generated docs live as their source format today (Markdown for most, HTML for /journey, BPMN XML for /process). Sharing with non-technical stakeholders, board members, customers, or auditors often wants a PDF.

The destination question matters because it mirrors the existing "would it follow the code if the project spun out tomorrow?" rule from docs/multi-project.md:

The skill should ask, not guess.

Acceptance Criteria

• New skill /pdf <input-file> at .claude/skills/pdf/SKILL.md
• Input formats supported: markdown (.md), HTML (.html), BPMN (.bpmn — rendered via bpmn-to-image or similar)
• Operator destination prompt:

  Where should the PDF land?
    (1) workspace/<name>/docs/<file-stem>.pdf  ← travels with the code
    (2) projects/<name>/pdfs/<file-stem>.pdf   ← ApexYard's view
    (3) <custom path>                          ← anywhere
    (k) keep next to source                    ← <input-dir>/<file-stem>.pdf
  

• Converter preference (configurable):
  1. Pandoc (preferred — high quality, broad input support)
  2. md-to-pdf (npm fallback for markdown inputs)
  3. wkhtmltopdf (HTML inputs)
  4. bpmn-to-image (BPMN → SVG → PDF pipeline)
• Graceful degrade: if no converter is installed, print clear advisory naming each option + install command; exit 3 (same shape as _lib-mermaid-lint.sh / _lib-bpmnlint)
• Adopter config in .claude/project-config.defaults.json:

  "pdf": {
    "preferred_converter": "pandoc",
    "pdf_engine": "xelatex",
    "default_destination": "ask"
  }

• Optional --no-prompt flag (uses default_destination from config, fails if config is ask)
• Filename rule: <input-stem>.pdf by default; <input-stem>-<YYYY-MM-DD>.pdf if input file is in audits/<dim>/<ts>.md (audit-class outputs get dated PDFs to match the audit's dated-subdir convention)
• Tests:
  • markdown → PDF (smoke, requires pandoc)
  • HTML → PDF (smoke, requires wkhtmltopdf or playwright)
  • Missing-converter graceful degrade (no converter installed → exit 3, advisory)
  • Destination prompt resolves each option correctly
• Docs note in docs/multi-project.md § "Architecture diagrams" extending the "would it follow the code?" rule to PDF outputs
• AgDR if the converter-choice introduces a meaningful new dep (pandoc isn't yet a framework dependency; bpmn-to-image isn't either)

Out of scope (deferred)

• --pdf flag on each doc-emitting skill that does the export at write-time. Cleaner UX (one command, one output) but couples every doc skill to the converter dep. Standalone /pdf is the v1 path; per-skill flag can land in v1.5.0 if operators use it enough.
• Custom PDF templates (LaTeX styles, header/footer, branding). Use the system pandoc defaults for v1; templating is its own ticket.
• Batch export (one command, multiple files). Out of scope; operators can loop in shell if needed.

Risks

• Pandoc dep weight: pandoc + xelatex is ~500MB on first install. Document this clearly; the graceful-degrade exit-3 path ensures adopters who don't want to install it can still use every other skill.
• HTML → PDF rendering quirks: especially for /journey's interactive modals. The journey.html shape may need a "print stylesheet" companion to render flat-paged. Out of scope v1 — /pdf journey.html v1 produces a "best effort" PDF; operators wanting pixel-perfect should screenshot the modals manually.
• BPMN → PDF: requires rendering through a BPMN visualizer first (bpmn-auto-layout already used by /process). Adds one more step in the pipeline; document the dependency chain.

Glossary