Skip to content

Development Notes

This repository has two documentation audiences.

User-Facing Docs

User-facing docs live directly under docs/ and are served by Zensical. These pages should explain stable concepts, setup steps, workflows, benchmark choices, and how to interpret outputs.

Good user-facing topics include:

  • how to run notebooks,
  • what an environment objective means,
  • how to choose an algorithm,
  • where artifacts are written,
  • how to read verification reports.

Avoid burying essential usage information only in implementation notes.

Internal AI Notes

Durable implementation notes live under:

docs/AI/

These notes are maintained for future development work. They can be more detailed, more internal, and closer to current implementation choices than the public docs.

Use docs/AI/ for:

  • design decisions,
  • migration notes,
  • debugging records,
  • implementation invariants,
  • tradeoffs and alternatives,
  • notes that are useful to future agents or maintainers.

The notes are organized by owner:

docs/AI/algorithms/
docs/AI/environments/
docs/AI/experiments/
docs/AI/monitoring/
docs/AI/notebooks/
docs/AI/operations/
docs/AI/testing/
docs/AI/verification/
docs/AI/visualisation/

Use docs/AI/history/ only for dated migrations, audits, and removed surfaces. The maintained index is docs/AI/index.md.

When an internal note becomes broadly useful to users, summarize it in the user-facing docs and link to the code or notebook surface rather than exposing every implementation detail.

Docs Site Maintenance

The Zensical config is:

zensical.toml

The source docs are:

docs/

The generated site is:

site/

Local preview:

uv run zensical serve

Strict build:

uv run zensical build --strict

Do not commit generated site/ output.

Updating The Navigation

When adding a new user-facing page:

  1. Add the Markdown file under docs/.
  2. Add it to zensical.toml if it belongs in the main docs navigation.
  3. Run uv run zensical build --strict.
  4. Update the owning docs/AI/<topic>/ note if the change affects a durable technical contract.

When adding a stable user-facing Python entrypoint, also update the curated API Reference.

Test Suites

Use the repository test runner during development:

# Select routine tests from tracked and untracked working-tree changes.
uv run python scripts/run_tests.py changed

# Run every non-slow test or the complete suite.
uv run python scripts/run_tests.py fast
uv run python scripts/run_tests.py full

Focused suites are env, monitor, rl, verification, experiments, visualisation, and tooling. They exclude slow integration checks by default; add --include-slow when the relevant training or verification path changed. The maintained change-to-suite map and runtime policy are in docs/AI/testing/test-runtime.md.

Documentation-only changes select no pytest modules. They still require a strict Zensical build, which validates navigation, links, Markdown, and curated API imports.