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.

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

@@ -0,0 +1,15 @@
+---
+"@stainless-code/codemap": patch
+---
+
+Agent-friendly CLI surface: `codemap validate`, `codemap context`, `--performance`, `-r` recipe alias, and four new bundled query recipes.
+
+- **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`

.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,20 @@ 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
+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 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