docs: update CLAUDE.md and agents for dev refs CLI and graph caching

- Add dev refs to CLI commands section with usage examples
- Document graph caching (dependency-graph.json) in MCP tools section
- Update dev_refs description to mention dependsOn parameter
- Update agent prompts (bug-investigator, plan-reviewer, research-planner,
  quick-scout) to reference dependsOn for dependency chain tracing

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

Author: prosdev

.claude/agents/bug-investigator.md

@@ -10,13 +10,15 @@ color: orange
 
 Systematically traces issues through the dev-agent monorepo. Reproduces, traces, fixes, and prevents regression.
 
-## MCP Tools — Use These First
+## MCP Tools — Save Tokens, Extend Sessions
 
-- **`dev_search`** — Start here for any conceptual query ("where does rate limiting happen", "how are embeddings stored"). Semantic search finds code by meaning, not just keywords.
-- **`dev_refs`** — Trace callers/callees of a function to map the data flow. Use this instead of grepping for function names when tracing how data moves across packages.
-- **`dev_map`** — Check change frequency to see what files changed recently. Useful for "when did it break?" — high-churn files near the bug timeframe are prime suspects.
+Use MCP tools to get focused results instead of Grep → Read cycles. See CLAUDE.md for the token savings table.
 
-Fall back to Grep/Glob for exact string matches or file patterns.
+- **`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.
+- **`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.
 
 ## Investigation Framework
 

.claude/agents/logic-reviewer.md

@@ -65,9 +65,10 @@ Every finding MUST include confidence: **HIGH** (verified from code), **MEDIUM**
 
 ### Cross-Package Data Flow (Deep+ Effort)
 
-Use `dev_refs` to trace caller/callee chains across package boundaries. Use `dev_search` to find related code by concept when the function name isn't obvious.
+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.
 
 - [ ] 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
 - [ ] Type boundaries between packages match (no `any` casting to bridge mismatches)
 - [ ] Logger (@prosdevlab/kero) configuration consistent across consumers
 - [ ] Error handling patterns are consistent with existing code (verify with `dev_patterns`)

.claude/agents/plan-reviewer.md

@@ -21,7 +21,7 @@ Read the plan as a senior engineer. Use `dev_map` to verify structure claims, `d
 1. **Context** — Does it accurately describe what exists today? (Verify with `dev_map` and reading actual code)
 2. **Architecture** — Does the proposed design fit the existing monorepo structure?
 3. **Parts breakdown** — Are parts sized correctly? (Each should be 1-2 commits)
-4. **Dependencies** — Are cross-package dependencies identified? (Verify with `dev_refs`)
+4. **Dependencies** — Are cross-package dependencies identified? (Verify with `dev_refs`. Use `dependsOn` to trace dependency chains between files.)
 5. **Build order** — Does the implementation order respect the build dependency chain?
 6. **Breaking changes** — Are they identified and migration paths described?
 

.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 `dev_patterns` to find similar code and detect duplication. Use `dev_search` to check if a utility already exists before flagging missing abstractions.
+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.
 
 - [ ] 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,6 +10,10 @@ color: blue
 
 Lightweight explorer optimized for speed and cost. Finds code, traces flows, maps dependencies.
 
+## Token Efficiency
+
+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.
+
 ## Capability Boundaries
 
 You excel at:
@@ -25,10 +29,10 @@ Do NOT guess at architectural reasoning or make recommendations.
 
 ## Workflow
 
-1. **Search** — Always start with `dev_search`. It finds code by meaning, not just keywords. Only fall back to Grep for exact string matches or Glob for file patterns.
-2. **Trace** — For "who calls X?" or "what does X call?", use `dev_refs`. Do not grep for function names when `dev_refs` can trace the graph directly.
-3. **Map** — For "what's the structure?" or "what changed recently?", use `dev_map`.
-4. **Verify** — Read the file to confirm the match
+1. **Search** — Start with `dev_search` for conceptual queries. Returns ranked snippets without reading files. Only fall back to Grep for exact string matches.
+2. **Trace** — For "who calls X?", use `dev_refs`. For "how does A depend on B?", use `dev_refs` with `dependsOn`. Returns the call graph directly — no grepping for function names.
+3. **Map** — For "what's the structure?", use `dev_map`. One call replaces dozens of ls/glob/read operations.
+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

.claude/agents/research-planner.md

@@ -12,12 +12,14 @@ Plans investigations before jumping into implementation. Produces a structured r
 
 This agent **NEVER writes code**. It produces investigation plans.
 
-## MCP Tools — Use These to Map the Territory
+## MCP Tools — Save Tokens, Extend Sessions
 
-- **`dev_search`** — Find relevant code areas by meaning. Start broad ("authentication middleware", "vector storage") to discover what exists before diving in.
-- **`dev_map`** — Get codebase structure with change frequency. Use early to understand scope and identify hot spots.
-- **`dev_patterns`** — Analyze existing patterns before proposing new ones. Find similar implementations, error handling conventions, and type patterns.
-- **`dev_refs`** — Trace cross-package dependencies. Understand what depends on what before proposing changes.
+Use MCP tools to map the territory without burning tokens on Grep → Read cycles. See CLAUDE.md for the token savings table.
+
+- **`dev_search`** — Find relevant code areas by meaning. Returns ranked snippets — no file reading needed.
+- **`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.
 
 ## When to Use
 

