From 6034a216e157436775e18e929c72d33f88d81411 Mon Sep 17 00:00:00 2001 From: Edward Langley Date: Tue, 22 Sep 2026 08:26:12 -0700 Subject: [PATCH] docs(site): publish the two new context docs, and de-number two stale counts MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The `build` job failed, correctly: `scripts/build-doc-site.mjs` requires every `context/**/*.md` to be either in the SECTIONS manifest or a named omission (improvise-res9's cure), and the two files this branch added were neither. Both are now published, beside the TUI in each section. While there: `context/code/doc-site.md` asserted 'the seven `context/code/*.md` documents' when there were already twelve, and '501 entries' when the checker reports 801. Both were stale before this branch and this branch makes them staler, so they are de-numbered rather than re-asserted โ€” a count in prose that nothing checks is a fact with no owner, and the shape that stops drifting is not having one. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01FC2jVn8Au7E9JPkw6bwXXH --- context/code/doc-site.md | 8 ++++---- scripts/build-doc-site.mjs | 2 ++ 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/context/code/doc-site.md b/context/code/doc-site.md index 92f8965d..44a8a934 100644 --- a/context/code/doc-site.md +++ b/context/code/doc-site.md @@ -21,7 +21,7 @@ Published, in four sections: | Start here | `docs/design-notes.md`, `context/design-principles.md`, `context/repo-map.md` | What the project is for, the doctrine, and the single best explanation of how it is built. | | Decision records | `context/adr/*.md` | An ADR is written for an outside reader by construction โ€” it states the options that were rejected, which is the part that is worth reading and the part that is nowhere else. | | The arguments, by area | `context/code/*.md` | This is the reasoning that used to live in code comments and was moved out under the two-line cap (design-principles ยง6). It is the most valuable prose in the repository and it is addressed to exactly the reader a documentation site has. | -| Test evidence | `context/test-evidence/*.md` | 501 entries, one per test whose narrative is longer than its code. | +| Test evidence | `context/test-evidence/*.md` | One entry per test whose narrative is longer than its code. | Not published: @@ -62,9 +62,9 @@ says `context/code/*.md` is published; the manifest disagreed and nothing could see it. That is the whole failure mode in one file. **Test evidence is the one judgement call worth stating.** The argument for -leaving it out is that 501 entries about individual tests are noise to a reader -who wanted to know what a pivot table is. The argument for keeping it is -stronger: every one of the seven `context/code/*.md` documents points at its +leaving it out is that hundreds of entries about individual tests are noise +to a reader who wanted to know what a pivot table is. The argument for keeping it is +stronger: every one of the `context/code/*.md` documents points at its evidence file by name, so omitting it would break the published prose in exactly the way this site is otherwise careful not to; and the evidence file is the most distinctive artefact the repository has โ€” a written record of the diff --git a/scripts/build-doc-site.mjs b/scripts/build-doc-site.mjs index 1a847d4e..24bb82b4 100644 --- a/scripts/build-doc-site.mjs +++ b/scripts/build-doc-site.mjs @@ -58,6 +58,7 @@ const SECTIONS = [ ["context/code/command.md", "code/command", "improvise-command"], ["context/code/clients.md", "code/clients", "The clients"], ["context/code/tui.md", "code/tui", "The TUI"], + ["context/code/cli.md", "code/cli", "The headless CLI"], ["context/code/gp.md", "code/gp", "gp-tree and improvise-gp"], ["context/code/kb-tool.md", "code/kb-tool", "The kb tool"], ["context/code/tooling.md", "code/tooling", "The repository's own checkers"], @@ -75,6 +76,7 @@ const SECTIONS = [ ["context/test-evidence/command.md", "test-evidence/command", "improvise-command"], ["context/test-evidence/clients.md", "test-evidence/clients", "The clients"], ["context/test-evidence/tui.md", "test-evidence/tui", "The TUI"], + ["context/test-evidence/cli.md", "test-evidence/cli", "The headless CLI"], ["context/test-evidence/gp.md", "test-evidence/gp", "gp-tree and improvise-gp"], ["context/test-evidence/tooling.md", "test-evidence/tooling", "The repository's own gates"], ],