vexp-cli 2.0.19 → 2.0.21

package/dist/agent-config.js

@@ -16,7 +16,7 @@ import { VEXP_GUARD_HOOK } from "./hook-template.js";
 // ---------------------------------------------------------------------------
 const VEXP_MARKER_RE = /<!-- vexp(?:\s+v[\d.]+)? -->/;
 const VEXP_MARKER_END = "<!-- /vexp -->";
-// Matches LEGACY vexp entry keys ONLY — "vexp-mcp", "vexp-core", "vexp-stdio",
+// Matches LEGACY vexp entry keys ONLY - "vexp-mcp", "vexp-core", "vexp-stdio",
 // "vexp_old", etc. Explicitly excludes the canonical "vexp" key so that idempotency
 // checks (command+args+env identical?) work: we only remove siblings, not the entry
 // we're about to upsert.
@@ -73,10 +73,10 @@ function logRemoval(removed) {
     if (removed.length === 0)
         return;
     for (const entry of removed) {
-        process.stdout.write(`  · Removed legacy entry: ${entry}\n`);
+        process.stdout.write(`  - Removed legacy entry: ${entry}\n`);
     }
 }
-// All vexp MCP tools (all read-only — safe to pre-approve).
+// All vexp MCP tools (all read-only - safe to pre-approve).
 const VEXP_TOOLS = [
     "run_pipeline",
     "get_context_capsule",
@@ -92,7 +92,7 @@ const VEXP_TOOLS = [
     "get_token_savings",
 ];
 // ---------------------------------------------------------------------------
-// Agent detectors — mirrors VS Code extension's AGENT_DETECTORS
+// Agent detectors - mirrors VS Code extension's AGENT_DETECTORS
 // ---------------------------------------------------------------------------
 const AGENT_DETECTORS = [
     {
@@ -396,8 +396,104 @@ export function configureSelectedAgents(workspaceRoot, binaryPath, version, sele
     return { agents: results, mcpConfigs };
 }
 // ---------------------------------------------------------------------------
-// File helpers — ported from agent-auto-config.ts
+// File helpers - ported from agent-auto-config.ts
 // ---------------------------------------------------------------------------
+/**
+ * Parse JSON that may use JSONC syntax - `//` and slash-star comments and
+ * trailing commas. VS Code mcp.json and Zed settings.json are JSONC, so a raw
+ * JSON.parse throws on perfectly valid user files. Strips comments and trailing
+ * commas (preserving string contents) before parsing.
+ */
+export function parseJsonc(text) {
+    let out = "";
+    let inString = false;
+    let inLineComment = false;
+    let inBlockComment = false;
+    for (let i = 0; i < text.length; i++) {
+        const c = text[i];
+        const next = text[i + 1];
+        if (inLineComment) {
+            if (c === "\n") {
+                inLineComment = false;
+                out += c;
+            }
+            continue;
+        }
+        if (inBlockComment) {
+            if (c === "*" && next === "/") {
+                inBlockComment = false;
+                i++;
+            }
+            continue;
+        }
+        if (inString) {
+            out += c;
+            if (c === "\\") {
+                out += next ?? "";
+                i++;
+            }
+            else if (c === '"')
+                inString = false;
+            continue;
+        }
+        if (c === '"') {
+            inString = true;
+            out += c;
+            continue;
+        }
+        if (c === "/" && next === "/") {
+            inLineComment = true;
+            i++;
+            continue;
+        }
+        if (c === "/" && next === "*") {
+            inBlockComment = true;
+            i++;
+            continue;
+        }
+        out += c;
+    }
+    out = out.replace(/,(\s*[}\]])/g, "$1");
+    return JSON.parse(out);
+}
+/**
+ * Read a JSON/JSONC config file without ever risking user data. When the file
+ * exists but cannot be parsed (even as JSONC), returns ok:false so callers skip
+ * the write instead of silently clobbering the user's config.
+ */
+export function readJsonConfigSafe(filePath) {
+    if (!fs.existsSync(filePath))
+        return { data: {}, ok: true, existed: false };
+    let raw;
+    try {
+        raw = fs.readFileSync(filePath, "utf-8");
+    }
+    catch {
+        return { data: {}, ok: false, existed: true };
+    }
+    if (raw.trim() === "")
+        return { data: {}, ok: true, existed: true };
+    try {
+        const parsed = parseJsonc(raw);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            return { data: parsed, ok: true, existed: true };
+        }
+    }
+    catch { /* fall through to ok:false */ }
+    return { data: {}, ok: false, existed: true };
+}
+/** Copy an existing config to <file>.vexp-bak before overwriting it. */
+function backupConfig(filePath) {
+    try {
+        if (fs.existsSync(filePath))
+            fs.copyFileSync(filePath, `${filePath}.vexp-bak`);
+    }
+    catch { /* non-fatal */ }
+}
+/** Warn that we refused to touch an unparseable config file. */
+function warnUnparseable(filePath) {
+    process.stderr.write(`  [!] ${filePath} could not be parsed - leaving it untouched. Fix the file or add vexp manually, then re-run setup.\n`);
+}
 function appendOrCreate(filePath, content, version) {
     if (!fs.existsSync(filePath)) {
         fs.mkdirSync(path.dirname(filePath), { recursive: true });
@@ -422,7 +518,7 @@ function appendOrCreate(filePath, content, version) {
     if (endIdx !== -1) {
         const existingSection = existing.substring(startIdx, endIdx + VEXP_MARKER_END.length);
         if (existingSection === content)
-            return "skipped"; // truly identical → no write
+            return "skipped"; // truly identical -> no write
         const before = existing.substring(0, startIdx);
         const after = existing.substring(endIdx + VEXP_MARKER_END.length);
         fs.writeFileSync(filePath, before + content + after, "utf-8");
@@ -433,16 +529,13 @@ function appendOrCreate(filePath, content, version) {
     }
     return "updated";
 }
-function mergeJsonConfig(filePath, mergePayload, version) {
-    let existing = {};
-    if (fs.existsSync(filePath)) {
-        try {
-            existing = JSON.parse(fs.readFileSync(filePath, "utf-8"));
-        }
-        catch {
-            // Malformed JSON: overwrite
-        }
+export function mergeJsonConfig(filePath, mergePayload, version) {
+    const read = readJsonConfigSafe(filePath);
+    if (!read.ok) {
+        warnUnparseable(filePath);
+        return "skipped";
     }
+    const existing = read.data;
     // Build the merged result first, then compare to avoid unnecessary writes.
     const merged = { ...existing };
     for (const [key, value] of Object.entries(mergePayload)) {
@@ -461,32 +554,31 @@ function mergeJsonConfig(filePath, mergePayload, version) {
     }
     delete merged.__vexp;
     merged.__vexp_version = version;
-    // Compare serialized output — skip if truly identical
+    // Compare serialized output - skip if truly identical
     const mergedStr = JSON.stringify(merged, null, 2);
     const existingStr = JSON.stringify(existing, null, 2);
     if (mergedStr === existingStr)
         return "skipped";
     fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    if (read.existed)
+        backupConfig(filePath);
     fs.writeFileSync(filePath, mergedStr, "utf-8");
     return "merged";
 }
 // ---------------------------------------------------------------------------
-// MCP config writers — adapted for Rust binary path
+// MCP config writers - adapted for Rust binary path
 // ---------------------------------------------------------------------------
 /**
  * Write MCP config JSON for agents that use mcpServers format (Cursor, Windsurf).
  * Returns true if a new entry was written.
  */
-function writeMcpConfig(mcpConfigPath, binaryPath, alwaysAllow, mcpServerPath, workspaceRoot) {
-    let existing = {};
-    if (fs.existsSync(mcpConfigPath)) {
-        try {
-            existing = JSON.parse(fs.readFileSync(mcpConfigPath, "utf-8"));
-        }
-        catch {
-            // Malformed JSON: overwrite
-        }
+export function writeMcpConfig(mcpConfigPath, binaryPath, alwaysAllow, mcpServerPath, workspaceRoot) {
+    const read = readJsonConfigSafe(mcpConfigPath);
+    if (!read.ok) {
+        warnUnparseable(mcpConfigPath);
+        return false;
     }
+    const existing = read.data;
     const useNode = mcpServerPath && fs.existsSync(mcpServerPath);
     const targetCmd = useNode ? "node" : binaryPath;
     const targetArgs = useNode ? [mcpServerPath] : ["mcp"];
@@ -517,6 +609,8 @@ function writeMcpConfig(mcpConfigPath, binaryPath, alwaysAllow, mcpServerPath, w
     };
     existing.mcpServers = servers;
     fs.mkdirSync(path.dirname(mcpConfigPath), { recursive: true });
+    if (read.existed)
+        backupConfig(mcpConfigPath);
     fs.writeFileSync(mcpConfigPath, JSON.stringify(existing, null, 2), "utf-8");
     return true;
 }
@@ -561,49 +655,124 @@ function readMcpPort(workspaceRoot) {
     }
     return DEFAULT_PORT;
 }
+// Marker placed inside a vexp-generated [mcp_servers.vexp] section so we can
+// tell OUR config apart from a config the user hand-wrote. Must stay in sync
+// with packages/vexp-vscode/src/providers/agent-auto-config.ts.
+const CODEX_MANAGED_MARKER = "# vexp-managed";
+/** Quote a value as a TOML literal string (single quotes, no escaping) so
+ *  Windows paths work verbatim. Falls back to a basic escaped string if the
+ *  value contains a single quote. */
+function tomlString(value) {
+    if (!value.includes("'"))
+        return `'${value}'`;
+    return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+/** Extract the existing canonical [mcp_servers.vexp] block (incl. subsections). */
+function extractCodexVexpSection(content) {
+    const m = content.match(CANONICAL_VEXP_TOML_SECTION_RE);
+    return m ? m.join("\n") : "";
+}
+/** True when the existing [mcp_servers.vexp] section was written by the user
+ *  (not by vexp) and must NOT be overwritten. */
+function isUserManagedCodexSection(section) {
+    if (!section)
+        return false;
+    if (section.includes(CODEX_MANAGED_MARKER))
+        return false; // ours
+    if (/^\s*command\s*=/m.test(section))
+        return true; // hand-written direct config
+    const localUrl = /^\s*url\s*=\s*"https?:\/\/127\.0\.0\.1[:/]/m.test(section);
+    const anyUrl = /^\s*url\s*=/m.test(section);
+    if (anyUrl && !localUrl)
+        return true; // points elsewhere
+    return false;
+}
+/** Build the canonical [mcp_servers.vexp] section for the chosen transport.
+ *  Returns null for `direct` when no usable core binary is available. */
+function buildCodexSection(opts) {
+    if (opts.transport === "direct") {
+        if (!opts.coreBinaryPath)
+            return null;
+        const lines = [
+            "",
+            "[mcp_servers.vexp]",
+            `${CODEX_MANAGED_MARKER}: direct transport (set VEXP_CODEX_TRANSPORT=http for the HTTP supervisor)`,
+            `command = ${tomlString(opts.coreBinaryPath)}`,
+            `args = ["mcp"]`,
+        ];
+        if (opts.workspaceRoot)
+            lines.push(`cwd = ${tomlString(opts.workspaceRoot)}`);
+        lines.push("tool_timeout_sec = 120", "", "[mcp_servers.vexp.env]");
+        if (opts.workspaceRoot)
+            lines.push(`VEXP_WORKSPACE = ${tomlString(opts.workspaceRoot)}`);
+        if (opts.home)
+            lines.push(`VEXP_HOME = ${tomlString(opts.home)}`);
+        lines.push("");
+        return lines.join("\n");
+    }
+    const wsHash = opts.workspaceRoot ? workspaceHash(opts.workspaceRoot) : "";
+    const urlPath = wsHash ? `/ws/${wsHash}/mcp` : "/mcp";
+    const desiredUrl = `http://127.0.0.1:${opts.mcpPort}${urlPath}`;
+    return `\n[mcp_servers.vexp]\n${CODEX_MANAGED_MARKER}: http transport (set VEXP_CODEX_TRANSPORT=direct for stdio)\nurl = "${desiredUrl}"\ntool_timeout_sec = 120\n\n[mcp_servers.vexp.http_headers]\nAuthorization = "Bearer ${opts.token}"\n`;
+}
 /**
  * Configure MCP in ~/.codex/config.toml (global).
  * Codex only reads the global config, not project-level .codex/config.toml.
- * Uses HTTP transport with bearer token so Codex shows "Auth: BearerToken"
- * instead of "Auth: Unsupported" (which is hardcoded for stdio servers).
- * Uses TOML format with [mcp_servers.<name>] sections.
+ *
+ * Default transport is `direct` (stdio: `vexp-core mcp`), which works with AND
+ * without VS Code/daemon: `vexp-core mcp` auto-proxies to a running daemon when
+ * reachable and otherwise runs an embedded in-process index. Override with the
+ * VEXP_CODEX_TRANSPORT env var ("direct" | "http").
+ *
+ * Never clobbers a config the user wrote by hand.
  */
-function configureCodexGlobal(binaryPath, mcpServerPath, workspaceRoot) {
+export function configureCodexGlobal(binaryPath, _mcpServerPath, workspaceRoot) {
     const home = os.homedir();
     if (!home)
         return false;
     const configPath = path.join(home, ".codex", "config.toml");
     const mcpPort = readMcpPort(workspaceRoot);
     const token = resolveCodexToken();
-    // Per-workspace URL path — lets the single MCP server on :port route
-    // each codex request to the correct daemon in multi-workspace setups.
-    // Falls back to /mcp if no workspace is known (e.g. global bootstrap).
-    const wsHash = workspaceRoot ? workspaceHash(workspaceRoot) : "";
-    const urlPath = wsHash ? `/ws/${wsHash}/mcp` : "/mcp";
-    const desiredUrl = `http://127.0.0.1:${mcpPort}${urlPath}`;
-    const newSection = `\n[mcp_servers.vexp]\nurl = "${desiredUrl}"\ntool_timeout_sec = 120\n\n[mcp_servers.vexp.http_headers]\nAuthorization = "Bearer ${token}"\n`;
+    const requested = (process.env.VEXP_CODEX_TRANSPORT ?? "direct").toLowerCase();
+    let transport = requested === "http" ? "http" : "direct";
+    if (transport === "direct" && !(binaryPath && fs.existsSync(binaryPath))) {
+        transport = "http";
+    }
     let content = "";
-    if (fs.existsSync(configPath)) {
+    if (fs.existsSync(configPath))
         content = fs.readFileSync(configPath, "utf-8");
-    }
+    const original = content;
     fs.mkdirSync(path.dirname(configPath), { recursive: true });
     // Step 1: strip LEGACY vexp-* sections (not the canonical one).
     const beforeLegacy = content.length;
     content = content.replace(LEGACY_VEXP_TOML_SECTION_RE, "");
-    const legacyStripped = content.length !== beforeLegacy;
-    if (legacyStripped) {
-        process.stdout.write(`  · Removed legacy codex entries from ${configPath}\n`);
+    if (content.length !== beforeLegacy) {
+        process.stdout.write(`  - Removed legacy codex entries from ${configPath}\n`);
     }
-    // Step 2: check if the canonical section already has the desired URL+token.
-    // If yes and no legacy was stripped, this is a true no-op.
-    const canonicalOk = content.includes(`url = "${desiredUrl}"`) &&
-        content.includes(`Authorization = "Bearer ${token}"`);
-    if (canonicalOk && !legacyStripped) {
+    // Step 2: no-clobber — leave a hand-written [mcp_servers.vexp] alone.
+    const existingSection = extractCodexVexpSection(content);
+    if (isUserManagedCodexSection(existingSection)) {
+        if (content !== original) {
+            backupConfig(configPath);
+            fs.writeFileSync(configPath, content, "utf-8");
+            return true;
+        }
         return false;
     }
-    // Step 3: rewrite canonical section (strip it if present, then append).
-    content = content.replace(CANONICAL_VEXP_TOML_SECTION_RE, "");
-    content += newSection;
+    const newSection = buildCodexSection({ transport, coreBinaryPath: binaryPath, workspaceRoot, mcpPort, token, home });
+    if (!newSection) {
+        if (content !== original) {
+            backupConfig(configPath);
+            fs.writeFileSync(configPath, content, "utf-8");
+            return true;
+        }
+        return false;
+    }
+    // Step 3: rewrite the canonical section.
+    content = content.replace(CANONICAL_VEXP_TOML_SECTION_RE, "") + newSection;
+    if (content === original)
+        return false;
+    backupConfig(configPath);
     fs.writeFileSync(configPath, content, "utf-8");
     return true;
 }
@@ -611,16 +780,13 @@ function configureCodexGlobal(binaryPath, mcpServerPath, workspaceRoot) {
  * Write .vscode/mcp.json for GitHub Copilot.
  * VS Code uses "servers" (not "mcpServers") + "type": "stdio".
  */
-function writeVsCodeMcpConfig(p, binaryPath, mcpServerPath, workspaceRoot) {
-    let existing = {};
-    if (fs.existsSync(p)) {
-        try {
-            existing = JSON.parse(fs.readFileSync(p, "utf-8"));
-        }
-        catch {
-            // Malformed JSON: overwrite
-        }
+export function writeVsCodeMcpConfig(p, binaryPath, mcpServerPath, workspaceRoot) {
+    const read = readJsonConfigSafe(p);
+    if (!read.ok) {
+        warnUnparseable(p);
+        return false;
     }
+    const existing = read.data;
     const useNode = mcpServerPath && fs.existsSync(mcpServerPath);
     const targetCmd = useNode ? "node" : binaryPath;
     const targetArgs = useNode ? [mcpServerPath] : ["mcp"];
@@ -645,22 +811,21 @@ function writeVsCodeMcpConfig(p, binaryPath, mcpServerPath, workspaceRoot) {
     };
     existing.servers = servers;
     fs.mkdirSync(path.dirname(p), { recursive: true });
+    if (read.existed)
+        backupConfig(p);
     fs.writeFileSync(p, JSON.stringify(existing, null, 2), "utf-8");
     return true;
 }
 /**
  * Write context_servers in .zed/settings.json for Zed.
  */
-function writeZedMcpConfig(p, binaryPath, mcpServerPath, workspaceRoot) {
-    let settings = {};
-    if (fs.existsSync(p)) {
-        try {
-            settings = JSON.parse(fs.readFileSync(p, "utf-8"));
-        }
-        catch {
-            // Malformed JSON: overwrite
-        }
+export function writeZedMcpConfig(p, binaryPath, mcpServerPath, workspaceRoot) {
+    const read = readJsonConfigSafe(p);
+    if (!read.ok) {
+        warnUnparseable(p);
+        return false;
     }
+    const settings = read.data;
     const useNode = mcpServerPath && fs.existsSync(mcpServerPath);
     const targetCmd = useNode ? "node" : binaryPath;
     const targetArgs = useNode ? [mcpServerPath] : ["mcp"];
@@ -694,6 +859,8 @@ function writeZedMcpConfig(p, binaryPath, mcpServerPath, workspaceRoot) {
     }
     settings.agent = { ...agent, tool_permissions: { ...tp, tools } };
     fs.mkdirSync(path.dirname(p), { recursive: true });
+    if (read.existed)
+        backupConfig(p);
     fs.writeFileSync(p, JSON.stringify(settings, null, 2), "utf-8");
     return true;
 }
@@ -701,20 +868,17 @@ function writeZedMcpConfig(p, binaryPath, mcpServerPath, workspaceRoot) {
  * Configure vexp MCP in ~/.claude.json (user-scope) using the Rust binary.
  * Returns true if config was written/updated.
  */
-function configureClaudeCodeGlobal(binaryPath, mcpServerPath, workspaceRoot) {
+export function configureClaudeCodeGlobal(binaryPath, mcpServerPath, workspaceRoot) {
     const home = os.homedir();
     if (!home)
         return false;
     const configPath = path.join(home, ".claude.json");
-    let config = {};
-    if (fs.existsSync(configPath)) {
-        try {
-            config = JSON.parse(fs.readFileSync(configPath, "utf-8"));
-        }
-        catch {
-            // Malformed JSON: overwrite
-        }
+    const read = readJsonConfigSafe(configPath);
+    if (!read.ok) {
+        warnUnparseable(configPath);
+        return false;
     }
+    const config = read.data;
     const beforeServers = config.mcpServers;
     const existing = beforeServers?.["vexp"];
     const useNode = mcpServerPath && fs.existsSync(mcpServerPath);
@@ -736,18 +900,20 @@ function configureClaudeCodeGlobal(binaryPath, mcpServerPath, workspaceRoot) {
         ...(desiredEnv ? { env: desiredEnv } : {}),
     };
     config.mcpServers = servers;
+    if (read.existed)
+        backupConfig(configPath);
     fs.writeFileSync(configPath, JSON.stringify(config, null, 2), "utf-8");
     return true;
 }
 // ---------------------------------------------------------------------------
-// Claude Code PreToolUse hook — blocks Grep/Glob when daemon is available
+// Claude Code PreToolUse hook - blocks Grep/Glob when daemon is available
 // ---------------------------------------------------------------------------
 /**
  * Install the vexp-guard hook for Claude Code.
  * Creates .claude/hooks/vexp-guard.sh and merges hook config into .claude/settings.json.
  * Returns the action taken, or null if nothing was written.
  */
-function installClaudeCodeHook(workspaceRoot) {
+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");
@@ -757,19 +923,16 @@ function installClaudeCodeHook(workspaceRoot) {
     if (existed) {
         const current = fs.readFileSync(hookPath, "utf-8");
         if (current === VEXP_GUARD_HOOK)
-            return null; // identical — skip
+            return null; // identical - skip
     }
     fs.writeFileSync(hookPath, VEXP_GUARD_HOOK, { mode: 0o755 });
     // 2. Merge hook config into .claude/settings.json
-    let settings = {};
-    if (fs.existsSync(settingsPath)) {
-        try {
-            settings = JSON.parse(fs.readFileSync(settingsPath, "utf-8"));
-        }
-        catch {
-            // Malformed JSON: overwrite
-        }
+    const read = readJsonConfigSafe(settingsPath);
+    if (!read.ok) {
+        warnUnparseable(settingsPath);
+        return 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)
@@ -806,6 +969,8 @@ function installClaudeCodeHook(workspaceRoot) {
         ],
     });
     settings.hooks = { ...hooks, PreToolUse: filtered };
+    if (read.existed)
+        backupConfig(settingsPath);
     fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
     return existed ? "updated" : "created";
 }
@@ -834,13 +999,13 @@ function generateAgentConfig(template, vars) {
     }
 }
 // ---------------------------------------------------------------------------
-// Templates — copied verbatim from agent-auto-config.ts
+// Templates - copied verbatim from agent-auto-config.ts
 // ---------------------------------------------------------------------------
 function claudeCodeTemplate(vars) {
-    return `## vexp — Context-Aware AI Coding <!-- vexp v${vars.version} -->
+    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:
+### 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.
 
@@ -851,47 +1016,47 @@ inspect files (detail: minimal/standard/detailed, 70-90% token savings).
 Only use Read when you need exact raw content to edit a specific line.
 
 ### Primary Tool
-- \`run_pipeline\` — **USE THIS FOR EVERYTHING**. Single call that runs
+- \`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
+  - \`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
+- \`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
 
 ### 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
+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
+5. Do NOT chain multiple vexp calls - one \`run_pipeline\` replaces capsule + impact + memory + observation
 
 ### Subagent / Explore / Plan mode
-- Subagents CAN and MUST call \`run_pipeline\` — always include the task description
+- 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,
+- 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
+- Always: \`run_pipeline\` -> get context -> spawn agent with context
 
-### Smart Features (automatic — no action needed)
-- **Intent Detection**: auto-detects from your task keywords. "fix bug" → Debug, "refactor" → blast-radius, "add" → Modify
+### 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)
+- \`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,
@@ -905,28 +1070,28 @@ 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.**
+**MANDATORY: use \`run_pipeline\` - do NOT grep, glob, or read files manually.**
 vexp returns pre-indexed, graph-ranked context in a single call.
 
 ### Workflow
-1. \`run_pipeline\` with your task description — ALWAYS FIRST (replaces all other tools)
+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
 
 ### Available MCP tools
-- \`run_pipeline\` — **PRIMARY TOOL**. Runs capsule + impact + memory in 1 call.
+- \`run_pipeline\` - **PRIMARY TOOL**. Runs capsule + impact + memory in 1 call.
   Auto-detects intent. Includes file content. 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
+- \`get_skeleton\` - compact file structure
+- \`index_status\` - indexing status
+- \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
 
 ### Agentic search
-- Do NOT use built-in file search, grep, or codebase indexing — always call \`run_pipeline\` first
+- 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
-- Natural language queries work well — vexp uses hybrid search (keyword + semantic + graph)
+- Natural language queries work well - vexp uses hybrid search (keyword + semantic + graph)
 - Add \`include_tests: true\` when debugging
 - Use \`preset: "refactor"\` for deep impact analysis
 
@@ -938,29 +1103,29 @@ Use file search and read tools directly until the index is ready.
 \`run_pipeline\` auto-queries all indexed repos. Use \`repos: ["alias"]\` to scope. Run \`index_status\` to see aliases.
 
 > **Tip:** To avoid confirmation prompts on every tool call, enable Yolo mode:
-> Cursor Settings → Features → Agent → Enable Yolo Mode.
+> Cursor Settings -> Features -> Agent -> Enable Yolo Mode.
 <!-- /vexp -->`;
 }
 function windsurfTemplate(vars) {
     return `## vexp for Windsurf <!-- vexp v${vars.version} -->
 
-**MANDATORY: use \`run_pipeline\` — do NOT grep, glob, or read files manually.**
+**MANDATORY: use \`run_pipeline\` - do NOT grep, glob, or read files manually.**
 vexp returns pre-indexed, graph-ranked context in a single call.
 
 ### Workflow
-1. \`run_pipeline\` with your task description — ALWAYS FIRST (replaces all other tools)
+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
 
 ### Available MCP tools
-- \`run_pipeline\` — **PRIMARY TOOL**. Runs capsule + impact + memory in 1 call.
+- \`run_pipeline\` - **PRIMARY TOOL**. Runs capsule + impact + memory in 1 call.
   Auto-detects intent. Includes file content. 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
+- \`get_skeleton\` - compact file structure
+- \`index_status\` - indexing status
+- \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
 
 ### Agentic search
-- Do NOT use built-in file search, grep, or codebase indexing — always call \`run_pipeline\` first
+- 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
 
@@ -993,23 +1158,23 @@ 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.**
+**MANDATORY: use \`run_pipeline\` - do NOT grep, glob, or read files manually.**
 vexp returns pre-indexed, graph-ranked context in a single call.
 
 When working on this codebase:
-1. \`run_pipeline\` with task description — ALWAYS FIRST
+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
 
 ### Available MCP tools
-- \`run_pipeline\` — **PRIMARY TOOL**. Runs capsule + impact + memory in 1 call.
+- \`run_pipeline\` - **PRIMARY TOOL**. Runs capsule + impact + memory in 1 call.
   Example: \`run_pipeline({ "task": "fix auth bug" })\`
-- \`get_skeleton\` — token-efficient file structure
-- \`index_status\` — indexing status
-- \`expand_vexp_ref\` — expand V-REF placeholders in v2 output
+- \`get_skeleton\` - token-efficient file structure
+- \`index_status\` - indexing status
+- \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
 
 ### Agentic search
-- Do NOT use built-in file search, grep, or codebase indexing — always call \`run_pipeline\` first
+- 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
 
@@ -1023,23 +1188,23 @@ 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.**
+**MANDATORY: use \`run_pipeline\` - do NOT grep, glob, or read files manually.**
 vexp returns pre-indexed, graph-ranked context in a single call.
 
 ### Workflow
-1. \`run_pipeline\` with your task description — ALWAYS FIRST (replaces all other tools)
+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
 
 ### Available MCP tools
-- \`run_pipeline\` — **PRIMARY TOOL**. Runs capsule + impact + memory in 1 call.
+- \`run_pipeline\` - **PRIMARY TOOL**. Runs capsule + impact + memory in 1 call.
   Auto-detects intent. Includes file content. 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
+- \`get_skeleton\` - compact file structure
+- \`index_status\` - indexing status
+- \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
 
 ### Agentic search
-- Do NOT use built-in file search, grep, or codebase indexing — always call \`run_pipeline\` first
+- 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
 
@@ -1053,23 +1218,23 @@ 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.**
+**MANDATORY: use \`run_pipeline\` - do NOT grep, glob, or read files manually.**
 vexp returns pre-indexed, graph-ranked context in a single call.
 
 ### Workflow
-1. \`run_pipeline\` with your task description — ALWAYS FIRST (replaces all other tools)
+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
 
 ### Available MCP tools
-- \`run_pipeline\` — **PRIMARY TOOL**. Runs capsule + impact + memory in 1 call.
+- \`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
+- \`get_skeleton\` - compact file structure
+- \`index_status\` - indexing status
+- \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
 
 ### Agentic search
-- Do NOT use built-in file search, grep, or codebase indexing — always call \`run_pipeline\` first
+- 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
 
@@ -1083,23 +1248,23 @@ 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.**
+**MANDATORY: use \`run_pipeline\` - do NOT grep or glob the codebase.**
 vexp returns pre-indexed, graph-ranked context in a single call.
 
 ### Workflow
-1. \`run_pipeline\` with your task description — ALWAYS FIRST (replaces all other tools)
+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
 
 ### Available MCP tools
-- \`run_pipeline\` — **PRIMARY TOOL**. Runs capsule + impact + memory in 1 call.
+- \`run_pipeline\` - **PRIMARY TOOL**. Runs capsule + impact + memory in 1 call.
   Auto-detects intent. Includes file content. 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
+- \`get_skeleton\` - compact file structure
+- \`index_status\` - indexing status
+- \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
 
 ### Agentic search
-- Do NOT use built-in file search, grep, or codebase indexing — always call \`run_pipeline\` first
+- 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
 
@@ -1113,23 +1278,23 @@ 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.**
+**MANDATORY: use \`run_pipeline\` - do NOT grep, glob, or read files manually.**
 vexp returns pre-indexed, graph-ranked context in a single call.
 
 ## Workflow
-1. \`run_pipeline\` with your task description — ALWAYS FIRST (replaces all other tools)
+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
 
 ## Available vexp tools
-- \`run_pipeline\` — **PRIMARY TOOL**. Runs capsule + impact + memory in 1 call.
+- \`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
+- \`get_skeleton\` - compact file structure
+- \`index_status\` - indexing status
+- \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
 
 ## Agentic search
-- Do NOT use built-in file search, grep, or codebase indexing — always call \`run_pipeline\` first
+- 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
 
@@ -1143,23 +1308,23 @@ Intent auto-detection, hybrid ranking, session memory, auto-expanding budget.
 function genericTemplate(vars) {
     return `## vexp <!-- vexp v${vars.version} -->
 
-**MANDATORY: use \`run_pipeline\` — do NOT grep or glob the codebase.**
+**MANDATORY: use \`run_pipeline\` - do NOT grep or glob the codebase.**
 vexp returns pre-indexed, graph-ranked context in a single call.
 
 ### Workflow
-1. \`run_pipeline\` with your task description — ALWAYS FIRST (replaces all other tools)
+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
 
 ### Available MCP tools
-- \`run_pipeline\` — **PRIMARY TOOL**. Runs capsule + impact + memory in 1 call.
+- \`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
+- \`get_skeleton\` - compact file structure
+- \`index_status\` - indexing status
+- \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
 
 ### Agentic search
-- Do NOT use built-in file search, grep, or codebase indexing — always call \`run_pipeline\` first
+- 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