@zvec/zvec-grep 0.1.3 → 0.1.5

package/dist/engine/service/zvec-grep.js

@@ -1,18 +1,20 @@
-import { mkdirSync, readdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { mkdirSync, readdirSync, readFileSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
 import { createHash } from "node:crypto";
 import { dirname, join, relative, resolve } from "node:path";
+import { globalConfigPath, readGlobalConfig, } from "../config.js";
 import { Collection, CollectionRegistry, isCollectionIndexed, } from "../collection/index.js";
 import { collectionDetail, detail, EngineError, errorDetails, } from "../errors/index.js";
 import { createEmbeddingModel, createEmbeddingModelFromReference, } from "../models/index.js";
 import { ANONYMOUS_COLLECTION_NAME, anonymousCollectionPath, anonymousHome, anonymousIndexLocation, resolveZvecGrepRoot, } from "./root.js";
-import { runLexicalFallback, runRgSearch } from "./lexical.js";
-import { defaultHome } from "../utils/path.js";
-import { acquireReadWriteLock, assertNoWriteLock } from "../utils/lock.js";
+import { runRgSearch } from "./lexical.js";
+import { defaultHome, normalizePath } from "../utils/path.js";
+import { acquireReadWriteLock, assertNoWriteLock, } from "../utils/lock.js";
 import { TimingCollector } from "../utils/timing.js";
 import { enrichLexicalItemsWithStructure } from "./structure-enrichment.js";
 const DEFAULT_CONTEXT_LIMIT = 10;
 const DEFAULT_CONTEXT_TOTAL_LIMIT = 30;
 const DEFAULT_LOCAL_EMBEDDING = "local/embeddinggemma-300m";
+const MAX_RECOVERED_EMBEDDING_MODELS = 4;
 export async function createZvecGrep(options = {}) {
     return new ZvecGrepService(options);
 }
@@ -21,14 +23,14 @@ class ZvecGrepService {
     root;
     collections;
     embeddingModel;
-    embeddingModelExplicit;
     recoveredEmbeddingModels = new Map();
+    retiredEmbeddingModels = new Set();
+    activeEmbeddingModelOperations = 0;
     closed = false;
     constructor(options) {
         this.options = options;
         this.root = resolveZvecGrepRoot(options.root);
-        this.embeddingModelExplicit = hasExplicitEmbeddingModel(options);
-        this.embeddingModel = resolveEmbeddingModel(options, this.root);
+        this.embeddingModel = options.embeddingModel;
         this.collections = {
             list: () => this.listCollections(),
             info: (name) => this.collectionInfo(name),
@@ -41,7 +43,7 @@ class ZvecGrepService {
         this.ensureOpen();
         const root = resolveZvecGrepRoot(options.root ?? this.root);
         const location = anonymousIndexLocation(root);
-        return await withHomeWriteLock(location.home, options.rebuild ? "index.rebuild" : "index", async () => {
+        return await this.withEmbeddingModelOperation(() => withHomeWriteLock(location.home, options.rebuild ? "index.rebuild" : "index", async () => {
             const existing = readCollectionInfo(location.home, ANONYMOUS_COLLECTION_NAME);
             const embeddingModel = this.embeddingModelForIndex(existing, location.home, "index");
             const registry = new CollectionRegistry(location.home, embeddingModel);
@@ -50,13 +52,23 @@ class ZvecGrepService {
                     resetPaths: options.resetPaths === true,
                     includePaths: options.includePaths,
                     excludePaths: options.excludePaths,
+                    globs: options.globs,
+                    insensitiveGlobs: options.insensitiveGlobs,
+                    fileTypes: options.fileTypes,
+                    excludedFileTypes: options.excludedFileTypes,
+                    hidden: options.hidden,
+                    noIgnore: options.noIgnore,
+                    ignoreFiles: options.ignoreFiles,
+                    maxDepth: options.maxDepth,
+                    maxFileSizeBytes: options.maxFileSizeBytes,
+                    follow: options.follow,
                 });
                 if (options.rebuild) {
                     registry.remove(ANONYMOUS_COLLECTION_NAME);
                 }
                 const existingAfterRebuild = registry.get(ANONYMOUS_COLLECTION_NAME);
                 if (isCollectionIndexed(existingAfterRebuild)) {
-                    assertCollectionEmbeddingMatchesCurrentModel(existingAfterRebuild, embeddingModel, "zg --index --rebuild");
+                    assertCollectionEmbeddingMatchesCurrentModel(existingAfterRebuild, embeddingModel, "zg index --rebuild");
                 }
                 registry.prepareIndex(ANONYMOUS_COLLECTION_NAME, rootPaths, anonymousCollectionPath(root));
                 return await registry.open(ANONYMOUS_COLLECTION_NAME).index({
@@ -68,6 +80,23 @@ class ZvecGrepService {
             finally {
                 registry.close();
             }
+        }));
+    }
+    async dropIndex(options = {}) {
+        this.ensureOpen();
+        const root = resolveZvecGrepRoot(options.root ?? this.root);
+        const location = anonymousIndexLocation(root);
+        if (!readCollectionInfo(location.home, ANONYMOUS_COLLECTION_NAME)) {
+            return false;
+        }
+        return await withHomeWriteLock(location.home, "index.drop", async () => {
+            const registry = new CollectionRegistry(location.home, undefined);
+            try {
+                return registry.remove(ANONYMOUS_COLLECTION_NAME);
+            }
+            finally {
+                registry.close();
+            }
         });
     }
     async disableIndex(options = {}) {
@@ -87,9 +116,11 @@ class ZvecGrepService {
     }
     async context(options) {
         this.ensureOpen();
-        const timings = new TimingCollector();
-        const result = await timings.time("total", () => this.contextWithTimings(options, timings));
-        return withContextTimings(result, timings);
+        return await this.withEmbeddingModelOperation(async () => {
+            const timings = new TimingCollector();
+            const result = await timings.time("total", () => this.contextWithTimings(options, timings));
+            return withContextTimings(result, timings);
+        });
     }
     async contextWithTimings(options, timings) {
         const request = normalizeContextRequest(options);
@@ -131,16 +162,16 @@ class ZvecGrepService {
                 home: location.home,
                 indexPath: location.collectionPath,
                 source: "unindexed",
-                suggestion: "zg --index or zg --rg",
+                suggestion: "zg index or zg query --rg",
             };
         }
         return await withHomeReadLock(nearest.location.home, "info", async () => {
             const registry = new CollectionRegistry(nearest.location.home, undefined, true);
             try {
                 const collection = registry.get(ANONYMOUS_COLLECTION_NAME);
-                const indexed = collection !== null
-                    && collection.indexPolicy !== "disabled"
-                    && isCollectionIndexed(collection);
+                const indexed = collection !== null &&
+                    collection.indexPolicy !== "disabled" &&
+                    isCollectionIndexed(collection);
                 return {
                     root: nearest.location.root,
                     indexed,
@@ -149,7 +180,9 @@ class ZvecGrepService {
                     indexPath: nearest.location.collectionPath,
                     source: indexed ? "index" : "unindexed",
                     collection: collection ?? undefined,
-                    status: indexed ? await registry.status(ANONYMOUS_COLLECTION_NAME) : null,
+                    status: indexed
+                        ? await registry.status(ANONYMOUS_COLLECTION_NAME)
+                        : null,
                     suggestion: anonymousInfoSuggestion(collection),
                 };
             }
@@ -162,8 +195,10 @@ class ZvecGrepService {
         const models = new Set([
             ...(this.embeddingModel ? [this.embeddingModel] : []),
             ...this.recoveredEmbeddingModels.values(),
+            ...this.retiredEmbeddingModels,
         ]);
         this.recoveredEmbeddingModels.clear();
+        this.retiredEmbeddingModels.clear();
         for (const model of models) {
             await model.dispose();
         }
@@ -208,7 +243,7 @@ class ZvecGrepService {
     async indexCollection(name, paths, options = {}) {
         this.ensureOpen();
         const home = serviceHome(this.options);
-        return await withHomeWriteLock(home, options.rebuild ? "collections.index.rebuild" : "collections.index", async () => {
+        return await this.withEmbeddingModelOperation(() => withHomeWriteLock(home, options.rebuild ? "collections.index.rebuild" : "collections.index", async () => {
             const existing = readCollectionInfo(home, name);
             const embeddingModel = this.embeddingModelForIndex(existing, home, "collections.index");
             const registry = this.createRegistry(false, embeddingModel);
@@ -222,13 +257,23 @@ class ZvecGrepService {
                     resetPaths: options.resetPaths === true,
                     includePaths: options.includePaths,
                     excludePaths: options.excludePaths,
+                    globs: options.globs,
+                    insensitiveGlobs: options.insensitiveGlobs,
+                    fileTypes: options.fileTypes,
+                    excludedFileTypes: options.excludedFileTypes,
+                    hidden: options.hidden,
+                    noIgnore: options.noIgnore,
+                    ignoreFiles: options.ignoreFiles,
+                    maxDepth: options.maxDepth,
+                    maxFileSizeBytes: options.maxFileSizeBytes,
+                    follow: options.follow,
                 });
                 if (options.rebuild) {
                     registry.remove(name);
                 }
                 const existingAfterRebuild = registry.get(name);
                 if (isCollectionIndexed(existingAfterRebuild)) {
-                    assertCollectionEmbeddingMatchesCurrentModel(existingAfterRebuild, embeddingModel, "zg --collections index <name> --rebuild");
+                    assertCollectionEmbeddingMatchesCurrentModel(existingAfterRebuild, embeddingModel, "zg collections index <name> --rebuild");
                 }
                 registry.prepareIndex(name, rootPaths);
                 return await registry.open(name).index({
@@ -239,7 +284,7 @@ class ZvecGrepService {
             finally {
                 registry.close();
             }
-        });
+        }));
     }
     async removeCollection(name) {
         this.ensureOpen();
@@ -305,7 +350,7 @@ class ZvecGrepService {
                 return;
             }
             const embeddingModel = this.embeddingModelForIndex(existing, location.home, "context.refresh");
-            assertCollectionEmbeddingMatchesCurrentModel(existing, embeddingModel, "zg --index --rebuild");
+            assertCollectionEmbeddingMatchesCurrentModel(existing, embeddingModel, "zg index --rebuild");
             const registry = new CollectionRegistry(location.home, embeddingModel);
             try {
                 const result = await registry.open(ANONYMOUS_COLLECTION_NAME).index({
@@ -332,7 +377,8 @@ class ZvecGrepService {
                     });
                 }
                 const collection = this.openCollectionForSearch(info, request, registry.home);
-                const root = collection.info.rootPaths[0]?.absolutePath ?? resolveZvecGrepRoot(options.root ?? this.root);
+                const root = collection.info.rootPaths[0]?.absolutePath ??
+                    resolveZvecGrepRoot(options.root ?? this.root);
                 try {
                     return await this.contextFromCollection({
                         root,
@@ -341,7 +387,6 @@ class ZvecGrepService {
                         anonymous: false,
                         options: {
                             ...options,
-                            fallback: "disabled",
                         },
                         timings,
                     });
@@ -357,8 +402,11 @@ class ZvecGrepService {
     }
     async contextFromCollection(input) {
         const searches = [];
-        const limit = contextGroupLimit(input.options.limit, input.request.groups.length);
-        for (const group of input.request.groups) {
+        const groups = input.options.fuse
+            ? [{ routes: input.request.routes }]
+            : input.request.groups;
+        const limit = contextGroupLimit(input.options.limit, groups.length);
+        for (const group of groups) {
             const search = await input.collection.searchPlan({
                 routes: group.routes,
                 limit,
@@ -367,6 +415,10 @@ class ZvecGrepService {
                 symbolTypes: input.options.symbolTypes,
                 includePaths: input.options.includePaths,
                 excludePaths: input.options.excludePaths,
+                globs: input.options.globs,
+                insensitiveGlobs: input.options.insensitiveGlobs,
+                fileTypes: input.options.fileTypes,
+                excludedFileTypes: input.options.excludedFileTypes,
                 modifiedAfter: input.options.modifiedAfter,
                 modifiedBefore: input.options.modifiedBefore,
             });
@@ -395,45 +447,26 @@ class ZvecGrepService {
             },
         };
     }
-    async contextFromLexicalFallback(root, request, options, timings) {
-        const fallbackResults = [];
-        const limit = contextGroupLimit(options.limit, request.groups.length);
-        for (const query of request.fallbackQueries) {
-            fallbackResults.push(await timings.time("fallback_search", () => runLexicalFallback({
-                root,
-                query,
-                limit,
-                includePaths: options.includePaths,
-                excludePaths: options.excludePaths,
-                modifiedAfter: options.modifiedAfter,
-                modifiedBefore: options.modifiedBefore,
-                rgOptions: options.rgOptions,
-            })));
-        }
-        const items = dedupeAndRerankContextItems(fallbackResults.flatMap((fallback) => fallback.items));
-        const diagnostics = mergeFallbackDiagnostics(fallbackResults);
-        return {
-            query: request.displayQuery,
-            root,
-            source: "lexical_fallback",
-            coverage: diagnostics.truncated ? "lexical_truncated" : "lexical_exhaustive",
-            items,
-            diagnostics: {
-                emptyReason: items.length === 0 ? "no_matches" : undefined,
-                fallback: diagnostics,
-            },
-        };
-    }
     async contextFromRg(root, request, options, timings) {
         let rgResult;
         try {
             rgResult = await timings.time("rg_search", () => runRgSearch({
                 root,
-                patterns: request.fallbackQueries,
+                patterns: request.rgPatterns,
                 paths: options.rgPaths,
                 limit: options.limit,
                 includePaths: options.includePaths,
                 excludePaths: options.excludePaths,
+                globs: options.globs,
+                insensitiveGlobs: options.insensitiveGlobs,
+                fileTypes: options.fileTypes,
+                excludedFileTypes: options.excludedFileTypes,
+                hidden: options.hidden,
+                noIgnore: options.noIgnore,
+                ignoreFiles: options.ignoreFiles,
+                maxDepth: options.maxDepth,
+                maxFileSizeBytes: options.maxFileSizeBytes,
+                follow: options.follow,
                 modifiedAfter: options.modifiedAfter,
                 modifiedBefore: options.modifiedBefore,
                 rgOptions: options.rgOptions,
@@ -442,27 +475,24 @@ class ZvecGrepService {
         catch (cause) {
             throw new EngineError("Search failed", {
                 code: "ZVEC_GREP.ENGINE.SEARCH.FAILED",
-                context: errorDetails([
-                    detail("source", "rg"),
-                    detail("root", root),
-                ]),
+                context: errorDetails([detail("source", "rg"), detail("root", root)]),
                 cause,
             });
         }
         const structuralEnrichment = await timings.time("structure_enrichment", () => enrichLexicalItemsWithStructure(root, rgResult.items));
         const items = dedupeAndRerankContextItems(structuralEnrichment.items);
-        const emptyReason = items.length === 0
-            ? rgEmptyReason(rgResult.diagnostics)
-            : undefined;
+        const emptyReason = items.length === 0 ? rgEmptyReason(rgResult.diagnostics) : undefined;
         return {
             query: request.displayQuery,
             root,
             source: "rg",
-            coverage: rgResult.diagnostics.truncated ? "lexical_truncated" : "lexical_exhaustive",
+            coverage: rgResult.diagnostics.truncated
+                ? "rg_truncated"
+                : "rg_exhaustive",
             items,
             diagnostics: {
                 emptyReason,
-                fallback: rgResult.diagnostics,
+                rg: rgResult.diagnostics,
                 structure: structuralEnrichment.diagnostics,
             },
         };
@@ -483,31 +513,96 @@ class ZvecGrepService {
         return this.recoverEmbeddingModel(schema, registryHome);
     }
     embeddingModelForIndex(existing, registryHome, operation) {
-        if (isCollectionIndexed(existing) && !this.embeddingModelExplicit) {
+        if (isCollectionIndexed(existing) &&
+            !this.embeddingModel &&
+            !this.options.embedding) {
             return this.recoverEmbeddingModel(existing.embedding, registryHome);
         }
-        return this.requireEmbeddingModel(operation);
+        const reference = this.options.embedding ??
+            (this.options.defaultEmbedding === true
+                ? DEFAULT_LOCAL_EMBEDDING
+                : undefined);
+        return (this.embeddingModel ??
+            (reference
+                ? this.embeddingModelFromReference(reference, registryHome)
+                : undefined) ??
+            this.configuredEmbeddingModel(registryHome) ??
+            this.requireEmbeddingModel(operation));
     }
     recoverEmbeddingModel(schema, registryHome) {
-        const key = `${schema.provider}/${schema.model}/${modelCacheDir(this.options, this.root, registryHome)}`;
+        const config = readGlobalConfig();
+        const options = providerOptions(this.options, this.root, registryHome, schema.provider, config);
+        const key = `${schema.provider}/${schema.model}/${providerOptionsFingerprint(options)}`;
+        return this.cachedEmbeddingModel(key, () => createEmbeddingModel({
+            provider: schema.provider,
+            model: schema.model,
+        }, options));
+    }
+    configuredEmbeddingModel(registryHome) {
+        const config = readGlobalConfig();
+        const reference = config.defaults?.embedding;
+        if (!reference) {
+            return undefined;
+        }
+        return this.embeddingModelFromReference(reference, registryHome, config);
+    }
+    embeddingModelFromReference(reference, registryHome, config = readGlobalConfig()) {
+        const provider = providerFromReference(reference);
+        const options = providerOptions(this.options, this.root, registryHome, provider, config);
+        const key = `configured/${reference}/${providerOptionsFingerprint(options)}`;
+        return this.cachedEmbeddingModel(key, () => createEmbeddingModelFromReference(reference, options));
+    }
+    cachedEmbeddingModel(key, create) {
         const cached = this.recoveredEmbeddingModels.get(key);
         if (cached) {
+            this.recoveredEmbeddingModels.delete(key);
+            this.recoveredEmbeddingModels.set(key, cached);
             return cached;
         }
-        const model = createEmbeddingModel({
-            provider: schema.provider,
-            model: schema.model,
-        }, providerOptions(this.options, this.root, registryHome));
+        const model = create();
         this.recoveredEmbeddingModels.set(key, model);
+        this.trimRecoveredEmbeddingModels();
         return model;
     }
+    trimRecoveredEmbeddingModels() {
+        while (this.recoveredEmbeddingModels.size > MAX_RECOVERED_EMBEDDING_MODELS) {
+            const oldestKey = this.recoveredEmbeddingModels.keys().next().value;
+            if (oldestKey === undefined) {
+                return;
+            }
+            const model = this.recoveredEmbeddingModels.get(oldestKey);
+            this.recoveredEmbeddingModels.delete(oldestKey);
+            if (model) {
+                this.retiredEmbeddingModels.add(model);
+            }
+        }
+    }
+    async withEmbeddingModelOperation(operation) {
+        this.activeEmbeddingModelOperations += 1;
+        try {
+            return await operation();
+        }
+        finally {
+            this.activeEmbeddingModelOperations -= 1;
+            if (this.activeEmbeddingModelOperations === 0) {
+                await this.disposeRetiredEmbeddingModels();
+            }
+        }
+    }
+    async disposeRetiredEmbeddingModels() {
+        const models = [...this.retiredEmbeddingModels];
+        this.retiredEmbeddingModels.clear();
+        for (const model of models) {
+            await model.dispose();
+        }
+    }
     requireEmbeddingModel(operation) {
         if (!this.embeddingModel) {
             throw new EngineError("zvec-grep operation requires an embedding model", {
                 code: "ZVEC_GREP.ENGINE.SERVICE.EMBEDDING_MODEL_REQUIRED",
                 context: errorDetails([
                     detail("operation", operation),
-                    detail("hint", 'Pass "--embedding <model>" or set ZVEC_GREP_EMBEDDING. Existing indexes can rerun --index without --embedding to reuse the stored schema.'),
+                    detail("hint", `Pass "--embedding <model>", set ZVEC_GREP_EMBEDDING, or configure defaults.embedding in ${globalConfigPath()}. Existing indexes can run "zg index" without --embedding to reuse the stored schema.`),
                     detail("examples", "local/embeddinggemma-300m, qwen/text-embedding-v4"),
                 ]),
             });
@@ -551,11 +646,11 @@ async function collectionNeedsRefresh(home, collectionName) {
     }
 }
 function collectionIndexStatusNeedsRefresh(status) {
-    return status.filesAdded > 0
-        || status.filesModified > 0
-        || status.filesDeleted > 0
-        || status.filesPending > 0
-        || status.filesFailed > 0;
+    return (status.filesAdded > 0 ||
+        status.filesModified > 0 ||
+        status.filesDeleted > 0 ||
+        status.filesPending > 0 ||
+        status.filesFailed > 0);
 }
 function acquireHomeLock(home, mode, operation) {
     return acquireReadWriteLock(homeLockPath(home), mode, { operation });
@@ -581,9 +676,10 @@ function serviceHome(options) {
     return options.home ?? defaultHome();
 }
 function rgEmptyReason(diagnostics) {
-    return diagnostics.missingPaths && diagnostics.missingPaths.length > 0
-        && diagnostics.searchedPaths
-        && diagnostics.searchedPaths.length === 0
+    return diagnostics.missingPaths &&
+        diagnostics.missingPaths.length > 0 &&
+        diagnostics.searchedPaths &&
+        diagnostics.searchedPaths.length === 0
         ? "no_searchable_files"
         : "no_matches";
 }
@@ -617,13 +713,13 @@ function findNearestAnonymousCollection(start) {
 }
 function anonymousInfoSuggestion(collection) {
     if (!collection) {
-        return "zg --index or zg --rg";
+        return "zg index or zg query --rg";
     }
     if (collection.indexPolicy === "disabled") {
-        return "zg --rg";
+        return "zg query --rg";
     }
     if (!isCollectionIndexed(collection)) {
-        return "zg --index";
+        return "zg index";
     }
     return undefined;
 }
@@ -634,11 +730,11 @@ function anonymousIndexMissingError(root, policy) {
             detail("root", root),
             detail("policy", policy),
             detail("hint", policy === "undecided"
-                ? "Ask the user whether to build an index with zg --index, or use zg --rg for no-index search."
-                : "Run zg --index to build the enabled workspace index, or use zg --rg for no-index search."),
+                ? "Ask the user whether to build an index with zg index, or use zg query --rg for no-index search."
+                : "Run zg index to build the enabled workspace index, or use zg query --rg for no-index search."),
             detail("agent_prompt", policy === "undecided"
-                ? "Ask the user whether this workspace should be indexed. If yes, run zg --index --embedding <model> with appropriate include/exclude filters; if no, run zg --disable-index. For immediate no-index search, use zg --rg."
-                : "This workspace is marked index-enabled but has no built index. Ask before running zg --index if an embedding model or cost is involved; otherwise use zg --rg for immediate no-index search."),
+                ? "Ask the user whether this workspace should be indexed. If yes, run zg index --embedding <model> with appropriate -g/--glob and -t/--type filters; otherwise use zg query --rg for immediate no-index search."
+                : "This workspace is marked index-enabled but has no built index. Ask before running zg index if an embedding model or cost is involved; otherwise use zg query --rg for immediate no-index search."),
         ]),
     });
 }
@@ -648,23 +744,66 @@ function anonymousIndexDisabledError(root) {
         context: errorDetails([
             detail("root", root),
             detail("policy", "disabled"),
-            detail("hint", "Use zg --rg for no-index search. Run zg --index only if the user explicitly decides to index this workspace."),
+            detail("hint", "Use zg query --rg for no-index search. Run zg index only if the user explicitly decides to index this workspace."),
             detail("agent_action", "do_not_build_index"),
         ]),
     });
 }
 function resolveIndexRootPaths(existing, requested, fallbackRoot, options) {
     let rootPaths = requested
-        ?? existing?.rootPaths
-        ?? [fallbackRoot];
+        ? inheritRequestedRootPathSettings(requested, existing?.rootPaths)
+        : (existing?.rootPaths ?? [fallbackRoot]);
     if (options.resetPaths) {
         rootPaths = rootPaths.map(resetRootPathFilters);
     }
-    if (options.includePaths !== undefined || options.excludePaths !== undefined) {
-        rootPaths = rootPaths.map((rootPath) => applyRootPathFilterOverrides(rootPath, options.includePaths, options.excludePaths));
+    if (options.includePaths !== undefined ||
+        options.excludePaths !== undefined ||
+        options.globs !== undefined ||
+        options.insensitiveGlobs !== undefined ||
+        options.fileTypes !== undefined ||
+        options.excludedFileTypes !== undefined ||
+        options.hidden !== undefined ||
+        options.noIgnore !== undefined ||
+        options.ignoreFiles !== undefined ||
+        options.maxDepth !== undefined ||
+        options.maxFileSizeBytes !== undefined ||
+        options.follow !== undefined) {
+        rootPaths = rootPaths.map((rootPath) => applyRootPathOverrides(rootPath, options));
     }
     return rootPaths;
 }
+function inheritRequestedRootPathSettings(requested, existing) {
+    if (!existing?.length) {
+        return requested;
+    }
+    return requested.map((rootPath) => {
+        const absolutePath = normalizePath(typeof rootPath === "string" ? rootPath : rootPath.absolutePath);
+        const inherited = existing.find((candidate) => normalizePath(candidate.absolutePath) === absolutePath);
+        if (!inherited) {
+            return rootPath;
+        }
+        if (typeof rootPath === "string") {
+            return { ...inherited, absolutePath };
+        }
+        return {
+            ...inherited,
+            ...rootPath,
+            absolutePath,
+            include: rootPath.include ?? inherited.include,
+            exclude: rootPath.exclude ?? inherited.exclude,
+            globs: rootPath.globs ?? inherited.globs,
+            insensitiveGlobs: rootPath.insensitiveGlobs ?? inherited.insensitiveGlobs,
+            fileTypes: rootPath.fileTypes ?? inherited.fileTypes,
+            excludedFileTypes: rootPath.excludedFileTypes ?? inherited.excludedFileTypes,
+            hidden: rootPath.hidden ?? inherited.hidden,
+            noIgnore: rootPath.noIgnore ?? inherited.noIgnore,
+            ignoreFiles: rootPath.ignoreFiles ?? inherited.ignoreFiles,
+            maxDepth: rootPath.maxDepth ?? inherited.maxDepth,
+            maxFileSizeBytes: rootPath.maxFileSizeBytes ?? inherited.maxFileSizeBytes,
+            follow: rootPath.follow ?? inherited.follow,
+        };
+    });
+}
 function resetRootPathFilters(rootPath) {
     if (typeof rootPath === "string") {
         return rootPath;
@@ -674,7 +813,7 @@ function resetRootPathFilters(rootPath) {
         recursive: rootPath.recursive,
     };
 }
-function applyRootPathFilterOverrides(rootPath, include, exclude) {
+function applyRootPathOverrides(rootPath, options) {
     const normalized = typeof rootPath === "string"
         ? {
             absolutePath: rootPath,
@@ -683,26 +822,20 @@ function applyRootPathFilterOverrides(rootPath, include, exclude) {
         : rootPath;
     return {
         ...normalized,
-        include: include ?? normalized.include,
-        exclude: exclude ?? normalized.exclude,
+        include: options.includePaths ?? normalized.include,
+        exclude: options.excludePaths ?? normalized.exclude,
+        globs: options.globs ?? normalized.globs,
+        insensitiveGlobs: options.insensitiveGlobs ?? normalized.insensitiveGlobs,
+        fileTypes: options.fileTypes ?? normalized.fileTypes,
+        excludedFileTypes: options.excludedFileTypes ?? normalized.excludedFileTypes,
+        hidden: options.hidden ?? normalized.hidden,
+        noIgnore: options.noIgnore ?? normalized.noIgnore,
+        ignoreFiles: options.ignoreFiles ?? normalized.ignoreFiles,
+        maxDepth: options.maxDepth ?? normalized.maxDepth,
+        maxFileSizeBytes: options.maxFileSizeBytes ?? normalized.maxFileSizeBytes,
+        follow: options.follow ?? normalized.follow,
     };
 }
-function resolveEmbeddingModel(options, root) {
-    if (options.embeddingModel) {
-        return options.embeddingModel;
-    }
-    if (options.embedding) {
-        return createEmbeddingModelFromReference(options.embedding, providerOptions(options, root));
-    }
-    if (options.defaultEmbedding === true) {
-        return createEmbeddingModelFromReference(DEFAULT_LOCAL_EMBEDDING, providerOptions(options, root));
-    }
-    return undefined;
-}
-function hasExplicitEmbeddingModel(options) {
-    return options.embeddingModel !== undefined
-        || options.embedding !== undefined;
-}
 function readCollectionInfo(home, name) {
     const registry = new CollectionRegistry(home, undefined, true);
     try {
@@ -720,28 +853,47 @@ function indexedEmbeddingSchema(info) {
         code: "ZVEC_GREP.ENGINE.SERVICE.INDEX_MISSING",
         context: errorDetails([
             collectionDetail(info.name),
-            detail("hint", "Run zg --index to build this index."),
+            detail("hint", "Run zg index to build this index."),
         ]),
     });
 }
-function providerOptions(options, root, registryHome) {
+function providerOptions(options, root, registryHome, provider, config = readGlobalConfig()) {
+    const providerConfig = provider ? config.providers?.[provider] : undefined;
     return {
-        apiKey: options.apiKey ?? "",
-        endpoint: options.endpoint,
-        modelCacheDir: modelCacheDir(options, root, registryHome),
-        llamaGpu: options.llamaGpu,
-        embeddingParallelism: options.embeddingParallelism,
+        apiKey: options.apiKey ?? providerConfig?.apiKey ?? "",
+        endpoint: options.endpoint ?? providerConfig?.endpoint,
+        modelCacheDir: options.modelCacheDir ??
+            process.env.ZVEC_GREP_MODEL_CACHE ??
+            config.defaults?.modelCacheDir ??
+            modelCacheDir(options, root, registryHome),
+        llamaGpu: options.llamaGpu ?? config.defaults?.llamaGpu,
+        embeddingParallelism: options.embeddingParallelism ?? config.defaults?.embeddingParallelism,
     };
 }
+function providerFromReference(reference) {
+    const separator = reference.indexOf("/");
+    return separator > 0 ? reference.slice(0, separator) : undefined;
+}
+function providerOptionsFingerprint(options) {
+    return createHash("sha256")
+        .update(JSON.stringify([
+        options.apiKey,
+        options.endpoint,
+        options.modelCacheDir,
+        options.llamaGpu,
+        options.embeddingParallelism,
+    ]))
+        .digest("hex");
+}
 function assertCollectionEmbeddingMatchesCurrentModel(info, model, rebuildCommand) {
     if (!isCollectionIndexed(info)) {
         return;
     }
     const expected = info.embedding;
-    const changed = expected.provider !== model.ref.provider
-        || expected.model !== model.ref.model
-        || expected.dimension !== model.dimension
-        || expected.metric !== model.metric;
+    const changed = expected.provider !== model.ref.provider ||
+        expected.model !== model.ref.model ||
+        expected.dimension !== model.dimension ||
+        expected.metric !== model.metric;
     if (!changed) {
         return;
     }
@@ -808,29 +960,36 @@ function contextGroupLimit(limit, groupCount) {
 function normalizeContextRequest(options) {
     const primaryQueries = normalizePrimaryQueries(options.query, options.queries);
     const extraRoutes = normalizeContextRoutes(options.routes ?? []);
-    if (primaryQueries.length === 0 && extraRoutes.length === 0) {
+    const hasPatternFiles = options.rg === true && (options.rgOptions?.patternFiles?.length ?? 0) > 0;
+    if (primaryQueries.length === 0 &&
+        extraRoutes.length === 0 &&
+        !hasPatternFiles) {
         throw new EngineError("zvec-grep context requires a non-empty query or route", {
             code: "ZVEC_GREP.ENGINE.SERVICE.EMPTY_QUERY",
         });
     }
     const groups = contextGroups(primaryQueries, extraRoutes);
     const routes = groups.flatMap((group) => group.routes);
-    const fallbackQueries = groups.map((group) => group.fallbackQuery);
+    const rgPatterns = [
+        ...primaryQueries,
+        ...extraRoutes.map((route) => route.query),
+    ];
     const displayQuery = primaryQueries.length > 0
         ? primaryQueries.join(" | ")
-        : extraRoutes.map((route) => route.query).join(" | ");
+        : extraRoutes.length > 0
+            ? extraRoutes.map((route) => route.query).join(" | ")
+            : options
+                .rgOptions.patternFiles.map((path) => `@${path}`)
+                .join(" | ");
     return {
         displayQuery,
-        fallbackQueries,
+        rgPatterns,
         routes,
         groups,
     };
 }
 function normalizePrimaryQueries(query, queries) {
-    return [
-        query,
-        ...(queries ?? []),
-    ].flatMap((value) => {
+    return [query, ...(queries ?? [])].flatMap((value) => {
         const normalized = normalizeOptionalQuery(value);
         return normalized ? [normalized] : [];
     });
@@ -867,11 +1026,9 @@ function contextGroups(primaryQueries, extraRoutes) {
                 { mode: "fts", query },
                 { mode: "vector", query },
             ],
-            fallbackQuery: query,
         })),
         ...extraRoutes.map((route) => ({
             routes: [route],
-            fallbackQuery: route.query,
         })),
     ];
 }
@@ -920,23 +1077,7 @@ function contextItemDedupeKey(item) {
     if (item.entityId) {
         return `entity:${item.entityId}`;
     }
-    return [
-        "range",
-        item.file.absolutePath,
-        JSON.stringify(item.range),
-    ].join(":");
-}
-function mergeFallbackDiagnostics(results) {
-    const [first] = results;
-    if (!first) {
-        throw new EngineError("zvec-grep lexical fallback requires at least one query", {
-            code: "ZVEC_GREP.ENGINE.SERVICE.EMPTY_QUERY",
-        });
-    }
-    return {
-        ...first.diagnostics,
-        truncated: results.some((result) => result.diagnostics.truncated),
-    };
+    return ["range", item.file.absolutePath, JSON.stringify(item.range)].join(":");
 }
 function contextItemTarget(hit) {
     const evidence = hit.evidence.find((item) => !item.isEntity);
@@ -979,7 +1120,8 @@ function contextItemOutline(hit, evidence) {
     if (!isUsefulOutline(hit.entity.metadata, outline)) {
         return undefined;
     }
-    if (evidence?.content.kind === "text" && evidence.content.text.trim() === outline) {
+    if (evidence?.content.kind === "text" &&
+        evidence.content.text.trim() === outline) {
         return undefined;
     }
     return outline;
@@ -988,23 +1130,23 @@ function isUsefulOutline(metadata, outline) {
     if (!metadata || metadata.kind !== "code") {
         return false;
     }
-    return metadata.symbolType === "class"
-        || metadata.symbolType === "interface"
-        || metadata.symbolType === "module"
-        || outline.includes("\ncalls:");
+    return (metadata.symbolType === "class" ||
+        metadata.symbolType === "interface" ||
+        metadata.symbolType === "module" ||
+        outline.includes("\ncalls:"));
 }
 function sameDisplayedContent(entity, evidence) {
-    return JSON.stringify(entity.range) === JSON.stringify(evidence.range)
-        && contentEquals(entity.content, evidence.content);
+    return (JSON.stringify(entity.range) === JSON.stringify(evidence.range) &&
+        contentEquals(entity.content, evidence.content));
 }
 function contentEquals(left, right) {
     if (left.kind !== right.kind) {
         return false;
     }
     if (left.kind === "image") {
-        return right.kind === "image"
-            && left.format === right.format
-            && left.data.byteLength === right.data.byteLength;
+        return (right.kind === "image" &&
+            left.format === right.format &&
+            left.data.byteLength === right.data.byteLength);
     }
     return right.kind === "text" && left.text === right.text;
 }
@@ -1020,7 +1162,8 @@ function fileFreshnessStatus(file) {
         if (file.indexStatus.indexedTime >= info.mtimeMs) {
             return "fresh";
         }
-        if (file.contentHash && sha256File(file.absolutePath) === file.contentHash) {
+        if (file.contentHash &&
+            sha256File(file.absolutePath) === file.contentHash) {
             return "fresh";
         }
     }