docs: sync playbook, CLI help, CLAUDE.md, README with this session's changes

- playbook (`server-instructions.ts`): `codegraph_biomarkers` "pending"
  state after `index --force`; `dead_code verdict:'all'` returns every
  judged candidate; `tests_for` files-mode + showing-first-N cap;
  `affected` rejects unindexed explicit paths; `session` CLI-mirror line.
- CLI help (`codegraph.ts`): `coverage --mode` description now lists
  `refresh` (the rest of the new CLI surface — `session`, the new
  `at-range`/`tests-for`/`affected`/`dead-code` flags — already carried
  accurate help text).
- CLAUDE.md: CLI Usage section gains the new flags + a `codegraph_session`
  family block; MCP-tools table notes the biomarkers-pending state and
  the `affected` unindexed-path rejection.
- README.md: `affected` options table gains the `--files` alias row.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: andreinknv

CLAUDE.md

@@ -147,12 +147,22 @@ codegraph admin unlock [path]     # remove a stale lock file
 codegraph status [path]                       # Show index status
 codegraph find <query> [--by name|content|env|sql]  # find a symbol / regex / env-var / SQL-table ref
 codegraph context <task>                      # Build context for AI
-codegraph at-range <file> <startLine> <endLine>  # Symbols overlapping a line range (R*Tree)
+codegraph at-range <file> <startLine> <endLine>  # Symbols overlapping a line range (R*Tree; --compact / --fields)
+codegraph tests-for [symbol]                  # Tests exercising a symbol; --files <paths...> for files-mode
+codegraph affected [files...]                 # Test files affected by changes (--files alias; validates indexed paths)
+codegraph dead-code                           # Likely-dead functions (--limit alias of --max-candidates)
 codegraph deps                                # Audit unused package.json deps
 
 # Coverage — codegraph_coverage family
 codegraph coverage [symbol]                          # mode=ranked default
-codegraph coverage --mode load --report-path <path>  # ingest lcov
+codegraph coverage --mode refresh                    # auto-discover + re-ingest the latest lcov report
+codegraph coverage --mode load --report-path <path>  # ingest lcov from an explicit path
+
+# Agent session state + macros — codegraph_session family
+codegraph session create [--label <l>]       # create a labelled session
+codegraph session resume <id>                # render a prior session's tool calls
+codegraph session list                       # list recent sessions
+codegraph session macro_save / macro_run / macro_list / macro_delete  # tool-macro recipes
 
 # Agent-bridge summaries — codegraph_summaries family
 codegraph summaries pending                  # pull a batch
