documate

• ArchitectureEvery subsystem on one page, in reading order.
• ReferenceAll 21 modules, grouped by directory.

Install

uv tool install documate     # or: pipx install documate  /  pip install documate

Everything runs on the standard library. The optional --ai mode is the only extra: it shells out to the claude CLI, so that needs to be on your PATH too.

First run

cd your-repo
documate --init    # write a config, index the code, generate docs/
documate           # regenerate or refresh docs/, then gate them

--init drops a small documate.config.json you can leave untouched. From then on, bare documate is the whole job: it re-indexes, writes docs/README.md (an overview with a dependency map, coverage, and hotspots), docs/ARCHITECTURE.md (the system on one page), and one page per module under docs/architecture/, then checks them.

The commands

• documate — index, write or refresh docs/, then gate it.
• documate --check — gate only, writes nothing; this is what CI and the pre-commit hook run.
• documate --watch — regenerate on every save while you work.
• documate --html — also render this static site into site/.
• documate --ai [MODEL] — draft missing docstrings with a model, then re-verify.
• documate --stats — show coverage, documentation lines, and any model spend.

Point it anywhere with documate path/to/repo, and see the full list with documate --help.

Keep the docs honest

documate --check exits non-zero when a generated page is stale, when a hand-written page points at code that no longer exists, or when a hand-written page describes code that changed but was not updated. Nothing to remember day to day — install the hook once and it regenerates and stages the pages on every commit:

git config core.hooksPath hooks

In CI, run documate --check with fetch-depth: 0 on the checkout step, so the history the overview's hotspots and evidence are mined from is fully available.

• How documate keeps these docs honestEverything under docs/architecture/ (plus the overview and ARCHITECTURE.md, the one-page stitch of every subsystem) is generated: documate reads the code graph…

• coverage_report.pycoverage_report.py — render coverage.py JSON as a colored per-file table.
• scan_hygiene.shHygiene gate for the built site: refuse to publish pages that leak local
• scan_pii.shPersonal-info deny-list scan. The patterns arrive via $PII_PATTERNS (one

• __init__.pydocumate — generate docs from your code and keep them honest.
• anchors.pyanchors.py — scan authored docs for documents: anchors and validate them.
• briefs.pybriefs.py — O(diff) work orders for a prose-writing model (or a human).
• check.pycheck.py — documate --check: the one gate. Are the docs fresh, real, and honest?
• cli.pycli.py — one command. Bare documate does the whole job; flags pick a mode.
• config.pyconfig.py — everything project-specific about the repo documate is pointed at.
• core.pycore.py — the per-invocation Context: root + config + graph adapter.
• docs.pydocs.py — documate: generate the committed documentation from code.
• drift.pydrift.py — flag docs that describe code which just changed.
• extract.pyextract.py — pull the prose out of source, per language.
• graphdb.pygraphdb.py — documate's only door to the code graph.
• prose.pyprose.py — the opt-in model layer: drive Claude over the work orders.
• resolve.pyresolve.py — turn a doc anchor into the concrete code it names, or fail loudly.
• rewrap.pyrewrap.py — reflow doc comments already in the source to doc_width.
• site.pysite.py — documate --html: the same docs, rendered as a static site.
• stats.pystats.py — documate --stats: the documentation dashboard.
• ui.pyui.py — one voice for everything documate says.
• undo.pyundo.py — the --ai run manifest, and documate --undo to revert it.