sigmap 3.3.1 → 3.3.2

package/AGENTS.md

@@ -0,0 +1,42 @@
+# SigMap — AGENTS.md
+
+Instructions for Codex-style agents working in this repository.
+
+## Append Strategy (Required)
+
+When writing generated signature content, never overwrite human-written notes above the marker.
+
+Use this marker block for all appendable context files:
+
+```
+## Auto-generated signatures
+<!-- Updated by gen-context.js -->
+```
+
+### Files that must use append-under-marker
+
+1. `CLAUDE.md`
+2. `.github/copilot-instructions.md`
+3. `.github/gemini-context.md`
+
+### Safe write procedure
+
+1. Read existing file (or start with empty string if file does not exist).
+2. Find the marker `## Auto-generated signatures`.
+3. If marker exists: keep everything above marker unchanged; replace only marker-and-below with new generated block.
+4. If marker does not exist: append marker + generated block to the end.
+5. Never modify human content above marker.
+
+### Legacy cleanup rule
+
+If an existing generated file has no marker but contains prior SigMap-generated content headers, replace the full legacy generated content with marker + new generated block.
+
+## Verification
+
+After changing write logic, run:
+
+```bash
+node test/integration/multi-output.test.js
+```
+
+Expected: all tests pass, including append-preservation cases.

package/README.md

@@ -1,38 +1,62 @@
 <div align="center">
 
+<img src="docs-vp/.vitepress/public/logo.svg" alt="SigMap logo" width="64" height="84" />
+
 <h1>⚡ SigMap</h1>
 
-<p><strong>Zero-dependency AI context engine — 97% token reduction</strong></p>
+<p><strong>WITHOUT SIGMAP, YOUR AI IS GUESSING.</strong><br>
+<strong>It sees 8% of your codebase and invents the rest.</strong></p>
+
+<p><sub>Run one command. Force every answer to come from real code.</sub></p>
+
+</div>
 
-<p>
-  Every coding agent session starts with full codebase context at under 4K tokens.<br>
-  Multiple install options. Zero runtime dependencies. Requires only Node.js 18+.
-</p>
+<div align="center">
+<img src="docs/impact-banner.svg" alt="SigMap — 6× better answers, 97% fewer tokens, 2× fewer prompts" width="760" />
+</div>
 
-<img src="docs/sigmap-banner.png" alt="SigMap — AI context engine" width="700">
+```sh
+npx sigmap   # 10 seconds. zero config. your AI never reads the wrong file again.
+```
+
+<details>
+<summary><strong>Trust signals</strong></summary>
+
+<div align="center">
 
