craft-doc-publish
Publish Markdown with frontmatter as a templated DOCX and PDF with ArtCraft apps - fill the company template, inline images and Mermaid, WordCraft body and TOC, optional PdfCraft package/protect; veri
SKILL.mdpackages/craft-apps/.pi/skills/craft-doc-publish/SKILL.md
GitHubcraft-doc-publish — Markdown + template → DOCX + PDF (→ packaged PDF)
The default Markdown → templated DOCX/PDF path. pi-craft doc prepare fills the template's placeholders (frontmatter,
--var, template defaults, system variables) and prepares the body; WordCraft then only appends the body, builds the TOC and
exports; PdfCraft packages the result. No Docker, no pandoc. Read wordcraft (and pdfcraft for step 3) first. Resumable-job
rules are in the craft-studio router, section Craft jobs. Ingest/OCR of existing documents, round-trip editing
(extract → edit → merge back), PlantUML and table-width profiles stay with document-converter.
Step table
| # | Step | Tool | Input → Output | Gate |
|---|---|---|---|---|
| 0 | Preflight + job | agent | request → job.json |
check: job |
| 1 | Prepare | pi-craft doc prepare |
report.md + template → 01-prepare/ (template.filled.docx, body.md, prepare.json) |
check: prepare (+ user confirms defaults) |
| 2 | Render | WordCraft | filled template + body → 02-render/out.docx, out.pdf |
pi-craft verify --pages --text-contains |
| 3 | Package (optional) | PdfCraft | pdf (+ extra pdfs) → 03-package/final.pdf |
pi-craft verify (before protecting) |
Hand-off formats: filled docx + Markdown body between 1 and 2, pdf out (the docx is verified through its pdf). The
template is a doc-engine template directory <templates-dir>/<name>/template.docx (+ variables.xml, manifest.xml).
Passwords and API keys are never written to job.json, gate reports or step files.
Step 0 — Preflight and job
Output: craft-jobs/<slug>/job.json (created or loaded).
Gate: check: job.
| Sibling | Package | Check | If missing |
|---|---|---|---|
document-converter |
@blackbelt-technology/pi-dashboard-document-converter |
skill in the loaded skill list | not needed here: only for ingest/OCR, round-trip editing and PlantUML — route those requests to it, continue otherwise |
mmdc |
@mermaid-js/mermaid-cli |
command -v mmdc (it needs a Chromium; if it cannot find one set PUPPETEER_EXECUTABLE_PATH) |
diagrams stay code blocks; step 1's gate asks you to install it or accept code-block diagrams |
pi-nano-banana |
already a dependency of craft-apps | usable credentials, only when the frontmatter sets nano_banana.enabled: true |
no credentials: diagrams render with mmdc (the fallback runs anyway) |
"Loaded skill list" is the available-skills list in your own system prompt. nano_banana.enabled is a paid API call per
new diagram: state that to the user before step 1; results are cached in .mermaid-cache/ next to the Markdown.
Resolve the template first and echo its path to the user (it is in prepare.json after step 1): ./templates is searched
before ~/Documents/templates, so a repo-local template can win without being asked for.
Set up the job (Craft jobs in craft-studio: slug rule, job-helper) and run Resume.
# run from the directory that contains craft-jobs/ (SLUG set as in step 0)
jq -e '.name and .workflow and (.steps | type == "object")' "craft-jobs/$SLUG/job.json"
Step 1 — Prepare
Output: 01-prepare/template.filled.docx, 01-prepare/body.md, 01-prepare/prepare.json.
Gate: check: prepare — the report has no unresolved placeholder, unrendered diagram, skipped or remote image, and
every template-defaulted variable was confirmed by the user.
pi-craft doc prepare report.md --out "$JOB/01-prepare" [--template default] [--templates-dir <dir>] [--var client_name="ACME Kft."]… [--allow-path <dir>]…
Frontmatter uses the doc-engine keys: template, templates_dir, language, document_title, document_name,
enable_toc, toc_heading, nano_banana; every other scalar key is a template variable (--var wins over frontmatter,
which wins over the template's own variables.xml default). Read prepare.json:
defaulted— variables that still carry the template's default (a real template ships another customer's name, offer number…). Show each default value and ask the user to confirm or supply a value (--var name=value, rerun). Only then run the gate withDEFAULTS_CONFIRMED=1.unresolved— placeholders with no value (also a token split across paragraphs): supply the variable or, with the user's consent,--allow-missing.mermaid.unrendered— diagrams left as code (nommdc, no browser, render error): ask the user to installmmdcor accept code-block diagrams before rendering.images.skipped/images.remote— images outside the Markdown's directory (pass--allow-path), missing, or remote (WordCraft does not fetch them): fix the path or accept the omission with the user.warnings— PlantUML blocks stay code (usedocument-converter); a variable value that contained image/diagram syntax stays literal.pictures— present when the template owns images (WordCraft 0.7.0 would paste every Markdown-imported image onto the template's first one):body.mdthen carriesCRAFTIMG0001-style markers and step 2 puts the pictures in.
# run inside the step directory: cd "$JOB/01-prepare" (DEFAULTS_CONFIRMED=1 once the user confirmed every defaulted variable)
jq -e --arg ok "${DEFAULTS_CONFIRMED:-0}" '
(.unresolved | length == 0) and (.mermaid.unrendered == 0) and (.images.skipped | length == 0) and (.images.remote | length == 0)
and ((.defaulted | length == 0) or $ok == "1")' prepare.json
Step 2 — Render
Output: 02-render/out.docx and 02-render/out.pdf (the docx is verified through its pdf).
Gate: pi-craft verify out.pdf --pages N --text-contains "<title>" — N is WordCraft's own page count of the docx.
One WordCraft run opens the filled template with run --file (never run --template: it drops the template's header/footer
parts), appends the body after a page break, builds the TOC if enabled, puts in any pictures, sets the properties, then convert
exports the pdf. The TOC is inserted before the body: references.toc leaves the caret above the TOC, so move to the end
(caret.docEnd) again before the second page break and the body.
D="$PWD/$JOB/01-prepare"; TOC=$(jq -r .toc.enabled "$D/prepare.json")
ARGS=(--cmd 'caret.docEnd={}' --cmd 'text.pageBreak={}')
if [ "$TOC" = true ]; then
ARGS+=(--cmd "references.toc=$(jq -c '{levels:.toc.levels,title:.toc.heading}' "$D/prepare.json")" --cmd 'caret.docEnd={}' --cmd 'text.pageBreak={}')
fi
ARGS+=(--cmd "insert.textFromFile=$(jq -nc --arg p "$D/body.md" '{path:$p}')")
# pictures (only when prepare.json has them): find the marker, insert the picture, delete the marker
while IFS= read -r pic; do
m=$(jq -r .marker <<<"$pic"); f=$(jq -r .file <<<"$pic")
ARGS+=(--cmd "edit.find=$(jq -nc --arg t "$m" '{text:$t}')" --cmd "insert.picture=$(jq -nc --arg p "$D/$f" '{path:$p}')" --cmd "edit.replaceAll=$(jq -nc --arg t "$m" '{text:$t,with:""}')")
done < <(jq -c '.pictures[]?' "$D/prepare.json")
ARGS+=(--cmd "file.properties=$(jq -c '{title:.title}' "$D/prepare.json")")
[ "$TOC" = true ] && ARGS+=(--cmd 'references.updateToc={}')
pi-craft wordcraft exec run --file "$D/template.filled.docx" "${ARGS[@]}" --save "$JOB/02-render/out.docx"
pi-craft wordcraft exec convert "$JOB/02-render/out.docx" "$JOB/02-render/out.pdf"
N=$(pi-craft wordcraft exec info "$JOB/02-render/out.docx" | jq -r .pages)
TITLE=$(jq -r .title "$D/prepare.json")
CLIENT=${CLIENT:?set CLIENT to a variable value you supplied, e.g. the --var client_name value}
pi-craft verify "$JOB/02-render/out.pdf" --pages "$N" --text-contains "$TITLE" --text-contains "$CLIENT"
A page-count mismatch or a missing title stops the workflow here: the package step does not start. Look at the rendered pages
(pi-craft pdfcraft exec render out.pdf --page 1 --out <abs>.png, then read the image) before step 3 — the gate cannot see a
wrong picture or a broken cover.
Step 3 — Package (optional)
Output: 03-package/final.pdf (combined, audited, optionally password-protected).
Gate: pi-craft verify on the unprotected pdf (--pages = sum of the parts); a protected pdf cannot be probed, so the protect
step is checked by check: protected (opening without the password must fail).
pi-craft pdfcraft exec combine "$JOB/02-render/out.pdf" appendix.pdf --out "$JOB/03-package/final.pdf" # skip when there is nothing to add
pi-craft pdfcraft exec audit "$JOB/03-package/final.pdf" # faux-redaction finder, fails when found
pi-craft verify "$JOB/03-package/final.pdf" --pages 5 --text-contains "$(jq -r .title "$JOB/01-prepare/prepare.json")"
Protect only when asked. The password comes from the user at run time; it goes to a 0600 temp file outside the job directory
(argv would show it in the process list for the call; the temp file is deleted at once) and never into job.json, reports or
the job directory:
S=$(mktemp); chmod 600 "$S"
jq -nc --arg pw "$PASSWORD" --arg in "$JOB/03-package/final.pdf" --arg out "$JOB/03-package/final-protected.pdf" \
'[{tool:"doc_open",args:{path:$in}},{tool:"doc_protect",args:{doc:1,open_password:$pw}},{tool:"doc_save",args:{doc:1,path:$out}}]' > "$S"
pi-craft pdfcraft exec run --script "$S"; rm -f "$S"
# run from the directory that contains craft-jobs/: opening without the password must fail
! pi-craft pdfcraft exec info "craft-jobs/$SLUG/03-package/final-protected.pdf" >/dev/null 2>&1
Resume
Follow the Craft jobs convention in craft-studio: read craft-jobs/<slug>/job.json as data, confirm the job name, and start
at the first step with no passing report or whose recorded inputs (path, size, mtime) changed — an edited report.md, a new
template, an image. Re-run every step downstream of it (a changed report.md re-prepares, re-renders and re-packages) and reuse the
verified outputs before it. Record each step with the job-helper snippet after its gate passed; the prepare step's report is
the prepare.json summary (defaulted, unresolved, counts). A job stopped after step 2 verified resumes at step 3 with the
verified pdf. Never record a protect password.
When a gate fails
Stop at the failed gate; never continue past it. Re-discover the commands you used (pi-craft wordcraft exec commands --json | jq … — WordCraft has no describe; pi-craft pdfcraft exec tools for PdfCraft), repeat the step and re-run the gate. At most 2
retries per step; after the second failure stop and report the verify output and what was tried. pi-craft verify exit 3 means
a probe tool is missing (PdfCraft cannot be provisioned): stop and report the missing tool — never treat it as a pass. If
WordCraft itself cannot be provisioned, offer document-converter as the fallback renderer.
Recipes
# A WordCraft-made template -> doc prepare -> WordCraft render with TOC -> pdf gate. (The real company template is
# ~/Documents/templates/default; this one is built on the spot so the recipe needs nothing installed.)
mkdir -p templates/default 01-prepare 02-render
pi-craft wordcraft exec run --cmd para.heading1 --cmd 'text.insert={"text":"{{ client_name }}"}' \
--cmd text.newParagraph --cmd para.normal --cmd 'text.insert={"text":"Version {{ version }}"}' \
--save templates/default/template.docx
printf -- '---\ndocument_title: Quarterly Report\nclient_name: ACME Kft.\nversion: "2.0"\nenable_toc: true\ntoc_heading: Contents\n---\n# Quarterly Report\n\nHello {{ client_name }}.\n\n## Results\n\nRevenue grew by twelve percent.\n' > report.md
pi-craft doc prepare report.md --out 01-prepare --templates-dir templates
jq -e '(.unresolved|length==0) and (.mermaid.unrendered==0) and (.images.skipped|length==0) and (.images.remote|length==0) and (.defaulted|length==0)' 01-prepare/prepare.json
D="$PWD/01-prepare"; TOC=$(jq -r .toc.enabled "$D/prepare.json")
ARGS=(--cmd 'caret.docEnd={}' --cmd 'text.pageBreak={}')
if [ "$TOC" = true ]; then
ARGS+=(--cmd "references.toc=$(jq -c '{levels:.toc.levels,title:.toc.heading}' "$D/prepare.json")" --cmd 'caret.docEnd={}' --cmd 'text.pageBreak={}')
fi
ARGS+=(--cmd "insert.textFromFile=$(jq -nc --arg p "$D/body.md" '{path:$p}')")
ARGS+=(--cmd "file.properties=$(jq -c '{title:.title}' "$D/prepare.json")")
[ "$TOC" = true ] && ARGS+=(--cmd 'references.updateToc={}')
pi-craft wordcraft exec run --file "$D/template.filled.docx" "${ARGS[@]}" --save 02-render/out.docx
pi-craft wordcraft exec convert 02-render/out.docx 02-render/out.pdf
N=$(pi-craft wordcraft exec info 02-render/out.docx | jq -r .pages)
pi-craft verify 02-render/out.pdf --pages "$N" --text-contains "Quarterly Report" --text-contains "ACME Kft." --text-contains "Version 2.0"
# Package step: protect with a password from a 0600 temp file (never in the job directory), then prove the protection.
pi-craft wordcraft exec run --cmd 'text.insert={"text":"Confidential offer"}' --save src.docx
pi-craft wordcraft exec convert src.docx final.pdf
pi-craft verify final.pdf --pages 1 --text-contains "Confidential offer"
PASSWORD=${PASSWORD:-recipe-only-secret}
S=$(mktemp); chmod 600 "$S"
jq -nc --arg pw "$PASSWORD" --arg in "$PWD/final.pdf" --arg out "$PWD/final-protected.pdf" \
'[{tool:"doc_open",args:{path:$in}},{tool:"doc_protect",args:{doc:1,open_password:$pw}},{tool:"doc_save",args:{doc:1,path:$out}}]' > "$S"
pi-craft pdfcraft exec run --script "$S"; rm -f "$S"
! pi-craft pdfcraft exec info final-protected.pdf >/dev/null 2>&1
test -f final-protected.pdf
pi-craft verify final.pdf --pages 1