@swarmvaultai/cli 0.7.21 → 0.7.23

package/README.md

@@ -72,6 +72,18 @@ The schema file is the vault-specific instruction layer. Edit it to define namin
 
 `--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` starter profile 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> [--port <port>] [--no-serve]`
+
+Quick-start a scratch vault from a local directory in one command.
+
+- initializes the current directory as a SwarmVault workspace
+- ingests the supplied directory as local sources
+- compiles the vault immediately
+- starts `graph serve` unless you pass `--no-serve`
+- respects `--port` when you want a specific viewer port
+
+Use this when you want the fastest repo or docs-tree walkthrough without first deciding on managed-source registration.
+
 ### `swarmvault source add|list|reload|review|guide|session|delete`
 
 Manage recurring source roots through a registry-backed workflow.
@@ -244,12 +256,14 @@ Set `profile.deepLintDefault: true` when deep lint should be the default for `sw
 
 `--conflicts` filters the results down to contradiction-focused findings so you can audit conflicting claims without the rest of the lint output.
 
-### `swarmvault watch [--lint] [--repo] [--once] [--debounce <ms>]`
+### `swarmvault watch [--lint] [--repo] [--once] [--code-only] [--debounce <ms>]`
 
-Watch the inbox directory and trigger import and compile cycles when files change. With `--repo`, each cycle also refreshes tracked repo roots that were previously ingested through directory ingest. With `--once`, SwarmVault runs one refresh cycle immediately instead of starting a long-running watcher. With `--lint`, each cycle also runs linting. Each cycle writes a canonical session artifact to `state/sessions/`, and compatibility run metadata is still appended to `state/jobs.ndjson`.
+Watch the inbox directory and trigger import and compile cycles when files change. With `--repo`, each cycle also refreshes tracked repo roots that were previously ingested through directory ingest. With `--once`, SwarmVault runs one refresh cycle immediately instead of starting a long-running watcher. With `--code-only`, SwarmVault forces the narrower AST-only refresh path and skips non-code semantic re-analysis until you run a normal `compile`. With `--lint`, each cycle also runs linting. Each cycle writes a canonical session artifact to `state/sessions/`, and compatibility run metadata is still appended to `state/jobs.ndjson`.
 
 When `--repo` sees non-code changes under tracked repo roots, SwarmVault records those files under `state/watch/pending-semantic-refresh.json`, marks affected compiled pages stale, and exposes the pending set through `watch status` and the local graph workspace instead of silently re-ingesting them.
 
+When `--repo` sees only code-file changes under tracked repo roots, SwarmVault takes the faster code-only path: it refreshes code pages and graph structure without re-running non-code semantic analysis for unchanged sources.
+
 ### `swarmvault watch status`
 
 Show watched repo roots, the latest watch run, and any pending semantic refresh entries for tracked non-code repo changes.
@@ -262,7 +276,7 @@ Manage SwarmVault's local git hook blocks for the nearest git repository.
 - `hook uninstall` removes only the SwarmVault-managed hook block
 - `hook status` reports whether those managed hook blocks are installed
 
-The installed hooks run `swarmvault watch --repo --once` from the vault root so repo-aware source changes are re-ingested and recompiled after commit and checkout.
+The installed hooks run `swarmvault watch --repo --once --code-only` from the vault root so commit and checkout refreshes update code pages and graph structure quickly. Run a normal `swarmvault compile` when you also want non-code semantic re-analysis.
 
 ### `swarmvault mcp`
 
@@ -299,14 +313,20 @@ Inspect graph metadata, community membership, neighbors, provenance, and group-p
 
 List the most connected bridge-heavy nodes in the current graph.
 
-### `swarmvault graph export --html|--svg|--graphml|--cypher <output>`
+### `swarmvault graph export --html|--html-standalone|--svg|--graphml|--cypher|--json|--obsidian|--canvas <output>`
 
-Export the current graph as one of four formats:
+Export the current graph as one or more shareable formats:
 
-- `--html` for the standalone read-only graph workspace
+- `--html` for the full self-contained read-only graph workspace
+- `--html-standalone` for a lighter vis.js export with node search, legend, and sidebar inspection
 - `--svg` for a static shareable diagram
 - `--graphml` for graph-tool interoperability
 - `--cypher` for Neo4j-style import scripts
