@swarmvaultai/cli 3.14.1 → 3.15.0

package/README.md

@@ -105,25 +105,26 @@ Set `SWARMVAULT_OUT=<dir>` when generated artifacts should be isolated from the
 
 `--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` preset 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 quickstart <directory|github-url> [--port <port>] [--no-serve] [--no-viz] [--mcp] [--branch <name>] [--ref <ref>] [--checkout-dir <path>]`
+### `swarmvault quickstart <file|directory|github-url> [--port <port>] [--no-serve] [--no-viz] [--mcp] [--branch <name>] [--ref <ref>] [--checkout-dir <path>] [--install-agent-rules]`
 
 Beginner-friendly alias for `swarmvault scan`.
 
 - initializes the current directory as a SwarmVault workspace
-- ingests the supplied local directory, or registers/syncs the supplied public GitHub repo root URL
+- ingests the supplied local file or directory, or registers/syncs the supplied public GitHub repo root URL
 - compiles wiki, graph, search, and share artifacts immediately
 - prints the generated `raw/`, `wiki/`, `state/graph.json`, and `wiki/graph/` paths in human output
 - starts `graph serve` unless you pass `--no-serve` or `--no-viz`
 - keeps the same JSON output contract as `scan`
+- leaves agent rule files alone unless you pass `--install-agent-rules`
 
 Use this as the default first-run command in docs and onboarding.
 
-### `swarmvault scan <directory|github-url> [--port <port>] [--no-serve] [--no-viz] [--mcp] [--branch <name>] [--ref <ref>] [--checkout-dir <path>]`
+### `swarmvault scan <file|directory|github-url> [--port <port>] [--no-serve] [--no-viz] [--mcp] [--branch <name>] [--ref <ref>] [--checkout-dir <path>] [--install-agent-rules]`
 
-Quick-start a scratch vault from a local directory or public GitHub repo root URL in one command.
+Quick-start a scratch vault from a local file, directory, or public GitHub repo root URL in one command.
 
 - initializes the current directory as a SwarmVault workspace
-- ingests the supplied directory as local sources, or registers/syncs the supplied public GitHub repo root URL
+- ingests the supplied file or directory as local sources, or registers/syncs the supplied public GitHub repo root URL
 - compiles the vault immediately
 - writes `wiki/graph/share-card.md`, `wiki/graph/share-card.svg`, and `wiki/graph/share-kit/`, then prints the paths
 - starts `graph serve` unless you pass `--no-serve` or `--no-viz`
@@ -131,10 +132,11 @@ Quick-start a scratch vault from a local directory or public GitHub repo root UR
 - `--mcp` starts the MCP stdio server after compile instead of the graph viewer
 - respects `--port` when you want a specific viewer port
 - for GitHub repo URLs, supports `--branch`, `--ref`, and `--checkout-dir`
+- `--install-agent-rules` installs the configured `agents` targets during initialization
 
 Use this when you want the fastest repo or docs-tree walkthrough without first deciding on managed-source registration.
 
-### `swarmvault clone <directory|github-url> [--no-viz] [--mcp] [--branch <name>] [--ref <ref>] [--checkout-dir <path>]`
+### `swarmvault clone <file|directory|github-url> [--no-viz] [--mcp] [--branch <name>] [--ref <ref>] [--checkout-dir <path>] [--install-agent-rules]`
 
 Compatibility alias for `swarmvault scan`.
 
@@ -268,7 +270,7 @@ Useful flags:
 
 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.
+Interactive file and directory ingest now emits bounded stderr progress, including the active file and processed content size. JSON, MCP, watch, and CI-style flows stay quiet, and parser compatibility failures stay local to the affected source instead of aborting unrelated analysis.
 
 Audio and video files use `tasks.audioProvider` when you configure a provider with `audio` capability. Local video extraction shells out to `ffmpeg`; public video URL extraction with `--video` shells out to `yt-dlp`. When no audio provider or extractor binary 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.
 
@@ -303,6 +305,8 @@ Compile the current manifests into:
 
 The compiler also reads `swarmvault.schema.md` and records a `schema_hash` plus lifecycle metadata such as `status`, `created_at`, `updated_at`, `compiled_from`, and `managed_by` in generated pages so schema edits can mark pages stale without losing lifecycle state.
 
+Large compile runs process source analysis in bounded batches and use a sparse graph co-occurrence projection so high-overlap note sets do not explode into unbounded pairwise graph work.
+
 For ingested code trees, compile also writes `state/code-index.json` so local imports and module aliases can resolve across the repo-aware code graph.
 
 New concept and entity pages are staged into `wiki/candidates/` first. A later matching compile promotes them into `wiki/concepts/` or `wiki/entities/`.
@@ -713,6 +717,8 @@ Defaults:
 
 Install agent-specific rules into the current project so an agent understands the SwarmVault workspace contract and workflow.
 
+`init`, `quickstart`, `scan`, and `clone` do not write project-local agent rule files by default. Run `swarmvault install --agent <agent>` for one target at a time, or list targets in `swarmvault.config.json` and pass `--install-agent-rules` to `init`, `quickstart`, `scan`, or `clone` when you intentionally want configured targets installed together.
+
 Hook-capable installs:
 
 ```bash
