vexp-cli 2.2.3 → 2.3.0

package/dist/agent-config.js

@@ -95,6 +95,13 @@ const VEXP_TOOLS = [
     "save_observation",
     "get_token_savings",
 ];
+let activeGuardMode = "off";
+export function setGuardMode(mode) {
+    activeGuardMode = mode;
+}
+export function guardMode() {
+    return activeGuardMode;
+}
 // ---------------------------------------------------------------------------
 // Agent detectors - mirrors VS Code extension's AGENT_DETECTORS
 // ---------------------------------------------------------------------------
@@ -291,8 +298,20 @@ export function configureAgents(workspaceRoot, binaryPath, version, agentFilter,
         // Write MCP config for agents with mcpConfigFile (project-level JSON)
         if (detector.mcpConfigFile) {
             const mcpConfigPath = path.join(workspaceRoot, detector.mcpConfigFile);
-            const alwaysAllow = detector.agent === "Windsurf" ? VEXP_TOOLS : undefined;
-            if (writeMcpConfig(mcpConfigPath, binaryPath, alwaysAllow, mcpServerPath, workspaceRoot)) {
+            const isKiro = detector.agent === "Kiro";
+            // Windsurf and Kiro auto-approve vexp's tools so the agent isn't prompted
+            // on every run_pipeline call. Kiro's field is `autoApprove`; others use
+            // `alwaysAllow`.
+            const alwaysAllow = (detector.agent === "Windsurf" || isKiro) ? VEXP_TOOLS : undefined;
+            const approveKey = isKiro ? "autoApprove" : "alwaysAllow";
+            // Kiro resolves the MCP `command` via PATH, and a macOS GUI launch has no
+            // `node` on PATH — so the `node <mcp-server.cjs>` transport silently fails
+            // to start and run_pipeline never appears (the agent then falls back to
+            // grep/sed). Point Kiro straight at the vexp binary (`vexp-core mcp`, which
+            // reads VEXP_WORKSPACE from env) by withholding mcpServerPath — no `node`
+            // needed, an absolute path that always resolves.
+            const mcpSrv = isKiro ? undefined : mcpServerPath;
+            if (writeMcpConfig(mcpConfigPath, binaryPath, alwaysAllow, mcpSrv, workspaceRoot, approveKey)) {
                 mcpConfigs.push(detector.mcpConfigFile);
             }
         }
@@ -301,15 +320,27 @@ export function configureAgents(workspaceRoot, binaryPath, version, agentFilter,
             const wrote = configureClaudeCodeGlobal(binaryPath, mcpServerPath, workspaceRoot);
             if (wrote)
                 mcpConfigs.push("~/.claude.json");
-            // Install PreToolUse hook: blocks Grep/Glob when vexp daemon is available
-            const hookResult = installClaudeCodeHook(workspaceRoot);
-            if (hookResult) {
+            // Guard is OPT-IN from 2.3 (see GuardMode): strict installs the
+            // PreToolUse deny hook; default removes any previously installed one.
+            if (guardMode() === "strict") {
+                const hookResult = installClaudeCodeHook(workspaceRoot);
+                if (hookResult) {
+                    results.push({
+                        agent: "Claude Code Hook",
+                        configFile: ".claude/hooks/vexp-guard.sh",
+                        content: VEXP_GUARD_HOOK,
+                        alreadyExists: false,
+                        action: hookResult,
+                    });
+                }
+            }
+            else if (uninstallClaudeCodeHook(workspaceRoot)) {
                 results.push({
                     agent: "Claude Code Hook",
                     configFile: ".claude/hooks/vexp-guard.sh",
-                    content: VEXP_GUARD_HOOK,
+                    content: "",
                     alreadyExists: false,
-                    action: hookResult,
+                    action: "removed",
                 });
             }
         }
@@ -348,34 +379,56 @@ export function configureAgents(workspaceRoot, binaryPath, version, agentFilter,
             // 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).
-            const kilo = installKiloPlugin(workspaceRoot);
-            if (kilo.plugin) {
+            if (guardMode() === "strict") {
+                const kilo = installKiloPlugin(workspaceRoot);
+                if (kilo.plugin) {
+                    results.push({
+                        agent: "Kilo Code Guard",
+                        configFile: path.join(".kilo", "plugins", "vexp-guard.js"),
+                        content: VEXP_OPENCODE_GUARD,
+                        alreadyExists: kilo.plugin === "updated",
+                        action: kilo.plugin,
+                    });
+                }
+                if (kilo.registered)
+                    mcpConfigs.push(path.relative(workspaceRoot, kiloConfigTarget(workspaceRoot)));
+            }
+            else if (uninstallKiloPlugin(workspaceRoot)) {
                 results.push({
                     agent: "Kilo Code Guard",
                     configFile: path.join(".kilo", "plugins", "vexp-guard.js"),
-                    content: VEXP_OPENCODE_GUARD,
-                    alreadyExists: kilo.plugin === "updated",
-                    action: kilo.plugin,
+                    content: "",
+                    alreadyExists: false,
+                    action: "removed",
                 });
             }
-            if (kilo.registered)
-                mcpConfigs.push(path.relative(workspaceRoot, kiloConfigTarget(workspaceRoot)));
         }
         // Cursor: preToolUse hook matching Grep. Text search only - Cursor's native
         // semantic search is not hookable.
         if (detector.agent === "Cursor") {
-            const cur = installCursorHook(workspaceRoot);
-            if (cur.hook) {
+            if (guardMode() === "strict") {
+                const cur = installCursorHook(workspaceRoot);
+                if (cur.hook) {
+                    results.push({
+                        agent: "Cursor Guard",
+                        configFile: path.join(".cursor", "hooks", "vexp-guard.js"),
+                        content: VEXP_CURSOR_GUARD,
+                        alreadyExists: cur.hook === "updated",
+                        action: cur.hook,
+                    });
+                }
+                if (cur.registered)
+                    mcpConfigs.push(path.join(".cursor", "hooks.json"));
+            }
+            else if (uninstallCursorHook(workspaceRoot)) {
                 results.push({
                     agent: "Cursor Guard",
                     configFile: path.join(".cursor", "hooks", "vexp-guard.js"),
-                    content: VEXP_CURSOR_GUARD,
-                    alreadyExists: cur.hook === "updated",
-                    action: cur.hook,
+                    content: "",
+                    alreadyExists: false,
+                    action: "removed",
                 });
             }
-            if (cur.registered)
-                mcpConfigs.push(path.join(".cursor", "hooks.json"));
         }
         // Opencode: MCP lives under the `mcp` key in opencode.json(c) — opencode
         // carries no `mcpConfigFile`, so without this call the generic writer above
@@ -386,14 +439,25 @@ export function configureAgents(workspaceRoot, binaryPath, version, agentFilter,
             const wroteMcp = configureOpencodeMcp(workspaceRoot, binaryPath, mcpServerPath);
             if (wroteMcp)
                 mcpConfigs.push(wroteMcp);
-            const pluginResult = installOpencodePlugin(workspaceRoot);
-            if (pluginResult) {
+            if (guardMode() === "strict") {
+                const pluginResult = installOpencodePlugin(workspaceRoot);
+                if (pluginResult) {
+                    results.push({
+                        agent: "Opencode Guard",
+                        configFile: ".opencode/plugins/vexp-guard.js",
+                        content: VEXP_OPENCODE_GUARD,
+                        alreadyExists: pluginResult === "updated",
+                        action: pluginResult,
+                    });
+                }
+            }
+            else if (uninstallOpencodePlugin(workspaceRoot)) {
                 results.push({
                     agent: "Opencode Guard",
                     configFile: ".opencode/plugins/vexp-guard.js",
-                    content: VEXP_OPENCODE_GUARD,
-                    alreadyExists: pluginResult === "updated",
-                    action: pluginResult,
+                    content: "",
+                    alreadyExists: false,
+                    action: "removed",
                 });
             }
         }
@@ -529,15 +593,24 @@ export function configureSelectedAgents(workspaceRoot, binaryPath, version, sele
         }
         if (detector.mcpConfigFile) {
             const mcpConfigPath = path.join(workspaceRoot, detector.mcpConfigFile);
-            const alwaysAllow = detector.agent === "Windsurf" ? VEXP_TOOLS : undefined;
-            if (writeMcpConfig(mcpConfigPath, binaryPath, alwaysAllow, mcpServerPath, workspaceRoot))
+            const isKiro = detector.agent === "Kiro";
+            // See configureAgents(): Kiro auto-approves under `autoApprove` and is
+            // pointed at the vexp binary (no `node` on macOS GUI PATH) by withholding
+            // mcpServerPath.
+            const alwaysAllow = (detector.agent === "Windsurf" || isKiro) ? VEXP_TOOLS : undefined;
+            const approveKey = isKiro ? "autoApprove" : "alwaysAllow";
+            const mcpSrv = isKiro ? undefined : mcpServerPath;
+            if (writeMcpConfig(mcpConfigPath, binaryPath, alwaysAllow, mcpSrv, workspaceRoot, approveKey))
                 mcpConfigs.push(detector.mcpConfigFile);
         }
         if (detector.agent === "Claude Code") {
             const wrote = configureClaudeCodeGlobal(binaryPath, mcpServerPath, workspaceRoot);
             if (wrote)
                 mcpConfigs.push("~/.claude.json");
-            installClaudeCodeHook(workspaceRoot);
+            if (guardMode() === "strict")
+                installClaudeCodeHook(workspaceRoot);
+            else
+                uninstallClaudeCodeHook(workspaceRoot);
         }
         if (detector.agent === "Codex") {
             const wrote = configureCodexGlobal(binaryPath, mcpServerPath, workspaceRoot);
@@ -563,10 +636,16 @@ export function configureSelectedAgents(workspaceRoot, binaryPath, version, sele
             const wrote = configureOpencodeMcp(workspaceRoot, binaryPath, mcpServerPath);
             if (wrote)
                 mcpConfigs.push(wrote);
-            installOpencodePlugin(workspaceRoot);
+            if (guardMode() === "strict")
+                installOpencodePlugin(workspaceRoot);
+            else
+                uninstallOpencodePlugin(workspaceRoot);
         }
         if (detector.agent === "Cursor") {
-            installCursorHook(workspaceRoot);
+            if (guardMode() === "strict")
+                installCursorHook(workspaceRoot);
+            else
+                uninstallCursorHook(workspaceRoot);
         }
         // Kilo carries no `mcpConfigFile` (its MCP lives under the `mcp` key inside
         // kilo.jsonc), so without this branch the generic writer above skips it and
@@ -576,7 +655,10 @@ export function configureSelectedAgents(workspaceRoot, binaryPath, version, sele
             const wrote = configureKiloMcp(workspaceRoot, binaryPath, mcpServerPath);
             if (wrote)
                 mcpConfigs.push(wrote);
-            installKiloPlugin(workspaceRoot);
+            if (guardMode() === "strict")
+                installKiloPlugin(workspaceRoot);
+            else
+                uninstallKiloPlugin(workspaceRoot);
         }
         results.push({ agent: detector.agent, configFile: detector.configFile, content, alreadyExists, action });
     }
@@ -861,7 +943,10 @@ export function configureAntigravityGlobal(binaryPath, mcpServerPath) {
     }
     return writeMcpConfig(path.join(cfgDir, "mcp_config.json"), binaryPath, undefined, mcpServerPath, undefined);
 }
-export function writeMcpConfig(mcpConfigPath, binaryPath, alwaysAllow, mcpServerPath, workspaceRoot) {
+export function writeMcpConfig(mcpConfigPath, binaryPath, alwaysAllow, mcpServerPath, workspaceRoot, 
+// Key under which the auto-approve tool list is written. Cursor/Windsurf use
+// `alwaysAllow`; Kiro uses `autoApprove` (a `.kiro/settings/mcp.json` field).
+approveKey = "alwaysAllow") {
     const read = readJsonConfigSafe(mcpConfigPath);
     if (!read.ok) {
         warnUnparseable(mcpConfigPath);
@@ -900,7 +985,7 @@ export function writeMcpConfig(mcpConfigPath, binaryPath, alwaysAllow, mcpServer
         command: targetCmd,
         args: targetArgs,
         ...(targetEnv ? { env: targetEnv } : {}),
-        ...(alwaysAllow && alwaysAllow.length > 0 ? { alwaysAllow } : {}),
+        ...(alwaysAllow && alwaysAllow.length > 0 ? { [approveKey]: alwaysAllow } : {}),
     };
     existing.mcpServers = servers;
     fs.mkdirSync(path.dirname(mcpConfigPath), { recursive: true });
@@ -1457,6 +1542,68 @@ export function migrateClaudeCodeUnpin() {
 // ---------------------------------------------------------------------------
 // Claude Code PreToolUse hook - blocks Grep/Glob when daemon is available
 // ---------------------------------------------------------------------------
+/**
+ * True for any vexp-related PreToolUse entry in .claude/settings.json —
+ * old format, stale matchers, malformed "suggestion" hooks. Shared by the
+ * strict installer (dedup before re-adding) and the uninstaller (guard off).
+ */
+function isVexpGuardHookEntry(h) {
+    if (!h || typeof h !== "object")
+        return false;
+    const entry = h;
+    const cmd = entry.command;
+    if (cmd && cmd.includes("vexp-guard"))
+        return true;
+    const hks = entry.hooks;
+    if (hks && Array.isArray(hks) && hks.some((hook) => {
+        if (!hook || typeof hook !== "object")
+            return false;
+        const hCmd = hook.command;
+        return hCmd?.includes("vexp-guard") ?? false;
+    }))
+        return true;
+    if (cmd && cmd.includes("run_pipeline") && cmd.includes("allow"))
+        return true;
+    return false;
+}
+/**
+ * Remove the Claude Code guard (2.3 A2 default): drop vexp entries from
+ * .claude/settings.json PreToolUse and delete the hook scripts. Returns true
+ * when anything was actually removed.
+ */
+export function uninstallClaudeCodeHook(workspaceRoot) {
+    let removed = false;
+    const hookDir = path.join(workspaceRoot, ".claude", "hooks");
+    for (const name of ["vexp-guard.sh", "vexp-guard.cmd"]) {
+        const p = path.join(hookDir, name);
+        if (fs.existsSync(p)) {
+            try {
+                fs.unlinkSync(p);
+                removed = true;
+            }
+            catch { /* leave in place */ }
+        }
+    }
+    const settingsPath = path.join(workspaceRoot, ".claude", "settings.json");
+    const read = readJsonConfigSafe(settingsPath);
+    if (read.ok && read.existed) {
+        const settings = read.data;
+        const hooks = (settings.hooks ?? {});
+        const existingPreToolUse = Array.isArray(hooks.PreToolUse) ? hooks.PreToolUse : [];
+        const filtered = existingPreToolUse.filter((h) => !isVexpGuardHookEntry(h));
+        if (filtered.length !== existingPreToolUse.length) {
+            if (filtered.length > 0)
+                hooks.PreToolUse = filtered;
+            else
+                delete hooks.PreToolUse;
+            settings.hooks = hooks;
+            backupConfig(settingsPath);
+            fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+            removed = true;
+        }
+    }
+    return removed;
+}
 /**
  * Install the vexp-guard hook for Claude Code.
  * Creates .claude/hooks/vexp-guard.sh and merges hook config into .claude/settings.json.
@@ -1485,28 +1632,7 @@ export function installClaudeCodeHook(workspaceRoot) {
     const hooks = (settings.hooks ?? {});
     const existingPreToolUse = Array.isArray(hooks.PreToolUse) ? hooks.PreToolUse : [];
     // Aggressively remove ALL vexp-related hook entries (old format, stale matchers, malformed)
-    const filtered = existingPreToolUse.filter((h) => {
-        if (!h || typeof h !== "object")
-            return true;
-        const entry = h;
-        // Remove flat-format entries referencing vexp-guard
-        const cmd = entry.command;
-        if (cmd && cmd.includes("vexp-guard"))
-            return false;
-        // Remove nested-format entries referencing vexp-guard
-        const hks = entry.hooks;
-        if (hks && Array.isArray(hks) && hks.some((hook) => {
-            if (!hook || typeof hook !== "object")
-                return false;
-            const hCmd = hook.command;
-            return hCmd?.includes("vexp-guard") ?? false;
-        }))
-            return false;
-        // Remove malformed "suggestion" hooks that output allow + mention run_pipeline
-        if (cmd && cmd.includes("run_pipeline") && cmd.includes("allow"))
-            return false;
-        return true;
-    });
+    const filtered = existingPreToolUse.filter((h) => !isVexpGuardHookEntry(h));
     filtered.push({
         matcher: "Grep|Glob|Regex",
         hooks: [
@@ -1555,6 +1681,25 @@ function writeGuardScript(scriptPath, content) {
 export function installOpencodePlugin(workspaceRoot) {
     return writeGuardScript(path.join(workspaceRoot, ".opencode", "plugins", "vexp-guard.js"), VEXP_OPENCODE_GUARD);
 }
+/** Delete a guard script if present. Returns true when a file was removed. */
+function removeGuardScript(scriptPath) {
+    if (!fs.existsSync(scriptPath))
+        return false;
+    try {
+        fs.unlinkSync(scriptPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Remove the opencode guard plugin (2.3 A2 default). Both directory
+ *  spellings are checked — older builds wrote `.opencode/plugin/`. */
+export function uninstallOpencodePlugin(workspaceRoot) {
+    const a = removeGuardScript(path.join(workspaceRoot, ".opencode", "plugins", "vexp-guard.js"));
+    const b = removeGuardScript(path.join(workspaceRoot, ".opencode", "plugin", "vexp-guard.js"));
+    return a || b;
+}
 /**
  * Cursor enforcement — `preToolUse` hook with matcher `Grep`.
  *
@@ -1661,6 +1806,59 @@ export function installKiloPlugin(workspaceRoot) {
     fs.writeFileSync(target, JSON.stringify(cfg, null, 2), "utf-8");
     return { plugin, registered: true };
 }
+/** Remove the Kilo guard plugin (2.3 A2 default): delete the script and drop
+ *  the explicit `plugin` array entry from a root kilo.jsonc when present. */
+export function uninstallKiloPlugin(workspaceRoot) {
+    const pluginPath = path.join(workspaceRoot, ".kilo", "plugins", "vexp-guard.js");
+    let removed = removeGuardScript(pluginPath);
+    const target = kiloConfigTarget(workspaceRoot);
+    const read = readJsonConfigSafe(target);
+    if (read.ok && read.existed) {
+        const cfg = read.data;
+        const list = Array.isArray(cfg.plugin) ? cfg.plugin : [];
+        const filtered = list.filter((e) => typeof e !== "string" || !e.includes("vexp-guard"));
+        if (filtered.length !== list.length) {
+            if (filtered.length > 0)
+                cfg.plugin = filtered;
+            else
+                delete cfg.plugin;
+            backupConfig(target);
+            fs.writeFileSync(target, JSON.stringify(cfg, null, 2), "utf-8");
+            removed = true;
+        }
+    }
+    return removed;
+}
+/** 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) {
+    const rel = path.join(".cursor", "hooks", "vexp-guard.js");
+    let removed = removeGuardScript(path.join(workspaceRoot, rel));
+    const cfgPath = path.join(workspaceRoot, ".cursor", "hooks.json");
+    const read = readJsonConfigSafe(cfgPath);
+    if (read.ok && read.existed) {
+        const cfg = read.data;
+        const hooks = cfg.hooks ?? {};
+        const preToolUse = Array.isArray(hooks.preToolUse) ? hooks.preToolUse : [];
+        const filtered = preToolUse.filter((e) => {
+            if (!e || typeof e !== "object")
+                return true;
+            const cmd = e.command;
+            return typeof cmd !== "string" || !cmd.includes("vexp-guard");
+        });
+        if (filtered.length !== preToolUse.length) {
+            if (filtered.length > 0)
+                hooks.preToolUse = filtered;
+            else
+                delete hooks.preToolUse;
+            cfg.hooks = hooks;
+            backupConfig(cfgPath);
+            fs.writeFileSync(cfgPath, JSON.stringify(cfg, null, 2), "utf-8");
+            removed = true;
+        }
+    }
+    return removed;
+}
 /**
  * The single highest-leverage instruction we ship, and for a long time the one
  * most agents never saw.
@@ -1714,22 +1912,30 @@ function generateAgentConfig(template, vars) {
 function claudeCodeTemplate(vars) {
     return `## vexp - Context-Aware AI Coding <!-- vexp v${vars.version} -->
 
-### MANDATORY: use vexp pipeline - do NOT grep or glob the codebase
-For every task - bug fixes, features, refactors, debugging:
-**call \`run_pipeline\` FIRST**. It executes context search + impact analysis +
-memory recall in a single call, returning compressed results.
-
-Do NOT use grep, glob, Bash, or cat to search/explore the codebase.
-vexp returns pre-indexed, graph-ranked context that is more relevant and
-uses fewer tokens than manual searching. Prefer \`get_skeleton\` over Read to
-inspect files (detail: minimal/standard/detailed, 70-90% token savings).
-Only use Read when you need exact raw content to edit a specific line.
-
-The hook denies Grep/Glob while the daemon is up. That is policy, not a transient
-failure: call \`run_pipeline\` instead - do NOT work around it by shelling out or
-writing a script. 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 Bash/Read there, those are never blocked.
+### Context strategy: one pipeline call up front, then your normal tools
+For every multi-file task - bug fixes, features, refactors, debugging:
+**call \`run_pipeline\` ONCE at the start**. It executes context search + impact
+analysis + memory recall in a single call: which files matter, what breaks,
+what was learned before. Then implement with your normal tools.
+
+Division of labor (each tool where it wins):
+- **Architecture, impact, "where is X wired"**: \`run_pipeline\` - the graph
+  answers these better and cheaper than exploratory reading.
+- **Literal text sweeps** (string constants, log messages, config keys, e.g.
+  \`localStorage\`, API paths): Grep/Glob directly - text search is what they
+  are best at, do NOT route text sweeps through vexp.
+- **Editing**: Read the files you are about to modify; use \`get_skeleton\`
+  (detail: minimal/standard/detailed, 70-90% token savings) for files you only
+  need to understand, not edit.
+
+Every extra tool call costs a turn: one good \`run_pipeline\` call beats five
+small ones. Each result opens with a coverage header (index: N files, M nodes) -
+if it does not match this repo, run \`vexp index\`.
+vexp only covers indexed source inside the workspace: for runtime logs, build
+output (dist/, .vite/, node_modules/) or files outside the repo use Bash/Read.
+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.
 
 ### Primary Tool
 - \`run_pipeline\` - **USE THIS FOR EVERYTHING**. Single call that runs
@@ -1749,18 +1955,17 @@ no answer - use Bash/Read there, those are never blocked.
 ${QUERY_SHAPE}
 
 ### Workflow
-1. \`run_pipeline("your task")\` - ALWAYS FIRST. Returns pivots + impact + memories in 1 call
-2. Need more detail on a file? Use \`get_skeleton({ files: [...], detail: "detailed" })\` - avoid Read unless editing
-3. Make targeted changes based on the context returned
-4. \`run_pipeline\` again ONLY if you need more context during implementation
-5. Do NOT chain multiple vexp calls - one \`run_pipeline\` replaces capsule + impact + memory + observation
+1. \`run_pipeline("your task")\` - ONCE at task start. Returns pivots + impact + memories in 1 call
+2. Literal string sweeps? Grep/Glob directly. Editing a file? Read it directly.
+3. Structural overview of a non-edit file? \`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 per turn
 
 ### Subagent / Explore / Plan mode
-- Subagents CAN and MUST call \`run_pipeline\` - always include the task description
-- The PreToolUse hook blocks Grep/Glob when vexp daemon is running
-- Do NOT spawn Agent(Explore) to freely search - call \`run_pipeline\` first,
-  then pass the returned context into the agent prompt if needed
-- Always: \`run_pipeline\` -> get context -> spawn agent with context
+- Subagents CAN call \`run_pipeline\` - always include the task description
+- Before spawning Agent(Explore) for architecture questions, call \`run_pipeline\`
+  and pass the returned context into the agent prompt - it usually replaces the
+  exploration entirely
 
 ### Smart Features (automatic - no action needed)
 - **Intent Detection**: auto-detects from your task keywords. "fix bug" -> Debug, "refactor" -> blast-radius, "add" -> Modify
@@ -1788,13 +1993,19 @@ Use \`index_status\` to discover available repo aliases.
 function cursorTemplate(vars) {
     return `## vexp rules for Cursor <!-- vexp v${vars.version} -->
 
-**MANDATORY: use \`run_pipeline\` - do NOT grep, glob, or read files manually.**
-vexp returns pre-indexed, graph-ranked context in a single call.
+**Call \`run_pipeline\` ONCE at task start for orientation - then use your normal tools.**
+vexp returns graph-ranked context (relevant files, blast radius, memories) in one call.
+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 - ALWAYS FIRST (replaces all other tools)
-2. Make targeted changes based on the context returned
-3. \`run_pipeline\` again only if you need more context
+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.
@@ -1806,9 +2017,10 @@ vexp returns pre-indexed, graph-ranked context in a single call.
 ${QUERY_SHAPE}
 
 ### Agentic search
-- Do NOT use built-in file search, grep, or codebase indexing - always call \`run_pipeline\` first
+- 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\`
-  rather than letting them search the codebase independently
+  so they do not re-explore from scratch
 
 ### Tips
 - Add \`include_tests: true\` when debugging
@@ -1828,13 +2040,19 @@ Use file search and read tools directly until the index is ready.
 function windsurfTemplate(vars) {
     return `## vexp for Windsurf <!-- vexp v${vars.version} -->
 
-**MANDATORY: use \`run_pipeline\` - do NOT grep, glob, or read files manually.**
-vexp returns pre-indexed, graph-ranked context in a single call.
+**Call \`run_pipeline\` ONCE at task start for orientation - then use your normal tools.**
+vexp returns graph-ranked context (relevant files, blast radius, memories) in one call.
+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 - ALWAYS FIRST (replaces all other tools)
-2. Make targeted changes based on the context returned
-3. \`run_pipeline\` again only if you need more context
+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.
@@ -1846,9 +2064,10 @@ vexp returns pre-indexed, graph-ranked context in a single call.
 ${QUERY_SHAPE}
 
 ### Agentic search
-- Do NOT use built-in file search, grep, or codebase indexing - always call \`run_pipeline\` first
+- 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\`
-  rather than letting them search the codebase independently
+  so they do not re-explore from scratch
 
 ### Smart Features
 Intent auto-detection, hybrid ranking, session memory, auto-expanding budget.
@@ -1879,13 +2098,19 @@ function continueTemplate(vars) {
 function augmentTemplate(vars) {
     return `## vexp for Augment <!-- vexp v${vars.version} -->
 
-**MANDATORY: use \`run_pipeline\` - do NOT grep, glob, or read files manually.**
-vexp returns pre-indexed, graph-ranked context in a single call.
+**Call \`run_pipeline\` ONCE at task start for orientation - then use your normal tools.**
+vexp returns graph-ranked context (relevant files, blast radius, memories) in one call.
+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 - ALWAYS FIRST
-2. Make targeted changes based on the context returned
-3. \`run_pipeline\` again only if you need more context
+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.
@@ -1897,9 +2122,10 @@ When working on this codebase:
 ${QUERY_SHAPE}
 
 ### Agentic search
-- Do NOT use built-in file search, grep, or codebase indexing - always call \`run_pipeline\` first
+- 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\`
-  rather than letting them search the codebase independently
+  so they do not re-explore from scratch
 
 ### Smart Features
 Intent auto-detection, hybrid ranking, session memory, auto-expanding budget.
@@ -1911,13 +2137,19 @@ Intent auto-detection, hybrid ranking, session memory, auto-expanding budget.
 function copilotTemplate(vars) {
     return `## vexp context tools <!-- vexp v${vars.version} -->
 
-**MANDATORY: use \`run_pipeline\` - do NOT grep, glob, or read files manually.**
-vexp returns pre-indexed, graph-ranked context in a single call.
+**Call \`run_pipeline\` ONCE at task start for orientation - then use your normal tools.**
+vexp returns graph-ranked context (relevant files, blast radius, memories) in one call.
+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 - ALWAYS FIRST (replaces all other tools)
-2. Make targeted changes based on the context returned
-3. \`run_pipeline\` again only if you need more context
+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.
@@ -1929,9 +2161,10 @@ vexp returns pre-indexed, graph-ranked context in a single call.
 ${QUERY_SHAPE}
 
 ### Agentic search
-- Do NOT use built-in file search, grep, or codebase indexing - always call \`run_pipeline\` first
+- 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\`
-  rather than letting them search the codebase independently
+  so they do not re-explore from scratch
 
 ### Smart Features
 Intent auto-detection, hybrid ranking, session memory, auto-expanding budget.
@@ -1943,13 +2176,19 @@ Intent auto-detection, hybrid ranking, session memory, auto-expanding budget.
 function zedTemplate(vars) {
     return `## vexp for Zed <!-- vexp v${vars.version} -->
 
-**MANDATORY: use \`run_pipeline\` - do NOT grep, glob, or read files manually.**
-vexp returns pre-indexed, graph-ranked context in a single call.
+**Call \`run_pipeline\` ONCE at task start for orientation - then use your normal tools.**
+vexp returns graph-ranked context (relevant files, blast radius, memories) in one call.
+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 - ALWAYS FIRST (replaces all other tools)
-2. Make targeted changes based on the context returned
-3. \`run_pipeline\` again only if you need more context
+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.
@@ -1961,9 +2200,10 @@ vexp returns pre-indexed, graph-ranked context in a single call.
 ${QUERY_SHAPE}
 
 ### Agentic search
-- Do NOT use built-in file search, grep, or codebase indexing - always call \`run_pipeline\` first
+- 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\`
-  rather than letting them search the codebase independently
+  so they do not re-explore from scratch
 
 ### Smart Features
 Intent auto-detection, hybrid ranking, session memory, auto-expanding budget.
@@ -1975,13 +2215,19 @@ Intent auto-detection, hybrid ranking, session memory, auto-expanding budget.
 function agentsMdTemplate(vars) {
     return `## vexp <!-- vexp v${vars.version} -->
 
-**MANDATORY: use \`run_pipeline\` - do NOT grep or glob the codebase.**
-vexp returns pre-indexed, graph-ranked context in a single call.
+**Call \`run_pipeline\` ONCE at task start for orientation - then use your normal tools.**
+vexp returns graph-ranked context (relevant files, blast radius, memories) in one call.
+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 - ALWAYS FIRST (replaces all other tools)
-2. Make targeted changes based on the context returned
-3. \`run_pipeline\` again only if you need more context
+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.
@@ -1993,14 +2239,13 @@ vexp returns pre-indexed, graph-ranked context in a single call.
 ${QUERY_SHAPE}
 
 ### Agentic search
-- Do NOT use built-in file search, grep, or codebase indexing - always call \`run_pipeline\` first
-- If a search tool is denied, that is policy, not a transient failure: call \`run_pipeline\`
-  instead. Do NOT work around it with shell search or by writing a script.
+- 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; those searches are never blocked.
+  normal tools there.
 - If you spawn sub-agents or background tasks, pass them the context from \`run_pipeline\`
-  rather than letting them search the codebase independently
+  so they do not re-explore from scratch
 
 ### Smart Features
 Intent auto-detection, hybrid ranking, session memory, auto-expanding budget.
@@ -2012,13 +2257,19 @@ Intent auto-detection, hybrid ranking, session memory, auto-expanding budget.
 function kiroTemplate(vars) {
     return `# vexp steering <!-- vexp v${vars.version} -->
 
-**MANDATORY: use \`run_pipeline\` - do NOT grep, glob, or read files manually.**
-vexp returns pre-indexed, graph-ranked context in a single call.
+**Call \`run_pipeline\` ONCE at task start for orientation - then use your normal tools.**
+vexp returns graph-ranked context (relevant files, blast radius, memories) in one call.
+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 - ALWAYS FIRST (replaces all other tools)
-2. Make targeted changes based on the context returned
-3. \`run_pipeline\` again only if you need more context
+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.
@@ -2030,9 +2281,10 @@ vexp returns pre-indexed, graph-ranked context in a single call.
 ${QUERY_SHAPE}
 
 ## Agentic search
-- Do NOT use built-in file search, grep, or codebase indexing - always call \`run_pipeline\` first
+- 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\`
-  rather than letting them search the codebase independently
+  so they do not re-explore from scratch
 
 ## Smart Features
 Intent auto-detection, hybrid ranking, session memory, auto-expanding budget.
@@ -2044,22 +2296,24 @@ Intent auto-detection, hybrid ranking, session memory, auto-expanding budget.
 function genericTemplate(vars) {
     return `## vexp - Context-Aware AI Coding <!-- vexp v${vars.version} -->
 
-### MANDATORY: call run_pipeline FIRST - do NOT grep, glob, or read to explore
-For every task - bug fixes, features, refactors, questions about the code:
-**call \`run_pipeline\` before any other tool**. It runs context search + impact
-analysis + memory recall in a single call and returns compressed, graph-ranked
-results.
-
-This holds even when you already know the file path. The pipeline returns the
-callers, the blast radius and the co-changed files that opening the file cannot.
-No tool here will stop you from searching manually, so honouring this rule is on
-you: "I already knew where to look" is not an exception, it is the exact case the
-rule exists for.
-
-Do NOT use grep, glob, built-in codebase search, or shell commands to explore.
-Do NOT open files one by one to find your way around: use \`get_skeleton\`
-(detail: minimal/standard/detailed, 70-90% fewer tokens than reading the file).
-Read raw file content only when you need it to edit a specific line.
+### Context strategy: call run_pipeline ONCE at task start
+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.
+
+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 -
@@ -2080,16 +2334,16 @@ read those directly, this rule does not cover them.
 ${QUERY_SHAPE}
 
 ### Workflow
-1. \`run_pipeline("your task")\` - ALWAYS FIRST. Returns pivots + impact + memories in 1 call
-2. Need more on a file? \`get_skeleton({ files: [...], detail: "detailed" })\` - not a raw read
-3. Make targeted changes based on the context returned
-4. \`run_pipeline\` again ONLY if you need more context while implementing
-5. Do NOT chain vexp calls - one \`run_pipeline\` replaces capsule + impact + memory + observation
+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 and MUST call \`run_pipeline\` - always give them the task description
-- Do NOT spawn an agent to search freely: call \`run_pipeline\` first, then pass the
-  returned context into the agent prompt
+- 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,