Rebuild the homepage as a three-slide deck, and lead with the extra zero - #131
Merged
Conversation
The homepage embedded the full 48-domain ScenarioExplorer and also linked to /try, which renders the same component. The refund story's CTA said "in the demo" while pointing off-page, past the demo sitting below it. Drop the inline explorer. The try section becomes a compact card whose primary button is the refund deep link the failure story sets up (/try?domain=Payments&action=Refund payment&situation=uncertain), with a second link for picking your own domain and a third for the real wheel in the browser. Hero and footer "Try CTRLRun" now go to /try. Also tighten the how-it-works and integration copy, and add a direct contact link to the commercial section and the footer.
The page carried seven sections and said the same thing three times: a boundary strip (propose / check / act), a four-step how-it-works, and a try card that re-explained the demo the failure story had just set up. Follow the adopt.ctrlrun.dev deck, which says it in two moves. The boundary strip and the refund comparison collapse into one section: the same failure as two chains, without controls and with CTRLRun, ending at $1,000 and $500 once. The try CTAs move onto the end of that chain, where the reader already has the case in mind, so the standalone try card goes. The four how-it-works steps become the deck's three pillars — set limits, check actions, know what happened — with the deck's wording. Hero keeps one line, the deck's promise, instead of a lede plus an intro. Integration and commercial each lose a paragraph. Seven sections to five, 820 words to 555. CSS: drop .cr-boundary, .cr-boundary-node, .cr-control and .cr-try-card with their responsive rules, all now unused; add .cr-chain and .cr-pillar. The classes try.mdx shares — .cr-failure, .cr-comparison, .cr-how-steps, .cr-how-close, .cr-flow-arrow — stay.
The lost-response chain asks the reader to already hold a distributed-systems mental model: a call succeeded, its reply vanished, the retry double-pays. That is CTRLRun's most distinctive guarantee and its least legible one on a first visit. The chain now shows the failure people actually fear. The agent invents a $50,000 payout, the tool is in its list, and without controls the call goes through. With CTRLRun policy denies those arguments and the call never leaves the process. It is the demo's existing `blocked` scenario, so "Walk through this refusal" deep-links to the same refusal the chain describes, and the eyebrow is that scenario's own kernel line: the tool was in its list, that is not permission. The caption states the limit rather than letting the story imply more than it should. CTRLRun cannot tell that the agent made it up; it can tell the action is not one this agent may take. The AMBIGUOUS case is not dropped, only demoted: it stays as pillar 02's outcome checks, as `unknown outcome` in the outcomes list, and it is now named in the demo CTA alongside the edited approval and the duplicate.
The homepage chain changed story last commit; the README and the rest of the site still led with the lost reply. Three changes, in order of size. README: "The refund that happened twice" becomes "The refund nobody approved". It opens where a reader already is, an agent inventing a €50,000 payout that policy refuses, notes that an approval for €2,000 authorises nothing when €5,000 is executed, and only then turns to the half people do not expect, the correct €500 refund whose reply is lost. Both halves are what `ctrlrun demo` actually prints, and the recorded GIF shows both, so the narrative and the evidence still agree. The ambiguity guarantee is not softened anywhere it is documented: concepts, cookbook and the specs are untouched. Chain labels are symmetric now, "Without CTRLRun" and "With CTRLRun", on the homepage and in both decks. The section caption said what CTRLRun cannot do. It now says what it does: it checks the action rather than the reasoning, reads the arguments about to leave the process, and answers whether they may go. Em dashes are out of the site copy: index.mdx, try.mdx, docs.mdx and the two page snippets. The four left in docs.mdx are two lines of `ctrlrun demo` output a test asserts byte for byte, and two build comments that never render. tests/test_readme_assets.py pinned the old first-H2 title; it pins the new one. The assertion's point is that the README opens on a story rather than a feature table, and it still does.
The page was one continuous scroll. It is now three slides, one viewport each, grouped as: hero plus the failure chain; the demo CTA plus the three pillars; integration, commercial and the footer. Mechanics. The slides are plain markup in index.mdx inside a scroll-snap container, so with no JavaScript the page still reads, indexes, and snaps one slide at a time. snippets/deck-nav.jsx adds the position dots, the keyboard (arrows, page keys, space, Home, End) and the fit pass. It reads the theme's navbar height rather than assuming one, since the deck has to start below whatever chrome the docs theme renders. Fit is one scale for the whole deck, not one per slide. Scaling each slide against its own content puts neighbouring slides at different left edges, and arrowing between them reads as a mistake; a shared scale cannot drift. Slide 3 was the tall one, so its code block, outcome list and internal gaps came down until nothing needs scaling at all: at 1440x900 the shared scale is exactly 1 and all three slides start at the same x. No arrow buttons on screen. The dots are the only visible control, so they carry real labels and take focus rather than being decorative. Below 800px wide or 620px tall the deck is not the right shape, so it reverts to an ordinary scrolling page with the slides as sections and the dots hidden. Also: the navbar wordmark goes from 28px to 40px, 32px on small screens.
"The agent invents a $50,000 payout" never said what the right number was, so the reader had to take the wrongness on trust. The chain now shows the divergence: the ticket says refund $500, the agent asks for $5,000. One extra zero is the error people recognise, and it is the believable one -- two extra zeros reads as contrived, and a chain nobody believes stops working. End cells show the loss rather than the gross, so the two rows compare like for like: "$4,500 too much" against "$0 wrongly paid". Currency: ctrlrun.dev and adopt.ctrlrun.dev are dollars throughout. The automotive use case keeps its own scale, $8,000 asked as $80,000, because a dealer incentive is not a consumer refund; the shape is the same. The README stays in euros, and that is not an oversight. It quotes `ctrlrun demo` byte for byte, the demo prints euros from src/ctrlrun/cli/demo.py, and docs/assets/demo.gif is a recording of that output. Prose in dollars above a transcript and a GIF in euros would make the README contradict its own evidence. Its story is aligned instead: 500 asked, 5,000 called, one extra zero. Under the demo's own policy 500 is autonomous and 5,000 is not, so the sentence says the extra zero meets a human rather than claiming a denial the demo would not produce.
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Automations to automatically generate PRs for you. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Five commits, all copy and presentation. No
src/change.The page
Seven sections became three slides, one viewport each, grouped as: hero plus the failure chain; the demo CTA plus the three pillars; integration, commercial and footer. The slides are plain markup inside a scroll-snap container, so with no JavaScript the page still reads, indexes and snaps a slide at a time;
snippets/deck-nav.jsxadds the dots, the keyboard and a fit pass, and reads the theme's navbar height rather than assuming one.Fit applies one scale to the whole deck, not one per slide. Scaling each slide against its own content put neighbours at different left edges, which reads as a bug when you arrow between them. Slide 3 was then trimmed until nothing needs scaling at all: at 1440x900 the shared scale is exactly 1 and all three slides start at the same x.
No arrow buttons on screen. The dots are the only visible control, so they carry real labels and take focus. Below 800px wide or 620px tall the deck reverts to an ordinary scrolling page. Navbar wordmark 28px to 40px.
The story
The lead was the lost-reply chain, which needs the reader to already hold a distributed-systems model. It is now the failure people actually fear, and the divergence is on the page rather than taken on trust: the ticket says refund $500, the agent asks for $5,000, one extra zero. With CTRLRun policy denies those arguments and the call never leaves. It is the demo's existing
blockedscenario, so "Walk through this refusal" deep-links to the refusal the chain describes.AMBIGUOUS is demoted, not dropped - pillar 02,
unknown outcomein the code panel, and named in the demo CTA. Everywhere it is documented as library semantics (docs/concepts/, the cookbook, the specs) is untouched.The section caption says what CTRLRun does rather than what it cannot do. Em dashes are out of the site copy; the four left in
docs.mdxarectrlrun demooutput a test asserts byte for byte, plus two build comments.Two things to know
The README stays in euros. It quotes
ctrlrun demo, the demo prints euros, anddocs/assets/demo.gifis a recording of that output. Dollars in the prose above a euro transcript and GIF would make the README contradict its own evidence. Its story is aligned instead, and its policy claim follows the demo's real bands: 500 is autonomous, 5,000 is not, so it says the extra zero meets a human rather than claiming a denial the demo would not produce. Putting the README in dollars means changing the CLI and re-recording the GIF.adopt.ctrlrun.dev is already deployed (it lives outside this repo), both pages, dollars throughout.
tests/test_readme_assets.pypinned the old first-H2 title and now pins the new one; its point is that the README opens on a story rather than a feature table, which still holds. Docs tests pass (92). Checked light and dark, 1440x900 and 414x896.