@zvec/zvec-grep 0.1.4 → 0.1.6

package/docs/08-roadmap.md

@@ -0,0 +1,85 @@
+# Roadmap
+
+[Documentation](./README.md) · [Agents](./01-agents.md) ·
+[CLI](./02-cli.md) · [MCP](./03-mcp.md) · [Pipeline](./04-pipeline.md) ·
+[Architecture](./05-architecture.md) · [Server](./06-server.md) ·
+[Embedding](./07-embedding.md) · [Roadmap](./08-roadmap.md)
+
+zvec-grep is under active development. The destination is one dependable,
+local-first search layer that people and agents can use without choosing among
+separate retrieval tools. This roadmap describes direction, not promised dates;
+priorities may change as we learn from real workloads.
+
+## Now — make the public preview dependable
+
+- Make installation, updates, and removal reliable across current platforms and
+  agent integrations.
+- Harden incremental indexing, freshness, Server recovery, and concurrent
+  workspace access.
+- Establish reproducible search-quality, performance, and agent-context
+  evaluation.
+- Stabilize the CLI, MCP contracts, configuration, diagnostics, and index
+  compatibility policy before a stable release.
+
+## Product direction
+
+The following four directions are part of the product vision, not optional
+experiments. Their sequencing may change, but each is required for zg to become
+the search layer we want it to be.
+
+### 1. Search more data formats, natively
+
+- Make PDF, PowerPoint (`.ppt` and `.pptx`), HTML, images, and other multimodal
+  documents first-class searchable inputs.
+- Add format-aware extraction that preserves useful structure, layout, metadata,
+  and relationships instead of flattening every file into plain text.
+- Combine text extraction, OCR, vision-language understanding, and multimodal
+  Embedding where each format benefits from them.
+- Use format- and content-aware retrieval so zg can choose a smarter strategy
+  for each query and source.
+
+### 2. Strengthen retrieval
+
+- Add knowledge-graph construction and graph retrieval to complement BM25,
+  vector search, and managed ripgrep.
+- Expand multi-route hybrid retrieval across lexical, vector, graph, structural,
+  and metadata signals.
+- Improve query planning so people and agents can express intent without
+  manually choosing retrieval routes.
+- Improve fusion, reranking, evaluation, and explainability while keeping the
+  returned context compact.
+
+### 3. Make zg more out of the box
+
+- Provide a local GUI for search, workspace management, indexing, model setup,
+  permissions, and diagnostics.
+- Support more installation paths beyond npm, including platform-native package
+  managers and installers where appropriate.
+- Make first-run setup, Agent discovery, model selection, updates, and recovery
+  increasingly automatic with useful defaults.
+- Preserve CLI and configuration control for advanced users while removing it
+  from the critical path for everyone else.
+
+### 4. Reach every platform, from PC to mobile
+
+- Deliver a consistent experience across macOS, Windows, and Linux desktops.
+- Extend the local search layer to iOS and Android instead of treating mobile as
+  a remote client to a required cloud service.
+- Adapt indexing, storage, and model execution to the memory, power, and lifecycle
+  constraints of mobile devices.
+- Keep the same local-first trust and permission model across desktop and mobile.
+
+## Guardrails
+
+- Local-first remains the default; remote content transfer always requires
+  explicit authorization.
+- zg should hide retrieval-tool choice from users without hiding useful control.
+- Better recall must not come at the cost of noisy, oversized agent context.
+- A hosted service must never be required for the core local workflow.
+
+## Help shape the roadmap
+
+Priorities should come from real use. Open a
+[GitHub issue](https://github.com/zvec-ai/zvec-grep/issues) to describe a
+workflow, limitation, or result that matters to you. Contributions are welcome;
+see the [Contributing Guide](../CONTRIBUTING.md).

package/docs/README.md

@@ -0,0 +1,53 @@
+# zvec-grep documentation
+
+**zg** is one local-first search layer for people and agents. These guides go
+beyond the short path in the project [README](../README.md) and explain how to
+connect an agent, shape an index, search it, and control the underlying
+interfaces.
+
+> [!IMPORTANT]
+> zvec-grep is a work in progress. Commands and configuration may change before
+> the first stable release.
+
+## Start here
+
+| I want to… | Read |
+| --- | --- |
+| Connect Codex, Claude Code, Cursor, or OpenCode | [Agent integrations](./01-agents.md) |
+| Use zg directly from a terminal | [CLI guide](./02-cli.md) |
+| Understand the tools exposed to an agent | [MCP guide](./03-mcp.md) |
+| Understand indexing, updates, and search routes | [Retrieval pipeline](./04-pipeline.md) |
+| See how the components and trust boundaries fit together | [Architecture](./05-architecture.md) |
+| Choose between Auto, Server, and Direct execution | [Server and execution modes](./06-server.md) |
+| Choose and configure an Embedding model | [Embedding models](./07-embedding.md) |
+| See what is stable now and what comes next | [Roadmap](./08-roadmap.md) |
+
+## Recommended paths
+
+If you primarily use an agent, start with [Agent integrations](./01-agents.md),
+then read the [MCP guide](./03-mcp.md) and
+[Retrieval pipeline](./04-pipeline.md). The [Server guide](./06-server.md)
+explains the daemon that connects them.
+
+If you primarily use the terminal, start with the [CLI guide](./02-cli.md), then
+read the [Retrieval pipeline](./04-pipeline.md). Use the
+[Embedding guide](./07-embedding.md) when creating a new index. The default
+`auto` execution mode is explained in
+[Server and execution modes](./06-server.md).
+
+For the whole-system mental model and trust boundaries, read
+[Architecture](./05-architecture.md).
+
+The [Roadmap](./08-roadmap.md) tracks the path from work in progress to a stable
+release.
+
+The CLI remains the source of truth for flags in the installed version:
+
+```bash
+zg help
+zg help query
+zg help index
+```
+
+For development setup and pull request conventions, see
+[CONTRIBUTING.md](../CONTRIBUTING.md).

package/package.json

@@ -1,14 +1,22 @@
 {
   "name": "@zvec/zvec-grep",
-  "version": "0.1.4",
-  "description": "Agent-friendly hybrid grep with indexed context and lexical fallback.",
+  "version": "0.1.6",
+  "description": "Agent-friendly hybrid code search with indexed context and managed ripgrep.",
   "type": "module",
   "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zvec-ai/zvec-grep.git"
+  },
+  "bugs": {
+    "url": "https://github.com/zvec-ai/zvec-grep/issues"
+  },
+  "homepage": "https://github.com/zvec-ai/zvec-grep#readme",
   "publishConfig": {
     "access": "public"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "exports": {
     ".": {
@@ -23,23 +31,51 @@
     "README.md",
     "README_CN.md",
     "LICENSE",
+    "docs",
     "dist",
     "skills/zvec-grep"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
+    "check": "npm run lint && npm run format:check && npm run typecheck && npm run test:coverage && npm run test:package",
+    "format:check": "prettier --check .",
+    "lint": "eslint .",
+    "prepack": "npm run build",
+    "test:coverage": "npm run build && c8 --all --include=dist/**/*.js --check-coverage --lines=80 --statements=80 --functions=80 --branches=80 npm run test:all",
+    "test:all": "npm run test:run:root && npm run test:run:unit && npm run test:run:integration && npm run test:run:e2e",
+    "test:e2e": "npm run build && npm run test:run:e2e",
+    "test:integration": "npm run build && npm run test:run:root && npm run test:run:integration",
+    "test:package": "npm run build && node --test --test-concurrency=1 test/package/*.test.mjs",
+    "test:run:e2e": "node --test --test-concurrency=1 test/e2e/*.test.mjs",
+    "test:run:integration": "node --test --test-concurrency=1 test/integration/*.test.mjs",
+    "test:run:root": "node --test --test-concurrency=1 test/*.test.mjs",
+    "test:run:unit": "node --test --test-concurrency=1 test/unit/*.test.mjs test/unit/extraction/*.test.mjs test/unit/models/*.test.mjs",
+    "test:unit": "npm run build && npm run test:run:unit",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "npm run build && node --test test/*.test.mjs"
+    "test": "npm run build && npm run test:all"
   },
   "devDependencies": {
-    "@types/node": "^25.9.4",
-    "typescript": "^5.9.3"
+    "@eslint/js": "^10.0.1",
+    "@modelcontextprotocol/conformance": "0.1.16",
+    "@types/node": "^22.20.1",
+    "c8": "^11.0.0",
+    "eslint": "^10.7.0",
+    "globals": "^17.7.0",
+    "prettier": "^3.9.5",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.64.0"
   },
   "dependencies": {
+    "@huggingface/transformers": "^3.8.1",
+    "@modelcontextprotocol/client": "2.0.0",
+    "@modelcontextprotocol/core": "2.0.0",
+    "@modelcontextprotocol/node": "2.0.0",
+    "@modelcontextprotocol/server": "2.0.0",
     "@vscode/ripgrep": "^1.18.0",
     "@zvec/zvec": "^0.5.0",
     "tree-sitter-wasms": "^0.1.13",
-    "web-tree-sitter": "^0.20.8"
+    "web-tree-sitter": "^0.20.8",
+    "zod": "4.2.0"
   },
   "optionalDependencies": {
     "node-llama-cpp": "3.18.1"

package/skills/zvec-grep/SKILL.md

@@ -1,141 +1,61 @@
 ---
 name: zvec-grep
-description: Use zvec-grep instead of grep or rg: check the index state once per repository investigation when needed, use existing indexed context when available, and use explicit zg --rg for lexical search when no index exists unless the user asks to build an index.
+description: Repository code search and indexing with zvec-grep. Use when exploring a codebase, locating symbols, references, or exact text, creating or inspecting a repository index, diagnosing the daemon, or whenever repository investigation would otherwise use grep, rg, or broad file reads.
 ---
 
 # zvec-grep
 
-Use zvec-grep through the `zg` command for repository search instead of `grep`, `rg`, or broad manual file scans. zvec-grep provides higher-quality results by combining indexed semantic context with lexical matching, while `zg --rg` provides an explicit no-index lexical search route.
+## Select the transport
 
-At the start of a repository investigation, check the current repository's anonymous index status once:
+Use zvec-grep indexed search for conceptual repository investigation. Use native
+`grep` or `rg` for exact lexical searches unless the optional managed-rg MCP tool
+is explicitly available.
 
-```bash
-zg --status
-```
+Use the public native HTTP MCP search tools as the primary interface when the matching `zvec_grep_*` tool is present. Call them directly; do not run `zg`, probe the daemon through shell, or choose CLI for convenience.
 
-Do not run `zg --status` before every search. Reuse the initial status for subsequent `zg` queries in the same root. Check again only when switching roots or collections, after an index/rebuild, or when a query reports an index problem that you need to diagnose.
+Use CLI fallback only when one of these conditions is true:
 
-If the index is missing, do not build it automatically and do not run a default `zg "<query>"` search. Use `zg --rg` for explicit exhaustive literal/regex search, and mention `zg --index` when the user wants persistent indexed semantic search. Indexing creates repository-local state, may load local models or call remote embedding providers, and should be a user-owned action.
+- The task requires index lifecycle or daemon diagnostics, which are intentionally
+  kept out of the default agent MCP toolset.
+- An available MCP search tool cannot perform the required operation.
+- MCP initialization, authentication, connection, or the required search call has
+  failed.
+- The repository has no index, the user has not authorized indexing, and an explicit no-index lexical search is needed.
 
-When indexing or rebuilding, choose useful repo paths instead of indexing everything. Prefer source, tests, docs, config, and scripts. zvec-grep skips dependency, third-party, generated, build, cache, hidden, nested-git, `.gitignore`d, and over-1MB files by default; use `--include` and `--exclude` to further keep the index focused:
+Do not retry a submitted indexing write through another transport after a connection interruption.
 
-```bash
-zg --index --embedding local/embeddinggemma-300m --include "src/**" --include "docs/**" --include "test/**" --exclude "dist/**,node_modules/**,coverage/**,.zvec-grep/**"
-zg --index --rebuild --embedding local/embeddinggemma-300m --include "src/**" --exclude "dist/**,node_modules/**,coverage/**,.zvec-grep/**"
-```
+## Use the MCP workflow
 
-If `zg --status` reports incompatible settings, ask before rebuilding. Existing anonymous indexes are checked and incrementally refreshed by query commands by default; use `--no-auto-update` only when diagnosing stale-index behavior. Rebuild only when the embedding schema or index version requires it:
+Pass the repository's daemon-visible absolute path as `root` on every repository call.
 
-```bash
-zg --index --rebuild --embedding local/embeddinggemma-300m
-```
+1. Use native `grep` or `rg` when an exact keyword, text, symbol, filename,
+   path, configuration key, error message, source fragment, literal, or regex
+   anchor is known and locating it is sufficient to answer the question.
+2. Call `zvec_grep_search` when the answer requires conceptual discovery,
+   architecture, lifecycle, data or control flow, comparison, design rationale,
+   or performance analysis. Search defaults to `freshness: "eventual"`; use
+   `freshness: "wait_for_fresh"` only when the result must include all pending
+   changes. Use hybrid `queries` for concepts plus known lexical constraints,
+   `fts` for indexed lexical-only intent, and `vector` for semantic-only intent.
+3. When exact symbols are present but the answer spans multiple components,
+   files, stages, or implementations, call `zvec_grep_search` first with the
+   concept and known symbols, then use native `grep` or `rg` for focused follow-up.
+4. Read the indexed search response's `freshness` and `indexing` fields. Use
+   `possibly_stale` results immediately when they are sufficient; do not call
+   status merely because a background update is active.
+5. Apply focused path and file-type filters early. Exclude dependencies,
+   generated output, caches, build artifacts, fixtures, and logs unless the
+   task concerns them.
 
-After an anonymous index exists, start with high-quality semantic context:
+The default public MCP endpoint intentionally exposes only indexed search. If the
+index is missing, explain that indexed search requires an index and ask before
+creating one. After authorization, use the CLI lifecycle workflow; never silently
+create, rebuild, or drop an index. The optional full MCP toolset exposes
+`zvec_grep_rg`; the CLI `zg query --rg` route remains available for explicit
+managed-ripgrep fallback.
 
-```bash
-zg "<query>"
-```
+Use multiple queries when comparing related concepts.
 
-Prefer the default indexed/hybrid search for exploration. Agent output uses `--preview none` by default to keep results token-efficient; `--human` uses `--preview full` by default for terminal reading. Use `--limit` to control candidate width, `--preview short` for a small deterministic source window, and `--preview full` after narrowing to a few results.
+## Use CLI fallback
 
-Use filters early. For source-code investigations, start with implementation paths and exclude tests, fixtures, generated output, dependencies, and build artifacts unless the task is specifically about those areas. Good filters keep candidate sets smaller and reduce token use:
-
-```bash
-zg "plugin loading lifecycle" --include "src/**" --exclude "test/**,tests/**,**/*.test.*,**/*.spec.*,fixtures/**,dist/**"
-zg "query planning" --include "src/**,packages/*/src/**" --exclude "test/**,tests/**,fixtures/**,node_modules/**,dist/**"
-```
-
-Indexed agent results use `--preview none` by default: essential metadata plus one representative source line when source is available. Human results use `--preview full` by default. Use `--preview short` for essential metadata plus a small deterministic source window, or `--preview full` after narrowing to a few results. `--preview` is for indexed/semantic results; with `--rg`, use ripgrep context flags such as `-A`, `-B`, or `-C` instead.
-
-```bash
-zg "plugin loading" --limit 30 --preview none
-zg "plugin loading" --limit 10 --preview short
-zg "plugin loading" --limit 3 --preview full
-```
-
-Use multiple quoted queries when you are exploring related ideas or comparing several names/concepts. Each query gets its own search group, and `--limit` applies per query/group:
-
-```bash
-zg "request validation" "error handling"
-zg "authentication flow" "session refresh" "permission checks" --limit 5
-```
-
-Use `zg --rg` only when you need exhaustive literal/regex search, exact verification, or ripgrep-specific flags. For exploratory code understanding, prefer default `zg` indexed search first:
-
-```bash
-zg --rg "SymbolName|LogMessage"
-zg --rg -F "ExactSymbolOrText" src
-zg --rg -i -C 2 -g "*.ts" -g "!dist/**" "needle text" src
-```
-
-Do not call `grep` or `rg` directly for repository search. If exhaustive regex or literal matching is required, use `zg --rg`; otherwise keep using default `zg` indexed search to avoid noisy, token-heavy match lists.
-
-Check the local anonymous index explicitly only when starting a repository investigation or diagnosing index state. Build it only when the user asks for persistent indexed semantic search:
-
-```bash
-zg --status
-zg --index --embedding local/embeddinggemma-300m
-zg --index --rebuild --embedding local/embeddinggemma-300m
-```
-
-For a new index, always pass `--embedding <model>` or set `ZVEC_GREP_EMBEDDING`; `zg --index` does not choose a model silently. For an existing index, rerunning `zg --index` without `--embedding` reuses the collection's stored embedding schema. Use `--embedding <model>` when intentionally choosing or changing models. Local models use `local/model`, such as `local/embeddinggemma-300m` and `local/qwen3-embedding-0.6b`. Remote models use `provider/model`, such as `qwen/text-embedding-v4`.
-
-```bash
-zg --index --embedding local/qwen3-embedding-0.6b
-zg --index --embedding qwen/text-embedding-v4 --api-key "$DASHSCOPE_API_KEY"
-```
-
-Use explicit routes only when the intent is clear:
-
-```bash
-zg --fts "ExactSymbolOrToken"
-zg --vector "natural language description of the code you need"
-zg --fts "AuthService" "validateRequest" --vector "where incoming requests are authorized"
-```
-
-Combine default hybrid queries with `--fts` when you want broad semantic/lexical recall plus exact anchors such as symbols, flags, error codes, or log text. Put the default hybrid queries first, then add one or more `--fts` terms:
-
-```bash
-zg "authentication flow" --fts "AuthService" --include "src/**"
-zg "cache invalidation" "stale data handling" --fts "CACHE_TTL" "invalidateCache" --limit 5
-zg "request routing behavior" --fts "routeRequest" "RouteOptions" --include "src/**"
-```
-
-Use query filters to narrow noisy searches before reading results. Prefer adding `--include` and `--exclude` to the first query when you already know the relevant area:
-
-```bash
-zg "error handling" --include "src/**" --exclude "dist/**,node_modules/**"
-zg "database migration" --include "src/**" --exclude "**/*.test.*"
-zg "recent API changes" --modified-after 2026-06-01 --modified-before 2026-06-25
-zg "create user" --symbol-type function --prefer-symbol
-zg "service lifecycle" "resource cleanup" --symbol-type class --symbol-type function --limit 5
-```
-
-Filter notes:
-
-- Quote glob filters so the shell does not expand them.
-- `--include` and `--exclude` accept comma-separated globs and can be repeated.
-- Dependency, third-party, generated, build, cache, nested-git, `.gitignore`d, and over-1MB files are skipped during indexing by default. Hidden dot paths are skipped by default; explicitly include useful hidden paths such as `.github/**`, `.codex/**`, or `.agents/**` with `--include` when needed. `.git/**` and `.zvec-grep/**` remain excluded.
-- `--modified-after` and `--modified-before` accept epoch milliseconds, `YYYY-MM-DD`, or other parseable date strings.
-- `--symbol-type` can be repeated; supported values are `module`, `class`, `interface`, `function`, `value`, and `alias`.
-- `--prefer-symbol` is useful when a query names a symbol and you want exact indexed symbol hits ranked first.
-- `--rg` is for exhaustive ripgrep search; do not combine it with indexed symbol options such as `--symbol-type` or `--prefer-symbol`. It uses rg regex syntax by default, so use `-F`/`--fixed-strings` for literal text, and use `-e`/`--regexp` when the pattern begins with `-`. It accepts common agent rg flags: `-n`, `-H`, `-F`, `-i`, `-w`, `-A`, `-B`, `-C`, `-e`/`--regexp`, `-g`/`--glob`, `--hidden`, `-t`/`--type`, `-T`/`--type-not`, `--max-depth`, `--ignore-file`, `--no-ignore`, `--smart-case`, and `--pcre2`. In `--rg`, `--limit` is a global match limit.
-
-Combine multiple queries, explicit routes, and filters for focused context:
-
-```bash
-zg "authorization failure" "permission checks" \
-  --fts "ForbiddenError" "hasPermission" \
-  --include "src/**" \
-  --exclude "dist/**,**/*.test.*" \
-  --symbol-type function \
-  --limit 5
-```
-
-Read output as:
-
-- `path:start-end` is the returned entity.
-- `outline:` is generated structure or call summary.
-- `matched:` is the matching excerpt range inside the entity or `--rg` context block.
-- `source:` is original file text for indexed results. `--rg` results omit the `source:` label and print numbered matching lines directly under `path:start-end`.
-- `--preview none` omits `outline:`, `matched:`, and `source:` blocks but keeps metadata and one representative numbered source line when source is available.
+Read [references/cli-fallback.md](references/cli-fallback.md) only after a fallback condition above is satisfied. Leave CLI mode unset for status, fallback search, and authorized indexing commands so the default Auto mode can select Server or Direct; do not probe forced Server mode and then retry forced Direct mode. Keep the selected transport consistent for the investigation unless its availability changes.

package/skills/zvec-grep/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "zvec-grep"
-  short_description: "Agent-friendly indexed repository search"
-  default_prompt: "Use zvec-grep through the zg command instead of grep or rg: check zg --status once at the start of a repository investigation when needed, then reuse that status for later searches in the same root; when indexing or rebuilding the local index, use --include and --exclude to index useful source/docs/tests/config/scripts and exclude generated, dependency, cache, build, log, and .zvec-grep garbage; prefer default zg indexed/hybrid queries for high-quality, token-efficient context; use --preview none for broad candidate scans and --preview full only after narrowing; use filters early, especially --include implementation paths and --exclude tests/fixtures/generated output when the task is about source code; use multiple quoted queries for related concepts; combine default hybrid queries with --fts exact anchors for symbols/flags/errors; narrow noisy searches with --include/--exclude/--modified-after/--modified-before/--symbol-type/--prefer-symbol; and use zg --rg only for exhaustive literal/regex verification with common rg flags such as -F, -i, -w, -A/-B/-C, -e/--regexp, -g/--glob, --hidden, --type, --type-not, --no-ignore, --smart-case, and --pcre2; use -e/--regexp when an rg pattern begins with -."
+  short_description: "Repository search with explicit index lifecycle"
+  default_prompt: "Use $zvec-grep to investigate this repository before raw grep or rg. Prefer the public MCP search tools, and use the zg CLI only for authorized index lifecycle or daemon diagnostics."

package/skills/zvec-grep/references/cli-fallback.md

@@ -0,0 +1,85 @@
+# CLI fallback
+
+Use these commands only when the native MCP tools are unavailable or when an explicit no-index lexical search is required.
+
+## Choose the route
+
+Leave `--mode` unset for ordinary status and query commands. The default Auto mode uses the daemon when reachable and Direct mode otherwise:
+
+```bash
+zg status
+zg query "authentication flow" --fts "AuthService" -g "src/**" -g "!tests/**" -g "!dist/**"
+```
+
+Do not probe with `--mode server` and then retry with `--mode direct`. Use an explicit mode only when diagnosing routing or when the user requests one. Do not force Direct writes while a daemon lease is active.
+
+## Check index state
+
+Check status once per repository investigation and reuse it:
+
+```bash
+zg status
+```
+
+If the index is missing, do not build it automatically. Mention `zg index` and wait for the user to authorize persistent indexing.
+
+## Search an existing index
+
+Start with indexed hybrid search, then add exact or semantic routes as needed:
+
+```bash
+zg query "request validation" "error handling" -g "src/**" -g "!tests/**" -g "!dist/**" --limit 10 --preview short
+zg query "authentication flow" --fts "AuthService" --fts "ForbiddenError" -g "src/**"
+zg query --vector "where incoming requests are authorized" -g "src/**"
+zg query "changes that must be indexed before search" --refresh wait
+```
+
+When Auto selects Server, queries return the current index and refresh stale data in the background by default. Direct queries do not refresh by default. Add `--refresh wait` when the query must wait for pending index changes, or `--refresh off` to disable refresh explicitly. Use `--preview none` for broad candidate scans, `--preview short` for a small deterministic window, and `--preview full` only after narrowing.
+
+## Recover from a Direct model failure
+
+Direct mode already attempts CPU fallback when local GPU initialization fails. Do not repeat the query with an explicit CPU override.
+
+If the local model or embedding context remains unavailable and exact anchors are available, remove positional hybrid and vector queries and search those anchors through the existing indexed FTS route. Indexed FTS does not require an embedding model:
+
+```bash
+zg query --fts "AuthService" --fts "ForbiddenError" -g "src/**" --limit 20 --preview short
+```
+
+Do not switch to managed ripgrep merely because semantic search is unavailable. Use it only when the task requires exhaustive literal or regex matching, or when no index exists and the user has not authorized creating one.
+
+## Search exhaustively with managed ripgrep
+
+Use managed ripgrep only for exhaustive literal or regex matching; it does not require an index:
+
+```bash
+zg query --rg "SymbolName|LogMessage"
+zg query --rg -F "ExactSymbolOrText" src
+zg query --rg -i -C 2 -g "*.ts" -g "!dist/**" "needle text" src
+```
+
+Managed ripgrep always runs locally. It remains available while the daemon is running or an index writer is active; do not stop the daemon or switch client mode before using it.
+
+Use `-e` or `--regexp` when the pattern begins with `-`. Common ripgrep flags include `-n`, `-H`, `-F`, `-i`, `-w`, `-A`, `-B`, `-C`, `-g`, `--hidden`, `--type`, `--type-not`, `--no-ignore`, `--smart-case`, and `--pcre2`.
+
+## Index only with authorization
+
+When a server default model is known, let Auto submit the index without repeating the model:
+
+```bash
+zg index
+```
+
+Otherwise, use the embedding model selected by the user:
+
+```bash
+zg index --embedding local/embeddinggemma-300m
+```
+
+Use focused path filters for a new index:
+
+```bash
+zg index --embedding local/embeddinggemma-300m -g "src/**" -g "docs/**" -g "test/**" -g "!dist/**" -g "!node_modules/**" -g "!coverage/**"
+```
+
+Rebuild only when an incompatible embedding schema or index version requires it. Existing indexes reuse their stored embedding schema unless the user intentionally changes it.

package/dist/engine/collection/index.d.ts

@@ -1,55 +0,0 @@
-import type { EmbeddingModel } from "../models/embeddings.js";
-import type { StoredEntity } from "../storage/index.js";
-import type { CollectionEmbeddingSchema, CollectionIndexStatus, CollectionInfo, EntitySearchDiagnosis, FileDiagnosis, FileInfo, IndexOptions, IndexResult, RootPath, SearchPlan, SearchPlanResult } from "../types.js";
-export declare class Collection {
-    readonly info: CollectionInfo;
-    private readonly embeddingModel?;
-    private readonly readOnly;
-    private readonly fileStorePath;
-    private readonly storage;
-    private readonly embedding;
-    constructor(info: CollectionInfo, embeddingModel?: EmbeddingModel | undefined, readOnly?: boolean, fileStorePath?: string);
-    get id(): string;
-    get name(): string;
-    index(options?: IndexOptions): Promise<IndexResult>;
-    status(): Promise<CollectionIndexStatus>;
-    searchPlan(plan: SearchPlan): Promise<SearchPlanResult>;
-    diagnoseFile(absolutePath: string): FileDiagnosis;
-    diagnoseEntitySearch(query: string, entityId: string): Promise<EntitySearchDiagnosis>;
-    diagnoseFileSearch(query: string, absolutePath: string): Promise<EntitySearchDiagnosis | null>;
-    getFile(absolutePath: string): FileInfo | null;
-    listEntitiesByFile(fileId: string, options?: {
-        limit?: number;
-        offset?: number;
-    }): StoredEntity[];
-    getEntity(entityId: string): StoredEntity | null;
-    close(): void;
-    private validateIndexVersion;
-    private validateEmbeddingSchema;
-    private requireEmbeddingModel;
-}
-export declare function isCollectionIndexed(info: CollectionInfo | null | undefined): info is CollectionInfo & {
-    embedding: CollectionEmbeddingSchema;
-    indexVersion: number;
-};
-export declare class CollectionRegistry {
-    readonly home: string;
-    private readonly embeddingModel?;
-    private readonly readOnly;
-    private readonly meta;
-    private readonly collections;
-    constructor(home?: string, embeddingModel?: EmbeddingModel | undefined, readOnly?: boolean);
-    list(): CollectionInfo[];
-    get(name: string): CollectionInfo | null;
-    has(name: string): boolean;
-    remove(name: string): boolean;
-    rename(name: string, nextName: string): CollectionInfo | null;
-    status(name: string): Promise<CollectionIndexStatus | null>;
-    create(name: string, rootPaths: readonly (string | RootPath)[], path?: string): CollectionInfo;
-    prepareIndex(name: string, rootPaths: readonly (string | RootPath)[], path?: string): CollectionInfo;
-    disableIndex(name: string, rootPaths: readonly (string | RootPath)[], path?: string): CollectionInfo;
-    updateRootPaths(name: string, rootPaths: readonly (string | RootPath)[]): CollectionInfo | null;
-    open(name: string): Collection;
-    close(): void;
-}
-export declare function defaultCollectionName(path: string): string;