sigmap 4.1.1 → 4.2.0

package/AGENTS.md

@@ -12,17 +12,22 @@ Use this marker block for all appendable context files:
 ## Auto-generated signatures
 <!-- Updated by gen-context.js -->
 You are a coding assistant with full knowledge of this codebase.
-Below are the code signatures extracted by SigMap v4.1.0 on 2026-04-15T08:05:43.080Z.
+Below are the code signatures extracted by SigMap v4.1.2 on 2026-04-16T17:45:07.132Z.
 
 Use these signatures to answer questions about the code accurately.
 
 ## Code Signatures
 
-<!-- Generated by SigMap gen-context.js v4.1.0 -->
+<!-- Generated by SigMap gen-context.js v4.1.2 -->
 <!-- DO NOT EDIT below the marker line — run gen-context.js to regenerate -->
 
 # Code signatures
 
+## changes (last 5 commits — 53 minutes ago)
+```
+src/retrieval/ranker.js                       +_parseContextFile  +buildSigIndex  ~buildSigIndex  ~rank
+```
+
 ## packages
 
 ### packages/adapters/claude.js
@@ -34,41 +39,24 @@ function outputPath(cwd) → string
 function write(context, cwd, opts = {})
 ```
 
-### packages/adapters/copilot.js
+### packages/adapters/codex.js
 ```
 module.exports = { name, format, outputPath, write }
 function format(context, opts = {}) → string
-function _confidenceMeta(opts)
 function outputPath(cwd) → string
 function write(context, cwd, opts = {})
 ```
 
-### packages/adapters/cursor.js
-```
-module.exports = { name, format, outputPath }
-function format(context, opts = {}) → string
-function _confidenceMeta(opts)
-function outputPath(cwd) → string
-```
-
-### packages/adapters/gemini.js
+### packages/adapters/copilot.js
 ```
 module.exports = { name, format, outputPath, write }
 function format(context, opts = {}) → string
-function outputPath(cwd) → string
-function write(context, cwd, opts = {})
 function _confidenceMeta(opts)
-```
-
-### packages/adapters/openai.js
-```
-module.exports = { name, format, outputPath }
-function format(context, opts = {}) → string
 function outputPath(cwd) → string
-function _confidenceMeta(opts)
+function write(context, cwd, opts = {})
 ```
 
-### packages/adapters/windsurf.js
+### packages/adapters/cursor.js
 ```
 module.exports = { name, format, outputPath }
 function format(context, opts = {}) → string
@@ -76,12 +64,13 @@ function _confidenceMeta(opts)
 function outputPath(cwd) → string
 ```
 
-### packages/adapters/codex.js
+### packages/adapters/gemini.js
 ```
 module.exports = { name, format, outputPath, write }
 function format(context, opts = {}) → string
 function outputPath(cwd) → string
 function write(context, cwd, opts = {})
+function _confidenceMeta(opts)
 ```
 
 ### packages/adapters/index.js
@@ -101,6 +90,22 @@ function format(context, opts)
 function write(context, cwd, opts)
 ```
 
