vexp-cli 2.7.0 → 3.1.0

package/dist/agent-config.js

@@ -10,7 +10,7 @@ import * as fs from "fs";
 import * as path from "path";
 import * as os from "os";
 import * as crypto from "crypto";
-import { VEXP_GUARD_HOOK, VEXP_OPENCODE_GUARD, VEXP_CURSOR_GUARD, vexpHintHookScript, vexpSearchHookScript, vexpHintHookCmdScript, vexpStopGateHookScript, vexpSessionContextHookScript, vexpOpencodeHintPlugin } from "./hook-template.js";
+import { VEXP_GUARD_HOOK, VEXP_OPENCODE_GUARD, VEXP_CURSOR_GUARD, vexpHintHookScript, vexpSearchHookScript, vexpHintHookCmdScript, vexpStopGateHookScript, vexpSessionContextHookScript, vexpOpencodeHintPlugin, vexpOpencodeCompressPlugin, bakeEditHintHook, bakeReadHintHook, bakeBashCapHook } from "./hook-template.js";
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -102,6 +102,13 @@ export function setGuardMode(mode) {
 export function guardMode() {
     return activeGuardMode;
 }
+let activeInterventionMode = "off";
+export function setInterventionMode(mode) {
+    activeInterventionMode = mode;
+}
+export function interventionMode() {
+    return activeInterventionMode;
+}
 // ---------------------------------------------------------------------------
 // Agent detectors - mirrors VS Code extension's AGENT_DETECTORS
 // ---------------------------------------------------------------------------
@@ -116,14 +123,16 @@ const AGENT_DETECTORS = [
     {
         agent: "Cursor",
         detectPath: ".cursor",
-        configFile: ".cursor/rules",
+        // Cursor reads a DIRECTORY of rules here (`.cursor/rules/*.mdc`); the
+        // file inside is ours. See `cursorRulesTarget` for the one exception.
+        configFile: ".cursor/rules/vexp.mdc",
         templateName: "cursor",
         mcpConfigFile: ".cursor/mcp.json",
     },
     {
         agent: "Windsurf",
         detectPath: ".windsurf",
-        configFile: ".windsurf/rules.md",
+        configFile: ".windsurf/rules/vexp.md",
         templateName: "windsurf",
         mcpConfigFile: ".windsurf/mcp.json",
     },
@@ -244,7 +253,7 @@ const AGENT_DETECTORS = [
  * true but badly incomplete story. Kept next to the installers, with a
  * lockstep test asserting every detector has an entry.
  */
-export function plannedWrites(agent, guard = guardMode()) {
+export function plannedWrites(agent, guard = guardMode(), interventions = interventionMode()) {
     const det = AGENT_DETECTORS.find((d) => d.agent === agent);
     if (!det)
         return [];
@@ -255,8 +264,11 @@ export function plannedWrites(agent, guard = guardMode()) {
         case "Claude Code":
             out.push("~/.claude.json  (MCP server entry, user scope)");
             out.push(".claude/hooks/vexp-hint.sh + settings.json hooks.UserPromptSubmit  (orientation)");
-            out.push(".claude/hooks/vexp-verify.sh + settings.json hooks.Stop  (verification gate)");
             out.push(".claude/hooks/vexp-restore.sh + settings.json hooks.SessionStart  (context restore)");
+            if (interventions === "on") {
+                out.push(".claude/hooks/vexp-verify.sh + settings.json hooks.Stop  (verification gate, opt-in)");
+                out.push(".claude/hooks/vexp-edit-hint.sh + settings.json hooks.PostToolUse  (coupling, opt-in)");
+            }
             if (guard === "strict") {
                 out.push(".claude/hooks/vexp-guard.sh + settings.json hooks.PreToolUse  (guard, opt-in)");
             }
@@ -331,9 +343,18 @@ export function configureAgents(workspaceRoot, binaryPath, version, agentFilter,
         const filter = agentFilter.map((a) => a.toLowerCase());
         agents = agents.filter((d) => filter.includes(d.agent.toLowerCase()));
     }
-    for (const detector of agents) {
+    for (const detected of agents) {
+        const detector = withCursorTarget(detected, workspaceRoot);
         const configFilePath = path.join(workspaceRoot, detector.configFile);
         const alreadyExists = fs.existsSync(configFilePath);
+        // Sweep the location we used to write to. For several releases the
+        // Windsurf rules went to `.windsurf/rules.md`, which Cascade does not
+        // read: its rules are `.windsurf/rules/*.md`, `.devin/rules/*.md`, or the
+        // legacy root `.windsurfrules`. Upgrading users would otherwise keep a
+        // stale, unread copy of our instructions beside the live one.
+        if (detector.agent === "Windsurf") {
+            removeVexpSection(path.join(workspaceRoot, ".windsurf", "rules.md"));
+        }
         const content = generateAgentConfig(detector.templateName, {
             workspaceRoot,
             binaryPath,
@@ -404,6 +425,15 @@ export function configureAgents(workspaceRoot, binaryPath, version, agentFilter,
             // 2.3 A2 opt-in applies to DENY hooks, this one cannot block).
             const hintResult = installClaudeCodeHintHook(workspaceRoot, binaryPath);
             installClaudeCodeSearchHook(workspaceRoot, binaryPath);
+            // Both doors. Bounding either alone measured as no change at all: the
+            // work simply moves to the other one.
+            if (interventionMode() === "on") {
+                installClaudeCodeReadHint(workspaceRoot, binaryPath);
+                installClaudeCodeBashCap(workspaceRoot, binaryPath);
+            }
+            else {
+                removeClaudeCodePreToolHooks(workspaceRoot);
+            }
             installClaudeCodeStopGate(workspaceRoot, binaryPath);
             installClaudeCodeSessionContext(workspaceRoot, binaryPath);
             if (hintResult) {
@@ -473,6 +503,7 @@ export function configureAgents(workspaceRoot, binaryPath, version, agentFilter,
             if (wrote)
                 mcpConfigs.push(wrote);
             installOpencodeHintPlugin(workspaceRoot, binaryPath, ".kilo/plugin");
+            installOpencodeCompressPlugin(workspaceRoot, binaryPath, ".kilo/plugin");
             // Kilo v7 vendors opencode, so it takes the same guard plugin — the rules
             // markdown alone was demonstrably not enough (a reported session loaded
             // vexp.md, quoted it back, and still read five files by hand).
@@ -526,6 +557,18 @@ export function configureAgents(workspaceRoot, binaryPath, version, agentFilter,
                     action: "removed",
                 });
             }
+            // v5: the coupling on edit. Default-ON and independent of the guard —
+            // it blocks nothing, so there is no reason to make it opt-in.
+            const edit = installCursorEditHint(workspaceRoot, binaryPath);
+            if (edit) {
+                results.push({
+                    agent: "Cursor Edit Hint",
+                    configFile: path.join(".cursor", "hooks", "vexp-edit-hint.sh"),
+                    content: "",
+                    alreadyExists: edit === "updated",
+                    action: edit,
+                });
+            }
         }
         // Cline: rules in .clinerules (generic template, handled by the writer
         // above); MCP registry is machine-global VS Code storage.
@@ -545,6 +588,7 @@ export function configureAgents(workspaceRoot, binaryPath, version, agentFilter,
         if (detector.agent === "Opencode") {
             const wroteMcp = configureOpencodeMcp(workspaceRoot, binaryPath, mcpServerPath);
             installOpencodeHintPlugin(workspaceRoot, binaryPath, ".opencode/plugin");
+            installOpencodeCompressPlugin(workspaceRoot, binaryPath, ".opencode/plugin");
             if (wroteMcp)
                 mcpConfigs.push(wroteMcp);
             if (guardMode() === "strict") {
@@ -648,7 +692,8 @@ export function configureSelectedAgents(workspaceRoot, binaryPath, version, sele
     const results = [];
     const mcpConfigs = [];
     const writtenConfigFiles = new Set();
-    for (const detector of AGENT_DETECTORS) {
+    for (const detected of AGENT_DETECTORS) {
+        const detector = withCursorTarget(detected, workspaceRoot);
         if (!selectedAgentNames.includes(detector.agent))
             continue;
         // Create agent directory if it doesn't exist. Skip for file-based
@@ -674,6 +719,11 @@ export function configureSelectedAgents(workspaceRoot, binaryPath, version, sele
                 fs.mkdirSync(mcpDir, { recursive: true });
             }
         }
+        // Same sweep as the other writer: the Windsurf rules moved out of
+        // `.windsurf/rules.md`, which Cascade never read.
+        if (detector.agent === "Windsurf") {
+            removeVexpSection(path.join(workspaceRoot, ".windsurf", "rules.md"));
+        }
         const alreadyExists = fs.existsSync(configFilePath);
         const content = generateAgentConfig(detector.templateName, {
             workspaceRoot,
@@ -721,6 +771,13 @@ export function configureSelectedAgents(workspaceRoot, binaryPath, version, sele
             if (wrote)
                 mcpConfigs.push("~/.claude.json");
             installClaudeCodeHintHook(workspaceRoot, binaryPath);
+            if (interventionMode() === "on") {
+                installClaudeCodeReadHint(workspaceRoot, binaryPath);
+                installClaudeCodeBashCap(workspaceRoot, binaryPath);
+            }
+            else {
+                removeClaudeCodePreToolHooks(workspaceRoot);
+            }
             installClaudeCodeStopGate(workspaceRoot, binaryPath);
             installClaudeCodeSessionContext(workspaceRoot, binaryPath);
             if (guardMode() === "strict")
@@ -761,12 +818,17 @@ export function configureSelectedAgents(workspaceRoot, binaryPath, version, sele
             if (wrote)
                 mcpConfigs.push(wrote);
             installOpencodeHintPlugin(workspaceRoot, binaryPath, ".opencode/plugin");
+            installOpencodeCompressPlugin(workspaceRoot, binaryPath, ".opencode/plugin");
             if (guardMode() === "strict")
                 installOpencodePlugin(workspaceRoot);
             else
                 uninstallOpencodePlugin(workspaceRoot);
         }
         if (detector.agent === "Cursor") {
+            if (interventionMode() === "on") {
+                installCursorReadHint(workspaceRoot, binaryPath);
+                installCursorBashCap(workspaceRoot, binaryPath);
+            }
             if (guardMode() === "strict")
                 installCursorHook(workspaceRoot);
             else
@@ -781,6 +843,7 @@ export function configureSelectedAgents(workspaceRoot, binaryPath, version, sele
             if (wrote)
                 mcpConfigs.push(wrote);
             installOpencodeHintPlugin(workspaceRoot, binaryPath, ".kilo/plugin");
+            installOpencodeCompressPlugin(workspaceRoot, binaryPath, ".kilo/plugin");
             if (guardMode() === "strict")
                 installKiloPlugin(workspaceRoot);
             else
@@ -907,6 +970,70 @@ export function readJsonConfigSafe(filePath) {
  *   {command: {path, args}}                         Zed
  *   {command: ["node", "…/mcp-server.cjs"]}         Kilo Code
  */
+/**
+ * The interpreter to write into an editor's MCP config for `mcp-server.cjs`.
+ *
+ * A bare `node` is resolved through the PATH of the process that spawns the
+ * server — and a VS Code / Cursor / Windsurf launched from the Dock, the Start
+ * menu or a desktop shortcut carries the login PATH, which on most developer
+ * machines has no nvm, Volta or Homebrew node in it. The server then dies with
+ * `spawn node ENOENT`, the editor lists no vexp tools, and nothing on our side
+ * logged anything (GitHub Copilot field report, 2026-08). Pin the node that is
+ * running us instead; the VS Code extension has done the same
+ * (`resolveNodePath`) since 2.x. Same search order, bare `node` as last resort.
+ */
+export function resolveNodeCommand() {
+    const execPath = process.execPath;
+    if (execPath && !/Code|Electron/i.test(execPath)) {
+        try {
+            fs.accessSync(execPath, fs.constants.X_OK);
+            return execPath;
+        }
+        catch { /* not executable */ }
+    }
+    if (process.platform !== "win32" && fs.existsSync("/usr/local/bin/node"))
+        return "/usr/local/bin/node";
+    const home = os.homedir();
+    const nvmDir = path.join(home, ".nvm", "versions", "node");
+    if (fs.existsSync(nvmDir)) {
+        try {
+            const versions = fs.readdirSync(nvmDir).filter((d) => d.startsWith("v")).sort().reverse();
+            for (const v of versions) {
+                const candidate = path.join(nvmDir, v, "bin", "node");
+                if (fs.existsSync(candidate))
+                    return candidate;
+            }
+        }
+        catch { /* ignore */ }
+    }
+    return "node";
+}
+/**
+ * An entry whose interpreter is a bare name (`node`, `node.exe`) rather than a
+ * path. Such an entry may well work from a terminal and still fail inside a
+ * GUI editor, so it is never adopted as "already working" — the writer replaces
+ * it with the pinned interpreter on the next setup.
+ */
+export function isBareInterpreter(entry) {
+    if (!entry || typeof entry !== "object")
+        return false;
+    const e = entry;
+    let command = e.command;
+    if (Array.isArray(command))
+        command = command[0];
+    else if (command !== null && typeof command === "object")
+        command = command.path;
+    return typeof command === "string" && command.length > 0 && !/[\\/]/.test(command);
+}
+/**
+ * Adopt a foreign entry only when it resolves AND pins its interpreter. Used by
+ * the GUI-editor writers (VS Code/Copilot, Cursor/Windsurf/Kiro/Trae, Zed),
+ * where a bare `node` is exactly the entry that fails; terminal agents
+ * (opencode, Claude Code) keep adopting a bare interpreter — it works there.
+ */
+function adoptableEntry(entry) {
+    return vexpEntryStillResolves(entry) && !isBareInterpreter(entry);
+}
 function vexpEntryStillResolves(entry) {
     if (!entry || typeof entry !== "object")
         return false;
@@ -1010,13 +1137,110 @@ function warnUnparseable(filePath) {
     }
     process.stderr.write(`  [!] ${filePath} could not be parsed - leaving it untouched. Fix the file or add vexp manually, then re-run setup.\n`);
 }
-function appendOrCreate(filePath, content, version) {
+/**
+ * Remove a vexp section from a file we no longer write to, and delete the file
+ * when nothing of the user's is left in it.
+ *
+ * Needed because vexp wrote its Windsurf rules to `.windsurf/rules.md` for
+ * several releases. Cascade reads `.windsurf/rules/*.md` (a directory),
+ * `.devin/rules/*.md`, or the legacy root `.windsurfrules` — never that path.
+ * Leaving the old file behind would put a stale, unread copy of our
+ * instructions next to the live one.
+ */
+export function removeVexpSection(filePath) {
+    if (!fs.existsSync(filePath))
+        return "absent";
+    let existing;
+    try {
+        existing = fs.readFileSync(filePath, "utf-8");
+    }
+    catch {
+        return "absent";
+    }
+    const marker = existing.match(VEXP_MARKER_RE);
+    const endIdx = existing.indexOf(VEXP_MARKER_END);
+    if (!marker || endIdx === -1)
+        return "absent";
+    const markerIdx = existing.indexOf(marker[0]);
+    let startIdx = markerIdx;
+    while (startIdx > 0 && existing[startIdx - 1] !== "\n")
+        startIdx--;
+    const rest = (existing.slice(0, startIdx) + existing.slice(endIdx + VEXP_MARKER_END.length)).trim();
+    if (rest === "") {
+        try {
+            fs.unlinkSync(filePath);
+            return "deleted";
+        }
+        catch {
+            return "absent";
+        }
+    }
+    try {
+        fs.writeFileSync(filePath, rest + "\n", "utf-8");
+        return "stripped";
+    }
+    catch {
+        return "absent";
+    }
+}
+/**
+ * Where the Cursor rule goes, after clearing the way.
+ *
+ * Cursor reads `.cursor/rules/` as a directory of `.mdc` rules. vexp wrote a
+ * single FILE at `.cursor/rules` for several releases — read by nothing, and
+ * a file where Cursor wants a folder, so Cursor could not create its own
+ * rules either. On a project where the folder already existed, `vexp setup`
+ * then crashed with EISDIR reading the directory (field report, Windows /
+ * Cursor, 2026-08) after indexing and the MCP start had already succeeded.
+ *
+ * Our stale file is removed when it holds only our section. If a user put
+ * their own text in a `.cursor/rules` FILE we keep it and fall back to the
+ * legacy root `.cursorrules`, which Cursor still reads — the folder cannot
+ * exist while that file does.
+ */
+export function cursorRulesTarget(workspaceRoot) {
+    const legacy = path.join(workspaceRoot, ".cursor", "rules");
+    let isFile = false;
+    try {
+        isFile = fs.statSync(legacy).isFile();
+    }
+    catch {
+        /* absent, or a directory */
+    }
+    if (isFile) {
+        removeVexpSection(legacy);
+        if (fs.existsSync(legacy))
+            return ".cursorrules";
+    }
+    return path.join(".cursor", "rules", "vexp.mdc");
+}
+/** The detector with its Cursor target resolved for THIS workspace. */
+function withCursorTarget(d, workspaceRoot) {
+    return d.agent === "Cursor" ? { ...d, configFile: cursorRulesTarget(workspaceRoot) } : d;
+}
+export function appendOrCreate(filePath, content, version) {
+    // A directory where a file was expected. Reading it is EISDIR, and that
+    // aborted the whole setup once (the `.cursor/rules` folder above). The
+    // detectors no longer point at folders; if one ever does again, write a
+    // file inside it rather than crash on the user's machine.
+    if (fs.existsSync(filePath) && fs.statSync(filePath).isDirectory()) {
+        filePath = path.join(filePath, "vexp.md");
+    }
     if (!fs.existsSync(filePath)) {
         fs.mkdirSync(path.dirname(filePath), { recursive: true });
         fs.writeFileSync(filePath, content, "utf-8");
         return "created";
     }
-    const existing = fs.readFileSync(filePath, "utf-8");
+    let existing = fs.readFileSync(filePath, "utf-8");
+    // Front matter has to stay the FIRST thing in the file, and the splice below
+    // preserves whatever sits above our marker — so a rewrite would leave the
+    // old block above and insert a second one. One rule file, one front matter.
+    if (content.startsWith("---\n")) {
+        const lead = existing.match(/^---\n[\s\S]*?\n---\n/);
+        if (lead) {
+            existing = existing.slice(lead[0].length).replace(/^\s*\n/, "");
+        }
+    }
     const markerMatch = existing.match(VEXP_MARKER_RE);
     if (!markerMatch) {
         fs.appendFileSync(filePath, "\n\n" + content);
@@ -1120,7 +1344,7 @@ approveKey = "alwaysAllow") {
     }
     const existing = read.data;
     const useNode = mcpServerPath && fs.existsSync(mcpServerPath);
-    const targetCmd = useNode ? "node" : binaryPath;
+    const targetCmd = useNode ? resolveNodeCommand() : binaryPath;
     const targetArgs = useNode ? [mcpServerPath] : ["mcp"];
     const targetEnv = workspaceRoot ? { VEXP_WORKSPACE: workspaceRoot } : undefined;
     const beforeServers = existing.mcpServers;
@@ -1144,7 +1368,7 @@ approveKey = "alwaysAllow") {
     // Another vexp install already left a working entry here — don't fight it.
     // Only the install path may differ: `envMatches` still gates on the
     // VEXP_WORKSPACE pin, so a moved or renamed project is repinned normally.
-    if (removed.length === 0 && envMatches && vexpEntryStillResolves(previousVexp))
+    if (removed.length === 0 && envMatches && adoptableEntry(previousVexp))
         return false;
     const servers = existing.mcpServers ?? {};
     servers["vexp"] = {
@@ -1290,7 +1514,15 @@ function buildCodexSection(opts) {
     const wsHash = opts.workspaceRoot ? workspaceHash(opts.workspaceRoot) : "";
     const urlPath = wsHash ? `/ws/${wsHash}/mcp` : "/mcp";
     const desiredUrl = `http://127.0.0.1:${opts.mcpPort}${urlPath}`;
-    return `\n[mcp_servers.vexp]\n${CODEX_MANAGED_MARKER}: http transport (set VEXP_CODEX_TRANSPORT=direct for stdio)\nurl = "${desiredUrl}"\ntool_timeout_sec = 120\n\n[mcp_servers.vexp.http_headers]\nAuthorization = "Bearer ${opts.token}"\n`;
+    return `
+[mcp_servers.vexp]
+${CODEX_MANAGED_MARKER}: http transport (set VEXP_CODEX_TRANSPORT=direct for stdio)
+url = "${desiredUrl}"
+tool_timeout_sec = 120
+
+[mcp_servers.vexp.http_headers]
+Authorization = "Bearer ${opts.token}"
+`;
 }
 /**
  * Configure MCP in ~/.codex/config.toml (global).
@@ -1378,7 +1610,7 @@ export function writeVsCodeMcpConfig(p, binaryPath, mcpServerPath, workspaceRoot
     }
     const existing = read.data;
     const useNode = mcpServerPath && fs.existsSync(mcpServerPath);
-    const targetCmd = useNode ? "node" : binaryPath;
+    const targetCmd = useNode ? resolveNodeCommand() : binaryPath;
     const targetArgs = useNode ? [mcpServerPath] : ["mcp"];
     const targetEnv = workspaceRoot ? { VEXP_WORKSPACE: workspaceRoot } : undefined;
     const beforeServers = existing.servers;
@@ -1398,7 +1630,7 @@ export function writeVsCodeMcpConfig(p, binaryPath, mcpServerPath, workspaceRoot
     // Copilot branch, which is gated only on `.github/` existing. Only the
     // install path may differ — `envMatches` still gates on the VEXP_WORKSPACE
     // pin, so a moved or renamed project is repinned normally.
-    if (removed.length === 0 && envMatches && vexpEntryStillResolves(previousVexp))
+    if (removed.length === 0 && envMatches && adoptableEntry(previousVexp))
         return false;
     const servers = existing.servers ?? {};
     servers["vexp"] = {
@@ -1536,7 +1768,7 @@ export function configureOpencodeMcp(workspaceRoot, binaryPath, mcpServerPath) {
     }
     const cfg = read.data;
     const useNode = mcpServerPath && fs.existsSync(mcpServerPath);
-    const command = useNode ? ["node", mcpServerPath] : [binaryPath, "mcp"];
+    const command = useNode ? [resolveNodeCommand(), mcpServerPath] : [binaryPath, "mcp"];
     const env = { VEXP_WORKSPACE: workspaceRoot };
     const mcp = cfg.mcp ?? {};
     const prev = mcp["vexp"];
@@ -1577,7 +1809,7 @@ export function configureKiloMcp(workspaceRoot, binaryPath, mcpServerPath) {
     }
     const cfg = read.data;
     const useNode = mcpServerPath && fs.existsSync(mcpServerPath);
-    const command = useNode ? ["node", mcpServerPath] : [binaryPath, "mcp"];
+    const command = useNode ? [resolveNodeCommand(), mcpServerPath] : [binaryPath, "mcp"];
     const env = { VEXP_WORKSPACE: workspaceRoot };
     const mcp = cfg.mcp ?? {};
     const prev = mcp["vexp"];
@@ -1611,7 +1843,7 @@ export function writeZedMcpConfig(p, binaryPath, mcpServerPath, workspaceRoot) {
     }
     const settings = read.data;
     const useNode = mcpServerPath && fs.existsSync(mcpServerPath);
-    const targetCmd = useNode ? "node" : binaryPath;
+    const targetCmd = useNode ? resolveNodeCommand() : binaryPath;
     const targetArgs = useNode ? [mcpServerPath] : ["mcp"];
     const targetEnv = workspaceRoot ? { VEXP_WORKSPACE: workspaceRoot } : undefined;
     const beforeCs = settings.context_servers;
@@ -1630,7 +1862,7 @@ export function writeZedMcpConfig(p, binaryPath, mcpServerPath, workspaceRoot) {
     // Another vexp install already left a working entry here — don't fight it.
     // Only the install path may differ: `envMatches` still gates on the
     // VEXP_WORKSPACE pin, so a moved or renamed project is repinned normally.
-    if (removed.length === 0 && envMatches && vexpEntryStillResolves(previousVexp))
+    if (removed.length === 0 && envMatches && adoptableEntry(previousVexp))
         return false;
     const cs = settings.context_servers ?? {};
     cs["vexp"] = {
@@ -1673,7 +1905,7 @@ export function configureClaudeCodeGlobal(binaryPath, mcpServerPath, workspaceRo
     const beforeServers = config.mcpServers;
     const existing = beforeServers?.["vexp"];
     const useNode = mcpServerPath && fs.existsSync(mcpServerPath);
-    const desiredCommand = useNode ? "node" : binaryPath;
+    const desiredCommand = useNode ? resolveNodeCommand() : binaryPath;
     const desiredArgs = useNode ? [mcpServerPath] : ["mcp"];
     // Multi-session fix: do NOT pin VEXP_WORKSPACE on this user-scope entry.
     // Claude Code applies ~/.claude.json mcpServers to EVERY project, so a pinned
@@ -1965,11 +2197,27 @@ export function installClaudeCodeStopGate(workspaceRoot, binaryPath) {
     const hookPath = path.join(hookDir, "vexp-verify.sh");
     const settingsPath = path.join(workspaceRoot, ".claude", "settings.json");
     fs.mkdirSync(hookDir, { recursive: true });
-    const script = vexpStopGateHookScript(binaryPath);
+    // Opt-in since the measurement: the gate bought 15 to 32 extra turns per 13
+    // bench sessions, and they land at the END of a session where the
+    // transcript is heaviest, so one of them costs more than a session's entire
+    // tool output. See InterventionMode above. When off, a previously installed
+    // gate is removed and de-registered so upgrades converge.
+    const gateOn = interventionMode() === "on";
     const existed = fs.existsSync(hookPath);
-    const scriptIdentical = existed && fs.readFileSync(hookPath, "utf8") === script;
-    if (!scriptIdentical) {
-        fs.writeFileSync(hookPath, script, { mode: 0o755 });
+    const script = vexpStopGateHookScript(binaryPath);
+    const scriptIdentical = gateOn && existed && fs.readFileSync(hookPath, "utf8") === script;
+    if (gateOn) {
+        if (!scriptIdentical) {
+            fs.writeFileSync(hookPath, script, { mode: 0o755 });
+        }
+    }
+    else if (existed) {
+        try {
+            fs.unlinkSync(hookPath);
+        }
+        catch {
+            /* a hook we cannot remove is still de-registered below */
+        }
     }
     const read = readJsonConfigSafe(settingsPath);
     if (!read.ok) {
@@ -1981,16 +2229,20 @@ export function installClaudeCodeStopGate(workspaceRoot, binaryPath) {
     const existing = Array.isArray(hooks.Stop) ? hooks.Stop : [];
     const filtered = existing.filter((h) => !isVexpHookEntry(h, "vexp-verify"));
     // Cross-OS shape as everywhere: bash + QUOTED path; timeout in SECONDS.
-    filtered.push({
-        hooks: [
-            {
-                type: "command",
-                command: 'bash "$CLAUDE_PROJECT_DIR/.claude/hooks/vexp-verify.sh"',
-                timeout: 15,
-            },
-        ],
-    });
+    if (gateOn) {
+        filtered.push({
+            hooks: [
+                {
+                    type: "command",
+                    command: 'bash "$CLAUDE_PROJECT_DIR/.claude/hooks/vexp-verify.sh"',
+                    timeout: 15,
+                },
+            ],
+        });
+    }
     const merged = { ...hooks, Stop: filtered };
+    if (filtered.length === 0)
+        delete merged.Stop;
     const settingsIdentical = JSON.stringify(merged) === JSON.stringify(settings.hooks ?? {});
     if (scriptIdentical && settingsIdentical)
         return null;
@@ -2002,6 +2254,10 @@ export function installClaudeCodeStopGate(workspaceRoot, binaryPath) {
     }
     return existed ? "updated" : "created";
 }
+function isVexpEditHintHookEntry(entry) {
+    const cmds = JSON.stringify(entry ?? "");
+    return cmds.includes("vexp-edit-hint");
+}
 function isVexpHintHookEntry(h) {
     if (!h || typeof h !== "object")
         return false;
@@ -2046,6 +2302,99 @@ function isVexpSearchHookEntry(h) {
  * Why a hook rather than a tool: 9 of 227 measured agent sessions called the
  * MCP tools. All 227 called Bash.
  */
+/**
+ * Install one of the compression hooks into Claude Code's PreToolUse.
+ *
+ * Shared because the two are one mechanism seen from two sides. Bounding reads
+ * alone did nothing measurable: Read-tool tokens fell 54% and shell output rose
+ * 39%, and the total sat inside the band between two identical stock runs. An
+ * agent takes what it needs through whichever door is open.
+ */
+/**
+ * Undo the two compression hooks, so a workspace configured by an older
+ * version converges on the next setup instead of quietly keeping a default
+ * that was measured and withdrawn.
+ *
+ * Same contract as the guard's removal: take the files out AND de-register
+ * them. A hook left in settings.json pointing at a script that no longer
+ * exists is worse than either state on its own — Claude Code runs it, it
+ * fails, and every Read or Bash call carries the failure.
+ */
+function removeClaudeCodePreToolHooks(workspaceRoot) {
+    const hookDir = path.join(workspaceRoot, ".claude", "hooks");
+    for (const name of ["read-hint", "bash-cap"]) {
+        const p = path.join(hookDir, `vexp-${name}.sh`);
+        if (fs.existsSync(p)) {
+            try {
+                fs.unlinkSync(p);
+            }
+            catch {
+                /* still de-registered below */
+            }
+        }
+    }
+    const settingsPath = path.join(workspaceRoot, ".claude", "settings.json");
+    const read = readJsonConfigSafe(settingsPath);
+    if (!read.ok || !read.existed)
+        return;
+    const settings = read.data;
+    const hooks = (settings.hooks ?? {});
+    const existing = Array.isArray(hooks.PreToolUse) ? hooks.PreToolUse : [];
+    const filtered = existing.filter((h) => !/vexp-(read-hint|bash-cap)/.test(JSON.stringify(h)));
+    if (filtered.length === existing.length)
+        return;
+    const merged = { ...hooks, PreToolUse: filtered };
+    if (filtered.length === 0)
+        delete merged.PreToolUse;
+    settings.hooks = merged;
+    backupConfig(settingsPath);
+    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf-8");
+}
+function installClaudeCodePreToolHook(workspaceRoot, binaryPath, name, matcher, script) {
+    const hookDir = path.join(workspaceRoot, ".claude", "hooks");
+    const hookPath = path.join(hookDir, `vexp-${name}.sh`);
+    const settingsPath = path.join(workspaceRoot, ".claude", "settings.json");
+    fs.mkdirSync(hookDir, { recursive: true });
+    const existed = fs.existsSync(hookPath);
+    const scriptIdentical = existed && fs.readFileSync(hookPath, "utf-8") === script;
+    if (!scriptIdentical)
+        fs.writeFileSync(hookPath, script, { mode: 0o755 });
+    const read = readJsonConfigSafe(settingsPath);
+    if (!read.ok) {
+        warnUnparseable(settingsPath);
+        return scriptIdentical ? null : existed ? "updated" : "created";
+    }
+    const settings = read.data;
+    const hooks = (settings.hooks ?? {});
+    const existing = Array.isArray(hooks.PreToolUse) ? hooks.PreToolUse : [];
+    const filtered = existing.filter((h) => !JSON.stringify(h).includes(`vexp-${name}`));
+    // Shell form with a quoted path: exec form cannot run a .sh on Windows, and
+    // an unquoted path word-splits on "C:\\Program Files" (c4a0b9e).
+    filtered.push({
+        matcher,
+        hooks: [
+            {
+                type: "command",
+                command: `bash "$CLAUDE_PROJECT_DIR/.claude/hooks/vexp-${name}.sh"`,
+                timeout: 10,
+            },
+        ],
+    });
+    const merged = { ...hooks, PreToolUse: filtered };
+    const settingsIdentical = JSON.stringify(merged) === JSON.stringify(settings.hooks ?? {});
+    if (scriptIdentical && settingsIdentical)
+        return null;
+    settings.hooks = merged;
+    fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf-8");
+    return existed ? "updated" : "created";
+}
+export function installClaudeCodeReadHint(workspaceRoot, binaryPath) {
+    return installClaudeCodePreToolHook(workspaceRoot, binaryPath, "read-hint", "Read", bakeReadHintHook(binaryPath));
+}
+export function installClaudeCodeBashCap(workspaceRoot, binaryPath) {
+    return installClaudeCodePreToolHook(workspaceRoot, binaryPath, "bash-cap", "Bash", bakeBashCapHook(binaryPath));
+}
 export function installClaudeCodeSearchHook(workspaceRoot, binaryPath) {
     const hookDir = path.join(workspaceRoot, ".claude", "hooks");
     const hookPath = path.join(hookDir, "vexp-search.sh");
@@ -2096,6 +2445,34 @@ export function installClaudeCodeHintHook(workspaceRoot, binaryPath) {
     const settingsPath = path.join(workspaceRoot, ".claude", "settings.json");
     const script = vexpHintHookScript(binaryPath);
     fs.mkdirSync(hookDir, { recursive: true });
+    // v5: the edit-time coupling hook, written beside the prompt-time one -
+    // but only when interventions are on. It is one of the two mechanisms that
+    // ask the agent to go do something, and a turn costs 65,521 tokens. See
+    // InterventionMode above for the measurement.
+    const editHookPath = path.join(hookDir, "vexp-edit-hint.sh");
+    const couplingOn = interventionMode() === "on";
+    if (couplingOn) {
+        const editScript = bakeEditHintHook(binaryPath);
+        const editExisted = fs.existsSync(editHookPath);
+        if (!editExisted || fs.readFileSync(editHookPath, "utf-8") !== editScript) {
+            fs.writeFileSync(editHookPath, editScript, { mode: 0o755 });
+        }
+        try {
+            fs.chmodSync(editHookPath, 0o755);
+        }
+        catch {
+            /* Windows has no exec bit; Git Bash runs it anyway. */
+        }
+    }
+    else if (fs.existsSync(editHookPath)) {
+        // Converge an upgraded workspace without asking anyone to clean up.
+        try {
+            fs.unlinkSync(editHookPath);
+        }
+        catch {
+            /* a hook we cannot remove is still de-registered below */
+        }
+    }
     const existed = fs.existsSync(hookPath);
     const scriptIdentical = existed && fs.readFileSync(hookPath, "utf-8") === script;
     if (!scriptIdentical) {
@@ -2123,7 +2500,35 @@ export function installClaudeCodeHintHook(workspaceRoot, binaryPath) {
             },
         ],
     });
-    const merged = { ...hooks, UserPromptSubmit: filtered };
+    // v5: the coupling on the edit that needs it. PostToolUse rather than
+    // PreToolUse because a deny on an edit stops real work, and this must never
+    // block — it adds no turn and no permission decision, only a line the model
+    // reads as a system-reminder.
+    const existingPost = Array.isArray(hooks.PostToolUse)
+        ? hooks.PostToolUse
+        : [];
+    const filteredPost = existingPost.filter((h) => !isVexpEditHintHookEntry(h));
+    if (couplingOn) {
+        filteredPost.push({
+            matcher: "Edit|Write|NotebookEdit",
+            hooks: [
+                {
+                    type: "command",
+                    command: 'bash "$CLAUDE_PROJECT_DIR/.claude/hooks/vexp-edit-hint.sh"',
+                    timeout: 5,
+                },
+            ],
+        });
+    }
+    const merged = {
+        ...hooks,
+        UserPromptSubmit: filtered,
+        PostToolUse: filteredPost,
+    };
+    // An empty array is not "no hook": it leaves a key behind that reads like a
+    // configured-but-broken event. Drop it, as the extension copy does.
+    if (filteredPost.length === 0)
+        delete merged.PostToolUse;
     const settingsIdentical = JSON.stringify(merged) === JSON.stringify(settings.hooks ?? {});
     if (scriptIdentical && settingsIdentical)
         return null;
@@ -2140,6 +2545,21 @@ export function installClaudeCodeHintHook(workspaceRoot, binaryPath) {
  * unlike the deny guard (strict-only), this cannot break a session; it only
  * ever appends an orientation line the daemon judged useful.
  */
+/**
+ * opencode / Kilo compression plugin: both doors, mutating rather than
+ * blocking. Their `tool.execute.before` can rewrite `output.args`, which is
+ * the whole mechanism.
+ */
+export function installOpencodeCompressPlugin(workspaceRoot, binaryPath, pluginDir) {
+    const pluginPath = path.join(workspaceRoot, pluginDir, "vexp-compress.js");
+    const content = vexpOpencodeCompressPlugin(binaryPath);
+    fs.mkdirSync(path.dirname(pluginPath), { recursive: true });
+    const existed = fs.existsSync(pluginPath);
+    if (existed && fs.readFileSync(pluginPath, "utf-8") === content)
+        return null;
+    fs.writeFileSync(pluginPath, content);
+    return existed ? "updated" : "created";
+}
 export function installOpencodeHintPlugin(workspaceRoot, binaryPath, pluginDir) {
     const pluginPath = path.join(workspaceRoot, pluginDir, "vexp-hint.js");
     const content = vexpOpencodeHintPlugin(binaryPath);
@@ -2317,6 +2737,58 @@ export function uninstallOpencodePlugin(workspaceRoot) {
  * `failClosed` is left at its default (false): a crashing guard must let the
  * agent work, not lock it out.
  */
+/**
+ * Register a compression hook with Cursor.
+ *
+ * Cursor's `preToolUse` takes the SAME input as Claude Code's — `tool_name`,
+ * `tool_input` — and answers in a different shape: `permission` plus a
+ * snake_case `updated_input`. The binary emits either on request, so nothing
+ * here has to know the difference beyond passing `--protocol cursor`.
+ *
+ * The binary is registered directly rather than through a shell script: there
+ * is no `$CLAUDE_PROJECT_DIR` to expand here and no bash to assume on Windows.
+ */
+function installCursorCompressionHook(workspaceRoot, binaryPath, sub, matcher) {
+    const cfgPath = path.join(workspaceRoot, ".cursor", "hooks.json");
+    const command = `${binaryPath} ${sub} --protocol cursor`;
+    const read = readJsonConfigSafe(cfgPath);
+    if (!read.ok) {
+        warnUnparseable(cfgPath);
+        return false;
+    }
+    const cfg = read.data;
+    const hooks = cfg.hooks ?? {};
+    const preToolUse = Array.isArray(hooks.preToolUse) ? [...hooks.preToolUse] : [];
+    // Idempotent by SUBCOMMAND, not by exact command: the binary path changes
+    // between installs and must replace its own entry rather than add one.
+    const mine = (e) => !!e &&
+        typeof e === "object" &&
+        typeof e.command === "string" &&
+        (e.command).includes(` ${sub} --protocol cursor`);
+    const entry = { command, matcher };
+    const at = preToolUse.findIndex(mine);
+    if (at >= 0 && JSON.stringify(preToolUse[at]) === JSON.stringify(entry))
+        return false;
+    if (at >= 0)
+        preToolUse[at] = entry;
+    else
+        preToolUse.push(entry);
+    hooks.preToolUse = preToolUse;
+    cfg.hooks = hooks;
+    if (cfg.version === undefined)
+        cfg.version = 1;
+    fs.mkdirSync(path.dirname(cfgPath), { recursive: true });
+    if (read.existed)
+        backupConfig(cfgPath);
+    fs.writeFileSync(cfgPath, JSON.stringify(cfg, null, 2), "utf-8");
+    return true;
+}
+export function installCursorReadHint(workspaceRoot, binaryPath) {
+    return installCursorCompressionHook(workspaceRoot, binaryPath, "read-hint", "Read");
+}
+export function installCursorBashCap(workspaceRoot, binaryPath) {
+    return installCursorCompressionHook(workspaceRoot, binaryPath, "bash-cap", "Bash");
+}
 export function installCursorHook(workspaceRoot) {
     const rel = path.join(".cursor", "hooks", "vexp-guard.js");
     const hookPath = path.join(workspaceRoot, rel);
@@ -2424,6 +2896,58 @@ export function uninstallKiloPlugin(workspaceRoot) {
     }
     return removed;
 }
+/**
+ * v5: the edit-time coupling for Cursor.
+ *
+ * Cursor sees a prompt but cannot inject at prompt time — `beforeSubmitPrompt`
+ * is read-only. Its injectable channel is `postToolUse`, which is exactly
+ * where this signal belongs anyway: the file has just been edited and the
+ * coupling is what the plan is about to miss.
+ *
+ * Same binary, same daemon op, same fail-open contract as the Claude Code
+ * hook. The point of doing both is that a signal only one agent receives is a
+ * feature of that agent, not of the product.
+ */
+export function installCursorEditHint(workspaceRoot, binaryPath) {
+    const dir = path.join(workspaceRoot, ".cursor", "hooks");
+    const scriptPath = path.join(dir, "vexp-edit-hint.sh");
+    const script = bakeEditHintHook(binaryPath);
+    fs.mkdirSync(dir, { recursive: true });
+    const existed = fs.existsSync(scriptPath);
+    if (!existed || fs.readFileSync(scriptPath, "utf-8") !== script) {
+        fs.writeFileSync(scriptPath, script, { mode: 0o755 });
+    }
+    try {
+        fs.chmodSync(scriptPath, 0o755);
+    }
+    catch {
+        /* no exec bit on Windows */
+    }
+    const cfgPath = path.join(workspaceRoot, ".cursor", "hooks.json");
+    const read = readJsonConfigSafe(cfgPath);
+    if (!read.ok) {
+        warnUnparseable(cfgPath);
+        return null;
+    }
+    const cfg = read.data;
+    const hooks = cfg.hooks ?? {};
+    const post = Array.isArray(hooks.postToolUse) ? hooks.postToolUse : [];
+    const filtered = post.filter((e) => {
+        if (!e || typeof e !== "object")
+            return true;
+        const cmd = e.command;
+        return typeof cmd !== "string" || !cmd.includes("vexp-edit-hint");
+    });
+    filtered.push({ command: `bash "${scriptPath}"` });
+    hooks.postToolUse = filtered;
+    const merged = { ...cfg, hooks };
+    if (JSON.stringify(merged) === JSON.stringify(cfg) && existed)
+        return null;
+    if (read.existed)
+        backupConfig(cfgPath);
+    fs.writeFileSync(cfgPath, JSON.stringify(merged, null, 2), "utf-8");
+    return read.existed ? "updated" : "created";
+}
 /** Remove the Cursor guard (2.3 A2 default): delete the hook script and drop
  *  our preToolUse entry from .cursor/hooks.json. */
 export function uninstallCursorHook(workspaceRoot) {
@@ -2472,12 +2996,47 @@ export function uninstallCursorHook(workspaceRoot) {
  * Shared by every prose template so the wording cannot drift again. ASCII only
  * (these land in files that get read on Windows).
  */
-const QUERY_SHAPE = `### Query shape (do this)
-- Anchor the task on real identifiers (ClassName, functionName) or file paths:
-  \`run_pipeline({ "task": "fix JWT expiry in AuthService.validateToken" })\`
-- A pure natural-language question ("why does login fail?") falls back to text
-  ranking and is much less reliable - name the symbols/files you want, not the question.`;
-function generateAgentConfig(template, vars) {
+/**
+ * The standing mandate, and it is deliberately short.
+ *
+ * Whatever this file says is resident in the agent's context on EVERY turn,
+ * while a tool call happens at most once. Measured over 13 full bench
+ * sessions: 37.1 API turns against a transcript averaging 65,521 tokens, so
+ * a line here is billed 37 times and a call is billed once. The templates
+ * this replaces ran 282 tokens (Claude Code) to 959 (generic) - up to 35,000
+ * replayed tokens per session - and most of what they carried was a second
+ * copy of the tool descriptions the MCP schemas already send.
+ *
+ * So this keeps only the three things a schema cannot carry:
+ *
+ *   1. WHEN to call, and when not to - the schema says what a tool returns,
+ *      not whether this task wants it.
+ *   2. The two guardrails that stop wasted calls: text sweeps belong to
+ *      native search, and the index covers repo source only (logs, dist/,
+ *      node_modules are not in it - read those directly).
+ *   3. The privacy line, because users ask and compliance reviews ask.
+ *
+ * Everything else was deleted, not shortened. See the catalog diet in
+ * mcp_stdio.rs for the same argument applied one layer down.
+ */
+const MANDATE_CORE = `### Context strategy: call run_pipeline ONCE at task start
+If the task already names the files/symbols to touch, SKIP vexp. Otherwise one
+\`run_pipeline({ "task": "..." })\` returns ranked pivot files with line ranges and
+blast radius. Do NOT open files one by one to find your way around - every extra
+tool call costs a turn. Call it again ONLY when the task moves to a new area.
+\`get_skeleton\` for files to understand, not edit. \`verify_done\` before calling a
+multi-file task complete, then RUN the tests it names.
+
+### Query shape (do this)
+Anchor the task on real identifiers (ClassName, functionName) or file paths:
+\`run_pipeline({ "task": "fix JWT expiry in AuthService.validateToken" })\`
+
+vexp runs entirely on this machine, index in \`.vexp/\`;
+\`run_pipeline\` transmits nothing to any external service.
+On \`status: "degraded"\` or 0 pivots the index is still building - use your own tools.
+For literal string sweeps use your native search - do NOT route text sweeps through vexp.
+Repo SOURCE only: logs, dist/, node_modules/ and files outside the repo are NOT indexed.`;
+export function generateAgentConfig(template, vars) {
     switch (template) {
         case "claude-code":
             return claudeCodeTemplate(vars);
@@ -2506,469 +3065,82 @@ function generateAgentConfig(template, vars) {
 // ---------------------------------------------------------------------------
 function claudeCodeTemplate(vars) {
     return `## vexp - Context-Aware AI Coding <!-- vexp v${vars.version} -->
-vexp runs entirely on this machine: local daemon, index in \`.vexp/\`.
-\`run_pipeline\` transmits nothing to any external service.
-- \`run_pipeline({ "task": "..." })\` - orientation in one call (ranked pivot
-  files with line ranges + blast radius + session notes) when a task does NOT
-  name the files/symbols to touch. If it does, SKIP vexp - use your normal tools.
-- \`get_skeleton\` - file structure at 70-90% token savings for files you only
-  need to understand, not edit.
-- \`verify_done\` - call once BEFORE declaring a multi-file task complete:
-  returns mechanically broken references (imports of removed names, parse
-  errors), untouched dependents of the files you changed (file:line), and
-  the impacted tests - RUN those tests before declaring done.
-- vexp may append a one-line hint to a prompt when orientation would help;
-  otherwise it stays silent.
 
-### Query shape (do this)
-Anchor the task on real identifiers (ClassName, functionName) or file paths:
-\`run_pipeline({ "task": "fix JWT expiry in AuthService.validateToken" })\`
+${MANDATE_CORE}
 <!-- /vexp -->`;
 }
 function cursorTemplate(vars) {
-    return `## vexp rules for Cursor <!-- vexp v${vars.version} -->
-
-**Call \`run_pipeline\` ONCE at task start for orientation - then use your normal tools.**
-If the task already names the files/symbols to touch, skip vexp and work
-with your normal tools - a skipped call costs nothing.
-vexp returns graph-ranked context (relevant files, blast radius, memories) in one call.
-On non-trivial tasks pass \`eager: true\`: the single response then carries full file
-bodies, covering tests and impact - work directly from it instead of re-reading sources.
-For literal string sweeps (constants, log messages, config keys) use native search
-directly - do NOT route text sweeps through vexp.
-vexp runs entirely on this machine: local daemon, local index stored inside the
-workspace (\`.vexp/\`). \`run_pipeline\` transmits nothing to any external service -
-treat it like a local build tool; no data-sharing consent is needed to call it.
-
-### Workflow
-1. \`run_pipeline\` with your task description - ONCE at task start
-2. Literal text sweeps with native search; Read the files you will edit
-3. Make targeted changes based on the context returned
-4. \`run_pipeline\` again ONLY when the task moves to a new area - not per turn
-
-### Available MCP tools
-- \`run_pipeline\` - **PRIMARY TOOL**. Runs capsule + impact + memory in 1 call.
-  Auto-detects intent. Includes file content. Example: \`run_pipeline({ "task": "fix JWT expiry in AuthService.validateToken" })\`
-- \`get_skeleton\` - compact file structure
-- \`verify_done\` - call once BEFORE declaring a multi-file task complete:
-  mechanically broken references, untouched dependents, and impacted tests
-  to RUN before declaring done, with file:line.
-- \`index_status\` - indexing status
-- \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
-
-(Recommended core set, not the full schema: paid plans advertise 14 MCP tools -
-capsule, impact graph, logic flow, memory and more. \`run_pipeline\` already runs
-those server-side, so the four above cover the normal workflow.)
-
-${QUERY_SHAPE}
-
-### Agentic search
-- Ask vexp first for architecture/impact questions; native search remains the right
-  tool for literal text sweeps
-- If you spawn sub-agents or background tasks, pass them the context from \`run_pipeline\`
-  so they do not re-explore from scratch
-
-### Tips
-- Add \`include_tests: true\` when debugging
-- Use \`preset: "refactor"\` for deep impact analysis
-
-### Fallback
-If \`run_pipeline\` returns 0 pivots with an INDEX EMPTY warning, the index is rebuilding.
-Use file search and read tools directly until the index is ready.
-
-### Multi-Repo
-\`run_pipeline\` auto-queries all indexed repos. Use \`repos: ["alias"]\` to scope. Run \`index_status\` to see aliases.
-
-> **Tip:** To avoid confirmation prompts on every tool call, enable Yolo mode:
-> Cursor Settings -> Features -> Agent -> Enable Yolo Mode.
+    // Cursor project rules are `.cursor/rules/*.mdc` with front matter;
+    // `alwaysApply: true` puts the rule in every chat without the agent having
+    // to pick it. A rule file that Cursor reads at all is new: for several
+    // releases vexp wrote a single FILE at `.cursor/rules`, a path Cursor never
+    // reads, and one that stopped Cursor from creating its rules folder.
+    return `---
+description: vexp code-graph orientation for this workspace
+alwaysApply: true
+---
+
+## vexp rules for Cursor <!-- vexp v${vars.version} -->
+
+${MANDATE_CORE}
 <!-- /vexp -->`;
 }
 function windsurfTemplate(vars) {
-    return `## vexp for Windsurf <!-- vexp v${vars.version} -->
-
-**Call \`run_pipeline\` ONCE at task start for orientation - then use your normal tools.**
-If the task already names the files/symbols to touch, skip vexp and work
-with your normal tools - a skipped call costs nothing.
-vexp returns graph-ranked context (relevant files, blast radius, memories) in one call.
-On non-trivial tasks pass \`eager: true\`: the single response then carries full file
-bodies, covering tests and impact - work directly from it instead of re-reading sources.
-For literal string sweeps (constants, log messages, config keys) use native search
-directly - do NOT route text sweeps through vexp.
-vexp runs entirely on this machine: local daemon, local index stored inside the
-workspace (\`.vexp/\`). \`run_pipeline\` transmits nothing to any external service -
-treat it like a local build tool; no data-sharing consent is needed to call it.
-
-### Workflow
-1. \`run_pipeline\` with your task description - ONCE at task start
-2. Literal text sweeps with native search; Read the files you will edit
-3. Make targeted changes based on the context returned
-4. \`run_pipeline\` again ONLY when the task moves to a new area - not per turn
-
-### Available MCP tools
-- \`run_pipeline\` - **PRIMARY TOOL**. Runs capsule + impact + memory in 1 call.
-  Auto-detects intent. Includes file content. Example: \`run_pipeline({ "task": "fix JWT expiry in AuthService.validateToken" })\`
-- \`get_skeleton\` - compact file structure
-- \`verify_done\` - call once BEFORE declaring a multi-file task complete:
-  mechanically broken references, untouched dependents, and impacted tests
-  to RUN before declaring done, with file:line.
-- \`index_status\` - indexing status
-- \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
-
-(Recommended core set, not the full schema: paid plans advertise 14 MCP tools -
-capsule, impact graph, logic flow, memory and more. \`run_pipeline\` already runs
-those server-side, so the four above cover the normal workflow.)
-
-${QUERY_SHAPE}
-
-### Agentic search
-- Ask vexp first for architecture/impact questions; native search remains the right
-  tool for literal text sweeps
-- If you spawn sub-agents or background tasks, pass them the context from \`run_pipeline\`
-  so they do not re-explore from scratch
-
-### Smart Features
-Intent auto-detection, hybrid ranking, session memory, auto-expanding budget.
-
-### Multi-Repo
-\`run_pipeline\` auto-queries all indexed repos. Use \`repos: ["alias"]\` to scope. Run \`index_status\` to see aliases.
+    // Front matter, because a rule without one is not always on. Cascade puts
+    // the FULL text of an \`always_on\` rule in the system prompt on every
+    // message; the other modes make the agent choose to look, which is the
+    // complaint every Windsurf user brings ("it ignores the index unless I
+    // remind it"). This is the one lever Windsurf gives us and we were not
+    // pulling it.
+    return `---
+trigger: always_on
+description: vexp code-graph orientation for this workspace
+---
+
+## vexp for Windsurf <!-- vexp v${vars.version} -->
+
+${MANDATE_CORE}
 <!-- /vexp -->`;
 }
 function continueTemplate(vars) {
-    return JSON.stringify({
-        customCommands: [
-            {
-                name: "vexp-context",
-                description: "Run vexp pipeline for current task",
-                prompt: "{{{ input }}}\n\nFirst, call run_pipeline with the above task description.",
-            },
-        ],
-        mcpServers: [
-            {
-                name: "vexp",
-                command: vars.binaryPath,
-                args: ["mcp"],
-                type: "stdio",
-            },
-        ],
-    }, null, 2);
+    return `## vexp <!-- vexp v${vars.version} -->
+
+${MANDATE_CORE}
+<!-- /vexp -->`;
 }
 function augmentTemplate(vars) {
-    return `## vexp for Augment <!-- vexp v${vars.version} -->
-
-**Call \`run_pipeline\` ONCE at task start for orientation - then use your normal tools.**
-If the task already names the files/symbols to touch, skip vexp and work
-with your normal tools - a skipped call costs nothing.
-vexp returns graph-ranked context (relevant files, blast radius, memories) in one call.
-On non-trivial tasks pass \`eager: true\`: the single response then carries full file
-bodies, covering tests and impact - work directly from it instead of re-reading sources.
-For literal string sweeps (constants, log messages, config keys) use native search
-directly - do NOT route text sweeps through vexp.
-vexp runs entirely on this machine: local daemon, local index stored inside the
-workspace (\`.vexp/\`). \`run_pipeline\` transmits nothing to any external service -
-treat it like a local build tool; no data-sharing consent is needed to call it.
-
-When working on this codebase:
-1. \`run_pipeline\` with task description - ONCE at task start
-2. Literal text sweeps with native search; Read the files you will edit
-3. Make targeted changes based on the context returned
-4. \`run_pipeline\` again ONLY when the task moves to a new area
-
-### Available MCP tools
-- \`run_pipeline\` - **PRIMARY TOOL**. Runs capsule + impact + memory in 1 call.
-  Example: \`run_pipeline({ "task": "fix JWT expiry in AuthService.validateToken" })\`
-- \`get_skeleton\` - token-efficient file structure
-- \`verify_done\` - call once BEFORE declaring a multi-file task complete:
-  mechanically broken references, untouched dependents, and impacted tests
-  to RUN before declaring done, with file:line.
-- \`index_status\` - indexing status
-- \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
-
-(Recommended core set, not the full schema: paid plans advertise 14 MCP tools -
-capsule, impact graph, logic flow, memory and more. \`run_pipeline\` already runs
-those server-side, so the four above cover the normal workflow.)
-
-${QUERY_SHAPE}
-
-### Agentic search
-- Ask vexp first for architecture/impact questions; native search remains the right
-  tool for literal text sweeps
-- If you spawn sub-agents or background tasks, pass them the context from \`run_pipeline\`
-  so they do not re-explore from scratch
-
-### Smart Features
-Intent auto-detection, hybrid ranking, session memory, auto-expanding budget.
+    return `## vexp <!-- vexp v${vars.version} -->
 
-### Multi-Repo
-\`run_pipeline\` auto-queries all indexed repos. Use \`repos: ["alias"]\` to scope. Run \`index_status\` to see aliases.
+${MANDATE_CORE}
 <!-- /vexp -->`;
 }
 function copilotTemplate(vars) {
-    return `## vexp context tools <!-- vexp v${vars.version} -->
-
-**Call \`run_pipeline\` ONCE at task start for orientation - then use your normal tools.**
-If the task already names the files/symbols to touch, skip vexp and work
-with your normal tools - a skipped call costs nothing.
-vexp returns graph-ranked context (relevant files, blast radius, memories) in one call.
-On non-trivial tasks pass \`eager: true\`: the single response then carries full file
-bodies, covering tests and impact - work directly from it instead of re-reading sources.
-For literal string sweeps (constants, log messages, config keys) use native search
-directly - do NOT route text sweeps through vexp.
-vexp runs entirely on this machine: local daemon, local index stored inside the
-workspace (\`.vexp/\`). \`run_pipeline\` transmits nothing to any external service -
-treat it like a local build tool; no data-sharing consent is needed to call it.
-
-### Workflow
-1. \`run_pipeline\` with your task description - ONCE at task start
-2. Literal text sweeps with native search; Read the files you will edit
-3. Make targeted changes based on the context returned
-4. \`run_pipeline\` again ONLY when the task moves to a new area - not per turn
-
-### Available MCP tools
-- \`run_pipeline\` - **PRIMARY TOOL**. Runs capsule + impact + memory in 1 call.
-  Auto-detects intent. Includes file content. Example: \`run_pipeline({ "task": "fix JWT expiry in AuthService.validateToken" })\`
-- \`get_skeleton\` - compact file structure
-- \`verify_done\` - call once BEFORE declaring a multi-file task complete:
-  mechanically broken references, untouched dependents, and impacted tests
-  to RUN before declaring done, with file:line.
-- \`index_status\` - indexing status
-- \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
-
-(Recommended core set, not the full schema: paid plans advertise 14 MCP tools -
-capsule, impact graph, logic flow, memory and more. \`run_pipeline\` already runs
-those server-side, so the four above cover the normal workflow.)
-
-${QUERY_SHAPE}
-
-### Agentic search
-- Ask vexp first for architecture/impact questions; native search remains the right
-  tool for literal text sweeps
-- If you spawn sub-agents or background tasks, pass them the context from \`run_pipeline\`
-  so they do not re-explore from scratch
-
-### Smart Features
-Intent auto-detection, hybrid ranking, session memory, auto-expanding budget.
+    return `## vexp <!-- vexp v${vars.version} -->
 
-### Multi-Repo
-\`run_pipeline\` auto-queries all indexed repos. Use \`repos: ["alias"]\` to scope. Run \`index_status\` to see aliases.
+${MANDATE_CORE}
 <!-- /vexp -->`;
 }
 function zedTemplate(vars) {
-    return `## vexp for Zed <!-- vexp v${vars.version} -->
-
-**Call \`run_pipeline\` ONCE at task start for orientation - then use your normal tools.**
-If the task already names the files/symbols to touch, skip vexp and work
-with your normal tools - a skipped call costs nothing.
-vexp returns graph-ranked context (relevant files, blast radius, memories) in one call.
-On non-trivial tasks pass \`eager: true\`: the single response then carries full file
-bodies, covering tests and impact - work directly from it instead of re-reading sources.
-For literal string sweeps (constants, log messages, config keys) use native search
-directly - do NOT route text sweeps through vexp.
-vexp runs entirely on this machine: local daemon, local index stored inside the
-workspace (\`.vexp/\`). \`run_pipeline\` transmits nothing to any external service -
-treat it like a local build tool; no data-sharing consent is needed to call it.
-
-### Workflow
-1. \`run_pipeline\` with your task description - ONCE at task start
-2. Literal text sweeps with native search; Read the files you will edit
-3. Make targeted changes based on the context returned
-4. \`run_pipeline\` again ONLY when the task moves to a new area - not per turn
-
-### Available MCP tools
-- \`run_pipeline\` - **PRIMARY TOOL**. Runs capsule + impact + memory in 1 call.
-  Example: \`run_pipeline({ "task": "fix JWT expiry in AuthService.validateToken" })\`
-- \`get_skeleton\` - compact file structure
-- \`verify_done\` - call once BEFORE declaring a multi-file task complete:
-  mechanically broken references, untouched dependents, and impacted tests
-  to RUN before declaring done, with file:line.
-- \`index_status\` - indexing status
-- \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
-
-(Recommended core set, not the full schema: paid plans advertise 14 MCP tools -
-capsule, impact graph, logic flow, memory and more. \`run_pipeline\` already runs
-those server-side, so the four above cover the normal workflow.)
-
-${QUERY_SHAPE}
-
-### Agentic search
-- Ask vexp first for architecture/impact questions; native search remains the right
-  tool for literal text sweeps
-- If you spawn sub-agents or background tasks, pass them the context from \`run_pipeline\`
-  so they do not re-explore from scratch
-
-### Smart Features
-Intent auto-detection, hybrid ranking, session memory, auto-expanding budget.
+    return `## vexp <!-- vexp v${vars.version} -->
 
-### Multi-Repo
-\`run_pipeline\` auto-queries all indexed repos. Use \`repos: ["alias"]\` to scope. Run \`index_status\` to see aliases.
+${MANDATE_CORE}
 <!-- /vexp -->`;
 }
 function agentsMdTemplate(vars) {
-    return `## vexp <!-- vexp v${vars.version} -->
-
-**Call \`run_pipeline\` ONCE at task start for orientation - then use your normal tools.**
-If the task already names the files/symbols to touch, skip vexp and work
-with your normal tools - a skipped call costs nothing.
-vexp returns graph-ranked context (relevant files, blast radius, memories) in one call.
-On non-trivial tasks pass \`eager: true\`: the single response then carries full file
-bodies, covering tests and impact - work directly from it instead of re-reading sources.
-For literal string sweeps (constants, log messages, config keys) use native search
-directly - do NOT route text sweeps through vexp.
-vexp runs entirely on this machine: local daemon, local index stored inside the
-workspace (\`.vexp/\`). \`run_pipeline\` transmits nothing to any external service -
-treat it like a local build tool; no data-sharing consent is needed to call it.
-
-### Workflow
-1. \`run_pipeline\` with your task description - ONCE at task start
-2. Literal text sweeps with native search; Read the files you will edit
-3. Make targeted changes based on the context returned
-4. \`run_pipeline\` again ONLY when the task moves to a new area - not per turn
-
-### Available MCP tools
-- \`run_pipeline\` - **PRIMARY TOOL**. Runs capsule + impact + memory in 1 call.
-  Auto-detects intent. Includes file content. Example: \`run_pipeline({ "task": "fix JWT expiry in AuthService.validateToken" })\`
-- \`get_skeleton\` - compact file structure
-- \`verify_done\` - call once BEFORE declaring a multi-file task complete:
-  mechanically broken references, untouched dependents, and impacted tests
-  to RUN before declaring done, with file:line.
-- \`index_status\` - indexing status
-- \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
-
-${QUERY_SHAPE}
-
-### Agentic search
-- Ask vexp first for architecture/impact questions; native search remains the right
-  tool for literal text sweeps
-- vexp only covers indexed source inside the workspace. For runtime logs, build output
-  (dist/, .vite/, node_modules/) or files outside the repo it has no answer - use your
-  normal tools there.
-- If you spawn sub-agents or background tasks, pass them the context from \`run_pipeline\`
-  so they do not re-explore from scratch
-
-### Smart Features
-Intent auto-detection, hybrid ranking, session memory, auto-expanding budget.
+    return `## vexp - Context-Aware AI Coding <!-- vexp v${vars.version} -->
 
-### Multi-Repo
-\`run_pipeline\` auto-queries all indexed repos. Use \`repos: ["alias"]\` to scope. Run \`index_status\` to see aliases.
+${MANDATE_CORE}
 <!-- /vexp -->`;
 }
 function kiroTemplate(vars) {
     return `# vexp steering <!-- vexp v${vars.version} -->
 
-**Call \`run_pipeline\` ONCE at task start for orientation - then use your normal tools.**
-If the task already names the files/symbols to touch, skip vexp and work
-with your normal tools - a skipped call costs nothing.
-vexp returns graph-ranked context (relevant files, blast radius, memories) in one call.
-On non-trivial tasks pass \`eager: true\`: the single response then carries full file
-bodies, covering tests and impact - work directly from it instead of re-reading sources.
-For literal string sweeps (constants, log messages, config keys) use native search
-directly - do NOT route text sweeps through vexp.
-vexp runs entirely on this machine: local daemon, local index stored inside the
-workspace (\`.vexp/\`). \`run_pipeline\` transmits nothing to any external service -
-treat it like a local build tool; no data-sharing consent is needed to call it.
-
-## Workflow
-1. \`run_pipeline\` with your task description - ONCE at task start
-2. Literal text sweeps with native search; Read the files you will edit
-3. Make targeted changes based on the context returned
-4. \`run_pipeline\` again ONLY when the task moves to a new area - not per turn
-
-## Available vexp tools
-- \`run_pipeline\` - **PRIMARY TOOL**. Runs capsule + impact + memory in 1 call.
-  Example: \`run_pipeline({ "task": "fix JWT expiry in AuthService.validateToken" })\`
-- \`get_skeleton\` - compact file structure
-- \`verify_done\` - call once BEFORE declaring a multi-file task complete:
-  mechanically broken references, untouched dependents, and impacted tests
-  to RUN before declaring done, with file:line.
-- \`index_status\` - indexing status
-- \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
-
-(Recommended core set, not the full schema: paid plans advertise 14 MCP tools -
-capsule, impact graph, logic flow, memory and more. \`run_pipeline\` already runs
-those server-side, so the four above cover the normal workflow.)
-
-${QUERY_SHAPE}
-
-## Agentic search
-- Ask vexp first for architecture/impact questions; native search remains the right
-  tool for literal text sweeps
-- If you spawn sub-agents or background tasks, pass them the context from \`run_pipeline\`
-  so they do not re-explore from scratch
-
-## Smart Features
-Intent auto-detection, hybrid ranking, session memory, auto-expanding budget.
-
-## Multi-Repo
-\`run_pipeline\` auto-queries all indexed repos. Use \`repos: ["alias"]\` to scope. Run \`index_status\` to see aliases.
+${MANDATE_CORE}
 <!-- /vexp -->`;
 }
 function genericTemplate(vars) {
     return `## vexp - Context-Aware AI Coding <!-- vexp v${vars.version} -->
 
-### Context strategy: call run_pipeline ONCE at task start
-If the task already names the files/symbols to touch, skip vexp and work
-with your normal tools - a skipped call costs nothing.
-For every multi-file task - bug fixes, features, refactors, questions about the code:
-**start with one \`run_pipeline\` call**. It runs context search + impact analysis +
-memory recall in a single call and returns compressed, graph-ranked results: the
-callers, the blast radius and the co-changed files that opening a file cannot show.
-
-Then implement with your normal tools:
-- Literal text sweeps (string constants, log messages, config keys): use your
-  native search directly - do NOT route text sweeps through vexp.
-- Read the files you are about to edit; use \`get_skeleton\`
-  (detail: minimal/standard/detailed, 70-90% fewer tokens) for files you only
-  need to understand, not edit.
-- Do NOT open files one by one to find your way around - one good pipeline call
-  beats five exploratory reads; every extra tool call costs a turn.
-- Before declaring a multi-file task complete, call \`verify_done\` once:
-  it returns mechanically broken references (imports of removed names,
-  parse errors), untouched dependents of your changes (file:line), and the
-  impacted tests - RUN those tests before declaring done.
-
-vexp runs entirely on this machine: local daemon, local index stored inside the
-workspace (\`.vexp/\`). \`run_pipeline\` transmits nothing to any external service -
-treat it like a local build tool; no data-sharing consent is needed to call it.
-
-vexp indexes source inside the workspace and nothing else. Runtime logs, build
-output (dist/, .vite/, node_modules/) and files outside the repo are NOT indexed -
-read those directly, this rule does not cover them.
-
-### Primary tool
-- \`run_pipeline\` - **USE THIS FOR EVERYTHING**. Auto-detects intent
-  (debug/modify/refactor/explore) from your task. Includes file content for pivots.
-  - \`run_pipeline({ "task": "fix JWT expiry in AuthService.validateToken" })\`
-  - \`run_pipeline({ "task": "refactor db layer", "preset": "refactor" })\`
-  - \`run_pipeline({ "task": "add auth", "observation": "using JWT" })\` - saves an insight in the same call
-
-### Other MCP tools (only when run_pipeline is not enough)
-- \`get_skeleton\` - **preferred over reading a file**: signatures and structure, 3 detail levels
-- \`index_status\` - indexing status and health check
-- \`expand_vexp_ref\` - expand V-REF hash placeholders in v2 compact output
-
-${QUERY_SHAPE}
-
-### Workflow
-1. \`run_pipeline("your task")\` - ONCE at task start. Returns pivots + impact + memories in 1 call
-2. Literal string sweeps with native search; Read the files you will edit
-3. Structural overview without editing? \`get_skeleton({ files: [...], detail: "detailed" })\`
-4. Make targeted changes based on the context returned
-5. \`run_pipeline\` again ONLY when the task moves to a new area - do NOT chain vexp calls
-
-### Sub-agents and background tasks
-- Sub-agents CAN call \`run_pipeline\` - always give them the task description
-- For architecture exploration, call \`run_pipeline\` first and pass the returned
-  context into the agent prompt - it usually replaces the exploration entirely
-
-### Fallback
-If \`run_pipeline\` returns \`status: "degraded"\` or 0 pivots with an INDEX EMPTY warning,
-the index is empty or still building. Use the built-in search and read tools directly
-until it is ready - do not stall waiting for vexp.
-
-### Smart features (automatic - no action needed)
-Intent detection, hybrid keyword+semantic+graph ranking, session memory,
-change coupling, auto-expanding budget.
-
-### Multi-repo
-\`run_pipeline\` auto-queries all indexed repos. Use \`repos: ["alias"]\` to scope. Run \`index_status\` to see aliases.
+${MANDATE_CORE}
 <!-- /vexp -->`;
 }