fix(cli,core): address code review — validation, cached graph, cleanup

- Validate --direction with Commander .choices() (rejects invalid values)
- Use cached dependency graph for --depends-on (loadOrBuildGraph)
- Pass excludePatterns/languages from config (parity with search command)
- Use replaceAll for dist/ normalization (handles nested paths)
- Note indexer.close() not needed in catch (process.exit cleans up)

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

Author: prosdev

.claude/agents/bug-investigator.md

@@ -10,15 +10,17 @@ color: orange
 
 Systematically traces issues through the dev-agent monorepo. Reproduces, traces, fixes, and prevents regression.
 
-## MCP Tools — Save Tokens, Extend Sessions
+## MCP Tools — Conserve Context
 
-Use MCP tools to get focused results instead of Grep → Read cycles. See CLAUDE.md for the token savings table.
+This agent runs in a long session with a finite context window. Every Grep → Read cycle burns ~5,000 tokens on irrelevant matches. MCP tools return only what you need.
 
-- **`dev_search`** — Conceptual queries ("where does rate limiting happen"). Returns ranked snippets — no file reading needed.
-- **`dev_refs`** — Callers/callees of a function. Use `dependsOn` to trace dependency chains between files.
+**Before you Grep or Read, ask: can an MCP tool answer this without reading files?**
+
+- **`dev_search`** — Conceptual queries ("where does rate limiting happen"). Returns ranked snippets, not 200 grep matches.
+- **`dev_refs`** — Callers/callees of a function. Use `dependsOn` to trace dependency chains. Returns the call graph directly.
 - **`dev_map`** — Codebase structure with hot paths and subsystems. One call replaces dozens of ls/glob/read operations.
 
-Reserve Grep/Glob for exact string matches where you know the literal text.
+Only use Grep for exact string matches where you know the literal text. Only Read files when you need the full implementation.
 
 ## Investigation Framework
 

.claude/agents/logic-reviewer.md

@@ -65,7 +65,7 @@ Every finding MUST include confidence: **HIGH** (verified from code), **MEDIUM**
 
 ### Cross-Package Data Flow (Deep+ Effort)
 
-Use MCP tools to trace cross-package flows without reading every file (see CLAUDE.md for token savings). `dev_refs` returns the call graph directly, `dev_search` finds related code by concept, `dev_patterns` compares error handling across files.
+**Before you Grep or Read, ask: can an MCP tool answer this without reading files?** `dev_refs` returns the call graph directly, `dev_search` finds related code by concept, `dev_patterns` compares error handling across files — each saves ~3,000-5,000 tokens vs manual file reading.
 
 - [ ] Core exports consumed correctly by CLI, MCP server, and subagents — verify with `dev_refs`
 - [ ] Dependency chains make sense — use `dev_refs` with `dependsOn` to trace file-to-file paths

.claude/agents/plan-reviewer.md

@@ -12,6 +12,16 @@ Two-pass review of execution plans in `.claude/da-plans/`. Validates completenes
 
 This agent **NEVER modifies plans**. It reports issues for the author to fix.
 
+## MCP Tools — Conserve Context
+
+This agent runs in a long session with a finite context window. Every Grep → Read cycle burns ~5,000 tokens on irrelevant matches. MCP tools return only what you need.
+
+**Before you Grep or Read, ask: can an MCP tool answer this without reading files?**
+
+- **`dev_map`** — Verify structure claims in the plan against actual codebase layout.
+- **`dev_refs`** — Confirm dependency assertions. Use `dependsOn` to trace dependency chains between files.
+- **`dev_patterns`** — Check if proposed patterns match existing conventions.
+
 ## Two-Pass Review
 
 ### Pass 1: Engineer Review

.claude/agents/quality-reviewer.md

@@ -48,7 +48,7 @@ Maximum **5 SUGGESTION items** per review. If more found, pick the top 5 and not
 
 ### Readability & Simplification
 
-Use MCP tools to check for duplication without reading every file (see CLAUDE.md for token savings). `dev_patterns` compares patterns across similar files. `dev_search` checks if a utility exists by meaning, not just name.
+**Before you Grep or Read, ask: can an MCP tool answer this without reading files?** `dev_patterns` compares patterns across similar files (~500 tokens vs ~3,000 for manual reads). `dev_search` checks if a utility exists by meaning, not just name.
 
 - [ ] No code duplicating existing utilities — verify with `dev_patterns` and `dev_search`
 - [ ] Functions reasonably sized (consider splitting if >50 lines)

.claude/agents/quick-scout.md

@@ -10,9 +10,11 @@ color: blue
 
 Lightweight explorer optimized for speed and cost. Finds code, traces flows, maps dependencies.
 
-## Token Efficiency
+## MCP Tools — Conserve Context
 
