Skip to content

Rebuild the homepage as a scrolling page, and cut the README to three questions - #132

Merged
arpanghoshal merged 5 commits into
mainfrom
docs-homepage-refresh
Sep 9, 2026
Merged

Rebuild the homepage as a scrolling page, and cut the README to three questions#132
arpanghoshal merged 5 commits into
mainfrom
docs-homepage-refresh

Conversation

@arpanghoshal

@arpanghoshal arpanghoshal commented Sep 9, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

The three-slide scroll-snap deck depended on 100dvh slides and a JS transform: scale() fitter to make content fit. It broke deep links and read badly on short viewports. The homepage is now an ordinary scrolling document.

Content

  • Five regulated domains — finance, healthcare, insurance, life sciences, legal — one per check, so each card demonstrates a different refusal: money changed after approval, a patient messaged twice, a claim payment whose reply was lost, a controlled workflow the agent may not release, a filing needing a person. Public Sector cannot be a card label: lint.py forbids sector.
  • A fourth rule card for the decision record. Receipts and verify were absent from the homepage entirely after the rewrite.
  • One sentence restoring what CTRLRun is not — not an LLM, does not read prompts, checks the action rather than the thinking.
  • /try states again that its rules are not industry defaults.
  • The boundary gate carries the logo lockup (keycap mark plus the CTRL/Run weight split) rather than a plain wordmark.
  • adopt.ctrlrun.dev linked for businesses, in the production strip and the footer.
  • The navbar primary returns to Get a safety review; the hero keeps the demo CTA. The two were pointing at the same destination with near-identical labels.

Cleanup

  • Delete snippets/deck-nav.jsx, orphaned once the deck went, plus ~30 dead rules (cr-pillars, cr-how-steps, cr-outcomes, cr-chain-cta, cr-commercial, cr-comparison, cr-failure).
  • Specificity fix: .cr-home-hero inside @media (max-width:800px) is one class and could never beat .cr-home .cr-home-hero, so the tablet hero padding never applied. Confirmed fixed — 38px/48px at 768.
  • Collapse two generations of duplicated .cr-lede and .cr-home-hero declarations.
  • Restore Payments as the explorer default. On DevOps the demo copy degrades from $500 → $5,000 to "one approved target".

Verification

lint.py 0 findings, links.py 0 broken. Every /try deep link validated against the explorer's domain, action and situation data. Rendered at 390 / 768 / 1440: one h1, no horizontal overflow, rule cards 4 → 2 → 1, domain cards 5 → 2.

Known, not addressed here

docs/assets/verify-website.cjs drives the scenario explorer against /, which stopped being true at #130/#131. It needs repointing at /try and its getByLabel('Explore a situation') selector updated to Choose what goes wrong. Pre-existing, tracked separately.

The README, cut to three questions

Added after the homepage work, in f07a007 and 945b708. 705 lines to 355. The page answers
what CTRLRun does, how to use it in three steps, and how it works. Everything else is a link to
ctrlrun.dev. Kept as extras: the wordmark, the badges, the demo animation, contributing, licence.

What went, and where its guard went with it

The README is pinned by tests in eight files, so nothing was deleted without moving the check
behind it.

  • The demo transcript is a collapsed block rather than a section of its own.
    test_the_readme_demo_section_quotes_the_demo_output_verbatim and
    test_every_expected_line_is_one_the_readme_quotes still hold every line the demo prints
    against the README; only their anchor moved, and a missing block is a failure rather than an
    empty string that would pass vacuously.
  • The verify report had two identical copies. docs/docs/verify.md is now its only home and
    keeps the verbatim-output guard, renamed to say so. The drift test between the two copies is
    gone because there is nothing left to drift. The README keeps the badge sentence, asserted by
    a new test_the_readme_says_what_the_badge_does_not_mean.
  • The readiness block keeps its two homes on the site. READINESS_HOMES drops the README;
    the generator still refuses a shrunken suite.
  • The four paragraphs on limits are one paragraph. Both halves of SPEC-v0.6 §6.4's sentence
    survive it, so T180's allow-list points at the line that now carries them rather than losing
    the entry.
  • docs/docs/CLAIMS.md follows the two renamed tests.

Unchanged: the nine-domain table read back against examples/policies/, SPEC-v0.5 §7 item 4's
negative sentence (T139), the capability matrix, the runnable quickstart blocks, and
absolute-only links for PyPI.

