docs: resolve R.4–R.9 fact-check residuals

Add benchmark snapshot callout, clarify index-summary tables, drop fragile
recipe link, document CODEMAP_STATE_DIR/CODEMAP_WATCH, and note substrate
ship-date semantics plus non-goals section numbering.

Author: SutuSebastian

README.md

@@ -234,7 +234,7 @@ codemap agents init --force
 codemap agents init --interactive   # -i; IDE wiring + symlink vs copy
 ```
 
-**Environment / flags:** `--root` overrides **`CODEMAP_ROOT`** / **`CODEMAP_TEST_BENCH`**, then **`process.cwd()`**. Indexing a project outside this clone: [docs/benchmark.md § Indexing another project](docs/benchmark.md#indexing-another-project).
+**Environment / flags:** `--root` overrides **`CODEMAP_ROOT`** / **`CODEMAP_TEST_BENCH`**, then **`process.cwd()`**; **`--state-dir`** overrides **`CODEMAP_STATE_DIR`** (default `.codemap/`); **`CODEMAP_WATCH=0`** opts out of the default-ON watcher on `mcp` / `serve` (mirrors `--no-watch`). Indexing a project outside this clone: [docs/benchmark.md § Indexing another project](docs/benchmark.md#indexing-another-project).
 
 **Configuration:** optional **`<state-dir>/config.{ts,js,json}`** (default `.codemap/config.*`; default export object or async factory). Shape: [codemap.config.example.json](codemap.config.example.json). Runtime validation (**Zod**, strict keys) and API surface: [docs/architecture.md § User config](docs/architecture.md#user-config). When developing inside this repo you can use `defineConfig` from `@stainless-code/codemap` or `./src/config`. If you set **`include`**, it **replaces** the default glob list entirely. **Self-healing files (D11):** `<state-dir>/.gitignore` is rewritten to canonical on every codemap boot; JSON config gets unknown-key pruning + key-sort drift; TS/JS configs are validate-only.
 

docs/audits/2026-05-24-docs-fact-check-residuals.md

@@ -1,6 +1,6 @@
 # Docs fact-check residuals — 2026-05-24
 
-**Status:** Open — low-priority items deferred after the May 2026 full `.md` audit.
+**Status:** Open — code items R.1–R.3 remain; doc-only R.4–R.9 fixed in follow-up commits on `main`.
 
 **Scope:** ~129 markdown files under `docs/`, `.agents/`, `templates/`, root, and `.github/`. Parent verification on `main` through `0f7e6fc`.
 
@@ -14,7 +14,7 @@ This audit follows [docs/README.md Rule 6](../README.md) and [docs/README.md Rul
 
 ## TL;DR
 
-The audit corrected stale/wrong prose without dropping load-bearing design. **11 residual items** remain — mostly code/doc drift and STYLE nits. None block releases; three want code changes when touched next.
+The audit corrected stale/wrong prose without dropping load-bearing design. **Doc-only nits (R.4–R.9) are fixed.** **Three code/doc drift items (R.1–R.3)** remain — none block releases.
 
 ---
 
@@ -28,16 +28,16 @@ The audit corrected stale/wrong prose without dropping load-bearing design. **11
 | **R.2** | **`function_params.owner_kind` never varies.** Recipe doc updated; extractor always passes `"function"`.                                                                                                                            | `pushParams()` default in `src/extractors/params.ts`; all call sites omit `ownerKind`.                                | Populate distinct values (`method`, `arrow`, `constructor`, …) at extraction sites, then restore filter docs on `find-by-param-type`.            | M                  |
 | **R.3** | **MCP stdio does not register `codemap://files/{path}` / `codemap://symbols/{name}`.** README and glossary correctly scope these to HTTP `GET /resources/{uri}`; `readResource()` supports them but `registerResources()` does not. | `src/application/mcp-server.ts` vs `src/application/resource-handlers.ts`.                                            | Either register as MCP resource templates (parity with HTTP) or keep HTTP-only and ensure agent-content skill states the split (done in README). | S (if registering) |
 
-### Doc-only (STYLE / accuracy nits)
+### Doc-only — fixed
 
