board: 36 → to-do (istos)

tasks/to-do/36-the-reference-section.md

@@ -0,0 +1,71 @@
+# 36 — Add the reference section: settings and the contracts
+
+**Status:** To Do
+**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.