@swarmvaultai/cli 0.7.24 → 0.7.26

package/README.md

@@ -2,7 +2,7 @@
 
 `@swarmvaultai/cli` is the global command-line entry point for SwarmVault.
 
-It gives you the `swarmvault` command for building a local-first knowledge vault from files, reStructuredText and DOCX documents, URLs, browser clips, saved query outputs, and guided exploration runs.
+It gives you the `swarmvault` command for building a local-first knowledge vault from files, audio transcripts, YouTube URLs, reStructuredText and DOCX documents, browser clips, saved query outputs, and guided exploration runs.
 
 ## Install
 
@@ -24,6 +24,7 @@ mkdir my-vault
 cd my-vault
 swarmvault init --obsidian --profile personal-research
 swarmvault init --obsidian --profile reader,timeline
+swarmvault demo
 swarmvault source add https://github.com/karpathy/micrograd
 swarmvault source add https://example.com/docs/getting-started
 swarmvault source add ./exports/customer-call.srt --guide
@@ -32,20 +33,25 @@ 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 ./repo
 swarmvault add https://arxiv.org/abs/2401.12345
-swarmvault compile
+swarmvault compile --max-tokens 120000
+swarmvault diff
 swarmvault benchmark
-swarmvault query "What keeps recurring?"
+swarmvault query "What keeps recurring?" --commit
 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 query "Which nodes bridge the biggest clusters?"
 swarmvault graph explain "concept:drift"
 swarmvault watch status
 swarmvault watch --repo --once
 swarmvault hook install
 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 push neo4j --dry-run
@@ -84,6 +90,23 @@ Quick-start a scratch vault from a local directory in one command.
 
 Use this when you want the fastest repo or docs-tree walkthrough without first deciding on managed-source registration.
 
+### `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`.
+
+- writes the demo vault under the system temp directory
+- requires no API keys or extra setup
+- is the fastest way to inspect the full init + ingest + compile + graph workflow on a clean machine
+- respects `--port` when you want a specific viewer port
+
+### `swarmvault diff`
+
+Compare the current `state/graph.json` against the last committed graph in git.
+
+- when a prior committed graph exists, prints added and removed nodes, pages, and edges
+- when no git baseline exists, falls back to a summary of the current graph state
+- supports `--json` for structured automation output
+
 ### `swarmvault source add|list|reload|review|guide|session|delete`
 
 Manage recurring source roots through a registry-backed workflow.
@@ -121,7 +144,7 @@ Source-scoped artifacts are intentionally split by role:
 | Source guide | `source guide`, `source add --guide`, `ingest --guide` | Guided walkthrough with approval-bundled updates in `wiki/outputs/source-guides/` |
 | Source session | `source session`, `source add --guide`, `ingest --guide` | Resumable workflow state in `wiki/outputs/source-sessions/` and `state/source-sessions/` |
 
-### `swarmvault ingest <path-or-url>`
+### `swarmvault ingest <path-or-url> [--commit]`
 
 Ingest a local file path, directory path, or URL into immutable source storage and write manifests to `state/manifests/`.
 
@@ -130,7 +153,8 @@ Ingest a local file path, directory path, or URL into immutable source storage a
 - repo-aware directory ingest records `repoRelativePath` and later compile writes `state/code-index.json`
 - use `source add` instead when the same local directory, public GitHub repo root, or docs hub should stay registered and reloadable
 - URL ingest still localizes remote image references by default
