Contributing to the docs¶

Contributing code

This page covers the documentation site. For code, start with CONTRIBUTING.md: the development setup, the gates CI runs, the engineering rules, adding a harness adapter or a benchmark skill, and pull request conventions. Report security problems privately, as described in SECURITY.md. Changes by release are in the changelog.

This site is built with MkDocs and Material for MkDocs from docs/user/. The configuration is mkdocs.yml at the repository root. No Node.js is involved.

Build and preview¶

uv sync --group docs                          # mkdocs-material and its dependencies
uv run python scripts/gen_docs.py             # regenerate every generated section
uv run --group docs mkdocs build --strict     # → site/  (fails on any warning)
uv run --group docs mkdocs serve              # live preview at http://127.0.0.1:8000

site/ is git-ignored. Material for MkDocs prints a notice about MkDocs 2.0 on every build. It is informational: Material pins mkdocs<2, so the build is unaffected. Set NO_MKDOCS_2_WARNING=1 to hide it.

What is generated¶

Some sections come from the code, so they can't drift from it. Each one carries a "Generated section" or "Generated copy" banner that names its generator. Don't edit them by hand: change the source and rerun scripts/gen_docs.py.

Output	Generator	Source
`cli.md`, "Every command"	`scripts/gen_cli_docs.py`	the Typer app in `ratchet/cli/`
`configuration.md`, "Every setting"	`scripts/gen_settings_docs.py`	`ratchet/config/settings.py` (field order, groups, descriptions)
`api.md`, "Endpoints" to the end, including "Error codes"	`scripts/gen_api_docs.py`	`schemas/openapi.json`; the registry in `docs/CONTRACTS.md` §8; the copy in `ratchet/copy_errors.py`
`reference/api-models.md`	`scripts/gen_api_docs.py`	`schemas/openapi.json`
`reference/adr/*.md` and the ADR index	`scripts/gen_docs.py`	`docs/adr/*.md`
`reference/verified.md`, `contracts.md`, `feedback.md`	`scripts/gen_docs.py`	`docs/VERIFIED.md`, `docs/CONTRACTS.md`, `FEEDBACK.md`
`img/*.png`	`scripts/gen_docs.py`	`docs/img/*.png`

In hand-written pages, generated regions sit between two HTML comments,  and . The prose outside them is yours to edit.

scripts/gen_docs.py --check writes nothing, and exits 1 when any generated file is stale.

CI¶

The docs job in .github/workflows/ci.yml runs on every pull request. It needs no keys and no Node:

uv sync --group docs
uv run python scripts/gen_docs.py --check
NO_MKDOCS_2_WARNING=1 uv run --group docs mkdocs build --strict

Every generator imports Ratchet modules or reads files only. scripts/gen_docs.py also sets RATCHET_UPSTREAM=sim and RATCHET_TAVILY_MODE=fixtures before it imports anything, so no model or Tavily call can happen.

Writing style¶

The docs use the product's voice:

Short, active sentences that name the thing. No hype, no exclamation marks, no emoji.
Costs always carry their tier: $0.04 (nano).
Quote the UI's own words when you describe it. They live in ratchet/copy.py and dashboard/src/copy.ts.
Say what is simulated, recorded or unverified, every time.
Chips in prose use the site's classes, so they look like the dashboard's: ✕ BLOCK, N, Simulated models.