diff --git a/.agents/lessons.md b/.agents/lessons.md
index d9722cd..579fe2b 100644
--- a/.agents/lessons.md
+++ b/.agents/lessons.md
@@ -15,3 +15,6 @@ Each entry is a single bullet: `- **<topic>** — <lesson>`. Newest entries at t
 - **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 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.
+- **Semicolons inside `--` line comments in `db.ts` DDL strings break Node CI** — `architecture.md` notes this but the lesson wasn't in this file. `runSql()` on Node splits multi-statement SQL on `;` (because `better-sqlite3` allows one statement per `prepare()`); a `;` inside an inner `--` comment (e.g. `-- recipe_id is loose (matches a or b; no FK)`) creates a comment-only fragment, which `prepare()` rejects with `RangeError: The supplied SQL string contains no statements`. **Bun tests don't catch this** — `bun:sqlite` accepts multi-statement SQL natively, so `bun test` + `bun run check` are both green; the failure surfaces only when CI runs `node dist/index.mjs --full`. **Pattern:** rewrite comment-side `;` to a comma or em-dash; sanity-check with a tiny harness that splits the createTables template on `;` and prints any fragment that's all-`--`-comments. Hit on PR #76. The validator can be a one-liner — adding it as `bun run smoke:node` is a candidate roadmap item.
+- **`process.exitCode` is NOT a safe success oracle inside CLI verbs** — when a CLI handler in `runQueryCmd` (or any sibling that supports `--ci`) needs to know "did the work succeed?" for a side-effect decision (recency tracking, telemetry, follow-up writes), do NOT key off `process.exitCode !== 1`. Two failure modes: (1) `--ci` deliberately sets `exitCode = 1` on findings as the CI gating signal even though the recipe ran cleanly — keying off exitCode then treats success as failure (PR #76 audit Finding 1: `--ci + --recipe X --format sarif` exits 1 → recency NOT recorded → undercounts every CI run). (2) The exit code is process-global and survives across calls when an exported helper is invoked multiple times in one process (tests, programmatic use); a prior failure poisons later success. **Pattern:** track an explicit `recipeQuerySucceeded` (or domain-named) local flag, set true at each successful exit point inside the try block; check it in the finally. For helpers that conflate "ran cleanly" with "exit 1 because findings" (like `printFormattedQuery`), refactor to a discriminated-union return shape (`{ ok: true, exitCode: 0 | 1 } | { ok: false }`) so callers can disambiguate. Hit on PR #76 — caught by 2/3 PR-review agents (Codex + gpt-5.5) with concrete repros.
+- **Read-side substrate must be pure even when "lazy on read" looks cheap** — when a write-side cleanup (DELETE-on-prune, GC sweep, cache invalidation) seems cheaper to run lazily on the read path, weigh that against the documented contract of the read site. If the read surface promises "no side effects" / "no DB required" / "read resource" semantics (per CLI help text, README, MCP resource conventions), an in-place DELETE breaks the contract — even under WAL where the write doesn't block readers. **Pattern:** filter at SELECT time (`WHERE last_run_at >= cutoff`) for read paths, do eager prune on the write path (typically cheap on tiny domain tables — index-bounded scan is microseconds). The "hot path" cost concern that motivates lazy-on-read usually doesn't hold for tiny tables, but the read-purity invariant is durable across N agents reading the resource. Hit on PR #76 — Q3 of the recipe-recency plan locked lazy-on-read with reasoning that didn't model the "No DB required" `--recipes-json` contract; gpt-5.5 audit caught it.
diff --git a/.agents/rules/codemap.md b/.agents/rules/codemap.md
index 7a29e83..a4b44df 100644
--- a/.agents/rules/codemap.md
+++ b/.agents/rules/codemap.md
@@ -23,7 +23,7 @@ A local database (default **`.codemap/index.db`**) indexes structure: symbols, i
 | 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`                                                                                                                                                                                                                                                                              |
+| Recipe catalog / SQL           | —                  | `bun src/index.ts query --recipes-json` (every entry includes `last_run_at: number \| null` + `run_count: number` recency fields; rank with `jq 'sort_by(.last_run_at // 0) \| reverse'`; opt-out via `.codemap/config` `recipeRecency: false`) · `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`                                                                                                                                                                                                                                                                                                      |
@@ -75,12 +75,12 @@ Validation: SQL is rejected at load time if it starts with DML/DDL (DELETE/DROP/
 
 **Impact (`bun src/index.ts impact <target>`)**: symbol/file blast-radius walker — replaces hand-composed `WITH RECURSIVE` queries that agents struggle to write. Target auto-resolves: contains `/` or matches `files.path` → file target; otherwise symbol (case-sensitive). Walks compatible graphs by target kind: **symbol** → `calls` (callers / callees by name); **file** → `dependencies` + `imports` (`resolved_path` only). `--via <b>` overrides; mismatched explicit choices land in `skipped_backends` (no error). Cycle-detected via `WITH RECURSIVE` path-string + `instr` check; bounded by `--depth N` (default 3, `0` = unbounded but still cycle-detected and limit-capped) and `--limit N` (default 500). Output envelope: `{target, direction, via, depth_limit, matches: [{depth, direction, edge, kind, name?, file_path}], summary: {nodes, max_depth_reached, by_kind, terminated_by: 'depth'|'limit'|'exhausted'}}`. `--summary` trims `matches` for cheap CI-gate consumption (`jq '.summary.nodes'`) but preserves the count. SARIF / annotations not supported (graph traversal, not findings). Pure transport-agnostic engine in `application/impact-engine.ts`; CLI / MCP / HTTP all dispatch the same `findImpact` function.
 
-**MCP server (`bun src/index.ts mcp`)**: stdio MCP (Model Context Protocol) server — agents call codemap as JSON-RPC tools instead of shelling out to the CLI on every read. v1 ships one tool per CLI verb plus four lazy-cached resources:
+**MCP server (`bun src/index.ts mcp`)**: stdio MCP (Model Context Protocol) server — agents call codemap as JSON-RPC tools instead of shelling out to the CLI on every read. v1 ships one tool per CLI verb plus six resources (`codemap://recipes` + `codemap://recipes/{id}` are live read every call so inline `last_run_at` / `run_count` recency stays fresh; `codemap://schema` + `codemap://skill` lazy-cache; `codemap://files/{path}` + `codemap://symbols/{name}` always live):
 
 - **Tools:** `query` / `query_batch` / `query_recipe` / `audit` / `save_baseline` / `list_baselines` / `drop_baseline` / `context` / `validate` / `show` / `snippet` / `impact`. Snake_case keys (Codemap convention matching MCP spec examples + reference servers — spec is convention-agnostic; CLI stays kebab).
 - **`query_batch` (MCP-only):** N statements in one round-trip. Items are `string | {sql, summary?, changed_since?, group_by?}` — string form inherits batch-wide flag defaults, object form overrides on a per-key basis. Per-statement errors are isolated.
 - **`save_baseline` (polymorphic):** one tool, `{name, sql? | recipe?}` with runtime exclusivity check (mirrors the CLI's single `--save-baseline=<name>` verb).
-- **Resources:** `codemap://recipes` (catalog), `codemap://recipes/{id}` (one recipe), `codemap://schema` (live DDL from `sqlite_schema`), `codemap://skill` (bundled SKILL.md text), `codemap://files/{path}` (per-file roll-up: symbols, imports, exports, coverage), `codemap://symbols/{name}` (symbol lookup with `{matches, disambiguation?}` envelope; `?in=<path-prefix>` filter mirrors `show --in`). Catalog resources lazy-cache on first `read_resource`; `files/` and `symbols/` read live every call (no caching) since the index can change between requests under `--watch`.
+- **Resources:** `codemap://recipes` (catalog — live), `codemap://recipes/{id}` (one recipe — live), `codemap://schema` (live DDL from `sqlite_schema`; lazy-cached), `codemap://skill` (bundled SKILL.md text; lazy-cached), `codemap://files/{path}` (per-file roll-up: symbols, imports, exports, coverage — live), `codemap://symbols/{name}` (symbol lookup with `{matches, disambiguation?}` envelope; `?in=<path-prefix>` filter mirrors `show --in` — live). Recipe catalogs read live every call so inline `last_run_at` / `run_count` recency reflects mutations during the server lifetime; `schema` / `skill` cache because their inputs don't change mid-session.
 - **Output shape uniformity:** every tool returns the JSON envelope its CLI counterpart's `--json` would print — no re-mapping. Schema additions to the CLI envelope propagate to MCP automatically.
 
 For developing the MCP server itself: `src/cli/cmd-mcp.ts` (CLI shell) + `src/application/mcp-server.ts` (engine). See [`docs/architecture.md` § MCP wiring](../../docs/architecture.md#cli-usage).
diff --git a/.agents/skills/codemap/SKILL.md b/.agents/skills/codemap/SKILL.md
index 21ef321..ee0a99d 100644
--- a/.agents/skills/codemap/SKILL.md
+++ b/.agents/skills/codemap/SKILL.md
@@ -38,7 +38,7 @@ Replace placeholders (`'...'`) with your module path, file glob, or symbol name.
 
 **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`**.
+**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`**, plus **`last_run_at`** + **`run_count`** recency fields) as JSON (no DB required for the catalog itself; recency populates when an indexed DB exists, otherwise null/0). **`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):
 
@@ -80,10 +80,10 @@ Each emitted delta carries its own `base` metadata so mixed-baseline audits are
 - **`snippet`** — `{name, kind?, in?}`. 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 indexing — line range may have shifted), `missing` (true when file is gone). Per Q-6 (settled): `source` is always returned when the file exists; agent decides whether to act on stale content or run `codemap` / `codemap --files <path>` to re-index first. No auto-reindex side-effects from this read tool.
 - **`impact`** — `{target, direction?, via?, depth?, limit?, summary?}`. Symbol/file blast-radius walker — replaces hand-composed `WITH RECURSIVE` queries that agents struggle to write reliably. `target` is a symbol name (case-sensitive, exact) OR a project-relative file path (auto-detected by `/` or by matching `files.path`). `direction`: `up` (callers / dependents), `down` (callees / dependencies), `both` (default). `via`: `dependencies`, `calls`, `imports`, `all` (default — every backend compatible with the resolved target kind: symbol → `calls`; file → `dependencies` + `imports`; mismatched explicit choices land in `skipped_backends`, no error). `depth` default 3, `0` = unbounded (still cycle-detected and limit-capped). `limit` default 500. `summary: true` trims `matches` for cheap CI-gate consumption (`jq '.summary.nodes'`) but preserves the count. Result: `{target, direction, via, depth_limit, matches: [{depth, direction, edge, kind, name?, file_path}], summary: {nodes, max_depth_reached, by_kind, terminated_by: 'depth'|'limit'|'exhausted'}}`. Cycle detection is approximate-but-bounded — bounded depth + `LIMIT` keep cyclic graphs cheap; `terminated_by` reports the dominant stop reason. SARIF / annotations not supported (impact rows are graph traversals, not findings).
 
-**Resources (lazy-cached on first `read_resource`; constant for server-process lifetime):**
+**Resources (mostly lazy-cached on first `read_resource`; recipes / one-recipe live-read every call so the inline recency fields stay fresh):**
 
-- **`codemap://recipes`** — full catalog JSON (same as `--recipes-json`). Each entry carries `source: "bundled" | "project"` and `shadows: true` on project entries that override a bundled recipe id. Read this at session start so you know when a `--recipe foo` call will run a project override instead of the documented bundled version.
-- **`codemap://recipes/{id}`** — single recipe `{id, description, body?, sql, actions?, source, shadows?}`. Replaces `--print-sql <id>`.
+- **`codemap://recipes`** — full catalog JSON (same as `--recipes-json`). Each entry carries `source: "bundled" | "project"`, optional `shadows: true` on project entries that override a bundled recipe id, plus `last_run_at: number | null` and `run_count: number` recency fields (rank with `jq 'sort_by(.last_run_at // 0) | reverse'`). Read this at session start so you know when a `--recipe foo` call will run a project override instead of the documented bundled version.
+- **`codemap://recipes/{id}`** — single recipe `{id, description, body?, sql, actions?, source, shadows?, last_run_at, run_count}`. Replaces `--print-sql <id>`.
 - **`codemap://schema`** — DDL of every table in `.codemap/index.db` (queried live from `sqlite_schema`).
 - **`codemap://skill`** — full text of bundled `templates/agents/skills/codemap/SKILL.md`. Agents that don't preload the skill at session start can fetch it here.
 - **`codemap://files/{path}`** — per-file roll-up. Returns `{path, language, line_count, symbols, imports, exports, coverage}` where `imports.specifiers` is parsed JSON and `coverage` is `{measured_symbols, avg_coverage_pct, per_symbol}` or `null` when the file has no measured coverage. URI-encode the path. Reads live (no caching).
diff --git a/.changeset/recipe-recency.md b/.changeset/recipe-recency.md
new file mode 100644
index 0000000..ececb12
--- /dev/null
+++ b/.changeset/recipe-recency.md
@@ -0,0 +1,13 @@
+---
+"@stainless-code/codemap": patch
+---
+
+**Recipe-recency tracking** — every successful `--recipe` call now writes to a new `recipe_recency(recipe_id PK, last_run_at, run_count)` table. `--recipes-json` and the matching `codemap://recipes` / `codemap://recipes/{id}` MCP resources gain inline `last_run_at: number | null` + `run_count: number` fields per entry, so agent hosts can rank live recipes ahead of historic ones via `jq 'sort_by(.last_run_at // 0) | reverse'`. Default ON; opt-out via `.codemap/config` `recipeRecency: false` (short-circuits before any DB write — no rows ever land).
+
+Two write sites both call `tryRecordRecipeRun` (the failure-isolated wrapper around `recordRecipeRun`) from `application/recipe-recency.ts`: `handleQueryRecipe` in `application/tool-handlers.ts` (covers MCP + HTTP — both flow through it) and `runQueryCmd` in `cli/cmd-query.ts` (CLI — `finally` block keys off a local `recipeQuerySucceeded` flag, NOT `process.exitCode`, so `--ci`'s deliberate exit-1-on-findings is recognised as success). Counts only successful runs; recency-write failures are swallowed with a stderr `[recency] write failed: <reason>` warning so they NEVER block the recipe response. The 90-day rolling window is enforced eagerly on the write path (single indexed `DELETE` inside `recordRecipeRun` before the upsert); reads filter at SELECT time (`WHERE last_run_at >= cutoff`) and never mutate the DB so the catalog stays side-effect free for `--recipes-json` and the MCP `codemap://recipes` resources.
+
+The MCP/HTTP catalog cache was dropped — caching the JSON.stringify result alongside recency would freeze `last_run_at` at first-read forever per long-running `codemap mcp` / `codemap serve` lifetime. The underlying `listQueryRecipeCatalog()` is itself module-cached upstream, so the extra cost is one DB-read + one JSON.stringify per call. Schema / skill resources stay cached.
+
+**Local-only — no upload primitive ever ships.** The Floor exists to resist accumulation pressure. Sibling to `query_baselines` / `coverage`: intentionally absent from `dropAll()` so `--full` and `SCHEMA_VERSION` rebuilds preserve user-activity history. **No `SCHEMA_VERSION` bump** — the new table is purely additive and lands on existing DBs via `CREATE TABLE IF NOT EXISTS` on next boot.
+
+Schema docs: `architecture.md` § `recipe_recency`. Term entry: `glossary.md`. Bundled agent rule + skill (`templates/agents/`) + dev-side mirror (`.agents/`) updated in lockstep per Rule 10.
diff --git a/bun.lock b/bun.lock
index a88e7ad..965bb68 100644
--- a/bun.lock
+++ b/bun.lock
@@ -32,6 +32,9 @@
       },
     },
   },