-<!-- Status -->
 [![npm version](https://img.shields.io/npm/v/sigmap?color=7c6af7&label=latest&logo=npm)](https://www.npmjs.com/package/sigmap)
 [![CI](https://github.com/manojmallick/sigmap/actions/workflows/ci.yml/badge.svg)](https://github.com/manojmallick/sigmap/actions/workflows/ci.yml)
 [![Zero deps](https://img.shields.io/badge/dependencies-zero-22c55e)](package.json)
-[![Last commit](https://img.shields.io/github/last-commit/manojmallick/sigmap?color=7c6af7)](https://github.com/manojmallick/sigmap/commits/main)
-
-<!-- Meta -->
 [![License: MIT](https://img.shields.io/badge/License-MIT-7c6af7.svg)](LICENSE)
-[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
-[![npm](https://img.shields.io/badge/npm-sigmap-cb3837?logo=npm)](https://www.npmjs.com/package/sigmap)
-[![GitHub Stars](https://img.shields.io/github/stars/manojmallick/sigmap?style=flat&color=f59e0b&logo=github)](https://github.com/manojmallick/sigmap/stargazers)
-
-<!-- Links -->
-[![Docs](https://img.shields.io/badge/docs-live-7c6af7?logo=github-pages)](https://manojmallick.github.io/sigmap)
-[![Changelog](https://img.shields.io/badge/changelog-CHANGELOG.md-blue)](CHANGELOG.md)
-[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
 [![VS Code](https://img.shields.io/badge/VS%20Code-extension-0078d4?logo=visual-studio-code)](https://marketplace.visualstudio.com/items?itemName=manojmallick.sigmap)
 [![JetBrains](https://img.shields.io/badge/JetBrains-plugin-000000?logo=jetbrains)](https://plugins.jetbrains.com/plugin/31109-sigmap--ai-context-engine/)
-[![Open VSX](https://img.shields.io/open-vsx/v/manojmallick/sigmap?color=a251e3&label=Open%20VSX&logo=vscodium)](https://open-vsx.org/extension/manojmallick/sigmap)
+[![Docs](https://img.shields.io/badge/docs-live-7c6af7?logo=github-pages)](https://manojmallick.github.io/sigmap)
+[![GitHub Stars](https://img.shields.io/github/stars/manojmallick/sigmap?style=flat&color=f59e0b&logo=github)](https://github.com/manojmallick/sigmap/stargazers)
 
 </div>
 
+</details>
+
+<details>
+<summary><strong>Full benchmark breakdown →</strong></summary>
+
+<br/>
+
+<div align="center">
+<img src="docs/comparison-chart.svg" alt="SigMap benchmark — before vs after across 3 RAG quality metrics" width="700" />
+<br/><sub><a href="https://manojmallick.github.io/sigmap/guide/task-benchmark.html">80 tasks · 16 real repos · no LLM API · <strong>full methodology →</strong></a></sub>
+</div>
+
+| | Without SigMap | With SigMap |
+|---|:---:|:---:|
+| Task success | 10% | **59%** |
+| Prompts per task | 2.84 | **1.54** |
+| Tokens per session | ~80,000 | **~2,000** |
+| Right file found | 13.7% | **87.5%** |
+| Hallucination risk | 92% | **0%** |
+
+</details>
+
 ---
 
 ## Table of contents
@@ -67,7 +91,7 @@ SigMap scans your source files and extracts only the **function and class signat
 Your codebase
     │
     ▼
-gen-context.js ──► extracts signatures from 21 languages
+sigmap ─────────► extracts signatures from 21 languages
     │
     ▼
 .github/copilot-instructions.md   ◄── auto-read by Copilot / Claude / Cursor
@@ -90,6 +114,31 @@ AI agent session starts with full context
 
 > **97% fewer tokens. The same codebase understanding.**
 
+### Benchmark: real-world repos
+
+Reproduced with `node scripts/run-benchmark.mjs` on public repos:
+
+| Repo | Language | Raw tokens | After SigMap | Reduction |
+|------|----------|------------|--------------|-----------|
+| express | JavaScript | 15.5K | 201 | **98.7%** |
+| flask | Python | 84.8K | 3.4K | **96.0%** |
+| gin | Go | 172.8K | 5.7K | **96.7%** |
+| spring-petclinic | Java | 77.0K | 634 | **99.2%** |
+| rails | Ruby | 1.5M | 7.1K | **99.5%** |
+| axios | TypeScript | 31.7K | 1.5K | **95.2%** |
+| rust-analyzer | Rust | 3.5M | 5.9K | **99.8%** |
+| abseil-cpp | C++ | 2.3M | 6.3K | **99.7%** |
+| serilog | C# | 113.7K | 5.8K | **94.9%** |
+| riverpod | Dart | 682.7K | 6.5K | **99.0%** |
+| okhttp | Kotlin | 31.3K | 1.4K | **95.5%** |
+| laravel | PHP | 1.7M | 7.2K | **99.6%** |
+| akka | Scala | 790.5K | 7.1K | **99.1%** |
+| vapor | Swift | 171.2K | 6.4K | **96.3%** |
+| vue-core | Vue | 404.2K | 8.8K | **97.8%** |
+| svelte | Svelte | 438.2K | 8.0K | **98.2%** |
+
+**Average: 99.3% reduction across 16 languages.** See [`benchmarks/reports/token-reduction.md`](benchmarks/reports/token-reduction.md) or reproduce with `node scripts/run-benchmark.mjs`.
+
 ---
 
 ## ⚡ Installation
@@ -250,8 +299,6 @@ No npm, no `node_modules`. Drop `gen-context.js` into any project and run it dir
 
 </details>
 
-> **Note:** When using the single-file download, replace `sigmap` with `node gen-context.js` in all commands below.
-
 ---
 
 ## 🚀 Features
@@ -266,17 +313,19 @@ sigmap --adapter claude     # → CLAUDE.md (appended below marker)
 sigmap --adapter cursor     # → .cursorrules
 sigmap --adapter windsurf   # → .windsurfrules
 sigmap --adapter openai     # → .github/openai-context.md
-sigmap --adapter gemini     # → .github/gemini-context.md
+sigmap --adapter gemini     # → .github/gemini-context.md (appended below marker)
+sigmap --adapter codex      # → AGENTS.md (appended below marker)
 ```
 
 | Adapter | Output file | AI assistant |
 |---|---|---|
-| `copilot` | `.github/copilot-instructions.md` | GitHub Copilot |
+| `copilot` | `.github/copilot-instructions.md` (append) | GitHub Copilot |
 | `claude` | `CLAUDE.md` (append) | Claude / Claude Code |
 | `cursor` | `.cursorrules` | Cursor |
 | `windsurf` | `.windsurfrules` | Windsurf |
 | `openai` | `.github/openai-context.md` | Any OpenAI model |
-| `gemini` | `.github/gemini-context.md` | Google Gemini |
+| `gemini` | `.github/gemini-context.md` (append) | Google Gemini |
+| `codex` | `AGENTS.md` (append) | OpenAI Codex |
 
 Configure multiple adapters at once in `gen-context.config.json`:
 
@@ -342,7 +391,7 @@ npm install -g sigmap       # install globally
 
 ### Generate context
 
-Download the single-file CLI and generate context immediately:
+Once installed, run from your project root:
 
 ```bash
 sigmap                         # generate once and exit
@@ -374,17 +423,17 @@ npx repomix --compress # deep dive sessions
 
 ## 🧩 VS Code extension
 
-The `vscode-extension/` directory contains a first-party VS Code extension that keeps you informed without any manual commands.
+The official SigMap VS Code extension keeps your context fresh without any manual commands. Install it once and it runs silently in the background.
 
 | Feature | Detail |
 |---|---|
 | **Status bar item** | Shows health grade (`A`/`B`/`C`/`D`) + time since last regen; refreshes every 60 s |
 | **Stale notification** | Warns when `copilot-instructions.md` is > 24 h old; one-click regeneration |
-| **Regenerate command** | `SigMap: Regenerate Context` — runs `node gen-context.js` in the integrated terminal |
+| **Regenerate command** | `SigMap: Regenerate Context` — runs `sigmap` in the integrated terminal |
 | **Open context command** | `SigMap: Open Context File` — opens `.github/copilot-instructions.md` |
-| **Script path setting** | `sigmap.scriptPath` — override when `gen-context.js` is not at the project root |
+| **Script path setting** | `sigmap.scriptPath` — override the path to the `sigmap` binary or `gen-context.js` |
 
-Activate on startup (`onStartupFinished`) — loads within 3 s, never blocks editor startup.
+Activates on startup (`onStartupFinished`) — loads within 3 s, never blocks editor startup.
 
 **Install:** [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=manojmallick.sigmap) | [Open VSX Registry](https://open-vsx.org/extension/manojmallick/sigmap)
 
@@ -392,12 +441,12 @@ Activate on startup (`onStartupFinished`) — loads within 3 s, never blocks edi
 
 ## 🔧 JetBrains plugin
 
-The `jetbrains-plugin/` directory contains a Kotlin-based plugin for JetBrains IDEs with the same core features as the VS Code extension.
+The official SigMap JetBrains plugin brings the same features to IntelliJ-based IDEs. Install it from the JetBrains Marketplace and it works identically to the VS Code extension.
 
 | Feature | Detail |
 |---|---|
 | **Status bar widget** | Shows health grade (`A`-`F`) + time since last regen; updates every 60 s |
-| **Regenerate action** | `Tools → SigMap → Regenerate Context` or **Ctrl+Alt+G** — runs `node gen-context.js` |
+| **Regenerate action** | `Tools → SigMap → Regenerate Context` or **Ctrl+Alt+G** — runs `sigmap` |
 | **Open context action** | `Tools → SigMap → Open Context File` — opens `.github/copilot-instructions.md` |
 | **View roadmap action** | `Tools → SigMap → View Roadmap` — opens roadmap in browser |
 | **One-click regen** | Click status bar widget to regenerate context instantly |
@@ -495,7 +544,7 @@ Recently committed files are **hot** (auto-injected). Everything else is **cold*
 Start the MCP server on stdio:
 
 ```bash
-node gen-context.js --mcp
+sigmap --mcp
 ```
 
 ### Available tools
@@ -576,11 +625,11 @@ sigmap --help                                 Usage information
 ### Task classification — `--suggest-tool`
 
 ```bash
-node gen-context.js --suggest-tool "security audit of the auth module"
+sigmap --suggest-tool "security audit of the auth module"
 # tier   : powerful
 # models : claude-opus-4-6, gpt-5-4, gemini-2-5-pro
 
-node gen-context.js --suggest-tool "fix a typo in the yaml config" --json
+sigmap --suggest-tool "fix a typo in the yaml config" --json
 # {"tier":"fast","label":"Fast (low-cost)","models":"claude-haiku-4-5, ...","costHint":"~$0.0008 / 1K tokens"}
 ```
 
@@ -646,7 +695,7 @@ build/
 test/fixtures/
 ```
 
-Run `node gen-context.js --init` to scaffold both files in one step.
+Run `sigmap --init` to scaffold both files in one step.
 
 ### Output targets
 
@@ -676,14 +725,14 @@ If `output` is omitted, the default `.github/copilot-instructions.md` is used.
 
 ```bash
 # Append run metrics to .context/usage.ndjson
-node gen-context.js --track
+sigmap --track
 
 # Structured JSON report for CI (exits 1 if over budget)
-node gen-context.js --report --json
+sigmap --report --json
 # { "version": "2.0.0", "finalTokens": 3200, "reductionPct": 92.4, "overBudget": false }
 
 # Composite health score
-node gen-context.js --health
+sigmap --health
 # score: 95/100 (grade A) | reduction: 91.2% | 1 day since regen | 47 runs
 ```
 
@@ -695,9 +744,9 @@ Copy `examples/self-healing-github-action.yml` to `.github/workflows/` to auto-r
 
 ```yaml
 - name: SigMap health check
-  run: node gen-context.js --health --json
+  run: sigmap --health --json
 - name: Regenerate context
-  run: node gen-context.js
+  run: sigmap
 ```
 
 📖 Full guide: [docs/readmes/ENTERPRISE_SETUP.md](docs/readmes/ENTERPRISE_SETUP.md)
@@ -705,7 +754,7 @@ Copy `examples/self-healing-github-action.yml` to `.github/workflows/` to auto-r
 ### Prompt caching — 60% API cost reduction
 
 ```bash
-node gen-context.js --format cache
+sigmap --format cache
 # Writes: .github/copilot-instructions.cache.json
 # Format: { type: 'text', text: '...', cache_control: { type: 'ephemeral' } }
 ```
@@ -840,7 +889,7 @@ sigmap/
 
 | Principle | Implementation |
 |---|---|
-| **Zero npm dependencies** | `node gen-context.js` on a blank machine with Node 18+ — nothing else required |
+| **Zero npm dependencies** | `npx sigmap` on any machine — no install required. Or use the standalone binary for zero Node.js dependency. |
 | **Never throw** | All extractors return `[]` on any error — the run always completes |
 | **Deterministic** | No AI or LLM involved in extraction — only regex + Node built-ins |
 | **Repomix is a companion** | Use both tools; SigMap never replaces Repomix |

package/gen-context.config.json.example

@@ -3,7 +3,7 @@
 
   "output": ".github/copilot-instructions.md",
 
-  "outputs": ["copilot"],
+  "outputs": ["copilot", "codex"],
 
   "srcDirs": ["src", "app", "lib", "packages", "services", "api"],
 

package/gen-context.js

@@ -34,7 +34,7 @@ __factories["./src/config/defaults"] = function(module, exports) {
     // Output targets: 'copilot' | 'claude' | 'cursor' | 'windsurf'
     outputs: ['copilot'],
 
-    // Adapter targets (v3.0+): replaces 'outputs'. Same names, adds 'openai' | 'gemini'.
+    // Adapter targets (v3.0+): replaces 'outputs'. Same names, adds 'openai' | 'gemini' | 'codex'.
     // Old 'outputs' config key is still accepted and silently maps to 'adapters'.
     adapters: null, // null means: use 'outputs' for backward compat
   
@@ -173,7 +173,7 @@ __factories["./src/config/loader"] = function(module, exports) {
     if (!merged.adapters && Array.isArray(merged.outputs)) {
       merged.adapters = merged.outputs.slice();
     } else if (Array.isArray(merged.adapters) && !userConfig.outputs) {
-      merged.outputs = merged.adapters.filter((a) => ['copilot','claude','cursor','windsurf'].includes(a));
+      merged.outputs = merged.adapters.filter((a) => ['copilot','claude','cursor','windsurf','codex'].includes(a));
     }
     return merged;
   }
@@ -3700,7 +3700,7 @@ __factories["./src/mcp/server"] = function(module, exports) {
   
   const SERVER_INFO = {
     name: 'sigmap',
-    version: '3.2.1',
+    version: '3.3.2',
     description: 'SigMap MCP server — code signatures on demand',
   };
   
@@ -4888,7 +4888,9 @@ __factories["./src/eval/runner"] = function(module, exports) {
 // ── ./packages/adapters/copilot (bundled) ──
 __factories["./packages/adapters/copilot"] = function(module, exports) {
   const path = require('path');
+  const fs = require('fs');
   const name = 'copilot';
+  const COPILOT_MARKER = '\n\n## Auto-generated signatures\n<!-- Updated by gen-context.js -->\n';
   function format(context, opts = {}) {
     if (!context || typeof context !== 'string') return '';
     const version = (opts && opts.version) || 'unknown';
@@ -4904,7 +4906,20 @@ __factories["./packages/adapters/copilot"] = function(module, exports) {
     ].join('\n');
   }
   function outputPath(cwd) { return path.join(cwd, '.github', 'copilot-instructions.md'); }
-  module.exports = { name, format, outputPath };
+  function write(context, cwd, opts = {}) {
+    const filePath = outputPath(cwd);
+    let existing = '';
+    if (fs.existsSync(filePath)) existing = fs.readFileSync(filePath, 'utf8');
+    const formatted = format(context, opts);
+    const markerIdx = existing.indexOf('## Auto-generated signatures');
+    const isLegacyGenerated = existing.includes('<!-- Generated by SigMap gen-context.js') || existing.includes('# Code signatures');
+    const newContent = markerIdx !== -1
+      ? existing.slice(0, markerIdx) + COPILOT_MARKER.trimStart() + formatted
+      : (isLegacyGenerated ? COPILOT_MARKER.trimStart() + formatted : existing + COPILOT_MARKER + formatted);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, newContent, 'utf8');
+  }
+  module.exports = { name, format, outputPath, write };
 };
 
 // ── ./packages/adapters/claude (bundled) ──
@@ -4989,7 +5004,9 @@ __factories["./packages/adapters/openai"] = function(module, exports) {
 // ── ./packages/adapters/gemini (bundled) ──
 __factories["./packages/adapters/gemini"] = function(module, exports) {
   const path = require('path');
+  const fs = require('fs');
   const name = 'gemini';
+  const GEMINI_MARKER = '\n\n## Auto-generated signatures\n<!-- Updated by gen-context.js -->\n';
   function format(context, opts = {}) {
     if (!context || typeof context !== 'string') return '';
     const version = (opts && opts.version) || 'unknown';
@@ -5007,12 +5024,51 @@ __factories["./packages/adapters/gemini"] = function(module, exports) {
     ].join('\n');
   }
   function outputPath(cwd) { return path.join(cwd, '.github', 'gemini-context.md'); }
-  module.exports = { name, format, outputPath };
+  function write(context, cwd, opts = {}) {
+    const filePath = outputPath(cwd);
+    let existing = '';
+    if (fs.existsSync(filePath)) existing = fs.readFileSync(filePath, 'utf8');
+    const formatted = format(context, opts);
+    const markerIdx = existing.indexOf('## Auto-generated signatures');
+    const isLegacyGenerated = existing.includes('<!-- Generated by SigMap gen-context.js') || existing.includes('## Code Signatures');
+    const newContent = markerIdx !== -1
+      ? existing.slice(0, markerIdx) + GEMINI_MARKER.trimStart() + formatted
+      : (isLegacyGenerated ? GEMINI_MARKER.trimStart() + formatted : existing + GEMINI_MARKER + formatted);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, newContent, 'utf8');
+  }
+  module.exports = { name, format, outputPath, write };
+};
+
+// ── ./packages/adapters/codex (bundled) ──
+__factories["./packages/adapters/codex"] = function(module, exports) {
+  const path = require('path');
+  const fs = require('fs');
+  const openai = __require('./packages/adapters/openai');
+  const name = 'codex';
+  const CODEX_MARKER = '\n\n## Auto-generated signatures\n<!-- Updated by gen-context.js -->\n';
+  function format(context, opts = {}) {
+    return openai.format(context, opts);
+  }
+  function outputPath(cwd) { return path.join(cwd, 'AGENTS.md'); }
+  function write(context, cwd, opts = {}) {
+    const filePath = outputPath(cwd);
+    let existing = '';
+    if (fs.existsSync(filePath)) existing = fs.readFileSync(filePath, 'utf8');
+    const formatted = format(context, opts);
+    const markerIdx = existing.indexOf('## Auto-generated signatures');
+    const isLegacyGenerated = existing.includes('<!-- Generated by SigMap gen-context.js') || existing.includes('## Code Signatures') || existing.includes('# Code signatures');
+    const newContent = markerIdx !== -1
+      ? existing.slice(0, markerIdx) + CODEX_MARKER.trimStart() + formatted
+      : (isLegacyGenerated ? CODEX_MARKER.trimStart() + formatted : existing + CODEX_MARKER + formatted);
+    fs.writeFileSync(filePath, newContent, 'utf8');
+  }
+  module.exports = { name, format, outputPath, write };
 };
 
 // ── ./packages/adapters/index (bundled) ──
 __factories["./packages/adapters/index"] = function(module, exports) {
-  const ADAPTER_NAMES = ['copilot', 'claude', 'cursor', 'windsurf', 'openai', 'gemini'];
+  const ADAPTER_NAMES = ['copilot', 'claude', 'cursor', 'windsurf', 'openai', 'gemini', 'codex'];
   const _adapterCache = {};
   function getAdapter(name) {
     if (!name || typeof name !== 'string') return null;
@@ -5049,7 +5105,7 @@ const path = require('path');
 const os = require('os');
 const { execSync } = require('child_process');
 
-const VERSION = '3.3.1';
+const VERSION = '3.3.2';
 const MARKER = '\n\n## Auto-generated signatures\n<!-- Updated by gen-context.js -->\n';
 
 function requireSourceOrBundled(key) {
@@ -5619,6 +5675,7 @@ function resolveAdapterPath(adapter, cwd, config) {
   if (adapter === 'claude') return path.join(cwd, 'CLAUDE.md');
   if (adapter === 'cursor') return path.join(cwd, '.cursorrules');
   if (adapter === 'windsurf') return path.join(cwd, '.windsurfrules');
+  if (adapter === 'codex') return path.join(cwd, 'AGENTS.md');
   
   return null;
 }
@@ -5641,7 +5698,7 @@ function writeCacheOutput(content, cwd) {
 function writeOutputs(content, targets, cwd, config) {
   config = config || {};
   // v3.0+: adapter-aware output targets
-  const ADAPTER_TARGETS = new Set(['openai', 'gemini']);
+  const ADAPTER_TARGETS = new Set(['copilot', 'openai', 'gemini', 'codex']);
 
   const targetMap = {
     copilot: resolveAdapterPath('copilot', cwd, config),
@@ -5654,15 +5711,21 @@ function writeOutputs(content, targets, cwd, config) {
       writeClaude(content, cwd);
       continue;
     }
-    // v3.0+ adapter targets (openai, gemini) — use bundled adapter to format + write
+    // v3.0+ adapter targets (copilot, openai, gemini, codex) — use bundled adapter to format + write
     if (ADAPTER_TARGETS.has(target)) {
       try {
         const adapterMod = __require('./packages/adapters/' + target);
-        const formatted = adapterMod.format(content, { version: VERSION });
-        const outPath = adapterMod.outputPath(cwd);
-        ensureDir(outPath);
-        fs.writeFileSync(outPath, formatted, 'utf8');
-        console.warn(`[sigmap] wrote ${path.relative(cwd, outPath)}`);
+        if (typeof adapterMod.write === 'function') {
+          adapterMod.write(content, cwd, { version: VERSION });
+          const outPath = adapterMod.outputPath(cwd);
+          console.warn(`[sigmap] wrote ${path.relative(cwd, outPath)} (appended signatures)`);
+        } else {
+          const formatted = adapterMod.format(content, { version: VERSION });
+          const outPath = adapterMod.outputPath(cwd);
+          ensureDir(outPath);
+          fs.writeFileSync(outPath, formatted, 'utf8');
+          console.warn(`[sigmap] wrote ${path.relative(cwd, outPath)}`);
+        }
       } catch (err) {
         console.warn(`[sigmap] adapter "${target}" failed: ${err.message}`);
       }
@@ -6420,8 +6483,8 @@ Strategies (set via config "strategy" key):
                 ~90% fewer tokens. Best with MCP (Claude Code, Cursor).
                 Set "hotCommits": N to control how many commits count as hot (default 10).
 
-Adapters (v3.0+): copilot | claude | cursor | windsurf | openai | gemini
-  Set "adapters": ["copilot","openai"] in config to write multiple adapter outputs.
+Adapters (v3.0+): copilot | claude | cursor | windsurf | openai | gemini | codex
+  Set "adapters": ["copilot","openai","codex"] in config to write multiple adapter outputs.
   Old "outputs" config key is still accepted (maps to adapters automatically).
 
 Config: gen-context.config.json
@@ -6760,7 +6823,7 @@ function main() {
   // handled here (per-repo) rather than running a single generate on the
   // parent directory.
   if (args.includes('--each')) {
-    const VALID_ADAPTERS = ['copilot', 'claude', 'cursor', 'windsurf', 'openai', 'gemini'];
+    const VALID_ADAPTERS = ['copilot', 'claude', 'cursor', 'windsurf', 'openai', 'gemini', 'codex'];
     const adpIdx = args.indexOf('--adapter');
     const adapterOverride = adpIdx >= 0 ? (args[adpIdx + 1] || '').trim().toLowerCase() : null;
     if (adapterOverride && !VALID_ADAPTERS.includes(adapterOverride)) {
@@ -6777,7 +6840,7 @@ function main() {
     try {
       const adpIdx = args.indexOf('--adapter');
       const adapterName = (args[adpIdx + 1] || '').trim().toLowerCase();
-      const VALID_ADAPTERS = ['copilot', 'claude', 'cursor', 'windsurf', 'openai', 'gemini'];
+      const VALID_ADAPTERS = ['copilot', 'claude', 'cursor', 'windsurf', 'openai', 'gemini', 'codex'];
       if (!adapterName || adapterName.startsWith('--')) {
         console.error('[sigmap] --adapter requires an adapter name');
         console.error(`  Valid adapters: ${VALID_ADAPTERS.join(', ')}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigmap",
-  "version": "3.3.1",
+  "version": "3.3.2",
   "description": "Zero-dependency AI context engine — 97% token reduction. No npm install. Runs on Node 18+.",
   "main": "gen-context.js",
   "exports": {
@@ -36,6 +36,7 @@
     "src/",
     "packages/",
     "README.md",
+    "AGENTS.md",
     "LICENSE",
     "CHANGELOG.md",
     ".contextignore.example",

package/packages/adapters/codex.js

@@ -0,0 +1,74 @@
+'use strict';
+
+/**
+ * Codex adapter — writes OpenAI-style context to AGENTS.md.
+ *
+ * This adapter reuses the same prompt format as the OpenAI adapter,
+ * but targets AGENTS.md so Codex-style agents can read repository guidance.
+ *
+ * Contract:
+ *   format(context, opts?) → string
+ *   outputPath(cwd) → string
+ *   write(context, cwd, opts?) → void
+ */
+
+const path = require('path');
+const fs = require('fs');
+const openai = require('./openai');
+
+const name = 'codex';
+const MARKER = '\n\n## Auto-generated signatures\n<!-- Updated by gen-context.js -->\n';
+
+/**
+ * Format context using the OpenAI adapter format.
+ * @param {string} context - Raw signature context string
+ * @param {object} [opts]
+ * @returns {string}
+ */
+function format(context, opts = {}) {
+  return openai.format(context, opts);
+}
+
+/**
+ * Return the output file path for this adapter.
+ * @param {string} cwd - Project root
+ * @returns {string}
+ */
+function outputPath(cwd) {
+  return path.join(cwd, 'AGENTS.md');
+}
+
+/**
+ * Write signatures into AGENTS.md using append-under-marker.
+ * If marker exists, content above marker is preserved.
+ * If legacy generated content exists without marker, replace it cleanly.
+ * @param {string} context - Raw signature context string
+ * @param {string} cwd - Project root
+ * @param {object} [opts]
+ */
+function write(context, cwd, opts = {}) {
+  const filePath = outputPath(cwd);
+  let existing = '';
+  if (fs.existsSync(filePath)) {
+    existing = fs.readFileSync(filePath, 'utf8');
+  }
+
+  const formatted = format(context, opts);
+  const markerIdx = existing.indexOf('## Auto-generated signatures');
+
+  let newContent;
+  if (markerIdx !== -1) {
+    newContent = existing.slice(0, markerIdx) + MARKER.trimStart() + formatted;
+  } else {
+    const isLegacyGenerated = existing.includes('<!-- Generated by SigMap gen-context.js')
+      || existing.includes('## Code Signatures')
+      || existing.includes('# Code signatures');
+    newContent = isLegacyGenerated
+      ? MARKER.trimStart() + formatted
+      : existing + MARKER + formatted;
+  }
+
+  fs.writeFileSync(filePath, newContent, 'utf8');
+}
+
+module.exports = { name, format, outputPath, write };

package/packages/adapters/copilot.js

@@ -10,8 +10,10 @@
  */
 
 const path = require('path');
+const fs = require('fs');
 
 const name = 'copilot';
+const MARKER = '\n\n## Auto-generated signatures\n<!-- Updated by gen-context.js -->\n';
 
 /**
  * Format context for GitHub Copilot instructions.
@@ -44,4 +46,37 @@ function outputPath(cwd) {
   return path.join(cwd, '.github', 'copilot-instructions.md');
 }
 
-module.exports = { name, format, outputPath };
+/**
+ * Write signatures into copilot-instructions.md using append-under-marker.
+ * If marker exists, content above marker is preserved.
+ * If legacy generated content exists without marker, replace it cleanly.
+ * @param {string} context - Raw signature context string
+ * @param {string} cwd - Project root
+ * @param {object} [opts]
+ */
+function write(context, cwd, opts = {}) {
+  const filePath = outputPath(cwd);
+  let existing = '';
+  if (fs.existsSync(filePath)) {
+    existing = fs.readFileSync(filePath, 'utf8');
+  }
+
+  const formatted = format(context, opts);
+  const markerIdx = existing.indexOf('## Auto-generated signatures');
+
+  let newContent;
+  if (markerIdx !== -1) {
+    newContent = existing.slice(0, markerIdx) + MARKER.trimStart() + formatted;
+  } else {
+    const isLegacyGenerated = existing.includes('<!-- Generated by SigMap gen-context.js')
+      || existing.includes('# Code signatures');
+    newContent = isLegacyGenerated
+      ? MARKER.trimStart() + formatted
+      : existing + MARKER + formatted;
+  }
+
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, newContent, 'utf8');
+}
+
+module.exports = { name, format, outputPath, write };

package/packages/adapters/gemini.js

@@ -15,8 +15,10 @@
  */
 
 const path = require('path');
+const fs = require('fs');
 
 const name = 'gemini';
+const MARKER = '\n\n## Auto-generated signatures\n<!-- Updated by gen-context.js -->\n';
 
 /**
  * Format context as a Gemini system instruction.
@@ -56,4 +58,37 @@ function outputPath(cwd) {
   return path.join(cwd, '.github', 'gemini-context.md');
 }
 
-module.exports = { name, format, outputPath };
+/**
+ * Write signatures into gemini-context.md using append-under-marker.
+ * If marker exists, content above marker is preserved.
+ * If legacy generated content exists without marker, replace it cleanly.
+ * @param {string} context - Raw signature context string
+ * @param {string} cwd - Project root
+ * @param {object} [opts]
+ */
+function write(context, cwd, opts = {}) {
+  const filePath = outputPath(cwd);
+  let existing = '';
+  if (fs.existsSync(filePath)) {
+    existing = fs.readFileSync(filePath, 'utf8');
+  }
+
+  const formatted = format(context, opts);
+  const markerIdx = existing.indexOf('## Auto-generated signatures');
+
+  let newContent;
+  if (markerIdx !== -1) {
+    newContent = existing.slice(0, markerIdx) + MARKER.trimStart() + formatted;
+  } else {
+    const isLegacyGenerated = existing.includes('<!-- Generated by SigMap gen-context.js')
+      || existing.includes('## Code Signatures');
+    newContent = isLegacyGenerated
+      ? MARKER.trimStart() + formatted
+      : existing + MARKER + formatted;
+  }
+
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, newContent, 'utf8');
+}
+
+module.exports = { name, format, outputPath, write };

package/packages/adapters/index.js

@@ -11,14 +11,14 @@
 
 const path = require('path');
 
-const ADAPTER_NAMES = ['copilot', 'claude', 'cursor', 'windsurf', 'openai', 'gemini'];
+const ADAPTER_NAMES = ['copilot', 'claude', 'cursor', 'windsurf', 'openai', 'gemini', 'codex'];
 
 // Lazy-load adapters so unused ones don't pay any require() cost
 const _cache = {};
 
 /**
  * Load and return an adapter module by name.
- * @param {string} name - Adapter name (copilot|claude|cursor|windsurf|openai|gemini)
+ * @param {string} name - Adapter name (copilot|claude|cursor|windsurf|openai|gemini|codex)
  * @returns {{ name: string, format: Function, outputPath: Function }|null}
  */
 function getAdapter(name) {

package/packages/cli/package.json

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

package/src/mcp/server.js

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