@swarmvaultai/cli 0.7.25 → 0.7.26

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SwarmVault
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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,9 +33,12 @@ 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 --max-tokens 120000
+swarmvault diff
 swarmvault benchmark
 swarmvault query "What keeps recurring?" --commit
 swarmvault query "Turn this into slides" --format slides
@@ -86,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.
@@ -132,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
@@ -157,6 +179,8 @@ Repo ingest defaults to `first_party` material. The extra `--include-*` flags op
 
 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>`
@@ -361,11 +385,13 @@ Export the current graph as one or more shareable formats:
 - `--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.

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 {
@@ -23,6 +24,7 @@ import {
   exportObsidianVault,
   getGitHookStatus,
   getWatchStatus,
+  graphDiff,
   guideManagedSource,
   guideSourceScope,
   importInbox,
@@ -269,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.25";
+    return typeof packageJson.version === "string" && packageJson.version.trim() ? packageJson.version : "0.7.26";
   } catch {
-    return "0.7.25";
+    return "0.7.26";
   }
 }
 function parsePositiveInt(value, fallback) {
@@ -299,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)}
@@ -789,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) => {
@@ -1189,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, {});
@@ -1222,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.25",
+  "version": "0.7.26",
   "description": "Global CLI for SwarmVault.",
   "type": "module",
   "main": "dist/index.js",
@@ -37,19 +37,18 @@
   "engines": {
     "node": ">=24.0.0"
   },
-  "scripts": {
-    "build": "tsup src/index.ts --format esm --dts",
-    "test": "vitest run",
-    "typecheck": "tsc --noEmit",
-    "prepublishOnly": "node ../../scripts/check-release-sync.mjs && node ../../scripts/check-published-manifests.mjs"
-  },
   "dependencies": {
-    "@swarmvaultai/engine": "0.7.25",
+    "@swarmvaultai/engine": "0.7.26",
     "commander": "^14.0.1"
   },
   "devDependencies": {
     "@types/node": "^24.6.0",
     "tsup": "^8.5.0",
     "vitest": "^3.2.4"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
   }
-}
+}