-- local file and archive ingest supports markdown, text, reStructuredText, HTML, PDF, Word, RTF, OpenDocument, EPUB, CSV/TSV, Excel, PowerPoint, Jupyter notebooks, BibTeX, Org-mode, AsciiDoc, transcripts, Slack exports, email, calendar, structured config/data, developer manifests, images, and code
+- YouTube URLs short-circuit to direct transcript capture instead of generic HTML fetch
+- local file and archive ingest supports markdown, text, reStructuredText, HTML, PDF, Word, RTF, OpenDocument, EPUB, CSV/TSV, Excel, PowerPoint, Jupyter notebooks, BibTeX, Org-mode, AsciiDoc, transcripts, Slack exports, email, calendar, audio, structured config/data, developer manifests, images, and code
 - add `--guide` when you want a resumable source session, source brief, source review, source guide, and approval-bundled canonical page edits when `profile.guidedSessionMode` is `canonical_review`, with `wiki/insights/` fallback for `insights_only`
 - set `profile.guidedIngestDefault: true` when guided mode should be the default for `ingest`, and use `--no-guide` to force a plain ingest for one run
 - code-aware directory ingest currently covers JavaScript, JSX, TypeScript, TSX, Bash/shell scripts, Python, Go, Rust, Java, Kotlin, Scala, Dart, Lua, Zig, C#, C, C++, PHP, Ruby, PowerShell, Elixir, OCaml, Objective-C, ReScript, Solidity, HTML, CSS, and Vue single-file components
@@ -149,11 +173,16 @@ Useful flags:
 - `--no-gitignore`
 - `--no-include-assets`
 - `--max-asset-size <bytes>`
+- `--commit`
 
 Repo ingest defaults to `first_party` material. The extra `--include-*` flags opt dependency trees, resource bundles, and generated output back in when you actually want them in the vault.
 
 Large repo ingest now emits low-noise progress on materially large batches, and parser compatibility failures stay local to the affected source instead of aborting unrelated analysis.
 
+Audio files use `tasks.audioProvider` when you configure a provider with `audio` capability. When no such provider is configured, SwarmVault still ingests the source and records an explicit extraction warning instead of failing. YouTube transcript ingest does not require a model provider.
+
+When `--commit` is set, SwarmVault stages `wiki/` and `state/` changes and creates a git commit when the vault root is inside a git worktree. Outside git, it becomes a no-op instead of failing.
+
 ### `swarmvault add <url>`
 
 Capture supported URLs through a normalized markdown layer before ingesting them into the vault.
@@ -171,7 +200,7 @@ Capture supported URLs through a normalized markdown layer before ingesting them
 
 Import supported files from the configured inbox directory. This is meant for browser-clipper style markdown bundles, HTML clip bundles, and other capture workflows. Local image and asset references are preserved and copied into canonical storage under `raw/assets/`.
 
-### `swarmvault compile [--approve]`
+### `swarmvault compile [--approve] [--commit] [--max-tokens <n>]`
 
 Compile the current manifests into:
 
@@ -187,6 +216,14 @@ New concept and entity pages are staged into `wiki/candidates/` first. A later m
 
 With `--approve`, compile writes a staged review bundle into `state/approvals/` without applying active wiki changes.
 
+Useful flags:
+
+- `--approve`
+- `--commit`
+- `--max-tokens <n>`
+
+`--max-tokens <n>` keeps the generated wiki inside a bounded token budget by dropping lower-priority pages from final `wiki/` output and reporting token-budget stats in the compile result. `--commit` immediately commits `wiki/` and `state/` changes when the vault lives in a git repo.
+
 ### `swarmvault benchmark [--question "<text>" ...]`
 
 Measure graph-guided context reduction against a naive full-corpus read.
@@ -218,7 +255,7 @@ Inspect and resolve staged concept and entity candidates.
 
 Targets can be page ids or relative paths under `wiki/candidates/`.
 
-### `swarmvault query "<question>" [--no-save] [--format markdown|report|slides|chart|image]`
+### `swarmvault query "<question>" [--no-save] [--commit] [--format markdown|report|slides|chart|image]`
 
 Query the compiled vault. The query layer also reads `swarmvault.schema.md`, so answers follow the vault’s own structure and grounding rules.
 
@@ -233,6 +270,8 @@ Saved outputs also carry related page, node, and source metadata so SwarmVault c
 
 Human-authored pages in `wiki/insights/` are also indexed into search and query context, but SwarmVault does not rewrite them after initialization.
 
+By default, query uses the local SQLite search index. When an embedding-capable provider is available and `search.hybrid` is not disabled, semantic page matches are fused into the same candidate set before answer generation. `tasks.embeddingProvider` is the explicit way to choose that backend, but SwarmVault can also fall back to a `queryProvider` with embeddings support. Set `search.rerank: true` when you want the configured `queryProvider` to rerank the merged top hits. `--commit` immediately commits saved `wiki/` and `state/` changes when the vault root is inside a git repo.
+
 ### `swarmvault explore "<question>" [--steps <n>] [--format markdown|report|slides|chart|image]`
 
 Run a save-first multi-step research loop.
