@swarmvaultai/cli 3.10.0 → 3.12.0

package/README.md

@@ -56,6 +56,9 @@ swarmvault graph share --svg ./share-card.svg
 swarmvault graph share --bundle ./share-kit
 swarmvault benchmark
 swarmvault query "What keeps recurring?" --commit
+swarmvault chat "What should the next agent know?"
+swarmvault chat --resume <session-id> "What changed?"
+swarmvault export ai --out ./exports/ai
 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
@@ -73,6 +76,7 @@ swarmvault update .
 swarmvault graph cluster
 swarmvault cluster-only
 swarmvault graph tree --output ./exports/tree.html
+swarmvault tree --output ./exports/tree.html
 swarmvault graph query "Which nodes bridge the biggest clusters?"
 swarmvault graph explain "concept:drift"
 swarmvault watch status
@@ -84,7 +88,9 @@ swarmvault graph export --html ./exports/graph.html
 swarmvault graph export --cypher ./exports/graph.cypher
 swarmvault graph export --neo4j ./exports/graph.cypher
 swarmvault graph merge ./exports/graph.json ./other-graph.json --out ./exports/merged-graph.json
+swarmvault merge-graphs ./exports/graph.json ./other-graph.json --out ./exports/merged-graph.json
 swarmvault graph push neo4j --dry-run
+swarmvault clone https://github.com/owner/repo --no-viz
 ```
 
 ## Commands
@@ -110,7 +116,7 @@ Set `SWARMVAULT_OUT=<dir>` when generated artifacts should be isolated from the
 
 `--profile` accepts `default`, `personal-research`, or a comma-separated preset list such as `reader,timeline`. For fully custom vault behavior, edit the `profile` block in `swarmvault.config.json`; that deterministic profile layer works alongside the human-written `swarmvault.schema.md`. The `personal-research` preset also sets `profile.guidedIngestDefault: true` and `profile.deepLintDefault: true`, so guided ingest/source and lint flows are on by default until you override them with `--no-guide` or `--no-deep`.
 
-### `swarmvault scan <directory|github-url> [--port <port>] [--no-serve] [--branch <name>] [--ref <ref>] [--checkout-dir <path>]`
+### `swarmvault scan <directory|github-url> [--port <port>] [--no-serve] [--no-viz] [--mcp] [--branch <name>] [--ref <ref>] [--checkout-dir <path>]`
 
 Quick-start a scratch vault from a local directory or public GitHub repo root URL in one command.
 
@@ -118,12 +124,22 @@ Quick-start a scratch vault from a local directory or public GitHub repo root UR
 - ingests the supplied directory as local sources, or registers/syncs the supplied public GitHub repo root URL
 - compiles the vault immediately
 - 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`
+- starts `graph serve` unless you pass `--no-serve` or `--no-viz`
+- `--no-viz` is a compatibility alias for `--no-serve`
+- `--mcp` starts the MCP stdio server after compile instead of the graph viewer
 - respects `--port` when you want a specific viewer port
 - for GitHub repo URLs, supports `--branch`, `--ref`, and `--checkout-dir`
 
 Use this when you want the fastest repo or docs-tree walkthrough without first deciding on managed-source registration.
 
+### `swarmvault clone <directory|github-url> [--no-viz] [--mcp] [--branch <name>] [--ref <ref>] [--checkout-dir <path>]`
+
+Compatibility alias for `swarmvault scan`.
+
+- initializes, ingests or registers the input, and compiles in one command
+- supports the same public GitHub repo checkout flags as `scan`
+- accepts `--no-serve`, `--no-viz`, `--mcp`, and `--port`
+
 ### `swarmvault demo [--port <port>] [--no-serve]`
 
 Create a temporary sample vault with bundled sources, compile it immediately, and launch the graph viewer unless you pass `--no-serve`.
@@ -142,6 +158,28 @@ Compare the current `state/graph.json` against the last committed graph in git.
 - when no git baseline exists, falls back to a summary of the current graph state
 - supports `--json` for structured automation output
 
