# Documentation Workflow

The published documentation is organized as a system manual first. The top of
`docs/SUMMARY.md` should lead with pages that explain how to understand, build,
boot, configure, operate, and review the current capOS implementation.

The mdBook site may keep the wider project corpus reachable for maintainers:
roadmap, changelog, backlog, proposal, paper, and research files can remain
under the lower archive section. Those pages should not shape the primary
reader path, and they should not be treated as part of the generated PDF
manual unless they become current system documentation.

## PDF Manual Pipeline

The PDF is a Typst-authored manual shell plus generated body content:

1. `tools/docs-bundle.js` reads `docs/SUMMARY.md`, selects only manual
   sections, rewrites bundled-doc links to PDF-local heading anchors, and
   emits ignored Markdown at `docs/capos-docs.md`.
2. `mdbook-mermaid` checks Mermaid syntax, and `mermaid-cli` converts Mermaid
   blocks in the generated Markdown to PNG artifacts under `target/docs-bundle/`.
3. `uv tool run --constraints tools/md2typst-constraints.txt --from
   md2typst==0.3.3 md2typst` converts the generated Markdown body to Typst
   with the converter dependency set pinned.
4. `tools/build-typst-manual.js` normalizes the converted body, fills
   `docs/manual.typ` with the generated version/date/source metadata, and
   writes `target/docs-bundle/capos-docs.pdf.typ`. The normalizer also
   collapses Markdown source-wrap line breaks outside code blocks so PDF prose
   and list items use normal paragraph layout.
5. The pinned Typst binary compiles the final PDF.

`docs/manual.typ` owns the PDF document structure: title page, version block,
one-level table of contents, page setup, and base typography. Generated files
under `docs/capos-docs.md`, `target/docs-bundle/`, and `target/docs-site/`
must remain untracked.

## Scope Rules

The PDF manual includes current system documentation: introduction, status,
build and boot workflow, configuration, repository map, runnable demos,
architecture, and security/verification pages.

Project archives stay on the mdBook site but are excluded from the PDF manual:
proposals, backlogs, research notes, whitepaper planning, and other planning
records are useful context for maintainers, not the operator-facing manual.