@@ -299,6 +338,9 @@ Run SwarmVault as a local MCP server over stdio. This exposes the vault to compa
 - `ingest_input`
 - `compile_vault`
 - `lint_vault`
+- `blast_radius`
+
+`compile_vault` also accepts `maxTokens` for bounded wiki output, and `blast_radius` traces reverse import impact for a file or module target.
 
 The MCP surface also exposes `swarmvault://schema`, `swarmvault://sessions`, `swarmvault://sessions/{path}`, and includes `schemaPath` in `workspace_info`.
 
@@ -306,6 +348,8 @@ The MCP surface also exposes `swarmvault://schema`, `swarmvault://sessions`, `sw
 
 Start the local graph workspace backed by `state/graph.json`, `/api/search`, `/api/page`, and local graph query/path/explain endpoints.
 
+It also exposes `/api/bookmarklet` and `/api/clip`, so a running local viewer can ingest the current browser page through a bookmarklet without leaving the browser.
+
 ### `swarmvault graph query "<question>" [--dfs] [--budget <n>]`
 
 Run a deterministic local graph traversal seeded from local search, graph labels, and matching group patterns.
@@ -322,21 +366,32 @@ 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|--html-standalone|--svg|--graphml|--cypher|--json|--obsidian|--canvas <output>`
+### `swarmvault graph blast <target> [--depth <n>]`
+
+Trace the reverse-import blast radius of changing a file or module.
+
+- accepts a file path, module label, or module id
+- follows reverse `imports` edges through the compiled graph
+- reports affected modules by depth so you can estimate downstream impact before editing
+
+### `swarmvault graph export --html|--html-standalone|--report|--svg|--graphml|--cypher|--json|--obsidian|--canvas <output>`
 
 Export the current graph as one or more shareable formats:
 
 - `--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
+- `--report` for a self-contained HTML graph report with stats, key nodes, communities, and warnings
 - `--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
+- `--obsidian` for an Obsidian-friendly markdown vault that preserves wiki folders, appends graph connections, emits orphan-node stubs and community notes, copies assets, and writes a minimal `.obsidian/` config
 - `--canvas` for an Obsidian canvas grouped by community
 
 You can combine multiple flags in one run to write several exports at once.
 
+Set `graph.communityResolution` in `swarmvault.config.json` when you want to pin the Louvain clustering resolution used by graph reports and Obsidian community output instead of relying on the adaptive default.
+
 ### `swarmvault graph push neo4j`
 
 Push the compiled graph directly into Neo4j over Bolt/Aura instead of writing an intermediate file.
@@ -463,6 +518,20 @@ Deep lint web augmentation uses a separate `webSearch` config block. Example:
 }
 ```
 
+Search behavior is configurable separately from provider routing:
+
+```json
+{
+  "search": {
+    "hybrid": true,
+    "rerank": false
+  }
+}
+```
+
+- `search.hybrid` defaults to enabled and merges full-text hits with semantic page matches when an embedding-capable provider is available
+- `search.rerank` optionally asks the current `queryProvider` to rerank the merged top hits before query answers are generated
+
 ## Troubleshooting
 
 - If you are running from a source checkout and `graph serve` says the viewer build is missing, run `pnpm build` in the repository first

package/dist/index.js

@@ -2,6 +2,7 @@
 
 // src/index.ts
 import { readFileSync } from "fs";
+import { readFile as readFile2 } from "fs/promises";
 import process2 from "process";
 import { createInterface } from "readline/promises";
 import {
@@ -9,17 +10,21 @@ import {
   addInput,
   addManagedSource,
   archiveCandidate,
+  autoCommitWikiChanges,
   benchmarkVault,
+  blastRadiusVault,
   compileVault,
   deleteManagedSource,
   explainGraphVault,
   exploreVault,
   exportGraphFormat,
   exportGraphHtml,
+  exportGraphReportHtml,
   exportObsidianCanvas,
   exportObsidianVault,
   getGitHookStatus,
   getWatchStatus,
+  graphDiff,
   guideManagedSource,
   guideSourceScope,
   importInbox,
@@ -266,13 +271,14 @@ function normalizeVersion(version) {
 // src/index.ts
 var program = new Command();
 var CLI_VERSION = readCliVersion();
-program.name("swarmvault").description("SwarmVault is a local-first knowledge compiler with graph outputs and optional provider-backed workflows.").version(CLI_VERSION).option("--json", "Emit structured JSON output", false);
+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);
 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.24";
+    return typeof packageJson.version === "string" && packageJson.version.trim() ? packageJson.version : "0.7.26";
   } catch {
-    return "0.7.24";
+    return "0.7.26";
   }
 }
 function parsePositiveInt(value, fallback) {
@@ -296,7 +302,7 @@ function slugForCli(value) {
   return value.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "source";
 }
 function isJson() {
-  return program.opts().json === true;
+  return activeCommand?.opts().json === true || program.opts().json === true;
 }
 function emitJson(data) {
   process2.stdout.write(`${JSON.stringify(data)}
