sigmap 8.11.0 → 8.12.0

package/AGENTS.md

@@ -33,11 +33,12 @@ Always run `sigmap ask` (or `sigmap --query`) before searching for files relevan
 src/extractors/python_ast.py ← ast
 ```
 
-## changes (last 5 commits — 2 days ago)
+## changes (last 5 commits — 0 seconds ago)
 ```
+src/format/terse.js                           +splitAnchor  +encodeTerseSig  +encodeTerseSigs  +_tokens
+src/wiki/generate.js                          +_rel  +_pct  +_identity  +_modules
 src/conventions/extract.js                    ~classifyNaming  ~scoreConvention
 src/conventions/fix.js                        ~buildFixList
-src/daemon/daemon.js                          +daemonDir  +pidFile  +logFile  +isAlive
 src/extractors/javascript.js                  ~extract  ~extractClassMembers  ~extractBlock  ~buildReturnHints
 src/extractors/typescript.js                  ~extract  ~extractInterfaceMembers  ~extractClassMembers  ~extractBlock
 src/graph/builder.js                          +probeJs  +resolveJsPath  +stripJsonc  +loadAliasMap
@@ -179,6 +180,21 @@ code-fence ---
 
 ## src
 
+### src/config/defaults.js
+```
+module.exports = { DEFAULTS }  :161-161
+```
+
+### src/format/terse.js
+```
+module.exports = { encodeTerseSig, encodeTerseSigs, measureTerse, splitAnchor }  :86-86
+function splitAnchor(sig) → { text: string, suffix: s  :25-30
+function encodeTerseSig(sig) → string  :37-50
+function encodeTerseSigs(sigs) → string[]  :57-59
+function _tokens(sigs)  :62-64
+function measureTerse(sigsList) → { beforeTokens: number, a  :72-84
+```
+
 ### src/mcp/server.js
 ```
 module.exports = { start }  :140-140
@@ -188,6 +204,20 @@ function dispatch(msg, cwd)  :41-107
 function start(cwd)  :112-138
 ```
 
+### src/wiki/generate.js
+```
+module.exports = { buildWiki, renderWikiMarkdown }  :250-250
+function _rel(cwd, f)  :22-24
+function _pct(fraction)  :26-28
+function _identity(cwd)  :31-37
+function _modules(index)  :40-67
+function _flow(cwd)  :70-97
+function _conventions(cwd, index)  :100-117
+function _health(cwd)  :119-127
+function buildWiki(cwd, opts = {}) → { data: object, markdown:  :137-162
+function renderWikiMarkdown(data, sigmapVersion) → string  :171-248
+```
+
 ### src/analysis/coverage-score.js
 ```
 module.exports = { coverageScore, CODE_EXTS }  :105-105
@@ -225,11 +255,6 @@ function getChangedFiles(files, cache) → { changed: string[], unch  :71-88
 function updateCacheEntries(cache, extracted)  :96-103
 ```
 
-### src/config/defaults.js
-```
-module.exports = { DEFAULTS }  :161-161
-```
-
 ### src/config/loader.js
 ```
 module.exports = { loadConfig, loadBaseConfig }  :313-313
@@ -904,16 +929,6 @@ function detectVersion(cwd)  :13-19
 function format(context, cwd, writtenFiles, sigmapVersion)  :21-69
 ```
 
