@angri450/zvec-grep 0.2.2

package/dist/observability/trace-context.js

@@ -0,0 +1,138 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+const storage = new AsyncLocalStorage();
+const TRACEPARENT = /^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})((?:-[0-9a-f]+)*)$/;
+export function currentTraceContext() {
+    return storage.getStore();
+}
+export function runWithTraceContext(context, operation) {
+    return context ? storage.run(context, operation) : operation();
+}
+export function traceContextFromMcpBody(body) {
+    if (!body || typeof body !== "object" || Array.isArray(body)) {
+        return undefined;
+    }
+    return traceContextFromMcpMeta(body.params?._meta);
+}
+export function traceContextFromMcpMeta(meta) {
+    if (!meta || typeof meta !== "object" || Array.isArray(meta)) {
+        return undefined;
+    }
+    const values = meta;
+    const traceparent = typeof values.traceparent === "string" ? values.traceparent : undefined;
+    const match = traceparent?.match(TRACEPARENT);
+    if (!match ||
+        match[1] === "ff" ||
+        (match[1] === "00" && match[5] !== "") ||
+        match[2] === "0".repeat(32) ||
+        match[3] === "0".repeat(16)) {
+        return undefined;
+    }
+    const tracestate = validTracestate(values.tracestate);
+    const baggage = validBaggage(values.baggage);
+    return {
+        traceparent: traceparent,
+        traceId: match[2],
+        ...(tracestate ? { tracestate } : {}),
+        ...(baggage ? { baggage } : {}),
+    };
+}
+export function traceHeaders() {
+    const context = currentTraceContext();
+    if (!context)
+        return {};
+    return {
+        traceparent: context.traceparent,
+        ...(context.tracestate ? { tracestate: context.tracestate } : {}),
+        ...(context.baggage ? { baggage: context.baggage } : {}),
+    };
+}
+function boundedHeader(value, maxLength, allowHorizontalTab = false) {
+    if (typeof value !== "string" || value.length > maxLength)
+        return undefined;
+    for (const character of value) {
+        const code = character.charCodeAt(0);
+        if (code > 0x7e ||
+            (code < 0x20 && !(allowHorizontalTab && code === 0x09))) {
+            return undefined;
+        }
+    }
+    return value;
+}
+function validTracestate(value) {
+    const header = boundedHeader(value, 512);
+    if (!header)
+        return undefined;
+    const members = header.split(",");
+    if (members.length > 32)
+        return undefined;
+    const keys = new Set();
+    for (const rawMember of members) {
+        const member = rawMember.trim();
+        const separator = member.indexOf("=");
+        if (separator <= 0)
+            return undefined;
+        const key = member.slice(0, separator);
+        const item = member.slice(separator + 1);
+        if (!/^(?:[a-z][a-z0-9_\-*/]{0,255}|[a-z0-9][a-z0-9_\-*/]{0,240}@[a-z][a-z0-9_\-*/]{0,13})$/.test(key) ||
+            item.length === 0 ||
+            item.length > 256 ||
+            !/^[\x20-\x2b\x2d-\x3c\x3e-\x7e]+$/.test(item) ||
+            item.endsWith(" ") ||
+            keys.has(key)) {
+            return undefined;
+        }
+        keys.add(key);
+    }
+    return header;
+}
+function validBaggage(value) {
+    const header = boundedHeader(value, 8_192, true);
+    if (!header)
+        return undefined;
+    const members = header.split(",");
+    if (members.length > 64)
+        return undefined;
+    for (const rawMember of members) {
+        const segments = rawMember.trim().split(";");
+        const pair = segments.shift();
+        const separator = pair.indexOf("=");
+        const pairValue = separator < 0 ? "" : pair.slice(separator + 1).trim();
+        if (separator <= 0 ||
+            !isHttpToken(pair.slice(0, separator).trim()) ||
+            hasInvalidBaggageCharacters(pairValue, ",")) {
+            return undefined;
+        }
+        for (const rawProperty of segments) {
+            const property = rawProperty.trim();
+            const propertySeparator = property.indexOf("=");
+            const key = propertySeparator < 0
+                ? property
+                : property.slice(0, propertySeparator).trim();
+            const propertyValue = propertySeparator < 0
+                ? ""
+                : property.slice(propertySeparator + 1).trim();
+            if (!isHttpToken(key) ||
+                hasInvalidBaggageCharacters(propertyValue, ";,")) {
+                return undefined;
+            }
+        }
+    }
+    return header;
+}
+function isHttpToken(value) {
+    return /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/.test(value);
+}
+function hasInvalidBaggageCharacters(value, delimiters) {
+    for (const character of value) {
+        const code = character.charCodeAt(0);
+        if (code <= 0x20 ||
+            code === 0x22 ||
+            code === 0x5c ||
+            code === 0x7f ||
+            delimiters.includes(character)) {
+            return true;
+        }
+    }
+    return false;
+}
+//# sourceMappingURL=trace-context.js.map