@@ -739,6 +745,8 @@ Agent target mapping:
 - `antigravity` writes `.agents/rules/swarmvault.md` and `.agents/workflows/swarmvault.md`, and removes older fully managed `.agent/` files during reinstall
 - `vscode` writes `.github/chatmodes/swarmvault.chatmode.md` plus `.github/copilot-instructions.md`
 
+SwarmVault only owns the managed block inside shared markdown rule files. It keeps the SwarmVault block aligned across targets while preserving any user-owned text before or after the block, so `AGENTS.md` and `CLAUDE.md` do not need to be byte-identical.
+
 Hook semantics:
 
 - `codex --hook` writes `.codex/hooks.json` plus `.codex/hooks/swarmvault-graph-first.js` and emits model-visible guidance before broad shell search
@@ -841,6 +849,8 @@ Search behavior is configurable separately from provider routing:
 - If a provider claims OpenAI compatibility but fails structured generation, declare only the capabilities it actually supports
 - If `lint --deep --web` fails immediately, make sure a `webSearch` provider is configured and mapped to `tasks.deepLintProvider`
 - If you still see a `node:sqlite` experimental warning on Node 24, upgrade to the latest CLI; current releases suppress that upstream warning during normal runs
+- If compile reports `Failed to parse JSON file ...`, the named derived state file is corrupt or empty. Remove the named file or restore it from git, then rerun `swarmvault compile`; current releases write JSON state atomically to reduce partial-file failures.
+- If a large heuristic vault fails with heap exhaustion or `Map maximum size exceeded` on an older CLI, upgrade and rerun compile. Current releases bound analysis concurrency and graph projection during compile.
 
 ## Links
 

package/dist/index.js

@@ -2,7 +2,7 @@
 
 // src/index.ts
 import { readFileSync } from "fs";
-import { access, mkdir as mkdir2, readFile as readFile2, writeFile as writeFile2 } from "fs/promises";
+import { access, mkdir as mkdir2, readFile as readFile2, stat, writeFile as writeFile2 } from "fs/promises";
 import path2 from "path";
 import process2 from "process";
 import { createInterface } from "readline/promises";
@@ -330,9 +330,9 @@ program.addHelpText(
 function readCliVersion() {
   try {
     const packageJson = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
-    return typeof packageJson.version === "string" && packageJson.version.trim() ? packageJson.version : "3.14.1";
+    return typeof packageJson.version === "string" && packageJson.version.trim() ? packageJson.version : "3.15.0";
   } catch {
-    return "3.14.1";
+    return "3.15.0";
   }
 }
 function parsePositiveInt(value, fallback) {
@@ -818,7 +818,8 @@ async function runGraphMergeCommand(graphPaths, options) {
 }
 async function runScanCommand(input, options) {
   const rootDir = process2.cwd();
-  await initVault(rootDir, {});
+  const progress = !isJson() && !options.mcp;
+  await initVault(rootDir, { installAgentRules: options.installAgentRules ?? false });
   if (!isJson()) {
     log("Initialized workspace.");
   }
@@ -828,14 +829,17 @@ async function runScanCommand(input, options) {
     branch: options.branch,
     ref: options.ref,
     checkoutDir: options.checkoutDir
-  }) : await ingestDirectory(rootDir, input, {});
+  }) : await ingestScanInput(rootDir, input, progress);
   if (!isJson()) {
     if ("source" in result) {
       log(
         `Registered ${result.source.kind} source ${result.source.id}. Imported ${result.source.lastSyncCounts?.importedCount ?? 0}, updated ${result.source.lastSyncCounts?.updatedCount ?? 0}.`
       );
-    } else {
+    } else if ("inputDir" in result) {
       log(`Ingested ${result.imported.length} file(s).`);
+    } else {
+      const sourceCount = result.created.length + result.updated.length + result.unchanged.length;
+      log(`Ingested ${sourceCount} source(s).`);
     }
   }
   const compiled = "compile" in result && result.compile ? result.compile : await compileVault(rootDir, {});
