The page is now three things: what bench is, what installing costs, and
why to bother. The header nav is the way into the docs.
Removing them takes their CSS with them (.doors/.door* in the base sheet
and in all three breakpoints) and two tests that existed only for them —
the six-are-distinct check here and TheDoorsOpenOntoArticles in
test_site_pages. The hero-buttons test survives its class, renamed to say
what it now guards: the landing page's only links into the docs.
One test needed retargeting rather than deleting.
test_it_fails_before_anything_is_written removed /concepts/team-mode/
from the manifest to prove a dead internal link stops the build before
anything is written — but the link it relied on was a door. It now aims
at /guides/install/, which the hero button still hard-links.
Side effect worth having: the two reasons in "Why bench?" that nearly
repeated doors 03 and 04 no longer sit above them.
Two changes to the landing page and the reference layout.
The three problem one-liners become "Why bench?" — four reasons now,
led by the one no hosted tool can answer: bench lives in your codebase
and is built to be extended, so the workflow it runs is exactly yours.
It stays unboxed on purpose; the doors below are the page's one grid of
cards and repeating that shape would make the eye read it twice.
The reference pages split the room right of the nav three fifths prose,
two fifths console. At the old fixed 208px every BOARD_AGENT_MODEL_* key
was cut mid-word, which makes a console of settings useless for the one
thing it is there for. Articles keep the narrow gutter — a list of
headings needs no more.
The narrow-width overrides are repeated at .page-reference .shell
specificity in both media blocks. Without that the base override (0-2-0)
outranks the bare .shell inside the query (0-1-0), the third track
survives, and with the gutter hidden it becomes two fifths of empty grid
squeezing the prose on every phone.
The landing page was carrying two large visuals stacked — a full
terminal in the hero and the board beneath it — which is what made it
read as busy. Now the hero is one third words and two thirds board: the
claim this page makes is a board, so the board is what it shows first
and shows large.
The terminal moves into a 50/50 section below, beside the copy that
explains what installing costs: one script, port 26071, two questions,
and the settings file it writes. The six doors are unchanged.
Smaller changes that follow from it: the headline takes a narrower step
(--t-hero-narrow, 40px) because it no longer has half a row; it loses
its hard <br> and wraps on its own; the CTA drops the time claim now
that a whole section makes it; and the caption under the shot becomes
one plain line rather than a tagged row.
The third setup question wanted an answer about a repo the person may
have just cloned, thirty seconds in, before anything had explained why
the board needed one. The file that names a project's ecosystem usually
names its runner too, so it is read off the project: package.json → npm
test, Cargo.toml → cargo test, go.mod → go test ./..., a
pyproject/setup.py/tests/ → python3 -m unittest.
Nothing recognisable writes BOARD_AGENT_COMMANDS empty rather than the
example's Python default, which would be quietly wrong in most repos —
and a wrong prefix denies an agent exactly the way an empty one does, so
absent beats wrong here.
Two details the first attempt got wrong, both now covered:
- Detection runs *before* the questions. Placed after them, a Ctrl-D
part-way through skipped it and left the example's default.
- "Keep what the project already said" reads the existing .env, not the
example-seeded defaults dict — which already carries the example's
answer, so every first run looked like it had one and detection never
ran.
The landing page's terminal, README.md and AGENTS.md follow: two
questions now, and AGENTS.md documents the detection table.
One conflict, in the 480px block of site.css: main added the landing
page's .shot rules there while this branch widened the prose padding
selector to cover .page-reference. Both belong — the shot is home-only,
the padding is every long-form layout — so the resolution keeps main's
two rules and the branch's wider selector.
Everything else merged clean: the reference layout, its four routes and
the settings parser do not touch what the landing page changed.
The third design layout (1c Logbook) had no page. This lands it, and
with it the four routes a reader reaches for when the guides have
stopped answering: /reference/settings and the three contracts a
project implements against.
The settings page is parsed, not transcribed. site/build.py grows a
second way to make a body — a page may say "generate": "settings"
instead of a "from" heading — and manager/core/.env.example is read on
every build: its blank-line blocks become the page's entries, a comment
block documents the keys directly under it, and the file's own
NAME=value lines are the defaults shown. A key with no comment above it,
or one set twice, stops the build naming the route; a settings page that
disagrees with the settings file is worse than no settings page.
Generated bodies render with raw HTML off. The file writes
<git user.name> meaning a placeholder, and a parser honouring HTML
swallows it — it was never written to be markdown.
The reference layout is the article's three columns with the contents
gutter given over to a console: every entry on the page once more in the
machine register, keys with their defaults on the settings page and
headings on a sliced one. It links the same anchors "On this page"
carries, so the 1080px step folds the whole column away and the contents
strip hands them back — no third copy of anything, and the responsive
rules already in the sheet cover it.
The contract pages are slices like every other page: the adapter
contract and its event schema out of manager/core/adapters/README.md,
the driver and local-command contracts out of AGENTS.md. Renaming any of
those headings stops the build naming its route.
tests/test_site_reference.py holds the promise: add a key to
.env.example with its comment, rebuild, and it is on the page with its
default, with nothing in site/ edited.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The page claimed 'mission control' and showed a terminal. It now shows
the board itself, directly under the hero, on bench's own repo with
three agents working — the claim demonstrated rather than described.
The terminal gives up the height for it: the .env preamble and the
Ctrl-C line go, the install command and the three setup questions stay.
tests/test_site_landing.py's TRANSCRIPT follows, and still holds every
remaining line against the source that prints it.
The shot goes through stamp() like the stylesheet, so its url carries a
?v=<hash>. Without that, /static/*'s year-long immutable cache would
make the screenshot unreplaceable. 1600px wide and palettised to 256
colours — 164K rather than 452K, and a flat dark UI loses nothing to it.
img{max-width:100%} is now a base rule rather than only .prose img: the
shot lives outside the article body, where that rule never reached.
Fathom sends its pageview as an image request. script-src named the
origin and img-src did not, so the script loaded and the one thing it
loads to do was blocked — visible only in the browser console, with a
200 on every response and no pageview at the other end.
The console said it plainly:
Loading the image 'https://cdn.usefathom.com/?h=...&sid=ZPKDEHCV...'
violates the following Content-Security-Policy directive: img-src
'self'
A test now asserts the origin appears under all three directives it
actually uses, because nothing on this side of the wire can tell that it
does not.
The hero explained the architecture before saying why anyone would care:
'task files in stage directories', 'stdlib-only', 'narrates' are words
that mean something once you already use bench. Every line now maps to
something the audience has actually hit — agents outrunning the person
supposed to be tracking them.
- Hero: 'Run a team of coding agents. Stay in control.' The old headline
keeps its job as the brand line, in the footer of every layout.
- A new section between hero and doors: three sentences a reader has
said out loud, each answered by a mechanism rather than a promise.
Deliberately unboxed — the doors below are the page's one grid of
cards, and repeating that shape would make the eye work twice.
- The six doors lead with the outcome and keep one mechanism as the
evidence for it, which is the inversion of what they did before.
- Title and description follow, since a pasted url is the same pitch in
another form.
Two lines that were quietly false are fixed too: the strip's comment
still said this site counts nothing (Fathom counts pageviews now), and
'no per-seat pricing' would have tripped the fiction guard in
tests/test_site_landing.py, which forbids the word outright.
The host uploads the assets directory whole, so a .md left in static/
becomes a public url — static/fonts/README.md was live, telling readers
how to refresh fonts they cannot write to. copy_static skips it, and
internal_targets skips it too: the link checker and the copier have to
agree, or a link to a skipped file would pass the build and 404 on the
site. The licences are .txt and still ship, which is the point of
committing them.
Card 43 records the other thing today's run turned up: the suite reads
the developer's own local/.env, so two sync tests fail here and pass in
CI.
Two changes to what the live site sends.
Analytics: Fathom's tag goes in every template's <head>, deferred. It is
cookieless and collects nothing about a person, so no consent banner —
but it is a third party, so the CSP names cdn.usefathom.com for script
and connect rather than opening the door generally, and the tests that
said 'no script at all' now say 'no script this site depends on, and no
origin nobody chose'.
Caching: the host concatenates a header two matching rules both set
rather than overriding, so /* and /static/* each setting Cache-Control
sent 'max-age=0, must-revalidate, max-age=31536000, immutable' on the
stylesheet — first max-age wins, and the year-long cache never happened.
Measured on the live site, which is where the from-memory assumption in
task 32 said to check it. Now /static/* is the only rule that sets it
and HTML takes the host's revalidating default; the post-deploy checks
in site/README.md verify both ends.
article.html: 34 added the lede under the h1, 35 added the folded
contents strip in the same place. Both belong, and site.css settles the
order — its lede adjacency names .menu-contents + p, so the strip sits
between the title and the lede.
Two things the merge exposed rather than caused:
- $toc and $sidebar were spelled inside article.html's own comments,
and string.Template substitutes there too, so every page carried a
second copy of both rails inside a comment (28 toc links for 7
headings). Doubled to $$toc / $$sidebar, as the template contract
already said to.
- test_site_pages assumed one rendering of each rail. Both are now
written twice by design, so the tests assert every rendering agrees
with the page instead of assuming there is one.
The card file keeps main's location: the board owns a card's stage, and
main had already moved 35 to review/.
Committing the woff2 files is redistribution, and OFL 1.1 asks that its
text and copyright notice travel with the font. IBMPlex.LICENSE.txt from
IBM/plex, ZillaSlab.LICENSE.txt from mozilla/zilla-slab; both ship in
dist/static/fonts/ with the faces they cover.
Fetching them per checkout made every deploy machine ask Google for the
site's own typography, and a clean checkout build silently fell back to
system fonts. 113 KB, immutable under their filenames — which is what
the year-long immutable cache in root/_headers already assumes.
The design is drawn at a fixed 1180px with three-column articles and a
two-column hero, and the site's first traffic is a link pasted into a
chat and opened on a handset. This is what happens below that width —
three max-width steps, and nothing that takes effect at or above the
width the design defines.
The two columns an article loses come back as <details> strips: "On
this page" folds under the title at 1080px, where the gutter goes, and
the section nav becomes a menu under the masthead at 760px, where the
sidebar goes. Both are filled from the same $sidebar and $toc as the
columns they replace, so a folded copy cannot say something the column
does not — and one menu that opens and closes needs no script, which
keeps the site's promise of shipping none.
The rest is what the acceptance asks for: a table becomes its own
scroller with an edge shadow that appears only while there is more to
the right; a token that cannot break, breaks; fenced code keeps
scrolling inside its own block; the hero and title steps come down
without leaving Zilla Slab; everything a finger has to hit is --tap
(44px) tall; and the masthead, footer and hero actions wrap instead of
widening the page.
The one thing that would have changed desktop is guarded rather than
noticed later: the contents strip is a sibling between the h1 and the
body's first paragraph even when display:none, so the lede rule names
it too.
tests/test_site_responsive.py mechanises all four promises, including
the one that matters most — every media query is a max-width below the
design.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Fills the middle of the site. Nine routes, every body a heading slice of
AGENTS.md or README.md, and the article layout given the furniture the
design calls for.
The manifest gains the two concepts nothing covered: /concepts/task-files/
(the header format, from AGENTS.md's own section) and /concepts/adapters/
(the adapter summary, which is the other half of the three-layer law).
/concepts/stages/ now runs through "Moving a task", because the five
directories and moving between them are one idea.
The layout:
- A lede under the title — the one sentence an article authors, taken
from the manifest's `description` or an explicit `lede` where the two
want different words. A slice starts mid-document; a reader arriving
from the nav is owed a line saying what they are looking at.
- Prev/next at the foot, walking the sidebar's own order so the arrows
and the rail cannot disagree. Pages with no section (the landing page,
the 404) are not on the flow.
- "Edit this page on GitHub" anchors to the section the page was cut
from, built from the same `from` heading the slice starts at.
Two bugs the new pages found:
- string.Template substitutes inside HTML comments, so a comment naming
the body placeholder emitted the whole body twice and closed itself
early on the first `-->` in it.
- Promotion could produce a second <h1>. A slice that deliberately runs
past its own section carries headings at the `from` level, and those
promoted to h1 on a page that already had one. Promotion now stops at
h2, where they read as peers — which is what putting them on one page
said in the first place.
tests/test_site_pages.py covers the furniture on the real built site:
the routes, the layout, the sidebar marking one page, the contents list
being exactly the body's own h2s in order, the prev/next chain end to
end, the edit link's anchor, the six landing-page doors, and a table, a
fenced block and a nested list surviving the renderer. The scratch-repo
helper now copies every file a slice links to, since the builder checks
those exist.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Turn design 1b (Dockside) into `/`: a terminal hero, the claim README.md
already makes, six doors, and a strip at the foot. The layout is task
31's; what this commit is really about is that nothing factual on the
page is typed by hand.
- **Two facts are read, not written.** `site/build.py` reads the install
one-liner out of README.md's "Install into a repo" block and the
version out of `manager/core/VERSION`, and offers them to the template
as `$install_block` and `$version`. A renamed section, a missing
VERSION or an install section that lost its command block stops the
build, exactly as a renamed heading already did. `pages.json` loses
its `version` key, and a build refuses one if it comes back.
- **A dead internal link stops the build.** Every href a rendered page
emits — a door as much as a link inside a slice — must resolve to a
route in the manifest or a file in `static/`/`root/`. The check runs
after rendering and before writing, so a bad link leaves the last good
build standing rather than shipping a 404 with a nice typeface.
- **Six real doors.** `pages.json` grows the routes they open: install
and first run, the five stages, agents on the board, PRs and review,
team mode, the three-layer law. They are heading slices, i.e. the
stub routes task 33 expected and task 34 will re-cut.
- **The terminal is a transcript.** README.md's own command, then lines
install.py and board.py really print, with the abridgement declared in
the terminal's title bar. `tests/test_site_landing.py` holds every one
of those lines against the source that prints it, so a reworded prompt
fails the suite instead of quietly making the page fiction.
- **No fake telemetry.** Turn 1's "most opened this week" strip becomes
the version, read from VERSION, and a link to the releases.
The landing page no longer carries a generated body, so the tests that
read one from it now read `/concepts/stages/`, and the two scratch repos
in the suite copy VERSION alongside the markdown.
python3 -m unittest: 407 tests, OK.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
site/wrangler.jsonc puts site/dist/ behind bench.12vectors.com as static
assets. No `main`: the site is files, and a Worker with no script is the
cheapest correct way to serve them.
html_handling force-trailing-slash, so /x redirects to /x/ — the
url the pages link and rel=canonical names. One
page, one address; no url ends in .html.
not_found_handling 404-page, so an unknown path gets dist/404.html
with a 404 status rather than the landing page
with a 200.
routes bench.12vectors.com as a custom domain. Cloudflare
takes the hostname at the zone level and makes the
DNS record; nothing else on 12vectors.com moves.
site/root/_headers carries the response policy. HTML revalidates on
every view, so a deploy is visible on the next reload without anyone
clearing a cache; /static/* is kept for a year and never re-checked,
which is safe because the stylesheet and icon urls carry a hash of their
contents. The general rule is written first and the specific one second,
so a host that merged the two instead of overriding would still land on
max-age=0 — the safe side. Alongside it the baseline a public page owes:
nosniff, a referrer policy, a year of HSTS without preload,
X-Frame-Options, and a default-src 'none' CSP that makes "no analytics,
no third-party anything" something the browser enforces rather than
something a test asserted once.
Deploys are run by hand, as releases already are — no Cloudflare token
in repository secrets, no first deploy pipeline. site/README.md names
the account, the Worker, the route and the four-command sequence, plus
the four things to check after a deploy that no test here can reach.
The tests cover everything before Cloudflare: that the config says what
the site needs, that the build writes the files it names, and that
wrangler.jsonc, pages.json and README.md cannot drift apart about which
domain this is. A live response is not among them.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Three things the build owed the host before the site could have an
address, all of them visible in site/dist/ rather than in a deploy
script.
A 404 page. Cloudflare's not-found handling serves a literal 404.html
from the root of the assets directory, so a route may now name an .html
file instead of ending in "/" — the one that does is /404.html, a normal
manifest entry with its own layout. It is the site's design and the
site's nav, with a way back to the landing page, a noindex and no
canonical. A null section keeps it off the nav it renders.
site/root/, copied verbatim to the TOP of the build the way static/ is
copied to a subdirectory of it. _headers is what it holds; the host
reads that file from the root and nowhere else. A file in root/ that a
route would also write stops the build rather than letting one silently
win.
Stamped urls for the stylesheet and the icon: the templates link them
through $stylesheet and $icon, which carry a ?v=<hash> of the file's own
contents. Nothing in static/ is renamed, so the tree and the /static/*
glob stay as they were — but the url changes when the file does, which
is what will make a year-long immutable cache safe.
Tests ask the builder where a route lands rather than keeping their own
copy of the rule.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
bench has no public page. site/ is the machinery for one: a manifest,
a generator, two layouts from the turn-2 docs design, and the Daylight
half of the board's own token set.
Nothing here is transcribed. Every page body is a heading slice of a
file that already documents bench, and site/pages.json is the only
place that mapping is written down — the IA is editorial judgement, so
it lives in one readable file rather than in a directory convention.
The point is the failure: a from/to heading the source no longer
contains stops the build naming the route, the file and the heading,
and every page renders before the output directory is touched, so a
drifting rebuild leaves the last good build standing instead of
replacing it with an empty one. Repo-relative links come out as site
routes or GitHub links; a dead one stops the build too.
Rendering is markdown-it-py, pinned in site/requirements.txt. The
stdlib-only law binds manager/core/ — the tool people install — and
site/ is neither shipped nor installed, so a hand-rolled parser would
have been risk spent in the wrong place on a document that leans on
fenced code, nested lists and inline code throughout.
Templates are string.Template: $name substitutes and a literal dollar
doubles, because str.format's braces collide with every line of CSS.
Fonts are self-hosted and same-origin: no page bench serves may need a
request to a third party to be read. fetch-fonts.py downloads the seven
woff2 files once; until they are there the build says which are missing
and the pages fall back to the system stack.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
istos