@zvec/zvec-grep 0.1.3 → 0.1.5

package/skills/zvec-grep/SKILL.md

@@ -1,39 +1,39 @@
 ---
 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: 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 query --rg for lexical search when no index exists unless the user asks to build an index.
 ---
 
 # 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.
+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 query --rg` provides an explicit no-index lexical search route.
 
 At the start of a repository investigation, check the current repository's anonymous index status once:
 
 ```bash
-zg --info
+zg status
 ```
 
-Do not run `zg --info` 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.
+Do not run `zg status` before every search. Reuse the initial status for subsequent `zg query` calls 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.
 
-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.
+If the index is missing, do not build it automatically and do not run a default `zg query "<query>"` search. Use `zg query --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.
 
-When indexing or rebuilding, choose useful repo paths instead of indexing everything. Prefer source, tests, docs, config, and scripts. zvec-grep skips dependency, build, cache, `.gitignore`d, and over-1MB files by default; use `--include` and `--exclude` to further keep the index focused:
+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 repeatable rg-style `-g`/`--glob` and `-t`/`--type` filters to keep the index focused:
 
 ```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/**"
+zg index --embedding local/embeddinggemma-300m -g "src/**" -g "docs/**" -g "test/**" -g "!dist/**" -g "!node_modules/**"
+zg index --rebuild --embedding local/embeddinggemma-300m -g "src/**" -g "!dist/**" -g "!node_modules/**" -t ts
 ```
 
-If `zg --info` 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:
+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:
 
 ```bash
-zg --index --rebuild --embedding local/embeddinggemma-300m
+zg index --rebuild --embedding local/embeddinggemma-300m
 ```
 
 After an anonymous index exists, start with high-quality semantic context:
 
 ```bash
-zg "<query>"
+zg query "<query>"
 ```
 
 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.
@@ -41,93 +41,103 @@ Prefer the default indexed/hybrid search for exploration. Agent output uses `--p
 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/**"
+zg query "plugin loading lifecycle" -g "src/**" -g "!test/**" -g "!tests/**" -g "!**/*.test.*" -g "!**/*.spec.*"
+zg query "query planning" -g "src/**" -g "packages/*/src/**" -g "!fixtures/**" -g "!node_modules/**" -t ts
 ```
 
 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
+zg query "plugin loading" --limit 30 --preview none
+zg query "plugin loading" --limit 10 --preview short
+zg query "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
+zg query "request validation" "error handling"
+zg query "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:
+Use `--fuse` only when those groups should contribute to one combined ranking;
+then `--limit` applies to the final fused list:
 
 ```bash
-zg --rg "SymbolName|LogMessage"
-zg --rg -F "ExactSymbolOrText" src
-zg --rg -i -C 2 -g "*.ts" -g "!dist/**" "needle text" src
+zg query --hybrid "authentication flow" --fts "AuthService" --vector "credential validation" --fuse --limit 10
 ```
 
-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.
+Use `zg query --rg` only when you need exhaustive literal/regex search, exact verification, or ripgrep-specific flags. For exploratory code understanding, prefer indexed `zg query` search first:
+
+```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
+```
+
+Do not call `grep` or `rg` directly for repository search. If exhaustive regex or literal matching is required, use `zg query --rg`; otherwise keep using indexed `zg query` 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 --info
-zg --index --embedding local/embeddinggemma-300m
-zg --index --rebuild --embedding local/embeddinggemma-300m
+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`.
+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"
+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"
+zg query --fts "ExactSymbolOrToken"
+zg query --vector "natural language description of the code you need"
+zg query --fts "AuthService" --fts "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/**"
+zg query "authentication flow" --fts "AuthService" -g "src/**" -t ts
+zg query "cache invalidation" "stale data handling" --fts "CACHE_TTL" --fts "invalidateCache" --limit 5
+zg query "request routing behavior" --fts "routeRequest" --fts "RouteOptions" -g "src/**" -t ts
 ```
 
-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:
+Use query filters to narrow noisy searches before reading results. Prefer adding `-g`/`--glob`, `--iglob`, `-t`/`--type`, and `-T`/`--type-not` 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
+zg query "error handling" -g "src/**" -g "!dist/**" -g "!node_modules/**"
+zg query "database migration" -g "src/**" -g "!**/*.test.*"
+zg query "recent API changes" --modified-after 2026-06-01 --modified-before 2026-06-25
+zg query "create user" --symbol-type function --prefer-symbol
+zg query "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, build, cache, `.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.
+- `-g`/`--glob` accepts one glob and can be repeated. Prefix a glob with `!` to exclude it. Use `--iglob` for case-insensitive globs.
+- `-t`/`--type` and `-T`/`--type-not` use ripgrep's file-type names and work in indexed and rg modes.
+- Type filters further restrict the glob-selected files. For example, `-g "docs/**" -t ts` selects only TypeScript files under `docs`.
+- 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; use `--hidden` when explicitly 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.
+- `--rg` is for exhaustive ripgrep search outside `.git/**` and `.zvec-grep/**`; 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` for literal text and `-e` when a pattern begins with `-`. Managed rg supports common matching, pattern-file, context, glob, type, ignore, depth, size, symlink, encoding, multiline, and regex-engine flags. Zvec-grep owns the result format, so output-changing flags such as `--json`, `--count`, `--files`, `-l`, `-o`, `--replace`, and `--vimgrep` are rejected. In `--rg`, `--limit` is a global result limit while `-m`/`--max-count` retains rg's per-file meaning.
 
 Combine multiple queries, explicit routes, and filters for focused context:
 
 ```bash
-zg "authorization failure" "permission checks" \
-  --fts "ForbiddenError" "hasPermission" \
-  --include "src/**" \
-  --exclude "dist/**,**/*.test.*" \
+zg query "authorization failure" "permission checks" \
+  --fts "ForbiddenError" --fts "hasPermission" \
+  -g "src/**" \
+  -g "!dist/**" \
+  -g "!**/*.test.*" \
   --symbol-type function \
   --limit 5
 ```

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 --info 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 -."
+  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 zg index with repeatable rg-style -g/--glob filters and, for language-specific scopes, -t/--type filters to index useful source/docs/tests/config/scripts and exclude generated, dependency, cache, build, log, and .zvec-grep garbage; prefer zg query indexed/hybrid searches for high-quality, token-efficient context; use --preview none for broad candidate scans and --preview full only after narrowing; use the same -g/--iglob/-t/-T filters for indexed and rg queries when applicable; use multiple quoted queries for related concepts; combine hybrid queries with repeated --fts exact anchors for symbols/flags/errors; narrow noisy searches with globs, types, --modified-after/--modified-before/--symbol-type/--prefer-symbol; and use zg query --rg only for exhaustive literal/regex verification with common rg matching, pattern-file, context, ignore, depth, size, encoding, multiline, and regex-engine flags; use -e/--regexp when an rg pattern begins with -."