@hraness/wordcell 0.21.3 → 0.22.0

package/skills/wordcell/references/publish.md

@@ -0,0 +1,93 @@
+# Publish selected knowledge as a static site
+
+Use `wordcell publish` to turn selected Markdown notes into read-only pages,
+backlinks, a graph, and browser-local search. It builds files locally with no
+model call. Publishing here means generating the artifact; uploading it to a
+host is a separate action.
+
+## Select and preview
+
+Use the scope in the user's request. Ask only when the selection or destination
+is materially ambiguous. Resolve `KB_ROOT` before running commands, and choose
+an output directory outside the vault that does not contain it.
+
+Start with a compact, read-only preview:
+
+```sh
+wordcell publish --root "$KB_ROOT" --out ./public-notes \
+  --include notes/decision --include plans/implementation \
+  --dry-run --list-limit 20 --json
+```
+
+The report contains counts, at most 20 selected note IDs, and a digest of the
+selected Markdown. It does not print note bodies. Inspect `selection.truncated` before
+treating the preview as a complete list. Raise `--list-limit` up to 1000 when
+individual IDs matter, or use zero for counts and a digest alone. Open only
+selected notes whose contents need review; do not load or summarize the whole
+vault to choose a known slice.
+
+Selectors are repeatable:
+
+- `--include <id-or-directory>` selects exact notes or directory prefixes.
+- `--include-glob 'notes/**'` and `--exclude-glob '**/draft-*'` select by pattern.
+  Quote globs so the shell does not expand them. `*` matches within one segment,
+  `?` matches one character, and `**` matches whole path segments.
+- `--where type=concept`, `--has relations`, `--tag public`, and
+  `--scope packages/parser` select by authored metadata.
+- `--from notes/topic --depth 2 --direction both` selects a bounded neighborhood
+  of explicit links and relationships. Oversized neighborhoods fail rather
+  than silently publish an incomplete selection.
+
+Positive path, glob, metadata, and graph selectors form a **union**. Metadata
+predicates within their group must all match. `--include notes --tag public`
+therefore includes all of `notes`, not only its public-tagged notes. Use a
+metadata conjunction or explicit note IDs when an intersection is required.
+Excludes and `publish: false` always win.
+
+Publication is not prose redaction. Review selected text and referenced assets
+for anything unsuitable for the intended audience. A selected note can mention
+excluded material in its own text. Private flags exclude a note's page, search
+record, and graph membership; they cannot remove information copied into another
+note or attachment. `--noindex` is a crawler preference, not access control.
+
+## Build the reviewed slice
+
+Repeat the preview command without `--dry-run`. Keep the same selectors and
+check the returned digest and counts; if the Markdown changed, review it again.
+The digest covers selected Markdown, not attachment bytes. Review referenced
+attachments separately before sharing.
+
+```sh
+wordcell publish --root "$KB_ROOT" --out ./public-notes \
+  --include notes/decision --include plans/implementation \
+  --title "Project decisions" --deterministic --json
+```
+
+Use `--force` only to replace a known generated output directory. Set
+`--base-path /handbook/` if the host serves the files at a subpath, and add
+`--base-url https://docs.example.com` when a sitemap is useful. Use
+`--no-index-content` for field-only search. None of these flags changes the
+source vault.
+
+Read dropped-link, skipped-asset, and search-truncation counts. Run
+`wordcell check --root "$KB_ROOT"` when missing links or attachments need
+diagnosis. Do not report missing content as complete.
+
+## Preview and host
+
+```sh
+wordcell serve --root ./public-notes --port 8080
+```
+
+Open the loopback URL. Check a note, its navigation, the Search overlay, and the
+Graph page. HTML can be read without JavaScript; browser search and graph need
+HTTP hosting rather than `file://`. The preview server is not a production
+service.
+
+Upload the generated directory to the user's selected static host only when
+hosting is in the request. Confirm the exact destination and preserve unrelated
+files. Verify the public URL and selected content after upload. A successful
+local build alone is not a live deployment.
+
+The full artifact contract and hosting options are in
+[the publishing guide](https://github.com/hraness/wordcell/blob/main/docs/publish.md).

package/skills/wordcell/references/query.md

@@ -155,6 +155,28 @@ form. Graph neighbors and Git history remain separate from primary
 text rank. They explain and expand candidates without becoming authored facts,
 links, or recency boosts.
 
+Reranking is opt-in through `--rerank typesafe`. It uses `jev-1.13.0` and sends
+the query plus each candidate's identifier, title, vault-relative path, and at
+most 512 UTF-8 bytes of snippet text to TypeSafe. Enable it only for vaults
+approved for external processing and provider input-token charges. Use
+`--rerank-limit 25` to bound the window (2–25 candidates); four requests run
+concurrently under one eight-second deadline with no retries. Exact identities
+remain first. Results retain their original scores and retrieval evidence.
+
+The CLI reads `TYPESAFE_API_KEY`, an explicit `TYPESAFE_API_KEY_FILE`, or the
+owner-only file `~/.config/wordcell/typesafe-api-key` (honoring
+`XDG_CONFIG_HOME`). Keep credentials outside the repository. A missing key or
+provider failure retains baseline ordering and marks the rerank lane
+unavailable or degraded. Inspect its structured `rerank` receipt for attempted
+requests, known usage, elapsed time, and whether usage is complete; an unknown
+charge is never reported as zero. A successful exit alone does not establish
+that reranking occurred. Omit `--rerank` for local-only retrieval.
+
+For a repository's ordinary KB searches, prefer its approved, pinned
+`kb:search` script when present. That script declares the vault and processing
+choice. Read returned notes before acting; model probabilities are ranking
+signals, not proof of truth. Explicit priority rules still run last.
+
 `wordcell history <note>` returns the bounded commit history already associated with
 one resolved note. `wordcell history search <query-or-path>` searches the bounded Git
 projection directly and retains hashes, subjects, matched paths, co-change

package/src/cli-program.ts

@@ -96,6 +96,14 @@ import {
   openKnowledgePortfolio,
   type PortfolioSearchResult,
 } from "./portfolio.js";
+import {
+  DEFAULT_PUBLISH_LIST_LIMIT,
+  MAX_PUBLISH_LIST_LIMIT,
+  publishVault,
+  renderPublishReportText,
+  type PublishSelectionInput,
+} from "./publish.js";
+import { serveSite } from "./serve.js";
 import {
   MAX_AUTHORIZED_VAULTS,
   loadPortfolioRegistry,
@@ -140,11 +148,14 @@ import {
   MAX_SEARCH_RELATED_SEEDS,
   MAX_SEARCH_RESULTS,
   openKnowledgeBase,
+  searchEvidenceRank,
   type KnowledgeBaseGraphOptions,
   type KnowledgeBaseSearchMode,
   type KnowledgeBaseSearchOrdering,
   type KnowledgeBaseSearchResult,
 } from "./sdk.js";
+import { MAX_RERANK_CANDIDATES, type SearchReranker } from "./rerank.js";
+import { createCliTypeSafeReranker } from "./rerank-credentials.js";
 import {
   refreshVault,
   scanVault,
@@ -215,7 +226,16 @@ async function loadSearchRulesFile(path: string): Promise<SearchRulesV1> {
   return parseSearchRules(input);
 }
 
-export const usage = `wordcell — auditable capture and derived links for Markdown vaults
+export const usage = `wordcell — 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]
@@ -243,12 +263,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]
@@ -359,6 +381,8 @@ type ParsedCommand =
       readonly limit?: number;
       readonly candidateLimit?: number;
       readonly minScore?: number;
+      readonly rerank?: "typesafe";
+      readonly rerankLimit?: number;
       readonly query: string;
       readonly json: boolean;
     }
