sigmap 7.27.0 → 7.29.0

package/CHANGELOG.md

@@ -10,6 +10,30 @@ Format: [Semantic Versioning](https://semver.org/)
 
 ---
 
+## [7.29.0] — 2026-06-23
+
+Minor release — **v8.0 E4:** one-command, per-client MCP install so a cold user reaches a working MCP setup fast (the v8.0 <5-minute-quickstart exit gate).
+
+### Added
+- **`sigmap mcp install <client>` (#385):** targeted MCP wiring for a single client — `claude`, `cursor`, `windsurf`, `vscode`, `zed`, `codex`, `gemini`, `opencode`, or portable `mcp` (`.mcp.json`). Unlike `sigmap --setup` (which wires *every* editor at once and only updates configs that already exist), this **creates** the config dir/file when absent, is idempotent (re-running reports already-registered, never duplicates), and emits the correct shape per client — `mcpServers` JSON, Zed `context_servers`, or Codex YAML. `--global` selects the user-level config for clients that have both a project and a global scope (Windsurf, OpenCode). Composed in the zero-dep `src/mcp/install.js` — no system-shell spawns, no install scripts.
+- **`sigmap mcp list` (#385):** lists every supported MCP client and its resolved config path (`--json` for a machine-readable array).
+
+### Changed
+- Regenerated `llms-full.txt` so the published surface lists the new `mcp install`/`mcp list` commands.
+
+### Fixed
+- Hardened two `--ci --min-coverage` integration tests (#385) that were order- and environment-dependent — they hard-coded an "unreachable" 99% threshold, but once the suite generates a full `src/` context the repo's measured coverage reaches 99–100%. They now pin the threshold relative to the actual measured coverage, so the gate-fails-above-achievable property holds deterministically everywhere.
+
+## [7.28.0] — 2026-06-23
+
+Minor release — **v8.0 E3:** a one-shot setup doctor so a cold user reaches a useful answer fast.
+
+### Added
+- **`sigmap doctor` (#381):** a one-shot diagnostic that runs seven resilient checks — git repository, config & source roots, generated context file, signature index, index freshness, coverage, and MCP wiring — and prints an **actionable fix** for anything wrong (e.g. "run: npx sigmap", "run: sigmap --setup", "increase maxTokens or expand srcDirs"). `sigmap doctor --json` emits `{ checks, ok, errors, warnings }`; the command exits **1** on a hard failure (no context file / invalid config) and **0** otherwise, so it is usable in CI. Composed from `loadConfig`, `coverageScore`, `buildSigIndex`, and the known adapter-output / MCP-config paths — zero new runtime dependencies, no system-shell spawns.
+
+### Changed
+- **Release CI self-heals `develop` (#380):** the develop→main release PR's head branch is `develop`, which the repo's delete-branch-on-merge setting removes on every release; the "Sync develop with main" workflow now fetches `main` and recreates `develop` from it when the ref is missing (else merges `main` in), so `develop` no longer needs manual restoration after a release.
+
 ## [7.27.0] — 2026-06-22
 
 Minor release — **v8.0 D3:** two new MCP tools, taking the server from 15 to 17 tools. Both are composed from data SigMap already computes — zero new runtime dependencies, no system-shell spawns.

package/README.md

@@ -91,8 +91,8 @@ Ask → Rank → Context → Validate → Judge → Learn
 
 <!--SM:benchmarkBlock-->
 ```
-Benchmark : sigmap-v7.27-main (21 repositories, including R language)
-Date      : 2026-06-22
+Benchmark : sigmap-v7.29-main (21 repositories, including R language)
+Date      : 2026-06-23
 
 Hit@5          : 75.6%   (baseline 13.6%  — 5.6× lift)
 Token reduction: 97.0%   (across 21 repos)

package/gen-context.js

@@ -3462,6 +3462,246 @@ __factories["./src/discovery/source-root-scorer"] = function(module, exports) {
   
 };
 
+// ── ./src/doctor/diagnose ──
+__factories["./src/doctor/diagnose"] = function(module, exports) {
+  
+  /**
+   * sigmap doctor (v8.0 E3).
+   *
+   * One-shot diagnostic for a SigMap setup: each check reports ok/warn/fail with
+   * an actionable fix, so a cold user can reach a useful answer in minutes. Pure,
+   * resilient (no check ever throws), zero new runtime deps. Composes the config
+   * loader, coverage scorer, signature index, and the known adapter-output /
+   * MCP-config paths.
+   */
+
+  const fs = require('fs');
+  const path = require('path');
+  const os = require('os');
+
+  // Generated context files a `read_context`/`ask` flow can consume.
+  const ADAPTER_OUTPUTS = [
+    ['.github', 'copilot-instructions.md'],
+    ['CLAUDE.md'],
+    ['AGENTS.md'],
+    ['.cursorrules'],
+    ['.windsurfrules'],
+    ['.github', 'openai-context.md'],
+    ['.github', 'gemini-context.md'],
+    ['llm-full.txt'],
+    ['llm.txt'],
+  ];
+
+  const EXCLUDE_DIRS = new Set([
+    'node_modules', '.git', 'dist', 'build', 'out', '__pycache__',
+    '.next', 'coverage', 'target', 'vendor', '.context',
+  ]);
+
+  const ICON = { ok: '✓', warn: '⚠', fail: '✗' };
+
+  function _short(p, cwd) {
+    const rel = path.relative(cwd, p);
+    return rel && !rel.startsWith('..') ? rel : p.replace(os.homedir(), '~');
+  }
+
+  function _contextFiles(cwd) {
+    const out = [];
+    for (const parts of ADAPTER_OUTPUTS) {
+      const p = path.join(cwd, ...parts);
+      try { if (fs.existsSync(p)) out.push(p); } catch (_) {}
+    }
+    return out;
+  }
+
+  function _mcpTargets(cwd) {
+    return [
+      path.join(cwd, '.mcp.json'),
+      path.join(cwd, '.claude', 'settings.json'),
+      path.join(cwd, '.cursor', 'mcp.json'),
+      path.join(cwd, '.windsurf', 'mcp.json'),
+      path.join(cwd, '.vscode', 'mcp.json'),
+      path.join(cwd, 'opencode.json'),
+      path.join(os.homedir(), '.codeium', 'windsurf', 'mcp_config.json'),
+      path.join(os.homedir(), '.config', 'opencode', 'config.json'),
+      path.join(os.homedir(), '.gemini', 'settings.json'),
+      path.join(os.homedir(), '.codex', 'config.yaml'),
+      path.join(os.homedir(), '.config', 'zed', 'settings.json'),
+    ];
+  }
+
+  /** Count code files under srcDirs modified after the context was generated. */
+  function _countChangedSince(cwd, srcDirs, config, ctxMtime) {
+    const { CODE_EXTS } = __require('./src/analysis/coverage-score');
+    const exclude = new Set(EXCLUDE_DIRS);
+    if (config && Array.isArray(config.exclude)) for (const x of config.exclude) exclude.add(String(x));
+
+    let changed = 0;
+    let seen = 0;
+    const walk = (dir, depth) => {
+      if (depth > 8 || seen > 5000) return;
+      let entries;
+      try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch (_) { return; }
+      for (const e of entries) {
+        if (exclude.has(e.name)) continue;
+        const full = path.join(dir, e.name);
+        if (e.isDirectory()) walk(full, depth + 1);
+        else if (e.isFile() && CODE_EXTS.has(path.extname(e.name).toLowerCase())) {
+          seen++;
+          try { if (fs.statSync(full).mtimeMs > ctxMtime) changed++; } catch (_) {}
+        }
+      }
+    };
+    for (const d of srcDirs) {
+      const abs = path.isAbsolute(d) ? d : path.join(cwd, d);
+      if (fs.existsSync(abs)) walk(abs, 0);
+    }
+    return changed;
+  }
+
+  /**
+   * Run all diagnostic checks.
+   * @param {string} cwd
+   * @returns {{ checks: Array<{id,label,status,detail,fix}>, ok: boolean, errors: number, warnings: number }}
+   */
+  function diagnose(cwd, opts = {}) {
+    const checks = [];
+    const add = (id, label, status, detail, fix) => checks.push({ id, label, status, detail: detail || '', fix: fix || null });
+
+    // 1. Git repository
+    try {
+      const { tryGit } = __require('./src/util/git');
+      const inside = tryGit(['rev-parse', '--is-inside-work-tree'], { cwd });
+      if (inside === 'true') add('git', 'Git repository', 'ok', 'recency boost + impact analysis enabled');
+      else add('git', 'Git repository', 'warn', 'not a git repository', 'git init — enables recency boost and impact analysis');
+    } catch (_) {
+      add('git', 'Git repository', 'warn', 'git not available', 'install git for recency boost + impact analysis');
+    }
+
+    // 2. Config & source roots
+    let config = {};
+    try {
+      const cfgPath = path.join(cwd, 'gen-context.config.json');
+      let configBroken = false;
+      if (fs.existsSync(cfgPath)) {
+        try { JSON.parse(fs.readFileSync(cfgPath, 'utf8')); }
+        catch (e) {
+          configBroken = true;
+          add('config', 'Config & source roots', 'fail', `gen-context.config.json is invalid JSON: ${e.message}`, 'fix the JSON syntax, or delete the file to fall back to defaults');
+        }
+      }
+      const { loadConfig } = __require('./src/config/loader');
+      config = loadConfig(cwd) || {};
+      if (!configBroken) {
+        // Distinguish explicitly-configured srcDirs (validate each) from the
+        // default candidate list (just report which ones actually exist).
+        let explicitSrcDirs = null;
+        if (fs.existsSync(cfgPath)) {
+          try { const raw = JSON.parse(fs.readFileSync(cfgPath, 'utf8')); if (Array.isArray(raw.srcDirs)) explicitSrcDirs = raw.srcDirs; } catch (_) {}
+        }
+        const exists = (d) => { try { return fs.existsSync(path.isAbsolute(d) ? d : path.join(cwd, d)); } catch (_) { return false; } };
+        const srcDirs = Array.isArray(config.srcDirs) ? config.srcDirs : [];
+        const present = srcDirs.filter(exists);
+
+        if (explicitSrcDirs) {
+          const missing = explicitSrcDirs.filter((d) => !exists(d));
+          if (missing.length) add('config', 'Config & source roots', 'warn', `configured srcDirs not found: ${missing.join(', ')}`, 'fix "srcDirs" in gen-context.config.json');
+          else add('config', 'Config & source roots', 'ok', `srcDirs: ${explicitSrcDirs.join(', ')}`);
+        } else if (present.length === 0) {
+          add('config', 'Config & source roots', 'warn', 'no source directories found (looked for src/, app/, lib/, …)', 'create a src/ dir, set "srcDirs" in gen-context.config.json, or run: sigmap roots --fix');
+        } else {
+          add('config', 'Config & source roots', 'ok', `source roots: ${present.slice(0, 8).join(', ')}${present.length > 8 ? `, +${present.length - 8} more` : ''}`);
+        }
+      }
+    } catch (e) {
+      if (!checks.some((c) => c.id === 'config')) add('config', 'Config & source roots', 'warn', `could not load config: ${e.message}`);
+    }
+
+    // 3. Generated context file
+    const ctxFiles = _contextFiles(cwd);
+    if (ctxFiles.length === 0) {
+      add('context', 'Generated context', 'fail', 'no context file found', 'run: npx sigmap   (generates the signature map)');
+    } else {
+      add('context', 'Generated context', 'ok', `${ctxFiles.length} file(s): ${ctxFiles.map((f) => _short(f, cwd)).join(', ')}`);
+    }
+
+    // 4. Signature index
+    let indexSize = 0;
+    try {
+      const { buildSigIndex } = __require('./src/retrieval/ranker');
+      indexSize = buildSigIndex(cwd).size;
+    } catch (_) {}
+    if (indexSize === 0) {
+      add('index', 'Signature index', ctxFiles.length === 0 ? 'fail' : 'warn', 'no signatures indexed', 'run: npx sigmap   then: sigmap ask "<query>"');
+    } else {
+      add('index', 'Signature index', 'ok', `${indexSize} file(s) indexed`);
+    }
+
+    // 5. Index freshness
+    try {
+      if (ctxFiles.length) {
+        const ctxMtime = Math.max(...ctxFiles.map((f) => { try { return fs.statSync(f).mtimeMs; } catch (_) { return 0; } }));
+        const srcDirs = (config && Array.isArray(config.srcDirs) && config.srcDirs.length) ? config.srcDirs : ['src', 'app', 'lib'];
+        const changed = _countChangedSince(cwd, srcDirs, config, ctxMtime);
+        if (changed > 0) add('freshness', 'Index freshness', 'warn', `${changed} source file(s) changed since last generate`, 'run: sigmap   (or: sigmap --watch to auto-refresh)');
+        else add('freshness', 'Index freshness', 'ok', 'index is up to date with sources');
+      }
+    } catch (_) {}
+
+    // 6. Coverage
+    try {
+      if (indexSize > 0) {
+        const { coverageScore } = __require('./src/analysis/coverage-score');
+        const { buildSigIndex } = __require('./src/retrieval/ranker');
+        const entries = [...buildSigIndex(cwd).keys()].map((rel) => ({ filePath: path.resolve(cwd, rel) }));
+        const cov = coverageScore(cwd, entries, config);
+        if (cov.score < 70) add('coverage', 'Coverage', 'warn', `${cov.score}% of source files in context (grade ${cov.grade})`, 'increase maxTokens or expand srcDirs in gen-context.config.json');
+        else add('coverage', 'Coverage', 'ok', `${cov.score}% of source files in context (grade ${cov.grade})`);
+      }
+    } catch (_) {}
+
+    // 7. MCP wiring
+    try {
+      let wired = null;
+      for (const t of _mcpTargets(cwd)) {
+        try {
+          if (!fs.existsSync(t)) continue;
+          if (/sigmap/.test(fs.readFileSync(t, 'utf8'))) { wired = t; break; }
+        } catch (_) {}
+      }
+      if (wired) add('mcp', 'MCP wiring', 'ok', `registered in ${_short(wired, cwd)}`);
+      else add('mcp', 'MCP wiring', 'warn', 'MCP server not registered in any editor config', 'run: sigmap --setup   (auto-wires Claude, Cursor, Windsurf, VS Code, …)');
+    } catch (_) {}
+
+    const errors = checks.filter((c) => c.status === 'fail').length;
+    const warnings = checks.filter((c) => c.status === 'warn').length;
+    return { checks, ok: errors === 0, errors, warnings };
+  }
+
+  /** Human-readable checklist. */
+  function formatDoctor(result) {
+    const lines = ['sigmap doctor', ''];
+    for (const c of result.checks) {
+      lines.push(`${ICON[c.status] || '?'} ${c.label}${c.detail ? ' — ' + c.detail : ''}`);
+      if (c.status !== 'ok' && c.fix) lines.push(`    ↳ ${c.fix}`);
+    }
+    lines.push('');
+    lines.push(
+      result.errors === 0 && result.warnings === 0
+        ? '✓ All checks passed.'
+        : `${result.errors} error(s), ${result.warnings} warning(s).`
+    );
+    return lines.join('\n');
+  }
+
+  /** Machine-readable result. */
+  function formatDoctorJSON(result) {
+    return JSON.stringify(result, null, 2);
+  }
+
+  module.exports = { diagnose, formatDoctor, formatDoctorJSON };
+  
+};
+
 // ── ./src/eval/analyzer ──
 __factories["./src/eval/analyzer"] = function(module, exports) {
   
@@ -12288,6 +12528,152 @@ __factories["./src/mcp/handlers"] = function(module, exports) {
   
 };
 
+// ── ./src/mcp/install ──
+__factories["./src/mcp/install"] = function(module, exports) {
+  
+  /**
+   * Per-client MCP install (v8.0 E4).
+   *
+   * `sigmap --setup` wires *every* known editor at once and only touches config
+   * files that already exist (to avoid creating clutter for editors the user does
+   * not use). This module is the targeted counterpart: `sigmap mcp install <client>`
+   * picks one client, and — because the user explicitly asked for it — CREATES the
+   * config dir/file if it is missing. Idempotent: re-running never duplicates the
+   * entry. Zero dependencies; only `fs`/`path`/`os`.
+   */
+
+  const fs   = require('fs');
+  const path = require('path');
+  const os   = require('os');
+
+  // Config shapes the supported clients use.
+  //  - 'json'  → { mcpServers: { sigmap: { command, args } } }
+  //  - 'zed'   → { context_servers: { sigmap: { command: { path, args } } } }
+  //  - 'yaml'  → Codex CLI ~/.codex/config.yaml (mcpServers block, appended)
+  const CLIENTS = {
+    claude:   { label: 'Claude Code',  format: 'json', scope: 'project', project: ['.claude', 'settings.json'] },
+    cursor:   { label: 'Cursor',       format: 'json', scope: 'project', project: ['.cursor', 'mcp.json'] },
+    windsurf: { label: 'Windsurf',     format: 'json', scope: 'both',
+                project: ['.windsurf', 'mcp.json'],
+                global:  ['.codeium', 'windsurf', 'mcp_config.json'] },
+    vscode:   { label: 'VS Code',      format: 'json', scope: 'project', project: ['.vscode', 'mcp.json'] },
+    opencode: { label: 'OpenCode',     format: 'json', scope: 'both',
+                project: ['opencode.json'],
+                global:  ['.config', 'opencode', 'config.json'] },
+    gemini:   { label: 'Gemini CLI',   format: 'json', scope: 'global', global: ['.gemini', 'settings.json'] },
+    zed:      { label: 'Zed',          format: 'zed',  scope: 'global', global: ['.config', 'zed', 'settings.json'] },
+    codex:    { label: 'Codex CLI',    format: 'yaml', scope: 'global', global: ['.codex', 'config.yaml'] },
+    mcp:      { label: 'Portable (.mcp.json)', format: 'json', scope: 'project', project: ['.mcp.json'] },
+  };
+
+  /** Resolve the absolute config path for a client, honoring `global`. */
+  function resolveTarget(spec, cwd, home, useGlobal) {
+    const wantGlobal = useGlobal || spec.scope === 'global';
+    if (wantGlobal && spec.global) return path.join(home, ...spec.global);
+    if (spec.project) return path.join(cwd, ...spec.project);
+    if (spec.global)  return path.join(home, ...spec.global);
+    return null;
+  }
+
+  /** List supported clients with their resolved target paths. */
+  function listClients(opts = {}) {
+    const cwd  = opts.cwd  || process.cwd();
+    const home = opts.home || os.homedir();
+    return Object.keys(CLIENTS).map((key) => {
+      const spec = CLIENTS[key];
+      return {
+        client: key,
+        label:  spec.label,
+        scope:  spec.scope,
+        format: spec.format,
+        target: resolveTarget(spec, cwd, home, false),
+        globalTarget: spec.scope === 'both' ? resolveTarget(spec, cwd, home, true) : null,
+      };
+    });
+  }
+
+  function serverArgs(scriptPath) {
+    return [path.resolve(scriptPath), '--mcp'];
+  }
+
+  /** Install into a JSON `mcpServers` config (create file/dir if absent). */
+  function _installJson(filePath, scriptPath) {
+    let settings = {};
+    if (fs.existsSync(filePath)) {
+      try { settings = JSON.parse(fs.readFileSync(filePath, 'utf8')) || {}; }
+      catch (_) { settings = {}; }
+    }
+    if (!settings.mcpServers) settings.mcpServers = {};
+    if (settings.mcpServers.sigmap) return 'already';
+    settings.mcpServers.sigmap = { command: 'node', args: serverArgs(scriptPath) };
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, JSON.stringify(settings, null, 2) + '\n');
+    return 'installed';
+  }
+
+  /** Install into Zed's `context_servers` config (create file/dir if absent). */
+  function _installZed(filePath, scriptPath) {
+    let settings = {};
+    if (fs.existsSync(filePath)) {
+      try { settings = JSON.parse(fs.readFileSync(filePath, 'utf8')) || {}; }
+      catch (_) { settings = {}; }
+    }
+    if (!settings.context_servers) settings.context_servers = {};
+    if (settings.context_servers.sigmap) return 'already';
+    settings.context_servers.sigmap = { command: { path: 'node', args: serverArgs(scriptPath) } };
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, JSON.stringify(settings, null, 2) + '\n');
+    return 'installed';
+  }
+
+  /** Install into Codex CLI YAML (append block; create file if absent). */
+  function _installYaml(filePath, scriptPath) {
+    let raw = '';
+    if (fs.existsSync(filePath)) {
+      raw = fs.readFileSync(filePath, 'utf8');
+      if (raw.includes('sigmap')) return 'already';
+    }
+    const block = [
+      'mcpServers:',
+      '  sigmap:',
+      '    command: node',
+      '    args:',
+      `      - ${path.resolve(scriptPath)}`,
+      '      - --mcp',
+    ].join('\n');
+    const next = raw ? raw.trimEnd() + '\n\n' + block + '\n' : block + '\n';
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, next);
+    return 'installed';
+  }
+
+  /**
+   * Install the sigmap MCP server for a single client.
+   * @returns { client, label, path, status } where status is
+   *   'installed' | 'already' | 'unknown'.
+   */
+  function installClient(client, opts = {}) {
+    const spec = CLIENTS[client];
+    if (!spec) {
+      return { client, status: 'unknown', valid: Object.keys(CLIENTS) };
+    }
+    const cwd        = opts.cwd  || process.cwd();
+    const home       = opts.home || os.homedir();
+    const scriptPath = opts.scriptPath || path.join(cwd, 'gen-context.js');
+    const filePath   = resolveTarget(spec, cwd, home, opts.global);
+
+    let status;
+    if (spec.format === 'zed')       status = _installZed(filePath, scriptPath);
+    else if (spec.format === 'yaml') status = _installYaml(filePath, scriptPath);
+    else                             status = _installJson(filePath, scriptPath);
+
+    return { client, label: spec.label, path: filePath, status };
+  }
+
+  module.exports = { CLIENTS, listClients, installClient, resolveTarget };
+  
+};
+
 // ── ./src/mcp/server ──
 __factories["./src/mcp/server"] = function(module, exports) {
   
@@ -12309,7 +12695,7 @@ __factories["./src/mcp/server"] = function(module, exports) {
 
   const SERVER_INFO = {
     name: 'sigmap',
-    version: '7.27.0',
+    version: '7.29.0',
     description: 'SigMap MCP server — code signatures on demand',
   };
 
@@ -16138,7 +16524,7 @@ function __tryGit(args, opts = {}) {
   catch (_) { return ''; }
 }
 
-const VERSION = '7.27.0';
+const VERSION = '7.29.0';
 const MARKER = '\n\n## Auto-generated signatures\n<!-- Updated by gen-context.js -->\n';
 
 function requireSourceOrBundled(key) {
@@ -17951,6 +18337,9 @@ Usage:
   ${cmd} note "<text>"                     Append a note to the cross-session decision log
   ${cmd} note                              List recent notes (also: note --list <N>)
   ${cmd} status                            Show repo state — branch, dirty files, index freshness, notes
+  ${cmd} doctor                            Diagnose config, index, freshness, coverage, MCP wiring — with fixes (--json; exits 1 on hard failure)
+  ${cmd} mcp list                          List MCP clients and their config paths (--json)
+  ${cmd} mcp install <client>              Wire MCP for one client (claude|cursor|windsurf|vscode|zed|codex|gemini|opencode|mcp); --global for user-level
   ${cmd} --init                            Write example config + .contextignore scaffold
   ${cmd} --help                            Show this message
   ${cmd} --version                         Show version
@@ -19375,6 +19764,70 @@ function main() {
     process.exit(0);
   }
 
+  // `sigmap mcp install <client>` / `sigmap mcp list` — one-command per-client
+  // MCP wiring (v8.0 E4). Unlike `--setup` (wires every editor, only touches
+  // existing configs), this targets one client and creates the config if absent.
+  if (args[0] === 'mcp') {
+    const { listClients, installClient } = requireSourceOrBundled('./src/mcp/install');
+    const sub = args[1];
+
+    if (sub === 'list') {
+      const clients = listClients({ cwd });
+      if (args.includes('--json')) {
+        process.stdout.write(JSON.stringify(clients, null, 2) + '\n');
+        process.exit(0);
+      }
+      console.log('Supported MCP clients:\n');
+      for (const c of clients) {
+        const scope = c.scope === 'both' ? 'project (or --global)' : c.scope;
+        console.log(`  ${c.client.padEnd(10)} ${c.label}`);
+        console.log(`             ${_displayPath(c.target, cwd)}  [${scope}]`);
+      }
+      console.log('\nInstall with: sigmap mcp install <client>');
+      process.exit(0);
+    }
+
+    if (sub === 'install') {
+      const client = args[2];
+      if (!client || client.startsWith('--')) {
+        console.error('[sigmap] usage: sigmap mcp install <client>   (see: sigmap mcp list)');
+        process.exit(1);
+      }
+      const result = installClient(client, {
+        cwd,
+        scriptPath,
+        global: args.includes('--global'),
+      });
+      if (result.status === 'unknown') {
+        console.error(`[sigmap] unknown client "${client}". Valid: ${result.valid.join(', ')}`);
+        process.exit(1);
+      }
+      if (result.status === 'already') {
+        console.log(`[sigmap] ${result.label}: sigmap already registered in ${_displayPath(result.path, cwd)}`);
+      } else {
+        console.log(`[sigmap] ${result.label}: registered MCP server in ${_displayPath(result.path, cwd)}`);
+      }
+      process.exit(0);
+    }
+
+    console.error('[sigmap] usage: sigmap mcp install <client> | sigmap mcp list');
+    process.exit(1);
+  }
+
+  // `sigmap doctor` — diagnose config, index, freshness, coverage, and MCP
+  // wiring; print an actionable fix for anything wrong. Exit 1 on a hard
+  // failure (no context file / invalid config) so it is usable in CI.
+  if (args[0] === 'doctor') {
+    const { diagnose, formatDoctor, formatDoctorJSON } = requireSourceOrBundled('./src/doctor/diagnose');
+    const result = diagnose(cwd);
+    if (args.includes('--json')) {
+      process.stdout.write(formatDoctorJSON(result) + '\n');
+    } else {
+      console.log(formatDoctor(result));
+    }
+    process.exit(result.ok ? 0 : 1);
+  }
+
   // Layer 3: `sigmap conventions` — extract & report repo coding conventions
   // (file naming, export style, test framework) for TS/JS/Python so generated
   // code matches the house style. Writes .context/conventions.json.

package/llms-full.txt

@@ -9,13 +9,13 @@ the files relevant to the task — cutting tokens ~97% while keeping answers
 grounded. Deterministic, offline, no embeddings or vector database. Works with
 Claude, Cursor, GitHub Copilot, Aider, Windsurf, local LLMs, and MCP.
 
-# Version: 7.27.0 | Benchmark: sigmap-v7.27-main (2026-06-22)
+# Version: 7.29.0 | Benchmark: sigmap-v7.29-main (2026-06-23)
 # Source: auto-generated from package.json, version.json, benchmarks/latest.json, src/mcp/tools.js, src/config/defaults.js
 # Regenerate: npm run generate:llms   |   Validate: npm run validate:llms
 
 ---
 
-## Core metrics (benchmark: sigmap-v7.27-main, 2026-06-22)
+## Core metrics (benchmark: sigmap-v7.29-main, 2026-06-23)
 
 | Metric | Without SigMap | With SigMap |
 |--------|----------------|-------------|
@@ -115,6 +115,9 @@ sigmap evidence "<query>" --top <n> --budget <n> --out <path>   Tune ranked file
 sigmap note "<text>"                     Append a note to the cross-session decision log
 sigmap note                              List recent notes (also: note --list <N>)
 sigmap status                            Show repo state — branch, dirty files, index freshness, notes
+sigmap doctor                            Diagnose config, index, freshness, coverage, MCP wiring — with fixes (--json; exits 1 on hard failure)
+sigmap mcp list                          List MCP clients and their config paths (--json)
+sigmap mcp install <client>              Wire MCP for one client (claude|cursor|windsurf|vscode|zed|codex|gemini|opencode|mcp); --global for user-level
 sigmap --init                            Write example config + .contextignore scaffold
 sigmap --help                            Show this message
 sigmap --version                         Show version

package/llms.txt

@@ -9,7 +9,7 @@ the files relevant to the task — cutting tokens ~97% while keeping answers
 grounded. Deterministic, offline, no embeddings or vector database. Works with
 Claude, Cursor, GitHub Copilot, Aider, Windsurf, local LLMs, and MCP.
 
-# Version: 7.27.0 | Benchmark: sigmap-v7.27-main (2026-06-22)
+# Version: 7.29.0 | Benchmark: sigmap-v7.29-main (2026-06-23)
 # Source: auto-generated from package.json, version.json, benchmarks/latest.json, src/mcp/tools.js, src/config/defaults.js
 # Regenerate: npm run generate:llms   |   Validate: npm run validate:llms
 
@@ -21,7 +21,7 @@ Claude, Cursor, GitHub Copilot, Aider, Windsurf, local LLMs, and MCP.
 - No blast-radius awareness before editing a hub file — `--impact` shows every file a change touches.
 - Pasted stack traces, CI logs, and JSON bloat the prompt — `squeeze` minimizes them and enriches the top frame from the symbol index.
 
-## Core metrics (benchmark: sigmap-v7.27-main, 2026-06-22)
+## Core metrics (benchmark: sigmap-v7.29-main, 2026-06-23)
 
 - hit@5 retrieval: 75.6% vs 13.6% random baseline (5.6× lift)
 - Token reduction: 97.0% average across benchmark repos

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigmap",
-  "version": "7.27.0",
+  "version": "7.29.0",
   "description": "97% token reduction for AI coding. Extracts function & class signatures with TF-IDF ranking to feed only the right files to Claude, Cursor, Copilot, Aider, Windsurf, local LLMs & MCP. Zero dependencies, runs offline via npx.",
   "main": "packages/core/index.js",
   "exports": {

package/packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigmap-cli",
-  "version": "7.27.0",
+  "version": "7.29.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": "7.27.0",
+  "version": "7.29.0",
   "description": "SigMap core library — zero-dependency code signature extraction, retrieval, and security scanning",
   "main": "index.js",
   "keywords": [

package/src/doctor/diagnose.js

@@ -0,0 +1,236 @@
+'use strict';
+
+/**
+ * sigmap doctor (v8.0 E3).
+ *
+ * One-shot diagnostic for a SigMap setup: each check reports ok/warn/fail with
+ * an actionable fix, so a cold user can reach a useful answer in minutes. Pure,
+ * resilient (no check ever throws), zero new runtime deps. Composes the config
+ * loader, coverage scorer, signature index, and the known adapter-output /
+ * MCP-config paths.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// Generated context files a `read_context`/`ask` flow can consume.
+const ADAPTER_OUTPUTS = [
+  ['.github', 'copilot-instructions.md'],
+  ['CLAUDE.md'],
+  ['AGENTS.md'],
+  ['.cursorrules'],
+  ['.windsurfrules'],
+  ['.github', 'openai-context.md'],
+  ['.github', 'gemini-context.md'],
+  ['llm-full.txt'],
+  ['llm.txt'],
+];
+
+const EXCLUDE_DIRS = new Set([
+  'node_modules', '.git', 'dist', 'build', 'out', '__pycache__',
+  '.next', 'coverage', 'target', 'vendor', '.context',
+]);
+
+const ICON = { ok: '✓', warn: '⚠', fail: '✗' };
+
+function _short(p, cwd) {
+  const rel = path.relative(cwd, p);
+  return rel && !rel.startsWith('..') ? rel : p.replace(os.homedir(), '~');
+}
+
+function _contextFiles(cwd) {
+  const out = [];
+  for (const parts of ADAPTER_OUTPUTS) {
+    const p = path.join(cwd, ...parts);
+    try { if (fs.existsSync(p)) out.push(p); } catch (_) {}
+  }
+  return out;
+}
+
+function _mcpTargets(cwd) {
+  return [
+    path.join(cwd, '.mcp.json'),
+    path.join(cwd, '.claude', 'settings.json'),
+    path.join(cwd, '.cursor', 'mcp.json'),
+    path.join(cwd, '.windsurf', 'mcp.json'),
+    path.join(cwd, '.vscode', 'mcp.json'),
+    path.join(cwd, 'opencode.json'),
+    path.join(os.homedir(), '.codeium', 'windsurf', 'mcp_config.json'),
+    path.join(os.homedir(), '.config', 'opencode', 'config.json'),
+    path.join(os.homedir(), '.gemini', 'settings.json'),
+    path.join(os.homedir(), '.codex', 'config.yaml'),
+    path.join(os.homedir(), '.config', 'zed', 'settings.json'),
+  ];
+}
+
+/** Count code files under srcDirs modified after the context was generated. */
+function _countChangedSince(cwd, srcDirs, config, ctxMtime) {
+  const { CODE_EXTS } = require('../analysis/coverage-score');
+  const exclude = new Set(EXCLUDE_DIRS);
+  if (config && Array.isArray(config.exclude)) for (const x of config.exclude) exclude.add(String(x));
+
+  let changed = 0;
+  let seen = 0;
+  const walk = (dir, depth) => {
+    if (depth > 8 || seen > 5000) return;
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch (_) { return; }
+    for (const e of entries) {
+      if (exclude.has(e.name)) continue;
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) walk(full, depth + 1);
+      else if (e.isFile() && CODE_EXTS.has(path.extname(e.name).toLowerCase())) {
+        seen++;
+        try { if (fs.statSync(full).mtimeMs > ctxMtime) changed++; } catch (_) {}
+      }
+    }
+  };
+  for (const d of srcDirs) {
+    const abs = path.isAbsolute(d) ? d : path.join(cwd, d);
+    if (fs.existsSync(abs)) walk(abs, 0);
+  }
+  return changed;
+}
+
+/**
+ * Run all diagnostic checks.
+ * @param {string} cwd
+ * @returns {{ checks: Array<{id,label,status,detail,fix}>, ok: boolean, errors: number, warnings: number }}
+ */
+function diagnose(cwd, opts = {}) {
+  const checks = [];
+  const add = (id, label, status, detail, fix) => checks.push({ id, label, status, detail: detail || '', fix: fix || null });
+
+  // 1. Git repository
+  try {
+    const { tryGit } = require('../util/git');
+    const inside = tryGit(['rev-parse', '--is-inside-work-tree'], { cwd });
+    if (inside === 'true') add('git', 'Git repository', 'ok', 'recency boost + impact analysis enabled');
+    else add('git', 'Git repository', 'warn', 'not a git repository', 'git init — enables recency boost and impact analysis');
+  } catch (_) {
+    add('git', 'Git repository', 'warn', 'git not available', 'install git for recency boost + impact analysis');
+  }
+
+  // 2. Config & source roots
+  let config = {};
+  try {
+    const cfgPath = path.join(cwd, 'gen-context.config.json');
+    let configBroken = false;
+    if (fs.existsSync(cfgPath)) {
+      try { JSON.parse(fs.readFileSync(cfgPath, 'utf8')); }
+      catch (e) {
+        configBroken = true;
+        add('config', 'Config & source roots', 'fail', `gen-context.config.json is invalid JSON: ${e.message}`, 'fix the JSON syntax, or delete the file to fall back to defaults');
+      }
+    }
+    const { loadConfig } = require('../config/loader');
+    config = loadConfig(cwd) || {};
+    if (!configBroken) {
+      // Distinguish explicitly-configured srcDirs (validate each) from the
+      // default candidate list (just report which ones actually exist).
+      let explicitSrcDirs = null;
+      if (fs.existsSync(cfgPath)) {
+        try { const raw = JSON.parse(fs.readFileSync(cfgPath, 'utf8')); if (Array.isArray(raw.srcDirs)) explicitSrcDirs = raw.srcDirs; } catch (_) {}
+      }
+      const exists = (d) => { try { return fs.existsSync(path.isAbsolute(d) ? d : path.join(cwd, d)); } catch (_) { return false; } };
+      const srcDirs = Array.isArray(config.srcDirs) ? config.srcDirs : [];
+      const present = srcDirs.filter(exists);
+
+      if (explicitSrcDirs) {
+        const missing = explicitSrcDirs.filter((d) => !exists(d));
+        if (missing.length) add('config', 'Config & source roots', 'warn', `configured srcDirs not found: ${missing.join(', ')}`, 'fix "srcDirs" in gen-context.config.json');
+        else add('config', 'Config & source roots', 'ok', `srcDirs: ${explicitSrcDirs.join(', ')}`);
+      } else if (present.length === 0) {
+        add('config', 'Config & source roots', 'warn', 'no source directories found (looked for src/, app/, lib/, …)', 'create a src/ dir, set "srcDirs" in gen-context.config.json, or run: sigmap roots --fix');
+      } else {
+        add('config', 'Config & source roots', 'ok', `source roots: ${present.slice(0, 8).join(', ')}${present.length > 8 ? `, +${present.length - 8} more` : ''}`);
+      }
+    }
+  } catch (e) {
+    if (!checks.some((c) => c.id === 'config')) add('config', 'Config & source roots', 'warn', `could not load config: ${e.message}`);
+  }
+
+  // 3. Generated context file
+  const ctxFiles = _contextFiles(cwd);
+  if (ctxFiles.length === 0) {
+    add('context', 'Generated context', 'fail', 'no context file found', 'run: npx sigmap   (generates the signature map)');
+  } else {
+    add('context', 'Generated context', 'ok', `${ctxFiles.length} file(s): ${ctxFiles.map((f) => _short(f, cwd)).join(', ')}`);
+  }
+
+  // 4. Signature index
+  let indexSize = 0;
+  try {
+    const { buildSigIndex } = require('../retrieval/ranker');
+    indexSize = buildSigIndex(cwd).size;
+  } catch (_) {}
+  if (indexSize === 0) {
+    add('index', 'Signature index', ctxFiles.length === 0 ? 'fail' : 'warn', 'no signatures indexed', 'run: npx sigmap   then: sigmap ask "<query>"');
+  } else {
+    add('index', 'Signature index', 'ok', `${indexSize} file(s) indexed`);
+  }
+
+  // 5. Index freshness
+  try {
+    if (ctxFiles.length) {
+      const ctxMtime = Math.max(...ctxFiles.map((f) => { try { return fs.statSync(f).mtimeMs; } catch (_) { return 0; } }));
+      const srcDirs = (config && Array.isArray(config.srcDirs) && config.srcDirs.length) ? config.srcDirs : ['src', 'app', 'lib'];
+      const changed = _countChangedSince(cwd, srcDirs, config, ctxMtime);
+      if (changed > 0) add('freshness', 'Index freshness', 'warn', `${changed} source file(s) changed since last generate`, 'run: sigmap   (or: sigmap --watch to auto-refresh)');
+      else add('freshness', 'Index freshness', 'ok', 'index is up to date with sources');
+    }
+  } catch (_) {}
+
+  // 6. Coverage
+  try {
+    if (indexSize > 0) {
+      const { coverageScore } = require('../analysis/coverage-score');
+      const { buildSigIndex } = require('../retrieval/ranker');
+      const entries = [...buildSigIndex(cwd).keys()].map((rel) => ({ filePath: path.resolve(cwd, rel) }));
+      const cov = coverageScore(cwd, entries, config);
+      if (cov.score < 70) add('coverage', 'Coverage', 'warn', `${cov.score}% of source files in context (grade ${cov.grade})`, 'increase maxTokens or expand srcDirs in gen-context.config.json');
+      else add('coverage', 'Coverage', 'ok', `${cov.score}% of source files in context (grade ${cov.grade})`);
+    }
+  } catch (_) {}
+
+  // 7. MCP wiring
+  try {
+    let wired = null;
+    for (const t of _mcpTargets(cwd)) {
+      try {
+        if (!fs.existsSync(t)) continue;
+        if (/sigmap/.test(fs.readFileSync(t, 'utf8'))) { wired = t; break; }
+      } catch (_) {}
+    }
+    if (wired) add('mcp', 'MCP wiring', 'ok', `registered in ${_short(wired, cwd)}`);
+    else add('mcp', 'MCP wiring', 'warn', 'MCP server not registered in any editor config', 'run: sigmap --setup   (auto-wires Claude, Cursor, Windsurf, VS Code, …)');
+  } catch (_) {}
+
+  const errors = checks.filter((c) => c.status === 'fail').length;
+  const warnings = checks.filter((c) => c.status === 'warn').length;
+  return { checks, ok: errors === 0, errors, warnings };
+}
+
+/** Human-readable checklist. */
+function formatDoctor(result) {
+  const lines = ['sigmap doctor', ''];
+  for (const c of result.checks) {
+    lines.push(`${ICON[c.status] || '?'} ${c.label}${c.detail ? ' — ' + c.detail : ''}`);
+    if (c.status !== 'ok' && c.fix) lines.push(`    ↳ ${c.fix}`);
+  }
+  lines.push('');
+  lines.push(
+    result.errors === 0 && result.warnings === 0
+      ? '✓ All checks passed.'
+      : `${result.errors} error(s), ${result.warnings} warning(s).`
+  );
+  return lines.join('\n');
+}
+
+/** Machine-readable result. */
+function formatDoctorJSON(result) {
+  return JSON.stringify(result, null, 2);
+}
+
+module.exports = { diagnose, formatDoctor, formatDoctorJSON };

package/src/mcp/install.js

@@ -0,0 +1,142 @@
+'use strict';
+
+/**
+ * Per-client MCP install (v8.0 E4).
+ *
+ * `sigmap --setup` wires *every* known editor at once and only touches config
+ * files that already exist (to avoid creating clutter for editors the user does
+ * not use). This module is the targeted counterpart: `sigmap mcp install <client>`
+ * picks one client, and — because the user explicitly asked for it — CREATES the
+ * config dir/file if it is missing. Idempotent: re-running never duplicates the
+ * entry. Zero dependencies; only `fs`/`path`/`os`.
+ */
+
+const fs   = require('fs');
+const path = require('path');
+const os   = require('os');
+
+// Config shapes the supported clients use.
+//  - 'json'  → { mcpServers: { sigmap: { command, args } } }
+//  - 'zed'   → { context_servers: { sigmap: { command: { path, args } } } }
+//  - 'yaml'  → Codex CLI ~/.codex/config.yaml (mcpServers block, appended)
+const CLIENTS = {
+  claude:   { label: 'Claude Code',  format: 'json', scope: 'project', project: ['.claude', 'settings.json'] },
+  cursor:   { label: 'Cursor',       format: 'json', scope: 'project', project: ['.cursor', 'mcp.json'] },
+  windsurf: { label: 'Windsurf',     format: 'json', scope: 'both',
+              project: ['.windsurf', 'mcp.json'],
+              global:  ['.codeium', 'windsurf', 'mcp_config.json'] },
+  vscode:   { label: 'VS Code',      format: 'json', scope: 'project', project: ['.vscode', 'mcp.json'] },
+  opencode: { label: 'OpenCode',     format: 'json', scope: 'both',
+              project: ['opencode.json'],
+              global:  ['.config', 'opencode', 'config.json'] },
+  gemini:   { label: 'Gemini CLI',   format: 'json', scope: 'global', global: ['.gemini', 'settings.json'] },
+  zed:      { label: 'Zed',          format: 'zed',  scope: 'global', global: ['.config', 'zed', 'settings.json'] },
+  codex:    { label: 'Codex CLI',    format: 'yaml', scope: 'global', global: ['.codex', 'config.yaml'] },
+  mcp:      { label: 'Portable (.mcp.json)', format: 'json', scope: 'project', project: ['.mcp.json'] },
+};
+
+/** Resolve the absolute config path for a client, honoring `global`. */
+function resolveTarget(spec, cwd, home, useGlobal) {
+  const wantGlobal = useGlobal || spec.scope === 'global';
+  if (wantGlobal && spec.global) return path.join(home, ...spec.global);
+  if (spec.project) return path.join(cwd, ...spec.project);
+  if (spec.global)  return path.join(home, ...spec.global);
+  return null;
+}
+
+/** List supported clients with their resolved target paths. */
+function listClients(opts = {}) {
+  const cwd  = opts.cwd  || process.cwd();
+  const home = opts.home || os.homedir();
+  return Object.keys(CLIENTS).map((key) => {
+    const spec = CLIENTS[key];
+    return {
+      client: key,
+      label:  spec.label,
+      scope:  spec.scope,
+      format: spec.format,
+      target: resolveTarget(spec, cwd, home, false),
+      globalTarget: spec.scope === 'both' ? resolveTarget(spec, cwd, home, true) : null,
+    };
+  });
+}
+
+function serverArgs(scriptPath) {
+  return [path.resolve(scriptPath), '--mcp'];
+}
+
+/** Install into a JSON `mcpServers` config (create file/dir if absent). */
+function _installJson(filePath, scriptPath) {
+  let settings = {};
+  if (fs.existsSync(filePath)) {
+    try { settings = JSON.parse(fs.readFileSync(filePath, 'utf8')) || {}; }
+    catch (_) { settings = {}; }
+  }
+  if (!settings.mcpServers) settings.mcpServers = {};
+  if (settings.mcpServers.sigmap) return 'already';
+  settings.mcpServers.sigmap = { command: 'node', args: serverArgs(scriptPath) };
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(settings, null, 2) + '\n');
+  return 'installed';
+}
+
+/** Install into Zed's `context_servers` config (create file/dir if absent). */
+function _installZed(filePath, scriptPath) {
+  let settings = {};
+  if (fs.existsSync(filePath)) {
+    try { settings = JSON.parse(fs.readFileSync(filePath, 'utf8')) || {}; }
+    catch (_) { settings = {}; }
+  }
+  if (!settings.context_servers) settings.context_servers = {};
+  if (settings.context_servers.sigmap) return 'already';
+  settings.context_servers.sigmap = { command: { path: 'node', args: serverArgs(scriptPath) } };
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(settings, null, 2) + '\n');
+  return 'installed';
+}
+
+/** Install into Codex CLI YAML (append block; create file if absent). */
+function _installYaml(filePath, scriptPath) {
+  let raw = '';
+  if (fs.existsSync(filePath)) {
+    raw = fs.readFileSync(filePath, 'utf8');
+    if (raw.includes('sigmap')) return 'already';
+  }
+  const block = [
+    'mcpServers:',
+    '  sigmap:',
+    '    command: node',
+    '    args:',
+    `      - ${path.resolve(scriptPath)}`,
+    '      - --mcp',
+  ].join('\n');
+  const next = raw ? raw.trimEnd() + '\n\n' + block + '\n' : block + '\n';
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, next);
+  return 'installed';
+}
+
+/**
+ * Install the sigmap MCP server for a single client.
+ * @returns { client, label, path, status } where status is
+ *   'installed' | 'already' | 'unknown'.
+ */
+function installClient(client, opts = {}) {
+  const spec = CLIENTS[client];
+  if (!spec) {
+    return { client, status: 'unknown', valid: Object.keys(CLIENTS) };
+  }
+  const cwd        = opts.cwd  || process.cwd();
+  const home       = opts.home || os.homedir();
+  const scriptPath = opts.scriptPath || path.join(cwd, 'gen-context.js');
+  const filePath   = resolveTarget(spec, cwd, home, opts.global);
+
+  let status;
+  if (spec.format === 'zed')       status = _installZed(filePath, scriptPath);
+  else if (spec.format === 'yaml') status = _installYaml(filePath, scriptPath);
+  else                             status = _installJson(filePath, scriptPath);
+
+  return { client, label: spec.label, path: filePath, status };
+}
+
+module.exports = { CLIENTS, listClients, installClient, resolveTarget };

package/src/mcp/server.js

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