package/dist/observability/trace-context.js.map

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

package/dist/prompts/zvec-grep-guidance.d.ts

@@ -0,0 +1,2 @@
+export declare const ZVEC_GREP_WORKSPACE_EVIDENCE_RULES: readonly ["Use the current workspace as the evidence source when the user asks about local material, prior context establishes it as relevant, or the question concerns how the current project works—even if the workspace is not mentioned explicitly.", "A workspace may contain any mix of code, documents, configuration, and data.", "Do not use workspace retrieval for unrelated open-world questions, current external facts, or web content that does not depend on local evidence."];
+export declare function formatPromptRules(heading: string, rules: readonly string[]): string;

package/dist/prompts/zvec-grep-guidance.js

@@ -0,0 +1,9 @@
+export const ZVEC_GREP_WORKSPACE_EVIDENCE_RULES = [
+    "Use the current workspace as the evidence source when the user asks about local material, prior context establishes it as relevant, or the question concerns how the current project works—even if the workspace is not mentioned explicitly.",
+    "A workspace may contain any mix of code, documents, configuration, and data.",
+    "Do not use workspace retrieval for unrelated open-world questions, current external facts, or web content that does not depend on local evidence.",
+];
+export function formatPromptRules(heading, rules) {
+    return [heading, ...rules.map((rule) => `- ${rule}`)].join("\n");
+}
+//# sourceMappingURL=zvec-grep-guidance.js.map

package/dist/prompts/zvec-grep-guidance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"zvec-grep-guidance.js","sourceRoot":"","sources":["../../src/prompts/zvec-grep-guidance.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,kCAAkC,GAAG;IAChD,+OAA+O;IAC/O,8EAA8E;IAC9E,mJAAmJ;CAC3I,CAAC;AAEX,MAAM,UAAU,iBAAiB,CAC/B,OAAe,EACf,KAAwB;IAExB,OAAO,CAAC,OAAO,EAAE,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACnE,CAAC"}

package/docs/01-agents.md

