docs: sync CLI and agent docs with shipped capabilities.

README and --help now cover apply, skill/rule, audit, and MCP resources;
lessons and agent rules use the pointer-protocol maintenance model and
.codemap/index.db paths; clean script preserves .codemap/ after consolidation.

Author: SutuSebastian

.agents/lessons.md

@@ -8,8 +8,8 @@ Each entry is a single bullet: `- **<topic>** — <lesson>`. Newest entries at t
 
 ## Lessons
 
-- **changesets bump policy (pre-v1)** — while in `0.x`, default to **patch** for everything (additive features, fixes, docs, internal refactors); reserve **minor** for schema-breaking changes that force a `.codemap.db` rebuild (matches 0.2.0 precedent: new tables/columns/`SCHEMA_VERSION` bump). Strict SemVer kicks in only after `1.0.0`. Don't propose `minor` just because new CLI commands or public types were added.
-- **agent rule + skill maintenance** — when shipping a CLI flag, recipe id, recipe `actions` template, schema column, or any agent-queryable surface, update **both** copies of the codemap rule + skill in the **same PR** per [docs/README.md Rule 10](../docs/README.md): `templates/agents/rules/codemap.md` + `templates/agents/skills/codemap/SKILL.md` (ships to npm) **and** `.agents/rules/codemap.md` + `.agents/skills/codemap/SKILL.md` (this clone's mirror). Drift between the two pairs should be CLI-prefix-only (`codemap` vs `bun src/index.ts`). Forgetting this leaves installed agents with a stale view of the CLI — that's how `--summary` / `--changed-since` / `--group-by` / `actions` / `symbols.visibility` shipped without any `templates/agents/` mention until PR #29 retro-fixed it.
+- **changesets bump policy (pre-v1)** — while in `0.x`, default to **patch** for everything (additive features, fixes, docs, internal refactors); reserve **minor** for schema-breaking changes that force a `.codemap/index.db` rebuild (matches 0.2.0 precedent: new tables/columns/`SCHEMA_VERSION` bump). Strict SemVer kicks in only after `1.0.0`. Don't propose `minor` just because new CLI commands or public types were added.
+- **agent-content maintenance (pointer protocol)** — when shipping a CLI flag, recipe id, recipe `actions` template, schema column, or any agent-queryable surface, follow [docs/README.md Rule 10](../docs/README.md) in the **same PR**: (1) **recipes** → `templates/recipes/*.{sql,md}` (auto-flows via `20-recipes.gen.md`); (2) **schema** → `src/db.ts` (auto-flows via `30-schema.gen.md`); (3) **narrative** (flags, MCP/HTTP tools, output shapes) → hand-written `templates/agent-content/skill/*.md`; (4) **pointer shape** only → `templates/agents/{rules/codemap,skills/codemap/SKILL}.md` + bump `EXPECTED_POINTER_VERSION` in `agent-content.ts`. Consumer pointers in `.agents/` regenerate via `bun src/index.ts agents init --force` when shape changes — no fat dual-copy sync. Pre-pointer mistake: editing only `.agents/` and leaving served content stale.
 - **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.

.agents/rules/agents-tier-system.md

@@ -51,7 +51,7 @@ Today's Tier-2 rules:
 
 Pure intent-triggered. The skill description is detailed enough that Cursor surfaces it on relevant phrases. No always-on cost.
 
-Skills stay rule-less when the work is **explicitly invoked** by the user, not pattern-triggered. Today: `audit-pr-architecture`, `diagnose`, `docs-governance`, `docs-lifecycle-sweep`, `grill-me`, `improve-codebase-architecture`, `write-a-skill`. (Skills like `gritql-codemods` and `ubiquitous-language` would also fit this tier if adopted.)
+Skills stay rule-less when the work is **explicitly invoked** by the user, not pattern-triggered. Today: `audit-pr-architecture`, `diagnose`, `docs-governance`, `docs-lifecycle-sweep`, `grill-me`, `improve-codebase-architecture`, `pr-comment-fact-check`, `write-a-skill`. (Skills like `gritql-codemods` and `ubiquitous-language` would also fit this tier if adopted.)
 
 ## Authoring guidelines
 

.agents/rules/tracer-bullets.md

@@ -22,8 +22,8 @@ AI agents tend to produce complete solutions in one leap — all parsers, all sc
 
 A typical vertical slice for Codemap touches these layers top-to-bottom:
 
-1. **CLI / orchestration** — `src/index.ts` (args, incremental vs full, `query` subcommand)
-2. **Workers / parsing** — `src/parse-worker.ts`, `src/parser.ts`, `src/css-parser.ts`
+1. **CLI / orchestration** — `src/cli/` (`bootstrap.ts`, `main.ts`, lazy `cmd-*` chunks; entry `src/index.ts`)
+2. **Workers / parsing** — `src/parse-worker.ts` / `parse-worker-node.ts`, `parse-worker-core.ts`, `src/parser.ts`, `src/css-parser.ts`, `src/adapters/`
 3. **Persistence** — `src/db.ts` (schema, inserts, `SCHEMA_VERSION`)
 4. **Config / runtime** — `src/config.ts`, `src/runtime.ts`, resolver
 5. **Tests** — `src/*.test.ts`
@@ -38,7 +38,7 @@ Bad — building in layers:
 
 Good — tracer bullet:
 
-1. **`constants` + parser language** — `LANG_MAP` + `extractFileData` / worker `TS_EXTENSIONS` — commit, `bun run check`, small test parsing a one-line file
+1. **`constants` + adapter** — `LANG_MAP` + builtin adapter extensions + `extractFileData` — commit, `bun run check`, small test parsing a one-line file
 2. **Resolver** — `resolver` extensions if needed — commit, validate
 3. **Docs** — `docs/architecture.md` table row — commit, validate
 

.agents/skills/diagnose/SKILL.md

@@ -19,7 +19,7 @@ Spend disproportionate effort here. **Be aggressive. Be creative. Refuse to give
 
 1. **Failing test** at whatever seam reaches the bug — unit, integration, e2e. Codemap convention: `src/**/<name>.test.ts` for unit + integration; `fixtures/golden/` for query-shape regressions; `bun test <file>` runs them.
 2. **CLI invocation** with a fixture input, diffing stdout against a known-good snapshot. Examples: `bun src/index.ts query --json …` against `fixtures/minimal/`, golden runner under `scripts/query-golden.ts`.
-3. **Replay a captured trace.** Save a real `.codemap.db` / config / fixture file to disk; replay it through the code path in isolation.
+3. **Replay a captured trace.** Save a real `.codemap/index.db` / config / fixture file to disk; replay it through the code path in isolation.
 4. **Throwaway harness.** Spin up a minimal subset (one parser, one DB connection) that exercises the bug code path with a single function call.
 5. **Property / fuzz loop.** If the bug is "sometimes wrong output", run 1000 random inputs and look for the failure mode.
 6. **Bisection harness.** If the bug appeared between two known states (commit, dataset, version), automate "boot at state X, check, repeat" so you can `git bisect run` it.
@@ -44,7 +44,7 @@ The goal is not a clean repro but a **higher reproduction rate**. Loop the trigg
 
 ### When you genuinely cannot build a loop
 
-Stop and say so explicitly. List what you tried. Ask the user for: (a) access to whatever environment reproduces it, (b) a captured artifact (HAR file, log dump, core dump, screen recording with timestamps, broken `.codemap.db`), or (c) permission to add temporary instrumentation. Do **not** proceed to hypothesise without a loop.
+Stop and say so explicitly. List what you tried. Ask the user for: (a) access to whatever environment reproduces it, (b) a captured artifact (HAR file, log dump, core dump, screen recording with timestamps, broken `.codemap/index.db`), or (c) permission to add temporary instrumentation. Do **not** proceed to hypothesise without a loop.
 
 Do not proceed to Phase 2 until you have a loop you believe in.
 

.agents/skills/pr-comment-fact-check/SKILL.md

@@ -165,7 +165,7 @@ These come up repeatedly with LLM reviewers and warrant extra scrutiny. The code
 7. **Memory-leak / resource-leak claims with no concrete trigger** — "this could leak the SQLite handle" without a scenario is speculation; ask for the path. Codemap closes DB handles via the `using` pattern in most call sites — verify before accepting.
 8. **Type-safety alarms** — if `tsgo --noEmit` (`bun run typecheck`) passes, the claim is almost always wrong (or about runtime behaviour the type system can't see, in which case the reviewer should justify with the runtime case).
 9. **Convention citations that don't exist** — "This breaks our API conventions" — grep `.agents/` and `docs/` for the convention. If it's not codified, it's preference, not rule.
-10. **Schema-bump / changeset alarms** — "this needs a minor changeset" — check [`.agents/lessons.md`](../../lessons.md) ("changesets bump policy"): pre-v1, default is patch unless the schema actually breaks the `.codemap.db` (new tables/columns/SCHEMA_VERSION bump). Don't accept "minor for new CLI commands or public types".
+10. **Schema-bump / changeset alarms** — "this needs a minor changeset" — check [`.agents/lessons.md`](../../lessons.md) ("changesets bump policy"): pre-v1, default is patch unless the schema actually breaks `.codemap/index.db` (new tables/columns/`SCHEMA_VERSION` bump). Don't accept "minor for new CLI commands or public types".
 
 ## Anti-patterns
 

.github/CONTRIBUTING.md

@@ -14,7 +14,7 @@ bun test
 bun run test:golden   # golden SQL vs fixtures/minimal (also runs at end of `bun run check`)
 bun run test:golden:external   # Tier B: local tree via CODEMAP_ROOT / --root (not in CI)
 bun run check   # format + lint + tests + typecheck + build + test:golden
-bun run clean   # remove untracked/ignored build artifacts (keeps `.env`, `.codemap.db*`)
+bun run clean   # remove untracked/ignored build artifacts (keeps `.env`, `.codemap/`)
 bun run check-updates   # interactive dependency updates (`bun update -i --latest`)
 ```
 

README.md

@@ -55,6 +55,7 @@ codemap context --compact --for "refactor auth"              # JSON envelope + i
 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
+codemap apply rename-preview --params old=foo,new=bar --dry-run  # preview recipe-driven edits (substrate executor)
 ```
 
 **Version-matched agent guidance:** `codemap agents init` writes **thin pointer files** to `.agents/` (~16-line SKILL.md + ~22-line rule). The full content is served live by **`codemap skill`** / **`codemap rule`** (CLI) and **`codemap://skill`** / **`codemap://rule`** (MCP / HTTP) — so `bun update @stainless-code/codemap` auto-refreshes the content agents see, no re-init needed. See [docs/agents.md](docs/agents.md).
@@ -197,11 +198,23 @@ codemap impact runWatchLoop --json --summary | jq '.summary.nodes'  # CI-gate fa
 # (default 3, --depth 0 = unbounded), limit-capped (default 500). Result envelope:
 # {target, matches: [{depth, edge, kind, name?, file_path}], summary: {nodes, terminated_by}}.
 
+# Apply — substrate-shaped fix executor (recipe SQL describes hunks; codemap validates + writes)
+codemap apply rename-preview --params old=usePermissions,new=useAccess,kind=function --dry-run
+codemap apply rename-preview --params old=usePermissions,new=useAccess,kind=function --yes   # TTY prompts without --yes
+# Consumes the --format diff-json row contract ({file_path, line_start, before_pattern, after_pattern}).
+# All-or-nothing: any conflict aborts before any file is written. Pair with --format diff-json preview first.
+
+# Live agent content (pointer protocol — full body served from installed package version)
+codemap skill                                                   # full codemap SKILL markdown to stdout
+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: 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
-# Resources: codemap://schema, codemap://skill, codemap://rule (lazy-cached); codemap://recipes, codemap://recipes/{id} (live read-per-call — keep recency fresh)
+#        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);
+#            codemap://files/{path}, codemap://symbols/{name} (live per-file / per-symbol roll-ups)
 # Output shape verbatim from `--json` envelopes (no re-mapping). Snake_case throughout.
 
 # Another project

package.json

@@ -50,7 +50,7 @@
     "check-updates": "bun update -i --latest",
     "check:perf-baseline": "bun scripts/check-perf-baseline.ts",
     "check:perf-baseline:update": "bun scripts/check-perf-baseline.ts --update",
-    "clean": "git clean -xdf -e .env -e .codemap.db -e .codemap.db-wal -e .codemap.db-shm",
+    "clean": "git clean -xdf -e .env -e .codemap",
     "dev": "bun src/index.ts",
     "fix": "bun run lint:fix && bun run format",
     "format": "oxfmt",

src/cli/bootstrap.ts

@@ -29,8 +29,15 @@ Validate (compare on-disk SHA-256 to indexed hash):
 Context (project snapshot envelope for any agent):
   codemap context [--compact] [--for "<intent>"]
 
+Audit (structural drift — baseline snapshots or git ref):
+  codemap audit [--baseline <prefix>] [--base <ref>] [--json] [--ci] ...
+
 Agents:
   codemap agents init [--force] [--interactive|-i]
+  codemap skill · codemap rule              # live full markdown (pointer protocol)
+
+PR comment renderer (audit/SARIF → markdown summary):
+  codemap pr-comment <file> [--shape audit|sarif] [--json]   # - for stdin
 
 MCP server (Model Context Protocol — for agent hosts):
   codemap mcp                                        # stdio JSON-RPC, one tool per CLI verb