-| ID      | Finding                                                                                         | Location                                          | Suggested fix                                                                                 |
-| ------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------- | --------------------------------------------------------------------------------------------- |
-| **R.4** | Example timing tables will drift.                                                               | `docs/benchmark.md` Results section               | Optional callout: regenerate via `bun src/benchmark.ts`; numbers are snapshots, not CI-gated. |
-| **R.5** | "Main tables" copy counts five tables; index has more.                                          | `templates/recipes/index-summary.md` description  | Say "core tables" or list which five; or point at `index-summary.sql`.                        |
-| **R.6** | Relative `./unimported-exports.md` link may not resolve in MCP/`--recipes-json` body consumers. | `templates/recipes/unused-type-members.md`        | Use recipe id prose only, or absolute path in bundled context if a consumer breaks.           |
-| **R.7** | Root README env block omits `CODEMAP_STATE_DIR`, `CODEMAP_WATCH`.                               | `README.md` Configuration inline block            | One-line mention if users hit custom state-dir or watch opt-out often.                        |
-| **R.8** | Substrate plan ship dates mix 2026-05-14 / 15 / 19.                                             | `docs/plans/substrate-extraction.md` tier headers | Normalize to wave date where one SCHEMA bump covers multiple tiers.                           |
-| **R.9** | Research note jumps §3 → §5 → §7 (§4/§6 lifted).                                                | `docs/research/non-goals-reassessment-2026-05.md` | Optional one-line TOC note: "§4/§6 lifted to roadmap/plans."                                  |
+| ID      | Finding                                    | Fix                                                                      |
+| ------- | ------------------------------------------ | ------------------------------------------------------------------------ |
+| **R.4** | Example timing tables will drift           | `docs/benchmark.md` § Results — snapshot / regenerate callout            |
+| **R.5** | "Main tables" copy ambiguous               | `templates/recipes/index-summary.md` — names five tables + points at SQL |
+| **R.6** | Relative recipe link in MCP context        | `templates/recipes/unused-type-members.md` — recipe id prose only        |
+| **R.7** | README env block omitted state-dir / watch | `README.md` Environment / flags — `CODEMAP_STATE_DIR`, `CODEMAP_WATCH`   |
+| **R.8** | Substrate plan ship dates mixed            | `docs/plans/substrate-extraction.md` header — wave vs per-PR date note   |
+| **R.9** | Research note § numbering gap              | `docs/research/non-goals-reassessment-2026-05.md` — §4/§6 lifted note    |
 
 ### Already tracked elsewhere (no new work)
 
@@ -51,6 +51,6 @@ The audit corrected stale/wrong prose without dropping load-bearing design. **11
 
 ## Closing criteria
 
