engramx 3.3.0 → 3.4.0

package/CHANGELOG.md

@@ -6,14 +6,46 @@ All notable changes to engram are documented here. Format based on
 
 ## [Unreleased]
 
-### Added — v3.3 "Cost Lens" (in progress, target: 2026-05-08)
+## [3.4.0] — 2026-05-02 — "Universal Spine"
+
+The release that turns engram from a Claude Code tool into a universal context spine across every major AI coding tool. Same engram, same graph, same 89.1% reduction — now plugged into 8 IDEs out of the box.
+
+### Added
+
+- **Universal init detector.** `src/setup/detect.ts` adds three new detectors: `detectCline` (probes for VS Code's Cline globalStorage), `detectZed` (probes for Zed's config and `.zed/settings.json`), `detectCodex` (probes for `~/.codex` and `AGENTS.md`). `detectAllIdes()` now returns 8 entries (was 5). Per-IDE setup hints in `wizard.ts` now include the exact MCP config snippet for Cline.
+- **Anthropic Claude Code plugin manifest.** `plugins/anthropic-marketplace/` — submission-ready `marketplace.json`, `plugin.json`, three skills (`/engram:cost`, `/engram:query`, `/engram:mistakes`), and the MCP server config that registers `engram-serve` automatically. Verified against `code.claude.com/docs/en/plugins`.
+- **VS Code / Cursor extension.** `extensions/vscode/` — thin wrapper around the engramx CLI. Six commands (init, gen-mdc, gen, cost, dashboard, doctor), status-bar entry, two configuration settings. Compiles to a single `out/extension.js` and packs via `vsce` for OpenVSX. Works in VS Code, Cursor, and any VS Code fork.
+- **Cline integration documented.** `docs/integrations/cline.md` — Cline supports MCP natively, so the integration is one config-snippet away. Cross-linked from `docs/integrations/README.md`.
+- **engramx-continue.** Sister npm package at `adapters/continue/` — Continue.dev `@engram` context provider with HTTP and CLI fallback transports. Tarball verified clean (2.2 KB, 4 files).
+
+### Changed
+
+- **README.md.** Top-of-file callout now leads with the May 2026 market context (Cursor pricing crisis + Claude Code rate-limit pain) so the positioning matches what users are actually searching for. IDE matrix expanded from 8 to 11. "How It Compares" rewritten as the May 2026 8-row competitive matrix (engramx vs Cursor index / Aider repo map / Cline / Continue / Mem0 / claude-mem / CartoGopher); legacy table moved to a collapsed details block.
+- **docs/install.html.** Title, meta description, OG title + description, hero pill, nav link, and IDE matrix all refreshed for v3.4 framing.
+- **GitHub repo description and topics.** Description shortened and re-led with "context spine that 10x's every AI coding session." Topics maxed at 20 with `cline` and `universal-spine` added.
+
+### Tests
+- Net-new: 3 detector tests in `tests/setup/detect.test.ts` (detectCline / detectZed / detectCodex).
+- Total: **910 passing** (was 907 baseline).
+
+### Process
+
+This is the first release that walks the new 8-phase release ritual codified at `~/.claude/skills/engram-release/SKILL.md`. Phase 3 (public surface refresh) caught README + install.html + topics drift in one pass. Future releases follow the same checklist by default.
+
+### Why
+
+Three things broke at the same time in 2026. Cursor went usage-based and people started getting $1,400 surprise bills. Anthropic tightened Claude Code limits, then quietly tested removing the product from the $20 Pro plan. AI coding fragmented into 8 IDEs with no common context layer. v3.4 puts engram into all of them — one install, one graph, every tool benefits. Audit at `~/Desktop/Projects/Engram/00-strategy/2026-05-02-strategic-audit-v34-pivot.md`.
+
+## [3.3.0] — 2026-05-02 — "Cost Lens"
+
+### Added
 - New `engram cost` subcommand: aggregates token-savings telemetry from existing `.engram/hook-log.jsonl` files across one or many project roots. Outputs a terminal table, JSON, or a weekly Markdown digest at `~/.engram/cost-report-YYYY-Www.md`.
