@swarmvaultai/cli 3.9.0 → 3.11.0

package/README.md

@@ -65,11 +65,15 @@ swarmvault explore "What should I research next?" --steps 3
 swarmvault lint --deep
 swarmvault graph blast ./src/index.ts
 swarmvault graph status ./src
+swarmvault check-update ./src
 swarmvault graph stats
 swarmvault graph validate --strict
 swarmvault graph update .
+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
@@ -79,8 +83,11 @@ swarmvault graph serve
 swarmvault graph export --report ./exports/report.html
 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
@@ -106,7 +113,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.
 
@@ -114,12 +121,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`.
@@ -410,6 +427,22 @@ Refresh code-derived graph artifacts from tracked repo roots or one explicit rep
 - aborts if nodes or edges drop by more than 25% compared with the existing graph; pass `--force` or set `SWARMVAULT_FORCE_UPDATE=1` when the shrink is expected
 - `--json` returns the same one-shot watch result shape, including repo import/update/remove counts and pending semantic refresh entries
 
+### `swarmvault check-update [path]`
+
+Compatibility alias for `swarmvault graph status [path]`.
+
+- performs the same read-only graph/report freshness check
+- keeps automation-friendly JSON output for cron or hook wrappers
+- recommends `swarmvault update`/`swarmvault graph update` for code-only drift and `swarmvault compile` when semantic refresh is required
+
+### `swarmvault update [path]`
+
+Compatibility alias for `swarmvault graph update [path]`.
+
+- runs the same code-only repo refresh path
+- accepts `--lint` and `--force`
+- returns the same JSON shape as `graph update`
+
 ### `swarmvault graph tree [--output <html>] [--root <path>] [--label <name>] [--max-children <n>]`
 
 Write a collapsible HTML source tree for the current `state/graph.json`.
@@ -420,6 +453,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.
@@ -430,6 +470,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.
@@ -441,6 +488,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.
@@ -470,6 +526,21 @@ Recompute communities, node degrees, bridge scores, god-node flags, and graph re
 - splits oversized or low-cohesion communities after the initial Louvain pass so large-repo reports stay scannable
 - `--json` returns counts plus the graph/report paths
 
+### `swarmvault cluster-only [vault] [--resolution <n>]`
+
+Compatibility alias for `swarmvault graph cluster`.
+
+- recomputes communities and graph report artifacts without ingest or semantic analysis
+- accepts an optional vault root when the command is run from outside the vault
+- returns the same JSON shape as `graph cluster`
+
+### `swarmvault graph export --neo4j <path>`
+
+Compatibility alias for `swarmvault graph export --cypher <path>`.
+
+- writes a Neo4j-ready Cypher import file
+- can be combined with other `graph export` formats in the same run
+
 ### `swarmvault hook install|uninstall|status`
 
 Manage SwarmVault's local git hook blocks for the nearest git repository.

package/dist/index.js

@@ -315,9 +315,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.9.0";
+    return typeof packageJson.version === "string" && packageJson.version.trim() ? packageJson.version : "3.11.0";
   } catch {
-    return "3.9.0";
+    return "3.11.0";
   }
 }
 function parsePositiveInt(value, fallback) {
@@ -488,6 +488,167 @@ function getCommandPath(command) {
   }
   return names;
 }
+async function runGraphUpdateCommand(targetPath, options) {
+  const overrideRoots = targetPath ? [path2.resolve(process2.cwd(), targetPath)] : void 0;
+  const result = await runWatchCycle(process2.cwd(), {
+    repo: true,
+    codeOnly: true,
+    lint: options.lint ?? false,
+    force: options.force ?? false,
+    overrideRoots
+  });
+  if (isJson()) {
+    emitJson(result);
+    return;
+  }
+  log(
+    `Updated graph from ${result.watchedRepoRoots.length} repo root${result.watchedRepoRoots.length === 1 ? "" : "s"}. Imported ${result.repoImportedCount}, updated ${result.repoUpdatedCount}, removed ${result.repoRemovedCount}, pending semantic refresh ${result.pendingSemanticRefreshCount}.`
+  );
+}
+async function showGraphStatusCommand(targetPath) {
+  const overrideRoots = targetPath ? [path2.resolve(process2.cwd(), targetPath)] : void 0;
+  const status = await getGraphStatus(process2.cwd(), { repoRoots: overrideRoots });
+  if (isJson()) {
+    emitJson(status);
+    return;
+  }
+  log(`Graph: ${status.graphExists ? status.graphPath : `missing (${status.graphPath})`}`);
+  log(`Report: ${status.reportExists ? status.reportPath : `missing (${status.reportPath})`}`);
+  log(`Tracked repo roots: ${status.trackedRepoRoots.length ? status.trackedRepoRoots.join(", ") : "none"}`);
+  log(`Code changes: ${status.codeChangeCount}`);
+  log(`Semantic changes: ${status.semanticChangeCount}`);
+  log(`Pending semantic refresh: ${status.pendingSemanticRefresh.length}`);
+  if (status.changes.length) {
+    for (const change of status.changes.slice(0, 20)) {
+      log(`- ${change.refreshType} ${change.changeType} ${change.path}`);
+    }
+    if (status.changes.length > 20) {
+      log(`... and ${status.changes.length - 20} more`);
+    }
+  }
+  log(`State: ${status.stale ? "stale" : "fresh"}`);
+  if (status.recommendedCommand) {
+    log(`Recommended: ${status.recommendedCommand}`);
+  }
+}
+async function runGraphClusterCommand(options, rootDir = process2.cwd()) {
+  const resolution = parsePositiveNumber(options.resolution);
+  if (options.resolution && resolution === void 0) {
+    throw new Error("--resolution must be a positive number.");
+  }
+  const result = await refreshGraphClusters(rootDir, { resolution });
+  if (isJson()) {
+    emitJson(result);
+    return;
+  }
+  log(
+    `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 });
+  }
+}
 program.hook("postAction", async (_thisCommand, actionCommand) => {
   const notices = await collectCliNotices({
     commandPath: getCommandPath(actionCommand),
@@ -1157,79 +1318,10 @@ 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(async (targetPath, options) => {
-  const overrideRoots = targetPath ? [path2.resolve(process2.cwd(), targetPath)] : void 0;
-  const result = await runWatchCycle(process2.cwd(), {
-    repo: true,
-    codeOnly: true,
-    lint: options.lint ?? false,
-    force: options.force ?? false,
-    overrideRoots
-  });
-  if (isJson()) {
-    emitJson(result);
-    return;
-  }
-  log(
-    `Updated graph from ${result.watchedRepoRoots.length} repo root${result.watchedRepoRoots.length === 1 ? "" : "s"}. Imported ${result.repoImportedCount}, updated ${result.repoUpdatedCount}, removed ${result.repoRemovedCount}, pending semantic refresh ${result.pendingSemanticRefreshCount}.`
-  );
-});
-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("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(async (targetPath) => {
-  const overrideRoots = targetPath ? [path2.resolve(process2.cwd(), targetPath)] : void 0;
-  const status = await getGraphStatus(process2.cwd(), { repoRoots: overrideRoots });
-  if (isJson()) {
-    emitJson(status);
-    return;
-  }
-  log(`Graph: ${status.graphExists ? status.graphPath : `missing (${status.graphPath})`}`);
-  log(`Report: ${status.reportExists ? status.reportPath : `missing (${status.reportPath})`}`);
-  log(`Tracked repo roots: ${status.trackedRepoRoots.length ? status.trackedRepoRoots.join(", ") : "none"}`);
-  log(`Code changes: ${status.codeChangeCount}`);
-  log(`Semantic changes: ${status.semanticChangeCount}`);
-  log(`Pending semantic refresh: ${status.pendingSemanticRefresh.length}`);
-  if (status.changes.length) {
-    for (const change of status.changes.slice(0, 20)) {
-      log(`- ${change.refreshType} ${change.changeType} ${change.path}`);
-    }
-    if (status.changes.length > 20) {
-      log(`... and ${status.changes.length - 20} more`);
-    }
-  }
-  log(`State: ${status.stale ? "stale" : "fresh"}`);
-  if (status.recommendedCommand) {
-    log(`Recommended: ${status.recommendedCommand}`);
-  }
-});
+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(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());
   if (isJson()) {
@@ -1270,20 +1362,7 @@ graph.command("validate").description("Validate a compiled graph artifact for da
     process2.exitCode = 1;
   }
 });
-graph.command("cluster").alias("clusters").description("Recompute graph communities, degrees, god-node flags, and graph report artifacts without re-ingesting sources.").option("--resolution <number>", "Override the Louvain community resolution for this run").action(async (options) => {
-  const resolution = parsePositiveNumber(options.resolution);
-  if (options.resolution && resolution === void 0) {
-    throw new Error("--resolution must be a positive number.");
-  }
-  const result = await refreshGraphClusters(process2.cwd(), { resolution });
-  if (isJson()) {
-    emitJson(result);
-    return;
-  }
-  log(
-    `Refreshed ${result.communityCount} communities across ${result.nodeCount} nodes and ${result.edgeCount} edges. Report: ${result.reportPath}`
-  );
-});
+graph.command("cluster").alias("clusters").description("Recompute graph communities, degrees, god-node flags, and graph report artifacts without re-ingesting sources.").option("--resolution <number>", "Override the Louvain community resolution for this run").action((options) => runGraphClusterCommand(options));
 graphPush.command("neo4j").description("Push the compiled graph directly into Neo4j over Bolt/Aura.").option("--uri <bolt-uri>", "Neo4j Bolt or Aura URI").option("--username <user>", "Neo4j username").option("--password-env <env-var>", "Environment variable containing the Neo4j password").option("--database <name>", "Neo4j database name").option("--vault-id <id>", "Stable vault identifier used for shared-database namespacing").option("--batch-size <n>", "Maximum rows to write per Neo4j transaction batch").option("--include-third-party", "Also push third-party repo material", false).option("--include-resources", "Also push resource-like content", false).option("--include-generated", "Also push generated output", false).option("--dry-run", "Show what would be pushed without writing to Neo4j", false).action(
   async (options) => {
     const batchSize = typeof options.batchSize === "string" && options.batchSize.trim() ? parsePositiveInt(options.batchSize, 0) || void 0 : void 0;
@@ -1339,7 +1418,7 @@ graph.command("serve").description("Serve the local graph viewer.").option("--po
 });
 graph.command("export").description(
   "Export the graph as HTML, report, SVG, GraphML, Cypher, JSON, Obsidian vault, or Obsidian canvas. Combine flags to write multiple formats in one run."
-).option("--html <output>", "Output HTML file path").option("--html-standalone <output>", "Output lightweight standalone HTML file path (vis.js, no build tooling)").option("--report <output>", "Output self-contained HTML report (graph stats, key nodes, communities)").option("--svg <output>", "Output SVG file path").option("--graphml <output>", "Output GraphML file path").option("--cypher <output>", "Output Cypher file path").option("--json <output>", "Output JSON file path").option("--obsidian <output>", "Output Obsidian vault directory path").option("--canvas <output>", "Output Obsidian canvas file path").option("--full", "Include the full graph in HTML export (default; queries traverse complete graph)", true).option("--overview", "Use overview sampling for HTML export (smaller file, queries limited to sampled nodes)", false).action(
+).option("--html <output>", "Output HTML file path").option("--html-standalone <output>", "Output lightweight standalone HTML file path (vis.js, no build tooling)").option("--report <output>", "Output self-contained HTML report (graph stats, key nodes, communities)").option("--svg <output>", "Output SVG file path").option("--graphml <output>", "Output GraphML file path").option("--cypher <output>", "Output Cypher file path").option("--neo4j <output>", "Compatibility alias for --cypher, writing a Neo4j Cypher import file").option("--json <output>", "Output JSON file path").option("--obsidian <output>", "Output Obsidian vault directory path").option("--canvas <output>", "Output Obsidian canvas file path").option("--full", "Include the full graph in HTML export (default; queries traverse complete graph)", true).option("--overview", "Use overview sampling for HTML export (smaller file, queries limited to sampled nodes)", false).action(
   async (options) => {
     const useFullGraph = options.overview ? false : options.full ?? true;
     const targets = [
@@ -1349,13 +1428,14 @@ graph.command("export").description(
       options.svg ? { format: "svg", outputPath: options.svg } : null,
       options.graphml ? { format: "graphml", outputPath: options.graphml } : null,
       options.cypher ? { format: "cypher", outputPath: options.cypher } : null,
+      options.neo4j ? { format: "cypher", outputPath: options.neo4j } : null,
       options.json ? { format: "json", outputPath: options.json } : null,
       options.obsidian ? { format: "obsidian", outputPath: options.obsidian } : null,
       options.canvas ? { format: "canvas", outputPath: options.canvas } : null
     ].filter((target) => Boolean(target));
     if (targets.length === 0) {
       throw new Error(
-        "Pass at least one of --html, --html-standalone, --report, --svg, --graphml, --cypher, --json, --obsidian, or --canvas."
+        "Pass at least one of --html, --html-standalone, --report, --svg, --graphml, --cypher, --neo4j, --json, --obsidian, or --canvas."
       );
     }
     const results = [];
@@ -1687,14 +1767,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,
@@ -1704,7 +1786,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;
@@ -1712,16 +1794,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 {
@@ -1776,6 +1858,13 @@ async function showWatchStatus() {
 }
 watch.command("status").description("Show the latest watch run plus pending semantic refresh entries.").action(showWatchStatus);
 program.command("watch-status").description("Show the latest watch run plus pending semantic refresh entries.").action(showWatchStatus);
+program.command("check-update").description("Compatibility alias for graph status: read-only graph/report freshness and tracked repo change check.").argument("[path]", "Optional repo root to check instead of configured/tracked roots").action(showGraphStatusCommand);
+program.command("update").description("Compatibility alias for graph update: refresh code-derived graph artifacts from tracked repo roots.").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);
+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());
@@ -2256,67 +2345,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.9.0",
+  "version": "3.11.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.9.0",
+    "@swarmvaultai/engine": "3.11.0",
     "commander": "^14.0.1"
   },
   "devDependencies": {