@swarmvaultai/cli 1.3.0 → 3.0.0

package/README.md

@@ -41,8 +41,12 @@ swarmvault compile --max-tokens 120000
 swarmvault diff
 swarmvault graph share --post
 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
@@ -87,7 +91,7 @@ Quick-start a scratch vault from a local directory in one command.
 - initializes the current directory as a SwarmVault workspace
 - ingests the supplied directory as local sources
 - compiles the vault immediately
-- writes `wiki/graph/share-card.md` and `wiki/graph/share-card.svg`, then prints both paths
+- writes `wiki/graph/share-card.md`, `wiki/graph/share-card.svg`, and `wiki/graph/share-kit/`, then prints the paths
 - starts `graph serve` unless you pass `--no-serve`
 - respects `--port` when you want a specific viewer port
 
@@ -100,7 +104,7 @@ Create a temporary sample vault with bundled sources, compile it immediately, an
 - writes the demo vault under the system temp directory
 - requires no API keys or extra setup
 - is the fastest way to inspect the full init + ingest + compile + graph workflow on a clean machine
-- writes `wiki/graph/share-card.md` and `wiki/graph/share-card.svg` inside the demo vault
+- writes `wiki/graph/share-card.md`, `wiki/graph/share-card.svg`, and `wiki/graph/share-kit/` inside the demo vault
 - respects `--port` when you want a specific viewer port
 
 ### `swarmvault diff`
@@ -210,8 +214,8 @@ Compile the current manifests into:
 
 - generated markdown in `wiki/`
 - structured graph data in `state/graph.json`
-- local search data in `state/search.sqlite`
-- share cards at `wiki/graph/share-card.md` and `wiki/graph/share-card.svg`
+- 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.
 
@@ -269,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]`
 
@@ -344,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`
 
@@ -371,14 +427,15 @@ Inspect graph metadata, community membership, neighbors, provenance, and group-p
 
 List the most connected bridge-heavy nodes in the current graph.
 
-### `swarmvault graph share [--post] [--svg [path]]`
+### `swarmvault graph share [--post] [--svg [path]] [--bundle [dir]]`
 
 Print a shareable summary of the compiled graph.
 
 - default output is the same markdown shape written to `wiki/graph/share-card.md`
 - `--post` prints only the concise social-post text
 - `--svg [path]` writes the 1200x630 visual share card, defaulting to `wiki/graph/share-card.svg`
-- `--json` emits the structured share artifact for automation; with `--svg`, it also includes `svgPath`
+- `--bundle [dir]` writes `share-card.md`, `share-post.txt`, `share-card.svg`, `share-preview.html`, and `share-artifact.json`, defaulting to `wiki/graph/share-kit`
+- `--json` emits the structured share artifact for automation; with `--svg`, it also includes `svgPath`; with `--bundle`, it includes `bundlePath` and named output paths
 - useful immediately after `swarmvault scan`, `swarmvault demo`, or a normal compile
 
 ### `swarmvault graph blast <target> [--depth <n>]`
