Bug Scenario

Given the /pdf skill ships with a convert.sh dispatch helper that runs md-to-pdf (npm package) when pandoc is not installed
When an operator invokes /pdf <markdown-file> on a system without pandoc but with Node available
Then convert.sh calls md-to-pdf --pdf-output-folder <dir> ... and md-to-pdf errors out with ArgError: unknown or unexpected option: --pdf-output-folder
Expected the conversion succeeds and writes the PDF at the requested path

Repro Steps

On a system with no pandoc but npx md-to-pdf available (current upstream Node 26 default install):

# A real-world repro from this session: convert the geo-audit report
.claude/skills/pdf/convert.sh \
  --from=/path/to/report.md \
  --to=/path/to/report.pdf

Output:

convert.sh: input=markdown  converter=md-to-pdf  out=/path/to/report.pdf
ArgError: unknown or unexpected option: --pdf-output-folder
    at arg (/Users/<u>/.npm/_npx/.../node_modules/arg/index.js:132:13)
    at Object.<anonymous> (/Users/<u>/.npm/_npx/.../node_modules/md-to-pdf/dist/cli.js:25:38)
    ...
convert.sh: md-to-pdf conversion failed for /path/to/report.md

Manual workaround (succeeds): cd <dir>; npx md-to-pdf <file>.md — md-to-pdf defaults to writing <file>.pdf next to the source.

Environment

• Framework: apexyard v2.0.2 (any tagged version that ships the current convert.sh)
• Node: v26.0.0
• md-to-pdf: current npm latest (the version npx --yes resolves)
• pandoc: not installed (the dispatch path that fails)

Severity

P2 — /pdf is not on the release-blocking path; markdown-only inputs degrade to "operator runs npx md-to-pdf by hand". Hits any adopter who tries /pdf without pandoc preinstalled (common — pandoc adds LaTeX-related deps that adopters typically defer). The flag in question (--pdf-output-folder) was a real md-to-pdf flag at some point; current md-to-pdf uses different flags for output path. The fix is one line in convert.sh.

Mitigation

Two short-term workarounds for affected adopters:

1. Install pandoc — brew install pandoc on macOS, apt-get install pandoc on Debian/Ubuntu; convert.sh prefers pandoc when present and uses different (current) flags for it.
2. Run md-to-pdf by hand — cd $(dirname <file>) && npx --yes md-to-pdf <file>.md writes <file>.pdf next to source.

Investigation Notes

convert.sh lives at .claude/skills/pdf/convert.sh. The failing path is the md-to-pdf branch (look for --pdf-output-folder). Current md-to-pdf CLI uses:

• --basedir <dir> for relative-path resolution
• --config-file <yaml> for output destination + styling
• output path is controlled by passing the source file with the desired name; md-to-pdf writes <source-basename>.pdf in the same directory by default

The fix likely changes the dispatch from md-to-pdf --pdf-output-folder <dir> <file> to something like: stage the source file in a temp dir, run npx md-to-pdf <tmp>/<file>.md, then mv <tmp>/<file>.pdf <out>. Worth checking the latest md-to-pdf docs before deciding — there may be a --output or -o flag in newer versions.

Should also add a test case in .claude/skills/pdf/tests/ that runs an end-to-end conversion on a sample fixture, so this kind of regression is caught at PR time rather than at adopter-invocation time. The test can pin a specific md-to-pdf version to insulate against upstream API changes.

Glossary