-- New `src/cost/` module: `types.ts` (CostEvent / CostSummary / CostConfig), `aggregator.ts` (read + summarize), `formatter.ts` (one-liner / table / Markdown digest), `digest.ts` (ISO-week digest writer with idempotent file output).
-- 13 new tests in `tests/cost.test.ts`, hermetic — use tmp dirs with synthetic logs, no real engram state required.
-- USD estimate uses configurable `inputUsdPerMillion` rate. Default $3.00/M matches Claude Sonnet 4.6 input pricing as of 2026-04-27.
+- New `src/cost/` module: `types.ts`, `aggregator.ts`, `formatter.ts`, `digest.ts`, `instrument.ts`. Pure functions, hermetic tests, NaN-safe math.
+- Dispatch instrumentation in `src/intercept/dispatch.ts` — every PreToolUse log entry now carries `wouldHaveRead`, `injected`, and `tokensSaved` fields when applicable.
+- 31 new tests across `tests/cost.test.ts` and `tests/cost-instrument.test.ts`, hermetic.
 
 ### Why
-Cost Lens is the baseline for everything in the v3.3 → v4.0 roadmap. We need a measured number that survives between releases so future features (Mesh, Vector, Bridge) can be evaluated against the real-world impact, not against a single benchmark file. The PRD lives at `01-prds/03-engram-mesh-ruflo-integration-PRD.md`.
+Cost Lens is the baseline for the v3.3 → v4.0 roadmap. Future features (Bridge, Mesh, Vector) get evaluated against the real-world impact, not a single static benchmark. PRD: `01-prds/03-engram-mesh-ruflo-integration-PRD.md`.
 
 ## [3.0.2] — 2026-04-24 — "MCP Registry"
 

package/README.md

@@ -1,181 +1,131 @@
 <p align="center">
-  <img src="assets/banner-v3.png" alt="EngramX — the memory layer for AI coding agents" width="100%">
+  <img src="assets/banner-v3.png" alt="EngramX — the cached context spine for AI coding agents (v3.0 'Spine')" width="100%">
 </p>
 
+<!-- ============================================================
+     24-second product showcase (Hyperframes-rendered MP4 + WebM).
+     Source: docs/demos/showcase.html · scenes drive both the
+     live HTML player and this MP4. Edit scene-table.md to change.
+     If the MP4 isn't rendered yet, GitHub gracefully shows the
+     poster image and links to the live HTML player.
+     ============================================================ -->
 <p align="center">
-  <strong>The memory layer that stretches every Claude session.</strong>
+  <video src="https://raw.githubusercontent.com/NickCirv/engram/main/docs/demos/showcase.mp4"
+         controls
+         muted
+         playsinline
+         poster="docs/demos/poster.svg"
+         width="100%">
+    <a href="docs/demos/showcase.html">
+      <img src="docs/demos/poster.svg" alt="engram — 24-second showcase (click to open the live HTML player)" width="100%">
+    </a>
+  </video>
+</p>
+
+<p align="center">
+  <sub>
+    <a href="docs/install.html"><strong>Install Page</strong></a> ·
+    <a href="docs/demos/showcase.html"><strong>Live Demo</strong></a> ·
+    <a href="docs/demos/scene-table.md"><strong>Scene Table</strong></a> ·
+    rendered with <a href="https://github.com/heygen-com/hyperframes">Hyperframes</a>
+  </sub>
+</p>
+
+<p align="center">
+  <a href="#install"><strong>Install</strong></a> ·
+  <a href="#quickstart"><strong>Quickstart</strong></a> ·
+  <a href="#dashboard"><strong>Dashboard</strong></a> ·
+  <a href="#benchmark"><strong>Benchmark</strong></a> ·
+  <a href="#ide-integrations"><strong>IDE Integrations</strong></a> ·
+  <a href="#http-api"><strong>HTTP API</strong></a> ·
+  <a href="#ecp-spec"><strong>ECP Spec</strong></a> ·
+  <a href="#contributing"><strong>Contributing</strong></a>
 </p>
 
 <p align="center">
   <a href="https://github.com/NickCirv/engram/actions"><img src="https://github.com/NickCirv/engram/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
   <a href="https://www.npmjs.com/package/engramx"><img src="https://img.shields.io/npm/v/engramx?color=blue" alt="npm version"></a>
-  <a href="https://www.npmjs.com/package/engramx"><img src="https://img.shields.io/npm/dm/engramx?color=blue" alt="npm downloads"></a>
   <img src="https://img.shields.io/badge/license-Apache%202.0-blue" alt="License">
   <img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen" alt="Node">
-  <img src="https://img.shields.io/badge/tests-878%20passing-brightgreen" alt="Tests">
+  <img src="https://img.shields.io/badge/tests-910%20passing-brightgreen" alt="Tests">
   <img src="https://img.shields.io/badge/providers-9%20%2B%20plugins-blue" alt="9 Providers + plugins">
+  <img src="https://img.shields.io/badge/token%20savings-89.1%25%20measured-orange" alt="89.1% measured savings">
   <img src="https://img.shields.io/badge/native%20deps-zero-green" alt="Zero native deps">
