@zvec/zvec-grep 0.2.0 → 0.2.2

package/docs/01-agents.md

@@ -17,13 +17,22 @@ managed-rg route.
 | 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` | `~/.config/opencode/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`, `OPENCODE_CONFIG`, and
+`CODEX_HOME`, `CLAUDE_CONFIG_DIR`, `QWEN_HOME`, `QODER_CONFIG_DIR`,
+`QODER_IDE_MCP_PATH`, `QODER_IDE_EXECUTABLE`, `OPENCODE_CONFIG`, and
 `CURSOR_CONFIG_DIR`.
 
+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:
@@ -38,6 +47,7 @@ For scripts or repeatable setup, select targets explicitly:
 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
 ```
 
@@ -45,16 +55,73 @@ 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, and managed server
-   trust for Qwen Code;
+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. If an unmanaged `zvec_grep` entry
-already exists, inspect it before using `--force` to replace it.
+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.
 
@@ -103,10 +170,13 @@ 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
-`zvec_grep_zvec_grep_search` in OpenCode. If the MCP connection is unavailable,
-the same indexed search and optional managed-rg route remain available from the
-shell:
+`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 query "where theme preferences are restored"
@@ -131,6 +201,7 @@ 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
 ```
 

package/docs/02-cli.md

@@ -146,17 +146,18 @@ scripts.
 ## `zg install` and `zg uninstall`
 
 ```text
-zg install [--target codex|claude|qwen|opencode|cursor|all|auto] [--mcp-transport stdio|http] [--mcp-toolset agent|full] [--yes] [--force]
-zg uninstall [--target codex|claude|qwen|opencode|cursor|all|auto] [--yes]
+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. `zg install` also accepts:
+`--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, and OpenCode MCP timeout; default 600 seconds |
+| `--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 |
 
@@ -221,6 +222,7 @@ refresh, authentication, and logs. See [MCP](./03-mcp.md) for the tool contract.
 | `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 |
@@ -229,6 +231,9 @@ refresh, authentication, and logs. See [MCP](./03-mcp.md) for the tool contract.
 | `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:

package/docs/06-server.md

@@ -99,6 +99,19 @@ zg server off
 zg server on --mcp-toolset full
 ```
 
+The Server releases a Workspace watcher and its lightweight runtime after four
+hours without a client request or a relevant file-system change. Periodic
+reconciliation does not extend this idle deadline. To select another timeout,
+set the number of seconds before starting or restarting the Server:
+
+```bash
+export ZVEC_GREP_WATCHER_IDLE_TIMEOUT_SECONDS=7200
+zg server off
+zg server on
+```
+
+Set the value to `0` to keep activated watchers until the Server stops.
+
 ## Configure the mode
 
 Choose a mode for one command:

package/docs/07-embedding.md

@@ -15,7 +15,13 @@ zg index --embedding local/potion-code-16m-v2
 ```
 
 Local models keep workspace content and query text on the machine. Their files
-are downloaded on first use and cached under `~/.zvec-grep/models` by default.
+are downloaded from Hugging Face on first use and cached under
+`~/.zvec-grep/models` by default. If a pinned Hugging Face artifact cannot be
+downloaded, zvec-grep automatically falls back to its pinned, integrity-checked
+ModelScope copy. A complete ModelScope snapshot is reused on later runs without
+retrying Hugging Face. ModelScope downloads use a separate `modelscope` cache
+subdirectory.
+
 Remote models avoid local inference but send disclosed query or workspace
 content to the configured provider after authorization.
 
@@ -152,6 +158,27 @@ Before granting access, confirm that the workspace content is permitted to be
 sent to the selected provider and endpoint. MCP tool approval is separate from
 this data authorization.
 
+When Qoder CLI reports that it has no handler for `elicitation/create`, or
+declines or cancels without displaying the form, the `AGENTS.md` guidance
+installed by `zg install --target qoder` uses the exact `AskUserQuestion` tool
+as a compatibility path. It offers workspace approval, local FTS only, or
+cancel.
+
+Qoder IDE uses the exact native tool name `ask_user_question`. Because Qoder IDE
+does not provide a supported global Rules location, the installer does not
+write equivalent IDE guidance. In stdio mode, the zvec-grep bridge instead
+turns a missing `elicitation/create` handler into an actionable error directing
+the top-level IDE agent to present the same choices with `ask_user_question`.
+This path still requires an end-to-end smoke test in a real Qoder IDE session.
+
+Either path runs the Workspace grant only after explicit approval and retries
+the original MCP search once. Choosing local FTS instead removes
+vector-producing query routes, sets `autoUpdate` to `false`, and keeps retrieval
+local without refreshing the remote-embedding index; a headless session never
+grants access automatically. Neither question tool should collect a token, API
+key, or password. `--allow-remote` is not a substitute for this path because it
+authorizes only the current CLI command, not a later MCP retry.
+
 ## Input length and truncation
 
 zvec-grep uses the selected model's input limit when it creates fragments, but

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zvec/zvec-grep",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Agent-friendly hybrid workspace search across code and non-code content.",
   "type": "module",
   "license": "Apache-2.0",
@@ -74,7 +74,7 @@
     "@modelcontextprotocol/node": "2.0.0",
     "@modelcontextprotocol/server": "2.0.0",
     "@vscode/ripgrep": "^1.18.0",
-    "@zvec/zvec": "^0.7.0",
+    "@zvec/zvec": "^0.7.1",
     "jsonc-parser": "^3.3.1",
     "tree-sitter-wasms": "^0.1.13",
     "web-tree-sitter": "^0.20.8",