@hraness/wordcell 0.21.3 → 0.22.0

package/dist/{index-0rfcqab6.js → index-4ag64rc1.js}

@@ -3,22 +3,28 @@ import {
   backfillSavedUrlMetadata,
   createRustMetadataSearchProvider
 } from "./index-bcknqxrq.js";
+import {
+  main as main2
+} from "./index-054mb7d3.js";
 import {
   MAX_AUTHORIZED_VAULTS,
   auditKnowledgePortfolio,
   loadPortfolioRegistry,
   openKnowledgePortfolio,
   snapshotPortfolioRegistry
-} from "./index-51bap0mq.js";
-import {
-  main as main2
-} from "./index-054mb7d3.js";
+} from "./index-avbce90h.js";
 import {
   diffCaptureBundle
 } from "./index-j4zgmzjr.js";
+import {
+  main
+} from "./index-de2w8crk.js";
 import {
   verifyCaptureBundle
 } from "./index-npg9z1a4.js";
+import {
+  redactSensitiveText
+} from "./index-mxxxytys.js";
 import {
   initVault
 } from "./index-23z4zxgg.js";
@@ -27,18 +33,22 @@ import {
   MAX_SOURCE_INBOX_RESULTS,
   sourceInbox
 } from "./index-pj501bh1.js";
+import {
+  createTypeSafeReranker
+} from "./index-9rf81m0p.js";
 import {
   knowledgeBaseEvaluationRetrieverIds,
   openKnowledgeBaseEvaluation
-} from "./index-pbr6rv47.js";
+} from "./index-e6p9e926.js";
 import {
   DEFAULT_SEARCH_RESULTS,
   MAX_SEARCH_CANDIDATES,
   MAX_SEARCH_NOTE_REFERENCE_BYTES,
   MAX_SEARCH_RELATED_SEEDS,
   MAX_SEARCH_RESULTS,
-  openKnowledgeBase
-} from "./index-vdw5yjfa.js";
+  openKnowledgeBase,
+  searchEvidenceRank
+} from "./index-2hf27mws.js";
 import {
   MAX_SEARCH_RULE_CONFIG_BYTES,
   parseSearchRules
@@ -49,22 +59,20 @@ import {
   recommendedEmbeddingModel,
   recommendedEmbeddingModelSha256,
   sha256EmbeddingModelFile
-} from "./index-115b07ap.js";
-import {
-  percolateWithGraph
-} from "./index-bgfzwt4h.js";
+} from "./index-hcw140eb.js";
 import {
-  queryGraph,
-  rebuildGraph,
-  verifyGraph
-} from "./index-bcfn9xah.js";
+  MAX_RERANK_CANDIDATES
+} from "./index-j70m75wd.js";
 import {
-  validateGraphQueryRequest
-} from "./index-11621h23.js";
+  MAX_EVALUATION_RESULTS_PER_QUERY,
+  MAX_EVALUATION_TIMEOUT_MS,
+  buildRetrievalEvaluationReport,
+  parseRetrievalEvaluationCorpus,
+  runRetrievalEvaluation
+} from "./index-b88v3vtm.js";
 import {
-  refreshVault,
-  scanVault
-} from "./index-0k2x4nn9.js";
+  percolateWithGraph
+} from "./index-t2bs9xdr.js";
 import {
   MAX_PERCOLATION_MENTIONS,
   MAX_PERCOLATION_MENTION_PAIRS,
@@ -73,26 +81,33 @@ import {
   percolateVault
 } from "./index-nd6nynv2.js";
 import {
-  MAX_EVALUATION_RESULTS_PER_QUERY,
-  MAX_EVALUATION_TIMEOUT_MS,
-  buildRetrievalEvaluationReport,
-  parseRetrievalEvaluationCorpus,
-  runRetrievalEvaluation
-} from "./index-b88v3vtm.js";
+  queryGraph,
+  rebuildGraph,
+  verifyGraph
+} from "./index-famy7fhs.js";
 import {
-  auditAgentGuideRepository
-} from "./index-hya40gb2.js";
+  validateGraphQueryRequest
+} from "./index-11621h23.js";
 import {
-  validateMarkdownAttachments
-} from "./index-x3fthpsc.js";
+  validateSearchQuery
+} from "./index-gm9t95d9.js";
 import {
-  addNoteRelation,
-  createNote,
-  removeNoteRelation
-} from "./index-6sw24nvv.js";
+  sanitizeTerminalLine,
+  sanitizeTerminalText
+} from "./index-1xxnjn0d.js";
 import {
-  validateSearchQuery
-} from "./index-why54q5p.js";
+  DEFAULT_PUBLISH_LIST_LIMIT,
+  MAX_PUBLISH_LIST_LIMIT,
+  publishVault,
+  renderPublishReportText
+} from "./index-0dqfnrz9.js";
+import {
+  refreshVault,
+  scanVault
+} from "./index-1tm7bgx7.js";
+import {
+  navigateLinks
+} from "./index-d13v9ckt.js";
 import {
   MAX_QUERY_FILTERS,
   MAX_QUERY_TAGS,
@@ -105,8 +120,11 @@ import {
   repositoryMemoryGroupKeys
 } from "./index-06c9ctr6.js";
 import {
-  navigateLinks
-} from "./index-d13v9ckt.js";
+  findKbPackageRoot
+} from "./index-4knsp9qj.js";
+import {
+  auditAgentGuideRepository
+} from "./index-hya40gb2.js";
 import {
   agentContextGuidePath,
   agentContextMarkerForScope,
@@ -116,24 +134,19 @@ import {
   inspectAgentContextRepository,
   normalizeRepositoryScope
 } from "./index-5vwpzb5a.js";
+import {
+  validateMarkdownAttachments
+} from "./index-x3fthpsc.js";
+import {
+  addNoteRelation,
+  createNote,
+  removeNoteRelation
+} from "./index-6sw24nvv.js";
 import {
   lookupNote,
   parseVaultKey,
   renderCatalog
 } from "./index-ekpwvbra.js";
-import {
-  main
-} from "./index-9zcpdbjg.js";
-import {
-  findKbPackageRoot
-} from "./index-jzcws0zn.js";
-import {
-  redactSensitiveText
-} from "./index-mxxxytys.js";
-import {
-  sanitizeTerminalLine,
-  sanitizeTerminalText
-} from "./index-1xxnjn0d.js";
 
 // src/clip/url-metadata-cli.ts
 import { resolve as resolve2 } from "path";
@@ -800,7 +813,7 @@ function terminalIntro(terminal) {
 }
 
 // src/cli-program.ts
-import { open } from "fs/promises";
+import { open as open2 } from "fs/promises";
 import { cpus, release, totalmem } from "os";
 import { relative, resolve as resolve3 } from "path";
 import { format } from "util";
@@ -905,13 +918,197 @@ Snapshot: ${value.revision}
   };
 }
 
