sigmap 8.24.0 → 8.26.0

package/CHANGELOG.md

@@ -10,6 +10,30 @@ Format: [Semantic Versioning](https://semver.org/)
 
 ---
 
+## [8.26.0] — 2026-08-18
+
+Minor release — **"Agent Economy III" (v8.26, F3+F4)**: the optimal SigMap usage loop ships as installable agent skills in every client's native format — completing the Agent Economy pillar (F1 budget → F2 tune → F3+F4 skills).
+
+### Added
+- **`sigmap skills` (#517, PR #518):** new `src/skills/skills.js` — two canonical, deterministic skill documents: **sigmap-usage-maximizer** (F3 — the spend-minimizing loop: `ask` before any file read · `get_lines` for anchored ranges instead of whole files · `verify_suggestion` before trusting generated code · `squeeze` any big log/trace/JSON · checkpoint via `create_checkpoint`/`note` · check `get_budget` and, near budget, summarize-then-drop; token accounting reads the F1 ledger — no LLM calls) and **sigmap-config-optimizer** (the F2 playbook: `tune` → review the evidence-naming reasons → `tune --apply` → `validate`). Multi-client installer mirroring the `mcp/install.js` CLIENTS pattern: Claude Code (`.claude/skills/<skill>/SKILL.md`), Cursor (`.cursor/rules/*.mdc`), Windsurf (`.windsurf/rules/*.md`), GitHub Copilot (`.github/instructions/*.instructions.md`), and Codex — a marker-delimited block injected into `AGENTS.md` **above** the `## Auto-generated signatures` marker, so the codex adapter's regeneration preserves it (proven by an end-to-end regeneration test). Human content is never touched; every install is idempotent (`installed`/`updated`/`already`). CLI: `sigmap skills list` and `sigmap skills install [--client <name> | --all] [--json]` — plain `install` wires only clients whose parent artifact exists (the `--setup` only-touch-existing precedent); `--client`/`--all` create. Zero new dependencies.
+
+### Changed
+- 8 new integration tests (132 test files); bundle rebuilt (149 modules).
+
+---
+
+## [8.25.0] — 2026-08-18
+
+Minor release — **"Agent Economy II" (v8.25, F2)**: the discovery stack becomes a config optimizer — one command that recommends (and can apply) the config a repo actually needs.
+
+### Added
+- **`sigmap tune` (#514, PR #515):** new `src/config/tune.js` — `buildTuneProposal(cwd)` packages the existing discovery stack (`resolveSourceRoots`, workspace markers, client-artifact probes) into a deterministic recommended-config diff with one evidence-naming reason per change. Five rules, explicit user choices never overridden: **srcDirs pin** (resolver roots, confidence-gated, never proposed against user-pinned dirs — pinned srcDirs are stable across runs and protected from token-budget drops), **monorepo** (fires when a workspace marker exists and the mode is off; reason names the marker — `pnpm-workspace.yaml`/`turbo.json`/`nx.json`/`lerna.json`/package.json `workspaces`), **adapters** (additive from client artifacts present: `CLAUDE.md`→claude, `.cursorrules`/`.cursor/`→cursor, `.windsurfrules`→windsurf, `AGENTS.md`→codex), **exclude** (curated vendored/generated dirs present at root — `third_party`, `external(s)`, `generated`, `testdata`, `tmp`, `.cache` … — appended with defaults preserved), **autoMaxTokens** (fires only when a pinned budget is below a labeled ~25-tokens/file heuristic estimate). `applyTuneProposal` merges into `gen-context.config.json` preserving every user key; re-proposal after apply is empty (idempotent). CLI: `sigmap tune` is read-only by default (`--dry-run` alias), `--apply` writes and points to `sigmap validate`, `--json` for agents. Zero new dependencies.
+
+### Changed
+- 10 new integration tests (131 test files); bundle rebuilt (148 modules).
+
+---
+
 ## [8.24.0] — 2026-07-28
 
 Minor release — **"Trust Quick Wins I" (v8.24, G3a)**: the secret-redaction engine that already protects signatures, `get_lines`, and evidence packs becomes a standalone command for arbitrary text.

package/README.md

@@ -59,7 +59,7 @@ That map is exactly what agentic grep is worst at: reproducible, auditable conte
 
 **Proof it pays off** (full benchmark below):
 <!--SM:whyMetrics-->
-- **82.2% hit@5** — right file in top 5 results (vs 44.8% single-shot grep baseline — 1.59× lift)
+- **82.2% hit@5** — right file in top 5 results (vs 44.0% single-shot grep baseline — 1.87× lift)
 - **96.8% token reduction** — average across 21 real repos
 - **64.8% task-success proxy** — modeled from retrieval tiers, not measured LLM sessions
 - **1.53 prompts per task** — down from 2.84 (46.1% fewer retries, modeled)
@@ -122,10 +122,10 @@ Ask → Rank → Context → Validate → Judge → Learn
 
 <!--SM:benchmarkBlock-->
 ```
-Benchmark : sigmap-v8.24-main (21 repositories, including R language)
-Date      : 2026-07-28
+Benchmark : sigmap-v8.26-main (21 repositories, including R language)
+Date      : 2026-08-17
 
-Hit@5          : 82.2%   (grep-agent baseline 44.8%  — 1.59× lift)
+Hit@5          : 82.2%   (grep-agent baseline 44.0%  — 1.87× lift)
 Token reduction: 96.8%   (across 21 repos)
 Prompt reduction : 46.1% (2.84 → 1.53 prompts per task, modeled)
 Task success   : 64.8%   (proxy — modeled from retrieval tiers)

package/gen-context.js

@@ -1877,6 +1877,220 @@ __factories["./src/config/loader"] = function(module, exports) {
   
 };
 
+// ── ./src/config/tune ──
+__factories["./src/config/tune"] = function(module, exports) {
+  
+  /**
+   * sigmap tune — deterministic config optimizer (F2, #514).
+   *
+   * Packages the existing discovery stack (source-root-resolver, monorepo
+   * markers, client-artifact probes) into a recommended config diff with a
+   * one-line reason per change. Read-only by default; `applyTuneProposal`
+   * merges accepted changes into gen-context.config.json, preserving every
+   * user key. Explicit user choices are never proposed against.
+   */
+
+  const fs = require('fs');
+  const path = require('path');
+  const { loadConfig } = __require('./src/config/loader');
+  const { resolveSourceRoots } = __require('./src/discovery/source-root-resolver');
+
+  // Workspace markers, in probe order (reason names the first one found).
+  const MONOREPO_MARKERS = ['pnpm-workspace.yaml', 'turbo.json', 'nx.json', 'lerna.json'];
+
+  // Client artifacts → adapter names (additive only).
+  const ADAPTER_MARKERS = [
+    { adapter: 'claude',   files: ['CLAUDE.md'] },
+    { adapter: 'cursor',   files: ['.cursorrules', '.cursor'] },
+    { adapter: 'windsurf', files: ['.windsurfrules', '.windsurf'] },
+    { adapter: 'codex',    files: ['AGENTS.md'] },
+  ];
+
+  // Root-level dirs that are typically vendored/generated when present.
+  const JUNK_DIRS = [
+    'third_party', 'thirdparty', 'external', 'externals',
+    'generated', 'testdata', 'snapshots', 'tmp', 'temp', '.cache',
+  ];
+
+  // Rough signature cost per source file (chars/4 world) for the budget check.
+  const TOKENS_PER_FILE = 25;
+
+  const SOURCE_EXTS = new Set([
+    '.js', '.mjs', '.cjs', '.jsx', '.ts', '.tsx', '.py', '.rb', '.go', '.rs',
+    '.java', '.kt', '.cs', '.cpp', '.c', '.h', '.hpp', '.swift', '.dart',
+    '.scala', '.php', '.gd', '.r', '.R',
+  ]);
+
+  /** Raw user config file content, or null when absent/unparsable. */
+  function _readUserConfig(cwd) {
+    try {
+      return JSON.parse(fs.readFileSync(path.join(cwd, 'gen-context.config.json'), 'utf8'));
+    } catch (_) {
+      return null;
+    }
+  }
+
+  /** Count source files under `roots` (relative to cwd), depth-capped, deterministic. */
+  function _countSourceFiles(cwd, roots, exclude, depth = 5) {
+    const excSet = new Set(exclude || []);
+    let count = 0;
+    const walk = (dir, d) => {
+      if (d <= 0 || count > 20000) return;
+      let entries;
+      try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch (_) { return; }
+      for (const e of entries) {
+        if (excSet.has(e.name)) continue;
+        if (e.isDirectory()) walk(path.join(dir, e.name), d - 1);
+        else if (e.isFile() && SOURCE_EXTS.has(path.extname(e.name))) count++;
+      }
+    };
+    for (const r of roots) {
+      const full = path.join(cwd, r);
+      if (fs.existsSync(full)) walk(full, depth);
+    }
+    return count;
+  }
+
+  /** The workspace marker present at cwd, or null. */
+  function _monorepoMarker(cwd) {
+    for (const m of MONOREPO_MARKERS) {
+      if (fs.existsSync(path.join(cwd, m))) return m;
+    }
+    try {
+      const pkg = JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf8'));
+      if (pkg.workspaces) return 'package.json workspaces';
+    } catch (_) {}
+    return null;
+  }
+
+  /**
+   * Build the recommended config diff for a repo.
+   *
+   * @param {string} cwd
+   * @returns {{ changes: Array<{key:string, current:*, recommended:*, reason:string}>,
+   *             detection: { roots:string[], confidence:string, isMonorepo:boolean },
+   *             configExists: boolean }}
+   */
+  function buildTuneProposal(cwd) {
+    const userConfig = _readUserConfig(cwd);
+    const config = loadConfig(cwd);
+    const detection = resolveSourceRoots(cwd, { exclude: config.exclude });
+    const changes = [];
+
+    // 1. srcDirs — recommend pinning the detected roots when the user hasn't.
+    // Pinned srcDirs make generation explicit/stable and are protected from
+    // token-budget drops; user-pinned srcDirs are never proposed against.
+    const userPinnedSrcDirs = !!(userConfig && Array.isArray(userConfig.srcDirs));
+    if (!userPinnedSrcDirs && detection.roots.length > 0 && detection.confidence !== 'low') {
+      changes.push({
+        key: 'srcDirs',
+        current: null,
+        recommended: detection.roots,
+        reason: `pin the ${detection.roots.length} detected source root(s) [confidence ${detection.confidence}] — explicit srcDirs are stable across runs and protected from budget drops`,
+      });
+    }
+
+    // 2. monorepo — a workspace marker exists but the mode is off.
+    const marker = _monorepoMarker(cwd);
+    if (marker && config.monorepo !== true) {
+      changes.push({
+        key: 'monorepo',
+        current: config.monorepo,
+        recommended: true,
+        reason: `workspace marker found: ${marker}`,
+      });
+    }
+
+    // 3. adapters — client artifacts present that the adapter list doesn't cover.
+    const currentAdapters = Array.isArray(config.adapters) ? config.adapters
+      : (Array.isArray(config.outputs) ? config.outputs : ['copilot']);
+    const found = [];
+    for (const { adapter, files } of ADAPTER_MARKERS) {
+      if (currentAdapters.includes(adapter)) continue;
+      const hit = files.find((f) => fs.existsSync(path.join(cwd, f)));
+      if (hit) found.push({ adapter, hit });
+    }
+    if (found.length > 0) {
+      changes.push({
+        key: 'adapters',
+        current: currentAdapters,
+        recommended: [...currentAdapters, ...found.map((f) => f.adapter)],
+        reason: `client files present: ${found.map((f) => f.hit).join(', ')}`,
+      });
+    }
+
+    // 4. exclude — root-level vendored/generated dirs not excluded yet.
+    const junkFound = JUNK_DIRS.filter((d) => {
+      if ((config.exclude || []).includes(d)) return false;
+      try { return fs.statSync(path.join(cwd, d)).isDirectory(); } catch (_) { return false; }
+    });
+    if (junkFound.length > 0) {
+      changes.push({
+        key: 'exclude',
+        current: userConfig && userConfig.exclude ? userConfig.exclude : null,
+        recommended: [...((userConfig && userConfig.exclude) || config.exclude), ...junkFound],
+        reason: `present at root and typically vendored/generated: ${junkFound.join(', ')}`,
+      });
+    }
+
+    // 5. autoMaxTokens — a pinned budget that the repo's size will overflow.
+    if (config.autoMaxTokens === false) {
+      const roots = detection.roots.length > 0 ? detection.roots : config.srcDirs;
+      const files = _countSourceFiles(cwd, roots, config.exclude);
+      const estTokens = files * TOKENS_PER_FILE;
+      if (estTokens > config.maxTokens) {
+        changes.push({
+          key: 'autoMaxTokens',
+          current: false,
+          recommended: true,
+          reason: `~${files} source files need ~${estTokens} tokens (heuristic) but maxTokens is pinned at ${config.maxTokens} — auto-scaling targets ${Math.round((config.coverageTarget || 0.8) * 100)}% coverage`,
+        });
+      }
+    }
+
+    return {
+      changes,
+      detection: { roots: detection.roots, confidence: detection.confidence, isMonorepo: detection.isMonorepo },
+      configExists: userConfig !== null,
+    };
+  }
+
+  /**
+   * Merge a proposal's changes into gen-context.config.json (create if absent).
+   * Preserves every existing user key; only the proposed keys are written.
+   *
+   * @returns {{ path: string, applied: string[] }}
+   */
+  function applyTuneProposal(cwd, proposal) {
+    const cfgPath = path.join(cwd, 'gen-context.config.json');
+    const existing = _readUserConfig(cwd) || {};
+    for (const c of proposal.changes) existing[c.key] = c.recommended;
+    fs.writeFileSync(cfgPath, JSON.stringify(existing, null, 2) + '\n');
+    return { path: cfgPath, applied: proposal.changes.map((c) => c.key) };
+  }
+
+  /** Human rendering of a proposal (one block per change, reason indented). */
+  function formatTuneProposal(proposal) {
+    const lines = [];
+    if (proposal.changes.length === 0) {
+      lines.push('[sigmap] tune: config already matches detection — no changes recommended');
+    } else {
+      lines.push(`[sigmap] tune: ${proposal.changes.length} recommended change(s)`);
+      for (const c of proposal.changes) {
+        lines.push(`  ${c.key.padEnd(14)} ${JSON.stringify(c.current)} → ${JSON.stringify(c.recommended)}`);
+        lines.push(`  ${''.padEnd(14)} reason: ${c.reason}`);
+      }
+      lines.push('');
+      lines.push('  apply with: sigmap tune --apply   (then: sigmap validate)');
+    }
+    lines.push(`  detection: roots [${proposal.detection.roots.join(', ')}] · confidence ${proposal.detection.confidence} · monorepo ${proposal.detection.isMonorepo ? 'yes' : 'no'}`);
+    return lines.join('\n');
+  }
+
+  module.exports = { buildTuneProposal, applyTuneProposal, formatTuneProposal, JUNK_DIRS, TOKENS_PER_FILE };
+  
+};
+
 // ── ./src/conventions/ci ──
 __factories["./src/conventions/ci"] = function(module, exports) {
   
@@ -14981,7 +15195,7 @@ __factories["./src/mcp/server"] = function(module, exports) {
 
   const SERVER_INFO = {
     name: 'sigmap',
-    version: '8.24.0',
+    version: '8.26.0',
     description: 'SigMap MCP server — code signatures on demand',
   };
 
@@ -17875,6 +18089,192 @@ __factories["./src/session/notes"] = function(module, exports) {
   
 };
 
+// ── ./src/skills/skills ──
+__factories["./src/skills/skills"] = function(module, exports) {
+  
+  /**
+   * sigmap skills — canonical agent playbooks + multi-client installer (F3+F4, #517).
+   *
+   * Two deterministic skill documents (the spend-minimizing usage loop and the
+   * config-optimizer playbook) emitted in each client's native skill/rules
+   * format — the `mcp/install.js` CLIENTS pattern applied to skills. File-based
+   * clients get sigmap-namespaced files we own outright; AGENTS.md (codex) gets
+   * a marker-delimited block inserted ABOVE the `## Auto-generated signatures`
+   * marker, since the codex adapter preserves content above it and replaces
+   * everything below. Idempotent; human content is never touched.
+   */
+
+  const fs = require('fs');
+  const path = require('path');
+
+  const START = '<!-- sigmap-skills:start -->';
+  const END = '<!-- sigmap-skills:end -->';
+  const SIGNATURES_MARKER = '## Auto-generated signatures';
+
+  const SKILLS = {
+    'sigmap-usage-maximizer': {
+      title: 'SigMap usage maximizer',
+      description: 'Spend-minimizing loop for agents in a SigMap-indexed repo: ask before reading, read ranges, verify before trusting, squeeze big pastes, checkpoint, watch the budget.',
+      body: [
+        'Follow this loop before any file exploration in a repo with SigMap installed.',
+        '',
+        '1. **Ask before reading.** `sigmap ask "<task>"` (or the `query_context` MCP tool) ranks the relevant files as ~hundreds of tokens of signatures instead of thousands of raw-file tokens. Never open files to "look around".',
+        '2. **Read ranges, not files.** Use the `get_lines` MCP tool with the `:start-end` line anchors carried on every signature to pull only the lines you need.',
+        '3. **Ground before trusting.** Run the `verify_suggestion` MCP tool (or `sigmap verify-ai-output`) on generated code before applying it — it flags fabricated files, imports, symbols, and npm scripts against the live index.',
+        '4. **Squeeze big pastes.** Any stack trace, CI/build log, or JSON blob goes through `sigmap squeeze` (or the `squeeze_output` MCP tool) before it enters context — the signal survives, the noise does not.',
+        '5. **Checkpoint progress.** Use the `create_checkpoint` MCP tool or `sigmap note "<decision>"` so a follow-up session resumes without re-deriving state.',
+        '6. **Watch the budget.** Check the `get_budget` MCP tool or `sigmap budget` (estimates from SigMap\'s local ledger — no LLM calls). Near the budget: summarize-then-drop older context instead of accumulating, and prefer terse output.',
+      ].join('\n'),
+    },
+    'sigmap-config-optimizer': {
+      title: 'SigMap config optimizer',
+      description: 'Playbook for getting a correct SigMap config on any repo: detect with sigmap tune, review the per-change reasons, apply, validate.',
+      body: [
+        'Playbook for configuring SigMap on a new or misconfigured repo.',
+        '',
+        '1. **Detect.** `sigmap tune` prints a recommended config diff — srcDirs pin, monorepo mode, adapters, excludes, budget — with one evidence-naming reason per change. Read-only.',
+        '2. **Review.** Every reason names its evidence (workspace marker, client artifact, vendored dir, file-count estimate). Explicit user config is never proposed against.',
+        '3. **Apply.** `sigmap tune --apply` merges the recommendations into `gen-context.config.json`, preserving every existing key. Idempotent — a second `tune` proposes nothing.',
+        '4. **Validate.** `sigmap validate` confirms the generated context matches the config; `sigmap doctor` diagnoses anything left.',
+      ].join('\n'),
+    },
+  };
+
+  // Client registry — parent = artifact whose presence means "user uses this
+  // client" (the `--setup` only-touch-existing rule for plain `skills install`).
+  const SKILL_CLIENTS = {
+    claude:   { label: 'Claude Code',    parent: ['.claude'],
+                target: (cwd, skill) => path.join(cwd, '.claude', 'skills', skill, 'SKILL.md') },
+    cursor:   { label: 'Cursor',         parent: ['.cursor'],
+                target: (cwd, skill) => path.join(cwd, '.cursor', 'rules', `${skill}.mdc`) },
+    windsurf: { label: 'Windsurf',       parent: ['.windsurf'],
+                target: (cwd, skill) => path.join(cwd, '.windsurf', 'rules', `${skill}.md`) },
+    copilot:  { label: 'GitHub Copilot', parent: ['.github'],
+                target: (cwd, skill) => path.join(cwd, '.github', 'instructions', `${skill}.instructions.md`) },
+    codex:    { label: 'Codex CLI (AGENTS.md)', parent: ['AGENTS.md'],
+                target: (cwd) => path.join(cwd, 'AGENTS.md'), inject: true },
+  };
+
+  function _footer(version) {
+    const ver = version ? ` v${version}` : '';
+    return `<sub>Generated by SigMap${ver} · run \`sigmap skills install\` to refresh.</sub>`;
+  }
+
+  /** Render one skill's client-specific file content. */
+  function renderSkill(client, skillName, version) {
+    const skill = SKILLS[skillName];
+    const body = `# ${skill.title}\n\n${skill.body}\n\n${_footer(version)}\n`;
+    if (client === 'claude') {
+      return `---\nname: ${skillName}\ndescription: ${skill.description}\n---\n\n${body}`;
+    }
+    if (client === 'cursor') {
+      return `---\ndescription: ${skill.description}\nalwaysApply: false\n---\n\n${body}`;
+    }
+    if (client === 'copilot') {
+      return `---\napplyTo: "**"\n---\n\n${body}`;
+    }
+    return body; // windsurf: plain markdown
+  }
+
+  /** Render the combined AGENTS.md block (both skills, marker-delimited). */
+  function renderAgentsBlock(version) {
+    const parts = [START, '## SigMap agent skills', ''];
+    for (const name of Object.keys(SKILLS)) {
+      parts.push(`### ${SKILLS[name].title}`, '', SKILLS[name].body, '');
+    }
+    parts.push(_footer(version), END);
+    return parts.join('\n');
+  }
+
+  /**
+   * Inject (or replace) the skills block in AGENTS.md content.
+   * A new block is inserted ABOVE the `## Auto-generated signatures` marker —
+   * the codex adapter's write() preserves content above that marker and
+   * replaces everything below it. Never touches content outside the markers.
+   */
+  function injectSkillsBlock(existing, block) {
+    const src = String(existing || '');
+    const startIdx = src.indexOf(START);
+    if (startIdx !== -1) {
+      const endIdx = src.indexOf(END, startIdx);
+      if (endIdx !== -1) {
+        return src.slice(0, startIdx) + block + src.slice(endIdx + END.length);
+      }
+    }
+    const sigIdx = src.indexOf(SIGNATURES_MARKER);
+    if (sigIdx !== -1) {
+      return src.slice(0, sigIdx) + block + '\n\n' + src.slice(sigIdx);
+    }
+    if (src.trim() === '') return block + '\n';
+    return src + (src.endsWith('\n') ? '\n' : '\n\n') + block + '\n';
+  }
+
+  function _writeIfChanged(filePath, content) {
+    if (fs.existsSync(filePath)) {
+      const existing = fs.readFileSync(filePath, 'utf8');
+      if (existing === content) return 'already';
+      fs.writeFileSync(filePath, content);
+      return 'updated';
+    }
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, content);
+    return 'installed';
+  }
+
+  /**
+   * Install both skills for one client.
+   * @returns {{ client, label, results: Array<{skill, path, status}> }}
+   *          status: 'installed' | 'updated' | 'already'; or { status:'unknown', valid } for a bad client.
+   */
+  function installSkills(client, opts = {}) {
+    const spec = SKILL_CLIENTS[client];
+    if (!spec) return { client, status: 'unknown', valid: Object.keys(SKILL_CLIENTS) };
+    const cwd = opts.cwd || process.cwd();
+    const version = opts.version || null;
+    const results = [];
+
+    if (spec.inject) {
+      const filePath = spec.target(cwd);
+      const existing = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : '';
+      const next = injectSkillsBlock(existing, renderAgentsBlock(version));
+      let status;
+      if (next === existing) status = 'already';
+      else { fs.writeFileSync(filePath, next); status = existing ? 'updated' : 'installed'; }
+      results.push({ skill: Object.keys(SKILLS).join(' + '), path: filePath, status });
+    } else {
+      for (const skillName of Object.keys(SKILLS)) {
+        const filePath = spec.target(cwd, skillName);
+        results.push({ skill: skillName, path: filePath, status: _writeIfChanged(filePath, renderSkill(client, skillName, version)) });
+      }
+    }
+    return { client, label: spec.label, results };
+  }
+
+  /** True when the client's parent artifact exists (plain-install eligibility). */
+  function clientPresent(client, cwd) {
+    const spec = SKILL_CLIENTS[client];
+    return !!spec && fs.existsSync(path.join(cwd, ...spec.parent));
+  }
+
+  /** List clients with target paths, presence, and installed state. */
+  function listSkillClients(opts = {}) {
+    const cwd = opts.cwd || process.cwd();
+    return Object.keys(SKILL_CLIENTS).map((client) => {
+      const spec = SKILL_CLIENTS[client];
+      const targets = spec.inject
+        ? [spec.target(cwd)]
+        : Object.keys(SKILLS).map((s) => spec.target(cwd, s));
+      const installed = spec.inject
+        ? (fs.existsSync(targets[0]) && fs.readFileSync(targets[0], 'utf8').includes(START))
+        : targets.every((t) => fs.existsSync(t));
+      return { client, label: spec.label, present: clientPresent(client, cwd), installed, targets };
+    });
+  }
+
+  module.exports = { SKILLS, SKILL_CLIENTS, renderSkill, renderAgentsBlock, injectSkillsBlock, installSkills, listSkillClients, clientPresent, START, END };
+  
+};
+
 // ── ./src/squeeze/cilog ──
 __factories["./src/squeeze/cilog"] = function(module, exports) {
   
@@ -20407,7 +20807,7 @@ function __tryGit(args, opts = {}) {
   catch (_) { return ''; }
 }
 
-const VERSION = '8.24.0';
+const VERSION = '8.26.0';
 const MARKER = '\n\n## Auto-generated signatures\n<!-- Updated by gen-context.js -->\n';
 
 function requireSourceOrBundled(key) {
@@ -22295,6 +22695,10 @@ Usage:
   ${cmd} budget                            Session spend ledger — estimated SigMap-emitted tokens, budget, context age (--json)
   ${cmd} budget --budget <tokens>          One-off budget override (config: sessionBudgetTokens, contextTtlDays)
   ${cmd} redact [file]                     Mask secrets in a file or stdin (10-pattern bank); redacted text to stdout (--json)
+  ${cmd} tune                              Recommend config from repo detection — srcDirs, monorepo, adapters, exclude, budget (--json)
+  ${cmd} tune --apply                      Write the recommendations into gen-context.config.json (merges; your keys preserved)
+  ${cmd} skills list                       List skill clients (Claude/Cursor/Windsurf/Copilot/AGENTS.md) and install state (--json)
+  ${cmd} skills install                    Install the SigMap agent playbooks for detected clients (--client <name> | --all)
   ${cmd} note "<text>"                     Append a note to the cross-session decision log
   ${cmd} note                              List recent notes (also: note --list <N>)
   ${cmd} status                            Show repo state — branch, dirty files, index freshness, notes
@@ -23694,6 +24098,94 @@ function main() {
     process.exit(0);
   }
 
+  // `sigmap tune [--apply|--dry-run] [--json]` — deterministic config optimizer:
+  // recommend srcDirs/monorepo/adapters/exclude/autoMaxTokens from the existing
+  // discovery stack, one reason per change. Read-only unless --apply.
+  if (args[0] === 'tune') {
+    const { buildTuneProposal, applyTuneProposal, formatTuneProposal } = requireSourceOrBundled('./src/config/tune');
+    let proposal;
+    try {
+      proposal = buildTuneProposal(cwd);
+    } catch (err) {
+      console.error(`[sigmap] tune failed: ${err.message}`);
+      process.exit(1);
+    }
+    if (args.includes('--apply') && proposal.changes.length > 0) {
+      const res = applyTuneProposal(cwd, proposal);
+      if (args.includes('--json')) {
+        process.stdout.write(JSON.stringify({ ...proposal, applied: res.applied, path: res.path }) + '\n');
+      } else {
+        console.log(formatTuneProposal(proposal));
+        console.log(`[sigmap] tune: wrote ${res.applied.join(', ')} → ${path.relative(cwd, res.path)} — run: sigmap validate`);
+      }
+      process.exit(0);
+    }
+    if (args.includes('--json')) {
+      process.stdout.write(JSON.stringify(proposal) + '\n');
+    } else {
+      console.log(formatTuneProposal(proposal));
+    }
+    process.exit(0);
+  }
+
+  // `sigmap skills list|install [--client <name>|--all] [--json]` — install the
+  // agent playbooks (usage-maximizer, config-optimizer) in each client's native
+  // skill/rules format. Plain `install` touches only clients whose parent
+  // artifact exists; --client/--all create. Idempotent.
+  if (args[0] === 'skills') {
+    const { installSkills, listSkillClients, SKILL_CLIENTS } = requireSourceOrBundled('./src/skills/skills');
+    const sub = args[1];
+    const jsonOut = args.includes('--json');
+
+    if (sub === 'list' || sub === undefined) {
+      const clients = listSkillClients({ cwd });
+      if (jsonOut) {
+        process.stdout.write(JSON.stringify(clients, null, 2) + '\n');
+        process.exit(0);
+      }
+      console.log('Supported skill clients:\n');
+      for (const c of clients) {
+        const state = c.installed ? 'installed' : (c.present ? 'client present, skills not installed' : 'client not detected');
+        console.log(`  ${c.client.padEnd(10)} ${c.label.padEnd(24)} ${state}`);
+        for (const t of c.targets) console.log(`             ${path.relative(cwd, t)}`);
+      }
+      console.log('\nInstall with: sigmap skills install [--client <name> | --all]');
+      process.exit(0);
+    }
+
+    if (sub === 'install') {
+      const cIdx = args.indexOf('--client');
+      const one = cIdx !== -1 ? args[cIdx + 1] : null;
+      let targets;
+      if (one) targets = [one];
+      else if (args.includes('--all')) targets = Object.keys(SKILL_CLIENTS);
+      else targets = listSkillClients({ cwd }).filter((c) => c.present).map((c) => c.client);
+      if (targets.length === 0) {
+        console.error('[sigmap] skills: no clients detected — use --client <name> or --all (see: sigmap skills list)');
+        process.exit(1);
+      }
+      const out = targets.map((c) => installSkills(c, { cwd, version: VERSION }));
+      const bad = out.find((r) => r.status === 'unknown');
+      if (bad) {
+        console.error(`[sigmap] skills: unknown client "${bad.client}" — valid: ${bad.valid.join(', ')}`);
+        process.exit(1);
+      }
+      if (jsonOut) {
+        process.stdout.write(JSON.stringify(out, null, 2) + '\n');
+        process.exit(0);
+      }
+      for (const r of out) {
+        for (const res of r.results) {
+          console.log(`  ${r.client.padEnd(10)} ${res.status.padEnd(10)} ${path.relative(cwd, res.path)}`);
+        }
+      }
+      process.exit(0);
+    }
+
+    console.error('[sigmap] usage: sigmap skills [list | install [--client <name> | --all]] [--json]');
+    process.exit(1);
+  }
+
   // `sigmap note "<text>"` — append to the cross-session decision log.
   // With no text, lists recent notes (also `note --list [N]`).
   // `sigmap memory` — one view over the cross-session stores in .context/.

package/llms-full.txt

@@ -11,17 +11,17 @@ 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.24.0 | Benchmark: sigmap-v8.24-main (2026-07-28)
+# Version: 8.26.0 | Benchmark: sigmap-v8.26-main (2026-08-17)
 # 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.24-main, 2026-07-28)
+## Core metrics (benchmark: sigmap-v8.26-main, 2026-08-17)
 
 | Metric | Without SigMap | With SigMap |
 |--------|----------------|-------------|
-| Retrieval hit@5 | 44.8% (single-shot grep) | 82.2% (1.59× lift) |
+| Retrieval hit@5 | 44.0% (single-shot grep) | 82.2% (1.87× lift) |
 | Token reduction | — | 96.8% average |
 | Task-success proxy (modeled) | — | 64.8% |
 | Prompts per task | 2.84 | 1.53 (46.1% fewer) |
@@ -128,6 +128,10 @@ sigmap memory --clear <store>            Clear one store: session|notes|weights|
 sigmap budget                            Session spend ledger — estimated SigMap-emitted tokens, budget, context age (--json)
 sigmap budget --budget <tokens>          One-off budget override (config: sessionBudgetTokens, contextTtlDays)
 sigmap redact [file]                     Mask secrets in a file or stdin (10-pattern bank); redacted text to stdout (--json)
+sigmap tune                              Recommend config from repo detection — srcDirs, monorepo, adapters, exclude, budget (--json)
+sigmap tune --apply                      Write the recommendations into gen-context.config.json (merges; your keys preserved)
+sigmap skills list                       List skill clients (Claude/Cursor/Windsurf/Copilot/AGENTS.md) and install state (--json)
+sigmap skills install                    Install the SigMap agent playbooks for detected clients (--client <name> | --all)
 sigmap note "<text>"                     Append a note to the cross-session decision log
 sigmap note                              List recent notes (also: note --list <N>)
 sigmap status                            Show repo state — branch, dirty files, index freshness, notes

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.24.0 | Benchmark: sigmap-v8.24-main (2026-07-28)
+# Version: 8.26.0 | Benchmark: sigmap-v8.26-main (2026-08-17)
 # 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,9 +23,9 @@ 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.24-main, 2026-07-28)
+## Core metrics (benchmark: sigmap-v8.26-main, 2026-08-17)
 
-- hit@5 retrieval: 82.2% vs 44.8% single-shot grep baseline (1.59× lift)
+- hit@5 retrieval: 82.2% vs 44.0% single-shot grep baseline (1.87× lift)
 - Token reduction: 96.8% average across benchmark repos
 - Task-success proxy: 64.8% (modeled from retrieval tiers, not measured LLM sessions)
 - Prompts per task: 1.53 vs 2.84 baseline (46.1% fewer, modeled)

package/package.json

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

package/src/config/tune.js

@@ -0,0 +1,210 @@
+'use strict';
+
+/**
+ * sigmap tune — deterministic config optimizer (F2, #514).
+ *
+ * Packages the existing discovery stack (source-root-resolver, monorepo
+ * markers, client-artifact probes) into a recommended config diff with a
+ * one-line reason per change. Read-only by default; `applyTuneProposal`
+ * merges accepted changes into gen-context.config.json, preserving every
+ * user key. Explicit user choices are never proposed against.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { loadConfig } = require('./loader');
+const { resolveSourceRoots } = require('../discovery/source-root-resolver');
+
+// Workspace markers, in probe order (reason names the first one found).
+const MONOREPO_MARKERS = ['pnpm-workspace.yaml', 'turbo.json', 'nx.json', 'lerna.json'];
+
+// Client artifacts → adapter names (additive only).
+const ADAPTER_MARKERS = [
+  { adapter: 'claude',   files: ['CLAUDE.md'] },
+  { adapter: 'cursor',   files: ['.cursorrules', '.cursor'] },
+  { adapter: 'windsurf', files: ['.windsurfrules', '.windsurf'] },
+  { adapter: 'codex',    files: ['AGENTS.md'] },
+];
+
+// Root-level dirs that are typically vendored/generated when present.
+const JUNK_DIRS = [
+  'third_party', 'thirdparty', 'external', 'externals',
+  'generated', 'testdata', 'snapshots', 'tmp', 'temp', '.cache',
+];
+
+// Rough signature cost per source file (chars/4 world) for the budget check.
+const TOKENS_PER_FILE = 25;
+
+const SOURCE_EXTS = new Set([
+  '.js', '.mjs', '.cjs', '.jsx', '.ts', '.tsx', '.py', '.rb', '.go', '.rs',
+  '.java', '.kt', '.cs', '.cpp', '.c', '.h', '.hpp', '.swift', '.dart',
+  '.scala', '.php', '.gd', '.r', '.R',
+]);
+
+/** Raw user config file content, or null when absent/unparsable. */
+function _readUserConfig(cwd) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(cwd, 'gen-context.config.json'), 'utf8'));
+  } catch (_) {
+    return null;
+  }
+}
+
+/** Count source files under `roots` (relative to cwd), depth-capped, deterministic. */
+function _countSourceFiles(cwd, roots, exclude, depth = 5) {
+  const excSet = new Set(exclude || []);
+  let count = 0;
+  const walk = (dir, d) => {
+    if (d <= 0 || count > 20000) return;
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch (_) { return; }
+    for (const e of entries) {
+      if (excSet.has(e.name)) continue;
+      if (e.isDirectory()) walk(path.join(dir, e.name), d - 1);
+      else if (e.isFile() && SOURCE_EXTS.has(path.extname(e.name))) count++;
+    }
+  };
+  for (const r of roots) {
+    const full = path.join(cwd, r);
+    if (fs.existsSync(full)) walk(full, depth);
+  }
+  return count;
+}
+
+/** The workspace marker present at cwd, or null. */
+function _monorepoMarker(cwd) {
+  for (const m of MONOREPO_MARKERS) {
+    if (fs.existsSync(path.join(cwd, m))) return m;
+  }
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf8'));
+    if (pkg.workspaces) return 'package.json workspaces';
+  } catch (_) {}
+  return null;
+}
+
+/**
+ * Build the recommended config diff for a repo.
+ *
+ * @param {string} cwd
+ * @returns {{ changes: Array<{key:string, current:*, recommended:*, reason:string}>,
+ *             detection: { roots:string[], confidence:string, isMonorepo:boolean },
+ *             configExists: boolean }}
+ */
+function buildTuneProposal(cwd) {
+  const userConfig = _readUserConfig(cwd);
+  const config = loadConfig(cwd);
+  const detection = resolveSourceRoots(cwd, { exclude: config.exclude });
+  const changes = [];
+
+  // 1. srcDirs — recommend pinning the detected roots when the user hasn't.
+  // Pinned srcDirs make generation explicit/stable and are protected from
+  // token-budget drops; user-pinned srcDirs are never proposed against.
+  const userPinnedSrcDirs = !!(userConfig && Array.isArray(userConfig.srcDirs));
+  if (!userPinnedSrcDirs && detection.roots.length > 0 && detection.confidence !== 'low') {
+    changes.push({
+      key: 'srcDirs',
+      current: null,
+      recommended: detection.roots,
+      reason: `pin the ${detection.roots.length} detected source root(s) [confidence ${detection.confidence}] — explicit srcDirs are stable across runs and protected from budget drops`,
+    });
+  }
+
+  // 2. monorepo — a workspace marker exists but the mode is off.
+  const marker = _monorepoMarker(cwd);
+  if (marker && config.monorepo !== true) {
+    changes.push({
+      key: 'monorepo',
+      current: config.monorepo,
+      recommended: true,
+      reason: `workspace marker found: ${marker}`,
+    });
+  }
+
+  // 3. adapters — client artifacts present that the adapter list doesn't cover.
+  const currentAdapters = Array.isArray(config.adapters) ? config.adapters
+    : (Array.isArray(config.outputs) ? config.outputs : ['copilot']);
+  const found = [];
+  for (const { adapter, files } of ADAPTER_MARKERS) {
+    if (currentAdapters.includes(adapter)) continue;
+    const hit = files.find((f) => fs.existsSync(path.join(cwd, f)));
+    if (hit) found.push({ adapter, hit });
+  }
+  if (found.length > 0) {
+    changes.push({
+      key: 'adapters',
+      current: currentAdapters,
+      recommended: [...currentAdapters, ...found.map((f) => f.adapter)],
+      reason: `client files present: ${found.map((f) => f.hit).join(', ')}`,
+    });
+  }
+
+  // 4. exclude — root-level vendored/generated dirs not excluded yet.
+  const junkFound = JUNK_DIRS.filter((d) => {
+    if ((config.exclude || []).includes(d)) return false;
+    try { return fs.statSync(path.join(cwd, d)).isDirectory(); } catch (_) { return false; }
+  });
+  if (junkFound.length > 0) {
+    changes.push({
+      key: 'exclude',
+      current: userConfig && userConfig.exclude ? userConfig.exclude : null,
+      recommended: [...((userConfig && userConfig.exclude) || config.exclude), ...junkFound],
+      reason: `present at root and typically vendored/generated: ${junkFound.join(', ')}`,
+    });
+  }
+
+  // 5. autoMaxTokens — a pinned budget that the repo's size will overflow.
+  if (config.autoMaxTokens === false) {
+    const roots = detection.roots.length > 0 ? detection.roots : config.srcDirs;
+    const files = _countSourceFiles(cwd, roots, config.exclude);
+    const estTokens = files * TOKENS_PER_FILE;
+    if (estTokens > config.maxTokens) {
+      changes.push({
+        key: 'autoMaxTokens',
+        current: false,
+        recommended: true,
+        reason: `~${files} source files need ~${estTokens} tokens (heuristic) but maxTokens is pinned at ${config.maxTokens} — auto-scaling targets ${Math.round((config.coverageTarget || 0.8) * 100)}% coverage`,
+      });
+    }
+  }
+
+  return {
+    changes,
+    detection: { roots: detection.roots, confidence: detection.confidence, isMonorepo: detection.isMonorepo },
+    configExists: userConfig !== null,
+  };
+}
+
+/**
+ * Merge a proposal's changes into gen-context.config.json (create if absent).
+ * Preserves every existing user key; only the proposed keys are written.
+ *
+ * @returns {{ path: string, applied: string[] }}
+ */
+function applyTuneProposal(cwd, proposal) {
+  const cfgPath = path.join(cwd, 'gen-context.config.json');
+  const existing = _readUserConfig(cwd) || {};
+  for (const c of proposal.changes) existing[c.key] = c.recommended;
+  fs.writeFileSync(cfgPath, JSON.stringify(existing, null, 2) + '\n');
+  return { path: cfgPath, applied: proposal.changes.map((c) => c.key) };
+}
+
+/** Human rendering of a proposal (one block per change, reason indented). */
+function formatTuneProposal(proposal) {
+  const lines = [];
+  if (proposal.changes.length === 0) {
+    lines.push('[sigmap] tune: config already matches detection — no changes recommended');
+  } else {
+    lines.push(`[sigmap] tune: ${proposal.changes.length} recommended change(s)`);
+    for (const c of proposal.changes) {
+      lines.push(`  ${c.key.padEnd(14)} ${JSON.stringify(c.current)} → ${JSON.stringify(c.recommended)}`);
+      lines.push(`  ${''.padEnd(14)} reason: ${c.reason}`);
+    }
+    lines.push('');
+    lines.push('  apply with: sigmap tune --apply   (then: sigmap validate)');
+  }
+  lines.push(`  detection: roots [${proposal.detection.roots.join(', ')}] · confidence ${proposal.detection.confidence} · monorepo ${proposal.detection.isMonorepo ? 'yes' : 'no'}`);
+  return lines.join('\n');
+}
+
+module.exports = { buildTuneProposal, applyTuneProposal, formatTuneProposal, JUNK_DIRS, TOKENS_PER_FILE };

