@zvec/zvec-grep 0.1.5 → 0.1.6

package/README.md

@@ -3,305 +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="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="License"/></a>
-  <img src="https://img.shields.io/badge/node-%3E%3D22-blue.svg" alt="Node.js >=22"/>
-  <img src="https://img.shields.io/badge/CLI-zg-2ea44f.svg" alt="zg CLI"/>
-</p>
+**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.
 
-<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>
+<a id="tour"></a>
 
-**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.
+## 🎬 See it in action
 
-The command is intentionally short:
+<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>
 
-```bash
-zg query "where query auto update happens"
-```
+Install the integration once, index the workspace, then search from the terminal
+or ask your agent naturally.
 
-> [!IMPORTANT]
-> **Command interface**
->
-> - **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 query --rg` provides managed ripgrep search without requiring an index.
+<a id="features"></a>
 
-## <a id="features"></a>💫 Features
+## 💫 Why zg?
 
-- **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 query --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.
-- **MCP Server**: Run `zg serve --mcp` to expose indexed and no-index lexical search tools to MCP clients. Indexing and status remain CLI-only operations.
-- **Library API**: Use `createZvecGrep()` directly from Node.js tools, agents, or MCP servers.
+- **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="installation"></a>📦 Installation
+<a id="quickstart"></a>
 
-Install the CLI from npm:
+## 🚀 Quickstart
 
-```bash
-npm install -g @zvec/zvec-grep
-zg version
-```
+Requires Node.js 22 or newer on macOS, Linux, or Windows.
 
-Or run it without a global install:
+### 1. Install and connect your agent
 
 ```bash
-npx @zvec/zvec-grep help
-```
-
-Install the latest source checkout as a global `zg` command:
-
-```bash
-git clone https://github.com/zvec-ai/zvec-grep.git
-cd zvec-grep
-npm ci
-npm run build
-npm install -g .
-zg version
-```
-
-Run the stdio MCP server:
-
-```bash
-zg serve --mcp
+npm install -g @zvec/zvec-grep
+zg install
 ```
 
-Install the Codex MCP integration:
+`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 install --target codex --yes
 ```
 
-Codex MCP tool calls default to a 600-second timeout. Override it during installation with `--mcp-tool-timeout <seconds>`.
-
-### ✅ Requirements
-
-- Node.js 22 or newer
-- macOS, Linux, or Windows
-- A supported embedding model for indexed search
-
-`zg query --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 \
-  -g "src/**" \
-  -g "docs/**" \
-  -g "test/**" \
-  -g "!dist/**" \
-  -g "!node_modules/**" \
-  -g "!coverage/**"
-```
-
-Check index state:
+### 2. Index your repository
 
 ```bash
-zg status
+cd your-repository
+zg index --embedding local/potion-code-16m-v2
 ```
 
-Search with natural language:
+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.
 
-```bash
-zg query "where query auto update happens"
-```
+### 3. Ask your agent
 
-Combine semantic intent with exact anchors:
-
-```bash
-zg query "GPU fallback" --fts "usingCpuFallback" -g "src/**" -t ts --limit 5
+```text
+My app forgets dark mode every time I refresh. Find out why.
 ```
 
-Use exhaustive lexical search without an index:
+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.
 
