milens 0.4.0 → 0.4.2

package/dist/server/mcp.js

@@ -1,15 +1,19 @@
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { z } from 'zod';
 import { createServer } from 'node:http';
 import { randomUUID } from 'node:crypto';
-import { resolve, relative, join } from 'node:path';
+import { resolve, relative, join, dirname } from 'node:path';
 import { execFileSync } from 'node:child_process';
-import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { readFileSync, readdirSync, statSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
 import ignore from 'ignore';
 import { Database } from '../store/db.js';
 import { RepoRegistry } from '../store/registry.js';
+import { fileURLToPath } from 'node:url';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PKG_VERSION = JSON.parse(readFileSync(join(__dirname, '..', '..', 'package.json'), 'utf-8')).version;
 // ── Lazy DB connection with idle eviction ──
 class LazyDb {
     dbPath;
@@ -42,15 +46,72 @@ class LazyDb {
         this.instance = null;
     }
 }
-// ── Compact formatters (token-efficient for AI agents) ──
-function fmtSymbol(s) {
-    return `${s.name} [${s.kind}] ${s.filePath}:${s.startLine}`;
+// ── Tool usage tracking ──
+// Estimated tokens an agent would spend WITHOUT milens (manual exploration cost per tool)
+const TOKEN_SAVINGS_MULTIPLIER = {
+    query: 3, // vs 3+ separate grep/file reads
+    grep: 2, // vs terminal grep + manual filtering
+    context: 5, // vs incoming + outgoing + file reads
+    impact: 6, // vs recursive manual upstream/downstream exploration
+    edit_check: 8, // vs context + impact + grep + coverage check
+    smart_context: 6, // vs multiple tool calls based on intent
+    overview: 8, // vs context + impact + grep combined
+    trace: 5, // vs manually tracing call chains
+    routes: 3, // vs searching for route patterns
+    domains: 3, // vs exploring file structure
+    status: 2, // vs checking multiple stats
+    detect_changes: 4, // vs git diff + manual symbol mapping
+    explain_relationship: 4, // vs manual path finding
+    find_dead_code: 3, // vs manual export usage search
+    get_file_symbols: 2, // vs reading entire file
+    get_type_hierarchy: 4, // vs manual inheritance traversal
+    repos: 1, // simple listing
+};
+function estimateTokens(text) {
+    // Rough token estimate: ~4 chars per token for English/code
+    return Math.ceil(text.length / 4);
 }
-function fmtImpact(items) {
+function getTrackingDb() {
+    try {
+        const dir = join(homedir(), '.milens');
+        mkdirSync(dir, { recursive: true });
+        return new Database(join(dir, 'tracking.db'));
+    }
+    catch {
+        return null; // tracking is best-effort, never block
+    }
+}
+function trackToolCall(trackDb, tool, startMs, responseText, repo) {
+    if (!trackDb)
+        return;
+    try {
+        const durationMs = Date.now() - startMs;
+        const tokensOut = estimateTokens(responseText);
+        const multiplier = TOKEN_SAVINGS_MULTIPLIER[tool] ?? 2;
+        const tokensSaved = tokensOut * (multiplier - 1); // net savings = what agent would spend minus what milens returned
+        trackDb.logToolUsage(tool, durationMs, tokensOut, tokensSaved, repo);
+    }
+    catch { /* best-effort */ }
+}
+function fmtSymbol(s, detail = 'L1') {
+    const base = `${s.name} [${s.kind}] ${s.filePath}:${s.startLine}`;
+    if (detail === 'L0')
+        return `${s.name} [${s.kind}]`;
+    if (detail === 'L2') {
+        const meta = [];
+        if (s.role)
+            meta.push(s.role);
+        if (s.heat != null && s.heat > 0)
+            meta.push(`heat:${s.heat}`);
+        return meta.length > 0 ? `${base} {${meta.join(',')}}` : base;
+    }
+    return base;
+}
+function fmtImpact(items, detail = 'L1') {
     const grouped = new Map();
     for (const { symbol, depth, via } of items) {
         const arr = grouped.get(depth) ?? [];
-        arr.push(`${fmtSymbol(symbol)} (${via})`);
+        arr.push(`${fmtSymbol(symbol, detail)} (${via})`);
         grouped.set(depth, arr);
     }
     const lines = [];
@@ -61,6 +122,14 @@ function fmtImpact(items) {
     }
     return lines.join('\n');
 }
+/** Check if a file path looks like a test/spec file */
+function isTestFilePath(filePath) {
+    return /\.(test|spec)\.[jt]sx?$/.test(filePath) ||
+        /^tests?[/\\]/.test(filePath) ||
+        /__tests__[/\\]/.test(filePath) ||
+        /_test\.(go|py|rb|rs|java|php)$/.test(filePath) ||
+        /^test_.*\.py$/.test(filePath.split('/').pop() ?? '');
+}
 // ── Text grep across project files ──
 const GREP_SKIP_DIRS = new Set([
     'node_modules', '.git', 'dist', 'build', 'out',
@@ -150,6 +219,15 @@ function grepFiles(rootPath, pattern, options) {
 function escapeRegExp(s) {
     return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
+/** Line-level scope matching for scoped grep */
+function matchesScope(lineText, scope) {
+    const trimmed = lineText.trimStart();
+    if (scope === 'imports') {
+        return /^(import\s|from\s|require\(|use\s|include\s|require_relative|require\s)/.test(trimmed);
+    }
+    // definitions: function, class, interface, struct, trait, enum, type, def, fn, pub fn, etc.
+    return /^(export\s+)?(async\s+)?(function|class|interface|type|enum|struct|trait|const|let|var|def|fn|pub\s+fn|pub\s+struct|pub\s+enum|module)\s/.test(trimmed);
+}
 /** Validate user-supplied regex is safe from catastrophic backtracking (ReDoS). */
 function safeRegex(pattern, flags) {
     if (pattern.length > 200)
@@ -157,6 +235,24 @@ function safeRegex(pattern, flags) {
     // Reject nested quantifiers like (a+)+, (a*)*,  (a{1,})+
     if (/([+*}])\)?[+*{]/.test(pattern))
         throw new Error('Unsafe regex pattern');
+    // Reject overlapping alternation inside quantified groups: (a|a)*, (ab|a)+
+    if (/\((?:[^)]*\|[^)]*)\)[+*{]/.test(pattern))
+        throw new Error('Unsafe regex pattern');
+    // Reject backreferences inside quantified groups (exponential matching)
+    if (/\((?:[^)]*\\[1-9][^)]*)\)[+*{]/.test(pattern))
+        throw new Error('Unsafe regex pattern');
+    // Reject deeply nested groups (>3 levels)
+    let depth = 0, maxDepth = 0;
+    for (const ch of pattern) {
+        if (ch === '(') {
+            depth++;
+            maxDepth = Math.max(maxDepth, depth);
+        }
+        else if (ch === ')')
+            depth--;
+    }
+    if (maxDepth > 3)
+        throw new Error('Unsafe regex pattern');
     return new RegExp(pattern, flags);
 }
 function globToRegex(glob) {
@@ -178,53 +274,70 @@ function loadGrepIgnoreRules(rootPath) {
     return ig;
 }
 // ── Server instructions (sent to client via MCP protocol on initialize) ──
-const MILENS_INSTRUCTIONS = `milens is a code intelligence engine. It indexes codebases into knowledge graphs and provides tools for navigating and understanding code.
-
-## Critical Workflow Rules
-
-### Always combine \`impact\` with \`grep\`
-\`impact\` only tracks code-level symbol dependencies (calls, imports, extends).
-\`grep\` finds ALL text references including templates, styles, configs, routes, and docs.
-**After running \`impact\`, always run \`grep\` for the same symbol to catch non-code references.**
-
-### Before editing a symbol
-1. Run \`context\` to see all incoming/outgoing relationships
-2. Run \`impact\` with direction "upstream" to find what depends on it
-3. Run \`grep\` to find ALL text references (templates, SCSS, configs, routes, docs)
-
-### When deleting a feature or renaming
-1. Run \`grep\` first — finds every text occurrence across all file types
-2. Run \`impact\` — finds code-level dependency graph
-3. Combine both results — grep catches what impact misses and vice versa
-
-### Tool selection guide
-- **Find symbol definitions** → \`query\`
-- **Find ALL text references** (templates, styles, configs, docs) → \`grep\`
-- **Understand a symbol's relationships** → \`context\`
-- **What breaks if I change this?** → \`impact\` (upstream) + \`grep\`
-- **What does this call/depend on?** → \`impact\` (downstream)
-- **How are two symbols connected?** → \`explain_relationship\`
-- **What changed recently?** → \`detect_changes\`
-- **Find unused exports** → \`find_dead_code\`
-- **See all symbols in a file** → \`get_file_symbols\`
-- **Class inheritance tree** → \`get_type_hierarchy\`
-
-### Impact depth guide
-- depth 1: WILL BREAK — direct callers/importers → must update
-- depth 2: LIKELY AFFECTED — indirect dependents → should test
-- depth 3: MAY NEED TESTING — transitive → test if critical path
+const MILENS_INSTRUCTIONS = `milens — code intelligence engine. Indexes codebases into symbol graphs.
+
+## Tool selection
+- \`query\` — find symbol definitions (code identifiers only)
+- \`grep\` — text search ALL files. Use \`scope\` param: all (default), code (source only), imports, definitions
+- \`context\` — 360° view: incoming + outgoing for a symbol
+- \`impact\` — blast radius: what breaks if symbol changes
+- \`overview\` — combined context + impact + grep in one call (preferred for editing workflows)
+- \`edit_check\` — pre-edit safety: callers + export status + re-export chains + test coverage + ⚠ warnings (fastest for edits)
+- \`trace\` — execution flow: call chains from entrypoints to a symbol (or downstream from it)
+- \`routes\` — detect framework routes/endpoints (Express, FastAPI, NestJS, Flask, Go, PHP, Rails)
+- \`smart_context\` — intent-aware context: understand/edit/debug/test (returns only what matters for intent)
+- \`domains\` — show domain clusters: groups of files forming logical modules based on dependency graph
+- \`repos\` — list all indexed repositories with summary stats (multi-repo support)
+- \`detect_changes\` — git diff → affected symbols
+- \`explain_relationship\` — shortest path between two symbols
+- \`find_dead_code\` — unused exports
+- \`get_file_symbols\` — all symbols in a file
+- \`get_type_hierarchy\` — inheritance tree
+
+## Rules
+- Before editing a symbol: run \`edit_check\` or \`smart_context\` with intent=edit
+- For debugging: run \`smart_context\` with intent=debug or \`trace\` to=symbol
+- For writing tests: run \`smart_context\` with intent=test — shows deps to mock + callers to cover
+- \`impact\` only tracks code deps — always pair with \`grep\` for templates/configs
+- Use \`query\` for camelCase/PascalCase identifiers, \`grep\` for display text or multi-word strings
+- impact depth: 1=WILL BREAK, 2=LIKELY AFFECTED, 3=MAY NEED TESTING
+- ⚠ markers indicate unresolved INTERNAL references — external package imports/calls are tracked separately
+- ✓ test coverage shown on edit_check — symbols with no test coverage get a warning
+- ⏳ staleness: files not re-analyzed in 24h are flagged — consider re-running \`milens analyze\`
+
+## Resources (MCP Resources protocol)
+- \`milens://overview\` — index overview (stats, domains, coverage, staleness)
+- \`milens://symbol/{name}\` — symbol context by name
+- \`milens://file/{path}\` — all symbols in a file
+- \`milens://domain/{name}\` — domain cluster details
 `;
 // ── Server setup ──
 export function createMcpServer(rootPath) {
     const registry = new RepoRegistry();
     const pools = new Map();
+    const trackDb = getTrackingDb();
     function resolveRoot(repoPath) {
-        const root = resolve(repoPath ?? rootPath ?? '.');
-        // Prevent path traversal — repo must be registered in the index
-        const entry = registry.findByRoot(root);
-        if (!entry)
-            throw new Error(`No index for ${root}. Run \`milens analyze\` first.`);
-        return root;
+        if (repoPath) {
+            const root = resolve(repoPath);
+            const entry = registry.findByRoot(root);
+            if (!entry)
+                throw new Error(`No index for ${root}. Run \`milens analyze\` first.`);
+            return root;
+        }
+        if (rootPath) {
+            const root = resolve(rootPath);
+            const entry = registry.findByRoot(root);
+            if (!entry)
+                throw new Error(`No index for ${root}. Run \`milens analyze\` first.`);
+            return root;
+        }
+        // Auto-resolve: if exactly 1 repo is indexed, use it
+        const all = registry.listAll();
+        if (all.length === 1)
+            return all[0].rootPath;
+        if (all.length === 0)
+            throw new Error('No indexed repositories. Run `milens analyze` first.');
+        throw new Error(`Multiple repos indexed (${all.length}). Specify \`repo\` parameter.`);
     }
     function getDb(repoPath) {
         const root = resolveRoot(repoPath);
@@ -235,10 +348,26 @@ export function createMcpServer(rootPath) {
             pools.set(root, new LazyDb(dbPath));
         return { db: pools.get(root).get(), root };
     }
-    const server = new McpServer({ name: 'milens', version: '0.3.1' }, { instructions: MILENS_INSTRUCTIONS });
+    const server = new McpServer({ name: 'milens', version: PKG_VERSION }, { instructions: MILENS_INSTRUCTIONS });
+    // Auto-wrap every tool handler with usage tracking
+    const origTool = server.tool.bind(server);
+    server.tool = ((...args) => {
+        const toolName = args[0];
+        const handler = args[args.length - 1];
+        if (typeof handler === 'function') {
+            args[args.length - 1] = async (...handlerArgs) => {
+                const start = Date.now();
+                const result = await handler(...handlerArgs);
+                const responseText = result?.content?.map((c) => c.text).join('\n') ?? '';
+                const repo = handlerArgs[0]?.repo;
+                trackToolCall(trackDb, toolName, start, responseText, repo);
+                return result;
+            };
+        }
+        return origTool(...args);
+    });
     // ── Tool: query ──
-    server.tool('query', 'Search indexed symbol definitions (functions, classes, exports) by name, kind, or file path. ' +
-        'Only finds symbols in indexed code files. For text references in templates, SCSS, configs, or docs, use `grep` instead.', {
+    server.tool('query', 'Search indexed symbol definitions by name/kind. For text in templates/configs/docs, use `grep`.', {
         query: z.string().describe('Symbol name, kind, or keyword to search'),
         repo: z.string().optional().describe('Repository root path (optional if only one indexed)'),
         limit: z.number().optional().default(15).describe('Max results'),
@@ -246,75 +375,87 @@ export function createMcpServer(rootPath) {
         const { db } = getDb(repo);
         const results = db.searchSymbols(query, limit);
         if (results.length === 0) {
-            return { content: [{ type: 'text', text: `No symbols matching "${query}". NOTE: query only searches indexed symbol definitions. Use \`grep\` to search ALL project files (templates, styles, configs, docs).` }] };
+            return { content: [{ type: 'text', text: `No symbols matching "${query}". Try \`grep\` for non-code references.` }] };
         }
         const text = results.map(s => fmtSymbol(s)).join('\n');
         return { content: [{ type: 'text', text }] };
     });
     // ── Tool: grep ──
-    server.tool('grep', 'Text search across ALL project files (templates, styles, configs, docs, routes, etc.). ' +
-        'Unlike `query` which only searches indexed symbol definitions, grep finds every text occurrence. ' +
-        'Essential for: deleting features, renaming across templates/SCSS/configs, finding route/config references.', {
+    server.tool('grep', 'Text search ALL project files (templates, styles, configs, docs). Finds every text occurrence, not just symbols.', {
         pattern: z.string().describe('Text or regex pattern to search for'),
         repo: z.string().optional().describe('Repository root path (optional)'),
         isRegex: z.boolean().optional().default(false).describe('Treat pattern as regex'),
         caseSensitive: z.boolean().optional().default(false),
         include: z.string().optional().describe('Glob filter for file paths (e.g. "**/*.vue", "*.scss")'),
+        scope: z.enum(['all', 'code', 'imports', 'definitions']).optional().default('all')
+            .describe('Scope: all=everything, code=source files only (no configs/docs), imports=import/require lines only, definitions=function/class/interface declarations only'),
         limit: z.number().optional().default(50).describe('Max results'),
-    }, async ({ pattern, repo, isRegex, caseSensitive, include, limit }) => {
+    }, async ({ pattern, repo, isRegex, caseSensitive, include, scope, limit }) => {
         const root = resolveRoot(repo);
+        const effectiveInclude = scope === 'code' && !include
+            ? '**/*.{ts,tsx,js,jsx,mjs,cjs,vue,py,go,rs,java,php,rb}'
+            : include;
         const matches = grepFiles(root, pattern, {
-            isRegex, caseSensitive, maxResults: limit, includePattern: include,
+            isRegex, caseSensitive, maxResults: limit, includePattern: effectiveInclude,
         });
-        if (matches.length === 0) {
-            return { content: [{ type: 'text', text: `No matches for "${pattern}"` }] };
+        // Apply scope-specific line filtering
+        const filtered = scope === 'all' || scope === 'code'
+            ? matches
+            : matches.filter(m => matchesScope(m.text, scope));
+        if (filtered.length === 0) {
+            return { content: [{ type: 'text', text: `No matches for "${pattern}"${scope !== 'all' ? ` (scope: ${scope})` : ''}` }] };
         }
         // Group by file for compact output
         const grouped = new Map();
-        for (const m of matches) {
+        for (const m of filtered) {
             const arr = grouped.get(m.file) ?? [];
             arr.push({ line: m.line, text: m.text });
             grouped.set(m.file, arr);
         }
-        const lines = [`${matches.length} matches in ${grouped.size} files:\n`];
+        const lines = [`${filtered.length} matches in ${grouped.size} files${scope !== 'all' ? ` (scope: ${scope})` : ''}:\n`];
         for (const [file, hits] of grouped) {
             lines.push(file);
             for (const h of hits) {
                 lines.push(`  L${h.line}: ${h.text}`);
             }
         }
-        if (matches.length >= limit) {
+        if (filtered.length >= limit) {
             lines.push(`\n(truncated at ${limit} results — increase limit or narrow pattern)`);
         }
         return { content: [{ type: 'text', text: lines.join('\n') }] };
     });
     // ── Tool: context ──
-    server.tool('context', 'Get 360° context of a symbol: incoming refs, outgoing deps, parent, children.', {
+    server.tool('context', 'Symbol 360°: incoming refs + outgoing deps. Use `overview` for combined context+impact+grep.', {
         name: z.string().describe('Symbol name to inspect'),
         repo: z.string().optional(),
-    }, async ({ name, repo }) => {
+        detail: z.enum(['L0', 'L1', 'L2']).optional().default('L1').describe('Output detail: L0=names only, L1=default, L2=full metadata'),
+    }, async ({ name, repo, detail }) => {
         const { db } = getDb(repo);
         const symbols = db.findSymbolByName(name);
         if (symbols.length === 0) {
-            return { content: [{ type: 'text', text: `Symbol "${name}" not found in index. Use \`grep\` to search ALL project files for text references.` }] };
+            return { content: [{ type: 'text', text: `"${name}" not found. Try \`grep\`.` }] };
         }
         const lines = [];
         for (const sym of symbols) {
-            lines.push(`## ${fmtSymbol(sym)}${sym.exported ? ' (exported)' : ''}`);
+            lines.push(`## ${fmtSymbol(sym, detail)}${sym.exported ? ' (exported)' : ''}`);
             const incoming = db.getIncomingLinks(sym.id);
             if (incoming.length > 0) {
                 lines.push('incoming:');
-                for (const l of incoming) {
-                    const from = db.findSymbolById(l.fromId);
-                    lines.push(`  ${l.type}: ${from ? fmtSymbol(from) : l.fromId}`);
+                const inSyms = incoming.map(l => ({ link: l, sym: db.findSymbolById(l.fromId) }));
+                if (detail === 'L2')
+                    inSyms.sort((a, b) => (b.sym?.heat ?? 0) - (a.sym?.heat ?? 0));
+                for (const { link: l, sym: from } of inSyms) {
+                    lines.push(`  ${l.type}: ${from ? fmtSymbol(from, detail) : l.fromId}`);
                 }
             }
             const outgoing = db.getOutgoingLinks(sym.id);
             if (outgoing.length > 0) {
                 lines.push('outgoing:');
-                for (const l of outgoing) {
-                    const to = db.findSymbolById(l.toId);
-                    lines.push(`  ${l.type}: ${to ? fmtSymbol(to) : l.toId}`);
+                const outSyms = outgoing.map(l => ({ link: l, sym: db.findSymbolById(l.toId) }));
+                if (detail === 'L2')
+                    outSyms.sort((a, b) => (b.sym?.heat ?? 0) - (a.sym?.heat ?? 0));
+                for (const { link: l, sym: to } of outSyms) {
+                    lines.push(`  ${l.type}: ${to ? fmtSymbol(to, detail) : l.toId}`);
                 }
             }
             lines.push('');
@@ -322,47 +463,204 @@ export function createMcpServer(rootPath) {
         return { content: [{ type: 'text', text: lines.join('\n') }] };
     });
     // ── Tool: impact ──
-    server.tool('impact', 'Blast radius analysis via symbol dependency graph. Shows what code-level symbols break if a symbol changes. ' +
-        'Note: only tracks code dependencies (calls, imports, extends). For template/SCSS/config references, also use `grep`.', {
+    server.tool('impact', 'Blast radius: what symbols break if target changes. Code deps only — pair with `grep` for templates/configs.', {
         target: z.string().describe('Symbol name to analyze'),
         direction: z.enum(['upstream', 'downstream']).default('upstream'),
         depth: z.number().optional().default(3),
         repo: z.string().optional(),
-    }, async ({ target, direction, depth, repo }) => {
+        detail: z.enum(['L0', 'L1', 'L2']).optional().default('L1').describe('Output detail: L0=names only, L1=default, L2=full metadata'),
+    }, async ({ target, direction, depth, repo, detail }) => {
         const { db } = getDb(repo);
         const symbols = db.findSymbolByName(target);
         if (symbols.length === 0) {
-            return { content: [{ type: 'text', text: `Symbol "${target}" not found in index. Use \`grep\` to search ALL project files for text references.` }] };
+            return { content: [{ type: 'text', text: `"${target}" not found. Try \`grep\`.` }] };
         }
         const lines = [];
         for (const sym of symbols) {
-            lines.push(`TARGET: ${fmtSymbol(sym)}`);
+            lines.push(`TARGET: ${fmtSymbol(sym, detail)}`);
             const refs = direction === 'upstream'
                 ? db.findUpstream(sym.id, depth)
                 : db.findDownstream(sym.id, depth);
             if (refs.length === 0) {
-                lines.push(`No ${direction} dependencies found in symbol graph. IMPORTANT: Also run \`grep\` for "${target}" to find references in templates, styles, configs, routes, and docs that are not tracked by impact analysis.`);
+                lines.push(`No ${direction} deps found.`);
             }
             else {
                 lines.push(`${direction} (${refs.length} symbols):`);
-                lines.push(fmtImpact(refs));
-                lines.push(`\nNOTE: impact only tracks code-level dependencies. Also run \`grep\` for "${target}" to find template/style/config/doc references.`);
+                lines.push(fmtImpact(refs, detail));
             }
             lines.push('');
         }
         return { content: [{ type: 'text', text: lines.join('\n') }] };
     });
     // ── Tool: status ──
-    server.tool('status', 'Show index stats for a repository.', {
+    server.tool('status', 'Index stats for a repository.', {
         repo: z.string().optional(),
     }, async ({ repo }) => {
         const { db, root } = getDb(repo);
         const stats = db.getStats();
-        const text = `repo: ${root}\nsymbols: ${stats.symbols}\nlinks: ${stats.links}\nfiles: ${stats.files}`;
+        const unresolved = db.getUnresolvedStats();
+        const coverage = db.getTestCoverage();
+        let text = `repo: ${root}\nsymbols: ${stats.symbols}\nlinks: ${stats.links}\nfiles: ${stats.files}`;
+        if (unresolved.imports > 0 || unresolved.calls > 0) {
+            text += `\n⚠ unresolved (internal): ${unresolved.imports} imports, ${unresolved.calls} calls — callers may be incomplete`;
+        }
+        if (unresolved.externalImports > 0 || unresolved.externalCalls > 0) {
+            text += `\nexternal (expected): ${unresolved.externalImports} imports, ${unresolved.externalCalls} calls`;
+        }
+        if (coverage.testFiles > 0) {
+            const pct = coverage.exportedProductionSymbols > 0
+                ? Math.round(coverage.testedSymbols / coverage.exportedProductionSymbols * 100)
+                : 0;
+            text += `\ntest coverage: ${coverage.testedSymbols}/${coverage.exportedProductionSymbols} exported symbols (${pct}%) from ${coverage.testFiles} test files`;
+        }
+        const domains = db.getDomainStats();
+        if (domains.length > 0) {
+            text += `\ndomains: ${domains.map(d => `${d.domain}(${d.files}f/${d.symbols}s)`).join(', ')}`;
+        }
+        const staleFiles = db.getStaleFiles(24);
+        if (staleFiles.length > 0) {
+            text += `\n⏳ ${staleFiles.length} files not analyzed in 24h`;
+        }
         return { content: [{ type: 'text', text }] };
     });
+    // ── Tool: domains ──
+    server.tool('domains', 'Show domain clusters — groups of files forming logical modules based on dependency graph. Helps understand codebase structure at a glance.', {
+        repo: z.string().optional(),
+    }, async ({ repo }) => {
+        const { db } = getDb(repo);
+        const domains = db.getDomainStats();
+        if (domains.length === 0) {
+            return { content: [{ type: 'text', text: 'No domains detected. Run `milens analyze` first.' }] };
+        }
+        const totalFiles = domains.reduce((s, d) => s + d.files, 0);
+        const totalSymbols = domains.reduce((s, d) => s + d.symbols, 0);
+        const lines = [`${domains.length} domains (${totalFiles} files, ${totalSymbols} symbols):\n`];
+        for (const d of domains) {
+            const pct = totalSymbols > 0 ? Math.round(d.symbols / totalSymbols * 100) : 0;
+            lines.push(`  ${d.domain}: ${d.files} files, ${d.symbols} symbols (${pct}%)`);
+        }
+        const staleFiles = db.getStaleFiles(24);
+        if (staleFiles.length > 0) {
+            lines.push(`\n⏳ ${staleFiles.length} files stale (>24h) — re-run \`milens analyze\` for fresh clusters`);
+        }
+        return { content: [{ type: 'text', text: lines.join('\n') }] };
+    });
+    // ── Tool: overview ──
+    server.tool('overview', 'Combined context + impact + grep in ONE call. Preferred before editing/deleting/renaming a symbol. Saves 2-3 round trips.', {
+        name: z.string().describe('Symbol name'),
+        repo: z.string().optional(),
+        depth: z.number().optional().default(2).describe('Impact traversal depth (default: 2)'),
+        detail: z.enum(['L0', 'L1', 'L2']).optional().default('L1').describe('Output detail level'),
+    }, async ({ name, repo, depth, detail }) => {
+        const { db, root } = getDb(repo);
+        const symbols = db.findSymbolByName(name);
+        const sections = [];
+        // Section 1: Symbol definitions
+        if (symbols.length === 0) {
+            sections.push(`[symbol] "${name}" not found in index.`);
+        }
+        else {
+            for (const sym of symbols) {
+                sections.push(`[symbol] ${fmtSymbol(sym, detail)}${sym.exported ? ' (exported)' : ''}`);
+            }
+        }
+        // Section 2: Context (incoming + outgoing) for each symbol
+        if (symbols.length > 0) {
+            for (const sym of symbols) {
+                const incoming = db.getIncomingLinks(sym.id).filter(l => l.type !== 'contains');
+                const outgoing = db.getOutgoingLinks(sym.id).filter(l => l.type !== 'contains');
+                if (incoming.length > 0) {
+                    sections.push(`[incoming] ${incoming.length} refs:`);
+                    const inSyms = incoming.map(l => {
+                        const s = db.findSymbolById(l.fromId);
+                        return s ? `  ${l.type}: ${fmtSymbol(s, detail)}` : `  ${l.type}: ${l.fromId}`;
+                    });
+                    sections.push(...inSyms);
+                }
+                if (outgoing.length > 0) {
+                    sections.push(`[outgoing] ${outgoing.length} deps:`);
+                    const outSyms = outgoing.map(l => {
+                        const s = db.findSymbolById(l.toId);
+                        return s ? `  ${l.type}: ${fmtSymbol(s, detail)}` : `  ${l.type}: ${l.toId}`;
+                    });
+                    sections.push(...outSyms);
+                }
+            }
+            // Section 3: Impact (upstream)
+            for (const sym of symbols) {
+                const upstream = db.findUpstream(sym.id, depth);
+                if (upstream.length > 0) {
+                    sections.push(`[impact] ${upstream.length} upstream deps:`);
+                    sections.push(fmtImpact(upstream, detail));
+                }
+                else {
+                    sections.push(`[impact] No upstream deps.`);
+                }
+            }
+        }
+        // Section 4: Grep (text references across all files)
+        const grepMatches = grepFiles(root, name, { maxResults: 20 });
+        if (grepMatches.length > 0) {
+            const grouped = new Map();
+            for (const m of grepMatches) {
+                const arr = grouped.get(m.file) ?? [];
+                arr.push({ line: m.line, text: m.text });
+                grouped.set(m.file, arr);
+            }
+            sections.push(`[grep] ${grepMatches.length} text matches in ${grouped.size} files:`);
+            for (const [file, hits] of grouped) {
+                sections.push(`  ${file}`);
+                for (const h of hits)
+                    sections.push(`    L${h.line}: ${h.text}`);
+            }
+        }
+        else {
+            sections.push(`[grep] No text matches.`);
+        }
+        // Section 5: Unresolved warnings (only for internal)
+        const unresolved = db.getUnresolvedStats();
+        if (unresolved.imports > 0 || unresolved.calls > 0) {
+            sections.push(`[⚠ unresolved internal] ${unresolved.imports} imports, ${unresolved.calls} calls — some references may be missing`);
+        }
+        return { content: [{ type: 'text', text: sections.join('\n') }] };
+    });
+    // ── Tool: repos ──
+    server.tool('repos', 'List all indexed repositories with summary stats. Useful for multi-repo workspaces.', {}, async () => {
+        const entries = registry.listAll();
+        if (entries.length === 0) {
+            return { content: [{ type: 'text', text: 'No indexed repositories. Run `milens analyze` first.' }] };
+        }
+        const lines = [`${entries.length} indexed repositories:\n`];
+        for (const entry of entries) {
+            lines.push(`${entry.rootPath}`);
+            lines.push(`  indexed: ${entry.analyzedAt}`);
+            try {
+                const dbPath = registry.findDbPath(entry.rootPath);
+                if (dbPath) {
+                    const tempDb = pools.has(entry.rootPath)
+                        ? pools.get(entry.rootPath).get()
+                        : new Database(dbPath);
+                    const summary = tempDb.getRepoSummary();
+                    lines.push(`  ${summary.symbols} symbols, ${summary.links} links, ${summary.files} files`);
+                    if (summary.domains.length > 0) {
+                        lines.push(`  domains: ${summary.domains.join(', ')}`);
+                    }
+                    if (summary.staleCount > 0) {
+                        lines.push(`  ⏳ ${summary.staleCount} stale files`);
+                    }
+                    if (!pools.has(entry.rootPath))
+                        tempDb.close();
+                }
+            }
+            catch {
+                lines.push(`  (unable to read index)`);
+            }
+            lines.push('');
+        }
+        return { content: [{ type: 'text', text: lines.join('\n') }] };
+    });
     // ── Tool: detect_changes ──
-    server.tool('detect_changes', 'Detect changed files via git diff and find affected symbols with upstream impact.', {
+    server.tool('detect_changes', 'Git diff → affected symbols + direct dependents.', {
         ref: z.string().optional().default('HEAD').describe('Git ref to diff against (default: HEAD)'),
         repo: z.string().optional(),
     }, async ({ ref, repo }) => {
@@ -404,7 +702,7 @@ export function createMcpServer(rootPath) {
         return { content: [{ type: 'text', text: lines.join('\n') }] };
     });
     // ── Tool: explain_relationship ──
-    server.tool('explain_relationship', 'Explain how two symbols are connected. Finds the shortest path in the dependency graph.', {
+    server.tool('explain_relationship', 'Shortest dependency path between two symbols.', {
         from: z.string().describe('Source symbol name'),
         to: z.string().describe('Target symbol name'),
         repo: z.string().optional(),
@@ -412,7 +710,7 @@ export function createMcpServer(rootPath) {
         const { db } = getDb(repo);
         const path = db.findPath(from, to);
         if (!path) {
-            return { content: [{ type: 'text', text: `No relationship found between "${from}" and "${to}" in the symbol graph. Use \`grep\` to search for text references that may connect them.` }] };
+            return { content: [{ type: 'text', text: `No path between "${from}" and "${to}".` }] };
         }
         const fromSym = db.findSymbolByName(from)[0];
         const lines = [`FROM: ${fmtSymbol(fromSym)}`, ''];
@@ -422,7 +720,7 @@ export function createMcpServer(rootPath) {
         return { content: [{ type: 'text', text: lines.join('\n') }] };
     });
     // ── Tool: find_dead_code ──
-    server.tool('find_dead_code', 'Find exported symbols with zero incoming references (potentially unused code).', {
+    server.tool('find_dead_code', 'Exported symbols with zero incoming references (potentially unused).', {
         kind: z.string().optional().describe('Filter by symbol kind (function, class, method, etc.)'),
         limit: z.number().optional().default(30),
         repo: z.string().optional(),
@@ -439,33 +737,52 @@ export function createMcpServer(rootPath) {
         return { content: [{ type: 'text', text: lines.join('\n') }] };
     });
     // ── Tool: get_file_symbols ──
-    server.tool('get_file_symbols', 'List all symbols defined in a specific file with their relationships.', {
+    server.tool('get_file_symbols', 'All symbols in a file with ref/dep counts.', {
         file: z.string().describe('File path (relative to repo root)'),
         repo: z.string().optional(),
-    }, async ({ file, repo }) => {
+        detail: z.enum(['L0', 'L1', 'L2']).optional().default('L1').describe('Output detail: L0=names only, L1=default, L2=full metadata'),
+    }, async ({ file, repo, detail }) => {
         const { db } = getDb(repo);
         const symbols = db.getSymbolsByFile(file);
         if (symbols.length === 0) {
             return { content: [{ type: 'text', text: `No symbols found in "${file}". Is the path relative to repo root?` }] };
         }
+        // Sort by heat descending in L2 mode for relevance-first output
+        const sorted = detail === 'L2'
+            ? [...symbols].sort((a, b) => (b.heat ?? 0) - (a.heat ?? 0))
+            : symbols;
         const lines = [`${file}: ${symbols.length} symbols\n`];
-        for (const sym of symbols) {
+        for (const sym of sorted) {
             const incoming = db.getIncomingLinks(sym.id).filter(l => l.type !== 'contains');
             const outgoing = db.getOutgoingLinks(sym.id).filter(l => l.type !== 'contains');
             const exp = sym.exported ? ' (exported)' : '';
-            lines.push(`${sym.name} [${sym.kind}] L${sym.startLine}-${sym.endLine}${exp} ← ${incoming.length} refs, → ${outgoing.length} deps`);
+            if (detail === 'L0') {
+                lines.push(`${sym.name} [${sym.kind}]${exp}`);
+            }
+            else if (detail === 'L2') {
+                const meta = [];
+                if (sym.role)
+                    meta.push(sym.role);
+                if (sym.heat != null && sym.heat > 0)
+                    meta.push(`heat:${sym.heat}`);
+                const metaStr = meta.length > 0 ? ` {${meta.join(',')}}` : '';
+                lines.push(`${sym.name} [${sym.kind}] L${sym.startLine}-${sym.endLine}${exp}${metaStr} ← ${incoming.length} refs, → ${outgoing.length} deps`);
+            }
+            else {
+                lines.push(`${sym.name} [${sym.kind}] L${sym.startLine}-${sym.endLine}${exp} ← ${incoming.length} refs, → ${outgoing.length} deps`);
+            }
         }
         return { content: [{ type: 'text', text: lines.join('\n') }] };
     });
     // ── Tool: get_type_hierarchy ──
-    server.tool('get_type_hierarchy', 'Show the inheritance/implementation hierarchy of a class, interface, or trait.', {
+    server.tool('get_type_hierarchy', 'Inheritance/implementation tree for a class, interface, or trait.', {
         name: z.string().describe('Symbol name to show hierarchy for'),
         repo: z.string().optional(),
     }, async ({ name, repo }) => {
         const { db } = getDb(repo);
         const symbols = db.findSymbolByName(name);
         if (symbols.length === 0) {
-            return { content: [{ type: 'text', text: `Symbol "${name}" not found in index. Use \`grep\` to search ALL project files for text references.` }] };
+            return { content: [{ type: 'text', text: `"${name}" not found. Try \`grep\`.` }] };
         }
         const lines = [];
         for (const sym of symbols) {
@@ -478,18 +795,489 @@ export function createMcpServer(rootPath) {
                 }
             }
             if (descendants.length > 0) {
-                lines.push('implemented/extended by:');
+                lines.push('extended/implemented by:');
                 for (const { symbol: d, depth } of descendants) {
                     lines.push(`  ${'↓'.repeat(depth)} ${fmtSymbol(d)}`);
                 }
             }
             if (ancestors.length === 0 && descendants.length === 0) {
-                lines.push('No inheritance relationships found.');
+                lines.push('No inheritance relationships.');
+            }
+            lines.push('');
+        }
+        return { content: [{ type: 'text', text: lines.join('\n') }] };
+    });
+    // ── Tool: edit_check ──
+    server.tool('edit_check', 'Pre-edit safety check: callers, export status, re-export chains, ⚠ warnings. Focused for editing intent — no downstream deps, no outgoing calls. Use BEFORE modifying a symbol.', {
+        name: z.string().describe('Symbol name to check before editing'),
+        repo: z.string().optional(),
+    }, async ({ name, repo }) => {
+        const { db, root } = getDb(repo);
+        const symbols = db.findSymbolByName(name);
+        const sections = [];
+        if (symbols.length === 0) {
+            sections.push(`"${name}" not found in index. Try \`grep\`.`);
+            return { content: [{ type: 'text', text: sections.join('\n') }] };
+        }
+        for (const sym of symbols) {
+            // 1. Symbol info
+            sections.push(`${fmtSymbol(sym)}${sym.exported ? ' (exported)' : ''}`);
+            // 2. Who calls/uses this? (direct upstream only — what WILL break)
+            const incoming = db.getIncomingLinks(sym.id).filter(l => l.type !== 'contains');
+            if (incoming.length > 0) {
+                sections.push(`callers (${incoming.length}):`);
+                for (const l of incoming) {
+                    const from = db.findSymbolById(l.fromId);
+                    sections.push(`  ${l.type}: ${from ? fmtSymbol(from) : l.fromId}`);
+                }
+            }
+            else {
+                sections.push(`callers: none`);
+            }
+            // 3. Export chain — is this re-exported from barrel files?
+            const grepMatches = grepFiles(root, name, { maxResults: 10, includePattern: '**/index.{ts,js,mjs}' });
+            const reExportMatches = grepMatches.filter(m => /export\s*\{[^}]*/.test(m.text) && m.text.includes('from'));
+            if (reExportMatches.length > 0) {
+                sections.push(`re-exported via:`);
+                for (const m of reExportMatches) {
+                    sections.push(`  ${m.file}:${m.line}`);
+                }
+            }
+            // 4. Heritage — is this a parent class?
+            const descendants = db.getTypeHierarchy(sym.id).descendants;
+            if (descendants.length > 0) {
+                sections.push(`⚠ inherited by ${descendants.length} types:`);
+                for (const { symbol: d } of descendants) {
+                    sections.push(`  ${fmtSymbol(d)}`);
+                }
+            }
+        }
+        // 5. Unresolved warning (only for internal)
+        const unresolved = db.getUnresolvedStats();
+        if (unresolved.imports > 0 || unresolved.calls > 0) {
+            sections.push(`⚠ index has ${unresolved.imports} unresolved internal imports, ${unresolved.calls} unresolved internal calls — callers list may be incomplete`);
+        }
+        // 6. Test coverage for this symbol
+        for (const sym of symbols) {
+            const incoming = db.getIncomingLinks(sym.id);
+            const testRefs = incoming.filter(l => {
+                const from = db.findSymbolById(l.fromId);
+                return from && isTestFilePath(from.filePath);
+            });
+            if (testRefs.length > 0) {
+                const testFiles = [...new Set(testRefs.map(l => {
+                        const from = db.findSymbolById(l.fromId);
+                        return from?.filePath;
+                    }).filter(Boolean))];
+                sections.push(`✓ tested from: ${testFiles.join(', ')}`);
+            }
+            else if (sym.exported) {
+                sections.push(`⚠ no test coverage for this exported symbol`);
+            }
+        }
+        return { content: [{ type: 'text', text: sections.join('\n') }] };
+    });
+    // ── Tool: trace ──
+    server.tool('trace', 'Trace execution flow: find call chains from entrypoints to a target symbol, or from a symbol downstream. Shows HOW code gets executed.', {
+        name: z.string().describe('Symbol name to trace'),
+        direction: z.enum(['to', 'from']).optional().default('to')
+            .describe('to=trace paths TO this symbol from entrypoints, from=trace paths FROM this symbol downstream'),
+        repo: z.string().optional(),
+        depth: z.number().optional().default(8).describe('Max chain depth'),
+    }, async ({ name, direction, repo, depth }) => {
+        const { db } = getDb(repo);
+        const symbols = db.findSymbolByName(name);
+        if (symbols.length === 0) {
+            return { content: [{ type: 'text', text: `"${name}" not found. Try \`grep\`.` }] };
+        }
+        const sections = [];
+        for (const sym of symbols) {
+            if (direction === 'to') {
+                // Trace upstream to entrypoints
+                const traces = db.traceToEntrypoints(sym.id, depth);
+                sections.push(`## Execution paths TO ${fmtSymbol(sym)}\n`);
+                if (traces.length === 0) {
+                    sections.push('No call chains found (symbol may be an entrypoint itself or unreachable).');
+                }
+                else {
+                    for (let i = 0; i < traces.length; i++) {
+                        const chain = traces[i].path;
+                        sections.push(`path ${i + 1} (${chain.length} steps):`);
+                        sections.push(chain.map((step, idx) => {
+                            const arrow = idx === chain.length - 1 ? '→ (target)' : `→ [${chain[idx + 1]?.via ?? ''}]`;
+                            return `  ${' '.repeat(idx)}${fmtSymbol(step.symbol)} ${arrow}`;
+                        }).join('\n'));
+                        sections.push('');
+                    }
+                }
+            }
+            else {
+                // Trace downstream — show call/dependency tree from this symbol
+                const downstream = db.findDownstream(sym.id, depth);
+                sections.push(`## Execution paths FROM ${fmtSymbol(sym)}\n`);
+                if (downstream.length === 0) {
+                    sections.push('No downstream dependencies (leaf symbol).');
+                }
+                else {
+                    // Group by depth and show as tree
+                    const byDepth = new Map();
+                    for (const { symbol, depth: d, via } of downstream) {
+                        const arr = byDepth.get(d) ?? [];
+                        arr.push(`${'  '.repeat(d)}[${via}] ${fmtSymbol(symbol)}`);
+                        byDepth.set(d, arr);
+                    }
+                    for (const [, items] of [...byDepth].sort((a, b) => a[0] - b[0])) {
+                        sections.push(...items);
+                    }
+                }
+            }
+            sections.push('');
+        }
+        return { content: [{ type: 'text', text: sections.join('\n') }] };
+    });
+    // ── Tool: routes ──
+    server.tool('routes', 'Detect framework routes/endpoints and map them to handler symbols. Scans for Express, FastAPI, NestJS, Flask, Go HTTP, PHP, Rails patterns.', {
+        repo: z.string().optional(),
+        framework: z.string().optional().describe('Filter by framework (express, fastapi, nestjs, flask, go, php, rails). Default: auto-detect all.'),
+        limit: z.number().optional().default(50),
+    }, async ({ repo, framework, limit }) => {
+        const root = resolveRoot(repo);
+        const { db } = getDb(repo);
+        // Route patterns for different frameworks
+        const routePatterns = [
+            { name: 'express', pattern: /\b(?:app|router)\.(get|post|put|patch|delete|use|all)\s*\(\s*['"`]([^'"`]+)['"`]/, fileGlob: '**/*.{ts,js,mjs,cjs}' },
+            { name: 'fastapi', pattern: /@(?:app|router)\.(get|post|put|patch|delete)\s*\(\s*['"]([^'"]+)['"]/, fileGlob: '**/*.py' },
+            { name: 'flask', pattern: /@(?:app|bp|blueprint)\.(route|get|post|put|delete)\s*\(\s*['"]([^'"]+)['"]/, fileGlob: '**/*.py' },
+            { name: 'nestjs', pattern: /@(Get|Post|Put|Patch|Delete)\s*\(\s*['"]?([^'")]*?)['"]?\s*\)/, fileGlob: '**/*.ts' },
+            { name: 'go', pattern: /\b(?:mux|router|http)\.(HandleFunc|Handle|Get|Post|Put|Delete)\s*\(\s*['"]([^'"]+)['"]/, fileGlob: '**/*.go' },
+            { name: 'php', pattern: /Route::(get|post|put|patch|delete|any)\s*\(\s*['"]([^'"]+)['"]/, fileGlob: '**/*.php' },
+            { name: 'rails', pattern: /\b(get|post|put|patch|delete|resources?|root)\s+['"]([^'"]+)['"]/, fileGlob: '**/*.rb' },
+        ];
+        const activePatterns = framework
+            ? routePatterns.filter(p => p.name === framework.toLowerCase())
+            : routePatterns;
+        if (activePatterns.length === 0) {
+            return { content: [{ type: 'text', text: `Unknown framework "${framework}". Available: express, fastapi, nestjs, flask, go, php, rails` }] };
+        }
+        const routes = [];
+        for (const rp of activePatterns) {
+            const matches = grepFiles(root, rp.pattern.source, {
+                isRegex: true, maxResults: limit, includePattern: rp.fileGlob,
+            });
+            for (const m of matches) {
+                const match = rp.pattern.exec(m.text);
+                if (!match)
+                    continue;
+                const method = match[1].toUpperCase();
+                const path = match[2] || '/';
+                // Try to find the handler symbol on this line or nearby
+                const fileSymbols = db.getSymbolsByFile(m.file);
+                const handler = fileSymbols.find(s => s.startLine <= m.line && s.endLine >= m.line && s.kind === 'method') ?? fileSymbols.find(s => s.startLine <= m.line && s.endLine >= m.line) ?? fileSymbols.find(s => Math.abs(s.startLine - m.line) <= 3 && (s.kind === 'function' || s.kind === 'method'));
+                routes.push({
+                    framework: rp.name,
+                    method,
+                    path,
+                    file: m.file,
+                    line: m.line,
+                    handler: handler ? `${handler.name} [${handler.kind}]` : undefined,
+                });
+            }
+        }
+        if (routes.length === 0) {
+            return { content: [{ type: 'text', text: 'No framework routes detected.' }] };
+        }
+        // Group by framework
+        const grouped = new Map();
+        for (const r of routes) {
+            const arr = grouped.get(r.framework) ?? [];
+            arr.push(r);
+            grouped.set(r.framework, arr);
+        }
+        const lines = [`${routes.length} routes detected:\n`];
+        for (const [fw, fwRoutes] of grouped) {
+            lines.push(`[${fw}]`);
+            for (const r of fwRoutes) {
+                const handlerInfo = r.handler ? ` → ${r.handler}` : '';
+                lines.push(`  ${r.method.padEnd(7)} ${r.path}  (${r.file}:${r.line})${handlerInfo}`);
             }
             lines.push('');
         }
         return { content: [{ type: 'text', text: lines.join('\n') }] };
     });
+    // ── Tool: smart_context ──
+    server.tool('smart_context', 'Intent-aware context: returns different information based on what you want to do. Saves tokens by showing only what matters for your intent.', {
+        name: z.string().describe('Symbol name'),
+        intent: z.enum(['understand', 'edit', 'debug', 'test'])
+            .describe('understand=360° view, edit=callers+blast radius, debug=execution paths+data flow, test=coverage+dependencies'),
+        repo: z.string().optional(),
+    }, async ({ name, intent, repo }) => {
+        const { db, root } = getDb(repo);
+        const symbols = db.findSymbolByName(name);
+        if (symbols.length === 0) {
+            return { content: [{ type: 'text', text: `"${name}" not found. Try \`grep\`.` }] };
+        }
+        const sections = [];
+        for (const sym of symbols) {
+            sections.push(`${fmtSymbol(sym, 'L2')}${sym.exported ? ' (exported)' : ''}\n`);
+            if (intent === 'understand') {
+                // Full 360° — context + downstream + file structure
+                const incoming = db.getIncomingLinks(sym.id).filter(l => l.type !== 'contains');
+                const outgoing = db.getOutgoingLinks(sym.id).filter(l => l.type !== 'contains');
+                if (incoming.length > 0) {
+                    sections.push(`incoming (${incoming.length}):`);
+                    for (const l of incoming) {
+                        const from = db.findSymbolById(l.fromId);
+                        sections.push(`  ${l.type}: ${from ? fmtSymbol(from) : l.fromId}`);
+                    }
+                }
+                if (outgoing.length > 0) {
+                    sections.push(`outgoing (${outgoing.length}):`);
+                    for (const l of outgoing) {
+                        const to = db.findSymbolById(l.toId);
+                        sections.push(`  ${l.type}: ${to ? fmtSymbol(to) : l.toId}`);
+                    }
+                }
+                // Heritage
+                const { ancestors, descendants } = db.getTypeHierarchy(sym.id);
+                if (ancestors.length > 0) {
+                    sections.push(`extends: ${ancestors.map(a => fmtSymbol(a.symbol)).join(', ')}`);
+                }
+                if (descendants.length > 0) {
+                    sections.push(`extended by: ${descendants.map(d => fmtSymbol(d.symbol)).join(', ')}`);
+                }
+                // Siblings — other symbols in same file
+                const siblings = db.getSymbolsByFile(sym.filePath)
+                    .filter(s => s.id !== sym.id && !s.parentId)
+                    .slice(0, 10);
+                if (siblings.length > 0) {
+                    sections.push(`file peers: ${siblings.map(s => `${s.name} [${s.kind}]`).join(', ')}`);
+                }
+            }
+            else if (intent === 'edit') {
+                // Focused: who calls this + blast radius + test coverage
+                const incoming = db.getIncomingLinks(sym.id).filter(l => l.type !== 'contains');
+                const upstream = db.findUpstream(sym.id, 2);
+                if (incoming.length > 0) {
+                    sections.push(`direct callers (${incoming.length}):`);
+                    for (const l of incoming) {
+                        const from = db.findSymbolById(l.fromId);
+                        sections.push(`  ${l.type}: ${from ? fmtSymbol(from) : l.fromId}`);
+                    }
+                }
+                else {
+                    sections.push(`direct callers: none`);
+                }
+                if (upstream.length > incoming.length) {
+                    const depth2 = upstream.filter(u => u.depth === 2);
+                    if (depth2.length > 0) {
+                        sections.push(`indirect dependents (depth 2): ${depth2.length} symbols`);
+                    }
+                }
+                // Re-export detection
+                const reExportMatches = grepFiles(root, name, { maxResults: 5, includePattern: '**/index.{ts,js,mjs}' })
+                    .filter(m => /export\s*\{/.test(m.text) && m.text.includes('from'));
+                if (reExportMatches.length > 0) {
+                    sections.push(`re-exported via: ${reExportMatches.map(m => `${m.file}:${m.line}`).join(', ')}`);
+                }
+                // Test coverage
+                const testRefs = incoming.filter(l => {
+                    const from = db.findSymbolById(l.fromId);
+                    return from && isTestFilePath(from.filePath);
+                });
+                if (testRefs.length > 0) {
+                    sections.push(`✓ has test coverage`);
+                }
+                else if (sym.exported) {
+                    sections.push(`⚠ no test coverage`);
+                }
+            }
+            else if (intent === 'debug') {
+                // Execution paths + data flow
+                const traces = db.traceToEntrypoints(sym.id, 6);
+                if (traces.length > 0) {
+                    sections.push(`execution paths (${traces.length}):`);
+                    for (let i = 0; i < Math.min(traces.length, 3); i++) {
+                        const chain = traces[i].path;
+                        sections.push(`  ${chain.map(s => s.symbol.name).join(' → ')}`);
+                    }
+                }
+                else {
+                    sections.push(`no call chains found (may be entrypoint or unreachable)`);
+                }
+                // What does this call? (downstream immediate)
+                const outgoing = db.getOutgoingLinks(sym.id).filter(l => l.type === 'calls');
+                if (outgoing.length > 0) {
+                    sections.push(`calls (${outgoing.length}):`);
+                    for (const l of outgoing) {
+                        const to = db.findSymbolById(l.toId);
+                        sections.push(`  ${to ? fmtSymbol(to) : l.toId}`);
+                    }
+                }
+                // Data types used
+                const dataTypes = db.getOutgoingLinks(sym.id)
+                    .filter(l => l.type === 'imports')
+                    .map(l => db.findSymbolById(l.toId))
+                    .filter(s => s && (s.kind === 'interface' || s.kind === 'type' || s.kind === 'class'))
+                    .slice(0, 10);
+                if (dataTypes.length > 0) {
+                    sections.push(`data types: ${dataTypes.map(s => s.name).join(', ')}`);
+                }
+            }
+            else if (intent === 'test') {
+                // Test coverage + what to mock
+                const incoming = db.getIncomingLinks(sym.id).filter(l => l.type !== 'contains');
+                const testRefs = incoming.filter(l => {
+                    const from = db.findSymbolById(l.fromId);
+                    return from && isTestFilePath(from.filePath);
+                });
+                if (testRefs.length > 0) {
+                    const testFiles = [...new Set(testRefs.map(l => {
+                            const from = db.findSymbolById(l.fromId);
+                            return from?.filePath;
+                        }).filter(Boolean))];
+                    sections.push(`✓ tested from: ${testFiles.join(', ')}`);
+                }
+                else {
+                    sections.push(`⚠ no existing tests`);
+                }
+                // Dependencies to mock
+                const outgoing = db.getOutgoingLinks(sym.id).filter(l => l.type !== 'contains');
+                const externalDeps = outgoing.filter(l => {
+                    const to = db.findSymbolById(l.toId);
+                    return to && to.filePath !== sym.filePath;
+                });
+                if (externalDeps.length > 0) {
+                    sections.push(`dependencies to mock (${externalDeps.length}):`);
+                    for (const l of externalDeps) {
+                        const to = db.findSymbolById(l.toId);
+                        if (to)
+                            sections.push(`  ${l.type}: ${fmtSymbol(to)}`);
+                    }
+                }
+                // Inputs — what calls this? (test should cover these call patterns)
+                const nonTestCallers = incoming.filter(l => {
+                    const from = db.findSymbolById(l.fromId);
+                    return from && !isTestFilePath(from.filePath);
+                });
+                if (nonTestCallers.length > 0) {
+                    sections.push(`callers to cover (${nonTestCallers.length}):`);
+                    for (const l of nonTestCallers.slice(0, 5)) {
+                        const from = db.findSymbolById(l.fromId);
+                        if (from)
+                            sections.push(`  ${fmtSymbol(from)}`);
+                    }
+                }
+            }
+            sections.push('');
+        }
+        return { content: [{ type: 'text', text: sections.join('\n') }] };
+    });
+    // ══════════════════════════════════════════════
+    // ── MCP Resources ──
+    // ══════════════════════════════════════════════
+    // ── Resource: milens://symbol/{name} ──
+    server.resource('symbol', new ResourceTemplate('milens://symbol/{name}', { list: undefined }), { description: 'Symbol context: definition, incoming refs, outgoing deps, role/heat metadata' }, async (uri, { name }) => {
+        const { db } = getDb();
+        const symbols = db.findSymbolByName(name);
+        if (symbols.length === 0) {
+            return { contents: [{ uri: uri.href, mimeType: 'text/plain', text: `"${name}" not found.` }] };
+        }
+        const lines = [];
+        for (const sym of symbols) {
+            lines.push(`${fmtSymbol(sym, 'L2')}${sym.exported ? ' (exported)' : ''}`);
+            const incoming = db.getIncomingLinks(sym.id).filter(l => l.type !== 'contains');
+            if (incoming.length > 0) {
+                lines.push(`incoming (${incoming.length}):`);
+                for (const l of incoming) {
+                    const from = db.findSymbolById(l.fromId);
+                    lines.push(`  ${l.type}: ${from ? fmtSymbol(from) : l.fromId}`);
+                }
+            }
+            const outgoing = db.getOutgoingLinks(sym.id).filter(l => l.type !== 'contains');
+            if (outgoing.length > 0) {
+                lines.push(`outgoing (${outgoing.length}):`);
+                for (const l of outgoing) {
+                    const to = db.findSymbolById(l.toId);
+                    lines.push(`  ${l.type}: ${to ? fmtSymbol(to) : l.toId}`);
+                }
+            }
+            lines.push('');
+        }
+        return { contents: [{ uri: uri.href, mimeType: 'text/plain', text: lines.join('\n') }] };
+    });
+    // ── Resource: milens://file/{path} ──
+    server.resource('file-symbols', new ResourceTemplate('milens://file/{+path}', { list: undefined }), { description: 'All symbols in a file with ref/dep counts' }, async (uri, { path }) => {
+        const { db } = getDb();
+        const filePath = decodeURIComponent(path);
+        const symbols = db.getSymbolsByFile(filePath);
+        if (symbols.length === 0) {
+            return { contents: [{ uri: uri.href, mimeType: 'text/plain', text: `No symbols in "${filePath}".` }] };
+        }
+        const lines = [`${filePath}: ${symbols.length} symbols\n`];
+        for (const sym of symbols) {
+            const incoming = db.getIncomingLinks(sym.id).filter(l => l.type !== 'contains');
+            const outgoing = db.getOutgoingLinks(sym.id).filter(l => l.type !== 'contains');
+            const exp = sym.exported ? ' (exported)' : '';
+            lines.push(`${fmtSymbol(sym, 'L2')}${exp} ← ${incoming.length} refs, → ${outgoing.length} deps`);
+        }
+        return { contents: [{ uri: uri.href, mimeType: 'text/plain', text: lines.join('\n') }] };
+    });
+    // ── Resource: milens://domain/{name} ──
+    server.resource('domain', new ResourceTemplate('milens://domain/{name}', { list: undefined }), { description: 'Domain cluster details: files and top symbols in a domain' }, async (uri, { name }) => {
+        const { db } = getDb();
+        const domainName = name;
+        // Find files in this domain
+        const allFiles = db.db_getFilesByZone(domainName);
+        if (allFiles.length === 0) {
+            return { contents: [{ uri: uri.href, mimeType: 'text/plain', text: `Domain "${domainName}" not found.` }] };
+        }
+        const lines = [`domain: ${domainName} (${allFiles.length} files)\n`];
+        let totalSymbols = 0;
+        for (const file of allFiles) {
+            const syms = db.getSymbolsByFile(file);
+            totalSymbols += syms.length;
+            const exported = syms.filter(s => s.exported);
+            lines.push(`${file}: ${syms.length} symbols (${exported.length} exported)`);
+        }
+        lines.push(`\ntotal: ${totalSymbols} symbols in ${allFiles.length} files`);
+        return { contents: [{ uri: uri.href, mimeType: 'text/plain', text: lines.join('\n') }] };
+    });
+    // ── Resource: milens://overview ──
+    server.resource('overview', 'milens://overview', { description: 'Index overview: stats, domains, unresolved, test coverage, staleness' }, async (uri) => {
+        const { db, root } = getDb();
+        const stats = db.getStats();
+        const unresolved = db.getUnresolvedStats();
+        const coverage = db.getTestCoverage();
+        const domains = db.getDomainStats();
+        const staleFiles = db.getStaleFiles(24);
+        const lines = [
+            `repo: ${root}`,
+            `symbols: ${stats.symbols}`,
+            `links: ${stats.links}`,
+            `files: ${stats.files}`,
+        ];
+        if (unresolved.imports > 0 || unresolved.calls > 0) {
+            lines.push(`⚠ unresolved (internal): ${unresolved.imports} imports, ${unresolved.calls} calls`);
+        }
+        if (unresolved.externalImports > 0 || unresolved.externalCalls > 0) {
+            lines.push(`external (expected): ${unresolved.externalImports} imports, ${unresolved.externalCalls} calls`);
+        }
+        if (coverage.testFiles > 0) {
+            const pct = coverage.exportedProductionSymbols > 0
+                ? Math.round(coverage.testedSymbols / coverage.exportedProductionSymbols * 100) : 0;
+            lines.push(`test coverage: ${coverage.testedSymbols}/${coverage.exportedProductionSymbols} (${pct}%) from ${coverage.testFiles} test files`);
+        }
+        if (domains.length > 0) {
+            lines.push(`\ndomains (${domains.length}):`);
+            for (const d of domains) {
+                lines.push(`  ${d.domain}: ${d.files} files, ${d.symbols} symbols`);
+            }
+        }
+        if (staleFiles.length > 0) {
+            lines.push(`\n⏳ ${staleFiles.length} stale files (>24h)`);
+        }
+        return { contents: [{ uri: uri.href, mimeType: 'text/plain', text: lines.join('\n') }] };
+    });
     // ── Prompt: delete-feature ──
     server.prompt('delete-feature', 'Step-by-step workflow for safely deleting a feature from the codebase', { name: z.string().describe('Feature or symbol name to delete') }, ({ name }) => ({
         messages: [{