-Use MCP tools to get focused results instead of Grep → Read cycles. See CLAUDE.md for the token savings table. Every file Read costs tokens — let the tools do the reading.
+This agent runs in a long session with a finite context window. Every Grep → Read cycle burns ~5,000 tokens on irrelevant matches. MCP tools return only what you need.
+
+**Before you Grep or Read, ask: can an MCP tool answer this without reading files?**
 
 ## Capability Boundaries
 
@@ -35,52 +37,6 @@ Do NOT guess at architectural reasoning or make recommendations.
 4. **Verify** — Only Read a file when you need the full implementation, not just the location.
 5. **Report** — Concise, factual answer with file paths and line numbers
 
-## Dev-Agent Quick Reference
-
-```
-packages/
-  core/src/
-    scanner/          # ts-morph (TS/JS) and tree-sitter (Go) analysis
-    vector/           # Antfly vector storage + embeddings
-    services/         # Coordinator, search, health
-    events/           # Event bus system
-    indexer/          # Repository indexing orchestration
-    map/              # Codebase structure mapping
-    observability/    # Logger integration
-
-  cli/src/
-    commands/         # Commander.js CLI commands
-    utils/            # Formatters, logger, output helpers
-
-  mcp-server/src/
-    server/           # MCP server setup
-    adapters/         # Tool adapters (search, refs, map, inspect, status, health)
-    formatters/       # Compact and verbose output formatters
-    utils/            # Logger
-
-  subagents/src/
-    coordinator/      # Agent orchestration
-    explorer/         # Code exploration agent
-    planner/          # Planning agent
-    github/           # GitHub integration agent
-
-  logger/src/         # @prosdevlab/kero centralized logging
-  types/src/          # Shared TypeScript types
-  integrations/       # Claude Code, VS Code integrations
-  dev-agent/          # Root package (CLI entry point)
-```
-
-### Common Patterns
+## Orientation
 