+  "overrides": {
+    "ip-address": "^10.2.0",
+  },
   "packages": {
     "@babel/generator": ["@babel/generator@8.0.0-rc.3", "", { "dependencies": { "@babel/parser": "^8.0.0-rc.3", "@babel/types": "^8.0.0-rc.3", "@jridgewell/gen-mapping": "^0.3.12", "@jridgewell/trace-mapping": "^0.3.28", "@types/jsesc": "^2.5.0", "jsesc": "^3.0.2" } }, "sha512-em37/13/nR320G4jab/nIIHZgc2Wz2y/D39lxnTyxB4/D/omPQncl/lSdlnJY1OhQcRGugTSIF2l/69o31C9dA=="],
 
@@ -559,7 +562,7 @@
 
     "ini": ["ini@1.3.8", "", {}, "sha512-JV/yugV2uzW5iMRSiZAyDtQd+nxtUnjeLt0acNdw98kKLrvuRVyB80tsREOE7yvGVgalhZ6RNXCmEHkUKBKxew=="],
 
-    "ip-address": ["ip-address@10.1.0", "", {}, "sha512-XXADHxXmvT9+CRxhXg56LJovE+bmWnEWB78LB83VZTprKTmaC5QfruXocxzTZ2Kl0DNwKuBdlIhjL8LeY8Sf8Q=="],
+    "ip-address": ["ip-address@10.2.0", "", {}, "sha512-/+S6j4E9AHvW9SWMSEY9Xfy66O5PWvVEJ08O0y5JGyEKQpojb0K0GKpz/v5HJ/G0vi3D2sjGK78119oXZeE0qA=="],
 
     "ipaddr.js": ["ipaddr.js@1.9.1", "", {}, "sha512-0KI/607xoxSToH7GjN1FfSbLoU0+btTicjsQSWQlh/hZykN8KpmMf7uYwPW3R+akZ6R/w18ZlXSHBYXiYUPO3g=="],
 
diff --git a/docs/architecture.md b/docs/architecture.md
index b100ef4..26670fa 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -388,6 +388,22 @@ Three meta keys (`coverage_last_ingested_at` / `_path` / `_format`) record fresh
 
 Bundled recipes consuming the table — `untested-and-dead`, `files-by-coverage`, `worst-covered-exports`. Each ships a frontmatter `actions` block (per PR #26) so agents see per-row follow-up hints in `--json` output.
 
+### `recipe_recency` — Per-recipe last-run + run-count (user data) (`STRICT, WITHOUT ROWID`)
+
+Tracks `last_run_at` (epoch ms) + `run_count` per recipe id so agent hosts can rank live recipes ahead of historic ones. Surfaces inline on `--recipes-json` and the matching `codemap://recipes` / `codemap://recipes/{id}` MCP resources (live read every call — the resource cache was dropped to avoid freezing recency at first-read for the server-process lifetime). Same lifecycle posture as `query_baselines` / `coverage`: **intentionally absent from `dropAll()`** so `--full` and `SCHEMA_VERSION` rebuilds preserve user-activity history. Local-only — no upload primitive ever ships (resists telemetry-creep PRs by construction).
+
+Two write sites both call `tryRecordRecipeRun` (the failure-isolated wrapper around `recordRecipeRun`) from `application/recipe-recency.ts`: `handleQueryRecipe` in `application/tool-handlers.ts` (covers MCP + HTTP — both flow through it) and `runQueryCmd` in `cli/cmd-query.ts` (CLI — finally-block keys off a local `recipeQuerySucceeded` flag, NOT `process.exitCode`, so `--ci`'s deliberate exit-1-on-findings is recognised as success). Counts only successful runs; recency-write failures are swallowed with a stderr `[recency] write failed: <reason>` warning so they NEVER block the recipe response. The 90-day rolling window is enforced eagerly on the write path (single indexed `DELETE` inside `recordRecipeRun` before the upsert); reads filter at SELECT time (`WHERE last_run_at >= cutoff`) and never mutate the DB so the catalog stays side-effect free for `--recipes-json` and the MCP `codemap://recipes` resources.
+
+Default ON; opt-out via `.codemap/config` `recipeRecency: false` (short-circuits before any DB write — no rows ever land). `recipe_id` is loose — matches bundled or project-recipe ids (no `recipes` SQLite table to FK against; project-shadow rows share the bundled row, since only one version is ever reachable per id).
+
+| Column      | Type    | Description                                                                              |
+| ----------- | ------- | ---------------------------------------------------------------------------------------- |
+| recipe_id   | TEXT PK | Recipe id (matches `QUERY_RECIPES` keys + project-recipe ids in `<state-dir>/recipes/`). |
+| last_run_at | INTEGER | Epoch ms of the last successful run.                                                     |
+| run_count   | INTEGER | Cumulative successful runs (incremented per call). `INTEGER` wraparound is theoretical.  |
+
+`idx_recipe_recency_last_run` on `last_run_at` keeps both the eager-on-write prune (`DELETE WHERE last_run_at < cutoffMs` inside `recordRecipeRun`) and the read-time filter (`WHERE last_run_at >= cutoffMs` inside `loadRecipeRecency`) indexed scans as project-recipe counts grow. **Boundary discipline (write-path)**: only `application/tool-handlers.ts` + `cli/cmd-query.ts` (+ the test file) may import `tryRecordRecipeRun` / `recordRecipeRun` — re-runnable forbidden-edge query at [§ Boundary verification — `recipe_recency` write path](#boundary-verification--recipe_recency-write-path). **Read-path** (`enrichWithRecency` / `loadRecipeRecency`) is unrestricted — any catalog renderer can import it (today: `cmd-query.ts` for `--recipes-json`, `application/resource-handlers.ts` for `codemap://recipes` + `codemap://recipes/{id}`).
+
 ### `boundary_rules` — Architecture-boundary rules (config-derived) (`STRICT, WITHOUT ROWID`)
 
 Reconciled from `.codemap/config.ts` `boundaries: [...]` on every index pass via `reconcileBoundaryRules` in `db.ts`; the wiring lives in `application/run-index.ts` right after `createSchema`. Empty when the user declares no boundaries. Bundled `boundary-violations` recipe joins this table against `dependencies` via SQLite `GLOB` to surface forbidden imports; `--format sarif` lights up automatically because the recipe row aliases `dependencies.from_path` to `file_path` (the existing location-column priority list catches it).
@@ -563,13 +579,30 @@ During full rebuild the tables are empty (just created), so the per-file `delete
 
 The `meta` table stores `schema_version`. The canonical version is `SCHEMA_VERSION` in `db.ts` (exported). Both `createSchema()` and the full-rebuild path in `index.ts` persist `String(SCHEMA_VERSION)` after building tables and indexes.
 
-When `SCHEMA_VERSION` is bumped (after the first release, when DDL changes require it):
-
-- `createSchema()` detects the mismatch automatically and calls `dropAll()` before recreating
-- No manual intervention needed — run the indexer and it auto-rebuilds on version change
+**When to bump.** Only when a DDL change FORCES a rebuild — i.e. an existing `.codemap/index.db` from the previous version would be incorrect or incompatible with the new code (column drop, type change, breaking constraint shift, table rename). Purely additive tables / columns / indexes that land via `CREATE … IF NOT EXISTS` on next boot DON'T need a bump — that's the `query_baselines` / `coverage` / `recipe_recency` precedent (each landed without a bump and existing DBs picked them up automatically). Bumping triggers `dropAll()` and a full reindex; doing it for additive changes burns ~85ms (per `benchmark.md`) for zero migration benefit. See also [`.agents/lessons.md`](../.agents/lessons.md) "changesets bump policy (pre-v1)" — a `SCHEMA_VERSION` bump always rides with a `minor` changeset; additive tables ride patch.
 
 When `SCHEMA_VERSION` changes, the indexer auto-detects the mismatch and triggers a full rebuild — no manual intervention needed.
 
+### Boundary verification — `recipe_recency` write path
+
+Re-runnable kit, lifted from the engine module so the docstring stays slim. Only `application/tool-handlers.ts` + `cli/cmd-query.ts` (+ the test file) may import the write-path symbols (`tryRecordRecipeRun` / `recordRecipeRun`):
+
+```bash
+bun src/index.ts query --json "
+  SELECT DISTINCT file_path FROM imports
+  WHERE source LIKE '%application/recipe-recency%'
+    -- Quoted-name match (specifiers is JSON) — explicit so a future
+    -- symbol like 'recordRecipeRunner' wouldn't false-positive.
+    AND (specifiers LIKE '%\"recordRecipeRun\"%'
+         OR specifiers LIKE '%\"tryRecordRecipeRun\"%')
+    AND file_path NOT IN ('src/application/tool-handlers.ts',
+                          'src/cli/cmd-query.ts',
+                          'src/application/recipe-recency.test.ts')
+"
+```
+
+Expected: `[]`. Non-empty = a new write site appeared without a docs update — escalate per [`audit-pr-architecture` skill](../.agents/skills/audit-pr-architecture/SKILL.md). Read-path imports (`enrichWithRecency` / `loadRecipeRecency`) are unrestricted by design.
+
 ## SQLite Performance Configuration
 
 ### `bun:sqlite` API
diff --git a/docs/audits/.gitkeep b/docs/audits/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/docs/glossary.md b/docs/glossary.md
index 733dad7..cd02c22 100644
--- a/docs/glossary.md
+++ b/docs/glossary.md
@@ -408,6 +408,10 @@ Run via `codemap query --recipe <id>` (alias `-r`). Project recipes win on id co
 
 Boolean flag on a project-local recipe entry that has the same `id` as a bundled recipe — `shadows: true` means "this project recipe overrides what the bundled version would have done." Surfaces in `--recipes-json`, `codemap://recipes`, and `codemap://recipes/{id}` so agents can see overrides without parsing per-execution responses (per-execution shape stays unchanged for plan § 4 uniformity). Silent at runtime — the agent-facing skill prompt is the channel that tells agents to check the flag at session start.
 
+### `recipe_recency` (table) / recipe recency / `recipeRecency: false`
+
+Per-recipe `last_run_at` (epoch ms) + `run_count` for agent-host ranking — surfaces inline on every `--recipes-json` entry and the matching `codemap://recipes` / `codemap://recipes/{id}` MCP resources (live read every call; the resource cache was dropped to avoid freezing recency at first-read for the server-process lifetime). Counts only successful recipe runs; failed runs / param-validation rejections / SQL errors don't write. Default ON; opt-out via `.codemap/config` `recipeRecency: false` (short-circuits before any DB write — no rows ever land). 90-day rolling window enforced eagerly on the write path (single transactional `DELETE` + `INSERT … ON CONFLICT` inside `recordRecipeRun`); reads filter at SELECT, never mutate. Local-only — no upload primitive (resists telemetry-creep PRs by construction). Two write sites — `handleQueryRecipe` in `application/tool-handlers.ts` (covers MCP + HTTP) and `runQueryCmd` in `cli/cmd-query.ts` (CLI) — both call `tryRecordRecipeRun` (the failure-isolated wrapper around `recordRecipeRun`) from `application/recipe-recency.ts`. Failure-isolated: a recency-write throw NEVER blocks the recipe response (warning to stderr unless `quiet`). Schema: see [architecture.md § `recipe_recency`](./architecture.md#recipe_recency--per-recipe-last-run--run-count-user-data-strict-without-rowid).
+
 ### research
 
 A snapshot-style note under `docs/research/` capturing a competitive scan or evaluation. Closed per [README § Closing research](./README.md#closing-research) — adopted items are slimmed to a "What shipped" appendix; rejected items keep a status header.
diff --git a/docs/research/.gitkeep b/docs/research/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/docs/research/non-goals-reassessment-2026-05.md b/docs/research/non-goals-reassessment-2026-05.md
index 91391ec..e5c7972 100644
--- a/docs/research/non-goals-reassessment-2026-05.md
+++ b/docs/research/non-goals-reassessment-2026-05.md
@@ -20,18 +20,19 @@ The right framing now: **what does the SQL-index-with-three-transports + worker-
 
 The original capability inventory contained 10 rows. Items that have shipped since are listed below; pending picks moved to canonical homes per [§ 7](#7-lifted-to).
 
-| Item                                       | What shipped                                                                                                                                                                                 | Canonical home                                                                                                                                   |
-| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
-| 1.3 Cyclomatic complexity per symbol       | `complexity` column on `symbols`; `high-complexity-untested.sql` recipe                                                                                                                      | [`architecture.md § Schema`](../architecture.md#schema), `templates/recipes/high-complexity-untested.{sql,md}`                                   |
-| 1.7 Mermaid output                         | `--format mermaid` on edge-shaped recipes (`impact`, `dependencies`); bounded-input contract (≤ 50 edges)                                                                                    | [`README.md § CLI`](../../README.md#cli)                                                                                                         |
-| 1.8 More MCP resources                     | `codemap://files/{path}` + `codemap://symbols/{name}` (live read-per-call); reuses `{matches, disambiguation?}` envelope                                                                     | [`templates/agents/skills/codemap/SKILL.md`](../../templates/agents/skills/codemap/SKILL.md), [`docs/glossary.md § MCP server`](../glossary.md)  |
-| 2.1 Opt-in FTS5                            | `--with-fts` CLI flag / `fts5: true` config; `source_fts` virtual table at index time; `text-in-deprecated-functions.sql` JOIN demo                                                          | [`roadmap.md § Non-goals (v1) → Floors`](../roadmap.md#floors-v1-product-shape), [`README.md § CLI`](../../README.md#cli)                        |
-| 2.2 Visualisation flip → output formatter  | `--format mermaid` (above); SARIF + annotations were the precedent                                                                                                                           | Same                                                                                                                                             |
-| 1.10 rename-preview + parametrised recipes | `params:` frontmatter + `--params key=value` CLI / `query_recipe.params` MCP/HTTP; `find-symbol-by-kind.sql` exemplar; `rename-preview.sql` recipe; `--format diff` / `diff-json` formatters | [`README.md § CLI`](../../README.md#cli), `templates/recipes/find-symbol-by-kind.{sql,md}`, `templates/recipes/rename-preview.{sql,md}` (PR #71) |
-| § 6 Q1 daemon-default flip                 | `mcp` / `serve` watcher default-ON; `--no-watch` and `CODEMAP_WATCH=0` opt-outs                                                                                                              | [`architecture.md § Watch wiring`](../architecture.md#cli-usage), [`docs/glossary.md`](../glossary.md)                                           |
-| 1.5 Boundary violations                    | `boundaries` config + `boundary_rules` table + bundled `boundary-violations` recipe; SARIF auto-detects via `from_path` location column                                                      | [`architecture.md § Schema`](../architecture.md#schema), `templates/recipes/boundary-violations.{sql,md}` (PR #72)                               |
-
-Pending picks (§ 1.1, 1.2, 1.4, 1.6, 1.9, plus § 5 (b) and (d)) moved to canonical homes — see [§ 7](#7-lifted-to).
+| Item                                       | What shipped                                                                                                                                                                                      | Canonical home                                                                                                                                                          |
+| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1.3 Cyclomatic complexity per symbol       | `complexity` column on `symbols`; `high-complexity-untested.sql` recipe                                                                                                                           | [`architecture.md § Schema`](../architecture.md#schema), `templates/recipes/high-complexity-untested.{sql,md}`                                                          |
+| 1.7 Mermaid output                         | `--format mermaid` on edge-shaped recipes (`impact`, `dependencies`); bounded-input contract (≤ 50 edges)                                                                                         | [`README.md § CLI`](../../README.md#cli)                                                                                                                                |
+| 1.8 More MCP resources                     | `codemap://files/{path}` + `codemap://symbols/{name}` (live read-per-call); reuses `{matches, disambiguation?}` envelope                                                                          | [`templates/agents/skills/codemap/SKILL.md`](../../templates/agents/skills/codemap/SKILL.md), [`docs/glossary.md § MCP server`](../glossary.md)                         |
+| 2.1 Opt-in FTS5                            | `--with-fts` CLI flag / `fts5: true` config; `source_fts` virtual table at index time; `text-in-deprecated-functions.sql` JOIN demo                                                               | [`roadmap.md § Non-goals (v1) → Floors`](../roadmap.md#floors-v1-product-shape), [`README.md § CLI`](../../README.md#cli)                                               |
+| 2.2 Visualisation flip → output formatter  | `--format mermaid` (above); SARIF + annotations were the precedent                                                                                                                                | Same                                                                                                                                                                    |
+| 1.10 rename-preview + parametrised recipes | `params:` frontmatter + `--params key=value` CLI / `query_recipe.params` MCP/HTTP; `find-symbol-by-kind.sql` exemplar; `rename-preview.sql` recipe; `--format diff` / `diff-json` formatters      | [`README.md § CLI`](../../README.md#cli), `templates/recipes/find-symbol-by-kind.{sql,md}`, `templates/recipes/rename-preview.{sql,md}` (PR #71)                        |
+| § 6 Q1 daemon-default flip                 | `mcp` / `serve` watcher default-ON; `--no-watch` and `CODEMAP_WATCH=0` opt-outs                                                                                                                   | [`architecture.md § Watch wiring`](../architecture.md#cli-usage), [`docs/glossary.md`](../glossary.md)                                                                  |
+| 1.5 Boundary violations                    | `boundaries` config + `boundary_rules` table + bundled `boundary-violations` recipe; SARIF auto-detects via `from_path` location column                                                           | [`architecture.md § Schema`](../architecture.md#schema), `templates/recipes/boundary-violations.{sql,md}` (PR #72)                                                      |
+| 1.9 Recipe-recency tracking                | `recipe_recency` table; `last_run_at` + `run_count` inline on `--recipes-json` + `codemap://recipes` resources; opt-out via `.codemap/config` `recipeRecency: false`; 90-day eager prune on write | [`architecture.md § recipe_recency`](../architecture.md#recipe_recency--per-recipe-last-run--run-count-user-data-strict-without-rowid), [`glossary.md`](../glossary.md) |
+
+Pending picks (§ 1.1, 1.2, 1.4, 1.6, plus § 5 (b) and (d)) moved to canonical homes — see [§ 7](#7-lifted-to).
 
 ---
 
@@ -118,7 +119,7 @@ ripgrep can't compose with `symbols` / `coverage` / `markers` in one shot — it
 
 > **Lifted (2026-05).** Forward-looking pick order lives in [`roadmap.md § Backlog`](../roadmap.md#backlog); big items track in [`c9-plugin-layer.md`](../plans/c9-plugin-layer.md) and [`lsp-diagnostic-push.md`](../plans/lsp-diagnostic-push.md). The narrative below preserves the **rationale archive** — particularly the (d) three-revisions arc — for future readers.
 
-The reasoning that produced the cadence (a) ✅ → (c) ✅ → § 1.10 rename-preview + parametrised-recipes infra ✅ → § 6 Q1 daemon-default flip ✅ → § 1.5 boundary → § 1.9 recipe-recency → § 1.6 unused type members → **(b) C.9 plugin layer** → **(d) LSP+VSCode-extension pair** last:
+The reasoning that produced the cadence (a) ✅ → (c) ✅ → § 1.10 rename-preview + parametrised-recipes infra ✅ → § 6 Q1 daemon-default flip ✅ → § 1.5 boundary ✅ → § 1.6 unused type members ✅ → § 1.9 recipe-recency ✅ → **(b) C.9 plugin layer** → **(d) LSP+VSCode-extension pair** last:
 
 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.
@@ -134,25 +135,25 @@ The reasoning that produced the cadence (a) ✅ → (c) ✅ → § 1.10 rename-p
 
 The lift trail — for future archaeologists asking "where did this idea / decision land?".
 
-| Original (this note's section)                         | Lifted to                                                                                                                                 | Plan PR / commit              |
-| ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
-| § 1.7 Mermaid output (shipped)                         | `templates/recipes/` + `README.md § CLI`                                                                                                  | PR #59 (FTS5 + Mermaid)       |
-| § 1.3 cyclomatic complexity (shipped)                  | `architecture.md § Schema` + `templates/recipes/high-complexity-untested.{sql,md}`                                                        | PR #70                        |
-| § 1.8 MCP resources (shipped)                          | `templates/agents/skills/codemap/SKILL.md` + `docs/glossary.md`                                                                           | post-PR #35 follow-ups        |
-| § 1.5 boundary violations (shipped)                    | `templates/recipes/boundary-violations.{sql,md}` + `boundaries` config field + `boundary_rules` table                                     | PR #72                        |
-| § 1.10 rename-preview + parametrised recipes (shipped) | `templates/recipes/find-symbol-by-kind.{sql,md}` + `templates/recipes/rename-preview.{sql,md}` + `--format diff` / `diff-json` formatters | PR #71                        |
-| § 1.9 recipe-recency (pending)                         | [`roadmap.md § Backlog`](../roadmap.md#backlog) (inline rationale)                                                                        | docs-capability-sync Slice 5c |
-| § 1.6 unused type members (advisory; pending)          | [`roadmap.md § Backlog`](../roadmap.md#backlog) (inline rationale)                                                                        | docs-capability-sync Slice 5c |
-| § 2.1–2.4 verdicts                                     | [`roadmap.md § Non-goals (v1) → Floors`](../roadmap.md#floors-v1-product-shape)                                                           | docs-capability-sync Slice 3  |
-| § 2.5 / § 5 (b) C.9 framework plugin layer             | [`docs/plans/c9-plugin-layer.md`](../plans/c9-plugin-layer.md)                                                                            | already open                  |
-| § 2.5 / § 5 (d) LSP diagnostic-push + VSCode extension | [`docs/plans/lsp-diagnostic-push.md`](../plans/lsp-diagnostic-push.md)                                                                    | already open                  |
-| § 3 moats A + B + ergonomic floors                     | [`roadmap.md § Non-goals (v1) → Moats`](../roadmap.md#moats-load-bearing) + [`Floors`](../roadmap.md#floors-v1-product-shape)             | docs-capability-sync Slice 3  |
-| § 4 inspiration sources catalogue                      | [`.agents/rules/plan-pr-inspiration-discipline.md`](../../.agents/rules/plan-pr-inspiration-discipline.md) Top inspiration sources table  | docs-capability-sync Slice 5a |
-| § 6 Q1 daemon-default flip (shipped)                   | `mcp` / `serve` watcher default-ON; `--no-watch` / `CODEMAP_WATCH=0` opt-outs; `architecture.md` § Watch wiring + `glossary.md`           | commit `31479a5`              |
-| § 6 Q2 FTS5 opt-in (shipped)                           | [`roadmap.md § Non-goals (v1) → Floors`](../roadmap.md#floors-v1-product-shape)                                                           | already there                 |
-| § 6 Q3 LSP shape                                       | [`docs/plans/lsp-diagnostic-push.md`](../plans/lsp-diagnostic-push.md)                                                                    | already open                  |
-| § 6 Q4 C.9 plugin contract scope                       | [`docs/plans/c9-plugin-layer.md`](../plans/c9-plugin-layer.md)                                                                            | already open                  |
-| § 6 Q5 history table (deferred)                        | [`roadmap.md § Backlog`](../roadmap.md#backlog) (revisit triggers preserved inline)                                                       | docs-capability-sync Slice 5c |
+| Original (this note's section)                         | Lifted to                                                                                                                                                                | Plan PR / commit              |
+| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------- |
+| § 1.7 Mermaid output (shipped)                         | `templates/recipes/` + `README.md § CLI`                                                                                                                                 | PR #59 (FTS5 + Mermaid)       |
+| § 1.3 cyclomatic complexity (shipped)                  | `architecture.md § Schema` + `templates/recipes/high-complexity-untested.{sql,md}`                                                                                       | PR #70                        |
+| § 1.8 MCP resources (shipped)                          | `templates/agents/skills/codemap/SKILL.md` + `docs/glossary.md`                                                                                                          | post-PR #35 follow-ups        |
+| § 1.5 boundary violations (shipped)                    | `templates/recipes/boundary-violations.{sql,md}` + `boundaries` config field + `boundary_rules` table                                                                    | PR #72                        |
+| § 1.10 rename-preview + parametrised recipes (shipped) | `templates/recipes/find-symbol-by-kind.{sql,md}` + `templates/recipes/rename-preview.{sql,md}` + `--format diff` / `diff-json` formatters                                | PR #71                        |
+| § 1.9 recipe-recency (shipped)                         | [`architecture.md § recipe_recency`](../architecture.md#recipe_recency--per-recipe-last-run--run-count-user-data-strict-without-rowid) + [`glossary.md`](../glossary.md) | branch `feat/recipe-recency`  |
+| § 1.6 unused type members (advisory; pending)          | [`roadmap.md § Backlog`](../roadmap.md#backlog) (inline rationale)                                                                                                       | docs-capability-sync Slice 5c |
+| § 2.1–2.4 verdicts                                     | [`roadmap.md § Non-goals (v1) → Floors`](../roadmap.md#floors-v1-product-shape)                                                                                          | docs-capability-sync Slice 3  |
+| § 2.5 / § 5 (b) C.9 framework plugin layer             | [`docs/plans/c9-plugin-layer.md`](../plans/c9-plugin-layer.md)                                                                                                           | already open                  |
+| § 2.5 / § 5 (d) LSP diagnostic-push + VSCode extension | [`docs/plans/lsp-diagnostic-push.md`](../plans/lsp-diagnostic-push.md)                                                                                                   | already open                  |
+| § 3 moats A + B + ergonomic floors                     | [`roadmap.md § Non-goals (v1) → Moats`](../roadmap.md#moats-load-bearing) + [`Floors`](../roadmap.md#floors-v1-product-shape)                                            | docs-capability-sync Slice 3  |
+| § 4 inspiration sources catalogue                      | [`.agents/rules/plan-pr-inspiration-discipline.md`](../../.agents/rules/plan-pr-inspiration-discipline.md) Top inspiration sources table                                 | docs-capability-sync Slice 5a |
+| § 6 Q1 daemon-default flip (shipped)                   | `mcp` / `serve` watcher default-ON; `--no-watch` / `CODEMAP_WATCH=0` opt-outs; `architecture.md` § Watch wiring + `glossary.md`                                          | commit `31479a5`              |
+| § 6 Q2 FTS5 opt-in (shipped)                           | [`roadmap.md § Non-goals (v1) → Floors`](../roadmap.md#floors-v1-product-shape)                                                                                          | already there                 |
+| § 6 Q3 LSP shape                                       | [`docs/plans/lsp-diagnostic-push.md`](../plans/lsp-diagnostic-push.md)                                                                                                   | already open                  |
+| § 6 Q4 C.9 plugin contract scope                       | [`docs/plans/c9-plugin-layer.md`](../plans/c9-plugin-layer.md)                                                                                                           | already open                  |
+| § 6 Q5 history table (deferred)                        | [`roadmap.md § Backlog`](../roadmap.md#backlog) (revisit triggers preserved inline)                                                                                      | docs-capability-sync Slice 5c |
 
 Other anchors:
 
diff --git a/docs/roadmap.md b/docs/roadmap.md
index 7192741..b4399d9 100644
--- a/docs/roadmap.md
+++ b/docs/roadmap.md
@@ -52,7 +52,6 @@ Soft constraints — describe shipped reality. Decided-but-unshipped flips live
 
 ## 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.
 - [ ] **`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.
diff --git a/package.json b/package.json
index 162f0f8..3c556ab 100644
--- a/package.json
+++ b/package.json
@@ -96,6 +96,9 @@
     "tsdown": "^0.21.10",
     "typescript": "^6.0.3"
   },
+  "overrides": {
+    "ip-address": "^10.2.0"
+  },
   "engines": {
     "bun": ">=1.0.0",
     "node": "^20.19.0 || >=22.12.0"
diff --git a/src/application/recipe-recency.test.ts b/src/application/recipe-recency.test.ts
new file mode 100644
index 0000000..abd8c05
--- /dev/null
+++ b/src/application/recipe-recency.test.ts
@@ -0,0 +1,365 @@
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { resolveCodemapConfig } from "../config";
+import { closeDb, createTables, openDb } from "../db";
+import { initCodemap } from "../runtime";
+import {
+  loadRecipeRecency,
+  pruneRecipeRecency,
+  RECENCY_WINDOW_MS,
+  recordRecipeRun,
+  tryRecordRecipeRun,
+} from "./recipe-recency";
+
+let projectRoot: string;
+
+beforeEach(() => {
+  projectRoot = mkdtempSync(join(tmpdir(), "recipe-recency-"));
+  initCodemap(resolveCodemapConfig(projectRoot, undefined));
+  const db = openDb();
+  try {
+    createTables(db);
+  } finally {
+    closeDb(db);
+  }
+});
+
+afterEach(() => {
+  rmSync(projectRoot, { recursive: true, force: true });
+});
+
+describe("recipe_recency — schema", () => {
+  it("starts empty after createTables", () => {
+    const db = openDb();
+    try {
+      const rows = db
+        .query<{ n: number }>("SELECT COUNT(*) AS n FROM recipe_recency")
+        .all();
+      expect(rows[0]?.n).toBe(0);
+    } finally {
+      closeDb(db, { readonly: true });
+    }
+  });
+
+  it("RECENCY_WINDOW_MS equals 90 days", () => {
+    expect(RECENCY_WINDOW_MS).toBe(90 * 24 * 60 * 60 * 1000);
+  });
+});
+
+describe("recordRecipeRun", () => {
+  it("creates a row with run_count=1 on first call", () => {
+    const db = openDb();
+    try {
+      recordRecipeRun({ db, recipeId: "fan-out", now: 1_000_000 });
+      const row = db
+        .query<{
+          recipe_id: string;
+          last_run_at: number;
+          run_count: number;
+        }>("SELECT recipe_id, last_run_at, run_count FROM recipe_recency")
+        .get();
+      expect(row).toEqual({
+        recipe_id: "fan-out",
+        last_run_at: 1_000_000,
+        run_count: 1,
+      });
+    } finally {
+      closeDb(db);
+    }
+  });
+
+  it("increments run_count and updates last_run_at on subsequent calls", () => {
+    const db = openDb();
+    try {
+      recordRecipeRun({ db, recipeId: "fan-out", now: 1_000_000 });
+      recordRecipeRun({ db, recipeId: "fan-out", now: 2_000_000 });
+      recordRecipeRun({ db, recipeId: "fan-out", now: 3_000_000 });
+      const row = db
+        .query<{ last_run_at: number; run_count: number }>(
+          "SELECT last_run_at, run_count FROM recipe_recency WHERE recipe_id = 'fan-out'",
+        )
+        .get();
+      expect(row).toEqual({ last_run_at: 3_000_000, run_count: 3 });
+    } finally {
+      closeDb(db);
+    }
+  });
+
+  it("tracks distinct recipes in separate rows", () => {
+    const db = openDb();
+    try {
+      recordRecipeRun({ db, recipeId: "fan-out", now: 1_000_000 });
+      recordRecipeRun({ db, recipeId: "fan-in", now: 1_500_000 });
+      recordRecipeRun({ db, recipeId: "fan-out", now: 2_000_000 });
+      const rows = db
+        .query<{
+          recipe_id: string;
+          last_run_at: number;
+          run_count: number;
+        }>(
+          "SELECT recipe_id, last_run_at, run_count FROM recipe_recency ORDER BY recipe_id",
+        )
+        .all();
+      expect(rows).toEqual([
+        { recipe_id: "fan-in", last_run_at: 1_500_000, run_count: 1 },
+        { recipe_id: "fan-out", last_run_at: 2_000_000, run_count: 2 },
+      ]);
+    } finally {
+      closeDb(db);
+    }
+  });
+
+  it("defaults `now` to Date.now() when omitted", () => {
+    const db = openDb();
+    try {
+      const before = Date.now();
+      recordRecipeRun({ db, recipeId: "fan-out" });
+      const after = Date.now();
+      const row = db
+        .query<{ last_run_at: number }>(
+          "SELECT last_run_at FROM recipe_recency WHERE recipe_id = 'fan-out'",
+        )
+        .get();
+      expect(row?.last_run_at).toBeGreaterThanOrEqual(before);
+      expect(row?.last_run_at).toBeLessThanOrEqual(after);
+    } finally {
+      closeDb(db);
+    }
+  });
+});
+
+describe("pruneRecipeRecency", () => {
+  it("deletes rows whose last_run_at < cutoffMs", () => {
+    const db = openDb();
+    try {
+      recordRecipeRun({ db, recipeId: "old-recipe", now: 1_000 });
+      recordRecipeRun({ db, recipeId: "new-recipe", now: 9_999 });
+      pruneRecipeRecency({ db, cutoffMs: 5_000 });
+      const rows = db
+        .query<{ recipe_id: string }>(
+          "SELECT recipe_id FROM recipe_recency ORDER BY recipe_id",
+        )
+        .all();
+      expect(rows).toEqual([{ recipe_id: "new-recipe" }]);
+    } finally {
+      closeDb(db);
+    }
+  });
+
+  it("keeps rows where last_run_at == cutoffMs (strict <)", () => {
+    const db = openDb();
+    try {
+      recordRecipeRun({ db, recipeId: "exactly-cutoff", now: 5_000 });
+      pruneRecipeRecency({ db, cutoffMs: 5_000 });
+      const rows = db
+        .query<{ recipe_id: string }>("SELECT recipe_id FROM recipe_recency")
+        .all();
+      expect(rows).toEqual([{ recipe_id: "exactly-cutoff" }]);
+    } finally {
+      closeDb(db);
+    }
+  });
+
+  it("is a no-op on an empty table", () => {
+    const db = openDb();
+    try {
+      pruneRecipeRecency({ db, cutoffMs: Date.now() });
+      const rows = db
+        .query<{ n: number }>("SELECT COUNT(*) AS n FROM recipe_recency")
+        .all();
+      expect(rows[0]?.n).toBe(0);
+    } finally {
+      closeDb(db);
+    }
+  });
+});
+
+describe("loadRecipeRecency", () => {
+  it("returns an empty Map when no recipes have run", () => {
+    const db = openDb();
+    try {
+      const map = loadRecipeRecency({ db });
+      expect(map.size).toBe(0);
+    } finally {
+      closeDb(db, { readonly: true });
+    }
+  });
+
+  it("returns rows keyed by recipe_id", () => {
+    const db = openDb();
+    try {
+      const now = Date.now();
+      recordRecipeRun({ db, recipeId: "fan-out", now });
+      recordRecipeRun({ db, recipeId: "fan-out", now });
+      recordRecipeRun({ db, recipeId: "fan-in", now });
+      const map = loadRecipeRecency({ db, now });
+      expect(map.size).toBe(2);
+      expect(map.get("fan-out")).toEqual({ last_run_at: now, run_count: 2 });
+      expect(map.get("fan-in")).toEqual({ last_run_at: now, run_count: 1 });
+    } finally {
+      closeDb(db);
+    }
+  });
+
+  it("filters out rows older than 90 days WITHOUT mutating the table (read purity)", () => {
+    const db = openDb();
+    try {
+      const now = 100 * 24 * 60 * 60 * 1000;
+      const tooOld = now - RECENCY_WINDOW_MS - 1;
+      const justInside = now - RECENCY_WINDOW_MS + 1;
+      // Raw INSERT — `recordRecipeRun` would eager-prune the ancient row.
+      db.run(
+        "INSERT INTO recipe_recency (recipe_id, last_run_at, run_count) VALUES (?, ?, 1)",
+        ["ancient", tooOld],
+      );
+      db.run(
+        "INSERT INTO recipe_recency (recipe_id, last_run_at, run_count) VALUES (?, ?, 1)",
+        ["still-fresh", justInside],
+      );
+      const map = loadRecipeRecency({ db, now });
+      expect(map.has("ancient")).toBe(false);
+      expect(map.has("still-fresh")).toBe(true);
+      // Read MUST NOT delete — ancient row still on disk.
+      const rows = db
+        .query<{ recipe_id: string }>(
+          "SELECT recipe_id FROM recipe_recency ORDER BY recipe_id",
+        )
+        .all();
+      expect(rows.map((r) => r.recipe_id)).toEqual(["ancient", "still-fresh"]);
+    } finally {
+      closeDb(db);
+    }
+  });
+});
+
+describe("recordRecipeRun — eager prune (write-side)", () => {
+  it("deletes ancient rows alongside its upsert", () => {
+    const db = openDb();
+    try {
+      const now = 100 * 24 * 60 * 60 * 1000;
+      const tooOld = now - RECENCY_WINDOW_MS - 1;
+      db.run(
+        "INSERT INTO recipe_recency (recipe_id, last_run_at, run_count) VALUES (?, ?, 1)",
+        ["ancient", tooOld],
+      );
+      recordRecipeRun({ db, recipeId: "fresh", now });
+      const rows = db
+        .query<{ recipe_id: string }>(
+          "SELECT recipe_id FROM recipe_recency ORDER BY recipe_id",
+        )
+        .all();
+      expect(rows.map((r) => r.recipe_id)).toEqual(["fresh"]);
+    } finally {
+      closeDb(db);
+    }
+  });
+});
+
+describe("tryRecordRecipeRun — failure isolation", () => {
+  it("swallows openDb failures and emits a stderr warning", () => {
+    const warnings: string[] = [];
+    const origWarn = console.warn;
+    console.warn = (...args: unknown[]) =>
+      warnings.push(args.map((a) => String(a)).join(" "));
+    try {
+      expect(() =>
+        tryRecordRecipeRun("any-recipe", {
+          _openDb: () => {
+            throw new Error("simulated openDb failure");
+          },
+        }),
+      ).not.toThrow();
+    } finally {
+      console.warn = origWarn;
+    }
+    expect(
+      warnings.some(
+        (w) =>
+          w.includes("[recency] write failed") &&
+          w.includes("simulated openDb failure"),
+      ),
+    ).toBe(true);
+  });
+
+  it("respects quiet flag — no stderr warning emitted", () => {
+    const warnings: string[] = [];
+    const origWarn = console.warn;
+    console.warn = (...args: unknown[]) =>
+      warnings.push(args.map((a) => String(a)).join(" "));
+    try {
+      tryRecordRecipeRun("any-recipe", {
+        quiet: true,
+        _openDb: () => {
+          throw new Error("simulated failure");
+        },
+      });
+    } finally {
+      console.warn = origWarn;
+    }
+    expect(warnings).toEqual([]);
+  });
+
+  it("writes successfully when openDb succeeds (smoke for the production path)", () => {
+    tryRecordRecipeRun("smoke-recipe");
+    const db = openDb();
+    try {
+      const row = db
+        .query<{ recipe_id: string; run_count: number }>(
+          "SELECT recipe_id, run_count FROM recipe_recency WHERE recipe_id = 'smoke-recipe'",
+        )
+        .get();
+      expect(row).toEqual({ recipe_id: "smoke-recipe", run_count: 1 });
+    } finally {
+      closeDb(db, { readonly: true });
+    }
+  });
+});
+
+describe("tryRecordRecipeRun — opt-out (recipeRecency: false)", () => {
+  it("short-circuits the upsert when recipeRecency: false", () => {
+    initCodemap(resolveCodemapConfig(projectRoot, { recipeRecency: false }));
+
+    // Thrower factory — fires only if the short-circuit fails.
+    let openDbCalled = false;
+    tryRecordRecipeRun("opt-out-recipe", {
+      _openDb: () => {
+        openDbCalled = true;
+        throw new Error("openDb should not be called when opt-out");
+      },
+    });
+    expect(openDbCalled).toBe(false);
+
+    initCodemap(resolveCodemapConfig(projectRoot, undefined));
+
+    const db = openDb();
+    try {
+      const rows = db
+        .query<{ n: number }>("SELECT COUNT(*) AS n FROM recipe_recency")
+        .all();
+      expect(rows[0]?.n).toBe(0);
+    } finally {
+      closeDb(db, { readonly: true });
+    }
+  });
+
+  it("writes normally when recipeRecency: true (default)", () => {
+    initCodemap(resolveCodemapConfig(projectRoot, { recipeRecency: true }));
+    tryRecordRecipeRun("explicit-on-recipe");
+    initCodemap(resolveCodemapConfig(projectRoot, undefined));
+
+    const db = openDb();
+    try {
+      const row = db
+        .query<{ recipe_id: string; run_count: number }>(
+          "SELECT recipe_id, run_count FROM recipe_recency WHERE recipe_id = 'explicit-on-recipe'",
+        )
+        .get();
+      expect(row).toEqual({ recipe_id: "explicit-on-recipe", run_count: 1 });
+    } finally {
+      closeDb(db, { readonly: true });
+    }
+  });
+});
diff --git a/src/application/recipe-recency.ts b/src/application/recipe-recency.ts
new file mode 100644
index 0000000..a6553ad
--- /dev/null
+++ b/src/application/recipe-recency.ts
@@ -0,0 +1,209 @@
+import { isAbsolute, resolve } from "node:path";
+
+import { closeDb, openDb } from "../db";
+import type { CodemapDatabase } from "../db";
+import { getRecipeRecencyEnabled } from "../runtime";
+import { STATE_DIR_DEFAULT } from "./state-dir";
+
+/**
+ * Write-path imports (`tryRecordRecipeRun` / `recordRecipeRun`) are restricted
+ * to `tool-handlers.ts` + `cmd-query.ts` (+ the test file). Re-runnable
+ * forbidden-edge query lives at [`docs/architecture.md` § Boundary verification —
+ * `recipe_recency` write path](../../docs/architecture.md#boundary-verification--recipe_recency-write-path).
+ * Read-path imports (`enrichWithRecency` / `loadRecipeRecency`) are unrestricted.
+ *
+ * Schema + lifecycle: [`docs/architecture.md` § `recipe_recency`](../../docs/architecture.md#recipe_recency--per-recipe-last-run--run-count-user-data-strict-without-rowid).
+ */
+export interface RecipeRecencyRow {
+  recipe_id: string;
+  last_run_at: number;
+  run_count: number;
+}
+
+/** 90-day rolling retention window. Tests inject `cutoffMs` directly. */
+export const RECENCY_WINDOW_MS = 90 * 24 * 60 * 60 * 1000;
+
+interface RecordRunOpts {
+  db: CodemapDatabase;
+  recipeId: string;
+  /** Override for tests; defaults to `Date.now()`. */
+  now?: number;
+}
+
+/**
+ * Eager prune + upsert in a single transaction (one fsync, atomic).
+ * Prune lives on the write path so catalog reads stay side-effect free.
+ * Caller is `tryRecordRecipeRun`, which guards "successful run only".
+ */
+export function recordRecipeRun(opts: RecordRunOpts): void {
+  const { db, recipeId } = opts;
+  const now = opts.now ?? Date.now();
+  const tx = db.transaction(() => {
+    db.run("DELETE FROM recipe_recency WHERE last_run_at < ?", [
+      now - RECENCY_WINDOW_MS,
+    ]);
+    db.run(
+      `INSERT INTO recipe_recency (recipe_id, last_run_at, run_count)
+       VALUES (?, ?, 1)
+       ON CONFLICT(recipe_id) DO UPDATE SET
+         last_run_at = excluded.last_run_at,
+         run_count   = recipe_recency.run_count + 1`,
+      [recipeId, now],
+    );
+  });
+  tx();
+}
+
+/**
+ * The wrapper both write sites call (`handleQueryRecipe` for MCP/HTTP +
+ * `runQueryCmd` for CLI). Opens its own DB because `executeQuery` runs
+ * with `PRAGMA query_only = 1` and can't double as the writer. Swallows
+ * every error — recency-write failures NEVER block the recipe response.
+ *
+ * Caller contract: only call AFTER recipe execution returns successfully.
+ *
+ * `_openDb` is a test seam — production omits it.
+ */
+export function tryRecordRecipeRun(
+  recipeId: string,
+  opts?: { quiet?: boolean; _openDb?: () => CodemapDatabase },
+): void {
+  // Bail on opt-out, OR on uninitialised-runtime (the toggle-getter
+  // throws) — openDb shares the same runtime and would fail anyway.
+  try {
+    if (!getRecipeRecencyEnabled()) return;
+  } catch {
+    return;
+  }
+  let db: CodemapDatabase | undefined;
+  try {
+    db = (opts?._openDb ?? openDb)();
+    recordRecipeRun({ db, recipeId });
+  } catch (err) {
+    if (!opts?.quiet) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.warn(`[recency] write failed: ${msg}`);
+    }
+  } finally {
+    if (db !== undefined) {
+      try {
+        closeDb(db);
+      } catch {
+        // Already in error path; nothing useful to do.
+      }
+    }
+  }
+}
+
+interface PruneOpts {
+  db: CodemapDatabase;
+  /** Cutoff epoch ms — rows with `last_run_at < cutoffMs` get deleted. */
+  cutoffMs: number;
+}
+
+/**
+ * Maintenance helper for tests / ad-hoc CLI use; production pruning lives
+ * inside `recordRecipeRun`. Reads never call this — catalog stays pure.
+ */
+export function pruneRecipeRecency(opts: PruneOpts): void {
+  const { db, cutoffMs } = opts;
+  db.run("DELETE FROM recipe_recency WHERE last_run_at < ?", [cutoffMs]);
+}
+
+interface LoadOpts {
+  db: CodemapDatabase;
+  /** Override for tests; defaults to `Date.now()`. */
+  now?: number;
+}
+
+/**
+ * Pure read for the catalog renderers — filters to the 90-day window with
+ * `WHERE last_run_at >= ?`; never DELETEs. Returns a Map keyed by
+ * `recipe_id` so callers can `map.get(entry.id) ?? null` for never-run.
+ */
+export function loadRecipeRecency(
+  opts: LoadOpts,
+): Map<string, { last_run_at: number; run_count: number }> {
+  const { db } = opts;
+  const now = opts.now ?? Date.now();
+  const cutoff = now - RECENCY_WINDOW_MS;
+  const rows = db
+    .query<RecipeRecencyRow>(
+      "SELECT recipe_id, last_run_at, run_count FROM recipe_recency WHERE last_run_at >= ?",
+    )
+    .all(cutoff);
+  const map = new Map<string, { last_run_at: number; run_count: number }>();
+  for (const row of rows) {
+    map.set(row.recipe_id, {
+      last_run_at: row.last_run_at,
+      run_count: row.run_count,
+    });
+  }
+  return map;
+}
+
+/**
+ * Per-entry shape inlined onto every `--recipes-json` row. `null` /
+ * `0` for recipes never executed.
+ */
+export interface RecipeRecencyFields {
+  last_run_at: number | null;
+  run_count: number;
+}
+
+/**
+ * Resolve `<state-dir>/index.db` from CLI inputs without mutating the
+ * runtime singleton — `--recipes-json` runs before `initCodemap()` and
+ * must stay zero-side-effect. Mirrors `resolveStateDir` precedence
+ * (`cliFlag > env > default`).
+ */
+export function resolveRecencyDbPath(opts: {
+  root: string;
+  stateDir: string | undefined;
+}): string {
+  const raw =
+    opts.stateDir ?? process.env.CODEMAP_STATE_DIR ?? STATE_DIR_DEFAULT;
+  const dir = isAbsolute(raw) ? raw : resolve(opts.root, raw);
+  return resolve(dir, "index.db");
+}
+
+/**
+ * Read-side enricher for `--recipes-json` + the matching MCP/HTTP catalog
+ * resources. Live every call — caching at this layer would freeze recency
+ * at first-read for the lifetime of `codemap mcp` / `codemap serve`.
+ *
+ * Failure-isolated like {@link tryRecordRecipeRun}: any DB-open / read
+ * failure returns entries with `null` / `0` fallbacks. The optional
+ * `openDb` factory is for callers without an `initCodemap()` runtime
+ * (CLI `--recipes-json` before bootstrap supplies a path-based opener).
+ */
+export function enrichWithRecency<T extends { id: string }>(
+  entries: ReadonlyArray<T>,
+  opts?: { openDb?: () => CodemapDatabase },
+): Array<T & RecipeRecencyFields> {
+  let map: Map<string, { last_run_at: number; run_count: number }> | undefined;
+  let db: CodemapDatabase | undefined;
+  try {
+    db = (opts?.openDb ?? openDb)();
+    map = loadRecipeRecency({ db });
+  } catch {
+    // Recency errors NEVER block the catalog — null/0 fallbacks below.
+    map = undefined;
+  } finally {
+    if (db !== undefined) {
+      try {
+        closeDb(db, { readonly: true });
+      } catch {
+        // Already in error path; nothing useful to do.
+      }
+    }
+  }
+  return entries.map((entry) => {
+    const hit = map?.get(entry.id);
+    return {
+      ...entry,
+      last_run_at: hit?.last_run_at ?? null,
+      run_count: hit?.run_count ?? 0,
+    };
+  });
+}
diff --git a/src/application/resource-handlers.test.ts b/src/application/resource-handlers.test.ts
index c46d989..030fae2 100644
--- a/src/application/resource-handlers.test.ts
+++ b/src/application/resource-handlers.test.ts
@@ -129,3 +129,103 @@ describe("listResources", () => {
     expect(uris).toContain("codemap://symbols/{name}");
   });
 });
+
+describe("readResource — codemap://recipes (recency inline)", () => {
+  it("includes last_run_at + run_count fields on every entry", () => {
+    const r = readResource("codemap://recipes");
+    expect(r).toBeDefined();
+    const entries = JSON.parse(r!.text) as Array<{
+      id: string;
+      last_run_at: number | null;
+      run_count: number;
+    }>;
+    expect(entries.length).toBeGreaterThan(0);
+    for (const entry of entries) {
+      expect("last_run_at" in entry).toBe(true);
+      expect("run_count" in entry).toBe(true);
+      expect(entry.run_count).toBe(0);
+      expect(entry.last_run_at).toBeNull();
+    }
+  });
+
+  it("populates real recency for recipes that have been run", () => {
+    // Fresh timestamp — `loadRecipeRecency` lazily prunes anything older
+    // than 90 days, so a fixed past `ts` would race-delete on slow runs.
+    const ts = Date.now();
+    const db = openDb();
+    try {
+      db.run(
+        "INSERT INTO recipe_recency (recipe_id, last_run_at, run_count) VALUES (?, ?, ?)",
+        ["fan-out", ts, 7],
+      );
+    } finally {
+      closeDb(db);
+    }
+
+    const r = readResource("codemap://recipes");
+    const entries = JSON.parse(r!.text) as Array<{
+      id: string;
+      last_run_at: number | null;
+      run_count: number;
+    }>;
+    const fanOut = entries.find((e) => e.id === "fan-out");
+    expect(fanOut).toBeDefined();
+    expect(fanOut!.last_run_at).toBe(ts);
+    expect(fanOut!.run_count).toBe(7);
+    // Untouched recipes still null/0.
+    const barrel = entries.find((e) => e.id === "barrel-files");
+    expect(barrel?.last_run_at).toBeNull();
+    expect(barrel?.run_count).toBe(0);
+  });
+
+  it("reads live every call (no stale cache between reads)", () => {
+    const r1 = readResource("codemap://recipes");
+    const before = (
+      JSON.parse(r1!.text) as Array<{ id: string; run_count: number }>
+    ).find((e) => e.id === "fan-in");
+    expect(before?.run_count).toBe(0);
+
+    const ts = Date.now();
+    const db = openDb();
+    try {
+      db.run(
+        "INSERT INTO recipe_recency (recipe_id, last_run_at, run_count) VALUES (?, ?, ?)",
+        ["fan-in", ts, 3],
+      );
+    } finally {
+      closeDb(db);
+    }
+
+    const r2 = readResource("codemap://recipes");
+    const after = (
+      JSON.parse(r2!.text) as Array<{ id: string; run_count: number }>
+    ).find((e) => e.id === "fan-in");
+    expect(after?.run_count).toBe(3);
+  });
+});
+
+describe("readResource — codemap://recipes/{id} (recency inline)", () => {
+  it("returns entry with last_run_at + run_count fields", () => {
+    const ts = Date.now();
+    const db = openDb();
+    try {
+      db.run(
+        "INSERT INTO recipe_recency (recipe_id, last_run_at, run_count) VALUES (?, ?, ?)",
+        ["fan-out", ts, 4],
+      );
+    } finally {
+      closeDb(db);
+    }
+
+    const r = readResource("codemap://recipes/fan-out");
+    expect(r).toBeDefined();
+    const entry = JSON.parse(r!.text) as {
+      id: string;
+      last_run_at: number | null;
+      run_count: number;
+    };
+    expect(entry.id).toBe("fan-out");
+    expect(entry.last_run_at).toBe(ts);
+    expect(entry.run_count).toBe(4);
+  });
+});
diff --git a/src/application/resource-handlers.ts b/src/application/resource-handlers.ts
index 88ba037..f264541 100644
--- a/src/application/resource-handlers.ts
+++ b/src/application/resource-handlers.ts
@@ -17,6 +17,7 @@ import {
   getQueryRecipeCatalogEntry,
   listQueryRecipeCatalog,
 } from "./query-recipes";
+import { enrichWithRecency } from "./recipe-recency";
 import { buildShowResult, findSymbolsByName } from "./show-engine";
 
 export interface ResourcePayload {
@@ -24,20 +25,21 @@ export interface ResourcePayload {
   text: string;
 }
 
-let recipesCache: ResourcePayload | undefined;
+// Recipes / one-recipe deliberately NOT cached — inline recency fields
+// (last_run_at / run_count) need to reflect mutations during the
+// `codemap mcp` / `codemap serve` lifetime; a cached snapshot would
+// freeze them at first-read. Schema / skill stay cached — neither
+// changes mid-session.
 let schemaCache: ResourcePayload | undefined;
 let skillCache: ResourcePayload | undefined;
-const oneRecipeCache = new Map<string, ResourcePayload>();
 
 /**
  * Test-only escape hatch — drops every cached payload so a temp-DB test
  * can re-read with fresh state. Production code never calls this.
  */
 export function _resetResourceCachesForTests(): void {
-  recipesCache = undefined;
   schemaCache = undefined;
   skillCache = undefined;
-  oneRecipeCache.clear();
 }
 
 /**
@@ -110,25 +112,20 @@ export function listResources(): { uri: string; description: string }[] {
 }
 
 function readRecipesCatalog(): ResourcePayload {
-  if (recipesCache !== undefined) return recipesCache;
-  recipesCache = {
+  return {
     mimeType: "application/json",
-    text: JSON.stringify(listQueryRecipeCatalog()),
+    text: JSON.stringify(enrichWithRecency(listQueryRecipeCatalog())),
   };
-  return recipesCache;
 }
 
 function readOneRecipe(id: string): ResourcePayload | undefined {
-  const cached = oneRecipeCache.get(id);
-  if (cached !== undefined) return cached;
   const entry = getQueryRecipeCatalogEntry(id);
   if (entry === undefined) return undefined;
-  const payload: ResourcePayload = {
+  const [enriched] = enrichWithRecency([entry]);
+  return {
     mimeType: "application/json",
-    text: JSON.stringify(entry),
+    text: JSON.stringify(enriched),
   };
-  oneRecipeCache.set(id, payload);
-  return payload;
 }
 
 function readSchema(): ResourcePayload {
diff --git a/src/application/tool-handlers.ts b/src/application/tool-handlers.ts
index b9cbf9d..c05513f 100644
--- a/src/application/tool-handlers.ts
+++ b/src/application/tool-handlers.ts
@@ -55,6 +55,7 @@ import {
 } from "./query-recipes";
 import { resolveRecipeParams } from "./recipe-params";
 import type { RecipeParamValue, RecipeParamValues } from "./recipe-params";
+import { tryRecordRecipeRun } from "./recipe-recency";
 import { runCodemapIndex } from "./run-index";
 import {
   buildShowResult,
@@ -281,7 +282,7 @@ export function handleQueryRecipe(
     ) {
       const incompat = formatToolIncompatibility(args.format, args);
       if (incompat !== undefined) return err(incompat);
-      return runFormattedQuery({
+      const result = runFormattedQuery({
         sql,
         recipeId: args.recipe,
         recipeActions,
@@ -290,6 +291,9 @@ export function handleQueryRecipe(
         format: args.format,
         root,
       });
+      // Successful runs only; failure-isolated inside the helper.
+      if (result.ok) tryRecordRecipeRun(args.recipe);
+      return result;
     }
     const payload = executeQuery({
       sql,
@@ -301,6 +305,7 @@ export function handleQueryRecipe(
       root,
     });
     if (isEnginePayloadError(payload)) return err(payload.error);
+    tryRecordRecipeRun(args.recipe);
     return ok(payload);
   } catch (e) {
     return err(e instanceof Error ? e.message : String(e), 500);
diff --git a/src/cli/cmd-query-recency.test.ts b/src/cli/cmd-query-recency.test.ts
new file mode 100644
index 0000000..79e58db
--- /dev/null
+++ b/src/cli/cmd-query-recency.test.ts
@@ -0,0 +1,188 @@
+/**
+ * End-to-end CLI coverage for recipe-recency, including the `--ci` path
+ * (recipe succeeds, exit=1 is the gating signal — recency must still record).
+ * Per-test temp project + full-index so `--recipe` calls return real rows.
+ */
+
+import {
+  afterEach,
+  beforeAll,
+  beforeEach,
+  describe,
+  expect,
+  it,
+} from "bun:test";
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const repoRoot = join(import.meta.dir, "..", "..");
+const indexTs = join(repoRoot, "src", "index.ts");
+let bunBin: string | null = null;
+
+async function runCli(
+  args: string[],
+  envOverride: Record<string, string> = {},
+): Promise<{ exitCode: number; out: string; err: string }> {
+  if (bunBin === null) {
+    throw new Error("cmd-query-recency: bunBin not initialised by beforeAll.");
+  }
+  const proc = Bun.spawn([bunBin, indexTs, ...args], {
+    cwd: repoRoot,
+    stdout: "pipe",
+    stderr: "pipe",
+    env: { ...process.env, ...envOverride },
+  });
+  const exitCode = await proc.exited;
+  const out = await new Response(proc.stdout).text();
+  const err = await new Response(proc.stderr).text();
+  return { exitCode, out, err };
+}
+
+let projectRoot: string;
+
+// Minimal indexable project: one TS file with two symbols + an import
+// graph so dependency / symbol / import recipes have rows to return.
+const tinySource = `import { helper } from "./helper";
+
+export function entry(): number {
+  return helper() + 1;
+}
+
+export const VALUE = "x";
+`;
+const helperSource = `export function helper(): number {
+  return 42;
+}
+`;
+
+beforeAll(() => {
+  bunBin = Bun.which("bun");
+  if (!bunBin || !existsSync(indexTs)) {
+    throw new Error(
+      `cmd-query-recency: cannot locate Bun (${bunBin}) or src entry (${indexTs}).`,
+    );
+  }
+});
+
+beforeEach(async () => {
+  projectRoot = mkdtempSync(join(tmpdir(), "codemap-cli-recency-"));
+  mkdirSync(join(projectRoot, "src"), { recursive: true });
+  writeFileSync(join(projectRoot, "src", "entry.ts"), tinySource, "utf8");
+  writeFileSync(join(projectRoot, "src", "helper.ts"), helperSource, "utf8");
+  writeFileSync(join(projectRoot, "package.json"), "{}\n", "utf8");
+  // Full index so subsequent --recipe calls have real data.
+  const idx = await runCli(["--full"], { CODEMAP_ROOT: projectRoot });
+  expect(idx.exitCode).toBe(0);
+});
+
+afterEach(() => {
+  rmSync(projectRoot, { recursive: true, force: true });
+});
+
+async function loadRunCount(recipeId: string): Promise<number> {
+  const r = await runCli(
+    [
+      "query",
+      "--json",
+      `SELECT run_count FROM recipe_recency WHERE recipe_id = '${recipeId}'`,
+    ],
+    { CODEMAP_ROOT: projectRoot },
+  );
+  expect(r.exitCode).toBe(0);
+  const rows = JSON.parse(r.out) as Array<{ run_count: number }>;
+  return rows[0]?.run_count ?? 0;
+}
+
+describe("runQueryCmd — recipe-recency CLI write site", () => {
+  it("records recency on plain --recipe + --json", async () => {
+    const before = await loadRunCount("fan-out");
+    const r = await runCli(["query", "--recipe", "fan-out", "--json"], {
+      CODEMAP_ROOT: projectRoot,
+    });
+    expect(r.exitCode).toBe(0);
+    expect(await loadRunCount("fan-out")).toBe(before + 1);
+  });
+
+  it("records recency on --ci + --format sarif WITH findings (CI gate exits 1, recipe succeeded)", async () => {
+    // Regression: don't undercount when --ci's gate-exit (1) collides
+    // with the success-detection logic. `unimported-exports` reliably
+    // returns rows on this fixture so the gate fires.
+    const before = await loadRunCount("unimported-exports");
+    const r = await runCli(
+      ["query", "--recipe", "unimported-exports", "--format", "sarif", "--ci"],
+      { CODEMAP_ROOT: projectRoot },
+    );
+    expect(r.exitCode).toBe(1); // CI gate fired (findings present)
+    expect(await loadRunCount("unimported-exports")).toBe(before + 1); // run STILL recorded
+  });
+
+  it("records recency on --ci with NO findings (recipe ran cleanly, no gate fired)", async () => {
+    // `deprecated-symbols` returns 0 rows on a fixture with no `@deprecated`.
+    const before = await loadRunCount("deprecated-symbols");
+    const r = await runCli(
+      ["query", "--recipe", "deprecated-symbols", "--format", "sarif", "--ci"],
+      { CODEMAP_ROOT: projectRoot },
+    );
+    expect(r.exitCode).toBe(0);
+    expect(await loadRunCount("deprecated-symbols")).toBe(before + 1);
+  });
+
+  it("does NOT record recency on a recipe failure (deterministic — unknown recipe id)", async () => {
+    // Unknown recipe id is the most stable forced-failure trigger
+    // (param-validation rules can evolve; the "unknown recipe" error
+    // is fundamental to the catalog lookup).
+    const r = await runCli(
+      ["query", "--recipe", "recipe-does-not-exist", "--json"],
+      { CODEMAP_ROOT: projectRoot },
+    );
+    expect(r.exitCode).toBe(1);
+    const total = await runCli(
+      ["query", "--json", "SELECT COUNT(*) AS n FROM recipe_recency"],
+      { CODEMAP_ROOT: projectRoot },
+    );
+    const n = (JSON.parse(total.out) as Array<{ n: number }>)[0]?.n;
+    expect(n).toBe(0);
+  });
+
+  it("does NOT record recency on ad-hoc SQL (recipeId undefined)", async () => {
+    const before = await loadRunCount("fan-out");
+    const r = await runCli(
+      ["query", "--json", "SELECT name FROM symbols LIMIT 1"],
+      { CODEMAP_ROOT: projectRoot },
+    );
+    expect(r.exitCode).toBe(0);
+    const all = await runCli(
+      ["query", "--json", "SELECT COUNT(*) AS n FROM recipe_recency"],
+      { CODEMAP_ROOT: projectRoot },
+    );
+    const totalRows = (JSON.parse(all.out) as Array<{ n: number }>)[0]?.n;
+    expect(await loadRunCount("fan-out")).toBe(before);
+    expect(totalRows).toBeDefined();
+  });
+
+  it("does NOT record recency when recipeRecency: false in user config", async () => {
+    mkdirSync(join(projectRoot, ".codemap"), { recursive: true });
+    writeFileSync(
+      join(projectRoot, ".codemap", "config.json"),
+      JSON.stringify({ recipeRecency: false }, null, 2),
+      "utf8",
+    );
+    const r = await runCli(["query", "--recipe", "fan-out", "--json"], {
+      CODEMAP_ROOT: projectRoot,
+    });
+    expect(r.exitCode).toBe(0);
+    const total = await runCli(
+      ["query", "--json", "SELECT COUNT(*) AS n FROM recipe_recency"],
+      { CODEMAP_ROOT: projectRoot },
+    );
+    const n = (JSON.parse(total.out) as Array<{ n: number }>)[0]?.n;
+    expect(n).toBe(0);
+  });
+});
diff --git a/src/cli/cmd-query.ts b/src/cli/cmd-query.ts
index 45daf62..b3c31ba 100644
--- a/src/cli/cmd-query.ts
+++ b/src/cli/cmd-query.ts
@@ -1,3 +1,5 @@
+import { existsSync } from "node:fs";
+
 import {
   getCurrentCommit,
   printQueryResult,
@@ -29,6 +31,11 @@ import type {
   RecipeParamValue,
   RecipeParamValues,
 } from "../application/recipe-params";
+import {
+  enrichWithRecency,
+  resolveRecencyDbPath,
+  tryRecordRecipeRun,
+} from "../application/recipe-recency";
 import {
   closeDb,
   deleteQueryBaseline,
@@ -50,6 +57,7 @@ import {
   makePackageBucketizer,
 } from "../group-by";
 import { getProjectRoot } from "../runtime";
+import { openCodemapDatabase } from "../sqlite-db";
 import { bootstrapCodemap } from "./bootstrap-codemap";
 
 /**
@@ -601,9 +609,37 @@ function formatIncompatibility(
   return `codemap: --format ${fmt} cannot be combined with ${offenders.join(", ")} (different output shapes — formatted outputs only support flat row lists).`;
 }
 
-/** Print the bundled recipe catalog as JSON to stdout (no DB access). */
-export function printRecipesCatalogJson(): void {
-  console.log(JSON.stringify(listQueryRecipeCatalog(), null, 2));
+/**
+ * Print the bundled recipe catalog as JSON to stdout. Each entry carries
+ * `last_run_at` + `run_count` recency fields when an indexed DB exists,
+ * else null/0 fallbacks. The verb runs before `bootstrapCodemap()` (the
+ * catalog has historically been "no DB required") — keep it side-effect
+ * free by using a path-based opener instead of `initCodemap()`.
+ */
+export function printRecipesCatalogJson(opts?: {
+  root?: string;
+  stateDir?: string | undefined;
+}): void {
+  const root = opts?.root;
+  const dbFactory =
+    root === undefined
+      ? undefined
+      : () => {
+          const dbPath = resolveRecencyDbPath({
+            root,
+            stateDir: opts?.stateDir,
+          });
+          // Throw on never-indexed; enrichWithRecency catches and falls
+          // back to null/0 entries (no .codemap dir gets created).
+          if (!existsSync(dbPath)) {
+            throw new Error(`recipe-recency: no DB at ${dbPath}`);
+          }
+          return openCodemapDatabase(dbPath);
+        };
+  const enriched = enrichWithRecency(listQueryRecipeCatalog(), {
+    openDb: dbFactory,
+  });
+  console.log(JSON.stringify(enriched, null, 2));
 }
 
 /** Print one recipe's SQL to stdout, or false if the id is unknown (caller should exit 1). */
@@ -779,6 +815,10 @@ export async function runQueryCmd(opts: {
   // emit plain stderr for `--format diff-json` / `sarif` / etc., breaking
   // pipelines that key off the JSON envelope.
   const structuredErrors = effectiveFormat !== "text";
+  // Recency tracker reads this in finally. Don't use process.exitCode:
+  // --ci sets it to 1 on findings (success, not failure); exitCode also
+  // poisons across calls when this helper runs multiple times per process.
+  let recipeQuerySucceeded = false;
   try {
     await bootstrapCodemap(opts);
 
@@ -807,6 +847,7 @@ export async function runQueryCmd(opts: {
     // the diff semantics are about row identity, not bucketing. (--summary still
     // composes: collapses the diff to {added: N, removed: N}.)
     if (opts.saveBaseline !== undefined) {
+      const before = process.exitCode;
       runSaveBaseline({
         sql: opts.sql,
         json: isJson,
@@ -818,9 +859,11 @@ export async function runQueryCmd(opts: {
         changedFiles,
         bindValues: bindValues.values,
       });
+      if (process.exitCode !== 1 || before === 1) recipeQuerySucceeded = true;
       return;
     }
     if (opts.baseline !== undefined) {
+      const before = process.exitCode;
       runBaselineDiff({
         sql: opts.sql,
         json: isJson,
@@ -831,10 +874,12 @@ export async function runQueryCmd(opts: {
         recipeActions,
         bindValues: bindValues.values,
       });
+      if (process.exitCode !== 1 || before === 1) recipeQuerySucceeded = true;
       return;
     }
 
     if (opts.groupBy !== undefined) {
+      const before = process.exitCode;
       runGroupedQuery({
         sql: opts.sql,
         json: isJson,
@@ -845,18 +890,25 @@ export async function runQueryCmd(opts: {
         bindValues: bindValues.values,
         root: getProjectRoot(),
       });
+      if (process.exitCode !== 1 || before === 1) recipeQuerySucceeded = true;
       return;
     }
 
     if (effectiveFormat !== "text" && effectiveFormat !== "json") {
-      const code = printFormattedQuery(opts.sql, {
+      const result = printFormattedQuery(opts.sql, {
         format: effectiveFormat,
         recipeId: opts.recipeId,
         changedFiles,
         bindValues: bindValues.values,
         ci: opts.ci === true,
       });
-      if (code !== 0) process.exitCode = code;
+      if (result.ok) {
+        // exitCode=1 here is the --ci gating signal, not a failure.
+        recipeQuerySucceeded = true;
+        if (result.exitCode !== 0) process.exitCode = result.exitCode;
+      } else {
+        process.exitCode = 1;
+      }
       return;
     }
 
@@ -867,10 +919,15 @@ export async function runQueryCmd(opts: {
       recipeActions,
       bindValues: bindValues.values,
     });
+    if (code === 0) recipeQuerySucceeded = true;
     if (code !== 0) process.exitCode = code;
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     emitErrorMaybeJson(msg, structuredErrors);
+  } finally {
+    if (opts.recipeId !== undefined && recipeQuerySucceeded) {
+      tryRecordRecipeRun(opts.recipeId);
+    }
   }
 }
 
@@ -966,6 +1023,13 @@ export async function runDropBaselineCmd(opts: {
  * findings shape; annotations emit nothing + the same warning. See
  * [`docs/architecture.md` § Output formatters](../../docs/architecture.md#cli-usage).
  */
+/**
+ * Disambiguates a CI-gating exit (recipe SUCCEEDED, `--ci` wants exit 1
+ * to flag findings) from a real failure (SQL error, formatter rejection).
+ * Callers (recency tracker, etc.) need this distinction.
+ */
+type FormattedQueryResult = { ok: true; exitCode: 0 | 1 } | { ok: false };
+
 function printFormattedQuery(
   sql: string,
   opts: {
@@ -973,10 +1037,10 @@ function printFormattedQuery(
     recipeId: string | undefined;
     changedFiles: Set<string> | undefined;
     bindValues: RecipeParamValue[] | undefined;
-    /** `--ci`: suppress no-locatable-rows warning + return 1 on `rows.length > 0`. */
+    /** `--ci`: suppress no-locatable-rows warning + exit 1 on `rows.length > 0`. */
     ci?: boolean;
   },
-): number {
+): FormattedQueryResult {
   let db: Awaited<ReturnType<typeof openDb>> | undefined;
   try {
     db = openDb();
@@ -1018,38 +1082,34 @@ function printFormattedQuery(
       });
       console.log(out);
       // `--ci` gates the runner step on findings (non-zero exit).
-      return opts.ci === true && rows.length > 0 ? 1 : 0;
+      return {
+        ok: true,
+        exitCode: opts.ci === true && rows.length > 0 ? 1 : 0,
+      };
     }
 
     if (opts.format === "mermaid") {
-      const out = formatMermaid({
-        rows,
-        recipeId: opts.recipeId,
-      });
-      console.log(out);
-      return 0;
+      console.log(formatMermaid({ rows, recipeId: opts.recipeId }));
+      return { ok: true, exitCode: 0 };
     }
 
     if (opts.format === "diff") {
       console.log(formatDiff({ rows, projectRoot: getProjectRoot() }));
-      return 0;
+      return { ok: true, exitCode: 0 };
     }
 
     if (opts.format === "diff-json") {
       console.log(formatDiffJson({ rows, projectRoot: getProjectRoot() }));
-      return 0;
+      return { ok: true, exitCode: 0 };
     }
 
-    const annotations = formatAnnotations({
-      rows,
-      recipeId: opts.recipeId,
-    });
+    const annotations = formatAnnotations({ rows, recipeId: opts.recipeId });
     if (annotations.length > 0) console.log(annotations);
-    return 0;
+    return { ok: true, exitCode: 0 };
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     console.log(JSON.stringify({ error: msg }));
-    return 1;
+    return { ok: false };
   } finally {
     if (db !== undefined) closeDb(db, { readonly: true });
   }
diff --git a/src/cli/main.ts b/src/cli/main.ts
index cdd08ca..329ba02 100644
--- a/src/cli/main.ts
+++ b/src/cli/main.ts
@@ -367,7 +367,7 @@ Copies bundled agent templates into .agents/ under the project root.
       process.exit(1);
     }
     if (parsed.kind === "recipesCatalog") {
-      printRecipesCatalogJson();
+      printRecipesCatalogJson({ root, stateDir });
       return;
     }
     if (parsed.kind === "printRecipeSql") {
diff --git a/src/config.ts b/src/config.ts
index 004bb81..7df9ab5 100644
--- a/src/config.ts
+++ b/src/config.ts
@@ -90,6 +90,12 @@ export const codemapUserConfigSchema = z
       .describe(
         "Enable FTS5 full-text indexing of file content into the `source_fts` virtual table. Default `false` — FTS5 grows `.codemap/index.db` ~30–50% on text-heavy projects. Override at the CLI with `--with-fts` (CLI wins; logs a stderr line on override).",
       ),
+    recipeRecency: z
+      .boolean()
+      .optional()
+      .describe(
+        "Track per-recipe `last_run_at` + `run_count` in the `recipe_recency` table; surfaces inline on `--recipes-json` for agent-host ranking. Default `true` (opt-out). Set `false` to short-circuit every write — no rows ever land. Local-only — no upload primitive. See `docs/architecture.md` § `recipe_recency`.",
+      ),
     boundaries: z
       .array(
         z
@@ -172,6 +178,14 @@ export interface ResolvedCodemapConfig {
    * flag; CLI wins. See `docs/plans/fts5-mermaid.md`.
    */
   readonly fts5: boolean;
+  /**
+   * Recipe-recency tracking toggle. `true` (default) populates the
+   * `recipe_recency` table on every successful recipe run and inlines
+   * `last_run_at` / `run_count` on `--recipes-json` reads. `false`
+   * short-circuits every write — no rows ever land. Local-only — no
+   * upload primitive. See `docs/architecture.md` § `recipe_recency`.
+   */
+  readonly recipeRecency: boolean;
   /**
    * Reconciled into the `boundary_rules` table on every index pass. The
    * bundled `boundary-violations` recipe joins this against `dependencies`
@@ -282,6 +296,9 @@ export function resolveCodemapConfig(
     action: rule.action ?? "deny",
   }));
 
+  // Default ON (opt-out, not opt-in). Only `false` disables.
+  const recipeRecency = parsed?.recipeRecency !== false;
+
   return {
     root: absRoot,
     stateDir,
@@ -291,6 +308,7 @@ export function resolveCodemapConfig(
     tsconfigPath,
     fts5,
     boundaries,
+    recipeRecency,
   };
 }
 
diff --git a/src/db.test.ts b/src/db.test.ts
index ad15a31..c5a6767 100644
--- a/src/db.test.ts
+++ b/src/db.test.ts
@@ -1,4 +1,6 @@
 import { describe, expect, it } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
 
 import {
   closeDb,
@@ -18,6 +20,30 @@ import {
 } from "./db";
 import { openCodemapDatabase } from "./sqlite-db";
 
+describe("createTables() DDL — Node split-on-`;` invariant", () => {
+  // `bun test` masks this regression class; see `.agents/lessons.md`
+  // "Semicolons inside `--` line comments in `db.ts` DDL strings".
+  it("contains no comment-only fragments after split-on-`;`", () => {
+    const src = readFileSync(join(import.meta.dir, "db.ts"), "utf-8");
+    const match = src.match(/createTables[^`]*`([\s\S]+?)`/);
+    expect(match).not.toBeNull();
+    const sql = match![1]!;
+    const fragments = sql
+      .split(";")
+      .map((s) => s.trim())
+      .filter(Boolean);
+    const offenders = fragments.filter((f) => {
+      const stripped = f
+        .split("\n")
+        .map((l) => l.trim())
+        .filter((l) => l && !l.startsWith("--"))
+        .join(" ");
+      return stripped === "";
+    });
+    expect(offenders).toEqual([]);
+  });
+});
+
 describe("SQLite layer (in-memory)", () => {
   it("creates schema and round-trips meta", () => {
     const db = openCodemapDatabase(":memory:");
diff --git a/src/db.ts b/src/db.ts
index 496f13b..1b1651c 100644
--- a/src/db.ts
+++ b/src/db.ts
@@ -1,7 +1,8 @@
 import { openCodemapDatabase } from "./sqlite-db";
 import type { CodemapDatabase, BindValues } from "./sqlite-db";
 
-/** Bump on any DDL change; `createSchema()` auto-rebuilds on mismatch. */
+/** Bump only on rebuild-forcing DDL changes (NOT on additive tables/columns).
+ *  See `docs/architecture.md` § Schema Versioning. */
 export const SCHEMA_VERSION = 10;
 
 /**
@@ -193,6 +194,19 @@ export function createTables(db: CodemapDatabase) {
       PRIMARY KEY (file_path, name, line_start)
     ) STRICT, WITHOUT ROWID;
 
+    -- User-data table: per-recipe last_run_at + run_count for agent-host
+    -- ranking. Joined inline into --recipes-json / codemap://recipes via
+    -- loadRecipeRecency. Like query_baselines / coverage, intentionally absent
+    -- from dropAll() so --full and SCHEMA_VERSION rebuilds preserve activity
+    -- history. 90-day window is eager-on-write (recordRecipeRun DELETEs stale
+    -- rows before its upsert) — reads stay pure. recipe_id is loose (no FK,
+    -- can match bundled or project recipe ids). See docs/architecture.md.
+    CREATE TABLE IF NOT EXISTS recipe_recency (
+      recipe_id   TEXT PRIMARY KEY,
+      last_run_at INTEGER NOT NULL,
+      run_count   INTEGER NOT NULL DEFAULT 1
+    ) STRICT, WITHOUT ROWID;
+
     -- Config-derived: reconcileBoundaryRules clears and re-fills from
     -- .codemap/config boundaries on every index pass. Dropped on --full
     -- like the other index tables (unlike query_baselines / coverage which
@@ -302,6 +316,11 @@ export function createIndexes(db: CodemapDatabase) {
     -- The (file_path, name) prefix also covers GROUP BY file_path scans
     -- used by the bundled files-by-coverage recipe (D2 + D13).
     CREATE INDEX IF NOT EXISTS idx_coverage_file_name ON coverage(file_path, name);
+
+    -- Powers the lazy 90-day prune (DELETE WHERE last_run_at < cutoff) inside
+    -- loadRecipeRecency. Tiny table (one row per known recipe id) — index keeps
+    -- the prune predictable as project-recipe counts grow.
+    CREATE INDEX IF NOT EXISTS idx_recipe_recency_last_run ON recipe_recency(last_run_at);
   `);
 }
 
diff --git a/src/runtime.ts b/src/runtime.ts
index 5e50b6a..66dbcf2 100644
--- a/src/runtime.ts
+++ b/src/runtime.ts
@@ -47,6 +47,10 @@ export function getFts5Enabled(): boolean {
   return getCodemapConfig().fts5;
 }
 
+export function getRecipeRecencyEnabled(): boolean {
+  return getCodemapConfig().recipeRecency;
+}
+
 export function getBoundaryRules(): ResolvedCodemapConfig["boundaries"] {
   return getCodemapConfig().boundaries;
 }
diff --git a/templates/agents/rules/codemap.md b/templates/agents/rules/codemap.md
index a7e1a46..2dee163 100644
--- a/templates/agents/rules/codemap.md
+++ b/templates/agents/rules/codemap.md
@@ -29,7 +29,7 @@ Install **[@stainless-code/codemap](https://www.npmjs.com/package/@stainless-cod
 | 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`                                                                                                                                                                                                                                                                                                                             |
+| Recipe catalog (JSON)             | `codemap query --recipes-json` — every entry includes `last_run_at: number \| null` + `run_count: number` recency fields. Rank with `jq 'sort_by(.last_run_at // 0) \| reverse'`. Local-only; opt-out via `.codemap/config` `recipeRecency: false`.                                                                                                        |
 | 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`                                                                                                                                                                                                                                                                                              |
@@ -82,12 +82,12 @@ Validation: SQL is rejected at load time if it starts with DML/DDL (DELETE/DROP/
 
 **Impact (`codemap impact <target>`)**: symbol/file blast-radius walker — replaces hand-composed `WITH RECURSIVE` queries that agents struggle to write. Target auto-resolves: contains `/` or matches `files.path` → file target; otherwise symbol (case-sensitive). Walks compatible graphs by target kind: **symbol** → `calls` (callers / callees by name); **file** → `dependencies` + `imports` (`resolved_path` only). `--via <b>` overrides; mismatched explicit choices land in `skipped_backends` (no error). Cycle-detected via `WITH RECURSIVE` path-string + `instr` check; bounded by `--depth N` (default 3, `0` = unbounded but still cycle-detected and limit-capped) and `--limit N` (default 500). Output envelope: `{target, direction, via, depth_limit, matches: [{depth, direction, edge, kind, name?, file_path}], summary: {nodes, max_depth_reached, by_kind, terminated_by: 'depth'|'limit'|'exhausted'}}`. `--summary` trims `matches` for cheap CI-gate consumption (`jq '.summary.nodes'`) but preserves the count. SARIF / annotations not supported (graph traversal, not findings). Pure transport-agnostic — same logic across CLI, MCP, and HTTP.
 
-**MCP server (`codemap mcp`)**: stdio MCP (Model Context Protocol) server — agents call codemap as JSON-RPC tools instead of shelling out to the CLI on every read. v1 ships one tool per CLI verb plus four lazy-cached resources:
+**MCP server (`codemap mcp`)**: stdio MCP (Model Context Protocol) server — agents call codemap as JSON-RPC tools instead of shelling out to the CLI on every read. v1 ships one tool per CLI verb plus six resources (`codemap://recipes` + `codemap://recipes/{id}` are live read every call so inline `last_run_at` / `run_count` recency stays fresh; `codemap://schema` + `codemap://skill` lazy-cache; `codemap://files/{path}` + `codemap://symbols/{name}` always live):
 
 - **Tools:** `query` / `query_batch` / `query_recipe` / `audit` / `save_baseline` / `list_baselines` / `drop_baseline` / `context` / `validate` / `show` / `snippet` / `impact`. Snake_case keys (Codemap convention matching MCP spec examples + reference servers — spec is convention-agnostic; CLI stays kebab).
 - **`query_batch` (MCP-only):** N statements in one round-trip. Items are `string | {sql, summary?, changed_since?, group_by?}` — string form inherits batch-wide flag defaults, object form overrides on a per-key basis. Per-statement errors are isolated.
 - **`save_baseline` (polymorphic):** one tool, `{name, sql? | recipe?}` with runtime exclusivity check (mirrors the CLI's single `--save-baseline=<name>` verb).
-- **Resources:** `codemap://recipes` (catalog), `codemap://recipes/{id}` (one recipe), `codemap://schema` (live DDL from `sqlite_schema`), `codemap://skill` (bundled SKILL.md text), `codemap://files/{path}` (per-file roll-up: symbols, imports, exports, coverage), `codemap://symbols/{name}` (symbol lookup with `{matches, disambiguation?}` envelope; `?in=<path-prefix>` filter mirrors `show --in`). Catalog resources lazy-cache on first `read_resource`; `files/` and `symbols/` read live every call (no caching) since the index can change between requests under `--watch`.
+- **Resources:** `codemap://recipes` (catalog — live), `codemap://recipes/{id}` (one recipe — live), `codemap://schema` (live DDL from `sqlite_schema`; lazy-cached), `codemap://skill` (bundled SKILL.md text; lazy-cached), `codemap://files/{path}` (per-file roll-up: symbols, imports, exports, coverage — live), `codemap://symbols/{name}` (symbol lookup with `{matches, disambiguation?}` envelope; `?in=<path-prefix>` filter mirrors `show --in` — live). Recipe catalogs read live every call so inline `last_run_at` / `run_count` recency reflects mutations during the server lifetime; `schema` / `skill` cache because their inputs don't change mid-session.
 - **Output shape uniformity:** every tool returns the JSON envelope its CLI counterpart's `--json` would print — no re-mapping.
 
 To use from your agent host: launch `codemap mcp` as the MCP server command. Most hosts (Claude Code, Cursor, Codex) accept a stdio command + working directory; codemap will index the working directory's project root.
diff --git a/templates/agents/skills/codemap/SKILL.md b/templates/agents/skills/codemap/SKILL.md
index ffdf815..33b48f4 100644
--- a/templates/agents/skills/codemap/SKILL.md
+++ b/templates/agents/skills/codemap/SKILL.md
@@ -38,7 +38,7 @@ Replace placeholders (`'...'`) with your module path, file glob, or symbol name.
 
 **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`**.
+**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`**, plus **`last_run_at`** + **`run_count`** recency fields) as JSON (no DB required for the catalog itself; recency populates when an indexed DB exists, otherwise null/0). **`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):
 
@@ -80,10 +80,10 @@ Each emitted delta carries its own `base` metadata so mixed-baseline audits are
 - **`snippet`** — `{name, kind?, in?}`. 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 indexing — line range may have shifted), `missing` (true when file is gone). `source` is always returned when the file exists; agent decides whether to act on stale content or run `codemap` / `codemap --files <path>` to re-index first. No auto-reindex side-effects from this read tool.
 - **`impact`** — `{target, direction?, via?, depth?, limit?, summary?}`. Symbol/file blast-radius walker — replaces hand-composed `WITH RECURSIVE` queries that agents struggle to write reliably. `target` is a symbol name (case-sensitive, exact) OR a project-relative file path (auto-detected by `/` or by matching `files.path`). `direction`: `up` (callers / dependents), `down` (callees / dependencies), `both` (default). `via`: `dependencies`, `calls`, `imports`, `all` (default — every backend compatible with the resolved target kind: symbol → `calls`; file → `dependencies` + `imports`; mismatched explicit choices land in `skipped_backends`, no error). `depth` default 3, `0` = unbounded (still cycle-detected and limit-capped). `limit` default 500. `summary: true` trims `matches` for cheap CI-gate consumption (`jq '.summary.nodes'`) but preserves the count. Result: `{target, direction, via, depth_limit, matches: [{depth, direction, edge, kind, name?, file_path}], summary: {nodes, max_depth_reached, by_kind, terminated_by: 'depth'|'limit'|'exhausted'}}`. Cycle detection is approximate-but-bounded — bounded depth + `LIMIT` keep cyclic graphs cheap; `terminated_by` reports the dominant stop reason. SARIF / annotations not supported (impact rows are graph traversals, not findings).
 
-**Resources (lazy-cached on first `read_resource`; constant for server-process lifetime):**
+**Resources (mostly lazy-cached on first `read_resource`; recipes / one-recipe live-read every call so the inline recency fields stay fresh):**
 
-- **`codemap://recipes`** — full catalog JSON (same as `--recipes-json`). Each entry carries `source: "bundled" | "project"` and `shadows: true` on project entries that override a bundled recipe id. Read this at session start so you know when a `--recipe foo` call will run a project override instead of the documented bundled version.
-- **`codemap://recipes/{id}`** — single recipe `{id, description, body?, sql, actions?, source, shadows?}`. Replaces `--print-sql <id>`.
+- **`codemap://recipes`** — full catalog JSON (same as `--recipes-json`). Each entry carries `source: "bundled" | "project"`, optional `shadows: true` on project entries that override a bundled recipe id, plus `last_run_at: number | null` and `run_count: number` recency fields (rank with `jq 'sort_by(.last_run_at // 0) | reverse'`). Read this at session start so you know when a `--recipe foo` call will run a project override instead of the documented bundled version.
+- **`codemap://recipes/{id}`** — single recipe `{id, description, body?, sql, actions?, source, shadows?, last_run_at, run_count}`. Replaces `--print-sql <id>`.
 - **`codemap://schema`** — DDL of every table in `.codemap/index.db` (queried live from `sqlite_schema`).
 - **`codemap://skill`** — full text of this skill file. Agents that don't preload the skill at session start can fetch it here.
 - **`codemap://files/{path}`** — per-file roll-up. Returns `{path, language, line_count, symbols, imports, exports, coverage}` where `imports.specifiers` is parsed JSON and `coverage` is `{measured_symbols, avg_coverage_pct, per_symbol}` or `null` when the file has no measured coverage. URI-encode the path. Reads live (no caching).