+### `swarmvault chat [question...] [--resume [id]] [--list] [--delete <id>]`
+
+Ask the compiled wiki in a persisted multi-turn session.
+
+- without a question, opens an interactive TTY chat loop with `/help`, `/sessions`, `/status`, `/clear`, and `/exit`
+- with a question, runs one turn and persists the transcript under `wiki/outputs/chat-sessions/`
+- stores structured session state under `state/chat-sessions/`
+- `--resume <id>` resumes by id or unique prefix; `--resume` alone resumes the most recent session
+- `--list` prints saved sessions and `--delete <id>` removes one
+- `--save-output` also writes each turn as a regular `wiki/outputs/` query page
+- supports `--format markdown|report|slides|chart|image`, `--gap-fill`, and global `--json`
+
+### `swarmvault export ai [--out <dir>] [--max-full-chars <n>] [--no-page-siblings]`
+
+Write a static AI handoff pack for agents, crawlers, and documentation systems.
+
+- defaults to `wiki/exports/ai/`
+- writes `llms.txt`, `llms-full.txt`, `graph.jsonld`, `manifest.json`, and `ai-readme.md`
+- writes per-page `.txt` and `.json` siblings under `pages/` unless `--no-page-siblings` is passed
+- caps `llms-full.txt` with `--max-full-chars` so huge vaults stay bounded
+- includes SHA-256 hashes and file metadata in `manifest.json`
+
 ### `swarmvault doctor [--repair]`
 
 Run a whole-vault health check before handing the workspace to an agent or opening the live viewer.
@@ -440,6 +478,13 @@ Write a collapsible HTML source tree for the current `state/graph.json`.
 - `--max-children` caps very wide folders or modules with a `+N more` row
 - `--json` returns the output path, source count, node count, and tree payload
 
+### `swarmvault tree [--output <html>] [--root <path>] [--label <name>] [--max-children <n>]`
+
+Compatibility alias for `swarmvault graph tree`.
+
+- writes the same source/module/symbol tree
+- returns the same JSON shape as `graph tree`
+
 ### `swarmvault graph merge <graph...> --out <path> [--label <name>]`
 
 Merge multiple graph JSON files into one namespaced graph artifact.
@@ -450,6 +495,13 @@ Merge multiple graph JSON files into one namespaced graph artifact.
 - maps explicit extracted/inferred/ambiguous edge evidence into SwarmVault edge semantics
 - `--json` returns the merged graph, input summaries, and warnings
 
+### `swarmvault merge-graphs <graph...> --out <path> [--label <name>]`
+
+Compatibility alias for `swarmvault graph merge`.
+
+- accepts the same SwarmVault and NetworkX/node-link graph inputs
+- returns the same JSON shape as `graph merge`
+
 ### `swarmvault graph status [path]`
 
 Read-only graph freshness check for tracked repo roots or one explicit repo path.
@@ -461,6 +513,15 @@ Read-only graph freshness check for tracked repo roots or one explicit repo path
 - recommends `swarmvault compile` when graph/report artifacts are missing, non-code files changed, or a semantic refresh is pending
 - supports global `--json` for automation
 
+### `swarmvault watch [path] [--once] [--code-only] [--lint]`
+
+Watch or refresh one explicit repo root without first writing `watch.repoRoots`.
+
+- positional `[path]` is treated as a repo-root override and turns on repo mode
+- `--once` runs one refresh cycle and exits
+- `--code-only` limits the refresh to parser-backed repo graph artifacts
+- repeated `--root <path>` remains available when you need multiple roots
+
 ### `swarmvault graph stats`
 
 Summarize the current compiled graph without opening the viewer.

package/dist/index.js

