Skip to content

The front door leads somewhere: @protect before the inventory, and a starter that is not v0.1 - #105

Merged
arpanghoshal merged 1 commit into
mainfrom
docs/front-door
Sep 6, 2026
Merged

arpanghoshal merged 1 commit into
mainfrom
docs/front-door

Conversation

@arpanghoshal

Copy link
Copy Markdown
Member

What a stranger saw

The docs home: hero → install → demo transcript → 26 capability cards → table → status → a "start here" row led by Run it in production. No @protect on the page. The quickstart said sixty seconds, took ten minutes, and had no pip install. ctrlrun init wrote a v1 file headed "(v0.1)" with "allow_with_log arrives later" in a comment. The README put New in 0.6 above the first usable line of code. All of it asked the reader to take the proof before being shown the thing.

What changes

  • Home (docs/index.mdx): two cards beside the install line, then one policy and one decorated function (both runnable), then the six-row table of what that function does at €100 / €2,000 / €5,000-on-a-€2,000-approval / €20,000 / lost reply / second worker. Cookbook gets a card. Run it for real moves down a row.
  • Grid: six guarantee cards visible, the other twenty in one <Accordion>. Done in render_capabilities.py::_render_mdx, so the drift test still binds all three renders to capabilities.yaml. Mutation: flattening the split fails test_the_generated_copies_match_the_generator.
  • "One effect, once" now reads happens at most once — the hero's own phrase — instead of executes once, which the limitations section contradicted. CLAIMS row updated; the name stays (it is an issue-template value).
  • Quickstart: retitled Protect your first action, prerequisites line with pip install ctrlrun, cookbook in Next. Every "60-second" reference updated.
  • ctrlrun init writes a v2 starter with effect: on the refund and the namespace delete — the same templates the README decorator uses. Same actions, same decisions; test_the_shipped_example_policy_* both pass unchanged. ctrlrun verify against the starter now exercises G3–G5 instead of reporting them N/A. T100 split into the starter row and the v1 row (examples/policies/payments.yaml).
  • Policy reference: the version rule, stated once — declare the lowest schema that has every key you use.
  • README: Protect your first action before The problem; New in 0.6Beyond one process under Running it in production; the eight-action policy and both verify transcripts in <details>; the decorator block gains the else: that fails if the delete ran without a human. docs/CLAIMS.md mirrors the order and gains a section; line numbers repointed.
  • Sidebar: cookbook nested into the eight groups its index already used; operator's Postgres page placed beside the decision page. Each recipe and the index gain a Run it block for the extracted examples/cookbook/<name>/ directory.
  • CHANGELOG: one Changed bullet (init) and one Documentation bullet.

Not done here, on purpose

The interactive /try-it playground is the next PR; this one only makes the existing demo a visible CTA. docs/postgres.md was going to be merged into production/postgres.mdx and is not: they are two pages (choose / operate), and test_release_v0_6 requires the long one by name, so the fix is placement, not deletion.

Checks

  • Full suite under .venv: 4112 passed, 45 skipped.
  • snippets.py (13 runnable blocks in the four edited documents; the whole-docs snippet test in the suite), lint.py 0 findings, links.py 0 broken, every render_*.py --check clean.
  • ruff check, ruff format --check, mypy --strict src/ clean.
  • Touches src/ctrlrun/cli/main.py (the starter text only) — merge waits for the maintainer.

…starter that is not v0.1

The docs home showed a hero, an install line, the demo transcript, twenty-six capability
cards, a table, a status block, and a "start here" row led by *Run it in production* — and
never the decorator. The quickstart said sixty seconds, took ten minutes, and did not say
`pip install`. `ctrlrun init` wrote a v1 file headed "(v0.1)" with a comment about a feature
that "arrives later", six releases on. The README put *New in 0.6* above the first line of
code a reader could use. None of that was wrong; all of it asked a stranger to read the
proof before being shown the thing.

- Home: two cards beside the install line (the browser demo, the first action), then one
  policy and one decorated function that run offline, then a six-row table of what the same
  function does at €100, €2,000, €5,000 on a €2,000 approval, €20,000, a lost reply, and a
  second worker. The cookbook gets a card; *Run it for real* moves to the second row.
- The grid: the six guarantees as cards, the other twenty in one accordion. Done in the
  generator, so the drift test still holds all three renders to the YAML, and a flattening
  mutation fails `test_the_generated_copies_match_the_generator`.
- *One effect, once* reads "happens at most once", the hero's phrase, instead of "executes
  once", which the limitations section had been contradicting two screens down.
- Quickstart: titled *Protect your first action*, a prerequisites line, a cookbook link.
  Every page that called it "60-second" updated.
- `ctrlrun init` writes a v2 starter with `effect:` on the refund and the namespace delete —
  the same templates the README decorator uses, so the two agree. Same actions, same
  decisions. T100 splits: the starter now exercises G3–G5, and the v1 template under
  `examples/policies/` keeps the no-templates row.
- Policy reference: the version rule, stated once — declare the lowest schema that has every
  key you use.
- README: *Protect your first action* before *The problem*; *New in 0.6* becomes *Beyond one
  process* under *Running it in production*; the eight-action policy and both verify
  transcripts collapse into `<details>`. The decorator block gains the `else:` that fails if
  the delete ran without a human. CLAIMS.md mirrors the new order and gains the section.
- Sidebar: the cookbook nested into the eight groups its index already used; the operator's
  Postgres page placed beside the decision page instead of after Operations. Each recipe and
  the index say how to run the extracted directory.

Full suite 4112 passed; snippets, lint, links and every generator check green.
@arpanghoshal
arpanghoshal merged commit cc3a21c into main Sep 6, 2026
11 checks passed
@arpanghoshal
arpanghoshal deleted the docs/front-door branch September 6, 2026 22:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant