sigmap 7.28.0 → 7.30.0

package/CHANGELOG.md

@@ -10,6 +10,33 @@ Format: [Semantic Versioning](https://semver.org/)
 
 ---
 
+## [7.30.0] — 2026-06-23
+
+Minor release — **v8.0 E2 + E4 (the "Pivot"):** completes v8.0 by repositioning every public surface to the chosen framing — *"the deterministic, verifiable grounding layer for AI code work"* — and framing coding agents as **consumers, not competitors**. The Evidence Pack code (E1/E3/D3 + `mcp install`) already shipped in 7.27–7.29; this is the positioning half. Docs/strings only — no runtime behaviour change, zero new dependencies.
+
+### Added
+- **Agent recipes (#389):** new README "Agent recipes" section with copy-paste setup for Claude Code, Cursor, Cline, Continue, Aider, OpenHands, and Codex CLI — each via `sigmap mcp install <client>` or a deterministic Evidence Pack, positioning agents as consumers of SigMap's map.
+- **Surface docs for shipped commands (#389):** README now documents `sigmap evidence` (deterministic Evidence Pack JSON/Markdown) and `sigmap doctor` (setup diagnostics), which shipped in code but were undocumented.
+- **Repositioning gate (#389):** `test/integration/repositioning.test.js` makes the pivot non-regressable — asserts the grounding-layer framing on README/`llms.txt`/docs `<title>`, recipes for every named agent, and the documented commands.
+
+### Changed
+- **E2 repositioning (#389):** README tagline, "What is SigMap?", "Why SigMap?" (token reduction demoted to proof) and the compare table; `docs/index.html` title/meta/keywords/JSON-LD + hero (and the stale `softwareVersion` 5.8.0 → current); `llms.txt`/`llms-full.txt` regenerated from `scripts/llms-manual.mjs`; the per-project adapter tagline in `src/format/llms-txt.js` (bundle rebuilt, reproducible); `docs/_config.yml`. The literal `context-engine` remains only inside the published JetBrains plugin URL slug.
+- **Structure guards updated (#389):** `readme-structure.test.js` tagline/compare-table assertions moved to the new copy; `version-json.test.js` now derives the docs `softwareVersion` from `version.json` instead of a hardcoded stale value.
+
+## [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.

package/README.md

@@ -4,7 +4,7 @@
 
 # ⚡ SigMap
 
-**SigMap finds the right files before your AI answers.**
+**SigMap is the deterministic, verifiable grounding layer for AI code work.**
 
 [![npm version](https://img.shields.io/npm/v/sigmap?color=7c6af7&label=latest&logo=npm)](https://www.npmjs.com/package/sigmap)
 [![npm downloads](https://img.shields.io/npm/dt/sigmap?color=22c55e&label=downloads&logo=npm)](https://www.npmjs.com/package/sigmap)
@@ -35,7 +35,9 @@ Zero config. Zero dependencies. Under 10 seconds.
 
 ## What is SigMap?
 
-SigMap extracts function and class signatures from your codebase and feeds the right files — not the whole repo — to your AI.
+SigMap builds a **deterministic, auditable signature-and-evidence map** of your codebase — no LLM calls, no embeddings, byte-stable output — so AI agents, CI, and reviewers can *trust and verify* which files and symbols are real before acting. Same repo in, same map out, every time.
+
+That map is exactly what agentic grep is worst at: reproducible, auditable context an agent can consume without a copy-paste, and a grounding check that proves an AI answer is anchored to real signatures and line numbers. Token reduction comes for free — but trust is the point.
 
 **Model-agnostic.** Works with:
 - **Cloud LLMs:** Claude, GPT-4, Copilot, Gemini
@@ -48,6 +50,12 @@ SigMap extracts function and class signatures from your codebase and feeds the r
 
 ## Why SigMap?
 
+**Deterministic and verifiable — the two things an agentic-grep loop can't give you:**
+- **Deterministic** — no LLM calls, no agent loop; the same repo always produces a byte-identical map you can diff, cache, and gate in CI.
+- **Auditable & grounded** — every file and symbol traces to a real line anchor; `sigmap verify-ai-output` flags any AI claim that isn't.
+- **Zero dependencies** — `npx sigmap` on any machine; no embeddings, no vector DB, no hosted service, fully offline.
+
+**Proof it pays off** (full benchmark below):
 <!--SM:whyMetrics-->
 - **75.6% hit@5** — right file found in top 5 results (vs 13.6% baseline)
 - **97.0% token reduction** — average across 21 real repos
@@ -58,7 +66,6 @@ SigMap extracts function and class signatures from your codebase and feeds the r
 - **No vendor lock-in** — works with any AI assistant or local LLM
 - **No API costs** — use local models (Ollama, llama.cpp, vLLM) with zero token fees
 - **Full privacy** — keep your code and context on your machine
-- **Zero npm dependencies** — `npx sigmap` on any machine
 
 ---
 
@@ -66,9 +73,9 @@ SigMap extracts function and class signatures from your codebase and feeds the r
 
 | Without SigMap | With SigMap |
 |---|---|
-| ❌ Guessing which files are relevant | ✅ Right file in context — <!--SM:hitWhole-->76%<!--/SM:hitWhole--> of the time |
-| ❌ Sending the full repo to your AI | ✅ Minimal context — only what matters |
-| ❌ Embeddings / vector DB required | ✅ Grounded answers, no infra needed |
+| ❌ Non-reproducible agent guesses | ✅ Deterministic map — same input, same output, every time |
+| ❌ "Trust me" AI answers | ✅ Grounded — right file in context <!--SM:hitWhole-->76%<!--/SM:hitWhole--> of the time, every symbol on a real line anchor |
+| ❌ Embeddings / vector DB required | ✅ Zero deps, no infra, fully offline |
 
 ---
 
@@ -91,8 +98,8 @@ Ask → Rank → Context → Validate → Judge → Learn
 
 <!--SM:benchmarkBlock-->
 ```
-Benchmark : sigmap-v7.28-main (21 repositories, including R language)
-Date      : 2026-06-22
+Benchmark : sigmap-v7.30-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)
@@ -216,6 +223,47 @@ sigmap create "<task>"             # run the whole pipeline: scaffold → verify
 
 ---
 
+## Evidence Pack & diagnostics
+
+The **Evidence Pack** is the consumable, machine-readable replacement for "paste this into your prompt" — a deterministic JSON artifact (with a Markdown handoff mode) that an agent or CI step reads directly, with zero copy-paste:
+
+```bash
+sigmap evidence "how does auth work"            # → .context/evidence-pack.json (deterministic, byte-stable)
+sigmap evidence "how does auth work" --markdown # Markdown handoff to stdout
+sigmap doctor                                   # diagnose config, index, freshness, coverage, MCP wiring — with fixes
+```
+
+Each pack carries the ranked files, the symbols and line anchors that justify them, the token budget, the dropped files (and why), and the grounding summary — so a consumer can trust and audit the context instead of guessing.
+
+---
+
+## Agent recipes
+
+SigMap treats coding agents as **consumers, not competitors**: it hands them a deterministic, auditable map the agent can read on demand. Wire any of them up once, then let the agent pull context or consume an Evidence Pack.
+
+| Agent | One-time setup | How it consumes SigMap |
+|---|---|---|
+| **Claude Code** | `sigmap mcp install claude` | 17 MCP tools (`search_signatures`, `get_lines`, `get_diff_context`…) |
+| **Cursor** | `sigmap mcp install cursor` | MCP tools, plus the `cursor` adapter writes `.cursorrules` |
+| **Cline** | `sigmap mcp install cursor` | Reads `.cursorrules`; same MCP server |
+| **Continue** | `sigmap mcp install vscode` | MCP tools inside the Continue extension |
+| **Aider** | `sigmap --adapter openai` | Reads `.github/openai-context.md` before a session |
+| **OpenHands** | `sigmap evidence "<task>"` | Consumes `.context/evidence-pack.json` directly |
+| **Codex CLI** | `sigmap mcp install codex` | MCP tools, plus the `codex` adapter writes `AGENTS.md` |
+
+```bash
+# Pattern 1 — give the agent live, on-demand access (MCP)
+sigmap mcp install claude        # one of: claude|cursor|windsurf|vscode|zed|codex|gemini|opencode|mcp
+                                 # add --global for a user-level install
+
+# Pattern 2 — hand the agent a deterministic Evidence Pack (no MCP, no copy-paste)
+sigmap evidence "implement rate limiting" --markdown   # or read .context/evidence-pack.json
+```
+
+See [`sigmap mcp list`](https://sigmap.io/guide/cli.html) for every supported client.
+
+---
+
 ## Try it
 
 ```bash

package/gen-context.js

@@ -9837,7 +9837,7 @@ __factories["./src/format/llms-txt"] = function(module, exports) {
 
     const lines = [
       '# SigMap Context Index',
-      `> Generated by SigMap v${sigmapVersion} — zero-dependency AI context engine`,
+      `> Generated by SigMap v${sigmapVersion} — the deterministic, verifiable grounding layer for AI code work`,
       '',
       '## Project',
       `- Name: ${name}`,
@@ -12528,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) {
   
@@ -12549,7 +12695,7 @@ __factories["./src/mcp/server"] = function(module, exports) {
 
   const SERVER_INFO = {
     name: 'sigmap',
-    version: '7.28.0',
+    version: '7.30.0',
     description: 'SigMap MCP server — code signatures on demand',
   };
 
@@ -16378,7 +16524,7 @@ function __tryGit(args, opts = {}) {
   catch (_) { return ''; }
 }
 
-const VERSION = '7.28.0';
+const VERSION = '7.30.0';
 const MARKER = '\n\n## Auto-generated signatures\n<!-- Updated by gen-context.js -->\n';
 
 function requireSourceOrBundled(key) {
@@ -18192,6 +18338,8 @@ Usage:
   ${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
@@ -18943,7 +19091,7 @@ function main() {
     }
 
     const shareText = [
-      'Generated with SigMap — zero-dependency AI context engine',
+      'Generated with SigMap — the deterministic, verifiable grounding layer for AI code work',
       `${reduction}% fewer tokens · ${hitAt5}% retrieval accuracy · 6× better results`,
       'https://sigmap.io',
     ].join('\n');
@@ -19616,6 +19764,56 @@ 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.

package/llms-full.txt

@@ -1,21 +1,23 @@
 # SigMap — Complete LLM Reference
 
-> Zero-dependency context engine that stops AI coding agents from guessing in your codebase.
-> Grounded context. Verified answers. No embeddings, no vector DB, fully offline.
-
-SigMap is a zero-dependency AI context engine. It extracts function and class
-signatures from a codebase and uses TF-IDF ranking to feed an AI assistant only
-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.28.0 | Benchmark: sigmap-v7.28-main (2026-06-22)
+> The deterministic, verifiable grounding layer for AI code work.
+> A reproducible signature-and-evidence map that agents, CI, and reviewers can trust and audit. No embeddings, no vector DB, fully offline.
+
+SigMap is the deterministic, verifiable grounding layer for AI code work. It
+extracts function and class signatures from a codebase and builds a byte-stable
+signature-and-evidence map that agents, CI, and reviewers can trust and audit —
+proving which files and symbols are real before acting. Deterministic TF-IDF
+ranking keeps the relevant context in scope (cutting tokens ~97% as a side
+effect), with no LLM calls, embeddings, or vector database. Works with Claude,
+Cursor, GitHub Copilot, Aider, Windsurf, local LLMs, and MCP.
+
+# Version: 7.30.0 | Benchmark: sigmap-v7.30-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.28-main, 2026-06-22)
+## Core metrics (benchmark: sigmap-v7.30-main, 2026-06-23)
 
 | Metric | Without SigMap | With SigMap |
 |--------|----------------|-------------|
@@ -116,6 +118,8 @@ sigmap note "<text>"                     Append a note to the cross-session deci
 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

@@ -1,15 +1,17 @@
 # SigMap
 
-> Zero-dependency context engine that stops AI coding agents from guessing in your codebase.
-> Grounded context. Verified answers. No embeddings, no vector DB, fully offline.
-
-SigMap is a zero-dependency AI context engine. It extracts function and class
-signatures from a codebase and uses TF-IDF ranking to feed an AI assistant only
-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.28.0 | Benchmark: sigmap-v7.28-main (2026-06-22)
+> The deterministic, verifiable grounding layer for AI code work.
+> A reproducible signature-and-evidence map that agents, CI, and reviewers can trust and audit. No embeddings, no vector DB, fully offline.
+
+SigMap is the deterministic, verifiable grounding layer for AI code work. It
+extracts function and class signatures from a codebase and builds a byte-stable
+signature-and-evidence map that agents, CI, and reviewers can trust and audit —
+proving which files and symbols are real before acting. Deterministic TF-IDF
+ranking keeps the relevant context in scope (cutting tokens ~97% as a side
+effect), with no LLM calls, embeddings, or vector database. Works with Claude,
+Cursor, GitHub Copilot, Aider, Windsurf, local LLMs, and MCP.
+
+# Version: 7.30.0 | Benchmark: sigmap-v7.30-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 +23,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.28-main, 2026-06-22)
+## Core metrics (benchmark: sigmap-v7.30-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
@@ -52,5 +54,6 @@ npx sigmap --mcp                    # start the MCP server over stdio
 - [Benchmark dataset (Zenodo)](https://doi.org/10.5281/zenodo.19898842)
 - [Full LLM reference](https://sigmap.io/llms-full.txt)
 
-SigMap — grounded AI coding context. The lightweight, deterministic alternative
-to embeddings for feeding the right code to AI assistants.
+SigMap — the deterministic, verifiable grounding layer for AI code work. The
+reproducible signature-and-evidence map agents, CI, and reviewers can audit,
+which agentic grep cannot produce.

package/package.json

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

package/src/format/llms-txt.js

@@ -29,7 +29,7 @@ function format(context, cwd, writtenFiles, sigmapVersion) {
 
   const lines = [
     '# SigMap Context Index',
-    `> Generated by SigMap v${sigmapVersion} — zero-dependency AI context engine`,
+    `> Generated by SigMap v${sigmapVersion} — the deterministic, verifiable grounding layer for AI code work`,
     '',
     '## Project',
     `- Name: ${name}`,

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.28.0',
+  version: '7.30.0',
   description: 'SigMap MCP server — code signatures on demand',
 };