From 79bafeb4f8b1889ca60680169bd6dbedea130ff4 Mon Sep 17 00:00:00 2001
From: Kuba Sunderland-Ober <kuba@mareimbrium.org>
Date: Sun, 27 Sep 2026 13:16:47 +0200
Subject: [PATCH 01/27] wip: the file tools decode a \u escape; say so, and
 what to write instead

---
 WIP.md | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/WIP.md b/WIP.md
index 800d8275..69549926 100644
--- a/WIP.md
+++ b/WIP.md
@@ -565,6 +565,12 @@ they are.
   through `<<'EOF'` had every `"\\s+"` delivered as `"\s+"`, matched nothing, and reported
   **444 unclassifiable fences against a true 32** --- a number that reads as a finding
   about the corpus and was a finding about the quoting.
+
+  **The file tools decode a `\u` escape of four hex digits** into the character it
+  names: a BOM, an em-dash and a replacement character all arrived raw, and only NUL was
+  left as written. A doubled backslash arrives doubled, which is a different string.
+  Write the brace form, `\u{FEFF}`, which arrives intact (a regex needs the `u` flag
+  for it), and check a file you have written for raw non-ASCII.
 - Don't push or force-push without explicit user request.
 - Don't leave a remote image URL in a finished page. A pasted `https://github.com/user-attachments/assets/...` link is fine to write --- [builder/vendor-assets.mjs](builder/vendor-assets.mjs) downloads it to `docs/assets/attachments/gh-<uuid>.<ext>` on the next local build and rewrites the render to point there; commit the downloaded file with the edit. Any other remote host has no such handling: download it yourself and commit it under the section's `Images/` folder. Remote images cost a network round trip per page view, break the `file://` offline mirror, and **abort the PDF book render** -- the forked paged.js in `book/lib/` dropped async image loading, so an image still in flight when the page-breaking pass runs raises instead of degrading. The build enforces this unconditionally (see [Site integrity check](#site-integrity-check)); `--check-remote-assets` is the standalone checker's flag, not a `tbdocs` one. The check is scoped to `<img>`; `<iframe>` is untouched, but the site no longer has any embeds. A video is authored as a marked link -- `[Title](https://www.youtube.com/watch?v=<id>){: .video }` -- which `videoLinkPlugin` ([builder/render.mjs](builder/render.mjs)) renders as a locally vendored poster frame linking out to the video page, styled by `.video-link` in `docs/_sass/custom/custom.scss`. That makes the site free of third-party requests entirely; don't reintroduce an embed or a hotlinked `img.youtube.com` thumbnail.
 - **Don't hand-edit a diagram's `.svg`, and don't change its `font-family` anywhere but the `.dot`.** The `.svg` is a build artifact; the next build overwrites it. More to the point, Graphviz sizes every box to the text *it* measured, so a face the layout never saw leaves labels hanging outside their boxes --- which is exactly how 27 labels shipped that way across three diagrams. Edit the `.dot`, rebuild, and let `node scripts/check_dot_fit.mjs` confirm it; see [Diagrams](WIP.Typography.md#diagrams).

From d294f45ad92cfc1a89b363227464871bad31379d Mon Sep 17 00:00:00 2001
From: Kuba Sunderland-Ober <kuba@mareimbrium.org>
Date: Sun, 27 Sep 2026 13:20:38 +0200
Subject: [PATCH 02/27] lib: markdown.mjs and frontmatter.mjs, with their
 probes

---
 WIP.md                          |   2 +-
 builder/PLAN-TOOLING-REVIEW.md  |  73 ++++++++++++
 docs/Documentation/Extending.md |   2 +-
 docs/Documentation/Tools.md     |   6 +-
 lib/README.md                   |   9 ++
 lib/frontmatter.mjs             |  61 ++++++++++
 lib/markdown.mjs                | 204 ++++++++++++++++++++++++++++++++
 scripts/check_code_regions.mjs  | 148 ++++++++++++++++++++++-
 8 files changed, 499 insertions(+), 6 deletions(-)
 create mode 100644 lib/frontmatter.mjs
 create mode 100644 lib/markdown.mjs

diff --git a/WIP.md b/WIP.md
index 69549926..0f1ddc25 100644
--- a/WIP.md
+++ b/WIP.md
@@ -501,7 +501,7 @@ wrapper:
 | `check.bat` | `check_tree_fresh` | the tree is not older than the sources that produced it |
 | `check.bat` | `check_dot_fit` | every diagram label sits inside the box Graphviz drew for it |
 | `check.bat` | `pick_a11y_sample --check`, `check_a11y` | see [WIP.A11y.md](WIP.A11y.md) |
-| `test.bat` | `check_code_regions` | no source or HTML rewrite altered a code region |
+| `test.bat` | `check_code_regions` | no source or HTML rewrite altered a code region; `lib/markdown.mjs` and `lib/frontmatter.mjs` pass their probes, and the block parse finds what the full parse finds |
 | `test.bat` | `check_regex_safety` | no regex in the tree can backtrack exponentially |
 | `test.bat` | `check_symbol_index` | the symbol index still places each kind of symbol, from fixtures |
 | `test.bat` | `check_ci_workflows` | both CI workflows run every wrapper gate, with the same arguments and order, and build with `build.bat`'s flags |
diff --git a/builder/PLAN-TOOLING-REVIEW.md b/builder/PLAN-TOOLING-REVIEW.md
index c146e359..28bb32d2 100644
--- a/builder/PLAN-TOOLING-REVIEW.md
+++ b/builder/PLAN-TOOLING-REVIEW.md
@@ -558,6 +558,65 @@ whole corpus takes about 34 ms.
 **Verify.** The probes. Over every page under `docs/`, `blockRegions` finds the same 1,371
 fences as `check_code_regions.mjs`'s own pass over the tokens.
 
+**Landed.** `lib/markdown.mjs` exports `blockRegions(src, { md })`, `maskCode(src, { md,
+indented })`, `splitCodeSpans(line)`, `splitOnMarker(src, isMarker, { md })` and `mapLines(src,
+fn)`, the line-splice helper. `lib/frontmatter.mjs` exports `parseFrontmatter(raw)`. Nothing
+adopts either yet. `check_code_regions.mjs` gained eleven module probes, one of them the
+sixteen code-span cases, and its sweep now checks on every page that `blockRegions` gives the
+full parse's fences, code blocks and HTML blocks at the same lines; its summary line adds the
+fence count. `lib/README.md`, Tools.md's list entry and section, Extending.md's "Say what a
+pass covered" and WIP.md's gate row say so.
+
+What the module decides, which later entries rely on:
+- **Lines** end at CRLF, LF or a lone CR, as in CommonMark, and are 0-based. `blockRegions`
+  applies markdown-it's `normalize` rule itself, since a block-only parse skips it: without
+  it a CRLF closing fence closes nothing. `mapLines` and `splitOnMarker` split the same way,
+  so a region's `start` and `end` index what they see. Neither gives a line for the empty
+  remainder after a final line ending, where `split("\n")` gives one (C35, C36).
+- **A region** is `{ type, start, end, markup, info, content }`: a half-open range whose
+  lines keep their blockquote and list prefixes, and markdown-it's token fields. Regions are
+  disjoint and in document order.
+- **`maskCode`** replaces a fence whole, prefixes included, with one line that starts with a
+  backtick, as `maskCodeRegions` did; the line's ending stays outside the placeholder.
+  Code spans are masked on every other line, HTML blocks included, and indented code blocks
+  only under `indented: true`.
+- **`splitOnMarker`** returns `{ marker, start, lines }[]`: first the lines before any marker,
+  with `marker` null, then each marker line's text and index with the lines after it, line
+  endings dropped. A line inside any region, HTML blocks included, is never a marker.
+- **`splitCodeSpans`** is `convert_em_dash_separators.mjs`'s `splitInlineCode` verbatim, so
+  V1's equivalence with `maskInlineCode` carries over. It scans backticks only: the entry's
+  "backtick and tilde run scanner" is wrong, since a code span cannot be written with tildes.
+  Its two known gaps are stated beside it, and both copies had them: a span over two lines
+  is not seen, and a backslash before a backtick does not stop it opening a span.
+- **`parseFrontmatter`** returns `{ data, content }`, or null when the first line is not
+  `---`. It differs from gray-matter only on input no page holds (C40, C41): a block closes
+  only at a line that is `---` with optional trailing whitespace, where gray-matter closes at
+  the first `\n---` whatever follows; nothing may follow the opening `---` but whitespace,
+  where gray-matter reads a language name there; an unclosed block throws, where gray-matter
+  parses the rest of the file as YAML; a block that parses to anything but a mapping throws.
+  An empty block, or one of only comments, gives `{}`, as gray-matter's does. A YAML error
+  names the line of the file, because the parse is given a newline in place of the opener.
+
+**Verify.** The eleven module probes and `--self-test` pass. Over all 912 pages
+`blockRegions` agrees with the full parse, and finds **1,372 fences, not 1,371**: one has
+been added since the review. Each of eight faults put into the modules fails the gate:
+dropping the newline normalisation (the CRLF probe and 598 pages), a marker split that
+ignores regions, a span closed by a longer run, `blockRegions` ignoring the parser passed,
+indented blocks always masked, the placeholder losing its line ending (three probes), no BOM
+strip, and no stand-in line for js-yaml (the error-line probe). `maskCodeRegions` fails the
+A3-1 probe's mask assertion: it masks the ```` ```abc`def ```` line and all after it as a
+fence. Ahead of C32 and C40, two scratch comparisons over the corpus: `maskCode` with the
+site's parser against `maskCodeRegions`, on the content `render.mjs` sees, gives the same
+masked text on 905 of 912 pages (the other seven are under C32); `parseFrontmatter` against
+gray-matter as `discover.mjs` calls it gives the same result on all 912 pages and on the two
+tracked `.html` pages, which have frontmatter too: data deep-equal, content byte-equal. The
+tree comparison differs only where the commit edits pages: Tools and Extending online and
+offline, the search data, and `book.html`. Nothing in `builder/` imports the modules yet.
+
+Writing the modules, the Write tool turned a four-digit `\u` escape into the character it
+names, twice; a scan for raw non-ASCII found both. WIP.md's Don'ts now say so, in the commit
+before this one.
+
 ### C32 — `render: the pre-render rewrites ask lib/markdown what is code`
 
 **A3-1 (R1), first half.** `maskCodeRegions` (`render.mjs:141-175`) accepts a backtick fence
@@ -573,6 +632,20 @@ site's instance and `indented: false` as today. `maskCodeRegions` and `maskInlin
 **Verify.** The tree comparison identical, since no page holds the shape.
 `check_code_regions.mjs` clean, its mirror-fault probes included.
 
+**Found in C31: the new mask covers seven fences the old one does not.** `maskCodeRegions`
+masks a fence only when nothing but up to three spaces or tabs precedes its opener, and
+`maskCode` masks every fence markdown-it finds. On the content `render.mjs` sees, with the site's parser, the
+two masks give the same text on 905 of 912 pages. The other seven each hold a `> ```tb`
+fence inside an admonition, which only the new mask hides: `CEF/CefBrowser/index.md`,
+`WebView2/WebView2/index.md`, `tbIDE/HtmlElement.md`, `Core/If-Then-Else.md`,
+`Core/Option.md`, `Core/WithEvents.md` and `VBA/Interaction/InputBox.md`. The tree comparison
+should still come out identical, but that is reasoned, not measured: `check_code_regions.mjs`
+already shows that no rewrite alters those fences, and `rewriteAdmonitions` runs after the
+restore. If it differs, look at those seven pages first. Two more things this commit must
+settle. `applyPreRenderRewrites` takes no parser today, so it needs one to pass the site's.
+And `check_code_regions.mjs` calls it: with the bare parser by default, the gate would mask
+differently from the build wherever the definition-list plugin makes a fence.
+
 ### C33 — `render: admonitions find their fences through lib/markdown`
 
 **A3-1, second half.** `rewriteAdmonitions` protects fences with its own `stashCodeFences`.
diff --git a/docs/Documentation/Extending.md b/docs/Documentation/Extending.md
index a6ca3aa9..dba69de5 100644
--- a/docs/Documentation/Extending.md
+++ b/docs/Documentation/Extending.md
@@ -647,7 +647,7 @@ The split exists so that an edit confined to `docs/` usually has to pay for `che
 
 Separating 1 from 2 is what stops a broken gate reading as a clean site, and it has to hold at the top level too. End the script with `main().catch((err) => { console.error(err); process.exit(2); })`, the way `check_a11y.mjs` does, so a crash cannot fall through to node's default exit 1 and be mistaken for a finding.
 
-**Say what a pass covered.** Nearly every gate in both wrappers does: `check_dot_fit.mjs` gives the diagram count, `pick_a11y_sample.mjs --check` the sample size and the number of construct families in use, `check_publish_policy.mjs` the probe counts on both sides, `check_code_regions.mjs` the number of files swept and the number whose code regions moved, `check_a11y.mjs` the page × theme × viewport product it audited. A gate silent on success says nothing about whether it examined anything, which is the state a gate that has quietly stopped working also reports.
+**Say what a pass covered.** Nearly every gate in both wrappers does: `check_dot_fit.mjs` gives the diagram count, `pick_a11y_sample.mjs --check` the sample size and the number of construct families in use, `check_publish_policy.mjs` the probe counts on both sides, `check_code_regions.mjs` the number of files swept, the number whose code regions moved and the number of fences found, `check_a11y.mjs` the page × theme × viewport product it audited. A gate silent on success says nothing about whether it examined anything, which is the state a gate that has quietly stopped working also reports.
 
 **Name the artifact and the remedy.** A gate's output is read by someone who was in the middle of something else. `check_dot_fit.mjs` names the failing diagram, then `builder/dot-metrics.mjs` and an `@hpcc-js/wasm-graphviz` bump as the usual cause, then `build.bat` as the fix. `check_tree_fresh.mjs` names the source file that is newer than the tree and says to run `build.bat`. `pick_a11y_sample.mjs --check` names the uncovered construct *and* the cheapest page that would cover it.
 
diff --git a/docs/Documentation/Tools.md b/docs/Documentation/Tools.md
index 062c44a7..82ed3519 100644
--- a/docs/Documentation/Tools.md
+++ b/docs/Documentation/Tools.md
@@ -72,7 +72,7 @@ The tests the toolchain has to pass. Ten steps, each stopping the run if it fail
 3. [`scripts/check_ci_workflows.mjs`](#check-ci-workflows) --- verifies both CI workflows run the gates the wrappers run, and build as `build.bat` does.
 4. [`scripts/check_lint.mjs`](#check-lint) --- runs Biome over the tooling and fails on any finding, warnings included.
 5. [`scripts/check_regex_safety.mjs`](#check-regex-safety) --- refuses a regex that can backtrack exponentially, written as a literal or built from constants.
-6. [`scripts/check_code_regions.mjs`](#check-code-regions) --- verifies no pre-render rewrite alters the contents of a code fence or code span.
+6. [`scripts/check_code_regions.mjs`](#check-code-regions) --- verifies no pre-render rewrite alters the contents of a code fence or code span, and that `lib/markdown.mjs` and `lib/frontmatter.mjs` pass their probes.
 7. [`scripts/check_page_baseline.mjs`](#check-page-baseline) --- verifies the page-count drift guard still refuses a fall.
 8. [`scripts/check_book_coverage.mjs`](#check-book-coverage) --- verifies the build still warns about a page `docs/_book.yml` does not mention.
 9. [`scripts/check_symbol_index.mjs`](#check-symbol-index) --- verifies the symbol index still places each kind of symbol, and its drift guard still refuses a lost URL.
@@ -425,9 +425,11 @@ Probes ride along in the normal run, each a defect this repository actually ship
 
 The admonition probes test the mirror fault, which the region comparison structurally cannot see: **a rewrite that misreads what is code can also fail to fire on real prose**, and the regions still come back identical because the text was only stashed and restored. `Reference/Attributes.md` shipped all six of its admonitions as the literal text `[!NOTE]` for exactly that reason --- a `[Description(...)]` sample whose argument is a Markdown string containing two fence markers as twinBASIC string literals, which the fence stasher closed the surrounding fence on. Every pairing after it was off by one.
 
+It is also the gate on `lib/markdown.mjs` and `lib/frontmatter.mjs`, the modules that tell the tools what in a page is code and where its frontmatter ends. Their probes run with the others, and on every page the sweep checks that `blockRegions`, which parses blocks only, finds exactly the fences, code blocks and HTML blocks of a full parse. The summary line gives the number of fences that full parse found.
+
 `--verbose` prints the first few altered regions of each failing file, before and after. `--self-test` replaces the normal run rather than adding to it, so neither the probes nor the sweep runs: it de-indents the body of one small fence by hand and passes only if the comparison notices. That proves the comparator can still see a change, and nothing more --- it runs no rewrite at all.
 
-Exits 1 when a code region differs, when a probe's admonition is not rewritten, or when `--self-test`'s de-indent goes unnoticed, and 2 when the gate itself cannot run. [When `test.bat` fails in `check_code_regions`](Extending#code-regions-altered) says what to change.
+Exits 1 when a code region differs, when a probe's admonition is not rewritten, when a module probe fails or the two parses disagree on a page, or when `--self-test`'s de-indent goes unnoticed, and 2 when the gate itself cannot run. [When `test.bat` fails in `check_code_regions`](Extending#code-regions-altered) says what to change.
 
 ### check_gate_lists.mjs
 {: #check-gate-lists }
diff --git a/lib/README.md b/lib/README.md
index 88cff30e..5b097cd1 100644
--- a/lib/README.md
+++ b/lib/README.md
@@ -10,6 +10,15 @@ The folder exists because `builder/` may not import `scripts/`, which
 [markdown-files.mjs](markdown-files.mjs) is the first: it walks `docs/` for its
 pages and decides which folders there are the build's output trees.
 
+[markdown.mjs](markdown.mjs) says what in a page's source is code, from a
+markdown-it block parse: every fence, indented code block and HTML block with
+its lines, a mask that hides the code from a rewrite and restores it, the code
+spans on a line, sections split on a marker line outside any code, and a line
+map that keeps each line's ending. [frontmatter.mjs](frontmatter.mjs) splits
+off a page's YAML frontmatter and parses it with the `js-yaml` the rest of the
+tooling uses. `scripts/check_code_regions.mjs` carries the probes for both, and
+checks on every page that the block parse finds what a full parse finds.
+
 `scripts/check_tree_fresh.mjs` counts `lib/` among the inputs that decide the
 built bytes, beside `docs/` and `builder/`, so an edit here marks every built
 tree stale, and `check.bat` and `book.bat` refuse it until the next build.
diff --git a/lib/frontmatter.mjs b/lib/frontmatter.mjs
new file mode 100644
index 00000000..ec93e584
--- /dev/null
+++ b/lib/frontmatter.mjs
@@ -0,0 +1,61 @@
+// A page's YAML frontmatter, split off and parsed with the one YAML library the
+// rest of the tooling uses.
+//
+// markdown-it knows nothing of frontmatter and misreads it -- the opening `---`
+// as a rule, and the YAML up to the closing `---` as a setext heading -- so it
+// has to come off before any parse. gray-matter did this for the build, with a
+// js-yaml 3 of its own inside it, while the site configuration went through the
+// js-yaml 4 installed beside it.
+
+import yaml from "js-yaml";
+
+const DELIMITER_RE = /^---[ \t]*$/;
+
+/**
+ * Split `raw` into its frontmatter and the rest. Returns `{ data, content }`,
+ * or null when `raw` does not start with a frontmatter block.
+ *
+ * A block opens on the first line, which is `---`, and closes at the next line
+ * that is `---`; either may carry trailing spaces or tabs. A leading BOM is
+ * dropped first: editors on Windows add one unasked, and a page whose `---`
+ * sits behind it was once published as a static file, raw markdown and all.
+ *
+ * `data` is the block parsed as YAML, or `{}` for an empty block or one of only
+ * comments. `content` is everything after the closing line's ending, with its
+ * bytes untouched, CRLF included.
+ *
+ * Throws when the block is never closed, when its YAML does not parse, or when
+ * it parses to something other than a mapping. A YAML error names the line of
+ * `raw` it is on, counting the opening `---` as line 1.
+ */
+export function parseFrontmatter(raw) {
+  const text = raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw;
+  let pos = 0;
+  let blockStart = -1;
+  while (pos < text.length) {
+    let end = pos;
+    while (end < text.length && text[end] !== "\n" && text[end] !== "\r") end++;
+    const next = text[end] === "\r" && text[end + 1] === "\n" ? end + 2 : end + 1;
+    const isDelimiter = DELIMITER_RE.test(text.slice(pos, end));
+    if (blockStart < 0) {
+      if (!isDelimiter || end === text.length) return null;
+      blockStart = next;
+    } else if (isDelimiter) {
+      return { data: parseBlock(text.slice(blockStart, pos)), content: text.slice(next) };
+    }
+    pos = next;
+  }
+  if (blockStart < 0) return null;
+  throw new Error("the frontmatter opened on line 1 is never closed by a `---` line");
+}
+
+function parseBlock(block) {
+  // The newline stands in for the opening `---`, so that js-yaml counts lines
+  // from the top of the file.
+  const data = yaml.load(`\n${block}`);
+  if (data == null) return {};
+  if (typeof data !== "object" || Array.isArray(data)) {
+    throw new Error("the frontmatter is not a mapping of keys to values");
+  }
+  return data;
+}
diff --git a/lib/markdown.mjs b/lib/markdown.mjs
new file mode 100644
index 00000000..7b0487f3
--- /dev/null
+++ b/lib/markdown.mjs
@@ -0,0 +1,204 @@
+// What in a markdown source is code, asked of markdown-it rather than of a
+// private regex.
+//
+//     blockRegions(src, { md })        every fence, code block and HTML block, with its lines
+//     maskCode(src, { md, indented })  hide the code, rewrite the prose, restore the code
+//     splitCodeSpans(line)             one line cut into prose and code-span segments
+//     splitOnMarker(src, isMarker)     sections split on a marker line outside any region
+//     mapLines(src, fn)                rewrite each line, keeping its own line ending
+//
+// Every tool that rewrites or scans page source used to decide for itself what
+// was code, and the copies disagreed: one accepted a backtick fence whose info
+// string holds a backtick, which CommonMark refuses, and another split a fenced
+// `---` as though it ended a section. A block parse settles it the way the
+// renderer will.
+//
+// LINES. A line ends at CRLF, LF or a lone CR, as in CommonMark, and every line
+// index here is 0-based. `blockRegions` numbers lines as markdown-it does, and
+// `mapLines` and `splitOnMarker` split the same way, so a region's `start` and
+// `end` index straight into what they see. The source is never normalised on
+// its way back out: `maskCode`'s restore and `mapLines` return every line
+// ending as it came in.
+
+import MarkdownIt from "markdown-it";
+
+let bare;
+
+// A bare CommonMark parser with raw HTML on, for a caller that passes none. A
+// caller whose own parser adds block syntax passes that one instead: the
+// site's definition-list plugin, for one, makes a fence after `: ` a fence.
+function bareParser() {
+  bare ??= new MarkdownIt({ html: true });
+  return bare;
+}
+
+// markdown-it's own `normalize` core rule, which a block-only parse skips.
+// Without it a CRLF line ends in a CR, and a closing fence followed by one is
+// not a closing fence. Neither replacement changes the number of lines.
+const NEWLINES_RE = /\r\n?|\n/g;
+// biome-ignore lint/suspicious/noControlCharactersInRegex: markdown-it replaces NUL, and so must this.
+const NULL_RE = /\u0000/g;
+
+const REGION_TYPES = new Set(["fence", "code_block", "html_block"]);
+
+/**
+ * Every fence, indented code block and HTML block in `src`, in document order.
+ *
+ * Each is `{ type, start, end, markup, info, content }`: `type` is markdown-it's
+ * token type, `start` and `end` a half-open range of 0-based lines, and the
+ * rest the token's own fields. The range includes the lines' blockquote and
+ * list-item prefixes, which `content` has had removed. A fence that is never
+ * closed runs to the end of its container, as in CommonMark.
+ *
+ * The parse is block-only -- inline content is never tokenised -- so a whole
+ * corpus costs tens of milliseconds. Frontmatter is not recognised: markdown-it
+ * reads a leading `---` block as a rule and a setext heading, which holds no
+ * region unless the YAML has an indented line after a blank one.
+ */
+export function blockRegions(src, { md = bareParser() } = {}) {
+  const tokens = [];
+  md.block.parse(src.replace(NEWLINES_RE, "\n").replace(NULL_RE, "\u{FFFD}"), md, {}, tokens);
+  const regions = [];
+  for (const t of tokens) {
+    if (!REGION_TYPES.has(t.type)) continue;
+    regions.push({
+      type: t.type, start: t.map[0], end: t.map[1], markup: t.markup, info: t.info, content: t.content,
+    });
+  }
+  return regions;
+}
+
+// Each line's text and the ending that followed it, which is "" only for a
+// last line with none. An empty source has no lines, and a final line ending
+// starts no line after it: markdown-it counts the same way.
+function splitLines(src) {
+  const lines = [];
+  let i = 0;
+  while (i < src.length) {
+    let j = i;
+    while (j < src.length && src[j] !== "\n" && src[j] !== "\r") j++;
+    const eol = src[j] === "\r" && src[j + 1] === "\n" ? "\r\n" : src.slice(j, j + 1);
+    lines.push({ text: src.slice(i, j), eol });
+    i = j + eol.length;
+  }
+  return lines;
+}
+
+/** `fn(text, index)` for every line, rejoined with each line's own ending. */
+export function mapLines(src, fn) {
+  return splitLines(src).map(({ text, eol }, i) => fn(text, i) + eol).join("");
+}
+
+/**
+ * Cut one line into `{ code, text }` segments that rejoin to the line.
+ *
+ * A code span is a run of N backticks, the shortest possible content, then a
+ * run of exactly N backticks, so ``a `b` c`` is one span. A run with no
+ * partner is literal text, as in CommonMark. Only backticks: a code span
+ * cannot be written with tildes.
+ *
+ * markdown-it cannot supply this, because an inline token has no offset into
+ * its line. Two things CommonMark allows are not followed. A span that
+ * continues onto the next line is not seen, since the scan is per line. And a
+ * backslash before a backtick does not stop it opening a span: in
+ * `` \`a `b` `` the scan pairs the escaped backtick with the one before `b`.
+ */
+export function splitCodeSpans(line) {
+  const parts = [];
+  let buf = "";
+  let k = 0;
+  while (k < line.length) {
+    if (line[k] !== "`") { buf += line[k++]; continue; }
+    let n = 0;
+    while (line[k + n] === "`") n++;
+    let p = k + n;
+    let found = -1;
+    while (p < line.length) {
+      if (line[p] === "`") {
+        let m = 0;
+        while (line[p + m] === "`") m++;
+        if (m === n) { found = p; break; }
+        p += m;
+      } else p++;
+    }
+    if (found < 0) { buf += line.slice(k, k + n); k += n; continue; }
+    if (buf) { parts.push({ code: false, text: buf }); buf = ""; }
+    parts.push({ code: true, text: line.slice(k, found + n) });
+    k = found + n;
+  }
+  if (buf) parts.push({ code: false, text: buf });
+  return parts;
+}
+
+// NUL delimits a placeholder because page text never holds one: markdown-it
+// replaces it. The backticks around it are deliberate -- see maskCode.
+const placeholder = (n) => `\`\u0000CM${n}\u0000\``;
+// biome-ignore lint/suspicious/noControlCharactersInRegex: NUL delimits the placeholders because page text never contains one.
+const PLACEHOLDER_RE = /`\u0000CM(\d+)\u0000`/g;
+
+/**
+ * Hide every fence and code span in `src` behind a placeholder, so a rewrite of
+ * the prose cannot reach the code. Returns `{ masked, restore }`; `restore`
+ * puts the code back into a rewritten `masked`, and `restore(masked)` is `src`.
+ *
+ * A fence is masked whole, its lines' blockquote and list prefixes included,
+ * as one line that starts with a backtick. So a rewrite that decides what a
+ * line is from its first character reads it as it read the fence's own lines:
+ * never a paragraph, a list item or a blockquote. Code spans are masked on
+ * every line outside a masked block, HTML blocks included.
+ *
+ * `indented: true` masks indented code blocks as well. It is off by default
+ * because the site's pre-render rewrites have never masked them, and turning it
+ * on changes what they may rewrite.
+ */
+export function maskCode(src, { md, indented = false } = {}) {
+  const stash = [];
+  const lines = splitLines(src);
+  const regions = blockRegions(src, { md })
+    .filter((r) => r.type === "fence" || (indented && r.type === "code_block"));
+  const out = [];
+  let r = 0;
+  for (let i = 0; i < lines.length;) {
+    const region = regions[r];
+    if (region?.start === i) {
+      const block = lines.slice(region.start, region.end);
+      const last = block.pop();
+      stash.push(block.map((l) => l.text + l.eol).join("") + last.text);
+      out.push(placeholder(stash.length - 1) + last.eol);
+      i = region.end;
+      r++;
+      continue;
+    }
+    const spans = splitCodeSpans(lines[i].text).map(({ code, text }) => {
+      if (!code) return text;
+      stash.push(text);
+      return placeholder(stash.length - 1);
+    });
+    out.push(spans.join("") + lines[i].eol);
+    i++;
+  }
+  return {
+    masked: out.join(""),
+    restore: (s) => s.replace(PLACEHOLDER_RE, (_, n) => stash[Number(n)] ?? ""),
+  };
+}
+
+/**
+ * Split `src` into sections at every line for which `isMarker(text, index)` is
+ * true, except a line inside a fence, code block or HTML block. Returns
+ * `{ marker, start, lines }[]`: the first section is whatever precedes the
+ * first marker, with `marker` null and `start` 0; each other has the marker
+ * line's text and 0-based index, and `lines` the lines after it, up to the next
+ * marker. Line endings are not kept.
+ */
+export function splitOnMarker(src, isMarker, { md } = {}) {
+  const lines = splitLines(src).map((l) => l.text);
+  const inRegion = new Uint8Array(lines.length);
+  for (const r of blockRegions(src, { md })) inRegion.fill(1, r.start, r.end);
+  const sections = [{ marker: null, start: 0, lines: [] }];
+  for (let i = 0; i < lines.length; i++) {
+    if (!inRegion[i] && isMarker(lines[i], i)) sections.push({ marker: lines[i], start: i, lines: [] });
+    else sections[sections.length - 1].lines.push(lines[i]);
+  }
+  return sections;
+}
diff --git a/scripts/check_code_regions.mjs b/scripts/check_code_regions.mjs
index 3b46f3e3..1f14ba1e 100644
--- a/scripts/check_code_regions.mjs
+++ b/scripts/check_code_regions.mjs
@@ -58,13 +58,25 @@
 // contains a backtick -- and markdown-it does not build a code span inside that
 // context anyway, so there is no code region there to damage today. If a page
 // ever does put code inside raw HTML, this gate will not speak up.
+//
+// THE MODULES
+//
+// It is also the gate on lib/markdown.mjs and lib/frontmatter.mjs, which the
+// tools ask what in a page is code and where its frontmatter ends. Their
+// probes ride along too, and the sweep checks on every page that
+// blockRegions, which parses blocks only, finds exactly the fences, code
+// blocks and HTML blocks of the full parse the comparison already makes.
 
+import assert from "node:assert/strict";
 import { promises as fs } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 import MarkdownIt from "markdown-it";
+import deflist from "markdown-it-deflist";
 import { applyPreRenderRewrites } from "../builder/render.mjs";
+import { parseFrontmatter } from "../lib/frontmatter.mjs";
+import { blockRegions, mapLines, maskCode, splitCodeSpans, splitOnMarker } from "../lib/markdown.mjs";
 import { markdownFiles } from "../lib/markdown-files.mjs";
 
 const REPO = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
@@ -89,6 +101,12 @@ function codeRegions(src) {
   return out;
 }
 
+// The block regions of a full parse, in the form regionsOf gives blockRegions'.
+const REGION_TYPES = new Set(["fence", "code_block", "html_block"]);
+function parsedRegions(src) {
+  return md.parse(src, {}).filter((t) => REGION_TYPES.has(t.type)).map((t) => `${t.type} ${t.map[0]}-${t.map[1]}`);
+}
+
 // The real chain, imported from render.mjs rather than reconstructed here.
 // That is what makes this gate mean something: unmasking any one of the
 // rewrites changes what this function does, and the comparison below sees it.
@@ -164,6 +182,107 @@ const ADMONITION_PROBES = [
     "prose\n\n~~~markdown\nsample\n```\n~~~\n\n> [!NOTE]\n> body\n\n```tb\nDim y\n```\n"],
 ];
 
+// The regions blockRegions reports, in a form assert can compare at a glance.
+const regionsOf = (src, options) => blockRegions(src, options).map((r) => `${r.type} ${r.start}-${r.end}`);
+
+// A line's code-span segments, code in braces, segments joined by "|".
+const spansOf = (line) => splitCodeSpans(line).map((s) => (s.code ? `{${s.text}}` : s.text)).join("|");
+
+// One per shape the scanner has to get right: an empty line, none, runs of one,
+// two and four, an unmatched run, runs of another length inside a span, spans
+// side by side and at either end of the line, and three lengths on one line.
+const CODE_SPAN_CASES = [
+  ["", ""],
+  ["no backticks here", "no backticks here"],
+  ["a `b` c", "a |{`b`}| c"],
+  ["``a ` b``", "{``a ` b``}"],
+  ["x ````y```` z", "x |{````y````}| z"],
+  ["a ` b", "a ` b"],
+  ["`a``b`", "{`a``b`}"],
+  ["``a`b``", "{``a`b``}"],
+  ["`a` `b`", "{`a`}| |{`b`}"],
+  ["`a`x`b`", "{`a`}|x|{`b`}"],
+  ["`x` at the start", "{`x`}| at the start"],
+  ["at the end `x`", "at the end |{`x`}"],
+  ["``", "``"],
+  ["` `", "{` `}"],
+  ["``a`", "``a`"],
+  ["`a` ``b`` ```c```", "{`a`}| |{``b``}| |{```c```}"],
+];
+
+// Each probe throws an assert.AssertionError when the module answers wrongly.
+const MODULE_PROBES = [
+  // A3-1. CommonMark refuses a backtick in a backtick fence's info string, so
+  // this opens no fence and the admonition is prose. maskCodeRegions masked it
+  // as a fence while stashCodeFences did not, so one rewrite saw code where
+  // the next saw prose.
+  ["a backtick in a backtick fence's info string opens no fence", () => {
+    const src = "```abc`def\n> [!NOTE]\n> body\n";
+    assert.deepEqual(regionsOf(src), []);
+    assert.equal(maskCode(src).masked, src);
+    assert.deepEqual(regionsOf("~~~abc`def\nx\n~~~\n"), ["fence 0-3"]);
+  }],
+  ["a fence inside a blockquote is masked whole, markers and all", () => {
+    const src = "> text\n> ```tb\n> *** x ***\n> ```\n";
+    assert.deepEqual(regionsOf(src), ["fence 1-4"]);
+    const { masked, restore } = maskCode(src);
+    assert.equal(masked, "> text\n`\u0000CM0\u0000`\n");
+    assert.equal(restore(masked), src);
+  }],
+  ["a fence inside a list item, and inside a blockquote inside one", () => {
+    assert.deepEqual(regionsOf("- item\n\n  ```tb\n  x\n  ```\n"), ["fence 2-5"]);
+    assert.deepEqual(regionsOf("- item\n\n  > ```tb\n  > x\n  > ```\n"), ["fence 2-5"]);
+  }],
+  ["an indented code block is masked only when asked", () => {
+    const src = "text\n\n    *** x ***\n";
+    assert.deepEqual(regionsOf(src), ["code_block 2-3"]);
+    assert.equal(maskCode(src).masked, src);
+    assert.equal(maskCode(src, { indented: true }).masked, "text\n\n`\u0000CM0\u0000`\n");
+  }],
+  ["the parser a caller passes decides what is a block", () => {
+    // Only a parser with the site's definition-list plugin sees a fence after
+    // `: `. A bare one reads the closing marker as an opener instead.
+    const src = "Term\n: ```tb\n  x\n  ```\n";
+    assert.deepEqual(regionsOf(src), ["fence 3-4"]);
+    assert.deepEqual(regionsOf(src, { md: new MarkdownIt({ html: true }).use(deflist) }), ["fence 1-4"]);
+  }],
+  ["code spans: sixteen shapes", () => {
+    for (const [line, want] of CODE_SPAN_CASES) assert.equal(spansOf(line), want, JSON.stringify(line));
+  }],
+  ["CRLF and lone CR line endings come back as they went in", () => {
+    const src = "a\r\n\r\n```tb\r\n*** x ***\r\n```\r\nb `c` d\r\n";
+    assert.deepEqual(regionsOf(src), ["fence 2-5"]);
+    const { masked, restore } = maskCode(src);
+    assert.equal(masked, "a\r\n\r\n`\u0000CM0\u0000`\r\nb `\u0000CM1\u0000` d\r\n");
+    assert.equal(restore(masked), src);
+    assert.equal(mapLines("a\r\nb\nc\rd", (s) => s.toUpperCase()), "A\r\nB\nC\rD");
+    assert.deepEqual(regionsOf("x\r```tb\ry\r```\rz"), ["fence 1-4"]);
+  }],
+  ["a fenced --- does not start a section", () => {
+    const src = "top\n---\n```yaml\nk: v\n---\n```\ntail\n";
+    assert.deepEqual(splitOnMarker(src, (line) => line === "---"), [
+      { marker: null, start: 0, lines: ["top"] },
+      { marker: "---", start: 1, lines: ["```yaml", "k: v", "---", "```", "tail"] },
+    ]);
+  }],
+  ["frontmatter that markdown-it would read as a heading", () => {
+    const src = "---\ntitle: X\npermalink: /y\n---\n\n# Heading\n";
+    assert.deepEqual(parseFrontmatter(src), { data: { title: "X", permalink: "/y" }, content: "\n# Heading\n" });
+  }],
+  ["frontmatter behind a BOM, and content with CRLF endings", () => {
+    assert.deepEqual(parseFrontmatter("\u{FEFF}---\ntitle: X\n---\nbody\n"), { data: { title: "X" }, content: "body\n" });
+    assert.deepEqual(parseFrontmatter("---\r\ntitle: X\r\n---\r\nbody\r\n"), { data: { title: "X" }, content: "body\r\n" });
+    assert.deepEqual(parseFrontmatter("---\n# only a comment\n---\n"), { data: {}, content: "" });
+  }],
+  ["what is not frontmatter, and what is broken frontmatter", () => {
+    assert.equal(parseFrontmatter("----\nx: 1\n----\n"), null);
+    assert.equal(parseFrontmatter("text\n---\nx: 1\n---\n"), null);
+    assert.throws(() => parseFrontmatter("---\nx: 1\n"), /never closed/);
+    assert.throws(() => parseFrontmatter("---\n- a list\n---\n"), /not a mapping/);
+    assert.throws(() => parseFrontmatter("---\nok: 1\nbad: [\n---\n"), /\(4:1\)/);
+  }],
+];
+
 async function main(argv) {
   const verbose = argv.includes("--verbose");
 
@@ -197,16 +316,41 @@ async function main(argv) {
     console.log(`        the admonition was not rewritten -- the fence stasher`);
     console.log(`        mistook the prose around it for code`);
   }
+  // Anything but a failed assertion is the gate breaking, and goes to exit 2.
+  for (const [name, probe] of MODULE_PROBES) {
+    try {
+      probe();
+    } catch (err) {
+      if (!(err instanceof assert.AssertionError)) throw err;
+      failed++;
+      console.log(`FAIL  probe: ${name}`);
+      for (const line of err.message.split("\n")) console.log(`        ${line}`);
+    }
+  }
 
   if (!failed) {
     console.log(`ok    ${PROBES.length} probes: no rewrite alters a code region`);
     console.log(`ok    ${ADMONITION_PROBES.length} probes: a rewrite still fires on prose beside code`);
+    console.log(`ok    ${MODULE_PROBES.length} probes: lib/markdown.mjs and lib/frontmatter.mjs`);
   }
 
   const files = await markdownFiles(ROOT);
   let touched = 0;
+  let fences = 0;
   for (const rel of files) {
     const src = await fs.readFile(path.join(ROOT, rel), "utf8");
+    const parsed = parsedRegions(src);
+    const found = regionsOf(src);
+    fences += parsed.filter((r) => r.startsWith("fence ")).length;
+    if (found.join("\n") !== parsed.join("\n")) {
+      failed++;
+      console.log(`FAIL  ${rel}: blockRegions finds ${found.length} region(s), the full parse ${parsed.length}`);
+      if (verbose) {
+        let i = 0;
+        while (i < found.length && found[i] === parsed[i]) i++;
+        console.log(`        first difference: ${found[i] ?? "none"} against ${parsed[i] ?? "none"}`);
+      }
+    }
     const findings = compare(src);
     if (!findings.length) continue;
     touched++;
@@ -221,8 +365,8 @@ async function main(argv) {
   }
 
   console.log(
-    `check_code_regions: ${files.length} file(s), ${touched} with altered code regions`
-    + (failed ? "" : " -- clean"),
+    `check_code_regions: ${files.length} file(s), ${touched} with altered code regions,`
+    + ` ${fences} fence(s) in the full parse` + (failed ? "" : " -- clean"),
   );
   process.exit(failed ? 1 : 0);
 }

From ed7aff2cf76e69bcb6f86d98c4556da74fba5926 Mon Sep 17 00:00:00 2001
From: Kuba Sunderland-Ober <kuba@mareimbrium.org>
Date: Sun, 27 Sep 2026 13:39:45 +0200
Subject: [PATCH 03/27] render: the pre-render rewrites ask lib/markdown what
 is code

---
 WIP.Build.md                          |  23 +++--
 WIP.ExamplesBuild.md                  |   5 +-
 WIP.md                                |   2 +-
 builder/PLAN-TOOLING-REVIEW.md        |  40 ++++++++
 builder/README.md                     |   2 +-
 builder/counts.mjs                    |  23 +++--
 builder/render.mjs                    | 138 ++++++--------------------
 builder/tbdocs.mjs                    |  17 ++--
 docs/Documentation/Authoring.md       |   2 +-
 docs/Documentation/Extending.md       |   7 +-
 docs/Documentation/Pipeline-Stages.md |   7 +-
 eval/usecases.md                      |   2 +-
 scripts/check_code_regions.mjs        |  34 +++++--
 scripts/check_examples.mjs            |   9 +-
 scripts/lib/tb-fences.mjs             |   5 +-
 15 files changed, 152 insertions(+), 164 deletions(-)

diff --git a/WIP.Build.md b/WIP.Build.md
index 3b8d47e6..170aa1b6 100644
--- a/WIP.Build.md
+++ b/WIP.Build.md
@@ -286,24 +286,25 @@ that accident.**
 Two mechanisms now exist, and a new rewrite must use one of them:
 
 - **Source rewrites** go inside `applyPreRenderRewrites` in
-  [builder/render.mjs](builder/render.mjs), between `maskCodeRegions` and its
-  `restore`. The mask hides fenced blocks (backtick or tilde, any length) and
-  inline code spans (any backtick-run length).
+  [builder/render.mjs](builder/render.mjs), between `maskCode` and its
+  `restore`. `maskCode` lives in [lib/markdown.mjs](lib/markdown.mjs) and masks
+  every fence the site's parser finds --- including one inside a blockquote or
+  admonition, inside a list item, or one the definition-list plugin makes after
+  `: ` --- plus every inline code span.
 - **Rendered-HTML rewrites** use `replaceOutsideCode` in
   [builder/book.mjs](builder/book.mjs), or the same leading-alternation shape
   found in `offline-rewrite.mjs:299`, `pdf.mjs:138` and `book.mjs`'s
   `IMG_SRC_RE_BOOK`, which consume `<code>` and `<pre>` atomically.
 
-**One gap is deliberate and stated rather than hidden:** `maskCodeRegions` does
-not protect **indented** (4-space) code blocks, because telling one from a
-list-item continuation needs block context a pre-render pass does not have, and
-guessing would change how real list content renders. `check_code_regions.mjs`
+**One gap is deliberate and stated rather than hidden:** the chain does not
+mask **indented** (4-space) code blocks, since it calls `maskCode` without
+`indented: true`. `check_code_regions.mjs`
 *does* compare them, so a rewrite that damages one is reported --- and must be
 fixed at the rewrite, not by widening the mask.
 
-`rewriteAdmonitions` deliberately runs **outside** the mask. A fence inside an
-admonition still carries its `> ` markers at that point, so the mask does not
-see it as a fence, and the admonition rewrite is what strips those markers.
+`rewriteAdmonitions` deliberately runs **outside** the mask. It finds an
+admonition's lines by their `>` markers and strips them, and a masked fence
+inside an admonition takes its markers with it into the stash.
 
 ### Whitespace inside inline code is content
 
@@ -420,7 +421,7 @@ node scripts/check_code_regions.mjs --self-test
 
 Two details are load-bearing. **It imports the chain rather than reconstructing
 it**, so removing the mask from one rewrite changes what the gate runs and is
-caught --- a gate that exercised `maskCodeRegions` alone would have passed. And
+caught --- a gate that exercised `maskCode` alone would have passed. And
 **its seven probes ride along in the normal run**, each a defect this repository
 actually shipped, because the corpus is clean: a sweep that finds nothing is
 otherwise indistinguishable from a gate that has stopped detecting. Verified by
diff --git a/WIP.ExamplesBuild.md b/WIP.ExamplesBuild.md
index 50ec527c..f512da23 100644
--- a/WIP.ExamplesBuild.md
+++ b/WIP.ExamplesBuild.md
@@ -117,7 +117,7 @@ that ride along on every run:
 | property | result |
 |---|---|
 | a marked fence renders byte-identical HTML to a plain one | **true** |
-| `maskCodeRegions` still hides the body | **true** |
+| `maskCode` still hides the body | **true** |
 | the mask round-trips the marked fence | **true** |
 | `applyPreRenderRewrites` leaves it byte-identical | **true** |
 
@@ -129,7 +129,8 @@ Shape --- bare flags and `key=value` pairs after the language token:
     ```tb check_build slot=module id=getobject-1
 
 **No backticks in it.** CommonMark forbids them in a backtick fence's info string, and
-`maskCodeRegions` skips such a fence outright.
+markdown-it reads such a line as prose rather than as a fence, so the sample would not be
+a fence at all.
 
 | token | meaning | default |
 |---|---|---|
diff --git a/WIP.md b/WIP.md
index 0f1ddc25..ec984672 100644
--- a/WIP.md
+++ b/WIP.md
@@ -576,7 +576,7 @@ they are.
 - **Don't hand-edit a diagram's `.svg`, and don't change its `font-family` anywhere but the `.dot`.** The `.svg` is a build artifact; the next build overwrites it. More to the point, Graphviz sizes every box to the text *it* measured, so a face the layout never saw leaves labels hanging outside their boxes --- which is exactly how 27 labels shipped that way across three diagrams. Edit the `.dot`, rebuild, and let `node scripts/check_dot_fit.mjs` confirm it; see [Diagrams](WIP.Typography.md#diagrams).
 - **Don't add a `@font-face` to `docs/_sass/custom/_fonts.scss` without also adding the stack to `modules-dark.scss`,** and don't move the `@font-face` block out of the `emit-font-faces` mixin. The dark compilation re-emits its whole payload under two selectors at raised specificity: a face declared there would be invalid, and a stack left out there applies in light mode and silently does not in dark.
 - **Don't widen `SOURCE_EXTENSIONS` in [builder/publish-policy.mjs](builder/publish-policy.mjs) to make a build pass.** The build refusing a file is the gate working. Remove the file from `docs/`, or add a pattern to `exclude:` in `_config.yml`; widen the allowlist only when the type genuinely belongs on the published site, and never by folding `BUILD_EXTENSIONS` into it. See [The publish allowlist](WIP.Build.md#the-publish-allowlist).
-- **Don't add a rewrite over markdown source or rendered HTML without a code guard.** A pre-render source rewrite goes inside `applyPreRenderRewrites`, between `maskCodeRegions` and its `restore`; a rendered-HTML rewrite uses `replaceOutsideCode` or the `<code>`/`<pre>` leading-alternation shape. Four rewrites shipped without one and corrupted real code samples, including control-flow indentation in a language reference and six code spans in the published PDF. `node scripts/check_code_regions.mjs` is the gate. See [Never rewrite markdown source without knowing what is code](WIP.Build.md#never-rewrite-markdown-source-without-knowing-what-is-code).
+- **Don't add a rewrite over markdown source or rendered HTML without a code guard.** A pre-render source rewrite goes inside `applyPreRenderRewrites`, between `maskCode` and its `restore`; a rendered-HTML rewrite uses `replaceOutsideCode` or the `<code>`/`<pre>` leading-alternation shape. Four rewrites shipped without one and corrupted real code samples, including control-flow indentation in a language reference and six code spans in the published PDF. `node scripts/check_code_regions.mjs` is the gate. See [Never rewrite markdown source without knowing what is code](WIP.Build.md#never-rewrite-markdown-source-without-knowing-what-is-code).
 - Don't invent semantics — read the relevant primary source before paraphrasing (VBA-Docs for VBA-derived pages; the package's `.twin` sources for twinBASIC-specific ones).
 - Don't add boilerplate sections (Remarks, See Also) if the source has nothing meaningful for them.
 - **Never add `Co-Authored-By:` (or any "Co-authored by" / "Generated with Claude" / similar) trailers to commit messages.** Repository policy. Plain commit messages only.
diff --git a/builder/PLAN-TOOLING-REVIEW.md b/builder/PLAN-TOOLING-REVIEW.md
index 28bb32d2..39442ec3 100644
--- a/builder/PLAN-TOOLING-REVIEW.md
+++ b/builder/PLAN-TOOLING-REVIEW.md
@@ -646,6 +646,46 @@ settle. `applyPreRenderRewrites` takes no parser today, so it needs one to pass
 And `check_code_regions.mjs` calls it: with the bare parser by default, the gate would mask
 differently from the build wherever the definition-list plugin makes a fence.
 
+**Landed.** `applyPreRenderRewrites(rawContent, md)` masks with `maskCode(source, { md })`
+and throws a `TypeError` when given no parser, so no caller can mask differently from the
+build without noticing; `renderPage` passes the site's. `maskCodeRegions` and
+`maskInlineCode` are gone. `findCountRefs(rawContent, md)` and `validateCountNames(pages,
+counts, md)` mask the same way, so `counts.mjs` no longer imports `render.mjs` and the
+circular import between them is gone; `tbdocs.mjs` now creates the site's parser before it
+validates the count names. `check_code_regions.mjs` builds the site's parser with
+`createMarkdownIt` and passes it to the chain, which settles the entry's question, and gains
+`UNCHANGED_PROBES`: sources the chain must return byte for byte, one so far, a fence the
+definition-list plugin makes. That probe had to be a direct comparison. The region
+comparison parses bare, finds no fence there, and so never sees the fence's body rewritten.
+`check_examples.mjs`'s markup probe masks with `maskCode`. At the owner's request,
+`encodeSpacesInMediaUrls`' comment, stranded above `applyPreRenderRewrites`, went back above
+its function. Citations of the old mask are updated in `builder/README.md`, WIP.md,
+WIP.Build.md, WIP.ExamplesBuild.md, Extending, Authoring, Pipeline-Stages,
+`eval/usecases.md` and `scripts/lib/tb-fences.mjs`; two of those said the old mask skipped a
+fence whose info string holds a backtick, which A3-1 shows it did not. The comment above
+`stashCodeFences` still names `maskCodeRegions`; C33 deletes it.
+
+For later entries: the region comparison cannot see a code region that only the site's
+parser finds, so a probe for one compares the chain's output directly. With the mask taken
+out of the chain altogether, the corpus sweep still reports no page altered; today only the
+probes catch that fault.
+
+**Verify.** Before the citation edits the tree comparison was identical (1,461 files online,
+1,457 offline, 137 pdf), the seven admonition-fence pages included, so the entry's reasoning
+now has a measurement behind it. After them it differs only in Authoring, Extending and
+Pipeline-Stages online and offline, the search data, and `book.html`.
+`check_code_regions.mjs`: `912 file(s), 0 with altered code regions, 1372 fence(s) in the
+full parse -- clean`, with 7, 5, 1 and 11 probes. Three faults each fail it with exit 1: the
+gate passing its bare parser to the chain and the mask ignoring the parser it is given both
+fail the new probe, and the chain rewriting unmasked source fails three fence probes and the
+new one. `check_examples.mjs --census` runs the markup probe: `ok 119 probes`. From a
+scratch page, the count validator ignores a name in a fence, in a code span and in a
+definition-list fence, and reports one in prose.
+
+Found: the line `validateCountNames` reports is a line of the masked content after the
+frontmatter, not of the file: `x.md:5` for a name on line 12, below three lines of
+frontmatter and a five-line fence. C32 keeps that number, and C32a fixes it.
+
 ### C33 — `render: admonitions find their fences through lib/markdown`
 
 **A3-1, second half.** `rewriteAdmonitions` protects fences with its own `stashCodeFences`.
diff --git a/builder/README.md b/builder/README.md
index b0d9e5c8..4ec00cd4 100644
--- a/builder/README.md
+++ b/builder/README.md
@@ -158,7 +158,7 @@ patterns too, so assembling one from string constants is not an escape.
 refuses a pre-render rewrite that alters the contents of a code fence or
 code span, which four rewrites in [render.mjs](render.mjs) have done ---
 so a new one belongs inside `applyPreRenderRewrites`, between
-`maskCodeRegions` and its `restore`.
+`maskCode` and its `restore`.
 [Tools and Scripts](https://docs.twinbasic.com/Documentation/Development/Tools)
 lists every gate in both wrappers, in running order.
 
diff --git a/builder/counts.mjs b/builder/counts.mjs
index 0488e407..b86c0fd2 100644
--- a/builder/counts.mjs
+++ b/builder/counts.mjs
@@ -54,9 +54,9 @@
 // route; a placeholder rendering as empty is worse. Both abort the build, and
 // it takes two checks rather than one because they fail differently:
 //
-//   - `validateCountNames` scans the source, with code regions masked by the
-//     renderer's own `maskCodeRegions`, and rejects an unknown name. This is
-//     the typo case, and it names the file, the line and the nearest match.
+//   - `validateCountNames` scans the source, with code masked as the
+//     pre-render rewrites mask it, and rejects an unknown name. This is the
+//     typo case, and it names the file, the line and the nearest match.
 //   - `assertNoPlaceholders` scans the rendered HTML for a placeholder that
 //     survived, outside `<code>` and `<pre>`. Source validation cannot see
 //     this case: a placeholder inside a raw HTML block has a perfectly good
@@ -65,7 +65,7 @@
 // A name with no uses is fine and is not reported. Names are cheap; the
 // registry is allowed to offer more than the prose currently asks for.
 
-import { maskCodeRegions } from "./render.mjs";
+import { maskCode } from "../lib/markdown.mjs";
 
 export const PLACEHOLDER_RE = /\{\{tbdocs:([A-Za-z][A-Za-z0-9]*)\}\}/g;
 
@@ -231,14 +231,15 @@ function substitute(text, counts) {
 /**
  * Find every `{{tbdocs:...}}` in a page's source that is not inside code.
  *
- * Uses the renderer's own `maskCodeRegions`, so "what is code" has one
- * definition here and in the pre-render rewrites. Without it this would reject
- * the very examples the documentation of this feature has to contain.
+ * Masks code with `maskCode` and the site's parser `md`, as the pre-render
+ * rewrites do, so "what is code" has one definition here and there. Without
+ * it this would reject the very examples the documentation of this feature
+ * has to contain.
  *
  * @returns {{name: string, line: number}[]}
  */
-export function findCountRefs(rawContent) {
-  const { masked } = maskCodeRegions(rawContent.replace(/\r\n?/g, "\n"));
+export function findCountRefs(rawContent, md) {
+  const { masked } = maskCode(rawContent.replace(/\r\n?/g, "\n"), { md });
   const out = [];
   for (const m of masked.matchAll(PLACEHOLDER_RE)) {
     out.push({ name: m[1], line: masked.slice(0, m.index).split("\n").length });
@@ -282,11 +283,11 @@ function editDistance(a, b) {
  *
  * @returns {string[]} one message per bad reference; empty means clean
  */
-export function validateCountNames(pages, counts) {
+export function validateCountNames(pages, counts, md) {
   const names = Object.keys(counts).sort();
   const problems = [];
   for (const p of pages) {
-    for (const { name, line } of findCountRefs(p.rawContent ?? "")) {
+    for (const { name, line } of findCountRefs(p.rawContent ?? "", md)) {
       if (Object.hasOwn(counts, name)) continue;
       const guess = nearest(name, names);
       problems.push(
diff --git a/builder/render.mjs b/builder/render.mjs
index cc3e3727..8f154284 100644
--- a/builder/render.mjs
+++ b/builder/render.mjs
@@ -15,12 +15,8 @@ import attrs from "markdown-it-attrs";
 import deflist from "markdown-it-deflist";
 import footnote from "markdown-it-footnote";
 
+import { maskCode } from "../lib/markdown.mjs";
 import { initHighlighter } from "./highlight.mjs";
-// Circular with counts.mjs, which imports maskCodeRegions from here so that
-// "what is code" has one definition across the pre-render rewrites and the
-// count validator. Safe because both sides export function DECLARATIONS, which
-// are hoisted and bound before either module body runs, and neither calls into
-// the other at module-evaluation time. Verified in both import orders.
 import { countPlugin, findSurvivingPlaceholder } from "./counts.mjs";
 
 export async function renderPhase(pages, site, staticFiles = []) {
@@ -62,7 +58,7 @@ function renderPage(page, md) {
     // consumed by Phase 8. Either way, no markdown rendering happens here.
     return page.rawContent;
   }
-  const source = applyPreRenderRewrites(page.rawContent);
+  const source = applyPreRenderRewrites(page.rawContent, md);
   let html = md.render(source, { page });
   html = normaliseVoidTags(html);
   html = padEmptyCells(html);
@@ -79,21 +75,18 @@ function padEmptyCells(html) {
   return html.replace(/<(t[dh])([^>]*)><\/\1>/g, "<$1$2> </$1>");
 }
 
-// kramdown accepts unescaped spaces inside `![alt](url)` and `[text](url)`
-// URLs; CommonMark / markdown-it does NOT and leaves the source text
-// unparsed. URL-encode spaces inside image and link URL components so
-// markdown-it can parse them the way kramdown would.
-//
-// Only the simple case is handled: a URL that's a plain file path with
-// spaces and NO embedded quotes or parens. Anything trickier (titles,
-// nested parens) gets left alone -- the regex is too coarse to safely
-// rewrite those.
 // The whole pre-render rewrite chain, exactly as renderPage applies it.
 // Exported so scripts/check_code_regions.mjs can gate the real thing rather
 // than a reconstruction of it -- in particular so that removing the mask from
-// one of these rewrites is caught, which a gate that only exercised
-// maskCodeRegions would miss.
-export function applyPreRenderRewrites(rawContent) {
+// one of these rewrites is caught, which a gate that only exercised the mask
+// would miss.
+//
+// `md` is the site's markdown-it instance, and it decides what the mask hides:
+// the definition-list plugin, for one, makes a fence after `: ` that a bare
+// parser reads as a paragraph. Without it the mask would silently differ from
+// the build's, so a call without one throws.
+export function applyPreRenderRewrites(rawContent, md) {
+  if (!md) throw new TypeError("applyPreRenderRewrites: pass the site's markdown-it instance");
   // CommonMark normalises CRLF/CR to LF before block parsing. The rewrites
   // below all rely on LF-only input -- do the normalisation up front so they
   // see consistent line shapes.
@@ -105,105 +98,36 @@ export function applyPreRenderRewrites(rawContent) {
   // `Items[1](a,%20b)`, `' *** banner ***` became `' **_ banner _**`, and a
   // YAML sample ending in `---` had that line DELETED and the entry above it
   // promoted to a heading. Mask the code regions, rewrite, then restore.
-  const code = maskCodeRegions(source);
+  //
+  // The mask hides every fence the parser finds, blockquote and list prefixes
+  // included, and every code span. It does not hide indented code blocks,
+  // which the chain has never masked; check_code_regions.mjs compares them
+  // all the same. Each masked fence becomes one line starting with a backtick,
+  // so absorbTrailingHtmlComments, which will not join a comment to a line that
+  // starts with one, never joins a comment to a fence.
+  const code = maskCode(source, { md });
   let work = code.masked;
   work = rewriteTripleAsteriskEmphasis(work);
   work = encodeSpacesInMediaUrls(work);
   work = rewriteListItemSetextHeadings(work);
   work = absorbTrailingHtmlComments(work);
 
-  // rewriteAdmonitions runs OUTSIDE the mask, and must: a fence inside an
-  // admonition still carries its `> ` markers at this point, so the mask does
-  // not see it as a fence, and the admonition rewrite is what strips those
-  // markers. It does its own code handling.
+  // rewriteAdmonitions runs OUTSIDE the mask, and must: it finds an
+  // admonition's lines by their `> ` markers and strips them, and a masked
+  // fence inside an admonition has taken its markers with it into the stash.
+  // It does its own code handling.
   return rewriteAdmonitions(code.restore(work));
 }
 
-// ---------- code-region mask for the pre-render rewrites --------------------
-//
-// Hides fenced code blocks (backtick or tilde, any fence length) and inline
-// code spans (any backtick-run length) behind opaque placeholders, so a
-// source-level rewrite cannot reach into a code sample.
-//
-// The placeholder is wrapped in backticks deliberately. A masked fence
-// collapses several lines into one, and `absorbTrailingHtmlComments`
-// classifies the PREVIOUS line to decide whether to join a comment to it --
-// its PARAGRAPH_CONTINUATION_RE excludes a line starting with a backtick,
-// which is what a real fence line started with. Keeping that leading
-// backtick keeps the classification identical.
+// kramdown accepts unescaped spaces inside `![alt](url)` and `[text](url)`
+// URLs; CommonMark / markdown-it does NOT and leaves the source text
+// unparsed. URL-encode spaces inside image and link URL components so
+// markdown-it can parse them the way kramdown would.
 //
-// Indented code blocks are NOT masked: telling one from a list-item
-// continuation needs block context that a pre-render pass does not have, and
-// guessing would change how real list content renders. That gap is a known,
-// measured one -- scripts/check_code_regions.mjs covers it.
-// biome-ignore lint/suspicious/noControlCharactersInRegex: NUL delimits the placeholders because page text never contains one.
-const CODE_MASK_RE = /`\u0000CM(\d+)\u0000`/g;
-
-export function maskCodeRegions(src) {
-  const stash = [];
-  const lines = src.split("\n");
-  const out = [];
-  let i = 0;
-
-  while (i < lines.length) {
-    const open = lines[i].match(/^[ \t]{0,3}(`{3,}|~{3,})/);
-    if (open) {
-      const marker = open[1];
-      const fenceChar = marker[0];
-      const block = [lines[i]];
-      let j = i + 1;
-      for (; j < lines.length; j++) {
-        block.push(lines[j]);
-        const close = lines[j].match(/^[ \t]{0,3}(`+|~+)[ \t]*$/);
-        if (close && close[1][0] === fenceChar && close[1].length >= marker.length) {
-          j++;
-          break;
-        }
-      }
-      stash.push(block.join("\n"));
-      out.push(`\`\u0000CM${stash.length - 1}\u0000\``);
-      i = j;
-      continue;
-    }
-    out.push(maskInlineCode(lines[i], stash));
-    i++;
-  }
-
-  return {
-    masked: out.join("\n"),
-    restore: (s) => s.replace(CODE_MASK_RE, (_, n) => stash[Number(n)] ?? ""),
-  };
-}
-
-// A code span is a run of N backticks, the shortest possible content, then a
-// run of exactly N backticks. An unmatched run is literal text in CommonMark
-// and simply never matches here, which is the correct outcome.
-function maskInlineCode(line, stash) {
-  let res = "";
-  let k = 0;
-  while (k < line.length) {
-    if (line[k] !== "`") { res += line[k++]; continue; }
-    let n = 0;
-    while (line[k + n] === "`") n++;
-    const open = k;
-    let p = k + n;
-    let found = -1;
-    while (p < line.length) {
-      if (line[p] === "`") {
-        let m = 0;
-        while (line[p + m] === "`") m++;
-        if (m === n) { found = p; break; }
-        p += m;
-      } else p++;
-    }
-    if (found < 0) { res += line.slice(open, open + n); k = open + n; continue; }
-    stash.push(line.slice(open, found + n));
-    res += `\`\u0000CM${stash.length - 1}\u0000\``;
-    k = found + n;
-  }
-  return res;
-}
-
+// Only the simple case is handled: a URL that's a plain file path with
+// spaces and NO embedded quotes or parens. Anything trickier (titles,
+// nested parens) gets left alone -- the regex is too coarse to safely
+// rewrite those.
 const MEDIA_URL_SPACES_RE = /(!?\[(?:[^\]\n]*)\])\(([^)"'\n]+)\)/g;
 function encodeSpacesInMediaUrls(src) {
   return src.replace(MEDIA_URL_SPACES_RE, (whole, prefix, url) => {
diff --git a/builder/tbdocs.mjs b/builder/tbdocs.mjs
index 01a3a362..b19382f0 100644
--- a/builder/tbdocs.mjs
+++ b/builder/tbdocs.mjs
@@ -602,21 +602,22 @@ const TASKS = {
       // renders -- and validated here for the same reason. An unknown name
       // cannot be an error inside the substitution rule: markdown-it emits an
       // unrecognised inline verbatim, so the rule would publish the typo to
-      // readers rather than fail. See counts.mjs.
+      // readers rather than fail. See counts.mjs. The validation masks code
+      // with the site's parser, so it follows the parser's creation.
       state.site.counts = deriveCounts(state, { redirectStubs: stubs.length });
-      const badNames = validateCountNames(state.pages, state.site.counts);
-      if (badNames.length) {
-        throw new Error(
-          `unknown {{tbdocs:...}} count name in ${badNames.length} place(s):\n\n` +
-          badNames.join("\n\n"));
-      }
-
       state.site.markdown             = createMarkdownIt({
         highlighter: null, linkTables, baseurl, staticFiles: staticFileSet,
         vendoredVideos: state.site.vendoredVideos,
         vendoredImages: state.site.vendoredImages,
         counts: state.site.counts,
       });
+      const badNames = validateCountNames(state.pages, state.site.counts, state.site.markdown);
+      if (badNames.length) {
+        throw new Error(
+          `unknown {{tbdocs:...}} count name in ${badNames.length} place(s):\n\n` +
+          badNames.join("\n\n"));
+      }
+
       state.site.linkTablesSerialized = serializeLinkTables(linkTables);
       const { seoSiteTitle, seoLogoUrl } = computeSiteSeo(state.site.config, state.site.markdown);
       state.site.seoSiteTitle = seoSiteTitle;
diff --git a/docs/Documentation/Authoring.md b/docs/Documentation/Authoring.md
index 456c4031..d76a3642 100644
--- a/docs/Documentation/Authoring.md
+++ b/docs/Documentation/Authoring.md
@@ -420,7 +420,7 @@ with four backticks and close with four:
 
 Nothing else changes. A fence closes only on a run at least as long as the one
 that opened it, and both pre-render passes that have to find fences apply that
-same rule --- `maskCodeRegions`, which hides code from the rewrites, and the
+same rule --- `maskCode`, which hides code from the rewrites, and the
 fence stasher inside `rewriteAdmonitions`, which is the one that matters here
 because it runs *outside* the mask by design. The language tag reaching the
 highlighter is the same string either way --- a four-backtick `tb` fence is highlighted exactly as a
diff --git a/docs/Documentation/Extending.md b/docs/Documentation/Extending.md
index dba69de5..8fa4c1ca 100644
--- a/docs/Documentation/Extending.md
+++ b/docs/Documentation/Extending.md
@@ -111,7 +111,7 @@ rewrite runs:
    rewrites run and put back afterwards. A rewrite added between the two never sees code:
 
    ```js
-   const code = maskCodeRegions(source);
+   const code = maskCode(source, { md });
    let work = code.masked;
    work = rewriteTripleAsteriskEmphasis(work);
    // ... the other masked rewrites ...
@@ -120,8 +120,7 @@ rewrite runs:
    ```
 
 2. **For an indented code block, the mask cannot help.** It does not cover indented blocks
-   on purpose: telling one from a list item's continuation needs block context a
-   pre-render pass does not have. Narrow the rewrite so it cannot match the block's
+   on purpose. Narrow the rewrite so it cannot match the block's
    lines, and let the gate say when it no longer does.
 3. **Do not widen the mask to make the report go away.** Text the mask hides is text no
    rewrite reaches, so a mask that hides prose stops the rewrites firing on it --- and the
@@ -790,7 +789,7 @@ Three gates are the ones a builder change is most likely to trip, and each fails
 
 - `pick_a11y_sample.mjs --check`, in `check.bat`, fails when a construct family the site uses is covered by no page in the sample --- normally because a build added or moved pages and the cheapest page for some family is no longer in the list. The fix is to add the page it names, not to widen the sample by hand. **It cannot report a genuinely new construct.** The gate iterates the registered `FAMILIES` and nothing else, so markup no family describes produces silence, and that silence is the exact failure a derived sample exists to prevent: the axe rule keyed on that construct then runs nowhere. Adding a family is the deliberate step, and [Tools and Scripts](Tools#pick-a11y-sample) gives the shape of one.
 - `check_publish_policy.mjs`, in `test.bat`, fails when a new emitted file type is not on the allowlist in `builder/publish-policy.mjs`. Add it to `BUILD_EXTENSIONS`, which is deliberately a separate set from `SOURCE_EXTENSIONS` so blessing a generated type does not also bless a stray one a contributor drops into `docs/`.
-- `check_code_regions.mjs`, also in `test.bat`, fails when a new pre-render rewrite alters the contents of a code fence, an indented code block or a code span. For a fence or a span, the fix is to move the rewrite inside `applyPreRenderRewrites` in `render.mjs`, between `maskCodeRegions` and its `restore`, rather than to widen the mask; an indented block is not masked at all. [When `test.bat` fails in `check_code_regions`](#code-regions-altered) has both cases.
+- `check_code_regions.mjs`, also in `test.bat`, fails when a new pre-render rewrite alters the contents of a code fence, an indented code block or a code span. For a fence or a span, the fix is to move the rewrite inside `applyPreRenderRewrites` in `render.mjs`, between `maskCode` and its `restore`, rather than to widen the mask; an indented block is not masked at all. [When `test.bat` fails in `check_code_regions`](#code-regions-altered) has both cases.
 
 > [!NOTE]
 > Both `check.bat` and `test.bat` want `build.bat` to have run first, for different reasons. `check.bat` reads the built tree throughout, and `check_tree_fresh.mjs` refuses one older than the sources that produced it rather than letting the later gates report on stale output. `test.bat` needs a built tree only for its last gate, `check_axe_patch_equiv.mjs`, and does not care how old that tree is.
diff --git a/docs/Documentation/Pipeline-Stages.md b/docs/Documentation/Pipeline-Stages.md
index 09e9ead3..fb9d3c57 100644
--- a/docs/Documentation/Pipeline-Stages.md
+++ b/docs/Documentation/Pipeline-Stages.md
@@ -650,8 +650,7 @@ Runs two build-aborting integrity checks before building the tree: `validatePerm
 | Symbol | Signature | Description |
 |---|---|---|
 | `renderPhase` | `(pages, site, staticFiles?) → Promise<void>` | Renders each page's `rawContent` to `renderedContent` via the supplied site's markdown-it. Skips `layout: book-combined`. |
-| `applyPreRenderRewrites` | `(rawContent) → string` | The whole pre-render source rewrite chain, as the render stage applies it to each page before parsing: normalises line endings to LF, masks the code regions, runs the four kramdown-parity rewrites, restores the code, then runs `rewriteAdmonitions`. Exported so `check_code_regions.mjs` and `check_examples.mjs` test the real chain rather than a copy of it. |
-| `maskCodeRegions` | `(src) → { masked, restore }` | Replaces each fenced code block and inline code span with a placeholder, so a source rewrite cannot reach into code; `restore(text)` puts them back. Indented code blocks are not masked. `counts.mjs` uses it to find `{{tbdocs:<name>}}` outside code. |
+| `applyPreRenderRewrites` | `(rawContent, md) → string` | The whole pre-render source rewrite chain, as the render stage applies it to each page before parsing: normalises line endings to LF, masks code with `maskCode` from `lib/markdown.mjs` using the site's markdown-it instance `md`, runs the four kramdown-parity rewrites, restores the code, then runs `rewriteAdmonitions`. Throws a `TypeError` when `md` is omitted. Exported so `check_code_regions.mjs` and `check_examples.mjs` test the real chain rather than a copy of it. |
 | `createMarkdownIt` | `({ highlighter, linkTables, baseurl, staticFiles, svgContents?, vendoredVideos?, vendoredImages?, counts? }) → MarkdownIt` | Builds the configured markdown-it instance: the eighteen plugins tabulated below, in their fixed order, plus eight renderer-rule overrides assigned directly. `svgContents` is a `Map<srcRel, string>` of pre-read SVG file contents; when present, `svgInlinePlugin` replaces a lone `.svg` image with an inline SVG wrapper. `vendoredVideos` and `vendoredImages` are the maps `videoLinkPlugin` and `remoteImagePlugin` resolve against, and `counts` is the registry `countPlugin` substitutes from. See [Extending](Extending#adding-a-markdown-it-plugin) for how to add a plugin. |
 | `initHighlighter` | (re-export from `highlight.mjs`) | `() → Promise<object>`. Initialises Shiki with the bundled twinBASIC grammar. |
 | `buildLinkTables` | `(pages) → { byPath, byUrl, byRedirect }` | Map lookups keyed by `srcRel`, `permalink`, and `redirect_from` entries. |
@@ -718,8 +717,8 @@ For **renderer rules**, order inverts. Both image plugins capture the current `m
 | `PLACEHOLDER_RE` | `RegExp` | Matches a `{{tbdocs:<name>}}` placeholder and captures the name. Used by the internal `substitute` helper that `countPlugin` calls, and by `findCountRefs` to locate placeholders in a page's raw markdown. |
 | `deriveCounts` | `(state, extra) → Record<string, number>` | Derives every named count from build state: page, static-file, reference-page and documentation-page totals, folder-style reference indexes and how many of them have a permalink ending in a slash, packages (total, default, built-in), attribute anchors, enumerations, and `extra.redirectStubs`. Called by `markdownInit` in `tbdocs.mjs` to build `state.site.counts`, whose keys are the names a page may use. |
 | `countPlugin` | `(md, ctx) → void` | A markdown-it plugin, the last one `createMarkdownIt` applies. Its core rule is pushed last, so it runs after `replacements` and sees the same text the reader will. Substitutes each `{{tbdocs:<name>}}` placeholder in prose and image alt text with the value `ctx.counts` holds under that name, and leaves an unknown name as written; code spans and fences are untouched. Does nothing when `ctx.counts` is absent. |
-| `findCountRefs` | `(rawContent) → { name, line }[]` | Finds every `{{tbdocs:...}}` reference in a page's raw source that is outside code, using `maskCodeRegions` from `render.mjs` so code is masked the same way the pre-render rewrites mask it. Called by `validateCountNames` for each page. |
-| `validateCountNames` | `(pages, counts) → string[]` | Checks every page's count references against the known `counts` names via `findCountRefs`, returning one message per unknown reference that gives the file and line, the nearest known name when one is within an edit distance of three, and every known name; empty when every reference is known. Called by `markdownInit` in `tbdocs.mjs`, which throws when the result is non-empty. |
+| `findCountRefs` | `(rawContent, md) → { name, line }[]` | Finds every `{{tbdocs:...}}` reference in a page's raw source that is outside code, using `maskCode` from `lib/markdown.mjs` with the site's markdown-it instance `md`, so code is masked the same way the pre-render rewrites mask it. Called by `validateCountNames` for each page. |
+| `validateCountNames` | `(pages, counts, md) → string[]` | Checks every page's count references against the known `counts` names via `findCountRefs`, returning one message per unknown reference that gives the file and line, the nearest known name when one is within an edit distance of three, and every known name; empty when every reference is known. Called by `markdownInit` in `tbdocs.mjs`, which throws when the result is non-empty. |
 | `findSurvivingPlaceholder` | `(html) → string\|null` | Scans rendered HTML, outside `<code>` and `<pre>`, for a `{{tbdocs:...}}` placeholder that survived rendering, returning the first survivor or `null`. Called by `renderPhase` in `render.mjs` after each page renders, which throws when a survivor is found. |
 
 ### `highlight.mjs`
diff --git a/eval/usecases.md b/eval/usecases.md
index 95920664..3764a43f 100644
--- a/eval/usecases.md
+++ b/eval/usecases.md
@@ -351,7 +351,7 @@ started; a re-run would re-measure the same absence.
 | id | goal | hazard |
 |----|------|--------|
 | UC-40 | *(re-run)* A gate refused a regex I added to the builder. Understand it and fix it. | **H** rounds 5 and 6 found the answer only under the script's own name; the section added for this round quotes the failure instead |
-| UC-56 | I changed one of the builder's text rewrites, and `test.bat` now fails in `check_code_regions`. What does it want from me, and what is the right fix? | **H** exempting the page or loosening the comparison looks like a fix; the rewrite belongs between `maskCodeRegions` and its restore, and the gate's `Tools.md` entry has no "when this fails" passage |
+| UC-56 | I changed one of the builder's text rewrites, and `test.bat` now fails in `check_code_regions`. What does it want from me, and what is the right fix? | **H** exempting the page or loosening the comparison looks like a fix; the rewrite belongs between `maskCode` and its restore, and the gate's `Tools.md` entry has no "when this fails" passage |
 
 ### Persona D: a twinBASIC developer on the published site
 
diff --git a/scripts/check_code_regions.mjs b/scripts/check_code_regions.mjs
index 1f14ba1e..719d67c0 100644
--- a/scripts/check_code_regions.mjs
+++ b/scripts/check_code_regions.mjs
@@ -38,11 +38,9 @@
 //
 // KNOWN GAP 1, stated rather than hidden: an indented (4-space) code block is
 // compared as a `code_block` token, so corruption of one IS caught here -- but
-// maskCodeRegions in render.mjs deliberately does not protect indented blocks,
-// because distinguishing one from a list-item continuation needs block context
-// a pre-render pass does not have. So a future rewrite that damages an indented
-// block will be reported by this gate and will need fixing at the rewrite, not
-// by widening the mask.
+// the chain's mask in render.mjs does not protect indented blocks, and never
+// has. So a future rewrite that damages an indented block will be reported by
+// this gate and will need fixing at the rewrite.
 //
 // KNOWN GAP 2: code inside a RAW HTML BLOCK is invisible here. markdown-it
 // emits such a block as a single `html_block` token, which is none of the three
@@ -74,7 +72,7 @@ import { fileURLToPath } from "node:url";
 
 import MarkdownIt from "markdown-it";
 import deflist from "markdown-it-deflist";
-import { applyPreRenderRewrites } from "../builder/render.mjs";
+import { applyPreRenderRewrites, createMarkdownIt } from "../builder/render.mjs";
 import { parseFrontmatter } from "../lib/frontmatter.mjs";
 import { blockRegions, mapLines, maskCode, splitCodeSpans, splitOnMarker } from "../lib/markdown.mjs";
 import { markdownFiles } from "../lib/markdown-files.mjs";
@@ -110,7 +108,10 @@ function parsedRegions(src) {
 // The real chain, imported from render.mjs rather than reconstructed here.
 // That is what makes this gate mean something: unmasking any one of the
 // rewrites changes what this function does, and the comparison below sees it.
-const applyRewrites = applyPreRenderRewrites;
+// It masks with the site's parser, as renderPage does; only its block rules
+// run, so the options that matter to rendering are left empty.
+const siteMd = createMarkdownIt({ highlighter: null, linkTables: null, baseurl: "", staticFiles: new Set() });
+const applyRewrites = (src) => applyPreRenderRewrites(src, siteMd);
 
 function compare(src) {
   const before = codeRegions(src);
@@ -182,6 +183,16 @@ const ADMONITION_PROBES = [
     "prose\n\n~~~markdown\nsample\n```\n~~~\n\n> [!NOTE]\n> body\n\n```tb\nDim y\n```\n"],
 ];
 
+// Sources the whole chain must return byte for byte. The first holds the chain
+// to the site's parser: the definition-list plugin makes a fence after `: `
+// that a bare parser reads as a paragraph, and masked with a bare parser, the
+// fence's body is rewritten (`a,%20b`). The region comparison cannot see that,
+// because it parses bare too and finds no fence there to compare.
+const UNCHANGED_PROBES = [
+  ["a fence the definition-list plugin makes",
+    "Term\n: ```tb\n  v = Items[1](a, b)\n  ```\n"],
+];
+
 // The regions blockRegions reports, in a form assert can compare at a glance.
 const regionsOf = (src, options) => blockRegions(src, options).map((r) => `${r.type} ${r.start}-${r.end}`);
 
@@ -316,6 +327,14 @@ async function main(argv) {
     console.log(`        the admonition was not rewritten -- the fence stasher`);
     console.log(`        mistook the prose around it for code`);
   }
+  for (const [name, src] of UNCHANGED_PROBES) {
+    const after = applyRewrites(src);
+    if (after === src) continue;
+    failed++;
+    console.log(`FAIL  probe: ${name}`);
+    console.log(`        before ${JSON.stringify(src)}`);
+    console.log(`        after  ${JSON.stringify(after)}`);
+  }
   // Anything but a failed assertion is the gate breaking, and goes to exit 2.
   for (const [name, probe] of MODULE_PROBES) {
     try {
@@ -331,6 +350,7 @@ async function main(argv) {
   if (!failed) {
     console.log(`ok    ${PROBES.length} probes: no rewrite alters a code region`);
     console.log(`ok    ${ADMONITION_PROBES.length} probes: a rewrite still fires on prose beside code`);
+    console.log(`ok    ${UNCHANGED_PROBES.length} probe(s): the chain masks what the site's parser calls code`);
     console.log(`ok    ${MODULE_PROBES.length} probes: lib/markdown.mjs and lib/frontmatter.mjs`);
   }
 
diff --git a/scripts/check_examples.mjs b/scripts/check_examples.mjs
index 29c8401a..98da8330 100644
--- a/scripts/check_examples.mjs
+++ b/scripts/check_examples.mjs
@@ -1567,8 +1567,9 @@ async function runProbes() {
   // pipeline -- createMarkdownIt plus the highlighter -- because a bare
   // markdown-it is a different renderer, which is the mistake WIP.md's
   // "Source dashes" section records paying for.
-  const { createMarkdownIt, initHighlighter, applyPreRenderRewrites, maskCodeRegions } =
+  const { createMarkdownIt, initHighlighter, applyPreRenderRewrites } =
     await import("../builder/render.mjs");
+  const { maskCode } = await import("../lib/markdown.mjs");
   const highlighter = await initHighlighter();
   const md = createMarkdownIt({ highlighter, linkTables: null, baseurl: "", staticFiles: new Set() });
   const plain = "```tb\nDim x As Long\n```\n";
@@ -1583,10 +1584,10 @@ async function runProbes() {
   // fence in another language, must still publish.
   const notHidden = "```tb " + MARKER + " id=hidden-thing\nDim x As Long\n```\n";
   if (md.render(notHidden).trim() === "") failures.push("markup: `hidden` matched inside a value");
-  const masked = maskCodeRegions(marked);
-  if (masked.masked.includes("Dim x As Long")) failures.push("markup: maskCodeRegions stops hiding the body");
+  const masked = maskCode(marked, { md });
+  if (masked.masked.includes("Dim x As Long")) failures.push("markup: the pre-render mask stops hiding the body");
   if (masked.restore(masked.masked) !== marked) failures.push("markup: the mask does not round-trip");
-  if (applyPreRenderRewrites(marked) !== marked) failures.push("markup: a pre-render rewrite alters it");
+  if (applyPreRenderRewrites(marked, md) !== marked) failures.push("markup: a pre-render rewrite alters it");
 
   if (failures.length) {
     for (const f of failures) say(`FAIL  probe: ${f}`);
diff --git a/scripts/lib/tb-fences.mjs b/scripts/lib/tb-fences.mjs
index 6a953870..fcdd919b 100644
--- a/scripts/lib/tb-fences.mjs
+++ b/scripts/lib/tb-fences.mjs
@@ -21,12 +21,13 @@
 //     const lang = tok.info ? tok.info.trim().split(/\s+/)[0] : "";
 //
 // so everything after the language token is discarded before the highlighter
-// sees it, and maskCodeRegions hides the fence body either way -- which is why
+// sees it, and maskCode hides the fence body either way -- which is why
 // the marker cannot reach the HTML and cannot perturb check_code_regions.mjs.
 // check_examples.mjs asserts all of that on every run rather than trusting it.
 //
 // No backticks may appear in it: CommonMark forbids them in a backtick fence's
-// info string, and maskCodeRegions skips such a fence outright.
+// info string, and markdown-it reads such a line as prose rather than as a
+// fence, so the sample would not be a fence at all.
 //
 // ------------------------------------------------------------- the five slots
 //

From d541c6fc32c597be8784aed2279b19e7413dd916 Mon Sep 17 00:00:00 2001
From: Kuba Sunderland-Ober <kuba@mareimbrium.org>
Date: Sun, 27 Sep 2026 13:46:44 +0200
Subject: [PATCH 04/27] builder: an unknown count name is reported at its file
 line

---
 WIP.md                                |  2 +-
 builder/PLAN-TOOLING-REVIEW.md        | 30 +++++++++++++++++++
 builder/counts.mjs                    | 12 ++++++--
 builder/discover.mjs                  | 12 ++++++--
 docs/Documentation/Pipeline-Stages.md |  5 ++--
 docs/Documentation/Tools.md           |  2 +-
 scripts/check_code_regions.mjs        | 43 ++++++++++++++++++++++++++-
 7 files changed, 96 insertions(+), 10 deletions(-)

diff --git a/WIP.md b/WIP.md
index ec984672..db66a899 100644
--- a/WIP.md
+++ b/WIP.md
@@ -501,7 +501,7 @@ wrapper:
 | `check.bat` | `check_tree_fresh` | the tree is not older than the sources that produced it |
 | `check.bat` | `check_dot_fit` | every diagram label sits inside the box Graphviz drew for it |
 | `check.bat` | `pick_a11y_sample --check`, `check_a11y` | see [WIP.A11y.md](WIP.A11y.md) |
-| `test.bat` | `check_code_regions` | no source or HTML rewrite altered a code region; `lib/markdown.mjs` and `lib/frontmatter.mjs` pass their probes, and the block parse finds what the full parse finds |
+| `test.bat` | `check_code_regions` | no source or HTML rewrite altered a code region; `lib/markdown.mjs` and `lib/frontmatter.mjs` pass their probes, and the block parse finds what the full parse finds; the count-name check skips code and names the file's line |
 | `test.bat` | `check_regex_safety` | no regex in the tree can backtrack exponentially |
 | `test.bat` | `check_symbol_index` | the symbol index still places each kind of symbol, from fixtures |
 | `test.bat` | `check_ci_workflows` | both CI workflows run every wrapper gate, with the same arguments and order, and build with `build.bat`'s flags |
diff --git a/builder/PLAN-TOOLING-REVIEW.md b/builder/PLAN-TOOLING-REVIEW.md
index 39442ec3..ffede823 100644
--- a/builder/PLAN-TOOLING-REVIEW.md
+++ b/builder/PLAN-TOOLING-REVIEW.md
@@ -686,6 +686,30 @@ Found: the line `validateCountNames` reports is a line of the masked content aft
 frontmatter, not of the file: `x.md:5` for a name on line 12, below three lines of
 frontmatter and a five-line fence. C32 keeps that number, and C32a fixes it.
 
+### C32a — `builder: an unknown count name is reported at its file line`
+
+**Found in C32** (see Found while implementing); the owner asked for the fix as its own
+commit straight after C32, so that C32 changes nothing.
+
+**Landed.** `discover` gives each page `contentLine`, the file's 1-based line on which
+`rawContent` starts, counted from the text before gray-matter's content. `findCountRefs`
+counts a reference's line in `rawContent` with the code put back, so a masked fence counts
+all its lines, and `validateCountNames` adds `contentLine - 1`. C40 needs no change for it,
+because the line comes from the content's length. If `parseFrontmatter`'s content is ever
+not the file's tail, the probe fails. The probe is in `check_code_regions.mjs`, which the
+owner chose because the validator asks `lib/markdown` what is code. It writes one page to a
+temporary folder and runs it through the real `discover` and `validateCountNames`: CRLF
+frontmatter, count names in a fence, a code span and a definition-list fence, then an
+unknown one in prose on line 16. Pipeline-Stages gains the `contentLine` field and states
+both functions' lines. Tools.md's section and WIP.md's gate row name C32's probe and this one.
+
+**Verify.** HEAD's validator reports the probe's page at `x.md:9`, and this one at
+`x.md:16`. Four faults each fail the probe: lines counted in the masked content, no
+frontmatter offset, `discover` setting no `contentLine`, and the validator masking with a
+bare parser. Over all 914 pages `discover` finds (912 `.md`, 2 `.html`), the file from line
+`contentLine` on is exactly `rawContent`. The tree comparison differs only where the commit
+edits pages: Pipeline-Stages and Tools online and offline, the search data, and `book.html`.
+
 ### C33 — `render: admonitions find their fences through lib/markdown`
 
 **A3-1, second half.** `rewriteAdmonitions` protects fences with its own `stashCodeFences`.
@@ -1853,6 +1877,12 @@ Defects the review did not have, found by building something this plan asks for.
   the file's end and the date. C27a's oracle measured it: a stored channel holding d1 and d2
   held d10 alone after an export with `--since` d5. Fixed in `wisdom: export --since keeps the
   history already stored`.
+- **An unknown count name was reported at the wrong line**, found while landing C32.
+  `findCountRefs` counted lines in the masked content, where a fence is one line, and
+  `rawContent` starts after the frontmatter, so `validateCountNames` gave `x.md:5` for a name
+  on line 12 below three lines of frontmatter and a five-line fence. The build still failed;
+  only the line it named was wrong. Fixed in `builder: an unknown count name is reported at
+  its file line`.
 
 ## Open questions
 
diff --git a/builder/counts.mjs b/builder/counts.mjs
index b86c0fd2..7d87a019 100644
--- a/builder/counts.mjs
+++ b/builder/counts.mjs
@@ -236,13 +236,16 @@ function substitute(text, counts) {
  * it this would reject the very examples the documentation of this feature
  * has to contain.
  *
+ * `line` is 1-based in `rawContent`. It is counted with the code put back,
+ * because a masked fence is one line however many it holds.
+ *
  * @returns {{name: string, line: number}[]}
  */
 export function findCountRefs(rawContent, md) {
-  const { masked } = maskCode(rawContent.replace(/\r\n?/g, "\n"), { md });
+  const { masked, restore } = maskCode(rawContent.replace(/\r\n?/g, "\n"), { md });
   const out = [];
   for (const m of masked.matchAll(PLACEHOLDER_RE)) {
-    out.push({ name: m[1], line: masked.slice(0, m.index).split("\n").length });
+    out.push({ name: m[1], line: restore(masked.slice(0, m.index)).split("\n").length });
   }
   return out;
 }
@@ -281,6 +284,9 @@ function editDistance(a, b) {
  * name cannot be an error there: markdown-it emits the text verbatim, so the
  * rule would publish `{{tbdocs:pgaes}}` to readers rather than fail.
  *
+ * A message names the line of the file, not of `rawContent`: the page's
+ * `contentLine`, from `discover`, says where its content starts.
+ *
  * @returns {string[]} one message per bad reference; empty means clean
  */
 export function validateCountNames(pages, counts, md) {
@@ -291,7 +297,7 @@ export function validateCountNames(pages, counts, md) {
       if (Object.hasOwn(counts, name)) continue;
       const guess = nearest(name, names);
       problems.push(
-        `${p.srcRel}:${line}\n` +
+        `${p.srcRel}:${line + (p.contentLine ?? 1) - 1}\n` +
         `  unknown count name {{tbdocs:${name}}}\n` +
         (guess ? `  did you mean: ${guess}?\n` : "") +
         `  available: ${names.join(", ")}`,
diff --git a/builder/discover.mjs b/builder/discover.mjs
index a43ba0a7..75741506 100644
--- a/builder/discover.mjs
+++ b/builder/discover.mjs
@@ -106,17 +106,24 @@ function stripBom(s) {
   return s.charCodeAt(0) === 0xfeff ? s.slice(1) : s;
 }
 
+// `contentLine` is the file's 1-based line on which `content` starts, so a
+// message about a line of the content can name the line of the file. The
+// content is the text after the frontmatter block, so the lines before it are
+// the lines of the block.
 function parseFrontmatter(raw, srcRel) {
   const text = stripBom(raw);
   if (!matter.test(text)) return null;
+  let data, content;
   try {
-    return matter(text);
+    ({ data, content } = matter(text));
   } catch (err) {
     throw new Error(`Failed to parse frontmatter in ${srcRel}: ${err.message}`);
   }
+  const block = text.slice(0, text.length - content.length);
+  return { data, content, contentLine: (block.match(/\r\n?|\n/g) ?? []).length + 1 };
 }
 
-function buildPage(srcRoot, srcRel, { data, content }) {
+function buildPage(srcRoot, srcRel, { data, content, contentLine }) {
   const srcRelPosix = toPosix(srcRel);
   const ext = path.extname(srcRel).toLowerCase();
   const permalink = computePermalink(data.permalink, srcRelPosix);
@@ -127,6 +134,7 @@ function buildPage(srcRoot, srcRel, { data, content }) {
     ext,
     frontmatter: data,
     rawContent: content,
+    contentLine,
     permalink,
     destPath,
     layoutDefault: data.layout === undefined || data.layout === null,
diff --git a/docs/Documentation/Pipeline-Stages.md b/docs/Documentation/Pipeline-Stages.md
index fb9d3c57..7aa565de 100644
--- a/docs/Documentation/Pipeline-Stages.md
+++ b/docs/Documentation/Pipeline-Stages.md
@@ -31,6 +31,7 @@ The pipeline passes three pieces of mutable state through every task: the `pages
 | `ext` | `discover` | `string` | Lowercase file extension: `.md` or `.html`. |
 | `frontmatter` | `discover` | `object` | Parsed YAML frontmatter, with any leading UTF-8 BOM stripped before parsing (a BOM in front of the `---` otherwise makes `gray-matter` report no frontmatter at all, and the page is silently filed as a static asset). Only the named keys below are ever read --- nothing iterates this object, so an unrecognised key such as a package page's `indexed_from` is inert and never reaches the output. |
 | `rawContent` | `discover` | `string` | Body text after the frontmatter block. |
+| `contentLine` | `discover` | `number` | The 1-based line of the source file on which `rawContent` starts. `validateCountNames` adds it to a line of `rawContent`, so its messages name the line of the file. |
 | `permalink` | `discover` | `string` | URL path from `frontmatter.permalink`. A fallback of `/<srcRel>.html` exists in `computePermalink`, but `nav`'s `validatePermalinks` aborts the build before it can matter --- the file tree does not mirror the URL tree, so a derived permalink is structurally wrong here. |
 | `destPath` | `discover` | `string` | Filesystem path within the output root, e.g. `Reference/Core/Dim.html`. |
 | `layoutDefault` | `discover` | `boolean` | `true` when frontmatter has no explicit `layout:` key. |
@@ -717,8 +718,8 @@ For **renderer rules**, order inverts. Both image plugins capture the current `m
 | `PLACEHOLDER_RE` | `RegExp` | Matches a `{{tbdocs:<name>}}` placeholder and captures the name. Used by the internal `substitute` helper that `countPlugin` calls, and by `findCountRefs` to locate placeholders in a page's raw markdown. |
 | `deriveCounts` | `(state, extra) → Record<string, number>` | Derives every named count from build state: page, static-file, reference-page and documentation-page totals, folder-style reference indexes and how many of them have a permalink ending in a slash, packages (total, default, built-in), attribute anchors, enumerations, and `extra.redirectStubs`. Called by `markdownInit` in `tbdocs.mjs` to build `state.site.counts`, whose keys are the names a page may use. |
 | `countPlugin` | `(md, ctx) → void` | A markdown-it plugin, the last one `createMarkdownIt` applies. Its core rule is pushed last, so it runs after `replacements` and sees the same text the reader will. Substitutes each `{{tbdocs:<name>}}` placeholder in prose and image alt text with the value `ctx.counts` holds under that name, and leaves an unknown name as written; code spans and fences are untouched. Does nothing when `ctx.counts` is absent. |
-| `findCountRefs` | `(rawContent, md) → { name, line }[]` | Finds every `{{tbdocs:...}}` reference in a page's raw source that is outside code, using `maskCode` from `lib/markdown.mjs` with the site's markdown-it instance `md`, so code is masked the same way the pre-render rewrites mask it. Called by `validateCountNames` for each page. |
-| `validateCountNames` | `(pages, counts, md) → string[]` | Checks every page's count references against the known `counts` names via `findCountRefs`, returning one message per unknown reference that gives the file and line, the nearest known name when one is within an edit distance of three, and every known name; empty when every reference is known. Called by `markdownInit` in `tbdocs.mjs`, which throws when the result is non-empty. |
+| `findCountRefs` | `(rawContent, md) → { name, line }[]` | Finds every `{{tbdocs:...}}` reference in a page's raw source that is outside code, using `maskCode` from `lib/markdown.mjs` with the site's markdown-it instance `md`, so code is masked the same way the pre-render rewrites mask it. `line` is 1-based in `rawContent`, counted with the code put back, since a masked fence is one line. Called by `validateCountNames` for each page. |
+| `validateCountNames` | `(pages, counts, md) → string[]` | Checks every page's count references against the known `counts` names via `findCountRefs`, returning one message per unknown reference that gives the file and the line in it (the reference's line in `rawContent`, moved down by the page's `contentLine`), the nearest known name when one is within an edit distance of three, and every known name; empty when every reference is known. Called by `markdownInit` in `tbdocs.mjs`, which throws when the result is non-empty. |
 | `findSurvivingPlaceholder` | `(html) → string\|null` | Scans rendered HTML, outside `<code>` and `<pre>`, for a `{{tbdocs:...}}` placeholder that survived rendering, returning the first survivor or `null`. Called by `renderPhase` in `render.mjs` after each page renders, which throws when a survivor is found. |
 
 ### `highlight.mjs`
diff --git a/docs/Documentation/Tools.md b/docs/Documentation/Tools.md
index 82ed3519..3f9d6034 100644
--- a/docs/Documentation/Tools.md
+++ b/docs/Documentation/Tools.md
@@ -425,7 +425,7 @@ Probes ride along in the normal run, each a defect this repository actually ship
 
 The admonition probes test the mirror fault, which the region comparison structurally cannot see: **a rewrite that misreads what is code can also fail to fire on real prose**, and the regions still come back identical because the text was only stashed and restored. `Reference/Attributes.md` shipped all six of its admonitions as the literal text `[!NOTE]` for exactly that reason --- a `[Description(...)]` sample whose argument is a Markdown string containing two fence markers as twinBASIC string literals, which the fence stasher closed the surrounding fence on. Every pairing after it was off by one.
 
-It is also the gate on `lib/markdown.mjs` and `lib/frontmatter.mjs`, the modules that tell the tools what in a page is code and where its frontmatter ends. Their probes run with the others, and on every page the sweep checks that `blockRegions`, which parses blocks only, finds exactly the fences, code blocks and HTML blocks of a full parse. The summary line gives the number of fences that full parse found.
+It is also the gate on `lib/markdown.mjs` and `lib/frontmatter.mjs`, the modules that tell the tools what in a page is code and where its frontmatter ends. Their probes run with the others, and on every page the sweep checks that `blockRegions`, which parses blocks only, finds exactly the fences, code blocks and HTML blocks of a full parse. The summary line gives the number of fences that full parse found. Two more probes hold the build to the same answer: the rewrite chain must leave alone a fence that only the site's parser finds, and the build's check of `{{tbdocs:<name>}}` count names must skip names in code and give an unknown one's line in its file.
 
 `--verbose` prints the first few altered regions of each failing file, before and after. `--self-test` replaces the normal run rather than adding to it, so neither the probes nor the sweep runs: it de-indents the body of one small fence by hand and passes only if the comparison notices. That proves the comparator can still see a change, and nothing more --- it runs no rewrite at all.
 
diff --git a/scripts/check_code_regions.mjs b/scripts/check_code_regions.mjs
index 719d67c0..3aaf9261 100644
--- a/scripts/check_code_regions.mjs
+++ b/scripts/check_code_regions.mjs
@@ -63,15 +63,20 @@
 // tools ask what in a page is code and where its frontmatter ends. Their
 // probes ride along too, and the sweep checks on every page that
 // blockRegions, which parses blocks only, finds exactly the fences, code
-// blocks and HTML blocks of the full parse the comparison already makes.
+// blocks and HTML blocks of the full parse the comparison already makes. One
+// probe holds builder/counts.mjs's count validator, which asks the same module
+// what is code.
 
 import assert from "node:assert/strict";
 import { promises as fs } from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 import MarkdownIt from "markdown-it";
 import deflist from "markdown-it-deflist";
+import { validateCountNames } from "../builder/counts.mjs";
+import { discover } from "../builder/discover.mjs";
 import { applyPreRenderRewrites, createMarkdownIt } from "../builder/render.mjs";
 import { parseFrontmatter } from "../lib/frontmatter.mjs";
 import { blockRegions, mapLines, maskCode, splitCodeSpans, splitOnMarker } from "../lib/markdown.mjs";
@@ -294,6 +299,33 @@ const MODULE_PROBES = [
   }],
 ];
 
+// The count validator asks the same module what is code, with the site's
+// parser, and must name the line of the file. One page through the real
+// discover and validateCountNames: CRLF frontmatter, count names in a fence, a
+// code span and a definition-list fence, none of them references, then an
+// unknown name in prose on line 16. Counted in the masked content after the
+// frontmatter, where each fence is one line, it was reported at line 9.
+const COUNT_PAGE = [
+  "---", "title: T", "---", "",
+  "```tb", "{{tbdocs:a}}", "```", "",
+  "x `{{tbdocs:b}}` y", "",
+  "T", ": ```", "  {{tbdocs:c}}", "  ```", "",
+  "prose {{tbdocs:d}}", "",
+].join("\r\n");
+
+async function countProbe() {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "check-code-regions-"));
+  try {
+    await fs.writeFile(path.join(dir, "x.md"), COUNT_PAGE);
+    const { pages } = await discover(dir);
+    const problems = validateCountNames(pages, { pages: 1 }, siteMd);
+    assert.deepEqual(problems.map((p) => p.split("\n").slice(0, 2).join(" ")),
+      ["x.md:16   unknown count name {{tbdocs:d}}"]);
+  } finally {
+    await fs.rm(dir, { recursive: true, force: true });
+  }
+}
+
 async function main(argv) {
   const verbose = argv.includes("--verbose");
 
@@ -346,12 +378,21 @@ async function main(argv) {
       for (const line of err.message.split("\n")) console.log(`        ${line}`);
     }
   }
+  try {
+    await countProbe();
+  } catch (err) {
+    if (!(err instanceof assert.AssertionError)) throw err;
+    failed++;
+    console.log("FAIL  probe: the count validator's references and lines");
+    for (const line of err.message.split("\n")) console.log(`        ${line}`);
+  }
 
   if (!failed) {
     console.log(`ok    ${PROBES.length} probes: no rewrite alters a code region`);
     console.log(`ok    ${ADMONITION_PROBES.length} probes: a rewrite still fires on prose beside code`);
     console.log(`ok    ${UNCHANGED_PROBES.length} probe(s): the chain masks what the site's parser calls code`);
     console.log(`ok    ${MODULE_PROBES.length} probes: lib/markdown.mjs and lib/frontmatter.mjs`);
+    console.log("ok    1 probe: the count validator skips code and names the file's line");
   }
 
   const files = await markdownFiles(ROOT);

From 6a73ed767fb7c3acca92c0f854522bf7952ae123 Mon Sep 17 00:00:00 2001
From: Kuba Sunderland-Ober <kuba@mareimbrium.org>
Date: Sun, 27 Sep 2026 14:00:19 +0200
Subject: [PATCH 05/27] builder: regenerate package-api.json on twinBASIC BETA
 987

---
 builder/package-api.json | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/builder/package-api.json b/builder/package-api.json
index 1fa8d1d4..269d95bc 100644
--- a/builder/package-api.json
+++ b/builder/package-api.json
@@ -1,5 +1,5 @@
 {
-  "build": 983,
+  "build": 987,
   "packages": {
     "AppGlobalClassProject": {
       "exports": ["AppGlobalClassObject"],
@@ -560,6 +560,8 @@
         {"name":"OLEMISC","kind":"enum","in":"Miscellaneous","values":["OLEMISC_RECOMPOSEONRESIZE","OLEMISC_ONLYICONIC","OLEMISC_INSERTNOTREPLACE","OLEMISC_STATIC","OLEMISC_CANTLINKINSIDE","OLEMISC_CANLINKBYOLE1","OLEMISC_ISLINKOBJECT","OLEMISC_INSIDEOUT","OLEMISC_ACTIVATEWHENVISIBLE","OLEMISC_RENDERINGISDEVICEINDEPENDENT","OLEMISC_INVISIBLEATRUNTIME","OLEMISC_ALWAYSRUN","OLEMISC_ACTSLIKEBUTTON","OLEMISC_ACTSLIKELABEL","OLEMISC_NOUIACTIVATE","OLEMISC_ALIGNABLE","OLEMISC_SIMPLEFRAME","OLEMISC_SETCLIENTSITEFIRST","OLEMISC_IMEMODE","OLEMISC_IGNOREACTIVATEWHENVISIBLE","OLEMISC_WANTSTOMENUMERGE","OLEMISC_SUPPORTSMULTILEVELUNDO"]},
         {"name":"BorderStyles","kind":"enum","in":"Miscellaneous","values":["BDR_RAISEDOUTER","BDR_SUNKENOUTER","BDR_RAISEDINNER","BDR_SUNKENINNER","BDR_OUTER","BDR_INNER","BDR_RAISED","BDR_SUNKEN","EDGE_RAISED","EDGE_SUNKEN","EDGE_ETCHED","EDGE_BUMP"]},
         {"name":"BorderFlags","kind":"enum","in":"Miscellaneous","values":["BF_LEFT","BF_TOP","BF_RIGHT","BF_BOTTOM","BF_DIAGONAL","BF_MIDDLE","BF_SOFT","BF_ADJUST","BF_FLAT","BF_MONO","BF_TOPLEFT","BF_TOPRIGHT","BF_BOTTOMLEFT","BF_BOTTOMRIGHT","BF_RECT","BF_DIAGONAL_ENDTOPRIGHT","BF_DIAGONAL_ENDTOPLEFT","BF_DIAGONAL_ENDBOTTOMLEFT","BF_DIAGONAL_ENDBOTTOMRIGHT"]},
+        {"name":"tbBytes","kind":"type","in":"Miscellaneous","public":false},
+        {"name":"tbIntegers","kind":"type","in":"Miscellaneous","public":false},
         {"name":"TEXTMETRICW","kind":"type","in":"Miscellaneous","public":false},
         {"name":"ENHMETAHEADER","kind":"type","in":"Miscellaneous","public":false},
         {"name":"DEVMODEW","kind":"type","in":"Miscellaneous","public":false},
@@ -590,7 +592,7 @@
     "VBA": {
       "exports": ["VBA"],
       "types": [
-        {"name":"_Collection","kind":"interface","members":{"Item":"function","Add":"sub","Count":"property","Remove":"sub","Clear":"sub","Exists":"function","KeyCountHint":"property","KeyCompareMode":"property","Items":"function","Keys":"function","_NewEnum":"function"},"hiddenMembers":["_NewEnum"]},
+        {"name":"_Collection","kind":"interface","members":{"Item":"function","Add":"sub","Count":"property","Remove":"sub","_NewEnum":"function","Clear":"sub","Exists":"function","KeyCountHint":"property","KeyCompareMode":"property","Items":"function","Keys":"function"},"hiddenMembers":["_NewEnum"]},
         {"name":"Collection","kind":"coclass","default":"_Collection"},
         {"name":"Compilation","kind":"module","members":{"CurrentProjectName":"function","CurrentComponentName":"function","CurrentComponentCLSID":"function","CurrentProcedureName":"function","CurrentSourceFile":"function","ProcessorArchitecture":"function","CompilerVersion":"function"}},
         {"name":"Constants","kind":"module","members":{"vbNewLine":"const","vbCrLf":"const","vbCr":"const","vbLf":"const","vbBack":"const","vbFormFeed":"const","vbTab":"const","vbVerticalTab":"const","vbNullChar":"const","vbNullString":"const","vbObjectError":"const","vbNullPtr":"const"}},
@@ -1008,8 +1010,9 @@
         {"name":"NMLISTVIEW","kind":"type","in":"ListViewConsts","public":false},
         {"name":"LVStyles","kind":"enum","in":"ListViewConsts","values":["LVS_ICON","LVS_REPORT","LVS_SMALLICON","LVS_LIST","LVS_TYPEMASK","LVS_SINGLESEL","LVS_SHOWSELALWAYS","LVS_SORTASCENDING","LVS_SORTDESCENDING","LVS_SHAREIMAGELISTS","LVS_NOLABELWRAP","LVS_AUTOARRANGE","LVS_EDITLABELS","LVS_OWNERDATA","LVS_NOSCROLL","LVS_TYPESTYLEMASK","LVS_ALIGNTOP","LVS_ALIGNLEFT","LVS_ALIGNMASK","LVS_OWNERDRAWFIXED","LVS_NOCOLUMNHEADER","LVS_NOSORTHEADER"]},
         {"name":"LVExtendedStyles","kind":"enum","in":"ListViewConsts","values":["LVS_EX_GRIDLINES","LVS_EX_SUBITEMIMAGES","LVS_EX_CHECKBOXES","LVS_EX_TRACKSELECT","LVS_EX_HEADERDRAGDROP","LVS_EX_FULLROWSELECT","LVS_EX_ONECLICKACTIVATE","LVS_EX_TWOCLICKACTIVATE","LVS_EX_FLATSB","LVS_EX_REGIONAL","LVS_EX_INFOTIP","LVS_EX_UNDERLINEHOT","LVS_EX_UNDERLINECOLD","LVS_EX_MULTIWORKAREAS","LVS_EX_LABELTIP","LVS_EX_BORDERSELECT","LVS_EX_DOUBLEBUFFER","LVS_EX_HIDELABELS","LVS_EX_SINGLEROW","LVS_EX_SNAPTOGRID","LVS_EX_SIMPLESELECT","LVS_EX_JUSTIFYCOLUMNS","LVS_EX_TRANSPARENTBKGND","LVS_EX_TRANSPARENTSHADOWTEXT","LVS_EX_AUTOAUTOARRANGE","LVS_EX_HEADERINALLVIEWS","LVS_EX_AUTOCHECKSELECT","LVS_EX_AUTOSIZECOLUMNS","LVS_EX_COLUMNSNAPPOINTS","LVS_EX_COLUMNOVERFLOW"]},
+        {"name":"Miscellaneous2","kind":"module"},
+        {"name":"OrientationConstants","kind":"enum","in":"Miscellaneous2","values":["ccOrientationHorizontal","ccOrientationVertical"]},
         {"name":"Miscellaneous","kind":"module","public":false},
-        {"name":"OrientationConstants","kind":"enum","in":"Miscellaneous","values":["ccOrientationHorizontal","ccOrientationVertical"]},
         {"name":"MonthViewConsts","kind":"module","members":{"GDTR_MIN":"const","GDTR_MAX":"const"}},
         {"name":"MonthViewStyles","kind":"enum","in":"MonthViewConsts","values":["MCS_DAYSTATE","MCS_MULTISELECT","MCS_WEEKNUMBERS","MCS_NOTODAYCIRCLE","MCS_NOTODAY","MCS_NOTRAILINGDATES","MCS_SHORTDAYSOFWEEK","MCS_NOSELCHANGEONNAV"]},
         {"name":"MonthViewColorArea","kind":"enum","in":"MonthViewConsts","values":["MCSC_BACKGROUND","MCSC_TEXT","MCSC_TITLEBK","MCSC_TITLETEXT","MCSC_MONTHBK","MCSC_TRAILINGTEXT"]},

From 1df8cdc89b56a7a45085b9a19d84d9fbfa86f8a8 Mon Sep 17 00:00:00 2001
From: Kuba Sunderland-Ober <kuba@mareimbrium.org>
Date: Sun, 27 Sep 2026 14:03:24 +0200
Subject: [PATCH 06/27] test: P5 takes an empty hover as nothing, which BETA
 987 gives

---
 WIP.HelpAddin.md            |  3 ++-
 test/addin/symbols.test.mjs | 11 +++++++----
 2 files changed, 9 insertions(+), 5 deletions(-)

diff --git a/WIP.HelpAddin.md b/WIP.HelpAddin.md
index c2e78fdc..4d1e63f5 100644
--- a/WIP.HelpAddin.md
+++ b/WIP.HelpAddin.md
@@ -391,7 +391,8 @@ have: writing into the install, which every new build replaces. Still deferred.
   says `*class* **Collection** ... in package VBA` and lists `*[default]* VBA._Collection`.
   A variable gives its declaration, `*local variable* Dim c As Collection`. `Debug`,
   `Debug.Print` and a statement such as `Dim` give nothing, and a type such as `Long` a line
-  about it. Over a procedure's name in its own declaration, hover gives a debug block
+  about it. BETA 983 gives no hover for those three, and BETA 987 a hover whose text is
+  empty, so the add-in must treat both as nothing. Over a procedure's name in its own declaration, hover gives a debug block
   instead, `TB-DEBUG CODEGEN SIZE: [NOT-READY]`; over a `ByVal` parameter of a class,
   `String`, `Variant` or `Object` it adds a wrong note about `Option Explicit`
   ([BUGS-TO-REPORT.md](BUGS-TO-REPORT.md)).
diff --git a/test/addin/symbols.test.mjs b/test/addin/symbols.test.mjs
index ac547d02..a6ec9816 100644
--- a/test/addin/symbols.test.mjs
+++ b/test/addin/symbols.test.mjs
@@ -6,7 +6,7 @@
 // as the code editor's intellisense does (getLiveDebugIntellisenseMonaco).
 // Only page script can ask any of them; the add-in API has no such call.
 //
-// Each test states what BETA 983 does. If one fails after an IDE update, the
+// Each test states what BETA 983 and 987 do. If one fails after an IDE update, the
 // IDE has changed: update P5 in WIP.HelpAddin.md, and the entry in
 // BUGS-TO-REPORT.md that the last hover test rests on, and then this file.
 //
@@ -120,9 +120,12 @@ describe("P5: what the compiler says about the name under the cursor", { skip: l
   test("hover on a variable gives its declaration, and on Debug.Print and a statement nothing", async () => {
     assert.equal(await hover(c, "c.Add", "c"), "*local variable* Dim c As Collection");
     assert.equal(await hover(c, "Nothing, count", "count"), "*parameter* ByVal count As Long");
-    assert.equal(await hover(c, "Debug.Print FindTheNeedle", "Debug"), null);
-    assert.equal(await hover(c, "Debug.Print FindTheNeedle", "Print"), null);
-    assert.equal(await hover(c, "Dim c As New", "Dim"), null);
+    // BETA 983 gives no hover here, and BETA 987 one whose text is empty.
+    const nothing = [["Debug.Print FindTheNeedle", "Debug"], ["Debug.Print FindTheNeedle", "Print"], ["Dim c As New", "Dim"]];
+    for (const [text, word] of nothing) {
+      const h = await hover(c, text, word);
+      assert.ok(h === null || h === "", `${word} in ${text}: ${JSON.stringify(h)}`);
+    }
     assert.match(await hover(c, "ByVal n As Long", "Long"), /^\*\*Long\*\*/);
   });
 

From 6a4400673de95bee75097ebaf0a43c7ef97b31e3 Mon Sep 17 00:00:00 2001
From: Kuba Sunderland-Ober <kuba@mareimbrium.org>
Date: Sun, 27 Sep 2026 14:05:47 +0200
Subject: [PATCH 07/27] render: admonitions find their fences through
 lib/markdown

---
 WIP.Build.md                          |  28 ++++---
 builder/PLAN-TOOLING-REVIEW.md        |  28 +++++++
 builder/render.mjs                    | 103 ++++++++------------------
 docs/Documentation/Authoring.md       |  10 +--
 docs/Documentation/Building.md        |   2 +-
 docs/Documentation/Extending.md       |   5 +-
 docs/Documentation/Pipeline-Stages.md |   4 +-
 docs/Documentation/Tools.md           |   2 +-
 scripts/check_code_regions.mjs        |  17 ++++-
 9 files changed, 103 insertions(+), 96 deletions(-)

diff --git a/WIP.Build.md b/WIP.Build.md
index 170aa1b6..96c5ab3c 100644
--- a/WIP.Build.md
+++ b/WIP.Build.md
@@ -304,7 +304,8 @@ fixed at the rewrite, not by widening the mask.
 
 `rewriteAdmonitions` deliberately runs **outside** the mask. It finds an
 admonition's lines by their `>` markers and strips them, and a masked fence
-inside an admonition takes its markers with it into the stash.
+inside an admonition takes its markers with it into the stash. It asks
+`blockRegions`, with the same parser, which lines are code instead.
 
 ### Whitespace inside inline code is content
 
@@ -522,20 +523,27 @@ comparison matched, the link check passed, and axe has no opinion about a
 blockquote. It was found only because a new entry added to that page rendered
 the same way and looked wrong.
 
-The stasher is a line scan now --- CommonMark closes a fence on a line that is
+The stasher became a line scan --- CommonMark closes a fence on a line that is
 only the fence character, repeated at least as often as in the opener, which is
 a rule about lines rather than something to express as one regex over a whole
-document. Measured across the site, the fix changes four files: `Attributes.html`,
+document. Measured across the site, that fix changed four files: `Attributes.html`,
 `search-data.json` (which indexes it), and the two that record build timings.
 
 The same stasher had a second way to fail: it recognised *backtick* fences only,
-reasoning that `maskCodeRegions` knows about tildes --- but `rewriteAdmonitions` runs
-**outside** the mask by design, so nothing protected a tilde fence. `FENCE_OPEN_RE`
-accepts either character now and closes on the one that opened. `docs/` contains no
-tilde fence, which is why the corpus sweep could never have found it --- the same
-blind spot that makes the ADMONITION_PROBES necessary.
-
-Five probes in `check_code_regions.mjs` assert this direction, and **writing one
+reasoning that `maskCodeRegions` knew about tildes --- but `rewriteAdmonitions` runs
+**outside** the mask by design, so nothing protected a tilde fence. Its opener test
+was made to accept either character and close on the one that opened. `docs/`
+contains no tilde fence, which is why the corpus sweep could never have found it ---
+the same blind spot that makes the ADMONITION_PROBES necessary.
+
+**The stasher is gone.** A scan of its own could still disagree with the parser
+that renders the page: it never saw a fence opened after a definition list's `: `,
+so an admonition written inside one as a sample became a live one. `rewriteAdmonitions`
+asks `blockRegions` from `lib/markdown.mjs`, with the site's parser, and leaves an
+admonition alone when its `[!TYPE]` line is in a region. A fence *inside* an
+admonition is a region too, and the rewrite still strips its `>` markers.
+
+Six probes in `check_code_regions.mjs` assert this direction, and **writing one
 correctly is not obvious**: a mis-paired opener swallows text only as far as the next
 fence marker, so a probe with no fence *after* the admonition passes against the very
 stasher it was written to catch. The damage is always to the prose **between** two
diff --git a/builder/PLAN-TOOLING-REVIEW.md b/builder/PLAN-TOOLING-REVIEW.md
index ffede823..b3de413e 100644
--- a/builder/PLAN-TOOLING-REVIEW.md
+++ b/builder/PLAN-TOOLING-REVIEW.md
@@ -724,6 +724,34 @@ pre-render chain.
 (five variants, `Attributes.md`'s literal fence strings among them) and the new probe pass;
 putting back a private opener test fails the new one.
 
+**Landed.** `stashCodeFences` and its `FENCE_OPEN_RE` are gone, with the comment above them
+that named `maskCodeRegions`. `rewriteAdmonitions(src, md)` asks `blockRegions` with the
+site's parser, which `applyPreRenderRewrites` passes on, and throws a `TypeError` without one,
+as the chain does. It leaves a match alone when the match's `[!TYPE]` line is in a region.
+That is narrower than the entry's "skips the ranges": a fence inside an admonition is a
+region too, and the rewrite must still strip its `> ` markers, so only the opener line
+decides. HTML blocks count as regions, as they do for `splitOnMarker`; the old stash did not
+protect them, but no page has an admonition in one (below). The new comment says what decides
+and points to WIP.Build.md for the two defects the old scan had. Two probes: A3-1's shape
+joins `ADMONITION_PROBES`, six now, with a fence after it that a wrong opener would close on;
+`UNCHANGED_PROBES` gains an admonition written inside a definition-list fence, the shape where
+the old scan and the parser disagree. The gate's failure message and summary line no longer
+name the stasher. Pipeline-Stages (both functions' rows), Extending (its sample passes `md`,
+and a rewrite outside the mask can skip `blockRegions`' lines), Authoring, Building, Tools
+and WIP.Build say so; what WIP.Build tells of the old scan stays in the past tense.
+
+**Verify.** Before the change, over all 912 pages: 632 admonition openers, one of them in a
+region (a fence in `Documentation/Wisdom.md`), which the old stash protected too, and none in
+an indented code block or an HTML block. The tree comparison with the page edits set aside is
+identical (1,461 files online, 1,457 offline, 137 pdf); with them it differs only in
+Authoring, Building, Extending, Pipeline-Stages and Tools online and offline, the search
+data, and `book.html`. `check_code_regions.mjs`: 7, 6, 2 and 11 probes, and `912 file(s), 0
+with altered code regions, 1372 fence(s) in the full parse -- clean`. Four faults each fail
+it with exit 1: the rewrite ignoring the regions (the new unchanged probe, and Wisdom.md's
+fence altered), the rewrite asking a bare parser (the new unchanged probe), a private opener
+test that allows a backtick in the info string, as the old mask's did (both new probes), and
+HEAD's `render.mjs` put back whole, stash and all (the new unchanged probe).
+
 ### C34 — `scripts: convert_em_dash_separators reads code regions from lib/`
 
 **L3-4, L4-7, merged into A3-1.** Its `FENCE_OPEN_RE` (`:59-60`) is byte for byte
diff --git a/builder/render.mjs b/builder/render.mjs
index 8f154284..d09bea49 100644
--- a/builder/render.mjs
+++ b/builder/render.mjs
@@ -15,7 +15,7 @@ import attrs from "markdown-it-attrs";
 import deflist from "markdown-it-deflist";
 import footnote from "markdown-it-footnote";
 
-import { maskCode } from "../lib/markdown.mjs";
+import { blockRegions, maskCode } from "../lib/markdown.mjs";
 import { initHighlighter } from "./highlight.mjs";
 import { countPlugin, findSurvivingPlaceholder } from "./counts.mjs";
 
@@ -115,8 +115,8 @@ export function applyPreRenderRewrites(rawContent, md) {
   // rewriteAdmonitions runs OUTSIDE the mask, and must: it finds an
   // admonition's lines by their `> ` markers and strips them, and a masked
   // fence inside an admonition has taken its markers with it into the stash.
-  // It does its own code handling.
-  return rewriteAdmonitions(code.restore(work));
+  // It asks lib/markdown where the code is itself, with the same parser.
+  return rewriteAdmonitions(code.restore(work), md);
 }
 
 // kramdown accepts unescaped spaces inside `![alt](url)` and `[text](url)`
@@ -1577,76 +1577,38 @@ const ADMONITION_TYPES = {
 // indentation; the gem's regex captures that into \1 and uses it as a
 // per-line anchor on the body lines.
 const ADMONITION_RE = /(^|\n)([ \t]*)>[ \t]*\[!(NOTE|TIP|IMPORTANT|WARNING|CAUTION)\][^\n]*\n((?:\2[ \t]*>[ \t]*[^\n]*(?:\n|$))(?:(?![ \t]*>[ \t]*\[!)\2[ \t]*>[ \t]*[^\n]*(?:\n|$))*)?/g;
-// Stashing the fences used to be one regex --
-// `/(?:^|\n)[ \t]*```[\s\S]*?```/g` -- which paired an opening fence with the
-// next ``` ANYWHERE, including one in the middle of a line.
-// Reference/Attributes.md contains exactly that: a [Description(...)] sample
-// whose argument is a Markdown string built from twinBASIC string literals,
-// two of which are "```basic" and "```". The fence opened at that sample's
-// ```tb line closed on the literal instead of on its own closing line, and
-// every pairing after it was off by one -- so for the rest of the file the
-// stasher had prose and code exactly the wrong way round. None of the page's
-// six admonitions was rewritten, and all six shipped as literal "[!NOTE]"
-// text. One page in 869, and nothing reported it: check_code_regions.mjs
-// compares the code regions, and the damage here is to the prose between them.
+// An admonition written inside a code region is a sample of the syntax, and is
+// left as it is. This rewrite runs outside the mask, so it asks lib/markdown
+// where the regions are, with the site's parser for the reason
+// applyPreRenderRewrites gives. It is the `[!TYPE]` line that decides: a fence
+// INSIDE an admonition is a region too, and the rewrite must still strip its
+// `> ` markers with the rest of the body.
 //
-// CommonMark closes a fence on a line that is only the fence character,
-// repeated at least as often as in the opener. That is a rule about lines, so
-// this is a line scan rather than a cleverer regex.
-//
-// **Tildes are recognised here, and leaving them out was a live defect.** The
-// comment that stood here said they were deliberately skipped because
-// maskCodeRegions knows about them -- but rewriteAdmonitions runs OUTSIDE the
-// mask, by design, because a fence inside an admonition still carries its
-// `> ` markers at that point and this rewrite is what strips them. So nothing
-// protected a tilde fence, and a standalone ``` line inside one was read as an
-// opener: with an odd number of them the pairing ran past the end of the
-// sample and swallowed the prose after it. That is the Attributes.md failure
-// exactly, reachable by a construct CommonMark allows. Measured before the
-// fix: a ~~~ block holding one standalone ``` shipped the following
-// `> [!NOTE]` as literal text, while the 4-backtick form rendered correctly.
-//
-// A fence is closed only by its OWN character, so the close pattern is built
-// from what opened it. An info string may not contain a backtick on a backtick
-// fence, and may contain anything on a tilde fence -- CommonMark's rule, and
-// the reason the two cases are checked separately.
-const FENCE_OPEN_RE = /^([ \t]*)(`{3,}|~{3,})(.*)$/;
-
-function stashCodeFences(src, stashed) {
-  const lines = src.split("\n");
-  const out = [];
-  for (let i = 0; i < lines.length; i++) {
-    const m = FENCE_OPEN_RE.exec(lines[i]);
-    if (!m) { out.push(lines[i]); continue; }
-    const [, indent, ticks, info] = m;
-    if (ticks[0] === "`" && info.includes("`")) { out.push(lines[i]); continue; }
-    const fenceChar = ticks[0] === "`" ? "`" : "~";
-    const closeRe = new RegExp("^[ \\t]*" + fenceChar + "{" + ticks.length + ",}[ \\t]*$");
-    let j = i + 1;
-    while (j < lines.length && !closeRe.test(lines[j])) j++;
-    // An unclosed fence runs to the end of the document, as CommonMark says.
-    const end = Math.min(j, lines.length - 1);
-    // Stashed WITHOUT the opener's own indent: the placeholder is emitted with
-    // that indent in front of it and the restore puts the stashed text back in
-    // the placeholder's place, so carrying the indent in both would double it.
-    // That is visible wherever a literal fence sits inside an indented code
-    // block, such as the page-template skeleton in Documentation/Authoring.md.
-    stashed.push(lines.slice(i, end + 1).join("\n").slice(indent.length));
-    out.push(`${indent}\`\`\`{{CODE_BLOCK_${stashed.length - 1}}}\`\`\``);
-    i = end;
-  }
-  return out.join("\n");
-}
-
-export function rewriteAdmonitions(src) {
+// It used to find fences with a line scan of its own, and that scan is where
+// two defects lived that shipped admonitions as the literal text "[!NOTE]": it
+// once paired a fence with a marker in the middle of a line (the six
+// admonitions of Reference/Attributes.md), and it once saw backtick fences
+// only, so a tilde fence holding a ``` line swallowed the prose after it.
+// WIP.Build.md tells both. A private scan can also disagree with the parser
+// without anyone noticing, which the tooling review's A3-1 reproduced;
+// check_code_regions.mjs probes each shape through the whole chain.
+export function rewriteAdmonitions(src, md) {
+  if (!md) throw new TypeError("rewriteAdmonitions: pass the site's markdown-it instance");
   // CommonMark's normalisation pass converts CRLF/CR to LF before block
   // parsing. We do it up-front so our regexes operate on LF-only input.
   src = src.replace(/\r\n?/g, "\n");
 
-  const stashed = [];
-  let work = stashCodeFences(src, stashed);
+  const inCode = [];
+  for (const r of blockRegions(src, { md })) for (let i = r.start; i < r.end; i++) inCode[i] = true;
+  // The matches arrive in order, so the line count only moves forward.
+  let line = 0;
+  let counted = 0;
+
+  return src.replace(ADMONITION_RE, (match, leading, indent, typeRaw, bodyRaw, offset) => {
+    const at = offset + leading.length;
+    for (; counted < at; counted++) if (src.charCodeAt(counted) === 10) line++;
+    if (inCode[line]) return match;
 
-  work = work.replace(ADMONITION_RE, (_m, leading, indent, typeRaw, bodyRaw) => {
     const type = typeRaw.toLowerCase();
     const meta = ADMONITION_TYPES[type];
     // The body lines all share the same leading indent; strip it plus the
@@ -1656,9 +1618,8 @@ export function rewriteAdmonitions(src) {
     // The gem's `gsub(/^#{indent}\s*>\s*/, "")` was mirrored literally here
     // and the trailing `\s*` is greedy over `\s`, which includes newlines --
     // so it also ate the body's own indentation and swallowed blank lines.
-    // CODE_FENCE_RE cannot protect a fence inside an admonition (the fence
-    // opener is preceded by `> `, which `[ \t]*` does not match), so this
-    // ran over real code samples: Reference/Default/VBA/Interaction/InputBox
+    // A fence inside an admonition is stripped with the rest of the body, so
+    // this ran over real code samples: Reference/Default/VBA/Interaction/InputBox
     // shipped its If/ElseIf/Else bodies flush left, and Reference/Core/Option
     // lost the blank line between its Module and Class examples.
     const stripRe = indent
@@ -1676,8 +1637,6 @@ export function rewriteAdmonitions(src) {
     // a separate markdown block rather than absorbed into the html_block.
     return `${leading}<div class="markdown-alert markdown-alert-${type}" role="${meta.role}" markdown="1">\n<p class="markdown-alert-title">${meta.icon} ${meta.title}</p>\n\n${body}\n</div>\n\n`;
   });
-
-  return work.replace(/```\{\{CODE_BLOCK_(\d+)\}\}```/g, (_, n) => stashed[Number(n)]);
 }
 
 // ---------- markdown="1" attribute strip -----------------------------------
diff --git a/docs/Documentation/Authoring.md b/docs/Documentation/Authoring.md
index d76a3642..d123339a 100644
--- a/docs/Documentation/Authoring.md
+++ b/docs/Documentation/Authoring.md
@@ -419,9 +419,9 @@ with four backticks and close with four:
     ````
 
 Nothing else changes. A fence closes only on a run at least as long as the one
-that opened it, and both pre-render passes that have to find fences apply that
-same rule --- `maskCode`, which hides code from the rewrites, and the
-fence stasher inside `rewriteAdmonitions`, which is the one that matters here
+that opened it, and both pre-render passes that have to find fences get them from
+the site's own parser, through `lib/markdown.mjs` --- `maskCode`, which hides code
+from the rewrites, and `rewriteAdmonitions`, which is the one that matters here
 because it runs *outside* the mask by design. The language tag reaching the
 highlighter is the same string either way --- a four-backtick `tb` fence is highlighted exactly as a
 three-backtick one is. No page in `docs/` uses one yet, so there is no example to
@@ -437,8 +437,8 @@ longer backtick run is the one construct here with a shipped precedent.
 That failure is not hypothetical. The attribute reference once shipped all six of
 its admonitions as the literal text `[!NOTE]`, because the same pairing closed
 that page's opening fence on a marker in the middle of a line and every pairing
-after it was off by one. The mid-line case is fixed --- the rewrite scans lines
-now --- and [`check_code_regions.mjs`](Tools#check-code-regions), which
+after it was off by one. The mid-line case is fixed --- the rewrite now asks the
+site's parser where the fences are --- and [`check_code_regions.mjs`](Tools#check-code-regions), which
 `test.bat` runs, is the only gate that sees this class of fault at all.
 
 ### Typography
diff --git a/docs/Documentation/Building.md b/docs/Documentation/Building.md
index c3b0649c..8ae2bad8 100644
--- a/docs/Documentation/Building.md
+++ b/docs/Documentation/Building.md
@@ -453,7 +453,7 @@ and restored unchanged --- it simply never fires. That is how
 admonitions as the literal text `[!NOTE]`: a twinBASIC string literal holding a
 fence marker closed the fence around it, and every pairing for the rest of the
 page was off by one. The gate keeps fixed probes for that rather than sweeping
-the corpus, so a green line says the fence stasher still works --- it does not
+the corpus, so a green line says the rewrites still find the code the parser finds --- it does not
 say your own page came out right. Read that one in
 [`serve.bat`](#building-and-local-serving) as well.
 
diff --git a/docs/Documentation/Extending.md b/docs/Documentation/Extending.md
index 8fa4c1ca..bd20454c 100644
--- a/docs/Documentation/Extending.md
+++ b/docs/Documentation/Extending.md
@@ -116,12 +116,13 @@ rewrite runs:
    work = rewriteTripleAsteriskEmphasis(work);
    // ... the other masked rewrites ...
    work = yourRewrite(work);
-   return rewriteAdmonitions(code.restore(work));
+   return rewriteAdmonitions(code.restore(work), md);
    ```
 
 2. **For an indented code block, the mask cannot help.** It does not cover indented blocks
    on purpose. Narrow the rewrite so it cannot match the block's
-   lines, and let the gate say when it no longer does.
+   lines, and let the gate say when it no longer does. A rewrite that has to run outside
+   the mask can instead skip the lines `blockRegions` reports, as `rewriteAdmonitions` does.
 3. **Do not widen the mask to make the report go away.** Text the mask hides is text no
    rewrite reaches, so a mask that hides prose stops the rewrites firing on it --- and the
    region comparison cannot see that, because the hidden text comes back unchanged.
diff --git a/docs/Documentation/Pipeline-Stages.md b/docs/Documentation/Pipeline-Stages.md
index 7aa565de..f31175b0 100644
--- a/docs/Documentation/Pipeline-Stages.md
+++ b/docs/Documentation/Pipeline-Stages.md
@@ -651,12 +651,12 @@ Runs two build-aborting integrity checks before building the tree: `validatePerm
 | Symbol | Signature | Description |
 |---|---|---|
 | `renderPhase` | `(pages, site, staticFiles?) → Promise<void>` | Renders each page's `rawContent` to `renderedContent` via the supplied site's markdown-it. Skips `layout: book-combined`. |
-| `applyPreRenderRewrites` | `(rawContent, md) → string` | The whole pre-render source rewrite chain, as the render stage applies it to each page before parsing: normalises line endings to LF, masks code with `maskCode` from `lib/markdown.mjs` using the site's markdown-it instance `md`, runs the four kramdown-parity rewrites, restores the code, then runs `rewriteAdmonitions`. Throws a `TypeError` when `md` is omitted. Exported so `check_code_regions.mjs` and `check_examples.mjs` test the real chain rather than a copy of it. |
+| `applyPreRenderRewrites` | `(rawContent, md) → string` | The whole pre-render source rewrite chain, as the render stage applies it to each page before parsing: normalises line endings to LF, masks code with `maskCode` from `lib/markdown.mjs` using the site's markdown-it instance `md`, runs the four kramdown-parity rewrites, restores the code, then runs `rewriteAdmonitions` with the same instance. Throws a `TypeError` when `md` is omitted. Exported so `check_code_regions.mjs` and `check_examples.mjs` test the real chain rather than a copy of it. |
 | `createMarkdownIt` | `({ highlighter, linkTables, baseurl, staticFiles, svgContents?, vendoredVideos?, vendoredImages?, counts? }) → MarkdownIt` | Builds the configured markdown-it instance: the eighteen plugins tabulated below, in their fixed order, plus eight renderer-rule overrides assigned directly. `svgContents` is a `Map<srcRel, string>` of pre-read SVG file contents; when present, `svgInlinePlugin` replaces a lone `.svg` image with an inline SVG wrapper. `vendoredVideos` and `vendoredImages` are the maps `videoLinkPlugin` and `remoteImagePlugin` resolve against, and `counts` is the registry `countPlugin` substitutes from. See [Extending](Extending#adding-a-markdown-it-plugin) for how to add a plugin. |
 | `initHighlighter` | (re-export from `highlight.mjs`) | `() → Promise<object>`. Initialises Shiki with the bundled twinBASIC grammar. |
 | `buildLinkTables` | `(pages) → { byPath, byUrl, byRedirect }` | Map lookups keyed by `srcRel`, `permalink`, and `redirect_from` entries. |
 | `serializeLinkTables` | `(lt) → { byPath, byUrl, byRedirect }` | Serializes the Maps to `[key, permalink]` pair arrays for structured-clone transfer to workers. |
-| `rewriteAdmonitions` | `(src) → string` | GFM admonition rewrite to the `markdown-alert markdown-alert-<type>` class structure with the five SVG octicons. |
+| `rewriteAdmonitions` | `(src, md) → string` | GFM admonition rewrite to the `markdown-alert markdown-alert-<type>` class structure with the five SVG octicons. Leaves an admonition alone when its `[!TYPE]` line is inside a region that `blockRegions` from `lib/markdown.mjs` reports with the site's markdown-it instance `md`; a fence inside an admonition is part of its body. Throws a `TypeError` when `md` is omitted. |
 #### The plugin chain
 
 `createMarkdownIt` applies eighteen plugins in a fixed order: three from npm, fourteen defined in `render.mjs` itself, and `countPlugin` from `counts.mjs`. Most of the in-tree ones exist to close a behavioural gap between markdown-it and kramdown, which rendered this content under Jekyll --- the site's ~870 pages were authored against kramdown's dialect, so matching it is a compatibility requirement rather than a preference.
diff --git a/docs/Documentation/Tools.md b/docs/Documentation/Tools.md
index 3f9d6034..1e03f6c6 100644
--- a/docs/Documentation/Tools.md
+++ b/docs/Documentation/Tools.md
@@ -425,7 +425,7 @@ Probes ride along in the normal run, each a defect this repository actually ship
 
 The admonition probes test the mirror fault, which the region comparison structurally cannot see: **a rewrite that misreads what is code can also fail to fire on real prose**, and the regions still come back identical because the text was only stashed and restored. `Reference/Attributes.md` shipped all six of its admonitions as the literal text `[!NOTE]` for exactly that reason --- a `[Description(...)]` sample whose argument is a Markdown string containing two fence markers as twinBASIC string literals, which the fence stasher closed the surrounding fence on. Every pairing after it was off by one.
 
-It is also the gate on `lib/markdown.mjs` and `lib/frontmatter.mjs`, the modules that tell the tools what in a page is code and where its frontmatter ends. Their probes run with the others, and on every page the sweep checks that `blockRegions`, which parses blocks only, finds exactly the fences, code blocks and HTML blocks of a full parse. The summary line gives the number of fences that full parse found. Two more probes hold the build to the same answer: the rewrite chain must leave alone a fence that only the site's parser finds, and the build's check of `{{tbdocs:<name>}}` count names must skip names in code and give an unknown one's line in its file.
+It is also the gate on `lib/markdown.mjs` and `lib/frontmatter.mjs`, the modules that tell the tools what in a page is code and where its frontmatter ends. Their probes run with the others, and on every page the sweep checks that `blockRegions`, which parses blocks only, finds exactly the fences, code blocks and HTML blocks of a full parse. The summary line gives the number of fences that full parse found. Three more probes hold the build to the same answer: the rewrite chain must leave alone a fence that only the site's parser finds, and an admonition written inside one, and the build's check of `{{tbdocs:<name>}}` count names must skip names in code and give an unknown one's line in its file.
 
 `--verbose` prints the first few altered regions of each failing file, before and after. `--self-test` replaces the normal run rather than adding to it, so neither the probes nor the sweep runs: it de-indents the body of one small fence by hand and passes only if the comparison notices. That proves the comparator can still see a change, and nothing more --- it runs no rewrite at all.
 
diff --git a/scripts/check_code_regions.mjs b/scripts/check_code_regions.mjs
index 3aaf9261..296b91c2 100644
--- a/scripts/check_code_regions.mjs
+++ b/scripts/check_code_regions.mjs
@@ -186,16 +186,27 @@ const ADMONITION_PROBES = [
   // sweep would never have found it.
   ["admonition after a tilde fence holding a lone fence marker",
     "prose\n\n~~~markdown\nsample\n```\n~~~\n\n> [!NOTE]\n> body\n\n```tb\nDim y\n```\n"],
+  // A3-1. A backtick in a backtick fence's info string opens no fence, so the
+  // admonition after it is prose. An opener test that took the line for one,
+  // as the chain's old mask did, closes it on the last line here and hides the
+  // admonition inside.
+  ["admonition after a line that a backtick in its info string keeps from opening a fence",
+    "```abc`def\n> [!NOTE]\n> body\n\n```tb\nDim y\n```\n"],
 ];
 
 // Sources the whole chain must return byte for byte. The first holds the chain
 // to the site's parser: the definition-list plugin makes a fence after `: `
 // that a bare parser reads as a paragraph, and masked with a bare parser, the
 // fence's body is rewritten (`a,%20b`). The region comparison cannot see that,
-// because it parses bare too and finds no fence there to compare.
+// because it parses bare too and finds no fence there to compare. The second
+// holds the admonition rewrite, which runs outside the mask, to the same
+// parser: the line scan it had never saw a fence open after `: `, and turned
+// the sample inside into a live admonition.
 const UNCHANGED_PROBES = [
   ["a fence the definition-list plugin makes",
     "Term\n: ```tb\n  v = Items[1](a, b)\n  ```\n"],
+  ["an admonition written inside a fence the definition-list plugin makes",
+    "Term\n: ```md\n  > [!NOTE]\n  > body\n  ```\n"],
 ];
 
 // The regions blockRegions reports, in a form assert can compare at a glance.
@@ -356,7 +367,7 @@ async function main(argv) {
     if (applyRewrites(src).includes("markdown-alert")) continue;
     failed++;
     console.log(`FAIL  probe: ${name}`);
-    console.log(`        the admonition was not rewritten -- the fence stasher`);
+    console.log(`        the admonition was not rewritten -- the chain`);
     console.log(`        mistook the prose around it for code`);
   }
   for (const [name, src] of UNCHANGED_PROBES) {
@@ -390,7 +401,7 @@ async function main(argv) {
   if (!failed) {
     console.log(`ok    ${PROBES.length} probes: no rewrite alters a code region`);
     console.log(`ok    ${ADMONITION_PROBES.length} probes: a rewrite still fires on prose beside code`);
-    console.log(`ok    ${UNCHANGED_PROBES.length} probe(s): the chain masks what the site's parser calls code`);
+    console.log(`ok    ${UNCHANGED_PROBES.length} probe(s): the chain leaves alone what the site's parser calls code`);
     console.log(`ok    ${MODULE_PROBES.length} probes: lib/markdown.mjs and lib/frontmatter.mjs`);
     console.log("ok    1 probe: the count validator skips code and names the file's line");
   }

From f413861290d0e9580bbac1c9cade253a5c17bb49 Mon Sep 17 00:00:00 2001
From: Kuba Sunderland-Ober <kuba@mareimbrium.org>
Date: Sun, 27 Sep 2026 14:20:50 +0200
Subject: [PATCH 08/27] scripts: convert_em_dash_separators reads code regions
 from lib/

---
 WIP.md                                 |   2 +-
 builder/PLAN-TOOLING-REVIEW.md         |  40 +++++++++
 docs/Documentation/Tools.md            |   6 +-
 scripts/check_code_regions.mjs         |  42 ++++++++-
 scripts/convert_em_dash_separators.mjs | 113 +++++++------------------
 5 files changed, 114 insertions(+), 89 deletions(-)

diff --git a/WIP.md b/WIP.md
index db66a899..b33d18b8 100644
--- a/WIP.md
+++ b/WIP.md
@@ -501,7 +501,7 @@ wrapper:
 | `check.bat` | `check_tree_fresh` | the tree is not older than the sources that produced it |
 | `check.bat` | `check_dot_fit` | every diagram label sits inside the box Graphviz drew for it |
 | `check.bat` | `pick_a11y_sample --check`, `check_a11y` | see [WIP.A11y.md](WIP.A11y.md) |
-| `test.bat` | `check_code_regions` | no source or HTML rewrite altered a code region; `lib/markdown.mjs` and `lib/frontmatter.mjs` pass their probes, and the block parse finds what the full parse finds; the count-name check skips code and names the file's line |
+| `test.bat` | `check_code_regions` | no source or HTML rewrite altered a code region; `lib/markdown.mjs` and `lib/frontmatter.mjs` pass their probes, and the block parse finds what the full parse finds; the count-name check skips code and names the file's line; the dash normaliser converts only prose |
 | `test.bat` | `check_regex_safety` | no regex in the tree can backtrack exponentially |
 | `test.bat` | `check_symbol_index` | the symbol index still places each kind of symbol, from fixtures |
 | `test.bat` | `check_ci_workflows` | both CI workflows run every wrapper gate, with the same arguments and order, and build with `build.bat`'s flags |
diff --git a/builder/PLAN-TOOLING-REVIEW.md b/builder/PLAN-TOOLING-REVIEW.md
index b3de413e..3e6019b7 100644
--- a/builder/PLAN-TOOLING-REVIEW.md
+++ b/builder/PLAN-TOOLING-REVIEW.md
@@ -767,6 +767,37 @@ kept by the module's splice. The file's accepted gap for two-space list-item fen
 endings, a doubled-backtick span and a list-item fence has only its prose converted, and
 keeps its endings.
 
+**Landed.** `convertText(text, md)` takes its code regions from `blockRegions` with the
+site's parser, which `main` builds with `createMarkdownIt`, and throws a `TypeError` without
+one, as the build's two rewrites do. A line inside any region is left alone, and the other
+lines go through `splitCodeSpans`, rejoined by `mapLines`. HTML blocks count, because the
+typographer converts only text tokens, so a dash in one is literal on the page. `FENCE_OPEN_RE`,
+`FENCE_CLOSE_RE`, `splitInlineCode` and `KEEP_ENDS` are gone, and so is the comment on the
+known gap for indented code blocks, which this closes. The entry's gap for two-space
+list-item fences was already closed by `427f77a6`, whose opener allows up to three spaces.
+**The old scan closed no fence** (see Found while implementing), and deleting it is the fix,
+at the owner's choice. Also at the owner's choice, the entry's seeded file became seven
+permanent `DASH_PROBES` in `check_code_regions.mjs`: a fence after an earlier fence with CRLF
+and lone-CR endings, a doubled-backtick span, a fence five spaces into a nested list item,
+one behind `> `, an indented code block beside an HTML block, a definition-list fence, and a
+See Also separator. Tools.md's two sections and WIP.md's gate row say so. The exit paragraph
+in Tools.md now says "any other probe" where it named module probes and left out two kinds.
+
+**Verify.** `--check` over `docs/` exits 0 before and after, with `Files affected: 0`. Over
+all 912 pages against the old scan: 37,861 lines it read as code are prose to `blockRegions`,
+in 1,386 runs across 598 files, all after the page's first fence. 304 lines it read as prose
+are code now: 15 in fences behind `> `, 180 in indented code blocks and 109 in HTML blocks.
+The pages hold 77 literal dashes in fences and 4 on other lines, all four in code spans
+(`Authoring.md:388`, `Tools.md:596`), so no dash got past the old scan. The site's parser and
+a bare one find the same regions on every page, and so do the whole file and its content
+after the frontmatter. `check_code_regions.mjs`: 7, 6, 2, 7, 11 and 1 probes, and `912
+file(s), 0 with altered code regions, 1372 fence(s) in the full parse -- clean`. Six faults
+each fail it with exit 1: HEAD's scan put back and the regions
+ignored each fail five probes, the first among them; a bare parser fails the definition-list
+probe; skipping fences only fails the indented-block probe; unsplit code spans fail the span
+probe; and normalised line endings fail the first. The tree comparison differs only in Tools
+online and offline, the search data, and `book.html`.
+
 ### C35 — `scripts: check_examples' marker splice uses lib/markdown's line splice`
 
 **Inventory site A4.** `applyMarkers` (`check_examples.mjs:1123-1154`) already finds its line
@@ -1911,6 +1942,15 @@ Defects the review did not have, found by building something this plan asks for.
   on line 12 below three lines of frontmatter and a five-line fence. The build still failed;
   only the line it named was wrong. Fixed in `builder: an unknown count name is reported at
   its file line`.
+- **`convert_em_dash_separators.mjs` closed no fence**, found while landing C34. Its closing
+  test, `FENCE_CLOSE_RE`, ends in `[ \t]*$` without the `m` flag, and each line it tested
+  still carried its line ending, so a closing fence matched only as a page's last line with
+  no ending. From a page's first fence on, the tool converted nothing and `--check` reported
+  nothing: 37,861 prose lines in 598 of 912 pages. It came in with `427f77a6` (2026-09-21),
+  whose close test replaced the port's toggle on any line starting with three backticks,
+  and nothing tested the tool. No literal
+  dash got past it. Fixed in `scripts: convert_em_dash_separators reads code regions from
+  lib/`, which deletes the scan and adds the tool's probes to `check_code_regions.mjs`.
 
 ## Open questions
 
diff --git a/docs/Documentation/Tools.md b/docs/Documentation/Tools.md
index 1e03f6c6..7a7f0e65 100644
--- a/docs/Documentation/Tools.md
+++ b/docs/Documentation/Tools.md
@@ -425,11 +425,11 @@ Probes ride along in the normal run, each a defect this repository actually ship
 
 The admonition probes test the mirror fault, which the region comparison structurally cannot see: **a rewrite that misreads what is code can also fail to fire on real prose**, and the regions still come back identical because the text was only stashed and restored. `Reference/Attributes.md` shipped all six of its admonitions as the literal text `[!NOTE]` for exactly that reason --- a `[Description(...)]` sample whose argument is a Markdown string containing two fence markers as twinBASIC string literals, which the fence stasher closed the surrounding fence on. Every pairing after it was off by one.
 
-It is also the gate on `lib/markdown.mjs` and `lib/frontmatter.mjs`, the modules that tell the tools what in a page is code and where its frontmatter ends. Their probes run with the others, and on every page the sweep checks that `blockRegions`, which parses blocks only, finds exactly the fences, code blocks and HTML blocks of a full parse. The summary line gives the number of fences that full parse found. Three more probes hold the build to the same answer: the rewrite chain must leave alone a fence that only the site's parser finds, and an admonition written inside one, and the build's check of `{{tbdocs:<name>}}` count names must skip names in code and give an unknown one's line in its file.
+It is also the gate on `lib/markdown.mjs` and `lib/frontmatter.mjs`, the modules that tell the tools what in a page is code and where its frontmatter ends. Their probes run with the others, and on every page the sweep checks that `blockRegions`, which parses blocks only, finds exactly the fences, code blocks and HTML blocks of a full parse. The summary line gives the number of fences that full parse found. Three more probes hold the build to the same answer: the rewrite chain must leave alone a fence that only the site's parser finds, and an admonition written inside one, and the build's check of `{{tbdocs:<name>}}` count names must skip names in code and give an unknown one's line in its file. Another set holds [`convert_em_dash_separators.mjs`](#convert-em-dash-separators), which rewrites page source by hand rather than in the build, to converting prose and nothing else.
 
 `--verbose` prints the first few altered regions of each failing file, before and after. `--self-test` replaces the normal run rather than adding to it, so neither the probes nor the sweep runs: it de-indents the body of one small fence by hand and passes only if the comparison notices. That proves the comparator can still see a change, and nothing more --- it runs no rewrite at all.
 
-Exits 1 when a code region differs, when a probe's admonition is not rewritten, when a module probe fails or the two parses disagree on a page, or when `--self-test`'s de-indent goes unnoticed, and 2 when the gate itself cannot run. [When `test.bat` fails in `check_code_regions`](Extending#code-regions-altered) says what to change.
+Exits 1 when a code region differs, when a probe's admonition is not rewritten, when any other probe fails or the two parses disagree on a page, or when `--self-test`'s de-indent goes unnoticed, and 2 when the gate itself cannot run. [When `test.bat` fails in `check_code_regions`](Extending#code-regions-altered) says what to change.
 
 ### check_gate_lists.mjs
 {: #check-gate-lists }
@@ -593,7 +593,7 @@ It shares [`census_attributes.mjs`](#census-attributes)'s export and cache, and
     node scripts/convert_em_dash_separators.mjs            # rewrite in place
     node scripts/convert_em_dash_separators.mjs --check    # report, change nothing
 
-Normalises literal en-dash / em-dash characters in markdown source under `docs/` to the ASCII source forms markdown-it's typographer converts at build time (`--` for en-dash, `---` for em-dash). The site forbids literal `–` / `—` in source --- this is the canonical fixer if any slip back in. Skips fenced code blocks and inline code spans, and preserves each file's existing line endings. `--check` reports what it would change and exits non-zero without writing, so it can serve as a gate.
+Normalises literal en-dash / em-dash characters in markdown source under `docs/` to the ASCII source forms markdown-it's typographer converts at build time (`--` for en-dash, `---` for em-dash). The site forbids literal `–` / `—` in source --- this is the canonical fixer if any slip back in. Skips what the site's parser reads as code --- fences, indented code blocks and HTML blocks, found through `lib/markdown.mjs` --- and inline code spans, and preserves each file's existing line endings. Its probes run in [`check_code_regions.mjs`](#check-code-regions). `--check` reports what it would change and exits non-zero without writing, so it can serve as a gate.
 
 ### survey_tooling.mjs
 {: #survey-tooling }
diff --git a/scripts/check_code_regions.mjs b/scripts/check_code_regions.mjs
index 296b91c2..90d00aa8 100644
--- a/scripts/check_code_regions.mjs
+++ b/scripts/check_code_regions.mjs
@@ -65,7 +65,8 @@
 // blockRegions, which parses blocks only, finds exactly the fences, code
 // blocks and HTML blocks of the full parse the comparison already makes. One
 // probe holds builder/counts.mjs's count validator, which asks the same module
-// what is code.
+// what is code, and a set holds scripts/convert_em_dash_separators.mjs, which
+// rewrites page source outside the build and asks it too.
 
 import assert from "node:assert/strict";
 import { promises as fs } from "node:fs";
@@ -81,6 +82,7 @@ import { applyPreRenderRewrites, createMarkdownIt } from "../builder/render.mjs"
 import { parseFrontmatter } from "../lib/frontmatter.mjs";
 import { blockRegions, mapLines, maskCode, splitCodeSpans, splitOnMarker } from "../lib/markdown.mjs";
 import { markdownFiles } from "../lib/markdown-files.mjs";
+import { convertText } from "./convert_em_dash_separators.mjs";
 
 const REPO = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
 const ROOT = path.join(REPO, "docs");
@@ -209,6 +211,34 @@ const UNCHANGED_PROBES = [
     "Term\n: ```md\n  > [!NOTE]\n  > body\n  ```\n"],
 ];
 
+// The dash normaliser: a source, what the tool must make of it, and how many
+// separator, em-dash and en-dash replacements it counts. Its own line scan
+// closed no fence, because the closing test ended in `$` and every line still
+// carried its ending, so after a page's first fence it converted nothing; the
+// first probe is that shape. The scan also never saw a fence indented four
+// spaces or more, or behind `> ` or `: `, an indented code block or an HTML
+// block, and the typographer converts none of them.
+const DASH_PROBES = [
+  ["a fence after an earlier fence, with CRLF and lone CR endings",
+    "```tb\r\na \u{2014} b\r\n```\r\n\r\nc \u{2014} d\re \u{2013} f\r\n",
+    "```tb\r\na \u{2014} b\r\n```\r\n\r\nc --- d\re -- f\r\n", "0/1/1"],
+  ["a doubled-backtick code span holding a single backtick",
+    "x ``a \u{2014} `b` c`` y \u{2013} z\n", "x ``a \u{2014} `b` c`` y -- z\n", "0/0/1"],
+  ["a fence in a nested list item, five spaces in",
+    "1. a\n\n   - b\n\n     ```tb\n     x \u{2014} y\n     ```\n",
+    "1. a\n\n   - b\n\n     ```tb\n     x \u{2014} y\n     ```\n", "0/0/0"],
+  ["a fence inside an admonition",
+    "> [!NOTE]\n> ```tb\n> a \u{2014} b\n> ```\n> c \u{2014} d\n",
+    "> [!NOTE]\n> ```tb\n> a \u{2014} b\n> ```\n> c --- d\n", "0/1/0"],
+  ["an indented code block and an HTML block",
+    "text\n\n    a \u{2014} b\n\n<div>\nc \u{2014} d\n</div>\n",
+    "text\n\n    a \u{2014} b\n\n<div>\nc \u{2014} d\n</div>\n", "0/0/0"],
+  ["a fence the definition-list plugin makes",
+    "Term\n: ```tb\n  a \u{2014} b\n  ```\n", "Term\n: ```tb\n  a \u{2014} b\n  ```\n", "0/0/0"],
+  ["a See Also separator, then an em-dash in prose",
+    "- [X](X) \u{2014} one \u{2014} two\n", "- [X](X) -- one --- two\n", "1/1/0"],
+];
+
 // The regions blockRegions reports, in a form assert can compare at a glance.
 const regionsOf = (src, options) => blockRegions(src, options).map((r) => `${r.type} ${r.start}-${r.end}`);
 
@@ -378,6 +408,15 @@ async function main(argv) {
     console.log(`        before ${JSON.stringify(src)}`);
     console.log(`        after  ${JSON.stringify(after)}`);
   }
+  for (const [name, src, want, counts] of DASH_PROBES) {
+    const r = convertText(src, siteMd);
+    const got = `${r.sep}/${r.em}/${r.en}`;
+    if (r.text === want && got === counts) continue;
+    failed++;
+    console.log(`FAIL  probe: ${name}`);
+    console.log(`        want ${JSON.stringify(want)} (${counts})`);
+    console.log(`        got  ${JSON.stringify(r.text)} (${got})`);
+  }
   // Anything but a failed assertion is the gate breaking, and goes to exit 2.
   for (const [name, probe] of MODULE_PROBES) {
     try {
@@ -402,6 +441,7 @@ async function main(argv) {
     console.log(`ok    ${PROBES.length} probes: no rewrite alters a code region`);
     console.log(`ok    ${ADMONITION_PROBES.length} probes: a rewrite still fires on prose beside code`);
     console.log(`ok    ${UNCHANGED_PROBES.length} probe(s): the chain leaves alone what the site's parser calls code`);
+    console.log(`ok    ${DASH_PROBES.length} probes: the dash normaliser converts prose and nothing else`);
     console.log(`ok    ${MODULE_PROBES.length} probes: lib/markdown.mjs and lib/frontmatter.mjs`);
     console.log("ok    1 probe: the count validator skips code and names the file's line");
   }
diff --git a/scripts/convert_em_dash_separators.mjs b/scripts/convert_em_dash_separators.mjs
index f4b66e8e..3e880f89 100644
--- a/scripts/convert_em_dash_separators.mjs
+++ b/scripts/convert_em_dash_separators.mjs
@@ -26,8 +26,13 @@
 //   * Every other em-dash becomes `---` (renders as em-dash, unchanged).
 //   * Every en-dash becomes `--` (renders as en-dash, unchanged).
 //
-// Code is skipped: fenced blocks are left intact, and so is anything inside an
-// inline code span on a prose line.
+// Code is skipped as the site's own parser finds it: every fence, indented code
+// block and HTML block that lib/markdown.mjs's blockRegions reports, and every
+// code span on the other lines. The typographer converts none of them, so a
+// dash there is literal on the page and must stay literal in the source.
+// Frontmatter is not recognised, so its lines are prose here. Not followed:
+// the two gaps splitCodeSpans states, and an attribute inside inline HTML,
+// which the typographer also leaves alone.
 //
 // LINE ENDINGS ARE PRESERVED BYTE-FOR-BYTE, which the Python predecessor did
 // not do. `Path.read_text` / `write_text` apply universal-newline translation,
@@ -39,6 +44,8 @@ import { promises as fs } from "node:fs";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
+import { createMarkdownIt } from "../builder/render.mjs";
+import { blockRegions, mapLines, splitCodeSpans } from "../lib/markdown.mjs";
 import { markdownFiles } from "../lib/markdown-files.mjs";
 
 const REPO = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
@@ -50,62 +57,9 @@ const EN_DASH = "–";
 // First em-dash after a `[link](url)` on a bullet line. The negated class stops
 // at a backtick so the match cannot reach into an inline-code span.
 const SEPARATOR_RE = new RegExp(
-  String.raw`^(- \[.*?\]\(.*?\)[^` + EM_DASH + String.raw`\n\x60]*)` + EM_DASH,
+  String.raw`^(- \[.*?\]\(.*?\)[^` + EM_DASH + String.raw`\x60]*)` + EM_DASH,
 );
 
-// A fenced-code-block opener. CommonMark allows up to three leading spaces,
-// tilde fences as well as backtick ones, and any run length of three or more;
-// a closer must use the same character and be at least as long. Anchoring this
-// at column 0 with exactly three backticks -- as it was -- let an indented
-// fence through as prose. Reference/Core/Get.md and Option.md carry 2-space
-// fences of exactly that shape.
-const FENCE_OPEN_RE = /^[ \t]{0,3}(`{3,}|~{3,})/;
-const FENCE_CLOSE_RE = /^[ \t]{0,3}(`+|~+)[ \t]*$/;
-
-// Known gap: an indented (4-space) code block is still treated as prose --
-// Documentation/Authoring.md's page-template skeleton is one, and the ```tb
-// inside it is literal text rather than a fence. Telling such a block from a
-// list-item continuation needs block context this line-at-a-time pass does
-// not have, and guessing would rewrite real list content. Nothing in the
-// corpus currently trips it, and a missed conversion is the safe direction:
-// it leaves a literal dash in source rather than corrupting a code sample.
-
-// Split a line into alternating prose / inline-code segments, handling a
-// backtick run of any length -- ``a `b` c`` is one span. The previous regex
-// matched single-backtick spans only, so an em-dash inside a doubled-backtick
-// span was rewritten as prose.
-function splitInlineCode(line) {
-  const parts = [];
-  let buf = "";
-  let k = 0;
-  while (k < line.length) {
-    if (line[k] !== "`") { buf += line[k++]; continue; }
-    let n = 0;
-    while (line[k + n] === "`") n++;
-    let p = k + n;
-    let found = -1;
-    while (p < line.length) {
-      if (line[p] === "`") {
-        let m = 0;
-        while (line[p + m] === "`") m++;
-        if (m === n) { found = p; break; }
-        p += m;
-      } else p++;
-    }
-    if (found < 0) { buf += line.slice(k, k + n); k += n; continue; }
-    if (buf) { parts.push({ code: false, text: buf }); buf = ""; }
-    parts.push({ code: true, text: line.slice(k, found + n) });
-    k = found + n;
-  }
-  if (buf) parts.push({ code: false, text: buf });
-  return parts;
-}
-
-// Split keeping line terminators, so the text rejoins unchanged. Python's
-// `splitlines(keepends=True)` also breaks on a bare CR; this matches that
-// without splitting CRLF in two.
-const KEEP_ENDS = /(?<=\n)|(?<=\r)(?!\n)/;
-
 function countOf(haystack, needle) {
   let n = 0;
   for (let i = haystack.indexOf(needle); i !== -1; i = haystack.indexOf(needle, i + 1)) n++;
@@ -125,7 +79,7 @@ function processLine(line) {
   // Step 2: remaining em-dash -> `---`, en-dash -> `--`, outside code spans.
   let em = 0;
   let en = 0;
-  const parts = splitInlineCode(line).map(({ code, text }) => {
+  const parts = splitCodeSpans(line).map(({ code, text }) => {
     if (code) return text;
     em += countOf(text, EM_DASH);
     en += countOf(text, EN_DASH);
@@ -135,37 +89,27 @@ function processLine(line) {
   return { line: parts.join(""), sep, em, en };
 }
 
-export function convertText(text) {
-  const out = [];
+// `md` is the site's markdown-it instance: its definition-list plugin makes a
+// fence after `: ` that a bare parser reads as prose.
+export function convertText(text, md) {
+  if (!md) throw new TypeError("convertText: pass the site's markdown-it instance");
   let sep = 0;
   let em = 0;
   let en = 0;
 
-  let fenceMarker = null;
-  for (const line of text.split(KEEP_ENDS)) {
-    if (fenceMarker === null) {
-      const open = line.match(FENCE_OPEN_RE);
-      if (open) {
-        fenceMarker = open[1];
-        out.push(line);
-        continue;
-      }
-    } else {
-      const close = line.match(FENCE_CLOSE_RE);
-      if (close && close[1][0] === fenceMarker[0] && close[1].length >= fenceMarker.length) {
-        fenceMarker = null;
-      }
-      out.push(line);
-      continue;
-    }
-    const r = processLine(line);
-    sep += r.sep;
-    em += r.em;
-    en += r.en;
-    out.push(r.line);
-  }
+  const regions = blockRegions(text, { md });
+  let r = 0;
+  const out = mapLines(text, (line, i) => {
+    while (regions[r] && regions[r].end <= i) r++;
+    if (regions[r] && regions[r].start <= i) return line;
+    const p = processLine(line);
+    sep += p.sep;
+    em += p.em;
+    en += p.en;
+    return p.line;
+  });
 
-  return { text: out.join(""), sep, em, en };
+  return { text: out, sep, em, en };
 }
 
 // Python sorts `Path` objects, which on Windows compare as a tuple of
@@ -188,10 +132,11 @@ async function main(argv) {
   let sep = 0;
   let em = 0;
   let en = 0;
+  const md = createMarkdownIt({ highlighter: null, linkTables: null, baseurl: "", staticFiles: new Set() });
 
   for (const rel of (await markdownFiles(ROOT)).sort(byPathParts)) {
     const abs = path.join(ROOT, rel);
-    const r = convertText(await fs.readFile(abs, "utf8"));
+    const r = convertText(await fs.readFile(abs, "utf8"), md);
     if (r.sep + r.em + r.en === 0) continue;
 
     if (!check) await fs.writeFile(abs, r.text, "utf8");

From fcd1f68acfad7c1802dd84350ed48fd0b22160b8 Mon Sep 17 00:00:00 2001
From: Kuba Sunderland-Ober <kuba@mareimbrium.org>
Date: Sun, 27 Sep 2026 14:24:27 +0200
Subject: [PATCH 09/27] scripts: check_examples' marker splice uses
 lib/markdown's line splice

---
 builder/PLAN-TOOLING-REVIEW.md | 16 ++++++++++++++++
 scripts/check_examples.mjs     | 21 +++++++++++----------
 2 files changed, 27 insertions(+), 10 deletions(-)

diff --git a/builder/PLAN-TOOLING-REVIEW.md b/builder/PLAN-TOOLING-REVIEW.md
index 3e6019b7..8680609e 100644
--- a/builder/PLAN-TOOLING-REVIEW.md
+++ b/builder/PLAN-TOOLING-REVIEW.md
@@ -809,6 +809,22 @@ keeps CRLF is private.
 **Verify.** An equivalence run in a scratch script: the old and new splice give identical
 files for every `tb` fence opener in `docs/`.
 
+**Landed.** `applyMarkers` rewrites each file through `mapLines`, with a map from a line's
+0-based index to the fence found there; the re-verification and its finding are unchanged,
+and a refused line comes back as it was. The one difference is intended: `collectFences`
+numbers lines from a full markdown-it parse, which also ends a line at a lone CR, and
+`split("\n")` did not, so below a lone CR the old splice read the wrong line and refused the
+fence. `mapLines` splits as the parse does.
+
+**Verify.** HEAD's `applyMarkers` and this one, each cut from its file and run with a fake
+`fs` over the 1,222 `tb` fences `collectFences` returns from 606 pages, every one claimed
+unmarked with the info string `tb`. On the pages as they are, both refuse all 1,222 and write
+back identical files. With ` check_build` taken off every opener that carries it (569 pages),
+both mark 950 and refuse 272, and the marked pages are byte for byte the pages in the tree,
+all 606 of them, CRLF included. For a fence below a line holding a lone CR, HEAD refuses and
+this marks.
+`check_examples.mjs --census` loads it and passes its 119 probes.
+
 ### C36 — `wisdom: parseStaging splits only on real section boundaries`
 
 **L3-3 (R1), second half.** After C26 a fenced `---` makes the run fail instead of dropping
diff --git a/scripts/check_examples.mjs b/scripts/check_examples.mjs
index 98da8330..faa7d595 100644
--- a/scripts/check_examples.mjs
+++ b/scripts/check_examples.mjs
@@ -75,6 +75,7 @@ import { tmpdir } from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
+import { mapLines } from "../lib/markdown.mjs";
 import {
   BODY_SLOTS, CONCAT_KEY, HIDDEN_MARKER, MARKER, RUN_MARKER, SLOTS, classify,
   collectFences, concatFences, moduleName, parseInfo, partOf, resourcePath, wrapFence,
@@ -1152,12 +1153,12 @@ async function applyMarkers(passed) {
   for (const [rel, list] of byFile) {
     const file = path.join(DOCS, rel);
     const src = await fs.readFile(file, "utf8");
-    const lines = src.split("\n");
-    for (const fence of list) {
-      const i = fence.line - 1;
-      const line = lines[i];
-      const cr = line.endsWith("\r") ? "\r" : "";
-      const body = cr ? line.slice(0, -1) : line;
+    // Lines are counted as the parse that found the fences counts them, and
+    // each keeps its own ending.
+    const at = new Map(list.map((fence) => [fence.line - 1, fence]));
+    const out = mapLines(src, (body, i) => {
+      const fence = at.get(i);
+      if (!fence) return body;
       // The blockquote markers are part of the line for a fence inside an
       // admonition, which is where several samples live -- `> ```tb`. Refusing
       // those would leave a sample unmarkable for a reason that has nothing to
@@ -1165,12 +1166,12 @@ async function applyMarkers(passed) {
       if (!/^[ \t]*(?:>[ \t]*)*(`{3,}|~{3,})tb[ \t]*$/.test(body)) {
         addFinding(fence, "could not mark: the fence line is not what was parsed",
           `line ${fence.line} reads ${JSON.stringify(body)}`);
-        continue;
+        return body;
       }
-      lines[i] = `${body} ${MARKER}${cr}`;
       count++;
-    }
-    await fs.writeFile(file, lines.join("\n"), "utf8");
+      return `${body} ${MARKER}`;
+    });
+    await fs.writeFile(file, out, "utf8");
   }
   return count;
 }

From 10684eceb1ed7774ab979f2e21a1dc6bbd6800c0 Mon Sep 17 00:00:00 2001
From: Kuba Sunderland-Ober <kuba@mareimbrium.org>
Date: Sun, 27 Sep 2026 14:30:29 +0200
Subject: [PATCH 10/27] wisdom: parseStaging splits only on real section
 boundaries

---
 WIP.Wisdom.md                  |  5 ++--
 builder/PLAN-TOOLING-REVIEW.md | 26 ++++++++++++++++++
 docs/Documentation/Wisdom.md   |  4 +--
 wisdom/extract/merger.mjs      | 50 +++++++++++++++-------------------
 4 files changed, 53 insertions(+), 32 deletions(-)

diff --git a/WIP.Wisdom.md b/WIP.Wisdom.md
index 9ab68b64..1b3fd8a6 100644
--- a/WIP.Wisdom.md
+++ b/WIP.Wisdom.md
@@ -3,8 +3,9 @@
 The Discord knowledge-harvesting tool: a three-phase pipeline (`export` →
 `process` → `extract`) that mines the twinBASIC Discord for things the
 documentation does not yet say, and drafts additions for human review. Plans in
-`wisdom/PLAN-{1,2,3}.md`; implementation under `wisdom/`. Uses only Node.js
-built-in APIs.
+`wisdom/PLAN-{1,2,3}.md`; implementation under `wisdom/`. Uses Node.js built-in
+APIs, and the repository's npm packages through `lib/markdown.mjs`, which
+`extract/merger.mjs` reads `staging.md` with.
 
 Split out of [WIP.md](WIP.md) because Wisdom runs occasionally and its
 invocation detail has no business in the context of a session doing anything
diff --git a/builder/PLAN-TOOLING-REVIEW.md b/builder/PLAN-TOOLING-REVIEW.md
index 8680609e..7c217e65 100644
--- a/builder/PLAN-TOOLING-REVIEW.md
+++ b/builder/PLAN-TOOLING-REVIEW.md
@@ -837,6 +837,32 @@ content; this makes it not a boundary at all.
 and metadata, and serialises to the same bytes as before. C26's synthetic file now keeps its
 section's tail and metadata.
 
+**Landed.** `parseStaging` splits with `splitOnMarker(content, (line) => line === '---')`,
+with the bare parser, since `staging.md` is not a page. Each chunk's first line for C26's
+error comes from the marker's index, and C26's message no longer says that a fenced `---`
+splits the file. The CRLF replace goes: the module splits at any line ending. A fence left
+open runs to the end of the file in markdown, so every section after it would have become
+body text of one section, where the old split cut at every `---`. At the owner's choice
+`parseStaging` refuses that instead: a region that reaches the file's last line and holds a
+`---` line throws, naming its first line and the `---`. `serializeStaging` has nothing to
+take from the module: it builds lines from parsed sections and reads no source. Wisdom now
+loads markdown-it through `lib/`, from `wisdom.mjs` on, since it imports `prep.mjs` and so
+`merger.mjs` statically: Wisdom.md's Prerequisites said no `npm install` was needed, and now
+say it is, and WIP.Wisdom.md's opening says the same. C41 would have made that so anyway,
+through `lib/frontmatter.mjs` and js-yaml. Wisdom.md's merge step says what the split skips
+and what it refuses.
+
+**Verify.** The kit's `c36-oracle.mjs`, against a HEAD copy of `wisdom/extract` and
+`wisdom/files.mjs`. The real `staging.md` (1,586,815 bytes, LF, 180 fences and 10 HTML
+blocks, none holding a `---` or `## ` line) parses to 1,160 sections under both, deep-equal,
+and the same parse from its CRLF form. A graft of no additions writes back 1,586,815 bytes
+under both, equal to the file. C26's synthetic file, and one with a `---` in a tilde fence and
+in an HTML comment, give two sections with their finding ids and every body line, where HEAD
+throws. A fence left open and an HTML comment left open throw, where HEAD split them into
+three and two sections. Prose after an unfenced `---` throws under both at the same line;
+blank chunks, an all-preamble file and a file with no final newline parse the same. The tree
+comparison differs only in Wisdom online and offline, the search data, and `book.html`.
+
 ### C37 — `scripts: check_gate_lists' sections ignore fenced headings`
 
 **Inventory site B3.** `splitSections` (`:251-264`) starts a section at any line matching
diff --git a/docs/Documentation/Wisdom.md b/docs/Documentation/Wisdom.md
index a3570503..38e8ade6 100644
--- a/docs/Documentation/Wisdom.md
+++ b/docs/Documentation/Wisdom.md
@@ -20,7 +20,7 @@ Three-phase tool that extracts technical knowledge from the twinBASIC Discord se
 ## Prerequisites
 
 - **Node.js 18+** (uses native `fetch` and ES modules).
-- **No external dependencies** --- the tool uses only Node.js built-in APIs. No `npm install` needed.
+- **The repository's npm packages** --- run `npm install` once, as for the build. The tool reads `staging.md` through the repository's `lib/markdown.mjs`, which uses markdown-it.
 - **Discord token** --- for Phases 1 and 2.
 - **Claude Code session** --- for Phase 3 (the extract workflow runs Claude agents).
 
@@ -294,7 +294,7 @@ The pipeline runs both stages without a barrier --- Stage 2 for group A starts a
 1. **Collect results**: read all `extract-results-*.json` files and concatenate their additions arrays.
 
 2. **Graft into staging.md** (`extract/merger.mjs` --- `graftAdditions`):
-   - Parse existing `staging.md` into `{ preamble, sections[] }`. The parser splits on `---` delimiter lines, then parses each chunk into heading (target_page + section + optional marker), body lines, and trailing meta lines (source threads, confidence, date range, reviewer note). A chunk that does not start with a `## ` heading stops the merge, naming its first line, before anything is written.
+   - Parse existing `staging.md` into `{ preamble, sections[] }`. The parser splits on `---` delimiter lines outside any code sample, then parses each chunk into heading (target_page + section + optional marker), body lines, and trailing meta lines (source threads, confidence, date range, reviewer note). A chunk that does not start with a `## ` heading stops the merge, naming its first line, before anything is written. So does a fence left open: it runs to the end of the file, and no delimiter after it would split.
    - For each addition, compute a match key: `(target_page, section, sorted finding_ids)`.
      - **Key exists in staging.md** (and section is not `[LOCKED]`): replace the section body and meta in place.
      - **Key not in staging, but in the emission log** (from `extract-state.json`): this was previously emitted, reviewed, and removed. Insert with a `[REFINED?]` marker.
diff --git a/wisdom/extract/merger.mjs b/wisdom/extract/merger.mjs
index b47ff340..9b52a4ec 100644
--- a/wisdom/extract/merger.mjs
+++ b/wisdom/extract/merger.mjs
@@ -16,6 +16,7 @@
 
 import { existsSync, mkdirSync, readFileSync, copyFileSync } from 'node:fs'
 import { join } from 'node:path'
+import { blockRegions, splitOnMarker } from '../../lib/markdown.mjs'
 import { writeFileAtomic } from '../files.mjs'
 import { buildEmissionKeySet, emissionKey } from './state.mjs'
 
@@ -105,37 +106,31 @@ export function renderSideband(additions) {
 /**
  * Parse staging.md into { preamble, sections } where:
  *   preamble: string[] — lines before the first `## ` heading
- *   sections: Section[] — each section parsed from a chunk delimited by `---`
+ *   sections: Section[] — each section parsed from a chunk delimited by a
+ *             `---` line outside any fence, code block or HTML block
  *
  * The parser is forgiving: anything it can't categorise gets preserved as
- * part of a section body so we never silently drop reviewer content. A chunk
- * after a `---` that does not start with `## ` has no section to go in, so it
- * throws, naming the chunk's first line, rather than being dropped.
+ * part of a section body so we never silently drop reviewer content. It
+ * throws, naming the line, rather than drop or misfile content: when a chunk
+ * after a `---` does not start with `## `, so has no section to go in, and
+ * when a fence left open runs to the end of the file, so that no `---` after
+ * it splits and every later section would be read as part of its body.
  */
 export function parseStaging(content) {
-  const text = content.replace(/\r\n/g, '\n')
-  const lines = text.split('\n')
-
-  // Split on lines that are exactly "---", keeping each chunk's first line
-  // number for the error below.
-  const chunks = []
-  const starts = []
-  let current = []
-  let start = 1
-  for (let i = 0; i < lines.length; i++) {
-    if (lines[i] === '---') {
-      chunks.push(current)
-      starts.push(start)
-      current = []
-      start = i + 2
-    } else {
-      current.push(lines[i])
-    }
-  }
-  if (current.length || chunks.length === 0) {
-    chunks.push(current)
-    starts.push(start)
+  // Split on lines that are exactly "---", except inside a code sample, which
+  // may hold one. Each chunk keeps its first line number for the errors below.
+  const parts = splitOnMarker(content, (line) => line === '---')
+  const lines = parts.flatMap((p) => (p.marker === null ? p.lines : [p.marker, ...p.lines]))
+  for (const r of blockRegions(content)) {
+    if (r.end < lines.length) continue
+    const dash = lines.slice(r.start, r.end).indexOf('---')
+    if (dash < 0) continue
+    const what = r.type === 'fence' ? 'a fence that is never closed' : 'a block that runs to the end of the file'
+    throw new Error(`staging.md line ${r.start + 1} opens ${what}, so the "---" on line ` +
+                    `${r.start + dash + 1} and every one after it split no sections: close it`)
   }
+  const chunks = parts.map((p) => p.lines)
+  const starts = parts.map((p) => (p.marker === null ? 1 : p.start + 2))
 
   // First chunk = preamble + first section.  Subsequent chunks = sections.
   // Trailing chunk after the last `---` is usually blank lines; preserve as
@@ -168,8 +163,7 @@ export function parseStaging(content) {
     const first = chunks[i].findIndex((l) => l !== '')
     if (first >= 0) {
       throw new Error(`staging.md line ${starts[i] + first} follows a "---" line but is not a ` +
-                      `"## " heading, so it belongs to no section (a "---" inside a code sample ` +
-                      `splits the file too): ${chunks[i][first]}`)
+                      `"## " heading, so it belongs to no section: ${chunks[i][first]}`)
     }
   }
 

From a56d99fcb78d834bd29ac76e089678c0a845489a Mon Sep 17 00:00:00 2001
From: Kuba Sunderland-Ober <kuba@mareimbrium.org>
Date: Sun, 27 Sep 2026 14:58:17 +0200
Subject: [PATCH 11/27] scripts: check_gate_lists' sections ignore fenced
 headings

---
 WIP.Build.md                   |  7 +++--
 builder/PLAN-TOOLING-REVIEW.md | 17 ++++++++++++
 docs/Documentation/Tools.md    |  2 +-
 scripts/check_gate_lists.mjs   | 50 ++++++++++++++++++++--------------
 4 files changed, 52 insertions(+), 24 deletions(-)

diff --git a/WIP.Build.md b/WIP.Build.md
index 96c5ab3c..7d18b232 100644
--- a/WIP.Build.md
+++ b/WIP.Build.md
@@ -743,8 +743,11 @@ Two judgement calls worth keeping:
   *"found `test.bat` documented as three gates when it had four"* as a false
   claim, so the verb list is explicit.
 
-Twelve of its eighteen probes cover the sweep, seven positive and five
-negative, each taken from the real corpus. The verification that means anything
+Thirteen of its nineteen probes cover the sweep, eight positive and five
+negative. Twelve are taken from the real corpus; the thirteenth puts a fenced
+`## ` line, the shape of Wisdom.md's `staging.md` example, inside a wrapper's
+section, since sections are split through `lib/markdown.mjs`'s `splitOnMarker`
+and a heading-shaped line in a region starts none. The verification that means anything
 is reverting the offending pages to the commit that shipped them and confirming
 the gate names every site.
 
diff --git a/builder/PLAN-TOOLING-REVIEW.md b/builder/PLAN-TOOLING-REVIEW.md
index 7c217e65..efd5842b 100644
--- a/builder/PLAN-TOOLING-REVIEW.md
+++ b/builder/PLAN-TOOLING-REVIEW.md
@@ -876,6 +876,23 @@ none. A probe: a fenced `## ` line inside a section that states a count.
 **Verify.** The gate's verdict and its 18 probes unchanged; the new probe fails with the old
 splitter.
 
+**Landed.** `splitSections` splits with `splitOnMarker` on the same `/^#{1,6}\s/` test, with
+the site's parser, since the pages are the site's; it is built on first use inside `main`, so
+a failure to build it exits 2. A section still begins with its heading line and carries that
+line's 1-based number. `sectionBody` had the same fault in Tools.md's two wrapper sections,
+which the entry does not name, and now takes its section from `splitSections`. The new prose
+probe states a wrong total after a fenced `## ` line in a wrapper's section: 19 probes, and
+Tools.md's section and WIP.Build.md now say thirteen of the nineteen cover the sweep. Two
+other differences from the old split reach no page: a lone CR now ends a line (no page the
+gate reads has one), and a final line ending no longer gives an empty last line, which no
+rule matches.
+
+**Verify.** Of the 16 pages the gate reads, one has a heading-shaped line inside a region:
+`Wisdom.md:310`, in the `staging.md` example, under the bare parser and the site's alike.
+`--verbose` under a HEAD copy and the working file gives the same claim lines, 6 stated
+counts across 16 pages, exit 0 both; the only difference is the new probe's line. With the
+old splitter put back the new probe fails: exit 1, `1 of 19 self-test probes failed`.
+
 ### C38 — `scripts: one Attributes.md reader for census and the probe generator`
 
 **Inventory sites B1, B2.** `census_attributes.mjs`'s `documentedAttributes` (`:377-392`) and
diff --git a/docs/Documentation/Tools.md b/docs/Documentation/Tools.md
index 7a7f0e65..2b99c6ac 100644
--- a/docs/Documentation/Tools.md
+++ b/docs/Documentation/Tools.md
@@ -448,7 +448,7 @@ Three things follow from how it works. **The wrapper is the source of truth**, n
 
 When it fires on a count that is merely a subset --- *three cheaper gates run first* --- the fix is to delete the number rather than correct it. The command block or the linked list beneath it already states it, and a number nothing derives is a number that goes stale. The script's header names what the sweep deliberately does not see.
 
-Its probes ride along in the ordinary run rather than hiding behind `--self-test`, because a green line from a gate that has stopped detecting looks exactly like a green line from a working one. Twelve of the eighteen cover the sweep, each a sentence that was published at the commit round 4 reviewed. Exits 1 on a disagreement or a failed probe, 2 if it cannot run.
+Its probes ride along in the ordinary run rather than hiding behind `--self-test`, because a green line from a gate that has stopped detecting looks exactly like a green line from a working one. Thirteen of the nineteen cover the sweep. Twelve are sentences that were published at the commit round 4 reviewed; the thirteenth puts a heading-shaped line in a code fence, as in [Wisdom](Wisdom)'s `staging.md` example, inside a wrapper's section, because such a line starts no section. Exits 1 on a disagreement or a failed probe, 2 if it cannot run.
 
 ### check_ci_workflows.mjs
 {: #check-ci-workflows }
diff --git a/scripts/check_gate_lists.mjs b/scripts/check_gate_lists.mjs
index 454e107a..18427feb 100644
--- a/scripts/check_gate_lists.mjs
+++ b/scripts/check_gate_lists.mjs
@@ -81,11 +81,19 @@
 import { readFile, readdir } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { createMarkdownIt } from "../builder/render.mjs";
+import { splitOnMarker } from "../lib/markdown.mjs";
 import { gatesFromBat } from "./lib/gate-roster.mjs";
 
 const REPO = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
 const TOOLS_MD = "docs/Documentation/Tools.md";
 
+// The site's own parser, so that what is code is what the renderer will make
+// of it. Built on first use, inside main, so a failure exits 2.
+let siteMd;
+const siteParser = () =>
+  (siteMd ??= createMarkdownIt({ highlighter: null, linkTables: null, baseurl: "", staticFiles: new Set() }));
+
 // The wrappers this gate covers, and the heading each one is documented under.
 // book.bat and build.bat are deliberately absent: neither runs a list of gates,
 // so there is nothing here to drift.
@@ -102,13 +110,9 @@ const NUMBER_WORDS = [
 ];
 
 /** The body of a `### <name>` section: up to the next heading of any level. */
-function sectionBody(md, heading) {
-  const lines = md.split(/\r?\n/);
-    const start = lines.findIndex((l) => l.trim() === heading);
-  if (start === -1) return null;
-  const rest = lines.slice(start + 1);
-  const end = rest.findIndex((l) => /^#{1,6}\s/.test(l));
-  return (end === -1 ? rest : rest.slice(0, end)).join("\n");
+function sectionBody(src, heading) {
+  const sec = splitSections(src).find((s) => s.heading === heading);
+  return sec ? sec.lines.slice(1).join("\n") : null;
 }
 
 /**
@@ -231,20 +235,17 @@ const asNumber = (w) => {
   return i === -1 ? Number(w) : i;
 };
 
-/** Split markdown into sections: a heading and everything up to the next one. */
-function splitSections(md) {
-  const lines = md.split(/\r?\n/);
-  const out = [];
-  let cur = { heading: "(top of file)", start: 1, lines: [] };
-  for (let i = 0; i < lines.length; i++) {
-    if (/^#{1,6}\s/.test(lines[i])) {
-      out.push(cur);
-      cur = { heading: lines[i].trim(), start: i + 1, lines: [] };
-    }
-    cur.lines.push(lines[i]);
-  }
-  out.push(cur);
-  return out;
+/**
+ * Split markdown into sections: a heading and everything up to the next one.
+ * A heading-shaped line inside a fence, code block or HTML block starts none;
+ * Wisdom.md's `staging.md` example holds one. A section's `lines` begin with
+ * its heading, and `start` is that line's 1-based number.
+ */
+function splitSections(src) {
+  return splitOnMarker(src, (line) => /^#{1,6}\s/.test(line), { md: siteParser() }).map((s) =>
+    s.marker === null
+      ? { heading: "(top of file)", start: 1, lines: s.lines }
+      : { heading: s.marker.trim(), start: s.start + 1, lines: [s.marker, ...s.lines] });
 }
 
 /**
@@ -474,6 +475,13 @@ const PROSE_PROBES = [
     name: "a count in the sub-page list of an index page",
     md: "`build.bat` produces three output trees; `check.bat` runs six further gates, from the publish allowlist to the accessibility scan.\n",
   },
+  {
+    // Not a published sentence: Wisdom.md's `staging.md` example has a fenced
+    // `## ` line, and read as a heading it cut the section it sits in, so a
+    // count after it belonged to a section about no wrapper.
+    name: "a section total after a fenced heading-shaped line",
+    md: "## Tests of the toolchain\n\n    test.bat\n\n```\n## not a heading\n```\n\nFive gates that test the build system rather than the site.\n",
+  },
 ];
 
 const PROSE_NEGATIVES = [

From f41ac2bb2d226f7b6b1289f7ba5dbabaeb383ff7 Mon Sep 17 00:00:00 2001
From: Kuba Sunderland-Ober <kuba@mareimbrium.org>
Date: Sun, 27 Sep 2026 15:02:56 +0200
Subject: [PATCH 12/27] scripts: one Attributes.md reader for census and the
 probe generator

---
 builder/PLAN-TOOLING-REVIEW.md   | 19 ++++++++++
 docs/Documentation/Tools.md      |  2 +-
 scripts/census_attributes.mjs    | 15 ++------
 scripts/gen_attribute_probes.mjs | 42 ++--------------------
 scripts/lib/attributes-doc.mjs   | 60 ++++++++++++++++++++++++++++++++
 5 files changed, 84 insertions(+), 54 deletions(-)
 create mode 100644 scripts/lib/attributes-doc.mjs

diff --git a/builder/PLAN-TOOLING-REVIEW.md b/builder/PLAN-TOOLING-REVIEW.md
index efd5842b..2d3b44d3 100644
--- a/builder/PLAN-TOOLING-REVIEW.md
+++ b/builder/PLAN-TOOLING-REVIEW.md
@@ -907,6 +907,25 @@ tools use it.
 **Verify.** A scratch script: both tools' parsed attribute lists identical before and after on
 the real page, and a fenced `Syntax:` line ignored.
 
+**Landed.** `scripts/lib/attributes-doc.mjs` exports `parseAttributes(src)`, which is
+`gen_attribute_probes`' reader, `{ name, syntax, line, app }[]` in page order, with every line
+inside a region from `blockRegions` skipped. Its regions come from the site's parser, built on
+first use, as in C37. `gen_attribute_probes` calls it on the file it reads; `census_attributes`
+builds its map from it, keyed by name, a later entry replacing an earlier one as before, and
+its values now also carry `syntax`, which it never reads. Both tools therefore load
+markdown-it and `builder/render.mjs`, where they imported only `node:` modules, so neither runs
+without `npm install` any more. Tools.md's `gen_attribute_probes.mjs` section says a fenced
+line is not read and names the module.
+
+**Verify.** The kit-style oracle, HEAD's `documentedAttributes` and `parseAttributes` cut from
+HEAD's files and run beside the new reader: the real page and its CRLF form give the same 71
+attributes, each with a target, under all three. A fenced `Syntax:` block appended to the page
+is read by both HEAD readers and not by the new one, and a fenced `Applicable to:` line put
+straight after the first `Syntax:` line becomes that attribute's target under HEAD, where the
+new reader takes the real line after the fence. End to end, HEAD copies and the working tools
+give byte-identical output, 136 files: `gen_attribute_probes`' two probe trees and key, and
+`census_attributes --json` over the BETA 987 cache (661 files, 9,706 sites; no IDE started).
+
 ### C39 — `builder, eval: counts, run_case and nav_hops skip code`
 
 **Inventory sites B4, B5, B8, B9.** `counts.mjs`'s `countAttributeAnchors` (`:112-116`) and
diff --git a/docs/Documentation/Tools.md b/docs/Documentation/Tools.md
index 2b99c6ac..f088d5dc 100644
--- a/docs/Documentation/Tools.md
+++ b/docs/Documentation/Tools.md
@@ -970,7 +970,7 @@ is.
 
     node scripts/gen_attribute_probes.mjs <out_dir> [key.md]
 
-Generates twinBASIC probe projects from the `Applicable to:` lines in `Reference/Attributes.md`, for [`tbbuild.mjs`](#tbbuild) to compile. Those lines had gone unchecked against the compiler since they were written, and the one that was eventually checked turned out to be wrong. This writes one source file per claimed target, so a single build answers every claim at once. A misplaced attribute comes back as `This attribute is not supported in this context` (TB5155) or `Syntax error.  No handler for this symbol` (TB5182). Which of the two arrives says nothing about whether the attribute exists, only that it is not accepted there.
+Generates twinBASIC probe projects from the `Applicable to:` lines in `Reference/Attributes.md`, for [`tbbuild.mjs`](#tbbuild) to compile. Those lines had gone unchecked against the compiler since they were written, and the one that was eventually checked turned out to be wrong. This writes one source file per claimed target, so a single build answers every claim at once. A `Syntax:` or `Applicable to:` line inside a code fence is not read, so an example that shows the page's own format is not taken for an attribute; [`census_attributes.mjs`](#census-attributes) reads the page through the same code, `scripts/lib/attributes-doc.mjs`. A misplaced attribute comes back as `This attribute is not supported in this context` (TB5155) or `Syntax error.  No handler for this symbol` (TB5182). Which of the two arrives says nothing about whether the attribute exists, only that it is not accepted there.
 
 Up to three trees come out, on two contracts that must not be mixed:
 
diff --git a/scripts/census_attributes.mjs b/scripts/census_attributes.mjs
index 53ab1f25..77ec037f 100644
--- a/scripts/census_attributes.mjs
+++ b/scripts/census_attributes.mjs
@@ -75,6 +75,7 @@
 import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { parseAttributes } from "./lib/attributes-doc.mjs";
 import { findIde } from "./lib/tb-install.mjs";
 import { defaultCache, exportPackages, packageName } from "./lib/tb-packages.mjs";
 
@@ -371,19 +372,7 @@ function scanFile(file, pkg) {
 // ------------------------------------------------------ documented attributes
 function documentedAttributes() {
   if (!existsSync(ATTR_DOC)) return null;
-  const out = new Map();
-  const lines = readFileSync(ATTR_DOC, "utf8").replace(/\r\n?/g, "\n").split("\n");
-  let cur = null;
-  lines.forEach((line, i) => {
-    const m = /^Syntax:\s*\*\*\[(\w+)/.exec(line);
-    if (m) { cur = { name: m[1], line: i + 1, app: null }; out.set(m[1], cur); return; }
-    const a = /^Applicable to:\s*(.*)$/.exec(line);
-    if (a && cur && cur.app === null) {
-      cur.app = a[1].replace(/\[\*\*([^\]]*)\*\*\]\([^)]*\)/g, "$1")
-        .replace(/\[([^\]]*)\]\([^)]*\)/g, "$1").replaceAll("**", "").replaceAll("\\", "").trim();
-    }
-  });
-  return out;
+  return new Map(parseAttributes(readFileSync(ATTR_DOC, "utf8")).map((e) => [e.name, e]));
 }
 
 // ------------------------------------------------------------------- report
diff --git a/scripts/gen_attribute_probes.mjs b/scripts/gen_attribute_probes.mjs
index bd3aac77..7c3ca113 100644
--- a/scripts/gen_attribute_probes.mjs
+++ b/scripts/gen_attribute_probes.mjs
@@ -38,6 +38,7 @@
 import { promises as fs } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { parseAttributes } from "./lib/attributes-doc.mjs";
 
 const REPO = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
 const DOCS = path.join(REPO, "docs", "Reference", "Attributes.md");
@@ -50,45 +51,6 @@ Writes one source file per claimed attribute target, plus a key naming the
 Attributes.md line each probe came from. Every probe is expected to compile; a
 diagnostic naming a probe module is a finding.`;
 
-// ----------------------------------------------------------------- parsing
-const LINK_BOLD = /\[\*\*([^\]]*)\*\*\]\([^)]*\)/g;
-const LINK = /\[([^\]]*)\]\([^)]*\)/g;
-
-function clean(s) {
-  return s
-    .replace(LINK_BOLD, "$1")
-    .replace(LINK, "$1")
-    .replaceAll("**", "")
-    .replaceAll("\\", "")
-    .trim();
-}
-
-async function parseAttributes(file) {
-  // Python reads in text mode, so universal-newline translation has already
-  // collapsed CRLF before the split. Match that, or every line carries a
-  // trailing CR into the generated key.
-  const lines = (await fs.readFile(file, "utf8")).replace(/\r\n?/g, "\n").split("\n");
-  const entries = [];
-  let cur = null;
-
-  lines.forEach((line, i) => {
-    const m = /^Syntax:\s*(.*)$/.exec(line);
-    if (m) {
-      const name = /^Syntax:\s*\*\*\[(\w+)/.exec(line);
-      // A `Syntax:` line that names no attribute leaves `cur` alone, exactly as
-      // the Python `continue` did -- the line cannot also be `Applicable to:`.
-      if (!name) return;
-      cur = { name: name[1], syntax: clean(m[1]), line: i + 1, app: null };
-      entries.push(cur);
-      return;
-    }
-    const m2 = /^Applicable to:\s*(.*)$/.exec(line);
-    if (m2 && cur !== null && cur.app === null) cur.app = clean(m2[1]);
-  });
-
-  return entries;
-}
-
 // --------------------------------------------------------------- arguments
 // An attribute with a mandatory argument needs a value that is itself valid, or
 // the compiler reports the argument instead of the applicability. GUIDs are
@@ -1157,7 +1119,7 @@ async function main(argv) {
   const overflowSrc = path.join(out + "-2", "Sources");
   await fs.mkdir(srcDir, { recursive: true });
 
-  const entries = await parseAttributes(DOCS);
+  const entries = parseAttributes(await fs.readFile(DOCS, "utf8"));
   const byName = new Map(entries.map((e) => [e.name, e]));
   const probes = [];
   const overflow = [];
diff --git a/scripts/lib/attributes-doc.mjs b/scripts/lib/attributes-doc.mjs
new file mode 100644
index 00000000..320624e0
--- /dev/null
+++ b/scripts/lib/attributes-doc.mjs
@@ -0,0 +1,60 @@
+// What Reference/Attributes.md documents: each attribute's `Syntax:` line and
+// the first `Applicable to:` line after it. census_attributes.mjs reports each
+// attribute's documented targets beside its uses, and gen_attribute_probes.mjs
+// generates a probe from each target.
+//
+// A line inside a fence, an indented code block or an HTML block is not read,
+// so an example that shows the page's own format is not taken for an
+// attribute. The regions come from the site's parser, since the page is the
+// site's.
+
+import { createMarkdownIt } from "../../builder/render.mjs";
+import { blockRegions } from "../../lib/markdown.mjs";
+
+const LINK_BOLD = /\[\*\*([^\]]*)\*\*\]\([^)]*\)/g;
+const LINK = /\[([^\]]*)\]\([^)]*\)/g;
+
+/** The text with its links, bold markers and backslashes removed. */
+function clean(s) {
+  return s
+    .replace(LINK_BOLD, "$1")
+    .replace(LINK, "$1")
+    .replaceAll("**", "")
+    .replaceAll("\\", "")
+    .trim();
+}
+
+let siteMd;
+
+/**
+ * Every attribute `src` documents, in page order, as `{ name, syntax, line, app }`:
+ * the name a `Syntax: **[Name` line gives, the rest of that line cleaned, its
+ * 1-based line number, and the first `Applicable to:` line after it, cleaned,
+ * or null. A `Syntax:` line that names no attribute is skipped, so an
+ * `Applicable to:` line after it still belongs to the attribute before.
+ */
+export function parseAttributes(src) {
+  siteMd ??= createMarkdownIt({ highlighter: null, linkTables: null, baseurl: "", staticFiles: new Set() });
+  // CRLF and a lone CR end a line as LF does, as they do for blockRegions, so
+  // the two index the same lines and no line keeps a CR.
+  const lines = src.replace(/\r\n?/g, "\n").split("\n");
+  const inRegion = new Uint8Array(lines.length);
+  for (const r of blockRegions(src, { md: siteMd })) inRegion.fill(1, r.start, r.end);
+
+  const entries = [];
+  let cur = null;
+  lines.forEach((line, i) => {
+    if (inRegion[i]) return;
+    const m = /^Syntax:\s*(.*)$/.exec(line);
+    if (m) {
+      const name = /^Syntax:\s*\*\*\[(\w+)/.exec(line);
+      if (!name) return;
+      cur = { name: name[1], syntax: clean(m[1]), line: i + 1, app: null };
+      entries.push(cur);
+      return;
+    }
+    const a = /^Applicable to:\s*(.*)$/.exec(line);
+    if (a && cur !== null && cur.app === null) cur.app = clean(a[1]);
+  });
+  return entries;
+}

From c71bcae7fc3866dfb0818d34dff07e4d44720eef Mon Sep 17 00:00:00 2001
From: Kuba Sunderland-Ober <kuba@mareimbrium.org>
Date: Sun, 27 Sep 2026 15:10:09 +0200
Subject: [PATCH 13/27] builder, eval: counts, run_case and nav_hops skip code

---
 builder/PLAN-TOOLING-REVIEW.md  | 38 +++++++++++++++++++++++++++++++++
 builder/counts.mjs              | 27 +++++++++++++++++------
 docs/Documentation/Extending.md |  4 +++-
 eval/nav_hops.mjs               | 13 ++++++++---
 eval/run_case.mjs               | 11 +++++++---
 5 files changed, 80 insertions(+), 13 deletions(-)

diff --git a/builder/PLAN-TOOLING-REVIEW.md b/builder/PLAN-TOOLING-REVIEW.md
index 2d3b44d3..6010f038 100644
--- a/builder/PLAN-TOOLING-REVIEW.md
+++ b/builder/PLAN-TOOLING-REVIEW.md
@@ -940,6 +940,33 @@ the ones it misses are indented or use four backticks. None misfires today.
 **Verify.** The tree comparison identical (the counts); `evaluatorProtocol` returns the same
 text; `hrefs` returns the same links for every page.
 
+**Landed.** All four use the bare parser. `counts.mjs` has no choice: the site's parser is
+built with the counts (`tbdocs.mjs:607-613`), so it does not exist when they are derived. A new
+`proseLines(src)` there gives a page's lines with each line in a region replaced by null;
+`countAttributeAnchors` counts the `{: #id }` lines in it, and `countEnumerations` finds the
+index heading and scans to the next heading in it, where each did a multiline regex over the
+raw source. `evaluatorProtocol` takes neither boundary from a region. `hrefs` blanks the lines
+of every fence and indented code block and keeps HTML blocks, whose `href`s are links.
+`eval/` still imports only `lib/`, not `builder/`: over all 912 pages the bare parser and the
+site's give the same regions. Extending.md's paragraph on the two scanning counts says they
+skip code, and that a new one should.
+
+**Verify.** A scratch oracle cut each function out of HEAD's file and the working one and ran
+both with their dependencies injected. The counts come out 72 anchors and 140 enumerations
+from the real pages and their CRLF forms under both; with a fenced `{: #fake }` appended and
+a fence holding `- [Fake](Fake)` and `## x` put under the index heading, HEAD gives 73 and 1
+and the new code 72 and 140. The protocol's evaluator half is the same 3,985 characters from
+the file and its CRLF form; with a fence holding `---` and the orchestrator heading put
+before the first rule, HEAD throws and the new code returns the same text. `hrefs` gives the
+same links on 911 of 912 pages (12,835 links in all). The one difference is `Authoring.md`,
+81 links under HEAD and 86 now, which is the Found item "`nav_hops.mjs`' `hrefs` misread
+`Authoring.md`": the new reader drops the three link strings in indented code and finds the
+five prose link targets HEAD's regex dropped. On a probe page it keeps a prose link and an
+HTML block's `href`, and drops one in a four-backtick fence, a fence in a list item and an
+indented code block, where HEAD dropped none of the three. `nav_hops` itself, HEAD copy against
+the working file, prints the same paths for four targets. The tree comparison differs only in
+Extending online and offline, the search data, and `book.html`.
+
 ### C40 — `builder, eval: frontmatter through lib/frontmatter; drop gray-matter`
 
 **Decision (a)'s frontmatter half.** `gray-matter@4.0.3` bundles its own `js-yaml@3.15.2`,
@@ -2029,6 +2056,17 @@ Defects the review did not have, found by building something this plan asks for.
   and nothing tested the tool. No literal
   dash got past it. Fixed in `scripts: convert_em_dash_separators reads code regions from
   lib/`, which deletes the scan and adds the tool's probes to `check_code_regions.mjs`.
+- **`nav_hops.mjs`' `hrefs` misread `Authoring.md`**, found while landing C39. Its fence
+  regex opens on any line starting with three backticks and closes only on a line of exactly
+  three, so each of the page's four-backtick fences (from `Authoring.md:476`) was closed
+  early, and its own four-backtick closing line then opened a fence that ran to the next
+  three-backtick line: lines 482-576, 577-614 and 615-760 were dropped as code, and five
+  prose link targets with them. The regex also keeps indented code blocks, where three link
+  strings sit (the page template's See Also, and two climbs shown as code). The fences came
+  in with `5b64cd41` (2026-09-22), before the review, whose B9 says "None misfires today":
+  it counted the fences the regex misses, not what it made of the lines after them. At the
+  owner's choice it is fixed inside `builder, eval: counts, run_case and nav_hops skip code`
+  rather than in place first.
 
 ## Open questions
 
diff --git a/builder/counts.mjs b/builder/counts.mjs
index 7d87a019..d2aa30cb 100644
--- a/builder/counts.mjs
+++ b/builder/counts.mjs
@@ -65,7 +65,7 @@
 // A name with no uses is fine and is not reported. Names are cheap; the
 // registry is allowed to offer more than the prose currently asks for.
 
-import { maskCode } from "../lib/markdown.mjs";
+import { blockRegions, maskCode } from "../lib/markdown.mjs";
 
 export const PLACEHOLDER_RE = /\{\{tbdocs:([A-Za-z][A-Za-z0-9]*)\}\}/g;
 
@@ -112,7 +112,16 @@ function countPackages(pages, root = null) {
 function countAttributeAnchors(pages) {
   const page = pages.find((p) => p.srcRel === "Reference/Attributes.md");
   if (!page) return 0;
-  return (page.rawContent.match(/^\{: #[a-z0-9]+ \}/gm) ?? []).length;
+  return proseLines(page.rawContent).filter((l) => l !== null && /^\{: #[a-z0-9]+ \}/.test(l)).length;
+}
+
+// A page's lines, each line inside a fence, code block or HTML block replaced
+// by null, so that a scan over them reads no code. The bare parser finds the
+// regions: the site's is built with these counts, so it does not exist yet.
+function proseLines(src) {
+  const lines = src.split(/\r\n|\r|\n/);
+  for (const r of blockRegions(src)) lines.fill(null, r.start, r.end);
+  return lines;
 }
 
 // Enumerations documented across every package, counted off the alphabetical
@@ -130,13 +139,19 @@ function countAttributeAnchors(pages) {
 function countEnumerations(pages) {
   const page = pages.find((p) => p.srcRel === "Reference/Enumerations.md");
   if (!page) return 0;
-  const body = page.rawContent.split(/^## Alphabetical index\s*$/m)[1];
-  if (!body) return 0;
+  const lines = proseLines(page.rawContent);
+  const start = lines.findIndex((l) => l !== null && /^## Alphabetical index\s*$/.test(l));
+  if (start === -1) return 0;
   // Stop at the next heading of any level -- `### See Also` closes the list,
   // and its four bullets are not enumerations. The A/B/C dividers between
   // groups are bold text, not headings, so they do not terminate the scan.
-  const list = body.split(/^#{1,6} /m)[0];
-  return (list.match(/^- \[/gm) ?? []).length;
+  let n = 0;
+  for (const l of lines.slice(start + 1)) {
+    if (l === null) continue;
+    if (/^#{1,6} /.test(l)) break;
+    if (/^- \[/.test(l)) n++;
+  }
+  return n;
 }
 
 /**
diff --git a/docs/Documentation/Extending.md b/docs/Documentation/Extending.md
index bd20454c..dbeeec34 100644
--- a/docs/Documentation/Extending.md
+++ b/docs/Documentation/Extending.md
@@ -690,7 +690,9 @@ Two shapes qualify. Most names count things `discover` already found --- pages u
 prefix, static files, packages. `attributeAnchors` and `enumerations` are the other shape:
 they scan one page's `rawContent` for the pattern that makes an entry, which is legitimate
 because the page *is* the list, and carries the matching exposure --- change that page's
-list formatting and the number moves with it.
+list formatting and the number moves with it. Both scan only the lines outside code, which
+`proseLines` in `counts.mjs` gives them, so an example of the pattern in a fence is not
+counted; a new scan should do the same.
 
 1. **Add the entry.** A function beside the others in
    [`counts.mjs`](https://github.com/twinbasic/documentation/blob/main/builder/counts.mjs),
diff --git a/eval/nav_hops.mjs b/eval/nav_hops.mjs
index e4570b64..8f57d8e6 100644
--- a/eval/nav_hops.mjs
+++ b/eval/nav_hops.mjs
@@ -33,6 +33,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import matter from "gray-matter";
+import { blockRegions } from "../lib/markdown.mjs";
 
 const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const SITE_HOST = /^https?:\/\/docs\.twinbasic\.com/i;
@@ -82,10 +83,16 @@ async function loadPages(src) {
   return { urlOf, byKey };
 }
 
-/** The link targets a reader can click on a page, code fences left out. */
+/**
+ * The link targets a reader can click on a page, fences and indented code
+ * left out. An HTML block stays, since its `href`s are links. The bare parser
+ * finds the code: on the site's pages it finds what the site's parser finds.
+ */
 function hrefs(file) {
-  const text = fs.readFileSync(file, "utf8").replace(/\r\n/g, "\n")
-    .replace(/^(```|~~~)[^\n]*\n[\s\S]*?^\1[ \t]*$/gm, "");
+  const src = fs.readFileSync(file, "utf8");
+  const lines = src.split(/\r\n|\r|\n/);
+  for (const r of blockRegions(src)) if (r.type !== "html_block") lines.fill("", r.start, r.end);
+  const text = lines.join("\n");
   const out = [];
   for (const m of text.matchAll(/\]\(\s*<?([^()\s<>]+)>?(?:\s+"[^"]*")?\s*\)/g)) out.push(m[1]);
   for (const m of text.matchAll(/^[ \t]*\[[^\]\n]+\]:[ \t]*<?(\S+?)>?[ \t]*$/gm)) out.push(m[1]);
diff --git a/eval/run_case.mjs b/eval/run_case.mjs
index 4347a67a..2e99ac92 100644
--- a/eval/run_case.mjs
+++ b/eval/run_case.mjs
@@ -59,6 +59,7 @@ import { spawn } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { blockRegions } from "../lib/markdown.mjs";
 import { printDigest, readTranscript, summarize } from "./transcript.mjs";
 
 const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
@@ -98,9 +99,13 @@ function parseArgs(argv) {
 
 /** The evaluator-facing half of protocol.md: from its first rule up to "For the orchestrator". */
 function evaluatorProtocol() {
-  const lines = fs.readFileSync(path.join(REPO_ROOT, "eval", "protocol.md"), "utf8").split(/\r?\n/);
-  const start = lines.indexOf("---");
-  const end = lines.findIndex((l) => l.startsWith("## For the orchestrator"));
+  const src = fs.readFileSync(path.join(REPO_ROOT, "eval", "protocol.md"), "utf8");
+  const lines = src.split(/\r\n|\r|\n/);
+  // A line inside a fence, code block or HTML block is neither boundary.
+  const inCode = new Uint8Array(lines.length);
+  for (const r of blockRegions(src)) inCode.fill(1, r.start, r.end);
+  const start = lines.findIndex((l, i) => !inCode[i] && l === "---");
+  const end = lines.findIndex((l, i) => !inCode[i] && l.startsWith("## For the orchestrator"));
   if (start < 0 || end < start) throw new Error("eval/protocol.md: cannot find the evaluator-facing half");
   const text = lines.slice(start + 1, end).join("\n").trim();
   if (!text.includes(SEARCH_COMMAND)) {

From f121c4a013ac5d2900e31f1dc566f43397b533e6 Mon Sep 17 00:00:00 2001
From: Kuba Sunderland-Ober <kuba@mareimbrium.org>
Date: Sun, 27 Sep 2026 15:17:23 +0200
Subject: [PATCH 14/27] builder, eval: frontmatter through lib/frontmatter;
 drop gray-matter

---
 WIP.Build.md                          |   2 +-
 WIP.md                                |   9 +-
 builder/PLAN-TOOLING-REVIEW.md        |  26 ++++++
 builder/discover.mjs                  |  33 +++----
 builder/publish-policy.mjs            |  17 ++--
 docs/Documentation/Builder.md         |   3 +-
 docs/Documentation/Pipeline-Stages.md |   2 +-
 eval/nav_hops.mjs                     |   5 +-
 lib/frontmatter.mjs                   |   9 +-
 package-lock.json                     | 119 --------------------------
 package.json                          |   1 -
 11 files changed, 58 insertions(+), 168 deletions(-)

diff --git a/WIP.Build.md b/WIP.Build.md
index 7d18b232..8b680fb1 100644
--- a/WIP.Build.md
+++ b/WIP.Build.md
@@ -217,7 +217,7 @@ Three details of the policy are load-bearing:
   refusing at source. Folding the two together would pass every other assertion
   in the self-test, so the self-test asserts the disjointness directly.
 - **`.md` is deliberately absent from both.** A markdown file that reaches the
-  check is one `gray-matter` found no frontmatter block in --- the
+  check is one `discover` found no frontmatter block in --- the
   AppGlobalClassObject shape, where the raw markdown was served verbatim for
   months. The two causes that come to mind first are both handled upstream: a
   **UTF-8 BOM** is stripped before parsing, and **malformed YAML** inside the
diff --git a/WIP.md b/WIP.md
index b33d18b8..aea8d848 100644
--- a/WIP.md
+++ b/WIP.md
@@ -87,11 +87,10 @@ The rest of this file is the maintenance guide for updating existing pages or ad
   > to drop `_Images`, swallowed all 37 pages under `_App/` --- the twinBASIC interface
   > really is named `_App`, after the COM hidden-interface convention. It is scoped to
   > `**/_Images/**` (plus `**/*.af`) now, so **never widen an exclude to a bare
-  > underscore prefix.** Separately `index.md` carried a UTF-8 BOM, which sits in front
-  > of the `---` and stops `gray-matter` recognising any frontmatter at all, so
-  > `discover` filed it as a *static file* and served the raw markdown verbatim;
-  > `discover.mjs` strips a leading BOM before parsing now, and editors on Windows add
-  > one without being asked.
+  > underscore prefix.** Separately `index.md` carried a UTF-8 BOM in front of the `---`,
+  > which hid the frontmatter, so `discover` filed it as a *static file* and served the raw
+  > markdown verbatim; `lib/frontmatter.mjs` strips a leading BOM before parsing now, and
+  > editors on Windows add one without being asked.
 - `docs/Reference/Built-In/tbIDE/` — IDE Extensibility package (this is the **addin SDK**). The package is type-only — it ships **public interfaces + CoClasses** that an addin DLL binds to; every implementation behind them lives in the twinBASIC IDE itself. The user-facing surface is one entry-point factory (`tbCreateCompilerAddin`) plus 23 CoClasses grouped by role: the addin contract (`AddIn`), the root API (`Host`), the loaded `Project`, the editors collection (`Editor` / `CodeEditor` / `Editors`), the virtual file system (`FileSystem` / `FileSystemItem` / `Folder` / `File`), the in-IDE UI surface (`Toolbar` / `Toolbars` / `Button` / `ToolWindow` / `ToolWindows`), the HTML DOM inside a tool window (`HtmlElement` / `HtmlElements` / `HtmlElementProperty` / `HtmlElementProperties` / `HtmlEventProperty` / `HtmlEventProperties`), the `DebugConsole`, `KeyboardShortcuts`, `Themes`, and the single concrete user-instantiable helper class `AddinTimer`. Flat layout — one page per CoClass / Class plus the index landing.
 - `docs/Reference/Statements.md` — alphabetical index of language statements.
 - `docs/Reference/Procedures and Functions.md` — alphabetical index of procedures/functions.
diff --git a/builder/PLAN-TOOLING-REVIEW.md b/builder/PLAN-TOOLING-REVIEW.md
index 6010f038..4613ae46 100644
--- a/builder/PLAN-TOOLING-REVIEW.md
+++ b/builder/PLAN-TOOLING-REVIEW.md
@@ -983,6 +983,32 @@ does not) and `eval/nav_hops.mjs` use `parseFrontmatter`. `gray-matter` leaves
 comparison identical. Compare before uninstalling, since the before side needs `gray-matter`;
 rebuild once after.
 
+**Landed.** `discover.mjs`'s own frontmatter step is renamed `readFrontmatter`, to free the
+name: it calls `parseFrontmatter` inside the same `Failed to parse frontmatter in <file>`
+wrap, and takes `contentLine` (C32a) from the raw text, since the stripped BOM holds no line
+ending. `stripBom` goes, as `parseFrontmatter` strips the BOM. `nav_hops` takes a missing block as no permalink, as gray-matter's
+empty data was. `npm uninstall gray-matter` removed it from `package.json`, and from the
+lockfile it, its nested `js-yaml@3` and `argparse`, and seven packages only it used
+(`esprima`, `extend-shallow`, `is-extendable`, `kind-of`, `section-matter`, `sprintf-js`,
+`strip-bom-string`): 120 lines deleted, none added. Builder.md's `package.json` listing and
+its Dependencies paragraph, Pipeline-Stages.md's `frontmatter` row, WIP.md's BOM paragraph,
+WIP.Build.md's publish-allowlist note, two comments in `publish-policy.mjs` and the headers
+of `lib/frontmatter.mjs` and `discover.mjs`'s frontmatter step no longer name gray-matter, in
+the present or as history: at the owner's word, history that no later task needs is left to
+git.
+
+**Verify.** `discover()` from a HEAD copy of `builder/` and `lib/` against the working one,
+over `docs/`: 914 pages (912 `.md`, 2 `.html`) deep-equal, frontmatter, content and
+`contentLine` included, in the same order, and the same 281 static files. With gray-matter
+still installed, the tree comparison before any page edit matched in all three trees (1,461,
+1,457 and 137 files). Its after side was set aside, gray-matter uninstalled, and the tree
+comparison run again with `--before` a `git stash create` commit of the working tree; the
+two after sides, compared by a scratch script with `compare_trees`' normalisers, agree on
+every file, five of them once normalised (the Gantt chart twice over in two trees, and the
+book's build line). HEAD's side no longer builds once the package is gone, so the final tree
+comparison takes that stash commit as its before side: it differs only in Builder and
+Pipeline-Stages online and offline, the search data, and `book.html`.
+
 ### C41 — `wisdom: read pages and threads through lib/`
 
 **A10-2 (R1), A10-3 (R2).** Three frontmatter readers disagree: `wisdom/extract/sitemap.mjs:69-87`
diff --git a/builder/discover.mjs b/builder/discover.mjs
index 75741506..3dd86498 100644
--- a/builder/discover.mjs
+++ b/builder/discover.mjs
@@ -5,8 +5,8 @@
 import fg from "fast-glob";
 import { promises as fs } from "node:fs";
 import path from "node:path";
-import matter from "gray-matter";
 
+import { parseFrontmatter } from "../lib/frontmatter.mjs";
 import { permalinkToDestPath } from "./paths.mjs";
 
 const PAGE_EXT = /\.(md|html)$/i;
@@ -30,7 +30,7 @@ export async function discover(srcRoot, ignore = []) {
 
     if (PAGE_EXT.test(srcRel)) {
       const raw = await fs.readFile(srcPath, "utf8");
-      const parsed = parseFrontmatter(raw, srcRel);
+      const parsed = readFrontmatter(raw, srcRel);
       if (parsed) {
         pages.push(buildPage(srcRoot, srcRel, parsed));
         return;
@@ -91,35 +91,24 @@ function bySrcRel(a, b) {
   return a.srcRel < b.srcRel ? -1 : a.srcRel > b.srcRel ? 1 : 0;
 }
 
-// A UTF-8 BOM decodes to U+FEFF, which node's "utf8" reader hands back as
-// the first character rather than swallowing. gray-matter's `test` then sees
-// --- instead of ---, reports no frontmatter, and the caller files the
-// page as a static asset: it vanishes from the nav and the search index, and
-// its raw markdown is copied into the output tree and served verbatim,
-// frontmatter keys and all. That is what happened to
-// Reference/Built-In/AppGlobalClassObject/index.md, undetected, for months.
+// Every .md and .html passes through here, and `parseFrontmatter` drops a
+// leading BOM, so a page an editor saved with one is still a page rather than
+// a static asset served as raw markdown.
 //
-// Editors on Windows add a BOM without being asked, so this is a hazard any
-// contributor can reintroduce. Strip it here, at the one place every .md and
-// .html passes through, rather than policing the files.
-function stripBom(s) {
-  return s.charCodeAt(0) === 0xfeff ? s.slice(1) : s;
-}
-
 // `contentLine` is the file's 1-based line on which `content` starts, so a
 // message about a line of the content can name the line of the file. The
 // content is the text after the frontmatter block, so the lines before it are
 // the lines of the block.
-function parseFrontmatter(raw, srcRel) {
-  const text = stripBom(raw);
-  if (!matter.test(text)) return null;
-  let data, content;
+function readFrontmatter(raw, srcRel) {
+  let parsed;
   try {
-    ({ data, content } = matter(text));
+    parsed = parseFrontmatter(raw);
   } catch (err) {
     throw new Error(`Failed to parse frontmatter in ${srcRel}: ${err.message}`);
   }
-  const block = text.slice(0, text.length - content.length);
+  if (!parsed) return null;
+  const { data, content } = parsed;
+  const block = raw.slice(0, raw.length - content.length);
   return { data, content, contentLine: (block.match(/\r\n?|\n/g) ?? []).length + 1 };
 }
 
diff --git a/builder/publish-policy.mjs b/builder/publish-policy.mjs
index 4d650401..d8b1964f 100644
--- a/builder/publish-policy.mjs
+++ b/builder/publish-policy.mjs
@@ -36,10 +36,9 @@
 //
 // `.md` is deliberately absent. A markdown file that reaches this check is
 // one discover() could not parse frontmatter from, which is the shape of
-// the AppGlobalClassObject bug -- a UTF-8 BOM in front of the `---` made
-// gray-matter report no frontmatter, the page was filed as a static asset,
-// and its raw markdown was served verbatim for months. stripBom() fixed
-// that cause; this refuses the whole class.
+// the AppGlobalClassObject bug, where the raw markdown is served verbatim.
+// A BOM in front of the `---` was one cause, and lib/frontmatter.mjs strips
+// it now; this refuses the whole class.
 export const SOURCE_EXTENSIONS = new Set([
   ".css",
   ".gif",
@@ -105,12 +104,12 @@ function refuse(rel, extensions, declared) {
   if (extensions.has(ext)) return null;
 
   if (ext === ".md") {
-    // Not "check for a BOM": stripBom() removes one before parsing, so a
-    // BOM'd page renders normally and never reaches here. Nor is it
+    // Not "check for a BOM": parseFrontmatter removes one before parsing, so
+    // a BOM'd page renders normally and never reaches here. Nor is it
     // malformed YAML, which throws its own error naming the file and the
-    // parse fault. What is left is gray-matter finding no frontmatter
-    // block at all -- either there is none, or something precedes the
-    // opening `---`.
+    // parse fault. What is left is parseFrontmatter finding no frontmatter
+    // block at all -- either there is none, or the file's first line is
+    // something other than `---`.
     return "markdown with no frontmatter block -- it would be served as " +
            "raw markdown (the opening `---` must be the first line)";
   }
diff --git a/docs/Documentation/Builder.md b/docs/Documentation/Builder.md
index e531d0f2..f840fa61 100644
--- a/docs/Documentation/Builder.md
+++ b/docs/Documentation/Builder.md
@@ -429,7 +429,6 @@ A single `package.json` at the repo root contains everything --- the static site
     "acorn-walk": "^8.0",
     "axe-core": "4.13.0",
     "fast-glob": "^3.3",
-    "gray-matter": "^4.0",
     "html-entities": "^2.6.0",
     "htmlparser2": "^12.0.0",
     "js-yaml": "^4.1",
@@ -448,7 +447,7 @@ A single `package.json` at the repo root contains everything --- the static site
 }
 ```
 
-No template engine, no framework, no bundler, no postinstall hooks. For the site generator, the `markdown-it-*` packages cover the dialect extensions the legacy parser supported; `gray-matter` splits off page frontmatter and `js-yaml` parses `_config.yml` and `_book.yml`; `fast-glob` finds the source files; `shiki` is the syntax highlighter; `@hpcc-js/wasm-graphviz` is the WASM build of Graphviz that renders `.dot` diagram sources; `sass` is Dart Sass for the SCSS compile; `acorn` + `acorn-walk` parse the upstream `just-the-docs.js` for the AST-based offline patcher; `htmlparser2` is the SAX parser under the link and integrity check; and `picocolors` colours `tbdocs`'s terminal output. `puppeteer` + `pdf-lib` + `html-entities` are the PDF renderer's toolchain: puppeteer controls headless Chromium for the paged.js layout pass, and `html-entities` decodes the entities in the PDF outline's entries. `pako` is pdf-lib's own zlib library, declared because the renderer imports it too. `axe-core` + `puppeteer` also back the standalone accessibility checker ([`scripts/check_a11y.mjs`](https://github.com/twinbasic/documentation/blob/main/scripts/check_a11y.mjs)), which runs the same headless Chromium over the built pages, and `recheck` + `acorn` back the regex-safety gate ([`scripts/check_regex_safety.mjs`](https://github.com/twinbasic/documentation/blob/main/scripts/check_regex_safety.mjs)). `@biomejs/biome` is the repository's linter, which `biome.jsonc` limits to its correctness and suspicious rules, and the lint gate ([`scripts/check_lint.mjs`](https://github.com/twinbasic/documentation/blob/main/scripts/check_lint.mjs)) runs it. None of `axe-core`, `recheck` and `@biomejs/biome` is used by `tbdocs` itself.
+No template engine, no framework, no bundler, no postinstall hooks. For the site generator, the `markdown-it-*` packages cover the dialect extensions the legacy parser supported; `js-yaml` parses `_config.yml`, `_book.yml` and the page frontmatter that `lib/frontmatter.mjs` splits off; `fast-glob` finds the source files; `shiki` is the syntax highlighter; `@hpcc-js/wasm-graphviz` is the WASM build of Graphviz that renders `.dot` diagram sources; `sass` is Dart Sass for the SCSS compile; `acorn` + `acorn-walk` parse the upstream `just-the-docs.js` for the AST-based offline patcher; `htmlparser2` is the SAX parser under the link and integrity check; and `picocolors` colours `tbdocs`'s terminal output. `puppeteer` + `pdf-lib` + `html-entities` are the PDF renderer's toolchain: puppeteer controls headless Chromium for the paged.js layout pass, and `html-entities` decodes the entities in the PDF outline's entries. `pako` is pdf-lib's own zlib library, declared because the renderer imports it too. `axe-core` + `puppeteer` also back the standalone accessibility checker ([`scripts/check_a11y.mjs`](https://github.com/twinbasic/documentation/blob/main/scripts/check_a11y.mjs)), which runs the same headless Chromium over the built pages, and `recheck` + `acorn` back the regex-safety gate ([`scripts/check_regex_safety.mjs`](https://github.com/twinbasic/documentation/blob/main/scripts/check_regex_safety.mjs)). `@biomejs/biome` is the repository's linter, which `biome.jsonc` limits to its correctness and suspicious rules, and the lint gate ([`scripts/check_lint.mjs`](https://github.com/twinbasic/documentation/blob/main/scripts/check_lint.mjs)) runs it. None of `axe-core`, `recheck` and `@biomejs/biome` is used by `tbdocs` itself.
 
 **Which packages are pinned.** A package is pinned to an exact version where a new release could change what the build produces or what a gate reports without anything failing to say so: where the code patches the package or relies on its internals with no guard that fails when they change, or where the package's own results are what a gate reports. Everything else takes a caret range. Six packages are exact:
 
diff --git a/docs/Documentation/Pipeline-Stages.md b/docs/Documentation/Pipeline-Stages.md
index f31175b0..516dfd50 100644
--- a/docs/Documentation/Pipeline-Stages.md
+++ b/docs/Documentation/Pipeline-Stages.md
@@ -29,7 +29,7 @@ The pipeline passes three pieces of mutable state through every task: the `pages
 | `srcPath` | `discover` | `string` | Absolute filesystem path of the source file. |
 | `srcRel` | `discover` | `string` | POSIX-style path relative to `srcRoot`, e.g. `Reference/Core/Dim.md`. |
 | `ext` | `discover` | `string` | Lowercase file extension: `.md` or `.html`. |
-| `frontmatter` | `discover` | `object` | Parsed YAML frontmatter, with any leading UTF-8 BOM stripped before parsing (a BOM in front of the `---` otherwise makes `gray-matter` report no frontmatter at all, and the page is silently filed as a static asset). Only the named keys below are ever read --- nothing iterates this object, so an unrecognised key such as a package page's `indexed_from` is inert and never reaches the output. |
+| `frontmatter` | `discover` | `object` | Parsed YAML frontmatter, with any leading UTF-8 BOM stripped before parsing (a BOM in front of the `---` would otherwise hide the frontmatter, and the page would be silently filed as a static asset). Only the named keys below are ever read --- nothing iterates this object, so an unrecognised key such as a package page's `indexed_from` is inert and never reaches the output. |
 | `rawContent` | `discover` | `string` | Body text after the frontmatter block. |
 | `contentLine` | `discover` | `number` | The 1-based line of the source file on which `rawContent` starts. `validateCountNames` adds it to a line of `rawContent`, so its messages name the line of the file. |
 | `permalink` | `discover` | `string` | URL path from `frontmatter.permalink`. A fallback of `/<srcRel>.html` exists in `computePermalink`, but `nav`'s `validatePermalinks` aborts the build before it can matter --- the file tree does not mirror the URL tree, so a derived permalink is structurally wrong here. |
diff --git a/eval/nav_hops.mjs b/eval/nav_hops.mjs
index 8f57d8e6..719d3cbc 100644
--- a/eval/nav_hops.mjs
+++ b/eval/nav_hops.mjs
@@ -32,7 +32,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import matter from "gray-matter";
+import { parseFrontmatter } from "../lib/frontmatter.mjs";
 import { blockRegions } from "../lib/markdown.mjs";
 
 const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
@@ -71,8 +71,7 @@ async function loadPages(src) {
   const aliases = [];
   for (const rel of await markdownFiles(docs)) {
     const file = path.join(docs, rel);
-    // A BOM in front of the frontmatter hides it from gray-matter; builder/discover.mjs strips it too.
-    const { data } = matter(fs.readFileSync(file, "utf8").replace(/^/, ""));
+    const data = parseFrontmatter(fs.readFileSync(file, "utf8"))?.data ?? {};
     if (typeof data.permalink !== "string") continue;
     urlOf.set(file, data.permalink);
     byKey.set(pageKey(data.permalink), file);
diff --git a/lib/frontmatter.mjs b/lib/frontmatter.mjs
index ec93e584..c1a8b047 100644
--- a/lib/frontmatter.mjs
+++ b/lib/frontmatter.mjs
@@ -3,9 +3,7 @@
 //
 // markdown-it knows nothing of frontmatter and misreads it -- the opening `---`
 // as a rule, and the YAML up to the closing `---` as a setext heading -- so it
-// has to come off before any parse. gray-matter did this for the build, with a
-// js-yaml 3 of its own inside it, while the site configuration went through the
-// js-yaml 4 installed beside it.
+// has to come off before any parse.
 
 import yaml from "js-yaml";
 
@@ -17,8 +15,9 @@ const DELIMITER_RE = /^---[ \t]*$/;
  *
  * A block opens on the first line, which is `---`, and closes at the next line
  * that is `---`; either may carry trailing spaces or tabs. A leading BOM is
- * dropped first: editors on Windows add one unasked, and a page whose `---`
- * sits behind it was once published as a static file, raw markdown and all.
+ * dropped first: editors on Windows add one unasked, and a `---` behind one is
+ * not an opener, so the page would be published as a static file, raw
+ * markdown and all.
  *
  * `data` is the block parsed as YAML, or `{}` for an empty block or one of only
  * comments. `content` is everything after the closing line's ending, with its
diff --git a/package-lock.json b/package-lock.json
index ab85e354..064073b1 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -14,7 +14,6 @@
         "acorn-walk": "^8.0",
         "axe-core": "4.13.0",
         "fast-glob": "^3.3",
-        "gray-matter": "^4.0",
         "html-entities": "^2.6.0",
         "htmlparser2": "^12.0.0",
         "js-yaml": "^4.1",
@@ -1301,20 +1300,6 @@
         "node": ">=6"
       }
     },
-    "node_modules/esprima": {
-      "version": "4.0.1",
-      "resolved": "https://registry.npmjs.org/esprima/-/esprima-4.0.1.tgz",
-      "integrity": "sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A==",
-      "dev": true,
-      "license": "BSD-2-Clause",
-      "bin": {
-        "esparse": "bin/esparse.js",
-        "esvalidate": "bin/esvalidate.js"
-      },
-      "engines": {
-        "node": ">=4"
-      }
-    },
     "node_modules/events-universal": {
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/events-universal/-/events-universal-1.0.1.tgz",
@@ -1325,19 +1310,6 @@
         "bare-events": "^2.7.0"
       }
     },
-    "node_modules/extend-shallow": {
-      "version": "2.0.1",
-      "resolved": "https://registry.npmjs.org/extend-shallow/-/extend-shallow-2.0.1.tgz",
-      "integrity": "sha512-zCnTtlxNoAiDc3gqY2aYAWFx7XWWiasuF2K8Me5WbN8otHKTUKBwjPtNpRs/rbUZm7KxWAaNj7P1a/p52GbVug==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "is-extendable": "^0.1.0"
-      },
-      "engines": {
-        "node": ">=0.10.0"
-      }
-    },
     "node_modules/fast-fifo": {
       "version": "1.3.2",
       "resolved": "https://registry.npmjs.org/fast-fifo/-/fast-fifo-1.3.2.tgz",
@@ -1408,46 +1380,6 @@
         "node": ">= 6"
       }
     },
-    "node_modules/gray-matter": {
-      "version": "4.0.3",
-      "resolved": "https://registry.npmjs.org/gray-matter/-/gray-matter-4.0.3.tgz",
-      "integrity": "sha512-5v6yZd4JK3eMI3FqqCouswVqwugaA9r4dNZB1wwcmrD02QkV5H0y7XBQW8QwQqEaZY1pM9aqORSORhJRdNK44Q==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "js-yaml": "^3.13.1",
-        "kind-of": "^6.0.2",
-        "section-matter": "^1.0.0",
-        "strip-bom-string": "^1.0.0"
-      },
-      "engines": {
-        "node": ">=6.0"
-      }
-    },
-    "node_modules/gray-matter/node_modules/argparse": {
-      "version": "1.0.10",
-      "resolved": "https://registry.npmjs.org/argparse/-/argparse-1.0.10.tgz",
-      "integrity": "sha512-o5Roy6tNG4SL/FOkCAN6RzjiakZS25RLYFrcMttJqbdd8BWrnA+fGz57iN5Pb06pvBGvl5gQ0B48dJlslXvoTg==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "sprintf-js": "~1.0.2"
-      }
-    },
-    "node_modules/gray-matter/node_modules/js-yaml": {
-      "version": "3.15.2",
-      "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-3.15.2.tgz",
-      "integrity": "sha512-6EuL879VkRA+1Cz578mKMiKvjPNEuk6+r1JaFzoSWejZmtf7xWbIyw1e3KkxlkzTIt9Taw6JBhEppG7utc1P+w==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "argparse": "^1.0.7",
-        "esprima": "^4.0.0"
-      },
-      "bin": {
-        "js-yaml": "bin/js-yaml.js"
-      }
-    },
     "node_modules/hast-util-to-html": {
       "version": "9.0.5",
       "resolved": "https://registry.npmjs.org/hast-util-to-html/-/hast-util-to-html-9.0.5.tgz",
@@ -1568,16 +1500,6 @@
       "dev": true,
       "license": "MIT"
     },
-    "node_modules/is-extendable": {
-      "version": "0.1.1",
-      "resolved": "https://registry.npmjs.org/is-extendable/-/is-extendable-0.1.1.tgz",
-      "integrity": "sha512-5BMULNob1vgFX6EjQw5izWDxrecWK9AM72rugNr0TFldMOi0fj6Jk+zeKIt0xGj4cEfQIJth4w3OKWOJ4f+AFw==",
-      "dev": true,
-      "license": "MIT",
-      "engines": {
-        "node": ">=0.10.0"
-      }
-    },
     "node_modules/is-extglob": {
       "version": "2.1.1",
       "resolved": "https://registry.npmjs.org/is-extglob/-/is-extglob-2.1.1.tgz",
@@ -1658,16 +1580,6 @@
       "dev": true,
       "license": "MIT"
     },
-    "node_modules/kind-of": {
-      "version": "6.0.3",
-      "resolved": "https://registry.npmjs.org/kind-of/-/kind-of-6.0.3.tgz",
-      "integrity": "sha512-dcS1ul+9tmeD95T+x28/ehLgd9mENa3LsvDTtzm3vyBEO7RPptvAD+t44WVXaUjTBRcrpFeFlC8WCruUR456hw==",
-      "dev": true,
-      "license": "MIT",
-      "engines": {
-        "node": ">=0.10.0"
-      }
-    },
     "node_modules/lines-and-columns": {
       "version": "1.2.4",
       "resolved": "https://registry.npmjs.org/lines-and-columns/-/lines-and-columns-1.2.4.tgz",
@@ -2332,20 +2244,6 @@
         "@parcel/watcher": "^2.4.1"
       }
     },
-    "node_modules/section-matter": {
-      "version": "1.0.0",
-      "resolved": "https://registry.npmjs.org/section-matter/-/section-matter-1.0.0.tgz",
-      "integrity": "sha512-vfD3pmTzGpufjScBh50YHKzEu2lxBWhVEHsNGoEXmCmn2hKGfeNLYMzCJpe8cD7gqX7TJluOVpBkAequ6dgMmA==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "extend-shallow": "^2.0.1",
-        "kind-of": "^6.0.0"
-      },
-      "engines": {
-        "node": ">=4"
-      }
-    },
     "node_modules/semver": {
       "version": "7.8.0",
       "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.0.tgz",
@@ -2397,13 +2295,6 @@
         "url": "https://github.com/sponsors/wooorm"
       }
     },
-    "node_modules/sprintf-js": {
-      "version": "1.0.3",
-      "resolved": "https://registry.npmjs.org/sprintf-js/-/sprintf-js-1.0.3.tgz",
-      "integrity": "sha512-D9cPgkvLlV3t3IzL0D0YLvGA9Ahk4PcvVwUbN0dSGr1aP0Nrt4AEnTUbuGvquEC0mA64Gqt1fzirlRs5ibXx8g==",
-      "dev": true,
-      "license": "BSD-3-Clause"
-    },
     "node_modules/streamx": {
       "version": "2.25.0",
       "resolved": "https://registry.npmjs.org/streamx/-/streamx-2.25.0.tgz",
@@ -2459,16 +2350,6 @@
         "node": ">=8"
       }
     },
-    "node_modules/strip-bom-string": {
-      "version": "1.0.0",
-      "resolved": "https://registry.npmjs.org/strip-bom-string/-/strip-bom-string-1.0.0.tgz",
-      "integrity": "sha512-uCC2VHvQRYu+lMh4My/sFNmF2klFymLX1wHJeXnbEJERpV/ZsVuonzerjfrGpIGF7LBVa1O7i9kjiWvJiFck8g==",
-      "dev": true,
-      "license": "MIT",
-      "engines": {
-        "node": ">=0.10.0"
-      }
-    },
     "node_modules/synckit": {
       "version": "0.9.2",
       "resolved": "https://registry.npmjs.org/synckit/-/synckit-0.9.2.tgz",
diff --git a/package.json b/package.json
index bad90605..c4cc0970 100644
--- a/package.json
+++ b/package.json
@@ -10,7 +10,6 @@
     "acorn-walk": "^8.0",
     "axe-core": "4.13.0",
     "fast-glob": "^3.3",
-    "gray-matter": "^4.0",
     "html-entities": "^2.6.0",
     "htmlparser2": "^12.0.0",
     "js-yaml": "^4.1",

From 3f487326c30fbb0d098986b1e3ef790766533d11 Mon Sep 17 00:00:00 2001
From: Kuba Sunderland-Ober <kuba@mareimbrium.org>
Date: Sun, 27 Sep 2026 15:31:47 +0200
Subject: [PATCH 15/27] wisdom: read pages and threads through lib/

---
 builder/PLAN-TOOLING-REVIEW.md | 34 +++++++++++++++++++++
 wisdom/PLAN-3.md               |  2 +-
 wisdom/extract/prep.mjs        | 54 +++-------------------------------
 wisdom/extract/sitemap.mjs     | 43 +++++----------------------
 wisdom/files.mjs               | 20 +++++++++++--
 wisdom/process/frontmatter.mjs |  3 ++
 6 files changed, 68 insertions(+), 88 deletions(-)

diff --git a/builder/PLAN-TOOLING-REVIEW.md b/builder/PLAN-TOOLING-REVIEW.md
index 4613ae46..063381e5 100644
--- a/builder/PLAN-TOOLING-REVIEW.md
+++ b/builder/PLAN-TOOLING-REVIEW.md
@@ -1028,6 +1028,40 @@ harvested Discord title may hold. If a thread file has one, the harvester that w
 files quotes its values, and the existing files are fixed in the same commit. The walker
 returns the same files.
 
+**Landed.** `wisdom/files.mjs` gains `readFrontmatter(path)`: `parseFrontmatter`'s data, `{}`
+for a file with no block, and an error naming the file for a block that does not parse, as
+`readJsonFile` names a state file. `sitemap.mjs`'s `parseFrontmatter` and `walk()` and
+`prep.mjs`'s `parseThreadFrontmatter` go, and all three call sites read through it.
+`buildSitemap` lists its pages with `markdownFiles`, so it is async and `runExtract` awaits
+it. `findThreadMetadata` still skips a thread file it cannot read, which now includes one
+whose frontmatter does not parse; `runExtract` stops on such a file and names it. The
+serializer's `quote` says why every string is written quoted: YAML would read an unquoted
+snowflake as a number and lose its low digits. `wisdom/PLAN-3.md`'s layout line no longer
+says the sitemap has a parser of its own.
+
+**Verify.** The kit's `c41-oracle.mjs`, HEAD's two readers cut out of the files against
+`parseFrontmatter`. Threads: 1,847 files, 1,830 of them in channel folders; none throws and
+no snowflake is unquoted, and the record `prep.mjs` builds from each of the 1,830 is
+deep-equal. The whole frontmatter differs on 919 files, each on purpose: the old reader
+dropped the nested `top_reactions` (898 files) and `starter_reactions` (250), and kept the
+backslash of an escaped `"` in 41 titles; `prep.mjs` reads none of those. Pages: 760 under
+`docs/Reference`, none throws, and `title`, `permalink` and `parent` agree on 757. The other
+three are `Input.md`, `Line-Input.md` and `Write.md`, whose unquoted `title: Input #` YAML
+reads as `Input` with a comment after it, which is how the site has shown them since
+`042210e2`; the old reader kept the `#`. The keys the sitemap does not read differ as
+expected: numbers and booleans where the old reader gave strings (`nav_order`, `has_toc`,
+`has_children`, `vba_attribution`), and lists it dropped or kept as text (`redirect_from`,
+`symbols`, `exclude_from_docs`, `exclude_kinds`). The walk returns the same 760 files, in
+code-unit order where it was the file system's. With HEAD's three titles read as YAML reads
+them, the entries, the package summary and the page index are the same; only
+`page-index.json`'s key order differs. End to end, the kit's `c41-prep.mjs` runs HEAD's
+`runExtract` and the working one into scratch folders over the real threads (it starts no
+agent): the ten batch files and the manifest are byte-identical, `package-summary.txt`
+differs by the three ` #` (6 bytes), and `page-index.json` by the six keys that held them
+(12 bytes) and by its key order. An unclosed block, a YAML error and a list each throw with
+the file's path; a BOM and CRLF parse. The tree comparison is identical in all three trees
+(1,461, 1,457 and 137 files).
+
 *The link checker, the gates' scaffolding, the browser tools and the repository root:
 C42–C46.*
 
diff --git a/wisdom/PLAN-3.md b/wisdom/PLAN-3.md
index 3b97c278..43c1d3f3 100644
--- a/wisdom/PLAN-3.md
+++ b/wisdom/PLAN-3.md
@@ -401,7 +401,7 @@ wisdom/
     workflow.mjs    Workflow script (agent orchestration via Claude Code's Workflow tool)
     merger.mjs      parses staging.md, graft-merges DOC_ADDITIONs in place, atomic write
     state.mjs       reads / writes data/findings/extract-state.json (watermark + emission log)
-    sitemap.mjs     globs docs/Reference/**/*.md, parses YAML frontmatter (title, permalink, parent) with a minimal built-in parser — no dependency on builder/
+    sitemap.mjs     lists docs/Reference/**/*.md and reads each page's frontmatter (title, permalink, parent) through lib/
     prep.mjs        CLI handler: applies state filter, scans threads, writes shared + batch files
   data/
     findings/       gitignored
diff --git a/wisdom/extract/prep.mjs b/wisdom/extract/prep.mjs
index 34aa91d3..2d10290e 100644
--- a/wisdom/extract/prep.mjs
+++ b/wisdom/extract/prep.mjs
@@ -4,6 +4,7 @@ import { fileURLToPath } from 'node:url'
 import { buildSitemap, buildPackageSummary, buildPageIndex } from './sitemap.mjs'
 import { loadState, saveState, isThreadChanged, recordEmission } from './state.mjs'
 import { graftAdditions, renderSideband } from './merger.mjs'
+import { readFrontmatter } from '../files.mjs'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const REPO_ROOT = join(__dirname, '..', '..')
@@ -28,7 +29,7 @@ export async function runExtract(flags) {
   const mode = modeFlags[0] || 'incremental'
 
   // Build docs sitemap
-  const sitemap = buildSitemap(docsDir, REPO_ROOT)
+  const sitemap = await buildSitemap(docsDir, REPO_ROOT)
   const packageSummary = buildPackageSummary(sitemap)
   process.stderr.write(`[wisdom] Sitemap: ${sitemap.length} reference pages\n`)
 
@@ -64,7 +65,7 @@ export async function runExtract(flags) {
 
     for (const file of files) {
       const filePath = join(channelDir, file)
-      const fm = parseThreadFrontmatter(readFileSync(filePath, 'utf-8'))
+      const fm = readFrontmatter(filePath)
       if (!fm.thread_id) continue
 
       // --since filter: thread creation date
@@ -328,7 +329,7 @@ function findThreadMetadata(threadsDir, threadIds) {
       const tid = file.split('--')[0]
       if (!threadIds.has(tid)) continue
       try {
-        const fm = parseThreadFrontmatter(readFileSync(join(chDir, file), 'utf-8'))
+        const fm = readFrontmatter(join(chDir, file))
         result.set(tid, {
           last_message_id: fm.last_message_id || null,
           message_count: fm.message_count || 0,
@@ -338,50 +339,3 @@ function findThreadMetadata(threadsDir, threadIds) {
   }
   return result
 }
-
-function parseThreadFrontmatter(content) {
-  content = content.replace(/\r\n/g, '\n')
-  if (!content.startsWith('---')) return {}
-  const end = content.indexOf('\n---', 3)
-  if (end === -1) return {}
-  const block = content.slice(4, end)
-  const result = {}
-
-  for (const line of block.split('\n')) {
-    const m = line.match(/^(\w[\w_]*)\s*:\s*(.+)$/)
-    if (!m) continue
-    const key = m[1]
-    let val = m[2].trim()
-
-    // Inline array: [item, item, ...]
-    if (val.startsWith('[') && val.endsWith(']')) {
-      const inner = val.slice(1, -1).trim()
-      if (!inner) { result[key] = []; continue }
-      result[key] = inner.split(',').map(s => {
-        s = s.trim()
-        if ((s.startsWith('"') && s.endsWith('"')) ||
-            (s.startsWith("'") && s.endsWith("'"))) {
-          s = s.slice(1, -1)
-        }
-        return s
-      })
-      continue
-    }
-
-    // Strip quotes
-    if ((val.startsWith('"') && val.endsWith('"')) ||
-        (val.startsWith("'") && val.endsWith("'"))) {
-      val = val.slice(1, -1)
-    }
-
-    // Coerce booleans and numbers (but not snowflakes — those exceed 15 digits
-    // and must stay as strings to avoid float precision loss)
-    if (val === 'true') val = true
-    else if (val === 'false') val = false
-    else if (/^\d+$/.test(val) && val.length <= 15) val = parseInt(val, 10)
-
-    result[key] = val
-  }
-
-  return result
-}
diff --git a/wisdom/extract/sitemap.mjs b/wisdom/extract/sitemap.mjs
index 51542f7f..8614f8ed 100644
--- a/wisdom/extract/sitemap.mjs
+++ b/wisdom/extract/sitemap.mjs
@@ -1,20 +1,21 @@
-import { readdirSync, readFileSync } from 'node:fs'
 import { join, relative, sep } from 'node:path'
+import { markdownFiles } from '../../lib/markdown-files.mjs'
+import { readFrontmatter } from '../files.mjs'
 
-export function buildSitemap(docsDir, rootDir) {
+export async function buildSitemap(docsDir, rootDir) {
   const root = rootDir || process.cwd()
   const entries = []
-  walk(docsDir, filePath => {
-    if (!filePath.endsWith('.md')) return
-    const fm = parseFrontmatter(readFileSync(filePath, 'utf-8'))
-    if (!fm.title || !fm.permalink) return
+  for (const rel of await markdownFiles(docsDir)) {
+    const filePath = join(docsDir, rel)
+    const fm = readFrontmatter(filePath)
+    if (!fm.title || !fm.permalink) continue
     entries.push({
       path: relative(root, filePath).split(sep).join('/'),
       title: fm.title,
       permalink: fm.permalink,
       parent: fm.parent || null,
     })
-  })
+  }
   return entries
 }
 
@@ -57,31 +58,3 @@ export function buildPageIndex(sitemap) {
   }
   return index
 }
-
-function walk(dir, callback) {
-  for (const entry of readdirSync(dir, { withFileTypes: true })) {
-    const full = join(dir, entry.name)
-    if (entry.isDirectory()) walk(full, callback)
-    else callback(full)
-  }
-}
-
-function parseFrontmatter(content) {
-  content = content.replace(/\r\n/g, '\n')
-  if (!content.startsWith('---')) return {}
-  const end = content.indexOf('\n---', 3)
-  if (end === -1) return {}
-  const block = content.slice(4, end)
-  const result = {}
-  for (const line of block.split('\n')) {
-    const m = line.match(/^(\w[\w_]*)\s*:\s*(.+)$/)
-    if (!m) continue
-    let val = m[2].trim()
-    if ((val.startsWith('"') && val.endsWith('"')) ||
-        (val.startsWith("'") && val.endsWith("'"))) {
-      val = val.slice(1, -1)
-    }
-    result[m[1]] = val
-  }
-  return result
-}
diff --git a/wisdom/files.mjs b/wisdom/files.mjs
index c12e646f..c1c76460 100644
--- a/wisdom/files.mjs
+++ b/wisdom/files.mjs
@@ -1,10 +1,13 @@
-// files.mjs — how wisdom writes and reads the state files it keeps between runs.
+// files.mjs — how wisdom writes and reads the state files it keeps between runs,
+// and reads the frontmatter of the pages and threads it works from.
 //
 // A state file is written to `<file>.tmp` and renamed over the old one, so a
 // write cut off part way leaves the previous file whole.  A JSON state file
-// that does not parse is reported by its path, not as a bare SyntaxError.
+// that does not parse is reported by its path, not as a bare SyntaxError, and
+// so is a frontmatter block.
 
 import { existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { parseFrontmatter } from '../lib/frontmatter.mjs'
 
 /**
  * Write `text` to `path` through a temp file and a rename.  The caller makes
@@ -30,3 +33,16 @@ export function readJsonFile(path, fallback, remedy) {
     throw new Error(`${path} is not valid JSON (${err.message}). ${remedy}`)
   }
 }
+
+/**
+ * The frontmatter of the markdown file at `path` -- a documentation page or a
+ * harvested thread -- parsed as YAML, or `{}` when the file has none.  A block
+ * that does not parse throws an error that names the file.
+ */
+export function readFrontmatter(path) {
+  try {
+    return parseFrontmatter(readFileSync(path, 'utf-8'))?.data ?? {}
+  } catch (err) {
+    throw new Error(`${path} has frontmatter that does not parse (${err.message})`)
+  }
+}
diff --git a/wisdom/process/frontmatter.mjs b/wisdom/process/frontmatter.mjs
index 94336df6..4d47e7b1 100644
--- a/wisdom/process/frontmatter.mjs
+++ b/wisdom/process/frontmatter.mjs
@@ -105,6 +105,9 @@ export function serializeChannelFrontmatter(fm) {
   return lines.join('\n')
 }
 
+// Every string is written double-quoted, because the extract step reads these
+// blocks as YAML: unquoted, a snowflake id would parse as a number and lose its
+// low digits, and a title holding `: ` or ` #` would not parse as written.
 function quote(v) {
   if (typeof v === 'boolean') return v ? 'true' : 'false'
   if (typeof v === 'number') return String(v)

From 779fe14250d1b6c38e60e3443ef137738d2e839e Mon Sep 17 00:00:00 2001
From: Kuba Sunderland-Ober <kuba@mareimbrium.org>
Date: Sun, 27 Sep 2026 15:37:22 +0200
Subject: [PATCH 16/27] docs: quote the three statement titles that end in #

---
 builder/PLAN-TOOLING-REVIEW.md    | 24 ++++++++++++++++++++++++
 docs/Reference/Core/Input.md      |  2 +-
 docs/Reference/Core/Line-Input.md |  2 +-
 docs/Reference/Core/Write.md      |  2 +-
 4 files changed, 27 insertions(+), 3 deletions(-)

diff --git a/builder/PLAN-TOOLING-REVIEW.md b/builder/PLAN-TOOLING-REVIEW.md
index 063381e5..dc9c54b4 100644
--- a/builder/PLAN-TOOLING-REVIEW.md
+++ b/builder/PLAN-TOOLING-REVIEW.md
@@ -1062,6 +1062,24 @@ differs by the three ` #` (6 bytes), and `page-index.json` by the six keys that
 the file's path; a BOM and CRLF parse. The tree comparison is identical in all three trees
 (1,461, 1,457 and 137 files).
 
+### C41a — `docs: quote the three statement titles that end in #`
+
+**Found while landing C41.** `Input.md`, `Line-Input.md` and `Write.md` under
+`docs/Reference/Core/` have `title: Input #` and the like unquoted, and YAML reads ` #` as
+the start of a comment.
+
+**Change.** The three titles are quoted.
+
+**Landed.** As the entry says. No other frontmatter line under `docs/` holds an unquoted
+` #`: a grep for a key whose unquoted value contains one finds these three lines only.
+
+**Verify.** The tree comparison differs on all 914 pages online and offline, and on
+`book.html`. A word diff of the two kept trees, the Gantt chart's two files left out, finds
+nothing but the three titles gaining their `#`: the sidebar's link text on every page, the
+three pages' breadcrumbs, `<title>`, meta titles and JSON-LD headline, their entries in the
+search data, and their running heads in the book. The page count and the symbol index are
+unchanged.
+
 *The link checker, the gates' scaffolding, the browser tools and the repository root:
 C42–C46.*
 
@@ -2127,6 +2145,12 @@ Defects the review did not have, found by building something this plan asks for.
   it counted the fences the regex misses, not what it made of the lines after them. At the
   owner's choice it is fixed inside `builder, eval: counts, run_case and nav_hops skip code`
   rather than in place first.
+- **Three statement pages had lost the `#` from their titles**, found while landing C41.
+  `title: Input #`, `title: Line Input #` and `title: Write #` were unquoted, and YAML reads
+  ` #` as the start of a comment, so the site had titled the pages `Input`, `Line Input` and
+  `Write` (in the sidebar, the breadcrumb, the browser tab and the search) since `042210e2`
+  (2026-05-09). Wisdom's own reader kept the `#`, which is how C41's oracle saw the
+  difference. Fixed in `docs: quote the three statement titles that end in #`.
 
 ## Open questions
 
diff --git a/docs/Reference/Core/Input.md b/docs/Reference/Core/Input.md
index e5cf3adf..1bc037aa 100644
--- a/docs/Reference/Core/Input.md
+++ b/docs/Reference/Core/Input.md
@@ -1,5 +1,5 @@
 ---
-title: Input #
+title: "Input #"
 parent: Statements
 permalink: /tB/Core/Input
 vba_attribution: true
diff --git a/docs/Reference/Core/Line-Input.md b/docs/Reference/Core/Line-Input.md
index a9558046..c7aadb22 100644
--- a/docs/Reference/Core/Line-Input.md
+++ b/docs/Reference/Core/Line-Input.md
@@ -1,5 +1,5 @@
 ---
-title: Line Input #
+title: "Line Input #"
 parent: Statements
 permalink: /tB/Core/Line-Input
 vba_attribution: true
diff --git a/docs/Reference/Core/Write.md b/docs/Reference/Core/Write.md
index 57bd2811..05e5c39e 100644
--- a/docs/Reference/Core/Write.md
+++ b/docs/Reference/Core/Write.md
@@ -1,5 +1,5 @@
 ---
-title: Write #
+title: "Write #"
 parent: Statements
 permalink: /tB/Core/Write
 vba_attribution: true

From 184d5c273d192359be018d0a7fd1ef987f1785b1 Mon Sep 17 00:00:00 2001
From: Kuba Sunderland-Ober <kuba@mareimbrium.org>
Date: Sun, 27 Sep 2026 15:47:31 +0200
Subject: [PATCH 17/27] builder: warn about an unquoted frontmatter value that
 ends in #

---
 WIP.md                                |  2 +-
 builder/PLAN-TOOLING-REVIEW.md        | 30 +++++++++++
 builder/discover.mjs                  | 10 +++-
 docs/Documentation/Authoring.md       |  2 +
 docs/Documentation/Pipeline-Stages.md |  2 +-
 docs/Documentation/Tools.md           |  2 +-
 lib/README.md                         |  3 +-
 lib/frontmatter.mjs                   | 52 +++++++++++++++++-
 scripts/check_code_regions.mjs        | 77 +++++++++++++++++++++++----
 9 files changed, 164 insertions(+), 16 deletions(-)

diff --git a/WIP.md b/WIP.md
index aea8d848..071e5dfe 100644
--- a/WIP.md
+++ b/WIP.md
@@ -500,7 +500,7 @@ wrapper:
 | `check.bat` | `check_tree_fresh` | the tree is not older than the sources that produced it |
 | `check.bat` | `check_dot_fit` | every diagram label sits inside the box Graphviz drew for it |
 | `check.bat` | `pick_a11y_sample --check`, `check_a11y` | see [WIP.A11y.md](WIP.A11y.md) |
-| `test.bat` | `check_code_regions` | no source or HTML rewrite altered a code region; `lib/markdown.mjs` and `lib/frontmatter.mjs` pass their probes, and the block parse finds what the full parse finds; the count-name check skips code and names the file's line; the dash normaliser converts only prose |
+| `test.bat` | `check_code_regions` | no source or HTML rewrite altered a code region; `lib/markdown.mjs` and `lib/frontmatter.mjs` pass their probes, and the block parse finds what the full parse finds; the count-name check skips code and names the file's line; `discover` warns about an unquoted frontmatter value that ends in `#`; the dash normaliser converts only prose |
 | `test.bat` | `check_regex_safety` | no regex in the tree can backtrack exponentially |
 | `test.bat` | `check_symbol_index` | the symbol index still places each kind of symbol, from fixtures |
 | `test.bat` | `check_ci_workflows` | both CI workflows run every wrapper gate, with the same arguments and order, and build with `build.bat`'s flags |
diff --git a/builder/PLAN-TOOLING-REVIEW.md b/builder/PLAN-TOOLING-REVIEW.md
index dc9c54b4..4193d586 100644
--- a/builder/PLAN-TOOLING-REVIEW.md
+++ b/builder/PLAN-TOOLING-REVIEW.md
@@ -1080,6 +1080,36 @@ three pages' breadcrumbs, `<title>`, meta titles and JSON-LD headline, their ent
 search data, and their running heads in the book. The page count and the symbol index are
 unchanged.
 
+### C41b — `builder: warn about an unquoted frontmatter value that ends in #`
+
+**The owner's request, after C41a.** Nothing told the author of C41a's three pages that YAML
+had dropped their `#`. The build warns when a frontmatter value left unquoted ends in `#`,
+whitespace after the `#` aside, so the author is reminded to check; quoting the value
+always silences it.
+
+**Landed.** `lib/frontmatter.mjs` gains `unquotedHashValues(raw)`, the block's lines whose
+value is unquoted and ends in `#`, as `{ line, text }` counted from the opening `---`; it
+shares a new private `splitBlock` with `parseFrontmatter`, which is otherwise unchanged. A
+key's value, a list item, and a key opening a list item are checked; a comment line, a key
+whose value is on the lines below, and the lines of a `|` or `>` block scalar are not, since
+a scalar cannot be quoted. A value such as `C#`, which YAML keeps whole, is still reported,
+as the rule asks. `discover.mjs`'s `readFrontmatter` prints each as `discover:
+<page>:<line>: an unquoted value ends in #, ...` with the line's text, and the build goes on.
+`check_code_regions.mjs` gains a module probe (eighteen lines: five reported, among them a
+BOM, CRLF, trailing spaces and a list item's key; a quoted value, a quoted value followed by
+a bare `#`, a comment, a list of quoted items and a block scalar's lines not) and a
+`discover` probe that captures `console.warn` over a real page. Authoring.md's frontmatter
+section, Pipeline-Stages.md's `frontmatter` row, Tools.md's section on the gate, WIP.md's
+gate row and `lib/README.md` say so.
+
+**Verify.** On today's 912 pages no frontmatter line ends in `#` and none holds a block
+scalar, so the build prints no warning. With C41a's `title: "Input #"` put back unquoted and
+three spaces after the `#`, a build printed `discover: Reference/Core/Input.md:2: an
+unquoted value ends in #, ...: title: Input #` and exited 0. Four faults put into the code
+each fail `check_code_regions`: no call in `discover` (the `discover` probe), no block-scalar
+skip (line 16 reported), no allowance for trailing whitespace (line 5 missed), and no quote
+check (line 18 reported).
+
 *The link checker, the gates' scaffolding, the browser tools and the repository root:
 C42–C46.*
 
diff --git a/builder/discover.mjs b/builder/discover.mjs
index 3dd86498..1aeda546 100644
--- a/builder/discover.mjs
+++ b/builder/discover.mjs
@@ -6,7 +6,7 @@ import fg from "fast-glob";
 import { promises as fs } from "node:fs";
 import path from "node:path";
 
-import { parseFrontmatter } from "../lib/frontmatter.mjs";
+import { parseFrontmatter, unquotedHashValues } from "../lib/frontmatter.mjs";
 import { permalinkToDestPath } from "./paths.mjs";
 
 const PAGE_EXT = /\.(md|html)$/i;
@@ -99,6 +99,11 @@ function bySrcRel(a, b) {
 // message about a line of the content can name the line of the file. The
 // content is the text after the frontmatter block, so the lines before it are
 // the lines of the block.
+//
+// A value left unquoted that ends in `#` is warned about, not refused: YAML
+// drops a `#` after a space as a comment, so `title: Input #` titles the page
+// `Input`, while `lang: C#` is read as written. Quoting the value keeps the `#`
+// and silences the warning either way.
 function readFrontmatter(raw, srcRel) {
   let parsed;
   try {
@@ -107,6 +112,9 @@ function readFrontmatter(raw, srcRel) {
     throw new Error(`Failed to parse frontmatter in ${srcRel}: ${err.message}`);
   }
   if (!parsed) return null;
+  for (const { line, text } of unquotedHashValues(raw)) {
+    console.warn(`discover: ${srcRel}:${line}: an unquoted value ends in #, and YAML drops a # after a space as a comment; quote the value to keep it: ${text.trim()}`);
+  }
   const { data, content } = parsed;
   const block = raw.slice(0, raw.length - content.length);
   return { data, content, contentLine: (block.match(/\r\n?|\n/g) ?? []).length + 1 };
diff --git a/docs/Documentation/Authoring.md b/docs/Documentation/Authoring.md
index d123339a..69872227 100644
--- a/docs/Documentation/Authoring.md
+++ b/docs/Documentation/Authoring.md
@@ -168,6 +168,8 @@ A package's `index.md` may also carry **`indexed_from`**, **`exclude_from_docs`*
 
 Any key the build does not recognise is simply inert --- nothing iterates frontmatter generically, so an unknown key is never emitted into the page. A key whose *value* is not valid YAML is a different matter: the build aborts with `Failed to parse frontmatter in <file>`, quoting the YAML parser's own line and column.
 
+A value that is valid YAML can still mean less than it shows. YAML reads a `#` after a space, and everything after it, as a comment, so `title: Input #` titles the page *Input*. The build warns about any value left unquoted that ends in `#`, naming the file and line, and goes on building. Quote the value --- `title: "Input #"` --- to keep the `#`. Quoting also silences the warning where YAML would have kept the `#` anyway, as in `C#`.
+
 A minimal reference-page header:
 
 ```yaml
diff --git a/docs/Documentation/Pipeline-Stages.md b/docs/Documentation/Pipeline-Stages.md
index 516dfd50..0ed8a8a2 100644
--- a/docs/Documentation/Pipeline-Stages.md
+++ b/docs/Documentation/Pipeline-Stages.md
@@ -29,7 +29,7 @@ The pipeline passes three pieces of mutable state through every task: the `pages
 | `srcPath` | `discover` | `string` | Absolute filesystem path of the source file. |
 | `srcRel` | `discover` | `string` | POSIX-style path relative to `srcRoot`, e.g. `Reference/Core/Dim.md`. |
 | `ext` | `discover` | `string` | Lowercase file extension: `.md` or `.html`. |
-| `frontmatter` | `discover` | `object` | Parsed YAML frontmatter, with any leading UTF-8 BOM stripped before parsing (a BOM in front of the `---` would otherwise hide the frontmatter, and the page would be silently filed as a static asset). Only the named keys below are ever read --- nothing iterates this object, so an unrecognised key such as a package page's `indexed_from` is inert and never reaches the output. |
+| `frontmatter` | `discover` | `object` | Parsed YAML frontmatter, with any leading UTF-8 BOM stripped before parsing (a BOM in front of the `---` would otherwise hide the frontmatter, and the page would be silently filed as a static asset). A value left unquoted that ends in `#` gets a `discover:` warning naming its file and line, since YAML reads a `#` after a space as the start of a comment. Only the named keys below are ever read --- nothing iterates this object, so an unrecognised key such as a package page's `indexed_from` is inert and never reaches the output. |
 | `rawContent` | `discover` | `string` | Body text after the frontmatter block. |
 | `contentLine` | `discover` | `number` | The 1-based line of the source file on which `rawContent` starts. `validateCountNames` adds it to a line of `rawContent`, so its messages name the line of the file. |
 | `permalink` | `discover` | `string` | URL path from `frontmatter.permalink`. A fallback of `/<srcRel>.html` exists in `computePermalink`, but `nav`'s `validatePermalinks` aborts the build before it can matter --- the file tree does not mirror the URL tree, so a derived permalink is structurally wrong here. |
diff --git a/docs/Documentation/Tools.md b/docs/Documentation/Tools.md
index f088d5dc..059ceda0 100644
--- a/docs/Documentation/Tools.md
+++ b/docs/Documentation/Tools.md
@@ -425,7 +425,7 @@ Probes ride along in the normal run, each a defect this repository actually ship
 
 The admonition probes test the mirror fault, which the region comparison structurally cannot see: **a rewrite that misreads what is code can also fail to fire on real prose**, and the regions still come back identical because the text was only stashed and restored. `Reference/Attributes.md` shipped all six of its admonitions as the literal text `[!NOTE]` for exactly that reason --- a `[Description(...)]` sample whose argument is a Markdown string containing two fence markers as twinBASIC string literals, which the fence stasher closed the surrounding fence on. Every pairing after it was off by one.
 
-It is also the gate on `lib/markdown.mjs` and `lib/frontmatter.mjs`, the modules that tell the tools what in a page is code and where its frontmatter ends. Their probes run with the others, and on every page the sweep checks that `blockRegions`, which parses blocks only, finds exactly the fences, code blocks and HTML blocks of a full parse. The summary line gives the number of fences that full parse found. Three more probes hold the build to the same answer: the rewrite chain must leave alone a fence that only the site's parser finds, and an admonition written inside one, and the build's check of `{{tbdocs:<name>}}` count names must skip names in code and give an unknown one's line in its file. Another set holds [`convert_em_dash_separators.mjs`](#convert-em-dash-separators), which rewrites page source by hand rather than in the build, to converting prose and nothing else.
+It is also the gate on `lib/markdown.mjs` and `lib/frontmatter.mjs`, the modules that tell the tools what in a page is code and where its frontmatter ends. Their probes run with the others, and on every page the sweep checks that `blockRegions`, which parses blocks only, finds exactly the fences, code blocks and HTML blocks of a full parse. The summary line gives the number of fences that full parse found. Three more probes hold the build to the same answer: the rewrite chain must leave alone a fence that only the site's parser finds, and an admonition written inside one, and the build's check of `{{tbdocs:<name>}}` count names must skip names in code and give an unknown one's line in its file. One more holds the build's warning about a frontmatter value left unquoted that ends in `#`: `discover` must name the page and line of `title: Input #`, and say nothing about a quoted value. Another set holds [`convert_em_dash_separators.mjs`](#convert-em-dash-separators), which rewrites page source by hand rather than in the build, to converting prose and nothing else.
 
 `--verbose` prints the first few altered regions of each failing file, before and after. `--self-test` replaces the normal run rather than adding to it, so neither the probes nor the sweep runs: it de-indents the body of one small fence by hand and passes only if the comparison notices. That proves the comparator can still see a change, and nothing more --- it runs no rewrite at all.
 
diff --git a/lib/README.md b/lib/README.md
index 5b097cd1..b2904f17 100644
--- a/lib/README.md
+++ b/lib/README.md
@@ -16,7 +16,8 @@ its lines, a mask that hides the code from a rewrite and restores it, the code
 spans on a line, sections split on a marker line outside any code, and a line
 map that keeps each line's ending. [frontmatter.mjs](frontmatter.mjs) splits
 off a page's YAML frontmatter and parses it with the `js-yaml` the rest of the
-tooling uses. `scripts/check_code_regions.mjs` carries the probes for both, and
+tooling uses, and lists the values left unquoted that end in `#`, since YAML
+reads a `#` after a space as a comment. `scripts/check_code_regions.mjs` carries the probes for both, and
 checks on every page that the block parse finds what a full parse finds.
 
 `scripts/check_tree_fresh.mjs` counts `lib/` among the inputs that decide the
diff --git a/lib/frontmatter.mjs b/lib/frontmatter.mjs
index c1a8b047..df00d570 100644
--- a/lib/frontmatter.mjs
+++ b/lib/frontmatter.mjs
@@ -28,6 +28,56 @@ const DELIMITER_RE = /^---[ \t]*$/;
  * `raw` it is on, counting the opening `---` as line 1.
  */
 export function parseFrontmatter(raw) {
+  const split = splitBlock(raw);
+  return split && { data: parseBlock(split.block), content: split.content };
+}
+
+/**
+ * The lines of `raw`'s frontmatter block that give a value unquoted and end in
+ * `#`, trailing whitespace aside, as `{ line, text }` with `line` counted from
+ * the opening `---` as line 1. YAML reads a `#` after whitespace as the start
+ * of a comment, so `title: Input #` is the title `Input`; quoting the value
+ * keeps the `#` and leaves it off this list. A key's value on its own line and
+ * a list item are checked; the lines of a `|` or `>` block scalar are not,
+ * since a `#` there is text and the scalar cannot be quoted.
+ *
+ * Returns `[]` when `raw` has no block, and throws as `parseFrontmatter` does
+ * when the block is never closed.
+ */
+export function unquotedHashValues(raw) {
+  const split = splitBlock(raw);
+  if (!split) return [];
+  const found = [];
+  let scalarIndent = -1;
+  split.block.split(/\r\n|\n|\r/).forEach((text, i) => {
+    const indent = text.search(/\S/);
+    if (scalarIndent >= 0) {
+      if (indent < 0 || indent > scalarIndent) return;
+      scalarIndent = -1;
+    }
+    const value = valueOn(text);
+    if (value === undefined) return;
+    if (BLOCK_SCALAR_RE.test(value)) scalarIndent = indent;
+    else if (!/^["']/.test(value) && /#\s*$/.test(value)) found.push({ line: i + 2, text });
+  });
+  return found;
+}
+
+const ITEM_RE = /^\s*-\s+(\S.*)$/;
+const KEY_RE = /^\s*[^\s#-][^:]*:\s+(\S.*)$/;
+const BLOCK_SCALAR_RE = /^[|>][-+0-9]*\s*(?:#.*)?$/;
+
+// The value a line gives: a key's, a list item's, or the value of a key that
+// opens a list item. Undefined for a comment, a blank line, a key whose value
+// is on the lines below it, and any other line.
+function valueOn(text) {
+  const item = ITEM_RE.exec(text)?.[1];
+  return KEY_RE.exec(item ?? text)?.[1] ?? item;
+}
+
+// The block's text between its two `---` lines, and the text after the
+// closing line's ending; null when `raw` does not open a block.
+function splitBlock(raw) {
   const text = raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw;
   let pos = 0;
   let blockStart = -1;
@@ -40,7 +90,7 @@ export function parseFrontmatter(raw) {
       if (!isDelimiter || end === text.length) return null;
       blockStart = next;
     } else if (isDelimiter) {
-      return { data: parseBlock(text.slice(blockStart, pos)), content: text.slice(next) };
+      return { block: text.slice(blockStart, pos), content: text.slice(next) };
     }
     pos = next;
   }
diff --git a/scripts/check_code_regions.mjs b/scripts/check_code_regions.mjs
index 90d00aa8..79f36431 100644
--- a/scripts/check_code_regions.mjs
+++ b/scripts/check_code_regions.mjs
@@ -65,8 +65,9 @@
 // blockRegions, which parses blocks only, finds exactly the fences, code
 // blocks and HTML blocks of the full parse the comparison already makes. One
 // probe holds builder/counts.mjs's count validator, which asks the same module
-// what is code, and a set holds scripts/convert_em_dash_separators.mjs, which
-// rewrites page source outside the build and asks it too.
+// what is code, another builder/discover.mjs's warning about a frontmatter
+// value that ends in `#`, and a set holds scripts/convert_em_dash_separators.mjs,
+// which rewrites page source outside the build and asks it too.
 
 import assert from "node:assert/strict";
 import { promises as fs } from "node:fs";
@@ -79,7 +80,7 @@ import deflist from "markdown-it-deflist";
 import { validateCountNames } from "../builder/counts.mjs";
 import { discover } from "../builder/discover.mjs";
 import { applyPreRenderRewrites, createMarkdownIt } from "../builder/render.mjs";
-import { parseFrontmatter } from "../lib/frontmatter.mjs";
+import { parseFrontmatter, unquotedHashValues } from "../lib/frontmatter.mjs";
 import { blockRegions, mapLines, maskCode, splitCodeSpans, splitOnMarker } from "../lib/markdown.mjs";
 import { markdownFiles } from "../lib/markdown-files.mjs";
 import { convertText } from "./convert_em_dash_separators.mjs";
@@ -338,6 +339,35 @@ const MODULE_PROBES = [
     assert.throws(() => parseFrontmatter("---\n- a list\n---\n"), /not a mapping/);
     assert.throws(() => parseFrontmatter("---\nok: 1\nbad: [\n---\n"), /\(4:1\)/);
   }],
+  ["an unquoted value that ends in # is reported, a quoted one is not", () => {
+    assert.equal(parseFrontmatter("---\ntitle: Input #\n---\n").data.title, "Input");
+    const src = [
+      "\u{FEFF}---",
+      "title: Input #",
+      "parent: Statements",
+      'quoted: "Write #"',
+      "lang: C#  ",
+      "comment: x # a note",
+      "# title: y #",
+      "list:",
+      "  - Line Input #",
+      "  - 'kept #'",
+      "  - key: v #",
+      '  - key: "v #"',
+      "text: |",
+      "  a line #",
+      "",
+      "  - key: v #",
+      "after: z #",
+      'tail: "quoted" #',
+      "---",
+      "body: b #",
+    ].join("\r\n");
+    assert.deepEqual(unquotedHashValues(src).map((f) => f.line), [2, 5, 9, 11, 17]);
+    assert.equal(unquotedHashValues(src)[0].text, "title: Input #");
+    assert.deepEqual(unquotedHashValues("body: b #\n"), []);
+    assert.throws(() => unquotedHashValues("---\nx: 1 #\n"), /never closed/);
+  }],
 ];
 
 // The count validator asks the same module what is code, with the site's
@@ -367,6 +397,30 @@ async function countProbe() {
   }
 }
 
+// discover warns about a frontmatter value left unquoted that ends in `#`,
+// naming the page and the line, and reads the page as YAML does: the `#` after
+// a space is a comment. A quoted value, and a `#` in the content, say nothing.
+async function hashProbe() {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "check-code-regions-"));
+  const warn = console.warn;
+  const warned = [];
+  console.warn = (message) => warned.push(message);
+  try {
+    await fs.writeFile(path.join(dir, "x.md"), '---\r\ntitle: Input #\r\nparent: "Write #"\r\n---\r\nbody #\r\n');
+    const { pages } = await discover(dir);
+    assert.equal(pages[0].frontmatter.title, "Input");
+    assert.deepEqual(warned.map((message) => message.split(": an unquoted")[0]), ["discover: x.md:2"]);
+  } finally {
+    console.warn = warn;
+    await fs.rm(dir, { recursive: true, force: true });
+  }
+}
+
+const DISCOVER_PROBES = [
+  ["the count validator's references and lines", countProbe],
+  ["discover's warning about an unquoted value that ends in #", hashProbe],
+];
+
 async function main(argv) {
   const verbose = argv.includes("--verbose");
 
@@ -428,13 +482,15 @@ async function main(argv) {
       for (const line of err.message.split("\n")) console.log(`        ${line}`);
     }
   }
-  try {
-    await countProbe();
-  } catch (err) {
-    if (!(err instanceof assert.AssertionError)) throw err;
-    failed++;
-    console.log("FAIL  probe: the count validator's references and lines");
-    for (const line of err.message.split("\n")) console.log(`        ${line}`);
+  for (const [name, probe] of DISCOVER_PROBES) {
+    try {
+      await probe();
+    } catch (err) {
+      if (!(err instanceof assert.AssertionError)) throw err;
+      failed++;
+      console.log(`FAIL  probe: ${name}`);
+      for (const line of err.message.split("\n")) console.log(`        ${line}`);
+    }
   }
 
   if (!failed) {
@@ -444,6 +500,7 @@ async function main(argv) {
     console.log(`ok    ${DASH_PROBES.length} probes: the dash normaliser converts prose and nothing else`);
     console.log(`ok    ${MODULE_PROBES.length} probes: lib/markdown.mjs and lib/frontmatter.mjs`);
     console.log("ok    1 probe: the count validator skips code and names the file's line");
+    console.log("ok    1 probe: discover warns about an unquoted value that ends in #");
   }
 
   const files = await markdownFiles(ROOT);

From 0bfc1e4317e2eae2704d838df57788096ed65bda Mon Sep 17 00:00:00 2001
From: Kuba Sunderland-Ober <kuba@mareimbrium.org>
Date: Sun, 27 Sep 2026 15:51:33 +0200
Subject: [PATCH 18/27] wisdom: group reference pages by package, below
 Default/ and Built-In/

---
 builder/PLAN-TOOLING-REVIEW.md | 41 +++++++++++++++++++++++++++++++++-
 wisdom/extract/sitemap.mjs     | 15 ++++++++-----
 2 files changed, 50 insertions(+), 6 deletions(-)

diff --git a/builder/PLAN-TOOLING-REVIEW.md b/builder/PLAN-TOOLING-REVIEW.md
index 4193d586..ed9be015 100644
--- a/builder/PLAN-TOOLING-REVIEW.md
+++ b/builder/PLAN-TOOLING-REVIEW.md
@@ -1110,6 +1110,30 @@ each fail `check_code_regions`: no call in `discover` (the `discover` probe), no
 skip (line 16 reported), no allowance for trailing whitespace (line 5 missed), and no quote
 check (line 18 reported).
 
+### C41c — `wisdom: group reference pages by package, below Default/ and Built-In/`
+
+**Found while landing C41.** `buildPackageSummary` and `buildPageIndex` take the first
+folder under `docs/Reference/` as a page's package, and since `58a5e1c` that folder is
+`Default`, `Built-In` or `Core`.
+
+**Change.** Both take a page's parts through one `packageParts(path)`, which drops
+`docs/Reference/` and then a `Default/` or `Built-In/`.
+
+**Landed.** As the entry says. Wisdom.md already describes `Package > Module` lines and
+`Package/Title` keys, so no page changes. The Assert package groups as
+`TwinBasicAssertions`, its folder's name, where the last summary written (2026-06-04, from a
+tree before the move) said `Assert`; the grouping has always been by folder. Open
+questions keeps this, at the owner's request.
+
+**Verify.** The kit's `c41c-oracle.mjs`, HEAD's two functions against the working ones over
+one sitemap: the summary goes from three groups to 40, VBA and VBRUN split by module again,
+and lists 735 titles where it listed 726, since a title shared by two packages no longer
+collapses into one group. The page index goes from 1,492 keys to 1,500, its 740 bare-title
+keys and their paths unchanged, and the pages a `Package/Title` key reaches from 751 to 759
+of 760, none lost. The kit's `c41-prep.mjs`, HEAD's `runExtract` against the working one:
+the batch files and the manifest are byte-identical, and only `package-summary.txt` and
+`page-index.json` differ.
+
 *The link checker, the gates' scaffolding, the browser tools and the repository root:
 C42–C46.*
 
@@ -2181,6 +2205,14 @@ Defects the review did not have, found by building something this plan asks for.
   `Write` (in the sidebar, the breadcrumb, the browser tab and the search) since `042210e2`
   (2026-05-09). Wisdom's own reader kept the `#`, which is how C41's oracle saw the
   difference. Fixed in `docs: quote the three statement titles that end in #`.
+- **Wisdom's extract grouped the reference as `Default`, `Built-In` and `Core`**, found while
+  landing C41. `buildPackageSummary` and `buildPageIndex` took the first folder under
+  `docs/Reference/` as a page's package, and `58a5e1c` (2026-06-03) moved the packages one
+  folder down. From then on `package-summary.txt` would have held three groups where the
+  Extract agents are told to expect `Package > Module` lines, and `page-index.json`'s keys
+  read `Default/<title>`, so that pages of one title in two packages hid all but one. No
+  extract run has used it: the one on disk predates the move. Fixed in `wisdom: group
+  reference pages by package, below Default/ and Built-In/`.
 
 ## Open questions
 
@@ -2192,7 +2224,14 @@ decides otherwise:
 - whether `test.bat` without Python fails or skips `check_impexp_parity.mjs` loudly: C70,
   decision (b)'s open question, which the owner settled on 2026-09-25: it skips, loudly;
 - whether the pre-commit hook should also run the dash check, which A6-3 assumed: the owner
-  approved a hook that runs Biome only (C08), so it stays out unless the owner asks for it.
+  approved a hook that runs Biome only (C08), so it stays out unless the owner asks for it;
+- what Wisdom's extract should call the Assert package: its reference folder is
+  `docs/Reference/Built-In/TwinBasicAssertions/`, while the package's title, nav parent and
+  permalinks say `Assert`. Since C41c `package-summary.txt` groups it as
+  `TwinBasicAssertions` and `page-index.json` keys it `TwinBasicAssertions/<title>`; the last
+  summary written (2026-06-04, before `58a5e1c` reached it) said `Assert`, the name a thread
+  on Discord would use. Kept at the owner's request, to be picked up later; no commit is
+  named yet.
 
 The two questions this plan started with are settled: the two link checkers (decision 5), and
 the survey script, which is committed.
diff --git a/wisdom/extract/sitemap.mjs b/wisdom/extract/sitemap.mjs
index 8614f8ed..ef66384f 100644
--- a/wisdom/extract/sitemap.mjs
+++ b/wisdom/extract/sitemap.mjs
@@ -19,11 +19,18 @@ export async function buildSitemap(docsDir, rootDir) {
   return entries
 }
 
+// A reference page's path from its package down: docs/Reference/Default/VBA/
+// Strings/Len.md gives [VBA, Strings, Len.md].  Default/ and Built-In/ only sort
+// the packages into those every project references and those it may; Core/,
+// the language itself, sits directly under docs/Reference/.
+function packageParts(path) {
+  return path.replace(/^docs\/Reference\/(?:(?:Default|Built-In)\/)?/, '').split('/')
+}
+
 export function buildPackageSummary(sitemap) {
   const groups = {}
   for (const entry of sitemap) {
-    const rel = entry.path.replace(/^docs\/Reference\//, '')
-    const parts = rel.split('/')
+    const parts = packageParts(entry.path)
     if (parts.length < 2) continue
     const pkg = parts[0]
     const isModule = (pkg === 'VBA' || pkg === 'VBRUN') && parts.length > 2
@@ -44,9 +51,7 @@ export function buildPageIndex(sitemap) {
   const index = {}
   const titleCount = {}
   for (const entry of sitemap) {
-    const rel = entry.path.replace(/^docs\/Reference\//, '')
-    const parts = rel.split('/')
-    const pkg = parts[0]
+    const pkg = packageParts(entry.path)[0]
     index[`${pkg}/${entry.title}`] = entry.path
     titleCount[entry.title] = (titleCount[entry.title] || 0) + 1
   }

From 96d8fd3e68f600c4428ffafb2d4c951c7054c6e4 Mon Sep 17 00:00:00 2001
From: Kuba Sunderland-Ober <kuba@mareimbrium.org>
Date: Sun, 27 Sep 2026 16:15:21 +0200
Subject: [PATCH 19/27] scripts: check_links.mjs becomes a thin wrapper over
 builder/check.mjs

---
 .github/workflows/checks.yml          |   2 +-
 WIP.Build.md                          |  10 +-
 builder/PLAN-TOOLING-REVIEW.md        |  47 +++
 builder/README.md                     |   9 +-
 builder/check.mjs                     |  65 ++--
 builder/link-check.mjs                |   8 +-
 builder/page-baseline.mjs             |   8 +-
 docs/Documentation/Builder.md         |   2 +-
 docs/Documentation/Building.md        |   2 +-
 docs/Documentation/Extending.md       |   4 +-
 docs/Documentation/Pipeline-Stages.md |   8 +-
 docs/Documentation/Tools.md           |   8 +-
 scripts/check_gate_lists.mjs          |   5 +-
 scripts/check_links.mjs               | 482 +++++++++-----------------
 scripts/check_links_diff.mjs          |  19 +-
 test/README.md                        |  14 +-
 16 files changed, 306 insertions(+), 387 deletions(-)

diff --git a/.github/workflows/checks.yml b/.github/workflows/checks.yml
index 6ca64c04..85a28b39 100644
--- a/.github/workflows/checks.yml
+++ b/.github/workflows/checks.yml
@@ -76,7 +76,7 @@ jobs:
         # trees out and reading ~270 MB of them back through
         # scripts/check_links.mjs. Same findings -- that equivalence is
         # gated by scripts/check_links_diff.mjs, run by hand when either
-        # implementation changes. Do NOT also add a check_links.mjs pass
+        # front end changes. Do NOT also add a check_links.mjs pass
         # over _site/: it would check the same bytes a second time.
         #
         # --check-audit-index adds the index audit on top: a diff of the
diff --git a/WIP.Build.md b/WIP.Build.md
index 8b680fb1..81e76424 100644
--- a/WIP.Build.md
+++ b/WIP.Build.md
@@ -158,17 +158,17 @@ A failing check never aborts the build: a broken link still produces a site you
 
 The remote-asset rule fails the run on any `<img src>` resolving off-box (`http://`, `https://`, or protocol-relative `//host`). In the build it is unconditional -- `checkRemoteAssets: true` on both trees in `builder/check.mjs`'s `TREES` -- and is *not* reachable by a flag: `tbdocs` rejects `--check-remote-assets` as an unknown argument. That name belongs to the standalone `scripts/check_links.mjs`, where it is opt-in. The PDF pass over `book.html` is informational, so enforcement comes from the `_site/` pass -- every page in the book is also in `_site/`, making it a superset. The check is deliberately scoped to `<img>` only; `<iframe>` is untouched.
 
-### The two link checkers, and the gate that catches divergence
+### The link check's two front ends, and the gate that catches divergence
 
-[scripts/check_links.mjs](scripts/check_links.mjs) is still the tool for a tree the build did not produce -- a release zip, a bisect, someone else's artifact -- and both CI workflows still run it, though not directly: they invoke `check_links_diff.mjs`, which calls the script in-process as its `script` side (only the `fused` side spawns, and it spawns `tbdocs`). It is exercised only against the fixtures, never against the real trees. The pure core both front ends share lives in [builder/link-check.mjs](builder/link-check.mjs); the build-side plumbing is [builder/check.mjs](builder/check.mjs) and [builder/check-tree.mjs](builder/check-tree.mjs).
+[scripts/check_links.mjs](scripts/check_links.mjs) is still the tool for a tree the build did not produce -- a release zip, a bisect, someone else's artifact -- and both CI workflows still run it, though not directly: they invoke `check_links_diff.mjs`, which calls the script in-process as its `script` side (only the `fused` side spawns, and it spawns `tbdocs`). It is exercised only against the fixtures, never against the real trees. Both front ends run the check in [builder/check.mjs](builder/check.mjs), over the pure core in [builder/link-check.mjs](builder/link-check.mjs); the script keeps only its command line, its walk and reads of the tree, and its report's summary lines. [builder/check-tree.mjs](builder/check-tree.mjs) is the build's alone.
 
-Two implementations of one check is exactly the shape that rots quietly: **a checker that silently checks less reports a clean pass.** [scripts/check_links_diff.mjs](scripts/check_links_diff.mjs) is the gate against that, and it plays the same role on this side that `check_a11y_fingerprint.mjs` plays on the axe side. Run it whenever `link-check.mjs`, `check.mjs` or `check_links.mjs` changes:
+The two still read the tree differently -- the build from memory, through an index of what it wrote and in chunks across its workers -- and **a checker that silently checks less reports a clean pass.** [scripts/check_links_diff.mjs](scripts/check_links_diff.mjs) is the gate against that, and it plays the same role on this side that `check_a11y_fingerprint.mjs` plays on the axe side. Run it whenever `link-check.mjs`, `check.mjs` or `check_links.mjs` changes:
 
 ```sh
 node scripts/check_links_diff.mjs --a script --b fused
 ```
 
-It diffs the two implementations' findings category by category across the real invocations -- `_site/` with sitemap + search + canonical, `_site-offline/` with the forbidden-prefix rule, `book.html` with the same rule (there it collects the links that leave the book for the website, reported as `OUT OF BOOK`), and a `--baseurl` tree checked with the matching base path. It is deliberately *not* in `check.bat`: the script side costs ~3 s, which is the whole saving.
+It diffs the two front ends' findings category by category across the real invocations -- `_site/` with sitemap + search + canonical, `_site-offline/` with the forbidden-prefix rule, `book.html` with the same rule (there it collects the links that leave the book for the website, reported as `OUT OF BOOK`), and a `--baseurl` tree checked with the matching base path. It is deliberately *not* in `check.bat`: the script side costs ~3 s, which is the whole saving.
 
 Two further modes matter:
 
@@ -475,7 +475,7 @@ comment in [builder/page-baseline.mjs](builder/page-baseline.mjs):
   `test/fixtures/check-src`, three pages, to compare the two link checkers.
   Against an unkeyed baseline that build reports **905 pages missing** --- a
   loud, confident, entirely wrong finding, on the one harness whose whole job is
-  noticing when two implementations disagree. `GUARDED_SRC` names the tree the
+  noticing when two front ends disagree. `GUARDED_SRC` names the tree the
   numbers are of and every other root is skipped in silence.
 - **The build now writes a tracked file, and `check_tree_fresh.mjs` watches
   `builder/`.** The write happens after the tree, so without an exclusion the
diff --git a/builder/PLAN-TOOLING-REVIEW.md b/builder/PLAN-TOOLING-REVIEW.md
index ed9be015..1d3643ac 100644
--- a/builder/PLAN-TOOLING-REVIEW.md
+++ b/builder/PLAN-TOOLING-REVIEW.md
@@ -1156,6 +1156,48 @@ memory, through one implementation.
 `--self-test` passes. `check_links.mjs` prints the same report on `docs/_site` and
 `docs/_site-offline` before and after. CI's fixture cases unchanged.
 
+**Landed.** `runCheck` walks the tree as before, then hands every page to `checkChunk` as one
+chunk, each page's `html` a getter that reads the file, so one page is in memory at a time
+and the chunk's unique count, fragment-target count and stage timings are the tree's. It
+passes the oracle on `env` (`FsOracle`, or `treeIndexFor` over its own listing for `--oracle
+index`), then `joinChunks` with the tree's rel paths, the sniffed stubs, and `sitemap.xml` and
+`search-data.json` read from disk, and returns `findingsFor`'s view with `counts.unique` filled
+in from the chunk. `buildFindings`, the three `*Contents` wrappers, `extractLinksAndIds`,
+`relFilesFor` and `statSafe` (inlined as a `try` in `collectHtmlFiles`) go. `check.mjs` pages
+are tree-relative; a `walkPath` map turns them back into the walk's paths for the report, so
+the report is unchanged. The owner chose that report over `formatReport` (Where the plan was
+wrong). `checkChunk` now also returns `stubs` (always empty in the build, whose `TREES` never
+set `captureRedirectStub`), `fragmentTargets` and `stages` (with `extract`), for `-v`. The
+self-test's guards 1 and 3 now run `runCheck` over its one-page tree, four passes, ~20 ms
+instead of <10 ms. Both comments the entry names are rewritten, and so is every sentence that
+called the pair two implementations or the script the reference implementation: Tools.md,
+Building.md, Extending.md, Builder.md, Pipeline-Stages.md (also `checkChunk`'s and
+`findingsFor`'s rows), WIP.Build.md (a heading, which nothing links to), test/README.md,
+builder/README.md, `link-check.mjs`'s banner and reporter comment, `check_links_diff.mjs`'s
+header and `script` side, `page-baseline.mjs`, a `checks.yml` comment (no step changes), and
+`check_gate_lists.mjs`'s note on `checks?`, whose example phrase is gone from the corpus.
+
+Oracle: the kit's `c42-oracle.mjs` runs `runCheck` in 25 cases (the three real trees, an
+absolute root, `-v`, the book with and without `--no-fail`, the base-path tree right and
+wrong, `check_links_diff`'s hand-written fixture cut from its source in five flag sets, the
+two built fixture trees, a subfolder, two inputs, no `--root-dir`, a missing input, only a
+missing input, a root without `sitemap.xml`, unknown flags and the three usage errors), each
+with the default, `fs` and `index` oracles, plus four CLI runs (`-h`, no arguments, three
+passes over `/sep/`, one pass), with timings masked. Against HEAD everything is identical,
+the self-test included, but two things: the findings gain `findingsFor`'s `skipped`, which
+`check_links_diff` does not compare; and where cross-file issues are printed (the wrong base
+path and the root without a sitemap, 13 canonical lines each) they now come sorted by code
+unit, as `joinChunks` sorts them, rather than in the walk's order (`tB/Core/LSet.html` now
+before `LeftShift.html`); line order only, no line gained or lost. `check_links_diff.mjs --a
+script --b fused`: no differences across 6 cases; `--a script --b index`: none across 8, both
+`online-abs` identities ok; `--self-test` ok, and with `basePath: ""` passed to `joinChunks`
+it fails on guard 1 (`--check-sitemap with --base-path`). Timing on `docs/_site` with `-v`,
+HEAD against now: 3.81 s against 3.38 (`fs`), 3.49 against 3.27 (`index`). `compare_trees`:
+the trees match. Two cases change and are not covered: an input on another drive than
+`--root-dir` on Windows, where a page's tree-relative path is absolute, so `checkChunk`
+resolves its links from a folder that does not exist; and a tree whose every canonical-bearing
+page is a redirect stub, where `--check-canonical` now warns instead of reporting `[]`.
+
 ### C43 — `scripts: lib/gate-probes.mjs for the gates' probes and crash handler`
 
 **A6-1 / L1-11 / L4-13 (R1).** A probe accumulator and report loop in
@@ -2003,6 +2045,11 @@ text, gains a Landed note, and the correction is listed here, as in the last rev
   Retrying the wait only makes it longer, which is what `afterReveal`'s `timeout` is for, and
   opening the file again would start a new reveal, so each call throws at the first timeout,
   the review's other option ("retry or fail loudly"); see C24's Landed note.
+- **C42 (A4-2): the script does not call `formatReport`.** The entry names it among the
+  functions the script calls, and also asks for the same report before and after; the two
+  cannot both hold, since `formatReport` prints the build's format. The owner chose the
+  unchanged report: the script prints its own summary lines around the two `link-check.mjs`
+  reporters it already shared, and `formatReport` stays the build's; see C42's Landed note.
 
 ## Found while implementing
 
diff --git a/builder/README.md b/builder/README.md
index 4ec00cd4..4ae8a07f 100644
--- a/builder/README.md
+++ b/builder/README.md
@@ -162,10 +162,11 @@ so a new one belongs inside `applyPreRenderRewrites`, between
 [Tools and Scripts](https://docs.twinbasic.com/Documentation/Development/Tools)
 lists every gate in both wrappers, in running order.
 
-The pure core lives in [link-check.mjs](link-check.mjs); the build-side
-plumbing is [check.mjs](check.mjs) and [check-tree.mjs](check-tree.mjs).
-[scripts/check_links.mjs](../scripts/check_links.mjs) is the same check
-as a standalone tool, for trees this build did not produce. Neither CI
+The pure core lives in [link-check.mjs](link-check.mjs), and the check
+over it in [check.mjs](check.mjs); [check-tree.mjs](check-tree.mjs) is
+the build-side index. [scripts/check_links.mjs](../scripts/check_links.mjs)
+runs the same check as a standalone tool, for trees this build did not
+produce. Neither CI
 workflow invokes it directly any more -- both reach it through
 `check_links_diff.mjs`, which runs it in-process against the fixtures.
 [scripts/check_links_diff.mjs](../scripts/check_links_diff.mjs) is the
diff --git a/builder/check.mjs b/builder/check.mjs
index 14a5b5d4..ffc75e88 100644
--- a/builder/check.mjs
+++ b/builder/check.mjs
@@ -1,22 +1,29 @@
-// The link check, folded into the build.
+// The link check, over pages already rendered.
 //
-// `tbdocs --src docs --check` reaches the same conclusions
-// scripts/check_links.mjs does, against the HTML the build already has
-// in worker memory rather than against ~270 MB read back off disk. The
-// two front ends share builder/link-check.mjs; this module is only the
-// build-side plumbing:
+// It has two front ends. `tbdocs --src docs --check` runs it on the HTML
+// the build already has in worker memory, rather than on ~270 MB read
+// back off disk. scripts/check_links.mjs runs the same functions over a
+// tree it reads from disk, for a tree the build did not produce. Both
+// sit on builder/link-check.mjs, the pure core:
 //
 //   deriveTreeRels()  what each output tree receives, from the build's
-//                     own records rather than a directory walk.
-//   checkChunk()      runs on a worker, inside flush(), on HTML that is
-//                     already decoded and in the lane's memory.
-//   joinChunks()      merges the chunks on main, settles the fragment
-//                     references no single chunk could decide, and runs
-//                     the three cross-file checks.
-//   formatReport()    the human-readable report and the exit code.
+//                     own records rather than a directory walk. Build
+//                     only.
+//   checkChunk()      checks a chunk of pages against one tree. The
+//                     build runs it on a worker, inside flush(), on HTML
+//                     already decoded in the lane's memory; the script
+//                     runs it once, over the whole tree.
+//   joinChunks()      merges the chunks, settles the fragment references
+//                     no single chunk could decide, and runs the three
+//                     cross-file checks.
+//   formatReport()    the build's human-readable report and exit code.
+//                     The script prints its own summary lines around the
+//                     same two link-check.mjs reporters.
+//   findingsFor()     the conclusions as sorted strings, which
+//                     scripts/check_links_diff.mjs compares.
 //
-// Two properties make replacing the filesystem with an index sound
-// rather than merely faster:
+// In the build, two properties make replacing the filesystem with an
+// index sound rather than merely faster:
 //
 //   1. prepareDestinations() wipes _site/, _site-offline/ and _site-pdf/
 //      before the build writes a byte, so nothing survives from a
@@ -31,6 +38,7 @@
 // are collected and reported; only the exit code changes.
 
 import * as path from "node:path";
+import { performance } from "node:perf_hooks";
 
 import {
   extractFromHtml, resolveOccurrences, settleFragments,
@@ -133,7 +141,9 @@ export function checkChunk(docs, env) {
   const integrity = [];
   const canonicals = [];
   const forbidden = [];
+  const stubs = [];
 
+  const t0 = performance.now();
   for (const doc of docs) {
     const abs = path.join(root, doc.destPath);
     const r = extractFromHtml(doc.html, tree.includeFragments, tree.forbid, tree.checkOpts);
@@ -155,7 +165,9 @@ export function checkChunk(docs, env) {
       }]);
     }
     if (r.canonicalHref) canonicals.push([doc.destPath, r.canonicalHref]);
+    if (r.isRedirectStub) stubs.push(doc.destPath);
   }
+  const extract = performance.now() - t0;
 
   const res = resolveOccurrences(occurrences, env.oracle, {
     rootStr: root, basePath,
@@ -184,6 +196,13 @@ export function checkChunk(docs, env) {
     forbidden,
     pending:     res.pendingFragments,
     ids, integrity, canonicals,
+    // Only the standalone script uses these three. The build knows its
+    // own stubs (captureRedirectStub is off in every TREES entry, so
+    // `stubs` stays empty), and the script checks a whole tree as one
+    // chunk, so its -v figures are the tree's.
+    stubs,
+    fragmentTargets: res.fragmentTargets.size,
+    stages: { extract, ...res.stages },
   };
 }
 
@@ -407,14 +426,16 @@ function prefixPaths(text, label) {
 
 // ── Structured findings ─────────────────────────────────────────────
 
-// The same conclusions, in the shape scripts/check_links.mjs's
-// `structured` mode emits, so scripts/check_links_diff.mjs can diff the
-// two implementations category by category. This is the whole gate:
-// check.bat going green proves nothing about whether the fused pass
-// still looks at everything the standalone script does.
+// The same conclusions as sorted arrays of tree-relative strings, one
+// category per check. Both front ends produce them here -- the script
+// in its `structured` mode -- so scripts/check_links_diff.mjs compares
+// one implementation reading a tree two ways: from disk, and held in
+// the build's memory through its index and its chunks. That comparison
+// is the only thing that says the build's pass still looks at every
+// page and link a read from disk finds; check.bat going green does not.
 //
-// `unique` is deliberately null. The script's "N unique" counts entries
-// deduped across the whole tree; the build resolves in 160 chunks and
+// `unique` is null here. The script checks its tree as one chunk and
+// fills in that chunk's own count; the build resolves in 160 chunks and
 // reconstructing a global figure would mean shipping every unique
 // target key back from every chunk -- hundreds of thousands of strings
 // for a number that appears in a summary line and is not a finding.
diff --git a/builder/link-check.mjs b/builder/link-check.mjs
index feae9e58..be448003 100644
--- a/builder/link-check.mjs
+++ b/builder/link-check.mjs
@@ -3,7 +3,7 @@
 // existence oracle -- nothing reads the filesystem, nothing walks a
 // directory, nothing knows where the HTML came from.
 //
-// Two front ends share it:
+// Two front ends share it, both through builder/check.mjs:
 //
 //   scripts/check_links.mjs   reads HTML off disk and stats the disk.
 //                             Works against any tree, including one this
@@ -948,9 +948,9 @@ export function formatLinkReport(broken, forbiddenBySource, { tag = "FORBIDDEN",
   return lines.join("\n") + "\n";
 }
 
-// The findings strings both front ends diff are deliberately terse --
-// see buildFindings / findingsFor. The report adds the part a reader
-// needs to know what to do about it.
+// The findings strings check_links_diff.mjs compares are deliberately
+// terse -- see findingsFor in check.mjs. The report adds the part a
+// reader needs to know what to do about it.
 const HTML_ERROR_HINT = {
   "unclosed-tag":
     "the document never closed it",
diff --git a/builder/page-baseline.mjs b/builder/page-baseline.mjs
index cbccd477..5fea481f 100644
--- a/builder/page-baseline.mjs
+++ b/builder/page-baseline.mjs
@@ -47,10 +47,10 @@
 //
 // **The baseline describes one source tree, and the guard says which.** tbdocs
 // is not only run over `docs/`: scripts/check_links_diff.mjs spawns it over
-// test/fixtures/check-src, three pages, to compare the two link checkers. A
-// baseline keyed to nothing would meet that build with "905 pages missing" --
-// a loud, confident, entirely wrong finding, on a harness whose whole job is to
-// notice when two implementations disagree. So GUARDED_SRC names the tree these
+// test/fixtures/check-src, three pages, to compare the link check's two front
+// ends. A baseline keyed to nothing would meet that build with "905 pages
+// missing" -- a loud, confident, entirely wrong finding, on a harness whose
+// whole job is to notice when two front ends disagree. So GUARDED_SRC names the tree these
 // numbers are of, the file records it, and every other source root is skipped
 // in silence rather than measured against figures that were never about it.
 
diff --git a/docs/Documentation/Builder.md b/docs/Documentation/Builder.md
index f840fa61..534b45a4 100644
--- a/docs/Documentation/Builder.md
+++ b/docs/Documentation/Builder.md
@@ -118,7 +118,7 @@ Modules grouped by role. Each entry has one line; deep-dive in [Pipeline Stages]
 | File | Role |
 |---|---|
 | [`link-check.mjs`](https://github.com/twinbasic/documentation/blob/main/builder/link-check.mjs) | The pure core: HTML in, findings out. No filesystem traversal and no CLI, which is what lets the build's fused check and the standalone [`scripts/check_links.mjs`](Tools#check-links) share one implementation. |
-| [`check.mjs`](https://github.com/twinbasic/documentation/blob/main/builder/check.mjs) | Build-side plumbing: the `TREES` table, per-chunk `checkChunk`, the `joinChunks` merge, report formatting, and the `--check-audit-index` tree-index audit. |
+| [`check.mjs`](https://github.com/twinbasic/documentation/blob/main/builder/check.mjs) | The check over rendered pages, which `scripts/check_links.mjs` runs too: per-chunk `checkChunk`, the `joinChunks` merge and `findingsFor`. Also the build's `TREES` table, report formatting, and the `--check-audit-index` tree-index audit. |
 | [`check-tree.mjs`](https://github.com/twinbasic/documentation/blob/main/builder/check-tree.mjs) | `deriveTreeRels` --- every relative path the build believes it emitted into a tree. The check's existence oracle is built from this rather than from a `readdir`, which is why the audit exists to keep it honest. |
 | [`counts.mjs`](https://github.com/twinbasic/documentation/blob/main/builder/counts.mjs) | The registry behind `{{tbdocs:<name>}}` in prose. `deriveCounts(state)` computes every name from build state; `countPlugin` substitutes them as a core rule over the inline token stream, which is what makes code immune without a rule for it. `validateCountNames` rejects an unknown name on main before any worker renders, and `findSurvivingPlaceholder` rejects one that reached the output --- two checks because they fail differently. See [Authoring Pages](Authoring#counts). |
 | [`page-baseline.mjs`](https://github.com/twinbasic/documentation/blob/main/builder/page-baseline.mjs) | The page-count drift guard, and the committed `page-baseline.json` it compares against. A rise rewrites the file, a fall fails the build, and neither CI nor `--serve` may write. See [Building and Deployment](Building#the-page-count-drift-guard). |
diff --git a/docs/Documentation/Building.md b/docs/Documentation/Building.md
index 8ae2bad8..525bc10b 100644
--- a/docs/Documentation/Building.md
+++ b/docs/Documentation/Building.md
@@ -569,7 +569,7 @@ The deploy workflow passes `--url` and `--baseurl` from the `configure-pages` ou
 
 ### The link-checker parity fixtures
 
-[`scripts/check_links_diff.mjs`](Tools#check-links-diff) compares two implementations of one check: the standalone [`scripts/check_links.mjs`](Tools#check-links), still the tool for a tree this build did not produce, and the pass fused into the build. Two implementations of one check is the shape that rots quietly, because **a checker that silently checks less reports a clean pass.** `check.bat` runs neither invocation; CI runs one or both.
+[`scripts/check_links_diff.mjs`](Tools#check-links-diff) compares the check's two front ends: the standalone [`scripts/check_links.mjs`](Tools#check-links), still the tool for a tree this build did not produce, and the pass fused into the build. They run the same functions and differ only in how they read the tree, which is still enough to hide a fault, because **a checker that silently checks less reports a clean pass.** `check.bat` runs neither invocation; CI runs one or both.
 
 | Invocation | Where | What it holds to the comparison |
 |---|---|---|
diff --git a/docs/Documentation/Extending.md b/docs/Documentation/Extending.md
index dbeeec34..980b78d4 100644
--- a/docs/Documentation/Extending.md
+++ b/docs/Documentation/Extending.md
@@ -158,7 +158,7 @@ Two things are easy to miss from a changer's position.
 ## Changing the link checker
 {: #changing-the-link-checker }
 
-The link check exists twice. The build runs it over the HTML it holds in memory, through `builder/check.mjs`, and `scripts/check_links.mjs` runs it over a tree on disk; both use the core in `builder/link-check.mjs`. A change to any of the three can make the two disagree, and **a checker that silently checks less reports a clean pass** --- on a healthy site nearly every category of finding is empty, so nothing else would notice.
+The link check has two front ends. The build runs it over the HTML it holds in memory, and `scripts/check_links.mjs` runs it over a tree on disk; both call the same functions in `builder/check.mjs`, over the core in `builder/link-check.mjs`. A change to any of the three can make the two disagree, and **a checker that silently checks less reports a clean pass** --- on a healthy site nearly every category of finding is empty, so nothing else would notice.
 
 After changing `builder/link-check.mjs`, `builder/check.mjs` or `scripts/check_links.mjs`, run the full comparison by hand:
 
@@ -168,7 +168,7 @@ It builds everything it compares --- the site into the usual trees, a copy under
 
 **Nothing else runs this comparison.** `build.bat`, `check.bat` and `test.bat` never call it, and the CI workflows run only the fixture cases: both compare the script with its `index` variant over a synthetic tree, and the pull-request workflow also compares the script with the build's pass over the three-page fixture. Neither goes near the real site, so a green pull request says only that the two sides agree over the fixtures, not over the pages you will publish. A change meant to alter what the checker finds also moves the counts asserted after every fixture run, `FIXTURE_EXPECTED`, `FIXTURE_BUILT_ONLINE` and `FIXTURE_BUILT_OFFLINE` in `check_links_diff.mjs`; [`test/README.md`](https://github.com/twinbasic/documentation/blob/main/test/README.md) says what each fixture page is there to provoke.
 
-If you changed the harness itself, or `check_links.mjs`, which is the harness's reference implementation, also run:
+If you changed the harness itself, or `check_links.mjs`, which is the harness's `script` side, also run:
 
     node scripts/check_links_diff.mjs --self-test
 
diff --git a/docs/Documentation/Pipeline-Stages.md b/docs/Documentation/Pipeline-Stages.md
index 0ed8a8a2..4858e514 100644
--- a/docs/Documentation/Pipeline-Stages.md
+++ b/docs/Documentation/Pipeline-Stages.md
@@ -512,17 +512,17 @@ The same modules as above, with the full export list per file.
 
 ### `check.mjs`
 
-The build-side plumbing for the link and integrity check. Imported dynamically --- on the workers by `renderEnvInit`, on main by `linkJoin` / `checkBook` / `checkReport` --- because `htmlparser2` costs ~23 ms to import and a build without `--check` must not pay it on sixteen lanes.
+The link and integrity check over rendered pages, which the standalone [`scripts/check_links.mjs`](Tools#check-links) also runs, over a tree it reads from disk. The build imports it dynamically --- on the workers by `renderEnvInit`, on main by `linkJoin` / `checkBook` / `checkReport` --- because `htmlparser2` costs ~23 ms to import and a build without `--check` must not pay it on sixteen lanes.
 
 | Symbol | Signature | Description |
 |---|---|---|
 | `TREES` | `object` | Per-tree configuration: `suffix`, `label`, the `checkOpts` that tree enables, and its `forbid` prefixes. `online` and `offline` both set `checkRemoteAssets: true` unconditionally --- there is no flag to turn it off. |
 | `FALLBACK_EXTS` | `string[]` | Extensions appended when a target does not exist as-is (`["html"]`, mirroring Pages' extensionless URLs). |
 | `INDEX_FILES` | `string[]` | Filenames tried when a URL resolves to a directory. |
-| `checkChunk` | `(docs, env) → chunkResult` | Checks one chunk of `{ destPath, html }` against one tree. The unit of work that rides along inside `flush:i`. |
+| `checkChunk` | `(docs, env) → chunkResult` | Checks one chunk of `{ destPath, html }` against one tree. The unit of work that rides along inside `flush:i`; `check_links.mjs` runs it once, over a whole tree. |
 | `joinChunks` | `(chunks, opts) → treeResult` | Merges per-chunk results into one per-tree result, settling cross-chunk fragment references. |
 | `formatReport` | `(r) → { text, linksFailed, integrityFailed }` | Human-readable report plus the two booleans `checkReport` turns into an exit code. |
-| `findingsFor` | `(r) → object` | The machine-readable view, written by `--check-findings`. |
+| `findingsFor` | `(r) → object` | The machine-readable view, written by `--check-findings` and returned by `check_links.mjs`'s structured mode for `check_links_diff.mjs`. |
 | `treeIndexFor` | `(root, rels) → treeIndex` | Builds the existence oracle a tree is checked against, from the build's own records rather than a `readdir`. |
 | `auditIndex` | `(root, rels) → Promise<{ missing, spurious }>` | Diffs that derived index against what actually landed on disk. `--check-audit-index` only. |
 | `deriveTreeRels` | re-exported from `check-tree.mjs` | --- |
@@ -537,7 +537,7 @@ The build-side plumbing for the link and integrity check. Imported dynamically -
 
 ### `link-check.mjs`
 
-The pure core shared by the build's fused check and the standalone [`scripts/check_links.mjs`](Tools#check-links). No filesystem traversal and no CLI --- it takes HTML and an oracle and returns findings, which is what lets one implementation serve both front ends. **Two implementations of one check is the shape that rots quietly, so run [`check_links_diff.mjs`](Tools#check-links-diff) whenever this file, `check.mjs` or `check_links.mjs` changes.**
+The pure core shared by the build's fused check and the standalone [`scripts/check_links.mjs`](Tools#check-links). No filesystem traversal and no CLI --- it takes HTML and an oracle and returns findings, which is what lets one implementation serve both front ends. **The two front ends read the tree differently, and a checker that silently checks less reports a clean pass, so run [`check_links_diff.mjs`](Tools#check-links-diff) whenever this file, `check.mjs` or `check_links.mjs` changes.**
 
 | Symbol | Signature | Description |
 |---|---|---|
diff --git a/docs/Documentation/Tools.md b/docs/Documentation/Tools.md
index 059ceda0..0cd448fe 100644
--- a/docs/Documentation/Tools.md
+++ b/docs/Documentation/Tools.md
@@ -314,13 +314,13 @@ which is the path `--check` names for you. Two things follow from that second ed
     node scripts/check_links_diff.mjs --list
     node scripts/check_links_diff.mjs --self-test
 
-Differential harness for the link checker. There are two implementations of one check --- the standalone [`scripts/check_links.mjs`](#check-links) and the build's own `--check` pass --- and two implementations of one check is the shape that rots quietly, because **a checker that silently checks less reports a clean pass**. This runs both over the same bytes and diffs their findings category by category, across the nine finding categories plus the per-run counts. Exits 0 when the two sides agree, 1 on a difference, 2 on a harness error.
+Differential harness for the link checker. The check has two front ends --- the standalone [`scripts/check_links.mjs`](#check-links), which reads a tree from disk, and the build's own `--check` pass, which checks the pages it holds in memory against an index of what it wrote, in chunks across its workers. Both run the same functions in `builder/check.mjs` and differ only in how they read the tree, which is still enough to hide a fault, because **a checker that silently checks less reports a clean pass**. This runs both over the same bytes and diffs their findings category by category, across the nine finding categories plus the per-run counts. Exits 0 when the two sides agree, 1 on a difference, 2 on a harness error.
 
 Two registries decide what a run actually does, and `--list` prints both. **Sides** are the implementations being compared, named by `--a` and `--b`:
 
 | Side | What it is |
 |---|---|
-| `script` | `check_links.mjs` pinned to `--oracle fs`, run in-process. The reference implementation --- though not an oracle of record: on Windows its filesystem oracle answers "exists" for a wrong-case path that 404s on GitHub Pages, and on that one question `index` is the correct side. |
+| `script` | `check_links.mjs` pinned to `--oracle fs`, run in-process. The reference side --- though not an oracle of record: on Windows its filesystem oracle answers "exists" for a wrong-case path that 404s on GitHub Pages, and on that one question `index` is the correct side. |
 | `index` | The same script over the same walk, with existence answered from a Set built off one directory listing rather than a stat per candidate. Proves the oracle's lookup semantics. |
 | `fused` | `tbdocs --check`, the build's own pass. The side the whole harness exists for: the one that could quietly check less, with nothing else on a clean site to say so. |
 | `mutant` | `script`, corrupted on purpose. Reachable only through `--self-test`. |
@@ -347,9 +347,9 @@ Both CI workflows run the harness, and neither runs it over the real site. `chec
     node scripts/check_links_diff.mjs --case fixture --a script --b index
     node scripts/check_links_diff.mjs --case fixture-built --case fixture-built-offline --a script --b fused
 
-`tbdocs-gh-pages.yml` (deploy) keeps only the first: ~0.3 s over a synthetic tree, enough that the reference implementation cannot rot unnoticed, while the extra three-page build stays on the PR gate. What is in neither, and deliberately not in `check.bat` either, is the full `--a script --b fused` over the real trees --- it builds the site itself so both sides read the same bytes, and the script side then costs a few seconds, which is the entire saving of having folded the check into the build. Run that one by hand after touching `builder/link-check.mjs`, `builder/check.mjs` or `scripts/check_links.mjs`.
+`tbdocs-gh-pages.yml` (deploy) keeps only the first: ~0.3 s over a synthetic tree, enough that the script side cannot rot unnoticed, while the extra three-page build stays on the PR gate. What is in neither, and deliberately not in `check.bat` either, is the full `--a script --b fused` over the real trees --- it builds the site itself so both sides read the same bytes, and the script side then costs a few seconds, which is the entire saving of having folded the check into the build. Run that one by hand after touching `builder/link-check.mjs`, `builder/check.mjs` or `scripts/check_links.mjs`.
 
-`--self-test` is the guard on the guard. It runs `check_links.mjs`'s own regression guards --- since `b97c75f` nothing else does --- and then diffs the reference implementation against a deliberately corrupted copy, failing unless the difference is reported. Everything else the harness prints reduces to *the two sides agreed*, which is also what a harness comparing nothing says.
+`--self-test` is the guard on the guard. It runs `check_links.mjs`'s own regression guards --- nothing else does --- and then diffs the `script` side against a deliberately corrupted copy, failing unless the difference is reported. Everything else the harness prints reduces to *the two sides agreed*, which is also what a harness comparing nothing says.
 
 The fixtures have their own document, and it is the one to read before editing them: [`test/README.md`](https://github.com/twinbasic/documentation/blob/main/test/README.md) covers what each page under `check-src/` is there to provoke, and the hard-coded per-category counts (`FIXTURE_EXPECTED`, `FIXTURE_BUILT_ONLINE`, `FIXTURE_BUILT_OFFLINE`) that are asserted after every run, so a fixture that stops provoking a category fails loudly instead of quietly returning to empty-against-empty. It also covers the hazard that catches people out: **the fixture is built by the real `tbdocs`, so a template change can turn this gate red without anyone touching the fixture or the checker.** Adding the self-hosted fonts put two `<link rel="preload">` tags on every page, `check-src/` had no `assets/fonts/`, and its `broken` count went from 3 to 9. The fix for that shape of failure is to add the stub asset the template now expects --- never to raise the expected count, which dilutes a category the fixture exists to hold at an exact number.
 
diff --git a/scripts/check_gate_lists.mjs b/scripts/check_gate_lists.mjs
index 18427feb..a69696a1 100644
--- a/scripts/check_gate_lists.mjs
+++ b/scripts/check_gate_lists.mjs
@@ -195,8 +195,9 @@ function statedCount(body) {
 
 const NUM = `(?:${NUMBER_WORDS.join("|")}|\\d+)`;
 const WRAP = "`?(check|test)\\.bat`?";
-// Deliberately not `checks?`: "two implementations of one check" is ordinary
-// English about the link checker and appears twice in the corpus.
+// Deliberately not `checks?`: a count of checks is ordinary English in the
+// corpus ("Two checks enforce the registration", "two more checks"), not a
+// count of gates.
 const NOUN = "(?:gates?|steps?|scripts?)";
 const QUAL = "(?:more|further|other|separate|cheaper|local|remaining)\\s+";
 // "`test.bat` is six more" names no noun at all, and that sentence is one of
diff --git a/scripts/check_links.mjs b/scripts/check_links.mjs
index d204cd4d..9bac3aba 100644
--- a/scripts/check_links.mjs
+++ b/scripts/check_links.mjs
@@ -5,13 +5,15 @@
 // already hold, rather than writing ~270 MB out and reading it back.
 // This script is the same check as a standalone tool, for a tree the
 // build did not produce: a release zip, a bisect, someone else's
-// artifact. Both CI workflows still run it, though not directly: they
-// invoke check_links_diff.mjs, which spawns this script as its `script`
-// side, and only against the fixtures.
-//
-// The two front ends share builder/link-check.mjs, and
-// scripts/check_links_diff.mjs is the gate that says they agree --
-// run it whenever either side changes. See builder/PLAN-checks.md.
+// artifact. It keeps its own command line, its own walk of the tree and
+// its own reading of each page, and hands the pages to the functions
+// the build's pass runs, builder/check.mjs's checkChunk and joinChunks,
+// as one chunk. Both CI workflows still run it, though not directly:
+// check_links_diff.mjs runs it in-process as its `script` side, only
+// against the fixtures, and compares its findings with the build's. The
+// two differ only in how they read the tree, so run that comparison
+// whenever builder/check.mjs, builder/link-check.mjs or this script
+// changes. See builder/PLAN-checks.md.
 //
 // Typical invocation (single pass):
 //
@@ -63,94 +65,39 @@ import { performance } from "node:perf_hooks";
 import { fileURLToPath } from "node:url";
 import { isMainThread, parentPort, workerData, Worker } from "node:worker_threads";
 
-// The pure core -- extraction, resolution, the cross-file checks and
-// the reporters -- lives in builder/. This script is one front end over
-// it; the build's --check pass is the other. See builder/link-check.mjs
-// for why the dependency runs this way round.
+// The check is builder/check.mjs's, the one the build's --check pass
+// runs, over the pure core in builder/link-check.mjs. This script adds
+// only what a tree on disk needs: the walk, the reads, the choice of
+// oracle, and its report's summary lines. See builder/link-check.mjs for
+// why the dependency runs this way round.
+import {
+  checkChunk, joinChunks, findingsFor, normalizeBasePath, treeIndexFor,
+} from "../builder/check.mjs";
 import {
-  extractFromHtml, resolveOccurrences, FsOracle,
-  IndexOracle, buildTreeIndex,
-  checkSitemap, checkSearch, checkCanonical,
-  formatLinkReport, formatIntegrityReport,
-  normalizeBasePath, resolve, OUTSIDE_BASEPATH_MARKER,
+  FsOracle, formatLinkReport, formatIntegrityReport,
+  resolve, OUTSIDE_BASEPATH_MARKER,
 } from "../builder/link-check.mjs";
 
-// Tree-relative POSIX path. The core's cross-file checks work in this
-// coordinate space, and so does the structured-findings view (see
-// runCheck's `structured` option): the human-readable report keeps
-// printing whatever shape the caller passed in, but findings need a
-// stable space so the same tree checked with a relative --root-dir, an
-// absolute one, or from inside the build compares equal.
+// Tree-relative POSIX path, the space check.mjs works and reports in, so
+// the same tree checked with a relative --root-dir, an absolute one, or
+// from inside the build gives equal findings.
 function relToRoot(rootStr, p) {
   const rootAbs = path.resolve(rootStr || ".");
   return path.relative(rootAbs, path.resolve(p)).replace(/\\/g, "/");
 }
 
-// Walk paths -> tree-relative POSIX paths, redirect stubs dropped.
-function relFilesFor(rootStr, htmlFiles, redirectStubSet) {
-  const rootAbs = path.resolve(rootStr);
-  const out = [];
-  for (const file of htmlFiles) {
-    if (redirectStubSet && redirectStubSet.has(path.resolve(file))) continue;
-    out.push(path.relative(rootAbs, path.resolve(file)).replace(/\\/g, "/"));
-  }
-  return out;
-}
-
-// Cross-file check: every .html file (except hardcoded exclusions and
-// redirect stubs) should appear in sitemap.xml.
-// Returns an array of issue strings, or null if sitemap.xml is absent.
+// sitemap.xml and search-data.json, which a cross-file check reads when
+// they are there and reports skipped when they are not.
 //
-// One thing this side cannot do, and the fused side can: a page carrying
+// One thing this side cannot do, and the build can: a page carrying
 // `sitemap: false` or `search_exclude: true` is absent from the generated
 // file on purpose, and nothing in the built HTML says so. The build knows
 // because it still has the frontmatter and passes the generators' own
 // opt-out sets to the checker; a tree this build did not produce is just a
 // directory of HTML, so a deliberate omission and a bug look identical
 // here. Both checks are opt-in flags for that reason.
-function checkSitemapContents(rootStr, htmlFiles, redirectStubSet, basePath) {
-  let xml;
-  try { xml = fs.readFileSync(path.join(rootStr, "sitemap.xml"), "utf8"); } catch { return null; }
-  return checkSitemap(xml, relFilesFor(rootStr, htmlFiles, redirectStubSet), basePath);
-}
-
-// Cross-file check: every .html file (except exclusions and redirect
-// stubs) should have at least one entry in search-data.json whose
-// url matches the page's canonical path (ignoring fragment).
-// Returns an array of issue strings, or null if search-data.json is absent.
-function checkSearchContents(rootStr, htmlFiles, redirectStubSet, basePath) {
-  let searchData;
-  try {
-    searchData = JSON.parse(
-      fs.readFileSync(path.join(rootStr, "assets", "js", "search-data.json"), "utf8"));
-  } catch { return null; }
-  return checkSearch(searchData, relFilesFor(rootStr, htmlFiles, redirectStubSet), basePath);
-}
-
-// Thin wrapper over the core's SAX pass: read the file, hand over the
-// string. Everything this used to do lives in builder/link-check.mjs so
-// the build can call it on HTML it already has in memory.
-function extractLinksAndIds(htmlPath, captureIds, forbidPrefixes, checkOpts) {
-  return extractFromHtml(fs.readFileSync(htmlPath, "utf8"), captureIds, forbidPrefixes, checkOpts);
-}
-
-// Cross-file check: every page's <link rel="canonical" href="..."> must
-// match the page's own deployment URL. Returns an array of issue
-// strings, or null if no pages had a canonical href (the input set was
-// empty / canonical-less).
-function checkCanonicalContents(rootStr, canonicalByFile, redirectStubSet, basePath) {
-  if (canonicalByFile.size === 0) return null;
-  const rootAbs = path.resolve(rootStr);
-  const byRel = new Map();
-  for (const [file, canonical] of canonicalByFile) {
-    if (redirectStubSet && redirectStubSet.has(path.resolve(file))) continue;
-    byRel.set(path.relative(rootAbs, path.resolve(file)).replace(/\\/g, "/"), canonical);
-  }
-  return checkCanonical(byRel, basePath);
-}
-
-function statSafe(p) {
-  try { return fs.statSync(p); } catch { return null; }
+function readIfPresent(p) {
+  try { return fs.readFileSync(p, "utf8"); } catch { return null; }
 }
 
 function printHelp() {
@@ -328,7 +275,8 @@ function collectHtmlFiles(inputs) {
   const files = [];
   const warnings = [];
   for (const inp of inputs) {
-    const s = statSafe(inp);
+    let s = null;
+    try { s = fs.statSync(inp); } catch { /* reported below */ }
     if (!s) {
       warnings.push(`warning: input not found: ${inp}\n`);
       continue;
@@ -371,10 +319,10 @@ function collectAllRelFiles(rootStr) {
 // nothing is written to stdout/stderr.  Returns { output, exitCode }.
 //
 // With `structured: true` the result additionally carries a `findings`
-// object -- the same conclusions the report prints, as sorted arrays of
-// tree-relative strings, for machine comparison. It is what
-// scripts/check_links_diff.mjs diffs. Building it costs a few ms and is
-// skipped entirely when not requested, so the CLI path is unchanged.
+// object -- builder/check.mjs's findingsFor, the same conclusions the
+// report prints as sorted arrays of tree-relative strings, which
+// scripts/check_links_diff.mjs compares with the build's. Building it
+// costs a few ms and is skipped entirely when not requested.
 export function runCheck(argv, { structured = false } = {}) {
   const buf = [];
   const write = (s) => buf.push(s);
@@ -406,13 +354,10 @@ export function runCheck(argv, { structured = false } = {}) {
     return { output: buf.join(""), exitCode: 4 };
   }
 
-  // Keep --root-dir in its caller-supplied shape (no path.resolve) so
-  // resolver-built target strings have the same relative-vs-absolute
-  // shape as walk paths -- otherwise the idsByFile lookup below would
-  // miss for absolute-URL hrefs, which produce absolute targets when
-  // root-dir is absolute but relative walk-path entries when not.
-  // check.bat / CI both pass the same string for --root-dir and the
-  // positional input, so the two sides always agree.
+  // --root-dir is used in the shape it was given. checkChunk joins it to
+  // each page's tree-relative path, so the paths it resolves links
+  // against and the paths it looks fragment ids up by are in one shape,
+  // relative or absolute, whatever shape the walk paths are in.
   const rootStr = opts.rootDir ?? "";
   const fallbackExts = opts.fallbackExtensions.split(",").filter(Boolean);
   const indexFiles = opts.indexFiles.split(",").filter(Boolean);
@@ -425,6 +370,9 @@ export function runCheck(argv, { structured = false } = {}) {
 
   // Build checkOpts only when at least one integrity flag is on, to
   // avoid adding handlers to the parser on runs that don't need them.
+  // The cross-file checks leave redirect stubs out, and a tree on disk
+  // does not say which pages the build generated as stubs, so they are
+  // sniffed from their meta refresh.
   const needIntegrity = opts.checkHtml || opts.checkA11y || opts.checkIds || opts.checkRemoteAssets;
   const needRedirectStub = opts.checkSitemap || opts.checkSearch || opts.checkCanonical;
   const checkOpts = (needIntegrity || needRedirectStub || opts.checkCanonical) ? {
@@ -436,86 +384,77 @@ export function runCheck(argv, { structured = false } = {}) {
     captureRedirectStub: needRedirectStub,
   } : null;
 
-  // Per-file: extract once, then group hrefs by (source_dir, href) so we
-  // resolve each unique combination exactly once. The same nav/footer
-  // links repeat across hundreds of pages from the same directory. Also
-  // capture the per-file id/name set if fragment checking is on, so the
-  // later fragment check is a Map lookup instead of a second SAX pass.
-  // idsByFile key matches the walk-path shape and (because rootStr is
-  // kept relative -- see above) the resolver-built target shape too,
-  // so a later `idsByFile.get(entry.resolved)` lands without
-  // canonicalisation.
-  const occurrences = []; // flat [srcPath, srcDir, href, ...] triples
-  const idsByFile = opts.includeFragments ? new Map() : null;
-  const forbidPrefixes = opts.forbid.length ? opts.forbid : null;
-  const forbiddenBySource = forbidPrefixes ? new Map() : null;
-
-  // Per-file integrity results (populated when checkOpts is set).
-  const integrityByFile = needIntegrity ? new Map() : null;
-  const redirectStubSet = needRedirectStub ? new Set() : null;
-  const canonicalByFile = opts.checkCanonical ? new Map() : null;
-
-  for (const src of htmlFiles) {
-    const srcDir = path.dirname(src);
-    const { links, ids, forbidden, htmlErrors, a11yErrors, dupIds, remoteAssets, isRedirectStub, canonicalHref } =
-      extractLinksAndIds(src, opts.includeFragments, forbidPrefixes, checkOpts);
-    for (const h of links) occurrences.push(src, srcDir, h);
-    if (idsByFile) idsByFile.set(src, ids);
-    if (forbidden && forbidden.length) forbiddenBySource.set(src, forbidden);
-    if (integrityByFile && (htmlErrors?.length || a11yErrors?.length || dupIds?.length || remoteAssets?.length)) {
-      integrityByFile.set(src, { htmlErrors, a11yErrors, dupIds, remoteAssets });
-    }
-    if (redirectStubSet && isRedirectStub) {
-      redirectStubSet.add(path.resolve(src));
-    }
-    if (canonicalByFile && canonicalHref) {
-      canonicalByFile.set(src, canonicalHref);
-    }
-  }
-  const tExtract = performance.now();
-
-  // Resolution, existence checks and fragment settling all live in the
-  // core now. idsByFile keys match the walk-path shape and (because
-  // rootStr is kept in its caller-supplied shape -- see above) the
-  // resolver-built target shape too, so the fragment lookup lands
-  // without canonicalisation. The set is complete here, so nothing
-  // defers.
-  const oracle = opts.oracle === "index"
-    ? IndexOracle(buildTreeIndex(rootStr, collectAllRelFiles(rootStr)))
-    : FsOracle();
-
-  const { broken, brokenUniqueCount, uniqueCount, fragmentTargets, stages } =
-    resolveOccurrences(occurrences, oracle, {
-      rootStr, basePath, fallbackExts, indexFiles,
-      includeFragments: opts.includeFragments,
-      localIds: idsByFile,
-    });
-  const filesForFragments = [...fragmentTargets];
+  // This pass's tree, in the shape of check.mjs's TREES entries.
+  const tree = {
+    label: rootStr || ".",
+    checkOpts,
+    forbid: opts.forbid.length ? opts.forbid : null,
+    crossFile: {
+      sitemap: opts.checkSitemap, search: opts.checkSearch, canonical: opts.checkCanonical,
+    },
+    fallbackExts, indexFiles,
+    includeFragments: opts.includeFragments,
+  };
+
+  // checkChunk reads each page's `html` once, in order, so a getter
+  // keeps one page in memory at a time, and the whole tree goes through
+  // as one chunk: the unique count and the -v figures below are then the
+  // tree's, not a slice's. check.mjs reports a page by its tree-relative
+  // path; walkPath maps that back to the path the walk found, which is
+  // what the report prints.
+  const walkPath = new Map();
+  const docs = htmlFiles.map((file) => {
+    const destPath = relToRoot(rootStr, file);
+    walkPath.set(destPath, file);
+    return { destPath, get html() { return fs.readFileSync(file, "utf8"); } };
+  });
+
+  const env = { root: rootStr, basePath, tree };
+  if (opts.oracle === "index") env.index = treeIndexFor(rootStr, collectAllRelFiles(rootStr));
+  else env.oracle = FsOracle();
+
+  const chunk = checkChunk(docs, env);
   const tDone = performance.now();
-  write(formatLinkReport(broken, forbiddenBySource));
+
+  const r = joinChunks([chunk], {
+    root: rootStr, tree, basePath,
+    relFiles: docs.map(d => d.destPath),
+    stubRels: new Set(chunk.stubs),
+    aux: {
+      sitemapXml: opts.checkSitemap
+        ? readIfPresent(path.join(rootStr, "sitemap.xml")) : null,
+      searchJson: opts.checkSearch
+        ? readIfPresent(path.join(rootStr, "assets", "js", "search-data.json")) : null,
+    },
+  });
+
+  const shown = (rel) => walkPath.get(rel) ?? rel;
+  const byWalkPath = (m) => m && new Map([...m].map(([rel, v]) => [shown(rel), v]));
+  const brokenShown = r.broken.slice();
+  for (let i = 0; i < brokenShown.length; i += 3) brokenShown[i] = shown(brokenShown[i]);
+  write(formatLinkReport(brokenShown, byWalkPath(r.forbiddenBySource)));
 
   let forbiddenCount = 0;
-  if (forbiddenBySource) {
-    for (const fhits of forbiddenBySource.values()) forbiddenCount += fhits.length;
+  if (r.forbiddenBySource) {
+    for (const fhits of r.forbiddenBySource.values()) forbiddenCount += fhits.length;
   }
-  const total = occurrences.length / 3;
-  const unique = uniqueCount;
-  const errorsUnique = brokenUniqueCount;
-  const okUnique = unique - errorsUnique;
+  const unique = chunk.uniqueLocal;
+  const okUnique = unique - r.brokenUnique;
   const elapsed = (tDone - t0) / 1000;
-  const forbidNote = forbidPrefixes ? `, ${forbiddenCount} forbidden` : "";
+  const forbidNote = tree.forbid ? `, ${forbiddenCount} forbidden` : "";
   write(
-    `Checked ${total} occurrences (${unique} unique) in ${elapsed.toFixed(3)}s ` +
-    `-- ${okUnique} OK, ${errorsUnique} broken${forbidNote}\n`
+    `Checked ${r.occurrences} occurrences (${unique} unique) in ${elapsed.toFixed(3)}s ` +
+    `-- ${okUnique} OK, ${r.brokenUnique} broken${forbidNote}\n`
   );
 
   if (opts.verbose) {
     const fmt = (ms) => `${(ms / 1000).toFixed(3)}s`;
+    const stages = chunk.stages;
     write("\n");
     write(`  Files scanned:        ${htmlFiles.length}\n`);
-    write(`  Fragment targets:     ${filesForFragments.length}\n`);
+    write(`  Fragment targets:     ${chunk.fragmentTargets}\n`);
     write(`  Walk:        ${fmt(tWalk - t0)}\n`);
-    write(`  Extract:     ${fmt(tExtract - tWalk)}\n`);
+    write(`  Extract:     ${fmt(stages.extract)}\n`);
     write(`  Resolve:     ${fmt(stages.resolve)}\n`);
     write(`  Check paths: ${fmt(stages.checkPaths)}\n`);
     write(`  Fragments:   ${fmt(stages.fragments)}\n`);
@@ -524,38 +463,22 @@ export function runCheck(argv, { structured = false } = {}) {
 
   // ── Integrity check reporting ──────────────────────────────────────
 
-  const integrityReport = formatIntegrityReport(integrityByFile);
+  const integrityReport = formatIntegrityReport(byWalkPath(r.integrityByFile));
   let integrityIssueCount = integrityReport.count;
   write(integrityReport.text);
 
-  // Cross-file sitemap check.
-  let sitemapIssues = null, searchIssues = null, canonicalIssues = null;
-  if (opts.checkSitemap) {
-    const issues = sitemapIssues = checkSitemapContents(rootStr, htmlFiles, redirectStubSet, basePath);
+  // The cross-file checks: each result is null when the check could not
+  // run, and joinChunks has already left the redirect stubs out.
+  const crossFile = [
+    [opts.checkSitemap, r.sitemapIssues, "--check-sitemap: sitemap.xml not found in root-dir"],
+    [opts.checkSearch, r.searchIssues, "--check-search: search-data.json not found in root-dir"],
+    [opts.checkCanonical, r.canonicalIssues,
+      '--check-canonical: no <link rel="canonical"> found in any page'],
+  ];
+  for (const [requested, issues, skipped] of crossFile) {
+    if (!requested) continue;
     if (issues === null) {
-      write("warning: --check-sitemap: sitemap.xml not found in root-dir, skipping\n");
-    } else if (issues.length) {
-      write("\n" + issues.join("\n") + "\n");
-      integrityIssueCount += issues.length;
-    }
-  }
-
-  // Cross-file search-index check.
-  if (opts.checkSearch) {
-    const issues = searchIssues = checkSearchContents(rootStr, htmlFiles, redirectStubSet, basePath);
-    if (issues === null) {
-      write("warning: --check-search: search-data.json not found in root-dir, skipping\n");
-    } else if (issues.length) {
-      write("\n" + issues.join("\n") + "\n");
-      integrityIssueCount += issues.length;
-    }
-  }
-
-  // Per-page canonical URL check.
-  if (opts.checkCanonical && canonicalByFile) {
-    const issues = canonicalIssues = checkCanonicalContents(rootStr, canonicalByFile, redirectStubSet, basePath);
-    if (issues === null) {
-      write("warning: --check-canonical: no <link rel=\"canonical\"> found in any page, skipping\n");
+      write(`warning: ${skipped}, skipping\n`);
     } else if (issues.length) {
       write("\n" + issues.join("\n") + "\n");
       integrityIssueCount += issues.length;
@@ -568,121 +491,57 @@ export function runCheck(argv, { structured = false } = {}) {
   }
 
   // Exit codes: 1 = link failures, 2 = integrity failures, 3 = both.
-  const linksFailed = broken.length > 0 || forbiddenCount > 0;
+  const linksFailed = r.broken.length > 0 || forbiddenCount > 0;
   const integrityFailed = integrityIssueCount > 0;
   let exitCode = (linksFailed ? 1 : 0) | (integrityFailed ? 2 : 0);
   if (opts.noFail) exitCode = 0;
 
   if (!structured) return { output: buf.join(""), exitCode };
 
-  return {
-    output: buf.join(""),
-    exitCode,
-    findings: buildFindings({
-      rootStr, broken, forbiddenBySource, integrityByFile,
-      sitemapIssues, searchIssues, canonicalIssues,
-      enabled: {
-        html: opts.checkHtml, a11y: opts.checkA11y,
-        ids: opts.checkIds, remoteAssets: opts.checkRemoteAssets,
-        forbid: forbidPrefixes !== null, fragments: opts.includeFragments,
-      },
-      counts: {
-        files:       htmlFiles.length,
-        occurrences: occurrences.length / 3,
-        unique:      uniqueCount,
-        brokenUnique: brokenUniqueCount,
-        forbidden:   forbiddenCount,
-        integrity:   integrityIssueCount,
-      },
-      linksFailed, integrityFailed,
-    }),
-  };
-}
-
-// Reduce a pass's conclusions to sorted arrays of tree-relative strings.
-// Category names match the flags that produce them, so a diff says which
-// check drifted rather than only that something did.
-function buildFindings({
-  rootStr, broken, forbiddenBySource, integrityByFile,
-  sitemapIssues, searchIssues, canonicalIssues, counts, enabled,
-  linksFailed, integrityFailed,
-}) {
-  const rel = (p) => relToRoot(rootStr, p);
-
-  const brokenOut = [];
-  for (let i = 0; i < broken.length; i += 3) {
-    brokenOut.push(`${rel(broken[i])}\t${broken[i + 1]}\t${broken[i + 2]}`);
-  }
-
-  const forbiddenOut = [];
-  if (forbiddenBySource) {
-    for (const [src, hits] of forbiddenBySource) {
-      for (const h of hits) forbiddenOut.push(`${rel(src)}\t${h.url}\t${h.prefix}`);
-    }
-  }
-
-  const html = [], a11y = [], dupIds = [], remoteAssets = [];
-  if (integrityByFile) {
-    for (const [src, rec] of integrityByFile) {
-      const r = rel(src);
-      for (const e of rec.htmlErrors ?? []) html.push(`${r}: html-${e.type}: <${e.tag}>`);
-      for (const e of rec.a11yErrors ?? []) {
-        if (e.type === "img-missing-alt")   a11y.push(`${r}: a11y-img-missing-alt: src=${e.src}`);
-        else if (e.type === "empty-anchor") a11y.push(`${r}: a11y-empty-anchor`);
-        else if (e.type === "empty-href")   a11y.push(`${r}: a11y-empty-href: <${e.tag}>`);
-      }
-      for (const e of rec.dupIds ?? []) dupIds.push(`${r}: duplicate-id: '${e.id}' appears ${e.count} times`);
-      for (const e of rec.remoteAssets ?? []) remoteAssets.push(`${r}: remote-asset: <${e.tag} src="${e.src}">`);
-    }
-  }
-
-  // `null` means "check not requested / input absent" and is distinct
-  // from `[]` ("ran, found nothing") -- a fused path that silently
-  // stopped running a cross-file check must not compare equal to one
-  // that ran it clean.
-  const sortOrNull = (a) => (a === null || a === undefined ? null : [...a].sort());
-
-  const gate = (on, a) => (on ? a.sort() : null);
-
-  return {
-    broken:       brokenOut.sort(),
-    forbidden:    gate(enabled.forbid, forbiddenOut),
-    html:         gate(enabled.html, html),
-    a11y:         gate(enabled.a11y, a11y),
-    dupIds:       gate(enabled.ids, dupIds),
-    remoteAssets: gate(enabled.remoteAssets, remoteAssets),
-    sitemap:      sortOrNull(sitemapIssues),
-    search:       sortOrNull(searchIssues),
-    canonical:    sortOrNull(canonicalIssues),
-    counts,
-    linksFailed, integrityFailed,
-  };
+  // findingsFor leaves `unique` null because the build cannot count it
+  // across its chunks. This pass is one chunk, so it can.
+  const findings = findingsFor(r);
+  findings.counts.unique = unique;
+  return { output: buf.join(""), exitCode, findings };
 }
 
 // ── Self-test ──────────────────────────────────────────────────
-// Regression guards.  Runs once per process; takes <10 ms.
+// Regression guards.  Runs once per process; takes ~20 ms.
 //
-//   1. checkSitemapContents / checkSearchContents must strip
-//      --base-path from extracted URLs before comparing against
-//      file-derived paths.
+//   1. --check-sitemap and --check-search must strip --base-path from
+//      the URLs they read before comparing them against the tree's own
+//      paths.
 //   2. The resolver must flag root-absolute URLs that escape
 //      --base-path as broken (browser-semantics check).  A link
 //      missing the baseurl prefix may still find a file on disk
 //      under --root-dir, but it would 404 on a real subpath deploy.
-//   3. checkCanonicalContents must flag canonical URLs whose path
+//   3. --check-canonical must flag canonical URLs whose path
 //      doesn't equal --base-path + the page's URL path.  Catches
 //      "canonical missing baseurl" (would 404 on subpath deploy)
 //      and the inverse "canonical includes baseurl on root deploy".
+//
+// Guards 1 and 3 run the whole pass, runCheck over a one-page tree, so
+// they cover this script's reading of the tree as well as the check.
 
-// Exported so scripts/check_links_diff.mjs can run it: these three guards
-// used to sit inside the `isEntry` branch below, and since b97c75f nothing
-// invokes this script as an entry point in CI -- so they ran in no
-// automated context at all. A clean differential against a broken
-// reference implementation means nothing, so the harness runs them first.
+// Exported so scripts/check_links_diff.mjs can run it, since nothing in
+// CI runs this script as an entry point. A clean comparison against a
+// side that reads the tree wrongly means nothing, so the harness runs
+// these first.
 export function selfTest() {
   const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "check-links-test-"));
   try {
-    fs.writeFileSync(path.join(tmp, "Foo.html"), "<html><body>t</body></html>");
+    const page = path.join(tmp, "Foo.html");
+    // One pass over the tree, with Foo.html declaring `canonical`.
+    const run = (canonical, bp) => {
+      fs.writeFileSync(page,
+        `<html><head><link rel="canonical" href="${canonical}"></head><body>t</body></html>`);
+      const argv = ["--offline", "--check-sitemap", "--check-search", "--check-canonical",
+                    "--root-dir", tmp, tmp];
+      if (bp) argv.push("--base-path", bp);
+      const { findings, output } = runCheck(argv, { structured: true });
+      if (!findings) throw new Error(`runCheck refused the self-test's arguments:\n${output}`);
+      return findings;
+    };
 
     fs.writeFileSync(path.join(tmp, "sitemap.xml"),
       `<?xml version="1.0" encoding="UTF-8"?>\n` +
@@ -695,31 +554,29 @@ export function selfTest() {
     fs.writeFileSync(path.join(assetsDir, "search-data.json"),
       JSON.stringify({ "0": { url: "/base/Foo", title: "Foo", content: "" } }));
 
-    const files = [path.join(tmp, "Foo.html")];
     const bp = "/base";
 
-    // Guard 1: sitemap / search check base-path stripping.
-    const sm = checkSitemapContents(tmp, files, null, bp);
-    if (!sm || sm.length)
-      throw new Error("checkSitemapContents with --base-path: " + JSON.stringify(sm));
-
-    const se = checkSearchContents(tmp, files, null, bp);
-    if (!se || se.length)
-      throw new Error("checkSearchContents with --base-path: " + JSON.stringify(se));
+    // Guard 1: sitemap / search check base-path stripping. Guard 3's
+    // first case, a correct canonical under --base-path, is this pass.
+    const ok = run("https://example.com/base/Foo", bp);
+    if (!ok.sitemap || ok.sitemap.length)
+      throw new Error("--check-sitemap with --base-path: " + JSON.stringify(ok.sitemap));
+    if (!ok.search || ok.search.length)
+      throw new Error("--check-search with --base-path: " + JSON.stringify(ok.search));
 
     // Guard 2: resolver flags off-base-path root-absolute URLs.
     // /base/Foo (inside)  -> resolves to <tmp>/Foo (exists)
     // /Foo (outside)      -> sentinel target that won't exist on disk
-    const inside = resolve("/base/Foo", tmp, path.join(tmp, "Foo.html"), tmp, bp);
+    const inside = resolve("/base/Foo", tmp, page, tmp, bp);
     if (!inside || inside[0].startsWith(OUTSIDE_BASEPATH_MARKER))
       throw new Error("resolve('/base/Foo') should resolve inside base-path: " + JSON.stringify(inside));
 
-    const outside = resolve("/Foo", tmp, path.join(tmp, "Foo.html"), tmp, bp);
+    const outside = resolve("/Foo", tmp, page, tmp, bp);
     if (!outside || !outside[0].startsWith(OUTSIDE_BASEPATH_MARKER))
       throw new Error("resolve('/Foo') with base-path should be flagged outside: " + JSON.stringify(outside));
 
     // With no base-path, every root-absolute URL is in-bounds.
-    const noBp = resolve("/Foo", tmp, path.join(tmp, "Foo.html"), tmp, "");
+    const noBp = resolve("/Foo", tmp, page, tmp, "");
     if (!noBp || noBp[0].startsWith(OUTSIDE_BASEPATH_MARKER))
       throw new Error("resolve('/Foo') without --base-path must not be flagged: " + JSON.stringify(noBp));
 
@@ -727,34 +584,21 @@ export function selfTest() {
     // canonical for Foo.html must be "<host>/base/Foo" (the actual
     // deployment URL).  Both "missing baseurl" and "wrong baseurl"
     // are mismatches.
-    const okBp = new Map([
-      [path.join(tmp, "Foo.html"), "https://example.com/base/Foo"],
-    ]);
-    const okBpIssues = checkCanonicalContents(tmp, okBp, null, bp);
-    if (!okBpIssues || okBpIssues.length)
-      throw new Error("checkCanonicalContents under --base-path: correct canonical flagged: " + JSON.stringify(okBpIssues));
-
-    const missingBaseurl = new Map([
-      [path.join(tmp, "Foo.html"), "https://example.com/Foo"],
-    ]);
-    const miBpIssues = checkCanonicalContents(tmp, missingBaseurl, null, bp);
-    if (!miBpIssues || miBpIssues.length !== 1 || !miBpIssues[0].includes("canonical-mismatch"))
-      throw new Error("checkCanonicalContents: should flag baseurl-less canonical under --base-path: " + JSON.stringify(miBpIssues));
+    if (!ok.canonical || ok.canonical.length)
+      throw new Error("--check-canonical under --base-path: correct canonical flagged: " + JSON.stringify(ok.canonical));
+
+    const miBp = run("https://example.com/Foo", bp).canonical;
+    if (!miBp || miBp.length !== 1 || !miBp[0].includes("canonical-mismatch"))
+      throw new Error("--check-canonical: should flag baseurl-less canonical under --base-path: " + JSON.stringify(miBp));
 
     // With no --base-path, canonical must NOT include any path prefix.
-    const okNoBp = new Map([
-      [path.join(tmp, "Foo.html"), "https://example.com/Foo"],
-    ]);
-    const okNoBpIssues = checkCanonicalContents(tmp, okNoBp, null, "");
-    if (!okNoBpIssues || okNoBpIssues.length)
-      throw new Error("checkCanonicalContents without --base-path: correct canonical flagged: " + JSON.stringify(okNoBpIssues));
-
-    const extraBaseurl = new Map([
-      [path.join(tmp, "Foo.html"), "https://example.com/base/Foo"],
-    ]);
-    const exNoBpIssues = checkCanonicalContents(tmp, extraBaseurl, null, "");
-    if (!exNoBpIssues || exNoBpIssues.length !== 1 || !exNoBpIssues[0].includes("canonical-mismatch"))
-      throw new Error("checkCanonicalContents: should flag canonical with extra prefix on root deploy: " + JSON.stringify(exNoBpIssues));
+    const okNoBp = run("https://example.com/Foo", "").canonical;
+    if (!okNoBp || okNoBp.length)
+      throw new Error("--check-canonical without --base-path: correct canonical flagged: " + JSON.stringify(okNoBp));
+
+    const exNoBp = run("https://example.com/base/Foo", "").canonical;
+    if (!exNoBp || exNoBp.length !== 1 || !exNoBp[0].includes("canonical-mismatch"))
+      throw new Error("--check-canonical: should flag canonical with extra prefix on root deploy: " + JSON.stringify(exNoBp));
   } finally {
     fs.rmSync(tmp, { recursive: true, force: true });
   }
diff --git a/scripts/check_links_diff.mjs b/scripts/check_links_diff.mjs
index 739a1f16..01fcd1e2 100644
--- a/scripts/check_links_diff.mjs
+++ b/scripts/check_links_diff.mjs
@@ -1,14 +1,17 @@
 // Differential harness for the link checker.
 //
-// Runs the same check pass under two named *sides* -- two
-// implementations that are supposed to reach identical conclusions --
-// and diffs their findings category by category. Exits non-zero on any
-// difference.
+// Runs the same check pass under two named *sides* -- two ways of
+// running one check, which must reach identical conclusions -- and
+// diffs their findings category by category. Exits non-zero on any
+// difference. The two sides that matter run the same functions in
+// builder/check.mjs and differ in how they read the tree: the
+// standalone script reads it from disk, while the build's pass holds it
+// in memory, answers "does this exist" from an index of what it wrote,
+// and checks it in chunks across its workers.
 //
-// It exists because of the failure mode that makes this whole
-// refactor dangerous: a checker that silently checks *less* reports a
+// It exists because a checker that silently checks *less* reports a
 // clean pass. `check.bat` going green proves nothing about whether the
-// fused path still looks at everything the standalone script does.
+// fused path still looks at everything a read from disk finds.
 // This is the same role scripts/check_a11y_fingerprint.mjs plays on the
 // axe side, and it has the same blind spot: it compares conclusions,
 // never the shape of the work that produced them. Treat it as
@@ -330,7 +333,7 @@ const SIDES = {
   // case-insensitive), and a side that silently became the same oracle
   // as `index` would turn this comparison into a no-op on one platform.
   //
-  // It is the reference implementation, not an oracle of record: on
+  // It is the reference side, not an oracle of record: on
   // Windows, FsOracle answers "exists" for a wrong-case path that 404s on
   // GitHub Pages, so on that one question the `index` side is the correct
   // one and this side is the one with the missing finding.
diff --git a/test/README.md b/test/README.md
index c7bbc981..1862ec29 100644
--- a/test/README.md
+++ b/test/README.md
@@ -18,16 +18,18 @@ the fixture or the checker.
 
 ## Why this exists
 
-The link and integrity check has two front ends over one core
-([`builder/link-check.mjs`](../builder/link-check.mjs)):
+The link and integrity check has two front ends over one implementation
+([`builder/check.mjs`](../builder/check.mjs), over the core in
+[`builder/link-check.mjs`](../builder/link-check.mjs)):
 
 - the **build's own** fused check, reached with `tbdocs --check`, which walks each tree's
   HTML on the worker lane that produced it; and
 - the **standalone** [`scripts/check_links.mjs`](../scripts/check_links.mjs), for a tree
   the build did not produce --- a release zip, a bisect, someone else's artifact.
 
-Two implementations of one check is exactly the shape that rots quietly, because **a
-checker that silently checks less reports a clean pass.** `check_links_diff.mjs` runs both
+The two read the tree differently --- the build from memory, through an index of what it
+wrote and in chunks across its workers --- and **a checker that silently checks less
+reports a clean pass.** `check_links_diff.mjs` runs both
 over the same bytes and diffs their findings category by category.
 
 On a healthy site that comparison is nearly worthless: the real tree is clean, so both
@@ -79,8 +81,8 @@ in `tbdocs-gh-pages.yml`, which keeps only the cheaper `fixture` case, and neith
 having folded the check into the build. Run them locally after touching
 `builder/link-check.mjs`, `builder/check.mjs` or `scripts/check_links.mjs`.
 
-`--self-test` is a third mode: it diffs the reference implementation against a
-deliberately corrupted copy of itself and fails unless the difference is reported.
+`--self-test` is a third mode: it diffs the `script` side against a deliberately
+corrupted copy of itself and fails unless the difference is reported.
 Everything else the harness prints reduces to "the two sides agreed", which is also what a
 harness comparing nothing says.
 

From 7edfc87797bc7d3e78c2dcf80253a44b85020dca Mon Sep 17 00:00:00 2001
From: Kuba Sunderland-Ober <kuba@mareimbrium.org>
Date: Sun, 27 Sep 2026 16:50:57 +0200
Subject: [PATCH 20/27] scripts: lib/gate-probes.mjs for the gates' probes and
 crash handler

---
 builder/PLAN-TOOLING-REVIEW.md         | 40 +++++++++++++++++
 docs/Documentation/Extending.md        |  4 +-
 docs/Documentation/Tools.md            |  2 +-
 scripts/build_dot_metrics.mjs          |  8 ++--
 scripts/check_book_coverage.mjs        | 27 +++--------
 scripts/check_ci_workflows.mjs         |  3 +-
 scripts/check_dot_fit.mjs              |  6 +--
 scripts/check_lint.mjs                 |  3 +-
 scripts/check_page_baseline.mjs        | 41 +++--------------
 scripts/check_publish_policy.mjs       |  6 +--
 scripts/check_symbol_index.mjs         | 48 ++++++--------------
 scripts/check_tb_registry.mjs          |  7 ++-
 scripts/convert_em_dash_separators.mjs |  3 +-
 scripts/lib/gate-probes.mjs            | 62 ++++++++++++++++++++++++++
 scripts/pick_a11y_sample.mjs           |  7 ++-
 15 files changed, 149 insertions(+), 118 deletions(-)
 create mode 100644 scripts/lib/gate-probes.mjs

diff --git a/builder/PLAN-TOOLING-REVIEW.md b/builder/PLAN-TOOLING-REVIEW.md
index 1d3643ac..802cf119 100644
--- a/builder/PLAN-TOOLING-REVIEW.md
+++ b/builder/PLAN-TOOLING-REVIEW.md
@@ -1219,6 +1219,41 @@ re-indenting becomes the shared behaviour: the one change in output, and only in
 **Verify.** Each adopting gate's probe count and verdict unchanged; a broken probe still fails
 it; a forced crash exits 2.
 
+**Landed.** `scripts/lib/gate-probes.mjs` exports `exitOnCrash()`, `createProbes(tool,
+onFailure)`, whose `check` records a probe and whose `report()` prints the lines and the
+summary and returns the exit code, and `baselineFixture(name)`, which returns the
+`withBaseline(initial, fn)` both drift-guard self-tests call. Each does its work when called,
+never on import. The three probe gates adopt all three; `check_book_coverage.mjs` passes its
+summary's remedy as `onFailure`. `check_symbol_index.mjs`'s fixture now takes `{ src, urls }`
+(`BASE_FILE`) and writes it pretty-printed where it was compact, which both guards read with
+`JSON.parse`. The temporary folders are `tb-page-baseline-*` and `tb-symbol-baseline-*`
+(were `tb-pagebaseline-*`, `tb-symbolbaseline-*`). `exitOnCrash()` replaces the handler in
+eleven files: the three gates, `check_publish_policy.mjs` (which keeps its own reporter), C07's
+in `convert_em_dash_separators.mjs`, still inside its entry-point guard, and C28's three
+(`pick_a11y_sample`, `build_dot_metrics`, `check_tb_registry`); and, at the owner's choice,
+the three copies this entry did not name: `check_dot_fit.mjs`, which the others copied,
+`check_ci_workflows.mjs` (C03) and `check_lint.mjs` (C06). Where a handler's comment said what
+exit 1 means, one line keeps that. Neither `check_gate_lists.mjs` nor `check_regex_safety.mjs`
+fits exactly, so neither adopts, and the failed-probe exit code is not a parameter (Where the
+plan was wrong). Extending.md's exit-code convention names `exitOnCrash` for a script with no
+`main()`, and a sentence after its four probe shapes names `createProbes`. Tools.md's
+`check_page_baseline` section now says it exits 2 if it cannot run, as its two siblings'
+sections say; the handler was there before.
+
+Oracle: the kit's `c43-oracle.mjs before|after|compare` runs 26 cases: each of the eleven
+tools plainly (`pick_a11y_sample`, `build_dot_metrics` and the converter with `--check`,
+`check_tb_registry` once each side, 37 s), each through a forced crash (`c43-crash.mjs`, a
+preload whose wrapped `process.on` throws from the line that installs the handler), an
+import of the converter that counts the `uncaughtException` listeners it leaves (0), and the
+three probe gates through a broken probe (`c43-fault.mjs`, a load hook that edits a builder
+module's source as it loads: `was ${baseline[k]}` in `page-baseline.mjs`, `is missing` in
+`symbol-baseline.mjs`, the `unlisted` push in `book.mjs`). 23 cases are identical, every crash
+exiting 2 with `Error: c43 forced crash` and each fault exiting 1 with the same probe failed.
+The three differences: lint checks 143 files, the new module among them; and in the page and
+symbol faults the detail's continuation lines gain seven spaces, so they stay aligned under
+`ERROR:` as the build prints them, the one change the entry expects. No `tb-*-baseline-*`
+folder is left in `%TEMP%`.
+
 ### C44 — `scripts: the dot tools share one launch, host page and source list`
 
 **A5-5, A5-6 / L2-3 (R2).** `check_dot_fit.mjs:76-87` and `build_dot_metrics.mjs:57-68`
@@ -2050,6 +2085,11 @@ text, gains a Landed note, and the correction is listed here, as in the last rev
   cannot both hold, since `formatReport` prints the build's format. The owner chose the
   unchanged report: the script prints its own summary lines around the two `link-check.mjs`
   reporters it already shared, and `formatReport` stays the build's; see C42's Landed note.
+- **C43 (A6-1): no exit-code parameter.** The entry makes the exit code for a failed probe a
+  parameter, 2 for `check_gate_lists.mjs` and `check_regex_safety.mjs`, which adopt only if
+  the fit is exact. It is not: the first keeps its probes as pairs, prints failures to stderr
+  and has verbose and self-test-only modes, and the second runs its probes inside the sharded
+  recheck. With no caller passing anything but 1, `report()` returns 1; see C43's Landed note.
 
 ## Found while implementing
 
diff --git a/docs/Documentation/Extending.md b/docs/Documentation/Extending.md
index 980b78d4..948bff0c 100644
--- a/docs/Documentation/Extending.md
+++ b/docs/Documentation/Extending.md
@@ -645,7 +645,7 @@ The split exists so that an edit confined to `docs/` usually has to pay for `che
 | `1` | The checked thing failed. This is the finding. |
 | `2` | The harness or the environment failed --- an unknown argument, an absent tree, an unhandled throw. Nothing was checked. |
 
-Separating 1 from 2 is what stops a broken gate reading as a clean site, and it has to hold at the top level too. End the script with `main().catch((err) => { console.error(err); process.exit(2); })`, the way `check_a11y.mjs` does, so a crash cannot fall through to node's default exit 1 and be mistaken for a finding.
+Separating 1 from 2 is what stops a broken gate reading as a clean site, and it has to hold at the top level too. End the script with `main().catch((err) => { console.error(err); process.exit(2); })`, the way `check_a11y.mjs` does, so a crash cannot fall through to node's default exit 1 and be mistaken for a finding. A script that runs at top level, with no `main()`, calls `exitOnCrash()` from `scripts/lib/gate-probes.mjs` before it does anything else; that handler also catches a rejected top-level await.
 
 **Say what a pass covered.** Nearly every gate in both wrappers does: `check_dot_fit.mjs` gives the diagram count, `pick_a11y_sample.mjs --check` the sample size and the number of construct families in use, `check_publish_policy.mjs` the probe counts on both sides, `check_code_regions.mjs` the number of files swept, the number whose code regions moved and the number of fences found, `check_a11y.mjs` the page × theme × viewport product it audited. A gate silent on success says nothing about whether it examined anything, which is the state a gate that has quietly stopped working also reports.
 
@@ -672,6 +672,8 @@ So a new gate needs a second assertion of the opposite sign, and there are four
 - **A fixture that provokes one fault of each kind,** with the count asserted afterwards. The real site is clean, so without one every category compares empty against empty --- and a category that has stopped being checked looks identical to a category with nothing to find.
 - **An A/A control.** Running `check_a11y_fingerprint.mjs` with the same scheme on both sides says whether the harness is stable, before any A/B result from it is believed.
 
+A self-test made of named probes, such as `check_page_baseline.mjs`, records them with `createProbes` from `scripts/lib/gate-probes.mjs`, which prints a line for each probe and a summary, and returns the exit code.
+
 When the gate cannot assert its own correctness from the inside, the proof goes in a sibling script and is named in the gate's header comment, so whoever changes the gate next finds it in the file they are already reading.
 
 ---
diff --git a/docs/Documentation/Tools.md b/docs/Documentation/Tools.md
index 0cd448fe..9714b451 100644
--- a/docs/Documentation/Tools.md
+++ b/docs/Documentation/Tools.md
@@ -490,7 +490,7 @@ The guard says nothing on a healthy tree, so every ordinary build sounds exactly
 
 Two probes look redundant and are the two that caught real bugs while the guard was being written. A **foreign source root must be ignored**: [`check_links_diff.mjs`](#check-links-diff) builds a three-page fixture tree, and a baseline keyed to nothing met it with *905 pages missing*. And **CI must refuse a missing baseline** rather than create one, because a run that wrote the file would record whatever drop it had been asked to catch.
 
-Exits 1 on any failed probe.
+Exits 1 on any failed probe, 2 if it cannot run.
 
 ### check_book_coverage.mjs
 {: #check-book-coverage }
diff --git a/scripts/build_dot_metrics.mjs b/scripts/build_dot_metrics.mjs
index da341e09..dc437d1d 100644
--- a/scripts/build_dot_metrics.mjs
+++ b/scripts/build_dot_metrics.mjs
@@ -35,12 +35,10 @@ import { promises as fs } from "node:fs";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import puppeteer from "puppeteer";
+import { exitOnCrash } from "./lib/gate-probes.mjs";
 
-// A crash is the harness failing, not a finding: exit 2, as Extending.md's gate
-// conventions require, where 1 is --check finding the table stale. This file
-// runs at top level, so there is no main().catch to do it; the handler also
-// catches a rejected top-level await.
-process.on("uncaughtException", (err) => { console.error(err); process.exit(2); });
+// A crash exits 2, where 1 is --check finding the table stale.
+exitOnCrash();
 
 const REPO = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
 const OUT = path.join(REPO, "builder", "inter-metrics.json");
diff --git a/scripts/check_book_coverage.mjs b/scripts/check_book_coverage.mjs
index c20feb6a..13f3833b 100644
--- a/scripts/check_book_coverage.mjs
+++ b/scripts/check_book_coverage.mjs
@@ -20,11 +20,9 @@
 //     node scripts/check_book_coverage.mjs
 
 import { resolveBookChapters, bookCoverage, formatBookCoverage } from "../builder/book.mjs";
+import { createProbes, exitOnCrash } from "./lib/gate-probes.mjs";
 
-// A crash is the harness failing, not a finding: exit 2, as Extending.md's gate
-// conventions require. This file runs at top level, so there is no main().catch
-// to do it; the handler also catches a rejected top-level await.
-process.on("uncaughtException", (err) => { console.error(err); process.exit(2); });
+exitOnCrash();
 
 const page = (srcRel, permalink, title, frontmatter = {}) => ({
   srcRel, permalink, navPath: title, frontmatter: { title, permalink, ...frontmatter },
@@ -78,13 +76,8 @@ function coverage(mutate = () => {}) {
 const KINDS = ["unlisted", "both", "emptyEntries", "emptyLeftOut", "missingUrls"];
 const counts = (c) => KINDS.map(k => `${k}=${c[k].length}`).join(" ");
 
-let failures = 0;
-const results = [];
-
-function check(name, ok, detail) {
-  results.push({ name, ok, detail });
-  if (!ok) failures++;
-}
+const { check, report } = createProbes("check_book_coverage",
+  "bookCoverage() in builder/book.mjs no longer reports what the probe names");
 
 // Exactly the findings `expect` names, as {kind: n}, and none of any other kind.
 function only(c, expect) {
@@ -157,14 +150,4 @@ function only(c, expect) {
 
 // --- report ------------------------------------------------------------------
 
-for (const { name, ok, detail } of results) {
-  console.log(`  ${ok ? "ok  " : "FAIL"} ${name}`);
-  if (!ok && detail) console.log(`       ${detail.replaceAll("\n", "\n       ")}`);
-}
-console.log(
-  failures
-    ? `check_book_coverage: ${failures} of ${results.length} probes failed -- ` +
-      `bookCoverage() in builder/book.mjs no longer reports what the probe names`
-    : `check_book_coverage: ${results.length} probes, all pass`
-);
-process.exit(failures ? 1 : 0);
+process.exit(report());
diff --git a/scripts/check_ci_workflows.mjs b/scripts/check_ci_workflows.mjs
index 7daf1856..73c0eaf1 100644
--- a/scripts/check_ci_workflows.mjs
+++ b/scripts/check_ci_workflows.mjs
@@ -30,9 +30,10 @@ import { readFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import yaml from "js-yaml";
+import { exitOnCrash } from "./lib/gate-probes.mjs";
 import { buildArgs, gateSteps, workflowSteps } from "./lib/gate-roster.mjs";
 
-process.on("uncaughtException", (err) => { console.error(err); process.exit(2); });
+exitOnCrash();
 
 const ROOT = path.resolve(fileURLToPath(new URL("..", import.meta.url)));
 const JOB = "build";
diff --git a/scripts/check_dot_fit.mjs b/scripts/check_dot_fit.mjs
index c8928030..39782b2f 100644
--- a/scripts/check_dot_fit.mjs
+++ b/scripts/check_dot_fit.mjs
@@ -27,11 +27,9 @@ import { promises as fs } from "node:fs";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import puppeteer from "puppeteer";
+import { exitOnCrash } from "./lib/gate-probes.mjs";
 
-// A crash is the harness failing, not a finding: exit 2, as Extending.md's gate
-// conventions require. This file runs at top level, so there is no main().catch
-// to do it; the handler also catches a rejected top-level await.
-process.on("uncaughtException", (err) => { console.error(err); process.exit(2); });
+exitOnCrash();
 
 const REPO = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
 const SRC = path.join(REPO, "docs");
diff --git a/scripts/check_lint.mjs b/scripts/check_lint.mjs
index 6a420642..872dce1f 100644
--- a/scripts/check_lint.mjs
+++ b/scripts/check_lint.mjs
@@ -37,8 +37,9 @@ import { createRequire } from "node:module";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { exitOnCrash } from "./lib/gate-probes.mjs";
 
-process.on("uncaughtException", (err) => { console.error(err); process.exit(2); });
+exitOnCrash();
 
 const ROOT = path.resolve(fileURLToPath(new URL("..", import.meta.url)));
 
diff --git a/scripts/check_page_baseline.mjs b/scripts/check_page_baseline.mjs
index f092b1b5..eb8bbd26 100644
--- a/scripts/check_page_baseline.mjs
+++ b/scripts/check_page_baseline.mjs
@@ -23,36 +23,16 @@
 //
 //     node scripts/check_page_baseline.mjs
 
-import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import path from "node:path";
+import { readFile } from "node:fs/promises";
 import { checkPageBaseline, GUARDED_SRC } from "../builder/page-baseline.mjs";
+import { baselineFixture, createProbes, exitOnCrash } from "./lib/gate-probes.mjs";
 
-// A crash is the harness failing, not a finding: exit 2, as Extending.md's gate
-// conventions require. This file runs at top level, so there is no main().catch
-// to do it; the handler also catches a rejected top-level await.
-process.on("uncaughtException", (err) => { console.error(err); process.exit(2); });
+exitOnCrash();
 
 const BASE = { src: GUARDED_SRC, pages: 908, staticFiles: 247 };
 
-let failures = 0;
-const results = [];
-
-function check(name, ok, detail) {
-  results.push({ name, ok, detail });
-  if (!ok) failures++;
-}
-
-async function withBaseline(initial, fn) {
-  const dir = await mkdtemp(path.join(tmpdir(), "tb-pagebaseline-"));
-  const file = path.join(dir, "page-baseline.json");
-  try {
-    if (initial) await writeFile(file, `${JSON.stringify(initial, null, 2)}\n`, "utf8");
-    return await fn(file);
-  } finally {
-    await rm(dir, { recursive: true, force: true });
-  }
-}
+const { check, report } = createProbes("check_page_baseline");
+const withBaseline = baselineFixture("page-baseline.json");
 
 const readJson = async (file) => JSON.parse(await readFile(file, "utf8"));
 
@@ -127,13 +107,4 @@ await withBaseline(null, async (file) => {
 
 // --- report ------------------------------------------------------------------
 
-for (const { name, ok, detail } of results) {
-  console.log(`  ${ok ? "ok  " : "FAIL"} ${name}`);
-  if (!ok && detail) console.log(`       ${detail}`);
-}
-console.log(
-  failures
-    ? `check_page_baseline: ${failures} of ${results.length} probes failed`
-    : `check_page_baseline: ${results.length} probes, all pass`
-);
-process.exit(failures ? 1 : 0);
+process.exit(report());
diff --git a/scripts/check_publish_policy.mjs b/scripts/check_publish_policy.mjs
index b328ebb7..348bb7c7 100644
--- a/scripts/check_publish_policy.mjs
+++ b/scripts/check_publish_policy.mjs
@@ -22,11 +22,9 @@ import {
   publishPolicyFor, unpublishableSourceFiles, unpublishableTreePaths,
   SOURCE_EXTENSIONS, BUILD_EXTENSIONS,
 } from "../builder/publish-policy.mjs";
+import { exitOnCrash } from "./lib/gate-probes.mjs";
 
-// A crash is the harness failing, not a finding: exit 2, as Extending.md's gate
-// conventions require. This file runs at top level, so there is no main().catch
-// to do it; the handler also catches a rejected top-level await.
-process.on("uncaughtException", (err) => { console.error(err); process.exit(2); });
+exitOnCrash();
 
 const SRC = process.argv.includes("--src")
   ? process.argv[process.argv.indexOf("--src") + 1]
diff --git a/scripts/check_symbol_index.mjs b/scripts/check_symbol_index.mjs
index 8dc7aec9..cdca3b9e 100644
--- a/scripts/check_symbol_index.mjs
+++ b/scripts/check_symbol_index.mjs
@@ -26,23 +26,16 @@
 //     typographer's ellipsis in a Core heading, and an attribute's `##`;
 //   - the drift guard's refusals, which on a healthy tree it never shows.
 
-import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import path from "node:path";
+import { readFile } from "node:fs/promises";
 import { checkSymbolBaseline } from "../builder/symbol-baseline.mjs";
 import { deriveSymbolIndex, headingsOf, serializeSymbolIndex } from "../builder/symbols.mjs";
 import { GUARDED_SRC } from "../builder/page-baseline.mjs";
+import { baselineFixture, createProbes, exitOnCrash } from "./lib/gate-probes.mjs";
 import { apiSnapshot, isPublicType, parseTwin } from "./lib/twin-api.mjs";
 
-// A crash is the harness failing, not a finding: exit 2.
-process.on("uncaughtException", (err) => { console.error(err); process.exit(2); });
+exitOnCrash();
 
-let failures = 0;
-const results = [];
-function check(name, ok, detail) {
-  results.push({ name, ok, detail });
-  if (!ok) failures++;
-}
+const { check, report } = createProbes("check_symbol_index");
 const show = (x) => JSON.stringify(x);
 
 // ------------------------------------------------------------ the scanner
@@ -311,41 +304,33 @@ check("a declared member no page documents is a gap, not an entry",
 
 // ------------------------------------------------------------ the drift guard
 
-async function withBaseline(initial, fn) {
-  const dir = await mkdtemp(path.join(tmpdir(), "tb-symbolbaseline-"));
-  const file = path.join(dir, "symbol-baseline.json");
-  try {
-    if (initial) await writeFile(file, JSON.stringify({ src: GUARDED_SRC, urls: initial }), "utf8");
-    return await fn(file);
-  } finally {
-    await rm(dir, { recursive: true, force: true });
-  }
-}
+const withBaseline = baselineFixture("symbol-baseline.json");
 const urlsIn = async (file) => JSON.parse(await readFile(file, "utf8")).urls;
 const BASE = ["/tB/Modules/Strings/Left", "/tB/Packages/tbIDE/ToolWindows#add"];
+const BASE_FILE = { src: GUARDED_SRC, urls: BASE };
 
-await withBaseline(BASE, async (file) => {
+await withBaseline(BASE_FILE, async (file) => {
   const out = await checkSymbolBaseline({ src: GUARDED_SRC, urls: ["/tB/Modules/Strings/Left", "/tB/Packages/tbIDE/ToolWindows#add-method"], write: true, file });
   check("a reworded heading's lost anchor fails, and is named",
     out.failed && out.text.includes("ToolWindows#add") && (await urlsIn(file)).length === 2, out.text.trim());
 });
-await withBaseline(BASE, async (file) => {
+await withBaseline(BASE_FILE, async (file) => {
   const out = await checkSymbolBaseline({ src: GUARDED_SRC, urls: [...BASE, "/tB/Core/Dim"], write: true, file });
   check("a new URL is accepted and recorded", !out.failed && (await urlsIn(file)).includes("/tB/Core/Dim"), out.text.trim());
 });
-await withBaseline(BASE, async (file) => {
+await withBaseline(BASE_FILE, async (file) => {
   const out = await checkSymbolBaseline({ src: GUARDED_SRC, urls: [...BASE, "/tB/Core/Dim"], write: false, file });
   check("a new URL with write:false leaves the file alone", !out.failed && (await urlsIn(file)).length === 2, out.text.trim());
 });
-await withBaseline(BASE, async (file) => {
+await withBaseline(BASE_FILE, async (file) => {
   const out = await checkSymbolBaseline({ src: GUARDED_SRC, urls: BASE, write: true, file });
   check("an unchanged index says nothing", !out.failed && out.text === "", show(out.text));
 });
-await withBaseline(BASE, async (file) => {
+await withBaseline(BASE_FILE, async (file) => {
   await checkSymbolBaseline({ src: GUARDED_SRC, urls: BASE.slice(0, 1), write: false, force: true, file });
   check("--update-symbol-baseline records a removal on request", (await urlsIn(file)).length === 1);
 });
-await withBaseline(BASE, async (file) => {
+await withBaseline(BASE_FILE, async (file) => {
   const out = await checkSymbolBaseline({ src: "test/fixtures/check-src", urls: [], write: true, file });
   check("a foreign source root is ignored, not measured", !out.failed && out.text === "" && (await urlsIn(file)).length === 2);
 });
@@ -360,11 +345,4 @@ await withBaseline(null, async (file) => {
 
 // ------------------------------------------------------------ report
 
-for (const { name, ok, detail } of results) {
-  console.log(`  ${ok ? "ok  " : "FAIL"} ${name}`);
-  if (!ok && detail) console.log(`       ${detail}`);
-}
-console.log(failures
-  ? `check_symbol_index: ${failures} of ${results.length} probes failed`
-  : `check_symbol_index: ${results.length} probes, all pass`);
-process.exit(failures ? 1 : 0);
+process.exit(report());
diff --git a/scripts/check_tb_registry.mjs b/scripts/check_tb_registry.mjs
index 143bb5db..0f307ecb 100644
--- a/scripts/check_tb_registry.mjs
+++ b/scripts/check_tb_registry.mjs
@@ -49,12 +49,11 @@ import assert from "node:assert/strict";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
+import { exitOnCrash } from "./lib/gate-probes.mjs";
 import * as R from "./lib/tb-registry.mjs";
 
-// A crash is the harness failing, not a finding: exit 2, as Extending.md's gate
-// conventions require. This file runs at top level, so there is no main().catch
-// to do it; the catch below passes it everything but a failed assertion.
-process.on("uncaughtException", (err) => { console.error(err); process.exit(2); });
+// A crash exits 2; the catch below passes on everything but a failed assertion.
+exitOnCrash();
 
 const BASE = "Software\\tbharness-selftest";
 const ROOT = BASE + "\\twinBASIC_IDE";
diff --git a/scripts/convert_em_dash_separators.mjs b/scripts/convert_em_dash_separators.mjs
index 3e880f89..d0dc4563 100644
--- a/scripts/convert_em_dash_separators.mjs
+++ b/scripts/convert_em_dash_separators.mjs
@@ -47,6 +47,7 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import { createMarkdownIt } from "../builder/render.mjs";
 import { blockRegions, mapLines, splitCodeSpans } from "../lib/markdown.mjs";
 import { markdownFiles } from "../lib/markdown-files.mjs";
+import { exitOnCrash } from "./lib/gate-probes.mjs";
 
 const REPO = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
 const ROOT = path.join(REPO, "docs");
@@ -159,6 +160,6 @@ async function main(argv) {
 }
 
 if (process.argv[1] && pathToFileURL(process.argv[1]).href === import.meta.url) {
-  process.on("uncaughtException", (err) => { console.error(err); process.exit(2); });
+  exitOnCrash();
   process.exit(await main(process.argv.slice(2)));
 }
diff --git a/scripts/lib/gate-probes.mjs b/scripts/lib/gate-probes.mjs
new file mode 100644
index 00000000..b4a5d321
--- /dev/null
+++ b/scripts/lib/gate-probes.mjs
@@ -0,0 +1,62 @@
+// What the gates' self-tests share: the crash handler, the probe accumulator
+// and its report, and a scratch baseline file for the two drift guards.
+//
+// Every export here does its work when called, never on import, so a module
+// that can be imported as well as run -- convert_em_dash_separators.mjs is one
+// -- installs nothing in the process that imports it.
+
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+// A crash is the harness failing, not a finding: exit 2, as Extending.md's gate
+// conventions require. A script that runs at top level has no main().catch to
+// do it; this handler also catches a rejected top-level await.
+export function exitOnCrash() {
+  process.on("uncaughtException", (err) => { console.error(err); process.exit(2); });
+}
+
+// A probe list for the gate `tool`. `check(name, ok, detail)` records one probe;
+// `report()` prints a line for each, with a failed probe's detail under it,
+// every line of the detail indented alike, then a summary, and returns the exit
+// code: 1 if any probe failed. `onFailure`, when given, ends the summary of a
+// failed run, to say what a failed probe means.
+export function createProbes(tool, onFailure) {
+  const results = [];
+  return {
+    check(name, ok, detail) {
+      results.push({ name, ok, detail });
+    },
+    report() {
+      const failures = results.filter((r) => !r.ok).length;
+      for (const { name, ok, detail } of results) {
+        console.log(`  ${ok ? "ok  " : "FAIL"} ${name}`);
+        if (!ok && detail) console.log(`       ${String(detail).replaceAll("\n", "\n       ")}`);
+      }
+      console.log(
+        failures
+          ? `${tool}: ${failures} of ${results.length} probes failed${onFailure ? ` -- ${onFailure}` : ""}`
+          : `${tool}: ${results.length} probes, all pass`
+      );
+      return failures ? 1 : 0;
+    },
+  };
+}
+
+// withBaseline(initial, fn) for a drift guard whose baseline is the JSON file
+// `name`. fn(file) runs with `file` in a fresh folder in the system temp
+// directory, holding `initial` as JSON, or absent when `initial` is null; the
+// folder is removed whatever fn does. So no probe touches the real baseline
+// under builder/.
+export function baselineFixture(name) {
+  return async (initial, fn) => {
+    const dir = await mkdtemp(path.join(tmpdir(), `tb-${path.basename(name, ".json")}-`));
+    const file = path.join(dir, name);
+    try {
+      if (initial) await writeFile(file, `${JSON.stringify(initial, null, 2)}\n`, "utf8");
+      return await fn(file);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  };
+}
diff --git a/scripts/pick_a11y_sample.mjs b/scripts/pick_a11y_sample.mjs
index fb5e83bc..86b0df09 100644
--- a/scripts/pick_a11y_sample.mjs
+++ b/scripts/pick_a11y_sample.mjs
@@ -45,11 +45,10 @@
 import { readdirSync, readFileSync, existsSync } from "node:fs";
 import { resolve, join, relative, sep } from "node:path";
 import { DEFAULT_ROOT_DIR, REPO_ROOT, SAMPLE_PAGES } from "./lib/axe-scan.mjs";
+import { exitOnCrash } from "./lib/gate-probes.mjs";
 
-// A crash is the harness failing, not a finding: exit 2, as Extending.md's gate
-// conventions require, where 1 is a coverage gap. This file runs at top level,
-// so there is no main().catch to do it.
-process.on("uncaughtException", (err) => { console.error(err); process.exit(2); });
+// A crash exits 2, where 1 is a coverage gap.
+exitOnCrash();
 
 // ---------------------------------------------------------------------------
 // Construct families

From c0fc52ab04d2a0db1c4cc001085a4a9d3a6161ee Mon Sep 17 00:00:00 2001
From: Kuba Sunderland-Ober <kuba@mareimbrium.org>
Date: Sun, 27 Sep 2026 17:02:52 +0200
Subject: [PATCH 21/27] scripts: the dot tools share one launch, host page and
 source list

---
 builder/PLAN-TOOLING-REVIEW.md        | 31 +++++++++++++
 builder/dot.mjs                       |  5 +-
 docs/Documentation/Pipeline-Stages.md |  1 +
 scripts/build_dot_metrics.mjs         | 38 +++------------
 scripts/check_dot_fit.mjs             | 67 +++++++--------------------
 scripts/lib/inter-page.mjs            | 40 ++++++++++++++++
 6 files changed, 99 insertions(+), 83 deletions(-)
 create mode 100644 scripts/lib/inter-page.mjs

diff --git a/builder/PLAN-TOOLING-REVIEW.md b/builder/PLAN-TOOLING-REVIEW.md
index 802cf119..8d1f87a4 100644
--- a/builder/PLAN-TOOLING-REVIEW.md
+++ b/builder/PLAN-TOOLING-REVIEW.md
@@ -1269,6 +1269,32 @@ skip, which is safe today.
 **Verify.** `check_dot_fit.mjs`'s output unchanged; `build_dot_metrics.mjs` regenerates
 `builder/inter-metrics.json` byte for byte; both listings name the same files.
 
+**Landed.** Both tools launch through `withBrowser` from `scripts/lib/browser.mjs`, and
+`--allow-file-access-from-files` is gone rather than explained: the host page loads both Inter
+faces without it (Where the plan was wrong), so `browser.mjs` is unchanged. The host page is
+built in a new `scripts/lib/inter-page.mjs`, whose `openInterPage(browser, name, { css, body
+})` writes `docs/_<name>-host.html` with the two `@font-face` rules, loads it, removes it, and
+returns the page with its `pageerror` logger; each tool passes only its own styles, and the
+two host files keep their names. The page's `<title>` is now the name (`dot-fit`,
+`dot-metrics`; was `dot fit`, `metrics`), which nothing reads. `builder/dot.mjs` exports
+`listDotSources`, and `check_dot_fit.mjs` maps its sources to the SVGs on disk in place of
+`findDotSvgs`, then sorts them as before (a sorted list of `.dot` paths can come out in
+another order once each ends in `.svg`, as `a.dot` and `a.e.dot` do). Pipeline-Stages.md's
+`dot.mjs` table gains the row. Neither tool's `try` body returned or exited, so moving it into
+the callback changed nothing; `build_dot_metrics.mjs`'s `table` is now the callback's result.
+
+Oracle: the kit's `c44-oracle.mjs before|after|compare`, 7 cases: `check_dot_fit` plain and
+`--verbose` (their `ok` lines name every SVG found, so they are the listing), with its
+tolerance forced to -100 through `c43-fault.mjs` (exit 1, every diagram reported), and through
+`c43-crash.mjs` (exit 2); `build_dot_metrics --check`, a regeneration, and a crash. All 7 are
+identical before and after, the regeneration leaves `inter-metrics.json` unchanged (sha256
+`15d2c7739cde15b2…` both sides), and no run leaves a host file in `docs/` or a Puppeteer
+profile in `%TEMP%`. The kit's `c44-noflag.mjs` ran the four plain cases with the flag still
+there but turned off, and all four matched; `c44-flag.mjs` prints each face's
+`FontFace.status` after a load, `loaded` both ways. With a font URL broken through
+`c43-fault.mjs`, both tools exit 2 on `NetworkError` from `document.fonts.load`, so a refused
+font stops the run rather than measuring a fallback; `inter-page.mjs`'s header says so.
+
 ### C45 — `a11y: one page discovery and stub ceiling for the sampler and the sweep`
 
 **A5-3 / L4-9, A5-4 (R2, R3).** `pick_a11y_sample.mjs` (`:122,159-169,184`, `STUB_CEILING`)
@@ -2090,6 +2116,11 @@ text, gains a Landed note, and the correction is listed here, as in the last rev
   the fit is exact. It is not: the first keeps its probes as pairs, prints failures to stderr
   and has verbose and self-test-only modes, and the second runs its probes inside the sharded
   recheck. With no caller passing anything but 1, `report()` returns 1; see C43's Landed note.
+- **C44 (A5-5): no file-access option.** The entry has `browser.mjs` add
+  `--allow-file-access-from-files` and state its reason. There is none for these tools: their
+  host page loads both Inter faces without it, and both give the same output, the regenerated
+  table included. At the owner's choice the flag was dropped; CI's `check_dot_fit` step on
+  Linux confirms it on the next push. See C44's Landed note.
 
 ## Found while implementing
 
diff --git a/builder/dot.mjs b/builder/dot.mjs
index 8b349846..74e4b938 100644
--- a/builder/dot.mjs
+++ b/builder/dot.mjs
@@ -131,8 +131,9 @@ async function statSvgFiles(sources, srcRoot) {
 // are skipped for the same reason _config.yml's `exclude` skips them: they
 // hold build output (`_site`, `_site-offline`, `_site-pdf`, `_serve`, `_pdf`)
 // and source that is not itself a page. Walking into `_site*` would also mean
-// rendering each diagram once per output tree.
-async function listDotSources(srcRoot) {
+// rendering each diagram once per output tree. scripts/check_dot_fit.mjs finds
+// the diagrams it checks through this too, so it checks what the build renders.
+export async function listDotSources(srcRoot) {
   const found = [];
   async function walk(dir) {
     let entries;
diff --git a/docs/Documentation/Pipeline-Stages.md b/docs/Documentation/Pipeline-Stages.md
index 4858e514..08da5f34 100644
--- a/docs/Documentation/Pipeline-Stages.md
+++ b/docs/Documentation/Pipeline-Stages.md
@@ -638,6 +638,7 @@ Runs two build-aborting integrity checks before building the tree: `validatePerm
 | Symbol | Signature | Description |
 |---|---|---|
 | `regenerateDot` | `(srcRoot) → Promise<{ processed, regenerated, failed, setupSkipped?, svgFiles }>` | Regenerates stale `.dot` → `.svg` via the WASM build of Graphviz (`@hpcc-js/wasm-graphviz`). `svgFiles` is the appendable static-file descriptor list. |
+| `listDotSources` | `(srcRoot) → Promise<string[]>` | Every `.dot` under `srcRoot` at any depth, sorted, each path joined onto `srcRoot`, skipping entries whose names start with `_` or `.`. `scripts/check_dot_fit.mjs` finds the diagrams it checks through it. |
 
 ### `scss.mjs`
 
diff --git a/scripts/build_dot_metrics.mjs b/scripts/build_dot_metrics.mjs
index dc437d1d..f949ed4d 100644
--- a/scripts/build_dot_metrics.mjs
+++ b/scripts/build_dot_metrics.mjs
@@ -33,9 +33,10 @@
 
 import { promises as fs } from "node:fs";
 import path from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
-import puppeteer from "puppeteer";
+import { fileURLToPath } from "node:url";
+import { withBrowser } from "./lib/browser.mjs";
 import { exitOnCrash } from "./lib/gate-probes.mjs";
+import { openInterPage } from "./lib/inter-page.mjs";
 
 // A crash exits 2, where 1 is --check finding the table stale.
 exitOnCrash();
@@ -58,33 +59,10 @@ const VARIANTS = [
 
 const check = process.argv.includes("--check");
 
-const fontDirUrl = pathToFileURL(path.join(REPO, "docs/assets/fonts")).href;
-const hostHtml = `<!doctype html><meta charset="utf-8"><title>metrics</title><style>
-@font-face{font-family:"Inter";font-style:normal;font-weight:100 900;
-  src:url("${fontDirUrl}/inter-variable.woff2") format("woff2")}
-@font-face{font-family:"Inter";font-style:italic;font-weight:100 900;
-  src:url("${fontDirUrl}/inter-variable-italic.woff2") format("woff2")}
-body{margin:0}</style>`;
+const table = await withBrowser(async (browser) => {
+  const page = await openInterPage(browser, "dot-metrics", { css: "body{margin:0}" });
 
-const browser = await puppeteer.launch({
-  headless: true,
-  args: ["--no-sandbox", "--disable-dev-shm-usage", "--allow-file-access-from-files"],
-});
-
-let table;
-try {
-  const page = await browser.newPage();
-  page.on("pageerror", (e) => console.error("[page error]", e.message));
-
-  const tmp = path.join(REPO, "docs", "_dot-metrics-host.html");
-  await fs.writeFile(tmp, hostHtml, "utf8");
-  try {
-    await page.goto(pathToFileURL(tmp).href, { waitUntil: "load" });
-  } finally {
-    await fs.rm(tmp, { force: true });
-  }
-
-  table = await page.evaluate(async (variants, upm) => {
+  return await page.evaluate(async (variants, upm) => {
     for (const v of variants) {
       await document.fonts.load(`${v.style === "italic" ? "italic " : ""}${v.weight} 16px Inter`);
     }
@@ -121,9 +99,7 @@ try {
     }
     return { unitsPerEm: upm, widths: out, probe: Math.round(big) };
   }, VARIANTS, UNITS_PER_EM);
-} finally {
-  await browser.close();
-}
+});
 
 for (const v of VARIANTS) {
   const arr = table.widths[v.key];
diff --git a/scripts/check_dot_fit.mjs b/scripts/check_dot_fit.mjs
index 39782b2f..0ef79698 100644
--- a/scripts/check_dot_fit.mjs
+++ b/scripts/check_dot_fit.mjs
@@ -25,9 +25,11 @@
 
 import { promises as fs } from "node:fs";
 import path from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
-import puppeteer from "puppeteer";
+import { fileURLToPath } from "node:url";
+import { listDotSources } from "../builder/dot.mjs";
+import { withBrowser } from "./lib/browser.mjs";
 import { exitOnCrash } from "./lib/gate-probes.mjs";
+import { openInterPage } from "./lib/inter-page.mjs";
 
 exitOnCrash();
 
@@ -44,59 +46,26 @@ const TOLERANCE = 1.0;
 
 const verbose = process.argv.includes("--verbose");
 
-async function findDotSvgs(dir, out = []) {
-  let entries;
-  try {
-    entries = await fs.readdir(dir, { withFileTypes: true });
-  } catch (err) {
-    if (err.code === "ENOENT") return out;
-    throw err;
-  }
-  for (const e of entries) {
-    if (e.name.startsWith("_") || e.name.startsWith(".")) continue;
-    const full = path.join(dir, e.name);
-    if (e.isDirectory()) await findDotSvgs(full, out);
-    else if (e.isFile() && e.name.endsWith(".dot")) {
-      const svg = full.replace(/\.dot$/, ".svg");
-      if (await fs.stat(svg).then(() => true, () => false)) out.push(svg);
-    }
-  }
-  return out;
+// The committed SVG of every diagram the build renders, found as it finds them.
+const svgs = [];
+for (const dot of await listDotSources(SRC)) {
+  const svg = dot.replace(/\.dot$/, ".svg");
+  if (await fs.stat(svg).then(() => true, () => false)) svgs.push(svg);
 }
-
-const svgs = (await findDotSvgs(SRC)).sort();
+svgs.sort();
 if (svgs.length === 0) {
   console.log("check_dot_fit: no DOT diagrams found");
   process.exit(0);
 }
 
-const fontDirUrl = pathToFileURL(path.join(REPO, "docs/assets/fonts")).href;
-const hostHtml = `<!doctype html><meta charset="utf-8"><title>dot fit</title><style>
-@font-face{font-family:"Inter";font-style:normal;font-weight:100 900;
-  src:url("${fontDirUrl}/inter-variable.woff2") format("woff2")}
-@font-face{font-family:"Inter";font-style:italic;font-weight:100 900;
-  src:url("${fontDirUrl}/inter-variable-italic.woff2") format("woff2")}
-body{font-family:Inter,system-ui,sans-serif;margin:0}
-#host{width:1200px}#host svg{width:1200px;height:auto}</style><div id="host"></div>`;
-
-const browser = await puppeteer.launch({
-  headless: true,
-  args: ["--no-sandbox", "--disable-dev-shm-usage", "--allow-file-access-from-files"],
-});
-
 let failures = 0;
 let checked = 0;
-try {
-  const page = await browser.newPage();
-  page.on("pageerror", (e) => console.error("[page error]", e.message));
-
-  const tmp = path.join(SRC, "_dot-fit-host.html");
-  await fs.writeFile(tmp, hostHtml, "utf8");
-  try {
-    await page.goto(pathToFileURL(tmp).href, { waitUntil: "load" });
-  } finally {
-    await fs.rm(tmp, { force: true });
-  }
+await withBrowser(async (browser) => {
+  const page = await openInterPage(browser, "dot-fit", {
+    css: "body{font-family:Inter,system-ui,sans-serif;margin:0}\n" +
+      "#host{width:1200px}#host svg{width:1200px;height:auto}",
+    body: '<div id="host"></div>',
+  });
   await page.evaluate(async () => {
     await Promise.all([
       document.fonts.load("400 12px Inter"),
@@ -175,9 +144,7 @@ try {
       if (verbose) console.log(`               tolerance ${TOLERANCE}`);
     }
   }
-} finally {
-  await browser.close();
-}
+});
 
 if (failures) {
   console.error(
diff --git a/scripts/lib/inter-page.mjs b/scripts/lib/inter-page.mjs
new file mode 100644
index 00000000..607d6f41
--- /dev/null
+++ b/scripts/lib/inter-page.mjs
@@ -0,0 +1,40 @@
+// The page the two diagram tools measure text in, scripts/check_dot_fit.mjs
+// and scripts/build_dot_metrics.mjs: a blank page that paints with the site's
+// own Inter, loaded from docs/assets/fonts.
+//
+// The fonts are file:// URLs, so the page is a file:// page too: it is written
+// to docs/_<name>-host.html, loaded, and removed at once, and the leading
+// underscore keeps a build that runs meanwhile from reading it as source. A
+// face that fails to load rejects the tool's document.fonts.load(), so the
+// tool exits 2 rather than measuring a fallback font.
+
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const DOCS = path.resolve(fileURLToPath(import.meta.url), "../../../docs");
+
+/**
+ * Opens a new page in `browser` with Inter declared, `css` after the
+ * @font-face rules and `body` after the stylesheet, and returns it once loaded.
+ */
+export async function openInterPage(browser, name, { css = "", body = "" } = {}) {
+  const fontDirUrl = pathToFileURL(path.join(DOCS, "assets", "fonts")).href;
+  const html = `<!doctype html><meta charset="utf-8"><title>${name}</title><style>
+@font-face{font-family:"Inter";font-style:normal;font-weight:100 900;
+  src:url("${fontDirUrl}/inter-variable.woff2") format("woff2")}
+@font-face{font-family:"Inter";font-style:italic;font-weight:100 900;
+  src:url("${fontDirUrl}/inter-variable-italic.woff2") format("woff2")}
+${css}</style>${body}`;
+
+  const page = await browser.newPage();
+  page.on("pageerror", (e) => console.error("[page error]", e.message));
+  const host = path.join(DOCS, `_${name}-host.html`);
+  await fs.writeFile(host, html, "utf8");
+  try {
+    await page.goto(pathToFileURL(host).href, { waitUntil: "load" });
+  } finally {
+    await fs.rm(host, { force: true });
+  }
+  return page;
+}

From 050b5081ebb7aa3e5635e2dde572532eae718023 Mon Sep 17 00:00:00 2001
From: Kuba Sunderland-Ober <kuba@mareimbrium.org>
Date: Sun, 27 Sep 2026 17:10:34 +0200
Subject: [PATCH 22/27] a11y: one page discovery and stub ceiling for the
 sampler and the sweep

---
 builder/PLAN-TOOLING-REVIEW.md | 18 ++++++++++
 builder/PLAN-checks.md         |  5 +--
 docs/Documentation/Tools.md    |  2 +-
 scripts/lib/axe-scan.mjs       | 66 ++++++++++++++++++++++++++++++++--
 scripts/pick_a11y_sample.mjs   | 49 ++++++-------------------
 scripts/sweep_a11y.mjs         | 56 +++++------------------------
 6 files changed, 104 insertions(+), 92 deletions(-)

diff --git a/builder/PLAN-TOOLING-REVIEW.md b/builder/PLAN-TOOLING-REVIEW.md
index 8d1f87a4..4521c81b 100644
--- a/builder/PLAN-TOOLING-REVIEW.md
+++ b/builder/PLAN-TOOLING-REVIEW.md
@@ -1308,6 +1308,24 @@ import.
 **Verify.** `pick_a11y_sample.mjs --census` and `--propose` output unchanged; a sweep over two
 pages writes records of the same shape.
 
+**Landed.** `axe-scan.mjs` gains a page-discovery section: `STUB_TAG_CEILING` (the sweep's
+name; the sampler's `STUB_CEILING` goes), `staticTagCount`, `discoverPages(dir, fields)`,
+`splitStubs(pages)` returning `{ content, stubs }`, `pad` and `median`. `discoverPages` reads
+each page once and returns `{ filePath, tags, ...fields(html) }` sorted by `localeCompare`, as
+the sweep did; the sampler passes its family counts as `fields` (`raw`), so it still reads each
+page once, and its pages now come sorted where they came in `readdir` order. The two stub
+comments are merged into the ceiling's, in the present tense. Tools.md's `axe-scan.mjs`
+section names the shared discovery, and, at the owner's choice, all five scripts that import
+the module (it named three, leaving out `pick_a11y_sample.mjs` and `check_axe_patch_equiv.mjs`,
+a Found-in-passing item). `builder/PLAN-checks.md`'s open question cites the new name.
+
+Oracle: the kit's `c45-oracle.mjs before|after|compare`: `pick_a11y_sample --census`,
+`--propose` (over a copy of `perf/results/a11y-sweep.jsonl`, 3,476 records) and `--check`;
+`sweep_a11y --report` over the same copy; and a sweep of the first two `/tB/Core/A` pages,
+light and desktop, into a fresh JSONL. The sampler's three runs and the report are identical,
+so its new page order changed no tie. The two-page sweep writes the same records, `runMs`
+masked, and its output differs only in the per-page time column.
+
 ### C46 — `lib: one repository root for every tool`
 
 **L2-5 (R2).** Nineteen files derive the repository root inline, in about five different
diff --git a/builder/PLAN-checks.md b/builder/PLAN-checks.md
index 5a6d1e48..756f60af 100644
--- a/builder/PLAN-checks.md
+++ b/builder/PLAN-checks.md
@@ -786,8 +786,9 @@ graph. Three ways out, in rough order of preference:
 
 - Redirect stubs are counted out of the census (869 content pages, 290 stubs)
   but are written by `writeRedirects` inside `writeAux`, not by `flush` — so
-  the exclusion has to be deliberate rather than incidental. `STUB_CEILING`
-  (100) is the script's own heuristic for this; check whether the fused path
+  the exclusion has to be deliberate rather than incidental.
+  `STUB_TAG_CEILING` (100, in `scripts/lib/axe-scan.mjs`) is the a11y scripts'
+  own heuristic for this; check whether the fused path
   needs it at all, given the build knows exactly which pages are stubs.
 - `ANCHORS` pins `/index.html` and `/404.html` in the sample "for a reason the
   construct census cannot see". Nothing in the fused path should be able to
diff --git a/docs/Documentation/Tools.md b/docs/Documentation/Tools.md
index 9714b451..e9ade6a7 100644
--- a/docs/Documentation/Tools.md
+++ b/docs/Documentation/Tools.md
@@ -356,7 +356,7 @@ The fixtures have their own document, and it is the one to read before editing t
 ### axe-scan.mjs
 {: #axe-scan }
 
-Not a command --- `scripts/lib/axe-scan.mjs` is the shared module that **defines** the accessibility scan, imported by [`check_a11y.mjs`](#check-a11y), [`sweep_a11y.mjs`](#sweep-a11y) and [`check_a11y_fingerprint.mjs`](#check-a11y-fingerprint). It holds `SAMPLE_PAGES`, `THEMES`, `VIEWPORTS`, `STATE_AUDITS`, `BLOCKED_REQUESTS`, `AXE_RUN_OPTIONS`, `SOURCE_PATCHES` and the `SCHEMES` registry, plus the `runMatrix` / `buildMatrix` drivers. Any change to *what the scan runs* belongs here, and most of them must go through the [fingerprint gate](#check-a11y-fingerprint) first. **`SAMPLE_PAGES` is the exception, and it is the constant most often edited**: the gate compares a candidate against a baseline produced by the same page set, so a change to *which* pages are walked is its documented blind spot, and a green run there vouches for nothing. Argue that one from source, run [`sweep_a11y.mjs`](#sweep-a11y) once, and use the gate's A/A control (`--baseline production --candidate production`) only to show the matrix is still deterministic.
+Not a command --- `scripts/lib/axe-scan.mjs` is the shared module that **defines** the accessibility scan, imported by [`check_a11y.mjs`](#check-a11y), [`pick_a11y_sample.mjs`](#pick-a11y-sample), [`sweep_a11y.mjs`](#sweep-a11y), [`check_a11y_fingerprint.mjs`](#check-a11y-fingerprint) and [`check_axe_patch_equiv.mjs`](#check-axe-patch-equiv). It holds `SAMPLE_PAGES`, `THEMES`, `VIEWPORTS`, `STATE_AUDITS`, `BLOCKED_REQUESTS`, `AXE_RUN_OPTIONS`, `SOURCE_PATCHES` and the `SCHEMES` registry, plus the `runMatrix` / `buildMatrix` drivers, and the page discovery the sampler and the sweep share: `discoverPages`, and `STUB_TAG_CEILING`, below which a page is a redirect stub neither of them audits. Any change to *what the scan runs* belongs here, and most of them must go through the [fingerprint gate](#check-a11y-fingerprint) first. **`SAMPLE_PAGES` is the exception, and it is the constant most often edited**: the gate compares a candidate against a baseline produced by the same page set, so a change to *which* pages are walked is its documented blind spot, and a green run there vouches for nothing. Argue that one from source, run [`sweep_a11y.mjs`](#sweep-a11y) once, and use the gate's A/A control (`--baseline production --candidate production`) only to show the matrix is still deterministic.
 
 `STATE_AUDITS` deserves a note: a closed `<details>` subtree is `notRendered`, so axe never walks it. Entries here are layered onto the page × theme × viewport matrix and apply a DOM mutation from `PAGE_STATES` before the audit, which is how the section-links disclosure gets audited open as well as closed. **Every `PAGE_STATES` function must assert it found what it expected** --- a state that silently does nothing degrades into a second audit of the default page: slower, still green, covering nothing.
 
diff --git a/scripts/lib/axe-scan.mjs b/scripts/lib/axe-scan.mjs
index 46a0c9ac..fad4328e 100644
--- a/scripts/lib/axe-scan.mjs
+++ b/scripts/lib/axe-scan.mjs
@@ -15,8 +15,8 @@
 //
 // See builder/PLAN-axe-perf.md for why each knob below is a knob.
 
-import { readFileSync } from "node:fs";
-import { resolve, join } from "node:path";
+import { readdirSync, readFileSync } from "node:fs";
+import { resolve, join, relative, sep } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
 // This module lives at <repo>/scripts/lib/axe-scan.mjs.  Anchoring the built
@@ -860,3 +860,65 @@ export function fingerprint({ filePath, theme, viewport, state, results }) {
     `|I[${fmtIncomplete(results.incomplete)}]`
   );
 }
+
+// ---------------------------------------------------------------------------
+// Page discovery -- the pages pick_a11y_sample.mjs and sweep_a11y.mjs see
+// ---------------------------------------------------------------------------
+
+// Pages below this static start-tag count are redirect stubs -- a canonical
+// link, a meta refresh, `<script>location=...</script>` and a one-line body.
+// There are ~290 of them, and neither tool audits them, because they cannot be
+// audited: the inline script navigates before the audit runs, so what axe
+// walks is the redirect *target*.  The stub for /CustomControls.html reports
+// the same 2,221 elements as /Tutorials/CustomControls/index.html.  One
+// ceiling serves both tools, since pick_a11y_sample.mjs --propose reads the
+// records the sweep writes.
+export const STUB_TAG_CEILING = 100;
+
+// Static start-tag count.  Not the element count axe sees -- it misses what
+// scripts add and counts what parsing drops -- but it ranks pages correctly
+// and costs no browser, which is all it is used for: separating stubs from
+// content before any audit starts.
+export function staticTagCount(html) {
+  const m = html.match(/<[a-zA-Z][a-zA-Z0-9-]*(\s|>|\/)/g);
+  return m ? m.length : 0;
+}
+
+/**
+ * Every .html page under the built tree `dir`, sorted by path, as
+ * `{ filePath, tags, ...fields(html) }`: `filePath` is root-relative with a
+ * leading slash, and `fields`, when given, adds what the caller counts in the
+ * same read of the page.
+ */
+export function discoverPages(dir, fields = () => ({})) {
+  const out = [];
+  (function walk(d) {
+    for (const e of readdirSync(d, { withFileTypes: true })) {
+      const p = join(d, e.name);
+      if (e.isDirectory()) walk(p);
+      else if (e.name.endsWith(".html")) out.push(p);
+    }
+  })(dir);
+  return out
+    .map((p) => {
+      const html = readFileSync(p, "utf8");
+      return { filePath: "/" + relative(dir, p).split(sep).join("/"), tags: staticTagCount(html), ...fields(html) };
+    })
+    .sort((a, b) => a.filePath.localeCompare(b.filePath));
+}
+
+/** `pages` split at the stub ceiling: `{ content, stubs }`, each in order. */
+export function splitStubs(pages) {
+  return {
+    content: pages.filter((p) => p.tags >= STUB_TAG_CEILING),
+    stubs: pages.filter((p) => p.tags < STUB_TAG_CEILING),
+  };
+}
+
+// The two tools' report helpers.
+export const pad = (s, w) => String(s).padStart(w);
+
+export const median = (xs) => {
+  const s = [...xs].sort((a, b) => a - b);
+  return s.length % 2 ? s[(s.length - 1) / 2] : (s[s.length / 2 - 1] + s[s.length / 2]) / 2;
+};
diff --git a/scripts/pick_a11y_sample.mjs b/scripts/pick_a11y_sample.mjs
index 86b0df09..aad6e38e 100644
--- a/scripts/pick_a11y_sample.mjs
+++ b/scripts/pick_a11y_sample.mjs
@@ -42,9 +42,11 @@
 //   --root-dir DIR   tree to take the census from (default docs/_site-offline)
 //   --budget MS      audit-time budget --propose may spend on the sample
 
-import { readdirSync, readFileSync, existsSync } from "node:fs";
+import { readFileSync, existsSync } from "node:fs";
 import { resolve, join, relative, sep } from "node:path";
-import { DEFAULT_ROOT_DIR, REPO_ROOT, SAMPLE_PAGES } from "./lib/axe-scan.mjs";
+import {
+  DEFAULT_ROOT_DIR, REPO_ROOT, SAMPLE_PAGES, discoverPages, median, pad, splitStubs,
+} from "./lib/axe-scan.mjs";
 import { exitOnCrash } from "./lib/gate-probes.mjs";
 
 // A crash exits 2, where 1 is a coverage gap.
@@ -119,12 +121,6 @@ const ANCHORS = {
   "/404.html": "the error layout, and the site's cheapest real page",
 };
 
-// Redirect stubs (~290 of them) are excluded, and cannot be included: each
-// carries `<script>location=...</script>`, so the browser has navigated to the
-// target before the audit runs and what axe walks is the target page.  Putting
-// one in the sample buys a silent duplicate audit, not a new layout.
-const STUB_CEILING = 100;
-
 // ---------------------------------------------------------------------------
 // CLI
 // ---------------------------------------------------------------------------
@@ -160,33 +156,14 @@ rootDir = resolve(rootDir);
 // Scan the built tree
 // ---------------------------------------------------------------------------
 
-function discover(dir) {
-  const out = [];
-  (function walk(d) {
-    for (const e of readdirSync(d, { withFileTypes: true })) {
-      const p = join(d, e.name);
-      if (e.isDirectory()) walk(p);
-      else if (e.name.endsWith(".html")) out.push(p);
-    }
-  })(dir);
-  return out;
-}
-
 const count = (html, re) => (html.match(re) || []).length;
 
-const pages = discover(rootDir).map((p) => {
-  const html = readFileSync(p, "utf8");
-  const row = {
-    filePath: "/" + relative(rootDir, p).split(sep).join("/"),
-    tags: count(html, /<[a-zA-Z][a-zA-Z0-9-]*(\s|>|\/)/g),
-    raw: {},
-  };
-  for (const [name, f] of Object.entries(FAMILIES)) row.raw[name] = count(html, f.re);
-  return row;
-});
-
-const content = pages.filter((p) => p.tags >= STUB_CEILING);
-const stubs = pages.filter((p) => p.tags < STUB_CEILING);
+// Redirect stubs are left out: a stub in the sample would audit its target
+// again, not a new layout (STUB_TAG_CEILING in axe-scan.mjs says why).
+const pages = discoverPages(rootDir, (html) => ({
+  raw: Object.fromEntries(Object.entries(FAMILIES).map(([name, f]) => [name, count(html, f.re)])),
+}));
+const { content, stubs } = splitStubs(pages);
 
 if (content.length === 0) {
   console.error(`no content pages under ${rootDir} -- has build.bat run?`);
@@ -230,10 +207,6 @@ if (existsSync(sweepPath)) {
     }
   }
 }
-const median = (xs) => {
-  const s = [...xs].sort((a, b) => a - b);
-  return s.length % 2 ? s[(s.length - 1) / 2] : (s[s.length / 2 - 1] + s[s.length / 2]) / 2;
-};
 
 // Anchor the fitted curve on the sweep's own median page when there is one, so
 // modelled and measured costs are on the same scale.
@@ -260,8 +233,6 @@ const costSource = measured.size
 // Modes
 // ---------------------------------------------------------------------------
 
-const pad = (s, w) => String(s).padStart(w);
-
 if (mode === "census") {
   console.log(`construct census over ${content.length} content pages (+${stubs.length} redirect stubs)`);
   console.log(`cost: ${costSource}`);
diff --git a/scripts/sweep_a11y.mjs b/scripts/sweep_a11y.mjs
index 43f8d9eb..8e72bc58 100644
--- a/scripts/sweep_a11y.mjs
+++ b/scripts/sweep_a11y.mjs
@@ -38,25 +38,28 @@
 // Requires build.bat to have produced an up-to-date docs/_site-offline/.
 
 import {
-  readdirSync,
   readFileSync,
   appendFileSync,
   existsSync,
   mkdirSync,
 } from "node:fs";
-import { resolve, join, relative, sep, dirname } from "node:path";
+import { resolve, join, dirname } from "node:path";
 import {
   axeVersion,
   DEFAULT_ROOT_DIR,
   REPO_ROOT,
   THEMES,
   VIEWPORTS,
+  discoverPages,
   getScheme,
   gotoPage,
+  median,
   newAuditPage,
+  pad,
   pick,
   readAxeSource,
   runAxe,
+  splitStubs,
 } from "./lib/axe-scan.mjs";
 import { withBrowser } from "./lib/browser.mjs";
 
@@ -67,17 +70,6 @@ import { withBrowser } from "./lib/browser.mjs";
 const PRODUCTION = getScheme("production");
 const AXE_PATCHES = PRODUCTION.patches;
 
-// Pages below this tag count are redirect stubs -- a canonical link, a meta
-// refresh, `<script>location=...</script>` and a one-line body.  There are ~290
-// of them and they are excluded outright, for a better reason than cost: they
-// cannot be audited.  The inline script navigates before the audit runs, so
-// what axe walks is the redirect *target*.  An earlier version of this script
-// sampled three of them and produced three exact duplicates of other pages'
-// results -- the stub for /CustomControls.html reported the same 2,221
-// elements as /Tutorials/CustomControls/index.html.  A page nobody sees for
-// longer than 0 ms is not a page to audit.
-const STUB_TAG_CEILING = 100;
-
 const args = process.argv.slice(2);
 let rootDir = DEFAULT_ROOT_DIR;
 let themeArg = "both";
@@ -123,35 +115,9 @@ const viewports = pick("viewport", viewportArg, Object.keys(VIEWPORTS));
 
 // ---- page discovery ---------------------------------------------------
 
-// Static start-tag count.  Not the element count axe sees -- it misses what
-// scripts add and counts what parsing drops -- but it ranks pages correctly
-// and costs no browser, which is all it is used for here: separating stubs
-// from content before the sweep starts.
-function staticTagCount(html) {
-  const m = html.match(/<[a-zA-Z][a-zA-Z0-9-]*(\s|>|\/)/g);
-  return m ? m.length : 0;
-}
-
-function discoverPages(dir) {
-  const out = [];
-  (function walk(d) {
-    for (const e of readdirSync(d, { withFileTypes: true })) {
-      const p = join(d, e.name);
-      if (e.isDirectory()) walk(p);
-      else if (e.name.endsWith(".html")) out.push(p);
-    }
-  })(dir);
-  return out
-    .map((p) => ({
-      filePath: "/" + relative(dir, p).split(sep).join("/"),
-      tags: staticTagCount(readFileSync(p, "utf8")),
-    }))
-    .sort((a, b) => a.filePath.localeCompare(b.filePath));
-}
-
-const allPages = discoverPages(rootDir);
-const stubs = allPages.filter((p) => p.tags < STUB_TAG_CEILING);
-const content = allPages.filter((p) => p.tags >= STUB_TAG_CEILING);
+// Redirect stubs are left out, for a better reason than cost: they cannot be
+// audited (STUB_TAG_CEILING in axe-scan.mjs says why).
+const { content, stubs } = splitStubs(discoverPages(rootDir));
 
 let selected = content;
 if (filter) selected = selected.filter((p) => p.filePath.includes(filter));
@@ -274,12 +240,6 @@ if (!reportOnly && matrix.length) {
 
 // ---- report -----------------------------------------------------------
 
-const pad = (s, w) => String(s).padStart(w);
-const median = (xs) => {
-  const s = [...xs].sort((a, b) => a - b);
-  return s.length % 2 ? s[(s.length - 1) / 2] : (s[s.length / 2 - 1] + s[s.length / 2]) / 2;
-};
-
 console.log("");
 console.log(`=== a11y sweep: ${records.length} audits ===`);
 console.log("");

From 6eba7c33dc14fb2c0567acab67090a5c39984eb0 Mon Sep 17 00:00:00 2001
From: Kuba Sunderland-Ober <kuba@mareimbrium.org>
Date: Sun, 27 Sep 2026 17:37:58 +0200
Subject: [PATCH 23/27] lib: one repository root for every tool

---
 WIP.md                                 |  2 +-
 builder/PLAN-TOOLING-REVIEW.md         | 38 ++++++++++++++++++++++++++
 builder/tbdocs.mjs                     |  7 ++---
 builder/write.mjs                      |  4 +--
 docs/Documentation/Extending.md        |  2 +-
 eval/build_corpus.mjs                  |  4 +--
 eval/nav_hops.mjs                      |  4 +--
 eval/run_case.mjs                      |  3 +-
 eval/site_search.mjs                   |  3 +-
 lib/README.md                          |  3 ++
 lib/repo-paths.mjs                     | 15 ++++++++++
 scripts/addin_test.mjs                 |  8 +++---
 scripts/build_dot_metrics.mjs          |  7 ++---
 scripts/build_package_api.mjs          | 11 ++++----
 scripts/census_attributes.mjs          |  4 +--
 scripts/check_ci_workflows.mjs         |  6 ++--
 scripts/check_code_regions.mjs         |  9 ++----
 scripts/check_dot_fit.mjs              |  9 ++----
 scripts/check_examples.mjs             | 12 ++++----
 scripts/check_gate_lists.mjs           | 11 ++++----
 scripts/check_links_diff.mjs           |  3 +-
 scripts/check_lint.mjs                 | 10 +++----
 scripts/check_regex_safety.mjs         |  9 +++---
 scripts/check_tree_fresh.mjs           |  4 +--
 scripts/compare_trees.mjs              |  9 +++---
 scripts/convert_em_dash_separators.mjs | 10 +++----
 scripts/gen_attribute_probes.mjs       |  7 ++---
 scripts/lib/axe-scan.mjs               | 21 +++++++-------
 scripts/lib/inter-page.mjs             |  9 +++---
 scripts/survey_tooling.mjs             |  4 +--
 wisdom/extract/prep.mjs                |  4 +--
 31 files changed, 139 insertions(+), 113 deletions(-)
 create mode 100644 lib/repo-paths.mjs

diff --git a/WIP.md b/WIP.md
index 071e5dfe..af6b5020 100644
--- a/WIP.md
+++ b/WIP.md
@@ -469,7 +469,7 @@ build.bat && check.bat
 
 On the dev box that is ~4 s of build against ~37 s of check, of which the axe scan is ~20 s. [builder/PLAN-checks.md](builder/PLAN-checks.md) records how the link checker got folded into the build's task graph, what it cost and what it saved; the axe follow-ons are designed there but not implemented.
 
-**If the change touched `builder/`, `scripts/`, `lib/`, `book/`, `eval/`, `wisdom/`, `test/`, the site's scripts in `docs/assets/js/`, a wrapper or a workflow, run `test.bat` as well** --- another ~8 s. Seven of its ten gates cannot be affected by an edit under `docs/` at all. **Three can.** `check_lint.mjs` lints the site's two scripts in `docs/assets/js/` along with the tooling. `check_gate_lists.mjs` is the easy one to predict: it reads `README.md` and every page under `docs/Documentation/`, so an edit to any developer page that states a gate count can fail it. **`check_code_regions.mjs` is the one worth understanding**, and which half of it a content edit reaches is worth keeping straight. Its corpus sweep has `ROOT = <repo>/docs` and tokenises all 906 markdown files, so a page that provokes a rewrite into *altering* a code region fails it --- that half is content-dependent. Its fixed probes are not: they run against their own sources whatever the tree holds, and they cover the **mirror** fault, where a rewrite silently stops firing. The sweep structurally cannot see that one, because text the rewrite skipped is stashed and restored unchanged and every region still matches. So run `test.bat` after adding an unusual code construct --- a fence whose contents include a fence marker, a 4-space indented block, an admonition wrapping a fence --- and read the built page as well, because for the mirror fault the gate is asserting that the stasher still works rather than checking your page:
+**If the change touched `builder/`, `scripts/`, `lib/`, `book/`, `eval/`, `wisdom/`, `test/`, the site's scripts in `docs/assets/js/`, a wrapper or a workflow, run `test.bat` as well** --- another ~8 s. Seven of its ten gates cannot be affected by an edit under `docs/` at all. **Three can.** `check_lint.mjs` lints the site's two scripts in `docs/assets/js/` along with the tooling. `check_gate_lists.mjs` is the easy one to predict: it reads `README.md` and every page under `docs/Documentation/`, so an edit to any developer page that states a gate count can fail it. **`check_code_regions.mjs` is the one worth understanding**, and which half of it a content edit reaches is worth keeping straight. Its corpus sweep reads `DOCS_DIR`, which is `<repo>/docs`, and tokenises all 906 markdown files, so a page that provokes a rewrite into *altering* a code region fails it --- that half is content-dependent. Its fixed probes are not: they run against their own sources whatever the tree holds, and they cover the **mirror** fault, where a rewrite silently stops firing. The sweep structurally cannot see that one, because text the rewrite skipped is stashed and restored unchanged and every region still matches. So run `test.bat` after adding an unusual code construct --- a fence whose contents include a fence marker, a 4-space indented block, an admonition wrapping a fence --- and read the built page as well, because for the mirror fault the gate is asserting that the stasher still works rather than checking your page:
 
 ```sh
 build.bat && check.bat && test.bat
diff --git a/builder/PLAN-TOOLING-REVIEW.md b/builder/PLAN-TOOLING-REVIEW.md
index 4521c81b..856c5648 100644
--- a/builder/PLAN-TOOLING-REVIEW.md
+++ b/builder/PLAN-TOOLING-REVIEW.md
@@ -1340,6 +1340,44 @@ convention as it now is.
 **Verify.** The tree comparison identical; `test.bat` and `check.bat` clean;
 `check_examples.mjs --census`, and each `eval/` and `wisdom/` tool's cheapest mode, unchanged.
 
+**Landed.** `lib/repo-paths.mjs` exports `REPO_ROOT`, from its own URL, and `DOCS_DIR`, the
+one path several tools built from it; every other path built from the root is built by one or
+two tools and stays with them. Twenty-six files take the two from it: the review's nineteen;
+`check_regex_safety.mjs`, which was there at `fe9ce12b` and missing from the count;
+`check_ci_workflows.mjs`, `check_lint.mjs`, `compare_trees.mjs` and `survey_tooling.mjs`,
+added since, the last keeping its own `ROOT`, now `--root` or `REPO_ROOT`; `inter-page.mjs`
+(C44); and `axe-scan.mjs`, which imports the root and re-exports it with `export { REPO_ROOT
+}` for `pick_a11y_sample.mjs` and `sweep_a11y.mjs`, whose imports are unchanged. Local names
+follow the exports: `REPO`, `ROOT` and `PROJECT_ROOT` become `REPO_ROOT`; the docs folder's
+`ROOT` (`check_code_regions.mjs`, `convert_em_dash_separators.mjs`), `SRC` (`check_dot_fit.mjs`)
+and `DOCS` (`check_examples.mjs`, `inter-page.mjs`) become `DOCS_DIR`; and
+`gen_attribute_probes.mjs`'s `DOCS`, which held `Attributes.md`'s path, becomes `ATTR_DOC`, as
+in `census_attributes.mjs`. Left alone: `perf/`, outside the review's scope; `impexp.mjs`'s
+self-test path to `indexer/`, since the script is a download that must stand alone;
+`check_publish_policy.mjs`'s working-directory `docs` default, a behaviour change, which
+Extending.md names as the one gate that does not; and paths relative to a module that are not
+the root (Wisdom's data folders, `builder/`'s vendored assets, `test/addin/`'s `HERE`).
+Extending.md states the convention as it now is, `lib/README.md` names the module, and
+WIP.md's sentence on `check_code_regions`' sweep names `DOCS_DIR`. The mechanical edit was a
+Sonnet agent's (177 calls, ~207k, 12 min), reviewed line by line.
+
+Oracle: the kit's `c46-oracle.mjs` takes each of the 32 root and docs constants HEAD defined
+in the 26 files, evaluates it as HEAD wrote it for that file's own URL, and compares it with
+the exports: all 32 equal, byte for byte (the two `Attributes.md` paths as `DOCS_DIR` plus
+`\Reference\Attributes.md`). `c46-tools.mjs` runs each touched tool's cheapest mode from a
+HEAD worktree and from the working tree, both roots masked: `check_examples --census`,
+`nav_hops`, `site_search --site`, `run_case --prompt-only` over a `build_corpus` corpus,
+`survey_tooling --summary` (each tree measured by both scripts), `gen_attribute_probes` (135
+files) and `convert_em_dash_separators --check` give the same exit and output, and
+`site_search`'s default `--site` answers as the explicit one does. `build_corpus`'s corpus
+differs only in the three files this commit changes and in untracked local output that the
+worktree lacks; it holds `wisdom/.token` as the stub every unlisted file type gets, not the
+token. Wisdom's prep step, the kit's `c41-prep.mjs`, writes the same files. The tree
+comparison differs only in Extending.md's page, online and offline, the search index and
+`book.html`. Not run: `addin_test`, `build_dot_metrics`, `build_package_api`,
+`census_attributes` and `check_links_diff`, whose changed lines are the constants above; Biome's
+`noUndeclaredVariables` over the 26 files names none of the renamed identifiers.
+
 *Command lines (decision (e)): C47–C52.*
 
 ### C47 — `lib: cli.mjs on node:util parseArgs, and check_cli.mjs`
diff --git a/builder/tbdocs.mjs b/builder/tbdocs.mjs
index b19382f0..7e64c2fb 100644
--- a/builder/tbdocs.mjs
+++ b/builder/tbdocs.mjs
@@ -38,6 +38,8 @@ import { fileURLToPath } from "node:url";
 import yaml from "js-yaml";
 import pc   from "picocolors";
 
+import { REPO_ROOT } from "../lib/repo-paths.mjs";
+
 import { WorkerPool } from "./worker-pool.mjs";
 import { Scheduler }  from "./scheduler.mjs";
 import { renderGantt } from "./gantt.mjs";
@@ -87,11 +89,6 @@ import {
 const CPU_WORKER_URL = new URL("./cpu-worker.mjs", import.meta.url);
 const PACKAGE_API_PATH = new URL("./package-api.json", import.meta.url);
 
-// builder/ sits one level under the repository root. Used to state a build's
-// source root the same way however it was invoked, for the page-count drift
-// guard -- see page-baseline.mjs.
-const REPO_ROOT = path.resolve(fileURLToPath(new URL("..", import.meta.url)));
-
 // A command-line error, which main() reports by its message alone and exits 4
 // on: a value outside the 1/2/3 of the link and integrity checks, so a mistyped
 // flag never reads as a broken link. write.mjs marks its --dest refusal the same.
diff --git a/builder/write.mjs b/builder/write.mjs
index b8db021f..46e932f2 100644
--- a/builder/write.mjs
+++ b/builder/write.mjs
@@ -19,6 +19,7 @@ import { promises as fs } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { isOutputTree, OUTPUT_TREES } from "../lib/markdown-files.mjs";
+import { REPO_ROOT } from "../lib/repo-paths.mjs";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -26,7 +27,6 @@ const __dirname = path.dirname(__filename);
 // Everything else the site serves under /assets/ now comes from docs/assets/
 // (handled by the static-file copy in copyStaticFiles).
 const BUILDER_ASSETS = path.join(__dirname, "vendor", "just-the-docs", "assets");
-const PROJECT_ROOT = path.resolve(__dirname, "..");
 const LIMIT = 64;
 
 export const WRITE_LIMIT = LIMIT;
@@ -123,7 +123,7 @@ export async function preparePageDirs(pages, staticFiles, destRoot, offlineRoot)
 }
 
 export function isUnderProject(destRoot) {
-  const rel = path.relative(PROJECT_ROOT, destRoot);
+  const rel = path.relative(REPO_ROOT, destRoot);
   return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel);
 }
 
diff --git a/docs/Documentation/Extending.md b/docs/Documentation/Extending.md
index 948bff0c..03dacd98 100644
--- a/docs/Documentation/Extending.md
+++ b/docs/Documentation/Extending.md
@@ -651,7 +651,7 @@ Separating 1 from 2 is what stops a broken gate reading as a clean site, and it
 
 **Name the artifact and the remedy.** A gate's output is read by someone who was in the middle of something else. `check_dot_fit.mjs` names the failing diagram, then `builder/dot-metrics.mjs` and an `@hpcc-js/wasm-graphviz` bump as the usual cause, then `build.bat` as the fix. `check_tree_fresh.mjs` names the source file that is newer than the tree and says to run `build.bat`. `pick_a11y_sample.mjs --check` names the uncovered construct *and* the cheapest page that would cover it.
 
-**Resolve paths from `import.meta.url`.** `resolve(fileURLToPath(new URL("..", import.meta.url)))` is what nearly all of them do, directly or through `axe-scan.mjs`'s `REPO_ROOT`, and it makes the gate work from any directory. `check_publish_policy.mjs` is the exception, with a working-directory-relative `docs` default, which is why the batch wrappers `pushd` to the repository root before running anything.
+**Resolve paths from the repository root in `lib/repo-paths.mjs`.** Import `REPO_ROOT`, or `DOCS_DIR` for `docs/`, rather than deriving either from `import.meta.url` or the working directory, and the gate works from any directory. `check_publish_policy.mjs` is the one gate that does not, with a working-directory-relative `docs` default, which is why the batch wrappers `pushd` to the repository root before running anything.
 
 **Be explicit about what may already have run.** Both wrappers stop at the first failure, so a gate's position decides what it can assume --- and the two do not offer the same guarantees. `check_tree_fresh.mjs` runs first in `check.bat`, so every later gate there may assume `_site-offline/` is current. `test.bat` has no freshness gate at all, and its one gate that opens a built page does not need one: `check_axe_patch_equiv.mjs` loads a single page and never reads that page's DOM, so a stale tree cannot change its result. Nothing in either wrapper may assume the build's own link check passed: a link failure sets the build's exit code without aborting the build, so a tree that failed it is still on disk and still fresh.
 
diff --git a/eval/build_corpus.mjs b/eval/build_corpus.mjs
index 03dd94f5..9a31f718 100644
--- a/eval/build_corpus.mjs
+++ b/eval/build_corpus.mjs
@@ -12,13 +12,11 @@
 //
 // See eval/README.md for how a round uses it.
 
-import { fileURLToPath } from "node:url";
 import fs from "node:fs";
 import path from "node:path";
 
 import { isOutputTree } from "../lib/markdown-files.mjs";
-
-const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+import { REPO_ROOT } from "../lib/repo-paths.mjs";
 
 // ---------------------------------------------------------------------------
 // What stays readable is an ALLOWLIST, and that is the whole design.
diff --git a/eval/nav_hops.mjs b/eval/nav_hops.mjs
index 719d3cbc..e8a4ca8c 100644
--- a/eval/nav_hops.mjs
+++ b/eval/nav_hops.mjs
@@ -31,11 +31,11 @@
 
 import fs from "node:fs";
 import path from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
+import { pathToFileURL } from "node:url";
 import { parseFrontmatter } from "../lib/frontmatter.mjs";
 import { blockRegions } from "../lib/markdown.mjs";
+import { REPO_ROOT } from "../lib/repo-paths.mjs";
 
-const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const SITE_HOST = /^https?:\/\/docs\.twinbasic\.com/i;
 
 const USAGE =
diff --git a/eval/run_case.mjs b/eval/run_case.mjs
index 2e99ac92..ba3fc565 100644
--- a/eval/run_case.mjs
+++ b/eval/run_case.mjs
@@ -58,11 +58,10 @@
 import { spawn } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
 import { blockRegions } from "../lib/markdown.mjs";
+import { REPO_ROOT } from "../lib/repo-paths.mjs";
 import { printDigest, readTranscript, summarize } from "./transcript.mjs";
 
-const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const SEARCH_SCRIPT = path.join(REPO_ROOT, "eval", "site_search.mjs");
 const SEARCH_COMMAND = 'site-search "your query here"';
 
diff --git a/eval/site_search.mjs b/eval/site_search.mjs
index d49a6df9..0c01addb 100644
--- a/eval/site_search.mjs
+++ b/eval/site_search.mjs
@@ -17,12 +17,11 @@
 // Requires build.bat (or `node builder/tbdocs.mjs --src docs`) to have run.
 
 import { createRequire } from "node:module";
-import { fileURLToPath } from "node:url";
 import fs from "node:fs";
 import path from "node:path";
+import { REPO_ROOT } from "../lib/repo-paths.mjs";
 
 const require = createRequire(import.meta.url);
-const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 
 function parseArgs(argv) {
   const o = { site: path.join(REPO_ROOT, "docs/_site"), n: 8, terms: [] };
diff --git a/lib/README.md b/lib/README.md
index b2904f17..1c897851 100644
--- a/lib/README.md
+++ b/lib/README.md
@@ -20,6 +20,9 @@ tooling uses, and lists the values left unquoted that end in `#`, since YAML
 reads a `#` after a space as a comment. `scripts/check_code_regions.mjs` carries the probes for both, and
 checks on every page that the block parse finds what a full parse finds.
 
+[repo-paths.mjs](repo-paths.mjs) is where every tool gets the repository root,
+`REPO_ROOT`, and `docs/`, `DOCS_DIR`, so each runs the same from any folder.
+
 `scripts/check_tree_fresh.mjs` counts `lib/` among the inputs that decide the
 built bytes, beside `docs/` and `builder/`, so an edit here marks every built
 tree stale, and `check.bat` and `book.bat` refuse it until the next build.
diff --git a/lib/repo-paths.mjs b/lib/repo-paths.mjs
new file mode 100644
index 00000000..52d76934
--- /dev/null
+++ b/lib/repo-paths.mjs
@@ -0,0 +1,15 @@
+// The repository root, and the paths several tools build from it. Every tool
+// takes them from here rather than from the working directory, so it runs the
+// same from any folder, and a change to the repository's layout is made once.
+//
+// A path a tool is given on its command line still resolves against the
+// working directory, which is what someone typing a relative path expects.
+
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** The repository root: the folder holding `docs/`, `builder/`, `scripts/` and this `lib/`. */
+export const REPO_ROOT = path.resolve(fileURLToPath(new URL("..", import.meta.url)));
+
+/** The documentation source tree, `docs/`, which also holds the build's output trees. */
+export const DOCS_DIR = path.join(REPO_ROOT, "docs");
diff --git a/scripts/addin_test.mjs b/scripts/addin_test.mjs
index 4c6a425a..05e20cf0 100644
--- a/scripts/addin_test.mjs
+++ b/scripts/addin_test.mjs
@@ -52,16 +52,16 @@ import { spawn } from "node:child_process";
 import { existsSync, mkdirSync } from "node:fs";
 import { tmpdir } from "node:os";
 import path from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
+import { pathToFileURL } from "node:url";
 import { removeTree } from "./lib/tb-ide-copy.mjs";
 import { wantShow } from "./lib/tb-ide.mjs";
 import { buildNumber, findIde } from "./lib/tb-install.mjs";
 import { LANE_ENV } from "./lib/tb-lane.mjs";
 import { deleteSettings, finishTidy, ideLists, restoreKeys, SETTINGS_ROOT, settingsKey, snapshotKeys,
          startTidy, subkeyNames, sweepArchitectureMemory } from "./lib/tb-registry.mjs";
+import { REPO_ROOT } from "../lib/repo-paths.mjs";
 
-const REPO = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
-const SUITE = path.join(REPO, "test", "addin");
+const SUITE = path.join(REPO_ROOT, "test", "addin");
 
 const argv = process.argv.slice(2);
 const flag = (n) => argv.includes(`--${n}`);
@@ -168,7 +168,7 @@ function runLane(l) {
     }
     console.log(`  ${l.name}: started on port ${l.port}`);
     const child = spawn(process.execPath, ["--test", "--test-reporter=spec", path.join(SUITE, l.file)], {
-      cwd: REPO, stdio: ["ignore", "pipe", "pipe"], windowsHide: true,
+      cwd: REPO_ROOT, stdio: ["ignore", "pipe", "pipe"], windowsHide: true,
       env: { ...process.env,
              [LANE_ENV]: JSON.stringify({ name: l.name, port: l.port, work: l.work, ide, show }) },
     });
diff --git a/scripts/build_dot_metrics.mjs b/scripts/build_dot_metrics.mjs
index f949ed4d..4c6dd01b 100644
--- a/scripts/build_dot_metrics.mjs
+++ b/scripts/build_dot_metrics.mjs
@@ -33,16 +33,15 @@
 
 import { promises as fs } from "node:fs";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
 import { withBrowser } from "./lib/browser.mjs";
 import { exitOnCrash } from "./lib/gate-probes.mjs";
 import { openInterPage } from "./lib/inter-page.mjs";
+import { REPO_ROOT } from "../lib/repo-paths.mjs";
 
 // A crash exits 2, where 1 is --check finding the table stale.
 exitOnCrash();
 
-const REPO = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
-const OUT = path.join(REPO, "builder", "inter-metrics.json");
+const OUT = path.join(REPO_ROOT, "builder", "inter-metrics.json");
 
 // Graphviz stores widths as `short`, in the family's own em units. The Times
 // family it falls back to declares 2048, and builder/dot-metrics.mjs writes
@@ -119,7 +118,7 @@ const next = JSON.stringify({
 }, null, 1) + "\n";
 
 const prev = await fs.readFile(OUT, "utf8").catch(() => null);
-const rel = path.relative(REPO, OUT).replace(/\\/g, "/");
+const rel = path.relative(REPO_ROOT, OUT).replace(/\\/g, "/");
 if (prev === next) {
   console.log(`  unchanged  ${rel}`);
 } else if (check) {
diff --git a/scripts/build_package_api.mjs b/scripts/build_package_api.mjs
index a96bc043..61b591d1 100644
--- a/scripts/build_package_api.mjs
+++ b/scripts/build_package_api.mjs
@@ -43,13 +43,12 @@
 
 import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
 import { buildNumber, findIde } from "./lib/tb-install.mjs";
 import { defaultCache, exportPackages, packageName } from "./lib/tb-packages.mjs";
 import { apiSnapshot, parsePackage } from "./lib/twin-api.mjs";
+import { REPO_ROOT } from "../lib/repo-paths.mjs";
 
-const REPO = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
-const OUT = path.join(REPO, "builder", "package-api.json");
+const OUT = path.join(REPO_ROOT, "builder", "package-api.json");
 
 const argv = process.argv.slice(2);
 const flag = (n) => argv.includes(`--${n}`);
@@ -182,10 +181,10 @@ for (const u of [...new Set(unresolved)].slice(0, 20)) console.error(`  ? not fo
 const out = opt("out") ?? OUT;
 if (flag("check")) {
   const committed = existsSync(out) ? readFileSync(out, "utf8").replace(/\r\n/g, "\n") : null;
-  if (committed === text) { console.error(`up to date: ${path.relative(REPO, out)}`); process.exit(0); }
-  console.error(`STALE: ${path.relative(REPO, out)} differs from what BETA ${build ?? "?"} gives; ` +
+  if (committed === text) { console.error(`up to date: ${path.relative(REPO_ROOT, out)}`); process.exit(0); }
+  console.error(`STALE: ${path.relative(REPO_ROOT, out)} differs from what BETA ${build ?? "?"} gives; ` +
     `run node scripts/build_package_api.mjs and commit the result`);
   process.exit(1);
 }
 writeFileSync(out, text, "utf8");
-console.error(`wrote   : ${path.relative(REPO, out)} (${(text.length / 1024).toFixed(0)} KB)`);
+console.error(`wrote   : ${path.relative(REPO_ROOT, out)} (${(text.length / 1024).toFixed(0)} KB)`);
diff --git a/scripts/census_attributes.mjs b/scripts/census_attributes.mjs
index 77ec037f..cd7f7211 100644
--- a/scripts/census_attributes.mjs
+++ b/scripts/census_attributes.mjs
@@ -78,9 +78,9 @@ import { fileURLToPath } from "node:url";
 import { parseAttributes } from "./lib/attributes-doc.mjs";
 import { findIde } from "./lib/tb-install.mjs";
 import { defaultCache, exportPackages, packageName } from "./lib/tb-packages.mjs";
+import { DOCS_DIR } from "../lib/repo-paths.mjs";
 
-const REPO = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
-const ATTR_DOC = path.join(REPO, "docs", "Reference", "Attributes.md");
+const ATTR_DOC = path.join(DOCS_DIR, "Reference", "Attributes.md");
 
 const argv = process.argv.slice(2);
 const flag = (n) => argv.includes("--" + n);
diff --git a/scripts/check_ci_workflows.mjs b/scripts/check_ci_workflows.mjs
index 73c0eaf1..78f3bdd9 100644
--- a/scripts/check_ci_workflows.mjs
+++ b/scripts/check_ci_workflows.mjs
@@ -28,14 +28,12 @@
 
 import { readFileSync } from "node:fs";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
 import yaml from "js-yaml";
 import { exitOnCrash } from "./lib/gate-probes.mjs";
 import { buildArgs, gateSteps, workflowSteps } from "./lib/gate-roster.mjs";
+import { REPO_ROOT } from "../lib/repo-paths.mjs";
 
 exitOnCrash();
-
-const ROOT = path.resolve(fileURLToPath(new URL("..", import.meta.url)));
 const JOB = "build";
 const WORKFLOWS = ["checks.yml", "tbdocs-gh-pages.yml"];
 
@@ -301,7 +299,7 @@ if (probeFailures.length) {
 }
 console.log(`check_ci_workflows: ${PROBES.length} probes, all pass`);
 
-const read = (rel) => readFileSync(path.join(ROOT, rel), "utf8");
+const read = (rel) => readFileSync(path.join(REPO_ROOT, rel), "utf8");
 const workflows = {};
 for (const name of WORKFLOWS) workflows[name] = yaml.load(read(`.github/workflows/${name}`));
 // Every local action the workflows use; one that cannot be read is left out,
diff --git a/scripts/check_code_regions.mjs b/scripts/check_code_regions.mjs
index 79f36431..dd6f4cc4 100644
--- a/scripts/check_code_regions.mjs
+++ b/scripts/check_code_regions.mjs
@@ -73,7 +73,6 @@ import assert from "node:assert/strict";
 import { promises as fs } from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
 
 import MarkdownIt from "markdown-it";
 import deflist from "markdown-it-deflist";
@@ -83,11 +82,9 @@ import { applyPreRenderRewrites, createMarkdownIt } from "../builder/render.mjs"
 import { parseFrontmatter, unquotedHashValues } from "../lib/frontmatter.mjs";
 import { blockRegions, mapLines, maskCode, splitCodeSpans, splitOnMarker } from "../lib/markdown.mjs";
 import { markdownFiles } from "../lib/markdown-files.mjs";
+import { DOCS_DIR } from "../lib/repo-paths.mjs";
 import { convertText } from "./convert_em_dash_separators.mjs";
 
-const REPO = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
-const ROOT = path.join(REPO, "docs");
-
 // A bare CommonMark parser: this gate asks what the *source* says is code, so
 // it must not inherit the site's plugin stack (which rewrites content itself).
 const md = new MarkdownIt({ html: true });
@@ -503,11 +500,11 @@ async function main(argv) {
     console.log("ok    1 probe: discover warns about an unquoted value that ends in #");
   }
 
-  const files = await markdownFiles(ROOT);
+  const files = await markdownFiles(DOCS_DIR);
   let touched = 0;
   let fences = 0;
   for (const rel of files) {
-    const src = await fs.readFile(path.join(ROOT, rel), "utf8");
+    const src = await fs.readFile(path.join(DOCS_DIR, rel), "utf8");
     const parsed = parsedRegions(src);
     const found = regionsOf(src);
     fences += parsed.filter((r) => r.startsWith("fence ")).length;
diff --git a/scripts/check_dot_fit.mjs b/scripts/check_dot_fit.mjs
index 0ef79698..b1f1c269 100644
--- a/scripts/check_dot_fit.mjs
+++ b/scripts/check_dot_fit.mjs
@@ -25,17 +25,14 @@
 
 import { promises as fs } from "node:fs";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
 import { listDotSources } from "../builder/dot.mjs";
 import { withBrowser } from "./lib/browser.mjs";
 import { exitOnCrash } from "./lib/gate-probes.mjs";
 import { openInterPage } from "./lib/inter-page.mjs";
+import { DOCS_DIR, REPO_ROOT } from "../lib/repo-paths.mjs";
 
 exitOnCrash();
 
-const REPO = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
-const SRC = path.join(REPO, "docs");
-
 // A label may sit this far past its box edge before it counts as a failure.
 // Kerning is the irreducible part: a per-character table cannot express it,
 // and on the site's labels it makes Graphviz over-estimate by up to 2.8% --
@@ -48,7 +45,7 @@ const verbose = process.argv.includes("--verbose");
 
 // The committed SVG of every diagram the build renders, found as it finds them.
 const svgs = [];
-for (const dot of await listDotSources(SRC)) {
+for (const dot of await listDotSources(DOCS_DIR)) {
   const svg = dot.replace(/\.dot$/, ".svg");
   if (await fs.stat(svg).then(() => true, () => false)) svgs.push(svg);
 }
@@ -77,7 +74,7 @@ await withBrowser(async (browser) => {
   });
 
   for (const svgPath of svgs) {
-    const rel = path.relative(REPO, svgPath).replace(/\\/g, "/");
+    const rel = path.relative(REPO_ROOT, svgPath).replace(/\\/g, "/");
     const svg = await fs.readFile(svgPath, "utf8");
 
     const result = await page.evaluate((markup, tol) => {
diff --git a/scripts/check_examples.mjs b/scripts/check_examples.mjs
index faa7d595..9cba1fca 100644
--- a/scripts/check_examples.mjs
+++ b/scripts/check_examples.mjs
@@ -73,7 +73,6 @@ import {
 } from "node:fs";
 import { tmpdir } from "node:os";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
 
 import { mapLines } from "../lib/markdown.mjs";
 import {
@@ -82,10 +81,9 @@ import {
 } from "./lib/tb-fences.mjs";
 import { buildNumber, compilerExe, findIde, runCompiler } from "./lib/tb-install.mjs";
 import { finishTidy, startTidy } from "./lib/tb-registry.mjs";
+import { DOCS_DIR, REPO_ROOT } from "../lib/repo-paths.mjs";
 
-const REPO = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
-const DOCS = path.join(REPO, "docs");
-const TEMPLATES = path.join(REPO, "test", "example-projects");
+const TEMPLATES = path.join(REPO_ROOT, "test", "example-projects");
 
 // ---------------------------------------------------------------- arguments
 
@@ -615,7 +613,7 @@ function crashedIn(report, map) {
 
 /** Build one staged batch; returns per-fence errors, or a crash marker. */
 async function buildStaged(staged, port) {
-  const args = [path.join(REPO, "scripts", "tbbuild.mjs"), staged.proj,
+  const args = [path.join(REPO_ROOT, "scripts", "tbbuild.mjs"), staged.proj,
     "--port", String(port), "--json"];
   if (IDE) args.push("--ide", IDE);
   if (flag("show")) args.push("--show");
@@ -1151,7 +1149,7 @@ async function applyMarkers(passed) {
   }
   let count = 0;
   for (const [rel, list] of byFile) {
-    const file = path.join(DOCS, rel);
+    const file = path.join(DOCS_DIR, rel);
     const src = await fs.readFile(file, "utf8");
     // Lines are counted as the parse that found the fences counts them, and
     // each keeps its own ending.
@@ -1618,7 +1616,7 @@ async function main() {
     process.exit(0);
   }
 
-  const fences = await collectFences(DOCS);
+  const fences = await collectFences(DOCS_DIR);
   const selected = select(fences);
   checkGroups(fences, selected);
   // Everything that counts as a sample. A resource fence is selected -- it has
diff --git a/scripts/check_gate_lists.mjs b/scripts/check_gate_lists.mjs
index a69696a1..c5c95437 100644
--- a/scripts/check_gate_lists.mjs
+++ b/scripts/check_gate_lists.mjs
@@ -80,12 +80,11 @@
 
 import { readFile, readdir } from "node:fs/promises";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
 import { createMarkdownIt } from "../builder/render.mjs";
 import { splitOnMarker } from "../lib/markdown.mjs";
+import { REPO_ROOT } from "../lib/repo-paths.mjs";
 import { gatesFromBat } from "./lib/gate-roster.mjs";
 
-const REPO = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
 const TOOLS_MD = "docs/Documentation/Tools.md";
 
 // The site's own parser, so that what is code is what the renderer will make
@@ -552,11 +551,11 @@ async function main(argv) {
     return probesFailed.length ? 1 : 0;
   }
 
-  const toolsMd = await readFile(path.join(REPO, TOOLS_MD), "utf8");
+  const toolsMd = await readFile(path.join(REPO_ROOT, TOOLS_MD), "utf8");
   const findings = [];
   const wrapperGates = new Map();
   for (const w of WRAPPERS) {
-    const batSrc = await readFile(path.join(REPO, w.bat), "utf8");
+    const batSrc = await readFile(path.join(REPO_ROOT, w.bat), "utf8");
     wrapperGates.set(w.bat, gatesFromBat(batSrc));
     const found = compareWrapper(w, batSrc, toolsMd);
     findings.push(...found);
@@ -570,7 +569,7 @@ async function main(argv) {
   // is legitimate and is exactly the kind of second copy that drifted last
   // time; README.md is here because three of round 4's findings were on it
   // and nothing had ever read it.
-  const docsDir = path.join(REPO, "docs/Documentation");
+  const docsDir = path.join(REPO_ROOT, "docs/Documentation");
   const wanted = [...wrapperGates.values()].map((g) => g.join("\0"));
   const counts = new Map([...wrapperGates].map(([bat, g]) => [bat, g.length]));
   const rels = [
@@ -580,7 +579,7 @@ async function main(argv) {
   ];
   let claimsSeen = 0;
   for (const rel of rels) {
-    const src = await readFile(path.join(REPO, rel), "utf8");
+    const src = await readFile(path.join(REPO_ROOT, rel), "utf8");
     for (const run of commandRuns(src, rel)) {
       if (wanted.includes(run.gates.join("\0"))) {
         if (verbose) console.log(`  ok    ${rel}:${run.line}: matches a wrapper`);
diff --git a/scripts/check_links_diff.mjs b/scripts/check_links_diff.mjs
index 01fcd1e2..1592dc4e 100644
--- a/scripts/check_links_diff.mjs
+++ b/scripts/check_links_diff.mjs
@@ -77,11 +77,10 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { performance } from "node:perf_hooks";
-import { fileURLToPath } from "node:url";
 
 import { runCheck, selfTest as scriptSelfTest } from "./check_links.mjs";
+import { REPO_ROOT } from "../lib/repo-paths.mjs";
 
-const REPO_ROOT = path.resolve(fileURLToPath(new URL("..", import.meta.url)));
 const BASE_PATH = "/twinBASIC-docs";
 const DEFAULT_BASEPATH_TREE = "docs/_site-basepath";
 const FIXTURE_SRC  = "test/fixtures/check-src";
diff --git a/scripts/check_lint.mjs b/scripts/check_lint.mjs
index 872dce1f..110bb927 100644
--- a/scripts/check_lint.mjs
+++ b/scripts/check_lint.mjs
@@ -36,13 +36,11 @@ import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
 import { createRequire } from "node:module";
 import os from "node:os";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
 import { exitOnCrash } from "./lib/gate-probes.mjs";
+import { REPO_ROOT } from "../lib/repo-paths.mjs";
 
 exitOnCrash();
 
-const ROOT = path.resolve(fileURLToPath(new URL("..", import.meta.url)));
-
 function cannotLint(message) {
   console.error(`check_lint: ${message}`);
   process.exit(2);
@@ -56,12 +54,12 @@ if (argv.length && !staged) cannotLint("usage: node scripts/check_lint.mjs [--st
 // two extensions the scope in biome.jsonc is made of.
 function stagedScripts() {
   const r = spawnSync("git", ["diff", "--cached", "--name-only", "--diff-filter=ACMR", "-z"], {
-    cwd: ROOT,
+    cwd: REPO_ROOT,
     encoding: "utf8",
   });
   if (r.error) cannotLint(`could not run git: ${r.error.message}`);
   if (r.status !== 0) cannotLint(`git diff --cached failed: ${r.stderr.trim()}`);
-  return r.stdout.split("\0").filter((f) => /\.m?js$/.test(f) && existsSync(path.join(ROOT, f)));
+  return r.stdout.split("\0").filter((f) => /\.m?js$/.test(f) && existsSync(path.join(REPO_ROOT, f)));
 }
 
 const scripts = staged ? stagedScripts() : [];
@@ -95,7 +93,7 @@ try {
   const file = path.join(dir, "summary.txt");
   const args = ["lint", "--error-on-warnings", "--reporter=default", "--reporter=summary", `--reporter-file=${file}`];
   if (staged) args.push("--no-errors-on-unmatched", "--", ...scripts);
-  run = spawnSync(process.execPath, [biome, ...args], { cwd: ROOT, stdio: ["ignore", "inherit", "inherit"] });
+  run = spawnSync(process.execPath, [biome, ...args], { cwd: REPO_ROOT, stdio: ["ignore", "inherit", "inherit"] });
   summary = readSummary(file);
 } finally {
   rmSync(dir, { recursive: true, force: true });
diff --git a/scripts/check_regex_safety.mjs b/scripts/check_regex_safety.mjs
index e66fe57e..eee148a2 100644
--- a/scripts/check_regex_safety.mjs
+++ b/scripts/check_regex_safety.mjs
@@ -78,8 +78,7 @@ import * as walk from "acorn-walk";
 import fg from "fast-glob";
 
 import { foldConstructedRegexes } from "./lib/regex-fold.mjs";
-
-const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+import { REPO_ROOT } from "../lib/repo-paths.mjs";
 
 // ── Backend selection ────────────────────────────────────────────────────────
 //
@@ -250,13 +249,13 @@ function foldSelfTest() {
 // ── Extraction ───────────────────────────────────────────────────────────────
 
 async function extractRegexes() {
-  const files = (await fg(SOURCE_GLOBS, { cwd: ROOT, ignore: IGNORE })).sort();
+  const files = (await fg(SOURCE_GLOBS, { cwd: REPO_ROOT, ignore: IGNORE })).sort();
   const found = new Map();
   const unresolved = [];
   const parseFailures = [];
 
   for (const rel of files) {
-    const src = await readFile(path.join(ROOT, rel), "utf8");
+    const src = await readFile(path.join(REPO_ROOT, rel), "utf8");
     let ast;
     try {
       // allowReturnOutsideFunction: wisdom/extract/workflow.mjs has a
@@ -341,7 +340,7 @@ async function checkList(list) {
 function runShard(payload) {
   return new Promise((resolve, reject) => {
     const child = spawn(process.execPath, [fileURLToPath(import.meta.url), "--shard"], {
-      cwd: ROOT, stdio: ["pipe", "pipe", "inherit"],
+      cwd: REPO_ROOT, stdio: ["pipe", "pipe", "inherit"],
     });
     let buf = "";
     child.stdout.on("data", (d) => { buf += d; });
diff --git a/scripts/check_tree_fresh.mjs b/scripts/check_tree_fresh.mjs
index fb2f8292..692f6a2b 100644
--- a/scripts/check_tree_fresh.mjs
+++ b/scripts/check_tree_fresh.mjs
@@ -28,11 +28,9 @@
 
 import { readdirSync, statSync, existsSync } from "node:fs";
 import { join, resolve, relative, sep } from "node:path";
-import { fileURLToPath } from "node:url";
 
 import { isOutputTree } from "../lib/markdown-files.mjs";
-
-const REPO_ROOT = resolve(fileURLToPath(new URL("..", import.meta.url)));
+import { REPO_ROOT } from "../lib/repo-paths.mjs";
 
 // Output trees live under docs/, so walking docs/ naively would compare
 // the build against itself and always pass. They are skipped at the top of
diff --git a/scripts/compare_trees.mjs b/scripts/compare_trees.mjs
index e315d939..aee96db7 100644
--- a/scripts/compare_trees.mjs
+++ b/scripts/compare_trees.mjs
@@ -42,10 +42,9 @@ import { spawnSync } from "node:child_process";
 import { closeSync, existsSync, openSync } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
+import { REPO_ROOT } from "../lib/repo-paths.mjs";
 
-const ROOT = path.resolve(fileURLToPath(new URL("..", import.meta.url)));
-const WORK = path.join(ROOT, ".compare-trees");
+const WORK = path.join(REPO_ROOT, ".compare-trees");
 const SIDES = ["before", "after"];
 
 // The three trees one build writes, by the suffix tbdocs adds to --dest.
@@ -133,7 +132,7 @@ function parseArgs(argv) {
 class ToolError extends Error {}
 
 function git(args, { env, allowFail = false } = {}) {
-  const r = spawnSync("git", args, { cwd: ROOT, encoding: "utf8", env: env ? { ...process.env, ...env } : process.env });
+  const r = spawnSync("git", args, { cwd: REPO_ROOT, encoding: "utf8", env: env ? { ...process.env, ...env } : process.env });
   if (r.error) throw new ToolError(`git ${args.join(" ")}: ${r.error.message}`);
   if (r.status !== 0 && !allowFail) {
     throw new ToolError(`git ${args.join(" ")} exited ${r.status}: ${(r.stderr || "").trim()}`);
@@ -157,7 +156,7 @@ async function removeWorktrees() {
 // identities keep it independent of the user's configuration; nothing refers
 // to it afterwards, so git's garbage collection removes it in time.
 function snapshotWorkingTree() {
-  const gitDir = path.resolve(ROOT, git(["rev-parse", "--git-dir"]).stdout.trim());
+  const gitDir = path.resolve(REPO_ROOT, git(["rev-parse", "--git-dir"]).stdout.trim());
   const index = path.join(WORK, "index");
   const env = {
     GIT_INDEX_FILE: index,
diff --git a/scripts/convert_em_dash_separators.mjs b/scripts/convert_em_dash_separators.mjs
index d0dc4563..23070b3d 100644
--- a/scripts/convert_em_dash_separators.mjs
+++ b/scripts/convert_em_dash_separators.mjs
@@ -42,16 +42,14 @@
 
 import { promises as fs } from "node:fs";
 import path from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
+import { pathToFileURL } from "node:url";
 
 import { createMarkdownIt } from "../builder/render.mjs";
 import { blockRegions, mapLines, splitCodeSpans } from "../lib/markdown.mjs";
 import { markdownFiles } from "../lib/markdown-files.mjs";
+import { DOCS_DIR } from "../lib/repo-paths.mjs";
 import { exitOnCrash } from "./lib/gate-probes.mjs";
 
-const REPO = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
-const ROOT = path.join(REPO, "docs");
-
 const EM_DASH = "—";
 const EN_DASH = "–";
 
@@ -135,8 +133,8 @@ async function main(argv) {
   let en = 0;
   const md = createMarkdownIt({ highlighter: null, linkTables: null, baseurl: "", staticFiles: new Set() });
 
-  for (const rel of (await markdownFiles(ROOT)).sort(byPathParts)) {
-    const abs = path.join(ROOT, rel);
+  for (const rel of (await markdownFiles(DOCS_DIR)).sort(byPathParts)) {
+    const abs = path.join(DOCS_DIR, rel);
     const r = convertText(await fs.readFile(abs, "utf8"), md);
     if (r.sep + r.em + r.en === 0) continue;
 
diff --git a/scripts/gen_attribute_probes.mjs b/scripts/gen_attribute_probes.mjs
index 7c3ca113..7801976c 100644
--- a/scripts/gen_attribute_probes.mjs
+++ b/scripts/gen_attribute_probes.mjs
@@ -37,11 +37,10 @@
 
 import { promises as fs } from "node:fs";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
 import { parseAttributes } from "./lib/attributes-doc.mjs";
+import { DOCS_DIR } from "../lib/repo-paths.mjs";
 
-const REPO = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
-const DOCS = path.join(REPO, "docs", "Reference", "Attributes.md");
+const ATTR_DOC = path.join(DOCS_DIR, "Reference", "Attributes.md");
 
 const USAGE = `Generate a twinBASIC probe project for Reference/Attributes.md applicability.
 
@@ -1119,7 +1118,7 @@ async function main(argv) {
   const overflowSrc = path.join(out + "-2", "Sources");
   await fs.mkdir(srcDir, { recursive: true });
 
-  const entries = parseAttributes(await fs.readFile(DOCS, "utf8"));
+  const entries = parseAttributes(await fs.readFile(ATTR_DOC, "utf8"));
   const byName = new Map(entries.map((e) => [e.name, e]));
   const probes = [];
   const overflow = [];
diff --git a/scripts/lib/axe-scan.mjs b/scripts/lib/axe-scan.mjs
index fad4328e..b3fbe4e4 100644
--- a/scripts/lib/axe-scan.mjs
+++ b/scripts/lib/axe-scan.mjs
@@ -16,16 +16,17 @@
 // See builder/PLAN-axe-perf.md for why each knob below is a knob.
 
 import { readdirSync, readFileSync } from "node:fs";
-import { resolve, join, relative, sep } from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
-
-// This module lives at <repo>/scripts/lib/axe-scan.mjs.  Anchoring the built
-// tree and the axe bundle to the repo root rather than to process.cwd() lets
-// perf/ab-axe.mjs run from perf/ (as ab-css.mjs does) while check_a11y.mjs
-// runs from the repo root, without either needing to know where the other is.
-// An explicit --root-dir still resolves against the caller's cwd, which is
-// what someone typing a relative path expects.
-export const REPO_ROOT = resolve(fileURLToPath(import.meta.url), "../../..");
+import { join, relative, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+import { REPO_ROOT } from "../../lib/repo-paths.mjs";
+
+// Anchoring the built tree and the axe bundle to the repository root rather
+// than to process.cwd() lets perf/ab-axe.mjs run from perf/ (as ab-css.mjs
+// does) while check_a11y.mjs runs from the repo root, without either needing
+// to know where the other is. An explicit --root-dir still resolves against
+// the caller's cwd, which is what someone typing a relative path expects.
+// pick_a11y_sample.mjs and sweep_a11y.mjs take the root from here.
+export { REPO_ROOT };
 
 export const DEFAULT_ROOT_DIR = join(REPO_ROOT, "docs/_site-offline");
 
diff --git a/scripts/lib/inter-page.mjs b/scripts/lib/inter-page.mjs
index 607d6f41..af22266b 100644
--- a/scripts/lib/inter-page.mjs
+++ b/scripts/lib/inter-page.mjs
@@ -10,16 +10,15 @@
 
 import { promises as fs } from "node:fs";
 import path from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
-
-const DOCS = path.resolve(fileURLToPath(import.meta.url), "../../../docs");
+import { pathToFileURL } from "node:url";
+import { DOCS_DIR } from "../../lib/repo-paths.mjs";
 
 /**
  * Opens a new page in `browser` with Inter declared, `css` after the
  * @font-face rules and `body` after the stylesheet, and returns it once loaded.
  */
 export async function openInterPage(browser, name, { css = "", body = "" } = {}) {
-  const fontDirUrl = pathToFileURL(path.join(DOCS, "assets", "fonts")).href;
+  const fontDirUrl = pathToFileURL(path.join(DOCS_DIR, "assets", "fonts")).href;
   const html = `<!doctype html><meta charset="utf-8"><title>${name}</title><style>
 @font-face{font-family:"Inter";font-style:normal;font-weight:100 900;
   src:url("${fontDirUrl}/inter-variable.woff2") format("woff2")}
@@ -29,7 +28,7 @@ ${css}</style>${body}`;
 
   const page = await browser.newPage();
   page.on("pageerror", (e) => console.error("[page error]", e.message));
-  const host = path.join(DOCS, `_${name}-host.html`);
+  const host = path.join(DOCS_DIR, `_${name}-host.html`);
   await fs.writeFile(host, html, "utf8");
   try {
     await page.goto(pathToFileURL(host).href, { waitUntil: "load" });
diff --git a/scripts/survey_tooling.mjs b/scripts/survey_tooling.mjs
index b6764424..d9cdba01 100644
--- a/scripts/survey_tooling.mjs
+++ b/scripts/survey_tooling.mjs
@@ -50,10 +50,10 @@ import { execFileSync } from "node:child_process";
 import { readFileSync } from "node:fs";
 import { builtinModules } from "node:module";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
 import { parseArgs } from "node:util";
 import * as acorn from "acorn";
 import * as walk from "acorn-walk";
+import { REPO_ROOT } from "../lib/repo-paths.mjs";
 
 const TOOLING_DIRS = ["builder", "scripts", "lib", "book", "eval", "wisdom", "test", "perf"];
 const VENDORED = [/^book\/lib\/paged\.browser\.js$/, /^builder\/vendor\//];
@@ -86,7 +86,7 @@ if (opts.help) {
 }
 const WINDOW = positiveInt("window", opts.window);
 const TOP = positiveInt("top", opts.top);
-const ROOT = path.resolve(opts.root ?? fileURLToPath(new URL("..", import.meta.url)));
+const ROOT = path.resolve(opts.root ?? REPO_ROOT);
 const listed = (f) => opts["include-perf"] || !f.startsWith(LAB);
 
 function positiveInt(name, raw) {
diff --git a/wisdom/extract/prep.mjs b/wisdom/extract/prep.mjs
index 2d10290e..9af71b8e 100644
--- a/wisdom/extract/prep.mjs
+++ b/wisdom/extract/prep.mjs
@@ -5,15 +5,15 @@ import { buildSitemap, buildPackageSummary, buildPageIndex } from './sitemap.mjs
 import { loadState, saveState, isThreadChanged, recordEmission } from './state.mjs'
 import { graftAdditions, renderSideband } from './merger.mjs'
 import { readFrontmatter } from '../files.mjs'
+import { REPO_ROOT, DOCS_DIR } from '../../lib/repo-paths.mjs'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
-const REPO_ROOT = join(__dirname, '..', '..')
 const BATCH_SIZE = 200
 
 export async function runExtract(flags) {
   const threadsDir = flags.in || join(__dirname, '..', 'data', 'threads')
   const outDir = flags.out || join(__dirname, '..', 'data', 'findings')
-  const docsDir = join(REPO_ROOT, 'docs', 'Reference')
+  const docsDir = join(DOCS_DIR, 'Reference')
 
   if (!existsSync(threadsDir)) {
     process.stderr.write('[wisdom] Threads directory not found — run process first\n')

From 7e43247e8c114488d6a162977fa0463c7aae6e3e Mon Sep 17 00:00:00 2001
From: Kuba Sunderland-Ober <kuba@mareimbrium.org>
Date: Sun, 27 Sep 2026 18:14:17 +0200
Subject: [PATCH 24/27] lib: cli.mjs on node:util parseArgs, and check_cli.mjs

---
 .github/actions/run-gates/action.yml |   9 +
 WIP.md                               |   5 +-
 builder/PLAN-TOOLING-REVIEW.md       |  89 +++++++-
 docs/Documentation/Building.md       |   3 +-
 docs/Documentation/Tools.md          |  21 +-
 lib/README.md                        |   6 +
 lib/cli.mjs                          | 191 +++++++++++++++++
 scripts/check_cli.mjs                | 310 +++++++++++++++++++++++++++
 test.bat                             |   8 +
 9 files changed, 632 insertions(+), 10 deletions(-)
 create mode 100644 lib/cli.mjs
 create mode 100644 scripts/check_cli.mjs

diff --git a/.github/actions/run-gates/action.yml b/.github/actions/run-gates/action.yml
index 3c5cbbd4..e3155e31 100644
--- a/.github/actions/run-gates/action.yml
+++ b/.github/actions/run-gates/action.yml
@@ -134,6 +134,15 @@ runs:
     - name: Verify the symbol index and its drift guard (check_symbol_index.mjs)
       shell: bash
       run: node scripts/check_symbol_index.mjs
+    # Nothing else tests how a tool reads its command line, which is how a
+    # value flag given no value came to be read as NaN or as the next flag.
+    # lib/cli.mjs's probes, then each tool's recorded command-line errors, each
+    # run with a twinBASIC IDE and a browser that do not exist, so a case that
+    # gets past its command line fails rather than starting either. No
+    # browser, no built tree, no install.
+    - name: Verify the command-line parser and the tools' cases (check_cli.mjs)
+      shell: bash
+      run: node scripts/check_cli.mjs
     # Graphviz sizes each node box from a width table; the browser paints the
     # label with a real font. Nothing in the build compares the two, so a
     # mismatch ships as text hanging outside its box on a green build -- which
diff --git a/WIP.md b/WIP.md
index af6b5020..611e1a11 100644
--- a/WIP.md
+++ b/WIP.md
@@ -451,7 +451,7 @@ Why the report separates the wedged task from the merely blocked ones, and why
 - `build.bat` — runs `node builder\tbdocs.mjs --src docs --check-audit-index` (which implies `--check`) and produces three trees in one pass: the online copy at `_site/`, a `file://`-browsable copy at `_site-offline/`, and the sparse pagedjs source at `_site-pdf/`. The offline pass adds ~700 ms and the PDF pass adds ~150 ms on top of the ~2 s online build. Toggle `also_build_offline` / `also_build_pdf` in `_config.yml` (or pass `--no-offline` / `--no-pdf`) to skip a sibling output. `--check` adds ~1.7 s and runs the link + integrity check over the HTML while it is still in worker memory; `build.bat --no-check` gets a plain build.
 - `serve.bat` — runs `tbdocs --serve`: initial build, then a long-lived process with watcher, debounced rebuilds, and SSE-driven browser auto-reload. Writes to `docs/_serve/` (disjoint from `build.bat`'s `_site*/`) and skips the offline + PDF passes — so a one-off `build.bat` for the PDF or offline mirror doesn't disturb the live preview. Ctrl+C to stop.
 - `check.bat` — the gates that read the built site: a freshness check that refuses a stale tree (`scripts/check_tree_fresh.mjs`), the DOT diagram fit check (`scripts/check_dot_fit.mjs`), the a11y sample-coverage check (`scripts/pick_a11y_sample.mjs --check`), then the accessibility check (`scripts/check_a11y.mjs`). The link + integrity check moved into `build.bat`. ~37 s.
-- `test.bat` — the tests the *toolchain* has to pass: the publish-allowlist self-test (`scripts/check_publish_policy.mjs`), the gate-list check (`scripts/check_gate_lists.mjs`), the CI-workflow roster check (`scripts/check_ci_workflows.mjs`), the lint gate (`scripts/check_lint.mjs`), the regex-safety gate (`scripts/check_regex_safety.mjs`), the code-region gate (`scripts/check_code_regions.mjs`), the page-count drift-guard probes (`scripts/check_page_baseline.mjs`), the book-coverage probes (`scripts/check_book_coverage.mjs`), the symbol-index probes (`scripts/check_symbol_index.mjs`), and the axe source-patch verification (`scripts/check_axe_patch_equiv.mjs`). ~8 s. See [What belongs in test.bat rather than check.bat](WIP.Build.md#what-belongs-in-testbat-rather-than-checkbat).
+- `test.bat` — the tests the *toolchain* has to pass: the publish-allowlist self-test (`scripts/check_publish_policy.mjs`), the gate-list check (`scripts/check_gate_lists.mjs`), the CI-workflow roster check (`scripts/check_ci_workflows.mjs`), the lint gate (`scripts/check_lint.mjs`), the regex-safety gate (`scripts/check_regex_safety.mjs`), the code-region gate (`scripts/check_code_regions.mjs`), the page-count drift-guard probes (`scripts/check_page_baseline.mjs`), the book-coverage probes (`scripts/check_book_coverage.mjs`), the symbol-index probes (`scripts/check_symbol_index.mjs`), the command-line probes and cases (`scripts/check_cli.mjs`), and the axe source-patch verification (`scripts/check_axe_patch_equiv.mjs`). ~9 s. See [What belongs in test.bat rather than check.bat](WIP.Build.md#what-belongs-in-testbat-rather-than-checkbat).
 - `book.bat` — renders the PDF from `docs\_site-pdf\book.html` via `node book\render-book.mjs` into `docs\_pdf\twinBASIC Book.pdf`. Run `build.bat` first to populate `_site-pdf/`; `book.bat` refuses a tree older than its sources rather than rendering the previous book (see [The book refuses a stale source tree](WIP.Build.md#the-book-refuses-a-stale-source-tree)).
 
 - `examples.bat` — compiles the documentation's own twinBASIC code samples, every `tb` fence marked `check_build`, and reports the ones the compiler refuses against the line in the page they came from. Needs a twinBASIC install and Windows, so it is outside every gate and outside CI; ~120 s over the 1,129 samples marked as of 2026-09-25. Two modes need no compiler at all: `--census` classifies every fence and says how many classifiable ones are still unmarked, and `--report <survey.json>` groups a saved `--propose --json` survey by diagnostic, section and unresolved name. `--propose` itself does compile. See [Compiling the reference's own code samples](#compiling-the-references-own-code-samples) and [WIP.ExamplesBuild.md](WIP.ExamplesBuild.md).
@@ -469,7 +469,7 @@ build.bat && check.bat
 
 On the dev box that is ~4 s of build against ~37 s of check, of which the axe scan is ~20 s. [builder/PLAN-checks.md](builder/PLAN-checks.md) records how the link checker got folded into the build's task graph, what it cost and what it saved; the axe follow-ons are designed there but not implemented.
 
-**If the change touched `builder/`, `scripts/`, `lib/`, `book/`, `eval/`, `wisdom/`, `test/`, the site's scripts in `docs/assets/js/`, a wrapper or a workflow, run `test.bat` as well** --- another ~8 s. Seven of its ten gates cannot be affected by an edit under `docs/` at all. **Three can.** `check_lint.mjs` lints the site's two scripts in `docs/assets/js/` along with the tooling. `check_gate_lists.mjs` is the easy one to predict: it reads `README.md` and every page under `docs/Documentation/`, so an edit to any developer page that states a gate count can fail it. **`check_code_regions.mjs` is the one worth understanding**, and which half of it a content edit reaches is worth keeping straight. Its corpus sweep reads `DOCS_DIR`, which is `<repo>/docs`, and tokenises all 906 markdown files, so a page that provokes a rewrite into *altering* a code region fails it --- that half is content-dependent. Its fixed probes are not: they run against their own sources whatever the tree holds, and they cover the **mirror** fault, where a rewrite silently stops firing. The sweep structurally cannot see that one, because text the rewrite skipped is stashed and restored unchanged and every region still matches. So run `test.bat` after adding an unusual code construct --- a fence whose contents include a fence marker, a 4-space indented block, an admonition wrapping a fence --- and read the built page as well, because for the mirror fault the gate is asserting that the stasher still works rather than checking your page:
+**If the change touched `builder/`, `scripts/`, `lib/`, `book/`, `eval/`, `wisdom/`, `test/`, the site's scripts in `docs/assets/js/`, a wrapper or a workflow, run `test.bat` as well** --- another ~9 s. Eight of its eleven gates cannot be affected by an edit under `docs/` at all. **Three can.** `check_lint.mjs` lints the site's two scripts in `docs/assets/js/` along with the tooling. `check_gate_lists.mjs` is the easy one to predict: it reads `README.md` and every page under `docs/Documentation/`, so an edit to any developer page that states a gate count can fail it. **`check_code_regions.mjs` is the one worth understanding**, and which half of it a content edit reaches is worth keeping straight. Its corpus sweep reads `DOCS_DIR`, which is `<repo>/docs`, and tokenises all 906 markdown files, so a page that provokes a rewrite into *altering* a code region fails it --- that half is content-dependent. Its fixed probes are not: they run against their own sources whatever the tree holds, and they cover the **mirror** fault, where a rewrite silently stops firing. The sweep structurally cannot see that one, because text the rewrite skipped is stashed and restored unchanged and every region still matches. So run `test.bat` after adding an unusual code construct --- a fence whose contents include a fence marker, a 4-space indented block, an admonition wrapping a fence --- and read the built page as well, because for the mirror fault the gate is asserting that the stasher still works rather than checking your page:
 
 ```sh
 build.bat && check.bat && test.bat
@@ -503,6 +503,7 @@ wrapper:
 | `test.bat` | `check_code_regions` | no source or HTML rewrite altered a code region; `lib/markdown.mjs` and `lib/frontmatter.mjs` pass their probes, and the block parse finds what the full parse finds; the count-name check skips code and names the file's line; `discover` warns about an unquoted frontmatter value that ends in `#`; the dash normaliser converts only prose |
 | `test.bat` | `check_regex_safety` | no regex in the tree can backtrack exponentially |
 | `test.bat` | `check_symbol_index` | the symbol index still places each kind of symbol, from fixtures |
+| `test.bat` | `check_cli` | `lib/cli.mjs` parses as a strict `parseArgs` does, and keeps a lenient tool's leniency where asked; each tool's recorded command-line errors still exit and print as recorded, run with an IDE and a browser that do not exist |
 | `test.bat` | `check_ci_workflows` | both CI workflows run every wrapper gate, with the same arguments and order, and build with `build.bat`'s flags |
 | `test.bat` | `check_lint` | Biome finds nothing in the tooling, warnings included, and checked at least one script |
 | `test.bat` | `check_publish_policy`, `check_gate_lists`, `check_page_baseline`, `check_book_coverage`, `check_axe_patch_equiv` | the gates on the gates |
diff --git a/builder/PLAN-TOOLING-REVIEW.md b/builder/PLAN-TOOLING-REVIEW.md
index 856c5648..3bf36ff3 100644
--- a/builder/PLAN-TOOLING-REVIEW.md
+++ b/builder/PLAN-TOOLING-REVIEW.md
@@ -1405,6 +1405,83 @@ L1-2, L1-3 and L1-6 shipped.
 **Verify.** The probes; changing one recorded expectation fails the gate; the roster gate
 passes. CI waits for the owner's push.
 
+**Landed.** `lib/cli.mjs` exports `parseCli`, `CliError`, `numberOption`, `withUsageError` and
+`printHelpAndExit`. `parseCli(argv, { options, positionals, unknown, acceptsValue })` takes
+options in `parseArgs`' shape and returns `{ values, positionals, tokens, ignored }`: values
+keyed in camelCase; an absent option its `default`, a `multiple` one `[]`, any other none; a
+repeat keeps the last; `tokens` the kept options (each with its `key`), positionals and `--`,
+in order, for `tbdocs`' order-dependent resets. `parseArgs` runs loose and the module makes a
+strict parse's checks itself, because a strict parse stops at the first unknown option and a
+loose one alone takes a trailing value flag as `true`; with the defaults the two agree on 64
+argument lists (a probe). A tool's leniency is two parameters, each use of which Phase 3
+removes. `unknown` is `"error"`, `"ignore"` (an unknown option, a boolean given a value and a
+positional beyond `max` go into `ignored`, as given: the `includes` and `opt()` tools, and the
+list `check_links` warns about) or `"positional"` (an unknown option becomes a positional as
+given, and counts: `nav_hops`, `site_search`, `tbrun`, `gen_attribute_probes`); a value flag
+with no value is refused under all three. `acceptsValue(value, inline)` defaults to the strict
+rule (a separate value may not be missing or start with a dash and one more character; any
+inline value is taken; `-` and `""` are values); the survey's other guards are `(v) => v !==
+undefined` (`check_links`), `Boolean` (the a11y family's truthiness test), `(v) => v !==
+undefined && !v.startsWith("--")` (`compare_trees`) and `() => true` (no guard, which stores
+`undefined` for a trailing flag and skips its default). A `CliError` has a `code`
+(`unknown-option`, `unexpected-value`, `missing-value`, `unexpected-positional`,
+`missing-positional`, `bad-number`), `option` as typed, `arg` and `value`; its default
+messages are `unknown option: X`, `--x needs a value` (the majority wording), `--x takes no
+value`, `unexpected argument: X`, `expected at least N argument(s), got M` and `--x expects a
+whole number from 1 to 65535, got: 0`. `numberOption(value, { option, integer, min, max,
+message })` refuses blank text, which `Number` reads as 0. `withUsageError(fn, { stream,
+exitCode = 2, format, exit })` prints `format(err)` with one newline and exits, and throws
+anything but a `CliError` on; `printHelpAndExit(text, { stream = "stdout", exitCode = 0, exit
+})`. A `stream` object with a `write` and an `exit` are the probes' hooks, which no tool needs.
+
+`scripts/check_cli.mjs` holds 36 module probes and 14 cases, 50 checks in 0.6 s. A case is `{
+tool, args, exit, stdout, stderr }`: a string is the whole stream, a RegExp must match, and a
+stream not named must be empty. The tool's own words for the error are pinned exactly, a usage
+text after them by its opening. Each case runs in an empty folder of its own, with `TB_IDE` and
+`PUPPETEER_EXECUTABLE_PATH` naming missing files and `TBBUILD_SHOW` removed, 30 s at most,
+`availableParallelism()` at once. C47 records C18's settled behaviour (`tbdocs`: a trailing and
+a dash-led missing value, `--port=0` and an unknown argument, exit 4 on stderr; `check_links`:
+a trailing missing value for `--root-dir` and `--forbid`, exit 4, `error: ` on **stdout**) and
+C17's (`tbbuild`, `check_examples`, `census_attributes`, `build_package_api`: a trailing and a
+dash-led missing value, exit 2, `tbbuild`'s usage line matched by its opening).
+
+Measured: Puppeteer 25.0.4 honours `PUPPETEER_EXECUTABLE_PATH`; `check_dot_fit` and
+`check_axe_patch_equiv` exit 2 in about 0.3 s ("Tried to find the browser at the configured
+path"). The kit's `c47-faults.mjs` puts one fault at a time into the gate or the module as it
+loads (the `c43-fault.mjs` preload) and counts twinBASIC and Chromium processes, none before or
+after. A changed exit code, a changed message and a message moved to the other stream each fail
+their case alone (1 of 50); the value rule loosened to a loose parse's fails 2 probes, the
+comparison with `parseArgs` among them; unknown options accepted fails 6. Cases forced past the
+command line fail on their own message: `check_examples --jobs 2` runs its 119 probes and stops
+on "no compiler beside the IDE" (1.1 s), `census_attributes --out x.json` on "no packages/
+under", `tbdocs --port 4000` exits 1 with "task config failed" (0.5 s; its default `docs` is
+relative to the empty folder), `tbbuild` on "no such project". `check_gate_lists` passes, and
+`check_ci_workflows` counts 14 gates where it counted 13 (it leaves out `check_tree_fresh`,
+which CI does not run). Registered in `test.bat` after `check_symbol_index`, the
+composite action, Tools.md's list, POSIX block and a section, Building.md's POSIX block,
+WIP.md's table and bullet, and `lib/README.md`. CI waits for the push, where the four harness
+tools and `tbdocs` run on Linux for the first time, each only as far as its error.
+`build.bat`, `check.bat` (the a11y line unchanged) and `test.bat` exit 0, and the tree
+comparison differs only in Tools.md's and Building.md's pages, online and offline, the search
+index and `book.html`.
+
+For C48–C52:
+- `opt()` in `tbbuild`, `check_examples`, `census_attributes`, `build_package_api` and
+  `addin_test` finds its flag with `indexOf`, so a repeated flag keeps its **first** value;
+  `parseCli` keeps the last, as `parseArgs` does (read, not run; `tbrun`'s `opt` not read). The
+  survey's "every other repeat: last wins" is wrong for these. A repeat does not stop the tool,
+  so `check_cli` cannot hold it; C49 decides.
+- `check_tb_registry` reads no arguments, and C49's entry now says so; C50's names `check_lint`
+  and `compare_trees`, which no entry did; C51's counts five `eval/` scripts.
+- A migration adds its tools' cases to `CASES`, with a comment naming the commit, and runs the
+  gate against the unedited tool before the edit.
+- Found in passing, not fixed: a launch refused for a missing browser leaves a Puppeteer profile
+  folder in `%TEMP%`, since `ChromeLauncher` makes it (`ChromeLauncher.js:77`) before it
+  resolves the executable (`:87`), and `withBrowser` removes only the profile of a browser it
+  got. Only a case that gets past its command line reaches it here.
+- Building.md said "all ten gates" where there were 14 before this commit, and
+  `check_gate_lists` did not report it; it now says "all the gates", as that gate advises.
+
 ### C48 — `scripts: the a11y and diagram tools parse through lib/cli.mjs`
 
 **A5-1 (R1).** Eight hand-written loops, diverged three ways. `check_a11y.mjs:63-79` answers
@@ -1427,8 +1504,9 @@ have a `flag()` and `opt()` pair and a `die()`, in three shapes (V3's fifth note
 `check_examples`, `census_attributes`, `build_package_api`, `gen_attribute_probes` and
 `check_tb_registry` parse by hand as well.
 
-**Change.** All eight through `parseCli`, keeping today's behaviour, C17's fixes included;
+**Change.** All seven through `parseCli`, keeping today's behaviour, C17's fixes included;
 `tbrun` and `addin_test` still substitute their default for an empty value until C72.
+`check_tb_registry` reads no arguments (C47 found), so nothing of it migrates.
 
 **Verify.** `check_cli.mjs`'s cases; the `examples.bat` summary and `addin-test.bat`
 unchanged (harness runs, one at a time).
@@ -1440,8 +1518,10 @@ unchanged (harness runs, one at a time).
 **Change.** `check_links.mjs`, whose collect-and-warn handling of unknown flags stays custom
 code until C72; `check_links_diff.mjs`; `crawl_check.mjs`; `check_publish_policy.mjs`, whose
 inline `opt` is L1-2's fourth variant; `check_regex_safety.mjs`, with its internal `--shard`
-flag; `check_code_regions.mjs`; `check_gate_lists.mjs`; `convert_em_dash_separators.mjs`; and
-`survey_tooling.mjs`. Each keeps today's behaviour.
+flag; `check_code_regions.mjs`; `check_gate_lists.mjs`; `convert_em_dash_separators.mjs`;
+`survey_tooling.mjs`; and two no entry named until C47: `check_lint.mjs`, whose argument list
+must be `--staged` or nothing, and `compare_trees.mjs`, which passes what follows `--` to
+`tbdocs`. Each keeps today's behaviour.
 
 **Verify.** `check_cli.mjs`'s cases; `test.bat` and `check.bat` unchanged;
 `check_links_diff.mjs --a script --b fused` agrees.
@@ -1453,7 +1533,8 @@ flag; `check_code_regions.mjs`; `check_gate_lists.mjs`; `convert_em_dash_separat
 exits 1 on a bare `--help`; "usage, then an exit code chosen by whether help was asked" is
 repeated six times across `eval/` and `wisdom/`.
 
-**Change.** `render-book.mjs` and the four `eval/` scripts through `parseCli`, with
+**Change.** `render-book.mjs` and the five `eval/` scripts (the four parsers and
+`transcript.mjs`) through `parseCli`, with
 `printHelpAndExit` replacing the six copies, each keeping today's behaviour. `wisdom.mjs`'s
 subcommands need code the module does not have, so it migrates only if the fit is clean, and
 otherwise stays as it is with a comment saying why.
diff --git a/docs/Documentation/Building.md b/docs/Documentation/Building.md
index 525bc10b..dc66134b 100644
--- a/docs/Documentation/Building.md
+++ b/docs/Documentation/Building.md
@@ -42,7 +42,7 @@ The documentation is rendered to HTML by `tbdocs`, a custom Node.js static site
 ### On macOS and Linux
 {: #posix-equivalents }
 
-Nothing in the pipeline itself is Windows-specific --- `tbdocs` and all ten gates are Node programs, and CI runs all but one of them on `ubuntu-latest` (the exception is deliberate: see [What CI deliberately does not run](#what-ci-deliberately-does-not-run)). The five wrappers are the only part that is, and what follows is what each of them runs.
+Nothing in the pipeline itself is Windows-specific --- `tbdocs` and all the gates are Node programs, and CI runs all but one of them on `ubuntu-latest` (the exception is deliberate: see [What CI deliberately does not run](#what-ci-deliberately-does-not-run)). The five wrappers are the only part that is, and what follows is what each of them runs.
 
 Each `.bat` opens with `@pushd "%~dp0"`, which is what lets it be invoked from any directory. The commands below have no equivalent of that, so **run them from the repository root**. It is not a formality: `tbdocs`'s `--src docs`, `check_publish_policy.mjs`'s default source root, and every path handed to `render-book.mjs` are all resolved against the working directory.
 
@@ -77,6 +77,7 @@ Each `.bat` opens with `@pushd "%~dp0"`, which is what lets it be invoked from a
       && node scripts/check_page_baseline.mjs \
       && node scripts/check_book_coverage.mjs \
       && node scripts/check_symbol_index.mjs \
+      && node scripts/check_cli.mjs \
       && node scripts/check_axe_patch_equiv.mjs
 
 `book.bat` has one step that is invisible from the command it ends with. `render-book.mjs` writes the PDF with a plain file write and never creates the directory above it, so `docs/_pdf/` has to exist first --- otherwise the render fails with `ENOENT` at the very last moment, after the whole page-breaking pass has already run. The deploy workflow does the same `mkdir` before its render, for the same reason:
diff --git a/docs/Documentation/Tools.md b/docs/Documentation/Tools.md
index e9ade6a7..ec7ce6db 100644
--- a/docs/Documentation/Tools.md
+++ b/docs/Documentation/Tools.md
@@ -65,7 +65,7 @@ One of the four does not mean the same thing locally as it does in CI, on any pl
 
     test.bat
 
-The tests the toolchain has to pass. Ten steps, each stopping the run if it fails:
+The tests the toolchain has to pass. Eleven steps, each stopping the run if it fails:
 
 1. [`scripts/check_publish_policy.mjs`](#check-publish-policy) --- verifies the publish allowlist still refuses the types it is meant to. Needs neither a browser nor a built tree, so it goes first.
 2. [`scripts/check_gate_lists.mjs`](#check-gate-lists) --- verifies the two gate lists on this page still match the wrappers that run them.
@@ -76,7 +76,8 @@ The tests the toolchain has to pass. Ten steps, each stopping the run if it fail
 7. [`scripts/check_page_baseline.mjs`](#check-page-baseline) --- verifies the page-count drift guard still refuses a fall.
 8. [`scripts/check_book_coverage.mjs`](#check-book-coverage) --- verifies the build still warns about a page `docs/_book.yml` does not mention.
 9. [`scripts/check_symbol_index.mjs`](#check-symbol-index) --- verifies the symbol index still places each kind of symbol, and its drift guard still refuses a lost URL.
-10. [`scripts/check_axe_patch_equiv.mjs`](#check-axe-patch-equiv) --- verifies the vendored axe source patch still produces identical colour values.
+10. [`scripts/check_cli.mjs`](#check-cli) --- verifies `lib/cli.mjs`, the command-line parser, and each tool's recorded command-line errors.
+11. [`scripts/check_axe_patch_equiv.mjs`](#check-axe-patch-equiv) --- verifies the vendored axe source patch still produces identical colour values.
 
 POSIX:
 
@@ -89,9 +90,10 @@ POSIX:
       && node scripts/check_page_baseline.mjs \
       && node scripts/check_book_coverage.mjs \
       && node scripts/check_symbol_index.mjs \
+      && node scripts/check_cli.mjs \
       && node scripts/check_axe_patch_equiv.mjs
 
-**Seven of the ten cannot be affected by an edit confined to `docs/`**, which is why they are separate from `check.bat`. Run this one when the change touches `builder/`, `scripts/`, `lib/`, `book/`, `eval/`, `wisdom/` or `test/`, the site's scripts in `docs/assets/js/`, a wrapper, or a workflow. Both CI workflows run all ten unconditionally, as they always did, so skipping it locally cannot let a tooling regression reach `staging`.
+**Eight of the eleven cannot be affected by an edit confined to `docs/`**, which is why they are separate from `check.bat`. Run this one when the change touches `builder/`, `scripts/`, `lib/`, `book/`, `eval/`, `wisdom/` or `test/`, the site's scripts in `docs/assets/js/`, a wrapper, or a workflow. Both CI workflows run all eleven unconditionally, as they always did, so skipping it locally cannot let a tooling regression reach `staging`.
 
 The two exceptions are [`check_code_regions.mjs`](#check-code-regions) and [`check_gate_lists.mjs`](#check-gate-lists), which reads this page. The first is worth knowing in detail. Its corpus sweep tokenises every markdown file under `docs/`, so a page that provokes a rewrite into altering a code region fails it. Its fixed probes are a different matter: they run against their own sources whatever the tree holds, and they cover the *mirror* fault, where a rewrite silently stops firing. The sweep cannot see that one --- text the rewrite skipped is stashed and restored unchanged, so every region still matches. Add a page with an unusual code construct and run `test.bat`, but read the built page too.
 
@@ -516,6 +518,19 @@ A build that indexes the reference cleanly says nothing about the rules that did
 
 Exits 1 on any failed probe, 2 if it cannot run.
 
+### check_cli.mjs
+{: #check-cli }
+
+    node scripts/check_cli.mjs
+
+Verifies `lib/cli.mjs`, the module the tools read their command lines through, and each tool's recorded command-line errors. Nothing else tests how a tool reads its command line, which is how a value flag given no value came to be read as `NaN` or as the next flag. No built tree, no browser, no twinBASIC install; about a second.
+
+The module's probes cover what `parseCli` returns and refuses, with a comparison against a strict `node:util` `parseArgs` over the same argument lists, and what `numberOption`, `withUsageError` and `printHelpAndExit` do. A tool that is more lenient than a strict parse today --- one that ignores an unknown flag, say --- keeps its leniency through two of `parseCli`'s parameters, and the probes cover those too.
+
+The recorded cases are invocations that stop while the tool reads its command line, each with its exit code and what it prints on each stream: the tool's own words for the error exactly, and the opening of a usage text printed after it. A tool's cases are recorded before it moves onto `lib/cli.mjs`, so the move has to keep them. Each case runs the tool as a child process, in an empty folder of its own and with `TB_IDE` and `PUPPETEER_EXECUTABLE_PATH` naming files that do not exist, so a case that gets past the command line fails on a different message rather than starting a twinBASIC IDE or a browser. A case belongs here only if the tool stops before doing any work.
+
+Exits 1 on any failed probe or case, 2 if it cannot run.
+
 ### check_axe_patch_equiv.mjs
 {: #check-axe-patch-equiv }
 
diff --git a/lib/README.md b/lib/README.md
index 1c897851..1d7732ef 100644
--- a/lib/README.md
+++ b/lib/README.md
@@ -23,6 +23,12 @@ checks on every page that the block parse finds what a full parse finds.
 [repo-paths.mjs](repo-paths.mjs) is where every tool gets the repository root,
 `REPO_ROOT`, and `docs/`, `DOCS_DIR`, so each runs the same from any folder.
 
+[cli.mjs](cli.mjs) reads a command line against a table of options, over
+`node:util`'s `parseArgs`, and throws an error naming the problem that each
+tool prints in its own words; it also reads a number that must be one, and
+prints a usage text. `scripts/check_cli.mjs` carries its probes and the tools'
+recorded command-line cases.
+
 `scripts/check_tree_fresh.mjs` counts `lib/` among the inputs that decide the
 built bytes, beside `docs/` and `builder/`, so an edit here marks every built
 tree stale, and `check.bat` and `book.bat` refuse it until the next build.
diff --git a/lib/cli.mjs b/lib/cli.mjs
new file mode 100644
index 00000000..e18e9934
--- /dev/null
+++ b/lib/cli.mjs
@@ -0,0 +1,191 @@
+// Command-line parsing for every tool, over node:util's parseArgs.
+//
+// parseCli() reads an argument list against a table of options and either
+// returns what it found or throws a CliError that names the problem. A tool
+// turns that error into its own message with withUsageError(), so moving a tool
+// onto this module changes nothing it prints. numberOption() reads a number
+// that has to be one, and printHelpAndExit() prints a usage text.
+//
+// The defaults are strict: an unknown option, a value flag with no value, and a
+// positional the tool does not take are all errors. A tool that is more lenient
+// today keeps its leniency through two parameters, `unknown` and
+// `acceptsValue`, until Phase 3 of builder/PLAN-TOOLING-REVIEW.md makes every
+// tool strict and removes them.
+//
+// parseArgs runs loose, and this module makes a strict parse's checks itself,
+// from the tokens: a strict parse stops at the first unknown option, so it
+// cannot ignore one, and a loose parse alone takes a trailing value flag as
+// `true`. With the defaults, parseCli refuses what a strict parse refuses and
+// returns what it returns; the probes compare the two.
+//
+// scripts/check_cli.mjs carries the probes for this module, and the recorded
+// command-line cases of the tools that use it.
+
+import { parseArgs } from "node:util";
+
+/** A problem with the command line: `code` says which, and the fields name the argument. */
+export class CliError extends Error {
+  constructor(code, message, fields = {}) {
+    super(message);
+    this.name = "CliError";
+    this.code = code;
+    Object.assign(this, fields);
+  }
+}
+
+// parseArgs' own test for a value that looks like an option: two or more
+// characters, the first a dash. So `-` alone is a value, and so is "".
+const isOptionLike = (v) => v.length > 1 && v[0] === "-";
+
+// The default for acceptsValue: a value flag takes the next argument unless it
+// looks like an option, as a strict parse does; given inline, as `--port=-5`,
+// any value is taken. An argument list that ends at the flag gives it none.
+const strictValue = (value, inline) => value !== undefined && (inline || !isOptionLike(value));
+
+const camelCase = (name) => name.replace(/-([a-z0-9])/g, (_, c) => c.toUpperCase());
+
+/**
+ * Parses `argv` (without Node's own two entries) against `options`, a table in
+ * parseArgs' shape keyed by long name: `{ type: "boolean" | "string", short,
+ * multiple, default }`.
+ *
+ * Returns `{ values, positionals, tokens, ignored }`. `values` is keyed by the
+ * camelCase of each long name (`--root-dir` is `rootDir`); an absent option
+ * takes its `default`, a `multiple` one with no default is `[]`, and any other
+ * absent option is missing from `values`. A repeated option that is not
+ * `multiple` keeps its last value. `tokens` are parseArgs' tokens for the
+ * options, positionals and `--` that were kept, in order, each option's with
+ * its `key`, for a tool whose flags depend on their order. `ignored` lists the
+ * arguments dropped under `unknown: "ignore"`, as given.
+ *
+ * `positionals` is how many the tool takes: a number, or `{ min, max }`; 0 by
+ * default. `unknown` is what happens to an unknown option, a boolean given a
+ * value, and a positional beyond `max`: "error" (the default) throws; "ignore"
+ * drops it into `ignored`; "positional" makes an unknown option a positional,
+ * as given, and counts it. `acceptsValue(value, inline)` decides whether a
+ * value flag was given a value: `value` is the argument after the flag, or
+ * undefined at the end of the list, and `inline` is true for `--flag=value`.
+ * A value it accepts is stored as it is, undefined included.
+ *
+ * Throws a CliError whose code is "unknown-option", "unexpected-value",
+ * "missing-value", "unexpected-positional" or "missing-positional", with
+ * `option` (the flag as typed, `--port` or `-p`), `arg` (the argument as given)
+ * and `value` where they apply.
+ */
+export function parseCli(argv, { options = {}, positionals = 0, unknown = "error", acceptsValue = strictValue } = {}) {
+  if (!["error", "ignore", "positional"].includes(unknown)) {
+    throw new TypeError(`parseCli: unknown must be "error", "ignore" or "positional", not ${JSON.stringify(unknown)}`);
+  }
+  const { min, max } = typeof positionals === "number" ? { min: positionals, max: positionals } : { min: 0, max: Infinity, ...positionals };
+
+  const table = {};
+  for (const [name, { default: _, ...spec }] of Object.entries(options)) table[name] = spec;
+  const { tokens } = parseArgs({ args: argv, options: table, strict: false, allowPositionals: true, tokens: true });
+
+  const values = {};
+  const kept = [];
+  const ignored = [];
+  const found = [];
+  // A short-option group, -abc, is one token per letter with one index: an
+  // argument is dropped or made a positional once, however many it holds.
+  const seen = new Set();
+  const once = (list, t) => { if (!seen.has(t.index)) { seen.add(t.index); list.push(argv[t.index]); } };
+  const notOurs = (t, error) => {
+    if (unknown === "error") throw error;
+    once(unknown === "ignore" ? ignored : found, t);
+  };
+
+  for (const t of tokens) {
+    if (t.kind === "option-terminator") { kept.push(t); continue; }
+    if (t.kind === "positional") {
+      if (found.length >= max && unknown !== "positional") {
+        notOurs(t, new CliError("unexpected-positional", `unexpected argument: ${t.value}`, { arg: t.value }));
+        continue;
+      }
+      found.push(t.value);
+      kept.push(t);
+      continue;
+    }
+    const spec = options[t.name];
+    const arg = argv[t.index];
+    if (!spec) {
+      notOurs(t, new CliError("unknown-option", `unknown option: ${arg}`, { option: t.rawName, arg }));
+      continue;
+    }
+    const key = camelCase(t.name);
+    let value;
+    if (spec.type === "boolean") {
+      if (t.inlineValue) {
+        notOurs(t, new CliError("unexpected-value", `${t.rawName} takes no value`, { option: t.rawName, arg, value: t.value }));
+        continue;
+      }
+      value = true;
+    } else {
+      if (!acceptsValue(t.value, Boolean(t.inlineValue))) {
+        throw new CliError("missing-value", `${t.rawName} needs a value`, { option: t.rawName, arg, value: t.value });
+      }
+      value = t.value;
+    }
+    if (spec.multiple) (values[key] ??= []).push(value);
+    else values[key] = value;
+    kept.push({ ...t, key });
+  }
+
+  if (found.length > max) {
+    throw new CliError("unexpected-positional", `unexpected argument: ${found[max]}`, { arg: found[max] });
+  }
+  if (found.length < min) {
+    throw new CliError("missing-positional", `expected at least ${min} argument${min === 1 ? "" : "s"}, got ${found.length}`, { count: found.length });
+  }
+  for (const [name, spec] of Object.entries(options)) {
+    const key = camelCase(name);
+    if (key in values) continue;
+    if ("default" in spec) values[key] = spec.default;
+    else if (spec.multiple) values[key] = [];
+  }
+  return { values, positionals: found, tokens: kept, ignored };
+}
+
+/**
+ * Reads `value`, the text given to the flag `option`, as a number: a whole one
+ * when `integer`, between `min` and `max` inclusive. Blank text is not a
+ * number, though Number("") is 0. Throws a CliError "bad-number", whose message
+ * is `message(value)` when that is given.
+ */
+export function numberOption(value, { option, integer = false, min = -Infinity, max = Infinity, message } = {}) {
+  const n = typeof value === "string" && value.trim() !== "" ? Number(value) : Number.NaN;
+  if (Number.isFinite(n) && (!integer || Number.isInteger(n)) && n >= min && n <= max) return n;
+  const range = Number.isFinite(min) && Number.isFinite(max) ? ` from ${min} to ${max}`
+    : Number.isFinite(min) ? ` of at least ${min}`
+    : Number.isFinite(max) ? ` of at most ${max}`
+    : "";
+  const text = message ? message(value) : `${option} expects ${integer ? "a whole number" : "a number"}${range}, got: ${value}`;
+  throw new CliError("bad-number", text, { option, value });
+}
+
+// A stream named "stdout" or "stderr", or any object with a write(), which is
+// how the probes read what was printed.
+const streamOf = (stream) => (typeof stream === "string" ? process[stream] : stream);
+const line = (text) => (text.endsWith("\n") ? text : `${text}\n`);
+
+/**
+ * Runs `fn` and returns what it returns. A CliError thrown from it is printed
+ * to `stream` -- `format(err)`, or the error's own message -- and the process
+ * exits with `exitCode`; anything else is thrown on. `exit` stands in for
+ * process.exit in the probes.
+ */
+export function withUsageError(fn, { stream = "stderr", exitCode = 2, format = (err) => err.message, exit = process.exit } = {}) {
+  try {
+    return fn();
+  } catch (err) {
+    if (!(err instanceof CliError)) throw err;
+    streamOf(stream).write(line(format(err)));
+    return exit(exitCode);
+  }
+}
+
+/** Prints `text` to `stream` and exits with `exitCode`; `exit` as for withUsageError. */
+export function printHelpAndExit(text, { stream = "stdout", exitCode = 0, exit = process.exit } = {}) {
+  streamOf(stream).write(line(text));
+  return exit(exitCode);
+}
diff --git a/scripts/check_cli.mjs b/scripts/check_cli.mjs
new file mode 100644
index 00000000..b7c3e6d7
--- /dev/null
+++ b/scripts/check_cli.mjs
@@ -0,0 +1,310 @@
+// Self-test for lib/cli.mjs, the command-line parser the tools move onto, and
+// the tools' own command-line cases.
+//
+//     node scripts/check_cli.mjs
+//
+// Nothing else tests how any tool reads its command line, which is how a
+// value flag given no value came to be read as NaN or as the next flag, and
+// `--help` as an output folder. So this makes two assertions.
+//
+// The module's probes: what parseCli returns and refuses, including a
+// comparison with a strict node:util parseArgs over the same argument lists,
+// and what numberOption, withUsageError and printHelpAndExit do.
+//
+// The recorded cases: invocations that stop while the tool reads its command
+// line, each with the exit code and the text printed on each stream. A tool's
+// cases are recorded from its behaviour before it moves onto lib/cli.mjs, so
+// the move has to keep them. A case pins the tool's own words for the error
+// exactly; a usage text printed after it is matched by its opening, so adding
+// a flag to a tool's usage does not fail this gate. A string is the whole
+// stream; a RegExp must match it; a stream a case does not name must be empty.
+//
+// Only invocations that stop while reading the command line belong here. Each
+// runs as a child process, all of them at once, each with a time limit, in an
+// empty folder of its own and with TB_IDE and PUPPETEER_EXECUTABLE_PATH naming
+// files that do not exist. So a case that gets past the command line fails on
+// a message of a different kind rather than starting a twinBASIC IDE or a
+// browser, and a default path relative to the working folder, such as
+// tbdocs's `docs`, finds nothing. No tree, no browser, no install; about a
+// second.
+
+import { execFile } from "node:child_process";
+import { mkdir, mkdtemp, rm } from "node:fs/promises";
+import { availableParallelism, tmpdir } from "node:os";
+import path from "node:path";
+import { parseArgs } from "node:util";
+import { CliError, numberOption, parseCli, printHelpAndExit, withUsageError } from "../lib/cli.mjs";
+import { REPO_ROOT } from "../lib/repo-paths.mjs";
+import { createProbes, exitOnCrash } from "./lib/gate-probes.mjs";
+
+exitOnCrash();
+
+const { check, report } = createProbes("check_cli");
+const show = (x) => JSON.stringify(x);
+const caught = (fn) => {
+  try {
+    fn();
+    return null;
+  } catch (err) {
+    return err;
+  }
+};
+const cliError = (fn, code) => {
+  const err = caught(fn);
+  return err instanceof CliError && err.code === code ? err : null;
+};
+
+// ------------------------------------------------------------ parseCli
+
+const OPTIONS = {
+  verbose: { type: "boolean", short: "v" },
+  port: { type: "string", short: "p" },
+  "root-dir": { type: "string" },
+  forbid: { type: "string", multiple: true },
+};
+
+{
+  const { values } = parseCli([], {
+    options: { ...OPTIONS, "root-dir": { type: "string", default: "docs" } },
+  });
+  check("an absent option takes its default, a multiple one [], any other none", show(values) === show({ rootDir: "docs", forbid: [] }),
+    show(values));
+}
+{
+  const { values } = parseCli(["--root-dir", "a", "--root-dir=b", "-v", "--forbid", "x", "--forbid=y"], { options: OPTIONS });
+  check("values are keyed in camelCase; a repeat keeps the last, a multiple one all in order",
+    show(values) === show({ rootDir: "b", verbose: true, forbid: ["x", "y"] }), show(values));
+}
+{
+  const err = cliError(() => parseCli(["--port"], { options: OPTIONS }), "missing-value");
+  check("a value flag at the end has no value", err?.option === "--port" && err.value === undefined && err.message === "--port needs a value",
+    show(err));
+  const short = cliError(() => parseCli(["-p"], { options: OPTIONS }), "missing-value");
+  check("the error names the flag as typed", short?.option === "-p" && short.message === "-p needs a value", show(short));
+}
+{
+  const err = cliError(() => parseCli(["--port", "--verbose"], { options: OPTIONS }), "missing-value");
+  check("a value flag followed by a flag has no value", err?.value === "--verbose", show(err));
+  const { values } = parseCli(["--port=-5", "-p", "-"], { options: OPTIONS });
+  check("an inline value may start with a dash, and a lone - is a value", values.port === "-", show(values));
+  const inline = parseCli(["--port=-5"], { options: OPTIONS }).values;
+  check("--port=-5 is -5", inline.port === "-5", show(inline));
+}
+{
+  const err = cliError(() => parseCli(["--bogus=1"], { options: OPTIONS }), "unknown-option");
+  check("an unknown option is an error that names it as given",
+    err?.option === "--bogus" && err.arg === "--bogus=1" && err.message === "unknown option: --bogus=1", show(err));
+  const bool = cliError(() => parseCli(["--verbose=1"], { options: OPTIONS }), "unexpected-value");
+  check("a boolean given a value is an error", bool?.message === "--verbose takes no value", show(bool));
+  const extra = cliError(() => parseCli(["a"], { options: OPTIONS }), "unexpected-positional");
+  check("a positional the tool does not take is an error", extra?.arg === "a" && extra.message === "unexpected argument: a", show(extra));
+}
+{
+  const spec = { options: OPTIONS, positionals: { max: 1 }, unknown: "ignore" };
+  const r = parseCli(["--bogus", "x", "t", "--verbose=1", "--port", "80", "-q", "u"], spec);
+  check("unknown: ignore drops unknown options, a boolean's value and surplus positionals, in order",
+    show(r.values) === show({ port: "80", forbid: [] }) && show(r.positionals) === show(["x"])
+      && show(r.ignored) === show(["--bogus", "t", "--verbose=1", "-q", "u"]),
+    show(r));
+  const err = cliError(() => parseCli(["--bogus", "--port"], spec), "missing-value");
+  check("unknown: ignore still refuses a value flag with no value", err?.option === "--port", show(err));
+}
+{
+  const r = parseCli(["--x", "-5", "-ab", "t", "--verbose", "--y=1"], { options: OPTIONS, positionals: { max: Infinity }, unknown: "positional" });
+  check("unknown: positional makes each unknown option one positional, as given",
+    show(r.positionals) === show(["--x", "-5", "-ab", "t", "--y=1"]) && r.values.verbose === true, show(r));
+  const err = cliError(() => parseCli(["--x", "t"], { options: OPTIONS, positionals: 1, unknown: "positional" }), "unexpected-positional");
+  check("unknown: positional counts them", err?.arg === "t", show(err));
+}
+{
+  const few = cliError(() => parseCli([], { options: OPTIONS, positionals: 1 }), "missing-positional");
+  check("too few positionals is an error", few?.message === "expected at least 1 argument, got 0", show(few));
+  const many = cliError(() => parseCli(["a", "b"], { options: OPTIONS, positionals: { min: 1, max: 1 } }), "unexpected-positional");
+  check("too many positionals is an error naming the first extra", many?.arg === "b", show(many));
+  const r = parseCli(["--", "--verbose"], { options: OPTIONS, positionals: 1 });
+  check("after -- every argument is a positional", show(r.positionals) === show(["--verbose"]) && !("verbose" in r.values)
+    && r.tokens[0].kind === "option-terminator", show(r));
+}
+{
+  const r = parseCli(["--no-check", "x", "--check", "-v"], {
+    options: { "no-check": { type: "boolean" }, check: { type: "boolean" }, verbose: { type: "boolean", short: "v" } },
+    positionals: 1,
+  });
+  check("tokens keep the order, each option's with its key",
+    show(r.tokens.map((t) => t.key ?? t.value)) === show(["noCheck", "x", "check", "verbose"]), show(r.tokens));
+}
+{
+  const truthy = { options: OPTIONS, acceptsValue: (v) => Boolean(v) };
+  check("acceptsValue can take a flag as a value", parseCli(["--port", "--verbose"], truthy).values.port === "--verbose");
+  check("acceptsValue can refuse an empty value", Boolean(cliError(() => parseCli(["--port", ""], truthy), "missing-value")));
+  const any = parseCli(["--port"], { options: { port: { type: "string", default: "d" } }, acceptsValue: () => true }).values;
+  check("a value acceptsValue takes is stored as it is, undefined included", "port" in any && any.port === undefined, show(any));
+}
+check("unknown takes only its three values", caught(() => parseCli([], { unknown: "warn" })) instanceof TypeError);
+
+// With the defaults, parseCli refuses what a strict parseArgs refuses, in the
+// same kind, and otherwise returns the same values and positionals.
+{
+  const KINDS = {
+    ERR_PARSE_ARGS_UNKNOWN_OPTION: ["unknown-option"],
+    ERR_PARSE_ARGS_INVALID_OPTION_VALUE: ["missing-value", "unexpected-value"],
+    ERR_PARSE_ARGS_UNEXPECTED_POSITIONAL: ["unexpected-positional"],
+  };
+  const camel = (name) => name.replace(/-([a-z0-9])/g, (_, c) => c.toUpperCase());
+  const outcome = (fn, strict) => {
+    try {
+      const { values, positionals } = fn();
+      const entries = Object.entries(values)
+        .map(([k, v]) => [strict ? camel(k) : k, v])
+        .filter(([k, v]) => !(Array.isArray(v) && v.length === 0 && !strict && OPTIONS[k]?.multiple))
+        .sort(([a], [b]) => a.localeCompare(b));
+      return show({ values: entries, positionals });
+    } catch (err) {
+      return strict ? show(KINDS[err.code] ?? err.code) : show(Object.values(KINDS).find((k) => k.includes(err.code)) ?? err.code);
+    }
+  };
+  const LISTS = [
+    [], ["--verbose"], ["-v"], ["--port", "80"], ["--port=80"], ["-p", "80"], ["-p80"], ["-vp", "80"], ["-pv"],
+    ["--port"], ["-p"], ["--port", "--verbose"], ["--port", "-5"], ["--port=-5"], ["--port", "-"], ["--port", ""],
+    ["--port="], ["--port", "--"], ["--verbose=1"], ["--verbose="], ["--bogus"], ["--bogus=1"], ["-x"], ["-5"], ["--no-verbose"],
+    ["--forbid", "a", "--forbid", "b"], ["--port", "1", "--port", "2"], ["--root-dir", "x"],
+    ["a"], ["a", "--verbose", "b"], ["--", "--verbose"], ["--port", "1", "--", "-x"],
+  ];
+  const differ = [];
+  for (const allow of [true, false]) {
+    for (const args of LISTS) {
+      const strict = outcome(() => parseArgs({ args, options: OPTIONS, strict: true, allowPositionals: allow }), true);
+      const ours = outcome(() => parseCli(args, { options: OPTIONS, positionals: allow ? { max: Infinity } : 0 }), false);
+      if (strict !== ours) differ.push(`${allow ? "" : "no positionals: "}${show(args)}\n  parseArgs ${strict}\n  parseCli  ${ours}`);
+    }
+  }
+  check(`the defaults agree with a strict parseArgs on ${LISTS.length * 2} argument lists`, differ.length === 0, differ.join("\n"));
+}
+
+// ------------------------------------------------------------ numberOption
+
+{
+  const port = { option: "--port", integer: true, min: 1, max: 65535 };
+  check("numberOption reads a number in range", numberOption("8080", port) === 8080);
+  const low = cliError(() => numberOption("0", port), "bad-number");
+  check("numberOption refuses one out of range, naming the range",
+    low?.message === "--port expects a whole number from 1 to 65535, got: 0" && low.option === "--port", show(low));
+  check("numberOption refuses blank text, which Number reads as 0", Boolean(cliError(() => numberOption("", port), "bad-number")));
+  check("numberOption refuses a fraction where a whole number is wanted", Boolean(cliError(() => numberOption("1.5", port), "bad-number")));
+  check("numberOption takes a fraction otherwise", numberOption("1.5", { option: "--t", min: 0 }) === 1.5);
+  const nan = cliError(() => numberOption("abc", { option: "--t", min: 0 }), "bad-number");
+  check("numberOption refuses text that is not a number", nan?.message === "--t expects a number of at least 0, got: abc", show(nan));
+  const own = cliError(() => numberOption(undefined, { option: "--t", message: (v) => `--t: ${v}?` }), "bad-number");
+  check("numberOption takes the tool's own message", own?.message === "--t: undefined?", show(own));
+}
+
+// ------------------------------------------------------------ printing and exiting
+
+const EXITED = Symbol("exited");
+function capture(fn) {
+  const out = { text: "", code: null };
+  const stream = { write: (s) => { out.text += s; } };
+  const exit = (code) => { out.code = code; throw EXITED; };
+  const err = caught(() => fn(stream, exit));
+  if (err !== null && err !== EXITED) throw err;
+  return out;
+}
+{
+  let result;
+  const quiet = capture((stream, exit) => { result = withUsageError(() => 42, { stream, exit }); });
+  check("withUsageError returns what fn returns, printing nothing", result === 42 && quiet.text === "" && quiet.code === null, show(quiet));
+  const out = capture((stream, exit) => withUsageError(() => parseCli(["--port"], { options: OPTIONS }), { stream, exit, exitCode: 4 }));
+  check("withUsageError prints the message and exits with the code", out.text === "--port needs a value\n" && out.code === 4, show(out));
+  const own = capture((stream, exit) => withUsageError(() => parseCli(["--bogus"], { options: OPTIONS }), {
+    stream, exit, format: (err) => `usage: tool\n${err.code}\n`,
+  }));
+  check("withUsageError prints the tool's own text, adding no second newline", own.text === "usage: tool\nunknown-option\n" && own.code === 2,
+    show(own));
+  const other = caught(() => capture((stream, exit) => withUsageError(() => { throw new RangeError("boom"); }, { stream, exit })));
+  check("withUsageError throws on anything but a CliError", other instanceof RangeError);
+}
+{
+  const out = capture((stream, exit) => printHelpAndExit("usage: tool", { stream, exit }));
+  check("printHelpAndExit prints the text and exits 0", out.text === "usage: tool\n" && out.code === 0, show(out));
+  const err = capture((stream, exit) => printHelpAndExit("usage: tool\n", { stream, exit, exitCode: 2 }));
+  check("printHelpAndExit takes the tool's exit code", err.text === "usage: tool\n" && err.code === 2, show(err));
+}
+
+// ------------------------------------------------------------ the recorded cases
+
+const CASES = [
+  // Recorded in C47, from the behaviour C18 settled: a command-line error in
+  // tbdocs and check_links exits 4, outside the 1/2/3 bitmask of the link and
+  // integrity checks, so it never reads as a broken link. A value flag has no
+  // value at the end of the list or before another flag, and --port is a whole
+  // number from 1 to 65535. check_links prints on stdout, and requires a value
+  // only at the end: before a flag, it takes the flag as the value.
+  { tool: "builder/tbdocs.mjs", args: ["--port"], exit: 4, stderr: "--port needs a value\n" },
+  { tool: "builder/tbdocs.mjs", args: ["--dest", "--no-pdf"], exit: 4, stderr: "--dest needs a value\n" },
+  { tool: "builder/tbdocs.mjs", args: ["--port=0"], exit: 4, stderr: "--port expects a port number from 1 to 65535, got: 0\n" },
+  { tool: "builder/tbdocs.mjs", args: ["--bogus"], exit: 4, stderr: "Unknown argument: --bogus\n" },
+  { tool: "scripts/check_links.mjs", args: ["no-such-tree", "--root-dir"], exit: 4, stdout: "error: --root-dir requires a value\n" },
+  { tool: "scripts/check_links.mjs", args: ["no-such-tree", "--forbid"], exit: 4, stdout: "error: --forbid requires a value\n" },
+
+  // Recorded in C47, from the behaviour C17 settled: in the four harness tools
+  // that check, a value flag with no value, at the end or before another flag,
+  // exits 2. tbbuild follows the message with its usage line.
+  { tool: "scripts/tbbuild.mjs", args: ["--port"], exit: 2, stderr: /^--port needs a value\nusage: node scripts\/tbbuild\.mjs / },
+  { tool: "scripts/tbbuild.mjs", args: ["--timeout", "--keep"], exit: 2, stderr: /^--timeout needs a value\nusage: node scripts\/tbbuild\.mjs / },
+  { tool: "scripts/check_examples.mjs", args: ["--jobs"], exit: 2, stderr: "check_examples: --jobs needs a value\n" },
+  { tool: "scripts/check_examples.mjs", args: ["--port", "--json"], exit: 2, stderr: "check_examples: --port needs a value\n" },
+  { tool: "scripts/census_attributes.mjs", args: ["--out"], exit: 2, stderr: "--out needs a value\n" },
+  { tool: "scripts/census_attributes.mjs", args: ["--src", "--json"], exit: 2, stderr: "--src needs a value\n" },
+  { tool: "scripts/build_package_api.mjs", args: ["--out"], exit: 2, stderr: "--out needs a value\n" },
+  { tool: "scripts/build_package_api.mjs", args: ["--src", "--check"], exit: 2, stderr: "--src needs a value\n" },
+];
+
+const TIMEOUT_MS = 30_000;
+
+function runCase({ tool, args }, cwd, env) {
+  return new Promise((resolve) => {
+    execFile(process.execPath, [path.join(REPO_ROOT, tool), ...args], { cwd, env, timeout: TIMEOUT_MS, windowsHide: true },
+      (error, stdout, stderr) => {
+        const exit = !error ? 0 : error.killed ? `killed after ${TIMEOUT_MS / 1000} s` : error.code;
+        resolve({ exit, stdout, stderr });
+      });
+  });
+}
+
+const matches = (expected = "", text) => (expected instanceof RegExp ? expected.test(text) : text === expected);
+const expectation = (expected = "") => (expected instanceof RegExp ? String(expected) : show(expected));
+const clip = (text) => show(text.length > 400 ? `${text.slice(0, 400)}...` : text);
+
+const scratch = await mkdtemp(path.join(tmpdir(), "tb-check-cli-"));
+try {
+  const env = {
+    ...process.env,
+    TB_IDE: path.join(scratch, "no-ide", "twinBASIC.exe"),
+    PUPPETEER_EXECUTABLE_PATH: path.join(scratch, "no-browser", "chrome.exe"),
+  };
+  delete env.TBBUILD_SHOW;
+  const results = new Array(CASES.length);
+  let next = 0;
+  const lane = async () => {
+    while (next < CASES.length) {
+      const i = next++;
+      const cwd = path.join(scratch, `case-${i}`);
+      await mkdir(cwd);
+      results[i] = await runCase(CASES[i], cwd, env);
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(availableParallelism(), CASES.length) }, lane));
+  CASES.forEach((c, i) => {
+    const got = results[i];
+    const ok = got.exit === c.exit && matches(c.stdout, got.stdout) && matches(c.stderr, got.stderr);
+    check(`${path.basename(c.tool, ".mjs")} ${c.args.join(" ")}: exit ${c.exit}, ${c.stdout ? "stdout" : "stderr"}`, ok,
+      `expected exit ${c.exit}, stdout ${expectation(c.stdout)}, stderr ${expectation(c.stderr)}\n`
+        + `got      exit ${got.exit}, stdout ${clip(got.stdout)}, stderr ${clip(got.stderr)}`);
+  });
+} finally {
+  await rm(scratch, { recursive: true, force: true });
+}
+
+// ------------------------------------------------------------ report
+
+process.exit(report());
diff --git a/test.bat b/test.bat
index fdbfa517..c4b93bfe 100644
--- a/test.bat
+++ b/test.bat
@@ -109,6 +109,14 @@ node scripts/check_book_coverage.mjs
 @rem Fixtures only: no tree, no install, ~100 ms.
 node scripts/check_symbol_index.mjs
 @if errorlevel 1 goto :fail
+@rem Nothing else tests how a tool reads its command line, which is how a
+@rem value flag given no value came to be read as NaN or as the next flag.
+@rem lib/cli.mjs's probes, then each tool's recorded command-line errors:
+@rem the tool runs with an IDE and a browser that do not exist, so a case
+@rem that gets past its command line fails rather than starting either.
+@rem No tree, no browser, no install, ~1 s.
+node scripts/check_cli.mjs
+@if errorlevel 1 goto :fail
 @rem check_a11y.mjs injects a PATCHED axe bundle (plain-color-fields,
 @rem -26 % on a realistic page set). The patch asserts its substitution
 @rem targets, so an axe-core bump fails loudly; this catches the other

From 9f9032bee6f90006953b51c8300407a14dfc4a5e Mon Sep 17 00:00:00 2001
From: Kuba Sunderland-Ober <kuba@mareimbrium.org>
Date: Sun, 27 Sep 2026 18:33:01 +0200
Subject: [PATCH 25/27] scripts: the a11y and diagram tools parse through
 lib/cli.mjs

---
 builder/PLAN-TOOLING-REVIEW.md     | 35 +++++++++++
 lib/cli.mjs                        | 18 ++++--
 scripts/build_dot_metrics.mjs      |  3 +-
 scripts/check_a11y.mjs             | 39 ++++++------
 scripts/check_a11y_fingerprint.mjs | 99 ++++++++++++++++--------------
 scripts/check_axe_patch_equiv.mjs  | 29 +++++----
 scripts/check_cli.mjs              | 42 +++++++++++++
 scripts/check_dot_fit.mjs          |  3 +-
 scripts/check_tree_fresh.mjs       | 39 +++++++-----
 scripts/pick_a11y_sample.mjs       | 55 +++++++++--------
 scripts/sweep_a11y.mjs             | 76 ++++++++++++-----------
 11 files changed, 278 insertions(+), 160 deletions(-)

diff --git a/builder/PLAN-TOOLING-REVIEW.md b/builder/PLAN-TOOLING-REVIEW.md
index 3bf36ff3..d3a85529 100644
--- a/builder/PLAN-TOOLING-REVIEW.md
+++ b/builder/PLAN-TOOLING-REVIEW.md
@@ -1497,6 +1497,41 @@ typo included, which C72 removes. Their cases go into `check_cli.mjs` first.
 **Verify.** `check_cli.mjs`'s cases for the eight, recorded before and passing after;
 `check.bat` unchanged.
 
+**Landed.** All eight parse through `parseCli`. The six with a loop take `acceptsValue:
+Boolean`, which is their truthiness test (a missing or empty value is an error, a following
+flag is taken as the value), and `withUsageError` with `format: (err) => \`unknown arg:
+${err.arg}\``, since the loop printed every refused argument as given; positionals stay at 0.
+The loops answer `--help` and fingerprint's `--list` on the spot, so an error before them wins
+and nothing after them is read: `lib/cli.mjs` gained `stopAt` for this, with `stopped` in the
+result and three probes. `help` (short `h`) is in `stopAt` in the five that answer it, and each
+prints its usage unchanged through `printHelpAndExit`, to stdout (`check_a11y_fingerprint`,
+`check_axe_patch_equiv`, `check_tree_fresh`) or stderr (`pick_a11y_sample`, `sweep_a11y`);
+`check_a11y` has none and still refuses `--help`. `pick_a11y_sample`'s mode is the last of
+`--check`, `--propose` and `--census` in `tokens`; numbers are still read by `parseInt` and
+`parseFloat`. `check_dot_fit` and `build_dot_metrics` declare their one boolean with `unknown:
+"ignore"`, which cannot throw. The edit was a Sonnet agent's (43 calls, ~192k, 10.6 min),
+reviewed line by line; it gave the booleans `default: false`, so each value is a boolean.
+
+The cases were recorded from the unedited tools first: 25 across six tools (`--help`, an
+unknown flag, a trailing and an empty value, `--theme`/`--viewport` refused by C20's check);
+the two diagram tools ignore every argument and have none. `check_cli` now makes 78 checks, 39
+probes and 39 cases. The kit's `c48-tools.mjs` writes HEAD's copy of each tool beside the real
+one (`scripts/c48-head-<name>.mjs`, removed at the end) and runs both on 20 real invocations:
+the same exit and output on all 20, but for a stack-trace line number in one that fails alike
+on both (`--pages --list`, which takes `--list` as the page list). It covers the modes' order
+(`--propose --check` is check, `--check --census` census), `--help --bogus` against `--bogus
+--help`, `--list --bogus`, a flag taken as a value, `check_dot_fit` and `build_dot_metrics
+--check` with stray arguments, and `check_tree_fresh` with `--tree` twice. A HEAD worktree
+does not serve here: it lacks `node_modules/axe-core` and `perf/results`, which these tools
+read through `REPO_ROOT`.
+
+What differs, none of it a recorded case: `--name=value` is accepted (departure 9); after
+`--` an argument is a positional, so `check_dot_fit -- --verbose` is no longer verbose; and a
+short-option group is split into its letters, so `-hx` prints the usage where the loop said
+`unknown arg: -hx`. `build.bat`, `check.bat` (the a11y line unchanged, run by the migrated
+`check_tree_fresh`, `check_dot_fit`, `pick_a11y_sample --check` and `check_a11y`) and `test.bat`
+exit 0.
+
 ### C49 — `scripts: the harness tools parse through lib/cli.mjs`
 
 **A7-5 (R2)'s `die()` half, and L1-2's copies.** `tbbuild`, `tbrun` and `addin_test` each
diff --git a/lib/cli.mjs b/lib/cli.mjs
index e18e9934..59bfe0c8 100644
--- a/lib/cli.mjs
+++ b/lib/cli.mjs
@@ -49,7 +49,7 @@ const camelCase = (name) => name.replace(/-([a-z0-9])/g, (_, c) => c.toUpperCase
  * parseArgs' shape keyed by long name: `{ type: "boolean" | "string", short,
  * multiple, default }`.
  *
- * Returns `{ values, positionals, tokens, ignored }`. `values` is keyed by the
+ * Returns `{ values, positionals, tokens, ignored, stopped }`. `values` is keyed by the
  * camelCase of each long name (`--root-dir` is `rootDir`); an absent option
  * takes its `default`, a `multiple` one with no default is `[]`, and any other
  * absent option is missing from `values`. A repeated option that is not
@@ -65,14 +65,18 @@ const camelCase = (name) => name.replace(/-([a-z0-9])/g, (_, c) => c.toUpperCase
  * as given, and counts it. `acceptsValue(value, inline)` decides whether a
  * value flag was given a value: `value` is the argument after the flag, or
  * undefined at the end of the list, and `inline` is true for `--flag=value`.
- * A value it accepts is stored as it is, undefined included.
+ * A value it accepts is stored as it is, undefined included. `stopAt` names
+ * options that end the parse where they stand, as a hand-written loop that
+ * answers `--help` or `--list` on the spot does: nothing after the first of
+ * them is read or checked, the positional count included, and `stopped` in the
+ * result is its key.
  *
  * Throws a CliError whose code is "unknown-option", "unexpected-value",
  * "missing-value", "unexpected-positional" or "missing-positional", with
  * `option` (the flag as typed, `--port` or `-p`), `arg` (the argument as given)
  * and `value` where they apply.
  */
-export function parseCli(argv, { options = {}, positionals = 0, unknown = "error", acceptsValue = strictValue } = {}) {
+export function parseCli(argv, { options = {}, positionals = 0, unknown = "error", acceptsValue = strictValue, stopAt = [] } = {}) {
   if (!["error", "ignore", "positional"].includes(unknown)) {
     throw new TypeError(`parseCli: unknown must be "error", "ignore" or "positional", not ${JSON.stringify(unknown)}`);
   }
@@ -86,6 +90,7 @@ export function parseCli(argv, { options = {}, positionals = 0, unknown = "error
   const kept = [];
   const ignored = [];
   const found = [];
+  let stopped;
   // A short-option group, -abc, is one token per letter with one index: an
   // argument is dropped or made a positional once, however many it holds.
   const seen = new Set();
@@ -129,12 +134,13 @@ export function parseCli(argv, { options = {}, positionals = 0, unknown = "error
     if (spec.multiple) (values[key] ??= []).push(value);
     else values[key] = value;
     kept.push({ ...t, key });
+    if (stopAt.includes(t.name)) { stopped = key; break; }
   }
 
-  if (found.length > max) {
+  if (found.length > max && !stopped) {
     throw new CliError("unexpected-positional", `unexpected argument: ${found[max]}`, { arg: found[max] });
   }
-  if (found.length < min) {
+  if (found.length < min && !stopped) {
     throw new CliError("missing-positional", `expected at least ${min} argument${min === 1 ? "" : "s"}, got ${found.length}`, { count: found.length });
   }
   for (const [name, spec] of Object.entries(options)) {
@@ -143,7 +149,7 @@ export function parseCli(argv, { options = {}, positionals = 0, unknown = "error
     if ("default" in spec) values[key] = spec.default;
     else if (spec.multiple) values[key] = [];
   }
-  return { values, positionals: found, tokens: kept, ignored };
+  return { values, positionals: found, tokens: kept, ignored, stopped };
 }
 
 /**
diff --git a/scripts/build_dot_metrics.mjs b/scripts/build_dot_metrics.mjs
index 4c6dd01b..b7b1ea13 100644
--- a/scripts/build_dot_metrics.mjs
+++ b/scripts/build_dot_metrics.mjs
@@ -36,6 +36,7 @@ import path from "node:path";
 import { withBrowser } from "./lib/browser.mjs";
 import { exitOnCrash } from "./lib/gate-probes.mjs";
 import { openInterPage } from "./lib/inter-page.mjs";
+import { parseCli } from "../lib/cli.mjs";
 import { REPO_ROOT } from "../lib/repo-paths.mjs";
 
 // A crash exits 2, where 1 is --check finding the table stale.
@@ -56,7 +57,7 @@ const VARIANTS = [
   { key: "boldItalic", weight: 700, style: "italic" },
 ];
 
-const check = process.argv.includes("--check");
+const check = parseCli(process.argv.slice(2), { options: { check: { type: "boolean" } }, unknown: "ignore" }).values.check === true;
 
 const table = await withBrowser(async (browser) => {
   const page = await openInterPage(browser, "dot-metrics", { css: "body{margin:0}" });
diff --git a/scripts/check_a11y.mjs b/scripts/check_a11y.mjs
index 2e580d3f..415eebe1 100644
--- a/scripts/check_a11y.mjs
+++ b/scripts/check_a11y.mjs
@@ -60,24 +60,27 @@ import {
   runMatrix,
 } from "./lib/axe-scan.mjs";
 import { withBrowser } from "./lib/browser.mjs";
-
-const args = process.argv.slice(2);
-let rootDir = DEFAULT_ROOT_DIR;
-let themeArg = "both";
-let viewportArg = "both";
-let stockAxe = false;
-let minified = false;
-for (let i = 0; i < args.length; i++) {
-  if (args[i] === "--root-dir" && args[i + 1]) rootDir = args[++i];
-  else if (args[i] === "--theme" && args[i + 1]) themeArg = args[++i];
-  else if (args[i] === "--viewport" && args[i + 1]) viewportArg = args[++i];
-  else if (args[i] === "--stock-axe") stockAxe = true;
-  else if (args[i] === "--minified") minified = true;
-  else {
-    console.error(`unknown arg: ${args[i]}`);
-    process.exit(2);
-  }
-}
+import { parseCli, withUsageError } from "../lib/cli.mjs";
+
+const { values } = withUsageError(
+  () =>
+    parseCli(process.argv.slice(2), {
+      options: {
+        "root-dir": { type: "string", default: DEFAULT_ROOT_DIR },
+        theme: { type: "string", default: "both" },
+        viewport: { type: "string", default: "both" },
+        "stock-axe": { type: "boolean", default: false },
+        minified: { type: "boolean", default: false },
+      },
+      acceptsValue: Boolean,
+    }),
+  { format: (err) => `unknown arg: ${err.arg}` },
+);
+let rootDir = values.rootDir;
+let themeArg = values.theme;
+let viewportArg = values.viewport;
+let stockAxe = values.stockAxe;
+let minified = values.minified;
 rootDir = resolve(rootDir);
 
 const themes = pick("theme", themeArg, THEMES);
diff --git a/scripts/check_a11y_fingerprint.mjs b/scripts/check_a11y_fingerprint.mjs
index b0a71975..2df46913 100644
--- a/scripts/check_a11y_fingerprint.mjs
+++ b/scripts/check_a11y_fingerprint.mjs
@@ -74,57 +74,64 @@ import {
   SOURCE_PATCHES,
 } from "./lib/axe-scan.mjs";
 import { withBrowser } from "./lib/browser.mjs";
+import { parseCli, printHelpAndExit, withUsageError } from "../lib/cli.mjs";
 
 // ---- CLI ------------------------------------------------------------------
-let baselineLabel = "production";
-let candidateLabel = "production";
-let rootDir = DEFAULT_ROOT_DIR;
-let themeArg = "both";
-let viewportArg = "both";
-let pagesArg = null;
-let jsonOut = null;
-let unminified = false;
-let patchesArg = "";
+const cli = withUsageError(
+  () =>
+    parseCli(process.argv.slice(2), {
+      options: {
+        baseline: { type: "string", default: "production" },
+        candidate: { type: "string", default: "production" },
+        "root-dir": { type: "string", default: DEFAULT_ROOT_DIR },
+        theme: { type: "string", default: "both" },
+        viewport: { type: "string", default: "both" },
+        pages: { type: "string" },
+        json: { type: "string" },
+        unminified: { type: "boolean", default: false },
+        patches: { type: "string", default: "" },
+        list: { type: "boolean" },
+        help: { type: "boolean", short: "h" },
+      },
+      acceptsValue: Boolean,
+      stopAt: ["list", "help"],
+    }),
+  { format: (err) => `unknown arg: ${err.arg}` },
+);
 
-const args = process.argv.slice(2);
-for (let i = 0; i < args.length; i++) {
-  const a = args[i];
-  if (a === "--baseline" && args[i + 1]) baselineLabel = args[++i];
-  else if (a === "--candidate" && args[i + 1]) candidateLabel = args[++i];
-  else if (a === "--root-dir" && args[i + 1]) rootDir = args[++i];
-  else if (a === "--theme" && args[i + 1]) themeArg = args[++i];
-  else if (a === "--viewport" && args[i + 1]) viewportArg = args[++i];
-  else if (a === "--pages" && args[i + 1]) pagesArg = args[++i].split(",");
-  else if (a === "--json" && args[i + 1]) jsonOut = args[++i];
-  else if (a === "--unminified") unminified = true;
-  else if (a === "--patches" && args[i + 1]) patchesArg = args[++i];
-  else if (a === "--list") {
-    console.log(`axe-core ${axeVersion()}\n`);
-    console.log("patches:");
-    for (const [label, p] of Object.entries(SOURCE_PATCHES)) {
-      console.log(`  ${label.padEnd(24)} ${p.describe}`);
-    }
-    console.log("");
-    console.log("schemes:");
-    for (const label of Object.keys(SCHEMES)) {
-      const s = getScheme(label);
-      const flag = s.gates === false ? "  [does not gate]" : "";
-      const p = s.patches.length ? `  (+${s.patches.join(", ")})` : "  (stock)";
-      console.log(`  ${label.padEnd(20)} ${s.describe}${flag}${p}`);
-    }
-    process.exit(0);
-  } else if (a === "-h" || a === "--help") {
-    console.log(
-      "usage: node scripts/check_a11y_fingerprint.mjs [--baseline SCHEME] " +
-        "[--candidate SCHEME] [--root-dir DIR] [--theme T] [--viewport V] " +
-        "[--pages P,P] [--json FILE] [--unminified] [--list]"
-    );
-    process.exit(0);
-  } else {
-    console.error(`unknown arg: ${a}`);
-    process.exit(2);
+if (cli.stopped === "list") {
+  console.log(`axe-core ${axeVersion()}\n`);
+  console.log("patches:");
+  for (const [label, p] of Object.entries(SOURCE_PATCHES)) {
+    console.log(`  ${label.padEnd(24)} ${p.describe}`);
   }
+  console.log("");
+  console.log("schemes:");
+  for (const label of Object.keys(SCHEMES)) {
+    const s = getScheme(label);
+    const flag = s.gates === false ? "  [does not gate]" : "";
+    const p = s.patches.length ? `  (+${s.patches.join(", ")})` : "  (stock)";
+    console.log(`  ${label.padEnd(20)} ${s.describe}${flag}${p}`);
+  }
+  process.exit(0);
 }
+if (cli.stopped === "help") {
+  printHelpAndExit(
+    "usage: node scripts/check_a11y_fingerprint.mjs [--baseline SCHEME] " +
+      "[--candidate SCHEME] [--root-dir DIR] [--theme T] [--viewport V] " +
+      "[--pages P,P] [--json FILE] [--unminified] [--list]"
+  );
+}
+
+let baselineLabel = cli.values.baseline;
+let candidateLabel = cli.values.candidate;
+let rootDir = cli.values.rootDir;
+let themeArg = cli.values.theme;
+let viewportArg = cli.values.viewport;
+let pagesArg = cli.values.pages !== undefined ? cli.values.pages.split(",") : null;
+let jsonOut = cli.values.json ?? null;
+let unminified = cli.values.unminified;
+let patchesArg = cli.values.patches;
 
 const baseline = getScheme(baselineLabel);
 const candidate = getScheme(candidateLabel);
diff --git a/scripts/check_axe_patch_equiv.mjs b/scripts/check_axe_patch_equiv.mjs
index e9c85887..0ef00354 100644
--- a/scripts/check_axe_patch_equiv.mjs
+++ b/scripts/check_axe_patch_equiv.mjs
@@ -35,19 +35,24 @@ import {
   readAxeSource,
 } from "./lib/axe-scan.mjs";
 import { withBrowser } from "./lib/browser.mjs";
-
-let patchName = "plain-color-fields";
-const args = process.argv.slice(2);
-for (let i = 0; i < args.length; i++) {
-  if (args[i] === "--patch" && args[i + 1]) patchName = args[++i];
-  else if (args[i] === "-h" || args[i] === "--help") {
-    console.log("usage: node scripts/check_axe_patch_equiv.mjs [--patch NAME]");
-    process.exit(0);
-  } else {
-    console.error(`unknown arg: ${args[i]}`);
-    process.exit(2);
-  }
+import { parseCli, printHelpAndExit, withUsageError } from "../lib/cli.mjs";
+
+const cli = withUsageError(
+  () =>
+    parseCli(process.argv.slice(2), {
+      options: {
+        patch: { type: "string", default: "plain-color-fields" },
+        help: { type: "boolean", short: "h" },
+      },
+      acceptsValue: Boolean,
+      stopAt: ["help"],
+    }),
+  { format: (err) => `unknown arg: ${err.arg}` },
+);
+if (cli.stopped === "help") {
+  printHelpAndExit("usage: node scripts/check_axe_patch_equiv.mjs [--patch NAME]");
 }
+let patchName = cli.values.patch;
 
 // Runs in the page against whichever bundle was injected.
 const PROBE = () => {
diff --git a/scripts/check_cli.mjs b/scripts/check_cli.mjs
index b7c3e6d7..14e91d6b 100644
--- a/scripts/check_cli.mjs
+++ b/scripts/check_cli.mjs
@@ -140,6 +140,16 @@ const OPTIONS = {
   const any = parseCli(["--port"], { options: { port: { type: "string", default: "d" } }, acceptsValue: () => true }).values;
   check("a value acceptsValue takes is stored as it is, undefined included", "port" in any && any.port === undefined, show(any));
 }
+{
+  const spec = { options: { ...OPTIONS, help: { type: "boolean", short: "h" } }, positionals: 1, stopAt: ["help"] };
+  const r = parseCli(["--port", "80", "-h", "--bogus", "--port"], spec);
+  check("stopAt ends the parse at the option, reading nothing after it and counting no positionals",
+    r.stopped === "help" && r.values.port === "80" && r.values.help === true, show(r));
+  check("stopAt does not excuse an error before the option",
+    Boolean(cliError(() => parseCli(["--bogus", "--help"], spec), "unknown-option")));
+  check("without its option, stopAt changes nothing", parseCli(["a"], spec).stopped === undefined
+    && Boolean(cliError(() => parseCli([], spec), "missing-positional")));
+}
 check("unknown takes only its three values", caught(() => parseCli([], { unknown: "warn" })) instanceof TypeError);
 
 // With the defaults, parseCli refuses what a strict parseArgs refuses, in the
@@ -257,6 +267,38 @@ const CASES = [
   { tool: "scripts/census_attributes.mjs", args: ["--src", "--json"], exit: 2, stderr: "--src needs a value\n" },
   { tool: "scripts/build_package_api.mjs", args: ["--out"], exit: 2, stderr: "--out needs a value\n" },
   { tool: "scripts/build_package_api.mjs", args: ["--src", "--check"], exit: 2, stderr: "--src needs a value\n" },
+
+  // Recorded in C48, before the a11y and diagram tools moved onto lib/cli.mjs.
+  // A value flag given nothing, at the end or as "", reads as an unknown
+  // argument; one followed by another flag takes the flag as its value, so that
+  // is no case. check_a11y has no --help and refuses it. --theme and --viewport
+  // are checked against their lists (C20). check_dot_fit and build_dot_metrics
+  // ignore every argument, so neither has a case.
+  { tool: "scripts/check_a11y.mjs", args: ["--help"], exit: 2, stderr: "unknown arg: --help\n" },
+  { tool: "scripts/check_a11y.mjs", args: ["--bogus"], exit: 2, stderr: "unknown arg: --bogus\n" },
+  { tool: "scripts/check_a11y.mjs", args: ["--root-dir"], exit: 2, stderr: "unknown arg: --root-dir\n" },
+  { tool: "scripts/check_a11y.mjs", args: ["--theme", ""], exit: 2, stderr: "unknown arg: --theme\n" },
+  { tool: "scripts/check_a11y.mjs", args: ["--theme", "drak"], exit: 2, stderr: 'unknown --theme "drak"; expected one of light, dark or both\n' },
+  { tool: "scripts/check_a11y.mjs", args: ["--viewport", "huge"], exit: 2, stderr: 'unknown --viewport "huge"; expected one of desktop, mobile or both\n' },
+  { tool: "scripts/check_a11y_fingerprint.mjs", args: ["--help"], exit: 0, stdout: /^usage: node scripts\/check_a11y_fingerprint\.mjs / },
+  { tool: "scripts/check_a11y_fingerprint.mjs", args: ["--bogus"], exit: 2, stderr: "unknown arg: --bogus\n" },
+  { tool: "scripts/check_a11y_fingerprint.mjs", args: ["--pages"], exit: 2, stderr: "unknown arg: --pages\n" },
+  { tool: "scripts/check_a11y_fingerprint.mjs", args: ["--theme", "drak"], exit: 2, stderr: 'unknown --theme "drak"; expected one of light, dark or both\n' },
+  { tool: "scripts/check_axe_patch_equiv.mjs", args: ["--help"], exit: 0, stdout: /^usage: node scripts\/check_axe_patch_equiv\.mjs / },
+  { tool: "scripts/check_axe_patch_equiv.mjs", args: ["--bogus"], exit: 2, stderr: "unknown arg: --bogus\n" },
+  { tool: "scripts/check_axe_patch_equiv.mjs", args: ["--patch"], exit: 2, stderr: "unknown arg: --patch\n" },
+  { tool: "scripts/check_tree_fresh.mjs", args: ["--help"], exit: 0, stdout: /^usage: node scripts\/check_tree_fresh\.mjs / },
+  { tool: "scripts/check_tree_fresh.mjs", args: ["--bogus"], exit: 2, stderr: "unknown arg: --bogus\n" },
+  { tool: "scripts/check_tree_fresh.mjs", args: ["--source"], exit: 2, stderr: "unknown arg: --source\n" },
+  { tool: "scripts/check_tree_fresh.mjs", args: ["--tree"], exit: 2, stderr: "unknown arg: --tree\n" },
+  { tool: "scripts/pick_a11y_sample.mjs", args: ["--help"], exit: 0, stderr: /^usage: node scripts\/pick_a11y_sample\.mjs / },
+  { tool: "scripts/pick_a11y_sample.mjs", args: ["--bogus"], exit: 2, stderr: "unknown arg: --bogus\n" },
+  { tool: "scripts/pick_a11y_sample.mjs", args: ["--budget"], exit: 2, stderr: "unknown arg: --budget\n" },
+  { tool: "scripts/sweep_a11y.mjs", args: ["--help"], exit: 0, stderr: /^usage: node scripts\/sweep_a11y\.mjs / },
+  { tool: "scripts/sweep_a11y.mjs", args: ["--bogus"], exit: 2, stderr: "unknown arg: --bogus\n" },
+  { tool: "scripts/sweep_a11y.mjs", args: ["--limit"], exit: 2, stderr: "unknown arg: --limit\n" },
+  { tool: "scripts/sweep_a11y.mjs", args: ["--theme", "drak"], exit: 2, stderr: 'unknown --theme "drak"; expected one of light, dark or both\n' },
+  { tool: "scripts/sweep_a11y.mjs", args: ["--viewport", "huge"], exit: 2, stderr: 'unknown --viewport "huge"; expected one of desktop, mobile or both\n' },
 ];
 
 const TIMEOUT_MS = 30_000;
diff --git a/scripts/check_dot_fit.mjs b/scripts/check_dot_fit.mjs
index b1f1c269..61d4bba7 100644
--- a/scripts/check_dot_fit.mjs
+++ b/scripts/check_dot_fit.mjs
@@ -29,6 +29,7 @@ import { listDotSources } from "../builder/dot.mjs";
 import { withBrowser } from "./lib/browser.mjs";
 import { exitOnCrash } from "./lib/gate-probes.mjs";
 import { openInterPage } from "./lib/inter-page.mjs";
+import { parseCli } from "../lib/cli.mjs";
 import { DOCS_DIR, REPO_ROOT } from "../lib/repo-paths.mjs";
 
 exitOnCrash();
@@ -41,7 +42,7 @@ exitOnCrash();
 // tens of units rather than ones.
 const TOLERANCE = 1.0;
 
-const verbose = process.argv.includes("--verbose");
+const verbose = parseCli(process.argv.slice(2), { options: { verbose: { type: "boolean" } }, unknown: "ignore" }).values.verbose === true;
 
 // The committed SVG of every diagram the build renders, found as it finds them.
 const svgs = [];
diff --git a/scripts/check_tree_fresh.mjs b/scripts/check_tree_fresh.mjs
index 692f6a2b..24eae886 100644
--- a/scripts/check_tree_fresh.mjs
+++ b/scripts/check_tree_fresh.mjs
@@ -29,6 +29,7 @@
 import { readdirSync, statSync, existsSync } from "node:fs";
 import { join, resolve, relative, sep } from "node:path";
 
+import { parseCli, printHelpAndExit, withUsageError } from "../lib/cli.mjs";
 import { isOutputTree } from "../lib/markdown-files.mjs";
 import { REPO_ROOT } from "../lib/repo-paths.mjs";
 
@@ -63,24 +64,28 @@ const DEFAULT_SOURCES = ["docs", "builder", "lib"];
 const DEFAULT_TREE = "docs/_site-offline";
 const DEFAULT_MARKER = "index.html";
 
-let tree = DEFAULT_TREE;
-let markerName = DEFAULT_MARKER;
-const sources = [];
-const argv = process.argv.slice(2);
-for (let i = 0; i < argv.length; i++) {
-  if (argv[i] === "--tree" && argv[i + 1]) tree = argv[++i];
-  else if (argv[i] === "--marker" && argv[i + 1]) markerName = argv[++i];
-  else if (argv[i] === "--source" && argv[i + 1]) sources.push(argv[++i]);
-  else if (argv[i] === "-h" || argv[i] === "--help") {
-    console.log(
-      "usage: node scripts/check_tree_fresh.mjs [--tree DIR] [--marker FILE] [--source DIR ...]",
-    );
-    process.exit(0);
-  } else {
-    console.error(`unknown arg: ${argv[i]}`);
-    process.exit(2);
-  }
+const cli = withUsageError(
+  () =>
+    parseCli(process.argv.slice(2), {
+      options: {
+        tree: { type: "string", default: DEFAULT_TREE },
+        marker: { type: "string", default: DEFAULT_MARKER },
+        source: { type: "string", multiple: true },
+        help: { type: "boolean", short: "h" },
+      },
+      acceptsValue: Boolean,
+      stopAt: ["help"],
+    }),
+  { format: (err) => `unknown arg: ${err.arg}` },
+);
+if (cli.stopped === "help") {
+  printHelpAndExit(
+    "usage: node scripts/check_tree_fresh.mjs [--tree DIR] [--marker FILE] [--source DIR ...]",
+  );
 }
+let tree = cli.values.tree;
+let markerName = cli.values.marker;
+const sources = cli.values.source;
 if (!sources.length) sources.push(...DEFAULT_SOURCES);
 
 const treeDir = resolve(REPO_ROOT, tree);
diff --git a/scripts/pick_a11y_sample.mjs b/scripts/pick_a11y_sample.mjs
index aad6e38e..a05378b0 100644
--- a/scripts/pick_a11y_sample.mjs
+++ b/scripts/pick_a11y_sample.mjs
@@ -48,6 +48,7 @@ import {
   DEFAULT_ROOT_DIR, REPO_ROOT, SAMPLE_PAGES, discoverPages, median, pad, splitStubs,
 } from "./lib/axe-scan.mjs";
 import { exitOnCrash } from "./lib/gate-probes.mjs";
+import { parseCli, printHelpAndExit, withUsageError } from "../lib/cli.mjs";
 
 // A crash exits 2, where 1 is a coverage gap.
 exitOnCrash();
@@ -125,31 +126,37 @@ const ANCHORS = {
 // CLI
 // ---------------------------------------------------------------------------
 
-const args = process.argv.slice(2);
-let mode = "check";
-let rootDir = DEFAULT_ROOT_DIR;
-let sweepPath = join(REPO_ROOT, "perf/results/a11y-sweep.jsonl");
-let budget = Infinity;
-let fresh = false;
-
-for (let i = 0; i < args.length; i++) {
-  const a = args[i];
-  if (a === "--check") mode = "check";
-  else if (a === "--propose") mode = "propose";
-  else if (a === "--census") mode = "census";
-  else if (a === "--fresh") fresh = true;
-  else if (a === "--root-dir" && args[i + 1]) rootDir = args[++i];
-  else if (a === "--sweep" && args[i + 1]) sweepPath = args[++i];
-  else if (a === "--budget" && args[i + 1]) budget = parseFloat(args[++i]);
-  else if (a === "-h" || a === "--help") {
-    console.error("usage: node scripts/pick_a11y_sample.mjs [--check|--propose|--census] [--fresh]");
-    console.error("                                        [--root-dir DIR] [--sweep FILE] [--budget MS]");
-    process.exit(0);
-  } else {
-    console.error("unknown arg: " + a);
-    process.exit(2);
-  }
+const cli = withUsageError(
+  () =>
+    parseCli(process.argv.slice(2), {
+      options: {
+        check: { type: "boolean" },
+        propose: { type: "boolean" },
+        census: { type: "boolean" },
+        fresh: { type: "boolean", default: false },
+        "root-dir": { type: "string", default: DEFAULT_ROOT_DIR },
+        sweep: { type: "string", default: join(REPO_ROOT, "perf/results/a11y-sweep.jsonl") },
+        budget: { type: "string" },
+        help: { type: "boolean", short: "h" },
+      },
+      acceptsValue: Boolean,
+      stopAt: ["help"],
+    }),
+  { format: (err) => `unknown arg: ${err.arg}` },
+);
+if (cli.stopped === "help") {
+  printHelpAndExit(
+    "usage: node scripts/pick_a11y_sample.mjs [--check|--propose|--census] [--fresh]\n"
+      + "                                        [--root-dir DIR] [--sweep FILE] [--budget MS]",
+    { stream: "stderr" },
+  );
 }
+const modeTokens = cli.tokens.filter((t) => t.key === "check" || t.key === "propose" || t.key === "census");
+let mode = modeTokens.length ? modeTokens[modeTokens.length - 1].key : "check";
+let rootDir = cli.values.rootDir;
+let sweepPath = cli.values.sweep;
+let budget = cli.values.budget !== undefined ? parseFloat(cli.values.budget) : Infinity;
+let fresh = cli.values.fresh;
 rootDir = resolve(rootDir);
 
 // ---------------------------------------------------------------------------
diff --git a/scripts/sweep_a11y.mjs b/scripts/sweep_a11y.mjs
index 8e72bc58..23922d30 100644
--- a/scripts/sweep_a11y.mjs
+++ b/scripts/sweep_a11y.mjs
@@ -62,6 +62,7 @@ import {
   splitStubs,
 } from "./lib/axe-scan.mjs";
 import { withBrowser } from "./lib/browser.mjs";
+import { parseCli, printHelpAndExit, withUsageError } from "../lib/cli.mjs";
 
 // The production scheme, read from the one registry check_a11y.mjs reads --
 // same bundle, same patches, same run options.  A survey run against a
@@ -70,43 +71,48 @@ import { withBrowser } from "./lib/browser.mjs";
 const PRODUCTION = getScheme("production");
 const AXE_PATCHES = PRODUCTION.patches;
 
-const args = process.argv.slice(2);
-let rootDir = DEFAULT_ROOT_DIR;
-let themeArg = "both";
-let viewportArg = "both";
-let filter = null;
-let limit = Infinity;
-let outPath = null;
-let resume = false;
-let reportOnly = false;
-let stockAxe = false;
-let recycleEvery = 100;
-
-for (let i = 0; i < args.length; i++) {
-  const a = args[i];
-  if (a === "--root-dir" && args[i + 1]) rootDir = args[++i];
-  else if (a === "--theme" && args[i + 1]) themeArg = args[++i];
-  else if (a === "--viewport" && args[i + 1]) viewportArg = args[++i];
-  else if (a === "--filter" && args[i + 1]) filter = args[++i];
-  else if (a === "--limit" && args[i + 1]) limit = parseInt(args[++i], 10);
-  else if (a === "--out" && args[i + 1]) outPath = args[++i];
-  else if (a === "--resume") resume = true;
-  else if (a === "--report") {
-    reportOnly = true;
-    resume = true;
-  } else if (a === "--stock-axe") stockAxe = true;
-  else if (a === "--recycle-every" && args[i + 1]) recycleEvery = parseInt(args[++i], 10);
-  else if (a === "-h" || a === "--help") {
-    console.error("usage: node scripts/sweep_a11y.mjs [--theme T] [--viewport V] [--filter SUBSTR]");
-    console.error("                                   [--limit N] [--out FILE] [--resume] [--report]");
-    console.error("                                   [--stock-axe] [--root-dir DIR]");
-    process.exit(0);
-  } else {
-    console.error("unknown arg: " + a);
-    process.exit(2);
-  }
+const cli = withUsageError(
+  () =>
+    parseCli(process.argv.slice(2), {
+      options: {
+        "root-dir": { type: "string", default: DEFAULT_ROOT_DIR },
+        theme: { type: "string", default: "both" },
+        viewport: { type: "string", default: "both" },
+        filter: { type: "string" },
+        limit: { type: "string" },
+        out: { type: "string" },
+        resume: { type: "boolean", default: false },
+        report: { type: "boolean", default: false },
+        "stock-axe": { type: "boolean", default: false },
+        "recycle-every": { type: "string" },
+        help: { type: "boolean", short: "h" },
+      },
+      acceptsValue: Boolean,
+      stopAt: ["help"],
+    }),
+  { format: (err) => `unknown arg: ${err.arg}` },
+);
+if (cli.stopped === "help") {
+  printHelpAndExit(
+    "usage: node scripts/sweep_a11y.mjs [--theme T] [--viewport V] [--filter SUBSTR]\n"
+      + "                                   [--limit N] [--out FILE] [--resume] [--report]\n"
+      + "                                   [--stock-axe] [--root-dir DIR]",
+    { stream: "stderr" },
+  );
 }
 
+let rootDir = cli.values.rootDir;
+let themeArg = cli.values.theme;
+let viewportArg = cli.values.viewport;
+let filter = cli.values.filter ?? null;
+let limit = cli.values.limit !== undefined ? parseInt(cli.values.limit, 10) : Infinity;
+let outPath = cli.values.out ?? null;
+let resume = cli.values.resume;
+let reportOnly = cli.values.report;
+if (reportOnly) resume = true;
+let stockAxe = cli.values.stockAxe;
+let recycleEvery = cli.values.recycleEvery !== undefined ? parseInt(cli.values.recycleEvery, 10) : 100;
+
 rootDir = resolve(rootDir);
 outPath = resolve(outPath ?? join(REPO_ROOT, "perf/results/a11y-sweep.jsonl"));
 

From 6c34bdc2699765740300c8f019fa11fb27aeba77 Mon Sep 17 00:00:00 2001
From: Kuba Sunderland-Ober <kuba@mareimbrium.org>
Date: Sun, 27 Sep 2026 19:23:46 +0200
Subject: [PATCH 26/27] scripts: the harness tools parse through lib/cli.mjs

---
 builder/PLAN-TOOLING-REVIEW.md   | 62 +++++++++++++++++++++++++++-
 docs/Documentation/Tools.md      |  2 +-
 scripts/addin_test.mjs           | 33 ++++++++++-----
 scripts/build_package_api.mjs    | 37 +++++++++--------
 scripts/census_attributes.mjs    | 52 ++++++++++++++----------
 scripts/check_cli.mjs            | 40 ++++++++++++++++++
 scripts/check_examples.mjs       | 69 ++++++++++++++++++++------------
 scripts/gen_attribute_probes.mjs |  8 ++--
 scripts/tbbuild.mjs              | 54 ++++++++++++++-----------
 scripts/tbrun.mjs                | 62 ++++++++++++++++------------
 10 files changed, 290 insertions(+), 129 deletions(-)

diff --git a/builder/PLAN-TOOLING-REVIEW.md b/builder/PLAN-TOOLING-REVIEW.md
index d3a85529..62086a26 100644
--- a/builder/PLAN-TOOLING-REVIEW.md
+++ b/builder/PLAN-TOOLING-REVIEW.md
@@ -252,7 +252,9 @@ is implemented.
    helper commit that must change nothing (C43).
 9. **L1-10 closes as a side effect.** `node:util` `parseArgs` accepts `--name=value` for
    every option and cannot be told not to, so this is the one behaviour change Phase 2's
-   migrations make, and it only adds a form.
+   migrations make, and it only adds a form. C49 adds a second, at the owner's choice
+   (2026-09-27): in the harness tools whose `opt()` found a flag with `indexOf`, a repeated
+   flag now keeps its last value, as `parseArgs` does and as C72's strict parse would.
 10. **Three of the review's facts were wrong**, found by proofreading this plan against the
     source (A8-2, fixed in C10; A2-1, fixed in C14; L4-10, whose corrected figure, 119 probes,
     is stated in C61).
@@ -1546,6 +1548,64 @@ have a `flag()` and `opt()` pair and a `die()`, in three shapes (V3's fifth note
 **Verify.** `check_cli.mjs`'s cases; the `examples.bat` summary and `addin-test.bat`
 unchanged (harness runs, one at a time).
 
+**Landed.** All seven parse through `parseCli`. `tbbuild`, `check_examples`,
+`census_attributes` and `build_package_api` take the default `acceptsValue`, which is their
+old check for a value flag with no value, and print a `CliError` through `withUsageError`:
+`tbbuild` the message and then its usage line, `check_examples` with its `check_examples: `
+prefix, the other two the message alone, all on stderr with exit 2. Their number checks
+(`positive`, `positiveInteger`) stay in the tools, and so does the order: `tbbuild` and
+`check_examples` check their numbers before `--help`. `tbrun` and `addin_test` take
+`acceptsValue: () => true` and read each value as `values.x || default`, which keeps their
+truthy test until C72: a value flag at the end of the list, or given `""`, gets its default,
+and any other argument after it is its value. All six ignore an unknown flag (`unknown:
+"ignore"`); `tbbuild` and `tbrun` take one positional (`max: 1`), a second one ignored as
+before. `gen_attribute_probes` takes `unknown: "positional"` with no maximum, since every
+argument after its second is ignored. `check_examples` prints its help through
+`printHelpAndExit` (the same bytes: the text has no final newline); `census_attributes` still
+prints the slice of its own header comment with `console.log`; `build_package_api` still has
+no `--help`. The survey's list for `check_examples` lacked `--show` and `--hide`, which it
+passes on to `tbbuild`; they are in its table. The edit was a Sonnet agent's (65 calls,
+~275k, 18.6 min), reviewed line by line; one comment lost a dangling "too".
+
+The cases were recorded from the unedited tools first: 28 across the seven (`--help` in each
+shape, a number refused, a dash-led value, a bad `--arch`, a number error before `--help`,
+the project after an unknown flag, `tbrun`'s value flag taking the source folder, a trailing
+and an empty value given the default, `build_package_api --help` ignored,
+`gen_attribute_probes` with no argument). `census_attributes --help` prints its header with
+the checkout's line endings, so its case allows `\r`. Some cases stop at the first check of
+what the command line names (a project, a source folder, an install), which is where a
+default or a positional shows; Tools.md's `check_cli` section now says a case may. `check_cli`
+now makes 106 checks, 39
+probes and 67 cases. The kit's `c49-tools.mjs` (`c48-tools.mjs`'s shape, HEAD's copies
+beside the real tools) runs 35 real invocations that start no IDE: `tbbuild` and `tbrun`
+stopped at the project, Settings or IDE check with every option given, `addin_test` at the
+IDE check and at a lane filter matching nothing, `check_examples --census` in four forms,
+`--report` and `--help`, `census_attributes` over the warm BETA 987 cache, `build_package_api
+--check`, and `gen_attribute_probes` writing two probe trees, compared by hash. 29 are the
+same. Four differ as recorded below. `addin_test --only "("` crashes alike on both, the stack
+trace's line number moved (75 to 88). `census_attributes --help` differs only in `\r`: HEAD's
+copy is written from the LF blob and the tool prints its own file; the two slices are equal
+without it. The harness bar is unchanged from the BETA 987 baselines: `examples.bat` exit 0
+after 126.3 s, `1129 sample(s), 1129 compile, 0 finding(s), 124.0s -- clean`;
+`addin-test.bat` exit 0 after 129.8 s, `10 of 10 lane(s) ran: 10 passed`, `registry: put
+back (20 project-state, 21 recent-list and 3 association writes)`, the kit's registry
+snapshots identical before and after. `build.bat`, `check.bat` (the a11y line unchanged)
+and `test.bat` exit 0, and the tree comparison differs only in Tools.md's page, online and
+offline, the search index and `book.html`.
+
+What differs, none of it a recorded case: a repeated flag keeps its last value in `tbbuild`,
+`check_examples`, `census_attributes`, `build_package_api`, `addin_test` and `tbrun`, whose
+`opt()` also used `indexOf` (departure 9, at the owner's choice; `--census --jobs 3 --jobs
+0` now refuses the 0); `--name=value` is accepted (departure 9; `--only=Reference/Core`
+now filters); after `--` an argument is a positional, and `--` itself is not one; a
+single-dash argument is an unknown short option, so `tbbuild -x proj.twinproj` builds
+`proj.twinproj` where it said `not a .twinproj: -x`; and in `tbrun` and `addin_test` a flag
+taken as another flag's value (`--port --json`) no longer also counts as itself.
+
+Found in passing, not fixed: `census_attributes`' `--dump-sites <file>` is in neither its
+header comment nor its `--help`, which prints that comment; its help's first line is empty,
+since the slice starts at a bare `//`.
+
 ### C50 — `scripts: the gates and link tools parse through lib/cli.mjs`
 
 **Decision (e); L1-2's fourth variant.** The rest of `scripts/`.
diff --git a/docs/Documentation/Tools.md b/docs/Documentation/Tools.md
index ec7ce6db..8f09aba9 100644
--- a/docs/Documentation/Tools.md
+++ b/docs/Documentation/Tools.md
@@ -527,7 +527,7 @@ Verifies `lib/cli.mjs`, the module the tools read their command lines through, a
 
 The module's probes cover what `parseCli` returns and refuses, with a comparison against a strict `node:util` `parseArgs` over the same argument lists, and what `numberOption`, `withUsageError` and `printHelpAndExit` do. A tool that is more lenient than a strict parse today --- one that ignores an unknown flag, say --- keeps its leniency through two of `parseCli`'s parameters, and the probes cover those too.
 
-The recorded cases are invocations that stop while the tool reads its command line, each with its exit code and what it prints on each stream: the tool's own words for the error exactly, and the opening of a usage text printed after it. A tool's cases are recorded before it moves onto `lib/cli.mjs`, so the move has to keep them. Each case runs the tool as a child process, in an empty folder of its own and with `TB_IDE` and `PUPPETEER_EXECUTABLE_PATH` naming files that do not exist, so a case that gets past the command line fails on a different message rather than starting a twinBASIC IDE or a browser. A case belongs here only if the tool stops before doing any work.
+The recorded cases are invocations that stop while the tool reads its command line, or at its first check of the project, folder or install the command line names, each with its exit code and what it prints on each stream: the tool's own words for the error exactly, and the opening of a usage text printed after it. A tool's cases are recorded before it moves onto `lib/cli.mjs`, so the move has to keep them. Each case runs the tool as a child process, in an empty folder of its own and with `TB_IDE` and `PUPPETEER_EXECUTABLE_PATH` naming files that do not exist, so a case that gets past the command line fails on a different message rather than starting a twinBASIC IDE or a browser. A case belongs here only if the tool stops before doing any work.
 
 Exits 1 on any failed probe or case, 2 if it cannot run.
 
diff --git a/scripts/addin_test.mjs b/scripts/addin_test.mjs
index 05e20cf0..92282db3 100644
--- a/scripts/addin_test.mjs
+++ b/scripts/addin_test.mjs
@@ -53,6 +53,7 @@ import { existsSync, mkdirSync } from "node:fs";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
+import { parseCli } from "../lib/cli.mjs";
 import { removeTree } from "./lib/tb-ide-copy.mjs";
 import { wantShow } from "./lib/tb-ide.mjs";
 import { buildNumber, findIde } from "./lib/tb-install.mjs";
@@ -63,24 +64,36 @@ import { REPO_ROOT } from "../lib/repo-paths.mjs";
 
 const SUITE = path.join(REPO_ROOT, "test", "addin");
 
-const argv = process.argv.slice(2);
-const flag = (n) => argv.includes(`--${n}`);
-const opt = (n, d) => { const i = argv.indexOf(`--${n}`); return i >= 0 && argv[i + 1] ? argv[i + 1] : d; };
+const { values } = parseCli(process.argv.slice(2), {
+  options: {
+    only: { type: "string" },
+    port: { type: "string" },
+    jobs: { type: "string" },
+    timeout: { type: "string" },
+    ide: { type: "string" },
+    show: { type: "boolean", default: false },
+    hide: { type: "boolean", default: false },
+    help: { type: "boolean", default: false },
+  },
+  unknown: "ignore",
+  positionals: 0,
+  acceptsValue: () => true,
+});
 const die = (code, msg) => { console.error(msg); process.exit(code); };
 
-if (flag("help")) {
+if (values.help) {
   die(2, "usage: node scripts/addin_test.mjs [--only REGEX] [--port N] [--jobs N] " +
          "[--timeout S] [--ide <twinBASIC.exe>] [--show|--hide]");
 }
-const only = opt("only", null) ? new RegExp(opt("only")) : null;
-const basePort = Number(opt("port", 9560));
-const jobs = Math.max(1, Number(opt("jobs", 2)));
-const laneTimeout = Number(opt("timeout", 600)) * 1000;
-const show = wantShow({ show: flag("show"), hide: flag("hide") });
+const only = values.only ? new RegExp(values.only) : null;
+const basePort = Number(values.port || 9560);
+const jobs = Math.max(1, Number(values.jobs || 2));
+const laneTimeout = Number(values.timeout || 600) * 1000;
+const show = wantShow({ show: values.show, hide: values.hide });
 
 // ---------------------------------------------------------------- refusals
 
-const ide = findIde(opt("ide", undefined));
+const ide = findIde(values.ide || undefined);
 if (!ide || !existsSync(ide)) {
   die(2, "no twinBASIC IDE found: pass --ide <twinBASIC.exe>, set TB_IDE, " +
          "or unpack a twinBASIC_IDE_BETA_<n> folder on your Desktop");
diff --git a/scripts/build_package_api.mjs b/scripts/build_package_api.mjs
index 61b591d1..0b0fec43 100644
--- a/scripts/build_package_api.mjs
+++ b/scripts/build_package_api.mjs
@@ -46,27 +46,30 @@ import path from "node:path";
 import { buildNumber, findIde } from "./lib/tb-install.mjs";
 import { defaultCache, exportPackages, packageName } from "./lib/tb-packages.mjs";
 import { apiSnapshot, parsePackage } from "./lib/twin-api.mjs";
+import { parseCli, withUsageError } from "../lib/cli.mjs";
 import { REPO_ROOT } from "../lib/repo-paths.mjs";
 
 const OUT = path.join(REPO_ROOT, "builder", "package-api.json");
 
-const argv = process.argv.slice(2);
-const flag = (n) => argv.includes(`--${n}`);
-const opt = (n) => { const i = argv.indexOf(`--${n}`); return i < 0 ? undefined : argv[i + 1]; };
+const { values } = withUsageError(() =>
+  parseCli(process.argv.slice(2), {
+    options: {
+      ide: { type: "string" },
+      src: { type: "string" },
+      cache: { type: "string" },
+      out: { type: "string" },
+      refresh: { type: "boolean", default: false },
+      check: { type: "boolean", default: false },
+    },
+    unknown: "ignore",
+    positionals: 0,
+  }));
 const die = (code, msg) => { console.error(msg); process.exit(code); };
 
-// A flag that takes a value, given last or followed by another flag, has none,
-// and is refused rather than read as undefined: --src then fell back to an
-// export of the install, and --out to builder/package-api.json.
-const VALUE_FLAGS = ["ide", "src", "cache", "out"];
-const bare = argv.find((a, i) => a.startsWith("--") && VALUE_FLAGS.includes(a.slice(2)) &&
-  (argv[i + 1] === undefined || /^-./.test(argv[i + 1])));
-if (bare) die(2, `${bare} needs a value`);
-
 function sources() {
   // --src takes a folder of exports, or a cache holding `packages\` and more:
   // a folder with a Settings file is an export, and one without is looked into.
-  const src = opt("src");
+  const src = values.src;
   if (src) {
     if (!existsSync(src) || !statSync(src).isDirectory()) die(2, `not a directory: ${src}`);
     const packages = [];
@@ -83,17 +86,17 @@ function sources() {
     return { build: null, packages };
   }
   // --ide and TB_IDE may name the install root or the executable in it.
-  let ide = findIde(opt("ide"));
+  let ide = findIde(values.ide);
   if (ide && !/\.exe$/i.test(ide)) ide = path.join(ide, "twinBASIC.exe");
   if (!ide || !existsSync(ide)) die(2, "no twinBASIC install found; pass --ide or set TB_IDE");
   const root = path.dirname(ide);
   const build = buildNumber(ide);
-  const cache = opt("cache") ?? defaultCache(build);
+  const cache = values.cache ?? defaultCache(build);
   console.error(`install : ${root}`);
   console.error(`cache   : ${cache}`);
   let r;
   try {
-    r = exportPackages({ root, cache, refresh: flag("refresh"), log: (l) => console.error(l) });
+    r = exportPackages({ root, cache, refresh: values.refresh, log: (l) => console.error(l) });
   } catch (e) {
     die(2, e.message);
   }
@@ -178,8 +181,8 @@ for (const p of problems.slice(0, 20)) console.error(`  ? ${p.pkg} ${p.file}:${p
 if (problems.length > 20) console.error(`  ? ... and ${problems.length - 20} more`);
 for (const u of [...new Set(unresolved)].slice(0, 20)) console.error(`  ? not found: ${u}`);
 
-const out = opt("out") ?? OUT;
-if (flag("check")) {
+const out = values.out ?? OUT;
+if (values.check) {
   const committed = existsSync(out) ? readFileSync(out, "utf8").replace(/\r\n/g, "\n") : null;
   if (committed === text) { console.error(`up to date: ${path.relative(REPO_ROOT, out)}`); process.exit(0); }
   console.error(`STALE: ${path.relative(REPO_ROOT, out)} differs from what BETA ${build ?? "?"} gives; ` +
diff --git a/scripts/census_attributes.mjs b/scripts/census_attributes.mjs
index cd7f7211..71a84360 100644
--- a/scripts/census_attributes.mjs
+++ b/scripts/census_attributes.mjs
@@ -78,25 +78,33 @@ import { fileURLToPath } from "node:url";
 import { parseAttributes } from "./lib/attributes-doc.mjs";
 import { findIde } from "./lib/tb-install.mjs";
 import { defaultCache, exportPackages, packageName } from "./lib/tb-packages.mjs";
+import { parseCli, withUsageError } from "../lib/cli.mjs";
 import { DOCS_DIR } from "../lib/repo-paths.mjs";
 
 const ATTR_DOC = path.join(DOCS_DIR, "Reference", "Attributes.md");
 
-const argv = process.argv.slice(2);
-const flag = (n) => argv.includes("--" + n);
-const opt = (n, d) => { const i = argv.indexOf("--" + n); return i < 0 ? d : argv[i + 1]; };
+const { values } = withUsageError(() =>
+  parseCli(process.argv.slice(2), {
+    options: {
+      ide: { type: "string" },
+      src: { type: "string" },
+      cache: { type: "string" },
+      attr: { type: "string" },
+      out: { type: "string" },
+      "dump-sites": { type: "string" },
+      refresh: { type: "boolean", default: false },
+      samples: { type: "boolean", default: false },
+      json: { type: "boolean", default: false },
+      quiet: { type: "boolean", default: false },
+      help: { type: "boolean", default: false },
+    },
+    unknown: "ignore",
+    positionals: 0,
+  }));
 const die = (code, msg) => { console.error(msg); process.exit(code); };
-const log = (...a) => { if (!flag("quiet")) console.error(...a); };
+const log = (...a) => { if (!values.quiet) console.error(...a); };
 
-// A flag that takes a value, given last or followed by another flag, has none,
-// and is refused rather than read as undefined: --ide then fell back to TB_IDE,
-// and --out to stdout.
-const VALUE_FLAGS = ["ide", "src", "cache", "attr", "dump-sites", "out"];
-const bare = argv.find((a, i) => a.startsWith("--") && VALUE_FLAGS.includes(a.slice(2)) &&
-  (argv[i + 1] === undefined || /^-./.test(argv[i + 1])));
-if (bare) die(2, `${bare} needs a value`);
-
-if (flag("help")) {
+if (values.help) {
   console.log(readFileSync(fileURLToPath(import.meta.url), "utf8")
     .split("\n").filter((l) => l.startsWith("//")).slice(1, 18).map((l) => l.slice(3)).join("\n"));
   process.exit(0);
@@ -107,7 +115,7 @@ if (flag("help")) {
 // findIde, and then checked for the packages/ folder the census reads. An
 // install path contains a username, so it is never hardcoded.
 function findInstall() {
-  const found = findIde(opt("ide"));
+  const found = findIde(values.ide);
   if (!found) die(2, "no twinBASIC install found; pass --ide or set TB_IDE");
   // Accept either the install root or the IDE exe inside it.
   const root = /\.exe$/i.test(found) ? path.dirname(found) : found;
@@ -125,7 +133,7 @@ const buildNumberOf = (root) => (/_BETA_(\d+)$/.exec(root)?.[1]) ?? "unknown";
 function exportAll(root, cacheDir, includeSamples) {
   try {
     const { projects, failed } = exportPackages({
-      root, cache: cacheDir, refresh: flag("refresh"), samples: includeSamples, log,
+      root, cache: cacheDir, refresh: values.refresh, samples: includeSamples, log,
     });
     const lost = new Set(failed.map((f) => f.name));
     return projects.filter((p) => !lost.has(p.name));
@@ -523,7 +531,7 @@ function collectTwinFiles(dir, out = []) {
 
 function main() {
   let projects, install = null, build = "n/a";
-  const srcDir = opt("src");
+  const srcDir = values.src;
 
   if (srcDir) {
     if (!existsSync(srcDir) || !statSync(srcDir).isDirectory()) die(2, `not a directory: ${srcDir}`);
@@ -542,9 +550,9 @@ function main() {
     install = findInstall();
     build = buildNumberOf(install);
     log(`install : ${install}`);
-    const cache = opt("cache", defaultCache(build));
+    const cache = values.cache ?? defaultCache(build);
     log(`cache   : ${cache}`);
-    projects = exportAll(install, cache, flag("samples"));
+    projects = exportAll(install, cache, values.samples);
   }
 
   const allSites = [], allProblems = [];
@@ -571,14 +579,14 @@ function main() {
     documentedCount: doc ? doc.size : null,
   });
 
-  const attr = opt("attr");
-  const text = flag("json")
+  const attr = values.attr;
+  const text = values.json
     ? JSON.stringify(attr ? rep.rows.find((r) => r.attr.toLowerCase() === attr.toLowerCase()) ?? null : rep, null, 2) + "\n"
     : attr ? renderAttrDetail(rep, attr) : renderMarkdown(rep);
 
   // Every raw site, for answering "which file produced this row?" -- the
   // question every surprising number in the report turns into.
-  const dump = opt("dump-sites");
+  const dump = values.dumpSites;
   if (dump) {
     writeFileSync(dump, JSON.stringify(attr
       ? allSites.filter((s) => s.attr.toLowerCase() === attr.toLowerCase())
@@ -586,7 +594,7 @@ function main() {
     log(`sites   : ${dump}`);
   }
 
-  const out = opt("out");
+  const out = values.out;
   if (out) { writeFileSync(out, text, "utf8"); log(`report  : ${out}`); }
   else process.stdout.write(text);
 }
diff --git a/scripts/check_cli.mjs b/scripts/check_cli.mjs
index 14e91d6b..85e6a2ed 100644
--- a/scripts/check_cli.mjs
+++ b/scripts/check_cli.mjs
@@ -299,6 +299,46 @@ const CASES = [
   { tool: "scripts/sweep_a11y.mjs", args: ["--limit"], exit: 2, stderr: "unknown arg: --limit\n" },
   { tool: "scripts/sweep_a11y.mjs", args: ["--theme", "drak"], exit: 2, stderr: 'unknown --theme "drak"; expected one of light, dark or both\n' },
   { tool: "scripts/sweep_a11y.mjs", args: ["--viewport", "huge"], exit: 2, stderr: 'unknown --viewport "huge"; expected one of desktop, mobile or both\n' },
+
+  // Recorded in C49, before the harness tools moved onto lib/cli.mjs. All of
+  // them ignore an unknown flag. tbbuild, tbrun and addin_test answer --help
+  // with their usage line on stderr and exit 2; tbbuild checks its numbers
+  // first. tbbuild finds its project anywhere in the list (C17). tbrun and
+  // addin_test give a value flag with nothing after it, or "", its default,
+  // and a value flag takes the argument after it whatever it is.
+  // check_examples and census_attributes print their help on stdout and exit
+  // 0, after the value checks; build_package_api has no --help, and
+  // gen_attribute_probes takes any argument as its output folder, so only its
+  // empty list is a case. census_attributes prints its own header comment,
+  // with the checkout's line endings.
+  { tool: "scripts/tbbuild.mjs", args: [], exit: 2, stderr: /^usage: node scripts\/tbbuild\.mjs / },
+  { tool: "scripts/tbbuild.mjs", args: ["x.twinproj", "--help"], exit: 2, stderr: /^usage: node scripts\/tbbuild\.mjs / },
+  { tool: "scripts/tbbuild.mjs", args: ["x.twinproj", "--arch", "win99"], exit: 2, stderr: /^usage: node scripts\/tbbuild\.mjs / },
+  { tool: "scripts/tbbuild.mjs", args: ["x.twinproj", "--port", "1.5"], exit: 2, stderr: /^--port takes a positive whole number\nusage: node scripts\/tbbuild\.mjs / },
+  { tool: "scripts/tbbuild.mjs", args: ["x.twinproj", "--timeout", "abc"], exit: 2, stderr: /^--timeout takes a positive number\nusage: node scripts\/tbbuild\.mjs / },
+  { tool: "scripts/tbbuild.mjs", args: ["x.twinproj", "--timeout", "-3"], exit: 2, stderr: /^--timeout needs a value\nusage: node scripts\/tbbuild\.mjs / },
+  { tool: "scripts/tbbuild.mjs", args: ["x.twinproj", "--port", "0", "--help"], exit: 2, stderr: /^--port takes a positive whole number\nusage: node scripts\/tbbuild\.mjs / },
+  { tool: "scripts/tbbuild.mjs", args: ["--bogus", "--keep", "x.twinproj"], exit: 2, stderr: "no such project: x.twinproj\n" },
+  { tool: "scripts/tbrun.mjs", args: [], exit: 2, stderr: /^usage: node scripts\/tbrun\.mjs / },
+  { tool: "scripts/tbrun.mjs", args: ["no-such-dir", "--help"], exit: 2, stderr: /^usage: node scripts\/tbrun\.mjs / },
+  { tool: "scripts/tbrun.mjs", args: ["no-such-dir", "--arch", "win99"], exit: 2, stderr: /^usage: node scripts\/tbrun\.mjs / },
+  { tool: "scripts/tbrun.mjs", args: ["--port", "no-such-dir"], exit: 2, stderr: /^usage: node scripts\/tbrun\.mjs / },
+  { tool: "scripts/tbrun.mjs", args: ["no-such-dir", "--arch"], exit: 2, stderr: /^not a directory: .*no-such-dir\ntbrun takes an exported source tree / },
+  { tool: "scripts/tbrun.mjs", args: ["no-such-dir", "--arch", ""], exit: 2, stderr: /^not a directory: .*no-such-dir\ntbrun takes an exported source tree / },
+  { tool: "scripts/tbrun.mjs", args: ["--bogus", "no-such-dir"], exit: 2, stderr: /^not a directory: .*no-such-dir\ntbrun takes an exported source tree / },
+  { tool: "scripts/addin_test.mjs", args: ["--help"], exit: 2, stderr: /^usage: node scripts\/addin_test\.mjs / },
+  { tool: "scripts/addin_test.mjs", args: ["--ide"], exit: 2, stderr: /^no twinBASIC IDE found: pass --ide / },
+  { tool: "scripts/addin_test.mjs", args: ["--ide", ""], exit: 2, stderr: /^no twinBASIC IDE found: pass --ide / },
+  { tool: "scripts/check_examples.mjs", args: ["--help"], exit: 0, stdout: /^usage: node scripts\/check_examples\.mjs \[options\]\n/ },
+  { tool: "scripts/check_examples.mjs", args: ["--jobs", "0"], exit: 2, stderr: "check_examples: --jobs takes a positive whole number\n" },
+  { tool: "scripts/check_examples.mjs", args: ["--batch", "1.5"], exit: 2, stderr: "check_examples: --batch takes a positive whole number\n" },
+  { tool: "scripts/check_examples.mjs", args: ["--jobs", "0", "--help"], exit: 2, stderr: "check_examples: --jobs takes a positive whole number\n" },
+  { tool: "scripts/check_examples.mjs", args: ["--help", "--jobs"], exit: 2, stderr: "check_examples: --jobs needs a value\n" },
+  { tool: "scripts/census_attributes.mjs", args: ["--help"], exit: 0, stdout: /^\n {4}node scripts\/census_attributes\.mjs \[options\]\r?\n/ },
+  { tool: "scripts/census_attributes.mjs", args: ["--help", "--attr"], exit: 2, stderr: "--attr needs a value\n" },
+  { tool: "scripts/census_attributes.mjs", args: ["--dump-sites"], exit: 2, stderr: "--dump-sites needs a value\n" },
+  { tool: "scripts/build_package_api.mjs", args: ["--help"], exit: 2, stderr: "no twinBASIC install found; pass --ide or set TB_IDE\n" },
+  { tool: "scripts/gen_attribute_probes.mjs", args: [], exit: 2, stdout: /^Generate a twinBASIC probe project for Reference\/Attributes\.md applicability\.\n/ },
 ];
 
 const TIMEOUT_MS = 30_000;
diff --git a/scripts/check_examples.mjs b/scripts/check_examples.mjs
index 9cba1fca..1f3d6d90 100644
--- a/scripts/check_examples.mjs
+++ b/scripts/check_examples.mjs
@@ -74,6 +74,7 @@ import {
 import { tmpdir } from "node:os";
 import path from "node:path";
 
+import { parseCli, printHelpAndExit, withUsageError } from "../lib/cli.mjs";
 import { mapLines } from "../lib/markdown.mjs";
 import {
   BODY_SLOTS, CONCAT_KEY, HIDDEN_MARKER, MARKER, RUN_MARKER, SLOTS, classify,
@@ -87,37 +88,54 @@ const TEMPLATES = path.join(REPO_ROOT, "test", "example-projects");
 
 // ---------------------------------------------------------------- arguments
 
-const argv = process.argv.slice(2);
-const flag = (n) => argv.includes("--" + n);
-const opt = (n, d) => { const i = argv.indexOf("--" + n); return i < 0 ? d : argv[i + 1]; };
 const usageError = (why) => { console.error(`check_examples: ${why}`); process.exit(2); };
 
-// A flag that takes a value, given last or followed by another flag, has none,
-// and is refused rather than read as undefined. So is a count or a port that is
-// not a positive whole number: Number() makes NaN of anything it cannot read.
-const VALUE_FLAGS = ["only", "report", "jobs", "port", "batch", "ide"];
-const bare = argv.find((a, i) => a.startsWith("--") && VALUE_FLAGS.includes(a.slice(2)) &&
-  (argv[i + 1] === undefined || /^-./.test(argv[i + 1])));
-if (bare) usageError(`${bare} needs a value`);
+const { values } = withUsageError(
+  () => parseCli(process.argv.slice(2), {
+    options: {
+      only: { type: "string" },
+      report: { type: "string" },
+      jobs: { type: "string" },
+      port: { type: "string" },
+      batch: { type: "string" },
+      ide: { type: "string" },
+      census: { type: "boolean", default: false },
+      propose: { type: "boolean", default: false },
+      apply: { type: "boolean", default: false },
+      verbose: { type: "boolean", default: false },
+      json: { type: "boolean", default: false },
+      keep: { type: "boolean", default: false },
+      show: { type: "boolean", default: false },
+      hide: { type: "boolean", default: false },
+      help: { type: "boolean", default: false },
+    },
+    unknown: "ignore",
+    positionals: 0,
+  }),
+  { format: (err) => `check_examples: ${err.message}` },
+);
+
+// A count or a port that is not a positive whole number is refused: Number()
+// makes NaN of anything it cannot read.
 function positiveInteger(n, d) {
-  const v = Number(opt(n, d));
+  const v = Number(values[n] ?? d);
   if (!Number.isInteger(v) || v < 1) usageError(`--${n} takes a positive whole number`);
   return v;
 }
 
-const MODE_CENSUS = flag("census");
-const MODE_PROPOSE = flag("propose");
-const MODE_REPORT = opt("report", null);
-const APPLY = flag("apply");
-const VERBOSE = flag("verbose");
-const AS_JSON = flag("json");
-const only = opt("only", null) ? new RegExp(opt("only", null)) : null;
+const MODE_CENSUS = values.census;
+const MODE_PROPOSE = values.propose;
+const MODE_REPORT = values.report ?? null;
+const APPLY = values.apply;
+const VERBOSE = values.verbose;
+const AS_JSON = values.json;
+const only = values.only ? new RegExp(values.only) : null;
 const jobs = positiveInteger("jobs", 4);
 const basePort = positiveInteger("port", 9480);
 const batchSize = positiveInteger("batch", 120);
 
-if (flag("help")) {
-  console.log(`usage: node scripts/check_examples.mjs [options]
+if (values.help) {
+  printHelpAndExit(`usage: node scripts/check_examples.mjs [options]
 
   --only <regex>   restrict to pages whose path matches
   --census         classify every tb fence and print the table; no compiler
@@ -132,7 +150,6 @@ if (flag("help")) {
   --keep           leave the generated projects on disk and say where
   --verbose        also print warnings, not only errors
   --json           one JSON object instead of a report`);
-  process.exit(0);
 }
 
 // A page's template, when its fence does not name one. Inferred from the path
@@ -582,7 +599,7 @@ function stageBatch(batch, work) {
 
 // ------------------------------------------------------------------- building
 
-const IDE = findIde(opt("ide", undefined));
+const IDE = findIde(values.ide);
 const COMPILER = IDE ? compilerExe(IDE) : null;
 
 // The registry tidy for the whole run (lib/tb-registry.mjs): taken in main()
@@ -616,8 +633,8 @@ async function buildStaged(staged, port) {
   const args = [path.join(REPO_ROOT, "scripts", "tbbuild.mjs"), staged.proj,
     "--port", String(port), "--json"];
   if (IDE) args.push("--ide", IDE);
-  if (flag("show")) args.push("--show");
-  if (flag("hide")) args.push("--hide");
+  if (values.show) args.push("--show");
+  if (values.hide) args.push("--hide");
 
   const child = spawn(process.execPath, args, { stdio: ["ignore", "pipe", "pipe"] });
   let out = "", err = "";
@@ -790,7 +807,7 @@ function laneOf(port, work) {
     async build(batch) {
       const staged = stageBatch(batch, work);
       const result = await buildStaged(staged, port);
-      if (!flag("keep")) rmSync(staged.dir, { recursive: true, force: true });
+      if (!values.keep) rmSync(staged.dir, { recursive: true, force: true });
       return result;
     },
     finding: addFinding,
@@ -1807,7 +1824,7 @@ async function main() {
     say(`\ncheck_examples: ${samples.length} sample(s), ${passed.length} compile, ` +
       `${real} finding(s), ${secs}s` + (real ? "" : " -- clean"));
   }
-  if (flag("keep")) say(`generated projects kept in ${work}`);
+  if (values.keep) say(`generated projects kept in ${work}`);
   else rmSync(work, { recursive: true, force: true });
 
   process.exit(real ? 1 : 0);
diff --git a/scripts/gen_attribute_probes.mjs b/scripts/gen_attribute_probes.mjs
index 7801976c..8cfc6a92 100644
--- a/scripts/gen_attribute_probes.mjs
+++ b/scripts/gen_attribute_probes.mjs
@@ -38,6 +38,7 @@
 import { promises as fs } from "node:fs";
 import path from "node:path";
 import { parseAttributes } from "./lib/attributes-doc.mjs";
+import { parseCli } from "../lib/cli.mjs";
 import { DOCS_DIR } from "../lib/repo-paths.mjs";
 
 const ATTR_DOC = path.join(DOCS_DIR, "Reference", "Attributes.md");
@@ -1106,14 +1107,15 @@ const MAIN_TWIN = "' Startup object for the probe project. Does nothing.\n\n" +
   "Module ProbeMain\n    Public Sub Main()\n    End Sub\nEnd Module\n";
 
 async function main(argv) {
-  if (argv.length < 1) {
+  const { positionals } = parseCli(argv, { unknown: "positional", positionals: { min: 0 } });
+  if (positionals.length < 1) {
     console.log(USAGE);
     return 2;
   }
-  const out = argv[0];
+  const out = positionals[0];
   // The key must land OUTSIDE the tree: anything inside it gets packed into the
   // .twinproj and shows up as a stray file in the project.
-  const keyPath = argv[1] ?? path.join(path.dirname(path.resolve(out)), "probe-key.md");
+  const keyPath = positionals[1] ?? path.join(path.dirname(path.resolve(out)), "probe-key.md");
   const srcDir = path.join(out, "Sources");
   const overflowSrc = path.join(out + "-2", "Sources");
   await fs.mkdir(srcDir, { recursive: true });
diff --git a/scripts/tbbuild.mjs b/scripts/tbbuild.mjs
index 136f9033..e9a4cef0 100644
--- a/scripts/tbbuild.mjs
+++ b/scripts/tbbuild.mjs
@@ -51,40 +51,47 @@
 // front of you".
 import { existsSync, statSync } from "node:fs";
 import path from "node:path";
+import { parseCli, withUsageError } from "../lib/cli.mjs";
 import { findIde } from "./lib/tb-install.mjs";
 import { TARGETS, attachIde, compileOutcome, launchIde, setBuildTarget, shutdownIde,
          summaryLine, waitForCompile, wantShow } from "./lib/tb-ide.mjs";
 import { finishTidy, startTidy } from "./lib/tb-registry.mjs";
 
-const args = process.argv.slice(2);
-const flag = (n) => args.includes("--" + n);
-const opt = (n, d) => { const i = args.indexOf("--" + n); return i < 0 ? d : args[i + 1]; };
+const USAGE = "usage: node scripts/tbbuild.mjs <project.twinproj> " +
+  "[--ide <twinBASIC.exe>] [--port N] [--arch win32|win64] [--timeout S] [--json] " +
+  "[--keep] [--show|--hide]";
 
 function usage(why) {
   if (why) console.error(why);
-  console.error("usage: node scripts/tbbuild.mjs <project.twinproj> " +
-    "[--ide <twinBASIC.exe>] [--port N] [--arch win32|win64] [--timeout S] [--json] " +
-    "[--keep] [--show|--hide]");
+  console.error(USAGE);
   process.exit(2);
 }
 
-// Every flag that TAKES A VALUE is named here, as in tbrun. The token after
-// one is its value, never the project; the token after any other flag can be
-// the project, as in `--keep proj`. One given last, or followed by another
-// flag, has no value, and is refused rather than read as undefined.
-const VALUE_FLAGS = ["ide", "port", "arch", "timeout"];
-const takesValue = (a) => a?.startsWith("--") && VALUE_FLAGS.includes(a.slice(2));
-const bare = args.find((a, i) =>
-  takesValue(a) && (args[i + 1] === undefined || /^-./.test(args[i + 1])));
-if (bare) usage(`${bare} needs a value`);
-const proj = args.find((a, i) => !a.startsWith("--") && !takesValue(args[i - 1]));
+const { values, positionals } = withUsageError(
+  () => parseCli(process.argv.slice(2), {
+    options: {
+      ide: { type: "string" },
+      port: { type: "string" },
+      arch: { type: "string" },
+      timeout: { type: "string" },
+      json: { type: "boolean", default: false },
+      keep: { type: "boolean", default: false },
+      show: { type: "boolean", default: false },
+      hide: { type: "boolean", default: false },
+      help: { type: "boolean", default: false },
+    },
+    unknown: "ignore",
+    positionals: { min: 0, max: 1 },
+  }),
+  { format: (err) => `${err.message}\n${USAGE}` },
+);
 
 // A number that is not positive, or a port that is not whole, is refused too.
 // Anything Number() cannot read is NaN, and a NaN timeout ends
 // waitForCompile's loop before its first pass, which then reports that the IDE
 // never opened the project.
 function positive(n, d, { whole = false } = {}) {
-  const v = Number(opt(n, d));
+  const v = Number(values[n] ?? d);
   if (!(v > 0) || (whole && !Number.isInteger(v))) {
     usage(`--${n} takes a positive ${whole ? "whole " : ""}number`);
   }
@@ -94,15 +101,16 @@ function positive(n, d, { whole = false } = {}) {
 // An install path is a home directory, so it is never hardcoded here: pass
 // --ide, set TB_IDE, or let tb-install find the newest BETA on the Desktop,
 // which is where the IDE's own zip tells people to unpack it.
-const IDE = findIde(opt("ide", undefined));
+const IDE = findIde(values.ide);
 const port = positive("port", 9333, { whole: true });
-const arch = opt("arch", TARGETS[0]);
+const arch = values.arch ?? TARGETS[0];
 const timeout = positive("timeout", 180) * 1000;
-const asJson = flag("json");
-const keep = flag("keep");
-const show = wantShow({ show: flag("show"), hide: flag("hide") });
+const asJson = values.json;
+const keep = values.keep;
+const show = wantShow({ show: values.show, hide: values.hide });
 
-if (!proj || flag("help") || !TARGETS.includes(arch)) usage();
+const proj = positionals[0];
+if (!proj || values.help || !TARGETS.includes(arch)) usage();
 // Refuse anything that is not a .twinproj, rather than discovering it two
 // minutes later. A source directory is the tempting mistake -- it is what
 // `tbrun` takes -- and handing one to the IDE does not fail: the IDE starts,
diff --git a/scripts/tbrun.mjs b/scripts/tbrun.mjs
index 75f2722a..09d24962 100644
--- a/scripts/tbrun.mjs
+++ b/scripts/tbrun.mjs
@@ -101,6 +101,7 @@ import { execFileSync } from "node:child_process";
 import { existsSync, readFileSync, mkdirSync, statSync, readdirSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import path from "node:path";
+import { parseCli } from "../lib/cli.mjs";
 import { compilerExe, findIde } from "./lib/tb-install.mjs";
 import { BUILD_FAILED, TARGETS, attachIde, clickCenter, compileOutcome, keepClears, keptClears,
          killTree, launchIde, readConsole, setBuildTarget, shutdownIde, summaryLine,
@@ -108,29 +109,38 @@ import { BUILD_FAILED, TARGETS, attachIde, clickCenter, compileOutcome, keepClea
 import { laneProjectId, stageProject } from "./lib/tb-project.mjs";
 import { finishTidy, startTidy } from "./lib/tb-registry.mjs";
 
-const argv = process.argv.slice(2);
-const flag = (n) => argv.includes(`--${n}`);
-const opt = (n, d) => {
-  const i = argv.indexOf(`--${n}`);
-  return i >= 0 && argv[i + 1] ? argv[i + 1] : d;
-};
+const { values, positionals } = parseCli(process.argv.slice(2), {
+  options: {
+    port: { type: "string" },
+    arch: { type: "string" },
+    timeout: { type: "string" },
+    quiet: { type: "string" },
+    ide: { type: "string" },
+    "reap-images": { type: "string" },
+    json: { type: "boolean", default: false },
+    raw: { type: "boolean", default: false },
+    keep: { type: "boolean", default: false },
+    "no-reap": { type: "boolean", default: false },
+    show: { type: "boolean", default: false },
+    hide: { type: "boolean", default: false },
+    help: { type: "boolean", default: false },
+  },
+  unknown: "ignore",
+  positionals: { min: 0, max: 1 },
+  acceptsValue: () => true,
+});
 
 const die = (code, msg) => { console.error(msg); process.exit(code); };
 
-// Every flag that TAKES A VALUE has to be named here, or its value is mistaken
-// for the source directory.
-const VALUE_FLAGS = ["port", "arch", "timeout", "quiet", "ide", "reap-images"];
-const positional = argv.filter((a, i) =>
-  !a.startsWith("--") && !(i > 0 && VALUE_FLAGS.includes(argv[i - 1]?.replace(/^--/, ""))));
-const arch = opt("arch", TARGETS[0]);
+const arch = values.arch || TARGETS[0];
 
-if (!positional.length || flag("help") || !TARGETS.includes(arch)) {
+if (!positionals.length || values.help || !TARGETS.includes(arch)) {
   die(2, "usage: node scripts/tbrun.mjs <source-dir> [--port N] [--arch win32|win64] " +
          "[--timeout S] [--quiet MS] [--json] [--raw] [--keep] [--no-reap] " +
          "[--reap-images a,b] [--show|--hide]");
 }
 
-const srcDir = path.resolve(positional[0]);
+const srcDir = path.resolve(positionals[0]);
 if (!existsSync(srcDir) || !statSync(srcDir).isDirectory()) {
   die(2, `not a directory: ${srcDir}\n` +
          `tbrun takes an exported source tree (the folder holding Sources/ and Settings), ` +
@@ -141,9 +151,9 @@ if (!existsSync(srcDir) || !statSync(srcDir).isDirectory()) {
 const settingsPath = path.join(srcDir, "Settings");
 if (!existsSync(settingsPath)) die(2, `no Settings file in ${srcDir}`);
 
-const port = Number(opt("port", 9346));
-const timeoutMs = Number(opt("timeout", 120)) * 1000;
-const quietMs = Number(opt("quiet", 2500));
+const port = Number(values.port || 9346);
+const timeoutMs = Number(values.timeout || 120) * 1000;
+const quietMs = Number(values.quiet || 2500);
 
 // Images a probe can leave behind through COM activation. Office is the set that
 // prompted this; --reap-images replaces the list for anything else. Only out-of-
@@ -158,7 +168,7 @@ const REAP_IMAGES = [
 
 // One install packs the tree and builds it. --ide, then TB_IDE, then the
 // newest BETA on the Desktop, as for every other tool here.
-const ide = findIde(opt("ide", undefined));
+const ide = findIde(values.ide || undefined);
 if (!ide || !existsSync(ide)) {
   die(2, "no twinBASIC IDE found. Pass --ide <twinBASIC.exe> or set TB_IDE.");
 }
@@ -245,7 +255,7 @@ const processesBefore = snapshotProcesses();
 // it -- its recent list and its saved project state, see lib/tb-registry.mjs --
 // are swept by that folder once the IDE has exited, along with any an earlier
 // run on this port left behind. Not under --keep: a kept IDE is still writing.
-const tidy = flag("keep") ? null : startTidy({ prefixes: [work] });
+const tidy = values.keep ? null : startTidy({ prefixes: [work] });
 
 let ideRun = null;
 // A failure before the console is read: said on stdout, as it was when this
@@ -259,8 +269,8 @@ function failBuild(code, text) {
 
 try {
   ideRun = await launchIde({
-    exe: ide, project: projPath, port, keep: flag("keep"),
-    show: wantShow({ show: flag("show"), hide: flag("hide") }),
+    exe: ide, project: projPath, port, keep: values.keep,
+    show: wantShow({ show: values.show, hide: values.hide }),
   });
 } catch (e) {
   failBuild(2, e.message);
@@ -328,7 +338,7 @@ try {
   // line that starts where the console's text does, and a line holding only a
   // timestamp is never blank, so every check reads without the column; under
   // --raw the lines printed are the same entries, read again with it.
-  shown = flag("raw") ? strip(last, await readConsole(cdp, { timestamps: true })) : captured;
+  shown = values.raw ? strip(last, await readConsole(cdp, { timestamps: true })) : captured;
   const kept = await keptClears(cdp);
   if (!kept) {
     throw new Error("the IDE page no longer holds what the DEBUG CONSOLE's clears erased, so " +
@@ -385,7 +395,7 @@ if (!captured.length) {
          (wasTemplate ? "" : "\n  buildPath was already explicit, so a Save dialog is unlikely."));
 }
 
-if (flag("json")) {
+if (values.json) {
   console.log(JSON.stringify({ exe: builtFile(), arch, lines: shown, idePid: ideRun?.pid ?? null,
                                reaped }, null, 2));
 } else {
@@ -414,10 +424,10 @@ function strip(text, raw = null) {
 // and anything it spawned with CreateProcess; what it cannot take is a COM
 // server, which is what reapOrphans is for.
 function shutdown() {
-  if (flag("keep")) return null;          // the IDE is the caller's problem now
+  if (values.keep) return null;          // the IDE is the caller's problem now
   shutdownIde(ideRun);
   finishTidy(tidy);
-  return flag("no-reap") ? null : reapOrphans();
+  return values.noReap ? null : reapOrphans();
 }
 
 // Identity is pid + start time, because a pid alone is reused and a run that
@@ -460,7 +470,7 @@ function reapOrphans() {
   const after = snapshotProcesses();
   if (!after) return null;
 
-  const images = new Set((opt("reap-images", "") || "")
+  const images = new Set((values.reapImages || "")
     .split(",").map((s) => s.trim().toLowerCase().replace(/\.exe$/, "")).filter(Boolean));
   const wanted = images.size ? images : new Set(REAP_IMAGES);
 

From 88979462c6c97a3bb227d475ec3592aa61be294d Mon Sep 17 00:00:00 2001
From: Kuba Sunderland-Ober <kuba@mareimbrium.org>
Date: Sun, 27 Sep 2026 20:21:30 +0200
Subject: [PATCH 27/27] scripts: the gates and link tools parse through
 lib/cli.mjs

---
 builder/PLAN-TOOLING-REVIEW.md         |  49 +++++++-
 scripts/check_cli.mjs                  |  51 +++++++++
 scripts/check_code_regions.mjs         |   9 +-
 scripts/check_gate_lists.mjs           |   9 +-
 scripts/check_links.mjs                | 152 ++++++++++++++-----------
 scripts/check_links_diff.mjs           |  41 ++++---
 scripts/check_lint.mjs                 |  13 ++-
 scripts/check_publish_policy.mjs       |  10 +-
 scripts/check_regex_safety.mjs         |  16 ++-
 scripts/compare_trees.mjs              |  52 +++++----
 scripts/convert_em_dash_separators.mjs |   4 +-
 scripts/crawl_check.mjs                |  32 +++---
 scripts/survey_tooling.mjs             |  47 ++++----
 13 files changed, 331 insertions(+), 154 deletions(-)

diff --git a/builder/PLAN-TOOLING-REVIEW.md b/builder/PLAN-TOOLING-REVIEW.md
index 62086a26..d02fe794 100644
--- a/builder/PLAN-TOOLING-REVIEW.md
+++ b/builder/PLAN-TOOLING-REVIEW.md
@@ -253,8 +253,9 @@ is implemented.
 9. **L1-10 closes as a side effect.** `node:util` `parseArgs` accepts `--name=value` for
    every option and cannot be told not to, so this is the one behaviour change Phase 2's
    migrations make, and it only adds a form. C49 adds a second, at the owner's choice
-   (2026-09-27): in the harness tools whose `opt()` found a flag with `indexOf`, a repeated
-   flag now keeps its last value, as `parseArgs` does and as C72's strict parse would.
+   (2026-09-27): in the harness tools whose `opt()` found a flag with `indexOf`, and in
+   `check_publish_policy` (C50), a repeated flag now keeps its last value, as `parseArgs` does
+   and as C72's strict parse would.
 10. **Three of the review's facts were wrong**, found by proofreading this plan against the
     source (A8-2, fixed in C10; A2-1, fixed in C14; L4-10, whose corrected figure, 119 probes,
     is stated in C61).
@@ -1621,6 +1622,50 @@ must be `--staged` or nothing, and `compare_trees.mjs`, which passes what follow
 **Verify.** `check_cli.mjs`'s cases; `test.bat` and `check.bat` unchanged;
 `check_links_diff.mjs --a script --b fused` agrees.
 
+**Landed.** All eleven parse through `parseCli`. The four that read their flags with
+`includes` (`check_regex_safety`, `check_code_regions`, `check_gate_lists`,
+`convert_em_dash_separators`) and `check_publish_policy` take `unknown: "ignore"`;
+`check_publish_policy` reads `--src` with `acceptsValue: () => true`, so given last it is
+still undefined. `check_links` takes `acceptsValue: (v) => v !== undefined` (its old `need()`)
+and `unknown: "ignore"`, and turns a missing value back into `--x requires a value`; its
+warning list is rebuilt from the kept tokens' indexes, because an unknown `--flag` without
+`=` takes the positional after it along, which parseArgs makes an input. `check_links_diff`
+and `crawl_check` take `acceptsValue: () => true` (a value flag takes whatever follows, and
+given last is `undefined`, `NaN` once read as a number) and turn every `CliError` into their
+own words, `unknown argument: X` and `unknown flag: X`. `compare_trees` splits its list at the
+first `--` before parsing, which is exactly where its loop stopped, and parses the rest with
+its old value guard as `acceptsValue` and `stopAt: ["help"]`. `check_lint` refuses any error,
+and more kept tokens than `--staged` accounts for. `survey_tooling` moves off `node:util`'s
+strict parse onto `parseCli`'s, at the owner's choice (2026-09-27): its three parse errors
+now read `unknown option: --bogus`, `unexpected argument: x` and `--root needs a value` where
+they were node:util's words, still followed by its usage line. The edit was a Sonnet agent's
+(82 calls, ~280k, 33.9 min), reviewed line by line; two of its comments described the old
+loop, one of them wrongly, and one repeated an old reason that is no longer true (`check.bat`
+passes no arguments to `check_links`); all three were rewritten.
+
+The cases were recorded from the unedited tools first: 39 across seven tools (`check_links`'
+unknown flag taking its positional and a value flag taking a following flag;
+`check_links_diff`'s refusals and its same-sides stop; `crawl_check`'s refusals, `--help`
+among them; `check_publish_policy --src` given last; `survey_tooling`'s refusals, pinned by
+their line and the usage after it, and its number checks; `check_lint`'s whole list;
+`compare_trees`' refusals, `--` included). The other four ignore every argument and have none.
+`check_cli` makes 145 checks, 39 probes and 106 cases. The kit's `c50-tools.mjs` runs 22 real
+read-only invocations through HEAD's copies and the migrated tools: three `check_links` runs
+over the built site with every kind of flag and a `/sep/` segment (56 MB of output each,
+identical), `check_links_diff --self-test` and `--list`, `crawl_check` against a port with
+nothing listening, both modes of the four gates, `convert_em_dash_separators --check`,
+`survey_tooling` in two forms, `check_lint` both ways and `compare_trees --max 2 -- --no-pdf`.
+All are the same but `survey_tooling --bogus`, whose words change as above.
+`check_links_diff --a script --b fused` reports `No differences across 6 case(s)`, and
+`build.bat`, `check.bat` (the a11y line unchanged) and `test.bat` exit 0.
+
+What differs, beyond `survey_tooling`'s words and none of it a recorded case: `--src` given
+twice keeps the last (departure 9); `--name=value` is accepted for a known flag; after `--` an
+argument is a positional, outside `compare_trees`, and `--` is no longer an unknown argument
+in `check_links`; a short-option group such as `-vh` is split; a lone `-` is a start URL to
+`crawl_check`; `compare_trees --max x --bogus` reports the unknown argument where it reported
+the bad number.
+
 ### C51 — `book, eval, wisdom: parse through lib/cli.mjs`
 
 **A10-1, L1-12 (R3).** `render-book.mjs:204-225` parses by hand and rejects `--help`;
diff --git a/scripts/check_cli.mjs b/scripts/check_cli.mjs
index 85e6a2ed..8707853e 100644
--- a/scripts/check_cli.mjs
+++ b/scripts/check_cli.mjs
@@ -339,6 +339,57 @@ const CASES = [
   { tool: "scripts/census_attributes.mjs", args: ["--dump-sites"], exit: 2, stderr: "--dump-sites needs a value\n" },
   { tool: "scripts/build_package_api.mjs", args: ["--help"], exit: 2, stderr: "no twinBASIC install found; pass --ide or set TB_IDE\n" },
   { tool: "scripts/gen_attribute_probes.mjs", args: [], exit: 2, stdout: /^Generate a twinBASIC probe project for Reference\/Attributes\.md applicability\.\n/ },
+
+  // Recorded in C50, before the gates and link tools moved onto lib/cli.mjs.
+  // check_links prints on stdout and exits 4; an unknown flag is warned about
+  // and takes the argument after it along, unless that starts with a dash, and
+  // a value flag takes whatever follows. check_links_diff, crawl_check and
+  // compare_trees refuse an unknown argument; crawl_check has no --help, and a
+  // value flag there takes whatever follows. check_publish_policy reads only
+  // --src and ignores the rest; check_lint takes --staged alone or nothing.
+  // survey_tooling's words for a parse error were node:util's, so only the
+  // line and the usage after it are pinned. check_regex_safety,
+  // check_code_regions, check_gate_lists and convert_em_dash_separators
+  // ignore every argument they do not know, so none has a case.
+  { tool: "scripts/check_links.mjs", args: ["--help"], exit: 0, stdout: /^Usage: node check_links\.mjs \[options\] <inputs\.\.\.>\n/ },
+  { tool: "scripts/check_links.mjs", args: ["no-such-tree"], exit: 4, stdout: "error: --offline is required. Online (network) checking is not implemented by this tool.\n" },
+  { tool: "scripts/check_links.mjs", args: ["--offline"], exit: 4, stdout: "error: at least one input file or directory is required\n" },
+  { tool: "scripts/check_links.mjs", args: ["--offline", "--bogus", "no-such-tree"], exit: 4, stdout: "warning: ignoring unrecognised arguments: --bogus no-such-tree\nerror: at least one input file or directory is required\n" },
+  { tool: "scripts/check_links.mjs", args: ["--offline", "-x", "--bogus=1"], exit: 4, stdout: "warning: ignoring unrecognised arguments: -x --bogus=1\nerror: at least one input file or directory is required\n" },
+  { tool: "scripts/check_links.mjs", args: ["--offline", "--root-dir", "--forbid"], exit: 4, stdout: "error: at least one input file or directory is required\n" },
+  { tool: "scripts/check_links_diff.mjs", args: ["--help"], exit: 0, stdout: /^Usage: node scripts\/check_links_diff\.mjs \[options\]\n/ },
+  { tool: "scripts/check_links_diff.mjs", args: [], exit: 2, stderr: /^error: --a and --b are both 'script', which compares nothing\.\n/ },
+  { tool: "scripts/check_links_diff.mjs", args: ["--bogus"], exit: 2, stderr: "error: unknown argument: --bogus\n" },
+  { tool: "scripts/check_links_diff.mjs", args: ["stray"], exit: 2, stderr: "error: unknown argument: stray\n" },
+  { tool: "scripts/check_links_diff.mjs", args: ["--list=1"], exit: 2, stderr: "error: unknown argument: --list=1\n" },
+  { tool: "scripts/crawl_check.mjs", args: [], exit: 2, stderr: /^usage: node scripts\/crawl_check\.mjs <start-url> / },
+  { tool: "scripts/crawl_check.mjs", args: ["--help"], exit: 2, stderr: "unknown flag: --help\n" },
+  { tool: "scripts/crawl_check.mjs", args: ["--bogus", "http://127.0.0.1:9/"], exit: 2, stderr: "unknown flag: --bogus\n" },
+  { tool: "scripts/crawl_check.mjs", args: ["--timeout", "5", "-x"], exit: 2, stderr: "unknown flag: -x\n" },
+  { tool: "scripts/crawl_check.mjs", args: ["--skip-external=1"], exit: 2, stderr: "unknown flag: --skip-external=1\n" },
+  { tool: "scripts/crawl_check.mjs", args: ["--concurrency", "--bogus"], exit: 2, stderr: /^usage: node scripts\/crawl_check\.mjs <start-url> / },
+  { tool: "scripts/check_publish_policy.mjs", args: ["--src"], exit: 2, stderr: /^TypeError \[ERR_INVALID_ARG_TYPE\]: The "path" argument must be of type string\. Received undefined\n/ },
+  { tool: "scripts/survey_tooling.mjs", args: ["--help"], exit: 0, stdout: /^usage: node scripts\/survey_tooling\.mjs \[--root DIR\] / },
+  { tool: "scripts/survey_tooling.mjs", args: ["--bogus"], exit: 2, stderr: /^[^\n]+\nusage: node scripts\/survey_tooling\.mjs \[--root DIR\] / },
+  { tool: "scripts/survey_tooling.mjs", args: ["stray"], exit: 2, stderr: /^[^\n]+\nusage: node scripts\/survey_tooling\.mjs \[--root DIR\] / },
+  { tool: "scripts/survey_tooling.mjs", args: ["--root"], exit: 2, stderr: /^[^\n]+\nusage: node scripts\/survey_tooling\.mjs \[--root DIR\] / },
+  { tool: "scripts/survey_tooling.mjs", args: ["--window", "0"], exit: 2, stderr: /^--window expects a positive integer, got: 0\nusage: node scripts\/survey_tooling\.mjs / },
+  { tool: "scripts/survey_tooling.mjs", args: ["--top", "1.5"], exit: 2, stderr: /^--top expects a positive integer, got: 1\.5\nusage: node scripts\/survey_tooling\.mjs / },
+  { tool: "scripts/survey_tooling.mjs", args: ["--window", "0", "--help"], exit: 0, stdout: /^usage: node scripts\/survey_tooling\.mjs \[--root DIR\] / },
+  { tool: "scripts/check_lint.mjs", args: ["--help"], exit: 2, stderr: "check_lint: usage: node scripts/check_lint.mjs [--staged]\n" },
+  { tool: "scripts/check_lint.mjs", args: ["--staged", "--staged"], exit: 2, stderr: "check_lint: usage: node scripts/check_lint.mjs [--staged]\n" },
+  { tool: "scripts/check_lint.mjs", args: ["--staged", "x"], exit: 2, stderr: "check_lint: usage: node scripts/check_lint.mjs [--staged]\n" },
+  { tool: "scripts/check_lint.mjs", args: ["--"], exit: 2, stderr: "check_lint: usage: node scripts/check_lint.mjs [--staged]\n" },
+  { tool: "scripts/check_lint.mjs", args: ["--staged=1"], exit: 2, stderr: "check_lint: usage: node scripts/check_lint.mjs [--staged]\n" },
+  { tool: "scripts/compare_trees.mjs", args: ["--help"], exit: 0, stdout: /^usage: node scripts\/compare_trees\.mjs \[--before <ref>\] / },
+  { tool: "scripts/compare_trees.mjs", args: ["--bogus"], exit: 2, stderr: /^compare_trees: unknown argument "--bogus"\n\nusage: node scripts\/compare_trees\.mjs / },
+  { tool: "scripts/compare_trees.mjs", args: ["stray"], exit: 2, stderr: /^compare_trees: unknown argument "stray"\n\nusage: node scripts\/compare_trees\.mjs / },
+  { tool: "scripts/compare_trees.mjs", args: ["--before"], exit: 2, stderr: /^compare_trees: --before needs a value\n\nusage: node scripts\/compare_trees\.mjs / },
+  { tool: "scripts/compare_trees.mjs", args: ["--max", "--keep"], exit: 2, stderr: /^compare_trees: --max needs a value\n\nusage: node scripts\/compare_trees\.mjs / },
+  { tool: "scripts/compare_trees.mjs", args: ["--max", "1.5"], exit: 2, stderr: /^compare_trees: --max takes a whole number, not "1\.5"\n\nusage: node scripts\/compare_trees\.mjs / },
+  { tool: "scripts/compare_trees.mjs", args: ["--bogus", "--help"], exit: 2, stderr: /^compare_trees: unknown argument "--bogus"\n\nusage: node scripts\/compare_trees\.mjs / },
+  { tool: "scripts/compare_trees.mjs", args: ["--before", "--", "x"], exit: 2, stderr: /^compare_trees: --before needs a value\n\nusage: node scripts\/compare_trees\.mjs / },
+  { tool: "scripts/compare_trees.mjs", args: ["--keep=1"], exit: 2, stderr: /^compare_trees: unknown argument "--keep=1"\n\nusage: node scripts\/compare_trees\.mjs / },
 ];
 
 const TIMEOUT_MS = 30_000;
diff --git a/scripts/check_code_regions.mjs b/scripts/check_code_regions.mjs
index dd6f4cc4..255f568c 100644
--- a/scripts/check_code_regions.mjs
+++ b/scripts/check_code_regions.mjs
@@ -79,6 +79,7 @@ import deflist from "markdown-it-deflist";
 import { validateCountNames } from "../builder/counts.mjs";
 import { discover } from "../builder/discover.mjs";
 import { applyPreRenderRewrites, createMarkdownIt } from "../builder/render.mjs";
+import { parseCli } from "../lib/cli.mjs";
 import { parseFrontmatter, unquotedHashValues } from "../lib/frontmatter.mjs";
 import { blockRegions, mapLines, maskCode, splitCodeSpans, splitOnMarker } from "../lib/markdown.mjs";
 import { markdownFiles } from "../lib/markdown-files.mjs";
@@ -419,9 +420,13 @@ const DISCOVER_PROBES = [
 ];
 
 async function main(argv) {
-  const verbose = argv.includes("--verbose");
+  const { values } = parseCli(argv, {
+    options: { verbose: { type: "boolean" }, "self-test": { type: "boolean" } },
+    unknown: "ignore",
+  });
+  const verbose = values.verbose;
 
-  if (argv.includes("--self-test")) {
+  if (values.selfTest) {
     // Prove the comparator detects corruption by corrupting a region itself.
     const src = "```tb\nIf x Then\n    y\nEnd If\n```\n";
     const before = codeRegions(src);
diff --git a/scripts/check_gate_lists.mjs b/scripts/check_gate_lists.mjs
index c5c95437..cce1a9d7 100644
--- a/scripts/check_gate_lists.mjs
+++ b/scripts/check_gate_lists.mjs
@@ -81,6 +81,7 @@
 import { readFile, readdir } from "node:fs/promises";
 import path from "node:path";
 import { createMarkdownIt } from "../builder/render.mjs";
+import { parseCli } from "../lib/cli.mjs";
 import { splitOnMarker } from "../lib/markdown.mjs";
 import { REPO_ROOT } from "../lib/repo-paths.mjs";
 import { gatesFromBat } from "./lib/gate-roster.mjs";
@@ -530,8 +531,12 @@ function selfTest() {
 // ------------------------------------------------------------------ main
 
 async function main(argv) {
-  const verbose = argv.includes("--verbose");
-  const onlySelfTest = argv.includes("--self-test");
+  const { values } = parseCli(argv, {
+    options: { verbose: { type: "boolean" }, "self-test": { type: "boolean" } },
+    unknown: "ignore",
+  });
+  const verbose = values.verbose;
+  const onlySelfTest = values.selfTest;
 
   const probes = selfTest();
   const probesFailed = probes.filter(([ok]) => !ok);
diff --git a/scripts/check_links.mjs b/scripts/check_links.mjs
index 9bac3aba..f7445278 100644
--- a/scripts/check_links.mjs
+++ b/scripts/check_links.mjs
@@ -77,6 +77,7 @@ import {
   FsOracle, formatLinkReport, formatIntegrityReport,
   resolve, OUTSIDE_BASEPATH_MARKER,
 } from "../builder/link-check.mjs";
+import { parseCli } from "../lib/cli.mjs";
 
 // Tree-relative POSIX path, the space check.mjs works and reports in, so
 // the same tree checked with a relative --root-dir, an absolute one, or
@@ -196,76 +197,97 @@ for *.html.
 `);
 }
 
+// `forbid` is the only repeatable flag. `threads` is accepted and unused, and
+// `help` is answered before any argument list is parsed.
+const LINK_OPTIONS = {
+  offline: { type: "boolean", default: false },
+  "include-fragments": { type: "boolean", default: false },
+  "fallback-extensions": { type: "string", default: "" },
+  "index-files": { type: "string", default: "" },
+  "root-dir": { type: "string", default: null },
+  "base-path": { type: "string", default: "" },
+  forbid: { type: "string", multiple: true },
+  "no-fail": { type: "boolean", default: false },
+  threads: { type: "string" },
+  verbose: { type: "boolean", short: "v", default: false },
+  help: { type: "boolean", short: "h", default: false },
+  "check-html": { type: "boolean", default: false },
+  "check-a11y": { type: "boolean", default: false },
+  "check-ids": { type: "boolean", default: false },
+  "check-remote-assets": { type: "boolean", default: false },
+  "check-sitemap": { type: "boolean", default: false },
+  "check-search": { type: "boolean", default: false },
+  "check-canonical": { type: "boolean", default: false },
+  // GitHub Pages serves from a case-sensitive filesystem; NTFS is
+  // not. FsOracle asks the platform, so on Windows a wrong-case link
+  // passes here and 404s in production -- and because
+  // check_links_diff.mjs calls this script "the oracle of record",
+  // the harness would report the side that is RIGHT as the one with
+  // the extra finding. IndexOracle compares strings, so it behaves
+  // the same everywhere. --oracle fs stays available for the case
+  // where the question really is "what does this machine's
+  // filesystem say".
+  oracle: { type: "string", default: process.platform === "win32" ? "index" : "fs" },
+};
+
 function parseArgs(argv) {
+  let cli;
+  try {
+    cli = parseCli(argv, {
+      options: LINK_OPTIONS,
+      unknown: "ignore",
+      positionals: { min: 0 },
+      acceptsValue: (v) => v !== undefined,
+    });
+  } catch (err) {
+    if (err.code === "missing-value") throw new Error(`${err.option} requires a value`);
+    throw err;
+  }
+
+  const { values } = cli;
   const opts = {
-    offline: false,
-    includeFragments: false,
-    fallbackExtensions: "",
-    indexFiles: "",
-    rootDir: null,
-    basePath: "",
-    forbid: [],
-    noFail: false,
-    verbose: false,
-    checkHtml: false,
-    checkA11y: false,
-    checkIds: false,
-    checkRemoteAssets: false,
-    checkSitemap: false,
-    checkSearch: false,
-    checkCanonical: false,
-    // GitHub Pages serves from a case-sensitive filesystem; NTFS is
-    // not. FsOracle asks the platform, so on Windows a wrong-case link
-    // passes here and 404s in production -- and because
-    // check_links_diff.mjs calls this script "the oracle of record",
-    // the harness would report the side that is RIGHT as the one with
-    // the extra finding. IndexOracle compares strings, so it behaves
-    // the same everywhere. --oracle fs stays available for the case
-    // where the question really is "what does this machine's
-    // filesystem say".
-    oracle: process.platform === "win32" ? "index" : "fs",
+    offline: values.offline,
+    includeFragments: values.includeFragments,
+    fallbackExtensions: values.fallbackExtensions,
+    indexFiles: values.indexFiles,
+    rootDir: values.rootDir,
+    basePath: values.basePath,
+    forbid: values.forbid,
+    noFail: values.noFail,
+    verbose: values.verbose,
+    checkHtml: values.checkHtml,
+    checkA11y: values.checkA11y,
+    checkIds: values.checkIds,
+    checkRemoteAssets: values.checkRemoteAssets,
+    checkSitemap: values.checkSitemap,
+    checkSearch: values.checkSearch,
+    checkCanonical: values.checkCanonical,
+    oracle: values.oracle,
   };
+
+  // An index is covered once it is a kept token's own index, or the index
+  // right after a kept value option that took its value as a separate
+  // argument -- the two positions the parse actually looked at.
+  const covered = new Set();
+  const positionalAt = new Map();
+  for (const t of cli.tokens) {
+    covered.add(t.index);
+    if (t.kind === "option" && t.value !== undefined && !t.inlineValue) covered.add(t.index + 1);
+    if (t.kind === "positional") positionalAt.set(t.index, t.value);
+  }
+
+  // Everything else went unrecognised, and is warned about rather than
+  // refused. An unknown --flag with no "=" takes the positional right after
+  // it along, so that one goes to `unknown` too, not `inputs`.
   const inputs = [];
   const unknown = [];
-  const need = (flag, i) => {
-    if (i >= argv.length) throw new Error(`${flag} requires a value`);
-    return argv[i];
-  };
-
-  let i = 0;
-  while (i < argv.length) {
-    const a = argv[i++];
-    if (a === "--offline") opts.offline = true;
-    else if (a === "--include-fragments") opts.includeFragments = true;
-    else if (a === "--fallback-extensions") opts.fallbackExtensions = need(a, i++);
-    else if (a === "--index-files") opts.indexFiles = need(a, i++);
-    else if (a === "--root-dir") opts.rootDir = need(a, i++);
-    else if (a === "--base-path") opts.basePath = need(a, i++);
-    else if (a === "--forbid") opts.forbid.push(need(a, i++));
-    else if (a === "--no-fail") opts.noFail = true;
-    else if (a === "--threads") { need(a, i++); /* accepted, ignored */ }
-    else if (a === "-v" || a === "--verbose") opts.verbose = true;
-    else if (a === "-h" || a === "--help") { /* handled before dispatch */ }
-    else if (a === "--check-html") opts.checkHtml = true;
-    else if (a === "--check-a11y") opts.checkA11y = true;
-    else if (a === "--check-ids") opts.checkIds = true;
-    else if (a === "--check-remote-assets") opts.checkRemoteAssets = true;
-    else if (a === "--check-sitemap") opts.checkSitemap = true;
-    else if (a === "--check-search") opts.checkSearch = true;
-    else if (a === "--check-canonical") opts.checkCanonical = true;
-    else if (a === "--oracle") opts.oracle = need(a, i++);
-    else if (a.startsWith("--")) {
-      // Tolerate unknown flags passed through via check.bat's %*.
-      // Consume an attached value if present.
-      if (!a.includes("=") && i < argv.length && !argv[i].startsWith("-")) {
-        unknown.push(a, argv[i++]);
-      } else {
-        unknown.push(a);
-      }
-    } else if (a.startsWith("-") && a.length > 1) {
-      unknown.push(a);
-    } else {
-      inputs.push(a);
+  for (let i = 0; i < argv.length; i++) {
+    if (positionalAt.has(i)) {
+      const prev = argv[i - 1];
+      if (i > 0 && !covered.has(i - 1) && prev.startsWith("--") && !prev.includes("=")) unknown.push(argv[i]);
+      else inputs.push(positionalAt.get(i));
+    } else if (!covered.has(i)) {
+      unknown.push(argv[i]);
     }
   }
   return { opts, inputs, unknown };
diff --git a/scripts/check_links_diff.mjs b/scripts/check_links_diff.mjs
index 1592dc4e..a9bb96e8 100644
--- a/scripts/check_links_diff.mjs
+++ b/scripts/check_links_diff.mjs
@@ -79,6 +79,7 @@ import * as path from "node:path";
 import { performance } from "node:perf_hooks";
 
 import { runCheck, selfTest as scriptSelfTest } from "./check_links.mjs";
+import { parseCli } from "../lib/cli.mjs";
 import { REPO_ROOT } from "../lib/repo-paths.mjs";
 
 const BASE_PATH = "/twinBASIC-docs";
@@ -538,24 +539,32 @@ function ensureBasePathTree(dir, allowBuild) {
 // ── Main ────────────────────────────────────────────────────────────
 
 function parseArgs(argv) {
+  let values;
+  try {
+    ({ values } = parseCli(argv, {
+      options: {
+        a: { type: "string", default: "script" },
+        b: { type: "string", default: "script" },
+        case: { type: "string", multiple: true },
+        "max-lines": { type: "string", default: "12" },
+        "base-path-tree": { type: "string", default: DEFAULT_BASEPATH_TREE },
+        "build-base-path": { type: "boolean" },
+        "self-test": { type: "boolean" },
+        list: { type: "boolean" },
+        verbose: { type: "boolean", short: "v" },
+        help: { type: "boolean", short: "h" },
+      },
+      positionals: 0,
+      acceptsValue: () => true,
+    }));
+  } catch (err) {
+    throw new Error(`unknown argument: ${err.arg}`);
+  }
   const o = {
-    a: "script", b: "script", cases: [], verbose: false, list: false,
-    maxLines: 12, basePathTree: DEFAULT_BASEPATH_TREE, buildBasePath: false,
+    a: values.a, b: values.b, cases: values.case, verbose: values.verbose, list: values.list,
+    maxLines: Number(values.maxLines), basePathTree: values.basePathTree, buildBasePath: values.buildBasePath,
+    selfTest: values.selfTest, help: values.help,
   };
-  for (let i = 0; i < argv.length; i++) {
-    const x = argv[i];
-    if (x === "--a") o.a = argv[++i];
-    else if (x === "--b") o.b = argv[++i];
-    else if (x === "--case") o.cases.push(argv[++i]);
-    else if (x === "--max-lines") o.maxLines = Number(argv[++i]);
-    else if (x === "--base-path-tree") o.basePathTree = argv[++i];
-    else if (x === "--build-base-path") o.buildBasePath = true;
-    else if (x === "-v" || x === "--verbose") o.verbose = true;
-    else if (x === "--self-test") o.selfTest = true;
-    else if (x === "--list") o.list = true;
-    else if (x === "-h" || x === "--help") { o.help = true; }
-    else throw new Error(`unknown argument: ${x}`);
-  }
   if (!o.cases.length) o.cases = [...DEFAULT_CASES];
   return o;
 }
diff --git a/scripts/check_lint.mjs b/scripts/check_lint.mjs
index 110bb927..f8d9929a 100644
--- a/scripts/check_lint.mjs
+++ b/scripts/check_lint.mjs
@@ -36,6 +36,7 @@ import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
 import { createRequire } from "node:module";
 import os from "node:os";
 import path from "node:path";
+import { parseCli } from "../lib/cli.mjs";
 import { exitOnCrash } from "./lib/gate-probes.mjs";
 import { REPO_ROOT } from "../lib/repo-paths.mjs";
 
@@ -46,9 +47,15 @@ function cannotLint(message) {
   process.exit(2);
 }
 
-const argv = process.argv.slice(2);
-const staged = argv.length === 1 && argv[0] === "--staged";
-if (argv.length && !staged) cannotLint("usage: node scripts/check_lint.mjs [--staged]");
+const USAGE = "usage: node scripts/check_lint.mjs [--staged]";
+let cli;
+try {
+  cli = parseCli(process.argv.slice(2), { options: { staged: { type: "boolean", default: false } }, positionals: 0 });
+} catch {
+  cannotLint(USAGE);
+}
+if (cli.tokens.length > (cli.values.staged ? 1 : 0)) cannotLint(USAGE);
+const staged = cli.values.staged;
 
 // The scripts the next commit adds or changes that are still on disk, by the
 // two extensions the scope in biome.jsonc is made of.
diff --git a/scripts/check_publish_policy.mjs b/scripts/check_publish_policy.mjs
index 348bb7c7..1e9740e2 100644
--- a/scripts/check_publish_policy.mjs
+++ b/scripts/check_publish_policy.mjs
@@ -22,13 +22,17 @@ import {
   publishPolicyFor, unpublishableSourceFiles, unpublishableTreePaths,
   SOURCE_EXTENSIONS, BUILD_EXTENSIONS,
 } from "../builder/publish-policy.mjs";
+import { parseCli } from "../lib/cli.mjs";
 import { exitOnCrash } from "./lib/gate-probes.mjs";
 
 exitOnCrash();
 
-const SRC = process.argv.includes("--src")
-  ? process.argv[process.argv.indexOf("--src") + 1]
-  : "docs";
+const { values } = parseCli(process.argv.slice(2), {
+  options: { src: { type: "string", default: "docs" } },
+  unknown: "ignore",
+  acceptsValue: () => true,
+});
+const SRC = values.src;
 
 // Each probe names why refusing it matters. A probe that starts passing
 // is the allowlist having been widened -- deliberately or not -- and the
diff --git a/scripts/check_regex_safety.mjs b/scripts/check_regex_safety.mjs
index eee148a2..0054a2c7 100644
--- a/scripts/check_regex_safety.mjs
+++ b/scripts/check_regex_safety.mjs
@@ -78,6 +78,7 @@ import * as walk from "acorn-walk";
 import fg from "fast-glob";
 
 import { foldConstructedRegexes } from "./lib/regex-fold.mjs";
+import { parseCli } from "../lib/cli.mjs";
 import { REPO_ROOT } from "../lib/repo-paths.mjs";
 
 // ── Backend selection ────────────────────────────────────────────────────────
@@ -545,8 +546,15 @@ async function selfTest() {
   return 0;
 }
 
-const argv = process.argv.slice(2);
-if (argv.includes("--shard")) {
+const { values } = parseCli(process.argv.slice(2), {
+  options: {
+    shard: { type: "boolean" },
+    "self-test": { type: "boolean" },
+    census: { type: "boolean" },
+  },
+  unknown: "ignore",
+});
+if (values.shard) {
   // Worker half of checkAll(): a slice in on stdin, its verdicts out on
   // stdout. Not meant to be run by hand.
   const chunks = [];
@@ -555,9 +563,9 @@ if (argv.includes("--shard")) {
   process.stdout.write(JSON.stringify(await checkList(list)));
 } else {
   try {
-    process.exitCode = argv.includes("--self-test")
+    process.exitCode = values.selfTest
       ? await selfTest()
-      : await gate({ census: argv.includes("--census") });
+      : await gate({ census: values.census });
   } catch (err) {
     // Node's own exit code for an unhandled throw is 1, which here means
     // "an exponential regex was found". A crash is the gate failing.
diff --git a/scripts/compare_trees.mjs b/scripts/compare_trees.mjs
index aee96db7..77e6d0b7 100644
--- a/scripts/compare_trees.mjs
+++ b/scripts/compare_trees.mjs
@@ -42,6 +42,7 @@ import { spawnSync } from "node:child_process";
 import { closeSync, existsSync, openSync } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
+import { parseCli } from "../lib/cli.mjs";
 import { REPO_ROOT } from "../lib/repo-paths.mjs";
 
 const WORK = path.join(REPO_ROOT, ".compare-trees");
@@ -107,26 +108,39 @@ function usageError(message) {
 }
 
 function parseArgs(argv) {
-  const opts = { before: "HEAD", keep: false, max: 20, tbdocs: [] };
-  for (let i = 0; i < argv.length; i++) {
-    const a = argv[i];
-    if (a === "--") { opts.tbdocs = argv.slice(i + 1); break; }
-    if (a === "--help" || a === "-h") { process.stdout.write(USAGE); process.exit(0); }
-    if (a === "--keep") { opts.keep = true; continue; }
-    if (a === "--before" || a === "--max") {
-      const v = argv[i + 1];
-      if (v === undefined || v.startsWith("--")) usageError(`${a} needs a value`);
-      i++;
-      if (a === "--before") opts.before = v;
-      else {
-        opts.max = Number(v);
-        if (!Number.isInteger(opts.max) || opts.max < 0) usageError(`--max takes a whole number, not "${v}"`);
-      }
-      continue;
-    }
-    usageError(`unknown argument "${a}"`);
+  // Split before parsing: everything after the first -- is opaque, passed to
+  // both tbdocs builds unread, and must not be checked against this tool's
+  // own options.
+  const sep = argv.indexOf("--");
+  const head = sep === -1 ? argv : argv.slice(0, sep);
+  const tbdocs = sep === -1 ? [] : argv.slice(sep + 1);
+
+  let cli;
+  try {
+    cli = parseCli(head, {
+      options: {
+        before: { type: "string", default: "HEAD" },
+        max: { type: "string" },
+        keep: { type: "boolean", default: false },
+        help: { type: "boolean", short: "h" },
+      },
+      positionals: 0,
+      // A single-dash value such as -1 is taken; a double-dash one is not,
+      // so a flag with no value never eats the option that follows it.
+      acceptsValue: (v) => v !== undefined && !v.startsWith("--"),
+      stopAt: ["help"],
+    });
+  } catch (err) {
+    usageError(err.code === "missing-value" ? err.message : `unknown argument "${err.arg}"`);
+  }
+  if (cli.stopped === "help") { process.stdout.write(USAGE); process.exit(0); }
+
+  let max = 20;
+  if (cli.values.max !== undefined) {
+    max = Number(cli.values.max);
+    if (!Number.isInteger(max) || max < 0) usageError(`--max takes a whole number, not "${cli.values.max}"`);
   }
-  return opts;
+  return { before: cli.values.before, keep: cli.values.keep, max, tbdocs };
 }
 
 class ToolError extends Error {}
diff --git a/scripts/convert_em_dash_separators.mjs b/scripts/convert_em_dash_separators.mjs
index 23070b3d..896614c3 100644
--- a/scripts/convert_em_dash_separators.mjs
+++ b/scripts/convert_em_dash_separators.mjs
@@ -45,6 +45,7 @@ import path from "node:path";
 import { pathToFileURL } from "node:url";
 
 import { createMarkdownIt } from "../builder/render.mjs";
+import { parseCli } from "../lib/cli.mjs";
 import { blockRegions, mapLines, splitCodeSpans } from "../lib/markdown.mjs";
 import { markdownFiles } from "../lib/markdown-files.mjs";
 import { DOCS_DIR } from "../lib/repo-paths.mjs";
@@ -126,7 +127,8 @@ function byPathParts(a, b) {
 }
 
 async function main(argv) {
-  const check = argv.includes("--check");
+  const { values } = parseCli(argv, { options: { check: { type: "boolean" } }, unknown: "ignore" });
+  const check = values.check;
   let files = 0;
   let sep = 0;
   let em = 0;
diff --git a/scripts/crawl_check.mjs b/scripts/crawl_check.mjs
index d2a8c587..e5cd373b 100644
--- a/scripts/crawl_check.mjs
+++ b/scripts/crawl_check.mjs
@@ -18,19 +18,25 @@
 
 import { Parser } from "htmlparser2";
 import { forEachLink } from "../builder/link-check.mjs";
-
-const args = process.argv.slice(2);
-let startArg = null;
-let concurrency = 10;
-let timeoutMs = 15000;
-let skipExternal = false;
-for (let i = 0; i < args.length; i++) {
-  if (args[i] === "--concurrency") concurrency = Number(args[++i]);
-  else if (args[i] === "--timeout") timeoutMs = Number(args[++i]);
-  else if (args[i] === "--skip-external") skipExternal = true;
-  else if (args[i].startsWith("-")) { console.error(`unknown flag: ${args[i]}`); process.exit(2); }
-  else if (!startArg) startArg = args[i];
-}
+import { parseCli, withUsageError } from "../lib/cli.mjs";
+
+const { values, positionals } = withUsageError(
+  () =>
+    parseCli(process.argv.slice(2), {
+      options: {
+        concurrency: { type: "string", default: "10" },
+        timeout: { type: "string", default: "15000" },
+        "skip-external": { type: "boolean" },
+      },
+      positionals: { min: 0 },
+      acceptsValue: () => true,
+    }),
+  { format: (err) => `unknown flag: ${err.arg}` },
+);
+const startArg = positionals[0];
+const concurrency = Number(values.concurrency);
+const timeoutMs = Number(values.timeout);
+const skipExternal = values.skipExternal;
 if (!startArg) {
   console.error("usage: node scripts/crawl_check.mjs <start-url> [--concurrency N] [--timeout MS] [--skip-external]");
   process.exit(2);
diff --git a/scripts/survey_tooling.mjs b/scripts/survey_tooling.mjs
index d9cdba01..8491098e 100644
--- a/scripts/survey_tooling.mjs
+++ b/scripts/survey_tooling.mjs
@@ -50,9 +50,9 @@ import { execFileSync } from "node:child_process";
 import { readFileSync } from "node:fs";
 import { builtinModules } from "node:module";
 import path from "node:path";
-import { parseArgs } from "node:util";
 import * as acorn from "acorn";
 import * as walk from "acorn-walk";
+import { parseCli, withUsageError } from "../lib/cli.mjs";
 import { REPO_ROOT } from "../lib/repo-paths.mjs";
 
 const TOOLING_DIRS = ["builder", "scripts", "lib", "book", "eval", "wisdom", "test", "perf"];
@@ -64,30 +64,29 @@ const ARG_HELPERS = new Set(["flag", "opt", "die"]);
 const USAGE = "usage: node scripts/survey_tooling.mjs [--root DIR] [--summary] " +
   "[--window N] [--top N] [--include-perf]";
 
-let opts;
-try {
-  ({ values: opts } = parseArgs({
-    options: {
-      root: { type: "string" },
-      summary: { type: "boolean", default: false },
-      window: { type: "string", default: "60" },
-      top: { type: "string", default: "45" },
-      "include-perf": { type: "boolean", default: false },
-      help: { type: "boolean", default: false },
-    },
-  }));
-} catch (err) {
-  console.error(`${err.message}\n${USAGE}`);
-  process.exit(2);
-}
-if (opts.help) {
+const { values } = withUsageError(
+  () =>
+    parseCli(process.argv.slice(2), {
+      options: {
+        root: { type: "string" },
+        summary: { type: "boolean", default: false },
+        window: { type: "string", default: "60" },
+        top: { type: "string", default: "45" },
+        "include-perf": { type: "boolean", default: false },
+        help: { type: "boolean", default: false },
+      },
+      positionals: 0,
+    }),
+  { format: (err) => `${err.message}\n${USAGE}` },
+);
+if (values.help) {
   console.log(USAGE);
   process.exit(0);
 }
-const WINDOW = positiveInt("window", opts.window);
-const TOP = positiveInt("top", opts.top);
-const ROOT = path.resolve(opts.root ?? REPO_ROOT);
-const listed = (f) => opts["include-perf"] || !f.startsWith(LAB);
+const WINDOW = positiveInt("window", values.window);
+const TOP = positiveInt("top", values.top);
+const ROOT = path.resolve(values.root ?? REPO_ROOT);
+const listed = (f) => values.includePerf || !f.startsWith(LAB);
 
 function positiveInt(name, raw) {
   const n = Number(raw);
@@ -348,7 +347,7 @@ const summary = [
 console.log(`# Tooling survey: ${ROOT}\n`);
 const width = Math.max(...summary.map(([label]) => label.length));
 for (const [label, value] of summary) console.log(`${label.padEnd(width)}  ${value}`);
-if (opts.summary) process.exit(0);
+if (values.summary) process.exit(0);
 
 // ----------------------------------------------------------------- listings
 
@@ -379,7 +378,7 @@ for (const c of shownClones.slice(0, TOP)) {
   console.log(`              ${c.head.slice(0, 150)}`);
 }
 
-const shownNames = (opts["include-perf"] ? repeatedNames : repeatedOutsideLab)
+const shownNames = (values.includePerf ? repeatedNames : repeatedOutsideLab)
   .map(([name, defs]) => [name, defs.filter((d) => listed(d.file))])
   .sort((p, q) => q[1].length - p[1].length || p[0].localeCompare(q[0]));
 console.log(`\n## ${shownNames.length} top-level function names defined in 2+ files\n`);