@@ -537,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,13 +62,20 @@ import {
   queryGraphVault,
   queryVault,
   readApproval,
+  readContextPack,
   readGraphReport,
+  readMemoryTask,
+  rebuildRetrievalIndex,
   registerLocalWhisperProvider,
   rejectApproval,
   reloadManagedSources,
   removeWatchedRoot,
+  renderContextPackLlms,
+  renderContextPackMarkdown,
+  renderGraphShareBundleFiles,
   renderGraphShareMarkdown,
   renderGraphShareSvg,
+  resumeMemoryTask,
   resumeSourceSession,
   reviewManagedSource,
   reviewSourceScope,
@@ -72,8 +86,10 @@ import {
   serveSchedules,
   startGraphServer,
   startMcpServer,
+  startMemoryTask,
   summarizeLocalWhisperSetup,
   uninstallGitHooks,
+  updateMemoryTask,
   watchVault
 } from "@swarmvaultai/engine";
 import { Command, Option } from "commander";
@@ -292,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.3.0";
+    return typeof packageJson.version === "string" && packageJson.version.trim() ? packageJson.version : "3.0.0";
   } catch {
-    return "1.3.0";
+    return "3.0.0";
   }
 }
 function parsePositiveInt(value, fallback) {
@@ -348,6 +364,20 @@ function log(message) {
 `);
   }
 }
+async function writeShareBundle(bundlePath, files) {
+  await mkdir2(bundlePath, { recursive: true });
+  const bundleFiles = {
+    markdownPath: path2.join(bundlePath, "share-card.md"),
+    postPath: path2.join(bundlePath, "share-post.txt"),
+    svgPath: path2.join(bundlePath, "share-card.svg"),
+    previewHtmlPath: path2.join(bundlePath, "share-preview.html"),
+    artifactJsonPath: path2.join(bundlePath, "share-artifact.json")
+  };
+  for (const file of files) {
+    await writeFile2(path2.join(bundlePath, file.relativePath), file.content, "utf8");
+  }
+  return bundleFiles;
+}
 function emitNotice(message) {
   process2.stderr.write(`[swarmvault] ${message}
 `);
@@ -359,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";
     });
@@ -786,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) => {
@@ -794,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);
@@ -811,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) => {
@@ -820,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);
@@ -976,9 +1236,10 @@ graph.command("export").description(
     }
   }
 );
-graph.command("share").description("Print a shareable summary of the compiled graph.").option("--post", "Print only the short social post text", false).option("--svg [path]", "Write the visual SVG share card, defaulting to wiki/graph/share-card.svg").action(async (options) => {
-  if (options.post && options.svg) {
-    throw new Error("Choose either --post or --svg, not both.");
+graph.command("share").description("Print a shareable summary of the compiled graph.").option("--post", "Print only the short social post text", false).option("--svg [path]", "Write the visual SVG share card, defaulting to wiki/graph/share-card.svg").option("--bundle [dir]", "Write the portable share kit bundle, defaulting to wiki/graph/share-kit").action(async (options) => {
+  const outputModeCount = [options.post, options.svg, options.bundle].filter(Boolean).length;
+  if (outputModeCount > 1) {
+    throw new Error("Choose one graph share output mode: --post, --svg, or --bundle.");
   }
   const { paths } = await loadVaultConfig(process2.cwd());
   const raw = await readFile2(paths.graphPath, "utf-8");
@@ -1000,6 +1261,16 @@ graph.command("share").description("Print a shareable summary of the compiled gr
     log(`Wrote SVG share card to ${svgPath}`);
     return;
   }
+  if (options.bundle) {
+    const bundlePath = typeof options.bundle === "string" ? path2.resolve(process2.cwd(), options.bundle) : path2.join(paths.wikiDir, "graph", "share-kit");
+    const bundleFiles = await writeShareBundle(bundlePath, renderGraphShareBundleFiles(artifact));
+    if (isJson()) {
+      emitJson({ ...artifact, bundlePath, bundleFiles });
+      return;
+    }
+    log(`Wrote share kit to ${bundlePath}`);
+    return;
+  }
   if (isJson()) {
     emitJson(artifact);
     return;
@@ -1568,6 +1839,7 @@ program.command("demo").description("Try SwarmVault with a bundled sample vault
   const { paths } = await loadVaultConfig(demoDir);
   const shareCardPath = path3.join(demoDir, "wiki", "graph", "share-card.md");
   const shareCardSvgPath = path3.join(demoDir, "wiki", "graph", "share-card.svg");
+  const shareKitPath = path3.join(demoDir, "wiki", "graph", "share-kit");
   let graphStats = "";
   try {
     const raw = await readFile2(paths.graphPath, "utf-8");
@@ -1587,6 +1859,7 @@ program.command("demo").description("Try SwarmVault with a bundled sample vault
     log(`Vault location: ${demoDir}`);
     log(`Share card: ${shareCardPath}`);
     log(`Visual card: ${shareCardSvgPath}`);
+    log(`Share kit: ${shareKitPath}`);
   }
   if (options.serve !== false) {
     const port = options.port ? parsePositiveInt(options.port, 0) || void 0 : void 0;
@@ -1597,6 +1870,7 @@ program.command("demo").description("Try SwarmVault with a bundled sample vault
         graphStats: graphStats.trim(),
         shareCardPath,
         shareCardSvgPath,
+        shareKitPath,
         port: server.port,
         url: `http://localhost:${server.port}`
       });
@@ -1617,7 +1891,7 @@ program.command("demo").description("Try SwarmVault with a bundled sample vault
       process2.exit(0);
     });
   } else if (isJson()) {
-    emitJson({ demoDir, graphStats: graphStats.trim(), shareCardPath, shareCardSvgPath });
+    emitJson({ demoDir, graphStats: graphStats.trim(), shareCardPath, shareCardSvgPath, shareKitPath });
   } else {
     log("");
     log("Try next:");
@@ -1739,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, {});
@@ -1752,17 +2069,27 @@ program.command("scan").description("Quick-start: initialize, ingest, compile, a
   const compiled = await compileVault(rootDir, {});
   const shareCardPath = path2.join(rootDir, "wiki", "graph", "share-card.md");
   const shareCardSvgPath = path2.join(rootDir, "wiki", "graph", "share-card.svg");
+  const shareKitPath = path2.join(rootDir, "wiki", "graph", "share-kit");
   if (!isJson()) {
     log(`Compiled ${compiled.sourceCount} source(s), ${compiled.pageCount} page(s).`);
     log(`Share card: ${shareCardPath}`);
     log(`Visual card: ${shareCardSvgPath}`);
+    log(`Share kit: ${shareKitPath}`);
     log("Post text: swarmvault graph share --post");
   }
   if (options.serve !== false) {
     const port = options.port ? parsePositiveInt(options.port, 0) || void 0 : void 0;
     const server = await startGraphServer(rootDir, port, { full: false });
     if (isJson()) {
-      emitJson({ ...result, compiled, shareCardPath, shareCardSvgPath, port: server.port, url: `http://localhost:${server.port}` });
+      emitJson({
+        ...result,
+        compiled,
+        shareCardPath,
+        shareCardSvgPath,
+        shareKitPath,
+        port: server.port,
+        url: `http://localhost:${server.port}`
+      });
     } else {
       log(`Graph viewer running at http://localhost:${server.port}`);
     }
@@ -1774,7 +2101,7 @@ program.command("scan").description("Quick-start: initialize, ingest, compile, a
       process2.exit(0);
     });
   } else if (isJson()) {
-    emitJson({ ...result, compiled, shareCardPath, shareCardSvgPath });
+    emitJson({ ...result, compiled, shareCardPath, shareCardSvgPath, shareKitPath });
   }
 });
 function enableStructuredJsonOnSubcommands(command) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmvaultai/cli",
-  "version": "1.3.0",
+  "version": "3.0.0",
   "description": "Global CLI for SwarmVault.",
   "type": "module",
   "main": "dist/index.js",
@@ -44,7 +44,7 @@
     "prepublishOnly": "node ../../scripts/check-release-sync.mjs && node ../../scripts/check-published-manifests.mjs"
   },
   "dependencies": {
-    "@swarmvaultai/engine": "1.3.0",
+    "@swarmvaultai/engine": "3.0.0",
     "commander": "^14.0.1"
   },
   "devDependencies": {