@zvec/zvec-grep 0.1.4 → 0.1.6

package/README.md

@@ -3,220 +3,144 @@
 </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="https://zvec.oss-cn-hongkong.aliyuncs.com/logo/github_log_2.svg" />
-    <img src="https://zvec.oss-cn-hongkong.aliyuncs.com/logo/github_logo_1.svg" width="400" alt="zvec logo" />
+    <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" />
   </picture>
+  <p><strong>Know the words—or don’t. Just zg.</strong></p>
+  <p>The local-first search layer for humans and agents.</p>
+
+  <p>
+    <a href="https://www.npmjs.com/package/@zvec/zvec-grep"><img src="https://img.shields.io/npm/v/@zvec/zvec-grep.svg" alt="npm version" /></a>
+    <a href="https://github.com/zvec-ai/zvec-grep/actions/workflows/ci.yml"><img src="https://github.com/zvec-ai/zvec-grep/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
+    <a href="./LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg" alt="Apache 2.0 license" /></a>
+    <img src="https://img.shields.io/badge/node-%3E%3D22-blue.svg" alt="Node.js 22 or newer" />
+  </p>
+
+  <p>
+    <a href="#tour">🎬 <strong>Tour</strong></a> |
+    <a href="#features">💫 <strong>Features</strong></a> |
+    <a href="#quickstart">🚀 <strong>Quickstart</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>
+  </p>
 </div>
 
-<p align="center">
-  <a href="https://www.npmjs.com/package/@zvec/zvec-grep"><img src="https://img.shields.io/npm/v/@zvec/zvec-grep.svg" alt="npm Release"/></a>
-  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg" alt="License"/></a>
-  <img src="https://img.shields.io/badge/node-%3E%3D20-blue.svg" alt="Node.js >=20"/>
-  <img src="https://img.shields.io/badge/CLI-zg-2ea44f.svg" alt="zg CLI"/>
-</p>
-
-<p align="center">
-  <a href="#quickstart">🚀 <strong>Quickstart</strong></a> |
-  <a href="#features">💫 <strong>Features</strong></a> |
-  <a href="#installation">📦 <strong>Installation</strong></a> |
-  <a href="#models">🧠 <strong>Models</strong></a> |
-  <a href="#library-api">🛠️ <strong>Library API</strong></a>
-</p>
-
-**zvec-grep** is an agent-friendly hybrid code search tool built on Zvec. It gives repositories a root-local semantic index, combines vector search with full-text search, and keeps CLI output compact enough for AI agents while still offering rich terminal output for humans.
-
-The command is intentionally short:
-
-```bash
-zg "where query auto update happens"
-```
-
-> [!IMPORTANT]
-> **v0.1.3**
->
-> - **Hybrid Code Search**: Query code with natural language, exact terms, or both in one command.
-> - **Explicit Index Lifecycle**: New repositories require `zg --index --embedding <model>`; agents do not silently create indexes.
-> - **Automatic Refresh**: Existing anonymous indexes are checked and incrementally updated before normal queries.
-> - **Token-Efficient Output**: Agent output defaults to `--preview none`; `--human` defaults to full source previews.
-> - **No-Index Lexical Search**: `zg --rg` provides managed ripgrep search without requiring an index.
-
-## <a id="features"></a>💫 Features
-
-- **Semantic + Lexical Retrieval**: Blend vector search and full-text search for code, docs, tests, scripts, and configuration.
-- **Root-Local Indexes**: Anonymous indexes live under `<repo>/.zvec-grep/`, so repository state stays with the repository.
-- **Agent-Ready Output**: Default output is grouped by file and keeps previews small to save tokens.
-- **Human Output Mode**: Add `--human` for a terminal-friendly summary with full previews by default.
-- **Managed ripgrep Route**: `zg --rg` supports common `rg` flags and works even before a repository is indexed.
-- **Explicit Model Choice**: The first index build requires a model such as `local/embeddinggemma-300m`, `local/qwen3-embedding-0.6b`, or `qwen/text-embedding-v4`.
-- **Schema Reuse**: Re-running `zg --index` on an existing index reuses the stored embedding schema unless you explicitly change it.
-- **Library API**: Use `createZvecGrep()` directly from Node.js tools, agents, or MCP servers.
-
-## <a id="installation"></a>📦 Installation
-
-Install the CLI from npm:
-
-```bash
-npm install -g @zvec/zvec-grep
-zg --version
-```
-
-Or run it without a global install:
-
-```bash
-npx @zvec/zvec-grep --help
-```
-
-### ✅ Requirements
-
-- Node.js 20 or newer
-- macOS, Linux, or Windows
-- A supported embedding model for indexed search
-
-`zg --rg` works without any embedding model or index.
-
-## <a id="quickstart"></a>⚡ Quickstart
-
-Index a repository with an explicit embedding model:
-
-```bash
-zg --index \
-  --embedding local/embeddinggemma-300m \
-  --include "src/**" \
-  --include "docs/**" \
-  --include "test/**" \
-  --exclude "dist/**,node_modules/**,coverage/**"
-```
-
-Check index state:
+**zg** (**z**vec-**g**rep) unifies ripgrep, BM25, and vector search behind
+[one local-first interface](./docs/05-architecture.md). Use it directly from the
+terminal, or let your agent use it for you.
 