@@ -429,7 +435,7 @@ program.command("init").description("Initialize a SwarmVault workspace in the cu
     log("Initialized SwarmVault workspace.");
   }
 });
-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").action(
+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("--commit", "Auto-commit wiki and state changes after ingest").action(
   async (input, options) => {
     const guideAnswers = readGuideAnswersFile(options.answersFile);
     const vaultConfig = await loadVaultConfig(process2.cwd()).catch(() => null);
@@ -502,6 +508,10 @@ program.command("ingest").description("Ingest a local file path, directory path,
           log(`Staged guided session at ${completedGuide2.guidePath}.`);
         }
       }
+      if (options.commit) {
+        const msg = await autoCommitWikiChanges(process2.cwd(), "ingest", input, { force: true });
+        if (msg && !isJson()) log(`Committed: ${msg}`);
+      }
       return;
     }
     const ingest = await ingestInputDetailed(process2.cwd(), input, commonOptions);
@@ -537,6 +547,10 @@ program.command("ingest").description("Ingest a local file path, directory path,
         log(`Staged guided session at ${completedGuide.guidePath}.`);
       }
     }
+    if (options.commit) {
+      const msg = await autoCommitWikiChanges(process2.cwd(), "ingest", input, { force: true });
+      if (msg && !isJson()) log(`Committed: ${msg}`);
+    }
   }
 );
 program.command("add").description("Capture supported URLs into normalized markdown before ingesting them.").argument("<input>", "Supported URL or bare arXiv id").option("--author <name>", "Human author or curator for this capture").option("--contributor <name>", "Additional contributor metadata for this capture").action(async (input, options) => {
@@ -674,8 +688,9 @@ inbox.command("import").description("Import supported files from the configured
     );
   }
 });
