opencode-rag-plugin 1.22.1 → 1.23.0

package/dist/indexer/pipeline.js

@@ -7,7 +7,7 @@ import pLimit from "p-limit";
 import { scanWorkspaceFiles } from "../content/reader.js";
 import { loadManifest, saveManifest, normalizeFilePath, computeDescriptionConfigHash } from "../core/manifest.js";
 import { DescriptionCache } from "../core/desc-cache.js";
-import { embedBatch } from "../embedder/factory.js";
+import { embedBatch, probeEmbeddingDimension } from "../embedder/factory.js";
 import { createVectorStore } from "../vectorstore/factory.js";
 import { swapStoreDirectories } from "../vectorstore/lancedb.js";
 import { createIndexStats } from "./stats.js";
@@ -157,46 +157,12 @@ async function runIndexPassInner(options, logger) {
     // file content IS different — these would be caught by hash comparison below but
     // this pre-clear ensures the description cache is consulted during re-description.
     // (Files with same hash but different descHash already fall through in prepareFile.)
-    let filterPaths;
-    let gitDeletedPaths = [];
-    if (!options.force && manifestStatus === "ok" && manifest.lastGitCommit) {
-        const repoRoot = getRepoRoot(options.cwd);
-        if (repoRoot) {
-            const diffResult = getChangedFilesSince(options.cwd, manifest.lastGitCommit);
-            if (diffResult) {
-                const untracked = getUntrackedFiles(options.cwd);
-                const changedSet = new Set();
-                for (const f of diffResult.changedFiles)
-                    changedSet.add(f);
-                for (const f of untracked)
-                    changedSet.add(f);
-                // Git paths are relative to the REPO ROOT. When the workspace is a
-                // subdirectory of the repo (monorepos), convert them to workspace-
-                // relative paths before passing them to the scan — resolving repo-root
-                // paths against `cwd` would silently miss every change.
-                const toCwdRelative = (p) => {
-                    const abs = path.resolve(repoRoot, p);
-                    const rel = path.relative(options.cwd, abs);
-                    if (rel.startsWith("..") || path.isAbsolute(rel))
-                        return null;
-                    return rel;
-                };
-                const cwdRelative = [];
-                for (const p of changedSet) {
-                    const rel = toCwdRelative(p);
-                    if (rel !== null)
-                        cwdRelative.push(rel);
-                }
-                filterPaths = cwdRelative;
-                gitDeletedPaths = diffResult.deletedFiles;
-                logger.debug(`Git incremental: ${filterPaths.length} changed/untracked, ${gitDeletedPaths.length} deleted since ${manifest.lastGitCommit.slice(0, 8)}`);
-            }
-        }
-    }
-    const scanStart = Date.now();
-    const workspaceFiles = await scanWorkspaceFiles(options.cwd, options.config, logger, options.force ? undefined : manifest, filterPaths, options.imageVisionProvider, descCache);
-    const scanSec = ((Date.now() - scanStart) / 1000).toFixed(1);
-    logger.info(`Workspace scan complete: ${workspaceFiles.length} files in ${scanSec}s`);
+    // ── Store health checks (run BEFORE the scan) ──────────────────────────
+    // The checks below can invalidate the manifest and trigger a full rebuild.
+    // They must run before scanWorkspaceFiles: the reader skips reading the
+    // contents of unchanged files when a manifest entry matches (mtime + size +
+    // descHash unchanged), so clearing the manifest after the scan would leave
+    // those files with empty content and turn them into bogus "removed" entries.
     logger.info(`Querying vector store for existing chunk count...`);
     const storeCountStart = Date.now();
     const existingCount = await options.store.count();
@@ -236,15 +202,44 @@ async function runIndexPassInner(options, logger) {
             manifestStatus = "missing";
         }
     }
