diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1baf86f..75cac3f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -18,6 +18,12 @@ Credit the person or project that surfaced the change — the credit line is the
 - process(skill-routing): `learned-css-that-never-applied` routed **baseline** for mdl/review/gate at stages 5–6, trigger-phrased on *"a style change that appears to have done nothing, or an app still grey after a design port every instrument called green"*. Baseline rather than situational on this repo's own rule that a skill living only in the situational table goes unnoticed by projects that are not hunting for it — and not being reached is precisely what this one records — Maurits Visser, from a MOC/PSSR app replacement
 
 ## 2026-09-09
+- fix(bin/sync-project.sh + bin/check-portability.sh): the retire-ledger-row rewrite passed its regex to awk as `-v re="^\\|..."`; gawk (the GitHub runner's awk) processes escapes in -v values, so the pattern became an alternation that matched every line and the whole CLAUDE.local.md was replaced with copies of one row — green under mawk locally, red only in CI. Bracket expressions now; check-portability flags any backslash inside an awk -v value — the toolkit merge queue
+- process(tests/ab + process/token-path-ab-2026-09-09.md): the token-path A/B — answer-key corpus generator and scorer (synthetic Harbour Berth Booking, stdlib only), and the report: wave 1 Sonnet P–2 (branch 31% cheaper, recall 54%→81–94%), wave 2 Haiku P–4 on three corpora (4–8 min, <$1.10 each), the non-reproducing hollow run, the per-stage mandated reading load, and the proportionality finding — the toolkit merge queue
+- process(skills/conversion-runbook.md → Entry Modes): **the docs-ready fast path for a requirements-driven, text-native corpus (Markdown + HTML, no legacy code, no Office/PDF containers)** — measured cause four on the same project: the ledger wanted one disposition per file, every sidecar png/css/js included, for a corpus nothing extracts. Stage 0 = `source-sufficiency.sh init` + CAC-1 + sign-off, triage rows written `N/A (text-native corpus)`; Stage 1 = `bin/html-to-md.sh` once, the KB IS the converted text + `documents-index.md`, ONE ledger mark (`mark <p> 'sources/**' --artifact analysis/knowledge-base/documents-index.md --evidence ... --by ...`), images still read by vision with the index's count as denominator; Stage 2 = one use case per section with a `sourceRef`, rules lifted as stated, validation once; Stages 3–4 unchanged and not skippable (module boundaries, grants, script order). Every command was run against the real gates first, and two things had to change for it to pass: (1) `--adopt 1` is the wrong instrument — adoption waives the stages *before* the point (Stage 0, which ran) and leaves Stage 1 demanding an extraction report no extractor wrote — so the path records `--waive 1 --reason "text-native corpus: ..."` (Stage 2 still runs the ledger: index hidden → Stage 2 exits 1, verified); (2) `source-ledger.sh mark` now strips the source-root segment from a target, so `'sources/**'` — the natural spelling — matches the corpus instead of being refused. Verified that a glob mark whose artifact names every basename yields EXTRACTED for every row, css/js/png included, and that image rows owe no `--media`. `bin/lib/source-formats.tsv` gains route `chrome` for css|map|woff|woff2|ttf|otf|eot|ico ("web export chrome — listed, never content"; `.js` deliberately stays on the code route — one extension, one route, and a `.js` in a migration corpus is application source); `bin/html-to-md.sh` is routed baseline (ba, stages 0–1: "HTML in the source corpus — convert once before anyone reads it"), surfaces re-rendered, baseline 74,147 of 80,000 words. Fixture: tests/wave2/test-source-ledger.sh T12 — the toolkit merge queue, from a Markdown+HTML requirements project
+- new(bin/gate-check.sh + skills/conversion-runbook.md): **a stage run names the runbook lines to read — `Read for this gate: skills/conversion-runbook.md §"Stage N — …" (lines A–B) + §1b Live Checklist (lines C–D)` — instead of the whole 11,700-word file.** Measured cause three on the same Markdown+HTML requirements project: every project's CLAUDE.local.md says "read the runbook FIRST — every session", so every session read all of it. What a stage session needs is §1b (applies to every stage) plus its own stage's §2 section; the spans are derived on every run by grepping the runbook's actual headings (`### Stage N — `, `## 1b.`; keyed on the em dash because `### Stage 0 runs in every entry mode` also starts with `### Stage 0`), never hard-coded, and `build-ready` reads Stage 5's. The runbook's top now carries the matching "How to read this file: not whole" paragraph. Fixture: tests/wave2/test-bug03-gates.sh T10 (line numbers checked against the file's headings, span ends at the next heading, build-ready → Stage 5, whole-project run prints none); test-source-ledger.sh and test-stage-p.sh still pass — the toolkit merge queue, from a Markdown+HTML requirements project
+- fix(bin/sync-project.sh): **retires the always-on `bug-logs/mxcli-bugs.md` row in a project's CLAUDE.local.md → `bin/bug-lookup.sh`, and says so.** Measured cause two on the same Markdown+HTML requirements project: master replaced the 47,500-word ledger's baseline row with bin/bug-lookup.sh on 2026-09-08, but every project scaffolded before that still read the whole ledger every session. A marked routing block was already re-rendered by section 2d — silently; now the retirement is announced ("retired the 47k-word ledger row → bin/bug-lookup.sh"). A hand-written, UNMARKED `## Baseline routing` table (every project bootstrapped before 2026-08-18) got 2d's whole-table refusal and kept the row; new section 2e rewrites that ONE row in place with the row's own path prefix kept and every neighbouring row byte-identical (new `routing_row <name> [prefix]` in bin/lib/skill-routing.sh renders it from the table). CLAUDE.md's "mxcli-project-toolkit Integration" block is NOT edited — it is bootstrap-project.md's LLM merge, not something init-project.sh writes — the row is reported with the exact replacement instead. --dry-run announces and writes nothing; a second run is silent. Fixture: tests/wave2/test-bug12-sync.sh T11 (marked, unmarked, dry-run, idempotence, CLAUDE.md report) — the toolkit merge queue, from a Markdown+HTML requirements project
+- new(bin/html-to-md.sh + bin/lib/html-to-md.py): **convert a saved-webpage corpus to Markdown once, so no session reads raw HTML again.** A requirements-driven project whose sources were Markdown plus browser "save page as" exports (page + `_files/` sidecar) was slow and token-hungry through Stages 1–4; measured cause one: agents opened the .html themselves, at 3–10× the tokens of the page's own text, every session. Now `bin/html-to-md.sh <project>` walks the source root (the inventory's own walk — bin/lib/source-inventory.py, same prune rules) and writes each page to `analysis/knowledge-base/text/<same path>.md` — headings, lists, tables, links, pre/code, bold/italic kept; script/style/noscript/svg/comments and nav/sidebar/footer/cookie/breadcrumb chrome dropped, conservatively (never `<main>`, `<article>`, or anything holding an h1–h3); every `<img>` as `![alt](src)`, inline base64 images decoded to `<page>_images/NN.ext` so a vision read needs no HTML. Each .md opens with source, raw size, words, image count and the section list with md line numbers — the read's denominator. Plus `documents-index.md`: ONE row per file under the root, sidecar png/css/js included, with role (page · markdown · image of <page> · chrome of <page> · other), so a single ledger glob mark can point at it. Idempotent (skips up-to-date pages; `--force`). Prints raw KB → md words and the ratio per page. Stdlib `html.parser` only, bash 3.2. Fixture: tests/wave2/test-html-to-md.sh over a synthetic export (its CAPTURE.md says why synthetic is acceptable for a format with no tool contract), 67 assertions: structure kept, every chrome sentinel absent, base64 written and referenced, section line numbers verified against the file, index names every basename, idempotence, --force, ratio printed — the toolkit merge queue, from a Markdown+HTML requirements project
 - new(project-bin/page-fidelity.js): **`class="bound"` — the wireframe author saying "this text is a sample of bound data".** The scorer already had this concept and applied it structurally: `<td>` is excluded from the text corpus because a wireframe's table cells are sample ROWS and a page that correctly BINDS them contains none of that literal text. The same is true of a bound value anywhere else on the screen, and there the structure gives nothing away — an `<h1>` holding a record's number and name looks exactly like an `<h1>` holding page copy, and a chip holding a filename looks exactly like a chip holding a label. Measured on a MOC/PSSR app replacement's project detail page, 2026-09-09: **54%**, and all three misses were sample values the page could not contain — the record's own title, and a mocked attachment's filename, twice. The page was right; the denominator was wrong, and the number was about to be read off as a gate verdict. So the marker is **DECLARED, not guessed**: an element carrying `bound` leaves both the text corpus and the class denominator, and guessing was the alternative and does not work — a heading is bound or it is not, and only the person who drew the screen knows which. Put it on the smallest element that holds only the value (`<h1 class="bound">` leaves no heading behind; `<span class="bound">` inside a chip leaves the chip). Fixture grows to **18 assertions** including that a bound heading leaves the DENOMINATOR rather than merely stopping being reported as missed — otherwise the score would be 1 of 2 and still look clean. Known-bad control without the marker: **5 of 18 fail**. Same page scores 100% (3/3 headings, 2/2 content) with it — Maurits Visser, from a MOC/PSSR app replacement
 - process(bug-logs): BUG-114 filed upstream as mendixlabs/mxcli#1076 with BUG-118 as its second reproduction; both drafts and the ledger header stamped FILED — the toolkit merge queue
 - fix(project-bin/page-fidelity.js): **structure classed as bound data, and the score of record silently going `null%` again.** A wireframe's own `<style>` defines two very different kinds of class — BOUND-DATA MOCKS (a repeated region of sample rows, whose literal text a correctly *binding* page contains none of) and STRUCTURE (the wrapper, the page header, the toolbar — furniture the page script genuinely must declare) — and the classifier **drops a mock's whole subtree**, so a misclassified structural class deletes page content from the denominator. The test was `uses === 1 && kept < 0.4`, once-used AND dominant, which contradicts the paragraph directly above it stating that a mock is a **repeated** region: a once-used class whose subtree was *small* fell through the second conjunct and was dropped as sample data. Measured on a MOC/PSSR app replacement's project overview, 2026-09-09: `.page-head` (uses=1, kept=0.513) was deleted **with the page's only `<h1>` inside it**, `.toolbar` (uses=1, kept=0.825) with it, and every dimension reported `0 of 0` — which normalizes to **`null%`**, so the run printed a clean report over an empty corpus. That is the same silent-null failure this file's own header note says was worth fixing, arriving a second time through the other conjunct, on a page that scores **100%** once the page is not gutted. The threshold is **removed rather than retuned**: it was a guess, and any value for it splits once-used wrappers on a measurement that has nothing to do with whether their content is bound data; a repeated region is still a mock at any size, which is the half that was always right. New fixture `tests/wave2/test-page-fidelity-mocks.sh`, **14 assertions**, with two captured wireframe shapes and a `CAPTURE.md` stating that only literal text and class prefixes were changed. Its **first assertion is that the score is not `null`, not that it is high** — a null on a wireframe that draws an `<h1>` means the scorer gutted the page, whatever the eventual percentage. Proven against a known-bad control carrying the old rule: **8 of 14 fail** — Maurits Visser, from a MOC/PSSR app replacement
diff --git a/README.md b/README.md
index 5e0349d..54a58c6 100644
--- a/README.md
+++ b/README.md
@@ -733,6 +733,7 @@ The "When to use which skill" table above is *situational* — load a skill when
 | Deciding whether to extract at all, before any BRD gets generated | `skills/source-triage.md` |
 | Taking in a new source — before generating anything from it. Grades what the source can support; nothing else in this toolkit reads a source | `bin/source-sufficiency.sh` |
 | Closing Stage 1, or adding files to a source folder — every inventoried file must name the artifact that consumed it (text AND embedded diagrams), or carry a waiver; blocks Stages 1–2 until it does | `bin/source-ledger.sh` |
+| HTML in the source corpus — convert once before anyone reads it: `bin/html-to-md.sh <project>` writes each page as Markdown under analysis/knowledge-base/text/ (3–10× fewer tokens than the raw export; inline images decoded to files; section list with line numbers as the read's denominator) plus documents-index.md over EVERY file, which one ledger glob mark points at. A session that opens a .html itself has skipped this | `bin/html-to-md.sh` |
 | Deciding who answers a question — before putting any batch to the user. gap/conflict/choice/user-only is what keeps a gate batch at four questions instead of 127 | `bin/question-kinds.sh` |
 | Writing BRDs, especially several in parallel — "build" before the fan-out, "check" before any BRD is called done | `bin/facts-lock.sh` |
 | Building any module — before the first script. The mdl-agent's single per-module input | `skills/module-brief.md` |
diff --git a/ROUTING.md b/ROUTING.md
index e1fc1c4..257a215 100644
--- a/ROUTING.md
+++ b/ROUTING.md
@@ -64,6 +64,7 @@ picks the row up. That is the whole procedure — there is no second list to rem
 | Deciding whether to extract at all, before any BRD gets generated | `skills/source-triage.md` | ba | 0 | baseline |
 | Taking in a new source — before generating anything from it. Grades what the source can support; nothing else in this toolkit reads a source | `bin/source-sufficiency.sh` | ba | 0,1 | baseline |
 | Closing Stage 1, or adding files to a source folder — every inventoried file must name the artifact that consumed it (text AND embedded diagrams), or carry a waiver; blocks Stages 1–2 until it does | `bin/source-ledger.sh` | ba | 0,1,2 | baseline |
+| HTML in the source corpus — convert once before anyone reads it: `bin/html-to-md.sh <project>` writes each page as Markdown under analysis/knowledge-base/text/ (3–10× fewer tokens than the raw export; inline images decoded to files; section list with line numbers as the read's denominator) plus documents-index.md over EVERY file, which one ledger glob mark points at. A session that opens a .html itself has skipped this | `bin/html-to-md.sh` | ba | 0,1 | baseline |
 | Rendering a filled triage.md for review — the triage.html surface Stage 0 names. Renders only; the Stage 0 verdict stays with gate-check and the judgement with source-triage.md | `bin/triage-report.sh` | ba | 0 | ondemand |
 | Reviewing what the extraction actually produced — the Stage 1 surface, and the file the Stage 1 gate looks for. Renders a code-extracted and a document knowledge base alike, so a requirements-driven project gets the surface too; prints no zero that a second record does not agree with | `bin/extraction-report.sh` | ba | 1 | ondemand |
 | Assessing or planning a migration up front, before any pipeline is chosen | `skills/assess-migration.md` | ba | 0 | ondemand |
diff --git a/agents/ba-agent.md b/agents/ba-agent.md
index c66c2b0..fa1f693 100644
--- a/agents/ba-agent.md
+++ b/agents/ba-agent.md
@@ -44,6 +44,7 @@ You run discovery and the interview gates for {{PROJECT}}. You never touch the `
 | `skills/source-triage.md` | Deciding whether to extract at all, before any BRD gets generated |
 | `bin/source-sufficiency.sh` | Taking in a new source — before generating anything from it. Grades what the source can support; nothing else in this toolkit reads a source |
 | `bin/source-ledger.sh` | Closing Stage 1, or adding files to a source folder — every inventoried file must name the artifact that consumed it (text AND embedded diagrams), or carry a waiver; blocks Stages 1–2 until it does |
+| `bin/html-to-md.sh` | HTML in the source corpus — convert once before anyone reads it: `bin/html-to-md.sh <project>` writes each page as Markdown under analysis/knowledge-base/text/ (3–10× fewer tokens than the raw export; inline images decoded to files; section list with line numbers as the read's denominator) plus documents-index.md over EVERY file, which one ledger glob mark points at. A session that opens a .html itself has skipped this |
 | `bin/question-kinds.sh` | Deciding who answers a question — before putting any batch to the user. gap/conflict/choice/user-only is what keeps a gate batch at four questions instead of 127 |
 | `bin/facts-lock.sh` | Writing BRDs, especially several in parallel — "build" before the fan-out, "check" before any BRD is called done |
 | `skills/module-brief.md` | Building any module — before the first script. The mdl-agent's single per-module input |
diff --git a/bin/check-portability.sh b/bin/check-portability.sh
index 506e3d4..58eab01 100755
--- a/bin/check-portability.sh
+++ b/bin/check-portability.sh
@@ -127,6 +127,20 @@ while IFS= read -r f; do
           'Use: arr=(); while IFS= read -r x; do arr+=("$x"); done < <(cmd)' ;;
     esac
 
+    # awk -v processes escape sequences in the VALUE (gawk warns and rewrites, mawk keeps the
+    # backslash): a regex passed as -v re="^\\|..." became "^|..." under gawk — the GitHub
+    # runner's awk — and matched every line (sync-project 2e rewrote a whole CLAUDE.local.md
+    # with copies of one row, CI-only, 2026-09-12). Bracket expressions carry no backslash.
+    case "$txt" in
+      *awk*)
+        # A backslash inside a $(...) substitution is the shell's, not the value's (e.g.
+        # -v ok="$(... | tr '\n' ' ')"): strip substitutions before looking.
+        if printf '%s' "$txt" | sed 's/\$([^)]*)//g' | grep -Eq -- '-v [A-Za-z_][A-Za-z_0-9]*="[^"]*\\'; then
+          report "$f" "$ln" "backslash inside an awk -v value (gawk rewrites escapes, mawk does not)" \
+            'Pass patterns without backslashes: [|] for a literal pipe, [.] for a dot, or read the regex from ENVIRON["re"].'
+        fi ;;
+    esac
+
     case "$txt" in
       *'grep -P'*|*'grep -qP'*|*'grep -oP'*)
         report "$f" "$ln" "grep -P is GNU-only" \
diff --git a/bin/gate-check.sh b/bin/gate-check.sh
index 28a8737..0dc3cd2 100755
--- a/bin/gate-check.sh
+++ b/bin/gate-check.sh
@@ -2041,6 +2041,45 @@ else
     DRIFT_NOTE="$DRIFT_COUNT decision(s) touch a BRD/wireframe not yet re-synced (see '[sync: … UNSYNCED]' in $REGISTER) — ba-agent must update the BRD/wireframe, then flip the marker to 'synced <date>', before this gate passes"
   fi
 fi
+# ---------------------------------------------------------------------------
+# Read for this gate — the runbook lines this stage actually needs.
+#
+# WHY (2026-09-09, a Markdown+HTML requirements project). skills/conversion-runbook.md is
+# ~11,700 words and every project's CLAUDE.local.md says "read it FIRST — every session", so
+# every session read all of it — measured cause three of that project's slow Stages 1–4. What a
+# stage session needs is §1b (the Live Checklist Protocol, which applies to every stage) plus
+# its own stage's section under §2; the rest is other stages' business until a question sends
+# the reader there. So a stage-specific run names those two spans by line number, derived by
+# grepping the runbook's actual headings ("### Stage N — …", "## 1b. …") on every run — never
+# a hard-coded number, which would be wrong after the next edit. The runbook's own "how to
+# read this" paragraph states the same rule; this line is what makes it actionable.
+runbook_span() { # runbook_span <file> <start-regex> <end-regex> — "A–B" (1-based, inclusive) or ""
+  awk -v h="$2" -v e="$3" '
+    !start && $0 ~ h { start = NR; next }
+    start && $0 ~ e   { end = NR - 1; exit }
+    END { if (start) { if (!end) end = NR; printf "%d–%d", start, end } }' "$1" 2>/dev/null
+}
+if [ -n "$REQUESTED_STAGE" ]; then
+  RB_FILE="$TOOLKIT_DIR/skills/conversion-runbook.md"
+  case "$REQUESTED_STAGE" in
+    build-ready) RB_STAGE="5" ;;   # build-ready is Stage 5's readiness check; it reads Stage 5's section
+    *)           RB_STAGE="$(printf '%s' "$REQUESTED_STAGE" | tr '[:lower:]' '[:upper:]')" ;;
+  esac
+  if [ -f "$RB_FILE" ]; then
+    # Keyed on the " — " every stage heading carries: "### Stage 0 runs in every entry mode"
+    # (under Entry Modes) also starts with "### Stage 0", and matched first without it.
+    RB_HEAD="$(grep -m1 "^### Stage $RB_STAGE — " "$RB_FILE" | sed 's/^### //; s/[[:space:]]*$//')"
+    RB_SPAN="$(runbook_span "$RB_FILE" "^### Stage $RB_STAGE — " "^###? ")"
+    RB_1B="$(runbook_span "$RB_FILE" "^## 1b\\." "^## ")"
+    if [ -n "$RB_HEAD" ] && [ -n "$RB_SPAN" ] && [ -n "$RB_1B" ]; then
+      printf 'Read for this gate: skills/conversion-runbook.md §"%s" (lines %s) + §1b Live Checklist (lines %s) — not the whole file\n' \
+        "$RB_HEAD" "$RB_SPAN" "$RB_1B"
+    else
+      echo "Read for this gate: skills/conversion-runbook.md — could not locate '### Stage $RB_STAGE — ' or '## 1b.' by heading; read §1b and your stage's §2 section"
+    fi
+  fi
+fi
+
 printf "Drift (BRD sync): %s — %s\n" "$DRIFT_STATUS" "$DRIFT_NOTE"
 
 # ---------------------------------------------------------------------------
diff --git a/bin/html-to-md.sh b/bin/html-to-md.sh
new file mode 100755
index 0000000..5f55b3f
--- /dev/null
+++ b/bin/html-to-md.sh
@@ -0,0 +1,74 @@
+#!/usr/bin/env bash
+# html-to-md.sh — convert every HTML page in a project's source corpus to Markdown, ONCE.
+#
+#   bin/html-to-md.sh <project-root> [--source <dir>] [--out <dir>] [--force]
+#
+# WHY THIS EXISTS (2026-09-09). A requirements-driven project whose corpus was Markdown files
+# plus saved-webpage exports (each .html with its `_files` sidecar folder) was slow and
+# token-hungry through Stages 1–4, and the measured cause was that every session read the raw
+# HTML: 3–10× the tokens of the page's own text, paid again each time. Convert once, and the
+# knowledge base IS the converted text — that is the "docs-ready" fast path in
+# skills/conversion-runbook.md → Entry Modes → "Requirements-driven, docs-ready corpus".
+#
+# WHAT IT WRITES (all under <out>, default analysis/knowledge-base/text/):
+#   <same relative path>.md         headings, paragraphs, lists, tables, links, code; every <img>
+#                                   as ![alt](src); scripts, styles, nav/footer/sidebar chrome gone
+#   <same relative path>_images/    every inline base64 image decoded to a file, so it can be
+#                                   read with vision without opening the HTML
+#   ../documents-index.md           ONE row per file under the source root — pages, markdown,
+#                                   sidecar images, css, js, fonts — so a single ledger mark can
+#                                   point at it:  bin/source-ledger.sh mark <p> '*' --artifact
+#                                   analysis/knowledge-base/documents-index.md --evidence "..."
+# Each .md opens with a header — source path, raw size, words, images, and the section list with
+# md line numbers — which is the denominator a reader states ("all N sections covered").
+#
+# Source root: --source wins; else sources/, then source/ (the two drop-folder spellings
+# bin/init-project.sh scaffolds — the same detection as bin/source-sufficiency.sh, minus that
+# script's legacy analysis/ fallback, which would convert the project's own outputs).
+#
+# Idempotent: a page whose .md is newer than its source is skipped; --force reconverts all.
+# Bash 3.2 + any Python 3 (bin/lib/portable.sh); the converter is bin/lib/html-to-md.py,
+# standard library only. Exit 0 converted (or nothing to do) · 2 usage · 3 no files found.
+#
+# Fixture: tests/wave2/test-html-to-md.sh (a synthetic saved-webpage export; see its CAPTURE.md).
+set -u
+
+# shellcheck disable=SC1091
+. "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/lib/portable.sh"
+
+usage() {
+  echo "usage: html-to-md.sh <project-root> [--source <dir>] [--out <dir>] [--force]" >&2
+  exit 2
+}
+
+PROJECT_DIR=""; SOURCES_DIR=""; OUT_DIR=""; FORCE=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --source) SOURCES_DIR="${2:-}"; shift 2 ;;
+    --out)    OUT_DIR="${2:-}"; shift 2 ;;
+    --force)  FORCE="--force"; shift ;;
+    -h|--help) usage ;;
+    -*) echo "html-to-md: unknown option: $1" >&2; usage ;;
+    *)  [ -z "$PROJECT_DIR" ] || usage; PROJECT_DIR="$1"; shift ;;
+  esac
+done
+[ -n "$PROJECT_DIR" ] || usage
+[ -d "$PROJECT_DIR" ] || { echo "html-to-md: not a directory: $PROJECT_DIR" >&2; exit 2; }
+PROJECT_DIR="$(cd "$PROJECT_DIR" && pwd)"
+
+if [ -z "$SOURCES_DIR" ]; then
+  if   [ -d "$PROJECT_DIR/sources" ]; then SOURCES_DIR="$PROJECT_DIR/sources"
+  elif [ -d "$PROJECT_DIR/source"  ]; then SOURCES_DIR="$PROJECT_DIR/source"
+  else
+    echo "html-to-md: no sources/ or source/ under $PROJECT_DIR — name the corpus with --source <dir>" >&2
+    exit 2
+  fi
+fi
+[ -d "$SOURCES_DIR" ] || { echo "html-to-md: source root is not a directory: $SOURCES_DIR" >&2; exit 2; }
+[ -n "$OUT_DIR" ] || OUT_DIR="$PROJECT_DIR/analysis/knowledge-base/text"
+
+CONVERTER="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/lib/html-to-md.py"
+[ -f "$CONVERTER" ] || { echo "html-to-md: $CONVERTER missing" >&2; exit 2; }
+require_py
+
+"$PY" "$CONVERTER" "$PROJECT_DIR" "$SOURCES_DIR" "$OUT_DIR" $FORCE
diff --git a/bin/lib/html-to-md.py b/bin/lib/html-to-md.py
new file mode 100644
index 0000000..fb12fc9
--- /dev/null
+++ b/bin/lib/html-to-md.py
@@ -0,0 +1,700 @@
+#!/usr/bin/env python3
+"""html-to-md.py — convert a saved-webpage corpus to Markdown ONCE, so nobody reads raw HTML.
+
+WHY THIS EXISTS (2026-09-09, a requirements-driven project whose corpus was Markdown files plus
+HTML pages — saved-webpage exports with their `_files` sidecar folders). Stages 1–4 were slow
+and token-hungry, and the measured cause was that agents opened the .html files themselves: a
+saved page is 3–10× the tokens of its own text (inline styles, nested wrapper divs, the nav
+sidebar, the footer, a base64 screenshot or two), and every session paid that cost again. The
+fix is a one-time transform whose output is what everyone reads instead.
+
+WHAT IT WRITES. For each .html/.htm/.xhtml under the source root:
+  <out>/<same relative path>.md            the text, as Markdown, with a small header
+  <out>/<same relative path>_images/NN.ext every inline base64 image, decoded to a file, so a
+                                           vision read is possible without the HTML
+and one index over EVERY file under the source root — pages, markdown, sidecar images, css,
+js, fonts — at <out>/../documents-index.md. The index names every file's basename exactly,
+because it is the artifact a single ledger glob mark points at (bin/source-ledger.sh greps the
+artifact for each inventoried basename; a row it does not name reports FAULT).
+
+WHAT IT KEEPS: h1–h6, paragraphs, ordered/unordered lists, tables (as Markdown tables),
+bold/italic, links as [text](href), <pre>/<code>, every <img> as ![alt](src).
+WHAT IT DROPS: <script>, <style>, <noscript>, <svg>, <template>, comments, and chrome regions —
+<nav>, <footer>, <header> when it contains a nav, role=navigation|banner|contentinfo, and any
+element whose class/id contains nav|sidebar|footer|menu|cookie|breadcrumb. Conservative on
+purpose: <main>, <article> and anything containing an h1–h3 are never dropped, whatever their
+class says — a wrongly dropped region is content silently gone, which is worse than a nav
+that survives.
+
+THE HEADER is the read's denominator. Each .md opens with source path, raw size, word count,
+image count and the section list (every heading with the md line number it sits on), so a
+reader can state "all N sections covered" and a reviewer can check the claim by line number.
+
+Idempotent: a page whose .md is newer than its source is skipped (its header is read back for
+the index) unless --force. The file walk is bin/lib/source-inventory.py's — the same prune
+rules as the Stage 0 inventory, so the index and the inventory can never disagree about what
+"every file" means.
+
+Usage (called by bin/html-to-md.sh; runnable directly):
+    html-to-md.py <project-root> <source-root> <out-root> [--force]
+
+Python 3, standard library only (html.parser, base64). Writes only under <out-root> and the
+index beside it.
+"""
+import base64
+import importlib.util
+import os
+import re
+import sys
+import time
+from html.parser import HTMLParser
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+
+# The corpus walk is the inventory's, not a second copy of its prune rules.
+_spec = importlib.util.spec_from_file_location('source_inventory', os.path.join(HERE, 'source-inventory.py'))
+_inv = importlib.util.module_from_spec(_spec)
+_spec.loader.exec_module(_inv)
+
+PAGE_EXTS = ('html', 'htm', 'xhtml')
+MD_EXTS = ('md', 'markdown')
+IMG_EXTS = ('png', 'jpg', 'jpeg', 'gif', 'bmp', 'webp', 'svg', 'tif', 'tiff', 'ico')
+CHROME_EXTS = ('css', 'js', 'map', 'woff', 'woff2', 'ttf', 'otf', 'eot')
+
+VOID = {'img', 'br', 'hr', 'input', 'meta', 'link', 'area', 'base', 'col', 'embed', 'param',
+        'source', 'track', 'wbr'}
+DROP_TAGS = {'script', 'style', 'noscript', 'svg', 'template', 'head', 'iframe', 'object',
+             'canvas', 'video', 'audio', 'map', 'title', 'select', 'datalist'}
+BLOCK_TAGS = {'p', 'div', 'section', 'article', 'main', 'body', 'html', 'ul', 'ol', 'li',
+              'table', 'thead', 'tbody', 'tfoot', 'tr', 'td', 'th', 'blockquote', 'pre', 'hr',
+              'dl', 'dt', 'dd', 'figure', 'figcaption', 'header', 'footer', 'aside', 'nav',
+              'form', 'fieldset', 'legend', 'details', 'summary', 'address', 'center',
+              'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'caption', 'colgroup'}
+# Opening one of these implicitly closes an open one of the same kind (browsers do this; a
+# saved page written by hand or by an old CMS relies on it).
+IMPLICIT_CLOSE = {  # tag: (ancestors it closes, ancestors that end the search)
+    'p': ({'p'}, None),                       # None: any other block tag stops it
+    'li': ({'li'}, {'ul', 'ol'}),
+    'tr': ({'tr'}, {'table', 'thead', 'tbody', 'tfoot'}),
+    'td': ({'td', 'th'}, {'tr', 'table'}),
+    'th': ({'td', 'th'}, {'tr', 'table'}),
+    'dt': ({'dt', 'dd'}, {'dl'}),
+    'dd': ({'dt', 'dd'}, {'dl'}),
+    'option': ({'option'}, {'select', 'datalist'}),
+}
+CHROME_WORDS = ('nav', 'sidebar', 'footer', 'menu', 'cookie', 'breadcrumb')
+CHROME_ROLES = ('navigation', 'banner', 'contentinfo')
+NEVER_DROP = {'main', 'article', 'body', 'html'}
+
+
+class Node:
+    __slots__ = ('tag', 'attrs', 'children', 'parent')
+
+    def __init__(self, tag, attrs=None, parent=None):
+        self.tag = tag
+        self.attrs = dict(attrs or [])
+        self.children = []
+        self.parent = parent
+
+
+class TreeBuilder(HTMLParser):
+    """html.parser events → a small element tree. Text nodes are plain str children."""
+
+    def __init__(self):
+        super().__init__(convert_charrefs=True)
+        self.root = Node('#root')
+        self.cur = self.root
+        self.title = ''
+        self._in_title = False
+
+    def handle_starttag(self, tag, attrs):
+        tag = tag.lower()
+        if tag == 'title':
+            self._in_title = True
+        # implicit closes
+        rule = IMPLICIT_CLOSE.get(tag)
+        if rule:
+            closers, stops = rule
+            n = self.cur
+            while n is not None and n.tag != '#root':
+                if n.tag in closers:
+                    self.cur = n.parent
+                    break
+                if (stops is None and n.tag in BLOCK_TAGS) or (stops is not None and n.tag in stops):
+                    break
+                n = n.parent
+        node = Node(tag, attrs, self.cur)
+        self.cur.children.append(node)
+        if tag not in VOID:
+            self.cur = node
+
+    def handle_startendtag(self, tag, attrs):
+        node = Node(tag.lower(), attrs, self.cur)
+        self.cur.children.append(node)
+
+    def handle_endtag(self, tag):
+        tag = tag.lower()
+        if tag == 'title':
+            self._in_title = False
+        if tag in VOID:
+            return
+        n = self.cur
+        while n is not None and n.tag != '#root':
+            if n.tag == tag:
+                self.cur = n.parent
+                return
+            n = n.parent
+        # stray end tag: ignore
+
+    def handle_data(self, data):
+        if self._in_title:
+            self.title += data
+        self.cur.children.append(data)
+
+    def handle_comment(self, data):
+        pass
+
+
+# --- chrome detection ------------------------------------------------------------------------
+
+def _class_id(node):
+    return ((node.attrs.get('class') or '') + ' ' + (node.attrs.get('id') or '')).lower()
+
+
+def contains_heading(node, upto=3):
+    for c in node.children:
+        if isinstance(c, Node):
+            if len(c.tag) == 2 and c.tag[0] == 'h' and c.tag[1].isdigit() and int(c.tag[1]) <= upto:
+                return True
+            if contains_heading(c, upto):
+                return True
+    return False
+
+
+def contains_tag(node, tag):
+    for c in node.children:
+        if isinstance(c, Node):
+            if c.tag == tag or contains_tag(c, tag):
+                return True
+    return False
+
+
+def is_chrome(node):
+    """Drop this element as chrome? Conservative: main/article/anything with an h1–h3 stays."""
+    if node.tag in NEVER_DROP:
+        return False
+    hit = False
+    if node.tag == 'nav' or node.tag == 'footer':
+        hit = True
+    elif node.tag == 'header' and contains_tag(node, 'nav'):
+        hit = True
+    elif (node.attrs.get('role') or '').lower() in CHROME_ROLES:
+        hit = True
+    else:
+        ci = _class_id(node)
+        if ci.strip() and any(w in ci for w in CHROME_WORDS):
+            hit = True
+    if not hit:
+        return False
+    if contains_heading(node, 3):
+        return False
+    return True
+
+
+# --- rendering ---------------------------------------------------------------------------------
+
+class Renderer:
+    def __init__(self, page_dir, images_dir_rel, images_dir_abs, project=None):
+        self.page_dir = page_dir          # where the html lives: relative src values resolve here
+        self.project = project            # sidecar refs are rewritten project-relative when they exist
+        self.images_dir_rel = images_dir_rel
+        self.images_dir_abs = images_dir_abs
+        self.image_count = 0
+        self.inline_written = 0
+        self.sidecar_refs = []   # src values of non-data images, as written in the html
+        self.dropped = 0
+        self.blocks = []         # list of markdown block strings (no trailing newline)
+
+    # -- inline -------------------------------------------------------------------------------
+    def inline(self, node, pre=False):
+        """Render the children of node as one inline string."""
+        out = []
+        for c in node.children:
+            if isinstance(c, str):
+                out.append(c if pre else re.sub(r'\s+', ' ', c))
+                continue
+            t = c.tag
+            if t in DROP_TAGS:
+                continue
+            if is_chrome(c):
+                self.dropped += 1
+                continue
+            if t == 'br':
+                out.append('\n' if pre else '  \n')
+            elif t == 'img':
+                out.append(self.image(c))
+            elif t in ('strong', 'b'):
+                s = self.inline(c, pre).strip()
+                out.append(f'**{s}**' if s else '')
+            elif t in ('em', 'i'):
+                s = self.inline(c, pre).strip()
+                out.append(f'*{s}*' if s else '')
+            elif t == 'code' and not pre:
+                s = self.inline(c, True).strip().replace('`', '')
+                out.append(f'`{s}`' if s else '')
+            elif t == 'a':
+                s = self.inline(c, pre).strip()
+                href = (c.attrs.get('href') or '').strip()
+                if s and href and not href.lower().startswith(('javascript:', '#')):
+                    out.append(f'[{s}]({href})')
+                else:
+                    out.append(s)
+            elif t in BLOCK_TAGS:
+                # a block inside an inline context (e.g. <div> in <a>): flatten to text
+                out.append(' ' + self.inline(c, pre) + ' ')
+            elif t == 'input':
+                v = c.attrs.get('value') or ''
+                ty = (c.attrs.get('type') or 'text').lower()
+                if ty in ('checkbox', 'radio'):
+                    out.append('[x] ' if 'checked' in c.attrs else '[ ] ')
+                elif ty not in ('hidden', 'submit', 'button'):
+                    out.append(f'[{v}]' if v else '')
+            else:
+                out.append(self.inline(c, pre))
+        s = ''.join(out)
+        return s if pre else re.sub(r'[ \t]+', ' ', s)
+
+    def image(self, node):
+        src = (node.attrs.get('src') or '').strip()
+        alt = re.sub(r'\s+', ' ', (node.attrs.get('alt') or '').strip())
+        if not src:
+            return ''
+        self.image_count += 1
+        if src.lower().startswith('data:'):
+            path = self.write_inline(src)
+            if path:
+                return f'![{alt}]({path})'
+            return f'![{alt}](data:… inline image {self.image_count}, undecodable)'
+        self.sidecar_refs.append(src)
+        # A sidecar path is relative to the HTML's own folder, which is not where the .md lives.
+        # Rewrite it project-relative when the file exists, so the reference resolves from
+        # anywhere in the project (and names the sidecar exactly as the inventory does).
+        if self.page_dir and self.project and '://' not in src:
+            cand = os.path.normpath(os.path.join(self.page_dir, re.sub(r'[?#].*$', '', src)))
+            if os.path.exists(cand):
+                src = os.path.relpath(cand, self.project).replace(os.sep, '/')
+        return f'![{alt}]({src})'
+
+    def write_inline(self, data_uri):
+        m = re.match(r'data:image/([a-zA-Z0-9.+-]+);base64,(.*)$', data_uri, re.S)
+        if not m:
+            return None
+        ext = m.group(1).lower()
+        ext = {'jpeg': 'jpg', 'svg+xml': 'svg'}.get(ext, ext)
+        try:
+            raw = base64.b64decode(re.sub(r'\s+', '', m.group(2)), validate=False)
+        except Exception:  # noqa: BLE001
+            return None
+        os.makedirs(self.images_dir_abs, exist_ok=True)
+        self.inline_written += 1
+        name = f'{self.inline_written:02d}.{ext}'
+        with open(os.path.join(self.images_dir_abs, name), 'wb') as f:
+            f.write(raw)
+        return f'{self.images_dir_rel}/{name}'
+
+    # -- blocks -------------------------------------------------------------------------------
+    def emit(self, text):
+        text = text.strip('\n')
+        if text.strip():
+            self.blocks.append(text)
+
+    def flush_inline(self, buf):
+        s = ''.join(buf).strip()
+        if s:
+            self.emit(s)
+        del buf[:]
+
+    def block(self, node, depth=0):
+        """Render node's children as blocks; inline runs become paragraphs."""
+        buf = []
+        for c in node.children:
+            if isinstance(c, str):
+                buf.append(re.sub(r'\s+', ' ', c))
+                continue
+            t = c.tag
+            if t in DROP_TAGS:
+                continue
+            if is_chrome(c):
+                self.dropped += 1
+                continue
+            if len(t) == 2 and t[0] == 'h' and t[1].isdigit():
+                self.flush_inline(buf)
+                s = self.inline(c).strip()
+                if s:
+                    self.emit('#' * int(t[1]) + ' ' + s)
+            elif t in ('ul', 'ol'):
+                self.flush_inline(buf)
+                self.emit(self.list(c, depth))
+            elif t == 'table':
+                self.flush_inline(buf)
+                self.emit(self.table(c))
+            elif t == 'pre':
+                self.flush_inline(buf)
+                s = self.inline(c, pre=True).strip('\n')
+                self.emit('```\n' + s + '\n```')
+            elif t == 'hr':
+                self.flush_inline(buf)
+                self.emit('---')
+            elif t == 'blockquote':
+                self.flush_inline(buf)
+                sub = Renderer(self.page_dir, self.images_dir_rel, self.images_dir_abs, self.project)
+                sub.inline_written = self.inline_written
+                sub.block(c, depth)
+                self.adopt(sub)
+                self.emit('\n'.join('> ' + l for b in sub.blocks for l in b.split('\n')))
+            elif t in ('dt',):
+                self.flush_inline(buf)
+                self.emit('**' + self.inline(c).strip() + '**')
+            elif t in ('dd',):
+                self.flush_inline(buf)
+                self.emit(': ' + self.inline(c).strip())
+            elif t in BLOCK_TAGS or t in ('li',):
+                # a block container: if it holds only inline content, it is a paragraph;
+                # otherwise recurse
+                if any(isinstance(g, Node) and (g.tag in BLOCK_TAGS or g.tag in ('ul', 'ol', 'table')) for g in c.children):
+                    self.flush_inline(buf)
+                    self.block(c, depth)
+                else:
+                    self.flush_inline(buf)
+                    s = self.inline(c).strip()
+                    if s:
+                        self.emit(s)
+            else:
+                buf.append(self.inline_one(c))
+        self.flush_inline(buf)
+
+    def inline_one(self, node):
+        wrapper = Node('#w')
+        wrapper.children = [node]
+        return self.inline(wrapper)
+
+    def adopt(self, sub):
+        self.image_count += sub.image_count
+        self.inline_written = sub.inline_written
+        self.sidecar_refs += sub.sidecar_refs
+        self.dropped += sub.dropped
+
+    def list(self, node, depth):
+        lines = []
+        ordered = node.tag == 'ol'
+        n = 0
+        for c in node.children:
+            if not isinstance(c, Node) or c.tag != 'li':
+                continue
+            n += 1
+            marker = f'{n}. ' if ordered else '- '
+            head_parts = []
+            nested = []
+            for g in c.children:
+                if isinstance(g, Node) and g.tag in ('ul', 'ol'):
+                    nested.append(g)
+                elif isinstance(g, Node) and g.tag in ('p', 'div'):
+                    head_parts.append(self.inline(g))
+                elif isinstance(g, Node) and g.tag == 'table':
+                    nested.append(g)
+                else:
+                    w = Node('#w'); w.children = [g]
+                    head_parts.append(self.inline(w))
+            head = re.sub(r'\s+', ' ', ''.join(head_parts)).strip()
+            lines.append('  ' * depth + marker + head)
+            for g in nested:
+                if g.tag == 'table':
+                    lines.append('\n'.join('  ' * (depth + 1) + l for l in self.table(g).split('\n')))
+                else:
+                    lines.append(self.list(g, depth + 1))
+        return '\n'.join(l for l in lines if l.strip())
+
+    def table(self, node):
+        rows = []
+        has_th = []
+
+        def cell_text(cell):
+            return re.sub(r'\s+', ' ', self.inline(cell)).strip().replace('|', '\\|')
+
+        def walk(n):
+            for c in n.children:
+                if not isinstance(c, Node):
+                    continue
+                if c.tag == 'tr':
+                    cells = [g for g in c.children if isinstance(g, Node) and g.tag in ('td', 'th')]
+                    if cells:
+                        rows.append([cell_text(g) for g in cells])
+                        has_th.append(all(g.tag == 'th' for g in cells))
+                elif c.tag in ('thead', 'tbody', 'tfoot'):
+                    walk(c)
+                elif c.tag == 'caption':
+                    cap = self.inline(c).strip()
+                    if cap:
+                        rows.append(['__caption__', cap])
+                        has_th.append(False)
+        walk(node)
+        caption = None
+        if rows and rows[0][0] == '__caption__':
+            caption = rows.pop(0)[1]; has_th.pop(0)
+        if not rows:
+            return ''
+        width = max(len(r) for r in rows)
+        rows = [r + [''] * (width - len(r)) for r in rows]
+        out = []
+        if caption:
+            out.append(f'**{caption}**\n')
+        out.append('| ' + ' | '.join(rows[0]) + ' |')
+        out.append('|' + '---|' * width)
+        for r in rows[1:]:
+            out.append('| ' + ' | '.join(r) + ' |')
+        return '\n'.join(out)
+
+
+# --- one page ----------------------------------------------------------------------------------
+
+def convert_page(src_abs, src_rel_project, out_abs, images_dir_abs, project):
+    with open(src_abs, 'rb') as f:
+        raw = f.read()
+    text = raw.decode('utf-8', 'replace')
+    m = re.search(rb'charset\s*=\s*["\']?([A-Za-z0-9_-]+)', raw[:4096])
+    if m and m.group(1).decode('ascii', 'replace').lower().replace('-', '') not in ('utf8',):
+        try:
+            text = raw.decode(m.group(1).decode('ascii'), 'replace')
+        except LookupError:
+            pass
+    tb = TreeBuilder()
+    try:
+        tb.feed(text)
+        tb.close()
+    except Exception as e:  # noqa: BLE001 — a page that will not parse is still a page to list
+        return {'error': f'parse failed: {e}'}
+    stem = os.path.splitext(os.path.basename(out_abs))[0]
+    images_dir_rel = f'{stem}_images'
+    r = Renderer(os.path.dirname(src_abs), images_dir_rel, images_dir_abs, project)
+    r.block(tb.root)
+    body = '\n\n'.join(r.blocks)
+    body_lines = body.split('\n')
+    words = len(re.findall(r'\S+', body))
+    headings = heading_lines(body_lines)
+    title = re.sub(r'\s+', ' ', tb.title).strip()
+    # header: fixed lines + one per section; line numbers are 1-based positions in the final file
+    fixed = [
+        f'<!-- html-to-md: raw={len(raw)} words={words} images={r.image_count} inline={r.inline_written} sections={len(headings)} -->',
+        f'**Source:** `{src_rel_project}`' + (f' — *{title}*' if title else ''),
+        f'**Raw size:** {len(raw) / 1024:.1f} KB · **Words:** {words} · **Images:** {r.image_count}'
+        + (f' ({r.inline_written} inline, written to `{images_dir_rel}/`)' if r.inline_written else '')
+        + (f' · **Chrome regions dropped:** {r.dropped}' if r.dropped else ''),
+        '',
+        f'**Sections ({len(headings)})** — the denominator: a read covers all of them, by line number:',
+    ]
+    n_header = len(fixed) + max(len(headings), 1) + 2   # + section lines + blank + separator
+    section_lines = []
+    for i, l in headings:
+        m = re.match(r'^(#{1,6}) (.*)$', l)
+        section_lines.append(f'- L{n_header + 1 + i}: {"  " * (len(m.group(1)) - 1)}{m.group(2)}')
+    if not headings:
+        section_lines.append('- (no headings — the page is one section)')
+    header = fixed + section_lines + ['', '---']
+    assert len(header) == n_header
+    content = '\n'.join(header) + '\n' + body + '\n'
+    os.makedirs(os.path.dirname(out_abs), exist_ok=True)
+    with open(out_abs, 'w', encoding='utf-8') as f:
+        f.write(content)
+    return {'raw': len(raw), 'words': words, 'images': r.image_count, 'inline': r.inline_written,
+            'sections': len(headings), 'md_bytes': len(content.encode('utf-8')), 'title': title}
+
+
+def read_back(md_abs):
+    """Stats of an already-converted page, from its own machine-readable first line."""
+    try:
+        with open(md_abs, encoding='utf-8') as f:
+            first = f.readline()
+        m = re.search(r'<!-- html-to-md: raw=(\d+) words=(\d+) images=(\d+) inline=(\d+) sections=(\d+) -->', first)
+        if not m:
+            return None
+        return {'raw': int(m.group(1)), 'words': int(m.group(2)), 'images': int(m.group(3)),
+                'inline': int(m.group(4)), 'sections': int(m.group(5)),
+                'md_bytes': os.path.getsize(md_abs), 'title': ''}
+    except OSError:
+        return None
+
+
+def heading_lines(lines):
+    """(index, line) of every Markdown heading, ignoring lines inside ``` fences."""
+    out, fence = [], False
+    for i, l in enumerate(lines):
+        if l.startswith('```'):
+            fence = not fence
+            continue
+        if not fence and re.match(r'^#{1,6} ', l):
+            out.append((i, l))
+    return out
+
+
+def md_stats(path):
+    try:
+        with open(path, encoding='utf-8', errors='replace') as f:
+            t = f.read()
+    except OSError:
+        return 0, 0, 0
+    words = len(re.findall(r'\S+', t))
+    sections = len(heading_lines(t.split('\n')))
+    images = len(re.findall(r'!\[[^\]]*\]\(', t))
+    return words, sections, images
+
+
+IMG_SRC_RE = re.compile(r'<img\b[^>]*?\bsrc\s*=\s*["\']([^"\']+)["\']', re.I | re.S)
+
+
+def img_refs(html_path):
+    """Non-data <img src> values of a page, for sidecar ownership — regex on purpose: it runs
+    on skipped (already converted) pages too, so the index reads the same on every run."""
+    try:
+        with open(html_path, 'rb') as f:
+            t = f.read().decode('utf-8', 'replace')
+    except OSError:
+        return []
+    return [m for m in IMG_SRC_RE.findall(t) if not m.strip().lower().startswith('data:')]
+
+
+# --- the run -----------------------------------------------------------------------------------
+
+def main(argv):
+    if len(argv) < 4:
+        print(__doc__, file=sys.stderr)
+        return 2
+    project = os.path.abspath(argv[1])
+    src_root = os.path.abspath(argv[2])
+    out_root = os.path.abspath(argv[3])
+    force = '--force' in argv[4:]
+    if not os.path.isdir(src_root):
+        print(f'html-to-md: source root is not a directory: {src_root}', file=sys.stderr)
+        return 2
+    files = _inv.enumerate_root(src_root)
+    if not files:
+        print(f'html-to-md: no files under {src_root} — nothing to convert', file=sys.stderr)
+        return 3
+
+    def rel_project(p):
+        return os.path.relpath(p, project).replace(os.sep, '/')
+
+    # sidecar ownership: X_files/ belongs to X.html in the same directory (saved-webpage
+    # convention); an image a page references by src belongs to that page too.
+    pages = {}   # rel (under src root) -> stats
+    owner_of = {}  # rel -> page rel
+    page_rels = [e['rel'] for e in files if (e['ext'] or '') in PAGE_EXTS]
+    for prel in page_rels:
+        stem = os.path.splitext(prel)[0]
+        for cand in (stem + '_files/', stem + '_bestanden/', stem + '_fichiers/', stem + '_Dateien/', stem + '.files/'):
+            for e in files:
+                if e['rel'].startswith(cand):
+                    owner_of.setdefault(e['rel'], prel)
+
+    print(f'html-to-md: {len(files)} file(s) under {rel_project(src_root)}/, {len(page_rels)} page(s) → {rel_project(out_root)}/')
+    print('')
+    print(f'  {"page":<48} {"raw KB":>8} {"md words":>9} {"ratio":>7}  note')
+    tot_raw = tot_md = tot_words = tot_img = tot_inline = 0
+    converted = skipped = 0
+    for e in files:
+        if (e['ext'] or '') not in PAGE_EXTS:
+            continue
+        rel = e['rel']
+        out_abs = os.path.join(out_root, os.path.splitext(rel)[0] + '.md')
+        images_dir_abs = os.path.join(out_root, os.path.splitext(rel)[0] + '_images')
+        note = 'converted'
+        st = None
+        if not force and os.path.exists(out_abs) and os.path.getmtime(out_abs) >= os.path.getmtime(e['path']):
+            st = read_back(out_abs)
+            if st is not None:
+                note = 'up to date, skipped'
+                skipped += 1
+        if st is None:
+            st = convert_page(e['path'], rel_project(e['path']), out_abs, images_dir_abs, project)
+            if 'error' in st:
+                print(f'  {rel[:48]:<48} {(e.get("bytes") or 0) / 1024:>8.1f} {"-":>9} {"-":>7}  {st["error"]}')
+                pages[rel] = {'error': st['error']}
+                continue
+            converted += 1
+        # images the page references by relative src belong to it — on every run, so a skipped
+        # page owns the same sidecars as a converted one
+        base = os.path.dirname(rel)
+        for s in img_refs(e['path']):
+            s = re.sub(r'[?#].*$', '', s.strip())
+            if '://' in s or not s:
+                continue
+            target = os.path.normpath(os.path.join(base, s)).replace(os.sep, '/')
+            owner_of.setdefault(target, rel)
+        st['md'] = os.path.relpath(out_abs, project).replace(os.sep, '/')
+        pages[rel] = st
+        ratio = (st['raw'] / st['md_bytes']) if st['md_bytes'] else 0
+        print(f'  {rel[:48]:<48} {st["raw"] / 1024:>8.1f} {st["words"]:>9} {ratio:>6.1f}×  {note}'
+              + (f', {st["inline"]} inline image(s) written' if st.get('inline') else ''))
+        tot_raw += st['raw']; tot_md += st['md_bytes']; tot_words += st['words']
+        tot_img += st['images']; tot_inline += st.get('inline', 0)
+
+    # --- the index: EVERY file -------------------------------------------------------------
+    rows = []
+    n_md = n_img = n_chrome = n_other = 0
+    md_words_total = 0
+    img_to_read = 0
+    for e in files:
+        rel = e['rel']; ext = (e['ext'] or '').lower()
+        owner = owner_of.get(rel)
+        if ext in PAGE_EXTS:
+            st = pages.get(rel) or {}
+            if 'error' in st:
+                rows.append((rel, 'page (NOT converted: ' + st['error'] + ')', '—', '—', '—', '—'))
+            else:
+                rows.append((rel, 'page', f'`{st["md"]}`', str(st['sections']), str(st['images']), str(st['words'])))
+                img_to_read += st['images']
+        elif ext in MD_EXTS:
+            w, s, i = md_stats(e['path'])
+            n_md += 1; md_words_total += w; img_to_read += i
+            rows.append((rel, 'markdown', '— (read as is)', str(s), str(i), str(w)))
+        elif ext in IMG_EXTS:
+            n_img += 1
+            role = f'image of {owner}' if owner else 'image (standalone)'
+            if not owner:
+                img_to_read += 1
+            rows.append((rel, role, '—', '—', '—', '—'))
+        elif ext in CHROME_EXTS:
+            n_chrome += 1
+            role = f'chrome of {owner}' if owner else 'chrome (no owning page)'
+            rows.append((rel, role, '—', '—', '—', '—'))
+        else:
+            n_other += 1
+            rows.append((rel, f'other ({e.get("format") or "unknown"})' + (f' in {owner}_files' if owner else ''), '—', '—', '—', '—'))
+    index_abs = os.path.join(os.path.dirname(out_root), 'documents-index.md')
+    os.makedirs(os.path.dirname(index_abs), exist_ok=True)
+    n_pages = len(page_rels)
+    with open(index_abs, 'w', encoding='utf-8') as f:
+        f.write('# Documents index — every file under the source root\n\n')
+        f.write(f'Written by `bin/html-to-md.sh` on {time.strftime("%Y-%m-%d")} over `{rel_project(src_root)}/` '
+                f'({len(files)} files). One row per file, sidecars included: this is the artifact a single '
+                f'ledger mark points at (`bin/source-ledger.sh mark <project> \'*\' --artifact '
+                f'{rel_project(index_abs)} ...`), so it names every file.\n\n')
+        f.write(f'**Totals:** {n_pages} page(s) → {tot_words} words of Markdown (raw {tot_raw / 1024:.1f} KB → '
+                f'{tot_md / 1024:.1f} KB, {(tot_raw / tot_md) if tot_md else 0:.1f}×) · {n_md} markdown file(s), '
+                f'{md_words_total} words · {n_img} image file(s) · {n_chrome} chrome file(s) (css/js/fonts) · '
+                f'{n_other} other.\n\n')
+        f.write(f'**Images to read (vision) before Stage 2 closes: {img_to_read}** — every image a page or '
+                f'markdown file references ({tot_img} from pages, of which {tot_inline} inline and now written to '
+                f'`*_images/`) plus every standalone image file. The count is the denominator.\n\n')
+        f.write('| path | role | converted-to | sections | images | words |\n|---|---|---|---|---|---|\n')
+        for r in rows:
+            f.write('| ' + ' | '.join(x.replace('|', '\\|') for x in r) + ' |\n')
+    print('')
+    print(f'  {"TOTAL":<48} {tot_raw / 1024:>8.1f} {tot_words:>9} {(tot_raw / tot_md) if tot_md else 0:>6.1f}×  '
+          f'{converted} converted, {skipped} skipped (up to date), {tot_img} image(s) ({tot_inline} inline written)')
+    print(f'  index: {rel_project(index_abs)} — {len(rows)} row(s): {n_pages} page, {n_md} markdown, {n_img} image, '
+          f'{n_chrome} chrome, {n_other} other · images to read (vision): {img_to_read}')
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main(sys.argv))
diff --git a/bin/lib/skill-routing.sh b/bin/lib/skill-routing.sh
index 065c3e9..fe2b750 100644
--- a/bin/lib/skill-routing.sh
+++ b/bin/lib/skill-routing.sh
@@ -215,6 +215,17 @@ routing_render() {
   esac
 }
 
+# routing_row <name> [path-prefix] — ONE baseline-view row for a named table entry, path
+# prefixed as given. Used by sync-project.sh to rewrite a single stale row inside a table it
+# must not regenerate wholesale (a hand-written, unmarked one). Empty output = no such name.
+routing_row() {
+  local want="$1" prefix="${2:-}"
+  routing_rows | while IFS=$'\t' read -r name path when agents stages tier group; do
+    [ "$name" = "$want" ] || continue
+    printf '| %s | `%s%s` |\n' "$(_routing_md_escape "$when")" "$prefix" "$path"
+  done
+}
+
 # ── The project-side surface: <project>/CLAUDE.local.md ────────────────────────────────────
 #
 # This is the copy no script could reach. It lives inside each project, it is the ONLY routing
diff --git a/bin/lib/skill-routing.tsv b/bin/lib/skill-routing.tsv
index 791d0ef..0d53cc5 100644
--- a/bin/lib/skill-routing.tsv
+++ b/bin/lib/skill-routing.tsv
@@ -77,6 +77,7 @@ agent-roles	skills/agent-roles.md	Setting up or completing a project's dev-proce
 source-triage	skills/source-triage.md	Deciding whether to extract at all, before any BRD gets generated	ba	0	baseline	source
 source-sufficiency	bin/source-sufficiency.sh	Taking in a new source — before generating anything from it. Grades what the source can support; nothing else in this toolkit reads a source	ba	0,1	baseline	source
 source-ledger	bin/source-ledger.sh	Closing Stage 1, or adding files to a source folder — every inventoried file must name the artifact that consumed it (text AND embedded diagrams), or carry a waiver; blocks Stages 1–2 until it does	ba	0,1,2	baseline	source
+html-to-md	bin/html-to-md.sh	HTML in the source corpus — convert once before anyone reads it: `bin/html-to-md.sh <project>` writes each page as Markdown under analysis/knowledge-base/text/ (3–10× fewer tokens than the raw export; inline images decoded to files; section list with line numbers as the read's denominator) plus documents-index.md over EVERY file, which one ledger glob mark points at. A session that opens a .html itself has skipped this	ba	0,1	baseline	source
 triage-report	bin/triage-report.sh	Rendering a filled triage.md for review — the triage.html surface Stage 0 names. Renders only; the Stage 0 verdict stays with gate-check and the judgement with source-triage.md	ba	0	ondemand	source
 extraction-report	bin/extraction-report.sh	Reviewing what the extraction actually produced — the Stage 1 surface, and the file the Stage 1 gate looks for. Renders a code-extracted and a document knowledge base alike, so a requirements-driven project gets the surface too; prints no zero that a second record does not agree with	ba	1	ondemand	source
 question-kinds	bin/question-kinds.sh	Deciding who answers a question — before putting any batch to the user. gap/conflict/choice/user-only is what keeps a gate batch at four questions instead of 127	ba	1,2,3	baseline	spine
diff --git a/bin/lib/source-formats.tsv b/bin/lib/source-formats.tsv
index 15d9504..5b4f1a6 100644
--- a/bin/lib/source-formats.tsv
+++ b/bin/lib/source-formats.tsv
@@ -23,7 +23,7 @@
 # Format: TAB-separated, five columns. Blank lines and #-comments ignored. Extensions are
 # lowercase without the dot; several per row, |-separated.
 #   1 ext       extension(s)
-#   2 kind      docs | code | data | ui | contract | schema | media | archive | mail | diagram
+#   2 kind      docs | code | data | ui | contract | schema | media | archive | mail | diagram | chrome
 #               — the same vocabulary the inventory's `kind` field takes (plus schema/media/
 #               archive/mail/diagram, which the rubric readme lists as sub-kinds of the first six)
 #   3 route     the extraction route that consumes it whole
@@ -44,6 +44,7 @@ csv|tsv	data	rows; header row is the schema	no	One file, one table. Encoding and
 pdf	docs	text per page (skills/pdf) PLUS OCR when the text layer is empty PLUS embedded images	yes	A scanned PDF has no text layer; a text-only extraction returns nothing and reads as "empty document".
 md|txt|adoc|rst	docs	read whole	no
 html|htm|xhtml	docs	text + tables + form fields (screens exported as HTML are UI evidence, not prose)	no	An HTML export of a legacy screen is `ui`, not `docs` — reclassify by content.
+css|map|woff|woff2|ttf|otf|eot|ico	chrome	web export chrome — listed, never content; the page it belongs to carries the disposition (bin/html-to-md.sh's documents-index.md names each one as `chrome of <page>`)	no	A browser's "save page as (complete)" writes the page's stylesheets, scripts, fonts and favicon into `<page>_files/`. They are the page's furniture: one row each so nothing is silently absent, but a disposition is never owed for them separately — the index that lists them is what the ledger mark points at. NOTE: .js is deliberately NOT here — it stays on the code route below (one extension, one route, and a .js in a migration corpus is application source for pipelines/node-express-react); a saved page's sidecar .js is still named `chrome of <page>` by the index, which is the disposition that counts.
 xml|xsd|wsdl	contract	parse; schema and element names are structure	no	A .xml can be anything (OutSystems export, config, data). Reclassify by content.
 json|yaml|yml|toml	contract	parse; an OpenAPI/GraphQL contract grades as structure	no
 sql|ddl	schema	tables, columns, keys, constraints → domain model input	no	Frequently the best-specified thing in the corpus.
diff --git a/bin/source-ledger.sh b/bin/source-ledger.sh
index 9532244..0c629ce 100755
--- a/bin/source-ledger.sh
+++ b/bin/source-ledger.sh
@@ -180,6 +180,13 @@ inv = doc.get('inventory')
 if inv is None:
     print("source-ledger: this rubric predates the inventory pass; delete it and re-init", file=sys.stderr); sys.exit(4)
 t = os.environ['T'].replace(os.sep, '/')
+# Inventory rels are relative to the SOURCE ROOT, so a target spelled from the project root
+# ('sources/**', 'source/legacy/*.cls') is stripped of that one leading segment. Found on the
+# docs-ready path (2026-09-09): 'sources/**' — the natural spelling for "the whole corpus" —
+# matched no row and the mark was refused with the corpus listed right under the refusal.
+root_name = os.path.basename(os.path.normpath(doc.get('sourceRoot') or ''))
+if root_name and t.startswith(root_name + '/') and len(t) > len(root_name) + 1:
+    t = t[len(root_name) + 1:]
 is_glob = any(c in t for c in '*?[')
 rels = [r.get('rel') or os.path.basename(r.get('path') or '') for r in inv]
 hits = [r for r in rels if (fnmatch.fnmatch(r, t) if is_glob else (r == t or os.path.basename(r) == t))]
diff --git a/bin/sync-project.sh b/bin/sync-project.sh
index e0f9806..e5b8174 100755
--- a/bin/sync-project.sh
+++ b/bin/sync-project.sh
@@ -571,6 +571,17 @@ EOF
 fi
 # --- 2d. CLAUDE.local.md: rewrite the baseline routing block from the one routing table ----
 #
+# 2e below depends on knowing whether the file carried the retired ledger row BEFORE this
+# section rewrote the marked block, so the count is taken here.
+LEDGER_ROW_RE='bug-logs/mxcli-bugs\.md'
+# ledger_row_prefix <file> — the path prefix the retired row's cell carried ('' when relative).
+ledger_row_prefix() {
+  grep -m1 "^|.*$LEDGER_ROW_RE" "$1" | sed -n 's/.*[|` ]\([^|` ]*\)bug-logs\/mxcli-bugs\.md.*/\1/p'
+}
+LEDGER_ROWS_BEFORE=0
+[ -f "$CL" ] && LEDGER_ROWS_BEFORE="$(grep -c "^|.*$LEDGER_ROW_RE" "$CL" 2>/dev/null || true)"
+LEDGER_ROWS_BEFORE="${LEDGER_ROWS_BEFORE:-0}"
+#
 # This is the seventh copy — the one inside each project, which no script could update. The
 # previous code here could only WARN ("add them from README.md 'Baseline routing'"), and a
 # warning that costs a human a manual merge is a warning that gets ignored: measured across
@@ -615,6 +626,59 @@ if [ -f "$CL" ]; then
   fi
 fi
 
+# --- 2e. Retire the always-on ledger row: bug-logs/mxcli-bugs.md -> bin/bug-lookup.sh ----------
+#
+# WHY (2026-09-09, a Markdown+HTML requirements project). Master replaced the baseline routing
+# row for bug-logs/mxcli-bugs.md — 47,500 words, a third of everything a session read before
+# writing a line of MDL — with bin/bug-lookup.sh on 2026-09-08. A project scaffolded before
+# that still lists the ledger as always-on in CLAUDE.local.md, and a marked block gets that
+# fixed by 2d above. A project whose table is HAND-WRITTEN (no markers — every project
+# bootstrapped before 2026-08-18, and every one whose author trimmed the block by hand) gets
+# 2d's refusal instead, which is right for the table as a whole and wrong for this one row:
+# the row is not a project's local wiring, it is a 47k-word read per session that the toolkit
+# already retired. So the ONE row is rewritten in place wherever it sits, with the path prefix
+# the old row used (a hand-written table carries full toolkit paths; the generated one is
+# relative to the header's stated root), and the rest of the table is left byte-for-byte.
+#
+# CLAUDE.md is NOT edited. Its "mxcli-project-toolkit Integration" block is written by
+# skills/bootstrap-project.md — an LLM merge into the file `mxcli init` generates — and not by
+# bin/init-project.sh (which writes CLAUDE.local.md only; wire-agents.sh PRESERVES an existing
+# CLAUDE.md). A file no script produced is a file no script should rewrite (the report-only
+# rule at the top of this script); the row is reported with the exact replacement instead.
+if [ -f "$CL" ]; then
+  LEDGER_ROWS_NOW="$(grep -c "^|.*$LEDGER_ROW_RE" "$CL" 2>/dev/null || true)"; LEDGER_ROWS_NOW="${LEDGER_ROWS_NOW:-0}"
+  if [ "$LEDGER_ROWS_BEFORE" -gt 0 ] && [ "$LEDGER_ROWS_NOW" -eq 0 ]; then
+    # 2d's block rewrite already carried the new row in.
+    echo "${DRY:-}Retired: CLAUDE.local.md's always-on row for bug-logs/mxcli-bugs.md — retired the 47k-word ledger row → bin/bug-lookup.sh (rendered from the routing table)."
+  elif [ "$LEDGER_ROWS_NOW" -gt 0 ]; then
+    # The old row's path cell may carry a prefix (a hand-written table names the toolkit root
+    # on every path). Keep it, so the replacement resolves the way its neighbours do.
+    LEDGER_PREFIX="$(ledger_row_prefix "$CL")"
+    NEW_ROW="$(routing_row bug-lookup "$LEDGER_PREFIX")"
+    if [ -z "$NEW_ROW" ]; then
+      warn "bin/lib/skill-routing.tsv has no 'bug-lookup' row, so the retired ledger row in CLAUDE.local.md could not be rewritten."
+    elif [ "$DRY_RUN" -eq 1 ]; then
+      echo "${DRY:-}Retired: CLAUDE.local.md row(s) pointing at bug-logs/mxcli-bugs.md ($LEDGER_ROWS_NOW) — retired the 47k-word ledger row → bin/bug-lookup.sh"
+      CHANGES=$((CHANGES + 1))
+    else
+      _tmp="$(mktemp "${TMPDIR:-/tmp}/clrow.XXXXXX")"
+      # No backslashes in an awk -v value: gawk (the GitHub runner's awk) processes escapes in -v,
+      # so "^\\|" became "^|" — an alternation that matched EVERY line, and the whole file was
+      # replaced with copies of the row (CI-only failure, 2026-09-12). Bracket expressions instead.
+      awk -v re="^[|].*bug-logs/mxcli-bugs[.]md" -v repl="$NEW_ROW" '$0 ~ re { print repl; next } { print }' "$CL" > "$_tmp" \
+        && cat "$_tmp" > "$CL"; rm -f "$_tmp"
+      echo "Retired: CLAUDE.local.md row(s) pointing at bug-logs/mxcli-bugs.md ($LEDGER_ROWS_NOW) — retired the 47k-word ledger row → ${LEDGER_PREFIX}bin/bug-lookup.sh (the rest of the table untouched)."
+      CHANGES=$((CHANGES + 1))
+    fi
+  fi
+fi
+if [ -f "$PROJECT_DIR/CLAUDE.md" ] && grep -q "^|.*$LEDGER_ROW_RE" "$PROJECT_DIR/CLAUDE.md"; then
+  warn "CLAUDE.md still routes bug-logs/mxcli-bugs.md (47k words) as always-on. That block is" \
+       "bootstrap-project.md's (an LLM merge), not init-project.sh's, so sync does not edit" \
+       "CLAUDE.md — replace the row by hand with:" \
+       "  $(routing_row bug-lookup "$(ledger_row_prefix "$PROJECT_DIR/CLAUDE.md")")"
+fi
+
 # --- 3. Baseline routing / runbook-first wiring -----------------------------------------
 if [ ! -f "$PROJECT_DIR/CLAUDE.local.md" ] && { [ ! -f "$PROJECT_DIR/CLAUDE.md" ] || ! grep -q "conversion-runbook" "$PROJECT_DIR/CLAUDE.md"; }; then
   warn "No runbook-first wiring found (no CLAUDE.local.md, and CLAUDE.md doesn't reference" \
diff --git a/process/token-path-ab-2026-09-09.md b/process/token-path-ab-2026-09-09.md
new file mode 100644
index 0000000..d14998b
--- /dev/null
+++ b/process/token-path-ab-2026-09-09.md
@@ -0,0 +1,75 @@
+# Token-path A/B — 2026-09-09 to 09-12
+
+**Question.** A Markdown+HTML requirements project was slow and token-hungry through stages 1–4.
+Does converting HTML once, retiring the always-on bug-ledger row, stage-scoped runbook reads and a
+docs-ready fast path change cost and quality — and is the pipeline "overdoing" its artifacts?
+
+**Method.** Synthetic "Harbour Berth Booking" corpus generated from an answer key
+(`tests/ab/gen-corpus.py`, seed 20260909): 36 saved-webpage HTML exports with `_files/` sidecars,
+4 Markdown files; 48 requirements, 15 rules with thresholds, 3 planted contradictions, 2
+requirements present only inside screenshots. Scored by `tests/ab/score.py` (self-test: recall 1.0
+on a perfect BRD set, 0.5 on a half set). Arms ran as unattended cloud sessions from the same
+prompt; cost from the session record, timing from the run's own gate log. Corpus lives only on the
+throwaway `ab/arm-*` branches, never on master.
+
+## Wave 1 — Sonnet, stages P–2, one rep per arm
+
+| | A master | B branch, standard path | C branch, docs-ready |
+|---|---|---|---|
+| cost | $7.94 | $5.45 | $5.42 |
+| wall to Stage 2 | 19m04 | 12m46 | 12m04 |
+| requirement recall (48) | 54% | 81% | 94% |
+| rules with threshold (15) | 47% | 87% | 100% |
+| contradictions surfaced (3) | 0 | 1 | 3 |
+| screenshot-only found (2) | 1 | 2 | 2 |
+| source ledger (run's own report) | PASS, 41 extracted + 159 waived | PASS, 200 extracted | PASS, 200 extracted |
+| ASSUMED rulings | 17 | 14 | 8 |
+
+Arm B found and ran `bin/html-to-md.sh` unprompted (it is routed), so B vs C isolates only the
+waived Stage 1 + single glob mark + thin BRD. Recall matches in B/C are `section-cite` (a real
+reference back to the converted section); A's are loose overlap.
+
+## Wave 2 — Haiku, stages P–4, three corpora × two arms (+1 replication)
+
+| run | corpus | arm | cost | P→4 wall | gates | BRDs | artifact words |
+|---|---|---|---|---|---|---|---|
+| harbour-a | synthetic docs | master | $0.73 | 4.3m | 0–4 pass | 5 | 43,551 |
+| harbour-b | synthetic docs | branch | $0.96 | 5.6m | 1–4 pass (1 waived) | 8 | 58,290 |
+| toeic-a | single-file HTML app + guide | master | $0.67 | 5.4m | 0–4 pass | 3 | 30,148 |
+| toeic-b | same | branch | $0.90 | 7.8m | P–4 pass | 1 | 39,431 |
+| puffin-a | React/Express/SQL code | master | $0.64 | — | **none: hollow run** | 0 | — |
+| puffin-a2 | same (replication) | master | ~$0.7 | 8.2m | 0–4 pass | 4 | 12,327 |
+| puffin-b | same | branch | $1.03 | 5.2m | P–4 pass | ? | — |
+
+`puffin-a` wrote CONFIRMED decision rows for stages 2–4 with no artifacts behind them and
+`PROJECT.md`'s stage header still at "Stage P". The replication did not reproduce it: one-off agent
+failure, not a pipeline defect. Both runs left the stage header at "Stage P" (it is never
+advanced) — that is what made the hollow run look plausible; small fix, filed as follow-up.
+
+## Fixed reading load the runbook mandates (from `bin/lib/skill-routing.tsv`, master)
+
+Baseline tier: 23 docs, 75,147 words, every session. On-demand routed on top: P 11.7k · 0 23.0k ·
+1 17.3k · 2 8.4k · 3 23.1k · 4 18.4k · **5 134.2k** · 6 113.0k · 7 10.0k words. Stage 5's figure
+is half `mxcli-bugs.md` (48.6k) which `bin/bug-lookup.sh` already replaces.
+
+## Conclusions
+
+1. The analysis stages are not inherently expensive: a full P–4 pass is 4–8 minutes and under
+   $1.10 on Haiku for three different corpora. The slow day came from raw HTML in context, the
+   stale 47.5k-word ledger row still wired into older projects, and interview stops.
+2. `html-to-md.sh` is the single biggest win and is safe: 9× fewer agent-readable bytes, recall
+   54% → 81–94%, both screenshot-only requirements found, and the routing delivers it unprompted.
+3. The docs-ready fast path is strong on the one documents corpus (n=1, verbatim fixture): keep
+   it as the explicit opt-in mode the runbook now describes, not the default, until a real corpus
+   confirms it. Note its thin BRD carries no `microflows[]`; Stage 4 on `harbour-b` still produced
+   a build plan, so the work moves rather than disappears.
+4. No correctness change to the pipeline is warranted.
+5. The real "overdoing" is proportionality, not volume: a 3-file corpus produced 30k words of
+   stage artifacts, a 200-file corpus 44–58k. The artifact set is a fixed cost per project. A
+   small-project tier naming which artifacts may be waived is the follow-up worth writing.
+
+**Caveats.** n=1 per cell; the fixture restates every requirement verbatim, so recall partly
+measures copying; precision is not meaningful (a BRD legitimately says more than the key);
+unattended runs skip the interview cost; Stages 5–6 unmeasured. Spend: $118 on a first fan-out
+that hit the rate limit before any run finished (nine Fable sessions — pilot one rep first), $19
+wave 1, $5.60 wave 2 + replication.
diff --git a/skills/conversion-runbook.md b/skills/conversion-runbook.md
index 7666fe2..c51f5d9 100644
--- a/skills/conversion-runbook.md
+++ b/skills/conversion-runbook.md
@@ -27,6 +27,7 @@ table; a skill missing here is a skill no agent will find.
 | Deciding whether to extract at all, before any BRD gets generated | `skills/source-triage.md` |
 | Taking in a new source — before generating anything from it. Grades what the source can support; nothing else in this toolkit reads a source | `bin/source-sufficiency.sh` |
 | Closing Stage 1, or adding files to a source folder — every inventoried file must name the artifact that consumed it (text AND embedded diagrams), or carry a waiver; blocks Stages 1–2 until it does | `bin/source-ledger.sh` |
+| HTML in the source corpus — convert once before anyone reads it: `bin/html-to-md.sh <project>` writes each page as Markdown under analysis/knowledge-base/text/ (3–10× fewer tokens than the raw export; inline images decoded to files; section list with line numbers as the read's denominator) plus documents-index.md over EVERY file, which one ledger glob mark points at. A session that opens a .html itself has skipped this | `bin/html-to-md.sh` |
 | Deciding who answers a question — before putting any batch to the user. gap/conflict/choice/user-only is what keeps a gate batch at four questions instead of 127 | `bin/question-kinds.sh` |
 | Writing BRDs, especially several in parallel — "build" before the fan-out, "check" before any BRD is called done | `bin/facts-lock.sh` |
 | Building any module — before the first script. The mdl-agent's single per-module input | `skills/module-brief.md` |
@@ -56,6 +57,8 @@ table; a skill missing here is a skill no agent will find.
 **Downstream:** every stage skill listed in §2 — this runbook sequences them, it does not replace their content.
 **Root pointer:** `CONVERSION-RUNBOOK.md` at the repo root is a thin pointer to this skill plus "how to start"; this file is the executable detail. `toolkit-guide.html` at the repo root is the same journey as a visual page, and doubles as the shared CSS shell/token source for every stage HTML surface.
 
+**How to read this file: not whole.** A session reads **§1b** (the Live Checklist Protocol — it applies to every stage) **plus its own stage's section under §2**, and nothing else until a question sends it elsewhere. `bin/gate-check.sh <project> <stage>` prints the exact spans at the top of its output — `Read for this gate: skills/conversion-runbook.md §"Stage N — …" (lines A–B) + §1b Live Checklist (lines C–D)` — derived from the headings on every run, so they are never stale. "Read the runbook first, every session" in a project's `CLAUDE.local.md` means *those* lines, not the ~11,700 words: the whole-file read was measured cause three of a requirements-driven project's slow Stages 1–4 (2026-09-09). The baseline table above is rendered here so this file is complete, not so it is re-read.
+
 **Do not open `toolkit-guide.html` because you read this line.** Opening is governed by the first-touch rule in the toolkit's `CLAUDE.md` — open only if `<project-root>/.claude/.guide-shown` is absent, then `touch` it. You are reading this file *every session*; an unconditional "open it at kickoff" here means a browser tab every session, which is exactly the bug this wording replaced.
 
 ---
@@ -115,7 +118,7 @@ The stages are the same for everyone; what differs is where you enter and which
 | You're starting from… | Mode | Stages that run | What changes |
 |---|---|---|---|
 | **Legacy source code** (± docs, ± SME) | **Migration** | P, 0–7 (all) | The default everything below describes. Path A (code extractors) always runs. |
-| **Requirements only** — BRDs, specs, workshop outputs, wireframes; no legacy code | **Requirements-driven** | P, 0–6 (skip 7) | Stage 0 runs. `document-discovery.md` runs over the whole corpus for the inventory, **and** the extraction call runs per extractable structure inside it — a schema, a table dump, a data export or entity tables in a spec each get one; `N/A` is earned on evidence, never on the mode label (`source-triage.md` owns that rule — see "Stage 0 runs in every entry mode" below). Stage 1 runs Path B (`kb-generation.md`) + Path C (SME) only; Path A is declared not-applicable, not "skipped". Stages 2–6 run unchanged — BRDs come from documents instead of extraction. Stage 7 only if legacy data exists somewhere to cut over. |
+| **Requirements only** — BRDs, specs, workshop outputs, wireframes; no legacy code | **Requirements-driven** | P, 0–6 (skip 7) | Stage 0 runs. `document-discovery.md` runs over the whole corpus for the inventory, **and** the extraction call runs per extractable structure inside it — a schema, a table dump, a data export or entity tables in a spec each get one; `N/A` is earned on evidence, never on the mode label (`source-triage.md` owns that rule — see "Stage 0 runs in every entry mode" below). Stage 1 runs Path B (`kb-generation.md`) + Path C (SME) only; Path A is declared not-applicable, not "skipped". Stages 2–6 run unchanged — BRDs come from documents instead of extraction. Stage 7 only if legacy data exists somewhere to cut over. **A text-native corpus — Markdown and HTML pages, no legacy code, no Office/PDF containers — takes the docs-ready fast path below.** |
 | **Just an idea / a running start on the model** | **Greenfield** | P (light), 0 (scope only), 5–6 | Stages 1–4 collapse to whatever plan the user already has. Stage 0 does **not** collapse: with no corpus there is nothing to grade, but the scope conversation is exactly as load-bearing as it is anywhere else, so Stage 0 reduces to CAC-1's brainstorm and its sign-off. If you find yourself inventing requirements mid-build, you're actually in requirements-driven mode — back up to Stage 2. |
 
 ### Stage 0 runs in every entry mode
@@ -150,6 +153,30 @@ and sign the file off. Do not delete `triage.md` to express "this doesn't apply"
 then reports *"triage.md not found"*, which reads as an unanswered gate rather than a settled one,
 and the difference between those two is the whole point of having a gate.
 
+### Requirements-driven, docs-ready corpus
+
+**Trigger:** the corpus is text-native — Markdown files and HTML pages (saved-webpage exports with
+their `_files/` sidecars), no legacy code, no Office/PDF containers. A corpus with `.pptx`/`.docx`/
+`.pdf` in it takes the ordinary requirements-driven row above, because those containers carry
+embedded images that owe their own accounting (`bin/lib/source-formats.tsv`, `media = yes`).
+
+**Why this path exists (2026-09-09).** A project of exactly this shape was slow and token-hungry
+through Stages 1–4, for measured reasons: every session read the raw HTML (3–10× the tokens of
+its text), and the ledger asked for one disposition per file — every sidecar `.png`, `.css` and
+`.js` included — for a corpus nothing extracts. Nothing below skips a gate; it names the shortest
+honest route through them, and every command here was run against the gates before it was written.
+
+| Stage | Docs-ready form |
+|---|---|
+| **0** | `bin/source-sufficiency.sh init <p>` (the inventory — every file, sidecars included, css/fonts as format `chrome`), the scope interview (**CAC-1**), and the `## Sign-off` in `triage.md`. The triage's extractor-call, capability-coverage and Path-A rows are written **`N/A (text-native corpus)`** — an answer, on the record, never a deleted row. |
+| **1** | Run **`bin/html-to-md.sh <p>`** once. The knowledge base **is** `analysis/knowledge-base/text/` (one `.md` per page, header with the section list) plus **`analysis/knowledge-base/documents-index.md`** (one row per file). No extractor ran, so the Stage 1 gate — which wants `extraction-report.html`, the surface of an extraction — is waived *by name, with the reason*: `bin/gate-check.sh <p> --waive 1 --reason "text-native corpus: converted once with html-to-md, no extractor applies"`. **Not `--adopt 1`:** adoption waives the stages *before* the adoption point — Stage 0, which just ran — and leaves Stage 1 demanding the extraction report (verified 2026-09-09: `--adopt 1` → Stage 0 WAIVED, Stage 1 PENDING). **Ledger: ONE mark** — `bin/source-ledger.sh mark <p> 'sources/**' --artifact analysis/knowledge-base/documents-index.md --evidence "<the one finding that proves the corpus was read, e.g. 'R-list §3 → brd/F002'>" --by <who>` — the index names every basename, so every row reports EXTRACTED, the sidecar png/css/js rows included (an image row is not a container: it owes no `--media`). Then `bin/source-ledger.sh report <p>` for the surface. **The images the index lists still have to be read (vision) before Stage 2 closes** — its "Images to read" line is the denominator; the mark says the text was read, not the screenshots. The Stage 1 waiver means the ledger does not block *that* gate; **Stage 2 still runs it** (verified: hide the index → `gate-check <p> 2` exits 1, "Gate BLOCKED by the source ledger"). |
+| **2** | A thin BRD transform, not a re-analysis: **one use case per section** of the converted text, each with a `sourceRef` (`analysis/knowledge-base/text/<page>.md#L<line>` — the line from the header's section list), entities and rules **lifted as stated**, never inferred; `brd-validation.md` once, to Clean; `bin/brd-report.sh <p>`. Open questions are the ones the documents leave open, raised in chat per the Stage 2 gate. |
+| **3–4** | **Unchanged, and not skippable:** module boundaries, grants and the script order are decided here and nowhere else — a corpus that arrived as text has said nothing about any of them. |
+
+A session on this path reads §1b plus its stage's section — `bin/gate-check.sh <p> <stage>` prints the
+line ranges — and the converted `.md`, never the `.html`. A session that opens a `.html` itself has
+skipped Stage 1.
+
 **No pipeline at all — à-la-carte tool use.** An existing Mendix app that just needs an audit, lint pass, or a regression/e2e test net doesn't enter this pipeline: no intake, no stages, no gates. Route straight to `existing-app-assurance.md` (which points at `query-the-model.md`, `e2e-harness-base.md`, `learned-db-assertions.md`, and the bundled lint/graph/quality skills). The pipeline is for *producing* an app; the tool shelf is for everything else.
 
 ## When to Use This Skill
diff --git a/tests/ab/README.md b/tests/ab/README.md
new file mode 100644
index 0000000..aa8d9c1
--- /dev/null
+++ b/tests/ab/README.md
@@ -0,0 +1,128 @@
+# ab-fixture — Harbour Berth Booking
+
+The fixture side of a controlled A/B experiment on the mxcli-project-toolkit's Stage 0–2
+pipeline (intake → triage → source ledger → BRDs). One fictional application, one answer key,
+a deterministic corpus generator, and a scorer. **Everything is synthetic** — no real company,
+product, person or client data appears anywhere; the port authority does not exist.
+
+| File | What it is | Who sees it |
+|---|---|---|
+| `answer-key.json` | Ground truth: entities, associations, requirements, business rules, contradictions, screenshot-only rules, roles, screens, and the corpus plan (which page carries what, chrome pages, sidecar image counts) | **experimenter + scorer only** |
+| `gen-corpus.py` | Renders the key into a "webpage, complete" documentation export | experimenter |
+| `corpus/` | One generated corpus (default seed 20260909) — the thing the agents under test get, **minus `MANIFEST.json`** | agents under test (without the manifest) |
+| `corpus/MANIFEST.json` | What actually landed where: files, sizes, per-id placements, chrome list | **experimenter + scorer only** |
+| `score.py` | Scores a toolkit project after an agent ran Stages 0–2 on the corpus | experimenter |
+
+## The rules
+
+1. **Agents under test never see `answer-key.json` or `MANIFEST.json`.** Give them the corpus
+   directory generated with `--no-manifest`, or delete `MANIFEST.json` before handing it over.
+   Do not put the fixture directory itself anywhere a session under test can list.
+2. Both arms of the experiment run on the **same seed** — the generator is deterministic
+   (byte-identical output for the same key + seed; verified with md5 over every file).
+3. The scorer is mechanical. It fetches facts and prints them; it does not judge BRD quality
+   beyond what the key states. Read the matching table before believing a number.
+
+## Generate
+
+```bash
+python3 gen-corpus.py <out-dir> [--seed N] [--no-manifest] [--key answer-key.json]
+```
+
+Python 3 stdlib only. ~25 s. Produces ~13 MB:
+
+- 36 HTML pages `NN-title.html`, each with a `NN-title_files/` folder holding 3–12 PNG/JPG
+  images, `site.css` (+ sometimes `print.css`), `app.js`, and a `.woff` stub — the way a browser's
+  "Webpage, complete" export looks. Every page repeats the same header, cookie banner, sidebar
+  nav (all 36 pages) and footer. Markup is verbose: nested `div` wrappers, inline styles, class
+  soup.
+- 6 of the 36 are pure chrome (home, about, release notes, news, privacy, contact): no
+  requirements. The release notes contain changelog lines that *look* like requirements.
+- 8 pages carry a one-line minified block of 22–40 KB (a berth-occupancy "heatmap" of spans).
+  Two key statements (R044, B015) live **inside** such a line — line-based readers that truncate
+  long lines miss them.
+- 9 pages embed inline `data:image/png;base64` screenshots (58–67 KB each) of prototype screens.
+- Requirements are spread across prose, bullet lists, 2-column tables ("Requirement | …"), and
+  four are negatively phrased ("There is no automatic approval …").
+- 4 Markdown files: `glossary.md` (entity definitions), `roles.md`, `decisions-log.md` (ADR
+  style; carries R048 and B009), `workshop-notes.md` (carries R046, R047).
+- 3 contradictions on different pages (C001 auto-approval vs none; C002 cancellation 24 h vs
+  72 h; C003 who may waive a surcharge).
+- 2 requirements that exist **only inside an image** — S001 as a sidecar PNG on page 09
+  (`fig-booking-form-validation.png`: "IMO number must be exactly 7 digits"), S002 as an inline
+  base64 PNG on page 21 (`id="fig-review-decision"`: "Rejection reason is required when outcome
+  is Rejected"). The generator's self-test greps every text file to prove neither string leaks.
+  Text is drawn with a 5x7 bitmap font at 3x scale; verified legible by a vision model.
+
+Images are pure-Python: PNG via zlib, baseline JPEG via a ~60-line encoder with fixed-length
+Huffman tables (valid for every decoder, deliberately inefficient — the bulk is the point).
+
+## Run the experiment
+
+For each arm: scaffold a toolkit project (`bin/init-project.sh <project>`), copy the corpus into
+`<project>/sources/<anything>/` **without** `MANIFEST.json`, and let the agent run Stages 0–2
+per `skills/conversion-runbook.md`. Then score.
+
+## Score
+
+```bash
+python3 score.py <project-dir> --key answer-key.json [--json] \
+    [--toolkit ~/Mendix/mxcli-project-toolkit] [--manifest corpus/MANIFEST.json] \
+    [--brd-dir DIR] [--include-analysis] [--no-run]
+python3 score.py --self-test          # generates a corpus, scores fabricated perfect/half/paraphrased/empty projects
+```
+
+What it reads (toolkit conventions, not invented ones): BRDs via the three-path convention of
+`bin/lib/discover-brds.sh` (`analysis/*/knowledge-base/brd`, `analysis/knowledge-base/brd`,
+`knowledge-base/brd`); `PROJECT.md` (Decisions and Open questions tables, `## Current stage`,
+`Adopted at stage` / `Waived …` lines); `analysis/triage.md`; `analysis/sme-questions.md`;
+`docs/BUILD-LOG.md`; `.claude/` receipts; and, when the toolkit is reachable (`--toolkit`,
+`$MXTK_TOOLKIT`, the `Toolkit root` row in `CLAUDE.local.md`, or `~/Mendix/mxcli-project-toolkit`),
+it runs `bin/source-ledger.sh check --json` and `bin/gate-check.sh <project> 1` / `2`.
+
+| Metric | How it is computed |
+|---|---|
+| Requirement recall | key requirement counts as found when some BRD statement has stemmed-keyword overlap ≥ 0.6 of the key statement's tokens, or cites its id (`R012`), or cites its page file with overlap ≥ 0.5. Negation-aware: a key statement with no/not/never/cannot/only/without only matches a candidate that also carries a negation (or "manual"). |
+| Requirement precision | 1 − phantoms / claims. **Claims** are use-case titles, items of any `requirements` / `businessRules` / `rules` / `validations` / `hiddenRules` array, and microflow validations. Main-flow steps, purposes and descriptions are used for recall but are not claims. A claim is grounded when it overlaps ≥ 0.5 with any key requirement, rule or screenshot-only rule. |
+| Business-rule recall | as requirements, **and** every `must_contain` group of the rule (its threshold/state: "72", "overdue", "harbour master|harbourmaster") must appear in the same statement. The table's Note column says "statement found but threshold missing" when the rule was paraphrased without its number. |
+| Entity / attribute / association recall | BRD `domainEntities[].name` vs key entities (normalised; a BRD "Agent" matches "ShippingAgent"); attributes by normalised name with prefix/suffix tolerance ("IMO" matches "IMONumber"); associations as unordered entity pairs from `domainEntities[].associations[].target` or a top-level `associations[]`. |
+| Contradictions surfaced (0–3) | a row of PROJECT.md's tables, a BRD `openQuestions` entry, an `sme-questions.md` line, or an `analysis/**/*.md` line mentioning contradict/conflict/inconsistent, that either cites both requirement ids or contains a term from every `detect_terms` group of the contradiction. |
+| Screenshot-only found (0–2) | any BRD statement, register row or question carrying all `must_contain` groups with overlap ≥ 0.6. The ledger verdict on the sidecar screenshot image is reported next to it. |
+| Ledger | `counts` from `source-ledger.sh check --json` (EXTRACTED/WAIVED/PENDING/FAULT/drift) and the same verdicts bucketed by file kind (chrome pages, content pages, sidecar images, sidecar support files, markdown) — the key's `corpus.pages[].chrome` and `sidecar_images` tell the scorer which rows are which. With `--manifest`, row count vs manifest file count. |
+| Gates | the `Stage N (…): VERDICT` line of gate-check for stages 1 and 2, the register's current-stage line, waiver/adoption lines, BUILD-LOG stage lines, `.claude/` receipts. |
+
+`--json` prints every table as machine-readable numbers; the Markdown output includes the full
+per-id matching table (nearest BRD statement and where it lives), the phantom list, and the
+ledger-by-kind table.
+
+### Known biases of the scorer (read before comparing arms)
+
+- Fuzzy matching over-credits near-twins: in the self-test's half set the section-cite and
+  negation rules were tuned until the planted 24/48 scored exactly 0.5, but a BRD that
+  restates a rule verbatim next to a requirement on the same page can still earn a match for
+  both. Look at the `How` column (`overlap` / `id-cite` / `section-cite`).
+- Precision counts changelog lines and marketing copy an agent turns into "requirements" as
+  phantoms. That is intended (the chrome pages are noise), but an agent that lists *technical*
+  ADRs from `decisions-log.md` as requirements is penalised too.
+- Roles/screens are a cheap substring presence check over BRD actors and statements, not a
+  quality measure.
+- Gate verdicts depend on the toolkit version found; the scorer reports which root it used.
+
+## What the self-test proves
+
+`score.py --self-test` generates a corpus into a temp dir and asserts: size 8–20 MB, 36 pages
+with 6 chrome, no screenshot-only text in any text file, every key statement on its page, ≥ 6
+pages with a > 20 KB line; then fabricates a perfect BRD set from the key (recall 1.0 /
+precision 1.0 / rules 15/15 / entities + attributes + associations 1.0 / 3 contradictions / 2
+screenshot-only), a half set with three planted phantoms (recall ≈ 0.5, exactly 3 phantoms,
+0/3 and 0/2), a paraphrase set (reworded rules match; a rule without its threshold does not),
+and an empty project (recall 0, precision n/a). When the toolkit is reachable it also copies
+the corpus under `sources/`, runs `source-sufficiency.sh init` and checks the ledger inventoried
+every file as PENDING.
+
+## Regenerating the key's corpus plan
+
+The corpus plan (`corpus.pages[]`, `corpus.markdown[]`) lives in the key so the generator and
+the scorer cannot drift: every requirement/rule/screenshot id is placed exactly once, and each
+item's `section.file` must equal the page that carries it (the generator raises otherwise).
+Change the key, regenerate, re-run the self-test.
diff --git a/tests/ab/answer-key-small.json b/tests/ab/answer-key-small.json
new file mode 100644
index 0000000..014952e
--- /dev/null
+++ b/tests/ab/answer-key-small.json
@@ -0,0 +1,1704 @@
+{
+ "app": "Harbour Berth Booking",
+ "version": "1-small",
+ "description": "Synthetic ground truth for an A/B experiment on the mxcli-project-toolkit Stage 0-2 pipeline. A fictional port authority lets shipping agents book berths; berth officers approve; tariffs are invoiced; inspectors run checklists. Nothing here refers to a real organisation, product or person. [small variant: sidecar images trimmed to 1-2/page and inline screenshots to 2, so an unattended run finishes inside session limits; every requirement, rule, contradiction and screenshot-only item is unchanged from the full key.]",
+ "roles": [
+  {
+   "name": "ShippingAgent",
+   "label": "Shipping Agent",
+   "description": "Employee of a licensed shipping agency; creates and manages booking requests for the vessels the agency represents."
+  },
+  {
+   "name": "BerthOfficer",
+   "label": "Berth Officer",
+   "description": "Port authority officer who reviews booking requests, records decisions and grants departure clearance."
+  },
+  {
+   "name": "HarbourMaster",
+   "label": "Harbour Master",
+   "description": "Senior officer; everything a Berth Officer can do plus overrides, agent reactivation and tariff maintenance."
+  },
+  {
+   "name": "Inspector",
+   "label": "Inspector",
+   "description": "Schedules and performs inspections and records checklist outcomes."
+  }
+ ],
+ "screens": [
+  {
+   "name": "BookingBoard",
+   "label": "Booking Board",
+   "role": "BerthOfficer"
+  },
+  {
+   "name": "MyBookings",
+   "label": "My Bookings",
+   "role": "ShippingAgent"
+  },
+  {
+   "name": "InspectionCalendar",
+   "label": "Inspection Calendar",
+   "role": "Inspector"
+  }
+ ],
+ "entities": [
+  {
+   "name": "Vessel",
+   "attributes": [
+    {
+     "name": "IMONumber",
+     "type": "String(7)",
+     "required": true
+    },
+    {
+     "name": "Name",
+     "type": "String(100)",
+     "required": true
+    },
+    {
+     "name": "LengthOverall",
+     "type": "Decimal",
+     "required": true
+    },
+    {
+     "name": "Beam",
+     "type": "Decimal",
+     "required": false
+    },
+    {
+     "name": "Draught",
+     "type": "Decimal",
+     "required": true
+    },
+    {
+     "name": "FlagState",
+     "type": "String(2)",
+     "required": false
+    },
+    {
+     "name": "VesselType",
+     "type": "Enum(Container,Bulk,Tanker,RoRo,Cruise,GeneralCargo)",
+     "required": true
+    },
+    {
+     "name": "GrossTonnage",
+     "type": "Integer",
+     "required": false
+    }
+   ]
+  },
+  {
+   "name": "ShippingAgent",
+   "attributes": [
+    {
+     "name": "CompanyName",
+     "type": "String(120)",
+     "required": true
+    },
+    {
+     "name": "LicenceNumber",
+     "type": "String(20)",
+     "required": true
+    },
+    {
+     "name": "ContactEmail",
+     "type": "String(200)",
+     "required": true
+    },
+    {
+     "name": "Phone",
+     "type": "String(30)",
+     "required": false
+    },
+    {
+     "name": "IsSuspended",
+     "type": "Boolean",
+     "required": true
+    },
+    {
+     "name": "CreditLimit",
+     "type": "Decimal",
+     "required": false
+    }
+   ]
+  },
+  {
+   "name": "Terminal",
+   "attributes": [
+    {
+     "name": "Code",
+     "type": "String(6)",
+     "required": true
+    },
+    {
+     "name": "Name",
+     "type": "String(80)",
+     "required": true
+    },
+    {
+     "name": "OperatingHoursStart",
+     "type": "String(5)",
+     "required": false
+    },
+    {
+     "name": "OperatingHoursEnd",
+     "type": "String(5)",
+     "required": false
+    },
+    {
+     "name": "HasCustomsOffice",
+     "type": "Boolean",
+     "required": true
+    }
+   ]
+  },
+  {
+   "name": "Berth",
+   "attributes": [
+    {
+     "name": "Code",
+     "type": "String(10)",
+     "required": true
+    },
+    {
+     "name": "Name",
+     "type": "String(80)",
+     "required": true
+    },
+    {
+     "name": "MaxLength",
+     "type": "Decimal",
+     "required": true
+    },
+    {
+     "name": "MaxDraught",
+     "type": "Decimal",
+     "required": true
+    },
+    {
+     "name": "HasShorePower",
+     "type": "Boolean",
+     "required": true
+    },
+    {
+     "name": "Status",
+     "type": "Enum(Available,Closed,Maintenance)",
+     "required": true
+    },
+    {
+     "name": "Notes",
+     "type": "String(500)",
+     "required": false
+    }
+   ]
+  },
+  {
+   "name": "BookingRequest",
+   "attributes": [
+    {
+     "name": "Reference",
+     "type": "String(13)",
+     "required": true
+    },
+    {
+     "name": "ETA",
+     "type": "DateTime",
+     "required": true
+    },
+    {
+     "name": "ETD",
+     "type": "DateTime",
+     "required": true
+    },
+    {
+     "name": "Status",
+     "type": "Enum(Draft,Submitted,UnderReview,Approved,Rejected,Cancelled,Completed)",
+     "required": true
+    },
+    {
+     "name": "CargoClass",
+     "type": "Enum(General,Perishable,DangerousGoods,Empty)",
+     "required": true
+    },
+    {
+     "name": "ShorePowerRequested",
+     "type": "Boolean",
+     "required": true
+    },
+    {
+     "name": "SubmittedOn",
+     "type": "DateTime",
+     "required": false
+    },
+    {
+     "name": "Remarks",
+     "type": "String(500)",
+     "required": false
+    }
+   ]
+  },
+  {
+   "name": "ApprovalDecision",
+   "attributes": [
+    {
+     "name": "DecidedOn",
+     "type": "DateTime",
+     "required": true
+    },
+    {
+     "name": "Outcome",
+     "type": "Enum(Approved,Rejected,ReturnedForInformation)",
+     "required": true
+    },
+    {
+     "name": "Reason",
+     "type": "String(400)",
+     "required": false
+    },
+    {
+     "name": "OfficerName",
+     "type": "String(100)",
+     "required": true
+    },
+    {
+     "name": "IsOverride",
+     "type": "Boolean",
+     "required": true
+    }
+   ]
+  },
+  {
+   "name": "Tariff",
+   "attributes": [
+    {
+     "name": "Code",
+     "type": "String(10)",
+     "required": true
+    },
+    {
+     "name": "Description",
+     "type": "String(120)",
+     "required": true
+    },
+    {
+     "name": "RatePerMetrePerDay",
+     "type": "Decimal",
+     "required": true
+    },
+    {
+     "name": "Currency",
+     "type": "String(3)",
+     "required": true
+    },
+    {
+     "name": "ValidFrom",
+     "type": "Date",
+     "required": true
+    },
+    {
+     "name": "ValidTo",
+     "type": "Date",
+     "required": false
+    },
+    {
+     "name": "SurchargePercent",
+     "type": "Decimal",
+     "required": false
+    }
+   ]
+  },
+  {
+   "name": "Invoice",
+   "attributes": [
+    {
+     "name": "InvoiceNumber",
+     "type": "String(16)",
+     "required": true
+    },
+    {
+     "name": "IssuedOn",
+     "type": "Date",
+     "required": true
+    },
+    {
+     "name": "DueOn",
+     "type": "Date",
+     "required": true
+    },
+    {
+     "name": "TotalAmount",
+     "type": "Decimal",
+     "required": true
+    },
+    {
+     "name": "VatPercent",
+     "type": "Decimal",
+     "required": true
+    },
+    {
+     "name": "Status",
+     "type": "Enum(Draft,Issued,Paid,Overdue,Void)",
+     "required": true
+    }
+   ]
+  },
+  {
+   "name": "Inspection",
+   "attributes": [
+    {
+     "name": "ScheduledFor",
+     "type": "DateTime",
+     "required": true
+    },
+    {
+     "name": "CompletedOn",
+     "type": "DateTime",
+     "required": false
+    },
+    {
+     "name": "Outcome",
+     "type": "Enum(Pending,Passed,Failed,Deferred)",
+     "required": true
+    },
+    {
+     "name": "InspectorName",
+     "type": "String(100)",
+     "required": true
+    },
+    {
+     "name": "Findings",
+     "type": "String(1000)",
+     "required": false
+    },
+    {
+     "name": "FollowUpRequired",
+     "type": "Boolean",
+     "required": true
+    }
+   ]
+  },
+  {
+   "name": "InspectionItem",
+   "attributes": [
+    {
+     "name": "Category",
+     "type": "Enum(Safety,Environmental,Documentation,Security)",
+     "required": true
+    },
+    {
+     "name": "Description",
+     "type": "String(300)",
+     "required": true
+    },
+    {
+     "name": "IsCompliant",
+     "type": "Boolean",
+     "required": true
+    },
+    {
+     "name": "Severity",
+     "type": "Enum(Low,Medium,High)",
+     "required": false
+    },
+    {
+     "name": "Note",
+     "type": "String(300)",
+     "required": false
+    }
+   ]
+  },
+  {
+   "name": "AuditEntry",
+   "attributes": [
+    {
+     "name": "OccurredOn",
+     "type": "DateTime",
+     "required": true
+    },
+    {
+     "name": "Actor",
+     "type": "String(200)",
+     "required": true
+    },
+    {
+     "name": "Action",
+     "type": "String(100)",
+     "required": true
+    },
+    {
+     "name": "EntityName",
+     "type": "String(60)",
+     "required": true
+    },
+    {
+     "name": "Detail",
+     "type": "String(1000)",
+     "required": false
+    }
+   ]
+  }
+ ],
+ "associations": [
+  {
+   "name": "BookingRequest_Vessel",
+   "from": "BookingRequest",
+   "to": "Vessel",
+   "type": "ManyToOne"
+  },
+  {
+   "name": "BookingRequest_ShippingAgent",
+   "from": "BookingRequest",
+   "to": "ShippingAgent",
+   "type": "ManyToOne"
+  },
+  {
+   "name": "BookingRequest_Berth",
+   "from": "BookingRequest",
+   "to": "Berth",
+   "type": "ManyToOne"
+  },
+  {
+   "name": "ApprovalDecision_BookingRequest",
+   "from": "ApprovalDecision",
+   "to": "BookingRequest",
+   "type": "ManyToOne"
+  },
+  {
+   "name": "Invoice_BookingRequest",
+   "from": "Invoice",
+   "to": "BookingRequest",
+   "type": "OneToOne"
+  },
+  {
+   "name": "Invoice_Tariff",
+   "from": "Invoice",
+   "to": "Tariff",
+   "type": "ManyToOne"
+  },
+  {
+   "name": "Invoice_ShippingAgent",
+   "from": "Invoice",
+   "to": "ShippingAgent",
+   "type": "ManyToOne"
+  },
+  {
+   "name": "Inspection_BookingRequest",
+   "from": "Inspection",
+   "to": "BookingRequest",
+   "type": "ManyToOne"
+  },
+  {
+   "name": "InspectionItem_Inspection",
+   "from": "InspectionItem",
+   "to": "Inspection",
+   "type": "ManyToOne"
+  },
+  {
+   "name": "Berth_Terminal",
+   "from": "Berth",
+   "to": "Terminal",
+   "type": "ManyToOne"
+  },
+  {
+   "name": "Tariff_Terminal",
+   "from": "Tariff",
+   "to": "Terminal",
+   "type": "ManyToOne"
+  },
+  {
+   "name": "AuditEntry_BookingRequest",
+   "from": "AuditEntry",
+   "to": "BookingRequest",
+   "type": "ManyToOne"
+  },
+  {
+   "name": "Vessel_ShippingAgent",
+   "from": "Vessel",
+   "to": "ShippingAgent",
+   "type": "ManyToMany"
+  }
+ ],
+ "requirements": [
+  {
+   "id": "R001",
+   "text": "The system lets licensed shipping agents request berths online for vessels they represent.",
+   "section": {
+    "file": "04-vision-and-scope.html",
+    "heading": "1.1 Purpose"
+   },
+   "form": "prose"
+  },
+  {
+   "id": "R002",
+   "text": "Berth officers review every booking request and record an approval decision with a reason.",
+   "section": {
+    "file": "04-vision-and-scope.html",
+    "heading": "1.2 Goals"
+   },
+   "form": "bullet"
+  },
+  {
+   "id": "R003",
+   "text": "Pilotage and tug scheduling are out of scope and remain in the existing marine operations system.",
+   "section": {
+    "file": "04-vision-and-scope.html",
+    "heading": "1.3 Out of scope"
+   },
+   "form": "prose",
+   "negative": true
+  },
+  {
+   "id": "R004",
+   "text": "Four user roles exist: Shipping Agent, Berth Officer, Harbour Master and Inspector.",
+   "section": {
+    "file": "05-stakeholders-and-roles.html",
+    "heading": "2.1 Actors"
+   },
+   "form": "table"
+  },
+  {
+   "id": "R005",
+   "text": "The Harbour Master can perform every action a Berth Officer can, plus decision overrides, agent reactivation and tariff maintenance.",
+   "section": {
+    "file": "05-stakeholders-and-roles.html",
+    "heading": "2.3 Harbour Master"
+   },
+   "form": "prose"
+  },
+  {
+   "id": "R006",
+   "text": "A booking request always refers to exactly one vessel, one shipping agent and one berth.",
+   "section": {
+    "file": "07-domain-overview.html",
+    "heading": "3.1 Core concepts"
+   },
+   "form": "prose"
+  },
+  {
+   "id": "R007",
+   "text": "An agent can save a booking request as Draft and complete it later; drafts are invisible to officers.",
+   "section": {
+    "file": "08-booking-lifecycle.html",
+    "heading": "4.1 Draft"
+   },
+   "form": "prose"
+  },
+  {
+   "id": "R008",
+   "text": "On submission the system assigns a unique booking reference in the format HB-YYYY-NNNNN.",
+   "section": {
+    "file": "08-booking-lifecycle.html",
+    "heading": "4.2 Submission"
+   },
+   "form": "bullet"
+  },
+  {
+   "id": "R009",
+   "text": "A booking request moves through the states Draft, Submitted, Under Review, Approved, Rejected, Cancelled and Completed.",
+   "section": {
+    "file": "08-booking-lifecycle.html",
+    "heading": "4.3 Status model"
+   },
+   "form": "table"
+  },
+  {
+   "id": "R010",
+   "text": "A booking request is automatically approved when the requested berth is free for the whole stay and the vessel is shorter than 120 metres.",
+   "section": {
+    "file": "08-booking-lifecycle.html",
+    "heading": "4.4 Fast-track"
+   },
+   "form": "table"
+  },
+  {
+   "id": "R011",
+   "text": "The booking form requires vessel, berth, ETA, ETD and cargo class before it can be submitted.",
+   "section": {
+    "file": "09-booking-request-form.html",
+    "heading": "5.1 Mandatory fields"
+   },
+   "form": "bullet"
+  },
+  {
+   "id": "R012",
+   "text": "ETD must be later than ETA, and the system rejects a stay longer than 30 days.",
+   "section": {
+    "file": "09-booking-request-form.html",
+    "heading": "5.2 Validation"
+   },
+   "form": "prose"
+  },
+  {
+   "id": "R013",
+   "text": "An agent may edit a Submitted request until an officer opens it for review, after which it is locked.",
+   "section": {
+    "file": "10-cancellation-and-changes.html",
+    "heading": "6.1 Changing a request"
+   },
+   "form": "prose"
+  },
+  {
+   "id": "R014",
+   "text": "Cancellation is free of charge until 24 hours before ETA.",
+   "section": {
+    "file": "10-cancellation-and-changes.html",
+    "heading": "6.2 Cancellation"
+   },
+   "form": "bullet"
+  },
+  {
+   "id": "R015",
+   "text": "A shipping agent registers with a company name, port licence number and a contact e-mail address, and is activated by a Berth Officer.",
+   "section": {
+    "file": "11-agent-onboarding.html",
+    "heading": "7.1 Registration"
+   },
+   "form": "prose"
+  },
+  {
+   "id": "R016",
+   "text": "There is no self-service reactivation; a suspended agent is reactivated only by the Harbour Master.",
+   "section": {
+    "file": "11-agent-onboarding.html",
+    "heading": "7.2 Suspension"
+   },
+   "form": "prose",
+   "negative": true
+  },
+  {
+   "id": "R017",
+   "text": "Each berth records a code, a name, a maximum vessel length, a maximum draught, shore power availability and a status of Available, Closed or Maintenance.",
+   "section": {
+    "file": "12-berth-master-data.html",
+    "heading": "8.1 Berth attributes"
+   },
+   "form": "table"
+  },
+  {
+   "id": "R018",
+   "text": "Only the Harbour Master may waive a tariff surcharge.",
+   "section": {
+    "file": "13-berth-allocation-rules.html",
+    "heading": "9.3 Surcharge waivers"
+   },
+   "form": "prose"
+  },
+  {
+   "id": "R019",
+   "text": "A vessel is identified by its IMO number, which is unique across the vessel registry.",
+   "section": {
+    "file": "14-vessel-registry.html",
+    "heading": "10.1 Vessel record"
+   },
+   "form": "prose"
+  },
+  {
+   "id": "R020",
+   "text": "Vessel type is one of Container, Bulk, Tanker, RoRo, Cruise or General Cargo.",
+   "section": {
+    "file": "14-vessel-registry.html",
+    "heading": "10.2 Vessel types"
+   },
+   "form": "bullet"
+  },
+  {
+   "id": "R021",
+   "text": "Officers work from a Booking Board that lists Submitted and Under Review requests ordered by ETA.",
+   "section": {
+    "file": "15-officer-review-process.html",
+    "heading": "11.1 Queue"
+   },
+   "form": "prose"
+  },
+  {
+   "id": "R022",
+   "text": "Opening a request for review moves it to Under Review and records the reviewing officer.",
+   "section": {
+    "file": "15-officer-review-process.html",
+    "heading": "11.2 Review"
+   },
+   "form": "bullet"
+  },
+  {
+   "id": "R023",
+   "text": "An approval decision has one of three outcomes: Approved, Rejected or Returned for Information.",
+   "section": {
+    "file": "16-approval-decisions.html",
+    "heading": "12.1 Outcomes"
+   },
+   "form": "table"
+  },
+  {
+   "id": "R024",
+   "text": "A request Returned for Information goes back to the agent, who may amend and resubmit it once.",
+   "section": {
+    "file": "16-approval-decisions.html",
+    "heading": "12.2 Return for information"
+   },
+   "form": "prose"
+  },
+  {
+   "id": "R025",
+   "text": "There is no automatic approval; every booking request is reviewed by a berth officer before it can become Approved.",
+   "section": {
+    "file": "15-officer-review-process.html",
+    "heading": "11.4 Manual review only"
+   },
+   "form": "prose",
+   "negative": true
+  },
+  {
+   "id": "R026",
+   "text": "The agent receives an e-mail whenever the status of their booking request changes.",
+   "section": {
+    "file": "17-notifications.html",
+    "heading": "13.1 Agent notifications"
+   },
+   "form": "bullet"
+  },
+  {
+   "id": "R027",
+   "text": "Officers receive a daily digest at 06:00 listing requests with an ETA within the next 48 hours.",
+   "section": {
+    "file": "17-notifications.html",
+    "heading": "13.2 Officer digest"
+   },
+   "form": "prose"
+  },
+  {
+   "id": "R028",
+   "text": "Tariffs are defined per terminal with a rate per metre of vessel length per day, a currency and a validity period.",
+   "section": {
+    "file": "18-tariff-structure.html",
+    "heading": "14.1 Rate cards"
+   },
+   "form": "prose"
+  },
+  {
+   "id": "R029",
+   "text": "An invoice is generated automatically when a booking is marked Completed.",
+   "section": {
+    "file": "20-invoicing.html",
+    "heading": "16.1 Invoice creation"
+   },
+   "form": "prose"
+  },
+  {
+   "id": "R030",
+   "text": "A Harbour Master can mark an invoice as Paid or Void; a Paid invoice cannot be edited.",
+   "section": {
+    "file": "20-invoicing.html",
+    "heading": "16.3 Payment status"
+   },
+   "form": "bullet"
+  },
+  {
+   "id": "R031",
+   "text": "Cancellations made within 72 hours of ETA are charged 50% of the berth fee.",
+   "section": {
+    "file": "19-tariffs-cancellation-fees.html",
+    "heading": "15.2 Late cancellation"
+   },
+   "form": "table"
+  },
+  {
+   "id": "R032",
+   "text": "The review screen shows the vessel's dimensions next to the berth's limits and highlights any exceedance in red.",
+   "section": {
+    "file": "21-officer-review-screen.html",
+    "heading": "17.1 Review screen"
+   },
+   "form": "prose"
+  },
+  {
+   "id": "R033",
+   "text": "An inspector schedules an inspection against an Approved booking and the agent is notified of the time slot.",
+   "section": {
+    "file": "22-inspection-scheduling.html",
+    "heading": "18.1 Scheduling"
+   },
+   "form": "prose"
+  },
+  {
+   "id": "R034",
+   "text": "An inspection consists of checklist items in the categories Safety, Environmental, Documentation and Security.",
+   "section": {
+    "file": "23-inspection-checklist.html",
+    "heading": "19.1 Checklist"
+   },
+   "form": "table"
+  },
+  {
+   "id": "R035",
+   "text": "For each checklist item the inspector records compliant or not compliant, a severity of Low, Medium or High, and an optional note.",
+   "section": {
+    "file": "23-inspection-checklist.html",
+    "heading": "19.2 Recording"
+   },
+   "form": "bullet"
+  },
+  {
+   "id": "R036",
+   "text": "A berth officer may waive the late-arrival surcharge for vessels shorter than 80 metres.",
+   "section": {
+    "file": "24-inspection-outcomes.html",
+    "heading": "20.3 Surcharge relief"
+   },
+   "form": "prose"
+  },
+  {
+   "id": "R037",
+   "text": "Departure clearance is granted by a Berth Officer and requires every inspection on the booking to be Passed or Deferred.",
+   "section": {
+    "file": "25-departure-clearance.html",
+    "heading": "21.1 Clearance"
+   },
+   "form": "prose"
+  },
+  {
+   "id": "R038",
+   "text": "Every status change on a booking, decision, invoice or inspection is written to an audit trail with actor, timestamp and action.",
+   "section": {
+    "file": "26-audit-and-compliance.html",
+    "heading": "22.1 Audit trail"
+   },
+   "form": "prose"
+  },
+  {
+   "id": "R039",
+   "text": "The navigation offers three screens: Booking Board, My Bookings and Inspection Calendar.",
+   "section": {
+    "file": "28-navigation-and-screens.html",
+    "heading": "23.1 Screens"
+   },
+   "form": "table"
+  },
+  {
+   "id": "R040",
+   "text": "The Booking Board can be filtered by terminal, status and ETA date range.",
+   "section": {
+    "file": "29-booking-board-screen.html",
+    "heading": "24.1 Booking Board"
+   },
+   "form": "bullet"
+  },
+  {
+   "id": "R041",
+   "text": "My Bookings shows the agent's own requests only, with Draft requests listed first.",
+   "section": {
+    "file": "30-my-bookings-screen.html",
+    "heading": "25.1 My Bookings"
+   },
+   "form": "prose"
+  },
+  {
+   "id": "R042",
+   "text": "The Inspection Calendar shows inspections per day and per inspector and allows drag-and-drop rescheduling.",
+   "section": {
+    "file": "31-inspection-calendar-screen.html",
+    "heading": "26.1 Calendar"
+   },
+   "form": "prose"
+  },
+  {
+   "id": "R043",
+   "text": "A monthly berth occupancy report per terminal can be exported as CSV.",
+   "section": {
+    "file": "32-reporting.html",
+    "heading": "27.1 Reports"
+   },
+   "form": "bullet"
+  },
+  {
+   "id": "R044",
+   "text": "The system imports vessel positions from the AIS feed every 5 minutes and flags a booking as Arrived when the vessel enters the port geofence.",
+   "section": {
+    "file": "33-integration-ais-feed.html",
+    "heading": "28.2 AIS position feed"
+   },
+   "form": "minified"
+  },
+  {
+   "id": "R045",
+   "text": "Agents can only see bookings, invoices and inspections that belong to their own company.",
+   "section": {
+    "file": "35-security-and-access.html",
+    "heading": "29.1 Access"
+   },
+   "form": "prose"
+  },
+  {
+   "id": "R046",
+   "text": "Agents must be able to attach the cargo manifest as a PDF to a booking request.",
+   "section": {
+    "file": "workshop-notes.md",
+    "heading": "Session 2 \u2014 agents"
+   },
+   "form": "bullet"
+  },
+  {
+   "id": "R047",
+   "text": "The review screen must show the last five bookings of the same vessel.",
+   "section": {
+    "file": "workshop-notes.md",
+    "heading": "Session 3 \u2014 officers"
+   },
+   "form": "bullet"
+  },
+  {
+   "id": "R048",
+   "text": "Booking references are never reused, even after a request is cancelled or deleted.",
+   "section": {
+    "file": "decisions-log.md",
+    "heading": "ADR-004"
+   },
+   "form": "prose",
+   "negative": true
+  }
+ ],
+ "business_rules": [
+  {
+   "id": "B001",
+   "text": "A booking request cannot be submitted more than 90 days before the ETA.",
+   "must_contain": [
+    "90",
+    "day"
+   ],
+   "section": {
+    "file": "08-booking-lifecycle.html",
+    "heading": "4.5 Timing"
+   },
+   "form": "bullet"
+  },
+  {
+   "id": "B002",
+   "text": "A booking request must be submitted at least 48 hours before the ETA.",
+   "must_contain": [
+    "48",
+    "hour"
+   ],
+   "section": {
+    "file": "08-booking-lifecycle.html",
+    "heading": "4.5 Timing"
+   },
+   "form": "bullet"
+  },
+  {
+   "id": "B003",
+   "text": "A berth can be assigned only if the vessel's length does not exceed the berth's maximum length and the vessel's draught is at least 0.5 metres below the berth's maximum draught.",
+   "must_contain": [
+    "0.5",
+    "draught|draft"
+   ],
+   "section": {
+    "file": "13-berth-allocation-rules.html",
+    "heading": "9.1 Fit check"
+   },
+   "form": "prose"
+  },
+  {
+   "id": "B004",
+   "text": "An agent with three or more overdue invoices is automatically suspended.",
+   "must_contain": [
+    "three|3",
+    "overdue"
+   ],
+   "section": {
+    "file": "11-agent-onboarding.html",
+    "heading": "7.2 Suspension"
+   },
+   "form": "prose"
+  },
+  {
+   "id": "B005",
+   "text": "A suspended agent cannot submit booking requests; bookings that are already Approved remain valid.",
+   "must_contain": [
+    "suspend",
+    "approved"
+   ],
+   "section": {
+    "file": "11-agent-onboarding.html",
+    "heading": "7.2 Suspension"
+   },
+   "form": "prose"
+  },
+  {
+   "id": "B006",
+   "text": "Only the Harbour Master may override a Rejected decision, and the override is recorded with a reason.",
+   "must_contain": [
+    "harbour master|harbourmaster",
+    "reject"
+   ],
+   "section": {
+    "file": "16-approval-decisions.html",
+    "heading": "12.3 Overrides"
+   },
+   "form": "prose"
+  },
+  {
+   "id": "B007",
+   "text": "A booking with cargo class Dangerous Goods cannot be Approved until an inspection has been scheduled.",
+   "must_contain": [
+    "dangerous",
+    "inspection"
+   ],
+   "section": {
+    "file": "22-inspection-scheduling.html",
+    "heading": "18.2 Dangerous goods"
+   },
+   "form": "prose"
+  },
+  {
+   "id": "B008",
+   "text": "A vessel arriving more than 2 hours after its ETA incurs a late-arrival surcharge of 15% of the berth fee.",
+   "must_contain": [
+    "2 hour|two hour|2h",
+    "15"
+   ],
+   "section": {
+    "file": "19-tariffs-cancellation-fees.html",
+    "heading": "15.1 Late arrival"
+   },
+   "form": "table"
+  },
+  {
+   "id": "B009",
+   "text": "Invoices are due 30 days after the issue date and become Overdue on the day after the due date.",
+   "must_contain": [
+    "30",
+    "overdue"
+   ],
+   "section": {
+    "file": "decisions-log.md",
+    "heading": "ADR-006"
+   },
+   "form": "prose"
+  },
+  {
+   "id": "B010",
+   "text": "VAT of 21% is added to all berth fees.",
+   "must_contain": [
+    "21"
+   ],
+   "section": {
+    "file": "18-tariff-structure.html",
+    "heading": "14.3 VAT"
+   },
+   "form": "prose"
+  },
+  {
+   "id": "B011",
+   "text": "An Approved booking may be cancelled by the agent; a Completed booking cannot be cancelled.",
+   "must_contain": [
+    "approved",
+    "completed"
+   ],
+   "section": {
+    "file": "10-cancellation-and-changes.html",
+    "heading": "6.2 Cancellation"
+   },
+   "form": "bullet"
+  },
+  {
+   "id": "B012",
+   "text": "An inspection whose checklist contains any non-compliant item of High severity has the outcome Failed.",
+   "must_contain": [
+    "high",
+    "fail"
+   ],
+   "section": {
+    "file": "23-inspection-checklist.html",
+    "heading": "19.3 Outcome"
+   },
+   "form": "prose"
+  },
+  {
+   "id": "B013",
+   "text": "A Failed inspection blocks departure clearance until a follow-up inspection has Passed.",
+   "must_contain": [
+    "fail",
+    "follow"
+   ],
+   "section": {
+    "file": "24-inspection-outcomes.html",
+    "heading": "20.1 Consequences"
+   },
+   "form": "prose"
+  },
+  {
+   "id": "B014",
+   "text": "The berth fee is vessel length times days alongside times the tariff rate, with days alongside rounded up to whole days and a minimum of one day.",
+   "must_contain": [
+    "round",
+    "minimum|one day|1 day"
+   ],
+   "section": {
+    "file": "18-tariff-structure.html",
+    "heading": "14.2 Fee calculation"
+   },
+   "form": "table"
+  },
+  {
+   "id": "B015",
+   "text": "Shore power is billed at a flat 250 per day when the berth offers it and the agent requested it.",
+   "must_contain": [
+    "250"
+   ],
+   "section": {
+    "file": "18-tariff-structure.html",
+    "heading": "14.4 Shore power"
+   },
+   "form": "minified"
+  }
+ ],
+ "contradictions": [
+  {
+   "id": "C001",
+   "requirements": [
+    "R010",
+    "R025"
+   ],
+   "pages": [
+    "08-booking-lifecycle.html",
+    "15-officer-review-process.html"
+   ],
+   "summary": "Fast-track auto-approval under 120 m versus 'there is no automatic approval'.",
+   "detect_terms": [
+    [
+     "approv"
+    ],
+    [
+     "automatic",
+     "auto",
+     "fast-track",
+     "fast track"
+    ],
+    [
+     "no automatic",
+     "manual",
+     "every",
+     "all requests",
+     "every request",
+     "contradict",
+     "conflict",
+     "inconsisten",
+     "reviewed by"
+    ]
+   ]
+  },
+  {
+   "id": "C002",
+   "requirements": [
+    "R014",
+    "R031"
+   ],
+   "pages": [
+    "10-cancellation-and-changes.html",
+    "19-tariffs-cancellation-fees.html"
+   ],
+   "summary": "Free cancellation until 24 h before ETA versus 50% fee within 72 h of ETA.",
+   "detect_terms": [
+    [
+     "cancel"
+    ],
+    [
+     "24"
+    ],
+    [
+     "72"
+    ]
+   ]
+  },
+  {
+   "id": "C003",
+   "requirements": [
+    "R018",
+    "R036"
+   ],
+   "pages": [
+    "13-berth-allocation-rules.html",
+    "24-inspection-outcomes.html"
+   ],
+   "summary": "Only the Harbour Master may waive surcharges versus a Berth Officer may waive the late-arrival surcharge under 80 m.",
+   "detect_terms": [
+    [
+     "waiv"
+    ],
+    [
+     "surcharge"
+    ],
+    [
+     "harbour master",
+     "harbourmaster",
+     "berth officer",
+     "80",
+     "contradict",
+     "conflict",
+     "inconsisten"
+    ]
+   ]
+  }
+ ],
+ "screenshot_only": [
+  {
+   "id": "S001",
+   "text": "IMO number must be exactly 7 digits",
+   "must_contain": [
+    "7|seven",
+    "digit"
+   ],
+   "page": "09-booking-request-form.html",
+   "mode": "sidecar",
+   "image": "09-booking-request-form_files/fig-booking-form-validation.png",
+   "screen": "Booking request form"
+  },
+  {
+   "id": "S002",
+   "text": "Rejection reason is required when outcome is Rejected",
+   "must_contain": [
+    "reason",
+    "reject"
+   ],
+   "page": "21-officer-review-screen.html",
+   "mode": "inline",
+   "image": "(inline base64 <img> on 21-officer-review-screen.html, id=fig-review-decision)",
+   "screen": "Officer review screen"
+  }
+ ],
+ "corpus": {
+  "markdown": [
+   {
+    "file": "glossary.md",
+    "carries": [
+     "entities"
+    ]
+   },
+   {
+    "file": "roles.md",
+    "carries": [
+     "roles"
+    ]
+   },
+   {
+    "file": "decisions-log.md",
+    "carries": [
+     "R048",
+     "B009"
+    ]
+   },
+   {
+    "file": "workshop-notes.md",
+    "carries": [
+     "R046",
+     "R047"
+    ]
+   }
+  ],
+  "pages": [
+   {
+    "file": "01-home.html",
+    "title": "Home",
+    "chrome": true,
+    "sidecar_images": 1,
+    "inline_screenshots": 0
+   },
+   {
+    "file": "02-about-the-port-authority.html",
+    "title": "About the Port Authority",
+    "chrome": true,
+    "sidecar_images": 1,
+    "inline_screenshots": 0
+   },
+   {
+    "file": "03-release-notes.html",
+    "title": "Release notes",
+    "chrome": true,
+    "sidecar_images": 1,
+    "inline_screenshots": 0,
+    "minified": true
+   },
+   {
+    "file": "04-vision-and-scope.html",
+    "title": "Vision and scope",
+    "chrome": false,
+    "sidecar_images": 1,
+    "inline_screenshots": 0,
+    "carries": [
+     "R001",
+     "R002",
+     "R003"
+    ]
+   },
+   {
+    "file": "05-stakeholders-and-roles.html",
+    "title": "Stakeholders and roles",
+    "chrome": false,
+    "sidecar_images": 1,
+    "inline_screenshots": 0,
+    "carries": [
+     "R004",
+     "R005"
+    ]
+   },
+   {
+    "file": "06-news-and-events.html",
+    "title": "News and events",
+    "chrome": true,
+    "sidecar_images": 1,
+    "inline_screenshots": 0
+   },
+   {
+    "file": "07-domain-overview.html",
+    "title": "Domain overview",
+    "chrome": false,
+    "sidecar_images": 1,
+    "inline_screenshots": 0,
+    "carries": [
+     "R006"
+    ],
+    "entities": [
+     "Vessel",
+     "ShippingAgent",
+     "Berth",
+     "BookingRequest"
+    ]
+   },
+   {
+    "file": "08-booking-lifecycle.html",
+    "title": "Booking lifecycle",
+    "chrome": false,
+    "sidecar_images": 1,
+    "inline_screenshots": 1,
+    "carries": [
+     "R007",
+     "R008",
+     "R009",
+     "R010",
+     "B001",
+     "B002"
+    ]
+   },
+   {
+    "file": "09-booking-request-form.html",
+    "title": "Booking request form",
+    "chrome": false,
+    "sidecar_images": 2,
+    "inline_screenshots": 0,
+    "carries": [
+     "R011",
+     "R012",
+     "S001"
+    ]
+   },
+   {
+    "file": "10-cancellation-and-changes.html",
+    "title": "Cancellation and changes",
+    "chrome": false,
+    "sidecar_images": 1,
+    "inline_screenshots": 0,
+    "carries": [
+     "R013",
+     "R014",
+     "B011"
+    ]
+   },
+   {
+    "file": "11-agent-onboarding.html",
+    "title": "Agent onboarding",
+    "chrome": false,
+    "sidecar_images": 1,
+    "inline_screenshots": 0,
+    "carries": [
+     "R015",
+     "R016",
+     "B004",
+     "B005"
+    ],
+    "minified": true
+   },
+   {
+    "file": "12-berth-master-data.html",
+    "title": "Berth master data",
+    "chrome": false,
+    "sidecar_images": 1,
+    "inline_screenshots": 0,
+    "carries": [
+     "R017"
+    ],
+    "entities": [
+     "Berth",
+     "Terminal"
+    ]
+   },
+   {
+    "file": "13-berth-allocation-rules.html",
+    "title": "Berth allocation rules",
+    "chrome": false,
+    "sidecar_images": 1,
+    "inline_screenshots": 0,
+    "carries": [
+     "B003",
+     "R018"
+    ]
+   },
+   {
+    "file": "14-vessel-registry.html",
+    "title": "Vessel registry",
+    "chrome": false,
+    "sidecar_images": 1,
+    "inline_screenshots": 0,
+    "carries": [
+     "R019",
+     "R020"
+    ],
+    "entities": [
+     "Vessel"
+    ]
+   },
+   {
+    "file": "15-officer-review-process.html",
+    "title": "Officer review process",
+    "chrome": false,
+    "sidecar_images": 1,
+    "inline_screenshots": 0,
+    "carries": [
+     "R021",
+     "R022",
+     "R025"
+    ],
+    "minified": true
+   },
+   {
+    "file": "16-approval-decisions.html",
+    "title": "Approval decisions",
+    "chrome": false,
+    "sidecar_images": 1,
+    "inline_screenshots": 0,
+    "carries": [
+     "R023",
+     "R024",
+     "B006"
+    ]
+   },
+   {
+    "file": "17-notifications.html",
+    "title": "Notifications",
+    "chrome": false,
+    "sidecar_images": 1,
+    "inline_screenshots": 0,
+    "carries": [
+     "R026",
+     "R027"
+    ]
+   },
+   {
+    "file": "18-tariff-structure.html",
+    "title": "Tariff structure",
+    "chrome": false,
+    "sidecar_images": 1,
+    "inline_screenshots": 0,
+    "carries": [
+     "R028",
+     "B010",
+     "B014",
+     "B015"
+    ],
+    "minified": true
+   },
+   {
+    "file": "19-tariffs-cancellation-fees.html",
+    "title": "Tariffs: late arrival and cancellation fees",
+    "chrome": false,
+    "sidecar_images": 1,
+    "inline_screenshots": 0,
+    "carries": [
+     "R031",
+     "B008"
+    ]
+   },
+   {
+    "file": "20-invoicing.html",
+    "title": "Invoicing",
+    "chrome": false,
+    "sidecar_images": 1,
+    "inline_screenshots": 0,
+    "carries": [
+     "R029",
+     "R030"
+    ]
+   },
+   {
+    "file": "21-officer-review-screen.html",
+    "title": "Officer review screen",
+    "chrome": false,
+    "sidecar_images": 2,
+    "inline_screenshots": 1,
+    "carries": [
+     "R032",
+     "S002"
+    ]
+   },
+   {
+    "file": "22-inspection-scheduling.html",
+    "title": "Inspection scheduling",
+    "chrome": false,
+    "sidecar_images": 1,
+    "inline_screenshots": 0,
+    "carries": [
+     "R033",
+     "B007"
+    ]
+   },
+   {
+    "file": "23-inspection-checklist.html",
+    "title": "Inspection checklist",
+    "chrome": false,
+    "sidecar_images": 1,
+    "inline_screenshots": 0,
+    "carries": [
+     "R034",
+     "R035",
+     "B012"
+    ]
+   },
+   {
+    "file": "24-inspection-outcomes.html",
+    "title": "Inspection outcomes",
+    "chrome": false,
+    "sidecar_images": 1,
+    "inline_screenshots": 0,
+    "carries": [
+     "B013",
+     "R036"
+    ],
+    "minified": true
+   },
+   {
+    "file": "25-departure-clearance.html",
+    "title": "Departure clearance",
+    "chrome": false,
+    "sidecar_images": 1,
+    "inline_screenshots": 0,
+    "carries": [
+     "R037"
+    ]
+   },
+   {
+    "file": "26-audit-and-compliance.html",
+    "title": "Audit and compliance",
+    "chrome": false,
+    "sidecar_images": 1,
+    "inline_screenshots": 0,
+    "carries": [
+     "R038"
+    ],
+    "entities": [
+     "AuditEntry"
+    ]
+   },
+   {
+    "file": "27-privacy-and-cookies.html",
+    "title": "Privacy and cookies",
+    "chrome": true,
+    "sidecar_images": 1,
+    "inline_screenshots": 0,
+    "minified": true
+   },
+   {
+    "file": "28-navigation-and-screens.html",
+    "title": "Navigation and screens",
+    "chrome": false,
+    "sidecar_images": 1,
+    "inline_screenshots": 0,
+    "carries": [
+     "R039"
+    ]
+   },
+   {
+    "file": "29-booking-board-screen.html",
+    "title": "Booking Board screen",
+    "chrome": false,
+    "sidecar_images": 1,
+    "inline_screenshots": 0,
+    "carries": [
+     "R040"
+    ]
+   },
+   {
+    "file": "30-my-bookings-screen.html",
+    "title": "My Bookings screen",
+    "chrome": false,
+    "sidecar_images": 1,
+    "inline_screenshots": 0,
+    "carries": [
+     "R041"
+    ]
+   },
+   {
+    "file": "31-inspection-calendar-screen.html",
+    "title": "Inspection Calendar screen",
+    "chrome": false,
+    "sidecar_images": 1,
+    "inline_screenshots": 0,
+    "carries": [
+     "R042"
+    ]
+   },
+   {
+    "file": "32-reporting.html",
+    "title": "Reporting",
+    "chrome": false,
+    "sidecar_images": 1,
+    "inline_screenshots": 0,
+    "carries": [
+     "R043"
+    ]
+   },
+   {
+    "file": "33-integration-ais-feed.html",
+    "title": "Integration: AIS feed",
+    "chrome": false,
+    "sidecar_images": 1,
+    "inline_screenshots": 0,
+    "carries": [
+     "R044"
+    ],
+    "minified": true
+   },
+   {
+    "file": "34-contact-and-support.html",
+    "title": "Contact and support",
+    "chrome": true,
+    "sidecar_images": 1,
+    "inline_screenshots": 0
+   },
+   {
+    "file": "35-security-and-access.html",
+    "title": "Security and access",
+    "chrome": false,
+    "sidecar_images": 1,
+    "inline_screenshots": 0,
+    "carries": [
+     "R045"
+    ]
+   },
+   {
+    "file": "36-appendix-data-dictionary.html",
+    "title": "Appendix: data dictionary",
+    "chrome": false,
+    "sidecar_images": 1,
+    "inline_screenshots": 0,
+    "entities": [
+     "ApprovalDecision",
+     "Tariff",
+     "Invoice",
+     "Inspection",
+     "InspectionItem",
+     "AuditEntry"
+    ],
+    "minified": true
+   }
+  ]
+ },
+ "_detect_terms_note": "A question/decision text 'surfaces' a contradiction when it cites both requirement ids, or when it contains at least one term from EVERY group in detect_terms (case-insensitive substring)."
+}
\ No newline at end of file
diff --git a/tests/ab/answer-key.json b/tests/ab/answer-key.json
new file mode 100644
index 0000000..781c01d
--- /dev/null
+++ b/tests/ab/answer-key.json
@@ -0,0 +1,1704 @@
+{
+  "app": "Harbour Berth Booking",
+  "version": 1,
+  "description": "Synthetic ground truth for an A/B experiment on the mxcli-project-toolkit Stage 0-2 pipeline. A fictional port authority lets shipping agents book berths; berth officers approve; tariffs are invoiced; inspectors run checklists. Nothing here refers to a real organisation, product or person.",
+  "roles": [
+    {
+      "name": "ShippingAgent",
+      "label": "Shipping Agent",
+      "description": "Employee of a licensed shipping agency; creates and manages booking requests for the vessels the agency represents."
+    },
+    {
+      "name": "BerthOfficer",
+      "label": "Berth Officer",
+      "description": "Port authority officer who reviews booking requests, records decisions and grants departure clearance."
+    },
+    {
+      "name": "HarbourMaster",
+      "label": "Harbour Master",
+      "description": "Senior officer; everything a Berth Officer can do plus overrides, agent reactivation and tariff maintenance."
+    },
+    {
+      "name": "Inspector",
+      "label": "Inspector",
+      "description": "Schedules and performs inspections and records checklist outcomes."
+    }
+  ],
+  "screens": [
+    {
+      "name": "BookingBoard",
+      "label": "Booking Board",
+      "role": "BerthOfficer"
+    },
+    {
+      "name": "MyBookings",
+      "label": "My Bookings",
+      "role": "ShippingAgent"
+    },
+    {
+      "name": "InspectionCalendar",
+      "label": "Inspection Calendar",
+      "role": "Inspector"
+    }
+  ],
+  "entities": [
+    {
+      "name": "Vessel",
+      "attributes": [
+        {
+          "name": "IMONumber",
+          "type": "String(7)",
+          "required": true
+        },
+        {
+          "name": "Name",
+          "type": "String(100)",
+          "required": true
+        },
+        {
+          "name": "LengthOverall",
+          "type": "Decimal",
+          "required": true
+        },
+        {
+          "name": "Beam",
+          "type": "Decimal",
+          "required": false
+        },
+        {
+          "name": "Draught",
+          "type": "Decimal",
+          "required": true
+        },
+        {
+          "name": "FlagState",
+          "type": "String(2)",
+          "required": false
+        },
+        {
+          "name": "VesselType",
+          "type": "Enum(Container,Bulk,Tanker,RoRo,Cruise,GeneralCargo)",
+          "required": true
+        },
+        {
+          "name": "GrossTonnage",
+          "type": "Integer",
+          "required": false
+        }
+      ]
+    },
+    {
+      "name": "ShippingAgent",
+      "attributes": [
+        {
+          "name": "CompanyName",
+          "type": "String(120)",
+          "required": true
+        },
+        {
+          "name": "LicenceNumber",
+          "type": "String(20)",
+          "required": true
+        },
+        {
+          "name": "ContactEmail",
+          "type": "String(200)",
+          "required": true
+        },
+        {
+          "name": "Phone",
+          "type": "String(30)",
+          "required": false
+        },
+        {
+          "name": "IsSuspended",
+          "type": "Boolean",
+          "required": true
+        },
+        {
+          "name": "CreditLimit",
+          "type": "Decimal",
+          "required": false
+        }
+      ]
+    },
+    {
+      "name": "Terminal",
+      "attributes": [
+        {
+          "name": "Code",
+          "type": "String(6)",
+          "required": true
+        },
+        {
+          "name": "Name",
+          "type": "String(80)",
+          "required": true
+        },
+        {
+          "name": "OperatingHoursStart",
+          "type": "String(5)",
+          "required": false
+        },
+        {
+          "name": "OperatingHoursEnd",
+          "type": "String(5)",
+          "required": false
+        },
+        {
+          "name": "HasCustomsOffice",
+          "type": "Boolean",
+          "required": true
+        }
+      ]
+    },
+    {
+      "name": "Berth",
+      "attributes": [
+        {
+          "name": "Code",
+          "type": "String(10)",
+          "required": true
+        },
+        {
+          "name": "Name",
+          "type": "String(80)",
+          "required": true
+        },
+        {
+          "name": "MaxLength",
+          "type": "Decimal",
+          "required": true
+        },
+        {
+          "name": "MaxDraught",
+          "type": "Decimal",
+          "required": true
+        },
+        {
+          "name": "HasShorePower",
+          "type": "Boolean",
+          "required": true
+        },
+        {
+          "name": "Status",
+          "type": "Enum(Available,Closed,Maintenance)",
+          "required": true
+        },
+        {
+          "name": "Notes",
+          "type": "String(500)",
+          "required": false
+        }
+      ]
+    },
+    {
+      "name": "BookingRequest",
+      "attributes": [
+        {
+          "name": "Reference",
+          "type": "String(13)",
+          "required": true
+        },
+        {
+          "name": "ETA",
+          "type": "DateTime",
+          "required": true
+        },
+        {
+          "name": "ETD",
+          "type": "DateTime",
+          "required": true
+        },
+        {
+          "name": "Status",
+          "type": "Enum(Draft,Submitted,UnderReview,Approved,Rejected,Cancelled,Completed)",
+          "required": true
+        },
+        {
+          "name": "CargoClass",
+          "type": "Enum(General,Perishable,DangerousGoods,Empty)",
+          "required": true
+        },
+        {
+          "name": "ShorePowerRequested",
+          "type": "Boolean",
+          "required": true
+        },
+        {
+          "name": "SubmittedOn",
+          "type": "DateTime",
+          "required": false
+        },
+        {
+          "name": "Remarks",
+          "type": "String(500)",
+          "required": false
+        }
+      ]
+    },
+    {
+      "name": "ApprovalDecision",
+      "attributes": [
+        {
+          "name": "DecidedOn",
+          "type": "DateTime",
+          "required": true
+        },
+        {
+          "name": "Outcome",
+          "type": "Enum(Approved,Rejected,ReturnedForInformation)",
+          "required": true
+        },
+        {
+          "name": "Reason",
+          "type": "String(400)",
+          "required": false
+        },
+        {
+          "name": "OfficerName",
+          "type": "String(100)",
+          "required": true
+        },
+        {
+          "name": "IsOverride",
+          "type": "Boolean",
+          "required": true
+        }
+      ]
+    },
+    {
+      "name": "Tariff",
+      "attributes": [
+        {
+          "name": "Code",
+          "type": "String(10)",
+          "required": true
+        },
+        {
+          "name": "Description",
+          "type": "String(120)",
+          "required": true
+        },
+        {
+          "name": "RatePerMetrePerDay",
+          "type": "Decimal",
+          "required": true
+        },
+        {
+          "name": "Currency",
+          "type": "String(3)",
+          "required": true
+        },
+        {
+          "name": "ValidFrom",
+          "type": "Date",
+          "required": true
+        },
+        {
+          "name": "ValidTo",
+          "type": "Date",
+          "required": false
+        },
+        {
+          "name": "SurchargePercent",
+          "type": "Decimal",
+          "required": false
+        }
+      ]
+    },
+    {
+      "name": "Invoice",
+      "attributes": [
+        {
+          "name": "InvoiceNumber",
+          "type": "String(16)",
+          "required": true
+        },
+        {
+          "name": "IssuedOn",
+          "type": "Date",
+          "required": true
+        },
+        {
+          "name": "DueOn",
+          "type": "Date",
+          "required": true
+        },
+        {
+          "name": "TotalAmount",
+          "type": "Decimal",
+          "required": true
+        },
+        {
+          "name": "VatPercent",
+          "type": "Decimal",
+          "required": true
+        },
+        {
+          "name": "Status",
+          "type": "Enum(Draft,Issued,Paid,Overdue,Void)",
+          "required": true
+        }
+      ]
+    },
+    {
+      "name": "Inspection",
+      "attributes": [
+        {
+          "name": "ScheduledFor",
+          "type": "DateTime",
+          "required": true
+        },
+        {
+          "name": "CompletedOn",
+          "type": "DateTime",
+          "required": false
+        },
+        {
+          "name": "Outcome",
+          "type": "Enum(Pending,Passed,Failed,Deferred)",
+          "required": true
+        },
+        {
+          "name": "InspectorName",
+          "type": "String(100)",
+          "required": true
+        },
+        {
+          "name": "Findings",
+          "type": "String(1000)",
+          "required": false
+        },
+        {
+          "name": "FollowUpRequired",
+          "type": "Boolean",
+          "required": true
+        }
+      ]
+    },
+    {
+      "name": "InspectionItem",
+      "attributes": [
+        {
+          "name": "Category",
+          "type": "Enum(Safety,Environmental,Documentation,Security)",
+          "required": true
+        },
+        {
+          "name": "Description",
+          "type": "String(300)",
+          "required": true
+        },
+        {
+          "name": "IsCompliant",
+          "type": "Boolean",
+          "required": true
+        },
+        {
+          "name": "Severity",
+          "type": "Enum(Low,Medium,High)",
+          "required": false
+        },
+        {
+          "name": "Note",
+          "type": "String(300)",
+          "required": false
+        }
+      ]
+    },
+    {
+      "name": "AuditEntry",
+      "attributes": [
+        {
+          "name": "OccurredOn",
+          "type": "DateTime",
+          "required": true
+        },
+        {
+          "name": "Actor",
+          "type": "String(200)",
+          "required": true
+        },
+        {
+          "name": "Action",
+          "type": "String(100)",
+          "required": true
+        },
+        {
+          "name": "EntityName",
+          "type": "String(60)",
+          "required": true
+        },
+        {
+          "name": "Detail",
+          "type": "String(1000)",
+          "required": false
+        }
+      ]
+    }
+  ],
+  "associations": [
+    {
+      "name": "BookingRequest_Vessel",
+      "from": "BookingRequest",
+      "to": "Vessel",
+      "type": "ManyToOne"
+    },
+    {
+      "name": "BookingRequest_ShippingAgent",
+      "from": "BookingRequest",
+      "to": "ShippingAgent",
+      "type": "ManyToOne"
+    },
+    {
+      "name": "BookingRequest_Berth",
+      "from": "BookingRequest",
+      "to": "Berth",
+      "type": "ManyToOne"
+    },
+    {
+      "name": "ApprovalDecision_BookingRequest",
+      "from": "ApprovalDecision",
+      "to": "BookingRequest",
+      "type": "ManyToOne"
+    },
+    {
+      "name": "Invoice_BookingRequest",
+      "from": "Invoice",
+      "to": "BookingRequest",
+      "type": "OneToOne"
+    },
+    {
+      "name": "Invoice_Tariff",
+      "from": "Invoice",
+      "to": "Tariff",
+      "type": "ManyToOne"
+    },
+    {
+      "name": "Invoice_ShippingAgent",
+      "from": "Invoice",
+      "to": "ShippingAgent",
+      "type": "ManyToOne"
+    },
+    {
+      "name": "Inspection_BookingRequest",
+      "from": "Inspection",
+      "to": "BookingRequest",
+      "type": "ManyToOne"
+    },
+    {
+      "name": "InspectionItem_Inspection",
+      "from": "InspectionItem",
+      "to": "Inspection",
+      "type": "ManyToOne"
+    },
+    {
+      "name": "Berth_Terminal",
+      "from": "Berth",
+      "to": "Terminal",
+      "type": "ManyToOne"
+    },
+    {
+      "name": "Tariff_Terminal",
+      "from": "Tariff",
+      "to": "Terminal",
+      "type": "ManyToOne"
+    },
+    {
+      "name": "AuditEntry_BookingRequest",
+      "from": "AuditEntry",
+      "to": "BookingRequest",
+      "type": "ManyToOne"
+    },
+    {
+      "name": "Vessel_ShippingAgent",
+      "from": "Vessel",
+      "to": "ShippingAgent",
+      "type": "ManyToMany"
+    }
+  ],
+  "requirements": [
+    {
+      "id": "R001",
+      "text": "The system lets licensed shipping agents request berths online for vessels they represent.",
+      "section": {
+        "file": "04-vision-and-scope.html",
+        "heading": "1.1 Purpose"
+      },
+      "form": "prose"
+    },
+    {
+      "id": "R002",
+      "text": "Berth officers review every booking request and record an approval decision with a reason.",
+      "section": {
+        "file": "04-vision-and-scope.html",
+        "heading": "1.2 Goals"
+      },
+      "form": "bullet"
+    },
+    {
+      "id": "R003",
+      "text": "Pilotage and tug scheduling are out of scope and remain in the existing marine operations system.",
+      "section": {
+        "file": "04-vision-and-scope.html",
+        "heading": "1.3 Out of scope"
+      },
+      "form": "prose",
+      "negative": true
+    },
+    {
+      "id": "R004",
+      "text": "Four user roles exist: Shipping Agent, Berth Officer, Harbour Master and Inspector.",
+      "section": {
+        "file": "05-stakeholders-and-roles.html",
+        "heading": "2.1 Actors"
+      },
+      "form": "table"
+    },
+    {
+      "id": "R005",
+      "text": "The Harbour Master can perform every action a Berth Officer can, plus decision overrides, agent reactivation and tariff maintenance.",
+      "section": {
+        "file": "05-stakeholders-and-roles.html",
+        "heading": "2.3 Harbour Master"
+      },
+      "form": "prose"
+    },
+    {
+      "id": "R006",
+      "text": "A booking request always refers to exactly one vessel, one shipping agent and one berth.",
+      "section": {
+        "file": "07-domain-overview.html",
+        "heading": "3.1 Core concepts"
+      },
+      "form": "prose"
+    },
+    {
+      "id": "R007",
+      "text": "An agent can save a booking request as Draft and complete it later; drafts are invisible to officers.",
+      "section": {
+        "file": "08-booking-lifecycle.html",
+        "heading": "4.1 Draft"
+      },
+      "form": "prose"
+    },
+    {
+      "id": "R008",
+      "text": "On submission the system assigns a unique booking reference in the format HB-YYYY-NNNNN.",
+      "section": {
+        "file": "08-booking-lifecycle.html",
+        "heading": "4.2 Submission"
+      },
+      "form": "bullet"
+    },
+    {
+      "id": "R009",
+      "text": "A booking request moves through the states Draft, Submitted, Under Review, Approved, Rejected, Cancelled and Completed.",
+      "section": {
+        "file": "08-booking-lifecycle.html",
+        "heading": "4.3 Status model"
+      },
+      "form": "table"
+    },
+    {
+      "id": "R010",
+      "text": "A booking request is automatically approved when the requested berth is free for the whole stay and the vessel is shorter than 120 metres.",
+      "section": {
+        "file": "08-booking-lifecycle.html",
+        "heading": "4.4 Fast-track"
+      },
+      "form": "table"
+    },
+    {
+      "id": "R011",
+      "text": "The booking form requires vessel, berth, ETA, ETD and cargo class before it can be submitted.",
+      "section": {
+        "file": "09-booking-request-form.html",
+        "heading": "5.1 Mandatory fields"
+      },
+      "form": "bullet"
+    },
+    {
+      "id": "R012",
+      "text": "ETD must be later than ETA, and the system rejects a stay longer than 30 days.",
+      "section": {
+        "file": "09-booking-request-form.html",
+        "heading": "5.2 Validation"
+      },
+      "form": "prose"
+    },
+    {
+      "id": "R013",
+      "text": "An agent may edit a Submitted request until an officer opens it for review, after which it is locked.",
+      "section": {
+        "file": "10-cancellation-and-changes.html",
+        "heading": "6.1 Changing a request"
+      },
+      "form": "prose"
+    },
+    {
+      "id": "R014",
+      "text": "Cancellation is free of charge until 24 hours before ETA.",
+      "section": {
+        "file": "10-cancellation-and-changes.html",
+        "heading": "6.2 Cancellation"
+      },
+      "form": "bullet"
+    },
+    {
+      "id": "R015",
+      "text": "A shipping agent registers with a company name, port licence number and a contact e-mail address, and is activated by a Berth Officer.",
+      "section": {
+        "file": "11-agent-onboarding.html",
+        "heading": "7.1 Registration"
+      },
+      "form": "prose"
+    },
+    {
+      "id": "R016",
+      "text": "There is no self-service reactivation; a suspended agent is reactivated only by the Harbour Master.",
+      "section": {
+        "file": "11-agent-onboarding.html",
+        "heading": "7.2 Suspension"
+      },
+      "form": "prose",
+      "negative": true
+    },
+    {
+      "id": "R017",
+      "text": "Each berth records a code, a name, a maximum vessel length, a maximum draught, shore power availability and a status of Available, Closed or Maintenance.",
+      "section": {
+        "file": "12-berth-master-data.html",
+        "heading": "8.1 Berth attributes"
+      },
+      "form": "table"
+    },
+    {
+      "id": "R018",
+      "text": "Only the Harbour Master may waive a tariff surcharge.",
+      "section": {
+        "file": "13-berth-allocation-rules.html",
+        "heading": "9.3 Surcharge waivers"
+      },
+      "form": "prose"
+    },
+    {
+      "id": "R019",
+      "text": "A vessel is identified by its IMO number, which is unique across the vessel registry.",
+      "section": {
+        "file": "14-vessel-registry.html",
+        "heading": "10.1 Vessel record"
+      },
+      "form": "prose"
+    },
+    {
+      "id": "R020",
+      "text": "Vessel type is one of Container, Bulk, Tanker, RoRo, Cruise or General Cargo.",
+      "section": {
+        "file": "14-vessel-registry.html",
+        "heading": "10.2 Vessel types"
+      },
+      "form": "bullet"
+    },
+    {
+      "id": "R021",
+      "text": "Officers work from a Booking Board that lists Submitted and Under Review requests ordered by ETA.",
+      "section": {
+        "file": "15-officer-review-process.html",
+        "heading": "11.1 Queue"
+      },
+      "form": "prose"
+    },
+    {
+      "id": "R022",
+      "text": "Opening a request for review moves it to Under Review and records the reviewing officer.",
+      "section": {
+        "file": "15-officer-review-process.html",
+        "heading": "11.2 Review"
+      },
+      "form": "bullet"
+    },
+    {
+      "id": "R023",
+      "text": "An approval decision has one of three outcomes: Approved, Rejected or Returned for Information.",
+      "section": {
+        "file": "16-approval-decisions.html",
+        "heading": "12.1 Outcomes"
+      },
+      "form": "table"
+    },
+    {
+      "id": "R024",
+      "text": "A request Returned for Information goes back to the agent, who may amend and resubmit it once.",
+      "section": {
+        "file": "16-approval-decisions.html",
+        "heading": "12.2 Return for information"
+      },
+      "form": "prose"
+    },
+    {
+      "id": "R025",
+      "text": "There is no automatic approval; every booking request is reviewed by a berth officer before it can become Approved.",
+      "section": {
+        "file": "15-officer-review-process.html",
+        "heading": "11.4 Manual review only"
+      },
+      "form": "prose",
+      "negative": true
+    },
+    {
+      "id": "R026",
+      "text": "The agent receives an e-mail whenever the status of their booking request changes.",
+      "section": {
+        "file": "17-notifications.html",
+        "heading": "13.1 Agent notifications"
+      },
+      "form": "bullet"
+    },
+    {
+      "id": "R027",
+      "text": "Officers receive a daily digest at 06:00 listing requests with an ETA within the next 48 hours.",
+      "section": {
+        "file": "17-notifications.html",
+        "heading": "13.2 Officer digest"
+      },
+      "form": "prose"
+    },
+    {
+      "id": "R028",
+      "text": "Tariffs are defined per terminal with a rate per metre of vessel length per day, a currency and a validity period.",
+      "section": {
+        "file": "18-tariff-structure.html",
+        "heading": "14.1 Rate cards"
+      },
+      "form": "prose"
+    },
+    {
+      "id": "R029",
+      "text": "An invoice is generated automatically when a booking is marked Completed.",
+      "section": {
+        "file": "20-invoicing.html",
+        "heading": "16.1 Invoice creation"
+      },
+      "form": "prose"
+    },
+    {
+      "id": "R030",
+      "text": "A Harbour Master can mark an invoice as Paid or Void; a Paid invoice cannot be edited.",
+      "section": {
+        "file": "20-invoicing.html",
+        "heading": "16.3 Payment status"
+      },
+      "form": "bullet"
+    },
+    {
+      "id": "R031",
+      "text": "Cancellations made within 72 hours of ETA are charged 50% of the berth fee.",
+      "section": {
+        "file": "19-tariffs-cancellation-fees.html",
+        "heading": "15.2 Late cancellation"
+      },
+      "form": "table"
+    },
+    {
+      "id": "R032",
+      "text": "The review screen shows the vessel's dimensions next to the berth's limits and highlights any exceedance in red.",
+      "section": {
+        "file": "21-officer-review-screen.html",
+        "heading": "17.1 Review screen"
+      },
+      "form": "prose"
+    },
+    {
+      "id": "R033",
+      "text": "An inspector schedules an inspection against an Approved booking and the agent is notified of the time slot.",
+      "section": {
+        "file": "22-inspection-scheduling.html",
+        "heading": "18.1 Scheduling"
+      },
+      "form": "prose"
+    },
+    {
+      "id": "R034",
+      "text": "An inspection consists of checklist items in the categories Safety, Environmental, Documentation and Security.",
+      "section": {
+        "file": "23-inspection-checklist.html",
+        "heading": "19.1 Checklist"
+      },
+      "form": "table"
+    },
+    {
+      "id": "R035",
+      "text": "For each checklist item the inspector records compliant or not compliant, a severity of Low, Medium or High, and an optional note.",
+      "section": {
+        "file": "23-inspection-checklist.html",
+        "heading": "19.2 Recording"
+      },
+      "form": "bullet"
+    },
+    {
+      "id": "R036",
+      "text": "A berth officer may waive the late-arrival surcharge for vessels shorter than 80 metres.",
+      "section": {
+        "file": "24-inspection-outcomes.html",
+        "heading": "20.3 Surcharge relief"
+      },
+      "form": "prose"
+    },
+    {
+      "id": "R037",
+      "text": "Departure clearance is granted by a Berth Officer and requires every inspection on the booking to be Passed or Deferred.",
+      "section": {
+        "file": "25-departure-clearance.html",
+        "heading": "21.1 Clearance"
+      },
+      "form": "prose"
+    },
+    {
+      "id": "R038",
+      "text": "Every status change on a booking, decision, invoice or inspection is written to an audit trail with actor, timestamp and action.",
+      "section": {
+        "file": "26-audit-and-compliance.html",
+        "heading": "22.1 Audit trail"
+      },
+      "form": "prose"
+    },
+    {
+      "id": "R039",
+      "text": "The navigation offers three screens: Booking Board, My Bookings and Inspection Calendar.",
+      "section": {
+        "file": "28-navigation-and-screens.html",
+        "heading": "23.1 Screens"
+      },
+      "form": "table"
+    },
+    {
+      "id": "R040",
+      "text": "The Booking Board can be filtered by terminal, status and ETA date range.",
+      "section": {
+        "file": "29-booking-board-screen.html",
+        "heading": "24.1 Booking Board"
+      },
+      "form": "bullet"
+    },
+    {
+      "id": "R041",
+      "text": "My Bookings shows the agent's own requests only, with Draft requests listed first.",
+      "section": {
+        "file": "30-my-bookings-screen.html",
+        "heading": "25.1 My Bookings"
+      },
+      "form": "prose"
+    },
+    {
+      "id": "R042",
+      "text": "The Inspection Calendar shows inspections per day and per inspector and allows drag-and-drop rescheduling.",
+      "section": {
+        "file": "31-inspection-calendar-screen.html",
+        "heading": "26.1 Calendar"
+      },
+      "form": "prose"
+    },
+    {
+      "id": "R043",
+      "text": "A monthly berth occupancy report per terminal can be exported as CSV.",
+      "section": {
+        "file": "32-reporting.html",
+        "heading": "27.1 Reports"
+      },
+      "form": "bullet"
+    },
+    {
+      "id": "R044",
+      "text": "The system imports vessel positions from the AIS feed every 5 minutes and flags a booking as Arrived when the vessel enters the port geofence.",
+      "section": {
+        "file": "33-integration-ais-feed.html",
+        "heading": "28.2 AIS position feed"
+      },
+      "form": "minified"
+    },
+    {
+      "id": "R045",
+      "text": "Agents can only see bookings, invoices and inspections that belong to their own company.",
+      "section": {
+        "file": "35-security-and-access.html",
+        "heading": "29.1 Access"
+      },
+      "form": "prose"
+    },
+    {
+      "id": "R046",
+      "text": "Agents must be able to attach the cargo manifest as a PDF to a booking request.",
+      "section": {
+        "file": "workshop-notes.md",
+        "heading": "Session 2 — agents"
+      },
+      "form": "bullet"
+    },
+    {
+      "id": "R047",
+      "text": "The review screen must show the last five bookings of the same vessel.",
+      "section": {
+        "file": "workshop-notes.md",
+        "heading": "Session 3 — officers"
+      },
+      "form": "bullet"
+    },
+    {
+      "id": "R048",
+      "text": "Booking references are never reused, even after a request is cancelled or deleted.",
+      "section": {
+        "file": "decisions-log.md",
+        "heading": "ADR-004"
+      },
+      "form": "prose",
+      "negative": true
+    }
+  ],
+  "business_rules": [
+    {
+      "id": "B001",
+      "text": "A booking request cannot be submitted more than 90 days before the ETA.",
+      "must_contain": [
+        "90",
+        "day"
+      ],
+      "section": {
+        "file": "08-booking-lifecycle.html",
+        "heading": "4.5 Timing"
+      },
+      "form": "bullet"
+    },
+    {
+      "id": "B002",
+      "text": "A booking request must be submitted at least 48 hours before the ETA.",
+      "must_contain": [
+        "48",
+        "hour"
+      ],
+      "section": {
+        "file": "08-booking-lifecycle.html",
+        "heading": "4.5 Timing"
+      },
+      "form": "bullet"
+    },
+    {
+      "id": "B003",
+      "text": "A berth can be assigned only if the vessel's length does not exceed the berth's maximum length and the vessel's draught is at least 0.5 metres below the berth's maximum draught.",
+      "must_contain": [
+        "0.5",
+        "draught|draft"
+      ],
+      "section": {
+        "file": "13-berth-allocation-rules.html",
+        "heading": "9.1 Fit check"
+      },
+      "form": "prose"
+    },
+    {
+      "id": "B004",
+      "text": "An agent with three or more overdue invoices is automatically suspended.",
+      "must_contain": [
+        "three|3",
+        "overdue"
+      ],
+      "section": {
+        "file": "11-agent-onboarding.html",
+        "heading": "7.2 Suspension"
+      },
+      "form": "prose"
+    },
+    {
+      "id": "B005",
+      "text": "A suspended agent cannot submit booking requests; bookings that are already Approved remain valid.",
+      "must_contain": [
+        "suspend",
+        "approved"
+      ],
+      "section": {
+        "file": "11-agent-onboarding.html",
+        "heading": "7.2 Suspension"
+      },
+      "form": "prose"
+    },
+    {
+      "id": "B006",
+      "text": "Only the Harbour Master may override a Rejected decision, and the override is recorded with a reason.",
+      "must_contain": [
+        "harbour master|harbourmaster",
+        "reject"
+      ],
+      "section": {
+        "file": "16-approval-decisions.html",
+        "heading": "12.3 Overrides"
+      },
+      "form": "prose"
+    },
+    {
+      "id": "B007",
+      "text": "A booking with cargo class Dangerous Goods cannot be Approved until an inspection has been scheduled.",
+      "must_contain": [
+        "dangerous",
+        "inspection"
+      ],
+      "section": {
+        "file": "22-inspection-scheduling.html",
+        "heading": "18.2 Dangerous goods"
+      },
+      "form": "prose"
+    },
+    {
+      "id": "B008",
+      "text": "A vessel arriving more than 2 hours after its ETA incurs a late-arrival surcharge of 15% of the berth fee.",
+      "must_contain": [
+        "2 hour|two hour|2h",
+        "15"
+      ],
+      "section": {
+        "file": "19-tariffs-cancellation-fees.html",
+        "heading": "15.1 Late arrival"
+      },
+      "form": "table"
+    },
+    {
+      "id": "B009",
+      "text": "Invoices are due 30 days after the issue date and become Overdue on the day after the due date.",
+      "must_contain": [
+        "30",
+        "overdue"
+      ],
+      "section": {
+        "file": "decisions-log.md",
+        "heading": "ADR-006"
+      },
+      "form": "prose"
+    },
+    {
+      "id": "B010",
+      "text": "VAT of 21% is added to all berth fees.",
+      "must_contain": [
+        "21"
+      ],
+      "section": {
+        "file": "18-tariff-structure.html",
+        "heading": "14.3 VAT"
+      },
+      "form": "prose"
+    },
+    {
+      "id": "B011",
+      "text": "An Approved booking may be cancelled by the agent; a Completed booking cannot be cancelled.",
+      "must_contain": [
+        "approved",
+        "completed"
+      ],
+      "section": {
+        "file": "10-cancellation-and-changes.html",
+        "heading": "6.2 Cancellation"
+      },
+      "form": "bullet"
+    },
+    {
+      "id": "B012",
+      "text": "An inspection whose checklist contains any non-compliant item of High severity has the outcome Failed.",
+      "must_contain": [
+        "high",
+        "fail"
+      ],
+      "section": {
+        "file": "23-inspection-checklist.html",
+        "heading": "19.3 Outcome"
+      },
+      "form": "prose"
+    },
+    {
+      "id": "B013",
+      "text": "A Failed inspection blocks departure clearance until a follow-up inspection has Passed.",
+      "must_contain": [
+        "fail",
+        "follow"
+      ],
+      "section": {
+        "file": "24-inspection-outcomes.html",
+        "heading": "20.1 Consequences"
+      },
+      "form": "prose"
+    },
+    {
+      "id": "B014",
+      "text": "The berth fee is vessel length times days alongside times the tariff rate, with days alongside rounded up to whole days and a minimum of one day.",
+      "must_contain": [
+        "round",
+        "minimum|one day|1 day"
+      ],
+      "section": {
+        "file": "18-tariff-structure.html",
+        "heading": "14.2 Fee calculation"
+      },
+      "form": "table"
+    },
+    {
+      "id": "B015",
+      "text": "Shore power is billed at a flat 250 per day when the berth offers it and the agent requested it.",
+      "must_contain": [
+        "250"
+      ],
+      "section": {
+        "file": "18-tariff-structure.html",
+        "heading": "14.4 Shore power"
+      },
+      "form": "minified"
+    }
+  ],
+  "contradictions": [
+    {
+      "id": "C001",
+      "requirements": [
+        "R010",
+        "R025"
+      ],
+      "pages": [
+        "08-booking-lifecycle.html",
+        "15-officer-review-process.html"
+      ],
+      "summary": "Fast-track auto-approval under 120 m versus 'there is no automatic approval'.",
+      "detect_terms": [
+        [
+          "approv"
+        ],
+        [
+          "automatic",
+          "auto",
+          "fast-track",
+          "fast track"
+        ],
+        [
+          "no automatic",
+          "manual",
+          "every",
+          "all requests",
+          "every request",
+          "contradict",
+          "conflict",
+          "inconsisten",
+          "reviewed by"
+        ]
+      ]
+    },
+    {
+      "id": "C002",
+      "requirements": [
+        "R014",
+        "R031"
+      ],
+      "pages": [
+        "10-cancellation-and-changes.html",
+        "19-tariffs-cancellation-fees.html"
+      ],
+      "summary": "Free cancellation until 24 h before ETA versus 50% fee within 72 h of ETA.",
+      "detect_terms": [
+        [
+          "cancel"
+        ],
+        [
+          "24"
+        ],
+        [
+          "72"
+        ]
+      ]
+    },
+    {
+      "id": "C003",
+      "requirements": [
+        "R018",
+        "R036"
+      ],
+      "pages": [
+        "13-berth-allocation-rules.html",
+        "24-inspection-outcomes.html"
+      ],
+      "summary": "Only the Harbour Master may waive surcharges versus a Berth Officer may waive the late-arrival surcharge under 80 m.",
+      "detect_terms": [
+        [
+          "waiv"
+        ],
+        [
+          "surcharge"
+        ],
+        [
+          "harbour master",
+          "harbourmaster",
+          "berth officer",
+          "80",
+          "contradict",
+          "conflict",
+          "inconsisten"
+        ]
+      ]
+    }
+  ],
+  "screenshot_only": [
+    {
+      "id": "S001",
+      "text": "IMO number must be exactly 7 digits",
+      "must_contain": [
+        "7|seven",
+        "digit"
+      ],
+      "page": "09-booking-request-form.html",
+      "mode": "sidecar",
+      "image": "09-booking-request-form_files/fig-booking-form-validation.png",
+      "screen": "Booking request form"
+    },
+    {
+      "id": "S002",
+      "text": "Rejection reason is required when outcome is Rejected",
+      "must_contain": [
+        "reason",
+        "reject"
+      ],
+      "page": "21-officer-review-screen.html",
+      "mode": "inline",
+      "image": "(inline base64 <img> on 21-officer-review-screen.html, id=fig-review-decision)",
+      "screen": "Officer review screen"
+    }
+  ],
+  "corpus": {
+    "markdown": [
+      {
+        "file": "glossary.md",
+        "carries": [
+          "entities"
+        ]
+      },
+      {
+        "file": "roles.md",
+        "carries": [
+          "roles"
+        ]
+      },
+      {
+        "file": "decisions-log.md",
+        "carries": [
+          "R048",
+          "B009"
+        ]
+      },
+      {
+        "file": "workshop-notes.md",
+        "carries": [
+          "R046",
+          "R047"
+        ]
+      }
+    ],
+    "pages": [
+      {
+        "file": "01-home.html",
+        "title": "Home",
+        "chrome": true,
+        "sidecar_images": 8,
+        "inline_screenshots": 0
+      },
+      {
+        "file": "02-about-the-port-authority.html",
+        "title": "About the Port Authority",
+        "chrome": true,
+        "sidecar_images": 6,
+        "inline_screenshots": 0
+      },
+      {
+        "file": "03-release-notes.html",
+        "title": "Release notes",
+        "chrome": true,
+        "sidecar_images": 3,
+        "inline_screenshots": 0,
+        "minified": true
+      },
+      {
+        "file": "04-vision-and-scope.html",
+        "title": "Vision and scope",
+        "chrome": false,
+        "sidecar_images": 4,
+        "inline_screenshots": 0,
+        "carries": [
+          "R001",
+          "R002",
+          "R003"
+        ]
+      },
+      {
+        "file": "05-stakeholders-and-roles.html",
+        "title": "Stakeholders and roles",
+        "chrome": false,
+        "sidecar_images": 5,
+        "inline_screenshots": 0,
+        "carries": [
+          "R004",
+          "R005"
+        ]
+      },
+      {
+        "file": "06-news-and-events.html",
+        "title": "News and events",
+        "chrome": true,
+        "sidecar_images": 10,
+        "inline_screenshots": 0
+      },
+      {
+        "file": "07-domain-overview.html",
+        "title": "Domain overview",
+        "chrome": false,
+        "sidecar_images": 6,
+        "inline_screenshots": 0,
+        "carries": [
+          "R006"
+        ],
+        "entities": [
+          "Vessel",
+          "ShippingAgent",
+          "Berth",
+          "BookingRequest"
+        ]
+      },
+      {
+        "file": "08-booking-lifecycle.html",
+        "title": "Booking lifecycle",
+        "chrome": false,
+        "sidecar_images": 7,
+        "inline_screenshots": 1,
+        "carries": [
+          "R007",
+          "R008",
+          "R009",
+          "R010",
+          "B001",
+          "B002"
+        ]
+      },
+      {
+        "file": "09-booking-request-form.html",
+        "title": "Booking request form",
+        "chrome": false,
+        "sidecar_images": 5,
+        "inline_screenshots": 0,
+        "carries": [
+          "R011",
+          "R012",
+          "S001"
+        ]
+      },
+      {
+        "file": "10-cancellation-and-changes.html",
+        "title": "Cancellation and changes",
+        "chrome": false,
+        "sidecar_images": 3,
+        "inline_screenshots": 0,
+        "carries": [
+          "R013",
+          "R014",
+          "B011"
+        ]
+      },
+      {
+        "file": "11-agent-onboarding.html",
+        "title": "Agent onboarding",
+        "chrome": false,
+        "sidecar_images": 4,
+        "inline_screenshots": 1,
+        "carries": [
+          "R015",
+          "R016",
+          "B004",
+          "B005"
+        ],
+        "minified": true
+      },
+      {
+        "file": "12-berth-master-data.html",
+        "title": "Berth master data",
+        "chrome": false,
+        "sidecar_images": 9,
+        "inline_screenshots": 0,
+        "carries": [
+          "R017"
+        ],
+        "entities": [
+          "Berth",
+          "Terminal"
+        ]
+      },
+      {
+        "file": "13-berth-allocation-rules.html",
+        "title": "Berth allocation rules",
+        "chrome": false,
+        "sidecar_images": 4,
+        "inline_screenshots": 0,
+        "carries": [
+          "B003",
+          "R018"
+        ]
+      },
+      {
+        "file": "14-vessel-registry.html",
+        "title": "Vessel registry",
+        "chrome": false,
+        "sidecar_images": 6,
+        "inline_screenshots": 1,
+        "carries": [
+          "R019",
+          "R020"
+        ],
+        "entities": [
+          "Vessel"
+        ]
+      },
+      {
+        "file": "15-officer-review-process.html",
+        "title": "Officer review process",
+        "chrome": false,
+        "sidecar_images": 5,
+        "inline_screenshots": 0,
+        "carries": [
+          "R021",
+          "R022",
+          "R025"
+        ],
+        "minified": true
+      },
+      {
+        "file": "16-approval-decisions.html",
+        "title": "Approval decisions",
+        "chrome": false,
+        "sidecar_images": 3,
+        "inline_screenshots": 0,
+        "carries": [
+          "R023",
+          "R024",
+          "B006"
+        ]
+      },
+      {
+        "file": "17-notifications.html",
+        "title": "Notifications",
+        "chrome": false,
+        "sidecar_images": 4,
+        "inline_screenshots": 0,
+        "carries": [
+          "R026",
+          "R027"
+        ]
+      },
+      {
+        "file": "18-tariff-structure.html",
+        "title": "Tariff structure",
+        "chrome": false,
+        "sidecar_images": 5,
+        "inline_screenshots": 0,
+        "carries": [
+          "R028",
+          "B010",
+          "B014",
+          "B015"
+        ],
+        "minified": true
+      },
+      {
+        "file": "19-tariffs-cancellation-fees.html",
+        "title": "Tariffs: late arrival and cancellation fees",
+        "chrome": false,
+        "sidecar_images": 3,
+        "inline_screenshots": 0,
+        "carries": [
+          "R031",
+          "B008"
+        ]
+      },
+      {
+        "file": "20-invoicing.html",
+        "title": "Invoicing",
+        "chrome": false,
+        "sidecar_images": 6,
+        "inline_screenshots": 1,
+        "carries": [
+          "R029",
+          "R030"
+        ]
+      },
+      {
+        "file": "21-officer-review-screen.html",
+        "title": "Officer review screen",
+        "chrome": false,
+        "sidecar_images": 4,
+        "inline_screenshots": 1,
+        "carries": [
+          "R032",
+          "S002"
+        ]
+      },
+      {
+        "file": "22-inspection-scheduling.html",
+        "title": "Inspection scheduling",
+        "chrome": false,
+        "sidecar_images": 5,
+        "inline_screenshots": 0,
+        "carries": [
+          "R033",
+          "B007"
+        ]
+      },
+      {
+        "file": "23-inspection-checklist.html",
+        "title": "Inspection checklist",
+        "chrome": false,
+        "sidecar_images": 7,
+        "inline_screenshots": 1,
+        "carries": [
+          "R034",
+          "R035",
+          "B012"
+        ]
+      },
+      {
+        "file": "24-inspection-outcomes.html",
+        "title": "Inspection outcomes",
+        "chrome": false,
+        "sidecar_images": 4,
+        "inline_screenshots": 0,
+        "carries": [
+          "B013",
+          "R036"
+        ],
+        "minified": true
+      },
+      {
+        "file": "25-departure-clearance.html",
+        "title": "Departure clearance",
+        "chrome": false,
+        "sidecar_images": 3,
+        "inline_screenshots": 0,
+        "carries": [
+          "R037"
+        ]
+      },
+      {
+        "file": "26-audit-and-compliance.html",
+        "title": "Audit and compliance",
+        "chrome": false,
+        "sidecar_images": 5,
+        "inline_screenshots": 0,
+        "carries": [
+          "R038"
+        ],
+        "entities": [
+          "AuditEntry"
+        ]
+      },
+      {
+        "file": "27-privacy-and-cookies.html",
+        "title": "Privacy and cookies",
+        "chrome": true,
+        "sidecar_images": 3,
+        "inline_screenshots": 0,
+        "minified": true
+      },
+      {
+        "file": "28-navigation-and-screens.html",
+        "title": "Navigation and screens",
+        "chrome": false,
+        "sidecar_images": 6,
+        "inline_screenshots": 1,
+        "carries": [
+          "R039"
+        ]
+      },
+      {
+        "file": "29-booking-board-screen.html",
+        "title": "Booking Board screen",
+        "chrome": false,
+        "sidecar_images": 5,
+        "inline_screenshots": 1,
+        "carries": [
+          "R040"
+        ]
+      },
+      {
+        "file": "30-my-bookings-screen.html",
+        "title": "My Bookings screen",
+        "chrome": false,
+        "sidecar_images": 4,
+        "inline_screenshots": 1,
+        "carries": [
+          "R041"
+        ]
+      },
+      {
+        "file": "31-inspection-calendar-screen.html",
+        "title": "Inspection Calendar screen",
+        "chrome": false,
+        "sidecar_images": 4,
+        "inline_screenshots": 0,
+        "carries": [
+          "R042"
+        ]
+      },
+      {
+        "file": "32-reporting.html",
+        "title": "Reporting",
+        "chrome": false,
+        "sidecar_images": 6,
+        "inline_screenshots": 0,
+        "carries": [
+          "R043"
+        ]
+      },
+      {
+        "file": "33-integration-ais-feed.html",
+        "title": "Integration: AIS feed",
+        "chrome": false,
+        "sidecar_images": 3,
+        "inline_screenshots": 0,
+        "carries": [
+          "R044"
+        ],
+        "minified": true
+      },
+      {
+        "file": "34-contact-and-support.html",
+        "title": "Contact and support",
+        "chrome": true,
+        "sidecar_images": 7,
+        "inline_screenshots": 0
+      },
+      {
+        "file": "35-security-and-access.html",
+        "title": "Security and access",
+        "chrome": false,
+        "sidecar_images": 3,
+        "inline_screenshots": 0,
+        "carries": [
+          "R045"
+        ]
+      },
+      {
+        "file": "36-appendix-data-dictionary.html",
+        "title": "Appendix: data dictionary",
+        "chrome": false,
+        "sidecar_images": 12,
+        "inline_screenshots": 0,
+        "entities": [
+          "ApprovalDecision",
+          "Tariff",
+          "Invoice",
+          "Inspection",
+          "InspectionItem",
+          "AuditEntry"
+        ],
+        "minified": true
+      }
+    ]
+  },
+  "_detect_terms_note": "A question/decision text 'surfaces' a contradiction when it cites both requirement ids, or when it contains at least one term from EVERY group in detect_terms (case-insensitive substring)."
+}
diff --git a/tests/ab/gen-corpus.py b/tests/ab/gen-corpus.py
new file mode 100644
index 0000000..5d8ce43
--- /dev/null
+++ b/tests/ab/gen-corpus.py
@@ -0,0 +1,909 @@
+#!/usr/bin/env python3
+"""gen-corpus.py — render answer-key.json into a synthetic "webpage, complete" requirements corpus.
+
+    gen-corpus.py <out-dir> [--seed N] [--key answer-key.json] [--no-manifest]
+
+Deterministic for a given seed. Python 3 standard library only (no Pillow): PNGs are written
+with zlib+struct, JPEGs with a tiny baseline encoder, text is drawn with a built-in 5x7 bitmap
+font at 2-3x scale so a vision model can read it.
+
+Everything is fictional — "Harbour Berth Booking" is not a product and the port authority
+does not exist. The corpus is the fixture side of an A/B experiment: agents under test get
+<out-dir> (minus MANIFEST.json); the scorer gets answer-key.json + MANIFEST.json.
+"""
+import argparse
+import base64
+import hashlib
+import json
+import math
+import os
+import random
+import struct
+import sys
+import zlib
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+
+# ----------------------------------------------------------------------------------------
+# 5x7 bitmap font (uppercase; lowercase is drawn as uppercase)
+# ----------------------------------------------------------------------------------------
+FONT = {
+ 'A': ["01110","10001","10001","11111","10001","10001","10001"],
+ 'B': ["11110","10001","10001","11110","10001","10001","11110"],
+ 'C': ["01111","10000","10000","10000","10000","10000","01111"],
+ 'D': ["11110","10001","10001","10001","10001","10001","11110"],
+ 'E': ["11111","10000","10000","11110","10000","10000","11111"],
+ 'F': ["11111","10000","10000","11110","10000","10000","10000"],
+ 'G': ["01111","10000","10000","10111","10001","10001","01111"],
+ 'H': ["10001","10001","10001","11111","10001","10001","10001"],
+ 'I': ["01110","00100","00100","00100","00100","00100","01110"],
+ 'J': ["00111","00010","00010","00010","00010","10010","01100"],
+ 'K': ["10001","10010","10100","11000","10100","10010","10001"],
+ 'L': ["10000","10000","10000","10000","10000","10000","11111"],
+ 'M': ["10001","11011","10101","10101","10001","10001","10001"],
+ 'N': ["10001","11001","10101","10011","10001","10001","10001"],
+ 'O': ["01110","10001","10001","10001","10001","10001","01110"],
+ 'P': ["11110","10001","10001","11110","10000","10000","10000"],
+ 'Q': ["01110","10001","10001","10001","10101","10010","01101"],
+ 'R': ["11110","10001","10001","11110","10100","10010","10001"],
+ 'S': ["01111","10000","10000","01110","00001","00001","11110"],
+ 'T': ["11111","00100","00100","00100","00100","00100","00100"],
+ 'U': ["10001","10001","10001","10001","10001","10001","01110"],
+ 'V': ["10001","10001","10001","10001","01010","01010","00100"],
+ 'W': ["10001","10001","10001","10101","10101","11011","10001"],
+ 'X': ["10001","10001","01010","00100","01010","10001","10001"],
+ 'Y': ["10001","10001","01010","00100","00100","00100","00100"],
+ 'Z': ["11111","00001","00010","00100","01000","10000","11111"],
+ '0': ["01110","10001","10011","10101","11001","10001","01110"],
+ '1': ["00100","01100","00100","00100","00100","00100","01110"],
+ '2': ["01110","10001","00001","00010","00100","01000","11111"],
+ '3': ["11111","00010","00100","00010","00001","10001","01110"],
+ '4': ["00010","00110","01010","10010","11111","00010","00010"],
+ '5': ["11111","10000","11110","00001","00001","10001","01110"],
+ '6': ["00110","01000","10000","11110","10001","10001","01110"],
+ '7': ["11111","00001","00010","00100","01000","01000","01000"],
+ '8': ["01110","10001","10001","01110","10001","10001","01110"],
+ '9': ["01110","10001","10001","01111","00001","00010","01100"],
+ ' ': ["00000","00000","00000","00000","00000","00000","00000"],
+ '.': ["00000","00000","00000","00000","00000","01100","01100"],
+ ',': ["00000","00000","00000","00000","01100","00100","01000"],
+ ':': ["00000","01100","01100","00000","01100","01100","00000"],
+ ';': ["00000","01100","01100","00000","01100","00100","01000"],
+ '-': ["00000","00000","00000","11111","00000","00000","00000"],
+ '(': ["00100","01000","10000","10000","10000","01000","00100"],
+ ')': ["00100","00010","00001","00001","00001","00010","00100"],
+ '/': ["00001","00001","00010","00100","01000","10000","10000"],
+ "'": ["00100","00100","01000","00000","00000","00000","00000"],
+ '*': ["00000","10101","01110","11111","01110","10101","00000"],
+ '!': ["00100","00100","00100","00100","00100","00000","00100"],
+ '?': ["01110","10001","00001","00010","00100","00000","00100"],
+ '%': ["11001","11001","00010","00100","01000","10011","10011"],
+ '=': ["00000","00000","11111","00000","11111","00000","00000"],
+ '+': ["00000","00100","00100","11111","00100","00100","00000"],
+ '_': ["00000","00000","00000","00000","00000","00000","11111"],
+ '<': ["00010","00100","01000","10000","01000","00100","00010"],
+ '>': ["01000","00100","00010","00001","00010","00100","01000"],
+ '[': ["01110","01000","01000","01000","01000","01000","01110"],
+ ']': ["01110","00010","00010","00010","00010","00010","01110"],
+ '|': ["00100","00100","00100","00100","00100","00100","00100"],
+ '#': ["01010","01010","11111","01010","11111","01010","01010"],
+ '&': ["01100","10010","10100","01000","10101","10010","01101"],
+ '@': ["01110","10001","10111","10101","10111","10000","01110"],
+ 'v': ["00000","00000","10001","10001","01010","01010","00100"],
+}
+
+
+class Canvas:
+    """RGB byte canvas with rectangle, text and noise primitives. No dependencies."""
+
+    def __init__(self, w, h, color=(255, 255, 255)):
+        self.w, self.h = w, h
+        self.px = bytearray(bytes(color) * (w * h))
+
+    def put(self, x, y, c):
+        if 0 <= x < self.w and 0 <= y < self.h:
+            i = (y * self.w + x) * 3
+            self.px[i:i + 3] = bytes(c)
+
+    def rect(self, x, y, w, h, c, fill=True):
+        x0, y0 = max(0, x), max(0, y)
+        x1, y1 = min(self.w, x + w), min(self.h, y + h)
+        if x1 <= x0 or y1 <= y0:
+            return
+        if fill:
+            row = bytes(c) * (x1 - x0)
+            for yy in range(y0, y1):
+                i = (yy * self.w + x0) * 3
+                self.px[i:i + (x1 - x0) * 3] = row
+        else:
+            self.rect(x, y, w, 1, c); self.rect(x, y + h - 1, w, 1, c)
+            self.rect(x, y, 1, h, c); self.rect(x + w - 1, y, 1, h, c)
+
+    def text(self, x, y, s, scale=2, color=(20, 20, 20)):
+        cx = x
+        for ch in s:
+            up = ch.upper()
+            g = FONT.get(up) or FONT.get(ch) or FONT['?']
+            for ry, row in enumerate(g):
+                for rx, bit in enumerate(row):
+                    if bit == '1':
+                        self.rect(cx + rx * scale, y + ry * scale, scale, scale, color)
+            cx += 6 * scale
+        return cx
+
+    def text_width(self, s, scale=2):
+        return len(s) * 6 * scale
+
+    def noise(self, rng, amplitude, x=0, y=0, w=None, h=None, every=1):
+        """Add +-amplitude noise to a region; `every` thins it out (size control)."""
+        w = self.w if w is None else w
+        h = self.h if h is None else h
+        px = self.px
+        W = self.w
+        for yy in range(y, min(self.h, y + h)):
+            base = yy * W
+            for xx in range(x, min(self.w, x + w), every):
+                i = (base + xx) * 3
+                d = rng.randint(-amplitude, amplitude)
+                for k in range(3):
+                    v = px[i + k] + d
+                    px[i + k] = 0 if v < 0 else 255 if v > 255 else v
+
+    def gray(self):
+        out = bytearray(self.w * self.h)
+        px = self.px
+        for i in range(self.w * self.h):
+            j = i * 3
+            out[i] = (px[j] * 299 + px[j + 1] * 587 + px[j + 2] * 114) // 1000
+        return out
+
+
+# ----------------------------------------------------------------------------------------
+# PNG (zlib + struct)
+# ----------------------------------------------------------------------------------------
+def png_bytes(canvas):
+    w, h, px = canvas.w, canvas.h, canvas.px
+    raw = bytearray()
+    stride = w * 3
+    for y in range(h):
+        raw.append(0)
+        raw += px[y * stride:(y + 1) * stride]
+
+    def chunk(tag, data):
+        c = struct.pack('>I', len(data)) + tag + data
+        return c + struct.pack('>I', zlib.crc32(tag + data) & 0xffffffff)
+    return (b'\x89PNG\r\n\x1a\n' + chunk(b'IHDR', struct.pack('>IIBBBBB', w, h, 8, 2, 0, 0, 0))
+            + chunk(b'IDAT', zlib.compress(bytes(raw), 6)) + chunk(b'IEND', b''))
+
+
+# ----------------------------------------------------------------------------------------
+# Baseline JPEG, grayscale, one scan. The Huffman tables are deliberately trivial (fixed-length
+# canonical codes written into DHT) — valid for any decoder, no memorised spec tables needed.
+# ----------------------------------------------------------------------------------------
+_STD_LUM_Q = [16, 11, 10, 16, 24, 40, 51, 61, 12, 12, 14, 19, 26, 58, 60, 55,
+              14, 13, 16, 24, 40, 57, 69, 56, 14, 17, 22, 29, 51, 87, 80, 62,
+              18, 22, 37, 56, 68, 109, 103, 77, 24, 35, 55, 64, 81, 104, 113, 92,
+              49, 64, 78, 87, 103, 121, 120, 101, 72, 92, 95, 98, 112, 100, 103, 99]
+
+
+def _zigzag():
+    order = []
+    for s in range(15):
+        diag = [(r, s - r) for r in range(8) if 0 <= s - r < 8]
+        if s % 2 == 0:
+            diag.reverse()
+        order += [r * 8 + c for r, c in diag]
+    return order
+
+
+_ZZ = _zigzag()
+_COS = [[math.cos((2 * x + 1) * u * math.pi / 16) for x in range(8)] for u in range(8)]
+_CU = [1 / math.sqrt(2)] + [1.0] * 7
+_DC_VALUES = list(range(12))
+_AC_VALUES = [0x00, 0xF0] + [(r << 4) | s for r in range(16) for s in range(1, 11)]
+_DC_CODES = {v: (i, 4) for i, v in enumerate(_DC_VALUES)}           # 12 codes, 4 bits each
+_AC_CODES = {v: (i, 8) for i, v in enumerate(_AC_VALUES)}           # 162 codes, 8 bits each
+
+
+class _Bits:
+    def __init__(self):
+        self.out = bytearray(); self.acc = 0; self.n = 0
+
+    def write(self, code, length):
+        self.acc = (self.acc << length) | code
+        self.n += length
+        while self.n >= 8:
+            b = (self.acc >> (self.n - 8)) & 0xFF
+            self.out.append(b)
+            if b == 0xFF:
+                self.out.append(0)
+            self.n -= 8
+            self.acc &= (1 << self.n) - 1
+
+    def flush(self):
+        if self.n:
+            pad = 8 - self.n
+            self.write(((1 << pad) - 1), pad)
+
+
+def _dht(tc_th, bits_index, values):
+    bits = [0] * 16
+    bits[bits_index - 1] = len(values)
+    body = bytes([tc_th]) + bytes(bits) + bytes(values)
+    return b'\xFF\xC4' + struct.pack('>H', len(body) + 2) + body
+
+
+def jpeg_bytes(w, h, gray, quality=70):
+    q = 5000 / quality if quality < 50 else 200 - quality * 2
+    Q = [max(1, min(255, int((v * q + 50) / 100))) for v in _STD_LUM_Q]
+    out = bytearray(b'\xFF\xD8')
+    out += b'\xFF\xE0' + struct.pack('>H', 16) + b'JFIF\x00\x01\x01\x00\x00\x01\x00\x01\x00\x00'
+    out += b'\xFF\xDB' + struct.pack('>H', 67) + b'\x00' + bytes(Q[i] for i in _ZZ)
+    out += b'\xFF\xC0' + struct.pack('>HBHHB', 11, 8, h, w, 1) + b'\x01\x11\x00'
+    out += _dht(0x00, 4, _DC_VALUES) + _dht(0x10, 8, _AC_VALUES)
+    out += b'\xFF\xDA' + struct.pack('>HB', 8, 1) + b'\x01\x00\x00\x3F\x00'
+    bw = _Bits()
+    prev_dc = 0
+    blk = [0.0] * 64
+    tmp = [0.0] * 64
+    for by in range(0, h, 8):
+        for bx in range(0, w, 8):
+            for y in range(8):
+                yy = min(h - 1, by + y)
+                for x in range(8):
+                    xx = min(w - 1, bx + x)
+                    blk[y * 8 + x] = gray[yy * w + xx] - 128.0
+            # separable DCT: rows then columns
+            for y in range(8):
+                row = blk[y * 8:y * 8 + 8]
+                for v in range(8):
+                    cv = _COS[v]
+                    tmp[y * 8 + v] = sum(row[x] * cv[x] for x in range(8))
+            coeffs = [0] * 64
+            for u in range(8):
+                cu = _COS[u]
+                for v in range(8):
+                    s = sum(tmp[y * 8 + v] * cu[y] for y in range(8))
+                    val = 0.25 * _CU[u] * _CU[v] * s
+                    coeffs[u * 8 + v] = int(round(val / Q[u * 8 + v]))
+            zz = [coeffs[i] for i in _ZZ]
+            diff = zz[0] - prev_dc
+            prev_dc = zz[0]
+            s = abs(diff).bit_length()
+            code, ln = _DC_CODES[s]
+            bw.write(code, ln)
+            if s:
+                bw.write(diff if diff > 0 else (diff + (1 << s) - 1), s)
+            run = 0
+            for k in range(1, 64):
+                v = zz[k]
+                if v == 0:
+                    run += 1
+                    continue
+                while run > 15:
+                    c, l = _AC_CODES[0xF0]; bw.write(c, l); run -= 16
+                s = abs(v).bit_length()
+                c, l = _AC_CODES[(run << 4) | s]
+                bw.write(c, l)
+                bw.write(v if v > 0 else (v + (1 << s) - 1), s)
+                run = 0
+            if run:
+                c, l = _AC_CODES[0x00]; bw.write(c, l)
+    bw.flush()
+    out += bw.out + b'\xFF\xD9'
+    return bytes(out)
+
+
+# ----------------------------------------------------------------------------------------
+# Picture content: "photos" of a fictional port, and mock screens
+# ----------------------------------------------------------------------------------------
+def scene(rng, w, h, noise_amp=6, noise_every=1):
+    c = Canvas(w, h)
+    horizon = int(h * rng.uniform(0.35, 0.55))
+    sky_top = (rng.randint(120, 180), rng.randint(160, 210), rng.randint(210, 245))
+    for y in range(horizon):
+        t = y / max(1, horizon)
+        col = tuple(int(sky_top[k] * (1 - t) + 235 * t) for k in range(3))
+        c.rect(0, y, w, 1, col)
+    sea = (rng.randint(20, 60), rng.randint(70, 120), rng.randint(110, 160))
+    for y in range(horizon, h):
+        t = (y - horizon) / max(1, h - horizon)
+        wave = int(6 * math.sin(y * 0.35 + rng.random() * 0.2))
+        col = tuple(max(0, min(255, int(sea[k] * (1 - 0.4 * t) + wave))) for k in range(3))
+        c.rect(0, y, w, 1, col)
+    # quay, containers, cranes
+    quay_y = horizon + rng.randint(5, 25)
+    c.rect(0, quay_y, w, rng.randint(8, 18), (90, 90, 95))
+    for _ in range(rng.randint(4, 14)):
+        cw, chh = rng.randint(12, 40), rng.randint(8, 16)
+        c.rect(rng.randint(0, w - cw), quay_y - chh, cw, chh,
+               (rng.randint(120, 220), rng.randint(40, 120), rng.randint(30, 80)))
+    for _ in range(rng.randint(1, 4)):
+        x = rng.randint(10, w - 30)
+        top = rng.randint(10, horizon - 10)
+        c.rect(x, top, 4, quay_y - top, (200, 60, 40))
+        c.rect(x - rng.randint(10, 40), top, rng.randint(30, 80), 4, (200, 60, 40))
+    # hull silhouette
+    if rng.random() < 0.7:
+        hw = rng.randint(w // 4, w // 2)
+        hx = rng.randint(0, w - hw)
+        c.rect(hx, horizon - 6, hw, 14, (30, 30, 40))
+        c.rect(hx + hw // 3, horizon - 26, hw // 4, 20, (230, 230, 230))
+    c.noise(rng, noise_amp, every=noise_every)
+    return c
+
+
+def mock_screen(rng, title, fields, message=None, message_after=None, marker_field=None,
+                w=760, h=440, noise_amp=3, noise_every=2, text_scale=2, message_scale=3):
+    """A fake application window: title bar, side nav, a form with labelled input boxes.
+    `message` is drawn in red under `message_after`; `marker_field` gets a red asterisk."""
+    c = Canvas(w, h, (236, 239, 243))
+    c.rect(0, 0, w, 34, (28, 60, 100))
+    c.text(12, 10, 'HARBOUR BERTH BOOKING', 2, (255, 255, 255))
+    c.rect(0, 34, 150, h - 34, (215, 221, 228))
+    for i, item in enumerate(['BOOKING BOARD', 'MY BOOKINGS', 'INSPECTIONS', 'TARIFFS', 'REPORTS']):
+        c.text(10, 50 + i * 26, item, 2, (60, 70, 80))
+    c.rect(170, 50, w - 190, h - 70, (255, 255, 255))
+    c.rect(170, 50, w - 190, h - 70, (190, 196, 204), fill=False)
+    c.text(186, 62, title, 2, (28, 60, 100))
+    y = 94
+    for label, value in fields:
+        lab = label + (' *' if marker_field == label else '')
+        c.text(186, y + 4, lab, text_scale, (70, 70, 70))
+        col = (200, 40, 40) if marker_field == label else (150, 150, 150)
+        c.rect(186 + 170, y - 2, w - 190 - 200, 22, (250, 250, 250))
+        c.rect(186 + 170, y - 2, w - 190 - 200, 22, col, fill=False)
+        c.text(186 + 176, y + 3, value, text_scale, (30, 30, 30))
+        y += 30
+        if message and message_after == label:
+            # word-wrap the message inside the panel so nothing is clipped
+            avail = (w - 190 - 32) // (6 * message_scale)
+            lines, cur = [], ''
+            for word in message.split():
+                if cur and len(cur) + 1 + len(word) > avail:
+                    lines.append(cur); cur = word
+                else:
+                    cur = (cur + ' ' + word).strip()
+            lines.append(cur)
+            for ln in lines:
+                c.text(186, y, ln, message_scale, (200, 30, 30))
+                y += 8 * message_scale
+            y += 8
+    c.rect(w - 130, h - 52, 90, 26, (28, 110, 60))
+    c.text(w - 118, h - 45, 'SUBMIT', 2, (255, 255, 255))
+    c.noise(rng, noise_amp, 170, 50, w - 190, h - 70, every=noise_every)
+    return c
+
+
+# ----------------------------------------------------------------------------------------
+# Prose filler (fluff, never a rule) and HTML chrome
+# ----------------------------------------------------------------------------------------
+FILLER = [
+    "This section was reviewed with the operations team during the second documentation workshop.",
+    "The wording below reflects the agreed position at the time of writing and may be refined in a later revision.",
+    "Readers new to port operations should first consult the glossary for the terms used here.",
+    "Nothing in this chapter changes the responsibilities described in the stakeholder overview.",
+    "Where the text says 'the system', it means the Harbour Berth Booking application as a whole.",
+    "The examples given are illustrative and use fictional vessel names throughout.",
+    "Screenshots on this page are taken from the clickable prototype and may differ slightly from the final layout.",
+    "Questions about this chapter can be raised through the usual documentation feedback channel.",
+    "The numbering of headings follows the master table of contents and is stable across revisions.",
+    "This chapter does not describe the technical implementation; see the architecture notes for that.",
+    "Paragraphs marked as guidance are explanatory and do not add obligations.",
+    "The behaviour described here was demonstrated in the prototype walkthrough.",
+    "Terminology in this chapter is aligned with the glossary; where they differ, the glossary wins.",
+    "Diagrams are provided for orientation only.",
+    "The review comments from the previous round have been incorporated into this revision.",
+    "The chapter is intentionally short; details that belong to other chapters are cross-referenced rather than repeated.",
+    "For the history of this chapter see the release notes page.",
+    "Figures on this page are numbered per page, not per document.",
+]
+
+FILLER_BULLETS = [
+    "Reviewed by the documentation owner.",
+    "Cross-referenced from the glossary.",
+    "Illustrated in the prototype.",
+    "Discussed in workshop session 2.",
+    "No open comments on this item.",
+    "Wording aligned with the stakeholder overview.",
+    "Applies to all terminals unless stated otherwise.",
+    "See also the appendix data dictionary.",
+]
+
+FILLER_TABLE_ROWS = [
+    ("Owner", "Documentation team, port operations"),
+    ("Last reviewed", "Revision 7"),
+    ("Related chapter", "See the navigation sidebar"),
+    ("Illustration", "Figure on this page"),
+    ("Guidance", "Explanatory text, no obligations added"),
+    ("Status", "Agreed"),
+]
+
+MARKETING = [
+    "Welcome to the documentation portal for Harbour Berth Booking, the fictional port authority's berth request application.",
+    "The portal collects the functional description, the workshop notes and the decision log in one place.",
+    "Use the sidebar to move between chapters; every page shares the same navigation.",
+    "This portal is a documentation export. Interactive features of the original site are not available offline.",
+    "The port handles a fictional mix of container, bulk and cruise traffic across three terminals.",
+    "Our documentation team publishes a new revision roughly every fortnight.",
+    "The application described here replaces a spreadsheet-based booking process.",
+    "Thank you for reading. Feedback is welcome through the support page.",
+]
+
+CHANGELOG = [
+    ("Revision 7", ["Corrected the caption of the review screen figure.", "Sidebar now lists the appendix.", "Fixed a broken link in the tariff chapter."]),
+    ("Revision 6", ["Added the AIS integration chapter.", "Renumbered headings after the inspection chapters were split.", "Typo fixes throughout."]),
+    ("Revision 5", ["Added the data dictionary appendix.", "Workshop notes moved to a separate file."]),
+    ("Revision 4", ["Added screenshots from the prototype.", "Glossary extended with inspection terms."]),
+    ("Revision 3", ["First complete draft for review."]),
+    ("Revision 2", ["Restructured into chapters."]),
+    ("Revision 1", ["Initial outline."]),
+]
+
+CLASS_SOUP = ["c-a1", "c-b2", "mod-x", "u-pad-3", "grid__cell", "t-body", "is-visible", "js-hook",
+              "l-block", "l-block--wide", "theme-harbour", "v2", "legacy-wrap", "clearfix", "wp-block"]
+
+
+def esc(s):
+    return s.replace('&', '&amp;').replace('<', '&lt;').replace('>', '&gt;')
+
+
+def soup(rng, n=3):
+    return ' '.join(rng.sample(CLASS_SOUP, n))
+
+
+def wrap_div(rng, inner, depth):
+    for _ in range(depth):
+        style = rng.choice(["margin:0;padding:0", "display:block", "position:relative",
+                            "box-sizing:border-box;padding:0 4px", "font-size:inherit", ""])
+        inner = f'<div class="{soup(rng)}"{(" style=%s" % json.dumps(style)) if style else ""}>{inner}</div>'
+    return inner
+
+
+def para(rng, sentences):
+    return wrap_div(rng, '<p class="%s">%s</p>' % (soup(rng, 2), esc(' '.join(sentences))), rng.randint(1, 3))
+
+
+def filler_para(rng, n=None):
+    n = n or rng.randint(2, 4)
+    return para(rng, rng.sample(FILLER, n))
+
+
+def type_label(t):
+    if t.startswith('String('):
+        return 'Text, up to %s characters' % t[7:-1]
+    if t.startswith('Enum('):
+        return 'One of: ' + ', '.join(t[5:-1].split(','))
+    return {'Decimal': 'Decimal number', 'Integer': 'Whole number', 'Boolean': 'Yes/No',
+            'DateTime': 'Date and time', 'Date': 'Date'}.get(t, t)
+
+
+def entity_table(rng, ent):
+    rows = ''.join('<tr><td><code>%s</code></td><td>%s</td><td>%s</td></tr>'
+                   % (a['name'], type_label(a['type']), 'Required' if a['required'] else 'Optional')
+                   for a in ent['attributes'])
+    return wrap_div(rng, ('<h3 id="ent-%s">%s</h3><table class="%s"><thead><tr><th>Attribute</th><th>Type</th>'
+                          '<th>Required</th></tr></thead><tbody>%s</tbody></table>')
+                    % (ent['name'], ent['name'], soup(rng, 2), rows), rng.randint(1, 2))
+
+
+def assoc_sentence(a):
+    kind = {'ManyToOne': 'many-to-one', 'OneToOne': 'one-to-one', 'ManyToMany': 'many-to-many'}[a['type']]
+    return "%s refers to %s (%s, %s)." % (a['from'], a['to'], a['name'], kind)
+
+
+def render_statement(rng, item, key):
+    """Render one requirement/rule in the form the key asks for. Returns HTML, and a flag that says
+    whether it is a minified one-line block that the page must emit verbatim."""
+    form = item.get('form', 'prose')
+    text = item['text']
+    if form == 'prose':
+        before = rng.sample(FILLER, rng.randint(0, 2))
+        after = rng.sample(FILLER, rng.randint(0, 1))
+        return para(rng, before + [text] + after)
+    if form == 'bullet':
+        items = rng.sample(FILLER_BULLETS, rng.randint(2, 4))
+        items.insert(rng.randint(0, len(items)), text)
+        lis = ''.join('<li class="%s">%s</li>' % (soup(rng, 1), esc(i)) for i in items)
+        return wrap_div(rng, '<ul class="%s">%s</ul>' % (soup(rng, 2), lis), rng.randint(1, 2))
+    if form == 'table':
+        rows = rng.sample(FILLER_TABLE_ROWS, rng.randint(2, 4))
+        rows.insert(rng.randint(0, len(rows)), ("Requirement", text))
+        trs = ''.join('<tr><td class="%s">%s</td><td>%s</td></tr>' % (soup(rng, 1), esc(k), esc(v)) for k, v in rows)
+        return wrap_div(rng, '<table class="%s"><thead><tr><th>Aspect</th><th>Statement</th></tr></thead><tbody>%s</tbody></table>'
+                        % (soup(rng, 2), trs), 1)
+    if form == 'minified':
+        return None  # emitted inside the page's one-line block
+    raise ValueError(form)
+
+
+def minified_line(rng, embedded_html='', target_bytes=26000):
+    """One line of >20 KB: a berth-occupancy 'heatmap' of inline-styled spans. Requirement text, if
+    any, is buried in the middle of it."""
+    cells = []
+    while sum(len(c) for c in cells) < target_bytes:
+        col = '#%02x%02x%02x' % (rng.randint(180, 240), rng.randint(60, 200), rng.randint(40, 120))
+        cells.append('<span class="hm-cell %s" style="background:%s;width:9px;height:9px;display:inline-block" data-b="B%02d" data-d="%d" title="berth B%02d day %d"></span>'
+                     % (rng.choice(CLASS_SOUP), col, rng.randint(1, 24), rng.randint(1, 31), rng.randint(1, 24), rng.randint(1, 31)))
+    mid = len(cells) // 2
+    head = ''.join(cells[:mid]); tail = ''.join(cells[mid:])
+    return ('<div class="hm-wrap %s" style="line-height:0;font-size:0"><div class="hm-legend" style="font-size:11px">Berth occupancy heatmap (prototype data)</div>%s%s%s</div>'
+            % (soup(rng, 2), head, embedded_html, tail))
+
+
+def sidebar(pages, current):
+    lis = []
+    for p in pages:
+        cls = ' class="active"' if p['file'] == current else ''
+        lis.append('<li%s><a href="%s">%s</a></li>' % (cls, p['file'], esc(p['title'])))
+    md = ''.join('<li><a href="%s">%s</a></li>' % (m, m) for m in ('glossary.md', 'roles.md', 'decisions-log.md', 'workshop-notes.md'))
+    return ('<aside class="c-sidebar l-block theme-harbour"><div class="c-sidebar__inner"><div class="c-brand"><span class="c-brand__mark"></span>'
+            '<span class="c-brand__name">Harbour Berth Booking</span><span class="c-brand__sub">Documentation portal</span></div>'
+            '<nav aria-label="Chapters"><ul class="c-nav">%s</ul></nav><div class="c-sidebar__files"><h4>Files</h4><ul>%s</ul></div>'
+            '<div class="c-sidebar__foot">Revision 7 &middot; exported for offline reading</div></div></aside>' % (''.join(lis), md))
+
+
+def header_html():
+    return ('<header class="c-header clearfix"><div class="c-header__bar"><a class="c-header__home" href="01-home.html">Home</a>'
+            '<span class="c-header__crumb">Documentation</span><form class="c-search js-hook" action="#"><input type="search" placeholder="Search the documentation" name="q"><button type="submit">Search</button></form>'
+            '<div class="c-header__user">Signed in as <b>documentation reader</b></div></div>'
+            '<div class="c-cookie is-visible" role="dialog"><p>This documentation portal stores a single preference cookie so that the sidebar remembers whether it is collapsed. No analytics cookies are set. <a href="27-privacy-and-cookies.html">Read the privacy notice</a>.</p><button class="c-cookie__ok js-hook">OK</button></div></header>')
+
+
+def footer_html(rng):
+    return ('<footer class="c-footer"><div class="c-footer__cols"><div><h4>Documentation</h4><ul><li><a href="01-home.html">Home</a></li><li><a href="03-release-notes.html">Release notes</a></li><li><a href="34-contact-and-support.html">Contact and support</a></li></ul></div>'
+            '<div><h4>Legal</h4><ul><li><a href="27-privacy-and-cookies.html">Privacy and cookies</a></li><li>Fictional Port Authority &mdash; a made-up organisation used for documentation examples</li></ul></div>'
+            '<div><h4>Export</h4><p>Saved as "Webpage, complete". Linked stylesheets, scripts, fonts and images are in the <code>_files</code> folder next to this page.</p></div></div>'
+            '<div class="c-footer__legal">%s All vessel names, agents, terminals and people mentioned anywhere on this site are invented.</div></footer>' % esc(rng.choice(MARKETING)))
+
+
+def site_css(rng):
+    rules = []
+    for cls in CLASS_SOUP + ['c-header', 'c-sidebar', 'c-nav', 'c-footer', 'c-main', 'c-cookie', 'hm-cell', 'c-brand', 'c-search']:
+        rules.append('.%s{margin:%dpx;padding:%dpx;color:#%06x}' % (cls, rng.randint(0, 12), rng.randint(0, 12), rng.randint(0, 0xffffff)))
+        rules.append('.%s:hover{opacity:.%d}' % (cls, rng.randint(5, 9)))
+        rules.append('.%s > .%s{display:block}' % (cls, rng.choice(CLASS_SOUP)))
+    body = ('@font-face{font-family:"HarbourSans";src:url(font-harbour-sans.woff) format("woff")}'
+            'body{font-family:"HarbourSans",system-ui,sans-serif;margin:0;background:#f4f6f8;color:#1f2933}'
+            '.l-shell{display:grid;grid-template-columns:260px 1fr}.c-main{padding:24px 40px;max-width:980px}'
+            'table{border-collapse:collapse;margin:12px 0}td,th{border:1px solid #cfd6dd;padding:6px 10px;vertical-align:top}'
+            'figure{margin:16px 0}figcaption{font-size:.9em;color:#52606d}.active>a{font-weight:bold}\n')
+    return body + '\n'.join(rules) + '\n' + ''.join('.gen-%d{width:%dpx}' % (i, i) for i in range(400))
+
+
+def print_css():
+    return '@media print{.c-sidebar,.c-header,.c-footer,.c-cookie{display:none}.c-main{max-width:none}}\n' + \
+        ''.join('.p-%d{page-break-inside:avoid}' % i for i in range(120))
+
+
+def app_js(rng):
+    names = ['collapse', 'expand', 'toggle', 'search', 'cookie', 'track', 'lazy', 'nav', 'scroll', 'resize']
+    fns = []
+    for n in names:
+        fns.append('function %s_%d(e){var t=this,n=e&&e.target,r=%d;if(!n)return r;for(var i=0;i<r;i++){t=t&&t.parentNode}return t}'
+                   % (n, rng.randint(1, 99), rng.randint(1, 9)))
+    cfg = json.dumps({'portal': 'hbb-docs', 'revision': 7, 'features': {n: rng.random() < .5 for n in names},
+                      'lookup': {'k%03d' % i: rng.randint(0, 99999) for i in range(600)}}, separators=(',', ':'))
+    return ('/*! hbb-docs portal bundle — fictional, no network calls */\n!function(w,d){"use strict";var CFG=' + cfg + ';'
+            + ''.join(fns) + 'w.HBB={cfg:CFG,ready:function(f){d.readyState!=="loading"?f():d.addEventListener("DOMContentLoaded",f)}};'
+            'w.HBB.ready(function(){var c=d.querySelector(".c-cookie__ok");c&&c.addEventListener("click",function(){c.parentNode.className="c-cookie"})})}(window,document);\n')
+
+
+def woff_stub(rng):
+    body = bytes(rng.getrandbits(8) for _ in range(6000))
+    return b'wOFF' + b'\x00\x01\x00\x00' + struct.pack('>I', 44 + len(body)) + b'\x00\x00' * 2 + b'\x00' * 30 + body
+
+
+# ----------------------------------------------------------------------------------------
+# Pages
+# ----------------------------------------------------------------------------------------
+def page_sections(rng, page, key, byid, entities, figures):
+    """Return list of (heading, html) sections for a content page. `figures` is a callback that
+    returns the <figure> html for the n-th figure of the page."""
+    secs = {}
+    order = []
+    chapter = int(page['file'][:2]) - 3  # heading numbers follow the key's sections
+    carried = [byid[i] for i in page.get('carries', []) if i in byid]
+    for it in carried:
+        h = it['section']['heading']
+        if h not in secs:
+            secs[h] = []; order.append(h)
+        secs[h].append(it)
+    # a couple of filler sections so requirement headings are not the only ones
+    for extra in ('%d.0 Introduction' % chapter, '%d.9 Notes' % chapter):
+        if extra not in secs:
+            secs[extra] = []; order.append(extra)
+    order.sort(key=lambda h: [float(x) if x.replace('.', '').isdigit() else 99 for x in h.split(' ')[0].split('.')])
+    out = []
+    fig_n = 0
+    minified_payload = ''
+    for h in order:
+        body = [filler_para(rng)]
+        for it in secs[h]:
+            html_ = render_statement(rng, it, key)
+            if html_ is None:
+                minified_payload += '<p class="hm-note" style="font-size:12px;line-height:1.3;display:block">%s</p>' % esc(it['text'])
+            else:
+                body.append(html_)
+        if rng.random() < 0.5:
+            body.append(filler_para(rng, 2))
+        if rng.random() < 0.5 and fig_n < page['sidecar_images'] - 1:
+            body.append(figures(fig_n)); fig_n += 1
+        out.append((h, ''.join(body)))
+    # entity tables
+    for name in page.get('entities', []):
+        ent = entities[name]
+        out.append(('Data: %s' % name, filler_para(rng, 1) + entity_table(rng, ent)))
+    if page.get('entities'):
+        assocs = [a for a in key['associations'] if a['from'] in page['entities'] or a['to'] in page['entities']]
+        if assocs:
+            out.append(('Relationships', para(rng, [assoc_sentence(a) for a in assocs])))
+    return out, fig_n, minified_payload
+
+
+def chrome_sections(rng, page, figures):
+    out = []
+    title = page['title']
+    if 'release' in page['file']:
+        for rev, items in CHANGELOG:
+            lis = ''.join('<li>%s</li>' % esc(i) for i in items)
+            out.append((rev, '<ul>%s</ul>' % lis))
+    elif 'privacy' in page['file']:
+        out.append(('Cookies', para(rng, ["The portal stores one preference cookie for the sidebar state.", "No analytics or advertising cookies are used.", "Cookies can be cleared through the browser at any time."])))
+        out.append(('Personal data', para(rng, ["The documentation export contains no personal data.", "Names of people appearing in examples are invented."])))
+    elif 'contact' in page['file']:
+        out.append(('Support', para(rng, ["Documentation feedback is collected through the feedback form of the original portal, which is not available in this offline export.", "For the purposes of this fixture there is nobody to contact."])))
+        out.append(('Office hours', '<table><tr><th>Day</th><th>Hours</th></tr>' + ''.join('<tr><td>%s</td><td>09:00 - 17:00</td></tr>' % d for d in ('Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday')) + '</table>'))
+    elif 'news' in page['file']:
+        for i in range(6):
+            out.append(('News item %d' % (i + 1), para(rng, rng.sample(MARKETING, 2) + rng.sample(FILLER, 1)) + (figures(i) if i < page['sidecar_images'] else '')))
+    elif 'about' in page['file']:
+        out.append(('Who we are', para(rng, MARKETING[:3])))
+        out.append(('The port', para(rng, MARKETING[4:6])))
+    else:
+        out.append(('Welcome', para(rng, MARKETING[:2]) + figures(0)))
+        out.append(('How to read this documentation', para(rng, MARKETING[2:4])))
+        out.append(('Latest revision', para(rng, MARKETING[5:7])))
+    return out
+
+
+def make_figure(rng, page_dir, fig_index, rel, is_jpeg, caption, image_bytes_fn):
+    fname = 'img-%02d.%s' % (fig_index + 1, 'jpg' if is_jpeg else 'png')
+    return fname, ('<figure class="%s"><img src="%s/%s" alt="Figure %d (photo)" width="%d"><figcaption>Figure %d: %s</figcaption></figure>'
+                   % (soup(rng, 2), rel, fname, fig_index + 1, 480, fig_index + 1, esc(caption)))
+
+
+def generate(out_dir, seed, key, write_manifest=True):
+    rng = random.Random(seed)
+    os.makedirs(out_dir, exist_ok=True)
+    pages = key['corpus']['pages']
+    byid = {x['id']: x for x in key['requirements'] + key['business_rules']}
+    entities = {e['name']: e for e in key['entities']}
+    shots = {s['page']: s for s in key['screenshot_only']}
+    manifest = {'seed': seed, 'app': key['app'], 'generated_by': 'gen-corpus.py', 'files': [], 'pages': [],
+                'placements': {}, 'chrome_pages': [p['file'] for p in pages if p['chrome']], 'screenshot_only': [], 'markdown': []}
+
+    def add_file(path, data, kind):
+        full = os.path.join(out_dir, path)
+        os.makedirs(os.path.dirname(full), exist_ok=True)
+        with open(full, 'wb') as f:
+            f.write(data)
+        manifest['files'].append({'path': path, 'bytes': len(data), 'kind': kind})
+
+    captions = ["Container terminal at dawn (stock illustration)", "Quay wall and mooring bollards", "Bulk carrier alongside",
+                "Crane row at the north terminal", "Harbour entrance and breakwater", "Cruise berth, off season",
+                "Inspection launch at the pontoon", "Signal mast", "Tug basin", "Shore power cabinet",
+                "RoRo ramp", "Customs office at the south terminal"]
+
+    for page in pages:
+        prng = random.Random('%s:%s' % (seed, page['file']))
+        rel = page['file'][:-5] + '_files'
+        n_side = page['sidecar_images']
+        figure_html = {}
+        page_imgs = []
+        shot = shots.get(page['file'])
+        shot_side_index = None
+        if shot and shot['mode'] == 'sidecar':
+            shot_side_index = n_side - 1  # the last sidecar image is the screenshot
+        for i in range(n_side):
+            irng = random.Random('%s:%s:img%d' % (seed, page['file'], i))
+            if shot_side_index == i:
+                fname = os.path.basename(shot['image'])
+                c = mock_screen(irng, shot['screen'].upper(),
+                                [('VESSEL', 'MV NORTHERN GANNET'), ('IMO NUMBER', '123456'), ('BERTH', 'B07 NORTH TERMINAL'),
+                                 ('ETA', '14-03 08:00'), ('ETD', '16-03 18:00'), ('CARGO CLASS', 'GENERAL')],
+                                message=shot['text'], message_after='IMO NUMBER', marker_field='IMO NUMBER')
+                data = png_bytes(c)
+                add_file('%s/%s' % (rel, fname), data, 'image-screenshot')
+                figure_html[i] = ('<figure class="%s" id="fig-validation"><img src="%s/%s" alt="Figure %d (screenshot)" width="640">'
+                                  '<figcaption>Figure %d: the booking request form in the prototype.</figcaption></figure>'
+                                  % (soup(prng, 2), rel, fname, i + 1, i + 1))
+                manifest['screenshot_only'].append({'id': shot['id'], 'file': '%s/%s' % (rel, fname), 'page': page['file'], 'mode': 'sidecar'})
+                page_imgs.append(fname)
+                continue
+            is_jpeg = (i == 0) or (i == 3 and n_side >= 6)
+            if is_jpeg:
+                w, h = 256, 176
+                c = scene(irng, w, h, noise_amp=10)
+                data = jpeg_bytes(w, h, c.gray(), quality=irng.choice([60, 75, 85]))
+            else:
+                w, h = irng.choice([(320, 220), (360, 240), (400, 260)])
+                c = scene(irng, w, h, noise_amp=irng.choice([4, 6, 8]), noise_every=1)
+                data = png_bytes(c)
+            fname, fhtml = make_figure(prng, rel, i, rel, is_jpeg, captions[i % len(captions)], None)
+            add_file('%s/%s' % (rel, fname), data, 'image')
+            figure_html[i] = fhtml
+            page_imgs.append(fname)
+
+        def figures(n, figure_html=figure_html):
+            return figure_html.get(n, '')
+
+        # inline screenshots
+        inline_figs = []
+        for j in range(page.get('inline_screenshots', 0)):
+            irng = random.Random('%s:%s:inline%d' % (seed, page['file'], j))
+            if shot and shot['mode'] == 'inline' and j == 0:
+                c = mock_screen(irng, shot['screen'].upper(),
+                                [('REQUEST', 'HB-2031-00417'), ('VESSEL', 'MV GREY PETREL'), ('OUTCOME', 'REJECTED'), ('REASON', '')],
+                                message=shot["text"], message_after="REASON", marker_field="REASON", noise_amp=4, noise_every=2)
+                fid = 'fig-review-decision'
+                cap = 'the decision panel of the officer review screen (prototype).'
+                manifest['screenshot_only'].append({'id': shot['id'], 'file': page['file'], 'page': page['file'], 'mode': 'inline', 'element_id': fid})
+            else:
+                titles = {'08': 'BOOKING LIFECYCLE', '11': 'AGENT REGISTRATION', '14': 'VESSEL RECORD', '20': 'INVOICE',
+                          '23': 'INSPECTION CHECKLIST', '28': 'NAVIGATION', '29': 'BOOKING BOARD', '30': 'MY BOOKINGS'}
+                t = titles.get(page['file'][:2], page['title'].upper())
+                fields = [('REFERENCE', 'HB-2031-00%03d' % irng.randint(100, 999)), ('VESSEL', 'MV ' + irng.choice(['SILVER TERN', 'BLUE SKUA', 'RED KNOT', 'GREY PETREL'])),
+                          ('STATUS', irng.choice(['DRAFT', 'SUBMITTED', 'UNDER REVIEW', 'APPROVED'])), ('TERMINAL', irng.choice(['NORTH', 'SOUTH', 'EAST']))]
+                c = mock_screen(irng, t, fields, noise_amp=irng.choice([3, 4]), noise_every=2)
+                fid = 'fig-inline-%d' % (j + 1)
+                cap = 'prototype mock-up of the %s screen.' % page['title'].lower()
+            data = png_bytes(c)
+            b64 = base64.b64encode(data).decode('ascii')
+            inline_figs.append('<figure class="%s" id="%s"><img src="data:image/png;base64,%s" alt="Figure (screenshot)" width="640"><figcaption>Figure: %s</figcaption></figure>'
+                               % (soup(prng, 2), fid, b64, esc(cap)))
+            manifest['files'].append({'path': '%s#%s' % (page['file'], fid), 'bytes': len(data), 'kind': 'image-inline-base64'})
+
+        # sections
+        if page['chrome']:
+            secs = chrome_sections(prng, page, figures)
+            used_figs = min(len(secs), n_side)
+            minified_payload = ''
+        else:
+            secs, used_figs, minified_payload = page_sections(prng, page, key, byid, entities, figures)
+        # unused sidecar figures go into a gallery at the end so every image is referenced
+        gallery = ''.join(figure_html[i] for i in range(n_side) if i >= used_figs and (shot_side_index != i))
+        if shot_side_index is not None and shot_side_index >= used_figs:
+            # the screenshot figure sits under its own section, not in the gallery
+            secs.append(('Figure: booking form validation', filler_para(prng, 1) + figure_html[shot_side_index]))
+        if gallery:
+            secs.append(('Gallery', '<div class="c-gallery %s">%s</div>' % (soup(prng, 2), gallery)))
+        if inline_figs:
+            insert_at = min(1, len(secs))
+            secs.insert(insert_at, ('Prototype screens', filler_para(prng, 1) + ''.join(inline_figs)))
+
+        body_secs = []
+        for h, html_ in secs:
+            sid = 's-' + ''.join(ch if ch.isalnum() else '-' for ch in h.lower())
+            body_secs.append(wrap_div(prng, '<section id="%s" class="%s"><h2>%s</h2>%s</section>' % (sid, soup(prng, 2), esc(h), html_), prng.randint(1, 2)))
+        minified = ''
+        if page.get('minified'):
+            minified = '\n' + minified_line(prng, minified_payload, target_bytes=prng.randint(22000, 40000)) + '\n'
+        elif minified_payload:
+            raise RuntimeError('minified requirement on a page without a minified block: ' + page['file'])
+
+        head = ('<!DOCTYPE html>\n<!-- saved from url=(0061)https://docs.harbour-berth-booking.invalid/portal/%s -->\n'
+                '<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width"><title>%s &middot; Harbour Berth Booking documentation</title>\n'
+                '<link rel="stylesheet" href="%s/site.css"><link rel="stylesheet" href="%s/print.css" media="print">\n'
+                '<style>%s</style>\n<script src="%s/app.js" defer></script>\n</head>\n'
+                % (page['file'], esc(page['title']), rel, rel, ''.join('.inl-%d{padding:%dpx}' % (i, i % 7) for i in range(150)), rel))
+        meta = '<div class="c-meta">Revision 7 &middot; chapter %s &middot; %s</div>' % (page['file'][:2], 'reference only' if page['chrome'] else 'functional description')
+        body = ('<body class="docs-body theme-harbour %s">\n<div id="app"><div class="l-shell">\n%s\n%s\n<main class="c-main %s"><article class="c-article">\n<h1>%s</h1>\n%s\n%s%s\n</article></main>\n%s\n</div></div>\n</body></html>\n'
+                % (soup(prng, 2), header_html(), sidebar(pages, page['file']), soup(prng, 2), esc(page['title']), meta,
+                   '\n'.join(body_secs), minified, footer_html(prng)))
+        html_doc = (head + body).encode('utf-8')
+        add_file(page['file'], html_doc, 'html')
+        # sidecar support files
+        add_file('%s/site.css' % rel, site_css(prng).encode(), 'css')
+        if prng.random() < 0.6:
+            add_file('%s/print.css' % rel, print_css().encode(), 'css')
+        add_file('%s/app.js' % rel, app_js(prng).encode(), 'js')
+        add_file('%s/font-harbour-sans.woff' % rel, woff_stub(prng), 'font')
+        manifest['pages'].append({'file': page['file'], 'title': page['title'], 'chrome': page['chrome'], 'sidecar_images': n_side,
+                                  'inline_screenshots': page.get('inline_screenshots', 0), 'minified': bool(page.get('minified')),
+                                  'carries': page.get('carries', []), 'entities': page.get('entities', []), 'bytes': len(html_doc)})
+        for i in page.get('carries', []):
+            it = byid.get(i)
+            if it:
+                manifest['placements'][i] = {'file': page['file'], 'heading': it['section']['heading'], 'form': it.get('form', 'prose'),
+                                             'negative': bool(it.get('negative'))}
+            else:
+                manifest['placements'][i] = {'file': page['file'], 'form': 'screenshot', 'mode': shots[page['file']]['mode']}
+
+    # ---- markdown files ----
+    mrng = random.Random('%s:md' % seed)
+    gl = ['# Glossary\n', '\nTerms used across the Harbour Berth Booking documentation. Fictional throughout.\n\n', '| Term | Definition |\n|---|---|\n']
+    defs = {
+        'Vessel': 'A ship known to the registry; identified by IMO number, with name, length overall, beam, draught, flag state, vessel type and gross tonnage.',
+        'ShippingAgent': 'A licensed agency acting for vessels; company name, licence number, contact e-mail, phone, suspension flag and credit limit.',
+        'Terminal': 'A part of the port with its own berths; code, name, operating hours and whether it has a customs office.',
+        'Berth': 'A mooring place at a terminal; code, name, maximum length, maximum draught, shore power flag, status.',
+        'BookingRequest': 'A request by an agent to use a berth for a vessel between ETA and ETD; has a reference, status, cargo class, shore power request, submission time and remarks.',
+        'ApprovalDecision': 'The recorded outcome of an officer review: decided on, outcome, reason, officer name, override flag.',
+        'Tariff': 'A rate card per terminal: code, description, rate per metre per day, currency, valid from/to, surcharge percent.',
+        'Invoice': 'The bill for a completed booking: invoice number, issued on, due on, total amount, VAT percent, status.',
+        'Inspection': 'A scheduled visit by an inspector: scheduled for, completed on, outcome, inspector name, findings, follow-up flag.',
+        'InspectionItem': 'One line of an inspection checklist: category, description, compliant flag, severity, note.',
+        'AuditEntry': 'One line of the audit trail: occurred on, actor, action, entity name, detail.',
+        'ETA / ETD': 'Estimated time of arrival / departure.', 'LOA': 'Length overall of a vessel, in metres.',
+        'Shore power': 'Electrical supply from the quay so a moored vessel can switch off its generators.',
+    }
+    for t, d in defs.items():
+        gl.append('| %s | %s |\n' % (t, d))
+    add_file('glossary.md', ''.join(gl).encode(), 'markdown')
+
+    roles_md = ['# Roles and permissions\n\n', 'The application distinguishes the following user roles.\n\n', '| Role | Who | What they do |\n|---|---|---|\n']
+    for r in key['roles']:
+        roles_md.append('| %s | %s | %s |\n' % (r['label'], r['name'], r['description']))
+    roles_md.append('\nEvery user has exactly one role. Role names are shown in the header of every screen.\n')
+    add_file('roles.md', ''.join(roles_md).encode(), 'markdown')
+
+    adrs = [
+        ('ADR-001', 'Documentation lives in the portal', 'All functional documentation is published through the documentation portal and exported for offline review.'),
+        ('ADR-002', 'Chapters are numbered once', 'Heading numbers are allocated by the master table of contents and never re-used.'),
+        ('ADR-003', 'Fictional example data', 'All examples use invented vessel names, agents and people.'),
+        ('ADR-004', 'Booking references are permanent', byid['R048']['text'] + ' A cancelled request keeps its reference for the audit trail.'),
+        ('ADR-005', 'Screenshots come from the prototype', 'Figures are exported from the clickable prototype, not drawn by hand.'),
+        ('ADR-006', 'Invoice due dates', byid['B009']['text'] + ' This was agreed with the finance team in the third workshop.'),
+        ('ADR-007', 'Workshop notes are kept verbatim', 'Workshop notes are stored as written during the session; clean-up happens in the chapters.'),
+        ('ADR-008', 'Release notes per revision', 'Every published revision gets a release notes entry.'),
+    ]
+    md = ['# Decisions log\n\n', 'Architecture-decision-record style. One entry per decision, newest last.\n\n']
+    for aid, title, text in adrs:
+        md.append('## %s — %s\n\n**Status:** accepted\n\n**Decision:** %s\n\n**Consequences:** %s\n\n' % (aid, title, text, mrng.choice(FILLER)))
+    add_file('decisions-log.md', ''.join(md).encode(), 'markdown')
+
+    ws = ['# Workshop notes\n\n', 'Raw notes, three sessions. Not cleaned up (see ADR-007).\n\n',
+          '## Session 1 — scope\n\n- Attendees: operations, documentation, two agents (fictional)\n- Walked through the chapter list\n- Coffee at 10:30\n- Parking lot: none\n\n',
+          '## Session 2 — agents\n\n- Agents like the draft feature\n- %s\n- Question about attachments size limit: not decided\n- Agents want the e-mail notifications to include the reference\n\n' % byid['R046']['text'],
+          '## Session 3 — officers\n\n- Officers want the queue sorted by ETA (already in the chapter)\n- %s\n- Discussed colours of the exceedance highlight; red is fine\n- Follow-up: none\n' % byid['R047']['text']]
+    add_file('workshop-notes.md', ''.join(ws).encode(), 'markdown')
+    for m in key['corpus']['markdown']:
+        for i in m.get('carries', []):
+            if i in byid:
+                manifest['placements'][i] = {'file': m['file'], 'heading': byid[i]['section']['heading'], 'form': byid[i].get('form', 'prose')}
+        manifest['markdown'].append(m)
+
+    total = sum(f['bytes'] for f in manifest['files'] if f['kind'] != 'image-inline-base64')
+    manifest['totals'] = {'files': sum(1 for f in manifest['files'] if f['kind'] != 'image-inline-base64'), 'bytes': total,
+                          'html_pages': len(pages), 'chrome_pages': len(manifest['chrome_pages']),
+                          'sidecar_images': sum(1 for f in manifest['files'] if f['kind'].startswith('image') and f['kind'] != 'image-inline-base64'),
+                          'inline_screenshots': sum(1 for f in manifest['files'] if f['kind'] == 'image-inline-base64'),
+                          'requirements': len(key['requirements']), 'business_rules': len(key['business_rules']),
+                          'screenshot_only': len(key['screenshot_only']), 'contradictions': len(key['contradictions'])}
+    if write_manifest:
+        with open(os.path.join(out_dir, 'MANIFEST.json'), 'w') as f:
+            json.dump(manifest, f, indent=2)
+    return manifest
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(description=__doc__.split('\n')[0])
+    ap.add_argument('out_dir')
+    ap.add_argument('--seed', type=int, default=20260909)
+    ap.add_argument('--key', default=os.path.join(HERE, 'answer-key.json'))
+    ap.add_argument('--no-manifest', action='store_true', help='do not write MANIFEST.json (what the agents under test get)')
+    a = ap.parse_args(argv)
+    with open(a.key, encoding='utf-8') as f:
+        key = json.load(f)
+    m = generate(a.out_dir, a.seed, key, write_manifest=not a.no_manifest)
+    t = m['totals']
+    print('corpus: %s — %d files, %.1f MB, %d HTML pages (%d chrome), %d sidecar images, %d inline screenshots; %d requirements, %d rules, %d screenshot-only, %d contradictions%s'
+          % (a.out_dir, t['files'], t['bytes'] / 1e6, t['html_pages'], t['chrome_pages'], t['sidecar_images'], t['inline_screenshots'],
+             t['requirements'], t['business_rules'], t['screenshot_only'], t['contradictions'],
+             '' if a.no_manifest else ' — MANIFEST.json written (do NOT give it to the agents under test)'))
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())
diff --git a/tests/ab/score.py b/tests/ab/score.py
new file mode 100644
index 0000000..e1645dd
--- /dev/null
+++ b/tests/ab/score.py
@@ -0,0 +1,868 @@
+#!/usr/bin/env python3
+"""score.py — score a toolkit project (after Stages 0-2 on the synthetic corpus) against answer-key.json.
+
+    score.py <project-dir> --key answer-key.json [--json] [--toolkit DIR] [--brd-dir DIR]
+                           [--manifest MANIFEST.json] [--include-analysis] [--no-run]
+    score.py --self-test [--key answer-key.json] [--keep]
+
+What it reads (the toolkit's own conventions, nothing invented):
+  * BRDs — `*.brd.json` under any of <project>/analysis/*/knowledge-base/brd,
+    <project>/analysis/knowledge-base/brd, <project>/knowledge-base/brd (bin/lib/discover-brds.sh),
+    or --brd-dir.
+  * PROJECT.md — the decision register: Decisions and Open questions tables, "## Current stage".
+  * analysis/sme-questions.md, analysis/triage.md.
+  * bin/source-ledger.sh check --json, when the toolkit can be found (--toolkit, $MXTK_TOOLKIT,
+    the "Toolkit root" row of CLAUDE.local.md, this file's grandparent, ~/Mendix/mxcli-project-toolkit).
+  * bin/gate-check.sh <project> 1 and 2 (same discovery), plus docs/BUILD-LOG.md and .claude/ receipts.
+
+Metrics: requirement recall/precision (fuzzy: stemmed keyword overlap >= 0.6 of the key statement's
+tokens, or an explicit id cite such as "R012", or a page-file cite with overlap >= 0.5; negation-aware), entity and
+attribute recall, association recall, business-rule recall (a rule counts only when its
+`must_contain` thresholds/states are present), contradictions surfaced as questions/decisions (0-3),
+screenshot-only requirements found (0-2), phantom claims, ledger verdict counts, gate status.
+
+Python 3 standard library only.
+"""
+import argparse
+import glob
+import importlib.util
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+
+# ----------------------------------------------------------------------------------------
+# text normalisation
+# ----------------------------------------------------------------------------------------
+STOP = set("""a an the and or of to in on at for by with from as is are be been being was were it its this that these those
+there their they them then than which who whom whose what when where while into onto over under up down out off
+do does did done can could may might must shall should will would has have had having also any all each per via
+so such if else about after before during until whenever whether one's own same other another more most very
+i you he she we us our your his her""".split())
+NEG = {'not', 'no', 'never', 'cannot', 'only', 'without'}
+STOP -= NEG
+NUMWORDS = {'zero': '0', 'one': '1', 'two': '2', 'three': '3', 'four': '4', 'five': '5', 'six': '6', 'seven': '7',
+            'eight': '8', 'nine': '9', 'ten': '10', 'eleven': '11', 'twelve': '12', 'twenty': '20', 'thirty': '30',
+            'fifty': '50', 'ninety': '90', 'hundred': '100'}
+SUFFIXES = ['ations', 'ation', 'ising', 'izing', 'ness', 'ments', 'ment', 'ings', 'ing', 'ions', 'ion', 'ies', 'ied',
+            'ers', 'er', 'ed', 'es', 'al', 'ly', 's', 'e']
+TOKEN_RE = re.compile(r'\d+(?:\.\d+)?|[a-z]+')
+SYNONYMS = {'draft': 'draught', 'auto': 'automatic', 'harbourmaster': 'harbour', 'e': 'email'}
+
+
+def stem(w):
+    if w in NUMWORDS:
+        return NUMWORDS[w]
+    if w[0].isdigit():
+        return w
+    w = SYNONYMS.get(w, w)
+    for suf in SUFFIXES:
+        if w.endswith(suf) and len(w) - len(suf) >= 3:
+            if suf == 's' and (w.endswith('ss') or w.endswith('us')):
+                break
+            w = w[:-len(suf)]
+            break
+    if len(w) >= 4 and w[-1] == w[-2] and w[-1] not in 'aeiou':
+        w = w[:-1]
+    return w
+
+
+def tokens(text):
+    out = set()
+    for t in TOKEN_RE.findall(text.lower()):
+        if t in STOP or (len(t) == 1 and not t.isdigit()):
+            continue
+        out.add(stem(t))
+    return out
+
+
+NEG_MARKERS = NEG | {'manual', 'manually'}
+
+
+def overlap(key_tokens, cand_tokens):
+    """Share of the key statement's tokens present in the candidate. Negation-aware: a key statement
+    that carries a negation (no / not / never / cannot / only / without) is capped below the match
+    threshold unless the candidate carries one too (or says 'manual') — otherwise 'there is NO automatic
+    approval' matches its positive near-twin 'officers review every request'."""
+    if not key_tokens:
+        return 0.0
+    ov = len(key_tokens & cand_tokens) / len(key_tokens)
+    if (key_tokens & NEG_MARKERS) and not (cand_tokens & NEG_MARKERS):
+        ov = min(ov, 0.59)
+    return ov
+
+
+def has_must(text, must_contain):
+    """Every group present; a group is 'a|b' alternatives; numbers must be whole tokens."""
+    low = ' ' + re.sub(r'[^a-z0-9.%]+', ' ', text.lower()) + ' '
+    for group in must_contain or []:
+        ok = False
+        for alt in group.split('|'):
+            alt = alt.strip().lower()
+            if not alt:
+                continue
+            if alt[0].isdigit():
+                if re.search(r'(?<![0-9.])' + re.escape(alt) + r'(?![0-9])', low):
+                    ok = True; break
+            elif alt in low:
+                ok = True; break
+        if not ok:
+            return False
+    return True
+
+
+# ----------------------------------------------------------------------------------------
+# harvesting the project
+# ----------------------------------------------------------------------------------------
+CLAIM_KEYS = {'requirements', 'functionalrequirements', 'businessrules', 'rules', 'validations', 'hiddenrules',
+              'nonfunctionalrequirements', 'constraints', 'acceptancecriteria'}
+TEXT_FIELDS = ('text', 'statement', 'description', 'rule', 'requirement', 'title', 'name', 'question', 'summary', 'purpose')
+CITE_FIELDS = ('source', 'sources', 'sourceref', 'sourcerefs', 'section', 'sections', 'page', 'pages', 'heading', 'ref',
+               'refs', 'reference', 'references', 'sourcekb', 'evidence', 'origin', 'citation', 'id', 'sourceid')
+
+
+def discover_brds(project, brd_dir=None):
+    if brd_dir:
+        return sorted(glob.glob(os.path.join(brd_dir, '*.brd.json')))
+    out = []
+    for pat in ('analysis/*/knowledge-base/brd', 'analysis/knowledge-base/brd', 'knowledge-base/brd'):
+        for d in sorted(glob.glob(os.path.join(project, pat))):
+            out += sorted(glob.glob(os.path.join(d, '*.brd.json')))
+    return out
+
+
+class Statement:
+    __slots__ = ('text', 'cite', 'file', 'path', 'kind', 'toks')
+
+    def __init__(self, text, cite, file, path, kind):
+        self.text = text; self.cite = cite; self.file = file; self.path = path; self.kind = kind
+        self.toks = tokens(text)
+
+    def where(self):
+        return '%s:%s' % (os.path.basename(self.file), self.path)
+
+
+def _obj_text(o):
+    if isinstance(o, str):
+        return o, ''
+    if isinstance(o, dict):
+        parts = [str(o[k]) for k in TEXT_FIELDS if k in o and isinstance(o[k], (str, int, float))]
+        cite = ' '.join(str(o[k]) for k in o if k.lower() in CITE_FIELDS and isinstance(o[k], (str, int, float, list)))
+        return ' '.join(parts), cite
+    return '', ''
+
+
+def harvest_brd(path):
+    with open(path, encoding='utf-8') as f:
+        doc = json.load(f)
+    stmts = []
+
+    def walk(node, jpath, under_claim, parent_cite):
+        if isinstance(node, dict):
+            cite = ' '.join(str(node[k]) for k in node if k.lower() in CITE_FIELDS and isinstance(node[k], (str, int, float, list)))
+            cite = (parent_cite + ' ' + cite).strip()
+            for k, v in node.items():
+                kl = k.lower()
+                claim_here = under_claim or kl in CLAIM_KEYS
+                if isinstance(v, str):
+                    if len(v.strip()) < 8:
+                        continue
+                    kind = 'claim' if (kl in CLAIM_KEYS or (under_claim and kl in TEXT_FIELDS) or (re.search(r'usecases\[\d+\]$', jpath.lower()) and kl == 'title')) else 'context'
+                    stmts.append(Statement(v, cite, path, '%s.%s' % (jpath, k) if jpath else k, kind))
+                elif isinstance(v, (list, dict)):
+                    walk(v, '%s.%s' % (jpath, k) if jpath else k, claim_here, cite)
+        elif isinstance(node, list):
+            for i, v in enumerate(node):
+                if isinstance(v, str):
+                    if len(v.strip()) < 8:
+                        continue
+                    stmts.append(Statement(v, parent_cite, path, '%s[%d]' % (jpath, i), 'claim' if under_claim else 'context'))
+                else:
+                    walk(v, '%s[%d]' % (jpath, i), under_claim, parent_cite)
+    walk(doc, '', False, '')
+    # an object inside a claim array becomes ONE claim (text fields joined) so a {id, text, source} row
+    # is scored once, not per field
+    merged = []
+    seen = set()
+    for s in stmts:
+        if s.kind == 'claim' and s.path.endswith(']') is False and '[' in s.path:
+            base = s.path.rsplit('.', 1)[0]
+            if base in seen:
+                continue
+            seen.add(base)
+            sib = [t for t in stmts if t.kind == 'claim' and t.path.rsplit('.', 1)[0] == base]
+            if len(sib) > 1:
+                text = ' '.join(t.text for t in sib)
+                cite = ' '.join(t.cite for t in sib)
+                merged.append(Statement(text, cite, s.file, base, 'claim'))
+                continue
+        merged.append(s)
+    return doc, merged
+
+
+def md_table_rows(text):
+    rows = []
+    for line in text.splitlines():
+        if line.startswith('|') and not re.match(r'^\|\s*-', line) and not re.match(r'^\|\s*(#|Stage|Decision)\s*\|', line):
+            cells = [c.strip() for c in line.strip('|').split('|')]
+            rows.append(' | '.join(cells))
+    return rows
+
+
+def read(path):
+    try:
+        with open(path, encoding='utf-8', errors='replace') as f:
+            return f.read()
+    except OSError:
+        return ''
+
+
+def find_toolkit(project, explicit=None):
+    cands = []
+    if explicit:
+        cands.append(explicit)
+    if os.environ.get('MXTK_TOOLKIT'):
+        cands.append(os.environ['MXTK_TOOLKIT'])
+    loc = read(os.path.join(project, 'CLAUDE.local.md'))
+    m = re.search(r'^\|\s*Toolkit root\s*\|\s*`?([^`|]+)`?\s*\|', loc, re.M)
+    if m:
+        cands.append(os.path.expanduser(m.group(1).strip()))
+    cands.append(os.path.abspath(os.path.join(HERE, '..', '..')))
+    cands.append(os.path.abspath(os.path.join(HERE, '..')))
+    cands.append(os.path.expanduser('~/Mendix/mxcli-project-toolkit'))
+    for c in cands:
+        if os.path.isfile(os.path.join(c, 'bin', 'source-ledger.sh')) and os.path.isfile(os.path.join(c, 'bin', 'gate-check.sh')):
+            return c
+    return None
+
+
+def ledger_from_run_report(project):
+    """Read the verdict the RUN ITSELF recorded, from analysis/source-ledger.html.
+
+    Re-running `source-ledger.sh check` against a handed-in project is wrong: the hand-in
+    excludes sources/, so the checker sees an empty source root and reports 0 extracted /
+    FAIL for a run whose ledger actually passed. Measured 2026-09-09 — all three A/B arms
+    were reported FAIL this way while their own reports said PASS (a1 41 extracted + 159
+    waived, b1 and c1 200 extracted). The run's own report is the only honest record.
+    """
+    rep = os.path.join(project, 'analysis', 'source-ledger.html')
+    if not os.path.isfile(rep):
+        return None
+    try:
+        raw = open(rep, encoding='utf-8', errors='replace').read()
+    except OSError:
+        return None
+    import html as _html
+    txt = _html.unescape(re.sub(r'\s+', ' ', re.sub(r'<[^>]+>', ' ', raw)))
+    counts = {}
+    for kw in ('inventoried', 'extracted', 'waived', 'sensitive', 'superseded', 'pending', 'fault'):
+        m = re.search(r'(\d+)\s+' + kw, txt)
+        if m:
+            counts['total' if kw == 'inventoried' else kw] = int(m.group(1))
+    m = re.search(r'Source ledger:\s*(PASS|FAIL|BLOCKED)', txt, re.I)
+    status = m.group(1).upper() if m else ('FAIL' if counts.get('pending') or counts.get('fault') else 'PASS')
+    return {'ran': True, 'source': 'run report (analysis/source-ledger.html)',
+            'status': status, 'counts': counts, 'rows': []}
+
+
+def run_ledger(toolkit, project):
+    own = ledger_from_run_report(project)
+    if own is not None:
+        return own
+    if not os.path.isdir(os.path.join(project, 'sources')) and not os.path.isdir(os.path.join(project, 'source')):
+        return {'ran': False, 'error': 'no source root in the hand-in and no analysis/source-ledger.html to read'}
+    try:
+        r = subprocess.run(['bash', os.path.join(toolkit, 'bin', 'source-ledger.sh'), 'check', project, '--json'],
+                           capture_output=True, text=True, timeout=300)
+    except (OSError, subprocess.TimeoutExpired) as e:
+        return {'ran': False, 'error': str(e)}
+    out = r.stdout.strip()
+    try:
+        start = out.index('{')
+        doc = json.loads(out[start:])
+    except (ValueError, json.JSONDecodeError):
+        return {'ran': True, 'exit': r.returncode, 'error': 'no JSON on stdout', 'stdout_tail': out[-400:], 'stderr_tail': r.stderr[-400:]}
+    doc['ran'] = True
+    doc['exit'] = r.returncode
+    return doc
+
+
+def run_gate(toolkit, project, stage):
+    try:
+        r = subprocess.run(['bash', os.path.join(toolkit, 'bin', 'gate-check.sh'), project, str(stage)],
+                           capture_output=True, text=True, timeout=300)
+    except (OSError, subprocess.TimeoutExpired) as e:
+        return {'ran': False, 'error': str(e)}
+    text = (r.stdout + '\n' + r.stderr)
+    # the stage's own line looks like "Stage 1 (Analysis): PENDING · Surface MISSING: ..." — everything
+    # else in the output (obligations, artifacts, ledger rows) carries its own verdict word and is noise here
+    m = re.search(r'^Stage %d \(([^)]*)\):\s*(PASS|FAIL|PENDING|WAIVED|MANUAL|BLOCKED|ADOPTED)\b(.*)$' % stage, text, re.M)
+    ledger = re.search(r'^(Source ledger|LEDGER)[^\n]*$', text, re.M | re.I)
+    return {'ran': True, 'exit': r.returncode, 'verdict': m.group(2) if m else 'UNPARSED',
+            'stage_name': m.group(1) if m else '', 'detail': (m.group(3).strip(' ·—-') if m else '')[:200],
+            'ledger_line': ledger.group(0)[:200] if ledger else ''}
+
+
+# ----------------------------------------------------------------------------------------
+# scoring
+# ----------------------------------------------------------------------------------------
+def best_match(key_text, key_id, stmts, section=None, must_contain=None):
+    kt = tokens(key_text)
+    best = (0.0, None, 'none')
+    id_re = re.compile(r'(?<![A-Za-z0-9])' + re.escape(key_id) + r'(?![A-Za-z0-9])') if key_id else None
+    page = (section or {}).get('file', '')
+    page_stem = page.rsplit('.', 1)[0] if page else None
+    for s in stmts:
+        if must_contain and not has_must(s.text, must_contain):
+            continue
+        ov = overlap(kt, s.toks)
+        how = 'overlap'
+        if id_re and (id_re.search(s.text) or id_re.search(s.cite)):
+            ov = max(ov, 1.0); how = 'id-cite'
+        elif page_stem and ov >= 0.5 and (page_stem in s.cite or page_stem in s.text):
+            ov = max(ov, 0.6); how = 'section-cite'   # page cited AND half the key tokens present
+        if ov > best[0]:
+            best = (ov, s, how)
+    return best
+
+
+def norm_name(n):
+    return re.sub(r'[^a-z0-9]', '', str(n).lower())
+
+
+def score_project(project, key, brd_dir=None, toolkit=None, manifest=None, include_analysis=False, no_run=False):
+    res = {'project': os.path.abspath(project)}
+    brd_files = discover_brds(project, brd_dir)
+    res['brd_files'] = [os.path.relpath(b, project) for b in brd_files]
+    stmts = []
+    brds = []
+    for b in brd_files:
+        try:
+            doc, st = harvest_brd(b)
+        except (OSError, json.JSONDecodeError) as e:
+            res.setdefault('brd_errors', []).append('%s: %s' % (os.path.relpath(b, project), e))
+            continue
+        brds.append(doc); stmts += st
+
+    # register / questions
+    reg = read(os.path.join(project, 'PROJECT.md'))
+    reg_rows = md_table_rows(reg)
+    sme = read(os.path.join(project, 'analysis', 'sme-questions.md')) + ''.join(read(p) for p in glob.glob(os.path.join(project, 'analysis', '*', 'sme-questions.md')))
+    triage = read(os.path.join(project, 'analysis', 'triage.md'))
+    question_texts = list(reg_rows)
+    question_texts += [l for l in sme.splitlines() if l.strip()]
+    for s in stmts:
+        if 'openquestions' in s.path.lower() or 'opengaps' in s.path.lower() or 'gaps' in s.path.lower():
+            question_texts.append(s.text + ' ' + s.cite)
+    for p in glob.glob(os.path.join(project, 'analysis', '**', '*.md'), recursive=True):
+        for l in read(p).splitlines():
+            if re.search(r'contradict|conflict|inconsisten|disagree|ambigu', l, re.I):
+                question_texts.append(l)
+    # merge BRD openQuestions objects into one text each (question + answer + notes)
+    for doc in brds:
+        for q in doc.get('openQuestions', []) or []:
+            if isinstance(q, dict):
+                question_texts.append(' '.join(str(v) for v in q.values() if isinstance(v, (str, int, float))))
+
+    extra = []
+    if include_analysis:
+        for p in glob.glob(os.path.join(project, 'analysis', '**', '*.md'), recursive=True):
+            for i, l in enumerate(read(p).splitlines()):
+                if len(l.strip()) >= 12:
+                    extra.append(Statement(l, '', p, 'L%d' % (i + 1), 'context'))
+    pool = stmts + extra
+
+    # --- requirements ---
+    req_rows = []
+    hit = 0
+    for r in key['requirements']:
+        ov, s, how = best_match(r['text'], r['id'], pool, r.get('section'))
+        matched = ov >= 0.6
+        hit += matched
+        req_rows.append({'id': r['id'], 'matched': matched, 'score': round(ov, 2), 'how': how if matched else '',
+                         'where': s.where() if s else '', 'candidate': (s.text[:110] if s else ''), 'page': r['section']['file']})
+    res['requirements'] = {'total': len(key['requirements']), 'found': hit, 'recall': round(hit / len(key['requirements']), 3), 'rows': req_rows}
+
+    # --- business rules ---
+    rule_rows = []
+    rhit = 0
+    for b in key['business_rules']:
+        ov, s, how = best_match(b['text'], b['id'], pool, b.get('section'), must_contain=b.get('must_contain'))
+        ov_loose, s2, _ = best_match(b['text'], b['id'], pool, b.get('section'))
+        matched = ov >= 0.6
+        rhit += matched
+        rule_rows.append({'id': b['id'], 'matched': matched, 'score': round(ov, 2), 'how': how if matched else '',
+                          'where': s.where() if s else '', 'candidate': (s.text[:110] if s else ''),
+                          'note': ('' if matched or ov_loose < 0.6 else 'statement found but threshold/state (%s) missing' % ', '.join(b['must_contain']))})
+    res['business_rules'] = {'total': len(key['business_rules']), 'found': rhit, 'recall': round(rhit / len(key['business_rules']), 3), 'rows': rule_rows}
+
+    # --- screenshot-only ---
+    shot_rows = []
+    shits = 0
+    all_lines = [s.text for s in pool] + reg_rows + question_texts + [l for l in triage.splitlines()]
+    for sh in key['screenshot_only']:
+        found = None
+        kt = tokens(sh['text'])
+        for t in all_lines:
+            if has_must(t, sh['must_contain']) and overlap(kt, tokens(t)) >= 0.6:
+                found = t[:110]; break
+        shits += bool(found)
+        shot_rows.append({'id': sh['id'], 'found': bool(found), 'evidence': found or '', 'image': sh['image'], 'mode': sh['mode']})
+    res['screenshot_only'] = {'total': len(key['screenshot_only']), 'found': shits, 'rows': shot_rows}
+
+    # --- contradictions ---
+    con_rows = []
+    chits = 0
+    for c in key['contradictions']:
+        ids = c['requirements']
+        ev = None
+        for t in question_texts:
+            low = t.lower()
+            both = all(re.search(r'(?<![A-Za-z0-9])' + re.escape(i) + r'(?![A-Za-z0-9])', t) for i in ids)
+            terms = all(any(term.lower() in low for term in group) for group in c['detect_terms'])
+            if both or terms:
+                ev = t[:140]; break
+        chits += bool(ev)
+        con_rows.append({'id': c['id'], 'surfaced': bool(ev), 'evidence': ev or '', 'requirements': ids, 'pages': c['pages']})
+    res['contradictions'] = {'total': len(key['contradictions']), 'surfaced': chits, 'rows': con_rows}
+
+    # --- phantoms / precision ---
+    key_pool = [(r['id'], r['text']) for r in key['requirements']] + [(b['id'], b['text']) for b in key['business_rules']] + \
+               [(s['id'], s['text']) for s in key['screenshot_only']]
+    key_toks = [(i, tokens(t)) for i, t in key_pool]
+    claims = [s for s in stmts if s.kind == 'claim']
+    phantoms = []
+    grounded = 0
+    for s in claims:
+        best = 0.0; bid = None
+        for i, kt in key_toks:
+            ov = overlap(kt, s.toks)
+            if ov > best:
+                best, bid = ov, i
+            if re.search(r'(?<![A-Za-z0-9])' + re.escape(i) + r'(?![A-Za-z0-9])', s.text + ' ' + s.cite):
+                best, bid = 1.0, i
+        if best >= 0.5:
+            grounded += 1
+        else:
+            phantoms.append({'where': s.where(), 'text': s.text[:110], 'best': round(best, 2), 'nearest': bid})
+    res['claims'] = {'total': len(claims), 'grounded': grounded, 'phantoms': len(phantoms),
+                     'precision': (round(grounded / len(claims), 3) if claims else None), 'phantom_rows': phantoms[:40]}
+
+    # --- entities / attributes / associations ---
+    brd_entities = []
+    for doc in brds:
+        for e in doc.get('domainEntities', []) or []:
+            if not isinstance(e, dict) or not e.get('name'):
+                continue
+            attrs = [a.get('name') if isinstance(a, dict) else a for a in (e.get('attributes') or [])]
+            brd_entities.append({'name': e['name'], 'attrs': [norm_name(a) for a in attrs if a],
+                                 'assocs': [(a.get('target') or a.get('to') or '') for a in (e.get('associations') or []) if isinstance(a, dict)]})
+    ent_rows = []
+    ehit = 0; attr_total = 0; attr_hit = 0
+    used = set()
+    for ke in key['entities']:
+        kn = norm_name(ke['name'])
+        cand = None
+        for be in brd_entities:
+            if id(be) in used:
+                continue
+            bn = norm_name(be['name'])
+            if bn == kn:
+                cand = be; break
+        if cand is None:
+            for be in brd_entities:
+                bn = norm_name(be['name'])
+                if id(be) not in used and len(bn) >= 4 and (kn.endswith(bn) or (bn.endswith(kn) and len(kn) >= 5)):
+                    cand = be; break
+        found_attrs = []
+        missing = []
+        for a in ke['attributes']:
+            attr_total += 1
+            an = norm_name(a['name'])
+            ok = cand is not None and any(an == x or (len(x) >= 3 and (an.startswith(x) or x.startswith(an) or an.endswith(x))) for x in cand['attrs'])
+            attr_hit += ok
+            (found_attrs if ok else missing).append(a['name'])
+        if cand:
+            used.add(id(cand)); ehit += 1
+        ent_rows.append({'entity': ke['name'], 'matched': cand['name'] if cand else '', 'attributes_total': len(ke['attributes']),
+                         'attributes_found': len(found_attrs), 'missing_attributes': missing})
+    # associations: unordered entity pairs
+    key_pairs = {frozenset((norm_name(a['from']), norm_name(a['to']))) for a in key['associations']}
+    brd_pairs = set()
+    for be in brd_entities:
+        for t in be['assocs']:
+            t = str(t).split('.')[-1]
+            if t:
+                brd_pairs.add(frozenset((norm_name(be['name']), norm_name(t))))
+    for doc in brds:
+        for a in doc.get('associations', []) or []:
+            if isinstance(a, dict):
+                f = str(a.get('from') or a.get('owner') or a.get('source') or '').split('.')[-1]
+                t = str(a.get('to') or a.get('target') or '').split('.')[-1]
+                if f and t:
+                    brd_pairs.add(frozenset((norm_name(f), norm_name(t))))
+    ahit = sum(1 for p in key_pairs if p in brd_pairs)
+    res['entities'] = {'total': len(key['entities']), 'found': ehit, 'recall': round(ehit / len(key['entities']), 3),
+                       'brd_entities': len(brd_entities), 'attributes_total': attr_total, 'attributes_found': attr_hit,
+                       'attribute_recall': round(attr_hit / attr_total, 3) if attr_total else None,
+                       'associations_total': len(key_pairs), 'associations_found': ahit,
+                       'association_recall': round(ahit / len(key_pairs), 3), 'rows': ent_rows}
+
+    # --- roles & screens (cheap presence check over BRD actors/pages + register) ---
+    blob = ' '.join(s.text for s in stmts).lower() + ' '.join(str(doc.get('actors', '')) for doc in brds).lower()
+    res['roles'] = {'total': len(key['roles']), 'found': sum(1 for r in key['roles'] if r['label'].lower() in blob or norm_name(r['name']) in norm_name(blob))}
+    res['screens'] = {'total': len(key['screens']), 'found': sum(1 for s in key['screens'] if s['label'].lower() in blob or norm_name(s['name']) in norm_name(blob))}
+
+    # --- stage artifacts, ledger, gates ---
+    res['artifacts'] = {'triage.md': bool(triage.strip()), 'PROJECT.md': bool(reg.strip()),
+                        'sme-questions.md': bool(sme.strip()), 'brd_count': len(brd_files)}
+    tk = None if no_run else find_toolkit(project, toolkit)
+    res['toolkit'] = tk
+    ledger = run_ledger(tk, project) if tk else {'ran': False, 'error': 'toolkit not found (pass --toolkit)'}
+    lsum = {'ran': ledger.get('ran', False), 'status': ledger.get('status'), 'note': ledger.get('note') or ledger.get('error'),
+            'counts': ledger.get('counts', {})}
+    rows = ledger.get('rows', []) or []
+    if rows:
+        chrome = set(key['corpus'].get('pages') and [p['file'] for p in key['corpus']['pages'] if p['chrome']])
+        by_kind = {'chrome_pages': {}, 'content_pages': {}, 'sidecar_images': {}, 'sidecar_support': {}, 'markdown': {}, 'other': {}}
+        shot_rel = os.path.basename(key['screenshot_only'][0]['image'])
+        shot_verdict = None
+        for r in rows:
+            rel = r.get('rel', '')
+            base = os.path.basename(rel)
+            v = r.get('verdict', '?')
+            if base == shot_rel:
+                shot_verdict = v
+            if base in chrome:
+                k = 'chrome_pages'
+            elif base.endswith('.html'):
+                k = 'content_pages'
+            elif '_files/' in rel and base.lower().endswith(('.png', '.jpg', '.jpeg')):
+                k = 'sidecar_images'
+            elif '_files/' in rel:
+                k = 'sidecar_support'
+            elif base.endswith('.md'):
+                k = 'markdown'
+            else:
+                k = 'other'
+            by_kind[k][v] = by_kind[k].get(v, 0) + 1
+        lsum['by_kind'] = by_kind
+        lsum['screenshot_image_verdict'] = shot_verdict
+        if manifest:
+            try:
+                mf = json.load(open(manifest))
+                lsum['manifest_files'] = mf['totals']['files']
+                lsum['inventoried_rows'] = len(rows)
+            except (OSError, KeyError, json.JSONDecodeError):
+                pass
+    res['ledger'] = lsum
+
+    gates = {}
+    m = re.search(r'^## Current stage\s*\n+(.+)$', reg, re.M)
+    gates['register_current_stage'] = m.group(1).strip() if m else ''
+    gates['register_lines'] = [l.strip() for l in reg.splitlines() if re.match(r'^\s*(Adopted at stage|Waived stage|Waived artifact|Waived source)\b', l, re.I)][:20]
+    bl = read(os.path.join(project, 'docs', 'BUILD-LOG.md'))
+    gates['build_log_stage_lines'] = [l.strip()[:120] for l in bl.splitlines() if re.search(r'\bStage [012]\b', l)][:10]
+    gates['claude_receipts'] = sorted(os.path.basename(p) for p in glob.glob(os.path.join(project, '.claude', '.*')) + glob.glob(os.path.join(project, '.claude', '*')) if os.path.isfile(p))
+    gates['gate_check'] = {str(s): run_gate(tk, project, s) for s in (1, 2)} if tk else {'ran': False}
+    res['gates'] = gates
+    return res
+
+
+# ----------------------------------------------------------------------------------------
+# rendering
+# ----------------------------------------------------------------------------------------
+def pct(x):
+    return '—' if x is None else '%.0f%%' % (100 * x)
+
+
+def render_md(res):
+    L = []
+    L.append('# Score — %s' % res['project'])
+    L.append('')
+    L.append('BRDs read: %d (%s)' % (len(res['brd_files']), ', '.join(res['brd_files']) or 'none'))
+    if res.get('brd_errors'):
+        L.append('BRD errors: ' + '; '.join(res['brd_errors']))
+    L.append('')
+    r, b, e, c, s, sh = res['requirements'], res['business_rules'], res['entities'], res['claims'], res['contradictions'], res['screenshot_only']
+    L.append('| Metric | Value | Detail |')
+    L.append('|---|---|---|')
+    L.append('| Requirement recall | %s | %d / %d |' % (pct(r['recall']), r['found'], r['total']))
+    L.append('| Requirement precision | %s | %d grounded of %d claims, %d phantom |' % (pct(c['precision']), c['grounded'], c['total'], c['phantoms']))
+    L.append('| Business-rule recall | %s | %d / %d (threshold/state required) |' % (pct(b['recall']), b['found'], b['total']))
+    L.append('| Entity recall | %s | %d / %d (%d BRD entities) |' % (pct(e['recall']), e['found'], e['total'], e['brd_entities']))
+    L.append('| Attribute recall | %s | %d / %d |' % (pct(e['attribute_recall']), e['attributes_found'], e['attributes_total']))
+    L.append('| Association recall | %s | %d / %d |' % (pct(e['association_recall']), e['associations_found'], e['associations_total']))
+    L.append('| Contradictions surfaced | %d / %d | as open questions or decisions |' % (s['surfaced'], s['total']))
+    L.append('| Screenshot-only requirements found | %d / %d | |' % (sh['found'], sh['total']))
+    L.append('| Roles / screens named | %d / %d, %d / %d | |' % (res['roles']['found'], res['roles']['total'], res['screens']['found'], res['screens']['total']))
+    lg = res['ledger']
+    if lg.get('ran') and lg.get('counts'):
+        cn = lg['counts']
+        L.append('| Source ledger | %s | %s |' % (lg.get('status'), ', '.join('%s=%s' % (k, cn[k]) for k in ('total', 'extracted', 'waived', 'pending', 'fault', 'drift') if k in cn)))
+    else:
+        L.append('| Source ledger | not run | %s |' % (lg.get('note') or ''))
+    g = res['gates']
+    gc = g.get('gate_check', {})
+    if gc.get('1'):
+        L.append('| Gate check | stage 1: %s; stage 2: %s | register: %s |' % (gc['1'].get('verdict', gc['1'].get('error')), gc['2'].get('verdict', gc['2'].get('error')), g['register_current_stage']))
+    else:
+        L.append('| Gate check | not run | register: %s |' % g['register_current_stage'])
+    L.append('')
+    L.append('## Requirements')
+    L.append('')
+    L.append('| Id | Page | Found | Score | How | Where | Nearest BRD statement |')
+    L.append('|---|---|---|---|---|---|---|')
+    for row in r['rows']:
+        L.append('| %s | %s | %s | %.2f | %s | %s | %s |' % (row['id'], row['page'], 'yes' if row['matched'] else 'NO', row['score'], row['how'], row['where'], row['candidate'].replace('|', '/')))
+    L.append('')
+    L.append('## Business rules')
+    L.append('')
+    L.append('| Id | Found | Score | Where | Nearest | Note |')
+    L.append('|---|---|---|---|---|---|')
+    for row in b['rows']:
+        L.append('| %s | %s | %.2f | %s | %s | %s |' % (row['id'], 'yes' if row['matched'] else 'NO', row['score'], row['where'], row['candidate'].replace('|', '/'), row['note']))
+    L.append('')
+    L.append('## Entities')
+    L.append('')
+    L.append('| Key entity | BRD entity | Attributes found | Missing |')
+    L.append('|---|---|---|---|')
+    for row in e['rows']:
+        L.append('| %s | %s | %d / %d | %s |' % (row['entity'], row['matched'] or '—', row['attributes_found'], row['attributes_total'], ', '.join(row['missing_attributes'])))
+    L.append('')
+    L.append('## Contradictions')
+    L.append('')
+    for row in s['rows']:
+        L.append('- %s (%s on %s): %s%s' % (row['id'], ' vs '.join(row['requirements']), ' / '.join(row['pages']), 'SURFACED' if row['surfaced'] else 'not surfaced', (' — "%s"' % row['evidence'].replace('|', '/')) if row['evidence'] else ''))
+    L.append('')
+    L.append('## Screenshot-only requirements')
+    L.append('')
+    for row in sh['rows']:
+        L.append('- %s (%s, %s): %s%s' % (row['id'], row['mode'], row['image'], 'FOUND' if row['found'] else 'not found', (' — "%s"' % row['evidence']) if row['evidence'] else ''))
+    if lg.get('screenshot_image_verdict'):
+        L.append('- ledger verdict on the sidecar screenshot image: %s' % lg['screenshot_image_verdict'])
+    L.append('')
+    if c['phantom_rows']:
+        L.append('## Phantom claims (BRD statements matching nothing in the key; first %d)' % len(c['phantom_rows']))
+        L.append('')
+        for p in c['phantom_rows']:
+            L.append('- %s — "%s" (best %.2f vs %s)' % (p['where'], p['text'].replace('|', '/'), p['best'], p['nearest']))
+        L.append('')
+    if lg.get('by_kind'):
+        L.append('## Ledger by file kind')
+        L.append('')
+        L.append('| Kind | Verdicts |')
+        L.append('|---|---|')
+        for k, v in lg['by_kind'].items():
+            if v:
+                L.append('| %s | %s |' % (k, ', '.join('%s=%d' % kv for kv in sorted(v.items()))))
+        if 'manifest_files' in lg:
+            L.append('')
+            L.append('Manifest says %d files; ledger inventoried %d rows.' % (lg['manifest_files'], lg['inventoried_rows']))
+        L.append('')
+    L.append('## Gates')
+    L.append('')
+    L.append('- Register "Current stage": %s' % (g['register_current_stage'] or '(none)'))
+    if g['register_lines']:
+        L.append('- Register waiver/adoption lines: ' + '; '.join(g['register_lines']))
+    if g['build_log_stage_lines']:
+        L.append('- BUILD-LOG stage lines: ' + '; '.join(g['build_log_stage_lines']))
+    if g['claude_receipts']:
+        L.append('- .claude receipts: ' + ', '.join(g['claude_receipts']))
+    for st in ('1', '2'):
+        if gc.get(st) and gc[st].get('ran'):
+            L.append('- gate-check %s (%s): %s — %s' % (st, gc[st]['stage_name'], gc[st]['verdict'], gc[st]['detail'].replace('|', '/')))
+            if gc[st].get('ledger_line'):
+                L.append('  - %s' % gc[st]['ledger_line'].replace('|', '/'))
+    return '\n'.join(L) + '\n'
+
+
+# ----------------------------------------------------------------------------------------
+# self-test
+# ----------------------------------------------------------------------------------------
+def fabricate_brds(key, brd_dir, fraction=1.0, phantoms=0, contradictions=True, screenshots=True):
+    os.makedirs(brd_dir, exist_ok=True)
+    reqs = key['requirements']; rules = key['business_rules']; ents = key['entities']
+    n_req = int(round(len(reqs) * fraction)); n_rule = int(round(len(rules) * fraction)); n_ent = int(round(len(ents) * fraction))
+    reqs = reqs[:n_req]; rules = rules[:n_rule]; ents = ents[:n_ent]
+    ent_names = {e['name'] for e in ents}
+    chunks = [reqs[i::4] for i in range(4)]
+    rule_chunks = [rules[i::4] for i in range(4)]
+    ent_chunks = [ents[i::4] for i in range(4)]
+    phantom_texts = ['The portal shows a weather widget for the harbour entrance.', 'Users can choose between a light and a dark colour theme.',
+                     'A tug is dispatched automatically for vessels over 300 metres.', 'The application supports Dutch and German user interfaces.',
+                     'Bookings can be paid by credit card at submission time.', 'The system prints a boarding pass for the pilot.']
+    files = []
+    for i in range(4):
+        brd = {'id': 'F%03d' % (i + 1), 'title': 'Harbour Berth Booking part %d' % (i + 1), 'modules': ['HarbourBerthBooking'],
+               'actors': [r['label'] for r in key['roles']], 'provenance': 'documents',
+               'useCases': [{'id': 'UC%03d' % (j + 1), 'title': r['text'], 'actors': ['Shipping Agent'], 'preconditions': [], 'postconditions': [],
+                             'mainFlow': ['1. See ' + r['section']['file'] + ' ' + r['section']['heading']], 'screens': [s['label'] for s in key['screens']], 'mdlRefs': [],
+                             'source': r['section']['file'] + ' #' + r['section']['heading']} for j, r in enumerate(chunks[i])],
+               'businessRules': [{'id': b['id'], 'text': b['text'], 'source': b['section']['file']} for b in rule_chunks[i]],
+               'domainEntities': [{'name': e['name'], 'module': 'HarbourBerthBooking', 'persistent': True,
+                                   'attributes': [{'name': a['name'], 'type': a['type'].split('(')[0], 'mandatory': a['required']} for a in e['attributes']],
+                                   'associations': [{'name': a['name'], 'target': a['to'], 'type': a['type'], 'owner': a['from']} for a in key['associations'] if a['from'] == e['name'] and a['to'] in ent_names]}
+                                  for e in ent_chunks[i]],
+               'microflows': [], 'pages': [], 'integrations': [], 'openQuestions': [], 'sourceKB': ['workshop-notes.md']}
+        if i == 0 and phantoms:
+            brd['businessRules'] += [{'id': 'X%03d' % k, 'text': t} for k, t in enumerate(phantom_texts[:phantoms])]
+        if i == 1 and screenshots:
+            brd['microflows'].append({'name': 'VAL_BookingRequest', 'module': 'HarbourBerthBooking', 'purpose': 'form validation',
+                                      'validations': [s['text'] for s in key['screenshot_only']]})
+        if i == 2 and contradictions:
+            brd['openQuestions'] = [{'id': 'D%d' % k, 'question': 'Contradiction between %s and %s: %s' % (c['requirements'][0], c['requirements'][1], c['summary']),
+                                     'status': 'RAISED', 'raisedAtGate': 'Stage 2 gate'} for k, c in enumerate(key['contradictions'])]
+        p = os.path.join(brd_dir, '%s-part-%d.brd.json' % (brd['id'], i + 1))
+        with open(p, 'w') as f:
+            json.dump(brd, f, indent=2)
+        files.append(p)
+    return files
+
+
+def self_test(key_path, keep=False):
+    spec = importlib.util.spec_from_file_location('gen_corpus', os.path.join(HERE, 'gen-corpus.py'))
+    gen = importlib.util.module_from_spec(spec); spec.loader.exec_module(gen)
+    with open(key_path, encoding='utf-8') as f:
+        key = json.load(f)
+    tmp = tempfile.mkdtemp(prefix='ab-fixture-selftest-')
+    failures = []
+
+    def check(cond, msg):
+        print(('  ok   ' if cond else '  FAIL ') + msg)
+        if not cond:
+            failures.append(msg)
+    try:
+        corpus = os.path.join(tmp, 'corpus')
+        m = gen.generate(corpus, 7, key, write_manifest=True)
+        t = m['totals']
+        print('self-test: corpus generated in %s — %d files, %.1f MB' % (corpus, t['files'], t['bytes'] / 1e6))
+        check(8e6 <= t['bytes'] <= 20e6, 'corpus size within 8-20 MB (%.1f MB)' % (t['bytes'] / 1e6))
+        check(t['html_pages'] == 36 and t['chrome_pages'] == 6, '36 HTML pages incl. 6 chrome')
+        leak = []
+        for p in glob.glob(os.path.join(corpus, '**', '*'), recursive=True):
+            if os.path.isfile(p) and p.endswith(('.html', '.md', '.css', '.js')):
+                low = read(p).lower()
+                for s in key['screenshot_only']:
+                    if s['text'].lower() in low:
+                        leak.append((s['id'], os.path.basename(p)))
+        check(not leak, 'screenshot-only text appears in no text file (%s)' % (leak or 'clean'))
+        byid = {x['id']: x for x in key['requirements'] + key['business_rules']}
+        missing = [i for i, x in byid.items() if x['text'] not in read(os.path.join(corpus, x['section']['file']))]
+        check(not missing, 'every key statement is on its page (%s)' % (missing or 'all placed'))
+        big = [p['file'] for p in m['pages'] if p['minified']]
+        ok_min = all(max(len(l) for l in read(os.path.join(corpus, f)).splitlines()) > 20000 for f in big)
+        check(ok_min and len(big) >= 6, '%d pages carry a one-line block > 20 KB' % len(big))
+
+        # perfect project
+        proj = os.path.join(tmp, 'perfect')
+        os.makedirs(os.path.join(proj, 'analysis'), exist_ok=True)
+        fabricate_brds(key, os.path.join(proj, 'analysis', 'knowledge-base', 'brd'))
+        with open(os.path.join(proj, 'PROJECT.md'), 'w') as f:
+            f.write('# PROJECT.md\n\n## Current stage\n\n**Stage 2 — complete (self-test)**\n\n## Decisions\n\n| Stage | Decision | Status | Notes |\n|---|---|---|---|\n\n## Open questions\n\n| # | Question | Raised at | Status |\n|---|---|---|---|\n')
+        with open(os.path.join(proj, 'analysis', 'triage.md'), 'w') as f:
+            f.write('# Source Triage: self-test\n')
+        res = score_project(proj, key, no_run=True)
+        print(render_md(res).split('\n## Requirements')[0])
+        check(res['requirements']['recall'] == 1.0, 'perfect set: requirement recall 1.0 (%s)' % res['requirements']['recall'])
+        check(res['claims']['precision'] == 1.0, 'perfect set: precision 1.0 (%s)' % res['claims']['precision'])
+        check(res['business_rules']['recall'] == 1.0, 'perfect set: rule recall 1.0 (%s)' % res['business_rules']['recall'])
+        check(res['entities']['recall'] == 1.0 and res['entities']['attribute_recall'] == 1.0, 'perfect set: entity + attribute recall 1.0')
+        check(res['entities']['association_recall'] == 1.0, 'perfect set: association recall 1.0 (%s)' % res['entities']['association_recall'])
+        check(res['contradictions']['surfaced'] == 3, 'perfect set: 3 contradictions surfaced')
+        check(res['screenshot_only']['found'] == 2, 'perfect set: 2 screenshot-only requirements found')
+
+        # half project (+3 phantoms, no contradictions raised)
+        proj2 = os.path.join(tmp, 'half')
+        os.makedirs(os.path.join(proj2, 'analysis'), exist_ok=True)
+        fabricate_brds(key, os.path.join(proj2, 'analysis', 'knowledge-base', 'brd'), fraction=0.5, phantoms=3, contradictions=False, screenshots=False)
+        res2 = score_project(proj2, key, no_run=True)
+        print(render_md(res2).split('\n## Requirements')[0])
+        check(0.4 <= res2['requirements']['recall'] <= 0.6, 'half set: requirement recall ~0.5 (%s)' % res2['requirements']['recall'])
+        check(0.4 <= res2['business_rules']['recall'] <= 0.6, 'half set: rule recall ~0.5 (%s)' % res2['business_rules']['recall'])
+        check(0.4 <= res2['entities']['recall'] <= 0.6, 'half set: entity recall ~0.5 (%s)' % res2['entities']['recall'])
+        check(res2['claims']['phantoms'] == 3, 'half set: exactly the 3 planted phantoms counted (%d)' % res2['claims']['phantoms'])
+        check(res2['contradictions']['surfaced'] == 0 and res2['screenshot_only']['found'] == 0, 'half set: 0 contradictions, 0 screenshot-only')
+
+        # paraphrase robustness: rules with thresholds reworded, and one with the threshold dropped
+        proj3 = os.path.join(tmp, 'para')
+        bd = os.path.join(proj3, 'analysis', 'knowledge-base', 'brd'); os.makedirs(bd)
+        para = {'id': 'F001', 'modules': ['X'], 'provenance': 'documents', 'useCases': [
+            {'id': 'UC1', 'title': 'Suspend an agent automatically once it has 3 overdue invoices'},
+            {'id': 'UC2', 'title': 'Add VAT to every berth fee'},
+            {'id': 'UC3', 'title': 'Cancelling is free of charge up to 24h before the ETA (see 10-cancellation-and-changes)'},
+            {'id': 'UC4', 'title': 'Vessels arriving > 2 hours late pay a 15 percent surcharge on the berth fee'}]}
+        json.dump(para, open(os.path.join(bd, 'F001.brd.json'), 'w'))
+        res3 = score_project(proj3, key, no_run=True)
+        rr = {r['id']: r for r in res3['business_rules']['rows']}
+        check(rr['B004']['matched'], 'paraphrase: B004 (three->3, reworded) matched (%s)' % rr['B004']['score'])
+        check(not rr['B010']['matched'] and 'threshold' in rr['B010']['note'], 'paraphrase: B010 without its 21% threshold is NOT counted')
+        check(rr['B008']['matched'], 'paraphrase: B008 reworded with both thresholds matched (%s)' % rr['B008']['score'])
+        r14 = {r['id']: r for r in res3['requirements']['rows']}['R014']
+        check(r14['matched'], 'paraphrase: R014 reworded matched (%s via %s)' % (r14['score'], r14['how']))
+
+        # empty project
+        proj4 = os.path.join(tmp, 'empty'); os.makedirs(proj4)
+        res4 = score_project(proj4, key, no_run=True)
+        check(res4['requirements']['recall'] == 0.0 and res4['claims']['precision'] is None, 'empty project: recall 0, precision n/a')
+
+        # ledger integration, only if the toolkit is reachable
+        tk = find_toolkit(proj)
+        if tk:
+            src = os.path.join(proj, 'sources', 'portal')
+            shutil.copytree(corpus, src)
+            os.remove(os.path.join(src, 'MANIFEST.json'))
+            r = subprocess.run(['bash', os.path.join(tk, 'bin', 'source-sufficiency.sh'), 'init', proj], capture_output=True, text=True, timeout=300)
+            lg = run_ledger(tk, proj)
+            cn = lg.get('counts', {})
+            print('  ledger via %s: %s' % (tk, lg.get('note')))
+            check(lg.get('ran') and cn.get('total', 0) >= t['files'] - 1, 'ledger inventoried the whole corpus (%s rows vs %d files)' % (cn.get('total'), t['files'] - 1))
+            check(cn.get('pending', 0) == cn.get('total', 0), 'fresh inventory: every row PENDING (nobody extracted anything yet)')
+        else:
+            print('  skip ledger integration (toolkit not found; set MXTK_TOOLKIT to run it)')
+    finally:
+        if keep:
+            print('kept', tmp)
+        else:
+            shutil.rmtree(tmp, ignore_errors=True)
+    if failures:
+        print('SELF-TEST FAILED: %d assertion(s)' % len(failures))
+        return 1
+    print('SELF-TEST PASSED')
+    return 0
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(description=__doc__.split('\n')[0])
+    ap.add_argument('project', nargs='?')
+    ap.add_argument('--key', default=os.path.join(HERE, 'answer-key.json'))
+    ap.add_argument('--json', action='store_true')
+    ap.add_argument('--toolkit', help='toolkit root (for source-ledger.sh / gate-check.sh)')
+    ap.add_argument('--brd-dir', help='override BRD discovery')
+    ap.add_argument('--manifest', help='MANIFEST.json of the corpus the project was run on (ledger cross-check)')
+    ap.add_argument('--include-analysis', action='store_true', help='also match against analysis/**/*.md lines (recall only)')
+    ap.add_argument('--no-run', action='store_true', help='do not run the toolkit scripts')
+    ap.add_argument('--self-test', action='store_true')
+    ap.add_argument('--keep', action='store_true', help='self-test: keep the temp dir')
+    a = ap.parse_args(argv)
+    if a.self_test:
+        return self_test(a.key, keep=a.keep)
+    if not a.project:
+        ap.error('project dir required (or --self-test)')
+    with open(a.key, encoding='utf-8') as f:
+        key = json.load(f)
+    res = score_project(a.project, key, brd_dir=a.brd_dir, toolkit=a.toolkit, manifest=a.manifest, include_analysis=a.include_analysis, no_run=a.no_run)
+    if a.json:
+        print(json.dumps(res, indent=2))
+    else:
+        print(render_md(res))
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())
diff --git a/tests/wave2/fixtures/html-to-md/CAPTURE.md b/tests/wave2/fixtures/html-to-md/CAPTURE.md
new file mode 100644
index 0000000..783d8be
--- /dev/null
+++ b/tests/wave2/fixtures/html-to-md/CAPTURE.md
@@ -0,0 +1,27 @@
+# Fixture provenance — html-to-md
+
+**This page is synthetic.** `Fleet Portal Requirements.html` and its `_files/` sidecar were written
+by hand on 2026-09-09 in the SHAPE of a browser "Save page as… (complete)" export of a wiki page —
+the shape the requirements-driven project that motivated `bin/html-to-md.sh` had hundreds of.
+The real exports are a client's requirements and cannot be committed; nothing here was copied
+from them.
+
+Why a synthetic page is acceptable here, when CLAUDE.md says golden input is captured, never
+hand-written: the rule guards parsers of TOOL output, whose real columns nobody imagines. A saved
+webpage has no tool contract — every wiki writes different markup — so there is no single
+"real output" to capture, and the instrument's job is exactly to survive whatever markup shows
+up. What this fixture pins is the STRUCTURAL facts observed on the real exports, each one put
+here because the converter has to get it right:
+
+| Fact reproduced | Why the converter depends on it |
+|---|---|
+| `<!-- saved from url=… -->` comment, `<title>`, `<link>` to `./<Page>_files/site.css`, `<script src>` | the sidecar folder is named `<page stem>_files/` and its css/js are chrome of that page, not content |
+| a `<header role=banner>` holding a `<nav>`, a `div.sidebar`, a `div.breadcrumbs`, a `div.cookie-banner`, a `<footer role=contentinfo>` | each is a chrome region that must be dropped; every one carries a `*SENTINEL-n` token the fixture asserts is absent |
+| inline `<style>` and two `<script>` blocks, a `<noscript>`, an `<svg>` | dropped whole; each carries a sentinel |
+| `<main role=main>` wrapping `div.content-wrapper` → `div.wiki-content` with inline styles | the content lives three wrapper divs deep; nothing about a wrapper's class may drop it (`toc-macro` wraps a real `<h2>`) |
+| h1 → h2 → h3 outline, a nested `<ul>`, an `<ol>`, a `<table>` with `<thead>/<tbody>/<colgroup>`, a `<pre>`, `<code>`, `<strong>`/`<b>`/`<em>` | the constructs the Markdown must keep, and the section list must number |
+| one `<img>` to the sidecar png and one inline `data:image/png;base64` img | sidecar referenced by its existing path; inline decoded to `<page>_images/01.png` |
+| `glossary.md` beside the page | a Markdown source is listed (role `markdown`), never converted |
+
+The PNG is the well-known 1×1 transparent PNG (70 bytes), used both inline and as the sidecar
+file so the base64-decode path writes a byte-identical, valid image.
diff --git a/tests/wave2/fixtures/html-to-md/Fleet Portal Requirements.html b/tests/wave2/fixtures/html-to-md/Fleet Portal Requirements.html
new file mode 100644
index 0000000..8af168c
--- /dev/null
+++ b/tests/wave2/fixtures/html-to-md/Fleet Portal Requirements.html	
@@ -0,0 +1,74 @@
+<!DOCTYPE html>
+<!-- saved from url=(0052)https://wiki.example.internal/fleet/requirements -->
+<html lang="en"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<title>Fleet Portal — Requirements Overview</title>
+<link rel="stylesheet" href="./Fleet Portal Requirements_files/site.css">
+<style type="text/css">.hidden-style-text{display:none} body{font-family:Segoe UI}</style>
+<script src="./Fleet Portal Requirements_files/app.js"></script>
+<script type="text/javascript">window.__wikiState = {"page": "SCRIPTSENTINEL-9911"};</script>
+</head>
+<body class="wiki-body" style="margin:0;padding:0">
+<div id="page-wrapper" style="display:flex">
+  <header class="site-header" role="banner" style="background:#123"><div class="logo">Acme Wiki</div>
+    <nav class="top-nav"><ul><li><a href="/home">Home</a></li><li><a href="/spaces">Spaces</a></li><li><a href="/search">Search NAVSENTINEL-1</a></li></ul></nav>
+  </header>
+  <div class="sidebar" id="left-sidebar" style="width:220px">
+    <div class="sidebar-title">Fleet space SIDEBARSENTINEL-2</div>
+    <ul class="tree"><li><a href="/fleet/overview">Overview</a></li><li class="current"><a href="/fleet/requirements">Requirements</a></li><li><a href="/fleet/decisions">Decisions</a></li></ul>
+  </div>
+  <div class="breadcrumbs"><a href="/">Wiki</a> › <a href="/fleet">Fleet</a> › Requirements BREADCRUMBSENTINEL-3</div>
+  <main class="page-body" role="main">
+   <div class="content-wrapper" style="padding:16px">
+    <div class="title-block"><h1 id="title-heading" style="font-size:2em">Fleet Portal — Requirements Overview</h1></div>
+    <div class="meta" style="color:#666">Last edited by <span class="author">J. Doe</span> on 2026-08-30 · Version 14</div>
+    <div class="wiki-content" style="line-height:1.5">
+      <p style="margin:0 0 1em">This page lists the <strong>functional requirements</strong> for the <em>Fleet Portal</em>, the replacement for the spreadsheet-based vehicle register. See also <a href="/fleet/decisions">the decision log</a> and <a href="javascript:void(0)">expand all</a>.</p>
+      <div class="toc-macro"><h2 id="scope">1. Scope</h2>
+        <div><p>In scope for the first release:</p>
+          <ul style="margin-left:1em">
+            <li>Vehicle register (create, view, retire)</li>
+            <li>Driver assignment <span style="font-weight:bold">with history</span>
+              <ul><li>one active driver per vehicle</li><li>past assignments kept for 24 months</li></ul></li>
+            <li>Monthly mileage report</li>
+          </ul>
+        </div>
+      </div>
+      <h2 id="entities">2. Entities</h2>
+      <div class="table-wrap" style="overflow:auto">
+      <table class="req-table confluenceTable"><colgroup><col><col><col></colgroup>
+        <thead><tr><th>Entity</th><th>Key attributes</th><th>Notes</th></tr></thead>
+        <tbody>
+          <tr><td><b>Vehicle</b></td><td>LicencePlate (unique), Make, Model, Status</td><td>Status: Active | Retired</td></tr>
+          <tr><td><b>Driver</b></td><td>EmployeeNo (unique), Name, LicenceExpiry</td><td>Expiry drives the alert in §4</td></tr>
+          <tr><td><b>Assignment</b></td><td>Vehicle, Driver, From, To</td><td>To empty = active</td></tr>
+        </tbody>
+      </table>
+      </div>
+      <h2 id="rules">3. Business rules</h2>
+      <ol>
+        <li>A vehicle has at most one active assignment.</li>
+        <li>Retiring a vehicle closes its active assignment with today's date.</li>
+        <li>A driver whose licence expires within 30 days is flagged on every screen that shows them.</li>
+      </ol>
+      <h3 id="rules-example">3.1 Worked example</h3>
+      <pre class="code-block">Vehicle AB-123-C  Active
+  Assignment #41  Driver 1007  2026-01-01 → (open)
+  # retire on 2026-09-01 => Assignment #41.To = 2026-09-01</pre>
+      <h2 id="screens">4. Screens</h2>
+      <p>The vehicle list as it looks today in the spreadsheet:</p>
+      <p><img class="confluence-embedded-image" src="./Fleet Portal Requirements_files/screen-vehicle-list.png" alt="Vehicle list, current spreadsheet" width="640"></p>
+      <p>Sketch of the target screen (pasted into the wiki, so it travels inline):</p>
+      <p><img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==" alt="Target vehicle list sketch"></p>
+      <div class="panel" style="border:1px solid #ccc"><div class="panelContent"><p><code>LicencePlate</code> is validated against <code>^[A-Z]{2}-\d{3}-[A-Z]$</code>.</p></div></div>
+      <h2 id="open">5. Open questions</h2>
+      <ul><li>Who owns the driver master data — HR or Fleet?</li><li>Is the mileage report monthly or on demand?</li></ul>
+    </div>
+   </div>
+  </main>
+  <div class="cookie-banner" id="cookie-consent">We use cookies COOKIESENTINEL-4 <button>OK</button></div>
+</div>
+<footer class="site-footer" role="contentinfo"><p>© Acme Wiki · Powered by WikiSoft FOOTERSENTINEL-5</p></footer>
+<noscript>Please enable JavaScript NOSCRIPTSENTINEL-6</noscript>
+<svg width="10" height="10"><text>SVGSENTINEL-7</text></svg>
+<script>window.__tracking = "SCRIPTSENTINEL-9912";</script>
+</body></html>
diff --git a/tests/wave2/fixtures/html-to-md/Fleet Portal Requirements_files/app.js b/tests/wave2/fixtures/html-to-md/Fleet Portal Requirements_files/app.js
new file mode 100644
index 0000000..5aacf71
--- /dev/null
+++ b/tests/wave2/fixtures/html-to-md/Fleet Portal Requirements_files/app.js	
@@ -0,0 +1,2 @@
+// wiki chrome script — saved with the page
+(function(){document.querySelectorAll('.collapsible').forEach(function(e){e.addEventListener('click',function(){e.classList.toggle('open')})})})();
diff --git a/tests/wave2/fixtures/html-to-md/Fleet Portal Requirements_files/screen-vehicle-list.png b/tests/wave2/fixtures/html-to-md/Fleet Portal Requirements_files/screen-vehicle-list.png
new file mode 100644
index 0000000..613754c
Binary files /dev/null and b/tests/wave2/fixtures/html-to-md/Fleet Portal Requirements_files/screen-vehicle-list.png differ
diff --git a/tests/wave2/fixtures/html-to-md/Fleet Portal Requirements_files/site.css b/tests/wave2/fixtures/html-to-md/Fleet Portal Requirements_files/site.css
new file mode 100644
index 0000000..364ed05
--- /dev/null
+++ b/tests/wave2/fixtures/html-to-md/Fleet Portal Requirements_files/site.css	
@@ -0,0 +1,5 @@
+/* wiki theme — saved with the page */
+.sidebar{width:220px;float:left}
+.page-body{margin-left:240px}
+footer.site-footer{color:#888}
+.req-table td{border:1px solid #ddd;padding:4px}
diff --git a/tests/wave2/fixtures/html-to-md/glossary.md b/tests/wave2/fixtures/html-to-md/glossary.md
new file mode 100644
index 0000000..e4b8738
--- /dev/null
+++ b/tests/wave2/fixtures/html-to-md/glossary.md
@@ -0,0 +1,10 @@
+# Glossary
+
+## Terms
+
+- **Vehicle** — a registered car or van.
+- **Assignment** — a driver–vehicle pairing with a From/To.
+
+## Out of scope
+
+Pool bikes.
diff --git a/tests/wave2/test-bug03-gates.sh b/tests/wave2/test-bug03-gates.sh
index 014c52c..acaeab6 100755
--- a/tests/wave2/test-bug03-gates.sh
+++ b/tests/wave2/test-bug03-gates.sh
@@ -120,6 +120,32 @@ V="$(verdict "$P" 7)"
 case "$V" in *'no cutover decision row'*) ok "empty table reports the absent row, not a bad status" ;;
              *) bad "wrong diagnosis for an empty Decisions table: $V" ;; esac
 
+echo "== T10: a stage run names the runbook lines to read — derived from the headings, not hard-coded =="
+# Added 2026-09-09: the 11,700-word runbook was read whole every session. A stage run must say
+# which span is the stage's own section and which is §1b, and the numbers must be the file's.
+RB="$(cd "$(dirname "$GATE")/.." && pwd)/skills/conversion-runbook.md"
+P="$(mkproj t10)"
+printf '# Validation\n\n## Stop condition\n\nClean.\n' > "$P/knowledge-base/reports/validation-report.md"
+L="$("$GATE" --no-html "$P" 2 2>&1 | grep '^Read for this gate:' | head -1)"
+S2="$(grep -n '^### Stage 2 ' "$RB" | head -1 | cut -d: -f1)"
+S1B="$(grep -n '^## 1b\.' "$RB" | head -1 | cut -d: -f1)"
+case "$L" in
+  'Read for this gate: skills/conversion-runbook.md §"Stage 2 — Requirements" (lines '"$S2"'–'*') + §1b Live Checklist (lines '"$S1B"'–'*)
+    ok "names the Stage 2 section and §1b, each starting at its real heading line ($S2, $S1B)" ;;
+  '') bad "no 'Read for this gate:' line in a stage-2 run" ;;
+  *)  bad "wrong shape or wrong lines: $L" ;;
+esac
+# The span ends where the next heading starts: the line after B must be a ## or ### heading.
+B="$(printf '%s' "$L" | sed -n 's/.*§"Stage 2 — Requirements" (lines [0-9]*–\([0-9]*\)).*/\1/p')"
+NEXT="$(sed -n "$((B + 1))p" "$RB" 2>/dev/null)"
+case "$NEXT" in '## '*|'### '*) ok "the stage span ends right before the next heading ('${NEXT%% —*}')" ;; *) bad "span end $B is not followed by a heading: '$NEXT'" ;; esac
+# build-ready reads Stage 5's section.
+L="$("$GATE" --no-html "$P" build-ready 2>&1 | grep '^Read for this gate:' | head -1)"
+case "$L" in *'§"Stage 5 — Build"'*) ok "build-ready points at Stage 5's section" ;; *) bad "build-ready line: $L" ;; esac
+# A full (no-stage) run prints no such line — there is no single stage to read for.
+N="$("$GATE" --no-html "$P" 2>&1 | grep -c '^Read for this gate:')"
+[ "$N" -eq 0 ] && ok "a whole-project run names no single span" || bad "whole-project run printed a stage span"
+
 printf '\n%s: %d ok, %d FAIL\n' "$(basename "$0")" "$PASS" "$FAIL"
 rm -rf "$WORK"
 [ "$FAIL" -eq 0 ]
diff --git a/tests/wave2/test-bug12-sync.sh b/tests/wave2/test-bug12-sync.sh
index 9900963..4f4f539 100755
--- a/tests/wave2/test-bug12-sync.sh
+++ b/tests/wave2/test-bug12-sync.sh
@@ -24,7 +24,7 @@ WORK="$(mktemp -d /tmp/bug12.XXXXXX)"
 PASS=0; FAIL=0
 
 ok()  { PASS=$((PASS+1)); printf '  ok   %s\n' "$1"; }
-bad() { FAIL=$((FAIL+1)); printf '  FAIL %s\n' "$1"; }
+bad() { FAIL=$((FAIL+1)); printf '  FAIL %s\n' "$1"; [ -n "${2:-}" ] && printf '%s\n' "$2" | sed 's/^/  FAIL-detail: /'; }
 
 # A fingerprint of the whole tree: path, size, exec bit, content hash. Anything a run writes
 # shows up here — "wrote nothing" is otherwise unfalsifiable.
@@ -365,6 +365,72 @@ case "$O" in *"predates the current kickoff question set"*)
       bad "  a second sync finds nothing left to append" ;;
   *)  ok "  a second sync finds nothing left to append" ;; esac
 
+echo "== T11: the retired always-on ledger row (bug-logs/mxcli-bugs.md) becomes bin/bug-lookup.sh =="
+# Master retired the 47,500-word ledger from the baseline tier on 2026-09-08 (bin/bug-lookup.sh
+# reads one entry instead). A project scaffolded before that still routes the ledger as
+# always-on. Three shapes: a MARKED block (2d rewrites it — the retirement must be SAID, not
+# silent), a hand-written UNMARKED table (2d refuses the whole table, so the ONE row is rewritten
+# in place with its own path prefix kept), and CLAUDE.md's bootstrap-authored block (reported
+# with the exact replacement, never edited — no script produced it).
+P="$(mkproj t11)"
+awk '/^\| A CE error.*bin\/bug-lookup\.sh` \|$/ { print "| A CE error or behavior that looks like a known mxcli quirk | `bug-logs/mxcli-bugs.md` |"; next } { print }' \
+  "$P/CLAUDE.local.md" > "$P/CLAUDE.local.md.t" && mv "$P/CLAUDE.local.md.t" "$P/CLAUDE.local.md"
+grep -q 'bug-logs/mxcli-bugs.md' "$P/CLAUDE.local.md" && ok "control: marked block carries the retired row" || bad "control: fixture did not plant the row"
+OUT="$("$SYNC" "$P" 2>&1)"
+case "$OUT" in *"retired the 47k-word ledger row → bin/bug-lookup.sh"*) ok "marked block: the retirement is said on stdout" ;; *) bad "marked block: retirement not announced" "$OUT" ;; esac
+grep -q 'bug-logs/mxcli-bugs.md' "$P/CLAUDE.local.md" && bad "marked block: ledger row survived" || ok "marked block: ledger row gone"
+grep -q '`bin/bug-lookup.sh`' "$P/CLAUDE.local.md" && ok "marked block: bug-lookup row present" || bad "marked block: no bug-lookup row"
+OUT="$("$SYNC" "$P" 2>&1)"
+case "$OUT" in *"Retired"*) bad "marked block: second run retires again (not idempotent)" ;; *) ok "marked block: second run says nothing about it" ;; esac
+
+# Unmarked, hand-written, with full toolkit paths on every row — the pre-2026-08-18 shape.
+P="$WORK/t11b"; mkdir -p "$P"
+cat > "$P/CLAUDE.local.md" <<'EOF'
+# CLAUDE.local.md — toolkit wiring
+
+## Baseline routing (always-on — from the toolkit README, keep in sync via bin/sync-project.sh)
+
+| Always relevant for | Reference this |
+|---|---|
+| Any pipeline work, every session | `~/Mendix/mxcli-project-toolkit/skills/conversion-runbook.md` |
+| A CE error that looks like a tool quirk | `~/Mendix/mxcli-project-toolkit/bug-logs/mxcli-bugs.md` |
+| Any MCP write session | `~/Mendix/mxcli-project-toolkit/skills/learned-mcp-patterns.md` |
+
+## Session-start ritual
+
+1. pull the toolkit.
+EOF
+cat > "$P/CLAUDE.md" <<'EOF'
+# Project
+
+## mxcli-project-toolkit Integration
+
+| Always relevant for | Read this file |
+|---|---|
+| A CE error or behavior that looks like a known mxcli quirk | `~/Mendix/mxcli-project-toolkit/bug-logs/mxcli-bugs.md` |
+EOF
+B="$(fingerprint "$P")"
+OUT="$("$SYNC" "$P" --dry-run 2>&1)"
+A="$(fingerprint "$P")"
+[ "$B" = "$A" ] && ok "unmarked: --dry-run wrote nothing" || bad "unmarked: --dry-run WROTE"
+case "$OUT" in *"would be — Retired"*"retired the 47k-word ledger row"*) ok "unmarked: --dry-run announces the retirement" ;; *) bad "unmarked: --dry-run silent" "$OUT" ;; esac
+OUT="$("$SYNC" "$P" 2>&1)"
+case "$OUT" in *"retired the 47k-word ledger row → ~/Mendix/mxcli-project-toolkit/bin/bug-lookup.sh"*) ok "unmarked: retirement said, with the row's own path prefix" ;; *) bad "unmarked: retirement not announced with prefix" "$OUT" ;; esac
+case "$OUT" in *"hand-written '## Baseline routing' section"*) ok "unmarked: the whole-table refusal still stands (only the one row moved)" ;; *) bad "unmarked: 2d refusal missing" ;; esac
+grep -q 'bug-logs/mxcli-bugs.md' "$P/CLAUDE.local.md" && bad "unmarked: ledger row survived" || ok "unmarked: ledger row gone"
+grep -q '| `~/Mendix/mxcli-project-toolkit/bin/bug-lookup.sh` |' "$P/CLAUDE.local.md" && ok "unmarked: new row carries the table's path prefix" || bad "unmarked: new row prefix wrong" "$(grep bug-lookup "$P/CLAUDE.local.md")"
+grep -q '^| Any pipeline work, every session | `~/Mendix/mxcli-project-toolkit/skills/conversion-runbook.md` |$' "$P/CLAUDE.local.md" \
+  && grep -q '^| Any MCP write session | `~/Mendix/mxcli-project-toolkit/skills/learned-mcp-patterns.md` |$' "$P/CLAUDE.local.md" \
+  && [ "$(awk '/^## .*[Bb]aseline routing/{insec=1; next} insec && /^## /{insec=0} insec && /^\|/{n++} END{print n+0}' "$P/CLAUDE.local.md")" -eq 5 ] \
+  && ok "unmarked: neighbouring rows byte-identical, no row added or lost (header + separator + 3 rows)" || bad "unmarked: table disturbed" "$(printf '%s\n---sync output---\n%s' "$(cat "$P/CLAUDE.local.md")" "$OUT")"
+[ "$(grep -c 'ROUTING:BEGIN' "$P/CLAUDE.local.md")" -eq 0 ] && ok "unmarked: no generated block appended" || bad "unmarked: a second table was appended"
+case "$OUT" in *"CLAUDE.md still routes bug-logs/mxcli-bugs.md"*"bootstrap-project.md"*'`~/Mendix/mxcli-project-toolkit/bin/bug-lookup.sh`'*) ok "CLAUDE.md: reported with the exact replacement row, and why it is not edited" ;; *) bad "CLAUDE.md: report missing" "$OUT" ;; esac
+grep -q 'bug-logs/mxcli-bugs.md' "$P/CLAUDE.md" && ok "CLAUDE.md: left alone (bootstrap-authored, no script produced it)" || bad "CLAUDE.md was EDITED"
+B="$(fingerprint "$P/CLAUDE.local.md")"
+OUT="$("$SYNC" "$P" 2>&1)"
+[ "$B" = "$(fingerprint "$P/CLAUDE.local.md")" ] && ok "unmarked: second run leaves CLAUDE.local.md alone" || bad "unmarked: second run rewrote CLAUDE.local.md" "$(printf '%s\n---sync output---\n%s' "$(cat "$P/CLAUDE.local.md")" "$OUT")"
+case "$OUT" in *"Retired"*) bad "unmarked: second run retires again" ;; *) ok "unmarked: second run says nothing about retiring" ;; esac
+
 echo ""
 echo "PASS=$PASS FAIL=$FAIL   ($WORK)"
 [ "$FAIL" -eq 0 ]
diff --git a/tests/wave2/test-html-to-md.sh b/tests/wave2/test-html-to-md.sh
new file mode 100755
index 0000000..a7cacc6
--- /dev/null
+++ b/tests/wave2/test-html-to-md.sh
@@ -0,0 +1,156 @@
+#!/usr/bin/env bash
+# test-html-to-md.sh — pin bin/html-to-md.sh against the shape that motivated it: a saved-webpage
+# export (page + `_files/` sidecar) beside a Markdown file, in a project's sources/ folder.
+#
+# The page is SYNTHETIC — tests/wave2/fixtures/html-to-md/CAPTURE.md says why that is acceptable
+# here and which structural facts of the real exports it reproduces. Every chrome region and every
+# dropped block carries a `*SENTINEL-n` token, so "nav/footer/script text absent" is a grep, not
+# an impression.
+#
+#   T1  headings, the nested list, the ordered list, the table, pre/code, bold/italic, links survive
+#   T2  nav, sidebar, breadcrumbs, cookie banner, footer, script, style, noscript, svg are gone
+#   T3  the inline base64 image is written to <page>_images/01.png (byte-identical to the sidecar
+#       png, which is the same 1x1 PNG) and referenced from the .md; the sidecar image is referenced
+#       by its existing (project-relative) path
+#   T4  the header's section list is correct: every "L<n>:" line points at a line that IS that heading
+#   T5  documents-index.md names EVERY file under sources/ — page, markdown, png, css, js — with roles
+#   T6  idempotent: a second run skips the page and rewrites nothing under text/; --force reconverts
+#   T7  the summary prints the ratio and the totals
+#
+#   tests/wave2/test-html-to-md.sh /path/to/html-to-md.sh
+
+set -uo pipefail
+
+SUT="${1:?usage: test-html-to-md.sh /path/to/html-to-md.sh}"
+case "$SUT" in /*) ;; *) SUT="$PWD/$SUT" ;; esac
+TOOLKIT="$(cd "$(dirname "$SUT")/.." && pwd)"
+FIX="$TOOLKIT/tests/wave2/fixtures/html-to-md"
+WORK="$(mktemp -d "${TMPDIR:-/tmp}/h2m.XXXXXX")"
+trap 'rm -rf "$WORK"' EXIT
+PASS=0; FAIL=0
+
+ok()  { PASS=$((PASS+1)); printf '  ok   %s\n' "$1"; }
+bad() { FAIL=$((FAIL+1)); printf '  FAIL %s\n     %s\n' "$1" "${2:-}"; }
+has()   { case "$2" in *"$3"*) ok "$1" ;; *) bad "$1" "missing '$3'" ;; esac; }
+hasnt() { case "$2" in *"$3"*) bad "$1" "unexpected '$3'" ;; *) ok "$1" ;; esac; }
+
+P="$WORK/proj"; mkdir -p "$P/sources"
+cp -R "$FIX/." "$P/sources/"; rm -f "$P/sources/CAPTURE.md"
+[ -f "$P/sources/Fleet Portal Requirements.html" ] || { echo "fixture missing"; exit 2; }
+
+OUT="$("$SUT" "$P" 2>&1)"; RC=$?
+MD="$P/analysis/knowledge-base/text/Fleet Portal Requirements.md"
+IDX="$P/analysis/knowledge-base/documents-index.md"
+[ "$RC" -eq 0 ] && ok "html-to-md exits 0" || bad "html-to-md exits 0" "rc=$RC: $OUT"
+[ -f "$MD" ] && ok ".md written under analysis/knowledge-base/text/ at the mirrored path" || bad ".md written" "no $MD"
+[ -f "$IDX" ] && ok "documents-index.md written" || bad "documents-index.md written"
+[ -f "$MD" ] || { echo "PASS=$PASS FAIL=$FAIL"; exit 1; }
+BODY="$(cat "$MD")"
+
+echo "== T1: structure survives =="
+has "h1"                 "$BODY" "# Fleet Portal — Requirements Overview"
+has "h2 inside a wrapper div with a suspicious-looking class (toc-macro) survives" "$BODY" "## 1. Scope"
+has "h3"                 "$BODY" "### 3.1 Worked example"
+has "unordered list"     "$BODY" "- Vehicle register (create, view, retire)"
+has "nested list item indented" "$BODY" "  - one active driver per vehicle"
+has "ordered list"       "$BODY" "2. Retiring a vehicle closes its active assignment"
+has "table header row"   "$BODY" "| Entity | Key attributes | Notes |"
+has "table separator"    "$BODY" "|---|---|---|"
+has "table cell with escaped pipe" "$BODY" "Status: Active \\| Retired"
+has "bold"               "$BODY" "**functional requirements**"
+has "italic"             "$BODY" "*Fleet Portal*"
+has "link"               "$BODY" "[the decision log](/fleet/decisions)"
+hasnt "javascript: link is text only" "$BODY" "](javascript:"
+has "pre block fenced"   "$BODY" '```
+Vehicle AB-123-C  Active'
+has "inline code"        "$BODY" '`LicencePlate`'
+
+echo "== T2: chrome and non-content gone =="
+for s in NAVSENTINEL-1 SIDEBARSENTINEL-2 BREADCRUMBSENTINEL-3 COOKIESENTINEL-4 FOOTERSENTINEL-5 NOSCRIPTSENTINEL-6 SVGSENTINEL-7 SCRIPTSENTINEL-9911 SCRIPTSENTINEL-9912 hidden-style-text; do
+  hasnt "$s absent" "$BODY" "$s"
+done
+hasnt "the wiki's own title element is not rendered as body text twice" "$BODY" "Acme Wiki"
+has "the content inside <main> is intact (last paragraph)" "$BODY" "Is the mileage report monthly or on demand?"
+
+echo "== T3: images =="
+IMG="$P/analysis/knowledge-base/text/Fleet Portal Requirements_images/01.png"
+[ -f "$IMG" ] && ok "inline base64 image written to <page>_images/01.png" || bad "inline image written" "no $IMG"
+if [ -f "$IMG" ] && cmp -s "$IMG" "$P/sources/Fleet Portal Requirements_files/screen-vehicle-list.png"; then
+  ok "decoded image is byte-identical to the same PNG on disk (valid decode)"
+else
+  bad "decoded image bytes"
+fi
+has "inline image referenced from the .md" "$BODY" "![Target vehicle list sketch](Fleet Portal Requirements_images/01.png)"
+has "sidecar image referenced by its existing path, project-relative" "$BODY" "![Vehicle list, current spreadsheet](sources/Fleet Portal Requirements_files/screen-vehicle-list.png)"
+has "header counts 2 images" "$BODY" "**Images:** 2 (1 inline"
+
+echo "== T4: section list is a correct denominator =="
+has "header states the section count" "$BODY" "**Sections (7)**"
+has "header states source path" "$BODY" '**Source:** `sources/Fleet Portal Requirements.html`'
+has "header states raw size and words" "$BODY" "**Raw size:** "
+NSEC=0; NBAD=0
+while IFS= read -r line; do
+  n="$(printf '%s' "$line" | sed -n 's/^- L\([0-9][0-9]*\):.*/\1/p')"
+  [ -n "$n" ] || continue
+  NSEC=$((NSEC+1))
+  title="$(printf '%s' "$line" | sed 's/^- L[0-9]*: *//')"
+  actual="$(sed -n "${n}p" "$MD")"
+  case "$actual" in
+    "#"*" $title") ;;
+    *) NBAD=$((NBAD+1)); echo "     L$n is '$actual', section list says '$title'" ;;
+  esac
+done < "$MD"
+[ "$NSEC" -eq 7 ] && ok "7 section lines listed" || bad "7 section lines listed" "got $NSEC"
+[ "$NBAD" -eq 0 ] && ok "every listed line number holds exactly that heading" || bad "line numbers" "$NBAD wrong"
+# heading count in the body equals the header's count
+NH="$(sed -n '15,$p' "$MD" | grep -c '^#\{1,6\} ')"
+[ "$NH" -eq 7 ] && ok "body holds 7 headings (h1 + 5 h2 + 1 h3) — none inside the pre block counted" || bad "body headings" "got $NH"
+
+echo "== T5: the index names EVERY file =="
+IDXB="$(cat "$IDX")"
+for f in "Fleet Portal Requirements.html" glossary.md app.js site.css screen-vehicle-list.png; do
+  has "index names $f" "$IDXB" "$f"
+done
+has "page row with role and md path" "$IDXB" '| Fleet Portal Requirements.html | page | `analysis/knowledge-base/text/Fleet Portal Requirements.md` | 7 | 2 | '
+has "markdown row listed, not converted" "$IDXB" "| glossary.md | markdown | — (read as is) | 3 | 0 | "
+has "css is chrome of the page" "$IDXB" "| Fleet Portal Requirements_files/site.css | chrome of Fleet Portal Requirements.html |"
+has "js is chrome of the page" "$IDXB" "| Fleet Portal Requirements_files/app.js | chrome of Fleet Portal Requirements.html |"
+has "png is image of the page" "$IDXB" "| Fleet Portal Requirements_files/screen-vehicle-list.png | image of Fleet Portal Requirements.html |"
+has "vision denominator stated" "$IDXB" "Images to read (vision) before Stage 2 closes: 2"
+[ ! -f "$P/analysis/knowledge-base/text/glossary.md" ] && ok "markdown source NOT copied/converted" || bad "glossary.md was converted"
+
+echo "== T6: idempotent, and --force reconverts =="
+fingerprint() { find "$1" -type f | LC_ALL=C sort | while read -r f; do printf '%s %s\n' "${f#$1}" "$(md5sum "$f" 2>/dev/null | cut -d' ' -f1 || md5 -q "$f")"; done; }
+B="$(fingerprint "$P/analysis/knowledge-base/text")"
+OUT2="$("$SUT" "$P" 2>&1)"
+A="$(fingerprint "$P/analysis/knowledge-base/text")"
+[ "$B" = "$A" ] && ok "second run rewrote nothing under text/" || bad "second run rewrote text/"
+has "second run reports the skip" "$OUT2" "up to date, skipped"
+has "second run still reports the page's numbers (read back from the header)" "$OUT2" "265"
+IDX1="$(grep -v '^Written by' "$IDX")"
+OUT3="$("$SUT" "$P" --force 2>&1)"
+has "--force reconverts" "$OUT3" "1 converted, 0 skipped"
+hasnt "--force reports no skip" "$OUT3" "up to date, skipped"
+[ "$IDX1" = "$(grep -v '^Written by' "$IDX")" ] && ok "index identical across runs (sidecar ownership stable)" || bad "index differs between runs"
+A2="$(fingerprint "$P/analysis/knowledge-base/text")"
+[ "$B" = "$A2" ] && ok "--force output is byte-identical to the first run (deterministic)" || bad "--force output differs"
+
+echo "== T7: summary =="
+has "summary column header" "$OUT" "raw KB  md words   ratio"
+printf '%s' "$OUT" | grep -qE 'Fleet Portal Requirements\.html +[0-9.]+ +265 +[0-9.]+×' \
+  && ok "per-page row: raw KB, md words, ratio" || bad "per-page row" "$OUT"
+printf '%s' "$OUT" | grep -qE 'TOTAL +[0-9.]+ +265 +[0-9.]+×  1 converted' \
+  && ok "TOTAL row with ratio and converted count" || bad "TOTAL row" "$OUT"
+has "index line names its path and row count" "$OUT" "documents-index.md — 5 row(s): 1 page, 1 markdown, 1 image, 2 chrome, 0 other"
+
+echo "== T8: usage and root detection =="
+"$SUT" >/dev/null 2>&1; [ $? -eq 2 ] && ok "no args → exit 2" || bad "no args exit code"
+E="$WORK/empty"; mkdir -p "$E"
+"$SUT" "$E" >/dev/null 2>&1; [ $? -eq 2 ] && ok "no sources/ and no --source → exit 2, not a silent zero" || bad "empty project exit code"
+P2="$WORK/p2"; mkdir -p "$P2/source"; cp "$FIX/Fleet Portal Requirements.html" "$P2/source/"
+"$SUT" "$P2" >/dev/null 2>&1 && [ -f "$P2/analysis/knowledge-base/text/Fleet Portal Requirements.md" ] \
+  && ok "source/ (singular) is detected too" || bad "source/ detection"
+
+echo ""
+echo "PASS=$PASS FAIL=$FAIL"
+[ "$FAIL" -eq 0 ]
diff --git a/tests/wave2/test-source-ledger.sh b/tests/wave2/test-source-ledger.sh
index 6205890..c92d7ac 100755
--- a/tests/wave2/test-source-ledger.sh
+++ b/tests/wave2/test-source-ledger.sh
@@ -22,6 +22,9 @@
 #   T8  Stage 0 never blocks on the ledger (the inventory is Stage 0's own output)
 #   T9  a project with files under sources/ and NO inventory at all blocks Stage 1; a project
 #       with neither does not (legacy fixtures keep passing)
+#   T12 (2026-09-09) 'source/**' — the project-root spelling of "the whole corpus" — is accepted
+#       by mark (the root segment is stripped), and a saved page's css/woff2 sidecars inventory as
+#       format `chrome`, not unknown; the deck's pages/images stay owed under a glob mark
 #   T10 an export-prefixed module name (Form_X.cls) is matched when the artifact says X, and an
 #       umlaut filename matches too (bytes.lower() is ASCII-only — the unattended rerun on the real
 #       corpus reported 18 of 96 rows unverified, every one an Ä/Ü/ü name; casefold on text)
@@ -178,6 +181,29 @@ OUT="$(stage "$P9b" 1)"
 hasnt "no sources and no inventory does not block (legacy fixtures)" "$OUT" "Gate BLOCKED by the source ledger"
 has "reads NOT CHECKED, never a pass" "$OUT" "Source ledger (every file consumed?): MANUAL"
 
+echo "== T12: a mark spelled from the project root ('source/**') covers the corpus; a saved page's css is 'chrome', not unknown =="
+# The docs-ready path (2026-09-09): ONE glob mark over the whole corpus, pointing at an index that
+# names every file. Inventory rels are relative to the source root, so 'source/**' — the natural
+# spelling — matched no row and the mark was refused. Now the root segment is stripped.
+P="$(mkproj t12)"
+mkdir -p "$P/source/legacy/Spec_files"
+printf '.x{}\n' > "$P/source/legacy/Spec_files/site.css"
+printf 'x\n' > "$P/source/legacy/Spec_files/f.woff2"
+"$SS" init "$P" >/dev/null 2>&1
+FMT="$("$PY" -c "import json,sys; d=json.load(open(sys.argv[1])); print(' '.join(sorted(set(r['format'] for r in d['inventory'] if r['ext'] in ('css','woff2')))))" "$P/analysis/source-sufficiency.json")"
+[ "$FMT" = "chrome" ] && ok "css and woff2 inventoried as format 'chrome' (route: listed, never content)" || bad "css/woff2 format" "got '$FMT'"
+printf '# Index\n\n| path |\n|---|\n| Functional-Description-draft.pptx |\n| Form_Archive-Detail-Subform.cls |\n| Form_Workflow.cls |\n| Form_Release03.cls |\n| Form_Änderung-Übersicht.cls |\n| site.css |\n| f.woff2 |\n' > "$P/analysis/legacy/documents-index.md"
+OUT="$("$SL" mark "$P" 'source/**' --artifact analysis/legacy/documents-index.md --evidence "index lists each file by name" --by test 2>&1)"; RC=$?
+[ "$RC" -eq 0 ] && ok "'source/**' (project-root spelling) is accepted" || bad "'source/**' refused" "$OUT"
+has "the mark covers every row" "$OUT" "marked 7 row(s) extracted"
+OUT="$("$SL" check "$P" 2>&1)"; RC=$?
+# The pptx still owes its pages and images — a glob mark does not waive a container's media.
+[ "$RC" -eq 1 ] && ok "check still exits 1: the deck's 25 slides / 22 images are not covered by an index row" || bad "check exit" "rc=$RC"
+has "the container is what remains owed" "$OUT" "page(s)/slide(s)/sheet(s) inside"
+# The text output lists only non-green rows; per-row verdicts come from --json.
+VERD="$("$SL" check "$P" --json --quiet 2>/dev/null | "$PY" -c "import json,sys; d=json.load(sys.stdin); print(' '.join(r['verdict'] for r in d['rows'] if r['rel'].startswith('legacy/Spec_files/')))")"
+[ "$VERD" = "EXTRACTED EXTRACTED" ] && ok "css and woff2 rows are EXTRACTED by the index alone — chrome owes no --media, no separate disposition" || bad "sidecar verdicts" "got '$VERD'"
+
 echo ""
 echo "== $PASS passed, $FAIL failed =="
 [ "$FAIL" -eq 0 ]