sigmap 6.5.0 → 6.5.1

package/AGENTS.md

@@ -47,6 +47,26 @@ Use this marker block for all appendable context files:
 <!-- Updated by gen-context.js -->
 # Code signatures
 
+## SigMap commands
+
+| When | Command |
+|------|---------|
+| Before answering a question | `sigmap ask "<your question>"` |
+| After code changes | `sigmap validate` |
+| To query by topic | `sigmap --query "<topic>"` |
+
+Always run `sigmap ask` or `sigmap --query` before searching for files relevant to a task.
+## changes (last 5 commits — 6 minutes ago)
+```
+src/config/loader.js                          +_legacyDetectAutoSrcDirs  ~detectAutoSrcDirs
+src/discovery/language-detector.js            +detectLanguages  +_walkDepth
+src/discovery/framework-detector.js           +detectFrameworks  +_readDeps  +_readFile  +_existsAnywhere
+src/discovery/source-root-resolver.js         +resolveSourceRoots  +_detectMonorepo  +_enumerateCandidates  +_applySpecialRules
+src/discovery/source-root-scorer.js           +getRecentlyChangedDirs  +scoreCandidate  +_countSourceFiles
+src/discovery/sigmapignore.js                 +loadIgnorePatterns  +matchesIgnorePattern
+src/retrieval/ranker.js                       +_computePenalty  ~scoreFile  ~rank  ~buildSigIndex
+```
+
 ## packages
 
 ### packages/cli/index.js
