vexp-cli 2.3.0 → 2.4.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 } from "./hook-template.js";
+import { VEXP_GUARD_HOOK, VEXP_OPENCODE_GUARD, VEXP_CURSOR_GUARD, vexpHintHookScript, vexpOpencodeHintPlugin } from "./hook-template.js";
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -320,6 +320,18 @@ export function configureAgents(workspaceRoot, binaryPath, version, agentFilter,
             const wrote = configureClaudeCodeGlobal(binaryPath, mcpServerPath, workspaceRoot);
             if (wrote)
                 mcpConfigs.push("~/.claude.json");
+            // Event-driven hint hook: default-on (non-blocking, fail-open — the
+            // 2.3 A2 opt-in applies to DENY hooks, this one cannot block).
+            const hintResult = installClaudeCodeHintHook(workspaceRoot, binaryPath);
+            if (hintResult) {
+                results.push({
+                    agent: "Claude Code Hint",
+                    configFile: ".claude/hooks/vexp-hint.sh",
+                    content: vexpHintHookScript(binaryPath),
+                    alreadyExists: false,
+                    action: hintResult,
+                });
+            }
             // Guard is OPT-IN from 2.3 (see GuardMode): strict installs the
             // PreToolUse deny hook; default removes any previously installed one.
             if (guardMode() === "strict") {
@@ -349,6 +361,7 @@ export function configureAgents(workspaceRoot, binaryPath, version, agentFilter,
             const wrote = configureCodexGlobal(binaryPath, mcpServerPath, workspaceRoot);
             if (wrote)
                 mcpConfigs.push("~/.codex/config.toml");
+            installCodexHintHook(workspaceRoot, binaryPath);
         }
         // Antigravity: machine-global MCP config (~/.gemini/antigravity/mcp_config.json)
         if (detector.agent === "Antigravity") {
@@ -376,6 +389,7 @@ export function configureAgents(workspaceRoot, binaryPath, version, agentFilter,
             const wrote = configureKiloMcp(workspaceRoot, binaryPath, mcpServerPath);
             if (wrote)
                 mcpConfigs.push(wrote);
+            installOpencodeHintPlugin(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).
@@ -437,6 +451,7 @@ export function configureAgents(workspaceRoot, binaryPath, version, agentFilter,
         // Claude Code PreToolUse hook) — which is only safe once MCP is registered.
         if (detector.agent === "Opencode") {
             const wroteMcp = configureOpencodeMcp(workspaceRoot, binaryPath, mcpServerPath);
+            installOpencodeHintPlugin(workspaceRoot, binaryPath, ".opencode/plugin");
             if (wroteMcp)
                 mcpConfigs.push(wroteMcp);
             if (guardMode() === "strict") {
@@ -607,6 +622,7 @@ export function configureSelectedAgents(workspaceRoot, binaryPath, version, sele
             const wrote = configureClaudeCodeGlobal(binaryPath, mcpServerPath, workspaceRoot);
             if (wrote)
                 mcpConfigs.push("~/.claude.json");
+            installClaudeCodeHintHook(workspaceRoot, binaryPath);
             if (guardMode() === "strict")
                 installClaudeCodeHook(workspaceRoot);
             else
@@ -616,6 +632,7 @@ export function configureSelectedAgents(workspaceRoot, binaryPath, version, sele
             const wrote = configureCodexGlobal(binaryPath, mcpServerPath, workspaceRoot);
             if (wrote)
                 mcpConfigs.push("~/.codex/config.toml");
+            installCodexHintHook(workspaceRoot, binaryPath);
         }
         if (detector.agent === "Antigravity") {
             const wrote = configureAntigravityGlobal(binaryPath, mcpServerPath);
@@ -636,6 +653,7 @@ export function configureSelectedAgents(workspaceRoot, binaryPath, version, sele
             const wrote = configureOpencodeMcp(workspaceRoot, binaryPath, mcpServerPath);
             if (wrote)
                 mcpConfigs.push(wrote);
+            installOpencodeHintPlugin(workspaceRoot, binaryPath, ".opencode/plugin");
             if (guardMode() === "strict")
                 installOpencodePlugin(workspaceRoot);
             else
@@ -655,6 +673,7 @@ export function configureSelectedAgents(workspaceRoot, binaryPath, version, sele
             const wrote = configureKiloMcp(workspaceRoot, binaryPath, mcpServerPath);
             if (wrote)
                 mcpConfigs.push(wrote);
+            installOpencodeHintPlugin(workspaceRoot, binaryPath, ".kilo/plugin");
             if (guardMode() === "strict")
                 installKiloPlugin(workspaceRoot);
             else
@@ -1613,40 +1632,199 @@ export function installClaudeCodeHook(workspaceRoot) {
     const hookDir = path.join(workspaceRoot, ".claude", "hooks");
     const hookPath = path.join(hookDir, "vexp-guard.sh");
     const settingsPath = path.join(workspaceRoot, ".claude", "settings.json");
-    // 1. Write hook script
+    // 1. Write hook script. An identical script must NOT short-circuit the
+    // settings merge below: the 2.3.0→2.3.1 fix changed only the settings
+    // ENTRY (shell form → exec form), so skipping on identical script would
+    // leave every existing install on the broken word-splitting entry forever.
     fs.mkdirSync(hookDir, { recursive: true });
     const existed = fs.existsSync(hookPath);
-    if (existed) {
-        const current = fs.readFileSync(hookPath, "utf-8");
-        if (current === VEXP_GUARD_HOOK)
-            return null; // identical - skip
+    const scriptIdentical = existed && fs.readFileSync(hookPath, "utf-8") === VEXP_GUARD_HOOK;
+    if (!scriptIdentical) {
+        fs.writeFileSync(hookPath, VEXP_GUARD_HOOK, { mode: 0o755 });
     }
-    fs.writeFileSync(hookPath, VEXP_GUARD_HOOK, { mode: 0o755 });
     // 2. Merge hook config into .claude/settings.json
     const read = readJsonConfigSafe(settingsPath);
     if (!read.ok) {
         warnUnparseable(settingsPath);
-        return existed ? "updated" : "created";
+        return scriptIdentical ? null : existed ? "updated" : "created";
     }
     const settings = read.data;
     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) => !isVexpGuardHookEntry(h));
+    // Shell form with an explicit `bash` prefix and a QUOTED path — the one
+    // shape that works on every OS Claude Code supports:
+    //  - the quotes fix the historical spaces bug (unquoted
+    //    `$CLAUDE_PROJECT_DIR/...` word-split and the guard never ran);
+    //  - exec form (`args` present → direct spawn) fixed spaces but broke
+    //    Windows entirely: the OS cannot spawn a `.sh` without a shell, the
+    //    hook errored, failed open, and enforced nothing (field report) —
+    //    Claude Code on Windows runs shell-form hooks through Git Bash, so
+    //    `bash "$VAR"` works there and on unix alike.
+    // `timeout` is SECONDS (default 600), not ms: 3000 once configured a
+    // 50-minute hook timeout.
     filtered.push({
         matcher: "Grep|Glob|Regex",
         hooks: [
             {
                 type: "command",
-                command: "$CLAUDE_PROJECT_DIR/.claude/hooks/vexp-guard.sh",
-                timeout: 3000,
+                command: 'bash "$CLAUDE_PROJECT_DIR/.claude/hooks/vexp-guard.sh"',
+                timeout: 5,
             },
         ],
     });
-    settings.hooks = { ...hooks, PreToolUse: filtered };
-    if (read.existed)
-        backupConfig(settingsPath);
-    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+    // Idempotence check AFTER the merge is computed: skip the write (and the
+    // backup) only when settings already contain exactly the entry we would
+    // write AND the script was already current.
+    const merged = { ...hooks, PreToolUse: filtered };
+    const settingsIdentical = JSON.stringify(merged) === JSON.stringify(settings.hooks ?? {});
+    if (scriptIdentical && settingsIdentical)
+        return null;
+    settings.hooks = merged;
+    if (!settingsIdentical) {
+        if (read.existed)
+            backupConfig(settingsPath);
+        fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+    }
+    return existed ? "updated" : "created";
+}
+function isVexpHintHookEntry(h) {
+    if (!h || typeof h !== "object")
+        return false;
+    const entry = h;
+    const own = entry.command?.includes("vexp-hint");
+    if (own)
+        return true;
+    const hks = entry.hooks;
+    return Array.isArray(hks) && hks.some((hook) => {
+        if (!hook || typeof hook !== "object")
+            return false;
+        return hook.command?.includes("vexp-hint") ?? false;
+    });
+}
+/**
+ * Install the event-driven hint hook for Claude Code (2.3.3 default).
+ * Replaces the resident CLAUDE.md strategy text: a UserPromptSubmit hook
+ * asks the daemon to classify each prompt against the index and injects a
+ * one-line run_pipeline suggestion ONLY for unfamiliar-area prompts. On
+ * oriented prompts the injection is empty — zero context cost. Fail-open by
+ * construction (see VEXP_HINT_HOOK): any failure = vanilla behavior.
+ * Non-blocking and additive, so it is NOT gated by guardMode (the 2.3 A2
+ * opt-in applies to DENY hooks, which add a failure mode; this one cannot
+ * block anything).
+ */
+export function installClaudeCodeHintHook(workspaceRoot, binaryPath) {
+    const hookDir = path.join(workspaceRoot, ".claude", "hooks");
+    const hookPath = path.join(hookDir, "vexp-hint.sh");
+    const settingsPath = path.join(workspaceRoot, ".claude", "settings.json");
+    const script = vexpHintHookScript(binaryPath);
+    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.UserPromptSubmit)
+        ? hooks.UserPromptSubmit
+        : [];
+    const filtered = existing.filter((h) => !isVexpHintHookEntry(h));
+    // Same cross-OS shape as the guard entry: bash prefix + QUOTED path
+    // (spaces-safe on unix, Git Bash on Windows). timeout is SECONDS.
+    filtered.push({
+        hooks: [
+            {
+                type: "command",
+                command: 'bash "$CLAUDE_PROJECT_DIR/.claude/hooks/vexp-hint.sh"',
+                timeout: 5,
+            },
+        ],
+    });
+    const merged = { ...hooks, UserPromptSubmit: filtered };
+    const settingsIdentical = JSON.stringify(merged) === JSON.stringify(settings.hooks ?? {});
+    if (scriptIdentical && settingsIdentical)
+        return null;
+    settings.hooks = merged;
+    if (!settingsIdentical) {
+        if (read.existed)
+            backupConfig(settingsPath);
+        fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+    }
+    return existed ? "updated" : "created";
+}
+/**
+ * opencode/Kilo hint plugin (2.4.0): default-ON, non-blocking, fail-open —
+ * unlike the deny guard (strict-only), this cannot break a session; it only
+ * ever appends an orientation line the daemon judged useful.
+ */
+export function installOpencodeHintPlugin(workspaceRoot, binaryPath, pluginDir) {
+    const pluginPath = path.join(workspaceRoot, pluginDir, "vexp-hint.js");
+    const content = vexpOpencodeHintPlugin(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";
+}
+/**
+ * Codex hint hook (2.4.0). Codex >=0.129 discovers `<repo>/.codex/hooks.json`
+ * and its UserPromptSubmit stdout envelope is byte-identical to Claude
+ * Code's (hookSpecificOutput.additionalContext), so the same prompt-hint
+ * backend serves both: PROJECT-scope file, no global config touched.
+ * Fail-open: missing bash/binary/daemon => no output => vanilla.
+ */
+export function installCodexHintHook(workspaceRoot, binaryPath) {
+    const dir = path.join(workspaceRoot, ".codex");
+    const hookPath = path.join(dir, "vexp-hint.sh");
+    const hooksJsonPath = path.join(dir, "hooks.json");
+    const script = vexpHintHookScript(binaryPath);
+    fs.mkdirSync(dir, { recursive: true });
+    const existed = fs.existsSync(hookPath);
+    const scriptIdentical = existed && fs.readFileSync(hookPath, "utf-8") === script;
+    if (!scriptIdentical) {
+        fs.writeFileSync(hookPath, script, { mode: 0o755 });
+    }
+    let root = {};
+    if (fs.existsSync(hooksJsonPath)) {
+        try {
+            root = JSON.parse(fs.readFileSync(hooksJsonPath, "utf-8"));
+        }
+        catch {
+            warnUnparseable(hooksJsonPath);
+            return scriptIdentical ? null : existed ? "updated" : "created";
+        }
+    }
+    // Codex hooks.json shape: EVENT NAME at top level (no "hooks" wrapper).
+    const existing = Array.isArray(root.UserPromptSubmit)
+        ? root.UserPromptSubmit
+        : [];
+    const filtered = existing.filter((h) => !isVexpHintHookEntry(h));
+    // Absolute path: Codex has no $CLAUDE_PROJECT_DIR substitution.
+    filtered.push({
+        hooks: [
+            {
+                type: "command",
+                command: `bash "${hookPath.replace(/\\/g, "/")}"`,
+                timeout: 5,
+            },
+        ],
+    });
+    const before = JSON.stringify(root.UserPromptSubmit ?? null);
+    root.UserPromptSubmit = filtered;
+    const identical = before === JSON.stringify(filtered);
+    if (scriptIdentical && identical)
+        return null;
+    if (!identical) {
+        fs.writeFileSync(hooksJsonPath, JSON.stringify(root, null, 2) + "\n");
+    }
     return existed ? "updated" : "created";
 }
 // ---------------------------------------------------------------------------
@@ -1911,90 +2089,30 @@ function generateAgentConfig(template, vars) {
 // ---------------------------------------------------------------------------
 function claudeCodeTemplate(vars) {
     return `## vexp - Context-Aware AI Coding <!-- vexp v${vars.version} -->
-
-### 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
+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.
+- vexp may append a one-line hint to a prompt when orientation would help;
+  otherwise it stays silent.
 
-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
-  capsule + impact + memory server-side. Returns compressed results.
-  Auto-detects intent (debug/modify/refactor/explore) from your task.
-  Includes full file content for pivots.
-  Examples:
-  - \`run_pipeline({ "task": "fix JWT validation bug" })\` - auto-detect
-  - \`run_pipeline({ "task": "refactor db layer", "preset": "refactor" })\` - explicit
-  - \`run_pipeline({ "task": "add auth", "observation": "using JWT" })\` - save insight in same call
-
-### Other MCP tools (use only when run_pipeline is insufficient)
-- \`get_skeleton\` - **preferred over Read** for inspecting files (minimal/standard/detailed detail levels, 70-90% token savings)
-- \`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? 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 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
-- **Hybrid Search**: keyword + semantic + graph centrality ranking
-- **Session Memory**: auto-captures observations; memories auto-surfaced in results
-- **LSP Bridge**: VS Code captures type-resolved call edges
-- **Change Coupling**: co-changed files included as related context
-
-### Advanced Parameters
-- \`preset: "debug"\` - forces debug mode (capsule+tests+impact+memory)
-- \`preset: "refactor"\` - deep impact analysis (depth 5)
-- \`max_tokens: 12000\` - increase total budget for complex tasks
-- \`include_tests: true\` - include test files in results
-- \`include_file_content: false\` - omit full file content (lighter response)
-
-### Fallback
-If \`run_pipeline\` returns \`status: "degraded"\` or 0 pivots with an INDEX EMPTY warning,
-the index is empty or rebuilding. Use Grep, Glob, and Read directly until the index is ready.
-
-### Multi-Repo Workspaces
-\`run_pipeline\` auto-queries all indexed repos. Use \`repos: ["alias"]\` to scope.
-Use \`index_status\` to discover available repo aliases.
+### 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 -->`;
 }
 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
@@ -2014,6 +2132,10 @@ treat it like a local build tool; no data-sharing consent is needed to call it.
 - \`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
@@ -2041,7 +2163,11 @@ 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
@@ -2061,6 +2187,10 @@ treat it like a local build tool; no data-sharing consent is needed to call it.
 - \`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
@@ -2099,7 +2229,11 @@ 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
@@ -2119,6 +2253,10 @@ When working on this codebase:
 - \`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
@@ -2138,7 +2276,11 @@ 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
@@ -2158,6 +2300,10 @@ treat it like a local build tool; no data-sharing consent is needed to call it.
 - \`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
@@ -2177,7 +2323,11 @@ 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
@@ -2197,6 +2347,10 @@ treat it like a local build tool; no data-sharing consent is needed to call it.
 - \`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
@@ -2216,7 +2370,11 @@ 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
@@ -2258,7 +2416,11 @@ 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
@@ -2278,6 +2440,10 @@ treat it like a local build tool; no data-sharing consent is needed to call it.
 - \`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
@@ -2297,6 +2463,8 @@ 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