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. docs/manual.typ explicitly lists the Markdown pages that belong in the generated manual with {{CAPOS_MANUAL_PAGE:...}} placeholders. The mdBook site navigation in docs/SUMMARY.md can point at a different landing page or archive structure without changing the PDF contents.
2. tools/docs-bundle.js reads that explicit page list, rewrites bundled-doc links to PDF-local heading anchors, emits the aggregate generated Markdown at target/docs-bundle/manual.md, and emits one Markdown file per manual page under target/docs-bundle/.
3. mdbook-mermaid checks Mermaid syntax, and mermaid-cli converts Mermaid blocks in the generated Markdown to 2x PNG artifacts under target/docs-bundle/.
4. uv tool run --constraints tools/md2typst-constraints.txt --from md2typst==0.3.3 md2typst converts each generated Markdown page to Typst with the converter dependency set pinned.
5. tools/build-typst-manual.js normalizes the converted pages, fills docs/manual.typ with generated version/date/source metadata and the selected page include paths, and writes target/docs-bundle/manual.pdf.typ. The normalizer also collapses Markdown source-wrap line breaks outside code blocks so PDF prose and list items use normal paragraph layout, demotes generated page headings so manual parts remain the only top-level outline entries, and scales selected tall Mermaid diagrams so they fit with their surrounding manual context instead of becoming orphaned figure pages.
6. The pinned Typst binary compiles the final PDF.

docs/manual.typ owns the PDF document structure: title page, version block, table of contents, page setup, base typography, and the explicit manual page order. Manual part dividers are top-level headings; generated page titles are demoted during PDF normalization so chapters sit below those parts instead of appearing as peers.

Most manual pages are generated from Markdown through md2typst. A page can be overridden for the PDF only by adding a checked-in Typst file at docs/manual-overrides/<page-id>.typ, where <page-id> is the source path with non-alphanumeric characters collapsed to hyphens, for example docs/manual-overrides/architecture-memory.typ. Overrides replace the generated Typst page in the PDF but do not change the mdBook page or target/docs-bundle/manual.md. Override files are copied into target/docs-bundle/ before Typst compilation and should be self-contained Typst fragments.

Benchmark result tables stay in their source Markdown pages. If a wide benchmark table needs PDF-specific layout, mark that Markdown table with <!-- capos-benchmark-results:<id> start --> and matching end comments. The mdBook site renders the source table, while tools/build-typst-manual.js parses the marked table and replaces only that table region with a compact Typst rendering. Keep interpretation, caveats, and conclusions in normal prose around the table rather than encoding them in the table parser.

Generated files under docs/topics.md, target/docs-bundle/, and target/docs-site/ must remain untracked.

The mdBook metadata preprocessor and PDF bundler normalize default cross-document link labels. When a link label is only the target Markdown path or filename, rendered site and manual output use the target document title instead. Keep explicit prose labels in source when the surrounding sentence needs a more specific phrase than the document title.

PDF Typography Rules

The manual and the schema paper should share a conservative typographic base: letter paper, readable serif body text, a restrained heading scale, consistent link color, consistent code styling, and predictable figure/table captions. They do not need identical layouts. The paper can remain citation-oriented and formal; the manual should favor scanning, command lookup, and dense technical reference pages.

For the manual PDF:

• Keep body text readable before optimizing page count. Avoid global spacing changes that create worse page breaks or orphaned callouts.
• Use headings as navigation markers: leave more room before a heading than after it, and keep headings with the first paragraph or code block whenever practical. In the manual PDF, the below-heading gap must be visibly larger than ordinary line leading, while the above-heading gap remains larger than the below gap so the heading belongs to the content that follows.
• Treat long bullets as structure problems. Prefer short bullets, definition lists, or command/proof tables over paragraph-length list items.
• Use framed code blocks for commands and transcripts. Give them visible internal padding, a very light background, and enough surrounding whitespace to read as intentional panels.
• Keep inline code sparse in prose. When a sentence accumulates several commands, paths, or target names, prefer a code block or table.
• Use one callout style consistently. A left rule or light box is acceptable, but the callout needs enough padding that it does not look like accidental indentation.
• Avoid visual changes without checking rendered pages. Review at least one command-heavy page and one dense prose/list page after each PDF style change.

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.