+    // ── Detect a store built by a different embedding model ────────────────
+    // LanceDB silently zero-pads/truncates mismatched vectors on write, and
+    // every vector query then fails with "No vector column found to match with
+    // the query vector dimension". Treat a schema dimension mismatch like a
+    // corrupt store: clear the manifest so this pass rebuilds everything into a
+    // fresh store at the configured dimension.
+    let dimensionMismatch = false;
+    try {
+        const storeDimension = await options.store.getVectorDimension?.();
+        if (!options.force &&
+            storeDimension !== undefined &&
+            options.dimension !== undefined &&
+            storeDimension !== options.dimension) {
+            dimensionMismatch = true;
+            logger.warn(`Store was built with vector dimension ${storeDimension} but the configured embedding model produces ` +
+                `${options.dimension} — rebuilding the full index with the current model.`);
+            if (manifestStatus === "ok") {
+                for (const key of Object.keys(manifest.files))
+                    delete manifest.files[key];
+                manifest.lastIndexedAt = undefined;
+                manifestStatus = "missing";
+            }
+        }
+    }
+    catch {
+        // getVectorDimension is best-effort — proceed without the drift check.
+    }
     // Effective store used throughout the pass — may be a temp store for atomic rebuild.
     let effectiveStore = options.store;
     let tempStorePath;