+// src/serve.ts
+import { realpath, stat } from "fs/promises";
+import { join as join2, sep } from "path";
+var MAX_PATH_BYTES = 8 * 1024;
+var CONTENT_TYPES = Object.freeze({
+  ".avif": "image/avif",
+  ".css": "text/css; charset=utf-8",
+  ".gif": "image/gif",
+  ".html": "text/html; charset=utf-8",
+  ".ico": "image/x-icon",
+  ".jpeg": "image/jpeg",
+  ".jpg": "image/jpeg",
+  ".js": "text/javascript; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".map": "application/json; charset=utf-8",
+  ".mp3": "audio/mpeg",
+  ".mp4": "video/mp4",
+  ".pdf": "application/pdf",
+  ".png": "image/png",
+  ".svg": "image/svg+xml",
+  ".txt": "text/plain; charset=utf-8",
+  ".wasm": "application/wasm",
+  ".wav": "audio/wav",
+  ".webm": "video/webm",
+  ".webp": "image/webp",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".xml": "application/xml; charset=utf-8"
+});
+function contentType(path) {
+  const extension = path.slice(path.lastIndexOf("."));
+  return CONTENT_TYPES[extension] ?? "application/octet-stream";
+}
+async function regularFileUnder(rootReal, candidate) {
+  let resolved;
+  try {
+    resolved = await realpath(candidate);
+  } catch {
+    return null;
+  }
+  if (resolved !== rootReal && !resolved.startsWith(`${rootReal}${sep}`))
+    return null;
+  try {
+    return (await stat(resolved)).isFile() ? resolved : null;
+  } catch {
+    return null;
+  }
+}
+async function resolveRequest(rootReal, pathname) {
+  let decoded;
+  try {
+    decoded = decodeURIComponent(pathname);
+  } catch {
+    return null;
+  }
+  if (decoded.includes("\x00") || decoded.includes("\\"))
+    return null;
+  const segments = decoded.split("/").filter((segment) => segment !== "" && segment !== ".");
+  if (segments.some((segment) => segment === ".."))
+    return null;
+  const relative = segments.join("/");
+  const candidates = [
+    join2(rootReal, relative),
+    join2(rootReal, relative, "index.html")
+  ];
+  for (const candidate of candidates) {
+    const file = await regularFileUnder(rootReal, candidate);
+    if (file !== null)
+      return file;
+  }
+  return null;
+}
+async function createServeHandler(root) {
+  const rootReal = await realpath(root);
+  return async (request) => {
+    const method = request.method.toUpperCase();
+    if (method !== "GET" && method !== "HEAD") {
+      return new Response("Method not allowed", { status: 405 });
+    }
+    let pathname;
+    try {
+      pathname = new URL(request.url).pathname;
+    } catch {
+      return new Response("Bad request", { status: 400 });
+    }
+    if (pathname.length > MAX_PATH_BYTES) {
+      return new Response("URI too long", { status: 414 });
+    }
+    const head = method === "HEAD";
+    const file = await resolveRequest(rootReal, pathname);
+    if (file !== null) {
+      const body = Bun.file(file);
+      return new Response(head ? null : body, {
+        headers: {
+          "Cache-Control": "no-store",
+          "Content-Length": String(body.size),
+          "Content-Type": contentType(file)
+        }
+      });
+    }
+    const notFound = await regularFileUnder(rootReal, join2(rootReal, "404.html"));
+    if (notFound !== null) {
+      const body = Bun.file(notFound);
+      return new Response(head ? null : body, {
+        status: 404,
+        headers: {
+          "Cache-Control": "no-store",
+          "Content-Length": String(body.size),
+          "Content-Type": "text/html; charset=utf-8"
+        }
+      });
+    }
+    return new Response(head ? null : "Not found", {
+      status: 404,
+      headers: { "Cache-Control": "no-store" }
+    });
+  };
+}
+async function serveSite(options, io = {}) {
+  const host = options.host ?? "127.0.0.1";
+  const port = options.port ?? 8080;
+  if (!Number.isSafeInteger(port) || port < 0 || port > 65535) {
+    throw new Error("Port must be an integer from 0 through 65535");
+  }
+  const rootReal = await realpath(options.root);
+  if (!(await stat(rootReal)).isDirectory()) {
+    throw new Error(`Site root is not a directory: ${options.root}`);
+  }
+  const listen = io.listen ?? ((init) => Bun.serve(init));
+  const server = listen({
+    hostname: host,
+    port,
+    fetch: await createServeHandler(rootReal)
+  });
+  const boundPort = server.port ?? port;
+  return Object.freeze({
+    root: rootReal,
+    host,
+    port: boundPort,
+    url: `http://${host}:${String(boundPort)}/`,
+    close: () => server.stop()
+  });
+}
+
+// src/rerank-credentials.ts
+import { constants as constants2 } from "fs";
+import { open } from "fs/promises";
+import { homedir } from "os";
+import { isAbsolute as isAbsolute2, join as join3 } from "path";
+function unavailable(message) {
+  return { id: "typesafe", rerank: async () => ({ status: "unavailable", message }) };
+}
+async function createCliTypeSafeReranker(environment = process.env, homeDirectory = homedir()) {
+  if (Object.hasOwn(environment, "TYPESAFE_API_KEY")) {
+    return createTypeSafeReranker({ environment: { TYPESAFE_API_KEY: environment["TYPESAFE_API_KEY"] } });
+  }
+  const explicitFile = environment["TYPESAFE_API_KEY_FILE"];
+  const configDirectory = environment["XDG_CONFIG_HOME"];
+  if (explicitFile !== undefined && !isAbsolute2(explicitFile) || configDirectory !== undefined && configDirectory !== "" && !isAbsolute2(configDirectory)) {
+    return unavailable("TypeSafe credential file configuration requires absolute paths.");
+  }
+  const path = explicitFile ?? join3(configDirectory || join3(homeDirectory, ".config"), "wordcell", "typesafe-api-key");
+  let handle;
+  try {
+    handle = await open(path, constants2.O_RDONLY | constants2.O_NOFOLLOW | constants2.O_NONBLOCK);
+    const metadata = await handle.stat();
+    const uid = process.getuid?.();
+    if (!metadata.isFile() || metadata.nlink !== 1 || metadata.size < 1 || metadata.size > 514 || process.platform !== "win32" && ((metadata.mode & 63) !== 0 || metadata.uid !== uid)) {
+      return unavailable("TypeSafe credential file must be an owner-only regular file containing one API key.");
+    }
+    const bytes = Buffer.alloc(515);
+    const { bytesRead } = await handle.read(bytes, 0, bytes.length, 0);
+    const key = bytes.subarray(0, bytesRead).toString("utf8").replace(/\r?\n$/u, "");
+    if (!/^[\x21-\x7e]{1,512}$/u.test(key)) {
+      return unavailable("TypeSafe credential file must contain one valid API key.");
+    }
+    return createTypeSafeReranker({ environment: { TYPESAFE_API_KEY: key } });
+  } catch {
+    return unavailable("TypeSafe credentials are unavailable; set TYPESAFE_API_KEY or an owner-only TYPESAFE_API_KEY_FILE.");
+  } finally {
+    await handle?.close();
+  }
+}
+
 // src/cli-program.ts
 var defaultOutput2 = {
   stdout: (value) => process.stdout.write(value),
   stderr: (value) => process.stderr.write(value)
 };
 async function readBoundedUtf8(path, maximumBytes, label) {
-  const handle = await open(path, "r");
+  const handle = await open2(path, "r");
   try {
     const bytes = new Uint8Array(maximumBytes + 1);
     let offset = 0;
@@ -943,7 +1140,16 @@ async function loadSearchRulesFile(path) {
   }
   return parseSearchRules(input);
 }
-var usage = `wordcell \u2014 auditable capture and derived links for Markdown vaults
+var usage = `wordcell \u2014 a local knowledge base for coding agents
+
+Start here (no account or model needed):
+  wordcell init kb
+  wordcell note create notes/decision --title "A decision" --body "Keep retries bounded." --root kb
+  wordcell search "retries" --root kb --mode exact
+
+Already have Markdown? Search it with --root <your-notes-directory>.
+Use --mode exact for model-free search; optional hybrid search needs a local index.
+Quick start and examples: https://wordcell.io/docs
 
 Usage:
   wordcell init [directory] [--json]
@@ -971,12 +1177,14 @@ Usage:
   wordcell percolate [note] [--proofs] [--root <directory>] [--min-support <count>] [--limit <count>] [--json]
   wordcell list [--root <directory>] [--where <path=value>] [--has <path>] [--tag <tag>] [--scope <repository-path>] [--sort <field>] [--order <asc|desc>] [--limit <count>] [--json]
   wordcell index [--root <directory>] [--database <path>] [--force] [--json]
-  wordcell search <query> [--root <directory>] [--repo <repository>] [--database <path>] [--mode <hybrid|exact|keyword|semantic>] [--rules <file>] [--priority] [--where <path=value>] [--has <path>] [--tag <tag>] [--scope <repository-path>] [--related <note>] [--graph-depth <1|2>] [--no-graph] [--history | --no-history | --require-history] [--limit <count>] [--candidate-limit <count>] [--min-score <score>] [--json]
+  wordcell search <query> [--root <directory>] [--repo <repository>] [--database <path>] [--mode <hybrid|exact|keyword|semantic>] [--rules <file>] [--priority] [--where <path=value>] [--has <path>] [--tag <tag>] [--scope <repository-path>] [--related <note>] [--graph-depth <1|2>] [--no-graph] [--history | --no-history | --require-history] [--limit <count>] [--candidate-limit <count>] [--min-score <score>] [--rerank <typesafe>] [--rerank-limit <2..25>] [--json]
   wordcell history <note> [--root <directory>] [--repo <repository>] [--limit <count>] [--cochanged-limit <count>] [--json]
   wordcell history search <query-or-path> [--root <directory>] [--repo <repository>] [--limit <count>] [--commit-limit <count>] [--cochanged-limit <count>] [--json]
   wordcell evaluate <manifest.json> [--root <directory>] [--repo <repository>] [--database <path>] [--retriever <id>] [--split <development|test|all>] [--limit <count>] [--cutoff <count>] [--timeout <milliseconds>] [--baseline <id>] [--model-file <path>] [--cache-state <cold|mixed|warm>] [--json]
   wordcell portfolio search <query> --registry <file> --workspace <directory> (--shared | --vault <owner/id>...) [--mode <hybrid|exact|keyword|semantic>] [--rules <file>] [--priority] [--limit <count>] [--require-all] [--json]
   wordcell portfolio audit --registry <file> --workspace <directory> (--all | --shared | --vault <owner/id>...) [--strict] [--json]
+  wordcell publish --out <directory> [--root <directory>] [--index <path>] [--include <path>]... [--exclude <path>]... [--include-glob <pattern>]... [--exclude-glob <pattern>]... [--where <path=value>]... [--has <path>]... [--tag <tag>]... [--scope <repository-path>]... [--from <note> [--depth <count>] [--direction <in|out|both>]] [--title <title>] [--description <text>] [--base-path <path>] [--base-url <url>] [--noindex] [--no-index-content] [--deterministic] [--dry-run] [--list-limit <0-1000>] [--force] [--json]
+  wordcell serve --root <directory> [--host <host>] [--port <port>] [--json]
   wordcell inbox [--root <directory>] [--source-prefix <directory>] [--limit <count>] [--json]
   wordcell context <repository-path> [--root <vault>] [--repo <repository>] [--kind <auto|file|directory>] [--json]
   wordcell agents identity <repository-scope> [--json]
@@ -1367,6 +1575,220 @@ function parseListCommand(arguments_) {
     }
   };
 }
