@swarmvaultai/cli 0.7.24 → 0.7.25

package/README.md

@@ -34,18 +34,20 @@ sed -n '1,120p' swarmvault.schema.md
 swarmvault ingest ./notes.md
 swarmvault ingest ./repo
 swarmvault add https://arxiv.org/abs/2401.12345
-swarmvault compile
+swarmvault compile --max-tokens 120000
 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
@@ -121,7 +123,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/`.
 
@@ -149,11 +151,14 @@ 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.
 
+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 +176,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 +192,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 +231,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 +246,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 +314,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 +324,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,12 +342,21 @@ 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
@@ -463,6 +492,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

@@ -9,13 +9,16 @@ import {
   addInput,
   addManagedSource,
   archiveCandidate,
+  autoCommitWikiChanges,
   benchmarkVault,
+  blastRadiusVault,
   compileVault,
   deleteManagedSource,
   explainGraphVault,
   exploreVault,
   exportGraphFormat,
   exportGraphHtml,
+  exportGraphReportHtml,
   exportObsidianCanvas,
   exportObsidianVault,
   getGitHookStatus,
@@ -270,9 +273,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.24";
+    return typeof packageJson.version === "string" && packageJson.version.trim() ? packageJson.version : "0.7.25";
   } catch {
-    return "0.7.24";
+    return "0.7.25";
   }
 }
 function parsePositiveInt(value, fallback) {
@@ -429,7 +432,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 +505,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 +544,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 +685,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 +696,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) => {
@@ -805,6 +834,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 +845,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 +860,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 +932,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());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmvaultai/cli",
-  "version": "0.7.24",
+  "version": "0.7.25",
   "description": "Global CLI for SwarmVault.",
   "type": "module",
   "main": "dist/index.js",
@@ -37,18 +37,19 @@
   "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.24",
+    "@swarmvaultai/engine": "0.7.25",
     "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"
   }
-}
+}

package/LICENSE

@@ -1,21 +0,0 @@
-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.