@@ -901,6 +905,17 @@ async function runScanCommand(input, options) {
     emitJson({ ...result, compiled, shareCardPath, shareCardSvgPath, shareKitPath });
   }
 }
+async function ingestScanInput(rootDir, input, progress) {
+  const absoluteInput = path2.resolve(rootDir, input);
+  const inputStat = await stat(absoluteInput);
+  if (inputStat.isDirectory()) {
+    return ingestDirectory(rootDir, input, { progress });
+  }
+  if (inputStat.isFile()) {
+    return ingestInputDetailed(rootDir, input, { progress });
+  }
+  throw new Error(`Input must be a file or directory: ${input}`);
+}
 async function resolveChatResumeId(resume) {
   if (!resume) {
     return void 0;
@@ -1022,7 +1037,7 @@ program.command("next").description("Show the safest next command for this direc
   }
   printNextCommandReport(report);
 });
-program.command("quickstart").description("Beginner path: initialize, ingest, compile, and optionally open the graph viewer in one command.").argument("<input>", "Directory or public GitHub repo root URL to turn into a vault").option("--port <port>", "Port for the graph viewer").option("--no-serve", "Skip launching the graph viewer after compile").option("--no-viz", "Compatibility alias for --no-serve; skip launching the graph viewer after compile").option("--mcp", "Start the MCP stdio server after compile instead of launching the graph viewer", false).option("--branch <name>", "GitHub branch to clone when the input is a public repo URL").option("--ref <ref>", "Git ref, tag, or commit to check out when the input is a public repo URL").option("--checkout-dir <path>", "Persistent checkout directory for a public GitHub repo input").action(runScanCommand);
+program.command("quickstart").description("Beginner path: initialize, ingest, compile, and optionally open the graph viewer in one command.").argument("<input>", "Directory or public GitHub repo root URL to turn into a vault").option("--port <port>", "Port for the graph viewer").option("--no-serve", "Skip launching the graph viewer after compile").option("--no-viz", "Compatibility alias for --no-serve; skip launching the graph viewer after compile").option("--mcp", "Start the MCP stdio server after compile instead of launching the graph viewer", false).option("--branch <name>", "GitHub branch to clone when the input is a public repo URL").option("--ref <ref>", "Git ref, tag, or commit to check out when the input is a public repo URL").option("--checkout-dir <path>", "Persistent checkout directory for a public GitHub repo input").option("--install-agent-rules", "Install configured agent rule files during initialization", false).action(runScanCommand);
 program.command("init").description("Initialize a SwarmVault workspace in the current directory.").option("--obsidian", "Generate a minimal .obsidian workspace alongside the vault", false).option(
   "--profile <profile>",
   "Starter workspace profile or comma-separated preset list (for example: personal-research or reader,timeline)"
@@ -1030,11 +1045,12 @@ program.command("init").description("Initialize a SwarmVault workspace in the cu
   "--lite",
   "Minimal LLM-Wiki starter (raw/, wiki/, wiki/index.md, wiki/log.md, swarmvault.schema.md) without config, state, or agent installs",
   false
-).action(async (options) => {
+).option("--install-agent-rules", "Install configured agent rule files during initialization", false).action(async (options) => {
   await initVault(process2.cwd(), {
     obsidian: options.obsidian ?? false,
     profile: options.profile,
-    lite: options.lite ?? false
+    lite: options.lite ?? false,
+    installAgentRules: options.installAgentRules ?? false
   });
   if (isJson()) {
     emitJson({
@@ -1042,7 +1058,8 @@ program.command("init").description("Initialize a SwarmVault workspace in the cu
       rootDir: process2.cwd(),
       obsidian: options.obsidian ?? false,
       profile: options.profile ?? "default",
-      lite: options.lite ?? false
+      lite: options.lite ?? false,
+      installAgentRules: options.installAgentRules ?? false
     });
   } else {
     log(options.lite ? "Initialized SwarmVault lite workspace." : "Initialized SwarmVault workspace.");
@@ -1074,11 +1091,10 @@ program.command("ingest").description("Ingest a local file path, directory path,
       video: options.video,
       extractClasses,
       resume: options.resume,
-      redact: options.redact
+      redact: options.redact,
+      progress: !isJson()
     };
-    const directoryResult = !/^https?:\/\//i.test(input) ? await import("fs/promises").then(
-      (fs) => fs.stat(input).then((stat) => stat.isDirectory() ? ingestDirectory(process2.cwd(), input, commonOptions) : null).catch(() => null)
-    ) : null;
+    const directoryResult = !/^https?:\/\//i.test(input) ? await stat(input).then((inputStat) => inputStat.isDirectory() ? ingestDirectory(process2.cwd(), input, commonOptions) : null).catch(() => null) : null;
     if (directoryResult) {
       const scope2 = options.review || guideEnabled ? await (async () => {
         const pathModule = await import("path");
@@ -2765,8 +2781,8 @@ retrieval.command("doctor").description("Diagnose retrieval index problems and o
     log(`Warning: ${warning}`);
   }
 });
-program.command("scan", { hidden: true }).description("Quick-start: initialize, ingest, compile, and serve a graph viewer in one command.").argument("<input>", "Directory or public GitHub repo root URL to scan").option("--port <port>", "Port for the graph viewer").option("--no-serve", "Skip launching the graph viewer after compile").option("--no-viz", "Compatibility alias for --no-serve; skip launching the graph viewer after compile").option("--mcp", "Start the MCP stdio server after compile instead of launching the graph viewer", false).option("--branch <name>", "GitHub branch to clone when scanning a public repo URL").option("--ref <ref>", "Git ref, tag, or commit to check out when scanning a public repo URL").option("--checkout-dir <path>", "Persistent checkout directory for a public GitHub repo scan").action(runScanCommand);
-program.command("clone", { hidden: true }).description("Compatibility alias for scan: initialize, clone/register a public repo URL, and compile it into the vault.").argument("<input>", "Public GitHub repo URL or local directory to scan").option("--port <port>", "Port for the graph viewer").option("--no-serve", "Skip launching the graph viewer after compile").option("--no-viz", "Compatibility alias for --no-serve; skip launching the graph viewer after compile").option("--mcp", "Start the MCP stdio server after compile instead of launching the graph viewer", false).option("--branch <name>", "GitHub branch to clone when scanning a public repo URL").option("--ref <ref>", "Git ref, tag, or commit to check out when scanning a public repo URL").option("--checkout-dir <path>", "Persistent checkout directory for a public GitHub repo scan").action(runScanCommand);
+program.command("scan", { hidden: true }).description("Quick-start: initialize, ingest, compile, and serve a graph viewer in one command.").argument("<input>", "Directory or public GitHub repo root URL to scan").option("--port <port>", "Port for the graph viewer").option("--no-serve", "Skip launching the graph viewer after compile").option("--no-viz", "Compatibility alias for --no-serve; skip launching the graph viewer after compile").option("--mcp", "Start the MCP stdio server after compile instead of launching the graph viewer", false).option("--branch <name>", "GitHub branch to clone when scanning a public repo URL").option("--ref <ref>", "Git ref, tag, or commit to check out when scanning a public repo URL").option("--checkout-dir <path>", "Persistent checkout directory for a public GitHub repo scan").option("--install-agent-rules", "Install configured agent rule files during initialization", false).action(runScanCommand);
+program.command("clone", { hidden: true }).description("Compatibility alias for scan: initialize, clone/register a public repo URL, and compile it into the vault.").argument("<input>", "Public GitHub repo URL or local directory to scan").option("--port <port>", "Port for the graph viewer").option("--no-serve", "Skip launching the graph viewer after compile").option("--no-viz", "Compatibility alias for --no-serve; skip launching the graph viewer after compile").option("--mcp", "Start the MCP stdio server after compile instead of launching the graph viewer", false).option("--branch <name>", "GitHub branch to clone when scanning a public repo URL").option("--ref <ref>", "Git ref, tag, or commit to check out when scanning a public repo URL").option("--checkout-dir <path>", "Persistent checkout directory for a public GitHub repo scan").option("--install-agent-rules", "Install configured agent rule files during initialization", false).action(runScanCommand);
 function enableStructuredJsonOnSubcommands(command) {
   for (const subcommand of command.commands) {
     const hasJsonOption = subcommand.options.some((option) => option.attributeName() === "json");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmvaultai/cli",
-  "version": "3.14.1",
+  "version": "3.15.0",
   "description": "Global CLI for SwarmVault.",
   "type": "module",
   "main": "dist/index.js",
@@ -44,7 +44,7 @@
     "prepublishOnly": "node ../../scripts/check-release-sync.mjs && node ../../scripts/check-published-manifests.mjs"
   },
   "dependencies": {
-    "@swarmvaultai/engine": "3.14.1",
+    "@swarmvaultai/engine": "3.15.0",
     "commander": "^14.0.1"
   },
   "devDependencies": {