@@ -183,11 +193,11 @@ Use these tools **directly in the main session** for fast code exploration (repl
 | `codegraph_node` | Get details + source code for a symbol. Pass `symbols: [a, b, c]` for up to 20 at once. Set `includeCallers` / `includeCallees` / `includeBiomarkers` / `includeTests` to fold those answers in. A `kind:'file'` node also renders that file's LLM prose summary when cached. |
 | `codegraph_at_range` | Find symbols whose line range overlaps a file:start-end span. R*Tree-backed, O(log n), smallest-enclosing first. Use for line-range PR review or diff-hunk overlay. Pass `ranges: [{file, startLine, endLine}, …]` to query up to 100 hunks in one call. |
 | `codegraph_find by:content` | Regex content search across indexed files with enclosing-symbol attribution. Empty results surface two hints: (a) when `pathFilter` starts with the project-root basename (e.g. `codegraph/src/...`) and dropping it would have matched, a "drop the prefix?" nudge; (b) when the query contains numeric character classes, a "regex may span a template-literal interpolation; try matching one side" tip. Replaces the pre-merge `codegraph_grep`. |
-| `codegraph_biomarkers` | Static-analysis findings + Code Health score per symbol or project-wide. 17 biomarker types (large/complex/nested method, complex_conditional, brain_method composite, long_parameter_list, magic_number, hardcoded_url, recently_grew, stale_doc, unused_export, god_class, feature_envy [ATFD/LAA], illegal_import [opt-in architectural layering rules], secrets_handling, low_coverage, duplicate_code [code clones — Type-1 exact + Type-2 near + Type-3 partial + Type-4 semantic; the Type-3 partial tier runs a high-overlap (≥0.95) band by default, with a wider FP-prone band opt-in via `duplicateCodePartialClones`]). Auto-refreshed on indexAll/sync. |
+| `codegraph_biomarkers` | Static-analysis findings + Code Health score per symbol or project-wide. 17 biomarker types (large/complex/nested method, complex_conditional, brain_method composite, long_parameter_list, magic_number, hardcoded_url, recently_grew, stale_doc, unused_export, god_class, feature_envy [ATFD/LAA], illegal_import [opt-in architectural layering rules], secrets_handling, low_coverage, duplicate_code [code clones — Type-1 exact + Type-2 near + Type-3 partial + Type-4 semantic; the Type-3 partial tier runs a high-overlap (≥0.95) band by default, with a wider FP-prone band opt-in via `duplicateCodePartialClones`]). Auto-refreshed on indexAll/sync. In the window right after a full `index --force` (cache cleared, post-hook pass pending) it returns an explicit "biomarkers pending" state instead of a false "0 findings / clean". |
 | `codegraph_history` | Symbol-level co-change — "last N times this changed, what else changed?" |
 | `codegraph_review mode='risk'` | Composed triage: top biomarkers + hotspots + coverage gaps + dead-code. Merged into `codegraph_review` 2026-05-14; the standalone `codegraph_risk_review` tool was retired. |
 | `codegraph_digest` | Composite "land in a new repo" overview: hotspots + biomarkers + entry points + recent churn |
-| `codegraph_affected` | Given changed source files, return the test files that transitively depend on them. Reactive post-edit workflow: "which tests should I re-run?". `files` is optional — when omitted, the changed set is derived from `git diff HEAD` (a clean tree returns a friendly "no uncommitted changes" message). |
+| `codegraph_affected` | Given changed source files, return the test files that transitively depend on them. Reactive post-edit workflow: "which tests should I re-run?". `files` is optional — when omitted, the changed set is derived from `git diff HEAD` (a clean tree returns a friendly "no uncommitted changes" message). Explicitly-passed paths absent from the index are rejected with an error + non-zero exit. CLI mirror `codegraph affected` accepts both positional files and a `--files` alias. |
 | `codegraph_sql` | Read-only ad-hoc SQL escape hatch over the codegraph SQLite backend. Use when curated tools don't fit a novel query. Pass `schema: true` first to learn the table layout; combine with `tables: ['nodes', 'edges']` (case-insensitive name filter) and `compact: true` (one-line column lists) to dump just the layout you need without the full 60+ CREATE TABLE blocks. |
 | `codegraph_discover` | Find every `.codegraph/` directory under a parent path. Useful for monorepos. |
 | `codegraph_local_chat` | Delegate bulk-prose subtasks (file summaries, draft prose, paraphrase verification) to the user's configured local LLM — saves Anthropic-token cost. NOT for hard reasoning or user-visible verbatim output. |

README.md

@@ -314,12 +314,15 @@ codegraph affected src/auth.ts --filter "e2e/*"     # Custom test file pattern
 
 | Option | Description | Default |
 |--------|-------------|---------|
+| `--files <paths...>` | Alias for the positional file arguments | — |
 | `--stdin` | Read file list from stdin | `false` |
 | `-d, --depth <n>` | Max dependency traversal depth | `5` |
 | `-f, --filter <glob>` | Custom glob to identify test files | auto-detect |
 | `-j, --json` | Output as JSON | `false` |
 | `-q, --quiet` | Output file paths only | `false` |
 
+Paths passed explicitly that aren't in the index are rejected with an error and a non-zero exit code.
+
 **CI/hook example:**
 
 ```bash

src/bin/codegraph.ts

@@ -3427,7 +3427,7 @@ program
 
 program
   .command('coverage [symbol]')
-  .description("Coverage queries + ingestion (mirrors codegraph_coverage MCP tool). Data-source axis: --mode symbol/ranked/stats/load. Classifier axis: --via rule/llm/auto.")
+  .description("Coverage queries + ingestion (mirrors codegraph_coverage MCP tool). Data-source axis: --mode symbol/ranked/stats/load/refresh. Classifier axis: --via rule/llm/auto.")
   .option('-p, --project-path <path>', 'Project path')
   .option('--mode <m>', "Data-source axis: symbol | ranked | stats | load | refresh. `refresh` re-runs the coverage ingestion from the most recently loaded report (recommended onboarding mode).", 'ranked')
   .option('--via <axis>', "Classifier axis: rule (lcov ranking) | llm (not yet implemented) | auto (default).")

src/mcp/server-instructions.ts

@@ -45,11 +45,11 @@ about a second through the file watcher.
   - **Migration note:** \`since\` UIDs minted by the pre-merge \`codegraph_callers\` / \`codegraph_callees\` won't resolve under \`codegraph_graph\` — first call after upgrade falls back to a full result with the standard "call id is no longer cached" warning.
 - **"Show me this symbol's source / signature / docstring."** → \`codegraph_node\` (pass \`symbols: [a, b, c]\` for up to 20 in one call; pass \`code: true\` to include the actual source body; flip \`includeCallers\` / \`includeCallees\` / \`includeBiomarkers\` / \`includeTests\` to fold those tools' answers into the same response — collapses 3-5 round-trips into one for "tell me everything about X". A \`kind:'file'\` node also renders that file's LLM prose summary when one is cached.)
 - **"Which symbols overlap this line range / diff hunk?"** → \`codegraph_at_range({file, startLine, endLine})\` for one hunk; \`codegraph_at_range({ranges: [...]})\` for up to 100 pre-parsed hunks; or \`codegraph_at_range({diff: '<unified diff>'})\` to feed raw \`git diff\` output and let the server parse hunks itself. R*Tree-backed, O(log n), smallest-enclosing first. Pass \`compact: true\` to emit pipe-delimited rows (\`name|kind|path:line|end:N|sig:...\`) instead of the markdown table; add \`fields: ['name', 'kind']\` to restrict columns — saves 50-70% of output tokens on multi-hunk diff overlays. In \`diff:\` mode, a hunk that overlaps no symbol exactly (a tight signature-edit hunk whose context window doesn't reach the definition line) gets one conservative ±8-line retry; rows resolved that way are labelled \`(near hunk — exact overlap was empty)\`.
-- **"Is this function risky to change? Is it complex / nested / large?"** → \`codegraph_biomarkers\` — structured answer instead of reading 200 lines of source. Slice with \`minMetric\` / \`maxMetric\` for "show me only findings at threshold floor" or "only findings above the warning band". Batched form: \`mode: 'symbol', symbols: [...]\` for up to 20 symbols in one call.
+- **"Is this function risky to change? Is it complex / nested / large?"** → \`codegraph_biomarkers\` — structured answer instead of reading 200 lines of source. Slice with \`minMetric\` / \`maxMetric\` for "show me only findings at threshold floor" or "only findings above the warning band". Batched form: \`mode: 'symbol', symbols: [...]\` for up to 20 symbols in one call. In the window right after a full \`index --force\` (biomarker cache cleared, post-hook pass not yet run) the tool returns an explicit "biomarkers pending" state rather than a misleading "0 findings / clean" — retry once the post-sync pass completes.
 - **"Is this function tested? What's covered?"** → \`codegraph_coverage\`. **Onboarding shortcut: \`mode: 'refresh'\`** auto-discovers an lcov report under conventional paths (\`coverage/lcov.info\`, etc.) — no \`reportPath\` needed. For an explicit path use \`mode: 'load', reportPath: 'coverage/lcov.info'\` (project-relative). When \`node_coverage\` is loaded, the \`low_coverage\` biomarker auto-fires on high-centrality undertested symbols — surfaces under \`codegraph_biomarkers\`, \`codegraph_digest\`, and \`codegraph_review({mode: 'risk'})\`.
-- **"What code might be dead / unreachable?"** → \`codegraph_dead_code\` — default \`via: 'auto'\` is graph + LLM judge; \`via: 'rule'\` is graph orphan-finder (no LLM); \`via: 'llm'\` is explicit LLM-judge. Legacy \`mode: 'static' | 'judge'\` still accepted as alias.
-- **"Which tests cover this symbol?"** → \`codegraph_tests_for\` (graph-derived test discovery)
-- **"I just edited these files — which tests should I re-run?"** → \`codegraph_affected({files?})\` (reactive post-edit workflow — omit \`files\` to derive the changed set from \`git diff HEAD\`; a clean tree returns a friendly "no uncommitted changes" message). The rendered row list is capped (with a "showing first N of M" footer); when the dependency traversal passes through a public-API barrel (\`index.ts\` / \`index.mjs\` / …) the blast radius is most of the suite, so the result appends a hint to narrow with \`codegraph_tests_for\` for symbol-level test discovery.
+- **"What code might be dead / unreachable?"** → \`codegraph_dead_code\` — default \`via: 'auto'\` is graph + LLM judge; \`via: 'rule'\` is graph orphan-finder (no LLM); \`via: 'llm'\` is explicit LLM-judge. Legacy \`mode: 'static' | 'judge'\` still accepted as alias. \`verdict: 'all'\` (via=llm) returns every judged candidate regardless of verdict — the catch-all for "show me the full judge output".
+- **"Which tests cover this symbol?"** → \`codegraph_tests_for\` (graph-derived test discovery — pass \`files: [...]\` for files-mode test discovery against a changed file set; files-mode output is capped with a "showing first N" footer)
+- **"I just edited these files — which tests should I re-run?"** → \`codegraph_affected({files?})\` (reactive post-edit workflow — omit \`files\` to derive the changed set from \`git diff HEAD\`; a clean tree returns a friendly "no uncommitted changes" message). Explicitly-passed paths that aren't in the index are rejected with an error + non-zero exit. The rendered row list is capped (with a "showing first N of M" footer); when the dependency traversal passes through a public-API barrel (\`index.ts\` / \`index.mjs\` / …) the blast radius is most of the suite, so the result appends a hint to narrow with \`codegraph_tests_for\` for symbol-level test discovery.
 - **"What's in directory X?"** → \`codegraph_files\` (modes: tree / flat / grouped / summary; \`flat\` folds in the per-file LLM summary on listings ≤80 files)
 - **"Survey an unfamiliar topic / pattern / module."** → \`codegraph_explore\` (heavier; best when budget allows)
 - **"Where do I start?" (new repo)** → \`codegraph_digest\` (composite onboarding overview) or \`codegraph_entry_points\` (five buckets: routes / cli / mcp_tools / cli_files / public_exports — \`mcp_tools\` is sorted alphabetically by canonical \`codegraph_X\` name; \`public_exports\` lists exports with no incoming \`calls\`/\`references\`/type-usage edges; pass \`bucket: 'public_exports', limit: 200\` to page into one section's long tail).
@@ -157,7 +157,7 @@ For low-stakes bulk-prose subtasks (file/function summarization, draft prose, pa
 
 ## Cross-call agent state (multi-step investigations)
 
-\`codegraph_session({action})\` lets you create / resume sessions and save / replay tool macros across calls in the same MCP server. \`codegraph_note({action})\` leaves persistent annotations on symbols (kind: note / question / followup / bookmark). Most useful for long investigations or agent-to-future-agent handoffs.
+\`codegraph_session({action})\` lets you create / resume sessions and save / replay tool macros across calls in the same MCP server. \`codegraph_note({action})\` leaves persistent annotations on symbols (kind: note / question / followup / bookmark). Most useful for long investigations or agent-to-future-agent handoffs. CLI mirror: \`codegraph session <create|resume|list|macro_save|macro_run|macro_list|macro_delete>\`.
 
 ## Token-cost flags (Stage 6 — graph-walk efficiency)