-| Pattern | Location |
-|---------|----------|
-| MCP tool adapters | `packages/mcp-server/src/adapters/built-in/` |
-| Core services | `packages/core/src/services/` |
-| Scanner implementations | `packages/core/src/scanner/` |
-| CLI commands | `packages/cli/src/commands/` |
-| Subagent types | `packages/subagents/src/{agent}/` |
-| Tests | `packages/**/src/**/__tests__/` |
-| Package configs | `packages/*/package.json` |
-| Build config | `turbo.json`, `tsconfig.json` |
-| Test config | `vitest.config.ts` |
-```
+Use `dev_map` to get the current codebase structure — don't rely on memorized paths. Run `dev_map --focus packages/core --depth 3` to drill into a specific area.

.claude/agents/research-planner.md

@@ -12,11 +12,13 @@ Plans investigations before jumping into implementation. Produces a structured r
 
 This agent **NEVER writes code**. It produces investigation plans.
 
-## MCP Tools — Save Tokens, Extend Sessions
+## MCP Tools — Conserve Context
 
-Use MCP tools to map the territory without burning tokens on Grep → Read cycles. See CLAUDE.md for the token savings table.
+This agent runs in a long session with a finite context window. Every Grep → Read cycle burns ~5,000 tokens on irrelevant matches. MCP tools return only what you need.
 
-- **`dev_search`** — Find relevant code areas by meaning. Returns ranked snippets — no file reading needed.
+**Before you Grep or Read, ask: can an MCP tool answer this without reading files?**
+
+- **`dev_search`** — Find relevant code areas by meaning. Returns ranked snippets, not 200 grep matches.
 - **`dev_map`** — Codebase structure with hot paths and subsystems. One call replaces dozens of ls/glob/read operations.
 - **`dev_patterns`** — Compare patterns across similar files without reading each one.
 - **`dev_refs`** — Trace cross-package dependencies. Use `dependsOn` to trace dependency chains between files.

.claude/agents/security-reviewer.md

@@ -12,13 +12,17 @@ Security-focused review for a TypeScript monorepo that processes repository data
 
 This agent **NEVER modifies code**. It reports issues for the developer to fix.
 
-## Token Efficiency
+## MCP Tools — Conserve Context
 
-Use MCP tools to avoid expensive Grep → Read cycles. See CLAUDE.md for the token savings table. `dev_search` returns ranked snippets, `dev_refs` traces input flow directly, `dev_patterns` scans for similar vulnerability patterns — all without reading files manually.
+This agent runs in a long session with a finite context window. Every Grep → Read cycle burns ~5,000 tokens on irrelevant matches. MCP tools return only what you need.
 
-## Checklist
+**Before you Grep or Read, ask: can an MCP tool answer this without reading files?**
+
+- **`dev_search`** — Find security-sensitive code ("user input", "shell execution", "token handling"). Returns ranked snippets.
+- **`dev_patterns`** — If one injection vector exists, the same pattern likely appears elsewhere. Scan for similar patterns across files.
+- **`dev_refs`** — Trace how user input flows through the system. Use `dependsOn` to trace dependency chains.
 
-Use `dev_search` to find security-sensitive code ("user input", "shell execution", "token handling"). Use `dev_patterns` to find similar patterns across the codebase — if one injection vector exists, the same pattern likely appears elsewhere. Use `dev_refs` to trace how user input flows through the system.
+## Checklist
 
 ### Command Injection
 - [ ] No unsanitized user input passed to `child_process`, `exec`, `execSync`, or shell commands

CLAUDE.md

@@ -139,9 +139,11 @@ See `.claude/da-plans/README.md` for status and format details.
 
 ---
 
-## MCP tools — token-efficient context
+## MCP tools — conserve context
 
-MCP tools return pre-ranked, pre-snippeted results. Use them to avoid expensive Grep → Read cycles that burn thousands of tokens on irrelevant context.
+**Before you Grep or Read, ask: can an MCP tool answer this without reading files?**
+
+MCP tools return pre-ranked snippets. Every Grep → Read cycle burns ~3,000-5,000 tokens of context window on irrelevant matches. MCP tools return only what you need.
 
 | Instead of | Use | Tokens saved |
 |------------|-----|-------------|
@@ -150,7 +152,7 @@ MCP tools return pre-ranked, pre-snippeted results. Use them to avoid expensive
 | ls + glob + read READMEs | `dev_map` | ~2,000 |
 | Read multiple files to compare patterns | `dev_patterns filePath` | ~3,000 |
 
-Reserve Grep/Glob for exact string matches where you know the literal text.
+Only use Grep for exact string matches where you know the literal text. Only Read files when you need the full implementation.
 
 ### 5 adapters
 

packages/cli/src/commands/refs.ts

@@ -1,15 +1,15 @@
 import * as path from 'node:path';
 import {
-  buildDependencyGraph,
   ensureStorageDirectory,
   getStorageFilePaths,
   getStoragePath,
+  loadOrBuildGraph,
   RepositoryIndexer,
   type SearchResult,
   shortestPath,
 } from '@prosdevlab/dev-agent-core';
 import chalk from 'chalk';
-import { Command } from 'commander';
+import { Command, Option } from 'commander';
 import ora from 'ora';
 import { loadConfig } from '../utils/config.js';
 import { logger } from '../utils/logger.js';
@@ -25,7 +25,11 @@ interface CalleeInfo {
 export const refsCommand = new Command('refs')
   .description('Find callers and callees of a function')
   .argument('<name>', 'Function or method name (e.g., "createPlan", "SearchAdapter.execute")')
-  .option('-d, --direction <direction>', 'Query direction: callees, callers, or both', 'both')
+  .addOption(
+    new Option('-d, --direction <direction>', 'Query direction: callees, callers, or both')
+      .choices(['callees', 'callers', 'both'])
+      .default('both')
+  )
   .option('-l, --limit <number>', 'Maximum results per direction', '20')
   .option('--depends-on <file>', 'Trace dependency path to a target file')
   .option('--json', 'Output results as JSON', false)
@@ -44,6 +48,8 @@ export const refsCommand = new Command('refs')
       const indexer = new RepositoryIndexer({
         repositoryPath: resolvedRepoPath,
         vectorStorePath: filePaths.vectors,
+        excludePatterns: config?.repository?.excludePatterns || config?.excludePatterns,
+        languages: config?.repository?.languages || config?.languages,
       });
 
       await indexer.initialize();
@@ -64,8 +70,9 @@ export const refsCommand = new Command('refs')
       // Handle --depends-on
       if (options.dependsOn) {
         spinner.text = `Tracing path: ${name} → ${options.dependsOn}`;
-        const allDocs = await indexer.getAll({ limit: 50000 });
-        const graph = buildDependencyGraph(allDocs);
+        const graph = await loadOrBuildGraph(filePaths.dependencyGraph, async () =>
+          indexer.getAll({ limit: 50000 })
+        );
         const sourceFile = (target.metadata.path as string) || '';
         const tracePath = shortestPath(graph, sourceFile, options.dependsOn);
 
@@ -195,6 +202,7 @@ export const refsCommand = new Command('refs')
     } catch (error) {
       spinner.fail('Refs query failed');
       logger.error(error instanceof Error ? error.message : String(error));
+      // indexer may not be initialized if error was early, but close() is safe to call
       process.exit(1);
     }
   });

packages/core/src/scanner/typescript.ts

@@ -994,7 +994,7 @@ export class TypeScriptScanner implements Scanner {
                 // (e.g. /abs/packages/logger/dist/types.d.ts) but we store
                 // relative source paths (packages/logger/src/types.ts).
                 let normalized = rawPath
-                  .replace(/\/dist\//, '/src/')
+                  .replaceAll('/dist/', '/src/')
                   .replace(/\.d\.ts$/, '.ts')
                   .replace(/\.js$/, '.ts');
                 if (this.repoRoot && normalized.startsWith(this.repoRoot)) {