package/src/mcp/server.js

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

package/src/skills/skills.js

@@ -0,0 +1,182 @@
+'use strict';
+
+/**
+ * sigmap skills — canonical agent playbooks + multi-client installer (F3+F4, #517).
+ *
+ * Two deterministic skill documents (the spend-minimizing usage loop and the
+ * config-optimizer playbook) emitted in each client's native skill/rules
+ * format — the `mcp/install.js` CLIENTS pattern applied to skills. File-based
+ * clients get sigmap-namespaced files we own outright; AGENTS.md (codex) gets
+ * a marker-delimited block inserted ABOVE the `## Auto-generated signatures`
+ * marker, since the codex adapter preserves content above it and replaces
+ * everything below. Idempotent; human content is never touched.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const START = '<!-- sigmap-skills:start -->';
+const END = '<!-- sigmap-skills:end -->';
+const SIGNATURES_MARKER = '## Auto-generated signatures';
+
+const SKILLS = {
+  'sigmap-usage-maximizer': {
+    title: 'SigMap usage maximizer',
+    description: 'Spend-minimizing loop for agents in a SigMap-indexed repo: ask before reading, read ranges, verify before trusting, squeeze big pastes, checkpoint, watch the budget.',
+    body: [
+      'Follow this loop before any file exploration in a repo with SigMap installed.',
+      '',
+      '1. **Ask before reading.** `sigmap ask "<task>"` (or the `query_context` MCP tool) ranks the relevant files as ~hundreds of tokens of signatures instead of thousands of raw-file tokens. Never open files to "look around".',
+      '2. **Read ranges, not files.** Use the `get_lines` MCP tool with the `:start-end` line anchors carried on every signature to pull only the lines you need.',
+      '3. **Ground before trusting.** Run the `verify_suggestion` MCP tool (or `sigmap verify-ai-output`) on generated code before applying it — it flags fabricated files, imports, symbols, and npm scripts against the live index.',
+      '4. **Squeeze big pastes.** Any stack trace, CI/build log, or JSON blob goes through `sigmap squeeze` (or the `squeeze_output` MCP tool) before it enters context — the signal survives, the noise does not.',
+      '5. **Checkpoint progress.** Use the `create_checkpoint` MCP tool or `sigmap note "<decision>"` so a follow-up session resumes without re-deriving state.',
+      '6. **Watch the budget.** Check the `get_budget` MCP tool or `sigmap budget` (estimates from SigMap\'s local ledger — no LLM calls). Near the budget: summarize-then-drop older context instead of accumulating, and prefer terse output.',
+    ].join('\n'),
+  },
+  'sigmap-config-optimizer': {
+    title: 'SigMap config optimizer',
+    description: 'Playbook for getting a correct SigMap config on any repo: detect with sigmap tune, review the per-change reasons, apply, validate.',
+    body: [
+      'Playbook for configuring SigMap on a new or misconfigured repo.',
+      '',
+      '1. **Detect.** `sigmap tune` prints a recommended config diff — srcDirs pin, monorepo mode, adapters, excludes, budget — with one evidence-naming reason per change. Read-only.',
+      '2. **Review.** Every reason names its evidence (workspace marker, client artifact, vendored dir, file-count estimate). Explicit user config is never proposed against.',
+      '3. **Apply.** `sigmap tune --apply` merges the recommendations into `gen-context.config.json`, preserving every existing key. Idempotent — a second `tune` proposes nothing.',
+      '4. **Validate.** `sigmap validate` confirms the generated context matches the config; `sigmap doctor` diagnoses anything left.',
+    ].join('\n'),
+  },
+};
+
+// Client registry — parent = artifact whose presence means "user uses this
+// client" (the `--setup` only-touch-existing rule for plain `skills install`).
+const SKILL_CLIENTS = {
+  claude:   { label: 'Claude Code',    parent: ['.claude'],
+              target: (cwd, skill) => path.join(cwd, '.claude', 'skills', skill, 'SKILL.md') },
+  cursor:   { label: 'Cursor',         parent: ['.cursor'],
+              target: (cwd, skill) => path.join(cwd, '.cursor', 'rules', `${skill}.mdc`) },
+  windsurf: { label: 'Windsurf',       parent: ['.windsurf'],
+              target: (cwd, skill) => path.join(cwd, '.windsurf', 'rules', `${skill}.md`) },
+  copilot:  { label: 'GitHub Copilot', parent: ['.github'],
+              target: (cwd, skill) => path.join(cwd, '.github', 'instructions', `${skill}.instructions.md`) },
+  codex:    { label: 'Codex CLI (AGENTS.md)', parent: ['AGENTS.md'],
+              target: (cwd) => path.join(cwd, 'AGENTS.md'), inject: true },
+};
+
+function _footer(version) {
+  const ver = version ? ` v${version}` : '';
+  return `<sub>Generated by SigMap${ver} · run \`sigmap skills install\` to refresh.</sub>`;
+}
+
+/** Render one skill's client-specific file content. */
+function renderSkill(client, skillName, version) {
+  const skill = SKILLS[skillName];
+  const body = `# ${skill.title}\n\n${skill.body}\n\n${_footer(version)}\n`;
+  if (client === 'claude') {
+    return `---\nname: ${skillName}\ndescription: ${skill.description}\n---\n\n${body}`;
+  }
+  if (client === 'cursor') {
+    return `---\ndescription: ${skill.description}\nalwaysApply: false\n---\n\n${body}`;
+  }
+  if (client === 'copilot') {
+    return `---\napplyTo: "**"\n---\n\n${body}`;
+  }
+  return body; // windsurf: plain markdown
+}
+
+/** Render the combined AGENTS.md block (both skills, marker-delimited). */
+function renderAgentsBlock(version) {
+  const parts = [START, '## SigMap agent skills', ''];
+  for (const name of Object.keys(SKILLS)) {
+    parts.push(`### ${SKILLS[name].title}`, '', SKILLS[name].body, '');
+  }
+  parts.push(_footer(version), END);
+  return parts.join('\n');
+}
+
+/**
+ * Inject (or replace) the skills block in AGENTS.md content.
+ * A new block is inserted ABOVE the `## Auto-generated signatures` marker —
+ * the codex adapter's write() preserves content above that marker and
+ * replaces everything below it. Never touches content outside the markers.
+ */
+function injectSkillsBlock(existing, block) {
+  const src = String(existing || '');
+  const startIdx = src.indexOf(START);
+  if (startIdx !== -1) {
+    const endIdx = src.indexOf(END, startIdx);
+    if (endIdx !== -1) {
+      return src.slice(0, startIdx) + block + src.slice(endIdx + END.length);
+    }
+  }
+  const sigIdx = src.indexOf(SIGNATURES_MARKER);
+  if (sigIdx !== -1) {
+    return src.slice(0, sigIdx) + block + '\n\n' + src.slice(sigIdx);
+  }
+  if (src.trim() === '') return block + '\n';
+  return src + (src.endsWith('\n') ? '\n' : '\n\n') + block + '\n';
+}
+
+function _writeIfChanged(filePath, content) {
+  if (fs.existsSync(filePath)) {
+    const existing = fs.readFileSync(filePath, 'utf8');
+    if (existing === content) return 'already';
+    fs.writeFileSync(filePath, content);
+    return 'updated';
+  }
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, content);
+  return 'installed';
+}
+
+/**
+ * Install both skills for one client.
+ * @returns {{ client, label, results: Array<{skill, path, status}> }}
+ *          status: 'installed' | 'updated' | 'already'; or { status:'unknown', valid } for a bad client.
+ */
+function installSkills(client, opts = {}) {
+  const spec = SKILL_CLIENTS[client];
+  if (!spec) return { client, status: 'unknown', valid: Object.keys(SKILL_CLIENTS) };
+  const cwd = opts.cwd || process.cwd();
+  const version = opts.version || null;
+  const results = [];
+
+  if (spec.inject) {
+    const filePath = spec.target(cwd);
+    const existing = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : '';
+    const next = injectSkillsBlock(existing, renderAgentsBlock(version));
+    let status;
+    if (next === existing) status = 'already';
+    else { fs.writeFileSync(filePath, next); status = existing ? 'updated' : 'installed'; }
+    results.push({ skill: Object.keys(SKILLS).join(' + '), path: filePath, status });
+  } else {
+    for (const skillName of Object.keys(SKILLS)) {
+      const filePath = spec.target(cwd, skillName);
+      results.push({ skill: skillName, path: filePath, status: _writeIfChanged(filePath, renderSkill(client, skillName, version)) });
+    }
+  }
+  return { client, label: spec.label, results };
+}
+
+/** True when the client's parent artifact exists (plain-install eligibility). */
+function clientPresent(client, cwd) {
+  const spec = SKILL_CLIENTS[client];
+  return !!spec && fs.existsSync(path.join(cwd, ...spec.parent));
+}
+
+/** List clients with target paths, presence, and installed state. */
+function listSkillClients(opts = {}) {
+  const cwd = opts.cwd || process.cwd();
+  return Object.keys(SKILL_CLIENTS).map((client) => {
+    const spec = SKILL_CLIENTS[client];
+    const targets = spec.inject
+      ? [spec.target(cwd)]
+      : Object.keys(SKILLS).map((s) => spec.target(cwd, s));
+    const installed = spec.inject
+      ? (fs.existsSync(targets[0]) && fs.readFileSync(targets[0], 'utf8').includes(START))
+      : targets.every((t) => fs.existsSync(t));
+    return { client, label: spec.label, present: clientPresent(client, cwd), installed, targets };
+  });
+}
+
+module.exports = { SKILLS, SKILL_CLIENTS, renderSkill, renderAgentsBlock, injectSkillsBlock, installSkills, listSkillClients, clientPresent, START, END };