@swarmvaultai/cli 1.4.0 → 3.1.0

package/README.md

@@ -44,6 +44,9 @@ swarmvault graph share --svg ./share-card.svg
 swarmvault graph share --bundle ./share-kit
 swarmvault benchmark
 swarmvault query "What keeps recurring?" --commit
+swarmvault context build "Ship this feature safely" --target ./src --budget 8000
+swarmvault task start "Ship this feature safely" --target ./src --agent codex
+swarmvault retrieval status
 swarmvault query "Turn this into slides" --format slides
 swarmvault explore "What should I research next?" --steps 3
 swarmvault lint --deep
@@ -211,7 +214,7 @@ Compile the current manifests into:
 
 - generated markdown in `wiki/`
 - structured graph data in `state/graph.json`
-- local search data in `state/search.sqlite`
+- local retrieval data in `state/retrieval/`
 - share cards at `wiki/graph/share-card.md` and `wiki/graph/share-card.svg`, plus a portable share kit at `wiki/graph/share-kit/`
 
 The compiler also reads `swarmvault.schema.md` and records a `schema_hash` plus lifecycle metadata such as `status`, `created_at`, `updated_at`, `compiled_from`, and `managed_by` in generated pages so schema edits can mark pages stale without losing lifecycle state.
@@ -270,13 +273,47 @@ By default, the answer is written into `wiki/outputs/` and immediately registere
 - `wiki/index.md`
 - `wiki/outputs/index.md`
 - `state/graph.json`
-- `state/search.sqlite`
+- `state/retrieval/`
 
 Saved outputs also carry related page, node, and source metadata so SwarmVault can refresh related source, concept, and entity pages immediately.
 
 Human-authored pages in `wiki/insights/` are also indexed into search and query context, but SwarmVault does not rewrite them after initialization.
 
-By default, query uses the local SQLite search index. When an embedding-capable provider is available and `search.hybrid` is not disabled, semantic page matches are fused into the same candidate set before answer generation. `tasks.embeddingProvider` is the explicit way to choose that backend, but SwarmVault can also fall back to a `queryProvider` with embeddings support. Set `search.rerank: true` when you want the configured `queryProvider` to rerank the merged top hits. `--commit` immediately commits saved `wiki/` and `state/` changes when the vault root is inside a git repo.
+By default, query uses the local SQLite retrieval index. When an embedding-capable provider is available and `retrieval.hybrid` is not disabled, semantic page matches are fused into the same candidate set before answer generation. `tasks.embeddingProvider` is the explicit way to choose that backend, but SwarmVault can also fall back to a `queryProvider` with embeddings support. Set `retrieval.rerank: true` when you want the configured `queryProvider` to rerank the merged top hits. `--commit` immediately commits saved `wiki/` and `state/` changes when the vault root is inside a git repo.
+
+### `swarmvault context build|list|show|delete`
+
+Build and manage agent-ready context packs from the compiled vault.
+
+- `context build "<goal>"` assembles relevant pages, graph nodes, edges, hyperedges, citations, and explicit omitted entries into a bounded bundle
+- `--target <path-or-node>` anchors the pack around a file, page id, node id, or graph label
+- `--task <id>` links the newly built context pack to an active task
+- `--memory <id>` remains a compatibility alias for `--task`
+- `--budget <tokens>` caps the estimated token budget; over-budget candidates are listed in `omittedItems`
+- `--format markdown|json|llms` controls the printed output shape, while every pack is still saved as JSON
+- saved artifacts live under `state/context-packs/`, with companion markdown pages under `wiki/context/`
+- `context list`, `context show <id>`, and `context delete <id>` manage saved packs
+
+Use this before handing work to an agent, starting a PR review, or preserving the evidence bundle behind a design/debugging decision.
+
+### `swarmvault task start|update|finish|list|show|resume`
+
+Record a durable local task ledger for agent work.
+
+- `task start "<goal>" --target <path-or-node>` creates `state/memory/tasks/<id>.json`, `wiki/memory/tasks/<id>.md`, updates `wiki/memory/index.md`, and builds an initial context pack
+- `task update <id>` records notes, decisions, changed paths, context packs, sessions, sources, pages, nodes, git refs, or status changes
+- `task finish <id> --outcome <text>` marks the task completed and can add one or more `--follow-up` entries
+- `task list`, `task show <id>`, and `task resume <id> --format markdown|json|llms` expose the task history for the next agent
+
+`query`, `explore`, and `context build` accept `--task <id>` so saved outputs and context packs can attach to an active task. The 2.0 `memory` command group and `--memory <id>` flag remain compatibility aliases.
+
+### `swarmvault retrieval status|rebuild|doctor`
+
+Inspect and maintain the local retrieval index under `state/retrieval/`.
+
+- `retrieval status` reports backend, configured hybrid/rerank behavior, manifest freshness, page count, and the current SQLite shard path
+- `retrieval rebuild` rebuilds the local shard from current wiki pages and refreshes `state/retrieval/manifest.json`
+- `retrieval doctor` checks for stale or missing retrieval artifacts; add `--repair` to rebuild missing or stale artifacts immediately
 
 ### `swarmvault explore "<question>" [--steps <n>] [--format markdown|report|slides|chart|image]`
 