-Delete this file when **R.1–R.3** are resolved or explicitly rejected with a one-line decision in `roadmap.md`, and **R.4–R.9** are either fixed or accepted as intentional. Index closure in [`roadmap.md` § Closed audits (pointers)](../roadmap.md#closed-audits-pointers).
+Delete this file when **R.1–R.3** are resolved or explicitly rejected with a one-line decision in `roadmap.md`. Index closure in [`roadmap.md` § Closed audits (pointers)](../roadmap.md#closed-audits-pointers).
 
 Recover the full May 2026 audit agent reports via conversation / commit diffs at `f25f8a6..0f7e6fc` if needed.

docs/benchmark.md

@@ -145,6 +145,8 @@ This document measures **indexed SQL vs traditional glob/read** on an existing d
 
 ### Results
 
+**Snapshot only — not CI-gated.** Regenerate with `bun src/benchmark.ts` (or `bun src/index.ts benchmark`) after reindexing; numbers vary by machine, thermal state, and tree size.
+
 Example snapshot from `bun src/benchmark.ts` immediately after `bun src/index.ts --full` on **this repository** (small tree; many scenario counts are zero). Numbers vary by machine and project. Schema, indexes, and content fingerprints: [architecture.md § Schema](./architecture.md#schema).
 
 | Scenario                                | Index Time | Results | Trad. Time | Results | Files Read | Bytes Read | Speedup  |

docs/plans/substrate-extraction.md

@@ -2,7 +2,7 @@
 
 > **Status:** open (tiers **7–13**) · plan iterating in parallel with the broader [`research/codemap-richer-index-synthesis-2026-05.md`](../research/codemap-richer-index-synthesis-2026-05.md) write-engine direction.
 >
-> **Per-tier ship status (fact-checked 2026-05-19):** Tiers **1–6** remainder shipped (`SCHEMA_VERSION` **34**). Tier **1**: call-shape columns, side-effect `import_specifiers` + `import_id`. Tier **2**: `bindings.resolution_kind='re-exported'`. Tier **3**: `jsx_elements` / `jsx_attributes`. Tier **5**: `async_calls`, `try_catch`, `decorators`, `jsdoc_tags`. Tier **4** partial: `symbols.{return_type,is_async,is_generator}`; `generic_params` / `type_predicates` deferred. Tier **6** partial: `dynamic_imports`, `files.{is_barrel,has_side_effects}`; `files.is_entry` deferred to [`c9-plugin-layer.md`](./c9-plugin-layer.md). Tiers **7–13** open.
+> **Per-tier ship status (fact-checked 2026-05-19):** Tiers **1–6** remainder shipped (`SCHEMA_VERSION` **34**). Tier headings carry the PR landing date for that slice; the SCHEMA 34 remainder wave closed **2026-05-19** (tiers 1–6 foundation landed **2026-05-14**–**15**). Tier **1**: call-shape columns, side-effect `import_specifiers` + `import_id`. Tier **2**: `bindings.resolution_kind='re-exported'`. Tier **3**: `jsx_elements` / `jsx_attributes`. Tier **5**: `async_calls`, `try_catch`, `decorators`, `jsdoc_tags`. Tier **4** partial: `symbols.{return_type,is_async,is_generator}`; `generic_params` / `type_predicates` deferred. Tier **6** partial: `dynamic_imports`, `files.{is_barrel,has_side_effects}`; `files.is_entry` deferred to [`c9-plugin-layer.md`](./c9-plugin-layer.md). Tiers **7–13** open.
 >
 > **Motivator:** Codemap's distinctive value is the SQL-against-structural-index substrate. Per [Moat B](../roadmap.md#moats-load-bearing) — _"Extracted structure ≥ verdicts. Schema breadth is the substrate every recipe layers on."_ — the load-bearing growth axis is **what oxc / Lightning CSS / config loaders give us that the index doesn't yet expose.** Tiers **1–6** shipped (`SCHEMA_VERSION` **34**): position-precise calls/imports/exports, `references` / `scopes` / `bindings`, JSX, behavioral facts, module-graph flags, and more — see [architecture § Schema](../architecture.md#schema). **Tiers 7–13** below still enumerate CSS rule depth, project meta, ORM/SQL tracking, and other AST surfaces we discard at parse time today. Each remaining tier ships as an independent tracer-bullet PR that compounds into a maximal substrate.
 >

docs/research/non-goals-reassessment-2026-05.md

@@ -8,6 +8,8 @@
 >
 > **Implementation check (2026-05-18):** Most lifted items are now shipped. Remaining open surfaces are C.9 reachability (`files.is_entry` absent), LSP diagnostic-push, `history`, `symbols.body_hash`, and GitHub Marketplace Action publishing/listing. The Action's core wrapper, audit SARIF/`--ci`, and PR-comment summary path have shipped in-tree. `unused-type-members` has since shipped despite older wording below still describing § 1.6 as pending.
 
+> **Section numbering:** §4 and §6 were lifted to [`roadmap.md`](../roadmap.md) and plan PRs; headings jump 3→5→7 intentionally.
+
 ---
 
 ## 0. Reframing question

docs/roadmap.md

@@ -52,7 +52,7 @@ Soft constraints — describe shipped reality. Decided-but-unshipped flips live
 
 ## Backlog
 
-- [ ] **Docs fact-check residuals (2026-05-24)** — low-priority drift from the full `.md` audit (`e6ab158`–`0f7e6fc`): project-recipes + `--state-dir` loader (R.1), `owner_kind` extraction (R.2), optional MCP `files`/`symbols` resource registration (R.3), plus six STYLE doc nits. Audit: [`audits/2026-05-24-docs-fact-check-residuals.md`](./audits/2026-05-24-docs-fact-check-residuals.md). Effort: S–M per item.
+- [ ] **Docs fact-check residuals (2026-05-24)** — code drift from the full `.md` audit: project-recipes + `--state-dir` loader (R.1), `owner_kind` extraction (R.2), optional MCP `files`/`symbols` resource registration (R.3). Doc-only items fixed. Audit: [`audits/2026-05-24-docs-fact-check-residuals.md`](./audits/2026-05-24-docs-fact-check-residuals.md). Effort: S–M per item.
 - [ ] **`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 — publish + listing finish** — core Action implementation is in-tree: root `action.yml`, `query --ci`, `audit --format sarif` / `--ci`, package-manager detection, dogfood smoke, and opt-in `pr-comment` summary renderer have shipped. Remaining work is the release/listing slice: `MARKETPLACE.md`, `v1.0.0` / floating `v1` tags, Marketplace setup, sacrificial-repo smoke, and making `action-smoke` blocking once the Action tag exists. Action version stream is independent of CLI version (`package.json` currently drives CLI/npm version; Action publishes at its own `v1.0.0`). Plan: [`plans/github-marketplace-action.md`](./plans/github-marketplace-action.md). Effort: S.

templates/recipes/index-summary.md

@@ -1 +1 @@
-Single row: row counts for main tables (quick health snapshot)
+Single row: row counts for `files`, `symbols`, `imports`, `components`, and `dependencies` (five core tables — see `index-summary.sql`)

templates/recipes/unused-type-members.md

@@ -5,7 +5,7 @@ actions:
     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.
+Field-level enumeration of types that are **exported but never directly imported** anywhere in the project. Sister recipe to **`unimported-exports`**: 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