docs: fact-check sweep — align docs and CLI help with shipped behavior (#145)

* docs: lifecycle sweep — retire P1 agent-surface plans, fact-check references

P1 agent-surface plans are complete; lift status to roadmap and fix stale
schema, MCP, validate, and index-path claims across docs and agent templates.

* docs: second sweep — type_heritage, MCP metadata, index paths

Add type_heritage to served rule and roadmap substrate inventory, align MCP
tool/resource descriptions and CLI help with index.db paths and validate behavior.

* docs: third sweep — recipe catalog is bundled + project-local

Align agent templates, README, packaging, glossary, and MCP metadata with
recipes-loader behavior; fix Tier 11 glossary anchor suffix.

* docs: fourth sweep — agent strings, paths, index.db comments

Fix MCP tool/resource descriptions, CLI help/JSDoc, audit cache comments,
research doc relative paths, and non-goals MCP resource citation.

* docs: fifth sweep — complete MCP/HTTP help, recency write paths

List all 17 tools and mcp-instructions in cmd-mcp/cmd-serve help, fix schema
cache wording, recipe_recency write-path docs, and skill assembly cache notes.

* docs: sixth sweep — CLI help, audit --ci, resource cache split

Fix bundled-only recipe help text, audit --ci exit behavior, default-ON
watch wording, and skill resource freshness contract.

* docs: seventh sweep — README MCP line, schema.gen cache note

Align README quick-start comments and schema.gen fallback with 17-tool
MCP surface and codemap://schema lazy-cache behavior.

* docs: final sweep — audit archive extract, in-process watcher

Replace stale worktree/co-process wording with git archive + tar -x audit
cache semantics and in-process chokidar watch behavior.

* docs: eighth sweep — audit seam, HTTP shipped, error strings

Fix architecture audit wiring cross-ref, non-goals transport wording,
stale MCP-only HTTP JSDoc, and user-facing audit error messages.

* docs: ninth sweep — transport envelopes, state-dir paths, audit --ci

Fact-check passes 9–19: per-tool JSON shapes (not uniform query --json),
no-CLI-verb tools on MCP+HTTP, audit-cache vs state-dir, query --ci quiet
split, assembled resources, and related CLI/help string fixes.

* docs: address CodeRabbit PR #145 — MCP wiring, anchor, JSON example

Fact-checked 4/5 bot comments; push back on false-positive GitHub
capitalization (Actions expression github.base_ref is correct).

Author: SutuSebastian

README.md

@@ -47,7 +47,7 @@ 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 --recipe fan-out                        # recipe SQL by 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
@@ -124,11 +124,11 @@ codemap audit --baseline base --files-baseline hotfix-files     # mixed — auto
 codemap audit --baseline base --no-index                        # skip the auto-incremental-index prelude (frozen-DB CI)
 codemap audit --base origin/main --json                         # ad-hoc — archive+reindex against any committish; no --save-baseline needed
 codemap audit --base origin/main --format sarif                 # emit SARIF 2.1.0 directly (Code Scanning); also: --ci alias
-codemap audit --base origin/main --ci                           # CI shortcut: --format sarif + non-zero exit on additions + quiet
+codemap audit --base origin/main --ci                           # CI shortcut: --format sarif + non-zero exit on additions
 codemap audit --base v1.0.0 --files-baseline pre-release-files  # mix --base with per-delta override
 # --base materialises <ref> via `git archive | tar -x` to .codemap/audit-cache/<sha>/, reindexes into
-# a temp DB, then diffs. Cache hit on second run against same sha is sub-100ms. Requires git;
-# non-git projects get a clean `--base requires a git repository` error.
+# a cached `.codemap/index.db` at that sha, then diffs. Cache hit on second run against same sha is sub-100ms. Requires git;
+# non-git projects get a clean `codemap audit: --base requires a git repository.` error.
 # Recipes that define per-row action templates append "actions" hints (kebab-case verb +
 # description) in --json output; ad-hoc SQL never carries actions. Inspect via --recipes-json.
 # --format <text|json|sarif|annotations|mermaid|diff|diff-json> — pipe results into GitHub Code Scanning
@@ -169,7 +169,7 @@ codemap serve --port 7878             # default-ON watcher
 codemap watch --quiet                 # standalone (decoupled from a transport)
 codemap mcp --no-watch                # opt out for one-shot fire-and-forget calls
 CODEMAP_WATCH=0 codemap mcp           # env-var opt-out (mirrors --no-watch)
-# List bundled recipes as JSON, or print one recipe's SQL (no DB required)
+# List recipe catalog (bundled + project-local) as JSON, or print one recipe's SQL (no DB required)
 codemap query --recipes-json
 codemap query --print-sql fan-out
 # `components-by-hooks` ranks by hook count without SQLite JSON1 (comma-based count on the stored JSON array).
@@ -221,12 +221,12 @@ codemap skill                                                   # full codemap S
 codemap rule                                                    # full codemap rule markdown to stdout
 
 # MCP server (Model Context Protocol) — for agent hosts (Claude Code, Cursor, Codex, generic MCP clients)
-codemap mcp                                                     # JSON-RPC on stdio; one tool per CLI verb plus query_batch
-# Tools (17): query, query_batch (MCP-only), query_recipe, audit, save_baseline,
+codemap mcp                                                     # JSON-RPC on stdio (17 tools; watcher default-ON)
+# Tools (17): query, query_batch (no CLI verb), query_recipe, audit, save_baseline,
 #        list_baselines, drop_baseline, context, validate, show, snippet, impact,
 #        affected, trace, explore, node, apply
-# MCP-only (no CLI verb): query_batch, trace, explore, node. Other tools mirror a CLI --json envelope.
-# Resources: codemap://schema, codemap://skill, codemap://rule (lazy-cached);
+# No CLI verb (MCP + HTTP): query_batch, trace, explore, node. Other tools mirror a CLI --json envelope.
+# Resources: codemap://schema, codemap://skill, codemap://rule, codemap://mcp-instructions (lazy-cached);
 #            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.

docs/README.md

@@ -37,7 +37,7 @@ codemap agents init --no-git-hooks    # remove codemap hook blocks
 
 ## Git and `.gitignore`
 
-Codemap maintains its own self-managed **`<state-dir>/.gitignore`** (default `.codemap/.gitignore`) — a blacklist of generated artifacts (`index.db` + WAL/SHM, `audit-cache/`) reconciled to canonical on every codemap boot via `ensureStateGitignore` (`src/application/state-dir.ts`). Project-tracked sources (`recipes/`, `config.{ts,js,json}`) default to tracked.
+Codemap maintains its own self-managed **`<state-dir>/.gitignore`** (default `.codemap/.gitignore`) — a blacklist of generated artifacts (`index.db` + WAL/SHM, `audit-cache/` entry in the canonical list) reconciled to canonical on every codemap boot via `ensureStateGitignore` (`src/application/state-dir.ts`). **`audit --base` cache** physically lives at `<projectRoot>/.codemap/audit-cache/` (hardcoded; does not follow `--state-dir`). Project-tracked sources (`recipes/`, `config.{ts,js,json}`) default to tracked.
 
 The user's root **`.gitignore`** is no longer touched by `codemap agents init`. Future codemap versions can add new generated artifacts to the canonical blacklist; every consumer's project repairs itself on the next `codemap` invocation. **The setup logic IS the migration** (per plan §D11).
 
@@ -79,7 +79,7 @@ Append alone would duplicate on every run — markers + replace are what prevent
 
 ## Live fetch surface (CLI + MCP + HTTP)
 
-Once `agents init` has written the pointer templates, the consumer's disk holds 12–20 lines per file. The actual content is served live:
+Once `agents init` has written the pointer templates, the consumer's disk holds ~16-line SKILL + ~23-line rule. The actual content is served live:
 
 | Surface                | Skill                                                    | Rule                                                    |
 | ---------------------- | -------------------------------------------------------- | ------------------------------------------------------- |