README: lead with the homepage's pitch, and record the README's own three steps

[arpanghoshal]

What this does

The README says what the homepage says. ctrlrun.dev leads with CTRLRun stops AI agents from taking wrong, restricted, or malicious actions in your workflows and the README led with Execution safety for AI agents; a stranger arriving from one met a second pitch. The header now opens with the homepage's H1 and lede verbatim, the first section carries its extra-zero example (without / with CTRLRun), Three ways to use it carries its line about agents you can and can't modify, How it works walks the seven steps of its diagram in the same order (normalize, decide, approve, reserve, execute, resolve, record) with its three refusals. Nothing commercial crosses over: no tiers, no early-access or engagement links, no slogan. Every documentation link goes to https://docs.ctrlrun.dev/, which serves each page under ctrlrun.dev/docs at the same path; the three badges that point at pages are regenerated from the docs repository's generator. tests/test_readme_assets.py pins the strings here, and the ctrlrun-docs branch of the same name reads them out of index.mdx, so a drift on either side fails CI on the other.

The animation is now the README's own three steps. It was ctrlrun demo's first two scenarios piped through sed and a pacing loop: a true recording, and one a stranger could not read (two pipes in the command line, no code, a transcript in the library's own vocabulary). It is now a recording of the Use it in three steps section against the real library: the policy file, python agent.py (€500 runs, €5,000 stops and names the request), ctrlrun approve (the grant names the action hash), python approved.py (€5,000 with the approval runs, €9,000 on that same approval is refused, one call reached the provider). 65 columns at 20px instead of 120 at 17px, so it is legible at the width GitHub renders it. 25 seconds, 222 KB.

What keeps it honest. docs/assets/recording/ holds the three files, asserted byte for byte equal to the README's runnable blocks; the tape copies them into an empty directory off screen and types every command that produces output on screen; demo.expected.txt holds the lines the recording ends on, and the test runs the same three files and asserts each is printed and each is quoted by the README. Both programs sys.exit on the path where the refusal did not happen, so a recording of a broken build fails instead of looking fine.

Other README changes. The quick start moves from IAM back to a refund so that README, animation, homepage and quickstart tell one story; #122's multi-domain point is kept by the sentence after it and the nine-domain table (unchanged, still parsed by test_examples.py). How it works gains a paragraph on budgets, scope and tasks, which 0.9 shipped and the README did not mention. The demo transcript block, the capability matrix and the badge row are untouched. No em dashes in anything new.

Pairs with

CTRLRun/ctrlrun-docs #21: tests/test_home_and_readme_agree.py, which reads the homepage's sentences out of index.mdx and asserts this README carries them. Merge this PR first, then re-run and merge the docs PR: the docs CI checks out kernel main, so that test is red there until this lands. Nothing in this PR depends on the docs PR; the header test keeps its old name so CLAIMS.md's citation stays valid.

Checks run locally

• ruff check . and ruff format --check . clean. The recording files are linted too, with one scoped I001 ignore for the sibling import, explained in pyproject.toml.
• tests/test_readme_assets.py, test_demo.py, test_packaging.py, test_examples.py, test_repository_signals.py, test_scan.py, test_verify_*.py, test_preconditions.py, test_release_v0_6.py, test_framework_probe.py, test_fuzzing.py: 787 passed.
• ctrlrun-docs against this branch: lint 0 findings, links 0 broken, README snippets 4 blocks 0 failed, test_release_documents, test_docs_audit, test_home_and_readme_agree green.
• The docs job checks out ctrlrun-docs main and may show test_the_claims_table_line_numbers_point_at_what_they_name, the readiness count (24 vs 27 guarantees) and the OWASP rows for G25 to G27 red. Those fail against main today as well: v0.10 items merged into the kernel ahead of their docs pages. Not from this PR.

🤖 Generated with Claude Code

[coderabbitai]

Warning

Review limit reached

Next included review available in 29 seconds.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: 2e6b8303-40bf-4884-8479-cbbbc4730b5a

📥 Commits

Reviewing files that changed from the base of the PR and between 6156b07 and 4858d40.

⛔ Files ignored due to path filters (1)

• docs/assets/demo.gif is excluded by !**/*.gif

📒 Files selected for processing (9)

• MANIFEST.in
• README.md
• docs/assets/demo.expected.txt
• docs/assets/demo.tape
• docs/assets/recording/agent.py
• docs/assets/recording/approved.py
• docs/assets/recording/ctrlrun.yaml
• pyproject.toml
• tests/test_readme_assets.py

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}