-```bash
-zg --status
-```
+<a id="tour"></a>
 
-Search with natural language:
+## 🎬 See it in action
 
-```bash
-zg "where query auto update happens"
-```
+<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" />
+</div>
 
-Combine semantic intent with exact anchors:
+Install the integration once, index the workspace, then search from the terminal
+or ask your agent naturally.
 
-```bash
-zg "GPU fallback" --fts "usingCpuFallback" --include "src/**" --limit 5
-```
+<a id="features"></a>
 
-Use exhaustive lexical search without an index:
+## 💫 Why zg?
 
-```bash
-zg --rg -F "ZVEC_GREP_HOME" src
-```
+- **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.
 
-Switch to human-readable output:
+<a id="quickstart"></a>
 
-```bash
-zg --human "root local index discovery" --limit 3
-```
+## 🚀 Quickstart
 
-## <a id="models"></a>🧠 Models
+Requires Node.js 22 or newer on macOS, Linux, or Windows.
 
-Local models run through `node-llama-cpp` and keep code search private to your machine:
+### 1. Install and connect your agent
 
 ```bash
-zg --index --embedding local/embeddinggemma-300m
-zg --index --embedding local/qwen3-embedding-0.6b
+npm install -g @zvec/zvec-grep
+zg install
 ```
 
-Remote Qwen embeddings are useful when you prefer a managed embedding service or want to avoid local model setup:
+`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:
 
 ```bash
-zg --index \
-  --embedding qwen/text-embedding-v4 \
-  --api-key "$DASHSCOPE_API_KEY"
+zg install --target codex --yes
 ```
 
-For existing indexes, `zg --index` without `--embedding` reuses the stored schema. Use `--rebuild --embedding <model>` only when you intentionally want to rebuild with a different model:
+### 2. Index your repository
 
 ```bash
-zg --index --rebuild --embedding local/qwen3-embedding-0.6b
+cd your-repository
+zg index --embedding local/potion-code-16m-v2
 ```
 
-## 🔎 Query Patterns
+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.
 
-Multiple quoted queries are treated as separate search groups:
+### 3. Ask your agent
 
-```bash
-zg "request validation" "error handling" --limit 5
+```text
+My app forgets dark mode every time I refresh. Find out why.
 ```
 
-Use path filters early to keep results focused:
-
-```bash
-zg "cache invalidation" \
-  --include "src/**" \
-  --exclude "test/**,tests/**,fixtures/**,dist/**"
-```
-
-Use `--preview` to control indexed source previews:
-
-```bash
-zg "plugin lifecycle" --preview none
-zg "plugin lifecycle" --preview short --limit 5
-zg "plugin lifecycle" --preview full --limit 2
-```
+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 exact text, symbols, flags, or error codes, use `--fts` or `--rg`:
+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.
 
 ```bash
-zg "authentication flow" --fts "AuthService" "ForbiddenError"
-zg --rg -i -C 2 -g "*.ts" "needle text" src
+zg query --human "theme preference persistence on startup" --limit 3
 ```
 
