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.
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>
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/.
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>
istos