36 — Add the reference section: settings and the contracts

Status: Done PR: https://github.com/12vectors/bench/pull/33 Assignee: istos Priority: Low — deliberately after v1; the guides carry the site until someone needs an exact default Type: Feature Depends on: 34 — the article layout and the manifest pattern it establishes

The third design layout, 1c (Logbook), has no page yet: v1 of the site is landing, guides and concepts. This card is where the reference lands when it is wanted — every BOARD_* setting with its default, and the three contracts a project actually has to implement against.

Context

Design: Bench Docs.dc.html, panel 1c, as corrected by task 30 — prose left, a pinned console on the right, flag-style entries down the page. Turn 1 aimed it at a CLI bench does not have; corrected, it aims at settings, which have the same shape.
The sources are already exhaustive and already maintained:
- ../../manager/core/.env.example — every setting with its default documented, the reason this page can be generated at all
- ../../manager/core/adapters/README.md — the adapter contract, including the normalized event schema
- ../../manager/core/driver.example/ — the driver contract
- AGENTS.md's "Local commands" — the command contract
Deferred on purpose: the concepts explain the settings that matter (BOARD_SYNC, BOARD_COMMIT_MOVES, the agent binaries), and a reference page nobody has asked for yet is a page that goes stale quietly.

Affected areas: site/pages.json, a reference template, and whatever parsing .env.example needs.

What to build

A reference layout from the corrected 1c design.
/reference/settings — generated by parsing .env.example: one entry per key with its default and its documented effect, grouped as that file groups them. Parsed, not transcribed; a settings page that disagrees with the example file is worse than no settings page.
/reference/adapters — the adapter contract and event schema, sliced from the adapters README.
/reference/driver and the local-command contract — the two executables a project writes itself.
The section joins the site nav alongside Guides and Concepts.

Out of scope — tempting neighbours left alone:

An HTTP API reference. The board's routes are internal to the page that calls them and are not a public interface.
Versioned or multi-release docs.

Acceptance

Given a new setting added to .env.example with its comment, when the site rebuilds, then it appears on /reference/settings with its default, without anyone editing the site.
Every setting in .env.example appears exactly once; a key documented nowhere fails the build rather than being skipped.
The contract pages are slices of the contract files, not paraphrases.
Edge case: a multi-line comment above a key renders as that key's description without swallowing the next key.

Notes

Left in backlog on purpose. Promote it when someone asks "what's the default for X" twice.

Relevance review — 2026-07-31 16:08 (Sage)

RELEVANCE REVIEW: Still relevant

The work is not started — nothing on /reference/ exists yet, and the task's dependency (task 34) is done, so this card is unblocked and buildable exactly as written.

What I checked

The site has no reference section. site/pages.json defines only Guides and Concepts pages; there is no /reference/settings, /reference/adapters, or /reference/driver entry, and no section: "Reference".
No reference layout exists. site/templates/ holds only article.html, home.html, notfound.html. The task's "reference layout from the 1c design" is unbuilt.
No .env.example parsing exists. site/build.py slices markdown sections out of source docs by heading (slice_section, sections, render_nav); it has no per-key settings parser. The task's headline acceptance test — a new BOARD_* key in .env.example auto-appearing on the settings page — is not met by any current code.
The sources the task rests on all still exist, at the paths it names (resolved from a stage dir's ../../): manager/core/.env.example, manager/core/adapters/README.md, manager/core/driver.example/, and AGENTS.md's "Local commands" section.
The dependency is satisfied. Task 34 is in done/ (commit 6204e1a board: 34 → done); it established the article layout and the pages.json manifest pattern this card builds on.
The 1c "Logbook" design is present in reference/bench-docs-design-turn2.dc.html (panel 1c, labelled LOGBOOK), which is what the task describes.

One thing to fix if you promote it

The task cites the design file as Bench Docs.dc.html, but the file in the repo is reference/bench-docs-design-turn2.dc.html. Same design, renamed since the card was written — update the Context bullet so a work agent finds it.

Recommendation

Keep as is (with the one filename tweak above). The card is accurate, unblocked, and correctly scoped; it remains deliberately deferred per its own Priority/Notes ("promote when someone asks 'what's the default for X' twice"). Nothing here is stale enough to warrant a rewrite, and no work has been done that would move it toward done.

Work report — 2026-07-31 16:29 (Reed)

abled, because the file writes <git user.name> meaning a placeholder and a parser honouring HTML would swallow it.

site/templates/reference.html — the 1c Logbook layout: the article's three columns with the contents gutter given over to a pinned console listing every entry on the page (keys with their defaults on the settings page, headings on a sliced one). It links the same anchors "On this page" carries, so the existing 1080px fold already covers it and no third copy of the links exists.
site/pages.json — a Reference section beside Guides and Concepts: /reference/settings/, /reference/adapters/, /reference/driver/, /reference/commands/.
site/static/site.css, site/README.md — the console and the light "flag" strip under each setting; the manifest's new generate key, the parser's two build failures, and the layout documented.
tests/test_site_pages.py — its articles() helper now means "pages in the article layout" rather than "every page on the flow", since the flow has a second layout on it. The one promise that is site-wide, test_no_body_is_authored_twice, was widened rather than narrowed: every flow page must name a source and either a from or a generate.

Two judgement calls worth confirming

The card's third bullet reads as one page ("/reference/driver and the local-command contract — the two executables a project writes itself"). I shipped it as two pages, /reference/driver/ and /reference/commands/, because the two sections are not adjacent in AGENTS.md and a single slice spanning them would have dragged "The activity bar and the archive" onto a contract page. Merging them would mean reordering AGENTS.md, which is outside the card's stated affected areas.
Those two pages have no sub-headings, so they render no console — the layout drops the box rather than pinning an empty terminal, the same way the contents strip already handles a body with no h2s. If you want a console on all four, the fix is in AGENTS.md's section structure, not in site/.

The four acceptance criteria, and where each is checked

A new key in .env.example appears with its default and no site edit — ANewSettingReachesTheSiteByItself.test_a_new_key_appears_with_its_default_and_its_comment.
Every setting exactly once, and a key documented nowhere fails the build — TheSettingsPageIsTheEnvFile.test_every_setting_appears_exactly_once_in_the_console (compared against an independent parser written in the test file, sharing no code with the builder's) and ADriftingEnvFileStopsTheBuild.test_a_key_documented_nowhere_fails_rather_than_being_skipped.
The contract pages are slices — TheContractPagesAreSlices, plus two drift tests proving a renamed heading stops the build naming its route.
A multi-line comment does not swallow the next key — test_a_multi_line_comment_does_not_swallow_the_next_key, whose fixture deliberately names the second key inside the first key's comment.

8.3 KiB Raw Permalink Blame History