+- `--json` for a deterministic machine-readable graph package
+- `--obsidian` for an Obsidian-friendly markdown vault with one note per node plus community notes
+- `--canvas` for an Obsidian canvas grouped by community
+
+You can combine multiple flags in one run to write several exports at once.
 
 ### `swarmvault graph push neo4j`
 
@@ -331,7 +351,7 @@ Defaults:
 - namespaces every remote record by `vaultId` so multiple vaults can safely share one Neo4j database
 - upserts current graph records and does not prune stale remote data yet
 
-### `swarmvault install --agent <codex|claude|cursor|goose|pi|gemini|opencode|aider|copilot>`
+### `swarmvault install --agent <codex|claude|cursor|goose|pi|gemini|opencode|aider|copilot|trae|claw|droid>`
 
 Install agent-specific rules into the current project so an agent understands the SwarmVault workspace contract and workflow.
 
@@ -352,6 +372,9 @@ Agent target mapping:
 - `aider` writes `CONVENTIONS.md` and merges `.aider.conf.yml`
 - `copilot` writes `.github/copilot-instructions.md` plus `AGENTS.md`
 - `cursor` writes `.cursor/rules/swarmvault.mdc`
+- `trae` writes `.trae/rules/swarmvault.md`
+- `claw` writes `.claw/skills/swarmvault/SKILL.md`
+- `droid` writes `.factory/rules/swarmvault.md`
 
 Hook semantics:
 

package/dist/index.js

@@ -16,6 +16,8 @@ import {
   exploreVault,
   exportGraphFormat,
   exportGraphHtml,
+  exportObsidianCanvas,
+  exportObsidianVault,
   getGitHookStatus,
   getWatchStatus,
   guideManagedSource,
@@ -268,9 +270,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 : "0.7.21";
+    return typeof packageJson.version === "string" && packageJson.version.trim() ? packageJson.version : "0.7.23";
   } catch {
-    return "0.7.21";
+    return "0.7.23";
   }
 }
 function parsePositiveInt(value, fallback) {
@@ -812,29 +814,49 @@ graph.command("serve").description("Serve the local graph viewer.").option("--po
     process2.exit(0);
   });
 });
