sigmap 7.0.1 → 7.1.0

package/CHANGELOG.md

@@ -10,6 +10,21 @@ Format: [Semantic Versioning](https://semver.org/)
 
 ---
 
+## [7.1.0] — 2026-06-16
+
+Minor release — a token-savings dashboard in the terminal, plus domain and sponsorship docs.
+
+### Added
+- **Token-savings dashboard — `sigmap gain` (#260):** surfaces cumulative savings right in the terminal — total tokens saved, % efficiency, estimated $ saved, latency, and a by-operation breakdown, plus `gain --all` for daily / weekly / monthly trends. Savings are captured per operation (`ask`, `generate`) into a dedicated local log `.context/gain.ndjson` (counts only — no paths, source, or query text). Capture is **default-on** and privacy-safe; opt out via `--no-track`, `SIGMAP_NO_TRACK=1`, or `config.gainTracking:false`. The legacy `usage.ndjson` / `--track` health log is unchanged. New `src/tracking/{aggregate,pricing}.js` (zero-dep aggregation + model→$/Mtok pricing) and `src/format/gain-terminal.js` (ANSI renderer, `NO_COLOR`/non-TTY safe). Flags: `gain --all | --json | --since <7d|ISO> | --top <n> | --model <name> | --reset`. "Saved" is labeled everywhere as an estimate vs the whole-file baseline.
+
+### Fixed
+- **Docs served at the sigmap.io root (#258):** the docs site now builds with base `/` (dropped the `/sigmap/` path prefix) and the project domain points to sigmap.io.
+
+### Changed
+- **Sponsorship transparency (#257):** README gained a Sponsor section with a tier ladder and funding goal; detail moved into `SPONSOR.md`, with an "About the maintainer" note and a low-barrier welcome.
+
+---
+
 ## [7.0.1] — 2026-06-14
 
 Patch release — supply-chain hardening and package hygiene, plus a wider star nudge.

package/README.md

@@ -100,7 +100,7 @@ Repos tested   : 21 (JavaScript, Python, Go, Rust, Java, R, C++, C#, Dart, Swift
 Measured on 90 coding tasks across 18 real public repos. No LLM API — fully reproducible.
 
 **Resources:**
-- [Full methodology →](https://manojmallick.github.io/sigmap/guide/benchmark.html)
+- [Full methodology →](https://sigmap.io/guide/benchmark.html)
 - [Benchmark suite (GitHub)](https://github.com/manojmallick/sigmap-benchmark-suite) — scripts, tasks, and raw data
 - [Benchmark data (Zenodo)](https://zenodo.org/records/19898842) — archived results for reproducibility
 
@@ -172,8 +172,8 @@ sigmap --adapter claude    # works with Claude Code
 **Open-source agents & local LLMs:**
 
 Use SigMap with open-source tools and fully self-hosted setups:
-- **[Open-source agents guide →](https://manojmallick.github.io/sigmap/guide/agents)** — OpenCode, Aider, OpenHands, Cline
-- **[Local LLMs guide →](https://manojmallick.github.io/sigmap/guide/local-llms)** — Ollama, llama.cpp, vLLM (no API keys, full privacy)
+- **[Open-source agents guide →](https://sigmap.io/guide/agents)** — OpenCode, Aider, OpenHands, Cline
+- **[Local LLMs guide →](https://sigmap.io/guide/local-llms)** — Ollama, llama.cpp, vLLM (no API keys, full privacy)
 
 **IDE extensions:**
 
@@ -219,21 +219,21 @@ sigmap --health
 | 👶 **New** | [Quick start guide](docs/readmes/GETTING_STARTED.md) — setup in 60 seconds |
 | ⚡ **Daily** | `sigmap ask` / `sigmap validate` / `sigmap judge` |
 | 🧠 **Advanced** | [Context strategies](docs/readmes/CONTEXT_STRATEGIES.md) · [MCP setup](docs/readmes/MCP_SETUP.md) |
-| 🏢 **Teams** | [Config reference](https://manojmallick.github.io/sigmap/guide/config.html) · [CI setup](docs/readmes/ENTERPRISE_SETUP.md) |
+| 🏢 **Teams** | [Config reference](https://sigmap.io/guide/config.html) · [CI setup](docs/readmes/ENTERPRISE_SETUP.md) |
 
 ---
 
 ## Docs
 
-**[manojmallick.github.io/sigmap](https://manojmallick.github.io/sigmap)**
+**[sigmap.io](https://sigmap.io)**
 
 | Section | Link |
 |---|---|
-| CLI reference (32 commands) | [cli.html](https://manojmallick.github.io/sigmap/guide/cli.html) |
-| Benchmark methodology | [benchmark.html](https://manojmallick.github.io/sigmap/guide/benchmark.html) |
-| Config reference | [config.html](https://manojmallick.github.io/sigmap/guide/config.html) |
-| Roadmap | [roadmap.html](https://manojmallick.github.io/sigmap/guide/roadmap.html) |
-| 31 languages | [generalization.html](https://manojmallick.github.io/sigmap/guide/generalization.html) |
+| CLI reference (32 commands) | [cli.html](https://sigmap.io/guide/cli.html) |
+| Benchmark methodology | [benchmark.html](https://sigmap.io/guide/benchmark.html) |
+| Config reference | [config.html](https://sigmap.io/guide/config.html) |
+| Roadmap | [roadmap.html](https://sigmap.io/guide/roadmap.html) |
+| 31 languages | [generalization.html](https://sigmap.io/guide/generalization.html) |
 
 ---
 
@@ -245,6 +245,14 @@ If SigMap saves you context or API spend, a ⭐ on [GitHub](https://github.com/m
 
 ---
 
+## Sponsor
+
+SigMap is built and maintained by one developer, kept **zero-dependency**, offline, and free. If it saves your team context or API spend, sponsoring keeps it that way — and funds the benchmark CI, the `sigmap.io` domain, and ongoing supply-chain hardening.
+
+💜 **[Become a sponsor →](https://github.com/sponsors/manojmallick)** · see **[SPONSOR.md](SPONSOR.md)** for tiers and exactly where your support goes. Any amount helps — even $1/mo — and a ⭐ or a share counts too.
+
+---
+
 ## Contributing
 
 SigMap welcomes contributions! 
@@ -284,7 +292,7 @@ TypeScript · JavaScript · Python · Java · Kotlin · Go · Rust · C# · C/C+
 
 All implemented with zero external dependencies.
 
-[Full language table →](https://manojmallick.github.io/sigmap/guide/generalization.html)
+[Full language table →](https://sigmap.io/guide/generalization.html)
 
 ---
 
@@ -296,7 +304,7 @@ MIT © 2026 [Manoj Mallick](https://github.com/manojmallick) · Made in Amsterda
 
 <div align="center">
 
-**[Docs](https://manojmallick.github.io/sigmap) · [Changelog](CHANGELOG.md) · [Roadmap](https://manojmallick.github.io/sigmap/roadmap.html) · [npm](https://www.npmjs.com/package/sigmap)**
+**[Docs](https://sigmap.io) · [Changelog](CHANGELOG.md) · [Roadmap](https://sigmap.io/roadmap.html) · [npm](https://www.npmjs.com/package/sigmap)**
 
 ⭐ [Star on GitHub](https://github.com/manojmallick/sigmap) if SigMap saves you tokens.
 

package/gen-context.js

@@ -6254,7 +6254,7 @@ const { readContext, searchSignatures, getMap, createCheckpoint, getRouting, exp
 
 const SERVER_INFO = {
   name: 'sigmap',
-  version: '7.0.1',
+  version: '7.1.0',
   description: 'SigMap MCP server — code signatures on demand',
 };
 
@@ -8928,6 +8928,20 @@ __factories["./src/discovery/source-root-registry"] = function(module, exports)
   module.exports = { REGISTRY };
 };
 
+// ── ./src/util/git ──
+__factories["./src/util/git"] = function(module, exports) {
+  'use strict';
+  const { execFileSync } = require('child_process');
+  function git(args, opts = {}) {
+    return execFileSync('git', args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], ...opts });
+  }
+  function tryGit(args, opts = {}) {
+    try { return git(args, opts).toString().trim(); }
+    catch (_) { return ''; }
+  }
+  module.exports = { git, tryGit };
+};
+
 // ── ./src/discovery/sigmapignore ──
 __factories["./src/discovery/sigmapignore"] = function(module, exports) {
   'use strict';
@@ -10947,7 +10961,7 @@ function __tryGit(args, opts = {}) {
   catch (_) { return ''; }
 }
 
-const VERSION = '7.0.1';
+const VERSION = '7.1.0';
 const MARKER = '\n\n## Auto-generated signatures\n<!-- Updated by gen-context.js -->\n';
 
 function requireSourceOrBundled(key) {
@@ -12180,6 +12194,7 @@ function runDiff(cwd, config, stagedOnly, baseRef) {
 // Core generate pipeline
 // ---------------------------------------------------------------------------
 function runGenerate(cwd, config, reportMode, reportJson = false) {
+  const __genT0 = Date.now();
   const ignorePatterns = loadIgnorePatterns(cwd);
   let allFiles = buildFileList(cwd, config);
 
@@ -12379,7 +12394,7 @@ function runGenerate(cwd, config, reportMode, reportJson = false) {
     printReport(result.inputTokenTotal, result.finalTokens, result.fileCount, result.droppedCount, reportJson, effectiveMaxTokens, result.coverageResult, config.autoMaxTokens !== false && effectiveMaxTokens !== config.maxTokens, config.maxTokens);
   }
 
-  // Usage tracking (v0.9) — optional append-only NDJSON log
+  // Usage tracking (v0.9) — legacy health log, opt-in via config.tracking / --track.
   const trackingEnabled = !!(config.tracking || process.argv.includes('--track'));
   if (trackingEnabled && !reportMode) {
     try {
@@ -12399,6 +12414,22 @@ function runGenerate(cwd, config, reportMode, reportJson = false) {
     }
   }
 
+  // gain: capture generate savings (separate gain.ndjson; default ON, opt-out).
+  if (!reportMode) {
+    try {
+      const { recordUsage, isTrackingEnabled } = requireSourceOrBundled('./src/tracking/logger');
+      if (isTrackingEnabled(config, process.argv)) {
+        recordUsage({
+          version: VERSION,
+          op: 'generate',
+          baselineTokens: result.inputTokenTotal,
+          actualTokens: result.finalTokens,
+          durationMs: Date.now() - __genT0,
+        }, cwd);
+      }
+    } catch (_) { /* gain capture is best-effort */ }
+  }
+
   // Feature 8: post-run summary — 6-line stdout after every normal run
   if (!reportMode
     && !process.argv.includes('--json')
@@ -12695,6 +12726,13 @@ Usage:
   ${cmd} --suggest-tool "<task>" --json    Machine-readable tier recommendation
   ${cmd} --health                          Print composite health score
   ${cmd} --health --json                   Machine-readable health score
+  ${cmd} gain                              Token-savings dashboard (totals + by-operation)
+  ${cmd} gain --all                        Add daily / weekly / monthly trend tables
+  ${cmd} gain --json                       Aggregate savings as JSON
+  ${cmd} gain --since 7d                    Window filter (7d, 30d, 12h, or ISO date)
+  ${cmd} gain --top <n> | --model <name>   Limit rows / set $ pricing model
+  ${cmd} gain --reset                      Clear the local savings log (.context/gain.ndjson)
+  ${cmd} ... --no-track                    Disable gain savings capture for this run
   ${cmd} --diff                            Generate context for git-changed files only
   ${cmd} --diff <base-ref>                 Generate context + structural diff vs base ref (e.g. main)
   ${cmd} --diff --staged                   Generate context for staged files only
@@ -13094,6 +13132,7 @@ function main() {
 
   // v4.2: `sigmap ask "<query>"` — unified pipeline
   if (args[0] === 'ask') {
+    const __askT0 = Date.now();
     // v6.8: Handle --followup flag which may appear before or after query
     let query = args[1];
     if (query === '--followup' && args[2]) {
@@ -13261,6 +13300,21 @@ function main() {
         bar,
       ].join('\n'));
     }
+    // gain: capture this query's savings for the `sigmap gain` dashboard.
+    try {
+      const { recordUsage, isTrackingEnabled } = requireSourceOrBundled('./src/tracking/logger');
+      if (isTrackingEnabled(config, args)) {
+        recordUsage({
+          version: VERSION,
+          op: 'ask',
+          baselineTokens: rawTok,
+          actualTokens: ctxTok,
+          durationMs: Date.now() - __askT0,
+          model,
+        }, cwd);
+      }
+    } catch (_) { /* gain capture is best-effort */ }
+
     // v7.0.0: record the run and show the one-time star nudge (interactive only).
     try {
       const { checkStarNudge } = requireSourceOrBundled('./src/nudge');
@@ -13273,6 +13327,44 @@ function main() {
     process.exit(0);
   }
 
+  // `sigmap gain` — token-savings dashboard (totals, by-operation, trends).
+  if (args[0] === 'gain') {
+    const valOf = (f, d) => { const i = args.indexOf(f); return i >= 0 && args[i + 1] ? args[i + 1] : d; };
+    if (args.includes('--reset')) {
+      try {
+        const { GAIN_FILE } = requireSourceOrBundled('./src/tracking/logger');
+        const p = path.join(cwd, GAIN_FILE);
+        if (fs.existsSync(p)) fs.unlinkSync(p);
+        console.log('[sigmap] gain: usage log cleared.');
+      } catch (e) { console.error(`[sigmap] gain: ${e.message}`); }
+      process.exit(0);
+    }
+    try {
+      const { readGainLog } = requireSourceOrBundled('./src/tracking/logger');
+      const { aggregate } = requireSourceOrBundled('./src/tracking/aggregate');
+      const { renderSummary, renderBreakdown } = requireSourceOrBundled('./src/format/gain-terminal');
+      const records = readGainLog(cwd);
+      const agg = aggregate(records, {
+        model: valOf('--model', 'claude-sonnet'),
+        since: valOf('--since', null),
+        top: parseInt(valOf('--top', args.includes('--all') ? '0' : '10'), 10),
+      });
+      if (args.includes('--json')) {
+        process.stdout.write(JSON.stringify(agg, null, 2) + '\n');
+      } else {
+        const out = args.includes('--all')
+          ? renderSummary(agg, { version: VERSION }) + '\n' + renderBreakdown(agg)
+          : renderSummary(agg, { version: VERSION });
+        process.stdout.write(out + '\n');
+      }
+    } catch (e) {
+      console.error(`[sigmap] gain: ${e.message}`);
+      console.error('  (gain modules require src/ — for single-file installs, regenerate the bundle)');
+      process.exit(1);
+    }
+    process.exit(0);
+  }
+
   // v4.2: `sigmap suggest-profile` — auto-detect task type from git state
   if (args[0] === 'suggest-profile') {
     const short = args.includes('--short');
@@ -13359,7 +13451,7 @@ function main() {
     const shareText = [
       'Generated with SigMap — zero-dependency AI context engine',
       `${reduction}% fewer tokens · ${hitAt5}% retrieval accuracy · 6× better results`,
-      'https://sigmap.dev',
+      'https://sigmap.io',
     ].join('\n');
 
     console.log(shareText);

package/llms-full.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.0.1 | Benchmark: sigmap-v7.0-main (2026-06-14)
+# Version: 7.1.0 | Benchmark: sigmap-v7.0-main (2026-06-14)
 # Source: auto-generated from package.json, version.json, src/mcp/tools.js, src/config/defaults.js
 # Regenerate: npm run generate:llms   |   Validate: npm run validate:llms
 
@@ -67,6 +67,13 @@ sigmap --suggest-tool "<task>"           Recommend model tier for a task descrip
 sigmap --suggest-tool "<task>" --json    Machine-readable tier recommendation
 sigmap --health                          Print composite health score
 sigmap --health --json                   Machine-readable health score
+sigmap gain                              Token-savings dashboard (totals + by-operation)
+sigmap gain --all                        Add daily / weekly / monthly trend tables
+sigmap gain --json                       Aggregate savings as JSON
+sigmap gain --since 7d                    Window filter (7d, 30d, 12h, or ISO date)
+sigmap gain --top <n> | --model <name>   Limit rows / set $ pricing model
+sigmap gain --reset                      Clear the local savings log (.context/gain.ndjson)
+sigmap ... --no-track                    Disable gain savings capture for this run
 sigmap --diff                            Generate context for git-changed files only
 sigmap --diff <base-ref>                 Generate context + structural diff vs base ref (e.g. main)
 sigmap --diff --staged                   Generate context for staged files only
@@ -273,7 +280,7 @@ the relevant regulation before publication; SigMap makes no legal claims.
 - Author: Manoj Mallick
 - License: MIT
 - Repository: https://github.com/manojmallick/sigmap
-- Documentation: https://manojmallick.github.io/sigmap/
+- Documentation: https://sigmap.io/
 - npm: https://www.npmjs.com/package/sigmap
 - Benchmark dataset: https://doi.org/10.5281/zenodo.19898842
 - Issues: https://github.com/manojmallick/sigmap/issues

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.0.1 | Benchmark: sigmap-v7.0-main (2026-06-14)
+# Version: 7.1.0 | Benchmark: sigmap-v7.0-main (2026-06-14)
 # Source: auto-generated from package.json, version.json, src/mcp/tools.js, src/config/defaults.js
 # Regenerate: npm run generate:llms   |   Validate: npm run validate:llms
 
@@ -39,18 +39,18 @@ npx sigmap --mcp                    # start the MCP server over stdio
 ```
 
 ## Docs
-- [Full documentation](https://manojmallick.github.io/sigmap/)
-- [CLI reference](https://manojmallick.github.io/sigmap/guide/cli)
-- [MCP tools](https://manojmallick.github.io/sigmap/guide/mcp)
-- [Benchmark methodology](https://manojmallick.github.io/sigmap/guide/benchmark)
-- [Configuration guide](https://manojmallick.github.io/sigmap/guide/config)
+- [Full documentation](https://sigmap.io/)
+- [CLI reference](https://sigmap.io/guide/cli)
+- [MCP tools](https://sigmap.io/guide/mcp)
+- [Benchmark methodology](https://sigmap.io/guide/benchmark)
+- [Configuration guide](https://sigmap.io/guide/config)
 - [Changelog](https://github.com/manojmallick/sigmap/blob/main/CHANGELOG.md)
 
 ## Optional
 - [GitHub repository](https://github.com/manojmallick/sigmap)
 - [npm package](https://www.npmjs.com/package/sigmap)
 - [Benchmark dataset (Zenodo)](https://doi.org/10.5281/zenodo.19898842)
-- [Full LLM reference](https://manojmallick.github.io/sigmap/llms-full.txt)
+- [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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigmap",
-  "version": "7.0.1",
+  "version": "7.1.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": {
@@ -82,7 +82,7 @@
     "type": "git",
     "url": "https://github.com/manojmallick/sigmap.git"
   },
-  "homepage": "https://manojmallick.github.io/sigmap/",
+  "homepage": "https://sigmap.io/",
   "bugs": {
     "url": "https://github.com/manojmallick/sigmap/issues"
   },

package/packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigmap-cli",
-  "version": "7.0.1",
+  "version": "7.1.0",
   "description": "SigMap CLI wrapper — thin adapter for programmatic CLI invocation",
   "main": "index.js",
   "keywords": [
@@ -18,7 +18,7 @@
     "url": "https://github.com/manojmallick/sigmap.git",
     "directory": "packages/cli"
   },
-  "homepage": "https://manojmallick.github.io/sigmap/",
+  "homepage": "https://sigmap.io/",
   "license": "MIT",
   "engines": {
     "node": ">=18.0.0"

package/packages/core/README.md

@@ -1,6 +1,6 @@
 # sigmap-core
 
-Programmatic API for [SigMap](https://manojmallick.github.io/sigmap/) — zero-dependency code signature extraction, ranked retrieval, secret scanning, project health scoring, and multi-adapter output formatting (v3.0+).
+Programmatic API for [SigMap](https://sigmap.io/) — zero-dependency code signature extraction, ranked retrieval, secret scanning, project health scoring, and multi-adapter output formatting (v3.0+).
 
 ## Installation
 
@@ -145,7 +145,7 @@ const geminiInstruction = adapt(context, 'gemini');
 // All 6 adapters: copilot | claude | cursor | windsurf | openai | gemini
 ```
 
-See the full [roadmap](https://manojmallick.github.io/sigmap/roadmap.html).
+See the full [roadmap](https://sigmap.io/roadmap.html).
 
 ## Zero dependencies
 

package/packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigmap-core",
-  "version": "7.0.1",
+  "version": "7.1.0",
   "description": "SigMap core library — zero-dependency code signature extraction, retrieval, and security scanning",
   "main": "index.js",
   "keywords": [
@@ -20,7 +20,7 @@
     "url": "https://github.com/manojmallick/sigmap.git",
     "directory": "packages/core"
   },
-  "homepage": "https://manojmallick.github.io/sigmap/",
+  "homepage": "https://sigmap.io/",
   "license": "MIT",
   "engines": {
     "node": ">=18.0.0"

package/src/format/gain-terminal.js

@@ -0,0 +1,206 @@
+'use strict';
+
+/**
+ * SigMap `gain` — terminal renderer.
+ *
+ * Zero-dependency ANSI dashboard for token savings. Honors NO_COLOR and
+ * non-TTY output (plain text for pipes / --json consumers elsewhere).
+ *
+ * "saved" is a counterfactual estimate (whole-file baseline − actual context),
+ * never a measured delta — the footer says so on every view.
+ */
+
+const USE_COLOR = !process.env.NO_COLOR && process.stdout.isTTY;
+
+const C = {
+  reset: USE_COLOR ? '\x1b[0m' : '',
+  dim: USE_COLOR ? '\x1b[2m' : '',
+  bold: USE_COLOR ? '\x1b[1m' : '',
+  green: USE_COLOR ? '\x1b[32m' : '',
+  yellow: USE_COLOR ? '\x1b[33m' : '',
+  red: USE_COLOR ? '\x1b[31m' : '',
+  cyan: USE_COLOR ? '\x1b[36m' : '',
+  gray: USE_COLOR ? '\x1b[90m' : '',
+};
+
+// ── formatters ───────────────────────────────────────────────────────────
+function humanTokens(n) {
+  n = Number(n) || 0;
+  if (n >= 1e9) return (n / 1e9).toFixed(1) + 'B';
+  if (n >= 1e6) return (n / 1e6).toFixed(1) + 'M';
+  if (n >= 1e3) return (n / 1e3).toFixed(1) + 'K';
+  return String(Math.round(n));
+}
+
+function fmtInt(n) {
+  return (Number(n) || 0).toLocaleString('en-US');
+}
+
+function fmtUSD(n) {
+  n = Number(n) || 0;
+  if (n >= 1000) return '$' + n.toLocaleString('en-US', { maximumFractionDigits: 0 });
+  return '$' + n.toFixed(2);
+}
+
+function fmtDuration(ms) {
+  ms = Number(ms) || 0;
+  if (ms >= 3.6e6) return (ms / 3.6e6).toFixed(1) + 'h';
+  if (ms >= 60000) return (ms / 60000).toFixed(1) + 'm';
+  if (ms >= 1000) return (ms / 1000).toFixed(1) + 's';
+  return Math.round(ms) + 'ms';
+}
+
+function fmtPct(p) {
+  return (Number(p) || 0).toFixed(1) + '%';
+}
+
+function colorPct(p, text) {
+  if (!USE_COLOR) return text;
+  const c = p >= 85 ? C.green : p >= 60 ? C.yellow : C.red;
+  return c + text + C.reset;
+}
+
+function pad(s, w, align) {
+  s = String(s);
+  const visible = s.replace(/\x1b\[[0-9;]*m/g, '');
+  const gap = Math.max(0, w - visible.length);
+  return align === 'right' ? ' '.repeat(gap) + s : s + ' '.repeat(gap);
+}
+
+/** Solid horizontal efficiency bar with a dotted remainder. */
+function bar(pct, width) {
+  const filled = Math.round((clamp(pct, 0, 100) / 100) * width);
+  const solid = '█'.repeat(filled);
+  const rest = '░'.repeat(Math.max(0, width - filled));
+  return (USE_COLOR ? C.green : '') + solid + (USE_COLOR ? C.gray : '') + rest + C.reset;
+}
+
+/** Proportional impact bar (share of total saved). */
+function impactBar(sharePct, width) {
+  const n = Math.max(1, Math.round((clamp(sharePct, 0, 100) / 100) * width));
+  return (USE_COLOR ? C.cyan : '') + '█'.repeat(n) + C.reset;
+}
+
+const clamp = (n, lo, hi) => Math.max(lo, Math.min(hi, n));
+const rule = (w) => C.gray + '─'.repeat(w) + C.reset;
+
+// ── views ──────────────────────────────────────────────────────────────
+/**
+ * Render the global summary + by-operation table.
+ * @param {object} agg     output of aggregate()
+ * @param {object} [opts]  { version, scope }
+ * @returns {string}
+ */
+function renderSummary(agg, opts = {}) {
+  const W = 74;
+  const t = agg.totals;
+  const L = [];
+  const scope = opts.scope || 'this repo';
+  const ver = opts.version ? `v${opts.version}` : '';
+
+  L.push('');
+  const heading = `⚡ SigMap — Token Savings (${scope})`;
+  L.push('  ' + C.bold + C.cyan + heading + C.reset +
+    pad(`${C.green}✓${C.reset} ${C.dim}${ver}${C.reset}`, W - heading.length, 'right'));
+  L.push('  ' + rule(W));
+  L.push('');
+
+  if (t.count === 0) {
+    L.push(`  ${C.yellow}No usage recorded yet.${C.reset}`);
+    L.push(`  ${C.dim}Run a few queries (sigmap ask "...") or seed a demo:${C.reset}`);
+    L.push(`  ${C.dim}  node scripts/gain.mjs --demo${C.reset}`);
+    L.push('');
+    return L.join('\n');
+  }
+
+  const label = (k) => C.dim + pad(k, 21) + C.reset;
+  L.push('  ' + label('Total operations') + ': ' + C.bold + fmtInt(t.count) + C.reset);
+  L.push('  ' + label('Whole-file baseline') + ': ' + humanTokens(t.baseline) + ' tok' +
+    `   ${C.dim}← est. cost of feeding full files${C.reset}`);
+  L.push('  ' + label('SigMap context') + ': ' + humanTokens(t.actual) + ' tok');
+  L.push('  ' + label('Tokens saved') + ': ' + C.bold + humanTokens(t.saved) + C.reset +
+    '  (' + colorPct(t.savedPct, fmtPct(t.savedPct)) + ')');
+  L.push('  ' + label('Est. money saved') + ': ' + C.bold + C.green + fmtUSD(t.usdSaved) + C.reset +
+    `   ${C.dim}(${agg.price.model} input @ $${agg.price.perMtok}/M · --model to change)${C.reset}`);
+  L.push('  ' + label('Avg latency') + ': ' + fmtDuration(t.avgMs) + ' / op' +
+    `   ${C.dim}(local, no API round-trip)${C.reset}`);
+  L.push('');
+  L.push('  ' + label('Efficiency') + ': ▕' + bar(t.savedPct, 30) + '▏  ' +
+    colorPct(t.savedPct, C.bold + fmtPct(t.savedPct) + C.reset));
+  L.push('');
+
+  // By operation table
+  L.push(`  ${C.bold}By operation${C.reset}`);
+  L.push('  ' + rule(W));
+  L.push('  ' + C.dim +
+    pad('#', 3) + pad('Operation', 24) + pad('Count', 8, 'right') +
+    pad('Saved', 9, 'right') + pad('Avg%', 8, 'right') + pad('Time', 8, 'right') +
+    '  Impact' + C.reset);
+  agg.byOp.forEach((o, i) => {
+    L.push('  ' +
+      pad(`${i + 1}.`, 3) +
+      pad(o.op, 24) +
+      pad(fmtInt(o.count), 8, 'right') +
+      pad(humanTokens(o.saved), 9, 'right') +
+      pad(colorPct(o.avgPct, fmtPct(o.avgPct)), 8, 'right') +
+      pad(fmtDuration(o.avgMs), 8, 'right') +
+      '  ' + impactBar(o.sharePct, 12));
+  });
+  L.push('  ' + rule(W));
+  L.push(`  ${C.dim}saved = baseline − actual · estimated vs whole-file reads · local-only${C.reset}`);
+  L.push('');
+  return L.join('\n');
+}
+
+/**
+ * Render daily / weekly / monthly trend tables.
+ * @param {object} agg
+ * @returns {string}
+ */
+function renderBreakdown(agg) {
+  const L = [];
+  if (agg.totals.count === 0) return renderSummary(agg);
+
+  const section = (icon, title, rows, keyHeader) => {
+    L.push('');
+    L.push(`  ${C.bold}${icon} ${title}${C.reset}`);
+    L.push('  ' + C.dim +
+      pad(keyHeader, 14) + pad('Ops', 7, 'right') + pad('Baseline', 11, 'right') +
+      pad('Actual', 10, 'right') + pad('Saved', 10, 'right') + pad('Save%', 8, 'right') +
+      pad('Time', 8, 'right') + C.reset);
+    let TB = 0, TA = 0, TS = 0, TC = 0, TM = 0;
+    for (const r of rows) {
+      TB += r.baseline; TA += r.actual; TS += r.saved; TC += r.count; TM += r.ms;
+      L.push('  ' +
+        pad(r.key, 14) + pad(fmtInt(r.count), 7, 'right') +
+        pad(humanTokens(r.baseline), 11, 'right') + pad(humanTokens(r.actual), 10, 'right') +
+        pad(humanTokens(r.saved), 10, 'right') +
+        pad(colorPct(r.savedPct, fmtPct(r.savedPct)), 8, 'right') +
+        pad(fmtDuration(r.ms), 8, 'right'));
+    }
+    const tp = TB > 0 ? (TS / TB) * 100 : 0;
+    L.push('  ' + C.bold +
+      pad('TOTAL', 14) + pad(fmtInt(TC), 7, 'right') +
+      pad(humanTokens(TB), 11, 'right') + pad(humanTokens(TA), 10, 'right') +
+      pad(humanTokens(TS), 10, 'right') + pad(fmtPct(tp), 8, 'right') +
+      pad(fmtDuration(TM), 8, 'right') + C.reset);
+  };
+
+  const daily = agg.buckets.daily.slice(-30);
+  section('📅', `Daily (last ${daily.length})`, daily, 'Date');
+  const weekly = agg.buckets.weekly.slice(-6);
+  section('📆', `Weekly (last ${weekly.length})`, weekly, 'Week of');
+  const monthly = agg.buckets.monthly.slice(-3);
+  section('🗓️', `Monthly (last ${monthly.length})`, monthly, 'Month');
+  L.push('');
+  L.push(`  ${C.dim}saved = baseline − actual · estimated vs whole-file reads · local-only${C.reset}`);
+  L.push('');
+  return L.join('\n');
+}
+
+module.exports = {
+  renderSummary,
+  renderBreakdown,
+  // exported for tests
+  humanTokens, fmtUSD, fmtDuration, fmtPct,
+};

package/src/mcp/server.js

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

package/src/tracking/aggregate.js

@@ -0,0 +1,195 @@
+'use strict';
+
+/**
+ * SigMap usage aggregation for the `gain` dashboard.
+ *
+ * Pure, zero-dependency functions that turn raw NDJSON usage records into the
+ * totals / by-operation / time-bucket shapes the terminal renderer consumes.
+ *
+ * Tolerant of BOTH schemas:
+ *   - new:    { op, baselineTokens, actualTokens, savedTokens, savedPct, durationMs, model }
+ *   - legacy: { rawTokens, finalTokens, reductionPct }   (from logger.js v0.9)
+ *
+ * "saved" is a counterfactual estimate (baseline − actual), never a measured
+ * delta. Callers are responsible for labeling it as such in the UI.
+ */
+
+const { resolvePrice } = require('./pricing');
+
+const clamp = (n, lo, hi) => Math.max(lo, Math.min(hi, n));
+
+/**
+ * Normalize one raw record into a canonical shape.
+ * @param {object} rec
+ */
+function normalize(rec) {
+  const baseline = num(rec.baselineTokens != null ? rec.baselineTokens : rec.rawTokens);
+  const actual = num(rec.actualTokens != null ? rec.actualTokens : rec.finalTokens);
+  const saved = rec.savedTokens != null ? num(rec.savedTokens) : Math.max(0, baseline - actual);
+  const savedPct = rec.savedPct != null
+    ? num(rec.savedPct)
+    : rec.reductionPct != null
+      ? num(rec.reductionPct)
+      : baseline > 0 ? (saved / baseline) * 100 : 0;
+  return {
+    ts: rec.ts || null,
+    op: normalizeOp(rec.op),
+    baseline,
+    actual,
+    saved,
+    savedPct: clamp(savedPct, 0, 100),
+    durationMs: num(rec.durationMs),
+    model: rec.model || null,
+  };
+}
+
+function normalizeOp(op) {
+  if (!op) return 'generate';
+  return String(op);
+}
+
+function num(v) {
+  const n = Number(v);
+  return Number.isFinite(n) ? n : 0;
+}
+
+/**
+ * Parse a --since value into a cutoff Date (or null for "all time").
+ * Accepts: "7d", "30d", "12h", or an ISO date "2026-06-01".
+ * @param {string} since
+ * @param {number} [nowMs] - injectable clock for tests
+ * @returns {Date|null}
+ */
+function parseSince(since, nowMs) {
+  if (!since) return null;
+  const now = nowMs != null ? nowMs : Date.now();
+  const rel = /^(\d+)([dhw])$/.exec(String(since).trim());
+  if (rel) {
+    const n = parseInt(rel[1], 10);
+    const unit = rel[2];
+    const ms = unit === 'h' ? 3.6e6 : unit === 'w' ? 6.048e8 : 8.64e7;
+    return new Date(now - n * ms);
+  }
+  const d = new Date(since);
+  return Number.isNaN(d.getTime()) ? null : d;
+}
+
+/**
+ * Bucket records by calendar granularity.
+ * @param {object[]} records - normalized records
+ * @param {'day'|'week'|'month'} granularity
+ * @returns {Array<{key,count,baseline,actual,saved,savedPct,ms}>} ascending by key
+ */
+function bucketBy(records, granularity) {
+  const map = new Map();
+  for (const r of records) {
+    if (!r.ts) continue;
+    const key = bucketKey(r.ts, granularity);
+    if (!key) continue;
+    let b = map.get(key);
+    if (!b) { b = { key, count: 0, baseline: 0, actual: 0, saved: 0, ms: 0 }; map.set(key, b); }
+    b.count += 1;
+    b.baseline += r.baseline;
+    b.actual += r.actual;
+    b.saved += r.saved;
+    b.ms += r.durationMs;
+  }
+  return [...map.values()]
+    .map((b) => ({ ...b, savedPct: b.baseline > 0 ? clamp((b.saved / b.baseline) * 100, 0, 100) : 0 }))
+    .sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+}
+
+function bucketKey(ts, granularity) {
+  const d = new Date(ts);
+  if (Number.isNaN(d.getTime())) return null;
+  const y = d.getUTCFullYear();
+  const m = String(d.getUTCMonth() + 1).padStart(2, '0');
+  const day = String(d.getUTCDate()).padStart(2, '0');
+  if (granularity === 'month') return `${y}-${m}`;
+  if (granularity === 'week') {
+    // ISO-ish: key by the Monday (UTC) of that week.
+    const tmp = new Date(Date.UTC(y, d.getUTCMonth(), d.getUTCDate()));
+    const dow = (tmp.getUTCDay() + 6) % 7; // 0 = Monday
+    tmp.setUTCDate(tmp.getUTCDate() - dow);
+    return `${tmp.getUTCFullYear()}-${String(tmp.getUTCMonth() + 1).padStart(2, '0')}-${String(tmp.getUTCDate()).padStart(2, '0')}`;
+  }
+  return `${y}-${m}-${day}`;
+}
+
+/**
+ * Full aggregation for the `gain` dashboard.
+ * @param {object[]} rawRecords
+ * @param {object} [opts]
+ * @param {string} [opts.model]   pricing model
+ * @param {string} [opts.since]   window filter
+ * @param {number} [opts.top]     limit byOp rows (0 = all)
+ * @param {number} [opts.nowMs]   injectable clock
+ * @returns {object}
+ */
+function aggregate(rawRecords, opts = {}) {
+  const price = resolvePrice(opts.model);
+  const cutoff = parseSince(opts.since, opts.nowMs);
+
+  let records = (rawRecords || []).map(normalize);
+  if (cutoff) records = records.filter((r) => r.ts && new Date(r.ts) >= cutoff);
+
+  const totals = {
+    count: records.length,
+    baseline: 0,
+    actual: 0,
+    saved: 0,
+    totalMs: 0,
+    savedPct: 0,
+    avgMs: 0,
+    usdSaved: 0,
+    firstTs: null,
+    lastTs: null,
+  };
+
+  const opMap = new Map();
+  for (const r of records) {
+    totals.baseline += r.baseline;
+    totals.actual += r.actual;
+    totals.saved += r.saved;
+    totals.totalMs += r.durationMs;
+    if (r.ts) {
+      if (!totals.firstTs || r.ts < totals.firstTs) totals.firstTs = r.ts;
+      if (!totals.lastTs || r.ts > totals.lastTs) totals.lastTs = r.ts;
+    }
+    let o = opMap.get(r.op);
+    if (!o) { o = { op: r.op, count: 0, baseline: 0, saved: 0, ms: 0 }; opMap.set(r.op, o); }
+    o.count += 1;
+    o.baseline += r.baseline;
+    o.saved += r.saved;
+    o.ms += r.durationMs;
+  }
+
+  totals.savedPct = totals.baseline > 0 ? clamp((totals.saved / totals.baseline) * 100, 0, 100) : 0;
+  totals.avgMs = totals.count > 0 ? Math.round(totals.totalMs / totals.count) : 0;
+  totals.usdSaved = totals.saved * price.perToken;
+
+  let byOp = [...opMap.values()].map((o) => ({
+    op: o.op,
+    count: o.count,
+    saved: o.saved,
+    avgPct: o.baseline > 0 ? clamp((o.saved / o.baseline) * 100, 0, 100) : 0,
+    avgMs: o.count > 0 ? Math.round(o.ms / o.count) : 0,
+    usdSaved: o.saved * price.perToken,
+    sharePct: totals.saved > 0 ? (o.saved / totals.saved) * 100 : 0,
+  })).sort((a, b) => b.saved - a.saved);
+
+  if (opts.top && opts.top > 0) byOp = byOp.slice(0, opts.top);
+
+  return {
+    price,
+    totals,
+    byOp,
+    buckets: {
+      daily: bucketBy(records, 'day'),
+      weekly: bucketBy(records, 'week'),
+      monthly: bucketBy(records, 'month'),
+    },
+  };
+}
+
+module.exports = { aggregate, bucketBy, parseSince, normalize };

package/src/tracking/logger.js

@@ -18,6 +18,9 @@ const fs = require('fs');
 const path = require('path');
 
 const LOG_FILE = path.join('.context', 'usage.ndjson');
+// Dedicated log for the `gain` dashboard (extended schema). Kept separate from
+// usage.ndjson so the legacy health/nudge history never collides with it.
+const GAIN_FILE = path.join('.context', 'gain.ndjson');
 
 /**
  * Append one run entry to the usage log.
@@ -73,6 +76,25 @@ function readLog(cwd) {
   }
 }
 
+/**
+ * Read and parse all `gain` dashboard records (oldest first).
+ * @param {string} cwd
+ * @returns {object[]}
+ */
+function readGainLog(cwd) {
+  try {
+    const logPath = path.join(cwd, GAIN_FILE);
+    if (!fs.existsSync(logPath)) return [];
+    return fs.readFileSync(logPath, 'utf8')
+      .split('\n')
+      .filter(Boolean)
+      .map((line) => { try { return JSON.parse(line); } catch (_) { return null; } })
+      .filter(Boolean);
+  } catch (_) {
+    return [];
+  }
+}
+
 /**
  * Compute summary statistics from an array of log records.
  * @param {object[]} entries
@@ -112,4 +134,64 @@ function summarize(entries) {
   };
 }
 
-module.exports = { logRun, readLog, summarize };
+/**
+ * Whether `gain` savings capture is enabled. Default: ON (privacy-safe,
+ * local-only, counts only — no paths, source, or query text). This is
+ * intentionally decoupled from the legacy `config.tracking` flag (which gates
+ * the usage.ndjson health log and defaults OFF). Opt out of gain capture via:
+ *   config.gainTracking === false   ·   --no-track   ·   SIGMAP_NO_TRACK=1
+ * @param {object} [config]
+ * @param {string[]} [argv]
+ * @returns {boolean}
+ */
+function isTrackingEnabled(config, argv) {
+  const a = argv || (typeof process !== 'undefined' ? process.argv : []);
+  if (process.env && process.env.SIGMAP_NO_TRACK) return false;
+  if (a && a.includes('--no-track')) return false;
+  if (config && config.gainTracking === false) return false;
+  return true;
+}
+
+/**
+ * Append one operation to the usage log using the extended `gain` schema.
+ * Reuses the same NDJSON file as logRun and is tolerant of partial input.
+ * Never throws — tracking must never break the main process.
+ *
+ * @param {object} entry
+ * @param {string} entry.op             e.g. 'ask' | 'generate' | 'query' | 'mcp:get_map'
+ * @param {number} entry.baselineTokens whole-file / candidate baseline (counterfactual)
+ * @param {number} entry.actualTokens   tokens SigMap actually emitted
+ * @param {number} [entry.durationMs]
+ * @param {string} [entry.model]
+ * @param {string} [entry.version]
+ * @param {string} cwd
+ */
+function recordUsage(entry, cwd) {
+  try {
+    const logPath = path.join(cwd, GAIN_FILE);
+    const dir = path.dirname(logPath);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+    const baseline = Math.max(0, Number(entry.baselineTokens) || 0);
+    const actual = Math.max(0, Number(entry.actualTokens) || 0);
+    const saved = Math.max(0, baseline - actual);
+    const record = {
+      ts: new Date().toISOString(),
+      v: entry.version || '0.9.0',
+      op: entry.op || 'generate',
+      baselineTokens: baseline,
+      actualTokens: actual,
+      savedTokens: saved,
+      savedPct: baseline > 0 ? parseFloat(((saved / baseline) * 100).toFixed(1)) : 0,
+      durationMs: Math.max(0, Math.round(Number(entry.durationMs) || 0)),
+      model: entry.model || null,
+      ok: entry.ok !== false,
+    };
+    fs.appendFileSync(logPath, JSON.stringify(record) + '\n', 'utf8');
+  } catch (err) {
+    // Never crash the main process — tracking is optional.
+    if (process.stderr) process.stderr.write(`[sigmap] tracking: could not write log: ${err.message}\n`);
+  }
+}
+
+module.exports = { logRun, recordUsage, readLog, readGainLog, summarize, isTrackingEnabled, GAIN_FILE };

package/src/tracking/pricing.js

@@ -0,0 +1,43 @@
+'use strict';
+
+/**
+ * SigMap pricing table — input-token $/Mtok assumptions for the `gain` dashboard.
+ *
+ * These are ASSUMPTIONS used only to translate "tokens saved" into an estimated
+ * dollar figure. They are deliberately conservative and configurable via
+ *   --model <name>   or   config.pricingModel
+ * The `gain` views always print the model + rate inline so the $ is never
+ * presented as exact. Zero npm dependencies.
+ */
+
+// USD per 1,000,000 input tokens.
+const PRICES = {
+  'claude-sonnet': 3.0,
+  'claude-opus': 15.0,
+  'claude-haiku': 0.8,
+  'gpt-4o': 2.5,
+  'gpt-4o-mini': 0.15,
+  'gemini-1.5-pro': 1.25,
+  'gemini-1.5-flash': 0.075,
+};
+
+const DEFAULT_MODEL = 'claude-sonnet';
+
+/**
+ * Resolve a price (USD per token) for a model name.
+ * @param {string} [model]
+ * @returns {{ model: string, perMtok: number, perToken: number }}
+ */
+function resolvePrice(model) {
+  const key = (model || DEFAULT_MODEL).toLowerCase();
+  const perMtok = PRICES[key] != null ? PRICES[key] : PRICES[DEFAULT_MODEL];
+  const resolved = PRICES[key] != null ? key : DEFAULT_MODEL;
+  return { model: resolved, perMtok, perToken: perMtok / 1_000_000 };
+}
+
+/** @returns {string[]} known model keys */
+function listModels() {
+  return Object.keys(PRICES);
+}
+
+module.exports = { PRICES, DEFAULT_MODEL, resolvePrice, listModels };