@zvec/zvec-grep 0.1.6 → 0.1.8

package/README.md

@@ -3,9 +3,6 @@
 </p>
 
 <div align="center">
-  <p>
-    <a href="./docs/08-roadmap.md"><img src="https://img.shields.io/badge/status-work%20in%20progress-F59E0B?style=for-the-badge" alt="Work in progress" /></a>
-  </p>
   <picture>
     <source media="(prefers-color-scheme: dark)" srcset="./.github/assets/zg-logo-dark.svg">
     <img src="./.github/assets/zg-logo.svg" width="150" alt="zg logo" />
@@ -23,7 +20,7 @@
   <p>
     <a href="#tour">🎬 <strong>Tour</strong></a> |
     <a href="#features">💫 <strong>Features</strong></a> |
-    <a href="#quickstart">🚀 <strong>Quickstart</strong></a> |
+    <a href="#try-it-yourself">🚀 <strong>Try it yourself</strong></a> |
     <a href="./docs/README.md">📚 <strong>Docs</strong></a> |
     <a href="#benchmarks">📊 <strong>Benchmarks</strong></a> |
     <a href="#community">🤝 <strong>Community</strong></a>
@@ -39,91 +36,130 @@ terminal, or let your agent use it for you.
 ## 🎬 See it in action
 
 <div align="center">
-  <img src="./.github/assets/zvec-grep-tour.gif" width="1000" alt="Install the agent integration, index a repository, and let the agent search it with zvec-grep" />
+  <img src="./.github/assets/zvec-grep-tour.gif" width="1000" alt="Install the agent integration, index a workspace, and let the agent search it with zvec-grep" />
 </div>
 
-Install the integration once, index the workspace, then search from the terminal
-or ask your agent naturally.
-
 <a id="features"></a>
 
 ## 💫 Why zg?
 
-- **Works out of the box** — one guided install connects zg to your agent on
-  macOS, Linux, or Windows; ask naturally, with no search syntax to learn.
-- **All-in-one retrieval layer** — semantic discovery, BM25-ranked retrieval,
-  exact text, and regex search all stay behind zg.
-- **Agent- and human-friendly** — compact, file-oriented context for agents
-  and readable terminal output for people, with less noise for both.
-- **Local first, permission aware** — ripgrep, indexes, and local models stay
-  on your machine; remote embeddings require explicit authorization.
-
-<a id="quickstart"></a>
+- **Ready for humans and agents** — install once, index once, then use the same
+  workspace from the CLI or your agent on macOS, Linux, and Windows.
+- **Search beyond keywords** — discover by meaning, rank by relevance, then
+  verify with exact text or regex when needed.
+- **Multi-format search** — search source code, documents, and structured data
+  while preserving useful structure and source locations.
+- **Less searching, less context** — ranked, source-linked results surface the
+  right evidence with fewer tool calls, fewer tokens, and less noise.
+- **Local by default** — files, indexes, and local models stay on your machine;
+  remote embeddings receive data only with your permission.
 
-## 🚀 Quickstart
+<a id="try-it-yourself"></a>
 
-Requires Node.js 22 or newer on macOS, Linux, or Windows.
+## 🚀 Try it yourself
 
-### 1. Install and connect your agent
+### 1. Set up a sample bookshelf
 
 ```bash
+# Requires Node.js 22 or newer.
 npm install -g @zvec/zvec-grep
-zg install
-```
 
-`zg install` detects Codex, Claude Code, Cursor, and OpenCode and configures the
-local MCP integration. See [Agent integrations](./docs/01-agents.md) for managed
-configuration, permissions, and uninstall instructions. You can also select one
-explicitly:
+mkdir zg-mystery && cd zg-mystery
+curl --retry 3 --retry-all-errors --progress-bar -fL \
+  -o alice-in-wonderland.txt https://raw.githubusercontent.com/GITenberg/Alice-s-Adventures-in-Wonderland_11/master/11.txt \
+  -o sherlock-holmes.txt https://raw.githubusercontent.com/GITenberg/The-Memoirs-of-Sherlock-Holmes_834/master/834.txt
 
