@zvec/zvec-grep 0.1.6 → 0.1.7

package/dist/cli/help.js

@@ -1,3 +1,7 @@
+import { COMPONENT_CODE_FORMATS, STRUCTURED_CODE_FORMATS, } from "../engine/code-formats.js";
+import { listKnownBinaryExtensionGroups, listRecognizedFileTypes, } from "../engine/file-type.js";
+import { resolveMaxFileSizeBytes } from "../engine/file-size-policy.js";
+import { listEmbeddingModels } from "../engine/models/index.js";
 export function printHelp(version, topic) {
     if (!topic) {
         console.log(mainHelp(version));
@@ -24,7 +28,6 @@ const ENVIRONMENT_VARIABLES = {
     DASHSCOPE_API_KEY: "Qwen credential fallback after ZVEC_GREP_API_KEY",
     QWEN_API_KEY: "Qwen credential fallback after DASHSCOPE_API_KEY",
     ZVEC_GREP_AUTHORIZATION_KEY_FILE: "Workspace grant signing-key file (advanced)",
-    ZVEC_GREP_INSTALL_SKIP_SERVER: "Set to 1 to keep zg install from starting the Server (advanced)",
     ZVEC_GREP_METAL_KEEP_RESIDENCY: "Set to 1 to keep llama.cpp Metal residency enabled (advanced)",
     ZVEC_GREP_LLAMA_CONTEXT_PARALLELISM: "Positive llama.cpp context parallelism override (advanced)",
     NO_COLOR: "Disable terminal colors",
@@ -62,16 +65,17 @@ Examples:
   zg query "where authentication is validated"
   zg query --fts "AuthService"
   zg query --rg -F "AuthService" src
-  zg index --embedding local/embeddinggemma-300m
+  zg index --embedding local/potion-code-16m-v2
   zg status
   zg auth status
   zg server on
-  zg config model set local/embeddinggemma-300m --device metal
+  zg config model set local/potion-code-16m-v2 --device metal
   zg install
 
 Environment:
 ${formatEnvironmentVariables(MAIN_ENVIRONMENT_VARIABLES)}
 
+Run zg help models or zg help file-types for supported indexing capabilities.
 Run zg help environment for all variables, scopes, aliases, and precedence.
 Run zg help <command> or zg <command> --help for command-specific help.
 Use zg -h/--help for this page and zg -v/--version for the version.`;
@@ -93,13 +97,17 @@ Search routes:
   --rg                              Run exhaustive managed ripgrep
 
 Result options:
-  --limit <n>                       Maximum results
-  --human                           Human-readable ranked output
-  --preview <none|short|full>       Indexed source preview size
+  --limit <n>                       Maximum results per group (default: 7)
+  --human                           Human-readable output (default: agent markdown)
+  --preview <none|short|full>       Indexed preview size (default: none; --human: full)
   --debug                           Print diagnostics to stderr
   --trace                           Include per-hit indexed search trace
-  --refresh <background|wait|off>   Refresh policy (Server: background; Direct: off)
-  --mode <direct|server|auto>       Select indexed query transport
+  --refresh <background|wait|off>   Refresh policy (defaults: server=background, direct=off)
+                                    In direct mode, background warns and falls back to off
+  --mode <direct|server|auto>       Select indexed query transport (default: auto)
+
+Indexed results are shown by query group, preserving each group's own rank.
+A result that matches more than one group is shown in each matching group.
 
 Embedding runtime:
   --api-key <key>                   Embedding provider API key
@@ -107,8 +115,6 @@ Embedding runtime:
   --device <device>                 auto, cpu, metal, vulkan, cuda
   --allow-remote                    Allow Remote Embedding for this command only
 
-Direct mode warns and uses off when background is requested.
-
 File filters:
   -g, --glob <glob>                 Include paths; prefix with ! to exclude; repeatable
   --iglob <glob>                    Case-insensitive path glob; repeatable
@@ -143,10 +149,11 @@ Index options:
   --rebuild                         Rebuild the existing index
   --drop                            Permanently remove the workspace index
   --yes                             Confirm --drop without prompting
+  --debug                           Print skipped-file diagnostics to stderr
   --mode <direct|server|auto>       Select indexing transport
 
 Embedding options:
-  --embedding <model>               Model such as local/embeddinggemma-300m or qwen/text-embedding-v4
+  --embedding <model>               Model such as local/potion-code-16m-v2 or qwen/text-embedding-v4
   --api-key <key>                   Embedding provider API key
   --endpoint <url>                  Embedding provider endpoint
   --model-cache <path>              Local model cache directory
@@ -238,11 +245,16 @@ ${formatEnvironmentVariables([
             ])}`;
         case "server":
             return `Usage:
+  zg server --stdio [--token-file <path>] [--mcp-toolset <agent|full>]
   zg server on [--listen 127.0.0.1:7999] [--token-file <path>] [--mcp-toolset <agent|full>]
   zg server off [--token-file <path>]
   zg server status [--check-ready]
   zg server run [--listen 127.0.0.1:7999] [--token-file <path>] [--mcp-toolset <agent|full>]
 
+--stdio is the MCP client bootstrap transport. It safely starts or reuses the
+shared daemon, proxies MCP over stdin/stdout, and leaves the daemon running
+when the client disconnects.
+
 The server listens on loopback. Authentication is disabled by default; pass a
 token file or set ZVEC_GREP_SERVER_TOKEN to require Bearer authentication.
 The public MCP endpoint defaults to the agent toolset (indexed search only).
@@ -263,17 +275,21 @@ ${formatEnvironmentVariables([
 See zg help environment for daemon startup scope.`;
         case "install":
             return `Usage:
-  zg install [--target codex|claude|opencode|cursor|all|auto] [--yes] [--force]
+  zg install [--target codex|claude|opencode|cursor|all|auto] [--mcp-transport stdio|http] [--mcp-toolset agent|full] [--yes] [--force]
 
 Options:
   --target <agent>                  codex, claude, opencode, cursor, auto, or all; repeatable
+  --mcp-transport <stdio|http>      MCP connection mode (default: stdio)
+  --mcp-toolset <agent|full>        Daemon MCP toolset (default: agent)
   --mcp-tool-timeout <seconds>      Codex MCP tool timeout (default: 600)
-  --mcp-token-env <name>            Bearer token environment variable
+  --mcp-token-env <name>            HTTP mode Bearer token environment variable
   --yes                             Install detected agents without prompting
   --force                           Replace conflicting unmanaged configuration
 
-Interactive setup detects supported agents, configures the local MCP server,
-and starts it. Codex, Claude Code, and OpenCode also receive managed guidance;
+Interactive setup detects supported agents, configures stdio by default, and
+starts the shared daemon. In stdio mode an agent reconnect also starts the
+daemon automatically after a reboot. HTTP users manage later daemon restarts.
+Codex, Claude Code, and OpenCode also receive managed guidance;
 Codex and Claude Code receive local tool pre-approval. Remote Embedding
 authorization remains separate and is requested by zvec-grep on first remote
 use. This does not install the npm package.`;
@@ -290,7 +306,13 @@ Removes zvec-grep-managed MCP configuration, trust, and guidance.`;
   zg --help
 
 Topics:
+  models                             Supported embedding models
+  file-types                         Supported file types and structural parsing
   environment, env                   Environment variables and precedence`;
+        case "models":
+            return modelsHelp();
+        case "file-types":
+            return fileTypesHelp();
         case "environment":
         case "env":
             return environmentHelp();
@@ -304,6 +326,118 @@ Topics:
             return undefined;
     }
 }
+function modelsHelp() {
+    const models = listEmbeddingModels().sort((left, right) => {
+        const leftRuntime = left.provider === "local" ? 0 : 1;
+        const rightRuntime = right.provider === "local" ? 0 : 1;
+        return (leftRuntime - rightRuntime ||
+            left.reference.localeCompare(right.reference));
+    });
+    return `Usage:
+  zg help models
+
+Supported embedding models:
+${formatEmbeddingModels(models)}
+
+Local models are downloaded to the model cache on first use. Remote models
+require provider credentials plus --allow-remote or a Workspace authorization.
+Only qwen/qwen3-vl-embedding accepts image input.
+
+Existing indexes keep their stored model. See zg help environment for
+new-index model selection and runtime precedence.`;
+}
+function fileTypesHelp() {
+    const types = listRecognizedFileTypes();
+    const structuredFormats = new Set(STRUCTURED_CODE_FORMATS);
+    const componentFormats = new Set(COMPONENT_CODE_FORMATS);
+    const codeTypes = types.filter((type) => type.kind === "code");
+    const structuredCode = codeTypes.filter((type) => structuredFormats.has(type.format));
+    const componentCode = codeTypes.filter((type) => componentFormats.has(type.format));
+    const plainCode = codeTypes.filter((type) => !structuredFormats.has(type.format) && !componentFormats.has(type.format));
+    const documentsAndData = types.filter((type) => type.kind === "text" || type.kind === "data");
+    const images = types.filter((type) => type.kind === "image");
+    const skipped = listKnownBinaryExtensionGroups().map((group) => [
+        group.label,
+        group.extensions.join(", "),
+    ]);
+    const sizeLimits = [
+        ["Code", "code"],
+        ["Text", "text"],
+        ["Data", "data"],
+        ["Image", "image"],
+    ].map(([label, kind]) => [
+        label,
+        `${resolveMaxFileSizeBytes(kind) / (1024 * 1024)} MiB`,
+    ]);
+    return `Usage:
+  zg help file-types
+
+Structured code (symbols and scopes):
+${formatFileTypeTable(structuredCode)}
+
+Component code (JavaScript and TypeScript script blocks):
+${formatFileTypeTable(componentCode)}
+
+Other code (plain-text chunks):
+${formatFileTypeTable(plainCode)}
+
+Documents and data:
+${formatFileTypeTable(documentsAndData)}
+  Markdown preserves heading structure; other formats use text chunks.
+
+Images (multimodal embedding required):
+${formatFileTypeTable(images)}
+  Images are ignored by default and must be explicitly selected.
+
+Other text:
+  Unknown non-binary extensions and extensionless files use text chunks.
+
+Skipped binary types:
+${formatTable(["GROUP", "EXTENSIONS"], skipped)}
+  Files detected as binary by content are also skipped.
+
+Indexing rules:
+  Default size limits:
+${formatTable(["KIND", "MAX SIZE"], sizeLimits)}
+  Empty files are skipped. Use --max-filesize to override the size limit.
+  Common dependencies, build output, generated files, and lock files are
+  ignored by default. .git and .zvec-grep are always skipped.`;
+}
+function formatEmbeddingModels(models) {
+    const rows = models.map((model) => {
+        const runtime = model.provider === "local" ? "local" : "remote";
+        const input = "kind" in model && model.kind === "multimodal" ? "text,image" : "text";
+        const inputLimit = "maxInputTokens" in model ? model.maxInputTokens : model.contextSize;
+        return [
+            model.reference,
+            runtime,
+            input,
+            String(model.dimension),
+            String(inputLimit),
+            model.backend,
+        ];
+    });
+    return formatTable(["MODEL", "RUNTIME", "INPUT", "DIMS", "TOKENS", "BACKEND"], rows, new Set([3, 4]));
+}
+function formatFileTypeTable(types) {
+    const rows = [...types]
+        .sort((left, right) => left.format.localeCompare(right.format))
+        .map((type) => [type.format, type.patterns.join(", ")]);
+    return formatTable(["TYPE", "FILES"], rows);
+}
+function formatTable(header, rows, rightAlignedColumns = new Set()) {
+    const widths = header.map((label, index) => Math.max(label.length, ...rows.map((row) => row[index].length)));
+    const separator = widths.map((width) => "-".repeat(width));
+    return [header, separator, ...rows]
+        .map((row) => `  ${row
+        .map((value, index) => index === row.length - 1
+        ? value
+        : rightAlignedColumns.has(index)
+            ? value.padStart(widths[index])
+            : value.padEnd(widths[index]))
+        .join("  ")}`)
+        .join("\n");
+}
 function environmentHelp() {
     return `Usage:
   zg help environment
@@ -338,7 +472,6 @@ ${formatEnvironmentVariables([
 
 Advanced:
 ${formatEnvironmentVariables([
-        "ZVEC_GREP_INSTALL_SKIP_SERVER",
         "ZVEC_GREP_METAL_KEEP_RESIDENCY",
         "ZVEC_GREP_LLAMA_CONTEXT_PARALLELISM",
         "NO_COLOR",

package/dist/cli/help.js.map

@@ -1 +1 @@
-{"version":3,"file":"help.js","sourceRoot":"","sources":["../../src/cli/help.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"help.js","sourceRoot":"","sources":["../../src/cli/help.ts"],"names":[],"mappings":"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"}

package/dist/cli/index.d.ts

@@ -1,2 +1,2 @@
-#!/usr/bin/env node
+#!/usr/bin/env -S node --liftoff-only
 export {};

package/dist/cli/index.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env -S node --liftoff-only
 import { parseArgs } from "./args.js";
 import { runParsedCommand } from "./commands.js";
 import { colorModeFromArgs, printError } from "./errors.js";

package/dist/cli/install.js

@@ -5,6 +5,7 @@ import { homedir } from "node:os";
 import { delimiter, dirname, resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { resolveServerUrl } from "../client/mode-router.js";
+import { formatPromptRules, ZVEC_GREP_WORKSPACE_EVIDENCE_RULES, } from "../prompts/zvec-grep-guidance.js";
 const AGENT_INSTALLERS = [
     {
         id: "claude",
@@ -48,10 +49,13 @@ export async function runInstall(parsed) {
         console.log("\nNo agent integrations selected.");
         return;
     }
+    const transport = await resolveInstallTransport(parsed);
     console.log("\nInstalling integrations\n");
     for (const installer of installers) {
         await installer.install({
             force: parsed.options.force === true,
+            transport,
+            mcpToolset: parsed.options.mcpToolset,
             mcpToolTimeoutSeconds: parsed.options.installMcpToolTimeoutSeconds ??
                 DEFAULT_MCP_TOOL_TIMEOUT_SECONDS,
             mcpTokenEnv: parsed.options.installMcpTokenEnv,
@@ -60,7 +64,7 @@ export async function runInstall(parsed) {
         console.log("    MCP       configured");
         console.log("");
     }
-    const server = await ensureInstalledServer();
+    const server = await ensureInstalledServer(parsed.options.mcpToolset);
     if (server.ready) {
         console.log(`  ${installSuccessMark()} Server`);
         console.log(`    ready at ${server.serverUrl ?? resolveServerUrl()}`);
@@ -69,6 +73,10 @@ export async function runInstall(parsed) {
         console.log(`  ${installMutedMark()} Server`);
         console.log("    not started; run `zg server on`");
     }
+    if (transport === "stdio") {
+        console.log(`  ${installSuccessMark()} Connection`);
+        console.log("    stdio; reconnects start the server automatically");
+    }
     console.log("\nzvec-grep is ready\n");
     console.log(`  Agents       ${installers.map((installer) => installer.label).join(", ")}`);
     console.log("  Remote data  Authorization requested on first remote use");
@@ -97,7 +105,7 @@ async function installCodexIntegration(options) {
         path: configPath,
         startMarker: ZVEC_GREP_CONFIG_START,
         endMarker: ZVEC_GREP_CONFIG_END,
-        block: codexConfigBlock(options.mcpToolTimeoutSeconds, options.mcpTokenEnv),
+        block: codexConfigBlock(options),
         force: options.force,
         hasConflict: hasCodexMcpServerConfig,
         conflictMessage: `Existing [mcp_servers.zvec_grep] found in ${configPath}. Re-run with --force after removing or moving that table into the zvec-grep managed block.`,
@@ -120,6 +128,8 @@ async function installClaudeIntegration(options) {
     await updateClaudeMcpConfig({
         path: mcpConfigPath,
         force: options.force,
+        transport: options.transport,
+        mcpToolset: options.mcpToolset,
         tokenEnv: options.mcpTokenEnv,
     });
     await updateClaudePermissionSettings(settingsPath, true);
@@ -168,20 +178,27 @@ async function installOpenCodeIntegration(options) {
     await installJsonMcpServer({
         path: configPath,
         containerKey: "mcp",
-        server: {
-            type: "remote",
-            url: resolveServerUrl(),
-            enabled: true,
-            timeout: options.mcpToolTimeoutSeconds * 1_000,
-            oauth: false,
-            ...(options.mcpTokenEnv
-                ? {
-                    headers: {
-                        Authorization: `Bearer {env:${options.mcpTokenEnv}}`,
-                    },
-                }
-                : {}),
-        },
+        server: options.transport === "stdio"
+            ? {
+                type: "local",
+                command: stdioCommand(options.mcpToolset),
+                enabled: true,
+                timeout: options.mcpToolTimeoutSeconds * 1_000,
+            }
+            : {
+                type: "remote",
+                url: resolveServerUrl(),
+                enabled: true,
+                timeout: options.mcpToolTimeoutSeconds * 1_000,
+                oauth: false,
+                ...(options.mcpTokenEnv
+                    ? {
+                        headers: {
+                            Authorization: `Bearer {env:${options.mcpTokenEnv}}`,
+                        },
+                    }
+                    : {}),
+            },
         force: options.force,
         label: "OpenCode",
     });
@@ -191,6 +208,7 @@ async function installOpenCodeIntegration(options) {
         endMarker: ZVEC_GREP_AGENTS_END,
         block: agentGuidanceBlock({
             search: "zvec_grep_zvec_grep_search",
+            rg: "zvec_grep_zvec_grep_rg",
         }),
         force: true,
     });
@@ -212,16 +230,18 @@ async function installCursorIntegration(options) {
     await installJsonMcpServer({
         path: configPath,
         containerKey: "mcpServers",
-        server: {
-            url: resolveServerUrl(),
-            ...(options.mcpTokenEnv
-                ? {
-                    headers: {
-                        Authorization: `Bearer \${${options.mcpTokenEnv}}`,
-                    },
-                }
-                : {}),
-        },
+        server: options.transport === "stdio"
+            ? { command: "zg", args: stdioArgs(options.mcpToolset) }
+            : {
+                url: resolveServerUrl(),
+                ...(options.mcpTokenEnv
+                    ? {
+                        headers: {
+                            Authorization: `Bearer \${${options.mcpTokenEnv}}`,
+                        },
+                    }
+                    : {}),
+            },
         force: options.force,
         label: "Cursor",
     });
@@ -248,6 +268,32 @@ async function resolveInstallers(parsed, action) {
     }
     return promptInstallers(action, detected);
 }
+async function resolveInstallTransport(parsed) {
+    if (parsed.options.installMcpTransport) {
+        return parsed.options.installMcpTransport;
+    }
+    if (parsed.options.yes === true ||
+        !process.stdin.isTTY ||
+        !process.stdout.isTTY) {
+        return "stdio";
+    }
+    const readline = createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    try {
+        const answer = await readline.question("MCP transport [stdio] (stdio/http): ");
+        const value = answer.trim().toLowerCase();
+        if (!value || value === "stdio")
+            return "stdio";
+        if (value === "http")
+            return "http";
+        throw new Error("MCP transport must be stdio or http");
+    }
+    finally {
+        readline.close();
+    }
+}
 async function promptInstallers(action, detected) {
     console.log(action === "install"
         ? "\nChoose agent integrations\n"
@@ -439,12 +485,12 @@ function installStyle(code, value) {
         ? `\u001b[${code}m${value}\u001b[0m`
         : value;
 }
-async function ensureInstalledServer() {
+async function ensureInstalledServer(mcpToolset) {
     if (process.env.ZVEC_GREP_INSTALL_SKIP_SERVER === "1") {
         return { running: false, ready: false };
     }
     const { startServer } = await import("../daemon/server-controller.js");
-    return startServer({ cliPath: process.argv[1] });
+    return startServer({ cliPath: process.argv[1], mcpToolset });
 }
 function splitTargetTokens(value) {
     return value
@@ -518,27 +564,32 @@ async function updateClaudeMcpConfig(options) {
     const mcpServers = isJsonObject(currentServers) ? currentServers : {};
     const current = mcpServers.zvec_grep;
     if (current !== undefined &&
-        (!isJsonObject(current) || current.url !== resolveServerUrl()) &&
+        !isManagedJsonMcpServer(current) &&
         !options.force) {
         throw new Error(`Existing Claude Code MCP server "zvec_grep" found in ${options.path}. Re-run with --force to replace it.`);
     }
     const existingServer = isJsonObject(current) ? current : {};
-    const existingHeaders = isJsonObject(existingServer.headers)
-        ? existingServer.headers
-        : {};
-    mcpServers.zvec_grep = {
-        ...existingServer,
-        type: "http",
-        url: resolveServerUrl(),
-        ...(options.tokenEnv
+    const { type: _type, url: _url, command: _command, args: _args, headers: _headers, ...retained } = existingServer;
+    mcpServers.zvec_grep =
+        options.transport === "stdio"
             ? {
-                headers: {
-                    ...existingHeaders,
-                    Authorization: `Bearer \${${options.tokenEnv}}`,
-                },
+                ...retained,
+                type: "stdio",
+                command: "zg",
+                args: stdioArgs(options.mcpToolset),
             }
-            : {}),
-    };
+            : {
+                ...retained,
+                type: "http",
+                url: resolveServerUrl(),
+                ...(options.tokenEnv
+                    ? {
+                        headers: {
+                            Authorization: `Bearer \${${options.tokenEnv}}`,
+                        },
+                    }
+                    : {}),
+            };
     root.mcpServers = mcpServers;
     await writeJsonObject(options.path, root);
 }
@@ -550,7 +601,7 @@ async function removeClaudeMcpConfig(path) {
     if (!isJsonObject(root.mcpServers))
         return;
     const current = root.mcpServers.zvec_grep;
-    if (!isJsonObject(current) || current.url !== resolveServerUrl())
+    if (!isManagedJsonMcpServer(current))
         return;
     delete root.mcpServers.zvec_grep;
     if (Object.keys(root.mcpServers).length === 0) {
@@ -622,7 +673,43 @@ function isJsonObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function isManagedJsonMcpServer(value) {
-    return isJsonObject(value) && value.url === resolveServerUrl();
+    if (!isJsonObject(value))
+        return false;
+    if (value.url === resolveServerUrl())
+        return true;
+    if (value.command === "zg" && isStdioArgs(value.args))
+        return true;
+    return (value.type === "local" &&
+        Array.isArray(value.command) &&
+        (value.command.length === 3 || value.command.length === 5) &&
+        value.command[0] === "zg" &&
+        value.command[1] === "server" &&
+        value.command[2] === "--stdio" &&
+        (value.command.length === 3 ||
+            (value.command[3] === "--mcp-toolset" &&
+                (value.command[4] === "agent" || value.command[4] === "full"))));
+}
+function isStdioArgs(value) {
+    return (Array.isArray(value) &&
+        (value.length === 2 || value.length === 4) &&
+        value[0] === "server" &&
+        value[1] === "--stdio" &&
+        (value.length === 2 ||
+            (value[2] === "--mcp-toolset" &&
+                (value[3] === "agent" || value[3] === "full"))));
+}
+function stdioArgs(mcpToolset) {
+    return [
+        "server",
+        "--stdio",
+        ...(mcpToolset ? ["--mcp-toolset", mcpToolset] : []),
+    ];
+}
+function stdioCommand(mcpToolset) {
+    return ["zg", ...stdioArgs(mcpToolset)];
+}
+function tomlStringArray(values) {
+    return `[${values.map((value) => JSON.stringify(value)).join(", ")}]`;
 }
 async function writeJsonObject(path, value) {
     await writeTextFileAtomic(path, `${JSON.stringify(value, null, 2)}\n`);
@@ -813,33 +900,64 @@ function tomlTableName(line) {
 function isCodexMcpServerTableName(tableName) {
     return /^(?:mcp_servers|"mcp_servers"|'mcp_servers')\s*\.\s*(?:zvec_grep|"zvec_grep"|'zvec_grep')(?:\s*\.|$)/.test(tableName);
 }
-function codexConfigBlock(mcpToolTimeoutSeconds, tokenEnv) {
+function codexConfigBlock(options) {
     return `${ZVEC_GREP_CONFIG_START}
 [mcp_servers.zvec_grep]
-url = "${resolveServerUrl()}"
-${tokenEnv
-        ? `bearer_token_env_var = "${tokenEnv}"
+${options.transport === "stdio"
+        ? `command = "zg"
+args = ${tomlStringArray(stdioArgs(options.mcpToolset))}`
+        : `url = "${resolveServerUrl()}"`}
+${options.mcpTokenEnv
+        ? `bearer_token_env_var = "${options.mcpTokenEnv}"
 `
-        : ""}tool_timeout_sec = ${mcpToolTimeoutSeconds}
+        : ""}tool_timeout_sec = ${options.mcpToolTimeoutSeconds}
 default_tools_approval_mode = "approve"
 ${ZVEC_GREP_CONFIG_END}`;
 }
 function agentGuidanceBlock(toolNames) {
     const searchTool = toolNames?.search ?? "zvec_grep_search";
+    const rgTool = toolNames?.rg ?? "zvec_grep_rg";
+    const exactLookupRoute = `\`${rgTool}\` when it is listed by the current host; otherwise native Grep or \`rg\``;
     return `${ZVEC_GREP_AGENTS_START}
 ## zvec-grep
 
-Choose the initial search tool by the scope of the requested answer, not merely by whether the question contains an identifier.
+Choose the evidence source before the retrieval mode.
+
+${formatPromptRules("### Workspace evidence", ZVEC_GREP_WORKSPACE_EVIDENCE_RULES)}
 
-Use native Grep or rg first when the answer can be obtained by locating a specific definition, reference, filename, configuration key, error message, literal, source fragment, or regex.
+${formatPromptRules("### Retrieval routing", [
+        `When an exact word, phrase, name, date, identifier, filename, path, configuration key, error message, source fragment, literal, or regex is known and locating its occurrences is sufficient, use ${exactLookupRoute}.`,
+        `Use \`${searchTool}\` when wording or location is unknown, or when the answer requires semantic, conceptual, fuzzy, or paraphrase discovery; relationships, chronology, causality, architecture, or data or control flow; or comparison or synthesis across files, sections, or documents.`,
+        `For a mixed task with exact anchors that still requires relationships or cross-file synthesis, call \`${searchTool}\` with the concept and anchors, then use ${exactLookupRoute} for focused follow-up.`,
+        `When no sufficient exact anchor is available and the user asks whether conceptually related material exists locally, make at most one focused \`${searchTool}\` probe using the question plus distinctive names, dates, or terms. This probe does not apply to exact quotations, configuration keys, filenames, regexes, or exhaustive occurrence requests. Continue only when results are relevant; otherwise stop and report that the indexed workspace did not establish the answer.`,
+        "Before broad file reads or delegating workspace discovery, use the appropriate search route. Do not delegate solely to locate material, and stop when the evidence is sufficient.",
+    ])}
 
-Use \`${searchTool}\` first when the answer requires architecture, lifecycle, system design, conceptual discovery, data or control flow, comparison across implementations, design rationale, or performance analysis.
+${formatPromptRules("### Search arguments and evidence", [
+        "`query` creates one primary hybrid result group; `queries` creates one or more primary hybrid result groups.",
+        "`fts` and `vector` add supplemental lexical and semantic routes. `fts` is a retrieval route, not a hard filter or constraint.",
+        "Without `fuse`, search groups are evaluated separately and returned as one deduplicated, reranked list with query-group metadata. Set `fuse: true` to collapse the supplied primary and supplemental intents into one search plan.",
+        "Search results include bounded source snippets. Treat a sufficient snippet as already-read evidence, and read a cited file only when a required detail falls outside the snippet.",
+    ])}
 
-When exact symbols are present but the answer spans multiple components, files, stages, or implementations, treat it as a mixed task: use \`${searchTool}\` with the concept and known symbols, then use native Grep or rg for focused follow-up.
+Example mixed search:
 
-Before using broad file reads or a sub-agent for conceptual repository discovery, make at least one appropriate \`${searchTool}\` call.
+\`\`\`json
+{
+  "root": "/absolute/workspace",
+  "query": "how are search results ranked and fused",
+  "fts": ["RRF", "score"],
+  "fuse": true
+}
+\`\`\`
 
-Do not launch a sub-agent solely to locate code. Stop discovery when the evidence covers all components requested by the question.
+${formatPromptRules("### Freshness and index lifecycle", [
+        "Pass a daemon-visible absolute `root` on every zvec-grep workspace call.",
+        "Read `freshness` and `background_refresh` from search results without a status preflight.",
+        "When results are `served_from_current_index`, use them when sufficient instead of waiting for the background refresh.",
+        `If the index is missing but exact or regex lookup can answer the task, use ${exactLookupRoute}.`,
+        "Creating, rebuilding, or dropping a persistent index requires an explicit user request or authorization; never do so silently.",
+    ])}
 ${ZVEC_GREP_AGENTS_END}`;
 }
 //# sourceMappingURL=install.js.map