@swarmvaultai/cli 3.3.0 → 3.5.0

package/README.md

@@ -52,6 +52,7 @@ 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 update .
 swarmvault graph query "Which nodes bridge the biggest clusters?"
 swarmvault graph explain "concept:drift"
 swarmvault watch status
@@ -122,10 +123,11 @@ Run a whole-vault health check before handing the workspace to an agent or openi
 
 - checks workspace config and schema presence
 - reports graph, page, source, review, candidate, task, watch, migration, and retrieval state
+- emits prioritized recommended next actions before the full check list
 - emits suggested follow-up commands for warnings and errors
 - supports `--json` for structured automation output
 - add `--repair` to rebuild safe derived retrieval artifacts
-- the live viewer workbench shows the same checks with details and copyable suggested commands
+- the live viewer workbench shows the same recommendations and checks with details, copyable suggested commands, and safe direct repair
 
 ### `swarmvault source add|list|reload|review|guide|session|delete`
 
@@ -371,6 +373,16 @@ When `--repo` sees only code-file changes under tracked repo roots, SwarmVault t
 
 Show watched repo roots, the latest watch run, and any pending semantic refresh entries for tracked non-code repo changes.
 
+### `swarmvault graph update [path]`
+
+Refresh code-derived graph artifacts from tracked repo roots or one explicit repo path.
+
+- aliases to `swarmvault graph refresh [path]`
+- runs the same code-only repo refresh path as `swarmvault watch --repo --code-only --once`
+- without `path`, uses configured or auto-discovered watched repo roots
+- with `path`, refreshes that repo root instead of the tracked set
+- `--json` returns the same one-shot watch result shape, including repo import/update/remove counts and pending semantic refresh entries
+
 ### `swarmvault hook install|uninstall|status`
 
 Manage SwarmVault's local git hook blocks for the nearest git repository.
@@ -413,8 +425,17 @@ Run SwarmVault as a local MCP server over stdio. This exposes the vault to compa
 - `rebuild_retrieval`
 - `doctor_retrieval`
 - `doctor_vault`
-
-`compile_vault` also accepts `maxTokens` for bounded wiki output, `blast_radius` traces reverse import impact for a file or module target, `build_context_pack` creates the same bounded agent evidence bundles as `swarmvault context build`, the task tools mirror `swarmvault task`, the memory tools mirror the compatibility command group, `doctor_vault` mirrors `swarmvault doctor`, and retrieval tools inspect or repair the local index.
+- `query_graph`
+- `graph_report`
+- `graph_stats`
+- `get_node`
+- `get_community`
+- `get_neighbors`
+- `get_hyperedges`
+- `shortest_path`
+- `god_nodes`
+
+`compile_vault` also accepts `maxTokens` for bounded wiki output, `graph_stats` returns lightweight graph counts, `get_community` resolves community members and pages, `blast_radius` traces reverse import impact for a file or module target, `build_context_pack` creates the same bounded agent evidence bundles as `swarmvault context build`, the task tools mirror `swarmvault task`, the memory tools mirror the compatibility command group, `doctor_vault` mirrors `swarmvault doctor`, and retrieval tools inspect or repair the local index.
 
 The MCP surface also exposes `swarmvault://schema`, `swarmvault://sessions`, `swarmvault://sessions/{path}`, `swarmvault://context-packs`, `swarmvault://tasks`, `swarmvault://memory-tasks`, and includes `schemaPath` in `workspace_info`.
 
@@ -422,9 +443,9 @@ The MCP surface also exposes `swarmvault://schema`, `swarmvault://sessions`, `sw
 
 Start the local graph workspace backed by `state/graph.json`, `/api/search`, `/api/page`, local graph query/path/explain endpoints, and the workbench APIs for doctor, retrieval repair, capture, context packs, task start, and source reload.
 
-The workbench renders every vault doctor check with details, suggested commands that can be copied back to a terminal, safe one-click retrieval repair through `doctor --repair`, selectable capture modes (`ingest`, normalized `add`, or `inbox`), editable token budgets for context packs and task starts, and action receipts after workbench operations complete.
+The workbench renders prioritized vault doctor recommendations, every check with details, suggested commands that can be copied back to a terminal, safe one-click retrieval repair through `doctor --repair`, selectable capture modes (`ingest`, normalized `add`, or `inbox`), title/tag capture fields, editable token budgets for context packs and task starts, and action receipts after workbench operations complete.
 
-It also exposes `/api/bookmarklet` and `/api/clip`, so a running local viewer can capture the current browser URL, selected text, markdown, HTML excerpts, and tags through the workbench or bookmarklet without leaving the browser.
+It also exposes `/api/bookmarklet` and `/api/clip`, so a running local viewer can capture the current browser URL, page title, selected text, markdown, HTML excerpts, and tags through the workbench or bookmarklet without leaving the browser. URL-only bookmarklet clips use normalized `add`; selected text is imported through the inbox path.
 
 ### `swarmvault graph query "<question>" [--dfs] [--budget <n>]`
 
@@ -509,6 +530,7 @@ Install agent-specific rules into the current project so an agent understands th
 Hook-capable installs:
 
 ```bash