-  <a href="https://discord.gg/engramx"><img src="https://img.shields.io/badge/Discord-join-5865F2?logo=discord&logoColor=white" alt="Discord"></a>
-  <a href="https://github.com/NickCirv/engram/stargazers"><img src="https://img.shields.io/github/stars/NickCirv/engram?style=social" alt="Stars"></a>
-</p>
-
-<p align="center">
-  <a href="#anthropic-capped-your-week-engram-extends-it">Why</a> ·
-  <a href="#install">Install</a> ·
-  <a href="#per-agent-setup">Per-agent setup</a> ·
-  <a href="#see-what-your-agent-has-remembered">engram remembers</a> ·
-  <a href="#how-it-works">How it works</a> ·
-  <a href="ARCHITECTURE.md">Architecture</a> ·
-  <a href="https://discord.gg/engramx">Discord</a>
+  <img src="https://img.shields.io/badge/LLM%20cost-$0-green" alt="Zero LLM cost">
 </p>
 
 ---
 
-## Anthropic capped your week. engram extends it.
+## Why this exists, May 2026
 
-In November 2025, Anthropic tightened weekly limits on Claude Pro and Max. Heavy Claude Code users now hit caps mid-week. Some by Wednesday. The honest reality nobody is naming out loud:
+Three things broke at the same time. Cursor went usage-based and people started getting $1,400 surprise bills. Anthropic tightened Claude Code limits, then quietly tested removing it from the $20 Pro plan. Half the AI coding crowd migrated from one tool to the other, hit the new ceiling within a week, and started looking for any way to make a session last longer.
 
-> **Most of your weekly tokens are spent re-introducing yourself to an agent that forgets.**
+Engramx is what makes the session last longer. It indexes your codebase into a local SQLite knowledge graph once. Then it intercepts file reads at the agent boundary and replaces them with a structural summary the agent already has the working memory for. Same edit, same diff, same code shipped — fewer tokens consumed in the round trip.
 
-Every Monday starts from zero. The agent re-reads the codebase. Re-asks setup questions. Repeats last week's wrong fix. Re-decides architecture you already locked in. By Friday you're rate-limited. Not because you built a lot. Because the agent never got smarter.
+On a real 87-file repo, the measured reduction is **89.1%**. That's not a marketing number. The benchmark is committed to this repo as `bench/real-world.ts` and runs against any project you point it at. Independent migration guides ([dev.to/56kode](https://dev.to/56_kode/why-were-moving-from-cursor-to-claude-code-and-why-you-should-too-9kh), [SpectrumAI Lab](https://spectrumailab.com/blog/claude-code-vs-cursor)) cite engram as the strongest measured number in the category.
 
-engram is the memory layer that fixes that. A persistent knowledge graph, plus a mistake replay buffer, plus a provider mesh that wires in mempalace, obsidian, context7, MCP servers, and Anthropic's own auto-memory. The agent stops being single-shot. It learns from its own history.
+Works in 8 IDEs and counting — Claude Code, Cursor, Cline, Continue.dev, Aider, Windsurf, Zed, OpenAI Codex CLI. One install, one graph, every tool benefits. Apache 2.0. Local SQLite. Nothing leaves your machine.
 
----
-
-### What changes when your agent has memory
+> **v3.4 "Universal Spine" shipped 2026-05-02** — multi-IDE detector covers 8 tools, Anthropic Claude Code plugin (`/plugin install engram`), VS Code / Cursor extension on OpenVSX, `engramx-continue` on npm, Cline integration documented. Cost Lens telemetry from v3.3.0 now feeds a weekly Markdown digest at `~/.engram/cost-report-YYYY-Www.md`. 910 tests, CI green on Ubuntu + Windows × Node 20 + 22. See [CHANGELOG.md](CHANGELOG.md) for the v3.3 + v3.4 diff.
 
-| | Without engram | With engram |
-|---|---|---|
-| **Monday** | Agent re-reads codebase from scratch (~40K tokens) | Reads structural graph (~3K tokens) |
-| **Tuesday** | Repeats Monday's wrong fix | ⚠️ Warned: *"You tried this Monday, broke parser.rs:42"* |
-| **Wednesday** | Re-decides architecture you already locked | Surfaces Monday's decision: *"We chose Saga over 2PC because…"* |
-| **Thursday** | Asks the same 5 setup questions | Pulls config from `mempalace`, `obsidian`, `context7` providers |
-| **Friday** | Cap hit by 3pm | Cap hit Sunday, if at all |
-
-Token savings (89.1% measured per Read interception, reproducible benchmark below) are the side-effect. Compounding agent intelligence is the product.
+> **EngramX v3.0 "Spine" shipped 2026-04-24** — the biggest release before v3.4. The spine is **extensible**: any MCP server becomes an EngramX provider via a 10-line plugin file. **Pre-mortem mistake-guard** warns before you repeat a bug. **Bi-temporal mistake memory** — refactored-away mistakes stop firing. **Anthropic Auto-Memory bridge** reads Claude Code's own consolidated memory. **SSE-streaming** packets render progressively. `engram gen` dual-emits `AGENTS.md` + `CLAUDE.md` by default.
 
 ---
 
