Rendering outputs
Markdown, an HTML site, one self-contained page, the agent index and llms.txt — all deterministic, all free to re-run.
handbook render --work <workdir> [--title <t>] [--html] [--html-single] [--agent-site] [--llms-txt]No LLM. No network. Deterministic. Same model in, byte-identical files out — so this belongs in CI, on every commit.
The five outputs
Always written.
<out>/
overview.md system prose + a mermaid stage map + "see also" links
index.md every stage, nested by depth, a paragraph each
<stage-id>.md one page per content-bearing stage
register.md the cross-stage state table (only when registers exist)A stage page carries the stage summary, links to sub-stages, then its files — grouped and ordered as phase 2c decided, each rendered as a file card: purpose, role, lifecycle, call facts, and per-function notes for deep cards.
Two behaviours worth knowing:
- Stale pages are cleaned up. Stage ids change between generations; each render removes the previous render's pages first, so a renamed stage leaves no ghost page for the skill packager to scoop up.
- The per-stage register section is idempotent — appended under a marker, only when the marker is absent. Re-rendering never stacks duplicates.
Linking to your source
handbook render --work $WORK --source-base-url https://github.com/me/repo/blob/mainEvery file path in the handbook becomes a link to the real file. Point it at a tag or a
commit SHA instead of main if you want the handbook to reference the code it was
generated from.
Without this flag the output contains no external URLs at all, which is the right default for a private codebase.
Titles and languages
handbook render --work $WORK --title "Payments Service — Engineering Handbook"The narration language is fixed at generation time (--narrate-lang) and stored in
phase3/narration.json. The renderer reads it from there — every label, heading and table
header is localized to match. The structure is identical in both languages, so tooling
that reads the output does not need to know which one it is.
Re-rendering as a habit
Rendering is free and deterministic, so wire it into CI:
- run: handbook render --work work/api --title "API Handbook" --html --agent-site --llms-txt
- run: handbook skill --handbook work/api/handbook --out skills/api --name api \
--work work/api --source . --agent-dir work/api/handbook/agent
- run: handbook validate --skill skills/api --source .See CI integration.
Publishing the HTML site
The output is a static directory with relative links and no external assets, so any static host works:
# GitHub Pages
cp -R work/api/handbook/html/* docs-site/ && git add docs-site
# Netlify / Vercel / S3 / nginx
npx serve work/api/handbook/htmlServe llms.txt at the site root so agents can find it.