@@ -446,6 +470,31 @@ type ParsedCommand =
       readonly minSupport: number;
       readonly limit: number;
       readonly json: boolean;
+    }
+  | {
+      readonly kind: "publish";
+      readonly root: string;
+      readonly out: string;
+      readonly index?: string;
+      readonly title?: string;
+      readonly description?: string;
+      readonly basePath?: string;
+      readonly baseUrl?: string;
+      readonly noindex: boolean;
+      readonly indexContent: boolean;
+      readonly deterministic: boolean;
+      readonly dryRun: boolean;
+      readonly listLimit: number;
+      readonly force: boolean;
+      readonly selection: PublishSelectionInput;
+      readonly json: boolean;
+    }
+  | {
+      readonly kind: "serve";
+      readonly root: string;
+      readonly host: string;
+      readonly port: number;
+      readonly json: boolean;
     };
 
 type ParseResult =
@@ -468,6 +517,8 @@ type CliDependencies = GraphCliDependencies & {
   readonly indexSemanticVault?: typeof indexSemanticVault;
   readonly openKnowledgeBase?: typeof openKnowledgeBase;
   readonly openKnowledgeBaseEvaluation?: typeof openKnowledgeBaseEvaluation;
+  /** Test seam; production wiring builds the TypeSafe reranker lazily per flag. */
+  readonly rerankers?: readonly SearchReranker[];
   readonly digestEvaluationModel?: (path: string) => Promise<string>;
   readonly evaluationNow?: () => Date;
   readonly createNote?: typeof createNote;
@@ -479,6 +530,8 @@ type CliDependencies = GraphCliDependencies & {
   readonly buildRepositoryMemoryContext?: typeof buildRepositoryMemoryContext;
   readonly auditAgentGuideRepository?: typeof auditAgentGuideRepository;
   readonly validateMarkdownAttachments?: typeof validateMarkdownAttachments;
+  readonly publishVault?: typeof publishVault;
+  readonly serveSite?: typeof serveSite;
 };
 
 function safe(value: string): string {
@@ -866,6 +919,195 @@ function parseListCommand(arguments_: readonly string[]): ParseResult {
   };
 }
 
+function parsePublishCommand(arguments_: readonly string[]): ParseResult {
+  let root = ".";
+  let out: string | undefined;
+  let index: string | undefined;
+  let title: string | undefined;
+  let description: string | undefined;
+  let basePath: string | undefined;
+  let baseUrl: string | undefined;
+  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: string | undefined;
+  let depth = 1;
+  let direction: LinkDirection = "both";
+  const includes: string[] = [];
+  const excludes: string[] = [];
+  const includeGlobs: string[] = [];
+  const excludeGlobs: string[] = [];
+  const filters: MetadataFilter[] = [];
+  const tags: string[] = [];
+  const repositoryScopes: string[] = [];
+
+  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: unknown) {
+    return { ok: false, message: error instanceof Error ? error.message : String(error) };
+  }
+  const selection: PublishSelectionInput = {
+    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_: readonly string[]): ParseResult {
+  let root: string | undefined;
+  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 > 65_535) {
+          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_: readonly string[]): ParseResult {
   let root = ".";
   let index: string | undefined;
@@ -942,6 +1184,8 @@ function parseSemanticCommand(command: "index" | "search", arguments_: readonly
   let limit: number | undefined;
   let candidateLimit: number | undefined;
   let minScore: number | undefined;
+  let rerank: "typesafe" | undefined;
+  let rerankLimit: number | undefined;
   let graphDepth: number | undefined;
   let noGraph = false;
   let history = false;
@@ -1003,6 +1247,8 @@ function parseSemanticCommand(command: "index" | "search", arguments_: readonly
       || argument === "--limit"
       || argument === "--candidate-limit"
       || argument === "--min-score"
+      || argument === "--rerank"
+      || argument === "--rerank-limit"
       || argument === "--where"
       || argument === "--has"
       || argument === "--tag"
@@ -1018,6 +1264,17 @@ function parseSemanticCommand(command: "index" | "search", arguments_: readonly
           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();
@@ -1147,6 +1404,9 @@ function parseSemanticCommand(command: "index" | "search", arguments_: readonly
       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" };
   }
@@ -1185,6 +1445,8 @@ function parseSemanticCommand(command: "index" | "search", arguments_: readonly
       ...(limit === undefined ? {} : { limit }),
       ...(candidateLimit === undefined ? {} : { candidateLimit }),
       ...(minScore === undefined ? {} : { minScore }),
+      ...(rerank === undefined ? {} : { rerank }),
+      ...(rerankLimit === undefined ? {} : { rerankLimit }),
       query,
       json,
     },
@@ -1938,6 +2200,8 @@ export function parseArguments(arguments_: readonly string[]): ParseResult {
   if (command === "note") return parseNoteCommand(arguments_.slice(1));
   if (command === "relation") 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" };
 }
 
@@ -1960,10 +2224,28 @@ function renderKnowledgeBaseSearch(result: KnowledgeBaseSearchResult): string {
   const lines = [
     `${result.mode[0]?.toLocaleUpperCase("en-US") ?? ""}${result.mode.slice(1)} results for “${safe(result.query)}” (${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 ? "" : ` — ${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} — ${safe(hit.title)} [${safe(evidence)}]`);
     if (hit.snippet !== "") lines.push(`    ${safe(hit.snippet)}`);
   }
@@ -1999,12 +2281,17 @@ async function runSemantic(
   const searchRules = command.rulesPath === undefined
     ? undefined
     : await loadSearchRulesFile(command.rulesPath);
-  const kb = await (dependencies.openKnowledgeBase ?? openKnowledgeBase)({
-    root: command.root,
-    repository: command.repository,
-    ...(command.database === undefined ? {} : { database: command.database }),
-    ...(searchRules === undefined ? {} : { searchRules }),
-  });
+  const kb = await (dependencies.openKnowledgeBase ?? openKnowledgeBase)(
+    {
+      root: command.root,
+      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,
@@ -2020,6 +2307,12 @@ async function runSemantic(
         ? {}
         : { candidateLimit: command.candidateLimit }),
       ...(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)
@@ -2834,6 +3127,49 @@ async function runList(
   return 0;
 }
 
+async function runPublish(
+  command: Extract<ParsedCommand, { readonly kind: "publish" }>,
+  output: Output,
+  dependencies: CliDependencies,
+): Promise<number> {
+  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: Extract<ParsedCommand, { readonly kind: "serve" }>,
+  output: Output,
+  dependencies: CliDependencies,
+): Promise<number> {
+  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)}\n`);
+  return 0;
+}
+
 async function runCatalog(
   command: Extract<ParsedCommand, { readonly kind: "catalog" }>,
   output: Output,
@@ -3580,6 +3916,8 @@ export async function main(
     }
     if (command.kind === "percolate") 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") return await runCatalog(command, output, dependencies);
     return await runVault(command, output, dependencies);

package/src/index.ts

@@ -11,7 +11,11 @@ export * from "./init.js";
 export * from "./navigation.js";
 export * from "./oh-adoption.js";
 export * from "./percolate.js";
+export * from "./publish.js";
+export * from "./publish-model.js";
 export * from "./query.js";
+export * from "./rerank.js";
+export * from "./rerank-typesafe.js";
 export * from "./repository-memory.js";
 export * from "./search.js";
 export * from "./semantic.js";