@zvec/zvec-grep 0.1.6 → 0.1.7

package/README.md

@@ -23,7 +23,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,7 +39,7 @@ 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
@@ -49,81 +49,160 @@ or ask your agent naturally.
 
 ## 💫 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.
+- **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.
 
-<a id="quickstart"></a>
+<a id="try-it-yourself"></a>
 
-## 🚀 Quickstart
+## 🚀 Try it yourself
 
-Requires Node.js 22 or newer on macOS, Linux, or Windows.
+Requires Node.js 22 or newer and a configured
+[OpenCode](https://opencode.ai/) installation. The agent example explicitly
+selects a free model, so it does not depend on your default provider.
 
-### 1. Install and connect your agent
+### 1. Set up a sample bookshelf
 
 ```bash
 npm install -g @zvec/zvec-grep
-zg install
-```
+zg install --target opencode --yes
 
-`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 -L https://www.gutenberg.org/files/11/11-0.txt -o alice-in-wonderland.txt
+curl -L https://www.gutenberg.org/files/345/345-0.txt -o dracula.txt
+curl -L https://www.gutenberg.org/files/84/84-0.txt -o frankenstein.txt
+curl -L https://www.gutenberg.org/files/834/834-0.txt -o sherlock-holmes.txt
 
-```bash
-zg install --target codex --yes
+zg index --embedding local/potion-retrieval-32m
 ```
 
-### 2. Index your repository
+This creates a small bookshelf of four public-domain novels and indexes it
+locally with Potion Retrieval.
+
+Installation starts the shared daemon immediately. The default MCP transport is
+stdio: the agent runs `zg server --stdio`, which safely starts or reuses it
+again after a reboot. Advanced users can keep direct HTTP configuration with
+`zg install --mcp-transport http` and `zg server on`.
+
+Use `zg install --mcp-toolset full` when the installed MCP integration should
+also expose managed rg, index, and status tools. The default is `agent`.
+
+### 2. Choose how to search
+
+#### For agents: ask with OpenCode
 
 ```bash
-cd your-repository
-zg index --embedding local/potion-code-16m-v2
+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.
-
-### 3. Ask your agent
+OpenCode chooses zg on its own—the prompt does not name a tool. Query rewrites
+may vary by model, but a typical run looks like this:
 
 ```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.
+#### 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 the
+other novels.
+
 <a id="benchmarks"></a>
 
 ## 📊 Benchmarks
 
-> 🚧 **Work in progress.**
-
-## 🗺️ Roadmap
-
-zg is moving toward richer multimodal formats, stronger hybrid retrieval, a
-more out-of-the-box experience, and support from desktop to mobile.
-
-Explore the full [Roadmap](./docs/08-roadmap.md).
+zg is a general-purpose retrieval tool. Current benchmarks cover code and text
+retrieval.
+
+### Repository code retrieval
+
+We use [SWE-QA-Bench](https://github.com/peng-weihan/SWE-QA-Bench), which
+requires cross-file and multi-hop reasoning over real-world codebases.
+
+- **Coverage:** 20 retrieval-intensive tasks covering the paper's four
+  top-level categories—**What, Where, How, and Why**—across 8 intentions and
+  11 repositories.
+- **Agent:** Claude Code with **Claude Opus 5**.
+- **Embedding:** **Qwen3.7 Text Embedding** for the zg profile.
+- **Protocol:** 3 runs per task and profile.
+
+| Profile | Judge /100 ↑ | Input tokens ↓ | Tool calls ↓ | Time (s) ↓ | Cost ↓ |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| Native tools | 80.42 | 558,651 | 23.42 | 127.5 | $0.905 |
+| Native tools + zg | 81.92 | 294,262 | 9.70 | 79.7 | $0.558 |
+| Change | **+1.50 pp** | **−47.3%** | **−58.6%** | **−37.5%** | **−38.3%** |
+
+Across 20 tasks × 3 runs, zg increased the Judge score by 1.50 points while
+reducing input tokens by 47.3%, tool calls by 58.6%, execution time by 37.5%,
+and cost by 38.3%.
+
+### Large-scale text retrieval
+
+We use [BrowseComp-Plus](https://github.com/texttron/BrowseComp-Plus), which
+requires multi-document evidence retrieval over a fixed web corpus. The
+evaluation includes 30 queries covering 10 mapped topics and three
+evidence-breadth levels, with 3 runs per profile.
+
+| Profile | Accuracy ↑ | Evidence recall ↑ | Search calls ↓ | Input tokens ↓ | Time (s) ↓ | Cost ↓ |
+| --- | ---: | ---: | ---: | ---: | ---: | ---: |
+| Agent + BM25 | TBD | TBD | TBD | TBD | TBD | TBD |
+| Agent + zg | TBD | TBD | TBD | TBD | TBD | TBD |
+| Change | TBD | TBD | TBD | TBD | TBD | TBD |
+
+Across 30 queries × 3 runs, zg changed accuracy by TBD pp, evidence recall by
+TBD pp, search calls by TBD%, input tokens by TBD%, time by TBD%, and cost by
+TBD%.
+
+To reproduce the evaluation, follow the
+[benchmark guide](./benchmarks/README.md) for environment setup, pinned
+revisions, task manifests, baseline configuration, exact commands, and result
+aggregation. All profiles use the same agent, model, prompt, tool budget, and
+three-run protocol.
+
+## 📚 Documentation
+
+| 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

@@ -23,7 +23,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,15 +31,15 @@
 </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>
 
 只需安装一次集成并为工作区建索引，之后既可以在终端中搜索，也可以直接向
@@ -49,76 +49,149 @@ Agent 提问。
 
 ## 💫 为什么选择 zg？
 
-- **开箱即用，零学习成本**：一套引导式安装即可在 macOS、Linux 和 Windows
-  上接入 Agent；直接用自然语言提问，无需学习搜索语法。
-- **一站式检索层**：语义发现、BM25 相关性检索、精确文本与正则搜索
-  都由 zg 统一提供。
-- **对 Agent 和开发者都友好**：为 Agent 提供紧凑、围绕文件组织的上下文，
-  为开发者提供易读的终端输出，双方都能减少无关噪声。
-- **本地优先、权限明确**：ripgrep、索引与本地模型均留在本机；远程 Embedding
-  需要显式授权。
+- **人与 Agent 开箱即用**：安装一次、索引一次，即可在 macOS、Linux 和
+  Windows 上通过 CLI 或 Agent 复用同一个工作区。
+- **不止关键词搜索**：先按语义发现内容、按相关性排序，再在需要时使用精确文本
+  或正则完成验证。
+- **多格式检索**：搜索源代码、文档和结构化数据，同时保留有用的内容结构与
+  来源位置。
+- **更少搜索，更少上下文**：经过排序并保留来源的结果，可以减少工具调用、
+  Token 消耗与无关噪声，更快找到所需证据。
+- **默认本地运行**：文件、索引与本地模型都留在本机；只有经过你的授权，远程
+  Embedding 服务才能接收数据。
 
-<a id="quickstart"></a>
+<a id="try-it-yourself"></a>
 
-## 🚀 快速开始
+## 🚀 动手体验
 
-需要 Node.js 22 或更新版本，支持 macOS、Linux 和 Windows。
+需要 Node.js 22 或更新版本，以及已经完成配置的
+[OpenCode](https://opencode.ai/)。Agent 示例会显式选择免费模型，不依赖你配置的
+默认模型提供方。
 
-### 1. 安装并连接 Agent
+### 1. 准备示例书架
 
 ```bash
 npm install -g @zvec/zvec-grep
-zg install
-```
+zg install --target opencode --yes
 
-`zg install` 会检测 Codex、Claude Code、Cursor 和 OpenCode，并配置本地 MCP 集成。
-查看 [Agent 集成指南](./docs/01-agents.md)，了解配置变更、权限和卸载方式。
-也可以明确指定目标：
+mkdir zg-mystery && cd zg-mystery
+curl -L https://www.gutenberg.org/files/11/11-0.txt -o alice-in-wonderland.txt
+curl -L https://www.gutenberg.org/files/345/345-0.txt -o dracula.txt
+curl -L https://www.gutenberg.org/files/84/84-0.txt -o frankenstein.txt
+curl -L https://www.gutenberg.org/files/834/834-0.txt -o sherlock-holmes.txt
 
-```bash
-zg install --target codex --yes
+zg index --embedding local/potion-retrieval-32m
 ```
 
-### 2. 为仓库建索引
+这会创建一个包含四本公版小说的小书架，并使用 Potion Retrieval 在本地建立索引。
+
+安装时会立即启动共享 Daemon。默认 MCP 传输方式为 stdio：Agent 会运行
+`zg server --stdio`，电脑重启后该命令会再次安全启动或复用 Daemon。高级用户
+可以通过 `zg install --mcp-transport http` 保留 HTTP 直连，并自行使用
+`zg server on` 管理后续启动。
+
+如需让安装后的 MCP 集成额外暴露 managed rg、index 和 status 工具，可使用
+`zg install --mcp-toolset full`；默认值为 `agent`。
+
+### 2. 选择检索方式
+
+#### Agent：通过 OpenCode 提问
 
 ```bash
-cd your-repository
-zg index --embedding local/potion-code-16m-v2
+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)，进一步控制检索范围、
-增量更新和重建。
-
-### 3. 直接向 Agent 提问
+Prompt 中没有指定任何工具，OpenCode 会自主选择 zg。不同模型改写的
+Query 可能略有不同，一次典型的执行过程如下：
 
 ```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:
+侦探是《驼背人》中的福尔摩斯。根据动物留下的脚印，他推断：
+
+- 它不是狗、猫、猴子或其他常见动物：脚印有五个肉垫和长爪，整个脚印
+  接近一把甜点勺大小（sherlock-holmes.txt:5479-5486）。
+- 它身体细长、四肢很短：身长接近两英尺，步幅却只有约三英寸
+  （sherlock-holmes.txt:5497-5502）。
+- 它是食肉动物，因为它爬上窗帘，试图接近金丝雀笼
+  （sherlock-holmes.txt:5509-5510）。
+- 它很可能属于鼬或白鼬一类，但体型异常大
+  （sherlock-holmes.txt:5514-5516）。
+
+福尔摩斯还推断，一名男子和它一起从窗户进入房间，离开时带走了钥匙
+（sherlock-holmes.txt:5464-5470, 5527-5528）。
 ```
 