-## <a id="library-api"></a>🛠️ Library API
+<a id="benchmarks"></a>
 
-```ts
-import { createZvecGrep } from "@zvec/zvec-grep";
+## 📊 Benchmarks
 
-const zvecGrep = await createZvecGrep({
-  root: process.cwd(),
-});
+> 🚧 **Work in progress.**
 
-const result = await zvecGrep.context({
-  query: "ranking implementation",
-  limit: 5,
-});
+## 🗺️ Roadmap
 
-for (const item of result.items) {
-  console.log(`${item.file.relativePath}:${item.range.startLine}`);
-}
+zg is moving toward richer multimodal formats, stronger hybrid retrieval, a
+more out-of-the-box experience, and support from desktop to mobile.
 
-await zvecGrep.close();
-```
+Explore the full [Roadmap](./docs/08-roadmap.md).
 
-For explicit no-index lexical search:
+<a id="community"></a>
 
-```ts
-const result = await zvecGrep.context({
-  query: "ZVEC_GREP_HOME",
-  rg: true,
-});
-```
-
-## 🤝 Join the Zvec Community
+## 🤝 Join Our Community
 
 <div align="center">
 
 | 💬 DingTalk | 📱 WeChat | 🎮 Discord | X (Twitter) |
 | :---: | :---: | :---: | :---: |
