Maintenance

Notes for maintainers working in this repository. Consumers need only the project README at the repository root.

Repository layout

  • documentation/ — Sphinx site sources (Markdown with MyST).

Building the documentation

Prerequisites: uv and the Sphinx dependencies (sphinx, furo, myst-parser, sphinx-copybutton, sphinx-inline-tabs).

Build HTML into the ignored scratch directory (never commit build output):

uv run --with sphinx --with furo --with myst-parser \
    --with sphinx-copybutton --with sphinx-inline-tabs \
    sphinx-build -b html documentation .auxiliary/temporary/sphinx-build

The build must complete with zero warnings.

Workflow

  • Design discussion goes through OpenSpec changes; implementation is gated behind Tier-1/Tier-2 review plus operator approval — see .auxiliary/agents/procedures/.

  • Use --fixup commits for review feedback, held unsquashed until final approval, then autosquashed. See the delegated review procedure.

  • Coordination notes live in the documentation-common notebook.

  • This repository is not a Copier template consumer: never run copier update here.