Documentation style

Guidelines for Castellan book pages.

Voice

Honest scope — say what Castellan is not early
Operator-first — copy-paste commands that produce visible artifacts
No placeholder social proof
Lexicon: organism + coordination field (genome, vitals, immune, stigmergy, pressure, blackboard, mux panes, dashboard). No animal pack metaphors (herd/flock/rookery) and no feudal/military castle-staff metaphors in body copy. Canonical table: Conventions.
CLI names: keep castellan herd / swarm-demo as commands; describe them as mux UX / multi-pane demos in prose
Peer names: no “like X / parity with Y” framing on operator pages; landscape peers stay in Frontier + COMPETITIVE_MATRIX / VENDOR
Structure: What → Why → How → Failure paths → Next; cross-link instead of repeating essays

One H1 per page (mdbook enforces)
Use > **Note** / > **Warning** admonitions
Mermaid diagrams: use classDef + semantic classes (runtime, substrate, evolve, gate) — see Design system
No inline style fill:#... (breaks dark mode)
Max 3 columns in comparison tables

Hero line (keep in sync with DESIGN.md): Pressure wakes agents — multiplexer, dashboard, and episode flywheel in one binary.

See Design system for the full token reference, typography scale, layout, components, and Mermaid rules.

Quick palette (defined in book/theme/css/custom.css):

--castellan-coordination — teal links and active nav
--castellan-evolve — amber evolution accents
--castellan-runtime / --castellan-substrate / --castellan-gate — diagram roles

Single source: docs/harness-manifest.toml drives docs/HARNESS_FEATURES.md and the landscape table in docs/COMPETITIVE_MATRIX.md.
Update workflow: edit the manifest, then cargo run -p harness-docs -- generate.
CI: ./scripts/check-harness-doc-parity.sh (via verify.sh smoke-docs) fails on drift.