@zvec/zvec-grep 0.1.0

package/dist/engine/utils/lock.js

@@ -0,0 +1,254 @@
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { hostname } from "node:os";
+import { dirname, join } from "node:path";
+import { detail, EngineError, errorDetails } from "../errors/index.js";
+const LOCK_INFO_FILE = "lock.json";
+const DEFAULT_STALE_LOCK_MS = 6 * 60 * 60 * 1000;
+function acquireExclusiveDirectoryLock(lockPath, options) {
+    mkdirSync(dirname(lockPath), { recursive: true });
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            mkdirSync(lockPath);
+            const info = currentLockInfo(options.operation);
+            writeFileSync(lockInfoPath(lockPath), `${JSON.stringify(info, null, 2)}\n`, "utf8");
+            return {
+                path: lockPath,
+                info,
+                release: () => releaseFileLock(lockPath, info),
+            };
+        }
+        catch (error) {
+            if (!isNodeError(error) || error.code !== "EEXIST") {
+                throw error;
+            }
+            if (cleanupStaleLock(lockPath, options.staleMs ?? DEFAULT_STALE_LOCK_MS)) {
+                continue;
+            }
+            throw lockBusyError(lockPath, options.operation);
+        }
+    }
+    throw lockBusyError(lockPath, options.operation);
+}
+function assertExclusiveDirectoryUnlocked(lockPath, operation) {
+    if (!existsSync(lockPath)) {
+        return;
+    }
+    if (cleanupStaleLock(lockPath, DEFAULT_STALE_LOCK_MS)) {
+        return;
+    }
+    throw lockBusyError(lockPath, operation);
+}
+export function acquireReadWriteLock(lockPath, mode, options) {
+    return mode === "read"
+        ? acquireReadLock(lockPath, options)
+        : acquireWriteLock(lockPath, options);
+}
+export function assertNoWriteLock(lockPath, operation) {
+    assertExclusiveDirectoryUnlocked(writeLockPath(lockPath), operation);
+}
+function currentLockInfo(operation) {
+    return {
+        token: randomUUID(),
+        pid: process.pid,
+        hostname: hostname(),
+        startedAt: Date.now(),
+        operation,
+    };
+}
+function acquireReadLock(lockPath, options) {
+    mkdirSync(dirname(lockPath), { recursive: true });
+    const staleMs = options.staleMs ?? DEFAULT_STALE_LOCK_MS;
+    const writePath = writeLockPath(lockPath);
+    for (let attempt = 0; attempt < 2; attempt++) {
+        if (existsSync(writePath)) {
+            if (cleanupStaleLock(writePath, staleMs)) {
+                continue;
+            }
+            throw lockBusyError(writePath, options.operation);
+        }
+        const info = currentLockInfo(options.operation);
+        const readerPath = join(readersLockPath(lockPath), `${info.pid}-${info.token}`);
+        try {
+            mkdirSync(readerPath, { recursive: true });
+            writeFileSync(lockInfoPath(readerPath), `${JSON.stringify(info, null, 2)}\n`, "utf8");
+            if (existsSync(writePath)) {
+                releaseFileLock(readerPath, info);
+                if (cleanupStaleLock(writePath, staleMs)) {
+                    continue;
+                }
+                throw lockBusyError(writePath, options.operation);
+            }
+            return {
+                path: readerPath,
+                info,
+                release: () => releaseFileLock(readerPath, info),
+            };
+        }
+        catch (error) {
+            releaseFileLock(readerPath, info);
+            if (!isNodeError(error) || error.code !== "EEXIST") {
+                throw error;
+            }
+        }
+    }
+    throw lockBusyError(writePath, options.operation);
+}
+function acquireWriteLock(lockPath, options) {
+    const staleMs = options.staleMs ?? DEFAULT_STALE_LOCK_MS;
+    const writePath = writeLockPath(lockPath);
+    for (let attempt = 0; attempt < 2; attempt++) {
+        const lock = acquireExclusiveDirectoryLock(writePath, options);
+        if (!hasActiveReaders(lockPath, staleMs)) {
+            return lock;
+        }
+        lock.release();
+        throw readLockBusyError(lockPath, options.operation);
+    }
+    throw readLockBusyError(lockPath, options.operation);
+}
+function releaseFileLock(lockPath, owner) {
+    const current = readLockInfo(lockPath);
+    if (current?.token !== owner.token) {
+        return;
+    }
+    rmSync(lockPath, { recursive: true, force: true });
+}
+function cleanupStaleLock(lockPath, staleMs) {
+    if (!existsSync(lockPath)) {
+        return false;
+    }
+    const info = readLockInfo(lockPath);
+    if (!isStaleLock(lockPath, info, staleMs)) {
+        return false;
+    }
+    rmSync(lockPath, { recursive: true, force: true });
+    return true;
+}
+function hasActiveReaders(lockPath, staleMs) {
+    const readersPath = readersLockPath(lockPath);
+    if (!existsSync(readersPath)) {
+        return false;
+    }
+    let entries;
+    try {
+        entries = readdirSync(readersPath);
+    }
+    catch {
+        return false;
+    }
+    let active = false;
+    for (const entry of entries) {
+        const readerPath = join(readersPath, entry);
+        if (cleanupStaleLock(readerPath, staleMs)) {
+            continue;
+        }
+        active = true;
+    }
+    return active;
+}
+function isStaleLock(lockPath, info, staleMs) {
+    const now = Date.now();
+    const startedAt = info?.startedAt ?? lockDirectoryMtime(lockPath);
+    const expired = now - startedAt > staleMs;
+    if (!info) {
+        return expired;
+    }
+    if (info.hostname === hostname() && !processIsAlive(info.pid)) {
+        return true;
+    }
+    return expired;
+}
+function processIsAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0) {
+        return false;
+    }
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return isNodeError(error) && error.code === "EPERM";
+    }
+}
+function readLockInfo(lockPath) {
+    try {
+        const parsed = JSON.parse(readFileSync(lockInfoPath(lockPath), "utf8"));
+        if (typeof parsed.token === "string"
+            && typeof parsed.pid === "number"
+            && typeof parsed.hostname === "string"
+            && typeof parsed.startedAt === "number"
+            && typeof parsed.operation === "string") {
+            return parsed;
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+function lockDirectoryMtime(lockPath) {
+    try {
+        return statSync(lockPath).mtimeMs;
+    }
+    catch {
+        return Date.now();
+    }
+}
+function lockBusyError(lockPath, requestedOperation) {
+    const owner = readLockInfo(lockPath);
+    return new EngineError("Index unavailable", {
+        code: "ZVEC_GREP.ENGINE.LOCK.BUSY",
+        context: errorDetails([
+            detail("lock", lockPath),
+            detail("operation", requestedOperation),
+            detail("ownerOperation", owner?.operation),
+            detail("ownerPid", owner?.pid),
+            detail("ownerHost", owner?.hostname),
+        ]),
+    });
+}
+function readLockBusyError(lockPath, requestedOperation) {
+    const owner = firstActiveReaderInfo(lockPath);
+    return new EngineError("Index unavailable", {
+        code: "ZVEC_GREP.ENGINE.LOCK.BUSY",
+        context: errorDetails([
+            detail("lock", readersLockPath(lockPath)),
+            detail("operation", requestedOperation),
+            detail("ownerOperation", owner?.operation),
+            detail("ownerPid", owner?.pid),
+            detail("ownerHost", owner?.hostname),
+        ]),
+    });
+}
+function firstActiveReaderInfo(lockPath) {
+    const readersPath = readersLockPath(lockPath);
+    if (!existsSync(readersPath)) {
+        return null;
+    }
+    try {
+        for (const entry of readdirSync(readersPath)) {
+            const info = readLockInfo(join(readersPath, entry));
+            if (info) {
+                return info;
+            }
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+function lockInfoPath(lockPath) {
+    return join(lockPath, LOCK_INFO_FILE);
+}
+function writeLockPath(lockPath) {
+    return `${lockPath}.write`;
+}
+function readersLockPath(lockPath) {
+    return `${lockPath}.readers`;
+}
+function isNodeError(error) {
+    return typeof error === "object" && error !== null && "code" in error;
+}
+//# sourceMappingURL=lock.js.map

package/dist/engine/utils/lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.js","sourceRoot":"","sources":["../../../src/engine/utils/lock.ts"],"names":[],"mappings":"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"}

package/dist/engine/utils/path.d.ts

@@ -0,0 +1,4 @@
+export declare function defaultHome(): string;
+export declare function normalizePath(path: string): string;
+export declare function toDisplayPath(path: string): string;
+export declare function isPathInside(parent: string, child: string): boolean;

package/dist/engine/utils/path.js

@@ -0,0 +1,18 @@
+import { homedir } from "node:os";
+import { resolve, sep } from "node:path";
+export function defaultHome() {
+    return process.env.ZVEC_GREP_HOME ?? resolve(homedir(), ".zvec-grep");
+}
+export function normalizePath(path) {
+    return resolve(path);
+}
+export function toDisplayPath(path) {
+    return path.split(sep).join("/");
+}
+export function isPathInside(parent, child) {
+    const normalizedParent = normalizePath(parent);
+    const normalizedChild = normalizePath(child);
+    return normalizedChild === normalizedParent
+        || normalizedChild.startsWith(`${normalizedParent}${sep}`);
+}
+//# sourceMappingURL=path.js.map

package/dist/engine/utils/path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.js","sourceRoot":"","sources":["../../../src/engine/utils/path.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAGzC,MAAM,UAAU,WAAW;IACzB,OAAO,OAAO,CAAC,GAAG,CAAC,cAAc,IAAI,OAAO,CAAC,OAAO,EAAE,EAAE,YAAY,CAAC,CAAC;AACxE,CAAC;AAGD,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC;AACvB,CAAC;AAGD,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACnC,CAAC;AAGD,MAAM,UAAU,YAAY,CAAC,MAAc,EAAE,KAAa;IACxD,MAAM,gBAAgB,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;IAC/C,MAAM,eAAe,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IAE7C,OAAO,eAAe,KAAK,gBAAgB;WACtC,eAAe,CAAC,UAAU,CAAC,GAAG,gBAAgB,GAAG,GAAG,EAAE,CAAC,CAAC;AAC/D,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { createZvecGrep, } from "./engine/service/index.js";
+export type { CreateZvecGrepOptions, ZvecGrep, ZvecGrepCollectionIndexOptions, ZvecGrepCollections, ZvecGrepContent, ZvecGrepContextCollection, ZvecGrepContextCoverage, ZvecGrepContextDiagnostics, ZvecGrepContextFile, ZvecGrepContextItem, ZvecGrepContextItemKind, ZvecGrepContextOptions, ZvecGrepContextResult, ZvecGrepContextRoute, ZvecGrepContextSource, ZvecGrepFallbackPolicy, ZvecGrepIndexDiagnostics, ZvecGrepInfoOptions, ZvecGrepInfoResult, ZvecGrepInitOptions, ZvecGrepLexicalFallbackDiagnostics, } from "./engine/service/index.js";
+export { EMBEDDING_MODEL_CATALOG, MODEL_CATALOG, createEmbeddingModel, createEmbeddingModelFromCatalog, createEmbeddingModelFromReference, EmbeddingModel, getEmbeddingModelCatalogEntry, getEmbeddingModelCatalogEntryByRef, listEmbeddingModels, } from "./engine/models/index.js";
+export { isImageContent, isTextContent, } from "./engine/types.js";
+export type { CodeEntityMetadata, CodeEntityModifier, CodeSymbolType, CollectionEmbeddingSchema, CollectionIndexStatus, CollectionInfo, Content, ContentKind, EntityMetadata, FileFormat, FileIndexStatus, FileInfo, FileKind, ImageContent, ImageFormat, IndexOptions, IndexProgress, IndexProgressPhase, IndexResult, MarkdownEntityMetadata, RootPath, SearchFinalTrace, SearchHitTrace, SearchRecallTrace, SearchStageTrace, TextContent, } from "./engine/types.js";
+export type { EmbeddingCatalogEntry, LlamaCppEmbeddingCatalogEntry, LlamaGpuMode, LocalEmbeddingFormat, ModelProviderOptions, } from "./engine/models/index.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export { createZvecGrep, } from "./engine/service/index.js";
+export { EMBEDDING_MODEL_CATALOG, MODEL_CATALOG, createEmbeddingModel, createEmbeddingModelFromCatalog, createEmbeddingModelFromReference, EmbeddingModel, getEmbeddingModelCatalogEntry, getEmbeddingModelCatalogEntryByRef, listEmbeddingModels, } from "./engine/models/index.js";
+export { isImageContent, isTextContent, } from "./engine/types.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,GACf,MAAM,2BAA2B,CAAC;AAwBnC,OAAO,EACL,uBAAuB,EACvB,aAAa,EACb,oBAAoB,EACpB,+BAA+B,EAC/B,iCAAiC,EACjC,cAAc,EACd,6BAA6B,EAC7B,kCAAkC,EAClC,mBAAmB,GACpB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,cAAc,EACd,aAAa,GACd,MAAM,mBAAmB,CAAC"}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@zvec/zvec-grep",
+  "version": "0.1.0",
+  "description": "Agent-friendly hybrid grep with indexed context and lexical fallback.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "zg": "dist/cli/index.js"
+  },
+  "files": [
+    "README.md",
+    "README_CN.md",
+    "LICENSE",
+    "dist",
+    "skills/zvec-grep"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && node --test test/*.test.mjs"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.4",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "@vscode/ripgrep": "^1.18.0",
+    "@zvec/zvec": "^0.5.0",
+    "tree-sitter-wasms": "^0.1.13",
+    "web-tree-sitter": "^0.20.8"
+  },
+  "optionalDependencies": {
+    "node-llama-cpp": "3.18.1"
+  }
+}

package/skills/zvec-grep/SKILL.md

@@ -0,0 +1,141 @@
+---
+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 initialize.
+---
+
+# 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.
+
+At the start of a repository investigation, check the current repository's anonymous index status once:
+
+```bash
+zg --info
+```
+
+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 init/rebuild, or when a query reports an index problem that you need to diagnose.
+
+If the index is missing, do not initialize it automatically and do not run a default `zg "<query>"` search. Use `zg --rg` for explicit exhaustive literal/regex search, and mention `zg --init` when the user wants persistent indexed semantic search. Initializing creates repository-local state, may load local models or call remote embedding providers, and should be a user-owned action.
+
+When initializing 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:
+
+```bash
+zg --init --embedding local/embeddinggemma-300m --include "src/**" --include "docs/**" --include "test/**" --exclude "dist/**,node_modules/**,coverage/**,.zvec-grep/**"
+zg --init --rebuild --embedding local/embeddinggemma-300m --include "src/**" --exclude "dist/**,node_modules/**,coverage/**,.zvec-grep/**"
+```
+
+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:
+
+```bash
+zg --init --rebuild --embedding local/embeddinggemma-300m
+```
+
+After an anonymous index exists, start with high-quality semantic context:
+
+```bash
+zg "<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.
+
+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 --info
+zg --init --embedding local/embeddinggemma-300m
+zg --init --rebuild --embedding local/embeddinggemma-300m
+```
+
+For a new index, always pass `--embedding <model>` or set `ZVEC_GREP_EMBEDDING`; `zg --init` does not choose a model silently. For an existing index, rerunning `zg --init` 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 --init --embedding local/qwen3-embedding-0.6b
+zg --init --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, 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.
+- `--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.

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

@@ -0,0 +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 initializing 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 -."