Docs 6: the launch audit

[arpanghoshal]

Session 6: read the site as a stranger, run the full audit, write the human steps down. Two halves — what a machine can check, and what only a first read finds.

The fresh read

A session that had not written any of it read the site the way a site is read, as a backend engineer with an agent that issues refunds and deploys services, and ran the commands. Thirty-odd findings. The three that would have cost the most trust:

• reference/cli.mdx said Usage: main fourteen times, under a sentence promising each block is the command's own --help verbatim. Click takes the program name from sys.argv[0]. A reader who tried it got command-not-found from the reference page.
• Two pages quoted ctrlrun verify transcripts that were written, not captured. Every PASS row named stripe.refund where the page's own policy makes verify exercise k8s.delete_namespace. That is the false-green problem this project warns about, in its own evidence.
• All 71 API reference pages had signatures that raise. The renderer dropped the * and every default, so protect('stripe.refund', 'refund:{id}') copied off the page is a TypeError. Protocols rendered with none of their members, and no page had an import line or named its extra.

Also fixed: a stray fence in ARCHITECTURE.md that rendered everything from the module map to the end of the file inside a code block on the live site, and hid 88 lines from the lint. Five pages claiming every call leaves a receipt, when a call waiting on a human has none. Site-wide canonical and og:url, making all 180 pages declare themselves duplicates of the home page.

And a long tail of statements that were wrong: the Slack answer body and signature format, python -m ctrlrun.conformance.store, ctrlrun inspect given an approval id, the exit-2 case, a read-only Postgres role running --verify-chain, PendingApproval's keys, Subject's rule, five reserved subjects where there are ten, a receipt's action field called name, deny/blocked, ten guarantees where there are eleven, 10/10 and 5/5 in the roadmap, 1,625 test functions where there are 1,704.

Three sentences that were not true yet

• The README said an unreleased version was on PyPI. The readiness block read "Version 0.6.0, on PyPI" off pyproject.toml while the changelog says ## [0.6.0] - unreleased and PyPI holds 0.5.0. It reads the changelog for the newest dated version now, and dating the entry flips all three copies on its own.
• Every share card pointed at the wrong domain, because og:image was relative.
• The home page shared as "CTRLRun - CTRLRun".

New guards, each mutation-tested

Guard	Catches
Rendered signatures against inspect.signature	a signature a reader cannot call
Quoted verify transcripts against a real run	a written transcript
A measured receipt count	"every call leaves a receipt"
A guarantee count against the catalogue	ten where there are eleven
The suite size as a floor	a page undercounting its own evidence
No site-wide canonical	every page claiming to be the home page
No description cut mid-clause	a truncated search snippet
Every API page names its import and extra	a reference nobody can use

The three docs audits stop being advisory

Runnable snippets, the forbidden-words lint and the link check carried continue-on-error: true from session 0, so a job red on arrival would not teach everyone to ignore it. The baseline is clear, so the flags are gone. Adding docs to the required status checks is a settings click and is on the checklist.

Checked and green

Generators with --check	9, none drifted
Public names with a reference page	62 of 62
Runnable snippets · forbidden words · links	96 blocks, 0 failed · 0 · 0
mint validate · mint broken-links	passed · none
Tags with a GitHub Release · badges	6 of 6 · 7 of 7
Community profile	100%

The new-user path, from a wheel built here into a fresh 3.12 virtualenv with no repository: pip install brings click and pyyaml and nothing else, ctrlrun init writes a policy, ctrlrun demo runs five scenarios in 0.12s with no network, receipts and verify work, and the quickstart's five runnable blocks pass against that install.

Left for a person

In internal/LAUNCH-CHECKLIST.md, which stays local. The social preview on the repository page is still the pre-branding grey image; docs is not yet a required status check; the MCP screenshot needs taking.

Not fixed, and listed rather than hidden

• ctrlrun init writes a ctrlrun.policy/v1 policy with no effect: key, so a reader who starts where the install page points gets no reservation and no one-effect-once — the guarantee the whole site is about. That is a src/ behaviour change and needs your word.
• Every Production page, the Postgres guide and eight capability cards describe 0.6, which is not on PyPI yet. They become true on the tag; the readiness block is the only place that currently says so.
• The adapters pin ctrlrun>=0.5,<0.6, so pip install ctrlrun-langgraph on 0.6 downgrades the kernel. No site page states a supported kernel range.
• Unanswered questions a reader has: what this costs per call, how to unit-test a @protected function, what happens to an abandoned approval request.

Verification

ruff format --check · ruff check · mypy --strict src · pytest
3908 passed, 45 skipped — all checks passed

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
ctrlrun	🟢 Ready	View Preview	Sep 6, 2026, 4:16 PM

💡 Tip: Enable Automations to automatically generate PRs for you.