@hraness/wordcell 0.21.3 → 0.22.1

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,
@@ -114,10 +122,14 @@ import {
   type QuerySort,
 } from "./query.js";
 import {
+  auditRepositoryMemoryScopes,
   buildRepositoryMemoryContext,
+  MAX_REPOSITORY_MEMORY_DETAIL_LIMIT,
   MAX_REPOSITORY_SCOPES,
   repositoryMemoryGroupKeys,
   type RepositoryMemoryContext,
+  type RepositoryMemoryScopeAudit,
+  type RepositoryMemoryScopeAuditError,
 } from "./repository-memory.js";
 import { validateSearchQuery } from "./search.js";
 import {
@@ -140,11 +152,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 +230,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]
@@ -228,7 +252,7 @@ Usage:
   wordcell inspect <url> [capture options]
   wordcell pdf <file-or-url> [PDF options]
   wordcell refresh [--root <directory>] [--index <path>] [--json]
-  wordcell check [--root <directory>] [--index <path>] [--no-catalog] [--json]
+  wordcell check [--root <directory>] [--index <path>] [--no-catalog] [--repo <repository>] [--json]
   wordcell catalog [--root <directory>] [--index <path>] [--json]
   wordcell graph [--root <directory>] [--index <path>] [--json]
   wordcell graph rebuild [--fresh] [--root <directory>] [--index <path>] [--json]
@@ -243,12 +267,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 +385,8 @@ type ParsedCommand =
       readonly limit?: number;
       readonly candidateLimit?: number;
       readonly minScore?: number;
+      readonly rerank?: "typesafe";
+      readonly rerankLimit?: number;
       readonly query: string;
       readonly json: boolean;
     }
@@ -419,6 +447,8 @@ type ParsedCommand =
       readonly depth?: number;
       readonly limit?: number;
       readonly noCatalog?: boolean;
+      /** `check --repo` only: repository working tree for the advisory scope lane. */
+      readonly repository?: string;
     }
   | {
       readonly kind: "note-create";
@@ -446,6 +476,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 +523,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;
@@ -477,8 +534,11 @@ type CliDependencies = GraphCliDependencies & {
   readonly percolateWithGraph?: typeof percolateWithGraph;
   readonly inspectAgentContextRepository?: typeof inspectAgentContextRepository;
   readonly buildRepositoryMemoryContext?: typeof buildRepositoryMemoryContext;
+  readonly auditRepositoryMemoryScopes?: typeof auditRepositoryMemoryScopes;
   readonly auditAgentGuideRepository?: typeof auditAgentGuideRepository;
   readonly validateMarkdownAttachments?: typeof validateMarkdownAttachments;
+  readonly publishVault?: typeof publishVault;
+  readonly serveSite?: typeof serveSite;
 };
 
 function safe(value: string): string {
@@ -570,6 +630,7 @@ function parseVaultCommand(command: VaultCommand, arguments_: readonly string[])
   let depth = 1;
   let limit: number | undefined;
   let noCatalog = false;
+  let repository: string | undefined;
   const positional: string[] = [];
 
   for (let cursor = 0; cursor < arguments_.length; cursor += 1) {
@@ -583,6 +644,13 @@ function parseVaultCommand(command: VaultCommand, arguments_: readonly string[])
       noCatalog = true;
       continue;
     }
+    if (argument === "--repo" && command === "check") {
+      const value = readValue(arguments_, cursor);
+      if (value === null) return { ok: false, message: "--repo requires a value" };
+      repository = value;
+      cursor += 1;
+      continue;
+    }
     if (argument === "--root" || argument === "--index") {
       const value = readValue(arguments_, cursor);
       if (value === null) return { ok: false, message: `${argument} requires a value` };
@@ -647,6 +715,7 @@ function parseVaultCommand(command: VaultCommand, arguments_: readonly string[])
       options: index === undefined ? {} : { index },
       json,
       ...(command === "check" && noCatalog ? { noCatalog: true } : {}),
+      ...(command === "check" && repository !== undefined ? { repository } : {}),
     },
   };
 }
@@ -866,6 +935,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 +1200,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 +1263,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 +1280,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 +1420,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 +1461,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 +2216,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 +2240,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 +2297,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 +2323,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)
@@ -2344,6 +2653,7 @@ function summary(
   options: {
     readonly noCatalog?: boolean;
     readonly attachments?: AttachmentValidationReport;
+    readonly repositoryScopes?: RepositoryMemoryScopeAudit;
   } = {},
 ): Record<string, unknown> {
   return {
@@ -2369,6 +2679,9 @@ function summary(
             issues: options.attachments.issues,
           },
         }),
+    ...(options.repositoryScopes === undefined
+      ? {}
+      : { repositoryScopes: options.repositoryScopes }),
   };
 }
 
@@ -2404,6 +2717,60 @@ function renderAdvisories(analysis: VaultAnalysis): string[] {
   return lines;
 }
 