-### src/format/terse.js
-```
-module.exports = { encodeTerseSig, encodeTerseSigs, measureTerse, splitAnchor }  :86-86
-function splitAnchor(sig) → { text: string, suffix: s  :25-30
-function encodeTerseSig(sig) → string  :37-50
-function encodeTerseSigs(sigs) → string[]  :57-59
-function _tokens(sigs)  :62-64
-function measureTerse(sigsList) → { beforeTokens: number, a  :72-84
-```
-
 ### src/format/usage-guidance.js
 ```
 module.exports = { usageBlock }  :28-28

package/CHANGELOG.md

@@ -10,6 +10,15 @@ Format: [Semantic Versioning](https://semver.org/)
 
 ---
 
+## [8.12.0] — 2026-07-11
+
+Minor release — **`sigmap wiki`** (D9, the final unstarted in-boundary item from the master plan §3.5 backlog). With this, every in-boundary initiative D1–D9 has shipped.
+
+### Added
+- **`sigmap wiki` — deterministic architecture narrative (#465, PR #466):** writes `.context/WIKI.md` composed entirely from data SigMap already computes — overview (indexed files, modules, signature tokens, health grade), module rollup with key files, dependency flow (hub files, entry points, cycle count from the import graph), conventions summary, and navigation pointers. Template prose only: **no LLM, no network, no timestamps** — two consecutive runs on an unchanged repo are byte-identical (regression-tested). `--out <path>` overrides the target; `--json` emits the structured data instead. Graph paths are relativized against the builder's normalized base so hubs/entries render repo-relative on macOS tmpdirs.
+
+---
+
 ## [8.11.0] — 2026-07-11
 
 Minor release — the **terse signature encoder** (D7 from the master plan), shipped under its measure-first gate: the public reduction number comes from a benchmark run on this repo, never borrowed from another tool's prose-compression claims.

package/README.md

@@ -122,7 +122,7 @@ Ask → Rank → Context → Validate → Judge → Learn
 
 <!--SM:benchmarkBlock-->
 ```
-Benchmark : sigmap-v8.11-main (21 repositories, including R language)
+Benchmark : sigmap-v8.12-main (21 repositories, including R language)
 Date      : 2026-07-11
 
 Hit@5          : 87.8%   (baseline 13.6%  — 6.5× lift)

package/gen-context.js

