@swarmvaultai/cli 0.1.18 → 0.1.19

package/README.md

@@ -31,6 +31,8 @@ swarmvault query "What keeps recurring?"
 swarmvault query "Turn this into slides" --format slides
 swarmvault explore "What should I research next?" --steps 3
 swarmvault lint --deep
+swarmvault graph query "Which nodes bridge the biggest clusters?"
+swarmvault graph explain "concept:drift"
 swarmvault graph serve
 swarmvault graph export --html ./exports/graph.html
 ```
@@ -177,11 +179,27 @@ The MCP surface also exposes `swarmvault://schema`, `swarmvault://sessions`, `sw
 
 ### `swarmvault graph serve`
 
-Start the local graph workspace backed by `state/graph.json`, `/api/search`, and `/api/page`.
+Start the local graph workspace backed by `state/graph.json`, `/api/search`, `/api/page`, and local graph query/path/explain endpoints.
+
+### `swarmvault graph query "<question>" [--dfs] [--budget <n>]`
+
+Run a deterministic local graph traversal seeded from local search and graph labels.
+
+### `swarmvault graph path <from> <to>`
+
+Return the shortest high-confidence path between two graph targets.
+
+### `swarmvault graph explain <target>`
+
+Inspect graph metadata, community membership, neighbors, and provenance for a node or page.
+
+### `swarmvault graph god-nodes [--limit <n>]`
+
+List the most connected bridge-heavy nodes in the current graph.
 
 ### `swarmvault graph export --html <output>`
 
-Export the graph workspace as a standalone HTML file with embedded graph and page data for offline sharing.
+Export the graph workspace as a standalone HTML file with embedded graph and page data for offline sharing. The exported file keeps read-only graph browsing, search, and page preview. The live graph query/path/explain actions remain part of `graph serve` and the MCP surface.
 
 ### `swarmvault install --agent <codex|claude|cursor|goose|pi|gemini|opencode>`
 

package/dist/index.js

@@ -7,6 +7,7 @@ import {
   acceptApproval,
   archiveCandidate,
   compileVault,
+  explainGraphVault,
   exploreVault,
   exportGraphHtml,
   importInbox,
@@ -17,9 +18,12 @@ import {
   lintVault,
   listApprovals,
   listCandidates,
+  listGodNodes,
   listSchedules,
   loadVaultConfig,
+  pathGraphVault,
   promoteCandidate,
+  queryGraphVault,
   queryVault,
   readApproval,
   rejectApproval,
@@ -36,9 +40,9 @@ program.name("swarmvault").description("SwarmVault is a local-first LLM wiki com
 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 : "0.1.18";
+    return typeof packageJson.version === "string" && packageJson.version.trim() ? packageJson.version : "0.1.19";
   } catch {
-    return "0.1.18";
+    return "0.1.19";
   }
 }
 function isJson() {
@@ -194,6 +198,45 @@ graph.command("export").description("Export the graph viewer as a single self-co
     log(`Exported graph HTML to ${outputPath}`);
   }
 });
+graph.command("query").description("Traverse the compiled graph deterministically from local search seeds.").argument("<question>", "Question or graph search seed").option("--dfs", "Prefer a depth-first traversal instead of breadth-first", false).option("--budget <n>", "Maximum number of graph nodes to summarize").action(async (question, options) => {
+  const budget = options.budget ? Number.parseInt(options.budget, 10) : void 0;
+  const result = await queryGraphVault(process.cwd(), question, {
+    traversal: options.dfs ? "dfs" : "bfs",
+    budget: Number.isFinite(budget) ? budget : void 0
+  });
+  if (isJson()) {
+    emitJson(result);
+    return;
+  }
+  log(result.summary);
+});
+graph.command("path").description("Find the shortest graph path between two nodes or pages.").argument("<from>", "Source node/page label or id").argument("<to>", "Target node/page label or id").action(async (from, to) => {
+  const result = await pathGraphVault(process.cwd(), from, to);
+  if (isJson()) {
+    emitJson(result);
+    return;
+  }
+  log(result.summary);
+});
+graph.command("explain").description("Explain a graph node, its page, community, and neighbors.").argument("<target>", "Node/page label or id").action(async (target) => {
+  const result = await explainGraphVault(process.cwd(), target);
+  if (isJson()) {
+    emitJson(result);
+    return;
+  }
+  log(result.summary);
+});
+graph.command("god-nodes").description("List the highest-connectivity non-source graph nodes.").option("--limit <n>", "Maximum number of nodes to return", "10").action(async (options) => {
+  const limit = Number.parseInt(options.limit ?? "10", 10);
+  const result = await listGodNodes(process.cwd(), Number.isFinite(limit) ? limit : 10);
+  if (isJson()) {
+    emitJson(result);
+    return;
+  }
+  for (const node of result) {
+    log(`${node.label} degree=${node.degree ?? 0} bridge=${node.bridgeScore ?? 0}`);
+  }
+});
 var review = program.command("review").description("Review staged compile approval bundles.");
 review.command("list").description("List staged approval bundles and their resolution status.").action(async () => {
   const approvals = await listApprovals(process.cwd());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmvaultai/cli",
-  "version": "0.1.18",
+  "version": "0.1.19",
   "description": "Global CLI for SwarmVault.",
   "type": "module",
   "main": "dist/index.js",
@@ -39,7 +39,7 @@
   },
   "dependencies": {
     "commander": "^14.0.1",
-    "@swarmvaultai/engine": "0.1.18"
+    "@swarmvaultai/engine": "0.1.19"
   },
   "devDependencies": {
     "@types/node": "^24.6.0",