-## Install
+# EngramX — the cached context spine for AI coding agents.
 
-### macOS / Linux (recommended)
+Your AI coding agent keeps re-reading the same files. Every `Read`, every `Edit`, every `cat` re-pays for context you've already paid for.
 
-```bash
-brew install engramx
-```
+**EngramX is the spine.** It intercepts every file read at the tool boundary, answers from a pre-assembled context packet held in **three layers of cache** — a knowledge graph the agent has already "paid" to build, a per-provider SQLite cache of external lookups, and an in-memory LRU of recent queries — and hands the agent a single ~500-token response instead of a raw file.
 
-### Cross-platform fallback
+The agent gets what it needs. You stop paying for context you've already paid for. And **every plugin you add elevates the savings further** — Serena for LSP symbols, GitHub MCP for issue context, Sentry MCP for production errors, Supabase / Neon for schema. Each one closes another context leak the agent would otherwise burn tokens researching.
 
-```bash
-npm install -g engramx
-```
+**Measured savings on a reproducible benchmark: 89.1%.** Not estimated. 85 of 87 real source files saved tokens. Best case 98.4% (18,820 tokens → 306).
 
-### Zero-dep one-liner
+### One command to everything
 
 ```bash
-curl -fsSL engramx.dev/install | sh
+npm install -g engramx
+cd ~/my-project
+engram setup
 ```
 
-Verify: `engram --version` should show `3.x` or later. Requires Node.js 20+. Zero native deps. No build tools, no Rust, no Python, no system libs.
+That's the install. `engram setup` runs `engram init` (builds the graph), `engram install-hook` (wires the Sentinel into your AI tool), detects your IDE, dual-emits `AGENTS.md` + `CLAUDE.md`, then runs `engram doctor` to verify everything green. Under 30 seconds on most projects. Works in Claude Code, Cursor, Codex CLI, Windsurf, GitHub Copilot Chat, JetBrains Junie, Aider, Zed, Continue — any agent that reads `AGENTS.md` or uses MCP.
 
-> **Note:** "engram" the audio plugin and "engram" the neuroscience term are different things. We're `engramx` on npm, `engram` on the CLI. Also not [Go-Engram](https://github.com/Gentleman-Programming/engram) (a salience-gated chat memory in Go) and not DeepSeek's January 2026 "Engram" paper (research artifact, not a product).
+The **next session** you open starts with the spine pre-loaded: project brief already in context, file reads intercepted, a live HUD showing cumulative savings, bi-temporal mistakes waiting to warn you, and any plugins you've added already answering their domains.
 
 ---
 
-## Per-agent setup
+## I'm not a developer — what does this actually do?
 
-One command for your stack:
+Short answer: **your AI coding assistant stops charging you for the same information twice.**
 
-```bash
-engram init --agent claude          # Claude Code (default)
-engram init --agent cursor          # Cursor
-engram init --agent windsurf        # Windsurf
-engram init --agent codex           # OpenAI Codex
-engram init --agent gemini          # Gemini CLI
-engram init --agent cline           # Cline / Roo Code
-engram init --agent copilot         # GitHub Copilot CLI
-engram init --agent kilocode        # Kilo Code
-engram init --agent antigravity     # Google Antigravity
-```
+Long answer:
 
-One run wires the right hooks, settings, and per-agent config files. Restart your AI tool. engram is live.
+1. You ask your AI assistant (Claude Code, Cursor, Codex, whatever) to help with a file.
+2. The assistant tries to read that file. Normally it reads the whole thing, pays for every byte in tokens, and throws most of it away.
+3. EngramX catches the read, answers with a cached summary (the 50–200 lines the agent actually needs, plus context from your git history, past mistakes, library docs, and anything else useful), and lets the agent work from that.
+4. Your monthly AI bill drops. Multi-hour sessions stop hitting rate limits. The agent stops re-introducing bugs you already fixed — because EngramX remembers what broke.
 
