diff --git a/.abcd/config/reading-presets.json b/.abcd/config/reading-presets.json
index 68c1ee402..497bc928e 100644
--- a/.abcd/config/reading-presets.json
+++ b/.abcd/config/reading-presets.json
@@ -60,10 +60,10 @@
         "test"
       ],
       "window": {
-        "tokens_est": 1280000,
-        "measured_tokens_est": 1265015,
-        "measured_bytes": 4870311,
-        "measured_at": "b198acca0dd490d7e48fb0d11c54382fa826c21a"
+        "tokens_est": 1300000,
+        "measured_tokens_est": 1277632,
+        "measured_bytes": 4918884,
+        "measured_at": "00a250663e9d9f4631f7e7e0e2485f67b75f961a"
       }
     },
     "entailment": {
@@ -133,9 +133,9 @@
       ],
       "window": {
         "tokens_est": 390000,
-        "measured_tokens_est": 377255,
-        "measured_bytes": 1452432,
-        "measured_at": "b198acca0dd490d7e48fb0d11c54382fa826c21a"
+        "measured_tokens_est": 379456,
+        "measured_bytes": 1460909,
+        "measured_at": "00a250663e9d9f4631f7e7e0e2485f67b75f961a"
       }
     },
     "comparative": {
@@ -216,10 +216,10 @@
         "test"
       ],
       "window": {
-        "tokens_est": 1290000,
-        "measured_tokens_est": 1274051,
-        "measured_bytes": 4905099,
-        "measured_at": "b198acca0dd490d7e48fb0d11c54382fa826c21a"
+        "tokens_est": 1300000,
+        "measured_tokens_est": 1286668,
+        "measured_bytes": 4953672,
+        "measured_at": "00a250663e9d9f4631f7e7e0e2485f67b75f961a"
       }
     }
   }
diff --git a/.abcd/development/brief/04-surfaces/01-ahoy.md b/.abcd/development/brief/04-surfaces/01-ahoy.md
index edf47b521..aea9d2826 100644
--- a/.abcd/development/brief/04-surfaces/01-ahoy.md
+++ b/.abcd/development/brief/04-surfaces/01-ahoy.md
@@ -382,7 +382,7 @@ about, one question per category present, never one per item.
 | `safe-autocreate` | the repo skeleton, history-store directories, the name-guard artefacts | applied once the category is approved, no per-item prompt; create-if-absent, never overwriting |
 | `config-change` | visibility, oracle adapter, the `PATH` entry, the git-identity pin, the artefact kind | transparent confirm; skip-if-set with a "current value" notice |
 | `plugin-owned` | the marker block (itd-3); hook-manifest verification | silent overwrite on marker drift; a non-resolvable diagnostic for a malformed or missing manifest, and for a conventions file whose block would land inside a fence or HTML comment nothing closes (`marker.unplaceable`) |
-| `dependency` | the opt-in scanners | one category-level approval covering them; abcd never auto-executes a package manager, and the user runs the commands |
+| `dependency` | a tool a capability uses and cannot find: gitleaks, optional over the native secret scanner and required where the repository armed it in `.abcd/config/gitleaks.json` | the category approval reaches the step; each tool is then explained from the tool registry (what it is, optional or required here, what works without it, the exact install step, what the install does) and its install step runs only on a per-tool yes — typed at a terminal, or relayed by a host as a flag naming the tool — never under the approve-everything flag, a piped answer or CI; a no is reported as what the capability continues on |
 | `status-line` | the offer of abcd's status line in the host harness | an advisory offer asked after its own question, written only on an answered consent; never under the approve-everything flag, and reported as optional work it skipped |
 | `oracle-routing` | the offer of abcd's proposed model-tier routing table (itd-2609170822093401): the machine's `~/.abcd/oracle-routing.json`, then, as a separate question, the repository's `.abcd/config/oracle-routing.json` | the proposal rendered as a table (agent, tier, fan-out) and each file written only on its own answered consent, the machine one owner-only; never under the approve-everything flag, and reported as optional work it skipped; a decline records nothing, so the next install offers again; uninstall leaves both files |
 | `user-state` | the registry entry, re-founding, stale or duplicate entries | guided; never auto-edit user-scope state, report extras read-only |
@@ -448,6 +448,25 @@ prompt wait rather than decline, which is the contract every prompting CLI has.
 A run that must neither block nor prompt closes stdin and pre-answers with
 flags.
 
+**Installing a tool is the one question a piped answer never answers.** It runs
+a program on the machine, so it is asked only of a person at a terminal, after
+the tool registry's explanation is shown, and its default is no. Off a terminal
+the answer is a flag naming the tool, which is how a host relays the answer its
+own question tool got; the approve-everything flag never installs a tool, and a
+CI runner never installs one and is not asked: the canonical CI detector
+(`internal/cienv`, `GITHUB_ACTIONS=true` or a truthy `CI`) refuses, and so does
+`CI` set to any value, `false` and `0` included. What runs is the
+registry's fixed argv for the platform, never a shell string and never a command
+composed from input, and only when the package manager resolves on `PATH`
+outside the repository (`internal/core/tools`). The step runs in a process group
+of its own, bounded at 15 minutes (its verify at 30 seconds), and a timeout kills
+that group through the handle abcd holds. The kill has one limit: a process the
+step moves into another group or session (`setsid`, `setpgid`) is out of its
+reach and can outlive the run. abcd stops reading output 10 seconds after the
+step exits or is killed, so such a process holding the output open cannot hold
+the run past its bound, and a step that exits cleanly while leaving one behind
+is reported as failed, saying so.
+
 The non-interactive flags pre-answer the prompts: approve every resolvable
 category, decide the adoption question either way, set the marker target, the
 oracle backend, the deep-scan toggle and the repo visibility, select track-latest
@@ -591,9 +610,12 @@ byte-identical to a fresh install save for the setup date.
 - **Given** a repo with the install run at an older setup version, **when**
   the install runs, **then** the version is updated, the marker block refreshed,
   and existing config keys preserved.
-- **Given** an opt-in scanner is not on `PATH`, **when** the dependency category
-  is approved, **then** the user is shown the install commands under one
-  category-level approval; abcd never auto-executes a package manager.
+- **Given** a tool a capability uses is not on `PATH`, **when** the dependency
+  category is approved, **then** the person is shown the tool registry's
+  explanation and asked per tool; the registry's fixed install step runs only
+  on a yes typed at a terminal or relayed by a host naming the tool, the result
+  reports what ran and whether its verify passed, and a no reports what the
+  capability continues on (itd-63).
 - **Given** no oracle adapter is wired, **when** detection resolves the oracle,
   **then** it stays host-delegated: abcd needs no API keys or model config,
   because it emits prompts the host runs (adr-25), and an adapter can be
@@ -665,6 +687,7 @@ Sub-verbs: none.
 | `--bin-dir` | string |
 | `--dev` | bool |
 | `--docs-target` | string |
+| `--install-tool` | stringSlice |
 | `--oracle-backend` | string |
 | `--refuse-adopt` | bool |
 | `--scan-deep` | string |
diff --git a/.abcd/development/brief/04-surfaces/05-intent.md b/.abcd/development/brief/04-surfaces/05-intent.md
index aa7ad64a7..26fb0e80c 100644
--- a/.abcd/development/brief/04-surfaces/05-intent.md
+++ b/.abcd/development/brief/04-surfaces/05-intent.md
@@ -302,7 +302,7 @@ Later phase — intent-auditor (shape-classification role) scans the corpus
 | Subcommand | Purpose | File movement |
 |---|---|---|
 | `/abcd:intent` (no args) | Read-only status: bucket counts (drafts / planned / shipped / disciplines / superseded) with the count of owed fidelity reviews beside them (the owed listing's total, from the same reader), open/closed spec counts, the itd↔spc links, and in the machine-readable form a per-intent listing (id, title, bucket, `ac_state` `real` or `seeded`, and the filing date a timestamp id encodes, null for an ordinal id; iss-242), a ledger-routing hint (`abcd capture "…"` for an observation, `abcd intent "…"` for a user-facing change), and an ideate-routing line (a big, unproven idea? `abcd ideate` runs the optional admission gauntlet and records the verdict either way) | — |
-| `/abcd:intent "<free-text>"` | **Canonical create** (spc-30 (predecessor store)/itd-46): a leading quoted seed is the canonical create entry. Seeds a draft skeleton whose `## Press Release` is the quoted text as prose, under an H1 derived from the text's first sentence (cut on a word boundary at the slug cap) or given as a title — one line, non-empty, redacted like the text — with Why This Matters and Acceptance Criteria seeded as prompts for the human to fill; assigns `itd-N` and derives the slug from the text; writes `suggested_kind: null`. An optional impact (additive, breaking or fix) stamps the draft's product impact at create time, and an optional production mode (hand-written, dictated-and-formatted or scribe-transcribed) stamps how its text was produced (itd-178); the draft's `origin` carries no flag and is derived from the verb that ran. A leading quote always creates — never falls through to bare render | writes to `drafts/itd-N-<slug>.md` (no spec created) |
+| `/abcd:intent "<free-text>"` | **Canonical create** (spc-30 (predecessor store)/itd-46): a leading quoted seed is the canonical create entry. Seeds a draft skeleton whose `## Press Release` is the quoted text as prose, under an H1 derived from the text's first sentence (cut on a word boundary at the slug cap) or given as a title — one line, non-empty, redacted like the text — with Why This Matters and Acceptance Criteria seeded as prompts for the human to fill; assigns `itd-N` and derives the slug from the text; writes `suggested_kind: null`. An optional impact (additive, breaking or fix) stamps the draft's product impact at create time, and an optional production mode (hand-written, dictated-and-formatted or scribe-transcribed) stamps how its text was produced (itd-178); the draft's `origin` carries no flag and is derived from the verb that ran. Before the draft is written, under the store's mint lock, its title and press release are matched against every open and resolved issue and every intent by the term-overlap heuristic `/abcd:capture` uses (itd-2609212137116617): a record at or above `match.threshold` is written onto the draft as `duplicates:` or `refines:`, at most three links, and the output lists the near misses below it with their scores; the match never refuses the create. A leading quote always creates — never falls through to bare render | writes to `drafts/itd-N-<slug>.md` (no spec created) |
 | The grill step, on one intent id | Socratic adversarial interview that stress-tests an intent for vagueness, missing acceptance, hidden assumptions before planning. Glossary-aware once `terminology/` exists. A brief-section mode would stress-test a brief section instead. (per itd-27, `intents/planned/` — a later phase; no grill sub-verb ships yet) | (stays in current state) |
 | Plan (one intent id) | Plans a draft: mints its native spec, injects the bidirectional link (intent `spec_id` ↔ spec `intent`), stamps an identity onto every unmarked scope condition, and moves the file `drafts/` → `planned/`. An impact given at planning stamps the INTENT's product-impact judgement, because the planning interview is where that judgement is made: validated at the create path's bar (never `internal`), written as the bare scalar the create path writes, refused before anything moves when it disagrees with a judgement the record already carries, and a no-op when it agrees; without one the field is left as found and the judgement stays owed to the close (iss-2609170726457256). A production mode given at planning stamps the MINTED SPEC's disclosure pair; the intent's own stamp was written at create time and is never rewritten. On an intent already in `planned/` it does the identity step alone (no spec, no move), takes an impact under the same rules, and refuses when nothing is unmarked and no judgement is added — except where the planned record's `spec_id` is null, when it mints (or reuses the spec already naming the intent) and links the spec in place on the draft's Acceptance Criteria bar, still with no move, and the readiness gate's remedy for the missing spec names this call (iss-2609211738504433). | `drafts/` → `planned/` (stamp step: no move) |
 | Plan a bundle (several intent ids, a bundle name) | **The bundle command** (itd-34): plans two or more drafts as ONE shared spec. The name is the human's (the plugin page asks for it; the CLI refuses several ids without one, and a name with one id), kebab-case, and carried by no other record. It refuses a member naming another in `blocked_by`, naming the edge, and any member that is not a plannable draft — held, without criteria, already specced or naming another bundle — before the mint. It mints one spec whose frontmatter lists every member (`intents:` beside `intent:`, and `bundle:`), stamps `kind: bundle-member`, `bundle: <name>`, the scope-condition identities and an impact given at planning onto each member, links each `spec_id` to the shared spec, and moves all of them together; a failure after the mint puts every member back and takes the spec back. The shared spec's close ships every member together. | every member `drafts/` → `planned/` |
@@ -359,6 +359,12 @@ production_mode: hand-written # how the text was produced: hand-written | dictat
 #                                   draft, which graduated from nothing. The shipped
 #                                   record_provenance rule holds it against origin:
 #                                   extracted-from-record / contributed-by-reading
+#   duplicates: [iss-N | itd-N, ...] — written by the filing-time match (itd-2609212137116617)
+#   refines: [iss-N | itd-N, ...]      when a record clears match.threshold: a near-identical
+#                                   double, or a broader record this draft is the narrower case of.
+#                                   A person confirms a link by leaving it and removes it by
+#                                   deleting the line; record_schema resolves both like every
+#                                   other cross-reference
 # Added later, not part of the seed skeleton:
 #   held: "<reason>"              — the hold the intent verb writes and its unhold removes, on a
 #                                   drafts/ or planned/ record only: one non-empty line, redacted before the
diff --git a/.abcd/development/brief/04-surfaces/06-capture.md b/.abcd/development/brief/04-surfaces/06-capture.md
index 9b0383f1a..904c41ed6 100644
--- a/.abcd/development/brief/04-surfaces/06-capture.md
+++ b/.abcd/development/brief/04-surfaces/06-capture.md
@@ -49,7 +49,10 @@ refuses is counted in none of the three totals, so the board counts it beside
 them and names, for each one, the reader layer that refused it: the filename,
 the guarded read, the frontmatter parse, the schema or the folder and filename
 invariants. The layer is what tells a reader whether the record or the reader is
-the side to fix (iss-2609120452071388). The board also counts the records git
+the side to fix (iss-2609120452071388). A status directory that exists and
+cannot be listed is not counted as empty and is not an entry: the board faults
+naming the directory, as the list, the transitions and the mint do
+(iss-2609261241121312, iss-2609261631120364). The board also counts the records git
 reports as untracked or changed and marks each such row: folder membership is a
 status only once the file is committed, so an uncommitted record is in no state to
 any other branch, worktree or gate (iss-2609100508570527).
@@ -81,6 +84,24 @@ record names no location in this checkout, so nothing ties it to the repository
 it is filed into: that is a nudge, not a gate, and it is the shape every
 misfiled record behind iss-2609120511058115 had (iss-2609231156260287).
 
+Before the record is written, the fast path matches its text against the
+record (itd-2609212137116617): every open and resolved issue's body and every
+intent's title and press release, under the ledger lock, through the
+term-overlap primitive in `internal/core/record/match`. The score is the share
+of the new text's terms a candidate already holds, each term weighted by how
+rare it is across the candidates, and it is declared a lexical heuristic on
+every output. A candidate at or above `match.threshold` is written onto the
+new record as `duplicates:` (the two hold each other's terms) or `refines:`
+(the candidate holds this text's terms and more, so this record is the
+narrower), at most three links; the output lists the rest, and the best five
+below the threshold as near misses with their scores. The match never refuses
+and never drops a capture: a text with fewer than eight distinct terms, a record
+set that cannot be read and a configuration the reader refuses each file the
+record unlinked, and the output says which. A person confirms a link by leaving
+it and removes it by deleting its line, which leaves an ordinary record. The
+match proposes no `reverses` and no `supersedes`: the itd-84 discipline keeps a
+reversal advisory and human.
+
 One flag belongs to one category: the lapse-instant flag carries the RFC 3339
 instant a recorded discipline gave way, for the `lapse` category, and it has no
 default.
@@ -339,6 +360,8 @@ related_specs: [spc-N, ...]
 related_issues: [iss-N, ...]
 synthesis_clusters: [<label>, ...]  # optional synthesis grouping
 blocked_by: [iss-N, ...]   # dependency edges, written at capture or afterwards by linking; blocked/priority is derived, never stored
+duplicates: [iss-N|itd-N, ...]  # written by the filing-time match: a near-identical double; removed by hand when wrong
+refines: [iss-N|itd-N, ...]     # written by the filing-time match: this record is the narrower case
 wontfix_reason: "<text>"   # required when in wontfix/
 resolution: "<one-line>"   # required when in resolved/
 shipped_in: vX.Y.Z         # migration use: the release that already carried the work
@@ -398,7 +421,21 @@ token names. Appending rather than setting is the point: a later triage route
 adds a bullet beside the one an earlier route recorded, and neither overwrites
 the other. The section is held by `internal/core/grounds` per adr-57, and
 `record_schema` blocks a frontmatter `grounds:` key by naming this section as
-where the value belongs.
+where the value belongs. It also blocks a top-level bullet in the section that
+does not parse as `- <token>: <text>`, on an issue or an intent record: the
+reader drops such a bullet, so a hand edit spelled `- rejected: …` would
+otherwise be no recorded ground to any surface while the record reads as
+carrying one. Which bullets the reader drops is `internal/core/grounds`'s own
+answer, so the gate and the reader cannot disagree about it, and a paragraph of
+prose under the heading is not a bullet and is not judged.
+
+A body that leaves an HTML comment or a fence open is refused on every route
+that would append a bullet, a wontfix included, exit 2 and nothing written: the
+opener masks every line below it, so the bullet could not be read back. The
+refusal names the construct and its body line, and the repair is the hand edit:
+close or remove the opener in a text editor, then re-run the verb
+(iss-2608301908270888). A resolve or a promote given no grounds appends nothing,
+so it acts.
 
 **The grounds text is gated on substance, not only on grammar.** A value that
 parses as `<token>: <text>` is still refused, exit 2 and nothing written, unless
@@ -411,6 +448,15 @@ cases; a floor set high enough to judge reasoning would only buy padding. In a
 script written without inter-word spaces each letter counts as one unit, so the
 word floor does not fall on the writer of a Chinese or Japanese text.
 
+**The grounds text must render.** The section is append-only and no verb removes
+an entry, so a text the site's renderer refuses — an unclosed code span, an
+image, raw HTML, a reference link, a link title — is refused before anything is
+written, exit 2, on every route that records grounds, the reason-derived
+`declined:` entry of a wontfix included. The question is put to the renderer
+itself (`internal/core/mdrender`), so what is refused is exactly what a site
+build refuses, judged strictly where a page would supply context: every
+reference link and every image is refused.
+
 ## 4. Legacy scratch migration
 
 **Not built yet.** The migration rides the `dev-sync work` surface
diff --git a/.abcd/development/brief/05-internals/03-configuration.md b/.abcd/development/brief/05-internals/03-configuration.md
index 64d64bd57..5a611cbfe 100644
--- a/.abcd/development/brief/05-internals/03-configuration.md
+++ b/.abcd/development/brief/05-internals/03-configuration.md
@@ -1,7 +1,7 @@
 # Configuration Model
 
 Almost nothing here is a decision anyone has to make. Installing abcd asks four
-questions, records the answers, and gets on with it; two further keys can be
+questions, records the answers, and gets on with it; four further keys can be
 hand-set and are read but never written. That is the whole of the configuration
 surface the shipped binary consults. Everything else on this page is either a
 store abcd lays out for itself, a policy that follows from one of those four
@@ -15,13 +15,13 @@ shipped behaviour. Everything after them is **staged**, per the truth rule in
 
 ### The keys the binary reads
 
-Seven keys plus a `meta` block. Install asks about visibility, the docs target,
+Nine keys plus a `meta` block. Install asks about visibility, the docs target,
 the oracle backend, and the deep scan (the last only when visibility is private
 and the deep scanner is on `PATH`), and writes exactly those four values back.
-`attribution.hook` is written by `ahoy install --attribution`. The remaining two —
-whether abcd should enable the forge's own secret scanning, and the rules
-loader's refresh backstop — are hand-set: the binary reads them and never writes
-them.
+`attribution.hook` is written by `ahoy install --attribution`. The remaining four —
+whether abcd should enable the forge's own secret scanning, the rules loader's
+refresh backstop, and the filing-time match's threshold and compared fields —
+are hand-set: the binary reads them and never writes them.
 
 ```json
 {
@@ -57,10 +57,27 @@ them.
     "force_refresh_every_n": 15         // prompt-router refresh backstop (itd-3). The primary refresh is
                                         //   event-driven, on SessionStart and PreCompact, so this large
                                         //   counter only re-injects always-relevant domains
+  },
+  "match": {                            // the filing-time match of capture and the intent create
+                                        //   (itd-2609212137116617), a lexical heuristic
+    "threshold": 0.6,                   // share of the new text's terms a record must hold, in (0, 1],
+                                        //   for a duplicates/refines link to be written
+    "fields": ["issue.body", "intent.title", "intent.press_release"]
+                                        // what each candidate offers; one or more of the three
   }
 }
 ```
 
+The `match` keys are read through the layered configuration reader
+(`internal/core/layered`), as the provider adapter's `oracle` keys below are:
+`.abcd/config.json` wins, then
+`~/.abcd/config.json`, then the bundled default above, and each value is
+reported with the file it came from. The reader claims the `match` namespace,
+so a misspelt key, a threshold outside its range and a field outside the set
+are refused naming the file, never passed over for the default. A refusal
+there never refuses a filing: the record is written unlinked and the verb says
+which key was refused.
+
 There is no separate `.abcd/meta.json` at repo scope: setup metadata is the `meta`
 block. This repository's own config carries four of these blocks — `docs`, `meta`,
 `oracle` and `repo` — which is what an unremarkable managed repo looks like.
@@ -330,16 +347,18 @@ history registry, the transcript corpus, the voyage operations namespace, the
 lab store, the staged worktree store, the run state an autonomous run's sessions share
 ([`../04-surfaces/27-implement.md`](../04-surfaces/27-implement.md)), the inbox of reports managed repositories file back to abcd
 ([`../04-surfaces/29-report.md`](../04-surfaces/29-report.md)), the machine layer of the layered configuration in `config.json`
-(its one reader is the provider adapter's, and its one write the provider block
-`ahoy connect` adds; every other config read resolves the repo-scope
-`.abcd/config.json`), the load check's two limits in `load-limits` (read-only and
-never created, itd-2609231434459890), the external credentials adapters resolve
-by name in `credentials.json` (refused unless it is a regular file this uid owns
-at mode 0600 that names each credential once, a repeated key or a case twin
-included; `ahoy connect` adds one name at a time and never replaces a stored
-value, holding the file's lock across the read and the write as the provider
-block's write holds `config.json`'s, so concurrent setups lose nothing — the
-interim source the credential store, itd-2609221017023290, replaces), the
+(its readers are the provider adapter's and the filing-time match's `match`
+keys, each read beneath the repo-scope `.abcd/config.json`, and its one write
+the provider block `ahoy connect` adds; every other config read resolves the
+repo-scope `.abcd/config.json` alone), the load check's two limits in
+`load-limits` (read-only and never created, itd-2609231434459890), the external
+credentials adapters resolve by name in `credentials.json` (refused unless it is
+a regular file this uid owns at mode 0600 that names each credential once, a
+repeated key or a case twin included; `ahoy connect` adds one name at a time and
+never replaces a stored value, holding the file's lock across the read and the
+write as the provider block's write holds `config.json`'s, so concurrent setups
+lose nothing — the interim source the credential store, itd-2609221017023290,
+replaces), the
 machine's rule conventions in `rules.json` (the user layer of the rules loader,
 read-only and never created, itd-117 — see
 [the rules layers](#the-rules-layers--bundled-user-repo) below), user-scope memory for personal cross-project knowledge (a later
diff --git a/.abcd/development/brief/05-internals/06-lint.md b/.abcd/development/brief/05-internals/06-lint.md
index 32c1b4a42..6bbf8250f 100644
--- a/.abcd/development/brief/05-internals/06-lint.md
+++ b/.abcd/development/brief/05-internals/06-lint.md
@@ -6,7 +6,7 @@ Canonical reference for the lint engine in `internal/core/lint` — the determin
 
 The lint engine lives in `internal/core/lint` (Go). It is driven by two armed, deterministic tree gates, each reading its own JSON rule config as the single source of truth for the armed rule set, and by one history-range gate:
 
-- **Record-currency** (`cmd/record-lint`, config `.abcd/record-lint.json`) lints the markdown design record under `.abcd/development/` for drift: frontmatter and schema shape, a principle's typed claims and the scope conditions its evidence inherits, resolvable cross-links, directory coverage, intent-lifecycle placement, retired or banned tokens, index-drift on generated regions, delivery-state agreement, citation currency, and record ids cited in record PROSE (`prose_citation_resolves`: an id written in a record's prose must name a record that exists, unless the author marks the line `<!-- record-lint: illustrative -->` or `<!-- record-lint: forward-looking -->`, or the id is carried by the ratcheting baseline `.abcd/prose-citations-baseline.json`; §1.1 says exactly what counts as prose). `make record-lint` runs it, and CI runs the same job on every push.
+- **Record-currency** (`cmd/record-lint`, config `.abcd/record-lint.json`) lints the markdown design record under `.abcd/development/` for drift: frontmatter and schema shape (for the issue ledger, every record the ledger reader skips, reported in the reader's own words through `internal/core/issuerecord`), a principle's typed claims and the scope conditions its evidence inherits, resolvable cross-links, directory coverage, intent-lifecycle placement, retired or banned tokens, index-drift on generated regions, delivery-state agreement, citation currency, and record ids cited in record PROSE (`prose_citation_resolves`: an id written in a record's prose must name a record that exists, unless the author marks the line `<!-- record-lint: illustrative -->` or `<!-- record-lint: forward-looking -->`, or the id is carried by the ratcheting baseline `.abcd/prose-citations-baseline.json`; §1.1 says exactly what counts as prose). `make record-lint` runs it, and CI runs the same job on every push.
 - **Docs-currency** (`abcd lint docs`, config `.abcd/docs-lint.json`) lints `docs/` and the repo-root prose for change-narration (past-tense drift such as "previously" or "formerly"), broken relative links, stray root markdown, host-name leakage, British-spelling drift, em-dash-in-list-item punctuation, and citation health. `make docs-lint` runs it, and CI runs it on the Linux leg.
 - **Decisions-append** (`cmd/record-lint decisions-append <base> <head>`, no config) checks every commit in a git range, merges included, against the append-only contract of `.abcd/work/DECISIONS.md`: DA001 an added line lands after the parent's last line, DA002 no committed line below the header is removed against any parent, DA003 a merge holds a line no more times than its merge base plus what each parent added, DA004 no commit introduces a NUL byte. The four ids are the gate's contract rather than configurable rules, and the contract, with the reasoning behind each rule, heads `internal/core/lint/decisionsappend.go`. The base is resolved once, through `gitutil.ResolveRangeBase`: an empty value or the all-zeroes placeholder is an announced skip, and a base that names no commit is refused. Exit 0 is clean or skipped, 1 a violation, 2 a range the gate could not judge (a shallow checkout, an unresolvable ref, a merge whose bound has no base to rest on). `make lint-decisions` runs it over `origin/main..HEAD` after its `TestDecisionsAppend*` cases, and CI runs it over the event's base.
 
diff --git a/.abcd/development/intents/README.md b/.abcd/development/intents/README.md
index f4340afb7..a61f2ff4a 100644
--- a/.abcd/development/intents/README.md
+++ b/.abcd/development/intents/README.md
@@ -42,7 +42,7 @@ Standalone is the default (~60% of the corpus). Bundle-members ship together as
 
 The kind is **project-agnostic** — application projects (e.g., a macOS app under abcd) produce their own disciplines (privacy-impact review, accessibility passes, code-style conventions). The three kinds are a property of the intent framework, not of abcd's particular subject matter.
 
-**The persisted `kind` enum stays three-valued.** The capture-time classifier has a *fourth* verdict, `decision` (a standing infrastructure choice — "we use Postgres"), but `decision` is **never a persisted `kind`** and never enters this lifecycle: a confirmed `decision` routes to the existing ADR store (`../decisions/adrs/`, `adr-N-<slug>.md`), not to a draft. There is deliberately **no `intents/decisions/` directory**. See [itd-44](drafts/itd-44-fourth-intent-kind-decision.md) (spc-56 thin adoption) and `brief/04-surfaces/05-intent.md § 1`.
+**The persisted `kind` enum stays three-valued.** A *fourth* capture-time verdict, `decision` (a standing infrastructure choice — "we use Postgres"), is drafted as [itd-44](drafts/itd-44-fourth-intent-kind-decision.md) and not built: the binary has no capture-time classifier verdict. In that design `decision` is **never a persisted `kind`** and never enters this lifecycle: a confirmed `decision` would route to the existing ADR store (`../decisions/adrs/`), not to a draft. There is deliberately **no `intents/decisions/` directory**. See `brief/04-surfaces/05-intent.md § 1`.
 
 ---
 
diff --git a/.abcd/development/intents/disciplines/itd-84-intent-decomposition.md b/.abcd/development/intents/disciplines/itd-84-intent-decomposition.md
index b1a40856c..197a52fc2 100644
--- a/.abcd/development/intents/disciplines/itd-84-intent-decomposition.md
+++ b/.abcd/development/intents/disciplines/itd-84-intent-decomposition.md
@@ -60,6 +60,17 @@ capture-time agent is the **discipline rung — build after** the protocol is
 calibrated against ~50 real, human-graded captures. Until the agent ships the
 gate is the documented protocol, announced as not-yet-automated (loud-staging).
 
+**Delivered rung: the capture-time candidate pass.** The lexical shortlist of
+rule 2 runs at filing, delivered by
+[itd-2609212137116617](../shipped/itd-2609212137116617-a-new-capture-or-draft-is-matched-against-the-record-before.md):
+`capture` and the quoted-text intent create match the new text against every
+open and resolved issue and every intent, write each likely double onto the new
+record as a typed `duplicates` or `refines` link, never refuse the write, and
+leave the link for a human to confirm or remove. It proposes no `reverses` and
+no `supersedes`, so rule 3 holds by construction. The atomicity smell, the
+per-part routing, the reversal flag and the three-outcome verdict are not
+delivered, and the hand-run protocol stays their gate.
+
 ## Why
 
 The record information architecture ([adr-30](../../decisions/adrs/0030-record-information-architecture.md))
diff --git a/.abcd/development/intents/drafts/itd-30-design-fictions-as-intent-format.md b/.abcd/development/intents/drafts/itd-30-design-fictions-as-intent-format.md
index ae11f1b63..2d989a7a6 100644
--- a/.abcd/development/intents/drafts/itd-30-design-fictions-as-intent-format.md
+++ b/.abcd/development/intents/drafts/itd-30-design-fictions-as-intent-format.md
@@ -102,5 +102,5 @@ _Empty. Populated by intent-fidelity-reviewer when intent moves to shipped/._
 - Builds on: itd-1 (acceptance gates — gate applies identically across formats), itd-27 (grill sub-verb and glossary — fictions may need their own glossary entry), the brief's `04-surfaces/05-intent.md` (which currently codifies press-release-only and will need updating to describe both lanes).
 - Coordinates with: itd-15 (self-dogfooded SOTA audit — must remain format-neutral), `intent-fidelity-reviewer` agent (extends to read fiction texture).
 
-**Implementation note (post-2026-05-07 reclassification):** the spec for this intent MUST extend itd-27's grill machinery — the capture-while-grilling pattern, the persona registry pickup, the lint integration, the glossary surface — rather than duplicating any of it. The standalone reclassification (2026-05-07) does not weaken this dependency; it only changes its shape from bundle-shaped (one shared spec) to dependency-shaped (spec depends on or extends spc-3, the grill sub-verb's spec). itd-30's plan-review must verify this dependency is honoured. If the spec plan duplicates rather than extends, the plan-review fails.
+**Implementation note (post-2026-05-07 reclassification):** the spec for this intent MUST extend itd-27's grill machinery — the capture-while-grilling pattern, the persona registry pickup, the lint integration, the glossary surface — rather than duplicating any of it. The standalone reclassification (2026-05-07) does not weaken this dependency; it only changes its shape from bundle-shaped (one shared spec) to dependency-shaped (spec depends on or extends the grill sub-verb's spec — spc-3 of the predecessor store, not the live `spc-3`). itd-30's plan-review must verify this dependency is honoured. If the spec plan duplicates rather than extends, the plan-review fails.
 - Methodological precedents: Amazon's working-backwards press release (the existing default); Anthony Dunne and Fiona Raby's *Speculative Everything* (design fiction as a research method); Bruce Sterling's "design fiction" coinage; Julian Bleecker's *Design Fiction: A Short Essay on Design, Science, Fact and Fiction* (Near Future Laboratory); the diegetic-prototype tradition in HCI research; service-design tools like personas + journey maps that already inform `personas.json`.
diff --git a/.abcd/development/intents/drafts/itd-44-fourth-intent-kind-decision.md b/.abcd/development/intents/drafts/itd-44-fourth-intent-kind-decision.md
index 8e9cd9de0..2a00b638d 100644
--- a/.abcd/development/intents/drafts/itd-44-fourth-intent-kind-decision.md
+++ b/.abcd/development/intents/drafts/itd-44-fourth-intent-kind-decision.md
@@ -15,9 +15,10 @@ builds_on: [itd-39]
 
 ## Operator deviation (thin adoption — recorded)
 
-> **This intent is delivered under an operator-elected THIN adoption** (interview
-> decision; ratified at plan-review r1 of the implementing spec
-> `spc-56-fourth-intent-kind-decision-thin`). Two design choices in the original
+> **This intent is scoped to an operator-elected THIN adoption** (interview
+> decision; ratified at plan-review r1 of `spc-56-fourth-intent-kind-decision-thin`
+> in the predecessor store, a spec the Go rebuild did not carry — the live
+> `spc-56` is an unrelated record). Two design choices in the original
 > draft (preserved below the line, struck through where superseded) are
 > **rejected**, and the rejection is recorded here so a future reader does not
 > re-derive the heavy design:
@@ -45,6 +46,14 @@ builds_on: [itd-39]
 > `## Consequences` body — **no** `## Rationale` section (rationale folds into
 > `## Context`, matching the store convention).
 
+> **Delivery state (amended 2026-09-26, iss-239).** Nothing here is delivered.
+> The thin adoption was ratified against a spec of the predecessor store; the Go
+> binary has no capture-time classifier verdict, no `decision` route into the ADR
+> store from `abcd intent`, and no "decisions are not plannable" refusal — the
+> brief states the same (`brief/04-surfaces/05-intent.md`, the fourth capture
+> verdict). This draft carries the design for a later plan; `abcd decide` mints an
+> ADR directly and is not this capture-time route.
+
 ## Why This Matters
 
 The three-intent-kinds taxonomy (itd-34) covers `standalone`, `bundle-member`,
@@ -125,8 +134,8 @@ language version. The verdict generalises.
 - `decision` is therefore NEVER written to the schema `kind` or
   `kind_at_supersession`, NEVER enters the `drafts/→planned/→shipped/`
   lifecycle, NEVER gets a native spec, and is referenced downstream as
-  `adr-N` (which spc-48's RC linkage lint, matching only `itd-N` tokens, already
-  ignores).
+  `adr-N` (which the predecessor store's spc-48 RC linkage lint, matching only
+  `itd-N` tokens, ignored).
 
 ### Plan/reclassify refusal guard
 
@@ -166,9 +175,11 @@ language version. The verdict generalises.
 
 The original draft's full-store acceptance criteria are **superseded-by-decision**
 (the thin-adoption operator deviation recorded above). They are struck through in
-the preserved draft below the line and are NOT requirements of the implementing
-spec. The live acceptance criteria for this intent are owned by
-`spc-56-fourth-intent-kind-decision-thin` (R1–R5); in summary:
+the preserved draft below the line and are NOT requirements of any spec. The
+thin-adoption criteria were written as R1–R5 of
+`spc-56-fourth-intent-kind-decision-thin` in the predecessor store; the live spec
+store holds no spec for this intent (`spec_id: null`), so the criteria below are
+this draft's own, in summary:
 
 - *Given* a product thinker records a standing choice, *when* they run
   `/abcd:intent "we use Postgres for the audit trail"`, *then* the capture
@@ -229,7 +240,7 @@ spec. The live acceptance criteria for this intent are owned by
 
 ### ~~Audit / fidelity~~ (superseded — no decision-kind intent files exist to audit)
 
-- ~~The `intent-fidelity-reviewer` agent (spc-12) gets a Role 1 variant for decisions, with per-decision verdicts (`IMPLEMENTED` / `IMPLEMENTED_WITH_DRIFT` / `NOT_IMPLEMENTED` / `INCONCLUSIVE`).~~
+- ~~The `intent-fidelity-reviewer` agent (spc-12, predecessor store) gets a Role 1 variant for decisions, with per-decision verdicts (`IMPLEMENTED` / `IMPLEMENTED_WITH_DRIFT` / `NOT_IMPLEMENTED` / `INCONCLUSIVE`).~~
 
 ### ~~Original full-store Acceptance Criteria~~ (superseded-by-decision)
 
diff --git a/.abcd/development/intents/drafts/itd-51-harness-adoption-readiness-rubric.md b/.abcd/development/intents/drafts/itd-51-harness-adoption-readiness-rubric.md
index 6f6ac5086..2920282b7 100644
--- a/.abcd/development/intents/drafts/itd-51-harness-adoption-readiness-rubric.md
+++ b/.abcd/development/intents/drafts/itd-51-harness-adoption-readiness-rubric.md
@@ -15,15 +15,15 @@ severity: major
 
 ## Press Release
 
-> **abcd carries a written rubric of what any autonomous harness must guarantee before abcd will drive it — so when a candidate harness for the run seam appears, adoption is a checklist run, not a fresh argument.** abcd is an abstraction layer: operators work the `/abcd:*` surface and abcd drives an autonomous harness underneath through a **pluggable run seam** ([adr-27](../../decisions/adrs/0027-autonomous-run-pluggable-seam.md)). A security review of an early bundled harness surfaced concrete failure modes — unbounded runaway when a session timeout never fires, a worker that can forge its own review verdict, protected paths bypassable through the shell. Those specific defects are addressed where abcd owns the code (spc-33) and bounded where abcd orchestrates the session (spc-37). But the deeper asset is the *generalization*: the same review implicitly defined a set of properties abcd cares about in ANY harness it drives. The pluggable seam makes that rubric load-bearing — a candidate engine is only as safe as it scores. This intent makes the set explicit and durable — a harness-adoption-readiness rubric — so abcd never re-derives "is this safe to drive?" from scratch, and so a future adoption is evaluated against stated requirements instead of vibes.
+> **abcd carries a written rubric of what any autonomous harness must guarantee before abcd will drive it — so when a candidate harness for the run seam appears, adoption is a checklist run, not a fresh argument.** abcd is an abstraction layer: operators work the `/abcd:*` surface and abcd drives an autonomous harness underneath through a **pluggable run seam** ([adr-27](../../decisions/adrs/0027-autonomous-run-pluggable-seam.md)). A security review of an early bundled harness surfaced concrete failure modes — unbounded runaway when a session timeout never fires, a worker that can forge its own review verdict, protected paths bypassable through the shell. Those specific defects were assigned to the predecessor store's spc-33 (abcd-owned code) and spc-37 (abcd-orchestrated sessions); neither spec was carried into the Go rebuild, and the live `spc-33` and `spc-37` are unrelated records. But the deeper asset is the *generalization*: the same review implicitly defined a set of properties abcd cares about in ANY harness it drives. The pluggable seam makes that rubric load-bearing — a candidate engine is only as safe as it scores. This intent makes the set explicit and durable — a harness-adoption-readiness rubric — so abcd never re-derives "is this safe to drive?" from scratch, and so a future adoption is evaluated against stated requirements instead of vibes.
 
 > "The first time we vetted a harness it took a full security review to notice the worker could run for a hundred hours unattended," said Carol, the platform tech lead. "I don't want to re-learn that the hard way on the next one. I want a page that says: here is what abcd refuses to drive blind — bounded runtime, verdict integrity it can't forge, a real boundary on what it can write and push. Score the candidate against it. Done."
 
 ## Why This Matters
 
-abcd's whole proposition is that operators trust the `/abcd:*` surface and stay out of the dependency's complexity. That trust is only honest if abcd itself knows what it is willing to drive. Right now that knowledge is implicit — scattered across review findings, two specs (spc-33, spc-37), and institutional memory. The moment a candidate harness for the run seam appears, that implicit knowledge has to be re-assembled under time pressure, which is exactly when important properties get dropped.
+abcd's whole proposition is that operators trust the `/abcd:*` surface and stay out of the dependency's complexity. That trust is only honest if abcd itself knows what it is willing to drive. Right now that knowledge is implicit — scattered across review findings, two specs of the predecessor store (spc-33, spc-37), and institutional memory. The moment a candidate harness for the run seam appears, that implicit knowledge has to be re-assembled under time pressure, which is exactly when important properties get dropped.
 
-A written rubric converts a one-off security review into a reusable adoption gate. It also sharpens spc-37: spc-37 enforces guarantees for the harness abcd drives *today*; this rubric states the guarantees abcd requires of *any* harness, so spc-37 reads as one instantiation of the rubric rather than an ad-hoc list. The rubric is forward-looking and has no implementation surface of its own — it is a decision artifact (a scored checklist) that downstream adoption work consumes.
+A written rubric converts a one-off security review into a reusable adoption gate. It also sharpens the predecessor store's spc-37, which enforced guarantees for the harness abcd drove then; this rubric states the guarantees abcd requires of *any* harness, so a harness-specific guarantee list reads as one instantiation of the rubric rather than an ad-hoc list. The rubric is forward-looking and has no implementation surface of its own — it is a decision artifact (a scored checklist) that downstream adoption work consumes.
 
 Critically, this is **not** a plan to swap the configured harness. This intent only ensures abcd is *ready to evaluate* a candidate whenever one becomes available — readiness, not migration.
 
@@ -32,12 +32,12 @@ Critically, this is **not** a plan to swap the configured harness. This intent o
 - A durable rubric document enumerating the properties abcd requires of any harness it will drive under the hood, grouped by the categories the 2026-06-02 review exposed: bounded runaway (wall-clock / loop-count / token budget that abcd can enforce externally), timeout-mechanism-as-precondition, in-flight pathology detection, review-verdict integrity from the reviewer's own output channel, write/push boundary enforceable in abcd's own layer, and no info-leak from orchestration artifacts.
 - For each rubric item: a plain statement of the required guarantee, and how abcd would verify a candidate satisfies it (a check, not just a wish).
 - A short scoring/decision shape so a candidate can be marked pass / conditional / fail against the rubric, with conditional-pass tied to what abcd's own wrapper would have to supply.
-- A back-reference from spc-37 noting it is the today-harness instantiation of this rubric.
+- A back-reference from whichever live spec enforces the guarantees for the harness abcd drives, noting it is the instantiation of this rubric (the predecessor store's spc-37 played that role; no live spec does).
 
 ## What's Out of Scope
 
 - **Choosing or building a replacement harness.** No replacement is planned; this is the evaluation rubric only.
-- **Fixing the 2026-06-02 findings.** Those land in spc-33 (abcd-owned code) and spc-37 (abcd-orchestration guarantees). This intent generalizes the *requirements*, it does not re-fix.
+- **Fixing the 2026-06-02 findings.** Those were assigned to the predecessor store's spc-33 (abcd-owned code) and spc-37 (abcd-orchestration guarantees). This intent generalizes the *requirements*, it does not re-fix.
 - **Editing the current harness's upstream files.** abcd does not fork upstream; the rubric is about what abcd requires and verifies, not about patching what exists.
 - **A new `/abcd:*` surface.** The rubric is a decision artifact, not an operator-facing command.
 
@@ -47,15 +47,15 @@ Critically, this is **not** a plan to swap the configured harness. This intent o
 
 - **Given** the rubric document, **when** a contributor reads it, **then** it lists the abcd-required harness guarantees grouped by category, each with a stated verification check, in plain decision-artifact form (no implementation surface).
 - **Given** a hypothetical candidate harness, **when** it is scored against the rubric, **then** each item resolves to pass / conditional / fail, and any conditional pass names the wrapper-level compensation abcd would have to supply.
-- **Given** spc-37, **when** a reader follows its references, **then** spc-37 is identified as the today-harness instantiation of this rubric, and the rubric does not duplicate spc-37's enforcement detail.
+- **Given** the live spec that enforces the guarantees for the harness abcd drives, **when** a reader follows its references, **then** it is identified as the instantiation of this rubric, and the rubric does not duplicate its enforcement detail.
 - **Given** the rubric, **when** a reader checks its framing, **then** it states explicitly that no replacement is planned and the rubric is readiness-only.
 
 ## Open Questions
 
 - Where does the rubric live as a durable artifact — an ADR (it is a standing decision), a research-note record-type, or a dedicated `roadmap/` document? (Relates to the open research-notes record-type question logged in a working-log entry.)
-- Should the rubric's verification checks be purely manual (a human scores a candidate) or should some be machine-runnable probes reusing the existing external-tool monitor surface (the spc-34 doctor/probes layer)?
+- Should the rubric's verification checks be purely manual (a human scores a candidate) or should some be machine-runnable probes reusing the existing external-tool monitor surface (the doctor/probes layer of spc-34, predecessor store)?
 - Does the rubric also cover non-safety adoption properties (cost, latency, observability, recovery), or stay scoped to the safety/integrity properties the 2026-06-02 review exposed?
-- How does the rubric stay in sync when spc-33/spc-37 land and refine the guarantee set — is the rubric the source of truth those specs cite, or a downstream summary?
+- How does the rubric stay in sync when a live spec refines the guarantee set — is the rubric the source of truth such a spec cites, or a downstream summary?
 
 ## Audit Notes
 
@@ -65,17 +65,23 @@ _Empty. Populated by intent-fidelity-reviewer when intent moves to shipped/._
 
 - Source: the security/architecture review block in a dated working-log entry (2026-06-02),
   generalized from specific findings into standing requirements.
-- Instantiated-by: **spc-37** (abcd orchestration-layer safety when driving the
-  harness today) — the rubric's first concrete application.
-- Routed-here: the `[external-dep]` harness halves of spc-33's cluster-I
+- Instantiated-by: **spc-37, predecessor store** (abcd orchestration-layer safety
+  when driving the harness of the time) — the rubric's first concrete
+  application. The Go rebuild carried no successor spec.
+- Routed-here: the `[external-dep]` harness halves of the predecessor store's
+  spc-33 cluster-I
   deferrals — **I-D1** (abstraction-layer boundary) and **I-D2** (review-queue
   auto-drain) each split an abcd-owned half (routed to itd-53) from an
   `[external-dep]` harness half. Those external-dep halves are owned by the
-  harness-readiness rubric (this intent) and enforced today by **spc-37**, not
-  built in the spc-33 sweep. Tracked by the `routed_from` tokens
-  `spc-33:I-D1-extdep` and `spc-33:I-D2-extdep`.
-- Sibling cleanup: **spc-33** (Phase 3→4 cleanup) — fixes the abcd-owned defects
-  the same review found.
+  harness-readiness rubric (this intent) and were enforced by the predecessor
+  store's spc-37, not built in its spc-33 sweep. Tracked by the `routed_from`
+  tokens `spc-33:I-D1-extdep` and `spc-33:I-D2-extdep`, which name the
+  predecessor store's spc-33, not the live one.
+- Sibling cleanup: **spc-33, predecessor store** (Phase 3→4 cleanup) — the
+  abcd-owned defects the same review found.
+- Amended 2026-09-26 (iss-239): every `spc-N` in this draft names the retired
+  predecessor spec store; the live `spc-33`, `spc-34` and `spc-37` are
+  unrelated records (see the specs charter, "Two `spc-N` Namespaces").
 - Principle: the abcd abstraction-layer boundary — `/abcd:*` is where abcd's
   guarantees live; abcd must know what it requires of anything it drives beneath
   that surface.
diff --git a/.abcd/development/intents/drafts/itd-55-first-principles-foundations-auditor.md b/.abcd/development/intents/drafts/itd-55-first-principles-foundations-auditor.md
index 14e4d3b47..8aeaaa319 100644
--- a/.abcd/development/intents/drafts/itd-55-first-principles-foundations-auditor.md
+++ b/.abcd/development/intents/drafts/itd-55-first-principles-foundations-auditor.md
@@ -65,7 +65,7 @@ _Empty. Populated by intent-fidelity-reviewer when intent moves to shipped/._
   (the `first-principles-analysis` skill — Aristotelian *archai*: regress
   terminus, four causes, domain-appropriateness).
 - Complements: `skills/abcd-intent-grill/` (interactive criteria challenge) and
-  the spc-12 fidelity reviewer (intent-vs-delivery) — three distinct lenses that
+  the fidelity reviewer of spc-12, predecessor store (intent-vs-delivery) — three distinct lenses that
   compose.
 - Sibling harvest: the `socratic-grill` skill's domain-agnostic vocabulary +
   temperature modes are routed separately as an abcd-intent-grill enhancement
diff --git a/.abcd/development/intents/drafts/itd-57-manual-hold-sentinel.md b/.abcd/development/intents/drafts/itd-57-manual-hold-sentinel.md
index 3838a94cd..f0545a9b7 100644
--- a/.abcd/development/intents/drafts/itd-57-manual-hold-sentinel.md
+++ b/.abcd/development/intents/drafts/itd-57-manual-hold-sentinel.md
@@ -59,11 +59,11 @@ This is voyage-agnostic: every voyage that runs an autonomous loop eventually ne
 
 ## Audit Notes
 
-Captured 2026-06-12 from a facilitator decision while planning the session-layer activation spec (spc-58): the spec needed to be planned and double-backend reviewed but hard-blocked from run-seam pickup. The never-done-dependency mechanism was used ad hoc; this intent promotes it to a configure-time primitive. Hand-authored draft — validate via `/abcd:intent` or the record lint (`abcd docs lint`) before promotion.
+Captured 2026-06-12 from a facilitator decision while planning the session-layer activation spec (spc-58, predecessor store): the spec needed to be planned and double-backend reviewed but hard-blocked from run-seam pickup. The never-done-dependency mechanism was used ad hoc; this intent promotes it to a configure-time primitive. Hand-authored draft — validate via `/abcd:intent` or the record lint (`abcd docs lint`) before promotion.
 
 ## References
 
 - The native spec store's selector — the "skip specs blocked by a non-done spec-level dependency" rule this rides (referenced by behaviour, not a fixed location).
 - The native spec store's close path — the accidental-completion path the sentinel must be guarded against (a zero-task sentinel vacuously satisfies "no incomplete tasks"); the productized primitive should make `spec close` refuse the sentinel.
 - The native spec store's `spec add-dep` / `rm-dep` and task-block (task-grain precedent).
-- spc-60 (`spc-60-manual-hold-sentinel-never-completes`) — the current ad-hoc sentinel precursor this intent generalizes; spc-62 (`spc-62-session-enforcement-wiring-n1-a1-a4b2`) — its first real held consumer. spc-48 linkage lint — the guard that must exempt the sentinel.
+- The predecessor store's spc-60 (`spc-60-manual-hold-sentinel-never-completes`) — the ad-hoc sentinel precursor this intent generalizes; its spc-62 (`spc-62-session-enforcement-wiring-n1-a1-a4b2`) — the first held consumer; its spc-48 linkage lint — the guard that had to exempt the sentinel. None of the three was carried into the Go rebuild, and the live `spc-48`, `spc-58`, `spc-60` and `spc-62` are unrelated records (amended 2026-09-26, iss-239; see the specs charter, "Two `spc-N` Namespaces").
diff --git a/.abcd/development/intents/drafts/itd-59-autonomous-worker-transcript-capture.md b/.abcd/development/intents/drafts/itd-59-autonomous-worker-transcript-capture.md
index 4f0ae2240..e57b9ff24 100644
--- a/.abcd/development/intents/drafts/itd-59-autonomous-worker-transcript-capture.md
+++ b/.abcd/development/intents/drafts/itd-59-autonomous-worker-transcript-capture.md
@@ -40,7 +40,7 @@ This is also a *symmetry* failure, not just a missing feature: the native transc
 
 ## What's Out of Scope
 
-- **Re-architecting the transcript corpus.** `~/.abcd/history/<root_sha>/` and its single-owner provisioning (spc-15) stay as-is; this intent FEEDS that store, it does not redesign it.
+- **Re-architecting the transcript corpus.** `~/.abcd/history/<root_sha>/` and its single-owner provisioning (spc-15, predecessor store) stay as-is; this intent FEEDS that store, it does not redesign it.
 - **Capturing the operator's interactive sessions** — already solved (native transcript-corpus redirect). This is only the autonomous-worker half.
 - **The live run-console view** — that is orthogonal to durable capture; unchanged.
 - **Retroactive recovery of already-pruned runs** — this is forward-looking capture, not archaeology of lost logs.
@@ -66,7 +66,7 @@ Open questions for grill: does capturing a headless (non-interactive) run need a
 
 ## References
 
-- The native transcript corpus at `~/.abcd/history/<root_sha>/` and its single-owner provisioning (spc-15) — the store this feeds
+- The native transcript corpus at `~/.abcd/history/<root_sha>/` and its single-owner provisioning (spc-15, predecessor store) — the store this feeds
 - `.abcd/development/research/notes/ahoy-history-store-manual-scaffolding.md` (the transcript-store design this feeds)
 - ADR-29 (native transcript corpus), ADR-27 (pluggable autonomous seam)
 - Related: the abcd transparency/provenance promise in the brief (`01-product/`), itd-58 (a sibling autonomous-run-provenance closure)
diff --git a/.abcd/development/intents/drafts/itd-62-pluggable-safety-gate.md b/.abcd/development/intents/drafts/itd-62-pluggable-safety-gate.md
index b6d434352..124f7822d 100644
--- a/.abcd/development/intents/drafts/itd-62-pluggable-safety-gate.md
+++ b/.abcd/development/intents/drafts/itd-62-pluggable-safety-gate.md
@@ -78,7 +78,7 @@ _Empty. Populated by intent-fidelity-reviewer when intent moves to shipped/._
   mechanisms in the companion harness.
 - Governing constraints: abcd never forks/patches/reimplements a dependency
   (wrap + configure only); abcd must run locally, independent of Claude Code.
-- Reuses the fail-closed, four-verdict posture of the spc-12 fidelity reviewer
+- Reuses the fail-closed, four-verdict posture of the fidelity reviewer of spc-12 (predecessor store)
   and the native ship gate (scanner-unavailable → refuse, never silent
   pass).
 - Brief-change dependency: introducing framework-provided "validation
diff --git a/.abcd/development/intents/planned/itd-2609212137116617-a-new-capture-or-draft-is-matched-against-the-record-before.md b/.abcd/development/intents/shipped/itd-2609212137116617-a-new-capture-or-draft-is-matched-against-the-record-before.md
similarity index 97%
rename from .abcd/development/intents/planned/itd-2609212137116617-a-new-capture-or-draft-is-matched-against-the-record-before.md
rename to .abcd/development/intents/shipped/itd-2609212137116617-a-new-capture-or-draft-is-matched-against-the-record-before.md
index 5beb057a3..4856542f9 100644
--- a/.abcd/development/intents/planned/itd-2609212137116617-a-new-capture-or-draft-is-matched-against-the-record-before.md
+++ b/.abcd/development/intents/shipped/itd-2609212137116617-a-new-capture-or-draft-is-matched-against-the-record-before.md
@@ -69,7 +69,8 @@ _None open._
 
 ## Audit Notes
 
-_Empty. Populated by intent-auditor when intent moves to shipped/._
+<!-- abcd-review: OWED receipt=rcp-1887e5f574ef -->
+Fidelity review OWED (receipt rcp-1887e5f574ef).
 
 ## Grounds
 
diff --git a/.abcd/development/intents/shipped/itd-34-three-intent-kinds.md b/.abcd/development/intents/shipped/itd-34-three-intent-kinds.md
index 2766fdc1d..860257315 100644
--- a/.abcd/development/intents/shipped/itd-34-three-intent-kinds.md
+++ b/.abcd/development/intents/shipped/itd-34-three-intent-kinds.md
@@ -129,7 +129,7 @@ This mirrors the lint-code namespace pattern in [`05-internals/06-lint.md`](../.
 - **A closed enum of discipline subtypes.** Deferred per the revisit triggers above.
 - **Cross-bundle dependency tracking** ("bundle X must ship before bundle Y"). Out of scope; bundles are a delivery shape, not a dependency graph.
 - **Auto-merging coupled intents at capture time.** The LLM classifier proposes; the user binds at plan time. The framework never silently merges intents.
-- **A fourth kind** for some hypothetical case the three kinds don't cover. If a fourth kind is needed, it lands as a future intent, not this one. **Lineage update (itd-44, spc-56):** the standing-infrastructure-choice case the three kinds don't fit landed as [itd-44](../drafts/itd-44-fourth-intent-kind-decision.md) — but *not* as a fourth persisted `kind`. itd-44 adds a fourth capture-time *verdict*, `decision`, that routes a confirmed standing choice into the existing ADR store (`adr-N`); the persisted `kind` enum here stays **three-valued**, and there is deliberately no `intents/decisions/` lifecycle.
+- **A fourth kind** for some hypothetical case the three kinds don't cover. If a fourth kind is needed, it lands as a future intent, not this one. **Lineage update (itd-44; amended 2026-09-26, iss-239):** the standing-infrastructure-choice case the three kinds don't fit is drafted as [itd-44](../drafts/itd-44-fourth-intent-kind-decision.md) — and *not* as a fourth persisted `kind`. itd-44 proposes a fourth capture-time *verdict*, `decision`, that would route a confirmed standing choice into the existing ADR store (`adr-N`); it is a draft with no live spec, and nothing in the binary implements the verdict (its thin-adoption design was ratified against spc-56 of the predecessor store, not the live `spc-56`). The persisted `kind` enum here stays **three-valued**, and there is deliberately no `intents/decisions/` lifecycle.
 - **Migrating disciplines into the brief itself.** Disciplines live in `intents/disciplines/` so they have the same lifecycle, lint, and frontmatter discipline as other intents. Folding them into the brief would lose the lifecycle handling. The brief *describes* the discipline kind in its mental-model and intent-surface sections; the discipline files themselves stay under `intents/`.
 
 ## Mechanism
diff --git a/.abcd/development/intents/planned/itd-63-setup-wizard-explains-installs.md b/.abcd/development/intents/shipped/itd-63-setup-wizard-explains-installs.md
similarity index 98%
rename from .abcd/development/intents/planned/itd-63-setup-wizard-explains-installs.md
rename to .abcd/development/intents/shipped/itd-63-setup-wizard-explains-installs.md
index 69e8fff29..e92775125 100644
--- a/.abcd/development/intents/planned/itd-63-setup-wizard-explains-installs.md
+++ b/.abcd/development/intents/shipped/itd-63-setup-wizard-explains-installs.md
@@ -76,7 +76,8 @@ _None open; decisions 1 to 3 settle the three this record carried._
 
 ## Audit Notes
 
-_Empty. Populated by intent-fidelity-reviewer when intent moves to shipped/._
+<!-- abcd-review: OWED receipt=rcp-3c9fb4ba9770 -->
+Fidelity review OWED (receipt rcp-3c9fb4ba9770).
 
 ### Linkage note (spc-83.5)
 
diff --git a/.abcd/development/plans/2026-08-11-install-experience.md b/.abcd/development/plans/2026-08-11-install-experience.md
index 746c73a80..2d76c117f 100644
--- a/.abcd/development/plans/2026-08-11-install-experience.md
+++ b/.abcd/development/plans/2026-08-11-install-experience.md
@@ -70,7 +70,7 @@ assume, and the contradictions are the point.
    mechanism the same release removes.
 8. **iss-163/iss-164 (plain-language prompt help, persona-readable summary) are
    out of both cuts**, deferred to
-   [itd-63](../intents/planned/itd-63-setup-wizard-explains-installs.md).
+   [itd-63](../intents/shipped/itd-63-setup-wizard-explains-installs.md).
    Real, and larger than everything else here combined; keeping them out keeps
    both cuts reviewable.
 
diff --git a/.abcd/development/plans/2026-08-15-facilitator-experience.md b/.abcd/development/plans/2026-08-15-facilitator-experience.md
index e80871890..09e36d1a2 100644
--- a/.abcd/development/plans/2026-08-15-facilitator-experience.md
+++ b/.abcd/development/plans/2026-08-15-facilitator-experience.md
@@ -44,7 +44,7 @@ Ordering and item specs unchanged from that plan:
    — canonical per-choice help text lives in core; the foundation item.
 2. **[iss-164](../../work/issues/resolved/iss-164-the-ahoy-install-completion-summary-is-written-for-abcd-s-im.md)**
    (blocked by iss-163) — persona-readable result summaries.
-3. **[itd-63](../intents/planned/itd-63-setup-wizard-explains-installs.md)**
+3. **[itd-63](../intents/shipped/itd-63-setup-wizard-explains-installs.md)**
    — the intent frame A1/A2 deliver into. Lifecycle first: planned but
    spec-less, so the first milestone is the spec and `intent ready`, never
    code.
diff --git a/.abcd/development/readings/README.md b/.abcd/development/readings/README.md
index dc611a141..57890a484 100644
--- a/.abcd/development/readings/README.md
+++ b/.abcd/development/readings/README.md
@@ -107,7 +107,10 @@ document the floor cannot resolve at all — a fence delimiter inside the
 frontmatter block, a delimited block displaced from line 0 by blank lines,
 whitespace or an HTML comment, a compact mapping nested in a block sequence, an
 explicit key in a flow mapping, an attribute value that opens on the line after
-its equals sign, and a raw heading element that is never closed. Each is refused
+its equals sign, a raw heading element that is never closed, and raw heading
+elements whose titles overlap past the floor's read budget — a run of openers
+sharing one far bound, whose titles cannot be read in time linear in the
+document (iss-2608301421382564). Each is refused
 by name, naming the document, the line and the shape, because a control that
 cannot examine an input refuses it rather than admitting it silently (adr-56). Prose-borne warmth inside an admitted chapter has no structural
 signal: the chapter-level bound and the glossary discipline carry it, and it is
diff --git a/.abcd/development/release-gate/README.md b/.abcd/development/release-gate/README.md
index 4e6135013..0b63f49c5 100644
--- a/.abcd/development/release-gate/README.md
+++ b/.abcd/development/release-gate/README.md
@@ -157,12 +157,23 @@ brief doc plus one per surface), and the prompt (context plus both direction
 templates, with the prompt's own `sha256` over the three parts joined by blank
 lines). The context names every `commands/` page and every `agents/` prompt,
 and says that a surface claim found outside the pinned chapters is in scope.
-Two honest runs of the same tier therefore mean the same thing — the
-maintainer no longer chooses the scope per run. The
+Two honest runs of the same tier therefore examine the same scope — no run
+chooses its own. The
 [`brief-surface-crosscheck.js`](brief-surface-crosscheck.js) detector consumes
 this manifest as its input rather than composing an ad-hoc list.
 
-Pinning makes runs comparable to each other, not to the tree: a surface that
+Pinning fixes the inputs, not the findings. The checkers are LLM agents, so two
+runs of one tier over byte-identical inputs return different findings: three
+full-tier runs on 2026-08-23 against one manifest returned 125, 126 and 147,
+and the two whose brief was byte-identical differed by 21 findings, with
+per-chapter counts moving in both directions (iss-2608231409595789). Which
+chapters a run implicates is broadly stable across runs; how many findings each
+holds, and which class each takes, is not. A receipt's `failing` count is
+therefore an observation from one run, not a metric: comparing it with another
+release's count says nothing about whether drift grew or shrank, and a finding
+class's count is no basis for scoping an intent.
+
+Pinning makes runs comparable in scope to each other, not to the tree: a surface that
 ships without joining the pin is invisible to a run that obeys it, and the
 receipt attests coverage it never had. `TestReleaseGateManifestIsCurrent`
 (`internal/core/lint`) holds the manifest to the tree — every `04-surfaces/`
diff --git a/.abcd/development/release-gate/brief-surface-crosscheck.js b/.abcd/development/release-gate/brief-surface-crosscheck.js
index 9a469104f..f2f91f7b0 100644
--- a/.abcd/development/release-gate/brief-surface-crosscheck.js
+++ b/.abcd/development/release-gate/brief-surface-crosscheck.js
@@ -11,10 +11,12 @@
 //
 // Invoke with args = the pinned input manifest
 // (.abcd/development/release-gate/manifest.json): { briefDocs, surfaces, prompt,
-// ... }. The manifest is the reproducibility anchor (iss-122) — the doc list,
-// the directions, the checker count, and the prompt (context + both direction
+// ... }. The manifest pins the run's inputs (iss-122) — the doc list, the
+// directions, the checker count, and the prompt (context + both direction
 // templates) are fixed there rather than composed ad hoc here, so two honest
-// runs of the same tier mean the same thing. The receipt echoes the manifest's
+// runs of the same tier examine the same scope. It cannot pin the findings: the
+// checkers are LLM agents, and their count and classes vary between runs on
+// identical inputs (iss-2608231409595789). The receipt echoes the manifest's
 // sha256 as manifestHash and the depth it ran at as tier; receipt_gate refuses a
 // receipt whose manifestHash mismatches or whose tier is too shallow for the
 // release's impact class.
diff --git a/.abcd/development/release-gate/manifest.json b/.abcd/development/release-gate/manifest.json
index 8011dcec0..a75e1166e 100644
--- a/.abcd/development/release-gate/manifest.json
+++ b/.abcd/development/release-gate/manifest.json
@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "detector": "iss35-brief-surface-crosscheck",
-  "_comment": "Pinned input manifest for the iss-35 brief<->surface cross-check (iss-122). This is the reproducibility anchor: two honest runs of the same tier mean the same thing because the doc list, the directions, the checker count, and the prompt are fixed here rather than chosen per run. A receipt echoes this file's sha256 as manifestHash; receipt_gate refuses a receipt whose manifestHash does not match this file's actual hash. checkerCount is briefDocs plus surfaces, and promptHash is sha256 over context, directionA and directionB joined by blank lines; TestReleaseGateManifestIsCurrent holds both to that, and holds the pinned rosters and the brief-doc list to the tree. Compute the hash with `printf 'sha256:'; shasum -a 256 .abcd/development/release-gate/manifest.json | cut -d' ' -f1`.",
+  "_comment": "Pinned input manifest for the iss-35 brief<->surface cross-check (iss-122). This pins the run's INPUTS, not its findings: two honest runs of the same tier examine the same scope because the doc list, the directions, the checker count, and the prompt are fixed here rather than chosen per run, but the checkers are LLM agents, so the findings a run returns and their count and classes vary between runs on identical inputs (iss-2608231409595789: three full-tier runs returned 125, 126 and 147). A receipt's failing count is an observation from one run, not a metric to compare across runs. A receipt echoes this file's sha256 as manifestHash; receipt_gate refuses a receipt whose manifestHash does not match this file's actual hash. checkerCount is briefDocs plus surfaces, and promptHash is sha256 over context, directionA and directionB joined by blank lines; TestReleaseGateManifestIsCurrent holds both to that, and holds the pinned rosters and the brief-doc list to the tree. Compute the hash with `printf 'sha256:'; shasum -a 256 .abcd/development/release-gate/manifest.json | cut -d' ' -f1`.",
   "tiers": {
     "full": "both directions over the full brief-doc list; required for a feature (additive) or breaking release",
     "shallow": "Direction B only (surface->brief); sufficient for a patch (fix/internal) release"
diff --git a/.abcd/development/release-gate/receipt.example.json b/.abcd/development/release-gate/receipt.example.json
index ac6b5b622..5401f5548 100644
--- a/.abcd/development/release-gate/receipt.example.json
+++ b/.abcd/development/release-gate/receipt.example.json
@@ -8,7 +8,7 @@
   "verificationResult": "PROMOTE",
   "judgeModel": "claude-opus-4-8",
   "tier": "full",
-  "manifestHash": "sha256:53303d65e59e63894d3ef2cd50b4503bf70030a79b5c5c179779fe5b7964925f",
+  "manifestHash": "sha256:0262c01bf524de04de8f56fbfd14ea435dc2933fd9ae8bb1cad78aabfa4a6c1e",
   "policy": {
     "detector": "iss35-brief-surface-crosscheck",
     "version": "1",
diff --git a/.abcd/development/release/surface.json b/.abcd/development/release/surface.json
index d741a830e..3b0f3c514 100644
--- a/.abcd/development/release/surface.json
+++ b/.abcd/development/release/surface.json
@@ -129,7 +129,7 @@
     {
       "path": "abcd ahoy install",
       "hidden": false,
-      "sentence": "Apply the install gaps the detection finds: Writes the .abcd/ scaffolding, the name-guard hooks, and the PATH entry; refuses a stale binary before any write.",
+      "sentence": "Apply the install gaps the detection finds: Writes .abcd/, the name-guard hooks and the PATH entry, and installs a tool only on a yes; refuses a stale binary.",
       "flags": [
         {
           "name": "adopt",
@@ -173,6 +173,13 @@
           "required": false,
           "hidden": false
         },
+        {
+          "name": "install-tool",
+          "shorthand": "",
+          "type": "stringSlice",
+          "required": false,
+          "hidden": false
+        },
         {
           "name": "oracle-backend",
           "shorthand": "",
diff --git a/.abcd/development/roadmap/phases/phase-8-brief-currency.md b/.abcd/development/roadmap/phases/phase-8-brief-currency.md
index 20e5a8333..90e39ee23 100644
--- a/.abcd/development/roadmap/phases/phase-8-brief-currency.md
+++ b/.abcd/development/roadmap/phases/phase-8-brief-currency.md
@@ -34,7 +34,8 @@ rather than being smoothed over between cuts.
   the prose around them carries the why and the refusals.
 - The brief-to-surface crosscheck gate runs at every release cut against a
   manifest whose pinned inputs name the current brief and the current
-  surface, so two honest runs mean the same thing.
+  surface, so two honest runs of one tier examine the same scope (their
+  findings are LLM output and vary between runs).
 - The drift records the v0.7.0 receipts opened are resolved, and the two
   exact duplicates are closed as duplicates.
 
diff --git a/.abcd/development/specs/README.md b/.abcd/development/specs/README.md
index 8bcf4f58b..abf01223d 100644
--- a/.abcd/development/specs/README.md
+++ b/.abcd/development/specs/README.md
@@ -40,7 +40,7 @@ record-id seam (`recordid.Minter`, per
 The mint consults no maximum — not the store's, not the intents' `spec_id`
 reservations, not the refs' — so two checkouts minting in the same window
 allocate distinct ids by construction, with no coordination and no network. The
-ordinal ids minted before the seam (`spc-1` … `spc-69`) stay exactly as minted;
+ordinal ids minted before the seam (`spc-2` … `spc-70`) stay exactly as minted;
 the store is dual-vintage but single-grammar, and every consumer parses both.
 
 The write happens under an exclusive advisory lock: `flock(2)` on the `specs/`
@@ -139,32 +139,36 @@ mandating them — the spec body is a design record, not a form.
 
 ---
 
-## Two `spc-N` Namespaces — Always Qualify Above the Ceiling
+## Two `spc-N` Namespaces — Always Qualify a Predecessor Id
 
-The live store holds **spc-2 … spc-42** — 41 records, one per number. `spc-1` is
-reserved by itd-3 and has never been a file in this history.
+The live store holds the ordinals **spc-2 … spc-70**, one record per number, and
+every spec minted since through the timestamp seam. `spc-1` is reserved by itd-3
+and has never been a file in this history.
 
 A **retired predecessor store** minted its own `spc-1 … spc-83`, and prose across
 the record still cites those records — spc-56, spc-66, spc-75 and the bundle
-handle `spc-83-operator-surfaces` among them. The two namespaces overlap, so a
-bare `spc-N` is ambiguous wherever `N` falls inside the live range. Three rules
-follow:
+handle `spc-83-operator-surfaces` among them. The two namespaces overlap for
+every number up to the live ordinal ceiling, so a bare `spc-N` with `N` at or
+below 70 resolves, in the store, to a live spec about something else. Three
+rules follow:
 
 - **Every reference to a predecessor record carries a qualifier.** The
   convention in the record is the parenthetical *"(predecessor store)"* —
   "spc-12 (predecessor store)", or "the predecessor store's spc-66".
-- **An id above the live ceiling belongs to the predecessor store by
-  construction.** `spc-43` … `spc-83` name no live record, so prose citing one
-  means that store even where the qualifier is absent.
-- **Two ids collide outright.** `spc-33` and `spc-37` exist in both namespaces on
-  different subjects: live spc-33 is itd-114's collision-proof record-id mint and
-  live spc-37 is itd-135's abcdev.app landing page, while the predecessor's
-  spc-33 and spc-37 are the harness-security records itd-51 cites. An unqualified
-  reference to either resolves, in the store, to a spec about something else — so
-  it must never be written unqualified.
-
-The backlog of draft intents citing predecessor ids as though they were live is
-tracked as iss-239 in the issue ledger.
+- **An id above the live ordinal ceiling belongs to the predecessor store by
+  construction.** A `spc-N` with `N` from 71 to 83 names no live record, since
+  the live store mints no ordinals past `spc-70`, so prose citing one means that
+  store even where the qualifier is absent.
+- **An id at or below the ceiling collides outright.** The predecessor's spc-33
+  and spc-37 are the harness-security records itd-51 cites, while live spc-33 is
+  itd-114's collision-proof record-id mint and live spc-37 is itd-135's
+  abcdev.app landing page; the same holds for the predecessor's spc-48, spc-56,
+  spc-58, spc-60 and spc-62 that itd-44 and itd-57 cite. An unqualified
+  reference to any of them names the wrong spec, so it must never be written
+  unqualified.
+
+The draft intents qualify every predecessor id their prose cites (iss-239); a
+dated `reclassification_history` reason keeps the words it was written with.
 
 ---
 
diff --git a/.abcd/development/specs/open/spc-2609211955339422-setup-wizard-explains-installs.md b/.abcd/development/specs/closed/spc-2609211955339422-setup-wizard-explains-installs.md
similarity index 60%
rename from .abcd/development/specs/open/spc-2609211955339422-setup-wizard-explains-installs.md
rename to .abcd/development/specs/closed/spc-2609211955339422-setup-wizard-explains-installs.md
index 0b8969b78..1e03b0ea1 100644
--- a/.abcd/development/specs/open/spc-2609211955339422-setup-wizard-explains-installs.md
+++ b/.abcd/development/specs/closed/spc-2609211955339422-setup-wizard-explains-installs.md
@@ -52,3 +52,27 @@ each with a test that the explanation appears and the default holds on a no.
 | 3 unknown tool: generic text, gap captured | scope 1 |
 | 4 the safety gate routes through it | scope 3 |
 | 5 no host dependency | scope 2 |
+
+## Close note
+
+Delivered on 2026-09-26 against the tree as it stands, which differs from the
+record this spec was written from in two places:
+
+- **The safety gate's missing-scanner path** (criterion 4) belongs to itd-62,
+  which is still a draft: no gate on the default branch always blocks on a
+  missing scanner. The one fail-closed missing-scanner path there is the
+  history store's, for a repository that armed the gitleaks adapter
+  (`internal/adapter/gitleaks`, opt-in since the 2026-07-24 ruling that made
+  the native scanner the default). Its refusal now carries the registry's
+  explanation (`tools.Missing`), and `ahoy install` offers the install, as a
+  required tool, for exactly that repository.
+- **The guard's and the launch's tool checks** (scope 3) do not exist: the
+  guard runs no external tool, and the launch scans are native (itd-65). There
+  was nothing to reroute, and nothing was invented.
+
+The other callers are rerouted: `ahoy`'s dependency gap and install step, and
+the missing-`gh` refusal of `ahoy remote` and `site setup`. The trufflehog gap
+was removed rather than routed (iss-2609261447331434): nothing runs trufflehog.
+The unknown-tool gap (criterion 3) is captured, not composed: the explanation
+names it as abcd's own and carries the `abcd capture` line that records it,
+and a test fails on any tool ahoy names that the registry lacks.
diff --git a/.abcd/development/specs/open/spc-2609212141417782-a-new-capture-or-draft-is-matched-against-the-record-before.md b/.abcd/development/specs/closed/spc-2609212141417782-a-new-capture-or-draft-is-matched-against-the-record-before.md
similarity index 69%
rename from .abcd/development/specs/open/spc-2609212141417782-a-new-capture-or-draft-is-matched-against-the-record-before.md
rename to .abcd/development/specs/closed/spc-2609212141417782-a-new-capture-or-draft-is-matched-against-the-record-before.md
index 0151e1a1a..0f92a931f 100644
--- a/.abcd/development/specs/open/spc-2609212141417782-a-new-capture-or-draft-is-matched-against-the-record-before.md
+++ b/.abcd/development/specs/closed/spc-2609212141417782-a-new-capture-or-draft-is-matched-against-the-record-before.md
@@ -40,3 +40,15 @@ The overlap function is the one the embark ranking uses, moved to the record pac
 | 3 never refused | scope 2 |
 | 4 threshold and json | scope 1, 3 |
 | 5 itd-84 rung | scope 4 |
+
+## Amendment (2026-09-26)
+
+The Scope, Approach and Footprint above name a delivery that did not happen
+(iss-2609261631134401). No embark ranking held an overlap function to move: the
+embark ranking is scope 7 of the open reflect spec, spc-2609211751376504, and is
+not yet built. The primitive shipped new, as the package
+`internal/core/record/match` rather than a file in `internal/core/record`,
+because `internal/core/record` imports the capture and intent packages that
+call the matcher, and a matcher there would close an import cycle. The capture
+and intent writers import it directly, and the reflect spec's Approach names
+it as the primitive its embark ranking is to use.
diff --git a/.abcd/development/specs/open/spc-2609211751376504-reflect-command.md b/.abcd/development/specs/open/spc-2609211751376504-reflect-command.md
index 50b94137d..c5d093e99 100644
--- a/.abcd/development/specs/open/spc-2609211751376504-reflect-command.md
+++ b/.abcd/development/specs/open/spc-2609211751376504-reflect-command.md
@@ -68,8 +68,9 @@ interview itself is host-run from `commands/reflect.md`, which renders the
 seed and the five sections and calls `abcd reflect write <phase-id>
 --answers <file>` with the answers. The nudge is one line in `spec close`'s
 ship path. Lifeboat packing extends the record-family list `disembark`
-already carries; the embark ranking is a small term-overlap score in
-`internal/core/lifeboat`, declared a heuristic.
+already carries; the embark ranking scores with the canonical term-overlap
+primitive, `internal/core/record/match` (spc-2609212141417782), declared a
+heuristic.
 
 ## How the criteria are satisfied
 
diff --git a/.abcd/work/issues/open/iss-239-dangling-pre-rebuild-spec-ids-in-the-draft-corpus-itd-44-spc.md b/.abcd/work/issues/open/iss-239-dangling-pre-rebuild-spec-ids-in-the-draft-corpus-itd-44-spc.md
deleted file mode 100644
index 1836e686b..000000000
--- a/.abcd/work/issues/open/iss-239-dangling-pre-rebuild-spec-ids-in-the-draft-corpus-itd-44-spc.md
+++ /dev/null
@@ -1,12 +0,0 @@
----
-schema_version: 1
-id: "iss-239"
-slug: "dangling-pre-rebuild-spec-ids-in-the-draft-corpus-itd-44-spc"
-severity: "major"
-category: "drift"
-source: "agent-finding"
-found_during: "intent-planning-prep"
-found_at: ".abcd/development/intents/README.md"
----
-
-Dangling pre-rebuild spec ids in the draft corpus: itd-44 (spc-56), itd-51 (spc-33/37), itd-57 (spc-48/60/62), itd-61 (spc-75) cite specs from the numbering adr-21/adr-26 reset (live store is spc-1..spc-22). Worse, intents/README.md and itd-34 assert the itd-44 lineage 'landed as itd-44 (spc-56 thin adoption)' — no such spec or decision-verdict code exists, so the record claims a delivery the tree cannot back.
\ No newline at end of file
diff --git a/.abcd/work/issues/open/iss-2608241347321759-isnull-misses-trailing-comment-null-form.md b/.abcd/work/issues/open/iss-2608241347321759-isnull-misses-trailing-comment-null-form.md
deleted file mode 100644
index 1526284c1..000000000
--- a/.abcd/work/issues/open/iss-2608241347321759-isnull-misses-trailing-comment-null-form.md
+++ /dev/null
@@ -1,14 +0,0 @@
----
-schema_version: 1
-id: "iss-2608241347321759"
-slug: "isnull-misses-trailing-comment-null-form"
-severity: "minor"
-category: "bug"
-source: "review-followup"
-found_during: "pr-294"
-found_at: "internal/core/frontmatter/frontmatter.go"
-deferred_after: "v0.10.0"
-deferral_reason: "ruling owed to the product thinker (away; run A 2026-09-25): Should the frontmatter line scanner trim unquoted trailing comments (NULL # x reads null), or document the form unsupported?"
----
-
-frontmatter.Fields trims the captured value but strips nothing after a comment marker, and IsNull compares exact strings, so superseded_by: NULL # no successor is read as the literal string 'NULL # no successor' rather than the null token -- a trailing-comment form valid YAML never resolves as null; follow-up to pr-294 per reviewer (frontmatter self-describes as a line scanner, so decide: trim unquoted trailing comments or document as unsupported) takeover 2026-08-24
\ No newline at end of file
diff --git a/.abcd/work/issues/open/iss-2608310912217521-the-grounds-flag-carries-two-incompatible-grammars-on-one-ve.md b/.abcd/work/issues/open/iss-2608310912217521-the-grounds-flag-carries-two-incompatible-grammars-on-one-ve.md
index 3fe123017..870fe86a1 100644
--- a/.abcd/work/issues/open/iss-2608310912217521-the-grounds-flag-carries-two-incompatible-grammars-on-one-ve.md
+++ b/.abcd/work/issues/open/iss-2608310912217521-the-grounds-flag-carries-two-incompatible-grammars-on-one-ve.md
@@ -9,8 +9,8 @@ found_during: "itd-179-fidelity-audit"
 origin: researcher-authored
 production_mode: hand-written
 found_at: "internal/surface/cli/cli.go"
-deferred_after: "v0.10.0"
-deferral_reason: "ruling owed to the product thinker (away; run A 2026-09-25): Split --grounds into two flag names for its two contracts (token plus floor vs free-text disposition_grounds)?"
+deferred_after: "v0.11.0"
+deferral_reason: "ruling owed to the product thinker (re-deferred by lane drainR1 of autonomous run A, 2026-09-26): the honest fix changes what a person types on released verbs, so it is a surface ruling, not a mechanical one. The choice owed is one of: (a) split the flag name, keeping --grounds for the <token>: <text> contract of capture promote|resolve|wontfix and intent ready and renaming the free-text flags; (b) put capture disposition --grounds through grounds.New, which fails because a disposition carries its own state vocabulary (accepted|rejected|declined|held), not pursued|deferred|declined; or (c) record the divergence as intended. A third grammar has joined since capture: intent condition --grounds is free text held to the substance floor with no token."
 ---
 
 the grounds flag carries two incompatible grammars on one verb family with a floor on three routes and free text on the fourth
diff --git a/.abcd/work/issues/open/iss-2609261447395216-ahoy-install-asks-private-repo-trufflehog-present-confirm.md b/.abcd/work/issues/open/iss-2609261447395216-ahoy-install-asks-private-repo-trufflehog-present-confirm.md
new file mode 100644
index 000000000..f938f816e
--- /dev/null
+++ b/.abcd/work/issues/open/iss-2609261447395216-ahoy-install-asks-private-repo-trufflehog-present-confirm.md
@@ -0,0 +1,14 @@
+---
+schema_version: 1
+id: "iss-2609261447395216"
+slug: "ahoy-install-asks-private-repo-trufflehog-present-confirm"
+severity: "minor"
+category: "drift"
+source: "agent-finding"
+found_during: "autonomous run A resumed 2026-09-25"
+origin: researcher-authored
+production_mode: hand-written
+found_at: "internal/core/ahoy/apply.go"
+---
+
+ahoy install asks 'Private repo + trufflehog present — confirm deep secret scanning' and persists scan.deep in .abcd/config.json, but no scanner reads scan.deep and nothing runs trufflehog, so the answer changes nothing: a person told they enabled deep secret scanning has not. Either wire a trufflehog adapter behind the scanner seam or stop asking (and say the value is inert where it is already set).
diff --git a/.abcd/work/issues/open/iss-2609261536147903-planned-intents-and-disciplines-still-cite-specs-of-the.md b/.abcd/work/issues/open/iss-2609261536147903-planned-intents-and-disciplines-still-cite-specs-of-the.md
new file mode 100644
index 000000000..42324019b
--- /dev/null
+++ b/.abcd/work/issues/open/iss-2609261536147903-planned-intents-and-disciplines-still-cite-specs-of-the.md
@@ -0,0 +1,14 @@
+---
+schema_version: 1
+id: "iss-2609261536147903"
+slug: "planned-intents-and-disciplines-still-cite-specs-of-the"
+severity: "minor"
+category: "drift"
+source: "agent-finding"
+found_during: "autonomous run A resumed 2026-09-25"
+origin: researcher-authored
+production_mode: hand-written
+found_at: ".abcd/development/intents/planned"
+---
+
+Planned intents and disciplines still cite specs of the retired predecessor store unqualified, and such an id at or below spc-70 resolves to a live spec on another subject (spc-12, for one, is live as the disembark grounding spec): itd-48, itd-50 and itd-53 name spc-12, spc-28, spc-29, spc-31, spc-33, spc-43 and spc-52 for the fidelity reviewer, lifecycle hook and cleanup work (which of these are predecessor ids is itself the reading this record owes); itd-24 names spc-66 as the phase-audit receipt; itd-1 and itd-37 name spc-12 as the manual reviewer. The specs charter (Two spc-N Namespaces) rules that every predecessor citation carries the '(predecessor store)' qualifier; iss-239 applied it to the draft corpus only. Each site needs a reading to tell a predecessor citation from a live one, which is why the sweep was not folded into iss-239.
diff --git a/.abcd/work/issues/resolved/iss-239-dangling-pre-rebuild-spec-ids-in-the-draft-corpus-itd-44-spc.md b/.abcd/work/issues/resolved/iss-239-dangling-pre-rebuild-spec-ids-in-the-draft-corpus-itd-44-spc.md
new file mode 100644
index 000000000..5be31e0ec
--- /dev/null
+++ b/.abcd/work/issues/resolved/iss-239-dangling-pre-rebuild-spec-ids-in-the-draft-corpus-itd-44-spc.md
@@ -0,0 +1,20 @@
+---
+schema_version: 1
+id: "iss-239"
+slug: "dangling-pre-rebuild-spec-ids-in-the-draft-corpus-itd-44-spc"
+severity: "major"
+category: "drift"
+source: "agent-finding"
+found_during: "intent-planning-prep"
+found_at: ".abcd/development/intents/README.md"
+resolution: "The draft intents itd-30, itd-44, itd-51, itd-55, itd-57, itd-59 and itd-62 qualify every predecessor-store spec id they cite; itd-44, itd-34 and intents/README.md no longer claim the decision verdict was delivered and say no binary code implements it; the specs charter names the live ordinal ceiling spc-70 and the colliding ids. spc-75 had already left itd-61. The planned-intent sibling is iss-2609261536147903."
+impact: internal
+resolved_by:
+  commit: "934a4934"
+---
+
+Dangling pre-rebuild spec ids in the draft corpus: itd-44 (spc-56), itd-51 (spc-33/37), itd-57 (spc-48/60/62), itd-61 (spc-75) cite specs from the numbering adr-21/adr-26 reset (live store is spc-1..spc-22). Worse, intents/README.md and itd-34 assert the itd-44 lineage 'landed as itd-44 (spc-56 thin adoption)' — no such spec or decision-verdict code exists, so the record claims a delivery the tree cannot back.
+
+## Grounds
+
+- pursued: every spc id a draft intent cites either names the live spec it means or carries the predecessor-store qualifier, and no record states the decision verdict ships; a draft whose bare spc-N names an unrelated live spec, or a sentence saying the classifier emits decision, would show it wrong
diff --git a/.abcd/work/issues/open/iss-2608231409595789-the-manifest-pins-the-inputs-but-the-record-claims-it-pins-the-verdict.md b/.abcd/work/issues/resolved/iss-2608231409595789-the-manifest-pins-the-inputs-but-the-record-claims-it-pins-the-verdict.md
similarity index 82%
rename from .abcd/work/issues/open/iss-2608231409595789-the-manifest-pins-the-inputs-but-the-record-claims-it-pins-the-verdict.md
rename to .abcd/work/issues/resolved/iss-2608231409595789-the-manifest-pins-the-inputs-but-the-record-claims-it-pins-the-verdict.md
index 11f4dc6d7..82dd67087 100644
--- a/.abcd/work/issues/open/iss-2608231409595789-the-manifest-pins-the-inputs-but-the-record-claims-it-pins-the-verdict.md
+++ b/.abcd/work/issues/resolved/iss-2608231409595789-the-manifest-pins-the-inputs-but-the-record-claims-it-pins-the-verdict.md
@@ -7,6 +7,10 @@ category: "bug"
 source: "user-observation"
 found_during: "v0.6.2 release-gate double run 2026-08-23"
 found_at: ".abcd/development/release-gate/manifest.json"
+resolution: "The manifest's comment, the release-gate README, the detector header, the currency test's doc comment and the phase-8 goal claim what the manifest pins — the inputs, and so the scope two runs of one tier examine — and say the findings, their count and their classes vary between runs; the README states that a receipt's failing count is one run's observation, not a metric. Record correction only; the gate's refusals are unchanged."
+impact: internal
+resolved_by:
+  commit: "b2fc7f3b"
 ---
 
 `.abcd/development/release-gate/manifest.json` describes itself as "the
@@ -67,4 +71,8 @@ that issue's own class counts carry the same caveat.
 This is the enforcement-claims-are-facts class again (iss-2608230847432286): a
 record stating an assurance the machinery underneath it does not provide. It was
 found only because a release recovery happened to run the same gate twice in one
-afternoon, which is not something the process would otherwise ever do.
\ No newline at end of file
+afternoon, which is not something the process would otherwise ever do.
+
+## Grounds
+
+- pursued: no record states that two runs of one tier yield comparable findings or that a receipt's count measures drift; a surviving sentence saying runs 'mean the same thing', or a receipt comparison presented as a trend, would show it wrong
diff --git a/.abcd/work/issues/resolved/iss-2608241347321759-isnull-misses-trailing-comment-null-form.md b/.abcd/work/issues/resolved/iss-2608241347321759-isnull-misses-trailing-comment-null-form.md
new file mode 100644
index 000000000..528c6f1d4
--- /dev/null
+++ b/.abcd/work/issues/resolved/iss-2608241347321759-isnull-misses-trailing-comment-null-form.md
@@ -0,0 +1,20 @@
+---
+schema_version: 1
+id: "iss-2608241347321759"
+slug: "isnull-misses-trailing-comment-null-form"
+severity: "minor"
+category: "bug"
+source: "review-followup"
+found_during: "pr-294"
+found_at: "internal/core/frontmatter/frontmatter.go"
+resolution: "Every field reader now honours a trailing comment and the bare-null spellings the way frontmatter.Fields does: Fields already stripped the comment (iss-2608301744268001) and TestFieldsReadsACommentedNullAsNull pins the null half for every spelling; the sweep fixed issueschema.ParseDisposition (comment and null, TestParseDispositionHonoursCommentAndNull) and lint provenanceValue (null asked of the raw scalar, TestRecordProvenanceQuotedNullIsAValue)."
+impact: fix
+resolved_by:
+  commit: "66398414"
+---
+
+frontmatter.Fields trims the captured value but strips nothing after a comment marker, and IsNull compares exact strings, so superseded_by: NULL # no successor is read as the literal string 'NULL # no successor' rather than the null token -- a trailing-comment form valid YAML never resolves as null; follow-up to pr-294 per reviewer (frontmatter self-describes as a line scanner, so decide: trim unquoted trailing comments or document as unsupported) takeover 2026-08-24
+
+## Grounds
+
+- pursued: every reader of a frontmatter value strips a trailing comment and reads a bare null as absent; a record read one way by the board and another by the verb would show it wrong
diff --git a/.abcd/work/issues/open/iss-2608301421382564-a-raw-heading-opener-with-no-hard-bound-renders-its-title-ov.md b/.abcd/work/issues/resolved/iss-2608301421382564-a-raw-heading-opener-with-no-hard-bound-renders-its-title-ov.md
similarity index 65%
rename from .abcd/work/issues/open/iss-2608301421382564-a-raw-heading-opener-with-no-hard-bound-renders-its-title-ov.md
rename to .abcd/work/issues/resolved/iss-2608301421382564-a-raw-heading-opener-with-no-hard-bound-renders-its-title-ov.md
index 5a724abf1..c6cfbeb42 100644
--- a/.abcd/work/issues/open/iss-2608301421382564-a-raw-heading-opener-with-no-hard-bound-renders-its-title-ov.md
+++ b/.abcd/work/issues/resolved/iss-2608301421382564-a-raw-heading-opener-with-no-hard-bound-renders-its-title-ov.md
@@ -7,6 +7,10 @@ category: "bug"
 source: "user-observation"
 found_during: "itd-183-round-10-ruthless"
 found_at: "internal/core/reading/project.go"
+resolution: "The raw heading scan indexes each reading's bounds once and binary-searches per opener (a masked reading that blanks an opener's own > falls back to the walk, charged to a budget), charges every rendered title to a read budget of 8x the document plus 1 MiB and refuses a document whose titles overlap past it, and counts lines incrementally. TestRawHeadingScanStaysLinearInTheOpenerCount now covers the unbounded run, the shared-far-bound run and closed openers at the size cap (57 s and 67 s before, 0.2 s after); TestIndexedHeadingBoundsAgreeWithTheWalk holds the index to the walk."
+impact: fix
+resolved_by:
+  commit: "fce93af7"
 ---
 
 a raw heading opener with no hard bound renders its title over the whole remainder so the scan is quadratic in a shape the linearity test does not cover
@@ -39,3 +43,7 @@ Remedies to weigh together: cap the length of text a title may be read from (a
 heading is not kilobytes long), or give an unbounded opener a bound of the
 document's own end-of-line rather than end-of-file. Seed material for the
 exclusion floor's own intent, with the test's name to correct alongside it.
+
+## Grounds
+
+- pursued: verifyRedaction finishes in time linear in the document for any run of raw heading openers and refuses nothing the corpus holds; a document up to MaxFileBytes that takes seconds, or a committed markdown file refused for its read budget, would show it wrong
diff --git a/.abcd/work/issues/open/iss-2608301646046226-grounds-text-the-floor-accepts-can-be-refused-by-the-site-re.md b/.abcd/work/issues/resolved/iss-2608301646046226-grounds-text-the-floor-accepts-can-be-refused-by-the-site-re.md
similarity index 70%
rename from .abcd/work/issues/open/iss-2608301646046226-grounds-text-the-floor-accepts-can-be-refused-by-the-site-re.md
rename to .abcd/work/issues/resolved/iss-2608301646046226-grounds-text-the-floor-accepts-can-be-refused-by-the-site-re.md
index 92c23dfd9..18a89cc32 100644
--- a/.abcd/work/issues/open/iss-2608301646046226-grounds-text-the-floor-accepts-can-be-refused-by-the-site-re.md
+++ b/.abcd/work/issues/resolved/iss-2608301646046226-grounds-text-the-floor-accepts-can-be-refused-by-the-site-re.md
@@ -7,6 +7,10 @@ category: "bug"
 source: "user-observation"
 found_during: "itd-179-round-5-security"
 found_at: "internal/core/intent/grounds.go"
+resolution: "grounds.New and grounds.NewDerived refuse, with nothing written, a bullet the site renderer refuses, asking the renderer itself through one predicate (mdrender.RefusalIn, the renderer moved to a leaf so the grounds package can import it), strict on reference links and images. TestNewRefusesWhatTheSiteRendererRefuses covers the five reviewed constructs and five siblings from the renderer's refusal list; TestNewDerivedRefusesWhatTheSiteRendererRefuses covers the wontfix path. All 645 committed grounds entries pass, so none is stranded."
+impact: fix
+resolved_by:
+  commit: "cce6eb9f"
 ---
 
 grounds text the floor accepts can be refused by the site renderer and the entry is append only so no verb can remove it
@@ -39,3 +43,7 @@ command this residue can only be removed by hand-editing the committed record.
 The readability guard's own doc is silent about this: it says a bullet that
 fails to raise the count is refused, which is true of `ParseGrounds` and says
 nothing about the second reader that runs in the same preflight.
+
+## Grounds
+
+- pursued: no grounds entry a verb can write makes site build refuse the record it lands in; a grounds text that New accepts and site-render then refuses would show it wrong
diff --git a/.abcd/work/issues/open/iss-2608301747001641-a-malformed-grounds-bullet-on-an-issue-record-reads-as-prose.md b/.abcd/work/issues/resolved/iss-2608301747001641-a-malformed-grounds-bullet-on-an-issue-record-reads-as-prose.md
similarity index 63%
rename from .abcd/work/issues/open/iss-2608301747001641-a-malformed-grounds-bullet-on-an-issue-record-reads-as-prose.md
rename to .abcd/work/issues/resolved/iss-2608301747001641-a-malformed-grounds-bullet-on-an-issue-record-reads-as-prose.md
index ca94ed9fa..30cf98280 100644
--- a/.abcd/work/issues/open/iss-2608301747001641-a-malformed-grounds-bullet-on-an-issue-record-reads-as-prose.md
+++ b/.abcd/work/issues/resolved/iss-2608301747001641-a-malformed-grounds-bullet-on-an-issue-record-reads-as-prose.md
@@ -7,8 +7,10 @@ category: "bug"
 source: "user-observation"
 found_during: "itd-179-round-5-builder"
 found_at: "internal/core/grounds"
-deferred_after: "v0.10.0"
-deferral_reason: "ruling owed to the product thinker (away; run A 2026-09-25): Should a malformed ## Grounds bullet be a gate finding while grounds refusals stay parked (2026-09-09)?"
+resolution: "record_schema now reports every bullet under ## Grounds that the reader drops, on issue and intent records, from grounds.MalformedIn, the other half of the one walk ParseSection takes; the grammar is judged, not the floor, and prose paragraphs stay silent. The tree's one such bullet (iss-2609012039210402) is corrected. Proven by TestRecordSchemaReportsAMalformedGroundsBullet (watched red) and TestMalformedInIsTheReadersComplement."
+impact: fix
+resolved_by:
+  commit: "bc9fca94"
 ---
 
 a malformed grounds bullet on an issue record reads as prose so no gate can review it losing coverage the frontmatter rule had
@@ -26,3 +28,7 @@ That is the same shape as the class this branch has been closing all cycle -- a
 reader declining to see something while nothing downstream knows -- arrived at
 from the other direction, by moving data somewhere the gate does not look. Worth
 weighing before the section form is copied to any other field.
+
+## Grounds
+
+- pursued: a hand-typed bullet the grounds reader drops is named by the record gate; a malformed bullet passing record-lint while no surface shows it would show it wrong
diff --git a/.abcd/work/issues/resolved/iss-2609012039210402-an-override-pii-rules-passes-validate-internal-core-rules-ru.md b/.abcd/work/issues/resolved/iss-2609012039210402-an-override-pii-rules-passes-validate-internal-core-rules-ru.md
index 1b6346c07..e64361e4c 100644
--- a/.abcd/work/issues/resolved/iss-2609012039210402-an-override-pii-rules-passes-validate-internal-core-rules-ru.md
+++ b/.abcd/work/issues/resolved/iss-2609012039210402-an-override-pii-rules-passes-validate-internal-core-rules-ru.md
@@ -18,4 +18,4 @@ An override `{"PII": {"rules": []}}` passes `Validate` (internal/core/rules/rule
 ## Grounds
 
 - pursued: the heading-only block must not render, and the drop must be loud — a domain that silently stops existing is the same suppression-nobody-sees the fix is about
-- rejected: refusing the whole file, the shape the empty-rule-body refusal (iss-2608261550497978) set. That refusal is on a rule BODY inside an otherwise loadable domain; this one would take every other domain down with it, on an upgrade, for a config that worked yesterday. Validate keeps the refusal where it guards abcd's own bundled defaults
+- declined: refusing the whole file, the shape the empty-rule-body refusal (iss-2608261550497978) set. That refusal is on a rule BODY inside an otherwise loadable domain; this one would take every other domain down with it, on an upgrade, for a config that worked yesterday. Validate keeps the refusal where it guards abcd's own bundled defaults
diff --git a/.abcd/work/issues/resolved/iss-2609261447331434-ahoy-offers-trufflehog-as-an-optional-dependency-the-deps.md b/.abcd/work/issues/resolved/iss-2609261447331434-ahoy-offers-trufflehog-as-an-optional-dependency-the-deps.md
new file mode 100644
index 000000000..0308e7bde
--- /dev/null
+++ b/.abcd/work/issues/resolved/iss-2609261447331434-ahoy-offers-trufflehog-as-an-optional-dependency-the-deps.md
@@ -0,0 +1,22 @@
+---
+schema_version: 1
+id: "iss-2609261447331434"
+slug: "ahoy-offers-trufflehog-as-an-optional-dependency-the-deps"
+severity: "minor"
+category: "drift"
+source: "agent-finding"
+found_during: "autonomous run A resumed 2026-09-25"
+origin: researcher-authored
+production_mode: hand-written
+found_at: "internal/core/ahoy/detect.go"
+resolution: "ahoy no longer emits the deps.trufflehog_missing gap: nothing in abcd runs trufflehog, so the explain-then-install mode would have offered to install a program that does nothing for the person. A test pins that no dependency gap names trufflehog."
+impact: fix
+resolved_by:
+  commit: "920afe82"
+---
+
+ahoy offers trufflehog as an optional dependency (the deps.trufflehog_missing gap, 'trufflehog enables deep secret scanning when scan.deep=true', fix hint 'brew install trufflehog') although nothing in abcd runs trufflehog: no adapter exists and scan.deep is read by no scanner. The gap asks a person to install a tool abcd never uses, which the explain-then-install mode (itd-63) would turn into an executed install of a program that does nothing for them.
+
+## Grounds
+
+- pursued: we expect no ahoy run to offer trufflehog while no adapter runs it; shown wrong if a trufflehog gap or install offer reappears without a wired trufflehog adapter
diff --git a/.abcd/work/issues/resolved/iss-2609261604485703-the-tool-installer-s-15-minute-bound-is-not-a-bound-runargv.md b/.abcd/work/issues/resolved/iss-2609261604485703-the-tool-installer-s-15-minute-bound-is-not-a-bound-runargv.md
new file mode 100644
index 000000000..55e793ea3
--- /dev/null
+++ b/.abcd/work/issues/resolved/iss-2609261604485703-the-tool-installer-s-15-minute-bound-is-not-a-bound-runargv.md
@@ -0,0 +1,22 @@
+---
+schema_version: 1
+id: "iss-2609261604485703"
+slug: "the-tool-installer-s-15-minute-bound-is-not-a-bound-runargv"
+severity: "major"
+category: "bug"
+source: "review-followup"
+found_during: "autonomous run A resumed 2026-09-25: review-itd63"
+origin: researcher-authored
+production_mode: hand-written
+found_at: "internal/core/tools/install.go"
+resolution: "runArgv sets cmd.WaitDelay, so the wait for output ends 10s after the step exits or is killed even when a re-grouped descendant holds the pipe; the re-group limit is named in the code, the ahoy brief chapter and the command page."
+impact: fix
+resolved_by:
+  commit: "705b8216"
+---
+
+The tool installer's 15-minute bound is not a bound: runArgv in internal/core/tools/install.go kills the step's own process group on timeout and then waits for cmd.Wait, which waits for the stdout/stderr copier; a descendant that re-groups (setsid/setpgid) survives the group kill, and if it holds the pipe the wait never returns. The comment claims the kill reaches everything the step started, and nothing in the code, the ahoy brief chapter or the command page names the re-group limit.
+
+## Grounds
+
+- pursued: the install and verify calls return within their bound plus the grace whatever a descendant does with the pipe; a runArgv call that blocks past the bound with a Setpgid holder on the pipe would show it wrong
diff --git a/.abcd/work/issues/resolved/iss-2609261604492132-the-gitleaks-install-explanation-the-person-consents-on-says.md b/.abcd/work/issues/resolved/iss-2609261604492132-the-gitleaks-install-explanation-the-person-consents-on-says.md
new file mode 100644
index 000000000..a6388fe91
--- /dev/null
+++ b/.abcd/work/issues/resolved/iss-2609261604492132-the-gitleaks-install-explanation-the-person-consents-on-says.md
@@ -0,0 +1,22 @@
+---
+schema_version: 1
+id: "iss-2609261604492132"
+slug: "the-gitleaks-install-explanation-the-person-consents-on-says"
+severity: "major"
+category: "bug"
+source: "review-followup"
+found_during: "autonomous run A resumed 2026-09-25: review-itd63"
+origin: researcher-authored
+production_mode: hand-written
+found_at: "internal/core/tools/registry.go"
+resolution: "Both Homebrew entries' Effects text opens with one shared sentence naming the network fetch (package-list update, download) and Homebrew's own install analytics, sent unless the person's Homebrew settings turn them off; no entry claims the install sends nothing. The child environment is unchanged (an analytics opt-out is a product-thinker ruling)."
+impact: fix
+resolved_by:
+  commit: "09938d67"
+---
+
+The gitleaks install explanation the person consents on says Homebrew 'sends nothing anywhere', which is untrue: brew install may first update its taps over the network, downloads the package, and by default sends Homebrew's install analytics. The Effects text is the sentence the install question is answered on, so it must state what the install does to the machine and the network.
+
+## Grounds
+
+- pursued: the sentence the person consents on is true of what brew install does; an Effects text that omits the network or the analytics, or claims nothing is sent, would show it wrong
diff --git a/.abcd/work/issues/resolved/iss-2609261604498137-the-ahoy-install-changed-line-reaches-the-terminal.md b/.abcd/work/issues/resolved/iss-2609261604498137-the-ahoy-install-changed-line-reaches-the-terminal.md
new file mode 100644
index 000000000..587271096
--- /dev/null
+++ b/.abcd/work/issues/resolved/iss-2609261604498137-the-ahoy-install-changed-line-reaches-the-terminal.md
@@ -0,0 +1,22 @@
+---
+schema_version: 1
+id: "iss-2609261604498137"
+slug: "the-ahoy-install-changed-line-reaches-the-terminal"
+severity: "minor"
+category: "security"
+source: "review-followup"
+found_during: "autonomous run A resumed 2026-09-25: review-itd63"
+origin: researcher-authored
+production_mode: hand-written
+found_at: "internal/core/tools/install.go"
+resolution: "A program's output becomes result text only through tools.outputLines, which passes each line through termsafe, so the ahoy changed: and note: lines and --json carry no escape, C1 control or bidi override from it."
+impact: fix
+resolved_by:
+  commit: "291410bb"
+---
+
+The ahoy install 'changed:' line reaches the terminal unsanitised, and itd-63 put external process output on it: the verify program's first line (and a failed step's output tail) enters tools.Result.Output raw, flows through Summary() into the ahoy result's changes and notes, and cli.go prints the changes without termsafe, so an escape sequence or bidi control in a program's output rewrites the report.
+
+## Grounds
+
+- pursued: every render of a tools result carries the program's text with no control rune; a Summary or Output that still holds ESC, U+009B or a bidi override after a hostile program's output would show it wrong
diff --git a/.abcd/work/issues/resolved/iss-2609261604499090-the-tool-installer-carries-a-second-ci-detector-internal.md b/.abcd/work/issues/resolved/iss-2609261604499090-the-tool-installer-carries-a-second-ci-detector-internal.md
new file mode 100644
index 000000000..08691af39
--- /dev/null
+++ b/.abcd/work/issues/resolved/iss-2609261604499090-the-tool-installer-carries-a-second-ci-detector-internal.md
@@ -0,0 +1,22 @@
+---
+schema_version: 1
+id: "iss-2609261604499090"
+slug: "the-tool-installer-carries-a-second-ci-detector-internal"
+severity: "minor"
+category: "tech-debt"
+source: "review-followup"
+found_during: "autonomous run A resumed 2026-09-25: review-itd63"
+origin: researcher-authored
+production_mode: hand-written
+found_at: "internal/core/tools/install.go"
+resolution: "internal/cienv.Runner is the one CI detector: the load check and the tool installer both call it and core/implement's copy is gone; the installer also refuses any non-empty CI by an explicit, commented extra check, so GITHUB_ACTIONS=true alone and CI=false both refuse an install."
+impact: fix
+resolved_by:
+  commit: "7f34670d"
+---
+
+The tool installer carries a second CI detector (internal/core/tools/install.go reads CI != "") beside the canonical one in internal/core/implement/load.go (ciRunner: GITHUB_ACTIONS=true, or CI other than empty, false or 0); the copy misses a runner that sets only GITHUB_ACTIONS, and two detectors drift. One primitive should serve both, with the installer keeping its stricter refusal of any non-empty CI.
+
+## Grounds
+
+- pursued: one primitive answers is-this-CI for every verb that asks; a second detector reappearing, or an install proceeding with GITHUB_ACTIONS=true or any CI value set, would show it wrong
diff --git a/.abcd/work/issues/resolved/iss-2609261631120364-match-unreadable-ledger-dir-reads-as-empty.md b/.abcd/work/issues/resolved/iss-2609261631120364-match-unreadable-ledger-dir-reads-as-empty.md
new file mode 100644
index 000000000..dfd1dc1b6
--- /dev/null
+++ b/.abcd/work/issues/resolved/iss-2609261631120364-match-unreadable-ledger-dir-reads-as-empty.md
@@ -0,0 +1,21 @@
+---
+schema_version: 1
+id: "iss-2609261631120364"
+slug: "match-unreadable-ledger-dir-reads-as-empty"
+severity: "minor"
+category: "bug"
+source: "review-followup"
+found_during: "autonomous run A resumed 2026-09-25: review-match"
+origin: researcher-authored
+production_mode: hand-written
+resolution: "an unreadable status directory never reads as an empty one: scanStatusDir lists through readStatusDir, the one place an absent directory and an unreadable one part company (iss-2609261241121312), so the filing-time match reports an unreadable open/ or resolved/ as an unread record set, and capture list and capture status fault naming the directory."
+impact: fix
+resolved_by:
+  commit: "b24ec86f"
+---
+
+The filing-time match reads an unreadable open/ or resolved/ ledger directory as an empty candidate set: capture/match.go matchCandidates discards scanLedger's result for the directory, and scanLedger treats any ReadDir error as an absent ledger, so a capture or intent create reports 'compared N' or 'no record to compare' instead of the unread outcome the intent store's own failure takes. The same absent-or-unreadable conflation makes capture list and capture status count an unreadable status directory as zero records with nothing in the skipped roster.
+
+## Grounds
+
+- pursued: a capture with resolved/ at mode 000 reports the match as unread and links nothing, and list and status carry one read-layer skip naming the directory; TestMatchReportsAnUnreadableStatusDirectoryAsUnread, TestListAndStatusReportAnUnreadableStatusDirectory and TestAScopedListNamesAnUnreadableOpenDirectory would fail if the directory read as empty again
diff --git a/.abcd/work/issues/resolved/iss-2609261631132673-record-lint-misses-ledger-reader-skips.md b/.abcd/work/issues/resolved/iss-2609261631132673-record-lint-misses-ledger-reader-skips.md
new file mode 100644
index 000000000..98f8de74a
--- /dev/null
+++ b/.abcd/work/issues/resolved/iss-2609261631132673-record-lint-misses-ledger-reader-skips.md
@@ -0,0 +1,21 @@
+---
+schema_version: 1
+id: "iss-2609261631132673"
+slug: "record-lint-misses-ledger-reader-skips"
+severity: "minor"
+category: "bug"
+source: "review-followup"
+found_during: "autonomous run A resumed 2026-09-25: review-match"
+origin: researcher-authored
+production_mode: hand-written
+resolution: "The ledger reader's per-file judgement lives in internal/core/issuerecord; capture's scan and record_schema both call issuerecord.Judge, and record_schema reports every issue the reader skips with the reader's layer and reason."
+impact: fix
+resolved_by:
+  commit: "65cce5a5"
+---
+
+record-lint does not report an issue record the ledger reader skips for a value its schema check refuses: duplicates: [bogus] or blocked_by: [bogus] is lint-green while capture list skips the record and abcd <id> names the refusal. record_schema re-derives parts of the reader's judgement (required and unknown fields, the filename agreement) and misses the rest, though its store declaration states that a record the reader would refuse is not lint-green.
+
+## Grounds
+
+- pursued: a committed issue carrying duplicates: [bogus], blocked_by: [bogus] or a list naming one record twice is a record_schema blocker in the reader's words while the live ledger stays clean; TestRecordSchemaReportsEveryRecordTheLedgerReaderSkips would fail if the gate reverted to its own validator, and a skip reason the gate does not report would show it wrong
diff --git a/.abcd/work/issues/resolved/iss-2609261631134401-closed-match-spec-names-a-move-that-did-not-happen.md b/.abcd/work/issues/resolved/iss-2609261631134401-closed-match-spec-names-a-move-that-did-not-happen.md
new file mode 100644
index 000000000..fb6a45c7b
--- /dev/null
+++ b/.abcd/work/issues/resolved/iss-2609261631134401-closed-match-spec-names-a-move-that-did-not-happen.md
@@ -0,0 +1,21 @@
+---
+schema_version: 1
+id: "iss-2609261631134401"
+slug: "closed-match-spec-names-a-move-that-did-not-happen"
+severity: "minor"
+category: "drift"
+source: "review-followup"
+found_during: "autonomous run A resumed 2026-09-25: review-match"
+origin: researcher-authored
+production_mode: hand-written
+resolution: "The closed spec carries a dated amendment naming what shipped: a new primitive at internal/core/record/match, since no embark overlap function existed and internal/core/record would have closed an import cycle."
+impact: internal
+resolved_by:
+  commit: "bee225d9"
+---
+
+The closed spec spc-2609212141417782 says the filing-time overlap function is 'the one the embark ranking uses, moved to the record package' at internal/core/record/match.go. Neither happened: no embark overlap function existed, and the primitive shipped new, at internal/core/record/match (a sub-package, because record imports capture and intent). The closed record states a delivery that did not occur.
+
+## Grounds
+
+- pursued: the amendment states the package the code holds and that the embark ranking is unbuilt scope 7 of spc-2609211751376504; a later embark overlap function predating the match, or the primitive found elsewhere than internal/core/record/match, would show it wrong
diff --git a/.abcd/work/issues/resolved/iss-2609261726015043-record-lint-s-release-gate-derivation-reads-changelog-md-out.md b/.abcd/work/issues/resolved/iss-2609261726015043-record-lint-s-release-gate-derivation-reads-changelog-md-out.md
new file mode 100644
index 000000000..766b720a7
--- /dev/null
+++ b/.abcd/work/issues/resolved/iss-2609261726015043-record-lint-s-release-gate-derivation-reads-changelog-md-out.md
@@ -0,0 +1,22 @@
+---
+schema_version: 1
+id: "iss-2609261726015043"
+slug: "record-lint-s-release-gate-derivation-reads-changelog-md-out"
+severity: "minor"
+category: "security"
+source: "user-observation"
+found_during: "autonomous run A resumed 2026-09-25"
+origin: researcher-authored
+production_mode: hand-written
+found_at: "internal/core/lint/releasegate_derive.go"
+resolution: "changelogAt reads CHANGELOG.md out of git through gitutil.RunCapped at the 4 MiB cap every other CHANGELOG read holds to, and the lint read guard now names an unbounded gitutil.Run asked for a file's content."
+impact: fix
+resolved_by:
+  commit: "9b446292"
+---
+
+record-lint's release-gate derivation reads CHANGELOG.md out of a git tree without a bound: changelogAt (internal/core/lint/releasegate_derive.go) runs an unbounded git cat-file blob and holds the whole blob in memory, where every other CHANGELOG read in lint and core/changelog is capped at 4 MiB (maxChangelogBytes, changelog.MaxChangelogBytes). TestLintReadsNothingUnguarded did not see it because its scanner names filesystem opens and reads only (os, io/fs, io/ioutil, an Open/ReadFile method); a file's content read out of git through gitutil.Run passes it. Found sweeping lint for unbounded record reads while integrating review2-match's pre-existing note (readBucket's first read, already guarded at this tip by b48fd584).
+
+## Grounds
+
+- pursued: an oversized CHANGELOG.md blob is refused, fail-closed, and a new unbounded content read out of git in lint fails TestLintReadsNothingUnguarded; a release-gate derivation that parses a blob past 4 MiB, or a gitutil.Run cat-file blob in lint that the test passes, would show it wrong
diff --git a/.abcd/work/issues/open/iss-2608301908270888-an-unclosed-comment-or-fence-in-an-issue-body-still-locks-th.md b/.abcd/work/issues/wontfix/iss-2608301908270888-an-unclosed-comment-or-fence-in-an-issue-body-still-locks-th.md
similarity index 82%
rename from .abcd/work/issues/open/iss-2608301908270888-an-unclosed-comment-or-fence-in-an-issue-body-still-locks-th.md
rename to .abcd/work/issues/wontfix/iss-2608301908270888-an-unclosed-comment-or-fence-in-an-issue-body-still-locks-th.md
index 8b4488354..04954dc33 100644
--- a/.abcd/work/issues/open/iss-2608301908270888-an-unclosed-comment-or-fence-in-an-issue-body-still-locks-th.md
+++ b/.abcd/work/issues/wontfix/iss-2608301908270888-an-unclosed-comment-or-fence-in-an-issue-body-still-locks-th.md
@@ -7,8 +7,7 @@ category: "bug"
 source: "user-observation"
 found_during: "itd-179-fix-delta-ruthless"
 found_at: "internal/core/grounds/record.go"
-deferred_after: "v0.10.0"
-deferral_reason: "ruling owed to the product thinker (away; run A 2026-09-25): Does the record-body repair verb belong in the errata intent (M25), or its own?"
+wontfix_reason: "Declined on the product thinker's ruling of 2026-08-31 (DECISIONS.md, ruling 3): the guard is correct and the hand edit is the accepted repair, so a triage verb that would append a grounds entry below an unclosed comment or fence refuses rather than landing an entry no reader can see. What the fix/drain-record-reading branch still improved: the refusal, which already named the construct, its body line and the opener's text, now also says the exit, close or remove the opener in a text editor and re-run. A record-body repair verb, if wanted, is its own intent, as the ruling says."
 ---
 
 an unclosed comment or fence in an issue body still locks the record out of every triage verb and no open record tracks it
@@ -79,3 +78,7 @@ own intent rather than a fix bolted onto a shipped one.
 
 Stays OPEN at minor: the tool still stops mid-workflow and hands the operator a
 text editor, which is a real cost even if it is not a lockout.
+
+## Grounds
+
+- declined: refusing is correct because an entry appended below an unclosed opener cannot be read back; an operator unable to repair the record from the refusal message alone would show it wrong
diff --git a/ACKNOWLEDGEMENTS.md b/ACKNOWLEDGEMENTS.md
index 6164897dc..63a7584e0 100644
--- a/ACKNOWLEDGEMENTS.md
+++ b/ACKNOWLEDGEMENTS.md
@@ -166,6 +166,11 @@ Ideas and methodologies that shaped the design — not code abcd depends on.
   fix) while rejecting their implicit background network check: abcd implements
   the same grammar over disk-only sources, and the network answers only an
   explicit `--check` (adr-38).
+- **Homebrew (BSD-2-Clause)** — the package manager the tool registry's install
+  steps run (`brew install <formula>`, on macOS and on Linux), chosen as the one
+  manager with a single fixed command on both supported platforms, so an
+  explained install is an argv abcd can show exactly and run only on a yes
+  (itd-63). <https://brew.sh>
 - **git's editor hand-off (`GIT_EDITOR`, then `$VISUAL`, then `$EDITOR`)** — the
   order and the shape bare `abcd report` follows to open the report skeleton:
   `$VISUAL` before `$EDITOR`, run through the shell so the setting may carry
@@ -264,6 +269,16 @@ Ideas and methodologies that shaped the design — not code abcd depends on.
   (adr-2609212115255771, decision 4; itd-2609212103565953): a spec lists its
   steps under a `## Steps` section (`internal/core/spec/steps.go`), and a
   remainder carries forward the steps not yet landed.
+- **Inverse document frequency (Karen Spärck Jones, "A statistical
+  interpretation of term specificity and its application in retrieval",
+  *Journal of Documentation* 28, 1 (1972), 11–21,
+  [doi:10.1108/eb026526](https://doi.org/10.1108/eb026526))** — the idea that a
+  term few documents carry says more about a document than one most of them
+  carry. The filing-time match weights every shared term by it
+  (itd-2609212137116617, `internal/core/record/match`), so the words common to
+  the whole record do not make two unrelated findings look alike. Linear's
+  similar-issue detection, advisory and at issue creation (cited in itd-84),
+  is the precedent for running the match at filing and never refusing on it.
 
 ## References & sources
 
diff --git a/commands/ahoy.md b/commands/ahoy.md
index 57582e10e..6fd9aee02 100644
--- a/commands/ahoy.md
+++ b/commands/ahoy.md
@@ -62,7 +62,12 @@ Then summarise the JSON for the user:
   verbatim: it is the one sentence stating what the private layer does NOT cover,
   and a paraphrase drops the half that matters.
 - `gaps` — how many are outstanding, and for each actionable one its `title`,
-  `category`, and `fix_hint`; call out which are `required`.
+  `category`, and `fix_hint`; call out which are `required`. A `dependency` gap
+  carries `tool`, the tool registry's explanation: relay `what`, the
+  `requirement` for `capability_name`, `without_it`, `does`, the exact `step`
+  and `effects` (what the install does on the machine and over the network,
+  Homebrew's own analytics included) rather than a bare command, so the
+  person can judge the install.
 
 If there are actionable gaps, tell the user to run `/abcd:ahoy install` to apply
 them. If `folder_kind` is `unmanaged-folder`, note there is nothing to act on
@@ -159,6 +164,33 @@ harness-wide setting, and never accepts a model-tier routing table (below),
 because a table decides which model every delegated step asks for. When the result carries `optional_skipped`, report it and
 offer the `yes |` form above as the way to apply it.
 
+**The tool question.** When a `dependency` gap is present and its category is
+approved, each missing tool is its own question, and a piped answer never
+answers it: installing runs a program on the machine. At a terminal the install
+shows the explanation and asks `Install <tool> now by running <step>? [y/N]`.
+Through this page, ask the user with the host's question tool instead: present
+the gap's `tool` explanation (what it is, whether this capability needs it, what
+works without it, the exact step, what the install does), and only on their yes
+run
+
+```bash
+"${CLAUDE_PLUGIN_ROOT}/abcd" ahoy install --install-tool <tool> --json
+```
+
+`--install-tool` is the relayed yes, for the named tool only, and it also
+answers the `dependency` category's question, which is then not asked (so a
+piped answer stream has one question fewer); never pass it without the user's
+answer. The result's `changes` reports what ran and whether
+its verify passed; a no, a failed step or a missing package manager is a `notes`
+line ending in what the capability continues on (`continuing on the native
+secret scanner`). The step runs in its own process group, bounded at 15
+minutes, and a timeout kills that group; a process the step moves out of the
+group (`setsid`) escapes the kill and can outlive the run, so abcd stops
+waiting on its output 10 seconds after the step ends and reports a step that
+left one behind as failed. `--yes` never installs a tool, and a run with `CI` set
+to any value, or with `GITHUB_ACTIONS=true`, installs none and is not asked. A name that is not a tool `ahoy install` checks
+for is refused, naming the ones it does.
+
 **The house-style question.** When the install seeds `.abcd/docs-lint.json`,
 it asks `docs_lint.em_dash_in_list_item (blocking/warning) [warning]`: whether an
 em dash inside a list item, abcd's own house style rather than a currency rule,
@@ -328,7 +360,9 @@ named.
 
 The call goes through the GitHub CLI (`gh`), so the write is made by the user's
 own authenticated identity and abcd never holds a token; if `gh` is absent the
-verb refuses and says so. It is idempotent — a repository already in the desired
+verb refuses, and the refusal carries the tool registry's explanation of `gh`:
+what it is, that these verbs require it, the exact install step and what that
+install does. Relay it; the step is the user's to run. It is idempotent — a repository already in the desired
 state takes no write, and a re-run rewrites nothing in the tree — and it stops
 at the first failed step rather than attempting one that cannot succeed. Relay
 `status`, the resolved `repo`, every `change`, and every `note`: a note is a
diff --git a/commands/capture.md b/commands/capture.md
index 1745652c5..d9709de8e 100644
--- a/commands/capture.md
+++ b/commands/capture.md
@@ -53,7 +53,9 @@ name is not a well-formed record name), `read` (the guarded read refused the
 file itself, such as a symlink or an oversize body), `frontmatter` (the bytes do
 not parse), `schema` (a key or value the issue schema does not accept) or
 `invariant` (the record disagrees with its filename or with the folder holding
-it).
+it). A status directory that exists and cannot be listed is not an entry:
+the board and `list` count nothing from a ledger they could not read, so they
+exit 1 naming the directory.
 
 **Which ledger?** A half-formed observation, question, or nitpick goes to
 `/abcd:capture "…"`; a user-facing change you want to ship goes to
@@ -102,6 +104,36 @@ work settles what a lapse record must carry; the instant the discipline gave way
 is still what the flag exists to record, and a value that is given must be an
 RFC 3339 instant.
 
+### A likely double is linked, never refused
+
+Before the record is written, the text is matched against every open and
+resolved issue's body and every intent's title and press release. The match is
+a lexical heuristic and says so in its output: the score is the share of the
+new text's terms another record already holds, each term weighted by how rare
+it is across the records compared. A record at or above the threshold (`0.6`
+by default) is written onto the new one as a typed link, at most three of them,
+best first:
+
+- `duplicates: [<id>]` when the two hold each other's terms: the same finding
+  filed again;
+- `refines: [<id>]` when the other record holds this one's terms and a good
+  deal more: this one is the narrower case.
+
+Nothing is refused or dropped. The JSON's `match` object carries `matches`
+(each with `id`, `relation`, `score`, `reverse`, `linked` and `shared_terms`),
+`near_misses` (the best five below the threshold, with their scores),
+`threshold`, and `skipped` when nothing was compared: a text with fewer than
+eight distinct terms, a record set that could not be read, or a match
+configuration the reader refuses. Relay each match with its id and relation
+and ask the user to confirm it. A confirmed link is left as it is; a wrong one
+is removed by deleting its line, which leaves an ordinary record. The match
+never proposes `reverses` or `supersedes`: a reversal is a person's judgement.
+
+The threshold and the compared fields are configuration: `match.threshold`
+and `match.fields` (any of `issue.body`, `intent.title`,
+`intent.press_release`) in `.abcd/config.json`, or in `~/.abcd/config.json`
+for every checkout on the machine.
+
 ## Disclosure: where a record came from and how its text was produced
 
 Intent, spec and issue records carry two frontmatter keys, written by the
@@ -277,8 +309,11 @@ closed — `pursued`, `deferred`, `declined` — and the text is free prose:
 when it is not: the refusal on an absent value is parked (iss-2609091009111294)
 until the rethink of the reading work settles what a human is asked for at a
 triage. A malformed value is still refused — an unknown token, a missing colon,
-or a text below the substance floor. Every grounds refusal is a usage error at
-exit 2, on all three routes.
+a text below the substance floor, or a text the site cannot render (an unclosed
+backtick, an image, raw HTML, a reference link), since the entry is append-only
+and the record must still build. A wontfix reason is held to that last check
+too, because its `declined:` entry is written from it. Every grounds refusal is
+a usage error at exit 2, on all three routes.
 `promote <rdi-N>` is the one route that takes no grounds and refuses one handed
 to it: a reading item states its conjecture in its disposition, which promote
 already refuses to act without, so a second one here would reach no record.
@@ -287,6 +322,12 @@ already refuses to act without, so a second one here would reach no record.
 `--grounds "declined: <text>"` overrides that text for the case where the
 conjecture and the user-facing reason are not the same sentence.
 The token there stays `declined`: a wontfix IS the non-action that value names.
+When the record's body leaves an HTML comment or a fence open, every line below
+the opener is masked and no appended entry can be read, so every route that would
+append one refuses and writes nothing — a wontfix always, since it always appends.
+The refusal names the construct and its body line. The repair is a hand edit:
+close or remove the opener in a text editor, then re-run. Promote and resolve
+given no `--grounds` append nothing and act.
 
 **Ask for the expectation and its falsifier.** "Promoted it because it is next"
 restates the decision and records nothing; "promoted it because we expect a
diff --git a/commands/intent.md b/commands/intent.md
index 966ab9d95..b84beccbd 100644
--- a/commands/intent.md
+++ b/commands/intent.md
@@ -75,9 +75,12 @@ capture routes the pieces, it never files a monolith:
    note under the development record's `research/notes/`. That corpus (about
    50 graded captures) is what gates the automated rung.
 
-**Not yet automated.** The deterministic pre-pass and the capture-time
-validator are future rungs of the itd-84 discipline; until they ship, this
-documented protocol is the gate.
+**Partly automated.** The lexical candidate pass of step 2 runs at filing:
+the create command below matches the draft against the record and writes a
+`duplicates:` or `refines:` link for each likely double (itd-2609212137116617).
+The routing, the atomicity smell, the reversal flag and the verdict are future
+rungs of the itd-84 discipline; until they ship, this documented protocol is
+the gate for them.
 
 ## Create a draft
 
@@ -99,6 +102,16 @@ and Acceptance Criteria sections are placeholders that must be replaced — the
 criteria with real Given-When-Then bullets, via the planning interview below —
 before the draft can be planned.
 
+Before the draft is written, its title and press release are matched against
+every open and resolved issue and every intent, by the same lexical heuristic
+`/abcd:capture` uses: a record at or above `match.threshold` (`0.6` by default)
+is written onto the draft as `duplicates: [<id>]` (the same proposal filed
+again) or `refines: [<id>]` (the other record is broader), at most three links.
+The create is never refused by the match. The JSON's `match` object carries the
+matches, the `near_misses` below the threshold with their scores, and `skipped`
+when nothing was compared. Relay each match and ask the user to confirm it; a
+wrong link is removed by deleting its line, which leaves an ordinary draft.
+
 A single whitespace-free word is refused (exit 2, nothing written): a lone
 token reads as a mistyped sub-verb, never as a draft title. A near-miss of a
 real sub-verb is refused the same way, with the correction named. So is a word
@@ -232,8 +245,10 @@ those three records are in is not reachable through this verb.
 restates the decision and records nothing; "planned it because we expect a
 stamped identity to survive rewording, which nothing else does" is a conjecture
 somebody can later find wrong. abcd refuses only the degenerate texts — empty,
-too short, or the vocabulary word repeated back — and cannot tell a conjecture
-from a restatement. That part is yours: put the question to the human and write
+too short, or the vocabulary word repeated back — and text the site cannot
+render, such as an unclosed backtick, an image or raw HTML, because the entry is
+append-only and the record must still build; it cannot tell a conjecture from a
+restatement. That part is yours: put the question to the human and write
 down their answer, not a paraphrase of the route taken. A hand-typed bullet is
 held to the same floor: `- pursued: yes` is not an entry, and the gate reports
 the record as carrying none.
diff --git a/docs/explanation/process.md b/docs/explanation/process.md
index c9175a328..5713a6bea 100644
--- a/docs/explanation/process.md
+++ b/docs/explanation/process.md
@@ -36,6 +36,8 @@ abcd capture "<whatever crossed your mind>"
 
 One line, deliberately shaped like intent capture but for un-typed thoughts: `abcd capture` writes one small record into the repo's issue ledger (`.abcd/work/issues/open/`), minted with a collision-resistant id (`iss-<yymmddHHMMSS><4 random digits>`) that two parallel agents are overwhelmingly unlikely to duplicate, and that nothing ever renumbers. Everything else — severity, category, where it was found — has sensible defaults, so you don't have to decide anything beyond the text itself at this stage.
 
+The one thing capture does decide for you is whether you have written this down before. Before the record is written, its text is compared with every open and resolved issue and every intent, word by word: a record that already holds most of what you wrote is linked from the new one as `duplicates:` (the same finding again) or `refines:` (a narrower case of it), and the command names it. Nothing is refused or merged. The comparison is a heuristic, so a link is a question for you, not a verdict: leave it if it is right, delete the line if it is not.
+
 `abcd capture` essentially decouples retention from classification. Intents demand press-release discipline — a named user, acceptance criteria, a *why*. Forcing a half-formed doubt through that discipline either kills the thought (too much ceremony, you let it go) or pollutes the intent corpus (you file something vague to avoid losing it). The *fast hatch* makes retention almost free — seconds, zero decisions — and defers the "*what is this?*" question to someone in the right seat at the right time.
 
 That "someone" is your technical facilitator, who triages those captures later: They sweep the open captures and route each one — a bug gets fixed (finding first, fix after); a feature seed gets promoted into an intent draft; a doubt about the brief becomes a brief correction; a deliberate non-action goes to `wontfix` with the reasoning recorded, so the question never gets re-litigated.
diff --git a/docs/reference/cli/commands.md b/docs/reference/cli/commands.md
index ed0cc34df..5643377cf 100644
--- a/docs/reference/cli/commands.md
+++ b/docs/reference/cli/commands.md
@@ -78,7 +78,7 @@ Report every install gap, user-scope state included: Writes nothing; refuses any
 
 #### `abcd ahoy install`
 
-Apply the install gaps the detection finds: Writes the .abcd/ scaffolding, the name-guard hooks, and the PATH entry; refuses a stale binary before any write.
+Apply the install gaps the detection finds: Writes .abcd/, the name-guard hooks and the PATH entry, and installs a tool only on a yes; refuses a stale binary.
 
 **Usage:** `abcd ahoy install [flags]`
 
@@ -91,6 +91,7 @@ Apply the install gaps the detection finds: Writes the .abcd/ scaffolding, the n
       --bin-dir string          directory for the PATH entry (default ~/.local/bin, or an existing abcd install adopted in place); fails when it is not writable — abcd never escalates privileges
       --dev                     track-latest dogfood mode: the PATH entry rebuilds from the source tip on every call instead of pinning the built binary
       --docs-target string      which conventions file carries the managed block, which names abcd: claude_md | agents_md | both | skip (default skip)
+      --install-tool strings    answer yes to installing this missing tool (repeatable): the answer a host's question tool relays; without it a tool is installed only on an answer typed at a terminal, never on the approve-everything flag, a piped answer or CI
       --oracle-backend string   oracle backend: host-delegated | native | cli | api | mcp
       --refuse-adopt            decline to adopt an unmanaged repo
       --scan-deep string        enable deep scan: true | false
diff --git a/internal/README.md b/internal/README.md
index fb2b9aefd..7d5190e5d 100644
--- a/internal/README.md
+++ b/internal/README.md
@@ -25,6 +25,13 @@ plugin surface, and a future MCP server share one engine.
   carries, and a record they disagree about is one that sits in the ledger unread
   by every surface. It is not inside `core/capture` because that package's own
   tests import `core/lint`, so a lint importing capture back is an import cycle.
+- **`core/issuerecord/`** — the ledger reader's judgement of one file in a status
+  directory: the guarded read, the frontmatter parse, the schema and the
+  folder-and-filename invariants, and the stage that refused a record it skips.
+  A leaf on the `core/issueschema` precedent: `core/capture` scans the ledger
+  through it, and `core/lint`'s reader-parity leg asks the same judgement through
+  `capture.ReadRefusal`, so the gate and the surfaces reach one verdict on one
+  file rather than two validators agreeing.
 - **`core/grounds/`** — the recorded-grounds vocabulary and its record form: the
   three values (`pursued`, `deferred`, `declined`), the `<token>: <text>` grammar,
   the substance floor that refuses a degenerate text, and the append-only
@@ -135,12 +142,24 @@ plugin surface, and a future MCP server share one engine.
   record scan (`LoadRecordGraph`), never a second parser; the dates come from one
   `git log` pass; the chart arrangements are computed here so the published pages
   need no layout engine and make no requests.
+- **`core/mdrender/`** — the Markdown subset renderer the site publishes the
+  repository's prose through, and `RefusalIn`, the one answer to what that
+  subset refuses. It is a leaf apart from `core/site` because the writers of
+  append-only record prose (`core/grounds`) ask it before they write, and
+  `core/site` imports the record families they belong to.
 - **`core/cite/`** — the live half of the citation gate: the bounded fetcher and
   the refresh that writes the committed baseline `core/lint` then enforces with
   zero network. It is the only place abcd dials out on behalf of documentation,
   and it holds the seam a specialist link checker would later slot into — the
   baseline schema and the lint rules are the contract, the fetcher is a
   replaceable producer.
+- **`core/tools/`** — the explain-then-install mode (itd-63): the curated
+  registry of the external tools abcd knows, the plain-language explanation a
+  verb gives when one is missing, and the one place abcd runs a package
+  manager. It is a trust boundary, and a mode rather than a surface: a verb
+  hands `Install` a confirmation its front door supplies, and what runs is the
+  registry's fixed argv, never composed from input, never a shell, never in CI,
+  and never a program that resolves inside the repository.
 - **`core/lifeboat/`** — the brief↔lifeboat contract. `mapping.go` is the single
   source of truth for which brief section a lifeboat fills from which source
   tier, and it is rendered into the brief's `00-meta.md` with a test asserting
diff --git a/internal/cienv/cienv.go b/internal/cienv/cienv.go
new file mode 100644
index 000000000..5726d9172
--- /dev/null
+++ b/internal/cienv/cienv.go
@@ -0,0 +1,29 @@
+// Package cienv holds the one canonical answer to "is this a CI runner?". Two
+// verbs ask it — the load check (core/implement), which skips on a runner, and
+// the tool installer (core/tools), which never installs on one — and a detector
+// spelled twice is one the two disagree about. It is a leaf below both, because
+// core/implement reaches core/tools through the verbs it composes, so neither
+// can import the other.
+package cienv
+
+import "github.com/intentdriven/abcd/internal/termsafe"
+
+// Runner reports whether the environment is a CI runner, and names the
+// variable that says so: GITHUB_ACTIONS=true, or a CI value other than empty,
+// "false" or "0". The named value is sanitised and capped, since it is the
+// environment's text and a caller prints it.
+func Runner(getenv func(string) string) (string, bool) {
+	if getenv("GITHUB_ACTIONS") == "true" {
+		return "GITHUB_ACTIONS=true", true
+	}
+	switch v := getenv("CI"); v {
+	case "", "false", "0":
+		return "", false
+	default:
+		shown := termsafe.Sanitize(v)
+		if len(shown) > 32 {
+			shown = shown[:32]
+		}
+		return "CI=" + shown, true
+	}
+}
diff --git a/internal/cienv/cienv_test.go b/internal/cienv/cienv_test.go
new file mode 100644
index 000000000..d91f334f0
--- /dev/null
+++ b/internal/cienv/cienv_test.go
@@ -0,0 +1,37 @@
+package cienv
+
+import (
+	"strings"
+	"testing"
+)
+
+func env(m map[string]string) func(string) string { return func(k string) string { return m[k] } }
+
+// TestRunnerNamesTheVariable: GITHUB_ACTIONS=true or a CI value other than
+// empty, "false" or "0" is a runner, and the reason names the variable.
+func TestRunnerNamesTheVariable(t *testing.T) {
+	for _, tc := range []struct {
+		env  map[string]string
+		want string
+	}{
+		{map[string]string{"GITHUB_ACTIONS": "true"}, "GITHUB_ACTIONS=true"},
+		{map[string]string{"CI": "true"}, "CI=true"},
+		{map[string]string{"CI": "1"}, "CI=1"},
+		{map[string]string{"CI": "\x1b[31m" + strings.Repeat("x", 40)}, "CI=?[31m" + strings.Repeat("x", 27)},
+	} {
+		got, ok := Runner(env(tc.env))
+		if !ok || got != tc.want {
+			t.Errorf("%v: Runner = %q, %v; want %q, true", tc.env, got, ok, tc.want)
+		}
+	}
+}
+
+// TestRunnerFalseValuesAreNotCI: an empty, "false" or "0" CI is not a runner,
+// and GITHUB_ACTIONS counts only as "true".
+func TestRunnerFalseValuesAreNotCI(t *testing.T) {
+	for _, m := range []map[string]string{{}, {"CI": ""}, {"CI": "false"}, {"CI": "0"}, {"GITHUB_ACTIONS": "false"}} {
+		if got, ok := Runner(env(m)); ok || got != "" {
+			t.Errorf("%v: Runner = %q, %v; want not a runner", m, got, ok)
+		}
+	}
+}
diff --git a/internal/core/ahoy/ahoy.go b/internal/core/ahoy/ahoy.go
index 41ffa7eec..4773e5374 100644
--- a/internal/core/ahoy/ahoy.go
+++ b/internal/core/ahoy/ahoy.go
@@ -12,6 +12,8 @@
 // routed through the injected Prompter seam.
 package ahoy
 
+import "github.com/intentdriven/abcd/internal/core/tools"
+
 // FolderKind is the classification of the folder ahoy runs in. There is no
 // workspace layer: abcd manages exactly one kind of folder, a repository.
 type FolderKind string
@@ -36,7 +38,10 @@ const (
 	ConfigChange GapCategory = "config-change"
 	// PluginOwned covers the marker block and the (verify-only) hook manifest.
 	PluginOwned GapCategory = "plugin-owned"
-	// Dependency covers opt-in scanners on PATH (surfaced, never auto-run).
+	// Dependency covers the external tools a capability uses (itd-63): each gap
+	// carries the tool registry's explanation, and a tool is installed only on
+	// an answer the front door's confirmation returns, never on the category
+	// approval alone.
 	Dependency GapCategory = "dependency"
 	// UserState covers ~/.abcd/history registry state (guided, never auto-edited).
 	UserState GapCategory = "user-state"
@@ -63,6 +68,10 @@ type Gap struct {
 	FixHint    string      `json:"fix_hint"`
 	Required   bool        `json:"required"`   // advisory gaps set false
 	Resolvable bool        `json:"resolvable"` // false => diagnostic only
+	// Tool is the tool registry's explanation for a dependency gap (itd-63):
+	// what the tool is, whether this capability needs it, what works without
+	// it, and the exact install step. Absent on every other gap.
+	Tool *tools.Explanation `json:"tool,omitempty"`
 }
 
 // RepoIdentity is the deterministic identity of the repo under cwd.
@@ -146,6 +155,17 @@ type InstallOptions struct {
 	// cannot be determined, otherwise refuses before any write. The override is
 	// the documented escape when a rebuild is not an option. --allow-stale-binary.
 	AllowStaleBinary bool
+	// ConfirmTool is asked, once per missing tool, whether to run the tool
+	// registry's install step (itd-63). The front door supplies it: the CLI
+	// asks at a terminal, or answers yes for a tool the person named with
+	// --install-tool. Nil is a no for every tool, so a caller that asks nothing
+	// installs nothing. The category approval never stands in for it.
+	ConfirmTool tools.Confirm
+	// ApproveDependency answers the dependency category's question yes without
+	// asking it: the front door sets it when the person named a tool to
+	// install (--install-tool), which is that answer given in advance. Every
+	// other category is still asked, or pre-answered, as before.
+	ApproveDependency bool
 }
 
 // InstallResult is the outcome of Install.
diff --git a/internal/core/ahoy/apply.go b/internal/core/ahoy/apply.go
index 755570d5a..b1c8e5c1a 100644
--- a/internal/core/ahoy/apply.go
+++ b/internal/core/ahoy/apply.go
@@ -14,6 +14,7 @@ import (
 
 	"github.com/intentdriven/abcd/internal/core/history"
 	"github.com/intentdriven/abcd/internal/core/identity"
+	"github.com/intentdriven/abcd/internal/core/tools"
 )
 
 // Install runs detect + apply over the approved categories. It is idempotent:
@@ -143,6 +144,7 @@ func install(cwd string, opts InstallOptions, p Prompter) (InstallResult, error)
 		modeForced:  modeForced,
 		binTarget:   binTargetPath,
 		attribution: opts.Attribution,
+		confirmTool: opts.ConfirmTool,
 	}
 
 	// itd-111 refusal: a binary that is stale against its own source tip, or
@@ -331,6 +333,7 @@ type applyCtx struct {
 	modeForced  bool     // the requested install mode differs from the on-disk state
 	attribution bool     // --attribution: opt this repo into the committed prompt hook
 	binTarget   string   // the resolved PATH entry this run installs (never re-derived)
+	confirmTool tools.Confirm
 
 	visibilityForced bool     // an explicit --visibility override overwrote a valid value
 	docsTargetForced bool     // a --docs-target override overwrote a valid value, or this run chose the first one
@@ -432,23 +435,43 @@ func (a *applyCtx) stepIdentityPin() {
 
 func (a *applyCtx) has(id string) bool { return a.gapPresent[id] }
 
-// stepDependencies re-probes PATH; surfaces the fix hint but never auto-runs a
-// package manager.
+// stepDependencies is the explain-then-install mode at ahoy (itd-63). For each
+// dependency gap whose tool is still missing it hands the tool registry's
+// explanation to the front door's confirmation, and runs the registry's step
+// only on a yes. What ran, and whether it verified, is a change; a no, a failure
+// or a caller that asked nothing is a note carrying the explanation and the
+// capability's standing ("continuing on the native secret scanner"), never a
+// silent skip. The category approval gates reaching this step at all; it never
+// stands in for the per-tool answer.
 func (a *applyCtx) stepDependencies() {
 	if !a.approved[Dependency] {
 		return
 	}
 	for _, g := range a.det.Gaps {
-		if g.Category != Dependency {
+		if g.Category != Dependency || g.Tool == nil {
 			continue
 		}
-		tool := strings.TrimPrefix(strings.TrimSuffix(g.ID, "_missing"), "deps.")
-		if !onPath(tool) {
-			a.note(writeScannerHint, "dependency: "+g.FixHint)
+		if onPath(g.Tool.Tool) {
+			continue
+		}
+		res := newToolInstaller(a.cwd).Install(g.Tool.Tool, g.Tool.Capability, a.confirmTool)
+		if res.Ran && res.Installed && res.Verified {
+			a.changes = append(a.changes, receiptPath(a.cwd, "dependency: "+res.Summary()))
+			continue
+		}
+		if !res.Ran {
+			for _, line := range g.Tool.Lines() {
+				a.refuse(receiptPath(a.cwd, "dependency: "+line))
+			}
 		}
+		a.refuse(receiptPath(a.cwd, "dependency: "+res.Summary()))
 	}
 }
 
+// newToolInstaller is the tool installer seam, guarded on the repository the
+// install runs in; a test swaps it for one that records instead of executing.
+var newToolInstaller = tools.Default
+
 // stepSkeleton writes .abcd/config.json seed when the skeleton gap is present.
 func (a *applyCtx) stepSkeleton() {
 	if !a.approved[SafeAutocreate] || !a.has("skeleton.config_missing") {
@@ -1762,11 +1785,17 @@ func resolveApproval(gaps []Gap, opts InstallOptions, p Prompter) (map[GapCatego
 		}
 	default:
 		for _, c := range presentInPromptOrder(present) {
+			if c == Dependency && opts.ApproveDependency {
+				continue // answered by the named tool; approved below
+			}
 			if p.Confirm("Apply " + string(c) + " changes?") {
 				approved[c] = true
 			}
 		}
 	}
+	if opts.ApproveDependency && present[Dependency] {
+		approved[Dependency] = true
+	}
 	var declined []string
 	for c := range present {
 		if !approved[c] {
diff --git a/internal/core/ahoy/detect.go b/internal/core/ahoy/detect.go
index aa715d218..41d411ea8 100644
--- a/internal/core/ahoy/detect.go
+++ b/internal/core/ahoy/detect.go
@@ -9,7 +9,9 @@ import (
 	"sort"
 	"strings"
 
+	"github.com/intentdriven/abcd/internal/adapter/gitleaks"
 	"github.com/intentdriven/abcd/internal/core/identity"
+	"github.com/intentdriven/abcd/internal/core/tools"
 )
 
 // Enumerations for config-value validation.
@@ -87,7 +89,7 @@ func Detect(cwd string) (DetectionResult, error) {
 	var gaps []Gap
 	gaps = append(gaps, detectPluginRoot(pluginOK)...)
 	if kind != UnmanagedFolder {
-		gaps = append(gaps, detectDependencies()...)
+		gaps = append(gaps, detectDependencies(abs)...)
 		gaps = append(gaps, detectSkeleton(abs)...)
 		gaps = append(gaps, detectLocalTier(abs)...)
 		gaps = append(gaps, detectIdentity(identity, idx)...)
@@ -199,23 +201,43 @@ func detectPluginRoot(ok bool) []Gap {
 	}}
 }
 
-func detectDependencies() []Gap {
-	var gaps []Gap
-	if !onPath("gitleaks") {
-		gaps = append(gaps, Gap{
-			ID: "deps.gitleaks_missing", Category: Dependency, Scope: "machine",
-			Title: "gitleaks not on PATH", Detail: "gitleaks enables a deeper secret scan.",
-			FixHint: "brew install gitleaks", Required: false, Resolvable: true,
-		})
+// DependencyTools names the tools detectDependencies checks for, and so the
+// tools `ahoy install --install-tool` can name: the front door refuses any
+// other, since no gap would ever put it to the question.
+var DependencyTools = []string{"gitleaks"}
+
+// detectDependencies names each external tool a capability here would use and
+// cannot find, with the tool registry's explanation rather than a bare command
+// (itd-63). gitleaks is the one ahoy checks: optional over the native secret
+// scanner, and REQUIRED in a repository that armed it in
+// .abcd/config/gitleaks.json, whose transcript capture refuses without it. An
+// armed repository that names an existing binary by path has no gap: the
+// adapter judges that path itself, and a refusal there is not a missing tool.
+//
+// trufflehog is not offered: nothing in abcd runs it (iss-2609261447331434),
+// and a gap asking a person to install a program abcd never uses is not an
+// explanation anyone can act on.
+func detectDependencies(cwd string) []Gap {
+	capability := tools.TranscriptScan
+	if cfg, err := gitleaks.LoadConfig(cwd); err == nil && cfg.Enabled {
+		capability = tools.TranscriptScanArmed
+		if p := strings.TrimSpace(cfg.Path); p != "" && fileExists(p) {
+			return nil
+		}
 	}
-	if !onPath("trufflehog") {
-		gaps = append(gaps, Gap{
-			ID: "deps.trufflehog_missing", Category: Dependency, Scope: "machine",
-			Title: "trufflehog not on PATH", Detail: "trufflehog enables deep secret scanning when scan.deep=true.",
-			FixHint: "brew install trufflehog", Required: false, Resolvable: true,
-		})
+	if onPath("gitleaks") {
+		return nil
 	}
-	return gaps
+	e := tools.Explain("gitleaks", capability)
+	return []Gap{{
+		ID: "deps.gitleaks_missing", Category: Dependency, Scope: "machine",
+		Title:      "gitleaks not on PATH",
+		Detail:     string(e.Requirement) + " for " + e.CapabilityName + "; without it: " + e.WithoutIt + ".",
+		FixHint:    e.StepText() + " (abcd ahoy install explains it and runs it only on your yes)",
+		Required:   e.Requirement == tools.Required,
+		Resolvable: true,
+		Tool:       &e,
+	}}
 }
 
 func onPath(tool string) bool {
diff --git a/internal/core/ahoy/install_summary.go b/internal/core/ahoy/install_summary.go
index 236689455..fd1d455dc 100644
--- a/internal/core/ahoy/install_summary.go
+++ b/internal/core/ahoy/install_summary.go
@@ -36,7 +36,6 @@ const (
 	writeRules                   writeKind = "rules"
 	writeIdentityPin             writeKind = "identity-pin"
 	writeArtefactKind            writeKind = "artefact-kind"
-	writeScannerHint             writeKind = "scanner-hint"
 )
 
 // allWriteKinds is every kind, in the order the summary lists them: the
@@ -45,7 +44,7 @@ var allWriteKinds = []writeKind{
 	writeSettings, writeGitignore, writeLocalTier, writeNameGuard, writePrivateNames,
 	writeDocsCheck, writeAttributionHook, writeRules, writeConventionsBlock,
 	writeConventionsBlockRemoved, writeIdentityPin, writeArtefactKind, writeCommandEntry, writeSessionStore,
-	writeStatusLine, writeRouting, writeScannerHint,
+	writeStatusLine, writeRouting,
 }
 
 // writeKindHelp is the plain-language explanation of each kind of write.
@@ -130,11 +129,6 @@ var writeKindHelp = map[writeKind]SummaryItem{
 		Why:    "Larger models cost more; the table keeps the expensive ones for the steps that need them.",
 		Action: "Nothing. Edit the saved table if you want a different split.",
 	},
-	writeScannerHint: {
-		What:   "Listed the command that installs an optional extra scanner; abcd did not run it.",
-		Why:    "abcd's own checks work without it, and the extra scanner looks deeper for leaked secrets.",
-		Action: "If you want the deeper scan, run the command listed under the written items; abcd never runs an installer for you.",
-	},
 }
 
 // unexplainedWriteHelp is what a write reaches the person as when it carries no
diff --git a/internal/core/ahoy/install_summary_fallback_test.go b/internal/core/ahoy/install_summary_fallback_test.go
index 22c72023d..fedb3e58d 100644
--- a/internal/core/ahoy/install_summary_fallback_test.go
+++ b/internal/core/ahoy/install_summary_fallback_test.go
@@ -4,8 +4,9 @@ import "testing"
 
 // TestUnkindedWriteIsExplainedAsUnexplained is iss-2609260057112822: a write
 // that carries no kind, or a kind the table has no entry for, must reach the
-// person as a write the summary cannot describe, never as the scanner hint (the
-// old fallback) and never not at all.
+// person as a write the summary cannot describe, never as another kind's
+// explanation (the old fallback borrowed the scanner hint's, a kind itd-63's
+// explain-then-install step retired) and never not at all.
 func TestUnkindedWriteIsExplainedAsUnexplained(t *testing.T) {
 	r := &InstallResult{
 		Writes:     []string{"/x/kinded", "/x/unknown-kind", "/x/no-kind"},
@@ -27,8 +28,10 @@ func TestUnkindedWriteIsExplainedAsUnexplained(t *testing.T) {
 			t.Errorf("write %q is missing from the summary", w)
 			continue
 		}
-		if it.What == writeKindHelp[writeScannerHint].What {
-			t.Errorf("write %q is explained as the scanner hint: %+v", w, it)
+		for k, help := range writeKindHelp {
+			if it.What == help.What {
+				t.Errorf("write %q borrows the %s explanation: %+v", w, k, it)
+			}
 		}
 		if it.What != unexplainedWriteHelp.What {
 			t.Errorf("write %q is not reported as unexplained: %+v", w, it)
diff --git a/internal/core/ahoy/remote.go b/internal/core/ahoy/remote.go
index d131f47f2..4d73458bd 100644
--- a/internal/core/ahoy/remote.go
+++ b/internal/core/ahoy/remote.go
@@ -15,6 +15,7 @@ import (
 	"strings"
 	"time"
 
+	"github.com/intentdriven/abcd/internal/core/tools"
 	"github.com/intentdriven/abcd/internal/fsutil"
 	"github.com/intentdriven/abcd/internal/gitutil"
 )
@@ -452,8 +453,10 @@ func ghEnable(cwd, repo, key string) error {
 // the actor.
 func runGH(cwd string, stdin []byte, args ...string) ([]byte, error) {
 	if _, err := exec.LookPath("gh"); err != nil {
-		return nil, errors.New("the GitHub CLI (gh) is not on PATH; abcd speaks to GitHub through it so that a " +
-			"remote write is made by your own authenticated identity, never by a token abcd holds")
+		// The refusal carries the tool registry's explanation (itd-63): what gh
+		// is, that these verbs require it, and the exact install step.
+		return nil, tools.Missing(errors.New("the GitHub CLI (gh) is not on PATH; abcd speaks to GitHub through it so that a "+
+			"remote write is made by your own authenticated identity, never by a token abcd holds"), "gh", tools.GitHubSettings)
 	}
 	ctx, cancel := context.WithTimeout(context.Background(), remoteAPITimeout)
 	defer cancel()
diff --git a/internal/core/ahoy/remote_gh_explain_test.go b/internal/core/ahoy/remote_gh_explain_test.go
new file mode 100644
index 000000000..0b6f6b347
--- /dev/null
+++ b/internal/core/ahoy/remote_gh_explain_test.go
@@ -0,0 +1,35 @@
+package ahoy
+
+import (
+	"errors"
+	"strings"
+	"testing"
+
+	"github.com/intentdriven/abcd/internal/core/tools"
+)
+
+// emptyPath points PATH at an empty directory so no external tool is found.
+func emptyPath(t *testing.T) {
+	t.Helper()
+	t.Setenv("PATH", t.TempDir())
+}
+
+// TestMissingGhIsExplained is itd-63 criterion 1 at the remote verbs: a missing
+// gh is named with the registry's explanation, not a bare sentence.
+func TestMissingGhIsExplained(t *testing.T) {
+	emptyPath(t)
+	_, err := runGH(t.TempDir(), nil, "api", "repos/example/example")
+	if err == nil {
+		t.Fatal("runGH succeeded with no gh on PATH")
+	}
+	var missing *tools.MissingError
+	if !errors.As(err, &missing) || missing.Explanation.Tool != "gh" {
+		t.Fatalf("error carries no registry explanation: %v", err)
+	}
+	e := tools.Explain("gh", tools.GitHubSettings)
+	for _, want := range []string{"not on PATH", "required for", e.StepText(), "gh auth login"} {
+		if !strings.Contains(err.Error(), want) {
+			t.Errorf("error lacks %q:\n%s", want, err)
+		}
+	}
+}
diff --git a/internal/core/ahoy/statusline_install_test.go b/internal/core/ahoy/statusline_install_test.go
index 5905781b6..1ec3dd824 100644
--- a/internal/core/ahoy/statusline_install_test.go
+++ b/internal/core/ahoy/statusline_install_test.go
@@ -261,11 +261,9 @@ func TestStatusLineOfferDeclinedWritesNothing(t *testing.T) {
 	if err != nil {
 		t.Fatal(err)
 	}
-	// The dependency step reports the scanners it would have the user install
-	// under Writes too ("dependency: brew install …"), and on a machine without
-	// them that entry is legitimate and unrelated to the offer; the tree hashes
-	// below are what prove nothing was written. Here only the two files the
-	// offer owns may not appear.
+	// Other steps' entries in Writes are unrelated to the offer; the tree
+	// hashes below are what prove nothing was written. Here only the two files
+	// the offer owns may not appear.
 	for _, w := range res.Writes {
 		if strings.Contains(w, statusline.SettingsFileName) || strings.Contains(w, harnessSettingsFile) {
 			t.Errorf("a declined offer wrote: %v", res.Writes)
diff --git a/internal/core/ahoy/tools_route_test.go b/internal/core/ahoy/tools_route_test.go
new file mode 100644
index 000000000..fceb517e1
--- /dev/null
+++ b/internal/core/ahoy/tools_route_test.go
@@ -0,0 +1,235 @@
+package ahoy
+
+import (
+	"context"
+	"errors"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/intentdriven/abcd/internal/core/tools"
+)
+
+func depGap(t *testing.T, gaps []Gap, id string) Gap {
+	t.Helper()
+	for _, g := range gaps {
+		if g.ID == id {
+			return g
+		}
+	}
+	t.Fatalf("no %s gap among %v", id, gaps)
+	return Gap{}
+}
+
+// TestDependencyGapCarriesTheRegistryExplanation is itd-63 criterion 1 at
+// ahoy's gap: the gitleaks gap states what the registry says, not a bare
+// command.
+func TestDependencyGapCarriesTheRegistryExplanation(t *testing.T) {
+	emptyPath(t)
+	g := depGap(t, detectDependencies(t.TempDir()), "deps.gitleaks_missing")
+	if g.Tool == nil || g.Tool.Tool != "gitleaks" || !g.Tool.Known {
+		t.Fatalf("gap carries no registry explanation: %+v", g)
+	}
+	if g.Required || g.Tool.Requirement != tools.Optional {
+		t.Fatalf("an unarmed repository's gitleaks gap reads as required: %+v", g)
+	}
+	if !strings.Contains(g.Detail, "native secret scanner") {
+		t.Errorf("detail does not say what works without it: %q", g.Detail)
+	}
+	if !strings.Contains(g.FixHint, g.Tool.StepText()) {
+		t.Errorf("fix hint %q does not carry the registry step %q", g.FixHint, g.Tool.StepText())
+	}
+}
+
+// TestArmedRepositoryMakesGitleaksRequired: a repository that armed gitleaks
+// needs it, and the gap says so with the way back to the native scanner.
+func TestArmedRepositoryMakesGitleaksRequired(t *testing.T) {
+	emptyPath(t)
+	repo := t.TempDir()
+	if err := os.MkdirAll(filepath.Join(repo, ".abcd", "config"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(repo, ".abcd", "config", "gitleaks.json"),
+		[]byte(`{"schema_version":1,"enabled":true}`), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	g := depGap(t, detectDependencies(repo), "deps.gitleaks_missing")
+	if !g.Required || g.Tool == nil || g.Tool.Capability != tools.TranscriptScanArmed {
+		t.Fatalf("armed repository's gap: %+v", g)
+	}
+	if !strings.Contains(g.Detail, "enabled to false") {
+		t.Errorf("detail does not name the way back: %q", g.Detail)
+	}
+}
+
+// TestNoTrufflehogGap: nothing in abcd runs trufflehog, so ahoy never asks a
+// person to install it (iss-2609261447331434).
+func TestNoTrufflehogGap(t *testing.T) {
+	emptyPath(t)
+	for _, g := range detectDependencies(t.TempDir()) {
+		if strings.Contains(g.ID, "trufflehog") {
+			t.Fatalf("ahoy still offers trufflehog: %+v", g)
+		}
+	}
+}
+
+// fakeToolRun is a tools.Installer whose programs all "exist" outside the
+// repository and whose runs are recorded rather than executed.
+func fakeToolRun(t *testing.T, calls *[][]string) {
+	t.Helper()
+	bin := t.TempDir()
+	for _, n := range []string{"brew", "gitleaks"} {
+		if err := os.WriteFile(filepath.Join(bin, n), []byte("#!/bin/sh\n"), 0o755); err != nil {
+			t.Fatal(err)
+		}
+	}
+	prev := newToolInstaller
+	newToolInstaller = func(guard string) *tools.Installer {
+		in := tools.Default(guard)
+		in.LookPath = func(n string) (string, error) {
+			p := filepath.Join(bin, n)
+			if _, err := os.Stat(p); err != nil {
+				return "", errors.New("absent")
+			}
+			return p, nil
+		}
+		in.Getenv = func(string) string { return "" }
+		in.Run = func(_ context.Context, argv []string) ([]byte, error) {
+			*calls = append(*calls, argv)
+			return []byte("8.0.0\n"), nil
+		}
+		return in
+	}
+	t.Cleanup(func() { newToolInstaller = prev })
+}
+
+func depCtx(t *testing.T, confirm tools.Confirm) *applyCtx {
+	t.Helper()
+	emptyPath(t)
+	repo := t.TempDir()
+	return &applyCtx{
+		cwd:         repo,
+		det:         DetectionResult{Gaps: detectDependencies(repo)},
+		approved:    map[GapCategory]bool{Dependency: true},
+		confirmTool: confirm,
+	}
+}
+
+// TestDependencyNoKeepsTheNativeDefaultAndSaysSo is criterion 2's no half at
+// ahoy: nothing runs, the explanation is in the notes, and the loud line names
+// what the capability continues on.
+func TestDependencyNoKeepsTheNativeDefaultAndSaysSo(t *testing.T) {
+	var calls [][]string
+	fakeToolRun(t, &calls)
+	a := depCtx(t, func(tools.Explanation) tools.Answer { return tools.Answer{Why: "answered no"} })
+	a.stepDependencies()
+	if len(calls) != 0 {
+		t.Fatalf("a no ran %v", calls)
+	}
+	notes := strings.Join(a.notes, "\n")
+	for _, want := range []string{
+		"what abcd uses it for:",
+		"install step",
+		"gitleaks not installed (answered no); continuing on the native secret scanner",
+	} {
+		if !strings.Contains(notes, want) {
+			t.Errorf("notes lack %q:\n%s", want, notes)
+		}
+	}
+	if len(a.changes) != 0 || len(a.writes) != 0 {
+		t.Errorf("a no reported a change or a write: %v %v", a.changes, a.writes)
+	}
+}
+
+// TestDependencyWithoutAConfirmationNeverInstalls: a front door that supplies
+// no confirmation (--yes, a caller that never asks) installs nothing.
+func TestDependencyWithoutAConfirmationNeverInstalls(t *testing.T) {
+	var calls [][]string
+	fakeToolRun(t, &calls)
+	a := depCtx(t, nil)
+	a.stepDependencies()
+	if len(calls) != 0 {
+		t.Fatalf("installed with no confirmation: %v", calls)
+	}
+	if !strings.Contains(strings.Join(a.notes, "\n"), "continuing on the native secret scanner") {
+		t.Fatalf("the decline is silent: %v", a.notes)
+	}
+}
+
+// TestDependencyYesRunsTheStepAndReportsIt is criterion 2's yes half at ahoy.
+func TestDependencyYesRunsTheStepAndReportsIt(t *testing.T) {
+	var calls [][]string
+	fakeToolRun(t, &calls)
+	var shown tools.Explanation
+	a := depCtx(t, func(e tools.Explanation) tools.Answer { shown = e; return tools.Answer{Yes: true, Why: "typed yes"} })
+	a.stepDependencies()
+	if shown.Tool != "gitleaks" {
+		t.Fatalf("the confirmation was not shown the explanation: %+v", shown)
+	}
+	if len(calls) != 2 || filepath.Base(calls[0][0]) != "brew" {
+		t.Fatalf("calls = %v, want the brew step and the verify", calls)
+	}
+	changes := strings.Join(a.changes, "\n")
+	if !strings.Contains(changes, "ran brew install gitleaks") || !strings.Contains(changes, "verified") {
+		t.Fatalf("the install is not reported as a change: %v (notes %v)", a.changes, a.notes)
+	}
+}
+
+// TestEveryToolAhoyNamesIsRegistered is the build-time half of criterion 3: a
+// tool ahoy names that the registry lacks fails here, naming it, before it can
+// reach anyone as the generic explanation. DependencyTools and the gaps
+// detectDependencies emits are the same set.
+func TestEveryToolAhoyNamesIsRegistered(t *testing.T) {
+	emptyPath(t)
+	emitted := map[string]bool{}
+	for _, g := range detectDependencies(t.TempDir()) {
+		if g.Tool == nil {
+			t.Fatalf("dependency gap %s carries no explanation", g.ID)
+		}
+		emitted[g.Tool.Tool] = true
+	}
+	for _, n := range append(append([]string{}, DependencyTools...), "gh") {
+		if !tools.Known(n) {
+			t.Errorf("ahoy names %q, which the tool registry does not hold", n)
+		}
+	}
+	for _, n := range DependencyTools {
+		if !emitted[n] {
+			t.Errorf("DependencyTools names %q but no gap is emitted for it", n)
+		}
+		delete(emitted, n)
+	}
+	for n := range emitted {
+		t.Errorf("a gap names %q, which DependencyTools omits", n)
+	}
+}
+
+// TestNamedToolApprovesTheDependencyCategory: naming a tool to install is the
+// answer to the dependency question, so a host relaying it with no stdin
+// reaches the step; every other category is still asked (and here declined).
+func TestNamedToolApprovesTheDependencyCategory(t *testing.T) {
+	gaps := []Gap{
+		{ID: "deps.gitleaks_missing", Category: Dependency, Resolvable: true},
+		{ID: "skeleton.config_missing", Category: SafeAutocreate, Resolvable: true},
+	}
+	p := &recordingPrompter{}
+	approved, declined := resolveApproval(gaps, InstallOptions{ApproveDependency: true}, p)
+	asked := p.asked
+	if !approved[Dependency] {
+		t.Fatalf("a named tool did not approve the dependency category (declined %v)", declined)
+	}
+	for _, q := range asked {
+		if strings.Contains(q, string(Dependency)) {
+			t.Errorf("the dependency question was still asked: %v", asked)
+		}
+	}
+	if approved[SafeAutocreate] || len(asked) != 1 {
+		t.Errorf("the other categories were not left to their own answers: approved %v asked %v", approved, asked)
+	}
+
+	approved, _ = resolveApproval(gaps, InstallOptions{ApproveDependency: true, ApprovedCategories: map[GapCategory]bool{}}, &recordingPrompter{})
+	if !approved[Dependency] {
+		t.Fatal("an explicit category subset dropped the named tool's approval")
+	}
+}
diff --git a/internal/core/capture/blankrequired_parity_test.go b/internal/core/capture/blankrequired_parity_test.go
index d64ea7de9..3460376d7 100644
--- a/internal/core/capture/blankrequired_parity_test.go
+++ b/internal/core/capture/blankrequired_parity_test.go
@@ -6,6 +6,7 @@ import (
 	"strings"
 	"testing"
 
+	"github.com/intentdriven/abcd/internal/core/issuerecord"
 	"github.com/intentdriven/abcd/internal/core/issueschema"
 	"github.com/intentdriven/abcd/internal/core/lint"
 )
@@ -145,7 +146,7 @@ func TestBlankRequiredPropertyFindingsMatchTheReadersVerdict(t *testing.T) {
 				// ledger never reads either, so a parse error is a refusal like any
 				// other — the block-sequence spelling is refused there rather than at
 				// the validator.
-				fm, readerErr := parseFrontmatterBlock(lines)
+				fm, readerErr := issuerecord.ParseBlock(lines)
 				if readerErr == nil {
 					readerErr = validateStrict(fm)
 				}
diff --git a/internal/core/capture/capture.go b/internal/core/capture/capture.go
index f9ba378b6..b50464e89 100644
--- a/internal/core/capture/capture.go
+++ b/internal/core/capture/capture.go
@@ -19,7 +19,9 @@ import (
 	"fmt"
 	"regexp"
 
+	"github.com/intentdriven/abcd/internal/core/issuerecord"
 	"github.com/intentdriven/abcd/internal/core/issueschema"
+	"github.com/intentdriven/abcd/internal/core/record/match"
 	"github.com/intentdriven/abcd/internal/core/recordid"
 	"github.com/intentdriven/abcd/internal/core/relink"
 )
@@ -108,6 +110,12 @@ type Issue struct {
 	RelatedSpecs   []string `json:"related_specs,omitempty"`
 	RelatedIssues  []string `json:"related_issues,omitempty"`
 	BlockedBy      []string `json:"blocked_by,omitempty"` // iss-N dependency edges
+	// Duplicates and Refines are the typed links the filing-time match writes
+	// (itd-2609212137116617): the iss-N or itd-N this record is a near-identical
+	// double of, or a narrower case of. A person confirms a link by leaving it
+	// and removes it by deleting the line; a record without either is ordinary.
+	Duplicates []string `json:"duplicates,omitempty"`
+	Refines    []string `json:"refines,omitempty"`
 	// Grounds is the record's recorded conjectures, in the order they were
 	// written: one `<token>: <text>` value in the shared core/grounds vocabulary
 	// per grounds-bearing act. Appended by promote, resolve and wontfix; never by
@@ -163,6 +171,14 @@ type CaptureRequest struct {
 	// it is derived from which command ran, and a capture is researcher-authored
 	// by construction.
 	ProductionMode string
+	// Match, when non-nil, matches the text against every open and resolved
+	// issue and every intent before the record is written, under the ledger
+	// lock, and writes a `duplicates:` or `refines:` link naming each likely
+	// double (itd-2609212137116617). It never refuses the capture: a match that
+	// cannot run says why on the result and the record is filed without it.
+	// nil files the record unmatched, as a caller with its own matching (the
+	// inbox drain, the consistency pass) does.
+	Match *match.Config
 }
 
 // CaptureResult is the outcome of a successful Capture. The timestamp-numeric
@@ -189,6 +205,10 @@ type CaptureResult struct {
 	// record to the repository it is filed into — the shape every misfiled
 	// record of iss-2609120511058115 had (iss-2609231156260287).
 	NoLocation bool `json:"no_location,omitempty"`
+	// Match is the filing-time match's outcome when the request asked for one:
+	// the links written, the near misses below the threshold with their scores,
+	// or why nothing was compared.
+	Match *match.Outcome `json:"match,omitempty"`
 }
 
 // ResolveRequest moves an open issue to resolved/.
@@ -294,24 +314,18 @@ type SkipRecord struct {
 	Error string    `json:"error"`
 }
 
-// SkipLayer is the reader stage that refused a ledger file, in scan order.
-type SkipLayer string
+// SkipLayer is the reader stage that refused a ledger file, in scan order. It
+// is the record reader's own type (core/issuerecord), so the board and the
+// committed-ledger gate name a refusal with one vocabulary.
+type SkipLayer = issuerecord.Layer
 
-// The reader's stages, in the order a file meets them.
+// The reader's stages, in the order a file meets them; see core/issuerecord.
 const (
-	// SkipLayerName: the filename claims a record and is not a well-formed one.
-	SkipLayerName SkipLayer = "filename"
-	// SkipLayerRead: the guarded read refused the leaf (a FIFO, a symlink, an
-	// oversize body, an I/O error) — nothing about the record's content.
-	SkipLayerRead SkipLayer = "read"
-	// SkipLayerFrontmatter: the bytes do not parse as a frontmatter block.
-	SkipLayerFrontmatter SkipLayer = "frontmatter"
-	// SkipLayerSchema: the frontmatter parses and the issue schema refuses a
-	// key or value in it.
-	SkipLayerSchema SkipLayer = "schema"
-	// SkipLayerInvariant: schema-clean, and the record disagrees with where it
-	// sits — its filename, or the status folder holding it.
-	SkipLayerInvariant SkipLayer = "invariant"
+	SkipLayerName        = issuerecord.LayerName
+	SkipLayerRead        = issuerecord.LayerRead
+	SkipLayerFrontmatter = issuerecord.LayerFrontmatter
+	SkipLayerSchema      = issuerecord.LayerSchema
+	SkipLayerInvariant   = issuerecord.LayerInvariant
 )
 
 // ListResult is Issues sorted ascending by numeric N plus a corrupt roster.
@@ -393,16 +407,19 @@ var (
 	// written, and the surface gives both the one exit code a refusal takes
 	// (iss-2609260552251398).
 	ErrRequestRefused = errors.New("request refused")
+	// The record reader's own sentinels (core/issuerecord), re-exported: one
+	// value under either name, so errors.Is holds across the two packages.
+	//
 	// ErrInvariantViolation means frontmatter passed the schema but violates a
 	// folder-status cross-field invariant.
-	ErrInvariantViolation = errors.New("invariant violation")
+	ErrInvariantViolation = issuerecord.ErrInvariantViolation
 	// ErrMalformedFrontmatter means frontmatter could not be parsed or failed
 	// schema validation.
-	ErrMalformedFrontmatter = errors.New("malformed frontmatter")
+	ErrMalformedFrontmatter = issuerecord.ErrMalformedFrontmatter
 	// ErrMissingRequiredField means a schema-required field was absent.
-	ErrMissingRequiredField = errors.New("missing required field")
+	ErrMissingRequiredField = issuerecord.ErrMissingRequiredField
 	// ErrPathUnsafe means the ledger root or a status dir is a symlink.
-	ErrPathUnsafe = errors.New("path unsafe")
+	ErrPathUnsafe = issuerecord.ErrPathUnsafe
 	// ErrNotCharacterised means a disposition or an admission was asked for at
 	// the widening position before a committed comparative run named the item's
 	// run. The design characterises first and admits second, and the refusal
@@ -427,27 +444,18 @@ func refused(err error) error {
 
 // Field regexes mirroring issue.schema.json.
 var (
-	reIssID     = regexp.MustCompile(`^iss-[0-9]+$`)
-	reItdID     = regexp.MustCompile(`^itd-[0-9]+$`)
-	reSpcID     = regexp.MustCompile(`^spc-[0-9]+$`)
+	reIssID     = issuerecord.IssIDRe
+	reItdID     = issuerecord.ItdIDRe
+	reSpcID     = issuerecord.SpcIDRe
 	reCommitSha = regexp.MustCompile(`^[0-9a-f]{7,64}$`)
 	reSlug      = issueschema.SlugRe // the ONE kebab-slug pattern, shared with record-lint
-	// reIssNameClaim matches a filename that CLAIMS to be a ledger record: the
-	// family prefix followed by an ordinal. It is deliberately LOOSER than
-	// recordid.SplitRecordFilename, and the gap between the two is the point — a
-	// name that claims to be a record and then is not well-formed is reported as a
-	// skip rather than dropped, while a file claiming nothing (README.md,
-	// notes.md, iss-notes.md, the allocator lock) stays silently ignored. The
-	// ordinal is what parts the two: prose that merely starts with the prefix is
-	// not asserting an id.
-	reIssNameClaim = regexp.MustCompile(`^iss-[0-9]`)
 	// issFileNumRe is the ONE grammar that decides whether a ledger filename NAMES
 	// a record — the same recordid.FilenameNumRe the read-side resolver and
 	// record-lint's per-store rule match, so capture, the resolver and the gate
 	// agree on which files are records rather than sitting on two detection
 	// grammars (iss-2608280739112123). It is deliberately DISTINCT from the
 	// filename<->frontmatter slug agreement, which stays on the stricter
-	// recordid.SplitRecordFilename (validate.go) because that check EXTRACTS and
+	// recordid.SplitRecordFilename (core/issuerecord) because that check EXTRACTS and
 	// compares the slug; detection only needs the ordinal.
 	issFileNumRe = recordid.FilenameNumRe(issFamily)
 	reAbcdListID = regexp.MustCompile(`^(itd|fn|iss|rdi)-[0-9]+$`)
diff --git a/internal/core/capture/comment_parity_test.go b/internal/core/capture/comment_parity_test.go
index 7b010e810..403f05561 100644
--- a/internal/core/capture/comment_parity_test.go
+++ b/internal/core/capture/comment_parity_test.go
@@ -3,6 +3,8 @@ package capture
 import (
 	"strings"
 	"testing"
+
+	"github.com/intentdriven/abcd/internal/core/issuerecord"
 )
 
 // The gate exists to refuse exactly what the reader refuses, and a trailing
@@ -26,9 +28,9 @@ func TestLedgerParserStripsATrailingCommentLikeTheGate(t *testing.T) {
 	} {
 		t.Run(c.name, func(t *testing.T) {
 			key := c.line[:strings.IndexByte(c.line, ':')]
-			fm, err := parseFrontmatterBlock([]string{"id: iss-1", c.line})
+			fm, err := issuerecord.ParseBlock([]string{"id: iss-1", c.line})
 			if err != nil {
-				t.Fatalf("parseFrontmatterBlock(%q): %v", c.line, err)
+				t.Fatalf("issuerecord.ParseBlock(%q): %v", c.line, err)
 			}
 			got, _ := fm[key].(string)
 			if got != c.want {
diff --git a/internal/core/capture/grounds_scope_test.go b/internal/core/capture/grounds_scope_test.go
index 7ec3c2b1d..16da05a78 100644
--- a/internal/core/capture/grounds_scope_test.go
+++ b/internal/core/capture/grounds_scope_test.go
@@ -29,7 +29,7 @@ func rewriteIssue(t *testing.T, ir, issID string, fn func(string) string) {
 }
 
 // TestGroundsLandInTheBodyNotAFrontmatterComment is the writer/reader scope
-// agreement (iss-2608301805069999). parseFrontmatterBlock skips a line whose
+// agreement (iss-2608301805069999). issuerecord.ParseBlock skips a line whose
 // trimmed form starts with `#`, so `# Grounds` is a legal YAML comment inside
 // the frontmatter block — and an ATX heading pattern matches it as the section
 // heading. With the append judged over the WHOLE FILE the bullet landed in that
@@ -219,3 +219,74 @@ func TestAFrontmatterCommentMarkerDoesNotBlindTheRecord(t *testing.T) {
 		t.Fatalf("the recorded ground = %q, want %q", got, testGrounds)
 	}
 }
+
+// TestALockedBodyRefusesWhatWouldWriteGroundsAndNothingElse is
+// iss-2608301908270888 as the 2026-08-31 ruling settled it: a body that leaves an
+// opener unclosed masks every line below it, so a grounds entry appended there
+// cannot read back, and refusing is correct — the hand edit is the repair. So
+// every route that WOULD write an entry refuses, a wontfix included, since it
+// derives a `declined:` entry from its reason when given no grounds, and nothing
+// moves. The refusal names the construct, its body line and the exit: close or
+// remove the opener in a text editor, then re-run. The routes that write no
+// entry — resolve and promote given no grounds — have nothing to refuse and act.
+func TestALockedBodyRefusesWhatWouldWriteGroundsAndNothingElse(t *testing.T) {
+	for _, lock := range []struct {
+		name  string
+		apply func(t *testing.T, ir, issID string)
+		frag  string
+	}{
+		{"unclosed fence", openFence, "fenced code block"},
+		{"unclosed comment", func(t *testing.T, ir, issID string) {
+			rewriteIssue(t, ir, issID, func(s string) string {
+				return strings.TrimRight(s, "\n") + "\n\nthe loader drops rules when the <!-- abcd-review marker is stale\n"
+			})
+		}, "HTML comment"},
+	} {
+		refused := func(t *testing.T, ir, issID string, err error) {
+			t.Helper()
+			if err == nil {
+				t.Fatal("the route acted over a locked body, want a refusal")
+			}
+			for _, frag := range []string{lock.frag, "body line", "text editor", "re-run", "nothing written"} {
+				if !strings.Contains(err.Error(), frag) {
+					t.Fatalf("the refusal does not name %q: %v", frag, err)
+				}
+			}
+			if _, status, ferr := findIssue(ir, issID); ferr != nil || status != StateOpen {
+				t.Fatalf("after the refusal the record is in %q (%v), want it left in open/", status, ferr)
+			}
+		}
+		t.Run(lock.name+"/wontfix derives", func(t *testing.T) {
+			repo, ir, issID := promoteFixture(t, "the loader drops rules silently when the config is stale")
+			lock.apply(t, ir, issID)
+			_, err := Wontfix(WontfixRequest{RepoRoot: repo, IssuesRoot: ir, ID: issID, Reason: "superseded by the loader rewrite"})
+			refused(t, ir, issID, err)
+		})
+		t.Run(lock.name+"/wontfix with supplied grounds", func(t *testing.T) {
+			repo, ir, issID := promoteFixture(t, "the loader drops rules silently when the config is stale")
+			lock.apply(t, ir, issID)
+			_, err := Wontfix(WontfixRequest{RepoRoot: repo, IssuesRoot: ir, ID: issID,
+				Reason: "superseded by the loader rewrite", Grounds: "declined: the rewrite retires the loader this record is about"})
+			refused(t, ir, issID, err)
+		})
+		t.Run(lock.name+"/resolve without grounds", func(t *testing.T) {
+			repo, ir, issID := promoteFixture(t, "the loader drops rules silently when the config is stale")
+			lock.apply(t, ir, issID)
+			if _, err := Resolve(ResolveRequest{RepoRoot: repo, IssuesRoot: ir, ID: issID,
+				Resolution: "closed by the fix under review", Impact: "fix"}); err != nil {
+				t.Fatalf("Resolve without grounds over a locked body refused: %v", err)
+			}
+		})
+		t.Run(lock.name+"/promote without grounds", func(t *testing.T) {
+			repo, ir, issID := promoteFixture(t, "the loader drops rules silently when the config is stale")
+			lock.apply(t, ir, issID)
+			res, err := Promote(PromoteRequest{RepoRoot: repo, IssuesRoot: ir, ID: issID})
+			if err != nil {
+				t.Fatalf("Promote without grounds over a locked body refused: %v", err)
+			}
+			if res.IntentID == "" {
+				t.Fatalf("Promote without grounds minted no intent: %+v", res)
+			}
+		})
+	}
+}
diff --git a/internal/core/capture/impact_quoted_internal_test.go b/internal/core/capture/impact_quoted_internal_test.go
index 636527868..984d3fd5b 100644
--- a/internal/core/capture/impact_quoted_internal_test.go
+++ b/internal/core/capture/impact_quoted_internal_test.go
@@ -5,6 +5,7 @@ import (
 
 	"github.com/intentdriven/abcd/internal/core/changelog"
 	"github.com/intentdriven/abcd/internal/core/frontmatter"
+	"github.com/intentdriven/abcd/internal/core/issuerecord"
 )
 
 // gateImpactVerdict is record-lint's issue_impact_valid reading of one impact
@@ -48,7 +49,7 @@ func TestImpactQuotingReachesOneVerdict(t *testing.T) {
 		`impact: "sideways"`,
 	} {
 		t.Run(line, func(t *testing.T) {
-			fm, err := parseFrontmatterBlock([]string{line})
+			fm, err := issuerecord.ParseBlock([]string{line})
 			if err != nil {
 				t.Fatalf("parse %q: %v", line, err)
 			}
diff --git a/internal/core/capture/match.go b/internal/core/capture/match.go
new file mode 100644
index 000000000..5341aeb92
--- /dev/null
+++ b/internal/core/capture/match.go
@@ -0,0 +1,119 @@
+package capture
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/intentdriven/abcd/internal/core/intent"
+	"github.com/intentdriven/abcd/internal/core/record/match"
+)
+
+// match.go is the ledger's half of the filing-time match
+// (itd-2609212137116617): the candidate set a new capture or draft is compared
+// with — every open and resolved issue and every intent, through the fields the
+// configuration names — and the typed links a capture writes. The score is
+// internal/core/record/match's, the one term-overlap primitive. The ledger
+// gathers the intents too, because it already reads the intent store and the
+// intent store does not read the ledger; the intent create takes this set
+// through its Matcher.
+
+// linkFields are the typed-link keys a record may carry, in the order a
+// capture writes them.
+var linkFields = []match.Relation{match.Duplicates, match.Refines}
+
+// MatchCandidates is the candidate set for a filing in the checkout at
+// repoRoot, for a caller outside this package: the quoted-text intent create.
+func MatchCandidates(repoRoot string, cfg match.Config) ([]match.Candidate, error) {
+	rr, issuesRoot, err := resolveRoots(repoRoot, "")
+	if err != nil {
+		return nil, err
+	}
+	return matchCandidates(rr, issuesRoot, cfg)
+}
+
+// matchCandidates reads every open and resolved issue's body and every
+// intent's title and press release, as far as cfg compares them. A wontfix
+// record is not a candidate: it names work nobody is doing. A ledger record
+// the reader skips is not one either, since its text cannot be trusted; the
+// ledger's own surfaces already report it. A status directory that exists and
+// cannot be listed is different: the candidate set is then unknown rather than
+// smaller, so it is an error, which the caller reports as an unread match.
+func matchCandidates(repoRoot, issuesRoot string, cfg match.Config) ([]match.Candidate, error) {
+	var out []match.Candidate
+	if cfg.Compares(match.FieldIssueBody) {
+		for _, st := range []State{StateOpen, StateResolved} {
+			issues, _, err := scanStatusDir(issuesRoot, st)
+			if err != nil {
+				return nil, err // readStatusDir names the directory
+			}
+			for _, iss := range issues {
+				out = append(out, match.Candidate{ID: iss.ID, Text: iss.Body})
+			}
+		}
+	}
+	if cfg.Compares(match.FieldIntentTitle) || cfg.Compares(match.FieldIntentPressRelease) {
+		texts, err := intent.MatchTexts(repoRoot)
+		if err != nil {
+			return nil, err
+		}
+		for _, t := range texts {
+			var parts []string
+			if cfg.Compares(match.FieldIntentTitle) {
+				parts = append(parts, t.Title)
+			}
+			if cfg.Compares(match.FieldIntentPressRelease) {
+				parts = append(parts, t.PressRelease)
+			}
+			out = append(out, match.Candidate{ID: t.ID, Text: strings.Join(parts, "\n")})
+		}
+	}
+	return out, nil
+}
+
+// matchAndLink runs the match for a capture and writes its links into the
+// record's rendered content, validating the frontmatter they join. It runs
+// under the ledger lock, before the write. It never fails the capture: a
+// candidate set that cannot be read, or a link the schema would refuse, comes
+// back as an outcome saying why, with the content unlinked.
+func matchAndLink(repoRoot, issuesRoot string, cfg match.Config, text, content string, fm map[string]any) (string, *match.Outcome) {
+	if match.Short(text) {
+		o := match.Rank(text, nil, cfg.Threshold)
+		return content, &o
+	}
+	cands, err := matchCandidates(repoRoot, issuesRoot, cfg)
+	if err != nil {
+		o := match.Unread(cfg.Threshold, err)
+		return content, &o
+	}
+	o := match.Rank(text, cands, cfg.Threshold)
+	links := o.Links()
+	if len(links) == 0 {
+		return content, &o
+	}
+	linked := content
+	withLinks := make(map[string]any, len(fm)+len(links))
+	for k, v := range fm {
+		withLinks[k] = v
+	}
+	for _, rel := range linkFields {
+		ids := links[rel]
+		if len(ids) == 0 {
+			continue
+		}
+		withLinks[string(rel)] = ids
+		if linked, err = setListField(linked, string(rel), ids); err != nil {
+			break
+		}
+	}
+	if err == nil {
+		err = validateStrict(withLinks)
+	}
+	if err != nil {
+		o.Skipped = fmt.Sprintf("the links could not be written (%v), so the record is filed unlinked", err)
+		for i := range o.Matches {
+			o.Matches[i].Linked = false
+		}
+		return content, &o
+	}
+	return linked, &o
+}
diff --git a/internal/core/capture/match_test.go b/internal/core/capture/match_test.go
new file mode 100644
index 000000000..c8f3d15c6
--- /dev/null
+++ b/internal/core/capture/match_test.go
@@ -0,0 +1,263 @@
+package capture
+
+import (
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+	"testing"
+
+	"github.com/intentdriven/abcd/internal/core/intent"
+	"github.com/intentdriven/abcd/internal/core/record/match"
+)
+
+// The planted double: a finding, and the same finding filed again in other
+// words. The fillers are records about other things, so the corpus has a
+// vocabulary to weigh terms against.
+const (
+	plantedFinding = "The capture ledger reader silently skips a record whose frontmatter carries " +
+		"a duplicated key, so the finding disappears from every listing without a warning."
+	plantedDouble = "Capture ledger reader silently skips any record whose frontmatter carries a " +
+		"duplicated key: the finding disappears from every listing, and no warning is printed."
+	matchFiller1 = "The site builder renders a stale anchor for a heading renamed since the last build."
+	matchFiller2 = "The history store drops a transcript that exceeds its byte budget without saying so."
+	// A broad intent the narrow capture below refines.
+	broadTitle = "Record readers agree with the lint gate"
+	broadPress = "Record readers disagree with the lint gate. The capture ledger reader skips " +
+		"records with duplicated frontmatter keys, the intent loader fails closed on a missing id, " +
+		"the spec store tolerates unknown properties, the site builder renders stale anchors, " +
+		"the memory store truncates pages, and the history store drops transcripts over its budget."
+	narrowCapture = "The capture ledger reader skips records with duplicated frontmatter keys " +
+		"while the lint gate reports them."
+)
+
+func captureText(t *testing.T, repo, ir, text string, m *match.Config) CaptureResult {
+	t.Helper()
+	res, err := Capture(CaptureRequest{
+		RepoRoot: repo, IssuesRoot: ir, Text: text, Severity: SeverityMinor,
+		Category: "bug", Source: "user-observation", FoundDuring: "t", Match: m,
+	})
+	if err != nil {
+		t.Fatalf("capture refused: %v", err)
+	}
+	return res
+}
+
+func plantIntent(t *testing.T, repo, bucket, id, title, press string) {
+	t.Helper()
+	writeFile(t, filepath.Join(repo, ".abcd/development/intents", bucket, id+"-planted.md"),
+		"---\nid: "+id+"\nslug: planted\nspec_id: null\nkind: null\n---\n\n# "+title+
+			"\n\n## Press Release\n\n> "+press+"\n\n## Why This Matters\n\nUnrelated words about budgets.\n")
+}
+
+func readRecord(t *testing.T, repo, rel string) string {
+	t.Helper()
+	b, err := os.ReadFile(filepath.Join(repo, rel))
+	if err != nil {
+		t.Fatal(err)
+	}
+	return string(b)
+}
+
+func bundled() *match.Config { c := match.Bundled(); return &c }
+
+// Criterion 1: a capture that overlaps an existing issue above the threshold
+// is written with a typed link naming it, and the result carries the match.
+func TestCaptureLinksAPlantedDouble(t *testing.T) {
+	repo, ir := ledger(t)
+	first := captureText(t, repo, ir, plantedFinding, nil)
+	captureText(t, repo, ir, matchFiller1, nil)
+	captureText(t, repo, ir, matchFiller2, nil)
+
+	res := captureText(t, repo, ir, plantedDouble, bundled())
+	if res.Match == nil || len(res.Match.Matches) == 0 {
+		t.Fatalf("no match reported: %+v", res.Match)
+	}
+	m := res.Match.Matches[0]
+	if m.ID != first.ID || m.Relation != match.Duplicates || !m.Linked {
+		t.Fatalf("match = %+v, want %s linked as duplicates", m, first.ID)
+	}
+	content := readRecord(t, repo, res.Path)
+	if !strings.Contains(content, "\nduplicates: ["+first.ID+"]\n") {
+		t.Fatalf("the record carries no duplicates link naming %s:\n%s", first.ID, content)
+	}
+	// The link reads back through the ledger reader.
+	list, err := List(ListRequest{RepoRoot: repo, IssuesRoot: ir, State: StateOpen})
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, iss := range list.Issues {
+		if iss.ID == res.ID {
+			if len(iss.Duplicates) != 1 || iss.Duplicates[0] != first.ID {
+				t.Fatalf("read back duplicates = %v", iss.Duplicates)
+			}
+			return
+		}
+	}
+	t.Fatalf("the linked record %s is not listed (skipped: %+v)", res.ID, list.Skipped)
+}
+
+// The candidates include every intent's title and press release, and a
+// narrower capture of a broader record is written as `refines`.
+func TestCaptureRefinesABroaderIntent(t *testing.T) {
+	repo, ir := ledger(t)
+	captureText(t, repo, ir, matchFiller1, nil)
+	captureText(t, repo, ir, matchFiller2, nil)
+	plantIntent(t, repo, "planned", "itd-9", broadTitle, broadPress)
+
+	res := captureText(t, repo, ir, narrowCapture, bundled())
+	if res.Match == nil || len(res.Match.Matches) != 1 || res.Match.Matches[0].ID != "itd-9" ||
+		res.Match.Matches[0].Relation != match.Refines {
+		t.Fatalf("match = %+v, want itd-9 as refines", res.Match)
+	}
+	if content := readRecord(t, repo, res.Path); !strings.Contains(content, "\nrefines: [itd-9]\n") {
+		t.Fatalf("no refines link:\n%s", content)
+	}
+}
+
+// Criterion 4: below the threshold nothing is written and the near misses
+// are listed with their scores.
+func TestCaptureBelowTheThresholdWritesNothingAndListsNearMisses(t *testing.T) {
+	repo, ir := ledger(t)
+	captureText(t, repo, ir, plantedFinding, nil)
+	captureText(t, repo, ir, matchFiller1, nil)
+	cfg := match.Bundled()
+	cfg.Threshold = 0.99
+	res := captureText(t, repo, ir, narrowCapture, &cfg)
+	if res.Match == nil || len(res.Match.Matches) != 0 {
+		t.Fatalf("matched above a 0.99 threshold: %+v", res.Match)
+	}
+	if len(res.Match.NearMisses) == 0 || res.Match.NearMisses[0].Score <= 0 {
+		t.Fatalf("near misses = %+v, want the finding with its score", res.Match.NearMisses)
+	}
+	content := readRecord(t, repo, res.Path)
+	if regexp.MustCompile(`(?m)^(duplicates|refines):`).MatchString(content) {
+		t.Fatalf("a link was written below the threshold:\n%s", content)
+	}
+}
+
+// The compared fields are configuration: with issue bodies left out, the
+// planted double is not a candidate.
+func TestCaptureComparesOnlyTheConfiguredFields(t *testing.T) {
+	repo, ir := ledger(t)
+	captureText(t, repo, ir, plantedFinding, nil)
+	cfg := match.Bundled()
+	cfg.Fields = []string{match.FieldIntentTitle, match.FieldIntentPressRelease}
+	res := captureText(t, repo, ir, plantedDouble, &cfg)
+	if res.Match == nil || len(res.Match.Matches)+len(res.Match.NearMisses) != 0 {
+		t.Fatalf("an issue was compared though issue.body is not a configured field: %+v", res.Match)
+	}
+}
+
+// Criterion 3: a match that cannot run never refuses the capture; the record
+// is filed and the result says why nothing was compared. A short text is
+// filed without matching and says so.
+func TestCaptureIsNeverRefusedByTheMatch(t *testing.T) {
+	repo, ir := ledger(t)
+	captureText(t, repo, ir, plantedFinding, nil)
+	// An intent store no reader can load: a record whose id is malformed.
+	writeFile(t, filepath.Join(repo, ".abcd/development/intents/drafts/itd-1-broken.md"), "---\nid: nonsense\n---\n")
+	res := captureText(t, repo, ir, plantedDouble, bundled())
+	if res.Match == nil || res.Match.Skipped == "" || len(res.Match.Matches) != 0 {
+		t.Fatalf("an unreadable record set did not report a skipped match: %+v", res.Match)
+	}
+	if _, err := os.Stat(filepath.Join(repo, res.Path)); err != nil {
+		t.Fatalf("the capture was not written: %v", err)
+	}
+
+	short := captureText(t, repo, ir, "Typo in the ledger README.", bundled())
+	if short.Match == nil || !strings.Contains(short.Match.Skipped, "minimum") {
+		t.Fatalf("a short capture did not say it was filed without matching: %+v", short.Match)
+	}
+}
+
+// Criterion 3, second half: removing the link leaves an ordinary record, one
+// every reader takes exactly as it takes a record that never had one.
+func TestRemovingTheLinkLeavesAnOrdinaryRecord(t *testing.T) {
+	repo, ir := ledger(t)
+	captureText(t, repo, ir, plantedFinding, nil)
+	captureText(t, repo, ir, matchFiller1, nil)
+	res := captureText(t, repo, ir, plantedDouble, bundled())
+	p := filepath.Join(repo, res.Path)
+	content := readRecord(t, repo, res.Path)
+	stripped := regexp.MustCompile(`(?m)^duplicates: .*\n`).ReplaceAllString(content, "")
+	if stripped == content {
+		t.Fatalf("no link to remove:\n%s", content)
+	}
+	if err := os.WriteFile(p, []byte(stripped), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	list, err := List(ListRequest{RepoRoot: repo, IssuesRoot: ir, State: StateOpen})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(list.Skipped) != 0 {
+		t.Fatalf("the unlinked record is skipped: %+v", list.Skipped)
+	}
+	for _, iss := range list.Issues {
+		if iss.ID == res.ID && len(iss.Duplicates)+len(iss.Refines) == 0 {
+			return
+		}
+	}
+	t.Fatalf("%s not read back as an ordinary record", res.ID)
+}
+
+// Without a Match the capture is exactly the one it always was.
+func TestCaptureWithoutAMatchReportsNone(t *testing.T) {
+	repo, ir := ledger(t)
+	captureText(t, repo, ir, plantedFinding, nil)
+	res := captureText(t, repo, ir, plantedDouble, nil)
+	if res.Match != nil {
+		t.Fatalf("an unrequested match ran: %+v", res.Match)
+	}
+	if strings.Contains(readRecord(t, repo, res.Path), "duplicates:") {
+		t.Fatal("an unrequested match wrote a link")
+	}
+}
+
+// A link names a record by its id: a value of any other shape is refused by
+// the reader, like every other id list.
+func TestALinkValueIsARecordID(t *testing.T) {
+	fm := map[string]any{
+		"schema_version": 1, "id": "iss-1", "slug": "a", "severity": "minor",
+		"category": "bug", "source": "user-observation", "found_during": "t",
+	}
+	for _, key := range []string{"duplicates", "refines"} {
+		for _, v := range []string{"iss-2", "itd-3"} {
+			fm[key] = []string{v}
+			if err := validateStrict(fm); err != nil {
+				t.Fatalf("%s: [%s] refused: %v", key, v, err)
+			}
+		}
+		fm[key] = []string{"spc-4"}
+		if err := validateStrict(fm); err == nil {
+			t.Fatalf("%s: [spc-4] admitted", key)
+		}
+		delete(fm, key)
+	}
+}
+
+// Criterion 2 end to end: the quoted-text intent create, with the ledger's
+// candidate set, links a draft that doubles an existing intent's title and
+// press release.
+func TestIntentCreateMatchesTheRecordThroughTheLedger(t *testing.T) {
+	repo, ir := ledger(t)
+	captureText(t, repo, ir, matchFiller1, nil)
+	captureText(t, repo, ir, matchFiller2, nil)
+	plantIntent(t, repo, "shipped", "itd-9", broadTitle, broadPress)
+	cfg := match.Bundled()
+	m := &intent.Matcher{Threshold: cfg.Threshold, Candidates: func() ([]match.Candidate, error) {
+		return MatchCandidates(repo, cfg)
+	}}
+	c, err := intent.CreateFromTextMatched(repo, broadPress, intent.TextOptions{Title: broadTitle}, m)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if c.Match == nil || len(c.Match.Matches) == 0 || c.Match.Matches[0].ID != "itd-9" ||
+		c.Match.Matches[0].Relation != match.Duplicates {
+		t.Fatalf("match = %+v, want itd-9 as duplicates", c.Match)
+	}
+	if content := readRecord(t, repo, c.Path); !strings.Contains(content, "\nduplicates: [itd-9]\n") {
+		t.Fatalf("no link on the draft:\n%s", content)
+	}
+}
diff --git a/internal/core/capture/nulls_internal_test.go b/internal/core/capture/nulls_internal_test.go
index 11528c76c..110f6298d 100644
--- a/internal/core/capture/nulls_internal_test.go
+++ b/internal/core/capture/nulls_internal_test.go
@@ -1,6 +1,10 @@
 package capture
 
-import "testing"
+import (
+	"testing"
+
+	"github.com/intentdriven/abcd/internal/core/issuerecord"
+)
 
 // capture and record-lint must reach the SAME verdict on one record's impact,
 // whatever spelling and quoting it uses (iss-285, coupled to iss-287).
@@ -27,7 +31,7 @@ func TestBareAndQuotedNullsPartTheSameWay(t *testing.T) {
 		{"a real impact", "impact: fix", false},
 	} {
 		t.Run(c.name, func(t *testing.T) {
-			fm, err := parseFrontmatterBlock([]string{c.line})
+			fm, err := issuerecord.ParseBlock([]string{c.line})
 			if err != nil {
 				t.Fatalf("parse %q: %v", c.line, err)
 			}
@@ -90,7 +94,7 @@ func TestQuotedNullImpactPartsAtTheGate(t *testing.T) {
 		{"quoted tilde", `impact: "~"`, false},
 	} {
 		t.Run(c.name, func(t *testing.T) {
-			fm, err := parseFrontmatterBlock([]string{c.line})
+			fm, err := issuerecord.ParseBlock([]string{c.line})
 			if err != nil {
 				t.Fatalf("parse %q: %v", c.line, err)
 			}
diff --git a/internal/core/capture/parse_test.go b/internal/core/capture/parse_test.go
index 8ed665e99..eb582e787 100644
--- a/internal/core/capture/parse_test.go
+++ b/internal/core/capture/parse_test.go
@@ -3,6 +3,8 @@ package capture
 import (
 	"reflect"
 	"testing"
+
+	"github.com/intentdriven/abcd/internal/core/issuerecord"
 )
 
 // TestInlineListRoundTripQuotedCommas (B24) pins the quote-aware inline-list
@@ -34,7 +36,7 @@ func TestInlineListRoundTripQuotedCommas(t *testing.T) {
 // TestParseScalarOrListSkipsQuotedComma isolates the tokenizer: a comma inside a
 // quoted item is not a separator, so a two-item list is not blown apart.
 func TestParseScalarOrListSkipsQuotedComma(t *testing.T) {
-	v, err := parseScalarOrList(`["alpha, beta", "gamma"]`)
+	v, err := issuerecord.ParseScalarOrList(`["alpha, beta", "gamma"]`)
 	if err != nil {
 		t.Fatal(err)
 	}
diff --git a/internal/core/capture/roots.go b/internal/core/capture/roots.go
index d39885162..5c5c99796 100644
--- a/internal/core/capture/roots.go
+++ b/internal/core/capture/roots.go
@@ -3,18 +3,14 @@ package capture
 import (
 	"crypto/sha256"
 	"encoding/hex"
-	"errors"
 	"fmt"
-	"io/fs"
 	"os"
 	"path/filepath"
 	"regexp"
 	"strings"
-	"syscall"
 
-	"github.com/intentdriven/abcd/internal/core/issueschema"
+	"github.com/intentdriven/abcd/internal/core/issuerecord"
 	"github.com/intentdriven/abcd/internal/core/recordid"
-	"github.com/intentdriven/abcd/internal/fsutil"
 	"github.com/intentdriven/abcd/internal/gitutil"
 )
 
@@ -173,40 +169,6 @@ func readWithChecksum(path string) (string, string, error) {
 	return content, sha256Hex([]byte(content)), nil
 }
 
-// readRecordGuarded reads one record file through the shared trust-boundary
-// primitive: fsutil.ReadGuarded opens once with O_NOFOLLOW and O_NONBLOCK and
-// validates on the SAME descriptor, so no symlink swap fits between a check and
-// the read, and a FIFO or device at a record name cannot block the open. The cap
-// is issueschema.RecordReadLimit, the ONE cap the ledger's families share —
-// core/lint applies the same value, because a cap the board applies loosely and
-// the verb applies tightly makes the ledger say two things about one file.
-//
-// It is the reader for EVERY record family in this package. The reading and
-// disposition families used it from the start; the issue family read through a
-// bare os.ReadFile until GHSA-fh9j-8xmg-m33f, so a committed FIFO hung `list`,
-// an oversize record was serialized unbounded, and a committed symlink read an
-// out-of-tree file into `list --json` (iss-2609012036271396). A record store a
-// clone carries is a trust boundary whichever family the record belongs to.
-//
-// The sentinels are mapped to this package's own: a non-regular leaf, or a
-// symlink refused by O_NOFOLLOW, is ErrPathUnsafe, which is what every caller
-// here already tests for.
-func readRecordGuarded(path string) (string, error) {
-	data, err := fsutil.ReadGuarded(path, issueschema.RecordReadLimit)
-	if err == nil {
-		return string(data), nil
-	}
-	if errors.Is(err, fsutil.ErrNotRegular) || errors.Is(err, syscall.ELOOP) {
-		return "", fmt.Errorf("%w: record path is not a regular file: %s", ErrPathUnsafe, path)
-	}
-	if errors.Is(err, fsutil.ErrTooBig) {
-		return "", fmt.Errorf("%w: record is larger than the %d-byte size cap and was left unread: %s", ErrPathUnsafe, issueschema.RecordReadLimit, path)
-	}
-	// A record the process may not open is a refusal with a name, not a raw open
-	// error surfacing through a verb: the caller is told the ledger could not be
-	// read and which file, rather than a syscall's own wording.
-	if errors.Is(err, fs.ErrPermission) {
-		return "", fmt.Errorf("%w: record is unreadable (permission denied): %s", ErrPathUnsafe, path)
-	}
-	return "", err
-}
+// readRecordGuarded reads one record file through the guarded, capped read
+// every ledger family shares (issuerecord.ReadGuarded).
+func readRecordGuarded(path string) (string, error) { return issuerecord.ReadGuarded(path) }
diff --git a/internal/core/capture/serialize.go b/internal/core/capture/serialize.go
index 098faae37..0876edbdf 100644
--- a/internal/core/capture/serialize.go
+++ b/internal/core/capture/serialize.go
@@ -6,6 +6,7 @@ import (
 	"strings"
 
 	"github.com/intentdriven/abcd/internal/core/frontmatter"
+	"github.com/intentdriven/abcd/internal/core/issuerecord"
 )
 
 // kv is one ordered frontmatter entry. val is a string, int, or []string.
@@ -107,7 +108,7 @@ func buildIssueText(fields []kv, body string) (string, error) {
 }
 
 // yamlList encodes a string list as the inline flow form buildIssueText has
-// always written and parseScalarOrList reads back: `[]` when empty, bare ids
+// always written and issuerecord.ParseScalarOrList reads back: `[]` when empty, bare ids
 // when every item is an abcd id (`[itd-4, iss-12]`), per-item quoted otherwise.
 // It is the ONE list encoder, shared by the create path and the in-place list
 // rewrite (setListField), so a list a verb edits after capture is spelled
@@ -359,19 +360,6 @@ func frontmatterBounds(lines []string) (openIdx, closeIdx int, err error) {
 	return openIdx, closeIdx, nil
 }
 
-// splitKeepEnds splits s into lines preserving their trailing newline(s),
-// mirroring Python's str.splitlines(keepends=True) for \n and \r\n.
-func splitKeepEnds(s string) []string {
-	var out []string
-	start := 0
-	for i := 0; i < len(s); i++ {
-		if s[i] == '\n' {
-			out = append(out, s[start:i+1])
-			start = i + 1
-		}
-	}
-	if start < len(s) {
-		out = append(out, s[start:])
-	}
-	return out
-}
+// splitKeepEnds is the ledger reader's line splitter, so a writer and the
+// reader split one record's bytes the same way.
+func splitKeepEnds(s string) []string { return issuerecord.SplitKeepEnds(s) }
diff --git a/internal/core/capture/unreadabledir_test.go b/internal/core/capture/unreadabledir_test.go
new file mode 100644
index 000000000..8097d1884
--- /dev/null
+++ b/internal/core/capture/unreadabledir_test.go
@@ -0,0 +1,103 @@
+package capture
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// unreadableStatusDir creates the status directory sub under ir and takes
+// every permission off it, restoring them when the test ends so the temporary
+// directory can be removed. A test that runs as root reads through the mode
+// bits, so it is skipped there rather than passing for the wrong reason.
+func unreadableStatusDir(t *testing.T, ir string, sub State) string {
+	t.Helper()
+	if os.Geteuid() == 0 {
+		t.Skip("root reads through a mode-000 directory")
+	}
+	dir := filepath.Join(ir, statusDirName[sub])
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.Chmod(dir, 0); err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = os.Chmod(dir, 0o755) })
+	return dir
+}
+
+// An unreadable status directory is not an absent one (iss-2609261631120364).
+// The filing-time match that cannot read resolved/ has not compared the
+// record, so it says the record set was unread, as it does when the intent
+// store cannot be read, instead of reporting the records it happened to reach.
+// A capture never gets that far: its mint cannot tell a free id from one the
+// unreadable directory holds, so it faults naming the directory
+// (iss-2609261241121312). The quoted-text intent create writes nothing into
+// the ledger and still matches against it, so the unread outcome is what it
+// files with: the content comes back unlinked.
+func TestMatchReportsAnUnreadableStatusDirectoryAsUnread(t *testing.T) {
+	repo, ir := ledger(t)
+	captureText(t, repo, ir, plantedFinding, nil)
+	captureText(t, repo, ir, matchFiller1, nil)
+	unreadableStatusDir(t, ir, StateResolved)
+
+	if _, err := Capture(CaptureRequest{
+		RepoRoot: repo, IssuesRoot: ir, Text: plantedDouble, Severity: SeverityMinor,
+		Category: "bug", Source: "user-observation", FoundDuring: "t", Match: bundled(),
+	}); err == nil || !strings.Contains(err.Error(), statusDirName[StateResolved]+"/") {
+		t.Fatalf("a capture over an unreadable resolved/ was not refused naming it: %v", err)
+	}
+	if _, err := MatchCandidates(repo, *bundled()); err == nil || !strings.Contains(err.Error(), statusDirName[StateResolved]+"/") {
+		t.Fatalf("the intent create's candidate set read an unreadable resolved/ as empty: %v", err)
+	}
+	const content = "---\nid: planted\n---\n"
+	got, o := matchAndLink(repo, ir, *bundled(), plantedDouble, content, map[string]any{})
+	if o == nil || !strings.Contains(o.Skipped, "could not be read") {
+		t.Fatalf("an unreadable resolved/ did not read as an unread record set: %+v", o)
+	}
+	if len(o.Matches) != 0 {
+		t.Fatalf("an unread record set still linked: %+v", o.Matches)
+	}
+	if got != content {
+		t.Fatalf("an unread match changed the content it was to file:\n%s", got)
+	}
+}
+
+// The board says the same thing: capture list and capture status name an
+// unreadable status directory rather than counting it as a directory with no
+// records in it. The one mechanism is readStatusDir's (iss-2609261241121312):
+// the directory is a fault naming it, ledger-relatively, so neither surface
+// reports a count for a ledger it did not read. An absent directory stays
+// silent — a virgin ledger has none.
+func TestListAndStatusReportAnUnreadableStatusDirectory(t *testing.T) {
+	repo, ir := ledger(t)
+	captureText(t, repo, ir, plantedFinding, nil)
+	unreadableStatusDir(t, ir, StateResolved)
+
+	named := func(err error) bool {
+		return err != nil && strings.Contains(err.Error(), statusDirName[StateResolved]+"/") &&
+			!strings.Contains(err.Error(), statusDirName[StateWontfix]+"/") && !strings.Contains(err.Error(), repo)
+	}
+	if list, err := List(ListRequest{RepoRoot: repo, IssuesRoot: ir}); !named(err) {
+		t.Fatalf("capture list did not name the unreadable resolved/ alone: %v (%d rows)", err, len(list.Issues))
+	}
+	if st, err := Status(StatusRequest{RepoRoot: repo, IssuesRoot: ir}); !named(err) {
+		t.Fatalf("capture status did not name the unreadable resolved/ alone: %v (%d resolved)", err, st.ResolvedCount)
+	}
+}
+
+// A list scoped to resolved/ still reads open/ for the blocked_by projection;
+// an unreadable open/ there leaves every dependent looking unblocked, so the
+// list names it even though the rows come from another directory.
+func TestAScopedListNamesAnUnreadableOpenDirectory(t *testing.T) {
+	repo, ir := ledger(t)
+	if err := os.MkdirAll(filepath.Join(ir, statusDirName[StateResolved]), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	unreadableStatusDir(t, ir, StateOpen)
+	_, err := List(ListRequest{RepoRoot: repo, IssuesRoot: ir, State: StateResolved})
+	if err == nil || !strings.Contains(err.Error(), statusDirName[StateOpen]+"/") {
+		t.Fatalf("a resolved/ list did not name the unreadable open/: %v", err)
+	}
+}
diff --git a/internal/core/capture/validate.go b/internal/core/capture/validate.go
index 95264f25c..43b1859ca 100644
--- a/internal/core/capture/validate.go
+++ b/internal/core/capture/validate.go
@@ -1,15 +1,9 @@
 package capture
 
 import (
-	"fmt"
-	"path/filepath"
-	"regexp"
-	"strings"
-
-	"github.com/intentdriven/abcd/internal/core/changelog"
 	"github.com/intentdriven/abcd/internal/core/grounds"
+	"github.com/intentdriven/abcd/internal/core/issuerecord"
 	"github.com/intentdriven/abcd/internal/core/issueschema"
-	"github.com/intentdriven/abcd/internal/core/recordid"
 )
 
 // knownFields is the additionalProperties:false allow-list from
@@ -18,267 +12,29 @@ import (
 // which keys a well-formed record may carry.
 var knownFields = issueschema.Known
 
-// uniqueItemsFields are the array properties issue.schema.json flags
-// uniqueItems:true.
-var uniqueItemsFields = []string{"related_intents", "related_specs", "related_issues", "synthesis_clusters", "blocked_by"}
-
-// validateStrict validates a frontmatter map against the issue schema. It
-// special-cases schema_version first (mirrors _validate_strict) and rejects
-// unknown keys (additionalProperties:false).
-func validateStrict(fm map[string]any) error {
-	sv, ok := fm["schema_version"]
-	if !ok {
-		return fmt.Errorf("%w: missing required property 'schema_version'", ErrMissingRequiredField)
-	}
-	if n, isInt := sv.(int); !isInt || n != 1 {
-		return fmt.Errorf("%w: unsupported schema_version %v (this reader only handles 1)", ErrMissingRequiredField, sv)
-	}
-
-	for k := range fm {
-		if successor, retired := issueschema.Retired[k]; retired {
-			return fmt.Errorf("%w: retired property %q (renamed to %q); %s",
-				ErrMalformedFrontmatter, k, successor, issueschema.MigrateHint)
-		}
-		if !knownFields[k] {
-			return fmt.Errorf("%w: unknown property %q", ErrMalformedFrontmatter, k)
-		}
-	}
+// The record reader's judgement lives in core/issuerecord, where record-lint
+// reads it too; these are this package's names for it.
 
-	// Required strings — the schema's own list (core/issueschema) minus
-	// schema_version, which the version check above already answered for. The
-	// record lint reads the SAME list, so the reader and the committed-ledger gate
-	// cannot disagree about what a well-formed record carries.
-	for _, req := range issueschema.RequiredStrings {
-		v, present := fm[req]
-		if !present {
-			return fmt.Errorf("%w: missing required property %q", ErrMissingRequiredField, req)
-		}
-		if _, isStr := v.(string); !isStr {
-			return fmt.Errorf("%w: %q must be a string", ErrMalformedFrontmatter, req)
-		}
-	}
+// validateStrict validates a frontmatter map against the issue schema
+// (issuerecord.ValidateStrict).
+func validateStrict(fm map[string]any) error { return issuerecord.ValidateStrict(fm) }
 
-	id := fm["id"].(string)
-	if !reIssID.MatchString(id) {
-		return fmt.Errorf("%w: id %q does not match ^iss-[0-9]+$", ErrMalformedFrontmatter, id)
-	}
-	if !reSlug.MatchString(fm["slug"].(string)) {
-		return fmt.Errorf("%w: slug %q is not kebab-case", ErrMalformedFrontmatter, fm["slug"])
-	}
-	// A closed enum's refusal NAMES THE SET IT ACCEPTS. It has the legal values
-	// in hand, and withholding them turns one round trip into several: an
-	// operator told only that their value was rejected has to go looking, and
-	// the field report behind iss-2609100519128005 is what that costs — a
-	// refusal naming an invalid category with no accepted set, arriving as JSON
-	// on a stream the operator was not reading, made them doubt the store rather
-	// than the flag. The set is rendered from the ONE copy in core/issueschema,
-	// so it can never drift from the membership test on the line above it.
-	if !validSeverities[Severity(fm["severity"].(string))] {
-		return fmt.Errorf("%w: invalid severity %q; %s", ErrMalformedFrontmatter, fm["severity"], acceptedValues(issueschema.Severities))
-	}
-	if !validCategories[Category(fm["category"].(string))] {
-		return fmt.Errorf("%w: invalid category %q; %s", ErrMalformedFrontmatter, fm["category"], acceptedValues(issueschema.Categories))
-	}
-	if !validSources[Source(fm["source"].(string))] {
-		return fmt.Errorf("%w: invalid source %q; %s", ErrMalformedFrontmatter, fm["source"], acceptedValues(issueschema.Sources))
-	}
-	if strings.TrimSpace(fm["found_during"].(string)) == "" {
-		return fmt.Errorf("%w: found_during must be non-empty", ErrMalformedFrontmatter)
-	}
-
-	// impact is optional but, when written, is checked against the ONE shared
-	// enum (internal/core/changelog) rather than a private copy — the same enum
-	// the record lint gates on and the release derivation consumes, so all three
-	// can never disagree about what a legal judgement is.
-	//
-	// A YAML null reads as ABSENT rather than as a value. The parser is where
-	// bare parts from quoted (parse.go maps every bare null spelling to "" and
-	// deliberately keeps a QUOTED null as the string it spells), so by here the
-	// only null left is the empty string. Re-testing frontmatter.IsNull on the
-	// unquoted value would swallow the quoted spellings the parser just
-	// preserved, accepting `impact: "null"` here while the record-lint blocker
-	// issue_impact_valid — which reads the raw scalar — refuses it. Both gates
-	// must reach the same verdict on one value.
-	if v, present := fm["impact"]; present {
-		s, isStr := v.(string)
-		if !isStr {
-			return fmt.Errorf("%w: %q must be a string", ErrMalformedFrontmatter, "impact")
-		}
-		if s != "" {
-			if _, err := changelog.ParseImpact(s); err != nil {
-				return fmt.Errorf("%w: %v", ErrMalformedFrontmatter, err)
-			}
-		}
-	}
-
-	// Optional scalar strings.
-	for _, opt := range []string{"found_at", "lapsed_at", "details", "suggested_fix", "wontfix_reason", "resolution"} {
-		if v, present := fm[opt]; present {
-			if _, isStr := v.(string); !isStr {
-				return fmt.Errorf("%w: %q must be a string", ErrMalformedFrontmatter, opt)
-			}
-		}
-	}
-	// lapsed_at is optional for every category, lapse included, and an RFC 3339
-	// instant whenever it is present. spc-60 made it REQUIRED on a lapse; that
-	// refusal is parked (iss-2609091009111294) until the rethink of the reading
-	// work settles what a lapse record must carry. The format half is checked
-	// after the type loop above, so a non-string value is reported as the type
-	// error it is, and it reads the ONE shared definition in core/issueschema —
-	// the same one the committed-ledger gate reads.
-	lapsedAt := strings.TrimSpace(asString(fm["lapsed_at"]))
-	if lapsedAt != "" && !issueschema.ValidLapsedAt(lapsedAt) {
-		return fmt.Errorf("%w: lapsed_at %q is not an RFC 3339 instant (want 2026-08-28T00:00:00Z)",
-			ErrMalformedFrontmatter, lapsedAt)
-	}
-
-	// Optional id-list fields.
-	idListFields := []struct {
-		field string
-		re    *regexp.Regexp
-		desc  string
-	}{
-		{"related_intents", reItdID, "itd-N"},
-		{"related_specs", reSpcID, "spc-N"},
-		{"related_issues", reIssID, "iss-N"},
-		{"blocked_by", reIssID, "iss-N"},
-	}
-	for _, f := range idListFields {
-		v, present := fm[f.field]
-		if !present {
-			continue
-		}
-		items, isList := v.([]string)
-		if !isList {
-			return fmt.Errorf("%w: %q must be a list", ErrMalformedFrontmatter, f.field)
-		}
-		for _, it := range items {
-			if !f.re.MatchString(it) {
-				return fmt.Errorf("%w: %q item %q does not match %s", ErrMalformedFrontmatter, f.field, it, f.desc)
-			}
-		}
-	}
-	if v, present := fm["synthesis_clusters"]; present {
-		if _, isList := v.([]string); !isList {
-			return fmt.Errorf("%w: synthesis_clusters must be a list", ErrMalformedFrontmatter)
-		}
-	}
-	if v, present := fm["resolved_by"]; present {
-		m, isMap := v.(map[string]any)
-		if !isMap {
-			return fmt.Errorf("%w: resolved_by must be an object", ErrMalformedFrontmatter)
-		}
-		for k, sv := range m {
-			if k != "intent" && k != "spec" && k != "commit" {
-				return fmt.Errorf("%w: resolved_by has unknown key %q", ErrMalformedFrontmatter, k)
-			}
-			// Type-check the sub-value: issueFromFrontmatter reads it via asString,
-			// which coerces a non-string (a number, a list) to "". Without this
-			// check a malformed resolved_by validates cleanly and then silently
-			// loses its value on read, so the round-trip is lossy and undetected.
-			if _, isStr := sv.(string); !isStr {
-				return fmt.Errorf("%w: resolved_by.%s must be a string", ErrMalformedFrontmatter, k)
-			}
-		}
-	}
-	return nil
-}
-
-// validateInvariants enforces folder<->field invariants and filename<->id
-// match, mirroring _issue_lib._validate_invariants. Assumes validateStrict ran.
+// validateInvariants enforces the folder<->field invariants and the
+// filename<->id agreement (issuerecord.ValidateInvariants).
 func validateInvariants(fm map[string]any, status State, path string) error {
-	id, _ := fm["id"].(string)
-	if !reIssID.MatchString(id) {
-		return fmt.Errorf("%w: id %q does not match ^iss-[0-9]+$", ErrInvariantViolation, id)
-	}
-	name := filepath.Base(path)
-	fnID, fnSlug, ok := recordid.SplitRecordFilename(issFamily, name)
-	if !ok {
-		return fmt.Errorf("%w: filename %q does not match iss-N[-slug].md", ErrInvariantViolation, name)
-	}
-	if fnID != id {
-		return fmt.Errorf("%w: filename id %q does not match frontmatter id %q", ErrInvariantViolation, fnID, id)
-	}
-	// The slug is the other half of the same agreement, and it is checked the
-	// same way: exactly, not leniently. Capture derives the slug once (deriveSlug
-	// is where the 60-char cap is applied), normalises it once, and hands that one
-	// string to both writers — reservePath builds issID+"-"+slug+".md" while
-	// commitCapture stores the identical variable as fm["slug"]. The cap therefore
-	// lands BEFORE the fork, so a filename is never a truncated form of a longer
-	// field, and a prefix match would only license the drift this check exists to
-	// catch. A name with no slug segment at all likewise disagrees: the schema
-	// requires a non-empty slug, so "" is a value that names a different record.
-	//
-	// Without this, a record renamed by hand keeps a stale handle in its filename
-	// while its frontmatter says something else, and the readers that locate a
-	// record by name and the readers that trust the field part company in silence.
-	// record-lint's record_schema asks the SAME question of the committed corpus
-	// through the same splitter, so the drift is a red gate rather than a silent
-	// skip here.
-	slug, _ := fm["slug"].(string)
-	if fnSlug != slug {
-		return fmt.Errorf("%w: filename slug %q does not match frontmatter slug %q", ErrInvariantViolation, fnSlug, slug)
-	}
-
-	_, hasResolution := fm["resolution"]
-	_, hasWontfix := fm["wontfix_reason"]
-	switch status {
-	case StateOpen:
-		if hasResolution {
-			return fmt.Errorf("%w: resolution must not appear in open/", ErrInvariantViolation)
-		}
-		if hasWontfix {
-			return fmt.Errorf("%w: wontfix_reason must not appear in open/", ErrInvariantViolation)
-		}
-	case StateResolved:
-		if !hasResolution {
-			return fmt.Errorf("%w: resolution required in resolved/", ErrMissingRequiredField)
-		}
-		if isBlank(fm["resolution"]) {
-			return fmt.Errorf("%w: resolution required non-empty in resolved/", ErrInvariantViolation)
-		}
-		if hasWontfix {
-			return fmt.Errorf("%w: wontfix_reason must not appear in resolved/", ErrInvariantViolation)
-		}
-	case StateWontfix:
-		if !hasWontfix {
-			return fmt.Errorf("%w: wontfix_reason required in wontfix/", ErrMissingRequiredField)
-		}
-		if isBlank(fm["wontfix_reason"]) {
-			return fmt.Errorf("%w: wontfix_reason required non-empty in wontfix/", ErrInvariantViolation)
-		}
-		if hasResolution {
-			return fmt.Errorf("%w: resolution must not appear in wontfix/", ErrInvariantViolation)
-		}
-	default:
-		return fmt.Errorf("%w: unknown status directory %q", ErrInvariantViolation, status)
-	}
-
-	for _, field := range uniqueItemsFields {
-		v, present := fm[field]
-		if !present {
-			continue
-		}
-		items, ok := v.([]string)
-		if !ok {
-			continue
-		}
-		seen := map[string]bool{}
-		for _, it := range items {
-			if seen[it] {
-				return fmt.Errorf("%w: %s contains duplicate items", ErrInvariantViolation, field)
-			}
-			seen[it] = true
-		}
-	}
-	return nil
+	return issuerecord.ValidateInvariants(fm, statusDirName[status], path)
 }
 
-func isBlank(v any) bool {
-	s, ok := v.(string)
-	return ok && strings.TrimSpace(s) == ""
+// parseFrontmatterAndBody splits a record into its frontmatter map and body
+// (issuerecord.Parse).
+func parseFrontmatterAndBody(text string) (map[string]any, string, error) {
+	return issuerecord.Parse(text)
 }
 
+// acceptedValues renders a closed enum's legal set for a refusal message
+// (issuerecord.AcceptedValues).
+func acceptedValues(vals []string) string { return issuerecord.AcceptedValues(vals) }
+
 // issueFromFrontmatter builds a typed Issue from a validated frontmatter map.
 func issueFromFrontmatter(fm map[string]any, status State, path, body string) Issue {
 	iss := Issue{
@@ -302,6 +58,8 @@ func issueFromFrontmatter(fm map[string]any, status State, path, body string) Is
 	iss.RelatedSpecs = asStrList(fm["related_specs"])
 	iss.RelatedIssues = asStrList(fm["related_issues"])
 	iss.BlockedBy = asStrList(fm["blocked_by"])
+	iss.Duplicates = asStrList(fm["duplicates"])
+	iss.Refines = asStrList(fm["refines"])
 	if rb, ok := fm["resolved_by"].(map[string]any); ok {
 		iss.ResolvedBy = &ResolvedBy{
 			Intent: asString(rb["intent"]),
@@ -347,15 +105,6 @@ func groundsEntries(body string) []string {
 	return out
 }
 
-// acceptedValues renders a closed enum's legal set for a refusal message.
-//
-// One helper rather than three literal lists, so the message and the membership
-// test read the same slice: a value added to core/issueschema appears in the
-// refusal without anyone remembering to add it.
-func acceptedValues(vals []string) string {
-	return "accepted values: " + strings.Join(vals, " | ")
-}
-
 // ReadRefusal reports the error the ledger's read path would skip a committed
 // record with, or nil when it reads the record: the same parse, the same strict
 // schema validation and the same folder/filename invariants List runs, in that
@@ -366,14 +115,15 @@ func acceptedValues(vals []string) string {
 // reader refuses, by asking the reader rather than re-deriving its grammar: a
 // record the reader skips is invisible to every capture surface while it still
 // sits in the ledger, and each private copy of the grammar the gate carried drifted
-// from this one somewhere (iss-2608300205044566, iss-2608300244483405).
+// from this one somewhere (iss-2608300205044566, iss-2608300244483405). The
+// judgement itself is core/issuerecord's, the one the ledger reader runs.
 func ReadRefusal(content, status, path string) error {
-	fm, _, err := parseFrontmatterAndBody(content)
+	fm, _, err := issuerecord.Parse(content)
 	if err != nil {
 		return err
 	}
-	if err := validateStrict(fm); err != nil {
+	if err := issuerecord.ValidateStrict(fm); err != nil {
 		return err
 	}
-	return validateInvariants(fm, State(status), path)
+	return issuerecord.ValidateInvariants(fm, status, path)
 }
diff --git a/internal/core/capture/workflow.go b/internal/core/capture/workflow.go
index cf298ea8f..1a21fb389 100644
--- a/internal/core/capture/workflow.go
+++ b/internal/core/capture/workflow.go
@@ -11,8 +11,10 @@ import (
 
 	"github.com/intentdriven/abcd/internal/core/changelog"
 	"github.com/intentdriven/abcd/internal/core/grounds"
+	"github.com/intentdriven/abcd/internal/core/issuerecord"
 	"github.com/intentdriven/abcd/internal/core/issueschema"
 	"github.com/intentdriven/abcd/internal/core/provenance"
+	"github.com/intentdriven/abcd/internal/core/record/match"
 	"github.com/intentdriven/abcd/internal/core/relink"
 	"github.com/intentdriven/abcd/internal/fsutil"
 	"github.com/intentdriven/abcd/internal/termsafe"
@@ -256,10 +258,17 @@ func commitCapture(repoRoot, issuesRoot string, req CaptureRequest, issID, slug,
 		// Written inside the ledger's os.Root (iss-2609012037143368): an ancestor
 		// swapped since the re-read above cannot carry the record out of the
 		// checkout.
+		// The filing-time match (itd-2609212137116617) runs here, under the
+		// ledger lock, so the ledger it reads is the one the record joins. It
+		// adds links to the content and never fails the write.
+		var matched *match.Outcome
+		if req.Match != nil {
+			content, matched = matchAndLink(repoRoot, issuesRoot, *req.Match, req.Text, content, fm)
+		}
 		if werr := writeLedgerFile(repoRoot, issuesRoot, placeholder, []byte(content)); werr != nil {
 			return werr
 		}
-		result = CaptureResult{ID: issID, Slug: slug, Path: placeholder, Status: StateOpen}
+		result = CaptureResult{ID: issID, Slug: slug, Path: placeholder, Status: StateOpen, Match: matched}
 		return nil
 	})
 	if err != nil {
@@ -686,9 +695,19 @@ func List(req ListRequest) (ListResult, error) {
 	if state != StateAll && state != StateOpen && state != StateResolved && state != StateWontfix {
 		return ListResult{}, fmt.Errorf("state must be all/open/resolved/wontfix, got %q", state)
 	}
-	issues, skipped := scanLedger(ir, state)
+	issues, skipped, err := scanLedger(ir, state)
+	if err != nil {
+		return ListResult{}, err
+	}
 	sortIssues(issues)
-	prioritise(issues, openIDSet(ir))
+	// The blocked_by projection reads open/ whatever the scope, so an open/
+	// that cannot be listed is a fault here too: every dependent would read as
+	// unblocked.
+	openIDs, err := openIDSet(ir)
+	if err != nil {
+		return ListResult{}, err
+	}
+	prioritise(issues, openIDs)
 	relativiseLedgerPaths(repoRoot, issues, skipped)
 	if set, ok := uncommittedLedgerPaths(repoRoot, ir); ok {
 		markUncommitted(set, issues)
@@ -732,9 +751,18 @@ func Status(req StatusRequest) (StatusResult, error) {
 		return StatusResult{}, err
 	}
 	var res StatusResult
-	open, skOpen := scanLedger(ir, StateOpen)
-	resolved, skRes := scanLedger(ir, StateResolved)
-	wontfix, skWf := scanLedger(ir, StateWontfix)
+	open, skOpen, err := scanLedger(ir, StateOpen)
+	if err != nil {
+		return StatusResult{}, err
+	}
+	resolved, skRes, err := scanLedger(ir, StateResolved)
+	if err != nil {
+		return StatusResult{}, err
+	}
+	wontfix, skWf, err := scanLedger(ir, StateWontfix)
+	if err != nil {
+		return StatusResult{}, err
+	}
 	res.OpenCount = len(open)
 	res.ResolvedCount = len(resolved)
 	res.WontfixCount = len(wontfix)
@@ -801,9 +829,14 @@ func prioritise(issues []Issue, openIDs map[string]bool) {
 }
 
 // openIDSet returns the set of ids currently in open/ — the predicate a
-// blocked_by target must satisfy to still count as blocking. Read-only.
-func openIDSet(issuesRoot string) map[string]bool {
-	return openBlockingIDs(scanLedger(issuesRoot, StateOpen))
+// blocked_by target must satisfy to still count as blocking. Read-only. An
+// open/ that exists and cannot be listed is the fault readStatusDir names.
+func openIDSet(issuesRoot string) (map[string]bool, error) {
+	open, skipped, err := scanStatusDir(issuesRoot, StateOpen)
+	if err != nil {
+		return nil, err
+	}
+	return openBlockingIDs(open, skipped), nil
 }
 
 // openBlockingIDs is that predicate over ONE scan of open/: the ids that listed,
@@ -848,8 +881,10 @@ func idSet(issues []Issue) map[string]bool {
 }
 
 // scanLedger reads issues from the requested state(s). Stray/non-matching .md
-// files are silently ignored; corrupt matching files go into Skipped.
-func scanLedger(issuesRoot string, state State) ([]Issue, []SkipRecord) {
+// files are silently ignored; corrupt matching files go into Skipped. A status
+// directory that exists and cannot be listed is a fault, returned as
+// readStatusDir names it: the ledger was not read, so no count is reported.
+func scanLedger(issuesRoot string, state State) ([]Issue, []SkipRecord, error) {
 	var targets []State
 	if state == StateAll {
 		targets = statusDirs
@@ -859,70 +894,51 @@ func scanLedger(issuesRoot string, state State) ([]Issue, []SkipRecord) {
 	var issues []Issue
 	var skipped []SkipRecord
 	for _, sub := range targets {
-		dir := filepath.Join(issuesRoot, statusDirName[sub])
-		entries, err := os.ReadDir(dir)
+		got, sk, err := scanStatusDir(issuesRoot, sub)
 		if err != nil {
-			continue // virgin/absent ledger tolerance
+			return nil, nil, err
 		}
-		names := make([]string, 0, len(entries))
-		for _, e := range entries {
-			names = append(names, e.Name())
+		issues = append(issues, got...)
+		skipped = append(skipped, sk...)
+	}
+	return issues, skipped, nil
+}
+
+// scanStatusDir reads the records of ONE status directory. The directory is
+// listed through readStatusDir, where an absent directory and an unreadable one
+// part company once for every reader of the ledger: absent is a virgin ledger
+// and reads as no records, while a directory that exists and cannot be listed
+// is returned as the error naming it — a reader that counted it as empty would
+// report a ledger it never read (iss-2609261241121312, iss-2609261631120364).
+func scanStatusDir(issuesRoot string, sub State) ([]Issue, []SkipRecord, error) {
+	var issues []Issue
+	var skipped []SkipRecord
+	dir := filepath.Join(issuesRoot, statusDirName[sub])
+	entries, err := readStatusDir(issuesRoot, statusDirName[sub])
+	if err != nil {
+		return nil, nil, err
+	}
+	names := make([]string, 0, len(entries))
+	for _, e := range entries {
+		names = append(names, e.Name())
+	}
+	sort.Strings(names)
+	for _, name := range names {
+		path := filepath.Join(dir, name)
+		// The verdict on each file is the record reader's (core/issuerecord),
+		// the one record-lint reports from, so a record this scan skips is never
+		// green at the gate (iss-2609261631132673).
+		fm, body, refusal, claims := issuerecord.Judge(path, statusDirName[sub])
+		if !claims {
+			continue
 		}
-		sort.Strings(names)
-		for _, name := range names {
-			path := filepath.Join(dir, name)
-			wellFormed := issFileNumRe.MatchString(name)
-			if !wellFormed {
-				// A file that claims to be a record (family prefix + ordinal) and is
-				// not well-formed is REPORTED, not dropped: it sits in the ledger,
-				// counted by nothing and reported by nothing, which is how a record
-				// gets silently lost. A file claiming nothing — README.md, a stray
-				// note, the allocator lock — is silently ignored, as before.
-				//
-				// Detection uses recordid.FilenameNumRe, the SAME grammar the resolver
-				// and record-lint's per-store rule read, so a filename the gate and
-				// the resolver treat as a record reaches the reader too rather than
-				// being dropped by a stricter local grammar (iss-2608280739112123).
-				// The stricter slug shape is still enforced — as a filename<->
-				// frontmatter agreement, below in validateInvariants — but that is a
-				// judgement on a record, not the question of whether one exists.
-				if filepath.Ext(name) == ".md" && reIssNameClaim.MatchString(name) {
-					skipped = append(skipped, SkipRecord{Path: path, Layer: SkipLayerName, Error: fmt.Errorf(
-						"%w: filename %q is not a well-formed record name (iss-N[-slug].md)",
-						ErrInvariantViolation, name).Error()})
-				}
-				continue
-			}
-			// A well-formed name always ends .md — the grammar's pattern requires
-			// it — so no separate extension check is needed on this path.
-			//
-			// The read is guarded, not bare: a well-formed NAME says nothing about
-			// the leaf behind it, and in a hostile clone that leaf is a FIFO that
-			// would hang this scan, a symlink to a file outside the ledger, or a
-			// body sized to make the read unbounded. Each is a skipped record the
-			// surfaces already render, never a hang and never serialized.
-			content, err := readRecordGuarded(path)
-			if err != nil {
-				skipped = append(skipped, SkipRecord{Path: path, Layer: SkipLayerRead, Error: err.Error()})
-				continue
-			}
-			fm, body, err := parseFrontmatterAndBody(content)
-			if err != nil {
-				skipped = append(skipped, SkipRecord{Path: path, Layer: SkipLayerFrontmatter, Error: err.Error()})
-				continue
-			}
-			if err := validateStrict(fm); err != nil {
-				skipped = append(skipped, SkipRecord{Path: path, Layer: SkipLayerSchema, Error: err.Error()})
-				continue
-			}
-			if err := validateInvariants(fm, sub, path); err != nil {
-				skipped = append(skipped, SkipRecord{Path: path, Layer: SkipLayerInvariant, Error: err.Error()})
-				continue
-			}
-			issues = append(issues, issueFromFrontmatter(fm, sub, path, body))
+		if refusal != nil {
+			skipped = append(skipped, SkipRecord{Path: path, Layer: refusal.Layer, Error: refusal.Err.Error()})
+			continue
 		}
+		issues = append(issues, issueFromFrontmatter(fm, sub, path, body))
 	}
-	return issues, skipped
+	return issues, skipped, nil
 }
 
 // sortIssues orders issues ascending by numeric N.
diff --git a/internal/core/frontmatter/isnull_test.go b/internal/core/frontmatter/isnull_test.go
index d85345db0..67eff43f5 100644
--- a/internal/core/frontmatter/isnull_test.go
+++ b/internal/core/frontmatter/isnull_test.go
@@ -56,3 +56,23 @@ func TestIsNullRequiresTheRawScalar(t *testing.T) {
 		t.Fatal(`IsNull("\"null\"") must be false: quotes make it the three-character string`)
 	}
 }
+
+// A null spelled with a trailing comment is a null to every reader of Fields:
+// the scanner strips the comment before the value reaches IsNull, so
+// `superseded_by: NULL # no successor` reads as the null token and not as the
+// string `NULL # no successor` (iss-2608241347321759). The strip landed with
+// iss-2608301744268001; this pins the null half of it, for every spelling.
+func TestFieldsReadsACommentedNullAsNull(t *testing.T) {
+	for _, v := range []string{"", "~", "null", "Null", "NULL"} {
+		t.Run(v, func(t *testing.T) {
+			lines := []string{"---", "superseded_by: " + v + " # no successor", "---"}
+			got := frontmatter.Fields(lines)["superseded_by"].Value
+			if !frontmatter.IsNull(got) {
+				t.Errorf("superseded_by %q read as %q, which IsNull calls a value", v, got)
+			}
+		})
+	}
+	if got := frontmatter.Fields([]string{"---", `superseded_by: "null" # quoted`, "---"})["superseded_by"].Value; frontmatter.IsNull(got) {
+		t.Errorf("a quoted \"null\" read as %q, which IsNull calls null; quoting makes it a string", got)
+	}
+}
diff --git a/internal/core/grounds/grounds.go b/internal/core/grounds/grounds.go
index 41e9c5fa9..4e43905e4 100644
--- a/internal/core/grounds/grounds.go
+++ b/internal/core/grounds/grounds.go
@@ -12,9 +12,10 @@
 // no reading of the grammar and imports nothing from here. It imports core/mdrecord — the record-body machinery the
 // `## Grounds` section is read and written through — and core/frontmatter, for
 // the one rule about where a record's frontmatter stops and its body begins;
-// and internal/termsafe, whose hidden-rune encoder a written text passes
-// through; otherwise only the standard library: no filesystem, no transport, no
-// record store.
+// internal/termsafe, whose hidden-rune encoder a written text passes through;
+// and core/mdrender, the site's Markdown renderer, which the constructors ask
+// whether the entry they are about to hand a writer will render; otherwise only
+// the standard library: no filesystem, no transport, no record store.
 //
 // The grounds name the CONJECTURE being acted on, not the route taken. "Planned
 // it because it is next" restates the decision; "planned it because we expect a
@@ -32,6 +33,7 @@ import (
 	"strings"
 	"unicode"
 
+	"github.com/intentdriven/abcd/internal/core/mdrender"
 	"github.com/intentdriven/abcd/internal/termsafe"
 )
 
@@ -55,7 +57,7 @@ const (
 // Vocabulary is the closed set, in the order a surface should offer it. The two
 // refusals that reject a TOKEN -- Parse's grammar refusal and ParseToken's --
 // render it (vocabularyList), so a caller told their token is wrong is told
-// which tokens are right. The package's other eleven refusals render nothing of
+// which tokens are right. The package's other refusals render nothing of
 // the kind -- and that is all this comment claims about them. Two earlier
 // spellings each replaced an overclaim with a smaller one: first that every
 // refusal rendered the list, then that the other eleven all speak about the
@@ -250,14 +252,15 @@ func New(tok Token, text string) (Grounds, error) {
 	if err := ValidateText(folded); err != nil {
 		return Grounds{}, err
 	}
-	return Grounds{Token: t, Text: termsafe.EncodeHiddenRunes(folded)}, nil
+	return renderable(Grounds{Token: t, Text: termsafe.EncodeHiddenRunes(folded)})
 }
 
 // NewDerived builds a Grounds whose text is DERIVED from another required value
 // rather than supplied to the argument — a wontfix's `declined:` entry stamped
 // from its reason. It takes the same path New does with the substance floor left
 // off: the text is folded, refused for the control characters ValidateText
-// refuses, and hidden runes are encoded. The floor stays with what a caller
+// refuses, hidden runes are encoded, and the entry is refused when the site's
+// renderer would refuse it — a derived entry is as append-only as a supplied one. The floor stays with what a caller
 // supplies, because the value it is derived from has its own contract and a
 // terse reason is a legal one (iss-2608301244450106).
 func NewDerived(tok Token, text string) (Grounds, error) {
@@ -272,7 +275,27 @@ func NewDerived(tok Token, text string) (Grounds, error) {
 	if err := validateControl(folded); err != nil {
 		return Grounds{}, err
 	}
-	return Grounds{Token: t, Text: termsafe.EncodeHiddenRunes(folded)}, nil
+	return renderable(Grounds{Token: t, Text: termsafe.EncodeHiddenRunes(folded)})
+}
+
+// renderable refuses a ground whose entry the site's renderer would refuse, and
+// otherwise returns it unchanged. It is asked by BOTH constructors, of the text
+// exactly as it will be written, because the entry is append-only: no verb
+// removes it once it lands, so a record the site cannot render stays that way
+// until somebody hand-edits a committed record, and `site-render` is a
+// preflight gate, a CI step and a release gate (iss-2608301646046226).
+//
+// The question is put to the renderer itself (mdrender.RefusalIn) over the
+// bullet the record will carry, never to a list of its rules kept here: a copy
+// of the renderer's refusals is a copy that stops agreeing with it.
+func renderable(g Grounds) (Grounds, error) {
+	if err := mdrender.RefusalIn(g.Bullet()); err != nil {
+		return Grounds{}, fmt.Errorf(
+			"grounds text %q carries a construct the site renderer refuses: %v; the entry is append-only "+
+				"and the record it lands in must still build, so it is refused before anything is written — "+
+				"put markup in a closed code span or reword it", g.Text, err)
+	}
+	return g, nil
 }
 
 // Fold collapses every run of whitespace to a single space and trims the ends —
diff --git a/internal/core/grounds/grounds_test.go b/internal/core/grounds/grounds_test.go
index 96093ff8e..db7f2e0e5 100644
--- a/internal/core/grounds/grounds_test.go
+++ b/internal/core/grounds/grounds_test.go
@@ -525,3 +525,86 @@ func TestVocabularyRenderings(t *testing.T) {
 		}
 	}
 }
+
+// TestNewRefusesWhatTheSiteRendererRefuses: a grounds entry is append-only and
+// lands in a record the site renders, so text the site's renderer refuses must be
+// refused where it enters, or the record lands and `abcd site build` goes red
+// with no verb that can take the entry back out (iss-2608301646046226). The
+// first five are the constructs the security review verified; the rest are the
+// renderer's other inline refusals, which the shared predicate covers because it
+// IS the renderer.
+func TestNewRefusesWhatTheSiteRendererRefuses(t *testing.T) {
+	refused := map[string]string{
+		"an unclosed code span":       "we expect the `--grounds flag to make the conjecture survive the session",
+		"a remote image":              "we expect ![the chart](https://example.com/c.png) to show the drift shrinking",
+		"a raw div":                   `we expect <div class="note">this page</div> to stay readable after the change`,
+		"an undefined reference link": "we expect [the ledger][nowhere] to record the conjecture we pursued",
+		"a footnote link":             "we expect the conjecture [see the note][^1] to survive rewording",
+		"a link title":                `we expect [the page](https://example.com "a title") to keep its reader`,
+		"an executable link scheme":   "we expect [this link](javascript:void) to be refused by every reader",
+		"an unterminated comment":     "we expect the record <!-- to keep every line below this entry",
+		"a nested link":               "we expect [a [nested](https://example.com) link](https://example.com) to render",
+		"inline html":                 "we expect <span>marked words</span> to carry the conjecture forward",
+	}
+	for what, text := range refused {
+		if g, err := New(Pursued, text); err == nil {
+			t.Errorf("New admitted %s, which the site renderer refuses: %q", what, g.Text)
+		} else if !strings.Contains(err.Error(), "site") {
+			t.Errorf("the refusal of %s does not say the site cannot render it: %v", what, err)
+		}
+	}
+
+	admitted := map[string]string{
+		"a closed code span":  "we expect the `--grounds` flag to make the conjecture survive the session",
+		"an inline link":      "we expect [the ledger](https://example.com/ledger) to record the conjecture",
+		"a literal bracket":   "we expect the array [0] to hold the first conjecture we recorded",
+		"a prose placeholder": "we expect the `<ts>` stamp and <ts> placeholder to survive rewording",
+		"emphasis left open":  "we expect the *stamped identity to survive rewording in the record",
+	}
+	for what, text := range admitted {
+		if _, err := New(Pursued, text); err != nil {
+			t.Errorf("New refused %s, which the site renders: %v", what, err)
+		}
+	}
+}
+
+// TestNewDerivedRefusesWhatTheSiteRendererRefuses: a wontfix stamps its
+// `declined:` entry from its reason, and that entry is as append-only as a
+// supplied one, so the derived constructor asks the renderer too. The substance
+// floor stays off: a terse reason that renders is still admitted.
+func TestNewDerivedRefusesWhatTheSiteRendererRefuses(t *testing.T) {
+	if g, err := NewDerived(Declined, "the `--grounds flag is out of scope"); err == nil {
+		t.Errorf("NewDerived admitted an unclosed code span, which the site renderer refuses: %q", g.Text)
+	}
+	if _, err := NewDerived(Declined, "out of scope"); err != nil {
+		t.Errorf("NewDerived refused a terse reason that renders: %v", err)
+	}
+}
+
+// TestMalformedInIsTheReadersComplement: MalformedIn names exactly the top-level
+// bullets under `## Grounds` that ParseSection skips, with their FILE line, so a
+// gate built on it reports what the reader drops and nothing else
+// (iss-2608301747001641). Prose, a masked bullet, a bullet under another heading
+// and a frontmatter comment are not entries the reader offered, and stay silent.
+func TestMalformedInIsTheReadersComplement(t *testing.T) {
+	file := "---\nid: iss-1\n# Grounds\n---\n\nan issue\n\n## Grounds\n\n" +
+		"- pursued: " + conjecture + "\n" + // line 10: an entry
+		"- rejected: refusing the whole file\n" + // line 11: out of vocabulary
+		"- pursued\n" + // line 12: no colon
+		"\nprose under the heading\n\n" +
+		"```\n- planned: masked\n```\n\n" +
+		"## Later\n\n- planned: another section\n"
+	got := MalformedIn(file)
+	if len(got) != 2 {
+		t.Fatalf("MalformedIn = %+v, want the two bullets the reader skips", got)
+	}
+	if got[0].Line != 11 || !strings.HasPrefix(got[0].Text, "rejected:") || got[0].Err == nil {
+		t.Errorf("first = %+v, want line 11, the rejected bullet, with the grammar's refusal", got[0])
+	}
+	if got[1].Line != 12 || got[1].Text != "pursued" {
+		t.Errorf("second = %+v, want line 12, the colon-less bullet", got[1])
+	}
+	if n := len(ParseSection(Body(file))); n != 1 {
+		t.Errorf("ParseSection read %d entries, want the one well-formed bullet", n)
+	}
+}
diff --git a/internal/core/grounds/record.go b/internal/core/grounds/record.go
index 13c376e81..b03f3cec7 100644
--- a/internal/core/grounds/record.go
+++ b/internal/core/grounds/record.go
@@ -46,9 +46,8 @@ func Body(content string) string {
 
 // Heading is the section a record carries its grounds under. It is spelled once
 // for the two that have to agree: the writer that creates the section and the
-// reader that locates it, across both record families. Record-lint names the
-// section in a remedy as literal prose, because core/lint does not import this
-// package and one message is not a reason to (iss-2608301836222858).
+// reader that locates it, across both record families, and record-lint names it
+// in its remedies from here.
 const Heading = "Grounds"
 
 // headingRe matches the `## Grounds` heading at any heading depth.
@@ -58,9 +57,9 @@ var headingRe = regexp.MustCompile(`^#{1,6}\s+` + Heading + `\s*$`)
 // written. It is the single reader every consumer asks, so no two of them can
 // disagree about what an entry is.
 //
-// A bullet that does not parse is not an entry: it is prose under the heading,
-// and reporting it as a malformed ground would put a gate verdict on a sentence
-// somebody wrote for a human.
+// A bullet that does not parse is not an entry, and the reader says nothing
+// about it: a reader has no verdict to give. The record gate does, and asks
+// MalformedIn, the other half of the same walk, which bullets were skipped.
 //
 // It checks the GRAMMAR and stops there, which is what lets the ledger use it. A
 // wontfix stamps its grounds from a reason whose own contract is merely
@@ -69,19 +68,74 @@ var headingRe = regexp.MustCompile(`^#{1,6}\s+` + Heading + `\s*$`)
 // visibly carries one. A consumer that claims the floor asks for
 // ParseSectionAboveFloor instead.
 func ParseSection(content string) []Grounds {
+	var out []Grounds
+	for _, b := range sectionBullets(content) {
+		if b.err == nil {
+			out = append(out, b.g)
+		}
+	}
+	return out
+}
+
+// sectionBullet is one top-level bullet under the `## Grounds` heading, read
+// through the grammar: the entry when it parses, the refusal when it does not.
+type sectionBullet struct {
+	line int // 0-based line of the bullet in the text read
+	text string
+	g    Grounds
+	err  error
+}
+
+// sectionBullets is the ONE walk of the section, and ParseSection and
+// MalformedIn are its two halves: the bullets that parse, and the ones that do
+// not. Spelled once so the gate that reports a dropped bullet and the reader that
+// drops it cannot disagree about which bullets those are.
+func sectionBullets(content string) []sectionBullet {
 	lines := strings.Split(content, "\n")
 	mask := mdrecord.Mask(lines)
 	start, end, ok := mdrecord.SectionLineRangeIn(lines, mask, headingRe)
 	if !ok {
 		return nil
 	}
-	var out []Grounds
+	var out []sectionBullet
 	for _, b := range mdrecord.BulletBlocks(lines, mask, start, end) {
-		g, err := Parse(blockText(lines, b))
-		if err != nil {
-			continue
+		text := blockText(lines, b)
+		g, err := Parse(text)
+		out = append(out, sectionBullet{line: b.Start, text: text, g: g, err: err})
+	}
+	return out
+}
+
+// Malformed is a top-level bullet under a record's `## Grounds` heading that the
+// grammar refuses, so ParseSection does not take it as an entry.
+type Malformed struct {
+	// Line is the bullet's 1-based line in the record FILE.
+	Line int
+	// Text is the bullet folded onto one line, its `- ` marker removed.
+	Text string
+	// Err is the grammar's refusal.
+	Err error
+}
+
+// MalformedIn names every top-level bullet under the `## Grounds` heading of a
+// record FILE that the reader skips, with its file line.
+//
+// It is the gate's half of the reader's contract. ParseSection declines a bullet
+// that does not parse and says nothing, which is right for a reader with no
+// verdict to give and wrong for the record as a whole: a malformed `grounds:`
+// frontmatter value was a value a gate could judge, and moving grounds into the
+// section made a malformed one silently absent (iss-2608301747001641). A bullet
+// in the section is an entry attempt — the section is the verbs' append-only
+// list — while a paragraph of prose under the heading is not a bullet and is
+// never named here.
+func MalformedIn(file string) []Malformed {
+	head, body := frontmatter.Split(file)
+	offset := strings.Count(head, "\n")
+	var out []Malformed
+	for _, b := range sectionBullets(body) {
+		if b.err != nil {
+			out = append(out, Malformed{Line: offset + b.line + 1, Text: b.text, Err: b.err})
 		}
-		out = append(out, g)
 	}
 	return out
 }
@@ -144,7 +198,12 @@ func blockText(lines []string, b mdrecord.BulletBlock) string {
 //
 // The count question subsumes more than the comment one: a bullet swallowed by a
 // fence, by a mask this reader does not yet model, or by anything else, fails to
-// raise the count and is refused for the same reason. The comment question is
+// raise the count and is refused for the same reason. It answers for THIS
+// reader only. The site's renderer reads the same record in the same preflight
+// and refuses constructs this reader accepts — an unclosed code span, an image,
+// raw HTML, a reference link — and that question is asked where a Grounds is
+// built (New, NewDerived), of the site's renderer itself, so a Grounds that
+// reaches this writer through either constructor already renders. The comment question is
 // still asked separately because it is the one whose remedy the caller can act
 // on — "close the comment, or drop the marker" — and a refusal that can name the
 // cause is worth more than one that can only say the entry did not arrive.
@@ -195,6 +254,10 @@ func AppendToRecord(content string, g Grounds) (string, error) {
 // bullet's `- ` prefix rules out. So the line this names is the operator's to
 // close, and the grounds text is not.
 //
+// The refusal also names the exit. No verb edits a record body, so the repair is
+// the hand edit the 2026-08-31 ruling accepted: close or remove the opener in a
+// text editor, then re-run the verb (iss-2608301908270888).
+//
 // The line is counted from the start of the BODY, and the opener's own text is
 // quoted beside it. A file-relative number would be wrong: the triage verbs
 // append after setting their note field, so the content in hand carries
@@ -208,7 +271,8 @@ func readBackRefusal(body string, got, want int) error {
 		return fmt.Errorf(
 			"the record's body leaves %s open: the opener is body line %d, %q. An unclosed opener runs "+
 				"to end of file, so every line below it — the appended entry included — is masked and "+
-				"does not read back. Close it or remove it; the grounds text is not the fault; nothing written",
+				"does not read back. Close it or remove it in a text editor, then re-run; the grounds text is "+
+				"not the fault; nothing written",
 			maskConstruct(flag), i+1, strings.TrimRight(lines[i], "\r"))
 	}
 	return fmt.Errorf(
diff --git a/internal/core/history/gitleaks_explain_test.go b/internal/core/history/gitleaks_explain_test.go
new file mode 100644
index 000000000..64bd59531
--- /dev/null
+++ b/internal/core/history/gitleaks_explain_test.go
@@ -0,0 +1,59 @@
+package history
+
+import (
+	"errors"
+	"fmt"
+	"strings"
+	"testing"
+
+	"github.com/intentdriven/abcd/internal/adapter/gitleaks"
+	"github.com/intentdriven/abcd/internal/adapter/scanner"
+	"github.com/intentdriven/abcd/internal/core/tools"
+)
+
+// TestCaptureExplainsTheMissingGitleaks is itd-63 criterion 4 at the one
+// missing-scanner path on main: the transcript store of a repository that armed
+// gitleaks. The refusal stands (fail-closed, nothing stored), and it now says
+// what gitleaks is, that this repository requires it, the exact install step,
+// and the way back to the native scanner, rather than a bare error.
+func TestCaptureExplainsTheMissingGitleaks(t *testing.T) {
+	repoRoot, _ := setupStore(t)
+	restore := scanGitleaks
+	t.Cleanup(func() { scanGitleaks = restore })
+	scanGitleaks = func(_, _, _ string) ([]scanner.Finding, error) {
+		return nil, fmt.Errorf("%w: not on PATH and no path configured", gitleaks.ErrConfiguredNotFound)
+	}
+	_, err := Capture(repoRoot, testRootSHA, []byte("user: hi\n"), CaptureMeta{SessionID: "sess-explain", Kind: "native"})
+	if err == nil {
+		t.Fatal("capture did not fail closed")
+	}
+	if !errors.Is(err, gitleaks.ErrConfiguredNotFound) {
+		t.Fatalf("the explanation lost the sentinel: %v", err)
+	}
+	var missing *tools.MissingError
+	if !errors.As(err, &missing) || missing.Explanation.Capability != tools.TranscriptScanArmed {
+		t.Fatalf("error carries no registry explanation: %v", err)
+	}
+	e := tools.Explain("gitleaks", tools.TranscriptScanArmed)
+	for _, want := range []string{"gitleaks configured but not found", "required for", e.StepText(), "enabled to false"} {
+		if !strings.Contains(err.Error(), want) {
+			t.Errorf("refusal lacks %q:\n%s", want, err)
+		}
+	}
+}
+
+// TestCaptureDoesNotExplainARefusedPath: a binary that exists but is refused
+// is not a missing tool, and gets no install offer.
+func TestCaptureDoesNotExplainARefusedPath(t *testing.T) {
+	repoRoot, _ := setupStore(t)
+	restore := scanGitleaks
+	t.Cleanup(func() { scanGitleaks = restore })
+	scanGitleaks = func(_, _, _ string) ([]scanner.Finding, error) {
+		return nil, gitleaks.ErrConfiguredPathRefused
+	}
+	_, err := Capture(repoRoot, testRootSHA, []byte("user: hi\n"), CaptureMeta{SessionID: "sess-refused", Kind: "native"})
+	var missing *tools.MissingError
+	if err == nil || errors.As(err, &missing) {
+		t.Fatalf("a refused path was explained as a missing tool: %v", err)
+	}
+}
diff --git a/internal/core/history/history.go b/internal/core/history/history.go
index dab4f4706..b10f1392f 100644
--- a/internal/core/history/history.go
+++ b/internal/core/history/history.go
@@ -35,6 +35,7 @@ import (
 	"github.com/intentdriven/abcd/internal/adapter/gitleaks"
 	"github.com/intentdriven/abcd/internal/adapter/scanner"
 	"github.com/intentdriven/abcd/internal/core/sessionkind"
+	"github.com/intentdriven/abcd/internal/core/tools"
 	"github.com/intentdriven/abcd/internal/fsutil"
 )
 
@@ -268,6 +269,13 @@ func Capture(repoRoot, rootSHA string, raw []byte, meta CaptureMeta) (CaptureRes
 	// asked for.
 	extra, err := scanGitleaks(repoRoot, text, "transcript")
 	if err != nil {
+		// A binary the repository asked for and nobody installed is a missing
+		// tool: the refusal stands, and it says what gitleaks is, that this
+		// repository requires it, the install step, and the way back to the
+		// native scanner (itd-63). A refused path is not a missing tool.
+		if errors.Is(err, gitleaks.ErrConfiguredNotFound) {
+			err = tools.Missing(err, "gitleaks", tools.TranscriptScanArmed)
+		}
 		return CaptureResult{}, fmt.Errorf("history: %w", err)
 	}
 	findings = append(findings, extra...)
diff --git a/internal/core/implement/load.go b/internal/core/implement/load.go
index e2e6b071e..4240f6aba 100644
--- a/internal/core/implement/load.go
+++ b/internal/core/implement/load.go
@@ -10,6 +10,7 @@ import (
 	"runtime"
 	"time"
 
+	"github.com/intentdriven/abcd/internal/cienv"
 	"github.com/intentdriven/abcd/internal/core/banlist"
 	"github.com/intentdriven/abcd/internal/core/machineload"
 	"github.com/intentdriven/abcd/internal/fsutil"
@@ -191,7 +192,7 @@ func CheckLoad(req LoadRequest) LoadResult {
 		Site: req.Site, Triggers: []string{}, OwnStrays: []LoadOwnStray{}, Remedy: []LoadRemedy{},
 		WithinPreflight: getenv(loadCheckedEnv) == SitePreflight,
 	}
-	if reason, ci := ciRunner(getenv); ci {
+	if reason, ci := cienv.Runner(getenv); ci {
 		res.Status = LoadSkipped
 		res.Reason = "skipped on a CI runner (" + reason + "): a fresh runner carries no programs left from earlier work, so there is nothing to warn about"
 		return res
@@ -266,25 +267,6 @@ func CheckLoad(req LoadRequest) LoadResult {
 	return res
 }
 
-// ciRunner reports whether the environment is a CI runner, and names the
-// variable that says so: GITHUB_ACTIONS=true, or a CI value other than empty,
-// "false" or "0".
-func ciRunner(getenv func(string) string) (string, bool) {
-	if getenv("GITHUB_ACTIONS") == "true" {
-		return "GITHUB_ACTIONS=true", true
-	}
-	switch v := getenv("CI"); v {
-	case "", "false", "0":
-		return "", false
-	default:
-		shown := termsafe.Sanitize(v)
-		if len(shown) > 32 {
-			shown = shown[:32]
-		}
-		return "CI=" + shown, true
-	}
-}
-
 // readLimits reads ~/.abcd/load-limits through the guarded declaration read the
 // other home-scope files use: a regular file, not a symlink, owned by the
 // caller, writable by nobody else, at most 4 KiB. The check never creates the
diff --git a/internal/core/intent/create.go b/internal/core/intent/create.go
index e36cd14e7..660af41cc 100644
--- a/internal/core/intent/create.go
+++ b/internal/core/intent/create.go
@@ -11,6 +11,7 @@ import (
 
 	"github.com/intentdriven/abcd/internal/core/changelog"
 	"github.com/intentdriven/abcd/internal/core/provenance"
+	"github.com/intentdriven/abcd/internal/core/record/match"
 	"github.com/intentdriven/abcd/internal/core/recordid"
 	"github.com/intentdriven/abcd/internal/termsafe"
 )
@@ -59,9 +60,16 @@ const maxSlugLen = 60
 // `abcd intent plan` schedules it. This is the quoted-text create path itd-46
 // delivers — the create half of what spc-6 AC3 (promote) needs.
 func CreateFromText(repoRoot, text string, opts TextOptions) (Intent, error) {
+	c, err := createFromText(repoRoot, text, opts, nil)
+	return c.Intent, err
+}
+
+// createFromText is CreateFromText with the optional filing-time match
+// (match.go), which runs inside CreateDraft's mint lock.
+func createFromText(repoRoot, text string, opts TextOptions, m *Matcher) (Created, error) {
 	trimmed := strings.TrimSpace(text)
 	if trimmed == "" {
-		return Intent{}, fmt.Errorf("intent: refusing to create from empty text")
+		return Created{}, fmt.Errorf("intent: refusing to create from empty text")
 	}
 	// An explicit title is held to the text's own bar before anything is
 	// derived: non-empty once trimmed, and one line — it becomes the H1, where a
@@ -71,10 +79,10 @@ func CreateFromText(repoRoot, text string, opts TextOptions) (Intent, error) {
 	// alike rather than one of them silently falling back to the derived H1.
 	title := strings.TrimSpace(opts.Title)
 	if (opts.TitleSet || opts.Title != "") && title == "" {
-		return Intent{}, fmt.Errorf("intent: refusing an empty --title (nothing written)")
+		return Created{}, fmt.Errorf("intent: refusing an empty --title (nothing written)")
 	}
 	if strings.ContainsAny(title, "\r\n") {
-		return Intent{}, fmt.Errorf("intent: --title must be a single line (nothing written)")
+		return Created{}, fmt.Errorf("intent: --title must be a single line (nothing written)")
 	}
 	// Redact the caller's text through the one canonical scanner BEFORE anything
 	// derived from it is built (gh-486). The slug becomes the filename and is
@@ -85,11 +93,11 @@ func CreateFromText(repoRoot, text string, opts TextOptions) (Intent, error) {
 	// body again as its own boundary guard; that second pass is idempotent here.
 	redacted, _, err := redactIntentText(repoRoot, trimmed)
 	if err != nil {
-		return Intent{}, err
+		return Created{}, err
 	}
 	slug, err := deriveIntentSlug(redacted)
 	if err != nil {
-		return Intent{}, err
+		return Created{}, err
 	}
 	if title == "" {
 		title = deriveTitle(redacted)
@@ -97,10 +105,10 @@ func CreateFromText(repoRoot, text string, opts TextOptions) (Intent, error) {
 		// The same boundary the text crossed: the title is free prose too, and
 		// CreateDraft's own pass is idempotent on it.
 		if title, _, err = redactIntentText(repoRoot, title); err != nil {
-			return Intent{}, err
+			return Created{}, err
 		}
 	}
-	return CreateDraft(repoRoot, DraftOptions{
+	it, outcome, err := createDraftMatched(repoRoot, DraftOptions{
 		Slug:         slug,
 		Title:        title,
 		PressRelease: redacted,
@@ -109,7 +117,9 @@ func CreateFromText(repoRoot, text string, opts TextOptions) (Intent, error) {
 		// the default; the production mode is the operator's declared one, or the
 		// repo's default resolved by the surface.
 		ProductionMode: opts.ProductionMode,
+		Match:          m,
 	})
+	return Created{Intent: it, Match: outcome}, err
 }
 
 // TextOptions parameterizes CreateFromText beyond the text itself: an explicit
@@ -193,6 +203,11 @@ type DraftOptions struct {
 	// provenance.DefaultMode, so a draft written through a command carries the key
 	// whatever the caller says.
 	ProductionMode string
+	// Match, when non-nil, matches the draft's title and press release against
+	// the record under the mint lock and writes each likely double as a typed
+	// link (match.go). The promote route passes none: its draft is joined to
+	// the record it graduated from already.
+	Match *Matcher
 }
 
 // relatedIssueRe constrains the promote back-edge to a captured id before it is
@@ -211,17 +226,24 @@ var relatedIssueRe = regexp.MustCompile(`^(iss|rdi)-[0-9]+$`)
 // id through the shared recordid seam, and atomically writes
 // drafts/itd-N-<slug>.md. On any refusal nothing is written.
 func CreateDraft(repoRoot string, opts DraftOptions) (Intent, error) {
+	it, _, err := createDraftMatched(repoRoot, opts)
+	return it, err
+}
+
+// createDraftMatched is CreateDraft returning the filing-time match's outcome too,
+// nil when opts asked for none.
+func createDraftMatched(repoRoot string, opts DraftOptions) (Intent, *match.Outcome, error) {
 	if !slugRe.MatchString(opts.Slug) {
-		return Intent{}, fmt.Errorf("intent: slug %q is not kebab-case", opts.Slug)
+		return Intent{}, nil, fmt.Errorf("intent: slug %q is not kebab-case", opts.Slug)
 	}
 	if strings.TrimSpace(opts.Title) == "" {
-		return Intent{}, fmt.Errorf("intent: refusing to create a draft with an empty title")
+		return Intent{}, nil, fmt.Errorf("intent: refusing to create a draft with an empty title")
 	}
 	if strings.TrimSpace(opts.SeedBody) == "" && strings.TrimSpace(opts.PressRelease) == "" {
-		return Intent{}, fmt.Errorf("intent: refusing to create a draft with neither a press release nor a seed body")
+		return Intent{}, nil, fmt.Errorf("intent: refusing to create a draft with neither a press release nor a seed body")
 	}
 	if opts.RelatedIssue != "" && !relatedIssueRe.MatchString(opts.RelatedIssue) {
-		return Intent{}, fmt.Errorf("intent: related issue %q must match ^(iss|rdi)-[0-9]+$", opts.RelatedIssue)
+		return Intent{}, nil, fmt.Errorf("intent: related issue %q must match ^(iss|rdi)-[0-9]+$", opts.RelatedIssue)
 	}
 	// impact is optional on a draft (intent_impact_valid gates the move into
 	// shipped/, not the seed), but when set it must be a legal, non-internal
@@ -231,10 +253,10 @@ func CreateDraft(repoRoot string, opts DraftOptions) (Intent, error) {
 	if opts.Impact != "" {
 		imp, err := changelog.ParseImpact(opts.Impact)
 		if err != nil {
-			return Intent{}, fmt.Errorf("intent: %w", err)
+			return Intent{}, nil, fmt.Errorf("intent: %w", err)
 		}
 		if imp == changelog.ImpactInternal {
-			return Intent{}, fmt.Errorf("intent: impact must not be internal on an intent — a press-release-first intent is user-facing by definition; declare one of additive|breaking|fix, or record the work as an issue instead")
+			return Intent{}, nil, fmt.Errorf("intent: impact must not be internal on an intent — a press-release-first intent is user-facing by definition; declare one of additive|breaking|fix, or record the work as an issue instead")
 		}
 	}
 
@@ -244,7 +266,7 @@ func CreateDraft(repoRoot string, opts DraftOptions) (Intent, error) {
 	// path; an unset mode means provenance.DefaultMode.
 	stamp, err := draftStamp(opts)
 	if err != nil {
-		return Intent{}, fmt.Errorf("intent: %w", err)
+		return Intent{}, nil, fmt.Errorf("intent: %w", err)
 	}
 
 	// Boundary redaction (gh-486): CreateDraft is the ONE canonical draft-mint
@@ -257,15 +279,15 @@ func CreateDraft(repoRoot string, opts DraftOptions) (Intent, error) {
 	// scanner; the pass is idempotent for text a caller already redacted.
 	rTitle, _, err := redactIntentText(repoRoot, opts.Title)
 	if err != nil {
-		return Intent{}, err
+		return Intent{}, nil, err
 	}
 	rPress, _, err := redactIntentText(repoRoot, opts.PressRelease)
 	if err != nil {
-		return Intent{}, err
+		return Intent{}, nil, err
 	}
 	rBody, _, err := redactIntentText(repoRoot, opts.SeedBody)
 	if err != nil {
-		return Intent{}, err
+		return Intent{}, nil, err
 	}
 	// Hidden runes — a bidi override, a zero-width rune, a C1 control, DEL — are
 	// percent-encoded at the same boundary, after redaction, with termsafe's one
@@ -276,6 +298,7 @@ func CreateDraft(repoRoot string, opts DraftOptions) (Intent, error) {
 	opts.SeedBody = termsafe.EncodeHiddenRunesBlock(rBody)
 
 	var created Intent
+	var outcome *match.Outcome
 	err = withIntentMintLock(repoRoot, func() error {
 		draftsDirAbs := filepath.Join(repoRoot, IntentsRelDir, BucketDrafts)
 		if err := ensureRecordDir(repoRoot, filepath.Join(IntentsRelDir, BucketDrafts)); err != nil {
@@ -292,7 +315,14 @@ func CreateDraft(repoRoot string, opts DraftOptions) (Intent, error) {
 		name := id + "-" + opts.Slug + ".md"
 		rel := filepath.Join(IntentsRelDir, BucketDrafts, name)
 		abs := filepath.Join(draftsDirAbs, name)
-		content := seedDraft(id, opts, stamp)
+		// The filing-time match runs here, under the mint lock, so the record
+		// it reads is the record the draft is written into.
+		var links map[match.Relation][]string
+		if opts.Match != nil {
+			outcome = runMatch(opts.Match, opts.Title+"\n"+opts.PressRelease)
+			links = outcome.Links()
+		}
+		content := seedDraft(id, opts, stamp, links)
 		if err := writeIntentFile(abs, rel, content); err != nil {
 			return err
 		}
@@ -310,9 +340,9 @@ func CreateDraft(repoRoot string, opts DraftOptions) (Intent, error) {
 		return nil
 	})
 	if err != nil {
-		return Intent{}, err
+		return Intent{}, nil, err
 	}
-	return created, Validate(created)
+	return created, outcome, Validate(created)
 }
 
 // draftStamp resolves the draft's disclosure pair from the mint options: the
@@ -413,7 +443,7 @@ var intentFileNumRe = recordid.FilenameNumRe(intentFamily)
 // Press Release prose or the route's seed note, the Why This Matters seed body
 // or its prompt, and the itd-1 discipline's Acceptance Criteria section left as
 // a placeholder for the human to fill before planning.
-func seedDraft(id string, opts DraftOptions, stamp provenance.Stamp) string {
+func seedDraft(id string, opts DraftOptions, stamp provenance.Stamp, links map[match.Relation][]string) string {
 	var b strings.Builder
 	b.WriteString("---\n")
 	b.WriteString("id: " + id + "\n")
@@ -431,6 +461,13 @@ func seedDraft(id string, opts DraftOptions, stamp provenance.Stamp) string {
 	if opts.RelatedIssue != "" {
 		b.WriteString(RelatedIssuesKey + ": [" + opts.RelatedIssue + "]\n")
 	}
+	// The filing-time match's typed links (itd-2609212137116617), an inline id
+	// list each, written only when a candidate cleared the threshold.
+	for _, rel := range []match.Relation{match.Duplicates, match.Refines} {
+		if ids := links[rel]; len(ids) > 0 {
+			b.WriteString(string(rel) + ": [" + strings.Join(ids, ", ") + "]\n")
+		}
+	}
 	// impact is written only when the caller declared one (validated in
 	// CreateDraft). It is bare — the machine-read enum the shipped-intent gate
 	// compares byte-for-byte — and travels unchanged to shipped/. An unset impact
diff --git a/internal/core/intent/match.go b/internal/core/intent/match.go
new file mode 100644
index 000000000..b505bb29a
--- /dev/null
+++ b/internal/core/intent/match.go
@@ -0,0 +1,126 @@
+package intent
+
+import (
+	"path/filepath"
+	"regexp"
+	"strings"
+
+	"github.com/intentdriven/abcd/internal/core/frontmatter"
+	"github.com/intentdriven/abcd/internal/core/mdrecord"
+	"github.com/intentdriven/abcd/internal/core/record/match"
+)
+
+// match.go is the intent store's half of the filing-time match
+// (itd-2609212137116617): the text every intent offers as a candidate, and the
+// quoted-text create that matches a new draft against the record before it is
+// written. The score is internal/core/record/match's; the ledger gathers the
+// candidate set, because the ledger reads intents and this store does not read
+// the ledger.
+
+// MatchText is one intent's comparable text: its H1 and its press release.
+// A press release that is still the seed note a create wrote is left out, since
+// every promoted draft carries the same words there.
+type MatchText struct {
+	ID           string
+	Title        string
+	PressRelease string
+}
+
+var (
+	titleH1Re      = regexp.MustCompile(`^#\s+(.+?)\s*$`)
+	pressReleaseRe = regexp.MustCompile(`^##\s+Press Release\s*$`)
+	seedReduceRe   = regexp.MustCompile(`[>_*\s]+`)
+)
+
+// MatchTexts reads the title and press release of every intent in every
+// bucket. A store no reader can load is an error, which the match reports as
+// its reason for comparing nothing, never as a refusal of the write.
+func MatchTexts(repoRoot string) ([]MatchText, error) {
+	c, err := Load(repoRoot)
+	if err != nil {
+		return nil, err
+	}
+	out := make([]MatchText, 0, len(c.Intents))
+	for _, it := range c.Intents {
+		data, err := readRepoFile(filepath.Join(repoRoot, it.Path), it.Path)
+		if err != nil {
+			return nil, err
+		}
+		out = append(out, matchTextOf(it.ID, string(data)))
+	}
+	return out, nil
+}
+
+func matchTextOf(id, content string) MatchText {
+	lines := strings.Split(content, "\n")
+	// The body starts after the frontmatter's closing delimiter.
+	start := 0
+	if len(lines) > 0 && frontmatter.IsDelimiter(frontmatter.TrimBOM(lines[0])) {
+		for i := 1; i < len(lines); i++ {
+			if frontmatter.IsDelimiter(lines[i]) {
+				start = i + 1
+				break
+			}
+		}
+	}
+	body := lines[start:]
+	mt := MatchText{ID: id}
+	mask := mdrecord.Mask(body)
+	for i, ln := range body {
+		if mask[i] != 0 {
+			continue
+		}
+		if m := titleH1Re.FindStringSubmatch(strings.TrimRight(ln, "\r")); m != nil {
+			mt.Title = m[1]
+			break
+		}
+	}
+	if s, e, ok := mdrecord.SectionLineRangeIn(body, mask, pressReleaseRe); ok {
+		press := strings.TrimSpace(strings.Join(body[s:e], "\n"))
+		if !IsSeedNote(strings.TrimSpace(seedReduceRe.ReplaceAllString(press, " "))) {
+			mt.PressRelease = press
+		}
+	}
+	return mt
+}
+
+// Matcher is a create's request to be matched before it is written: the
+// threshold, and the candidate set, which the caller's reader gathers and the
+// create calls under the store's mint lock.
+type Matcher struct {
+	Threshold  float64
+	Candidates func() ([]match.Candidate, error)
+}
+
+// Created is a quoted-text create's result: the draft, and the match's
+// outcome when one was asked for.
+type Created struct {
+	Intent
+	Match *match.Outcome `json:"match,omitempty"`
+}
+
+// CreateFromTextMatched is CreateFromText with the filing-time match: the new
+// draft's title and press release are compared with the candidates under the
+// mint lock, and each likely double is written onto the draft as a
+// `duplicates:` or `refines:` link. The match never refuses the create: a
+// candidate set that cannot be read is reported on the outcome and the draft
+// is written unlinked. A nil matcher is CreateFromText exactly.
+func CreateFromTextMatched(repoRoot, text string, opts TextOptions, m *Matcher) (Created, error) {
+	return createFromText(repoRoot, text, opts, m)
+}
+
+// runMatch runs m over text, turning a candidate read that fails into an
+// outcome that says so rather than an error.
+func runMatch(m *Matcher, text string) *match.Outcome {
+	if match.Short(text) {
+		o := match.Rank(text, nil, m.Threshold)
+		return &o
+	}
+	cands, err := m.Candidates()
+	if err != nil {
+		o := match.Unread(m.Threshold, err)
+		return &o
+	}
+	o := match.Rank(text, cands, m.Threshold)
+	return &o
+}
diff --git a/internal/core/intent/match_test.go b/internal/core/intent/match_test.go
new file mode 100644
index 000000000..390242399
--- /dev/null
+++ b/internal/core/intent/match_test.go
@@ -0,0 +1,139 @@
+package intent
+
+import (
+	"errors"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/intentdriven/abcd/internal/core/lint"
+	"github.com/intentdriven/abcd/internal/core/record/match"
+)
+
+const (
+	existingTitle = "The quiet board says who holds the next move"
+	existingPress = "The bare board names the record whose next move is waiting on a person, " +
+		"says which person, and prints the command that answers it, without opening a file."
+	newDraftText = "The bare board names the record whose next move waits on a person, " +
+		"says which person that is, and prints the command that answers it, without opening any file."
+)
+
+func fixedCandidates(cands ...match.Candidate) func() ([]match.Candidate, error) {
+	return func() ([]match.Candidate, error) {
+		return append([]match.Candidate{
+			{ID: "itd-21", Text: "The site builder renders a stale anchor for a heading renamed since the last build."},
+			{ID: "iss-22", Text: "The history store drops a transcript that exceeds its byte budget without saying so."},
+		}, cands...), nil
+	}
+}
+
+// Criterion 2: a draft whose text overlaps an existing intent's title and
+// press release is written with the link, and the result carries the match.
+func TestCreateFromTextMatchedLinksADouble(t *testing.T) {
+	root := t.TempDir()
+	m := &Matcher{Threshold: match.DefaultThreshold, Candidates: fixedCandidates(
+		match.Candidate{ID: "itd-20", Text: existingTitle + "\n" + existingPress})}
+	c, err := CreateFromTextMatched(root, newDraftText, TextOptions{}, m)
+	if err != nil {
+		t.Fatalf("create refused: %v", err)
+	}
+	if c.Match == nil || len(c.Match.Matches) != 1 || c.Match.Matches[0].ID != "itd-20" ||
+		c.Match.Matches[0].Relation != match.Duplicates {
+		t.Fatalf("match = %+v, want itd-20 as duplicates", c.Match)
+	}
+	data, err := os.ReadFile(filepath.Join(root, c.Path))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(string(data), "\nduplicates: [itd-20]\n") {
+		t.Fatalf("the draft carries no link:\n%s", data)
+	}
+	// The linked draft is as lint-valid as an unlinked one.
+	cfg := lint.Config{
+		Roots: []string{".abcd/development"},
+		Rules: map[string]lint.RuleConfig{
+			"intent_lifecycle": {Enabled: true, Severity: "blocker", IntentsDir: "intents"},
+		},
+	}
+	findings, err := lint.Lint(cfg, root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, f := range findings {
+		t.Fatalf("linked draft: %s:%d %s", f.File, f.Line, f.Message)
+	}
+}
+
+// Criteria 3 and 4: a candidate set that cannot be read never refuses the
+// create, and below the threshold nothing is written while the near misses
+// are listed.
+func TestCreateFromTextMatchedNeverRefuses(t *testing.T) {
+	root := t.TempDir()
+	broken := &Matcher{Threshold: match.DefaultThreshold, Candidates: func() ([]match.Candidate, error) {
+		return nil, errors.New("the ledger is unreadable")
+	}}
+	c, err := CreateFromTextMatched(root, newDraftText, TextOptions{}, broken)
+	if err != nil {
+		t.Fatalf("an unreadable candidate set refused the create: %v", err)
+	}
+	if c.Match == nil || !strings.Contains(c.Match.Skipped, "unreadable") {
+		t.Fatalf("outcome = %+v, want the reason nothing was compared", c.Match)
+	}
+
+	strict := &Matcher{Threshold: 0.99, Candidates: fixedCandidates(
+		match.Candidate{ID: "itd-20", Text: existingTitle + "\n" + existingPress})}
+	c, err = CreateFromTextMatched(root, newDraftText+" Also a second time.", TextOptions{}, strict)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(c.Match.Matches) != 0 || len(c.Match.NearMisses) == 0 || c.Match.NearMisses[0].ID != "itd-20" {
+		t.Fatalf("outcome = %+v, want itd-20 as a near miss only", c.Match)
+	}
+	data, _ := os.ReadFile(filepath.Join(root, c.Path))
+	if strings.Contains(string(data), "duplicates:") || strings.Contains(string(data), "refines:") {
+		t.Fatalf("a link was written below the threshold:\n%s", data)
+	}
+}
+
+// Without a matcher the create is CreateFromText exactly.
+func TestCreateFromTextMatchedWithoutAMatcher(t *testing.T) {
+	c, err := CreateFromTextMatched(t.TempDir(), newDraftText, TextOptions{}, nil)
+	if err != nil || c.Match != nil {
+		t.Fatalf("err %v, match %+v: want a plain create", err, c.Match)
+	}
+}
+
+// MatchTexts offers each intent's H1 and press release, and leaves out a press
+// release that is still a create's seed note.
+func TestMatchTextsReadsTitleAndPressRelease(t *testing.T) {
+	root := t.TempDir()
+	dir := filepath.Join(root, IntentsRelDir, BucketPlanned)
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	write := func(name, body string) {
+		if err := os.WriteFile(filepath.Join(dir, name), []byte(body), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+	write("itd-5-a.md", "---\nid: itd-5\nslug: a\n---\n\n# "+existingTitle+"\n\n## Press Release\n\n> "+
+		existingPress+"\n\n## Why This Matters\n\nNot compared.\n")
+	write("itd-6-b.md", "---\nid: itd-6\nslug: b\n---\n\n# Promoted\n\n## Press Release\n\n> _"+
+		promotionSeedOpening+"iss-9. "+seedNoteTail+"_\n")
+	texts, err := MatchTexts(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	got := map[string]MatchText{}
+	for _, mt := range texts {
+		got[mt.ID] = mt
+	}
+	if got["itd-5"].Title != existingTitle || !strings.Contains(got["itd-5"].PressRelease, "prints the command") ||
+		strings.Contains(got["itd-5"].PressRelease, "Not compared") {
+		t.Fatalf("itd-5 = %+v", got["itd-5"])
+	}
+	if got["itd-6"].Title != "Promoted" || got["itd-6"].PressRelease != "" {
+		t.Fatalf("itd-6 = %+v, want its seed note left out", got["itd-6"])
+	}
+}
diff --git a/internal/core/intent/ready_test.go b/internal/core/intent/ready_test.go
index 5e92eed2e..37ea4f1d0 100644
--- a/internal/core/intent/ready_test.go
+++ b/internal/core/intent/ready_test.go
@@ -518,7 +518,7 @@ func TestReadyClaimChecksNotApplicableInTerminalBuckets(t *testing.T) {
 // and the gate must not report it as one.
 func TestReadyScaffoldPromptIsNotAClaim(t *testing.T) {
 	root := t.TempDir()
-	seeded := seedDraft("itd-10", DraftOptions{Slug: "alpha", Title: "alpha", SeedBody: "why it matters"}, researcherStamp(t))
+	seeded := seedDraft("itd-10", DraftOptions{Slug: "alpha", Title: "alpha", SeedBody: "why it matters"}, researcherStamp(t), nil)
 	// Plan the criteria only, so the two claim sections stay as seeded.
 	seeded = strings.Replace(seeded,
 		"> _Required (the itd-1 discipline)", "- **Given** x, **when** y, **then** z.\n\n> _was: ", 1)
diff --git a/internal/core/capture/parse.go b/internal/core/issuerecord/parse.go
similarity index 90%
rename from internal/core/capture/parse.go
rename to internal/core/issuerecord/parse.go
index f10a65daa..ae154cbdf 100644
--- a/internal/core/capture/parse.go
+++ b/internal/core/issuerecord/parse.go
@@ -1,4 +1,4 @@
-package capture
+package issuerecord
 
 import (
 	"fmt"
@@ -8,7 +8,7 @@ import (
 	"github.com/intentdriven/abcd/internal/core/frontmatter"
 )
 
-// parseFrontmatterAndBody splits text into a frontmatter map and a body,
+// Parse splits text into a frontmatter map and a body,
 // mirroring _issue_lib._parse_text_with_body. The text MUST start with an
 // opening --- line; the next un-indented --- closes the block. At most one
 // leading blank line after the closing delimiter is stripped from the body.
@@ -27,8 +27,8 @@ import (
 // lists (`[]`, `[itd-4, fn-12]`, `["a", "b"]`), and a single level of nested
 // object (used only by the optional resolved_by field). Values decode to
 // string, int, []string, or map[string]any.
-func parseFrontmatterAndBody(text string) (map[string]any, string, error) {
-	lines := splitKeepEnds(text)
+func Parse(text string) (map[string]any, string, error) {
+	lines := SplitKeepEnds(text)
 	// TrimBOM applies to lines[0] and nowhere else: U+FEFF is a byte-order mark
 	// only at the file's first position, and a mid-file "\ufeff---" is an
 	// ordinary body line (iss-2608270926036966).
@@ -58,14 +58,14 @@ func parseFrontmatterAndBody(text string) (map[string]any, string, error) {
 		body = body[1:]
 	}
 
-	fm, err := parseFrontmatterBlock(lines[1:closeIdx])
+	fm, err := ParseBlock(lines[1:closeIdx])
 	if err != nil {
 		return nil, "", err
 	}
 	return fm, body, nil
 }
 
-// parseFrontmatterBlock parses the interior lines of a frontmatter block.
+// ParseBlock parses the interior lines of a frontmatter block.
 // nextLineIsIndented reports whether the line after i begins an indented block,
 // skipping blank lines. It is the lookahead that separates `key:` as a null from
 // `key:` as the head of a nested object.
@@ -87,14 +87,14 @@ func quotedScalar(rest string) bool {
 	return len(t) >= 2 && strings.HasPrefix(t, `"`) && strings.HasSuffix(t, `"`)
 }
 
-// parseFrontmatterBlock parses the interior lines of a frontmatter block,
+// ParseBlock parses the interior lines of a frontmatter block,
 // deciding null-vs-string while the RAW scalar is still in hand.
 //
 // An earlier draft split this in two and threaded a set of quoted keys out to the
 // validator. The decision is made inline here, so that set was never populated and
 // both callers discarded it — dead scaffolding, and the comment justifying it was
 // false as well. One function, no reserved return.
-func parseFrontmatterBlock(lines []string) (map[string]any, error) {
+func ParseBlock(lines []string) (map[string]any, error) {
 	fm := map[string]any{}
 	i := 0
 	for i < len(lines) {
@@ -157,7 +157,7 @@ func parseFrontmatterBlock(lines []string) (map[string]any, error) {
 				if sidx < 0 {
 					return nil, fmt.Errorf("%w: nested line is not key: value %q", ErrMalformedFrontmatter, subRaw)
 				}
-				sval, err := parseScalarOrList(strings.TrimSpace(frontmatter.StripComment(subTrim[sidx+1:])))
+				sval, err := ParseScalarOrList(strings.TrimSpace(frontmatter.StripComment(subTrim[sidx+1:])))
 				if err != nil {
 					return nil, err
 				}
@@ -171,14 +171,14 @@ func parseFrontmatterBlock(lines []string) (map[string]any, error) {
 			fm[key] = sub
 			continue
 		}
-		val, err := parseScalarOrList(rest)
+		val, err := ParseScalarOrList(rest)
 		if err != nil {
 			return nil, err
 		}
 		// Normalise a BARE YAML null to the empty string, and leave a quoted one
 		// as the string it is (iss-285).
 		//
-		// parseScalarOrList unquotes, which destroys the only thing separating
+		// ParseScalarOrList unquotes, which destroys the only thing separating
 		// `impact: null` from `impact: "null"` — and record-lint tests the RAW
 		// scalar, so the two gates reached opposite verdicts on one record: the
 		// lint saw a string and refused, capture saw a null and passed. That is
@@ -212,8 +212,8 @@ func parseFrontmatterBlock(lines []string) (map[string]any, error) {
 // raw scalar — quotes included — rather than on its decoded string.
 var rawScalarKeys = map[string]bool{"impact": true}
 
-// parseScalarOrList decodes one YAML value into string, int, or []string.
-func parseScalarOrList(s string) (any, error) {
+// ParseScalarOrList decodes one YAML value into string, int, or []string.
+func ParseScalarOrList(s string) (any, error) {
 	if s == "[]" {
 		return []string{}, nil
 	}
@@ -285,3 +285,20 @@ func decodeScalar(s string) (any, error) {
 	// Bare token (unquoted string, e.g. an abcd id or a legacy value).
 	return s, nil
 }
+
+// SplitKeepEnds splits s into lines preserving their trailing newline(s),
+// mirroring Python's str.splitlines(keepends=True) for \n and \r\n.
+func SplitKeepEnds(s string) []string {
+	var out []string
+	start := 0
+	for i := 0; i < len(s); i++ {
+		if s[i] == '\n' {
+			out = append(out, s[start:i+1])
+			start = i + 1
+		}
+	}
+	if start < len(s) {
+		out = append(out, s[start:])
+	}
+	return out
+}
diff --git a/internal/core/issuerecord/read.go b/internal/core/issuerecord/read.go
new file mode 100644
index 000000000..2fa69a68b
--- /dev/null
+++ b/internal/core/issuerecord/read.go
@@ -0,0 +1,157 @@
+// Package issuerecord is the issue ledger's record reader: the one judgement of
+// whether a file in a status directory is a record the ledger takes, and if not,
+// which reader stage refused it and why.
+//
+// It is a leaf for the reason core/issueschema is: the ledger's surfaces
+// (core/capture) and the gate on the committed ledger (core/lint) must reach
+// one verdict on one file, and a record they disagree about sits in the ledger
+// unread by every surface while the gate stays green (iss-2609261631132673). It
+// is not inside core/capture because that package's own tests import core/lint,
+// so a lint importing capture back is an import cycle.
+package issuerecord
+
+import (
+	"errors"
+	"fmt"
+	"io/fs"
+	"path/filepath"
+	"regexp"
+	"syscall"
+
+	"github.com/intentdriven/abcd/internal/core/issueschema"
+	"github.com/intentdriven/abcd/internal/core/recordid"
+	"github.com/intentdriven/abcd/internal/fsutil"
+)
+
+// Layer is the reader stage that refused a ledger file, in scan order.
+type Layer string
+
+// The reader's stages, in the order a file meets them.
+const (
+	// LayerName: the filename claims a record and is not a well-formed one.
+	LayerName Layer = "filename"
+	// LayerRead: the guarded read refused the leaf (a FIFO, a symlink, an
+	// oversize body, an I/O error) — nothing about the record's content.
+	LayerRead Layer = "read"
+	// LayerFrontmatter: the bytes do not parse as a frontmatter block.
+	LayerFrontmatter Layer = "frontmatter"
+	// LayerSchema: the frontmatter parses and the issue schema refuses a key or
+	// value in it.
+	LayerSchema Layer = "schema"
+	// LayerInvariant: schema-clean, and the record disagrees with where it sits
+	// — its filename, or the status folder holding it.
+	LayerInvariant Layer = "invariant"
+)
+
+// Refusal is the reader's reason for skipping one file: the stage that refused
+// it and that stage's error.
+type Refusal struct {
+	Layer Layer
+	Err   error
+}
+
+func (r *Refusal) Error() string { return string(r.Layer) + ": " + r.Err.Error() }
+
+func (r *Refusal) Unwrap() error { return r.Err }
+
+var (
+	// nameClaimRe matches a filename that CLAIMS to be a ledger record: the
+	// family prefix followed by an ordinal. It is deliberately LOOSER than
+	// recordid.SplitRecordFilename, and the gap between the two is the point — a
+	// name that claims to be a record and then is not well-formed is reported as
+	// a skip rather than dropped, while a file claiming nothing (README.md,
+	// notes.md, iss-notes.md, the allocator lock) stays silently ignored. The
+	// ordinal is what parts the two: prose that merely starts with the prefix is
+	// not asserting an id.
+	nameClaimRe = regexp.MustCompile(`^iss-[0-9]`)
+	// fileNumRe is the ONE grammar that decides whether a ledger filename NAMES
+	// a record — recordid.FilenameNumRe, which the read-side resolver and
+	// record-lint's per-store rule match too (iss-2608280739112123).
+	fileNumRe = recordid.FilenameNumRe(issFamily)
+)
+
+// Judge is the ledger reader's verdict on the file at path, which sits in the
+// status directory named status (open, resolved or wontfix). claims is false
+// for a file that claims no record — README.md, a stray note, the allocator
+// lock — which every reader ignores. Otherwise exactly one of fm and refusal is
+// set: the record's frontmatter and body when the reader takes it, the stage
+// and reason when it skips it.
+func Judge(path, status string) (fm map[string]any, body string, refusal *Refusal, claims bool) {
+	name := filepath.Base(path)
+	if !fileNumRe.MatchString(name) {
+		// A file that claims to be a record (family prefix + ordinal) and is not
+		// well-formed is REPORTED, not dropped: it sits in the ledger, counted by
+		// nothing and reported by nothing, which is how a record gets silently
+		// lost. A file claiming nothing is silently ignored.
+		//
+		// The stricter slug shape is still enforced — as a filename<->frontmatter
+		// agreement, in ValidateInvariants — but that is a judgement on a record,
+		// not the question of whether one exists.
+		if filepath.Ext(name) == ".md" && nameClaimRe.MatchString(name) {
+			return nil, "", &Refusal{LayerName, fmt.Errorf(
+				"%w: filename %q is not a well-formed record name (iss-N[-slug].md)",
+				ErrInvariantViolation, name)}, true
+		}
+		return nil, "", nil, false
+	}
+	// A well-formed name always ends .md — the grammar's pattern requires it —
+	// so no separate extension check is needed on this path.
+	//
+	// The read is guarded, not bare: a well-formed NAME says nothing about the
+	// leaf behind it, and in a hostile clone that leaf is a FIFO that would hang
+	// the scan, a symlink to a file outside the ledger, or a body sized to make
+	// the read unbounded. Each is a skipped record, never a hang and never
+	// serialized.
+	content, err := ReadGuarded(path)
+	if err != nil {
+		return nil, "", &Refusal{LayerRead, err}, true
+	}
+	fm, body, err = Parse(content)
+	if err != nil {
+		return nil, "", &Refusal{LayerFrontmatter, err}, true
+	}
+	if err := ValidateStrict(fm); err != nil {
+		return nil, "", &Refusal{LayerSchema, err}, true
+	}
+	if err := ValidateInvariants(fm, status, path); err != nil {
+		return nil, "", &Refusal{LayerInvariant, err}, true
+	}
+	return fm, body, nil, true
+}
+
+// ReadGuarded reads one record file through the shared trust-boundary
+// primitive: fsutil.ReadGuarded opens once with O_NOFOLLOW and O_NONBLOCK and
+// validates on the SAME descriptor, so no symlink swap fits between a check and
+// the read, and a FIFO or device at a record name cannot block the open. The cap
+// is issueschema.RecordReadLimit, the ONE cap the ledger's families share —
+// core/lint applies the same value, because a cap the board applies loosely and
+// the verb applies tightly makes the ledger say two things about one file.
+//
+// It is the reader for EVERY record family core/capture reads. The reading and
+// disposition families used it from the start; the issue family read through a
+// bare os.ReadFile until GHSA-fh9j-8xmg-m33f, so a committed FIFO hung `list`,
+// an oversize record was serialized unbounded, and a committed symlink read an
+// out-of-tree file into `list --json` (iss-2609012036271396). A record store a
+// clone carries is a trust boundary whichever family the record belongs to.
+//
+// The sentinels are mapped to ErrPathUnsafe: a non-regular leaf, or a symlink
+// refused by O_NOFOLLOW, is what every caller already tests for.
+func ReadGuarded(path string) (string, error) {
+	data, err := fsutil.ReadGuarded(path, issueschema.RecordReadLimit)
+	if err == nil {
+		return string(data), nil
+	}
+	if errors.Is(err, fsutil.ErrNotRegular) || errors.Is(err, syscall.ELOOP) {
+		return "", fmt.Errorf("%w: record path is not a regular file: %s", ErrPathUnsafe, path)
+	}
+	if errors.Is(err, fsutil.ErrTooBig) {
+		return "", fmt.Errorf("%w: record is larger than the %d-byte size cap and was left unread: %s", ErrPathUnsafe, issueschema.RecordReadLimit, path)
+	}
+	// A record the process may not open is a refusal with a name, not a raw open
+	// error surfacing through a verb: the caller is told the ledger could not be
+	// read and which file, rather than a syscall's own wording.
+	if errors.Is(err, fs.ErrPermission) {
+		return "", fmt.Errorf("%w: record is unreadable (permission denied): %s", ErrPathUnsafe, path)
+	}
+	return "", err
+}
diff --git a/internal/core/issuerecord/validate.go b/internal/core/issuerecord/validate.go
new file mode 100644
index 000000000..cfa8dddd8
--- /dev/null
+++ b/internal/core/issuerecord/validate.go
@@ -0,0 +1,332 @@
+package issuerecord
+
+import (
+	"errors"
+	"fmt"
+	"path/filepath"
+	"regexp"
+	"strings"
+
+	"github.com/intentdriven/abcd/internal/core/changelog"
+	"github.com/intentdriven/abcd/internal/core/issueschema"
+	"github.com/intentdriven/abcd/internal/core/recordid"
+)
+
+// The reader's refusal sentinels. core/capture re-exports each under its own
+// name, so a caller testing errors.Is against either spelling tests one value.
+var (
+	// ErrInvariantViolation means frontmatter passed the schema but violates a
+	// folder-status cross-field invariant.
+	ErrInvariantViolation = errors.New("invariant violation")
+	// ErrMalformedFrontmatter means frontmatter could not be parsed or failed
+	// schema validation.
+	ErrMalformedFrontmatter = errors.New("malformed frontmatter")
+	// ErrMissingRequiredField means a schema-required field was absent.
+	ErrMissingRequiredField = errors.New("missing required field")
+	// ErrPathUnsafe means the ledger root or a status dir is a symlink, or a
+	// record leaf is not a regular file the guarded read will open.
+	ErrPathUnsafe = errors.New("path unsafe")
+)
+
+// The id shapes the schema's id-list fields take, mirroring issue.schema.json.
+var (
+	IssIDRe = regexp.MustCompile(`^iss-[0-9]+$`)
+	ItdIDRe = regexp.MustCompile(`^itd-[0-9]+$`)
+	SpcIDRe = regexp.MustCompile(`^spc-[0-9]+$`)
+	// LinkIDRe is the shape of a typed link's target (duplicates, refines): an
+	// issue or an intent, the two families the filing-time match compares with.
+	LinkIDRe = regexp.MustCompile(`^(iss|itd)-[0-9]+$`)
+)
+
+// issFamily is the issue family's filename prefix, without its hyphen.
+const issFamily = "iss"
+
+// The enum-membership sets, derived from the ONE copy of the value lists in
+// core/issueschema.
+var (
+	severities = stringSet(issueschema.Severities)
+	categories = stringSet(issueschema.Categories)
+	sources    = stringSet(issueschema.Sources)
+)
+
+func stringSet(vals []string) map[string]bool {
+	m := make(map[string]bool, len(vals))
+	for _, v := range vals {
+		m[v] = true
+	}
+	return m
+}
+
+// AcceptedValues renders a closed enum's legal set for a refusal message.
+//
+// One helper rather than three literal lists, so the message and the membership
+// test read the same slice: a value added to core/issueschema appears in the
+// refusal without anyone remembering to add it.
+func AcceptedValues(vals []string) string {
+	return "accepted values: " + strings.Join(vals, " | ")
+}
+
+// uniqueItemsFields are the array properties issue.schema.json flags
+// uniqueItems:true.
+var uniqueItemsFields = []string{"related_intents", "related_specs", "related_issues", "synthesis_clusters", "blocked_by", "duplicates", "refines"}
+
+// ValidateStrict validates a frontmatter map against the issue schema. It
+// special-cases schema_version first (mirrors _validate_strict) and rejects
+// unknown keys (additionalProperties:false).
+func ValidateStrict(fm map[string]any) error {
+	sv, ok := fm["schema_version"]
+	if !ok {
+		return fmt.Errorf("%w: missing required property 'schema_version'", ErrMissingRequiredField)
+	}
+	if n, isInt := sv.(int); !isInt || n != 1 {
+		return fmt.Errorf("%w: unsupported schema_version %v (this reader only handles 1)", ErrMissingRequiredField, sv)
+	}
+
+	for k := range fm {
+		if successor, retired := issueschema.Retired[k]; retired {
+			return fmt.Errorf("%w: retired property %q (renamed to %q); %s",
+				ErrMalformedFrontmatter, k, successor, issueschema.MigrateHint)
+		}
+		if !issueschema.Known[k] {
+			return fmt.Errorf("%w: unknown property %q", ErrMalformedFrontmatter, k)
+		}
+	}
+
+	// Required strings — the schema's own list (core/issueschema) minus
+	// schema_version, which the version check above already answered for. The
+	// record lint reads the SAME list, so the reader and the committed-ledger gate
+	// cannot disagree about what a well-formed record carries.
+	for _, req := range issueschema.RequiredStrings {
+		v, present := fm[req]
+		if !present {
+			return fmt.Errorf("%w: missing required property %q", ErrMissingRequiredField, req)
+		}
+		if _, isStr := v.(string); !isStr {
+			return fmt.Errorf("%w: %q must be a string", ErrMalformedFrontmatter, req)
+		}
+	}
+
+	id := fm["id"].(string)
+	if !IssIDRe.MatchString(id) {
+		return fmt.Errorf("%w: id %q does not match ^iss-[0-9]+$", ErrMalformedFrontmatter, id)
+	}
+	if !issueschema.SlugRe.MatchString(fm["slug"].(string)) {
+		return fmt.Errorf("%w: slug %q is not kebab-case", ErrMalformedFrontmatter, fm["slug"])
+	}
+	// A closed enum's refusal NAMES THE SET IT ACCEPTS. It has the legal values
+	// in hand, and withholding them turns one round trip into several: an
+	// operator told only that their value was rejected has to go looking, and
+	// the field report behind iss-2609100519128005 is what that costs — a
+	// refusal naming an invalid category with no accepted set, arriving as JSON
+	// on a stream the operator was not reading, made them doubt the store rather
+	// than the flag. The set is rendered from the ONE copy in core/issueschema,
+	// so it can never drift from the membership test on the line above it.
+	if !severities[fm["severity"].(string)] {
+		return fmt.Errorf("%w: invalid severity %q; %s", ErrMalformedFrontmatter, fm["severity"], AcceptedValues(issueschema.Severities))
+	}
+	if !categories[fm["category"].(string)] {
+		return fmt.Errorf("%w: invalid category %q; %s", ErrMalformedFrontmatter, fm["category"], AcceptedValues(issueschema.Categories))
+	}
+	if !sources[fm["source"].(string)] {
+		return fmt.Errorf("%w: invalid source %q; %s", ErrMalformedFrontmatter, fm["source"], AcceptedValues(issueschema.Sources))
+	}
+	if strings.TrimSpace(fm["found_during"].(string)) == "" {
+		return fmt.Errorf("%w: found_during must be non-empty", ErrMalformedFrontmatter)
+	}
+
+	// impact is optional but, when written, is checked against the ONE shared
+	// enum (internal/core/changelog) rather than a private copy — the same enum
+	// the record lint gates on and the release derivation consumes, so all three
+	// can never disagree about what a legal judgement is.
+	//
+	// A YAML null reads as ABSENT rather than as a value. The parser is where
+	// bare parts from quoted (parse.go maps every bare null spelling to "" and
+	// deliberately keeps a QUOTED null as the string it spells), so by here the
+	// only null left is the empty string. Re-testing frontmatter.IsNull on the
+	// unquoted value would swallow the quoted spellings the parser just
+	// preserved, accepting `impact: "null"` here while the record-lint blocker
+	// issue_impact_valid — which reads the raw scalar — refuses it. Both gates
+	// must reach the same verdict on one value.
+	if v, present := fm["impact"]; present {
+		s, isStr := v.(string)
+		if !isStr {
+			return fmt.Errorf("%w: %q must be a string", ErrMalformedFrontmatter, "impact")
+		}
+		if s != "" {
+			if _, err := changelog.ParseImpact(s); err != nil {
+				return fmt.Errorf("%w: %v", ErrMalformedFrontmatter, err)
+			}
+		}
+	}
+
+	// Optional scalar strings.
+	for _, opt := range []string{"found_at", "lapsed_at", "details", "suggested_fix", "wontfix_reason", "resolution"} {
+		if v, present := fm[opt]; present {
+			if _, isStr := v.(string); !isStr {
+				return fmt.Errorf("%w: %q must be a string", ErrMalformedFrontmatter, opt)
+			}
+		}
+	}
+	// lapsed_at is optional for every category, lapse included, and an RFC 3339
+	// instant whenever it is present. spc-60 made it REQUIRED on a lapse; that
+	// refusal is parked (iss-2609091009111294) until the rethink of the reading
+	// work settles what a lapse record must carry. The format half is checked
+	// after the type loop above, so a non-string value is reported as the type
+	// error it is, and it reads the ONE shared definition in core/issueschema —
+	// the same one the committed-ledger gate reads.
+	lapsedRaw, _ := fm["lapsed_at"].(string)
+	lapsedAt := strings.TrimSpace(lapsedRaw)
+	if lapsedAt != "" && !issueschema.ValidLapsedAt(lapsedAt) {
+		return fmt.Errorf("%w: lapsed_at %q is not an RFC 3339 instant (want 2026-08-28T00:00:00Z)",
+			ErrMalformedFrontmatter, lapsedAt)
+	}
+
+	// Optional id-list fields.
+	idListFields := []struct {
+		field string
+		re    *regexp.Regexp
+		desc  string
+	}{
+		{"related_intents", ItdIDRe, "itd-N"},
+		{"related_specs", SpcIDRe, "spc-N"},
+		{"related_issues", IssIDRe, "iss-N"},
+		{"blocked_by", IssIDRe, "iss-N"},
+		// The filing-time match's typed links name an issue or an intent.
+		{"duplicates", LinkIDRe, "iss-N or itd-N"},
+		{"refines", LinkIDRe, "iss-N or itd-N"},
+	}
+	for _, f := range idListFields {
+		v, present := fm[f.field]
+		if !present {
+			continue
+		}
+		items, isList := v.([]string)
+		if !isList {
+			return fmt.Errorf("%w: %q must be a list", ErrMalformedFrontmatter, f.field)
+		}
+		for _, it := range items {
+			if !f.re.MatchString(it) {
+				return fmt.Errorf("%w: %q item %q does not match %s", ErrMalformedFrontmatter, f.field, it, f.desc)
+			}
+		}
+	}
+	if v, present := fm["synthesis_clusters"]; present {
+		if _, isList := v.([]string); !isList {
+			return fmt.Errorf("%w: synthesis_clusters must be a list", ErrMalformedFrontmatter)
+		}
+	}
+	if v, present := fm["resolved_by"]; present {
+		m, isMap := v.(map[string]any)
+		if !isMap {
+			return fmt.Errorf("%w: resolved_by must be an object", ErrMalformedFrontmatter)
+		}
+		for k, sv := range m {
+			if k != "intent" && k != "spec" && k != "commit" {
+				return fmt.Errorf("%w: resolved_by has unknown key %q", ErrMalformedFrontmatter, k)
+			}
+			// Type-check the sub-value: issueFromFrontmatter reads it via asString,
+			// which coerces a non-string (a number, a list) to "". Without this
+			// check a malformed resolved_by validates cleanly and then silently
+			// loses its value on read, so the round-trip is lossy and undetected.
+			if _, isStr := sv.(string); !isStr {
+				return fmt.Errorf("%w: resolved_by.%s must be a string", ErrMalformedFrontmatter, k)
+			}
+		}
+	}
+	return nil
+}
+
+// ValidateInvariants enforces folder<->field invariants and filename<->id
+// match, mirroring _issue_lib._validate_invariants. Assumes ValidateStrict ran.
+func ValidateInvariants(fm map[string]any, status, path string) error {
+	id, _ := fm["id"].(string)
+	if !IssIDRe.MatchString(id) {
+		return fmt.Errorf("%w: id %q does not match ^iss-[0-9]+$", ErrInvariantViolation, id)
+	}
+	name := filepath.Base(path)
+	fnID, fnSlug, ok := recordid.SplitRecordFilename(issFamily, name)
+	if !ok {
+		return fmt.Errorf("%w: filename %q does not match iss-N[-slug].md", ErrInvariantViolation, name)
+	}
+	if fnID != id {
+		return fmt.Errorf("%w: filename id %q does not match frontmatter id %q", ErrInvariantViolation, fnID, id)
+	}
+	// The slug is the other half of the same agreement, and it is checked the
+	// same way: exactly, not leniently. Capture derives the slug once (deriveSlug
+	// is where the 60-char cap is applied), normalises it once, and hands that one
+	// string to both writers — reservePath builds issID+"-"+slug+".md" while
+	// commitCapture stores the identical variable as fm["slug"]. The cap therefore
+	// lands BEFORE the fork, so a filename is never a truncated form of a longer
+	// field, and a prefix match would only license the drift this check exists to
+	// catch. A name with no slug segment at all likewise disagrees: the schema
+	// requires a non-empty slug, so "" is a value that names a different record.
+	//
+	// Without this, a record renamed by hand keeps a stale handle in its filename
+	// while its frontmatter says something else, and the readers that locate a
+	// record by name and the readers that trust the field part company in silence.
+	// record-lint's record_schema asks the SAME question of the committed corpus
+	// through the same splitter, so the drift is a red gate rather than a silent
+	// skip here.
+	slug, _ := fm["slug"].(string)
+	if fnSlug != slug {
+		return fmt.Errorf("%w: filename slug %q does not match frontmatter slug %q", ErrInvariantViolation, fnSlug, slug)
+	}
+
+	_, hasResolution := fm["resolution"]
+	_, hasWontfix := fm["wontfix_reason"]
+	switch status {
+	case "open":
+		if hasResolution {
+			return fmt.Errorf("%w: resolution must not appear in open/", ErrInvariantViolation)
+		}
+		if hasWontfix {
+			return fmt.Errorf("%w: wontfix_reason must not appear in open/", ErrInvariantViolation)
+		}
+	case "resolved":
+		if !hasResolution {
+			return fmt.Errorf("%w: resolution required in resolved/", ErrMissingRequiredField)
+		}
+		if isBlank(fm["resolution"]) {
+			return fmt.Errorf("%w: resolution required non-empty in resolved/", ErrInvariantViolation)
+		}
+		if hasWontfix {
+			return fmt.Errorf("%w: wontfix_reason must not appear in resolved/", ErrInvariantViolation)
+		}
+	case "wontfix":
+		if !hasWontfix {
+			return fmt.Errorf("%w: wontfix_reason required in wontfix/", ErrMissingRequiredField)
+		}
+		if isBlank(fm["wontfix_reason"]) {
+			return fmt.Errorf("%w: wontfix_reason required non-empty in wontfix/", ErrInvariantViolation)
+		}
+		if hasResolution {
+			return fmt.Errorf("%w: resolution must not appear in wontfix/", ErrInvariantViolation)
+		}
+	default:
+		return fmt.Errorf("%w: unknown status directory %q", ErrInvariantViolation, status)
+	}
+
+	for _, field := range uniqueItemsFields {
+		v, present := fm[field]
+		if !present {
+			continue
+		}
+		items, ok := v.([]string)
+		if !ok {
+			continue
+		}
+		seen := map[string]bool{}
+		for _, it := range items {
+			if seen[it] {
+				return fmt.Errorf("%w: %s contains duplicate items", ErrInvariantViolation, field)
+			}
+			seen[it] = true
+		}
+	}
+	return nil
+}
+
+func isBlank(v any) bool {
+	s, ok := v.(string)
+	return ok && strings.TrimSpace(s) == ""
+}
diff --git a/internal/core/issueschema/disposition.go b/internal/core/issueschema/disposition.go
index 098da83ab..7938baa08 100644
--- a/internal/core/issueschema/disposition.go
+++ b/internal/core/issueschema/disposition.go
@@ -21,6 +21,8 @@ package issueschema
 import (
 	"sort"
 	"strings"
+
+	"github.com/intentdriven/abcd/internal/core/frontmatter"
 )
 
 // DispositionRecord is one disposition as the standing computation sees it: the
@@ -108,7 +110,18 @@ func ParseDisposition(id, content string) DispositionRecord {
 			return DispositionRecord{ID: id}
 		}
 		seen[key] = true
-		values[key] = strings.Trim(strings.TrimSpace(value), `"'`)
+		// The value is read as the strict ledger parser reads it: a trailing
+		// comment is not part of it, and a BARE null is no value at all — asked of
+		// the raw scalar, before the quotes go, because quoting is what makes
+		// "null" a string (frontmatter.IsNull). Taking the raw remainder read
+		// `state: held # waiting` as the state `held # waiting` and a commented
+		// supersession as no edge, so the board and the verb gave two answers
+		// about one file (iss-2608241347321759).
+		raw := strings.TrimSpace(frontmatter.StripComment(value))
+		if frontmatter.IsNull(raw) {
+			raw = ""
+		}
+		values[key] = strings.Trim(raw, `"'`)
 	}
 
 	// A record citing ITSELF is not well-formed. Honouring the citation would
diff --git a/internal/core/issueschema/disposition_test.go b/internal/core/issueschema/disposition_test.go
new file mode 100644
index 000000000..8f690e17c
--- /dev/null
+++ b/internal/core/issueschema/disposition_test.go
@@ -0,0 +1,41 @@
+package issueschema
+
+import "testing"
+
+// ParseDisposition reads a value the way the strict ledger parser reads it: a
+// trailing YAML comment is not part of the value, and a bare YAML null is no
+// value at all. It kept its own `strings.Cut` and took the raw remainder, so
+// `state: held  # waiting` reached the standing computation as the state
+// `held  # waiting`, a supersession edge with a comment after it read as no edge,
+// and `exit_condition: null` read as the exit condition "null" — each a record
+// the verb reads one way and the board another (iss-2608241347321759).
+func TestParseDispositionHonoursCommentAndNull(t *testing.T) {
+	const id = "dsp-2"
+	for _, tc := range []struct {
+		name       string
+		line       string
+		state      string
+		supersedes string
+		exit       string
+	}{
+		{"comment after state", "state: held  # waiting on the rethink", "held", "", ""},
+		{"comment after a supersession", "supersedes_disposition: dsp-1 # replaces the first", "", "dsp-1", ""},
+		{"comment after a quoted state", `state: "accepted" # ok`, "accepted", "", ""},
+		{"bare null exit condition", "exit_condition: null", "", "", ""},
+		{"tilde exit condition with comment", "exit_condition: ~ # none yet", "", "", ""},
+		{"NULL exit condition", "exit_condition: NULL", "", "", ""},
+		{"quoted null is a string", `exit_condition: "null"`, "", "", "null"},
+		{"a hash with no space before it is content", "exit_condition: issue#4", "", "", "issue#4"},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			rec := ParseDisposition(id, "---\n"+tc.line+"\n---\n")
+			if !rec.WellFormed {
+				t.Fatalf("%q read as not well-formed", tc.line)
+			}
+			if rec.State != tc.state || rec.Supersedes != tc.supersedes || rec.ExitCondition != tc.exit {
+				t.Errorf("%q read as state=%q supersedes=%q exit=%q; want state=%q supersedes=%q exit=%q",
+					tc.line, rec.State, rec.Supersedes, rec.ExitCondition, tc.state, tc.supersedes, tc.exit)
+			}
+		})
+	}
+}
diff --git a/internal/core/issueschema/issueschema.go b/internal/core/issueschema/issueschema.go
index 56afad29b..b6ee2f1b1 100644
--- a/internal/core/issueschema/issueschema.go
+++ b/internal/core/issueschema/issueschema.go
@@ -69,6 +69,12 @@ var Known = map[string]bool{
 	"related_specs": true, "related_issues": true,
 	"synthesis_clusters": true, "wontfix_reason": true, "resolution": true,
 	"resolved_by": true, "blocked_by": true,
+	// duplicates and refines are the typed links the filing-time match writes
+	// (itd-2609212137116617): each an id list naming the issue or intent this
+	// record is a near-identical double of, or a narrower case of. Optional, and
+	// removable by hand — a record without either is ordinary — but KNOWN, or
+	// the reader would drop every linked record as malformed.
+	"duplicates": true, "refines": true,
 	// shipped_in names the release that already carried this record's work, so the
 	// derivation can leave it out of a later cut (iss-2608241612087533). Optional
 	// and rare — only a ledger-hygiene close, for a fix released long ago, has
diff --git a/internal/core/lint/guardedread_test.go b/internal/core/lint/guardedread_test.go
index 990bf749a..a06148b3d 100644
--- a/internal/core/lint/guardedread_test.go
+++ b/internal/core/lint/guardedread_test.go
@@ -45,9 +45,12 @@ func TestReadRepoFile(t *testing.T) {
 // new rule that reaches for os.ReadFile is refused here rather than found by the
 // next sweep. The check parses the source rather than matching text, so a read
 // spelled through an import alias, a dot import, fs.ReadFile over os.DirFS, or a
-// method on a handle (an os.Root's Open, an fs.FS's ReadFile) is caught too. What
-// it cannot see is a raw read done inside a callee package; the guard is this
-// package's own source.
+// method on a handle (an os.Root's Open, an fs.FS's ReadFile) is caught too, and
+// so is a file's content read out of git through the unbounded gitutil.Run (a
+// `cat-file blob` or a `show`), which reads a committed record whole as surely as
+// os.ReadFile reads a working-tree one (iss-2609261726015043); the bounded
+// gitutil.RunCapped and RunCappedBytes pass. What it cannot see is a raw read
+// done inside a callee package; the guard is this package's own source.
 func TestLintReadsNothingUnguarded(t *testing.T) {
 	entries, err := os.ReadDir(".")
 	if err != nil {
@@ -67,7 +70,7 @@ func TestLintReadsNothingUnguarded(t *testing.T) {
 			t.Fatal(err)
 		}
 		for _, h := range hits {
-			t.Errorf("%s reads without the guard (use readRepoFile, readRepoAbs, readRepoLeaf or an fsutil guarded read)", h)
+			t.Errorf("%s reads without the guard (use readRepoFile, readRepoAbs, readRepoLeaf or an fsutil guarded read; out of git, gitutil.RunCapped)", h)
 		}
 	}
 }
@@ -84,6 +87,7 @@ import (
 	. "os"
 
 	"github.com/intentdriven/abcd/internal/fsutil"
+	"github.com/intentdriven/abcd/internal/gitutil"
 )
 
 func planted(root *sys.Root, fsys fs.FS) {
@@ -96,6 +100,8 @@ func planted(root *sys.Root, fsys fs.FS) {
 	ioutil.ReadFile("g")
 	ReadFile("h")
 	sys.OpenInRoot(".", "i")
+	gitutil.Run(".", "cat-file", "blob", "HEAD:j")
+	gitutil.Run(".", "show", "HEAD:k")
 }
 
 func guarded(root *sys.Root) {
@@ -104,6 +110,9 @@ func guarded(root *sys.Root) {
 	sys.OpenRoot(".")
 	sys.ReadDir(".")
 	sys.Lstat("c")
+	gitutil.RunCapped(".", 1, "cat-file", "blob", "HEAD:d")
+	gitutil.Run(".", "cat-file", "-e", "HEAD:e")
+	gitutil.Run(".", "rev-parse", "HEAD")
 }
 `
 	hits, err := unguardedReads("planted.go", []byte(src))
@@ -111,10 +120,11 @@ func guarded(root *sys.Root) {
 		t.Fatal(err)
 	}
 	want := []string{
-		"planted.go:13 sys.ReadFile", "planted.go:14 sys.OpenFile", "planted.go:15 fs.ReadFile",
-		"planted.go:15 sys.DirFS", "planted.go:16 root.Open", "planted.go:17 root.ReadFile",
-		"planted.go:18 fsys.Open", "planted.go:19 ioutil.ReadFile", "planted.go:20 ReadFile",
-		"planted.go:21 sys.OpenInRoot",
+		"planted.go:14 sys.ReadFile", "planted.go:15 sys.OpenFile", "planted.go:16 fs.ReadFile",
+		"planted.go:16 sys.DirFS", "planted.go:17 root.Open", "planted.go:18 root.ReadFile",
+		"planted.go:19 fsys.Open", "planted.go:20 ioutil.ReadFile", "planted.go:21 ReadFile",
+		"planted.go:22 sys.OpenInRoot", "planted.go:23 gitutil.Run cat-file blob",
+		"planted.go:24 gitutil.Run show",
 	}
 	if strings.Join(hits, "\n") != strings.Join(want, "\n") {
 		t.Errorf("got:\n%s\nwant:\n%s", strings.Join(hits, "\n"), strings.Join(want, "\n"))
@@ -138,6 +148,9 @@ func unguardedReads(name string, src []byte) ([]string, error) {
 	// Any other receiver: a method with a reading name on a handle (an os.Root, an
 	// fs.FS, an *os.File's directory) is a read the guard never saw.
 	methods := map[string]bool{"Open": true, "OpenFile": true, "ReadFile": true}
+	// gitutil.Run returns git's whole output: asked for a file's content at a
+	// revision (`cat-file blob`, `show`), it is a read with no bound.
+	const gitutilPath = "github.com/intentdriven/abcd/internal/gitutil"
 
 	pkgOf := map[string]string{} // local name -> import path, for every import
 	dot := map[string]bool{}     // import paths imported with "."
@@ -176,6 +189,11 @@ func unguardedReads(name string, src []byte) ([]string, error) {
 					if banned[path][fn.Sel.Name] {
 						hit(call.Pos(), x.Name+"."+fn.Sel.Name)
 					}
+					if path == gitutilPath && fn.Sel.Name == "Run" {
+						if read := gitContentRead(call.Args); read != "" {
+							hit(call.Pos(), x.Name+".Run "+read)
+						}
+					}
 					return true
 				}
 			}
@@ -197,3 +215,25 @@ func unguardedReads(name string, src []byte) ([]string, error) {
 	})
 	return hits, nil
 }
+
+// gitContentRead names the file-content read a git invocation's literal
+// arguments ask for — "cat-file blob" or "show" — or "" when they ask for none.
+func gitContentRead(args []ast.Expr) string {
+	var lits []string
+	for _, a := range args {
+		if b, ok := a.(*ast.BasicLit); ok && b.Kind == token.STRING {
+			if v, err := strconv.Unquote(b.Value); err == nil {
+				lits = append(lits, v)
+			}
+		}
+	}
+	for i, v := range lits {
+		switch {
+		case v == "show":
+			return "show"
+		case v == "cat-file" && i+1 < len(lits) && lits[i+1] == "blob":
+			return "cat-file blob"
+		}
+	}
+	return ""
+}
diff --git a/internal/core/lint/matchlinks_test.go b/internal/core/lint/matchlinks_test.go
new file mode 100644
index 000000000..4ef6eba60
--- /dev/null
+++ b/internal/core/lint/matchlinks_test.go
@@ -0,0 +1,27 @@
+package lint
+
+import (
+	"path/filepath"
+	"testing"
+)
+
+// The filing-time match's typed links (itd-2609212137116617) are claims that
+// another record exists, like every other cross-reference: a `duplicates:` or
+// `refines:` naming a record the corpus does not hold is a finding, and one
+// naming a present issue or intent is silent.
+func TestRecordSchemaResolvesMatchLinks(t *testing.T) {
+	root := t.TempDir()
+	writeFile(t, root, "rec/intents/drafts/itd-17-present.md", "---\nid: itd-17\nkind: null\nspec_id: null\n---\n# present\n")
+	writeFile(t, root, "rec/intents/drafts/itd-18-linked.md",
+		"---\nid: itd-18\nkind: null\nspec_id: null\nduplicates: [itd-17]\nrefines: [itd-99]\n---\n# linked\n")
+	fs, err := Lint(schemaConfig(), root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if n := countRule(fs, ruleRecordSchema); n != 1 {
+		t.Fatalf("want exactly the one phantom refines target, got %d: %+v", n, fs)
+	}
+	if !findingWith(fs, filepath.Join("rec/intents/drafts", "itd-18-linked.md"), ruleRecordSchema, "refines names 'itd-99'") {
+		t.Fatalf("no finding naming the phantom refines target: %+v", fs)
+	}
+}
diff --git a/internal/core/lint/provenance.go b/internal/core/lint/provenance.go
index 4456cb07c..2f4c0fa19 100644
--- a/internal/core/lint/provenance.go
+++ b/internal/core/lint/provenance.go
@@ -318,7 +318,7 @@ func containsID(list []string, id string) bool {
 }
 
 // provenanceValue reads one frontmatter scalar as the record's readers see it:
-// the same-line value, quotes stripped, an explicit YAML null read as ABSENT.
+// the same-line value, quotes stripped, an explicit (bare) YAML null read as ABSENT.
 //
 // Null-is-absent matches how every other gate in this package reads a record's
 // scalars, and it is the right reading here too: `origin: null` says the record
@@ -328,9 +328,12 @@ func provenanceValue(r schemaRecord, key string) (value string, line int, presen
 	if !ok {
 		return "", 0, false
 	}
-	v := strings.Trim(strings.TrimSpace(f.value), `"'`)
-	if frontmatter.IsNull(v) {
+	// Null is asked of the RAW scalar, before the quotes go: quoting is what
+	// makes "null" a string, and stripping first read `origin: "null"` as an
+	// absent origin (iss-2608241347321759).
+	raw := strings.TrimSpace(f.value)
+	if frontmatter.IsNull(raw) {
 		return "", f.line, false
 	}
-	return v, f.line, true
+	return strings.Trim(raw, `"'`), f.line, true
 }
diff --git a/internal/core/lint/readerskips_test.go b/internal/core/lint/readerskips_test.go
new file mode 100644
index 000000000..39c98c452
--- /dev/null
+++ b/internal/core/lint/readerskips_test.go
@@ -0,0 +1,59 @@
+package lint
+
+import (
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// withField returns a valid issue record carrying one extra frontmatter line.
+func withField(id, slug, line string) string {
+	return strings.Replace(validIssue(id, slug), "\nseverity:", "\n"+line+"\nseverity:", 1)
+}
+
+// readerParityPhrase opens the reader-parity leg's finding (checkIssueReaderParity).
+const readerParityPhrase = "capture's ledger reader refuses this record"
+
+// TestRecordSchemaReportsEveryRecordTheLedgerReaderSkips (iss-2609261631132673):
+// a committed issue the ledger reader skips is one every capture surface leaves
+// out, so record_schema reports it, in the reader's own words. The reasons
+// below were silent here while `abcd <id>` named them: a malformed item in an
+// id list, and a list naming one record twice. The finding carries the
+// reader's message rather than a lint-side restatement, because the verdict
+// comes from the reader itself (the reader-parity leg, asked of the one
+// judgement core/issuerecord holds) — a well-formed record stays silent.
+func TestRecordSchemaReportsEveryRecordTheLedgerReaderSkips(t *testing.T) {
+	root := t.TempDir()
+	writeFile(t, root, "rec/README.md", "# record\n")
+	open := "work/issues/open"
+	writeFile(t, root, open+"/iss-1-fine.md", validIssue("iss-1", "fine"))
+	cases := []struct {
+		name, content, reason string
+	}{
+		{"iss-2-dup.md", withField("iss-2", "dup", "duplicates: [bogus]"),
+			`malformed frontmatter: "duplicates" item "bogus" does not match iss-N or itd-N`},
+		{"iss-3-blocked.md", withField("iss-3", "blocked", "blocked_by: [bogus]"),
+			`malformed frontmatter: "blocked_by" item "bogus" does not match iss-N`},
+		{"iss-4-twice.md", withField("iss-4", "twice", "related_issues: [iss-1, iss-1]"),
+			"invariant violation: related_issues contains duplicate items"},
+	}
+	for _, c := range cases {
+		writeFile(t, root, open+"/"+c.name, c.content)
+	}
+	fs, err := Lint(schemaConfig(), root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, c := range cases {
+		file := filepath.Join(open, c.name)
+		if !findingWith(fs, file, ruleRecordSchema, readerParityPhrase) ||
+			!findingWith(fs, file, ruleRecordSchema, c.reason) {
+			t.Errorf("%s: no record_schema finding in the reader's words %q: %+v", c.name, c.reason, fs)
+		}
+	}
+	for _, f := range fs {
+		if f.File == filepath.Join(open, "iss-1-fine.md") {
+			t.Errorf("a record the reader takes was reported: %+v", f)
+		}
+	}
+}
diff --git a/internal/core/lint/releasegate_derive.go b/internal/core/lint/releasegate_derive.go
index dd1e588c3..44024f5a6 100644
--- a/internal/core/lint/releasegate_derive.go
+++ b/internal/core/lint/releasegate_derive.go
@@ -229,12 +229,15 @@ func candidateVersionAt(root, rev string) (string, error) {
 }
 
 // changelogAt reads CHANGELOG.md out of rev's tree. present=false means rev
-// carries no such file; an unreadable blob is an error.
+// carries no such file; an unreadable blob is an error, and so is one past
+// maxChangelogBytes, the cap every other CHANGELOG read holds to: the blob is
+// never held whole in memory, and a truncated one is never parsed as if it were
+// the file (iss-2609261726015043).
 func changelogAt(root, rev string) (string, bool, error) {
 	if _, err := gitutil.Run(root, "cat-file", "-e", rev+":CHANGELOG.md"); err != nil {
 		return "", false, nil
 	}
-	blob, err := gitutil.Run(root, "cat-file", "blob", rev+":CHANGELOG.md")
+	blob, err := gitutil.RunCapped(root, maxChangelogBytes, "cat-file", "blob", rev+":CHANGELOG.md")
 	if err != nil {
 		return "", false, fmt.Errorf("release-gate: reading CHANGELOG.md at %s: %w", rev, err)
 	}
diff --git a/internal/core/lint/releasegate_derive_test.go b/internal/core/lint/releasegate_derive_test.go
index 882b34d99..b03aa5e43 100644
--- a/internal/core/lint/releasegate_derive_test.go
+++ b/internal/core/lint/releasegate_derive_test.go
@@ -392,3 +392,22 @@ func TestReleasedVersion_ReadsTheStrictHead(t *testing.T) {
 		})
 	}
 }
+
+// TestReleasedVersion_RefusesAnOversizedChangelog (iss-2609261726015043): the
+// release-gate derivation reads CHANGELOG.md out of a git tree, and that read is
+// bounded like every other CHANGELOG read (4 MiB): a blob past the cap is
+// refused, fail-closed, rather than held whole in memory and parsed.
+func TestReleasedVersion_RefusesAnOversizedChangelog(t *testing.T) {
+	r := gittest.NewRepo(t)
+	head := "## [Unreleased]\n\n## [1.0.0] - 2026-01-01\n\n"
+	filler := strings.Repeat("- an entry that pads the release notes past the cap\n", (4<<20)/50+1)
+	r.Write("CHANGELOG.md", head+filler)
+	r.Commit("an oversized released tree")
+	got, err := lint.ReleasedVersion(r.Root(), r.Git("rev-parse", "HEAD"))
+	if err == nil {
+		t.Fatalf("read %q out of a CHANGELOG.md past the 4 MiB cap; must refuse", got)
+	}
+	if !strings.Contains(err.Error(), "cap") {
+		t.Errorf("error = %q, want it to name the cap", err)
+	}
+}
diff --git a/internal/core/lint/releasegate_manifest_currency_test.go b/internal/core/lint/releasegate_manifest_currency_test.go
index c7d9e8251..107d8a321 100644
--- a/internal/core/lint/releasegate_manifest_currency_test.go
+++ b/internal/core/lint/releasegate_manifest_currency_test.go
@@ -12,10 +12,11 @@ import (
 	"testing"
 )
 
-// The release-gate manifest is the reproducibility anchor for the iss-35
-// brief<->surface crosscheck: a receipt echoes its sha256 as manifestHash and
-// receipt_gate refuses a mismatch. Pinning the inputs makes two runs comparable
-// to each other; it does not make them comparable to the tree, and twice the
+// The release-gate manifest pins the inputs of the iss-35 brief<->surface
+// crosscheck: a receipt echoes its sha256 as manifestHash and receipt_gate
+// refuses a mismatch. Pinning the inputs makes two runs comparable in scope to
+// each other (never in findings, which LLM checkers do not reproduce —
+// iss-2608231409595789); it does not make them comparable to the tree, and twice the
 // pinned inputs were found describing a surface that had moved on
 // (iss-387: five shipped chapters unpinned; iss-2609011423385217: the pinned
 // context naming 10 of 22 command pages and no agents, the scope omitting the
diff --git a/internal/core/lint/schema.go b/internal/core/lint/schema.go
index faab8c332..f81c6db5a 100644
--- a/internal/core/lint/schema.go
+++ b/internal/core/lint/schema.go
@@ -34,6 +34,7 @@ import (
 	"strings"
 
 	"github.com/intentdriven/abcd/internal/core/frontmatter"
+	"github.com/intentdriven/abcd/internal/core/grounds"
 	"github.com/intentdriven/abcd/internal/core/issueschema"
 	"github.com/intentdriven/abcd/internal/core/mdrecord"
 	"github.com/intentdriven/abcd/internal/core/recordid"
@@ -127,7 +128,9 @@ var (
 	// pruned id, so it can never fail its own resolution check; listing it would
 	// read as coverage it does not provide. Its targets are checked separately,
 	// against the store's allocation high-water mark.
-	recordRefFields = []string{"related_adrs", "related_intents", "builds_on", "blocked_by"}
+	// `duplicates` and `refines` are the typed links the filing-time match
+	// writes (itd-2609212137116617), each naming an issue or an intent.
+	recordRefFields = []string{"related_adrs", "related_intents", "builds_on", "blocked_by", "duplicates", "refines"}
 	// Every field the rule reads handles out of, so the scan parses each once.
 	recordHandleFields = append([]string{"supersedes", "superseded_by"}, recordRefFields...)
 	// recordGraphFields are cross-reference fields the record carries that this
@@ -227,7 +230,7 @@ type recordStore struct {
 	// readerRefusesDuplicateKey declares that the store's reader refuses a record
 	// carrying a top-level key twice, and skips it. It is separate from
 	// readerFailsClosed because the two answers come apart: capture's
-	// parseFrontmatterBlock refuses a duplicate key by name, and the ADR dispatcher
+	// issuerecord.ParseBlock refuses a duplicate key by name, and the ADR dispatcher
 	// — which DOES validate the id before it renders — reads the frontmatter with
 	// the lenient scanner and so never sees the second line at all. An ADR carrying
 	// `status` twice renders, with the first value and a nil error
@@ -522,6 +525,10 @@ type schemaRecord struct {
 	// which hands it to the ledger reader itself rather than re-deriving its
 	// grammar.
 	content string
+	// malformedGrounds are the bullets under the record's `## Grounds` heading
+	// that core/grounds's reader skips, read once at scan time from the bytes the
+	// scan already holds (iss-2608301747001641).
+	malformedGrounds []grounds.Malformed
 }
 
 // scalar decodes a frontmatter value the way this record's own reader does. The
@@ -694,6 +701,7 @@ func checkRecordSchema(repoRoot string, cfg RuleConfig) ([]Finding, error) {
 			out = append(out, checkIssueReaderParity(r, cfg.Severity)...)
 		}
 		out = append(out, checkIssueBodyRenders(r, cfg.Severity)...)
+		out = append(out, checkRecordGroundsBullets(r, cfg.Severity)...)
 
 		// Cross-references: a named record must be in the corpus, or declared
 		// retired by the record that replaced it.
@@ -1347,6 +1355,43 @@ func checkRecordBucketField(r schemaRecord, severity string) []Finding {
 	}}
 }
 
+// groundsStores are the stores whose records carry a `## Grounds` section: the
+// issue record at its triage routes and the intent record at its readiness gate,
+// both written through core/grounds.
+var groundsStores = map[string]bool{"iss": true, "itd": true}
+
+// checkRecordGroundsBullets reports every bullet under a record's `## Grounds`
+// heading that the reader skips (iss-2608301747001641).
+//
+// A malformed `grounds:` frontmatter value was a value this rule could judge. The
+// section form lost that: the reader takes the bullets that parse and reads the
+// rest as prose, so a hand-typed `- rejected: …` is not an entry to any surface
+// and nothing says so. Which bullets were skipped is core/grounds's answer, from
+// the same walk its reader takes, so this rule can report neither a bullet the
+// reader counts nor miss one it drops. The grammar alone is judged — token,
+// colon, text — and not the substance floor, because the ledger's reader does not
+// apply the floor either and a wontfix stamps its entry from a reason the floor
+// never governed. A paragraph of prose under the heading is not a bullet and is
+// not judged.
+//
+// The verbs never write such a bullet, so this stops no triage; it reports a
+// hand edit the reader would silently drop.
+func checkRecordGroundsBullets(r schemaRecord, severity string) []Finding {
+	if !groundsStores[r.store.prefix] {
+		return nil
+	}
+	var out []Finding
+	for _, m := range r.malformedGrounds {
+		out = append(out, Finding{
+			File: r.rel, Line: m.Line, RuleID: ruleRecordSchema, Severity: severity,
+			Message: "a bullet under `## " + grounds.Heading + "` does not parse (" + m.Err.Error() +
+				"), so the reader drops it and it is no recorded ground to any surface; write it as `- " +
+				grounds.UsageSpelling() + ": <text>`, or make it a prose paragraph if it is not an entry",
+		})
+	}
+	return out
+}
+
 // checkIssueRecordShape mirrors capture's validateStrict shape checks for the
 // ISSUE store: enum membership (severity/category/source) and the kebab-slug
 // check. The third of them, the additionalProperties:false unknown-key check, is
@@ -1763,6 +1808,8 @@ func scanRecordStores(repoRoot string, cfg RuleConfig) ([]schemaRecord, []Findin
 					refs:    recordRefsOf(lines, fields),
 					blocks:  frontmatterBlocksOf(lines, fields),
 					content: string(content),
+
+					malformedGrounds: grounds.MalformedIn(string(content)),
 				})
 			}
 			return nil
diff --git a/internal/core/lint/schema_parity_test.go b/internal/core/lint/schema_parity_test.go
index 71673d066..eb5778ff6 100644
--- a/internal/core/lint/schema_parity_test.go
+++ b/internal/core/lint/schema_parity_test.go
@@ -371,3 +371,46 @@ func TestRecordSchemaSilentOnAGroundsSection(t *testing.T) {
 		t.Fatalf("a record carrying its grounds in the body raised %d record_schema finding(s): %+v", n, fs)
 	}
 }
+
+// TestRecordSchemaReportsAMalformedGroundsBullet is the coverage the frontmatter
+// rule had and the section form lost (iss-2608301747001641). A malformed
+// `grounds:` value was a value the gate could judge; a malformed bullet under
+// `## Grounds` reads as prose, so the reader drops it and nothing says so. The
+// gate asks core/grounds's own reader which bullets it skipped — one derivation,
+// so a bullet the reader takes is never reported and one it drops always is.
+// Prose paragraphs under the heading, and a bullet a fence masks, stay silent:
+// the reader never offered them as entries.
+func TestRecordSchemaReportsAMalformedGroundsBullet(t *testing.T) {
+	const issues = "work/issues"
+	root := t.TempDir()
+	seedRecRoot(t, root)
+	writeFile(t, root, issues+"/resolved/iss-1-ok.md",
+		resolvedIssue("iss-1", "ok", "")+
+			"\n## Grounds\n\n"+
+			"- pursued: we expect the recorded reasoning to outlive the session\n"+
+			"- rejected: refusing the whole file, which would take every other domain down\n"+
+			"\nA paragraph of prose under the heading is not an entry and is not judged.\n\n"+
+			"```\n- planned: inside a fence, masked from every reader\n```\n")
+	writeFile(t, root, "rec/intents/drafts/itd-1-draft.md",
+		"---\nid: itd-1\nkind: null\nspec_id: null\n---\n# draft\n\n## Grounds\n\n- pursued without a colon at all\n")
+
+	fs, err := Lint(schemaConfig(), root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if n := countRule(fs, ruleRecordSchema); n != 2 {
+		t.Fatalf("want one record_schema finding per malformed bullet (2), got %d: %+v", n, fs)
+	}
+	iss := filepath.Join(issues, "resolved", "iss-1-ok.md")
+	if !findingWith(fs, iss, ruleRecordSchema, "rejected") {
+		t.Errorf("the issue record's out-of-vocabulary bullet is not reported: %+v", fs)
+	}
+	for _, f := range fs {
+		if f.File == iss && f.RuleID == ruleRecordSchema && f.Line != 18 {
+			t.Errorf("the finding names line %d; the bullet is file line 18: %+v", f.Line, f)
+		}
+	}
+	if !findingWith(fs, filepath.Join("rec/intents/drafts", "itd-1-draft.md"), ruleRecordSchema, "pursued without a colon") {
+		t.Errorf("the intent record's colon-less bullet is not reported: %+v", fs)
+	}
+}
diff --git a/internal/core/lint/schema_test.go b/internal/core/lint/schema_test.go
index b6e00184e..012fbf449 100644
--- a/internal/core/lint/schema_test.go
+++ b/internal/core/lint/schema_test.go
@@ -2394,6 +2394,29 @@ func TestRecordProvenanceOutOfVocabulary(t *testing.T) {
 	}
 }
 
+// TestRecordProvenanceQuotedNullIsAValue: quoting is what makes "null" a string
+// rather than a null, so frontmatter.IsNull is asked of the RAW scalar. The rule
+// stripped the quotes first and read `origin: "null"` as an ABSENT origin, which
+// sent the author to a lone-key finding about a key the record carries; the value
+// is an origin no writer produces, and that is what the finding says
+// (iss-2608241347321759).
+func TestRecordProvenanceQuotedNullIsAValue(t *testing.T) {
+	root := t.TempDir()
+	writeFile(t, root, "rec/intents/drafts/itd-1-quoted-null.md",
+		"---\nid: itd-1\nkind: null\nspec_id: null\norigin: \"null\" # hand typed\nproduction_mode: hand-written\n---\n# draft\n")
+	fs, err := Lint(provenanceConfig(), root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	rel := filepath.Join("rec/intents/drafts", "itd-1-quoted-null.md")
+	if findingWith(fs, rel, ruleRecordProvenance, "with no `origin`") {
+		t.Errorf("a quoted \"null\" origin read as absent: %+v", fs)
+	}
+	if !findingWith(fs, rel, ruleRecordProvenance, "null") || countRule(fs, ruleRecordProvenance) != 1 {
+		t.Errorf("expected one finding refusing the origin value \"null\": %+v", fs)
+	}
+}
+
 // TestRecordProvenanceExtractedWithoutRelatedIssues: promote writes the back-edge
 // and the origin in one act, so the origin without the back-edge is a record no
 // promote could have produced.
diff --git a/internal/core/mdrecord/fence_canonical_test.go b/internal/core/mdrecord/fence_canonical_test.go
index 74e650f83..98f7cb6f7 100644
--- a/internal/core/mdrecord/fence_canonical_test.go
+++ b/internal/core/mdrecord/fence_canonical_test.go
@@ -36,9 +36,9 @@ var fenceWriters = map[string]fenceWriter{
 	"internal/core/history/reconstruct_render.go":   {1, "a WRITER: writeFenced opens a fence longer than any backtick run in the body, the floor of three; it reads no fences"},
 	"internal/core/lifeboat/sources_conventions.go": {3, "judges one line or the whole text: a README prose measure skips a delimiter line, and a presence test asks whether any fence exists; neither tracks which lines a fence covers"},
 	"internal/core/reading/project.go":              {2, "fenceDelimiterRe judges one frontmatter line and refuses it; which lines a fence covers is floorFences, which reads mdrecord"},
+	"internal/core/mdrender/render.go":              {10, "the site renderer: it renders a block Blocks already cut by mdrecord's reading, refuses a fence form it does not render (tilde, four or more backticks), a list line that opens a fence and an indented code block; it keeps no fence state of its own"},
 	"internal/core/release/page.go":                 {2, "a presence test: a headline carrying any delimiter is refused; it tracks nothing"},
 	"internal/core/site/compose.go":                 {1, "judges one block the site's Blocks already cut by mdrecord's reading: does it open with a fence"},
-	"internal/core/site/markdown.go":                {10, "the site renderer: it renders a block Blocks already cut by mdrecord's reading, refuses a fence form it does not render (tilde, four or more backticks), a list line that opens a fence and an indented code block; it keeps no fence state of its own"},
 	"internal/surface/cli/history_reconstruct.go":   {2, "a WRITER: the telemetry block is emitted inside one json fence; it reads no fences"},
 	"internal/surface/cli/reference.go":             {4, "a WRITER: the reference page emits its flag and example blocks as fences; it reads no fences"},
 }
diff --git a/internal/core/mdrender/blocks.go b/internal/core/mdrender/blocks.go
new file mode 100644
index 000000000..05c60cffa
--- /dev/null
+++ b/internal/core/mdrender/blocks.go
@@ -0,0 +1,73 @@
+package mdrender
+
+import (
+	"regexp"
+	"strings"
+
+	"github.com/intentdriven/abcd/internal/core/mdrecord"
+)
+
+// HeadingRe matches an ATX heading at column 0, capturing its marker run and
+// its title. The site's section walk and this renderer's heading block read one
+// pattern, so what the walk splits on is what the renderer renders.
+var HeadingRe = regexp.MustCompile(`^(#{1,6})\s+(.*)$`)
+
+// Block is one top-level markdown block: a paragraph, a table, a fence, an
+// image line, a list, or a blockquote — whatever sits between two blank lines.
+type Block struct {
+	Text string
+	// Line is the 1-based source line the block starts at.
+	Line int
+}
+
+// Blocks splits a section body into its top-level blocks, honouring fenced code
+// by mdrecord's ListNested rule, the same reading Sections takes.
+// start is the 1-based source line the body begins at.
+func Blocks(md string, start int) []Block {
+	if md == "" {
+		return nil
+	}
+	lines := strings.Split(md, "\n")
+	fences := mdrecord.Read(lines, mdrecord.ListNested).Fences
+	var out []Block
+	var buf []string
+	bufLine := 0
+	flush := func() {
+		if len(buf) > 0 {
+			out = append(out, Block{Text: strings.Join(buf, "\n"), Line: bufLine})
+			buf = nil
+		}
+	}
+	for i := 0; i < len(lines); i++ {
+		if len(fences) > 0 && i == fences[0].Start {
+			f := fences[0]
+			fences = fences[1:]
+			if len(buf) == 0 {
+				bufLine = start + i
+			}
+			buf = append(buf, lines[f.Start:f.End]...)
+			i = f.End - 1
+			// A fence closed at the left margin closes its own block. An
+			// INDENTED one belongs to whatever list item holds it, so the block
+			// runs on: the item's renderer dedents it and reads it as a fence
+			// there. Ending the block here instead would leave the fence's blank
+			// lines to split the code into paragraphs, and its `#` lines to be
+			// read as headings — which is a document silently losing sections.
+			if f.Closed && f.End-1 > f.Start && IndentOf(lines[f.End-1]) == 0 {
+				flush()
+			}
+			continue
+		}
+		line := lines[i]
+		if strings.TrimSpace(line) == "" {
+			flush()
+			continue
+		}
+		if len(buf) == 0 {
+			bufLine = start + i
+		}
+		buf = append(buf, line)
+	}
+	flush()
+	return out
+}
diff --git a/internal/core/mdrender/doc.go b/internal/core/mdrender/doc.go
new file mode 100644
index 000000000..b12f401cf
--- /dev/null
+++ b/internal/core/mdrender/doc.go
@@ -0,0 +1,12 @@
+// Package mdrender is the Markdown subset renderer the site publishes the
+// repository's prose through, and the one answer to what that subset refuses.
+//
+// It is a leaf — it imports only core/mdrecord, for the fence reading its block
+// walk shares with every other record reader — because two kinds of caller need
+// it. The site (core/site) renders every page through it. And the writers of
+// append-only record prose ask it, before they write, whether the site will
+// render what they are about to write: core/site imports the record families
+// that hold such prose, so they could not import it back, and a second copy of
+// the renderer's rules in each writer is a copy that drifts from the renderer
+// (iss-2608301646046226). RefusalIn is that question.
+package mdrender
diff --git a/internal/core/mdrender/render.go b/internal/core/mdrender/render.go
new file mode 100644
index 000000000..7b0e7ba3d
--- /dev/null
+++ b/internal/core/mdrender/render.go
@@ -0,0 +1,1153 @@
+package mdrender
+
+// The Markdown subset renderer.
+//
+// The site renders repository prose, and the repository writes a small, stable
+// dialect: ATX headings, paragraphs, bold/italic/code spans, links, images,
+// fenced code, pipe tables, blockquotes and lists. That dialect is what this
+// renders, and everything else is a BUILD ERROR naming file and line.
+//
+// Refusing is the point. A renderer that passes an unknown construct through
+// unrendered publishes raw markdown to readers; a renderer that silently drops
+// it publishes a hole. Both are worse than a build that stops and says
+// "docs/explanation/roles.md:31 — reference link", because the fix for that is
+// one edit and the fix for a silent hole is noticing it exists.
+
+import (
+	"errors"
+	"fmt"
+	"regexp"
+	"strings"
+)
+
+// UnsupportedError is a markdown construct outside the rendered subset.
+type UnsupportedError struct {
+	Path      string
+	Line      int
+	Construct string
+	Detail    string
+}
+
+func (e *UnsupportedError) Error() string {
+	d := ""
+	if e.Detail != "" {
+		d = ": " + e.Detail
+	}
+	return fmt.Sprintf("%s:%d: unsupported markdown construct: %s%s — the site renders a fixed subset and never passes text through unrendered",
+		e.Path, e.Line, e.Construct, d)
+}
+
+var (
+	tableDelimRe   = regexp.MustCompile(`^\s*\|?\s*:?-{1,}:?\s*(\|\s*:?-{1,}:?\s*)*\|?\s*$`)
+	OrderedItemRe  = regexp.MustCompile(`^(\d+)[.)]\s+(.*)$`)
+	setextRe       = regexp.MustCompile(`^\s{0,3}(=+|-{2,})\s*$`)
+	thematicRe     = regexp.MustCompile(`^\s{0,3}((\*\s*){3,}|(-\s*){3,}|(_\s*){3,})$`)
+	rawHTMLStartRe = regexp.MustCompile(`^\s*<[A-Za-z!/]`)
+	linkDefRe      = regexp.MustCompile(`^\s{0,3}\[([^\]]+)\]:\s*(\S+)\s*(".*"|'.*'|\(.*\))?\s*$`)
+	autolinkRe     = regexp.MustCompile(`^<([A-Za-z][A-Za-z0-9+.\-]{1,31}:[^<>\x00-\x20]*)>`)
+	emailAutoRe    = regexp.MustCompile(`^<([A-Za-z0-9.!#$%&'*+/=?^_` + "`" + `{|}~-]+@[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?(?:\.[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?)*)>`)
+	htmlTagRe      = regexp.MustCompile(`^</?([A-Za-z][A-Za-z0-9-]*)`)
+)
+
+// htmlElements is the set of names a `<…>` may carry and still be HTML.
+//
+// The distinction matters because the record writes angle brackets for two
+// different things. `<div>` is markup, and rendering it would let a record file
+// inject elements into a published page — that stays a refusal. `<ts>`,
+// `<file>` and `<number>` are PLACEHOLDERS in prose, and every generic HTML
+// sanitiser drops them silently, which is the one outcome worse than either
+// rendering or refusing: the sentence loses a word and nobody can tell. Those
+// are escaped and shown, so what the record wrote is what a reader sees.
+var htmlElements = map[string]bool{}
+
+func init() {
+	for _, n := range strings.Fields(`a abbr address area article aside audio b base bdi bdo blockquote body br
+button canvas caption cite code col colgroup data datalist dd del details dfn dialog div dl dt em embed
+fieldset figcaption figure footer form h1 h2 h3 h4 h5 h6 head header hgroup hr html i iframe img input ins
+kbd label legend li link main map mark menu meta meter nav noscript object ol optgroup option output p
+picture pre progress q rp rt ruby s samp script search section select slot small source span strong style
+sub summary sup table tbody td template textarea tfoot th thead time title tr track u ul var video wbr`) {
+		htmlElements[n] = true
+	}
+}
+
+// LinkDefinitions collects a document's link reference definitions — the
+// `[label]: destination "title"` lines the record's older entries keep at the
+// foot of a file and name from the prose above.
+//
+// They are document-level, and the renderer works a block at a time, so the
+// caller reads them once and hands them to the Renderer. A reference whose
+// definition is missing stays a refusal: the destination is lost either way,
+// and losing it silently is how a dead cross-reference survives review.
+func LinkDefinitions(md string) map[string]string {
+	defs := map[string]string{}
+	for _, line := range strings.Split(md, "\n") {
+		m := linkDefRe.FindStringSubmatch(line)
+		if m == nil {
+			continue
+		}
+		key := normaliseLabel(m[1])
+		if _, seen := defs[key]; !seen {
+			defs[key] = strings.Trim(m[2], "<>")
+		}
+	}
+	return defs
+}
+
+// normaliseLabel folds a reference label the way every reader folds it: case
+// insensitively, with internal whitespace collapsed.
+func normaliseLabel(s string) string {
+	return strings.ToLower(strings.Join(strings.Fields(s), " "))
+}
+
+// isLinkDefLine reports whether a line is nothing but a link reference
+// definition. A block made only of them renders as nothing, which is what it
+// means everywhere else.
+func isLinkDefLine(s string) bool { return linkDefRe.MatchString(s) }
+
+// Renderer turns the markdown subset into the site's HTML. Its two hooks are
+// the places the site differs from a generic renderer: an image becomes a
+// committed asset (inlined SVG or copied raster) rather than a bare <img>, and
+// a repo-relative link becomes a site route.
+type Renderer struct {
+	// Labels are the two interface strings the renderer adds — a fenced block's
+	// copy button and its confirmation — and it adds nothing else. The site
+	// takes them from its closed allowlist of interface strings.
+	Labels Labels
+	// Image renders one image reference. src is as written in the markdown,
+	// relative to the page; alt is its alt text.
+	Image func(src, alt string, at Source) (string, error)
+	// Link rewrites one href. It never fails: an href it does not recognise is
+	// left exactly as the record wrote it.
+	Link func(href string, at Source) string
+	// Refs are the document's link reference definitions, from LinkDefinitions.
+	// A nil map means the document defines none, and every reference link in it
+	// is a refusal.
+	Refs map[string]string
+}
+
+// Labels are the interface strings a rendered page carries from the renderer.
+type Labels struct {
+	Copy   string
+	Copied string
+}
+
+// Source is a position in a repository file.
+type Source struct {
+	Path string
+	Line int
+}
+
+// RenderBlocks renders a block sequence in order.
+func (r *Renderer) RenderBlocks(path string, blocks []Block) (string, error) {
+	var b strings.Builder
+	for _, blk := range blocks {
+		h, err := r.RenderBlock(path, blk)
+		if err != nil {
+			return "", err
+		}
+		b.WriteString(h)
+	}
+	return b.String(), nil
+}
+
+// unrenderedFenceRe matches a fence opener the renderer does not render: a
+// tilde run, or a backtick run longer than three, at any indent.
+var unrenderedFenceRe = regexp.MustCompile("^[ \t]*(~{3,}|`{4,})")
+
+// RenderBlock renders one top-level block.
+func (r *Renderer) RenderBlock(path string, blk Block) (string, error) {
+	at := Source{Path: path, Line: blk.Line}
+	lines := strings.Split(blk.Text, "\n")
+	first := lines[0]
+
+	// The walk that cut this block reads fences by mdrecord's rule, tildes and
+	// longer backtick runs included, and this renderer renders one form: a
+	// three-backtick run at column 0. Any other form arriving here would render
+	// as a paragraph, delimiters and code inlined into prose, with no error, so
+	// it is refused. A three-backtick fence's own body is code and is not read
+	// (iss-2609251514129841).
+	if !strings.HasPrefix(first, "```") || strings.HasPrefix(first, "````") {
+		for i, ln := range lines {
+			if unrenderedFenceRe.MatchString(ln) {
+				return "", &UnsupportedError{at.Path, at.Line + i, "fenced code block opened by a tilde or a run of four or more backticks",
+					"only a three-backtick fence renders; any other opener renders as a paragraph"}
+			}
+		}
+	}
+
+	// A fence must open its own block. Without a blank line before it the block
+	// walk never sees it start, so the whole run — prose, backticks and code —
+	// arrives here as one paragraph, and every backtick would be escaped into the
+	// page as visible punctuation with the code inlined into the sentence.
+	if !strings.HasPrefix(first, "```") {
+		for i, ln := range lines {
+			if strings.HasPrefix(ln, "```") {
+				return "", &UnsupportedError{at.Path, at.Line + i, "fenced code block without a blank line before it",
+					"a fence opens its own block; without the blank line the code renders as part of the paragraph above"}
+			}
+		}
+	}
+
+	switch {
+	case strings.HasPrefix(first, "```"):
+		return r.fence(at, lines)
+	case strings.HasPrefix(strings.TrimSpace(first), "<!--"):
+		return r.commentBlock(at, lines)
+	case allLinkDefs(lines):
+		// A block of nothing but link reference definitions is invisible in
+		// every reader; its content is already carried by r.Refs.
+		return "", nil
+	case HeadingRe.MatchString(first):
+		return r.heading(at, first)
+	case thematicRe.MatchString(first):
+		// A rule opening a block is a rule. The same characters AFTER a line of
+		// text are a setext heading instead, which the paragraph renderer reads.
+		if len(lines) == 1 {
+			return "<hr>", nil
+		}
+		rest, err := r.RenderBlock(path, Block{Text: strings.Join(lines[1:], "\n"), Line: blk.Line + 1})
+		if err != nil {
+			return "", err
+		}
+		return "<hr>" + rest, nil
+	case strings.HasPrefix(strings.TrimSpace(first), ">"):
+		return r.blockquote(at, lines)
+	case strings.HasPrefix(strings.TrimSpace(first), "|"):
+		return r.table(at, lines)
+	case IsUnorderedItem(first) || OrderedItemRe.MatchString(first):
+		return r.list(at, lines)
+	}
+	return r.paragraph(at, lines)
+}
+
+// allLinkDefs reports whether every non-blank line of a block is a link
+// reference definition.
+func allLinkDefs(lines []string) bool {
+	any := false
+	for _, ln := range lines {
+		if strings.TrimSpace(ln) == "" {
+			continue
+		}
+		if !isLinkDefLine(ln) {
+			return false
+		}
+		any = true
+	}
+	return any
+}
+
+// commentBlock drops an HTML comment and renders whatever follows it. The
+// record uses them for machine annotations — review receipts, scope notes — and
+// no reader has ever shown one, so showing one here would publish a note
+// written for a tool.
+func (r *Renderer) commentBlock(at Source, lines []string) (string, error) {
+	text := strings.Join(lines, "\n")
+	i := strings.Index(text, "-->")
+	if i < 0 {
+		return "", &UnsupportedError{at.Path, at.Line, "unterminated HTML comment",
+			"it swallows the rest of the block, so the text after it silently stops existing"}
+	}
+	rest := strings.TrimLeft(text[i+3:], "\n")
+	if strings.TrimSpace(rest) == "" {
+		return "", nil
+	}
+	skipped := strings.Count(text[:i+3], "\n")
+	var out strings.Builder
+	for _, b := range Blocks(rest, at.Line+skipped) {
+		h, err := r.RenderBlock(at.Path, b)
+		if err != nil {
+			return "", err
+		}
+		out.WriteString(h)
+	}
+	return out.String(), nil
+}
+
+// fence renders a fenced code block as a copyable command block: the button's
+// label is a ui.json string, and its payload is the block's own raw text.
+func (r *Renderer) fence(at Source, lines []string) (string, error) {
+	info := strings.TrimSpace(strings.TrimPrefix(lines[0], "```"))
+	if strings.ContainsAny(info, " \t") {
+		return "", &UnsupportedError{at.Path, at.Line, "fenced-code info string", "only a bare language word is rendered, got " + Quote(info)}
+	}
+	body := lines[1:]
+	if n := len(body); n > 0 && strings.HasPrefix(strings.TrimSpace(body[n-1]), "```") {
+		body = body[:n-1]
+	}
+	raw := strings.Join(body, "\n")
+	cls := ""
+	if info != "" {
+		cls = ` class="language-` + EscapeAttr(info) + `"`
+	}
+	// The button's two labels both travel in the markup: the page's script adds
+	// no words of its own, so every string a reader sees comes from ui.json.
+	return `<div class="cmd"><pre><code` + cls + `>` + EscapeText(raw) + "\n" +
+		`</code></pre><button class="copy" data-copy="` + EscapeAttr(raw) +
+		`" data-copied="` + EscapeAttr(r.Labels.Copied) + `">` + EscapeText(r.Labels.Copy) + `</button></div>`, nil
+}
+
+// heading renders an ATX heading.
+func (r *Renderer) heading(at Source, line string) (string, error) {
+	m := HeadingRe.FindStringSubmatch(line)
+	level := len(m[1])
+	inner, err := r.Inline(at, strings.TrimSpace(m[2]))
+	if err != nil {
+		return "", err
+	}
+	tag := fmt.Sprintf("h%d", level)
+	return "<" + tag + ">" + inner + "</" + tag + ">", nil
+}
+
+// blockquote renders a `>` block by stripping the marker and rendering what is
+// left as blocks in their own right.
+//
+// That recursion is what carries the structures a quote legitimately holds —
+// paragraphs, lists, a quote inside a quote, a table. Flattening any of them
+// would publish a document the source does not have, with nothing on the page to
+// tell a reader that it happened.
+//
+// A LAZY continuation — a line inside the block that drops the marker — is still
+// refused. It is genuinely ambiguous: the same bytes are a quote in one reader
+// and a quote followed by a paragraph in another, and guessing publishes one of
+// them as if it were certain.
+func (r *Renderer) blockquote(at Source, lines []string) (string, error) {
+	var stripped []string
+	for i, ln := range lines {
+		t := strings.TrimSpace(ln)
+		if !strings.HasPrefix(t, ">") {
+			return "", &UnsupportedError{at.Path, at.Line + i, "lazy blockquote continuation", "every line of a quoted block must start with '>'"}
+		}
+		stripped = append(stripped, strings.TrimPrefix(strings.TrimPrefix(t, ">"), " "))
+	}
+	var b strings.Builder
+	b.WriteString("<blockquote>\n")
+	for _, blk := range Blocks(strings.Join(stripped, "\n"), at.Line) {
+		h, err := r.RenderBlock(at.Path, blk)
+		if err != nil {
+			return "", err
+		}
+		if h == "" {
+			continue
+		}
+		b.WriteString(h + "\n")
+	}
+	b.WriteString("</blockquote>")
+	return b.String(), nil
+}
+
+// tableCells splits one table row into its cells, honouring `\|` as content.
+// An escaped pipe is a pipe a cell contains, not a column boundary, and
+// splitting on it shifts every cell after it one column to the left — a table
+// that is quietly wrong, which is worse than one that fails to build. The
+// escape itself is left in place for the inline pass, which already knows `\|`
+// means `|`.
+func tableCells(ln string) []string {
+	t := strings.TrimSpace(ln)
+	t = strings.TrimPrefix(t, "|")
+	t = strings.TrimSuffix(t, "|")
+	var out []string
+	var cur strings.Builder
+	for i := 0; i < len(t); i++ {
+		switch {
+		case t[i] == '\\' && i+1 < len(t):
+			cur.WriteByte(t[i])
+			cur.WriteByte(t[i+1])
+			i++
+		case t[i] == '|':
+			out = append(out, strings.TrimSpace(cur.String()))
+			cur.Reset()
+		default:
+			cur.WriteByte(t[i])
+		}
+	}
+	return append(out, strings.TrimSpace(cur.String()))
+}
+
+// table renders a pipe table, inside its own overflow container.
+//
+// The container is emitted HERE rather than by each layout, because a table is
+// the one block whose width its author does not choose: the widest cell decides
+// it, and without a box to scroll inside, that cell sets the width of the whole
+// page on a phone. Every consumer — a composed chapter, a quoted span, a record
+// body rendered verbatim — gets the same treatment, so no new caller has to
+// remember.
+//
+// Column alignment is not rendered — the site's stylesheet aligns every column
+// the same way — so an alignment row is accepted and its colons ignored.
+func (r *Renderer) table(at Source, lines []string) (string, error) {
+	if len(lines) < 2 || !tableDelimRe.MatchString(lines[1]) {
+		return "", &UnsupportedError{at.Path, at.Line, "pipe table", "a table needs a header row and a |---|---| delimiter row"}
+	}
+	var b strings.Builder
+	b.WriteString(`<div class="tablewrap">` + "<table>\n<thead>\n<tr>\n")
+	for _, c := range tableCells(lines[0]) {
+		inner, err := r.Inline(Source{at.Path, at.Line}, c)
+		if err != nil {
+			return "", err
+		}
+		b.WriteString("<th>" + inner + "</th>\n")
+	}
+	b.WriteString("</tr>\n</thead>\n<tbody>\n")
+	for i, ln := range lines[2:] {
+		b.WriteString("<tr>\n")
+		for _, c := range tableCells(ln) {
+			inner, err := r.Inline(Source{at.Path, at.Line + 2 + i}, c)
+			if err != nil {
+				return "", err
+			}
+			b.WriteString("<td>" + inner + "</td>\n")
+		}
+		b.WriteString("</tr>\n")
+	}
+	b.WriteString("</tbody>\n</table></div>")
+	return b.String(), nil
+}
+
+// list renders an unordered or ordered list, nesting and all.
+//
+// Nesting is carried by INDENTATION, so each item's continuation lines are
+// dedented and handed back to the block walk: a list inside an item is then a
+// list block like any other, and an item that carries a table or a quoted line
+// gets it rendered rather than flattened into the sentence.
+func (r *Renderer) list(at Source, lines []string) (string, error) {
+	ordered := OrderedItemRe.MatchString(strings.TrimLeft(lines[0], " \t"))
+	base := IndentOf(lines[0])
+
+	type item struct {
+		body []string
+		line int
+	}
+	var items []item
+	for i, ln := range lines {
+		trimmed := strings.TrimLeft(ln, " \t")
+		isItem := IsUnorderedItem(trimmed) || OrderedItemRe.MatchString(trimmed)
+		if isItem && IndentOf(ln) <= base {
+			if OrderedItemRe.MatchString(trimmed) != ordered {
+				return "", &UnsupportedError{at.Path, at.Line + i, "mixed list", "a list is ordered or unordered, not both"}
+			}
+			rest := trimmed[2:]
+			if ordered {
+				rest = OrderedItemRe.FindStringSubmatch(trimmed)[2]
+			}
+			items = append(items, item{body: []string{strings.TrimSpace(rest)}, line: at.Line + i})
+			continue
+		}
+		if len(items) == 0 {
+			return "", &UnsupportedError{at.Path, at.Line + i, "list", "a list item starts with '- ' or '1. '"}
+		}
+		items[len(items)-1].body = append(items[len(items)-1].body, ln)
+	}
+
+	tag := "ul"
+	if ordered {
+		tag = "ol"
+	}
+	var b strings.Builder
+	b.WriteString("<" + tag + ">\n")
+	for _, it := range items {
+		inner, err := r.listItem(Source{at.Path, it.line}, it.body)
+		if err != nil {
+			return "", err
+		}
+		b.WriteString("<li>" + inner + "</li>\n")
+	}
+	b.WriteString("</" + tag + ">")
+	return b.String(), nil
+}
+
+// listItem renders one item: its own lead text as a sentence, and anything with
+// structure of its own — a nested list above all — as blocks under it.
+func (r *Renderer) listItem(at Source, body []string) (string, error) {
+	body = dedentContinuations(body)
+	// The lead runs until a line that opens a structure of its own. A nested
+	// list may follow the sentence with no blank line between them, which is
+	// exactly how the record writes one.
+	split := len(body)
+	for i := 1; i < len(body); i++ {
+		t := strings.TrimLeft(body[i], " \t")
+		if IsUnorderedItem(t) || OrderedItemRe.MatchString(t) || strings.HasPrefix(t, "```") ||
+			strings.HasPrefix(t, ">") || strings.HasPrefix(t, "|") || HeadingRe.MatchString(t) {
+			split = i
+			break
+		}
+	}
+	lead, err := r.Inline(at, strings.Join(body[:split], "\n"))
+	if err != nil {
+		return "", err
+	}
+	if split == len(body) {
+		return lead, nil
+	}
+	var b strings.Builder
+	b.WriteString(lead)
+	for _, blk := range Blocks(strings.Join(body[split:], "\n"), at.Line+split) {
+		h, err := r.RenderBlock(at.Path, blk)
+		if err != nil {
+			return "", err
+		}
+		b.WriteString(h)
+	}
+	return b.String(), nil
+}
+
+// dedentContinuations strips the shared indentation from an item's continuation
+// lines, so a nested list reads as a list rather than as indented prose. The
+// first line has already had its marker removed and is left alone.
+func dedentContinuations(body []string) []string {
+	least := -1
+	for _, ln := range body[1:] {
+		if strings.TrimSpace(ln) == "" {
+			continue
+		}
+		if n := IndentOf(ln); least < 0 || n < least {
+			least = n
+		}
+	}
+	if least <= 0 {
+		return body
+	}
+	out := append([]string{}, body[:1]...)
+	for _, ln := range body[1:] {
+		cut := 0
+		for cut < least && cut < len(ln) && (ln[cut] == ' ' || ln[cut] == '\t') {
+			cut++
+		}
+		out = append(out, ln[cut:])
+	}
+	return out
+}
+
+// IndentOf counts a line's leading spaces, a tab counting as one.
+func IndentOf(s string) int {
+	n := 0
+	for n < len(s) && (s[n] == ' ' || s[n] == '\t') {
+		n++
+	}
+	return n
+}
+
+// paragraph renders a run of prose.
+//
+// Two block constructs can only be recognised HERE, because both are a line of
+// text plus the line under it: a setext heading (`Title` over `===` or `---`)
+// and, in every reader the record is read in, the same underline turning the
+// text above it into a heading rather than into a rule. The paragraph is cut at
+// the underline and the head becomes the heading.
+//
+// A RAW HTML block is refused, and only when it opens the block: the same
+// pattern in the middle of a paragraph is a code span wrapped across a line, and
+// refusing that would fail the build on correct prose.
+func (r *Renderer) paragraph(at Source, lines []string) (string, error) {
+	for i, ln := range lines {
+		// A LIST may interrupt a paragraph, and the record writes one that way
+		// constantly — a bold lead-in and its bullets under it with no blank
+		// line between. Rendering the whole run as one paragraph flattens the
+		// bullets into stray hyphens in a run-on sentence, which is a different
+		// document from the one on the forge.
+		if i > 0 && listInterrupts(ln) {
+			head, err := r.paragraph(at, lines[:i])
+			if err != nil {
+				return "", err
+			}
+			rest, err := r.RenderBlock(at.Path, Block{Text: strings.Join(lines[i:], "\n"), Line: at.Line + i})
+			if err != nil {
+				return "", err
+			}
+			return head + rest, nil
+		}
+		if i > 0 && setextRe.MatchString(ln) {
+			level := 2
+			if strings.Contains(ln, "=") {
+				level = 1
+			}
+			head, err := r.Inline(at, strings.Join(lines[:i], "\n"))
+			if err != nil {
+				return "", err
+			}
+			tag := fmt.Sprintf("h%d", level)
+			out := "<" + tag + ">" + head + "</" + tag + ">"
+			if i+1 >= len(lines) {
+				return out, nil
+			}
+			rest, err := r.RenderBlock(at.Path, Block{Text: strings.Join(lines[i+1:], "\n"), Line: at.Line + i + 1})
+			if err != nil {
+				return "", err
+			}
+			return out + rest, nil
+		}
+		if i == 0 && rawHTMLStartRe.MatchString(ln) && isHTMLElementStart(strings.TrimLeft(ln, " \t")) {
+			return "", &UnsupportedError{at.Path, at.Line + i, "raw HTML block", "every picture is a committed asset and every element is generated"}
+		}
+		if i == 0 && (strings.HasPrefix(ln, "    ") || strings.HasPrefix(ln, "\t")) {
+			return "", &UnsupportedError{at.Path, at.Line, "indented code block", "fence code with ``` so it renders as a copyable command"}
+		}
+	}
+	inner, err := r.Inline(at, strings.Join(lines, "\n"))
+	if err != nil {
+		return "", err
+	}
+	// An image on its own line is a block-level figure, exactly as the source
+	// markdown reads it; the layouts detect one by this shape.
+	return "<p>" + inner + "</p>", nil
+}
+
+// isHTMLElementStart reports whether a `<…` opens a real HTML element rather
+// than a prose placeholder.
+//
+// The element name alone does not settle it: the record writes
+// `collaborators/<u>/permission` in a sentence, and `u` happens to be an HTML
+// element. Real markup shows itself — it carries attributes, it closes itself,
+// or a matching closing tag follows it. A bare known name with none of those is
+// a placeholder, and is shown as the record wrote it.
+func isHTMLElementStart(s string) bool {
+	if strings.HasPrefix(s, "<!") {
+		return !strings.HasPrefix(s, "<!--")
+	}
+	m := htmlTagRe.FindStringSubmatch(s)
+	if m == nil {
+		return false
+	}
+	name := strings.ToLower(m[1])
+	if !htmlElements[name] {
+		return false
+	}
+	if strings.HasPrefix(s, "</") || VoidElements[name] {
+		return true
+	}
+	end := strings.IndexByte(s, '>')
+	if end < 0 {
+		return false
+	}
+	if strings.TrimSpace(s[len(m[0]):end]) != "" {
+		return true
+	}
+	return strings.Contains(strings.ToLower(s[end:]), "</"+name+">")
+}
+
+// VoidElements are the HTML elements that never carry a closing tag, so their
+// bare form is still markup.
+var VoidElements = map[string]bool{
+	"area": true, "base": true, "br": true, "col": true, "embed": true, "hr": true,
+	"img": true, "input": true, "link": true, "meta": true, "source": true,
+	"track": true, "wbr": true,
+}
+
+// listInterrupts reports whether a line opening a list may cut the paragraph
+// above it.
+//
+// A bullet always may. An ordered item may only when it is numbered ONE, which
+// is CommonMark's rule and exists for exactly the sentence the record also
+// writes: a paragraph that wraps onto a line beginning "2. " is prose, not a
+// list, and cutting it there would invent a list nobody wrote.
+func listInterrupts(ln string) bool {
+	if IsUnorderedItem(ln) {
+		return true
+	}
+	m := OrderedItemRe.FindStringSubmatch(ln)
+	return m != nil && m[1] == "1"
+}
+
+// IsUnorderedItem reports whether a line opens an unordered list item.
+func IsUnorderedItem(ln string) bool {
+	return len(ln) > 2 && (ln[0] == '-' || ln[0] == '*' || ln[0] == '+') && ln[1] == ' '
+}
+
+// inlineNode is one piece of a scanned span run: either finished HTML, or a
+// run of emphasis delimiters still looking for its partner.
+type inlineNode struct {
+	// html is the rendered output of a finished piece.
+	html string
+	// delim is '*' or '_' for a delimiter run, and 0 otherwise.
+	delim byte
+	// n is how many characters of the run are still unspent; origN the run's
+	// original length, which the matching rules are stated in terms of.
+	n, origN int
+	// canOpen and canClose are the matching walk's state: what this run may
+	// still do. origOpen and origClose are the flanking rules' verdict, which is
+	// a fact about the text and never changes.
+	canOpen, canClose   bool
+	origOpen, origClose bool
+	// before holds closing tags and after opening tags, so a run that both
+	// closes an inner span and opens nothing still emits them in the right
+	// order around whatever characters it has left over.
+	before, after string
+}
+
+// Inline renders the span-level subset in two passes.
+//
+// The first pass reads left to right and finishes everything whose boundaries
+// are unambiguous — escapes, code spans, autolinks, images, links — leaving the
+// emphasis delimiters as unspent runs. The second pass matches those runs.
+//
+// The order is what makes `**`+"`"+`.abcd/**`+"`"+` stays**` render: a code span binds
+// tighter than emphasis in every reader, so the asterisks inside one are
+// content, and a single left-to-right pass that met the `**` first would take
+// its closer from inside the code and then refuse an unclosed span.
+func (r *Renderer) Inline(at Source, s string) (string, error) {
+	nodes, err := r.scanInline(at, s)
+	if err != nil {
+		return "", err
+	}
+	matchEmphasis(nodes)
+	var b strings.Builder
+	for _, nd := range nodes {
+		if nd.delim == 0 {
+			b.WriteString(nd.html)
+			continue
+		}
+		b.WriteString(nd.before)
+		if nd.n > 0 {
+			b.WriteString(strings.Repeat(string(nd.delim), nd.n))
+		}
+		b.WriteString(nd.after)
+	}
+	return b.String(), nil
+}
+
+// scanInline is the first pass.
+func (r *Renderer) scanInline(at Source, s string) ([]*inlineNode, error) {
+	var nodes []*inlineNode
+	text := func(h string) {
+		if n := len(nodes); n > 0 && nodes[n-1].delim == 0 {
+			nodes[n-1].html += h
+			return
+		}
+		nodes = append(nodes, &inlineNode{html: h})
+	}
+	for i := 0; i < len(s); {
+		switch c := s[i]; {
+		case c == '\\' && i+1 < len(s) && isEscapable(s[i+1]):
+			text(EscapeText(string(s[i+1])))
+			i += 2
+		case c == '`':
+			n := runLen(s, i, '`')
+			end := strings.Index(s[i+n:], s[i:i+n])
+			if end < 0 {
+				return nil, &UnsupportedError{at.Path, at.Line, "unclosed code span", Quote(Clip(s[i:]))}
+			}
+			code := s[i+n : i+n+end]
+			if n > 1 {
+				code = strings.Trim(code, " ")
+			}
+			text("<code>" + EscapeText(code) + "</code>")
+			i += n + end + n
+		case c == '!' && i+1 < len(s) && s[i+1] == '[':
+			label, href, next, kind := parseLink(s, i+1)
+			switch kind {
+			case linkLiteral:
+				text("!")
+				i++
+				continue
+			case linkRefused, linkRef:
+				return nil, &UnsupportedError{at.Path, at.Line, "image", "only ![alt](src) is rendered, got " + Quote(Clip(s[i:]))}
+			}
+			html, err := r.Image(href, label, at)
+			if err != nil {
+				return nil, err
+			}
+			text(html)
+			i = next
+		case c == '[':
+			label, href, next, kind := parseLink(s, i)
+			switch kind {
+			case linkLiteral:
+				// A bracket that opens no link is a bracket. Refusing it would
+				// blocker-fail the build over prose like "the array [0]", which
+				// every markdown reader renders literally.
+				text("[")
+				i++
+				continue
+			case linkRef:
+				dest, ok := r.Refs[normaliseLabel(href)]
+				if !ok {
+					// A document that defines no references is not writing one:
+					// `[A-Za-z][A-Za-z0-9._-]*` is a regular expression, and
+					// every reader shows it as the brackets it is. A document
+					// that DOES define references is held to them, so a typo in
+					// a label fails the build rather than quietly losing a
+					// destination.
+					if len(r.Refs) == 0 {
+						text("[")
+						i++
+						continue
+					}
+					return nil, &UnsupportedError{at.Path, at.Line, "link",
+						"the reference " + Quote(href) + " has no [" + href + "]: definition in this document"}
+				}
+				href = dest
+			case linkRefused:
+				return nil, &UnsupportedError{at.Path, at.Line, "link",
+					"only [text](href) and a defined [text][ref] are rendered; footnotes and inline link titles are not in the subset"}
+			}
+			h, err := r.anchor(at, label, href)
+			if err != nil {
+				return nil, err
+			}
+			text(h)
+			i = next
+		case c == '*' || c == '_':
+			n := runLen(s, i, c)
+			opens, closes := flanking(s, i, n, c)
+			nodes = append(nodes, &inlineNode{delim: c, n: n, origN: n,
+				canOpen: opens, canClose: closes, origOpen: opens, origClose: closes})
+			i += n
+		case c == '<':
+			h, next, err := r.angle(at, s, i)
+			if err != nil {
+				return nil, err
+			}
+			text(h)
+			i = next
+		default:
+			j := i
+			for j < len(s) && !strings.ContainsRune("\\`![*_<", rune(s[j])) {
+				j++
+			}
+			if j == i {
+				j = i + 1
+			}
+			text(EscapeText(s[i:j]))
+			i = j
+		}
+	}
+	return nodes, nil
+}
+
+// anchor renders one link, refusing the two shapes HTML cannot carry.
+func (r *Renderer) anchor(at Source, label, href string) (string, error) {
+	if scheme, bad := ExecutableScheme(href); bad {
+		return "", &UnsupportedError{at.Path, at.Line, "link scheme",
+			Quote(scheme) + " runs code in the reader's browser; the site links to pages and files"}
+	}
+	inner, err := r.Inline(at, label)
+	if err != nil {
+		return "", err
+	}
+	// HTML has no nested anchor: a browser closes the outer one at the inner, so
+	// the markup a reader gets is not the markup written here and the outer
+	// link's tail stops being clickable. Markdown itself forbids the construct;
+	// this says so instead of emitting it.
+	if strings.Contains(inner, "<a ") {
+		return "", &UnsupportedError{at.Path, at.Line, "nested link",
+			"HTML has no anchor inside an anchor; the browser would silently close the outer one"}
+	}
+	return `<a href="` + EscapeAttr(r.Link(href, at)) + `">` + inner + "</a>", nil
+}
+
+// angle reads a `<` and decides which of the four things it is: an autolink, an
+// HTML comment (dropped, as every reader drops one), an HTML element (refused),
+// or a prose placeholder like `<ts>` (shown as the record wrote it).
+func (r *Renderer) angle(at Source, s string, i int) (string, int, error) {
+	rest := s[i:]
+	if strings.HasPrefix(rest, "<!--") {
+		end := strings.Index(rest, "-->")
+		if end < 0 {
+			return "", 0, &UnsupportedError{at.Path, at.Line, "unterminated HTML comment",
+				"it swallows the rest of the line, so the text after it silently stops existing"}
+		}
+		return "", i + end + 3, nil
+	}
+	if m := autolinkRe.FindStringSubmatch(rest); m != nil {
+		h, err := r.anchor(at, m[1], m[1])
+		if err != nil {
+			return "", 0, err
+		}
+		return h, i + len(m[0]), nil
+	}
+	if m := emailAutoRe.FindStringSubmatch(rest); m != nil {
+		h, err := r.anchor(at, m[1], "mailto:"+m[1])
+		if err != nil {
+			return "", 0, err
+		}
+		return h, i + len(m[0]), nil
+	}
+	if isHTMLElementStart(rest) {
+		return "", 0, &UnsupportedError{at.Path, at.Line, "inline HTML or autolink",
+			"wrap it in a code span or write it as [text](href): " + Quote(Clip(rest))}
+	}
+	return "&lt;", i + 1, nil
+}
+
+// flanking applies CommonMark's left- and right-flanking rules to a delimiter
+// run: whether it may open emphasis, close it, or neither. It is what keeps
+// `snake_case` a word and `npx-create-*` a filename pattern.
+func flanking(s string, i, n int, c byte) (canOpen, canClose bool) {
+	before := byte(' ')
+	if i > 0 {
+		before = s[i-1]
+	}
+	after := byte(' ')
+	if i+n < len(s) {
+		after = s[i+n]
+	}
+	left := !IsSpace(after) && (!isPunct(after) || IsSpace(before) || isPunct(before))
+	right := !IsSpace(before) && (!isPunct(before) || IsSpace(after) || isPunct(after))
+	if c == '*' {
+		return left, right
+	}
+	return left && (!right || isPunct(before)), right && (!left || isPunct(after))
+}
+
+// matchEmphasis is the second pass: CommonMark's closer-then-opener walk over
+// the unspent delimiter runs. A run that finds no partner keeps its characters
+// and renders as the punctuation it is.
+func matchEmphasis(nodes []*inlineNode) {
+	for ci := 0; ci < len(nodes); ci++ {
+		c := nodes[ci]
+		if c.delim == 0 || !c.canClose || c.n == 0 {
+			continue
+		}
+		oi := -1
+		for j := ci - 1; j >= 0; j-- {
+			o := nodes[j]
+			if o.delim != c.delim || !o.canOpen || o.n == 0 {
+				continue
+			}
+			// The "rule of three": a run that can both open and close only
+			// pairs with one whose combined length is not a multiple of three,
+			// unless both lengths are. It is what stops `**a*b**` pairing the
+			// wrong two runs.
+			//
+			// It is asked of the FLANKING verdicts, which never change, and not
+			// of canOpen/canClose, which the walk turns off as it consumes runs:
+			// reading the mutable pair here made a closer that had already given
+			// up look like a run that cannot open, and the wrong two runs paired.
+			if (c.origOpen || o.origClose) && (o.origN+c.origN)%3 == 0 &&
+				!(o.origN%3 == 0 && c.origN%3 == 0) {
+				continue
+			}
+			oi = j
+			break
+		}
+		if oi < 0 {
+			c.canClose = false
+			continue
+		}
+		o := nodes[oi]
+		tag := "em"
+		use := 1
+		if o.n >= 2 && c.n >= 2 {
+			tag, use = "strong", 2
+		}
+		o.n -= use
+		c.n -= use
+		o.after = "<" + tag + ">" + o.after
+		c.before += "</" + tag + ">"
+		// A run trapped inside the pair can no longer match anything, but its
+		// CHARACTERS are still characters: `**MET_WITH_CONCERNS.**` keeps its
+		// underscores, exactly as every reader keeps them. Zeroing `n` here
+		// deleted them from the page instead — a silent difference between the
+		// record and what a reader was shown, which is the one thing this
+		// renderer exists to prevent.
+		for j := oi + 1; j < ci; j++ {
+			if nodes[j].delim != 0 {
+				nodes[j].canOpen, nodes[j].canClose = false, false
+			}
+		}
+		if c.n > 0 {
+			// The same closer may still close an outer span.
+			ci--
+		}
+	}
+}
+
+// isPunct reports whether a byte is ASCII punctuation, the class the flanking
+// rules are stated over.
+func isPunct(c byte) bool {
+	return (c >= '!' && c <= '/') || (c >= ':' && c <= '@') ||
+		(c >= '[' && c <= '`') || (c >= '{' && c <= '~')
+}
+
+// The three things a '[' can turn out to be.
+const (
+	// linkInline is `[text](href)`: rendered.
+	linkInline = iota
+	// linkRefused is a construct that MEANS a link but is not in the subset — a
+	// reference link, a footnote, a link title. Rendering it literally would
+	// publish the markup; dropping it would lose the destination.
+	linkRefused
+	// linkLiteral is a bracket that opens no link at all. It is text.
+	linkLiteral
+	// linkRef is `[text][label]` or `[text][]`: the destination is defined
+	// elsewhere in the document, and the caller resolves it.
+	linkRef
+)
+
+// parseLink classifies a '[' at i and, for an inline link, returns its text,
+// its href, and the index just past the closing paren.
+func parseLink(s string, i int) (text, href string, next, kind int) {
+	depth := 0
+	j := i
+	for ; j < len(s); j++ {
+		switch s[j] {
+		case '[':
+			depth++
+		case ']':
+			depth--
+		}
+		if depth == 0 {
+			break
+		}
+	}
+	if j >= len(s) || j+1 >= len(s) {
+		return "", "", 0, linkLiteral
+	}
+	switch s[j+1] {
+	case '(':
+		// An inline link, or an attempt at one.
+	case '[':
+		// `[text][label]` — a reference link. The label is what sits in the
+		// second pair of brackets, or the text itself when they are empty.
+		end := strings.IndexByte(s[j+2:], ']')
+		if end < 0 {
+			return "", "", 0, linkLiteral
+		}
+		text = s[i+1 : j]
+		label := s[j+2 : j+2+end]
+		if strings.TrimSpace(label) == "" {
+			label = text
+		}
+		return text, label, j + 2 + end + 1, linkRef
+	default:
+		return "", "", 0, linkLiteral
+	}
+	text = s[i+1 : j]
+	k := j + 2
+	pd := 1
+	for ; k < len(s); k++ {
+		if s[k] == '(' {
+			pd++
+		} else if s[k] == ')' {
+			pd--
+			if pd == 0 {
+				break
+			}
+		}
+	}
+	if k >= len(s) {
+		return "", "", 0, linkRefused
+	}
+	href = strings.TrimSpace(s[j+2 : k])
+	if href == "" || strings.ContainsAny(href, " \t") {
+		// A link title (`[t](u "title")`) is not in the subset: it renders as an
+		// attribute nothing on the site reads, and hiding prose in one would
+		// smuggle unsourced text onto the page.
+		return "", "", 0, linkRefused
+	}
+	return text, href, k + 1, linkInline
+}
+
+// ExecutableScheme reports whether an href names a scheme that executes rather
+// than navigates. Escaping an attribute is not enough on its own: a perfectly
+// well-formed `javascript:` href needs no quote to break out of, and the site
+// renders text from a repository whose files an outside contributor can edit.
+// The comparison folds case and strips the whitespace and control characters a
+// browser ignores inside a scheme, because those are exactly what a bypass is
+// written with.
+func ExecutableScheme(href string) (string, bool) {
+	var b strings.Builder
+	for i := 0; i < len(href); i++ {
+		c := href[i]
+		if c == ':' {
+			scheme := strings.ToLower(b.String())
+			switch scheme {
+			case "javascript", "vbscript", "data":
+				return scheme + ":", true
+			}
+			return "", false
+		}
+		if c == '/' || c == '?' || c == '#' {
+			return "", false
+		}
+		if c <= ' ' || c == 0x7f {
+			continue
+		}
+		b.WriteByte(c)
+	}
+	return "", false
+}
+
+func isEscapable(c byte) bool {
+	return strings.IndexByte("\\`*_{}[]()#+-.!|<>&\"'~", c) >= 0
+}
+
+// runLen counts the run of c starting at i.
+func runLen(s string, i int, c byte) int {
+	n := 0
+	for i+n < len(s) && s[i+n] == c {
+		n++
+	}
+	return n
+}
+
+// EscapeText escapes a text node.
+func EscapeText(s string) string {
+	return strings.NewReplacer("&", "&amp;", "<", "&lt;", ">", "&gt;").Replace(s)
+}
+
+// EscapeAttr escapes an attribute value.
+func EscapeAttr(s string) string {
+	return strings.NewReplacer("&", "&amp;", "<", "&lt;", ">", "&gt;", `"`, "&quot;", "'", "&#39;").Replace(s)
+}
+
+func Quote(s string) string { return `"` + s + `"` }
+
+// Clip shortens a fragment for an error message.
+//
+// It counts RUNES, because the record is written in prose that carries
+// em-dashes and accents: slicing by bytes lands mid-character and puts a
+// replacement glyph in the middle of the one message somebody reads to find
+// the line the build refused.
+func Clip(s string) string {
+	const max = 40
+	s = strings.ReplaceAll(s, "\n", " ")
+	r := []rune(s)
+	if len(r) > max {
+		return string(r[:max]) + "…"
+	}
+	return s
+}
+
+// IsSpace reports whether a byte is markdown whitespace.
+func IsSpace(c byte) bool { return c == ' ' || c == '\t' || c == '\n' || c == '\r' }
+
+// RefusalIn reports the first construct this renderer refuses in one block of
+// record prose — a grounds entry's bullet is one — or nil when the block
+// renders. The error names the construct and why it is refused. It is the renderer itself, run over the block, so what it refuses is
+// exactly what a page build refuses and there is no list of rules to keep in
+// step with it.
+//
+// Two things a page supplies are absent, and each is answered the strict way,
+// so the answer is never looser than the page the block lands on:
+//
+//   - The block is judged as part of a document that DEFINES link references.
+//     A page that defines none shows `[text][label]` as the brackets it is,
+//     while a page that defines any refuses a label it does not define; the
+//     record a block is appended to may do either, so every reference link is
+//     refused. The one definition carries a label no reference can spell, since
+//     a label is folded to trimmed, single-spaced text before it is looked up.
+//   - Every image is refused. A page resolves a local image against its own
+//     committed assets and refuses a remote one; one block of prose has no page
+//     to resolve against, and a picture is not what such prose is for.
+func RefusalIn(block string) error {
+	r := &Renderer{
+		Image: func(_, _ string, at Source) (string, error) {
+			return "", &UnsupportedError{Path: at.Path, Line: at.Line, Construct: "image",
+				Detail: "a picture on a page is a committed asset resolved against that page, and one block of prose has none"}
+		},
+		Link: func(href string, _ Source) string { return href },
+		Refs: map[string]string{" ": ""},
+	}
+	_, err := r.RenderBlock("", Block{Text: block, Line: 1})
+	var u *UnsupportedError
+	if errors.As(err, &u) {
+		// The block has no file and no line a reader could open, so the refusal
+		// is the construct and why, without the position a page refusal leads with.
+		if u.Detail == "" {
+			return errors.New(u.Construct)
+		}
+		return fmt.Errorf("%s (%s)", u.Construct, u.Detail)
+	}
+	return err
+}
diff --git a/internal/core/reading/project.go b/internal/core/reading/project.go
index 718d93814..76b5a207f 100644
--- a/internal/core/reading/project.go
+++ b/internal/core/reading/project.go
@@ -6,6 +6,7 @@ import (
 	"regexp"
 	"slices"
 	"strings"
+	"unicode"
 
 	"github.com/intentdriven/abcd/internal/core/frontmatter"
 	"github.com/intentdriven/abcd/internal/core/lint"
@@ -498,7 +499,8 @@ func verifyRedaction(rel, original, redacted string, keys, headings map[string]b
 	// The scan runs over the unfenced body JOINED, not line by line, because
 	// `<h2>` and its text and its close need not share a line. The match offset
 	// maps back to a line so the refusal still names one.
-	if line, title, ok := rawHTMLHeading(lines, fenced, offset, headings); ok {
+	line, title, ok, overBudget := rawHTMLHeading(lines, fenced, offset, headings)
+	if ok {
 		if want, hit := namesExcludedHeading(title, headings); hit {
 			return fmt.Errorf("reading: %s carries the excluded heading %q as raw HTML at line %d; "+
 				"the floor names %q, and a heading is excluded however it is spelled",
@@ -508,15 +510,24 @@ func verifyRedaction(rel, original, redacted string, keys, headings map[string]b
 
 	// An opener that reaches the end of the document with neither a hard nor a
 	// soft bound has its title read over the whole remainder, which is the shape
-	// that admitted the heading sitting under it. The refusal removes the
-	// shape's admission and claims nothing about the scan's COST, which stays
-	// with iss-2608301421382564 (iss-2608301421380392).
+	// that admitted the heading sitting under it (iss-2608301421380392). It is
+	// asked before the budget below is, so a document that is both is refused
+	// by the shape it has rather than by what reading it would cost.
 	if line, ok := unboundedRawHeading(lines, fenced, offset); ok {
 		return fmt.Errorf("reading: %s opens a raw heading element that is never closed at line "+
 			"%d, and nothing bounds its title short of the end of the document; the title is "+
 			"refused rather than read over the remainder", rel, line)
 	}
 
+	// Titles that overlap past the read budget are refused rather than read in
+	// time quadratic in the opener count (iss-2608301421382564). The scan above
+	// stopped at the opener that spent the budget and read no title past it.
+	if overBudget {
+		return fmt.Errorf("reading: %s opens raw heading elements whose titles overlap past the "+
+			"floor's read budget (from line %d); each title would be read over most of the "+
+			"document, so the titles are refused rather than read in quadratic time", rel, line)
+	}
+
 	// Setext headings are a refusal rather than a redaction. The section scan
 	// does not model them, so there is no span to delete, and inventing a second
 	// heading scanner here to compute one is the second parser this package
@@ -738,8 +749,8 @@ func escapedQuotedKey(line string) (string, bool) {
 	return m[1], true
 }
 
-// rawHeadingTitleEnds bounds the text one heading element introduces, and
-// returns EVERY reading of that bound rather than one.
+// rawHeadingBounds bounds the text one heading element introduces, and returns
+// EVERY reading of that bound rather than one.
 //
 // The hard bound is the element's OWN closing tag or the next heading open,
 // whichever comes first. Bounding at any closing tag instead cut the title at
@@ -758,21 +769,88 @@ func escapedQuotedKey(line string) (string, bool) {
 // caller refuses on either: a title read two ways is excluded if EITHER way
 // names an excluded heading.
 //
-// The walk is incremental rather than a materialised match list. Listing every
-// candidate bound in the whole remainder for every opener, only to break at the
-// first hard one, is quadratic with a large constant: a committed markdown file
-// of repeated openers up to the size cap this package sets did not finish, and a
-// silent hang is the one staging a fail-closed floor cannot afford.
+// The bounds are indexed once per reading, not searched once per opener. A
+// walk from each opener to its first hard bound is linear per opener and
+// quadratic per document: listing every candidate bound in the remainder for
+// every opener did not finish on a committed file up to the size cap, and even
+// the incremental walk read the whole remainder once per opener when no bound
+// followed (iss-2608301421382564). One pass lists every candidate bound in the
+// reading, and each opener finds its own by binary search. The list is the one
+// the walk visited: a bound match ends at a `>` or is a blank line, so no match
+// straddles the `>` that ends an opener, and the matches at or after an opener
+// are exactly the ones a walk starting there would have found.
+//
 // The second return says whether ANY bound was found. An opener with neither a
 // hard nor a soft bound has its title read over the whole remainder of the
 // document, which is the shape that admitted the heading sitting under it; the
 // caller refuses it rather than reading the remainder as a title
 // (iss-2608301421380392).
-func rawHeadingTitleEnds(rest, name string) ([]int, bool) {
-	hard, soft := -1, -1
-	for off := 0; off < len(rest); {
+type rawHeadingBounds struct {
+	text   string
+	starts []int            // every candidate bound's start, ascending
+	endsAt []int            // and its end, index for index
+	blanks []int            // starts of blank lines: the soft bound
+	hOpens []int            // starts of h-tag openers: a hard bound for every element
+	closes map[string][]int // starts of closing tags, keyed by the name's case fold
+}
+
+// indexRawHeadingBounds lists every candidate bound in one reading of the
+// document, in a single pass.
+func indexRawHeadingBounds(text string) *rawHeadingBounds {
+	ix := &rawHeadingBounds{text: text, closes: map[string][]int{}}
+	for _, m := range rawHeadingBoundRe.FindAllStringSubmatchIndex(text, -1) {
+		ix.starts = append(ix.starts, m[0])
+		ix.endsAt = append(ix.endsAt, m[1])
+		switch {
+		case text[m[0]] == '\n':
+			ix.blanks = append(ix.blanks, m[0])
+		case m[2] >= 0:
+			key := elementFoldKey(text[m[2]:m[3]])
+			ix.closes[key] = append(ix.closes[key], m[0])
+		default:
+			ix.hOpens = append(ix.hOpens, m[0])
+		}
+	}
+	return ix
+}
+
+// titleEnds bounds the title of the opener whose tag ends at p, returning each
+// reading of the bound as an offset from p, and whether any bound was found.
+//
+// One case is walked rather than looked up. An opener is found in one reading
+// and bounded in every reading, and in a MASKED reading the `>` that ends it
+// may be blanked, because it sat inside a comment or an attribute value there.
+// A bound match of that reading can then straddle p, and a walk starting at p
+// finds matches the single pass never listed. For that opener the walk from p
+// runs as it always did, and the bytes it reads are charged to the budget, so a
+// document built of such openers is refused rather than read in quadratic time.
+func (ix *rawHeadingBounds) titleEnds(p int, name string, budget *titleReadBudget) ([]int, bool) {
+	if i, _ := slices.BinarySearch(ix.starts, p); i > 0 && ix.endsAt[i-1] > p {
+		ends, bounded, scanned := walkRawHeadingBounds(ix.text[p:], name)
+		budget.charge(scanned)
+		return ends, bounded
+	}
+	hard := min(nextAt(ix.hOpens, p), nextAt(ix.closes[elementFoldKey(name)], p))
+	soft := nextAt(ix.blanks, p)
+	bounded := hard != noBound || soft != noBound
+	if hard == noBound {
+		hard = len(ix.text)
+	}
+	ends := []int{hard - p}
+	if soft < hard {
+		ends = append(ends, soft-p)
+	}
+	return ends, bounded
+}
+
+// walkRawHeadingBounds is the bound walk titleEnds indexes, run from one opener
+// over the remainder of its reading. It also returns how far it read.
+func walkRawHeadingBounds(rest, name string) ([]int, bool, int) {
+	hard, soft, off := -1, -1, 0
+	for off < len(rest) {
 		m := rawHeadingBoundRe.FindStringSubmatchIndex(rest[off:])
 		if m == nil {
+			off = len(rest)
 			break
 		}
 		at := off + m[0]
@@ -789,7 +867,7 @@ func rawHeadingTitleEnds(rest, name string) ([]int, bool) {
 				continue
 			}
 		}
-		hard = at
+		hard, off = at, off+m[1]
 		break
 	}
 	bounded := hard >= 0 || soft >= 0
@@ -800,7 +878,73 @@ func rawHeadingTitleEnds(rest, name string) ([]int, bool) {
 	if soft >= 0 && soft < hard {
 		ends = append(ends, soft)
 	}
-	return ends, bounded
+	return ends, bounded, off
+}
+
+// titleReadBudget bounds the bytes the raw heading scan reads to a multiple of
+// the document's own length.
+//
+// Indexing the bounds makes FINDING each title linear; READING the titles is
+// another matter. A title is rendered and compared over the whole span its
+// bound gives it, and titles overlap: a run of openers that all share one far
+// bound gives each of them most of the document, so the rendering alone is
+// quadratic in the opener count however the bound is found. Truncating a long
+// title is not an answer — padding a heading with a comment or with tags is how
+// an excluded one would be walked past a cap — and a long title is not a refusal
+// on its own either, because the committed corpus holds single spans of tens of
+// kilobytes that read in no time.
+//
+// So the budget is on the TOTAL. Every title rendered, and every walk titleEnds
+// falls back to, is charged; a document whose titles overlap past the budget
+// is refused by name, which is the fail-closed answer the floor gives every
+// shape it cannot read, and the scan is linear in the document by construction.
+// The allowance is generous: the committed corpus reads under one times its own
+// length in titles, and the budget is eight times plus a floor.
+type titleReadBudget struct {
+	left      int
+	exhausted bool
+}
+
+// newTitleReadBudget sizes the budget for a document of n bytes.
+func newTitleReadBudget(n int) *titleReadBudget {
+	return &titleReadBudget{left: 8*n + 1<<20}
+}
+
+// charge spends n bytes, recording exhaustion once the budget is spent.
+func (b *titleReadBudget) charge(n int) {
+	b.left -= n
+	if b.left < 0 {
+		b.exhausted = true
+	}
+}
+
+// nextAt returns the first position in the sorted list at or after p, or
+// noBound when there is none, so that min over two lookups picks the one that
+// exists.
+func nextAt(sorted []int, p int) int {
+	i, _ := slices.BinarySearch(sorted, p)
+	if i == len(sorted) {
+		return noBound
+	}
+	return sorted[i]
+}
+
+// noBound stands for a missing bound. It is larger than every offset, so min
+// prefers any real bound.
+const noBound = int(^uint(0) >> 1)
+
+// elementFoldKey reduces an element name to one spelling per case-fold class, which
+// is the equivalence strings.EqualFold decides: the pattern matches names
+// case-insensitively, and under Go's folding that admits the Kelvin sign for
+// `k` and the long s for `s`, which a plain lower-casing would miss.
+func elementFoldKey(name string) string {
+	return strings.Map(func(r rune) rune {
+		least := r
+		for f := unicode.SimpleFold(r); f != r; f = unicode.SimpleFold(f) {
+			least = min(least, f)
+		}
+		return least
+	}, name)
 }
 
 // maskMarkupData blanks, length-preservingly, the angle brackets that stand
@@ -972,7 +1116,10 @@ func maskAngles(out []byte, from, to int) {
 // structure; it must never stop them from being read as content. Reading both
 // makes the mask purely additive: every refusal the unmasked text supports still
 // stands, and the masked text can only add more.
-func rawHTMLHeading(lines []string, fenced []bool, offset int, headings map[string]bool) (int, string, bool) {
+//
+// The fourth return reports that the titles overlapped past the read budget
+// (titleReadBudget); the scan stops there, and the caller refuses.
+func rawHTMLHeading(lines []string, fenced []bool, offset int, headings map[string]bool) (int, string, bool, bool) {
 	raw := strings.Join(lines, "\n")
 	lineBounded, _ := maskMarkupData(raw, true)
 	unbounded, _ := maskMarkupData(raw, false)
@@ -982,32 +1129,60 @@ func rawHTMLHeading(lines []string, fenced []bool, offset int, headings map[stri
 			readings = append(readings, masked)
 		}
 	}
+	bounds := make([]*rawHeadingBounds, len(readings))
+	for i, r := range readings {
+		bounds[i] = indexRawHeadingBounds(r)
+	}
+	budget := newTitleReadBudget(len(raw))
 
 	for _, text := range readings {
+		at := lineCounter{text: text}
 		for _, open := range rawHeadingOpenRe.FindAllStringSubmatchIndex(text, -1) {
-			line := strings.Count(text[:open[0]], "\n")
+			line := at.at(open[0])
 			if line < offset || (line < len(fenced) && fenced[line]) {
 				continue
 			}
-			name := ""
-			for _, g := range [][2]int{{open[2], open[3]}, {open[4], open[5]}} {
-				if g[0] >= 0 {
-					name = text[g[0]:g[1]]
-				}
-			}
+			name := openerName(text, open)
 			if name == "" {
 				continue
 			}
-			rests := make([]string, 0, len(readings))
-			for _, r := range readings {
-				rests = append(rests, r[open[1]:])
+			title, ok := excludedRawTitle(readings, bounds, open[1], name, headings, budget)
+			if ok {
+				return line + 1, title, true, false
 			}
-			if title, ok := excludedRawTitle(rests, name, headings); ok {
-				return line + 1, title, true
+			if budget.exhausted {
+				return line + 1, "", false, true
 			}
 		}
 	}
-	return 0, "", false
+	return 0, "", false, false
+}
+
+// openerName returns the element name a rawHeadingOpenRe match captured: the
+// h-tag's, or the name of the element carrying the heading role.
+func openerName(text string, open []int) string {
+	name := ""
+	for _, g := range [][2]int{{open[2], open[3]}, {open[4], open[5]}} {
+		if g[0] >= 0 {
+			name = text[g[0]:g[1]]
+		}
+	}
+	return name
+}
+
+// lineCounter maps ascending byte offsets to 0-based line numbers, counting
+// each newline once. Counting from the top of the document for every opener is
+// quadratic in the opener count: at the size cap it alone took seconds.
+type lineCounter struct {
+	text      string
+	pos, line int
+}
+
+// at returns the line holding offset. Offsets must not decrease between calls.
+func (c *lineCounter) at(offset int) int {
+	c.line += strings.Count(c.text[c.pos:offset], "\n")
+	c.pos = offset
+	return c.line
 }
 
 // excludedRawTitle reports the excluded heading the text after one raw opener
@@ -1018,17 +1193,25 @@ func rawHTMLHeading(lines []string, fenced []bool, offset int, headings map[stri
 // `</h2>` written inside an attribute value bounds nothing; the unmasked text
 // answers what the title SAYS, since a heading written inside a comment is still
 // carried by the file. Taking either alone lost the other.
-func excludedRawTitle(rests []string, name string, headings map[string]bool) (string, bool) {
+//
+// Every title rendered is charged to the budget first; once it is spent the
+// answer is no longer trusted and the caller refuses the document.
+func excludedRawTitle(readings []string, bounds []*rawHeadingBounds, p int, name string,
+	headings map[string]bool, budget *titleReadBudget) (string, bool) {
 	seen := map[int]bool{}
-	for _, bound := range rests {
-		ends, _ := rawHeadingTitleEnds(bound, name)
+	for _, ix := range bounds {
+		ends, _ := ix.titleEnds(p, name, budget)
 		for _, end := range ends {
 			if seen[end] {
 				continue
 			}
 			seen[end] = true
-			for _, text := range rests {
-				for _, read := range renderedTexts(text[:end]) {
+			for _, text := range readings {
+				budget.charge(end)
+				if budget.exhausted {
+					return "", false
+				}
+				for _, read := range renderedTexts(text[p : p+end]) {
 					title := normaliseHeadingTitle(read)
 					if title == "" {
 						continue
@@ -1267,23 +1450,25 @@ func displacedFrontmatter(lines []string) (int, string, bool) {
 // an attribute value's brackets from being read as structure, and a bound it
 // erases was never a bound; a mask that could manufacture this refusal would be
 // a mask deciding, which is what every other reading here refuses to let it do.
+//
+// The document is its own only reading here, so every opener's `>` is a `>` in
+// the reading its bounds come from and titleEnds never walks: the scan is one
+// pass to index and a lookup per opener.
 func unboundedRawHeading(lines []string, fenced []bool, offset int) (int, bool) {
 	text := strings.Join(lines, "\n")
+	bounds := indexRawHeadingBounds(text)
+	budget := newTitleReadBudget(len(text))
+	at := lineCounter{text: text}
 	for _, open := range rawHeadingOpenRe.FindAllStringSubmatchIndex(text, -1) {
-		line := strings.Count(text[:open[0]], "\n")
+		line := at.at(open[0])
 		if line < offset || (line < len(fenced) && fenced[line]) {
 			continue
 		}
-		name := ""
-		for _, g := range [][2]int{{open[2], open[3]}, {open[4], open[5]}} {
-			if g[0] >= 0 {
-				name = text[g[0]:g[1]]
-			}
-		}
+		name := openerName(text, open)
 		if name == "" {
 			continue
 		}
-		if _, bounded := rawHeadingTitleEnds(text[open[1]:], name); !bounded {
+		if _, bounded := bounds.titleEnds(open[1], name, budget); !bounded {
 			return line + 1, true
 		}
 	}
diff --git a/internal/core/reading/project_test.go b/internal/core/reading/project_test.go
index b9f121794..ef9297bbe 100644
--- a/internal/core/reading/project_test.go
+++ b/internal/core/reading/project_test.go
@@ -1,6 +1,7 @@
 package reading
 
 import (
+	"slices"
 	"strings"
 	"testing"
 	"time"
@@ -67,28 +68,108 @@ func TestAttributeMaskStaysOnItsOwnLine(t *testing.T) {
 	}
 }
 
-// TestRawHeadingScanStaysLinearInTheOpenerCount: the bound scan materialised
-// every candidate bound in the whole remainder of the document for every heading
-// opener, though it breaks at the first hard one. That is quadratic with a large
-// constant, and a committed markdown file up to the size cap the assembler sets
-// did not finish — a silent hang, which is the one staging a fail-closed floor
-// cannot afford. The bound is generous: the walk is milliseconds and the
-// materialising scan was minutes.
+// TestRawHeadingScanStaysLinearInTheOpenerCount: the raw heading scan finishes
+// in time linear in the document over every shape of opener run, not only the
+// cheap one.
+//
+// Three shapes, because each was once the expensive one:
+//
+//   - openers that each close at once. The bound scan materialised every
+//     candidate bound in the whole remainder for every opener, and a committed
+//     markdown file up to the size cap did not finish. At the cap the line each
+//     opener names was also counted from the top of the document, once per
+//     opener.
+//   - openers that never close, with no h-tag and no blank line anywhere
+//     (iss-2608301421382564). Each title ran to the end of the document, so the
+//     scan rendered the whole remainder once per opener: 4 000 openers took
+//     13.5 s and 8 000 took 57 s, where the closed shape above took 0.1 s. The
+//     test covered only the closed shape, so its name over-claimed.
+//   - openers that all share one bound far below them. Each title is bounded,
+//     so nothing refuses the shape as unbounded, and each is still read over
+//     most of the document.
+//
+// The last two are refusals as well as costs: a title that is never bounded is
+// refused rather than read, and titles that overlap past the floor's read budget
+// are refused rather than read in quadratic time. The bound is generous: the
+// linear scan is milliseconds. It is not asserted under -race (raceEnabled),
+// where the verdicts still are.
 func TestRawHeadingScanStaysLinearInTheOpenerCount(t *testing.T) {
-	var b strings.Builder
-	b.WriteString("# A spec\n\n")
-	for range 8000 {
-		b.WriteString("<h2>Ordinary heading</h2>\n")
-	}
-	doc := b.String()
 	headings := map[string]bool{"Audit Notes": true}
-	start := time.Now()
-	if err := verifyRedaction("spc-x.md", doc, doc, nil, headings); err != nil {
-		t.Fatalf("the scan refused an ordinary document: %v", err)
+	build := func(opener string, n int, tail string) string {
+		var b strings.Builder
+		b.WriteString("# A spec\n\n")
+		for range n {
+			b.WriteString(opener)
+		}
+		b.WriteString(tail)
+		return b.String()
+	}
+	closedAtCap := (MaxFileBytes - 64) / len("<h2>Ordinary heading</h2>\n")
+	cases := []struct {
+		name   string
+		doc    string
+		refuse string
+	}{
+		{"closed openers up to the size cap", build("<h2>Ordinary heading</h2>\n", closedAtCap, ""), ""},
+		{"unclosed openers with no bound", build(`<p role="heading">x`, 8000, ""), "never closed"},
+		{"unclosed openers sharing one far bound", build(`<p role="heading">x`, 8000, "</p>\n"), "read budget"},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			start := time.Now()
+			err := verifyRedaction("spc-x.md", c.doc, c.doc, nil, headings)
+			elapsed := time.Since(start)
+			switch {
+			case c.refuse == "" && err != nil:
+				t.Fatalf("the scan refused an ordinary document: %v", err)
+			case c.refuse != "" && err == nil:
+				t.Fatalf("the scan admitted a run of openers it cannot read in linear time")
+			case c.refuse != "" && !strings.Contains(err.Error(), c.refuse):
+				t.Errorf("the refusal does not name %q: %v", c.refuse, err)
+			}
+			if !raceEnabled && elapsed > 10*time.Second {
+				t.Errorf("the raw heading scan took %s over a %d-byte document; it reads each "+
+					"title over the remainder, or counts each line from the top", elapsed, len(c.doc))
+			}
+		})
 	}
-	if elapsed := time.Since(start); elapsed > 10*time.Second {
-		t.Errorf("the raw heading scan took %s over %d openers; it materialises the whole "+
-			"bound list per opener", elapsed, 8000)
+}
+
+// TestIndexedHeadingBoundsAgreeWithTheWalk: the bound index answers exactly what
+// the walk from each opener answered, in every reading the scan takes, including
+// the masked reading where an opener's own `>` is blanked and a bound match can
+// straddle it — the one case the index hands back to the walk — and including
+// element names that fold under Go's case folding but not under lower-casing
+// (the long s, the Kelvin sign).
+func TestIndexedHeadingBoundsAgreeWithTheWalk(t *testing.T) {
+	docs := []string{
+		"<h2>Audit Notes</h2>\n\n<h3><em>x</em> y</h3>",
+		"<h2>\n\nAudit Notes</h2>\n<h2>never closed\n",
+		"<p role=\"heading\">a</P><div role=heading>b\n\nc</div><h4 id=x>d",
+		"<h2 title=\"<h3>\"\n\n>Audit Notes</h2>",
+		"<!--\n<h2\n>\n--> <h2>x</h2>",
+		"<!-- <h2>a <h3>b --> <h2>c\n\n</h2>",
+		"<\u017fpan role=\"heading\">Audit Notes</span> <bloc\u212a role=heading>x</block>",
+		"<h2 a=\"x\ny\">z</h2>\r\n\r\n<h1>w",
+	}
+	for _, doc := range docs {
+		lineBounded, _ := maskMarkupData(doc, true)
+		unbounded, _ := maskMarkupData(doc, false)
+		readings := []string{doc, lineBounded, unbounded}
+		for _, found := range readings {
+			for _, open := range rawHeadingOpenRe.FindAllStringSubmatchIndex(found, -1) {
+				name := openerName(found, open)
+				for _, r := range readings {
+					budget := newTitleReadBudget(len(r))
+					got, gotBounded := indexRawHeadingBounds(r).titleEnds(open[1], name, budget)
+					want, wantBounded, _ := walkRawHeadingBounds(r[open[1]:], name)
+					if !slices.Equal(got, want) || gotBounded != wantBounded {
+						t.Errorf("opener %q at %d over %q: the index says %v (bounded %v), the walk %v (bounded %v)",
+							found[open[0]:open[1]], open[1], r, got, gotBounded, want, wantBounded)
+					}
+				}
+			}
+		}
 	}
 }
 
diff --git a/internal/core/reading/race_off_test.go b/internal/core/reading/race_off_test.go
new file mode 100644
index 000000000..28ba133d2
--- /dev/null
+++ b/internal/core/reading/race_off_test.go
@@ -0,0 +1,12 @@
+//go:build !race
+
+package reading
+
+// raceEnabled reports whether the race detector is instrumenting this build.
+// The linearity guards read it and assert no wall-clock bound under -race: the
+// instrumented run multiplies the cost many times over (23.7 s against 1.1 s for
+// the size-cap case), so a bound set for the plain lane fails there on linear
+// code, and a bound loose enough for both would not catch the quadratic shape.
+// The verdicts are still asserted. A build tag answers at compile time, the
+// mechanism core/adapter/scanner uses for its cost guards.
+const raceEnabled = false
diff --git a/internal/core/reading/race_on_test.go b/internal/core/reading/race_on_test.go
new file mode 100644
index 000000000..e66470402
--- /dev/null
+++ b/internal/core/reading/race_on_test.go
@@ -0,0 +1,7 @@
+//go:build race
+
+package reading
+
+// raceEnabled reports whether the race detector is instrumenting this build.
+// See the sibling file for what reads it.
+const raceEnabled = true
diff --git a/internal/core/record/match/config.go b/internal/core/record/match/config.go
new file mode 100644
index 000000000..1dad86c89
--- /dev/null
+++ b/internal/core/record/match/config.go
@@ -0,0 +1,102 @@
+package match
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/intentdriven/abcd/internal/core/layered"
+)
+
+// The compared fields: which text of each candidate family the match reads.
+// The set is closed; a name outside it is refused, never ignored.
+const (
+	// FieldIssueBody is an open or resolved issue's markdown body.
+	FieldIssueBody = "issue.body"
+	// FieldIntentTitle is an intent's H1.
+	FieldIntentTitle = "intent.title"
+	// FieldIntentPressRelease is an intent's `## Press Release` section.
+	FieldIntentPressRelease = "intent.press_release"
+)
+
+// DefaultFields is the bundled match.fields: every field in the set.
+var DefaultFields = []string{FieldIssueBody, FieldIntentTitle, FieldIntentPressRelease}
+
+var knownFields = map[string]bool{FieldIssueBody: true, FieldIntentTitle: true, FieldIntentPressRelease: true}
+
+// Config is the resolved match configuration, with the origin of each value
+// (the layered resolver's: "bundled", a file, or a flag), so a surface can say
+// where a threshold came from.
+type Config struct {
+	Threshold       float64  `json:"threshold"`
+	ThresholdOrigin string   `json:"threshold_origin"`
+	Fields          []string `json:"fields"`
+	FieldsOrigin    string   `json:"fields_origin"`
+}
+
+// Bundled is the configuration when nothing is configured.
+func Bundled() Config {
+	return Config{
+		Threshold: DefaultThreshold, ThresholdOrigin: "bundled",
+		Fields: append([]string(nil), DefaultFields...), FieldsOrigin: "bundled",
+	}
+}
+
+// Compares reports whether the configuration reads field.
+func (c Config) Compares(field string) bool {
+	for _, f := range c.Fields {
+		if f == field {
+			return true
+		}
+	}
+	return false
+}
+
+// LoadConfig resolves match.threshold and match.fields through the one layered
+// configuration reader (.abcd/config.json, then ~/.abcd/config.json, then the
+// bundled defaults). It claims the `match` namespace, so a misspelt key is
+// refused rather than letting a default apply unannounced, and a value outside
+// its range or set is refused naming its file, never replaced by the default.
+func LoadConfig(r layered.Roots) (Config, error) {
+	s, err := layered.Load(layered.Config, r)
+	if err != nil {
+		return Config{}, err
+	}
+	if err := s.Claim("match", "threshold", "fields"); err != nil {
+		return Config{}, err
+	}
+	th, err := layered.Get(s, "match.threshold", DefaultThreshold, func(v float64) error {
+		if !(v > 0 && v <= 1) {
+			return fmt.Errorf("want a share of the new text's terms greater than 0 and at most 1")
+		}
+		return nil
+	})
+	if err != nil {
+		return Config{}, err
+	}
+	fields, err := layered.Get(s, "match.fields", append([]string(nil), DefaultFields...), checkFields)
+	if err != nil {
+		return Config{}, err
+	}
+	return Config{
+		Threshold: th.V, ThresholdOrigin: th.Origin,
+		Fields: fields.V, FieldsOrigin: fields.Origin,
+	}, nil
+}
+
+func checkFields(fs []string) error {
+	accepted := strings.Join(DefaultFields, ", ")
+	if len(fs) == 0 {
+		return fmt.Errorf("want at least one of %s", accepted)
+	}
+	seen := map[string]bool{}
+	for _, f := range fs {
+		if !knownFields[f] {
+			return fmt.Errorf("%q is not a compared field; want one or more of %s", layered.BoundKey(f), accepted)
+		}
+		if seen[f] {
+			return fmt.Errorf("%q is named twice", f)
+		}
+		seen[f] = true
+	}
+	return nil
+}
diff --git a/internal/core/record/match/config_test.go b/internal/core/record/match/config_test.go
new file mode 100644
index 000000000..f690ac0b8
--- /dev/null
+++ b/internal/core/record/match/config_test.go
@@ -0,0 +1,91 @@
+package match
+
+import (
+	"os"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"testing"
+
+	"github.com/intentdriven/abcd/internal/core/layered"
+)
+
+// roots lays a checkout and a home under one temp dir, writing the repository
+// and machine config files when given (0o600, which the machine layer's
+// declaration guard admits).
+func roots(t *testing.T, repoJSON, machineJSON string) layered.Roots {
+	t.Helper()
+	base := t.TempDir()
+	r := layered.Roots{Repo: filepath.Join(base, "repo"), Home: filepath.Join(base, "home")}
+	put := func(p, body string) {
+		if err := os.MkdirAll(filepath.Dir(p), 0o700); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(p, []byte(body), 0o600); err != nil {
+			t.Fatal(err)
+		}
+	}
+	if err := os.MkdirAll(r.Repo, 0o700); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.MkdirAll(r.Home, 0o700); err != nil {
+		t.Fatal(err)
+	}
+	if repoJSON != "" {
+		put(filepath.Join(r.Repo, ".abcd", "config.json"), repoJSON)
+	}
+	if machineJSON != "" {
+		put(filepath.Join(r.Home, ".abcd", "config.json"), machineJSON)
+	}
+	return r
+}
+
+func TestConfigDefaultsWhenNothingIsConfigured(t *testing.T) {
+	c, err := LoadConfig(roots(t, `{"docs":{"target":"agents_md"}}`, ""))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if c.Threshold != DefaultThreshold || !reflect.DeepEqual(c.Fields, DefaultFields) {
+		t.Fatalf("config = %+v, want the bundled defaults", c)
+	}
+	if c.ThresholdOrigin != "bundled" || c.FieldsOrigin != "bundled" {
+		t.Fatalf("origins = %q / %q, want bundled", c.ThresholdOrigin, c.FieldsOrigin)
+	}
+}
+
+func TestConfigReadsThroughTheLayers(t *testing.T) {
+	c, err := LoadConfig(roots(t,
+		`{"match":{"threshold":0.75}}`,
+		`{"match":{"threshold":0.9,"fields":["issue.body"]}}`))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if c.Threshold != 0.75 || c.ThresholdOrigin != ".abcd/config.json" {
+		t.Fatalf("threshold %v from %q, want 0.75 from the repo file", c.Threshold, c.ThresholdOrigin)
+	}
+	if !reflect.DeepEqual(c.Fields, []string{"issue.body"}) || c.FieldsOrigin != "~/.abcd/config.json" {
+		t.Fatalf("fields %v from %q, want [issue.body] from the machine file", c.Fields, c.FieldsOrigin)
+	}
+	if !c.Compares(FieldIssueBody) || c.Compares(FieldIntentTitle) {
+		t.Fatalf("Compares disagrees with fields %v", c.Fields)
+	}
+}
+
+func TestConfigRefusesWhatWouldSilentlyDoLess(t *testing.T) {
+	cases := map[string]string{
+		`{"match":{"treshold":0.7}}`:                          "match.treshold",
+		`{"match":{"threshold":0}}`:                           "threshold",
+		`{"match":{"threshold":1.5}}`:                         "threshold",
+		`{"match":{"threshold":"high"}}`:                      "threshold",
+		`{"match":{"fields":[]}}`:                             "fields",
+		`{"match":{"fields":["issue.title"]}}`:                "issue.title",
+		`{"match":{"fields":["issue.body","issue.body"]}}`:    "twice",
+		`{"match":{"fields":["intent.title","intent.body"]}}`: "intent.body",
+	}
+	for repo, want := range cases {
+		_, err := LoadConfig(roots(t, repo, ""))
+		if err == nil || !strings.Contains(err.Error(), want) {
+			t.Errorf("%s: err = %v, want a refusal naming %q", repo, err, want)
+		}
+	}
+}
diff --git a/internal/core/record/match/discipline_test.go b/internal/core/record/match/discipline_test.go
new file mode 100644
index 000000000..34d78e10e
--- /dev/null
+++ b/internal/core/record/match/discipline_test.go
@@ -0,0 +1,40 @@
+package match
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// The itd-84 discipline names a capture-time validator as its next rung; the
+// record this package delivers marks that rung delivered (criterion 5 of
+// itd-2609212137116617). The test reads the committed discipline record, so a
+// later edit that drops the mark fails here rather than leaving the rung
+// reading as unbuilt.
+func TestTheDisciplineRecordsTheDeliveredRung(t *testing.T) {
+	dir, err := os.Getwd()
+	if err != nil {
+		t.Fatal(err)
+	}
+	for {
+		if _, err := os.Stat(filepath.Join(dir, "go.mod")); err == nil {
+			break
+		}
+		parent := filepath.Dir(dir)
+		if parent == dir {
+			t.Fatal("no go.mod above the package directory")
+		}
+		dir = parent
+	}
+	b, err := os.ReadFile(filepath.Join(dir, ".abcd/development/intents/disciplines/itd-84-intent-decomposition.md"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	s := string(b)
+	for _, want := range []string{"**Delivered rung: the capture-time candidate pass.**", "itd-2609212137116617", "duplicates", "refines"} {
+		if !strings.Contains(s, want) {
+			t.Fatalf("itd-84 does not carry %q: the capture-time candidate pass does not read as delivered", want)
+		}
+	}
+}
diff --git a/internal/core/record/match/match.go b/internal/core/record/match/match.go
new file mode 100644
index 000000000..4b57d40f0
--- /dev/null
+++ b/internal/core/record/match/match.go
@@ -0,0 +1,340 @@
+// Package match is the canonical term-overlap primitive: it scores how much of
+// a new text another record already holds, by the words the two share, and
+// classifies a likely double as `duplicates` (near-identical) or `refines`
+// (narrower). It is a lexical HEURISTIC and says so on every result it returns
+// (Heuristic): no model is consulted, nothing semantic is claimed, and a match
+// is a proposal a person confirms or removes (itd-2609212137116617).
+//
+// It is the one home of the overlap score (the one-canonical-primitive rule):
+// the filing-time match of `capture` and of the quoted-text `intent` create
+// call it, and any later ranking by shared terms (the embark ranking the
+// reflect spec names) calls it rather than growing a copy. It sits below the
+// record dispatcher rather than inside it because the dispatcher reads the
+// capture and intent stores, and both of those call this package; a leaf
+// package is what lets every caller reach it without an import cycle.
+//
+// The scorer reads nothing, writes nothing and never prints; the one read in
+// the package is LoadConfig, through the layered configuration reader. Its
+// callers gather the candidate texts under their own locks and write the
+// links.
+package match
+
+import (
+	"math"
+	"sort"
+	"strings"
+	"unicode"
+)
+
+// Heuristic names the method on every outcome, so a surface never renders a
+// score as more than it is.
+const Heuristic = "lexical term overlap, weighted by how rare each term is across the candidates; a heuristic, not a judgement"
+
+// Relation is the typed link a match writes. The vocabulary is the itd-84
+// discipline's (supersedes / reverses / duplicates / refines); a lexical
+// score can only ever propose the two below. A reversal or a supersession is a
+// judgement about meaning, which the discipline keeps advisory and human, so
+// this package never proposes either.
+type Relation string
+
+const (
+	// Duplicates: the two texts hold each other's terms, both ways.
+	Duplicates Relation = "duplicates"
+	// Refines: the candidate holds the new text's terms, and carries a good
+	// deal more besides — the new record is the narrower of the two.
+	Refines Relation = "refines"
+)
+
+// Bundled defaults. The threshold is configuration (the layered resolver's
+// match.threshold); the rest are declared constants of the heuristic.
+const (
+	// DefaultThreshold is the weighted share of the new text's terms a
+	// candidate must hold for a link to be written. It was read off this
+	// repository's own ledger on 2026-09-26: each of the 449 open issues was
+	// matched against the other 1,660 issues and intents, and 14 cleared 0.6.
+	// Most of those were the same finding filed twice or a narrower follow-up
+	// of an earlier one; the false ones shared a relocation footer rather than
+	// a finding. Below 0.6 the best pairs stop being the same finding.
+	DefaultThreshold = 0.6
+	// MinTerms is the fewest distinct terms a new text needs before it is
+	// compared at all. Below it the overlap of a line or two is chance, so the
+	// record is filed without matching and the outcome says so (the intent's
+	// scope condition).
+	MinTerms = 8
+	// MaxLinks caps the links one filing writes. A text that clears the
+	// threshold against more candidates than this links the highest scorers;
+	// the rest are still listed, so nothing is hidden.
+	MaxLinks = 3
+	// NearMissLimit caps how many below-threshold candidates an outcome lists.
+	NearMissLimit = 5
+	// sharedLimit caps the shared terms shown per scored candidate.
+	sharedLimit = 8
+	// minTermRunes is the shortest token that counts as a term.
+	minTermRunes = 3
+)
+
+// Candidate is one existing record's comparable text.
+type Candidate struct {
+	ID   string
+	Text string
+}
+
+// Score is one candidate's result.
+type Score struct {
+	ID string `json:"id"`
+	// Score is the weighted share of the NEW text's terms this candidate holds,
+	// in [0, 1] and rounded to three places. It is what the threshold compares.
+	Score float64 `json:"score"`
+	// Reverse is the weighted share of the CANDIDATE's terms the new text
+	// holds: high both ways is a duplicate, high one way a refinement.
+	Reverse float64 `json:"reverse"`
+	// Relation is set on a match above the threshold, and empty on a near miss.
+	Relation Relation `json:"relation,omitempty"`
+	// Linked is true when the writer wrote this match onto the record: every
+	// match up to MaxLinks.
+	Linked bool `json:"linked"`
+	// Shared are the rarest terms the two have in common, the evidence a person
+	// reads before confirming or removing the link.
+	Shared []string `json:"shared_terms"`
+}
+
+// Outcome is one text matched against a candidate set.
+type Outcome struct {
+	Heuristic string  `json:"heuristic"`
+	Threshold float64 `json:"threshold"`
+	// Terms is the number of distinct terms the new text carries.
+	Terms    int `json:"terms"`
+	MinTerms int `json:"min_terms"`
+	// Compared is the number of candidates scored.
+	Compared int `json:"compared"`
+	// Skipped says why no candidate was compared; empty when matching ran.
+	Skipped string `json:"skipped,omitempty"`
+	// Matches are the candidates at or above the threshold, best first.
+	Matches []Score `json:"matches"`
+	// NearMisses are the best candidates below it, with their scores.
+	NearMisses []Score `json:"near_misses"`
+}
+
+// Links returns the typed links an outcome writes, relation → ids, best first.
+func (o Outcome) Links() map[Relation][]string {
+	out := map[Relation][]string{}
+	for _, m := range o.Matches {
+		if m.Linked {
+			out[m.Relation] = append(out[m.Relation], m.ID)
+		}
+	}
+	return out
+}
+
+// stopwords are the English function words that carry no finding. The list is
+// short on purpose: domain words common to this record ("record", "intent")
+// are discounted by their weight, not by a list.
+var stopwords = func() map[string]bool {
+	m := map[string]bool{}
+	for _, w := range strings.Fields(`the and for are but not you all any can had her was one our out has
+		have been from they this that with which when what where who will would there their them then than
+		into onto its it's also only such each more most some very just over under about after before
+		because while does did doing done being were should could may might must shall these those here
+		upon via per nor yet both either neither own same other again once why how off too`) {
+		m[w] = true
+	}
+	return m
+}()
+
+// Terms is the canonical tokeniser: lower-cased runs of letters and digits,
+// at least three runes long, neither a stop word nor all digits (a count, a
+// date or a record number says nothing about what a finding is), each once,
+// sorted.
+func Terms(text string) []string {
+	seen := map[string]bool{}
+	var out []string
+	flush := func(b *strings.Builder) {
+		t := b.String()
+		b.Reset()
+		if len([]rune(t)) < minTermRunes || stopwords[t] || allDigits(t) || seen[t] {
+			return
+		}
+		seen[t] = true
+		out = append(out, t)
+	}
+	var b strings.Builder
+	for _, r := range text {
+		if unicode.IsLetter(r) || unicode.IsDigit(r) {
+			b.WriteRune(unicode.ToLower(r))
+			continue
+		}
+		flush(&b)
+	}
+	flush(&b)
+	sort.Strings(out)
+	return out
+}
+
+func allDigits(s string) bool {
+	for _, r := range s {
+		if !unicode.IsDigit(r) {
+			return false
+		}
+	}
+	return true
+}
+
+// Weights is the rarity weight of every term across a candidate set: a term
+// few candidates carry says more about a text than one most of them carry. A
+// term no candidate carries takes the highest weight.
+type Weights struct {
+	df map[string]int
+	n  int
+}
+
+// NewWeights counts, per term, how many of the term sets carry it.
+func NewWeights(sets [][]string) Weights {
+	w := Weights{df: map[string]int{}, n: len(sets)}
+	for _, s := range sets {
+		for _, t := range s {
+			w.df[t]++
+		}
+	}
+	return w
+}
+
+// Of is a term's weight: a smoothed inverse document frequency, always > 0.
+func (w Weights) Of(term string) float64 {
+	return math.Log(float64(w.n+1)/float64(w.df[term]+1)) + 1
+}
+
+// Overlap is THE overlap score: the weighted share of a's terms that b holds
+// (forward), the weighted share of b's terms that a holds (reverse), and the
+// shared terms, rarest first. Both inputs are sorted term sets (Terms).
+func Overlap(a, b []string, w Weights) (forward, reverse float64, shared []string) {
+	var wa, wb, ws float64
+	i, j := 0, 0
+	for _, t := range a {
+		wa += w.Of(t)
+	}
+	for _, t := range b {
+		wb += w.Of(t)
+	}
+	for i < len(a) && j < len(b) {
+		switch {
+		case a[i] == b[j]:
+			ws += w.Of(a[i])
+			shared = append(shared, a[i])
+			i++
+			j++
+		case a[i] < b[j]:
+			i++
+		default:
+			j++
+		}
+	}
+	if wa > 0 {
+		forward = ws / wa
+	}
+	if wb > 0 {
+		reverse = ws / wb
+	}
+	sort.SliceStable(shared, func(x, y int) bool {
+		wx, wy := w.Of(shared[x]), w.Of(shared[y])
+		if wx != wy {
+			return wx > wy
+		}
+		return shared[x] < shared[y]
+	})
+	return forward, reverse, shared
+}
+
+// Short reports whether text carries fewer distinct terms than MinTerms, so a
+// caller can file it without gathering any candidates: Rank would compare
+// nothing anyway.
+func Short(text string) bool { return len(Terms(text)) < MinTerms }
+
+// Rank matches text against every candidate. A threshold outside (0, 1] is
+// the caller's fault and reads as the bundled default, so a matcher can never
+// be configured into linking everything or nothing by accident; the layered
+// reader refuses such a value before it gets here.
+func Rank(text string, cands []Candidate, threshold float64) Outcome {
+	if !(threshold > 0 && threshold <= 1) {
+		threshold = DefaultThreshold
+	}
+	terms := Terms(text)
+	o := Outcome{
+		Heuristic: Heuristic, Threshold: threshold, Terms: len(terms), MinTerms: MinTerms,
+		Matches: []Score{}, NearMisses: []Score{},
+	}
+	if len(terms) < MinTerms {
+		o.Skipped = "the text carries fewer distinct terms than the declared minimum, so it is filed without matching"
+		return o
+	}
+	if len(cands) == 0 {
+		o.Skipped = "there is no record to compare it with"
+		return o
+	}
+	sets := make([][]string, len(cands))
+	for i, c := range cands {
+		sets[i] = Terms(c.Text)
+	}
+	w := NewWeights(sets)
+	var scored []Score
+	for i, c := range cands {
+		if len(sets[i]) == 0 {
+			continue
+		}
+		o.Compared++
+		fwd, rev, shared := Overlap(terms, sets[i], w)
+		if len(shared) == 0 {
+			continue
+		}
+		if len(shared) > sharedLimit {
+			shared = shared[:sharedLimit]
+		}
+		// The rounded values are the ones compared, so a score shown as 0.6 is
+		// never a near miss of a 0.6 threshold.
+		s := Score{ID: c.ID, Score: round3(fwd), Reverse: round3(rev), Shared: shared}
+		if s.Score >= threshold {
+			s.Relation = Refines
+			if s.Reverse >= threshold {
+				s.Relation = Duplicates
+			}
+		}
+		scored = append(scored, s)
+	}
+	sort.SliceStable(scored, func(i, j int) bool {
+		if scored[i].Score != scored[j].Score {
+			return scored[i].Score > scored[j].Score
+		}
+		return scored[i].ID < scored[j].ID
+	})
+	for _, s := range scored {
+		if s.Relation != "" {
+			s.Linked = len(o.Matches) < MaxLinks
+			o.Matches = append(o.Matches, s)
+			continue
+		}
+		if len(o.NearMisses) < NearMissLimit {
+			o.NearMisses = append(o.NearMisses, s)
+		}
+	}
+	return o
+}
+
+func round3(f float64) float64 { return math.Round(f*1000) / 1000 }
+
+// Unread is the outcome of a match whose candidate set could not be read: the
+// record is filed without matching, and the reason travels with the outcome
+// rather than refusing the write.
+func Unread(threshold float64, err error) Outcome {
+	return Skip(threshold, "the record could not be read for matching ("+err.Error()+"), so it is filed without matching")
+}
+
+// Skip is the outcome of a match that compared nothing, for the reason given:
+// the filing goes ahead, and the reason is what a surface says.
+func Skip(threshold float64, reason string) Outcome {
+	if !(threshold > 0 && threshold <= 1) {
+		threshold = DefaultThreshold
+	}
+	return Outcome{
+		Heuristic: Heuristic, Threshold: threshold, MinTerms: MinTerms,
+		Skipped: reason, Matches: []Score{}, NearMisses: []Score{},
+	}
+}
diff --git a/internal/core/record/match/match_test.go b/internal/core/record/match/match_test.go
new file mode 100644
index 000000000..58afb90a9
--- /dev/null
+++ b/internal/core/record/match/match_test.go
@@ -0,0 +1,168 @@
+package match
+
+import (
+	"reflect"
+	"strings"
+	"testing"
+)
+
+// The fixtures read like ledger records: a finding, a near-identical refiling
+// of it, a narrower follow-up of a broader one, and records about something
+// else entirely.
+const (
+	finding = "The capture ledger reader silently skips a record whose frontmatter carries " +
+		"a duplicated key, so the finding disappears from every listing without a warning."
+	refiled = "Capture ledger reader silently skips any record whose frontmatter carries a " +
+		"duplicated key: the finding disappears from every listing, and no warning is printed."
+	broad = "Record readers disagree with the lint gate. The capture ledger reader skips " +
+		"records with duplicated frontmatter keys, the intent loader fails closed on a missing id, " +
+		"the spec store tolerates unknown properties, the site builder renders stale anchors, " +
+		"the memory store truncates pages, and the history store drops transcripts over its budget."
+	narrow = "The capture ledger reader skips records with duplicated frontmatter keys " +
+		"while the lint gate reports them."
+	unrelated1 = "The site builder renders a stale anchor for a heading renamed since the last build."
+	unrelated2 = "The history store drops a transcript that exceeds its byte budget without saying so."
+	unrelated3 = "The guard refuses a shell command whose here-document is never terminated."
+)
+
+func corpus(extra ...Candidate) []Candidate {
+	return append([]Candidate{
+		{ID: "iss-11", Text: unrelated1},
+		{ID: "iss-12", Text: unrelated2},
+		{ID: "itd-13", Text: unrelated3},
+	}, extra...)
+}
+
+func TestTermsIsTheCanonicalTokeniser(t *testing.T) {
+	got := Terms("The CAPTURE ledger, the capture Ledger: 2026 iss-42 a to é-dit x1y")
+	want := []string{"capture", "dit", "iss", "ledger", "x1y"}
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("Terms = %v, want %v (lower-cased, deduplicated, sorted; stop words, "+
+			"short tokens and all-digit tokens dropped)", got, want)
+	}
+}
+
+func TestOverlapIsDirectional(t *testing.T) {
+	a := Terms("alpha bravo charlie")
+	b := Terms("alpha bravo charlie delta echo foxtrot")
+	w := NewWeights([][]string{a, b})
+	fwd, rev, shared := Overlap(a, b, w)
+	if fwd != 1 {
+		t.Fatalf("forward = %v, want 1: b holds every term of a", fwd)
+	}
+	if rev >= 1 || rev <= 0 {
+		t.Fatalf("reverse = %v, want strictly between 0 and 1", rev)
+	}
+	if len(shared) != 3 {
+		t.Fatalf("shared = %v, want the three common terms", shared)
+	}
+}
+
+func TestANearIdenticalTextIsADuplicate(t *testing.T) {
+	o := Rank(refiled, corpus(Candidate{ID: "iss-7", Text: finding}), DefaultThreshold)
+	if o.Skipped != "" {
+		t.Fatalf("skipped: %s", o.Skipped)
+	}
+	if len(o.Matches) != 1 || o.Matches[0].ID != "iss-7" || o.Matches[0].Relation != Duplicates || !o.Matches[0].Linked {
+		t.Fatalf("matches = %+v, want iss-7 linked as duplicates", o.Matches)
+	}
+	if got := o.Links(); !reflect.DeepEqual(got, map[Relation][]string{Duplicates: {"iss-7"}}) {
+		t.Fatalf("links = %v", got)
+	}
+	if o.Heuristic == "" || !strings.Contains(o.Heuristic, "heuristic") {
+		t.Fatalf("the outcome does not declare itself a heuristic: %q", o.Heuristic)
+	}
+}
+
+func TestANarrowerTextRefinesTheBroaderOne(t *testing.T) {
+	o := Rank(narrow, corpus(Candidate{ID: "itd-9", Text: broad}), DefaultThreshold)
+	if len(o.Matches) != 1 || o.Matches[0].ID != "itd-9" || o.Matches[0].Relation != Refines {
+		t.Fatalf("matches = %+v, want itd-9 as refines", o.Matches)
+	}
+	if o.Matches[0].Score < DefaultThreshold || o.Matches[0].Reverse >= DefaultThreshold {
+		t.Fatalf("score %v / reverse %v: a refinement is high one way and low the other",
+			o.Matches[0].Score, o.Matches[0].Reverse)
+	}
+}
+
+func TestBelowTheThresholdNothingLinksAndTheNearMissesCarryScores(t *testing.T) {
+	o := Rank(finding, corpus(), DefaultThreshold)
+	if len(o.Matches) != 0 {
+		t.Fatalf("unrelated records matched: %+v", o.Matches)
+	}
+	if len(o.Links()) != 0 {
+		t.Fatalf("links written below the threshold: %v", o.Links())
+	}
+	if len(o.NearMisses) == 0 {
+		t.Fatal("no near misses listed, though the unrelated records share terms with the text")
+	}
+	for _, nm := range o.NearMisses {
+		if nm.Score <= 0 || nm.Score >= DefaultThreshold || nm.Relation != "" || nm.Linked {
+			t.Fatalf("near miss %+v: want a score in (0, threshold), no relation, not linked", nm)
+		}
+	}
+	if o.Compared != 3 {
+		t.Fatalf("compared = %d, want 3", o.Compared)
+	}
+}
+
+func TestTheThresholdIsHonoured(t *testing.T) {
+	// The same pair links at the default and does not at a threshold above
+	// its score: the threshold is the configuration, not a constant.
+	o := Rank(narrow, corpus(Candidate{ID: "itd-9", Text: broad}), DefaultThreshold)
+	s := o.Matches[0].Score
+	high := Rank(narrow, corpus(Candidate{ID: "itd-9", Text: broad}), s+0.01)
+	if len(high.Matches) != 0 || len(high.NearMisses) == 0 || high.NearMisses[0].ID != "itd-9" {
+		t.Fatalf("threshold %v: matches %+v near misses %+v", s+0.01, high.Matches, high.NearMisses)
+	}
+	if high.Threshold != s+0.01 {
+		t.Fatalf("outcome threshold = %v", high.Threshold)
+	}
+}
+
+func TestAnOutOfRangeThresholdReadsAsTheDefault(t *testing.T) {
+	for _, th := range []float64{0, -1, 1.5} {
+		if o := Rank(finding, corpus(), th); o.Threshold != DefaultThreshold {
+			t.Fatalf("threshold %v became %v, want the default", th, o.Threshold)
+		}
+	}
+}
+
+func TestAShortTextIsFiledWithoutMatchingAndSaysSo(t *testing.T) {
+	o := Rank("Typo in the ledger README.", corpus(Candidate{ID: "iss-7", Text: finding}), DefaultThreshold)
+	if o.Skipped == "" || !strings.Contains(o.Skipped, "minimum") {
+		t.Fatalf("skipped = %q, want the declared-minimum reason", o.Skipped)
+	}
+	if o.Compared != 0 || len(o.Matches) != 0 || len(o.NearMisses) != 0 {
+		t.Fatalf("a text below the minimum was compared: %+v", o)
+	}
+	if o.MinTerms != MinTerms || o.Terms >= MinTerms {
+		t.Fatalf("terms %d / min %d", o.Terms, o.MinTerms)
+	}
+}
+
+func TestAnEmptyCorpusSaysSo(t *testing.T) {
+	if o := Rank(finding, nil, DefaultThreshold); o.Skipped == "" {
+		t.Fatal("an empty candidate set was not reported")
+	}
+}
+
+func TestLinksAreCappedAndTheRestStillListed(t *testing.T) {
+	var extra []Candidate
+	for _, id := range []string{"iss-1", "iss-2", "iss-3", "iss-4", "iss-5"} {
+		extra = append(extra, Candidate{ID: id, Text: finding})
+	}
+	o := Rank(refiled, corpus(extra...), DefaultThreshold)
+	if len(o.Matches) != 5 {
+		t.Fatalf("matches = %d, want all 5 listed", len(o.Matches))
+	}
+	linked := 0
+	for _, m := range o.Matches {
+		if m.Linked {
+			linked++
+		}
+	}
+	if linked != MaxLinks || len(o.Links()[Duplicates]) != MaxLinks {
+		t.Fatalf("linked = %d, want MaxLinks (%d)", linked, MaxLinks)
+	}
+}
diff --git a/internal/core/site/assets.go b/internal/core/site/assets.go
index fdb4383e4..3b6bae336 100644
--- a/internal/core/site/assets.go
+++ b/internal/core/site/assets.go
@@ -397,8 +397,8 @@ func (a *assetPipe) Copies() [][2]string {
 // resolves the way a reader on GitHub sees it.
 func (a *assetPipe) render(pageDir, src, alt string, at Source) (string, error) {
 	if strings.HasPrefix(src, "http://") || strings.HasPrefix(src, "https://") || strings.HasPrefix(src, "data:") {
-		return "", &UnsupportedError{at.Path, at.Line, "remote image",
-			"every picture is a committed asset under docs/assets/img/; " + quote(src) + " is fetched at render time"}
+		return "", &UnsupportedError{Path: at.Path, Line: at.Line, Construct: "remote image",
+			Detail: "every picture is a committed asset under docs/assets/img/; " + quote(src) + " is fetched at render time"}
 	}
 	rel := path.Clean(path.Join(pageDir, src))
 	if !fsutil.ValidRelPath(rel) {
diff --git a/internal/core/site/compose.go b/internal/core/site/compose.go
index 146e93150..cdedeea04 100644
--- a/internal/core/site/compose.go
+++ b/internal/core/site/compose.go
@@ -759,9 +759,6 @@ func leadIn(text string) (title, rest string, ok bool) {
 	return "", "", false
 }
 
-// isSpace reports whether a byte is markdown whitespace.
-func isSpace(c byte) bool { return c == ' ' || c == '\t' || c == '\n' || c == '\r' }
-
 // tablePortraits puts the role portraits above the column labels they name. The
 // portrait is not configured by asset name: the manifest names the PAGE the
 // roles live on, and each column label is matched to the section of that page
diff --git a/internal/core/site/markdown.go b/internal/core/site/markdown.go
index d667af8d5..4650e138b 100644
--- a/internal/core/site/markdown.go
+++ b/internal/core/site/markdown.go
@@ -1,108 +1,25 @@
 package site
 
-// The Markdown subset renderer.
+// The site renders repository prose through the Markdown subset renderer in
+// core/mdrender. The renderer lives there, outside this package, so the writers
+// of append-only record prose can ask it what it refuses before they write:
+// this package imports the record families that hold such prose, and they could
+// not import it back (iss-2608301646046226).
 //
-// The site renders repository prose, and the repository writes a small, stable
-// dialect: ATX headings, paragraphs, bold/italic/code spans, links, images,
-// fenced code, pipe tables, blockquotes and lists. That dialect is what this
-// renders, and everything else is a BUILD ERROR naming file and line.
-//
-// Refusing is the point. A renderer that passes an unknown construct through
-// unrendered publishes raw markdown to readers; a renderer that silently drops
-// it publishes a hole. Both are worse than a build that stops and says
-// "docs/explanation/roles.md:31 — reference link", because the fix for that is
-// one edit and the fix for a silent hole is noticing it exists.
+// What stays here is the site's side of the renderer: its interface strings,
+// which come from the site's closed allowlist, and the names this package's
+// other files already use for the renderer's types and helpers.
 
-import (
-	"fmt"
-	"regexp"
-	"strings"
-)
+import "github.com/intentdriven/abcd/internal/core/mdrender"
 
 // UnsupportedError is a markdown construct outside the rendered subset.
-type UnsupportedError struct {
-	Path      string
-	Line      int
-	Construct string
-	Detail    string
-}
-
-func (e *UnsupportedError) Error() string {
-	d := ""
-	if e.Detail != "" {
-		d = ": " + e.Detail
-	}
-	return fmt.Sprintf("%s:%d: unsupported markdown construct: %s%s — the site renders a fixed subset and never passes text through unrendered",
-		e.Path, e.Line, e.Construct, d)
-}
-
-var (
-	tableDelimRe   = regexp.MustCompile(`^\s*\|?\s*:?-{1,}:?\s*(\|\s*:?-{1,}:?\s*)*\|?\s*$`)
-	orderedItemRe  = regexp.MustCompile(`^(\d+)[.)]\s+(.*)$`)
-	setextRe       = regexp.MustCompile(`^\s{0,3}(=+|-{2,})\s*$`)
-	thematicRe     = regexp.MustCompile(`^\s{0,3}((\*\s*){3,}|(-\s*){3,}|(_\s*){3,})$`)
-	rawHTMLStartRe = regexp.MustCompile(`^\s*<[A-Za-z!/]`)
-	linkDefRe      = regexp.MustCompile(`^\s{0,3}\[([^\]]+)\]:\s*(\S+)\s*(".*"|'.*'|\(.*\))?\s*$`)
-	autolinkRe     = regexp.MustCompile(`^<([A-Za-z][A-Za-z0-9+.\-]{1,31}:[^<>\x00-\x20]*)>`)
-	emailAutoRe    = regexp.MustCompile(`^<([A-Za-z0-9.!#$%&'*+/=?^_` + "`" + `{|}~-]+@[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?(?:\.[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?)*)>`)
-	htmlTagRe      = regexp.MustCompile(`^</?([A-Za-z][A-Za-z0-9-]*)`)
-)
-
-// htmlElements is the set of names a `<…>` may carry and still be HTML.
-//
-// The distinction matters because the record writes angle brackets for two
-// different things. `<div>` is markup, and rendering it would let a record file
-// inject elements into a published page — that stays a refusal. `<ts>`,
-// `<file>` and `<number>` are PLACEHOLDERS in prose, and every generic HTML
-// sanitiser drops them silently, which is the one outcome worse than either
-// rendering or refusing: the sentence loses a word and nobody can tell. Those
-// are escaped and shown, so what the record wrote is what a reader sees.
-var htmlElements = map[string]bool{}
-
-func init() {
-	for _, n := range strings.Fields(`a abbr address area article aside audio b base bdi bdo blockquote body br
-button canvas caption cite code col colgroup data datalist dd del details dfn dialog div dl dt em embed
-fieldset figcaption figure footer form h1 h2 h3 h4 h5 h6 head header hgroup hr html i iframe img input ins
-kbd label legend li link main map mark menu meta meter nav noscript object ol optgroup option output p
-picture pre progress q rp rt ruby s samp script search section select slot small source span strong style
-sub summary sup table tbody td template textarea tfoot th thead time title tr track u ul var video wbr`) {
-		htmlElements[n] = true
-	}
-}
-
-// LinkDefinitions collects a document's link reference definitions — the
-// `[label]: destination "title"` lines the record's older entries keep at the
-// foot of a file and name from the prose above.
-//
-// They are document-level, and the renderer works a block at a time, so the
-// caller reads them once and hands them to the Renderer. A reference whose
-// definition is missing stays a refusal: the destination is lost either way,
-// and losing it silently is how a dead cross-reference survives review.
-func LinkDefinitions(md string) map[string]string {
-	defs := map[string]string{}
-	for _, line := range strings.Split(md, "\n") {
-		m := linkDefRe.FindStringSubmatch(line)
-		if m == nil {
-			continue
-		}
-		key := normaliseLabel(m[1])
-		if _, seen := defs[key]; !seen {
-			defs[key] = strings.Trim(m[2], "<>")
-		}
-	}
-	return defs
-}
+type UnsupportedError = mdrender.UnsupportedError
 
-// normaliseLabel folds a reference label the way every reader folds it: case
-// insensitively, with internal whitespace collapsed.
-func normaliseLabel(s string) string {
-	return strings.ToLower(strings.Join(strings.Fields(s), " "))
-}
+// Source is a position in a repository file.
+type Source = mdrender.Source
 
-// isLinkDefLine reports whether a line is nothing but a link reference
-// definition. A block made only of them renders as nothing, which is what it
-// means everywhere else.
-func isLinkDefLine(s string) bool { return linkDefRe.MatchString(s) }
+// Block is one top-level markdown block.
+type Block = mdrender.Block
 
 // Renderer turns the markdown subset into the site's HTML. Its two hooks are
 // the places the site differs from a generic renderer: an image becomes a
@@ -124,979 +41,49 @@ type Renderer struct {
 	Refs map[string]string
 }
 
-// Source is a position in a repository file.
-type Source struct {
-	Path string
-	Line int
-}
-
 // RenderBlocks renders a block sequence in order.
 func (r *Renderer) RenderBlocks(path string, blocks []Block) (string, error) {
-	var b strings.Builder
-	for _, blk := range blocks {
-		h, err := r.RenderBlock(path, blk)
-		if err != nil {
-			return "", err
-		}
-		b.WriteString(h)
-	}
-	return b.String(), nil
+	return r.subset().RenderBlocks(path, blocks)
 }
 
-// unrenderedFenceRe matches a fence opener the renderer does not render: a
-// tilde run, or a backtick run longer than three, at any indent.
-var unrenderedFenceRe = regexp.MustCompile("^[ \t]*(~{3,}|`{4,})")
-
 // RenderBlock renders one top-level block.
 func (r *Renderer) RenderBlock(path string, blk Block) (string, error) {
-	at := Source{Path: path, Line: blk.Line}
-	lines := strings.Split(blk.Text, "\n")
-	first := lines[0]
-
-	// The walk that cut this block reads fences by mdrecord's rule, tildes and
-	// longer backtick runs included, and this renderer renders one form: a
-	// three-backtick run at column 0. Any other form arriving here would render
-	// as a paragraph, delimiters and code inlined into prose, with no error, so
-	// it is refused. A three-backtick fence's own body is code and is not read
-	// (iss-2609251514129841).
-	if !strings.HasPrefix(first, "```") || strings.HasPrefix(first, "````") {
-		for i, ln := range lines {
-			if unrenderedFenceRe.MatchString(ln) {
-				return "", &UnsupportedError{at.Path, at.Line + i, "fenced code block opened by a tilde or a run of four or more backticks",
-					"only a three-backtick fence renders; any other opener renders as a paragraph"}
-			}
-		}
-	}
-
-	// A fence must open its own block. Without a blank line before it the block
-	// walk never sees it start, so the whole run — prose, backticks and code —
-	// arrives here as one paragraph, and every backtick would be escaped into the
-	// page as visible punctuation with the code inlined into the sentence.
-	if !strings.HasPrefix(first, "```") {
-		for i, ln := range lines {
-			if strings.HasPrefix(ln, "```") {
-				return "", &UnsupportedError{at.Path, at.Line + i, "fenced code block without a blank line before it",
-					"a fence opens its own block; without the blank line the code renders as part of the paragraph above"}
-			}
-		}
-	}
-
-	switch {
-	case strings.HasPrefix(first, "```"):
-		return r.fence(at, lines)
-	case strings.HasPrefix(strings.TrimSpace(first), "<!--"):
-		return r.commentBlock(at, lines)
-	case allLinkDefs(lines):
-		// A block of nothing but link reference definitions is invisible in
-		// every reader; its content is already carried by r.Refs.
-		return "", nil
-	case headingRe.MatchString(first):
-		return r.heading(at, first)
-	case thematicRe.MatchString(first):
-		// A rule opening a block is a rule. The same characters AFTER a line of
-		// text are a setext heading instead, which the paragraph renderer reads.
-		if len(lines) == 1 {
-			return "<hr>", nil
-		}
-		rest, err := r.RenderBlock(path, Block{Text: strings.Join(lines[1:], "\n"), Line: blk.Line + 1})
-		if err != nil {
-			return "", err
-		}
-		return "<hr>" + rest, nil
-	case strings.HasPrefix(strings.TrimSpace(first), ">"):
-		return r.blockquote(at, lines)
-	case strings.HasPrefix(strings.TrimSpace(first), "|"):
-		return r.table(at, lines)
-	case isUnorderedItem(first) || orderedItemRe.MatchString(first):
-		return r.list(at, lines)
-	}
-	return r.paragraph(at, lines)
-}
-
-// allLinkDefs reports whether every non-blank line of a block is a link
-// reference definition.
-func allLinkDefs(lines []string) bool {
-	any := false
-	for _, ln := range lines {
-		if strings.TrimSpace(ln) == "" {
-			continue
-		}
-		if !isLinkDefLine(ln) {
-			return false
-		}
-		any = true
-	}
-	return any
-}
-
-// commentBlock drops an HTML comment and renders whatever follows it. The
-// record uses them for machine annotations — review receipts, scope notes — and
-// no reader has ever shown one, so showing one here would publish a note
-// written for a tool.
-func (r *Renderer) commentBlock(at Source, lines []string) (string, error) {
-	text := strings.Join(lines, "\n")
-	i := strings.Index(text, "-->")
-	if i < 0 {
-		return "", &UnsupportedError{at.Path, at.Line, "unterminated HTML comment",
-			"it swallows the rest of the block, so the text after it silently stops existing"}
-	}
-	rest := strings.TrimLeft(text[i+3:], "\n")
-	if strings.TrimSpace(rest) == "" {
-		return "", nil
-	}
-	skipped := strings.Count(text[:i+3], "\n")
-	var out strings.Builder
-	for _, b := range Blocks(rest, at.Line+skipped) {
-		h, err := r.RenderBlock(at.Path, b)
-		if err != nil {
-			return "", err
-		}
-		out.WriteString(h)
-	}
-	return out.String(), nil
-}
-
-// fence renders a fenced code block as a copyable command block: the button's
-// label is a ui.json string, and its payload is the block's own raw text.
-func (r *Renderer) fence(at Source, lines []string) (string, error) {
-	info := strings.TrimSpace(strings.TrimPrefix(lines[0], "```"))
-	if strings.ContainsAny(info, " \t") {
-		return "", &UnsupportedError{at.Path, at.Line, "fenced-code info string", "only a bare language word is rendered, got " + quote(info)}
-	}
-	body := lines[1:]
-	if n := len(body); n > 0 && strings.HasPrefix(strings.TrimSpace(body[n-1]), "```") {
-		body = body[:n-1]
-	}
-	raw := strings.Join(body, "\n")
-	cls := ""
-	if info != "" {
-		cls = ` class="language-` + escapeAttr(info) + `"`
-	}
-	// The button's two labels both travel in the markup: the page's script adds
-	// no words of its own, so every string a reader sees comes from ui.json.
-	return `<div class="cmd"><pre><code` + cls + `>` + escapeText(raw) + "\n" +
-		`</code></pre><button class="copy" data-copy="` + escapeAttr(raw) +
-		`" data-copied="` + escapeAttr(r.UI.Copied) + `">` + escapeText(r.UI.Copy) + `</button></div>`, nil
-}
-
-// heading renders an ATX heading.
-func (r *Renderer) heading(at Source, line string) (string, error) {
-	m := headingRe.FindStringSubmatch(line)
-	level := len(m[1])
-	inner, err := r.inline(at, strings.TrimSpace(m[2]))
-	if err != nil {
-		return "", err
-	}
-	tag := fmt.Sprintf("h%d", level)
-	return "<" + tag + ">" + inner + "</" + tag + ">", nil
-}
-
-// blockquote renders a `>` block by stripping the marker and rendering what is
-// left as blocks in their own right.
-//
-// That recursion is what carries the structures a quote legitimately holds —
-// paragraphs, lists, a quote inside a quote, a table. Flattening any of them
-// would publish a document the source does not have, with nothing on the page to
-// tell a reader that it happened.
-//
-// A LAZY continuation — a line inside the block that drops the marker — is still
-// refused. It is genuinely ambiguous: the same bytes are a quote in one reader
-// and a quote followed by a paragraph in another, and guessing publishes one of
-// them as if it were certain.
-func (r *Renderer) blockquote(at Source, lines []string) (string, error) {
-	var stripped []string
-	for i, ln := range lines {
-		t := strings.TrimSpace(ln)
-		if !strings.HasPrefix(t, ">") {
-			return "", &UnsupportedError{at.Path, at.Line + i, "lazy blockquote continuation", "every line of a quoted block must start with '>'"}
-		}
-		stripped = append(stripped, strings.TrimPrefix(strings.TrimPrefix(t, ">"), " "))
-	}
-	var b strings.Builder
-	b.WriteString("<blockquote>\n")
-	for _, blk := range Blocks(strings.Join(stripped, "\n"), at.Line) {
-		h, err := r.RenderBlock(at.Path, blk)
-		if err != nil {
-			return "", err
-		}
-		if h == "" {
-			continue
-		}
-		b.WriteString(h + "\n")
-	}
-	b.WriteString("</blockquote>")
-	return b.String(), nil
-}
-
-// tableCells splits one table row into its cells, honouring `\|` as content.
-// An escaped pipe is a pipe a cell contains, not a column boundary, and
-// splitting on it shifts every cell after it one column to the left — a table
-// that is quietly wrong, which is worse than one that fails to build. The
-// escape itself is left in place for the inline pass, which already knows `\|`
-// means `|`.
-func tableCells(ln string) []string {
-	t := strings.TrimSpace(ln)
-	t = strings.TrimPrefix(t, "|")
-	t = strings.TrimSuffix(t, "|")
-	var out []string
-	var cur strings.Builder
-	for i := 0; i < len(t); i++ {
-		switch {
-		case t[i] == '\\' && i+1 < len(t):
-			cur.WriteByte(t[i])
-			cur.WriteByte(t[i+1])
-			i++
-		case t[i] == '|':
-			out = append(out, strings.TrimSpace(cur.String()))
-			cur.Reset()
-		default:
-			cur.WriteByte(t[i])
-		}
-	}
-	return append(out, strings.TrimSpace(cur.String()))
-}
-
-// table renders a pipe table, inside its own overflow container.
-//
-// The container is emitted HERE rather than by each layout, because a table is
-// the one block whose width its author does not choose: the widest cell decides
-// it, and without a box to scroll inside, that cell sets the width of the whole
-// page on a phone. Every consumer — a composed chapter, a quoted span, a record
-// body rendered verbatim — gets the same treatment, so no new caller has to
-// remember.
-//
-// Column alignment is not rendered — the site's stylesheet aligns every column
-// the same way — so an alignment row is accepted and its colons ignored.
-func (r *Renderer) table(at Source, lines []string) (string, error) {
-	if len(lines) < 2 || !tableDelimRe.MatchString(lines[1]) {
-		return "", &UnsupportedError{at.Path, at.Line, "pipe table", "a table needs a header row and a |---|---| delimiter row"}
-	}
-	var b strings.Builder
-	b.WriteString(`<div class="tablewrap">` + "<table>\n<thead>\n<tr>\n")
-	for _, c := range tableCells(lines[0]) {
-		inner, err := r.inline(Source{at.Path, at.Line}, c)
-		if err != nil {
-			return "", err
-		}
-		b.WriteString("<th>" + inner + "</th>\n")
-	}
-	b.WriteString("</tr>\n</thead>\n<tbody>\n")
-	for i, ln := range lines[2:] {
-		b.WriteString("<tr>\n")
-		for _, c := range tableCells(ln) {
-			inner, err := r.inline(Source{at.Path, at.Line + 2 + i}, c)
-			if err != nil {
-				return "", err
-			}
-			b.WriteString("<td>" + inner + "</td>\n")
-		}
-		b.WriteString("</tr>\n")
-	}
-	b.WriteString("</tbody>\n</table></div>")
-	return b.String(), nil
-}
-
-// list renders an unordered or ordered list, nesting and all.
-//
-// Nesting is carried by INDENTATION, so each item's continuation lines are
-// dedented and handed back to the block walk: a list inside an item is then a
-// list block like any other, and an item that carries a table or a quoted line
-// gets it rendered rather than flattened into the sentence.
-func (r *Renderer) list(at Source, lines []string) (string, error) {
-	ordered := orderedItemRe.MatchString(strings.TrimLeft(lines[0], " \t"))
-	base := indentOf(lines[0])
-
-	type item struct {
-		body []string
-		line int
-	}
-	var items []item
-	for i, ln := range lines {
-		trimmed := strings.TrimLeft(ln, " \t")
-		isItem := isUnorderedItem(trimmed) || orderedItemRe.MatchString(trimmed)
-		if isItem && indentOf(ln) <= base {
-			if orderedItemRe.MatchString(trimmed) != ordered {
-				return "", &UnsupportedError{at.Path, at.Line + i, "mixed list", "a list is ordered or unordered, not both"}
-			}
-			rest := trimmed[2:]
-			if ordered {
-				rest = orderedItemRe.FindStringSubmatch(trimmed)[2]
-			}
-			items = append(items, item{body: []string{strings.TrimSpace(rest)}, line: at.Line + i})
-			continue
-		}
-		if len(items) == 0 {
-			return "", &UnsupportedError{at.Path, at.Line + i, "list", "a list item starts with '- ' or '1. '"}
-		}
-		items[len(items)-1].body = append(items[len(items)-1].body, ln)
-	}
-
-	tag := "ul"
-	if ordered {
-		tag = "ol"
-	}
-	var b strings.Builder
-	b.WriteString("<" + tag + ">\n")
-	for _, it := range items {
-		inner, err := r.listItem(Source{at.Path, it.line}, it.body)
-		if err != nil {
-			return "", err
-		}
-		b.WriteString("<li>" + inner + "</li>\n")
-	}
-	b.WriteString("</" + tag + ">")
-	return b.String(), nil
-}
-
-// listItem renders one item: its own lead text as a sentence, and anything with
-// structure of its own — a nested list above all — as blocks under it.
-func (r *Renderer) listItem(at Source, body []string) (string, error) {
-	body = dedentContinuations(body)
-	// The lead runs until a line that opens a structure of its own. A nested
-	// list may follow the sentence with no blank line between them, which is
-	// exactly how the record writes one.
-	split := len(body)
-	for i := 1; i < len(body); i++ {
-		t := strings.TrimLeft(body[i], " \t")
-		if isUnorderedItem(t) || orderedItemRe.MatchString(t) || strings.HasPrefix(t, "```") ||
-			strings.HasPrefix(t, ">") || strings.HasPrefix(t, "|") || headingRe.MatchString(t) {
-			split = i
-			break
-		}
-	}
-	lead, err := r.inline(at, strings.Join(body[:split], "\n"))
-	if err != nil {
-		return "", err
-	}
-	if split == len(body) {
-		return lead, nil
-	}
-	var b strings.Builder
-	b.WriteString(lead)
-	for _, blk := range Blocks(strings.Join(body[split:], "\n"), at.Line+split) {
-		h, err := r.RenderBlock(at.Path, blk)
-		if err != nil {
-			return "", err
-		}
-		b.WriteString(h)
-	}
-	return b.String(), nil
-}
-
-// dedentContinuations strips the shared indentation from an item's continuation
-// lines, so a nested list reads as a list rather than as indented prose. The
-// first line has already had its marker removed and is left alone.
-func dedentContinuations(body []string) []string {
-	least := -1
-	for _, ln := range body[1:] {
-		if strings.TrimSpace(ln) == "" {
-			continue
-		}
-		if n := indentOf(ln); least < 0 || n < least {
-			least = n
-		}
-	}
-	if least <= 0 {
-		return body
-	}
-	out := append([]string{}, body[:1]...)
-	for _, ln := range body[1:] {
-		cut := 0
-		for cut < least && cut < len(ln) && (ln[cut] == ' ' || ln[cut] == '\t') {
-			cut++
-		}
-		out = append(out, ln[cut:])
-	}
-	return out
-}
-
-// indentOf counts a line's leading spaces, a tab counting as one.
-func indentOf(s string) int {
-	n := 0
-	for n < len(s) && (s[n] == ' ' || s[n] == '\t') {
-		n++
-	}
-	return n
-}
-
-// paragraph renders a run of prose.
-//
-// Two block constructs can only be recognised HERE, because both are a line of
-// text plus the line under it: a setext heading (`Title` over `===` or `---`)
-// and, in every reader the record is read in, the same underline turning the
-// text above it into a heading rather than into a rule. The paragraph is cut at
-// the underline and the head becomes the heading.
-//
-// A RAW HTML block is refused, and only when it opens the block: the same
-// pattern in the middle of a paragraph is a code span wrapped across a line, and
-// refusing that would fail the build on correct prose.
-func (r *Renderer) paragraph(at Source, lines []string) (string, error) {
-	for i, ln := range lines {
-		// A LIST may interrupt a paragraph, and the record writes one that way
-		// constantly — a bold lead-in and its bullets under it with no blank
-		// line between. Rendering the whole run as one paragraph flattens the
-		// bullets into stray hyphens in a run-on sentence, which is a different
-		// document from the one on the forge.
-		if i > 0 && listInterrupts(ln) {
-			head, err := r.paragraph(at, lines[:i])
-			if err != nil {
-				return "", err
-			}
-			rest, err := r.RenderBlock(at.Path, Block{Text: strings.Join(lines[i:], "\n"), Line: at.Line + i})
-			if err != nil {
-				return "", err
-			}
-			return head + rest, nil
-		}
-		if i > 0 && setextRe.MatchString(ln) {
-			level := 2
-			if strings.Contains(ln, "=") {
-				level = 1
-			}
-			head, err := r.inline(at, strings.Join(lines[:i], "\n"))
-			if err != nil {
-				return "", err
-			}
-			tag := fmt.Sprintf("h%d", level)
-			out := "<" + tag + ">" + head + "</" + tag + ">"
-			if i+1 >= len(lines) {
-				return out, nil
-			}
-			rest, err := r.RenderBlock(at.Path, Block{Text: strings.Join(lines[i+1:], "\n"), Line: at.Line + i + 1})
-			if err != nil {
-				return "", err
-			}
-			return out + rest, nil
-		}
-		if i == 0 && rawHTMLStartRe.MatchString(ln) && isHTMLElementStart(strings.TrimLeft(ln, " \t")) {
-			return "", &UnsupportedError{at.Path, at.Line + i, "raw HTML block", "every picture is a committed asset and every element is generated"}
-		}
-		if i == 0 && (strings.HasPrefix(ln, "    ") || strings.HasPrefix(ln, "\t")) {
-			return "", &UnsupportedError{at.Path, at.Line, "indented code block", "fence code with ``` so it renders as a copyable command"}
-		}
-	}
-	inner, err := r.inline(at, strings.Join(lines, "\n"))
-	if err != nil {
-		return "", err
-	}
-	// An image on its own line is a block-level figure, exactly as the source
-	// markdown reads it; the layouts detect one by this shape.
-	return "<p>" + inner + "</p>", nil
-}
-
-// isHTMLElementStart reports whether a `<…` opens a real HTML element rather
-// than a prose placeholder.
-//
-// The element name alone does not settle it: the record writes
-// `collaborators/<u>/permission` in a sentence, and `u` happens to be an HTML
-// element. Real markup shows itself — it carries attributes, it closes itself,
-// or a matching closing tag follows it. A bare known name with none of those is
-// a placeholder, and is shown as the record wrote it.
-func isHTMLElementStart(s string) bool {
-	if strings.HasPrefix(s, "<!") {
-		return !strings.HasPrefix(s, "<!--")
-	}
-	m := htmlTagRe.FindStringSubmatch(s)
-	if m == nil {
-		return false
-	}
-	name := strings.ToLower(m[1])
-	if !htmlElements[name] {
-		return false
-	}
-	if strings.HasPrefix(s, "</") || voidElements[name] {
-		return true
-	}
-	end := strings.IndexByte(s, '>')
-	if end < 0 {
-		return false
-	}
-	if strings.TrimSpace(s[len(m[0]):end]) != "" {
-		return true
-	}
-	return strings.Contains(strings.ToLower(s[end:]), "</"+name+">")
-}
-
-// voidElements are the HTML elements that never carry a closing tag, so their
-// bare form is still markup.
-var voidElements = map[string]bool{
-	"area": true, "base": true, "br": true, "col": true, "embed": true, "hr": true,
-	"img": true, "input": true, "link": true, "meta": true, "source": true,
-	"track": true, "wbr": true,
-}
-
-// listInterrupts reports whether a line opening a list may cut the paragraph
-// above it.
-//
-// A bullet always may. An ordered item may only when it is numbered ONE, which
-// is CommonMark's rule and exists for exactly the sentence the record also
-// writes: a paragraph that wraps onto a line beginning "2. " is prose, not a
-// list, and cutting it there would invent a list nobody wrote.
-func listInterrupts(ln string) bool {
-	if isUnorderedItem(ln) {
-		return true
-	}
-	m := orderedItemRe.FindStringSubmatch(ln)
-	return m != nil && m[1] == "1"
-}
-
-// isUnorderedItem reports whether a line opens an unordered list item.
-func isUnorderedItem(ln string) bool {
-	return len(ln) > 2 && (ln[0] == '-' || ln[0] == '*' || ln[0] == '+') && ln[1] == ' '
-}
-
-// inlineNode is one piece of a scanned span run: either finished HTML, or a
-// run of emphasis delimiters still looking for its partner.
-type inlineNode struct {
-	// html is the rendered output of a finished piece.
-	html string
-	// delim is '*' or '_' for a delimiter run, and 0 otherwise.
-	delim byte
-	// n is how many characters of the run are still unspent; origN the run's
-	// original length, which the matching rules are stated in terms of.
-	n, origN int
-	// canOpen and canClose are the matching walk's state: what this run may
-	// still do. origOpen and origClose are the flanking rules' verdict, which is
-	// a fact about the text and never changes.
-	canOpen, canClose   bool
-	origOpen, origClose bool
-	// before holds closing tags and after opening tags, so a run that both
-	// closes an inner span and opens nothing still emits them in the right
-	// order around whatever characters it has left over.
-	before, after string
+	return r.subset().RenderBlock(path, blk)
 }
 
-// inline renders the span-level subset in two passes.
-//
-// The first pass reads left to right and finishes everything whose boundaries
-// are unambiguous — escapes, code spans, autolinks, images, links — leaving the
-// emphasis delimiters as unspent runs. The second pass matches those runs.
-//
-// The order is what makes `**`+"`"+`.abcd/**`+"`"+` stays**` render: a code span binds
-// tighter than emphasis in every reader, so the asterisks inside one are
-// content, and a single left-to-right pass that met the `**` first would take
-// its closer from inside the code and then refuse an unclosed span.
+// inline renders one span of prose — a heading's title — on its own.
 func (r *Renderer) inline(at Source, s string) (string, error) {
-	nodes, err := r.scanInline(at, s)
-	if err != nil {
-		return "", err
-	}
-	matchEmphasis(nodes)
-	var b strings.Builder
-	for _, nd := range nodes {
-		if nd.delim == 0 {
-			b.WriteString(nd.html)
-			continue
-		}
-		b.WriteString(nd.before)
-		if nd.n > 0 {
-			b.WriteString(strings.Repeat(string(nd.delim), nd.n))
-		}
-		b.WriteString(nd.after)
-	}
-	return b.String(), nil
-}
-
-// scanInline is the first pass.
-func (r *Renderer) scanInline(at Source, s string) ([]*inlineNode, error) {
-	var nodes []*inlineNode
-	text := func(h string) {
-		if n := len(nodes); n > 0 && nodes[n-1].delim == 0 {
-			nodes[n-1].html += h
-			return
-		}
-		nodes = append(nodes, &inlineNode{html: h})
-	}
-	for i := 0; i < len(s); {
-		switch c := s[i]; {
-		case c == '\\' && i+1 < len(s) && isEscapable(s[i+1]):
-			text(escapeText(string(s[i+1])))
-			i += 2
-		case c == '`':
-			n := runLen(s, i, '`')
-			end := strings.Index(s[i+n:], s[i:i+n])
-			if end < 0 {
-				return nil, &UnsupportedError{at.Path, at.Line, "unclosed code span", quote(clip(s[i:]))}
-			}
-			code := s[i+n : i+n+end]
-			if n > 1 {
-				code = strings.Trim(code, " ")
-			}
-			text("<code>" + escapeText(code) + "</code>")
-			i += n + end + n
-		case c == '!' && i+1 < len(s) && s[i+1] == '[':
-			label, href, next, kind := parseLink(s, i+1)
-			switch kind {
-			case linkLiteral:
-				text("!")
-				i++
-				continue
-			case linkRefused, linkRef:
-				return nil, &UnsupportedError{at.Path, at.Line, "image", "only ![alt](src) is rendered, got " + quote(clip(s[i:]))}
-			}
-			html, err := r.Image(href, label, at)
-			if err != nil {
-				return nil, err
-			}
-			text(html)
-			i = next
-		case c == '[':
-			label, href, next, kind := parseLink(s, i)
-			switch kind {
-			case linkLiteral:
-				// A bracket that opens no link is a bracket. Refusing it would
-				// blocker-fail the build over prose like "the array [0]", which
-				// every markdown reader renders literally.
-				text("[")
-				i++
-				continue
-			case linkRef:
-				dest, ok := r.Refs[normaliseLabel(href)]
-				if !ok {
-					// A document that defines no references is not writing one:
-					// `[A-Za-z][A-Za-z0-9._-]*` is a regular expression, and
-					// every reader shows it as the brackets it is. A document
-					// that DOES define references is held to them, so a typo in
-					// a label fails the build rather than quietly losing a
-					// destination.
-					if len(r.Refs) == 0 {
-						text("[")
-						i++
-						continue
-					}
-					return nil, &UnsupportedError{at.Path, at.Line, "link",
-						"the reference " + quote(href) + " has no [" + href + "]: definition in this document"}
-				}
-				href = dest
-			case linkRefused:
-				return nil, &UnsupportedError{at.Path, at.Line, "link",
-					"only [text](href) and a defined [text][ref] are rendered; footnotes and inline link titles are not in the subset"}
-			}
-			h, err := r.anchor(at, label, href)
-			if err != nil {
-				return nil, err
-			}
-			text(h)
-			i = next
-		case c == '*' || c == '_':
-			n := runLen(s, i, c)
-			opens, closes := flanking(s, i, n, c)
-			nodes = append(nodes, &inlineNode{delim: c, n: n, origN: n,
-				canOpen: opens, canClose: closes, origOpen: opens, origClose: closes})
-			i += n
-		case c == '<':
-			h, next, err := r.angle(at, s, i)
-			if err != nil {
-				return nil, err
-			}
-			text(h)
-			i = next
-		default:
-			j := i
-			for j < len(s) && !strings.ContainsRune("\\`![*_<", rune(s[j])) {
-				j++
-			}
-			if j == i {
-				j = i + 1
-			}
-			text(escapeText(s[i:j]))
-			i = j
-		}
-	}
-	return nodes, nil
-}
-
-// anchor renders one link, refusing the two shapes HTML cannot carry.
-func (r *Renderer) anchor(at Source, label, href string) (string, error) {
-	if scheme, bad := executableScheme(href); bad {
-		return "", &UnsupportedError{at.Path, at.Line, "link scheme",
-			quote(scheme) + " runs code in the reader's browser; the site links to pages and files"}
-	}
-	inner, err := r.inline(at, label)
-	if err != nil {
-		return "", err
-	}
-	// HTML has no nested anchor: a browser closes the outer one at the inner, so
-	// the markup a reader gets is not the markup written here and the outer
-	// link's tail stops being clickable. Markdown itself forbids the construct;
-	// this says so instead of emitting it.
-	if strings.Contains(inner, "<a ") {
-		return "", &UnsupportedError{at.Path, at.Line, "nested link",
-			"HTML has no anchor inside an anchor; the browser would silently close the outer one"}
-	}
-	return `<a href="` + escapeAttr(r.Link(href, at)) + `">` + inner + "</a>", nil
-}
-
-// angle reads a `<` and decides which of the four things it is: an autolink, an
-// HTML comment (dropped, as every reader drops one), an HTML element (refused),
-// or a prose placeholder like `<ts>` (shown as the record wrote it).
-func (r *Renderer) angle(at Source, s string, i int) (string, int, error) {
-	rest := s[i:]
-	if strings.HasPrefix(rest, "<!--") {
-		end := strings.Index(rest, "-->")
-		if end < 0 {
-			return "", 0, &UnsupportedError{at.Path, at.Line, "unterminated HTML comment",
-				"it swallows the rest of the line, so the text after it silently stops existing"}
-		}
-		return "", i + end + 3, nil
-	}
-	if m := autolinkRe.FindStringSubmatch(rest); m != nil {
-		h, err := r.anchor(at, m[1], m[1])
-		if err != nil {
-			return "", 0, err
-		}
-		return h, i + len(m[0]), nil
-	}
-	if m := emailAutoRe.FindStringSubmatch(rest); m != nil {
-		h, err := r.anchor(at, m[1], "mailto:"+m[1])
-		if err != nil {
-			return "", 0, err
-		}
-		return h, i + len(m[0]), nil
-	}
-	if isHTMLElementStart(rest) {
-		return "", 0, &UnsupportedError{at.Path, at.Line, "inline HTML or autolink",
-			"wrap it in a code span or write it as [text](href): " + quote(clip(rest))}
-	}
-	return "&lt;", i + 1, nil
+	return r.subset().Inline(at, s)
 }
 
-// flanking applies CommonMark's left- and right-flanking rules to a delimiter
-// run: whether it may open emphasis, close it, or neither. It is what keeps
-// `snake_case` a word and `npx-create-*` a filename pattern.
-func flanking(s string, i, n int, c byte) (canOpen, canClose bool) {
-	before := byte(' ')
-	if i > 0 {
-		before = s[i-1]
+// subset is the renderer this one configures.
+func (r *Renderer) subset() *mdrender.Renderer {
+	return &mdrender.Renderer{
+		Labels: mdrender.Labels{Copy: r.UI.Copy, Copied: r.UI.Copied},
+		Image:  r.Image,
+		Link:   r.Link,
+		Refs:   r.Refs,
 	}
-	after := byte(' ')
-	if i+n < len(s) {
-		after = s[i+n]
-	}
-	left := !isSpace(after) && (!isPunct(after) || isSpace(before) || isPunct(before))
-	right := !isSpace(before) && (!isPunct(before) || isSpace(after) || isPunct(after))
-	if c == '*' {
-		return left, right
-	}
-	return left && (!right || isPunct(before)), right && (!left || isPunct(after))
 }
 
-// matchEmphasis is the second pass: CommonMark's closer-then-opener walk over
-// the unspent delimiter runs. A run that finds no partner keeps its characters
-// and renders as the punctuation it is.
-func matchEmphasis(nodes []*inlineNode) {
-	for ci := 0; ci < len(nodes); ci++ {
-		c := nodes[ci]
-		if c.delim == 0 || !c.canClose || c.n == 0 {
-			continue
-		}
-		oi := -1
-		for j := ci - 1; j >= 0; j-- {
-			o := nodes[j]
-			if o.delim != c.delim || !o.canOpen || o.n == 0 {
-				continue
-			}
-			// The "rule of three": a run that can both open and close only
-			// pairs with one whose combined length is not a multiple of three,
-			// unless both lengths are. It is what stops `**a*b**` pairing the
-			// wrong two runs.
-			//
-			// It is asked of the FLANKING verdicts, which never change, and not
-			// of canOpen/canClose, which the walk turns off as it consumes runs:
-			// reading the mutable pair here made a closer that had already given
-			// up look like a run that cannot open, and the wrong two runs paired.
-			if (c.origOpen || o.origClose) && (o.origN+c.origN)%3 == 0 &&
-				!(o.origN%3 == 0 && c.origN%3 == 0) {
-				continue
-			}
-			oi = j
-			break
-		}
-		if oi < 0 {
-			c.canClose = false
-			continue
-		}
-		o := nodes[oi]
-		tag := "em"
-		use := 1
-		if o.n >= 2 && c.n >= 2 {
-			tag, use = "strong", 2
-		}
-		o.n -= use
-		c.n -= use
-		o.after = "<" + tag + ">" + o.after
-		c.before += "</" + tag + ">"
-		// A run trapped inside the pair can no longer match anything, but its
-		// CHARACTERS are still characters: `**MET_WITH_CONCERNS.**` keeps its
-		// underscores, exactly as every reader keeps them. Zeroing `n` here
-		// deleted them from the page instead — a silent difference between the
-		// record and what a reader was shown, which is the one thing this
-		// renderer exists to prevent.
-		for j := oi + 1; j < ci; j++ {
-			if nodes[j].delim != 0 {
-				nodes[j].canOpen, nodes[j].canClose = false, false
-			}
-		}
-		if c.n > 0 {
-			// The same closer may still close an outer span.
-			ci--
-		}
-	}
-}
+// LinkDefinitions collects a document's link reference definitions.
+func LinkDefinitions(md string) map[string]string { return mdrender.LinkDefinitions(md) }
 
-// isPunct reports whether a byte is ASCII punctuation, the class the flanking
-// rules are stated over.
-func isPunct(c byte) bool {
-	return (c >= '!' && c <= '/') || (c >= ':' && c <= '@') ||
-		(c >= '[' && c <= '`') || (c >= '{' && c <= '~')
-}
+// Blocks splits a section body into its top-level blocks.
+func Blocks(md string, start int) []Block { return mdrender.Blocks(md, start) }
 
-// The three things a '[' can turn out to be.
-const (
-	// linkInline is `[text](href)`: rendered.
-	linkInline = iota
-	// linkRefused is a construct that MEANS a link but is not in the subset — a
-	// reference link, a footnote, a link title. Rendering it literally would
-	// publish the markup; dropping it would lose the destination.
-	linkRefused
-	// linkLiteral is a bracket that opens no link at all. It is text.
-	linkLiteral
-	// linkRef is `[text][label]` or `[text][]`: the destination is defined
-	// elsewhere in the document, and the caller resolves it.
-	linkRef
+// The renderer's patterns and helpers, under the names the site's own pages use.
+var (
+	headingRe     = mdrender.HeadingRe
+	orderedItemRe = mdrender.OrderedItemRe
+	voidElements  = mdrender.VoidElements
 )
 
-// parseLink classifies a '[' at i and, for an inline link, returns its text,
-// its href, and the index just past the closing paren.
-func parseLink(s string, i int) (text, href string, next, kind int) {
-	depth := 0
-	j := i
-	for ; j < len(s); j++ {
-		switch s[j] {
-		case '[':
-			depth++
-		case ']':
-			depth--
-		}
-		if depth == 0 {
-			break
-		}
-	}
-	if j >= len(s) || j+1 >= len(s) {
-		return "", "", 0, linkLiteral
-	}
-	switch s[j+1] {
-	case '(':
-		// An inline link, or an attempt at one.
-	case '[':
-		// `[text][label]` — a reference link. The label is what sits in the
-		// second pair of brackets, or the text itself when they are empty.
-		end := strings.IndexByte(s[j+2:], ']')
-		if end < 0 {
-			return "", "", 0, linkLiteral
-		}
-		text = s[i+1 : j]
-		label := s[j+2 : j+2+end]
-		if strings.TrimSpace(label) == "" {
-			label = text
-		}
-		return text, label, j + 2 + end + 1, linkRef
-	default:
-		return "", "", 0, linkLiteral
-	}
-	text = s[i+1 : j]
-	k := j + 2
-	pd := 1
-	for ; k < len(s); k++ {
-		if s[k] == '(' {
-			pd++
-		} else if s[k] == ')' {
-			pd--
-			if pd == 0 {
-				break
-			}
-		}
-	}
-	if k >= len(s) {
-		return "", "", 0, linkRefused
-	}
-	href = strings.TrimSpace(s[j+2 : k])
-	if href == "" || strings.ContainsAny(href, " \t") {
-		// A link title (`[t](u "title")`) is not in the subset: it renders as an
-		// attribute nothing on the site reads, and hiding prose in one would
-		// smuggle unsourced text onto the page.
-		return "", "", 0, linkRefused
-	}
-	return text, href, k + 1, linkInline
-}
-
-// executableScheme reports whether an href names a scheme that executes rather
-// than navigates. Escaping an attribute is not enough on its own: a perfectly
-// well-formed `javascript:` href needs no quote to break out of, and the site
-// renders text from a repository whose files an outside contributor can edit.
-// The comparison folds case and strips the whitespace and control characters a
-// browser ignores inside a scheme, because those are exactly what a bypass is
-// written with.
-func executableScheme(href string) (string, bool) {
-	var b strings.Builder
-	for i := 0; i < len(href); i++ {
-		c := href[i]
-		if c == ':' {
-			scheme := strings.ToLower(b.String())
-			switch scheme {
-			case "javascript", "vbscript", "data":
-				return scheme + ":", true
-			}
-			return "", false
-		}
-		if c == '/' || c == '?' || c == '#' {
-			return "", false
-		}
-		if c <= ' ' || c == 0x7f {
-			continue
-		}
-		b.WriteByte(c)
-	}
-	return "", false
-}
-
-func isEscapable(c byte) bool {
-	return strings.IndexByte("\\`*_{}[]()#+-.!|<>&\"'~", c) >= 0
-}
-
-// runLen counts the run of c starting at i.
-func runLen(s string, i int, c byte) int {
-	n := 0
-	for i+n < len(s) && s[i+n] == c {
-		n++
-	}
-	return n
-}
-
-// escapeText escapes a text node.
-func escapeText(s string) string {
-	return strings.NewReplacer("&", "&amp;", "<", "&lt;", ">", "&gt;").Replace(s)
-}
-
-// escapeAttr escapes an attribute value.
-func escapeAttr(s string) string {
-	return strings.NewReplacer("&", "&amp;", "<", "&lt;", ">", "&gt;", `"`, "&quot;", "'", "&#39;").Replace(s)
-}
-
-func quote(s string) string { return `"` + s + `"` }
-
-// clip shortens a fragment for an error message.
-//
-// It counts RUNES, because the record is written in prose that carries
-// em-dashes and accents: slicing by bytes lands mid-character and puts a
-// replacement glyph in the middle of the one message somebody reads to find
-// the line the build refused.
-func clip(s string) string {
-	const max = 40
-	s = strings.ReplaceAll(s, "\n", " ")
-	r := []rune(s)
-	if len(r) > max {
-		return string(r[:max]) + "…"
-	}
-	return s
-}
+func escapeText(s string) string                  { return mdrender.EscapeText(s) }
+func escapeAttr(s string) string                  { return mdrender.EscapeAttr(s) }
+func executableScheme(href string) (string, bool) { return mdrender.ExecutableScheme(href) }
+func clip(s string) string                        { return mdrender.Clip(s) }
+func quote(s string) string                       { return mdrender.Quote(s) }
+func isUnorderedItem(ln string) bool              { return mdrender.IsUnorderedItem(ln) }
+func indentOf(s string) int                       { return mdrender.IndentOf(s) }
+func isSpace(c byte) bool                         { return mdrender.IsSpace(c) }
diff --git a/internal/core/site/sections.go b/internal/core/site/sections.go
index 6dfa0a105..6d9459022 100644
--- a/internal/core/site/sections.go
+++ b/internal/core/site/sections.go
@@ -21,7 +21,6 @@ import (
 )
 
 var (
-	headingRe   = regexp.MustCompile(`^(#{1,6})\s+(.*)$`)
 	nonSlugRe   = regexp.MustCompile(`[^a-z0-9]+`)
 	slugStripRe = regexp.MustCompile("[`*_]")
 )
@@ -47,14 +46,6 @@ type Section struct {
 	BodyLine int
 }
 
-// Block is one top-level markdown block: a paragraph, a table, a fence, an
-// image line, a list, or a blockquote — whatever sits between two blank lines.
-type Block struct {
-	Text string
-	// Line is the 1-based source line the block starts at.
-	Line int
-}
-
 // StripFrontmatter removes a leading YAML frontmatter block and reports how many
 // lines it consumed, so a caller can keep reporting source lines against the
 // original file. It is the script's `strip_frontmatter`: a document that does
@@ -123,8 +114,8 @@ func Sections(path, md string, offset int) ([]Section, error) {
 		if flag&mdrecord.MaskComment != 0 {
 			what = "unterminated HTML comment"
 		}
-		return nil, &UnsupportedError{path, offset + at + 1, what,
-			"it swallows every heading after it, so the rest of the document silently stops existing"}
+		return nil, &UnsupportedError{Path: path, Line: offset + at + 1, Construct: what,
+			Detail: "it swallows every heading after it, so the rest of the document silently stops existing"}
 	}
 
 	var out []Section
@@ -187,55 +178,3 @@ func Slug(t string) string {
 	t = strings.ToLower(slugStripRe.ReplaceAllString(t, ""))
 	return strings.Trim(nonSlugRe.ReplaceAllString(t, "-"), "-")
 }
-
-// Blocks splits a section body into its top-level blocks, honouring fenced code
-// by mdrecord's ListNested rule, the same reading Sections takes.
-// start is the 1-based source line the body begins at.
-func Blocks(md string, start int) []Block {
-	if md == "" {
-		return nil
-	}
-	lines := strings.Split(md, "\n")
-	fences := mdrecord.Read(lines, mdrecord.ListNested).Fences
-	var out []Block
-	var buf []string
-	bufLine := 0
-	flush := func() {
-		if len(buf) > 0 {
-			out = append(out, Block{Text: strings.Join(buf, "\n"), Line: bufLine})
-			buf = nil
-		}
-	}
-	for i := 0; i < len(lines); i++ {
-		if len(fences) > 0 && i == fences[0].Start {
-			f := fences[0]
-			fences = fences[1:]
-			if len(buf) == 0 {
-				bufLine = start + i
-			}
-			buf = append(buf, lines[f.Start:f.End]...)
-			i = f.End - 1
-			// A fence closed at the left margin closes its own block. An
-			// INDENTED one belongs to whatever list item holds it, so the block
-			// runs on: the item's renderer dedents it and reads it as a fence
-			// there. Ending the block here instead would leave the fence's blank
-			// lines to split the code into paragraphs, and its `#` lines to be
-			// read as headings — which is a document silently losing sections.
-			if f.Closed && f.End-1 > f.Start && indentOf(lines[f.End-1]) == 0 {
-				flush()
-			}
-			continue
-		}
-		line := lines[i]
-		if strings.TrimSpace(line) == "" {
-			flush()
-			continue
-		}
-		if len(buf) == 0 {
-			bufLine = start + i
-		}
-		buf = append(buf, line)
-	}
-	flush()
-	return out
-}
diff --git a/internal/core/surface/sentences.go b/internal/core/surface/sentences.go
index 033bc2019..50b8e2eca 100644
--- a/internal/core/surface/sentences.go
+++ b/internal/core/surface/sentences.go
@@ -31,7 +31,7 @@ var sentences = map[string]string{
 	"abcd ahoy doctor": "Report every install gap, user-scope state included: " +
 		"Writes nothing; refuses any argument.",
 	"abcd ahoy install": "Apply the install gaps the detection finds: " +
-		"Writes the .abcd/ scaffolding, the name-guard hooks, and the PATH entry; refuses a stale binary before any write.",
+		"Writes .abcd/, the name-guard hooks and the PATH entry, and installs a tool only on a yes; refuses a stale binary.",
 	"abcd ahoy remote": "Enable GitHub secret scanning and push protection: " +
 		"Writes nothing bare, only the settings and their mirror; refuses bare, naming `abcd ahoy --remote`.",
 	"abcd ahoy remote apply": "Enable GitHub secret scanning and push protection on this repository: " +
diff --git a/internal/core/tools/explain.go b/internal/core/tools/explain.go
new file mode 100644
index 000000000..5045b7104
--- /dev/null
+++ b/internal/core/tools/explain.go
@@ -0,0 +1,168 @@
+package tools
+
+import (
+	"runtime"
+	"strings"
+)
+
+// Explanation is what a verb says when it finds a tool missing (criterion 1):
+// the tool, whether it is optional or required for this capability, what works
+// without it, what it would do, and the exact install step, all from the
+// registry. It is structured so each front door renders it its own way (the
+// plugin page reads it from a verb's --json); Lines is the plain-text rendering
+// every front door shares.
+type Explanation struct {
+	Tool           string      `json:"tool"`
+	Known          bool        `json:"known"`
+	Capability     Capability  `json:"capability"`
+	CapabilityName string      `json:"capability_name,omitempty"`
+	Requirement    Requirement `json:"requirement,omitempty"`
+	What           string      `json:"what,omitempty"`
+	Homepage       string      `json:"homepage,omitempty"`
+	Does           string      `json:"does,omitempty"`
+	WithoutIt      string      `json:"without_it,omitempty"`
+	NativeDefault  string      `json:"native_default,omitempty"`
+	OnDecline      string      `json:"on_decline,omitempty"`
+	StepManager    string      `json:"step_manager,omitempty"`
+	// Step is the exact argv Install would run on this platform; empty when
+	// the registry names none (an unknown tool, or a platform without a step).
+	Step    []string `json:"step,omitempty"`
+	Effects string   `json:"effects,omitempty"`
+	Verify  []string `json:"verify,omitempty"`
+	// RegistryGap is set for a tool the registry does not know: the gap is
+	// abcd's own, and this names the capture that records it.
+	RegistryGap string `json:"registry_gap,omitempty"`
+}
+
+// Explain renders the explanation for name as capability uses it, on the
+// running platform.
+func Explain(name string, capability Capability) Explanation {
+	return explainFor(name, capability, runtime.GOOS)
+}
+
+// explainFor is Explain with the platform named, so a test can reach every
+// platform's step from any host.
+func explainFor(name string, capability Capability, goos string) Explanation {
+	tool, ok := registry[name]
+	if !ok {
+		return unknown(name, capability)
+	}
+	e := Explanation{
+		Tool:       name,
+		Known:      true,
+		Capability: capability,
+		What:       tool.What,
+		Homepage:   tool.Homepage,
+		Effects:    tool.Effects,
+		Verify:     append([]string(nil), tool.Verify...),
+	}
+	if use, ok := tool.Uses[capability]; ok {
+		e.CapabilityName = use.Capability
+		e.Requirement = use.Requirement
+		e.Does = use.Does
+		e.WithoutIt = use.WithoutIt
+		e.NativeDefault = use.NativeDefault
+		e.OnDecline = use.OnDecline
+	} else {
+		// A known tool asked about for a capability its entry does not name is
+		// a registry gap too, but a narrower one: what the tool is and how it is
+		// installed are still known, so only the use is generic.
+		e.CapabilityName = string(capability)
+		e.Requirement = Optional
+		e.Does = "abcd's registry does not say what this capability uses it for"
+		e.WithoutIt = "abcd's registry does not say"
+		e.OnDecline = "nothing was installed"
+		e.RegistryGap = gapCapture(name, capability)
+	}
+	if step, ok := tool.Install[goos]; ok {
+		e.StepManager = step.Manager
+		e.Step = append([]string(nil), step.Argv...)
+	}
+	return e
+}
+
+// unknown is the generic explanation for a tool the registry does not know
+// (criterion 3). It carries no step: abcd installs only what it can explain,
+// and a step it does not hold is never composed from the tool's name.
+func unknown(name string, capability Capability) Explanation {
+	return Explanation{
+		Tool:           name,
+		Capability:     capability,
+		CapabilityName: string(capability),
+		What: "abcd's tool registry has no entry for it, so abcd cannot say what it is, why this capability " +
+			"wants it, or how to install it safely",
+		Does:        "unknown to abcd",
+		WithoutIt:   "unknown to abcd",
+		OnDecline:   "nothing was installed",
+		RegistryGap: gapCapture(name, capability),
+	}
+}
+
+// gapCapture is the capture that records a registry gap. The gap is abcd's own
+// (its curated registry lacks an entry), so it is recorded in abcd's ledger by
+// whoever meets it, and never written into the repository the verb ran in.
+func gapCapture(name string, capability Capability) string {
+	return `abcd's tool registry has no entry for ` + name + ` as ` + string(capability) +
+		` uses it; record the gap in abcd's own ledger with: abcd capture "the tool registry has no entry for ` +
+		name + ` (` + string(capability) + `)" --category future-work-seed`
+}
+
+// StepText is the install step as a person would type it, or the reason there
+// is none.
+func (e Explanation) StepText() string {
+	if len(e.Step) == 0 {
+		if !e.Known {
+			return "none known to abcd (look the tool up before installing it)"
+		}
+		return "none known to abcd for this platform (see " + e.Homepage + ")"
+	}
+	return strings.Join(e.Step, " ")
+}
+
+// Lines is the plain-text explanation, one line per part, the first naming the
+// tool and whether it is optional or required.
+func (e Explanation) Lines() []string {
+	if !e.Known {
+		return []string{
+			e.Tool + " — " + e.What,
+			"  install step: " + e.StepText(),
+			"  registry gap: " + e.RegistryGap,
+		}
+	}
+	lines := []string{
+		e.Tool + " — " + string(e.Requirement) + " for " + e.CapabilityName,
+		"  what it is: " + e.What + " (" + e.Homepage + ")",
+		"  what abcd uses it for: " + e.Does,
+		"  without it: " + e.WithoutIt,
+	}
+	if len(e.Step) > 0 {
+		lines = append(lines, "  install step ("+e.StepManager+"): "+e.StepText())
+	} else {
+		lines = append(lines, "  install step: "+e.StepText())
+	}
+	lines = append(lines, "  what the install does: "+e.Effects)
+	if e.RegistryGap != "" {
+		lines = append(lines, "  registry gap: "+e.RegistryGap)
+	}
+	return lines
+}
+
+// MissingError is a verb's refusal for a missing tool with the registry's
+// explanation appended: the refusal stands exactly as it was (its cause stays
+// reachable through errors.Is), and only its message grows to say what the
+// tool is, whether this capability needs it, and the exact install step.
+type MissingError struct {
+	Cause       error
+	Explanation Explanation
+}
+
+// Missing wraps cause with the explanation for name as capability uses it.
+func Missing(cause error, name string, capability Capability) error {
+	return &MissingError{Cause: cause, Explanation: Explain(name, capability)}
+}
+
+func (m *MissingError) Error() string {
+	return m.Cause.Error() + "\n" + strings.Join(m.Explanation.Lines(), "\n")
+}
+
+func (m *MissingError) Unwrap() error { return m.Cause }
diff --git a/internal/core/tools/install.go b/internal/core/tools/install.go
new file mode 100644
index 000000000..93830e5fc
--- /dev/null
+++ b/internal/core/tools/install.go
@@ -0,0 +1,368 @@
+package tools
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"syscall"
+	"time"
+
+	"github.com/intentdriven/abcd/internal/cienv"
+	"github.com/intentdriven/abcd/internal/fsutil"
+	"github.com/intentdriven/abcd/internal/termsafe"
+)
+
+// Answer is a caller's reply to the install question: yes or no, and in words
+// how the reply was reached (typed at a terminal, named with a flag, no
+// terminal to ask at), which the result repeats so a no is never silent.
+type Answer struct {
+	Yes bool
+	Why string
+}
+
+// Confirm asks the person whether to run the install the explanation shows.
+// The front door supplies it; a nil Confirm is a no.
+type Confirm func(Explanation) Answer
+
+// Result reports one Install: what it ran and whether it worked, or why it ran
+// nothing and what the capability continues on (criterion 2).
+type Result struct {
+	Tool string `json:"tool"`
+	// Ran reports that the install step was executed.
+	Ran bool `json:"ran"`
+	// Argv is the step as run (argv[0] resolved), when Ran.
+	Argv []string `json:"argv,omitempty"`
+	// Installed reports that the step exited zero.
+	Installed bool `json:"installed"`
+	// Verified reports that the verify command exited zero afterwards.
+	Verified bool `json:"verified"`
+	// Declined reports that nobody said yes (a no, no confirmation, CI).
+	Declined bool `json:"declined"`
+	// Why is the reason nothing ran, or what failed.
+	Why string `json:"why,omitempty"`
+	// Output is the bounded tail of the step's output on a failure, or the
+	// verify command's first line on success.
+	Output string `json:"output,omitempty"`
+	// OnDecline is the capability's standing after a no or a failure.
+	OnDecline string `json:"on_decline,omitempty"`
+	step      string
+	verify    string
+}
+
+// Summary is the one line a verb reports for the result. Every path that
+// installed nothing ends with the capability's standing ("continuing on the
+// native secret scanner"), so a no is loud rather than silent (spec scope 4).
+func (r Result) Summary() string {
+	tail := ""
+	if r.OnDecline != "" {
+		tail = "; " + r.OnDecline
+	}
+	switch {
+	case !r.Ran:
+		return r.Tool + " not installed (" + r.Why + ")" + tail
+	case !r.Installed:
+		s := r.Tool + ": ran " + r.step + " — it failed (" + r.Why + ")"
+		if r.Output != "" {
+			s += ": " + r.Output
+		}
+		return s + tail
+	case !r.Verified:
+		s := r.Tool + ": ran " + r.step + " — it succeeded, but the verify " + r.verify + " failed (" + r.Why + ")"
+		if r.Output != "" {
+			s += ": " + r.Output
+		}
+		return s + tail
+	}
+	s := r.Tool + ": ran " + r.step + " — installed, and verified with " + r.verify
+	if r.Output != "" {
+		s += " (" + r.Output + ")"
+	}
+	return s
+}
+
+// Installer runs confirmed install steps. Every process-touching seam is a
+// field so the whole decision path is exercised in tests with no package
+// manager; Default is the production wiring.
+type Installer struct {
+	// LookPath resolves a bare program name on the operator's PATH.
+	LookPath func(string) (string, error)
+	// Run executes an argv whose argv[0] is already resolved, without a shell.
+	Run func(context.Context, []string) ([]byte, error)
+	// Getenv reads the environment (CI detection).
+	Getenv func(string) string
+	// GOOS selects the platform's step.
+	GOOS string
+	// Guard is the directory a resolved program must lie outside: the
+	// repository the verb was run from. A PATH entry pointing into it is
+	// repository content, which is trusted to choose nothing that runs.
+	Guard string
+}
+
+// Default is the production installer for a verb run from guard (its
+// repository root, or its working directory outside one).
+func Default(guard string) *Installer {
+	return &Installer{LookPath: exec.LookPath, Run: runArgv, Getenv: os.Getenv, GOOS: runtime.GOOS, Guard: guard}
+}
+
+// Install explains name as capability uses it, asks confirm, and on a yes runs
+// the registry's step for this platform and then its verify command. It is the
+// package-level spelling of Default(guard).Install.
+func Install(name string, capability Capability, confirm Confirm, guard string) Result {
+	return Default(guard).Install(name, capability, confirm)
+}
+
+const (
+	// installTimeout bounds a package manager run; a timed-out step's process
+	// group is killed through its own handle (runArgv names what that misses).
+	installTimeout = 15 * time.Minute
+	// verifyTimeout bounds the verify command.
+	verifyTimeout = 30 * time.Second
+	// maxOutput bounds what is kept of a step's output.
+	maxOutput = 64 * 1024
+	// tailLines is how much of a failure's output the summary carries.
+	tailLines = 6
+)
+
+// Install is the trust boundary. In order, and each refusal runs nothing:
+//
+//  1. An unknown tool is refused: nothing is composed from a name.
+//  2. A platform without a step is refused.
+//  3. CI never installs, and is not asked.
+//  4. The caller's Confirm must return yes; nil is a no.
+//  5. The step's program must resolve on PATH to an absolute path outside the
+//     guarded tree, lexically and after symlinks.
+//
+// The step then runs as an argv (no shell), with stdin closed, in its own
+// process group, bounded in time (runArgv names the one limit of that bound's
+// kill); the verify command follows under the same rules.
+func (in *Installer) Install(name string, capability Capability, confirm Confirm) Result {
+	e := explainFor(name, capability, in.GOOS)
+	r := Result{Tool: name, OnDecline: e.OnDecline}
+	if !e.Known {
+		r.Declined = true
+		r.Why = "abcd's tool registry has no entry for " + name + ", so it holds no install step it trusts; " +
+			"it knows " + strings.Join(Names(), ", ")
+		return r
+	}
+	if len(e.Step) == 0 {
+		r.Why = "abcd's registry holds no install step for " + in.GOOS + "; see " + e.Homepage
+		return r
+	}
+	r.step = strings.Join(e.Step, " ")
+	r.verify = strings.Join(e.Verify, " ")
+	if reason, ci := cienv.Runner(in.Getenv); ci {
+		r.Declined = true
+		r.Why = "a CI runner (" + reason + "): abcd never installs a tool in CI"
+		return r
+	}
+	// Stricter than the canonical detector, on purpose: it counts CI=false and
+	// CI=0 as no runner, which is right for a check that only skips a warning,
+	// but an install changes the machine and abcd cannot undo it, so any CI
+	// value refuses here. A person who exports CI=false is told why and can
+	// unset it; a runner that set it is never installed on.
+	if v := in.Getenv("CI"); v != "" {
+		r.Declined = true
+		r.Why = "CI is set: abcd never installs a tool in CI, whatever CI's value"
+		return r
+	}
+	if confirm == nil {
+		r.Declined = true
+		r.Why = "no one was asked"
+		return r
+	}
+	ans := confirm(e)
+	if !ans.Yes {
+		r.Declined = true
+		r.Why = ans.Why
+		if r.Why == "" {
+			r.Why = "the answer was no"
+		}
+		return r
+	}
+	prog, err := in.admit(e.Step[0])
+	if err != nil {
+		if errors.Is(err, errNotFound) {
+			r.Why = e.StepManager + " (" + e.Step[0] + ") is not on PATH, so the step cannot run; install " +
+				e.StepManager + " first, or install " + name + " by the route " + e.Homepage + " gives"
+		} else {
+			r.Why = err.Error()
+		}
+		return r
+	}
+	argv := append([]string{prog}, e.Step[1:]...)
+	r.Ran = true
+	r.Argv = argv
+	ctx, cancel := context.WithTimeout(context.Background(), installTimeout)
+	out, err := in.Run(ctx, argv)
+	cancel()
+	if err != nil {
+		r.Why = err.Error()
+		r.Output = tail(out)
+		return r
+	}
+	r.Installed = true
+	vprog, err := in.admit(e.Verify[0])
+	if err != nil {
+		r.Why = err.Error()
+		return r
+	}
+	ctx, cancel = context.WithTimeout(context.Background(), verifyTimeout)
+	vout, err := in.Run(ctx, append([]string{vprog}, e.Verify[1:]...))
+	cancel()
+	if err != nil {
+		r.Why = err.Error()
+		r.Output = tail(vout)
+		return r
+	}
+	r.Verified = true
+	r.OnDecline = ""
+	r.Output = firstLine(vout)
+	return r
+}
+
+var errNotFound = errors.New("not found on PATH")
+
+// admit resolves a bare program name on PATH and refuses a result inside the
+// guarded tree. PATH is the operator's environment, which abcd trusts to locate
+// git and gh everywhere else; what a checkout CAN reach is a PATH entry that
+// points into it, so the result is judged as the gitleaks adapter judges a
+// binary: absolute, and outside the guarded tree both lexically and after
+// symlink resolution. An empty guard is refused rather than trusted.
+func (in *Installer) admit(name string) (string, error) {
+	p, err := in.LookPath(name)
+	if err != nil {
+		return "", fmt.Errorf("%s: %w", name, errNotFound)
+	}
+	if !filepath.IsAbs(p) {
+		return "", fmt.Errorf("%s resolves to %q, which is not an absolute path; nothing was run", name, p)
+	}
+	if in.Guard == "" || !filepath.IsAbs(in.Guard) {
+		return "", fmt.Errorf("%s cannot be judged without an absolute directory to hold it outside; nothing was run", name)
+	}
+	resolved, err := filepath.EvalSymlinks(p)
+	if err != nil {
+		return "", fmt.Errorf("%s resolves to %q, which does not resolve; nothing was run", name, p)
+	}
+	guards := []string{filepath.Clean(in.Guard)}
+	if g, err := filepath.EvalSymlinks(in.Guard); err == nil {
+		guards = append(guards, g)
+	}
+	fold := fsutil.CaseFoldingFS()
+	for _, g := range guards {
+		for _, c := range []string{filepath.Clean(p), resolved} {
+			if fsutil.PathWithin(c, g, fold) {
+				return "", fmt.Errorf("%s resolves to %q, inside the repository this verb ran from; "+
+					"a program there is repository content and is never run as an install step", name, p)
+			}
+		}
+	}
+	return resolved, nil
+}
+
+// pipeGrace is how long runArgv keeps reading a step's output once the step
+// has exited or been killed. It bounds the one wait the group kill cannot end:
+// a descendant that left the step's process group still holds the output pipe.
+var pipeGrace = 10 * time.Second
+
+// runArgv is the production runner: the argv is executed directly (no shell),
+// stdin is the null device so a package manager cannot stop to ask, the working
+// directory is the temporary directory rather than the repository, and the
+// child leads its own process group so a timeout kills that group through this
+// handle and nothing else.
+//
+// The kill reaches the step's process group, not every process the step
+// started: a descendant that moves itself into another group or session
+// (setsid, setpgid) is out of its reach and outlives the step. Such a
+// descendant can also keep the step's output pipe open, and reading until that
+// pipe closes would make the time bound unbounded, so the wait for output ends
+// pipeGrace after the step itself exits or is killed (cmd.WaitDelay), and a
+// step that exited cleanly while leaving such a process behind is reported as
+// a failure that says so.
+func runArgv(ctx context.Context, argv []string) ([]byte, error) {
+	cmd := exec.Command(argv[0], argv[1:]...)
+	cmd.Dir = os.TempDir()
+	cmd.Stdin = nil
+	var buf bytes.Buffer
+	w := &capped{w: &buf, remaining: maxOutput}
+	cmd.Stdout = w
+	cmd.Stderr = w
+	cmd.SysProcAttr = &syscall.SysProcAttr{Setpgid: true}
+	cmd.WaitDelay = pipeGrace
+	if err := cmd.Start(); err != nil {
+		return nil, err
+	}
+	done := make(chan error, 1)
+	go func() { done <- cmd.Wait() }()
+	select {
+	case err := <-done:
+		if errors.Is(err, exec.ErrWaitDelay) {
+			err = fmt.Errorf("exited, but a process it started left its process group and still held its output "+
+				"%s later; abcd stopped waiting for it, and it may still be running", pipeGrace)
+		}
+		return buf.Bytes(), err
+	case <-ctx.Done():
+		// The group is the one this child leads (Setpgid), addressed through
+		// the pid this handle holds: never a pattern, never another process.
+		_ = syscall.Kill(-cmd.Process.Pid, syscall.SIGKILL)
+		<-done
+		return buf.Bytes(), fmt.Errorf("did not finish within the time allowed (%w)", ctx.Err())
+	}
+}
+
+// capped keeps at most remaining bytes and drops the rest without failing the
+// writer, so a chatty package manager is never killed for its verbosity.
+type capped struct {
+	w         *bytes.Buffer
+	remaining int
+}
+
+func (c *capped) Write(p []byte) (int, error) {
+	n := len(p)
+	if c.remaining > 0 {
+		k := n
+		if k > c.remaining {
+			k = c.remaining
+		}
+		c.w.Write(p[:k])
+		c.remaining -= k
+	}
+	return n, nil
+}
+
+// outputLines is the one place a program's output becomes result text: its
+// non-blank lines, trimmed and passed through termsafe. The output is the
+// program's, not abcd's, and Output carries it to every render of the result
+// (the ahoy changed: and note: lines, and --json, which escapes no C1 control
+// or bidi override), so an escape sequence in it never reaches a terminal.
+func outputLines(out []byte) []string {
+	var keep []string
+	for _, l := range strings.Split(string(out), "\n") {
+		if l = strings.TrimSpace(l); l != "" {
+			keep = append(keep, termsafe.Sanitize(l))
+		}
+	}
+	return keep
+}
+
+// tail is the last few non-blank lines of out, joined on " | ".
+func tail(out []byte) string {
+	keep := outputLines(out)
+	if len(keep) > tailLines {
+		keep = keep[len(keep)-tailLines:]
+	}
+	return strings.Join(keep, " | ")
+}
+
+// firstLine is the first non-blank line of out.
+func firstLine(out []byte) string {
+	if keep := outputLines(out); len(keep) > 0 {
+		return keep[0]
+	}
+	return ""
+}
diff --git a/internal/core/tools/registry.go b/internal/core/tools/registry.go
new file mode 100644
index 000000000..5cf8e2ebe
--- /dev/null
+++ b/internal/core/tools/registry.go
@@ -0,0 +1,188 @@
+// Package tools is abcd's explain-then-install mode (itd-63): the curated
+// registry of the external tools abcd knows, the plain-language explanation a
+// verb gives when it finds one missing, and the one place a confirmed install
+// step is run.
+//
+// It is a MODE other verbs call, never a surface of its own (the product
+// thinker's decision 3, 2026-09-21): a verb that finds a tool missing asks
+// Explain for what to say and, where it offers the install, hands Install a
+// Confirm function its front door supplies. The package has no transport
+// knowledge — it never reads a terminal and never writes to stdout — so the CLI
+// asks on the terminal, the plugin page asks through the host's question tool,
+// and this code is the same under both (criterion 5).
+//
+// The trust boundary is Install. What it runs is fixed data in this file,
+// compiled into the binary: an argv per platform, never composed from a flag, a
+// repository file or an environment value, never a shell string. It runs only
+// after the caller's Confirm returns yes, never in CI, and never a program that
+// resolves inside the repository it was asked from. See install.go.
+package tools
+
+import "sort"
+
+// Requirement is whether a capability needs a tool or merely works better with
+// it (adr-22: most dependencies are optional adapters over a native default).
+type Requirement string
+
+const (
+	// Optional: the capability runs on its native default without the tool.
+	Optional Requirement = "optional"
+	// Required: the capability cannot run without the tool.
+	Required Requirement = "required"
+)
+
+// Capability names what a verb is doing when it finds a tool missing. The same
+// tool is optional for one capability and required for another, so an
+// explanation is always for a (tool, capability) pair.
+type Capability string
+
+const (
+	// TranscriptScan is the secret scan of captured session transcripts in a
+	// repository that has NOT armed gitleaks: the native scanner covers it.
+	TranscriptScan Capability = "transcript-scan"
+	// TranscriptScanArmed is the same scan in a repository that armed gitleaks
+	// in .abcd/config/gitleaks.json: the history store refuses to store a
+	// transcript with less coverage than the repository asked for.
+	TranscriptScanArmed Capability = "transcript-scan-armed"
+	// GitHubSettings is every verb that reads or changes the repository's
+	// settings on GitHub (ahoy remote, site setup), which abcd does only
+	// through gh.
+	GitHubSettings Capability = "github-settings"
+)
+
+// Use is what one capability does with a tool, in the words a person reads.
+type Use struct {
+	// Capability is the capability's human name.
+	Capability string
+	// Requirement is optional or required, for this capability.
+	Requirement Requirement
+	// Does is what abcd uses the tool for here.
+	Does string
+	// WithoutIt is what works without the tool (for an optional use, the
+	// native default; for a required one, what fails and the way back).
+	WithoutIt string
+	// NativeDefault is what the capability continues on after a no; empty when
+	// there is none.
+	NativeDefault string
+	// OnDecline is the loud line's tail after a no or a failed install:
+	// "continuing on <native default>" for an optional use, the standing
+	// refusal for a required one.
+	OnDecline string
+}
+
+// Step is one platform's install step: the package manager it uses, by name,
+// and the exact argv run. Argv[0] is a bare program name resolved on PATH at
+// run time; the rest are literal arguments.
+type Step struct {
+	Manager string
+	Argv    []string
+}
+
+// Tool is one registry entry.
+type Tool struct {
+	Name     string
+	What     string // what the tool is, plainly
+	Homepage string // where to read what it is
+	Uses     map[Capability]Use
+	Install  map[string]Step // keyed by runtime.GOOS
+	// Effects is what the install does on the machine and over the network, and
+	// what it does not.
+	Effects string
+	// Verify is the argv that proves the tool runs once installed.
+	Verify []string
+}
+
+// homebrew builds the Homebrew step for a formula. Homebrew is the one package
+// manager with a single fixed command on both supported platforms (macOS, and
+// Linux through Homebrew on Linux); a machine without it is told so, never
+// offered a step composed for some other manager.
+func homebrew(formula string) Step {
+	return Step{Manager: "Homebrew", Argv: []string{"brew", "install", formula}}
+}
+
+// homebrewEffects is what a Homebrew install does beyond the machine, said in
+// full because it is part of the sentence the install question is answered on:
+// brew install may first update its package lists over the network, downloads
+// the package, and sends Homebrew's own install analytics unless the person's
+// Homebrew settings turn them off. abcd neither adds to nor subtracts from
+// that: the step runs with the person's environment, as if they typed it.
+func homebrewEffects(program string) string {
+	return "Homebrew uses the network: it may first update its package lists, then downloads the " + program +
+		" program (with anything it depends on) and puts it on your PATH, and it sends Homebrew's own install " +
+		"analytics unless your Homebrew settings turn them off (brew analytics off)."
+}
+
+// registry is the curated set (the product thinker's decision 2). An entry is
+// added by a change to this file, never at run time: a gap met at run time is
+// named as abcd's own and captured, not composed (explain.go).
+var registry = map[string]Tool{
+	"gitleaks": {
+		Name: "gitleaks",
+		What: "an open-source secret scanner: it reads text and reports the credentials it recognises " +
+			"(API keys, access tokens, private keys)",
+		Homepage: "https://github.com/gitleaks/gitleaks",
+		Uses: map[Capability]Use{
+			TranscriptScan: {
+				Capability:  "the secret scan of captured session transcripts",
+				Requirement: Optional,
+				Does: "when a repository opts in with .abcd/config/gitleaks.json, abcd runs gitleaks over each " +
+					"transcript before storing it and masks what it finds, on top of the native scanner; it reaches " +
+					"labelled, high-entropy keys in prose that the native patterns miss",
+				WithoutIt: "the native secret scanner built into abcd still scans and masks every transcript and " +
+					"every launch payload",
+				NativeDefault: "the native secret scanner",
+				OnDecline:     "continuing on the native secret scanner",
+			},
+			TranscriptScanArmed: {
+				Capability:  "the secret scan of captured session transcripts, which this repository armed in .abcd/config/gitleaks.json",
+				Requirement: Required,
+				Does: "abcd runs gitleaks over each transcript before storing it and masks what it finds, on top of " +
+					"the native scanner, because this repository asked for that coverage",
+				WithoutIt: "nothing is stored: abcd refuses to store this repository's transcripts with less coverage " +
+					"than the repository asked for; setting enabled to false in .abcd/config/gitleaks.json returns it " +
+					"to the native secret scanner",
+				OnDecline: "transcript capture stays refused for this repository until gitleaks is installed or " +
+					".abcd/config/gitleaks.json sets enabled to false",
+			},
+		},
+		Install: map[string]Step{"darwin": homebrew("gitleaks"), "linux": homebrew("gitleaks")},
+		Effects: homebrewEffects("gitleaks") + " The install changes no repository and starts no background service; " +
+			"abcd runs gitleaks only in a repository that opts in.",
+		Verify: []string{"gitleaks", "version"},
+	},
+	"gh": {
+		Name:     "gh",
+		What:     "GitHub's own command-line program, signed in as you",
+		Homepage: "https://cli.github.com",
+		Uses: map[Capability]Use{
+			GitHubSettings: {
+				Capability:  "reading and changing this repository's settings on GitHub (ahoy remote, site setup)",
+				Requirement: Required,
+				Does: "abcd speaks to GitHub through gh, so a remote change is made by your own signed-in identity " +
+					"and abcd never holds a token",
+				WithoutIt: "ahoy remote and site setup cannot read or change the settings; nothing else in abcd needs gh",
+				OnDecline: "the settings on GitHub stay unread and unchanged",
+			},
+		},
+		Install: map[string]Step{"darwin": homebrew("gh"), "linux": homebrew("gh")},
+		Effects: homebrewEffects("gh") + " The install does not sign you in: run gh auth login afterwards, " +
+			"and abcd never sees the token.",
+		Verify: []string{"gh", "--version"},
+	},
+}
+
+// Names returns the registered tool names, sorted.
+func Names() []string {
+	out := make([]string, 0, len(registry))
+	for n := range registry {
+		out = append(out, n)
+	}
+	sort.Strings(out)
+	return out
+}
+
+// Known reports whether the registry holds an entry for name.
+func Known(name string) bool {
+	_, ok := registry[name]
+	return ok
+}
diff --git a/internal/core/tools/runargv_regroup_test.go b/internal/core/tools/runargv_regroup_test.go
new file mode 100644
index 000000000..1624ec867
--- /dev/null
+++ b/internal/core/tools/runargv_regroup_test.go
@@ -0,0 +1,126 @@
+package tools
+
+import (
+	"context"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"syscall"
+	"testing"
+	"time"
+)
+
+// The re-group fixture runs this test binary itself as the "installer", so no
+// package manager and no shell is involved: regroupEnv selects the role, and
+// regroupPIDEnv names the file the holder's pid is written to, so the test
+// stops the holder through that pid and never by pattern.
+const (
+	regroupEnv    = "ABCD_TOOLS_TEST_REGROUP"
+	regroupPIDEnv = "ABCD_TOOLS_TEST_REGROUP_PIDFILE"
+	holderLife    = 60 * time.Second
+)
+
+func TestMain(m *testing.M) {
+	switch role := os.Getenv(regroupEnv); role {
+	case "parent-hang", "parent-exit":
+		os.Exit(regroupParent(role))
+	case "holder":
+		// Holds the inherited stdout/stderr pipe open, in a process group of
+		// its own, for far longer than any bound under test.
+		time.Sleep(holderLife)
+		os.Exit(0)
+	}
+	os.Exit(m.Run())
+}
+
+// regroupParent is the step: it starts a holder that leaves the step's process
+// group (Setpgid) while keeping the step's output pipe, records the holder's
+// pid, and then either hangs until killed or exits cleanly.
+func regroupParent(role string) int {
+	self, err := os.Executable()
+	if err != nil {
+		return 2
+	}
+	holder := exec.Command(self)
+	holder.Env = append(os.Environ(), regroupEnv+"=holder")
+	holder.Stdout = os.Stdout
+	holder.Stderr = os.Stderr
+	holder.SysProcAttr = &syscall.SysProcAttr{Setpgid: true}
+	if err := holder.Start(); err != nil {
+		return 2
+	}
+	if err := os.WriteFile(os.Getenv(regroupPIDEnv), []byte(strconv.Itoa(holder.Process.Pid)), 0o600); err != nil {
+		return 2
+	}
+	if role == "parent-hang" {
+		time.Sleep(holderLife)
+	}
+	return 0
+}
+
+// TestRunArgvBoundHoldsAgainstAReGroupedDescendant is iss-2609261604485703: a
+// descendant that re-groups out of the step's process group survives the group
+// kill and holds the output pipe, and runArgv still returns within its bound,
+// both when the step is killed on timeout and when it exits cleanly first.
+func TestRunArgvBoundHoldsAgainstAReGroupedDescendant(t *testing.T) {
+	self, err := os.Executable()
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, tc := range []struct {
+		role    string
+		timeout time.Duration
+		want    string
+	}{
+		{"parent-hang", 500 * time.Millisecond, "did not finish"},
+		{"parent-exit", 30 * time.Second, "left its process group"},
+	} {
+		t.Run(tc.role, func(t *testing.T) {
+			pidfile := filepath.Join(t.TempDir(), "holder.pid")
+			t.Setenv(regroupEnv, tc.role)
+			t.Setenv(regroupPIDEnv, pidfile)
+			t.Cleanup(func() { stopHolder(t, pidfile) })
+			old := pipeGrace
+			pipeGrace = 200 * time.Millisecond
+			t.Cleanup(func() { pipeGrace = old })
+
+			ctx, cancel := context.WithTimeout(context.Background(), tc.timeout)
+			defer cancel()
+			done := make(chan error, 1)
+			start := time.Now()
+			go func() {
+				_, err := runArgv(ctx, []string{self})
+				done <- err
+			}()
+			select {
+			case err := <-done:
+				if err == nil || !strings.Contains(err.Error(), tc.want) {
+					t.Fatalf("err = %v, want it to say %q", err, tc.want)
+				}
+				if d := time.Since(start); d > 8*time.Second {
+					t.Fatalf("runArgv returned after %s", d)
+				}
+			case <-time.After(8 * time.Second):
+				t.Fatalf("runArgv still waiting after 8s: a re-grouped descendant holding the pipe made the bound unbounded")
+			}
+		})
+	}
+}
+
+// stopHolder kills the holder through the pid its parent recorded.
+func stopHolder(t *testing.T, pidfile string) {
+	t.Helper()
+	b, err := os.ReadFile(pidfile)
+	if err != nil {
+		t.Logf("no holder pid recorded: %v", err)
+		return
+	}
+	pid, err := strconv.Atoi(strings.TrimSpace(string(b)))
+	if err != nil || pid <= 1 {
+		t.Logf("holder pid %q unusable", b)
+		return
+	}
+	_ = syscall.Kill(pid, syscall.SIGKILL)
+}
diff --git a/internal/core/tools/tools_test.go b/internal/core/tools/tools_test.go
new file mode 100644
index 000000000..285241762
--- /dev/null
+++ b/internal/core/tools/tools_test.go
@@ -0,0 +1,453 @@
+package tools
+
+import (
+	"context"
+	"errors"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+)
+
+// TestExplainNamesEveryPartTheCriterionAsksFor is itd-63 criterion 1: a named
+// gap states the tool's name, whether it is optional or required for THIS
+// capability, what works without it, what the tool would do, and the exact
+// install step, all from the registry entry.
+func TestExplainNamesEveryPartTheCriterionAsksFor(t *testing.T) {
+	e := explainFor("gitleaks", TranscriptScan, "darwin")
+	if !e.Known {
+		t.Fatal("gitleaks is not in the registry")
+	}
+	if e.Requirement != Optional {
+		t.Errorf("requirement = %q, want optional for the plain transcript scan", e.Requirement)
+	}
+	if got := strings.Join(e.Step, " "); got != "brew install gitleaks" {
+		t.Errorf("step = %q, want the exact argv brew install gitleaks", got)
+	}
+	text := strings.Join(e.Lines(), "\n")
+	for _, want := range []string{
+		"gitleaks",
+		"optional",
+		"without it:",
+		"native secret scanner",
+		"what abcd uses it for:",
+		"install step (Homebrew): brew install gitleaks",
+		"what the install does:",
+		"https://github.com/gitleaks/gitleaks",
+	} {
+		if !strings.Contains(text, want) {
+			t.Errorf("explanation lacks %q:\n%s", want, text)
+		}
+	}
+}
+
+// TestExplainIsPerCapability: the same tool is optional for one capability and
+// required for another, and the explanation says which, with what a no means.
+func TestExplainIsPerCapability(t *testing.T) {
+	e := explainFor("gitleaks", TranscriptScanArmed, "linux")
+	if e.Requirement != Required {
+		t.Fatalf("requirement = %q, want required where the repository armed gitleaks", e.Requirement)
+	}
+	if !strings.Contains(e.WithoutIt, "enabled") {
+		t.Errorf("an armed repository's without-it must name the opt-out that returns it to the native scanner: %q", e.WithoutIt)
+	}
+	gh := explainFor("gh", GitHubSettings, "darwin")
+	if gh.Requirement != Required || !gh.Known {
+		t.Fatalf("gh for the remote settings: %+v", gh)
+	}
+	if !strings.Contains(gh.Effects, "gh auth login") {
+		t.Errorf("gh's install effects must say it does not sign the person in: %q", gh.Effects)
+	}
+}
+
+// TestUnknownToolGetsGenericTextAndARegistryGap is criterion 3: an unknown tool
+// gets the generic explanation, no install step abcd would run, and the gap is
+// named as abcd's own with the capture that records it.
+func TestUnknownToolGetsGenericTextAndARegistryGap(t *testing.T) {
+	e := explainFor("frobnicate", TranscriptScan, "darwin")
+	if e.Known {
+		t.Fatal("an unregistered tool reads as known")
+	}
+	if len(e.Step) != 0 {
+		t.Fatalf("an unregistered tool carries a step abcd would run: %v", e.Step)
+	}
+	if e.RegistryGap == "" || !strings.Contains(e.RegistryGap, "abcd capture") || !strings.Contains(e.RegistryGap, "frobnicate") {
+		t.Fatalf("registry gap does not carry the capture naming the tool: %q", e.RegistryGap)
+	}
+	text := strings.Join(e.Lines(), "\n")
+	for _, want := range []string{"frobnicate", "no entry", "install step: none"} {
+		if !strings.Contains(text, want) {
+			t.Errorf("generic explanation lacks %q:\n%s", want, text)
+		}
+	}
+}
+
+// TestUnknownPlatformHasNoStep: a platform the entry names no step for shows
+// none rather than borrowing another platform's.
+func TestUnknownPlatformHasNoStep(t *testing.T) {
+	e := explainFor("gitleaks", TranscriptScan, "plan9")
+	if len(e.Step) != 0 {
+		t.Fatalf("plan9 borrowed a step: %v", e.Step)
+	}
+	if !strings.Contains(strings.Join(e.Lines(), "\n"), "install step: none") {
+		t.Fatalf("no-step platform does not say so:\n%s", strings.Join(e.Lines(), "\n"))
+	}
+}
+
+// TestEveryRegistryEntryIsComplete keeps the registry honest: every entry and
+// every use carries each part the explanation renders, and every step is a
+// fixed argv whose program is a bare name (resolved on PATH at run time),
+// never a shell.
+func TestEveryRegistryEntryIsComplete(t *testing.T) {
+	if len(Names()) == 0 {
+		t.Fatal("empty registry")
+	}
+	for _, name := range Names() {
+		tool := registry[name]
+		if tool.Name != name || tool.What == "" || tool.Homepage == "" || tool.Effects == "" || len(tool.Verify) == 0 {
+			t.Errorf("%s: incomplete entry %+v", name, tool)
+		}
+		if tool.Verify[0] != name {
+			t.Errorf("%s: verify runs %q, not the tool itself", name, tool.Verify[0])
+		}
+		if len(tool.Uses) == 0 {
+			t.Errorf("%s: no capability uses it", name)
+		}
+		for c, u := range tool.Uses {
+			if u.Capability == "" || u.Does == "" || u.WithoutIt == "" || u.OnDecline == "" {
+				t.Errorf("%s/%s: incomplete use %+v", name, c, u)
+			}
+			if u.Requirement != Optional && u.Requirement != Required {
+				t.Errorf("%s/%s: requirement %q", name, c, u.Requirement)
+			}
+		}
+		for goos, s := range tool.Install {
+			if len(s.Argv) < 2 || s.Manager == "" {
+				t.Errorf("%s/%s: incomplete step %+v", name, goos, s)
+			}
+			for _, a := range s.Argv {
+				if strings.ContainsAny(a, " ;|&$`<>\\\"'") {
+					t.Errorf("%s/%s: argv element %q carries shell syntax", name, goos, a)
+				}
+			}
+			if s.Argv[0] == "sh" || s.Argv[0] == "bash" || s.Argv[0] == "sudo" || strings.Contains(s.Argv[0], "/") {
+				t.Errorf("%s/%s: program %q is a shell, sudo or a path", name, goos, s.Argv[0])
+			}
+		}
+	}
+}
+
+// TestHomebrewEffectsSayWhatTheInstallSends is iss-2609261604492132: the
+// Effects text is the sentence the install question is answered on, so for a
+// Homebrew step it names the network fetch (Homebrew may update its package
+// lists first, then downloads the package) and Homebrew's own install
+// analytics, which it sends unless the person's Homebrew settings turn them
+// off. It never claims the install sends nothing.
+func TestHomebrewEffectsSayWhatTheInstallSends(t *testing.T) {
+	for _, name := range Names() {
+		tool := registry[name]
+		brew := false
+		for _, s := range tool.Install {
+			brew = brew || s.Manager == "Homebrew"
+		}
+		if !brew {
+			continue
+		}
+		for _, want := range []string{"network", "update its package lists", "analytics", "brew analytics off"} {
+			if !strings.Contains(tool.Effects, want) {
+				t.Errorf("%s: effects do not say %q: %q", name, want, tool.Effects)
+			}
+		}
+		if strings.Contains(tool.Effects, "sends nothing") {
+			t.Errorf("%s: effects claim the install sends nothing: %q", name, tool.Effects)
+		}
+	}
+}
+
+// --- Install -----------------------------------------------------------------
+
+// fakeExec records every argv it is handed and answers from a table.
+type fakeExec struct {
+	calls [][]string
+	fail  map[string]error // keyed by the program's base name
+	out   map[string]string
+}
+
+func (f *fakeExec) run(_ context.Context, argv []string) ([]byte, error) {
+	f.calls = append(f.calls, append([]string(nil), argv...))
+	base := filepath.Base(argv[0])
+	return []byte(f.out[base]), f.fail[base]
+}
+
+// binDir plants executables named for each program outside any repository,
+// so the lookup finds them and admission passes.
+func binDir(t *testing.T, names ...string) string {
+	t.Helper()
+	dir := t.TempDir()
+	for _, n := range names {
+		if err := os.WriteFile(filepath.Join(dir, n), []byte("#!/bin/sh\nexit 0\n"), 0o755); err != nil {
+			t.Fatal(err)
+		}
+	}
+	return dir
+}
+
+func testInstaller(t *testing.T, fx *fakeExec, bin string, env map[string]string) *Installer {
+	t.Helper()
+	return &Installer{
+		LookPath: func(name string) (string, error) {
+			p := filepath.Join(bin, name)
+			if _, err := os.Stat(p); err != nil {
+				return "", errors.New("not found")
+			}
+			return p, nil
+		},
+		Run:    fx.run,
+		Getenv: func(k string) string { return env[k] },
+		GOOS:   "darwin",
+		Guard:  t.TempDir(),
+	}
+}
+
+func yes(Explanation) Answer { return Answer{Yes: true, Why: "typed yes"} }
+func no(Explanation) Answer  { return Answer{Why: "typed no"} }
+
+// TestInstallRunsTheRegistryStepOnlyOnYesAndVerifies is criterion 2's yes half:
+// the fixed argv runs, then the verify command, and the result says both.
+func TestInstallRunsTheRegistryStepOnlyOnYesAndVerifies(t *testing.T) {
+	fx := &fakeExec{out: map[string]string{"gitleaks": "8.18.0\n"}}
+	bin := binDir(t, "brew", "gitleaks")
+	in := testInstaller(t, fx, bin, nil)
+	var asked Explanation
+	r := in.Install("gitleaks", TranscriptScan, func(e Explanation) Answer { asked = e; return yes(e) })
+	if asked.Tool != "gitleaks" || len(asked.Step) == 0 {
+		t.Fatalf("the confirmation was not handed the explanation: %+v", asked)
+	}
+	if !r.Ran || !r.Installed || !r.Verified || r.Declined {
+		t.Fatalf("result = %+v, want ran, installed, verified", r)
+	}
+	if len(fx.calls) != 2 {
+		t.Fatalf("calls = %v, want the step then the verify", fx.calls)
+	}
+	// What runs is the symlink-resolved path, so what was judged and what is
+	// executed are the same bytes.
+	bin, _ = filepath.EvalSymlinks(bin)
+	if got := fx.calls[0]; got[0] != filepath.Join(bin, "brew") || strings.Join(got[1:], " ") != "install gitleaks" {
+		t.Errorf("step argv = %v", got)
+	}
+	if got := fx.calls[1]; got[0] != filepath.Join(bin, "gitleaks") || strings.Join(got[1:], " ") != "version" {
+		t.Errorf("verify argv = %v", got)
+	}
+	s := r.Summary()
+	if !strings.Contains(s, "ran brew install gitleaks") || !strings.Contains(s, "verified") {
+		t.Errorf("summary does not report what ran and whether it worked: %q", s)
+	}
+}
+
+// TestInstallOnNoRunsNothingAndSaysContinuing is criterion 2's no half and the
+// spec's loud staging: nothing runs, and the result carries the
+// "continuing on <native default>" line.
+func TestInstallOnNoRunsNothingAndSaysContinuing(t *testing.T) {
+	fx := &fakeExec{}
+	in := testInstaller(t, fx, binDir(t, "brew"), nil)
+	r := in.Install("gitleaks", TranscriptScan, no)
+	if r.Ran || !r.Declined || len(fx.calls) != 0 {
+		t.Fatalf("a no ran something: %+v calls=%v", r, fx.calls)
+	}
+	want := "gitleaks not installed (typed no); continuing on the native secret scanner"
+	if r.Summary() != want {
+		t.Fatalf("summary = %q, want %q", r.Summary(), want)
+	}
+}
+
+// TestInstallNeverRunsWithoutAConfirmation: a nil confirmation is a no.
+func TestInstallNeverRunsWithoutAConfirmation(t *testing.T) {
+	fx := &fakeExec{}
+	r := testInstaller(t, fx, binDir(t, "brew"), nil).Install("gitleaks", TranscriptScan, nil)
+	if r.Ran || len(fx.calls) != 0 || !r.Declined {
+		t.Fatalf("installed without a confirmation: %+v", r)
+	}
+}
+
+// TestInstallNeverRunsInCI: CI never installs, whatever the confirmation says,
+// and the confirmation is not even asked. Every environment the canonical CI
+// detector names refuses (a runner that sets only GITHUB_ACTIONS included,
+// iss-2609261604499090), and so does any non-empty CI, "false" and "0"
+// included: the installer is deliberately stricter than the detector.
+func TestInstallNeverRunsInCI(t *testing.T) {
+	for _, env := range []map[string]string{
+		{"CI": "true"}, {"CI": "1"}, {"GITHUB_ACTIONS": "true"}, {"CI": "false"}, {"CI": "0"},
+	} {
+		fx := &fakeExec{}
+		asked := false
+		in := testInstaller(t, fx, binDir(t, "brew"), env)
+		r := in.Install("gitleaks", TranscriptScan, func(e Explanation) Answer { asked = true; return yes(e) })
+		if r.Ran || len(fx.calls) != 0 || asked || !r.Declined {
+			t.Fatalf("%v: CI installed or asked: %+v asked=%v", env, r, asked)
+		}
+		if !strings.Contains(r.Summary(), "CI") || !strings.Contains(r.Summary(), "continuing on") {
+			t.Fatalf("%v: CI refusal is not said: %q", env, r.Summary())
+		}
+	}
+}
+
+// TestInstallRefusesAnUnknownTool: nothing composed, nothing run, and the
+// refusal names the tools the registry does know.
+func TestInstallRefusesAnUnknownTool(t *testing.T) {
+	fx := &fakeExec{}
+	asked := false
+	r := testInstaller(t, fx, binDir(t, "brew"), nil).Install("frobnicate", TranscriptScan, func(e Explanation) Answer { asked = true; return yes(e) })
+	if r.Ran || len(fx.calls) != 0 || asked {
+		t.Fatalf("an unknown tool ran or was asked about: %+v", r)
+	}
+	for _, n := range Names() {
+		if !strings.Contains(r.Why, n) {
+			t.Errorf("refusal does not name known tool %q: %q", n, r.Why)
+		}
+	}
+}
+
+// TestInstallSaysWhenThePackageManagerIsMissing: a yes with no Homebrew runs
+// nothing and says what is missing.
+func TestInstallSaysWhenThePackageManagerIsMissing(t *testing.T) {
+	fx := &fakeExec{}
+	r := testInstaller(t, fx, binDir(t), nil).Install("gitleaks", TranscriptScan, yes)
+	if r.Ran || len(fx.calls) != 0 {
+		t.Fatalf("ran without a package manager: %+v", r)
+	}
+	if !strings.Contains(r.Why, "Homebrew") || !strings.Contains(r.Summary(), "continuing on") {
+		t.Fatalf("missing manager not said: %q", r.Summary())
+	}
+}
+
+// TestInstallRefusesAProgramInsideTheGuardedTree: a PATH entry that resolves
+// the package manager into the repository is repository content, and never
+// runs.
+func TestInstallRefusesAProgramInsideTheGuardedTree(t *testing.T) {
+	fx := &fakeExec{}
+	repo := t.TempDir()
+	bin := filepath.Join(repo, "bin")
+	if err := os.MkdirAll(bin, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(bin, "brew"), []byte("#!/bin/sh\n"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	in := testInstaller(t, fx, bin, nil)
+	in.Guard = repo
+	r := in.Install("gitleaks", TranscriptScan, yes)
+	if r.Ran || len(fx.calls) != 0 {
+		t.Fatalf("ran a package manager from inside the repository: %+v", r)
+	}
+	if !strings.Contains(r.Why, "inside") {
+		t.Fatalf("refusal does not say why: %q", r.Why)
+	}
+}
+
+// TestInstallReportsAFailedStepAndAFailedVerify: both failures are reported,
+// never a success.
+func TestInstallReportsAFailedStepAndAFailedVerify(t *testing.T) {
+	fx := &fakeExec{fail: map[string]error{"brew": errors.New("exit status 1")}, out: map[string]string{"brew": "Error: no bottle\n"}}
+	r := testInstaller(t, fx, binDir(t, "brew", "gitleaks"), nil).Install("gitleaks", TranscriptScan, yes)
+	if !r.Ran || r.Installed || r.Verified {
+		t.Fatalf("a failed step reads as installed: %+v", r)
+	}
+	if !strings.Contains(r.Summary(), "failed") || !strings.Contains(r.Summary(), "no bottle") || !strings.Contains(r.Summary(), "continuing on") {
+		t.Fatalf("failed step summary: %q", r.Summary())
+	}
+
+	fx = &fakeExec{fail: map[string]error{"gitleaks": errors.New("exit status 2")}}
+	r = testInstaller(t, fx, binDir(t, "brew", "gitleaks"), nil).Install("gitleaks", TranscriptScan, yes)
+	if !r.Installed || r.Verified {
+		t.Fatalf("a failed verify reads as verified: %+v", r)
+	}
+	if !strings.Contains(r.Summary(), "verify") || !strings.Contains(r.Summary(), "failed") {
+		t.Fatalf("failed verify summary: %q", r.Summary())
+	}
+}
+
+// TestRunArgvExecutesWithoutAShell drives the production runner: the argv is
+// handed to the program as-is, so a metacharacter reaches it as a literal byte
+// rather than being interpreted.
+func TestRunArgvExecutesWithoutAShell(t *testing.T) {
+	dir := t.TempDir()
+	out := filepath.Join(dir, "argv")
+	script := filepath.Join(dir, "echoargs")
+	body := "#!/bin/sh\nprintf '%s\\n' \"$@\" > " + out + "\n"
+	if err := os.WriteFile(script, []byte(body), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := runArgv(context.Background(), []string{script, "a;b", "$(x)"}); err != nil {
+		t.Fatal(err)
+	}
+	got, err := os.ReadFile(out)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if string(got) != "a;b\n$(x)\n" {
+		t.Fatalf("argv reached the program as %q", got)
+	}
+}
+
+// TestRunArgvKillsItsOwnGroupOnTimeout: a step that outlives its bound is
+// stopped with everything it started, through the handle, promptly.
+func TestRunArgvKillsItsOwnGroupOnTimeout(t *testing.T) {
+	dir := t.TempDir()
+	script := filepath.Join(dir, "hang")
+	if err := os.WriteFile(script, []byte("#!/bin/sh\nsleep 30 &\nsleep 30\n"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 300*time.Millisecond)
+	defer cancel()
+	start := time.Now()
+	_, err := runArgv(ctx, []string{script})
+	if err == nil || !strings.Contains(err.Error(), "did not finish") {
+		t.Fatalf("err = %v, want the timeout named", err)
+	}
+	if d := time.Since(start); d > 10*time.Second {
+		t.Fatalf("runArgv waited %s: the group was not killed", d)
+	}
+}
+
+// TestMissingErrorKeepsTheCauseAndCarriesTheExplanation: a verb's refusal for a
+// missing tool keeps its sentinel for errors.Is and appends the explanation.
+func TestMissingErrorKeepsTheCauseAndCarriesTheExplanation(t *testing.T) {
+	cause := errors.New("gitleaks configured but not found")
+	err := Missing(cause, "gitleaks", TranscriptScanArmed)
+	if !errors.Is(err, cause) {
+		t.Fatal("the cause is lost")
+	}
+	lines := strings.Split(err.Error(), "\n")
+	if lines[0] != cause.Error() || len(lines) < 5 {
+		t.Fatalf("error = %q, want the cause then the explanation", err.Error())
+	}
+}
+
+// TestInstallSanitisesTheProgramsOutput is iss-2609261604498137: a program's
+// output is untrusted text, and the result carries it to the terminal (the
+// ahoy changed: and note: lines) and to --json, so no escape, C1 control or
+// bidi override survives into Output or the Summary, on success or failure.
+func TestInstallSanitisesTheProgramsOutput(t *testing.T) {
+	const hostile = "\x1b[2J8.18.0‮\u009b31m\x07"
+	for _, tc := range []struct {
+		name string
+		fx   *fakeExec
+	}{
+		{"verified", &fakeExec{out: map[string]string{"gitleaks": hostile + "\nsecond\n"}}},
+		{"failed step", &fakeExec{fail: map[string]error{"brew": errors.New("exit status 1")}, out: map[string]string{"brew": "Error:\n" + hostile + "\n"}}},
+		{"failed verify", &fakeExec{fail: map[string]error{"gitleaks": errors.New("exit status 2")}, out: map[string]string{"gitleaks": hostile}}},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			r := testInstaller(t, tc.fx, binDir(t, "brew", "gitleaks"), nil).Install("gitleaks", TranscriptScan, yes)
+			if !strings.Contains(r.Output, "8.18.0") {
+				t.Fatalf("output lost its text: %q", r.Output)
+			}
+			for _, s := range []string{r.Output, r.Summary()} {
+				if strings.ContainsAny(s, "\x1b‮\u009b\x07") {
+					t.Errorf("a control reached the result: %q", s)
+				}
+			}
+		})
+	}
+}
diff --git a/internal/surface/cli/ahoy_tool_confirm_test.go b/internal/surface/cli/ahoy_tool_confirm_test.go
new file mode 100644
index 000000000..540a2075d
--- /dev/null
+++ b/internal/surface/cli/ahoy_tool_confirm_test.go
@@ -0,0 +1,176 @@
+package cli
+
+import (
+	"bufio"
+	"bytes"
+	"encoding/json"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/intentdriven/abcd/internal/core/ahoy"
+	"github.com/intentdriven/abcd/internal/core/tools"
+)
+
+func gitleaksExplained() tools.Explanation {
+	return tools.Explain("gitleaks", tools.TranscriptScan)
+}
+
+// TestToolConfirmAsksOnlyAtATerminal is itd-63's non-interactive rule at the
+// CLI: a piped "y" (the `yes | abcd ahoy install` a host reaches for) answers
+// the category questions, never the install of a program. Only an answer typed
+// at a terminal, or the tool named with --install-tool, is a yes.
+func TestToolConfirmAsksOnlyAtATerminal(t *testing.T) {
+	e := gitleaksExplained()
+
+	var w bytes.Buffer
+	piped := &stdinPrompter{r: bufio.NewReader(strings.NewReader("y\n")), w: &w}
+	ans := toolConfirm(piped, nil, false, &w)(e)
+	if ans.Yes {
+		t.Fatal("a piped y installed a tool")
+	}
+	if !strings.Contains(ans.Why, "terminal") || !strings.Contains(ans.Why, "--install-tool gitleaks") {
+		t.Errorf("the decline does not say how to say yes: %q", ans.Why)
+	}
+
+	w.Reset()
+	tty := &stdinPrompter{r: bufio.NewReader(strings.NewReader("y\n")), w: &w, tty: true}
+	ans = toolConfirm(tty, nil, false, &w)(e)
+	if !ans.Yes {
+		t.Fatalf("a y typed at a terminal was not a yes: %+v", ans)
+	}
+	asked := w.String()
+	for _, want := range []string{"what abcd uses it for:", "without it:", "brew install gitleaks", "[y/N]"} {
+		if !strings.Contains(asked, want) {
+			t.Errorf("the terminal question lacks %q:\n%s", want, asked)
+		}
+	}
+
+	w.Reset()
+	tty = &stdinPrompter{r: bufio.NewReader(strings.NewReader("\n")), w: &w, tty: true}
+	if ans = toolConfirm(tty, nil, false, &w)(e); ans.Yes {
+		t.Fatal("a bare Enter at a terminal was a yes; the default is no")
+	}
+}
+
+// TestToolConfirmNamedAndYes: --install-tool is the explicit answer a host's
+// question tool relays; --yes never installs a tool, even at a terminal.
+func TestToolConfirmNamedAndYes(t *testing.T) {
+	e := gitleaksExplained()
+	var w bytes.Buffer
+	tty := &stdinPrompter{r: bufio.NewReader(strings.NewReader("y\n")), w: &w, tty: true}
+
+	// Off a terminal, and with nothing typed, the named tool is still a yes:
+	// the flag is the answer.
+	piped := &stdinPrompter{r: bufio.NewReader(strings.NewReader("")), w: &w}
+	if ans := toolConfirm(piped, map[string]bool{"gitleaks": true}, false, &w)(e); !ans.Yes {
+		t.Fatalf("a tool named with --install-tool was not a yes: %+v", ans)
+	}
+	ans := toolConfirm(tty, nil, true, &w)(e)
+	if ans.Yes || !strings.Contains(ans.Why, "--yes") {
+		t.Fatalf("--yes installed a tool or said nothing: %+v", ans)
+	}
+	if ans := toolConfirm(ahoy.RefusingPrompter{}, nil, false, &w)(e); ans.Yes {
+		t.Fatal("the refusing prompter installed a tool")
+	}
+}
+
+// TestInstallToolRefusesAnUnknownName: an --install-tool name ahoy install
+// does not check for is refused before anything runs, naming the ones it does.
+// gh is in the registry but no install gap names it, so it is refused too: a
+// flag that would be accepted and then do nothing is a silent no.
+func TestInstallToolRefusesAnUnknownName(t *testing.T) {
+	t.Chdir(t.TempDir())
+	for _, name := range []string{"frobnicate", "gh"} {
+		_, err := runCLIStdinErr(t, "", "ahoy", "install", "--install-tool", name, "--refuse-adopt")
+		if err == nil {
+			t.Fatalf("--install-tool %s was accepted", name)
+		}
+		for _, want := range append([]string{name}, ahoy.DependencyTools...) {
+			if !strings.Contains(err.Error(), want) {
+				t.Errorf("refusal lacks %q: %v", want, err)
+			}
+		}
+	}
+}
+
+// toolFreePath leaves git on PATH (the install reads the checkout) and nothing
+// else, so neither gitleaks nor a package manager is found and no install
+// step can ever run from this test.
+func toolFreePath(t *testing.T) {
+	t.Helper()
+	gitBin, err := exec.LookPath("git")
+	if err != nil {
+		t.Skip("git not on PATH")
+	}
+	dir := t.TempDir()
+	if err := os.Symlink(gitBin, filepath.Join(dir, "git")); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("PATH", dir)
+	// Both of the variables cienv.Runner reads, so the confirmation path runs
+	// on a CI runner as it does on a workstation.
+	t.Setenv("CI", "")
+	t.Setenv("GITHUB_ACTIONS", "")
+}
+
+func installNotes(t *testing.T, out []byte) (notes, declined []string) {
+	t.Helper()
+	var res struct {
+		Notes              []string `json:"notes"`
+		DeclinedCategories []string `json:"declined_categories"`
+	}
+	if err := json.Unmarshal(out, &res); err != nil {
+		t.Fatalf("install output not JSON: %v\n%s", err, out)
+	}
+	return res.Notes, res.DeclinedCategories
+}
+
+// TestAhoyInstallPipedYesExplainsAndKeepsTheNativeScanner is the end-to-end
+// no: `yes | abcd ahoy install` approves every category, and the missing
+// gitleaks is explained and left uninstalled, loudly, on the native scanner.
+func TestAhoyInstallPipedYesExplainsAndKeepsTheNativeScanner(t *testing.T) {
+	hermeticRepo(t)
+	toolFreePath(t)
+	out, errOut, err := runCLIPipedStdinSplit(t, strings.Repeat("y\n", 12), "ahoy", "install", "--allow-stale-binary", "--json")
+	if err != nil {
+		t.Fatalf("install exited non-zero: %v\n%s\n%s", err, out, errOut)
+	}
+	notes, _ := installNotes(t, out)
+	joined := strings.Join(notes, "\n")
+	for _, want := range []string{
+		"dependency: gitleaks — optional for",
+		"install step (Homebrew): brew install gitleaks",
+		"gitleaks not installed (no terminal to ask at",
+		"continuing on the native secret scanner",
+	} {
+		if !strings.Contains(joined, want) {
+			t.Errorf("notes lack %q:\n%s", want, joined)
+		}
+	}
+}
+
+// TestAhoyInstallNamedToolReachesTheStep is the host's relayed yes end to
+// end: with stdin closed, --install-tool answers the dependency question and
+// the install is attempted; here the package manager is absent, so the
+// result says so and nothing ran.
+func TestAhoyInstallNamedToolReachesTheStep(t *testing.T) {
+	hermeticRepo(t)
+	toolFreePath(t)
+	out, errOut, err := runCLIPipedStdinSplit(t, "", "ahoy", "install", "--adopt", "--allow-stale-binary", "--install-tool", "gitleaks", "--json")
+	if err != nil {
+		t.Fatalf("install exited non-zero: %v\n%s\n%s", err, out, errOut)
+	}
+	notes, declined := installNotes(t, out)
+	for _, c := range declined {
+		if c == "dependency" {
+			t.Fatalf("--install-tool did not answer the dependency question: declined %v", declined)
+		}
+	}
+	joined := strings.Join(notes, "\n")
+	if !strings.Contains(joined, "Homebrew (brew) is not on PATH") || !strings.Contains(joined, "continuing on the native secret scanner") {
+		t.Fatalf("the named install did not reach the step, or was silent:\n%s", joined)
+	}
+}
diff --git a/internal/surface/cli/capture_surface_test.go b/internal/surface/cli/capture_surface_test.go
index fc3a008e2..db6a84856 100644
--- a/internal/surface/cli/capture_surface_test.go
+++ b/internal/surface/cli/capture_surface_test.go
@@ -1142,6 +1142,10 @@ func TestCaptureUnreadableStatusDirectoryExits1(t *testing.T) {
 		{"capture", "resolve", m.ID, "fixed", "--impact", "fix"},
 		{"capture", "wontfix", m.ID, "not worth it"},
 		{"capture", "defer", m.ID, "--after", "v0.1.0", "--reason", "a reason that is long enough"},
+		// The board and the list read every folder too: an unreadable one is the
+		// same fault there, never a folder of no records (iss-2609261631120364).
+		{"capture", "list", "--all"},
+		{"capture"},
 	} {
 		out, err := runCLIErr(t, args...)
 		if exitCodeOf(err) != 1 || err == nil || strings.Contains(err.Error(), "unknown issue id") ||
@@ -1460,3 +1464,75 @@ func TestCaptureEnumRefusalNamesTheFlagAndItsSet(t *testing.T) {
 		t.Fatalf("refused captures wrote %d record(s)", n)
 	}
 }
+
+// TestCaptureGroundsAndBodyRefusalsExit2 holds the exit-2 rule for every
+// ledger-verb input refusal (iss-2609260552251398, iss-2609262211082803) to the
+// refusals two later lanes brought: grounds text the site renderer refuses
+// (an image, a reference link), and a wontfix over a body that leaves an HTML
+// comment open, which is refused on the 2026-08-31 ruling. Each is the caller's
+// to fix with nothing written, so each exits 2, never the fault's 1.
+func TestCaptureGroundsAndBodyRefusalsExit2(t *testing.T) {
+	_ = captureLedgerRepo(t)
+	var plain, locked struct {
+		ID string `json:"id"`
+	}
+	if err := json.Unmarshal(runCLI(t, "capture", "an observation whose grounds will not render", "--json"), &plain); err != nil || plain.ID == "" {
+		t.Fatalf("capture envelope unreadable: %v", err)
+	}
+	for _, bad := range []string{
+		"pursued: the loader keeps its rules when the marker is fresh, as ![the diagram](x.png) shows",
+		"pursued: the loader keeps its rules when the marker is fresh, as [the note][n] records",
+	} {
+		for _, args := range [][]string{
+			{"capture", "promote", plain.ID, "--grounds", bad},
+			{"capture", "resolve", plain.ID, "fixed", "--impact", "fix", "--grounds", bad},
+		} {
+			if _, err := runCLIErr(t, args...); exitCodeOf(err) != 2 || !strings.Contains(err.Error(), "site renderer refuses") {
+				t.Errorf("%v with %q: exit = %d (%v), want 2 naming the renderer's refusal", args[:2], bad, exitCodeOf(err), err)
+			}
+		}
+	}
+	if err := json.Unmarshal(runCLI(t, "capture", "the loader drops rules when the <!-- abcd-review marker is stale", "--json"), &locked); err != nil || locked.ID == "" {
+		t.Fatalf("capture envelope unreadable: %v", err)
+	}
+	if _, err := runCLIErr(t, "capture", "wontfix", locked.ID, "superseded by the loader rewrite"); exitCodeOf(err) != 2 || !strings.Contains(err.Error(), "HTML comment") {
+		t.Errorf("wontfix over a locked body: exit = %d (%v), want 2 naming the open comment", exitCodeOf(err), err)
+	}
+}
+
+// TestCaptureWontfixRefusesALockedBody is the surface half of
+// iss-2608301908270888 as the 2026-08-31 ruling settled it. Ordinary prose can
+// carry a `<!--` nothing closes, and capture writes it verbatim into the body,
+// where it masks every line below it. Wontfix derives a `declined:` entry that
+// could not read back there, so it refuses, moves nothing, and tells the
+// operator which construct and line to fix and how: the hand edit is the repair.
+func TestCaptureWontfixRefusesALockedBody(t *testing.T) {
+	repo := captureLedgerRepo(t)
+	var m struct {
+		ID string `json:"id"`
+	}
+	if err := json.Unmarshal(runCLI(t, "capture", "the loader drops rules when the <!-- abcd-review marker is stale", "--json"), &m); err != nil || m.ID == "" {
+		t.Fatalf("capture envelope unreadable: %v", err)
+	}
+	_, _, err := runCLISplit(t, "capture", "wontfix", m.ID, "superseded by the loader rewrite")
+	if err == nil {
+		t.Fatal("wontfix over a locked body acted, want a refusal")
+	}
+	for _, frag := range []string{"HTML comment", "body line 2", "text editor", "re-run", "nothing written"} {
+		if !strings.Contains(err.Error(), frag) {
+			t.Fatalf("the refusal does not name %q: %v", frag, err)
+		}
+	}
+	var where []string
+	if werr := filepath.WalkDir(repo, func(p string, d fs.DirEntry, err error) error {
+		if err == nil && !d.IsDir() && strings.HasPrefix(d.Name(), m.ID+"-") {
+			where = append(where, filepath.Base(filepath.Dir(p)))
+		}
+		return err
+	}); werr != nil {
+		t.Fatal(werr)
+	}
+	if len(where) != 1 || where[0] != "open" {
+		t.Fatalf("after the refusal the record sits in %v, want [open]", where)
+	}
+}
diff --git a/internal/surface/cli/cli.go b/internal/surface/cli/cli.go
index e166dab01..fb5f6af74 100644
--- a/internal/surface/cli/cli.go
+++ b/internal/surface/cli/cli.go
@@ -38,9 +38,11 @@ import (
 	"github.com/intentdriven/abcd/internal/core/oracle"
 	"github.com/intentdriven/abcd/internal/core/provenance"
 	"github.com/intentdriven/abcd/internal/core/record"
+	"github.com/intentdriven/abcd/internal/core/record/match"
 	"github.com/intentdriven/abcd/internal/core/rules"
 	"github.com/intentdriven/abcd/internal/core/spec"
 	"github.com/intentdriven/abcd/internal/core/surface"
+	"github.com/intentdriven/abcd/internal/core/tools"
 	"github.com/intentdriven/abcd/internal/core/update"
 	"github.com/intentdriven/abcd/internal/fsutil"
 	"github.com/intentdriven/abcd/internal/gitutil"
@@ -2665,12 +2667,25 @@ func createIntentFromText(cmd *cobra.Command, repoRoot, text string, opts intent
 		return err
 	}
 	opts.ProductionMode = mode
-	it, err := intent.CreateFromText(repoRoot, text, opts)
+	// The filing-time match (itd-2609212137116617): the ledger gathers the
+	// candidates, the create runs the match under its mint lock.
+	var m *intent.Matcher
+	cfg, refused := resolveMatch(cmd.ErrOrStderr(), "intent", repoRoot)
+	if cfg != nil {
+		m = &intent.Matcher{Threshold: cfg.Threshold, Candidates: func() ([]match.Candidate, error) {
+			return capture.MatchCandidates(repoRoot, *cfg)
+		}}
+	}
+	it, err := intent.CreateFromTextMatched(repoRoot, text, opts, m)
 	if err != nil {
 		return &exitError{Code: 2, Msg: "abcd intent: " + err.Error()}
 	}
+	if it.Match == nil {
+		it.Match = refused
+	}
 	return render(cmd.OutOrStdout(), asJSON, it, func(w io.Writer) {
 		fmt.Fprintf(w, "created %s (%s) — %s\n", it.ID, it.Bucket, termsafe.Sanitize(it.Path))
+		renderMatch(w, it.Match)
 	})
 }
 
@@ -3246,6 +3261,7 @@ func newAhoyCommand(asJSON *bool) *cobra.Command {
 		docsTarget    string
 		oracleBackend string
 		scanDeep      string
+		installTools  []string
 	)
 	installCmd := &cobra.Command{
 		Use:  "install",
@@ -3259,7 +3275,14 @@ func newAhoyCommand(asJSON *bool) *cobra.Command {
 			if err != nil {
 				return err
 			}
-			res, err := ahoy.Install(cwd, opts, newPrompter(cmd))
+			named, err := installToolNames(installTools)
+			if err != nil {
+				return err
+			}
+			p := newPrompter(cmd)
+			opts.ConfirmTool = toolConfirm(p, named, yes, cmd.ErrOrStderr())
+			opts.ApproveDependency = len(named) > 0
+			res, err := ahoy.Install(cwd, opts, p)
 			if err != nil {
 				return err
 			}
@@ -3324,6 +3347,7 @@ func newAhoyCommand(asJSON *bool) *cobra.Command {
 	installCmd.Flags().StringVar(&docsTarget, "docs-target", "", "which conventions file carries the managed block, which names abcd: claude_md | agents_md | both | skip (default skip)")
 	installCmd.Flags().StringVar(&oracleBackend, "oracle-backend", "", "oracle backend: host-delegated | native | cli | api | mcp")
 	installCmd.Flags().StringVar(&scanDeep, "scan-deep", "", "enable deep scan: true | false")
+	installCmd.Flags().StringSliceVar(&installTools, "install-tool", nil, "answer yes to installing this missing tool (repeatable): the answer a host's question tool relays; without it a tool is installed only on an answer typed at a terminal, never on the approve-everything flag, a piped answer or CI")
 	ahoyCmd.AddCommand(installCmd)
 
 	// uninstall
@@ -3613,6 +3637,57 @@ func optionalSkipReason(id string) string {
 	return ""
 }
 
+// installToolNames validates the --install-tool names against the tools
+// `ahoy install` checks for, refusing any other with the names it accepts.
+func installToolNames(names []string) (map[string]bool, error) {
+	accepted := map[string]bool{}
+	for _, n := range ahoy.DependencyTools {
+		accepted[n] = true
+	}
+	named := map[string]bool{}
+	for _, n := range names {
+		n = strings.TrimSpace(n)
+		if !accepted[n] {
+			return nil, &exitError{Code: 2, Msg: fmt.Sprintf("abcd ahoy install: --install-tool %q is not a tool ahoy install checks for; it checks for %s (nothing read, nothing written)",
+				termsafe.Sanitize(n), strings.Join(ahoy.DependencyTools, ", "))}
+		}
+		named[n] = true
+	}
+	return named, nil
+}
+
+// toolConfirm is the CLI's answer to the explain-then-install question
+// (itd-63). It is deliberately narrower than the category prompter: a piped
+// answer approves categories (iss-167), but installing a program is asked only
+// of a person at a terminal, or answered by naming the tool with
+// --install-tool, which is how a host relays the answer its own question tool
+// got. --yes never installs a tool. Every no carries the way to say yes.
+func toolConfirm(p ahoy.Prompter, named map[string]bool, yes bool, w io.Writer) tools.Confirm {
+	return func(e tools.Explanation) tools.Answer {
+		if named[e.Tool] {
+			return tools.Answer{Yes: true, Why: "named with --install-tool"}
+		}
+		if yes {
+			return tools.Answer{Why: "--yes never installs a tool; name it with --install-tool " + e.Tool + ", or run without --yes at a terminal"}
+		}
+		sp, ok := p.(*stdinPrompter)
+		if !ok || !sp.tty {
+			return tools.Answer{Why: "no terminal to ask at: abcd installs a tool only on an answer typed at a terminal, or with --install-tool " + e.Tool}
+		}
+		for _, line := range e.Lines() {
+			fmt.Fprintln(w, termsafe.Sanitize(line))
+		}
+		fmt.Fprintf(w, "Install %s now by running %s? [y/N] ", e.Tool, e.StepText())
+		line, _ := sp.r.ReadString('\n')
+		switch strings.ToLower(strings.TrimSpace(line)) {
+		case "y", "yes":
+			fmt.Fprintf(w, "running %s; a package manager can take a few minutes\n", e.StepText())
+			return tools.Answer{Yes: true, Why: "answered yes at the terminal"}
+		}
+		return tools.Answer{Why: "answered no at the terminal"}
+	}
+}
+
 // newPrompter returns the stdin-reading prompter. On a terminal it is the
 // interactive path, unchanged. When stdin is NOT a terminal the same prompter
 // reads the piped answers (iss-167): `yes | abcd ahoy install` is what a host
@@ -4073,6 +4148,10 @@ func newCaptureCommand(asJSON *bool) *cobra.Command {
 			if req.ProductionMode, err = resolveProductionMode(repoRoot, captureProductionMode); err != nil {
 				return err
 			}
+			// The filing-time match (itd-2609212137116617): configured through the
+			// layered reader, run by core under the ledger lock, never a refusal.
+			var matchRefused *match.Outcome
+			req.Match, matchRefused = resolveMatch(cmd.ErrOrStderr(), "capture", repoRoot)
 			// --lapsed-at has NO default and is never filled in for the caller: a
 			// lapse capture that omits the instant records none. The refusal that
 			// stood here is parked, not lifted (iss-2609091009111294): the instant stays
@@ -4089,8 +4168,12 @@ func newCaptureCommand(asJSON *bool) *cobra.Command {
 				}
 				return captureRefusal("", err)
 			}
+			if res.Match == nil {
+				res.Match = matchRefused
+			}
 			return renderLedger(cmd.OutOrStdout(), *asJSON, repoRoot, res, func(w io.Writer) {
 				fmt.Fprintf(w, "captured %s (%s) — %s\n", res.ID, res.Status, termsafe.Sanitize(res.Path))
+				renderMatch(w, res.Match)
 				// Folder membership is a status only once the file is committed
 				// (iss-2609100508570527): say so at the write, where it is cheap.
 				if res.Uncommitted {
diff --git a/internal/surface/cli/match.go b/internal/surface/cli/match.go
new file mode 100644
index 000000000..fddf5731d
--- /dev/null
+++ b/internal/surface/cli/match.go
@@ -0,0 +1,58 @@
+package cli
+
+import (
+	"fmt"
+	"io"
+
+	"github.com/intentdriven/abcd/internal/core/layered"
+	"github.com/intentdriven/abcd/internal/core/record/match"
+	"github.com/intentdriven/abcd/internal/fsutil"
+	"github.com/intentdriven/abcd/internal/termsafe"
+)
+
+// resolveMatch reads match.threshold and match.fields for a filing through the
+// layered configuration reader (itd-2609212137116617). A configuration the
+// reader refuses never refuses the filing, because a finding lost to a
+// misspelt key is the failure the match exists to prevent: it comes back as
+// the reason the match compared nothing, which the verb prints, and the record
+// is filed unlinked.
+func resolveMatch(stderr io.Writer, verb, repoRoot string) (*match.Config, *match.Outcome) {
+	roots, notes := layered.RootsFor(repoRoot)
+	for _, n := range notes {
+		fmt.Fprintf(stderr, "abcd %s\n", termsafe.Sanitize(fsutil.RedactHome(n)))
+	}
+	cfg, err := match.LoadConfig(roots)
+	if err != nil {
+		o := match.Skip(match.DefaultThreshold, "the match configuration is refused ("+
+			fsutil.RedactHome(err.Error())+"), so the record is filed without matching; fix or remove the key")
+		return nil, &o
+	}
+	return &cfg, nil
+}
+
+// renderMatch prints a filing's match: each link written, each match past the
+// link cap, the count of near misses (--json lists them with their scores), or
+// why nothing was compared. It prints nothing when no match was asked for.
+func renderMatch(w io.Writer, o *match.Outcome) {
+	if o == nil {
+		return
+	}
+	if o.Skipped != "" {
+		fmt.Fprintf(w, "  not matched: %s\n", termsafe.Sanitize(o.Skipped))
+	}
+	for _, m := range o.Matches {
+		state := "link written"
+		if !m.Linked {
+			state = "listed, not linked"
+		}
+		fmt.Fprintf(w, "  matched %s — %s (score %.3f, threshold %.2f): %s; confirm it by leaving the link, or remove the line\n",
+			termsafe.Sanitize(m.ID), m.Relation, m.Score, o.Threshold, state)
+	}
+	if o.Skipped == "" && len(o.Matches) == 0 {
+		fmt.Fprintf(w, "  no match at threshold %.2f among %d record(s)", o.Threshold, o.Compared)
+		if n := len(o.NearMisses); n > 0 {
+			fmt.Fprintf(w, "; %d near miss(es) below it, listed with their scores by --json", n)
+		}
+		fmt.Fprintln(w)
+	}
+}
diff --git a/internal/surface/cli/match_cli_test.go b/internal/surface/cli/match_cli_test.go
new file mode 100644
index 000000000..3c176d6bb
--- /dev/null
+++ b/internal/surface/cli/match_cli_test.go
@@ -0,0 +1,145 @@
+package cli
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// The filing-time match on the front door (itd-2609212137116617): `capture` and
+// the quoted-text `intent` create print each link they wrote, --json carries
+// the whole outcome with the near misses and their scores, and a configuration
+// the reader refuses files the record unlinked rather than refusing it.
+
+const (
+	cliFinding = "The capture ledger reader silently skips a record whose frontmatter carries " +
+		"a duplicated key, so the finding disappears from every listing without a warning."
+	cliDouble = "Capture ledger reader silently skips any record whose frontmatter carries a " +
+		"duplicated key: the finding disappears from every listing, and no warning is printed."
+	cliFiller1 = "The site builder renders a stale anchor for a heading renamed since the last build."
+	cliFiller2 = "The history store drops a transcript that exceeds its byte budget without saying so."
+)
+
+// matchRepo is a checkout with its own HOME, so the machine configuration
+// layer is the fixture's, and two unrelated issues to weigh terms against.
+func matchRepo(t *testing.T) string {
+	t.Helper()
+	repo := captureLedgerRepo(t)
+	t.Setenv("HOME", filepath.Join(t.TempDir(), "home"))
+	if err := os.MkdirAll(os.Getenv("HOME"), 0o700); err != nil {
+		t.Fatal(err)
+	}
+	runCLI(t, "capture", cliFiller1)
+	runCLI(t, "capture", cliFiller2)
+	return repo
+}
+
+type captureJSON struct {
+	ID    string `json:"id"`
+	Path  string `json:"path"`
+	Match *struct {
+		Threshold float64 `json:"threshold"`
+		Skipped   string  `json:"skipped"`
+		Matches   []struct {
+			ID       string  `json:"id"`
+			Relation string  `json:"relation"`
+			Score    float64 `json:"score"`
+			Linked   bool    `json:"linked"`
+		} `json:"matches"`
+		NearMisses []struct {
+			ID    string  `json:"id"`
+			Score float64 `json:"score"`
+		} `json:"near_misses"`
+	} `json:"match"`
+}
+
+func captureJSONOf(t *testing.T, out []byte) captureJSON {
+	t.Helper()
+	var c captureJSON
+	if err := json.Unmarshal(out, &c); err != nil {
+		t.Fatalf("not JSON: %v\n%s", err, out)
+	}
+	return c
+}
+
+func TestCaptureVerbLinksAndPrintsTheMatch(t *testing.T) {
+	repo := matchRepo(t)
+	first := captureJSONOf(t, runCLI(t, "capture", cliFinding, "--json"))
+
+	out := string(runCLI(t, "capture", cliDouble))
+	if !strings.Contains(out, "matched "+first.ID+" — duplicates") || !strings.Contains(out, "link written") {
+		t.Fatalf("the verb did not print the match against %s:\n%s", first.ID, out)
+	}
+	// The newest record is the double; it carries the link.
+	matches, _ := filepath.Glob(filepath.Join(repo, ".abcd/work/issues/open/iss-*.md"))
+	linked := 0
+	for _, m := range matches {
+		b, _ := os.ReadFile(m)
+		if strings.Contains(string(b), "\nduplicates: ["+first.ID+"]\n") {
+			linked++
+		}
+	}
+	if linked != 1 {
+		t.Fatalf("%d record(s) carry the duplicates link, want 1", linked)
+	}
+}
+
+func TestCaptureVerbJSONListsNearMisses(t *testing.T) {
+	repo := matchRepo(t)
+	runCLI(t, "capture", cliFinding)
+	if err := os.WriteFile(filepath.Join(repo, ".abcd/config.json"), []byte(`{"match":{"threshold":0.99}}`), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	c := captureJSONOf(t, runCLI(t, "capture", cliDouble, "--json"))
+	if c.Match == nil || c.Match.Threshold != 0.99 || len(c.Match.Matches) != 0 {
+		t.Fatalf("match = %+v, want nothing above the configured 0.99", c.Match)
+	}
+	if len(c.Match.NearMisses) == 0 || c.Match.NearMisses[0].Score <= 0 {
+		t.Fatalf("near misses = %+v, want the finding with its score", c.Match.NearMisses)
+	}
+	b, _ := os.ReadFile(filepath.Join(repo, c.Path))
+	if strings.Contains(string(b), "duplicates:") || strings.Contains(string(b), "refines:") {
+		t.Fatalf("a link was written below the threshold:\n%s", b)
+	}
+}
+
+func TestCaptureVerbFilesThroughARefusedConfiguration(t *testing.T) {
+	repo := matchRepo(t)
+	runCLI(t, "capture", cliFinding)
+	if err := os.WriteFile(filepath.Join(repo, ".abcd/config.json"), []byte(`{"match":{"treshold":0.5}}`), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	out := string(runCLI(t, "capture", cliDouble))
+	if !strings.Contains(out, "captured iss-") || !strings.Contains(out, "not matched") || !strings.Contains(out, "match.treshold") {
+		t.Fatalf("want the capture filed and the refused key named:\n%s", out)
+	}
+}
+
+func TestIntentCreateVerbLinksAndPrintsTheMatch(t *testing.T) {
+	repo := matchRepo(t)
+	dir := filepath.Join(repo, ".abcd/development/intents/planned")
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "itd-9-reader.md"), []byte("---\nid: itd-9\nslug: reader\nspec_id: null\nkind: null\n---\n\n# Ledger reader skips\n\n## Press Release\n\n> "+cliFinding+"\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	out := string(runCLI(t, "intent", cliDouble))
+	if !strings.Contains(out, "created itd-") || !strings.Contains(out, "matched itd-9 — duplicates") {
+		t.Fatalf("the create did not print the match against itd-9:\n%s", out)
+	}
+	// Filed again, the text now doubles itd-9 and the draft just created.
+	c := captureJSONOf(t, runCLI(t, "intent", cliDouble+" Filed once more.", "--json"))
+	if c.Match == nil || len(c.Match.Matches) != 2 {
+		t.Fatalf("--json match = %+v, want itd-9 and the first draft", c.Match)
+	}
+	named := false
+	for _, m := range c.Match.Matches {
+		named = named || (m.ID == "itd-9" && m.Linked)
+	}
+	if !named {
+		t.Fatalf("--json match = %+v, want itd-9 linked", c.Match)
+	}
+}