The pre-0.6 documentation pass: PyPI links, two shipped commands, and the two-host claim

[arpanghoshal]

Documentation only — nothing under src/. Five things that would each have been wrong at the tag.

1. The README is the PyPI page, and it would have rendered broken

pyproject.toml sets readme = "README.md", and PyPI resolves relative URLs against pypi.org/project/ctrlrun/. v0.5.0's README linked absolutely and carried no images. The rewrite that gave it a wordmark, a demo GIF and 23 relative links was green on every check this repository has, because all of them are correct on GitHub — so publishing 0.6.0 would have shipped a broken hero image, a broken demo GIF and 23 links that 404.

Every link and asset is absolute now, and test_the_readme_carries_no_relative_link_and_no_relative_image refuses a new one, with a positive control beside it. It costs no link coverage: links.py already resolves github.com/CTRLRun/ctrlrun/blob/<ref>/<path> against the checkout, so a dead target still fails there. Verified: links.py README.md → 0 broken.

2. ctrlrun scan had no changelog entry at all

It merged in #100, after the last changelog edit. It has one now, with ctrlrun mcp-operator, under "Shipped in this release, and not part of the v0.6 milestone" — a heading that keeps them out of the milestone's claims, because v0.6 says the surface did not grow and it did not; these grew it afterwards, each under its own specification. The separate top-level [Unreleased] section is folded in: two undated sections stacked above one release is not a changelog anybody can read at the tag. released() still parses to 0.5.0.

3. A docs page claimed what its own test denies

how-reservation-works.mdx cited T157/T158 for "one winner across two hosts". tests/test_cross_host.py opens with "They are not two hosts", and ROADMAP.md says the two-host case stays unclaimed. Both production pages now state what was actually run — separate OS processes against one Postgres, connection broken by a proxy the tests own — and that a network partition between machines is exercised by nothing here. postgres.mdx's table row no longer says "across hosts" as though it were measured.

4. The hero excluded the outcome the product is about

"Every consequential action happens once, exactly as approved, or not at all" is a two-way disjunction, and a lost reply is neither — it is AMBIGUOUS, which the next section of the same README calls the whole point. It now reads:

A consequential action happens at most once, exactly as approved, and leaves a receipt — and when the outcome is unknown, CTRLRun says so instead of guessing.

The category noun arrives with it: what CTRLRun is was on docs/index.mdx and in pyproject's description and nowhere in the README, so a reader had to infer it from three slogans.

5. Three shipped commands were invisible, and the release was unexplained

scan, mcp-operator and effects are in the CLI section now — scan with the sentence that matters: no score, no percentage, no badge. A "New in 0.6" section says what the durable-runtime release actually changed, which the README never did. And the "It can't" list now says CTRLRun does not detect prompt injection, beside a problem-table row that could be read as claiming it.

Kept in step

docs/index.mdx, docs/IA.md and docs/CLAIMS.md carry the same hero, so the site and the README do not drift; CLAIMS gains rows for the new section, both subcommands and the injection disclaimer. Its citation guard rejected four invented test names while this was written, which is the guard doing its job — the rows now cite what the table already cites for those claims. T180 caught the new "receipts are not signed" line and required it allow-listed with a reason, which it now is.

docs/BUILD-PROMPTS-docs-0.6.md is deliberately left alone: it is a record of prompts that were issued, not a live document.

Checks

• full suite: 4,111 passed, 45 skipped
• ruff check, ruff format --check, mypy --strict src/: clean
• links.py: 180 documents, 0 broken · lint.py: 186 documents, 0 findings
• readiness and soak renders: no drift
• src/ untouched

🤖 Generated with Claude Code

[mintlify]

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

Project	Status	Preview	Updated
ctrlrun	🟢 Ready	View Preview	Sep 6, 2026, 9:26 PM

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