Skip to content

Documentation Architecture

The repository uses Zensical for both user-facing documentation and linked maintainer notes.

Layout

  • zensical.toml is the site configuration.
  • docs/ is the Markdown source directory.
  • site/ is the generated static output directory and remains ignored by git.
  • The explicit nav in zensical.toml lists user-facing sections and one maintainer-notes entry point.
  • docs/AI/README.md indexes every durable technical note by owning subsystem; individual notes stay out of the top-level navigation.

Content Split

Use the main docs for:

  • conceptual explanations,
  • setup and notebook workflows,
  • supported environments and algorithms,
  • curated API references generated from Python docstrings,
  • glossary and troubleshooting.

Main docs must describe executable commands and current artifact/configuration contracts. Prefer repository-relative paths in examples; cluster aliases that exist only on one machine should be called out explicitly.

Use docs/AI/ for:

  • implementation details,
  • design rationale,
  • migration notes,
  • known edge cases,
  • alternatives considered.

Do not expand docs/Overview.md with technical depth. It is now a compatibility pointer into the richer docs tree.

Commands

Preview locally:

uv run zensical serve

Build strictly:

uv run zensical build --strict

Zensical is a dev dependency in pyproject.toml, so use uv run rather than relying on a globally installed executable.

mkdocstrings-python is also a dev dependency. Zensical uses it to render the curated API pages under docs/reference/api/.

Update Rules

When changing a user-facing workflow, update the relevant docs/workflows/ page.

When changing a concept that users need to understand before running experiments, update docs/concepts/.

When adding or renaming a reusable public Python surface, update the matching API page under docs/reference/api/. Prefer explicit module.symbol blocks for high-value symbols rather than documenting whole modules indiscriminately.

When changing implementation details that future agents or developers need, add or update an AI note and link to it from docs/AI/README.md.

Every AI note belongs in an owning subfolder such as architecture/, joint-graphs/, opponent-model/, shielding/, notebooks/, or operations/. Do not recreate a flat collection at the root.

Documentation-only changes should run both:

uv run python scripts/run_tests.py changed
uv run zensical build --strict