vexp-cli 2.2.1 → 2.2.3

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 } from "./hook-template.js";
+import { VEXP_GUARD_HOOK, VEXP_OPENCODE_GUARD, VEXP_CURSOR_GUARD } from "./hook-template.js";
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -345,10 +345,47 @@ export function configureAgents(workspaceRoot, binaryPath, version, agentFilter,
             const wrote = configureKiloMcp(workspaceRoot, binaryPath, mcpServerPath);
             if (wrote)
                 mcpConfigs.push(wrote);
+            // 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) {
+                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)));
+        }
+        // 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) {
+                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"));
         }
-        // Opencode: install the guard plugin that blocks grep/glob while the daemon
-        // is up (opencode's analogue of the Claude Code PreToolUse hook).
+        // Opencode: MCP lives under the `mcp` key in opencode.json(c) — opencode
+        // carries no `mcpConfigFile`, so without this call the generic writer above
+        // skips it and setup registers no tool at all. Plus the guard plugin that
+        // blocks grep/glob while the daemon is up (opencode's analogue of the
+        // Claude Code PreToolUse hook) — which is only safe once MCP is registered.
         if (detector.agent === "Opencode") {
+            const wroteMcp = configureOpencodeMcp(workspaceRoot, binaryPath, mcpServerPath);
+            if (wroteMcp)
+                mcpConfigs.push(wroteMcp);
             const pluginResult = installOpencodePlugin(workspaceRoot);
             if (pluginResult) {
                 results.push({
@@ -376,6 +413,60 @@ export function configureAgents(workspaceRoot, binaryPath, version, agentFilter,
 export function getAgentList() {
     return [...AGENT_DETECTORS];
 }
+/** Fold a name to its comparable form: case, spaces, dots and dashes carry no
+ *  meaning here ("claude-code", "Claude Code" and "claudecode" are one agent). */
+function foldAgentName(s) {
+    return s.toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+/**
+ * Canonicalize a name given to `--agents`, or null if it names no agent.
+ *
+ * `configureSelectedAgents` matches with `Array.includes` on the exact string,
+ * so "opencode" silently configured nothing while "Opencode" worked — nobody
+ * can be expected to know the capitalization, and the failure was invisible.
+ */
+export function resolveAgentName(input) {
+    const want = foldAgentName(input);
+    if (!want)
+        return null;
+    return AGENT_DETECTORS.find((d) => foldAgentName(d.agent) === want)?.agent ?? null;
+}
+/** Levenshtein distance, for "did you mean" on an unknown --agents name. */
+function editDistance(a, b) {
+    const prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+    const cur = new Array(b.length + 1).fill(0);
+    for (let i = 1; i <= a.length; i++) {
+        cur[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            cur[j] = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        }
+        prev.splice(0, prev.length, ...cur);
+    }
+    return prev[b.length];
+}
+/**
+ * The known agent an unknown name most likely meant, or null when nothing is
+ * close enough to be worth suggesting. Substring hits win (a bare "copilot"
+ * means "GitHub Copilot"); otherwise allow a couple of typos.
+ */
+export function suggestAgentName(input) {
+    const want = foldAgentName(input);
+    if (!want)
+        return null;
+    const contained = AGENT_DETECTORS.find((d) => {
+        const f = foldAgentName(d.agent);
+        return f.includes(want) || want.includes(f);
+    });
+    if (contained)
+        return contained.agent;
+    let best = null;
+    for (const d of AGENT_DETECTORS) {
+        const dist = editDistance(want, foldAgentName(d.agent));
+        if (!best || dist < best.d)
+            best = { name: d.agent, d: dist };
+    }
+    return best && best.d <= 3 ? best.name : null;
+}
 /**
  * Configure specific agents selected by the user.
  * Unlike configureAgents which auto-detects, this forces configuration
@@ -469,8 +560,24 @@ export function configureSelectedAgents(workspaceRoot, binaryPath, version, sele
                 mcpConfigs.push(".zed/settings.json");
         }
         if (detector.agent === "Opencode") {
+            const wrote = configureOpencodeMcp(workspaceRoot, binaryPath, mcpServerPath);
+            if (wrote)
+                mcpConfigs.push(wrote);
             installOpencodePlugin(workspaceRoot);
         }
+        if (detector.agent === "Cursor") {
+            installCursorHook(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
+        // picking Kilo explicitly used to write the rules file and NOTHING else — an
+        // agent told "always call run_pipeline" while the tool was never registered.
+        if (detector.agent === "Kilo Code") {
+            const wrote = configureKiloMcp(workspaceRoot, binaryPath, mcpServerPath);
+            if (wrote)
+                mcpConfigs.push(wrote);
+            installKiloPlugin(workspaceRoot);
+        }
         results.push({ agent: detector.agent, configFile: detector.configFile, content, alreadyExists, action });
     }
     return { agents: results, mcpConfigs };
@@ -1070,14 +1177,93 @@ export function writeVsCodeMcpConfig(p, binaryPath, mcpServerPath, workspaceRoot
  * an existing file is backed up before rewrite. Returns the workspace-relative
  * path written, or null on a no-op / unparseable file.
  */
-export function configureKiloMcp(workspaceRoot, binaryPath, mcpServerPath) {
+/**
+ * The kilo.jsonc that Kilo will actually read: `.kilo/kilo.jsonc` wins over a
+ * root `kilo.jsonc` when both exist, and a fresh setup gets the cleaner `.kilo/`
+ * location. Shared by the MCP writer and the guard-plugin installer so the two
+ * can never disagree about which file is live.
+ */
+export function kiloConfigTarget(workspaceRoot) {
     const dotKilo = path.join(workspaceRoot, ".kilo", "kilo.jsonc");
     const rootKilo = path.join(workspaceRoot, "kilo.jsonc");
-    const target = fs.existsSync(dotKilo)
+    return fs.existsSync(dotKilo)
         ? dotKilo
         : fs.existsSync(rootKilo)
             ? rootKilo
-            : dotKilo; // fresh setup → the recommended cleaner location
+            : dotKilo;
+}
+/**
+ * The opencode config file that opencode will actually read for `mcp`:
+ * `opencode.jsonc` wins over `opencode.json` when both exist (jsonc is the
+ * variant users keep when they want comments, and it is the one they edit),
+ * and a fresh setup gets plain `opencode.json` — opencode's documented default.
+ * Project-scope only: we never touch the machine-global
+ * `~/.config/opencode/opencode.json`, because a per-workspace VEXP_WORKSPACE pin
+ * in a global file would mis-target every other project on the machine.
+ */
+export function opencodeConfigTarget(workspaceRoot) {
+    const jsonc = path.join(workspaceRoot, "opencode.jsonc");
+    const json = path.join(workspaceRoot, "opencode.json");
+    return fs.existsSync(jsonc) ? jsonc : json;
+}
+/**
+ * Opencode MCP setup. Opencode reads MCP servers from the top-level `mcp` key
+ * of `opencode.json` / `opencode.jsonc` — the same shape Kilo Code uses, because
+ * Kilo v7 vendors opencode wholesale: `{type:"local", command:[…], enabled:true}`.
+ *
+ * Until this existed, picking Opencode in `vexp setup` wrote AGENTS.md and the
+ * guard plugin and NOTHING else — the worst possible end state, because the
+ * guard blocks grep/glob whenever the daemon is healthy while `run_pipeline` was
+ * never registered: the agent lost search and gained no replacement. Reported by
+ * an AppSumo user who had to add the `mcp` block by hand.
+ *
+ * Other `mcp` entries and unrelated top-level keys are preserved; an existing
+ * file is backed up before rewrite. Returns the workspace-relative path written,
+ * or null on a no-op / unparseable file.
+ */
+export function configureOpencodeMcp(workspaceRoot, binaryPath, mcpServerPath) {
+    const target = opencodeConfigTarget(workspaceRoot);
+    const read = readJsonConfigSafe(target);
+    if (!read.ok) {
+        warnUnparseable(target);
+        return null;
+    }
+    const cfg = read.data;
+    const useNode = mcpServerPath && fs.existsSync(mcpServerPath);
+    const command = useNode ? ["node", mcpServerPath] : [binaryPath, "mcp"];
+    const env = { VEXP_WORKSPACE: workspaceRoot };
+    const mcp = cfg.mcp ?? {};
+    const prev = mcp["vexp"];
+    const envMatches = JSON.stringify(prev?.["env"]) === JSON.stringify(env);
+    const identical = prev?.["type"] === "local" &&
+        prev?.["enabled"] === true &&
+        Array.isArray(prev?.["command"]) &&
+        JSON.stringify(prev["command"]) === JSON.stringify(command) &&
+        envMatches;
+    if (identical)
+        return null;
+    // A working entry is already here — either another vexp install, or the user's
+    // own hand-written block (this bug made several people write one). Don't fight
+    // it: only the install path may differ, and `envMatches` still gates on the
+    // VEXP_WORKSPACE pin so a moved project is repinned normally.
+    if (envMatches && prev?.["enabled"] === true && vexpEntryStillResolves(prev))
+        return null;
+    mcp["vexp"] = { type: "local", command, env, enabled: true };
+    cfg.mcp = mcp;
+    // `$schema` first if opencode's own key is absent — a fresh file we author
+    // should look like the one opencode's docs tell users to write.
+    if (cfg.$schema === undefined) {
+        cfg.$schema = "https://opencode.ai/config.json";
+    }
+    if (read.existed)
+        backupConfig(target);
+    // A .jsonc target loses its comments here (we reserialize parsed JSON), which
+    // is why the pre-write backup is not optional for this writer.
+    fs.writeFileSync(target, JSON.stringify(cfg, null, 2), "utf-8");
+    return path.relative(workspaceRoot, target);
+}
+export function configureKiloMcp(workspaceRoot, binaryPath, mcpServerPath) {
+    const target = kiloConfigTarget(workspaceRoot);
     const read = readJsonConfigSafe(target);
     if (!read.ok) {
         warnUnparseable(target);
@@ -1349,19 +1535,155 @@ export function installClaudeCodeHook(workspaceRoot) {
  * startup — no config-file merge required). Returns the action taken, or null
  * when the file is already byte-identical.
  */
-export function installOpencodePlugin(workspaceRoot) {
-    const pluginDir = path.join(workspaceRoot, ".opencode", "plugins");
-    const pluginPath = path.join(pluginDir, "vexp-guard.js");
-    fs.mkdirSync(pluginDir, { recursive: true });
+function writeGuardScript(scriptPath, content) {
+    const pluginPath = scriptPath;
+    fs.mkdirSync(path.dirname(pluginPath), { recursive: true });
     const existed = fs.existsSync(pluginPath);
     if (existed) {
         const current = fs.readFileSync(pluginPath, "utf-8");
-        if (current === VEXP_OPENCODE_GUARD)
+        if (current === content)
             return null; // identical - skip
+        // Content differs: either an older vexp guard, or a copy the user tuned by
+        // hand. We refresh either way — refusing to touch a hand-edited plugin would
+        // freeze that user on a stale guard forever — but their version stays
+        // recoverable at vexp-guard.js.vexp-bak instead of being silently discarded.
+        backupConfig(pluginPath);
     }
-    fs.writeFileSync(pluginPath, VEXP_OPENCODE_GUARD, "utf-8");
+    fs.writeFileSync(pluginPath, content, "utf-8");
     return existed ? "updated" : "created";
 }
+export function installOpencodePlugin(workspaceRoot) {
+    return writeGuardScript(path.join(workspaceRoot, ".opencode", "plugins", "vexp-guard.js"), VEXP_OPENCODE_GUARD);
+}
+/**
+ * Cursor enforcement — `preToolUse` hook with matcher `Grep`.
+ *
+ * Cursor is the only VS Code fork where this is possible: Windsurf's hooks are
+ * action-category based (twelve fixed events, no matcher, no tool names) and
+ * expose NO search event at all, so there is nothing there to redirect. Cursor
+ * exposes `Grep` as a matchable tool and feeds `agent_message` back to the model,
+ * which is the whole mechanism.
+ *
+ * Scope of the claim, deliberately narrow: this covers TEXT search. Cursor's
+ * native semantic codebase search has no documented tool identifier, so it is not
+ * hookable and not covered. Do not describe this as "Cursor is enforced".
+ *
+ * `command` is `node`, not a shell script: Cursor documents no PowerShell variant
+ * and never says which shell runs `command` on Windows. A bash guard would repeat
+ * the Claude Code hook's Windows bug (silently enforced nothing for releases).
+ * The path is project-root-relative because Cursor runs PROJECT hooks from the
+ * project root — `./hooks/x` there would resolve to `<project>/hooks/x`.
+ *
+ * `failClosed` is left at its default (false): a crashing guard must let the
+ * agent work, not lock it out.
+ */
+export function installCursorHook(workspaceRoot) {
+    const rel = path.join(".cursor", "hooks", "vexp-guard.js");
+    const hookPath = path.join(workspaceRoot, rel);
+    const hook = writeGuardScript(hookPath, VEXP_CURSOR_GUARD);
+    const cfgPath = path.join(workspaceRoot, ".cursor", "hooks.json");
+    const command = `node ${rel.split(path.sep).join("/")}`;
+    const read = readJsonConfigSafe(cfgPath);
+    if (!read.ok) {
+        warnUnparseable(cfgPath);
+        return { hook, registered: false };
+    }
+    const cfg = read.data;
+    const hooks = cfg.hooks ?? {};
+    const preToolUse = Array.isArray(hooks.preToolUse) ? [...hooks.preToolUse] : [];
+    // Idempotent by COMMAND, not by array position: re-running setup must not
+    // append a second copy, and a user's own preToolUse hooks must survive.
+    const ours = (e) => !!e && typeof e === "object" && e.command === command;
+    const existing = preToolUse.findIndex(ours);
+    const entry = { command, matcher: "Grep" };
+    if (existing >= 0 && JSON.stringify(preToolUse[existing]) === JSON.stringify(entry)) {
+        return { hook, registered: false }; // already exactly right
+    }
+    if (existing >= 0)
+        preToolUse[existing] = 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 { hook, registered: true };
+}
+/**
+ * Kilo Code enforcement — the same plugin, because Kilo v7 IS opencode: the
+ * rewrite vendors it wholesale (the loader lives at packages/opencode/src/ inside
+ * Kilo-Org/kilocode), so `tool.execute.before`, the `input.tool` ids and the
+ * grep/glob arg schemas are the same code, not merely a similar API.
+ *
+ * Loading is by auto-discovery: the loader globs `{plugin,plugins}/*.{ts,js}`
+ * with cwd = the directory of the kilo.jsonc it read, and every match is
+ * registered at startup with no config entry. So `.kilo/plugins/vexp-guard.js`
+ * is picked up for free — and we prefer that to an explicit `plugin` array entry
+ * because it leaves the user's config untouched.
+ *
+ * The one case auto-discovery misses: a project whose config is the ROOT
+ * `kilo.jsonc`, where cwd is the repo root and the scanned directory would be
+ * `<root>/plugins/` — we will not create a top-level `plugins/` dir in someone's
+ * repo just to be found. There we keep the file in `.kilo/plugins/` and register
+ * it explicitly, with the path relative to the config file (the loader resolves
+ * path specs against the declaring config's own directory, NOT the project root).
+ *
+ * The glob is non-recursive, so the file must sit flat in that directory.
+ *
+ * NOTE: `KILO_PURE=1` skips all external plugins. A CI run with it set gets no
+ * guard — correctly so, but it means "the guard is installed" is not the same
+ * claim as "the guard ran".
+ */
+export function installKiloPlugin(workspaceRoot) {
+    const pluginPath = path.join(workspaceRoot, ".kilo", "plugins", "vexp-guard.js");
+    const plugin = writeGuardScript(pluginPath, VEXP_OPENCODE_GUARD);
+    // `.kilo/kilo.jsonc` (the common case) → auto-discovery already covers us.
+    const target = kiloConfigTarget(workspaceRoot);
+    if (path.dirname(target) !== workspaceRoot)
+        return { plugin, registered: false };
+    const rel = "./" + path.relative(workspaceRoot, pluginPath).split(path.sep).join("/");
+    const read = readJsonConfigSafe(target);
+    if (!read.ok) {
+        warnUnparseable(target);
+        return { plugin, registered: false };
+    }
+    const cfg = read.data;
+    const list = Array.isArray(cfg.plugin) ? cfg.plugin : [];
+    if (list.includes(rel))
+        return { plugin, registered: false }; // already declared
+    cfg.plugin = [...list, rel];
+    if (read.existed)
+        backupConfig(target);
+    fs.writeFileSync(target, JSON.stringify(cfg, null, 2), "utf-8");
+    return { plugin, registered: true };
+}
+/**
+ * The single highest-leverage instruction we ship, and for a long time the one
+ * most agents never saw.
+ *
+ * vexp retrieval is identifier/path-first: FTS supplies the candidate pool and
+ * the semantic layer only RE-RANKS it, so a symbol that no query token reaches
+ * never enters the running at all. A task written as prose ("why does the proxy
+ * fail?") therefore ranks far worse than the same task anchored on the symbols
+ * and paths it is actually about — the difference between a useful pivot set and
+ * "the vexp result wasn't relevant".
+ *
+ * This shipped only in the Claude Code and Cursor templates, while the AGENTS.md
+ * example (`"task": "fix auth bug"`) actively modelled the weak mode — so two
+ * independent field reports ("the index seems not very useful") came from users
+ * whose instructions never told them the one thing that makes retrieval land.
+ * 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) {
     switch (template) {
         case "claude-code":
@@ -1403,6 +1725,12 @@ 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.
+
 ### Primary Tool
 - \`run_pipeline\` - **USE THIS FOR EVERYTHING**. Single call that runs
   capsule + impact + memory server-side. Returns compressed results.
@@ -1418,6 +1746,8 @@ Only use Read when you need exact raw content to edit a specific line.
 - \`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")\` - 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
@@ -1438,9 +1768,6 @@ Only use Read when you need exact raw content to edit a specific line.
 - **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
-- **Query tips**: include real identifiers (ClassName, function_name) or file paths
-  in the task for precise matches - pure natural-language phrasing falls back to
-  text ranking and is less reliable
 
 ### Advanced Parameters
 - \`preset: "debug"\` - forces debug mode (capsule+tests+impact+memory)
@@ -1471,19 +1798,19 @@ vexp returns pre-indexed, graph-ranked context in a single call.
 
 ### 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 auth bug" })\`
+  Auto-detects intent. Includes file content. Example: \`run_pipeline({ "task": "fix JWT expiry in AuthService.validateToken" })\`
 - \`get_skeleton\` - compact file structure
 - \`index_status\` - indexing status
 - \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
 
+${QUERY_SHAPE}
+
 ### Agentic search
 - Do NOT use built-in file search, grep, or codebase indexing - always call \`run_pipeline\` first
 - If you spawn sub-agents or background tasks, pass them the context from \`run_pipeline\`
   rather than letting them search the codebase independently
 
 ### Tips
-- Include real identifiers (class/function names) or file paths in the task - literal
-  matches rank best; pure natural-language phrasing falls back to text ranking
 - Add \`include_tests: true\` when debugging
 - Use \`preset: "refactor"\` for deep impact analysis
 
@@ -1511,11 +1838,13 @@ vexp returns pre-indexed, graph-ranked context in a single call.
 
 ### 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 auth bug" })\`
+  Auto-detects intent. Includes file content. Example: \`run_pipeline({ "task": "fix JWT expiry in AuthService.validateToken" })\`
 - \`get_skeleton\` - compact file structure
 - \`index_status\` - indexing status
 - \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
 
+${QUERY_SHAPE}
+
 ### Agentic search
 - Do NOT use built-in file search, grep, or codebase indexing - always call \`run_pipeline\` first
 - If you spawn sub-agents or background tasks, pass them the context from \`run_pipeline\`
@@ -1560,11 +1889,13 @@ When working on this codebase:
 
 ### Available MCP tools
 - \`run_pipeline\` - **PRIMARY TOOL**. Runs capsule + impact + memory in 1 call.
-  Example: \`run_pipeline({ "task": "fix auth bug" })\`
+  Example: \`run_pipeline({ "task": "fix JWT expiry in AuthService.validateToken" })\`
 - \`get_skeleton\` - token-efficient file structure
 - \`index_status\` - indexing status
 - \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
 
+${QUERY_SHAPE}
+
 ### Agentic search
 - Do NOT use built-in file search, grep, or codebase indexing - always call \`run_pipeline\` first
 - If you spawn sub-agents or background tasks, pass them the context from \`run_pipeline\`
@@ -1590,11 +1921,13 @@ vexp returns pre-indexed, graph-ranked context in a single call.
 
 ### 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 auth bug" })\`
+  Auto-detects intent. Includes file content. Example: \`run_pipeline({ "task": "fix JWT expiry in AuthService.validateToken" })\`
 - \`get_skeleton\` - compact file structure
 - \`index_status\` - indexing status
 - \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
 
+${QUERY_SHAPE}
+
 ### Agentic search
 - Do NOT use built-in file search, grep, or codebase indexing - always call \`run_pipeline\` first
 - If you spawn sub-agents or background tasks, pass them the context from \`run_pipeline\`
@@ -1620,11 +1953,13 @@ vexp returns pre-indexed, graph-ranked context in a single call.
 
 ### Available MCP tools
 - \`run_pipeline\` - **PRIMARY TOOL**. Runs capsule + impact + memory in 1 call.
-  Example: \`run_pipeline({ "task": "fix auth bug" })\`
+  Example: \`run_pipeline({ "task": "fix JWT expiry in AuthService.validateToken" })\`
 - \`get_skeleton\` - compact file structure
 - \`index_status\` - indexing status
 - \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
 
+${QUERY_SHAPE}
+
 ### Agentic search
 - Do NOT use built-in file search, grep, or codebase indexing - always call \`run_pipeline\` first
 - If you spawn sub-agents or background tasks, pass them the context from \`run_pipeline\`
@@ -1650,13 +1985,20 @@ vexp returns pre-indexed, graph-ranked context in a single call.
 
 ### 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 auth bug" })\`
+  Auto-detects intent. Includes file content. Example: \`run_pipeline({ "task": "fix JWT expiry in AuthService.validateToken" })\`
 - \`get_skeleton\` - compact file structure
 - \`index_status\` - indexing status
 - \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
 
+${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.
+- 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.
 - If you spawn sub-agents or background tasks, pass them the context from \`run_pipeline\`
   rather than letting them search the codebase independently
 
@@ -1680,11 +2022,13 @@ vexp returns pre-indexed, graph-ranked context in a single call.
 
 ## Available vexp tools
 - \`run_pipeline\` - **PRIMARY TOOL**. Runs capsule + impact + memory in 1 call.
-  Example: \`run_pipeline({ "task": "fix auth bug" })\`
+  Example: \`run_pipeline({ "task": "fix JWT expiry in AuthService.validateToken" })\`
 - \`get_skeleton\` - compact file structure
 - \`index_status\` - indexing status
 - \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
 
+${QUERY_SHAPE}
+
 ## Agentic search
 - Do NOT use built-in file search, grep, or codebase indexing - always call \`run_pipeline\` first
 - If you spawn sub-agents or background tasks, pass them the context from \`run_pipeline\`
@@ -1698,32 +2042,65 @@ Intent auto-detection, hybrid ranking, session memory, auto-expanding budget.
 <!-- /vexp -->`;
 }
 function genericTemplate(vars) {
-    return `## vexp <!-- vexp v${vars.version} -->
+    return `## vexp - Context-Aware AI Coding <!-- 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.
+### 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.
+
+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\` 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("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
 
-### Available MCP tools
-- \`run_pipeline\` - **PRIMARY TOOL**. Runs capsule + impact + memory in 1 call.
-  Example: \`run_pipeline({ "task": "fix auth bug" })\`
-- \`get_skeleton\` - compact file structure
-- \`index_status\` - indexing status
-- \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
+### 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
 
-### Agentic search
-- Do NOT use built-in file search, grep, or codebase indexing - always call \`run_pipeline\` first
-- If you spawn sub-agents or background tasks, pass them the context from \`run_pipeline\`
-  rather than letting them search the codebase independently
+### 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
-Intent auto-detection, hybrid ranking, session memory, auto-expanding budget.
+### Smart features (automatic - no action needed)
+Intent detection, hybrid keyword+semantic+graph ranking, session memory,
+change coupling, auto-expanding budget.
 
-### Multi-Repo
+### Multi-repo
 \`run_pipeline\` auto-queries all indexed repos. Use \`repos: ["alias"]\` to scope. Run \`index_status\` to see aliases.
 <!-- /vexp -->`;
 }