+function parsePublishCommand(arguments_) {
+  let root = ".";
+  let out;
+  let index;
+  let title;
+  let description;
+  let basePath;
+  let baseUrl;
+  let noindex = false;
+  let indexContent = true;
+  let deterministic = false;
+  let dryRun = false;
+  let listLimit = DEFAULT_PUBLISH_LIST_LIMIT;
+  let force = false;
+  let json = false;
+  let from;
+  let depth = 1;
+  let direction = "both";
+  const includes = [];
+  const excludes = [];
+  const includeGlobs = [];
+  const excludeGlobs = [];
+  const filters = [];
+  const tags = [];
+  const repositoryScopes = [];
+  for (let cursor = 0;cursor < arguments_.length; cursor += 1) {
+    const argument = arguments_[cursor];
+    if (argument === undefined)
+      continue;
+    if (argument === "--json") {
+      json = true;
+      continue;
+    }
+    if (argument === "--noindex") {
+      noindex = true;
+      continue;
+    }
+    if (argument === "--no-index-content") {
+      indexContent = false;
+      continue;
+    }
+    if (argument === "--deterministic") {
+      deterministic = true;
+      continue;
+    }
+    if (argument === "--dry-run") {
+      dryRun = true;
+      continue;
+    }
+    if (argument === "--force") {
+      force = true;
+      continue;
+    }
+    if (argument === "--root" || argument === "--out" || argument === "--index" || argument === "--title" || argument === "--description" || argument === "--base-path" || argument === "--base-url" || argument === "--include" || argument === "--exclude" || argument === "--include-glob" || argument === "--exclude-glob" || argument === "--list-limit" || argument === "--where" || argument === "--has" || argument === "--tag" || argument === "--scope" || argument === "--repository-scope" || argument === "--from" || argument === "--depth" || argument === "--direction") {
+      const value = readValue(arguments_, cursor);
+      if (value === null)
+        return { ok: false, message: `${argument} requires a value` };
+      if (argument === "--root")
+        root = value;
+      else if (argument === "--out")
+        out = value;
+      else if (argument === "--index")
+        index = value;
+      else if (argument === "--title")
+        title = value;
+      else if (argument === "--description")
+        description = value;
+      else if (argument === "--base-path")
+        basePath = value;
+      else if (argument === "--base-url")
+        baseUrl = value;
+      else if (argument === "--include")
+        includes.push(value);
+      else if (argument === "--exclude")
+        excludes.push(value);
+      else if (argument === "--include-glob")
+        includeGlobs.push(value);
+      else if (argument === "--exclude-glob")
+        excludeGlobs.push(value);
+      else if (argument === "--list-limit") {
+        if (!/^(0|[1-9][0-9]*)$/u.test(value) || Number(value) > MAX_PUBLISH_LIST_LIMIT) {
+          return { ok: false, message: `--list-limit must be an integer from 0 through ${MAX_PUBLISH_LIST_LIMIT}` };
+        }
+        listLimit = Number(value);
+      } else if (argument === "--from")
+        from = value;
+      else if (argument === "--depth") {
+        const parsed = Number(value);
+        if (!Number.isSafeInteger(parsed) || parsed < 1 || parsed > 10) {
+          return { ok: false, message: "--depth must be an integer from 1 through 10" };
+        }
+        depth = parsed;
+      } else if (argument === "--direction") {
+        if (value !== "in" && value !== "out" && value !== "both") {
+          return { ok: false, message: "--direction must be in, out, or both" };
+        }
+        direction = value;
+      } else if (argument === "--tag") {
+        if (tags.length >= MAX_QUERY_TAGS) {
+          return { ok: false, message: `Query tags may contain at most ${MAX_QUERY_TAGS} entries.` };
+        }
+        tags.push(value);
+      } else if (argument === "--scope" || argument === "--repository-scope") {
+        if (repositoryScopes.length >= MAX_REPOSITORY_SCOPES) {
+          return { ok: false, message: `Repository scope filters may contain at most ${MAX_REPOSITORY_SCOPES} entries.` };
+        }
+        repositoryScopes.push(value);
+      } else if (argument === "--has") {
+        if (value.trim() === "")
+          return { ok: false, message: "--has requires a metadata path" };
+        if (filters.length >= MAX_QUERY_FILTERS) {
+          return { ok: false, message: `Query filters may contain at most ${MAX_QUERY_FILTERS} entries.` };
+        }
+        filters.push({ kind: "exists", path: value });
+      } else {
+        const equals = value.indexOf("=");
+        const path = equals === -1 ? "" : value.slice(0, equals).trim();
+        if (path === "")
+          return { ok: false, message: "--where requires path=value" };
+        const scalar = metadataScalar(value.slice(equals + 1));
+        if (!scalar.ok)
+          return scalar;
+        if (filters.length >= MAX_QUERY_FILTERS) {
+          return { ok: false, message: `Query filters may contain at most ${MAX_QUERY_FILTERS} entries.` };
+        }
+        filters.push({ kind: "equals", path, value: scalar.value });
+      }
+      cursor += 1;
+      continue;
+    }
+    return {
+      ok: false,
+      message: argument.startsWith("--") ? "unknown publish option" : "publish does not accept positional arguments"
+    };
+  }
+  if (out === undefined)
+    return { ok: false, message: "publish requires --out <directory>" };
+  try {
+    validateQueryOptions({ filters, tags, repositoryScopes });
+  } catch (error) {
+    return { ok: false, message: error instanceof Error ? error.message : String(error) };
+  }
+  const selection = {
+    includes,
+    excludes,
+    includeGlobs,
+    excludeGlobs,
+    filters,
+    tags,
+    repositoryScopes,
+    ...from === undefined ? {} : { from: { note: from, depth, direction } }
+  };
+  return {
+    ok: true,
+    value: {
+      kind: "publish",
+      root,
+      out,
+      noindex,
+      indexContent,
+      deterministic,
+      dryRun,
+      listLimit,
+      force,
+      selection,
+      json,
+      ...index === undefined ? {} : { index },
+      ...title === undefined ? {} : { title },
+      ...description === undefined ? {} : { description },
+      ...basePath === undefined ? {} : { basePath },
+      ...baseUrl === undefined ? {} : { baseUrl }
+    }
+  };
+}
+function parseServeCommand(arguments_) {
+  let root;
+  let host = "127.0.0.1";
+  let port = 8080;
+  let json = false;
+  for (let cursor = 0;cursor < arguments_.length; cursor += 1) {
+    const argument = arguments_[cursor];
+    if (argument === undefined)
+      continue;
+    if (argument === "--json") {
+      json = true;
+      continue;
+    }
+    if (argument === "--root" || argument === "--host" || argument === "--port") {
+      const value = readValue(arguments_, cursor);
+      if (value === null)
+        return { ok: false, message: `${argument} requires a value` };
+      if (argument === "--root")
+        root = value;
+      else if (argument === "--host")
+        host = value;
+      else {
+        const parsed = Number(value);
+        if (!Number.isSafeInteger(parsed) || parsed < 0 || parsed > 65535) {
+          return { ok: false, message: "--port must be an integer from 0 through 65535" };
+        }
+        port = parsed;
+      }
+      cursor += 1;
+      continue;
+    }
+    return {
+      ok: false,
+      message: argument.startsWith("--") ? "unknown serve option" : "serve does not accept positional arguments"
+    };
+  }
+  if (root === undefined)
+    return { ok: false, message: "serve requires --root <directory>" };
+  return { ok: true, value: { kind: "serve", root, host, port, json } };
+}
 function parseInboxCommand(arguments_) {
   let root = ".";
   let index;
@@ -1439,6 +1861,8 @@ function parseSemanticCommand(command, arguments_) {
   let limit;
   let candidateLimit;
   let minScore;
+  let rerank;
+  let rerankLimit;
   let graphDepth;
   let noGraph = false;
   let history = false;
@@ -1496,7 +1920,7 @@ function parseSemanticCommand(command, arguments_) {
       cursor += 1;
       continue;
     }
-    if (command === "search" && (argument === "--mode" || argument === "--limit" || argument === "--candidate-limit" || argument === "--min-score" || argument === "--where" || argument === "--has" || argument === "--tag" || argument === "--scope" || argument === "--repository-scope" || argument === "--related" || argument === "--graph-depth")) {
+    if (command === "search" && (argument === "--mode" || argument === "--limit" || argument === "--candidate-limit" || argument === "--min-score" || argument === "--rerank" || argument === "--rerank-limit" || argument === "--where" || argument === "--has" || argument === "--tag" || argument === "--scope" || argument === "--repository-scope" || argument === "--related" || argument === "--graph-depth")) {
       const value = readValue(arguments_, cursor);
       if (value === null)
         return { ok: false, message: `${argument} requires a value` };
@@ -1505,6 +1929,17 @@ function parseSemanticCommand(command, arguments_) {
           return { ok: false, message: "--mode must be hybrid, exact, keyword, or semantic" };
         }
         mode = value;
+      } else if (argument === "--rerank") {
+        if (value !== "typesafe") {
+          return { ok: false, message: "--rerank must be typesafe" };
+        }
+        rerank = value;
+      } else if (argument === "--rerank-limit") {
+        const parsed = Number(value);
+        if (!Number.isSafeInteger(parsed) || parsed < 2 || parsed > MAX_RERANK_CANDIDATES) {
+          return { ok: false, message: `--rerank-limit must be an integer from 2 through ${MAX_RERANK_CANDIDATES}` };
+        }
+        rerankLimit = parsed;
       } else if (argument === "--where") {
         const equals = value.indexOf("=");
         const path = equals === -1 ? "" : value.slice(0, equals).trim();
@@ -1637,6 +2072,9 @@ function parseSemanticCommand(command, arguments_) {
       message: "Search minimum score applies only to hybrid, keyword, or semantic mode."
     };
   }
+  if (rerankLimit !== undefined && rerank === undefined) {
+    return { ok: false, message: "--rerank-limit requires --rerank typesafe" };
+  }
   if (priority && rulesPath === undefined) {
     return { ok: false, message: "--priority requires --rules" };
   }
@@ -1674,6 +2112,8 @@ function parseSemanticCommand(command, arguments_) {
       ...limit === undefined ? {} : { limit },
       ...candidateLimit === undefined ? {} : { candidateLimit },
       ...minScore === undefined ? {} : { minScore },
+      ...rerank === undefined ? {} : { rerank },
+      ...rerankLimit === undefined ? {} : { rerankLimit },
       query,
       json
     }
@@ -2420,6 +2860,10 @@ function parseArguments(arguments_) {
     return parseRelationCommand(arguments_.slice(1));
   if (command === "percolate")
     return parsePercolateCommand(arguments_.slice(1));
+  if (command === "publish")
+    return parsePublishCommand(arguments_.slice(1));
+  if (command === "serve")
+    return parseServeCommand(arguments_.slice(1));
   return { ok: false, message: "unknown command" };
 }
 function embeddingCount(result) {
@@ -2440,11 +2884,23 @@ function renderKnowledgeBaseSearch(result) {
   const lines = [
     `${result.mode[0]?.toLocaleUpperCase("en-US") ?? ""}${result.mode.slice(1)} results for \u201C${safe(result.query)}\u201D (${result.results.length})${result.partial ? " [partial]" : ""}`
   ];
+  const rerankLane = result.diagnostics.lanes.find(({ lane }) => lane === "rerank");
+  if (rerankLane !== undefined) {
+    lines.push(`  Rerank: typesafe over ${rerankLane.results} candidates (${rerankLane.status})` + (rerankLane.message === undefined ? "" : ` \u2014 ${safe(rerankLane.message)}`));
+    const receipt = rerankLane.rerank;
+    if (receipt?.accounting !== undefined) {
+      const { attempted, candidates, completed, elapsedMs, usageComplete } = receipt.accounting;
+      lines.push(`  Rerank requests: ${attempted}/${candidates} attempted, ${completed} settled; ${elapsedMs.toFixed(0)} ms` + (usageComplete ? "; usage complete" : "; usage incomplete, additional charges may be unknown"));
+      if (rerankLane.status !== "ready" && receipt.usage !== undefined) {
+        lines.push(`  Known rerank usage: ${receipt.usage.inputTokens ?? 0} input tokens, ${receipt.usage.outputTokens ?? 0} output tokens`);
+      }
+    }
+  }
   if (result.results.length === 0)
     lines.push("  None.");
   for (const hit of result.results) {
     const location = `${safe(hit.path)}${hit.line === undefined ? "" : `:${hit.line}`}`;
-    const evidence = hit.evidence.map((item) => `${item.kind}#${item.rank}`).join(", ");
+    const evidence = hit.evidence.map((item) => `${item.kind}#${searchEvidenceRank(item)}`).join(", ");
     lines.push(`  ${hit.rank}. ${hit.score.toFixed(3)}  ${location} \u2014 ${safe(hit.title)} [${safe(evidence)}]`);
     if (hit.snippet !== "")
       lines.push(`    ${safe(hit.snippet)}`);
@@ -2476,7 +2932,7 @@ async function runSemantic(command, output, dependencies) {
     repository: command.repository,
     ...command.database === undefined ? {} : { database: command.database },
     ...searchRules === undefined ? {} : { searchRules }
-  });
+  }, ...command.rerank === undefined ? [] : [{ rerankers: dependencies.rerankers ?? [await createCliTypeSafeReranker()] }]);
   try {
     const result = await kb.search({
       query: command.query,
@@ -2489,7 +2945,13 @@ async function runSemantic(command, output, dependencies) {
       history: command.history,
       ...command.limit === undefined ? {} : { limit: command.limit },
       ...command.candidateLimit === undefined ? {} : { candidateLimit: command.candidateLimit },
-      ...command.minScore === undefined ? {} : { minScore: command.minScore }
+      ...command.minScore === undefined ? {} : { minScore: command.minScore },
+      ...command.rerank === undefined ? {} : {
+        rerank: {
+          engine: command.rerank,
+          ...command.rerankLimit === undefined ? {} : { limit: command.rerankLimit }
+        }
+      }
     });
     output.stdout(command.json ? terminalSafeJson(result) : sanitizeTerminalText(renderKnowledgeBaseSearch(result)));
     return 0;
@@ -3104,6 +3566,36 @@ async function runList(command, output, dependencies) {
   output.stdout(command.json ? terminalSafeJson({ root: snapshot.root, count: rows.length, notes: rows }) : sanitizeTerminalText(renderList(rows)));
   return 0;
 }
+async function runPublish(command, output, dependencies) {
+  const result = await (dependencies.publishVault ?? publishVault)({
+    root: command.root,
+    out: command.out,
+    noindex: command.noindex,
+    indexContent: command.indexContent,
+    deterministic: command.deterministic,
+    dryRun: command.dryRun,
+    listLimit: command.listLimit,
+    force: command.force,
+    selection: command.selection,
+    ...command.index === undefined ? {} : { index: command.index },
+    ...command.title === undefined ? {} : { title: command.title },
+    ...command.description === undefined ? {} : { description: command.description },
+    ...command.basePath === undefined ? {} : { basePath: command.basePath },
+    ...command.baseUrl === undefined ? {} : { baseUrl: command.baseUrl }
+  });
+  output.stdout(command.json ? terminalSafeJson(result.report) : sanitizeTerminalText(renderPublishReportText(result.report, command.dryRun)));
+  return 0;
+}
+async function runServe(command, output, dependencies) {
+  const site = await (dependencies.serveSite ?? serveSite)({
+    root: command.root,
+    host: command.host,
+    port: command.port
+  });
+  output.stdout(command.json ? terminalSafeJson({ root: site.root, host: site.host, port: site.port, url: site.url }) : `Serving ${safe(site.root)} at ${safe(site.url)}
+`);
+  return 0;
+}
 async function runCatalog(command, output, dependencies) {
   const snapshot = await (dependencies.scanVault ?? scanVault)(command.root, command.options);
   const relativeIndex = relative(snapshot.root, snapshot.indexPath).split("\\").join("/");
@@ -3673,6 +4165,10 @@ ${sanitizeTerminalText(usage)}`);
       return await runPercolate(command, output, dependencies);
     if (command.kind === "list")
       return await runList(command, output, dependencies);
+    if (command.kind === "publish")
+      return await runPublish(command, output, dependencies);
+    if (command.kind === "serve")
+      return await runServe(command, output, dependencies);
     if (command.kind === "inbox")
       return await runInbox(command, output, dependencies);
     if (command.kind === "catalog")