@@ -345,10 +382,28 @@ Run SwarmVault as a local MCP server over stdio. This exposes the vault to compa
 - `compile_vault`
 - `lint_vault`
 - `blast_radius`
-
-`compile_vault` also accepts `maxTokens` for bounded wiki output, and `blast_radius` traces reverse import impact for a file or module target.
-
-The MCP surface also exposes `swarmvault://schema`, `swarmvault://sessions`, `swarmvault://sessions/{path}`, and includes `schemaPath` in `workspace_info`.
+- `build_context_pack`
+- `list_context_packs`
+- `read_context_pack`
+- `start_task`
+- `update_task`
+- `finish_task`
+- `list_tasks`
+- `read_task`
+- `resume_task`
+- `start_memory_task`
+- `update_memory_task`
+- `finish_memory_task`
+- `list_memory_tasks`
+- `read_memory_task`
+- `resume_memory_task`
+- `retrieval_status`
+- `rebuild_retrieval`
+- `doctor_retrieval`
+
+`compile_vault` also accepts `maxTokens` for bounded wiki output, `blast_radius` traces reverse import impact for a file or module target, `build_context_pack` creates the same bounded agent evidence bundles as `swarmvault context build`, the task tools mirror `swarmvault task`, the memory tools mirror the compatibility command group, and retrieval tools inspect or repair the local index.
+
+The MCP surface also exposes `swarmvault://schema`, `swarmvault://sessions`, `swarmvault://sessions/{path}`, `swarmvault://context-packs`, `swarmvault://tasks`, `swarmvault://memory-tasks`, and includes `schemaPath` in `workspace_info`.
 
 ### `swarmvault graph serve`
 
@@ -539,15 +594,18 @@ Search behavior is configurable separately from provider routing:
 
 ```json
 {
-  "search": {
+  "retrieval": {
+    "backend": "sqlite",
+    "shardSize": 25000,
     "hybrid": true,
     "rerank": false
   }
 }
 ```
 
-- `search.hybrid` defaults to enabled and merges full-text hits with semantic page matches when an embedding-capable provider is available
-- `search.rerank` optionally asks the current `queryProvider` to rerank the merged top hits before query answers are generated
+- `retrieval.hybrid` defaults to enabled and merges full-text hits with semantic page matches when an embedding-capable provider is available
+- `retrieval.rerank` optionally asks the current `queryProvider` to rerank the merged top hits before query answers are generated
+- `retrieval.backend` currently supports the local SQLite backend
 
 ## Troubleshooting
 

package/dist/index.js

