Documentation style guide

Platform v3.0.0 Docs v3.0.0 ENFORCED BY CI (quality gate)

Voice and register

Plain, precise, scientific prose. Present tense for behaviour (“the kernel raises…”), past tense for measurements (“1,653 tests passed”); the machine-readable docs-last-reviewed meta records the verification date, not the body text.
No marketing superlatives and no decorative adjectives. The gate rejects a banned-vocabulary list (world-class · cutting-edge · best-in-class · state-of-the-art · revolutionary · unparalleled · game-changing · industry-leading · unprecedented · next-generation · ultimate solution · seamless · blazing-fast); the adjectives appear only beside measured numbers.
No hardware or performance claims without evidence. Timings are single-environment observations, stamped with date + environment, or omitted.
Uncertainty is stated, not smoothed over. If it was not run, say so.

Code citations use path/to/file.ts:123-456 rendered as ⌗ chips; the gate verifies every cited file exists and the line range fits the file.
Scientific citations reproduce the source exactly as the code names it (author-year, journal/doi:token, ISBN, or the code’s own NO-DOI flag). Do not invent, upgrade or “modernise” references; DOIs must be the ones in source.
Verbatim quotes from code comments/docstrings use the dashed quote block with a file:line footer; they are the authority for validity limits.
Unit conventions: SI on parameter tables; non-SI retained only where a published formulation requires it (Rothermel imperial constants; FAO mm/inch), always stated inline. Wire units are named explicitly (µm vs m, km/h vs m/s).


Label	Meaning	Rule
MEASURED — verified by execution	produced by executing the code in this repository	must be reproducible from the page’s own command block
Known limitation (D-n)	defect or bound found by verification	register entry on the methodology page + note on the affected page

Every capability page carries: equations with citations → parameter contract → outputs + units → spatial-origin semantics → verbatim validity limits → measured evidence table → reproduction → honesty callout.
Prose lives in Markdown (linked from each page’s header); HTML pages carry structured verified data and navigation — they never duplicate prose paragraphs.
Navigation, breadcrumbs, version + last-reviewed stamps are generated by scripts/docs/build.mjs — edit specs, rebuild, never hand-edit HTML.

Landmarks: header/nav/main/footer; skip-to-content link; aria-current on active navigation; breadcrumbs as an ordered list with aria-label.
Text/background contrast ≥ 4.5:1 in light and dark schemes (values annotated in assets/docs.css); status tags choose hues for non-colour redundancy (labels carry the meaning).
Tables use scope attributes; equations are Unicode text with plain-language captions (screen-reader readable, no canvas-only math); keyboard focus outlines on all interactive elements; prefers-reduced-motion honoured; print stylesheet collapses navigation.

Per page: unique title + description, canonical URL, OpenGraph/Twitter card, sitemap.xml + robots.txt, lastmod dates.
All internal links relative so the tree works from any base path (project pages or custom domain).
docs/.nojekyll pins byte-exact delivery of Markdown sources linked from pages.

Edit page specs in scripts/docs/ and prose in the Markdown files.
node scripts/docs/build.mjs regenerates the HTML.
node scripts/docs/quality-gate.mjs must pass (it is wired into CI).
When re-verifying: bump LAST_REVIEWED in site.mjs and refresh measured tables; new discrepancies go to the methodology log.