-```bash
-zg install --target codex --yes
+zg index --embedding local/potion-retrieval-32m
 ```
 
-### 2. Index your repository
+### 2. Choose how to search
+
+#### For agents: ask with OpenCode
+
+With [OpenCode](https://opencode.ai/) configured:
 
 ```bash
-cd your-repository
-zg index --embedding local/potion-code-16m-v2
+zg install --target opencode --yes
+opencode run --model opencode/deepseek-v4-flash-free \
+  "An unseen creature left a few marks. What did the detective infer? Cite local evidence."
 ```
 
-This quickstart uses the lightweight
-[Potion Code v2](./docs/07-embedding.md) model so you can build the first index
-quickly. The first run downloads it; the index stays in `.zvec-grep/`, and later
-updates only need `zg index`. See the
-[retrieval pipeline](./docs/04-pipeline.md#indexing) to control scope, updates, and
-rebuilds.
+OpenCode chooses zg on its own—the prompt does not name a tool.
 
-### 3. Ask your agent
+<details>
+<summary><strong>See the full agent run and answer</strong></summary>
 
 ```text
-My app forgets dark mode every time I refresh. Find out why.
+⚙ zvec_grep_zvec_grep_search {"root":".../zg-mystery","query":"An unseen creature left a few marks. What did the detective infer?","fts":["marks","unseen creature","inferred","detective"],"fuse":true}
+→ Read sherlock-holmes.txt [offset=5440, limit=120]
+
+Answer:
+The detective is Sherlock Holmes in *The Adventure of the Crooked Man*.
+From the animal's foot-marks, he inferred:
+
+- It was not a dog, cat, monkey, or other familiar creature: its print had
+  five foot-pads, long nails, and was nearly as large as a dessert-spoon
+  (sherlock-holmes.txt:5479-5486).
+- It had a long body and very short legs: nearly two feet long, but with a
+  stride of only about three inches (sherlock-holmes.txt:5497-5502).
+- It was carnivorous because it climbed the curtain toward a canary's cage
+  (sherlock-holmes.txt:5509-5510).
+- It was probably from the weasel or stoat tribe, though unusually large
+  (sherlock-holmes.txt:5514-5516).
+
+Holmes also inferred that a man entered through the window with it and later
+left with the key (sherlock-holmes.txt:5464-5470, 5527-5528).
 ```
 
-The agent uses zg for semantic discovery and ranked keyword retrieval, while
-exact lexical lookup stays with native grep or rg. The
-[MCP guide](./docs/03-mcp.md) describes the default search tool and the optional
-full toolset, which retains managed rg.
+</details>
+
+#### For humans: search directly
 
-To search directly from the terminal, use the same local layer. See the
-[CLI guide](./docs/02-cli.md) for routes, filters, and output controls.
+Search the same bookshelf directly, without an agent:
 
 ```bash
-zg query --human "theme preference persistence on startup" --limit 3
+zg query --human "An unseen creature left a few marks. What did the detective infer?" --limit 3
 ```
 
+zg returns the relevant passages from `sherlock-holmes.txt`, ranked ahead of
+`alice-in-wonderland.txt`.
+
 <a id="benchmarks"></a>
 
 ## 📊 Benchmarks
 
-> 🚧 **Work in progress.**
+zg helps agents find relevant evidence faster by **narrowing the effective
+search space** — using **fewer tokens, tool calls, and less time** while
+preserving answer quality.
+
+Each benchmark follows a **controlled, reproducible paired A/B protocol**: the
+same agent runs the same pinned tasks with identical model, prompt, environment,
+and limits; **only `zg` access and usage guidance differ**.
+
+<img src="./.github/assets/benchmark-comparison-v2.svg" alt="Paired baseline and zvec-grep comparison for SWE-QA-Bench and BrowseComp-Plus" width="900" />
+
+| Benchmark | Answer&nbsp;quality&nbsp;↑ | Avg.&nbsp;input&nbsp;tokens&nbsp;↓ | Avg.&nbsp;tool&nbsp;calls&nbsp;↓ | Avg.&nbsp;agent&nbsp;time&nbsp;↓ |
+| --- | ---: | ---: | ---: | ---: |
+| [**SWE-QA-Bench**](./benchmarks/swe-qa-bench/README.md)<br>20 tasks · Codebase QA | Judge Score<br>80.42&nbsp;→&nbsp;81.92 | 558,651&nbsp;→&nbsp;294,262 | 23.42&nbsp;→&nbsp;9.70 | 127.5s&nbsp;→&nbsp;79.7s |
+| [**BrowseComp-Plus**](./benchmarks/browse-comp-plus/README.md)<br>80 cases · Deep-research QA | Accuracy<br>90.00%&nbsp;→&nbsp;90.00% | 2.04M&nbsp;→&nbsp;1.19M | 22.70&nbsp;→&nbsp;14.24 | 284.8s&nbsp;→&nbsp;199.3s |
+
+Values show **Baseline → zg**.
 
-## 🗺️ Roadmap
+See the [benchmark documentation](./benchmarks/README.md) for full results and
+reproduction details.
 
-zg is moving toward richer multimodal formats, stronger hybrid retrieval, a
-more out-of-the-box experience, and support from desktop to mobile.
+## 📚 Documentation
 
-Explore the full [Roadmap](./docs/08-roadmap.md).
+| Guide | What you can do |
+| :--- | :--- |
+| [Agent integrations](./docs/01-agents.md) | Connect zg to Codex, Claude Code, Cursor, or OpenCode and verify that it works. |
+| [CLI guide](./docs/02-cli.md) | Search, index, and manage your local workspaces from the terminal. |
+| [MCP guide](./docs/03-mcp.md) | Understand which zg tools your agent can use and how access is secured. |
+| [Retrieval pipeline](./docs/04-pipeline.md) | Choose what to index, keep it fresh, and get better search results. |
+| [Architecture](./docs/05-architecture.md) | See how zg handles your query and where your data stays. |
+| [Server and execution modes](./docs/06-server.md) | Choose between one-off commands and a long-running local server. |
+| [Embedding models](./docs/07-embedding.md) | Pick the right model for speed, search quality, privacy, and your hardware. |
+| [Roadmap](./docs/08-roadmap.md) | See what is coming next and help shape zg's priorities. |
 
 <a id="community"></a>
 

package/README_CN.md

@@ -3,9 +3,6 @@
 </p>
 
 <div align="center">
-  <p>
-    <a href="./docs/08-roadmap.md"><img src="https://img.shields.io/badge/status-work%20in%20progress-F59E0B?style=for-the-badge" alt="项目开发中" /></a>
-  </p>
   <picture>
     <source media="(prefers-color-scheme: dark)" srcset="./.github/assets/zg-logo-dark.svg">
     <img src="./.github/assets/zg-logo.svg" width="150" alt="zg logo" />
@@ -23,7 +20,7 @@
   <p>
     <a href="#tour">🎬 <strong>功能演示</strong></a> |
     <a href="#features">💫 <strong>核心特性</strong></a> |
-    <a href="#quickstart">🚀 <strong>快速开始</strong></a> |
+    <a href="#try-it-yourself">🚀 <strong>动手体验</strong></a> |
     <a href="./docs/README.md">📚 <strong>文档</strong></a> |
     <a href="#benchmarks">📊 <strong>性能测试</strong></a> |
     <a href="#community">🤝 <strong>社区</strong></a>
@@ -31,94 +28,133 @@
 </div>
 
 **zg**（**z**vec-**g**rep）将 ripgrep、BM25 与向量检索统一在一个
-[本地优先的检索入口](./docs/05-architecture.md)中。无论是人在终端中搜索，
-还是让 Agent 自主检索，只用 zg 即可。
+[本地优先的检索入口](./docs/05-architecture.md)中。既可以由人在终端中搜索，
+也可以让 Agent 根据问题选择合适的本地检索方式。
 
 <a id="tour"></a>
 
 ## 🎬 功能演示
 
 <div align="center">
-  <img src="./.github/assets/zvec-grep-tour.gif" width="1000" alt="安装 Agent 集成、为仓库建索引并让 Agent 使用 zvec-grep 搜索代码" />
+  <img src="./.github/assets/zvec-grep-tour.gif" width="1000" alt="安装 Agent 集成、为工作区建索引并让 Agent 使用 zvec-grep 检索本地内容" />
 </div>
 
-只需安装一次集成并为工作区建索引，之后既可以在终端中搜索，也可以直接向
-Agent 提问。
-
 <a id="features"></a>
 
 ## 💫 为什么选择 zg？
 
-- **开箱即用，零学习成本**：一套引导式安装即可在 macOS、Linux 和 Windows
-  上接入 Agent；直接用自然语言提问，无需学习搜索语法。
-- **一站式检索层**：语义发现、BM25 相关性检索、精确文本与正则搜索
-  都由 zg 统一提供。
-- **对 Agent 和开发者都友好**：为 Agent 提供紧凑、围绕文件组织的上下文，
-  为开发者提供易读的终端输出，双方都能减少无关噪声。
-- **本地优先、权限明确**：ripgrep、索引与本地模型均留在本机；远程 Embedding
-  需要显式授权。
-
-<a id="quickstart"></a>
+- **人与 Agent 开箱即用**：安装一次、索引一次，即可在 macOS、Linux 和
+  Windows 上通过 CLI 或 Agent 复用同一个工作区。
+- **不止关键词搜索**：先按语义发现内容、按相关性排序，再在需要时使用精确文本
+  或正则完成验证。
+- **多格式检索**：搜索源代码、文档和结构化数据，同时保留有用的内容结构与
+  来源位置。
+- **更少搜索，更少上下文**：经过排序并保留来源的结果，可以减少工具调用、
+  Token 消耗与无关噪声，更快找到所需证据。
+- **默认本地运行**：文件、索引与本地模型都留在本机；只有经过你的授权，远程
+  Embedding 服务才能接收数据。
 
-## 🚀 快速开始
+<a id="try-it-yourself"></a>
 
-需要 Node.js 22 或更新版本，支持 macOS、Linux 和 Windows。
+## 🚀 动手体验
 
-### 1. 安装并连接 Agent
+### 1. 准备示例书架
 
 ```bash
+# 需要 Node.js 22 或更新版本。
 npm install -g @zvec/zvec-grep
-zg install
-```
 
-`zg install` 会检测 Codex、Claude Code、Cursor 和 OpenCode，并配置本地 MCP 集成。
-查看 [Agent 集成指南](./docs/01-agents.md)，了解配置变更、权限和卸载方式。
-也可以明确指定目标：
+mkdir zg-mystery && cd zg-mystery
+curl --retry 3 --retry-all-errors --progress-bar -fL \
+  -o alice-in-wonderland.txt https://raw.githubusercontent.com/GITenberg/Alice-s-Adventures-in-Wonderland_11/master/11.txt \
+  -o sherlock-holmes.txt https://raw.githubusercontent.com/GITenberg/The-Memoirs-of-Sherlock-Holmes_834/master/834.txt
 
-```bash
-zg install --target codex --yes
+zg index --embedding local/potion-retrieval-32m
 ```
 
-### 2. 为仓库建索引
+### 2. 选择检索方式
+
+#### Agent：通过 OpenCode 提问
+
+配置好 [OpenCode](https://opencode.ai/) 后：
 
 ```bash
-cd your-repository
-zg index --embedding local/potion-code-16m-v2
+zg install --target opencode --yes
+opencode run --model opencode/deepseek-v4-flash-free \
+  "An unseen creature left a few marks. What did the detective infer? Cite local evidence."
 ```
 
-快速开始使用轻量的 [Potion Code v2](./docs/07-embedding.md)，以便快速完成首次建索引。
-第一次运行会下载模型，索引保存在 `.zvec-grep/` 下；后续更新只需运行
-`zg index`。查看 [检索 Pipeline](./docs/04-pipeline.md#indexing)，进一步控制检索范围、
-增量更新和重建。
+Prompt 中没有指定任何工具，OpenCode 会自主选择 zg。
 
-### 3. 直接向 Agent 提问
+<details>
+<summary><strong>展开查看完整 Agent 调用与回答</strong></summary>
 
 ```text
-每次刷新页面，应用都会忘记深色模式。帮我找出原因。
+⚙ zvec_grep_zvec_grep_search {"root":".../zg-mystery","query":"An unseen creature left a few marks. What did the detective infer?","fts":["marks","unseen creature","inferred","detective"],"fuse":true}
+→ Read sherlock-holmes.txt [offset=5440, limit=120]
+
+Answer:
+The detective is Sherlock Holmes in *The Adventure of the Crooked Man*.
+From the animal's foot-marks, he inferred:
+
+- It was not a dog, cat, monkey, or other familiar creature: its print had
+  five foot-pads, long nails, and was nearly as large as a dessert-spoon
+  (sherlock-holmes.txt:5479-5486).
+- It had a long body and very short legs: nearly two feet long, but with a
+  stride of only about three inches (sherlock-holmes.txt:5497-5502).
+- It was carnivorous because it climbed the curtain toward a canary's cage
+  (sherlock-holmes.txt:5509-5510).
+- It was probably from the weasel or stoat tribe, though unusually large
+  (sherlock-holmes.txt:5514-5516).
+
+Holmes also inferred that a man entered through the window with it and later
+left with the key (sherlock-holmes.txt:5464-5470, 5527-5528).
 ```
 
-Agent 会始终通过 zg 完成语义发现、关键词相关性检索与穷尽精确匹配。你无需
-选择或调用其他搜索工具。[MCP 指南](./docs/03-mcp.md)介绍了 Agent 使用的两个工具。
+</details>
+
+#### 用户：直接检索
 
-也可以直接在终端中使用同一个本地检索层。查看 [CLI 指南](./docs/02-cli.md)，了解
-搜索方式、过滤条件和输出控制。
+不通过 Agent，直接搜索同一个书架：
 
 ```bash
-zg query --human "theme preference persistence on startup" --limit 3
+zg query --human "An unseen creature left a few marks. What did the detective infer?" --limit 3
 ```
 
+zg 会将 `sherlock-holmes.txt` 中的相关段落排在
+`alice-in-wonderland.txt` 前面。
+
 <a id="benchmarks"></a>
 
 ## 📊 性能测试
 
-> 🚧 **正在完善中。**
+zg 通过**缩小有效搜索空间**，帮助 Agent 更快找到相关证据 —— 在保持回答质量的同时，使用**更少的 Token、工具调用和时间**。
+
+每项测试均采用**受控、可复现的配对 A/B 评测**：同一个 Agent 在完全相同的模型、Prompt、环境和资源限制下执行同一组预先固定的任务；**实验组仅额外提供 `zg` 工具及其使用说明**。
+
+<img src="./.github/assets/benchmark-comparison-cn-v2.svg" alt="SWE-QA-Bench 和 BrowseComp-Plus 中 Baseline 与 zvec-grep 的配对对比" width="900" />
+
+| 测试 | 回答质量&nbsp;↑ | 平均输入&nbsp;Token&nbsp;↓ | 平均工具调用&nbsp;↓ | 平均&nbsp;Agent&nbsp;耗时&nbsp;↓ |
+| --- | ---: | ---: | ---: | ---: |
+| [**SWE-QA-Bench**](./benchmarks/swe-qa-bench/README_CN.md)<br>20 个任务 · 代码库 QA | 评审得分<br>80.42&nbsp;→&nbsp;81.92 | 558,651&nbsp;→&nbsp;294,262 | 23.42&nbsp;→&nbsp;9.70 | 127.5s&nbsp;→&nbsp;79.7s |
+| [**BrowseComp-Plus**](./benchmarks/browse-comp-plus/README_CN.md)<br>80 个样例 · 深度研究 QA | 准确率<br>90.00%&nbsp;→&nbsp;90.00% | 2.04M&nbsp;→&nbsp;1.19M | 22.70&nbsp;→&nbsp;14.24 | 284.8s&nbsp;→&nbsp;199.3s |
+
+表中数值均按 **Baseline → zg** 展示。
 
-## 🗺️ Roadmap
+完整结果和复现细节参见[性能测试文档](./benchmarks/README_CN.md)。
 
-zg 正在迈向更丰富的多模态格式、更强的混合检索、更开箱即用的体验，以及从
-桌面端到移动端的全平台支持。
+## 📚 文档
 
-查看完整 [Roadmap](./docs/08-roadmap.md)。
+| 指南 | 你可以完成什么 |
+| :--- | :--- |
+| [Agent 集成](./docs/01-agents.md) | 将 zg 接入 Codex、Claude Code、Cursor 或 OpenCode，并验证是否正常工作。 |
+| [CLI 指南](./docs/02-cli.md) | 在终端中搜索、索引和管理本地工作区。 |
+| [MCP 指南](./docs/03-mcp.md) | 了解 Agent 可以使用哪些 zg 工具，以及访问权限如何受到保护。 |
+| [检索 Pipeline](./docs/04-pipeline.md) | 选择索引范围、保持内容新鲜，并获得更好的检索结果。 |
+| [架构](./docs/05-architecture.md) | 了解 zg 如何处理查询，以及数据会保留在哪里。 |
+| [服务端与执行模式](./docs/06-server.md) | 在一次性命令和长期运行的本地服务之间选择。 |
+| [Embedding 模型](./docs/07-embedding.md) | 根据速度、检索质量、隐私和本机硬件选择合适的模型。 |
+| [Roadmap](./docs/08-roadmap.md) | 了解接下来的产品方向，并参与影响 zg 的优先级。 |
 
 <a id="community"></a>
 

package/dist/cli/args.js

@@ -146,6 +146,9 @@ export function parseArgs(args) {
         else if (arg === "--force-direct") {
             options.forceDirect = true;
         }
+        else if (arg === "--stdio") {
+            options.serverStdio = true;
+        }
         else if (isLongOptionWithValue(arg, "--mcp-toolset")) {
             options.mcpToolset = parseMcpToolset(valueFromLongOption(arg));
         }
@@ -182,6 +185,12 @@ export function parseArgs(args) {
         else if (arg === "--mcp-token-env") {
             options.installMcpTokenEnv = parseEnvironmentVariable(readOptionValue(args, ++index, arg), arg);
         }
+        else if (isLongOptionWithValue(arg, "--mcp-transport")) {
+            options.installMcpTransport = parseMcpInstallTransport(valueFromLongOption(arg));
+        }
+        else if (arg === "--mcp-transport") {
+            options.installMcpTransport = parseMcpInstallTransport(readOptionValue(args, ++index, arg));
+        }
         else if (arg === "--yes") {
             options.yes = true;
         }
@@ -523,7 +532,6 @@ function validateCliShape(command, options, positionals) {
         [options.hybridQueries?.length, "--hybrid"],
         [options.routes?.length, "--fts/--vector"],
         [options.fuse, "--fuse"],
-        [options.debug, "--debug"],
         [options.trace, "--trace"],
         [options.human, "--human"],
         [options.preview, "--preview"],
@@ -538,6 +546,9 @@ function validateCliShape(command, options, positionals) {
     if (command !== "query" && queryOnly) {
         throw new Error(`${queryOnly} can only be used with zg query`);
     }
+    if (options.debug && command !== "query" && command !== "index") {
+        throw new Error("--debug can only be used with zg query or zg index");
+    }
     const sharedSelection = firstEnabledOption([
         [options.globs?.length, "--glob"],
         [options.insensitiveGlobs?.length, "--iglob"],
@@ -602,12 +613,16 @@ function validateCliShape(command, options, positionals) {
         throw new Error("--default can only be used with zg config model set");
     }
     if (command === "server") {
-        if (!options.serverAction) {
-            throw new Error("zg server requires on, off, status, or run");
+        if (!options.serverAction && !options.serverStdio) {
+            throw new Error("zg server requires on, off, status, run, or --stdio");
+        }
+        if (options.serverAction && options.serverStdio) {
+            throw new Error("--stdio cannot be combined with a server action");
         }
         if (options.listen !== undefined &&
             options.serverAction !== "run" &&
-            options.serverAction !== "on") {
+            options.serverAction !== "on" &&
+            !options.serverStdio) {
             throw new Error("--listen can only be used with zg server on or run");
         }
         if (options.serverTokenFile !== undefined &&
@@ -616,12 +631,16 @@ function validateCliShape(command, options, positionals) {
         }
         if (options.mcpToolset !== undefined &&
             options.serverAction !== "on" &&
-            options.serverAction !== "run") {
+            options.serverAction !== "run" &&
+            !options.serverStdio) {
             throw new Error("--mcp-toolset can only be used with zg server on or run");
         }
     }
-    else if (options.mcpToolset !== undefined) {
-        throw new Error("--mcp-toolset can only be used with zg server on or run");
+    else if (options.mcpToolset !== undefined && command !== "install") {
+        throw new Error("--mcp-toolset can only be used with zg server on, run, --stdio, or zg install");
+    }
+    else if (options.serverStdio !== undefined) {
+        throw new Error("--stdio can only be used with zg server");
     }
     if (options.rg &&
         (hasExplicitRoutes(options) || options.hybridQueries?.length)) {
@@ -679,6 +698,14 @@ function validateCliShape(command, options, positionals) {
     if (options.installMcpTokenEnv !== undefined && command !== "install") {
         throw new Error("--mcp-token-env can only be used with zg install");
     }
+    if (options.installMcpTransport !== undefined && command !== "install") {
+        throw new Error("--mcp-transport can only be used with zg install");
+    }
+    if (command === "install" &&
+        options.installMcpTransport !== "http" &&
+        options.installMcpTokenEnv !== undefined) {
+        throw new Error("--mcp-token-env requires --mcp-transport http");
+    }
     if (options.force && command !== "install") {
         throw new Error("--force can only be used with zg install");
     }
@@ -743,6 +770,7 @@ function validateCliShape(command, options, positionals) {
             options.ignoreFiles?.length ||
             options.maxDepth !== undefined ||
             options.maxFileSizeBytes !== undefined ||
+            options.debug ||
             options.follow ||
             options.embeddingConcurrency)) {
         throw new Error("zg index --drop cannot be combined with indexing options");
@@ -1014,6 +1042,11 @@ function parseEnvironmentVariable(value, option) {
     }
     return value;
 }
+function parseMcpInstallTransport(value) {
+    if (value === "stdio" || value === "http")
+        return value;
+    throw new Error("--mcp-transport must be stdio or http");
+}
 function parseByteSize(value, option) {
     const match = value.trim().match(/^(\d+)([KMGT])?$/i);
     if (!match) {