.claude/agents/security-reviewer.md

@@ -12,6 +12,10 @@ 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
+
+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.
+
 ## Checklist
 
 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.

CLAUDE.md

@@ -22,7 +22,7 @@ Everything runs on your machine. No data leaves.
 ```
 packages/
   core/          # Scanner (ts-morph, tree-sitter for Python/Go), vector storage (Antfly), services
-  cli/           # Commander.js CLI — dev index, dev mcp install, etc.
+  cli/           # Commander.js CLI — dev index, dev search, dev refs, dev map, dev mcp install
   mcp-server/    # MCP server with 5 built-in adapters
   subagents/     # Coordinator, explorer, planner, PR agents
   integrations/  # Claude Code, VS Code, Cursor
@@ -139,16 +139,33 @@ See `.claude/da-plans/README.md` for status and format details.
 
 ---
 
-## MCP tools (5 adapters)
+## MCP tools — token-efficient 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.
+
+| Instead of | Use | Tokens saved |
+|------------|-----|-------------|
+| Grep "auth" → read 10 files | `dev_search "authentication"` | ~5,000 |
+| Grep function name → read callers | `dev_refs "functionName"` | ~3,000 |
+| 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.
+
+### 5 adapters
 
 | Tool | Purpose |
 |------|---------|
 | `dev_search` | Hybrid code search — BM25 + vector + RRF (use FIRST for conceptual queries) |
-| `dev_refs` | Find callers/callees of functions |
-| `dev_map` | Codebase structure with change frequency |
+| `dev_refs` | Find callers/callees of functions. `dependsOn` traces the dependency chain between files. |
+| `dev_map` | Codebase structure with PageRank hot paths and connected subsystems |
 | `dev_patterns` | File pattern analysis (similar code, error handling, types). Takes `filePath`, not `query`. |
 | `dev_status` | Repository indexing status + Antfly stats + health checks (`section="health"`) |
 
+**Graph caching:** `dev index` builds a dependency graph (`dependency-graph.json`) saved alongside the index.
+`dev_map` and `dev_refs` load the cached graph instead of fetching all docs — scales to 50k+ docs.
+File watcher incrementally updates the graph on save.
+
 ---
 
 ## Adding a new MCP adapter
@@ -172,6 +189,13 @@ dev setup                                 # One-time: start Antfly
 dev index                                 # Index repository
 dev mcp install                           # Install for Claude Code
 dev mcp install --cursor                  # Install for Cursor
+
+# CLI tools (no MCP server needed)
+dev search "authentication"               # Semantic code search
+dev refs "functionName"                   # Find callers/callees
+dev refs "fn" --depends-on "src/db.ts"    # Trace dependency chain
+dev map                                    # Codebase structure overview
+dev map --focus packages/core --depth 3    # Focused map
 ```
 
 ---