-Prefer the all-in-one bootstrap? `engram setup` runs `engram init` + `engram install-hook` + IDE detection + dual-emits `AGENTS.md` and `CLAUDE.md` + `engram doctor`. Under 30 seconds on most projects.
+It runs on your laptop. It doesn't send your code anywhere. It's Apache 2.0. There's no account, no login, no cloud. You install it once and forget it's there.
 
----
+**Want even bigger savings?** Install a plugin. Each one closes a different context leak — see [Plugins multiply the savings](#plugins-multiply-the-savings) below. Drop a 10-line `.mjs` file in `~/.engram/plugins/` and the next session uses it.
 
-## See what your agent has remembered
+**Want out?** Clean uninstall is one command:
 
 ```bash
-$ engram remembers
-
-  43 mistakes avoided     ⚠️  surfaced before the agent could repeat them
- 127 decisions surfaced   📜  prior architectural choices recalled in context
-  18 cross-session bridges 🔗 sessions that picked up where the last one ended
-  86K tokens saved        🎟️  ~ 4.3 hours of weekly cap, reclaimed
-   7 days indexed         📅  since engram init
-
-Your subscription, stretched.
-```
-
-Cumulative since `engram init`. Run it weekly. Share the screenshot.
-
----
-
-## How it works
-
-```
-  Without engram:                              With engram:
-
-  Claude → reads file.rs (8,000 tokens)        Claude → reads file.rs
-                                                          ↓
-                                               engram intercepts → graph context (800 tokens)
-                                                          ↓
-                                               Claude sees: structure
-                                                         + last week's mistakes (⚠️ pre-mortem)
-                                                         + relevant decisions
-                                                         + git co-changes
-                                                         + cross-session memory
+npm uninstall -g engramx     # 3.0.1+ auto-runs preuninstall hook-cleanup
 ```
 
-Nine providers ship by default and every one is pluggable:
-
-| Provider | Surfaces |
-|---|---|
-| `structure` | AST-derived class/function/import graph of the project |
-| `mistakes` | What broke last week. Pre-mortem warnings before the agent re-makes the error. Bi-temporal: refactored-away mistakes stop firing. |
-| `git` | Hot files, co-change pairs, authorship signals |
-| `mempalace` | Your local semantic memory (mempalace MCP / ChromaDB) |
-| `context7` | Up-to-date library docs (Context7 MCP) |
-| `obsidian` | Your knowledge vault, queried at agent-time |
-| `anthropic-memory` | Anthropic's auto-memory bridge |
-| `mcp-client` | Any MCP server. engram talks to all of them. |
-| `lsp` | Live language-server symbols (Serena, etc.) |
-
-Add your own: drop a 10-line `.mjs` into `~/.engram/plugins/`. Validated before install.
-
----
-
-## Why this exists
-
-Stateless agents are amnesiacs with PhDs. They solve the problem in front of them, then never get smarter at *your* codebase. Multiply that by Anthropic's weekly caps and every session burns tokens re-learning what last session already learned.
-
-engram is the spine that connects sessions. It does what stateless tools physically can't:
-
-1. **Persistence.** `.engram/graph.db` survives every restart, every cap reset, every laptop reboot. Your agent gets a brain that remembers.
-2. **Mistake memory.** Pre-mortem warnings before the agent repeats last week's error. Surfaced at the top of context, automatically.
-3. **Provider mesh.** Runtime composition across knowledge sources you already use. mempalace, obsidian, context7, MCP servers, all wired in.
-
-Token compression is downstream of those.
+If you installed 3.0.0 and ran `npm uninstall` before the 3.0.1 patch shipped, your Claude Code hooks may be orphaned. Run `engram repair-hooks --scope user` (install 3.0.1 first if needed) or see the [`CHANGELOG.md`](CHANGELOG.md#301--2026-04-24--clean-uninstall) for the manual `jq`-based recovery one-liner.
 
 ---
 
 ## Proof, not promises
 
-Everything above is measured. `bench/real-world.ts` runs the full resolver against real files in this repo and compares the rich-packet token cost to the raw-file-read cost. Reproducible in one command on any project.
+Everything above is measured, not estimated. `bench/real-world.ts` runs the full resolver against real files in this repo and compares the rich-packet token cost to the raw-file-read cost. Reproducible in one command on any project.
 
-Latest run (2026-04-24, 87 source files, full report at [`bench/results/real-world-2026-04-24.md`](bench/results/real-world-2026-04-24.md)):
+Latest run (2026-04-24, 87 source files — full report at [`bench/results/real-world-2026-04-24.md`](bench/results/real-world-2026-04-24.md)):
 
 | Metric | Value |
 |---|---|
@@ -190,36 +140,23 @@ Reproduce on your own code:
 
 ```bash
 cd your-project
-engram init
+engram init                          # first-time setup for this project
 npx tsx /path/to/engram/bench/real-world.ts --project . --files 50
 ```
 
-Small projects score lower. Dense structural projects score higher. It's real arithmetic on your files. You can audit every number.
-
----
-
-## Companion tools
-
-engram compresses what the codebase *is* (file contents into graph context). For compressing what the system is *doing* (shell command output) pair it with [rtk](https://github.com/rtk-ai/rtk):
-
-```bash
-brew install rtk           # 60-90% savings on git/npm/cargo/grep/etc. (Bash)
-brew install engramx       # 89% savings + memory + mistake-guard (Read)
-```
-
-Both register PreToolUse hooks. They don't conflict. rtk owns Bash, engram owns Read. Run both for a 3-5x weekly cap stretch end to end.
+The bench writes a JSON + Markdown report per run into `bench/results/`. Small projects score lower; dense structural projects score higher. It's real arithmetic on your files — you can audit every number.
 
 ---
 
-## Clean uninstall
+## What engramx is not
 
-One command:
+The "engram" name is contested. To save you a search:
 
-```bash
-npm uninstall -g engramx     # 3.0.1+ auto-runs preuninstall hook-cleanup
-```
+- **Not Go-Engram** ([Gentleman-Programming/engram](https://github.com/Gentleman-Programming/engram)) — different project, Go binary, salience-gated chat memory. Ships under `engram` (without the `x`).
+- **Not DeepSeek's "Engram" paper** — January 2026 academic work on conditional memory. Research artifact, not a product.
+- **Not MemPalace** — adjacent positioning ("knowledge-graph memory," "method-of-loci"), but conversational memory, not code-structural.
 
-If you installed 3.0.0 and ran `npm uninstall` before the 3.0.1 patch shipped, your Claude Code hooks may be orphaned. Run `engram repair-hooks --scope user` (install 3.0.1 first) or see the [`CHANGELOG.md`](CHANGELOG.md#301--2026-04-24--clean-uninstall) for the manual `jq`-based recovery one-liner.
+`engramx` is specifically: **a local-first context spine for AI coding agents that hooks into your IDE's tool boundary, indexes your code via tree-sitter + LSP, remembers past mistakes, and assembles ~500-token context packets in place of raw file reads.** Open source, Apache 2.0, single npm install.
 
 ---
 
@@ -368,6 +305,18 @@ External providers cache into SQLite at SessionStart. Per-read resolution is a c
 
 ---
 
+## Install
+
+```bash
+npm install -g engramx
+```
+
+Requires Node.js 20+. Zero native dependencies. No build tools. Local SQLite via sql.js WASM — no Rust, no Python, no system libs.
+
+> **Prefer a designed walkthrough?** Open [**docs/install.html**](docs/install.html) — three-step install, benefits matrix, IDE coverage, FAQ. Local file, opens in any browser. Brand-matched terminal-mono aesthetic.
+
+---
+
 ## Quickstart
 
 **One command, zero friction:**
@@ -431,14 +380,19 @@ engram hooks install             # auto-rebuild graph on every git commit
 
 ## IDE Integrations
 
+`engram setup` auto-detects every supported IDE on your machine and prints the right next-step for each. You don't have to remember which command to run — the detector knows.
+
 | IDE | Integration | Setup |
 |-----|------------|-------|
-| **Claude Code** | Hook-based interception (native, automatic) | `engram install-hook` |
-| **Cursor** | MDC snapshot + native MCP | `engram gen-mdc` &middot; [docs/integrations/cursor-mcp.md](docs/integrations/cursor-mcp.md) |
-| **Continue.dev** | `@engram` context provider | [docs/integrations/continue.md](docs/integrations/continue.md) |
-| **Zed** | Context server (`/engram`) | `engram context-server` |
-| **Aider** | Context file generation | `engram gen-aider` |
+| **Claude Code** | Hook-based interception (native, automatic) — **plus** `/plugin install engram` for slash-commands | `engram install-hook` &middot; [docs/integrations/claude-code.md](docs/integrations/claude-code.md) |
+| **Cursor** | MDC snapshot + native MCP + VS Code extension on OpenVSX | `engram gen-mdc` &middot; [docs/integrations/cursor-mcp.md](docs/integrations/cursor-mcp.md) |
+| **Cline** | MCP server (5M+ VS Code installs, no native answer to token burn) | [docs/integrations/cline.md](docs/integrations/cline.md) |
+| **Continue.dev** | `@engram` context provider via [`engramx-continue`](https://www.npmjs.com/package/engramx-continue) | [docs/integrations/continue.md](docs/integrations/continue.md) |
+| **Aider** | Context file generation | `engram gen-aider` &middot; [docs/integrations/aider.md](docs/integrations/aider.md) |
 | **Windsurf** (Codeium) | `.windsurfrules` snapshot + MCP | `engram gen-windsurfrules` |
+| **Zed** | Context server (`/engram`) | `engram context-server` &middot; [docs/integrations/zed.md](docs/integrations/zed.md) |
+| **OpenAI Codex CLI** | `AGENTS.md` auto-emit (universal Linux Foundation standard) | `engram gen` (default emits both `AGENTS.md` + `CLAUDE.md`) |
+| **VS Code (any agent)** | Status-bar entry + 6 commands wrapping the CLI | `code --install-extension engram-vscode` (OpenVSX) |
 | **Neovim** | MCP via codecompanion / avante | [docs/integrations/neovim.md](docs/integrations/neovim.md) |
 | **Emacs** | MCP via gptel-mcp | [docs/integrations/emacs.md](docs/integrations/emacs.md) |
 
@@ -448,17 +402,40 @@ Per-IDE setup guides are in [`docs/integrations/`](docs/integrations/).
 
 ## How It Compares
 
+The "context spine" slot — local-first, code-aware, works in any MCP runtime, with a reproducible benchmark — is currently unowned. Here's the field as of May 2026:
+
+|  | **engramx** | Cursor index | Aider repo map | Cline | Continue.dev | Mem0 | claude-mem | CartoGopher |
+|---|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
+| Works in any MCP runtime | ✅ | IDE-locked | Aider only | VS Code only | VS Code only | ✅ | Claude Code only | ✅ |
+| Local-first (nothing leaves machine) | ✅ | cloud-synced | ✅ | ✅ | ✅ | optional | ✅ | ✅ |
+| Code-aware AST graph | ✅ | proprietary | ✅ | — | — | — | — | ✅ |
+| Reproducible benchmark | ✅ **89.1%** | — | — | — | — | — | — | claims 88% |
+| Bi-temporal mistake memory | ✅ | — | — | — | — | — | partial | — |
+| `AGENTS.md` + `CLAUDE.md` dual-emit | ✅ | — | — | — | — | — | — | — |
+| Single npm install | ✅ | full IDE | pip | VS Code ext | VS Code ext | pip / npm | claude plugin | Go binary |
+| License | Apache 2.0 | proprietary | Apache 2.0 | Apache 2.0 | Apache 2.0 | Apache 2.0 | MIT | unknown |
+| GitHub stars (May 2026) | 108 | proprietary | 39K | 61.2K | 32.4K | 47.8K | new | unknown |
+
+The matrix isn't a slight at any of them — most do something engram doesn't. Cursor's index is great inside Cursor. Aider's repo map is great in Aider. Cline's full-file rewrite model is honest about what it is. The point is that nobody else covers all eight rows. Engram is the only tool that does.
+
+For the legacy comparison vs `Continue @RepoMap` / `Cursor .cursorrules` / `@199-bio/engram` (small repo-map approaches), see the matrix below.
+
+<details>
+<summary><strong>Legacy detailed comparison</strong></summary>
+
 | | engram | Continue @RepoMap | Cursor .cursorrules | Aider repo-map | @199-bio/engram |
 |---|---|---|---|---|---|
 | **Interception model** | Hook-based, automatic on every Read | Fetched at @-mention time | Static file, manual | Per-session map | MCP server, called explicitly |
 | **Cache strategy** | SQLite at SessionStart, <5ms per read | No cache — live fetch | No cache | Per-session only | No cache |
 | **Persistent memory** | Decisions, mistakes, patterns across sessions | No | Manual text file | No | No |
-| **Multiple providers** | 8 (AST, git, mistakes, MemPalace, Context7, Obsidian, LSP) | Repo structure only | No | Repo structure only | Graph query only |
+| **Multiple providers** | 9 (AST, git, mistakes, MemPalace, Context7, Obsidian, LSP, Anthropic Memory, MCP plugins) | Repo structure only | No | Repo structure only | Graph query only |
 | **Mistake tracking** | LSP diagnostics → mistake nodes, ⚠️ on Edit | No | No | No | No |
 | **Survives compaction** | Yes (PreCompact hook) | No | Yes (static file) | No | No |
 | **LLM cost** | $0 | $0 | $0 | $0 | $0 |
 | **Native deps** | Zero | No | No | No | No |
 
+</details>
+
 ---
 
 ## Install + Configuration

package/dist/cli.js

@@ -3281,7 +3281,7 @@ program.command("setup").description("Zero-friction first-run wizard (init + ins
   "local"
 ).action(
   async (opts) => {
-    const { runSetup } = await import("./wizard-UH27IO4I.js");
+    const { runSetup } = await import("./wizard-WGBAIZLF.js");
     const scope = opts.scope === "local" || opts.scope === "project" || opts.scope === "user" ? opts.scope : "local";
     const result = await runSetup({
       projectPath: opts.project,

package/dist/{wizard-UH27IO4I.js → wizard-WGBAIZLF.js}

@@ -99,13 +99,66 @@ function detectAider(projectRoot) {
     status: !installed ? "not detected" : configured ? ".aider-context.md present" : "detected \u2014 run `engram gen-aider`"
   };
 }
+function detectCline() {
+  const candidates = [
+    join(homedir(), "Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev"),
+    join(homedir(), ".config/Code/User/globalStorage/saoudrizwan.claude-dev"),
+    join(homedir(), "AppData/Roaming/Code/User/globalStorage/saoudrizwan.claude-dev")
+  ];
+  const installed = candidates.some(existsSync);
+  let configured = false;
+  if (installed) {
+    try {
+      configured = candidates.filter(existsSync).some((p) => {
+        const settings = join(p, "settings", "cline_mcp_settings.json");
+        return existsSync(settings) && readFileSync(settings, "utf-8").includes("engram");
+      });
+    } catch {
+      configured = false;
+    }
+  }
+  return {
+    name: "Cline",
+    installed,
+    configured,
+    status: !installed ? "not detected" : configured ? "engram MCP server registered" : "detected \u2014 add engram-serve to cline_mcp_settings.json"
+  };
+}
+function detectZed(projectRoot) {
+  const candidates = [
+    join(homedir(), ".config/zed"),
+    join(homedir(), "Library/Application Support/Zed"),
+    join(homedir(), "AppData/Roaming/Zed")
+  ];
+  const installed = candidates.some(existsSync);
+  const configured = existsSync(join(projectRoot, ".zed", "settings.json"));
+  return {
+    name: "Zed",
+    installed,
+    configured,
+    status: !installed ? "not detected" : configured ? "Zed project settings present" : "detected \u2014 add engram context server"
+  };
+}
+function detectCodex(projectRoot) {
+  const installed = existsSync(join(homedir(), ".codex"));
+  const configured = existsSync(join(projectRoot, "AGENTS.md"));
+  return {
+    name: "Codex CLI",
+    installed,
+    configured,
+    status: !installed ? "not detected" : configured ? "AGENTS.md present" : "detected \u2014 run `engram gen` to create AGENTS.md"
+  };
+}
 function detectAllIdes(projectRoot) {
   return [
     detectClaudeCode(projectRoot),
     detectCursor(projectRoot),
-    detectWindsurf(projectRoot),
+    detectCline(),
     detectContinue(),
-    detectAider(projectRoot)
+    detectWindsurf(projectRoot),
+    detectAider(projectRoot),
+    detectZed(projectRoot),
+    detectCodex(projectRoot)
   ];
 }
 
@@ -214,7 +267,11 @@ async function offerIdeAdapters(opts, rl) {
   const suggest = {
     Cursor: "engram gen-mdc",
     Windsurf: "engram gen-windsurfrules",
-    Aider: "engram gen-aider"
+    Aider: "engram gen-aider",
+    "Codex CLI": "engram gen --target agents",
+    Cline: "Add to cline_mcp_settings.json: { engram: { command: 'engram-serve', args: ['" + root + "'] } }",
+    "Continue.dev": "Add to ~/.continue/config.json: { contextProviders: [{ name: 'engramx-continue' }] }",
+    Zed: "Register engram-serve as a Zed context server (see Docs/integrations/zed.md)"
   };
   const suggested = [];
   for (const ide of unconfigured) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "engramx",
-  "version": "3.3.0",
+  "version": "3.4.0",
   "mcpName": "io.github.NickCirv/engram",
   "description": "The context spine for AI coding agents. 9 built-in providers + mcpConfig plugin contract (wrap any MCP server in 10 lines), generic MCP-client aggregator (stdio), pre-mortem mistake-guard, bi-temporal mistake memory, Anthropic Auto-Memory bridge, SSE streaming context packets, dual-emit AGENTS.md+CLAUDE.md. 90.8% measured real-world token savings (reproducible bench included). Local SQLite, zero cloud.",
   "repository": {