Files
bench/tasks/in-progress/36-the-reference-section.md
T

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, 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.