-Agent 会始终通过 zg 完成语义发现、关键词相关性检索与穷尽精确匹配。你无需
-选择或调用其他搜索工具。[MCP 指南](./docs/03-mcp.md)介绍了 Agent 使用的两个工具。
+#### 用户：直接检索
 
-也可以直接在终端中使用同一个本地检索层。查看 [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` 中的证据排在前面。
+
 <a id="benchmarks"></a>
 
 ## 📊 性能测试
 
-> 🚧 **正在完善中。**
+zg 是通用检索工具，目前的性能测试覆盖代码与文本检索。
+
+### 代码仓库检索
+
+我们使用 [SWE-QA-Bench](https://github.com/peng-weihan/SWE-QA-Bench)，它要求
+Agent 在真实代码库中完成跨文件、多跳推理。
+
+- **覆盖范围：**20 个检索密集型任务，覆盖论文中的 **What、Where、How、Why**
+  四个一级类别、8 种意图和 11 个代码仓库。
+- **Agent：**使用 **Claude Opus 5** 的 Claude Code。
+- **Embedding：**zg 方案使用 **Qwen3.7 Text Embedding**。
+- **测试方式：**每个任务、每种方案运行 3 次。
+
+| 方案 | 评审得分 /100 ↑ | 输入 Token ↓ | 工具调用 ↓ | 耗时（秒）↓ | 成本 ↓ |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| 原生工具 | 80.42 | 558,651 | 23.42 | 127.5 | $0.905 |
+| 原生工具 + zg | 81.92 | 294,262 | 9.70 | 79.7 | $0.558 |
+| 变化 | **+1.50 个百分点** | **−47.3%** | **−58.6%** | **−37.5%** | **−38.3%** |
+
+在 20 个任务 × 3 次运行中，zg 将评审得分提升了 1.50 分，同时将输入 Token
+减少 47.3%、工具调用减少 58.6%、执行时间减少 37.5%、成本减少 38.3%。
+
+### 大规模文本检索
+
+我们使用 [BrowseComp-Plus](https://github.com/texttron/BrowseComp-Plus)，它要求
+Agent 从固定网页语料库中检索多文档证据。测试包含 30 个问题，覆盖 10 个映射主题
+和三个证据广度级别，每种方案运行 3 次。
+
+| 方案 | 准确率 ↑ | 证据召回率 ↑ | 搜索调用 ↓ | 输入 Token ↓ | 耗时（秒）↓ | 成本 ↓ |
+| --- | ---: | ---: | ---: | ---: | ---: | ---: |
+| Agent + BM25 | TBD | TBD | TBD | TBD | TBD | TBD |
+| Agent + zg | TBD | TBD | TBD | TBD | TBD | TBD |
+| 变化 | TBD | TBD | TBD | TBD | TBD | TBD |
+
+在 30 个问题 × 3 次运行中，zg 对准确率、证据召回率、搜索调用、输入 Token、
+执行时间和成本的影响尚待测试结果补充。
 
-## 🗺️ Roadmap
+如需复现测试，请按照[性能测试指南](./benchmarks/README.md)准备环境、固定版本、
+任务清单、基线配置、运行命令和结果汇总。所有方案使用相同的 Agent、模型、Prompt、
+工具预算和三次运行协议。
 
-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) {