feat(cli): codemap validate / context / --performance, four new query recipes, friendlier no-DB error

.agents/lessons.md

@@ -7,3 +7,5 @@ Persistent log of corrections and insights from past sessions. Agents **must** c
 Each entry is a single bullet: `- **<topic>** — <lesson>`. Newest entries at the bottom.
 
 ## Lessons
+
+- **changesets bump policy (pre-v1)** — while in `0.x`, default to **patch** for everything (additive features, fixes, docs, internal refactors); reserve **minor** for schema-breaking changes that force a `.codemap.db` rebuild (matches 0.2.0 precedent: new tables/columns/`SCHEMA_VERSION` bump). Strict SemVer kicks in only after `1.0.0`. Don't propose `minor` just because new CLI commands or public types were added.

.agents/rules/docs-governance.md

@@ -0,0 +1,60 @@
+---
+description: Always follow the docs governance in docs/README.md when touching files under docs/. Specifically: cite Rules by number, update File Ownership and Single Source of Truth tables when adding/removing docs, fold new content into existing files unless it passes the Existence Test.
+alwaysApply: true
+---
+
+# Docs Governance
+
+`docs/README.md` is the source of truth for how the docs folder is organized and edited. Read it first whenever you touch anything under `docs/`.
+
+## Quick checklist
+
+When you change a doc, these checks must pass before the PR ships:
+
+- **Rule 1 — One source of truth.** No prose duplicated across files. Cross-reference by relative path instead.
+- **Rule 2 — Shipped items leave the roadmap.** When a backlog item lands, move its description to its canonical home (architecture / why-codemap / README) and remove it from `roadmap.md`.
+- **Rule 3 — Plans get their own file.** Don't embed plans in `roadmap.md`. Create `docs/plans/<feature-name>.md` and link from the roadmap entry.
+- **Rule 4 — Tables stay current.** When you add or delete a doc, update the **File Ownership** and **Single Source of Truth** tables in `docs/README.md` in the same PR.
+- **Rule 5 — Relative cross-references.** `[architecture.md § Section](./architecture.md#section)` — never absolute paths or repo URLs for in-tree docs.
+- **Rule 6 — No inventory counts in narrative.** Don't hardcode counts of files / symbols / recipes. Use qualitative descriptors or a `codemap query` example. Decision values (cache TTLs, `SCHEMA_VERSION`) are fine.
+- **Rule 7 — No line-number references.** Cite by function name, section heading, or `codemap query` lookup. Methodology tables in `benchmark.md` are exempt.
+- **Rule 8 — Close research notes.** When a `research/` scan's adopt items ship, slim it to a "What shipped" appendix linking to canonical homes. Rejected items keep a `Status: Rejected (date) — <reason>` header.
+- **Rule 9 — New term ⇒ glossary.** Every PR that introduces a new domain noun (table name, recipe id, parser name, schema column) updates `docs/glossary.md` in the same PR. Disambiguations (e.g. `FileRow` TS shape vs `files` SQLite table) take priority.
+
+## Document Lifecycle (full text in `docs/README.md`)
+
+Four doc types: **Reference** (lives forever), **Roadmap** (single file, items move in/out), **Plan** (created on commit, deleted on ship), **Research** (created for evaluations, closed per § Closing research).
+
+Backlogs / frameworks / decisions don't get their own file — they fold into one of the four.
+
+### Existence test (apply on every doc-touching PR)
+
+A file earns its place if it meets at least one of:
+
+1. Source code or another doc cites it (grep finds the path).
+2. It documents durable policy or framework unavailable elsewhere.
+3. It tracks open work.
+4. It carries unique historical context that `git log` + `architecture.md` cannot reconstruct.
+
+If none → fold any salvageable content into roadmap / architecture / glossary, fix cross-refs, **delete the file**.
+
+### Top-level cap
+
+Adding a new top-level doc requires:
+
+1. The topic doesn't fit any existing root-level doc.
+2. The new file passes the existence test on day one.
+3. **File Ownership** table in `docs/README.md` updated in the same PR.
+
+When in doubt, default to absorbing into the closest existing root-level file.
+
+## Why this exists
+
+- Avoids the slow rot that hits any docs folder where any contributor (human or agent) can drop a new top-level file at any time.
+- Gives reviewers cite-able rule numbers ("violates Rule 4") instead of vague "this should go elsewhere" feedback.
+- Keeps `git log` legible by making doc files have predictable lifecycles.
+
+## Reference
+
+- [`docs/README.md`](../../docs/README.md) — full text of all rules, the lifecycle, and the existence test.
+- Adapted from PaySpace `analytics/docs/README.md` governance pattern.