-```bash
-zg query --rg -F "ZVEC_GREP_HOME" src
-```
-
-Switch to human-readable output:
+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 query --human "root local index discovery" --limit 3
+zg query --human "theme preference persistence on startup" --limit 3
 ```
 
-Use from an MCP client with `zvec_grep_search` and `zvec_grep_rg`. MCP inputs use JSON-friendly fields such as `include: ["src/**"]`; use the CLI for `zg status` and `zg index`. The Codex installer writes managed zvec-grep blocks to `${CODEX_HOME:-$HOME/.codex}/config.toml` and `${CODEX_HOME:-$HOME/.codex}/AGENTS.md`.
-
-## <a id="models"></a>🧠 Models
-
-Local models run through `node-llama-cpp` and keep code search private to your machine:
+<a id="benchmarks"></a>
 
-```bash
-zg index --embedding local/embeddinggemma-300m
-zg index --embedding local/qwen3-embedding-0.6b
-```
+## 📊 Benchmarks
 
-On Apple Silicon, local builds use quiet llama.cpp CMake defaults to avoid harmless OpenMP and ARM native-detection warnings. Override any llama.cpp CMake option with `NODE_LLAMA_CPP_CMAKE_OPTION_<name>`, for example `NODE_LLAMA_CPP_CMAKE_OPTION_GGML_NATIVE=ON` to opt back into native CPU tuning.
+> 🚧 **Work in progress.**
 
-Remote Qwen embeddings are useful when you prefer a managed embedding service or want to avoid local model setup:
+## 🗺️ Roadmap
 
-```bash
-zg index \
-  --embedding qwen/text-embedding-v4 \
-  --api-key "$DASHSCOPE_API_KEY"
-```
+zg is moving toward richer multimodal formats, stronger hybrid retrieval, a
+more out-of-the-box experience, and support from desktop to mobile.
 
-After a successful index, explicitly passed global model and provider options are saved to `~/.zvec-grep/config.json` with user-only permissions. This lets an already-running `zg` MCP server load a newly configured remote API key on its next model request without restarting Codex. Values read only from environment variables are not persisted.
-
-```json
-{
-  "version": 1,
-  "defaults": {
-    "embedding": "qwen/text-embedding-v4"
-  },
-  "providers": {
-    "qwen": {
-      "apiKey": "...",
-      "endpoint": "https://dashscope.aliyuncs.com/compatible-mode/v1/embeddings"
-    }
-  }
-}
-```
+Explore the full [Roadmap](./docs/08-roadmap.md).
 
-Resolution order is explicit CLI or library options, then environment variables, then global config, then built-in defaults. Repository roots and file-selection settings remain in each repository's `.zvec-grep` metadata rather than global config.
+<a id="community"></a>
 
-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:
-
-```bash
-zg index --rebuild --embedding local/qwen3-embedding-0.6b
-```
-
-## 🔎 Query Patterns
-
-Multiple quoted queries are treated as separate search groups:
-
-```bash
-zg query "request validation" "error handling" --limit 5
-```
-
-Route options each consume one query and can be repeated. Add `--fuse` when
-you want all groups combined into one ranked result list:
-
-```bash
-zg query \
-  --hybrid "authentication flow" \
-  --fts "AuthService" \
-  --vector "where credentials are validated" \
-  --fuse \
-  --limit 10
-```
-
-Use ripgrep-style path and file-type filters early to keep results focused.
-Positive globs include paths and globs beginning with `!` exclude them:
-
-```bash
-zg query "cache invalidation" \
-  -g "src/**" \
-  -g "!test/**" \
-  -g "!tests/**" \
-  -g "!fixtures/**" \
-  -g "!dist/**" \
-  -t ts
-```
-
-File-type filters are applied in addition to glob filters. For example,
-`-g "docs/**" -t ts` selects TypeScript files under `docs`, not every file in
-that directory.
-
-Use `--preview` to control indexed source previews:
-
-```bash
-zg query "plugin lifecycle" --preview none
-zg query "plugin lifecycle" --preview short --limit 5
-zg query "plugin lifecycle" --preview full --limit 2
-```
-
-For exact text, symbols, flags, or error codes, use `--fts` or `--rg`:
-
-```bash
-zg query "authentication flow" --fts "AuthService" --fts "ForbiddenError"
-zg query --rg -i -C 2 -g "*.ts" "needle text" src
-```
-
-Managed rg mode accepts common ripgrep matching, context, type, glob, ignore,
-depth, size, symlink, encoding, and regex-engine options. Zvec-grep owns the
-result format, so output-changing modes such as `--json`, `--count`, `--files`,
-`-l`, `-o`, `--replace`, and `--vimgrep` are rejected. `.git/**` and
-`.zvec-grep/**` remain excluded.
-
-## <a id="library-api"></a>🛠️ Library API
-
-```ts
-import { createZvecGrep } from "@zvec/zvec-grep";
-
-const zvecGrep = await createZvecGrep({
-  root: process.cwd(),
-});
-
-const result = await zvecGrep.context({
-  query: "ranking implementation",
-  limit: 5,
-});
-
-for (const item of result.items) {
-  const location =
-    item.range.kind === "text"
-      ? `${item.file.relativePath}:${item.range.startLine}`
-      : item.file.relativePath;
-  console.log(location);
-}
-
-await zvecGrep.close();
-```
-
-For explicit no-index lexical search:
-
-```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) |
-|                                                 Scan to join                                                  |                                                 Scan to join                                                  |                                                                      Click to join                                                                      |                                           Click to follow                                            |
+| 💬 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?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:
-
-```bash
-npm run check
-```
+Community contributions are always welcome—bug fixes, features, and
+documentation improvements all help make zvec-grep better.
 
-Pull request titles use Conventional Commits syntax.
+Check out our [Contributing Guide](./CONTRIBUTING.md) to get started!