@swarmvaultai/cli 3.12.0 → 3.14.0

package/README.md

@@ -29,72 +29,61 @@ The smoke parses `packages/cli/src/index.ts` with the TypeScript compiler API, c
 
 ## First Run
 
+Start in an empty folder or scratch folder:
+
 ```bash
 mkdir my-vault
 cd my-vault
-swarmvault init --obsidian --profile personal-research
-swarmvault init --obsidian --profile reader,timeline
+swarmvault quickstart ../your-repo
+```
+
+That single command initializes a vault, ingests the input, compiles the wiki and graph, writes share artifacts, and opens the local graph viewer. It is the beginner-friendly alias for `swarmvault scan`.
+
+No input ready yet?
+
+```bash
 swarmvault demo
-swarmvault source add https://github.com/karpathy/micrograd
-swarmvault source add https://github.com/owner/repo --branch main --checkout-dir .swarmvault-checkouts/repo
-swarmvault source add https://example.com/docs/getting-started
-swarmvault source add ./exports/customer-call.srt --guide
-swarmvault source session file-customer-call-srt-12345678
-swarmvault source list
-swarmvault source reload --all
-sed -n '1,120p' swarmvault.schema.md
-swarmvault ingest ./notes.md
-swarmvault ingest ./customer-call.mp3
-swarmvault ingest https://www.youtube.com/watch?v=dQw4w9WgXcQ
-swarmvault ingest --video https://example.com/product-demo.mp4
-swarmvault ingest ./repo
+```
+
+After the first compile, use:
+
+```bash
+swarmvault next
+swarmvault query "What are the key concepts?"
+swarmvault graph serve
+swarmvault doctor
+swarmvault candidate list
+```
+
+`swarmvault next` is read-only. It detects whether the current folder needs init, ingest, compile, graph refresh, review, or query work and prints the safest next commands.
+
+Use the step-by-step flow when you want more control:
+
+```bash
+swarmvault init --obsidian --profile personal-research
+swarmvault ingest ./src --repo-root .
+swarmvault ingest ./meeting.srt --guide
 swarmvault add https://arxiv.org/abs/2401.12345
-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 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
-swarmvault doctor --repair
-swarmvault query "Turn this into slides" --format slides
-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
-swarmvault watch --repo --once
-swarmvault hook install
+swarmvault compile
+swarmvault next
+swarmvault query "What is the auth flow?"
 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
 ```
 
+Use `source add` for recurring inputs (`swarmvault source add https://github.com/karpathy/micrograd`, `swarmvault source add https://example.com/docs/getting-started`, `swarmvault source list`, `swarmvault source reload --all`, and `swarmvault source session file-customer-call-srt-12345678`). Use advanced graph/context surfaces when needed: `swarmvault graph status ./src`, `swarmvault check-update ./src`, `swarmvault update ./src`, `swarmvault graph stats`, `swarmvault graph validate --strict`, `swarmvault graph cluster`, `swarmvault cluster-only`, `swarmvault tree --output ./exports/tree.html`, `swarmvault export ai --out ./exports/ai`, `swarmvault context build "Ship this feature safely" --target ./src --budget 8000`, and `swarmvault task start "Ship this feature safely" --target ./src --agent codex`.
+
 ## Commands
 
+### `swarmvault next`
+
+Print the safest next command for the current directory without changing files.
+
+- reports `uninitialized`, `initialized`, or `compiled`
+- prints key vault paths such as config, schema, `raw/`, `wiki/`, `state/graph.json`, and the graph report
+- recommends `quickstart`, `init`, `ingest`, `compile`, `query`, review, doctor, or graph refresh commands based on current state
+- supports `--json` with `status`, `paths`, `checks`, and `recommendations`
+- does not emit notices, prompts, repairs, or writes
+
 ### `swarmvault init [--obsidian] [--profile <alias-or-presets>]`
 
 Create a workspace with:
@@ -116,6 +105,19 @@ 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 quickstart <directory|github-url> [--port <port>] [--no-serve] [--no-viz] [--mcp] [--branch <name>] [--ref <ref>] [--checkout-dir <path>]`
+
+Beginner-friendly alias for `swarmvault scan`.
+
+- initializes the current directory as a SwarmVault workspace
+- ingests the supplied local directory, or registers/syncs the supplied public GitHub repo root URL
+- compiles wiki, graph, search, and share artifacts immediately
+- prints the generated `raw/`, `wiki/`, `state/graph.json`, and `wiki/graph/` paths in human output
+- starts `graph serve` unless you pass `--no-serve` or `--no-viz`
+- keeps the same JSON output contract as `scan`
+
+Use this as the default first-run command in docs and onboarding.
+
 ### `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.

package/dist/index.js

@@ -2,7 +2,7 @@
 
 // src/index.ts
 import { readFileSync } from "fs";
-import { mkdir as mkdir2, readFile as readFile2, writeFile as writeFile2 } from "fs/promises";
+import { access, mkdir as mkdir2, readFile as readFile2, writeFile as writeFile2 } from "fs/promises";
 import path2 from "path";
 import process2 from "process";
 import { createInterface } from "readline/promises";
@@ -21,6 +21,7 @@ import {
   compileVault,
   consolidateVault,
   createSupersessionEdge,
+  defaultVaultConfig,
   deleteChatSession,
   deleteContextPack,
   deleteManagedSource,
@@ -85,6 +86,7 @@ import {
   renderGraphShareBundleFiles,
   renderGraphShareMarkdown,
   renderGraphShareSvg,
+  resolvePaths,
   resumeMemoryTask,
   resumeSourceSession,
   reviewManagedSource,
@@ -316,12 +318,21 @@ var program = new Command();
 var CLI_VERSION = readCliVersion();
 var activeCommand = null;
 program.name("swarmvault").description("SwarmVault is a local-first knowledge compiler with graph outputs and optional provider-backed workflows.").version(CLI_VERSION).enablePositionalOptions().option("--json", "Emit structured JSON output", false);
+program.addHelpText(
+  "after",
+  (context2) => context2.command === program ? [
+    "",
+    "Need help choosing? Run `swarmvault next`.",
+    "Advanced and compatibility commands are still available with `swarmvault <command> --help`.",
+    "CLI docs: https://www.swarmvault.ai/docs/cli"
+  ].join("\n") : ""
+);
 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.12.0";
+    return typeof packageJson.version === "string" && packageJson.version.trim() ? packageJson.version : "3.14.0";
   } catch {
-    return "3.12.0";
+    return "3.14.0";
   }
 }
 function parsePositiveInt(value, fallback) {
@@ -386,6 +397,232 @@ function log(message) {
 `);
   }
 }
+function serializeNextPaths(paths) {
+  return {
+    configPath: paths.configPath,
+    schemaPath: paths.schemaPath,
+    rawDir: paths.rawDir,
+    wikiDir: paths.wikiDir,
+    stateDir: paths.stateDir,
+    graphPath: paths.graphPath,
+    reportPath: path2.join(paths.wikiDir, "graph", "report.md")
+  };
+}
+async function pathExists(filePath) {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function nextRecommendation(label, command, description, priority) {
+  return { label, command, description, priority };
+}
+function dedupeNextRecommendations(recommendations) {
+  const seen = /* @__PURE__ */ new Set();
+  const rank = { high: 0, medium: 1, low: 2 };
+  return recommendations.filter((recommendation) => {
+    if (seen.has(recommendation.command)) {
+      return false;
+    }
+    seen.add(recommendation.command);
+    return true;
+  }).sort((left, right) => rank[left.priority] - rank[right.priority] || left.command.localeCompare(right.command));
+}
+async function buildNextCommandReport(rootDir) {
+  const generatedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const fallbackPaths = resolvePaths(rootDir, defaultVaultConfig());
+  const fallbackNextPaths = serializeNextPaths(fallbackPaths);
+  const [configExists, schemaExists] = await Promise.all([pathExists(fallbackPaths.configPath), pathExists(fallbackPaths.schemaPath)]);
+  if (!configExists && !schemaExists) {
+    return {
+      status: "uninitialized",
+      rootDir,
+      generatedAt,
+      paths: fallbackNextPaths,
+      checks: [
+        {
+          id: "workspace",
+          label: "Workspace",
+          status: "error",
+          summary: "No SwarmVault workspace files were found in this directory.",
+          command: "swarmvault quickstart ./your-repo"
+        }
+      ],
+      recommendations: [
+        nextRecommendation(
+          "Fast start",
+          "swarmvault quickstart ./your-repo",
+          "Initialize, ingest, compile, and open the graph viewer.",
+          "high"
+        ),
+        nextRecommendation("Try a sample", "swarmvault demo", "Build a small demo vault before using your own files.", "medium"),
+        nextRecommendation(
+          "Manual setup",
+          "swarmvault init",
+          "Create an empty vault when you want to ingest and compile step by step.",
+          "medium"
+        )
+      ]
+    };
+  }
+  let paths;
+  try {
+    ({ paths } = await loadVaultConfig(rootDir));
+  } catch (error) {
+    return {
+      status: "initialized",
+      rootDir,
+      generatedAt,
+      paths: fallbackNextPaths,
+      checks: [
+        {
+          id: "config",
+          label: "Config",
+          status: "error",
+          summary: "SwarmVault workspace files exist, but the config could not be loaded.",
+          detail: error instanceof Error ? error.message : String(error),
+          command: "swarmvault doctor"
+        }
+      ],
+      recommendations: [
+        nextRecommendation(
+          "Inspect workspace health",
+          "swarmvault doctor",
+          "Review the config/schema issue before ingesting or compiling.",
+          "high"
+        )
+      ]
+    };
+  }
+  const nextPaths = serializeNextPaths(paths);
+  const graphStatus = await getGraphStatus(rootDir).catch(() => null);
+  const graphExists = graphStatus?.graphExists ?? await pathExists(paths.graphPath);
+  if (!graphExists) {
+    return {
+      status: "initialized",
+      rootDir,
+      generatedAt,
+      paths: nextPaths,
+      checks: [
+        {
+          id: "workspace",
+          label: "Workspace",
+          status: "ok",
+          summary: "Workspace config and schema are present."
+        },
+        {
+          id: "graph",
+          label: "Graph",
+          status: "error",
+          summary: "No compiled graph artifact was found.",
+          command: "swarmvault compile"
+        }
+      ],
+      recommendations: [
+        nextRecommendation("Add sources", "swarmvault ingest ./your-source", "Import a directory, file, or URL into raw/.", "high"),
+        nextRecommendation("Compile vault", "swarmvault compile", "Build wiki pages, graph JSON, and the graph report.", "high"),
+        nextRecommendation("Open the viewer", "swarmvault graph serve", "Open the local graph viewer after compiling.", "medium")
+      ],
+      graph: graphStatus ? {
+        exists: graphStatus.graphExists,
+        reportExists: graphStatus.reportExists,
+        stale: graphStatus.stale,
+        codeChangeCount: graphStatus.codeChangeCount,
+        semanticChangeCount: graphStatus.semanticChangeCount,
+        trackedRepoRoots: graphStatus.trackedRepoRoots
+      } : void 0
+    };
+  }
+  const doctor = await doctorVault(rootDir, { repair: false });
+  const recommendations = dedupeNextRecommendations([
+    ...graphStatus?.recommendedCommand ? [
+      nextRecommendation(
+        graphStatus.stale ? "Refresh graph" : "Check graph",
+        graphStatus.recommendedCommand,
+        graphStatus.stale ? "Tracked inputs changed since the graph was compiled." : "Review graph freshness.",
+        graphStatus.stale ? "high" : "medium"
+      )
+    ] : [],
+    ...doctor.recommendations.filter((recommendation) => recommendation.command).map(
+      (recommendation) => nextRecommendation(
+        recommendation.label,
+        recommendation.command,
+        recommendation.description ?? recommendation.summary,
+        recommendation.priority
+      )
+    ),
+    ...doctor.recommendations.length ? [] : [
+      nextRecommendation(
+        "Ask a question",
+        'swarmvault query "What are the key concepts?"',
+        "Query the compiled wiki and graph.",
+        "medium"
+      ),
+      nextRecommendation("Open the graph", "swarmvault graph serve", "Explore the compiled graph locally.", "medium"),
+      nextRecommendation("Run health checks", "swarmvault doctor", "Re-check graph, retrieval, review queues, and migrations.", "low")
+    ]
+  ]);
+  return {
+    status: "compiled",
+    rootDir,
+    generatedAt,
+    paths: nextPaths,
+    checks: doctor.checks.map((check) => ({
+      id: check.id,
+      label: check.label,
+      status: check.status,
+      summary: check.summary,
+      detail: check.detail,
+      command: check.actions?.[0]?.command
+    })),
+    recommendations,
+    counts: doctor.counts,
+    graph: graphStatus ? {
+      exists: graphStatus.graphExists,
+      reportExists: graphStatus.reportExists,
+      stale: graphStatus.stale,
+      codeChangeCount: graphStatus.codeChangeCount,
+      semanticChangeCount: graphStatus.semanticChangeCount,
+      trackedRepoRoots: graphStatus.trackedRepoRoots
+    } : void 0
+  };
+}
+function printNextCommandReport(report) {
+  if (report.status === "uninitialized") {
+    log(`SwarmVault is not initialized in ${report.rootDir}.`);
+    log("");
+    log("Start here:");
+  } else {
+    log(`SwarmVault workspace: ${report.rootDir}`);
+    log(`Config: ${report.paths.configPath}`);
+    log(`Schema: ${report.paths.schemaPath}`);
+    log(`Raw sources: ${report.paths.rawDir}`);
+    log(`Wiki output: ${report.paths.wikiDir}`);
+    const graphPresent = report.graph?.exists ?? report.status === "compiled";
+    log(`Graph JSON: ${graphPresent ? report.paths.graphPath : `missing (${report.paths.graphPath})`}`);
+    log(`Graph report: ${report.graph?.reportExists ? report.paths.reportPath : `missing (${report.paths.reportPath})`}`);
+    if (report.graph) {
+      log(`Graph state: ${report.graph.stale ? "stale" : "fresh"}`);
+      log(`Tracked repo roots: ${report.graph.trackedRepoRoots.length ? report.graph.trackedRepoRoots.join(", ") : "none"}`);
+      log(`Pending changes: ${report.graph.codeChangeCount + report.graph.semanticChangeCount}`);
+    }
+    if (report.counts) {
+      log(
+        `Counts: ${report.counts.sources} source(s), ${report.counts.pages} page(s), ${report.counts.nodes} node(s), ${report.counts.edges} edge(s).`
+      );
+    }
+    log("");
+    log(report.status === "initialized" ? "Status: initialized, not compiled yet." : "Status: compiled.");
+    log("");
+    log("Next steps:");
+  }
+  for (const recommendation of report.recommendations.slice(0, 6)) {
+    log(`  ${recommendation.command}`);
+    log(`    ${recommendation.description}`);
+  }
+}
 async function writeShareBundle(bundlePath, files) {
   await mkdir2(bundlePath, { recursive: true });
   const bundleFiles = {
@@ -608,10 +845,20 @@ async function runScanCommand(input, options) {
   const shareKitPath = path2.join(paths.wikiDir, "graph", "share-kit");
   if (!isJson()) {
     log(`Compiled ${compiled.sourceCount} source(s), ${compiled.pageCount} page(s).`);
+    log(`Vault workspace: ${rootDir}`);
+    log(`Raw sources: ${paths.rawDir}`);
+    log(`Wiki output: ${paths.wikiDir}`);
+    log(`Graph JSON: ${paths.graphPath}`);
     log(`Share card: ${shareCardPath}`);
     log(`Visual card: ${shareCardSvgPath}`);
     log(`Share kit: ${shareKitPath}`);
-    log("Post text: swarmvault graph share --post");
+    log("");
+    log("Next steps:");
+    log('  swarmvault query "What are the key concepts?"');
+    log("  swarmvault graph serve");
+    log("  swarmvault doctor");
+    log("  swarmvault candidate list");
+    log("  swarmvault next");
   }
   if (options.mcp) {
     process2.stderr.write(`${JSON.stringify({ status: "running", transport: "stdio", compiled: compiled.sourceCount })}
@@ -641,6 +888,7 @@ async function runScanCommand(input, options) {
       });
     } else {
       log(`Graph viewer running at http://localhost:${server.port}`);
+      log("Next orientation: swarmvault next");
     }
     process2.on("SIGINT", async () => {
       try {
@@ -753,8 +1001,12 @@ async function runInteractiveChat(options) {
   }
 }
 program.hook("postAction", async (_thisCommand, actionCommand) => {
+  const commandPath = getCommandPath(actionCommand);
+  if (commandPath[0] === "next" || commandPath[0] === "quickstart" || commandPath[0] === "init") {
+    return;
+  }
   const notices = await collectCliNotices({
-    commandPath: getCommandPath(actionCommand),
+    commandPath,
     currentVersion: CLI_VERSION,
     json: isJson()
   });
@@ -762,6 +1014,15 @@ program.hook("postAction", async (_thisCommand, actionCommand) => {
     emitNotice(notice);
   }
 });
+program.command("next").description("Show the safest next command for this directory without changing files.").action(async () => {
+  const report = await buildNextCommandReport(process2.cwd());
+  if (isJson()) {
+    emitJson(report);
+    return;
+  }
+  printNextCommandReport(report);
+});
+program.command("quickstart").description("Beginner path: initialize, ingest, compile, and optionally open the graph viewer in one command.").argument("<input>", "Directory or public GitHub repo root URL to turn into a vault").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 the input is a public repo URL").option("--ref <ref>", "Git ref, tag, or commit to check out when the input is a public repo URL").option("--checkout-dir <path>", "Persistent checkout directory for a public GitHub repo input").action(runScanCommand);
 program.command("init").description("Initialize a SwarmVault workspace in the current directory.").option("--obsidian", "Generate a minimal .obsidian workspace alongside the vault", false).option(
   "--profile <profile>",
   "Starter workspace profile or comma-separated preset list (for example: personal-research or reader,timeline)"
@@ -785,6 +1046,7 @@ program.command("init").description("Initialize a SwarmVault workspace in the cu
     });
   } else {
     log(options.lite ? "Initialized SwarmVault lite workspace." : "Initialized SwarmVault workspace.");
+    log("Next: swarmvault next");
   }
 });
 program.command("ingest").description("Ingest a local file path, directory path, or URL into the raw SwarmVault workspace.").argument("<input>", "Local file path, directory path, or URL").option("--review", "Stage a source review artifact after ingest and compile", false).option("--guide", "Stage a guided source integration bundle after ingest and compile (default: from config)").option("--no-guide", "Skip guided mode even if enabled in config").option("--answers-file <path>", "JSON file with guided-session answers keyed by question id or listed in prompt order").option("--include-assets", "Download remote image assets when ingesting URLs", true).option("--no-include-assets", "Skip downloading remote image assets when ingesting URLs").option("--max-asset-size <bytes>", "Maximum number of bytes to fetch for a single remote image asset").option("--repo-root <path>", "Override the detected repo root when ingesting a directory").option("--include <glob...>", "Only ingest files matching one or more glob patterns").option("--exclude <glob...>", "Skip files matching one or more glob patterns").option("--max-files <n>", "Maximum number of files to ingest from a directory").option("--include-third-party", "Also ingest repo files classified as third-party", false).option("--include-resources", "Also ingest repo files classified as resources", false).option("--include-generated", "Also ingest repo files classified as generated output", false).option("--no-gitignore", "Ignore .gitignore rules when ingesting a directory").option("--no-swarmvaultignore", "Ignore .swarmvaultignore rules when ingesting a directory").option("--video", "Treat a URL input as a public video and transcribe extracted audio", false).option("--resume <run-id>", "Re-run only the failed files from a prior ingest run id").option("--commit", "Auto-commit wiki and state changes after ingest").option("--no-redact", "Skip PII/secret redaction for this run (overrides config)").action(
@@ -1224,7 +1486,7 @@ context.command("delete").description("Delete a saved context pack artifact and
   }
   log(`Deleted context pack ${deleted.id}.`);
 });
-var memory = program.command("memory").description("Manage git-backed agent memory task ledger entries.");
+var memory = program.command("memory", { hidden: true }).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,
@@ -2016,13 +2278,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(
+program.command("check-update", { hidden: true }).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", { hidden: true }).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", { hidden: true }).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);
+program.command("tree", { hidden: true }).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", { hidden: true }).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());
@@ -2503,8 +2765,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("--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);
+program.command("scan", { hidden: true }).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", { hidden: true }).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.12.0",
+  "version": "3.14.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.12.0",
+    "@swarmvaultai/engine": "3.14.0",
     "commander": "^14.0.1"
   },
   "devDependencies": {