@tryformation/querylight-cli 0.2.4 → 0.2.6

package/dist/cli/main.js

@@ -2,8 +2,8 @@
 
 // src/cli/run-cli.ts
 import { Command, Option } from "commander";
-import { readFile as readFile11, stat as stat5 } from "fs/promises";
-import path22 from "path";
+import { readFile as readFile12, stat as stat6 } from "fs/promises";
+import path23 from "path";
 
 // src/chunk/chunker.ts
 import { readFile as readFile3 } from "fs/promises";
@@ -16,7 +16,11 @@ import path from "path";
 import YAML from "yaml";
 
 // src/core/constants.ts
-var PACKAGE_VERSION = "0.2.3";
+import { createRequire } from "module";
+var require2 = createRequire(import.meta.url);
+var packageJson = require2("../../package.json");
+var PACKAGE_NAME = packageJson.name;
+var PACKAGE_VERSION = packageJson.version;
 var DEFAULT_WORKSPACE = ".kb";
 var DEFAULT_SHARED_MODEL_CACHE_DIR = "~/.qli/models/huggingface";
 var LEGACY_WORKSPACE_MODEL_CACHE_DIR = ".kb/models/huggingface";
@@ -49,6 +53,9 @@ var defaultConfig = () => ({
     maxContextChars: 12e3,
     citationStyle: "markdown"
   },
+  search: {
+    defaultTopK: 50
+  },
   retrieval: {
     defaultMode: "lexical",
     dense: {
@@ -70,12 +77,12 @@ var defaultConfig = () => ({
     }
   },
   crawler: {
-    defaultUserAgent: "querylight-cli/0.1",
+    defaultUserAgent: "querylight-cli",
     obeyRobotsTxt: true,
     rateLimitMs: 1e3,
     maxConcurrentRequests: 5,
     renderJs: false,
-    retentionDays: 365,
+    retentionDays: 30,
     fetchArticles: true
   },
   limits: {
@@ -119,6 +126,10 @@ async function loadConfig(workspacePath, configPath) {
       ...defaults.rag,
       ...parsed.rag ?? {}
     },
+    search: {
+      ...defaults.search,
+      ...parsed.search ?? {}
+    },
     retrieval: {
       ...defaults.retrieval,
       ...parsed.retrieval ?? {},
@@ -373,27 +384,138 @@ async function assertWorkspaceExists(workspacePath) {
   }
 }
 
+// src/core/archive.ts
+import { mkdir as mkdir3, readdir, readFile as readFile4, rm, stat as stat2, writeFile as writeFile3 } from "fs/promises";
+import os from "os";
+import path6 from "path";
+import { unzipSync, zipSync } from "fflate";
+function isWorkspaceArchivePath(workspacePath) {
+  return workspacePath.toLowerCase().endsWith(".zip");
+}
+async function collectFiles(root, outputPath) {
+  const files = {};
+  const resolvedOutput = path6.resolve(outputPath);
+  async function visit(dir) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const absolute = path6.join(dir, entry.name);
+      if (path6.resolve(absolute) === resolvedOutput) {
+        continue;
+      }
+      if (entry.isDirectory()) {
+        await visit(absolute);
+        continue;
+      }
+      if (!entry.isFile()) {
+        continue;
+      }
+      const relative = path6.relative(root, absolute).split(path6.sep).join("/");
+      files[relative] = new Uint8Array(await readFile4(absolute));
+    }
+  }
+  await visit(root);
+  return files;
+}
+async function packageWorkspaceArchive({
+  workspacePath,
+  outputPath,
+  force = false
+}) {
+  const workspace = await assertWorkspaceExists(workspacePath);
+  const archivePath = path6.resolve(outputPath);
+  try {
+    await stat2(archivePath);
+    if (!force) {
+      throw new CliError(`archive already exists: ${archivePath}`, "INVALID_ARGUMENT", 2 /* InvalidArguments */);
+    }
+  } catch (error) {
+    if (error instanceof CliError) {
+      throw error;
+    }
+    if (error.code !== "ENOENT") {
+      throw error;
+    }
+  }
+  const files = await collectFiles(workspace, archivePath);
+  const archive = zipSync(files, { level: 6 });
+  await mkdir3(path6.dirname(archivePath), { recursive: true });
+  await writeFile3(archivePath, archive);
+  const archiveStat = await stat2(archivePath);
+  return {
+    workspacePath: workspace,
+    archivePath,
+    fileCount: Object.keys(files).length,
+    sizeBytes: archiveStat.size
+  };
+}
+function assertSafeArchiveEntry(name) {
+  const normalized = path6.posix.normalize(name);
+  if (name.startsWith("/") || normalized === "." || normalized.startsWith("../") || normalized.includes("/../")) {
+    throw new CliError(`unsafe archive entry: ${name}`, "WORKSPACE_ERROR", 3 /* WorkspaceError */);
+  }
+}
+async function archiveCachePath(archivePath) {
+  const info = await stat2(archivePath);
+  const key = sha256(`${path6.resolve(archivePath)}:${info.size}:${info.mtimeMs}`).slice(0, 24);
+  return path6.join(os.tmpdir(), "qli-workspace-archives", key);
+}
+async function resolveReadableWorkspace(workspacePath) {
+  const resolved = path6.resolve(workspacePath);
+  if (!isWorkspaceArchivePath(resolved)) {
+    return { workspacePath: await assertWorkspaceExists(resolved) };
+  }
+  const archive = await readFile4(resolved);
+  const extractRoot = await archiveCachePath(resolved);
+  const workspaceRoot = path6.join(extractRoot, "workspace");
+  try {
+    await assertWorkspaceExists(workspaceRoot);
+    return { workspacePath: workspaceRoot, archivePath: resolved };
+  } catch {
+  }
+  await rm(extractRoot, { recursive: true, force: true });
+  await mkdir3(workspaceRoot, { recursive: true });
+  const entries = unzipSync(new Uint8Array(archive));
+  await Promise.all(Object.entries(entries).map(async ([entryName, data]) => {
+    assertSafeArchiveEntry(entryName);
+    const target = path6.join(workspaceRoot, ...entryName.split("/"));
+    if (entryName.endsWith("/")) {
+      await mkdir3(target, { recursive: true });
+      return;
+    }
+    await mkdir3(path6.dirname(target), { recursive: true });
+    await writeFile3(target, Buffer.from(data));
+  }));
+  return { workspacePath: await assertWorkspaceExists(workspaceRoot), archivePath: resolved };
+}
+async function assertWritableWorkspacePath(workspacePath) {
+  const resolved = path6.resolve(workspacePath);
+  if (isWorkspaceArchivePath(resolved)) {
+    throw new CliError("zip workspaces are read-only; package a rebuilt directory workspace instead", "WORKSPACE_ERROR", 3 /* WorkspaceError */);
+  }
+  return resolved;
+}
+
 // src/index/querylight-indexer.ts
 import { Analyzer, DateFieldIndex, DocumentIndex, KeywordTokenizer, LowerCaseTextFilter, RankingAlgorithm, StoredSourceIndex, TextFieldIndex } from "@tryformation/querylight-ts";
-import path11 from "path";
+import path12 from "path";
 
 // src/vector/dense.ts
 import { VectorFieldIndex, cosineSimilarity, createSeededRandom } from "@tryformation/querylight-ts";
-import { mkdir as mkdir4 } from "fs/promises";
-import path8 from "path";
+import { mkdir as mkdir5 } from "fs/promises";
+import path9 from "path";
 
 // src/vector/runtime.ts
-import os from "os";
-import path6 from "path";
+import os2 from "os";
+import path7 from "path";
 import { fileURLToPath } from "url";
 import { execFile, execFileSync } from "child_process";
-import { mkdtemp, rm, writeFile as writeFile3 } from "fs/promises";
+import { mkdtemp, rm as rm2, writeFile as writeFile4 } from "fs/promises";
 
 // src/core/files.ts
-import { stat as stat2 } from "fs/promises";
+import { stat as stat3 } from "fs/promises";
 async function fileExists(filePath) {
   try {
-    await stat2(filePath);
+    await stat3(filePath);
     return true;
   } catch {
     return false;
@@ -403,35 +525,35 @@ async function fileExists(filePath) {
 // src/vector/runtime.ts
 var sparseExecFileSync = execFileSync;
 function resolveQliHomeDir() {
-  return path6.resolve(process.env.QLI_HOME ?? path6.join(os.homedir(), ".qli"));
+  return path7.resolve(process.env.QLI_HOME ?? path7.join(os2.homedir(), ".qli"));
 }
 function resolveCacheDir(workspacePath, configuredPath) {
   if (configuredPath === "~/.qli") {
     return resolveQliHomeDir();
   }
   if (configuredPath.startsWith("~/.qli/")) {
-    return path6.join(resolveQliHomeDir(), configuredPath.slice("~/.qli/".length));
+    return path7.join(resolveQliHomeDir(), configuredPath.slice("~/.qli/".length));
   }
   if (configuredPath === "~") {
-    return os.homedir();
+    return os2.homedir();
   }
   if (configuredPath.startsWith("~/")) {
-    return path6.join(os.homedir(), configuredPath.slice(2));
+    return path7.join(os2.homedir(), configuredPath.slice(2));
   }
-  return path6.isAbsolute(configuredPath) ? configuredPath : path6.resolve(workspacePath, configuredPath.replace(/^\.kb\//, ""));
+  return path7.isAbsolute(configuredPath) ? configuredPath : path7.resolve(workspacePath, configuredPath.replace(/^\.kb\//, ""));
 }
 function packageRootFromImportMeta(importMetaUrl) {
-  return path6.resolve(path6.dirname(fileURLToPath(importMetaUrl)), "..");
+  return path7.resolve(path7.dirname(fileURLToPath(importMetaUrl)), "..");
 }
 async function sparseScriptPath(importMetaUrl) {
   const base = packageRootFromImportMeta(importMetaUrl);
   const candidates = [
-    path6.join(base, "scripts", "sparse-encode.py"),
-    path6.join(base, "..", "scripts", "sparse-encode.py")
+    path7.join(base, "scripts", "sparse-encode.py"),
+    path7.join(base, "..", "scripts", "sparse-encode.py")
   ];
   for (const candidate of candidates) {
     if (await fileExists(candidate)) {
-      return path6.resolve(candidate);
+      return path7.resolve(candidate);
     }
   }
   throw new Error(`sparse helper script not found; checked ${candidates.join(", ")}`);
@@ -457,9 +579,9 @@ async function runSparsePython({
 }) {
   const cacheDir = resolveCacheDir(workspacePath, config.cacheDir);
   const scriptPath = await sparseScriptPath(importMetaUrl);
-  const payloadDir = await mkdtemp(path6.join(os.tmpdir(), "qli-sparse-"));
-  const payloadPath = path6.join(payloadDir, "payload.json");
-  await writeFile3(payloadPath, JSON.stringify(payload), "utf8");
+  const payloadDir = await mkdtemp(path7.join(os2.tmpdir(), "qli-sparse-"));
+  const payloadPath = path7.join(payloadDir, "payload.json");
+  await writeFile4(payloadPath, JSON.stringify(payload), "utf8");
   try {
     return sparseExecFileSync(
       "uv",
@@ -485,7 +607,7 @@ async function runSparsePython({
       }
     );
   } finally {
-    await rm(payloadDir, { recursive: true, force: true });
+    await rm2(payloadDir, { recursive: true, force: true });
   }
 }
 async function getDenseTransformersRuntime(cacheDir) {
@@ -499,28 +621,28 @@ async function getDenseTransformersRuntime(cacheDir) {
 }
 
 // src/vector/store.ts
-import { mkdir as mkdir3, rm as rm2, writeFile as writeFile5 } from "fs/promises";
-import path7 from "path";
+import { mkdir as mkdir4, rm as rm3, writeFile as writeFile6 } from "fs/promises";
+import path8 from "path";
 
 // src/core/gzip-json.ts
-import { readFile as readFile4, writeFile as writeFile4 } from "fs/promises";
+import { readFile as readFile5, writeFile as writeFile5 } from "fs/promises";
 import { promisify } from "util";
 import { gunzip, gzip } from "zlib";
 var gzipAsync = promisify(gzip);
 var gunzipAsync = promisify(gunzip);
 async function writeGzipJson(filePath, value) {
   const payload = JSON.stringify(value, null, 2);
-  await writeFile4(filePath, await gzipAsync(Buffer.from(payload, "utf8")));
+  await writeFile5(filePath, await gzipAsync(Buffer.from(payload, "utf8")));
 }
 async function readJsonFromGzipOrFile(gzipPath, legacyPath) {
   if (await fileExists(gzipPath)) {
-    const payload = await readFile4(gzipPath);
+    const payload = await readFile5(gzipPath);
     return JSON.parse((await gunzipAsync(payload)).toString("utf8"));
   }
   if (legacyPath && await fileExists(legacyPath)) {
-    return JSON.parse(await readFile4(legacyPath, "utf8"));
+    return JSON.parse(await readFile5(legacyPath, "utf8"));
   }
-  return JSON.parse(await readFile4(gzipPath, "utf8"));
+  return JSON.parse(await readFile5(gzipPath, "utf8"));
 }
 async function resolveExistingGzipOrFilePath(gzipPath, legacyPath) {
   if (await fileExists(gzipPath)) {
@@ -534,39 +656,39 @@ async function resolveExistingGzipOrFilePath(gzipPath, legacyPath) {
 
 // src/vector/store.ts
 function vectorsDir(workspacePath) {
-  return path7.join(workspacePath, "vectors");
+  return path8.join(workspacePath, "vectors");
 }
 function sharedModelStateDir() {
-  return path7.join(resolveQliHomeDir(), "models", "status");
+  return path8.join(resolveQliHomeDir(), "models", "status");
 }
 function denseVectorPath(workspacePath) {
-  return path7.join(vectorsDir(workspacePath), "dense.latest.json.gz");
+  return path8.join(vectorsDir(workspacePath), "dense.latest.json.gz");
 }
 function denseMetaPath(workspacePath) {
-  return path7.join(vectorsDir(workspacePath), "dense.latest.meta.json.gz");
+  return path8.join(vectorsDir(workspacePath), "dense.latest.meta.json.gz");
 }
 function sparseVectorPath(workspacePath) {
-  return path7.join(vectorsDir(workspacePath), "sparse.latest.json.gz");
+  return path8.join(vectorsDir(workspacePath), "sparse.latest.json.gz");
 }
 function sparseMetaPath(workspacePath) {
-  return path7.join(vectorsDir(workspacePath), "sparse.latest.meta.json.gz");
+  return path8.join(vectorsDir(workspacePath), "sparse.latest.meta.json.gz");
 }
 function legacyDenseVectorPath(workspacePath) {
-  return path7.join(vectorsDir(workspacePath), "dense.latest.json");
+  return path8.join(vectorsDir(workspacePath), "dense.latest.json");
 }
 function legacyDenseMetaPath(workspacePath) {
-  return path7.join(vectorsDir(workspacePath), "dense.latest.meta.json");
+  return path8.join(vectorsDir(workspacePath), "dense.latest.meta.json");
 }
 function legacySparseVectorPath(workspacePath) {
-  return path7.join(vectorsDir(workspacePath), "sparse.latest.json");
+  return path8.join(vectorsDir(workspacePath), "sparse.latest.json");
 }
 function legacySparseMetaPath(workspacePath) {
-  return path7.join(vectorsDir(workspacePath), "sparse.latest.meta.json");
+  return path8.join(vectorsDir(workspacePath), "sparse.latest.meta.json");
 }
 function pullMarkerPath(type, workspacePath, modelId, cacheDir) {
   const resolvedCacheDir = resolveCacheDir(workspacePath, cacheDir);
   const cacheKey = sha256(resolvedCacheDir).slice(0, 16);
-  return path7.join(sharedModelStateDir(), type, `${encodeURIComponent(modelId)}.${cacheKey}.json`);
+  return path8.join(sharedModelStateDir(), type, `${encodeURIComponent(modelId)}.${cacheKey}.json`);
 }
 function densePullMarker(workspacePath, modelId, cacheDir) {
   return pullMarkerPath("dense", workspacePath, modelId, cacheDir);
@@ -575,24 +697,24 @@ function sparsePullMarker(workspacePath, modelId, cacheDir) {
   return pullMarkerPath("sparse", workspacePath, modelId, cacheDir);
 }
 async function writeDensePayload(workspacePath, payload) {
-  await mkdir3(vectorsDir(workspacePath), { recursive: true });
+  await mkdir4(vectorsDir(workspacePath), { recursive: true });
   await writeGzipJson(denseVectorPath(workspacePath), payload);
   await writeGzipJson(denseMetaPath(workspacePath), payload.metadata);
   await Promise.all([
-    rm2(legacyDenseVectorPath(workspacePath), { force: true }),
-    rm2(legacyDenseMetaPath(workspacePath), { force: true })
+    rm3(legacyDenseVectorPath(workspacePath), { force: true }),
+    rm3(legacyDenseMetaPath(workspacePath), { force: true })
   ]);
 }
 async function readDensePayload(workspacePath) {
   return readJsonFromGzipOrFile(denseVectorPath(workspacePath), legacyDenseVectorPath(workspacePath));
 }
 async function writeSparsePayload(workspacePath, payload) {
-  await mkdir3(vectorsDir(workspacePath), { recursive: true });
+  await mkdir4(vectorsDir(workspacePath), { recursive: true });
   await writeGzipJson(sparseVectorPath(workspacePath), payload);
   await writeGzipJson(sparseMetaPath(workspacePath), payload.metadata);
   await Promise.all([
-    rm2(legacySparseVectorPath(workspacePath), { force: true }),
-    rm2(legacySparseMetaPath(workspacePath), { force: true })
+    rm3(legacySparseVectorPath(workspacePath), { force: true }),
+    rm3(legacySparseMetaPath(workspacePath), { force: true })
   ]);
 }
 async function readSparsePayload(workspacePath) {
@@ -600,13 +722,13 @@ async function readSparsePayload(workspacePath) {
 }
 async function writeDensePullMarker(workspacePath, model, value) {
   const markerPath = densePullMarker(workspacePath, model.modelId, model.cacheDir);
-  await mkdir3(path7.dirname(markerPath), { recursive: true });
-  await writeFile5(markerPath, JSON.stringify(value, null, 2), "utf8");
+  await mkdir4(path8.dirname(markerPath), { recursive: true });
+  await writeFile6(markerPath, JSON.stringify(value, null, 2), "utf8");
 }
 async function writeSparsePullMarker(workspacePath, model, value) {
   const markerPath = sparsePullMarker(workspacePath, model.modelId, model.cacheDir);
-  await mkdir3(path7.dirname(markerPath), { recursive: true });
-  await writeFile5(markerPath, JSON.stringify(value, null, 2), "utf8");
+  await mkdir4(path8.dirname(markerPath), { recursive: true });
+  await writeFile6(markerPath, JSON.stringify(value, null, 2), "utf8");
 }
 async function buildModelStatus(workspacePath, dense, sparse, uvAvailable) {
   const denseCacheDir = resolveCacheDir(workspacePath, dense.cacheDir);
@@ -709,7 +831,7 @@ function exactDenseQuery(payload, vector, topK) {
 }
 async function pullDenseModel(workspacePath, config) {
   const cacheDir = resolveCacheDir(workspacePath, config.cacheDir);
-  await mkdir4(cacheDir, { recursive: true });
+  await mkdir5(cacheDir, { recursive: true });
   const embedder = await createEmbedder(cacheDir, config.modelId);
   try {
     await embedder.embed("warm dense model cache");
@@ -722,9 +844,9 @@ async function buildDenseVectors({
   config,
   progress
 }) {
-  const chunks = await readJsonl(path8.join(workspacePath, "chunks", "chunks.jsonl"));
+  const chunks = await readJsonl(path9.join(workspacePath, "chunks", "chunks.jsonl"));
   const cacheDir = resolveCacheDir(workspacePath, config.cacheDir);
-  await mkdir4(cacheDir, { recursive: true });
+  await mkdir5(cacheDir, { recursive: true });
   const embedder = await createEmbedder(cacheDir, config.modelId);
   try {
     const records = [];
@@ -808,8 +930,8 @@ async function denseQuery({
 
 // src/vector/sparse.ts
 import { SparseVectorFieldIndex } from "@tryformation/querylight-ts";
-import { mkdir as mkdir5 } from "fs/promises";
-import path9 from "path";
+import { mkdir as mkdir6 } from "fs/promises";
+import path10 from "path";
 var sparseQueryEncoderFactory = null;
 var sparseDocumentBuilderFactory = null;
 function buildSparseQueryVector(tokenIds, tokenWeights) {
@@ -854,7 +976,6 @@ async function createSparseQueryEncoder(cacheDir, modelId, queryTokenWeights) {
   return async (text) => {
     const features = await tokenizer([text], {
       truncation: true,
-      return_attention_mask: false,
       return_token_type_ids: false
     });
     return buildSparseQueryVector(normalizeTokenIds(features.input_ids), queryTokenWeights);
@@ -863,7 +984,7 @@ async function createSparseQueryEncoder(cacheDir, modelId, queryTokenWeights) {
 async function pullSparseModel(workspacePath, config) {
   await ensureUvAvailable();
   const cacheDir = resolveCacheDir(workspacePath, config.cacheDir);
-  await mkdir5(cacheDir, { recursive: true });
+  await mkdir6(cacheDir, { recursive: true });
   await runSparsePython({
     workspacePath,
     config,
@@ -914,7 +1035,7 @@ async function buildSparseVectors({
   config,
   progress
 }) {
-  const chunks = await readJsonl(path9.join(workspacePath, "chunks", "chunks.jsonl"));
+  const chunks = await readJsonl(path10.join(workspacePath, "chunks", "chunks.jsonl"));
   reportProgress(progress, `Encoding ${chunks.length} chunk${chunks.length === 1 ? "" : "s"} for sparse retrieval`);
   const built = await buildSparseDocuments(workspacePath, config, chunks);
   reportProgress(progress, "Building sparse vector index");
@@ -1047,31 +1168,31 @@ async function getModelStatus(workspacePath, config) {
 }
 
 // src/index/index-store.ts
-import { mkdir as mkdir6, rm as rm3 } from "fs/promises";
-import path10 from "path";
+import { mkdir as mkdir7, rm as rm4 } from "fs/promises";
+import path11 from "path";
 function versionedIndexPath(workspacePath, stamp) {
-  return path10.join(workspacePath, "indexes", `${stamp}.json.gz`);
+  return path11.join(workspacePath, "indexes", `${stamp}.json.gz`);
 }
 function versionedLegacyIndexPath(workspacePath, stamp) {
-  return path10.join(workspacePath, "indexes", `${stamp}.json`);
+  return path11.join(workspacePath, "indexes", `${stamp}.json`);
 }
 function versionedMetaPath(workspacePath, stamp) {
-  return path10.join(workspacePath, "indexes", `${stamp}.meta.json.gz`);
+  return path11.join(workspacePath, "indexes", `${stamp}.meta.json.gz`);
 }
 function versionedLegacyMetaPath(workspacePath, stamp) {
-  return path10.join(workspacePath, "indexes", `${stamp}.meta.json`);
+  return path11.join(workspacePath, "indexes", `${stamp}.meta.json`);
 }
 function latestIndexPath(workspacePath) {
-  return path10.join(workspacePath, "indexes", "latest.json.gz");
+  return path11.join(workspacePath, "indexes", "latest.json.gz");
 }
 function legacyLatestIndexPath(workspacePath) {
-  return path10.join(workspacePath, "indexes", "latest.json");
+  return path11.join(workspacePath, "indexes", "latest.json");
 }
 function latestMetaPath(workspacePath) {
-  return path10.join(workspacePath, "indexes", "latest.meta.json.gz");
+  return path11.join(workspacePath, "indexes", "latest.meta.json.gz");
 }
 function legacyLatestMetaPath(workspacePath) {
-  return path10.join(workspacePath, "indexes", "latest.meta.json");
+  return path11.join(workspacePath, "indexes", "latest.meta.json");
 }
 async function writeIndexArtifacts({
   workspacePath,
@@ -1083,16 +1204,16 @@ async function writeIndexArtifacts({
   const metaPath = versionedMetaPath(workspacePath, stamp);
   const latestIndexArtifactPath = latestIndexPath(workspacePath);
   const latestMetadataArtifactPath = latestMetaPath(workspacePath);
-  await mkdir6(path10.join(workspacePath, "indexes"), { recursive: true });
+  await mkdir7(path11.join(workspacePath, "indexes"), { recursive: true });
   await writeGzipJson(indexPath, indexState);
   await writeGzipJson(metaPath, metadata);
   await writeGzipJson(latestIndexArtifactPath, indexState);
   await writeGzipJson(latestMetadataArtifactPath, metadata);
   await Promise.all([
-    rm3(legacyLatestIndexPath(workspacePath), { force: true }),
-    rm3(legacyLatestMetaPath(workspacePath), { force: true }),
-    rm3(versionedLegacyIndexPath(workspacePath, stamp), { force: true }),
-    rm3(versionedLegacyMetaPath(workspacePath, stamp), { force: true })
+    rm4(legacyLatestIndexPath(workspacePath), { force: true }),
+    rm4(legacyLatestMetaPath(workspacePath), { force: true }),
+    rm4(versionedLegacyIndexPath(workspacePath, stamp), { force: true }),
+    rm4(versionedLegacyMetaPath(workspacePath, stamp), { force: true })
   ]);
   return { indexPath: latestIndexArtifactPath, metadataPath: latestMetadataArtifactPath };
 }
@@ -1157,9 +1278,9 @@ async function buildIndex({
 }) {
   const config = await loadConfig(workspacePath);
   reportProgress(progress, "Loading documents, chunks, and sources");
-  const chunks = await readJsonl(path11.join(workspacePath, "chunks", "chunks.jsonl"));
-  const documents = await readJsonl(path11.join(workspacePath, "documents", "documents.jsonl"));
-  const sources = await readJsonl(path11.join(workspacePath, "sources", "sources.jsonl"));
+  const chunks = await readJsonl(path12.join(workspacePath, "chunks", "chunks.jsonl"));
+  const documents = await readJsonl(path12.join(workspacePath, "documents", "documents.jsonl"));
+  const sources = await readJsonl(path12.join(workspacePath, "sources", "sources.jsonl"));
   const metadataFields = [...new Set(chunks.flatMap((chunk) => Object.keys(chunk.metadata).map((key) => `metadata.${key}`)))];
   const index = new DocumentIndex(createIndexMapping(metadataFields));
   const documentsById = new Map(documents.map((document) => [document.id, document]));
@@ -1238,7 +1359,7 @@ async function buildIndex({
 }
 
 // src/ingest/ingest-service.ts
-import path17 from "path";
+import path18 from "path";
 
 // src/core/concurrency.ts
 async function mapWithConcurrency(items, limit, worker) {
@@ -1262,17 +1383,17 @@ async function mapWithConcurrency(items, limit, worker) {
 }
 
 // src/core/runs.ts
-import path12 from "path";
+import path13 from "path";
 async function writeRun(workspacePath, run) {
-  await writeJsonl(path12.join(workspacePath, "runs", `${run.id}.json`), [run]);
+  await writeJsonl(path13.join(workspacePath, "runs", `${run.id}.json`), [run]);
 }
 async function listRuns(workspacePath) {
   const fs = await import("fs/promises");
-  const dir = path12.join(workspacePath, "runs");
+  const dir = path13.join(workspacePath, "runs");
   try {
     const entries = await fs.readdir(dir);
     const records = await Promise.all(entries.filter((name) => name.endsWith(".json")).map(async (name) => {
-      const runs = await readJsonl(path12.join(dir, name));
+      const runs = await readJsonl(path13.join(dir, name));
       return runs[0];
     }));
     return records.filter((record) => record != null).sort((a, b) => a.createdAt.localeCompare(b.createdAt));
@@ -1282,8 +1403,8 @@ async function listRuns(workspacePath) {
 }
 
 // src/sources/source-store.ts
-import path13 from "path";
-var sourcesFile = (workspacePath) => path13.join(workspacePath, "sources", "sources.jsonl");
+import path14 from "path";
+var sourcesFile = (workspacePath) => path14.join(workspacePath, "sources", "sources.jsonl");
 async function listSources(workspacePath) {
   return readJsonl(sourcesFile(workspacePath));
 }
@@ -1329,8 +1450,8 @@ async function removeSource(workspacePath, sourceId) {
 }
 
 // src/ingest/document-utils.ts
-import { mkdir as mkdir7, rm as rm4, writeFile as writeFile6 } from "fs/promises";
-import path14 from "path";
+import { mkdir as mkdir8, rm as rm5, writeFile as writeFile7 } from "fs/promises";
+import path15 from "path";
 
 // src/normalize/normalize-markdown.ts
 import matter2 from "gray-matter";
@@ -1382,8 +1503,8 @@ async function writeNormalizedDocument({
   normalizedPath,
   markdown
 }) {
-  await mkdir7(path14.dirname(normalizedPath), { recursive: true });
-  await writeFile6(
+  await mkdir8(path15.dirname(normalizedPath), { recursive: true });
+  await writeFile7(
     normalizedPath,
     withFrontmatter(
       {
@@ -1405,14 +1526,14 @@ async function writeNormalizedDocument({
 }
 async function deleteDocumentArtifacts(document) {
   await Promise.all([
-    document.rawPath ? rm4(document.rawPath, { force: true }) : Promise.resolve(),
-    rm4(document.normalizedPath, { force: true })
+    document.rawPath ? rm5(document.rawPath, { force: true }) : Promise.resolve(),
+    rm5(document.normalizedPath, { force: true })
   ]);
 }
 
 // src/ingest/adapters/directory-adapter.ts
 import fg from "fast-glob";
-import path15 from "path";
+import path16 from "path";
 async function listDirectoryFiles(source) {
   const include = source.crawl?.includePatterns?.length ? source.crawl.includePatterns : ["**/*.md", "**/*.txt", "**/*.html", "**/*.htm", "**/*.pdf", "**/*.docx"];
   const exclude = source.crawl?.excludePatterns ?? [];
@@ -1425,12 +1546,12 @@ async function listDirectoryFiles(source) {
     ignore: exclude,
     followSymbolicLinks: false
   });
-  return matches.map((match) => path15.resolve(match)).sort();
+  return matches.map((match) => path16.resolve(match)).sort();
 }
 
 // src/ingest/adapters/file-adapter.ts
 import { basename, extname, resolve } from "path";
-import { mkdir as mkdir8, readFile as readFile8, stat as stat3, writeFile as writeFile7 } from "fs/promises";
+import { mkdir as mkdir9, readFile as readFile9, stat as stat4, writeFile as writeFile8 } from "fs/promises";
 
 // src/ingest/extractors/docx-extractor.ts
 import mammoth from "mammoth";
@@ -1604,16 +1725,16 @@ function extractPublicationDateFromHtml(html) {
 }
 
 // src/ingest/extractors/markdown-extractor.ts
-import { readFile as readFile5 } from "fs/promises";
+import { readFile as readFile6 } from "fs/promises";
 async function extractMarkdown(filePath) {
-  return readFile5(filePath, "utf8");
+  return readFile6(filePath, "utf8");
 }
 
 // src/ingest/extractors/pdf-extractor.ts
-import { readFile as readFile6 } from "fs/promises";
+import { readFile as readFile7 } from "fs/promises";
 import { PDFParse } from "pdf-parse";
 async function extractPdf(filePath) {
-  const buffer = await readFile6(filePath);
+  const buffer = await readFile7(filePath);
   const parser = new PDFParse({ data: buffer });
   try {
     const parsed = await parser.getText();
@@ -1624,9 +1745,9 @@ async function extractPdf(filePath) {
 }
 
 // src/ingest/extractors/text-extractor.ts
-import { readFile as readFile7 } from "fs/promises";
+import { readFile as readFile8 } from "fs/promises";
 async function extractText(filePath) {
-  return readFile7(filePath, "utf8");
+  return readFile8(filePath, "utf8");
 }
 
 // src/ingest/adapters/file-adapter.ts
@@ -1661,7 +1782,7 @@ async function extractFileContent(filePath, mimeType) {
 ${text}`, raw: text };
   }
   if (mimeType === "text/html") {
-    const raw = await readFile8(filePath, "utf8");
+    const raw = await readFile9(filePath, "utf8");
     const extracted = extractHtmlToMarkdown(raw);
     return { title: extracted.title, markdown: `# ${extracted.title}
 
@@ -1706,7 +1827,7 @@ async function ingestFile({
   previous
 }) {
   const resolved = resolve(filePath);
-  const fileStat = await stat3(resolved);
+  const fileStat = await stat4(resolved);
   const mimeType = mimeTypeFor(resolved);
   const extracted = await extractFileContent(resolved, mimeType);
   const documentId = stableId("doc", source.id, resolved);
@@ -1717,10 +1838,10 @@ async function ingestFile({
   const lastChangedAt = previous?.contentHash === contentHash ? previous.lastChangedAt : now;
   const indexedAt = now;
   const crawledAt = now;
-  await mkdir8(resolve(workspacePath, "normalized"), { recursive: true });
-  await mkdir8(resolve(workspacePath, "raw", source.id), { recursive: true });
+  await mkdir9(resolve(workspacePath, "normalized"), { recursive: true });
+  await mkdir9(resolve(workspacePath, "raw", source.id), { recursive: true });
   if (extracted.raw) {
-    await writeFile7(rawPath, extracted.raw, "utf8");
+    await writeFile8(rawPath, extracted.raw, "utf8");
   }
   await writeNormalizedDocument({
     documentId,
@@ -1783,7 +1904,7 @@ ${content}`;
   const now = (/* @__PURE__ */ new Date()).toISOString();
   const lastChangedAt = previous?.contentHash === contentHash ? previous.lastChangedAt : now;
   const indexedAt = now;
-  await mkdir8(resolve(workspacePath, "normalized"), { recursive: true });
+  await mkdir9(resolve(workspacePath, "normalized"), { recursive: true });
   await writeNormalizedDocument({
     documentId,
     sourceId: source.id,
@@ -1827,7 +1948,7 @@ async function reprocessStoredDocument(document, source) {
   if (!document.rawPath) {
     return null;
   }
-  const raw = await readFile8(document.rawPath, "utf8");
+  const raw = await readFile9(document.rawPath, "utf8");
   const fallbackTitle = document.title || basename(document.uri);
   const extracted = await extractRawContent(raw, document.mimeType, fallbackTitle);
   const contentHash = sha256(extracted.markdown);
@@ -1944,8 +2065,8 @@ async function parseRssFeedDocument(xml, source) {
 }
 
 // src/ingest/adapters/url-adapter.ts
-import { mkdir as mkdir9, readFile as readFile9, writeFile as writeFile8 } from "fs/promises";
-import path16 from "path";
+import { mkdir as mkdir10, readFile as readFile10, writeFile as writeFile9 } from "fs/promises";
+import path17 from "path";
 
 // src/core/urls.ts
 function normalizeRemoteUrl(uri) {
@@ -1988,16 +2109,16 @@ async function normalizeRemoteDocument({
 
 ${extracted.markdown}`;
   const documentId = stableId("doc", source.id, canonicalUri);
-  const normalizedPath = path16.resolve(workspacePath, "normalized", `${documentId}.md`);
-  const rawPath = path16.resolve(workspacePath, "raw", source.id, `${sha256(canonicalUri).slice(0, 12)}.html`);
+  const normalizedPath = path17.resolve(workspacePath, "normalized", `${documentId}.md`);
+  const rawPath = path17.resolve(workspacePath, "raw", source.id, `${sha256(canonicalUri).slice(0, 12)}.html`);
   const contentHash = sha256(markdown);
   const now = (/* @__PURE__ */ new Date()).toISOString();
   const lastChangedAt = previous?.contentHash === contentHash ? previous.lastChangedAt : now;
   const indexedAt = now;
   const crawledAt = now;
   const resolvedPublicationDate = choosePublicationDate(publicationDate, extractPublicationDateFromHtml(body), previous?.publicationDate);
-  await mkdir9(path16.resolve(workspacePath, "raw", source.id), { recursive: true });
-  await writeFile8(rawPath, body, "utf8");
+  await mkdir10(path17.resolve(workspacePath, "raw", source.id), { recursive: true });
+  await writeFile9(rawPath, body, "utf8");
   await writeNormalizedDocument({
     documentId,
     sourceId: source.id,
@@ -2052,7 +2173,7 @@ async function fetchUrlDocument({
   publicationDate
 }) {
   const headers = {
-    "user-agent": source.crawl?.userAgent ?? "querylight-cli/0.1"
+    "user-agent": source.crawl?.userAgent ?? "querylight-cli"
   };
   if (previous?.httpCache?.etag) {
     headers["if-none-match"] = previous.httpCache.etag;
@@ -2117,7 +2238,7 @@ async function reprocessRemoteDocument(document, source) {
   if (!document.rawPath || !await fileExists(document.rawPath)) {
     return null;
   }
-  const raw = await readFile9(document.rawPath, "utf8");
+  const raw = await readFile10(document.rawPath, "utf8");
   const extracted = extractHtmlToMarkdown(raw);
   const markdown = `# ${extracted.title}
 
@@ -2296,7 +2417,7 @@ async function crawlWebsite(source, defaults, progress) {
 
 // src/ingest/ingest-service.ts
 function documentsFile(workspacePath) {
-  return path17.join(workspacePath, "documents", "documents.jsonl");
+  return path18.join(workspacePath, "documents", "documents.jsonl");
 }
 async function loadDocuments(workspacePath) {
   return readJsonl(documentsFile(workspacePath));
@@ -2351,7 +2472,7 @@ async function purgeDocuments(workspacePath, documentIds, documents) {
 async function fetchFeedText(source) {
   const response2 = await fetch(source.uri, {
     headers: {
-      "user-agent": source.crawl?.userAgent ?? "querylight-cli/0.1"
+      "user-agent": source.crawl?.userAgent ?? "querylight-cli"
     }
   });
   if (!response2.ok) {
@@ -2839,9 +2960,9 @@ async function discoverWebsiteFeed(websiteUrl, userAgent) {
 }
 
 // src/query/search-service.ts
-import { readFile as readFile10 } from "fs/promises";
+import { readFile as readFile11 } from "fs/promises";
 import { reciprocalRankFusion, searchJsonDsl } from "@tryformation/querylight-ts";
-import path18 from "path";
+import path19 from "path";
 async function loadHydratedIndex(workspacePath) {
   let state;
   try {
@@ -3051,7 +3172,7 @@ async function buildSnippetWithAdjacentChunks(chunk, query, {
     if (!await fileExists(document.normalizedPath)) {
       return buildSnippet(chunk.text, query);
     }
-    const raw = await readFile10(document.normalizedPath, "utf8");
+    const raw = await readFile11(document.normalizedPath, "utf8");
     orderedChunks = buildChunksForDocument(document, raw, config);
     orderedChunkCache.set(document.id, orderedChunks);
   }
@@ -3386,9 +3507,9 @@ async function searchIndex({
   const config = await loadConfig(workspacePath);
   const mode = retrievalMode ?? config.retrieval.defaultMode;
   const candidateLimit = Math.max(topK * 5, 50);
-  const chunks = new Map((await readJsonl(path18.join(workspacePath, "chunks", "chunks.jsonl"))).map((chunk) => [chunk.id, chunk]));
-  const documents = new Map((await readJsonl(path18.join(workspacePath, "documents", "documents.jsonl"))).map((document) => [document.id, document]));
-  const sources = new Map((await readJsonl(path18.join(workspacePath, "sources", "sources.jsonl"))).map((source) => [source.id, source]));
+  const chunks = new Map((await readJsonl(path19.join(workspacePath, "chunks", "chunks.jsonl"))).map((chunk) => [chunk.id, chunk]));
+  const documents = new Map((await readJsonl(path19.join(workspacePath, "documents", "documents.jsonl"))).map((document) => [document.id, document]));
+  const sources = new Map((await readJsonl(path19.join(workspacePath, "sources", "sources.jsonl"))).map((source) => [source.id, source]));
   const orderedChunkCache = /* @__PURE__ */ new Map();
   const normalizedQuery = query.trim();
   const filterIds = [...chunks.values()].filter((chunk) => filterChunk(chunk, documents.get(chunk.documentId), sources.get(chunk.sourceId), { sourceId, sourceIds, sourceName, sourceNames, sourceType, sourceTypes, uriPrefix, uriPrefixes, hasPublicationDate, tag, tags, metadata, dateRanges })).map((chunk) => chunk.id);
@@ -3561,18 +3682,18 @@ async function searchIndex({
 
 // src/server/search-api.ts
 import { createServer } from "http";
-import { readdir, stat as stat4 } from "fs/promises";
-import path19 from "path";
+import { readdir as readdir2, stat as stat5 } from "fs/promises";
+import path20 from "path";
 async function pathIsDirectory(candidatePath) {
   try {
-    return (await stat4(candidatePath)).isDirectory();
+    return (await stat5(candidatePath)).isDirectory();
   } catch {
     return false;
   }
 }
 async function discoverKnowledgeBases(workspacePath) {
   try {
-    const singleWorkspace = await assertWorkspaceExists(workspacePath);
+    const singleWorkspace = (await resolveReadableWorkspace(workspacePath)).workspacePath;
     const config = await loadConfig(singleWorkspace);
     const index = await loadHydratedIndex(singleWorkspace);
     return {
@@ -3589,19 +3710,20 @@ async function discoverKnowledgeBases(workspacePath) {
       throw error;
     }
   }
-  const resolvedRoot = path19.resolve(workspacePath);
+  const resolvedRoot = path20.resolve(workspacePath);
   if (!await pathIsDirectory(resolvedRoot)) {
     throw new CliError(`workspace path does not exist: ${resolvedRoot}`, "WORKSPACE_ERROR", 3 /* WorkspaceError */);
   }
-  const entries = await readdir(resolvedRoot, { withFileTypes: true });
-  const knowledgeBases = (await Promise.all(entries.filter((entry) => entry.isDirectory()).map(async (entry) => {
-    const candidateWorkspace = path19.join(resolvedRoot, entry.name, ".kb");
+  const entries = await readdir2(resolvedRoot, { withFileTypes: true });
+  const knowledgeBases = (await Promise.all(entries.filter((entry) => entry.isDirectory() || entry.isFile() && isWorkspaceArchivePath(entry.name)).map(async (entry) => {
+    const candidateWorkspace = entry.isDirectory() ? path20.join(resolvedRoot, entry.name, ".kb") : path20.join(resolvedRoot, entry.name);
+    const knowledgeBaseName = entry.isDirectory() ? entry.name : entry.name.replace(/\.zip$/i, "");
     try {
-      const workspace = await assertWorkspaceExists(candidateWorkspace);
+      const workspace = entry.isDirectory() ? await assertWorkspaceExists(candidateWorkspace) : (await resolveReadableWorkspace(candidateWorkspace)).workspacePath;
       const config = await loadConfig(workspace);
       const index = await loadHydratedIndex(workspace);
       return {
-        name: entry.name,
+        name: knowledgeBaseName,
         workspacePath: workspace,
         configuredIndexName: config.index.name,
         index
@@ -3615,7 +3737,7 @@ async function discoverKnowledgeBases(workspacePath) {
   }))).filter((knowledgeBase) => knowledgeBase != null);
   if (knowledgeBases.length === 0) {
     throw new CliError(
-      `no knowledge bases found at ${resolvedRoot}; use a .kb workspace or a directory of named subdirectories that each contain .kb`,
+      `no knowledge bases found at ${resolvedRoot}; use a .kb workspace, a .zip workspace, or a directory of .zip files or named subdirectories that each contain .kb`,
       "WORKSPACE_ERROR",
       3 /* WorkspaceError */
     );
@@ -3749,7 +3871,7 @@ async function startSearchApiServer({
 }
 
 // src/query/related-service.ts
-import path20 from "path";
+import path21 from "path";
 function cosineSimilarity2(left, right) {
   let dot = 0;
   let leftNorm = 0;
@@ -3825,7 +3947,7 @@ async function findRelatedDocuments({
   if (!await fileExists(denseVectorPath(workspacePath))) {
     throw new CliError("dense vector index is not built; run `qli models pull --dense` and `qli rebuild`", "DENSE_INDEX_MISSING", 7 /* QueryError */);
   }
-  const documents = await readJsonl(path20.join(workspacePath, "documents", "documents.jsonl"));
+  const documents = await readJsonl(path21.join(workspacePath, "documents", "documents.jsonl"));
   const selected = resolveDocumentSelector(documents, document);
   const densePayload = await readDensePayload(workspacePath);
   const vectors = buildDocumentVectors(documents, densePayload.chunks, densePayload.metadata.dimensions);
@@ -3898,7 +4020,7 @@ async function createContext({
 }
 
 // src/report/diff-service.ts
-import path21 from "path";
+import path22 from "path";
 function chooseBaselineRun(runs, since) {
   if (since === "last-run") {
     return runs.at(-1);
@@ -3914,7 +4036,7 @@ async function diffWorkspace({
   documentId,
   since
 }) {
-  const current = await readJsonl(path21.join(workspacePath, "documents", "documents.jsonl"));
+  const current = await readJsonl(path22.join(workspacePath, "documents", "documents.jsonl"));
   const baseline = chooseBaselineRun(await listRuns(workspacePath), since);
   const previous = new Map((baseline?.documentsSnapshot ?? []).map((document) => [document.id, document]));
   const changedDocuments = current.filter((document) => (!sourceId || document.sourceId === sourceId) && (!documentId || document.id === documentId)).filter((document) => {
@@ -4273,7 +4395,7 @@ function parseDateValue(input, optionName) {
   return parsed.toISOString();
 }
 async function parseJsonArgument(input) {
-  const raw = input.startsWith("@") ? await readFile11(path22.resolve(input.slice(1)), "utf8") : input;
+  const raw = input.startsWith("@") ? await readFile12(path23.resolve(input.slice(1)), "utf8") : input;
   try {
     const parsed = JSON.parse(raw);
     if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
@@ -4316,20 +4438,35 @@ function searchDateRanges(options) {
   }
   return entries;
 }
-async function resolveWorkspace(options) {
-  return path22.resolve(options.workspace ?? DEFAULT_WORKSPACE);
+function resolveSearchTopK(optionsTopK, sourceTypes, dateRanges, defaultTopK) {
+  const explicitTopK = parseOptionalPositiveInteger(optionsTopK, "--top-k");
+  if (explicitTopK !== void 0) {
+    return explicitTopK;
+  }
+  const includesRss = (sourceTypes ?? []).includes("rss");
+  if (includesRss && dateRanges.length > 0) {
+    return 500;
+  }
+  return defaultTopK;
+}
+async function resolveWorkspace(options, mode = {}) {
+  const workspace = options.workspace ?? DEFAULT_WORKSPACE;
+  if (mode.writable) {
+    return assertWritableWorkspacePath(workspace);
+  }
+  return (await resolveReadableWorkspace(workspace)).workspacePath;
 }
 function workspaceFromArgv(argv) {
   const index = argv.findIndex((arg) => arg === "--workspace");
   if (index >= 0 && argv[index + 1]) {
-    return path22.resolve(argv[index + 1]);
+    return path23.resolve(argv[index + 1]);
   }
-  return path22.resolve(DEFAULT_WORKSPACE);
+  return path23.resolve(DEFAULT_WORKSPACE);
 }
 async function runCli(argv, io = {}) {
   const capture = { stdout: [], stderr: [], ...io };
   const program = new Command();
-  program.name("qli").description("Build and query a local Querylight workspace from files, directories, URLs, websites, and feeds.").showHelpAfterError().option("--workspace <path>", "Workspace directory. Defaults to .kb in the current directory.", DEFAULT_WORKSPACE).option("--config <path>", "Optional config file override. Useful for testing alternate retrieval settings.").option("--json", "Return a stable JSON envelope for automation and agents.").option("--silent", "Suppress progress logging for long-running commands.").option("--verbose", "Print more operational detail when a command supports it.").addOption(new Option("--quiet", "Deprecated alias for --silent.").hideHelp());
+  program.name("qli").description("Build and query a local Querylight workspace from files, directories, URLs, websites, and feeds.").showHelpAfterError().option("--workspace <path>", "Workspace directory, or a packaged .zip workspace for read-only commands. Defaults to .kb in the current directory.", DEFAULT_WORKSPACE).option("--config <path>", "Optional config file override. Useful for testing alternate retrieval settings.").option("--json", "Return a stable JSON envelope for automation and agents.").option("--silent", "Suppress progress logging for long-running commands.").option("--verbose", "Print more operational detail when a command supports it.").addOption(new Option("--quiet", "Deprecated alias for --silent.").hideHelp());
   program.addHelpText("after", `
 Workflow:
   1. Initialize a workspace with qli init
@@ -4341,12 +4478,15 @@ Examples:
   qli init
   qli source add directory ./docs --name "Product Docs" --tag docs
   qli ingest
+  qli package ./docs-kb.zip
   qli rebuild --silent
   qli search "api authentication" --top-k 8
+  qli search --workspace ./docs-kb.zip "api authentication"
   qli context "How do API keys work?" --top-k 8 --max-chars 8000
 
 Long-running commands print progress to stderr by default. Use --silent to suppress it.
 Use --json when another tool needs stable structured output.
+Read-only commands can use --workspace with a packaged .zip workspace.
 
 Use qli <command> --help for command-specific options and examples.`);
   program.command("init").description("Create a new workspace with the default directory layout and config, then pull missing retrieval models.").option("--force").addHelpText("after", `
@@ -4360,7 +4500,7 @@ Notes:
   init pulls missing model assets for enabled retrieval modes.
   Sparse model downloads require uv. If uv is not available, init skips the sparse pull.`).action(async function command(options) {
     const global = this.optsWithGlobals();
-    const workspace = await resolveWorkspace({ workspace: this.optsWithGlobals().workspace });
+    const workspace = await resolveWorkspace({ workspace: this.optsWithGlobals().workspace }, { writable: true });
     const result = await ensureWorkspace({ workspacePath: workspace, force: Boolean(options.force) });
     const config = await loadConfig(workspace, global.config);
     const status = await getModelStatus(workspace, config);
@@ -4401,7 +4541,7 @@ Notes:
     }
     validateSourceAddOptions(type, options);
     const global = this.optsWithGlobals();
-    const workspace = await resolveWorkspace({ workspace: global.workspace });
+    const workspace = await resolveWorkspace({ workspace: global.workspace }, { writable: true });
     const config = await loadConfig(workspace, global.config);
     const now = (/* @__PURE__ */ new Date()).toISOString();
     const initialCrawl = createSourceCrawlConfig(type, options, { retentionDays: config.crawler.retentionDays });
@@ -4418,7 +4558,7 @@ Notes:
     }
     const stored = await addSource(workspace, {
       type,
-      uri: ["file", "directory"].includes(type) ? path22.resolve(uri) : uri,
+      uri: ["file", "directory"].includes(type) ? path23.resolve(uri) : uri,
       name: options.name,
       enabled: true,
       tags: options.tag ?? [],
@@ -4479,7 +4619,7 @@ Notes:
   qli only exposes settings that the current source type uses at runtime.
   URI, source type, and source id do not change here.`).action(async function command(sourceId, options) {
     const global = this.optsWithGlobals();
-    const workspace = await resolveWorkspace({ workspace: global.workspace });
+    const workspace = await resolveWorkspace({ workspace: global.workspace }, { writable: true });
     const sources = await listSources(workspace);
     const current = sources.find((source2) => source2.id === sourceId);
     if (!current) {
@@ -4507,7 +4647,7 @@ Examples:
   qli source remove src_123
   qli source list --json`).action(async function command(sourceId) {
     const global = this.optsWithGlobals();
-    const workspace = await resolveWorkspace({ workspace: global.workspace });
+    const workspace = await resolveWorkspace({ workspace: global.workspace }, { writable: true });
     await removeSource(workspace, sourceId);
     emit(global.json, capture, response("source remove", workspace, { sourceId }), `Removed source ${sourceId}`);
   });
@@ -4516,7 +4656,7 @@ Examples:
   qli source disable src_123
   qli source enable src_123`).action(async function command(sourceId) {
     const global = this.optsWithGlobals();
-    const workspace = await resolveWorkspace({ workspace: global.workspace });
+    const workspace = await resolveWorkspace({ workspace: global.workspace }, { writable: true });
     const updated = await updateSource(workspace, sourceId, { enabled: false, updatedAt: (/* @__PURE__ */ new Date()).toISOString() });
     emit(global.json, capture, response("source disable", workspace, updated), `Disabled source ${sourceId}`);
   });
@@ -4525,7 +4665,7 @@ Examples:
   qli source enable src_123
   qli source list`).action(async function command(sourceId) {
     const global = this.optsWithGlobals();
-    const workspace = await resolveWorkspace({ workspace: global.workspace });
+    const workspace = await resolveWorkspace({ workspace: global.workspace }, { writable: true });
     const updated = await updateSource(workspace, sourceId, { enabled: true, updatedAt: (/* @__PURE__ */ new Date()).toISOString() });
     emit(global.json, capture, response("source enable", workspace, updated), `Enabled source ${sourceId}`);
   });
@@ -4537,7 +4677,7 @@ Examples:
   qli ingest --dense --sparse
   qli ingest --silent`).action(async function command(options) {
     const global = this.optsWithGlobals();
-    const workspace = await resolveWorkspace({ workspace: global.workspace });
+    const workspace = await resolveWorkspace({ workspace: global.workspace }, { writable: true });
     const result = await runIngestCommand({
       workspace,
       sourceId: options.source,
@@ -4555,7 +4695,7 @@ Examples:
   qli chunk --document doc_123
   qli chunk --silent`).action(async function command(options) {
     const global = this.optsWithGlobals();
-    const workspace = await resolveWorkspace({ workspace: global.workspace });
+    const workspace = await resolveWorkspace({ workspace: global.workspace }, { writable: true });
     const result = await chunkDocuments({
       workspacePath: workspace,
       sourceId: options.source,
@@ -4571,7 +4711,7 @@ Examples:
   qli reprocess --document doc_123
   qli reprocess --silent`).action(async function command(options) {
     const global = this.optsWithGlobals();
-    const workspace = await resolveWorkspace({ workspace: global.workspace });
+    const workspace = await resolveWorkspace({ workspace: global.workspace }, { writable: true });
     const result = await reprocessDocuments({
       workspacePath: workspace,
       sourceId: options.source,
@@ -4589,7 +4729,7 @@ Examples:
   qli index build --dense --sparse
   qli index build --silent`).action(async function command(options) {
     const global = this.optsWithGlobals();
-    const workspace = await resolveWorkspace({ workspace: global.workspace });
+    const workspace = await resolveWorkspace({ workspace: global.workspace }, { writable: true });
     const result = await buildIndex({
       workspacePath: workspace,
       denseOverride: options.dense ? true : void 0,
@@ -4606,7 +4746,7 @@ Examples:
   qli rebuild --dense --sparse
   qli rebuild --silent`).action(async function command(options) {
     const global = this.optsWithGlobals();
-    const workspace = await resolveWorkspace({ workspace: global.workspace });
+    const workspace = await resolveWorkspace({ workspace: global.workspace }, { writable: true });
     const progress = createProgressHandler(capture, global);
     progress?.("info", "Rebuild step 1/3: ingest");
     const ingest = await ingestSources({
@@ -4629,7 +4769,26 @@ Examples:
     progress?.("info", "Rebuild complete");
     emit(global.json, capture, response("rebuild", workspace, data), `Processed ${ingest.processedSources} sources, wrote ${chunk.chunksWritten} chunks`);
   });
-  program.command("search").description("Search the built index and return ranked matching documents or chunks. Use search-json for raw JSON DSL queries.").argument("[query]", "Text query. Omit it to list the latest matching documents.").option("--top-k <n>", "Maximum number of results to return.", "12").option("--source <sourceIds>", "Restrict results to one or more source ids. Use comma-separated values.").option("--source-name <names>", "Restrict results to one or more source names. Use comma-separated values.").option("--source-type <types>", `Restrict results to one or more source types. Use comma-separated values: ${SOURCE_TYPE_LIST.join(", ")}`).option("--uri-prefix <prefixes>", "Restrict results to one or more URI prefixes. Use comma-separated values.").option("--tag <tags>", "Restrict results to one or more source tags. Use comma-separated values.").option("--metadata <key=value...>", "Restrict results to sources with matching metadata.").option("--since <date>", "Shortcut for --publication-date-from.").option("--until <date>", "Shortcut for --publication-date-to.").option("--changed-since <date>", "Only include documents changed on or after this date.").option("--has-publication-date", "Only include documents with a publication date.").option("--publication-date-from <date>", "Only include documents published on or after this date.").option("--publication-date-to <date>", "Only include documents published on or before this date.").option("--first-seen-at-from <date>", "Only include documents first seen on or after this date.").option("--first-seen-at-to <date>", "Only include documents first seen on or before this date.").option("--last-seen-at-from <date>", "Only include documents last seen on or after this date.").option("--last-seen-at-to <date>", "Only include documents last seen on or before this date.").option("--last-changed-at-from <date>", "Only include documents changed on or after this date.").option("--last-changed-at-to <date>", "Only include documents changed on or before this date.").option("--crawled-at-from <date>", "Only include documents crawled on or after this date.").option("--crawled-at-to <date>", "Only include documents crawled on or before this date.").option("--retrieval <mode>", `Retrieval mode: ${RETRIEVAL_MODE_LIST.join(", ")}`).option("--show-chunks", "Return chunk-level matches when available.").addHelpText("after", `
+  program.command("package").description("Write the current workspace to a zip archive that read-only commands can use directly.").argument("<archive>", "Output .zip file.").option("--force", "Replace the output archive if it already exists.").addHelpText("after", `
+Examples:
+  qli package ./docs-kb.zip
+  qli package ./deploy/docs-kb.zip --workspace ./docs/.kb
+  qli package ./docs-kb.zip --force --json
+
+Notes:
+  The archive stores the workspace contents at the zip root.
+  Use the zip with read-only commands such as search, search-json, related, context, status, doctor, and serve.
+  Rebuild the directory workspace and package it again when source content changes.`).action(async function command(archive, options) {
+    const global = this.optsWithGlobals();
+    const workspace = await resolveWorkspace({ workspace: global.workspace }, { writable: true });
+    const result = await packageWorkspaceArchive({
+      workspacePath: workspace,
+      outputPath: archive,
+      force: Boolean(options.force)
+    });
+    emit(global.json, capture, response("package", workspace, result), `Packaged ${result.fileCount} files to ${result.archivePath}`);
+  });
+  program.command("search").description("Search the built index and return ranked matching documents or chunks. Use search-json for raw JSON DSL queries.").argument("[query]", "Text query. Omit it to list the latest matching documents.").option("--top-k <n>", "Maximum number of results to return. Defaults to search.defaultTopK in config.yaml. RSS searches with a time window use 500 when omitted.").option("--source <sourceIds>", "Restrict results to one or more source ids. Use comma-separated values.").option("--source-name <names>", "Restrict results to one or more source names. Use comma-separated values.").option("--source-type <types>", `Restrict results to one or more source types. Use comma-separated values: ${SOURCE_TYPE_LIST.join(", ")}`).option("--uri-prefix <prefixes>", "Restrict results to one or more URI prefixes. Use comma-separated values.").option("--tag <tags>", "Restrict results to one or more source tags. Use comma-separated values.").option("--metadata <key=value...>", "Restrict results to sources with matching metadata.").option("--since <date>", "Shortcut for --publication-date-from.").option("--until <date>", "Shortcut for --publication-date-to.").option("--changed-since <date>", "Only include documents changed on or after this date.").option("--has-publication-date", "Only include documents with a publication date.").option("--publication-date-from <date>", "Only include documents published on or after this date.").option("--publication-date-to <date>", "Only include documents published on or before this date.").option("--first-seen-at-from <date>", "Only include documents first seen on or after this date.").option("--first-seen-at-to <date>", "Only include documents first seen on or before this date.").option("--last-seen-at-from <date>", "Only include documents last seen on or after this date.").option("--last-seen-at-to <date>", "Only include documents last seen on or before this date.").option("--last-changed-at-from <date>", "Only include documents changed on or after this date.").option("--last-changed-at-to <date>", "Only include documents changed on or before this date.").option("--crawled-at-from <date>", "Only include documents crawled on or after this date.").option("--crawled-at-to <date>", "Only include documents crawled on or before this date.").option("--retrieval <mode>", `Retrieval mode: ${RETRIEVAL_MODE_LIST.join(", ")}`).option("--show-chunks", "Return chunk-level matches when available.").addHelpText("after", `
 Examples:
   qli search "pricing api limits"
   qli search "authentication" --top-k 20 --tag docs
@@ -4637,27 +4796,33 @@ Examples:
   qli search --source-name "Release Feed,Company Blog" --uri-prefix https://example.com/news,https://example.com/blog
   qli search "billing" --metadata team=support
   qli search "embedding model" --retrieval hybrid --show-chunks
+  qli search --workspace ./docs-kb.zip "authentication"
   qli search --source-type rss,page --top-k 25 --json
 
 Notes:
   lexical works without vector models.
   dense, sparse, and hybrid require the relevant index artifacts to exist.
+  When you omit --top-k, qli uses search.defaultTopK from config.yaml. The default workspace value is 50.
+  RSS searches with a time window default to 500 results when you omit --top-k.
   Use search-json when you want the raw Querylight 0.11 JSON DSL and hit format.
   When you omit the query, qli returns the latest matching documents sorted by publication date.`).action(async function command(query, options) {
     const global = this.optsWithGlobals();
     const workspace = await resolveWorkspace({ workspace: global.workspace });
+    const config = await loadConfig(workspace, global.config);
+    const sourceTypes = parseSourceTypes(options.sourceType);
+    const dateRanges = searchDateRanges(options);
     const result = await searchIndex({
       workspacePath: workspace,
       query: query ?? "",
-      topK: Number(options.topK),
+      topK: resolveSearchTopK(options.topK, sourceTypes, dateRanges, config.search.defaultTopK),
       sourceIds: parseCommaSeparatedList(options.source),
       sourceNames: parseCommaSeparatedList(options.sourceName),
-      sourceTypes: parseSourceTypes(options.sourceType),
+      sourceTypes,
       uriPrefixes: parseCommaSeparatedList(options.uriPrefix),
       hasPublicationDate: Boolean(options.hasPublicationDate),
       tags: parseCommaSeparatedList(options.tag),
       metadata: (options.metadata ?? []).map(parseKeyValue).map(([key, value]) => ({ key, value })),
-      dateRanges: searchDateRanges(options),
+      dateRanges,
       retrievalMode: parseRetrievalMode(options.retrieval),
       showChunks: Boolean(options.showChunks)
     });
@@ -4686,6 +4851,7 @@ Notes:
 Examples:
   qli serve
   qli serve --workspace ./docs/.kb --port 4000
+  qli serve --workspace ./docs-kb.zip --port 4000
   qli serve --workspace ./kbs --host 0.0.0.0 --port 4000
 
 Routes:
@@ -4696,10 +4862,10 @@ Routes:
 Notes:
   The request body must be a Querylight JSON DSL object.
   serve only exposes lexical _search for now.
-  When --workspace points to a directory of knowledge bases, each child directory must contain its own .kb workspace.
+  When --workspace points to a directory of knowledge bases, qli serves child .zip files and child directories that contain .kb.
   Index files are loaded once at startup and reused across requests.`).action(async function command(options) {
     const global = this.optsWithGlobals();
-    const workspace = await resolveWorkspace({ workspace: global.workspace });
+    const workspace = path23.resolve(global.workspace ?? DEFAULT_WORKSPACE);
     const port = Number(options.port);
     if (!Number.isInteger(port) || port < 0 || port > 65535) {
       throw new CliError(`invalid port: ${options.port}`, "INVALID_ARGUMENT", 2 /* InvalidArguments */);
@@ -4776,7 +4942,7 @@ Use --json when another tool needs structured access to the raw passages and met
   });
   const models = program.command("models");
   models.description("Inspect and download retrieval model assets.");
-  models.command("pull").description("Download dense and or sparse retrieval assets required by vector search.").option("--dense", "Only pull dense retrieval assets.").option("--sparse", "Only pull sparse retrieval assets.").addHelpText("after", `
+  models.command("pull").description("Download dense or sparse retrieval assets required by vector search.").option("--dense", "Only pull dense retrieval assets.").option("--sparse", "Only pull sparse retrieval assets.").addHelpText("after", `
 Examples:
   qli models pull
   qli models pull --dense
@@ -4786,7 +4952,7 @@ Examples:
 Pulled model assets are shared under ~/.qli by default.
 If you plan to use related, dense search, or hybrid retrieval, pull the models and rebuild the index first.`).action(async function command(options) {
     const global = this.optsWithGlobals();
-    const workspace = await resolveWorkspace({ workspace: global.workspace });
+    const workspace = await resolveWorkspace({ workspace: global.workspace }, { writable: true });
     const config = await loadConfig(workspace, global.config);
     const status = await getModelStatus(workspace, config);
     const { pullDense, pullSparse } = resolveModelPullPlan({
@@ -4862,7 +5028,7 @@ Examples:
     try {
       const meta = await readLatestIndexMetadata(workspace);
       latestIndex = meta.createdAt;
-      indexSize = (await stat5(await resolveLatestIndexArtifactPath(workspace))).size;
+      indexSize = (await stat6(await resolveLatestIndexArtifactPath(workspace))).size;
     } catch {
       latestIndex = void 0;
     }