unrag 0.2.6 → 0.2.8

package/dist/cli/index.js

@@ -1,7 +1,25 @@
 #!/usr/bin/env node
+import { createRequire } from "node:module";
+var __create = Object.create;
+var __getProtoOf = Object.getPrototypeOf;
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __toESM = (mod, isNodeMode, target) => {
+  target = mod != null ? __create(__getProtoOf(mod)) : {};
+  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
+  for (let key of __getOwnPropNames(mod))
+    if (!__hasOwnProp.call(to, key))
+      __defProp(to, key, {
+        get: () => mod[key],
+        enumerable: true
+      });
+  return to;
+};
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
 // cli/run.ts
-import { intro, outro as outro3 } from "@clack/prompts";
+import { intro, outro as outro5 } from "@clack/prompts";
 
 // cli/commands/init.ts
 import {
@@ -358,6 +376,10 @@ async function copyRegistryFiles(selection) {
       src: path2.join(selection.registryRoot, "core/config.ts"),
       dest: path2.join(installBaseAbs, "core/config.ts")
     },
+    {
+      src: path2.join(selection.registryRoot, "core/deep-merge.ts"),
+      dest: path2.join(installBaseAbs, "core/deep-merge.ts")
+    },
     {
       src: path2.join(selection.registryRoot, "core/context-engine.ts"),
       dest: path2.join(installBaseAbs, "core/context-engine.ts")
@@ -579,6 +601,52 @@ async function copyExtractorFiles(selection) {
     await writeText(dest, raw);
   }
 }
+async function copyBatteryFiles(selection) {
+  const toAbs = (projectRelative) => path2.join(selection.projectRoot, projectRelative);
+  const installBaseAbs = toAbs(selection.installDir);
+  const batteryRegistryDir = selection.battery === "reranker" ? "rerank" : selection.battery;
+  const batteryRegistryAbs = path2.join(selection.registryRoot, batteryRegistryDir);
+  if (!await exists(batteryRegistryAbs)) {
+    throw new Error(`Unknown battery registry: ${path2.relative(selection.registryRoot, batteryRegistryAbs)}`);
+  }
+  const batteryFiles = await listFilesRecursive(batteryRegistryAbs);
+  const destRootAbs = path2.join(installBaseAbs, batteryRegistryDir);
+  const nonInteractive = Boolean(selection.yes) || !process.stdin.isTTY;
+  const overwritePolicy = selection.overwrite ?? "skip";
+  const shouldWrite = async (src, dest) => {
+    if (!await exists(dest))
+      return true;
+    if (overwritePolicy === "force")
+      return true;
+    if (nonInteractive)
+      return false;
+    try {
+      const [srcRaw, destRaw] = await Promise.all([readText(src), readText(dest)]);
+      if (srcRaw === destRaw)
+        return false;
+    } catch {}
+    const answer = await confirm({
+      message: `Overwrite ${path2.relative(selection.projectRoot, dest)}?`,
+      initialValue: false
+    });
+    if (isCancel(answer)) {
+      cancel("Cancelled.");
+      return false;
+    }
+    return Boolean(answer);
+  };
+  for (const src of batteryFiles) {
+    if (!await exists(src)) {
+      throw new Error(`Registry file missing: ${src}`);
+    }
+    const rel = path2.relative(batteryRegistryAbs, src);
+    const dest = path2.join(destRootAbs, rel);
+    if (!await shouldWrite(src, dest))
+      continue;
+    const raw = await readText(src);
+    await writeText(dest, raw);
+  }
+}
 
 // cli/lib/json.ts
 import { readFile as readFile2, writeFile as writeFile2 } from "node:fs/promises";
@@ -675,6 +743,7 @@ async function fetchPreset(input) {
 // cli/lib/packageJson.ts
 import path4 from "node:path";
 import { readFile as readFile4, writeFile as writeFile3 } from "node:fs/promises";
+import { spawn } from "node:child_process";
 async function detectPackageManager(projectRoot) {
   if (await exists(path4.join(projectRoot, "bun.lock")))
     return "bun";
@@ -803,6 +872,15 @@ function depsForEmbeddingProvider(provider) {
     deps["voyage-ai-provider"] = "^3.0.0";
   return { deps, devDeps };
 }
+function depsForBattery(battery) {
+  const deps = {};
+  const devDeps = {};
+  if (battery === "reranker") {
+    deps["ai"] = "^6.0.3";
+    deps["@ai-sdk/cohere"] = "^3.0.1";
+  }
+  return { deps, devDeps };
+}
 function installCmd(pm) {
   if (pm === "bun")
     return "bun install";
@@ -812,6 +890,32 @@ function installCmd(pm) {
     return "yarn";
   return "npm install";
 }
+function installSpawnSpec(pm) {
+  if (pm === "bun")
+    return { cmd: "bun", args: ["install"] };
+  if (pm === "pnpm")
+    return { cmd: "pnpm", args: ["install"] };
+  if (pm === "yarn")
+    return { cmd: "yarn", args: [] };
+  return { cmd: "npm", args: ["install"] };
+}
+async function installDependencies(projectRoot) {
+  const pm = await detectPackageManager(projectRoot);
+  const { cmd, args } = installSpawnSpec(pm);
+  await new Promise((resolve, reject) => {
+    const child = spawn(cmd, args, {
+      cwd: projectRoot,
+      stdio: "inherit",
+      env: process.env
+    });
+    child.on("error", (err) => reject(err));
+    child.on("exit", (code, signal) => {
+      if (code === 0)
+        return resolve();
+      reject(new Error(`Dependency installation failed (${installCmd(pm)}). Exit code: ${code ?? "null"}, signal: ${signal ?? "null"}`));
+    });
+  });
+}
 
 // cli/lib/tsconfig.ts
 import path5 from "node:path";
@@ -956,6 +1060,10 @@ var parseInitArgs = (args) => {
       }
       continue;
     }
+    if (a === "--no-install") {
+      out.noInstall = true;
+      continue;
+    }
   }
   return out;
 };
@@ -987,6 +1095,7 @@ async function initCommand(args) {
   const defaultRichMediaExtractors = extractorOptions.filter((o) => o.defaultSelected).map((o) => o.value).sort();
   const existing = await readJsonFile(path6.join(root, CONFIG_FILE));
   const parsed = parseInitArgs(args);
+  const noInstall = Boolean(parsed.noInstall) || process.env.UNRAG_SKIP_INSTALL === "1";
   const preset = parsed.preset ? await fetchPreset(parsed.preset) : null;
   if (preset) {
     const hasOtherChoices = Boolean(parsed.installDir) || Boolean(parsed.storeAdapter) || Boolean(parsed.aliasBase) || typeof parsed.richMedia === "boolean" || (parsed.extractors ?? []).length > 0;
@@ -1185,6 +1294,9 @@ async function initCommand(args) {
   const merged = mergeDeps(pkg, { ...deps, ...embeddingDeps.deps, ...extractorDeps, ...connectorDeps }, { ...devDeps, ...embeddingDeps.devDeps, ...extractorDevDeps, ...connectorDevDeps });
   if (merged.changes.length > 0) {
     await writePackageJson(root, merged.pkg);
+    if (!noInstall) {
+      await installDependencies(root);
+    }
   }
   const config = {
     installDir,
@@ -1200,7 +1312,7 @@ async function initCommand(args) {
   };
   await writeJsonFile(path6.join(root, CONFIG_FILE), config);
   const pm = await detectPackageManager(root);
-  const installLine = merged.changes.length > 0 ? `Next: run \`${installCmd(pm)}\`` : "Dependencies already satisfied.";
+  const installLine = merged.changes.length === 0 ? "Dependencies already satisfied." : noInstall ? `Next: run \`${installCmd(pm)}\`` : "Dependencies installed.";
   const isNext = Boolean((merged.pkg.dependencies ?? {})["next"]) || Boolean((merged.pkg.devDependencies ?? {})["next"]);
   const tsconfigResult = isNext ? await patchTsconfigPaths({ projectRoot: root, installDir, aliasBase }) : { changed: false };
   const envHint = (() => {
@@ -1339,16 +1451,24 @@ var parseAddArgs = (args) => {
       out.yes = true;
       continue;
     }
+    if (a === "--no-install") {
+      out.noInstall = true;
+      continue;
+    }
     if (!out.kind && a && !a.startsWith("-")) {
       if (a === "extractor") {
         out.kind = "extractor";
         continue;
       }
+      if (a === "battery") {
+        out.kind = "battery";
+        continue;
+      }
       out.kind = "connector";
       out.name = a;
       continue;
     }
-    if (out.kind === "extractor" && !out.name && a && !a.startsWith("-")) {
+    if ((out.kind === "extractor" || out.kind === "battery") && !out.name && a && !a.startsWith("-")) {
       out.name = a;
       continue;
     }
@@ -1363,6 +1483,7 @@ async function addCommand(args) {
   const parsed = parseAddArgs(args);
   const kind = parsed.kind ?? "connector";
   const name = parsed.name;
+  const noInstall = Boolean(parsed.noInstall) || process.env.UNRAG_SKIP_INSTALL === "1";
   const configPath = path7.join(root, CONFIG_FILE2);
   const config = await readJsonFile(configPath);
   if (!config?.installDir) {
@@ -1376,20 +1497,76 @@ async function addCommand(args) {
   const manifest = await readRegistryManifest(registryRoot);
   const availableExtractors = new Set(manifest.extractors.map((e) => e.id));
   const availableConnectors = new Set(manifest.connectors.filter((c) => c.status === "available").map((c) => c.id));
+  const availableBatteries = new Set((manifest.batteries ?? []).filter((b) => b.status === "available").map((b) => b.id));
   if (!name) {
     outro2([
       "Usage:",
       "  unrag add <connector>",
       "  unrag add extractor <name>",
+      "  unrag add battery <name>",
       "",
       `Available connectors: ${Array.from(availableConnectors).join(", ")}`,
-      `Available extractors: ${Array.from(availableExtractors).join(", ")}`
+      `Available extractors: ${Array.from(availableExtractors).join(", ")}`,
+      `Available batteries: ${Array.from(availableBatteries).join(", ")}`
     ].join(`
 `));
     return;
   }
   const nonInteractive = parsed.yes || !process.stdin.isTTY;
   const pkg = await readPackageJson(root);
+  if (kind === "battery") {
+    const battery = name;
+    if (!battery || !availableBatteries.has(battery)) {
+      outro2(`Unknown battery: ${name}
+
+Available batteries: ${Array.from(availableBatteries).join(", ")}`);
+      return;
+    }
+    await copyBatteryFiles({
+      projectRoot: root,
+      registryRoot,
+      installDir: config.installDir,
+      battery,
+      yes: nonInteractive
+    });
+    const { deps: deps2, devDeps: devDeps2 } = depsForBattery(battery);
+    const merged2 = mergeDeps(pkg, deps2, devDeps2);
+    if (merged2.changes.length > 0) {
+      await writePackageJson(root, merged2.pkg);
+      if (!noInstall) {
+        await installDependencies(root);
+      }
+    }
+    const batteries = Array.from(new Set([...config.batteries ?? [], battery])).sort();
+    await writeJsonFile(configPath, { ...config, batteries });
+    const wiringSnippet = battery === "reranker" ? [
+      "",
+      "Next steps:",
+      "1. Import the reranker in unrag.config.ts:",
+      `   import { createCohereReranker } from "./${config.installDir}/rerank";`,
+      "",
+      "2. Add reranker to your engine config:",
+      "   const reranker = createCohereReranker();",
+      "   return unrag.createEngine({ store, reranker });",
+      "",
+      "3. Use reranking in your retrieval flow:",
+      "   const retrieved = await engine.retrieve({ query, topK: 30 });",
+      "   const reranked = await engine.rerank({ query, candidates: retrieved.chunks, topK: 8 });",
+      "",
+      "Env: COHERE_API_KEY (required for Cohere rerank-v3.5)"
+    ] : [];
+    outro2([
+      `Installed battery: ${battery}.`,
+      "",
+      `- Code: ${path7.join(config.installDir, battery === "reranker" ? "rerank" : battery)}`,
+      "",
+      merged2.changes.length > 0 ? `Added deps: ${merged2.changes.map((c) => c.name).join(", ")}` : "Added deps: none",
+      merged2.changes.length > 0 && !noInstall ? "Dependencies installed." : merged2.changes.length > 0 && noInstall ? "Dependencies not installed (skipped)." : "",
+      ...wiringSnippet
+    ].filter(Boolean).join(`
+`));
+    return;
+  }
   if (kind === "connector") {
     const connector = name;
     if (!connector || !availableConnectors.has(connector)) {
@@ -1409,6 +1586,9 @@ Available connectors: ${Array.from(availableConnectors).join(", ")}`);
     const merged2 = mergeDeps(pkg, deps2, devDeps2);
     if (merged2.changes.length > 0) {
       await writePackageJson(root, merged2.pkg);
+      if (!noInstall) {
+        await installDependencies(root);
+      }
     }
     const connectors = Array.from(new Set([...config.connectors ?? [], connector])).sort();
     await writeJsonFile(configPath, { ...config, connectors });
@@ -1419,6 +1599,7 @@ Available connectors: ${Array.from(availableConnectors).join(", ")}`);
       `- Docs: ${docsUrl(`/docs/connectors/${connector}`)}`,
       "",
       merged2.changes.length > 0 ? `Added deps: ${merged2.changes.map((c) => c.name).join(", ")}` : "Added deps: none",
+      merged2.changes.length > 0 && !noInstall ? "Dependencies installed." : merged2.changes.length > 0 && noInstall ? "Dependencies not installed (skipped)." : "",
       nonInteractive ? "" : connector === "notion" ? "Tip: keep NOTION_TOKEN server-side only (env var)." : connector === "google-drive" ? "Tip: keep Google OAuth refresh tokens and service account keys server-side only." : ""
     ].filter(Boolean).join(`
 `));
@@ -1442,6 +1623,9 @@ Available extractors: ${Array.from(availableExtractors).join(", ")}`);
   const merged = mergeDeps(pkg, deps, devDeps);
   if (merged.changes.length > 0) {
     await writePackageJson(root, merged.pkg);
+    if (!noInstall) {
+      await installDependencies(root);
+    }
   }
   const extractors = Array.from(new Set([...config.extractors ?? [], extractor])).sort();
   await writeJsonFile(configPath, { ...config, extractors });
@@ -1451,76 +1635,2577 @@ Available extractors: ${Array.from(availableExtractors).join(", ")}`);
     `- Code: ${path7.join(config.installDir, "extractors", extractor)}`,
     "",
     merged.changes.length > 0 ? `Added deps: ${merged.changes.map((c) => c.name).join(", ")}` : "Added deps: none",
+    merged.changes.length > 0 && !noInstall ? "Dependencies installed." : merged.changes.length > 0 && noInstall ? "Dependencies not installed (skipped)." : "",
     "",
     `Next: import the extractor and pass it to createContextEngine({ extractors: [...] }).`
   ].filter(Boolean).join(`
 `));
 }
 
-// cli/run.ts
-function renderHelp() {
-  return [
-    "unrag — vendor-in RAG primitives (ingest/retrieve + adapters) into your repo.",
-    "",
-    "Usage:",
-    "  bunx unrag <command> [options]",
-    "  npx  unrag <command> [options]",
-    "",
-    "Commands:",
-    "  init                Install core files (config + store adapter templates)",
-    "  add <connector>     Install a connector (notion, google-drive)",
-    "  help                Show this help",
-    "",
-    "Global options:",
-    "  -h, --help           Show help",
-    "  -y, --yes            Non-interactive; accept defaults",
-    "",
-    "init options:",
-    "  --store <adapter>    drizzle | prisma | raw-sql",
-    "  --dir <path>         Install directory (alias: --install-dir)",
-    "  --alias <@name>      Import alias base (e.g. @unrag)",
-    "  --preset <id|url>    Install from a web-generated preset (non-interactive)",
-    "  --overwrite <mode>   skip | force (when files already exist)",
-    "  --rich-media         Enable rich media setup (also enables multimodal embeddings)",
-    "  --no-rich-media      Disable rich media setup",
-    "  --extractors <list>  Comma-separated extractors (implies --rich-media)",
-    "",
-    "Examples:",
-    "  bunx unrag@latest init",
-    "  bunx unrag@latest init --yes --store drizzle --dir lib/unrag --alias @unrag",
-    "  bunx unrag@latest init --yes --rich-media",
-    "  bunx unrag@latest init --yes --extractors pdf-text-layer,file-text",
-    "  bunx unrag add notion --yes",
-    "",
-    "Docs:",
-    `  - Quickstart: ${docsUrl("/docs/getting-started/quickstart")}`,
-    `  - CLI:       ${docsUrl("/docs/reference/cli")}`,
-    `  - Notion:    ${docsUrl("/docs/connectors/notion")}`,
-    "",
-    "Repo:",
-    `  ${UNRAG_GITHUB_REPO_URL}`,
-    "",
-    "Tip:",
-    "  After `init`, open the generated unrag.md for schema + env vars (DATABASE_URL)."
-  ].join(`
-`);
+// cli/commands/doctor.ts
+import { outro as outro4, spinner as spinner2 } from "@clack/prompts";
+
+// cli/lib/doctor/infer.ts
+import path8 from "node:path";
+import { readdir as readdir2, readFile as readFile6 } from "node:fs/promises";
+var CONFIG_FILE3 = "unrag.json";
+var CONFIG_TS_FILE = "unrag.config.ts";
+var DEFAULT_INSTALL_DIRS = ["lib/unrag", "src/lib/unrag", "src/unrag"];
+async function inferInstallState(options) {
+  const warnings = [];
+  const projectRoot = options.projectRootOverride ?? await tryFindProjectRoot(process.cwd()) ?? process.cwd();
+  const unragJsonPath = path8.join(projectRoot, CONFIG_FILE3);
+  const unragJsonExists = await exists(unragJsonPath);
+  let unragJson = null;
+  let unragJsonParseable = false;
+  if (unragJsonExists) {
+    unragJson = await readJsonFile(unragJsonPath);
+    unragJsonParseable = unragJson !== null;
+    if (!unragJsonParseable) {
+      warnings.push(`${CONFIG_FILE3} exists but could not be parsed.`);
+    }
+  }
+  let installDir = null;
+  if (options.installDirOverride) {
+    installDir = options.installDirOverride;
+  } else if (unragJson?.installDir) {
+    installDir = unragJson.installDir;
+  } else {
+    installDir = await inferInstallDirFromFilesystem(projectRoot);
+    if (!installDir && !unragJsonExists) {
+      warnings.push("Could not find unrag.json or infer installDir from filesystem.");
+    }
+  }
+  const installDirFull = installDir ? path8.join(projectRoot, installDir) : null;
+  const installDirExists = installDirFull ? await exists(installDirFull) : false;
+  const configFileExists = await exists(path8.join(projectRoot, CONFIG_TS_FILE));
+  let storeAdapter = null;
+  if (unragJson?.storeAdapter) {
+    storeAdapter = unragJson.storeAdapter;
+  } else if (installDirFull && installDirExists) {
+    storeAdapter = await inferStoreAdapterFromFilesystem(installDirFull);
+  }
+  let embeddingProvider = null;
+  if (unragJson?.embeddingProvider) {
+    embeddingProvider = unragJson.embeddingProvider;
+  } else if (installDirFull && installDirExists) {
+    embeddingProvider = await inferEmbeddingProviderFromFilesystem(installDirFull);
+  }
+  let installedExtractors = [];
+  if (unragJson?.extractors && Array.isArray(unragJson.extractors)) {
+    installedExtractors = unragJson.extractors;
+  }
+  if (installDirFull && installDirExists) {
+    const fsExtractors = await inferExtractorsFromFilesystem(installDirFull);
+    installedExtractors = Array.from(new Set([...installedExtractors, ...fsExtractors])).sort();
+  }
+  let installedConnectors = [];
+  if (unragJson?.connectors && Array.isArray(unragJson.connectors)) {
+    installedConnectors = unragJson.connectors;
+  }
+  if (installDirFull && installDirExists) {
+    const fsConnectors = await inferConnectorsFromFilesystem(installDirFull);
+    installedConnectors = Array.from(new Set([...installedConnectors, ...fsConnectors])).sort();
+  }
+  let inferredDbEnvVar = null;
+  if (configFileExists) {
+    inferredDbEnvVar = await inferDbEnvVarFromConfig(projectRoot);
+  }
+  let inferenceConfidence = "low";
+  if (unragJsonExists && unragJsonParseable && installDirExists) {
+    inferenceConfidence = "high";
+  } else if (installDirExists && (storeAdapter || configFileExists)) {
+    inferenceConfidence = "medium";
+  }
+  return {
+    projectRoot,
+    installDir,
+    installDirExists,
+    unragJsonExists,
+    unragJsonParseable,
+    unragJson,
+    configFileExists,
+    storeAdapter,
+    embeddingProvider,
+    installedExtractors,
+    installedConnectors,
+    inferredDbEnvVar,
+    inferenceConfidence,
+    warnings
+  };
 }
-async function run(argv) {
-  const [, , command, ...rest] = argv;
-  intro("unrag");
-  if (!command || command === "help" || command === "--help" || command === "-h") {
-    outro3(renderHelp());
-    return;
+async function inferInstallDirFromFilesystem(projectRoot) {
+  for (const candidate of DEFAULT_INSTALL_DIRS) {
+    const full = path8.join(projectRoot, candidate);
+    if (!await exists(full))
+      continue;
+    const hasUnragMd = await exists(path8.join(full, "unrag.md"));
+    const hasStore = await exists(path8.join(full, "store"));
+    const hasCore = await exists(path8.join(full, "core"));
+    if (hasUnragMd || hasStore || hasCore) {
+      return candidate;
+    }
   }
-  if (command === "init") {
-    await initCommand(rest);
-    return;
+  return null;
+}
+async function inferStoreAdapterFromFilesystem(installDir) {
+  const storeDir = path8.join(installDir, "store");
+  if (!await exists(storeDir))
+    return null;
+  try {
+    const entries = await readdir2(storeDir, { withFileTypes: true });
+    const dirs = entries.filter((e) => e.isDirectory()).map((e) => e.name);
+    for (const dir of dirs) {
+      if (dir.includes("drizzle"))
+        return "drizzle";
+      if (dir.includes("prisma"))
+        return "prisma";
+      if (dir.includes("raw-sql"))
+        return "raw-sql";
+    }
+  } catch {}
+  return null;
+}
+async function inferEmbeddingProviderFromFilesystem(installDir) {
+  const embeddingDir = path8.join(installDir, "embedding");
+  if (!await exists(embeddingDir))
+    return null;
+  const providers = [
+    "ai",
+    "openai",
+    "google",
+    "openrouter",
+    "azure",
+    "vertex",
+    "bedrock",
+    "cohere",
+    "mistral",
+    "together",
+    "ollama",
+    "voyage"
+  ];
+  try {
+    const entries = await readdir2(embeddingDir);
+    for (const provider of providers) {
+      if (entries.includes(`${provider}.ts`)) {
+        return provider;
+      }
+    }
+  } catch {}
+  return null;
+}
+async function inferExtractorsFromFilesystem(installDir) {
+  const extractorsDir = path8.join(installDir, "extractors");
+  if (!await exists(extractorsDir))
+    return [];
+  try {
+    const entries = await readdir2(extractorsDir, { withFileTypes: true });
+    return entries.filter((e) => e.isDirectory()).map((e) => e.name).filter((name) => {
+      if (name === "_shared")
+        return false;
+      if (name.startsWith("_"))
+        return false;
+      return true;
+    });
+  } catch {
+    return [];
   }
-  if (command === "add") {
-    await addCommand(rest);
+}
+async function inferConnectorsFromFilesystem(installDir) {
+  const connectorsDir = path8.join(installDir, "connectors");
+  if (!await exists(connectorsDir))
+    return [];
+  try {
+    const entries = await readdir2(connectorsDir, { withFileTypes: true });
+    return entries.filter((e) => e.isDirectory()).map((e) => e.name);
+  } catch {
+    return [];
+  }
+}
+async function inferDbEnvVarFromConfig(projectRoot) {
+  const configPath = path8.join(projectRoot, CONFIG_TS_FILE);
+  if (!await exists(configPath))
+    return null;
+  try {
+    const content = await readFile6(configPath, "utf8");
+    const candidates = extractDbEnvVarCandidates(content);
+    if (candidates.length === 0) {
+      const importedFiles = extractLocalImports(content);
+      for (const importPath of importedFiles) {
+        const resolved = await resolveImportPath(projectRoot, importPath);
+        if (resolved) {
+          const importContent = await readFile6(resolved, "utf8").catch(() => null);
+          if (importContent) {
+            candidates.push(...extractDbEnvVarCandidates(importContent));
+          }
+        }
+      }
+    }
+    if (candidates.length === 0)
+      return null;
+    if (candidates.length === 1)
+      return candidates[0];
+    const preferred = candidates.find((c) => c === "DATABASE_URL" || c.endsWith("_DATABASE_URL") || c.endsWith("_DB_URL"));
+    return preferred ?? candidates[0];
+  } catch {
+    return null;
+  }
+}
+function extractDbEnvVarCandidates(source) {
+  const candidates = [];
+  const connectionStringPattern = /connectionString\s*[:=]\s*process\.env\.([A-Z_][A-Z0-9_]*)/gi;
+  let match;
+  while ((match = connectionStringPattern.exec(source)) !== null) {
+    if (match[1])
+      candidates.push(match[1]);
+  }
+  const dbUrlPattern = /process\.env\.([A-Z_]*(?:DATABASE|DB)_?(?:URL|URI|CONNECTION)[A-Z_]*)/gi;
+  while ((match = dbUrlPattern.exec(source)) !== null) {
+    if (match[1] && !candidates.includes(match[1])) {
+      candidates.push(match[1]);
+    }
+  }
+  const poolPattern = /new\s+Pool\s*\(\s*\{[^}]*process\.env\.([A-Z_][A-Z0-9_]*)/gi;
+  while ((match = poolPattern.exec(source)) !== null) {
+    if (match[1] && !candidates.includes(match[1])) {
+      candidates.push(match[1]);
+    }
+  }
+  return candidates;
+}
+function extractLocalImports(source) {
+  const imports = [];
+  const importPattern = /from\s+["']([.@][^"']+)["']/g;
+  let match;
+  while ((match = importPattern.exec(source)) !== null) {
+    if (match[1])
+      imports.push(match[1]);
+  }
+  return imports;
+}
+async function resolveImportPath(projectRoot, importPath) {
+  if (importPath.startsWith("./") || importPath.startsWith("../")) {
+    const configDir = projectRoot;
+    const resolved = path8.resolve(configDir, importPath);
+    for (const ext of [".ts", ".tsx", ".js", ".jsx", ""]) {
+      const candidate = resolved + ext;
+      if (await exists(candidate))
+        return candidate;
+    }
+    for (const ext of [".ts", ".tsx", ".js", ".jsx"]) {
+      const candidate = path8.join(resolved, `index${ext}`);
+      if (await exists(candidate))
+        return candidate;
+    }
+    return null;
+  }
+  if (importPath.startsWith("@/") || importPath.startsWith("@")) {
+    const tsconfigPath = path8.join(projectRoot, "tsconfig.json");
+    if (await exists(tsconfigPath)) {
+      try {
+        const tsconfig = await readJsonFile(tsconfigPath);
+        const paths = tsconfig?.compilerOptions?.paths;
+        if (paths) {
+          for (const [alias, targets] of Object.entries(paths)) {
+            const aliasBase = alias.replace("/*", "");
+            if (importPath.startsWith(aliasBase)) {
+              const rest = importPath.slice(aliasBase.length).replace(/^\//, "");
+              for (const target of targets) {
+                const targetBase = target.replace("/*", "").replace(/^\.\//, "");
+                const resolved = path8.join(projectRoot, targetBase, rest);
+                for (const ext of [".ts", ".tsx", ".js", ".jsx", ""]) {
+                  const candidate = resolved + ext;
+                  if (await exists(candidate))
+                    return candidate;
+                }
+              }
+            }
+          }
+        }
+      } catch {}
+    }
+  }
+  return null;
+}
+async function inferTableNames(installDir, storeAdapter) {
+  const defaults = {
+    documents: "documents",
+    chunks: "chunks",
+    embeddings: "embeddings"
+  };
+  if (!storeAdapter || !installDir)
+    return defaults;
+  const storeDir = path8.join(installDir, "store");
+  if (!await exists(storeDir))
+    return defaults;
+  try {
+    const entries = await readdir2(storeDir, { withFileTypes: true });
+    const adapterDir = entries.find((e) => e.isDirectory() && e.name.includes(storeAdapter));
+    if (!adapterDir)
+      return defaults;
+    const adapterPath = path8.join(storeDir, adapterDir.name);
+    if (storeAdapter === "drizzle") {
+      const schemaPath = path8.join(adapterPath, "schema.ts");
+      if (await exists(schemaPath)) {
+        const content = await readFile6(schemaPath, "utf8");
+        const tableNames = extractDrizzleTableNames(content);
+        return { ...defaults, ...tableNames };
+      }
+    }
+    const storePath = path8.join(adapterPath, "store.ts");
+    if (await exists(storePath)) {
+      const content = await readFile6(storePath, "utf8");
+      const tableNames = extractSqlTableNames(content);
+      return { ...defaults, ...tableNames };
+    }
+  } catch {}
+  return defaults;
+}
+function extractDrizzleTableNames(source) {
+  const result = {};
+  const tablePattern = /export\s+const\s+(documents|chunks|embeddings)\s*=\s*pgTable\s*\(\s*["']([^"']+)["']/g;
+  let match;
+  while ((match = tablePattern.exec(source)) !== null) {
+    const varName = match[1];
+    const tableName = match[2];
+    if (tableName)
+      result[varName] = tableName;
+  }
+  return result;
+}
+function extractSqlTableNames(source) {
+  const result = {};
+  const patterns = [
+    /(?:from|into|update|delete\s+from)\s+([a-z_][a-z0-9_]*)\s/gi,
+    /references\s+([a-z_][a-z0-9_]*)\s*\(/gi
+  ];
+  const found = new Set;
+  for (const pattern of patterns) {
+    let match;
+    while ((match = pattern.exec(source)) !== null) {
+      if (match[1])
+        found.add(match[1].toLowerCase());
+    }
+  }
+  for (const name of found) {
+    if (name.includes("document") && !name.includes("chunk")) {
+      result.documents = name;
+    } else if (name.includes("chunk")) {
+      result.chunks = name;
+    } else if (name.includes("embedding")) {
+      result.embeddings = name;
+    }
+  }
+  return result;
+}
+
+// cli/lib/doctor/staticChecks.ts
+import path9 from "node:path";
+
+// cli/lib/doctor/types.ts
+var EMBEDDING_PROVIDER_ENV_VARS = {
+  ai: {
+    required: ["AI_GATEWAY_API_KEY"],
+    optional: ["AI_GATEWAY_MODEL"]
+  },
+  openai: {
+    required: ["OPENAI_API_KEY"],
+    optional: ["OPENAI_EMBEDDING_MODEL"]
+  },
+  google: {
+    required: ["GOOGLE_GENERATIVE_AI_API_KEY"],
+    optional: ["GOOGLE_GENERATIVE_AI_EMBEDDING_MODEL"]
+  },
+  openrouter: {
+    required: ["OPENROUTER_API_KEY"],
+    optional: ["OPENROUTER_EMBEDDING_MODEL"]
+  },
+  azure: {
+    required: ["AZURE_OPENAI_API_KEY", "AZURE_RESOURCE_NAME"],
+    optional: ["AZURE_EMBEDDING_MODEL"]
+  },
+  vertex: {
+    required: [],
+    optional: ["GOOGLE_APPLICATION_CREDENTIALS", "GOOGLE_VERTEX_EMBEDDING_MODEL"]
+  },
+  bedrock: {
+    required: ["AWS_REGION"],
+    optional: ["AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY", "BEDROCK_EMBEDDING_MODEL"]
+  },
+  cohere: {
+    required: ["COHERE_API_KEY"],
+    optional: ["COHERE_EMBEDDING_MODEL"]
+  },
+  mistral: {
+    required: ["MISTRAL_API_KEY"],
+    optional: ["MISTRAL_EMBEDDING_MODEL"]
+  },
+  together: {
+    required: ["TOGETHER_AI_API_KEY"],
+    optional: ["TOGETHER_AI_EMBEDDING_MODEL"]
+  },
+  ollama: {
+    required: [],
+    optional: ["OLLAMA_EMBEDDING_MODEL"]
+  },
+  voyage: {
+    required: ["VOYAGE_API_KEY"],
+    optional: ["VOYAGE_MODEL"]
+  }
+};
+var STORE_ADAPTER_DEPS = {
+  drizzle: {
+    required: ["drizzle-orm", "pg"],
+    devRequired: ["@types/pg"]
+  },
+  prisma: {
+    required: ["@prisma/client"],
+    devRequired: ["prisma"]
+  },
+  "raw-sql": {
+    required: ["pg"],
+    devRequired: ["@types/pg"]
+  }
+};
+var EXTRACTOR_CONFIG_FLAGS = {
+  "pdf-llm": ["assetProcessing.pdf.llmExtraction.enabled"],
+  "pdf-text-layer": ["assetProcessing.pdf.textLayer.enabled"],
+  "pdf-ocr": ["assetProcessing.pdf.ocr.enabled"],
+  "image-ocr": ["assetProcessing.image.ocr.enabled"],
+  "image-caption-llm": ["assetProcessing.image.captionLlm.enabled"],
+  "audio-transcribe": ["assetProcessing.audio.transcription.enabled"],
+  "video-transcribe": ["assetProcessing.video.transcription.enabled"],
+  "video-frames": ["assetProcessing.video.frames.enabled"],
+  "file-text": ["assetProcessing.file.text.enabled"],
+  "file-docx": ["assetProcessing.file.docx.enabled"],
+  "file-pptx": ["assetProcessing.file.pptx.enabled"],
+  "file-xlsx": ["assetProcessing.file.xlsx.enabled"]
+};
+var EXTRACTOR_FACTORIES = {
+  "pdf-llm": "createPdfLlmExtractor",
+  "pdf-text-layer": "createPdfTextLayerExtractor",
+  "pdf-ocr": "createPdfOcrExtractor",
+  "image-ocr": "createImageOcrExtractor",
+  "image-caption-llm": "createImageCaptionLlmExtractor",
+  "audio-transcribe": "createAudioTranscribeExtractor",
+  "video-transcribe": "createVideoTranscribeExtractor",
+  "video-frames": "createVideoFramesExtractor",
+  "file-text": "createFileTextExtractor",
+  "file-docx": "createFileDocxExtractor",
+  "file-pptx": "createFilePptxExtractor",
+  "file-xlsx": "createFileXlsxExtractor"
+};
+
+// cli/lib/doctor/staticChecks.ts
+async function runStaticChecks(state) {
+  const install = await runInstallChecks(state);
+  const env = await runEnvChecks(state);
+  const modules = await runModuleChecks(state);
+  return { install, env, modules };
+}
+async function runInstallChecks(state) {
+  const results = [];
+  results.push(state.unragJsonExists && state.unragJsonParseable ? {
+    id: "unrag-json",
+    title: "unrag.json",
+    status: "pass",
+    summary: "Configuration file found and parseable.",
+    meta: { version: state.unragJson?.version }
+  } : state.unragJsonExists ? {
+    id: "unrag-json",
+    title: "unrag.json",
+    status: "warn",
+    summary: "Configuration file exists but could not be parsed.",
+    fixHints: [
+      "Check for JSON syntax errors in unrag.json",
+      "Try running `unrag init` again to regenerate"
+    ]
+  } : {
+    id: "unrag-json",
+    title: "unrag.json",
+    status: "warn",
+    summary: "Configuration file not found.",
+    details: [
+      "Doctor is inferring configuration from filesystem.",
+      `Inference confidence: ${state.inferenceConfidence}`
+    ],
+    fixHints: ["Run `unrag init` to create unrag.json"],
+    docsLink: docsUrl("/docs/reference/cli")
+  });
+  results.push(state.configFileExists ? {
+    id: "config-ts",
+    title: "unrag.config.ts",
+    status: "pass",
+    summary: "Engine configuration file found."
+  } : {
+    id: "config-ts",
+    title: "unrag.config.ts",
+    status: "fail",
+    summary: "Engine configuration file not found.",
+    details: [
+      "unrag.config.ts is required to create and configure the Unrag engine."
+    ],
+    fixHints: ["Run `unrag init` to create unrag.config.ts"],
+    docsLink: docsUrl("/docs/getting-started/quickstart")
+  });
+  if (state.installDir) {
+    const installDirFull = path9.join(state.projectRoot, state.installDir);
+    const coreExists = await exists(path9.join(installDirFull, "core"));
+    const storeExists = await exists(path9.join(installDirFull, "store"));
+    const embeddingExists = await exists(path9.join(installDirFull, "embedding"));
+    const unragMdExists = await exists(path9.join(installDirFull, "unrag.md"));
+    const missingDirs = [];
+    if (!coreExists)
+      missingDirs.push("core/");
+    if (!storeExists)
+      missingDirs.push("store/");
+    if (!embeddingExists)
+      missingDirs.push("embedding/");
+    if (state.installDirExists && missingDirs.length === 0) {
+      results.push({
+        id: "install-dir",
+        title: "Install directory",
+        status: "pass",
+        summary: `Install directory found at ${state.installDir}`,
+        details: [
+          `core/: ${coreExists ? "✓" : "✗"}`,
+          `store/: ${storeExists ? "✓" : "✗"}`,
+          `embedding/: ${embeddingExists ? "✓" : "✗"}`,
+          `unrag.md: ${unragMdExists ? "✓" : "✗"}`
+        ]
+      });
+    } else if (state.installDirExists) {
+      results.push({
+        id: "install-dir",
+        title: "Install directory",
+        status: "warn",
+        summary: `Install directory exists but is incomplete.`,
+        details: [`Missing: ${missingDirs.join(", ")}`],
+        fixHints: ["Run `unrag init` to reinstall missing files"]
+      });
+    } else {
+      results.push({
+        id: "install-dir",
+        title: "Install directory",
+        status: "fail",
+        summary: `Install directory not found at ${state.installDir}`,
+        fixHints: [
+          "Run `unrag init` to install Unrag files",
+          `Or use --install-dir to specify a different location`
+        ]
+      });
+    }
+  } else {
+    results.push({
+      id: "install-dir",
+      title: "Install directory",
+      status: "fail",
+      summary: "Could not determine install directory.",
+      fixHints: [
+        "Run `unrag init` to install Unrag",
+        "Or use --install-dir to specify the location"
+      ]
+    });
+  }
+  if (state.storeAdapter) {
+    results.push({
+      id: "store-adapter",
+      title: "Store adapter",
+      status: "pass",
+      summary: `Using ${state.storeAdapter} adapter.`
+    });
+  } else if (state.installDirExists) {
+    results.push({
+      id: "store-adapter",
+      title: "Store adapter",
+      status: "warn",
+      summary: "Could not determine store adapter.",
+      details: ["Expected to find drizzle, prisma, or raw-sql adapter folder."]
+    });
+  }
+  const depResults = await checkDependencies(state);
+  results.push(...depResults);
+  return results;
+}
+async function checkDependencies(state) {
+  const results = [];
+  const pkgJsonPath = path9.join(state.projectRoot, "package.json");
+  if (!await exists(pkgJsonPath)) {
+    results.push({
+      id: "deps-check",
+      title: "Dependencies",
+      status: "skip",
+      summary: "No package.json found."
+    });
+    return results;
+  }
+  const pkgJson = await readJsonFile(pkgJsonPath);
+  if (!pkgJson) {
+    results.push({
+      id: "deps-check",
+      title: "Dependencies",
+      status: "warn",
+      summary: "Could not parse package.json."
+    });
+    return results;
+  }
+  const allDeps = {
+    ...pkgJson.dependencies ?? {},
+    ...pkgJson.devDependencies ?? {}
+  };
+  if (state.storeAdapter) {
+    const adapterDeps = STORE_ADAPTER_DEPS[state.storeAdapter];
+    const missingDeps = [];
+    for (const dep of adapterDeps.required) {
+      if (!allDeps[dep])
+        missingDeps.push(dep);
+    }
+    if (missingDeps.length === 0) {
+      results.push({
+        id: "deps-store",
+        title: `${state.storeAdapter} dependencies`,
+        status: "pass",
+        summary: "All required dependencies installed."
+      });
+    } else {
+      results.push({
+        id: "deps-store",
+        title: `${state.storeAdapter} dependencies`,
+        status: "fail",
+        summary: `Missing dependencies: ${missingDeps.join(", ")}`,
+        fixHints: [`Run: npm install ${missingDeps.join(" ")}`]
+      });
+    }
+  }
+  if (!allDeps["ai"]) {
+    results.push({
+      id: "deps-ai",
+      title: "AI SDK",
+      status: "fail",
+      summary: "Missing required dependency: ai",
+      fixHints: ["Run: npm install ai"]
+    });
+  }
+  return results;
+}
+async function runEnvChecks(state) {
+  const results = [];
+  const dbUrl = process.env.DATABASE_URL || (state.inferredDbEnvVar ? process.env[state.inferredDbEnvVar] : undefined);
+  const dbEnvVarName = state.inferredDbEnvVar ?? "DATABASE_URL";
+  const actualEnvVar = process.env.DATABASE_URL ? "DATABASE_URL" : state.inferredDbEnvVar && process.env[state.inferredDbEnvVar] ? state.inferredDbEnvVar : null;
+  if (dbUrl) {
+    const isValidFormat = dbUrl.startsWith("postgres://") || dbUrl.startsWith("postgresql://");
+    results.push({
+      id: "env-database-url",
+      title: "Database URL",
+      status: isValidFormat ? "pass" : "warn",
+      summary: isValidFormat ? `${actualEnvVar} is set and appears to be a valid Postgres URL.` : `${actualEnvVar} is set but doesn't look like a Postgres URL.`,
+      details: isValidFormat ? undefined : ["Expected format: postgres://user:pass@host:port/db"],
+      meta: { envVar: actualEnvVar }
+    });
+  } else {
+    results.push({
+      id: "env-database-url",
+      title: "Database URL",
+      status: "warn",
+      summary: `${dbEnvVarName} is not set.`,
+      details: state.inferredDbEnvVar && state.inferredDbEnvVar !== "DATABASE_URL" ? [
+        `Inferred env var from config: ${state.inferredDbEnvVar}`,
+        "Neither DATABASE_URL nor the inferred var is set."
+      ] : undefined,
+      fixHints: [
+        `Set ${dbEnvVarName} to your Postgres connection string`,
+        "Example: postgresql://user:pass@localhost:5432/mydb"
+      ],
+      docsLink: docsUrl("/docs/getting-started/database")
+    });
+  }
+  if (state.embeddingProvider) {
+    const providerEnv = EMBEDDING_PROVIDER_ENV_VARS[state.embeddingProvider];
+    if (providerEnv) {
+      const missingRequired = [];
+      const missingOptional = [];
+      for (const envVar of providerEnv.required) {
+        if (!process.env[envVar])
+          missingRequired.push(envVar);
+      }
+      for (const envVar of providerEnv.optional) {
+        if (!process.env[envVar])
+          missingOptional.push(envVar);
+      }
+      if (missingRequired.length === 0) {
+        results.push({
+          id: "env-embedding",
+          title: `${state.embeddingProvider} provider`,
+          status: "pass",
+          summary: "Required environment variables are set.",
+          details: missingOptional.length > 0 ? [`Optional (not set): ${missingOptional.join(", ")}`] : undefined
+        });
+      } else {
+        results.push({
+          id: "env-embedding",
+          title: `${state.embeddingProvider} provider`,
+          status: "fail",
+          summary: `Missing required env vars: ${missingRequired.join(", ")}`,
+          fixHints: missingRequired.map((v) => `Set ${v} in your environment`),
+          docsLink: docsUrl(`/docs/providers/${state.embeddingProvider}`)
+        });
+      }
+    }
+  } else {
+    results.push({
+      id: "env-embedding",
+      title: "Embedding provider",
+      status: "skip",
+      summary: "Could not determine embedding provider."
+    });
+  }
+  for (const connector of state.installedConnectors) {
+    const connectorEnvResults = await checkConnectorEnvVars(connector);
+    results.push(...connectorEnvResults);
+  }
+  return results;
+}
+async function checkConnectorEnvVars(connector) {
+  const results = [];
+  const connectorEnvVars = {
+    notion: {
+      required: ["NOTION_TOKEN"],
+      optional: []
+    },
+    "google-drive": {
+      required: [],
+      optional: [
+        "GOOGLE_SERVICE_ACCOUNT_JSON",
+        "GOOGLE_CLIENT_ID",
+        "GOOGLE_CLIENT_SECRET"
+      ]
+    }
+  };
+  const envVars = connectorEnvVars[connector];
+  if (!envVars)
+    return results;
+  const missingRequired = [];
+  for (const envVar of envVars.required) {
+    if (!process.env[envVar])
+      missingRequired.push(envVar);
+  }
+  if (envVars.required.length === 0) {
+    const hasAny = envVars.optional.some((v) => process.env[v]);
+    results.push({
+      id: `env-connector-${connector}`,
+      title: `${connector} connector`,
+      status: hasAny ? "pass" : "warn",
+      summary: hasAny ? "Connector credentials configured." : "No credentials found (may be configured at runtime).",
+      docsLink: docsUrl(`/docs/connectors/${connector}`)
+    });
+  } else if (missingRequired.length === 0) {
+    results.push({
+      id: `env-connector-${connector}`,
+      title: `${connector} connector`,
+      status: "pass",
+      summary: "Required environment variables are set."
+    });
+  } else {
+    results.push({
+      id: `env-connector-${connector}`,
+      title: `${connector} connector`,
+      status: "fail",
+      summary: `Missing required env vars: ${missingRequired.join(", ")}`,
+      fixHints: missingRequired.map((v) => `Set ${v} in your environment`),
+      docsLink: docsUrl(`/docs/connectors/${connector}`)
+    });
+  }
+  return results;
+}
+async function runModuleChecks(state) {
+  const results = [];
+  if (!state.installDir || !state.installDirExists) {
+    return results;
+  }
+  const installDirFull = path9.join(state.projectRoot, state.installDir);
+  for (const extractor of state.installedExtractors) {
+    const extractorDir = path9.join(installDirFull, "extractors", extractor);
+    const extractorExists = await exists(extractorDir);
+    const hasIndex = extractorExists && await exists(path9.join(extractorDir, "index.ts"));
+    if (extractorExists && hasIndex) {
+      results.push({
+        id: `module-extractor-${extractor}`,
+        title: `Extractor: ${extractor}`,
+        status: "pass",
+        summary: "Module files present."
+      });
+    } else if (extractorExists) {
+      results.push({
+        id: `module-extractor-${extractor}`,
+        title: `Extractor: ${extractor}`,
+        status: "warn",
+        summary: "Module directory exists but may be incomplete.",
+        details: ["Expected index.ts not found."]
+      });
+    } else {
+      results.push({
+        id: `module-extractor-${extractor}`,
+        title: `Extractor: ${extractor}`,
+        status: "fail",
+        summary: "Listed in unrag.json but directory not found.",
+        fixHints: [`Run: unrag add extractor ${extractor}`]
+      });
+    }
+  }
+  for (const connector of state.installedConnectors) {
+    const connectorDir = path9.join(installDirFull, "connectors", connector);
+    const connectorExists = await exists(connectorDir);
+    const hasIndex = connectorExists && await exists(path9.join(connectorDir, "index.ts"));
+    if (connectorExists && hasIndex) {
+      results.push({
+        id: `module-connector-${connector}`,
+        title: `Connector: ${connector}`,
+        status: "pass",
+        summary: "Module files present."
+      });
+    } else if (connectorExists) {
+      results.push({
+        id: `module-connector-${connector}`,
+        title: `Connector: ${connector}`,
+        status: "warn",
+        summary: "Module directory exists but may be incomplete."
+      });
+    } else {
+      results.push({
+        id: `module-connector-${connector}`,
+        title: `Connector: ${connector}`,
+        status: "fail",
+        summary: "Listed in unrag.json but directory not found.",
+        fixHints: [`Run: unrag add ${connector}`]
+      });
+    }
+  }
+  const depResults = await checkExtractorDependencies(state);
+  results.push(...depResults);
+  return results;
+}
+async function checkExtractorDependencies(state) {
+  const results = [];
+  const pkgJsonPath = path9.join(state.projectRoot, "package.json");
+  if (!await exists(pkgJsonPath))
+    return results;
+  const pkgJson = await readJsonFile(pkgJsonPath);
+  if (!pkgJson)
+    return results;
+  const allDeps = {
+    ...pkgJson.dependencies ?? {},
+    ...pkgJson.devDependencies ?? {}
+  };
+  const extractorDeps = {
+    "pdf-text-layer": ["pdfjs-dist"],
+    "file-docx": ["mammoth"],
+    "file-pptx": ["jszip"],
+    "file-xlsx": ["xlsx"]
+  };
+  for (const extractor of state.installedExtractors) {
+    const deps = extractorDeps[extractor];
+    if (!deps || deps.length === 0)
+      continue;
+    const missingDeps = deps.filter((d) => !allDeps[d]);
+    if (missingDeps.length > 0) {
+      results.push({
+        id: `deps-extractor-${extractor}`,
+        title: `${extractor} dependencies`,
+        status: "fail",
+        summary: `Missing: ${missingDeps.join(", ")}`,
+        fixHints: [`Run: npm install ${missingDeps.join(" ")}`]
+      });
+    }
+  }
+  return results;
+}
+
+// cli/lib/doctor/configScan.ts
+import path10 from "node:path";
+import { readFile as readFile7 } from "node:fs/promises";
+var CONFIG_TS_FILE2 = "unrag.config.ts";
+async function runConfigCoherenceChecks(state) {
+  const results = [];
+  if (!state.configFileExists) {
+    results.push({
+      id: "config-coherence",
+      title: "Config coherence",
+      status: "skip",
+      summary: "unrag.config.ts not found; skipping coherence checks."
+    });
+    return results;
+  }
+  const configPath = path10.join(state.projectRoot, CONFIG_TS_FILE2);
+  const scanResult = await scanConfigFile(configPath);
+  if (!scanResult.configContent) {
+    results.push({
+      id: "config-coherence",
+      title: "Config coherence",
+      status: "warn",
+      summary: "Could not read unrag.config.ts for coherence analysis."
+    });
+    return results;
+  }
+  if (scanResult.parseWarnings.length > 0) {
+    results.push({
+      id: "config-scan-quality",
+      title: "Config analysis",
+      status: "warn",
+      summary: `Static analysis confidence: ${scanResult.confidence}`,
+      details: scanResult.parseWarnings
+    });
+  }
+  for (const extractor of state.installedExtractors) {
+    const extractorResult = checkExtractorCoherence(extractor, scanResult, state.installDir);
+    results.push(extractorResult);
+  }
+  if (state.installedExtractors.length === 0) {
+    results.push({
+      id: "config-extractors-summary",
+      title: "Extractor configuration",
+      status: "pass",
+      summary: "No extractors installed; nothing to check."
+    });
+  }
+  return results;
+}
+async function scanConfigFile(configPath) {
+  const result = {
+    configExists: false,
+    configContent: null,
+    registeredExtractors: [],
+    enabledFlags: [],
+    confidence: "low",
+    parseWarnings: []
+  };
+  if (!await exists(configPath)) {
+    return result;
+  }
+  result.configExists = true;
+  try {
+    result.configContent = await readFile7(configPath, "utf8");
+  } catch {
+    result.parseWarnings.push("Could not read config file.");
+    return result;
+  }
+  const content = result.configContent;
+  result.registeredExtractors = detectRegisteredExtractors(content);
+  result.enabledFlags = detectEnabledFlags(content);
+  if (content.includes("defineUnragConfig")) {
+    result.confidence = "high";
+  } else if (content.includes("createUnragEngine") || content.includes("createContextEngine")) {
+    result.confidence = "medium";
+  } else {
+    result.confidence = "low";
+    result.parseWarnings.push("Config file doesn't appear to use standard Unrag patterns.");
+  }
+  if (content.includes("...extractors") || content.includes("spread")) {
+    result.parseWarnings.push("Config uses spread operator for extractors; some may not be detected.");
+    result.confidence = "medium";
+  }
+  const enabledUsesEnv = /enabled\s*:\s*[^,\n}]*process\.env\./i.test(content) || /enabled\s*:\s*[^,\n}]*\bprocess\.env\[[^\]]+\]/i.test(content);
+  if (enabledUsesEnv) {
+    result.parseWarnings.push("Config uses environment variables for assetProcessing enabled flags; runtime values may differ.");
+    result.confidence = "medium";
+  }
+  return result;
+}
+function detectRegisteredExtractors(content) {
+  const found = [];
+  for (const [extractorId, factoryName] of Object.entries(EXTRACTOR_FACTORIES)) {
+    const pattern = new RegExp(`${factoryName}\\s*\\(`, "i");
+    if (pattern.test(content)) {
+      found.push(extractorId);
+    }
+    const importPattern = new RegExp(`import\\s*\\{[^}]*${factoryName}[^}]*\\}`, "i");
+    if (importPattern.test(content) && !found.includes(extractorId)) {
+      const usagePattern = new RegExp(`\\b${factoryName}\\b`, "g");
+      const matches = content.match(usagePattern);
+      if (matches && matches.length > 1) {
+        found.push(extractorId);
+      }
+    }
+  }
+  return found;
+}
+function detectEnabledFlags(content) {
+  const enabled = [];
+  const flagPatterns = {
+    "assetProcessing.pdf.llmExtraction.enabled": [
+      /pdf\s*:\s*\{[^}]*llmExtraction\s*:\s*\{[^}]*enabled\s*:\s*true/is,
+      /llmExtraction\s*:\s*\{[^}]*enabled\s*:\s*true/is
+    ],
+    "assetProcessing.pdf.textLayer.enabled": [
+      /pdf\s*:\s*\{[^}]*textLayer\s*:\s*\{[^}]*enabled\s*:\s*true/is,
+      /textLayer\s*:\s*\{[^}]*enabled\s*:\s*true/is
+    ],
+    "assetProcessing.pdf.ocr.enabled": [
+      /pdf\s*:\s*\{[^}]*ocr\s*:\s*\{[^}]*enabled\s*:\s*true/is
+    ],
+    "assetProcessing.image.ocr.enabled": [
+      /image\s*:\s*\{[^}]*ocr\s*:\s*\{[^}]*enabled\s*:\s*true/is
+    ],
+    "assetProcessing.image.captionLlm.enabled": [
+      /image\s*:\s*\{[^}]*captionLlm\s*:\s*\{[^}]*enabled\s*:\s*true/is
+    ],
+    "assetProcessing.audio.transcription.enabled": [
+      /audio\s*:\s*\{[^}]*transcription\s*:\s*\{[^}]*enabled\s*:\s*true/is
+    ],
+    "assetProcessing.video.transcription.enabled": [
+      /video\s*:\s*\{[^}]*transcription\s*:\s*\{[^}]*enabled\s*:\s*true/is
+    ],
+    "assetProcessing.video.frames.enabled": [
+      /video\s*:\s*\{[^}]*frames\s*:\s*\{[^}]*enabled\s*:\s*true/is
+    ],
+    "assetProcessing.file.text.enabled": [
+      /file\s*:\s*\{[^}]*text\s*:\s*\{[^}]*enabled\s*:\s*true/is
+    ],
+    "assetProcessing.file.docx.enabled": [
+      /file\s*:\s*\{[^}]*docx\s*:\s*\{[^}]*enabled\s*:\s*true/is
+    ],
+    "assetProcessing.file.pptx.enabled": [
+      /file\s*:\s*\{[^}]*pptx\s*:\s*\{[^}]*enabled\s*:\s*true/is
+    ],
+    "assetProcessing.file.xlsx.enabled": [
+      /file\s*:\s*\{[^}]*xlsx\s*:\s*\{[^}]*enabled\s*:\s*true/is
+    ]
+  };
+  for (const [flagPath, patterns] of Object.entries(flagPatterns)) {
+    for (const pattern of patterns) {
+      if (pattern.test(content)) {
+        enabled.push(flagPath);
+        break;
+      }
+    }
+  }
+  return enabled;
+}
+function checkExtractorCoherence(extractorId, scanResult, installDir) {
+  const isRegistered = scanResult.registeredExtractors.includes(extractorId);
+  const requiredFlags = EXTRACTOR_CONFIG_FLAGS[extractorId] ?? [];
+  const enabledRequiredFlags = requiredFlags.filter((f) => scanResult.enabledFlags.includes(f));
+  const missingFlags = requiredFlags.filter((f) => !scanResult.enabledFlags.includes(f));
+  const factoryName = EXTRACTOR_FACTORIES[extractorId];
+  const importPath = installDir ? `@unrag/extractors/${extractorId}` : `./lib/unrag/extractors/${extractorId}`;
+  if (isRegistered && missingFlags.length === 0) {
+    return {
+      id: `coherence-${extractorId}`,
+      title: `Extractor: ${extractorId}`,
+      status: "pass",
+      summary: "Installed, registered, and enabled.",
+      meta: {
+        registered: isRegistered,
+        enabledFlags: enabledRequiredFlags
+      }
+    };
+  }
+  if (!isRegistered) {
+    return {
+      id: `coherence-${extractorId}`,
+      title: `Extractor: ${extractorId}`,
+      status: "warn",
+      summary: "Installed but not registered in config.",
+      details: [
+        `Factory ${factoryName}() not found in unrag.config.ts`,
+        "Assets of this type will be skipped during ingestion."
+      ],
+      fixHints: [
+        `Import and add to extractors array:`,
+        `  import { ${factoryName} } from "${importPath}";`,
+        `  engine: { extractors: [${factoryName}()] }`
+      ],
+      docsLink: docsUrl("/docs/reference/cli#registering-extractors-manually"),
+      meta: {
+        registered: false,
+        confidence: scanResult.confidence
+      }
+    };
+  }
+  if (missingFlags.length > 0) {
+    return {
+      id: `coherence-${extractorId}`,
+      title: `Extractor: ${extractorId}`,
+      status: "warn",
+      summary: "Registered but required flags are disabled.",
+      details: [
+        `Missing enabled flags: ${missingFlags.join(", ")}`,
+        "The extractor is wired but assets won't be processed."
+      ],
+      fixHints: missingFlags.map((f) => `Set ${f.replace("assetProcessing.", "engine.assetProcessing.")}: true`),
+      meta: {
+        registered: true,
+        missingFlags,
+        confidence: scanResult.confidence
+      }
+    };
+  }
+  return {
+    id: `coherence-${extractorId}`,
+    title: `Extractor: ${extractorId}`,
+    status: "pass",
+    summary: "Configuration appears correct."
+  };
+}
+
+// cli/lib/doctor/dbChecks.ts
+import path11 from "node:path";
+async function runDbChecks(state, options) {
+  const results = [];
+  const dbUrlResult = resolveDbUrl(state, options);
+  if (!dbUrlResult.url) {
+    results.push({
+      id: "db-url",
+      title: "Database URL",
+      status: "fail",
+      summary: "Could not determine database connection string.",
+      details: dbUrlResult.details,
+      fixHints: [
+        "Set DATABASE_URL environment variable",
+        "Or use --database-url <url> flag",
+        "Or use --database-url-env <VAR_NAME> flag"
+      ],
+      docsLink: docsUrl("/docs/getting-started/database")
+    });
+    return results;
+  }
+  results.push({
+    id: "db-url",
+    title: "Database URL",
+    status: "pass",
+    summary: `Using ${dbUrlResult.source}`,
+    details: [redactConnectionString(dbUrlResult.url)]
+  });
+  let client = null;
+  try {
+    const pg = await import("pg");
+    const Pool = pg.default?.Pool ?? pg.Pool;
+    const pool = new Pool({ connectionString: dbUrlResult.url });
+    client = {
+      query: (sql, params) => pool.query(sql, params),
+      end: () => pool.end()
+    };
+    const connectivityResult = await checkConnectivity(client);
+    results.push(connectivityResult);
+    if (connectivityResult.status === "fail") {
+      return results;
+    }
+    const pgvectorResult = await checkPgvector(client);
+    results.push(pgvectorResult);
+    const installDirFull = state.installDir ? path11.join(state.projectRoot, state.installDir) : null;
+    const tableNames = await inferTableNames(installDirFull ?? "", state.storeAdapter);
+    const schemaResults = await checkSchema(client, options.schema, tableNames);
+    results.push(...schemaResults);
+    const indexResults = await checkIndexes(client, options.schema, tableNames);
+    results.push(...indexResults);
+    const dimensionResults = await checkDimensionConsistency(client, options.schema, tableNames, options.scope);
+    results.push(...dimensionResults);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    results.push({
+      id: "db-connection",
+      title: "Database connection",
+      status: "fail",
+      summary: `Connection failed: ${message}`,
+      fixHints: [
+        "Check that DATABASE_URL is correct",
+        "Ensure the database server is running",
+        "Check network connectivity and firewall rules"
+      ]
+    });
+  } finally {
+    if (client) {
+      await client.end().catch(() => {});
+    }
+  }
+  return results;
+}
+function resolveDbUrl(state, options) {
+  const details = [];
+  if (options.databaseUrl) {
+    return {
+      url: options.databaseUrl,
+      source: "--database-url flag",
+      details: ["Using explicitly provided connection string."]
+    };
+  }
+  if (options.databaseUrlEnv) {
+    const value = process.env[options.databaseUrlEnv];
+    if (value) {
+      return {
+        url: value,
+        source: `${options.databaseUrlEnv} (via --database-url-env)`,
+        details: [`Using env var specified by flag: ${options.databaseUrlEnv}`]
+      };
+    }
+    details.push(`${options.databaseUrlEnv} is not set (specified via --database-url-env).`);
+  }
+  if (state.inferredDbEnvVar) {
+    const value = process.env[state.inferredDbEnvVar];
+    if (value) {
+      return {
+        url: value,
+        source: `${state.inferredDbEnvVar} (inferred from config)`,
+        details: [`Found ${state.inferredDbEnvVar} in your database configuration.`]
+      };
+    }
+    details.push(`${state.inferredDbEnvVar} inferred from config but not set.`);
+  }
+  if (process.env.DATABASE_URL) {
+    return {
+      url: process.env.DATABASE_URL,
+      source: "DATABASE_URL",
+      details: ["Using standard DATABASE_URL environment variable."]
+    };
+  }
+  details.push("DATABASE_URL is not set.");
+  return { url: null, source: "", details };
+}
+function redactConnectionString(url) {
+  try {
+    const parsed = new URL(url);
+    if (parsed.password) {
+      parsed.password = "****";
+    }
+    return parsed.toString().replace(/\*\*\*\*@/, "****@");
+  } catch {
+    return url.replace(/:([^:@]+)@/, ":****@");
+  }
+}
+async function checkConnectivity(client) {
+  try {
+    const versionResult = await client.query("SELECT version()");
+    const version = versionResult.rows[0]?.version ?? "unknown";
+    const userResult = await client.query("SELECT current_user");
+    const user = userResult.rows[0]?.current_user ?? "unknown";
+    const dbResult = await client.query("SELECT current_database()");
+    const database = dbResult.rows[0]?.current_database ?? "unknown";
+    const versionMatch = version.match(/PostgreSQL (\d+\.\d+)/);
+    const pgVersion = versionMatch ? versionMatch[1] : version.slice(0, 50);
+    return {
+      id: "db-connectivity",
+      title: "Database connectivity",
+      status: "pass",
+      summary: "Successfully connected to PostgreSQL.",
+      details: [
+        `Version: PostgreSQL ${pgVersion}`,
+        `Database: ${database}`,
+        `User: ${user}`
+      ]
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      id: "db-connectivity",
+      title: "Database connectivity",
+      status: "fail",
+      summary: `Connection test failed: ${message}`
+    };
+  }
+}
+async function checkPgvector(client) {
+  try {
+    const extResult = await client.query("SELECT extname, extversion FROM pg_extension WHERE extname = 'vector'");
+    if (extResult.rows.length === 0) {
+      return {
+        id: "db-pgvector",
+        title: "pgvector extension",
+        status: "fail",
+        summary: "pgvector extension is not installed.",
+        fixHints: [
+          "Run: CREATE EXTENSION IF NOT EXISTS vector;",
+          "You may need superuser privileges or extension preinstalled."
+        ],
+        docsLink: docsUrl("/docs/getting-started/database#enabling-pgvector")
+      };
+    }
+    const version = extResult.rows[0]?.extversion ?? "unknown";
+    try {
+      await client.query("SELECT '[1,2,3]'::vector <=> '[1,2,3]'::vector");
+    } catch {
+      return {
+        id: "db-pgvector",
+        title: "pgvector extension",
+        status: "warn",
+        summary: `pgvector ${version} installed but operator test failed.`,
+        details: ["The <=> (cosine distance) operator may not be available."]
+      };
+    }
+    let hasHnsw = false;
+    try {
+      const amResult = await client.query("SELECT amname FROM pg_am WHERE amname = 'hnsw'");
+      hasHnsw = amResult.rows.length > 0;
+    } catch {}
+    return {
+      id: "db-pgvector",
+      title: "pgvector extension",
+      status: "pass",
+      summary: `pgvector ${version} installed and working.`,
+      details: hasHnsw ? ["HNSW index support available."] : ["HNSW index support not detected (requires pgvector 0.5.0+)."],
+      meta: { version, hasHnsw }
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      id: "db-pgvector",
+      title: "pgvector extension",
+      status: "fail",
+      summary: `pgvector check failed: ${message}`
+    };
+  }
+}
+async function checkSchema(client, schema, tableNames) {
+  const results = [];
+  for (const [logicalName, tableName] of Object.entries(tableNames)) {
+    const tableResult = await checkTable(client, schema, tableName, logicalName);
+    results.push(tableResult);
+  }
+  const fkResult = await checkForeignKeys(client, schema, tableNames);
+  results.push(fkResult);
+  return results;
+}
+async function checkTable(client, schema, tableName, logicalName) {
+  const expectedColumns = {
+    documents: ["id", "source_id", "content", "metadata"],
+    chunks: ["id", "document_id", "source_id", "idx", "content", "token_count", "metadata"],
+    embeddings: ["chunk_id", "embedding", "embedding_dimension"]
+  };
+  try {
+    const tableResult = await client.query(`SELECT EXISTS (
+        SELECT FROM information_schema.tables 
+        WHERE table_schema = $1 AND table_name = $2
+      )`, [schema, tableName]);
+    if (!tableResult.rows[0]?.exists) {
+      return {
+        id: `db-table-${logicalName}`,
+        title: `Table: ${tableName}`,
+        status: "fail",
+        summary: `Table ${schema}.${tableName} does not exist.`,
+        fixHints: [
+          "Run the schema migration to create Unrag tables.",
+          "See lib/unrag/unrag.md for the required schema."
+        ],
+        docsLink: docsUrl("/docs/getting-started/database#creating-the-schema")
+      };
+    }
+    const columnResult = await client.query(`SELECT column_name FROM information_schema.columns 
+       WHERE table_schema = $1 AND table_name = $2`, [schema, tableName]);
+    const actualColumns = columnResult.rows.map((r) => r.column_name);
+    const expected = expectedColumns[logicalName] ?? [];
+    const missingColumns = expected.filter((c) => !actualColumns.includes(c));
+    if (missingColumns.length > 0) {
+      return {
+        id: `db-table-${logicalName}`,
+        title: `Table: ${tableName}`,
+        status: "warn",
+        summary: `Table exists but missing columns: ${missingColumns.join(", ")}`,
+        details: [
+          `Expected: ${expected.join(", ")}`,
+          `Found: ${actualColumns.join(", ")}`
+        ]
+      };
+    }
+    return {
+      id: `db-table-${logicalName}`,
+      title: `Table: ${tableName}`,
+      status: "pass",
+      summary: "Table exists with expected columns.",
+      meta: { columns: actualColumns }
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      id: `db-table-${logicalName}`,
+      title: `Table: ${tableName}`,
+      status: "fail",
+      summary: `Schema check failed: ${message}`
+    };
+  }
+}
+async function checkForeignKeys(client, schema, tableNames) {
+  try {
+    const fkResult = await client.query(`SELECT 
+        tc.constraint_name,
+        tc.table_name,
+        kcu.column_name,
+        ccu.table_name AS foreign_table_name,
+        rc.delete_rule
+       FROM information_schema.table_constraints tc
+       JOIN information_schema.key_column_usage kcu 
+         ON tc.constraint_name = kcu.constraint_name
+       JOIN information_schema.constraint_column_usage ccu 
+         ON tc.constraint_name = ccu.constraint_name
+       JOIN information_schema.referential_constraints rc
+         ON tc.constraint_name = rc.constraint_name
+       WHERE tc.constraint_type = 'FOREIGN KEY'
+         AND tc.table_schema = $1
+         AND tc.table_name IN ($2, $3, $4)`, [schema, tableNames.documents, tableNames.chunks, tableNames.embeddings]);
+    const fks = fkResult.rows;
+    const issues = [];
+    const chunksFk = fks.find((f) => f.table_name === tableNames.chunks && f.column_name === "document_id");
+    if (!chunksFk) {
+      issues.push(`${tableNames.chunks}.document_id: FK not found`);
+    } else if (chunksFk.delete_rule !== "CASCADE") {
+      issues.push(`${tableNames.chunks}.document_id: delete rule is ${chunksFk.delete_rule}, expected CASCADE`);
+    }
+    const embeddingsFk = fks.find((f) => f.table_name === tableNames.embeddings && f.column_name === "chunk_id");
+    if (!embeddingsFk) {
+      issues.push(`${tableNames.embeddings}.chunk_id: FK not found`);
+    } else if (embeddingsFk.delete_rule !== "CASCADE") {
+      issues.push(`${tableNames.embeddings}.chunk_id: delete rule is ${embeddingsFk.delete_rule}, expected CASCADE`);
+    }
+    if (issues.length === 0) {
+      return {
+        id: "db-foreign-keys",
+        title: "Foreign key constraints",
+        status: "pass",
+        summary: "CASCADE delete constraints are properly configured."
+      };
+    }
+    return {
+      id: "db-foreign-keys",
+      title: "Foreign key constraints",
+      status: "warn",
+      summary: "Some foreign key constraints may be misconfigured.",
+      details: issues,
+      fixHints: [
+        "Ensure FK constraints use ON DELETE CASCADE",
+        "This ensures chunks/embeddings are deleted when documents are removed."
+      ]
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      id: "db-foreign-keys",
+      title: "Foreign key constraints",
+      status: "warn",
+      summary: `Could not verify FK constraints: ${message}`
+    };
+  }
+}
+async function checkIndexes(client, schema, tableNames) {
+  const results = [];
+  try {
+    const indexResult = await client.query(`SELECT tablename, indexname, indexdef 
+       FROM pg_indexes 
+       WHERE schemaname = $1 
+         AND tablename IN ($2, $3, $4)`, [schema, tableNames.documents, tableNames.chunks, tableNames.embeddings]);
+    const indexes = indexResult.rows;
+    const chunksSourceIdx = indexes.find((i) => i.tablename === tableNames.chunks && i.indexdef.toLowerCase().includes("source_id"));
+    results.push({
+      id: "db-index-chunks-source",
+      title: `Index: ${tableNames.chunks}(source_id)`,
+      status: chunksSourceIdx ? "pass" : "warn",
+      summary: chunksSourceIdx ? "Index exists for source_id filtering." : "Recommended index on source_id not found.",
+      fixHints: chunksSourceIdx ? undefined : [
+        `CREATE INDEX IF NOT EXISTS ${tableNames.chunks}_source_id_idx ON ${tableNames.chunks}(source_id);`
+      ]
+    });
+    const docsSourceIdx = indexes.find((i) => i.tablename === tableNames.documents && i.indexdef.toLowerCase().includes("source_id"));
+    results.push({
+      id: "db-index-docs-source",
+      title: `Index: ${tableNames.documents}(source_id)`,
+      status: docsSourceIdx ? "pass" : "warn",
+      summary: docsSourceIdx ? "Index exists for source_id filtering." : "Recommended index on source_id not found.",
+      fixHints: docsSourceIdx ? undefined : [
+        `CREATE INDEX IF NOT EXISTS ${tableNames.documents}_source_id_idx ON ${tableNames.documents}(source_id);`
+      ]
+    });
+    const vectorIdx = indexes.find((i) => i.tablename === tableNames.embeddings && (i.indexdef.toLowerCase().includes("hnsw") || i.indexdef.toLowerCase().includes("ivfflat")));
+    const countResult = await client.query(`SELECT COUNT(*) as count FROM ${schema}.${tableNames.embeddings}`);
+    const rowCount = parseInt(countResult.rows[0]?.count ?? "0", 10);
+    if (vectorIdx) {
+      results.push({
+        id: "db-index-vector",
+        title: "Vector index",
+        status: "pass",
+        summary: "Vector index found for similarity search.",
+        details: [vectorIdx.indexdef],
+        meta: { rowCount }
+      });
+    } else if (rowCount > 50000) {
+      results.push({
+        id: "db-index-vector",
+        title: "Vector index",
+        status: "warn",
+        summary: `No vector index found (${rowCount.toLocaleString()} embeddings).`,
+        details: [
+          "Large datasets benefit significantly from HNSW indexing.",
+          "Without an index, similarity search scans all rows."
+        ],
+        fixHints: [
+          `CREATE INDEX IF NOT EXISTS ${tableNames.embeddings}_hnsw_idx`,
+          `ON ${tableNames.embeddings} USING hnsw (embedding vector_cosine_ops);`
+        ],
+        docsLink: docsUrl("/docs/concepts/performance"),
+        meta: { rowCount }
+      });
+    } else {
+      results.push({
+        id: "db-index-vector",
+        title: "Vector index",
+        status: "pass",
+        summary: `No vector index (${rowCount.toLocaleString()} embeddings).`,
+        details: [
+          "Current dataset size is small enough for sequential scan.",
+          "Consider adding HNSW index when exceeding ~50k embeddings."
+        ],
+        meta: { rowCount }
+      });
+    }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    results.push({
+      id: "db-indexes",
+      title: "Index validation",
+      status: "warn",
+      summary: `Could not check indexes: ${message}`
+    });
+  }
+  return results;
+}
+async function checkDimensionConsistency(client, schema, tableNames, scope) {
+  const results = [];
+  try {
+    const nullDimSql = scope ? `SELECT COUNT(*) as count
+         FROM ${schema}.${tableNames.embeddings} e
+         JOIN ${schema}.${tableNames.chunks} c ON e.chunk_id = c.id
+         WHERE c.source_id LIKE $1
+           AND (e.embedding_dimension IS NULL OR e.embedding_dimension = 0)` : `SELECT COUNT(*) as count
+         FROM ${schema}.${tableNames.embeddings} e
+         WHERE (e.embedding_dimension IS NULL OR e.embedding_dimension = 0)`;
+    const nullDimResult = await client.query(nullDimSql, scope ? [scope + "%"] : []);
+    const nullCount = parseInt(nullDimResult.rows[0]?.count ?? "0", 10);
+    if (nullCount > 0) {
+      results.push({
+        id: "db-dim-nulls",
+        title: "Embedding dimensions",
+        status: "warn",
+        summary: `${nullCount} embeddings have NULL or 0 dimension.`,
+        details: [
+          "This may indicate incomplete ingestion or migration issues.",
+          scope ? `Scope: ${scope}*` : "Checking all embeddings."
+        ]
+      });
+    }
+    const dimSql = scope ? `SELECT e.embedding_dimension, COUNT(*) as count
+         FROM ${schema}.${tableNames.embeddings} e
+         JOIN ${schema}.${tableNames.chunks} c ON e.chunk_id = c.id
+         WHERE c.source_id LIKE $1
+           AND e.embedding_dimension IS NOT NULL AND e.embedding_dimension > 0
+         GROUP BY e.embedding_dimension
+         ORDER BY count DESC` : `SELECT e.embedding_dimension, COUNT(*) as count
+         FROM ${schema}.${tableNames.embeddings} e
+         WHERE e.embedding_dimension IS NOT NULL AND e.embedding_dimension > 0
+         GROUP BY e.embedding_dimension
+         ORDER BY count DESC`;
+    const dimResult = await client.query(dimSql, scope ? [scope + "%"] : []);
+    const dimensions = dimResult.rows;
+    if (dimensions.length === 0) {
+      results.push({
+        id: "db-dim-consistency",
+        title: "Dimension consistency",
+        status: "pass",
+        summary: "No embeddings found to check.",
+        details: scope ? [`Scope: ${scope}*`] : undefined
+      });
+    } else if (dimensions.length === 1) {
+      const dim = dimensions[0];
+      results.push({
+        id: "db-dim-consistency",
+        title: "Dimension consistency",
+        status: "pass",
+        summary: `All embeddings use ${dim.embedding_dimension} dimensions.`,
+        details: [
+          `Total: ${parseInt(dim.count, 10).toLocaleString()} embeddings`,
+          scope ? `Scope: ${scope}*` : "All embeddings checked."
+        ],
+        meta: { dimension: dim.embedding_dimension, count: parseInt(dim.count, 10) }
+      });
+    } else {
+      const details = dimensions.map((d) => `${d.embedding_dimension} dimensions: ${parseInt(d.count, 10).toLocaleString()} embeddings`);
+      results.push({
+        id: "db-dim-consistency",
+        title: "Dimension consistency",
+        status: "warn",
+        summary: `Mixed dimensions found (${dimensions.length} different values).`,
+        details: [
+          ...details,
+          "",
+          "Mixed dimensions can cause retrieval errors.",
+          "This typically happens when changing embedding models."
+        ],
+        fixHints: [
+          "Use --scope to isolate different embedding sets",
+          "Re-ingest documents with the current model",
+          "Or separate content by sourceId prefix"
+        ],
+        docsLink: docsUrl("/docs/concepts/architecture"),
+        meta: {
+          dimensions: dimensions.map((d) => ({
+            dimension: d.embedding_dimension,
+            count: parseInt(d.count, 10)
+          }))
+        }
+      });
+    }
+    try {
+      const sampleResult = await client.query(`SELECT 
+           chunk_id, 
+           embedding_dimension as stored_dim,
+           vector_dims(embedding) as actual_dim
+         FROM ${schema}.${tableNames.embeddings}
+         WHERE embedding IS NOT NULL
+         LIMIT 100`);
+      const mismatches = sampleResult.rows.filter((r) => r.stored_dim !== r.actual_dim);
+      if (mismatches.length > 0) {
+        results.push({
+          id: "db-dim-mismatch",
+          title: "Dimension metadata",
+          status: "warn",
+          summary: `${mismatches.length} sampled rows have dimension mismatch.`,
+          details: [
+            "embedding_dimension column doesn't match actual vector length.",
+            "This may cause issues with some operations."
+          ]
+        });
+      }
+    } catch {}
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    results.push({
+      id: "db-dimensions",
+      title: "Dimension checks",
+      status: "warn",
+      summary: `Could not check dimensions: ${message}`
+    });
+  }
+  return results;
+}
+
+// cli/lib/doctor/output.ts
+var STATUS_ICONS = {
+  pass: "✓",
+  warn: "⚠",
+  fail: "✗",
+  skip: "○"
+};
+var STATUS_COLORS = {
+  pass: (s) => `\x1B[32m${s}\x1B[0m`,
+  warn: (s) => `\x1B[33m${s}\x1B[0m`,
+  fail: (s) => `\x1B[31m${s}\x1B[0m`,
+  skip: (s) => `\x1B[90m${s}\x1B[0m`
+};
+function formatReport(report, options = {}) {
+  const lines = [];
+  lines.push("");
+  for (const group of report.groups) {
+    if (group.results.length === 0)
+      continue;
+    lines.push(`${group.title}`);
+    lines.push("─".repeat(group.title.length));
+    for (const result of group.results) {
+      lines.push(formatResult(result));
+    }
+    lines.push("");
+  }
+  lines.push("Summary");
+  lines.push("─".repeat(7));
+  const { pass, warn, fail, skip, total } = report.summary;
+  const summaryParts = [];
+  if (pass > 0)
+    summaryParts.push(STATUS_COLORS.pass(`${pass} passed`));
+  if (warn > 0)
+    summaryParts.push(STATUS_COLORS.warn(`${warn} warnings`));
+  if (fail > 0)
+    summaryParts.push(STATUS_COLORS.fail(`${fail} failed`));
+  if (skip > 0)
+    summaryParts.push(STATUS_COLORS.skip(`${skip} skipped`));
+  lines.push(`${summaryParts.join(", ")} (${total} total)`);
+  if (fail > 0) {
+    lines.push("");
+    lines.push(STATUS_COLORS.fail("Some checks failed. See details above."));
+  } else if (warn > 0) {
+    lines.push("");
+    lines.push(STATUS_COLORS.warn("All checks passed with warnings. Review recommended."));
+  } else {
+    lines.push("");
+    lines.push(STATUS_COLORS.pass("All checks passed!"));
+  }
+  if (options.showDbHint) {
+    lines.push("");
+    lines.push(STATUS_COLORS.skip("Tip: Run `unrag doctor --db` to also check database connectivity and schema."));
+  }
+  return lines.join(`
+`);
+}
+function formatResult(result) {
+  const lines = [];
+  const icon = STATUS_ICONS[result.status];
+  const color = STATUS_COLORS[result.status];
+  lines.push(`  ${color(icon)} ${result.title}: ${result.summary}`);
+  if (result.details && result.details.length > 0) {
+    for (const detail of result.details) {
+      if (detail === "") {
+        lines.push("");
+      } else {
+        lines.push(`      ${detail}`);
+      }
+    }
+  }
+  if (result.fixHints && result.fixHints.length > 0) {
+    lines.push(`      Fix:`);
+    for (const hint of result.fixHints) {
+      lines.push(`        ${hint}`);
+    }
+  }
+  if (result.docsLink) {
+    lines.push(`      Docs: ${result.docsLink}`);
+  }
+  return lines.join(`
+`);
+}
+function formatJson(report) {
+  return JSON.stringify(report, null, 2);
+}
+
+// cli/lib/doctor/env.ts
+import path12 from "node:path";
+import { readFile as readFile8 } from "node:fs/promises";
+async function loadEnvFilesFromList(options) {
+  const loadedFiles = [];
+  const loadedKeys = [];
+  const skippedKeys = [];
+  const warnings = [];
+  for (const rel of options.files) {
+    if (!rel.trim())
+      continue;
+    const abs = path12.isAbsolute(rel) ? rel : path12.join(options.projectRoot, rel);
+    if (!await exists(abs))
+      continue;
+    try {
+      const raw = await readFile8(abs, "utf8");
+      const parsed = parseDotenv(raw);
+      for (const [k, v] of Object.entries(parsed)) {
+        if (process.env[k] !== undefined) {
+          skippedKeys.push(k);
+          continue;
+        }
+        process.env[k] = v;
+        loadedKeys.push(k);
+      }
+      loadedFiles.push(rel);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      warnings.push(`Failed to read ${rel}: ${msg}`);
+    }
+  }
+  return {
+    loadedFiles,
+    loadedKeys,
+    skippedKeys,
+    warnings
+  };
+}
+function parseDotenv(raw) {
+  const out = {};
+  for (const line of raw.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#"))
+      continue;
+    const l = trimmed.startsWith("export ") ? trimmed.slice(7).trim() : trimmed;
+    const eq = l.indexOf("=");
+    if (eq <= 0)
+      continue;
+    const key = l.slice(0, eq).trim();
+    if (!key)
+      continue;
+    let value = l.slice(eq + 1).trim();
+    if (!value.startsWith('"') && !value.startsWith("'")) {
+      const hash = value.indexOf(" #");
+      if (hash >= 0)
+        value = value.slice(0, hash).trim();
+    }
+    if (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'")) {
+      value = value.slice(1, -1);
+    }
+    if (trimmed.includes('"')) {
+      value = value.replace(/\\n/g, `
+`).replace(/\\r/g, "\r").replace(/\\t/g, "\t");
+    }
+    out[key] = value;
+  }
+  return out;
+}
+
+// cli/lib/doctor/doctorConfig.ts
+import path13 from "node:path";
+var DOCTOR_CONFIG_VERSION = 1;
+var DEFAULT_ENV_LOAD_FILES = [
+  ".env",
+  ".env.local",
+  ".env.${NODE_ENV}",
+  ".env.${NODE_ENV}.local"
+];
+async function readDoctorConfig(configPath) {
+  if (!await exists(configPath)) {
+    return null;
+  }
+  const raw = await readJsonFile(configPath);
+  if (!raw || typeof raw !== "object") {
+    return null;
+  }
+  if (raw.version !== undefined && typeof raw.version !== "number") {
+    return null;
+  }
+  return raw;
+}
+function mergeDoctorArgsWithConfig(args, config, projectRoot) {
+  if (!config)
+    return args;
+  const merged = { ...args };
+  if (!merged.installDir && config.installDir) {
+    merged.installDir = config.installDir;
+  }
+  if (!merged.schema && config.db?.schema) {
+    merged.schema = config.db.schema;
+  }
+  if (merged.scope === undefined && config.defaults?.scope !== undefined) {
+    merged.scope = config.defaults.scope ?? undefined;
+  }
+  if (merged.strict === undefined && config.defaults?.strict !== undefined) {
+    merged.strict = config.defaults.strict;
+  }
+  if (!merged.databaseUrlEnv && config.env?.databaseUrlEnv) {
+    merged.databaseUrlEnv = config.env.databaseUrlEnv;
+  }
+  return merged;
+}
+function getEnvFilesToLoad(config, extraEnvFile) {
+  const files = config?.env?.loadFiles ?? DEFAULT_ENV_LOAD_FILES;
+  const nodeEnv = "development".trim();
+  const interpolated = files.map((f) => f.replace(/\$\{NODE_ENV\}/g, nodeEnv));
+  if (extraEnvFile) {
+    return [extraEnvFile, ...interpolated.filter((f) => f !== extraEnvFile)];
+  }
+  return interpolated;
+}
+function resolveConfigPath(projectRoot, configPath) {
+  if (path13.isAbsolute(configPath)) {
+    return configPath;
+  }
+  return path13.join(projectRoot, configPath);
+}
+
+// cli/commands/doctor-setup.ts
+import path14 from "node:path";
+import {
+  cancel as cancel3,
+  confirm as confirm3,
+  isCancel as isCancel3,
+  multiselect,
+  outro as outro3,
+  select as select2,
+  spinner,
+  text as text2
+} from "@clack/prompts";
+var DEFAULT_CONFIG_PATH = ".unrag/doctor.json";
+function parseSetupArgs(args) {
+  const out = {};
+  for (let i = 0;i < args.length; i++) {
+    const a = args[i];
+    if (a === "--yes" || a === "-y") {
+      out.yes = true;
+      continue;
+    }
+    if (a === "--project-root") {
+      const v = args[i + 1];
+      if (v && !v.startsWith("-")) {
+        out.projectRoot = v;
+        i++;
+      }
+      continue;
+    }
+    if (a === "--config") {
+      const v = args[i + 1];
+      if (v && !v.startsWith("-")) {
+        out.configPath = v;
+        i++;
+      }
+      continue;
+    }
+  }
+  return out;
+}
+function renderSetupHelp() {
+  return [
+    "unrag doctor setup — configure doctor for your project",
+    "",
+    "Usage:",
+    "  unrag doctor setup [options]",
+    "",
+    "Options:",
+    "  --yes, -y               Non-interactive; accept defaults",
+    "  --project-root <path>   Override project root directory",
+    "  --config <path>         Output config file path (default: .unrag/doctor.json)",
+    "",
+    "This command will:",
+    "  1. Detect your Unrag installation settings",
+    "  2. Create a doctor config file with your project-specific settings",
+    "  3. Add convenient npm scripts to your package.json:",
+    "     - unrag:doctor      Run static checks",
+    "     - unrag:doctor:db   Run with database checks",
+    "     - unrag:doctor:ci   Run strict mode with JSON output for CI",
+    "",
+    "Examples:",
+    "  unrag doctor setup                  Interactive setup",
+    "  unrag doctor setup --yes            Use detected defaults",
+    "  unrag doctor setup --config .doctor.json   Custom config location",
+    "",
+    "Docs:",
+    `  ${docsUrl("/docs/reference/cli")}`
+  ].join(`
+`);
+}
+async function doctorSetupCommand(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    outro3(renderSetupHelp());
+    return;
+  }
+  const parsed = parseSetupArgs(args);
+  const nonInteractive = Boolean(parsed.yes) || !process.stdin.isTTY;
+  const projectRoot = parsed.projectRoot ?? await tryFindProjectRoot(process.cwd()) ?? process.cwd();
+  const s = spinner();
+  s.start("Detecting project configuration...");
+  const state = await inferInstallState({
+    projectRootOverride: projectRoot
+  });
+  const tableNames = state.installDir ? await inferTableNames(path14.join(projectRoot, state.installDir), state.storeAdapter) : { documents: "documents", chunks: "chunks", embeddings: "embeddings" };
+  s.stop("Configuration detected.");
+  const configPathAnswer = parsed.configPath ? parsed.configPath : nonInteractive ? DEFAULT_CONFIG_PATH : await text2({
+    message: "Config file path",
+    initialValue: DEFAULT_CONFIG_PATH,
+    validate: (v) => {
+      if (!v.trim())
+        return "Config path is required";
+      if (!v.endsWith(".json"))
+        return "Config file must be .json";
+      return;
+    }
+  });
+  if (isCancel3(configPathAnswer)) {
+    cancel3("Cancelled.");
+    return;
+  }
+  const configPath = String(configPathAnswer).trim();
+  const configFullPath = path14.isAbsolute(configPath) ? configPath : path14.join(projectRoot, configPath);
+  if (await exists(configFullPath)) {
+    if (nonInteractive) {} else {
+      const overwrite = await confirm3({
+        message: `Config file ${configPath} already exists. Overwrite?`,
+        initialValue: false
+      });
+      if (isCancel3(overwrite)) {
+        cancel3("Cancelled.");
+        return;
+      }
+      if (!overwrite) {
+        outro3("Keeping existing config file.");
+        return;
+      }
+    }
+  }
+  const installDirAnswer = nonInteractive ? state.installDir ?? "lib/unrag" : await text2({
+    message: "Unrag install directory",
+    initialValue: state.installDir ?? "lib/unrag",
+    validate: (v) => {
+      if (!v.trim())
+        return "Install directory is required";
+      return;
+    }
+  });
+  if (isCancel3(installDirAnswer)) {
+    cancel3("Cancelled.");
+    return;
+  }
+  const installDir = String(installDirAnswer).trim();
+  const envFilesAnswer = nonInteractive ? DEFAULT_ENV_LOAD_FILES : await multiselect({
+    message: "Which .env files should doctor load? (space to toggle)",
+    options: [
+      { value: ".env", label: ".env", hint: "base env" },
+      { value: ".env.local", label: ".env.local", hint: "local overrides" },
+      {
+        value: ".env.${NODE_ENV}",
+        label: ".env.${NODE_ENV}",
+        hint: "e.g. .env.development"
+      },
+      {
+        value: ".env.${NODE_ENV}.local",
+        label: ".env.${NODE_ENV}.local",
+        hint: "e.g. .env.development.local"
+      }
+    ],
+    initialValues: DEFAULT_ENV_LOAD_FILES,
+    required: false
+  });
+  if (isCancel3(envFilesAnswer)) {
+    cancel3("Cancelled.");
+    return;
+  }
+  const envFiles = envFilesAnswer;
+  const dbEnvVarDefault = state.inferredDbEnvVar ?? "DATABASE_URL";
+  const dbEnvVarAnswer = nonInteractive ? dbEnvVarDefault : await text2({
+    message: "Database URL environment variable name",
+    initialValue: dbEnvVarDefault,
+    validate: (v) => {
+      if (!v.trim())
+        return "Env var name is required";
+      if (!/^[A-Z_][A-Z0-9_]*$/i.test(v))
+        return "Invalid env var name";
+      return;
+    }
+  });
+  if (isCancel3(dbEnvVarAnswer)) {
+    cancel3("Cancelled.");
+    return;
+  }
+  const databaseUrlEnv = String(dbEnvVarAnswer).trim();
+  const schemaAnswer = nonInteractive ? "public" : await text2({
+    message: "Database schema name",
+    initialValue: "public"
+  });
+  if (isCancel3(schemaAnswer)) {
+    cancel3("Cancelled.");
+    return;
+  }
+  const schema = String(schemaAnswer).trim() || "public";
+  const documentsTableAnswer = nonInteractive ? tableNames.documents : await text2({
+    message: "Documents table name",
+    initialValue: tableNames.documents
+  });
+  if (isCancel3(documentsTableAnswer)) {
+    cancel3("Cancelled.");
+    return;
+  }
+  const documentsTable = String(documentsTableAnswer).trim() || "documents";
+  const chunksTableAnswer = nonInteractive ? tableNames.chunks : await text2({
+    message: "Chunks table name",
+    initialValue: tableNames.chunks
+  });
+  if (isCancel3(chunksTableAnswer)) {
+    cancel3("Cancelled.");
+    return;
+  }
+  const chunksTable = String(chunksTableAnswer).trim() || "chunks";
+  const embeddingsTableAnswer = nonInteractive ? tableNames.embeddings : await text2({
+    message: "Embeddings table name",
+    initialValue: tableNames.embeddings
+  });
+  if (isCancel3(embeddingsTableAnswer)) {
+    cancel3("Cancelled.");
+    return;
+  }
+  const embeddingsTable = String(embeddingsTableAnswer).trim() || "embeddings";
+  const scopeAnswer = nonInteractive ? "" : await text2({
+    message: "Default scope prefix for dimension checks (optional, press enter to skip)",
+    initialValue: ""
+  });
+  if (isCancel3(scopeAnswer)) {
+    cancel3("Cancelled.");
+    return;
+  }
+  const defaultScope = String(scopeAnswer).trim() || null;
+  const strictAnswer = nonInteractive ? false : await confirm3({
+    message: "Enable strict mode by default? (treat warnings as failures)",
+    initialValue: false
+  });
+  if (isCancel3(strictAnswer)) {
+    cancel3("Cancelled.");
+    return;
+  }
+  const strictDefault = Boolean(strictAnswer);
+  const ciIncludeDbAnswer = nonInteractive ? true : await confirm3({
+    message: "Should CI script include database checks (--db)?",
+    initialValue: true
+  });
+  if (isCancel3(ciIncludeDbAnswer)) {
+    cancel3("Cancelled.");
+    return;
+  }
+  const ciIncludeDb = Boolean(ciIncludeDbAnswer);
+  const ciStrictAnswer = nonInteractive ? true : await confirm3({
+    message: "Should CI script use strict mode (--strict)?",
+    initialValue: true
+  });
+  if (isCancel3(ciStrictAnswer)) {
+    cancel3("Cancelled.");
+    return;
+  }
+  const ciStrict = Boolean(ciStrictAnswer);
+  const config = {
+    version: DOCTOR_CONFIG_VERSION,
+    installDir,
+    env: {
+      loadFiles: envFiles,
+      databaseUrlEnv
+    },
+    db: {
+      schema,
+      tables: {
+        documents: documentsTable,
+        chunks: chunksTable,
+        embeddings: embeddingsTable
+      }
+    },
+    defaults: {
+      scope: defaultScope,
+      strict: strictDefault
+    }
+  };
+  const configDir = path14.dirname(configFullPath);
+  if (!await exists(configDir)) {
+    await ensureDir(configDir);
+  }
+  await writeJsonFile(configFullPath, config);
+  const relConfigPath = path14.relative(projectRoot, configFullPath);
+  const scripts = {
+    "unrag:doctor": `unrag doctor --config ${relConfigPath}`,
+    "unrag:doctor:db": `unrag doctor --config ${relConfigPath} --db`,
+    "unrag:doctor:ci": buildCiScript(relConfigPath, ciIncludeDb, ciStrict)
+  };
+  const pkgPath = path14.join(projectRoot, "package.json");
+  const pkg = await readJsonFile(pkgPath);
+  if (!pkg) {
+    outro3([
+      `Created ${relConfigPath}`,
+      "",
+      "Could not find package.json to add scripts.",
+      "Add these scripts manually:",
+      ...Object.entries(scripts).map(([k, v]) => `  "${k}": "${v}"`)
+    ].join(`
+`));
+    return;
+  }
+  const existingScripts = pkg.scripts ?? {};
+  const conflictingScripts = Object.keys(scripts).filter((k) => (k in existingScripts));
+  let scriptsToAdd = scripts;
+  if (conflictingScripts.length > 0 && !nonInteractive) {
+    for (const scriptName of conflictingScripts) {
+      const action = await select2({
+        message: `Script "${scriptName}" already exists. What would you like to do?`,
+        options: [
+          { value: "keep", label: "Keep existing", hint: existingScripts[scriptName] },
+          { value: "overwrite", label: "Overwrite", hint: scripts[scriptName] },
+          {
+            value: "rename",
+            label: "Add with different name",
+            hint: `${scriptName}:new`
+          }
+        ],
+        initialValue: "keep"
+      });
+      if (isCancel3(action)) {
+        cancel3("Cancelled.");
+        return;
+      }
+      if (action === "keep") {
+        delete scriptsToAdd[scriptName];
+      } else if (action === "rename") {
+        const newName = await text2({
+          message: `New script name for ${scriptName}`,
+          initialValue: `${scriptName}:new`,
+          validate: (v) => {
+            if (!v.trim())
+              return "Script name is required";
+            if (v in existingScripts || v in scriptsToAdd)
+              return "Script name already exists";
+            return;
+          }
+        });
+        if (isCancel3(newName)) {
+          cancel3("Cancelled.");
+          return;
+        }
+        const value = scriptsToAdd[scriptName];
+        delete scriptsToAdd[scriptName];
+        scriptsToAdd[String(newName)] = value;
+      }
+    }
+  } else if (conflictingScripts.length > 0 && nonInteractive) {
+    for (const scriptName of conflictingScripts) {
+      delete scriptsToAdd[scriptName];
+    }
+  }
+  if (Object.keys(scriptsToAdd).length > 0) {
+    pkg.scripts = {
+      ...existingScripts,
+      ...scriptsToAdd
+    };
+    await writeJsonFile(pkgPath, pkg);
+  }
+  const addedScripts = Object.keys(scriptsToAdd);
+  const skippedScripts = conflictingScripts.filter((k) => !(k in scriptsToAdd) && !addedScripts.some((a) => a !== k && scripts[k]));
+  outro3([
+    `Created ${relConfigPath}`,
+    "",
+    addedScripts.length > 0 ? `Added scripts to package.json:
+${addedScripts.map((k) => `  ${k}: ${scriptsToAdd[k]}`).join(`
+`)}` : "No new scripts added.",
+    skippedScripts.length > 0 ? `
+Kept existing scripts: ${skippedScripts.join(", ")}` : "",
+    "",
+    "Usage:",
+    "  npm run unrag:doctor       # Static checks",
+    "  npm run unrag:doctor:db    # Include database checks",
+    "  npm run unrag:doctor:ci    # CI mode (JSON output)",
+    "",
+    "Or run directly:",
+    `  unrag doctor --config ${relConfigPath}`
+  ].filter(Boolean).join(`
+`));
+}
+function buildCiScript(configPath, includeDb, strict) {
+  const parts = ["unrag doctor", `--config ${configPath}`];
+  if (includeDb)
+    parts.push("--db");
+  if (strict)
+    parts.push("--strict");
+  parts.push("--json");
+  return parts.join(" ");
+}
+
+// cli/commands/doctor.ts
+function parseDoctorArgs(args) {
+  const out = {};
+  for (let i = 0;i < args.length; i++) {
+    const a = args[i];
+    if (a === "--db") {
+      out.db = true;
+      continue;
+    }
+    if (a === "--json") {
+      out.json = true;
+      continue;
+    }
+    if (a === "--strict") {
+      out.strict = true;
+      continue;
+    }
+    if (a === "--config") {
+      const v = args[i + 1];
+      if (v && !v.startsWith("-")) {
+        out.config = v;
+        i++;
+      }
+      continue;
+    }
+    if (a === "--project-root") {
+      const v = args[i + 1];
+      if (v && !v.startsWith("-")) {
+        out.projectRoot = v;
+        i++;
+      }
+      continue;
+    }
+    if (a === "--install-dir" || a === "--dir") {
+      const v = args[i + 1];
+      if (v && !v.startsWith("-")) {
+        out.installDir = v;
+        i++;
+      }
+      continue;
+    }
+    if (a === "--schema") {
+      const v = args[i + 1];
+      if (v && !v.startsWith("-")) {
+        out.schema = v;
+        i++;
+      }
+      continue;
+    }
+    if (a === "--scope") {
+      const v = args[i + 1];
+      if (v && !v.startsWith("-")) {
+        out.scope = v;
+        i++;
+      }
+      continue;
+    }
+    if (a === "--database-url") {
+      const v = args[i + 1];
+      if (v && !v.startsWith("-")) {
+        out.databaseUrl = v;
+        i++;
+      }
+      continue;
+    }
+    if (a === "--database-url-env") {
+      const v = args[i + 1];
+      if (v && !v.startsWith("-")) {
+        out.databaseUrlEnv = v;
+        i++;
+      }
+      continue;
+    }
+    if (a === "--env-file") {
+      const v = args[i + 1];
+      if (v && !v.startsWith("-")) {
+        out.envFile = v;
+        i++;
+      }
+      continue;
+    }
+  }
+  return out;
+}
+function renderDoctorHelp() {
+  return [
+    "unrag doctor — validate your Unrag installation",
+    "",
+    "Usage:",
+    "  unrag doctor [options]",
+    "  unrag doctor setup [options]",
+    "",
+    "Subcommands:",
+    "  setup                   Generate project-specific doctor config and package.json scripts",
+    "",
+    "Options:",
+    "  --config <path>         Load settings from a doctor config file",
+    "  --db                    Run database checks (connectivity, pgvector, schema, indexes)",
+    "  --json                  Output results as JSON (for CI)",
+    "  --strict                Treat warnings as failures",
+    "  --project-root <path>   Override project root directory",
+    "  --install-dir <path>    Override Unrag install directory",
+    "  --schema <name>         Database schema name (default: public)",
+    "  --scope <prefix>        Limit dimension checks to sourceId prefix",
+    "  --database-url <url>    Database connection string (overrides env)",
+    "  --database-url-env <name>  Env var name for database URL",
+    "  --env-file <path>       Load env vars from a specific .env file (optional)",
+    "",
+    "Static checks (default):",
+    "  - Project/install integrity (unrag.json, config, install dir)",
+    "  - Environment variables (DATABASE_URL, provider keys)",
+    "  - Dependencies (pg, drizzle-orm, etc.)",
+    "  - Module presence (extractors, connectors)",
+    "  - Config coherence (extractors wired and enabled)",
+    "",
+    "Database checks (--db):",
+    "  - PostgreSQL connectivity",
+    "  - pgvector extension installed",
+    "  - Schema/table validation",
+    "  - Index recommendations",
+    "  - Embedding dimension consistency",
+    "",
+    "Exit codes:",
+    "  0  All checks passed (warnings allowed unless --strict)",
+    "  1  One or more checks failed",
+    "  2  Doctor could not run (internal error)",
+    "",
+    "Examples:",
+    "  unrag doctor                    Run static checks",
+    "  unrag doctor --db               Include database checks",
+    "  unrag doctor --db --strict      Fail on warnings too",
+    "  unrag doctor --json             Output JSON for CI",
+    "  unrag doctor --config .unrag/doctor.json   Use project config",
+    "  unrag doctor setup              Generate config and scripts",
+    "",
+    "Docs:",
+    `  ${docsUrl("/docs/reference/cli")}`
+  ].join(`
+`);
+}
+async function doctorCommand(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    outro4(renderDoctorHelp());
+    return;
+  }
+  if (args[0] === "setup") {
+    await doctorSetupCommand(args.slice(1));
+    return;
+  }
+  const parsed = parseDoctorArgs(args);
+  const s = spinner2();
+  s.start("Running doctor checks...");
+  try {
+    const projectRoot = parsed.projectRoot ?? await tryFindProjectRoot(process.cwd()) ?? process.cwd();
+    let doctorConfig = null;
+    if (parsed.config) {
+      const configPath = resolveConfigPath(projectRoot, parsed.config);
+      doctorConfig = await readDoctorConfig(configPath);
+      if (!doctorConfig) {
+        s.stop("Doctor failed.");
+        outro4(`Error: Could not read config file: ${parsed.config}`);
+        process.exitCode = 2;
+        return;
+      }
+    }
+    const mergedArgs = mergeDoctorArgsWithConfig(parsed, doctorConfig, projectRoot);
+    const state = await inferInstallState({
+      projectRootOverride: projectRoot,
+      installDirOverride: mergedArgs.installDir
+    });
+    const envFilesToLoad = getEnvFilesToLoad(doctorConfig, mergedArgs.envFile);
+    await loadEnvFilesFromList({
+      projectRoot: state.projectRoot,
+      files: envFilesToLoad
+    });
+    const staticResults = await runStaticChecks(state);
+    const coherenceResults = await runConfigCoherenceChecks(state);
+    let dbResults = [];
+    if (mergedArgs.db) {
+      dbResults = await runDbChecks(state, {
+        databaseUrl: mergedArgs.databaseUrl,
+        databaseUrlEnv: mergedArgs.databaseUrlEnv ?? doctorConfig?.env?.databaseUrlEnv,
+        schema: mergedArgs.schema ?? doctorConfig?.db?.schema ?? "public",
+        scope: mergedArgs.scope
+      });
+    }
+    s.stop("Doctor checks complete.");
+    const groups = [
+      {
+        id: "install",
+        title: "Installation",
+        results: staticResults.install
+      },
+      {
+        id: "env",
+        title: "Environment",
+        results: staticResults.env
+      },
+      {
+        id: "modules",
+        title: "Modules",
+        results: staticResults.modules
+      },
+      {
+        id: "config",
+        title: "Configuration",
+        results: coherenceResults
+      }
+    ];
+    if (mergedArgs.db) {
+      groups.push({
+        id: "database",
+        title: "Database",
+        results: dbResults
+      });
+    }
+    const allResults = groups.flatMap((g) => g.results);
+    const summary = {
+      total: allResults.length,
+      pass: allResults.filter((r) => r.status === "pass").length,
+      warn: allResults.filter((r) => r.status === "warn").length,
+      fail: allResults.filter((r) => r.status === "fail").length,
+      skip: allResults.filter((r) => r.status === "skip").length
+    };
+    const report = { groups, summary };
+    if (mergedArgs.json) {
+      console.log(formatJson(report));
+    } else {
+      outro4(formatReport(report, { showDbHint: !mergedArgs.db }));
+    }
+    const hasFails = summary.fail > 0;
+    const hasWarns = summary.warn > 0;
+    if (hasFails) {
+      process.exitCode = 1;
+    } else if (mergedArgs.strict && hasWarns) {
+      process.exitCode = 1;
+    }
+  } catch (err) {
+    s.stop("Doctor failed.");
+    const message = err instanceof Error ? err.message : String(err);
+    outro4(`Error: ${message}`);
+    process.exitCode = 2;
+  }
+}
+
+// cli/run.ts
+function renderHelp() {
+  return [
+    "unrag — vendor-in RAG primitives (ingest/retrieve + adapters) into your repo.",
+    "",
+    "Usage:",
+    "  bunx unrag <command> [options]",
+    "  npx  unrag <command> [options]",
+    "",
+    "Commands:",
+    "  init                Install core files (config + store adapter templates)",
+    "  add <connector>     Install a connector (notion, google-drive)",
+    "  add extractor <n>   Install an extractor (pdf-llm, image-ocr, etc.)",
+    "  add battery <name>  Install a battery module (reranker, etc.)",
+    "  doctor              Validate installation and configuration",
+    "  doctor setup        Generate project-specific doctor config and scripts",
+    "  help                Show this help",
+    "",
+    "Global options:",
+    "  -h, --help           Show help",
+    "  -y, --yes            Non-interactive; accept defaults",
+    "",
+    "init options:",
+    "  --store <adapter>    drizzle | prisma | raw-sql",
+    "  --dir <path>         Install directory (alias: --install-dir)",
+    "  --alias <@name>      Import alias base (e.g. @unrag)",
+    "  --preset <id|url>    Install from a web-generated preset (non-interactive)",
+    "  --overwrite <mode>   skip | force (when files already exist)",
+    "  --rich-media         Enable rich media setup (also enables multimodal embeddings)",
+    "  --no-rich-media      Disable rich media setup",
+    "  --extractors <list>  Comma-separated extractors (implies --rich-media)",
+    "  --no-install         Skip automatic dependency installation",
+    "",
+    "add options:",
+    "  --no-install         Skip automatic dependency installation",
+    "",
+    "doctor options:",
+    "  --config <path>      Load settings from a doctor config file",
+    "  --db                 Run database checks (connectivity, schema, indexes)",
+    "  --json               Output JSON for CI",
+    "  --strict             Treat warnings as failures",
+    "",
+    "Examples:",
+    "  bunx unrag@latest init",
+    "  bunx unrag@latest init --yes --store drizzle --dir lib/unrag --alias @unrag",
+    "  bunx unrag@latest init --yes --rich-media",
+    "  bunx unrag@latest init --yes --extractors pdf-text-layer,file-text",
+    "  bunx unrag add notion --yes",
+    "  bunx unrag add battery reranker --yes",
+    "  bunx unrag doctor",
+    "  bunx unrag doctor --db",
+    "  bunx unrag doctor setup",
+    "  bunx unrag doctor --config .unrag/doctor.json",
+    "",
+    "Docs:",
+    `  - Quickstart: ${docsUrl("/docs/getting-started/quickstart")}`,
+    `  - CLI:       ${docsUrl("/docs/reference/cli")}`,
+    `  - Notion:    ${docsUrl("/docs/connectors/notion")}`,
+    "",
+    "Repo:",
+    `  ${UNRAG_GITHUB_REPO_URL}`,
+    "",
+    "Tip:",
+    "  After `init`, open the generated unrag.md for schema + env vars (DATABASE_URL)."
+  ].join(`
+`);
+}
+async function run(argv) {
+  const [, , command, ...rest] = argv;
+  intro("unrag");
+  if (!command || command === "help" || command === "--help" || command === "-h") {
+    outro5(renderHelp());
+    return;
+  }
+  if (command === "init") {
+    await initCommand(rest);
+    return;
+  }
+  if (command === "add") {
+    await addCommand(rest);
+    return;
+  }
+  if (command === "doctor") {
+    await doctorCommand(rest);
     return;
   }
-  outro3([`Unknown command: ${command}`, "", renderHelp()].join(`
+  outro5([`Unknown command: ${command}`, "", renderHelp()].join(`
 `));
   process.exitCode = 1;
 }