@@ -12,6 +12,7 @@ import {
   addManagedSource,
   addWatchedRoot,
   archiveCandidate,
+  askChatSession,
   autoCommitWikiChanges,
   benchmarkVault,
   blastRadiusVault,
@@ -20,6 +21,7 @@ import {
   compileVault,
   consolidateVault,
   createSupersessionEdge,
+  deleteChatSession,
   deleteContextPack,
   deleteManagedSource,
   doctorRetrieval,
@@ -27,6 +29,7 @@ import {
   downloadWhisperModel,
   explainGraphVault,
   exploreVault,
+  exportAiPack,
   exportGraphFormat,
   exportGraphHtml,
   exportGraphReportHtml,
@@ -51,6 +54,7 @@ import {
   lintVault,
   listApprovals,
   listCandidates,
+  listChatSessions,
   listContextPacks,
   listGodNodes,
   listManagedSourceRecords,
@@ -315,9 +319,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 : "3.10.0";
+    return typeof packageJson.version === "string" && packageJson.version.trim() ? packageJson.version : "3.12.0";
   } catch {
-    return "3.10.0";
+    return "3.12.0";
   }
 }
 function parsePositiveInt(value, fallback) {
@@ -545,6 +549,209 @@ async function runGraphClusterCommand(options, rootDir = process2.cwd()) {
     `Refreshed ${result.communityCount} communities across ${result.nodeCount} nodes and ${result.edgeCount} edges. Report: ${result.reportPath}`
   );
 }
+async function runGraphTreeCommand(options) {
+  const rootDir = options.root ? path2.resolve(process2.cwd(), options.root) : process2.cwd();
+  const result = await exportGraphTree(rootDir, options.output, {
+    label: options.label,
+    maxChildren: parsePositiveInt(options.maxChildren, 250)
+  });
+  if (isJson()) {
+    emitJson(result);
+    return;
+  }
+  log(`Graph tree: ${result.outputPath}`);
+  log(`Sources: ${result.sourceCount}; nodes: ${result.nodeCount}.`);
+}
+async function runGraphMergeCommand(graphPaths, options) {
+  const result = await mergeGraphFiles(
+    graphPaths.map((inputPath) => path2.resolve(process2.cwd(), inputPath)),
+    path2.resolve(process2.cwd(), options.out),
+    { label: options.label }
+  );
+  if (isJson()) {
+    emitJson(result);
+    return;
+  }
+  log(
+    `Merged ${result.inputGraphs.length} graph${result.inputGraphs.length === 1 ? "" : "s"} into ${result.outputPath}. Nodes ${result.graph.nodes.length}, edges ${result.graph.edges.length}.`
+  );
+  for (const warning of result.warnings) {
+    log(`Warning: ${warning}`);
+  }
+}
+async function runScanCommand(input, options) {
+  const rootDir = process2.cwd();
+  await initVault(rootDir, {});
+  if (!isJson()) {
+    log("Initialized workspace.");
+  }
+  const result = isHttpUrlInput(input) ? await addManagedSource(rootDir, input, {
+    compile: true,
+    brief: false,
+    branch: options.branch,
+    ref: options.ref,
+    checkoutDir: options.checkoutDir
+  }) : await ingestDirectory(rootDir, input, {});
+  if (!isJson()) {
+    if ("source" in result) {
+      log(
+        `Registered ${result.source.kind} source ${result.source.id}. Imported ${result.source.lastSyncCounts?.importedCount ?? 0}, updated ${result.source.lastSyncCounts?.updatedCount ?? 0}.`
+      );
+    } else {
+      log(`Ingested ${result.imported.length} file(s).`);
+    }
+  }
+  const compiled = "compile" in result && result.compile ? result.compile : await compileVault(rootDir, {});
+  const { paths } = await loadVaultConfig(rootDir);
+  const shareCardPath = path2.join(paths.wikiDir, "graph", "share-card.md");
+  const shareCardSvgPath = path2.join(paths.wikiDir, "graph", "share-card.svg");
+  const shareKitPath = path2.join(paths.wikiDir, "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.mcp) {
+    process2.stderr.write(`${JSON.stringify({ status: "running", transport: "stdio", compiled: compiled.sourceCount })}
+`);
+    const controller = await startMcpServer(rootDir);
+    process2.on("SIGINT", async () => {
+      try {
+        await controller.close();
+      } catch {
+      }
+      process2.exit(0);
+    });
+    return;
+  }
+  if (options.serve !== false && options.viz !== 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,
+        shareKitPath,
+        port: server.port,
+        url: `http://localhost:${server.port}`
+      });
+    } else {
+      log(`Graph viewer running at http://localhost:${server.port}`);
+    }
+    process2.on("SIGINT", async () => {
+      try {
+        await server.close();
+      } catch {
+      }
+      process2.exit(0);
+    });
+  } else if (isJson()) {
+    emitJson({ ...result, compiled, shareCardPath, shareCardSvgPath, shareKitPath });
+  }
+}
+async function resolveChatResumeId(resume) {
+  if (!resume) {
+    return void 0;
+  }
+  if (typeof resume === "string") {
+    return resume;
+  }
+  const sessions = await listChatSessions(process2.cwd());
+  return sessions[0]?.id;
+}
+function logChatSessions(sessions) {
+  if (!sessions.length) {
+    log("No chat sessions yet.");
+    return;
+  }
+  for (const session of sessions) {
+    log(`${session.id}  ${session.turnCount} turn${session.turnCount === 1 ? "" : "s"}  ${session.title}`);
+    log(`  updated: ${session.updatedAt}`);
+    log(`  markdown: ${session.markdownPath}`);
+  }
+}
+async function runChatQuestion(question, options) {
+  const sessionId = await resolveChatResumeId(options.resume);
+  return askChatSession(process2.cwd(), {
+    question,
+    sessionId,
+    saveOutput: options.saveOutput ?? false,
+    gapFill: options.gapFill ?? false,
+    format: options.format,
+    maxHistoryTurns: parsePositiveInt(options.maxHistoryTurns, 6)
+  });
+}
+async function runInteractiveChat(options) {
+  if (isJson()) {
+    throw new Error("Interactive chat is not available with --json. Pass a question for one-shot JSON output.");
+  }
+  if (!process2.stdin.isTTY) {
+    throw new Error("Pass a chat question, or run `swarmvault chat` in an interactive terminal.");
+  }
+  let sessionId = await resolveChatResumeId(options.resume);
+  log(sessionId ? `Resuming chat session ${sessionId}.` : "Starting a new chat session.");
+  log("Type /help for commands or /exit to quit.");
+  const reader = createInterface({ input: process2.stdin, output: process2.stdout });
+  try {
+    while (true) {
+      const input = (await reader.question("swarmvault> ")).trim();
+      if (!input) {
+        continue;
+      }
+      if (input === "/exit" || input === "/quit") {
+        break;
+      }
+      if (input === "/help") {
+        log(
+          [
+            "/help              Show commands",
+            "/sessions          List chat sessions",
+            "/status            Show vault health summary",
+            "/clear             Start a fresh session",
+            "/exit              Quit"
+          ].join("\n")
+        );
+        continue;
+      }
+      if (input === "/sessions") {
+        logChatSessions(await listChatSessions(process2.cwd()));
+        continue;
+      }
+      if (input === "/status") {
+        const report = await doctorVault(process2.cwd(), {});
+        log(`Vault health: ${report.ok ? "ok" : "needs attention"} (${report.recommendations.length} recommendation(s))`);
+        for (const recommendation of report.recommendations.slice(0, 5)) {
+          log(`- ${recommendation.label}: ${recommendation.command ?? recommendation.summary}`);
+        }
+        continue;
+      }
+      if (input === "/clear") {
+        sessionId = void 0;
+        log("Started a fresh chat session.");
+        continue;
+      }
+      const result = await askChatSession(process2.cwd(), {
+        question: input,
+        sessionId,
+        saveOutput: options.saveOutput ?? false,
+        gapFill: options.gapFill ?? false,
+        format: options.format,
+        maxHistoryTurns: parsePositiveInt(options.maxHistoryTurns, 6)
+      });
+      sessionId = result.session.id;
+      log(result.answer);
+      log(`Session: ${result.session.id}`);
+      log(`Saved transcript: ${result.markdownPath}`);
+      await maybeEmitHeuristicNotice(["chat"]);
+    }
+  } finally {
+    reader.close();
+  }
+}
 program.hook("postAction", async (_thisCommand, actionCommand) => {
   const notices = await collectCliNotices({
     commandPath: getCommandPath(actionCommand),
@@ -923,6 +1130,44 @@ program.command("query").description("Query the compiled SwarmVault wiki.").argu
     await maybeEmitHeuristicNotice(["query"]);
   }
 );
+program.command("chat").description("Ask the compiled wiki in a persisted multi-turn chat session.").argument("[question...]", "Question to ask in a chat session").option("--resume [id]", "Resume a chat session by id/prefix, or the most recent session when no id is supplied").option("--list", "List saved chat sessions", false).option("--delete <id>", "Delete a saved chat session by id/prefix").option("--save-output", "Also persist each answer as a regular wiki/outputs query page", false).option("--gap-fill", "Pull external web-search evidence when the local wiki has gaps (requires webSearch.tasks.queryProvider).").option("--max-history-turns <n>", "Number of prior turns to include as conversational context", "6").addOption(
+  new Option("--format <format>", "Answer format for generated turns").choices(["markdown", "report", "slides", "chart", "image"]).default("markdown")
+).action(
+  async (questionParts, options) => {
+    if (options.list) {
+      const sessions = await listChatSessions(process2.cwd());
+      if (isJson()) {
+        emitJson(sessions);
+      } else {
+        logChatSessions(sessions);
+      }
+      return;
+    }
+    if (options.delete) {
+      const deleted = await deleteChatSession(process2.cwd(), options.delete);
+      if (isJson()) {
+        emitJson(deleted);
+      } else {
+        log(`Deleted chat session ${deleted.id}`);
+      }
+      return;
+    }
+    const question = (questionParts ?? []).join(" ").trim();
+    if (!question) {
+      await runInteractiveChat(options);
+      return;
+    }
+    const result = await runChatQuestion(question, options);
+    if (isJson()) {
+      emitJson(result);
+    } else {
+      log(result.answer);
+      log(`Session: ${result.session.id}`);
+      log(`Saved transcript: ${result.markdownPath}`);
+    }
+    await maybeEmitHeuristicNotice(["chat"]);
+  }
+);
 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) => {
@@ -1190,6 +1435,23 @@ program.command("benchmark").description("Measure graph-guided context reduction
     }
   }
 });
