opencode-rag-plugin 1.22.1 → 1.22.2

package/dist/cli/commands/index-command.js

@@ -98,6 +98,7 @@ export function registerIndexCommand(program) {
                 }
             }
             logCliInfo(logFilePath, "index", `${c.label("Scanning:")} ${c.file(cwd)}`);
+            let incomplete = false;
             const runPass = async (watchTriggered = false, abortSignal, filterPaths) => {
                 const passStarted = Date.now();
                 const stats = await runIndexPass({
@@ -116,6 +117,14 @@ export function registerIndexCommand(program) {
                 });
                 if (!watchTriggered) {
                     logIndexSummary(logFilePath, stats);
+                    if (stats.embeddingUnavailable) {
+                        incomplete = true;
+                        logCliInfo(logFilePath, "index", `\n${c.error("Indexing incomplete:")} the embedding provider was unavailable — nothing was stored. Fix the provider and run the index again.`);
+                    }
+                    else if (stats.totalChunks === 0 && stats.newFiles + stats.modifiedFiles > 0) {
+                        incomplete = true;
+                        logCliInfo(logFilePath, "index", `\n${c.warn("Indexing incomplete:")} files were processed but no chunks were stored. Check the log for details.`);
+                    }
                     logCliInfo(logFilePath, "index", `\n${c.success("Indexing complete.")} ${c.num(stats.finalCount)} chunks stored (${formatDuration(Date.now() - passStarted)}).`);
                 }
                 if (sigReceived && !watchTriggered) {
@@ -128,7 +137,7 @@ export function registerIndexCommand(program) {
             process.removeListener("SIGTERM", handleSigint);
             if (!options.watch) {
                 await cleanupContext(ctx);
-                process.exit(sigReceived ? 130 : 0);
+                process.exit(sigReceived ? 130 : incomplete ? 1 : 0);
             }
             // Only one watcher may run per workspace — a background auto-indexer
             // in an OpenCode session (or another `index --watch`) may already own

package/dist/cli/commands/status.js

@@ -75,6 +75,20 @@ export function registerStatusCommand(program) {
             logCliInfo(logFilePath, "status", `${c.label("Store path:")}        ${c.file(storePath)}`);
             logCliInfo(logFilePath, "status", `${c.label("Embedding provider:")} ${c.value(config.embedding.provider)}`);
             logCliInfo(logFilePath, "status", `${c.label("Embedding model:")}   ${c.value(config.embedding.model)}`);
+            const storeDimension = await store.getVectorDimension?.();
+            const embedderDimension = config.embedding.vectorDimension;
+            if (embedderDimension && embedderDimension > 0) {
+                logCliInfo(logFilePath, "status", `${c.label("Embedder dim:")}      ${c.num(embedderDimension)}`);
+            }
+            if (storeDimension !== undefined) {
+                logCliInfo(logFilePath, "status", `${c.label("Store dimension:")}   ${c.num(storeDimension)}`);
+            }
+            if (storeDimension !== undefined &&
+                embedderDimension !== undefined &&
+                embedderDimension > 0 &&
+                storeDimension !== embedderDimension) {
+                logCliInfo(logFilePath, "status", `${c.label("Dimension mismatch:")} ${c.warn("yes")} — the store was built with a different embedding model. Run 'opencode-rag index' to rebuild.`);
+            }
             logCliInfo(logFilePath, "status", `${c.label("File extensions:")}   ${config.indexing.includeExtensions.join(", ")}`);
             logCliInfo(logFilePath, "status", `${c.label("Excluded dirs:")}     ${config.indexing.excludeDirs.join(", ")}`);
             logCliInfo(logFilePath, "status", `${c.label("Default top-K:")}     ${c.num(config.retrieval.topK)}`);

package/dist/cli/format.js

@@ -92,7 +92,7 @@ export async function resolveCliContext(opt, logFilePath, bootstrapOpts) {
         configPath: opt.config,
         ...bootstrapOpts,
     });
-    logCliInfo(logFilePath, "config", `${c.label("Config:")} ${c.file(ctx.logFilePath)}`);
+    logCliInfo(logFilePath, "config", `${c.label("Config:")} ${c.file(ctx.configPath ?? "(built-in defaults)")}`);
     logConfigDetails(logFilePath, ctx.config);
     return ctx;
 }
@@ -105,6 +105,9 @@ export async function resolveCliContext(opt, logFilePath, bootstrapOpts) {
 function logConfigDetails(logFilePath, config) {
     logCliInfo(logFilePath, "config", `  ${c.label("Embedding provider:")} ${c.value(config.embedding.provider)}`);
     logCliInfo(logFilePath, "config", `  ${c.label("Embedding model:")}    ${c.value(config.embedding.model)}`);
+    if (config.embedding.vectorDimension && config.embedding.vectorDimension > 0) {
+        logCliInfo(logFilePath, "config", `  ${c.label("Embedding dim:")}      ${c.num(config.embedding.vectorDimension)}`);
+    }
     logCliInfo(logFilePath, "config", `  ${c.label("Vector store:")}       ${c.file(config.vectorStore.path)}`);
 }
 /**
@@ -153,7 +156,13 @@ export function logIndexSummary(logFilePath, stats) {
     if (stats.descriptionFailedFiles > 0) {
         logCliInfo(logFilePath, "index", `  ${c.label("Desc failed:")}     ${c.num(stats.descriptionFailedFiles)}`);
     }
+    if (stats.embeddingFailures > 0) {
+        logCliInfo(logFilePath, "index", `  ${c.label("Embed failed:")}    ${c.num(stats.embeddingFailures)} chunk(s) without vectors — retried next pass`);
+    }
     logCliInfo(logFilePath, "index", `  ${c.label("Chunks written:")}   ${c.num(stats.totalChunks)}`);
+    if (stats.embeddingUnavailable) {
+        logCliInfo(logFilePath, "index", `  ${c.error("Embedding provider unavailable during this pass — no chunks were stored.")}`);
+    }
 }
 /**
  * Format a millisecond duration into a compact human-readable string.

package/dist/core/bootstrap.d.ts

@@ -35,6 +35,8 @@ export interface RagContext {
     dimension: number;
     /** Resolved path to the debug log file. */
     logFilePath: string;
+    /** Resolved path to the config file, or undefined when built-in defaults are used. */
+    configPath?: string;
 }
 /** Bootstrap the full RAG pipeline context: load config, resolve API keys, create embedder, vector store, keyword index, and description provider. */
 export declare function resolveRagContext(opts?: BootstrapOptions): Promise<RagContext>;

package/dist/core/bootstrap.js

@@ -6,26 +6,46 @@ import path from "node:path";
 import { loadConfig, findConfigFile, resolveLogConfig, DEFAULT_CONFIG } from "./config.js";
 import { resolveApiKey } from "./resolve-api-key.js";
 import { loadChunkersFromConfig } from "../chunker/loader.js";
-import { createEmbedder } from "../embedder/factory.js";
+import { createEmbedder, probeEmbeddingDimension } from "../embedder/factory.js";
 import { createDescriptionProvider } from "../describer/factory.js";
 import { createVectorStore } from "../vectorstore/factory.js";
+import { readStoreDimension } from "../vectorstore/lancedb.js";
 import { KeywordIndex } from "../retriever/keyword-index.js";
-/** Probe the embedding provider to determine the vector dimension. Falls back to 384 on failure. */
-async function probeDimension(embedder) {
-    try {
-        const probe = await embedder.embed(["dimension-probe"], "query");
-        if (probe && probe[0] && probe[0].length > 0 && typeof probe[0][0] === "number") {
-            return probe[0].length;
-        }
+/**
+ * Resolve the embedding dimension for the store.
+ *
+ * Precedence: an explicit `embedding.vectorDimension` in the config wins (it
+ * is persisted after the first successful probe), then a live probe of the
+ * provider, then the dimension of an existing store table, then the 384
+ * fallback. The old behavior always probed and fell back to 384 — which
+ * silently created 384-dimensional stores whenever the provider was down,
+ * even though the config declared the real dimension.
+ *
+ * @param embedder - Configured embedding provider (probed only when needed).
+ * @param storePath - Vector store path, used to read an existing schema.
+ * @param skipProbe - When true, never call the provider (read-only commands).
+ * @returns The resolved dimension.
+ */
+async function resolveDimension(embedder, storePath, skipProbe, configured) {
+    if (configured && configured > 0) {
+        return configured;
     }
-    catch {
-        // fallback to 384
+    if (!skipProbe) {
+        const probe = await probeEmbeddingDimension(embedder);
+        if (probe.dimension !== undefined) {
+            return probe.dimension;
+        }
+        const storeDimension = await readStoreDimension(storePath);
+        if (storeDimension !== undefined) {
+            console.warn(`[bootstrap] Could not probe embedding dimension (${probe.error?.message ?? "unknown error"}) — ` +
+                `using the existing store's dimension ${storeDimension}.`);
+            return storeDimension;
+        }
+        console.warn(`[bootstrap] Could not probe embedding dimension (${probe.error?.message ?? "unknown error"}) — ` +
+            "falling back to 384. Set embedding.vectorDimension explicitly if the provider produces a different size.");
+        return 384;
     }
-    // A wrong dimension is only discovered later as cryptic LanceDB errors —
-    // surface the fallback loudly so misconfigured providers are easy to spot.
-    console.warn("[bootstrap] Could not probe embedding dimension — falling back to 384. " +
-        "If indexing later fails with dimension errors, set embedding.vectorDimension explicitly.");
-    return 384;
+    return (await readStoreDimension(storePath)) ?? 384;
 }
 /** Load the keyword index from disk, or create a new empty one if loading fails. */
 async function loadKeywordIndex(storePath) {
@@ -61,8 +81,16 @@ export async function resolveRagContext(opts = {}) {
     }
     const logFilePath = path.resolve(workDir, resolveLogConfig(cfg).logFilePath);
     const embedder = createEmbedder(cfg);
-    const dimension = opts.skipProbe ? 384 : await probeDimension(embedder);
     const storePath = path.resolve(workDir, cfg.vectorStore.path);
+    const dimension = await resolveDimension(embedder, storePath, opts.skipProbe ?? false, cfg.embedding.vectorDimension);
+    // Warn (but do not block) when the existing store schema disagrees with the
+    // resolved dimension: the next index pass rebuilds automatically, and search
+    // callers would otherwise see only cryptic LanceDB errors.
+    const storeDimension = await readStoreDimension(storePath);
+    if (storeDimension !== undefined && storeDimension !== dimension) {
+        console.warn(`[bootstrap] Store was built with vector dimension ${storeDimension} but the current embedder produces ${dimension} — ` +
+            "run 'opencode-rag index' to rebuild the index with the current model.");
+    }
     const store = createVectorStore(cfg, storePath, dimension);
     const keywordIndex = opts.skipKeywordIndex
         ? new KeywordIndex(storePath)
@@ -80,6 +108,7 @@ export async function resolveRagContext(opts = {}) {
         descriptionProvider,
         dimension,
         logFilePath,
+        configPath,
     };
 }
 //# sourceMappingURL=bootstrap.js.map

package/dist/core/config.d.ts

@@ -296,6 +296,18 @@ export interface RagConfig {
         ollamaMaxBatchSize?: number;
         /** Maximum concurrent description generation requests. */
         descriptionConcurrency?: number;
+        /**
+         * Include LLM-generated chunk descriptions in the text that gets embedded.
+         *
+         * Descriptions help general-purpose embedding models align natural-language
+         * queries with raw code. Code-specialized models (e.g. jina-code-embeddings,
+         * trained for NL→code retrieval with instruction prefixes) do not need the
+         * crutch — and their passage prompt expects a code snippet, not prose.
+         * When false, descriptions are still generated and stored (search results,
+         * web UI), but only path/meta header/content are embedded.
+         * @default true
+         */
+        embedDescriptions?: boolean;
         /**
          * Maximum file size in bytes for SVG/XML files before chunking is skipped.
          * Large SVGs can cause tree-sitter to hang. Set to 0 for no limit.

package/dist/core/config.js

@@ -117,6 +117,7 @@ export const DEFAULT_CONFIG = {
         embedConcurrency: 3,
         ollamaMaxBatchSize: 100,
         descriptionConcurrency: 4,
+        embedDescriptions: true,
         maxSvgSizeBytes: 1_048_576,
         optimizeIntervalWindows: 8,
     },

package/dist/core/interfaces.d.ts

@@ -224,6 +224,14 @@ export interface VectorStore {
      * Used by the index pipeline to detect silent corruption before scanning.
      */
     checkIntegrity?(): Promise<boolean>;
+    /**
+     * Return the actual embedding dimension of the stored vector column, or
+     * `undefined` when the store has no table yet. Used to detect a store that
+     * was built with a different embedding model than the currently configured
+     * one — a mismatch makes every vector search fail and silently corrupts
+     * writes, so the pipeline rebuilds the index instead.
+     */
+    getVectorDimension?(): Promise<number | undefined>;
 }
 /** Filter criteria for narrowing search results by file path, language, kind, or extension. */
 export interface MetadataFilter {

package/dist/embedder/factory.d.ts

@@ -15,6 +15,26 @@ import type { RagConfig } from "../core/config.js";
  * @throws If the provider is unsupported or a required apiKey is not set
  */
 export declare function createEmbedder(config: RagConfig): EmbeddingProvider;
+/** Result of probing an embedding provider for its output dimension. */
+export interface EmbeddingProbeResult {
+    /** Detected vector dimension, or `undefined` when the probe failed. */
+    dimension?: number;
+    /** Error raised by the provider (or an empty response), when the probe failed. */
+    error?: Error;
+}
+/**
+ * Probe an embedding provider with a single short text to discover the
+ * dimension of the vectors it produces.
+ *
+ * Used as a health/dimension preflight before expensive index work: a provider
+ * that is down (server not running, model not pulled) fails here in
+ * milliseconds instead of after chunking and describing every file. Errors are
+ * captured in the result rather than thrown.
+ *
+ * @param embedder - The embedding provider to probe.
+ * @returns The detected dimension, or the failure reason.
+ */
+export declare function probeEmbeddingDimension(embedder: EmbeddingProvider): Promise<EmbeddingProbeResult>;
 /**
  * Embed a list of texts in batches with optional concurrency control and per-batch retry.
  *

package/dist/embedder/factory.js

@@ -40,6 +40,30 @@ export function createEmbedder(config) {
     }
     throw new Error(`Unknown embedding provider: ${provider}`);
 }
+/**
+ * Probe an embedding provider with a single short text to discover the
+ * dimension of the vectors it produces.
+ *
+ * Used as a health/dimension preflight before expensive index work: a provider
+ * that is down (server not running, model not pulled) fails here in
+ * milliseconds instead of after chunking and describing every file. Errors are
+ * captured in the result rather than thrown.
+ *
+ * @param embedder - The embedding provider to probe.
+ * @returns The detected dimension, or the failure reason.
+ */
+export async function probeEmbeddingDimension(embedder) {
+    try {
+        const probe = await embedder.embed(["dimension-probe"], "query");
+        if (probe && probe[0] && probe[0].length > 0 && typeof probe[0][0] === "number") {
+            return { dimension: probe[0].length };
+        }
+        return { error: new Error("Embedding provider returned an empty probe vector") };
+    }
+    catch (err) {
+        return { error: err instanceof Error ? err : new Error(String(err)) };
+    }
+}
 /**
  * HTTP statuses that indicate a permanent failure — retrying cannot help
  * (auth errors, bad requests, missing resources). Providers raise these as

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/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)

package/dist/vectorstore/lancedb.d.ts

@@ -53,10 +53,45 @@ export declare function isCorruptionError(err: unknown): boolean;
  * @returns True if the error matches a transient transaction conflict.
  */
 export declare function isTransientConflictError(err: unknown): boolean;
+/**
+ * Thrown when a write supplies embeddings whose length differs from the
+ * store's vector column dimension. LanceDB itself does NOT validate this —
+ * it silently zero-pads or truncates vectors into the fixed-size column,
+ * producing rows that can never be found by a query. Failing loudly here
+ * keeps that silent corruption out of the store.
+ */
+export declare class DimensionMismatchError extends Error {
+    /** Dimension of the store's vector column. */
+    readonly storeDimension: number;
+    /** Dimension of the embedding that was supplied. */
+    readonly embeddingDimension: number;
+    constructor(storeDimension: number, embeddingDimension: number, action?: string);
+}
+/** Type guard for {@link DimensionMismatchError}. */
+export declare function isDimensionMismatchError(err: unknown): err is DimensionMismatchError;
+/**
+ * Extract the fixed-size vector dimension of the `embedding` column from a
+ * LanceDB/Arrow schema. Returns `undefined` when the column is missing or is
+ * not a fixed-size list (e.g. before the table is created).
+ */
+export declare function extractEmbeddingDimension(fields: ReadonlyArray<{
+    name: string;
+    type: unknown;
+}>): number | undefined;
+/**
+ * Read the embedding dimension of an existing store without creating a table
+ * or holding a long-lived connection. Returns `undefined` when the store or
+ * table does not exist (or cannot be read).
+ *
+ * Used by the CLI bootstrap to avoid creating a brand-new store with a
+ * speculative dimension when the embedding provider cannot be probed.
+ */
+export declare function readStoreDimension(storePath: string): Promise<number | undefined>;
 /**
  * Atomically replace one LanceDB store directory with another.
  * Swaps the real directory with a temporary one that was built during a rebuild.
- * The old directory is moved to `${realPath}_old` and deleted asynchronously.
+ * The old directory is moved to `${realPath}_old` and deleted asynchronously
+ * after non-Lance artifacts (quirk memory, caches) have been carried over.
  *
  * @param tempPath - Path to the newly built store (source).
  * @param realPath - Path to the current store (destination, will be replaced).
@@ -94,6 +129,13 @@ export declare class LanceDbStore implements VectorStore {
     private indexRepairPromise;
     /** Consecutive failed repair attempts — bounded so a broken store cannot retrain forever. */
     private indexRepairFailures;
+    /**
+     * Actual dimension of the `embedding` column in the opened table. Read from
+     * the schema on first table access and used to validate writes/searches —
+     * the constructor's `vectorDimension` describes what the caller *expects*,
+     * which can drift from the store when the embedding model changes.
+     */
+    private knownDimension;
     /**
      * Execute an async function under an exclusive write lock.
      *
@@ -120,6 +162,23 @@ export declare class LanceDbStore implements VectorStore {
     private getTable;
     private initTable;
     private tableHasDescriptionColumn;
+    /**
+     * Read and cache the actual fixed-size dimension of the `embedding` column.
+     * Called whenever the table is (re)opened so write/search validation uses
+     * the store's real schema instead of the constructor's expectation.
+     */
+    private cacheTableDimension;
+    /**
+     * Return the actual embedding dimension of the store's vector column, or
+     * `undefined` when no table exists yet. Never creates the table.
+     */
+    getVectorDimension(): Promise<number | undefined>;
+    /**
+     * Fail loudly when rows carry embeddings whose length differs from the
+     * store's vector column. LanceDB would silently pad/truncate them instead,
+     * leaving rows that no query can match.
+     */
+    private assertEmbeddingDimensions;
     private hasColumn;
     /** Add kind/quirkType/tags columns if missing from an existing table. */
     private migrateNewColumns;

package/dist/vectorstore/lancedb.js

@@ -148,10 +148,129 @@ export function isTransientConflictError(err) {
     }
     return false;
 }
+/**
+ * Thrown when a write supplies embeddings whose length differs from the
+ * store's vector column dimension. LanceDB itself does NOT validate this —
+ * it silently zero-pads or truncates vectors into the fixed-size column,
+ * producing rows that can never be found by a query. Failing loudly here
+ * keeps that silent corruption out of the store.
+ */
+export class DimensionMismatchError extends Error {
+    /** Dimension of the store's vector column. */
+    storeDimension;
+    /** Dimension of the embedding that was supplied. */
+    embeddingDimension;
+    constructor(storeDimension, embeddingDimension, action = "rebuild it with 'opencode-rag index --force'") {
+        super(`Embedding dimension mismatch: the store holds ${storeDimension}-dimensional vectors ` +
+            `but the embedding model produced ${embeddingDimension}. The index was built with a ` +
+            `different embedding model — ${action}.`);
+        this.name = "DimensionMismatchError";
+        this.storeDimension = storeDimension;
+        this.embeddingDimension = embeddingDimension;
+    }
+}
+/** Type guard for {@link DimensionMismatchError}. */
+export function isDimensionMismatchError(err) {
+    return err instanceof DimensionMismatchError || (err instanceof Error && err.name === "DimensionMismatchError");
+}
+/**
+ * Extract the fixed-size vector dimension of the `embedding` column from a
+ * LanceDB/Arrow schema. Returns `undefined` when the column is missing or is
+ * not a fixed-size list (e.g. before the table is created).
+ */
+export function extractEmbeddingDimension(fields) {
+    const field = fields.find((f) => f.name === "embedding");
+    const type = field?.type;
+    if (type && typeof type.listSize === "number" && type.listSize > 0) {
+        return type.listSize;
+    }
+    return undefined;
+}
+/**
+ * Read the embedding dimension of an existing store without creating a table
+ * or holding a long-lived connection. Returns `undefined` when the store or
+ * table does not exist (or cannot be read).
+ *
+ * Used by the CLI bootstrap to avoid creating a brand-new store with a
+ * speculative dimension when the embedding provider cannot be probed.
+ */
+export async function readStoreDimension(storePath) {
+    if (storePath.startsWith("memory:"))
+        return undefined;
+    try {
+        // Do not create a store directory just to read a schema.
+        await fs.access(storePath);
+    }
+    catch {
+        return undefined;
+    }
+    try {
+        const db = await lancedb.connect(storePath);
+        const tableNames = await db.tableNames();
+        if (!tableNames.includes(TABLE_NAME))
+            return undefined;
+        const table = await db.openTable(TABLE_NAME);
+        const schema = await table.schema();
+        return extractEmbeddingDimension(schema.fields);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Non-Lance artifacts that live in the store directory next to the LanceDB
+ * data and must survive a rebuild swap. `chunks.lance`/`manifest.json` are
+ * rebuilt by the pipeline; the files below are not derivable from the new
+ * index and would otherwise be destroyed with the old directory.
+ */
+const PRESERVED_STORE_ENTRIES = [
+    "quirks.jsonl",
+    "runtime-overrides.json",
+    "watcher-status.json",
+    ".desc-cache.json",
+    "keyword-index.json",
+    "eval-sessions",
+];
+/**
+ * Carry non-Lance store artifacts (quirk memory, caches, overrides) from the
+ * pre-swap directory into the freshly promoted one. Best-effort: a failure to
+ * preserve one entry must not abort the swap.
+ */
+async function preserveStoreArtifacts(oldPath, realPath) {
+    for (const entry of PRESERVED_STORE_ENTRIES) {
+        const src = path.join(oldPath, entry);
+        const dest = path.join(realPath, entry);
+        try {
+            await fs.access(src);
+        }
+        catch {
+            continue; // artifact not present in the old store
+        }
+        try {
+            try {
+                await fs.access(dest);
+                continue; // destination already has this artifact (e.g. re-saved desc cache)
+            }
+            catch {
+                // destination missing — move or copy it over
+            }
+            await fs.rename(src, dest);
+        }
+        catch {
+            try {
+                await fs.cp(src, dest, { recursive: true, force: true });
+            }
+            catch {
+                // best-effort — keep the swap result even if an artifact cannot be carried over
+            }
+        }
+    }
+}
 /**
  * Atomically replace one LanceDB store directory with another.
  * Swaps the real directory with a temporary one that was built during a rebuild.
- * The old directory is moved to `${realPath}_old` and deleted asynchronously.
+ * The old directory is moved to `${realPath}_old` and deleted asynchronously
+ * after non-Lance artifacts (quirk memory, caches) have been carried over.
  *
  * @param tempPath - Path to the newly built store (source).
  * @param realPath - Path to the current store (destination, will be replaced).
@@ -176,7 +295,9 @@ export async function swapStoreDirectories(tempPath, realPath) {
         catch { }
         throw err;
     }
-    // Best-effort async cleanup of old directory
+    // Preserve quirks.jsonl & friends (the temp store contains only Lance data),
+    // then clean up the old directory best-effort.
+    await preserveStoreArtifacts(oldPath, realPath);
     fs.rm(oldPath, { recursive: true, force: true }).catch(() => { });
 }
 /**
@@ -201,6 +322,13 @@ export class LanceDbStore {
     indexRepairPromise = null;
     /** Consecutive failed repair attempts — bounded so a broken store cannot retrain forever. */
     indexRepairFailures = 0;
+    /**
+     * Actual dimension of the `embedding` column in the opened table. Read from
+     * the schema on first table access and used to validate writes/searches —
+     * the constructor's `vectorDimension` describes what the caller *expects*,
+     * which can drift from the store when the embedding model changes.
+     */
+    knownDimension = null;
     /**
      * Execute an async function under an exclusive write lock.
      *
@@ -270,6 +398,7 @@ export class LanceDbStore {
         const tableNames = await db.tableNames();
         if (tableNames.includes(TABLE_NAME)) {
             this.table = await db.openTable(TABLE_NAME);
+            await this.cacheTableDimension(this.table);
             if (await this.tableHasDescriptionColumn()) {
                 await this.migrateNewColumns();
                 return this.table;
@@ -323,6 +452,7 @@ export class LanceDbStore {
             data: [seedRow],
             mode: "overwrite",
         });
+        this.knownDimension = this.vectorDimension;
         const deleted = await this.table.delete('id = "__seed__"');
         if (deleted === undefined) {
             // LanceDB may not return a count; try a direct query to verify
@@ -342,6 +472,59 @@ export class LanceDbStore {
             return false;
         }
     }
+    /**
+     * Read and cache the actual fixed-size dimension of the `embedding` column.
+     * Called whenever the table is (re)opened so write/search validation uses
+     * the store's real schema instead of the constructor's expectation.
+     */
+    async cacheTableDimension(table) {
+        if (this.knownDimension !== null)
+            return this.knownDimension;
+        try {
+            const schema = await table.schema();
+            const dim = extractEmbeddingDimension(schema.fields);
+            if (dim !== undefined)
+                this.knownDimension = dim;
+            return dim;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Return the actual embedding dimension of the store's vector column, or
+     * `undefined` when no table exists yet. Never creates the table.
+     */
+    async getVectorDimension() {
+        if (this.knownDimension !== null)
+            return this.knownDimension;
+        try {
+            const db = await this.getDb();
+            const tableNames = await db.tableNames();
+            if (!tableNames.includes(TABLE_NAME))
+                return undefined;
+            const table = await this.getTable();
+            return await this.cacheTableDimension(table);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Fail loudly when rows carry embeddings whose length differs from the
+     * store's vector column. LanceDB would silently pad/truncate them instead,
+     * leaving rows that no query can match.
+     */
+    assertEmbeddingDimensions(rows) {
+        const storeDim = this.knownDimension;
+        if (storeDim === null)
+            return;
+        for (const row of rows) {
+            if (row.embedding.length !== storeDim) {
+                throw new DimensionMismatchError(storeDim, row.embedding.length);
+            }
+        }
+    }
     async hasColumn(name) {
         try {
             const schema = await this.table.schema();
@@ -489,6 +672,7 @@ export class LanceDbStore {
             .filter((r) => r !== null);
         if (rows.length === 0)
             return;
+        this.assertEmbeddingDimensions(rows);
         // INSERT FIRST: data is safely stored before any delete
         await table.add(rows);
         if (!dedup)
@@ -530,6 +714,7 @@ export class LanceDbStore {
         }
         if (allRows.length === 0)
             return;
+        this.assertEmbeddingDimensions(allRows);
         // INSERT FIRST (single add for the whole batch), then per-file dedup
         await table.add(allRows);
         for (const [filePath, ids] of dedupByFile) {
@@ -551,9 +736,21 @@ export class LanceDbStore {
     async searchWithFilter(embedding, topK, filter) {
         try {
             // Guard against dimension mismatch BEFORE the native call — LanceDB
-            // throws a cryptic error that used to be swallowed into "no results".
-            if (embedding.length !== this.vectorDimension) {
-                console.warn(`[lancedb] searchWithFilter: query embedding dimension ${embedding.length} != store dimension ${this.vectorDimension} — returning empty`);
+            // throws a cryptic "No vector column found to match with the query
+            // vector dimension" error. Compare against the table's *actual* column
+            // dimension, not the constructor's expectation: a store built by a
+            // different embedding model has a mismatching schema even when the
+            // handle was constructed with the current model's dimension.
+            const storeDimension = (await this.getVectorDimension()) ?? this.vectorDimension;
+            if (embedding.length !== storeDimension) {
+                if (storeDimension !== this.vectorDimension) {
+                    console.warn(`[lancedb] Store vector column is ${storeDimension}-dimensional but this handle expects ` +
+                        `${this.vectorDimension} — the index was built with a different embedding model. ` +
+                        "Rebuild it with 'opencode-rag index --force' (a plain 'opencode-rag index' also rebuilds automatically).");
+                }
+                else {
+                    console.warn(`[lancedb] searchWithFilter: query embedding dimension ${embedding.length} != store dimension ${storeDimension} — returning empty`);
+                }
                 return [];
             }
             return await this.searchInternal(embedding, topK, filter);
@@ -1090,6 +1287,7 @@ export class LanceDbStore {
         await this.close();
         if (newPath)
             this.dbPath = newPath;
+        this.knownDimension = null;
     }
     /**
      * Close the database connection and release resources.
@@ -1153,6 +1351,7 @@ export class LanceDbStore {
             console.warn(`[lancedb] Backed up chunks.lance to ${backup}`);
         await this.table?.close();
         this.table = null;
+        this.knownDimension = null;
         try {
             const db = await this.getDb();
             const tableNames = await db.tableNames();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-rag-plugin",
-  "version": "1.22.1",
+  "version": "1.22.2",
   "description": "OpenCode plugin for local-first RAG-based semantic code search",
   "type": "module",
   "main": "./dist/plugin-entry.js",