-    if (options.force || (manifestStatus !== "ok" && existingCount > 0)) {
+    /** Set when the temporary rebuild store actually received rows. */
+    let tempStoreWroteChunks = false;
+    if (options.force || (manifestStatus !== "ok" && (existingCount > 0 || dimensionMismatch))) {
         for (const key of Object.keys(manifest.files)) {
             delete manifest.files[key];
         }
         manifest.lastIndexedAt = undefined;
-        rebuildPerformed = existingCount > 0 || !!options.force;
+        rebuildPerformed = existingCount > 0 || !!options.force || dimensionMismatch;
         if (manifestStatus !== "ok" && existingCount > 0) {
             logger.warn("Manifest missing or corrupt; rebuilding full index.");
         }
@@ -271,7 +266,7 @@ async function runIndexPassInner(options, logger) {
             logger.warn("Cannot rebuild safely without embedding dimension — aborting to protect existing data. " +
                 "Run 'opencode-rag index --force' manually to rebuild.");
             // Restore manifest entries we just deleted so the next pass can retry incrementally
-            return createIndexStats(workspaceFiles.length, manifestStatus);
+            return createIndexStats(0, manifestStatus);
         }
         else {
             // No existing data — safe to proceed with in-place indexing (no clear needed)
@@ -279,8 +274,76 @@ async function runIndexPassInner(options, logger) {
             logger.debug("No existing data; indexing from scratch.");
         }
     }
+    let filterPaths;
+    let gitDeletedPaths = [];
+    if (!options.force && manifestStatus === "ok" && manifest.lastGitCommit) {
+        const repoRoot = getRepoRoot(options.cwd);
+        if (repoRoot) {
+            const diffResult = getChangedFilesSince(options.cwd, manifest.lastGitCommit);
+            if (diffResult) {
+                const untracked = getUntrackedFiles(options.cwd);
+                const changedSet = new Set();
+                for (const f of diffResult.changedFiles)
+                    changedSet.add(f);
+                for (const f of untracked)
+                    changedSet.add(f);
+                // Git paths are relative to the REPO ROOT. When the workspace is a
+                // subdirectory of the repo (monorepos), convert them to workspace-
+                // relative paths before passing them to the scan — resolving repo-root
+                // paths against `cwd` would silently miss every change.
+                const toCwdRelative = (p) => {
+                    const abs = path.resolve(repoRoot, p);
+                    const rel = path.relative(options.cwd, abs);
+                    if (rel.startsWith("..") || path.isAbsolute(rel))
+                        return null;
+                    return rel;
+                };
+                const cwdRelative = [];
+                for (const p of changedSet) {
+                    const rel = toCwdRelative(p);
+                    if (rel !== null)
+                        cwdRelative.push(rel);
+                }
+                filterPaths = cwdRelative;
+                gitDeletedPaths = diffResult.deletedFiles;
+                logger.debug(`Git incremental: ${filterPaths.length} changed/untracked, ${gitDeletedPaths.length} deleted since ${manifest.lastGitCommit.slice(0, 8)}`);
+            }
+        }
+    }
+    const scanStart = Date.now();
+    const workspaceFiles = await scanWorkspaceFiles(options.cwd, options.config, logger, options.force ? undefined : manifest, filterPaths, options.imageVisionProvider, descCache);
+    const scanSec = ((Date.now() - scanStart) / 1000).toFixed(1);
+    logger.info(`Workspace scan complete: ${workspaceFiles.length} files in ${scanSec}s`);
+    // ── Preflight: verify the embedding provider before expensive work ─────
+    // A provider outage used to burn the entire pass (chunking + describing
+    // every file) and then store nothing, reporting success. Probe once here
+    // so the pass aborts in milliseconds with an actionable message.
+    const pendingEmbeddingWork = options.force || workspaceFiles.some((f) => {
+        if (f.isEmpty || f.isTooSmall)
+            return false;
+        const previous = manifest.files[f.normalizedPath];
+        return !previous || previous.hash !== f.hash;
+    });
+    if (pendingEmbeddingWork && !(options.abortSignal?.aborted ?? false)) {
+        const probe = await probeEmbeddingDimension(options.embedder);
+        if (probe.dimension === undefined) {
+            logger.warn(`Embedding provider unavailable (${probe.error?.message ?? "probe failed"}) — ` +
+                "aborting index pass before chunking/description; nothing was stored.");
+            const failedStats = createIndexStats(workspaceFiles.length, manifestStatus);
+            failedStats.embeddingUnavailable = true;
+            return failedStats;
+        }
+        if (options.dimension !== undefined && probe.dimension !== options.dimension) {
+            logger.warn(`Embedding provider produces ${probe.dimension}-dimensional vectors but this index is configured for ` +
+                `${options.dimension} — aborting to avoid writing incompatible vectors. ` +
+                "Set embedding.vectorDimension to the provider's dimension and run the index again.");
+            const failedStats = createIndexStats(workspaceFiles.length, manifestStatus);
+            failedStats.embeddingUnavailable = true;
+            return failedStats;
+        }
+    }
     const stats = createIndexStats(workspaceFiles.length, manifestStatus);
-    stats.rebuildPerformed = rebuildPerformed;
+    stats.rebuildPerformed = rebuildPerformed || dimensionMismatch;
     for (const file of workspaceFiles) {
         if (file.extractionStatus === "failed" && file.extractionError) {
             stats.extractionFailures++;
@@ -416,6 +479,8 @@ async function runIndexPassInner(options, logger) {
             if (!allEmbedded && (prep.chunks?.length ?? 0) > 0) {
                 options.logger?.warn?.(`  ${prep.fileLabel}: ${validChunks.length}/${prep.chunks?.length} chunks embedded — marking for retry on next pass`);
             }
+            if (validChunks.length > 0)
+                tempStoreWroteChunks = true;
             storePayloads.push({ prep, validChunks, allEmbedded });
         }
         // One bulk write per window. Dedup (per-modified-file deletes) is skipped
@@ -738,7 +803,7 @@ async function runIndexPassInner(options, logger) {
                     }
                 }
                 for (const prep of deferredPreps) {
-                    prep.textToEmbed = buildTextsToEmbed(prep.chunks, prep.relPath, prep.metaHeader ?? "", prep.docPrefix ?? "", prep.isImageFile ?? false);
+                    prep.textToEmbed = buildTextsToEmbed(prep.chunks, prep.relPath, prep.metaHeader ?? "", prep.docPrefix ?? "", prep.isImageFile ?? false, options.config.indexing.embedDescriptions !== false);
                 }
                 const totalDescribedChunks = deferredPreps.reduce((s, p) => s + (p.chunks?.length ?? 0), 0);
                 logger.info(`Description phase complete: ${totalDescribedChunks} chunks across ${deferredPreps.length} files`);
@@ -801,6 +866,8 @@ async function runIndexPassInner(options, logger) {
             }
             catch (err) {
                 logger.warn(`  Global embedding failed: ${err.message}`);
+                stats.embeddingFailures += allTexts.length;
+                stats.embeddingUnavailable = true;
                 for (const { fileIdx } of embedQueue) {
                     options.progress?.failFile(prepared[fileIdx].fileLabel);
                     earlyWorkerResults.set(fileIdx, {
@@ -814,6 +881,21 @@ async function runIndexPassInner(options, logger) {
                 }
                 embedQueue.length = 0; // prevent double-processing in store phase
             }
+            // `embedBatch` returns empty vectors for batches whose retries were
+            // exhausted — count those so the summary and exit code report a failed
+            // pass instead of a successful "0 chunks stored".
+            const failedVectors = allEmbeddings.filter((v) => !Array.isArray(v) || v.length === 0).length;
+            if (failedVectors > 0) {
+                stats.embeddingFailures += failedVectors;
+                if (failedVectors >= allTexts.length) {
+                    stats.embeddingUnavailable = true;
+                    logger.warn(`All ${allTexts.length} embedding requests failed — no vectors were produced, so nothing was stored. ` +
+                        "Check that the embedding provider is running and the model is available, then run the index again.");
+                }
+                else {
+                    logger.warn(`  ${failedVectors}/${allTexts.length} embedding requests failed — those chunks are kept for retry on the next pass.`);
+                }
+            }
         }
         // ── Distribute embeddings back to per-file chunks ─────────────────────
         for (let i = 0; i < embedQueue.length; i++) {
@@ -875,25 +957,43 @@ async function runIndexPassInner(options, logger) {
         tryUpdateLastGitCommit(options.cwd, manifest);
     }
     // ── Atomically promote temp store if a full rebuild was performed ──
+    let tempStorePromoted = false;
     if (tempStorePath) {
         if (!aborted()) {
-            try {
-                await effectiveStore.close();
-                await options.store.close();
-                // Swap the newly-built temp directory into the real path
-                await swapStoreDirectories(tempStorePath, options.storePath);
-                // Re-open the original store handle so callers can search the new data
-                await options.store.reopen?.(options.storePath);
-                logger.debug(`Promoted temporary store ${tempStorePath} → ${options.storePath}`);
-            }
-            catch (err) {
-                logger.warn(`Could not promote temporary store: ${err.message}. ` +
-                    `Original data preserved at ${options.storePath}`);
+            if (!tempStoreWroteChunks) {
+                // Nothing was written (e.g. every embedding request failed). Keep the
+                // existing store and manifest untouched rather than promoting an
+                // empty store over good data.
+                logger.warn("Rebuild produced no chunks — keeping the existing index and manifest unchanged.");
+                try {
+                    await effectiveStore.close();
+                }
+                catch { }
                 try {
                     await fs.rm(tempStorePath, { recursive: true, force: true });
                 }
                 catch { }
             }
+            else {
+                try {
+                    await effectiveStore.close();
+                    await options.store.close();
+                    // Swap the newly-built temp directory into the real path
+                    await swapStoreDirectories(tempStorePath, options.storePath);
+                    // Re-open the original store handle so callers can search the new data
+                    await options.store.reopen?.(options.storePath);
+                    tempStorePromoted = true;
+                    logger.debug(`Promoted temporary store ${tempStorePath} → ${options.storePath}`);
+                }
+                catch (err) {
+                    logger.warn(`Could not promote temporary store: ${err.message}. ` +
+                        `Original data preserved at ${options.storePath}`);
+                    try {
+                        await fs.rm(tempStorePath, { recursive: true, force: true });
+                    }
+                    catch { }
+                }
+            }
         }
         else {
             // Aborted — discard temp, keep original data intact.
@@ -912,16 +1012,27 @@ async function runIndexPassInner(options, logger) {
             return stats;
         }
     }
-    // Save manifest and keyword index (always to the real store path — after
-    // a successful swap this points to the new data; after an abort it's the old).
-    await saveManifest(options.storePath, manifest);
-    await options.keywordIndex?.save(options.storePath);
+    // The in-memory manifest was cleared at rebuild start and only repopulated
+    // for the new store. When the rebuild did not promote (empty temp store or
+    // failed swap), keep the previous manifest/keyword index on disk — saving
+    // the cleared state would orphan the existing store's data.
+    const keepPreviousIndexState = tempStorePath !== undefined && !tempStorePromoted;
+    if (keepPreviousIndexState) {
+        logger.warn("Rebuild did not complete — keeping the previous manifest and keyword index.");
+    }
+    else {
+        // Save manifest and keyword index (always to the real store path — after
+        // a successful swap this points to the new data).
+        await saveManifest(options.storePath, manifest);
+        await options.keywordIndex?.save(options.storePath);
+    }
     // Compact fragments and prune old version manifests so countRows() can't
     // hang on accumulated versions from many add/delete cycles. After a temp
     // store rebuild, optimize the reopened real store handle (the temp handle
     // was closed and its directory moved); use aggressive pruning since the
-    // swapped-in store is private to this process.
-    if (!aborted()) {
+    // swapped-in store is private to this process. Skipped when the rebuild did
+    // not promote (the old store is untouched and its handle may be closed).
+    if (!aborted() && !keepPreviousIndexState) {
         logger.info("Optimizing vector store (compacting fragments, pruning old versions)...");
         const optimizeStart = Date.now();
         try {

package/dist/indexer/stats.d.ts

@@ -38,6 +38,10 @@ export interface IndexRunStats {
     }>;
     /** Number of files where description generation failed. */
     descriptionFailedFiles: number;
+    /** Number of chunks whose embedding request failed (kept for retry on the next pass). */
+    embeddingFailures: number;
+    /** True when the pass could not embed at all (provider unavailable or dimension mismatch) — nothing was stored. */
+    embeddingUnavailable: boolean;
     /** True when the pass was skipped because another pass holds the lock. */
     skipped: boolean;
 }

package/dist/indexer/stats.js

@@ -24,6 +24,8 @@ export function createIndexStats(totalFiles, manifestStatus) {
         extractionFailures: 0,
         extractionErrors: [],
         descriptionFailedFiles: 0,
+        embeddingFailures: 0,
+        embeddingUnavailable: false,
         skipped: false,
     };
 }

package/dist/indexer/worker.d.ts

@@ -61,16 +61,21 @@ export interface PreparedFile {
 /**
  * Build the list of text strings that will be sent to the embedding provider.
  * Each chunk is prefixed with the document prefix, relative path, metadata
- * header, and (if available) a description.
+ * header, and (if available and enabled) a description.
+ *
+ * Code-specialized embedding models do not need the description crutch: with
+ * `indexing.embedDescriptions: false` the prose description is omitted from
+ * the embedded text (it is still stored on the chunk for display).
  *
  * @param chunks     - Chunks to build embedding texts from.
  * @param relPath    - Relative file path used as context prefix.
  * @param metaHeader - Assembled metadata header (file type, directory, etc.).
  * @param docPrefix  - Optional document-level prefix from configuration.
  * @param isImage    - Whether the source is an image (uses description only).
+ * @param includeDescription - Whether to include non-image descriptions (default true).
  * @returns An array of formatted text strings, one per chunk.
  */
-export declare function buildTextsToEmbed(chunks: Chunk[], relPath: string, metaHeader: string, docPrefix: string, isImage: boolean): string[];
+export declare function buildTextsToEmbed(chunks: Chunk[], relPath: string, metaHeader: string, docPrefix: string, isImage: boolean, includeDescription?: boolean): string[];
 interface Logger {
     info(message: string): void;
     warn(message: string): void;
@@ -115,6 +120,7 @@ export declare function prepareFile(file: WorkspaceFile, cwd: string, previous:
     };
     indexing?: {
         maxSvgSizeBytes?: number;
+        embedDescriptions?: boolean;
     };
 }, keywordIndex: KeywordIndex | undefined, descriptionProvider: DescriptionProvider | undefined, logger: Logger, deferDescriptions?: boolean, descHash?: string): Promise<PreparedFile>;
 /**

package/dist/indexer/worker.js

@@ -10,23 +10,28 @@ import { generateDescriptions, buildFallbackDescription } from "./description-st
 /**
  * Build the list of text strings that will be sent to the embedding provider.
  * Each chunk is prefixed with the document prefix, relative path, metadata
- * header, and (if available) a description.
+ * header, and (if available and enabled) a description.
+ *
+ * Code-specialized embedding models do not need the description crutch: with
+ * `indexing.embedDescriptions: false` the prose description is omitted from
+ * the embedded text (it is still stored on the chunk for display).
  *
  * @param chunks     - Chunks to build embedding texts from.
  * @param relPath    - Relative file path used as context prefix.
  * @param metaHeader - Assembled metadata header (file type, directory, etc.).
  * @param docPrefix  - Optional document-level prefix from configuration.
  * @param isImage    - Whether the source is an image (uses description only).
+ * @param includeDescription - Whether to include non-image descriptions (default true).
  * @returns An array of formatted text strings, one per chunk.
  */
-export function buildTextsToEmbed(chunks, relPath, metaHeader, docPrefix, isImage) {
+export function buildTextsToEmbed(chunks, relPath, metaHeader, docPrefix, isImage, includeDescription = true) {
     const textToEmbed = [];
     for (const chunk of chunks) {
         if (isImage) {
             textToEmbed.push(docPrefix + relPath + "\n\n" + chunk.description);
         }
         else {
-            const desc = chunk.description ?? "";
+            const desc = includeDescription ? chunk.description ?? "" : "";
             if (desc.trim().length > 0) {
                 textToEmbed.push(docPrefix + relPath + "\n\n" + metaHeader + "\n\n" + desc + "\n\n" + chunk.content);
             }
@@ -210,7 +215,7 @@ export async function prepareFile(file, cwd, previous, config, keywordIndex, des
             }
         }
     }
-    const textToEmbed = buildTextsToEmbed(chunks, relPath, metaHeader, docPrefix, isImage);
+    const textToEmbed = buildTextsToEmbed(chunks, relPath, metaHeader, docPrefix, isImage, config.indexing?.embedDescriptions !== false);
     logger.debug(`  ${fileLabel}: textToEmbed ${textToEmbed.length} entries (descProvider: ${descriptionProvider ? "yes" : "no"})`);
     return {
         normalizedPath: file.normalizedPath,

package/dist/mcp/handlers.d.ts

@@ -97,7 +97,7 @@ export interface DescribeImageResult {
     /** Human-readable formatted output with metadata. */
     formatted: string;
 }
-/** Describe an image file using the configured vision provider (Ollama, OpenAI, Anthropic, or Gemini). */
+/** Describe an image file using the configured vision provider (Ollama, OpenAI, Anthropic, or Gemini). Honors `imageDescription.onDemand` overrides. */
 export declare function handleDescribeImage(params: DescribeImageParams, cfg: RagConfig, worktree: string, visionProvider?: ImageVisionProvider): Promise<DescribeImageResult>;
 /** Find usages and references of a symbol across the indexed codebase using hybrid (keyword + vector) search. */
 export declare function handleFindUsages(params: FindUsagesParams, embedder: EmbeddingProvider, store: VectorStore, cfg: RagConfig, keywordIndex?: KeywordIndex, retrieveFn?: typeof retrieve): Promise<FindUsagesResult>;

package/dist/mcp/handlers.js

@@ -227,7 +227,7 @@ export async function handleFileSkeleton(params, worktree) {
     const formatted = `${skeleton.length} structural elements (${summary || "—"})\n\n${formatSkeleton(skeleton)}`;
     return { elements: skeleton, formatted, summary };
 }
-/** Describe an image file using the configured vision provider (Ollama, OpenAI, Anthropic, or Gemini). */
+/** Describe an image file using the configured vision provider (Ollama, OpenAI, Anthropic, or Gemini). Honors `imageDescription.onDemand` overrides. */
 export async function handleDescribeImage(params, cfg, worktree, visionProvider) {
     const { existsSync, readFileSync } = await import("node:fs");
     const path = await import("node:path");
@@ -244,21 +244,22 @@ export async function handleDescribeImage(params, cfg, worktree, visionProvider)
     if (!imageDescriptionConfig?.enabled) {
         throw new Error("Image description is not enabled in config (imageDescription.enabled)");
     }
-    const { getMimeType } = await import("../chunker/image.js");
+    const { getMimeType, createImageVisionProvider, resolveOnDemandImageConfig } = await import("../chunker/image.js");
     const { resizeImage } = await import("../content/image.js");
+    const effectiveImageConfig = resolveOnDemandImageConfig(imageDescriptionConfig);
     const buffer = readFileSync(resolvedPath);
     const mimeType = getMimeType(ext);
-    const maxDimension = imageDescriptionConfig.resizeMaxDimension ?? 1024;
+    const maxDimension = effectiveImageConfig.resizeMaxDimension ?? 1024;
     const sized = maxDimension > 0 ? await resizeImage(buffer, resolvedPath, maxDimension) : buffer;
     const b64 = sized.toString("base64");
-    const provider = visionProvider ?? (await import("../chunker/image.js")).createImageVisionProvider(imageDescriptionConfig);
-    const description = await provider.describeImage(b64, mimeType, imageDescriptionConfig.prompt, params.systemPrompt);
+    const provider = visionProvider ?? createImageVisionProvider(effectiveImageConfig);
+    const description = await provider.describeImage(b64, mimeType, effectiveImageConfig.prompt, params.systemPrompt);
     const formatted = [
         `**Image description** — ${params.filePath}`,
         "",
         description,
         "",
-        `_Generated with ${imageDescriptionConfig.provider}/${imageDescriptionConfig.model}_`,
+        `_Generated with ${effectiveImageConfig.provider}/${effectiveImageConfig.model}_`,
     ].join("\n");
     return { description, formatted };
 }

package/dist/opencode/tools.d.ts

@@ -51,6 +51,9 @@ export interface DescribeImageToolOptions {
  * for natural-language description. Supports Ollama, OpenAI, Anthropic, and
  * Google Gemini providers with automatic resizing.
  *
+ * On-demand calls honor the optional `imageDescription.onDemand` overrides
+ * (a different provider/model than the indexing pipeline).
+ *
  * @param options - Tool configuration including workspace root and vision provider.
  * @returns A tool definition suitable for OpenCode plugin registration.
  */

package/dist/opencode/tools.js

@@ -14,7 +14,7 @@
  */
 import { tool } from "@opencode-ai/plugin/tool";
 import { CODE_SEARCH_FILTER } from "../core/interfaces.js";
-import { SUPPORTED_IMAGE_EXTENSIONS, createImageVisionProvider, getMimeType } from "../chunker/image.js";
+import { SUPPORTED_IMAGE_EXTENSIONS, createImageVisionProvider, resolveOnDemandImageConfig, getMimeType } from "../chunker/image.js";
 import { resizeImage } from "../content/image.js";
 import { retrieve } from "../retriever/retriever.js";
 import { Parser } from "web-tree-sitter";
@@ -247,6 +247,9 @@ export function createFileSkeletonTool(options) {
  * for natural-language description. Supports Ollama, OpenAI, Anthropic, and
  * Google Gemini providers with automatic resizing.
  *
+ * On-demand calls honor the optional `imageDescription.onDemand` overrides
+ * (a different provider/model than the indexing pipeline).
+ *
  * @param options - Tool configuration including workspace root and vision provider.
  * @returns A tool definition suitable for OpenCode plugin registration.
  */
@@ -292,22 +295,23 @@ export function createDescribeImageTool(options) {
                         metadata: { tool: "describe_image", filePath: args.filePath, error: "disabled" },
                     };
                 }
+                const effectiveImageConfig = resolveOnDemandImageConfig(imageDescriptionConfig);
                 const buffer = readFileSync(resolvedPath);
                 const mimeType = getMimeType(ext);
-                const maxDimension = imageDescriptionConfig.resizeMaxDimension ?? 1024;
+                const maxDimension = effectiveImageConfig.resizeMaxDimension ?? 1024;
                 const sized = maxDimension > 0 ? await resizeImage(buffer, resolvedPath, maxDimension) : buffer;
                 const b64 = sized.toString("base64");
-                const provider = visionProvider ?? createImageVisionProvider(imageDescriptionConfig);
-                const description = await provider.describeImage(b64, mimeType, imageDescriptionConfig.prompt, args.systemPrompt);
+                const provider = visionProvider ?? createImageVisionProvider(effectiveImageConfig);
+                const description = await provider.describeImage(b64, mimeType, effectiveImageConfig.prompt, args.systemPrompt);
                 return {
                     title: `Image description — ${args.filePath}`,
-                    output: `**${args.filePath}**\n\n${description}\n\n_Generated with ${imageDescriptionConfig.provider}/${imageDescriptionConfig.model}_`,
+                    output: `**${args.filePath}**\n\n${description}\n\n_Generated with ${effectiveImageConfig.provider}/${effectiveImageConfig.model}_`,
                     metadata: {
                         tool: "describe_image",
                         filePath: args.filePath,
                         description,
-                        provider: imageDescriptionConfig.provider,
-                        model: imageDescriptionConfig.model,
+                        provider: effectiveImageConfig.provider,
+                        model: effectiveImageConfig.model,
                     },
                 };
             }

package/dist/plugin.js

@@ -7,7 +7,8 @@ import { tool } from "@opencode-ai/plugin/tool";
 import { CODE_SEARCH_FILTER } from "./core/interfaces.js";
 import { normalizeFileExtensions } from "./core/filters.js";
 import { loadConfig, findConfigFile, DEFAULT_CONFIG, resolveLogConfig, persistProbedDimension } from "./core/config.js";
-import { createEmbedder } from "./embedder/factory.js";
+import { createEmbedder, probeEmbeddingDimension } from "./embedder/factory.js";
+import { readStoreDimension } from "./vectorstore/lancedb.js";
 import { createDescriptionProvider } from "./describer/factory.js";
 import { createVectorStore } from "./vectorstore/factory.js";
 import { retrieve } from "./retriever/retriever.js";
@@ -419,7 +420,8 @@ export function createRagHooks(options) {
         ...options.dependencies,
     };
     const embedder = options.embedder ?? dependencies.createEmbedder(options.cfg);
-    const store = options.store ?? dependencies.createStore(options.storePath, 384, options.cfg);
+    const configuredDimension = options.cfg.embedding.vectorDimension;
+    const store = options.store ?? dependencies.createStore(options.storePath, configuredDimension && configuredDimension > 0 ? configuredDimension : 384, options.cfg);
     const keywordIndex = options.keywordIndex;
     // Runtime overrides for live config editing from TUI
     let cachedOverrides = loadRuntimeOverrides(options.storePath);
@@ -1394,6 +1396,8 @@ export const ragPlugin = async (input, _options) => {
     }, logLevel);
     // Use cached dimension from config if available (avoids blocking startup with an API call)
     // If not set, probe the embedding provider once and persist the result.
+    // When the probe fails, prefer the existing store's schema over the 384
+    // default — a transient outage must not downgrade the store's dimension.
     const embedder = createEmbedder(effectiveCfg);
     let vectorDimension = effectiveCfg.embedding.vectorDimension;
     if (vectorDimension && vectorDimension > 0) {
@@ -1403,34 +1407,47 @@ export const ragPlugin = async (input, _options) => {
         }, logLevel);
     }
     else {
-        vectorDimension = 384;
-        try {
-            const probe = await embedder.embed(["dimension-probe"], "query");
-            if (probe && probe[0] && probe[0].length > 0 && typeof probe[0][0] === "number") {
-                vectorDimension = probe[0].length;
-                const configPath = findConfigFile(input.directory);
-                if (configPath) {
-                    try {
-                        persistProbedDimension(configPath, vectorDimension);
-                    }
-                    catch { /* best-effort */ }
+        const probe = await probeEmbeddingDimension(embedder);
+        if (probe.dimension !== undefined) {
+            vectorDimension = probe.dimension;
+            const configPath = findConfigFile(input.directory);
+            if (configPath) {
+                try {
+                    persistProbedDimension(configPath, vectorDimension);
                 }
+                catch { /* best-effort */ }
             }
             appendDebugLog(logFilePath, {
                 scope: "plugin",
                 message: `Vector dimension: ${vectorDimension}`,
             }, logLevel);
         }
-        catch (err) {
+        else {
+            vectorDimension = (await readStoreDimension(storePath)) ?? 384;
             appendDebugLog(logFilePath, {
                 scope: "plugin",
                 message: `Dimension probe failed, falling back to ${vectorDimension}`,
-                error: err,
+                error: probe.error,
             }, logLevel);
         }
     }
     const store = createVectorStore(effectiveCfg, storePath, vectorDimension);
     ragStores.set(input.directory, store);
+    // Warn when the store was built by a different embedding model — vector
+    // search fails (or silently degrades) until the index is rebuilt.
+    try {
+        const storeDimension = await store.getVectorDimension?.();
+        if (storeDimension !== undefined && storeDimension !== vectorDimension) {
+            appendDebugLog(logFilePath, {
+                scope: "plugin",
+                message: `Store vector dimension is ${storeDimension} but the configured embedder produces ${vectorDimension} — ` +
+                    "run 'opencode-rag index' to rebuild the index with the current model.",
+            }, logLevel);
+        }
+    }
+    catch {
+        // best-effort — dimension introspection must never block plugin startup
+    }
     // Load or create keyword index for hybrid search
     const keywordIndex = await loadKeywordIndex(storePath, logFilePath, logLevel);
     // Create description provider (enabled by default)