sigmap 7.2.1 → 7.4.0

package/gen-context.js

@@ -20,6 +20,122 @@ function __require(key) {
 }
 
 
+// ── ./src/extractors/dispatch ──
+__factories["./src/extractors/dispatch"] = function(module, exports) {
+  
+  /**
+   * Bundle-safe extractor dispatch.
+   *
+   * `packages/core`'s extract() resolves extractors via dynamic `require(path.join(…))`,
+   * which cannot run inside the standalone bundle (no filesystem `src/`). This module
+   * uses STATIC requires so the bundler rewrites them to `__require` and the extractors
+   * resolve from the bundled factories. Used by the live-index MCP write hooks.
+   */
+
+  const path = require('path');
+
+  // Static language → extractor map (every entry is a bundled factory).
+  const EXTRACTORS = {
+    typescript: __require('./src/extractors/typescript'),
+    typescript_react: __require('./src/extractors/typescript_react'),
+    javascript: __require('./src/extractors/javascript'),
+    python: __require('./src/extractors/python'),
+    java: __require('./src/extractors/java'),
+    kotlin: __require('./src/extractors/kotlin'),
+    go: __require('./src/extractors/go'),
+    rust: __require('./src/extractors/rust'),
+    csharp: __require('./src/extractors/csharp'),
+    cpp: __require('./src/extractors/cpp'),
+    ruby: __require('./src/extractors/ruby'),
+    php: __require('./src/extractors/php'),
+    swift: __require('./src/extractors/swift'),
+    dart: __require('./src/extractors/dart'),
+    scala: __require('./src/extractors/scala'),
+    gdscript: __require('./src/extractors/gdscript'),
+    r: __require('./src/extractors/r'),
+    vue: __require('./src/extractors/vue'),
+    vue_sfc: __require('./src/extractors/vue_sfc'),
+    svelte: __require('./src/extractors/svelte'),
+    html: __require('./src/extractors/html'),
+    css: __require('./src/extractors/css'),
+    yaml: __require('./src/extractors/yaml'),
+    shell: __require('./src/extractors/shell'),
+    sql: __require('./src/extractors/sql'),
+    graphql: __require('./src/extractors/graphql'),
+    terraform: __require('./src/extractors/terraform'),
+    protobuf: __require('./src/extractors/protobuf'),
+    toml: __require('./src/extractors/toml'),
+    properties: __require('./src/extractors/properties'),
+    xml: __require('./src/extractors/xml'),
+    markdown: __require('./src/extractors/markdown'),
+    dockerfile: __require('./src/extractors/dockerfile'),
+    generic: __require('./src/extractors/generic'),
+  };
+
+  const EXT_MAP = {
+    '.ts': 'typescript', '.tsx': 'typescript_react',
+    '.js': 'javascript', '.jsx': 'javascript', '.mjs': 'javascript', '.cjs': 'javascript',
+    '.py': 'python', '.pyw': 'python',
+    '.java': 'java',
+    '.kt': 'kotlin', '.kts': 'kotlin',
+    '.go': 'go',
+    '.rs': 'rust',
+    '.cs': 'csharp',
+    '.cpp': 'cpp', '.c': 'cpp', '.h': 'cpp', '.hpp': 'cpp', '.cc': 'cpp',
+    '.rb': 'ruby', '.rake': 'ruby',
+    '.php': 'php',
+    '.swift': 'swift',
+    '.dart': 'dart',
+    '.scala': 'scala', '.sc': 'scala',
+    '.gd': 'gdscript',
+    '.r': 'r', '.R': 'r',
+    '.vue': 'vue_sfc',
+    '.svelte': 'svelte',
+    '.html': 'html', '.htm': 'html',
+    '.css': 'css', '.scss': 'css', '.sass': 'css', '.less': 'css',
+    '.yml': 'yaml', '.yaml': 'yaml',
+    '.sh': 'shell', '.bash': 'shell', '.zsh': 'shell', '.fish': 'shell',
+    '.sql': 'sql',
+    '.graphql': 'graphql', '.gql': 'graphql',
+    '.tf': 'terraform', '.tfvars': 'terraform',
+    '.proto': 'protobuf',
+    '.toml': 'toml',
+    '.properties': 'properties',
+    '.xml': 'xml',
+    '.md': 'markdown',
+  };
+
+  /** Resolve a language key from a file path/name. */
+  function langFor(filePathOrName) {
+    const base = path.basename(String(filePathOrName || ''));
+    if (base === 'Dockerfile' || base.startsWith('Dockerfile.')) return 'dockerfile';
+    const ext = path.extname(base).toLowerCase();
+    return EXT_MAP[ext] || null;
+  }
+
+  /**
+   * Extract signatures from a file's content using the right extractor.
+   * @param {string} filePathOrName - path or name (extension drives the extractor)
+   * @param {string} src - file content
+   * @returns {string[]}
+   */
+  function extractFile(filePathOrName, src) {
+    if (!src || typeof src !== 'string') return [];
+    const lang = langFor(filePathOrName);
+    const mod = lang ? EXTRACTORS[lang] : null;
+    if (!mod || typeof mod.extract !== 'function') return [];
+    try {
+      const out = mod.extract(src);
+      return Array.isArray(out) ? out : [];
+    } catch (_) {
+      return [];
+    }
+  }
+
+  module.exports = { extractFile, langFor };
+  
+};
+
 // ── ./src/config/defaults ──
 __factories["./src/config/defaults"] = function(module, exports) {
   
@@ -5528,552 +5644,681 @@ __factories["./src/graph/impact"] = function(module, exports) {
 
 // ── ./src/mcp/handlers ──
 __factories["./src/mcp/handlers"] = function(module, exports) {
-'use strict';
-
-const fs   = require('fs');
-const path = require('path');
-
-const CONTEXT_FILE = path.join('.github', 'copilot-instructions.md');
-const CONTEXT_COLD_FILE = path.join('.github', 'context-cold.md');
-
-function _readContextFiles(cwd) {
-  const paths = [path.join(cwd, CONTEXT_FILE), path.join(cwd, CONTEXT_COLD_FILE)];
-  const chunks = [];
-  for (const p of paths) {
-    if (fs.existsSync(p)) chunks.push(fs.readFileSync(p, 'utf8'));
-  }
-  return chunks.join('\n');
-}
-
-// Section header keywords in PROJECT_MAP.md
-const MAP_SECTIONS = {
-  imports: '### Import graph',
-  classes: '### Class hierarchy',
-  routes: '### Route table',
-};
-
-/**
- * read_context({ module? }) → string
- *
- * Returns the full context file, or just the sections whose file paths
- * contain the given module substring.
- */
-function readContext(args, cwd) {
-  const content = _readContextFiles(cwd);
-  if (!content) {
-    return 'No context file found. Run: node gen-context.js';
-  }
-
-  if (!args || !args.module) return content;
+  
+  const fs   = require('fs');
+  const path = require('path');
+  const { git } = __require('./src/util/git');
 
-  const mod = args.module.replace(/\\/g, '/').replace(/\/$/, '');
-  const lines = content.split('\n');
-  const result = [];
-  let capturing = false;
+  const CONTEXT_FILE = path.join('.github', 'copilot-instructions.md');
+  const CONTEXT_COLD_FILE = path.join('.github', 'context-cold.md');
 
-  for (const line of lines) {
-    if (line.startsWith('### ')) {
-      const filePath = line.slice(4).trim().replace(/\\/g, '/');
-      // Match if file path starts with mod or contains /mod/ or /mod
-      capturing =
-        filePath === mod ||
-        filePath.startsWith(mod + '/') ||
-        filePath.includes('/' + mod + '/') ||
-        filePath.includes('/' + mod);
-      if (capturing) result.push(line);
-      continue;
+  function _readContextFiles(cwd) {
+    const paths = [path.join(cwd, CONTEXT_FILE), path.join(cwd, CONTEXT_COLD_FILE)];
+    const chunks = [];
+    for (const p of paths) {
+      if (fs.existsSync(p)) chunks.push(fs.readFileSync(p, 'utf8'));
     }
-    if (capturing) result.push(line);
+    return chunks.join('\n');
   }
 
-  if (result.length === 0) return `No signatures found for module: ${mod}`;
-  return result.join('\n');
-}
-
-/**
- * search_signatures({ query }) → string
- *
- * Case-insensitive search through all signature lines.
- * Returns matching lines grouped by file path.
- */
-function searchSignatures(args, cwd) {
-  if (!args || !args.query) return 'Missing required argument: query';
+  // Section header keywords in PROJECT_MAP.md
+  const MAP_SECTIONS = {
+    imports: '### Import graph',
+    classes: '### Class hierarchy',
+    routes: '### Route table',
+  };
 
-  const query = args.query.toLowerCase();
-  try {
-    const { buildSigIndex } = __require('./src/retrieval/ranker');
-    const index = buildSigIndex(cwd);
-    if (index.size === 0) {
+  /**
+   * read_context({ module? }) → string
+   *
+   * Returns the full context file, or just the sections whose file paths
+   * contain the given module substring.
+   */
+  function readContext(args, cwd) {
+    const content = _readContextFiles(cwd);
+    if (!content) {
       return 'No context file found. Run: node gen-context.js';
     }
 
+    if (!args || !args.module) return content;
+
+    const mod = args.module.replace(/\\/g, '/').replace(/\/$/, '');
+    const lines = content.split('\n');
     const result = [];
-    for (const [file, sigs] of index.entries()) {
-      const hits = sigs.filter((s) => s.toLowerCase().includes(query));
-      if (hits.length === 0) continue;
-      if (result.length > 0) result.push('');
-      result.push(`### ${file}`);
-      result.push(...hits);
+    let capturing = false;
+
+    for (const line of lines) {
+      if (line.startsWith('### ')) {
+        const filePath = line.slice(4).trim().replace(/\\/g, '/');
+        // Match if file path starts with mod or contains /mod/ or /mod
+        capturing =
+          filePath === mod ||
+          filePath.startsWith(mod + '/') ||
+          filePath.includes('/' + mod + '/') ||
+          filePath.includes('/' + mod);
+        if (capturing) result.push(line);
+        continue;
+      }
+      if (capturing) result.push(line);
     }
 
-    if (result.length === 0) return `No signatures found matching: ${args.query}`;
+    if (result.length === 0) return `No signatures found for module: ${mod}`;
     return result.join('\n');
-  } catch (err) {
-    return `_search_signatures failed: ${err.message}_`;
   }
-}
 
-/**
- * get_map({ type }) → string
- *
- * Returns a section from PROJECT_MAP.md.
- * type: 'imports' | 'classes' | 'routes'
- */
-function getMap(args, cwd) {
-  if (!args || !args.type) return 'Missing required argument: type';
+  /**
+   * search_signatures({ query }) → string
+   *
+   * Case-insensitive search through all signature lines.
+   * Returns matching lines grouped by file path.
+   */
+  function searchSignatures(args, cwd) {
+    if (!args || !args.query) return 'Missing required argument: query';
 
-  const header = MAP_SECTIONS[args.type];
-  if (!header) {
-    return `Unknown map type: "${args.type}". Use: imports, classes, routes`;
-  }
+    const query = args.query.toLowerCase();
+    try {
+      const { buildSigIndex } = __require('./src/retrieval/ranker');
+      const index = buildSigIndex(cwd);
+      if (index.size === 0) {
+        return 'No context file found. Run: node gen-context.js';
+      }
 
-  const mapPath = path.join(cwd, 'PROJECT_MAP.md');
-  if (!fs.existsSync(mapPath)) {
-    return 'PROJECT_MAP.md not found. Run: node gen-project-map.js';
-  }
+      const result = [];
+      for (const [file, sigs] of index.entries()) {
+        const hits = sigs.filter((s) => s.toLowerCase().includes(query));
+        if (hits.length === 0) continue;
+        if (result.length > 0) result.push('');
+        result.push(`### ${file}`);
+        result.push(...hits);
+      }
 
-  const content = fs.readFileSync(mapPath, 'utf8');
-  const idx = content.indexOf(header);
-  if (idx === -1) {
-    return `Section "${header}" not found in PROJECT_MAP.md`;
+      if (result.length === 0) return `No signatures found matching: ${args.query}`;
+      return result.join('\n');
+    } catch (err) {
+      return `_search_signatures failed: ${err.message}_`;
+    }
   }
 
-  // Extract from this header to the next ### header
-  const after = content.slice(idx);
-  const nextMatch = after.slice(header.length).search(/\n###\s/);
-  return nextMatch === -1 ? after : after.slice(0, header.length + nextMatch);
-}
+  /**
+   * get_map({ type }) → string
+   *
+   * Returns a section from PROJECT_MAP.md.
+   * type: 'imports' | 'classes' | 'routes'
+   */
+  function getMap(args, cwd) {
+    if (!args || !args.type) return 'Missing required argument: type';
 
-/**
- * create_checkpoint({ note? }) → string
- *
- * Returns a markdown checkpoint summarising current project state:
- * - Timestamp and optional user note
- * - Active git branch + last 5 commit messages
- * - Token count of current context file
- * - List of modules present in the context
- * - Route count (if PROJECT_MAP.md exists)
- */
-function createCheckpoint(args, cwd) {
-  const note = (args && args.note) ? args.note.trim() : '';
-  const now = new Date().toISOString().replace('T', ' ').slice(0, 19) + ' UTC';
-  const lines = [
-    '# SigMap Checkpoint',
-    `**Created:** ${now}`,
-  ];
+    const header = MAP_SECTIONS[args.type];
+    if (!header) {
+      return `Unknown map type: "${args.type}". Use: imports, classes, routes`;
+    }
 
-  if (note) lines.push(`**Note:** ${note}`);
-  lines.push('');
+    const mapPath = path.join(cwd, 'PROJECT_MAP.md');
+    if (!fs.existsSync(mapPath)) {
+      return 'PROJECT_MAP.md not found. Run: node gen-project-map.js';
+    }
 
-  // ── Git info ────────────────────────────────────────────────────────────
-  lines.push('## Git state');
-  try {
-    const branch = __git(['rev-parse', '--abbrev-ref', 'HEAD'], { cwd }).trim();
-    lines.push(`**Branch:** ${branch}`);
-  } catch (_) {
-    lines.push('**Branch:** (not a git repo)');
+    const content = fs.readFileSync(mapPath, 'utf8');
+    const idx = content.indexOf(header);
+    if (idx === -1) {
+      return `Section "${header}" not found in PROJECT_MAP.md`;
+    }
+
+    // Extract from this header to the next ### header
+    const after = content.slice(idx);
+    const nextMatch = after.slice(header.length).search(/\n###\s/);
+    return nextMatch === -1 ? after : after.slice(0, header.length + nextMatch);
   }
 
-  try {
-    const log = __git(['log', '--oneline', '-5', '--no-decorate'], { cwd }).trim();
-    if (log) {
-      lines.push('');
-      lines.push('**Recent commits:**');
-      for (const l of log.split('\n')) lines.push(`- ${l}`);
+  /**
+   * create_checkpoint({ note? }) → string
+   *
+   * Returns a markdown checkpoint summarising current project state:
+   * - Timestamp and optional user note
+   * - Active git branch + last 5 commit messages
+   * - Token count of current context file
+   * - List of modules present in the context
+   * - Route count (if PROJECT_MAP.md exists)
+   */
+  function createCheckpoint(args, cwd) {
+    const note = (args && args.note) ? args.note.trim() : '';
+    const now = new Date().toISOString().replace('T', ' ').slice(0, 19) + ' UTC';
+    const lines = [
+      '# SigMap Checkpoint',
+      `**Created:** ${now}`,
+    ];
+
+    if (note) lines.push(`**Note:** ${note}`);
+    lines.push('');
+
+    // ── Git info ────────────────────────────────────────────────────────────
+    lines.push('## Git state');
+    try {
+      const branch = git(['rev-parse', '--abbrev-ref', 'HEAD'], { cwd }).trim();
+      lines.push(`**Branch:** ${branch}`);
+    } catch (_) {
+      lines.push('**Branch:** (not a git repo)');
     }
-  } catch (_) {} // ignore — not every project uses git
-  lines.push('');
 
-  // ── Context stats ────────────────────────────────────────────────────────
-  lines.push('## Context snapshot');
-  const contextPath = path.join(cwd, CONTEXT_FILE);
-  if (fs.existsSync(contextPath)) {
-    const content = fs.readFileSync(contextPath, 'utf8');
-    const tokens = Math.ceil(content.length / 4);
+    try {
+      const log = git(['log', '--oneline', '-5', '--no-decorate'], { cwd }).trim();
+      if (log) {
+        lines.push('');
+        lines.push('**Recent commits:**');
+        for (const l of log.split('\n')) lines.push(`- ${l}`);
+      }
+    } catch (_) {} // ignore — not every project uses git
+    lines.push('');
 
-    // Count modules (### headers are file paths)
-    const modules = content.split('\n').filter((l) => l.startsWith('### ')).map((l) => l.slice(4).trim());
-    lines.push(`**Token count:** ~${tokens}`);
-    lines.push(`**Modules in context:** ${modules.length}`);
+    // ── Context stats ────────────────────────────────────────────────────────
+    lines.push('## Context snapshot');
+    const contextPath = path.join(cwd, CONTEXT_FILE);
+    if (fs.existsSync(contextPath)) {
+      const content = fs.readFileSync(contextPath, 'utf8');
+      const tokens = Math.ceil(content.length / 4);
 
-    if (modules.length > 0) {
-      lines.push('');
-      lines.push('**Modules:**');
-      for (const m of modules.slice(0, 20)) lines.push(`- ${m}`);
-      if (modules.length > 20) lines.push(`- … and ${modules.length - 20} more`);
-    }
-  } else {
-    lines.push('_No context file found. Run: node gen-context.js_');
-  }
-  lines.push('');
-
-  // ── Route summary ────────────────────────────────────────────────────────
-  const mapPath = path.join(cwd, 'PROJECT_MAP.md');
-  if (fs.existsSync(mapPath)) {
-    const mapContent = fs.readFileSync(mapPath, 'utf8');
-    const routeLines = mapContent.split('\n').filter((l) => l.startsWith('| ') && !l.startsWith('| Method') && !l.startsWith('|---'));
-    if (routeLines.length > 0) {
-      lines.push('## Routes');
-      lines.push(`**Total routes detected:** ${routeLines.length}`);
-      lines.push('');
-      for (const r of routeLines.slice(0, 10)) lines.push(r);
-      if (routeLines.length > 10) lines.push(`| … | +${routeLines.length - 10} more | |`);
-      lines.push('');
+      // Count modules (### headers are file paths)
+      const modules = content.split('\n').filter((l) => l.startsWith('### ')).map((l) => l.slice(4).trim());
+      lines.push(`**Token count:** ~${tokens}`);
+      lines.push(`**Modules in context:** ${modules.length}`);
+
+      if (modules.length > 0) {
+        lines.push('');
+        lines.push('**Modules:**');
+        for (const m of modules.slice(0, 20)) lines.push(`- ${m}`);
+        if (modules.length > 20) lines.push(`- … and ${modules.length - 20} more`);
+      }
+    } else {
+      lines.push('_No context file found. Run: node gen-context.js_');
     }
-  }
+    lines.push('');
 
-  lines.push('---');
-  lines.push('_Generated by SigMap `create_checkpoint`_');
+    // ── Route summary ────────────────────────────────────────────────────────
+    const mapPath = path.join(cwd, 'PROJECT_MAP.md');
+    if (fs.existsSync(mapPath)) {
+      const mapContent = fs.readFileSync(mapPath, 'utf8');
+      const routeLines = mapContent.split('\n').filter((l) => l.startsWith('| ') && !l.startsWith('| Method') && !l.startsWith('|---'));
+      if (routeLines.length > 0) {
+        lines.push('## Routes');
+        lines.push(`**Total routes detected:** ${routeLines.length}`);
+        lines.push('');
+        for (const r of routeLines.slice(0, 10)) lines.push(r);
+        if (routeLines.length > 10) lines.push(`| … | +${routeLines.length - 10} more | |`);
+        lines.push('');
+      }
+    }
 
-  return lines.join('\n');
-}
+    lines.push('---');
+    lines.push('_Generated by SigMap `create_checkpoint`_');
 
-/**
- * get_routing({}) → string
- *
- * Reads the current context file, classifies all indexed files by complexity,
- * and returns a formatted markdown routing guide showing which files belong
- * to the fast/balanced/powerful model tier.
- */
-function getRouting(args, cwd) {
-  const contextPath = path.join(cwd, CONTEXT_FILE);
-  if (!fs.existsSync(contextPath)) {
-    return (
-      '_No context file found. Run `node gen-context.js --routing` first._\n\n' +
-      'This generates routing hints that map each file to a model tier:\n' +
-      '- **fast** (haiku/gpt-4o-mini) — config, markup, trivial utilities\n' +
-      '- **balanced** (sonnet/gpt-4o) — standard application code\n' +
-      '- **powerful** (opus/gpt-4-turbo) — complex, security-critical, or large modules'
-    );
+    return lines.join('\n');
   }
 
-  // Parse file list from context (### headings are file paths)
-  const content = fs.readFileSync(contextPath, 'utf8');
-  const fileRels = content.split('\n')
-    .filter((l) => l.startsWith('### '))
-    .map((l) => l.slice(4).trim());
+  /**
+   * get_routing({}) → string
+   *
+   * Reads the current context file, classifies all indexed files by complexity,
+   * and returns a formatted markdown routing guide showing which files belong
+   * to the fast/balanced/powerful model tier.
+   */
+  function getRouting(args, cwd) {
+    const contextPath = path.join(cwd, CONTEXT_FILE);
+    if (!fs.existsSync(contextPath)) {
+      return (
+        '_No context file found. Run `node gen-context.js --routing` first._\n\n' +
+        'This generates routing hints that map each file to a model tier:\n' +
+        '- **fast** (haiku/gpt-4o-mini) — config, markup, trivial utilities\n' +
+        '- **balanced** (sonnet/gpt-4o) — standard application code\n' +
+        '- **powerful** (opus/gpt-4-turbo) — complex, security-critical, or large modules'
+      );
+    }
 
-  // Build synthetic fileEntries for the classifier
-  // We don't have live sig arrays here, so rebuild from the context blocks
-  const entries = [];
-  const blocks = content.split(/^### /m).slice(1); // slice past the header
-  for (const block of blocks) {
-    const firstLine = block.split('\n')[0].trim();
-    const codeBlock = block.match(/```\n([\s\S]*?)```/);
-    const sigs = codeBlock ? codeBlock[1].trim().split('\n').filter(Boolean) : [];
-    entries.push({ filePath: path.join(cwd, firstLine), sigs });
-  }
+    // Parse file list from context (### headings are file paths)
+    const content = fs.readFileSync(contextPath, 'utf8');
+    const fileRels = content.split('\n')
+      .filter((l) => l.startsWith('### '))
+      .map((l) => l.slice(4).trim());
 
-  try {
-    const { classifyAll } = __require('./src/routing/classifier');
-    const { formatRoutingSection } = __require('./src/routing/hints');
-    const groups = classifyAll(entries, cwd);
-    return formatRoutingSection(groups);
-  } catch (err) {
-    return `_Routing classification failed: ${err.message}_`;
+    // Build synthetic fileEntries for the classifier
+    // We don't have live sig arrays here, so rebuild from the context blocks
+    const entries = [];
+    const blocks = content.split(/^### /m).slice(1); // slice past the header
+    for (const block of blocks) {
+      const firstLine = block.split('\n')[0].trim();
+      const codeBlock = block.match(/```\n([\s\S]*?)```/);
+      const sigs = codeBlock ? codeBlock[1].trim().split('\n').filter(Boolean) : [];
+      entries.push({ filePath: path.join(cwd, firstLine), sigs });
+    }
+
+    try {
+      const { classifyAll } = __require('./src/routing/classifier');
+      const { formatRoutingSection } = __require('./src/routing/hints');
+      const groups = classifyAll(entries, cwd);
+      return formatRoutingSection(groups);
+    } catch (err) {
+      return `_Routing classification failed: ${err.message}_`;
+    }
   }
-}
 
-/**
- * explain_file({ path }) → string
- *
- * Returns a file's signatures, its direct imports, and files that import it.
- * path: relative path from project root (e.g. 'src/services/auth.ts')
- */
-function explainFile(args, cwd) {
-  if (!args || !args.path) return 'Missing required argument: path';
+  /**
+   * explain_file({ path }) → string
+   *
+   * Returns a file's signatures, its direct imports, and files that import it.
+   * path: relative path from project root (e.g. 'src/services/auth.ts')
+   */
+  function explainFile(args, cwd) {
+    if (!args || !args.path) return 'Missing required argument: path';
 
-  const targetRel = args.path.replace(/\\/g, '/').replace(/^\//, '');
-  const targetAbs = path.resolve(cwd, targetRel);
-  const contextPath = path.join(cwd, CONTEXT_FILE);
+    const targetRel = args.path.replace(/\\/g, '/').replace(/^\//, '');
+    const targetAbs = path.resolve(cwd, targetRel);
+    const contextPath = path.join(cwd, CONTEXT_FILE);
 
-  const lines = ['# explain_file: ' + targetRel, ''];
+    const lines = ['# explain_file: ' + targetRel, ''];
 
-  // ── Signatures (hot + cold + cache via buildSigIndex) ───────────────────
-  lines.push('## Signatures');
-  let indexedFiles = [];
+    // ── Signatures (hot + cold + cache via buildSigIndex) ───────────────────
+    lines.push('## Signatures');
+    let indexedFiles = [];
 
-  try {
-    const { buildSigIndex } = __require('./src/retrieval/ranker');
-    const index = buildSigIndex(cwd);
-    let sigs = index.get(targetRel);
-    if (!sigs) {
-      for (const [file, fileSigs] of index.entries()) {
-        if (file === targetRel || file.endsWith('/' + targetRel) || targetRel.endsWith('/' + file)) {
-          sigs = fileSigs;
-          break;
+    try {
+      const { buildSigIndex } = __require('./src/retrieval/ranker');
+      const index = buildSigIndex(cwd);
+      let sigs = index.get(targetRel);
+      if (!sigs) {
+        for (const [file, fileSigs] of index.entries()) {
+          if (file === targetRel || file.endsWith('/' + targetRel) || targetRel.endsWith('/' + file)) {
+            sigs = fileSigs;
+            break;
+          }
         }
       }
+      if (sigs && sigs.length > 0) {
+        lines.push(...sigs);
+      } else {
+        lines.push('_No signatures indexed for this file. Run: node gen-context.js_');
+      }
+      indexedFiles = [...index.keys()].map((rel) => path.resolve(cwd, rel));
+    } catch (_) {
+      lines.push('_No context file found. Run: node gen-context.js_');
     }
-    if (sigs && sigs.length > 0) {
-      lines.push(...sigs);
-    } else {
-      lines.push('_No signatures indexed for this file. Run: node gen-context.js_');
+
+    if (!fs.existsSync(targetAbs)) {
+      lines.push('');
+      lines.push('> File not found on disk: ' + targetRel);
+      return lines.join('\n');
     }
-    indexedFiles = [...index.keys()].map((rel) => path.resolve(cwd, rel));
-  } catch (_) {
-    lines.push('_No context file found. Run: node gen-context.js_');
-  }
 
-  if (!fs.existsSync(targetAbs)) {
     lines.push('');
-    lines.push('> File not found on disk: ' + targetRel);
-    return lines.join('\n');
-  }
 
-  lines.push('');
-
-  // ── Direct imports ────────────────────────────────────────────────────────
-  lines.push('## Imports (direct dependencies)');
-  try {
-    const { extractImports } = __require('./src/map/import-graph');
-    const fileContent = fs.readFileSync(targetAbs, 'utf8');
-    const fileSet = new Set(indexedFiles);
-    fileSet.add(targetAbs);
-    const imports = extractImports(targetAbs, fileContent, fileSet);
-    if (imports.length > 0) {
-      for (const imp of imports) lines.push('- ' + path.relative(cwd, imp).replace(/\\/g, '/'));
-    } else {
-      lines.push('_No resolvable relative imports found._');
+    // ── Direct imports ────────────────────────────────────────────────────────
+    lines.push('## Imports (direct dependencies)');
+    try {
+      const { extractImports } = __require('./src/map/import-graph');
+      const fileContent = fs.readFileSync(targetAbs, 'utf8');
+      const fileSet = new Set(indexedFiles);
+      fileSet.add(targetAbs);
+      const imports = extractImports(targetAbs, fileContent, fileSet);
+      if (imports.length > 0) {
+        for (const imp of imports) lines.push('- ' + path.relative(cwd, imp).replace(/\\/g, '/'));
+      } else {
+        lines.push('_No resolvable relative imports found._');
+      }
+    } catch (err) {
+      lines.push('_Could not analyze imports: ' + err.message + '_');
     }
-  } catch (err) {
-    lines.push('_Could not analyze imports: ' + err.message + '_');
-  }
 
-  lines.push('');
+    lines.push('');
 
-  // ── Callers (reverse-import lookup) ──────────────────────────────────────
-  lines.push('## Callers (files that import this file)');
-  try {
-    const { extractImports } = __require('./src/map/import-graph');
-    const fileSet = new Set(indexedFiles);
-    fileSet.add(targetAbs);
-    const callers = [];
-    for (const f of indexedFiles) {
-      if (f === targetAbs || !fs.existsSync(f)) continue;
-      try {
-        const fc = fs.readFileSync(f, 'utf8');
-        const imps = extractImports(f, fc, fileSet);
-        if (imps.includes(targetAbs)) callers.push(path.relative(cwd, f).replace(/\\/g, '/'));
-      } catch (_) {}
-    }
-    if (callers.length > 0) {
-      for (const c of callers) lines.push('- ' + c);
-    } else {
-      lines.push('_No indexed files import this file._');
+    // ── Callers (reverse-import lookup) ──────────────────────────────────────
+    lines.push('## Callers (files that import this file)');
+    try {
+      const { extractImports } = __require('./src/map/import-graph');
+      const fileSet = new Set(indexedFiles);
+      fileSet.add(targetAbs);
+      const callers = [];
+      for (const f of indexedFiles) {
+        if (f === targetAbs || !fs.existsSync(f)) continue;
+        try {
+          const fc = fs.readFileSync(f, 'utf8');
+          const imps = extractImports(f, fc, fileSet);
+          if (imps.includes(targetAbs)) callers.push(path.relative(cwd, f).replace(/\\/g, '/'));
+        } catch (_) {}
+      }
+      if (callers.length > 0) {
+        for (const c of callers) lines.push('- ' + c);
+      } else {
+        lines.push('_No indexed files import this file._');
+      }
+    } catch (err) {
+      lines.push('_Could not analyze callers: ' + err.message + '_');
     }
-  } catch (err) {
-    lines.push('_Could not analyze callers: ' + err.message + '_');
-  }
 
-  return lines.join('\n');
-}
+    return lines.join('\n');
+  }
 
-/**
- * list_modules({}) → string
- *
- * Lists all srcDir modules present in the context file, sorted by token count
- * descending. Helps agents decide which module to query with read_context.
- */
-function listModules(args, cwd) {
-  try {
-    const { buildSigIndex } = __require('./src/retrieval/ranker');
-    const index = buildSigIndex(cwd);
-    if (index.size === 0) {
-      return 'No context file found. Run: node gen-context.js';
-    }
+  /**
+   * list_modules({}) → string
+   *
+   * Lists all srcDir modules present in the context file, sorted by token count
+   * descending. Helps agents decide which module to query with read_context.
+   */
+  function listModules(args, cwd) {
+    try {
+      const { buildSigIndex } = __require('./src/retrieval/ranker');
+      const index = buildSigIndex(cwd);
+      if (index.size === 0) {
+        return 'No context file found. Run: node gen-context.js';
+      }
 
-    const groups = {};
-    for (const [rel, sigs] of index.entries()) {
-      const parts = rel.replace(/\\/g, '/').split('/');
-      const mod = parts.length > 1 ? parts[0] : '.';
-      if (!groups[mod]) groups[mod] = { fileCount: 0, tokenCount: 0 };
-      groups[mod].fileCount++;
-      groups[mod].tokenCount += Math.ceil(sigs.join('\n').length / 4);
-    }
+      const groups = {};
+      for (const [rel, sigs] of index.entries()) {
+        const parts = rel.replace(/\\/g, '/').split('/');
+        const mod = parts.length > 1 ? parts[0] : '.';
+        if (!groups[mod]) groups[mod] = { fileCount: 0, tokenCount: 0 };
+        groups[mod].fileCount++;
+        groups[mod].tokenCount += Math.ceil(sigs.join('\n').length / 4);
+      }
 
-  const sorted = Object.entries(groups)
-    .map(([mod, data]) => ({ module: mod, fileCount: data.fileCount, tokenCount: data.tokenCount }))
-    .sort((a, b) => b.tokenCount - a.tokenCount);
+    const sorted = Object.entries(groups)
+      .map(([mod, data]) => ({ module: mod, fileCount: data.fileCount, tokenCount: data.tokenCount }))
+      .sort((a, b) => b.tokenCount - a.tokenCount);
 
-  if (sorted.length === 0) return 'No modules found in context file.';
+    if (sorted.length === 0) return 'No modules found in context file.';
 
-  const total = sorted.reduce((s, m) => s + m.tokenCount, 0);
+    const total = sorted.reduce((s, m) => s + m.tokenCount, 0);
 
-  return [
-    '# Modules',
-    '',
-    '| Module | Files | Tokens |',
-    '|--------|-------|--------|',
-    ...sorted.map((m) => `| ${m.module} | ${m.fileCount} | ~${m.tokenCount} |`),
-    '',
-    `**Total context tokens: ~${total}**`,
-    '',
-    '_Use `read_context({ module: "name" })` to get signatures for a specific module._',
-  ].join('\n');
-  } catch (err) {
-    return `_list_modules failed: ${err.message}_`;
+    return [
+      '# Modules',
+      '',
+      '| Module | Files | Tokens |',
+      '|--------|-------|--------|',
+      ...sorted.map((m) => `| ${m.module} | ${m.fileCount} | ~${m.tokenCount} |`),
+      '',
+      `**Total context tokens: ~${total}**`,
+      '',
+      '_Use `read_context({ module: "name" })` to get signatures for a specific module._',
+    ].join('\n');
+    } catch (err) {
+      return `_list_modules failed: ${err.message}_`;
+    }
   }
-}
-
-/**
- * query_context({ query, topK? }) → string
- *
- * Ranks context-file entries by relevance to the query and returns the
- * top-K most relevant files with their signatures and scores.
- */
-function queryContext(args, cwd) {
-  if (!args || !args.query) return 'Missing required argument: query';
 
-  try {
-    const { rank, buildSigIndex, formatRankTable } = __require('./src/retrieval/ranker');
-    const { buildFromCwd } = __require('./src/graph/builder');
-    const index = buildSigIndex(cwd);
-    if (index.size === 0) return 'No signatures indexed. Run: node gen-context.js';
-
-    const topK = Math.min(Math.max(1, parseInt(args.topK, 10) || 10), 25);
-    // Build dependency graph for neighbor boost — non-fatal if it fails
-    let graph = null;
-    try { graph = buildFromCwd(cwd); } catch (_) {}
-    const results = rank(args.query, index, { topK, cwd, graph });
-    return formatRankTable(results, args.query);
-  } catch (err) {
-    return `_query_context failed: ${err.message}_`;
+  /**
+   * query_context({ query, topK? }) → string
+   *
+   * Ranks context-file entries by relevance to the query and returns the
+   * top-K most relevant files with their signatures and scores.
+   */
+  function queryContext(args, cwd) {
+    if (!args || !args.query) return 'Missing required argument: query';
+
+    try {
+      const { rank, buildSigIndex, formatRankTable } = __require('./src/retrieval/ranker');
+      const { buildFromCwd } = __require('./src/graph/builder');
+      const index = buildSigIndex(cwd);
+      if (index.size === 0) return 'No signatures indexed. Run: node gen-context.js';
+
+      const topK = Math.min(Math.max(1, parseInt(args.topK, 10) || 10), 25);
+      // Build dependency graph for neighbor boost — non-fatal if it fails
+      let graph = null;
+      try { graph = buildFromCwd(cwd); } catch (_) {}
+      const results = rank(args.query, index, { topK, cwd, graph });
+      return formatRankTable(results, args.query);
+    } catch (err) {
+      return `_query_context failed: ${err.message}_`;
+    }
   }
-}
 
-/**
- * get_impact({ file, depth? }) → string
- *
- * Returns a formatted markdown impact report for the given file:
- * direct importers, transitive importers, affected tests, affected routes.
- */
-function getImpact(args, cwd) {
-  if (!args || !args.file) return 'Missing required argument: file';
+  /**
+   * get_impact({ file, depth? }) → string
+   *
+   * Returns a formatted markdown impact report for the given file:
+   * direct importers, transitive importers, affected tests, affected routes.
+   */
+  function getImpact(args, cwd) {
+    if (!args || !args.file) return 'Missing required argument: file';
 
-  try {
-    const { analyzeImpact, formatImpact } = __require('./src/graph/impact');
-    const depth = Math.max(0, parseInt(args.depth, 10) || 3);
-    const results = analyzeImpact(args.file, cwd, { depth });
-    if (results.length === 0) return `No impact data for: ${args.file}`;
-    return results.map((r) => formatImpact(r.impact)).join('\n\n---\n\n');
-  } catch (err) {
-    return `_get_impact failed: ${err.message}_`;
+    try {
+      const { analyzeImpact, formatImpact } = __require('./src/graph/impact');
+      const depth = Math.max(0, parseInt(args.depth, 10) || 3);
+      const results = analyzeImpact(args.file, cwd, { depth });
+      if (results.length === 0) return `No impact data for: ${args.file}`;
+      return results.map((r) => formatImpact(r.impact)).join('\n\n---\n\n');
+    } catch (err) {
+      return `_get_impact failed: ${err.message}_`;
+    }
   }
-}
 
-/**
- * get_lines({ file, start, end }) → string
- *
- * Surgical Context demand-driven fetch: returns an exact, clamped line range from a
- * source file. The path is resolved inside the project root (no traversal escape) and
- * the returned lines are secret-scanned via the same redactor used for signatures.
- */
-function getLines(args, cwd) {
-  if (!args || !args.file) return 'Missing required argument: file';
+  /**
+   * get_lines({ file, start, end }) → string
+   *
+   * Surgical Context demand-driven fetch: returns an exact, clamped line range from a
+   * source file. The path is resolved inside the project root (no traversal escape) and
+   * the returned lines are secret-scanned via the same redactor used for signatures.
+   */
+  function getLines(args, cwd) {
+    if (!args || !args.file) return 'Missing required argument: file';
 
-  const rel = String(args.file).replace(/\\/g, '/').replace(/^\//, '');
-  const abs = path.resolve(cwd, rel);
+    const rel = String(args.file).replace(/\\/g, '/').replace(/^\//, '');
+    const abs = path.resolve(cwd, rel);
 
-  // Sandbox: refuse paths that resolve outside the project root.
-  const root = path.resolve(cwd);
-  if (abs !== root && !abs.startsWith(root + path.sep)) {
-    return `Refused: ${rel} resolves outside the project root`;
-  }
-  if (!fs.existsSync(abs) || !fs.statSync(abs).isFile()) {
-    return `File not found: ${rel}`;
-  }
+    // Sandbox: refuse paths that resolve outside the project root.
+    const root = path.resolve(cwd);
+    if (abs !== root && !abs.startsWith(root + path.sep)) {
+      return `Refused: ${rel} resolves outside the project root`;
+    }
+    if (!fs.existsSync(abs) || !fs.statSync(abs).isFile()) {
+      return `File not found: ${rel}`;
+    }
 
-  const start = parseInt(args.start, 10);
-  const end = parseInt(args.end, 10);
-  if (!Number.isFinite(start) || !Number.isFinite(end)) {
-    return 'Arguments "start" and "end" must be numbers (1-based line numbers).';
-  }
+    const start = parseInt(args.start, 10);
+    const end = parseInt(args.end, 10);
+    if (!Number.isFinite(start) || !Number.isFinite(end)) {
+      return 'Arguments "start" and "end" must be numbers (1-based line numbers).';
+    }
 
-  let lines;
-  try {
-    lines = fs.readFileSync(abs, 'utf8').split('\n');
-  } catch (err) {
-    return `Could not read ${rel}: ${err.message}`;
+    let lines;
+    try {
+      lines = fs.readFileSync(abs, 'utf8').split('\n');
+    } catch (err) {
+      return `Could not read ${rel}: ${err.message}`;
+    }
+
+    const total = lines.length;
+    const from = Math.max(1, Math.min(start, end));
+    const to = Math.min(total, Math.max(start, end));
+    if (from > total) return `${rel} has only ${total} lines; requested ${start}-${end}`;
+
+    const slice = lines.slice(from - 1, to);
+
+    // Redaction scan: reuse the signature secret scanner line-by-line.
+    let safeLines = slice;
+    try {
+      const { scan } = __require('./src/security/scanner');
+      safeLines = scan(slice, rel).safe;
+    } catch (_) {} // non-fatal: fall back to raw slice
+
+    return [
+      `# ${rel}:${from}-${to}`,
+      '```',
+      ...safeLines,
+      '```',
+    ].join('\n');
   }
 
-  const total = lines.length;
-  const from = Math.max(1, Math.min(start, end));
-  const to = Math.min(total, Math.max(start, end));
-  if (from > total) return `${rel} has only ${total} lines; requested ${start}-${end}`;
+  /**
+   * read_memory({ limit? }) → string
+   *
+   * Recall the cross-session decision log (notes) plus the last ranking-session
+   * focus, formatted for an agent to consume at the start of a task.
+   */
+  function readMemory(args, cwd) {
+    let limit = parseInt(args && args.limit, 10);
+    if (!Number.isFinite(limit) || limit <= 0) limit = 10;
+    limit = Math.min(limit, 50);
 
-  const slice = lines.slice(from - 1, to);
+    const out = ['# SigMap memory'];
 
-  // Redaction scan: reuse the signature secret scanner line-by-line.
-  let safeLines = slice;
-  try {
-    const { scan } = __require('./src/security/scanner');
-    safeLines = scan(slice, rel).safe;
-  } catch (_) {} // non-fatal: fall back to raw slice
+    let notes = [];
+    try {
+      const { readNotes, formatNotes } = __require('./src/session/notes');
+      notes = readNotes(cwd, limit);
+      out.push('');
+      out.push(`## Recent notes (${notes.length})`);
+      // Most recent first for quick scanning.
+      out.push(formatNotes(notes.slice().reverse()));
+    } catch (_) {
+      out.push('');
+      out.push('_No notes available._');
+    }
 
-  return [
-    `# ${rel}:${from}-${to}`,
-    '```',
-    ...safeLines,
-    '```',
-  ].join('\n');
-}
+    // Last ranking-session focus (if any) — extends src/session/memory.js.
+    try {
+      const { loadSession } = __require('./src/session/memory');
+      const s = loadSession(cwd);
+      if (s && (s.lastQuery || (s.topFiles && s.topFiles.length))) {
+        out.push('');
+        out.push('## Last session');
+        if (s.lastQuery) out.push(`**Last query:** ${s.lastQuery}`);
+        if (s.topFiles && s.topFiles.length) {
+          out.push(`**Focus files:** ${s.topFiles.map((f) => f.file).slice(0, 5).join(', ')}`);
+        }
+      }
+    } catch (_) { /* session optional */ }
 
-/**
- * read_memory({ limit? }) → string
- *
- * Recall the cross-session decision log (notes) plus the last ranking-session
- * focus, formatted for an agent to consume at the start of a task.
- */
-function readMemory(args, cwd) {
-  let limit = parseInt(args && args.limit, 10);
-  if (!Number.isFinite(limit) || limit <= 0) limit = 10;
-  limit = Math.min(limit, 50);
+    return out.join('\n');
+  }
 
-  const out = ['# SigMap memory'];
+  /**
+   * get_callee_signatures — return the exact defining signature(s) of named
+   * symbols from the index, so an agent never guesses a callee's parameter types.
+   * Unknown names get a closest-match suggestion.
+   * @param {{symbols:string[]}} args
+   * @param {string} cwd
+   */
+  function getCalleeSignatures(args, cwd) {
+    const symbols = args && Array.isArray(args.symbols)
+      ? args.symbols.map((s) => String(s).trim()).filter(Boolean)
+      : null;
+    if (!symbols || symbols.length === 0) {
+      return 'Missing required argument: symbols (non-empty string[])';
+    }
 
-  let notes = [];
-  try {
-    const { readNotes, formatNotes } = __require('./src/session/notes');
-    notes = readNotes(cwd, limit);
-    out.push('');
-    out.push(`## Recent notes (${notes.length})`);
-    // Most recent first for quick scanning.
-    out.push(formatNotes(notes.slice().reverse()));
-  } catch (_) {
-    out.push('');
-    out.push('_No notes available._');
+    try {
+      const { buildSigIndex } = __require('./src/retrieval/ranker');
+      const { buildSymbolCandidates, closestMatch, formatSuggestion } = __require('./src/verify/closest-match');
+      const index = buildSigIndex(cwd);
+      if (index.size === 0) return 'No context file found. Run: node gen-context.js';
+
+      // Extract the defining symbol name from a signature line (same rules as
+      // buildSymbolCandidates) so we match definitions, not param occurrences.
+      const defName = (sig) => {
+        const cleaned = String(sig).replace(/\s*:\d+(?:-\d+)?\s*$/, '');
+        const m = cleaned.match(/\b(?:async\s+function|function|class|def|interface|type|enum|const|let|var)\s+([A-Za-z_$][\w$]*)/)
+          || cleaned.match(/([A-Za-z_$][\w$]*)\s*\(/);
+        return m ? m[1] : null;
+      };
+
+      const candidates = buildSymbolCandidates(index);
+      const blocks = [];
+      for (const symbol of symbols) {
+        const matches = [];
+        for (const [file, sigs] of index.entries()) {
+          for (const sig of sigs) {
+            if (defName(sig) === symbol) matches.push(`${sig}    (${file})`);
+          }
+        }
+        if (matches.length === 0) {
+          const cm = closestMatch(symbol, candidates);
+          const hint = cm ? ' — ' + formatSuggestion(cm) : '';
+          blocks.push(`### ${symbol}\n_not found in index${hint}_`);
+        } else {
+          blocks.push(`### ${symbol}\n${matches.join('\n')}`);
+        }
+      }
+      return blocks.join('\n\n');
+    } catch (err) {
+      return `_get_callee_signatures failed: ${err.message}_`;
+    }
   }
 
-  // Last ranking-session focus (if any) — extends src/session/memory.js.
-  try {
-    const { loadSession } = __require('./src/session/memory');
-    const s = loadSession(cwd);
-    if (s && (s.lastQuery || (s.topFiles && s.topFiles.length))) {
-      out.push('');
-      out.push('## Last session');
-      if (s.lastQuery) out.push(`**Last query:** ${s.lastQuery}`);
-      if (s.topFiles && s.topFiles.length) {
-        out.push(`**Focus files:** ${s.topFiles.map((f) => f.file).slice(0, 5).join(', ')}`);
+  // ── Layer 1: live-index write hooks ────────────────────────────────────────
+  // Keep the sig-cache fresh while an agent creates/modifies/deletes files, so
+  // new code is discoverable in the same session. buildSigIndex already merges
+  // the cache (_buildSigIndexFromCache), so updates are live on the next read.
+
+  function _pkgVersion(cwd) {
+    try { return JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf8')).version || '0.0.0'; }
+    catch (_) { return '0.0.0'; }
+  }
+
+
+  /** notify_file_created — extract a file's signatures and index it live. */
+  function notifyFileCreated(args, cwd) {
+    const rel = args && args.path;
+    if (!rel) return 'Missing required argument: path';
+    try {
+      const { extractFile } = __require('./src/extractors/dispatch');
+      const { loadCache, saveCache } = __require('./src/cache/sig-cache');
+      const abs = path.resolve(cwd, rel);
+      let content = args.content;
+      if (typeof content !== 'string') {
+        try { content = fs.readFileSync(abs, 'utf8'); } catch (_) { content = ''; }
+      }
+      const sigs = extractFile(abs, content);
+      const version = _pkgVersion(cwd);
+      const cache = loadCache(cwd, version);
+      if (sigs.length > 0) {
+        cache.set(abs, { mtime: Date.now(), sigs });
       }
+      saveCache(cwd, version, cache);
+      return `Indexed ${rel}: ${sigs.length} signature(s) now live.`;
+    } catch (err) {
+      return `_notify_file_created failed: ${err.message}_`;
     }
-  } catch (_) { /* session optional */ }
+  }
 
-  return out.join('\n');
-}
+  /** notify_symbol_added — append one signature to a file's live cache entry. */
+  function notifySymbolAdded(args, cwd) {
+    if (!args || !args.signature || !args.file) {
+      return 'Missing required arguments: signature, file';
+    }
+    try {
+      const { loadCache, saveCache } = __require('./src/cache/sig-cache');
+      const abs = path.resolve(cwd, args.file);
+      const version = _pkgVersion(cwd);
+      const cache = loadCache(cwd, version);
+      const entry = cache.get(abs) || { mtime: Date.now(), sigs: [] };
+      const line = Number.isFinite(Number(args.line)) ? `  :${args.line}` : '';
+      const sig = String(args.signature) + line;
+      if (!entry.sigs.includes(sig)) entry.sigs.push(sig);
+      entry.mtime = Date.now();
+      cache.set(abs, entry);
+      saveCache(cwd, version, cache);
+      return `Added signature to ${args.file} (${entry.sigs.length} total).`;
+    } catch (err) {
+      return `_notify_symbol_added failed: ${err.message}_`;
+    }
+  }
 
-module.exports = { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules, queryContext, getImpact, getLines, readMemory };
+  /** notify_file_deleted — drop a file's cache-overlay entry. */
+  function notifyFileDeleted(args, cwd) {
+    const rel = args && args.path;
+    if (!rel) return 'Missing required argument: path';
+    try {
+      const { loadCache, saveCache } = __require('./src/cache/sig-cache');
+      const abs = path.resolve(cwd, rel);
+      const version = _pkgVersion(cwd);
+      const cache = loadCache(cwd, version);
+      const had = cache.delete(abs);
+      saveCache(cwd, version, cache);
+      return had ? `Removed ${rel} from the live index.` : `${rel} was not in the live cache.`;
+    } catch (err) {
+      return `_notify_file_deleted failed: ${err.message}_`;
+    }
+  }
 
+  module.exports = { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules, queryContext, getImpact, getLines, readMemory, getCalleeSignatures, notifyFileCreated, notifySymbolAdded, notifyFileDeleted };
+  
 };
 // ── ./src/learning/weights ──
 __factories["./src/learning/weights"] = function(module, exports) {
@@ -6234,363 +6479,428 @@ __factories["./src/learning/weights"] = function(module, exports) {
 
 // ── ./src/mcp/server ──
 __factories["./src/mcp/server"] = function(module, exports) {
-'use strict';
-
-/**
- * SigMap MCP server — zero npm dependencies.
- *
- * Wire protocol: JSON-RPC 2.0 over stdio.
- * One JSON object per line on both stdin and stdout.
- *
- * Supported methods:
- *   initialize        → serverInfo + capabilities
- *   tools/list        → 11 tool definitions
- *   tools/call        → dispatch to handler, return result
- */
-
-const readline = require('readline');
-const { TOOLS } = __require('./src/mcp/tools');
-const { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules, queryContext, getImpact, getLines, readMemory } = __require('./src/mcp/handlers');
-
-const SERVER_INFO = {
-  name: 'sigmap',
-  version: '7.2.1',
-  description: 'SigMap MCP server — code signatures on demand',
-};
-
-// ---------------------------------------------------------------------------
-// JSON-RPC helpers
-// ---------------------------------------------------------------------------
-function respond(id, result) {
-  process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id, result }) + '\n');
-}
-
-function respondError(id, code, message) {
-  process.stdout.write(
-    JSON.stringify({ jsonrpc: '2.0', id, error: { code, message } }) + '\n'
-  );
-}
+  
+  /**
+   * SigMap MCP server — zero npm dependencies.
+   *
+   * Wire protocol: JSON-RPC 2.0 over stdio.
+   * One JSON object per line on both stdin and stdout.
+   *
+   * Supported methods:
+   *   initialize        → serverInfo + capabilities
+   *   tools/list        → 11 tool definitions
+   *   tools/call        → dispatch to handler, return result
+   */
 
-// ---------------------------------------------------------------------------
-// Method dispatcher
-// ---------------------------------------------------------------------------
-function dispatch(msg, cwd) {
-  const { method, id, params } = msg;
+  const readline = require('readline');
+  const { TOOLS } = __require('./src/mcp/tools');
+  const { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules, queryContext, getImpact, getLines, readMemory, getCalleeSignatures, notifyFileCreated, notifySymbolAdded, notifyFileDeleted } = __require('./src/mcp/handlers');
 
-  // Notifications (no id) need no response
-  if (method === 'notifications/initialized' || method === 'notifications/cancelled') {
-    return;
-  }
+  const SERVER_INFO = {
+    name: 'sigmap',
+    version: '7.4.0',
+    description: 'SigMap MCP server — code signatures on demand',
+  };
 
-  if (method === 'initialize') {
-    respond(id, {
-      protocolVersion: (params && params.protocolVersion) || '2024-11-05',
-      serverInfo: SERVER_INFO,
-      capabilities: { tools: {} },
-    });
-    return;
+  // ---------------------------------------------------------------------------
+  // JSON-RPC helpers
+  // ---------------------------------------------------------------------------
+  function respond(id, result) {
+    process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id, result }) + '\n');
   }
 
-  if (method === 'tools/list') {
-    respond(id, { tools: TOOLS });
-    return;
+  function respondError(id, code, message) {
+    process.stdout.write(
+      JSON.stringify({ jsonrpc: '2.0', id, error: { code, message } }) + '\n'
+    );
   }
 
-  if (method === 'tools/call') {
-    const name = params && params.name;
-    const args = (params && params.arguments) || {};
+  // ---------------------------------------------------------------------------
+  // Method dispatcher
+  // ---------------------------------------------------------------------------
+  function dispatch(msg, cwd) {
+    const { method, id, params } = msg;
 
-    let text;
-    try {
-      if (name === 'read_context') text = readContext(args, cwd);
-      else if (name === 'search_signatures') text = searchSignatures(args, cwd);
-      else if (name === 'get_map') text = getMap(args, cwd);
-      else if (name === 'create_checkpoint') text = createCheckpoint(args, cwd);
-      else if (name === 'get_routing') text = getRouting(args, cwd);
-      else if (name === 'explain_file') text = explainFile(args, cwd);
-      else if (name === 'list_modules') text = listModules(args, cwd);
-      else if (name === 'query_context') text = queryContext(args, cwd);
-      else if (name === 'get_impact') text = getImpact(args, cwd);
-      else if (name === 'get_lines') text = getLines(args, cwd);
-      else if (name === 'read_memory') text = readMemory(args, cwd);
-      else {
-        respondError(id, -32601, `Unknown tool: ${name}`);
-        return;
-      }
-    } catch (err) {
-      respondError(id, -32603, `Tool error: ${err.message}`);
+    // Notifications (no id) need no response
+    if (method === 'notifications/initialized' || method === 'notifications/cancelled') {
       return;
     }
 
-    respond(id, {
-      content: [{ type: 'text', text: String(text) }],
-    });
-    return;
-  }
+    if (method === 'initialize') {
+      respond(id, {
+        protocolVersion: (params && params.protocolVersion) || '2024-11-05',
+        serverInfo: SERVER_INFO,
+        capabilities: { tools: {} },
+      });
+      return;
+    }
 
-  // Unknown method
-  if (id !== undefined && id !== null) {
-    respondError(id, -32601, `Method not found: ${method}`);
-  }
-}
+    if (method === 'tools/list') {
+      respond(id, { tools: TOOLS });
+      return;
+    }
 
-// ---------------------------------------------------------------------------
-// Server entry point
-// ---------------------------------------------------------------------------
-function start(cwd) {
-  const rl = readline.createInterface({ input: process.stdin, terminal: false });
+    if (method === 'tools/call') {
+      const name = params && params.name;
+      const args = (params && params.arguments) || {};
 
-  rl.on('line', (line) => {
-    const trimmed = line.trim();
-    if (!trimmed) return;
+      let text;
+      try {
+        if (name === 'read_context') text = readContext(args, cwd);
+        else if (name === 'search_signatures') text = searchSignatures(args, cwd);
+        else if (name === 'get_map') text = getMap(args, cwd);
+        else if (name === 'create_checkpoint') text = createCheckpoint(args, cwd);
+        else if (name === 'get_routing') text = getRouting(args, cwd);
+        else if (name === 'explain_file') text = explainFile(args, cwd);
+        else if (name === 'list_modules') text = listModules(args, cwd);
+        else if (name === 'query_context') text = queryContext(args, cwd);
+        else if (name === 'get_impact') text = getImpact(args, cwd);
+        else if (name === 'get_lines') text = getLines(args, cwd);
+        else if (name === 'read_memory') text = readMemory(args, cwd);
+        else if (name === 'get_callee_signatures') text = getCalleeSignatures(args, cwd);
+        else if (name === 'sigmap_notify_file_created') text = notifyFileCreated(args, cwd);
+        else if (name === 'sigmap_notify_symbol_added') text = notifySymbolAdded(args, cwd);
+        else if (name === 'sigmap_notify_file_deleted') text = notifyFileDeleted(args, cwd);
+        else {
+          respondError(id, -32601, `Unknown tool: ${name}`);
+          return;
+        }
+      } catch (err) {
+        respondError(id, -32603, `Tool error: ${err.message}`);
+        return;
+      }
 
-    let msg;
-    try {
-      msg = JSON.parse(trimmed);
-    } catch (_) {
-      // Cannot respond without a valid id — ignore malformed input
+      respond(id, {
+        content: [{ type: 'text', text: String(text) }],
+      });
       return;
     }
 
-    try {
-      dispatch(msg, cwd);
-    } catch (err) {
-      const id = (msg && msg.id) != null ? msg.id : null;
-      respondError(id, -32603, `Internal error: ${err.message}`);
+    // Unknown method
+    if (id !== undefined && id !== null) {
+      respondError(id, -32601, `Method not found: ${method}`);
     }
-  });
+  }
 
-  rl.on('close', () => {
-    process.exit(0);
-  });
-}
+  // ---------------------------------------------------------------------------
+  // Server entry point
+  // ---------------------------------------------------------------------------
+  function start(cwd) {
+    const rl = readline.createInterface({ input: process.stdin, terminal: false });
 
-module.exports = { start };
+    rl.on('line', (line) => {
+      const trimmed = line.trim();
+      if (!trimmed) return;
 
+      let msg;
+      try {
+        msg = JSON.parse(trimmed);
+      } catch (_) {
+        // Cannot respond without a valid id — ignore malformed input
+        return;
+      }
+
+      try {
+        dispatch(msg, cwd);
+      } catch (err) {
+        const id = (msg && msg.id) != null ? msg.id : null;
+        respondError(id, -32603, `Internal error: ${err.message}`);
+      }
+    });
+
+    rl.on('close', () => {
+      process.exit(0);
+    });
+  }
+
+  module.exports = { start };
+  
 };
 // ── ./src/mcp/tools ──
 __factories["./src/mcp/tools"] = function(module, exports) {
-'use strict';
-
-/**
- * MCP tool definitions for SigMap (11 tools).
- * read_context, search_signatures, get_map, create_checkpoint, get_routing,
- * explain_file, list_modules, query_context, get_impact, get_lines, read_memory.
- */
+  
+  /**
+   * MCP tool definitions for SigMap (15 tools).
+   * read_context, search_signatures, get_map, create_checkpoint, get_routing,
+   * explain_file, list_modules, query_context, get_impact, get_lines, read_memory,
+   * get_callee_signatures, sigmap_notify_file_created, sigmap_notify_symbol_added,
+   * sigmap_notify_file_deleted.
+   */
 
-const TOOLS = [
-  {
-    name: 'read_context',
-    description:
-      'Read extracted code signatures for the project or a specific module path. ' +
-      'Returns the full copilot-instructions.md content (~500–4K tokens) or a ' +
-      'filtered subset when a module path is provided (~50–500 tokens).',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        module: {
-          type: 'string',
-          description:
-            'Optional subdirectory path to scope results (e.g. "src/services"). ' +
-            'Omit to get the full codebase context.',
+  const TOOLS = [
+    {
+      name: 'read_context',
+      description:
+        'Read extracted code signatures for the project or a specific module path. ' +
+        'Returns the full copilot-instructions.md content (~500–4K tokens) or a ' +
+        'filtered subset when a module path is provided (~50–500 tokens).',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          module: {
+            type: 'string',
+            description:
+              'Optional subdirectory path to scope results (e.g. "src/services"). ' +
+              'Omit to get the full codebase context.',
+          },
         },
+        required: [],
       },
-      required: [],
     },
-  },
-  {
-    name: 'search_signatures',
-    description:
-      'Search extracted code signatures for a keyword, function name, or class name. ' +
-      'Returns matching signature lines with their file paths.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        query: {
-          type: 'string',
-          description: 'Keyword to search for in signatures (case-insensitive).',
+    {
+      name: 'search_signatures',
+      description:
+        'Search extracted code signatures for a keyword, function name, or class name. ' +
+        'Returns matching signature lines with their file paths.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          query: {
+            type: 'string',
+            description: 'Keyword to search for in signatures (case-insensitive).',
+          },
         },
+        required: ['query'],
       },
-      required: ['query'],
     },
-  },
-  {
-    name: 'get_map',
-    description:
-      'Read a section from PROJECT_MAP.md — import graph, class hierarchy, or route table. ' +
-      'Requires gen-project-map.js to have been run first.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        type: {
-          type: 'string',
-          enum: ['imports', 'classes', 'routes'],
-          description: 'Which section to retrieve: imports, classes, or routes.',
+    {
+      name: 'get_map',
+      description:
+        'Read a section from PROJECT_MAP.md — import graph, class hierarchy, or route table. ' +
+        'Requires gen-project-map.js to have been run first.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          type: {
+            type: 'string',
+            enum: ['imports', 'classes', 'routes'],
+            description: 'Which section to retrieve: imports, classes, or routes.',
+          },
         },
+        required: ['type'],
       },
-      required: ['type'],
     },
-  },
-  {
-    name: 'create_checkpoint',
-    description:
-      'Create a session checkpoint summarising current project state. ' +
-      'Returns recent git commits, active branch, token count, and a ' +
-      'compact snapshot of the codebase context — ideal for session handoffs ' +
-      'or periodic saves during long coding sessions.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        note: {
-          type: 'string',
-          description: 'Optional free-text note to include in the checkpoint (e.g. what you were working on).',
+    {
+      name: 'create_checkpoint',
+      description:
+        'Create a session checkpoint summarising current project state. ' +
+        'Returns recent git commits, active branch, token count, and a ' +
+        'compact snapshot of the codebase context — ideal for session handoffs ' +
+        'or periodic saves during long coding sessions.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          note: {
+            type: 'string',
+            description: 'Optional free-text note to include in the checkpoint (e.g. what you were working on).',
+          },
         },
+        required: [],
       },
-      required: [],
     },
-  },
-  {
-    name: 'get_routing',
-    description:
-      'Get model routing hints for this project — which files belong to which complexity ' +
-      'tier (fast/balanced/powerful) and which AI model to use for each type of task. ' +
-      'Helps reduce API costs by 40–80% by routing simple tasks to cheaper models.',
-    inputSchema: {
-      type: 'object',
-      properties: {},
-      required: [],
+    {
+      name: 'get_routing',
+      description:
+        'Get model routing hints for this project — which files belong to which complexity ' +
+        'tier (fast/balanced/powerful) and which AI model to use for each type of task. ' +
+        'Helps reduce API costs by 40–80% by routing simple tasks to cheaper models.',
+      inputSchema: {
+        type: 'object',
+        properties: {},
+        required: [],
+      },
     },
-  },
-  {
-    name: 'explain_file',
-    description:
-      'Explain a specific file: returns its extracted signatures, direct imports ' +
-      '(files it depends on), and callers (files that import it). ' +
-      'Ideal for understanding a file in isolation without reading raw source. ' +
-      'Requires the context file to have been generated first.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        path: {
-          type: 'string',
-          description:
-            'Relative path from the project root (e.g. "src/services/auth.ts"). ' +
-            'Use the paths shown in read_context output.',
+    {
+      name: 'explain_file',
+      description:
+        'Explain a specific file: returns its extracted signatures, direct imports ' +
+        '(files it depends on), and callers (files that import it). ' +
+        'Ideal for understanding a file in isolation without reading raw source. ' +
+        'Requires the context file to have been generated first.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          path: {
+            type: 'string',
+            description:
+              'Relative path from the project root (e.g. "src/services/auth.ts"). ' +
+              'Use the paths shown in read_context output.',
+          },
         },
+        required: ['path'],
       },
-      required: ['path'],
     },
-  },
-  {
-    name: 'list_modules',
-    description:
-      'List all top-level modules (srcDirs) present in the context file, ' +
-      'sorted by token count descending. Use this to decide which module to ' +
-      'pass to read_context before querying a specific area of the codebase.',
-    inputSchema: {
-      type: 'object',
-      properties: {},
-      required: [],
+    {
+      name: 'list_modules',
+      description:
+        'List all top-level modules (srcDirs) present in the context file, ' +
+        'sorted by token count descending. Use this to decide which module to ' +
+        'pass to read_context before querying a specific area of the codebase.',
+      inputSchema: {
+        type: 'object',
+        properties: {},
+        required: [],
+      },
     },
-  },
-  {
-    name: 'query_context',
-    description:
-      'Rank and return the most relevant files for a specific task or question. ' +
-      'Uses keyword + symbol + path scoring to surface only the top-K files relevant ' +
-      'to the query — much cheaper than reading all context. ' +
-      'Returns ranked file list with signatures and relevance scores.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        query: {
-          type: 'string',
-          description:
-            'Natural language task description or keyword(s) to rank files against. ' +
-            'E.g. "add a new language extractor", "fix secret scanning", "auth module".',
+    {
+      name: 'query_context',
+      description:
+        'Rank and return the most relevant files for a specific task or question. ' +
+        'Uses keyword + symbol + path scoring to surface only the top-K files relevant ' +
+        'to the query — much cheaper than reading all context. ' +
+        'Returns ranked file list with signatures and relevance scores.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          query: {
+            type: 'string',
+            description:
+              'Natural language task description or keyword(s) to rank files against. ' +
+              'E.g. "add a new language extractor", "fix secret scanning", "auth module".',
+          },
+          topK: {
+            type: 'number',
+            description: 'Maximum number of files to return (default: 10, max: 25).',
+          },
         },
-        topK: {
-          type: 'number',
-          description: 'Maximum number of files to return (default: 10, max: 25).',
+        required: ['query'],
+      },
+    },
+    {
+      name: 'get_impact',
+      description:
+        'Show every file that is impacted when a given file changes — direct importers, ' +
+        'transitive importers, affected tests, and affected routes/controllers. ' +
+        'Gives agents instant blast-radius awareness before making a change. ' +
+        'Handles circular dependencies safely (no infinite loops).',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          file: {
+            type: 'string',
+            description:
+              'Relative path from the project root of the file that changed ' +
+              '(e.g. "src/extractors/python.js"). Use forward slashes.',
+          },
+          depth: {
+            type: 'number',
+            description: 'BFS traversal depth limit (default: 3). Use 0 for unlimited.',
+          },
         },
+        required: ['file'],
       },
-      required: ['query'],
     },
-  },
-  {
-    name: 'get_impact',
-    description:
-      'Show every file that is impacted when a given file changes — direct importers, ' +
-      'transitive importers, affected tests, and affected routes/controllers. ' +
-      'Gives agents instant blast-radius awareness before making a change. ' +
-      'Handles circular dependencies safely (no infinite loops).',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        file: {
-          type: 'string',
-          description:
-            'Relative path from the project root of the file that changed ' +
-            '(e.g. "src/extractors/python.js"). Use forward slashes.',
+    {
+      name: 'get_lines',
+      description:
+        'Fetch an exact line range from a source file on demand — the Surgical Context ' +
+        'workhorse. Signatures carry `path:start-end` anchors; call this to read just those ' +
+        'lines instead of re-opening the whole file. Lines are clamped to the file bounds and ' +
+        'secret-scanned (redacted) before return. Path is sandboxed to the project root.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          file: {
+            type: 'string',
+            description:
+              'Relative path from the project root (e.g. "src/config/loader.js"). ' +
+              'Use the path shown in a signature anchor. Use forward slashes.',
+          },
+          start: {
+            type: 'number',
+            description: '1-based start line (inclusive). Clamped to the file bounds.',
+          },
+          end: {
+            type: 'number',
+            description: '1-based end line (inclusive). Clamped to the file bounds.',
+          },
         },
-        depth: {
-          type: 'number',
-          description: 'BFS traversal depth limit (default: 3). Use 0 for unlimited.',
+        required: ['file', 'start', 'end'],
+      },
+    },
+    {
+      name: 'read_memory',
+      description:
+        'Recall the project decision log — recent notes left by humans or agents ' +
+        'across sessions (via `sigmap note`), plus the last ranking-session focus. ' +
+        'Call this at the start of a task to kill cold-start: it answers ' +
+        '"what were we doing and why" without re-reading the whole codebase.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          limit: {
+            type: 'number',
+            description: 'How many of the most recent notes to return (default: 10, max: 50).',
+          },
         },
+        required: [],
       },
-      required: ['file'],
     },
-  },
-  {
-    name: 'get_lines',
-    description:
-      'Fetch an exact line range from a source file on demand — the Surgical Context ' +
-      'workhorse. Signatures carry `path:start-end` anchors; call this to read just those ' +
-      'lines instead of re-opening the whole file. Lines are clamped to the file bounds and ' +
-      'secret-scanned (redacted) before return. Path is sandboxed to the project root.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        file: {
-          type: 'string',
-          description:
-            'Relative path from the project root (e.g. "src/config/loader.js"). ' +
-            'Use the path shown in a signature anchor. Use forward slashes.',
+    {
+      name: 'get_callee_signatures',
+      description:
+        'Return the EXACT current signature(s) of named symbols (functions, classes, ' +
+        "methods) from the index — so an agent never guesses a callee's parameter types " +
+        'from training memory. Call this before writing code that uses a symbol. ' +
+        'Unknown names get a closest-match suggestion.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          symbols: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'Symbol names to resolve (e.g. ["validateToken", "UserService"]).',
+          },
         },
-        start: {
-          type: 'number',
-          description: '1-based start line (inclusive). Clamped to the file bounds.',
+        required: ['symbols'],
+      },
+    },
+    {
+      name: 'sigmap_notify_file_created',
+      description:
+        'Tell SigMap a file was created or modified so its signatures are indexed ' +
+        'live for the rest of the session. Call this after writing a file — the new ' +
+        'symbols become resolvable by search_signatures / get_callee_signatures.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          path: { type: 'string', description: 'File path relative to the project root.' },
+          content: { type: 'string', description: 'Optional file content; read from disk if omitted.' },
         },
-        end: {
-          type: 'number',
-          description: '1-based end line (inclusive). Clamped to the file bounds.',
+        required: ['path'],
+      },
+    },
+    {
+      name: 'sigmap_notify_symbol_added',
+      description:
+        'Fast path: register a single new symbol signature directly in the live ' +
+        'index without re-reading the whole file.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          signature: { type: 'string', description: 'The signature line (e.g. "function check(key)").' },
+          file: { type: 'string', description: 'File path the symbol belongs to (relative to root).' },
+          line: { type: 'number', description: 'Optional 1-based line number.' },
         },
+        required: ['signature', 'file'],
       },
-      required: ['file', 'start', 'end'],
     },
-  },
-  {
-    name: 'read_memory',
-    description:
-      'Recall the project decision log — recent notes left by humans or agents ' +
-      'across sessions (via `sigmap note`), plus the last ranking-session focus. ' +
-      'Call this at the start of a task to kill cold-start: it answers ' +
-      '"what were we doing and why" without re-reading the whole codebase.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        limit: {
-          type: 'number',
-          description: 'How many of the most recent notes to return (default: 10, max: 50).',
+    {
+      name: 'sigmap_notify_file_deleted',
+      description:
+        'Tell SigMap a file was deleted so its symbols are dropped from the live index.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          path: { type: 'string', description: 'Deleted file path relative to the project root.' },
         },
+        required: ['path'],
       },
-      required: [],
     },
-  },
-];
-
-module.exports = { TOOLS };
+  ];
 
+  module.exports = { TOOLS };
+  
 };
 // ── ./src/routing/classifier ──
 __factories["./src/routing/classifier"] = function(module, exports) {
@@ -7907,61 +8217,293 @@ __factories["./src/retrieval/tokenizer"] = function(module, exports) {
 
 // ── ./src/retrieval/ranker ──
 __factories["./src/retrieval/ranker"] = function(module, exports) {
-  'use strict';
+  
+  /**
+   * SigMap zero-dependency relevance ranker.
+   *
+   * Ranks all files in a signature index against a natural-language query.
+   * Scoring weights:
+   *   - keyword overlap (exact token match against sigs)
+   *   - symbol match (token appears in a top-level identifier / function name)
+   *   - partial prefix match (token is prefix of a sig token, length ≥ 4)
+   *   - path relevance (query token appears in the file path)
+   *   - recency boost (applied externally via recency map)
+   *
+   * Usage:
+   *   const { rank } = __require('./src/retrieval/src/retrieval/ranker');
+   *   const results = rank(query, sigIndex, { topK: 10 });
+   *   // results: [{ file, score, sigs, tokens }]
+   */
+
   const { loadWeights } = __require('./src/learning/weights');
   const { tokenize, STOP_WORDS } = __require('./src/retrieval/tokenizer');
+
+  // ---------------------------------------------------------------------------
+  // Default weights
+  // ---------------------------------------------------------------------------
   const DEFAULT_WEIGHTS = {
-    exactToken: 1.0, symbolMatch: 0.5, prefixMatch: 0.3, pathMatch: 0.8, recencyBoost: 1.5,
+    exactToken: 1.0,       // query token exactly in sig tokens
+    symbolMatch: 0.5,      // bonus if token appears in a function/class name line
+    prefixMatch: 0.3,      // partial prefix hit (query token ≥ 4 chars)
+    pathMatch: 0.8,        // query token appears in the file path
+    recencyBoost: 1.5,     // multiplier applied when file is in recencySet
+    graphBoost: 0.4,       // additive bonus for 1-hop import neighbors of matching files
+  };
+
+  // Graph boost amounts for 2-hop traversal with decay (v6.7)
+  const GRAPH_BOOST_AMOUNTS = {
+    hop1: 0.40,   // direct import neighbor of a file with score > 0
+    hop2: 0.15,   // 2 hops away (transitive), with decay
+  };
+
+  // Intent-specific weight adjustments
+  const INTENT_WEIGHTS = {
+    search:     DEFAULT_WEIGHTS,
+    debug:      { ...DEFAULT_WEIGHTS, exactToken: 1.2, pathMatch: 0.6 },
+    explain:    { ...DEFAULT_WEIGHTS, symbolMatch: 0.8, pathMatch: 0.9 },
+    refactor:   { ...DEFAULT_WEIGHTS, symbolMatch: 0.9, exactToken: 0.8 },
+    review:     { ...DEFAULT_WEIGHTS, pathMatch: 1.0, exactToken: 0.9 },
+    test:       { ...DEFAULT_WEIGHTS, exactToken: 0.7, symbolMatch: 0.4 },
+    integrate:  { ...DEFAULT_WEIGHTS, graphBoost: 0.7, pathMatch: 1.1 },
+    navigate:   { ...DEFAULT_WEIGHTS, pathMatch: 1.2, exactToken: 0.9 },
+  };
+
+  // Penalty multipliers for negative signals
+  const PENALTY_SIGNALS = {
+    testFile:      0.4,    // test/spec/__tests__ in path
+    generatedCode: 0.3,    // dist/build/.next in path
+    docsFile:      0.2,    // docs/doc/README in path
+    nodeModules:   0.0,    // node_modules (zero score)
   };
+
+  function _computePenalty(filePath) {
+    const pathLower = filePath.toLowerCase();
+    if (pathLower.includes('node_modules')) return PENALTY_SIGNALS.nodeModules;
+    if (/(^|\/)(test|tests|spec|__tests__|e2e)($|\/)/.test(pathLower)) return PENALTY_SIGNALS.testFile;
+    if (/(^|\/)(dist|build|\.next|\.nuxt|out|\.venv|venv)($|\/)/.test(pathLower)) return PENALTY_SIGNALS.generatedCode;
+    if (/(^|\/)(docs|doc|readme|changelog)($|\/)/.test(pathLower)) return PENALTY_SIGNALS.docsFile;
+    return 1.0;
+  }
+
+  // Detect hub files: those with fanout > 20% of all files in the graph
+  function _computeHubs(graph) {
+    if (!graph || !graph.reverse) return new Set();
+    const fileCount = Math.max(1, graph.reverse.size);
+    const threshold = Math.ceil(fileCount * 0.2);
+    const hubs = new Set();
+    for (const [file, deps] of graph.reverse) {
+      if ((deps && deps.size >= threshold) || (Array.isArray(deps) && deps.length >= threshold)) {
+        hubs.add(file);
+      }
+    }
+    return hubs;
+  }
+
+  // Common utility paths that should be treated as hubs regardless of fanout
+  function _isHub(filePath) {
+    return /\/(utils|helpers|shared|common|constants|types|interfaces|index|zzz|globals)\.(ts|tsx|js|jsx|r|R)$/.test(filePath)
+        || filePath.endsWith('/index.ts') || filePath.endsWith('/index.js')
+        || filePath.endsWith('/R/utils.R') || filePath.endsWith('/R/zzz.R') || filePath.endsWith('/R/globals.R');
+  }
+
+  /**
+   * Score a single file against a query, returning detailed signal breakdown.
+   *
+   * @param {string}   filePath   - relative file path (e.g. 'src/extractors/python.js')
+   * @param {string[]} sigs       - signature strings for this file
+   * @param {string[]} queryTokens - pre-tokenized query
+   * @param {object}   weights
+   * @returns {{ score: number, signals: { exactToken: number, symbolMatch: number, prefixMatch: number, pathMatch: number, penalty: number } }}
+   */
   function scoreFile(filePath, sigs, queryTokens, weights) {
-    if (!sigs || sigs.length === 0) return 0;
+    if (!sigs || sigs.length === 0) return { score: 0, signals: { exactToken: 0, symbolMatch: 0, prefixMatch: 0, pathMatch: 0, penalty: 1.0 } };
+
     const w = weights || DEFAULT_WEIGHTS;
-    const sigTokenSet = new Set(tokenize(sigs.join(' ')));
+    const signals = { exactToken: 0, symbolMatch: 0, prefixMatch: 0, pathMatch: 0, penalty: _computePenalty(filePath) };
+
+    // Build token set from all signatures
+    const sigText = sigs.join(' ');
+    const sigTokenSet = new Set(tokenize(sigText));
+
+    // Build token set from the file path
     const pathTokenSet = new Set(tokenize(filePath));
+
     let score = 0;
+
     for (const qt of queryTokens) {
       if (STOP_WORDS.has(qt)) continue;
+
+      // Exact token match in sigs
       if (sigTokenSet.has(qt)) {
-        score += w.exactToken;
-        if (sigs.some((sig) => tokenize(sig.replace(/[^a-zA-Z0-9_\s]/g, ' ')).includes(qt))) score += w.symbolMatch;
+        const bonus = w.exactToken;
+        score += bonus;
+        signals.exactToken += bonus;
+
+        // Bonus: appears directly in a function/class/method name line
+        const nameLineMatch = sigs.some((sig) => {
+          const nt = tokenize(sig.replace(/[^a-zA-Z0-9_\s]/g, ' '));
+          return nt.includes(qt);
+        });
+        if (nameLineMatch) {
+          score += w.symbolMatch;
+          signals.symbolMatch += w.symbolMatch;
+        }
       }
+
+      // Prefix match (e.g. query "python" matches "pythonDeps")
       if (qt.length >= 4) {
         for (const st of sigTokenSet) {
-          if (st !== qt && st.startsWith(qt)) { score += w.prefixMatch; break; }
+          if (st !== qt && st.startsWith(qt)) {
+            score += w.prefixMatch;
+            signals.prefixMatch += w.prefixMatch;
+            break; // one bonus per query token
+          }
         }
       }
-      if (pathTokenSet.has(qt)) score += w.pathMatch;
+
+      // Path token match
+      if (pathTokenSet.has(qt)) {
+        score += w.pathMatch;
+        signals.pathMatch += w.pathMatch;
+      }
     }
-    return score;
+
+    // Apply penalty multiplier
+    score *= signals.penalty;
+
+    return { score, signals };
   }
+
+  /**
+   * Rank all files in a signature index against a query.
+   *
+   * @param {string}              query     - natural language query
+   * @param {Map<string,string[]>} sigIndex - Map<file, sigs[]>
+   * @param {object}  [opts]
+   * @param {number}  [opts.topK=10]               - max results to return
+   * @param {number}  [opts.recencyBoost=1.5]       - multiplier for recent files
+   * @param {Set<string>} [opts.recencySet]         - set of recently-changed file paths
+   * @param {object}  [opts.weights]               - override scoring weights
+   * @param {string}  [opts.cwd]                   - project root for learned ranking weights
+   * @param {{ forward: Map<string,string[]> }} [opts.graph] - dependency graph for neighbor boost
+   * @returns {{ file: string, score: number, sigs: string[], tokens: number, intent: string, signals: object }[]}
+   */
   function rank(query, sigIndex, opts) {
     if (!query || typeof query !== 'string') return [];
     if (!sigIndex || !(sigIndex instanceof Map) || sigIndex.size === 0) return [];
+
     const topK = (opts && opts.topK) || 10;
     const recencyMultiplier = (opts && opts.recencyBoost) || DEFAULT_WEIGHTS.recencyBoost;
     const recencySet = (opts && opts.recencySet) || null;
-    const weights = (opts && opts.weights) ? Object.assign({}, DEFAULT_WEIGHTS, opts.weights) : DEFAULT_WEIGHTS;
+    const graph = (opts && opts.graph && opts.graph.forward instanceof Map) ? opts.graph : null;
+    const cwd = (opts && opts.cwd) || null;
+
+    // Detect query intent and get appropriate weights
+    const intent = detectIntent(query);
+    const intentWeights = INTENT_WEIGHTS[intent] || DEFAULT_WEIGHTS;
+    const weights = (opts && opts.weights) ? Object.assign({}, intentWeights, opts.weights) : intentWeights;
     const learnedWeights = opts && opts.cwd ? loadWeights(opts.cwd) : null;
+
     const queryTokens = tokenize(query);
     if (queryTokens.length === 0) {
+      // Empty query: return top-K by file count (most signatures = most useful)
       const all = [];
-      for (const [file, sigs] of sigIndex.entries()) all.push({ file, score: sigs.length, sigs, tokens: Math.ceil(sigs.join('\n').length / 4) });
+      for (const [file, sigs] of sigIndex.entries()) {
+        all.push({ file, score: sigs.length, sigs, tokens: Math.ceil(sigs.join('\n').length / 4), intent, signals: {} });
+      }
       all.sort((a, b) => b.score - a.score || a.file.localeCompare(b.file));
       return all.slice(0, topK);
     }
+
     const scored = [];
     for (const [file, sigs] of sigIndex.entries()) {
-      let score = scoreFile(file, sigs, queryTokens, weights);
-      if (recencySet && recencySet.has(file) && score > 0) score *= recencyMultiplier;
-      if (learnedWeights && score > 0) score *= learnedWeights[file] || 1.0;
-      scored.push({ file, score, sigs, tokens: Math.ceil(sigs.join('\n').length / 4) });
+      const result = scoreFile(file, sigs, queryTokens, weights);
+      let score = result.score;
+      const signals = result.signals;
+
+      // Recency boost
+      if (recencySet && recencySet.has(file) && score > 0) {
+        score *= recencyMultiplier;
+        signals.recencyBoost = recencyMultiplier;
+      }
+
+      if (learnedWeights && score > 0) {
+        const multiplier = learnedWeights[file] || 1.0;
+        score *= multiplier;
+        signals.learnedWeights = multiplier;
+      }
+
+      scored.push({
+        file,
+        score,
+        sigs,
+        tokens: Math.ceil(sigs.join('\n').length / 4),
+        intent,
+        signals,
+      });
+    }
+
+    // Graph neighbor boost: 2-hop traversal with decay (v6.7)
+    // Hop 1: add hop1 amount to direct import neighbors (score > 0)
+    // Hop 2: add hop2 amount to neighbors of hop1 files (with decay)
+    // Hub suppression: files with high fanout (>20%) are not boosted
+    if (graph && cwd) {
+      const path = require('path');
+      // Build maps for relative ↔ absolute path conversion and index lookup
+      const relToIdx = new Map();
+      const absToRel = new Map();
+      for (let i = 0; i < scored.length; i++) {
+        relToIdx.set(scored[i].file, i);
+        const abs = path.resolve(cwd, scored[i].file);
+        absToRel.set(abs, scored[i].file);
+      }
+
+      const hubs = _computeHubs(graph);
+      const hop1Files = new Set(); // track which files received hop1 boost
+
+      // Hop 1: direct neighbors of scored files
+      for (const entry of scored) {
+        if (entry.score <= 0) continue;
+        const abs = path.resolve(cwd, entry.file);
+        const neighbors = graph.forward.get(abs) || [];
+        for (const neighborAbs of neighbors) {
+          if (_isHub(neighborAbs) || hubs.has(neighborAbs)) continue;
+          const neighborRel = path.relative(cwd, neighborAbs).replace(/\\/g, '/');
+          const idx = relToIdx.get(neighborRel);
+          if (idx !== undefined) {
+            scored[idx].score += GRAPH_BOOST_AMOUNTS.hop1;
+            scored[idx].signals.graphBoost = (scored[idx].signals.graphBoost || 0) + GRAPH_BOOST_AMOUNTS.hop1;
+            hop1Files.add(neighborAbs);
+          }
+        }
+      }
+
+      // Hop 2: neighbors of hop1 files (only if they didn't get a direct score)
+      for (const hop1File of hop1Files) {
+        if (!absToRel.has(hop1File)) continue; // skip files not in index
+        const neighbors = graph.forward.get(hop1File) || [];
+        for (const neighborAbs of neighbors) {
+          if (_isHub(neighborAbs) || hubs.has(neighborAbs)) continue;
+          if (hop1Files.has(neighborAbs)) continue; // skip already hop1-boosted
+          const neighborRel = path.relative(cwd, neighborAbs).replace(/\\/g, '/');
+          const idx = relToIdx.get(neighborRel);
+          if (idx !== undefined && scored[idx].score > 0) {
+            // Only boost files that have some baseline score (not noise)
+            scored[idx].score += GRAPH_BOOST_AMOUNTS.hop2;
+            scored[idx].signals.graphBoost = (scored[idx].signals.graphBoost || 0) + GRAPH_BOOST_AMOUNTS.hop2;
+          }
+        }
+      }
     }
+
     // Compute confidence levels based on score distribution
     if (scored.length > 0) {
       const scores = scored.map(s => s.score);
       const maxScore = Math.max(...scores);
       const minScore = Math.min(...scores);
       const scoreRange = maxScore - minScore || 1;
+
+      // Confidence tiers: top 33% = high, next 33% = medium, rest = low
       for (const entry of scored) {
         if (entry.score <= 0) {
           entry.confidence = 'low';
@@ -7971,39 +8513,73 @@ __factories["./src/retrieval/ranker"] = function(module, exports) {
         }
       }
     }
+
     scored.sort((a, b) => b.score - a.score || a.file.localeCompare(b.file));
     return scored.slice(0, topK);
   }
+
+  /**
+   * All paths where sigmap adapters write their context files, in probe order.
+   * The first existing file with a non-empty index wins when no explicit path
+   * is supplied.
+   */
   const ADAPTER_OUTPUT_PATHS = [
-    ['.github', 'copilot-instructions.md'],
-    ['CLAUDE.md'],
-    ['AGENTS.md'],
-    ['.cursorrules'],
-    ['.windsurfrules'],
-    ['.github', 'openai-context.md'],
-    ['.github', 'gemini-context.md'],
-    ['llm-full.txt'],
-    ['llm.txt'],
+    ['.github', 'copilot-instructions.md'], // copilot (default)
+    ['CLAUDE.md'],                           // claude
+    ['AGENTS.md'],                           // codex
+    ['.cursorrules'],                        // cursor
+    ['.windsurfrules'],                      // windsurf
+    ['.github', 'openai-context.md'],        // openai
+    ['.github', 'gemini-context.md'],        // gemini
+    ['llm-full.txt'],                        // llm-full
+    ['llm.txt'],                             // llm
   ];
+
+  /**
+   * Parse a single context file into a Map<filePath, string[]>.
+   *
+   * Files that contain human-written content before an
+   * "## Auto-generated signatures" marker (e.g. CLAUDE.md) are handled
+   * by skipping everything above the marker before scanning for ### headers.
+   *
+   * @param {string} contextPath  - absolute path to the context file
+   * @returns {Map<string, string[]>}
+   */
   function _parseContextFile(contextPath) {
     const fs = require('fs');
     const index = new Map();
+
     if (!fs.existsSync(contextPath)) return index;
+
     let content = fs.readFileSync(contextPath, 'utf8');
+
+    // Skip any human-written preamble that sits above the auto-generated block.
     const markerIdx = content.indexOf('## Auto-generated signatures');
     if (markerIdx !== -1) content = content.slice(markerIdx);
+
     const lines = content.split('\n');
-    let currentFile = null; let inBlock = false; let sigs = [];
+    let currentFile = null;
+    let inBlock = false;
+    let sigs = [];
+
     for (const line of lines) {
-      const hm = line.match(/^###\s+(\S+)\s*$/);
-      if (hm) { if (currentFile !== null) index.set(currentFile, sigs); currentFile = hm[1]; sigs = []; inBlock = false; continue; }
+      const headerMatch = line.match(/^###\s+(\S+)\s*$/);
+      if (headerMatch) {
+        if (currentFile !== null) index.set(currentFile, sigs);
+        currentFile = headerMatch[1];
+        sigs = [];
+        inBlock = false;
+        continue;
+      }
       if (line.startsWith('```')) { inBlock = !inBlock; continue; }
       if (inBlock && currentFile && line.trim()) sigs.push(line.trim());
     }
     if (currentFile !== null) index.set(currentFile, sigs);
+
     return index;
   }
 
+  /** Merge source index into target; prefer non-empty sig lists. */
   function _mergeSigIndex(target, source) {
     for (const [file, sigs] of source.entries()) {
       if (!sigs || sigs.length === 0) continue;
@@ -8014,12 +8590,17 @@ __factories["./src/retrieval/ranker"] = function(module, exports) {
     return target;
   }
 
+  /**
+   * Load signatures from .sigmap-cache.json (absolute paths → repo-relative keys).
+   * @param {string} cwd
+   * @returns {Map<string, string[]>}
+   */
   function _buildSigIndexFromCache(cwd) {
     const fs = require('fs');
     const path = require('path');
     const index = new Map();
     try {
-      const { loadCache } = require('../cache/sig-cache');
+      const { loadCache } = __require('./src/cache/sig-cache');
       const pkgPath = path.join(cwd, 'package.json');
       let version = '0.0.0';
       if (fs.existsSync(pkgPath)) {
@@ -8036,6 +8617,12 @@ __factories["./src/retrieval/ranker"] = function(module, exports) {
     return index;
   }
 
+  /**
+   * Hot-cold and per-module strategies store most signatures outside the primary
+   * copilot-instructions.md file. MCP tools must merge all sources.
+   * @param {string} cwd
+   * @returns {Map<string, string[]>}
+   */
   function _enrichSigIndexFromStrategy(cwd, index) {
     const path = require('path');
     const coldPath = path.join(cwd, '.github', 'context-cold.md');
@@ -8044,49 +8631,138 @@ __factories["./src/retrieval/ranker"] = function(module, exports) {
     return index;
   }
 
+  /**
+   * Build a signature index from the generated context file.
+   * Returns Map<filePath, string[]> where filePath is the relative path
+   * as it appears in the ### headers of the context file.
+   *
+   * Resolution priority:
+   *  1. `opts.contextPath` — explicit path from --output or --adapter flag
+   *  2. `customOutput` key in gen-context.config.json — persisted from a
+   *     previous `--output <file>` generation run
+   *  3. All known adapter output paths probed in order (first non-empty wins)
+   *
+   * @param {string} cwd
+   * @param {{ contextPath?: string }} [opts]
+   * @returns {Map<string, string[]>}
+   */
   function buildSigIndex(cwd, opts) {
-    const fs = require('fs'); const path = require('path');
-    if (opts && opts.contextPath) return _enrichSigIndexFromStrategy(cwd, _parseContextFile(opts.contextPath));
-    // Check gen-context.config.json for a persisted customOutput path.
+    const fs   = require('fs');
+    const path = require('path');
+
+    // 1. Caller supplied an explicit path — use it directly.
+    if (opts && opts.contextPath) {
+      const index = _parseContextFile(opts.contextPath);
+      return _enrichSigIndexFromStrategy(cwd, index);
+    }
+
+    // 2. Check gen-context.config.json for a persisted customOutput path.
     try {
       const cfgPath = path.join(cwd, 'gen-context.config.json');
       if (fs.existsSync(cfgPath)) {
         const cfg = JSON.parse(fs.readFileSync(cfgPath, 'utf8'));
         if (cfg.customOutput) {
-          const idx = _parseContextFile(path.resolve(cwd, cfg.customOutput));
-          if (idx.size > 0) return _enrichSigIndexFromStrategy(cwd, idx);
+          const customPath = path.resolve(cwd, cfg.customOutput);
+          const index = _parseContextFile(customPath);
+          if (index.size > 0) return _enrichSigIndexFromStrategy(cwd, index);
         }
       }
     } catch (_) {}
+
+    // 3. Probe all known adapter output paths; return first non-empty index.
     for (const parts of ADAPTER_OUTPUT_PATHS) {
       const contextPath = path.join(cwd, ...parts);
       const index = _parseContextFile(contextPath);
       if (index.size > 0) return _enrichSigIndexFromStrategy(cwd, index);
     }
-    return _enrichSigIndexFromStrategy(cwd, new Map());
+
+    // 4. Primary file empty/missing (hot-cold) — still serve cold + cache.
+    const fallback = new Map();
+    return _enrichSigIndexFromStrategy(cwd, fallback);
   }
+
+  /**
+   * Format ranked results as a markdown table string.
+   *
+   * @param {{ file: string, score: number, sigs: string[], tokens: number, intent: string, signals: object }[]} results
+   * @param {string} query
+   * @returns {string}
+   */
   function formatRankTable(results, query) {
-    if (!results || results.length === 0) return `No matching files found for query: "${query}"\n`;
-    const lines = [`## Query: ${query}`, '', '| Rank | File | Score | Sigs | Tokens |', '|------|------|-------|------|--------|',
-      ...results.map((r, i) => `| ${i + 1} | ${r.file} | ${r.score.toFixed(2)} | ${r.sigs.length} | ${r.tokens} |`), ''];
+    if (!results || results.length === 0) {
+      return `No matching files found for query: "${query}"\n`;
+    }
+
+    const intent = (results[0] && results[0].intent) || 'search';
+    const lines = [
+      `## Query: ${query}`,
+      `Intent: ${intent}`,
+      '',
+      '| Rank | File | Score | Sigs | Penalty |',
+      '|------|------|-------|------|---------|',
+      ...results.map((r, i) => {
+        const penalty = r.signals && r.signals.penalty ? r.signals.penalty.toFixed(2) : '1.00';
+        return `| ${i + 1} | ${r.file} | ${r.score.toFixed(2)} | ${r.sigs.length} | ${penalty} |`;
+      }),
+      '',
+    ];
+
+    // Add signature details for top results
     for (const r of results.slice(0, 3)) {
       if (r.sigs.length > 0) {
-        lines.push(`### ${r.file}`, '```', ...r.sigs.slice(0, 10));
+        lines.push(`### ${r.file}`);
+        if (r.signals) {
+          const sig = r.signals;
+          lines.push(`Signals: exactToken=${(sig.exactToken || 0).toFixed(2)} symbolMatch=${(sig.symbolMatch || 0).toFixed(2)} prefixMatch=${(sig.prefixMatch || 0).toFixed(2)} pathMatch=${(sig.pathMatch || 0).toFixed(2)} penalty=${(sig.penalty || 1).toFixed(2)}`);
+        }
+        lines.push('```');
+        lines.push(...r.sigs.slice(0, 10));
         if (r.sigs.length > 10) lines.push(`... (${r.sigs.length - 10} more)`);
-        lines.push('```', '');
+        lines.push('```');
+        lines.push('');
       }
     }
+
     return lines.join('\n');
   }
+
+  /**
+   * Format ranked results as a structured JSON-serialisable object.
+   *
+   * @param {{ file: string, score: number, sigs: string[], tokens: number, intent: string, signals: object }[]} results
+   * @param {string} query
+   * @returns {object}
+   */
   function formatRankJSON(results, query) {
-    return { query, results: (results || []).map((r, i) => ({ rank: i + 1, file: r.file, score: r.score, sigs: r.sigs, tokens: r.tokens })), totalResults: (results || []).length };
+    const intent = (results && results[0] && results[0].intent) || 'search';
+    return {
+      query,
+      intent,
+      results: (results || []).map((r, i) => ({
+        rank: i + 1,
+        file: r.file,
+        score: r.score,
+        sigs: r.sigs,
+        tokens: r.tokens,
+        signals: r.signals || {},
+      })),
+      totalResults: (results || []).length,
+    };
   }
+
+  // ---------------------------------------------------------------------------
+  // Intent detection — 7 intents
+  // ---------------------------------------------------------------------------
   const INTENT_PATTERNS = {
     debug:    /\b(bug|fix|error|crash|exception|broken|failing|issue|problem|regression)\b/i,
-    explain:  /\b(explain|how does|what is|understand|overview|architecture|describe|walk me)\b/i,
-    refactor: /\b(refactor|restructure|redesign|clean up|extract|move|rename|simplify)\b/i,
-    review:   /\b(review|check|audit|security|pr|pull request|assess)\b/i,
+    explain:  /\b(explain|how does|what is|understand|overview|architecture|describe|walk me|teach)\b/i,
+    refactor: /\b(refactor|restructure|redesign|clean up|extract|move|rename|simplify|optimize)\b/i,
+    review:   /\b(review|check|audit|security|pr|pull request|assess|validate)\b/i,
+    test:     /\b(test|unit test|integration test|testing|spec|assert|mock)\b/i,
+    integrate:/\b(import|integrate|connect|wire|bind|require|export|depend|graph)\b|require[ds]\b/i,
+    navigate: /\b(find|locate|where|search|look for|show me|navigate|browse|list)\b/i,
   };
+
   function detectIntent(query) {
     if (!query || typeof query !== 'string') return 'search';
     for (const [intent, re] of Object.entries(INTENT_PATTERNS)) {
@@ -8094,9 +8770,10 @@ __factories["./src/retrieval/ranker"] = function(module, exports) {
     }
     return 'search';
   }
-  module.exports = { rank, buildSigIndex, scoreFile, formatRankTable, formatRankJSON, DEFAULT_WEIGHTS, detectIntent };
-};
 
+  module.exports = { rank, buildSigIndex, scoreFile, formatRankTable, formatRankJSON, DEFAULT_WEIGHTS, GRAPH_BOOST_AMOUNTS, detectIntent };
+  
+};
 // ── ./src/eval/scorer ──
 __factories["./src/eval/scorer"] = function(module, exports) {
   'use strict';
@@ -11499,7 +12176,7 @@ function __tryGit(args, opts = {}) {
   catch (_) { return ''; }
 }
 
-const VERSION = '7.2.1';
+const VERSION = '7.4.0';
 const MARKER = '\n\n## Auto-generated signatures\n<!-- Updated by gen-context.js -->\n';
 
 function requireSourceOrBundled(key) {