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.

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. Add a short docs/AI/ note if the change captures durable technical design.

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