@tobilu/qmd 0.9.0

package/src/store.ts

@@ -0,0 +1,3072 @@
+/**
+ * QMD Store - Core data access and retrieval functions
+ *
+ * This module provides all database operations, search functions, and document
+ * retrieval for QMD. It returns raw data structures that can be formatted by
+ * CLI or MCP consumers.
+ *
+ * Usage:
+ *   const store = createStore("/path/to/db.sqlite");
+ *   // or use default path:
+ *   const store = createStore();
+ */
+
+import { Database } from "bun:sqlite";
+import { Glob } from "bun";
+import { realpathSync, statSync } from "node:fs";
+import * as sqliteVec from "sqlite-vec";
+import {
+  LlamaCpp,
+  getDefaultLlamaCpp,
+  formatQueryForEmbedding,
+  formatDocForEmbedding,
+  type RerankDocument,
+  type ILLMSession,
+} from "./llm";
+import {
+  findContextForPath as collectionsFindContextForPath,
+  addContext as collectionsAddContext,
+  removeContext as collectionsRemoveContext,
+  listAllContexts as collectionsListAllContexts,
+  getCollection,
+  listCollections as collectionsListCollections,
+  addCollection as collectionsAddCollection,
+  removeCollection as collectionsRemoveCollection,
+  renameCollection as collectionsRenameCollection,
+  setGlobalContext,
+  loadConfig as collectionsLoadConfig,
+  type NamedCollection,
+} from "./collections";
+
+// =============================================================================
+// Configuration
+// =============================================================================
+
+const HOME = Bun.env.HOME || "/tmp";
+export const DEFAULT_EMBED_MODEL = "embeddinggemma";
+export const DEFAULT_RERANK_MODEL = "ExpedientFalcon/qwen3-reranker:0.6b-q8_0";
+export const DEFAULT_QUERY_MODEL = "Qwen/Qwen3-1.7B";
+export const DEFAULT_GLOB = "**/*.md";
+export const DEFAULT_MULTI_GET_MAX_BYTES = 10 * 1024; // 10KB
+
+// Chunking: 900 tokens per chunk with 15% overlap
+// Increased from 800 to accommodate smart chunking finding natural break points
+export const CHUNK_SIZE_TOKENS = 900;
+export const CHUNK_OVERLAP_TOKENS = Math.floor(CHUNK_SIZE_TOKENS * 0.15);  // 135 tokens (15% overlap)
+// Fallback char-based approximation for sync chunking (~4 chars per token)
+export const CHUNK_SIZE_CHARS = CHUNK_SIZE_TOKENS * 4;  // 3600 chars
+export const CHUNK_OVERLAP_CHARS = CHUNK_OVERLAP_TOKENS * 4;  // 540 chars
+// Search window for finding optimal break points (in tokens, ~200 tokens)
+export const CHUNK_WINDOW_TOKENS = 200;
+export const CHUNK_WINDOW_CHARS = CHUNK_WINDOW_TOKENS * 4;  // 800 chars
+
+// =============================================================================
+// Smart Chunking - Break Point Detection
+// =============================================================================
+
+/**
+ * A potential break point in the document with a base score indicating quality.
+ */
+export interface BreakPoint {
+  pos: number;    // character position
+  score: number;  // base score (higher = better break point)
+  type: string;   // for debugging: 'h1', 'h2', 'blank', etc.
+}
+
+/**
+ * A region where a code fence exists (between ``` markers).
+ * We should never split inside a code fence.
+ */
+export interface CodeFenceRegion {
+  start: number;  // position of opening ```
+  end: number;    // position of closing ``` (or document end if unclosed)
+}
+
+/**
+ * Patterns for detecting break points in markdown documents.
+ * Higher scores indicate better places to split.
+ * Scores are spread wide so headings decisively beat lower-quality breaks.
+ * Order matters for scoring - more specific patterns first.
+ */
+export const BREAK_PATTERNS: [RegExp, number, string][] = [
+  [/\n#{1}(?!#)/g, 100, 'h1'],     // # but not ##
+  [/\n#{2}(?!#)/g, 90, 'h2'],      // ## but not ###
+  [/\n#{3}(?!#)/g, 80, 'h3'],      // ### but not ####
+  [/\n#{4}(?!#)/g, 70, 'h4'],      // #### but not #####
+  [/\n#{5}(?!#)/g, 60, 'h5'],      // ##### but not ######
+  [/\n#{6}(?!#)/g, 50, 'h6'],      // ######
+  [/\n```/g, 80, 'codeblock'],     // code block boundary (same as h3)
+  [/\n(?:---|\*\*\*|___)\s*\n/g, 60, 'hr'],  // horizontal rule
+  [/\n\n+/g, 20, 'blank'],         // paragraph boundary
+  [/\n[-*]\s/g, 5, 'list'],        // unordered list item
+  [/\n\d+\.\s/g, 5, 'numlist'],    // ordered list item
+  [/\n/g, 1, 'newline'],           // minimal break
+];
+
+/**
+ * Scan text for all potential break points.
+ * Returns sorted array of break points with higher-scoring patterns taking precedence
+ * when multiple patterns match the same position.
+ */
+export function scanBreakPoints(text: string): BreakPoint[] {
+  const points: BreakPoint[] = [];
+  const seen = new Map<number, BreakPoint>();  // pos -> best break point at that pos
+
+  for (const [pattern, score, type] of BREAK_PATTERNS) {
+    for (const match of text.matchAll(pattern)) {
+      const pos = match.index!;
+      const existing = seen.get(pos);
+      // Keep higher score if position already seen
+      if (!existing || score > existing.score) {
+        const bp = { pos, score, type };
+        seen.set(pos, bp);
+      }
+    }
+  }
+
+  // Convert to array and sort by position
+  for (const bp of seen.values()) {
+    points.push(bp);
+  }
+  return points.sort((a, b) => a.pos - b.pos);
+}
+
+/**
+ * Find all code fence regions in the text.
+ * Code fences are delimited by ``` and we should never split inside them.
+ */
+export function findCodeFences(text: string): CodeFenceRegion[] {
+  const regions: CodeFenceRegion[] = [];
+  const fencePattern = /\n```/g;
+  let inFence = false;
+  let fenceStart = 0;
+
+  for (const match of text.matchAll(fencePattern)) {
+    if (!inFence) {
+      fenceStart = match.index!;
+      inFence = true;
+    } else {
+      regions.push({ start: fenceStart, end: match.index! + match[0].length });
+      inFence = false;
+    }
+  }
+
+  // Handle unclosed fence - extends to end of document
+  if (inFence) {
+    regions.push({ start: fenceStart, end: text.length });
+  }
+
+  return regions;
+}
+
+/**
+ * Check if a position is inside a code fence region.
+ */
+export function isInsideCodeFence(pos: number, fences: CodeFenceRegion[]): boolean {
+  return fences.some(f => pos > f.start && pos < f.end);
+}
+
+/**
+ * Find the best cut position using scored break points with distance decay.
+ *
+ * Uses squared distance for gentler early decay - headings far back still win
+ * over low-quality breaks near the target.
+ *
+ * @param breakPoints - Pre-scanned break points from scanBreakPoints()
+ * @param targetCharPos - The ideal cut position (e.g., maxChars boundary)
+ * @param windowChars - How far back to search for break points (default ~200 tokens)
+ * @param decayFactor - How much to penalize distance (0.7 = 30% score at window edge)
+ * @param codeFences - Code fence regions to avoid splitting inside
+ * @returns The best position to cut at
+ */
+export function findBestCutoff(
+  breakPoints: BreakPoint[],
+  targetCharPos: number,
+  windowChars: number = CHUNK_WINDOW_CHARS,
+  decayFactor: number = 0.7,
+  codeFences: CodeFenceRegion[] = []
+): number {
+  const windowStart = targetCharPos - windowChars;
+  let bestScore = -1;
+  let bestPos = targetCharPos;
+
+  for (const bp of breakPoints) {
+    if (bp.pos < windowStart) continue;
+    if (bp.pos > targetCharPos) break;  // sorted, so we can stop
+
+    // Skip break points inside code fences
+    if (isInsideCodeFence(bp.pos, codeFences)) continue;
+
+    const distance = targetCharPos - bp.pos;
+    // Squared distance decay: gentle early, steep late
+    // At target: multiplier = 1.0
+    // At 25% back: multiplier = 0.956
+    // At 50% back: multiplier = 0.825
+    // At 75% back: multiplier = 0.606
+    // At window edge: multiplier = 0.3
+    const normalizedDist = distance / windowChars;
+    const multiplier = 1.0 - (normalizedDist * normalizedDist) * decayFactor;
+    const finalScore = bp.score * multiplier;
+
+    if (finalScore > bestScore) {
+      bestScore = finalScore;
+      bestPos = bp.pos;
+    }
+  }
+
+  return bestPos;
+}
+
+// Hybrid query: strong BM25 signal detection thresholds
+// Skip expensive LLM expansion when top result is strong AND clearly separated from runner-up
+export const STRONG_SIGNAL_MIN_SCORE = 0.85;
+export const STRONG_SIGNAL_MIN_GAP = 0.15;
+// Max candidates to pass to reranker — balances quality vs latency.
+// 40 keeps rank 31-40 visible to the reranker (matters for recall on broad queries).
+export const RERANK_CANDIDATE_LIMIT = 40;
+
+/**
+ * A typed query expansion result. Decoupled from llm.ts internal Queryable —
+ * same shape, but store.ts owns its own public API type.
+ *
+ * - lex: keyword variant → routes to FTS only
+ * - vec: semantic variant → routes to vector only
+ * - hyde: hypothetical document → routes to vector only
+ */
+export type ExpandedQuery = {
+  type: 'lex' | 'vec' | 'hyde';
+  text: string;
+};
+
+// =============================================================================
+// Path utilities
+// =============================================================================
+
+export function homedir(): string {
+  return HOME;
+}
+
+/**
+ * Check if a path is absolute.
+ * Supports:
+ * - Unix paths: /path/to/file
+ * - Windows native: C:\path or C:/path
+ * - Git Bash: /c/path or /C/path (C-Z drives, excluding A/B floppy drives)
+ * 
+ * Note: /c without trailing slash is treated as Unix path (directory named "c"),
+ * while /c/ or /c/path are treated as Git Bash paths (C: drive).
+ */
+export function isAbsolutePath(path: string): boolean {
+  if (!path) return false;
+  
+  // Unix absolute path
+  if (path.startsWith('/')) {
+    // Check if it's a Git Bash style path like /c/ or /c/Users (C-Z only, not A or B)
+    // Requires path[2] === '/' to distinguish from Unix paths like /c or /cache
+    if (path.length >= 3 && path[2] === '/') {
+      const driveLetter = path[1];
+      if (driveLetter && /[c-zC-Z]/.test(driveLetter)) {
+        return true;
+      }
+    }
+    // Any other path starting with / is Unix absolute
+    return true;
+  }
+  
+  // Windows native path: C:\ or C:/ (any letter A-Z)
+  if (path.length >= 2 && /[a-zA-Z]/.test(path[0]!) && path[1] === ':') {
+    return true;
+  }
+  
+  return false;
+}
+
+/**
+ * Normalize path separators to forward slashes.
+ * Converts Windows backslashes to forward slashes.
+ */
+export function normalizePathSeparators(path: string): string {
+  return path.replace(/\\/g, '/');
+}
+
+/**
+ * Get the relative path from a prefix.
+ * Returns null if path is not under prefix.
+ * Returns empty string if path equals prefix.
+ */
+export function getRelativePathFromPrefix(path: string, prefix: string): string | null {
+  // Empty prefix is invalid
+  if (!prefix) {
+    return null;
+  }
+  
+  const normalizedPath = normalizePathSeparators(path);
+  const normalizedPrefix = normalizePathSeparators(prefix);
+  
+  // Ensure prefix ends with / for proper matching
+  const prefixWithSlash = !normalizedPrefix.endsWith('/') 
+    ? normalizedPrefix + '/' 
+    : normalizedPrefix;
+  
+  // Exact match
+  if (normalizedPath === normalizedPrefix) {
+    return '';
+  }
+  
+  // Check if path starts with prefix
+  if (normalizedPath.startsWith(prefixWithSlash)) {
+    return normalizedPath.slice(prefixWithSlash.length);
+  }
+  
+  return null;
+}
+
+export function resolve(...paths: string[]): string {
+  if (paths.length === 0) {
+    throw new Error("resolve: at least one path segment is required");
+  }
+  
+  // Normalize all paths to use forward slashes
+  const normalizedPaths = paths.map(normalizePathSeparators);
+  
+  let result = '';
+  let windowsDrive = '';
+  
+  // Check if first path is absolute
+  const firstPath = normalizedPaths[0]!;
+  if (isAbsolutePath(firstPath)) {
+    result = firstPath;
+    
+    // Extract Windows drive letter if present
+    if (firstPath.length >= 2 && /[a-zA-Z]/.test(firstPath[0]!) && firstPath[1] === ':') {
+      windowsDrive = firstPath.slice(0, 2);
+      result = firstPath.slice(2);
+    } else if (firstPath.startsWith('/') && firstPath.length >= 3 && firstPath[2] === '/') {
+      // Git Bash style: /c/ -> C: (C-Z drives only, not A or B)
+      const driveLetter = firstPath[1];
+      if (driveLetter && /[c-zC-Z]/.test(driveLetter)) {
+        windowsDrive = driveLetter.toUpperCase() + ':';
+        result = firstPath.slice(2);
+      }
+    }
+  } else {
+    // Start with PWD or cwd, then append the first relative path
+    const pwd = normalizePathSeparators(Bun.env.PWD || process.cwd());
+    
+    // Extract Windows drive from PWD if present
+    if (pwd.length >= 2 && /[a-zA-Z]/.test(pwd[0]!) && pwd[1] === ':') {
+      windowsDrive = pwd.slice(0, 2);
+      result = pwd.slice(2) + '/' + firstPath;
+    } else {
+      result = pwd + '/' + firstPath;
+    }
+  }
+  
+  // Process remaining paths
+  for (let i = 1; i < normalizedPaths.length; i++) {
+    const p = normalizedPaths[i]!;
+    if (isAbsolutePath(p)) {
+      // Absolute path replaces everything
+      result = p;
+      
+      // Update Windows drive if present
+      if (p.length >= 2 && /[a-zA-Z]/.test(p[0]!) && p[1] === ':') {
+        windowsDrive = p.slice(0, 2);
+        result = p.slice(2);
+      } else if (p.startsWith('/') && p.length >= 3 && p[2] === '/') {
+        // Git Bash style (C-Z drives only, not A or B)
+        const driveLetter = p[1];
+        if (driveLetter && /[c-zC-Z]/.test(driveLetter)) {
+          windowsDrive = driveLetter.toUpperCase() + ':';
+          result = p.slice(2);
+        } else {
+          windowsDrive = '';
+        }
+      } else {
+        windowsDrive = '';
+      }
+    } else {
+      // Relative path - append
+      result = result + '/' + p;
+    }
+  }
+  
+  // Normalize . and .. components
+  const parts = result.split('/').filter(Boolean);
+  const normalized: string[] = [];
+  for (const part of parts) {
+    if (part === '..') {
+      normalized.pop();
+    } else if (part !== '.') {
+      normalized.push(part);
+    }
+  }
+  
+  // Build final path
+  const finalPath = '/' + normalized.join('/');
+  
+  // Prepend Windows drive if present
+  if (windowsDrive) {
+    return windowsDrive + finalPath;
+  }
+  
+  return finalPath;
+}
+
+// Flag to indicate production mode (set by qmd.ts at startup)
+let _productionMode = false;
+
+export function enableProductionMode(): void {
+  _productionMode = true;
+}
+
+export function getDefaultDbPath(indexName: string = "index"): string {
+  // Always allow override via INDEX_PATH (for testing)
+  if (Bun.env.INDEX_PATH) {
+    return Bun.env.INDEX_PATH;
+  }
+
+  // In non-production mode (tests), require explicit path
+  if (!_productionMode) {
+    throw new Error(
+      "Database path not set. Tests must set INDEX_PATH env var or use createStore() with explicit path. " +
+      "This prevents tests from accidentally writing to the global index."
+    );
+  }
+
+  const cacheDir = Bun.env.XDG_CACHE_HOME || resolve(homedir(), ".cache");
+  const qmdCacheDir = resolve(cacheDir, "qmd");
+  try { Bun.spawnSync(["mkdir", "-p", qmdCacheDir]); } catch { }
+  return resolve(qmdCacheDir, `${indexName}.sqlite`);
+}
+
+export function getPwd(): string {
+  return process.env.PWD || process.cwd();
+}
+
+export function getRealPath(path: string): string {
+  try {
+    return realpathSync(path);
+  } catch {
+    return resolve(path);
+  }
+}
+
+// =============================================================================
+// Virtual Path Utilities (qmd://)
+// =============================================================================
+
+export type VirtualPath = {
+  collectionName: string;
+  path: string;  // relative path within collection
+};
+
+/**
+ * Normalize explicit virtual path formats to standard qmd:// format.
+ * Only handles paths that are already explicitly virtual:
+ * - qmd://collection/path.md (already normalized)
+ * - qmd:////collection/path.md (extra slashes - normalize)
+ * - //collection/path.md (missing qmd: prefix - add it)
+ *
+ * Does NOT handle:
+ * - collection/path.md (bare paths - could be filesystem relative)
+ * - :linenum suffix (should be parsed separately before calling this)
+ */
+export function normalizeVirtualPath(input: string): string {
+  let path = input.trim();
+
+  // Handle qmd:// with extra slashes: qmd:////collection/path -> qmd://collection/path
+  if (path.startsWith('qmd:')) {
+    // Remove qmd: prefix and normalize slashes
+    path = path.slice(4);
+    // Remove leading slashes and re-add exactly two
+    path = path.replace(/^\/+/, '');
+    return `qmd://${path}`;
+  }
+
+  // Handle //collection/path (missing qmd: prefix)
+  if (path.startsWith('//')) {
+    path = path.replace(/^\/+/, '');
+    return `qmd://${path}`;
+  }
+
+  // Return as-is for other cases (filesystem paths, docids, bare collection/path, etc.)
+  return path;
+}
+
+/**
+ * Parse a virtual path like "qmd://collection-name/path/to/file.md"
+ * into its components.
+ * Also supports collection root: "qmd://collection-name/" or "qmd://collection-name"
+ */
+export function parseVirtualPath(virtualPath: string): VirtualPath | null {
+  // Normalize the path first
+  const normalized = normalizeVirtualPath(virtualPath);
+
+  // Match: qmd://collection-name[/optional-path]
+  // Allows: qmd://name, qmd://name/, qmd://name/path
+  const match = normalized.match(/^qmd:\/\/([^\/]+)\/?(.*)$/);
+  if (!match?.[1]) return null;
+  return {
+    collectionName: match[1],
+    path: match[2] ?? '',  // Empty string for collection root
+  };
+}
+
+/**
+ * Build a virtual path from collection name and relative path.
+ */
+export function buildVirtualPath(collectionName: string, path: string): string {
+  return `qmd://${collectionName}/${path}`;
+}
+
+/**
+ * Check if a path is explicitly a virtual path.
+ * Only recognizes explicit virtual path formats:
+ * - qmd://collection/path.md
+ * - //collection/path.md
+ *
+ * Does NOT consider bare collection/path.md as virtual - that should be
+ * handled separately by checking if the first component is a collection name.
+ */
+export function isVirtualPath(path: string): boolean {
+  const trimmed = path.trim();
+
+  // Explicit qmd:// prefix (with any number of slashes)
+  if (trimmed.startsWith('qmd:')) return true;
+
+  // //collection/path format (missing qmd: prefix)
+  if (trimmed.startsWith('//')) return true;
+
+  return false;
+}
+
+/**
+ * Resolve a virtual path to absolute filesystem path.
+ */
+export function resolveVirtualPath(db: Database, virtualPath: string): string | null {
+  const parsed = parseVirtualPath(virtualPath);
+  if (!parsed) return null;
+
+  const coll = getCollectionByName(db, parsed.collectionName);
+  if (!coll) return null;
+
+  return resolve(coll.pwd, parsed.path);
+}
+
+/**
+ * Convert an absolute filesystem path to a virtual path.
+ * Returns null if the file is not in any indexed collection.
+ */
+export function toVirtualPath(db: Database, absolutePath: string): string | null {
+  // Get all collections from YAML config
+  const collections = collectionsListCollections();
+
+  // Find which collection this absolute path belongs to
+  for (const coll of collections) {
+    if (absolutePath.startsWith(coll.path + '/') || absolutePath === coll.path) {
+      // Extract relative path
+      const relativePath = absolutePath.startsWith(coll.path + '/')
+        ? absolutePath.slice(coll.path.length + 1)
+        : '';
+
+      // Verify this document exists in the database
+      const doc = db.prepare(`
+        SELECT d.path
+        FROM documents d
+        WHERE d.collection = ? AND d.path = ? AND d.active = 1
+        LIMIT 1
+      `).get(coll.name, relativePath) as { path: string } | null;
+
+      if (doc) {
+        return buildVirtualPath(coll.name, relativePath);
+      }
+    }
+  }
+
+  return null;
+}
+
+// =============================================================================
+// Database initialization
+// =============================================================================
+
+function setSQLiteFromBrewPrefixEnv(): void {
+  const candidates: string[] = [];
+
+  if (process.platform === "darwin") {
+    // Use BREW_PREFIX for non-standard Homebrew installs (common on corporate Macs).
+    const brewPrefix = Bun.env.BREW_PREFIX || Bun.env.HOMEBREW_PREFIX;
+    if (brewPrefix) {
+      // Homebrew can place SQLite in opt/sqlite (keg-only) or directly under the prefix.
+      candidates.push(`${brewPrefix}/opt/sqlite/lib/libsqlite3.dylib`);
+      candidates.push(`${brewPrefix}/lib/libsqlite3.dylib`);
+    } else {
+      candidates.push("/opt/homebrew/opt/sqlite/lib/libsqlite3.dylib");
+      candidates.push("/usr/local/opt/sqlite/lib/libsqlite3.dylib");
+    }
+  }
+
+  for (const candidate of candidates) {
+    try {
+      if (statSync(candidate).size > 0) {
+        Database.setCustomSQLite(candidate);
+        return;
+      }
+    } catch { }
+  }
+}
+
+setSQLiteFromBrewPrefixEnv();
+
+function createSqliteVecUnavailableError(reason: string): Error {
+  return new Error(
+    "sqlite-vec extension is unavailable. " +
+    `${reason}. ` +
+    "Install Homebrew SQLite so the sqlite-vec extension can be loaded, " +
+    "and set BREW_PREFIX if Homebrew is installed in a non-standard location."
+  );
+}
+
+function getErrorMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+export function verifySqliteVecLoaded(db: Database): void {
+  try {
+    const row = db.prepare(`SELECT vec_version() AS version`).get() as { version?: string } | null;
+    if (!row?.version || typeof row.version !== "string") {
+      throw new Error("vec_version() returned no version");
+    }
+  } catch (err) {
+    const message = getErrorMessage(err);
+    throw createSqliteVecUnavailableError(`sqlite-vec probe failed (${message})`);
+  }
+}
+
+function initializeDatabase(db: Database): void {
+  try {
+    sqliteVec.load(db);
+    verifySqliteVecLoaded(db);
+  } catch (err) {
+    const message = getErrorMessage(err);
+
+    if (message.includes("does not support dynamic extension loading")) {
+      throw createSqliteVecUnavailableError("SQLite build does not support dynamic extension loading");
+    }
+
+    if (message.includes("sqlite-vec extension is unavailable")) {
+      throw err;
+    }
+
+    throw err;
+  }
+  db.exec("PRAGMA journal_mode = WAL");
+  db.exec("PRAGMA foreign_keys = ON");
+
+  // Drop legacy tables that are now managed in YAML
+  db.exec(`DROP TABLE IF EXISTS path_contexts`);
+  db.exec(`DROP TABLE IF EXISTS collections`);
+
+  // Content-addressable storage - the source of truth for document content
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS content (
+      hash TEXT PRIMARY KEY,
+      doc TEXT NOT NULL,
+      created_at TEXT NOT NULL
+    )
+  `);
+
+  // Documents table - file system layer mapping virtual paths to content hashes
+  // Collections are now managed in ~/.config/qmd/index.yml
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS documents (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      collection TEXT NOT NULL,
+      path TEXT NOT NULL,
+      title TEXT NOT NULL,
+      hash TEXT NOT NULL,
+      created_at TEXT NOT NULL,
+      modified_at TEXT NOT NULL,
+      active INTEGER NOT NULL DEFAULT 1,
+      FOREIGN KEY (hash) REFERENCES content(hash) ON DELETE CASCADE,
+      UNIQUE(collection, path)
+    )
+  `);
+
+  db.exec(`CREATE INDEX IF NOT EXISTS idx_documents_collection ON documents(collection, active)`);
+  db.exec(`CREATE INDEX IF NOT EXISTS idx_documents_hash ON documents(hash)`);
+  db.exec(`CREATE INDEX IF NOT EXISTS idx_documents_path ON documents(path, active)`);
+
+  // Cache table for LLM API calls
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS llm_cache (
+      hash TEXT PRIMARY KEY,
+      result TEXT NOT NULL,
+      created_at TEXT NOT NULL
+    )
+  `);
+
+  // Content vectors
+  const cvInfo = db.prepare(`PRAGMA table_info(content_vectors)`).all() as { name: string }[];
+  const hasSeqColumn = cvInfo.some(col => col.name === 'seq');
+  if (cvInfo.length > 0 && !hasSeqColumn) {
+    db.exec(`DROP TABLE IF EXISTS content_vectors`);
+    db.exec(`DROP TABLE IF EXISTS vectors_vec`);
+  }
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS content_vectors (
+      hash TEXT NOT NULL,
+      seq INTEGER NOT NULL DEFAULT 0,
+      pos INTEGER NOT NULL DEFAULT 0,
+      model TEXT NOT NULL,
+      embedded_at TEXT NOT NULL,
+      PRIMARY KEY (hash, seq)
+    )
+  `);
+
+  // FTS - index filepath (collection/path), title, and content
+  db.exec(`
+    CREATE VIRTUAL TABLE IF NOT EXISTS documents_fts USING fts5(
+      filepath, title, body,
+      tokenize='porter unicode61'
+    )
+  `);
+
+  // Triggers to keep FTS in sync
+  db.exec(`
+    CREATE TRIGGER IF NOT EXISTS documents_ai AFTER INSERT ON documents
+    WHEN new.active = 1
+    BEGIN
+      INSERT INTO documents_fts(rowid, filepath, title, body)
+      SELECT
+        new.id,
+        new.collection || '/' || new.path,
+        new.title,
+        (SELECT doc FROM content WHERE hash = new.hash)
+      WHERE new.active = 1;
+    END
+  `);
+
+  db.exec(`
+    CREATE TRIGGER IF NOT EXISTS documents_ad AFTER DELETE ON documents BEGIN
+      DELETE FROM documents_fts WHERE rowid = old.id;
+    END
+  `);
+
+  db.exec(`
+    CREATE TRIGGER IF NOT EXISTS documents_au AFTER UPDATE ON documents
+    BEGIN
+      -- Delete from FTS if no longer active
+      DELETE FROM documents_fts WHERE rowid = old.id AND new.active = 0;
+
+      -- Update FTS if still/newly active
+      INSERT OR REPLACE INTO documents_fts(rowid, filepath, title, body)
+      SELECT
+        new.id,
+        new.collection || '/' || new.path,
+        new.title,
+        (SELECT doc FROM content WHERE hash = new.hash)
+      WHERE new.active = 1;
+    END
+  `);
+}
+
+
+function ensureVecTableInternal(db: Database, dimensions: number): void {
+  const tableInfo = db.prepare(`SELECT sql FROM sqlite_master WHERE type='table' AND name='vectors_vec'`).get() as { sql: string } | null;
+  if (tableInfo) {
+    const match = tableInfo.sql.match(/float\[(\d+)\]/);
+    const hasHashSeq = tableInfo.sql.includes('hash_seq');
+    const hasCosine = tableInfo.sql.includes('distance_metric=cosine');
+    const existingDims = match?.[1] ? parseInt(match[1], 10) : null;
+    if (existingDims === dimensions && hasHashSeq && hasCosine) return;
+    // Table exists but wrong schema - need to rebuild
+    db.exec("DROP TABLE IF EXISTS vectors_vec");
+  }
+  db.exec(`CREATE VIRTUAL TABLE vectors_vec USING vec0(hash_seq TEXT PRIMARY KEY, embedding float[${dimensions}] distance_metric=cosine)`);
+}
+
+// =============================================================================
+// Store Factory
+// =============================================================================
+
+export type Store = {
+  db: Database;
+  dbPath: string;
+  close: () => void;
+  ensureVecTable: (dimensions: number) => void;
+
+  // Index health
+  getHashesNeedingEmbedding: () => number;
+  getIndexHealth: () => IndexHealthInfo;
+  getStatus: () => IndexStatus;
+
+  // Caching
+  getCacheKey: typeof getCacheKey;
+  getCachedResult: (cacheKey: string) => string | null;
+  setCachedResult: (cacheKey: string, result: string) => void;
+  clearCache: () => void;
+
+  // Cleanup and maintenance
+  deleteLLMCache: () => number;
+  deleteInactiveDocuments: () => number;
+  cleanupOrphanedContent: () => number;
+  cleanupOrphanedVectors: () => number;
+  vacuumDatabase: () => void;
+
+  // Context
+  getContextForFile: (filepath: string) => string | null;
+  getContextForPath: (collectionName: string, path: string) => string | null;
+  getCollectionByName: (name: string) => { name: string; pwd: string; glob_pattern: string } | null;
+  getCollectionsWithoutContext: () => { name: string; pwd: string; doc_count: number }[];
+  getTopLevelPathsWithoutContext: (collectionName: string) => string[];
+
+  // Virtual paths
+  parseVirtualPath: typeof parseVirtualPath;
+  buildVirtualPath: typeof buildVirtualPath;
+  isVirtualPath: typeof isVirtualPath;
+  resolveVirtualPath: (virtualPath: string) => string | null;
+  toVirtualPath: (absolutePath: string) => string | null;
+
+  // Search
+  searchFTS: (query: string, limit?: number, collectionId?: number) => SearchResult[];
+  searchVec: (query: string, model: string, limit?: number, collectionName?: string) => Promise<SearchResult[]>;
+
+  // Query expansion & reranking
+  expandQuery: (query: string, model?: string) => Promise<ExpandedQuery[]>;
+  rerank: (query: string, documents: { file: string; text: string }[], model?: string) => Promise<{ file: string; score: number }[]>;
+
+  // Document retrieval
+  findDocument: (filename: string, options?: { includeBody?: boolean }) => DocumentResult | DocumentNotFound;
+  getDocumentBody: (doc: DocumentResult | { filepath: string }, fromLine?: number, maxLines?: number) => string | null;
+  findDocuments: (pattern: string, options?: { includeBody?: boolean; maxBytes?: number }) => { docs: MultiGetResult[]; errors: string[] };
+
+  // Fuzzy matching and docid lookup
+  findSimilarFiles: (query: string, maxDistance?: number, limit?: number) => string[];
+  matchFilesByGlob: (pattern: string) => { filepath: string; displayPath: string; bodyLength: number }[];
+  findDocumentByDocid: (docid: string) => { filepath: string; hash: string } | null;
+
+  // Document indexing operations
+  insertContent: (hash: string, content: string, createdAt: string) => void;
+  insertDocument: (collectionName: string, path: string, title: string, hash: string, createdAt: string, modifiedAt: string) => void;
+  findActiveDocument: (collectionName: string, path: string) => { id: number; hash: string; title: string } | null;
+  updateDocumentTitle: (documentId: number, title: string, modifiedAt: string) => void;
+  updateDocument: (documentId: number, title: string, hash: string, modifiedAt: string) => void;
+  deactivateDocument: (collectionName: string, path: string) => void;
+  getActiveDocumentPaths: (collectionName: string) => string[];
+
+  // Vector/embedding operations
+  getHashesForEmbedding: () => { hash: string; body: string; path: string }[];
+  clearAllEmbeddings: () => void;
+  insertEmbedding: (hash: string, seq: number, pos: number, embedding: Float32Array, model: string, embeddedAt: string) => void;
+};
+
+/**
+ * Create a new store instance with the given database path.
+ * If no path is provided, uses the default path (~/.cache/qmd/index.sqlite).
+ *
+ * @param dbPath - Path to the SQLite database file
+ * @returns Store instance with all methods bound to the database
+ */
+export function createStore(dbPath?: string): Store {
+  const resolvedPath = dbPath || getDefaultDbPath();
+  const db = new Database(resolvedPath);
+  initializeDatabase(db);
+
+  return {
+    db,
+    dbPath: resolvedPath,
+    close: () => db.close(),
+    ensureVecTable: (dimensions: number) => ensureVecTableInternal(db, dimensions),
+
+    // Index health
+    getHashesNeedingEmbedding: () => getHashesNeedingEmbedding(db),
+    getIndexHealth: () => getIndexHealth(db),
+    getStatus: () => getStatus(db),
+
+    // Caching
+    getCacheKey,
+    getCachedResult: (cacheKey: string) => getCachedResult(db, cacheKey),
+    setCachedResult: (cacheKey: string, result: string) => setCachedResult(db, cacheKey, result),
+    clearCache: () => clearCache(db),
+
+    // Cleanup and maintenance
+    deleteLLMCache: () => deleteLLMCache(db),
+    deleteInactiveDocuments: () => deleteInactiveDocuments(db),
+    cleanupOrphanedContent: () => cleanupOrphanedContent(db),
+    cleanupOrphanedVectors: () => cleanupOrphanedVectors(db),
+    vacuumDatabase: () => vacuumDatabase(db),
+
+    // Context
+    getContextForFile: (filepath: string) => getContextForFile(db, filepath),
+    getContextForPath: (collectionName: string, path: string) => getContextForPath(db, collectionName, path),
+    getCollectionByName: (name: string) => getCollectionByName(db, name),
+    getCollectionsWithoutContext: () => getCollectionsWithoutContext(db),
+    getTopLevelPathsWithoutContext: (collectionName: string) => getTopLevelPathsWithoutContext(db, collectionName),
+
+    // Virtual paths
+    parseVirtualPath,
+    buildVirtualPath,
+    isVirtualPath,
+    resolveVirtualPath: (virtualPath: string) => resolveVirtualPath(db, virtualPath),
+    toVirtualPath: (absolutePath: string) => toVirtualPath(db, absolutePath),
+
+    // Search
+    searchFTS: (query: string, limit?: number, collectionId?: number) => searchFTS(db, query, limit, collectionId),
+    searchVec: (query: string, model: string, limit?: number, collectionName?: string) => searchVec(db, query, model, limit, collectionName),
+
+    // Query expansion & reranking
+    expandQuery: (query: string, model?: string) => expandQuery(query, model, db),
+    rerank: (query: string, documents: { file: string; text: string }[], model?: string) => rerank(query, documents, model, db),
+
+    // Document retrieval
+    findDocument: (filename: string, options?: { includeBody?: boolean }) => findDocument(db, filename, options),
+    getDocumentBody: (doc: DocumentResult | { filepath: string }, fromLine?: number, maxLines?: number) => getDocumentBody(db, doc, fromLine, maxLines),
+    findDocuments: (pattern: string, options?: { includeBody?: boolean; maxBytes?: number }) => findDocuments(db, pattern, options),
+
+    // Fuzzy matching and docid lookup
+    findSimilarFiles: (query: string, maxDistance?: number, limit?: number) => findSimilarFiles(db, query, maxDistance, limit),
+    matchFilesByGlob: (pattern: string) => matchFilesByGlob(db, pattern),
+    findDocumentByDocid: (docid: string) => findDocumentByDocid(db, docid),
+
+    // Document indexing operations
+    insertContent: (hash: string, content: string, createdAt: string) => insertContent(db, hash, content, createdAt),
+    insertDocument: (collectionName: string, path: string, title: string, hash: string, createdAt: string, modifiedAt: string) => insertDocument(db, collectionName, path, title, hash, createdAt, modifiedAt),
+    findActiveDocument: (collectionName: string, path: string) => findActiveDocument(db, collectionName, path),
+    updateDocumentTitle: (documentId: number, title: string, modifiedAt: string) => updateDocumentTitle(db, documentId, title, modifiedAt),
+    updateDocument: (documentId: number, title: string, hash: string, modifiedAt: string) => updateDocument(db, documentId, title, hash, modifiedAt),
+    deactivateDocument: (collectionName: string, path: string) => deactivateDocument(db, collectionName, path),
+    getActiveDocumentPaths: (collectionName: string) => getActiveDocumentPaths(db, collectionName),
+
+    // Vector/embedding operations
+    getHashesForEmbedding: () => getHashesForEmbedding(db),
+    clearAllEmbeddings: () => clearAllEmbeddings(db),
+    insertEmbedding: (hash: string, seq: number, pos: number, embedding: Float32Array, model: string, embeddedAt: string) => insertEmbedding(db, hash, seq, pos, embedding, model, embeddedAt),
+  };
+}
+
+// =============================================================================
+// Core Document Type
+// =============================================================================
+
+/**
+ * Unified document result type with all metadata.
+ * Body is optional - use getDocumentBody() to load it separately if needed.
+ */
+export type DocumentResult = {
+  filepath: string;           // Full filesystem path
+  displayPath: string;        // Short display path (e.g., "docs/readme.md")
+  title: string;              // Document title (from first heading or filename)
+  context: string | null;     // Folder context description if configured
+  hash: string;               // Content hash for caching/change detection
+  docid: string;              // Short docid (first 6 chars of hash) for quick reference
+  collectionName: string;     // Parent collection name
+  modifiedAt: string;         // Last modification timestamp
+  bodyLength: number;         // Body length in bytes (useful before loading)
+  body?: string;              // Document body (optional, load with getDocumentBody)
+};
+
+/**
+ * Extract short docid from a full hash (first 6 characters).
+ */
+export function getDocid(hash: string): string {
+  return hash.slice(0, 6);
+}
+
+/**
+ * Handelize a filename to be more token-friendly.
+ * - Convert triple underscore `___` to `/` (folder separator)
+ * - Convert to lowercase
+ * - Replace sequences of non-word chars (except /) with single dash
+ * - Remove leading/trailing dashes from path segments
+ * - Preserve folder structure (a/b/c/d.md stays structured)
+ * - Preserve file extension
+ */
+export function handelize(path: string): string {
+  if (!path || path.trim() === '') {
+    throw new Error('handelize: path cannot be empty');
+  }
+
+  // Allow route-style "$" filenames while still rejecting paths with no usable content.
+  const segments = path.split('/').filter(Boolean);
+  const lastSegment = segments[segments.length - 1] || '';
+  const filenameWithoutExt = lastSegment.replace(/\.[^.]+$/, '');
+  const hasValidContent = /[\p{L}\p{N}$]/u.test(filenameWithoutExt);
+  if (!hasValidContent) {
+    throw new Error(`handelize: path "${path}" has no valid filename content`);
+  }
+
+  const result = path
+    .replace(/___/g, '/')       // Triple underscore becomes folder separator
+    .toLowerCase()
+    .split('/')
+    .map((segment, idx, arr) => {
+      const isLastSegment = idx === arr.length - 1;
+
+      if (isLastSegment) {
+        // For the filename (last segment), preserve the extension
+        const extMatch = segment.match(/(\.[a-z0-9]+)$/i);
+        const ext = extMatch ? extMatch[1] : '';
+        const nameWithoutExt = ext ? segment.slice(0, -ext.length) : segment;
+
+        const cleanedName = nameWithoutExt
+          .replace(/[^\p{L}\p{N}$]+/gu, '-')  // Keep route marker "$", dash-separate other chars
+          .replace(/^-+|-+$/g, ''); // Remove leading/trailing dashes
+
+        return cleanedName + ext;
+      } else {
+        // For directories, just clean normally
+        return segment
+          .replace(/[^\p{L}\p{N}$]+/gu, '-')
+          .replace(/^-+|-+$/g, '');
+      }
+    })
+    .filter(Boolean)
+    .join('/');
+
+  if (!result) {
+    throw new Error(`handelize: path "${path}" resulted in empty string after processing`);
+  }
+
+  return result;
+}
+
+/**
+ * Search result extends DocumentResult with score and source info
+ */
+export type SearchResult = DocumentResult & {
+  score: number;              // Relevance score (0-1)
+  source: "fts" | "vec";      // Search source (full-text or vector)
+  chunkPos?: number;          // Character position of matching chunk (for vector search)
+};
+
+/**
+ * Ranked result for RRF fusion (simplified, used internally)
+ */
+export type RankedResult = {
+  file: string;
+  displayPath: string;
+  title: string;
+  body: string;
+  score: number;
+};
+
+/**
+ * Error result when document is not found
+ */
+export type DocumentNotFound = {
+  error: "not_found";
+  query: string;
+  similarFiles: string[];
+};
+
+/**
+ * Result from multi-get operations
+ */
+export type MultiGetResult = {
+  doc: DocumentResult;
+  skipped: false;
+} | {
+  doc: Pick<DocumentResult, "filepath" | "displayPath">;
+  skipped: true;
+  skipReason: string;
+};
+
+export type CollectionInfo = {
+  name: string;
+  path: string;
+  pattern: string;
+  documents: number;
+  lastUpdated: string;
+};
+
+export type IndexStatus = {
+  totalDocuments: number;
+  needsEmbedding: number;
+  hasVectorIndex: boolean;
+  collections: CollectionInfo[];
+};
+
+// =============================================================================
+// Index health
+// =============================================================================
+
+export function getHashesNeedingEmbedding(db: Database): number {
+  const result = db.prepare(`
+    SELECT COUNT(DISTINCT d.hash) as count
+    FROM documents d
+    LEFT JOIN content_vectors v ON d.hash = v.hash AND v.seq = 0
+    WHERE d.active = 1 AND v.hash IS NULL
+  `).get() as { count: number };
+  return result.count;
+}
+
+export type IndexHealthInfo = {
+  needsEmbedding: number;
+  totalDocs: number;
+  daysStale: number | null;
+};
+
+export function getIndexHealth(db: Database): IndexHealthInfo {
+  const needsEmbedding = getHashesNeedingEmbedding(db);
+  const totalDocs = (db.prepare(`SELECT COUNT(*) as count FROM documents WHERE active = 1`).get() as { count: number }).count;
+
+  const mostRecent = db.prepare(`SELECT MAX(modified_at) as latest FROM documents WHERE active = 1`).get() as { latest: string | null };
+  let daysStale: number | null = null;
+  if (mostRecent?.latest) {
+    const lastUpdate = new Date(mostRecent.latest);
+    daysStale = Math.floor((Date.now() - lastUpdate.getTime()) / (24 * 60 * 60 * 1000));
+  }
+
+  return { needsEmbedding, totalDocs, daysStale };
+}
+
+// =============================================================================
+// Caching
+// =============================================================================
+
+export function getCacheKey(url: string, body: object): string {
+  const hash = new Bun.CryptoHasher("sha256");
+  hash.update(url);
+  hash.update(JSON.stringify(body));
+  return hash.digest("hex");
+}
+
+export function getCachedResult(db: Database, cacheKey: string): string | null {
+  const row = db.prepare(`SELECT result FROM llm_cache WHERE hash = ?`).get(cacheKey) as { result: string } | null;
+  return row?.result || null;
+}
+
+export function setCachedResult(db: Database, cacheKey: string, result: string): void {
+  const now = new Date().toISOString();
+  db.prepare(`INSERT OR REPLACE INTO llm_cache (hash, result, created_at) VALUES (?, ?, ?)`).run(cacheKey, result, now);
+  if (Math.random() < 0.01) {
+    db.exec(`DELETE FROM llm_cache WHERE hash NOT IN (SELECT hash FROM llm_cache ORDER BY created_at DESC LIMIT 1000)`);
+  }
+}
+
+export function clearCache(db: Database): void {
+  db.exec(`DELETE FROM llm_cache`);
+}
+
+// =============================================================================
+// Cleanup and maintenance operations
+// =============================================================================
+
+/**
+ * Delete cached LLM API responses.
+ * Returns the number of cached responses deleted.
+ */
+export function deleteLLMCache(db: Database): number {
+  const result = db.prepare(`DELETE FROM llm_cache`).run();
+  return result.changes;
+}
+
+/**
+ * Remove inactive document records (active = 0).
+ * Returns the number of inactive documents deleted.
+ */
+export function deleteInactiveDocuments(db: Database): number {
+  const result = db.prepare(`DELETE FROM documents WHERE active = 0`).run();
+  return result.changes;
+}
+
+/**
+ * Remove orphaned content hashes that are not referenced by any active document.
+ * Returns the number of orphaned content hashes deleted.
+ */
+export function cleanupOrphanedContent(db: Database): number {
+  const result = db.prepare(`
+    DELETE FROM content
+    WHERE hash NOT IN (SELECT DISTINCT hash FROM documents WHERE active = 1)
+  `).run();
+  return result.changes;
+}
+
+/**
+ * Remove orphaned vector embeddings that are not referenced by any active document.
+ * Returns the number of orphaned embedding chunks deleted.
+ */
+export function cleanupOrphanedVectors(db: Database): number {
+  // Check if vectors_vec table exists
+  const tableExists = db.prepare(`
+    SELECT name FROM sqlite_master WHERE type='table' AND name='vectors_vec'
+  `).get();
+
+  if (!tableExists) {
+    return 0;
+  }
+
+  // Count orphaned vectors first
+  const countResult = db.prepare(`
+    SELECT COUNT(*) as c FROM content_vectors cv
+    WHERE NOT EXISTS (
+      SELECT 1 FROM documents d WHERE d.hash = cv.hash AND d.active = 1
+    )
+  `).get() as { c: number };
+
+  if (countResult.c === 0) {
+    return 0;
+  }
+
+  // Delete from vectors_vec first
+  db.exec(`
+    DELETE FROM vectors_vec WHERE hash_seq IN (
+      SELECT cv.hash || '_' || cv.seq FROM content_vectors cv
+      WHERE NOT EXISTS (
+        SELECT 1 FROM documents d WHERE d.hash = cv.hash AND d.active = 1
+      )
+    )
+  `);
+
+  // Delete from content_vectors
+  db.exec(`
+    DELETE FROM content_vectors WHERE hash NOT IN (
+      SELECT hash FROM documents WHERE active = 1
+    )
+  `);
+
+  return countResult.c;
+}
+
+/**
+ * Run VACUUM to reclaim unused space in the database.
+ * This operation rebuilds the database file to eliminate fragmentation.
+ */
+export function vacuumDatabase(db: Database): void {
+  db.exec(`VACUUM`);
+}
+
+// =============================================================================
+// Document helpers
+// =============================================================================
+
+export async function hashContent(content: string): Promise<string> {
+  const hash = new Bun.CryptoHasher("sha256");
+  hash.update(content);
+  return hash.digest("hex");
+}
+
+const titleExtractors: Record<string, (content: string) => string | null> = {
+  '.md': (content) => {
+    const match = content.match(/^##?\s+(.+)$/m);
+    if (match) {
+      const title = (match[1] ?? "").trim();
+      if (title === "📝 Notes" || title === "Notes") {
+        const nextMatch = content.match(/^##\s+(.+)$/m);
+        if (nextMatch?.[1]) return nextMatch[1].trim();
+      }
+      return title;
+    }
+    return null;
+  },
+  '.org': (content) => {
+    const titleProp = content.match(/^#\+TITLE:\s*(.+)$/im);
+    if (titleProp?.[1]) return titleProp[1].trim();
+    const heading = content.match(/^\*+\s+(.+)$/m);
+    if (heading?.[1]) return heading[1].trim();
+    return null;
+  },
+};
+
+export function extractTitle(content: string, filename: string): string {
+  const ext = filename.slice(filename.lastIndexOf('.')).toLowerCase();
+  const extractor = titleExtractors[ext];
+  if (extractor) {
+    const title = extractor(content);
+    if (title) return title;
+  }
+  return filename.replace(/\.[^.]+$/, "").split("/").pop() || filename;
+}
+
+// =============================================================================
+// Document indexing operations
+// =============================================================================
+
+/**
+ * Insert content into the content table (content-addressable storage).
+ * Uses INSERT OR IGNORE so duplicate hashes are skipped.
+ */
+export function insertContent(db: Database, hash: string, content: string, createdAt: string): void {
+  db.prepare(`INSERT OR IGNORE INTO content (hash, doc, created_at) VALUES (?, ?, ?)`)
+    .run(hash, content, createdAt);
+}
+
+/**
+ * Insert a new document into the documents table.
+ */
+export function insertDocument(
+  db: Database,
+  collectionName: string,
+  path: string,
+  title: string,
+  hash: string,
+  createdAt: string,
+  modifiedAt: string
+): void {
+  db.prepare(`
+    INSERT INTO documents (collection, path, title, hash, created_at, modified_at, active)
+    VALUES (?, ?, ?, ?, ?, ?, 1)
+    ON CONFLICT(collection, path) DO UPDATE SET
+      title = excluded.title,
+      hash = excluded.hash,
+      modified_at = excluded.modified_at,
+      active = 1
+  `).run(collectionName, path, title, hash, createdAt, modifiedAt);
+}
+
+/**
+ * Find an active document by collection name and path.
+ */
+export function findActiveDocument(
+  db: Database,
+  collectionName: string,
+  path: string
+): { id: number; hash: string; title: string } | null {
+  return db.prepare(`
+    SELECT id, hash, title FROM documents
+    WHERE collection = ? AND path = ? AND active = 1
+  `).get(collectionName, path) as { id: number; hash: string; title: string } | null;
+}
+
+/**
+ * Update the title and modified_at timestamp for a document.
+ */
+export function updateDocumentTitle(
+  db: Database,
+  documentId: number,
+  title: string,
+  modifiedAt: string
+): void {
+  db.prepare(`UPDATE documents SET title = ?, modified_at = ? WHERE id = ?`)
+    .run(title, modifiedAt, documentId);
+}
+
+/**
+ * Update an existing document's hash, title, and modified_at timestamp.
+ * Used when content changes but the file path stays the same.
+ */
+export function updateDocument(
+  db: Database,
+  documentId: number,
+  title: string,
+  hash: string,
+  modifiedAt: string
+): void {
+  db.prepare(`UPDATE documents SET title = ?, hash = ?, modified_at = ? WHERE id = ?`)
+    .run(title, hash, modifiedAt, documentId);
+}
+
+/**
+ * Deactivate a document (mark as inactive but don't delete).
+ */
+export function deactivateDocument(db: Database, collectionName: string, path: string): void {
+  db.prepare(`UPDATE documents SET active = 0 WHERE collection = ? AND path = ? AND active = 1`)
+    .run(collectionName, path);
+}
+
+/**
+ * Get all active document paths for a collection.
+ */
+export function getActiveDocumentPaths(db: Database, collectionName: string): string[] {
+  const rows = db.prepare(`
+    SELECT path FROM documents WHERE collection = ? AND active = 1
+  `).all(collectionName) as { path: string }[];
+  return rows.map(r => r.path);
+}
+
+export { formatQueryForEmbedding, formatDocForEmbedding };
+
+export function chunkDocument(
+  content: string,
+  maxChars: number = CHUNK_SIZE_CHARS,
+  overlapChars: number = CHUNK_OVERLAP_CHARS,
+  windowChars: number = CHUNK_WINDOW_CHARS
+): { text: string; pos: number }[] {
+  if (content.length <= maxChars) {
+    return [{ text: content, pos: 0 }];
+  }
+
+  // Pre-scan all break points and code fences once
+  const breakPoints = scanBreakPoints(content);
+  const codeFences = findCodeFences(content);
+
+  const chunks: { text: string; pos: number }[] = [];
+  let charPos = 0;
+
+  while (charPos < content.length) {
+    // Calculate target end position for this chunk
+    const targetEndPos = Math.min(charPos + maxChars, content.length);
+
+    let endPos = targetEndPos;
+
+    // If not at the end, find the best break point
+    if (endPos < content.length) {
+      // Find best cutoff using scored algorithm
+      const bestCutoff = findBestCutoff(
+        breakPoints,
+        targetEndPos,
+        windowChars,
+        0.7,
+        codeFences
+      );
+
+      // Only use the cutoff if it's within our current chunk
+      if (bestCutoff > charPos && bestCutoff <= targetEndPos) {
+        endPos = bestCutoff;
+      }
+    }
+
+    // Ensure we make progress
+    if (endPos <= charPos) {
+      endPos = Math.min(charPos + maxChars, content.length);
+    }
+
+    chunks.push({ text: content.slice(charPos, endPos), pos: charPos });
+
+    // Move forward, but overlap with previous chunk
+    // For last chunk, don't overlap (just go to the end)
+    if (endPos >= content.length) {
+      break;
+    }
+    charPos = endPos - overlapChars;
+    const lastChunkPos = chunks.at(-1)!.pos;
+    if (charPos <= lastChunkPos) {
+      // Prevent infinite loop - move forward at least a bit
+      charPos = endPos;
+    }
+  }
+
+  return chunks;
+}
+
+/**
+ * Chunk a document by actual token count using the LLM tokenizer.
+ * More accurate than character-based chunking but requires async.
+ */
+export async function chunkDocumentByTokens(
+  content: string,
+  maxTokens: number = CHUNK_SIZE_TOKENS,
+  overlapTokens: number = CHUNK_OVERLAP_TOKENS,
+  windowTokens: number = CHUNK_WINDOW_TOKENS
+): Promise<{ text: string; pos: number; tokens: number }[]> {
+  const llm = getDefaultLlamaCpp();
+
+  // Use moderate chars/token estimate (prose ~4, code ~2, mixed ~3)
+  // If chunks exceed limit, they'll be re-split with actual ratio
+  const avgCharsPerToken = 3;
+  const maxChars = maxTokens * avgCharsPerToken;
+  const overlapChars = overlapTokens * avgCharsPerToken;
+  const windowChars = windowTokens * avgCharsPerToken;
+
+  // Chunk in character space with conservative estimate
+  let charChunks = chunkDocument(content, maxChars, overlapChars, windowChars);
+
+  // Tokenize and split any chunks that still exceed limit
+  const results: { text: string; pos: number; tokens: number }[] = [];
+
+  for (const chunk of charChunks) {
+    const tokens = await llm.tokenize(chunk.text);
+
+    if (tokens.length <= maxTokens) {
+      results.push({ text: chunk.text, pos: chunk.pos, tokens: tokens.length });
+    } else {
+      // Chunk is still too large - split it further
+      // Use actual token count to estimate better char limit
+      const actualCharsPerToken = chunk.text.length / tokens.length;
+      const safeMaxChars = Math.floor(maxTokens * actualCharsPerToken * 0.95); // 5% safety margin
+
+      const subChunks = chunkDocument(chunk.text, safeMaxChars, Math.floor(overlapChars * actualCharsPerToken / 2), Math.floor(windowChars * actualCharsPerToken / 2));
+
+      for (const subChunk of subChunks) {
+        const subTokens = await llm.tokenize(subChunk.text);
+        results.push({
+          text: subChunk.text,
+          pos: chunk.pos + subChunk.pos,
+          tokens: subTokens.length,
+        });
+      }
+    }
+  }
+
+  return results;
+}
+
+// =============================================================================
+// Fuzzy matching
+// =============================================================================
+
+function levenshtein(a: string, b: string): number {
+  const m = a.length, n = b.length;
+  if (m === 0) return n;
+  if (n === 0) return m;
+  const dp: number[][] = Array.from({ length: m + 1 }, () => Array(n + 1).fill(0));
+  for (let i = 0; i <= m; i++) dp[i]![0] = i;
+  for (let j = 0; j <= n; j++) dp[0]![j] = j;
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      dp[i]![j] = Math.min(
+        dp[i - 1]![j]! + 1,
+        dp[i]![j - 1]! + 1,
+        dp[i - 1]![j - 1]! + cost
+      );
+    }
+  }
+  return dp[m]![n]!;
+}
+
+/**
+ * Normalize a docid input by stripping surrounding quotes and leading #.
+ * Handles: "#abc123", 'abc123', "abc123", #abc123, abc123
+ * Returns the bare hex string.
+ */
+export function normalizeDocid(docid: string): string {
+  let normalized = docid.trim();
+
+  // Strip surrounding quotes (single or double)
+  if ((normalized.startsWith('"') && normalized.endsWith('"')) ||
+      (normalized.startsWith("'") && normalized.endsWith("'"))) {
+    normalized = normalized.slice(1, -1);
+  }
+
+  // Strip leading # if present
+  if (normalized.startsWith('#')) {
+    normalized = normalized.slice(1);
+  }
+
+  return normalized;
+}
+
+/**
+ * Check if a string looks like a docid reference.
+ * Accepts: #abc123, abc123, "#abc123", "abc123", '#abc123', 'abc123'
+ * Returns true if the normalized form is a valid hex string of 6+ chars.
+ */
+export function isDocid(input: string): boolean {
+  const normalized = normalizeDocid(input);
+  // Must be at least 6 hex characters
+  return normalized.length >= 6 && /^[a-f0-9]+$/i.test(normalized);
+}
+
+/**
+ * Find a document by its short docid (first 6 characters of hash).
+ * Returns the document's virtual path if found, null otherwise.
+ * If multiple documents match the same short hash (collision), returns the first one.
+ *
+ * Accepts lenient input: #abc123, abc123, "#abc123", "abc123"
+ */
+export function findDocumentByDocid(db: Database, docid: string): { filepath: string; hash: string } | null {
+  const shortHash = normalizeDocid(docid);
+
+  if (shortHash.length < 1) return null;
+
+  // Look up documents where hash starts with the short hash
+  const doc = db.prepare(`
+    SELECT 'qmd://' || d.collection || '/' || d.path as filepath, d.hash
+    FROM documents d
+    WHERE d.hash LIKE ? AND d.active = 1
+    LIMIT 1
+  `).get(`${shortHash}%`) as { filepath: string; hash: string } | null;
+
+  return doc;
+}
+
+export function findSimilarFiles(db: Database, query: string, maxDistance: number = 3, limit: number = 5): string[] {
+  const allFiles = db.prepare(`
+    SELECT d.path
+    FROM documents d
+    WHERE d.active = 1
+  `).all() as { path: string }[];
+  const queryLower = query.toLowerCase();
+  const scored = allFiles
+    .map(f => ({ path: f.path, dist: levenshtein(f.path.toLowerCase(), queryLower) }))
+    .filter(f => f.dist <= maxDistance)
+    .sort((a, b) => a.dist - b.dist)
+    .slice(0, limit);
+  return scored.map(f => f.path);
+}
+
+export function matchFilesByGlob(db: Database, pattern: string): { filepath: string; displayPath: string; bodyLength: number }[] {
+  const allFiles = db.prepare(`
+    SELECT
+      'qmd://' || d.collection || '/' || d.path as virtual_path,
+      LENGTH(content.doc) as body_length,
+      d.path,
+      d.collection
+    FROM documents d
+    JOIN content ON content.hash = d.hash
+    WHERE d.active = 1
+  `).all() as { virtual_path: string; body_length: number; path: string; collection: string }[];
+
+  const glob = new Glob(pattern);
+  return allFiles
+    .filter(f => glob.match(f.virtual_path) || glob.match(f.path))
+    .map(f => ({
+      filepath: f.virtual_path,  // Virtual path for precise lookup
+      displayPath: f.path,        // Relative path for display
+      bodyLength: f.body_length
+    }));
+}
+
+// =============================================================================
+// Context
+// =============================================================================
+
+/**
+ * Get context for a file path using hierarchical inheritance.
+ * Contexts are collection-scoped and inherit from parent directories.
+ * For example, context at "/talks" applies to "/talks/2024/keynote.md".
+ *
+ * @param db Database instance (unused - kept for compatibility)
+ * @param collectionName Collection name
+ * @param path Relative path within the collection
+ * @returns Context string or null if no context is defined
+ */
+export function getContextForPath(db: Database, collectionName: string, path: string): string | null {
+  const config = collectionsLoadConfig();
+  const coll = getCollection(collectionName);
+
+  if (!coll) return null;
+
+  // Collect ALL matching contexts (global + all path prefixes)
+  const contexts: string[] = [];
+
+  // Add global context if present
+  if (config.global_context) {
+    contexts.push(config.global_context);
+  }
+
+  // Add all matching path contexts (from most general to most specific)
+  if (coll.context) {
+    const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+
+    // Collect all matching prefixes
+    const matchingContexts: { prefix: string; context: string }[] = [];
+    for (const [prefix, context] of Object.entries(coll.context)) {
+      const normalizedPrefix = prefix.startsWith("/") ? prefix : `/${prefix}`;
+      if (normalizedPath.startsWith(normalizedPrefix)) {
+        matchingContexts.push({ prefix: normalizedPrefix, context });
+      }
+    }
+
+    // Sort by prefix length (shortest/most general first)
+    matchingContexts.sort((a, b) => a.prefix.length - b.prefix.length);
+
+    // Add all matching contexts
+    for (const match of matchingContexts) {
+      contexts.push(match.context);
+    }
+  }
+
+  // Join all contexts with double newline
+  return contexts.length > 0 ? contexts.join('\n\n') : null;
+}
+
+/**
+ * Get context for a file path (virtual or filesystem).
+ * Resolves the collection and relative path using the YAML collections config.
+ */
+export function getContextForFile(db: Database, filepath: string): string | null {
+  // Handle undefined or null filepath
+  if (!filepath) return null;
+
+  // Get all collections from YAML config
+  const collections = collectionsListCollections();
+  const config = collectionsLoadConfig();
+
+  // Parse virtual path format: qmd://collection/path
+  let collectionName: string | null = null;
+  let relativePath: string | null = null;
+
+  const parsedVirtual = filepath.startsWith('qmd://') ? parseVirtualPath(filepath) : null;
+  if (parsedVirtual) {
+    collectionName = parsedVirtual.collectionName;
+    relativePath = parsedVirtual.path;
+  } else {
+    // Filesystem path: find which collection this absolute path belongs to
+    for (const coll of collections) {
+      // Skip collections with missing paths
+      if (!coll || !coll.path) continue;
+
+      if (filepath.startsWith(coll.path + '/') || filepath === coll.path) {
+        collectionName = coll.name;
+        // Extract relative path
+        relativePath = filepath.startsWith(coll.path + '/')
+          ? filepath.slice(coll.path.length + 1)
+          : '';
+        break;
+      }
+    }
+
+    if (!collectionName || relativePath === null) return null;
+  }
+
+  // Get the collection from config
+  const coll = getCollection(collectionName);
+  if (!coll) return null;
+
+  // Verify this document exists in the database
+  const doc = db.prepare(`
+    SELECT d.path
+    FROM documents d
+    WHERE d.collection = ? AND d.path = ? AND d.active = 1
+    LIMIT 1
+  `).get(collectionName, relativePath) as { path: string } | null;
+
+  if (!doc) return null;
+
+  // Collect ALL matching contexts (global + all path prefixes)
+  const contexts: string[] = [];
+
+  // Add global context if present
+  if (config.global_context) {
+    contexts.push(config.global_context);
+  }
+
+  // Add all matching path contexts (from most general to most specific)
+  if (coll.context) {
+    const normalizedPath = relativePath.startsWith("/") ? relativePath : `/${relativePath}`;
+
+    // Collect all matching prefixes
+    const matchingContexts: { prefix: string; context: string }[] = [];
+    for (const [prefix, context] of Object.entries(coll.context)) {
+      const normalizedPrefix = prefix.startsWith("/") ? prefix : `/${prefix}`;
+      if (normalizedPath.startsWith(normalizedPrefix)) {
+        matchingContexts.push({ prefix: normalizedPrefix, context });
+      }
+    }
+
+    // Sort by prefix length (shortest/most general first)
+    matchingContexts.sort((a, b) => a.prefix.length - b.prefix.length);
+
+    // Add all matching contexts
+    for (const match of matchingContexts) {
+      contexts.push(match.context);
+    }
+  }
+
+  // Join all contexts with double newline
+  return contexts.length > 0 ? contexts.join('\n\n') : null;
+}
+
+/**
+ * Get collection by name from YAML config.
+ * Returns collection metadata from ~/.config/qmd/index.yml
+ */
+export function getCollectionByName(db: Database, name: string): { name: string; pwd: string; glob_pattern: string } | null {
+  const collection = getCollection(name);
+  if (!collection) return null;
+
+  return {
+    name: collection.name,
+    pwd: collection.path,
+    glob_pattern: collection.pattern,
+  };
+}
+
+/**
+ * List all collections with document counts from database.
+ * Merges YAML config with database statistics.
+ */
+export function listCollections(db: Database): { name: string; pwd: string; glob_pattern: string; doc_count: number; active_count: number; last_modified: string | null }[] {
+  const collections = collectionsListCollections();
+
+  // Get document counts from database for each collection
+  const result = collections.map(coll => {
+    const stats = db.prepare(`
+      SELECT
+        COUNT(d.id) as doc_count,
+        SUM(CASE WHEN d.active = 1 THEN 1 ELSE 0 END) as active_count,
+        MAX(d.modified_at) as last_modified
+      FROM documents d
+      WHERE d.collection = ?
+    `).get(coll.name) as { doc_count: number; active_count: number; last_modified: string | null } | null;
+
+    return {
+      name: coll.name,
+      pwd: coll.path,
+      glob_pattern: coll.pattern,
+      doc_count: stats?.doc_count || 0,
+      active_count: stats?.active_count || 0,
+      last_modified: stats?.last_modified || null,
+    };
+  });
+
+  return result;
+}
+
+/**
+ * Remove a collection and clean up its documents.
+ * Uses collections.ts to remove from YAML config and cleans up database.
+ */
+export function removeCollection(db: Database, collectionName: string): { deletedDocs: number; cleanedHashes: number } {
+  // Delete documents from database
+  const docResult = db.prepare(`DELETE FROM documents WHERE collection = ?`).run(collectionName);
+
+  // Clean up orphaned content hashes
+  const cleanupResult = db.prepare(`
+    DELETE FROM content
+    WHERE hash NOT IN (SELECT DISTINCT hash FROM documents WHERE active = 1)
+  `).run();
+
+  // Remove from YAML config (returns true if found and removed)
+  collectionsRemoveCollection(collectionName);
+
+  return {
+    deletedDocs: docResult.changes,
+    cleanedHashes: cleanupResult.changes
+  };
+}
+
+/**
+ * Rename a collection.
+ * Updates both YAML config and database documents table.
+ */
+export function renameCollection(db: Database, oldName: string, newName: string): void {
+  // Update all documents with the new collection name in database
+  db.prepare(`UPDATE documents SET collection = ? WHERE collection = ?`)
+    .run(newName, oldName);
+
+  // Rename in YAML config
+  collectionsRenameCollection(oldName, newName);
+}
+
+// =============================================================================
+// Context Management Operations
+// =============================================================================
+
+/**
+ * Insert or update a context for a specific collection and path prefix.
+ */
+export function insertContext(db: Database, collectionId: number, pathPrefix: string, context: string): void {
+  // Get collection name from ID
+  const coll = db.prepare(`SELECT name FROM collections WHERE id = ?`).get(collectionId) as { name: string } | null;
+  if (!coll) {
+    throw new Error(`Collection with id ${collectionId} not found`);
+  }
+
+  // Use collections.ts to add context
+  collectionsAddContext(coll.name, pathPrefix, context);
+}
+
+/**
+ * Delete a context for a specific collection and path prefix.
+ * Returns the number of contexts deleted.
+ */
+export function deleteContext(db: Database, collectionName: string, pathPrefix: string): number {
+  // Use collections.ts to remove context
+  const success = collectionsRemoveContext(collectionName, pathPrefix);
+  return success ? 1 : 0;
+}
+
+/**
+ * Delete all global contexts (contexts with empty path_prefix).
+ * Returns the number of contexts deleted.
+ */
+export function deleteGlobalContexts(db: Database): number {
+  let deletedCount = 0;
+
+  // Remove global context
+  setGlobalContext(undefined);
+  deletedCount++;
+
+  // Remove root context (empty string) from all collections
+  const collections = collectionsListCollections();
+  for (const coll of collections) {
+    const success = collectionsRemoveContext(coll.name, '');
+    if (success) {
+      deletedCount++;
+    }
+  }
+
+  return deletedCount;
+}
+
+/**
+ * List all contexts, grouped by collection.
+ * Returns contexts ordered by collection name, then by path prefix length (longest first).
+ */
+export function listPathContexts(db: Database): { collection_name: string; path_prefix: string; context: string }[] {
+  const allContexts = collectionsListAllContexts();
+
+  // Convert to expected format and sort
+  return allContexts.map(ctx => ({
+    collection_name: ctx.collection,
+    path_prefix: ctx.path,
+    context: ctx.context,
+  })).sort((a, b) => {
+    // Sort by collection name first
+    if (a.collection_name !== b.collection_name) {
+      return a.collection_name.localeCompare(b.collection_name);
+    }
+    // Then by path prefix length (longest first)
+    if (a.path_prefix.length !== b.path_prefix.length) {
+      return b.path_prefix.length - a.path_prefix.length;
+    }
+    // Then alphabetically
+    return a.path_prefix.localeCompare(b.path_prefix);
+  });
+}
+
+/**
+ * Get all collections (name only - from YAML config).
+ */
+export function getAllCollections(db: Database): { name: string }[] {
+  const collections = collectionsListCollections();
+  return collections.map(c => ({ name: c.name }));
+}
+
+/**
+ * Check which collections don't have any context defined.
+ * Returns collections that have no context entries at all (not even root context).
+ */
+export function getCollectionsWithoutContext(db: Database): { name: string; pwd: string; doc_count: number }[] {
+  // Get all collections from YAML config
+  const yamlCollections = collectionsListCollections();
+
+  // Filter to those without context
+  const collectionsWithoutContext: { name: string; pwd: string; doc_count: number }[] = [];
+
+  for (const coll of yamlCollections) {
+    // Check if collection has any context
+    if (!coll.context || Object.keys(coll.context).length === 0) {
+      // Get doc count from database
+      const stats = db.prepare(`
+        SELECT COUNT(d.id) as doc_count
+        FROM documents d
+        WHERE d.collection = ? AND d.active = 1
+      `).get(coll.name) as { doc_count: number } | null;
+
+      collectionsWithoutContext.push({
+        name: coll.name,
+        pwd: coll.path,
+        doc_count: stats?.doc_count || 0,
+      });
+    }
+  }
+
+  return collectionsWithoutContext.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * Get top-level directories in a collection that don't have context.
+ * Useful for suggesting where context might be needed.
+ */
+export function getTopLevelPathsWithoutContext(db: Database, collectionName: string): string[] {
+  // Get all paths in the collection from database
+  const paths = db.prepare(`
+    SELECT DISTINCT path FROM documents
+    WHERE collection = ? AND active = 1
+  `).all(collectionName) as { path: string }[];
+
+  // Get existing contexts for this collection from YAML
+  const yamlColl = getCollection(collectionName);
+  if (!yamlColl) return [];
+
+  const contextPrefixes = new Set<string>();
+  if (yamlColl.context) {
+    for (const prefix of Object.keys(yamlColl.context)) {
+      contextPrefixes.add(prefix);
+    }
+  }
+
+  // Extract top-level directories (first path component)
+  const topLevelDirs = new Set<string>();
+  for (const { path } of paths) {
+    const parts = path.split('/').filter(Boolean);
+    if (parts.length > 1) {
+      const dir = parts[0];
+      if (dir) topLevelDirs.add(dir);
+    }
+  }
+
+  // Filter out directories that already have context (exact or parent)
+  const missing: string[] = [];
+  for (const dir of topLevelDirs) {
+    let hasContext = false;
+
+    // Check if this dir or any parent has context
+    for (const prefix of contextPrefixes) {
+      if (prefix === '' || prefix === dir || dir.startsWith(prefix + '/')) {
+        hasContext = true;
+        break;
+      }
+    }
+
+    if (!hasContext) {
+      missing.push(dir);
+    }
+  }
+
+  return missing.sort();
+}
+
+// =============================================================================
+// FTS Search
+// =============================================================================
+
+function sanitizeFTS5Term(term: string): string {
+  return term.replace(/[^\p{L}\p{N}']/gu, '').toLowerCase();
+}
+
+function buildFTS5Query(query: string): string | null {
+  const terms = query.split(/\s+/)
+    .map(t => sanitizeFTS5Term(t))
+    .filter(t => t.length > 0);
+  if (terms.length === 0) return null;
+  if (terms.length === 1) return `"${terms[0]}"*`;
+  return terms.map(t => `"${t}"*`).join(' AND ');
+}
+
+export function searchFTS(db: Database, query: string, limit: number = 20, collectionId?: number): SearchResult[] {
+  const ftsQuery = buildFTS5Query(query);
+  if (!ftsQuery) return [];
+
+  let sql = `
+    SELECT
+      'qmd://' || d.collection || '/' || d.path as filepath,
+      d.collection || '/' || d.path as display_path,
+      d.title,
+      content.doc as body,
+      d.hash,
+      bm25(documents_fts, 10.0, 1.0) as bm25_score
+    FROM documents_fts f
+    JOIN documents d ON d.id = f.rowid
+    JOIN content ON content.hash = d.hash
+    WHERE documents_fts MATCH ? AND d.active = 1
+  `;
+  const params: (string | number)[] = [ftsQuery];
+
+  if (collectionId) {
+    // Note: collectionId is a legacy parameter that should be phased out
+    // Collections are now managed in YAML. For now, we interpret it as a collection name filter.
+    // This code path is likely unused as collection filtering should be done at CLI level.
+    sql += ` AND d.collection = ?`;
+    params.push(String(collectionId));
+  }
+
+  // bm25 lower is better; sort ascending.
+  sql += ` ORDER BY bm25_score ASC LIMIT ?`;
+  params.push(limit);
+
+  const rows = db.prepare(sql).all(...params) as { filepath: string; display_path: string; title: string; body: string; hash: string; bm25_score: number }[];
+  return rows.map(row => {
+    const collectionName = row.filepath.split('//')[1]?.split('/')[0] || "";
+    // Convert bm25 (negative, lower is better) into a stable [0..1) score where higher is better.
+    // FTS5 BM25 scores are negative (e.g., -10 is strong, -2 is weak).
+    // |x| / (1 + |x|) maps: strong(-10)→0.91, medium(-2)→0.67, weak(-0.5)→0.33, none(0)→0.
+    // Monotonic and query-independent — no per-query normalization needed.
+    const score = Math.abs(row.bm25_score) / (1 + Math.abs(row.bm25_score));
+    return {
+      filepath: row.filepath,
+      displayPath: row.display_path,
+      title: row.title,
+      hash: row.hash,
+      docid: getDocid(row.hash),
+      collectionName,
+      modifiedAt: "",  // Not available in FTS query
+      bodyLength: row.body.length,
+      body: row.body,
+      context: getContextForFile(db, row.filepath),
+      score,
+      source: "fts" as const,
+    };
+  });
+}
+
+// =============================================================================
+// Vector Search
+// =============================================================================
+
+export async function searchVec(db: Database, query: string, model: string, limit: number = 20, collectionName?: string, session?: ILLMSession): Promise<SearchResult[]> {
+  const tableExists = db.prepare(`SELECT name FROM sqlite_master WHERE type='table' AND name='vectors_vec'`).get();
+  if (!tableExists) return [];
+
+  const embedding = await getEmbedding(query, model, true, session);
+  if (!embedding) return [];
+
+  // IMPORTANT: We use a two-step query approach here because sqlite-vec virtual tables
+  // hang indefinitely when combined with JOINs in the same query. Do NOT try to
+  // "optimize" this by combining into a single query with JOINs - it will break.
+  // See: https://github.com/tobi/qmd/pull/23
+
+  // Step 1: Get vector matches from sqlite-vec (no JOINs allowed)
+  const vecResults = db.prepare(`
+    SELECT hash_seq, distance
+    FROM vectors_vec
+    WHERE embedding MATCH ? AND k = ?
+  `).all(new Float32Array(embedding), limit * 3) as { hash_seq: string; distance: number }[];
+
+  if (vecResults.length === 0) return [];
+
+  // Step 2: Get chunk info and document data
+  const hashSeqs = vecResults.map(r => r.hash_seq);
+  const distanceMap = new Map(vecResults.map(r => [r.hash_seq, r.distance]));
+
+  // Build query for document lookup
+  const placeholders = hashSeqs.map(() => '?').join(',');
+  let docSql = `
+    SELECT
+      cv.hash || '_' || cv.seq as hash_seq,
+      cv.hash,
+      cv.pos,
+      'qmd://' || d.collection || '/' || d.path as filepath,
+      d.collection || '/' || d.path as display_path,
+      d.title,
+      content.doc as body
+    FROM content_vectors cv
+    JOIN documents d ON d.hash = cv.hash AND d.active = 1
+    JOIN content ON content.hash = d.hash
+    WHERE cv.hash || '_' || cv.seq IN (${placeholders})
+  `;
+  const params: string[] = [...hashSeqs];
+
+  if (collectionName) {
+    docSql += ` AND d.collection = ?`;
+    params.push(collectionName);
+  }
+
+  const docRows = db.prepare(docSql).all(...params) as {
+    hash_seq: string; hash: string; pos: number; filepath: string;
+    display_path: string; title: string; body: string;
+  }[];
+
+  // Combine with distances and dedupe by filepath
+  const seen = new Map<string, { row: typeof docRows[0]; bestDist: number }>();
+  for (const row of docRows) {
+    const distance = distanceMap.get(row.hash_seq) ?? 1;
+    const existing = seen.get(row.filepath);
+    if (!existing || distance < existing.bestDist) {
+      seen.set(row.filepath, { row, bestDist: distance });
+    }
+  }
+
+  return Array.from(seen.values())
+    .sort((a, b) => a.bestDist - b.bestDist)
+    .slice(0, limit)
+    .map(({ row, bestDist }) => {
+      const collectionName = row.filepath.split('//')[1]?.split('/')[0] || "";
+      return {
+        filepath: row.filepath,
+        displayPath: row.display_path,
+        title: row.title,
+        hash: row.hash,
+        docid: getDocid(row.hash),
+        collectionName,
+        modifiedAt: "",  // Not available in vec query
+        bodyLength: row.body.length,
+        body: row.body,
+        context: getContextForFile(db, row.filepath),
+        score: 1 - bestDist,  // Cosine similarity = 1 - cosine distance
+        source: "vec" as const,
+        chunkPos: row.pos,
+      };
+    });
+}
+
+// =============================================================================
+// Embeddings
+// =============================================================================
+
+async function getEmbedding(text: string, model: string, isQuery: boolean, session?: ILLMSession): Promise<number[] | null> {
+  // Format text using the appropriate prompt template
+  const formattedText = isQuery ? formatQueryForEmbedding(text) : formatDocForEmbedding(text);
+  const result = session
+    ? await session.embed(formattedText, { model, isQuery })
+    : await getDefaultLlamaCpp().embed(formattedText, { model, isQuery });
+  return result?.embedding || null;
+}
+
+/**
+ * Get all unique content hashes that need embeddings (from active documents).
+ * Returns hash, document body, and a sample path for display purposes.
+ */
+export function getHashesForEmbedding(db: Database): { hash: string; body: string; path: string }[] {
+  return db.prepare(`
+    SELECT d.hash, c.doc as body, MIN(d.path) as path
+    FROM documents d
+    JOIN content c ON d.hash = c.hash
+    LEFT JOIN content_vectors v ON d.hash = v.hash AND v.seq = 0
+    WHERE d.active = 1 AND v.hash IS NULL
+    GROUP BY d.hash
+  `).all() as { hash: string; body: string; path: string }[];
+}
+
+/**
+ * Clear all embeddings from the database (force re-index).
+ * Deletes all rows from content_vectors and drops the vectors_vec table.
+ */
+export function clearAllEmbeddings(db: Database): void {
+  db.exec(`DELETE FROM content_vectors`);
+  db.exec(`DROP TABLE IF EXISTS vectors_vec`);
+}
+
+/**
+ * Insert a single embedding into both content_vectors and vectors_vec tables.
+ * The hash_seq key is formatted as "hash_seq" for the vectors_vec table.
+ */
+export function insertEmbedding(
+  db: Database,
+  hash: string,
+  seq: number,
+  pos: number,
+  embedding: Float32Array,
+  model: string,
+  embeddedAt: string
+): void {
+  const hashSeq = `${hash}_${seq}`;
+  const insertVecStmt = db.prepare(`INSERT OR REPLACE INTO vectors_vec (hash_seq, embedding) VALUES (?, ?)`);
+  const insertContentVectorStmt = db.prepare(`INSERT OR REPLACE INTO content_vectors (hash, seq, pos, model, embedded_at) VALUES (?, ?, ?, ?, ?)`);
+
+  insertVecStmt.run(hashSeq, embedding);
+  insertContentVectorStmt.run(hash, seq, pos, model, embeddedAt);
+}
+
+// =============================================================================
+// Query expansion
+// =============================================================================
+
+export async function expandQuery(query: string, model: string = DEFAULT_QUERY_MODEL, db: Database): Promise<ExpandedQuery[]> {
+  // Check cache first — stored as JSON preserving types
+  const cacheKey = getCacheKey("expandQuery", { query, model });
+  const cached = getCachedResult(db, cacheKey);
+  if (cached) {
+    try {
+      return JSON.parse(cached) as ExpandedQuery[];
+    } catch {
+      // Old cache format (pre-typed, newline-separated text) — re-expand
+    }
+  }
+
+  const llm = getDefaultLlamaCpp();
+  // Note: LlamaCpp uses hardcoded model, model parameter is ignored
+  const results = await llm.expandQuery(query);
+
+  // Map Queryable[] → ExpandedQuery[] (same shape, decoupled from llm.ts internals).
+  // Filter out entries that duplicate the original query text.
+  const expanded: ExpandedQuery[] = results
+    .filter(r => r.text !== query)
+    .map(r => ({ type: r.type, text: r.text }));
+
+  if (expanded.length > 0) {
+    setCachedResult(db, cacheKey, JSON.stringify(expanded));
+  }
+
+  return expanded;
+}
+
+// =============================================================================
+// Reranking
+// =============================================================================
+
+export async function rerank(query: string, documents: { file: string; text: string }[], model: string = DEFAULT_RERANK_MODEL, db: Database): Promise<{ file: string; score: number }[]> {
+  const cachedResults: Map<string, number> = new Map();
+  const uncachedDocs: RerankDocument[] = [];
+
+  // Check cache for each document
+  // Cache key includes chunk text — different queries can select different chunks
+  // from the same file, and the reranker score depends on which chunk was sent.
+  for (const doc of documents) {
+    const cacheKey = getCacheKey("rerank", { query, file: doc.file, model, chunk: doc.text });
+    const cached = getCachedResult(db, cacheKey);
+    if (cached !== null) {
+      cachedResults.set(doc.file, parseFloat(cached));
+    } else {
+      uncachedDocs.push({ file: doc.file, text: doc.text });
+    }
+  }
+
+  // Rerank uncached documents using LlamaCpp
+  if (uncachedDocs.length > 0) {
+    const llm = getDefaultLlamaCpp();
+    const rerankResult = await llm.rerank(query, uncachedDocs, { model });
+
+    // Cache results — use original doc.text for cache key (result.file lacks chunk text)
+    const textByFile = new Map(documents.map(d => [d.file, d.text]));
+    for (const result of rerankResult.results) {
+      const cacheKey = getCacheKey("rerank", { query, file: result.file, model, chunk: textByFile.get(result.file) || "" });
+      setCachedResult(db, cacheKey, result.score.toString());
+      cachedResults.set(result.file, result.score);
+    }
+  }
+
+  // Return all results sorted by score
+  return documents
+    .map(doc => ({ file: doc.file, score: cachedResults.get(doc.file) || 0 }))
+    .sort((a, b) => b.score - a.score);
+}
+
+// =============================================================================
+// Reciprocal Rank Fusion
+// =============================================================================
+
+export function reciprocalRankFusion(
+  resultLists: RankedResult[][],
+  weights: number[] = [],
+  k: number = 60
+): RankedResult[] {
+  const scores = new Map<string, { result: RankedResult; rrfScore: number; topRank: number }>();
+
+  for (let listIdx = 0; listIdx < resultLists.length; listIdx++) {
+    const list = resultLists[listIdx];
+    if (!list) continue;
+    const weight = weights[listIdx] ?? 1.0;
+
+    for (let rank = 0; rank < list.length; rank++) {
+      const result = list[rank];
+      if (!result) continue;
+      const rrfContribution = weight / (k + rank + 1);
+      const existing = scores.get(result.file);
+
+      if (existing) {
+        existing.rrfScore += rrfContribution;
+        existing.topRank = Math.min(existing.topRank, rank);
+      } else {
+        scores.set(result.file, {
+          result,
+          rrfScore: rrfContribution,
+          topRank: rank,
+        });
+      }
+    }
+  }
+
+  // Top-rank bonus
+  for (const entry of scores.values()) {
+    if (entry.topRank === 0) {
+      entry.rrfScore += 0.05;
+    } else if (entry.topRank <= 2) {
+      entry.rrfScore += 0.02;
+    }
+  }
+
+  return Array.from(scores.values())
+    .sort((a, b) => b.rrfScore - a.rrfScore)
+    .map(e => ({ ...e.result, score: e.rrfScore }));
+}
+
+// =============================================================================
+// Document retrieval
+// =============================================================================
+
+type DbDocRow = {
+  virtual_path: string;
+  display_path: string;
+  title: string;
+  hash: string;
+  collection: string;
+  path: string;
+  modified_at: string;
+  body_length: number;
+  body?: string;
+};
+
+/**
+ * Find a document by filename/path, docid (#hash), or with fuzzy matching.
+ * Returns document metadata without body by default.
+ *
+ * Supports:
+ * - Virtual paths: qmd://collection/path/to/file.md
+ * - Absolute paths: /path/to/file.md
+ * - Relative paths: path/to/file.md
+ * - Short docid: #abc123 (first 6 chars of hash)
+ */
+export function findDocument(db: Database, filename: string, options: { includeBody?: boolean } = {}): DocumentResult | DocumentNotFound {
+  let filepath = filename;
+  const colonMatch = filepath.match(/:(\d+)$/);
+  if (colonMatch) {
+    filepath = filepath.slice(0, -colonMatch[0].length);
+  }
+
+  // Check if this is a docid lookup (#abc123, abc123, "#abc123", "abc123", etc.)
+  if (isDocid(filepath)) {
+    const docidMatch = findDocumentByDocid(db, filepath);
+    if (docidMatch) {
+      filepath = docidMatch.filepath;
+    } else {
+      return { error: "not_found", query: filename, similarFiles: [] };
+    }
+  }
+
+  if (filepath.startsWith('~/')) {
+    filepath = homedir() + filepath.slice(1);
+  }
+
+  const bodyCol = options.includeBody ? `, content.doc as body` : ``;
+
+  // Build computed columns
+  // Note: absoluteFilepath is computed from YAML collections after query
+  const selectCols = `
+    'qmd://' || d.collection || '/' || d.path as virtual_path,
+    d.collection || '/' || d.path as display_path,
+    d.title,
+    d.hash,
+    d.collection,
+    d.modified_at,
+    LENGTH(content.doc) as body_length
+    ${bodyCol}
+  `;
+
+  // Try to match by virtual path first
+  let doc = db.prepare(`
+    SELECT ${selectCols}
+    FROM documents d
+    JOIN content ON content.hash = d.hash
+    WHERE 'qmd://' || d.collection || '/' || d.path = ? AND d.active = 1
+  `).get(filepath) as DbDocRow | null;
+
+  // Try fuzzy match by virtual path
+  if (!doc) {
+    doc = db.prepare(`
+      SELECT ${selectCols}
+      FROM documents d
+      JOIN content ON content.hash = d.hash
+      WHERE 'qmd://' || d.collection || '/' || d.path LIKE ? AND d.active = 1
+      LIMIT 1
+    `).get(`%${filepath}`) as DbDocRow | null;
+  }
+
+  // Try to match by absolute path (requires looking up collection paths from YAML)
+  if (!doc && !filepath.startsWith('qmd://')) {
+    const collections = collectionsListCollections();
+    for (const coll of collections) {
+      let relativePath: string | null = null;
+
+      // If filepath is absolute and starts with collection path, extract relative part
+      if (filepath.startsWith(coll.path + '/')) {
+        relativePath = filepath.slice(coll.path.length + 1);
+      }
+      // Otherwise treat filepath as relative to collection
+      else if (!filepath.startsWith('/')) {
+        relativePath = filepath;
+      }
+
+      if (relativePath) {
+        doc = db.prepare(`
+          SELECT ${selectCols}
+          FROM documents d
+          JOIN content ON content.hash = d.hash
+          WHERE d.collection = ? AND d.path = ? AND d.active = 1
+        `).get(coll.name, relativePath) as DbDocRow | null;
+        if (doc) break;
+      }
+    }
+  }
+
+  if (!doc) {
+    const similar = findSimilarFiles(db, filepath, 5, 5);
+    return { error: "not_found", query: filename, similarFiles: similar };
+  }
+
+  // Get context using virtual path
+  const virtualPath = doc.virtual_path || `qmd://${doc.collection}/${doc.display_path}`;
+  const context = getContextForFile(db, virtualPath);
+
+  return {
+    filepath: virtualPath,
+    displayPath: doc.display_path,
+    title: doc.title,
+    context,
+    hash: doc.hash,
+    docid: getDocid(doc.hash),
+    collectionName: doc.collection,
+    modifiedAt: doc.modified_at,
+    bodyLength: doc.body_length,
+    ...(options.includeBody && doc.body !== undefined && { body: doc.body }),
+  };
+}
+
+/**
+ * Get the body content for a document
+ * Optionally slice by line range
+ */
+export function getDocumentBody(db: Database, doc: DocumentResult | { filepath: string }, fromLine?: number, maxLines?: number): string | null {
+  const filepath = doc.filepath;
+
+  // Try to resolve document by filepath (absolute or virtual)
+  let row: { body: string } | null = null;
+
+  // Try virtual path first
+  if (filepath.startsWith('qmd://')) {
+    row = db.prepare(`
+      SELECT content.doc as body
+      FROM documents d
+      JOIN content ON content.hash = d.hash
+      WHERE 'qmd://' || d.collection || '/' || d.path = ? AND d.active = 1
+    `).get(filepath) as { body: string } | null;
+  }
+
+  // Try absolute path by looking up in YAML collections
+  if (!row) {
+    const collections = collectionsListCollections();
+    for (const coll of collections) {
+      if (filepath.startsWith(coll.path + '/')) {
+        const relativePath = filepath.slice(coll.path.length + 1);
+        row = db.prepare(`
+          SELECT content.doc as body
+          FROM documents d
+          JOIN content ON content.hash = d.hash
+          WHERE d.collection = ? AND d.path = ? AND d.active = 1
+        `).get(coll.name, relativePath) as { body: string } | null;
+        if (row) break;
+      }
+    }
+  }
+
+  if (!row) return null;
+
+  let body = row.body;
+  if (fromLine !== undefined || maxLines !== undefined) {
+    const lines = body.split('\n');
+    const start = (fromLine || 1) - 1;
+    const end = maxLines !== undefined ? start + maxLines : lines.length;
+    body = lines.slice(start, end).join('\n');
+  }
+
+  return body;
+}
+
+/**
+ * Find multiple documents by glob pattern or comma-separated list
+ * Returns documents without body by default (use getDocumentBody to load)
+ */
+export function findDocuments(
+  db: Database,
+  pattern: string,
+  options: { includeBody?: boolean; maxBytes?: number } = {}
+): { docs: MultiGetResult[]; errors: string[] } {
+  const isCommaSeparated = pattern.includes(',') && !pattern.includes('*') && !pattern.includes('?');
+  const errors: string[] = [];
+  const maxBytes = options.maxBytes ?? DEFAULT_MULTI_GET_MAX_BYTES;
+
+  const bodyCol = options.includeBody ? `, content.doc as body` : ``;
+  const selectCols = `
+    'qmd://' || d.collection || '/' || d.path as virtual_path,
+    d.collection || '/' || d.path as display_path,
+    d.title,
+    d.hash,
+    d.collection,
+    d.modified_at,
+    LENGTH(content.doc) as body_length
+    ${bodyCol}
+  `;
+
+  let fileRows: DbDocRow[];
+
+  if (isCommaSeparated) {
+    const names = pattern.split(',').map(s => s.trim()).filter(Boolean);
+    fileRows = [];
+    for (const name of names) {
+      let doc = db.prepare(`
+        SELECT ${selectCols}
+        FROM documents d
+        JOIN content ON content.hash = d.hash
+        WHERE 'qmd://' || d.collection || '/' || d.path = ? AND d.active = 1
+      `).get(name) as DbDocRow | null;
+      if (!doc) {
+        doc = db.prepare(`
+          SELECT ${selectCols}
+          FROM documents d
+          JOIN content ON content.hash = d.hash
+          WHERE 'qmd://' || d.collection || '/' || d.path LIKE ? AND d.active = 1
+          LIMIT 1
+        `).get(`%${name}`) as DbDocRow | null;
+      }
+      if (doc) {
+        fileRows.push(doc);
+      } else {
+        const similar = findSimilarFiles(db, name, 5, 3);
+        let msg = `File not found: ${name}`;
+        if (similar.length > 0) {
+          msg += ` (did you mean: ${similar.join(', ')}?)`;
+        }
+        errors.push(msg);
+      }
+    }
+  } else {
+    // Glob pattern match
+    const matched = matchFilesByGlob(db, pattern);
+    if (matched.length === 0) {
+      errors.push(`No files matched pattern: ${pattern}`);
+      return { docs: [], errors };
+    }
+    const virtualPaths = matched.map(m => m.filepath);
+    const placeholders = virtualPaths.map(() => '?').join(',');
+    fileRows = db.prepare(`
+      SELECT ${selectCols}
+      FROM documents d
+      JOIN content ON content.hash = d.hash
+      WHERE 'qmd://' || d.collection || '/' || d.path IN (${placeholders}) AND d.active = 1
+    `).all(...virtualPaths) as DbDocRow[];
+  }
+
+  const results: MultiGetResult[] = [];
+
+  for (const row of fileRows) {
+    // Get context using virtual path
+    const virtualPath = row.virtual_path || `qmd://${row.collection}/${row.display_path}`;
+    const context = getContextForFile(db, virtualPath);
+
+    if (row.body_length > maxBytes) {
+      results.push({
+        doc: { filepath: virtualPath, displayPath: row.display_path },
+        skipped: true,
+        skipReason: `File too large (${Math.round(row.body_length / 1024)}KB > ${Math.round(maxBytes / 1024)}KB)`,
+      });
+      continue;
+    }
+
+    results.push({
+      doc: {
+        filepath: virtualPath,
+        displayPath: row.display_path,
+        title: row.title || row.display_path.split('/').pop() || row.display_path,
+        context,
+        hash: row.hash,
+        docid: getDocid(row.hash),
+        collectionName: row.collection,
+        modifiedAt: row.modified_at,
+        bodyLength: row.body_length,
+        ...(options.includeBody && row.body !== undefined && { body: row.body }),
+      },
+      skipped: false,
+    });
+  }
+
+  return { docs: results, errors };
+}
+
+// =============================================================================
+// Status
+// =============================================================================
+
+export function getStatus(db: Database): IndexStatus {
+  // Load collections from YAML
+  const yamlCollections = collectionsListCollections();
+
+  // Get document counts and last update times for each collection
+  const collections = yamlCollections.map(col => {
+    const stats = db.prepare(`
+      SELECT
+        COUNT(*) as active_count,
+        MAX(modified_at) as last_doc_update
+      FROM documents
+      WHERE collection = ? AND active = 1
+    `).get(col.name) as { active_count: number; last_doc_update: string | null };
+
+    return {
+      name: col.name,
+      path: col.path,
+      pattern: col.pattern,
+      documents: stats.active_count,
+      lastUpdated: stats.last_doc_update || new Date().toISOString(),
+    };
+  });
+
+  // Sort by last update time (most recent first)
+  collections.sort((a, b) => {
+    if (!a.lastUpdated) return 1;
+    if (!b.lastUpdated) return -1;
+    return new Date(b.lastUpdated).getTime() - new Date(a.lastUpdated).getTime();
+  });
+
+  const totalDocs = (db.prepare(`SELECT COUNT(*) as c FROM documents WHERE active = 1`).get() as { c: number }).c;
+  const needsEmbedding = getHashesNeedingEmbedding(db);
+  const hasVectors = !!db.prepare(`SELECT name FROM sqlite_master WHERE type='table' AND name='vectors_vec'`).get();
+
+  return {
+    totalDocuments: totalDocs,
+    needsEmbedding,
+    hasVectorIndex: hasVectors,
+    collections,
+  };
+}
+
+// =============================================================================
+// Snippet extraction
+// =============================================================================
+
+export type SnippetResult = {
+  line: number;           // 1-indexed line number of best match
+  snippet: string;        // The snippet text with diff-style header
+  linesBefore: number;    // Lines in document before snippet
+  linesAfter: number;     // Lines in document after snippet
+  snippetLines: number;   // Number of lines in snippet
+};
+
+export function extractSnippet(body: string, query: string, maxLen = 500, chunkPos?: number, chunkLen?: number): SnippetResult {
+  const totalLines = body.split('\n').length;
+  let searchBody = body;
+  let lineOffset = 0;
+
+  if (chunkPos && chunkPos > 0) {
+    // Search within the chunk region, with some padding for context
+    // Use provided chunkLen or fall back to max chunk size (covers variable-length chunks)
+    const searchLen = chunkLen || CHUNK_SIZE_CHARS;
+    const contextStart = Math.max(0, chunkPos - 100);
+    const contextEnd = Math.min(body.length, chunkPos + searchLen + 100);
+    searchBody = body.slice(contextStart, contextEnd);
+    if (contextStart > 0) {
+      lineOffset = body.slice(0, contextStart).split('\n').length - 1;
+    }
+  }
+
+  const lines = searchBody.split('\n');
+  const queryTerms = query.toLowerCase().split(/\s+/).filter(t => t.length > 0);
+  let bestLine = 0, bestScore = -1;
+
+  for (let i = 0; i < lines.length; i++) {
+    const lineLower = (lines[i] ?? "").toLowerCase();
+    let score = 0;
+    for (const term of queryTerms) {
+      if (lineLower.includes(term)) score++;
+    }
+    if (score > bestScore) {
+      bestScore = score;
+      bestLine = i;
+    }
+  }
+
+  const start = Math.max(0, bestLine - 1);
+  const end = Math.min(lines.length, bestLine + 3);
+  const snippetLines = lines.slice(start, end);
+  let snippetText = snippetLines.join('\n');
+
+  // If we focused on a chunk window and it produced an empty/whitespace-only snippet,
+  // fall back to a full-document snippet so we always show something useful.
+  if (chunkPos && chunkPos > 0 && snippetText.trim().length === 0) {
+    return extractSnippet(body, query, maxLen, undefined);
+  }
+
+  if (snippetText.length > maxLen) snippetText = snippetText.substring(0, maxLen - 3) + "...";
+
+  const absoluteStart = lineOffset + start + 1; // 1-indexed
+  const snippetLineCount = snippetLines.length;
+  const linesBefore = absoluteStart - 1;
+  const linesAfter = totalLines - (absoluteStart + snippetLineCount - 1);
+
+  // Format with diff-style header: @@ -start,count @@ (linesBefore before, linesAfter after)
+  const header = `@@ -${absoluteStart},${snippetLineCount} @@ (${linesBefore} before, ${linesAfter} after)`;
+  const snippet = `${header}\n${snippetText}`;
+
+  return {
+    line: lineOffset + bestLine + 1,
+    snippet,
+    linesBefore,
+    linesAfter,
+    snippetLines: snippetLineCount,
+  };
+}
+
+// =============================================================================
+// Shared helpers (used by both CLI and MCP)
+// =============================================================================
+
+/**
+ * Add line numbers to text content.
+ * Each line becomes: "{lineNum}: {content}"
+ */
+export function addLineNumbers(text: string, startLine: number = 1): string {
+  const lines = text.split('\n');
+  return lines.map((line, i) => `${startLine + i}: ${line}`).join('\n');
+}
+
+// =============================================================================
+// Shared search orchestration
+//
+// hybridQuery() and vectorSearchQuery() are standalone functions (not Store
+// methods) because they are orchestration over primitives — same rationale as
+// reciprocalRankFusion(). They take a Store as first argument so both CLI
+// and MCP can share the identical pipeline.
+// =============================================================================
+
+/**
+ * Optional progress hooks for search orchestration.
+ * CLI wires these to stderr for user feedback; MCP leaves them unset.
+ */
+export interface SearchHooks {
+  /** BM25 probe found strong signal — expansion will be skipped */
+  onStrongSignal?: (topScore: number) => void;
+  /** Query expansion complete. Empty array = strong signal skip (no expansion). */
+  onExpand?: (original: string, expanded: ExpandedQuery[]) => void;
+  /** Reranking is about to start */
+  onRerankStart?: (chunkCount: number) => void;
+  /** Reranking finished */
+  onRerankDone?: () => void;
+}
+
+export interface HybridQueryOptions {
+  collection?: string;
+  limit?: number;           // default 10
+  minScore?: number;        // default 0
+  candidateLimit?: number;  // default RERANK_CANDIDATE_LIMIT
+  hooks?: SearchHooks;
+}
+
+export interface HybridQueryResult {
+  file: string;             // internal filepath (qmd://collection/path)
+  displayPath: string;
+  title: string;
+  body: string;             // full document body (for snippet extraction)
+  bestChunk: string;        // best chunk text
+  bestChunkPos: number;     // char offset of best chunk in body
+  score: number;            // blended score (full precision)
+  context: string | null;   // user-set context
+  docid: string;            // content hash prefix (6 chars)
+}
+
+/**
+ * Hybrid search: BM25 + vector + query expansion + RRF + chunked reranking.
+ *
+ * Pipeline:
+ * 1. BM25 probe → skip expansion if strong signal
+ * 2. expandQuery() → typed query variants (lex/vec/hyde)
+ * 3. Type-routed search: original→vector, lex→FTS, vec/hyde→vector
+ * 4. RRF fusion → slice to candidateLimit
+ * 5. chunkDocument() + keyword-best-chunk selection
+ * 6. rerank on chunks (NOT full bodies — O(tokens) trap)
+ * 7. Position-aware score blending (RRF rank × reranker score)
+ * 8. Dedup by file, filter by minScore, slice to limit
+ */
+export async function hybridQuery(
+  store: Store,
+  query: string,
+  options?: HybridQueryOptions
+): Promise<HybridQueryResult[]> {
+  const limit = options?.limit ?? 10;
+  const minScore = options?.minScore ?? 0;
+  const candidateLimit = options?.candidateLimit ?? RERANK_CANDIDATE_LIMIT;
+  const collection = options?.collection;
+  const hooks = options?.hooks;
+
+  const rankedLists: RankedResult[][] = [];
+  const docidMap = new Map<string, string>(); // filepath -> docid
+  const hasVectors = !!store.db.prepare(
+    `SELECT name FROM sqlite_master WHERE type='table' AND name='vectors_vec'`
+  ).get();
+
+  // Step 1: BM25 probe — strong signal skips expensive LLM expansion
+  const initialFts = store.searchFTS(query, 20)
+    .filter(r => !collection || r.collectionName === collection);
+  const topScore = initialFts[0]?.score ?? 0;
+  const secondScore = initialFts[1]?.score ?? 0;
+  const hasStrongSignal = initialFts.length > 0
+    && topScore >= STRONG_SIGNAL_MIN_SCORE
+    && (topScore - secondScore) >= STRONG_SIGNAL_MIN_GAP;
+
+  if (hasStrongSignal) hooks?.onStrongSignal?.(topScore);
+
+  // Step 2: Expand query (or skip if strong signal)
+  const expanded = hasStrongSignal
+    ? []
+    : await store.expandQuery(query);
+
+  hooks?.onExpand?.(query, expanded);
+
+  // Seed with initial FTS results (avoid re-running original query FTS)
+  if (initialFts.length > 0) {
+    for (const r of initialFts) docidMap.set(r.filepath, r.docid);
+    rankedLists.push(initialFts.map(r => ({
+      file: r.filepath, displayPath: r.displayPath,
+      title: r.title, body: r.body || "", score: r.score,
+    })));
+  }
+
+  // Step 3: Route searches by query type
+  // Original query → vector search (FTS already covered by probe in step 1).
+  // Vector searches run sequentially — node-llama-cpp's embed context
+  // hangs on concurrent embed() calls (known limitation).
+  if (hasVectors) {
+    const vecResults = await store.searchVec(query, DEFAULT_EMBED_MODEL, 20, collection);
+    if (vecResults.length > 0) {
+      for (const r of vecResults) docidMap.set(r.filepath, r.docid);
+      rankedLists.push(vecResults.map(r => ({
+        file: r.filepath, displayPath: r.displayPath,
+        title: r.title, body: r.body || "", score: r.score,
+      })));
+    }
+  }
+
+  // Expanded queries → route by type: lex→FTS only, vec/hyde→vector only.
+  // This restores the CLI's query-type-aware routing that was lost in the initial refactor.
+  for (const q of expanded) {
+    if (q.type === 'lex') {
+      const ftsResults = store.searchFTS(q.text, 20)
+        .filter(r => !collection || r.collectionName === collection);
+      if (ftsResults.length > 0) {
+        for (const r of ftsResults) docidMap.set(r.filepath, r.docid);
+        rankedLists.push(ftsResults.map(r => ({
+          file: r.filepath, displayPath: r.displayPath,
+          title: r.title, body: r.body || "", score: r.score,
+        })));
+      }
+    } else {
+      // vec or hyde → vector search only
+      if (hasVectors) {
+        const vecResults = await store.searchVec(q.text, DEFAULT_EMBED_MODEL, 20, collection);
+        if (vecResults.length > 0) {
+          for (const r of vecResults) docidMap.set(r.filepath, r.docid);
+          rankedLists.push(vecResults.map(r => ({
+            file: r.filepath, displayPath: r.displayPath,
+            title: r.title, body: r.body || "", score: r.score,
+          })));
+        }
+      }
+    }
+  }
+
+  // Step 4: RRF fusion — first 2 lists (original FTS + first vec) get 2x weight
+  const weights = rankedLists.map((_, i) => i < 2 ? 2.0 : 1.0);
+  const fused = reciprocalRankFusion(rankedLists, weights);
+  const candidates = fused.slice(0, candidateLimit);
+
+  if (candidates.length === 0) return [];
+
+  // Step 5: Chunk documents, pick best chunk per doc for reranking.
+  // Reranking full bodies is O(tokens) — the critical perf lesson that motivated this refactor.
+  const queryTerms = query.toLowerCase().split(/\s+/).filter(t => t.length > 2);
+  const chunksToRerank: { file: string; text: string }[] = [];
+  const docChunkMap = new Map<string, { chunks: { text: string; pos: number }[]; bestIdx: number }>();
+
+  for (const cand of candidates) {
+    const chunks = chunkDocument(cand.body);
+    if (chunks.length === 0) continue;
+
+    // Pick chunk with most keyword overlap (fallback: first chunk)
+    let bestIdx = 0;
+    let bestScore = -1;
+    for (let i = 0; i < chunks.length; i++) {
+      const chunkLower = chunks[i]!.text.toLowerCase();
+      const score = queryTerms.reduce((acc, term) => acc + (chunkLower.includes(term) ? 1 : 0), 0);
+      if (score > bestScore) { bestScore = score; bestIdx = i; }
+    }
+
+    chunksToRerank.push({ file: cand.file, text: chunks[bestIdx]!.text });
+    docChunkMap.set(cand.file, { chunks, bestIdx });
+  }
+
+  // Step 6: Rerank chunks (NOT full bodies)
+  hooks?.onRerankStart?.(chunksToRerank.length);
+  const reranked = await store.rerank(query, chunksToRerank);
+  hooks?.onRerankDone?.();
+
+  // Step 7: Blend RRF position score with reranker score
+  // Position-aware weights: top retrieval results get more protection from reranker disagreement
+  const candidateMap = new Map(candidates.map(c => [c.file, {
+    displayPath: c.displayPath, title: c.title, body: c.body,
+  }]));
+  const rrfRankMap = new Map(candidates.map((c, i) => [c.file, i + 1]));
+
+  const blended = reranked.map(r => {
+    const rrfRank = rrfRankMap.get(r.file) || candidateLimit;
+    let rrfWeight: number;
+    if (rrfRank <= 3) rrfWeight = 0.75;
+    else if (rrfRank <= 10) rrfWeight = 0.60;
+    else rrfWeight = 0.40;
+    const rrfScore = 1 / rrfRank;
+    const blendedScore = rrfWeight * rrfScore + (1 - rrfWeight) * r.score;
+
+    const candidate = candidateMap.get(r.file);
+    const chunkInfo = docChunkMap.get(r.file);
+    const bestIdx = chunkInfo?.bestIdx ?? 0;
+    const bestChunk = chunkInfo?.chunks[bestIdx]?.text || candidate?.body || "";
+    const bestChunkPos = chunkInfo?.chunks[bestIdx]?.pos || 0;
+
+    return {
+      file: r.file,
+      displayPath: candidate?.displayPath || "",
+      title: candidate?.title || "",
+      body: candidate?.body || "",
+      bestChunk,
+      bestChunkPos,
+      score: blendedScore,
+      context: store.getContextForFile(r.file),
+      docid: docidMap.get(r.file) || "",
+    };
+  }).sort((a, b) => b.score - a.score);
+
+  // Step 8: Dedup by file (safety net — prevents duplicate output)
+  const seenFiles = new Set<string>();
+  return blended
+    .filter(r => {
+      if (seenFiles.has(r.file)) return false;
+      seenFiles.add(r.file);
+      return true;
+    })
+    .filter(r => r.score >= minScore)
+    .slice(0, limit);
+}
+
+export interface VectorSearchOptions {
+  collection?: string;
+  limit?: number;           // default 10
+  minScore?: number;        // default 0.3
+  hooks?: Pick<SearchHooks, 'onExpand'>;
+}
+
+export interface VectorSearchResult {
+  file: string;
+  displayPath: string;
+  title: string;
+  body: string;
+  score: number;
+  context: string | null;
+  docid: string;
+}
+
+/**
+ * Vector-only semantic search with query expansion.
+ *
+ * Pipeline:
+ * 1. expandQuery() → typed variants, filter to vec/hyde only (lex irrelevant here)
+ * 2. searchVec() for original + vec/hyde variants (sequential — node-llama-cpp embed limitation)
+ * 3. Dedup by filepath (keep max score)
+ * 4. Sort by score descending, filter by minScore, slice to limit
+ */
+export async function vectorSearchQuery(
+  store: Store,
+  query: string,
+  options?: VectorSearchOptions
+): Promise<VectorSearchResult[]> {
+  const limit = options?.limit ?? 10;
+  const minScore = options?.minScore ?? 0.3;
+  const collection = options?.collection;
+
+  const hasVectors = !!store.db.prepare(
+    `SELECT name FROM sqlite_master WHERE type='table' AND name='vectors_vec'`
+  ).get();
+  if (!hasVectors) return [];
+
+  // Expand query — filter to vec/hyde only (lex queries target FTS, not vector)
+  const allExpanded = await store.expandQuery(query);
+  const vecExpanded = allExpanded.filter(q => q.type !== 'lex');
+  options?.hooks?.onExpand?.(query, vecExpanded);
+
+  // Run original + vec/hyde expanded through vector, sequentially — concurrent embed() hangs
+  const queryTexts = [query, ...vecExpanded.map(q => q.text)];
+  const allResults = new Map<string, VectorSearchResult>();
+  for (const q of queryTexts) {
+    const vecResults = await store.searchVec(q, DEFAULT_EMBED_MODEL, limit, collection);
+    for (const r of vecResults) {
+      const existing = allResults.get(r.filepath);
+      if (!existing || r.score > existing.score) {
+        allResults.set(r.filepath, {
+          file: r.filepath,
+          displayPath: r.displayPath,
+          title: r.title,
+          body: r.body || "",
+          score: r.score,
+          context: store.getContextForFile(r.filepath),
+          docid: r.docid,
+        });
+      }
+    }
+  }
+
+  return Array.from(allResults.values())
+    .sort((a, b) => b.score - a.score)
+    .filter(r => r.score >= minScore)
+    .slice(0, limit);
+}