diff --git a/.agents/lessons.md b/.agents/lessons.md
index fae1b79..d9722cd 100644
--- a/.agents/lessons.md
+++ b/.agents/lessons.md
@@ -13,5 +13,5 @@ Each entry is a single bullet: `- **<topic>** — <lesson>`. Newest entries at t
 - **backticks inside SQL or help-text template literals** — never put a literal backtick inside a `` `...` `` template-literal string. `db.ts` SQL DDL strings (multi-line CREATE TABLE templates) and `printQueryCmdHelp()` (multi-line help text) are both `` `...` `` template literals; an inner backtick — typically a Markdown-style code-fence around a flag like `` `--full` `` — terminates the literal early and the parser blows up several lines later with cryptic "expected `,` or `)`" errors. **Use plain prose in those strings** (`--full` not `` `--full` ``), or escape (`` \` ``) if you really need the character. Hit twice (B.7 + B.6 PR #30); the lesson is general — applies to any TS template literal that gets pasted prose later, not just SQL / help text.
 - **STOP-before-Grep applies to symbol lookups too** — `Grep` for symbol names like `printQueryResult`, `getCurrentCommit`, `dropAll` violates the [`codemap` rule](rules/codemap.md). The codemap query `SELECT file_path, line_start FROM symbols WHERE name = '<X>'` answers it faster and without scanning. Reach for `Grep` only when the question is content-shaped (regex over file bodies, finding pattern usages inside function bodies, etc.) — not when it's "where is X defined / who calls X / what does file Y export." This was a PR #30 self-correction.
 - **PR / issue / comment bodies always go through a temp file** — never pass markdown bodies via shell heredoc to `gh pr create --body "$(cat <<'EOF'…)"` / `gh pr edit --body …` / `gh pr comment --body …` / `gh issue create --body …` / `gh api` `--field body=…`. Backticks inside the heredoc (every code span and code fence) get shell-escaped to `\`` and render literally on GitHub — every recipe id, file path, flag, SQL fragment, and code fence in the rendered body comes out as `\`coverage\``instead of`coverage`. Pattern: write the body to a temp file (`Write`to`/tmp/pr-<n>-body.md`), pass `--body-file /tmp/pr-<n>-body.md`, then delete the temp file. Cost is one extra tool call; saves redoing every PR body that has more than a few backticks. Hit on PR #57 — final body was a wall of `\`` artifacts until rewritten via temp file.
-- **Never commit absolute local user paths** — no `/Users/<name>/…`, `/home/<name>/…`, `~/…`, or `file:///` URIs in any tracked doc, code, comment, or PR body. Reasons: (1) leaks the maintainer's directory structure / username to public mirrors; (2) every other contributor's paths differ — the reference is dead on their machine; (3) a `git clone` of someone else's machine isn't a fact we can cite as a "source for deep-dives" — public upstream URLs are. Pattern: cite `https://github.com/<org>/<repo>` (with optional `/tree/<sha>/<path>`) for upstream sources; use repo-relative paths (`docs/foo.md`, `src/bar.ts`) for in-tree references. Hit on PR #58 first draft — referenced the local fallow clone path in the research note before the user caught it.
+- **Never commit absolute local user paths** — no `/Users/<name>/…`, `/home/<name>/…`, `~/…`, or `file:///` URIs in any tracked doc, code, comment, or PR body. Reasons: (1) leaks the maintainer's directory structure / username to public mirrors; (2) every other contributor's paths differ — the reference is dead on their machine; (3) a `git clone` of someone else's machine isn't a fact we can cite as a "source for deep-dives" — public upstream URLs are. Pattern: cite `https://github.com/<org>/<repo>` (with optional `/tree/<sha>/<path>`) for upstream sources; use repo-relative paths (`docs/foo.md`, `src/bar.ts`) for in-tree references. Hit on PR #58 first draft — referenced a local peer-repo clone path in a research note before the user caught it.
 - **Prescriptive research notes pin every concrete claim before recommending a ship sequence** — when a research/plan-shape doc proposes work (effort estimates, capability inventories, "we already do X" framing), every concrete claim needs a `file:line` / `codemap query` / `rg` / `--recipes-json` reference a reviewer can re-run. Reasoning-from-substrate intuition without pinning ships errors: "the AST walker already counts nodes" / "fan-in detects orphans" / "the `re_export_source` column doesn't exist" — all real errors caught on PR #58 by triangulating against the codebase. Don't ship a peer / parallel "descriptive baseline" doc to triangulate against (Rule 1 violation — it duplicates `architecture.md` / `db.ts` / `--recipes-json`); instead, either (a) pin claims in the prescriptive doc itself, or (b) self-audit by re-running every claim against the canonical home before committing. Either path beats the "dual descriptive + prescriptive doc" pattern on docs-governance grounds.
diff --git a/.agents/rules/codemap.md b/.agents/rules/codemap.md
index 8416c40..7a29e83 100644
--- a/.agents/rules/codemap.md
+++ b/.agents/rules/codemap.md
@@ -12,36 +12,38 @@ A local database (default **`.codemap/index.db`**) indexes structure: symbols, i
 
 ## CLI (this repository)
 
-| Context                        | Incremental index  | Query                                                                                                                                                                                                                                                                                                      |
-| ------------------------------ | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Default** — from this clone  | `bun src/index.ts` | `bun src/index.ts query --json "<SQL>"`                                                                                                                                                                                                                                                                    |
-| Same entry                     | `bun run dev`      | (same as first row)                                                                                                                                                                                                                                                                                        |
-| Query (ASCII table — optional) | —                  | `bun src/index.ts query "<SQL>"`                                                                                                                                                                                                                                                                           |
-| Recipe                         | —                  | `bun src/index.ts query --json --recipe fan-out` (see **`bun src/index.ts query --help`**)                                                                                                                                                                                                                 |
-| Parametrised recipe            | —                  | `bun src/index.ts query --json --recipe find-symbol-by-kind --params kind=function,name_pattern=%Query%` — params declared in recipe `.md` frontmatter and validated before SQL binding.                                                                                                                   |
-| Boundary violations            | —                  | `bun src/index.ts query --json --recipe boundary-violations` — joins `dependencies` × `boundary_rules` (config-driven) via SQLite `GLOB`. `.codemap/config.ts` `boundaries: [{name, from_glob, to_glob, action?}]`; default `action: "deny"`. SARIF / annotations work via the `file_path` alias.          |
-| Rename preview                 | —                  | `bun src/index.ts query --recipe rename-preview --params old=usePermissions,new=useAccess,kind=function --format diff` — read-only unified diff; codemap never writes files.                                                                                                                               |
-| Recipe catalog / SQL           | —                  | `bun src/index.ts query --recipes-json` · `bun src/index.ts query --print-sql fan-out`                                                                                                                                                                                                                     |
-| Counts only                    | —                  | `bun src/index.ts query --json --summary -r deprecated-symbols`                                                                                                                                                                                                                                            |
-| PR-scoped rows                 | —                  | `bun src/index.ts query --json --changed-since origin/main -r fan-out`                                                                                                                                                                                                                                     |
-| Bucket by owner / dir / pkg    | —                  | `bun src/index.ts query --json --group-by directory -r fan-in`                                                                                                                                                                                                                                             |
-| Save / diff a baseline         | —                  | `bun src/index.ts query --save-baseline -r visibility-tags` then `… --json --baseline -r visibility-tags`                                                                                                                                                                                                  |
-| List / drop baselines          | —                  | `bun src/index.ts query --baselines` · `bun src/index.ts query --drop-baseline <name>`                                                                                                                                                                                                                     |
-| Per-delta audit                | —                  | `bun src/index.ts audit --json --baseline base` (auto-resolves `base-files` / `base-dependencies` / `base-deprecated`)                                                                                                                                                                                     |
-| Audit vs git ref               | —                  | `bun src/index.ts audit --base origin/main --json` — worktree+reindex against any committish; sub-100ms second run via sha-keyed cache. Mutually exclusive with `--baseline`; per-delta overrides compose. Add `--format sarif` to emit SARIF 2.1.0 directly (one rule per delta key; severity `warning`). |
-| MCP server (for agent hosts)   | —                  | `bun src/index.ts mcp [--no-watch] [--debounce <ms>]` — JSON-RPC on stdio; one tool per CLI verb. Watcher default-ON since 2026-05. See **MCP** section below.                                                                                                                                             |
-| HTTP server (for non-MCP)      | —                  | `bun src/index.ts serve [--host 127.0.0.1] [--port 7878] [--token <secret>] [--no-watch] [--debounce <ms>]` — same tool taxonomy over POST /tool/{name}. Watcher default-ON since 2026-05.                                                                                                                 |
-| Watch mode (live reindex)      | —                  | `bun src/index.ts watch [--debounce 250] [--quiet]` — standalone long-running process; debounced reindex on file changes. `mcp` / `serve` boot the watcher in-process by default — pass `--no-watch` (or `CODEMAP_WATCH=0`) to opt out.                                                                    |
-| Targeted read (metadata)       | —                  | `bun src/index.ts show <name> [--kind <k>] [--in <path>] [--json]` — file:line + signature                                                                                                                                                                                                                 |
-| Targeted read (source text)    | —                  | `bun src/index.ts snippet <name> [--kind <k>] [--in <path>] [--json]` — same lookup + source from disk + stale flag                                                                                                                                                                                        |
-| Impact (blast-radius walker)   | —                  | `bun src/index.ts impact <target> [--direction up\|down\|both] [--depth N] [--via <b>] [--limit N] [--summary] [--json]` — replaces hand-composed `WITH RECURSIVE` queries                                                                                                                                 |
-| Coverage ingest                | —                  | `bun src/index.ts ingest-coverage <path> [--json]` — Istanbul (`coverage-final.json`) or LCOV (`lcov.info`); format auto-detected. Joinable to `symbols` for "untested AND dead" queries.                                                                                                                  |
-| SARIF / GH annotations         | —                  | `bun src/index.ts query --recipe deprecated-symbols --format sarif` · `… --format annotations`                                                                                                                                                                                                             |
-| `--ci` aggregate flag          | —                  | `bun src/index.ts query -r deprecated-symbols --ci` (or `audit --base origin/main --ci`) — aliases `--format sarif` + non-zero exit when findings/additions surfaced + suppresses the no-locatable-rows stderr warning. Mutually exclusive with `--json` / `--format <other>`.                             |
-| PR-comment renderer            | —                  | `bun src/index.ts pr-comment <input.json>` (or `-` for stdin) — renders an audit JSON envelope or SARIF doc as a markdown PR-summary comment. Pipe to `gh pr comment <PR> -F -`. Useful for private repos without GHAS, aggregate audit deltas, or bot-context seeding.                                    |
-| Mermaid graph (≤50 edges)      | —                  | `bun src/index.ts query --format mermaid 'SELECT from_path AS "from", to_path AS "to" FROM dependencies LIMIT 50'` — recipes / SQL must alias columns to `{from, to, label?, kind?}`; rejects unbounded inputs.                                                                                            |
-| Diff preview                   | —                  | `bun src/index.ts query --format diff '<SQL returning file_path, line_start, before_pattern, after_pattern>'` — read-only unified diff; `--format diff-json` returns structured hunks for agents.                                                                                                          |
-| FTS5 full-text (opt-in)        | `--with-fts`       | `bun src/index.ts --with-fts --full` enables `source_fts` virtual table; `query --recipe text-in-deprecated-functions` demos JOINs.                                                                                                                                                                        |
+| Context                        | Incremental index  | Query                                                                                                                                                                                                                                                                                                                                                               |
+| ------------------------------ | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Default** — from this clone  | `bun src/index.ts` | `bun src/index.ts query --json "<SQL>"`                                                                                                                                                                                                                                                                                                                             |
+| Same entry                     | `bun run dev`      | (same as first row)                                                                                                                                                                                                                                                                                                                                                 |
+| Query (ASCII table — optional) | —                  | `bun src/index.ts query "<SQL>"`                                                                                                                                                                                                                                                                                                                                    |
+| Recipe                         | —                  | `bun src/index.ts query --json --recipe fan-out` (see **`bun src/index.ts query --help`**)                                                                                                                                                                                                                                                                          |
+| Outcome alias                  | —                  | `bun src/index.ts dead-code` · `deprecated` · `boundaries` · `hotspots` · `coverage-gaps` — thin wrappers over `query --recipe <id>`; every `query` flag passes through. See `bun src/index.ts <alias> --help` for the wrapped recipe id. Capped at 5 to avoid sprawl.                                                                                              |
+| Suppressions (opt-in)          | —                  | `// codemap-ignore-next-line <recipe-id>` and `// codemap-ignore-file <recipe-id>` (also `#`, `--`, `<!--`, `/*` leaders) populate `suppressions(file_path, line_number, recipe_id)`. Recipes opt in via `LEFT JOIN`; `untested-and-dead` (line + file) and `unimported-exports` (file only) honor today.                                                           |
+| Parametrised recipe            | —                  | `bun src/index.ts query --json --recipe find-symbol-by-kind --params kind=function,name_pattern=%Query%` — params declared in recipe `.md` frontmatter and validated before SQL binding.                                                                                                                                                                            |
+| Boundary violations            | —                  | `bun src/index.ts query --json --recipe boundary-violations` — joins `dependencies` × `boundary_rules` (config-driven) via SQLite `GLOB`. `.codemap/config.ts` `boundaries: [{name, from_glob, to_glob, action?}]`; default `action: "deny"`. SARIF / annotations work via the `file_path` alias.                                                                   |
+| Rename preview                 | —                  | `bun src/index.ts query --recipe rename-preview --params old=usePermissions,new=useAccess,kind=function --format diff` — read-only unified diff; codemap never writes files.                                                                                                                                                                                        |
+| Recipe catalog / SQL           | —                  | `bun src/index.ts query --recipes-json` · `bun src/index.ts query --print-sql fan-out`                                                                                                                                                                                                                                                                              |
+| Counts only                    | —                  | `bun src/index.ts query --json --summary -r deprecated-symbols`                                                                                                                                                                                                                                                                                                     |
+| PR-scoped rows                 | —                  | `bun src/index.ts query --json --changed-since origin/main -r fan-out`                                                                                                                                                                                                                                                                                              |
+| Bucket by owner / dir / pkg    | —                  | `bun src/index.ts query --json --group-by directory -r fan-in`                                                                                                                                                                                                                                                                                                      |
+| Save / diff a baseline         | —                  | `bun src/index.ts query --save-baseline -r visibility-tags` then `… --json --baseline -r visibility-tags`                                                                                                                                                                                                                                                           |
+| List / drop baselines          | —                  | `bun src/index.ts query --baselines` · `bun src/index.ts query --drop-baseline <name>`                                                                                                                                                                                                                                                                              |
+| Per-delta audit                | —                  | `bun src/index.ts audit --json --baseline base` (auto-resolves `base-files` / `base-dependencies` / `base-deprecated`)                                                                                                                                                                                                                                              |
+| Audit vs git ref               | —                  | `bun src/index.ts audit --base origin/main --json` — worktree+reindex against any committish; sub-100ms second run via sha-keyed cache. Mutually exclusive with `--baseline`; per-delta overrides compose. Add `--format sarif` to emit SARIF 2.1.0 directly (one rule per delta key; severity `warning`).                                                          |
+| MCP server (for agent hosts)   | —                  | `bun src/index.ts mcp [--no-watch] [--debounce <ms>]` — JSON-RPC on stdio; one tool per CLI verb. Watcher default-ON since 2026-05. See **MCP** section below.                                                                                                                                                                                                      |
+| HTTP server (for non-MCP)      | —                  | `bun src/index.ts serve [--host 127.0.0.1] [--port 7878] [--token <secret>] [--no-watch] [--debounce <ms>]` — same tool taxonomy over POST /tool/{name}. Watcher default-ON since 2026-05.                                                                                                                                                                          |
+| Watch mode (live reindex)      | —                  | `bun src/index.ts watch [--debounce 250] [--quiet]` — standalone long-running process; debounced reindex on file changes. `mcp` / `serve` boot the watcher in-process by default — pass `--no-watch` (or `CODEMAP_WATCH=0`) to opt out.                                                                                                                             |
+| Targeted read (metadata)       | —                  | `bun src/index.ts show <name> [--kind <k>] [--in <path>] [--json]` — file:line + signature                                                                                                                                                                                                                                                                          |
+| Targeted read (source text)    | —                  | `bun src/index.ts snippet <name> [--kind <k>] [--in <path>] [--json]` — same lookup + source from disk + stale flag                                                                                                                                                                                                                                                 |
+| Impact (blast-radius walker)   | —                  | `bun src/index.ts impact <target> [--direction up\|down\|both] [--depth N] [--via <b>] [--limit N] [--summary] [--json]` — replaces hand-composed `WITH RECURSIVE` queries                                                                                                                                                                                          |
+| Coverage ingest                | —                  | `bun src/index.ts ingest-coverage <path> [--runtime] [--json]` — Istanbul (`coverage-final.json`) and LCOV (`lcov.info`) auto-detect from path; V8 is **opt-in** via `--runtime` (treats `<path>` as a `NODE_V8_COVERAGE=...`-style directory of `coverage-*.json` dumps). Joinable to `symbols` for "untested AND dead" queries. Local-only — no SaaS aggregation. |
+| SARIF / GH annotations         | —                  | `bun src/index.ts query --recipe deprecated-symbols --format sarif` · `… --format annotations`                                                                                                                                                                                                                                                                      |
+| `--ci` aggregate flag          | —                  | `bun src/index.ts query -r deprecated-symbols --ci` (or `audit --base origin/main --ci`) — aliases `--format sarif` + non-zero exit when findings/additions surfaced + suppresses the no-locatable-rows stderr warning. Mutually exclusive with `--json` / `--format <other>`.                                                                                      |
+| PR-comment renderer            | —                  | `bun src/index.ts pr-comment <input.json>` (or `-` for stdin) — renders an audit JSON envelope or SARIF doc as a markdown PR-summary comment. Pipe to `gh pr comment <PR> -F -`. Useful for private repos without GHAS, aggregate audit deltas, or bot-context seeding.                                                                                             |
+| Mermaid graph (≤50 edges)      | —                  | `bun src/index.ts query --format mermaid 'SELECT from_path AS "from", to_path AS "to" FROM dependencies LIMIT 50'` — recipes / SQL must alias columns to `{from, to, label?, kind?}`; rejects unbounded inputs.                                                                                                                                                     |
+| Diff preview                   | —                  | `bun src/index.ts query --format diff '<SQL returning file_path, line_start, before_pattern, after_pattern>'` — read-only unified diff; `--format diff-json` returns structured hunks for agents.                                                                                                                                                                   |
+| FTS5 full-text (opt-in)        | `--with-fts`       | `bun src/index.ts --with-fts --full` enables `source_fts` virtual table; `query --recipe text-in-deprecated-functions` demos JOINs.                                                                                                                                                                                                                                 |
 
 **Recipe metadata:** with **`--json`**, recipes that define an `actions` template append it to every row (kebab-case verb + description — e.g. `fan-out` → `review-coupling`). Under `--baseline`, actions attach to the **`added`** rows only. Parametrised recipes declare `params` in `.md` frontmatter; pass values with `--params key=value[,key=value]` (repeatable; last value wins). Inspect both via **`--recipes-json`**. Ad-hoc SQL never carries actions or params.
 
diff --git a/.agents/rules/docs-governance.md b/.agents/rules/docs-governance.md
index e4dee1f..2d6f2dd 100644
--- a/.agents/rules/docs-governance.md
+++ b/.agents/rules/docs-governance.md
@@ -33,7 +33,7 @@ The canonical Rules (1–9) live in [`docs/README.md`](../../docs/README.md) —
 
 1. **Anchor preservation** — slim READMEs keep cited rule numbers and section anchors. Grep before any slim: `rg "Rule [0-9]+" docs/` and `rg "<doc-path>(#[a-z-]+)?"`.
 2. **Anti-bloat meta-rule** — don't add a rule until there's content that needs it. Same for ownership-table rows.
-3. **Repo-level vs in-source** — repo-wide tool evaluations + adoption (oxlint, future plugins) live in `.agents/`, not as permanent `docs/research/` files. A `docs/research/` file may motivate the adoption, but the rule + skill earn the permanent home. (Precedent: [`research/fallow.md`](../../docs/research/fallow.md) was closed in 2026-05 once peer-tool framing went off-mission — its tracker shape is no longer the ongoing-research pattern; for current positioning see [`research/non-goals-reassessment-2026-05.md`](../../docs/research/non-goals-reassessment-2026-05.md).)
+3. **Repo-level vs in-source** — repo-wide tool evaluations + adoption (oxlint, future plugins) live in `.agents/`, not as permanent `docs/research/` files. A `docs/research/` file may motivate the adoption, but the rule + skill earn the permanent home. Per-tool tracker notes (peer-tool comparisons, adoption-candidate logs) are an anti-pattern — peer-tool framing goes off-mission fast; positioning lives in [`docs/why-codemap.md`](../../docs/why-codemap.md) and [`research/non-goals-reassessment-2026-05.md`](../../docs/research/non-goals-reassessment-2026-05.md), not in tracker files.
 
 ## Existence test (apply on every doc-touching PR)
 
diff --git a/.agents/skills/audit-pr-architecture/SKILL.md b/.agents/skills/audit-pr-architecture/SKILL.md
index 2ea6d70..c6b658a 100644
--- a/.agents/skills/audit-pr-architecture/SKILL.md
+++ b/.agents/skills/audit-pr-architecture/SKILL.md
@@ -10,7 +10,7 @@ Mid-flight or post-merge structural review of a PR against the repo's own archit
 This skill exists because:
 
 - Lightweight STOP signals (new top-level src/ folder, new shared util with 3+ consumers, folder past ~15 files without `index.ts`, files moved across module boundaries) miss **content-driven** smells (twin wrappers, incomplete lifts, dead leftovers from a move) that show up only after the PR has been opened.
-- The audit recipe (codemap reindex → boundary queries → fallow audit → cross-check rules → write findings) is reusable but lived nowhere before this skill — every audit was rebuilding it from scratch.
+- The audit recipe (codemap reindex → boundary queries → dead-code / complexity recipes → cross-check rules → write findings) is reusable but lived nowhere before this skill — every audit was rebuilding it from scratch.
 
 ## When to fire
 
@@ -88,26 +88,28 @@ Read [`docs/architecture.md` § Layering](../../../docs/architecture.md#layering
 
 For a re-runnable kit, find the most recent open or recently-closed audit under `docs/audits/` and copy its § Boundary verification block. **Don't cite a specific audit file by name from this skill** — audits are mortal under [`docs-lifecycle-sweep`](../docs-lifecycle-sweep/SKILL.md), and naming one couples this skill's durability to its lifecycle.
 
-### 3. Run the fallow PR-audit
+### 3. Run codemap's structural-smell recipes
 
-Codemap is a TS project — fallow's PR-audit applies cleanly:
+Use codemap's own queries — same substrate for boundary checks, dead code, complexity, and unimported-export bloat:
 
 ```bash
-bunx fallow audit --base origin/main
+bun src/index.ts audit --base origin/main --json   # delta vs base ref
+bun src/index.ts query --json --recipe untested-and-dead
+bun src/index.ts query --json --recipe unimported-exports
+bun src/index.ts query --json --recipe high-complexity-untested
 ```
 
-Apply the duplication / complexity thresholds (translated from fallow's own audit-on-PR shape):
+Apply these verdicts to results:
 
-| Signal                                                                 | Verdict                                                  |
-| ---------------------------------------------------------------------- | -------------------------------------------------------- |
-| Clone group ≥40 LoC between sibling files of the same module / adapter | **Incomplete lift** — the orchestrator wasn't shared.    |
-| Clone family ≥3 groups across sibling files                            | **Structurally incomplete lift** — revisit the boundary. |
-| Function size ≥60 LoC in a wrapper / orchestrator                      | **Wrapper doing orchestration**, not adapter wiring.     |
-| Unused file (esp. file with the same name as one moved during the PR)  | **Dead leftover from the move** — delete.                |
-| Unused export of a type / fn referenced only inside the same folder    | **Public-surface bloat** — drop the `export`.            |
-| Unused dependency in `package.json`                                    | Out of scope for this audit unless the PR added it.      |
+| Signal                                                                                   | Verdict                                                  |
+| ---------------------------------------------------------------------------------------- | -------------------------------------------------------- |
+| Function size ≥60 LoC (`line_end - line_start` on `symbols`) in a wrapper / orchestrator | **Wrapper doing orchestration**, not adapter wiring.     |
+| `unimported-exports` row added by the PR                                                 | **Public-surface bloat** — drop the `export`.            |
+| `untested-and-dead` row co-located with files moved during the PR                        | **Dead leftover from the move** — delete.                |
+| `high-complexity-untested` row added by the PR                                           | **Untested orchestration** — split or test before merge. |
+| Unused dependency in `package.json`                                                      | Out of scope for this audit unless the PR added it.      |
 
-The thresholds (≥40 / ≥3) are **seed values** from fallow's own calibration. Re-tune as more codemap-shaped lifts land if the seed proves too tight or too loose.
+Duplication / structural-clone detection (AST-hash) is a [roadmap item](../../../docs/roadmap.md#backlog) and not yet a substrate column — for now, eyeball clones in the diff or use ad-hoc text grep.
 
 ### 4. Cross-check structural STOP signals
 
@@ -144,7 +146,7 @@ Doc shape — mirror the most recent audit under `docs/audits/` (or — if this
 
 **Status:** Open — pending PR #N follow-ups (or: Closed, all N findings shipped on the same branch).
 **Scope:** <one paragraph: what diff, what HEAD, what subtree(s)>.
-**Method:** <codemap query + fallow audit + cross-check; cite which queries>.
+**Method:** <codemap audit + structural-smell recipes + cross-check; cite which queries>.
 
 This audit follows [docs/README.md Rule 6](../README.md) (no inventory counts in evergreen prose) and [docs/README.md Rule 7](../README.md) (no line-number references). All numbers below are flagged "at audit time."
 
@@ -187,7 +189,7 @@ This audit follows [docs/README.md Rule 6](../README.md) (no inventory counts in
 
 ## Verification recipe
 
-<re-runnable bash block: codemap reindex + boundary queries + fallow audit + typecheck/lint/test>.
+<re-runnable bash block: codemap reindex + boundary queries + structural-smell recipes + typecheck/lint/test>.
 ```
 
 ## Closing this audit
@@ -213,4 +215,3 @@ Once findings are shipped (or deferred to `roadmap.md`):
 - [`docs-lifecycle-sweep`](../docs-lifecycle-sweep/SKILL.md) — operationalises docs-governance lifecycle on demand.
 - [`codemap`](../codemap/SKILL.md) — query patterns; the boundary-leak kit lives in § 2 here.
 - [`docs/architecture.md`](../../../docs/architecture.md) — the canonical source of codemap's layering; every audit derives its boundary kit from this file.
-- [fallow](https://github.com/fallow-rs/fallow) — `bunx fallow audit --base origin/main` thresholds.
diff --git a/.agents/skills/codemap/SKILL.md b/.agents/skills/codemap/SKILL.md
index b4c4796..21ef321 100644
--- a/.agents/skills/codemap/SKILL.md
+++ b/.agents/skills/codemap/SKILL.md
@@ -34,7 +34,11 @@ After **`bun run build`**, **`node dist/index.mjs query …`** or a linked **`co
 
 Replace placeholders (`'...'`) with your module path, file glob, or symbol name.
 
-**CLI shortcuts:** **`bun src/index.ts query --json --recipe <id>`** runs bundled SQL (preferred for agents). **`bun src/index.ts query --recipe <id>`** without **`--json`** prints a table. **`bun src/index.ts query --recipes-json`** prints every bundled recipe (**`id`**, **`description`**, **`sql`**, optional **`actions`**) as JSON (no index / DB required). **`bun src/index.ts query --print-sql <id>`** prints one recipe’s SQL only. Ids include **`fan-out`**, **`fan-out-sample`** (**`GROUP_CONCAT`** samples), **`fan-out-sample-json`** (same, but **`json_group_array`** — needs SQLite JSON1), **`fan-in`**, **`index-summary`**, **`files-largest`**, **`components-by-hooks`**, **`components-touching-deprecated`** (UNION of hook + call paths to `@deprecated` symbols), **`markers-by-kind`**, **`deprecated-symbols`**, **`refactor-risk-ranking`** (per-file `(fan_in + 1) × (100 - avg_coverage_pct)`), **`high-complexity-untested`** (cyclomatic complexity ≥ 10 + coverage < 50%; per-function), **`text-in-deprecated-functions`** (FTS5 ⨯ symbols ⨯ coverage demo — needs `--with-fts` enabled), **`unimported-exports`** (exports with no detectable importer; v1 doesn't follow re-export chains — see recipe `.md` for caveats), **`visibility-tags`**, **`barrel-files`**, **`files-hashes`**, **`untested-and-dead`** (exported AND uncalled AND uncovered), **`files-by-coverage`** (per-file rollup of statement coverage), **`worst-covered-exports`** (lowest-covered exported symbols) — see **`bun src/index.ts query --help`**.
+**Outcome aliases:** **`bun src/index.ts dead-code`** · **`deprecated`** · **`boundaries`** · **`hotspots`** · **`coverage-gaps`** — thin wrappers over `query --recipe <id>`. Every `query` flag passes through (`--json`, `--format sarif`, `--ci`, `--summary`, `--changed-since`, `--group-by`, `--params`, `--save-baseline`, `--baseline`). Run **`bun src/index.ts <alias> --help`** for the wrapped recipe id. Capped at 5 to avoid sprawl.
+
+**Suppressions (opt-in):** `// codemap-ignore-next-line <recipe-id>` and `// codemap-ignore-file <recipe-id>` (also `#`, `--`, `<!--`, `/*` leaders) get parsed into the `suppressions(file_path, line_number, recipe_id)` table. Recipe authors opt in by `LEFT JOIN`-ing on `(file_path, recipe_id)` with `line_number = 0` for file scope or `line_number = <row's line>` for next-line. Ad-hoc SQL is unaffected. No severity, no suppression-by-default, no universal-honor — consumer-chosen substrate. Today's opt-in recipes: `untested-and-dead` (line + file), `unimported-exports` (file only — exports has no `line_number`).
+
+**CLI shortcuts:** **`bun src/index.ts query --json --recipe <id>`** runs bundled SQL (preferred for agents). **`bun src/index.ts query --recipe <id>`** without **`--json`** prints a table. **`bun src/index.ts query --recipes-json`** prints every bundled recipe (**`id`**, **`description`**, **`sql`**, optional **`actions`**) as JSON (no index / DB required). **`bun src/index.ts query --print-sql <id>`** prints one recipe’s SQL only. Ids include **`fan-out`**, **`fan-out-sample`** (**`GROUP_CONCAT`** samples), **`fan-out-sample-json`** (same, but **`json_group_array`** — needs SQLite JSON1), **`fan-in`**, **`index-summary`**, **`files-largest`**, **`components-by-hooks`**, **`components-touching-deprecated`** (UNION of hook + call paths to `@deprecated` symbols), **`markers-by-kind`**, **`deprecated-symbols`**, **`refactor-risk-ranking`** (per-file `(fan_in + 1) × (100 - avg_coverage_pct)`), **`high-complexity-untested`** (cyclomatic complexity ≥ 10 + coverage < 50%; per-function), **`text-in-deprecated-functions`** (FTS5 ⨯ symbols ⨯ coverage demo — needs `--with-fts` enabled), **`unimported-exports`** (exports with no detectable importer; v1 doesn't follow re-export chains — see recipe `.md` for caveats), **`unused-type-members`** (advisory; field-level enumeration of `unimported-exports` joining `type_members`; codemap can't see indexed access / `keyof T` / mapped types / destructuring — see recipe `.md` for caveats), **`visibility-tags`**, **`barrel-files`**, **`files-hashes`**, **`untested-and-dead`** (exported AND uncalled AND uncovered), **`files-by-coverage`** (per-file rollup of statement coverage), **`worst-covered-exports`** (lowest-covered exported symbols) — see **`bun src/index.ts query --help`**.
 
 **Output flags** (compose with **`--recipe`** or ad-hoc SQL):
 
@@ -273,7 +277,7 @@ User-facing baselines saved by `codemap query --save-baseline`, replayed by `cod
 
 ### `coverage` — Statement coverage (user data, ingested via `codemap ingest-coverage`)
 
-Static coverage from Istanbul JSON or LCOV. Joinable to `symbols` for "what's untested?" queries. **Survives `--full` and SCHEMA bumps** — intentionally absent from `dropAll()`. Empty until first ingest.
+Coverage from Istanbul JSON, LCOV, or V8 runtime (`NODE_V8_COVERAGE=...` directory via `--runtime`). Joinable to `symbols` for "what's untested?" queries. **Survives `--full` and SCHEMA bumps** — intentionally absent from `dropAll()`. Empty until first ingest. V8 mode is local-only — no SaaS aggregation.
 
 | Column           | Type    | Description                                                                                              |
 | ---------------- | ------- | -------------------------------------------------------------------------------------------------------- |
diff --git a/.agents/skills/docs-governance/SKILL.md b/.agents/skills/docs-governance/SKILL.md
index 21ce1bc..f24175d 100644
--- a/.agents/skills/docs-governance/SKILL.md
+++ b/.agents/skills/docs-governance/SKILL.md
@@ -85,7 +85,7 @@ Same applies to ownership-table rows — a row exists when the file or folder it
 
 **Codemap-wide tool evaluations + adoption** (e.g. oxlint, future plugins) belong directly in `.agents/rules/` + `.agents/skills/` — not in `docs/research/`. The artifact that earns a permanent home isn't the evaluation; it's the rule + skill.
 
-A `docs/research/` file may **motivate** adoption of a repo-level tool (the precedent is [`research/competitive-scan-2026-04.md`](../../../docs/research/competitive-scan-2026-04.md), which drove PR #23), but the _adoption itself_ is repo-level — the rule lands under `.agents/rules/`, not as a permanent doc under `docs/research/`. The research note then slims to "what shipped" (per [`docs/README.md` Rule 8](../../../docs/README.md)) — or, if peer-tool framing goes off-mission entirely, closes with a status header and a pointer at the new canonical positioning home (the [`research/fallow.md`](../../../docs/research/fallow.md) precedent — closed 2026-05 when codemap's positioning shifted from "adoption-from-fallow" to its own intrinsic differentiation; see [`research/non-goals-reassessment-2026-05.md`](../../../docs/research/non-goals-reassessment-2026-05.md)).
+A `docs/research/` file may **motivate** adoption of a repo-level tool, but the _adoption itself_ is repo-level — the rule lands under `.agents/rules/`, not as a permanent doc under `docs/research/`. The research note then slims to "what shipped" (per [`docs/README.md` Rule 8](../../../docs/README.md)). **Per-tool tracker notes are an anti-pattern** — peer-tool framing goes off-mission fast; positioning lives in [`docs/why-codemap.md`](../../../docs/why-codemap.md) and [`research/non-goals-reassessment-2026-05.md`](../../../docs/research/non-goals-reassessment-2026-05.md), not in tracker files.
 
 ### 7. Cross-reference preservation discipline
 
@@ -158,11 +158,11 @@ The _one_ lifecycle, no "Slim & keep in plans/" option:
 
 ### Closing research
 
-A research file's job is the evaluation. When the evaluation concludes:
+A research file's job is the evaluation. When the evaluation concludes, follow the canonical [`docs/README.md` Rule 8](../../../docs/README.md) lifecycle:
 
-- **Adopted** → lift the decision-of-record into the relevant reference doc (`architecture.md`, `glossary.md`, etc.) or — for repo-level tools — into `.agents/rules/` + `.agents/skills/`. Delete the research file unless its comparison framework is reusable for future similar evaluations.
+- **Adopted** → lift the decision-of-record into the relevant reference doc (`architecture.md`, `glossary.md`, etc.) or — for repo-level tools — into `.agents/rules/` + `.agents/skills/`. **Slim the note to a "What shipped" appendix** linking to canonical homes (precedent: [`research/non-goals-reassessment-2026-05.md`](../../../docs/research/non-goals-reassessment-2026-05.md) — its § 8 errata + § Closed-out items pattern). **Exception:** § 6 anti-pattern files (per-tool trackers; peer-tool framing) get **deleted**, not slimmed — the framing was off-mission, not just stale, and a "What shipped" appendix would re-anchor the wrong mental model.
 - **Rejected** → add a `Status: Rejected (date) — <one-line reason>` header at the top. Keep the file. The rejection rationale is exactly what saves the next agent from re-litigating it.
-- **Open / Ongoing** → stays in `research/` with no status header (open is the default). Ongoing tool trackers (e.g. `research/<tool-name>.md`) are explicitly long-lived; they don't close until the tool is irrelevant.
+- **Open / Ongoing** → stays in `research/` with no status header (open is the default). Ongoing tool trackers (e.g. `research/<tool-name>.md`) are explicitly long-lived but **only when they aren't peer-tool trackers** — see § 6.
 
 ---
 
diff --git a/.changeset/outcome-aliases.md b/.changeset/outcome-aliases.md
new file mode 100644
index 0000000..7780dcd
--- /dev/null
+++ b/.changeset/outcome-aliases.md
@@ -0,0 +1,17 @@
+---
+"@stainless-code/codemap": patch
+---
+
+Outcome-shaped CLI aliases — five thin top-level verbs that wrap `query --recipe <id>`:
+
+- `codemap dead-code` → `query --recipe untested-and-dead`
+- `codemap deprecated` → `query --recipe deprecated-symbols`
+- `codemap boundaries` → `query --recipe boundary-violations`
+- `codemap hotspots` → `query --recipe fan-in`
+- `codemap coverage-gaps` → `query --recipe worst-covered-exports`
+
+Every `query` flag passes through (`--json`, `--format sarif|annotations|mermaid|diff|diff-json`, `--ci`, `--summary`, `--changed-since <ref>`, `--group-by owner|directory|package`, `--params key=value`, `--save-baseline`, `--baseline`). Run `codemap <alias> --help` for the wrapped recipe id.
+
+Closes the verb-obviousness gap — `codemap dead-code` is more discoverable than `codemap query --recipe untested-and-dead`. Capped at five to avoid alias-sprawl per [`roadmap.md`](../docs/roadmap.md); promote a sixth only when the recipe becomes a headline outcome.
+
+Mapping lives in `src/cli/aliases.ts` (`OUTCOME_ALIASES`); rewrite happens before dispatch in `src/cli/main.ts`. Pure CLI surface; no schema, no engine, no new substrate. Moat-A clean — the alias is a one-line `query --recipe <id>` rewrite, not a new primitive; the recipe IS the SQL.
diff --git a/.changeset/suppressions-substrate.md b/.changeset/suppressions-substrate.md
new file mode 100644
index 0000000..33b6256
--- /dev/null
+++ b/.changeset/suppressions-substrate.md
@@ -0,0 +1,11 @@
+---
+"@stainless-code/codemap": minor
+---
+
+`suppressions` substrate — opt-in recipe-suppression markers parsed from source comments. The markers parser now recognises `// codemap-ignore-next-line <recipe-id>` and `// codemap-ignore-file <recipe-id>` (also `#`, `--`, `<!--`, `/*` leaders for non-JS files) and writes them to a new `suppressions(file_path, line_number, recipe_id)` table. Two scopes encoded by `line_number`: positive = next-line (the directive sits one line above; `line_number` points at the suppressed line), `0` = file scope.
+
+Recipe authors opt in via `LEFT JOIN suppressions s ON s.file_path = … AND s.recipe_id = '<id>' AND (s.line_number = 0 OR s.line_number = <row's line>) WHERE s.id IS NULL`. Ad-hoc SQL is unaffected. Bundled recipes that opt in today: `untested-and-dead` (line + file) and `unimported-exports` (file only — `exports` has no `line_number` column, so per-line suppression isn't expressible there).
+
+**Stays consistent with the "no opinionated rule engine" Floor** — no severity, no suppression-by-default, no universal-honor model. The suppression is consumer-chosen substrate: recipe authors choose whether to honor it; consumers can override per recipe by writing project-local SQL that ignores suppressions or filters differently. The leader regex requires the directive to start a line (modulo whitespace) so directives never match inside string literals — both this clone's tests and recipe `.md` examples use the directive text in prose without polluting the index.
+
+Schema bumps to **10** — `--full` rebuild auto-runs on next index pass. `dropAll()` includes `suppressions` (index-data table, not user data). Surfaced in agent rules + skills + glossary + architecture schema docs per Rule 10.
diff --git a/.changeset/unused-type-members-recipe.md b/.changeset/unused-type-members-recipe.md
new file mode 100644
index 0000000..67a92b7
--- /dev/null
+++ b/.changeset/unused-type-members-recipe.md
@@ -0,0 +1,9 @@
+---
+"@stainless-code/codemap": patch
+---
+
+`unused-type-members` recipe — field-level enumeration of `type_members` whose owning type has no detectable importer in the project. Sister recipe to `unimported-exports`: same upstream signal at the type level, but JOINed against `type_members` so each row carries the field's name, type annotation, optionality, and readonly flag. Useful when planning a deletion of an interface and you need the full field inventory before drafting the codemod.
+
+**Strictly advisory.** Codemap doesn't track property access, so the recipe inherits all of `unimported-exports`'s false-positive classes plus the per-field opaqueness of indexed access (`T['field']`), `keyof T`, mapped types, type spreads, destructuring, and re-export chains. Output is a STARTING POINT for human review, never a "safe to delete" list. Bundled `.md` documents every caveat and includes tuning axes for project-local overrides.
+
+`unused-type-members` joins the standard recipe taxonomy and ships in `templates/recipes/unused-type-members.{sql,md}`. Reachable as `codemap query --recipe unused-type-members` (or via the `--format sarif` / `--format annotations` / `--ci` aggregate flags); rule id is `codemap.unused-type-members`. Golden-query expectation lives at `fixtures/golden/minimal/unused-type-members.json`. Pure recipe addition — no schema impact, no engine change.
diff --git a/.changeset/v8-runtime-coverage.md b/.changeset/v8-runtime-coverage.md
new file mode 100644
index 0000000..abad767
--- /dev/null
+++ b/.changeset/v8-runtime-coverage.md
@@ -0,0 +1,11 @@
+---
+"@stainless-code/codemap": minor
+---
+
+`codemap ingest-coverage --runtime <dir>` — V8 runtime coverage parser. Reads a `NODE_V8_COVERAGE=...`-style directory (one or more `coverage-<pid>-<ts>-<seq>.json` files) and dispatches to the existing `upsertCoverageRows` core through a new `ingestV8` parser. Each script's byte-offset ranges are converted to per-line hit counts via innermost-wins range walking (smaller, more specific ranges override the function-as-a-whole count — matches V8's documented semantics). Skips non-`file://` URLs (Node internals, `evalmachine.<anonymous>`); merges duplicate-URL scripts across dumps so multi-process test runs don't inflate `total_statements`.
+
+Format auto-detection is unchanged for files (`.json` → istanbul, `.info` → lcov, directory of either → probe both with explicit-error on ambiguity); `--runtime` is the explicit opt-in for V8 directories. The `coverage` table schema doesn't move — V8 rows write through the same `(file_path, name, line_start, hit_statements, total_statements, coverage_pct)` projection, so every existing JOIN (`untested-and-dead`, `files-by-coverage`, `worst-covered-exports`) works unchanged.
+
+Useful for "delete cold code with stronger evidence" agent flows: production-style traces from real test runs feed the same recipes that consume Istanbul/LCOV today. **Local-only — SaaS aggregation explicitly out of scope** (different product class). The parser stays in-process; no aggregation server, no upload primitive. New `format: "v8"` arm on the result envelope; existing `"istanbul" | "lcov"` consumers don't break.
+
+Engine module: `application/coverage-engine.ts` (added `ingestV8`, `V8ScriptCoverage`, `V8FunctionCoverage`, `V8CoveragePayload` exports). CLI module: `cli/cmd-ingest-coverage.ts` (added `--runtime` flag, `resolveV8Directory` helper that reads every top-level `*.json` in the directory and merges their `result` arrays). Pure additive — `--json` output gains `"format": "v8"` as a possible value.
diff --git a/README.md b/README.md
index e62f56c..1246c99 100644
--- a/README.md
+++ b/README.md
@@ -46,12 +46,14 @@ bun add @stainless-code/codemap
 
 ```bash
 codemap                                                      # incremental index (run once per session)
+codemap dead-code --json                                     # outcome alias → query --recipe untested-and-dead
 codemap query --json --recipe fan-out                        # bundled SQL via recipe id (alias: -r)
 codemap query --json "SELECT name, file_path FROM symbols WHERE name = 'foo'"  # ad-hoc SQL
 codemap --files src/a.ts src/b.tsx                           # targeted re-index after edits
 codemap validate --json                                      # detect stale / missing / unindexed files
 codemap context --compact --for "refactor auth"              # JSON envelope + intent-matched recipes
 codemap ingest-coverage coverage/coverage-final.json --json  # Istanbul / LCOV (auto-detected) → coverage table; joins with symbols
+NODE_V8_COVERAGE=.cov bun test && codemap ingest-coverage .cov --runtime --json  # V8 protocol (per-process dumps); local-only
 codemap agents init                                          # scaffold .agents/ rules + skills
 ```
 
@@ -77,6 +79,13 @@ codemap query "SELECT name, file_path FROM symbols LIMIT 10"
 # Bundled SQL (same as skill examples): fan-out rankings
 codemap query --json --recipe fan-out
 codemap query --json --recipe fan-out-sample
+# Outcome aliases — thin wrappers over `query --recipe <id>`; every query flag passes through.
+# Capped at 5 to avoid alias-sprawl.
+codemap dead-code --json                                     # → query --recipe untested-and-dead
+codemap deprecated --ci                                      # → query --recipe deprecated-symbols --ci
+codemap boundaries --format sarif > boundary-findings.sarif  # → query --recipe boundary-violations --format sarif
+codemap hotspots --json --group-by directory                 # → query --recipe fan-in --json --group-by directory
+codemap coverage-gaps --json --summary                       # → query --recipe worst-covered-exports --json --summary
 # Parametrised recipes validate params from <id>.md frontmatter before SQL binding.
 codemap query --json --recipe find-symbol-by-kind --params kind=function,name_pattern=%Query%
 codemap query --recipe rename-preview --params old=usePermissions,new=useAccess,kind=function --format diff
diff --git a/docs/README.md b/docs/README.md
index 1aeaf03..b444016 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -22,7 +22,7 @@ Each topic has exactly one canonical file. Other files cross-reference by relati
 | [packaging.md](./packaging.md)                | **`CHANGELOG.md` / `dist/` / `templates/`** on npm, **engines**, [**Node vs Bun**](./packaging.md#node-vs-bun), [**Releases**](./packaging.md#releases) (Changesets; **`bun run version`** + oxfmt **`CHANGELOG.md`**).                                                                                                                                                                             |
 | [roadmap.md](./roadmap.md)                    | Forward-looking [**Backlog**](./roadmap.md#backlog) and [**Non-goals**](./roadmap.md#non-goals-v1) (not a `src/` inventory).                                                                                                                                                                                                                                                                        |
 | [plans/](./plans/)                            | One `<feature-name>.md` per in-flight plan. Created on demand — don't add the `-plan` suffix; the folder provides context. In flight: [`c9-plugin-layer.md`](./plans/c9-plugin-layer.md), [`lsp-diagnostic-push.md`](./plans/lsp-diagnostic-push.md).                                                                                                                                               |
-| [research/](./research/)                      | Dated, snapshot-style notes (e.g. competitive scans). Each note links shipped items back to canonical homes — see [research/competitive-scan-2026-04.md](./research/competitive-scan-2026-04.md).                                                                                                                                                                                                   |
+| [research/](./research/)                      | Dated, snapshot-style notes (e.g. competitive scans, non-goals reassessments). Each note links shipped items back to canonical homes — see [research/non-goals-reassessment-2026-05.md](./research/non-goals-reassessment-2026-05.md).                                                                                                                                                              |
 
 ---
 
@@ -37,7 +37,7 @@ These rules are normative — cite them by number in PR review. Ordered by how o
 5. **Cross-references use relative paths** — `[architecture.md § Section](./architecture.md#section)` or `[plans/foo.md](./plans/foo.md)`. Prefer section-deep links over file-only links.
 6. **No inventory counts in narrative** — don't hardcode counts of files, symbols, recipes, or other code-derived quantities. Use qualitative descriptors or a `codemap query --json` example. Decision values (cache TTLs, batch sizes, schema version) are fine — those are decisions, not inventory.
 7. **No line-number references** — line numbers (e.g. `parser.ts:241`) rot on every edit. Reference by function name, section heading, or symbol from `codemap query` instead. Methodology tables in [benchmark.md](./benchmark.md) are exempt.
-8. **Research notes get closed** — when a research scan's adopt items ship, slim the note to a "What shipped" appendix linking to canonical homes (see [research/competitive-scan-2026-04.md](./research/competitive-scan-2026-04.md) as the precedent). Rejected items keep a `Status: Rejected (date) — <one-line reason>` header.
+8. **Research notes get closed** — when a research scan's adopt items ship, slim the note to a "What shipped" appendix linking to canonical homes (see [research/non-goals-reassessment-2026-05.md](./research/non-goals-reassessment-2026-05.md) as the precedent — its § 8 errata + § Closed-out items pattern). Rejected items keep a `Status: Rejected (date) — <one-line reason>` header.
 9. **New term ⇒ update [glossary.md](./glossary.md) in the same PR** — when a PR introduces a new domain noun / verb / acronym (table name, recipe id, parser name, schema column), add or update its entry. Disambiguations (e.g. `FileRow` TS shape vs `files` SQLite table) take priority over single defs.
 10. **Core surface change ⇒ update bundled agent rule + skill in the same PR** — when a PR adds / changes a CLI flag, recipe id, recipe `actions` template, schema column, or any other surface an agent would query, update **both** copies of the codemap rule + skill so installed agents and this clone stay in lockstep:
     - **`templates/agents/rules/codemap.md`** + **`templates/agents/skills/codemap/SKILL.md`** (ships to npm via `codemap agents init`).
@@ -99,7 +99,7 @@ If none → fold any salvageable content into roadmap / architecture / glossary,
 
 A research note's job is the evaluation. When it concludes:
 
-- **Adopted** → lift the decisions-of-record into the relevant reference doc; slim the note to a "What shipped" appendix linking to canonical homes (precedent: [research/competitive-scan-2026-04.md](./research/competitive-scan-2026-04.md)).
+- **Adopted** → lift the decisions-of-record into the relevant reference doc; slim the note to a "What shipped" appendix linking to canonical homes (precedent: [research/non-goals-reassessment-2026-05.md](./research/non-goals-reassessment-2026-05.md)).
 - **Rejected** → add `Status: Rejected (YYYY-MM-DD) — <one-line reason>` at the top. Keep the file. Don't delete; the rejection rationale saves the next agent from re-litigating.
 - **Open** → stays in `research/` with no status header (open is the default).
 
@@ -118,7 +118,7 @@ When in doubt, default to absorbing into the closest existing root-level file (u
 ## Naming Conventions
 
 - **`plans/` files**: `<feature-name>.md` — the folder provides "plan" context, don't add a `-plan` suffix.
-- **`research/` files**: `<topic>-YYYY-MM.md` for dated snapshots (e.g. `competitive-scan-2026-04.md`); `<tool-name>.md` for ongoing tool evaluations.
+- **`research/` files**: `<topic>-YYYY-MM.md` for dated snapshots (e.g. `non-goals-reassessment-2026-05.md`); `<tool-name>.md` for ongoing tool evaluations.
 - **Top-level files**: descriptive domain noun (`architecture.md`, `glossary.md`, `roadmap.md`) — no prefix or suffix.
 
 ---
diff --git a/docs/architecture.md b/docs/architecture.md
index 8259723..b100ef4 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -16,13 +16,13 @@ A local SQLite database (`.codemap/index.db`) indexes the project tree and store
 
 ## Layering
 
-| Layer                                        | Role                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **`cli/`** (`bootstrap`, `main`, `cmd-*`)    | Parses argv; **dynamic `import()`** loads only the command chunk (`cmd-index`, `cmd-query`, `cmd-agents`) so `--help` / `version` / `agents init` avoid the indexer.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| **`api.ts`**                                 | Public programmatic surface: `createCodemap()`, `Codemap` (`query`, `index`), re-exports `runCodemapIndex` for advanced use.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| **`application/`**                           | Pure transport-agnostic engines + handlers: `run-index.ts` / `index-engine.ts` (orchestration + indexing); `query-engine.ts` (`executeQuery` / `executeQueryBatch`); `audit-engine.ts` (`runAudit` + `resolveAuditBaselines` + `runAuditFromRef` + `makeWorktreeReindex`); `audit-worktree.ts` (sha-keyed cache + atomic populate); `context-engine.ts` (`buildContextEnvelope`); `validate-engine.ts` (`computeValidateRows` + `toProjectRelative`); `show-engine.ts` (lookup + envelope builders); `impact-engine.ts` (`findImpact` — graph blast-radius walker); `coverage-engine.ts` (`upsertCoverageRows` core + `ingestIstanbul` / `ingestLcov` parsers; schema in [§ Schema → coverage](#schema)); `query-recipes.ts` + `recipes-loader.ts` (recipe registry); `output-formatters.ts` (SARIF + GH annotations + Mermaid `flowchart LR` with bounded-input contract); `watcher.ts` (chokidar-backed debounced reindex; pure helpers + injectable backend); `tool-handlers.ts` + `resource-handlers.ts` (transport-agnostic tool / resource handlers shared by MCP + HTTP); `mcp-server.ts` (MCP transport — stdio); `http-server.ts` (HTTP transport — `node:http`). Engines depend on `db.ts` / `runtime.ts`; **never** on `cli/`. |
-| **`adapters/`**                              | `LanguageAdapter` registry; built-ins call `parser.ts` / `css-parser.ts` / `markers.ts` from `parse-worker-core`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| **`runtime.ts` / `config.ts` / `db.ts` / …** | Config, SQLite, resolver, workers.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| Layer                                        | Role                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **`cli/`** (`bootstrap`, `main`, `cmd-*`)    | Parses argv; **dynamic `import()`** loads only the command chunk (`cmd-index`, `cmd-query`, `cmd-agents`) so `--help` / `version` / `agents init` avoid the indexer.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| **`api.ts`**                                 | Public programmatic surface: `createCodemap()`, `Codemap` (`query`, `index`), re-exports `runCodemapIndex` for advanced use.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| **`application/`**                           | Pure transport-agnostic engines + handlers: `run-index.ts` / `index-engine.ts` (orchestration + indexing); `query-engine.ts` (`executeQuery` / `executeQueryBatch`); `audit-engine.ts` (`runAudit` + `resolveAuditBaselines` + `runAuditFromRef` + `makeWorktreeReindex`); `audit-worktree.ts` (sha-keyed cache + atomic populate); `context-engine.ts` (`buildContextEnvelope`); `validate-engine.ts` (`computeValidateRows` + `toProjectRelative`); `show-engine.ts` (lookup + envelope builders); `impact-engine.ts` (`findImpact` — graph blast-radius walker); `coverage-engine.ts` (`upsertCoverageRows` core + `ingestIstanbul` / `ingestLcov` / `ingestV8` parsers; schema in [§ Schema → coverage](#schema)); `query-recipes.ts` + `recipes-loader.ts` (recipe registry); `output-formatters.ts` (SARIF + GH annotations + Mermaid `flowchart LR` with bounded-input contract); `watcher.ts` (chokidar-backed debounced reindex; pure helpers + injectable backend); `tool-handlers.ts` + `resource-handlers.ts` (transport-agnostic tool / resource handlers shared by MCP + HTTP); `mcp-server.ts` (MCP transport — stdio); `http-server.ts` (HTTP transport — `node:http`). Engines depend on `db.ts` / `runtime.ts`; **never** on `cli/`. |
+| **`adapters/`**                              | `LanguageAdapter` registry; built-ins call `parser.ts` / `css-parser.ts` / `markers.ts` from `parse-worker-core`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| **`runtime.ts` / `config.ts` / `db.ts` / …** | Config, SQLite, resolver, workers.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 
 `index.ts` is the package entry: re-exports the public API and runs `cli/main` only when executed as the main module (Node/Bun `codemap` binary).
 
@@ -105,7 +105,7 @@ A local SQLite database (`.codemap/index.db`) indexes the project tree and store
 | `resolver.ts`                                                                                     | Import path resolution via `oxc-resolver` — respects `tsconfig` aliases, builds dependency graph                                                                                                                                                                 |
 | `constants.ts`                                                                                    | Shared constants — e.g. `LANG_MAP`                                                                                                                                                                                                                               |
 | `glob-sync.ts`                                                                                    | Include globs — Bun `Glob` vs `tinyglobby` on Node ([packaging § Node vs Bun](./packaging.md#node-vs-bun))                                                                                                                                                       |
-| `markers.ts`                                                                                      | Shared marker extraction (`TODO`/`FIXME`/`HACK`/`NOTE`) — used by all parsers                                                                                                                                                                                    |
+| `markers.ts`                                                                                      | Shared marker extraction (`TODO`/`FIXME`/`HACK`/`NOTE`) + `extractSuppressions` for opt-in `// codemap-ignore-{next-line,file} <recipe-id>` directives — used by all parsers                                                                                     |
 | `parse-worker.ts`                                                                                 | Worker thread entry point — reads, parses, and extracts file data in parallel                                                                                                                                                                                    |
 | `adapters/`                                                                                       | `LanguageAdapter` types and built-in TS/CSS/text implementations                                                                                                                                                                                                 |
 | `parsed-types.ts`                                                                                 | Shared `ParsedFile` shape for workers and adapters                                                                                                                                                                                                               |
@@ -183,7 +183,7 @@ Optional **`<state-dir>/config.{ts,js,json}`** (default `.codemap/config.*`; def
 
 **Fresh database:** the default CLI **`codemap`** (incremental) calls **`createSchema()`** in **`runCodemapIndex`** before **`getChangedFiles()`**, so the **`meta`** table exists before **`getMeta(..., "last_indexed_commit")`** runs on an empty **`.codemap/index.db`**.
 
-Current schema version: **9** — see [Schema Versioning](#schema-versioning) for details.
+Current schema version: **10** — see [Schema Versioning](#schema-versioning) for details.
 
 All tables use `STRICT` mode. Tables marked with `WITHOUT ROWID` store data directly in the primary key B-tree. PRAGMAs and index design: [SQLite Performance Configuration](#sqlite-performance-configuration).
 
@@ -324,6 +324,17 @@ Edges are deduped per (caller_scope, callee) per file: if `foo` calls `bar` thre
 | kind        | TEXT       | `TODO`, `FIXME`, `HACK`, or `NOTE` |
 | content     | TEXT       | Comment text                       |
 
+### `suppressions` — Opt-in recipe suppression markers (`STRICT`)
+
+Parsed from `// codemap-ignore-next-line <recipe-id>` and `// codemap-ignore-file <recipe-id>` comments (also `#`, `--`, `<!--`, `/*` leaders for non-JS files). Recipes opt in via `LEFT JOIN suppressions s ON s.file_path = … AND s.recipe_id = '<id>' AND (s.line_number = 0 OR s.line_number = <row's line>) WHERE s.id IS NULL`. Stays consistent with the "no opinionated rule engine" floor — no severity, no suppression-by-default, no universal-honor; the suppression is consumer-chosen substrate.
+
+| Column      | Type       | Description                                                                                        |
+| ----------- | ---------- | -------------------------------------------------------------------------------------------------- |
+| id          | INTEGER PK | Auto-increment row id                                                                              |
+| file_path   | TEXT FK    | File the directive lives in                                                                        |
+| line_number | INTEGER    | `> 0` = next-line scope (the suppressed line); `0` = file scope (suppress anywhere in `file_path`) |
+| recipe_id   | TEXT       | Recipe id the directive targets (e.g. `untested-and-dead`)                                         |
+
 ### `meta` — Key-value metadata (`STRICT, WITHOUT ROWID`)
 
 | Column | Type    | Description                                                                |
@@ -360,7 +371,7 @@ User-facing baselines saved by `codemap query --save-baseline`, replayed by `cod
 
 ### `coverage` — Statement coverage (user data) (`STRICT, WITHOUT ROWID`)
 
-Statement-level coverage ingested by `codemap ingest-coverage <path>` from Istanbul JSON or LCOV. Joinable to `symbols` for "what's untested?" queries. Same lifecycle posture as `query_baselines`: **intentionally absent from `dropAll()`** so `--full` and `SCHEMA_VERSION` rebuilds preserve user ingest.
+Statement-level coverage ingested by `codemap ingest-coverage <path>` from Istanbul JSON, LCOV, or V8 runtime (`NODE_V8_COVERAGE=...` directory via `--runtime`). Joinable to `symbols` for "what's untested?" queries. Same lifecycle posture as `query_baselines`: **intentionally absent from `dropAll()`** so `--full` and `SCHEMA_VERSION` rebuilds preserve user ingest. V8 ingest is local-only — no SaaS aggregation.
 
 Natural-key PK `(file_path, name, line_start)` — deliberately **not** a FK to `symbols.id`. `symbols.id` is `INTEGER PRIMARY KEY AUTOINCREMENT`; on `--full` reindex `dropAll()` drops `symbols` and `createTables()` recreates it with fresh ids. A FK with `ON DELETE CASCADE` would wipe every coverage row on every full rebuild, and the recreated symbols wouldn't match the old ids anyway. Natural key sidesteps the entire CASCADE hazard. Trade-off: orphan rows when a file is deleted from the project — cleaned by `DELETE FROM coverage WHERE file_path NOT IN (SELECT path FROM files)` at the end of every ingest.
 
diff --git a/docs/glossary.md b/docs/glossary.md
index 8db92cd..733dad7 100644
--- a/docs/glossary.md
+++ b/docs/glossary.md
@@ -121,22 +121,23 @@ Output mode rendering `{from, to, label?, kind?}` rows as a Mermaid `flowchart L
 
 ### `coverage` (table)
 
-Static statement coverage ingested from Istanbul JSON or LCOV via `codemap ingest-coverage <path>`. Natural-key PK `(file_path, name, line_start)` — intentionally **not** a FK to `symbols.id` because `symbols` re-creates with fresh AUTOINCREMENT ids on every `--full` reindex; the natural-key approach lets coverage rows survive that churn (`coverage` is also intentionally absent from `dropAll()`, joins the `query_baselines` precedent). Columns: `coverage_pct REAL` (`NULL` when `total_statements = 0` — "untested" and "no testable code" are different signals), `hit_statements`, `total_statements`. Orphan rows (file deleted from project) are cleaned by an explicit `DELETE FROM coverage WHERE file_path NOT IN (SELECT path FROM files)` at the end of every ingest. Three meta keys (`coverage_last_ingested_at` / `_path` / `_format`) record freshness — single ingest at a time, so format is meta-level not per-row.
+Statement coverage ingested from Istanbul JSON, LCOV, or V8 runtime (`NODE_V8_COVERAGE=...` directory via `--runtime`) via `codemap ingest-coverage <path>`. Natural-key PK `(file_path, name, line_start)` — intentionally **not** a FK to `symbols.id` because `symbols` re-creates with fresh AUTOINCREMENT ids on every `--full` reindex; the natural-key approach lets coverage rows survive that churn (`coverage` is also intentionally absent from `dropAll()`, joins the `query_baselines` precedent). Columns: `coverage_pct REAL` (`NULL` when `total_statements = 0` — "untested" and "no testable code" are different signals), `hit_statements`, `total_statements`. Orphan rows (file deleted from project) are cleaned by an explicit `DELETE FROM coverage WHERE file_path NOT IN (SELECT path FROM files)` at the end of every ingest. Three meta keys (`coverage_last_ingested_at` / `_path` / `_format`) record freshness — single ingest at a time, so format is meta-level not per-row.
 
-### `codemap ingest-coverage` / Istanbul JSON / LCOV / static coverage ingestion
+### `codemap ingest-coverage` / Istanbul JSON / LCOV / V8 runtime / static coverage ingestion
 
-`codemap ingest-coverage <path> [--json]` reads a static coverage artifact and writes statement-level rows into the `coverage` table. Two formats in v1:
+`codemap ingest-coverage <path> [--runtime] [--json]` reads a coverage artifact and writes statement-level rows into the `coverage` table. Three formats:
 
 - **Istanbul JSON** (`coverage-final.json`) — emitted natively by `c8`, `nyc`, `vitest --coverage --coverage.reporter=json`, `jest --coverage --coverageReporters=json`. Parser reads `statementMap` + `s` (per-statement hit counts).
-- **LCOV** (`lcov.info`) — emitted by `bun test --coverage`, `c8 --reporter=lcov`, every legacy stack. Parser tokenises `SF:` / `DA:<line>,<count>` / `end_of_record` records; ignores `TN:` / `FN:` / `BRDA:` / `LF:` / `LH:` (statement coverage only in v1).
+- **LCOV** (`lcov.info`) — emitted by `bun test --coverage`, `c8 --reporter=lcov`, every legacy stack. Parser tokenises `SF:` / `DA:<line>,<count>` / `end_of_record` records; ignores `TN:` / `FN:` / `BRDA:` / `LF:` / `LH:` (statement coverage only).
+- **V8 runtime** (with `--runtime`) — opt-in directory mode reading `NODE_V8_COVERAGE=...` per-process dumps (`coverage-<pid>-<ts>-<seq>.json`). Each script's byte-offset ranges are converted to per-line hit counts (innermost-wins: smaller ranges override the function-as-a-whole count). Skips non-`file://` URLs (Node internals, `evalmachine.<anonymous>`); merges duplicate-URL scripts across dumps. Useful for "delete cold code with stronger evidence" agent flows. **Local-only — SaaS aggregation explicitly out of scope** (different product class).
 
-Format auto-detected from extension (`.json` → istanbul, `.info` → lcov, directory → probe both, error if ambiguous). No `--source` flag (per the plan's "no half-way APIs" principle — adding a flag for what the engine can detect is API noise). Each statement projects onto the **innermost** enclosing symbol via JS-side `(line_end - line_start) ASC` tie-break — required because nested symbols (class methods inside classes, closures inside functions) would otherwise inflate `total_statements`. Statements that fall outside every symbol range (top-level expressions, side-effect imports) increment `skipped.statements_no_symbol` for observability. Three bundled recipes consume the table at first-class agent surface (no agent ever has to hand-compose the JOIN):
+Format auto-detected from extension (`.json` → istanbul, `.info` → lcov, directory → probe both, error if ambiguous); `--runtime` opts into V8 directory mode. Each statement projects onto the **innermost** enclosing symbol via JS-side `(line_end - line_start) ASC` tie-break — required because nested symbols (class methods inside classes, closures inside functions) would otherwise inflate `total_statements`. Statements that fall outside every symbol range (top-level expressions, side-effect imports) increment `skipped.statements_no_symbol` for observability. Three bundled recipes consume the table at first-class agent surface (no agent ever has to hand-compose the JOIN):
 
 - `untested-and-dead` — exported functions with no callers AND zero coverage (the killer recipe; ships with a name-collision mitigation guide in the recipe `.md`).
 - `files-by-coverage` — files ranked ascending by statement coverage (replaces a deferred `file_coverage` rollup table; aggregates the symbol-level table via index-bounded `GROUP BY`).
 - `worst-covered-exports` — top-20 worst-covered exported functions.
 
-Engine: `application/coverage-engine.ts` — pure `upsertCoverageRows({db, projectRoot, rows, format, sourcePath})` core consumed by both `ingestIstanbul` and `ingestLcov`.
+Engine: `application/coverage-engine.ts` — pure `upsertCoverageRows({db, projectRoot, rows, format, sourcePath})` core consumed by `ingestIstanbul`, `ingestLcov`, and `ingestV8`.
 
 ### `content_hash`
 
@@ -330,6 +331,10 @@ Key-value metadata table. Holds `schema_version`, `last_indexed_commit`, `indexe
 
 ## O
 
+### outcome aliases (`dead-code` / `deprecated` / `boundaries` / `hotspots` / `coverage-gaps`)
+
+Top-level CLI verbs that thin-wrap `query --recipe <id>`: `dead-code` → `untested-and-dead`, `deprecated` → `deprecated-symbols`, `boundaries` → `boundary-violations`, `hotspots` → `fan-in`, `coverage-gaps` → `worst-covered-exports`. Every `query` flag passes through (`--json`, `--format`, `--ci`, `--summary`, `--changed-since`, `--group-by`, `--params`, `--save-baseline`, `--baseline`). Mapping lives in `src/cli/aliases.ts` (`OUTCOME_ALIASES`). Capped at 5 to avoid alias-sprawl — promote a sixth only when the recipe becomes a headline outcome. Moat-A clean: the alias is a one-line rewrite, not a new primitive; the recipe IS the SQL.
+
 ### oxc-parser
 
 Rust-based TypeScript / JavaScript parser (NAPI bindings). Codemap's `src/parser.ts` uses it to extract symbols, imports, exports, components, type members, calls, and markers from `.ts` / `.tsx` / `.js` / `.jsx` (and `.mts` / `.cts` / `.mjs` / `.cjs`).
@@ -443,6 +448,10 @@ Integer constant in `src/db.ts`. Bumped whenever the DDL changes. `createSchema(
 
 `codemap snippet <name>` — same lookup as **show**, but each match also carries `source` (file lines from disk at `line_start..line_end`), `stale` (true when content_hash drifted since last index — line range may have shifted), and `missing` (true when file is gone). Per-execution shape mirrors `show`'s envelope; source/stale/missing are additive fields. Stale-file behavior: `source` is ALWAYS returned when the file exists; `stale: true` is metadata the agent reads (no refusal, no auto-reindex side-effects from a read tool — agent decides whether to act on possibly-shifted lines or run `codemap` first). See [`architecture.md` § Show / snippet wiring](./architecture.md#cli-usage).
 
+### `suppressions` (table) / `// codemap-ignore-next-line` / `// codemap-ignore-file`
+
+Opt-in substrate. Markers parser recognises `// codemap-ignore-next-line <recipe-id>` and `// codemap-ignore-file <recipe-id>` directives (also `#`, `--`, `<!--`, `/*` leaders for non-JS files) and writes to `suppressions(file_path, line_number, recipe_id)`. Two scopes encoded by `line_number`: positive integer = next-line (the directive sits one line above; `line_number` points at the suppressed line), `0` = file scope. Recipe authors opt in by `LEFT JOIN suppressions s ON s.file_path = … AND s.recipe_id = '<id>' AND (s.line_number = 0 OR s.line_number = <row's line>) WHERE s.id IS NULL`; ad-hoc SQL is unaffected. **Stays consistent with the "no opinionated rule engine" Floor** — no severity, no suppression-by-default, no universal-honor; the suppression is consumer-chosen substrate. The leader regex requires the directive to start a line (modulo whitespace) so it never matches inside string literals — both this clone's tests and recipe `.md` examples use the directive in prose without polluting the index. Bundled recipes that opt in: `untested-and-dead` (next-line + file), `unimported-exports` (file scope only — exports table has no `line_number` column).
+
 ### `codemap watch` / watch mode
 
 Long-running process that subscribes to filesystem changes via [chokidar v5](https://github.com/paulmillr/chokidar) and re-indexes only the changed files via `runCodemapIndex({mode: 'files'})`. Eliminates the "is the index stale?" friction every CLI / MCP / HTTP query rides on today: agents in long sessions or multi-step refactors can `query` immediately after editing without remembering to reindex. Debounced (default 250 ms) so a burst — `git checkout`, `npm install`, multi-file save — collapses to one reindex call. Filters event paths the same way the indexer does (TS / TSX / JS / JSX / CSS + project-local recipes; skips `node_modules`, `.git`, `dist`, etc.). SIGINT / SIGTERM drains pending edits before exit. Three shapes:
diff --git a/docs/plans/lsp-diagnostic-push.md b/docs/plans/lsp-diagnostic-push.md
index 46567fc..fd606de 100644
--- a/docs/plans/lsp-diagnostic-push.md
+++ b/docs/plans/lsp-diagnostic-push.md
@@ -6,7 +6,7 @@
 >
 > **Tier:** XL effort (per the research note's § 5 (d) row). Two paired components: `codemap-lsp` server + `codemap-vscode` extension. Server alone is incomplete — extension is required to consume the custom `codemap/analysisComplete` notification + render status bar / tree views.
 >
-> **Reference implementation:** fallow's [`crates/lsp/`](https://github.com/fallow-rs/fallow/tree/main/crates/lsp) (~1800 LoC, `tower-lsp`) + [`editors/vscode/`](https://github.com/fallow-rs/fallow/tree/main/editors/vscode) (~2400 LoC TS, `vscode-languageclient`). Inspected 2026-05; same shape mapped onto codemap recipes.
+> **Implementation libraries:** [`vscode-languageserver`](https://github.com/microsoft/vscode-languageserver-node) for the server side; [`vscode-languageclient`](https://github.com/microsoft/vscode-languageserver-node) for the paired VSCode extension. Both Microsoft-official LSP libraries on top of which the codemap-specific diagnostic-push behavior is built.
 
 ---
 
@@ -20,7 +20,7 @@ These are committed to v1. Questions opened against them must justify against th
 | L.2 | **Moat-A discipline:** every diagnostic must be the `--format lsp-diagnostic` rendering of a bundled recipe. Reviewer test: "is this finding queryable via `query --recipe X`?" If no recipe drives the diagnostic, it's rejected.                  | [Moat A](../roadmap.md#moats-load-bearing)                                                                                                                                              |
 | L.3 | **Moat-B aligned:** server consumes shipped engines (`application/show-engine.ts`, `application/impact-engine.ts`, `application/watcher.ts`); does NOT re-extract structure inside the protocol layer.                                              | [Moat B](../roadmap.md#moats-load-bearing); [§ 2.5 "no LSP engine"](../research/non-goals-reassessment-2026-05.md#25-no-lsp-replacement)                                                |
 | L.4 | **Bun/Node binary, not Rust.** Keep the toolchain consistent; reuse engines via direct imports.                                                                                                                                                     | Operational — repo is TS                                                                                                                                                                |
-| L.5 | **Server + extension is the unit, not either alone.** Custom `codemap/analysisComplete` notification requires the paired extension to render status bar / tree views; LSP-only consumption (no extension) is reduced UX, not v1.                    | [§ 2.5 v3 verdict](../research/non-goals-reassessment-2026-05.md#25-no-lsp-replacement); fallow precedent                                                                               |
+| L.5 | **Server + extension is the unit, not either alone.** Custom `codemap/analysisComplete` notification requires the paired extension to render status bar / tree views; LSP-only consumption (no extension) is reduced UX, not v1.                    | [§ 2.5 v3 verdict](../research/non-goals-reassessment-2026-05.md#25-no-lsp-replacement)                                                                                                 |
 | L.6 | **No JS execution at index time** survives — server speaks LSP, doesn't `eval` recipe SQL or extension-injected code.                                                                                                                               | [Floors "No JS execution at index time"](../roadmap.md#floors-v1-product-shape)                                                                                                         |
 | L.7 | **Ships AFTER (b) C.9** per cadence. Not a hard block — (d) ships valid diagnostics on existing recipe outputs without (b); but landing (b) first means `untested-and-dead` / `unimported-exports` diagnostics inherit cleaner inputs from day one. | [§ 5 Rationale 5](../research/non-goals-reassessment-2026-05.md#5-pick-order-rationale-historical)                                                                                      |
 
@@ -32,14 +32,14 @@ Each gets a "Resolution" subsection below as it crystallises (mirrors c9-plugin-
 
 - **Q1 — Repo structure (flat vs monorepo).** Add `lsp/` + `editors/vscode/` to current flat layout (no workspaces; Option 1)? Convert to monorepo first (`packages/codemap` + `packages/codemap-lsp` + `packages/codemap-vscode`; Option 2)? Combine convert + (d) impl in one PR (Option 3)? Trade-offs in [§ Repo-structure tradeoffs](#repo-structure-tradeoffs) below.
 - **Q2 — LSP server framework.** `vscode-languageserver` (Microsoft official, well-documented)? `vscode-jsonrpc` (lower-level, more control)? Custom over stdio? Bias toward `vscode-languageserver` for compatibility.
-- **Q3 — Extension-to-server transport.** Stdio (mirrors fallow + LSP convention)? Or skip LSP entirely and have extension call codemap MCP/HTTP directly? **L.1 already locks LSP shape**, so this is "stdio vs IPC" not "LSP yes/no" — bias toward stdio.
+- **Q3 — Extension-to-server transport.** Stdio (LSP convention)? Or skip LSP entirely and have extension call codemap MCP/HTTP directly? **L.1 already locks LSP shape**, so this is "stdio vs IPC" not "LSP yes/no" — bias toward stdio.
 - **Q4 — Which recipes become diagnostics in v1.** Candidate list: `untested-and-dead`, `unimported-exports`, `components-touching-deprecated`, `boundary-violations` (shipped PR #72), `high-complexity-untested`, `deprecated-symbols` callers (need the call-site row from `calls`, not the symbol row from `symbols`). Ship all 6 in v1 or start narrow?
 - **Q5 — Diagnostic severity mapping.** `Error` for `boundary-violations`? `Warning` for `untested-and-dead` / `unimported-exports`? `Information` for `high-complexity-untested` / `deprecated-symbols` callers? Per-recipe configurable via `initializationOptions`?
 - **Q6 — Hover provider scope.** Hover on every indexed symbol with `signature` + `doc_comment` + `complexity` + caller-count? Or only on symbols that have at least one of those (avoid noise on plain locals)? Coverage % when available?
 - **Q7 — Code lens scope.** Fan-in count above functions? Complexity? Coverage? All three? Lens ON/OFF per kind via settings?
-- **Q8 — Custom notification shape.** `codemap/analysisComplete` payload — counts per recipe (mirrors fallow's `total_issues` + per-category counts)? Or richer structure? Must remain stable across versions (extension reads it).
-- **Q9 — Settings / initializationOptions surface.** Toggle each recipe ON/OFF (mirrors fallow's `issueTypes`)? Severity overrides? `changedSince` git ref to scope diagnostics to PR-changed files (mirrors fallow)?
-- **Q10 — Auto-update / version-mismatch handling.** Extension bundles a binary version; what if user has a different `codemap` CLI installed globally? Warn? Use bundled? Use user's? Mirrors fallow's `binary-utils.ts` + `download.ts` resolution chain.
+- **Q8 — Custom notification shape.** `codemap/analysisComplete` payload — `total_issues` + per-recipe counts? Or richer structure? Must remain stable across versions (extension reads it).
+- **Q9 — Settings / initializationOptions surface.** Toggle each recipe ON/OFF (`issueTypes`-style array)? Severity overrides? `changedSince` git ref to scope diagnostics to PR-changed files?
+- **Q10 — Auto-update / version-mismatch handling.** Extension bundles a binary version; what if user has a different `codemap` CLI installed globally? Warn? Use bundled? Use user's? Resolution chain (project-installed → bundled → globally-installed → download) needs to be specified.
 - **Q11 — Marketplace publisher name.** `stainless-code` (matches GH org)? Other? **One-time decision; renaming a publisher is hard.**
 - **Q12 — Open VSX (VSCodium / Cursor / Theia) parity.** Publish to both VSCode Marketplace and Open VSX, or VSCode-only? Cursor users → likely yes for Open VSX.
 
@@ -136,7 +136,6 @@ LSP handlers NOT implemented (per L.1):
    │  Binary resolution                    │
    │   ↳ user setting > local node_modules │
    │   ↳   > PATH > auto-download          │
-   │   ↳ (mirrors fallow download.ts)      │
    └───────────────────────────────────────┘
 ```
 
@@ -182,19 +181,18 @@ Any one alone can ship in the current flat layout. Combinations start to strain
 | Option                                                  | Cost                                                                                                                                                                                                                                                                                                                                                                                             | Benefit                                                                                                                                                                                                                                                                                                        |
 | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | **1: Stay flat** — add `lsp/` + `editors/vscode/` dirs  | Zero refactor. Relative imports from `lsp/` into `src/application/*` work today. One additional `bin: { "codemap-lsp": "..." }` in main `package.json`. Extension is its own `package.json` (different name, different version, published to VSCode Marketplace not npm — already independent of CLI versioning regardless of layout choice).                                                    | Simplest path. No risk to existing code. Ships (d) without prerequisite work. **Loses:** independent versioning between CLI and LSP server (one changeset bumps both). **Loses:** clean package boundary if a third-party wants to consume engines as a library (no `@stainless-code/codemap-core` to import). |
-| **2: Convert to monorepo first** (separate refactor PR) | ~1-2 days of churn. Touches every import in `src/`, every test path, every doc reference (`bun src/index.ts` → `bun packages/codemap-cli/src/index.ts` or aliased), every script reference (`scripts/*.ts`), every changeset config (per-package). CI scripts updated. Risk surface unrelated to (d) value. Reviewer reaction to "refactor PR with no user-visible value" is generally negative. | Independent versioning per package. Clean `packages/codemap-core` exposing engines. Ready for C.9 community plugins. Standard pattern (oxc, tsgo, fallow's Cargo workspace, biome, vitest). Bun workspaces + changesets handle locked-or-independent versioning natively.                                      |
+| **2: Convert to monorepo first** (separate refactor PR) | ~1-2 days of churn. Touches every import in `src/`, every test path, every doc reference (`bun src/index.ts` → `bun packages/codemap-cli/src/index.ts` or aliased), every script reference (`scripts/*.ts`), every changeset config (per-package). CI scripts updated. Risk surface unrelated to (d) value. Reviewer reaction to "refactor PR with no user-visible value" is generally negative. | Independent versioning per package. Clean `packages/codemap-core` exposing engines. Ready for C.9 community plugins. Standard pattern (oxc, tsgo, biome, vitest). Bun workspaces + changesets handle locked-or-independent versioning natively.                                                                |
 | **3: Convert as part of (d) impl**                      | Bigger PR (refactor + new feature combined). Harder to review.                                                                                                                                                                                                                                                                                                                                   | Convert once, justify once with the new packages it creates. Avoids the "refactor PR with no user-visible value" review pushback.                                                                                                                                                                              |
 
 ### Reference: what other TS tools do
 
-| Tool                                                                              | Layout                                                                                                                                                                                                                   | Why                                                                                                  |
-| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- |
-| **fallow** ([upstream](https://github.com/fallow-rs/fallow))                      | Monorepo (Cargo workspace: `crates/cli`, `crates/lsp`, `crates/core`, `crates/extract`, `crates/graph`, `crates/mcp`, `crates/v8-coverage`, `crates/config`); `editors/vscode/` + `editors/zed/` outside cargo workspace | Rust forces this for multi-binary projects. VSCode extension is TS, separately published             |
-| **knip** ([upstream](https://github.com/webpro-nl/knip))                          | Single npm package; VSCode extension lives in a [completely different repo](https://github.com/webpro-nl/knip-vscode)                                                                                                    | Choice — extension maintainer is a different contributor; full repo-split rather than monorepo       |
-| **oxc** ([upstream](https://github.com/oxc-project/oxc))                          | Monorepo (pnpm workspaces): `napi/parser`, `napi/transform`, `napi/resolver`, `crates/oxc_*` (Rust), `editors/vscode`                                                                                                    | Ships many tools (parser, formatter, linter, resolver) as separable packages — natural workspace fit |
-| **tsgo / typescript-go** ([upstream](https://github.com/microsoft/typescript-go)) | Monorepo (Go modules + npm packages)                                                                                                                                                                                     | Multi-binary + multi-language                                                                        |
-| **biome** ([upstream](https://github.com/biomejs/biome))                          | Monorepo (pnpm workspaces): `packages/@biomejs/biome`, `packages/@biomejs/js-api`, `editors/vscode`, `editors/intellij`, `crates/*` (Rust core)                                                                          | Multiple language editors + Rust core + JS bindings                                                  |
-| **vitest** ([upstream](https://github.com/vitest-dev/vitest))                     | Monorepo (pnpm workspaces): `packages/vitest`, `packages/browser`, `packages/coverage-*`, `packages/vite-node`, `packages/ui`                                                                                            | Many separable concerns ship together                                                                |
+| Tool                                                                              | Layout                                                                                                                                          | Why                                                                                                  |
+| --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| **knip** ([upstream](https://github.com/webpro-nl/knip))                          | Single npm package; VSCode extension lives in a [completely different repo](https://github.com/webpro-nl/knip-vscode)                           | Choice — extension maintainer is a different contributor; full repo-split rather than monorepo       |
+| **oxc** ([upstream](https://github.com/oxc-project/oxc))                          | Monorepo (pnpm workspaces): `napi/parser`, `napi/transform`, `napi/resolver`, `crates/oxc_*` (Rust), `editors/vscode`                           | Ships many tools (parser, formatter, linter, resolver) as separable packages — natural workspace fit |
+| **tsgo / typescript-go** ([upstream](https://github.com/microsoft/typescript-go)) | Monorepo (Go modules + npm packages)                                                                                                            | Multi-binary + multi-language                                                                        |
+| **biome** ([upstream](https://github.com/biomejs/biome))                          | Monorepo (pnpm workspaces): `packages/@biomejs/biome`, `packages/@biomejs/js-api`, `editors/vscode`, `editors/intellij`, `crates/*` (Rust core) | Multiple language editors + Rust core + JS bindings                                                  |
+| **vitest** ([upstream](https://github.com/vitest-dev/vitest))                     | Monorepo (pnpm workspaces): `packages/vitest`, `packages/browser`, `packages/coverage-*`, `packages/vite-node`, `packages/ui`                   | Many separable concerns ship together                                                                |
 
 **Pattern:** monorepo is dominant when a tool ships **3+ independently-publishable artifacts**. Single-package wins when there's just one (knip).
 
@@ -296,9 +294,9 @@ GH secrets: `VSCE_PAT`, `OVSX_PAT`.
 
 ### Versioning relative to CLI
 
-Two patterns. Fallow uses **locked** (extension version always matches CLI). Codemap should match:
+Two patterns; pick one:
 
-- Locked → simpler users; one mental model; needs hand-bump or script in changeset hook
+- Locked (extension version always matches CLI) → simpler users; one mental model; needs hand-bump or script in changeset hook
 - Independent → extension iterates separately; needs "this extension version requires CLI ≥ X" docs
 
 Bias: **locked**. Relevant to Q1 — monorepo workspaces makes locked versioning trivial via changesets; flat layout needs a hand-script.
@@ -324,17 +322,17 @@ Bias: **locked**. Relevant to Q1 — monorepo workspaces makes locked versioning
 
 ## Risks / non-goals
 
-| Item                                                                            | Mitigation                                                                                                                                                                                                         |
-| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| **Non-goal:** standard LSP request handlers (definition / references).          | Per L.1; rejected.                                                                                                                                                                                                 |
-| **Non-goal:** verdict-shaped CLI verb fronting the LSP server.                  | Per L.2; recipes drive output. The LSP binary is a transport, not a new verb.                                                                                                                                      |
-| **Non-goal:** runtime tracing / live execution data.                            | Per [Floor "No runtime tracing"](../roadmap.md#floors-v1-product-shape). Static recipes only.                                                                                                                      |
-| **Risk:** XL surface (~3-4k LoC) — slip risk.                                   | Slice cadence per § Implementation slices. Each slice is shippable (extension MVP works against one recipe before adding 5 more). If the plan stalls, partial slices still deliver.                                |
-| **Risk:** marketplace approval delays first publish.                            | First publish = 24-48h review; plan slice 7 explicitly. Subsequent versions are instant.                                                                                                                           |
-| **Risk:** extension vs CLI version drift.                                       | Locked versioning (per § Versioning); changeset hook bumps both. Q1 (monorepo) makes this trivial; flat layout needs a small script.                                                                               |
-| **Risk:** false-positive squigglies on `untested-and-dead` for framework files. | (b) C.9 lands first per § 5 cadence; reduces FP class. Until then, extension settings let users disable specific diagnostic codes (mirrors fallow's `issueTypes`).                                                 |
-| **Risk:** plan abandoned mid-iteration.                                         | Per [`docs/README.md` Rule 8](../README.md), close as `Status: Rejected (YYYY-MM-DD) — <reason>`. Design surface captured either way. Engines stay as-is; nothing extracted.                                       |
-| **Risk:** binary size / startup time on user machines.                          | Bun-based binary is small (~10MB stripped); VSCode-bundled binary distribution mirrors fallow's pattern (one binary per platform; download lazily). Cold-start sub-100ms still applies on the LSP `did_open` path. |
+| Item                                                                            | Mitigation                                                                                                                                                                                                             |
+| ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Non-goal:** standard LSP request handlers (definition / references).          | Per L.1; rejected.                                                                                                                                                                                                     |
+| **Non-goal:** verdict-shaped CLI verb fronting the LSP server.                  | Per L.2; recipes drive output. The LSP binary is a transport, not a new verb.                                                                                                                                          |
+| **Non-goal:** runtime tracing / live execution data.                            | Per [Floor "No runtime tracing"](../roadmap.md#floors-v1-product-shape). Static recipes only.                                                                                                                          |
+| **Risk:** XL surface (~3-4k LoC) — slip risk.                                   | Slice cadence per § Implementation slices. Each slice is shippable (extension MVP works against one recipe before adding 5 more). If the plan stalls, partial slices still deliver.                                    |
+| **Risk:** marketplace approval delays first publish.                            | First publish = 24-48h review; plan slice 7 explicitly. Subsequent versions are instant.                                                                                                                               |
+| **Risk:** extension vs CLI version drift.                                       | Locked versioning (per § Versioning); changeset hook bumps both. Q1 (monorepo) makes this trivial; flat layout needs a small script.                                                                                   |
+| **Risk:** false-positive squigglies on `untested-and-dead` for framework files. | (b) C.9 lands first per § 5 cadence; reduces FP class. Until then, extension settings let users disable specific diagnostic codes (`issueTypes` array).                                                                |
+| **Risk:** plan abandoned mid-iteration.                                         | Per [`docs/README.md` Rule 8](../README.md), close as `Status: Rejected (YYYY-MM-DD) — <reason>`. Design surface captured either way. Engines stay as-is; nothing extracted.                                           |
+| **Risk:** binary size / startup time on user machines.                          | Bun-based binary is small (~10MB stripped); VSCode-bundled binary distribution (one binary per platform; download lazily) keeps install footprint thin. Cold-start sub-100ms still applies on the LSP `did_open` path. |
 
 ---
 
@@ -347,4 +345,4 @@ Bias: **locked**. Relevant to Q1 — monorepo workspaces makes locked versioning
 - [`docs/README.md` Rule 3](../README.md) — plan-file convention (this file's location)
 - [`docs/README.md` Rule 10](../README.md) — agent rule lockstep update (Slice 8)
 - [`.agents/rules/tracer-bullets.md`](../../.agents/rules/tracer-bullets.md) — slice cadence
-- Reference implementations: [fallow `crates/lsp/`](https://github.com/fallow-rs/fallow/tree/main/crates/lsp), [fallow `editors/vscode/`](https://github.com/fallow-rs/fallow/tree/main/editors/vscode)
+- LSP libraries: [`vscode-languageserver`](https://github.com/microsoft/vscode-languageserver-node), [`vscode-languageclient`](https://github.com/microsoft/vscode-languageserver-node), [`vscode-test`](https://github.com/microsoft/vscode-test) (E2E), [`vsce`](https://github.com/microsoft/vscode-vsce) + [`ovsx`](https://github.com/eclipse/openvsx) (publishing)
diff --git a/docs/research/competitive-scan-2026-04.md b/docs/research/competitive-scan-2026-04.md
deleted file mode 100644
index 6caf342..0000000
--- a/docs/research/competitive-scan-2026-04.md
+++ /dev/null
@@ -1,100 +0,0 @@
-# Competitive scan — fallow, AZidan/codemap, JordanCoin/codemap
-
-> Inspiration scan from three sibling tools in the "AI-friendly code intelligence" space.
-> Captured **2026-04-27** during PR [#23](https://github.com/stainless-code/codemap/pull/23). Most adopt items shipped in that PR; remaining items moved to [docs/roadmap.md](../roadmap.md).
->
-> **Fallow updates (post-scan):** fallow ships rapidly. Ongoing capability tracking — what fallow has shipped since this snapshot, what remains adoption-worthy, and where it explicitly should _not_ be copied — lives in [`research/fallow.md`](./fallow.md). AZidan and JordanCoin haven't moved meaningfully; they stay in this dated snapshot.
-
-Sources:
-
-- [fallow-rs/fallow](https://github.com/fallow-rs/fallow) — Rust, ~1.1k stars, TS/JS-only, "codebase intelligence" (dead code, dupes, complexity, boundaries, runtime). 91 framework plugins.
-- [AZidan/codemap](https://github.com/AZidan/codemap) — Python, ~55 stars, "make LLM reads cheaper" (symbol→line-range index). Multi-language tree-sitter.
-- [JordanCoin/codemap](https://github.com/JordanCoin/codemap) — Go, ~525 stars, "project brain" (tree+diff+deps+skyline+handoff). Hooks/MCP/HTTP/skills.
-
----
-
-## 1. Positioning recap (snapshot at scan time)
-
-**Codemap is:** a **structural SQLite index** → agents call **SQL** for symbols, imports, exports, components, calls, type members, deps, CSS tokens/classes/keyframes, markers. AST-backed (oxc, lightningcss, oxc-resolver). Bun + Node, TS/CSS-first. CLI **`codemap query --json`** + **`codemap agents init`** for IDE wiring.
-
-**Codemap is not:** a dead-code detector, duplication finder, dependency-flow visualizer, semantic understanding layer, or agent runtime. The canonical alternatives positioning lives in [why-codemap.md § When to reach for something else](../why-codemap.md#when-to-reach-for-something-else) and the explicit non-goals are in [roadmap.md § Non-goals](../roadmap.md#non-goals-v1) — keep this doc free of duplicates.
-
----
-
-## 2. Side-by-side (snapshot)
-
-| Axis              | **us**                                  | fallow                                                 | AZidan/codemap                       | JordanCoin/codemap                           |
-| ----------------- | --------------------------------------- | ------------------------------------------------------ | ------------------------------------ | -------------------------------------------- |
-| Lang of impl      | TS (Bun/Node)                           | Rust                                                   | Python                               | Go                                           |
-| Storage           | SQLite (`.codemap/index.db`)            | in-process; SARIF/JSON outputs                         | distributed JSON (`.codemap/*.json`) | per-project `.codemap/` JSON artifacts       |
-| Query surface     | **SQL** (full power)                    | CLI subcommands, `--format json`                       | `find`/`show`/`stats` CLI            | `tree`/`--diff`/`--deps`/`context`/MCP/HTTP  |
-| What's indexed    | symbols, imports/exports, deps, CSS, …  | module graph, dupe clones, complexity, boundary rules  | symbols + line ranges + hash         | tree + dep flow + hubs + working set         |
-| Agent integration | rules/skills via `agents init`          | MCP, LSP, VSCode ext, `--format json` w/ fix `actions` | Claude plugin, MCP planned           | hooks, MCP, HTTP, "context envelope", skills |
-| Refresh model     | git-diff incremental + targeted `files` | full+changed-since                                     | hash + watch + git pre-commit        | daemon, hooks, watch                         |
-| TS/JS depth       | oxc AST                                 | oxc AST + boundary/dup/complexity                      | tree-sitter                          | ast-grep (deps only)                         |
-| Other langs       | CSS                                     | TS/JS only (intentional)                               | 14 langs (tree-sitter)               | 18 langs (deps via ast-grep)                 |
-| Headline pitch    | "query your codebase"                   | "codebase truth layer for agents"                      | "make every read cheaper"            | "project brain for your AI"                  |
-| License           | MIT                                     | MIT (+ paid runtime)                                   | MIT                                  | MIT                                          |
-
-> A consumer-facing distillation of this table — focused on philosophy/scope rather than implementation — lives in [why-codemap.md § Codemap vs alternatives](../why-codemap.md#codemap-vs-alternatives). Keep prose comparisons there; this row is the unfiltered scan record.
-
----
-
-## 3. What shipped from this scan
-
-| Idea (originally §3 / §4 / §5 of this scan)                                             | Shipped where                                                                                           | Inspired by                                           |
-| --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
-| `codemap context` JSON envelope (incl. `--for "<intent>"` thin classifier, `--compact`) | `src/cli/cmd-context.ts` + `src/application/context-engine.ts`                                          | JordanCoin (`codemap context`)                        |
-| `codemap validate` (hash-based staleness, no re-read)                                   | `src/cli/cmd-validate.ts` + `src/application/validate-engine.ts`                                        | AZidan (`codemap validate`)                           |
-| `--performance` per-phase timing + top-10 slowest files                                 | `src/application/index-engine.ts`                                                                       | own roadmap, sharpened by JordanCoin's daemon framing |
-| `deprecated-symbols` recipe                                                             | `src/application/query-recipes.ts`                                                                      | fallow JSDoc visibility tags                          |
-| `visibility-tags` recipe (`@internal` / `@private` / `@alpha` / `@beta`)                | `src/application/query-recipes.ts`                                                                      | fallow JSDoc visibility tags                          |
-| `barrel-files` recipe (top files by export count)                                       | `src/application/query-recipes.ts`                                                                      | own derivation from JordanCoin "hubs" framing         |
-| `files-hashes` recipe powering `validate`                                               | `src/application/query-recipes.ts`                                                                      | AZidan                                                |
-| `-r` short alias for `--recipe`, cleaner `--help`                                       | `src/cli/cmd-query.ts`                                                                                  | own UX polish                                         |
-| Friendlier "no `.codemap/index.db`" error                                               | `src/application/index-engine.ts`                                                                       | own UX polish                                         |
-| Anti-pitch — "When to reach for something else"                                         | [why-codemap.md § When to reach for something else](../why-codemap.md#when-to-reach-for-something-else) | AZidan                                                |
-| Scenario-keyed token-savings table                                                      | [why-codemap.md § Across a Typical Session](../why-codemap.md#across-a-typical-session)                 | AZidan                                                |
-| "Grep/Read vs Codemap" capability table                                                 | [README.md § What you get](../../README.md#what-you-get)                                                | fallow ("Linter vs Fallow")                           |
-| "Daily commands" stripe + version-matched skill framing                                 | [README.md § CLI](../../README.md#cli)                                                                  | JordanCoin / fallow packaging                         |
-| Alternatives comparison table                                                           | [why-codemap.md § Codemap vs alternatives](../why-codemap.md#codemap-vs-alternatives)                   | AZidan ("CodeMap vs RepoMap/Serena/RepoPrompt")       |
-| Schema v3 — `NOT NULL` audit (orthogonal to scan but landed in same PR)                 | `src/db.ts`                                                                                             | CodeRabbit review during PR #23                       |
-
-All shipped under PR [#23](https://github.com/stainless-code/codemap/pull/23) as schema-bump-driven minor release.
-
----
-
-## 4. What moved to the roadmap
-
-Items the scan called out as "watch / defer / future" — most still live in [docs/roadmap.md § Backlog](../roadmap.md#backlog); items shipped after this scan are linked to their PRs.
-
-- ✅ **MCP server wrapping `query`** — shipped as `codemap mcp` (agent-transports v1) in PR [#35](https://github.com/stainless-code/codemap/pull/35). Tool taxonomy, output shape, and resource catalog reserved for HTTP API to inherit.
-- ✅ **Recipes-as-content registry + project-local recipes (`.codemap/recipes/`)** — shipped in PR [#37](https://github.com/stainless-code/codemap/pull/37). Catalog gains `source` / `body` / `shadows` fields so agents see project overrides at session start.
-- ✅ **Targeted-read CLI (`codemap show <symbol>`)** — shipped as `show` + `snippet` siblings in PR [#39](https://github.com/stainless-code/codemap/pull/39).
-- ✅ **`--format sarif` + `--format annotations`** — shipped in PR [#43](https://github.com/stainless-code/codemap/pull/43). GitHub Code Scanning + PR-inline annotations for any recipe row-set.
-- ✅ **HTTP API (`codemap serve`)** — shipped in PR [#44](https://github.com/stainless-code/codemap/pull/44). Same tool taxonomy as MCP, `POST /tool/{name}`, loopback default, optional `--token`.
-- ✅ **Watch mode (`codemap watch`)** — shipped in PR [#47](https://github.com/stainless-code/codemap/pull/47), planned in PR [#46](https://github.com/stainless-code/codemap/pull/46). Standalone + `mcp --watch` / `serve --watch` killer combos; chokidar v5 backend.
-- See [`research/fallow.md` § Status snapshot](./fallow.md#status-snapshot-as-of-2026-05-03) for the full ship summary.
-- Cross-agent handoff artifact (speculative) — still backlog
-
-The scan's "PASS" list (dead-code / dupes / complexity / boundaries / fix actions, runtime/V8 coverage merging, framework plugins, PageRank summarization, skyline visualization, daemon process, embedded intent classification) has been folded into [roadmap.md § Non-goals](../roadmap.md#non-goals-v1) — that's the canonical home; do not duplicate here.
-
-**Explicitly dropped:** "remote-repo support" (`codemap github.com/x/y`) — discussed in [PR #23](https://github.com/stainless-code/codemap/pull/23) and rejected as demoware that doesn't fit the SQL-index thesis.
-
----
-
-## 5. Open questions (still open)
-
-These were not resolved in PR #23 and warrant their own design conversations:
-
-- ✅ **Should recipes own their description?** — Settled in PR [#37](https://github.com/stainless-code/codemap/pull/37): file-pair `<id>.{sql,md}` in `templates/recipes/` (bundled) and `<projectRoot>/.codemap/recipes/` (project-local), loaded at runtime via `node:fs/readdirSync`. YAML frontmatter on `.md` carries the per-row `actions` template.
-- **Daemon vs one-shot** — JordanCoin's daemon is the only way they get sub-100ms hooks. Our CLI startup is ~50–100 ms cold (Node) and lower on Bun; we may not need a daemon at all. Worth measuring once MCP/HTTP land. Roadmap lists "persistent daemon" as a non-goal **for now** with this caveat.
-
----
-
-## 6. Citations / cross-links
-
-- [docs/roadmap.md](../roadmap.md) — current backlog and non-goals
-- [docs/why-codemap.md](../why-codemap.md) — anti-pitch, token-cost framing, alternatives comparison
-- [docs/architecture.md](../architecture.md) — schema and CLI layering
-- [PR #23](https://github.com/stainless-code/codemap/pull/23) — the implementation pass driven by this scan
diff --git a/docs/research/fallow.md b/docs/research/fallow.md
deleted file mode 100644
index cca7e4e..0000000
--- a/docs/research/fallow.md
+++ /dev/null
@@ -1,186 +0,0 @@
-# Fallow — adoption candidates (closed historical)
-
-> **Status:** Closed (2026-05) — adoption-from-fallow framing is no longer the codemap mission. See [`research/non-goals-reassessment-2026-05.md`](./non-goals-reassessment-2026-05.md) for the current positioning: codemap occupies a specific niche in the SQLite-backed-code-index cohort (peers: `srclight`, `Sverklo`, `ctxpp`, `KotaDB`, `codemogger`, etc.) — fallow is one of many, not a yardstick. Codemap's differentiation axes (predicate-as-API + pure structural + JS/TS/CSS-deep extraction) stand on intrinsic merit, not on cloning peer features.
->
-> **Body preserved** as historical record of what shipped from fallow inspirations during the 2026-04 → 2026-05 window. The Status snapshot below is the authoritative "what actually landed" log; do not extend it. New adoption candidates (if any) get authored against open specs and primitive sources per the [`plan-pr-inspiration-discipline`](../../.agents/rules/plan-pr-inspiration-discipline.md) rule, not against fallow's source tree.
->
-> **Outstanding open items** were lifted to canonical homes: C.9 plugin layer → in-flight plan PR ([`docs/plans/c9-plugin-layer.md`](../plans/c9-plugin-layer.md)); C.10 LSP → in-flight plan PR ([`docs/plans/lsp-diagnostic-push.md`](../plans/lsp-diagnostic-push.md)) with reasoning at [`non-goals-reassessment-2026-05.md § 2.5`](./non-goals-reassessment-2026-05.md#25-no-lsp-replacement); C.11 coverage → shipped. Tier D defers (suppressions, fix engine, dupes, runtime intel) are aligned with [`roadmap.md § Non-goals (v1) → Floors`](../roadmap.md#floors-v1-product-shape).
->
-> Originally an **ongoing** capability tracker; closure rationale captured below.
-
----
-
-## Original framing (preserved verbatim from before 2026-05 closure)
-
-> Ongoing capability tracker for [`fallow-rs/fallow`](https://github.com/fallow-rs/fallow). Complement to [`research/competitive-scan-2026-04.md`](./competitive-scan-2026-04.md), which captured the first three-tool scan (fallow, AZidan/codemap, JordanCoin/codemap) and the items it drove into PR [#23](https://github.com/stainless-code/codemap/pull/23).
->
-> **Last refreshed:** 2026-04-30 against fallow `v2.56.0` (npm; ~1.6k stars at refresh).
-> **Why a separate tracker:** fallow ships rapidly (149 releases as of 2026-04-29); a per-tool note keeps the comparison surface re-runnable without dragging the dated scan along. AZidan and JordanCoin haven't moved; they stay in the dated scan.
-
----
-
-## Status snapshot (as of 2026-05-03)
-
-Adoption-candidate ship status. The tier tables in § 1 are preserved as the original assessment record; this snapshot is the single source of truth for "what's open." Update on every PR that closes a row.
-
-| Tier | #         | Item                                                                                 | Status                                           | Where it landed / why deferred                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| ---- | --------- | ------------------------------------------------------------------------------------ | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| A    | A.1       | Per-row recipe `actions`                                                             | ✅ Shipped                                       | PR [#26](https://github.com/stainless-code/codemap/pull/26)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| A    | A.2       | `--changed-since <ref>`                                                              | ✅ Shipped                                       | PR [#26](https://github.com/stainless-code/codemap/pull/26)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| A    | A.3       | `--group-by owner\|directory\|package`                                               | ✅ Shipped                                       | PR [#26](https://github.com/stainless-code/codemap/pull/26)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| A    | A.4       | `--summary` flag                                                                     | ✅ Shipped                                       | PR [#26](https://github.com/stainless-code/codemap/pull/26)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| B    | B.5       | `codemap audit` (structural-drift)                                                   | ⚠️ Partial — v1 + v1.x shipped; verdict deferred | v1 in PR [#33](https://github.com/stainless-code/codemap/pull/33) (`--baseline <prefix>` reusing B.6 baselines). v1.x `--base <ref>` worktree+reindex shipped in PR [#52](https://github.com/stainless-code/codemap/pull/52) (planned PR [#51](https://github.com/stainless-code/codemap/pull/51)) — closes the per-PR structural-diff loop. `verdict` / threshold config still deferred to v1.x+ — trigger: 2 consumers ship `jq`-based threshold scripts with similar shapes. Schema landed on `symbols` (not `exports`) per actual usage. |
-| B    | B.6       | `--save-baseline` / `--baseline` on `query`                                          | ✅ Shipped                                       | PR [#30](https://github.com/stainless-code/codemap/pull/30). Implemented as a `query_baselines` table inside `.codemap/index.db` (not parallel JSON files) — survives `--full` and SCHEMA bumps because the table is intentionally absent from `dropAll()`.                                                                                                                                                                                                                                                                                  |
-| B    | B.7       | `symbols.visibility` column                                                          | ✅ Shipped                                       | PR [#28](https://github.com/stainless-code/codemap/pull/28). Landed on `symbols` (not `exports`) — `visibility` is a property of the symbol's docstring, not its export status.                                                                                                                                                                                                                                                                                                                                                              |
-| B    | B.8       | `--format sarif` + `--format annotations`                                            | ✅ Shipped                                       | PR [#43](https://github.com/stainless-code/codemap/pull/43). `codemap query --format sarif\|annotations` (also on MCP `query` / `query_recipe` tools as `format: "sarif"\|"annotations"`); `rule.id = codemap.<recipe-id>` (`codemap.adhoc` for ad-hoc SQL); auto-detects `file_path` / `path` / `to_path` / `from_path`; aggregate recipes (`index-summary`, `markers-by-kind`) emit `results: []` + stderr warning. Per-recipe `sarifLevel` / `sarifMessage` / `sarifRuleId` overrides via frontmatter deferred to v1.x.                   |
-| C    | C.9       | Framework plugin layer                                                               | ❌ Open                                          | Big surface; worth a `plans/<name>.md` before any code.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| C    | C.10      | LSP server + Code Lens                                                               | ❌ Open                                          | Independent but tangles with persistent-daemon non-goal.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| C    | C.11      | Static coverage ingestion                                                            | ✅ Shipped                                       | Plan PR [#56](https://github.com/stainless-code/codemap/pull/56); implementation this PR. `codemap ingest-coverage <path>` reads Istanbul JSON or LCOV (both formats v1 — `bun test --coverage` user not waiting). Natural-key `coverage` table joinable to `symbols`; three bundled recipes (`untested-and-dead`, `files-by-coverage`, `worst-covered-exports`) — every common agent question is a `--recipe` verb, no compose-your-own-JOIN tax.                                                                                           |
-| D    | D.12-D.16 | Suppressions / per-rule severity / `fix` / suffix-array dupes / runtime intelligence | ⏸️ Skip                                          | See § 1 Defer / skip table for the per-row reasoning.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-
-**Adjacent — also shipped post-refresh:**
-
-- **MCP server (agent-transports v1)** — `codemap mcp` ships every CLI verb (plus MCP-only `query_batch`) as JSON-RPC tools over stdio with six resources: four lazy-cached catalog resources (`codemap://recipes`, `codemap://recipes/{id}`, `codemap://schema`, `codemap://skill`) plus two live read-per-call resources (`codemap://files/{path}`, `codemap://symbols/{name}`). PR [#35](https://github.com/stainless-code/codemap/pull/35). Output shape verbatim from each tool's CLI `--json` envelope (no re-mapping). HTTP transport (`codemap serve`) shipped post-MCP — see PR #44 entry below.
-- **Recipes-as-content registry** — bundled recipes are now `<id>.{sql,md}` file pairs in `templates/recipes/`; project teams ship internal SQL via git-tracked `<projectRoot>/.codemap/recipes/<id>.{sql,md}`. PR [#37](https://github.com/stainless-code/codemap/pull/37). Catalog gains `source` / `body` / `shadows` fields so agents see project overrides at session start; YAML frontmatter actions on `.md` mean project recipes feel first-class. Load-time DML/DDL deny-list + runtime `PRAGMA query_only=1` backstop.
-- **Targeted-read CLI** — `codemap show <name>` + `codemap snippet <name>` for precise lookup-by-symbol-name without composing SQL. PR [#39](https://github.com/stainless-code/codemap/pull/39). Both verbs share the same flag set (`--kind`, `--in <path>`) and an agent-friendly `{matches, disambiguation?}` envelope; `snippet` adds `source` / `stale` / `missing` per match (read + flag, no auto-reindex side-effects). Registered as MCP tools too — every read verb maps to a tool. PR also shipped defence-in-depth security fixes (LIKE-wildcard escape on `--in`, path-traversal rejection in `agents-init`, non-blocking `bun audit` CI job).
-- **Doc-governance Rule 10** added during PR [#29](https://github.com/stainless-code/codemap/pull/29) — every core-surface change must update both `templates/agents/` (ships to npm) and `.agents/` (this clone) in lockstep.
-- **`cli/*` → `application/*` engine lift (internal)** — PR [#41](https://github.com/stainless-code/codemap/pull/41) closed the last layer-reversal imports `application/mcp-server.ts` had on `cli/*` (called out in the PR #35 self-audit). New engines `context-engine` / `validate-engine`; `query-recipes` moved to `application/`; envelope builders + helpers consolidated in `audit-engine` / `show-engine`. Pure refactor — no behavior or public API change — but unblocks the HTTP transport (B-tier `serve`) since that engine reuse is now clean.
-- **`codemap serve` HTTP API** — PR [#44](https://github.com/stainless-code/codemap/pull/44). Same tool taxonomy as `codemap mcp` over `POST /tool/{name}` for non-MCP consumers (CI scripts, simple `curl`, IDE plugins). Loopback default (`127.0.0.1:7878`); optional `--token` for Bearer auth. Bare `node:http` (no Express/Fastify dep). Tool bodies + resource fetchers live in shared `application/{tool,resource}-handlers.ts` — both transports dispatch the same pure handlers. CSRF + DNS-rebinding guard rejects `Sec-Fetch-Site: cross-site|same-site`, mismatched `Host` (loopback bind), and any `Origin` header — defends against malicious local webpages `fetch`-ing the API while the dev browses. Per-tool Zod validation at the HTTP boundary; ToolResult error arm carries `status?: 400|404|500` so unknown recipe / baseline → 404 and engine throws → 500.
-- **`.codemap/` directory consolidation + self-healing files** — PR [#54](https://github.com/stainless-code/codemap/pull/54), planned in PR [#53](https://github.com/stainless-code/codemap/pull/53). Single state directory under `<root>/.codemap/` (default; overridable via `--state-dir` / `CODEMAP_STATE_DIR`). `.codemap.db` → `.codemap/index.db`; `<root>/codemap.config.{ts,json}` → `.codemap/config.{ts,js,json}`. Self-managed `.codemap/.gitignore` (blacklist of generated artifacts) — codemap reconciles it (and JSON config) on every boot via `ensureStateGitignore` / `ensureStateConfig`. Bumping the canonical content IS the migration: every consumer's project repairs itself on next codemap run, no per-feature `agents-init.ts` `.gitignore` patching forever after. Pattern inspired by flowbite-react's `setup-*` shape, expressed in codemap's own conventions (`ensure*` reconcilers, Zod schema as single source of truth via `z.infer`, pure `{before, after, written}` return shapes for testability).
-- **`codemap audit --base <ref>` (git-ref baseline)** — PR [#52](https://github.com/stainless-code/codemap/pull/52), planned in PR [#51](https://github.com/stainless-code/codemap/pull/51). Closes the highest-frequency post-watch agent loop: "what changed structurally between this branch and origin/main?". Worktree+reindex against any git committish to a sha-keyed cache under `.codemap/audit-cache/`; cache hit on second run is sub-100ms. Atomic populate via per-pid temp dir + POSIX `rename` — concurrent CI matrix runs safe by construction. `AuditBase` discriminated union — existing `{source: "baseline", ...}` rows untouched, new `{source: "ref", ref, sha, ...}` arm. Mutually exclusive with `--baseline <prefix>`; per-delta `--<key>-baseline` overrides compose orthogonally. Hard error on non-git projects (no graceful fallback — there's no meaningful "ref" without git). MCP `audit` tool gains `base?: string` arg + HTTP `POST /tool/audit` lights up automatically via the existing dispatcher.
-- **`codemap impact` (blast-radius walker)** — PR [#50](https://github.com/stainless-code/codemap/pull/50), planned in PR [#49](https://github.com/stainless-code/codemap/pull/49). Replaces the "agent composes `WITH RECURSIVE` by hand" tax — single verb walks the calls / dependencies / imports graphs (callers, callees, dependents, dependencies), depth- and limit-bounded, cycle-detected. Same pure-engine pattern as `show` / `snippet`: `application/impact-engine.ts` reused by CLI / MCP `impact` / HTTP `POST /tool/impact` via the existing `tool-handlers.ts` dispatcher. Symbol vs file targets walk compatible backends automatically; mismatched explicit `--via` choices land in `skipped_backends`. Output envelope `{target, matches, summary: {nodes, terminated_by}}` — `--summary` trims `matches` for cheap CI-gate consumption (`jq '.summary.nodes'`).
-- **`codemap watch` (live reindex)** — PR [#47](https://github.com/stainless-code/codemap/pull/47), planned in PR [#46](https://github.com/stainless-code/codemap/pull/46). The biggest agent-UX win in the roadmap: eliminates the "is the index stale?" friction every CLI / MCP / HTTP query rides on today. Three shapes: standalone `codemap watch`, plus killer combos `codemap mcp --watch` and `codemap serve --watch` (also `CODEMAP_WATCH=1`). Chokidar v5 backend (selected via 6-watcher audit on PR #46 — pure JS, no Bun N-API quirks, identical on Bun + Node). Sliding-window debouncer (default 250 ms) + path-segment exclude scan + project-local recipe glob. Optional `onPrime` opt runs an incremental catch-up BEFORE flipping `isWatchActive()` true so `handleAudit` only skips its prelude when the index is genuinely fresh. Stop drains in-flight reindex (serialized via inFlight chain) before close so SIGINT/SIGTERM never leaves a half-written DB. Backend errors clear the active flag so a dying chokidar re-enables the audit prelude immediately.
-
-**Open-questions resolution** (from § 6 below):
-
-- "Should `actions` (A.1) live in recipe definitions or be derived?" — **(a) recipe-defined**, settled in PR [#26](https://github.com/stainless-code/codemap/pull/26).
-- "`codemap audit` (B.5) verdict threshold defaults?" — **defer verdict to v1.x; ship raw deltas + `jq` idiom in v1**, settled in PR [#33](https://github.com/stainless-code/codemap/pull/33).
-- "Coverage ingestion (C.11) — column on `symbols` or separate `coverage` table?" — **separate table**, settled in plan PR [#56](https://github.com/stainless-code/codemap/pull/56) (D1 + D6 — natural-key PK survives the `symbols` drop-recreate cycle on every `--full` reindex; `LEFT JOIN coverage` keeps NULL semantics explicit).
-- "How invasive should the framework plugin layer (C.9) be?" — still open.
-
----
-
-## 0. Fresh evidence — what a hands-on graph audit surfaced
-
-This refresh is grounded in a third-party graph audit run against a TanStack-Router / TS app, where both Codemap and Fallow were used side-by-side across ~14 sections (ownership map, owner→owner dependency matrix, fan-in / fan-out hotspots, hook-heavy components, file LoC, external consumers, cycles, folder-size discipline, dead code, public-surface barrel usage). The exercise is the most recent bottom-up evidence of where each tool stops and the other starts.
-
-**Findings worth importing here (the rest is methodology-specific):**
-
-- **Codemap is irreplaceable for ad-hoc graph shape questions.** Sections 1–7 of the audit (owner partition, owner→owner matrix, top-30 fan-in, top-15 fan-out, hook-heavy components, ≥300-LoC files, cross-feature edges) were Codemap-only — there is no Fallow command that produces an arbitrary owner-bucketed dependency matrix. SQL flexibility is the moat.
-- **Codemap mis-classifies closed dead sub-graphs as live.** The audit found an 8-file widget pack created in an earlier refactor that no consumer ever wired up. Each file imported the others, so every file had non-zero fan-in by the codemap dependency table; the codemap "zero-fan-in" recipe missed the entire pack. Fallow's re-export-aware analysis (`fallow dead-code --unused-files`) caught all 8. **This is the canonical case where Codemap's structural-only posture leaves true gaps.** Adoption candidates A.4 and (much further out) E.15 below address it.
-- **PR-scoped delta is the most-felt gap.** Hydrating the audit twice (once after PR #1474–#1477, again after PR #1478) required hand-computing every section's delta vs the prior commit. Fallow's `audit --base <ref>` does this with one command. **§B.5 below is the single highest-leverage candidate this refresh.**
-- **Per-row `actions` hints save the agent a derivation step.** Every Fallow finding in `--format json` carries an `actions: [{type, auto_fixable, description, comment?}]` array. When the audit needed to write recommendations ("delete this file", "drop this export"), the action was already named in the JSON; the agent just transcribed it. Codemap rows currently force the agent to re-derive what to do with each row.
-
----
-
-## 1. Adoption candidates by leverage tier
-
-Action hints in this section are **proposals** — not commitments. Tier hints reflect rough effort vs. payoff at the time of the refresh; promote into `roadmap.md § Backlog` only when designed.
-
-### Tier A — Ship now (≤1 week each, mostly mechanical)
-
-| #   | Candidate                                     | Sketch                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Why this tier                                                                                                                                                             |
-| --- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| A.1 | **Per-row `actions` array on common recipes** | Each row from `query --recipe <id>` optionally carries `actions: [{type, auto_fixable, description}]`. Examples: `zero-fan-in-files` row → `[{type:"delete-file", auto_fixable:false}]`; `deprecated-symbols` row → `[{type:"open-deprecation-issue"}]`; `barrel-files` row → `[{type:"split-barrel"}]`. Recipe authors define the action template; the SQL stays untouched. Future ad-hoc SQL doesn't get actions automatically — that's fine, it's a recipe-only feature. | Mirrors fallow's killer agent-facing detail. Pure recipe-layer change in [`src/application/query-recipes.ts`](../../src/application/query-recipes.ts) — no schema impact. |
-| A.2 | **`--changed-since <ref>` on `query`**        | Filters every query result row to files whose path matches `git diff --name-only <ref>...HEAD`. Implementation: pre-compute the changed-file set, append `AND <left-table>.file_path IN (...)` (or `from_path` / `to_path` for `dependencies` queries) to the SQL. Same primitive fallow uses for `--changed-since main`.                                                                                                                                                   | Unlocks PR-scoped queries without `codemap audit` (which is bigger — see B.5). Cheap; no schema impact.                                                                   |
-| A.3 | **`--group-by owner\|directory\|package`**    | Partition any `file_path`-bearing query result by CODEOWNERS first-owner / first directory component / workspace package. Implementation: post-process at JSON emit time; no SQL change required.                                                                                                                                                                                                                                                                           | Layered on top of existing query output; no schema impact. CODEOWNERS reading is the only new bit.                                                                        |
-| A.4 | **`--summary` flag**                          | Counts only, no rows. Useful pair with `--recipe` for dashboards / agent context windows.                                                                                                                                                                                                                                                                                                                                                                                   | Trivial; aligns with `codemap context --compact`.                                                                                                                         |
-
-### Tier B — Ship next (1–3 weeks; meaningful design work)
-
-| #   | Candidate                                                                  | Sketch                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Why this tier                                                                                                                                                                                                                                                                                     |
-| --- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| B.5 | **`codemap audit --base <ref>` — structural-drift verdict**                | Single command returning `{verdict: "pass"\|"warn"\|"fail", deltas: {…}}`. Built-in deltas: new files / deleted files / new edges in `dependencies` / new boundary crossings against a glob list / new cycles / top-N hot-file movements / new `@deprecated` symbols. **Highest-leverage candidate this refresh** — the audit hydrate loop hand-computed every one of these. Verdict thresholds are config-driven (per-delta `error\|warn\|off`). Don't try to compete with `fallow audit` on dead-code or duplication; stay structural. | This is the gap that hurt most in real use. Architecture work needed: where delta computation lives, how thresholds are configured, what the "two-snapshot diff" abstraction looks like (probably temp DB on the base ref, similar to fallow's git-worktree approach). Worth a `plans/<name>.md`. |
-| B.6 | **`--save-baseline` / `--baseline` on `query`**                            | Save current row-set to a JSON file; on next run compare and emit only the diff. Fallow ships this for all of `dead-code` / `dupes` / `health`. Codemap users would use it to baseline the dependency-edge count, the hot-file top-30, the boundary-violation set — anything queryable that should not regress.                                                                                                                                                                                                                          | Independent of B.5 but composes well with it. JSON snapshot file (probably under `.codemap/baselines/<recipe>.json`) is straightforward.                                                                                                                                                          |
-| B.7 | **JSDoc visibility extracted as a structured `symbols.visibility` column** | Already partially shipped: PR #23's `visibility-tags` recipe parses `@public` / `@internal` / `@beta` / `@alpha` / `@private` from `doc_comment`. Promote the parser output into a real `symbols.visibility` column (the original proposal hedged on `exports` vs `symbols`; the shipped column landed on `symbols` per the Status snapshot above) so queries like `WHERE visibility = 'beta'` don't need a `LIKE '%@beta%'` regex. Schema bump — counts as a minor per `.agents/lessons.md` "changesets bump policy".                   | Removes the two-step recipe (parse + filter) that the current setup forces. Aligns Codemap's surface with fallow's first-class JSDoc handling without copying fallow's rule machinery.                                                                                                            |
-| B.8 | **`--format sarif` and `--format annotations` (GitHub PR inline)**         | SARIF gives `--format json` consumers a path into GitHub Code Scanning without an Action wrapper. `--format annotations` emits the `::warning file=…,line=…::msg` GitHub-Actions output format — Fallow uses this to write inline PR comments without needing a custom Action.                                                                                                                                                                                                                                                           | Both are pure output-formatter additions on top of the existing JSON pipeline. The reason this is B not A: deciding the SARIF rule-id taxonomy for arbitrary recipes needs a small design pass.                                                                                                   |
-
-### Tier C — Ship eventually (months; high payoff, large surface)
-
-| #    | Candidate                                                                      | Sketch                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Why this tier                                                                                                                                                                                                                                                              |
-| ---- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| C.9  | **Framework plugin layer (entry-point + convention-export awareness)**         | Fallow's 91 plugins teach it that a Next.js `app/page.tsx` `default export` is a live entry, that Storybook stories are entries, that Vite `vite.config.ts` aliases mean `~/foo` resolves to `src/foo`, etc. Codemap currently treats every file equally — that's why the audit's hands-on §10 had to hand-maintain a "4 known re-export false positives" list. **A plugin layer is the only feature that closes the §10 gap structurally.** Don't replicate fallow's full plugin API; start with entry-point hints (each plugin contributes a glob → `is_entry: true` annotation on `files`), expand to convention exports if demand emerges. Plugin contract should be small enough that the community can add plugins without forking the core. Cross-references: existing roadmap item "Community language adapters" is adjacent (per-language adapters) but distinct (per-framework conventions). | The single feature that would let Codemap's `dependencies` table be authoritative for "is this file dead" instead of advisory. Big surface — plugin contract design, registry mechanism, version negotiation. Worth a `plans/<name>.md` before any code.                   |
-| C.10 | **LSP server + Code Lens with reference counts**                               | Hover an import statement → "fan-in: 17 callers, fan-out: 3"; gutter badge on `@deprecated` symbols using existing `doc_comment`; "go to N callers" code action backed by the `calls` table. Fallow ships LSP + a VS Code extension with status bar / tree views. Codemap has neither. The data is already in the SQLite index — this is presentation, not analysis.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Independent of B.5 / C.9 but very visible. Adds runtime requirements (LSP needs a long-lived process or quick-start) — interacts with the [persistent daemon non-goal](../roadmap.md#non-goals-v1). LSP is a separate process model from "one-shot CLI"; design carefully. |
-| C.11 | **Static coverage ingestion (`coverage-final.json` → `symbols.coverage_pct`)** | Add `coverage_pct REAL` and `is_runtime_hot INTEGER` columns to `symbols` (or `files`), populated from an Istanbul `coverage-final.json` if `--coverage <path>` is passed at index time. Then queries like "find unused exports with 0% test coverage" or "rank hot files by fan-in × coverage" become single SQL queries. Fallow's runtime-coverage layer is paid; the static side (Istanbul ingestion) is free and complements Codemap's structural posture nicely.                                                                                                                                                                                                                                                                                                                                                                                                                                  | Schema bump (minor per lessons.md). One-time ingester, no continuous integration with V8 traces. Production beacons (fallow's paid moat) explicitly out of scope.                                                                                                          |
-
-### Defer / skip
-
-| #    | Candidate                                                        | Reason                                                                                                                                                                                                                                                                                       |
-| ---- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| D.12 | **Suppression comments (`// codemap-ignore-next-line`)**         | Only relevant if Codemap pivots toward shipping opinionated rules / verdicts. Today Codemap ships SQL primitives, not assertions — there's nothing to suppress. Reconsider only after B.5 (`codemap audit`) lands and starts producing pass/warn/fail.                                       |
-| D.13 | **Per-rule severity in config (`{rules: {…: "error"\|"off"}}`)** | Same condition as D.12 — meaningless without first-class assertions. If B.5 lands, this becomes the natural config shape for the audit thresholds.                                                                                                                                           |
-| D.14 | **`fallow fix --dry-run` equivalent**                            | Codemap doesn't own behaviour to fix. Per-row `actions` (A.1) carries fix _suggestions_; executing them is the agent's job, not Codemap's. Don't grow a fix engine — the structural-index thesis stays cleaner without one.                                                                  |
-| D.15 | **Suffix-array duplication detection**                           | Codemap is not a duplication tool — that's covered by [roadmap.md § Non-goals (v1)](../roadmap.md#non-goals-v1) and the user reaches for `fallow dupes` or `jscpd`. Replicating fallow's suffix-array engine would dilute the structural-index thesis. Same logic as the dead-code non-goal. |
-| D.16 | **Runtime intelligence (V8 / production beacons)**               | Fallow's paid moat. Static coverage ingestion (C.11) is in scope; production beacons are not.                                                                                                                                                                                                |
-
----
-
-## 2. Already on the roadmap (cross-link, don't re-propose)
-
-These overlap with what fallow does, but were already on [`roadmap.md § Backlog`](../roadmap.md#backlog) before this refresh — go there for the latest status:
-
-- **MCP server wrapping `query`** — agents call `query` / `recipe` / `schema` / `index` directly without a Bash round-trip. Same UX shape as fallow's MCP integration with Claude Code / Cursor / Codex.
-- **HTTP API (`codemap serve`)** — adjacent transport for non-MCP consumers.
-- **Watch mode** — re-analyse on file changes; fallow has `fallow watch` with the same shape.
-- **Monorepo / workspace awareness** — fallow has `--workspace`, `--changed-workspaces`. Codemap's roadmap item targets per-workspace dependency graphs.
-- **Targeted-read CLI (`codemap show <symbol>`)** — adjacent to A.1 actions but a separate ergonomic affordance.
-
-If any of these get prioritised, fallow's CLI flag shape is the closest precedent — copying it where it doesn't cost anything keeps the surface familiar to fallow users.
-
----
-
-## 3. Already shipped from the prior scan
-
-PR [#23](https://github.com/stainless-code/codemap/pull/23) shipped fallow-inspired items in 2026-04 — see [`research/competitive-scan-2026-04.md` § 3](./competitive-scan-2026-04.md#3-what-shipped-from-this-scan). Highlights:
-
-- `deprecated-symbols` and `visibility-tags` recipes (inspired by fallow's JSDoc visibility tags) — B.7 (now shipped in PR [#28](https://github.com/stainless-code/codemap/pull/28)) promoted the parser output into a structured `symbols.visibility` column, so `visibility-tags` queries `WHERE visibility IS NOT NULL` instead of `LIKE '%@beta%'`.
-- "Grep/Read vs Codemap" capability table in the root README (inspired by fallow's "Linter vs Fallow" framing).
-
-The dated scan stays the canonical record of that pass; this file picks up where it left off.
-
----
-
-## 4. What NOT to copy (preserve Codemap's structural advantage)
-
-These are the things fallow does that Codemap should explicitly _not_ adopt — copying them would dilute the SQL-index thesis:
-
-| Fallow capability                                    | Why Codemap should skip it                                                                                                                                                                                                                                      |
-| ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Pre-baked verdicts as the foundation**             | Fallow's posture is "the tool wrote the predicate, you read the verdict." Codemap's posture is "you write the predicate." Don't lose that. B.5 (`codemap audit`) is fine because it's a **wrapper** over `query` recipes — `query` itself stays the foundation. |
-| **Suffix-array clone detection / Rust-native speed** | Different stack, different optimisation choices. Codemap is fast enough for incremental TS via oxc — chasing fallow's perf would require a rewrite. See also D.15.                                                                                              |
-| **Runtime intelligence (V8 / Istanbul beacons)**     | Fallow's paid moat. Static coverage ingestion (C.11) is fine; production runtime tracking is out of scope. See also D.16.                                                                                                                                       |
-| **Embedded fix engine**                              | Fallow has `fallow fix` that mutates code. Codemap should stay read-only — fix _suggestions_ via A.1 `actions` are enough; execution is the agent's job. See also D.14.                                                                                         |
-
----
-
-## 5. Where Codemap is already ahead (fallow could learn back)
-
-Captured here so the symmetry is honest — the audit exercise made these visible too:
-
-- **Ad-hoc SQL on the structural index.** Fallow ships pre-baked verdicts; Codemap lets you write any predicate. Owner→owner matrix, fan-in top-30, public-surface importer counts — all Codemap-only because no fallow command produces them.
-- **`components.hooks_used` JSON column.** React hook usage per component is a Codemap extraction; fallow doesn't surface this.
-- **CSS variables / classes / keyframes.** Fallow doesn't model CSS at all.
-- **`markers` table.** TODO / FIXME / HACK as queryable rows with line + content. Fallow doesn't surface markers.
-- **`type_members` table.** Field-level type inventory queryable. Fallow's analysis doesn't go to this depth.
-- **`calls` table.** Caller→callee at the symbol level. Fallow's analysis is module-level.
-
-Don't trade these away for fallow parity — they're the moat. The Tier A / B candidates above are explicitly designed to layer on top of these strengths, not replace them.
-
----
-
-## 6. Open questions
-
-- **Should `actions` (A.1) live in recipe definitions or be derived?** Two shapes: (a) recipe author hand-writes the `actions` template alongside the SQL — predictable, every row gets the same actions; (b) a small action-derivation layer keyed off recipe id + row shape — less code, less control. Bias toward (a) for the first pass.
-- **How invasive should the framework plugin layer (C.9) be?** Two extreme shapes: (i) plugins only contribute entry-point globs (`is_entry: true` annotation on `files`); (ii) plugins can contribute arbitrary `dependencies` edges (e.g. "Next.js's `next/link` href references this route"). (i) keeps the surface small and composable; (ii) catches more but explodes the contract surface and risks plugin drift. Bias toward (i) — see how far it gets us before reaching for (ii).
-- **`codemap audit` (B.5) verdict threshold defaults.** Fallow defaults to `pass / warn / fail` with reasonable thresholds. Codemap's structural deltas don't have obvious thresholds yet ("how many new dependency edges is too many?" depends entirely on the project). First pass probably exposes raw deltas only and lets the consumer set thresholds in `<state-dir>/config.{ts,js,json}`.
-- **Coverage ingestion (C.11) — column on `symbols` or separate `coverage` table?** Putting `coverage_pct` on `symbols` keeps queries simple but couples schema bumps to coverage shape changes. A `coverage` table with `(symbol_id, coverage_pct, last_updated)` is more flexible but forces every coverage query to JOIN. Probably worth prototyping both before committing.
-
----
-
-## 7. Citations / cross-links
-
-- Prior three-tool scan: [`research/competitive-scan-2026-04.md`](./competitive-scan-2026-04.md)
-- Fallow upstream: [`fallow-rs/fallow`](https://github.com/fallow-rs/fallow) (refresh hash: `v2.56.0`, 2026-04-29)
-- Fallow's audit-on-PR thresholds (the closest cousin to Codemap's B.5 candidate): [`fallow` README § Audit](https://github.com/fallow-rs/fallow#audit)
-- Codemap roadmap items already overlapping with fallow: [`roadmap.md § Backlog`](../roadmap.md#backlog) and [`roadmap.md § Non-goals (v1)`](../roadmap.md#non-goals-v1)
-- Adjacent ongoing work: [`agents.md`](../agents.md) (the `codemap agents init` surface that fallow's MCP / Skill packaging mirrors)
diff --git a/docs/research/non-goals-reassessment-2026-05.md b/docs/research/non-goals-reassessment-2026-05.md
index 6717b0f..91391ec 100644
--- a/docs/research/non-goals-reassessment-2026-05.md
+++ b/docs/research/non-goals-reassessment-2026-05.md
@@ -2,8 +2,6 @@
 
 > **Status:** lifted (2026-05-04) — durable decisions in [`roadmap.md § Non-goals (v1)`](../roadmap.md#non-goals-v1); pending picks tracked in [`roadmap.md § Backlog`](../roadmap.md#backlog) or dedicated plan PRs ([`c9-plugin-layer.md`](../plans/c9-plugin-layer.md), [`lsp-diagnostic-push.md`](../plans/lsp-diagnostic-push.md)). This note retains analytical history (§ 2 reasoning, § 5 pick-order rationale, § 8 errata).
 >
-> **Companion doc:** [`research/competitive-scan-2026-04.md`](./competitive-scan-2026-04.md) — closed; historical three-tool scan.
->
 > **Original positioning:** codemap occupies a specific niche in the **SQLite-backed-code-index cohort** for AI agents (peers: `srclight`, `Sverklo`, `ctxpp`, `KotaDB`, `codemogger`, `@squirrelsoft/code-index`, `QuickAST`, etc. — most use tree-sitter + SQLite + embeddings). Codemap's differentiation: **(1) predicate-as-API** (raw SQL + recipes) — peers ship pre-baked verbs; **(2) pure structural** — no embeddings, no LLM in box; **(3) JS/TS/CSS-ecosystem-deep extraction** via `oxc` + `lightningcss`. Mission: extract maximum value from the predicate-as-API thesis on this niche; grow the ecosystem.
 >
 > **Errata note (2026-05):** Three claims in v1 of this doc were softened or corrected after cross-checking against the codebase. See [§ 8](#8-triangulation-errata-2026-05) for the full diff and the process lesson it surfaced.
@@ -103,7 +101,7 @@ ripgrep can't compose with `symbols` / `coverage` / `markers` in one shot — it
 
 - **Agents** don't use LSP. They use MCP. The "Very High agent UX" framing in v1 was wrong.
 - **VSCode / IDEs with `tsserver`** — `tsserver` dominates **standard pull-model requests** (`textDocument/definition` / `references` / `hover types` / `workspace/symbol`) for JS/TS users. A shim wrapping `show`/`impact`/`watch` engines for those requests would duplicate marginally and provide ~zero unique value. **This is what v2 correctly rejected.**
-- **The actually-valuable LSP shape is a diagnostic-push server, not a request-handler shim.** Reference: fallow's `crates/lsp/` (~1800 LoC, `tower-lsp`) explicitly skips `definition` / `references` / `documentSymbol` and instead implements `diagnostic` (LSP 3.17 pull) + `code_action` + `code_lens` + `hover` + a custom `fallow/analysisComplete` notification consumed by their paired `editors/vscode/` extension.
+- **The actually-valuable LSP shape is a diagnostic-push server, not a request-handler shim.** A diagnostic-push server skips `textDocument/definition` / `references` / `documentSymbol` (where `tsserver` already wins) and instead implements `diagnostic` (LSP 3.17 pull) + `code_action` + `code_lens` + `hover` + a custom `codemap/analysisComplete` notification consumed by a paired VSCode extension. This is the shape proven to deliver value in the VS Code marketplace cohort.
 - **Why this is moat-A-aligned (despite "diagnostics ≈ verdicts"):** diagnostics here are an `--format lsp-diagnostic` rendering of bundled recipes. **Reviewer test:** "is the same finding queryable via `query --recipe X`?" If no recipe drives a diagnostic, it's a verdict-shaped primitive (rejected). Same discipline as `--format sarif` / `--format annotations` / `--format mermaid`.
 
 **Lifted to:** [`docs/plans/lsp-diagnostic-push.md`](../plans/lsp-diagnostic-push.md) carries the canonical scope + publishing prerequisites + repo-structure tradeoffs.
@@ -124,7 +122,7 @@ The reasoning that produced the cadence (a) ✅ → (c) ✅ → § 1.10 rename-p
 
 1. **(a) FTS5 + Mermaid output (shipped).** Cheapest non-goal flip; one PR; the moat rewrite paid the "flip a non-goal cleanly" confidence move so (a) didn't need to re-pay it.
 2. **(c) Cyclomatic complexity column (shipped).** Reused (a)'s "new column on `symbols`" muscle; kept the cadence.
-3. **(d) reframed (errata 2026-05 v3).** v1 ordered (b) before (d) on the wrong assumption that LSP shim consumed (b)'s entry-point awareness. v2 dropped (d) entirely after a consumer audit found agents-don't-use-LSP and tsserver-dominates-standard-requests — both true, but they only apply to the **request-handler** shape v2 was rejecting. The actually-valuable shape (proven by fallow shipping `crates/lsp/` + `editors/vscode/` to >80k VSCode marketplace installs) is **diagnostic-push server + paired VSCode extension** — recipes-as-squigglies, not go-to-def. v3 restores (d) with the corrected shape, XL effort, ships last after (b). **Three revisions across three grilling turns** — the doc captures all three so future readers see the reasoning, not just the final answer.
+3. **(d) reframed (errata 2026-05 v3).** v1 ordered (b) before (d) on the wrong assumption that LSP shim consumed (b)'s entry-point awareness. v2 dropped (d) entirely after a consumer audit found agents-don't-use-LSP and tsserver-dominates-standard-requests — both true, but they only apply to the **request-handler** shape v2 was rejecting. The actually-valuable shape is **diagnostic-push server + paired VSCode extension** — recipes-as-squigglies, not go-to-def. v3 restores (d) with the corrected shape, XL effort, ships last after (b). **Three revisions across three grilling turns** — the doc captures all three so future readers see the reasoning, not just the final answer.
 4. **§ 1.5 / § 1.10 / § 1.9 / § 1.6 are all orthogonal to (b)** — § 1.5 uses its own `boundary_rules` table, § 1.10 queries `calls` (no reachability concept), § 1.9 has its own table, § 1.6 uses `type_members` × `imports.specifiers`. None query "is this file reachable from an entry?", so none inherit the closed-dead-subgraph false-positive class C.9 sharpens.
 5. **(b) before (d)** — (b) C.9's entry-point awareness sharpens (d)'s diagnostic precision (fewer false-positive squigglies on framework files for `untested-and-dead`, `unimported-exports`). Not a hard block — (d) ships valid diagnostics on the existing recipe outputs without (b) — but landing (b) first means (d) inherits cleaner inputs from day one. The deferral cost on (b) is bounded (two advisory recipes with documented caveats); (d)'s deferral cost is zero (no consumer waiting today).
 
@@ -159,7 +157,6 @@ The lift trail — for future archaeologists asking "where did this idea / decis
 Other anchors:
 
 - [`architecture.md § Schema`](../architecture.md#schema) — canonical schema reference.
-- [`research/competitive-scan-2026-04.md`](./competitive-scan-2026-04.md) — historical three-tool scan (closed; this doc supersedes its non-goals shaping).
 - [`docs/why-codemap.md § When to reach for something else`](../why-codemap.md#when-to-reach-for-something-else) — consumer-facing alternatives positioning.
 
 ---
@@ -168,14 +165,14 @@ Other anchors:
 
 v1 of this doc was reasoned-from-substrate without enough pinning to actual file:line / `codemap query` references. A peer-model review (`composer-2-fast`) cross-checked every concrete claim against `db.ts`, `builtin.ts`, `audit-engine.ts`, `--recipes-json`, and `templates/recipes/*.sql` — caught three errors. Corrections applied below; documenting them here so future reviewers can see the diff between v1 and v2.
 
-| Section                       | Original claim                                                                                                                                                                                                                                                                                             | Corrected claim                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Evidence (codebase = source of truth)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| **§ 1.2**                     | "Exports never imported anywhere — one recipe; XS effort"                                                                                                                                                                                                                                                  | Same recipe; **S** effort because `exports.re_export_source` requires a JOIN through re-export chains to avoid false positives on barrel-only exports                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `db.ts:69` `re_export_source` column on `exports` table                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| **§ 1.3**                     | "AST node count from parser already in place" + "S effort"                                                                                                                                                                                                                                                 | Node-counting is **not** in place; needs an extension to the AST walker in `src/parser.ts`. **M** effort.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `rg 'complexity\|node_count\|nodeCount' src/` returns zero matches                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| **§ 2.3**                     | "We already ship `deprecated-symbols`, `untested-and-dead`, `barrel-files`, `fan-in`, `fan-out` — those _are_ static analysis"                                                                                                                                                                             | Same list, but with the caveat that `fan-in` / `fan-out` are **hotspot rankers** (`ORDER BY DESC LIMIT 15`), not orphan / dead-code detectors. They don't cover the closed-dead-subgraph case (N-file packs with self-imports — every file has non-zero fan-in but none reachable from a real entry) — that gap motivates C.9 (framework plugin layer), not the "no static analysis" flip                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `templates/recipes/fan-in.sql` shows `ORDER BY fan_in DESC LIMIT 15`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| **§ 5 (d) row + Rationale 4** | "(d) LSP shim blocks on (b) impl for entry-point awareness; (d) lands last because LSP shim wants entry-point awareness from (b) to give accurate find references"                                                                                                                                         | (d) is **orthogonal** to (b). Standard LSP `textDocument/references` / `textDocument/definition` return `Location[]` (file_path + range) with no decoration field, so C.9's `is_entry` annotation can't ride on the LSP response shape. C.9 sharpens **recipe-layer** outputs (`untested-and-dead`, `unimported-exports`); (d) ships shipping cadence whenever its slot arrives, not blocked on (b). Ship sequence corrected: (b) C.9 lands **last**; (d) and § 1.5 / § 1.10 / § 1.9 / § 1.6 all ship before it                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `bun src/index.ts query --json "SELECT name, signature FROM symbols WHERE file_path = 'src/application/show-engine.ts' AND parent_name IS NULL AND kind = 'function'"` confirms `findSymbolsByName`, `buildShowResult`, `readSymbolSource` exist; same for `impact-engine.ts` (`findImpact`, `walkCalls`, `walkFileGraph`); `src/application/watcher.ts` exports `runWatchLoop` + imports `chokidar`. No `is_entry` column on `files` (live `sqlite_schema` dump confirms — C.9 unshipped)                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| **§ 5 (b) row**               | "Sharpens every shipped recipe (untested-and-dead currently false-positives Next.js page.tsx)"                                                                                                                                                                                                             | Sharpens **two** already-shipped recipes that ask "is this live?" (`untested-and-dead`, `unimported-exports`). Foundation for one hypothetical future recipe (`dead-files-by-reachability`, c9 plan Slice 2). Recipes asking other questions (boundary, hotspot, complexity, calls, marker, CSS) don't inherit C.9's false-positive class because they don't query reachability                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Reviewed every shipped recipe in `templates/recipes/*.sql`; only `untested-and-dead` and `unimported-exports` predicate on "is symbol/file live"                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| **§ 4 intro**                 | "Codemap is structurally unique (only SQL-based code index in the market); there's no peer tool to clone"                                                                                                                                                                                                  | Codemap occupies a **specific niche** in the SQLite-backed-code-index cohort. Peer tools exist; none share all three differentiation axes (predicate-as-API + pure structural + JS/TS/CSS-deep extraction) simultaneously. Updated to align with header positioning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Header (line 9) acknowledges peer tools `srclight`, `Sverklo`, `ctxpp`, `KotaDB`, `codemogger`, `@squirrelsoft/code-index`, `QuickAST`; § 4 first sentence contradicted that without justification                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| **§ 5 (d) / § 2.5 / § 6 Q3**  | **Three revisions across three grilling turns** — v1: "thin shim wrapping show/impact engines; Very High agent UX; ship before (b)" → v2: "orthogonal to (b); ship between § 1.9 and § 1.6" → v2.5: "dropped from ship sequence; deferred until concrete consumer" → **v3: restored with corrected shape** | **v3 final:** (d) is a **diagnostic-push LSP server + paired VSCode extension**, not a request-handler shim. v2's rejection of the request-handler shape was correct (tsserver dominates `definition`/`references`/`hover types`; agents use MCP not LSP). v2.5's outright drop was **incomplete** — it conflated "LSP shim wrapping engines for go-to-def" (correctly rejected) with "LSP server pushing recipes-as-`Diagnostic[]`" (a different shape, high-value, proven by fallow). Corrected shape: each `{file_path, line, message}`-shaped recipe → `Diagnostic[]` source (squigglies); hover provider over `symbols.signature` + `doc_comment` + `complexity` + caller-count; code lens for fan-in / complexity / coverage; code actions hooked to `recipe.actions` template; custom `codemap/analysisComplete` notification for paired VSCode extension. **Moat-A discipline:** every diagnostic must be the `--format lsp-diagnostic` rendering of a bundled recipe (reviewer test: "is this also queryable via `query --recipe X`?"). XL effort; ships last after (b) C.9 so entry-point awareness sharpens diagnostic precision | Inspected fallow's `crates/lsp/src/main.rs` (~1800 LoC, `tower-lsp`): handlers implemented are `initialize` / `did_open` / `did_change` / `did_save` / `diagnostic` (LSP 3.17 pull) / `code_action` / `code_lens` / `hover` + custom `fallow/analysisComplete` notification. Handlers **NOT** implemented: `definition`, `references`, `documentSymbol`, `workspace/symbol` — explicitly skipped. Paired with `editors/vscode/` (~2400 LoC TS): `vscode-languageclient/node` over stdio, tree views (`fallow.deadCode`, `fallow.duplicates`), status bar fed by custom notification, auto-download binary, settings UI for issue toggles + git ref. Server + extension is the unit, not either alone. Diagnostic codes pushed: `unused-file`, `unused-export`, `unused-type`, `boundary-violation`, `circular-dependency`, `code-duplication`, `dead-code`, `quality` (complexity), etc. — direct precedent for codemap's recipe-as-diagnostic mapping |
+| Section                       | Original claim                                                                                                                                                                                                                                                                                             | Corrected claim                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Evidence (codebase = source of truth)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **§ 1.2**                     | "Exports never imported anywhere — one recipe; XS effort"                                                                                                                                                                                                                                                  | Same recipe; **S** effort because `exports.re_export_source` requires a JOIN through re-export chains to avoid false positives on barrel-only exports                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `db.ts:69` `re_export_source` column on `exports` table                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| **§ 1.3**                     | "AST node count from parser already in place" + "S effort"                                                                                                                                                                                                                                                 | Node-counting is **not** in place; needs an extension to the AST walker in `src/parser.ts`. **M** effort.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `rg 'complexity\|node_count\|nodeCount' src/` returns zero matches                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| **§ 2.3**                     | "We already ship `deprecated-symbols`, `untested-and-dead`, `barrel-files`, `fan-in`, `fan-out` — those _are_ static analysis"                                                                                                                                                                             | Same list, but with the caveat that `fan-in` / `fan-out` are **hotspot rankers** (`ORDER BY DESC LIMIT 15`), not orphan / dead-code detectors. They don't cover the closed-dead-subgraph case (N-file packs with self-imports — every file has non-zero fan-in but none reachable from a real entry) — that gap motivates C.9 (framework plugin layer), not the "no static analysis" flip                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `templates/recipes/fan-in.sql` shows `ORDER BY fan_in DESC LIMIT 15`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| **§ 5 (d) row + Rationale 4** | "(d) LSP shim blocks on (b) impl for entry-point awareness; (d) lands last because LSP shim wants entry-point awareness from (b) to give accurate find references"                                                                                                                                         | (d) is **orthogonal** to (b). Standard LSP `textDocument/references` / `textDocument/definition` return `Location[]` (file_path + range) with no decoration field, so C.9's `is_entry` annotation can't ride on the LSP response shape. C.9 sharpens **recipe-layer** outputs (`untested-and-dead`, `unimported-exports`); (d) ships shipping cadence whenever its slot arrives, not blocked on (b). Ship sequence corrected: (b) C.9 lands **last**; (d) and § 1.5 / § 1.10 / § 1.9 / § 1.6 all ship before it                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | `bun src/index.ts query --json "SELECT name, signature FROM symbols WHERE file_path = 'src/application/show-engine.ts' AND parent_name IS NULL AND kind = 'function'"` confirms `findSymbolsByName`, `buildShowResult`, `readSymbolSource` exist; same for `impact-engine.ts` (`findImpact`, `walkCalls`, `walkFileGraph`); `src/application/watcher.ts` exports `runWatchLoop` + imports `chokidar`. No `is_entry` column on `files` (live `sqlite_schema` dump confirms — C.9 unshipped)                                                                                                                                                                                        |
+| **§ 5 (b) row**               | "Sharpens every shipped recipe (untested-and-dead currently false-positives Next.js page.tsx)"                                                                                                                                                                                                             | Sharpens **two** already-shipped recipes that ask "is this live?" (`untested-and-dead`, `unimported-exports`). Foundation for one hypothetical future recipe (`dead-files-by-reachability`, c9 plan Slice 2). Recipes asking other questions (boundary, hotspot, complexity, calls, marker, CSS) don't inherit C.9's false-positive class because they don't query reachability                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Reviewed every shipped recipe in `templates/recipes/*.sql`; only `untested-and-dead` and `unimported-exports` predicate on "is symbol/file live"                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| **§ 4 intro**                 | "Codemap is structurally unique (only SQL-based code index in the market); there's no peer tool to clone"                                                                                                                                                                                                  | Codemap occupies a **specific niche** in the SQLite-backed-code-index cohort. Peer tools exist; none share all three differentiation axes (predicate-as-API + pure structural + JS/TS/CSS-deep extraction) simultaneously. Updated to align with header positioning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Header (line 9) acknowledges peer tools `srclight`, `Sverklo`, `ctxpp`, `KotaDB`, `codemogger`, `@squirrelsoft/code-index`, `QuickAST`; § 4 first sentence contradicted that without justification                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| **§ 5 (d) / § 2.5 / § 6 Q3**  | **Three revisions across three grilling turns** — v1: "thin shim wrapping show/impact engines; Very High agent UX; ship before (b)" → v2: "orthogonal to (b); ship between § 1.9 and § 1.6" → v2.5: "dropped from ship sequence; deferred until concrete consumer" → **v3: restored with corrected shape** | **v3 final:** (d) is a **diagnostic-push LSP server + paired VSCode extension**, not a request-handler shim. v2's rejection of the request-handler shape was correct (tsserver dominates `definition`/`references`/`hover types`; agents use MCP not LSP). v2.5's outright drop was **incomplete** — it conflated "LSP shim wrapping engines for go-to-def" (correctly rejected) with "LSP server pushing recipes-as-`Diagnostic[]`" (a different shape, high-value). Corrected shape: each `{file_path, line, message}`-shaped recipe → `Diagnostic[]` source (squigglies); hover provider over `symbols.signature` + `doc_comment` + `complexity` + caller-count; code lens for fan-in / complexity / coverage; code actions hooked to `recipe.actions` template; custom `codemap/analysisComplete` notification for paired VSCode extension. **Moat-A discipline:** every diagnostic must be the `--format lsp-diagnostic` rendering of a bundled recipe (reviewer test: "is this also queryable via `query --recipe X`?"). XL effort; ships last after (b) C.9 so entry-point awareness sharpens diagnostic precision | Shape locked-in: handlers implemented are `initialize` / `did_open` / `did_change` / `did_save` / `diagnostic` (LSP 3.17 pull) / `code_action` / `code_lens` / `hover` + custom `codemap/analysisComplete` notification. Handlers **NOT** implemented: `definition`, `references`, `documentSymbol`, `workspace/symbol` — explicitly skipped (tsserver covers them). Paired VSCode extension over `vscode-languageclient/node` stdio: tree views, status bar fed by custom notification, auto-download binary, settings UI for issue toggles + git ref. Server + extension is the unit, not either alone. Diagnostic codes pushed = recipe IDs (one-to-one with `--recipes-json`) |
 
 **Process lesson** (also in [`.agents/lessons.md`](../../.agents/lessons.md)): every prescriptive research note should pin every concrete claim to a file path / `codemap query` / `rg` invocation a reviewer can re-run, and ideally cross-check against a peer model or self-audit before recommending a ship sequence. The triangulation step on this doc caught all three errors before they propagated into a plan PR.
diff --git a/docs/roadmap.md b/docs/roadmap.md
index 6108463..7192741 100644
--- a/docs/roadmap.md
+++ b/docs/roadmap.md
@@ -37,26 +37,29 @@ Soft constraints — describe shipped reality. Decided-but-unshipped flips live
 
 - **Full-text search default-on** — opt-in FTS5 ships per the `--with-fts` CLI flag / `fts5: true` config field (default OFF; populates `source_fts` virtual table at index time). Default-on revisits a v2 size-tax measurement.
 - **No LSP engine** — no rename / go-to-definition / hover types. Read-side LSP-adjacent primitives (`show` / `snippet` / `impact`) ship as CLI / MCP / HTTP verbs (see [README § CLI](../README.md#cli)). LSP **diagnostic-push** server (recipes-as-`Diagnostic[]`) is a separate roadmap item tracked at [`plans/lsp-diagnostic-push.md`](./plans/lsp-diagnostic-push.md).
-- **No opinionated rule engine / fix engine / severity levels / suppression comments** — verdict-shaped lints (`knip`, `jscpd`, `eslint`) are a different product class. Predicate-as-API recipes (`untested-and-dead`, `worst-covered-exports`, `visibility-tags`, `barrel-files`, `deprecated-symbols`, …) are in scope and shipping; they're upstream of [Moat A](#moats-load-bearing).
+- **No opinionated rule engine / fix engine / severity levels** — verdict-shaped lints (`knip`, `jscpd`, `eslint`) are a different product class. Predicate-as-API recipes (`untested-and-dead`, `worst-covered-exports`, `visibility-tags`, `barrel-files`, `deprecated-symbols`, …) are in scope and shipping; they're upstream of [Moat A](#moats-load-bearing). **Suppression comments** ship as opt-in substrate (`// codemap-ignore-{next-line,file} <recipe-id>` → `suppressions` table; recipes JOIN to honor) — no severity, no suppression-by-default, no universal-honor; consumer-chosen, not policy.
 - **No renderer runtime** — skyline / ASCII art / animated diagrams; the index emits structured rows. Shape-only output formatters (`--format mermaid` shipped; `--format sarif` / `annotations` for CI; D2 / Graphviz on demand) are in scope.
 - **No daemon for one-shot CLI** — sub-100ms cold-start floor preserved for `query` / `show` / `snippet` / etc.; they spawn no watcher. The inherently long-running modes default-ON since 2026-05: `mcp` / `serve` boot the chokidar watcher in-process so every tool reads a live index. Pass `--no-watch` or set `CODEMAP_WATCH=0` to opt out for ephemeral / fire-and-forget invocations. Standalone `codemap watch` decouples the watcher from a transport.
 - **Embedded intent classification** beyond the thin keyword classifier in `codemap context --for "<intent>"` — deeper routing belongs in the agent host (Cursor / Claude Code / MCP client).
 - **No LLM in the box** — embedded intent classification, semantic search over symbol names, embedding-driven recipe routing — the agent host owns this. We supply structure; they supply meaning.
 - **No fix engine** — we **read** structure. Mutating code is a different product class (codemod tools own this). Per-row `actions` hints are enough — agents execute. Adjacent to Moat A.
-- **No runtime tracing** — V8 traces / production beacons / live execution telemetry are a different product class (live process data, not static analysis). Static coverage ingestion (`codemap ingest-coverage`) is the closest static-side adjacent capability.
+- **No runtime tracing** — production beacons / live execution telemetry are a different product class (live process data, not static analysis). Post-mortem coverage ingestion (`codemap ingest-coverage` reading Istanbul / LCOV / V8 protocol dumps from `NODE_V8_COVERAGE=...`) is the static-side adjacent capability — local-only, no SaaS aggregation.
 - **No JS execution at index time** — config files via `import()` is the only exception; recipe SQL is parsed but never `eval`'d. Plugin layer (tracked at [`plans/c9-plugin-layer.md`](./plans/c9-plugin-layer.md)) must respect this — plugins describe rules in static config, not by running arbitrary code. _Safety floor — protects supply-chain attack surface._
 - **No telemetry upload** — codemap never sends usage data anywhere. Local recipe-recency tracking is opt-out and stays in `.codemap/index.db`. _Floor exists to resist accumulation pressure._
+- **No remote-repo cloning** — `codemap github.com/x/y` (clone-and-index a remote URL) is demoware, not a real workflow; the user's local checkout is always the source of truth. Indexing another tree is `--root <path>` / `CODEMAP_ROOT`, never a network fetch. _Rejected in PR #23._
 
 ---
 
 ## Backlog
 
 - [ ] **Local recipe-recency tracking** — new `recipe_recency(recipe_id PK, last_run_at, run_count)` table; reconciler at MCP/HTTP request boundary; rolling 90-day retention; opt-out via `.codemap/config.ts` `recipe_recency: false`. Surfaces in `--recipes-json` so agents rank recently-used recipes first. Local-only — no upload primitive (resists future telemetry-creep PRs). Effort: M.
-- [ ] **Advisory unused-type-members recipe** — `type_members` × `imports.specifiers` (SQLite JSON1) join. Output is review-candidate list, NOT safe-to-delete; bundled `.md` warns about indirect-usage false-positive classes codemap doesn't track (indexed access `T['field']`, `keyof T`, type spreads, mapped types). Re-evaluate the overlap with the now-shipped `rename-preview` recipe before picking up. Effort: S.
 - [ ] **`history` table** (deferred — revisit-triggered) — temporal queries: "when did symbol X get `@deprecated`?", "coverage trend over last 50 commits", "files that became dead this week". `audit --base <ref>` covers the most-common temporal question (PR-scoped diff) without schema growth, so the table earns its place only when bigger questions emerge. Two shapes (per-commit snapshots ~N × DB size; append-only event log heavier CTE walks); both pay an N-reindexes backfill cost (~30s per reindex). **Revisit triggers:** two consumers ship `jq`-based "audit-runs-over-time" workflows, OR `query_baselines` evolution becomes a recurring agent need.
 - [ ] **`codemap audit` verdict + thresholds** (v1.x) — `verdict: "pass" | "warn" | "fail"` driven by an `audit.deltas[<key>].{added_max, action}` field on the config object (`.codemap/config.{ts,js,json}`). Triggers: two consumers ship `jq`-based threshold scripts with similar shapes, OR one consumer asks with a concrete config sketch. Until then, raw deltas + consumer-side `jq` is the CI exit-code idiom. **Likely accelerant:** the Marketplace Action (next item) shipping is the most plausible path to firing the trigger — once `- uses: stainless-code/codemap@v1` is the dominant CI path, real `jq` threshold scripts will surface.
 - [ ] **GitHub Marketplace Action — `stainless-code/codemap@v1`** — composite action wrapping `codemap audit --base ${{ github.base_ref }} --ci` (default) + auto-detect package manager (via [`package-manager-detector`](https://github.com/antfu-collective/package-manager-detector)) + opt-in PR-comment writer. Most primitives already shipped (PR #43 SARIF/annotations on `query`, PR #26 `--changed-since`/`--group-by`/`--summary`, PR #30 baselines, PR #52 `audit --base <ref>`, PR #72 boundary-violations). **Two genuine new CLI surfaces** ship alongside: `--format sarif` on `audit` (today only emits `--json`) and the `--ci` aggregate flag on `query` + `audit` (alias for `--format sarif` + non-zero exit + quiet). Action version stream is independent of CLI version (CLI at `0.4.0`; Action publishes at its own `v1.0.0`). Distribution multiplier: Marketplace is the dominant discovery surface for this tool cohort and codemap is currently absent from it. Plan: [`plans/github-marketplace-action.md`](./plans/github-marketplace-action.md). Effort: M.
-- [ ] **Repo-structure conversion (codemap itself: flat → monorepo)** — tracked decision, not a backlog item to ship. Default bias: stay flat until a trigger fires (C.9 community plugins ship as separate packages, OR a user asks for `codemap-core` library export, OR a second distro emerges). Full analysis + three options + reference layouts (fallow / oxc / knip / biome / vitest) + revisit triggers in [`plans/lsp-diagnostic-push.md § Repo-structure tradeoffs`](./plans/lsp-diagnostic-push.md#repo-structure-tradeoffs-canonical-home-for-the-monorepo-vs-flat-decision). Don't convert preemptively.
+- [ ] **`codemap apply <recipe-id>`** — substrate-shaped fix engine: apply any diff hunks your SQL describes, with conflict detection (re-parse, verify `before_pattern` still matches at `line_start`). Reuses the existing `--format diff-json` formatter (which already emits `{file_path, line_start, before_pattern, after_pattern}` rows from any recipe — see `rename-preview.sql` for an exemplar). **Substrate, not verdict:** the consumer's recipe SQL defines the transformation; codemap is the executor. Reviewer test (Moat A): "is this also expressible as `query --recipe X --format diff-json`?" — yes, because the recipe IS the SQL. Effort: ~1 week (M). **Needs a plan PR before impl** — design questions: dry-run mode, multi-hunk transactional apply, conflict-resolution UX.
+- [ ] **AST-hash duplication** — `symbols.body_hash` column (normalized AST hash via oxc, computed at parse time — Rust-native, fast) + bundled `duplicates.sql` recipe joining on `body_hash` (`SELECT * FROM symbols GROUP BY body_hash HAVING COUNT(*) > 1`). **Different shape from token-level suffix-array dupes** (catches structurally-identical functions, not copy-paste with renamed variables). Substrate addition — consumer writes the JOIN that decides "this is a problem"; no severity, no suppression-by-default. Effort: ~2 weeks (M). **Needs a plan PR before impl** — design questions: which oxc visitor scope (function bodies only? expressions? include comments?), what counts as "structurally identical" (rename-aware? whitespace-tolerant?), schema delta.
+- [ ] **Falsifiable benchmark CI** — codemap vs `find` + `grep` + `Read`-loop agent-discovery on named fixtures (zod, fastify, vue-core, next.js). Numbers land in [`docs/benchmark.md`](./benchmark.md) and ~3 surface in `MARKETPLACE.md`. Replaces the unfalsifiable "sub-millisecond" claim with named-fixture comparisons that any consumer can re-run. Effort: M.
+- [ ] **Repo-structure conversion (codemap itself: flat → monorepo)** — tracked decision, not a backlog item to ship. Default bias: stay flat until a trigger fires (C.9 community plugins ship as separate packages, OR a user asks for `codemap-core` library export, OR a second distro emerges). Full analysis + three options + reference layouts (oxc / knip / biome / vitest) + revisit triggers in [`plans/lsp-diagnostic-push.md § Repo-structure tradeoffs`](./plans/lsp-diagnostic-push.md#repo-structure-tradeoffs-canonical-home-for-the-monorepo-vs-flat-decision). Don't convert preemptively.
 - [ ] **Monorepo / workspace awareness** — discover workspaces from `pnpm-workspace.yaml` / `package.json` and index per-workspace dependency graphs (separate from the codemap-itself repo-structure decision above; this is about indexing user repos)
 - [ ] **Cross-agent handoff artifact** — _speculative_; layered prefix/delta JSON written on session-stop, read on session-start. Complementary to indexing rather than core to it; revisit if user demand emerges
 - [ ] **Adapter scaffolding** — `codemap create-adapter --name [name]` generates adapter + test + fixture boilerplate; blocked on community adapter registration API (could land with manual registration)
diff --git a/docs/why-codemap.md b/docs/why-codemap.md
index 93c18d5..602a33f 100644
--- a/docs/why-codemap.md
+++ b/docs/why-codemap.md
@@ -109,18 +109,18 @@ Some queries are trivial with the index but impractical (or slow) with tradition
 
 Other "AI-friendly code intelligence" tools occupy different points in the design space. Each one is solving a different problem:
 
-| Axis              | **Codemap**                           | [fallow](https://github.com/fallow-rs/fallow)                 | [Aider RepoMap](https://aider.chat) | LSP servers                 |
-| ----------------- | ------------------------------------- | ------------------------------------------------------------- | ----------------------------------- | --------------------------- |
-| Primary thesis    | Query structure with **SQL**          | Detect dead code / dupes / complexity                         | Summarize repo into a context blob  | Per-edit semantic helpers   |
-| Output shape      | Result rows from a SQL query          | SARIF / JSON findings, fix `actions`                          | Markdown / token-budgeted text      | LSP messages over stdio     |
-| Decides relevance | The agent (via SQL)                   | The tool (via static rules)                                   | The tool (PageRank-style)           | The editor                  |
-| Scope             | Structural facts (definitions, edges) | Static analysis verdicts                                      | Whole-repo summary                  | One file at a time          |
-| Storage           | Local SQLite (`.codemap/index.db`)    | In-process; emits findings                                    | In-prompt context                   | In-process index            |
-| Token cost        | Per-query; tiny result rows           | Per-run; finding lists                                        | Upfront; bounded by token budget    | None (editor-side)          |
-| Best for          | Targeted "where / what / who" lookups | "Did this PR introduce dead code / dupes / complexity drift?" | First-touch context priming         | Editor-time refactoring     |
-| Worst for         | Whole-file semantic understanding     | Granular structural lookups (different shape)                 | Targeted line-range reads           | Cross-cutting graph queries |
-
-**Why this matters:** Codemap deliberately **doesn't try to be smart**. Other tools predict what context an agent will need; Codemap lets the agent decide and just makes each decision cheap. The same agent can use Codemap **and** fallow **and** an LSP — they don't compete for the same slot.
+| Axis              | **Codemap**                           | Static-analysis tools (knip / ts-prune / jscpd / ESLint) | [Aider RepoMap](https://aider.chat) | LSP servers                 |
+| ----------------- | ------------------------------------- | -------------------------------------------------------- | ----------------------------------- | --------------------------- |
+| Primary thesis    | Query structure with **SQL**          | Detect dead code / dupes / complexity                    | Summarize repo into a context blob  | Per-edit semantic helpers   |
+| Output shape      | Result rows from a SQL query          | Findings with severity / fix suggestions                 | Markdown / token-budgeted text      | LSP messages over stdio     |
+| Decides relevance | The agent (via SQL)                   | The tool (via static rules)                              | The tool (PageRank-style)           | The editor                  |
+| Scope             | Structural facts (definitions, edges) | Static-analysis verdicts                                 | Whole-repo summary                  | One file at a time          |
+| Storage           | Local SQLite (`.codemap/index.db`)    | In-process; emits findings                               | In-prompt context                   | In-process index            |
+| Token cost        | Per-query; tiny result rows           | Per-run; finding lists                                   | Upfront; bounded by token budget    | None (editor-side)          |
+| Best for          | Targeted "where / what / who" lookups | "Did this PR introduce dead code / dupes / complexity?"  | First-touch context priming         | Editor-time refactoring     |
+| Worst for         | Whole-file semantic understanding     | Granular structural lookups (different shape)            | Targeted line-range reads           | Cross-cutting graph queries |
+
+**Why this matters:** Codemap deliberately **doesn't try to be smart**. Other tools predict what context an agent will need; Codemap lets the agent decide and just makes each decision cheap. The same agent can use Codemap **and** a verdict-shaped linter **and** an LSP — they don't compete for the same slot.
 
 For more on what Codemap deliberately does **not** do, see [When to reach for something else](#when-to-reach-for-something-else) above and [docs/roadmap.md § Non-goals](./roadmap.md#non-goals-v1).
 
diff --git a/fixtures/golden/minimal/unused-type-members.json b/fixtures/golden/minimal/unused-type-members.json
new file mode 100644
index 0000000..5c573f0
--- /dev/null
+++ b/fixtures/golden/minimal/unused-type-members.json
@@ -0,0 +1,18 @@
+[
+  {
+    "owner_type": "Transport",
+    "member": "handshakeMs",
+    "member_type": "number",
+    "is_optional": 0,
+    "is_readonly": 1,
+    "file_path": "src/api/client.ts"
+  },
+  {
+    "owner_type": "Transport",
+    "member": "socketUrl",
+    "member_type": "string",
+    "is_optional": 0,
+    "is_readonly": 1,
+    "file_path": "src/api/client.ts"
+  }
+]
diff --git a/fixtures/golden/scenarios.json b/fixtures/golden/scenarios.json
index c152392..4be6b97 100644
--- a/fixtures/golden/scenarios.json
+++ b/fixtures/golden/scenarios.json
@@ -133,6 +133,11 @@
       "id": "worst-covered-exports",
       "prompt": "Top 20 worst-covered exported functions",
       "recipe": "worst-covered-exports"
+    },
+    {
+      "id": "unused-type-members",
+      "prompt": "Members of exported types whose owning type has no detectable importer (advisory; field-level enumeration of `unimported-exports`)",
+      "recipe": "unused-type-members"
     }
   ]
 }
diff --git a/src/adapters/builtin.ts b/src/adapters/builtin.ts
index 3f0d743..204f5ca 100644
--- a/src/adapters/builtin.ts
+++ b/src/adapters/builtin.ts
@@ -1,5 +1,5 @@
 import { extractCssData } from "../css-parser";
-import { extractMarkers } from "../markers";
+import { extractMarkers, extractSuppressions } from "../markers";
 import { extractFileData } from "../parser";
 import type { LanguageAdapter, ParsedFilePayload, ParseContext } from "./types";
 
@@ -23,6 +23,7 @@ function parseTsJs(ctx: ParseContext): ParsedFilePayload {
     exports: data.exports,
     components: data.components,
     markers: data.markers,
+    suppressions: extractSuppressions(ctx.source, ctx.relPath),
     typeMembers: data.typeMembers,
     calls: data.calls,
   };
@@ -36,6 +37,7 @@ function parseCss(ctx: ParseContext): ParsedFilePayload {
     cssClasses: cssData.classes,
     cssKeyframes: cssData.keyframes,
     markers: cssData.markers,
+    suppressions: extractSuppressions(ctx.source, ctx.relPath),
     cssImportSources: cssData.importSources,
   };
 }
@@ -44,6 +46,7 @@ function parseText(ctx: ParseContext): ParsedFilePayload {
   return {
     category: "text",
     markers: extractMarkers(ctx.source, ctx.relPath),
+    suppressions: extractSuppressions(ctx.source, ctx.relPath),
   };
 }
 
diff --git a/src/adapters/types.ts b/src/adapters/types.ts
index da888b0..8103ac5 100644
--- a/src/adapters/types.ts
+++ b/src/adapters/types.ts
@@ -27,6 +27,7 @@ export type ParsedFilePayload = Pick<
   | "exports"
   | "components"
   | "markers"
+  | "suppressions"
   | "typeMembers"
   | "calls"
   | "cssVariables"
diff --git a/src/application/coverage-engine.test.ts b/src/application/coverage-engine.test.ts
index 7908dc5..186b6da 100644
--- a/src/application/coverage-engine.test.ts
+++ b/src/application/coverage-engine.test.ts
@@ -1,4 +1,8 @@
 import { describe, expect, it } from "bun:test";
+import { mkdtempSync, mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
 
 import {
   closeDb,
@@ -11,9 +15,10 @@ import { openCodemapDatabase } from "../sqlite-db";
 import {
   ingestIstanbul,
   ingestLcov,
+  ingestV8,
   upsertCoverageRows,
 } from "./coverage-engine";
-import type { IstanbulPayload } from "./coverage-engine";
+import type { IstanbulPayload, V8ScriptCoverage } from "./coverage-engine";
 
 const PROJECT_ROOT = "/repo";
 
@@ -587,4 +592,205 @@ describe("coverage-engine", () => {
       }
     });
   });
+
+  describe("ingestV8", () => {
+    function makeTempProject(source: string): { root: string; url: string } {
+      const root = mkdtempSync(join(tmpdir(), "codemap-v8-"));
+      mkdirSync(join(root, "src"), { recursive: true });
+      const absSrcPath = join(root, "src", "a.ts");
+      writeFileSync(absSrcPath, source, "utf-8");
+      return { root, url: pathToFileURL(absSrcPath).toString() };
+    }
+
+    it("maps V8 byte-offset ranges to per-line hits and aggregates per symbol", () => {
+      // 4-line source. `outer` spans lines 1–4; `inner` spans line 2 only.
+      const source = [
+        "function outer() {",
+        "  function inner() { return 1; }",
+        "  inner();",
+        "}",
+      ].join("\n");
+      const { root, url } = makeTempProject(source);
+
+      const db = setupDb();
+      try {
+        // Symbols + files use project-relative paths (matches the indexer).
+        insertFile(db, { ...indexedFile("src/a.ts"), language: "ts" });
+        insertSymbols(db, [
+          fnSym("src/a.ts", "outer", 1, 4),
+          fnSym("src/a.ts", "inner", 2, 2),
+        ]);
+
+        // Whole-file range hit twice; inner range (line 2 only) hit zero times.
+        const scripts: V8ScriptCoverage[] = [
+          {
+            scriptId: "1",
+            url,
+            functions: [
+              {
+                functionName: "outer",
+                isBlockCoverage: true,
+                ranges: [
+                  { startOffset: 0, endOffset: source.length, count: 2 },
+                  {
+                    // The byte offsets of line 2: from end of line 1's \n
+                    startOffset: source.indexOf("function inner"),
+                    endOffset: source.indexOf("}", source.indexOf("inner")),
+                    count: 0,
+                  },
+                ],
+              },
+            ],
+          },
+        ];
+
+        const result = ingestV8({
+          db,
+          projectRoot: root,
+          scripts,
+          sourcePath: join(root, ".cov"),
+        });
+        expect(result.format).toBe("v8");
+        expect(result.ingested.symbols).toBe(2);
+
+        const rows = db
+          .query(
+            "SELECT name, hit_statements, total_statements FROM coverage ORDER BY name",
+          )
+          .all() as Array<{
+          name: string;
+          hit_statements: number;
+          total_statements: number;
+        }>;
+        // Innermost-wins: inner range (count 0) overrode outer range (count 2) for line 2.
+        const inner = rows.find((r) => r.name === "inner")!;
+        const outer = rows.find((r) => r.name === "outer")!;
+        expect(inner.hit_statements).toBe(0);
+        expect(inner.total_statements).toBeGreaterThan(0);
+        expect(outer.hit_statements).toBe(outer.total_statements);
+      } finally {
+        closeDb(db);
+      }
+    });
+
+    it("skips scripts whose url isn't a file:// URL (Node internals, eval)", () => {
+      const db = setupDb();
+      try {
+        const result = ingestV8({
+          db,
+          projectRoot: "/repo",
+          sourcePath: "/cov",
+          scripts: [
+            {
+              scriptId: "1",
+              url: "node:internal/process/task_queues",
+              functions: [
+                {
+                  functionName: "x",
+                  isBlockCoverage: false,
+                  ranges: [{ startOffset: 0, endOffset: 10, count: 1 }],
+                },
+              ],
+            },
+            {
+              scriptId: "2",
+              url: "evalmachine.<anonymous>",
+              functions: [],
+            },
+          ],
+        });
+        expect(result.ingested).toEqual({ symbols: 0, files: 0 });
+      } finally {
+        closeDb(db);
+      }
+    });
+
+    it("merges duplicate URL scripts (same file ingested by multiple V8 dumps)", () => {
+      const source = "function a() { return 1; }\n";
+      const { root, url } = makeTempProject(source);
+
+      const db = setupDb();
+      try {
+        insertFile(db, { ...indexedFile("src/a.ts"), language: "ts" });
+        insertSymbols(db, [fnSym("src/a.ts", "a", 1, 1)]);
+
+        const dup: V8ScriptCoverage = {
+          scriptId: "x",
+          url,
+          functions: [
+            {
+              functionName: "a",
+              isBlockCoverage: false,
+              ranges: [{ startOffset: 0, endOffset: source.length, count: 5 }],
+            },
+          ],
+        };
+        const result = ingestV8({
+          db,
+          projectRoot: root,
+          sourcePath: join(root, ".cov"),
+          scripts: [dup, dup, dup], // 3 duplicate dumps
+        });
+        // Deduplicated by URL → ingested once.
+        expect(result.ingested.files).toBe(1);
+      } finally {
+        closeDb(db);
+      }
+    });
+
+    it("merges duplicate-URL scripts via Math.max (multi-process must not zero out another process's hit)", () => {
+      const source = "function a() { return 1; }\n";
+      const { root, url } = makeTempProject(source);
+
+      const db = setupDb();
+      try {
+        insertFile(db, { ...indexedFile("src/a.ts"), language: "ts" });
+        insertSymbols(db, [fnSym("src/a.ts", "a", 1, 1)]);
+
+        // Process A hit `a()` 7 times; process B never hit it (count 0).
+        const hot: V8ScriptCoverage = {
+          scriptId: "1",
+          url,
+          functions: [
+            {
+              functionName: "a",
+              isBlockCoverage: false,
+              ranges: [{ startOffset: 0, endOffset: source.length, count: 7 }],
+            },
+          ],
+        };
+        const cold: V8ScriptCoverage = {
+          scriptId: "2",
+          url,
+          functions: [
+            {
+              functionName: "a",
+              isBlockCoverage: false,
+              ranges: [{ startOffset: 0, endOffset: source.length, count: 0 }],
+            },
+          ],
+        };
+
+        const result = ingestV8({
+          db,
+          projectRoot: root,
+          sourcePath: join(root, ".cov"),
+          // `cold` last — would have zeroed line 1 with last-writer-wins.
+          scripts: [hot, cold],
+        });
+        expect(result.ingested.files).toBe(1);
+
+        const row = db
+          .query(
+            "SELECT hit_statements, total_statements FROM coverage WHERE name = 'a'",
+          )
+          .get() as { hit_statements: number; total_statements: number };
+        // Line 1 carries hot's count=7 → line is hit; total = total = 1.
+        expect(row.hit_statements).toBe(row.total_statements);
+        expect(row.hit_statements).toBeGreaterThan(0);
+      } finally {
+        closeDb(db);
+      }
+    });
+  });
 });
diff --git a/src/application/coverage-engine.ts b/src/application/coverage-engine.ts
index b0d89ca..a44908f 100644
--- a/src/application/coverage-engine.ts
+++ b/src/application/coverage-engine.ts
@@ -1,3 +1,6 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
 import type { CodemapDatabase } from "../db";
 import { toProjectRelative } from "./validate-engine";
 
@@ -17,7 +20,7 @@ export interface CoverageRow {
 }
 
 /** Source format detected by the CLI auto-detector. */
-export type CoverageFormat = "istanbul" | "lcov";
+export type CoverageFormat = "istanbul" | "lcov" | "v8";
 
 export interface IngestResult {
   ingested: { symbols: number; files: number };
@@ -351,3 +354,150 @@ export function ingestLcov(opts: LcovParserOpts): IngestResult {
     sourcePath,
   });
 }
+
+/* ------------------------------------------------------------------ */
+/* V8 runtime coverage parser                                          */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Subset of V8's coverage protocol shape (`NODE_V8_COVERAGE=...` per-process dump).
+ * `ranges` carry byte offsets, NOT lines; with `isBlockCoverage: true` the outer
+ * range is function-level and inner ranges are nested basic blocks.
+ */
+export interface V8FunctionCoverage {
+  functionName: string;
+  isBlockCoverage: boolean;
+  ranges: Array<{
+    startOffset: number;
+    endOffset: number;
+    count: number;
+  }>;
+}
+
+export interface V8ScriptCoverage {
+  scriptId: string;
+  url: string;
+  functions: V8FunctionCoverage[];
+}
+
+export interface V8CoveragePayload {
+  result: V8ScriptCoverage[];
+}
+
+interface V8ParserOpts {
+  db: CodemapDatabase;
+  projectRoot: string;
+  /** All `result` entries merged from every `coverage-*.json` in the dir. */
+  scripts: V8ScriptCoverage[];
+  /** Absolute path of the directory; threaded into `meta`. */
+  sourcePath: string;
+}
+
+/**
+ * Parse merged V8 ScriptCoverage entries and dispatch to {@link upsertCoverageRows}.
+ * Per-line hit counts: walk each function's ranges largest→smallest, last write
+ * wins → innermost-wins semantics matching V8's documented model.
+ */
+export function ingestV8(opts: V8ParserOpts): IngestResult {
+  const { scripts, sourcePath, ...rest } = opts;
+  const rows: CoverageRow[] = [];
+
+  // Group by URL so duplicate dumps (multi-process test run) merge before
+  // emit; otherwise upsert would inflate `total_statements`.
+  const scriptsByUrl = new Map<string, V8ScriptCoverage[]>();
+  for (const script of scripts) {
+    if (!script?.url) continue;
+    // V8 reports `node:internal/...`, `evalmachine.<anonymous>`, etc.
+    if (!script.url.startsWith("file://")) continue;
+    const list = scriptsByUrl.get(script.url) ?? [];
+    list.push(script);
+    scriptsByUrl.set(script.url, list);
+  }
+
+  for (const [url, urlScripts] of scriptsByUrl) {
+    let absPath: string;
+    try {
+      absPath = fileURLToPath(url);
+    } catch {
+      continue;
+    }
+    let source: string;
+    try {
+      source = readFileSync(absPath, "utf-8");
+    } catch {
+      // File deleted between test run and ingest; upsertCoverageRows would
+      // also surface this as `unmatched_files` if we'd let it through.
+      continue;
+    }
+
+    const lineOffsets = buildLineOffsets(source);
+    const lineHits: (number | undefined)[] = new Array(lineOffsets.length + 1);
+
+    for (const script of urlScripts) {
+      // Per-script innermost-wins, cross-script `Math.max` merge — a
+      // process that didn't hit a line must NOT zero out another's count.
+      const scriptHits: (number | undefined)[] = new Array(
+        lineOffsets.length + 1,
+      );
+      for (const fn of script.functions ?? []) {
+        const sorted = (fn.ranges ?? [])
+          .slice()
+          .sort(
+            (a, b) =>
+              b.endOffset - b.startOffset - (a.endOffset - a.startOffset),
+          );
+        for (const range of sorted) {
+          const startLine = offsetToLine(lineOffsets, range.startOffset);
+          const endLine = offsetToLine(lineOffsets, range.endOffset);
+          for (let line = startLine; line <= endLine; line++) {
+            // Innermost-wins within this script: last write is the smallest range.
+            scriptHits[line] = range.count;
+          }
+        }
+      }
+      for (let line = 1; line < scriptHits.length; line++) {
+        const hit = scriptHits[line];
+        if (hit === undefined) continue;
+        lineHits[line] = Math.max(lineHits[line] ?? 0, hit);
+      }
+    }
+
+    for (let line = 1; line < lineHits.length; line++) {
+      const hit = lineHits[line];
+      if (hit === undefined) continue;
+      rows.push({ file_path: absPath, line, hit_count: hit });
+    }
+  }
+
+  return upsertCoverageRows({
+    ...rest,
+    rows,
+    format: "v8",
+    sourcePath,
+  });
+}
+
+/**
+ * `offsets[i]` = UTF-16 code-unit position where line `i + 1` starts —
+ * matches V8's source-offset units (Chrome DevTools `Profiler.CoverageRange`
+ * spec); no UTF-8 byte conversion needed.
+ */
+function buildLineOffsets(source: string): number[] {
+  const offsets: number[] = [0];
+  for (let i = 0; i < source.length; i++) {
+    if (source.charCodeAt(i) === 10) offsets.push(i + 1);
+  }
+  return offsets;
+}
+
+/** Binary search → 1-indexed line containing `offset`. */
+function offsetToLine(lineOffsets: number[], offset: number): number {
+  let lo = 0;
+  let hi = lineOffsets.length - 1;
+  while (lo < hi) {
+    const mid = (lo + hi + 1) >>> 1;
+    if (lineOffsets[mid] <= offset) lo = mid;
+    else hi = mid - 1;
+  }
+  return lo + 1;
+}
diff --git a/src/application/index-engine.ts b/src/application/index-engine.ts
index bd21246..873ae36 100644
--- a/src/application/index-engine.ts
+++ b/src/application/index-engine.ts
@@ -22,6 +22,7 @@ import {
   insertComponents,
   insertDependencies,
   insertMarkers,
+  insertSuppressions,
   insertCssVariables,
   insertCssClasses,
   insertCssKeyframes,
@@ -36,7 +37,7 @@ import type { CodemapDatabase, FileRow } from "../db";
 import { filterRowsByChangedFiles } from "../git-changed";
 import { globSync } from "../glob-sync";
 import { hashContent } from "../hash";
-import { extractMarkers } from "../markers";
+import { extractMarkers, extractSuppressions } from "../markers";
 import type { ParsedFile } from "../parse-worker";
 import { extractFileData } from "../parser";
 import { resolveImports } from "../resolver";
@@ -247,6 +248,8 @@ function insertParsedResults(
           }
           if (parsed.calls?.length) insertCalls(db, parsed.calls);
         }
+        if (parsed.suppressions?.length)
+          insertSuppressions(db, parsed.suppressions);
       } catch (err) {
         console.error(
           `  Parse error in ${parsed.relPath}: ${err instanceof Error ? err.message : err}`,
@@ -419,6 +422,9 @@ export async function indexFiles(
               insertTypeMembers(db, data.typeMembers);
             if (data.calls.length) insertCalls(db, data.calls);
           }
+          // Category-agnostic: one regex pass over raw source, no AST needed.
+          const suppressions = extractSuppressions(source, relPath);
+          if (suppressions.length) insertSuppressions(db, suppressions);
         } catch (err) {
           console.error(
             `  Parse error in ${relPath}: ${err instanceof Error ? err.message : err}`,
diff --git a/src/cli/aliases.test.ts b/src/cli/aliases.test.ts
new file mode 100644
index 0000000..c41e71c
--- /dev/null
+++ b/src/cli/aliases.test.ts
@@ -0,0 +1,85 @@
+import { describe, expect, it } from "bun:test";
+
+import { listQueryRecipeCatalog } from "../application/query-recipes";
+import {
+  isOutcomeAlias,
+  OUTCOME_ALIASES,
+  resolveOutcomeAlias,
+} from "./aliases";
+
+describe("OUTCOME_ALIASES", () => {
+  it("caps at 5 aliases (avoids alias-sprawl per roadmap)", () => {
+    expect(Object.keys(OUTCOME_ALIASES)).toHaveLength(5);
+  });
+
+  it("every aliased recipe id exists in the bundled catalog", () => {
+    const catalog = new Set(listQueryRecipeCatalog().map((r) => r.id));
+    for (const recipeId of Object.values(OUTCOME_ALIASES)) {
+      expect(catalog.has(recipeId)).toBe(true);
+    }
+  });
+});
+
+describe("isOutcomeAlias", () => {
+  it("returns true for each declared alias", () => {
+    for (const alias of Object.keys(OUTCOME_ALIASES)) {
+      expect(isOutcomeAlias(alias)).toBe(true);
+    }
+  });
+
+  it("returns false for the wrapped recipe ids and other tokens", () => {
+    expect(isOutcomeAlias("untested-and-dead")).toBe(false);
+    expect(isOutcomeAlias("query")).toBe(false);
+    expect(isOutcomeAlias("audit")).toBe(false);
+    expect(isOutcomeAlias("")).toBe(false);
+  });
+});
+
+describe("resolveOutcomeAlias", () => {
+  it("rewrites a bare alias to query --recipe <id>", () => {
+    expect(resolveOutcomeAlias(["dead-code"])).toEqual([
+      "query",
+      "--recipe",
+      "untested-and-dead",
+    ]);
+    expect(resolveOutcomeAlias(["coverage-gaps"])).toEqual([
+      "query",
+      "--recipe",
+      "worst-covered-exports",
+    ]);
+  });
+
+  it("preserves trailing args verbatim (flags pass through)", () => {
+    expect(
+      resolveOutcomeAlias(["deprecated", "--json", "--format", "sarif"]),
+    ).toEqual([
+      "query",
+      "--recipe",
+      "deprecated-symbols",
+      "--json",
+      "--format",
+      "sarif",
+    ]);
+    expect(
+      resolveOutcomeAlias([
+        "boundaries",
+        "--ci",
+        "--changed-since",
+        "origin/main",
+      ]),
+    ).toEqual([
+      "query",
+      "--recipe",
+      "boundary-violations",
+      "--ci",
+      "--changed-since",
+      "origin/main",
+    ]);
+  });
+
+  it("returns null for non-aliases (caller falls through to existing dispatch)", () => {
+    expect(resolveOutcomeAlias(["query", "SELECT", "1"])).toBeNull();
+    expect(resolveOutcomeAlias(["audit", "--json"])).toBeNull();
+    expect(resolveOutcomeAlias([])).toBeNull();
+  });
+});
diff --git a/src/cli/aliases.ts b/src/cli/aliases.ts
new file mode 100644
index 0000000..11d3361
--- /dev/null
+++ b/src/cli/aliases.ts
@@ -0,0 +1,39 @@
+/**
+ * Outcome-shaped CLI aliases — thin wrappers over `query --recipe <id>`.
+ * Capped at 5 to avoid alias-sprawl; promote a sixth only when the recipe
+ * becomes a headline outcome ([roadmap.md](../../docs/roadmap.md)).
+ */
+export const OUTCOME_ALIASES = Object.freeze({
+  "dead-code": "untested-and-dead",
+  deprecated: "deprecated-symbols",
+  boundaries: "boundary-violations",
+  hotspots: "fan-in",
+  "coverage-gaps": "worst-covered-exports",
+} as const);
+
+export type OutcomeAlias = keyof typeof OUTCOME_ALIASES;
+
+export function isOutcomeAlias(token: string): token is OutcomeAlias {
+  return Object.hasOwn(OUTCOME_ALIASES, token);
+}
+
+/** Returns `null` (not `undefined`) so callers `if (rewritten)` falls through cleanly to the existing dispatch. */
+export function resolveOutcomeAlias(rest: string[]): string[] | null {
+  const head = rest[0];
+  if (!head || !isOutcomeAlias(head)) return null;
+  const recipeId = OUTCOME_ALIASES[head];
+  return ["query", "--recipe", recipeId, ...rest.slice(1)];
+}
+
+export function printOutcomeAliasHelp(alias: OutcomeAlias): void {
+  const recipeId = OUTCOME_ALIASES[alias];
+  console.log(`Usage: codemap ${alias} [query flags...]
+
+Alias for \`codemap query --recipe ${recipeId}\` — every flag accepted by
+\`codemap query\` passes through (--json, --format sarif|annotations|mermaid|diff|diff-json,
+--ci, --summary, --changed-since <ref>, --group-by owner|directory|package,
+--params key=value, --save-baseline[=name], --baseline[=name]).
+
+Run \`codemap query --help\` for the full flag reference, or
+\`codemap query --print-sql ${recipeId}\` to see the recipe SQL.`);
+}
diff --git a/src/cli/bootstrap.ts b/src/cli/bootstrap.ts
index 5621d6b..52890fb 100644
--- a/src/cli/bootstrap.ts
+++ b/src/cli/bootstrap.ts
@@ -16,6 +16,13 @@ Query:
   codemap query [--json] "<SQL>"
   codemap query [--json] --recipe <id>
 
+Outcome aliases (thin wrappers around \`query --recipe <id>\`; pass-through flags):
+  codemap dead-code         # query --recipe untested-and-dead
+  codemap deprecated        # query --recipe deprecated-symbols
+  codemap boundaries        # query --recipe boundary-violations
+  codemap hotspots          # query --recipe fan-in
+  codemap coverage-gaps     # query --recipe worst-covered-exports
+
 Validate (compare on-disk SHA-256 to indexed hash):
   codemap validate [--json] [paths...]
 
diff --git a/src/cli/cmd-ingest-coverage.test.ts b/src/cli/cmd-ingest-coverage.test.ts
index 898f249..6bd3f1d 100644
--- a/src/cli/cmd-ingest-coverage.test.ts
+++ b/src/cli/cmd-ingest-coverage.test.ts
@@ -16,7 +16,7 @@ describe("parseIngestCoverageRest", () => {
     });
   });
 
-  it("parses a single path with default --json=false", () => {
+  it("parses a single path with default --json=false and --runtime=false", () => {
     expect(
       parseIngestCoverageRest([
         "ingest-coverage",
@@ -26,13 +26,31 @@ describe("parseIngestCoverageRest", () => {
       kind: "run",
       path: "coverage/coverage-final.json",
       json: false,
+      runtime: false,
     });
   });
 
   it("parses --json", () => {
     expect(
       parseIngestCoverageRest(["ingest-coverage", "coverage", "--json"]),
-    ).toEqual({ kind: "run", path: "coverage", json: true });
+    ).toEqual({ kind: "run", path: "coverage", json: true, runtime: false });
+  });
+
+  it("parses --runtime (V8 protocol directory mode)", () => {
+    expect(
+      parseIngestCoverageRest(["ingest-coverage", ".cov", "--runtime"]),
+    ).toEqual({ kind: "run", path: ".cov", json: false, runtime: true });
+  });
+
+  it("parses --runtime + --json composed", () => {
+    expect(
+      parseIngestCoverageRest([
+        "ingest-coverage",
+        ".cov",
+        "--runtime",
+        "--json",
+      ]),
+    ).toEqual({ kind: "run", path: ".cov", json: true, runtime: true });
   });
 
   it("rejects missing path", () => {
diff --git a/src/cli/cmd-ingest-coverage.ts b/src/cli/cmd-ingest-coverage.ts
index 1e7c068..3853f0a 100644
--- a/src/cli/cmd-ingest-coverage.ts
+++ b/src/cli/cmd-ingest-coverage.ts
@@ -1,12 +1,18 @@
-import { existsSync, statSync } from "node:fs";
+import { existsSync, readdirSync, statSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { isAbsolute, join, resolve } from "node:path";
 
-import { ingestIstanbul, ingestLcov } from "../application/coverage-engine";
+import {
+  ingestIstanbul,
+  ingestLcov,
+  ingestV8,
+} from "../application/coverage-engine";
 import type {
   CoverageFormat,
   IngestResult,
   IstanbulPayload,
+  V8CoveragePayload,
+  V8ScriptCoverage,
 } from "../application/coverage-engine";
 import { closeDb, openDb } from "../db";
 import { bootstrapCodemap } from "./bootstrap-codemap";
@@ -18,34 +24,41 @@ interface IngestCoverageOpts {
   /** Resolved absolute path to coverage-final.json, lcov.info, or a directory. */
   path: string;
   json: boolean;
+  /** Treat <path> as a NODE_V8_COVERAGE directory (one or more `coverage-*.json` files). */
+  runtime: boolean;
 }
 
 const ISTANBUL_FILENAME = "coverage-final.json";
 const LCOV_FILENAME = "lcov.info";
 
 export function printIngestCoverageCmdHelp(): void {
-  console.log(`Usage: codemap ingest-coverage <path> [--json]
+  console.log(`Usage: codemap ingest-coverage <path> [--runtime] [--json]
 
-Ingest a static coverage artifact into the index so structural queries
-can compose coverage filters in pure SQL. No test runner is invoked —
-codemap reads what \`bun test\`, \`vitest\`, \`jest\`, \`c8\`, \`nyc\`
-already produce.
+Ingest a coverage artifact into the index so structural queries can
+compose coverage filters in pure SQL. No test runner is invoked —
+codemap reads what \`bun test\`, \`vitest\`, \`jest\`, \`c8\`, \`nyc\`,
+or Node's V8 protocol already produce.
 
 Args:
   <path>          Path to one of:
                     - coverage-final.json (Istanbul)
                     - lcov.info (LCOV; e.g. \`bun test --coverage\`)
                     - a directory containing exactly one of the above
+                    - a NODE_V8_COVERAGE directory (with --runtime)
 
 Format auto-detected from filename / extension. Errors if a directory
 holds both \`coverage-final.json\` and \`lcov.info\` (no precedence guess).
 
 Flags:
+  --runtime       Treat <path> as a NODE_V8_COVERAGE directory and merge
+                  every \`coverage-*.json\` inside it. Skip files whose
+                  \`url\` isn't \`file://\` (Node internals, eval). Local
+                  use only — no SaaS aggregation.
   --json          Emit the result envelope on stdout. Default: human text.
   --help, -h      Show this help.
 
 Output (JSON):
-  { "format": "istanbul"|"lcov",
+  { "format": "istanbul"|"lcov"|"v8",
     "ingested": { "symbols": N, "files": M },
     "skipped": { "unmatched_files": K, "statements_no_symbol": S },
     "pruned_orphans": O }
@@ -54,6 +67,8 @@ Examples:
   codemap ingest-coverage coverage/coverage-final.json
   codemap ingest-coverage coverage/lcov.info
   codemap ingest-coverage coverage --json
+  NODE_V8_COVERAGE=.cov bun test
+  codemap ingest-coverage .cov --runtime --json
 `);
 }
 
@@ -62,12 +77,13 @@ export function parseIngestCoverageRest(
 ):
   | { kind: "help" }
   | { kind: "error"; message: string }
-  | { kind: "run"; path: string; json: boolean } {
+  | { kind: "run"; path: string; json: boolean; runtime: boolean } {
   if (rest[0] !== "ingest-coverage") {
     throw new Error("parseIngestCoverageRest: expected ingest-coverage");
   }
   let path: string | undefined;
   let json = false;
+  let runtime = false;
   for (let i = 1; i < rest.length; i++) {
     const a = rest[i]!;
     if (a === "--help" || a === "-h") return { kind: "help" };
@@ -75,6 +91,10 @@ export function parseIngestCoverageRest(
       json = true;
       continue;
     }
+    if (a === "--runtime") {
+      runtime = true;
+      continue;
+    }
     if (a.startsWith("-")) {
       return {
         kind: "error",
@@ -95,7 +115,7 @@ export function parseIngestCoverageRest(
       message: `codemap ingest-coverage: missing <path>. Run \`codemap ingest-coverage --help\` for usage.`,
     };
   }
-  return { kind: "run", path, json };
+  return { kind: "run", path, json, runtime };
 }
 
 /**
@@ -136,6 +156,34 @@ function resolveArtifact(
   );
 }
 
+/** Filters to NODE_V8_COVERAGE's `coverage-<pid>-<ts>-<seq>.json` shape so a wrong dir errors loudly instead of producing a zero-row "successful" ingest. */
+const V8_FILENAME_RE = /^coverage-.*\.json$/;
+
+function resolveV8Directory(
+  inputPath: string,
+  cwd: string,
+): { absDir: string; jsonFiles: string[] } {
+  const abs = isAbsolute(inputPath) ? inputPath : resolve(cwd, inputPath);
+  if (!existsSync(abs)) {
+    throw new Error(`codemap ingest-coverage: path not found: ${abs}`);
+  }
+  const stat = statSync(abs);
+  if (!stat.isDirectory()) {
+    throw new Error(
+      `codemap ingest-coverage --runtime: expected a directory (NODE_V8_COVERAGE-style), got file ${abs}`,
+    );
+  }
+  const jsonFiles = readdirSync(abs)
+    .filter((f) => V8_FILENAME_RE.test(f))
+    .map((f) => join(abs, f));
+  if (jsonFiles.length === 0) {
+    throw new Error(
+      `codemap ingest-coverage --runtime: directory ${abs} contains no coverage-*.json files. NODE_V8_COVERAGE writes coverage-<pid>-<ts>-<seq>.json — point --runtime at the directory the test runner wrote to.`,
+    );
+  }
+  return { absDir: abs, jsonFiles };
+}
+
 /**
  * Read a JSON file via the canonical Node-vs-Bun split — Bun.file().json()
  * uses Bun's native parser (materially faster on multi-MB Istanbul payloads);
@@ -162,27 +210,50 @@ export async function runIngestCoverageCmd(
 ): Promise<void> {
   try {
     await bootstrapCodemap(opts);
-    const { format, absPath } = resolveArtifact(opts.path, opts.root);
 
     let result: IngestResult;
+    let displayPath: string;
     const db = openDb();
     try {
-      if (format === "istanbul") {
-        const payload = (await readJsonFile(absPath)) as IstanbulPayload;
-        result = ingestIstanbul({
+      if (opts.runtime) {
+        const { absDir, jsonFiles } = resolveV8Directory(opts.path, opts.root);
+        displayPath = absDir;
+        const scripts: V8ScriptCoverage[] = [];
+        for (const file of jsonFiles) {
+          const payload = (await readJsonFile(file)) as V8CoveragePayload;
+          if (Array.isArray(payload?.result)) scripts.push(...payload.result);
+        }
+        if (scripts.length === 0) {
+          throw new Error(
+            `codemap ingest-coverage --runtime: ${jsonFiles.length} coverage-*.json file(s) under ${absDir} contained no V8 \`result\` arrays. Confirm the directory is the one NODE_V8_COVERAGE wrote to.`,
+          );
+        }
+        result = ingestV8({
           db,
           projectRoot: opts.root,
-          payload,
-          sourcePath: absPath,
+          scripts,
+          sourcePath: absDir,
         });
       } else {
-        const payload = await readTextFile(absPath);
-        result = ingestLcov({
-          db,
-          projectRoot: opts.root,
-          payload,
-          sourcePath: absPath,
-        });
+        const { format, absPath } = resolveArtifact(opts.path, opts.root);
+        displayPath = absPath;
+        if (format === "istanbul") {
+          const payload = (await readJsonFile(absPath)) as IstanbulPayload;
+          result = ingestIstanbul({
+            db,
+            projectRoot: opts.root,
+            payload,
+            sourcePath: absPath,
+          });
+        } else {
+          const payload = await readTextFile(absPath);
+          result = ingestLcov({
+            db,
+            projectRoot: opts.root,
+            payload,
+            sourcePath: absPath,
+          });
+        }
       }
     } finally {
       closeDb(db);
@@ -192,7 +263,7 @@ export async function runIngestCoverageCmd(
       console.log(JSON.stringify(result));
       return;
     }
-    renderTerminal(result, absPath);
+    renderTerminal(result, displayPath);
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     if (opts.json) {
diff --git a/src/cli/main.ts b/src/cli/main.ts
index 7ae179a..cdd08ca 100644
--- a/src/cli/main.ts
+++ b/src/cli/main.ts
@@ -1,3 +1,8 @@
+import {
+  isOutcomeAlias,
+  printOutcomeAliasHelp,
+  resolveOutcomeAlias,
+} from "./aliases.js";
 import {
   parseBootstrapArgs,
   printCliUsage,
@@ -25,6 +30,17 @@ export async function main(): Promise<void> {
     return;
   }
 
+  // Outcome aliases — rewrite `<alias>` to `query --recipe <id>` so the
+  // existing query dispatch handles every flag pass-through. See ./aliases.ts.
+  if (rest[0] && isOutcomeAlias(rest[0])) {
+    if (rest.includes("--help") || rest.includes("-h")) {
+      printOutcomeAliasHelp(rest[0]);
+      return;
+    }
+    const rewritten = resolveOutcomeAlias(rest);
+    if (rewritten) rest.splice(0, rest.length, ...rewritten);
+  }
+
   if (rest[0] === "agents" && rest[1] === "init") {
     if (rest.includes("--help") || rest.includes("-h")) {
       console.log(`Usage: codemap agents init [--force] [--interactive|-i]
@@ -326,6 +342,7 @@ Copies bundled agent templates into .agents/ under the project root.
       stateDir,
       path: parsed.path,
       json: parsed.json,
+      runtime: parsed.runtime,
     });
     return;
   }
diff --git a/src/db.ts b/src/db.ts
index fdf75a7..496f13b 100644
--- a/src/db.ts
+++ b/src/db.ts
@@ -2,7 +2,7 @@ import { openCodemapDatabase } from "./sqlite-db";
 import type { CodemapDatabase, BindValues } from "./sqlite-db";
 
 /** Bump on any DDL change; `createSchema()` auto-rebuilds on mismatch. */
-export const SCHEMA_VERSION = 9;
+export const SCHEMA_VERSION = 10;
 
 /**
  * `meta` key tracking the FTS5 state at the last reindex; mismatch with the
@@ -142,6 +142,16 @@ export function createTables(db: CodemapDatabase) {
       is_readonly INTEGER NOT NULL DEFAULT 0
     ) STRICT;
 
+    -- Opt-in suppressions — recipes LEFT JOIN to honor, ad-hoc SQL unaffected.
+    -- line_number > 0 = next-line scope (suppressed line). 0 = file scope.
+    -- Sourced from // codemap-ignore-{next-line,file} <recipe-id> directives (see markers.ts).
+    CREATE TABLE IF NOT EXISTS suppressions (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      file_path TEXT NOT NULL REFERENCES files(path) ON DELETE CASCADE,
+      line_number INTEGER NOT NULL,
+      recipe_id TEXT NOT NULL
+    ) STRICT;
+
     CREATE TABLE IF NOT EXISTS meta (
       key TEXT PRIMARY KEY,
       value TEXT
@@ -270,6 +280,10 @@ export function createIndexes(db: CodemapDatabase) {
     CREATE INDEX IF NOT EXISTS idx_markers_kind ON markers(kind, file_path, line_number, content);
     CREATE INDEX IF NOT EXISTS idx_markers_file ON markers(file_path);
 
+    -- Suppressions: most recipe LEFT JOINs key on (recipe_id, file_path[, line_number]).
+    CREATE INDEX IF NOT EXISTS idx_suppressions_lookup ON suppressions(recipe_id, file_path, line_number);
+    CREATE INDEX IF NOT EXISTS idx_suppressions_file ON suppressions(file_path);
+
     CREATE INDEX IF NOT EXISTS idx_css_variables_name ON css_variables(name, value, scope, file_path);
     CREATE INDEX IF NOT EXISTS idx_css_variables_file ON css_variables(file_path);
     CREATE INDEX IF NOT EXISTS idx_css_classes_name ON css_classes(name, file_path, is_module);
@@ -317,6 +331,7 @@ export function createSchema(db: CodemapDatabase) {
 export function dropAll(db: CodemapDatabase) {
   db.run(`
     DROP TABLE IF EXISTS calls;
+    DROP TABLE IF EXISTS suppressions;
     DROP TABLE IF EXISTS type_members;
     DROP TABLE IF EXISTS dependencies;
     DROP TABLE IF EXISTS markers;
@@ -637,6 +652,26 @@ export function insertMarkers(db: CodemapDatabase, markers: MarkerRow[]) {
   );
 }
 
+/** Suppression marker; `line_number > 0` = next-line scope, `0` = file scope. See markers.ts + the `suppressions` DDL. */
+export interface SuppressionRow {
+  file_path: string;
+  line_number: number;
+  recipe_id: string;
+}
+
+export function insertSuppressions(
+  db: CodemapDatabase,
+  suppressions: SuppressionRow[],
+) {
+  batchInsert(
+    db,
+    suppressions,
+    "INSERT INTO suppressions (file_path, line_number, recipe_id)",
+    "(?,?,?)",
+    (s, v) => v.push(s.file_path, s.line_number, s.recipe_id),
+  );
+}
+
 /**
  * CSS custom property (`--token: value`). `scope` is `:root`, `@theme`
  * (Tailwind v4), or the selector text where the property was declared.
diff --git a/src/markers.test.ts b/src/markers.test.ts
index 8c3c456..fa0d1d3 100644
--- a/src/markers.test.ts
+++ b/src/markers.test.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it } from "bun:test";
 
-import { extractMarkers } from "./markers";
+import { extractMarkers, extractSuppressions } from "./markers";
 
 describe("extractMarkers", () => {
   it("finds TODO with line number and content", () => {
@@ -44,3 +44,92 @@ describe("extractMarkers", () => {
     expect(extractMarkers("const x = 1;", "f.ts")).toEqual([]);
   });
 });
+
+describe("extractSuppressions", () => {
+  it("recognizes // codemap-ignore-next-line and points at the next line", () => {
+    const src = [
+      "const a = 1;", // line 1
+      "// codemap-ignore-next-line untested-and-dead", // line 2
+      "export function legacy() {}", // line 3 — suppressed
+    ].join("\n");
+    const s = extractSuppressions(src, "f.ts");
+    expect(s).toEqual([
+      { file_path: "f.ts", line_number: 3, recipe_id: "untested-and-dead" },
+    ]);
+  });
+
+  it("recognizes // codemap-ignore-file and encodes scope as line_number = 0", () => {
+    const src =
+      "// codemap-ignore-file boundary-violations\nimport x from './y';\n";
+    const s = extractSuppressions(src, "f.ts");
+    expect(s).toEqual([
+      { file_path: "f.ts", line_number: 0, recipe_id: "boundary-violations" },
+    ]);
+  });
+
+  it("supports multiple suppressions across one file", () => {
+    const src = [
+      "// codemap-ignore-file deprecated-symbols",
+      "// line 2",
+      "// codemap-ignore-next-line unimported-exports",
+      "export const x = 1;",
+    ].join("\n");
+    const s = extractSuppressions(src, "f.ts");
+    expect(s).toHaveLength(2);
+    expect(s[0]).toEqual({
+      file_path: "f.ts",
+      line_number: 0,
+      recipe_id: "deprecated-symbols",
+    });
+    expect(s[1]).toEqual({
+      file_path: "f.ts",
+      line_number: 4,
+      recipe_id: "unimported-exports",
+    });
+  });
+
+  it("recognises hash, dash, and HTML/block comment leaders (markdown / yaml / sql)", () => {
+    expect(
+      extractSuppressions(
+        "# codemap-ignore-file deprecated-symbols\n",
+        "a.yml",
+      ),
+    ).toEqual([
+      { file_path: "a.yml", line_number: 0, recipe_id: "deprecated-symbols" },
+    ]);
+    expect(
+      extractSuppressions("-- codemap-ignore-file boundaries\n", "schema.sql"),
+    ).toEqual([
+      { file_path: "schema.sql", line_number: 0, recipe_id: "boundaries" },
+    ]);
+    expect(
+      extractSuppressions(
+        "<!-- codemap-ignore-file unused-type-members -->\n",
+        "doc.md",
+      ),
+    ).toEqual([
+      { file_path: "doc.md", line_number: 0, recipe_id: "unused-type-members" },
+    ]);
+    expect(
+      extractSuppressions("/* codemap-ignore-file fan-in */\n", "f.css"),
+    ).toEqual([{ file_path: "f.css", line_number: 0, recipe_id: "fan-in" }]);
+  });
+
+  it("returns empty when no suppression markers", () => {
+    expect(
+      extractSuppressions("const x = 1;\n// regular TODO: y\n", "f.ts"),
+    ).toEqual([]);
+  });
+
+  it("ignores prose mentions inside multi-line doc comments (no false positives)", () => {
+    // ` * ` continuation lines aren't leaders, so directive in prose is ignored.
+    const src = [
+      "/**",
+      " * Document mentions codemap-ignore-file boundaries in prose;",
+      " * NOT a real suppression because the line leader is `* `, not `//`.",
+      " */",
+      "export const x = 1;",
+    ].join("\n");
+    expect(extractSuppressions(src, "f.ts")).toEqual([]);
+  });
+});
diff --git a/src/markers.ts b/src/markers.ts
index da4cf56..10c3b3f 100644
--- a/src/markers.ts
+++ b/src/markers.ts
@@ -1,7 +1,13 @@
-import type { MarkerRow } from "./db";
+import type { MarkerRow, SuppressionRow } from "./db";
 
 const MARKER_RE = /\b(TODO|FIXME|HACK|NOTE)[\s:]+(.+)/g;
 
+// Leader must start the line (modulo whitespace) so the directive never
+// matches inside a string literal — both this clone's tests and recipe docs
+// embed the phrase legitimately.
+const SUPPRESS_RE =
+  /(?:^|\n)\s*(?:\/\/|#|--|<!--|\/\*+)\s*codemap-ignore-(next-line|file)\s+([\w.\-/:@]+)/g;
+
 export function extractMarkers(source: string, filePath: string): MarkerRow[] {
   const markers: MarkerRow[] = [];
   MARKER_RE.lastIndex = 0;
@@ -22,3 +28,31 @@ export function extractMarkers(source: string, filePath: string): MarkerRow[] {
   }
   return markers;
 }
+
+export function extractSuppressions(
+  source: string,
+  filePath: string,
+): SuppressionRow[] {
+  const out: SuppressionRow[] = [];
+  SUPPRESS_RE.lastIndex = 0;
+  let match: RegExpExecArray | null;
+  while ((match = SUPPRESS_RE.exec(source)) !== null) {
+    // Index of the directive keyword, not match.index — the pattern can
+    // consume a leading `\n`, which would skew the line count.
+    const keywordOffset = match.index + match[0].indexOf("codemap-ignore");
+    let line = 1;
+    for (let i = 0; i < keywordOffset; i++) {
+      if (source.charCodeAt(i) === 10) line++;
+    }
+    const scope = match[1] as "next-line" | "file";
+    const recipeId = match[2];
+    // file scope encoded as 0 so a single column carries both shapes.
+    const lineNumber = scope === "file" ? 0 : line + 1;
+    out.push({
+      file_path: filePath,
+      line_number: lineNumber,
+      recipe_id: recipeId,
+    });
+  }
+  return out;
+}
diff --git a/src/parse-worker-core.ts b/src/parse-worker-core.ts
index 2be558b..e386f40 100644
--- a/src/parse-worker-core.ts
+++ b/src/parse-worker-core.ts
@@ -6,7 +6,7 @@ import type { ParseContext } from "./adapters/types";
 import { LANG_MAP } from "./constants";
 import type { FileRow } from "./db";
 import { hashContent } from "./hash";
-import { extractMarkers } from "./markers";
+import { extractMarkers, extractSuppressions } from "./markers";
 import type { ParsedFile } from "./parsed-types";
 
 export type { ParsedFile } from "./parsed-types";
@@ -25,10 +25,11 @@ export interface WorkerOutput {
 function parseAsTextFallback(
   source: string,
   relPath: string,
-): Pick<ParsedFile, "category" | "markers"> {
+): Pick<ParsedFile, "category" | "markers" | "suppressions"> {
   return {
     category: "text",
     markers: extractMarkers(source, relPath),
+    suppressions: extractSuppressions(source, relPath),
   };
 }
 
diff --git a/src/parsed-types.ts b/src/parsed-types.ts
index 5a68ddf..e877039 100644
--- a/src/parsed-types.ts
+++ b/src/parsed-types.ts
@@ -5,6 +5,7 @@ import type {
   ExportRow,
   ComponentRow,
   MarkerRow,
+  SuppressionRow,
   CssVariableRow,
   CssClassRow,
   CssKeyframeRow,
@@ -33,6 +34,7 @@ export interface ParsedFile {
   exports?: ExportRow[];
   components?: ComponentRow[];
   markers?: MarkerRow[];
+  suppressions?: SuppressionRow[];
   typeMembers?: TypeMemberRow[];
   calls?: CallRow[];
   /** CSS-only fields (populated when `category === "css"`). */
diff --git a/templates/agents/rules/codemap.md b/templates/agents/rules/codemap.md
index 00adc30..a7e1a46 100644
--- a/templates/agents/rules/codemap.md
+++ b/templates/agents/rules/codemap.md
@@ -18,37 +18,39 @@ Install **[@stainless-code/codemap](https://www.npmjs.com/package/@stainless-cod
 
 **Examples below use `codemap`** — prefix with **`npx @stainless-code/codemap`** (or **`pnpm dlx`**, **`yarn dlx`**, **`bunx`**) when the CLI is not on your **`PATH`**.
 
-| Action                            | Command                                                                                                                                                                                                                                                                                           |
-| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Incremental index                 | `codemap`                                                                                                                                                                                                                                                                                         |
-| Query (JSON — default for agents) | `codemap query --json "<SQL>"`                                                                                                                                                                                                                                                                    |
-| Query (ASCII table — optional)    | `codemap query "<SQL>"`                                                                                                                                                                                                                                                                           |
-| Query (recipe)                    | `codemap query --json --recipe fan-out` (see **`codemap query --help`**)                                                                                                                                                                                                                          |
-| Parametrised recipe               | `codemap query --json --recipe find-symbol-by-kind --params kind=function,name_pattern=%Query%` — params declared in recipe `.md` frontmatter and validated before SQL binding.                                                                                                                   |
-| Boundary violations               | `codemap query --json --recipe boundary-violations` — joins `dependencies` × `boundary_rules` (config-driven) via SQLite `GLOB`. `.codemap/config.ts` `boundaries: [{name, from_glob, to_glob, action?}]`; default `action: "deny"`. SARIF / annotations work via the `file_path` alias.          |
-| Rename preview                    | `codemap query --recipe rename-preview --params old=usePermissions,new=useAccess,kind=function --format diff` — read-only unified diff; codemap never writes files.                                                                                                                               |
-| Recipe catalog (JSON)             | `codemap query --recipes-json`                                                                                                                                                                                                                                                                    |
-| Print one recipe’s SQL            | `codemap query --print-sql fan-out`                                                                                                                                                                                                                                                               |
-| Counts only                       | `codemap query --json --summary -r deprecated-symbols`                                                                                                                                                                                                                                            |
-| PR-scoped rows                    | `codemap query --json --changed-since origin/main -r fan-out`                                                                                                                                                                                                                                     |
-| Bucket by owner / dir / pkg       | `codemap query --json --group-by directory -r fan-in`                                                                                                                                                                                                                                             |
-| Save / diff a baseline            | `codemap query --save-baseline -r visibility-tags` then `… --json --baseline -r visibility-tags`                                                                                                                                                                                                  |
-| List / drop baselines             | `codemap query --baselines` · `codemap query --drop-baseline <name>`                                                                                                                                                                                                                              |
-| Per-delta audit                   | `codemap audit --json --baseline base` (auto-resolves `base-files` / `base-dependencies` / `base-deprecated`)                                                                                                                                                                                     |
-| Audit vs git ref                  | `codemap audit --base origin/main --json` — worktree+reindex against any committish; sub-100ms second run via sha-keyed cache. Mutually exclusive with `--baseline`; per-delta overrides compose. Add `--format sarif` to emit SARIF 2.1.0 directly (one rule per delta key; severity `warning`). |
-| MCP server (for agent hosts)      | `codemap mcp` — JSON-RPC on stdio; one tool per CLI verb. See **MCP** section below.                                                                                                                                                                                                              |
-| Targeted read (metadata)          | `codemap show <name> [--kind <k>] [--in <path>] [--json]` — file:line + signature                                                                                                                                                                                                                 |
-| Targeted read (source text)       | `codemap snippet <name> [--kind <k>] [--in <path>] [--json]` — same lookup + source from disk + stale flag                                                                                                                                                                                        |
-| Impact (blast-radius walker)      | `codemap impact <target> [--direction up\|down\|both] [--depth N] [--via <b>] [--limit N] [--summary] [--json]` — replaces hand-composed `WITH RECURSIVE` queries                                                                                                                                 |
-| Coverage ingest                   | `codemap ingest-coverage <path> [--json]` — Istanbul (`coverage-final.json`) or LCOV (`lcov.info`); format auto-detected. Joinable to `symbols` for "untested AND dead" queries.                                                                                                                  |
-| SARIF / GH annotations            | `codemap query --recipe deprecated-symbols --format sarif` · `… --format annotations`                                                                                                                                                                                                             |
-| `--ci` aggregate flag             | `codemap query -r deprecated-symbols --ci` (or `audit --base origin/main --ci`) — aliases `--format sarif` + non-zero exit when findings/additions surfaced + suppresses the no-locatable-rows stderr warning. Mutually exclusive with `--json` / `--format <other>`.                             |
-| PR-comment renderer               | `codemap pr-comment <input.json>` (or `-` for stdin) — renders an audit JSON envelope or SARIF doc as a markdown PR-summary comment. Pipe to `gh pr comment <PR> -F -`. Useful for private repos without GHAS, aggregate audit deltas, or bot-context seeding.                                    |
-| Mermaid graph (≤50 edges)         | `codemap query --format mermaid 'SELECT from_path AS "from", to_path AS "to" FROM dependencies LIMIT 50'` — recipes / SQL must alias columns to `{from, to, label?, kind?}`; rejects unbounded inputs.                                                                                            |
-| Diff preview                      | `codemap query --format diff '<SQL returning file_path, line_start, before_pattern, after_pattern>'` — read-only unified diff; `--format diff-json` returns structured hunks for agents.                                                                                                          |
-| FTS5 full-text (opt-in)           | `codemap --with-fts --full` enables `source_fts` virtual table; `query --recipe text-in-deprecated-functions` demos JOINs.                                                                                                                                                                        |
-| HTTP server (for non-MCP)         | `codemap serve [--host 127.0.0.1] [--port 7878] [--token <secret>] [--no-watch] [--debounce <ms>]` — same tool taxonomy over POST /tool/{name}. Watcher default-ON since 2026-05.                                                                                                                 |
-| Watch mode (live reindex)         | `codemap watch [--debounce 250] [--quiet]` — standalone long-running process; debounced reindex on file changes. `mcp` / `serve` boot the watcher in-process by default — pass `--no-watch` (or `CODEMAP_WATCH=0`) to opt out.                                                                    |
+| Action                            | Command                                                                                                                                                                                                                                                                                                                                                    |
+| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Incremental index                 | `codemap`                                                                                                                                                                                                                                                                                                                                                  |
+| Query (JSON — default for agents) | `codemap query --json "<SQL>"`                                                                                                                                                                                                                                                                                                                             |
+| Query (ASCII table — optional)    | `codemap query "<SQL>"`                                                                                                                                                                                                                                                                                                                                    |
+| Query (recipe)                    | `codemap query --json --recipe fan-out` (see **`codemap query --help`**)                                                                                                                                                                                                                                                                                   |
+| Outcome alias                     | `codemap dead-code` · `deprecated` · `boundaries` · `hotspots` · `coverage-gaps` — thin wrappers over `query --recipe <id>`; every `query` flag passes through. See `codemap <alias> --help` for the wrapped recipe id. Capped at 5 to avoid sprawl.                                                                                                       |
+| Suppressions (opt-in)             | `// codemap-ignore-next-line <recipe-id>` and `// codemap-ignore-file <recipe-id>` (also `#`, `--`, `<!--`, `/*` leaders) populate `suppressions(file_path, line_number, recipe_id)`. Recipes opt in via `LEFT JOIN`; `untested-and-dead` (line + file) and `unimported-exports` (file only) honor today.                                                  |
+| Parametrised recipe               | `codemap query --json --recipe find-symbol-by-kind --params kind=function,name_pattern=%Query%` — params declared in recipe `.md` frontmatter and validated before SQL binding.                                                                                                                                                                            |
+| Boundary violations               | `codemap query --json --recipe boundary-violations` — joins `dependencies` × `boundary_rules` (config-driven) via SQLite `GLOB`. `.codemap/config.ts` `boundaries: [{name, from_glob, to_glob, action?}]`; default `action: "deny"`. SARIF / annotations work via the `file_path` alias.                                                                   |
+| Rename preview                    | `codemap query --recipe rename-preview --params old=usePermissions,new=useAccess,kind=function --format diff` — read-only unified diff; codemap never writes files.                                                                                                                                                                                        |
+| Recipe catalog (JSON)             | `codemap query --recipes-json`                                                                                                                                                                                                                                                                                                                             |
+| Print one recipe’s SQL            | `codemap query --print-sql fan-out`                                                                                                                                                                                                                                                                                                                        |
+| Counts only                       | `codemap query --json --summary -r deprecated-symbols`                                                                                                                                                                                                                                                                                                     |
+| PR-scoped rows                    | `codemap query --json --changed-since origin/main -r fan-out`                                                                                                                                                                                                                                                                                              |
+| Bucket by owner / dir / pkg       | `codemap query --json --group-by directory -r fan-in`                                                                                                                                                                                                                                                                                                      |
+| Save / diff a baseline            | `codemap query --save-baseline -r visibility-tags` then `… --json --baseline -r visibility-tags`                                                                                                                                                                                                                                                           |
+| List / drop baselines             | `codemap query --baselines` · `codemap query --drop-baseline <name>`                                                                                                                                                                                                                                                                                       |
+| Per-delta audit                   | `codemap audit --json --baseline base` (auto-resolves `base-files` / `base-dependencies` / `base-deprecated`)                                                                                                                                                                                                                                              |
+| Audit vs git ref                  | `codemap audit --base origin/main --json` — worktree+reindex against any committish; sub-100ms second run via sha-keyed cache. Mutually exclusive with `--baseline`; per-delta overrides compose. Add `--format sarif` to emit SARIF 2.1.0 directly (one rule per delta key; severity `warning`).                                                          |
+| MCP server (for agent hosts)      | `codemap mcp` — JSON-RPC on stdio; one tool per CLI verb. See **MCP** section below.                                                                                                                                                                                                                                                                       |
+| Targeted read (metadata)          | `codemap show <name> [--kind <k>] [--in <path>] [--json]` — file:line + signature                                                                                                                                                                                                                                                                          |
+| Targeted read (source text)       | `codemap snippet <name> [--kind <k>] [--in <path>] [--json]` — same lookup + source from disk + stale flag                                                                                                                                                                                                                                                 |
+| Impact (blast-radius walker)      | `codemap impact <target> [--direction up\|down\|both] [--depth N] [--via <b>] [--limit N] [--summary] [--json]` — replaces hand-composed `WITH RECURSIVE` queries                                                                                                                                                                                          |
+| Coverage ingest                   | `codemap ingest-coverage <path> [--runtime] [--json]` — Istanbul (`coverage-final.json`) and LCOV (`lcov.info`) auto-detect from path; V8 is **opt-in** via `--runtime` (treats `<path>` as a `NODE_V8_COVERAGE=...`-style directory of `coverage-*.json` dumps). Joinable to `symbols` for "untested AND dead" queries. Local-only — no SaaS aggregation. |
+| SARIF / GH annotations            | `codemap query --recipe deprecated-symbols --format sarif` · `… --format annotations`                                                                                                                                                                                                                                                                      |
+| `--ci` aggregate flag             | `codemap query -r deprecated-symbols --ci` (or `audit --base origin/main --ci`) — aliases `--format sarif` + non-zero exit when findings/additions surfaced + suppresses the no-locatable-rows stderr warning. Mutually exclusive with `--json` / `--format <other>`.                                                                                      |
+| PR-comment renderer               | `codemap pr-comment <input.json>` (or `-` for stdin) — renders an audit JSON envelope or SARIF doc as a markdown PR-summary comment. Pipe to `gh pr comment <PR> -F -`. Useful for private repos without GHAS, aggregate audit deltas, or bot-context seeding.                                                                                             |
+| Mermaid graph (≤50 edges)         | `codemap query --format mermaid 'SELECT from_path AS "from", to_path AS "to" FROM dependencies LIMIT 50'` — recipes / SQL must alias columns to `{from, to, label?, kind?}`; rejects unbounded inputs.                                                                                                                                                     |
+| Diff preview                      | `codemap query --format diff '<SQL returning file_path, line_start, before_pattern, after_pattern>'` — read-only unified diff; `--format diff-json` returns structured hunks for agents.                                                                                                                                                                   |
+| FTS5 full-text (opt-in)           | `codemap --with-fts --full` enables `source_fts` virtual table; `query --recipe text-in-deprecated-functions` demos JOINs.                                                                                                                                                                                                                                 |
+| HTTP server (for non-MCP)         | `codemap serve [--host 127.0.0.1] [--port 7878] [--token <secret>] [--no-watch] [--debounce <ms>]` — same tool taxonomy over POST /tool/{name}. Watcher default-ON since 2026-05.                                                                                                                                                                          |
+| Watch mode (live reindex)         | `codemap watch [--debounce 250] [--quiet]` — standalone long-running process; debounced reindex on file changes. `mcp` / `serve` boot the watcher in-process by default — pass `--no-watch` (or `CODEMAP_WATCH=0`) to opt out.                                                                                                                             |
 
 **Recipe metadata:** with **`--json`**, recipes that define an `actions` template append it to every row (kebab-case verb + description — e.g. `fan-out` → `review-coupling`). Under `--baseline`, actions attach to the **`added`** rows only. Parametrised recipes declare `params` in `.md` frontmatter; pass values with `--params key=value[,key=value]` (repeatable; last value wins). Inspect both via **`--recipes-json`**. Ad-hoc SQL never carries actions or params.
 
diff --git a/templates/agents/skills/codemap/SKILL.md b/templates/agents/skills/codemap/SKILL.md
index a965db2..ffdf815 100644
--- a/templates/agents/skills/codemap/SKILL.md
+++ b/templates/agents/skills/codemap/SKILL.md
@@ -34,7 +34,11 @@ Use **`codemap --root /path/to/project`** (or **`CODEMAP_ROOT`**) to index anoth
 
 Replace placeholders (`'...'`) with your module path, file glob, or symbol name.
 
-**CLI shortcuts:** **`codemap query --json --recipe <id>`** runs bundled SQL (preferred for agents). **`codemap query --recipe <id>`** without **`--json`** prints a table. **`codemap query --recipes-json`** prints every bundled recipe (**`id`**, **`description`**, **`sql`**, optional **`actions`**) as JSON (no index / DB required). **`codemap query --print-sql <id>`** prints one recipe’s SQL only. Ids include **`fan-out`**, **`fan-out-sample`** (**`GROUP_CONCAT`** samples), **`fan-out-sample-json`** (same, but **`json_group_array`** — needs SQLite JSON1), **`fan-in`**, **`index-summary`**, **`files-largest`**, **`components-by-hooks`**, **`components-touching-deprecated`** (UNION of hook + call paths to `@deprecated` symbols), **`markers-by-kind`**, **`deprecated-symbols`**, **`refactor-risk-ranking`** (per-file `(fan_in + 1) × (100 - avg_coverage_pct)`), **`high-complexity-untested`** (cyclomatic complexity ≥ 10 + coverage < 50%; per-function), **`text-in-deprecated-functions`** (FTS5 ⨯ symbols ⨯ coverage demo — needs `--with-fts` enabled), **`unimported-exports`** (exports with no detectable importer; v1 doesn't follow re-export chains — see recipe `.md` for caveats), **`visibility-tags`**, **`barrel-files`**, **`files-hashes`**, **`untested-and-dead`** (exported AND uncalled AND uncovered), **`files-by-coverage`** (per-file rollup of statement coverage), **`worst-covered-exports`** (lowest-covered exported symbols) — see **`codemap query --help`**.
+**Outcome aliases:** **`codemap dead-code`** · **`deprecated`** · **`boundaries`** · **`hotspots`** · **`coverage-gaps`** — thin wrappers over `query --recipe <id>`. Every `query` flag passes through (`--json`, `--format sarif`, `--ci`, `--summary`, `--changed-since`, `--group-by`, `--params`, `--save-baseline`, `--baseline`). Run **`codemap <alias> --help`** for the wrapped recipe id. Capped at 5 to avoid sprawl.
+
+**Suppressions (opt-in):** `// codemap-ignore-next-line <recipe-id>` and `// codemap-ignore-file <recipe-id>` (also `#`, `--`, `<!--`, `/*` leaders) get parsed into the `suppressions(file_path, line_number, recipe_id)` table. Recipe authors opt in by `LEFT JOIN`-ing on `(file_path, recipe_id)` with `line_number = 0` for file scope or `line_number = <row's line>` for next-line. Ad-hoc SQL is unaffected. No severity, no suppression-by-default, no universal-honor — consumer-chosen substrate. Today's opt-in recipes: `untested-and-dead` (line + file), `unimported-exports` (file only — exports has no `line_number`).
+
+**CLI shortcuts:** **`codemap query --json --recipe <id>`** runs bundled SQL (preferred for agents). **`codemap query --recipe <id>`** without **`--json`** prints a table. **`codemap query --recipes-json`** prints every bundled recipe (**`id`**, **`description`**, **`sql`**, optional **`actions`**) as JSON (no index / DB required). **`codemap query --print-sql <id>`** prints one recipe’s SQL only. Ids include **`fan-out`**, **`fan-out-sample`** (**`GROUP_CONCAT`** samples), **`fan-out-sample-json`** (same, but **`json_group_array`** — needs SQLite JSON1), **`fan-in`**, **`index-summary`**, **`files-largest`**, **`components-by-hooks`**, **`components-touching-deprecated`** (UNION of hook + call paths to `@deprecated` symbols), **`markers-by-kind`**, **`deprecated-symbols`**, **`refactor-risk-ranking`** (per-file `(fan_in + 1) × (100 - avg_coverage_pct)`), **`high-complexity-untested`** (cyclomatic complexity ≥ 10 + coverage < 50%; per-function), **`text-in-deprecated-functions`** (FTS5 ⨯ symbols ⨯ coverage demo — needs `--with-fts` enabled), **`unimported-exports`** (exports with no detectable importer; v1 doesn't follow re-export chains — see recipe `.md` for caveats), **`unused-type-members`** (advisory; field-level enumeration of `unimported-exports` joining `type_members`; codemap can't see indexed access / `keyof T` / mapped types / destructuring — see recipe `.md` for caveats), **`visibility-tags`**, **`barrel-files`**, **`files-hashes`**, **`untested-and-dead`** (exported AND uncalled AND uncovered), **`files-by-coverage`** (per-file rollup of statement coverage), **`worst-covered-exports`** (lowest-covered exported symbols) — see **`codemap query --help`**.
 
 **Output flags** (compose with **`--recipe`** or ad-hoc SQL):
 
@@ -273,7 +277,7 @@ User-facing baselines saved by `codemap query --save-baseline`, replayed by `cod
 
 ### `coverage` — Statement coverage (user data, ingested via `codemap ingest-coverage`)
 
-Static coverage from Istanbul JSON or LCOV. Joinable to `symbols` for "what's untested?" queries. **Survives `--full` and SCHEMA bumps** — intentionally absent from `dropAll()`. Empty until first ingest.
+Coverage from Istanbul JSON, LCOV, or V8 runtime (`NODE_V8_COVERAGE=...` directory via `--runtime`). Joinable to `symbols` for "what's untested?" queries. **Survives `--full` and SCHEMA bumps** — intentionally absent from `dropAll()`. Empty until first ingest. V8 mode is local-only — no SaaS aggregation.
 
 | Column           | Type    | Description                                                                                              |
 | ---------------- | ------- | -------------------------------------------------------------------------------------------------------- |
diff --git a/templates/recipes/unimported-exports.sql b/templates/recipes/unimported-exports.sql
index 7beac09..14d334e 100644
--- a/templates/recipes/unimported-exports.sql
+++ b/templates/recipes/unimported-exports.sql
@@ -19,6 +19,7 @@ WITH direct_uses AS (
   CROSS JOIN json_each(i.specifiers) j
   WHERE j.value = e.name OR j.value = '*'
 )
+-- File-scope suppressions only — `exports` has no line_number column.
 SELECT
   e.name,
   e.kind,
@@ -26,8 +27,13 @@ SELECT
   e.is_default,
   e.re_export_source
 FROM exports e
+LEFT JOIN suppressions s
+  ON s.file_path = e.file_path
+ AND s.recipe_id = 'unimported-exports'
+ AND s.line_number = 0
 WHERE e.id NOT IN (SELECT id FROM direct_uses)
   AND e.is_default = 0
   AND e.kind != 're-export'
+  AND s.id IS NULL
 ORDER BY e.file_path, e.name
 LIMIT 50
diff --git a/templates/recipes/untested-and-dead.sql b/templates/recipes/untested-and-dead.sql
index a763613..7963dbe 100644
--- a/templates/recipes/untested-and-dead.sql
+++ b/templates/recipes/untested-and-dead.sql
@@ -1,3 +1,4 @@
+-- Honors `// codemap-ignore-{next-line,file} untested-and-dead` via the suppressions LEFT JOIN.
 SELECT
   s.name,
   s.file_path,
@@ -8,9 +9,14 @@ LEFT JOIN coverage c
   ON  c.file_path  = s.file_path
   AND c.name       = s.name
   AND c.line_start = s.line_start
+LEFT JOIN suppressions sup
+  ON  sup.file_path = s.file_path
+  AND sup.recipe_id = 'untested-and-dead'
+  AND (sup.line_number = 0 OR sup.line_number = s.line_start)
 WHERE s.kind = 'function'
   AND s.is_exported = 1
   AND NOT EXISTS (SELECT 1 FROM calls WHERE callee_name = s.name)
   AND COALESCE(c.coverage_pct, 0) = 0
+  AND sup.id IS NULL
 ORDER BY s.file_path ASC, s.line_start ASC
 LIMIT 100
diff --git a/templates/recipes/unused-type-members.md b/templates/recipes/unused-type-members.md
new file mode 100644
index 0000000..3964853
--- /dev/null
+++ b/templates/recipes/unused-type-members.md
@@ -0,0 +1,46 @@
+---
+actions:
+  - type: review-for-deletion
+    auto_fixable: false
+    description: "Member of an EXPORTED type that has no detectable importer. STARTING POINT for review only — codemap cannot see indexed access (T['field']), keyof T, mapped types, type spreads, destructuring, or re-export chains. Cross-check with rg before deleting."
+---
+
+Field-level enumeration of types that are **exported but never directly imported** anywhere in the project. Sister recipe to [`unimported-exports`](./unimported-exports.md): same upstream signal (`exports.name NOT IN imports.specifiers`), but JOINed against `type_members` so each row carries the field's name, type annotation, optionality, and readonly flag.
+
+## When to reach for it
+
+- Planning a deletion of an interface or type alias and need the full field inventory before drafting the codemod.
+- Auditing a published API surface — which exported types carry fields that consumers don't reference?
+- Cross-checking `rename-preview` — if `rename-preview` finds zero call sites for a symbol, this recipe's parent type is a candidate too.
+
+## When NOT to reach for it
+
+- "Find unused fields on a type that IS imported." Codemap does not track property access — there's no substrate for this question. False-positive rate would be near 100%.
+- "Safe-to-delete list." Treat every row as a candidate worth a `rg <member>` pass before any deletion.
+
+## Substrate caveats (codemap can't see)
+
+The recipe inherits all the false-positive classes of `unimported-exports`, **plus** the fact that interface fields can be referenced indirectly through several TypeScript constructs codemap doesn't model:
+
+| Pattern                                                             | Why it's invisible                                                                             |
+| ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| Indexed access — `T['baseUrl']`                                     | String-key lookup; the field name is in a string literal, not a name reference.                |
+| `keyof T` / mapped types — `{ [K in keyof T]: U }`                  | Members are used as a set; no per-field reference.                                             |
+| Type spreads — `interface U extends T {}`, `type U = T & {…}`       | Members propagate without per-field mention.                                                   |
+| Destructuring — `function f({ baseUrl }: ClientConfig)`             | Property access; codemap's `calls` table tracks function calls, not property reads.            |
+| Re-export chains — barrel `export { ClientConfig } from './client'` | Same gap as `unimported-exports`; recursive CTE walking `re_export_source` is a future recipe. |
+| `tsconfig.json` path aliases                                        | When `imports.resolved_path IS NULL` the row is excluded; common with unusual config.          |
+| Default exports                                                     | Excluded (`e.is_default = 0`) — high false-positive class on framework entry points.           |
+
+## Tuning axes for project-local overrides
+
+- **Scope to a directory** — add `AND tm.file_path LIKE 'src/lib/%'` to narrow the audit to a single owner / package.
+- **Filter to optional fields** — add `AND tm.is_optional = 1` to surface candidates whose absence wouldn't break compilation.
+- **Filter to readonly fields** — add `AND tm.is_readonly = 1` to surface immutable contract surface.
+- **Exclude conventional public-API types** — add `AND tm.symbol_name NOT LIKE '%Props' AND tm.symbol_name NOT LIKE '%Config'` if your codebase treats those suffixes as deliberate consumer surface.
+
+## What's NOT covered (orthogonal recipes)
+
+- **Re-export chain following** — same gap as `unimported-exports`; tracked in research notes.
+- **Property-access tracking** — would require a new substrate column on `calls` or a separate `property_reads` table; not on the v1 roadmap.
+- **Component prop usage** — for React props, [`components-by-hooks`](./components-by-hooks.md) gives hook usage; per-prop reference is the same property-access gap.
diff --git a/templates/recipes/unused-type-members.sql b/templates/recipes/unused-type-members.sql
new file mode 100644
index 0000000..d9f27f9
--- /dev/null
+++ b/templates/recipes/unused-type-members.sql
@@ -0,0 +1,28 @@
+-- Advisory: members of exported types with no detectable importer.
+-- Field-level cousin of `unimported-exports`. Caveats (indexed access,
+-- keyof, mapped types, destructuring, re-export chains) live in the .md.
+WITH imported_type_names AS (
+  SELECT DISTINCT spec.value AS name
+  FROM imports i
+  CROSS JOIN json_each(i.specifiers) spec
+  WHERE spec.value != '*'
+),
+unimported_exported_types AS (
+  SELECT DISTINCT e.name, e.file_path
+  FROM exports e
+  WHERE e.is_default = 0
+    AND e.kind != 're-export'
+    AND e.name NOT IN (SELECT name FROM imported_type_names)
+)
+SELECT
+  tm.symbol_name AS owner_type,
+  tm.name AS member,
+  tm.type AS member_type,
+  tm.is_optional,
+  tm.is_readonly,
+  tm.file_path
+FROM type_members tm
+JOIN unimported_exported_types u
+  ON u.name = tm.symbol_name AND u.file_path = tm.file_path
+ORDER BY tm.file_path, tm.symbol_name, tm.name
+LIMIT 50;