5.2 KiB
36 — Add the reference section: settings and the contracts
Status: In Progress 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, panel1c, 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 contractAGENTS.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
referencelayout 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/driverand 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.examplewith its comment, when the site rebuilds, then it appears on/reference/settingswith its default, without anyone editing the site. - Every setting in
.env.exampleappears 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.jsondefines only Guides and Concepts pages; there is no/reference/settings,/reference/adapters, or/reference/driverentry, and nosection: "Reference". - No
referencelayout exists.site/templates/holds onlyarticle.html,home.html,notfound.html. The task's "reference layout from the 1c design" is unbuilt. - No
.env.exampleparsing exists.site/build.pyslices 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 newBOARD_*key in.env.exampleauto-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/(commit6204e1a board: 34 → done); it established thearticlelayout and thepages.jsonmanifest pattern this card builds on. - The 1c "Logbook" design is present in
reference/bench-docs-design-turn2.dc.html(panel1c, 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.