+var exportCommand = program.command("export").description("Export portable SwarmVault artifacts.");
+exportCommand.command("ai").description("Export static AI handoff files for agents, crawlers, and documentation systems.").option("--out <dir>", "Output directory", path2.join("wiki", "exports", "ai")).option("--max-full-chars <n>", "Maximum characters to include in llms-full.txt", "5000000").option("--no-page-siblings", "Skip per-page .txt and .json sibling files").action(async (options) => {
+  const result = await exportAiPack(process2.cwd(), {
+    outDir: options.out,
+    maxFullChars: parsePositiveInt(options.maxFullChars, 5e6),
+    pageSiblings: options.pageSiblings ?? true
+  });
+  if (isJson()) {
+    emitJson(result);
+    return;
+  }
+  log(`Exported AI handoff pack to ${result.outputDir}`);
+  log(`Files: ${result.files.length}; pages: ${result.pageCount}; nodes: ${result.nodeCount}; edges: ${result.edgeCount}`);
+  if (result.truncatedFullText) {
+    log("llms-full.txt was truncated; rerun with --max-full-chars for a larger export.");
+  }
+});
 program.command("lint").description("Run anti-drift and wiki-health checks.").option("--deep", "Run LLM-powered advisory lint (default: from config)").option("--no-deep", "Skip deep lint even if enabled in config").option("--web", "Augment deep lint with configured web search", false).option("--conflicts", "Filter to contradiction findings only", false).option("--decay", "Filter to decay-related findings only", false).option("--tiers", "Filter to consolidation-tier findings only", false).action(async (options) => {
   const lintConfig = await loadVaultConfig(process2.cwd()).catch(() => null);
   const deepEnabled = options.decay || options.tiers ? false : options.deep ?? lintConfig?.config.profile.deepLintDefault ?? false;
@@ -1215,36 +1477,8 @@ program.command("lint").description("Run anti-drift and wiki-health checks.").op
 var graph = program.command("graph").description("Graph-related commands.").enablePositionalOptions();
 var graphPush = graph.command("push").description("Push the compiled graph into external sinks.");
 graph.command("update").alias("refresh").description("Refresh code-derived graph artifacts from tracked repo roots or one explicit repo path.").argument("[path]", "Optional repo root to refresh instead of configured/tracked roots").option("--lint", "Run lint after the refresh cycle", false).option("--force", "Allow graph updates even when node or edge counts shrink sharply", false).action(runGraphUpdateCommand);
-graph.command("tree").description("Write a collapsible source/module/symbol tree for the compiled graph.").option("--output <html>", "Output HTML path (default: wiki/graph/tree.html)").option("--root <path>", "Vault root to read instead of the current directory").option("--label <name>", "Tree title").option("--max-children <n>", "Maximum children to render per tree node", "250").action(async (options) => {
-  const rootDir = options.root ? path2.resolve(process2.cwd(), options.root) : process2.cwd();
-  const result = await exportGraphTree(rootDir, options.output, {
-    label: options.label,
-    maxChildren: parsePositiveInt(options.maxChildren, 250)
-  });
-  if (isJson()) {
-    emitJson(result);
-    return;
-  }
-  log(`Graph tree: ${result.outputPath}`);
-  log(`Sources: ${result.sourceCount}; nodes: ${result.nodeCount}.`);
-});
-graph.command("merge").description("Merge SwarmVault or node-link JSON graph files into one namespaced graph artifact.").argument("<graphs...>", "Graph JSON files to merge").requiredOption("--out <path>", "Output graph JSON path").option("--label <name>", "Label/prefix to use when merging one graph").action(async (graphPaths, options) => {
-  const result = await mergeGraphFiles(
-    graphPaths.map((inputPath) => path2.resolve(process2.cwd(), inputPath)),
-    path2.resolve(process2.cwd(), options.out),
-    { label: options.label }
-  );
-  if (isJson()) {
-    emitJson(result);
-    return;
-  }
-  log(
-    `Merged ${result.inputGraphs.length} graph${result.inputGraphs.length === 1 ? "" : "s"} into ${result.outputPath}. Nodes ${result.graph.nodes.length}, edges ${result.graph.edges.length}.`
-  );
-  for (const warning of result.warnings) {
-    log(`Warning: ${warning}`);
-  }
-});
+graph.command("tree").description("Write a collapsible source/module/symbol tree for the compiled graph.").option("--output <html>", "Output HTML path (default: wiki/graph/tree.html)").option("--root <path>", "Vault root to read instead of the current directory").option("--label <name>", "Tree title").option("--max-children <n>", "Maximum children to render per tree node", "250").action(runGraphTreeCommand);
+graph.command("merge").description("Merge SwarmVault or node-link JSON graph files into one namespaced graph artifact.").argument("<graphs...>", "Graph JSON files to merge").requiredOption("--out <path>", "Output graph JSON path").option("--label <name>", "Label/prefix to use when merging one graph").action(runGraphMergeCommand);
 graph.command("status").description("Read-only check for graph/report presence and tracked repo changes.").argument("[path]", "Optional repo root to check instead of configured/tracked roots").action(showGraphStatusCommand);
 graph.command("stats").description("Summarize compiled graph counts, node types, evidence classes, and relation mix.").action(async () => {
   const stats = await graphStatsVault(process2.cwd());
@@ -1691,14 +1925,16 @@ async function confirmInteractive(message) {
     rl.close();
   }
 }
-var watch = program.command("watch").description("Watch the inbox directory and optionally tracked repos, or run one refresh cycle immediately.").option("--lint", "Run lint after each compile cycle", false).option("--repo", "Also refresh tracked repo sources and watch their repo roots", false).option("--once", "Run one import/refresh cycle immediately instead of starting a watcher", false).option("--code-only", "Only re-extract code sources (AST-only, no LLM re-analysis)", false).option("--debounce <ms>", "Debounce window in milliseconds", "900").option("--root <path>", "Watch this repo root instead of config/auto-discovery (repeat for multiple)", collectRepeated, []).option("--force", "Allow graph updates even when node or edge counts shrink sharply", false).action(
-  async (options) => {
+var watch = program.command("watch").description("Watch the inbox directory and optionally tracked repos, or run one refresh cycle immediately.").argument("[path]", "Optional repo root to watch or refresh instead of config/auto-discovery").option("--lint", "Run lint after each compile cycle", false).option("--repo", "Also refresh tracked repo sources and watch their repo roots", false).option("--once", "Run one import/refresh cycle immediately instead of starting a watcher", false).option("--code-only", "Only re-extract code sources (AST-only, no LLM re-analysis)", false).option("--debounce <ms>", "Debounce window in milliseconds", "900").option("--root <path>", "Watch this repo root instead of config/auto-discovery (repeat for multiple)", collectRepeated, []).option("--force", "Allow graph updates even when node or edge counts shrink sharply", false).action(
+  async (targetPath, options) => {
     const debounceMs = parsePositiveInt(options.debounce, 900);
-    const overrideRoots = options.root && options.root.length > 0 ? options.root : void 0;
+    const rootOverrides = [...targetPath ? [targetPath] : [], ...options.root ?? []];
+    const overrideRoots = rootOverrides.length > 0 ? rootOverrides : void 0;
+    const repoMode = options.repo || Boolean(targetPath);
     if (options.once) {
       const result = await runWatchCycle(process2.cwd(), {
         lint: options.lint ?? false,
-        repo: options.repo ?? false,
+        repo: repoMode,
         codeOnly: options.codeOnly ?? false,
         debounceMs,
         force: options.force ?? false,
@@ -1708,7 +1944,7 @@ var watch = program.command("watch").description("Watch the inbox directory and
         emitJson(result);
       } else {
         log(
-          `Refreshed inbox${options.repo ? " and tracked repos" : ""}. Imported ${result.importedCount}, repo imported ${result.repoImportedCount}, repo updated ${result.repoUpdatedCount}, repo removed ${result.repoRemovedCount}.`
+          `Refreshed inbox${repoMode ? " and tracked repos" : ""}. Imported ${result.importedCount}, repo imported ${result.repoImportedCount}, repo updated ${result.repoUpdatedCount}, repo removed ${result.repoRemovedCount}.`
         );
       }
       return;
@@ -1716,16 +1952,16 @@ var watch = program.command("watch").description("Watch the inbox directory and
     const { paths } = await loadVaultConfig(process2.cwd());
     const controller = await watchVault(process2.cwd(), {
       lint: options.lint ?? false,
-      repo: options.repo ?? false,
+      repo: repoMode,
       codeOnly: options.codeOnly ?? false,
       debounceMs,
       force: options.force ?? false,
       overrideRoots
     });
     if (isJson()) {
-      emitJson({ status: "watching", inboxDir: paths.inboxDir, repo: options.repo ?? false });
+      emitJson({ status: "watching", inboxDir: paths.inboxDir, repo: repoMode });
     } else {
-      log(`Watching inbox${options.repo ? " and tracked repos" : ""} for changes. Press Ctrl+C to stop.`);
+      log(`Watching inbox${repoMode ? " and tracked repos" : ""} for changes. Press Ctrl+C to stop.`);
     }
     process2.on("SIGINT", async () => {
       try {
@@ -1785,6 +2021,8 @@ program.command("update").description("Compatibility alias for graph update: ref
 program.command("cluster-only").description("Compatibility alias for graph cluster: recompute graph communities and report artifacts without re-ingesting.").argument("[vault]", "Optional vault root to cluster instead of the current directory").option("--resolution <number>", "Override the Louvain community resolution for this run").action(
   (vaultPath, options) => runGraphClusterCommand(options, vaultPath ? path2.resolve(process2.cwd(), vaultPath) : process2.cwd())
 );
+program.command("tree").description("Compatibility alias for graph tree: write a collapsible source/module/symbol tree for the compiled graph.").option("--output <html>", "Output HTML path (default: wiki/graph/tree.html)").option("--root <path>", "Vault root to read instead of the current directory").option("--label <name>", "Tree title").option("--max-children <n>", "Maximum children to render per tree node", "250").action(runGraphTreeCommand);
+program.command("merge-graphs").description("Compatibility alias for graph merge: combine graph JSON files into one namespaced graph artifact.").argument("<graphs...>", "Graph JSON files to merge").requiredOption("--out <path>", "Output graph JSON path").option("--label <name>", "Label/prefix to use when merging one graph").action(runGraphMergeCommand);
 var hook = program.command("hook").description("Install local git hooks that keep tracked repos and the vault in sync.");
 hook.command("install").description("Install post-commit and post-checkout hooks for the nearest git repository.").action(async () => {
   const status = await installGitHooks(process2.cwd());
@@ -2265,67 +2503,8 @@ retrieval.command("doctor").description("Diagnose retrieval index problems and o
     log(`Warning: ${warning}`);
   }
 });
-program.command("scan").description("Quick-start: initialize, ingest, compile, and serve a graph viewer in one command.").argument("<input>", "Directory or public GitHub repo root URL to scan").option("--port <port>", "Port for the graph viewer").option("--no-serve", "Skip launching the graph viewer after compile").option("--branch <name>", "GitHub branch to clone when scanning a public repo URL").option("--ref <ref>", "Git ref, tag, or commit to check out when scanning a public repo URL").option("--checkout-dir <path>", "Persistent checkout directory for a public GitHub repo scan").action(async (input, options) => {
-  const rootDir = process2.cwd();
-  await initVault(rootDir, {});
-  if (!isJson()) {
-    log("Initialized workspace.");
-  }
-  const result = isHttpUrlInput(input) ? await addManagedSource(rootDir, input, {
-    compile: true,
-    brief: false,
-    branch: options.branch,
-    ref: options.ref,
-    checkoutDir: options.checkoutDir
-  }) : await ingestDirectory(rootDir, input, {});
-  if (!isJson()) {
-    if ("source" in result) {
-      log(
-        `Registered ${result.source.kind} source ${result.source.id}. Imported ${result.source.lastSyncCounts?.importedCount ?? 0}, updated ${result.source.lastSyncCounts?.updatedCount ?? 0}.`
-      );
-    } else {
-      log(`Ingested ${result.imported.length} file(s).`);
-    }
-  }
-  const compiled = "compile" in result && result.compile ? result.compile : await compileVault(rootDir, {});
-  const { paths } = await loadVaultConfig(rootDir);
-  const shareCardPath = path2.join(paths.wikiDir, "graph", "share-card.md");
-  const shareCardSvgPath = path2.join(paths.wikiDir, "graph", "share-card.svg");
-  const shareKitPath = path2.join(paths.wikiDir, "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,
-        shareKitPath,
-        port: server.port,
-        url: `http://localhost:${server.port}`
-      });
-    } else {
-      log(`Graph viewer running at http://localhost:${server.port}`);
-    }
-    process2.on("SIGINT", async () => {
-      try {
-        await server.close();
-      } catch {
-      }
-      process2.exit(0);
-    });
-  } else if (isJson()) {
-    emitJson({ ...result, compiled, shareCardPath, shareCardSvgPath, shareKitPath });
-  }
-});
+program.command("scan").description("Quick-start: initialize, ingest, compile, and serve a graph viewer in one command.").argument("<input>", "Directory or public GitHub repo root URL to scan").option("--port <port>", "Port for the graph viewer").option("--no-serve", "Skip launching the graph viewer after compile").option("--no-viz", "Compatibility alias for --no-serve; skip launching the graph viewer after compile").option("--mcp", "Start the MCP stdio server after compile instead of launching the graph viewer", false).option("--branch <name>", "GitHub branch to clone when scanning a public repo URL").option("--ref <ref>", "Git ref, tag, or commit to check out when scanning a public repo URL").option("--checkout-dir <path>", "Persistent checkout directory for a public GitHub repo scan").action(runScanCommand);
+program.command("clone").description("Compatibility alias for scan: initialize, clone/register a public repo URL, and compile it into the vault.").argument("<input>", "Public GitHub repo URL or local directory to scan").option("--port <port>", "Port for the graph viewer").option("--no-serve", "Skip launching the graph viewer after compile").option("--no-viz", "Compatibility alias for --no-serve; skip launching the graph viewer after compile").option("--mcp", "Start the MCP stdio server after compile instead of launching the graph viewer", false).option("--branch <name>", "GitHub branch to clone when scanning a public repo URL").option("--ref <ref>", "Git ref, tag, or commit to check out when scanning a public repo URL").option("--checkout-dir <path>", "Persistent checkout directory for a public GitHub repo scan").action(runScanCommand);
 function enableStructuredJsonOnSubcommands(command) {
   for (const subcommand of command.commands) {
     const hasJsonOption = subcommand.options.some((option) => option.attributeName() === "json");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmvaultai/cli",
-  "version": "3.10.0",
+  "version": "3.12.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": "3.10.0",
+    "@swarmvaultai/engine": "3.12.0",
     "commander": "^14.0.1"
   },
   "devDependencies": {