stainless-code · SutuSebastian · May 25, 2026 · May 25, 2026 · May 25, 2026 · May 25, 2026
diff --git a/README.md b/README.md
@@ -213,8 +213,8 @@ codemap mcp                                                     # JSON-RPC on st
 # Tools: query, query_batch (MCP-only — N statements in one round-trip), query_recipe, audit,
 #        save_baseline, list_baselines, drop_baseline, context, validate, show, snippet, impact, apply
 # Resources: codemap://schema, codemap://skill, codemap://rule (lazy-cached);
-#            codemap://recipes, codemap://recipes/{id} (live read-per-call — recency fields stay fresh)
-# HTTP-only resources (via `codemap serve` GET /resources/{uri}): codemap://files/{path}, codemap://symbols/{name}
+#            codemap://recipes, codemap://recipes/{id} (live read-per-call — recency fields stay fresh);
+#            codemap://files/{path}, codemap://symbols/{name} (live read-per-call)
 # Output shape verbatim from `--json` envelopes (no re-mapping). Snake_case throughout.
 
 # Another project

diff --git 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. See folder contents for the current in-flight set; avoid maintaining a duplicate inline list.                                                                                                                                                                                                                                                                              |
-| [audits/](./audits/)                          | Targeted architecture / performance / lifecycle audits. Open: [`audits/2026-05-24-docs-fact-check-residuals.md`](./audits/2026-05-24-docs-fact-check-residuals.md). Closed audits indexed from [`roadmap.md` § Closed audits (pointers)](./roadmap.md#closed-audits-pointers).                                                                                                                                                                                                                        |
+| [audits/](./audits/)                          | Targeted architecture / performance / lifecycle audits. None open; closed audits indexed from [`roadmap.md` § Closed audits (pointers)](./roadmap.md#closed-audits-pointers).                                                                                                                                                                                                                                                                                                                         |
 | [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).                                                                                                                                                                                                                                                                |
 
 ---

diff --git a/docs/audits/2026-05-24-docs-fact-check-residuals.md b/docs/audits/2026-05-24-docs-fact-check-residuals.md
diff --git a/docs/glossary.md b/docs/glossary.md
@@ -353,7 +353,7 @@ Rust-based CSS parser (NAPI bindings). Codemap's `src/css-parser.ts` uses its vi
 
 ### `codemap mcp` / MCP server
 
-Stdio MCP (Model Context Protocol) server exposing codemap's structural-query surface to agent hosts (Claude Code, Cursor, Codex, generic MCP clients) as JSON-RPC tools — eliminates the bash round-trip on every agent invocation. v1 ships the query / audit / context / validate / show / snippet / impact / baseline / apply tool set, plus MCP resources for `codemap://schema`, `codemap://skill`, `codemap://rule`, `codemap://recipes`, and `codemap://recipes/{id}`. Resource freshness is split by contract: schema / skill / rule are lazy-cached per server process; recipes are live read-per-call so inline `last_run_at` / `run_count` recency fields don't freeze at first read. HTTP's `GET /resources/{encoded-uri}` uses the same resource handler and additionally serves direct `codemap://files/{path}` and `codemap://symbols/{name}` lookups. Tool input/output keys are snake_case — Codemap's convention, matching the patterns in MCP spec examples and reference servers (GitHub MCP, Cursor built-ins); the spec itself doesn't mandate it. CLI stays kebab — translation lives at the MCP-arg layer. Output shape is verbatim from the CLI's `--json` envelope (no re-mapping). Bootstrap once at server boot; tool handlers (in `application/tool-handlers.ts`) and resource handlers (in `application/resource-handlers.ts`) are pure transport-agnostic — the same handlers serve `codemap serve` (HTTP) via `POST /tool/{name}` and `GET /resources/{encoded-uri}`. Implementation: `src/cli/cmd-mcp.ts` (CLI shell) + `src/application/mcp-server.ts` (engine). See [`architecture.md` § MCP wiring](./architecture.md#cli-usage).
+Stdio MCP (Model Context Protocol) server exposing codemap's structural-query surface to agent hosts (Claude Code, Cursor, Codex, generic MCP clients) as JSON-RPC tools — eliminates the bash round-trip on every agent invocation. v1 ships the query / audit / context / validate / show / snippet / impact / baseline / apply tool set, plus MCP resources for `codemap://schema`, `codemap://skill`, `codemap://rule`, `codemap://recipes`, `codemap://recipes/{id}`, `codemap://files/{path}`, and `codemap://symbols/{name}`. Resource freshness is split by contract: schema / skill / rule are lazy-cached per server process; recipes, files, and symbols are live read-per-call so inline recency fields and index mutations under `--watch` don't freeze at first read. HTTP's `GET /resources/{encoded-uri}` uses the same resource handler. Tool input/output keys are snake_case — Codemap's convention, matching the patterns in MCP spec examples and reference servers (GitHub MCP, Cursor built-ins); the spec itself doesn't mandate it. CLI stays kebab — translation lives at the MCP-arg layer. Output shape is verbatim from the CLI's `--json` envelope (no re-mapping). Bootstrap once at server boot; tool handlers (in `application/tool-handlers.ts`) and resource handlers (in `application/resource-handlers.ts`) are pure transport-agnostic — the same handlers serve `codemap serve` (HTTP) via `POST /tool/{name}` and `GET /resources/{encoded-uri}`. Implementation: `src/cli/cmd-mcp.ts` (CLI shell) + `src/application/mcp-server.ts` (engine). See [`architecture.md` § MCP wiring](./architecture.md#cli-usage).
 
 ### `query_batch` (MCP-only tool)
 

diff --git a/docs/roadmap.md b/docs/roadmap.md
@@ -52,7 +52,6 @@ Soft constraints — describe shipped reality. Decided-but-unshipped flips live
 
 ## Backlog
 
-- [ ] **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.
@@ -74,9 +73,10 @@ Soft constraints — describe shipped reality. Decided-but-unshipped flips live
 
 Closed audit content is consolidated into its canonical home (plan, reference doc, or `.agents/lessons.md`) per [docs/README.md Rule 8](./README.md). Recover full text via `git log --follow` on the deleted path.
 
-| Topic                                                      | Canonical home                                                                         | Closed                 |
-| ---------------------------------------------------------- | -------------------------------------------------------------------------------------- | ---------------------- |
-| Perf triangulation (per-model audits + triangulation file) | [`plans/perf-triangulation-rollout.md`](./plans/perf-triangulation-rollout.md) Phase 5 | 2026-05-18 (`cc28bce`) |
+| Topic                                                      | Canonical home                                                                                                                                                                                                                                     | Closed                 |
+| ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
+| Full `.md` fact-check (May 2026)                           | Shipped: audit fixes `e6ab158`–`14d3efc` on `main`, R.1–R.3 in this PR. R.10–R.12 always in [`roadmap.md` Backlog](./roadmap.md#backlog) / plans. Recover deleted audit: `git log --follow -- docs/audits/2026-05-24-docs-fact-check-residuals.md` | 2026-05-24             |
+| Perf triangulation (per-model audits + triangulation file) | [`plans/perf-triangulation-rollout.md`](./plans/perf-triangulation-rollout.md) Phase 5                                                                                                                                                             | 2026-05-18 (`cc28bce`) |
 
 - [ ] **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)