@@ -15,11 +15,14 @@ import {
   autoCommitWikiChanges,
   benchmarkVault,
   blastRadiusVault,
+  buildContextPack,
   buildGraphShareArtifact,
   compileVault,
   consolidateVault,
   createSupersessionEdge,
+  deleteContextPack,
   deleteManagedSource,
+  doctorRetrieval,
   downloadWhisperModel,
   explainGraphVault,
   exploreVault,
@@ -28,7 +31,9 @@ import {
   exportGraphReportHtml,
   exportObsidianCanvas,
   exportObsidianVault,
+  finishMemoryTask,
   getGitHookStatus,
+  getRetrievalStatus,
   getWatchStatus,
   graphDiff,
   guideManagedSource,
@@ -42,9 +47,11 @@ import {
   lintVault,
   listApprovals,
   listCandidates,
+  listContextPacks,
   listGodNodes,
   listManagedSourceRecords,
   listManifests,
+  listMemoryTasks,
   listSchedules,
   listWatchedRoots,
   loadVaultConfig,
@@ -55,14 +62,20 @@ import {
   queryGraphVault,
   queryVault,
   readApproval,
+  readContextPack,
   readGraphReport,
+  readMemoryTask,
+  rebuildRetrievalIndex,
   registerLocalWhisperProvider,
   rejectApproval,
   reloadManagedSources,
   removeWatchedRoot,
+  renderContextPackLlms,
+  renderContextPackMarkdown,
   renderGraphShareBundleFiles,
   renderGraphShareMarkdown,
   renderGraphShareSvg,
+  resumeMemoryTask,
   resumeSourceSession,
   reviewManagedSource,
   reviewSourceScope,
@@ -73,8 +86,10 @@ import {
   serveSchedules,
   startGraphServer,
   startMcpServer,
+  startMemoryTask,
   summarizeLocalWhisperSetup,
   uninstallGitHooks,
+  updateMemoryTask,
   watchVault
 } from "@swarmvaultai/engine";
 import { Command, Option } from "commander";
@@ -293,9 +308,9 @@ program.name("swarmvault").description("SwarmVault is a local-first knowledge co
 function readCliVersion() {
   try {
     const packageJson = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
-    return typeof packageJson.version === "string" && packageJson.version.trim() ? packageJson.version : "1.4.0";
+    return typeof packageJson.version === "string" && packageJson.version.trim() ? packageJson.version : "3.1.0";
   } catch {
-    return "1.4.0";
+    return "3.1.0";
   }
 }
 function parsePositiveInt(value, fallback) {
@@ -374,8 +389,8 @@ async function maybeEmitHeuristicNotice(commandPath) {
   try {
     const { config } = await loadVaultConfig(process2.cwd());
     const analysisTaskKeys = ["compileProvider", "queryProvider", "lintProvider"];
-    const usingHeuristic = analysisTaskKeys.every((task) => {
-      const providerId = config.tasks[task];
+    const usingHeuristic = analysisTaskKeys.every((task2) => {
+      const providerId = config.tasks[task2];
       const providerConfig = config.providers[providerId];
       return !providerConfig || providerConfig.type === "heuristic";
     });
@@ -801,7 +816,7 @@ program.command("consolidate").description("Roll working-tier insights up into e
     log(decision);
   }
 });
-program.command("query").description("Query the compiled SwarmVault wiki.").argument("<question>", "Question to ask SwarmVault").option("--no-save", "Do not persist the answer to wiki/outputs").option("--commit", "Auto-commit wiki changes after query").option("--gap-fill", "Pull external web-search evidence when the local wiki has gaps (requires webSearch.tasks.queryProvider).").addOption(
+program.command("query").description("Query the compiled SwarmVault wiki.").argument("<question>", "Question to ask SwarmVault").option("--no-save", "Do not persist the answer to wiki/outputs").option("--commit", "Auto-commit wiki changes after query").option("--gap-fill", "Pull external web-search evidence when the local wiki has gaps (requires webSearch.tasks.queryProvider).").option("--task <id>", "Attach this query output to an agent task").option("--memory <id>", "Compatibility alias for --task").addOption(
   new Option("--format <format>", "Output format").choices(["markdown", "report", "slides", "chart", "image"]).default("markdown")
 ).action(
   async (question, options) => {
@@ -809,7 +824,8 @@ program.command("query").description("Query the compiled SwarmVault wiki.").argu
       question,
       save: options.save ?? true,
       format: options.format,
-      gapFill: options.gapFill ?? false
+      gapFill: options.gapFill ?? false,
+      memoryTaskId: options.task ?? options.memory
     });
     if (isJson()) {
       emitJson(result);
@@ -826,7 +842,235 @@ program.command("query").description("Query the compiled SwarmVault wiki.").argu
     await maybeEmitHeuristicNotice(["query"]);
   }
 );
-program.command("explore").description("Run a save-first multi-step exploration loop against the vault.").argument("<question>", "Root question to explore").option("--steps <n>", "Maximum number of exploration steps", "3").option("--gap-fill", "Pull external web-search evidence when the local wiki has gaps (requires webSearch.tasks.exploreProvider).").addOption(
+var context = program.command("context").description("Build and manage token-bounded agent context packs.");
+context.command("build").description("Build a cited, token-bounded context pack for an agent task.").argument("<goal>", "Task, question, or goal the agent needs context for").option("--target <target>", "Optional page, node, path, project, or label to anchor the pack").option("--budget <tokens>", "Approximate token budget for included context", String(8e3)).option("--task <id>", "Attach the context pack to an agent task").option("--memory <id>", "Compatibility alias for --task").addOption(new Option("--format <format>", "Output format").choices(["markdown", "json", "llms"]).default("markdown")).action(
+  async (goal, options) => {
+    const budgetTokens = parsePositiveInt(options.budget, 8e3);
+    const result = await buildContextPack(process2.cwd(), {
+      goal,
+      target: options.target,
+      budgetTokens,
+      format: options.format,
+      memoryTaskId: options.task ?? options.memory
+    });
+    if (isJson()) {
+      emitJson(result);
+      return;
+    }
+    log(result.rendered);
+    log(`Saved context pack to ${result.markdownPath}`);
+    log(`Saved context artifact to ${result.artifactPath}`);
+  }
+);
+context.command("list").description("List saved context packs.").action(async () => {
+  const packs = await listContextPacks(process2.cwd());
+  if (isJson()) {
+    emitJson(packs);
+    return;
+  }
+  if (!packs.length) {
+    log("No context packs.");
+    return;
+  }
+  for (const pack of packs) {
+    log(`${pack.id} \u2014 ${pack.goal} (${pack.itemCount} item(s), ${pack.omittedCount} omitted)`);
+  }
+});
+context.command("show").description("Print a saved context pack.").argument("<id>", "Context pack id").addOption(new Option("--format <format>", "Output format").choices(["markdown", "json", "llms"]).default("markdown")).action(async (id, options) => {
+  const pack = await readContextPack(process2.cwd(), id);
+  if (!pack) {
+    throw new Error(`Context pack not found: ${id}`);
+  }
+  if (isJson() || options.format === "json") {
+    emitJson(pack);
+    return;
+  }
+  log(options.format === "llms" ? renderContextPackLlms(pack) : renderContextPackMarkdown(pack));
+});
+context.command("delete").description("Delete a saved context pack artifact and markdown page.").argument("<id>", "Context pack id").action(async (id) => {
+  const deleted = await deleteContextPack(process2.cwd(), id);
+  if (!deleted) {
+    throw new Error(`Context pack not found: ${id}`);
+  }
+  if (isJson()) {
+    emitJson(deleted);
+    return;
+  }
+  log(`Deleted context pack ${deleted.id}.`);
+});
+var memory = program.command("memory").description("Manage git-backed agent memory task ledger entries.");
+memory.command("start").description("Start a durable agent memory task and build its initial context pack.").argument("<goal>", "Task goal to preserve in agent memory").option("--target <target>", "Optional page, node, path, project, or label to anchor the initial context pack").option("--budget <tokens>", "Approximate token budget for the initial context pack", String(8e3)).option("--agent <name>", "Agent name to record on the task").option("--context-pack <id>", "Attach an existing context pack instead of building a new one").action(async (goal, options) => {
+  const result = await startMemoryTask(process2.cwd(), {
+    goal,
+    target: options.target,
+    budgetTokens: parsePositiveInt(options.budget, 8e3),
+    agent: options.agent,
+    contextPackId: options.contextPack
+  });
+  if (isJson()) {
+    emitJson(result);
+    return;
+  }
+  log(result.task.id);
+  log(`Saved memory task to ${result.markdownPath}`);
+});
+memory.command("update").description("Append a note, decision, path, context pack, or status change to a memory task.").argument("<id>", "Memory task id").option("--note <text>", "Append a task note").option("--decision <text>", "Append a decision").option("--changed-path <path>", "Record a changed file or wiki path").option("--context-pack <id>", "Attach a context pack").option("--session <id>", "Attach a session id").option("--source <id>", "Attach a source id").option("--page <id>", "Attach a page id").option("--node <id>", "Attach a graph node id").option("--git-ref <ref>", "Attach a git ref").addOption(new Option("--status <status>", "Task status").choices(["active", "blocked", "completed", "archived"])).action(
+  async (id, options) => {
+    const result = await updateMemoryTask(process2.cwd(), id, {
+      note: options.note,
+      decision: options.decision,
+      changedPath: options.changedPath,
+      contextPackId: options.contextPack,
+      sessionId: options.session,
+      sourceId: options.source,
+      pageId: options.page,
+      nodeId: options.node,
+      gitRef: options.gitRef,
+      status: options.status
+    });
+    if (isJson()) {
+      emitJson(result);
+      return;
+    }
+    log(`Updated memory task ${result.task.id}.`);
+  }
+);
+memory.command("finish").description("Finish a memory task with an outcome and optional follow-up.").argument("<id>", "Memory task id").requiredOption("--outcome <text>", "Outcome to record").option("--follow-up <text>", "Follow-up to preserve for the next agent").action(async (id, options) => {
+  const result = await finishMemoryTask(process2.cwd(), id, {
+    outcome: options.outcome,
+    followUp: options.followUp
+  });
+  if (isJson()) {
+    emitJson(result);
+    return;
+  }
+  log(`Finished memory task ${result.task.id}.`);
+});
+memory.command("list").description("List saved agent memory tasks.").action(async () => {
+  const tasks = await listMemoryTasks(process2.cwd());
+  if (isJson()) {
+    emitJson(tasks);
+    return;
+  }
+  if (!tasks.length) {
+    log("No memory tasks.");
+    return;
+  }
+  for (const task2 of tasks) {
+    log(`${task2.id} \u2014 ${task2.status} \u2014 ${task2.goal}`);
+  }
+});
+memory.command("show").description("Print a saved agent memory task.").argument("<id>", "Memory task id").action(async (id) => {
+  const task2 = await readMemoryTask(process2.cwd(), id);
+  if (!task2) {
+    throw new Error(`Memory task not found: ${id}`);
+  }
+  if (isJson()) {
+    emitJson(task2);
+    return;
+  }
+  log(`Task: ${task2.title}`);
+  log(`Status: ${task2.status}`);
+  log(`Goal: ${task2.goal}`);
+  if (task2.outcome) log(`Outcome: ${task2.outcome}`);
+  if (task2.followUps.length) log(`Follow-ups: ${task2.followUps.join("; ")}`);
+  log(`Markdown: ${task2.markdownPath}`);
+});
+memory.command("resume").description("Render a memory task handoff for the next agent.").argument("<id>", "Memory task id").addOption(new Option("--format <format>", "Output format").choices(["markdown", "json", "llms"]).default("markdown")).action(async (id, options) => {
+  const result = await resumeMemoryTask(process2.cwd(), id, { format: options.format });
+  if (isJson() || options.format === "json") {
+    emitJson(result);
+    return;
+  }
+  log(result.rendered);
+});
+var task = program.command("task").description("Manage git-backed agent task ledger entries.");
+task.command("start").description("Start a durable agent task and build its initial context pack.").argument("<goal>", "Task goal to preserve").option("--target <target>", "Optional page, node, path, project, or label to anchor the initial context pack").option("--budget <tokens>", "Approximate token budget for the initial context pack", String(8e3)).option("--agent <name>", "Agent name to record on the task").option("--context-pack <id>", "Attach an existing context pack instead of building a new one").action(async (goal, options) => {
+  const result = await startMemoryTask(process2.cwd(), {
+    goal,
+    target: options.target,
+    budgetTokens: parsePositiveInt(options.budget, 8e3),
+    agent: options.agent,
+    contextPackId: options.contextPack
+  });
+  if (isJson()) {
+    emitJson(result);
+    return;
+  }
+  log(result.task.id);
+  log(`Saved task to ${result.markdownPath}`);
+});
+task.command("update").description("Append a note, decision, path, context pack, or status change to a task.").argument("<id>", "Task id").option("--note <text>", "Append a task note").option("--decision <text>", "Append a decision").option("--changed-path <path>", "Record a changed file or wiki path").option("--context-pack <id>", "Attach a context pack").option("--session <id>", "Attach a session id").option("--source <id>", "Attach a source id").option("--page <id>", "Attach a page id").option("--node <id>", "Attach a graph node id").option("--git-ref <ref>", "Attach a git ref").addOption(new Option("--status <status>", "Task status").choices(["active", "blocked", "completed", "archived"])).action(
+  async (id, options) => {
+    const result = await updateMemoryTask(process2.cwd(), id, {
+      note: options.note,
+      decision: options.decision,
+      changedPath: options.changedPath,
+      contextPackId: options.contextPack,
+      sessionId: options.session,
+      sourceId: options.source,
+      pageId: options.page,
+      nodeId: options.node,
+      gitRef: options.gitRef,
+      status: options.status
+    });
+    if (isJson()) {
+      emitJson(result);
+      return;
+    }
+    log(`Updated task ${result.task.id}.`);
+  }
+);
+task.command("finish").description("Finish a task with an outcome and optional follow-up.").argument("<id>", "Task id").requiredOption("--outcome <text>", "Outcome to record").option("--follow-up <text>", "Follow-up to preserve for the next agent").action(async (id, options) => {
+  const result = await finishMemoryTask(process2.cwd(), id, {
+    outcome: options.outcome,
+    followUp: options.followUp
+  });
+  if (isJson()) {
+    emitJson(result);
+    return;
+  }
+  log(`Finished task ${result.task.id}.`);
+});
+task.command("list").description("List saved agent tasks.").action(async () => {
+  const tasks = await listMemoryTasks(process2.cwd());
+  if (isJson()) {
+    emitJson(tasks);
+    return;
+  }
+  if (!tasks.length) {
+    log("No tasks.");
+    return;
+  }
+  for (const entry of tasks) {
+    log(`${entry.id} \u2014 ${entry.status} \u2014 ${entry.goal}`);
+  }
+});
+task.command("show").description("Print a saved agent task.").argument("<id>", "Task id").action(async (id) => {
+  const entry = await readMemoryTask(process2.cwd(), id);
+  if (!entry) {
+    throw new Error(`Task not found: ${id}`);
+  }
+  if (isJson()) {
+    emitJson(entry);
+    return;
+  }
+  log(`Task: ${entry.title}`);
+  log(`Status: ${entry.status}`);
+  log(`Goal: ${entry.goal}`);
+  if (entry.outcome) log(`Outcome: ${entry.outcome}`);
+  if (entry.followUps.length) log(`Follow-ups: ${entry.followUps.join("; ")}`);
+  log(`Markdown: ${entry.markdownPath}`);
+});
+task.command("resume").description("Render a task handoff for the next agent.").argument("<id>", "Task id").addOption(new Option("--format <format>", "Output format").choices(["markdown", "json", "llms"]).default("markdown")).action(async (id, options) => {
+  const result = await resumeMemoryTask(process2.cwd(), id, { format: options.format });
+  if (isJson() || options.format === "json") {
+    emitJson(result);
+    return;
+  }
+  log(result.rendered);
+});
+program.command("explore").description("Run a save-first multi-step exploration loop against the vault.").argument("<question>", "Root question to explore").option("--steps <n>", "Maximum number of exploration steps", "3").option("--gap-fill", "Pull external web-search evidence when the local wiki has gaps (requires webSearch.tasks.exploreProvider).").option("--task <id>", "Attach this exploration to an agent task").option("--memory <id>", "Compatibility alias for --task").addOption(
   new Option("--format <format>", "Output format for step pages").choices(["markdown", "report", "slides", "chart", "image"]).default("markdown")
 ).action(
   async (question, options) => {
@@ -835,7 +1079,8 @@ program.command("explore").description("Run a save-first multi-step exploration
       question,
       steps: stepCount,
       format: options.format,
-      gapFill: options.gapFill ?? false
+      gapFill: options.gapFill ?? false,
+      memoryTaskId: options.task ?? options.memory
     });
     if (isJson()) {
       emitJson(result);
@@ -1468,7 +1713,7 @@ program.command("mcp").description("Run SwarmVault as a local MCP server over st
 });
 program.command("install").description("Install SwarmVault instructions for an agent in the current project.").requiredOption(
   "--agent <agent>",
-  "codex, claude, cursor, goose, pi, gemini, opencode, aider, copilot, trae, claw, droid, kiro, hermes, antigravity, or vscode"
+  "claude, codex, cursor, gemini, goose, opencode, copilot, aider, droid, pi, trae, claw, kiro, hermes, antigravity, vscode, amp, augment, adal, bob, cline, codebuddy, command-code, continue, cortex, crush, deepagents, firebender, iflow, junie, kilo-code, kimi, kode, mcpjam, mistral-vibe, mux, neovate, openclaw, openhands, pochi, qoder, qwen-code, replit, roo-code, trae-cn, warp, windsurf, or zencoder"
 ).option("--hook", "Also install hook/plugin guidance when the target agent supports it", false).action(
   async (options) => {
     const hookCapableAgents = /* @__PURE__ */ new Set(["claude", "opencode", "gemini", "copilot"]);
@@ -1768,6 +2013,49 @@ program.command("diff").description("Show what changed in the knowledge graph si
     }
   }
 });
+var retrieval = program.command("retrieval").description("Inspect and repair the local retrieval index.");
+retrieval.command("status").description("Show retrieval index health and configuration.").action(async () => {
+  const status = await getRetrievalStatus(process2.cwd());
+  if (isJson()) {
+    emitJson(status);
+    return;
+  }
+  log(`Retrieval backend: ${status.configured.backend}`);
+  log(`Index: ${status.indexExists ? "present" : "missing"} (${status.indexPath})`);
+  log(`Manifest: ${status.manifestExists ? "present" : "missing"} (${status.manifestPath})`);
+  log(`Graph: ${status.graphExists ? "present" : "missing"}`);
+  log(`Pages indexed: ${status.pageCount}`);
+  log(`State: ${status.stale ? "stale" : "fresh"}`);
+  for (const warning of status.warnings) {
+    log(`Warning: ${warning}`);
+  }
+});
+retrieval.command("rebuild").description("Rebuild the local retrieval index from the current graph.").action(async () => {
+  const status = await rebuildRetrievalIndex(process2.cwd());
+  if (isJson()) {
+    emitJson(status);
+    return;
+  }
+  log(`Rebuilt retrieval index at ${status.indexPath}`);
+  log(`Pages indexed: ${status.pageCount}`);
+});
+retrieval.command("doctor").description("Diagnose retrieval index problems and optionally repair them.").option("--repair", "Rebuild stale or missing retrieval artifacts", false).action(async (options) => {
+  const result = await doctorRetrieval(process2.cwd(), { repair: options.repair });
+  if (isJson()) {
+    emitJson(result);
+    return;
+  }
+  log(`Retrieval health: ${result.ok ? "ok" : "needs attention"}`);
+  if (result.repaired) {
+    log("Repaired retrieval index.");
+  }
+  if (result.actions.length) {
+    log(`Suggested action(s): ${result.actions.join(", ")}`);
+  }
+  for (const warning of result.status.warnings) {
+    log(`Warning: ${warning}`);
+  }
+});
 program.command("scan").description("Quick-start: initialize, ingest, compile, and serve a graph viewer in one command.").argument("<directory>", "Directory to scan").option("--port <port>", "Port for the graph viewer").option("--no-serve", "Skip launching the graph viewer after compile").action(async (directory, options) => {
   const rootDir = process2.cwd();
   await initVault(rootDir, {});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmvaultai/cli",
-  "version": "1.4.0",
+  "version": "3.1.0",
   "description": "Global CLI for SwarmVault.",
   "type": "module",
   "main": "dist/index.js",
@@ -38,7 +38,7 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@swarmvaultai/engine": "1.4.0",
+    "@swarmvaultai/engine": "3.1.0",
     "commander": "^14.0.1"
   },
   "devDependencies": {