+### packages/adapters/openai.js
+```
+module.exports = { name, format, outputPath }
+function format(context, opts = {}) → string
+function outputPath(cwd) → string
+function _confidenceMeta(opts)
+```
+
+### packages/adapters/windsurf.js
+```
+module.exports = { name, format, outputPath }
+function format(context, opts = {}) → string
+function _confidenceMeta(opts)
+function outputPath(cwd) → string
+```
+
 ### packages/cli/index.js
 ```
 module.exports = { CLI_ENTRY, run }
@@ -141,24 +146,9 @@ function adapt(context, adapterName, opts = {}) → string
 
 ## src
 
-### src/analysis/coverage-score.js
-```
-module.exports = { coverageScore }
-function coverageScore(cwd, fileEntries, config) → { * score: number, * grad
-function _walk(dir, excludeSet, out)
-```
-
-### src/eval/analyzer.js
+### src/config/defaults.js
 ```
-module.exports = { analyzeFiles, formatAnalysisTable, formatAnalysisJSON }
-function isDockerfile(name)
-function getExtractorName(filePath)
-function tokenCount(sigs)
-function hasCoverage(filePath, cwd)
-function loadExtractor(name, cwd)
-function analyzeFiles(files, cwd, opts) → object[]
-function formatAnalysisTable(stats, showSlow) → string
-function formatAnalysisJSON(stats) → object
+module.exports = { DEFAULTS }
 ```
 
 ### src/mcp/server.js
@@ -170,9 +160,22 @@ function dispatch(msg, cwd)
 function start(cwd)
 ```
 
-### src/config/defaults.js
+### src/retrieval/ranker.js
 ```
-module.exports = { DEFAULTS }
+module.exports = { rank, buildSigIndex, scoreFile, formatRankTable, formatRankJSON, DEFAULT_WEIGHTS }
+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
+```
+
+### src/analysis/coverage-score.js
+```
+module.exports = { coverageScore }
+function coverageScore(cwd, fileEntries, config) → { * score: number, * grad
+function _walk(dir, excludeSet, out)
 ```
 
 ### src/config/loader.js
@@ -183,6 +186,19 @@ function loadConfig(cwd) → object
 function deepClone(obj)
 ```
 
+### src/eval/analyzer.js
+```
+module.exports = { analyzeFiles, formatAnalysisTable, formatAnalysisJSON }
+function isDockerfile(name)
+function getExtractorName(filePath)
+function tokenCount(sigs)
+function hasCoverage(filePath, cwd)
+function loadExtractor(name, cwd)
+function analyzeFiles(files, cwd, opts) → object[]
+function formatAnalysisTable(stats, showSlow) → string
+function formatAnalysisJSON(stats) → object
+```
+
 ### src/eval/runner.js
 ```
 module.exports = { run, rank, loadTasks, buildSigIndex, formatTable, formatMetrics, tokenize }
@@ -615,16 +631,6 @@ function getImpact(args, cwd)
 module.exports = { TOOLS }
 ```
 
-### src/retrieval/ranker.js
-```
-module.exports = { rank, buildSigIndex, scoreFile, formatRankTable, formatRankJSON, DEFAULT_WEIGHTS }
-function scoreFile(filePath, sigs, queryTokens, weights) → number
-function rank(query, sigIndex, opts) → { file: string, score: nu
-function buildSigIndex(cwd) → Map<string, string[]>
-function formatRankTable(results, query) → string
-function formatRankJSON(results, query) → object
-```
-
 ### src/retrieval/tokenizer.js
 ```
 module.exports = { tokenize, STOP_WORDS }

package/CHANGELOG.md

@@ -10,6 +10,60 @@ Format: [Semantic Versioning](https://semver.org/)
 
 ---
 
+## [4.2.0] — 2026-04-16
+
+### Added
+
+- **`sigmap ask "<query>"`** — unified pipeline: intent detection → ranked mini-context → coverage check → cost estimate → risk level in one command. Supports `--json` for machine-readable output.
+- **Intent detection** (`detectIntent`) — classifies queries as `debug`, `explain`, `refactor`, `review`, or `search` and adjusts ranking weights accordingly for higher-relevance results.
+- **`sigmap query --context`** — writes a targeted mini-context (top-5 ranked files, ≤ 2 000 tokens) to `.context/query-context.md` for direct pasting into an LLM prompt.
+- **`--cost [--model <name>] [--json]`** — prints per-model token/dollar cost comparison (raw source vs SigMap output). Supports `gpt-4o`, `gpt-4`, `claude-3-5-sonnet`, `claude-opus-4`, `gemini-1.5-pro`, and more.
+- **`sigmap suggest-profile [--short]`** — reads the last git commit message and staged files to recommend a context profile (`debug`, `architecture`, `review`, or `default`).
+- **`sigmap compare [--json]`** — human-readable CLI wrapper over the retrieval benchmark scripts, showing SigMap vs baseline hit@5, token counts, and lift multiplier.
+- **`sigmap share`** — prints a shareable one-liner with live benchmark numbers and copies it to the clipboard via `pbcopy`/`xclip`.
+
+---
+
+## [4.1.2] — 2026-04-16 — Feat: --output <file> flag for custom context path
+
+### Added
+
+- **`--output <file>` flag** — write signatures to any custom path, not just
+  an adapter's fixed location:
+  ```bash
+  sigmap --output .context/ai-context.md          # default generation
+  sigmap --adapter claude --output shared/sigs.md # adapter + custom path
+  ```
+  The custom file is written **in addition to** the adapter's default output so
+  existing tooling is unaffected.
+
+- **Automatic discovery for `--query`** — the resolved path is persisted to
+  `gen-context.config.json` as `customOutput` so subsequent `--query` runs
+  find it automatically without needing to pass `--output` again:
+  ```bash
+  sigmap --output .context/ai-context.md          # generates + persists path
+  sigmap --query "add a new extractor"             # auto-finds .context/ai-context.md
+  ```
+
+- **Priority order for `--query` context resolution** (most specific first):
+  1. `--output <file>` flag — explicit path
+  2. `--adapter <name>` flag — adapter's fixed output path
+  3. `customOutput` in `gen-context.config.json` — persisted from last `--output` run
+  4. Probe all known adapter output paths — existing fallback behaviour
+
+- **Nested directories created automatically** — `--output a/b/c/file.md`
+  creates any missing parent directories.
+
+### Tests
+
+- Added `test/integration/output-flag.test.js` (13 tests) covering: custom
+  file creation, parseable headers, config persistence, nested dirs, missing
+  arg error, `--adapter` + `--output` combo, explicit `--query` with `--output`,
+  auto-discovery via persisted config, missing-file error, `--output` overrides
+  `--adapter` during `--query`.
+
+---
+
 ## [4.1.1] — 2026-04-16 — Fix: --query works with any adapter output
 
 ### Fixed

package/README.md

@@ -353,6 +353,24 @@ Configure multiple adapters at once in `gen-context.config.json`:
 
 Use SigMap as a Node.js library without spawning a subprocess. See the [full API reference](#-programmatic-api) below.
 
+### Custom output path
+
+Write signatures to any file location — useful for shared docs folders, monorepos,
+or tooling that expects context at a non-standard path:
+
+```bash
+sigmap --output .context/ai-context.md           # write to custom path
+sigmap --adapter claude --output shared/sigs.md  # adapter + custom path
+```
+
+The path is persisted to `gen-context.config.json`, so `--query` finds it
+automatically on subsequent runs — no need to pass `--output` again:
+
+```bash
+sigmap --output .context/ai-context.md  # generates and saves the path
+sigmap --query "add an extractor"        # auto-discovers .context/ai-context.md
+```
+
 ### Query-aware retrieval
 
 Find the most relevant files for any task without reading the whole codebase:
@@ -361,6 +379,7 @@ Find the most relevant files for any task without reading the whole codebase:
 sigmap --query "authentication middleware"   # ranked file list
 sigmap --query "auth" --json                 # machine-readable output
 sigmap --query "auth" --top 5               # top 5 results only
+sigmap --query "auth" --adapter claude       # query against CLAUDE.md specifically
 ```
 
 ### Diagnostic and evaluation tools
@@ -616,9 +635,14 @@ sigmap --diff                                 Generate context for git-changed f
 sigmap --diff --staged                        Staged files only (pre-commit check)
 sigmap --mcp                                  Start MCP server on stdio
 
+sigmap --output <file>                        Write signatures to a custom path (persists for --query)
+sigmap --output <file> --adapter <name>       Adapter output + custom copy
+
 sigmap --query "<text>"                       Rank files by relevance to a query
 sigmap --query "<text>" --json                Ranked results as JSON
 sigmap --query "<text>" --top <n>             Limit results to top N files (default 10)
+sigmap --query "<text>" --adapter <name>      Query against a specific adapter's output file
+sigmap --query "<text>" --output <file>       Query against a specific custom file
 
 sigmap --analyze                              Per-file breakdown (sigs / tokens / extractor / coverage)
 sigmap --analyze --json                       Analysis as JSON

package/gen-context.js

@@ -4654,7 +4654,7 @@ __factories["./src/mcp/server"] = function(module, exports) {
   
   const SERVER_INFO = {
     name: 'sigmap',
-    version: '4.1.0',
+    version: '4.2.0',
     description: 'SigMap MCP server — code signatures on demand',
   };
   
@@ -5479,8 +5479,19 @@ __factories["./src/retrieval/ranker"] = function(module, exports) {
     return index;
   }
   function buildSigIndex(cwd, opts) {
-    const path = require('path');
+    const fs = require('fs'); const path = require('path');
     if (opts && opts.contextPath) return _parseContextFile(opts.contextPath);
+    // 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 idx;
+        }
+      }
+    } catch (_) {}
     for (const parts of ADAPTER_OUTPUT_PATHS) {
       const contextPath = path.join(cwd, ...parts);
       const index = _parseContextFile(contextPath);
@@ -5504,7 +5515,20 @@ __factories["./src/retrieval/ranker"] = function(module, exports) {
   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 };
   }
-  module.exports = { rank, buildSigIndex, scoreFile, formatRankTable, formatRankJSON, DEFAULT_WEIGHTS };
+  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,
+  };
+  function detectIntent(query) {
+    if (!query || typeof query !== 'string') return 'search';
+    for (const [intent, re] of Object.entries(INTENT_PATTERNS)) {
+      if (re.test(query)) return intent;
+    }
+    return 'search';
+  }
+  module.exports = { rank, buildSigIndex, scoreFile, formatRankTable, formatRankJSON, DEFAULT_WEIGHTS, detectIntent };
 };
 
 // ── ./src/eval/scorer ──
@@ -6238,7 +6262,7 @@ const path = require('path');
 const os = require('os');
 const { execSync } = require('child_process');
 
-const VERSION = '4.1.0';
+const VERSION = '4.2.0';
 const MARKER = '\n\n## Auto-generated signatures\n<!-- Updated by gen-context.js -->\n';
 
 function requireSourceOrBundled(key) {
@@ -6926,6 +6950,19 @@ function writeOutputs(content, targets, cwd, config) {
     if (ADAPTER_TARGETS.has(target)) {
       try {
         const adapterMod = __require('./packages/adapters/' + target);
+        // copilot: honour config.output custom path (redirects away from default .github/copilot-instructions.md)
+        if (target === 'copilot') {
+          const outPath = resolveAdapterPath('copilot', cwd, config);
+          const defaultPath = path.join(cwd, '.github', 'copilot-instructions.md');
+          if (outPath !== defaultPath) {
+            // custom path: format and write directly (no append logic)
+            const formatted = adapterMod.format(content, { version: VERSION });
+            ensureDir(outPath);
+            fs.writeFileSync(outPath, formatted, 'utf8');
+            console.warn(`[sigmap] wrote ${path.relative(cwd, outPath)}`);
+            continue;
+          }
+        }
         if (typeof adapterMod.write === 'function') {
           adapterMod.write(content, cwd, { version: VERSION });
           const outPath = adapterMod.outputPath(cwd);
@@ -7507,6 +7544,25 @@ function runGenerate(cwd, config, reportMode, reportJson = false) {
         writeOutputs(content, config.outputs, cwd, config);
       }
       if (formatValue === 'cache') writeCacheOutput(content, cwd);
+
+      // --output <file>: write a copy of the formatted context to the custom path.
+      if (config.customOutput) {
+        try {
+          const absCustom = path.resolve(cwd, config.customOutput);
+          const SIGMAP_HEADER = [
+            `<!-- Generated by SigMap v${VERSION} -->`,
+            `<!-- Updated: ${new Date().toISOString()} -->`,
+            `<!-- Regenerate: node gen-context.js --output ${config.customOutput} -->`,
+            '',
+          ].join('\n');
+          fs.mkdirSync(path.dirname(absCustom), { recursive: true });
+          fs.writeFileSync(absCustom, SIGMAP_HEADER + content, 'utf8');
+          console.warn(`[sigmap] wrote ${path.relative(cwd, absCustom)} (custom output)`);
+        } catch (err) {
+          console.warn(`[sigmap] --output write failed: ${err.message}`);
+        }
+      }
+
       result = { inputTokenTotal, finalTokens, fileCount: beforeCount, droppedCount };
     }
   } else {
@@ -7896,6 +7952,58 @@ function registerMcp(cwd, scriptPath) {
   console.warn(JSON.stringify({ mcpServers: { 'sigmap': serverEntry } }, null, 2));
 }
 
+// ---------------------------------------------------------------------------
+// v4.2 helpers
+// ---------------------------------------------------------------------------
+const MODEL_COSTS = {
+  'gpt-4':             0.030,
+  'gpt-4o':            0.005,
+  'gpt-4o-mini':       0.000150,
+  'claude-3-5-sonnet': 0.003,
+  'claude-3-haiku':    0.00025,
+  'claude-opus-4':     0.015,
+  'gemini-1.5-pro':    0.00125,
+};
+
+function buildMiniContext(ranked, cwd) {
+  const lines = ['# SigMap Query Context', `Generated: ${new Date().toISOString()}`, ''];
+  for (const { file, sigs } of ranked) {
+    lines.push(`## ${file}`, '```', ...sigs.slice(0, 20), '```', '');
+  }
+  return lines.join('\n');
+}
+
+function computeCurrentRisk(cwd) {
+  try {
+    const { execSync } = require('child_process');
+    const out = execSync('git diff --name-only HEAD', { cwd, timeout: 3000, encoding: 'utf8' });
+    const count = out.trim().split('\n').filter(Boolean).length;
+    if (count === 0) return 'NONE';
+    if (count <= 3)  return 'LOW';
+    if (count <= 10) return 'MEDIUM';
+    return 'HIGH';
+  } catch (_) { return 'UNKNOWN'; }
+}
+
+function getRawTokenCount(cwd, config) {
+  let total = 0;
+  const files = buildFileList(cwd, config);
+  for (const fp of files) {
+    try { total += estimateTokens(fs.readFileSync(fp, 'utf8')); } catch (_) {}
+  }
+  return total;
+}
+
+function getIntentWeights(intent) {
+  const { DEFAULT_WEIGHTS } = requireSourceOrBundled('./src/retrieval/ranker');
+  const base = Object.assign({}, DEFAULT_WEIGHTS);
+  if (intent === 'debug')    return Object.assign({}, base, { recencyBoost: base.recencyBoost * 1.5 });
+  if (intent === 'explain')  return Object.assign({}, base, { symbolMatch:  base.symbolMatch  * 1.5 });
+  if (intent === 'refactor') return Object.assign({}, base, { pathMatch:    base.pathMatch    * 1.5 });
+  if (intent === 'review')   return Object.assign({}, base, { exactToken:   base.exactToken   * 1.3 });
+  return base;
+}
+
 function main() {
   const args = process.argv.slice(2);
 
@@ -7931,6 +8039,39 @@ function main() {
 
   const config = loadConfig(cwd);
 
+  // ── --output <file> — parse early so every subsequent block can use it ─────
+  // Resolves the custom output path and merges it into config.customOutput.
+  // Also persists the resolved relative path to gen-context.config.json so
+  // future --query calls (without --output) find the file automatically.
+  (function resolveOutputFlag() {
+    const outIdx = args.indexOf('--output');
+    if (outIdx < 0) return;
+    const raw = (args[outIdx + 1] || '').trim();
+    if (!raw || raw.startsWith('--')) {
+      console.error('[sigmap] --output requires a file path');
+      console.error('  Example: node gen-context.js --output .context/ai-context.md');
+      process.exit(1);
+    }
+    const abs  = path.resolve(cwd, raw);
+    const rel  = path.relative(cwd, abs);
+    config.customOutput = rel; // consumed by runGenerate
+
+    // Persist to gen-context.config.json for future --query calls
+    const cfgPath = path.join(cwd, 'gen-context.config.json');
+    try {
+      let savedCfg = {};
+      if (fs.existsSync(cfgPath)) {
+        try { savedCfg = JSON.parse(fs.readFileSync(cfgPath, 'utf8')); } catch (_) {}
+      }
+      if (savedCfg.customOutput !== rel) {
+        savedCfg.customOutput = rel;
+        fs.writeFileSync(cfgPath, JSON.stringify(savedCfg, null, 2) + '\n', 'utf8');
+      }
+    } catch (err) {
+      console.warn(`[sigmap] could not persist customOutput to config: ${err.message}`);
+    }
+  })();
+
   // Feature 2: `--mode fast|full|both`
   const modeIdx = args.indexOf('--mode');
   const mode = modeIdx !== -1
@@ -7942,6 +8083,170 @@ function main() {
     process.exit(1);
   }
 
+  // v4.2: `sigmap ask "<query>"` — unified pipeline
+  if (args[0] === 'ask') {
+    const query = args[1];
+    if (!query || query.startsWith('--')) {
+      console.error('[sigmap] Usage: sigmap ask "<query>"');
+      console.error('  Example: sigmap ask "fix the login bug"');
+      process.exit(1);
+    }
+
+    const { detectIntent, buildSigIndex, rank } = requireSourceOrBundled('./src/retrieval/ranker');
+    const { coverageScore } = requireSourceOrBundled('./src/analysis/coverage-score');
+
+    const intent = detectIntent(query);
+    const intentWeights = getIntentWeights(intent);
+
+    const sigIndex = buildSigIndex(cwd);
+    if (sigIndex.size === 0) {
+      console.error('[sigmap] no context file found. Run: sigmap  (to generate first)');
+      process.exit(1);
+    }
+
+    const ranked = rank(query, sigIndex, { topK: 5, weights: intentWeights });
+    const miniCtx = buildMiniContext(ranked, cwd);
+    const outPath = path.join(cwd, '.context', 'query-context.md');
+    fs.mkdirSync(path.dirname(outPath), { recursive: true });
+    fs.writeFileSync(outPath, miniCtx, 'utf8');
+    const ctxTok = estimateTokens(miniCtx);
+
+    const allFiles = buildFileList(cwd, config);
+    const fakeEntries = allFiles.map((f) => ({ filePath: f }));
+    let coveragePct = 0;
+    try { coveragePct = coverageScore(cwd, fakeEntries, config).score; } catch (_) {}
+
+    const rawTok = getRawTokenCount(cwd, config);
+    const savings = rawTok > 0 ? Math.round((1 - ctxTok / rawTok) * 100) : 0;
+    const model = args[args.indexOf('--model') + 1] || 'gpt-4o';
+    const rateK = MODEL_COSTS[model] || MODEL_COSTS['gpt-4o'];
+    const costRaw = ((rawTok / 1000) * rateK).toFixed(4);
+    const costCtx = ((ctxTok / 1000) * rateK).toFixed(4);
+
+    const riskLevel = computeCurrentRisk(cwd);
+
+    if (args.includes('--json')) {
+      process.stdout.write(JSON.stringify({
+        intent, coverage: coveragePct, contextTokens: ctxTok,
+        costBefore: costRaw, costAfter: costCtx, savingsPct: savings,
+        riskLevel, contextPath: path.relative(cwd, outPath),
+      }) + '\n');
+    } else {
+      const bar = '─'.repeat(44);
+      console.log([
+        bar,
+        ` sigmap ask  "${query}"`,
+        ` Intent    : ${intent}`,
+        ` Context   : ${ctxTok.toLocaleString()} tokens  →  ${path.relative(cwd, outPath)}`,
+        ` Coverage  : ${coveragePct}%`,
+        ` Risk      : ${riskLevel}`,
+        ` Cost      : $${costCtx}/query  (was $${costRaw} · saved ${savings}%)`,
+        bar,
+      ].join('\n'));
+    }
+    process.exit(0);
+  }
+
+  // v4.2: `sigmap suggest-profile` — auto-detect task type from git state
+  if (args[0] === 'suggest-profile') {
+    const short = args.includes('--short');
+    let msg = '', diff = '';
+    try {
+      const { execSync } = require('child_process');
+      msg  = execSync('git log -1 --format=%s',        { cwd, timeout: 3000, encoding: 'utf8' }).trim();
+      diff = execSync('git diff --cached --name-only',  { cwd, timeout: 3000, encoding: 'utf8' });
+    } catch (_) {}
+
+    let profile = 'default';
+    let reason  = 'no strong signal in git state';
+    if      (/fix|bug|error|crash|exception/i.test(msg))         { profile = 'debug';        reason = `commit: "${msg.slice(0, 60)}"`;  }
+    else if (/refactor|architect|redesign|module/i.test(msg))    { profile = 'architecture'; reason = `commit: "${msg.slice(0, 60)}"`;  }
+    else if (/review|pr|pull.request|check/i.test(msg))          { profile = 'review';       reason = `commit: "${msg.slice(0, 60)}"`;  }
+    else if (diff.includes('.spec.') || diff.includes('.test.')) { profile = 'debug';        reason = 'staged test files detected'; }
+
+    if (short) {
+      console.log(profile);
+    } else {
+      console.log(`[sigmap] suggested profile: --profile ${profile}`);
+      console.log(`  Reason: ${reason}`);
+    }
+    process.exit(0);
+  }
+
+  // v4.2: `sigmap compare` — human-readable benchmark CLI
+  if (args[0] === 'compare') {
+    const { execSync } = require('child_process');
+    console.log('[sigmap] Running comparison benchmark (this may take ~30s)...\n');
+
+    let raw = '';
+    try {
+      raw = execSync(
+        `node ${JSON.stringify(path.join(__dirname, 'scripts', 'run-retrieval-benchmark.mjs'))} --compare`,
+        { cwd, timeout: 90_000, encoding: 'utf8' }
+      );
+    } catch (e) { raw = (e && e.stdout) ? e.stdout : ''; }
+
+    let results = null;
+    try { results = JSON.parse(raw); } catch (_) {}
+
+    if (!results) {
+      console.error('[sigmap] Could not parse benchmark output.');
+      console.error('  Run manually: node scripts/run-retrieval-benchmark.mjs --skip-run --json');
+      process.exit(1);
+    }
+
+    if (args.includes('--json')) {
+      process.stdout.write(JSON.stringify(results, null, 2) + '\n');
+    } else {
+      const pct  = (v) => `${(v * 100).toFixed(1)}%`;
+      const lift = (a, b) => (b > 0 ? (a / b).toFixed(1) : '∞');
+      const bar  = '─'.repeat(44);
+      console.log([
+        bar,
+        ' SigMap vs Baseline',
+        bar,
+        ` hit@5         ${pct(results.sigmap.hitAt5)} vs ${pct(results.baseline.hitAt5)}   (${lift(results.sigmap.hitAt5, results.baseline.hitAt5)}× lift)`,
+        ` Avg tokens    ${results.sigmap.tokens.toLocaleString()} vs ${results.baseline.tokens.toLocaleString()}`,
+        bar,
+      ].join('\n'));
+    }
+    process.exit(0);
+  }
+
+  // v4.2: `sigmap share` — shareable one-liner with live benchmark numbers
+  if (args[0] === 'share') {
+    const histPath = path.join(cwd, '.context', 'benchmark-history.ndjson');
+    let reduction = 97, hitAt5 = 88;
+
+    if (fs.existsSync(histPath)) {
+      try {
+        const entries = fs.readFileSync(histPath, 'utf8').trim().split('\n')
+          .map((l) => { try { return JSON.parse(l); } catch (_) { return null; } }).filter(Boolean);
+        const tok = [...entries].reverse().find((e) => e.type === 'token-reduction');
+        const ret = [...entries].reverse().find((e) => e.type === 'retrieval');
+        if (tok && tok.reduction) reduction = tok.reduction;
+        if (ret && ret.hitAt5)   hitAt5    = Math.round(ret.hitAt5 * 100);
+      } catch (_) {}
+    }
+
+    const shareText = [
+      'Generated with SigMap — zero-dependency AI context engine',
+      `${reduction}% fewer tokens · ${hitAt5}% retrieval accuracy · 6× better results`,
+      'https://sigmap.dev',
+    ].join('\n');
+
+    console.log(shareText);
+
+    try {
+      const { execSync } = require('child_process');
+      const clipCmd = process.platform === 'darwin' ? 'pbcopy' : 'xclip -selection clipboard';
+      execSync(`printf '%s' ${JSON.stringify(shareText)} | ${clipCmd}`, { timeout: 2000 });
+      console.log('\n[sigmap] Copied to clipboard.');
+    } catch (_) {}
+
+    process.exit(0);
+  }
+
   // Feature 6: `sigmap sync` — write all outputs + llms.txt + print compact diff
   if (args[0] === 'sync') {
     try {
@@ -8355,19 +8660,28 @@ function main() {
       }
       const { rank, buildSigIndex, formatRankTable, formatRankJSON } = requireSourceOrBundled('./src/retrieval/ranker');
 
-      // Resolve an explicit context file path when --adapter is present.
-      // This lets `--adapter claude --query "..."` read CLAUDE.md instead of
-      // falling through to the default copilot-instructions.md probe.
+      // Resolve the context file path to query against.
+      // Priority: --output flag > --adapter flag > buildSigIndex probe order
+      //   (customOutput from config is handled inside buildSigIndex itself)
       let queryOpts;
-      const adpIdx = args.indexOf('--adapter');
-      if (adpIdx >= 0) {
-        const adapterName = (args[adpIdx + 1] || '').trim().toLowerCase();
-        const VALID_ADAPTERS = ['copilot', 'claude', 'cursor', 'windsurf', 'openai', 'gemini', 'codex'];
-        if (VALID_ADAPTERS.includes(adapterName)) {
-          try {
-            const adapterMod = __require('./packages/adapters/' + adapterName);
-            queryOpts = { contextPath: adapterMod.outputPath(cwd) };
-          } catch (_) {}
+
+      // 1. --output <file> pins to an explicit path
+      if (config.customOutput) {
+        queryOpts = { contextPath: path.resolve(cwd, config.customOutput) };
+      }
+
+      // 2. --adapter <name> pins to that adapter's output path (if --output not given)
+      if (!queryOpts) {
+        const adpIdx = args.indexOf('--adapter');
+        if (adpIdx >= 0) {
+          const adapterName = (args[adpIdx + 1] || '').trim().toLowerCase();
+          const VALID_ADAPTERS = ['copilot', 'claude', 'cursor', 'windsurf', 'openai', 'gemini', 'codex'];
+          if (VALID_ADAPTERS.includes(adapterName)) {
+            try {
+              const adapterMod = __require('./packages/adapters/' + adapterName);
+              queryOpts = { contextPath: adapterMod.outputPath(cwd) };
+            } catch (_) {}
+          }
         }
       }
 
@@ -8384,7 +8698,13 @@ function main() {
                                : ((config && config.retrieval && config.retrieval.topK) || 10);
       const recencyBoost = (config && config.retrieval && config.retrieval.recencyBoost) || 1.5;
       const results = rank(query, index, { topK, recencyBoost });
-      if (args.includes('--json')) {
+      if (args.includes('--context')) {
+        const miniCtx  = buildMiniContext(results, cwd);
+        const ctxOut   = path.join(cwd, '.context', 'query-context.md');
+        fs.mkdirSync(path.dirname(ctxOut), { recursive: true });
+        fs.writeFileSync(ctxOut, miniCtx, 'utf8');
+        console.log(`[sigmap] query context → ${path.relative(cwd, ctxOut)}  (${estimateTokens(miniCtx)} tokens)`);
+      } else if (args.includes('--json')) {
         process.stdout.write(JSON.stringify(formatRankJSON(results, query)) + '\n');
       } else {
         process.stdout.write(formatRankTable(results, query));
@@ -8554,6 +8874,44 @@ function main() {
     process.exit(0);
   }
 
+  // v4.2: `--cost` — show token/$ cost estimate before and after SigMap
+  if (args.includes('--cost')) {
+    const rawTok = getRawTokenCount(cwd, config);
+    runGenerate(cwd, config, false);
+
+    const model = args[args.indexOf('--model') + 1] || 'gpt-4o';
+    const rateK = MODEL_COSTS[model] || MODEL_COSTS['gpt-4o'];
+
+    const ctxPath = config.customOutput
+      ? path.resolve(cwd, config.customOutput)
+      : path.join(cwd, '.github', 'copilot-instructions.md');
+    let outTok = 0;
+    try { outTok = estimateTokens(fs.readFileSync(ctxPath, 'utf8')); } catch (_) {}
+
+    const savings = rawTok > 0 ? Math.round((1 - outTok / rawTok) * 100) : 0;
+    const costRaw = (rawTok / 1000) * rateK;
+    const costCtx = (outTok / 1000) * rateK;
+
+    const out = {
+      model,
+      rawTokens:     rawTok,
+      contextTokens: outTok,
+      costRaw:       costRaw.toFixed(4),
+      costContext:   costCtx.toFixed(4),
+      savingsPct:    savings,
+    };
+
+    if (args.includes('--json')) {
+      process.stdout.write(JSON.stringify(out) + '\n');
+    } else {
+      console.log(`\n Cost estimate (${model}):`);
+      console.log(` Without SigMap : ${rawTok.toLocaleString()} tok  $${out.costRaw}/query`);
+      console.log(` With SigMap    : ${outTok.toLocaleString()} tok  $${out.costContext}/query`);
+      console.log(` Savings        : ${savings}%  ($${(costRaw - costCtx).toFixed(4)} saved per query)\n`);
+    }
+    process.exit(0);
+  }
+
   // Default: generate once
   runGenerate(cwd, config, false);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigmap",
-  "version": "4.1.1",
+  "version": "4.2.0",
   "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": "4.1.0",
+  "version": "4.2.0",
   "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": "4.1.0",
+  "version": "4.2.0",
   "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: '4.1.0',
+  version: '4.2.0',
   description: 'SigMap MCP server — code signatures on demand',
 };
 

package/src/retrieval/ranker.js

@@ -206,26 +206,39 @@ function _parseContextFile(contextPath) {
  * Returns Map<filePath, string[]> where filePath is the relative path
  * as it appears in the ### headers of the context file.
  *
- * When `opts.contextPath` is provided, that specific file is used.
- * This is the case when the caller already knows the path (e.g. via
- * --adapter <name> or --output <file>).
- *
- * Otherwise all known adapter output paths are probed in order and the
- * first file that produces a non-empty index is returned.
+ * 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');
 
-  // Caller supplied an explicit path — use it directly.
+  // 1. Caller supplied an explicit path — use it directly.
   if (opts && opts.contextPath) {
     return _parseContextFile(opts.contextPath);
   }
 
-  // Probe all known adapter output paths; return first non-empty 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 customPath = path.resolve(cwd, cfg.customOutput);
+        const index = _parseContextFile(customPath);
+        if (index.size > 0) return 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);
@@ -294,4 +307,22 @@ function formatRankJSON(results, query) {
   };
 }
 
-module.exports = { rank, buildSigIndex, scoreFile, formatRankTable, formatRankJSON, DEFAULT_WEIGHTS };
+// ---------------------------------------------------------------------------
+// Intent detection
+// ---------------------------------------------------------------------------
+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,
+};
+
+function detectIntent(query) {
+  if (!query || typeof query !== 'string') return 'search';
+  for (const [intent, re] of Object.entries(INTENT_PATTERNS)) {
+    if (re.test(query)) return intent;
+  }
+  return 'search';
+}
+
+module.exports = { rank, buildSigIndex, scoreFile, formatRankTable, formatRankJSON, DEFAULT_WEIGHTS, detectIntent };