-| <img src="https://zvec.oss-cn-hongkong.aliyuncs.com/qrcode/dingding.png" width="150" alt="DingTalk QR Code"/> | <img src="https://zvec.oss-cn-hongkong.aliyuncs.com/qrcode/wechat.png?v=6" width="150" alt="WeChat QR Code"/> | [![Discord](https://img.shields.io/badge/Discord-Join%20Server-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/rKddFBBu9z) | [![X (formerly Twitter) Follow](https://img.shields.io/twitter/follow/ZvecAI)](<https://x.com/ZvecAI>) |
+| <img src="https://zvec.oss-cn-hongkong.aliyuncs.com/qrcode/dingding.png" width="150" alt="DingTalk QR Code"/> | <img src="https://zvec.oss-cn-hongkong.aliyuncs.com/qrcode/wechat.png?v1" width="150" alt="WeChat QR Code"/> | [![Discord](https://img.shields.io/badge/Discord-Join%20Server-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/rKddFBBu9z) | [![X (formerly Twitter) Follow](https://img.shields.io/twitter/follow/ZvecAI)](<https://x.com/ZvecAI>) |
 | Scan to join | Scan to join | Click to join | Click to follow |
 
 </div>
 
 ## ❤️ Contributing
 
-Issues and pull requests are welcome. Please keep changes focused, add tests for behavior changes, and run:
+Community contributions are always welcome—bug fixes, features, and
+documentation improvements all help make zvec-grep better.
 
-```bash
-npm test
-```
+Check out our [Contributing Guide](./CONTRIBUTING.md) to get started!

package/README_CN.md

@@ -3,220 +3,138 @@
 </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="https://zvec.oss-cn-hongkong.aliyuncs.com/logo/github_log_2.svg" />
-    <img src="https://zvec.oss-cn-hongkong.aliyuncs.com/logo/github_logo_1.svg" width="400" alt="zvec logo" />
+    <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" />
   </picture>
+  <p><strong>Know the words—or don’t. Just zg.</strong></p>
+  <p>面向人与 Agent 的本地优先统一检索层。</p>
+
+  <p>
+    <a href="https://www.npmjs.com/package/@zvec/zvec-grep"><img src="https://img.shields.io/npm/v/@zvec/zvec-grep.svg" alt="npm 版本" /></a>
+    <a href="https://github.com/zvec-ai/zvec-grep/actions/workflows/ci.yml"><img src="https://github.com/zvec-ai/zvec-grep/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
+    <a href="./LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg" alt="Apache 2.0 许可证" /></a>
+    <img src="https://img.shields.io/badge/node-%3E%3D22-blue.svg" alt="Node.js 22 或更新版本" />
+  </p>
+
+  <p>
+    <a href="#tour">🎬 <strong>功能演示</strong></a> |
+    <a href="#features">💫 <strong>核心特性</strong></a> |
+    <a href="#quickstart">🚀 <strong>快速开始</strong></a> |
+    <a href="./docs/README.md">📚 <strong>文档</strong></a> |
+    <a href="#benchmarks">📊 <strong>性能测试</strong></a> |
+    <a href="#community">🤝 <strong>社区</strong></a>
+  </p>
 </div>
 
-<p align="center">
-  <a href="https://www.npmjs.com/package/@zvec/zvec-grep"><img src="https://img.shields.io/npm/v/@zvec/zvec-grep.svg" alt="npm 版本"/></a>
-  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg" alt="许可证"/></a>
-  <img src="https://img.shields.io/badge/node-%3E%3D20-blue.svg" alt="Node.js >=20"/>
-  <img src="https://img.shields.io/badge/CLI-zg-2ea44f.svg" alt="zg CLI"/>
-</p>
-
-<p align="center">
-  <a href="#quickstart">🚀 <strong>快速开始</strong></a> |
-  <a href="#features">💫 <strong>核心特性</strong></a> |
-  <a href="#installation">📦 <strong>安装</strong></a> |
-  <a href="#models">🧠 <strong>模型</strong></a> |
-  <a href="#library-api">🛠️ <strong>库 API</strong></a>
-</p>
-
-**zvec-grep** 是基于 Zvec 构建的、面向 agent 的代码库混合检索工具。它为仓库维护本地语义索引，融合向量检索与全文检索，并默认输出节省 token 的结果；当人在终端里阅读时，也可以切换到更完整的展示模式。
-
-命令非常短：
-
-```bash
-zg "where query auto update happens"
-```
-
-> [!IMPORTANT]
-> **v0.1.3**
->
-> - **混合代码检索**：可以用自然语言、精确关键词，或两者组合来搜索代码。
-> - **明确的索引生命周期**：新仓库必须显式运行 `zg --index --embedding <model>`；agent 不会静默创建索引。
-> - **自动刷新**：已有匿名索引会在普通查询前自动检查并增量更新。
-> - **节省 Token 的输出**：agent 默认输出 `--preview none`；`--human` 默认展示完整源码 preview。
-> - **无索引文本搜索**：`zg --rg` 提供托管的 ripgrep 搜索，不需要先建索引。
-
-## <a id="features"></a>💫 核心特性
-
-- **语义 + 词法检索**：融合向量检索和全文检索，适合源码、文档、测试、脚本和配置。
-- **仓库本地索引**：匿名索引存放在 `<repo>/.zvec-grep/`，索引状态跟随仓库。
-- **Agent 友好输出**：默认按文件分组，并尽量减少源码 preview，降低上下文成本。
-- **人类阅读模式**：加 `--human` 后更适合终端阅读，并默认展示完整 preview。
-- **托管 ripgrep 通道**：`zg --rg` 支持常见 `rg` 参数，未建索引仓库也能使用。
-- **显式模型选择**：第一次建索引必须指定模型，例如 `local/embeddinggemma-300m`、`local/qwen3-embedding-0.6b` 或 `qwen/text-embedding-v4`。
-- **Schema 复用**：已有索引再次运行 `zg --index` 会复用保存的 embedding schema，除非你显式切换模型。
-- **库 API**：Node.js 工具、agent 或 MCP server 可以直接使用 `createZvecGrep()`。
-
-## <a id="installation"></a>📦 安装
-
-从 npm 安装 CLI：
-
-```bash
-npm install -g @zvec/zvec-grep
-zg --version
-```
-
-也可以不全局安装，直接运行：
-
-```bash
-npx @zvec/zvec-grep --help
-```
-
-### ✅ 运行要求
-
-- Node.js 20 或更新版本
-- macOS、Linux 或 Windows
-- 使用索引检索时需要选择一个支持的 embedding 模型
-
-`zg --rg` 不需要 embedding 模型，也不需要索引。
-
-## <a id="quickstart"></a>⚡ 快速开始
-
-为仓库建索引，并显式指定 embedding 模型：
-
-```bash
-zg --index \
-  --embedding local/embeddinggemma-300m \
-  --include "src/**" \
-  --include "docs/**" \
-  --include "test/**" \
-  --exclude "dist/**,node_modules/**,coverage/**"
-```
-
-查看索引状态：
+**zg**（**z**vec-**g**rep）将 ripgrep、BM25 与向量检索统一在一个
+[本地优先的检索入口](./docs/05-architecture.md)中。无论是人在终端中搜索，
+还是让 Agent 自主检索，只用 zg 即可。
 
-```bash
-zg --status
-```
+<a id="tour"></a>
 
-用自然语言搜索：
+## 🎬 功能演示
 
-```bash
-zg "where query auto update happens"
-```
+<div align="center">
+  <img src="./.github/assets/zvec-grep-tour.gif" width="1000" alt="安装 Agent 集成、为仓库建索引并让 Agent 使用 zvec-grep 搜索代码" />
+</div>
 
-组合语义意图和精确锚点：
+只需安装一次集成并为工作区建索引，之后既可以在终端中搜索，也可以直接向
+Agent 提问。
 
-```bash
-zg "GPU fallback" --fts "usingCpuFallback" --include "src/**" --limit 5
-```
+<a id="features"></a>
 
-不依赖索引，做穷尽文本搜索：
+## 💫 为什么选择 zg？
 
-```bash
-zg --rg -F "ZVEC_GREP_HOME" src
-```
+- **开箱即用，零学习成本**：一套引导式安装即可在 macOS、Linux 和 Windows
+  上接入 Agent；直接用自然语言提问，无需学习搜索语法。
+- **一站式检索层**：语义发现、BM25 相关性检索、精确文本与正则搜索
+  都由 zg 统一提供。
+- **对 Agent 和开发者都友好**：为 Agent 提供紧凑、围绕文件组织的上下文，
+  为开发者提供易读的终端输出，双方都能减少无关噪声。
+- **本地优先、权限明确**：ripgrep、索引与本地模型均留在本机；远程 Embedding
+  需要显式授权。
 
-切换到适合人看的输出：
+<a id="quickstart"></a>
 
-```bash
-zg --human "root local index discovery" --limit 3
-```
+## 🚀 快速开始
 
-## <a id="models"></a>🧠 模型
+需要 Node.js 22 或更新版本，支持 macOS、Linux 和 Windows。
 
-本地模型通过 `node-llama-cpp` 运行，适合把代码检索留在本机：
+### 1. 安装并连接 Agent
 
 ```bash
-zg --index --embedding local/embeddinggemma-300m
-zg --index --embedding local/qwen3-embedding-0.6b
+npm install -g @zvec/zvec-grep
+zg install
 ```
 
-远程 Qwen embedding 适合希望使用托管 embedding 服务，或不想在本机配置模型的场景：
+`zg install` 会检测 Codex、Claude Code、Cursor 和 OpenCode，并配置本地 MCP 集成。
+查看 [Agent 集成指南](./docs/01-agents.md)，了解配置变更、权限和卸载方式。
+也可以明确指定目标：
 
 ```bash
-zg --index \
-  --embedding qwen/text-embedding-v4 \
-  --api-key "$DASHSCOPE_API_KEY"
+zg install --target codex --yes
 ```
 
-对于已有索引，`zg --index` 不传 `--embedding` 会复用索引里保存的 schema。只有在你明确想切换模型时，才使用 `--rebuild --embedding <model>`：
+### 2. 为仓库建索引
 
 ```bash
-zg --index --rebuild --embedding local/qwen3-embedding-0.6b
+cd your-repository
+zg index --embedding local/potion-code-16m-v2
 ```
 
-## 🔎 查询模式
+快速开始使用轻量的 [Potion Code v2](./docs/07-embedding.md)，以便快速完成首次建索引。
+第一次运行会下载模型，索引保存在 `.zvec-grep/` 下；后续更新只需运行
+`zg index`。查看 [检索 Pipeline](./docs/04-pipeline.md#indexing)，进一步控制检索范围、
+增量更新和重建。
 
-多个带引号的 query 会作为多个搜索组分别检索：
+### 3. 直接向 Agent 提问
 
-```bash
-zg "request validation" "error handling" --limit 5
+```text
+每次刷新页面，应用都会忘记深色模式。帮我找出原因。
 ```
 
-尽早使用路径过滤，让结果保持聚焦：
-
-```bash
-zg "cache invalidation" \
-  --include "src/**" \
-  --exclude "test/**,tests/**,fixtures/**,dist/**"
-```
-
-使用 `--preview` 控制索引结果的源码展示量：
-
-```bash
-zg "plugin lifecycle" --preview none
-zg "plugin lifecycle" --preview short --limit 5
-zg "plugin lifecycle" --preview full --limit 2
-```
+Agent 会始终通过 zg 完成语义发现、关键词相关性检索与穷尽精确匹配。你无需
+选择或调用其他搜索工具。[MCP 指南](./docs/03-mcp.md)介绍了 Agent 使用的两个工具。
 
-查精确文本、符号、配置项或错误码时，使用 `--fts` 或 `--rg`：
+也可以直接在终端中使用同一个本地检索层。查看 [CLI 指南](./docs/02-cli.md)，了解
+搜索方式、过滤条件和输出控制。
 
 ```bash
-zg "authentication flow" --fts "AuthService" "ForbiddenError"
-zg --rg -i -C 2 -g "*.ts" "needle text" src
+zg query --human "theme preference persistence on startup" --limit 3
 ```
 
-## <a id="library-api"></a>🛠️ 库 API
+<a id="benchmarks"></a>
 
-```ts
-import { createZvecGrep } from "@zvec/zvec-grep";
+## 📊 性能测试
 
-const zvecGrep = await createZvecGrep({
-  root: process.cwd(),
-});
+> 🚧 **正在完善中。**
 
-const result = await zvecGrep.context({
-  query: "ranking implementation",
-  limit: 5,
-});
+## 🗺️ Roadmap
 
-for (const item of result.items) {
-  console.log(`${item.file.relativePath}:${item.range.startLine}`);
-}
+zg 正在迈向更丰富的多模态格式、更强的混合检索、更开箱即用的体验，以及从
+桌面端到移动端的全平台支持。
 
-await zvecGrep.close();
-```
+查看完整 [Roadmap](./docs/08-roadmap.md)。
 
-显式进行无索引文本搜索：
+<a id="community"></a>
 
-```ts
-const result = await zvecGrep.context({
-  query: "ZVEC_GREP_HOME",
-  rg: true,
-});
-```
-
-## 🤝 加入 Zvec 社区
+## 🤝 加入社区
 
 <div align="center">
 
 | 💬 钉钉群 | 📱 微信群 | 🎮 Discord | X (Twitter) |
 | :---: | :---: | :---: | :---: |
-| <img src="https://zvec.oss-cn-hongkong.aliyuncs.com/qrcode/dingding.png" width="150" alt="钉钉二维码"/> | <img src="https://zvec.oss-cn-hongkong.aliyuncs.com/qrcode/wechat.png?v=6" width="150" alt="微信二维码"/> | [![Discord](https://img.shields.io/badge/Discord-Join%20Server-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/rKddFBBu9z) | [![X (formerly Twitter) Follow](https://img.shields.io/twitter/follow/ZvecAI)](<https://x.com/ZvecAI>) |
+| <img src="https://zvec.oss-cn-hongkong.aliyuncs.com/qrcode/dingding.png" width="150" alt="钉钉二维码"/> | <img src="https://zvec.oss-cn-hongkong.aliyuncs.com/qrcode/wechat.png?v1" width="150" alt="微信二维码"/> | [![Discord](https://img.shields.io/badge/Discord-Join%20Server-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/rKddFBBu9z) | [![X (formerly Twitter) Follow](https://img.shields.io/twitter/follow/ZvecAI)](<https://x.com/ZvecAI>) |
 | 扫码加入 | 扫码加入 | 点击加入 | 点击关注 |
 
 </div>
 
 ## ❤️ 参与贡献
 
-欢迎提交 issue 和 pull request。请保持改动聚焦；如果改变行为，请补充测试，并运行：
+始终欢迎社区贡献——缺陷修复、新功能和文档改进都会让 zvec-grep 变得更好。
 
-```bash
-npm test
-```
+请查阅我们的[贡献指南](./CONTRIBUTING.md)开始参与！

package/dist/authorization/index.d.ts

@@ -0,0 +1,7 @@
+export { RemoteEmbeddingAuthorizationManager } from "./manager.js";
+export { createRemoteEmbeddingOperationPermit, remoteEmbeddingAuthorizationGuard, withRemoteEmbeddingOperationPermit, } from "./operation.js";
+export { RemoteEmbeddingAuthorizationStore } from "./store.js";
+export { formatRemoteEmbeddingAuthorizationPrompt, remoteEmbeddingDisclosureData, type RemoteEmbeddingAuthorizationPromptInput, } from "./prompt.js";
+export { indexStatusIsFresh, planRemoteIndexAuthorization, planRemoteSearchAuthorization, searchUsesVector, } from "./planner.js";
+export { canonicalizeWorkspaceRoots, createRemoteEmbeddingTarget, remoteEmbeddingTargetFingerprint, workspaceFingerprint, } from "./target.js";
+export type { RemoteEmbeddingAuthorizationPlan, RemoteEmbeddingAuthorizationScope, RemoteEmbeddingAuthorizationStatus, RemoteEmbeddingDataDisclosure, RemoteEmbeddingOperation, RemoteEmbeddingOperationPermit, RemoteEmbeddingTarget, RemoteEmbeddingWorkspaceGrant, } from "./types.js";

package/dist/authorization/index.js

@@ -0,0 +1,7 @@
+export { RemoteEmbeddingAuthorizationManager } from "./manager.js";
+export { createRemoteEmbeddingOperationPermit, remoteEmbeddingAuthorizationGuard, withRemoteEmbeddingOperationPermit, } from "./operation.js";
+export { RemoteEmbeddingAuthorizationStore } from "./store.js";
+export { formatRemoteEmbeddingAuthorizationPrompt, remoteEmbeddingDisclosureData, } from "./prompt.js";
+export { indexStatusIsFresh, planRemoteIndexAuthorization, planRemoteSearchAuthorization, searchUsesVector, } from "./planner.js";
+export { canonicalizeWorkspaceRoots, createRemoteEmbeddingTarget, remoteEmbeddingTargetFingerprint, workspaceFingerprint, } from "./target.js";
+//# sourceMappingURL=index.js.map

package/dist/authorization/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/authorization/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mCAAmC,EAAE,MAAM,cAAc,CAAC;AACnE,OAAO,EACL,oCAAoC,EACpC,iCAAiC,EACjC,kCAAkC,GACnC,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,iCAAiC,EAAE,MAAM,YAAY,CAAC;AAC/D,OAAO,EACL,wCAAwC,EACxC,6BAA6B,GAE9B,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,kBAAkB,EAClB,4BAA4B,EAC5B,6BAA6B,EAC7B,gBAAgB,GACjB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,0BAA0B,EAC1B,2BAA2B,EAC3B,gCAAgC,EAChC,oBAAoB,GACrB,MAAM,aAAa,CAAC"}

package/dist/authorization/manager.d.ts

@@ -0,0 +1,8 @@
+import { RemoteEmbeddingAuthorizationStore } from "./store.js";
+import type { RemoteEmbeddingAuthorizationPlan, RemoteEmbeddingAuthorizationScope, RemoteEmbeddingOperationPermit } from "./types.js";
+export declare class RemoteEmbeddingAuthorizationManager {
+    readonly store: RemoteEmbeddingAuthorizationStore;
+    constructor(store?: RemoteEmbeddingAuthorizationStore);
+    existingWorkspacePermit(plan: RemoteEmbeddingAuthorizationPlan): Promise<RemoteEmbeddingOperationPermit | undefined>;
+    grant(plan: RemoteEmbeddingAuthorizationPlan, scope: RemoteEmbeddingAuthorizationScope): Promise<RemoteEmbeddingOperationPermit>;
+}