@@ -0,0 +1,217 @@
+# Agent integrations
+
+[Documentation](./README.md) · [Agents](./01-agents.md) ·
+[CLI](./02-cli.md) · [MCP](./03-mcp.md) · [Pipeline](./04-pipeline.md) ·
+[Architecture](./05-architecture.md) · [Server](./06-server.md) ·
+[Embedding](./07-embedding.md) · [Roadmap](./08-roadmap.md)
+
+`zg --install` connects zvec-grep to supported agents through the local MCP
+server. After that, the agent can use indexed retrieval for workspace-grounded
+semantic discovery while keeping exact lookup on the appropriate native or
+managed-rg route.
+
+## Supported agents
+
+| Agent | Target | Managed configuration |
+| --- | --- | --- |
+| Codex | `codex` | `~/.codex/config.toml` and `~/.codex/AGENTS.md` |
+| Claude Code | `claude` | `~/.claude.json`, `~/.claude/settings.json`, and `~/.claude/CLAUDE.md` |
+| Qwen Code | `qwen` | `~/.qwen/settings.json` and `~/.qwen/QWEN.md` |
+| Qoder CLI and IDE | `qoder` | `~/.qoder/settings.json`, `~/.qoder/AGENTS.md`, and the IDE user-level `~/.qoder/mcp.json` |
+| OpenCode | `opencode` | the existing `~/.config/opencode/opencode.jsonc` or `opencode.json`, and the adjacent `AGENTS.md` |
+| Cursor | `cursor` | `~/.cursor/mcp.json` |
+
+The standard environment overrides used by each agent are respected, including
+`CODEX_HOME`, `CLAUDE_CONFIG_DIR`, `QWEN_HOME`, `QODER_CONFIG_DIR`,
+`QODER_IDE_MCP_PATH`, `QODER_IDE_EXECUTABLE`, `OPENCODE_CONFIG`, and
+`CURSOR_CONFIG_DIR`.
+
+For OpenCode, `OPENCODE_CONFIG` selects the exact configuration file. Without
+that override, the installer uses an existing global `opencode.jsonc` before
+`opencode.json`, preserves JSONC comments and unrelated settings, and creates
+`opencode.json` only when neither file exists. If both files exist, the selected
+`opencode.jsonc` path is reported in the install output. On Linux and other
+XDG-based environments, `XDG_CONFIG_HOME` replaces the default `~/.config`
+root.
+
+The current Qoder CLI package exposes both `qoder` and `qodercli` commands, but
+the installer exposes only the canonical `qoder` target. One Qoder install
+configures both the CLI and IDE, and automatic detection recognizes either CLI
+executable or the IDE. `QODER_CONFIG_DIR` overrides the Qoder CLI configuration
+directory; `QODER_IDE_MCP_PATH` independently overrides the full IDE `mcp.json` path, and
+`QODER_IDE_EXECUTABLE` overrides the IDE executable used by automatic detection.
+
+## Install an integration
+
+Run the guided installer to select from detected agents:
+
+```bash
+zg --install
+```
+
+For scripts or repeatable setup, select targets explicitly:
+
+```bash
+zg --install --target codex --yes
+zg --install --target claude --target cursor --yes
+zg --install --target qwen --yes
+zg --install --target qoder --yes
+zg --install --target all --yes
+```
+
+The installer:
+
+1. adds a managed `zvec_grep` MCP entry;
+2. adds search guidance where the agent supports it;
+3. adds local MCP tool approval for Codex and Claude Code, managed server trust
+   for Qwen Code and Qoder CLI, and exact search/rg allow rules for Qoder's
+   CLI-backed runtime;
+4. starts the local zvec-grep server when possible.
+
+The [Server guide](./06-server.md) explains when the daemon is useful and how its
+lifecycle differs from Direct execution.
+
+Managed text blocks use `ZVEC_GREP_START` and `ZVEC_GREP_END` markers. Existing
+content outside those blocks is preserved, as are unrelated settings and other
+MCP servers. If an unmanaged `zvec_grep` entry already exists, inspect it before
+using `--force` to replace it.
+
+For Qoder CLI, `--mcp-transport` selects either a stdio or HTTP entry under
+`mcpServers`; the installer also manages the timeout and trust fields. Search
+guidance is written to `${QODER_CONFIG_DIR:-~/.qoder}/AGENTS.md` without
+replacing unrelated guidance.
+
+The same Qoder `settings.json`, used by Qoder CLI and CLI-backed Qoder clients,
+receives exact `permissions.allow` rules for
+`mcp__zvec_grep__zvec_grep_search` and `mcp__zvec_grep__zvec_grep_rg`, plus the
+equivalent server-level `alwaysAllow` policy. This avoids repeated tool approval
+prompts without allowing other MCP tools. Existing permission rules and JSONC
+comments are preserved; uninstall removes only rules added by zg.
+
+The same install writes the Qoder IDE MCP entry to its user-level
+`~/.qoder/mcp.json`. Set `QODER_IDE_MCP_PATH` to override that complete file
+path. The IDE entry uses
+stdio when `--mcp-transport stdio` is selected. For HTTP it uses a `type: "sse"`
+URL entry, from which Qoder IDE automatically detects the streamable HTTP MCP
+endpoint. Qoder's platform `SharedClientCache` is runtime/cache state rather
+than the user MCP configuration entry point, so the installer does not write
+it. Qoder IDE has no supported global Rules file, so the installer does not
+claim to create or manage IDE search guidance.
+
+Both Qoder clients receive the same MCP form-based Remote Embedding
+authorization request as other clients. If Qoder CLI reports that no handler is
+registered for `elicitation/create`, or returns a decline or cancellation
+without displaying the form, its installed `AGENTS.md` guidance supplies a
+compatibility interaction through the exact `AskUserQuestion` tool. The CLI
+agent must ask whether to allow Remote Embedding for the workspace, use local
+FTS only, or cancel.
+
+Qoder IDE uses the exact native tool name `ask_user_question`, but its official
+integration does not provide a global Rules location where the installer can
+persist the fallback. In stdio mode, the zvec-grep bridge turns a missing
+`elicitation/create` handler into an actionable error that tells the top-level
+IDE agent to present the same three choices with `ask_user_question`. This path
+still needs an end-to-end smoke test in a real Qoder IDE session and should not
+be treated as proof that every IDE build follows the instruction.
+
+Only after explicit workspace approval may either client run the following
+persistent grant and retry the original MCP search once:
+
+```bash
+zg --auth grant "/absolute/workspace" \
+  --capability embedding \
+  --scope workspace
+```
+
+The local-FTS choice retries the search without `query`, `queries`, or `vector`
+routes and with `autoUpdate: false` and `freshness: "eventual"`. It neither
+refreshes the remote-embedding index nor sends query text or workspace content
+to a remote Embedding provider. In a headless session where Qoder cannot ask the
+user, the agent stops without granting access. Neither question tool should
+collect a token, API key, or password. Provider credentials remain separate
+from this data authorization.
+
+Restart the selected agent, or open a new session, after installation.
+
+## How the agent searches
+
+The agent routes in two stages: first it decides whether the answer should be
+grounded in the current indexed workspace, then it chooses exact or semantic
+retrieval. Code versus non-code is not the boundary; a workspace may contain any
+mix of code, documents, configuration, and data.
+
+Workspace content is the intended evidence source when the user asks to inspect,
+search, or ground the answer in local files, the workspace, or its index; prior
+context established local material as the intended source; or the user asks
+whether relevant local material exists. Negative, incidental, or comparative
+workspace mentions do not establish relevance. Tool availability or topic
+overlap alone does not establish workspace relevance.
+
+The default MCP surface gives the agent one indexed search tool and leaves exact
+lexical lookup to the agent's native tools:
+
+| Intent | Tool |
+| --- | --- |
+| Workspace-grounded exact words, quotations, names, dates, keys, filenames, paths, or regexes are sufficient | Native grep or rg |
+| Workspace-grounded wording or location is unknown, or the answer requires semantic, fuzzy, relationship, chronology, causality, comparison, or cross-file synthesis | `zvec_grep_search` |
+| Exact anchors are known but the answer requires broader context or synthesis | `zvec_grep_search`, then native grep or rg |
+| The answer is unrelated open-world knowledge, a current external fact, or web content that does not depend on local evidence | The appropriate external source, not zvec-grep |
+
+`zvec_grep_search` needs an existing index. Managed rg remains available through
+`zg --rg` and through the optional `full` MCP toolset. See the
+[Pipeline guide](./04-pipeline.md) for the distinction and the
+[MCP guide](./03-mcp.md) for tool inputs.
+
+When semantic discovery is selected because no sufficient exact anchor is
+available and the user asks whether conceptually related material exists
+locally, the agent makes at most one focused `zvec_grep_search` probe and stops
+when the results are not relevant. Exact quotations, configuration keys,
+filenames, regexes, and exhaustive occurrence requests stay on the exact route.
+
+## Verify the setup
+
+Check the server first:
+
+```bash
+zg --server status --check-ready
+```
+
+Then start a new agent session and confirm that the client-specific search tool
+is available. It is `zvec_grep_search` in Codex and Claude Code,
+`mcp__zvec_grep__zvec_grep_search` in Qwen Code and Qoder CLI, and
+`zvec_grep_zvec_grep_search` in OpenCode. With the optional `full` MCP toolset,
+Qoder CLI exposes managed rg as `mcp__zvec_grep__zvec_grep_rg`. For Qoder IDE,
+confirm after restart that the `zvec_grep` server and its tools appear; the exact
+host-qualified tool label remains part of the real-machine smoke test. If the
+MCP connection is unavailable, the same indexed search and optional managed-rg
+route remain available from the shell:
+
+```bash
+zg "where theme preferences are restored"
+zg --rg -F "loadTheme" src
+```
+
+## Permissions and remote data
+
+The server listens on loopback and has no token by default. See
+[Server authentication](./06-server.md#bearer-authentication) when a local Bearer
+token is required.
+
+MCP tool approval only authorizes calls to the local server. It does **not**
+authorize sending query text or workspace content to a remote Embedding
+provider. Remote Embedding asks separately on first use; see
+[Embedding models](./07-embedding.md#remote-embedding-and-authorization).
+
+## Remove an integration
+
+Use the same target names to remove only zvec-grep-managed entries:
+
+```bash
+zg --uninstall --target codex --yes
+zg --uninstall --target qwen --yes
+zg --uninstall --target qoder --yes
+zg --uninstall --target all --yes
+```
+
+Restart the agent or open a new session to apply the change. Uninstalling an
+agent integration does not delete repository indexes or the npm package.

package/docs/02-cli.md

@@ -0,0 +1,259 @@
+# CLI guide
+
+[Documentation](./README.md) · [Agents](./01-agents.md) ·
+[CLI](./02-cli.md) · [MCP](./03-mcp.md) · [Pipeline](./04-pipeline.md) ·
+[Architecture](./05-architecture.md) · [Server](./06-server.md) ·
+[Embedding](./07-embedding.md) · [Roadmap](./08-roadmap.md)
+
+The `zg` command is a search interface first. Positional arguments are always
+queries; maintenance operations use long action options so ordinary words such
+as `index`, `install`, and `status` never collide with commands. Use the
+installed CLI for version-specific help:
+
+To expose accidental use of the old command shape without making it an alias,
+a leading command-shaped word such as `query`, `index`, or `install` emits a
+warning on stderr and is still parsed as search input. Use `zg -- query` (or
+another literal word after `--`) to make that search intent explicit and
+suppress the warning.
+
+```bash
+zg --help
+zg --help search
+zg --help models
+zg --help file-types
+zg --help environment
+zg --index --help
+```
+
+## Interface overview
+
+| Form | Purpose |
+| --- | --- |
+| `zg <query>` | Search an index or run managed ripgrep |
+| `--index` | Build, update, rebuild, or drop a Workspace index |
+| `--status` | Inspect Workspace and index state |
+| `--install` / `--uninstall` | Manage agent integrations |
+| `--config` | Configure provider credentials and model defaults |
+| `--auth` | Manage Remote Embedding authorization |
+| `--server` | Manage the shared MCP server |
+| `--help` / `--version` | Show help or the installed version |
+
+## `zg`
+
+```text
+zg <query> [options]
+zg --hybrid <query> --fts <query> --vector <query> [--fuse]
+zg --rg [rg-options] <pattern> [path...]
+```
+
+Search routes:
+
+| Option | Meaning |
+| --- | --- |
+| positional query | Hybrid lexical and vector retrieval |
+| `--hybrid <query>` | Add an explicit hybrid query group |
+| `--fts <query>` | Add a ranked lexical query group |
+| `--vector <query>` | Add a semantic-only query group |
+| `--fuse` | Combine all groups into one ranked plan |
+| `--rg` | Run exhaustive managed ripgrep without an index |
+
+Result controls:
+
+| Option | Meaning |
+| --- | --- |
+| `--limit <n>` | Maximum returned items per group |
+| `--compact` | Force compact output intended for pipes |
+| `--preview none\|short\|full` | Indexed source preview size |
+| `--refresh background\|wait\|off` | Index refresh policy |
+| `--mode direct\|server\|auto` | Execution transport |
+| `--debug` | Print diagnostics to stderr |
+| `--trace` | Add per-hit indexed search trace |
+| `--prefer-symbol` | Prefer an exact indexed symbol |
+| `--symbol-type <type>` | Restrict results to a symbol type |
+| `--modified-after <time>` | Search files modified after a time |
+| `--modified-before <time>` | Search files modified before a time |
+
+Indexed CLI results are separated by query group and preserve the rank assigned
+inside that group. The CLI does not apply the MCP response's cross-group
+coverage/global-fill presentation. A result recalled by several groups appears
+under each of those groups. `--limit` continues to bound each group.
+
+Valid symbol types are `module`, `class`, `interface`, `function`, `value`, and
+`alias`.
+
+Common scope options for indexed search are `-g/--glob`, `--iglob`, `-t/--type`,
+and `-T/--type-not`. Managed rg additionally supports common ripgrep matching,
+context, discovery, encoding, and regex-engine flags.
+
+If no index exists, `zg` creates one with a local embedding model before the
+first indexed search. A configured local model is respected; a configured
+remote model is not used implicitly. Use `zg --index` when you want to choose a
+remote model, narrow the indexed paths, rebuild, or drop the index.
+
+Examples:
+
+```bash
+zg "theme preference persistence on startup"
+zg --fts "loadTheme" -g "src/**" -t ts
+zg --vector "where user preferences are restored" --limit 5
+zg "plugin lifecycle" --preview full
+zg --rg -i -C 2 -g "*.ts" "dark mode" src
+```
+
+See [Retrieval pipeline](./04-pipeline.md#3-query-through-one-search-layer) for
+route selection and freshness behavior.
+
+## `zg --index`
+
+```text
+zg --index [root] [options]
+zg --index [root] --rebuild [options]
+zg --index [root] --drop [--yes]
+```
+
+Core options:
+
+| Option | Meaning |
+| --- | --- |
+| `--embedding <model>` | Model for a new or rebuilt index |
+| `--rebuild` | Recreate an existing index |
+| `--drop` | Permanently remove the Workspace index |
+| `--yes` | Confirm `--drop` without a prompt |
+| `--reset-paths` | Replace stored file-selection settings |
+| `--mode direct\|server\|auto` | Execution transport |
+| `--api-key <key>` | One-command provider credential |
+| `--endpoint <url>` | Remote provider endpoint |
+| `--model-cache <path>` | Local model cache directory |
+| `--device <device>` | `auto`, `cpu`, `metal`, `vulkan`, or `cuda` |
+| `--embedding-concurrency <n>` | Concurrent Embedding tasks |
+| `--allow-remote` | Authorize Remote Embedding for this command |
+
+Local Potion embedding tasks run on worker threads. They default to two workers;
+`--embedding-concurrency` can override that value for larger machines.
+
+File discovery accepts `-g/--glob`, `--iglob`, `-t/--type`, `-T/--type-not`,
+`--hidden`, `--no-ignore`, `--ignore-file`, `--max-depth`, `--max-filesize`, and
+`-L/--follow`.
+
+Examples:
+
+```bash
+zg --index --embedding local/potion-code-16m-v2
+zg --index
+zg --index --rebuild --embedding local/jina-embeddings-v2-base-code
+zg --index --drop --yes
+```
+
+## `zg --status`
+
+```text
+zg --status [root] [--mode direct|server|auto] [--check-ready]
+```
+
+Status includes the selected root, index policy, stored schema and paths, file
+counts, refresh state, and a suggested next action. `--check-ready` preserves
+normal output and exits non-zero unless the index is ready, which is useful in
+scripts.
+
+## `zg --install` and `zg --uninstall`
+
+```text
+zg --install [--target codex|claude|qwen|qoder|opencode|cursor|all|auto] [--mcp-transport stdio|http] [--mcp-toolset agent|full] [--yes] [--force]
+zg --uninstall [--target codex|claude|qwen|qoder|opencode|cursor|all|auto] [--yes]
+```
+
+`--target` is repeatable. `qoder` is the single Qoder target and configures
+Qoder CLI and Qoder IDE together. `zg --install` also accepts:
+
+| Option | Meaning |
+| --- | --- |
+| `--mcp-transport <stdio\|http>` | MCP connection mode; default `stdio` |
+| `--mcp-toolset <agent\|full>` | Daemon MCP surface; default `agent` |
+| `--mcp-tool-timeout <seconds>` | Codex, Qwen Code, both Qoder clients, and OpenCode MCP timeout; default 600 seconds |
+| `--mcp-token-env <name>` | Environment variable containing the server token |
+| `--force` | Replace a conflicting unmanaged `zvec_grep` entry |
+
+See [Agent integrations](./01-agents.md) before using `--force`.
+
+## `zg --config`
+
+```text
+zg --config provider set <provider> --api-key <key>
+zg --config model set <model> [--endpoint <url> | --device <device>] [--default]
+```
+
+Examples:
+
+```bash
+zg --config provider set qwen --api-key "$DASHSCOPE_API_KEY"
+zg --config model set qwen/text-embedding-v4 --default
+zg --config model set local/potion-code-16m-v2 --device metal
+```
+
+Global configuration is stored in `~/.zvec-grep/config.json`. Existing indexes
+continue to use their stored model until explicitly rebuilt.
+
+## `zg --auth`
+
+```text
+zg --auth grant [root] --capability embedding --scope workspace [--embedding <model>]
+zg --auth status [root]
+zg --auth revoke [root]
+```
+
+Workspace grants are stored under `.zvec-grep/authorization.json` and shared by
+the CLI and MCP server. `--allow-remote` is the non-persistent alternative for
+one search or `--index` operation. `--embedding` selects the Remote Embedding model
+to authorize; it does not run embedding. It may be omitted when the model can be
+resolved from the existing Workspace index, `ZVEC_GREP_EMBEDDING`, or the global
+default, in that order.
+
+## `zg --server`
+
+```text
+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]
+```
+
+`on` starts the background daemon; `run` keeps it in the foreground. The server
+only accepts loopback listen addresses. The default public endpoint is
+`http://127.0.0.1:7999/mcp` with the `agent` toolset.
+
+See [Server and execution modes](./06-server.md) for mode selection, lifecycle,
+refresh, authentication, and logs. See [MCP](./03-mcp.md) for the tool contract.
+
+## Environment variables
+
+| Variable | Purpose |
+| --- | --- |
+| `ZVEC_GREP_HOME` | Override zvec-grep state directory |
+| `ZVEC_GREP_MODE` | Default `direct`, `server`, or `auto` transport |
+| `ZVEC_GREP_SERVER_URL` | Override the MCP server URL used by clients |
+| `ZVEC_GREP_SERVER_TOKEN` | Server/client Bearer token |
+| `ZVEC_GREP_SERVER_TOKEN_FILE` | File containing the server/client token |
+| `ZVEC_GREP_MCP_TOOLSET` | Default `agent` or `full` MCP surface |
+| `ZVEC_GREP_WATCHER_IDLE_TIMEOUT_SECONDS` | Seconds of workspace inactivity before the server releases its watcher; default `14400`, `0` disables idle eviction |
+| `ZVEC_GREP_EMBEDDING` | Default model for new indexes |
+| `ZVEC_GREP_API_KEY` | Embedding provider API key |
+| `ZVEC_GREP_ENDPOINT` | Remote Embedding endpoint |
+| `ZVEC_GREP_MODEL_CACHE` | Local model cache directory |
+| `ZVEC_GREP_DEVICE` | Local model device |
+| `DASHSCOPE_API_KEY` | Qwen API-key fallback after `ZVEC_GREP_API_KEY` |
+| `QWEN_API_KEY` | Qwen API-key fallback after `DASHSCOPE_API_KEY` |
+| `QWEN_HOME` | Qwen Code configuration directory used by `zg --install` |
+| `QODER_CONFIG_DIR` | Qoder CLI configuration directory used by `zg --install` |
+| `QODER_IDE_MCP_PATH` | Full Qoder IDE `mcp.json` path used by `zg --install` |
+| `QODER_IDE_EXECUTABLE` | Qoder IDE executable used for automatic install-target detection |
+
+Run `zg --help environment` for advanced variables, agent integration paths,
+scope, and detailed precedence. A new index selects its model in this order:
+explicit `--embedding`, `ZVEC_GREP_EMBEDDING`, the global default, then the
+built-in local default. Existing indexes continue to use their stored model
+unless `--embedding` and `--rebuild` explicitly change it.
+
+Embedding runtime values such as endpoint and device retain this order: explicit
+command option, Workspace snapshot, global configuration, then environment.
+`zg --index` forwards its `ZVEC_GREP_EMBEDDING` value in server and auto modes;
+direct MCP calls use the environment inherited when the daemon started.