@@ -14043,7 +14043,7 @@ __factories["./src/mcp/server"] = function(module, exports) {
 
   const SERVER_INFO = {
     name: 'sigmap',
-    version: '8.11.0',
+    version: '8.12.0',
     description: 'SigMap MCP server — code signatures on demand',
   };
 
@@ -18625,6 +18625,260 @@ __factories["./src/verify/parsers"] = function(module, exports) {
   
 };
 
+// ── ./src/wiki/generate ──
+__factories["./src/wiki/generate"] = function(module, exports) {
+  
+  /**
+   * Wiki generation (D9) — `sigmap wiki`.
+   *
+   * Deterministic architecture narrative composed from data SigMap already
+   * computes: the signature index, the dependency graph, conventions, and the
+   * health score. Template prose only — no LLM, no network, no timestamps —
+   * so two runs on an unchanged repo produce byte-identical markdown.
+   */
+
+  const fs = require('fs');
+  const path = require('path');
+
+  const HUB_LIMIT = 8;
+  const ENTRY_LIMIT = 8;
+  const MODULE_LIMIT = 20;
+  const KEY_FILE_LIMIT = 3;
+
+  // Graph keys come from src/graph/builder's normalizePath (normalized +
+  // lowercased), so relativize against the same normalization of cwd.
+  function _rel(cwd, f) {
+    return path.relative(path.normalize(cwd).toLowerCase(), f).replace(/\\/g, '/');
+  }
+
+  function _pct(fraction) {
+    return Math.round(fraction * 100);
+  }
+
+  /** Project name + version from package.json, falling back to the dir name. */
+  function _identity(cwd) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf8'));
+      if (pkg && pkg.name) return { name: pkg.name, version: pkg.version || null };
+    } catch (_) {}
+    return { name: path.basename(cwd), version: null };
+  }
+
+  /** Module rollup from the signature index (keys are cwd-relative paths). */
+  function _modules(index) {
+    const groups = new Map();
+    let totalTokens = 0;
+    for (const [rel, sigs] of index.entries()) {
+      const parts = String(rel).replace(/\\/g, '/').split('/');
+      const mod = parts.length > 1 ? parts[0] : '.';
+      const tokens = Math.ceil((sigs || []).join('\n').length / 4);
+      totalTokens += tokens;
+      if (!groups.has(mod)) groups.set(mod, { name: mod, files: 0, tokens: 0, fileSigs: [] });
+      const g = groups.get(mod);
+      g.files++;
+      g.tokens += tokens;
+      g.fileSigs.push({ file: rel, sigCount: (sigs || []).length });
+    }
+    const modules = [...groups.values()]
+      .sort((a, b) => b.tokens - a.tokens || a.name.localeCompare(b.name))
+      .slice(0, MODULE_LIMIT)
+      .map((g) => ({
+        name: g.name,
+        files: g.files,
+        tokens: g.tokens,
+        keyFiles: g.fileSigs
+          .sort((a, b) => b.sigCount - a.sigCount || a.file.localeCompare(b.file))
+          .slice(0, KEY_FILE_LIMIT)
+          .map((f) => f.file),
+      }));
+    return { modules, totalTokens };
+  }
+
+  /** Hubs, entry points, and cycle count from the dependency graph. */
+  function _flow(cwd) {
+    try {
+      const { buildFromCwd } = __require('./src/graph/builder');
+      const { detectCycles } = __require('./src/map/import-graph');
+      const graph = buildFromCwd(cwd);
+      if (!graph || !graph.forward || graph.forward.size === 0) return null;
+
+      const importersOf = (f) => (graph.reverse.get(f) || []).length;
+      const hubs = [...graph.reverse.entries()]
+        .map(([f, importers]) => ({ file: _rel(cwd, f), importers: importers.length }))
+        .filter((h) => h.importers > 0)
+        .sort((a, b) => b.importers - a.importers || a.file.localeCompare(b.file))
+        .slice(0, HUB_LIMIT);
+
+      const entryPoints = [...graph.forward.entries()]
+        .filter(([f, deps]) => deps.length > 0 && importersOf(f) === 0)
+        .map(([f, deps]) => ({ file: _rel(cwd, f), imports: deps.length }))
+        .sort((a, b) => b.imports - a.imports || a.file.localeCompare(b.file))
+        .slice(0, ENTRY_LIMIT);
+
+      let cycles = 0;
+      try { cycles = detectCycles(graph.forward).length; } catch (_) {}
+
+      return { hubs, entryPoints, cycles, edges: graph.forward.size };
+    } catch (_) {
+      return null;
+    }
+  }
+
+  /** Conventions summary; index keys are resolved back to absolute paths. */
+  function _conventions(cwd, index) {
+    try {
+      const { extractConventions } = __require('./src/conventions/extract');
+      const files = [...index.keys()].map((rel) => path.join(cwd, rel));
+      const c = extractConventions(cwd, files);
+      return {
+        fileNaming: c.fileNaming
+          ? { dominant: c.fileNaming.dominant, pct: _pct(c.fileNaming.dominantPct || 0), tier: c.fileNaming.tier }
+          : null,
+        exportStyle: c.exportStyle
+          ? { dominant: c.exportStyle.dominant, pct: _pct(c.exportStyle.dominantPct || 0), tier: c.exportStyle.tier }
+          : null,
+        testFramework: c.testFramework || null,
+      };
+    } catch (_) {
+      return null;
+    }
+  }
+
+  function _health(cwd) {
+    try {
+      const { score } = __require('./src/health/scorer');
+      const h = score(cwd);
+      return { score: h.score, grade: h.grade };
+    } catch (_) {
+      return null;
+    }
+  }
+
+  /**
+   * Build the wiki. Every data source is optional — a repo with no context file
+   * or no resolvable graph still yields a valid document.
+   * @param {string} cwd
+   * @param {object} [opts]
+   * @param {string} [opts.version] SigMap version stamped in the header
+   * @returns {{ data: object, markdown: string }}
+   */
+  function buildWiki(cwd, opts = {}) {
+    let index = new Map();
+    try {
+      const { buildSigIndex } = __require('./src/retrieval/ranker');
+      index = buildSigIndex(cwd);
+    } catch (_) {}
+
+    const identity = _identity(cwd);
+    const { modules, totalTokens } = _modules(index);
+    const flow = _flow(cwd);
+    const conventions = index.size ? _conventions(cwd, index) : null;
+    const health = _health(cwd);
+
+    const data = {
+      name: identity.name,
+      version: identity.version,
+      files: index.size,
+      modules,
+      totalTokens,
+      flow,
+      conventions,
+      health,
+    };
+
+    return { data, markdown: renderWikiMarkdown(data, opts.version) };
+  }
+
+  /**
+   * Render the narrative markdown. Pure function of `data` — no clocks, no
+   * randomness — so output is byte-stable for a fixed repo state.
+   * @param {object} data
+   * @param {string} [sigmapVersion]
+   * @returns {string}
+   */
+  function renderWikiMarkdown(data, sigmapVersion) {
+    const L = [];
+    const title = data.version ? `${data.name} v${data.version}` : data.name;
+    L.push(`# ${title} — Architecture Wiki`);
+    L.push('');
+    L.push(`_Deterministically generated from signatures + dependency graph by SigMap${sigmapVersion ? ` v${sigmapVersion}` : ''} — no LLM. Regenerate: \`sigmap wiki\`._`);
+    L.push('');
+
+    L.push('## Overview');
+    if (data.files === 0) {
+      L.push('No signature index found yet — run `sigmap` (or `node gen-context.js`) to generate context, then regenerate this wiki.');
+    } else {
+      const fileWord = data.files === 1 ? 'indexed file' : 'indexed files';
+      const modWord = data.modules.length === 1 ? 'top-level module' : 'top-level modules';
+      L.push(`The codebase spans **${data.files} ${fileWord}** across **${data.modules.length} ${modWord}**, with ~${data.totalTokens} tokens of extracted signatures.`);
+      if (data.health) {
+        L.push(`Context health: **${data.health.score}/100 (${data.health.grade})**.`);
+      }
+    }
+    L.push('');
+
+    if (data.modules.length) {
+      L.push('## Modules');
+      L.push('| Module | Files | Sig tokens | Key files |');
+      L.push('|--------|-------|------------|-----------|');
+      for (const m of data.modules) {
+        L.push(`| \`${m.name}\` | ${m.files} | ~${m.tokens} | ${m.keyFiles.map((f) => `\`${f}\``).join(', ')} |`);
+      }
+      const top = data.modules[0];
+      L.push('');
+      L.push(`The largest module by signature volume is \`${top.name}\` (${top.files} files, ~${top.tokens} tokens) — start there for the core logic.`);
+      L.push('');
+    }
+
+    if (data.flow) {
+      L.push('## Dependency flow');
+      if (data.flow.hubs.length) {
+        L.push('The most depended-on files — changes here have the widest blast radius:');
+        L.push('');
+        L.push('| Hub file | Importers |');
+        L.push('|----------|-----------|');
+        for (const h of data.flow.hubs) L.push(`| \`${h.file}\` | ${h.importers} |`);
+        L.push('');
+      }
+      if (data.flow.entryPoints.length) {
+        L.push('Entry points (imported by nothing, importing the rest):');
+        L.push('');
+        for (const e of data.flow.entryPoints) L.push(`- \`${e.file}\` → ${e.imports} imports`);
+        L.push('');
+      }
+      L.push(data.flow.cycles
+        ? `**Dependency cycles:** ${data.flow.cycles} — untangle these first when refactoring.`
+        : '**Dependency cycles:** none detected.');
+      L.push('');
+    }
+
+    if (data.conventions) {
+      L.push('## Conventions');
+      const c = data.conventions;
+      const bits = [];
+      if (c.fileNaming && c.fileNaming.dominant) bits.push(`file naming is predominantly **${c.fileNaming.dominant}** (${c.fileNaming.pct}%, ${c.fileNaming.tier})`);
+      if (c.exportStyle && c.exportStyle.dominant) bits.push(`exports use the **${c.exportStyle.dominant}** style (${c.exportStyle.pct}%, ${c.exportStyle.tier})`);
+      if (c.testFramework) bits.push(`tests run on **${c.testFramework}**`);
+      L.push(bits.length
+        ? `In this repo, ${bits.join('; ')}. New code should match.`
+        : 'No dominant conventions detected (repo too small or styles mixed).');
+      L.push('');
+    }
+
+    L.push('## Navigating');
+    L.push('- `sigmap ask "<question>"` — ranked, budgeted mini-context for any task');
+    L.push('- `sigmap --impact <file>` / `--callers <symbol>` — blast radius before you change something');
+    L.push('- `sigmap evidence "<query>"` — machine-consumable Evidence Pack (JSON) for agents/CI');
+    L.push('- MCP: `get_architecture_overview`, `get_map`, `get_callee_signatures` for live agent access');
+    L.push('');
+
+    return L.join('\n');
+  }
+
+  module.exports = { buildWiki, renderWikiMarkdown };
+  
+};
+
 // ── ./src/workspace/detector ──
 __factories["./src/workspace/detector"] = function(module, exports) {
   
@@ -18733,7 +18987,7 @@ function __tryGit(args, opts = {}) {
   catch (_) { return ''; }
 }
 
-const VERSION = '8.11.0';
+const VERSION = '8.12.0';
 const MARKER = '\n\n## Auto-generated signatures\n<!-- Updated by gen-context.js -->\n';
 
 function requireSourceOrBundled(key) {
@@ -20607,6 +20861,7 @@ Usage:
   ${cmd} review-pr                         Audit a diff — scope drift, god-node edits, missing tests, security files (--staged, --base, --json, --markdown)
   ${cmd} review-pr --markdown              PR Evidence Report — branded Markdown (signatures + blast radius + tests) to post as a PR comment
   ${cmd} create "<task>"                   Grounded-creation pipeline: scaffold → verify-plan → verify-ai-output → review-pr (--staged)
+  ${cmd} wiki                              Deterministic architecture wiki from signatures + graph — no LLM (--json, --out <path>)
   ${cmd} squeeze <file|->                  Minimize a pasted stacktrace/CI-log/JSON blob (--json for stats)
   ${cmd} squeeze --response <file|->       Minimize an agent/tool response (same engine; also exposed as the squeeze_output MCP tool)
   ${cmd} ask "<query>" --squeeze           Auto-accept input minimization (no prompt; for scripts/CI)
@@ -22227,6 +22482,30 @@ function main() {
     process.exit(result.ok ? 0 : 1);
   }
 
+  // D9: `sigmap wiki` — deterministic architecture narrative (no LLM).
+  if (args[0] === 'wiki') {
+    const { buildWiki } = requireSourceOrBundled('./src/wiki/generate');
+    const result = buildWiki(cwd, { version: VERSION });
+    if (args.includes('--json')) {
+      process.stdout.write(JSON.stringify(result.data, null, 2) + '\n');
+      process.exit(0);
+    }
+    const outIdx = args.indexOf('--out');
+    const outRel = outIdx >= 0 && args[outIdx + 1] && !args[outIdx + 1].startsWith('--')
+      ? args[outIdx + 1]
+      : path.join('.context', 'WIKI.md');
+    const outPath = path.resolve(cwd, outRel);
+    try {
+      fs.mkdirSync(path.dirname(outPath), { recursive: true });
+      fs.writeFileSync(outPath, result.markdown, 'utf8');
+    } catch (e) {
+      console.error(`[sigmap] cannot write ${outPath}: ${e.message}`);
+      process.exit(1);
+    }
+    console.log(`[sigmap] wiki → ${path.relative(cwd, outPath)} (${result.data.files} files · ${result.data.modules.length} modules)`);
+    process.exit(0);
+  }
+
   // 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

@@ -11,13 +11,13 @@ 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: 8.11.0 | Benchmark: sigmap-v8.11-main (2026-07-11)
+# Version: 8.12.0 | Benchmark: sigmap-v8.12-main (2026-07-11)
 # 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-v8.11-main, 2026-07-11)
+## Core metrics (benchmark: sigmap-v8.12-main, 2026-07-11)
 
 | Metric | Without SigMap | With SigMap |
 |--------|----------------|-------------|
@@ -114,6 +114,7 @@ sigmap verify-plan <plan.md|->           Check a plan vs the live index — file
 sigmap review-pr                         Audit a diff — scope drift, god-node edits, missing tests, security files (--staged, --base, --json, --markdown)
 sigmap review-pr --markdown              PR Evidence Report — branded Markdown (signatures + blast radius + tests) to post as a PR comment
 sigmap create "<task>"                   Grounded-creation pipeline: scaffold → verify-plan → verify-ai-output → review-pr (--staged)
+sigmap wiki                              Deterministic architecture wiki from signatures + graph — no LLM (--json, --out <path>)
 sigmap squeeze <file|->                  Minimize a pasted stacktrace/CI-log/JSON blob (--json for stats)
 sigmap squeeze --response <file|->       Minimize an agent/tool response (same engine; also exposed as the squeeze_output MCP tool)
 sigmap ask "<query>" --squeeze           Auto-accept input minimization (no prompt; for scripts/CI)

package/llms.txt

@@ -11,7 +11,7 @@ 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: 8.11.0 | Benchmark: sigmap-v8.11-main (2026-07-11)
+# Version: 8.12.0 | Benchmark: sigmap-v8.12-main (2026-07-11)
 # 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
 
@@ -23,7 +23,7 @@ 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-v8.11-main, 2026-07-11)
+## Core metrics (benchmark: sigmap-v8.12-main, 2026-07-11)
 
 - hit@5 retrieval: 87.8% vs 13.6% random baseline (6.5× lift)
 - Token reduction: 97.0% average across benchmark repos

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigmap",
-  "version": "8.11.0",
+  "version": "8.12.0",
   "description": "The deterministic, verifiable grounding layer for AI code work — a zero-dependency signature-and-evidence map that grounds Claude, Cursor, Copilot, Aider, Windsurf, local LLMs & MCP agents against your real code (repo + installed libraries) so they stop hallucinating files, imports & APIs. Runs offline via npx; byte-stable output; ~97% token reduction as proof.",
   "main": "packages/core/index.js",
   "exports": {

package/packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigmap-cli",
-  "version": "8.11.0",
+  "version": "8.12.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": "8.11.0",
+  "version": "8.12.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: '8.11.0',
+  version: '8.12.0',
   description: 'SigMap MCP server — code signatures on demand',
 };
 

package/src/wiki/generate.js

@@ -0,0 +1,250 @@
+'use strict';
+
+/**
+ * Wiki generation (D9) — `sigmap wiki`.
+ *
+ * Deterministic architecture narrative composed from data SigMap already
+ * computes: the signature index, the dependency graph, conventions, and the
+ * health score. Template prose only — no LLM, no network, no timestamps —
+ * so two runs on an unchanged repo produce byte-identical markdown.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const HUB_LIMIT = 8;
+const ENTRY_LIMIT = 8;
+const MODULE_LIMIT = 20;
+const KEY_FILE_LIMIT = 3;
+
+// Graph keys come from src/graph/builder's normalizePath (normalized +
+// lowercased), so relativize against the same normalization of cwd.
+function _rel(cwd, f) {
+  return path.relative(path.normalize(cwd).toLowerCase(), f).replace(/\\/g, '/');
+}
+
+function _pct(fraction) {
+  return Math.round(fraction * 100);
+}
+
+/** Project name + version from package.json, falling back to the dir name. */
+function _identity(cwd) {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf8'));
+    if (pkg && pkg.name) return { name: pkg.name, version: pkg.version || null };
+  } catch (_) {}
+  return { name: path.basename(cwd), version: null };
+}
+
+/** Module rollup from the signature index (keys are cwd-relative paths). */
+function _modules(index) {
+  const groups = new Map();
+  let totalTokens = 0;
+  for (const [rel, sigs] of index.entries()) {
+    const parts = String(rel).replace(/\\/g, '/').split('/');
+    const mod = parts.length > 1 ? parts[0] : '.';
+    const tokens = Math.ceil((sigs || []).join('\n').length / 4);
+    totalTokens += tokens;
+    if (!groups.has(mod)) groups.set(mod, { name: mod, files: 0, tokens: 0, fileSigs: [] });
+    const g = groups.get(mod);
+    g.files++;
+    g.tokens += tokens;
+    g.fileSigs.push({ file: rel, sigCount: (sigs || []).length });
+  }
+  const modules = [...groups.values()]
+    .sort((a, b) => b.tokens - a.tokens || a.name.localeCompare(b.name))
+    .slice(0, MODULE_LIMIT)
+    .map((g) => ({
+      name: g.name,
+      files: g.files,
+      tokens: g.tokens,
+      keyFiles: g.fileSigs
+        .sort((a, b) => b.sigCount - a.sigCount || a.file.localeCompare(b.file))
+        .slice(0, KEY_FILE_LIMIT)
+        .map((f) => f.file),
+    }));
+  return { modules, totalTokens };
+}
+
+/** Hubs, entry points, and cycle count from the dependency graph. */
+function _flow(cwd) {
+  try {
+    const { buildFromCwd } = require('../graph/builder');
+    const { detectCycles } = require('../map/import-graph');
+    const graph = buildFromCwd(cwd);
+    if (!graph || !graph.forward || graph.forward.size === 0) return null;
+
+    const importersOf = (f) => (graph.reverse.get(f) || []).length;
+    const hubs = [...graph.reverse.entries()]
+      .map(([f, importers]) => ({ file: _rel(cwd, f), importers: importers.length }))
+      .filter((h) => h.importers > 0)
+      .sort((a, b) => b.importers - a.importers || a.file.localeCompare(b.file))
+      .slice(0, HUB_LIMIT);
+
+    const entryPoints = [...graph.forward.entries()]
+      .filter(([f, deps]) => deps.length > 0 && importersOf(f) === 0)
+      .map(([f, deps]) => ({ file: _rel(cwd, f), imports: deps.length }))
+      .sort((a, b) => b.imports - a.imports || a.file.localeCompare(b.file))
+      .slice(0, ENTRY_LIMIT);
+
+    let cycles = 0;
+    try { cycles = detectCycles(graph.forward).length; } catch (_) {}
+
+    return { hubs, entryPoints, cycles, edges: graph.forward.size };
+  } catch (_) {
+    return null;
+  }
+}
+
+/** Conventions summary; index keys are resolved back to absolute paths. */
+function _conventions(cwd, index) {
+  try {
+    const { extractConventions } = require('../conventions/extract');
+    const files = [...index.keys()].map((rel) => path.join(cwd, rel));
+    const c = extractConventions(cwd, files);
+    return {
+      fileNaming: c.fileNaming
+        ? { dominant: c.fileNaming.dominant, pct: _pct(c.fileNaming.dominantPct || 0), tier: c.fileNaming.tier }
+        : null,
+      exportStyle: c.exportStyle
+        ? { dominant: c.exportStyle.dominant, pct: _pct(c.exportStyle.dominantPct || 0), tier: c.exportStyle.tier }
+        : null,
+      testFramework: c.testFramework || null,
+    };
+  } catch (_) {
+    return null;
+  }
+}
+
+function _health(cwd) {
+  try {
+    const { score } = require('../health/scorer');
+    const h = score(cwd);
+    return { score: h.score, grade: h.grade };
+  } catch (_) {
+    return null;
+  }
+}
+
+/**
+ * Build the wiki. Every data source is optional — a repo with no context file
+ * or no resolvable graph still yields a valid document.
+ * @param {string} cwd
+ * @param {object} [opts]
+ * @param {string} [opts.version] SigMap version stamped in the header
+ * @returns {{ data: object, markdown: string }}
+ */
+function buildWiki(cwd, opts = {}) {
+  let index = new Map();
+  try {
+    const { buildSigIndex } = require('../retrieval/ranker');
+    index = buildSigIndex(cwd);
+  } catch (_) {}
+
+  const identity = _identity(cwd);
+  const { modules, totalTokens } = _modules(index);
+  const flow = _flow(cwd);
+  const conventions = index.size ? _conventions(cwd, index) : null;
+  const health = _health(cwd);
+
+  const data = {
+    name: identity.name,
+    version: identity.version,
+    files: index.size,
+    modules,
+    totalTokens,
+    flow,
+    conventions,
+    health,
+  };
+
+  return { data, markdown: renderWikiMarkdown(data, opts.version) };
+}
+
+/**
+ * Render the narrative markdown. Pure function of `data` — no clocks, no
+ * randomness — so output is byte-stable for a fixed repo state.
+ * @param {object} data
+ * @param {string} [sigmapVersion]
+ * @returns {string}
+ */
+function renderWikiMarkdown(data, sigmapVersion) {
+  const L = [];
+  const title = data.version ? `${data.name} v${data.version}` : data.name;
+  L.push(`# ${title} — Architecture Wiki`);
+  L.push('');
+  L.push(`_Deterministically generated from signatures + dependency graph by SigMap${sigmapVersion ? ` v${sigmapVersion}` : ''} — no LLM. Regenerate: \`sigmap wiki\`._`);
+  L.push('');
+
+  L.push('## Overview');
+  if (data.files === 0) {
+    L.push('No signature index found yet — run `sigmap` (or `node gen-context.js`) to generate context, then regenerate this wiki.');
+  } else {
+    const fileWord = data.files === 1 ? 'indexed file' : 'indexed files';
+    const modWord = data.modules.length === 1 ? 'top-level module' : 'top-level modules';
+    L.push(`The codebase spans **${data.files} ${fileWord}** across **${data.modules.length} ${modWord}**, with ~${data.totalTokens} tokens of extracted signatures.`);
+    if (data.health) {
+      L.push(`Context health: **${data.health.score}/100 (${data.health.grade})**.`);
+    }
+  }
+  L.push('');
+
+  if (data.modules.length) {
+    L.push('## Modules');
+    L.push('| Module | Files | Sig tokens | Key files |');
+    L.push('|--------|-------|------------|-----------|');
+    for (const m of data.modules) {
+      L.push(`| \`${m.name}\` | ${m.files} | ~${m.tokens} | ${m.keyFiles.map((f) => `\`${f}\``).join(', ')} |`);
+    }
+    const top = data.modules[0];
+    L.push('');
+    L.push(`The largest module by signature volume is \`${top.name}\` (${top.files} files, ~${top.tokens} tokens) — start there for the core logic.`);
+    L.push('');
+  }
+
+  if (data.flow) {
+    L.push('## Dependency flow');
+    if (data.flow.hubs.length) {
+      L.push('The most depended-on files — changes here have the widest blast radius:');
+      L.push('');
+      L.push('| Hub file | Importers |');
+      L.push('|----------|-----------|');
+      for (const h of data.flow.hubs) L.push(`| \`${h.file}\` | ${h.importers} |`);
+      L.push('');
+    }
+    if (data.flow.entryPoints.length) {
+      L.push('Entry points (imported by nothing, importing the rest):');
+      L.push('');
+      for (const e of data.flow.entryPoints) L.push(`- \`${e.file}\` → ${e.imports} imports`);
+      L.push('');
+    }
+    L.push(data.flow.cycles
+      ? `**Dependency cycles:** ${data.flow.cycles} — untangle these first when refactoring.`
+      : '**Dependency cycles:** none detected.');
+    L.push('');
+  }
+
+  if (data.conventions) {
+    L.push('## Conventions');
+    const c = data.conventions;
+    const bits = [];
+    if (c.fileNaming && c.fileNaming.dominant) bits.push(`file naming is predominantly **${c.fileNaming.dominant}** (${c.fileNaming.pct}%, ${c.fileNaming.tier})`);
+    if (c.exportStyle && c.exportStyle.dominant) bits.push(`exports use the **${c.exportStyle.dominant}** style (${c.exportStyle.pct}%, ${c.exportStyle.tier})`);
+    if (c.testFramework) bits.push(`tests run on **${c.testFramework}**`);
+    L.push(bits.length
+      ? `In this repo, ${bits.join('; ')}. New code should match.`
+      : 'No dominant conventions detected (repo too small or styles mixed).');
+    L.push('');
+  }
+
+  L.push('## Navigating');
+  L.push('- `sigmap ask "<question>"` — ranked, budgeted mini-context for any task');
+  L.push('- `sigmap --impact <file>` / `--callers <symbol>` — blast radius before you change something');
+  L.push('- `sigmap evidence "<query>"` — machine-consumable Evidence Pack (JSON) for agents/CI');
+  L.push('- MCP: `get_architecture_overview`, `get_map`, `get_callee_signatures` for live agent access');
+  L.push('');
+
+  return L.join('\n');
+}
+
+module.exports = { buildWiki, renderWikiMarkdown };