-program.command("compile").description("Compile manifests into wiki pages, graph JSON, and search index.").option("--approve", "Stage a review bundle without applying active page changes", false).action(async (options) => {
-  const result = await compileVault(process2.cwd(), { approve: options.approve ?? false });
+program.command("compile").description("Compile manifests into wiki pages, graph JSON, and search index.").option("--approve", "Stage a review bundle without applying active page changes", false).option("--commit", "Auto-commit wiki and state changes after compile").option("--max-tokens <n>", "Cap wiki output by trimming lower-priority pages").action(async (options) => {
+  const maxTokens = options.maxTokens ? parsePositiveInt(options.maxTokens, 0) || void 0 : void 0;
+  const result = await compileVault(process2.cwd(), { approve: options.approve ?? false, maxTokens });
   if (isJson()) {
     emitJson(result);
   } else {
@@ -684,27 +699,44 @@ program.command("compile").description("Compile manifests into wiki pages, graph
     } else {
       log(`Compiled ${result.sourceCount} source(s), ${result.pageCount} page(s). Changed: ${result.changedPages.length}.`);
     }
+    if (result.tokenStats) {
+      log(
+        `Token budget: ~${result.tokenStats.estimatedTokens} tokens, kept ${result.tokenStats.pagesKept} pages, dropped ${result.tokenStats.pagesDropped}.`
+      );
+    }
+  }
+  if (options.commit) {
+    const msg = await autoCommitWikiChanges(process2.cwd(), "compile", `${result.sourceCount} sources, ${result.pageCount} pages`, {
+      force: true
+    });
+    if (msg && !isJson()) log(`Committed: ${msg}`);
   }
   await maybeEmitHeuristicNotice(["compile"]);
 });
-program.command("query").description("Query the compiled SwarmVault wiki.").argument("<question>", "Question to ask SwarmVault").option("--no-save", "Do not persist the answer to wiki/outputs").addOption(
+program.command("query").description("Query the compiled SwarmVault wiki.").argument("<question>", "Question to ask SwarmVault").option("--no-save", "Do not persist the answer to wiki/outputs").option("--commit", "Auto-commit wiki changes after query").addOption(
   new Option("--format <format>", "Output format").choices(["markdown", "report", "slides", "chart", "image"]).default("markdown")
-).action(async (question, options) => {
-  const result = await queryVault(process2.cwd(), {
-    question,
-    save: options.save ?? true,
-    format: options.format
-  });
-  if (isJson()) {
-    emitJson(result);
-  } else {
-    log(result.answer);
-    if (result.savedPath) {
-      log(`Saved to ${result.savedPath}`);
+).action(
+  async (question, options) => {
+    const result = await queryVault(process2.cwd(), {
+      question,
+      save: options.save ?? true,
+      format: options.format
+    });
+    if (isJson()) {
+      emitJson(result);
+    } else {
+      log(result.answer);
+      if (result.savedPath) {
+        log(`Saved to ${result.savedPath}`);
+      }
+    }
+    if (options.commit) {
+      const msg = await autoCommitWikiChanges(process2.cwd(), "query", question.slice(0, 72), { force: true });
+      if (msg && !isJson()) log(`Committed: ${msg}`);
     }
+    await maybeEmitHeuristicNotice(["query"]);
   }
-  await maybeEmitHeuristicNotice(["query"]);
-});
+);
 program.command("explore").description("Run a save-first multi-step exploration loop against the vault.").argument("<question>", "Root question to explore").option("--steps <n>", "Maximum number of exploration steps", "3").addOption(
   new Option("--format <format>", "Output format for step pages").choices(["markdown", "report", "slides", "chart", "image"]).default("markdown")
 ).action(async (question, options) => {
@@ -760,7 +792,7 @@ program.command("lint").description("Run anti-drift and wiki-health checks.").op
     log(`[${finding.severity}] ${finding.code}: ${finding.message}${finding.pagePath ? ` (${finding.pagePath})` : ""}`);
   }
 });
-var graph = program.command("graph").description("Graph-related commands.");
+var graph = program.command("graph").description("Graph-related commands.").enablePositionalOptions();
 var graphPush = graph.command("push").description("Push the compiled graph into external sinks.");
 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) => {
@@ -805,6 +837,7 @@ graph.command("serve").description("Serve the local graph viewer.").option("--po
     emitJson({ port: server.port, url: `http://localhost:${server.port}` });
   } else {
     log(`Graph viewer running at http://localhost:${server.port}`);
+    log(`Browser clipper: http://localhost:${server.port}/api/bookmarklet`);
   }
   process2.on("SIGINT", async () => {
     try {
@@ -815,12 +848,13 @@ graph.command("serve").description("Serve the local graph viewer.").option("--po
   });
 });
 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(
+  "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", "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.report ? { format: "report", outputPath: options.report } : 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,
@@ -829,13 +863,18 @@ graph.command("export").description(
       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.");
+      throw new Error(
+        "Pass at least one of --html, --html-standalone, --report, --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 === "report") {
+        const result = await exportGraphReportHtml(process2.cwd(), target.outputPath);
+        results.push({ format: result.format, outputPath: result.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 });
@@ -896,6 +935,18 @@ graph.command("god-nodes").description("List the highest-connectivity non-source
     log(`${node.label} degree=${node.degree ?? 0} bridge=${node.bridgeScore ?? 0}`);
   }
 });
+graph.command("blast").description("Show the blast radius of changing a file or module.").argument("<target>", "File path, module label, or module id").option("--depth <n>", "Maximum traversal depth", "3").action(async (target, options) => {
+  const depth = parsePositiveInt(options.depth, 3);
+  const result = await blastRadiusVault(process2.cwd(), target, { maxDepth: depth });
+  if (isJson()) {
+    emitJson(result);
+    return;
+  }
+  log(result.summary);
+  for (const mod of result.affectedModules) {
+    log(`  ${"  ".repeat(mod.depth - 1)}${mod.label} (depth ${mod.depth})`);
+  }
+});
 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(process2.cwd());
@@ -1141,6 +1192,269 @@ program.command("install").description("Install SwarmVault instructions for an a
     }
   }
 );
+program.command("demo").description("Try SwarmVault with a bundled sample vault \u2014 zero config, zero API keys.").option("--port <port>", "Port for the graph viewer").option("--no-serve", "Skip launching the graph viewer after compile").action(async (options) => {
+  const { mkdtemp, writeFile: writeFile2, mkdir: mkdir2 } = await import("fs/promises");
+  const { tmpdir } = await import("os");
+  const path2 = await import("path");
+  const demoDir = await mkdtemp(path2.join(tmpdir(), "swarmvault-demo-"));
+  if (!isJson()) {
+    log(`Creating demo vault in ${demoDir}`);
+  }
+  const rawDir = path2.join(demoDir, "raw", "sources");
+  await mkdir2(rawDir, { recursive: true });
+  await writeFile2(
+    path2.join(rawDir, "llm-wiki-pattern.md"),
+    [
+      "# The LLM Wiki Pattern",
+      "",
+      "Most AI tools answer a question then throw away the work. The LLM Wiki pattern",
+      "keeps a durable wiki between you and raw sources. The LLM does the bookkeeping \u2014",
+      "updating cross-references, noting contradictions, maintaining consistency \u2014 while",
+      "you do the thinking.",
+      "",
+      "## Three Layers",
+      "",
+      "1. **Raw sources** \u2014 immutable documents: books, articles, papers, transcripts, code.",
+      "2. **The wiki** \u2014 LLM-generated markdown: summaries, entity pages, concept pages, cross-references.",
+      "3. **The schema** \u2014 rules for how the wiki is organized and what matters in your domain.",
+      "",
+      "## Why This Beats RAG",
+      "",
+      "RAG re-derives knowledge on every query. The wiki compiles knowledge once and compounds",
+      "it over time. Good answers get filed back as new pages, so exploration builds on itself.",
+      "",
+      "## Key Operations",
+      "",
+      "- **Ingest** \u2014 read a source, write summaries, update cross-references",
+      "- **Query** \u2014 search the wiki, synthesize answers, file results back",
+      "- **Lint** \u2014 health-check for contradictions, orphans, stale claims",
+      ""
+    ].join("\n")
+  );
+  await writeFile2(
+    path2.join(rawDir, "knowledge-graphs.md"),
+    [
+      "# Knowledge Graphs for AI",
+      "",
+      "A knowledge graph represents information as typed nodes and edges with provenance.",
+      "Unlike flat document stores, graphs let you traverse relationships, detect communities,",
+      "and find surprising connections between concepts.",
+      "",
+      "## Node Types",
+      "",
+      "- **Sources** \u2014 the raw documents that feed the graph",
+      "- **Concepts** \u2014 abstract ideas extracted from sources",
+      "- **Entities** \u2014 named things: people, tools, organizations",
+      "- **Modules** \u2014 code units with import/export relationships",
+      "",
+      "## Edge Semantics",
+      "",
+      "Every edge carries an evidence class: `extracted` (directly found), `inferred`",
+      "(derived by reasoning), or `conflicted` (contradictory evidence). This provenance",
+      "tracking prevents hallucination from compounding silently.",
+      "",
+      "## Contradiction Detection",
+      "",
+      "When two sources make conflicting claims, the graph flags the contradiction rather",
+      "than silently picking one. This is critical for research wikis where outdated claims",
+      "from older papers may conflict with newer findings.",
+      "",
+      "RAG systems do not track contradictions because they re-derive everything per query.",
+      "A compiled wiki with a graph layer can detect and surface them automatically.",
+      ""
+    ].join("\n")
+  );
+  await writeFile2(
+    path2.join(rawDir, "local-first-tools.md"),
+    [
+      "# Local-First AI Tools",
+      "",
+      "Local-first means your data stays on your machine by default. No cloud dependency,",
+      "no API keys required for basic operation. Privacy is the default, not an option.",
+      "",
+      "## Advantages",
+      "",
+      "- **Privacy** \u2014 sensitive documents never leave your machine",
+      "- **Speed** \u2014 no network latency for search and graph operations",
+      "- **Reliability** \u2014 works offline, no service outages",
+      "- **Cost** \u2014 no per-query API charges for basic workflows",
+      "",
+      "## The Heuristic Provider",
+      "",
+      "A heuristic provider uses deterministic text analysis \u2014 keyword extraction, TF-IDF,",
+      "structural parsing \u2014 instead of LLM inference. It produces lower-quality summaries",
+      "but runs instantly with zero setup. This makes it ideal for first-run experiences",
+      "and air-gapped environments.",
+      "",
+      "For sharper concept extraction, pair with a local LLM via Ollama. This keeps",
+      "everything on-device while getting model-backed analysis.",
+      ""
+    ].join("\n")
+  );
+  await initVault(demoDir, {});
+  await ingestDirectory(demoDir, rawDir, {});
+  await compileVault(demoDir, {});
+  const { paths } = await loadVaultConfig(demoDir);
+  let graphStats = "";
+  try {
+    const raw = await readFile2(paths.graphPath, "utf-8");
+    const graph2 = JSON.parse(raw);
+    graphStats = ` (${graph2.nodes.length} nodes, ${graph2.edges.length} edges)`;
+  } catch {
+  }
+  if (!isJson()) {
+    log("");
+    log(`Demo vault created${graphStats}.`);
+    log("");
+    log("What just happened:");
+    log("  1. Created 3 sample sources about LLM wikis, knowledge graphs, and local-first tools");
+    log("  2. Ingested and compiled them into a knowledge graph");
+    log("  3. Generated wiki pages with cross-references and a graph report");
+    log("");
+    log(`Vault location: ${demoDir}`);
+  }
+  if (options.serve !== false) {
+    const port = options.port ? parsePositiveInt(options.port, 0) || void 0 : void 0;
+    const server = await startGraphServer(demoDir, port, { full: false });
+    if (isJson()) {
+      emitJson({ demoDir, graphStats: graphStats.trim(), port: server.port, url: `http://localhost:${server.port}` });
+    } else {
+      log(`Graph viewer running at http://localhost:${server.port}`);
+      log("");
+      log("Try next:");
+      log(`  cd ${demoDir}`);
+      log('  swarmvault query "How does contradiction detection work?"');
+      log("  swarmvault lint");
+    }
+    process2.on("SIGINT", async () => {
+      try {
+        await server.close();
+      } catch {
+      }
+      process2.exit(0);
+    });
+  } else if (isJson()) {
+    emitJson({ demoDir, graphStats: graphStats.trim() });
+  } else {
+    log("");
+    log("Try next:");
+    log(`  cd ${demoDir}`);
+    log("  swarmvault graph serve");
+    log('  swarmvault query "How does contradiction detection work?"');
+  }
+});
+program.command("diff").description("Show what changed in the knowledge graph since the last compile.").action(async () => {
+  const rootDir = process2.cwd();
+  const { paths } = await loadVaultConfig(rootDir);
+  let currentGraph;
+  try {
+    const raw = await readFile2(paths.graphPath, "utf-8");
+    currentGraph = JSON.parse(raw);
+  } catch {
+    if (isJson()) {
+      emitJson({ error: "No compiled graph found. Run swarmvault compile first." });
+    } else {
+      log("No compiled graph found. Run swarmvault compile first.");
+    }
+    return;
+  }
+  let previousGraph;
+  const { execFileSync } = await import("child_process");
+  try {
+    const relPath = paths.graphPath.replace(`${rootDir}/`, "");
+    const previousRaw = execFileSync("git", ["show", `HEAD:${relPath}`], {
+      cwd: rootDir,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    previousGraph = JSON.parse(previousRaw);
+  } catch {
+  }
+  if (!previousGraph) {
+    if (isJson()) {
+      emitJson({
+        status: "no-baseline",
+        current: {
+          nodes: currentGraph.nodes.length,
+          edges: currentGraph.edges.length,
+          pages: currentGraph.pages.length,
+          communities: currentGraph.communities?.length ?? 0
+        }
+      });
+    } else {
+      log("No previous graph found (not in a git repo or no prior commit).");
+      log("");
+      log("Current graph:");
+      log(`  ${currentGraph.nodes.length} nodes, ${currentGraph.edges.length} edges, ${currentGraph.pages.length} pages`);
+      if (currentGraph.communities?.length) {
+        log(`  ${currentGraph.communities.length} communities`);
+      }
+      const conflicted = currentGraph.edges.filter((e) => e.status === "conflicted");
+      if (conflicted.length) {
+        log(`  ${conflicted.length} conflicted edges`);
+      }
+    }
+    return;
+  }
+  const diff = graphDiff(previousGraph, currentGraph);
+  if (isJson()) {
+    emitJson(diff);
+    return;
+  }
+  if (diff.summary === "No changes") {
+    log("No changes since last commit.");
+    return;
+  }
+  log(diff.summary);
+  log("");
+  if (diff.addedNodes.length) {
+    log("Added nodes:");
+    for (const node of diff.addedNodes) {
+      log(`  + [${node.type}] ${node.label}`);
+    }
+    log("");
+  }
+  if (diff.removedNodes.length) {
+    log("Removed nodes:");
+    for (const node of diff.removedNodes) {
+      log(`  - [${node.type}] ${node.label}`);
+    }
+    log("");
+  }
+  if (diff.addedPages.length) {
+    log("Added pages:");
+    for (const page of diff.addedPages) {
+      log(`  + [${page.kind}] ${page.title} (${page.path})`);
+    }
+    log("");
+  }
+  if (diff.removedPages.length) {
+    log("Removed pages:");
+    for (const page of diff.removedPages) {
+      log(`  - [${page.kind}] ${page.title} (${page.path})`);
+    }
+    log("");
+  }
+  if (diff.addedEdges.length) {
+    log(`Added edges: ${diff.addedEdges.length}`);
+    for (const edge of diff.addedEdges.slice(0, 20)) {
+      log(`  + ${edge.source} -[${edge.relation}]-> ${edge.target} (${edge.evidenceClass})`);
+    }
+    if (diff.addedEdges.length > 20) {
+      log(`  ... and ${diff.addedEdges.length - 20} more`);
+    }
+    log("");
+  }
+  if (diff.removedEdges.length) {
+    log(`Removed edges: ${diff.removedEdges.length}`);
+    for (const edge of diff.removedEdges.slice(0, 20)) {
+      log(`  - ${edge.source} -[${edge.relation}]-> ${edge.target}`);
+    }
+    if (diff.removedEdges.length > 20) {
+      log(`  ... and ${diff.removedEdges.length - 20} more`);
+    }
+  }
+});
 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, {});
@@ -1174,6 +1488,19 @@ program.command("scan").description("Quick-start: initialize, ingest, compile, a
     emitJson({ ...result, compiled });
   }
 });
+function enableStructuredJsonOnSubcommands(command) {
+  for (const subcommand of command.commands) {
+    const hasJsonOption = subcommand.options.some((option) => option.attributeName() === "json");
+    if (!hasJsonOption) {
+      subcommand.option("--json", "Emit structured JSON output", false);
+    }
+    enableStructuredJsonOnSubcommands(subcommand);
+  }
+}
+enableStructuredJsonOnSubcommands(program);
+program.hook("preAction", (_command, actionCommand) => {
+  activeCommand = actionCommand;
+});
 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.24",
+  "version": "0.7.26",
   "description": "Global CLI for SwarmVault.",
   "type": "module",
   "main": "dist/index.js",
@@ -38,7 +38,7 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@swarmvaultai/engine": "0.7.24",
+    "@swarmvaultai/engine": "0.7.26",
     "commander": "^14.0.1"
   },
   "devDependencies": {