+swarmvault install --agent codex --hook
 swarmvault install --agent claude --hook
 swarmvault install --agent gemini --hook
 swarmvault install --agent opencode --hook
@@ -529,6 +551,7 @@ Agent target mapping:
 
 Hook semantics:
 
+- `codex --hook` writes `.codex/hooks.json` plus `.codex/hooks/swarmvault-graph-first.js` and emits model-visible guidance before broad shell search
 - `claude --hook` writes `.claude/settings.json` plus `.claude/hooks/swarmvault-graph-first.js` and adds model-visible advisory context through structured hook JSON
 - `gemini --hook` writes `.gemini/settings.json` plus `.gemini/hooks/swarmvault-graph-first.js` and stays advisory/model-visible
 - `opencode --hook` writes `.opencode/plugins/swarmvault-graph-first.js` and stays advisory/log-only

package/dist/index.js

@@ -309,9 +309,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.3.0";
+    return typeof packageJson.version === "string" && packageJson.version.trim() ? packageJson.version : "3.5.0";
   } catch {
-    return "3.3.0";
+    return "3.5.0";
   }
 }
 function parsePositiveInt(value, fallback) {
@@ -1134,6 +1134,22 @@ 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).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,
+    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}.`
+  );
+});
 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;
@@ -1717,9 +1733,9 @@ program.command("install").description("Install SwarmVault instructions for an a
   "claude, codex, cursor, gemini, goose, opencode, copilot, aider, droid, pi, trae, claw, kiro, hermes, antigravity, vscode, amp, augment, adal, bob, cline, codebuddy, command-code, continue, cortex, crush, deepagents, firebender, iflow, junie, kilo-code, kimi, kode, mcpjam, mistral-vibe, mux, neovate, openclaw, openhands, pochi, qoder, qwen-code, replit, roo-code, trae-cn, warp, windsurf, or zencoder"
 ).option("--hook", "Also install hook/plugin guidance when the target agent supports it", false).action(
   async (options) => {
-    const hookCapableAgents = /* @__PURE__ */ new Set(["claude", "opencode", "gemini", "copilot"]);
+    const hookCapableAgents = /* @__PURE__ */ new Set(["codex", "claude", "opencode", "gemini", "copilot"]);
     if (options.hook && !hookCapableAgents.has(options.agent)) {
-      throw new Error("--hook is only supported for --agent claude, opencode, gemini, or copilot");
+      throw new Error("--hook is only supported for --agent codex, claude, opencode, gemini, or copilot");
     }
     const result = await installAgent(process2.cwd(), options.agent, { hook: options.hook ?? false });
     if (isJson()) {
@@ -2024,6 +2040,16 @@ program.command("doctor").description("Diagnose vault health across graph, retri
   log(
     `Sources ${report.counts.sources} | Managed ${report.counts.managedSources} | Pages ${report.counts.pages} | Nodes ${report.counts.nodes} | Edges ${report.counts.edges}`
   );
+  if (report.recommendations.length) {
+    log("Recommended next actions:");
+    for (const recommendation of report.recommendations) {
+      const action = recommendation.command ? ` ${recommendation.command}` : "";
+      log(`  [${recommendation.priority}] ${recommendation.label}:${action}`);
+      if (recommendation.description) {
+        log(`    ${recommendation.description}`);
+      }
+    }
+  }
   for (const check of report.checks) {
     log(`[${check.status}] ${check.label}: ${check.summary}`);
     if (check.detail) {

package/package.json

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