.changeset/agent-friendly-cli-recipes.md

@@ -0,0 +1,16 @@
+---
+"@stainless-code/codemap": minor
+---
+
+Agent-friendly CLI surface plus a schema v3 bump that tightens `NOT NULL` invariants. Existing `.codemap.db` files auto-rebuild on first open.
+
+- **New: `codemap validate [--json] [paths...]`** — diffs the on-disk SHA-256 of indexed files against `files.content_hash` and prints stale / missing / unindexed rows. Lets agents skip re-reads they don't need; exits `1` on any drift (git-status semantics)
+- **New: `codemap context [--compact] [--for "<intent>"]`** — emits a stable JSON envelope (project metadata, top hubs, recent markers, recipe catalog) for any agent or editor that wants the index in one cheap shot. `--for` runs lightweight intent classification (refactor / debug / test / feature / explore / other) and returns matched recipe ids plus a hint
+- **New: `codemap --performance`** flag — prints a per-phase timing breakdown (collect / parse / insert / index_create) and the top-10 slowest files by parse time during full rebuilds, for triaging giant or pathological inputs
+- **New: `-r` short alias for `codemap query --recipe`** + cleaner organized `codemap query --help` (sectioned flags, dynamic recipe-id padding, examples for both forms)
+- **New recipes**: `deprecated-symbols` (`@deprecated` JSDoc tag scan), `visibility-tags` (`@internal` / `@private` / `@alpha` / `@beta`), `files-hashes` (powers `validate`), `barrel-files` (top files by export count)
+- **Friendlier no-`.codemap.db` error**: `no such table: <X>` now rewrites to an actionable hint pointing at `codemap` / `codemap --full`, on both the JSON and human paths
+- **Public type surface**: new `IndexPerformanceReport`; `IndexRunStats.performance?` field; per-field JSDoc coverage on `IndexResult`, `IndexRunStats`, `ResolvedCodemapConfig`, all `db.ts` row interfaces (`FileRow`, `SymbolRow`, `ImportRow`, `ExportRow`, `ComponentRow`, `DependencyRow`, `MarkerRow`, `CssVariableRow`, `CssClassRow`, `CssKeyframeRow`, `CallRow`, `TypeMemberRow`), and `ParsedFile`
+- **Documentation**: README now leads with a "What you get" Grep/Read vs Codemap capability table and a "Daily commands" stripe; `docs/why-codemap.md` adds a "What Codemap is **not**" anti-pitch section and a scenario-keyed token-savings table (single lookup → 50-turn session) replacing the earlier hand-wave
+- **Stricter lint baseline**: enabled `prefer-const`, `consistent-type-specifier-style`, `consistent-type-definitions`, `no-confusing-non-null-assertion`, `no-unnecessary-{boolean-literal-compare,template-expression,type-assertion}`, `prefer-{includes,nullish-coalescing,optional-chain}`, and `unicorn/switch-case-braces`
+- **Schema v3 — tighter `NOT NULL` invariants**: every column whose `Row`-interface type was non-nullable is now `NOT NULL` in the SQLite DDL (`files.size`/`line_count`/`language`/`last_modified`/`indexed_at`, `symbols.line_start`/`line_end`/`signature`/`is_exported`/`is_default_export`, `imports.specifiers`/`is_type_only`/`line_number`, `exports.kind`/`is_default`, `components.hooks_used`/`is_default_export`, `markers.line_number`/`content`, `css_variables.scope`/`line_number`, `css_classes.is_module`/`line_number`, `css_keyframes.line_number`, `type_members.is_optional`/`is_readonly`). Existing v2 databases auto-rebuild via `createSchema()`'s version-mismatch detector — no manual action needed

.cursor/rules/docs-governance.mdc

@@ -0,0 +1 @@
+../../.agents/rules/docs-governance.md

.oxlintrc.json