MANIFEST.in ships docs/images/*.mp4 and *.jpg, which is what check was failing on at
7eeec77: the homepage video is tracked, and test_the_sdist_carries_everything_the_tests_read
requires a tracked file the tests read to be in the sdist.

Verification

PYTHON=.venv/bin/python scripts/check.sh: 4443 passed, 47 skipped, ruff and mypy --strict
clean. links.py 0 broken, lint.py 0 findings, snippets.py 97 runnable blocks, 0 failed.

@arpanghoshal
Replace the homepage deck with a scrolling page, led by regulated dom…
b82040e 
…ains

The three-slide scroll-snap deck depended on 100dvh slides and a JS transform
scale to make content fit; it broke deep links and read badly on short
viewports. The homepage is now an ordinary document.

Content:
- Five regulated domains — finance, healthcare, insurance, life sciences,
  legal — one per check, so each card demonstrates a different refusal.
  Public Sector cannot be a label: lint.py forbids "sector".
- A fourth rule card for the decision record, so receipts and verify are not
  absent from the homepage.
- One sentence restoring what CTRLRun is not: not an LLM, does not read
  prompts, checks the action rather than the thinking.
- /try states again that its rules are not industry defaults.
- The boundary gate carries the logo lockup rather than a plain wordmark.
- adopt.ctrlrun.dev linked for businesses, in the production strip and footer.
- The navbar primary returns to the safety review; the hero keeps the demo,
  so the two CTAs stop competing for the same destination.

Cleanup:
- Delete deck-nav.jsx, orphaned once the deck went, along with ~30 dead rules
  (pillars, how-steps, outcomes, chain-cta, commercial, comparison, failure).
- Fix a specificity bug: .cr-home-hero in @media(max-width:800px) could never
  beat .cr-home .cr-home-hero, so the tablet hero padding never applied.
- Collapse two generations of duplicated .cr-lede and .cr-home-hero rules.
- Restore Payments as the explorer default; on DevOps the demo copy degrades
  from $500/$5,000 to "one approved target".

lint.py 0 findings, links.py 0 broken. Every /try deep link validated against
the explorer's domain and situation data. No horizontal overflow at 390, 768
or 1440.
@mintlify

mintlify Bot commented Sep 9, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

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

Project Status Preview Updated
ctrlrun 🟢 Ready View Preview Sep 9, 2026, 6:56 AM

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

@arpanghoshal
Condense the hero example and name the failure in its headline
4555f19 
The two columns repeated their first two steps verbatim: same ticket, same
agent request, printed twice. Ten boxes carrying six boxes of information, in
a card 607px tall that pushed the hero past the fold.

State the premise once, then fork. The card is 467px, and the headline says
what the example is about — a tool the agent was allowed to call, with an
amount it was not — instead of asserting the model's state of mind.
@arpanghoshal
Explain the demo, add the screencast, and give the page room
7eeec77 
The /try page opened on dropdowns with no statement of who was doing what: the
three-lane explanation of agent, boundary and real system was collapsed into a
details element below the demo, the chips and the share box. A visitor reached
the controls before being told what they were controlling.

/try:
- Lift the three lanes above the controls and say plainly that an LLM picks the
  action and believes it is right.
- Title states the division: the model decides what, CTRLRun decides whether.
- Number the three controls and hand the visitor a role before them.

Homepage:
- A 49 second screencast of a policy file and the decisions it produces, between
  the domains section and the integration section. Re-encoded 2560x1440 to 720p,
  4.2MB to 1.1MB, poster frame and preload none so only a viewer who scrolls to
  it pays for it. Plays on scroll via IntersectionObserver, muted and looping,
  pausing when it leaves view and respecting prefers-reduced-motion.
- Five integration surfaces under the CTA: Python, the MCP gateway, the
  framework adapters, non-agent workloads, and the HTTP API marked PLANNED
  because it is not built and carries no milestone.
- Move the proof links under the code block they refer to.

Spacing pass throughout, and two bugs it exposed: the code column was centred
against a taller sibling, and .cr-surfaces lost its top margin to the
.cr-site ul reset, which outranks a bare class.

No em dashes in visitor-facing copy.
@arpanghoshal
Cut the README to three questions, and move the guards it carried
f07a007 
705 lines down to 355. The page now answers what CTRLRun does, how to use
it in three steps, and how it works, and everything else is a link to
ctrlrun.dev. Kept as extras: the wordmark, the badges, the demo animation,
contributing and the licence.

What went, and where its guard went with it:

- The demo transcript is now a collapsed block rather than a section.
  `test_the_readme_demo_section_quotes_the_demo_output_verbatim` and
  `test_every_expected_line_is_one_the_readme_quotes` still hold every
  line the demo prints against the README; only their anchor moved.
- The verify report had two copies, and now has one. `docs/docs/verify.md`
  keeps the verbatim-output guard, renamed to say so, and the drift test
  between the two copies is gone because there is nothing left to drift.
  The README keeps the sentence that stops the badge being read as more
  than it is.
- The readiness block keeps its two homes on the site. READINESS_HOMES
  drops the README; the generator still refuses a shrunken suite.
- The four paragraphs on what CTRLRun is not are one paragraph. Both
  halves of SPEC-v0.6 §6.4's sentence survive it, so T180's allow-list is
  updated to the line that now carries them rather than pruned.

The nine-domain table, the adapter section's negative sentence (SPEC-v0.5
§7 item 4, T139), the capability matrix, the runnable quickstart blocks and
every absolute link are unchanged.

4443 passed, 47 skipped. links, lint and snippets clean.
@arpanghoshal
Drop the noqa the shortened allow-list line no longer needs
945b708 
The T180 entry was rewritten when the README's four limits became one
paragraph, and the new line fits in 100 columns, so `# noqa: E501` became
an unused directive and RUF100 failed the `check` job on it. Caught by CI
rather than locally because ruff runs first in `scripts/check.sh` and the
last local run of it predates that edit.
@arpanghoshal arpanghoshal changed the title Replace the homepage deck with a scrolling page, led by regulated domains Rebuild the homepage as a scrolling page, and cut the README to three questions Sep 9, 2026
@arpanghoshal
arpanghoshal merged commit 637c699 into main Sep 9, 2026
11 checks passed
@arpanghoshal
arpanghoshal deleted the docs-homepage-refresh branch September 9, 2026 09:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@arpanghoshal