@@ -104,15 +124,7 @@ function score(cwd) → { * score: number, * grad
 function adapt(context, adapterName, opts = {}) → string
 ```
 
-### packages/adapters/codex.js
-```
-module.exports = { name, format, outputPath, write }
-function format(context, opts = {}) → string
-function outputPath(cwd) → string
-function write(context, cwd, opts = {})
-```
-
-### packages/adapters/claude.js
+### packages/adapters/copilot.js
 ```
 module.exports = { name, format, outputPath, write }
 function format(context, opts = {}) → string
@@ -121,13 +133,12 @@ function outputPath(cwd) → string
 function write(context, cwd, opts = {})
 ```
 
-### packages/adapters/copilot.js
+### packages/adapters/cursor.js
 ```
-module.exports = { name, format, outputPath, write }
+module.exports = { name, format, outputPath }
 function format(context, opts = {}) → string
 function _confidenceMeta(opts)
 function outputPath(cwd) → string
-function write(context, cwd, opts = {})
 ```
 
 ### packages/adapters/gemini.js
@@ -139,14 +150,6 @@ function write(context, cwd, opts = {})
 function _confidenceMeta(opts)
 ```
 
-### packages/adapters/cursor.js
-```
-module.exports = { name, format, outputPath }
-function format(context, opts = {}) → string
-function _confidenceMeta(opts)
-function outputPath(cwd) → string
-```
-
 ### packages/adapters/openai.js
 ```
 module.exports = { name, format, outputPath }
@@ -163,74 +166,24 @@ function _confidenceMeta(opts)
 function outputPath(cwd) → string
 ```
 
-## src
-
-### src/security/patterns.js
-```
-module.exports = { PATTERNS }
-```
-
-### src/security/scanner.js
-```
-module.exports = { scan }
-function scan(signatures, filePath) → { safe: string[], redacte
-```
-
-### src/extractors/cpp.js
-```
-module.exports = { extract }
-function extract(src) → string[]
-function extractBlock(src, startIndex)
-function extractMembers(block)
-function normalizeParams(params)
-function normalizeType(type)
-```
-
-### src/extractors/csharp.js
-```
-module.exports = { extract }
-function extract(src) → string[]
-function extractBlock(src, startIndex)
-function extractMembers(block)
-function normalizeParams(params)
-function normalizeType(type)
-```
-
-### src/extractors/dart.js
-```
-module.exports = { extract }
-function extract(src) → string[]
-function extractBlock(src, startIndex)
-function extractMembers(block)
-function normalizeParams(params)
-```
-
-### src/extractors/deps.js
+### packages/adapters/codex.js
 ```
-module.exports = { extractPythonDeps, extractTSDeps, buildReverseDepMap }
-function extractPythonDeps(src) → string[]
-function extractTSDeps(src) → string[]
-function buildReverseDepMap(forwardMap) → Map<string, string[]>
+module.exports = { name, format, outputPath, write }
+function format(context, opts = {}) → string
+function outputPath(cwd) → string
+function write(context, cwd, opts = {})
 ```
 
-### src/extractors/go.js
+### packages/adapters/claude.js
 ```
-module.exports = { extract }
-function extract(src) → string[]
-function extractBlock(src, startIndex)
-function extractInterfaceMethods(block)
-function normalizeParams(params)
+module.exports = { name, format, outputPath, write }
+function format(context, opts = {}) → string
+function _confidenceMeta(opts)
+function outputPath(cwd) → string
+function write(context, cwd, opts = {})
 ```
 
-### src/extractors/java.js
-```
-module.exports = { extract }
-function extract(src) → string[]
-function extractBlock(src, startIndex)
-function extractMembers(block)
-function normalizeParams(params)
-function normalizeType(type)
-```
+## src
 
 ### src/extractors/javascript.js
 ```
@@ -622,18 +575,6 @@ function queryContext(args, cwd)
 function getImpact(args, cwd)
 ```
 
-### src/retrieval/ranker.js
-```
-module.exports = { rank, buildSigIndex, scoreFile, formatRankTable, formatRankJSON, DEFAULT_WEIGHTS, detectIntent }
-function scoreFile(filePath, sigs, queryTokens, weights) → number
-function rank(query, sigIndex, opts) → { file: string, score: nu
-function _parseContextFile(contextPath) → Map<string, string[]>
-function buildSigIndex(cwd, opts) → Map<string, string[]>
-function formatRankTable(results, query) → string
-function formatRankJSON(results, query) → object
-function detectIntent(query)
-```
-
 ### src/tracking/logger.js
 ```
 module.exports = { logRun, readLog, summarize }
@@ -652,15 +593,6 @@ function extractClassMembers(block)
 function normalizeParams(params)
 ```
 
-### src/config/loader.js
-```
-module.exports = { loadConfig, loadBaseConfig }
-function loadBaseConfig(extendsVal, cwd)
-function detectAutoSrcDirs(cwd, excludeList) → string[]
-function loadConfig(cwd) → object
-function deepClone(obj)
-```
-
 ### src/learning/weights.js
 ```
 module.exports = { BASELINE, DECAY, MAX_MULT, MIN_MULT, weightsPath, clampMultiplier, normalizeFile, loadWeights, saveWeights, updateWeights, boostFiles, penalizeFiles, resetWeights, exportWeights, importWeights }
@@ -678,6 +610,77 @@ function exportWeights(cwd, outputPath)
 function importWeights(cwd, importPath, replace)
 ```
 
+### src/config/loader.js
+```
+module.exports = { loadConfig, loadBaseConfig }
+function loadBaseConfig(extendsVal, cwd)
+function detectAutoSrcDirs(cwd, excludeList) → string[]
+function _legacyDetectAutoSrcDirs(cwd, excludeList) → string[]
+function loadConfig(cwd) → object
+function deepClone(obj)
+```
+
+### src/discovery/language-detector.js
+```
+module.exports = { detectLanguages }
+function detectLanguages(cwd)
+function _walkDepth(dir, depth, extCount)
+```
+
+### src/discovery/framework-detector.js
+```
+module.exports = { detectFrameworks }
+function detectFrameworks(cwd)
+function _readDeps(cwd)
+function _readFile(p)
+function _existsAnywhere(cwd, filename, maxDepth)
+function _walkFind(dir, name, depth)
+```
+
+### src/discovery/source-root-registry.js
+```
+module.exports = { REGISTRY }
+```
+
+### src/discovery/source-root-resolver.js
+```
+module.exports = { resolveSourceRoots }
+function resolveSourceRoots(cwd, opts = {})
+function _detectMonorepo(cwd)
+function _enumerateCandidates(cwd, isMonorepo, ignorePatterns, excludeList)
+function _applySpecialRules(scored, cwd, primaryFw, fwEntry, frameworks)
+function _dedupeNested(scored)
+function _computeConfidence(frameworks, languages, scoredCount)
+```
+
+### src/discovery/source-root-scorer.js
+```
+module.exports = { scoreCandidate, getRecentlyChangedDirs, ROOT_ENTRYPOINTS }
+function getRecentlyChangedDirs(cwd)
+function scoreCandidate(dirName, fullPath, context)
+function _countSourceFiles(dir, depth)
+```
+
+### src/discovery/sigmapignore.js
+```
+module.exports = { loadIgnorePatterns, matchesIgnorePattern }
+function loadIgnorePatterns(cwd)
+function matchesIgnorePattern(dirName, patterns)
+```
+
+### src/retrieval/ranker.js
+```
+module.exports = { rank, buildSigIndex, scoreFile, formatRankTable, formatRankJSON, DEFAULT_WEIGHTS, detectIntent }
+function _computePenalty(filePath)
+function scoreFile(filePath, sigs, queryTokens, weights) → { score: number, signals:
+function rank(query, sigIndex, opts) → { file: string, score: nu
+function _parseContextFile(contextPath) → Map<string, string[]>
+function buildSigIndex(cwd, opts) → Map<string, string[]>
+function formatRankTable(results, query) → string
+function formatRankJSON(results, query) → object
+function detectIntent(query)
+```
+
 ### src/mcp/server.js
 ```
 module.exports = { start }

package/CHANGELOG.md

@@ -10,6 +10,21 @@ Format: [Semantic Versioning](https://semver.org/)
 
 ---
 
+## [6.5.1] — 2026-04-25
+
+### Added
+
+- **Retrieval explain** — `rank()` and `scoreFile()` now return detailed signal breakdown (exactToken, symbolMatch, prefixMatch, pathMatch, penalty) for transparency in ranking decisions
+- **7-intent ranking** — expanded intent detection from 4 to 7 patterns (debug, explain, refactor, review, test, integrate, navigate). Each intent applies tuned weights to prioritize relevant signals.
+- **Negative-signal penalty layer** — formalized penalties for test files (0.4x), generated code (0.3x), documentation (0.2x), and node_modules (0.0x) to deprioritize non-source content
+
+### Changed
+
+- `formatRankTable` now shows penalty column and signals breakdown for top 3 results
+- `formatRankJSON` now includes `intent` and `signals` fields in output for API consumers
+
+---
+
 ## [6.5.0] — 2026-04-25
 
 ### Added

package/README.md

@@ -38,7 +38,7 @@ Works with Copilot, Claude, Cursor, Windsurf, and any LLM.
 
 ## Why SigMap?
 
-- **78.9% hit@5** — right file found in top 5 results (vs 13.6% baseline)
+- **81.1% hit@5** — right file found in top 5 results (vs 13.6% baseline)
 - **40–98% token reduction** — 2K–4K tokens instead of 80K+
 - **52.2% task success rate** — up from 10% without context
 - **1.69 prompts per task** — down from 2.84
@@ -51,7 +51,7 @@ Works with Copilot, Claude, Cursor, Windsurf, and any LLM.
 
 | Without SigMap | With SigMap |
 |---|---|
-| ❌ Guessing which files are relevant | ✅ Right file in context — 79% of the time |
+| ❌ Guessing which files are relevant | ✅ Right file in context — 81% of the time |
 | ❌ Sending the full repo to your AI | ✅ Minimal context — only what matters |
 | ❌ Embeddings / vector DB required | ✅ Grounded answers, no infra needed |
 
@@ -75,11 +75,11 @@ Ask → Rank → Context → Validate → Judge → Learn
 ## Benchmark
 
 ```
-Benchmark : sigmap-v6.4-main
-Date      : 2026-04-23
+Benchmark : sigmap-v6.5-main
+Date      : 2026-04-25
 
-Hit@5          : 78.9%   (baseline 13.6%  — 5.8× lift)
-Prompt reduction : 40.6%
+Hit@5          : 81.1%   (baseline 13.6%  — 6.0× lift)
+Prompt reduction : 41.4%
 Task success   : 52.2%   (baseline 10%)
 Prompts / task : 1.69    (baseline 2.84)
 Token reduction: 40–98%  (avg 96.9% across 18 real repos)

package/gen-context.js

@@ -5387,7 +5387,7 @@ __factories["./src/mcp/server"] = function(module, exports) {
   
   const SERVER_INFO = {
     name: 'sigmap',
-  version: '6.5.0',
+  version: '6.5.1',
     description: 'SigMap MCP server — code signatures on demand',
   };
   
@@ -7222,7 +7222,7 @@ const path = require('path');
 const os = require('os');
 const { execSync } = require('child_process');
 
-const VERSION = '6.5.0';
+const VERSION = '6.5.1';
 const MARKER = '\n\n## Auto-generated signatures\n<!-- Updated by gen-context.js -->\n';
 
 function requireSourceOrBundled(key) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigmap",
-  "version": "6.5.0",
+  "version": "6.5.1",
   "description": "Zero-dependency AI context engine — 97% token reduction. No npm install. Runs on Node 18+.",
   "main": "gen-context.js",
   "exports": {

package/packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigmap-cli",
-  "version": "6.5.0",
+  "version": "6.5.1",
   "description": "SigMap CLI wrapper — thin adapter for programmatic CLI invocation",
   "main": "index.js",
   "keywords": [

package/packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigmap-core",
-  "version": "6.5.0",
+  "version": "6.5.1",
   "description": "SigMap core library — zero-dependency code signature extraction, retrieval, and security scanning",
   "main": "index.js",
   "keywords": [

package/src/mcp/server.js

@@ -18,7 +18,7 @@ const { readContext, searchSignatures, getMap, createCheckpoint, getRouting, exp
 
 const SERVER_INFO = {
   name: 'sigmap',
-  version: '6.5.0',
+  version: '6.5.1',
   description: 'SigMap MCP server — code signatures on demand',
 };
 

package/src/retrieval/ranker.js

@@ -32,19 +32,49 @@ const DEFAULT_WEIGHTS = {
   graphBoost: 0.4,       // additive bonus for 1-hop import neighbors of matching files
 };
 
+// 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;
+}
+
 /**
- * Score a single file against a query.
+ * 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 {number}
+ * @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 signals = { exactToken: 0, symbolMatch: 0, prefixMatch: 0, pathMatch: 0, penalty: _computePenalty(filePath) };
 
   // Build token set from all signatures
   const sigText = sigs.join(' ');
@@ -60,14 +90,19 @@ function scoreFile(filePath, sigs, queryTokens, weights) {
 
     // Exact token match in sigs
     if (sigTokenSet.has(qt)) {
-      score += w.exactToken;
+      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;
+      if (nameLineMatch) {
+        score += w.symbolMatch;
+        signals.symbolMatch += w.symbolMatch;
+      }
     }
 
     // Prefix match (e.g. query "python" matches "pythonDeps")
@@ -75,6 +110,7 @@ function scoreFile(filePath, sigs, queryTokens, weights) {
       for (const st of sigTokenSet) {
         if (st !== qt && st.startsWith(qt)) {
           score += w.prefixMatch;
+          signals.prefixMatch += w.prefixMatch;
           break; // one bonus per query token
         }
       }
@@ -83,10 +119,14 @@ function scoreFile(filePath, sigs, queryTokens, weights) {
     // 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 };
 }
 
 /**
@@ -101,7 +141,7 @@ function scoreFile(filePath, sigs, queryTokens, weights) {
  * @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 }[]}
+ * @returns {{ file: string, score: number, sigs: string[], tokens: number, intent: string, signals: object }[]}
  */
 function rank(query, sigIndex, opts) {
   if (!query || typeof query !== 'string') return [];
@@ -110,17 +150,21 @@ function rank(query, sigIndex, opts) {
   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 learnedWeights = opts && opts.cwd ? loadWeights(opts.cwd) : null;
   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) });
+      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);
@@ -128,15 +172,20 @@ function rank(query, sigIndex, opts) {
 
   const scored = [];
   for (const [file, sigs] of sigIndex.entries()) {
-    let score = scoreFile(file, sigs, queryTokens, weights);
+    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) {
-      score *= learnedWeights[file] || 1.0;
+      const multiplier = learnedWeights[file] || 1.0;
+      score *= multiplier;
+      signals.learnedWeights = multiplier;
     }
 
     scored.push({
@@ -144,6 +193,8 @@ function rank(query, sigIndex, opts) {
       score,
       sigs,
       tokens: Math.ceil(sigs.join('\n').length / 4),
+      intent,
+      signals,
     });
   }
 
@@ -166,6 +217,7 @@ function rank(query, sigIndex, opts) {
         const idx = relToIdx.get(neighborRel);
         if (idx !== undefined) {
           scored[idx].score += weights.graphBoost;
+          scored[idx].signals.graphBoost = (scored[idx].signals.graphBoost || 0) + weights.graphBoost;
         }
       }
     }
@@ -286,7 +338,7 @@ function buildSigIndex(cwd, opts) {
 /**
  * Format ranked results as a markdown table string.
  *
- * @param {{ file: string, score: number, sigs: string[], tokens: number }[]} results
+ * @param {{ file: string, score: number, sigs: string[], tokens: number, intent: string, signals: object }[]} results
  * @param {string} query
  * @returns {string}
  */
@@ -295,14 +347,17 @@ function formatRankTable(results, query) {
     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 | Tokens |',
-    '|------|------|-------|------|--------|',
-    ...results.map((r, i) =>
-      `| ${i + 1} | ${r.file} | ${r.score.toFixed(2)} | ${r.sigs.length} | ${r.tokens} |`
-    ),
+    '| 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} |`;
+    }),
     '',
   ];
 
@@ -310,6 +365,10 @@ function formatRankTable(results, query) {
   for (const r of results.slice(0, 3)) {
     if (r.sigs.length > 0) {
       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)`);
@@ -324,32 +383,38 @@ function formatRankTable(results, query) {
 /**
  * Format ranked results as a structured JSON-serialisable object.
  *
- * @param {{ file: string, score: number, sigs: string[], tokens: number }[]} results
+ * @param {{ file: string, score: number, sigs: string[], tokens: number, intent: string, signals: object }[]} results
  * @param {string} query
  * @returns {object}
  */
 function formatRankJSON(results, query) {
+  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
+// 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) {