+function renderRepositoryScopeAuditError(error: RepositoryMemoryScopeAuditError): string {
+  if (error.kind === "invalid-record") {
+    return `${safe(error.path)}: ${error.issues.map(safe).join(" ")}`;
+  }
+  const declared = error.recordPaths.map(safe).join(", ")
+    + (error.recordPathsTruncated ? ", …" : "");
+  return `${safe(error.scope)}: ${safe(error.state.reason)} at ${safe(error.state.path)}`
+    + ` (declared by ${declared})`;
+}
+
+/**
+ * Advisory repository-state lane for `check --repo`.
+ *
+ * Every line derives from authored `repository_scopes` declarations and the
+ * working tree they name. Nothing here changes the exit code: a current note
+ * that names a path the repository no longer has is reported for a reader to
+ * judge, never treated as a vault correctness failure.
+ */
+function renderRepositoryScopeAudit(audit: RepositoryMemoryScopeAudit): string[] {
+  const { counts } = audit;
+  const lines = [
+    `Repository scopes: ${counts.authoredRecords} declaring note${counts.authoredRecords === 1 ? "" : "s"}; `
+      + `${counts.distinctScopes} distinct scope${counts.distinctScopes === 1 ? "" : "s"} `
+      + `(${counts.presentScopes} present, ${counts.absentScopes} absent, ${counts.invalidScopes} unusable).`,
+  ];
+  if (audit.advisories.total > 0) {
+    lines.push(audit.advisories.total === 1
+      ? "Advisory: 1 current note declares a repository path that no longer exists."
+      : `Advisory: ${audit.advisories.total} current notes declare repository paths that no longer exist.`);
+    for (const advisory of audit.advisories.details) {
+      lines.push(`  ${safe(advisory.path)} declares absent scope ${safe(advisory.scope)}`);
+    }
+    if (audit.advisories.truncated) {
+      lines.push(
+        `  … ${audit.advisories.total - audit.advisories.returned} more; rerun with --json for the complete audit.`,
+      );
+    }
+  }
+  if (audit.errors.total > 0) {
+    lines.push(
+      `Advisory: ${audit.errors.total} repository scope declaration problem${audit.errors.total === 1 ? "" : "s"}.`,
+    );
+    for (const error of audit.errors.details) {
+      lines.push(`  ${renderRepositoryScopeAuditError(error)}`);
+    }
+    if (audit.errors.truncated) {
+      lines.push(
+        `  … ${audit.errors.total - audit.errors.returned} more; rerun with --json for the complete audit.`,
+      );
+    }
+  }
+  return lines;
+}
+
 function checkExitCode(
   snapshot: VaultSnapshot,
   noCatalog = false,
@@ -2430,6 +2797,7 @@ function renderSnapshot(
   snapshot: VaultSnapshot,
   noCatalog = false,
   attachments?: AttachmentValidationReport,
+  repositoryScopes?: RepositoryMemoryScopeAudit,
 ): string {
   const lines = [
     `${command === "refresh" ? "Refreshed" : "Checked"} ${safe(snapshot.root)}`,
@@ -2449,6 +2817,7 @@ function renderSnapshot(
     lines.push("error: attachment validation was truncated by a resource limit");
   }
   lines.push(...renderAdvisories(snapshot.analysis));
+  if (repositoryScopes !== undefined) lines.push(...renderRepositoryScopeAudit(repositoryScopes));
   return `${lines.join("\n")}\n`;
 }
 
@@ -2834,6 +3203,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,
@@ -3470,9 +3882,24 @@ async function runVault(
           documents: snapshot.notes.map(({ path, content }) => ({ path, content })),
         })
       : undefined;
+    const repositoryScopes = command.kind === "check" && command.repository !== undefined
+      ? await (dependencies.auditRepositoryMemoryScopes ?? auditRepositoryMemoryScopes)(
+          snapshot.notes,
+          {
+            repositoryRoot: command.repository,
+            detailLimit: MAX_REPOSITORY_MEMORY_DETAIL_LIMIT,
+          },
+        )
+      : undefined;
     output.stdout(command.json
-      ? terminalSafeJson(summary(snapshot, { noCatalog, ...(attachments === undefined ? {} : { attachments }) }))
-      : sanitizeTerminalText(renderSnapshot(command.kind, snapshot, noCatalog, attachments)));
+      ? terminalSafeJson(summary(snapshot, {
+          noCatalog,
+          ...(attachments === undefined ? {} : { attachments }),
+          ...(repositoryScopes === undefined ? {} : { repositoryScopes }),
+        }))
+      : sanitizeTerminalText(
+        renderSnapshot(command.kind, snapshot, noCatalog, attachments, repositoryScopes),
+      ));
     return checkExitCode(snapshot, noCatalog, attachments);
   }
   if (command.kind === "graph") {
@@ -3580,6 +4007,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);