@autorag/librarian 2.4.1 → 2.4.2

package/dist/cli/index.js

@@ -206,7 +206,7 @@ function renderMemory(schema, opts) {
 function renderFeedback(result, opts) {
   const envelope = { ok: true, applied: result.applied, sessionId: result.sessionId };
   if (opts.json) {
-    return JSON.stringify(envelope, null, 2);
+    return JSON.stringify(envelope);
   }
   const lines = [];
   lines.push(`feedback: ${result.applied ? "applied" : "not applied"}`);
@@ -877,7 +877,10 @@ function parsedOutputPath(root, virtualPath) {
   const digest = createHash("sha256").update(virtualPath).digest("hex");
   return join3(parsedMirrorRoot(root), PARSED_FILES_SUBDIR, `${digest}.md`);
 }
-var PARSED_MIRROR_SUBDIR, PARSED_FILES_SUBDIR = "files", PARSED_INDEX_FILE = "index.json";
+function refreshReadinessPath(root) {
+  return join3(root, ".autorag", REFRESH_READINESS_FILE);
+}
+var PARSED_MIRROR_SUBDIR, PARSED_FILES_SUBDIR = "files", PARSED_INDEX_FILE = "index.json", REFRESH_READINESS_FILE = "refresh-complete.json";
 var init_paths = __esm(() => {
   PARSED_MIRROR_SUBDIR = join3(".autorag", "parsed");
 });
@@ -6356,6 +6359,11 @@ function globalArgs(options) {
   return options.configPath !== undefined ? ["--config", options.configPath] : [];
 }
 function parseCount(stdout) {
+  const trimmed = stdout.trim();
+  if (!trimmed.startsWith("{") && !trimmed.startsWith("[")) {
+    const textMatch = /\bpages=(\d+)/.exec(trimmed);
+    return textMatch ? Number(textMatch[1]) : 0;
+  }
   const parsed = parseJson3(stdout);
   if (parsed === undefined)
     return;
@@ -6371,6 +6379,10 @@ function parseCount(stdout) {
   return 0;
 }
 function parseHits(stdout) {
+  const trimmed = stdout.trim();
+  if (trimmed.length > 0 && !trimmed.startsWith("{") && !trimmed.startsWith("[")) {
+    return parseTabSeparatedHits(trimmed);
+  }
   const parsed = parseJson3(stdout);
   const rows = Array.isArray(parsed) ? parsed : isRecord3(parsed) && Array.isArray(parsed.results) ? parsed.results : undefined;
   if (rows === undefined)
@@ -6404,6 +6416,33 @@ function parseHits(stdout) {
   }
   return hits;
 }
+function parseTabSeparatedHits(stdout) {
+  const hits = [];
+  for (const [index, line] of stdout.split(`
+`).entries()) {
+    if (line.trim().length === 0)
+      continue;
+    const [kind, id, title, ...textParts] = line.split("\t");
+    if (kind === undefined || id === undefined || id.length === 0)
+      return;
+    const content = textParts.join("\t");
+    const cleanTitle = (title ?? "").replace(/\\t/g, "\t").replace(/\\n/g, `
+`);
+    hits.push({
+      id,
+      content: content.replace(/\\t/g, "\t").replace(/\\n/g, `
+`),
+      score: 1 / (index + 1),
+      ...cleanTitle.length > 0 ? { title: cleanTitle } : {},
+      hierarchy: [kind, ...cleanTitle.length > 0 ? [cleanTitle] : [], id],
+      metadata: {
+        kind,
+        ...cleanTitle.length > 0 ? { title: cleanTitle } : {}
+      }
+    });
+  }
+  return hits;
+}
 function parseJson3(stdout) {
   const trimmed = stdout.trim();
   if (trimmed.length === 0)
@@ -6433,7 +6472,7 @@ var init_notion = __esm(() => {
     binaryName: "notcrawl",
     allowedEnvPrefixes: ["NOTCRAWL_"],
     syncArgs: (options) => [...globalArgs(options), "sync"],
-    searchArgs: (options, query, topK) => [...globalArgs(options), "search", query, "--limit", String(topK), "--json"],
+    searchArgs: (options, query, topK) => [...globalArgs(options), "search", query, "--limit", String(topK)],
     parseSyncCount: parseCount,
     parseHits
   };
@@ -9032,6 +9071,12 @@ function resolveBuiltInModel(reference) {
   }
   return;
 }
+function resolveModel(config) {
+  if (!config.model) {
+    throw new ConfigError('No model configured. Provide --model-provider and --model-id on the command line, or set the "model" key (with provider and id) in the config file.');
+  }
+  return resolveRegisteredModel(config.model);
+}
 function resolveAgentModelCore(config, localOptions = {}) {
   const modelRef = config.model;
   const registered = resolveBuiltInModel(modelRef);
@@ -9442,18 +9487,21 @@ class DatasourceAccessContext {
       return false;
     return tags.some((tag) => this.allowedTags.includes(tag));
   }
-  allowedSourcesPredicate(_userScope) {
+  allowedSourcesPredicate(_userScope, userScopes) {
     if (this.denyAll)
       return () => false;
     const trustedScopes = this.allowedScopes;
     const normalizedUserScope = _userScope === undefined ? undefined : normalizeVirtualPath2(_userScope);
+    const normalizedUserScopes = userScopes?.map(normalizeVirtualPath2);
     return (source) => {
       if (source.includes("#"))
         return false;
       const inTrusted = trustedScopes.length === 0 ? true : trustedScopes.some((scope) => matchesVirtualPathScope(source, scope));
       if (!inTrusted)
         return false;
-      return normalizedUserScope === undefined ? true : matchesVirtualPathScope(source, normalizedUserScope);
+      if (normalizedUserScope !== undefined && !matchesVirtualPathScope(source, normalizedUserScope))
+        return false;
+      return normalizedUserScopes === undefined || normalizedUserScopes.length === 0 ? true : normalizedUserScopes.some((scope) => matchesVirtualPathScope(source, scope));
     };
   }
 }
@@ -9490,7 +9538,7 @@ function datasourceCodeToRetrieval(code) {
 
 // src/datasource/result-filter.ts
 class DatasourceResultFilter {
-  filter(byMethod, methods, ctx, userScope) {
+  filter(byMethod, methods, ctx, userScope, userScopes) {
     const descriptors = new Map;
     for (const method of methods) {
       descriptors.set(method.describe().name, method);
@@ -9515,7 +9563,7 @@ class DatasourceResultFilter {
         out.set(name, results);
         continue;
       }
-      const predicate = ctx.allowedSourcesPredicate(userScope);
+      const predicate = ctx.allowedSourcesPredicate(userScope, userScopes);
       out.set(name, results.filter((r) => predicate(r.source)));
     }
     return out;
@@ -11324,7 +11372,7 @@ class MinSyncClient {
     this.embedder = options.embedder;
     this.maxChunkSize = options.maxChunkSize;
   }
-  async sync() {
+  async sync(force = false) {
     if (!existsSync11(this.binaryPath)) {
       return { ok: false, synced: 0, workspacePath: this.workspacePath, reason: "missing-binary" };
     }
@@ -11352,7 +11400,7 @@ class MinSyncClient {
         initArgs.push("--embedder", this.embedder.id);
       }
       const init = await this.spawn(initArgs, spawnOpts);
-      if (!init.ok) {
+      if (!init.ok || !existsSync11(minSyncConfigPath(this.workspacePath))) {
         return {
           ok: false,
           synced: 0,
@@ -11388,7 +11436,7 @@ class MinSyncClient {
     const chunkSizeChanged = this.maxChunkSize !== undefined && configuredChunkSize !== this.maxChunkSize;
     if (chunkSizeChanged)
       rmSync2(cursorPath, { force: true });
-    const syncArgs = existsSync11(cursorPath) && !chunkSizeChanged ? ["sync", "--format", "json"] : ["sync", "--full", "--format", "json"];
+    const syncArgs = existsSync11(cursorPath) && !chunkSizeChanged && !force ? ["sync", "--format", "json"] : ["sync", "--full", "--format", "json"];
     const result = await this.spawn(syncArgs, spawnOpts);
     if (!result.ok) {
       if (chunkSizeChanged)
@@ -11412,7 +11460,7 @@ class MinSyncClient {
   async query(text, topK, mode = "vector") {
     if (!existsSync11(this.binaryPath))
       return [];
-    const result = await this.spawn(["query", "--format", "json", "-k", String(topK), "--mode", mode, text]);
+    const result = await this.spawn(["query", "--format", "json", "--mode", mode, "-k", String(topK), text]);
     if (!result.ok)
       return [];
     return parseQueryHits(result.stdout);
@@ -11490,34 +11538,51 @@ import { copyFileSync, createWriteStream, existsSync as existsSync12, mkdirSync
 import { chmod, mkdtemp as mkdtemp2 } from "node:fs/promises";
 import { get } from "node:https";
 import { tmpdir as tmpdir2 } from "node:os";
-import { basename as basename6, dirname as dirname9, join as join17 } from "node:path";
+import { basename as basename6, delimiter as delimiter2, dirname as dirname9, join as join17 } from "node:path";
 import { pipeline } from "node:stream/promises";
 async function ensureMinSyncBinary(options) {
   const binaryPath = join17(options.root, ".autorag", "bin", executableName(options.platform ?? process.platform));
   if (existsSync12(binaryPath))
     return { binaryPath, version: "cached" };
-  const releaseProvider = options.releaseProvider ?? fetchLatestMinSyncRelease;
-  const release = await releaseProvider();
-  let asset;
+  mkdirSync9(dirname9(binaryPath), { recursive: true });
+  const cargoInstaller = options.cargoInstaller ?? ((destination) => installMinSyncFromCargoIfAvailable(options, destination));
   try {
-    asset = selectReleaseAsset(release, options.platform ?? process.platform, options.arch ?? process.arch);
+    const fromCargo = await cargoInstaller(binaryPath);
+    if (fromCargo !== undefined)
+      return fromCargo;
   } catch (error) {
-    if (!(error instanceof MinSyncReleaseError) || !error.message.startsWith("No MinSync"))
+    if (!(error instanceof MinSyncReleaseError))
       throw error;
-    return installMinSyncFromCargo(options, binaryPath);
   }
+  const releaseProvider = options.releaseProvider ?? fetchLatestMinSyncRelease;
+  const release = await releaseProvider();
+  const asset = selectReleaseAsset(release, options.platform ?? process.platform, options.arch ?? process.arch);
   requireSha256(asset);
   const assetInstaller = options.assetInstaller ?? installReleaseAsset;
-  mkdirSync9(dirname9(binaryPath), { recursive: true });
   await assetInstaller(asset, binaryPath);
   await chmod(binaryPath, 493);
   return { binaryPath, version: release.tagName };
 }
-async function installMinSyncFromCargo(options, destination) {
+function isIsolatedTestRuntime() {
+  return false;
+}
+async function installMinSyncFromCargoIfAvailable(options, destination) {
+  if (isIsolatedTestRuntime() && options.cargoLocator === undefined)
+    return;
+  const env = options.env ?? process.env;
+  const cargoLocator = options.cargoLocator ?? ((lookupEnv) => lookupCargo(lookupEnv, options.platform ?? process.platform));
+  const cargo = cargoLocator(env);
+  if (cargo === undefined)
+    return;
+  if (!await cargoIsUsable(cargo, options.root))
+    return;
+  return installMinSyncFromCargo(options, destination, cargo);
+}
+async function installMinSyncFromCargo(options, destination, cargo) {
   const cargoRoot = join17(options.root, ".autorag", "minsync-cargo");
   mkdirSync9(dirname9(destination), { recursive: true });
   mkdirSync9(cargoRoot, { recursive: true });
-  const result = await spawnProcess("cargo", ["install", "minsync", "--version", MINSYNC_VERSION, "--locked", "--root", cargoRoot], options.root);
+  const result = await spawnProcess(cargo, ["install", "minsync", "--version", MINSYNC_VERSION, "--locked", "--root", cargoRoot], options.root, { timeoutMs: MINSYNC_CARGO_INSTALL_TIMEOUT_MS });
   if (!result.ok) {
     throw new MinSyncReleaseError(result.stderr || `Could not install MinSync ${MINSYNC_VERSION} from crates.io`);
   }
@@ -11642,6 +11707,27 @@ function targetTriple(platform, arch) {
 function executableName(platform) {
   return platform === "win32" ? "minsync.exe" : "minsync";
 }
+function cargoExecutableName2(platform) {
+  return platform === "win32" ? "cargo.exe" : "cargo";
+}
+function lookupCargo(env, platform) {
+  const pathEnv = env.PATH;
+  if (typeof pathEnv !== "string" || pathEnv.length === 0)
+    return;
+  const execName = cargoExecutableName2(platform);
+  for (const dir of pathEnv.split(delimiter2)) {
+    if (dir.length === 0)
+      continue;
+    const candidate = join17(dir, execName);
+    if (existsSync12(candidate))
+      return candidate;
+  }
+  return;
+}
+async function cargoIsUsable(cargo, cwd) {
+  const result = await spawnProcess(cargo, ["--version"], cwd, { timeoutMs: CARGO_PROBE_TIMEOUT_MS });
+  return result.ok && result.stdout.toLowerCase().includes("cargo");
+}
 function parseDigest(value) {
   if (typeof value !== "string")
     return;
@@ -11664,10 +11750,11 @@ function isGitHubAsset(value) {
 function isRecord11(value) {
   return typeof value === "object" && value !== null;
 }
-var LATEST_RELEASE_URL = "https://api.github.com/repos/NomaDamas/MinSync/releases/latest", SHA256_HEX_PATTERN, MINSYNC_VERSION = "0.3.0", MinSyncReleaseError;
+var LATEST_RELEASE_URL = "https://api.github.com/repos/NomaDamas/MinSync/releases/latest", SHA256_HEX_PATTERN, MINSYNC_VERSION = "0.4.2", MINSYNC_CARGO_INSTALL_TIMEOUT_MS, CARGO_PROBE_TIMEOUT_MS = 5000, MinSyncReleaseError;
 var init_installer2 = __esm(() => {
   init_process();
   SHA256_HEX_PATTERN = /^[a-f0-9]{64}$/;
+  MINSYNC_CARGO_INSTALL_TIMEOUT_MS = 10 * 60 * 1000;
   MinSyncReleaseError = class MinSyncReleaseError extends Error {
     name = "MinSyncReleaseError";
   };
@@ -11843,7 +11930,7 @@ var init_workspace = __esm(() => {
 
 // src/minsync/method.ts
 import { accessSync, constants, existsSync as existsSync14, realpathSync as realpathSync3 } from "node:fs";
-import { basename as basename8, delimiter as delimiter2, join as join20, normalize as normalize2 } from "node:path";
+import { basename as basename8, delimiter as delimiter3, join as join20, normalize as normalize2 } from "node:path";
 function degrade(workspacePath, reason) {
   return { ok: false, synced: 0, workspacePath, reason };
 }
@@ -11852,7 +11939,7 @@ function lookupInPath(env) {
   if (typeof pathEnv !== "string" || pathEnv.length === 0)
     return;
   const execName = executableName(process.platform);
-  for (const dir of pathEnv.split(delimiter2)) {
+  for (const dir of pathEnv.split(delimiter3)) {
     if (dir.length === 0)
       continue;
     const candidate = join20(dir, execName);
@@ -11873,6 +11960,7 @@ class MinSyncVectorMethod {
   embedder;
   maxChunkSize;
   mode;
+  installFailed = false;
   constructor(options) {
     this.root = options.root;
     this.binaryPath = options.binaryPath;
@@ -11897,7 +11985,7 @@ class MinSyncVectorMethod {
       ]
     };
   }
-  async sync() {
+  async sync(force = false) {
     syncMinSyncWorkspace(this.root, { workspacePath: this.workspacePath });
     const binaryResult = await this.resolveBinary();
     if (binaryResult === undefined) {
@@ -11910,11 +11998,21 @@ class MinSyncVectorMethod {
         embedder: this.embedder,
         maxChunkSize: this.maxChunkSize
       });
-      return client.sync();
+      return client.sync(force);
     }
     return binaryResult;
   }
   isBinaryMissing() {
+    if (this.binaryPath !== undefined)
+      return !existsSync14(this.binaryPath);
+    if (lookupInPath(process.env) !== undefined)
+      return false;
+    const cachedBinary = join20(this.root, ".autorag", "bin", executableName(process.platform));
+    if (existsSync14(cachedBinary))
+      return false;
+    return this.installFailed || !this.autoInstall;
+  }
+  isExplicitBinaryMissing() {
     return this.binaryPath !== undefined && !existsSync14(this.binaryPath);
   }
   isReady() {
@@ -11973,6 +12071,7 @@ class MinSyncVectorMethod {
         const installed = await ensureMinSyncBinary({ ...this.installer, root: this.root });
         return installed.binaryPath;
       } catch {
+        this.installFailed = true;
         return degrade(this.workspacePath, "install-failed");
       }
     }
@@ -12444,6 +12543,106 @@ class RetrievalMethodRegistry {
   }
 }
 
+// src/retrieval/engine.ts
+class RetrievalEngine {
+  registry;
+  retriever;
+  filter;
+  merger;
+  accessContext;
+  defaultTopK;
+  defaultDedup;
+  isMinSyncBinaryMissing;
+  constructor(options = {}) {
+    this.registry = new RetrievalMethodRegistry;
+    this.retriever = new ParallelRetriever;
+    this.filter = new DatasourceResultFilter;
+    this.merger = new ResultMerger;
+    this.accessContext = new DatasourceAccessContext(options.datasourceAccess);
+    this.defaultTopK = options.defaultTopK ?? 20;
+    this.defaultDedup = options.defaultDedup ?? true;
+    this.isMinSyncBinaryMissing = options.isMinSyncBinaryMissing;
+  }
+  getMethodRegistry() {
+    return this.registry;
+  }
+  getAccessContext() {
+    return this.accessContext;
+  }
+  register(method) {
+    this.registry.register(method);
+  }
+  registerMany(methods) {
+    const names = new Set;
+    for (const method of methods) {
+      const name = method.describe().name;
+      if (this.registry.get(name) !== undefined || names.has(name)) {
+        throw new Error(`Retrieval method "${name}" is already registered`);
+      }
+      names.add(name);
+    }
+    for (const method of methods) {
+      this.registry.register(method);
+    }
+  }
+  async retrieve(query, options = {}) {
+    const topK = options.topK ?? this.defaultTopK;
+    const methods = this.registry.list();
+    const { results: byMethod, diagnostics } = await this.retriever.retrieveWithDiagnostics(methods, query, options);
+    const ctx = this.accessContextFor(options);
+    const filtered = this.filter.filter(byMethod, methods, ctx, options.scope, options.allowedScopes);
+    const allDiagnostics = this.appendMinSyncUnavailableDiagnostic(methods, filtered, diagnostics);
+    return {
+      results: this.merger.merge(filtered, { topK, dedup: this.defaultDedup }),
+      diagnostics: allDiagnostics
+    };
+  }
+  async retrieveByMethod(query, options = {}) {
+    const methods = this.registry.list();
+    const { results: byMethod, diagnostics } = await this.retriever.retrieveWithDiagnostics(methods, query, options);
+    const ctx = this.accessContextFor(options);
+    const filtered = this.filter.filter(byMethod, methods, ctx, options.scope, options.allowedScopes);
+    const allDiagnostics = this.appendMinSyncUnavailableDiagnostic(methods, filtered, diagnostics);
+    return { byMethod: filtered, diagnostics: allDiagnostics };
+  }
+  appendMinSyncUnavailableDiagnostic(methods, filtered, diagnostics) {
+    if (this.isMinSyncBinaryMissing === undefined)
+      return diagnostics;
+    if (!this.isMinSyncBinaryMissing())
+      return diagnostics;
+    if (diagnostics.some((d) => d.code === "minsync-unavailable"))
+      return diagnostics;
+    const hasEmptyMinsync = methods.some((m) => {
+      const name = m.describe().name;
+      if (name !== "minsync")
+        return false;
+      const results = filtered.get(name);
+      return results === undefined || results.length === 0;
+    });
+    if (!hasEmptyMinsync)
+      return diagnostics;
+    return [
+      ...diagnostics,
+      {
+        code: "minsync-unavailable",
+        severity: "warning",
+        message: "MinSync semantic search is unavailable; results rely on other retrieval paths.",
+        source: "minsync"
+      }
+    ];
+  }
+  accessContextFor(options) {
+    const baseTags = this.accessContext.allowedTags;
+    const baseScopes = this.accessContext.allowedScopes;
+    const userTags = options.allowedTags;
+    const allowedTags = baseTags.length === 0 ? [] : userTags !== undefined ? baseTags.filter((t) => userTags.includes(t)) : baseTags;
+    return new DatasourceAccessContext({ allowedTags, allowedScopes: baseScopes });
+  }
+}
+var init_engine = __esm(() => {
+  init_access_context();
+});
+
 // src/filesystem/cloud-placeholder.ts
 import { execFile } from "node:child_process";
 import { lstat } from "node:fs/promises";
@@ -13001,7 +13200,7 @@ var init_emit_results_tool = __esm(() => {
         excerpt: Type5.String({ description: "Supporting excerpt" }),
         lineNumber: Type5.Optional(Type5.Integer({ description: "Line number of the excerpt, if known" }))
       })),
-      confidence: Type5.Number({ description: "Confidence in this result, 0..1" })
+      confidence: Type5.Number({ description: "Confidence in this result, 0..1", minimum: 0, maximum: 1 })
     }), { description: "Numbered curated knowledge units." }),
     mapping: Type5.Array(Type5.Object({
       number: Type5.Integer({ description: "Matches the result number this entry maps" }),
@@ -13655,7 +13854,7 @@ var init_watch_refresh = __esm(() => {
 
 // src/agent/agent.ts
 import { randomUUID as randomUUID7 } from "node:crypto";
-import { watch as fsWatch, realpathSync as realpathSync4, statSync } from "node:fs";
+import { watch as fsWatch, mkdirSync as mkdirSync13, realpathSync as realpathSync4, statSync, writeFileSync as writeFileSync11 } from "node:fs";
 import { dirname as dirname14, join as join21, resolve as resolve11 } from "node:path";
 import { Agent } from "@earendil-works/pi-agent-core";
 import { streamSimple } from "@earendil-works/pi-ai/compat";
@@ -14205,9 +14404,12 @@ ${initialRetrievalContext}`);
     }
   }
   datasourceAccessContext(options = {}) {
+    const trustedTags = this.datasourceAccessOptions.allowedTags ?? [];
+    const requestedTags = options.allowedTags;
+    const allowedTags = requestedTags === undefined ? trustedTags : trustedTags.filter((tag) => requestedTags.includes(tag));
     return new DatasourceAccessContext({
-      allowedTags: options.allowedTags ?? this.datasourceAccessOptions.allowedTags,
-      allowedScopes: options.allowedScopes ?? this.datasourceAccessOptions.allowedScopes
+      allowedTags,
+      allowedScopes: this.datasourceAccessOptions.allowedScopes
     });
   }
   buildAuthorizedDatasourceSkills() {
@@ -14361,7 +14563,7 @@ ${initialRetrievalContext ?? "Pending; continue only with a brief progress state
     };
     try {
       const summary = needsParsed ? await this.syncParsedMirrors(force) : await this.scanMirrorStaleness();
-      const minsync = wants("minsync") ? await this.syncMinSync() : undefined;
+      const minsync = wants("minsync") ? await this.syncMinSync(force) : undefined;
       const datasources = wants("datasources") ? await this.indexDatasources() : [];
       const jikji = allMethods || wants("jikji") || wants("minsync") ? await this.executeJikjiPrepare() : undefined;
       this.retrievalScopeBindings = buildRetrievalScopeBindings(this.workspaceProjectRoot, this.searchPaths, this.configuredSearchPaths);
@@ -14381,6 +14583,11 @@ ${initialRetrievalContext ?? "Pending; continue only with a brief progress state
         datasources,
         lastError: undefined
       };
+      if (needsParsed) {
+        mkdirSync13(dirname14(refreshReadinessPath(this.workspaceProjectRoot)), { recursive: true });
+        writeFileSync11(refreshReadinessPath(this.workspaceProjectRoot), `{"version":1,"completed":true,"parsed":true}
+`);
+      }
       const publicMinsync = minsync ? {
         ok: minsync.ok,
         synced: minsync.synced,
@@ -14459,7 +14666,7 @@ ${initialRetrievalContext ?? "Pending; continue only with a brief progress state
   refreshComponentStatus() {
     const status = {};
     if (this.minSyncMethod !== undefined) {
-      status.minsync = this.minSyncMethod.isBinaryMissing() ? "unavailable" : this.refreshState.minsync?.ok === false ? "degraded" : this.minSyncMethod.isReady() ? "ready" : "configured";
+      status.minsync = this.minSyncMethod.isExplicitBinaryMissing() ? "unavailable" : this.refreshState.minsync?.ok === false ? "degraded" : this.minSyncMethod.isReady() ? "ready" : "configured";
     }
     if (this.jikjiClient !== undefined) {
       status.jikji = this.refreshState.jikjiDiagnostics.length > 0 ? "degraded" : "configured";
@@ -14546,8 +14753,8 @@ ${initialRetrievalContext ?? "Pending; continue only with a brief progress state
     }
     return { excluded };
   }
-  async syncMinSync() {
-    const result = await this.minSyncMethod?.sync();
+  async syncMinSync(force = false) {
+    const result = await this.minSyncMethod?.sync(force);
     this.minSyncReady = result?.ok === true;
     this.refreshState = { ...this.refreshState, minsync: result };
     return result;
@@ -14748,7 +14955,7 @@ ${initialRetrievalContext ?? "Pending; continue only with a brief progress state
     options = this.normalizeRetrievalOptions(options);
     const methods = this.methodRegistry.list();
     const { results: byMethod, diagnostics } = await this.retriever.retrieveWithDiagnostics(methods, query, options);
-    const filteredByMethod = this.datasourceFilter.filter(byMethod, methods, this.datasourceAccessContext(options), options.scope);
+    const filteredByMethod = this.datasourceFilter.filter(byMethod, methods, this.datasourceAccessContext(options), options.scope, options.allowedScopes);
     if (this.minSyncMethod?.isBinaryMissing() && !diagnostics.some((d) => d.source === "minsync")) {
       diagnostics.push({
         code: "minsync-unavailable",
@@ -14784,6 +14991,19 @@ ${initialRetrievalContext ?? "Pending; continue only with a brief progress state
   getMethodRegistry() {
     return this.methodRegistry;
   }
+  retrievalEngine;
+  getRetrievalEngine() {
+    if (this.retrievalEngine === undefined) {
+      this.retrievalEngine = new RetrievalEngine({
+        datasourceAccess: this.datasourceAccessOptions,
+        isMinSyncBinaryMissing: this.minSyncMethod !== undefined ? () => this.minSyncMethod.isBinaryMissing() : undefined
+      });
+      for (const method of this.methodRegistry.list()) {
+        this.retrievalEngine.register(method);
+      }
+    }
+    return this.retrievalEngine;
+  }
   getSystemPrompt() {
     return this.innerAgent.state.systemPrompt;
   }
@@ -14887,6 +15107,7 @@ var init_agent = __esm(() => {
   init_paths();
   init_sync();
   init_run_log();
+  init_engine();
   init_scope();
   init_bash_tool();
   init_datasource_skill();
@@ -14920,7 +15141,7 @@ async function runRefresh(ctx) {
     return 0;
   } catch (error) {
     ctx.stderr(renderError(error, { json: ctx.json, debug: ctx.debug }));
-    return 1;
+    return error instanceof ConfigError ? 2 : 1;
   }
 }
 function parseMethodFlag(flag) {
@@ -14964,7 +15185,7 @@ async function runStatus(ctx) {
     return 0;
   } catch (error) {
     ctx.stderr(renderError(error, { json: ctx.json, debug: ctx.debug }));
-    return 1;
+    return error instanceof ConfigError ? 2 : 1;
   }
 }
 var init_status = __esm(() => {
@@ -15318,6 +15539,9 @@ async function runIndex(ctx) {
   for (const target of targets) {
     rmSync6(target, { recursive: true, force: true });
   }
+  if (sub === "reset" || targetSubdirs.includes(PARSED_MIRROR_SUBDIR)) {
+    rmSync6(refreshReadinessPath(config.workspacePath), { force: true });
+  }
   if (sub === "reset") {
     ctx.stdout(renderIndex({ action: "reset", removed: [...targetNames] }, { json: ctx.json }));
     return 0;
@@ -15436,7 +15660,7 @@ async function runWatch(ctx) {
     return 0;
   } catch (error) {
     ctx.stderr(renderError(error, { json: ctx.json, debug: ctx.debug }));
-    return 1;
+    return error instanceof ConfigError ? 2 : 1;
   }
 }
 var init_watch = __esm(() => {
@@ -15682,7 +15906,7 @@ async function runDuplicates(ctx, scanner = (path) => scanWithDupey(path)) {
     return 0;
   } catch (error) {
     ctx.stderr(renderError(error, { json: ctx.json, debug: ctx.debug }));
-    return 1;
+    return error instanceof ConfigError ? 2 : 1;
   }
 }
 function exactGroupsFromScan(scan) {
@@ -15740,7 +15964,7 @@ function renderSlashHelp() {
 }
 
 // src/cli/tui-session-store.ts
-import { existsSync as existsSync17, mkdirSync as mkdirSync13, readFileSync as readFileSync14, renameSync as renameSync8, writeFileSync as writeFileSync11 } from "node:fs";
+import { existsSync as existsSync17, mkdirSync as mkdirSync14, readFileSync as readFileSync14, renameSync as renameSync8, writeFileSync as writeFileSync12 } from "node:fs";
 import { dirname as dirname15 } from "node:path";
 function createFileTuiSessionStore(path) {
   const readSessions = () => {
@@ -15762,9 +15986,9 @@ function createFileTuiSessionStore(path) {
       const sessions = readSessions().filter((item) => item.id !== session.id);
       sessions.unshift(session);
       const dir = dirname15(path);
-      mkdirSync13(dir, { recursive: true });
+      mkdirSync14(dir, { recursive: true });
       const tmpPath = `${path}.${process.pid}.tmp`;
-      writeFileSync11(tmpPath, `${JSON.stringify(sessions.slice(0, MAX_SESSIONS), null, 2)}
+      writeFileSync12(tmpPath, `${JSON.stringify(sessions.slice(0, MAX_SESSIONS), null, 2)}
 `, "utf8");
       renameSync8(tmpPath, path);
     }
@@ -16770,7 +16994,7 @@ var init_catalog = __esm(() => {
 
 // src/ui/probe.ts
 import { existsSync as existsSync19 } from "node:fs";
-import { delimiter as delimiter3, join as join25 } from "node:path";
+import { delimiter as delimiter4, join as join25 } from "node:path";
 function probeConnection(input, deps = {}) {
   const catalog = getDatasourceType(input.type);
   if (catalog === undefined) {
@@ -16898,7 +17122,7 @@ function defaultBinaryExists(binaryName, binaryPath) {
     return existsSync19(binaryPath);
   const pathEnv = process.env.PATH ?? "";
   const extensions = process.platform === "win32" ? [".exe", ".cmd", ".bat", ""] : [""];
-  for (const dir of pathEnv.split(delimiter3)) {
+  for (const dir of pathEnv.split(delimiter4)) {
     if (dir.length === 0)
       continue;
     for (const extension of extensions) {
@@ -17982,6 +18206,484 @@ var init_ui = __esm(() => {
   init_config2();
 });
 
+// src/core.ts
+import { randomUUID as randomUUID8 } from "node:crypto";
+
+class AutoRAGLite {
+  config;
+  agent;
+  retrievalEngine;
+  memory;
+  sessions = new Map;
+  constructor(config) {
+    this.config = config;
+    const agentOptions = buildAgentOptions(config);
+    this.agent = new AutoRAGAgent(agentOptions);
+    this.retrievalEngine = this.agent.getRetrievalEngine();
+    this.memory = new RetrievalMemory({ storagePath: config.memoryPath });
+    this.memory.load();
+  }
+  refresh(force = false, options) {
+    return this.agent.refresh(force, options);
+  }
+  index(force = false, options) {
+    return this.refresh(force, options);
+  }
+  getRefreshStatus() {
+    return this.agent.getRefreshStatus();
+  }
+  status() {
+    return this.getRefreshStatus();
+  }
+  syncParsedMirrors(force = false) {
+    return this.agent.syncParsedMirrors(force);
+  }
+  syncMinSync() {
+    return this.agent.syncMinSync();
+  }
+  prepareJikji() {
+    return this.agent.prepareJikji();
+  }
+  startWatchRefresh(options) {
+    return this.agent.startWatchRefresh(options);
+  }
+  getRetrievalEngine() {
+    return this.retrievalEngine;
+  }
+  retrieve(query, options) {
+    return this.retrievalEngine.retrieve(query, options);
+  }
+  retrieveByMethod(query, options) {
+    return this.retrievalEngine.retrieveByMethod(query, options);
+  }
+  recordStructuredResultsSession(sessionId, query, details) {
+    return recordStructuredResultsSession(sessionId, query, details, this.sessions, this.memory);
+  }
+  recordReport(query, details) {
+    return this.recordStructuredResultsSession(randomUUID8(), query, details);
+  }
+  getResultRegistry(sessionId) {
+    return this.sessions.get(sessionId)?.registry ?? new Map;
+  }
+  recordFeedbackByNumbers(sessionId, usefulNumbers, notUsefulNumbers = []) {
+    recordNumberedFeedback(this.sessions, this.memory, sessionId, usefulNumbers, notUsefulNumbers);
+  }
+  getMemorySchema() {
+    return structuredClone(this.memory.getSchema());
+  }
+}
+function createAutoRAGLite(options = {}) {
+  const input = { flags: options.flags ?? {} };
+  if (options.env !== undefined)
+    input.env = options.env;
+  if (options.cwd !== undefined)
+    input.cwd = options.cwd;
+  if (options.readOnly !== undefined)
+    input.readOnly = options.readOnly;
+  return new AutoRAGLite(resolveConfig(input));
+}
+var init_core = __esm(() => {
+  init_agent();
+  init_search_documents();
+  init_config2();
+  init_memory();
+  init_config2();
+});
+
+// src/cli/commands/lite-refresh.ts
+async function runLiteRefresh(ctx) {
+  try {
+    const lite = createAutoRAGLite({ flags: ctx.flags, cwd: ctx.cwd });
+    const methods = parseMethodFlag(ctx.flags.method);
+    const force = ctx.flags.force === true || ctx.flags.full === true;
+    const result = await lite.refresh(force, methods ? { methods } : undefined);
+    await Promise.resolve();
+    ctx.stdout(renderRefresh(result, { json: ctx.json, debug: ctx.debug }));
+    return 0;
+  } catch (error) {
+    ctx.stderr(renderError(error, { json: ctx.json, debug: ctx.debug }));
+    return error instanceof ConfigError ? 2 : 1;
+  }
+}
+var init_lite_refresh = __esm(() => {
+  init_core();
+  init_config2();
+  init_refresh();
+});
+
+// src/mirror/index.ts
+var init_mirror = __esm(() => {
+  init_index_store();
+  init_paths();
+  init_sync();
+});
+
+// src/cli/commands/lite-retrieve.ts
+import { existsSync as existsSync21, readFileSync as readFileSync15 } from "node:fs";
+function parseIntOptional2(value) {
+  if (typeof value !== "string" || value.trim() === "")
+    return;
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed))
+    return;
+  return Math.trunc(parsed);
+}
+function parseCsvStrings2(value) {
+  if (typeof value !== "string" || value.trim() === "")
+    return;
+  const parts = value.split(",").map((part) => part.trim()).filter((part) => part !== "");
+  return parts.length > 0 ? parts : undefined;
+}
+function buildRetrieveOptions(flags) {
+  const options = {};
+  const topK = parseIntOptional2(flags["top-k"]);
+  if (topK !== undefined)
+    options.topK = topK;
+  if (typeof flags.scope === "string" && flags.scope.trim() !== "")
+    options.scope = flags.scope;
+  const tags = parseCsvStrings2(flags.tags);
+  if (tags !== undefined)
+    options.allowedTags = tags;
+  return options;
+}
+function parseTopK(value) {
+  if (value === undefined || value === true || value === false)
+    return { kind: "ok", value: undefined };
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || !Number.isInteger(parsed)) {
+    return { kind: "reject", error: `Invalid --top-k value: "${String(value)}". Must be a positive integer.` };
+  }
+  if (parsed < 1) {
+    return { kind: "reject", error: `Invalid --top-k value: ${parsed}. Must be a positive integer.` };
+  }
+  return { kind: "ok", value: parsed };
+}
+function diagnosticProjection2(d) {
+  const out = {
+    code: d.code,
+    severity: d.severity,
+    message: d.message
+  };
+  if (d.source !== undefined) {
+    out.source = d.source;
+  }
+  return out;
+}
+function renderLiteRetrieveJson(envelope) {
+  return JSON.stringify(envelope, null, 2);
+}
+function renderLiteRetrieveHuman(envelope, debug) {
+  const lines = [];
+  if (!envelope.ok) {
+    lines.push(`error: index not ready`);
+    for (const d of envelope.diagnostics) {
+      lines.push(`  diagnostic: [${d.severity}] ${d.code}: ${d.message}`);
+    }
+    return lines.join(`
+`);
+  }
+  const okEnvelope = envelope;
+  if (okEnvelope.results.length === 0) {
+    lines.push("retrieve: no results");
+  } else {
+    lines.push("results:");
+    for (const r of okEnvelope.results) {
+      lines.push(`  ${r.number}. source: ${r.source} | method: ${r.method} | score: ${r.score}`);
+      if (r.content.length > 0) {
+        lines.push(`     ${r.content.slice(0, 200)}`);
+      }
+      if (debug) {
+        lines.push(`     metadata: ${JSON.stringify(r.metadata)}`);
+      }
+    }
+  }
+  if (debug && okEnvelope.diagnostics.length > 0) {
+    for (const d of okEnvelope.diagnostics) {
+      lines.push(`  diagnostic: [${d.severity}] ${d.code}: ${d.message}`);
+    }
+  }
+  return lines.join(`
+`);
+}
+function hasCompletedParsedRefresh(workspacePath) {
+  const markerPath = refreshReadinessPath(workspacePath);
+  if (!existsSync21(markerPath))
+    return false;
+  try {
+    const marker = JSON.parse(readFileSync15(markerPath, "utf8"));
+    return typeof marker === "object" && marker !== null && "version" in marker && marker.version === 1 && "completed" in marker && marker.completed === true && "parsed" in marker && marker.parsed === true;
+  } catch {
+    return false;
+  }
+}
+async function runLiteRetrieve(ctx) {
+  const query = ctx.positionals.join(" ").trim();
+  if (query.length === 0) {
+    ctx.stderr(renderError(new Error("Usage: autorag lite retrieve <query> [--top-k N] [--scope SCOPE] [--tags tag1,tag2]"), {
+      json: ctx.json,
+      debug: ctx.debug
+    }));
+    return 2;
+  }
+  const topKResult = parseTopK(ctx.flags["top-k"]);
+  if (topKResult.kind === "reject") {
+    const envelope = { ok: false, error: topKResult.error };
+    ctx.stderr(renderLiteRetrieveJson(envelope));
+    return 2;
+  }
+  let lite;
+  try {
+    lite = createAutoRAGLite({ flags: ctx.flags, cwd: ctx.cwd });
+  } catch (error) {
+    ctx.stderr(renderError(error, { json: ctx.json, debug: ctx.debug }));
+    return 2;
+  }
+  const workspacePath = lite.config.workspacePath;
+  const parsedReady = hasCompletedParsedRefresh(workspacePath);
+  if (!parsedReady) {
+    const envelope = {
+      ok: false,
+      query,
+      diagnostics: [
+        {
+          code: "index-not-ready",
+          severity: "error",
+          message: "Index has not been refreshed. Run `autorag lite refresh` or `autorag refresh` before retrieving."
+        }
+      ]
+    };
+    ctx.stdout(renderLiteRetrieveJson(envelope));
+    return 2;
+  }
+  const staleDiagnostics = await detectMirrorStaleness({
+    root: workspacePath,
+    searchPaths: lite.config.searchPaths,
+    parserOptions: lite.config.parserOptions
+  });
+  if (staleDiagnostics.length > 0) {
+    const envelope = {
+      ok: false,
+      query,
+      diagnostics: [
+        {
+          code: "index-not-ready",
+          severity: "error",
+          message: "Index is stale. Run `autorag lite refresh` or `autorag refresh` before retrieving."
+        }
+      ]
+    };
+    ctx.stdout(renderLiteRetrieveJson(envelope));
+    return 2;
+  }
+  const options = buildRetrieveOptions(ctx.flags);
+  let retrievalResult;
+  try {
+    retrievalResult = await lite.retrieve(query, {
+      topK: topKResult.value ?? options.topK,
+      scope: options.scope,
+      allowedTags: options.allowedTags
+    });
+  } catch (error) {
+    ctx.stderr(renderError(error, { json: ctx.json, debug: ctx.debug }));
+    return 1;
+  }
+  const diagnostics = (retrievalResult.diagnostics ?? []).map(diagnosticProjection2);
+  const results = retrievalResult.results.map((r, i) => ({
+    number: i + 1,
+    source: r.source,
+    method: typeof r.metadata.method === "string" ? r.metadata.method : "unknown",
+    score: r.score,
+    metadata: r.metadata,
+    content: r.content
+  }));
+  const envelope = {
+    ok: true,
+    query,
+    results,
+    diagnostics
+  };
+  if (ctx.json) {
+    ctx.stdout(renderLiteRetrieveJson(envelope));
+  } else {
+    ctx.stdout(renderLiteRetrieveHuman(envelope, ctx.debug));
+  }
+  return 0;
+}
+var init_lite_retrieve = __esm(() => {
+  init_core();
+  init_mirror();
+  init_paths();
+});
+
+// src/cli/commands/report.ts
+import { readFileSync as readFileSync16 } from "node:fs";
+import { Value } from "typebox/value";
+function readReportInput(input) {
+  if (typeof input === "string" && input.length > 0)
+    return readFileSync16(input, "utf8");
+  return readFileSync16(0, "utf8");
+}
+function validateReport(value) {
+  if (!Value.Check(emitResultsSchema, value)) {
+    throw new Error("Invalid report: expected the emit_autorag_results JSON schema");
+  }
+  const parsed = Value.Parse(emitResultsSchema, value);
+  const resultNumbers = parsed.results.map((result) => result.number);
+  const mappingNumbers = parsed.mapping.map((entry) => entry.number);
+  const allNumbers = [...resultNumbers, ...mappingNumbers];
+  const uniqueResultNumbers = new Set(resultNumbers);
+  const uniqueMappingNumbers = new Set(mappingNumbers);
+  const oneToOne = resultNumbers.length === mappingNumbers.length && uniqueResultNumbers.size === resultNumbers.length && uniqueMappingNumbers.size === mappingNumbers.length && resultNumbers.every((number) => uniqueMappingNumbers.has(number));
+  if (!oneToOne || allNumbers.some((number) => number < 1)) {
+    throw new Error("Invalid report: results and mapping numbers must be one-to-one positive numbers");
+  }
+  if (parsed.results.some((result) => !Number.isFinite(result.confidence) || result.confidence < 0 || result.confidence > 1)) {
+    throw new Error("Invalid report: result confidence must be in [0, 1]");
+  }
+  if (parsed.mapping.some((entry) => (entry.evidenceRefs ?? []).some((reference) => reference.confidence !== undefined && (!Number.isFinite(reference.confidence) || reference.confidence < 0 || reference.confidence > 1)))) {
+    throw new Error("Invalid report: evidence confidence must be in [0, 1]");
+  }
+  return {
+    answer: parsed.answer,
+    results: parsed.results,
+    mapping: parsed.mapping.map((entry) => ({
+      ...entry,
+      evidenceRefs: entry.evidenceRefs ?? [{ method: entry.method, source: entry.source, content: entry.content }]
+    })),
+    warnings: parsed.warnings ?? []
+  };
+}
+function renderReport(details, sessionId, query, json) {
+  const envelope = { ok: true, sessionId, query, answer: details.answer, resultCount: details.results.length };
+  if (json)
+    return JSON.stringify(envelope, null, 2);
+  return `report: ok
+  sessionId: ${sessionId}
+  results: ${details.results.length}`;
+}
+function renderReportError(error, json, debug) {
+  if (!json)
+    return renderError(error, { json, debug });
+  const message = error instanceof Error ? error.message : String(error);
+  return JSON.stringify({ ok: false, error: message });
+}
+async function runReport(ctx) {
+  const query = ctx.positionals.join(" ").trim();
+  if (query.length === 0) {
+    ctx.stderr(renderError(new Error("Usage: autorag lite report <query> [--input FILE]"), { json: ctx.json }));
+    return 2;
+  }
+  let details;
+  try {
+    const text = readReportInput(ctx.flags.input);
+    const parsed = JSON.parse(text);
+    details = validateReport(parsed);
+  } catch (error) {
+    ctx.stderr(renderReportError(error, ctx.json, ctx.debug));
+    return 2;
+  }
+  try {
+    const lite = createAutoRAGLite({ flags: ctx.flags, cwd: ctx.cwd });
+    const response = lite.recordReport(query, details);
+    ctx.stdout(renderReport(details, response.sessionId, query, ctx.json));
+    return 0;
+  } catch (error) {
+    ctx.stderr(renderError(error, { json: ctx.json, debug: ctx.debug }));
+    return error instanceof ConfigError ? 2 : 1;
+  }
+}
+var init_report = __esm(() => {
+  init_emit_results_tool();
+  init_core();
+  init_config2();
+});
+
+// src/cli/commands/lite.ts
+async function runLite(ctx) {
+  const sub = ctx.positionals[0];
+  if (ctx.flags.help === true || sub === undefined || sub === "help") {
+    ctx.stdout(LITE_USAGE.trimEnd());
+    return 0;
+  }
+  const subCtx = {
+    ...ctx,
+    positionals: ctx.positionals.slice(1)
+  };
+  switch (sub) {
+    case "init":
+      return runInit(subCtx);
+    case "ui":
+      return runUi(subCtx);
+    case "refresh":
+      return runLiteRefresh(subCtx);
+    case "watch":
+      return runWatch(subCtx);
+    case "status":
+      return runStatus(subCtx);
+    case "index":
+      return runIndex(subCtx);
+    case "duplicates":
+      return runDuplicates(subCtx);
+    case "health":
+      return runStatus(subCtx);
+    case "retrieve": {
+      await Promise.resolve().then(() => init_lite_retrieve());
+      return runLiteRetrieve(subCtx);
+    }
+    case "report": {
+      await Promise.resolve().then(() => init_report());
+      return runReport(subCtx);
+    }
+    default:
+      ctx.stderr(`Unknown lite subcommand: ${sub}
+
+${LITE_USAGE}`);
+      return 2;
+  }
+}
+var LITE_USAGE = `autorag lite - model-free AutoRAG lifecycle CLI
+
+Usage: autorag lite <subcommand> [args] [flags]
+
+Subcommands:
+  autorag lite init
+                       Write the configured model-free lifecycle config
+                       (--search-paths PATHS  --workspace DIR  --memory-path FILE  --force)
+  autorag lite ui      Open the local datasource setup UI
+                       (--port N  --host 127.0.0.1  --no-open  --allow-remote)
+  autorag lite refresh Run an incremental index refresh (no model required)
+                       (--full  --force  --method minsync,parsed,datasources,jikji,all)
+  autorag lite watch  Watch configured roots (or --once for one refresh tick)
+                       (--once  --immediate  --debounce-ms N  --force)
+  autorag lite status  Show path-opaque corpus freshness and index health
+  autorag lite index   Reset or rebuild parsed/MinSync indexes
+                       (reset|rebuild  --yes  --method)
+  autorag lite duplicates
+                       Scan duplicate document families without deleting files
+  autorag lite health  Show model-free index health (alias of lite status)
+  autorag lite retrieve <query>
+                       Retrieve documents without model curation
+                       (--top-k N  --scope SCOPE  --tags A,B  --json  --debug)
+  autorag lite report <query>
+                       Persist a structured report from external curation
+                       (--input FILE  --json  --debug)
+
+Global flags:
+  --json               Emit machine-readable JSON
+  --debug              Reveal opaque internal diagnostics
+  --config <path>      Use a specific config file
+  --help, -h           Show this help
+`;
+var init_lite = __esm(() => {
+  init_duplicates();
+  init_commands();
+  init_init();
+  init_lite_refresh();
+  init_status();
+  init_ui();
+  init_watch();
+});
+
 // src/cli/index.ts
 import { realpathSync as realpathSync5 } from "node:fs";
 import { createInterface } from "node:readline";
@@ -17996,7 +18698,8 @@ var BOOLEAN_FLAGS = new Set([
   "immediate",
   "skip-probes",
   "no-open",
-  "allow-remote"
+  "allow-remote",
+  "full"
 ]);
 var VALUE_FLAGS = new Set([
   "config",
@@ -18024,7 +18727,8 @@ var VALUE_FLAGS = new Set([
   "minsync-max-chunk-size",
   "timeout-ms",
   "port",
-  "host"
+  "host",
+  "input"
 ]);
 var COMMANDS = [
   "init",
@@ -18039,7 +18743,8 @@ var COMMANDS = [
   "health",
   "duplicates",
   "tui",
-  "ui"
+  "ui",
+  "lite"
 ];
 var USAGE2 = `autorag - self-evolving librarian CLI
 
@@ -18062,6 +18767,13 @@ Commands:
   index reset          Remove parsed/minsync indexes (--method)
   index rebuild        Reset then re-run a refresh (--method minsync|all)
   health               Check model/provider auth and completion access (no index check)
+  lite init|ui|refresh|watch|status|index|duplicates|health
+                       Model-free setup, indexing, status, and datasource lifecycle
+                       (lite refresh: --full --force --method; watch: --once)
+  lite retrieve <query>
+                       Retrieve documents without model curation
+                       (--top-k N  --scope SCOPE  --tags A,B  --json  --debug)
+  lite report <query>   Persist a structured report (--input FILE)
   duplicates [DIR]     Scan exact/near duplicate document families; never deletes files
   tui                  Open an interactive Pi-powered librarian terminal UI
   ui                   Open a local loopback page to connect and manage data sources
@@ -18190,6 +18902,9 @@ async function dispatch(command, ctx) {
       await Promise.resolve().then(() => init_ui());
       return runUi(ctx);
     }
+    case "lite": {
+      return dispatchLite(ctx);
+    }
   }
 }
 async function main(argv) {
@@ -18204,8 +18919,10 @@ async function main(argv) {
   const json = flags.json === true;
   const debug = flags.debug === true;
   if (flags.help === true || command === undefined || command === "help") {
-    process.stdout.write(USAGE2);
-    return 0;
+    if (command === "lite") {} else {
+      process.stdout.write(USAGE2);
+      return 0;
+    }
   }
   if (!COMMANDS.includes(command)) {
     process.stderr.write(`Unknown command: ${command}
@@ -18243,6 +18960,10 @@ function isInvokedDirectly() {
     return false;
   }
 }
+async function dispatchLite(ctx) {
+  await Promise.resolve().then(() => init_lite());
+  return runLite(ctx);
+}
 if (isInvokedDirectly()) {
   main(process.argv.slice(2)).then((code) => {
     process.exitCode = code;