-graph.command("export").description("Export the graph as HTML, SVG, GraphML, or Cypher. Combine flags to write multiple formats in one run.").option("--html <output>", "Output HTML file path").option("--svg <output>", "Output SVG file path").option("--graphml <output>", "Output GraphML file path").option("--cypher <output>", "Output Cypher file path").option("--full", "Disable overview sampling for HTML export", false).action(async (options) => {
-  const targets = [
-    options.html ? { format: "html", outputPath: options.html } : null,
-    options.svg ? { format: "svg", outputPath: options.svg } : null,
-    options.graphml ? { format: "graphml", outputPath: options.graphml } : null,
-    options.cypher ? { format: "cypher", outputPath: options.cypher } : null
-  ].filter((target) => Boolean(target));
-  if (targets.length === 0) {
-    throw new Error("Pass at least one of --html, --svg, --graphml, or --cypher.");
-  }
-  const results = [];
-  for (const target of targets) {
-    const outputPath = target.format === "html" ? await exportGraphHtml(process2.cwd(), target.outputPath, { full: options.full ?? false }) : (await exportGraphFormat(process2.cwd(), target.format, target.outputPath)).outputPath;
-    results.push({ format: target.format, outputPath });
-  }
-  if (isJson()) {
-    emitJson(results.length === 1 ? results[0] : { exports: results });
-  } else {
-    for (const result of results) {
-      log(`Exported graph ${result.format} to ${result.outputPath}`);
+graph.command("export").description(
+  "Export the graph as HTML, 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("--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", "Disable overview sampling for HTML export", false).action(
+  async (options) => {
+    const targets = [
+      options.html ? { format: "html", outputPath: options.html } : null,
+      options.htmlStandalone ? { format: "html-standalone", outputPath: options.htmlStandalone } : null,
+      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.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, --svg, --graphml, --cypher, --json, --obsidian, or --canvas.");
+    }
+    const results = [];
+    for (const target of targets) {
+      if (target.format === "html") {
+        const outputPath = await exportGraphHtml(process2.cwd(), target.outputPath, { full: options.full ?? false });
+        results.push({ format: target.format, outputPath });
+      } else if (target.format === "obsidian") {
+        const result = await exportObsidianVault(process2.cwd(), target.outputPath);
+        results.push({ format: result.format, outputPath: result.outputPath, fileCount: result.fileCount });
+      } else if (target.format === "canvas") {
+        const result = await exportObsidianCanvas(process2.cwd(), target.outputPath);
+        results.push({ format: result.format, outputPath: result.outputPath });
+      } else {
+        const result = await exportGraphFormat(process2.cwd(), target.format, target.outputPath);
+        results.push({ format: result.format, outputPath: result.outputPath });
+      }
+    }
+    if (isJson()) {
+      emitJson(results.length === 1 ? results[0] : { exports: results });
+    } else {
+      for (const result of results) {
+        const suffix = result.fileCount ? ` (${result.fileCount} files)` : "";
+        log(`Exported graph ${result.format} to ${result.outputPath}${suffix}`);
+      }
     }
   }
-});
+);
 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 ? parsePositiveInt(options.budget, 0) || void 0 : void 0;
   const result = await queryGraphVault(process2.cwd(), question, {
@@ -959,12 +981,13 @@ candidate.command("archive").description("Archive a candidate by removing it fro
     log(`Archived ${result.pageId}`);
   }
 });
-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("--debounce <ms>", "Debounce window in milliseconds", "900").action(async (options) => {
+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").action(async (options) => {
   const debounceMs = parsePositiveInt(options.debounce, 900);
   if (options.once) {
     const result = await runWatchCycle(process2.cwd(), {
       lint: options.lint ?? false,
       repo: options.repo ?? false,
+      codeOnly: options.codeOnly ?? false,
       debounceMs
     });
     if (isJson()) {
@@ -980,6 +1003,7 @@ var watch = program.command("watch").description("Watch the inbox directory and
   const controller = await watchVault(process2.cwd(), {
     lint: options.lint ?? false,
     repo: options.repo ?? false,
+    codeOnly: options.codeOnly ?? false,
     debounceMs
   });
   if (isJson()) {
@@ -1097,7 +1121,7 @@ program.command("mcp").description("Run SwarmVault as a local MCP server over st
     process2.exit(0);
   });
 });
-program.command("install").description("Install SwarmVault instructions for an agent in the current project.").requiredOption("--agent <agent>", "codex, claude, cursor, goose, pi, gemini, opencode, aider, or copilot").option("--hook", "Also install hook/plugin guidance when the target agent supports it", false).action(
+program.command("install").description("Install SwarmVault instructions for an agent in the current project.").requiredOption("--agent <agent>", "codex, claude, cursor, goose, pi, gemini, opencode, aider, copilot, trae, claw, or droid").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"]);
     if (options.hook && !hookCapableAgents.has(options.agent)) {
@@ -1117,6 +1141,39 @@ program.command("install").description("Install SwarmVault instructions for an a
     }
   }
 );
+program.command("scan").description("Quick-start: initialize, ingest, compile, and serve a graph viewer in one command.").argument("<directory>", "Directory to scan").option("--port <port>", "Port for the graph viewer").option("--no-serve", "Skip launching the graph viewer after compile").action(async (directory, options) => {
+  const rootDir = process2.cwd();
+  await initVault(rootDir, {});
+  if (!isJson()) {
+    log("Initialized workspace.");
+  }
+  const result = await ingestDirectory(rootDir, directory, {});
+  if (!isJson()) {
+    log(`Ingested ${result.imported.length} file(s).`);
+  }
+  const compiled = await compileVault(rootDir, {});
+  if (!isJson()) {
+    log(`Compiled ${compiled.sourceCount} source(s), ${compiled.pageCount} page(s).`);
+  }
+  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, 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 });
+  }
+});
 program.parseAsync(process2.argv).catch((error) => {
   const message = error instanceof Error ? error.message : String(error);
   if (isJson()) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmvaultai/cli",
-  "version": "0.7.21",
+  "version": "0.7.23",
   "description": "Global CLI for SwarmVault.",
   "type": "module",
   "main": "dist/index.js",
@@ -38,7 +38,7 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@swarmvaultai/engine": "0.7.21",
+    "@swarmvaultai/engine": "0.7.23",
     "commander": "^14.0.1"
   },
   "devDependencies": {