From f15d7bd3e9d49e9bc92cea26f28d3d68a906cebe Mon Sep 17 00:00:00 2001 From: istos Date: Fri, 31 Jul 2026 14:11:24 +0200 Subject: [PATCH] =?UTF-8?q?board:=2036=20=E2=86=92=20to-do=20(istos)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- tasks/to-do/36-the-reference-section.md | 71 +++++++++++++++++++++++++ 1 file changed, 71 insertions(+) create mode 100644 tasks/to-do/36-the-reference-section.md diff --git a/tasks/to-do/36-the-reference-section.md b/tasks/to-do/36-the-reference-section.md new file mode 100644 index 0000000..91598d5 --- /dev/null +++ b/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.