@@ -1,5 +1,25 @@
 {
   "$schema": "./node_modules/oxlint/configuration_schema.json",
-  "ignorePatterns": [".output", "node_modules", "dist", "coverage", "bun.lock"],
-  "plugins": ["eslint", "typescript", "unicorn", "oxc"]
+  "ignorePatterns": [
+    ".output",
+    "bun.lock",
+    "coverage",
+    "dist",
+    "fixtures",
+    "node_modules"
+  ],
+  "plugins": ["eslint", "typescript", "unicorn", "oxc", "import"],
+  "rules": {
+    "eslint/prefer-const": "error",
+    "import/consistent-type-specifier-style": ["error", "prefer-top-level"],
+    "typescript/consistent-type-definitions": ["error", "interface"],
+    "typescript/no-confusing-non-null-assertion": "error",
+    "typescript/no-unnecessary-boolean-literal-compare": "error",
+    "typescript/no-unnecessary-template-expression": "error",
+    "typescript/no-unnecessary-type-assertion": "error",
+    "typescript/prefer-includes": "error",
+    "typescript/prefer-nullish-coalescing": "error",
+    "typescript/prefer-optional-chain": "error",
+    "unicorn/switch-case-braces": "error"
+  }
 }

README.md

@@ -9,6 +9,23 @@
 
 ---
 
+## What you get
+
+Structural questions answered in **one SQL round-trip** instead of 3–5 file reads:
+
+| Question                                           | Grep / Read (today)                                          | Codemap                                                                                |
+| -------------------------------------------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------------- |
+| Find a symbol by exact name                        | Glob + Read + filter by hand                                 | `SELECT name, file_path, line_start FROM symbols WHERE name = 'X'`                     |
+| Who imports `~/utils/date`?                        | Grep + resolve `tsconfig` aliases manually                   | `SELECT DISTINCT from_path FROM dependencies WHERE to_path LIKE '%utils/date%'`        |
+| Components using the `useQuery` hook               | Grep `useQuery` + filter to component files                  | `SELECT name, file_path FROM components WHERE hooks_used LIKE '%useQuery%'`            |
+| Heaviest files by import fan-out                   | Impractical without a parser                                 | `SELECT from_path, COUNT(*) AS n FROM dependencies GROUP BY from_path ORDER BY n DESC` |
+| All CSS keyframes / design tokens / module classes | Grep `@keyframes`, `--var-`, `.module.css` then disambiguate | One `SELECT` against `css_keyframes` / `css_variables` / `css_classes`                 |
+| Deprecated symbols (`@deprecated` JSDoc)           | Grep `@deprecated` + cross-reference symbol                  | `SELECT name, kind FROM symbols WHERE doc_comment LIKE '%@deprecated%'`                |
+
+Full schema and recipe catalog: [docs/architecture.md § Schema](docs/architecture.md#schema) · [docs/why-codemap.md](docs/why-codemap.md) · `codemap query --recipes-json`.
+
+---
+
 ## Install
 
 ```bash
@@ -25,6 +42,22 @@ bun add @stainless-code/codemap
 - **Installed package:** `codemap`, `bunx @stainless-code/codemap`, or `node node_modules/@stainless-code/codemap/dist/index.mjs`
 - **This repo (dev):** `bun src/index.ts` (same flags)
 
+### Daily commands
+
+```bash
+codemap                                                      # incremental index (run once per session)
+codemap query --json --recipe fan-out                        # bundled SQL via recipe id (alias: -r)
+codemap query --json "SELECT name, file_path FROM symbols WHERE name = 'foo'"  # ad-hoc SQL
+codemap --files src/a.ts src/b.tsx                           # targeted re-index after edits
+codemap validate --json                                      # detect stale / missing / unindexed files
+codemap context --compact --for "refactor auth"              # JSON envelope + intent-matched recipes
+codemap agents init                                          # scaffold .agents/ rules + skills
+```
+
+**Version-matched agent guidance:** the published npm package ships **`templates/agents/`** (rules + skills) keyed to that version, so `codemap agents init` writes guidance that matches the CLI you installed. See [docs/agents.md](docs/agents.md).
+
+### Full reference
+
 ```bash
 # Index project root (optional codemap.config.ts / codemap.config.json)
 codemap