@swarmvaultai/cli 3.14.2 → 3.16.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.
 
@@ -670,7 +672,15 @@ Trace the reverse-import blast radius of changing a file or module.
 - 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>`
+### `swarmvault graph cycles [--relation <name>] [--limit <n>] [--max-depth <n>]`
+
+Find deterministic directed cycles in the compiled graph.
+
+- defaults to `imports` edges for module cycle checks
+- accepts repeated `--relation` flags to inspect other directed relationships
+- supports global `--json` for automation
+
+### `swarmvault graph export --html|--html-standalone|--report|--svg|--graphml|--cypher|--json|--callflow|--obsidian|--canvas <output>`
 
 Export the current graph as one or more shareable formats:
 
@@ -681,6 +691,7 @@ 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
+- `--callflow` for compact directed relationship HTML
 - `--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
 
@@ -711,10 +722,12 @@ Defaults:
 - namespaces every remote record by `vaultId` so multiple vaults can safely share one Neo4j database
 - upserts current graph records and does not prune stale remote data yet
 
-### `swarmvault install --agent <agent>`
+### `swarmvault install --agent <agent> [--scope project|user]`
 
 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> --scope project` for one target at a time, use `--scope user` for supported user-scope skill installs, 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
@@ -723,6 +736,7 @@ swarmvault install --agent claude --hook
 swarmvault install --agent gemini --hook
 swarmvault install --agent opencode --hook
 swarmvault install --agent copilot --hook
+swarmvault install --agent kilo --hook
 ```
 
 Agent target mapping:
@@ -737,9 +751,13 @@ Agent target mapping:
 - `claw` writes `.claw/skills/swarmvault/SKILL.md`
 - `droid` writes `.factory/rules/swarmvault.md`
 - `kiro` writes `.kiro/skills/swarmvault/SKILL.md` and `.kiro/steering/swarmvault.md`
+- `kilo` project-scope writes `AGENTS.md`; with `--hook`, it also writes `.kilo/plugins/swarmvault.js` and `.kilo/kilo.json` while preserving an existing `.kilo/kilo.jsonc`
 - `hermes` writes `~/.hermes/skills/swarmvault/SKILL.md` plus `AGENTS.md`
 - `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`
+- `devin` writes `.devin/skills/swarmvault/SKILL.md` plus `.windsurf/rules/swarmvault.md`
+
+`swarmvault install status --agent <agent> [--scope project|user] [--hook]` reports the expected install paths and whether they exist without writing files.
 
 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.
 
@@ -750,6 +768,7 @@ Hook semantics:
 - `gemini --hook` writes `.gemini/settings.json` plus `.gemini/hooks/swarmvault-graph-first.js` and stays advisory/model-visible
 - `opencode --hook` writes `.opencode/plugins/swarmvault-graph-first.js` and stays advisory/log-only
 - `copilot --hook` writes `.github/hooks/swarmvault-graph-first.json` plus `.github/hooks/swarmvault-graph-first.js` and remains decision-based rather than advisory
+- `kilo --hook` writes `.kilo/plugins/swarmvault.js` and registers it in `.kilo/kilo.json`
 
 `aider` is intentionally file/config-based in this release rather than hook-based.
 
@@ -771,6 +790,17 @@ npm install -g @swarmvaultai/cli
 
 SwarmVault defaults to a local `heuristic` provider so the CLI works without API keys, but real vaults will usually point at an actual model provider.
 
+CLI registry commands:
+
+```bash
+swarmvault provider add router --type openrouter --model openrouter/auto --api-key-env OPENROUTER_API_KEY --capability chat --capability structured --task queryProvider
+swarmvault provider list
+swarmvault provider show router
+swarmvault provider remove router --fallback local
+```
+
+`provider add|remove` preserves unrelated config fields and stores secret references through `apiKeyEnv`, not literal API key values.
+
 Example:
 
 ```json

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";
@@ -10,6 +10,7 @@ import {
   acceptApproval,
   addInput,
   addManagedSource,
+  addProviderConfig,
   addWatchedRoot,
   archiveCandidate,
   askChatSession,
@@ -37,9 +38,12 @@ import {
   exportGraphTree,
   exportObsidianCanvas,
   exportObsidianVault,
+  findGraphCycles,
   finishMemoryTask,
+  getAgentInstallStatus,
   getGitHookStatus,
   getGraphStatus,
+  getProviderConfigEntry,
   getRetrievalStatus,
   getWatchStatus,
   graphDiff,
@@ -61,6 +65,7 @@ import {
   listManagedSourceRecords,
   listManifests,
   listMemoryTasks,
+  listProviderConfigEntries,
   listSchedules,
   listWatchedRoots,
   loadVaultConfig,
@@ -80,6 +85,7 @@ import {
   registerLocalWhisperProvider,
   rejectApproval,
   reloadManagedSources,
+  removeProviderConfig,
   removeWatchedRoot,
   renderContextPackLlms,
   renderContextPackMarkdown,
@@ -330,9 +336,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.2";
+    return typeof packageJson.version === "string" && packageJson.version.trim() ? packageJson.version : "3.16.0";
   } catch {
-    return "3.14.2";
+    return "3.16.0";
   }
 }
 function parsePositiveInt(value, fallback) {
@@ -340,6 +346,60 @@ function parsePositiveInt(value, fallback) {
   const parsed = Number.parseInt(value, 10);
   return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
 }
+var providerTypes = [
+  "heuristic",
+  "openai",
+  "ollama",
+  "anthropic",
+  "gemini",
+  "openai-compatible",
+  "openrouter",
+  "groq",
+  "together",
+  "xai",
+  "cerebras",
+  "local-whisper",
+  "custom"
+];
+var providerCapabilities = [
+  "responses",
+  "chat",
+  "structured",
+  "tools",
+  "vision",
+  "embeddings",
+  "streaming",
+  "local",
+  "image_generation",
+  "audio"
+];
+var providerTaskKeys = [
+  "compileProvider",
+  "queryProvider",
+  "lintProvider",
+  "visionProvider",
+  "imageProvider",
+  "embeddingProvider",
+  "audioProvider"
+];
+function parseProviderType(value) {
+  if (providerTypes.includes(value)) {
+    return value;
+  }
+  throw new Error(`Unknown provider type "${value}". Use one of: ${providerTypes.join(", ")}.`);
+}
+function parseProviderCapability(value) {
+  if (providerCapabilities.includes(value)) {
+    return value;
+  }
+  throw new Error(`Unknown provider capability "${value}". Use one of: ${providerCapabilities.join(", ")}.`);
+}
+function parseProviderTask(value) {
+  if (providerTaskKeys.includes(value)) {
+    return value;
+  }
+  throw new Error(`Unknown provider task "${value}". Use one of: ${providerTaskKeys.join(", ")}.`);
+}
 function parsePositiveNumber(value) {
   if (value === void 0) return void 0;
   const parsed = Number.parseFloat(value);
@@ -818,7 +878,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 +889,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 +965,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 +1097,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 +1105,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 +1118,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 +1151,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");
@@ -1837,8 +1913,8 @@ graph.command("serve").description("Serve the local graph viewer.").option("--po
   });
 });
 graph.command("export").description(
-  "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("--neo4j <output>", "Compatibility alias for --cypher, writing a Neo4j Cypher import file").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", "Include the full graph in HTML export (default; queries traverse complete graph)", true).option("--overview", "Use overview sampling for HTML export (smaller file, queries limited to sampled nodes)", false).action(
+  "Export the graph as HTML, report, SVG, GraphML, Cypher, JSON, callflow HTML, 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("--neo4j <output>", "Compatibility alias for --cypher, writing a Neo4j Cypher import file").option("--json <output>", "Output JSON file path").option("--callflow <output>", "Output directed callflow HTML file path").option("--obsidian <output>", "Output Obsidian vault directory path").option("--canvas <output>", "Output Obsidian canvas file path").option("--full", "Include the full graph in HTML export (default; queries traverse complete graph)", true).option("--overview", "Use overview sampling for HTML export (smaller file, queries limited to sampled nodes)", false).action(
   async (options) => {
     const useFullGraph = options.overview ? false : options.full ?? true;
     const targets = [
@@ -1850,12 +1926,13 @@ graph.command("export").description(
       options.cypher ? { format: "cypher", outputPath: options.cypher } : null,
       options.neo4j ? { format: "cypher", outputPath: options.neo4j } : null,
       options.json ? { format: "json", outputPath: options.json } : null,
+      options.callflow ? { format: "callflow", outputPath: options.callflow } : null,
       options.obsidian ? { format: "obsidian", outputPath: options.obsidian } : null,
       options.canvas ? { format: "canvas", outputPath: options.canvas } : null
     ].filter((target) => Boolean(target));
     if (targets.length === 0) {
       throw new Error(
-        "Pass at least one of --html, --html-standalone, --report, --svg, --graphml, --cypher, --neo4j, --json, --obsidian, or --canvas."
+        "Pass at least one of --html, --html-standalone, --report, --svg, --graphml, --cypher, --neo4j, --json, --callflow, --obsidian, or --canvas."
       );
     }
     const results = [];
@@ -1994,6 +2071,24 @@ graph.command("blast").description("Show the blast radius of changing a file or
     log(`  ${"  ".repeat(mod.depth - 1)}${mod.label} (depth ${mod.depth})`);
   }
 });
+graph.command("cycles").description("Find directed cycles in the compiled graph, defaulting to import edges.").option("--relation <name>", "Relation name to follow (repeatable; default: imports)", collectRepeated, []).option("--limit <n>", "Maximum cycles to report", "25").option("--max-depth <n>", "Maximum cycle depth", "25").action(async (options) => {
+  const { paths } = await loadVaultConfig(process2.cwd());
+  const raw = await readFile2(paths.graphPath, "utf-8");
+  const graphArtifact = JSON.parse(raw);
+  const result = findGraphCycles(graphArtifact, {
+    relations: options.relation?.length ? options.relation : ["imports"],
+    limit: parsePositiveInt(options.limit, 25),
+    maxDepth: parsePositiveInt(options.maxDepth, 25)
+  });
+  if (isJson()) {
+    emitJson(result);
+    return;
+  }
+  log(result.summary);
+  for (const cycle of result.cycles) {
+    log(`- ${cycle.labels.join(" -> ")} -> ${cycle.labels[0]} (${cycle.relations.join(", ")})`);
+  }
+});
 graph.command("supersession").description("Record that one page has been replaced by another (writes a superseded_by edge).").argument("<pageId>", "Page id or path of the older page").argument("<replacedById>", "Page id or path of the replacement page").action(async (pageId, replacedById) => {
   const result = await createSupersessionEdge(process2.cwd(), pageId, replacedById);
   if (isJson()) {
@@ -2177,6 +2272,88 @@ provider.command("setup").description("Interactive setup for a provider (current
     log(`Left tasks.audioProvider = "${registration.previousAudioProvider}" untouched (use --set-audio-provider to override).`);
   }
 });
+provider.command("add").description("Add or update a named provider in swarmvault.config.json.").argument("<id>", "Provider id").requiredOption("--type <type>", `Provider type: ${providerTypes.join(", ")}`).requiredOption("--model <model>", "Provider model name").option("--base-url <url>", "OpenAI-compatible base URL").option("--api-key-env <name>", "Environment variable that holds the provider API key").option("--capability <capability>", `Provider capability (${providerCapabilities.join(", ")})`, collectRepeated, []).option("--task <task>", `Assign provider to task (${providerTaskKeys.join(", ")})`, collectRepeated, []).option("--api-style <style>", "OpenAI-compatible API style: responses or chat").option("--module <path>", "Custom provider module path").option("--binary-path <path>", "Local provider binary path").option("--model-path <path>", "Local model file path").option("--threads <n>", "Local provider thread count").action(
+  async (id, options) => {
+    const apiStyle = options.apiStyle;
+    if (apiStyle && apiStyle !== "responses" && apiStyle !== "chat") {
+      throw new Error("--api-style must be responses or chat.");
+    }
+    const threads = options.threads ? parsePositiveInt(options.threads, 0) || void 0 : void 0;
+    const result = await addProviderConfig({
+      rootDir: process2.cwd(),
+      providerId: id,
+      provider: {
+        type: parseProviderType(options.type),
+        model: options.model,
+        baseUrl: options.baseUrl,
+        apiKeyEnv: options.apiKeyEnv,
+        capabilities: options.capability?.map(parseProviderCapability),
+        apiStyle,
+        module: options.module,
+        binaryPath: options.binaryPath,
+        modelPath: options.modelPath,
+        threads
+      },
+      tasks: options.task?.map(parseProviderTask)
+    });
+    if (isJson()) {
+      emitJson(result);
+      return;
+    }
+    log(`${result.added ? "Added" : result.updated ? "Updated" : "Kept"} provider ${result.providerId} in ${result.configPath}.`);
+    if (result.updatedTasks.length) {
+      log(`Assigned tasks: ${result.updatedTasks.join(", ")}`);
+    }
+  }
+);
+provider.command("list").description("List configured providers and task assignments.").action(async () => {
+  const entries = await listProviderConfigEntries(process2.cwd());
+  if (isJson()) {
+    emitJson(entries);
+    return;
+  }
+  if (!entries.length) {
+    log("No providers configured.");
+    return;
+  }
+  for (const entry of entries) {
+    const tasks = entry.assignedTasks.length ? ` tasks=${entry.assignedTasks.join(",")}` : "";
+    const key = entry.apiKeyEnv ? ` key=${entry.apiKeyEnv}` : "";
+    log(`${entry.id} type=${entry.type} model=${entry.model}${key}${tasks}`);
+  }
+});
+provider.command("show").description("Show one configured provider.").argument("<id>", "Provider id").action(async (id) => {
+  const entry = await getProviderConfigEntry(process2.cwd(), id);
+  if (!entry) {
+    throw new Error(`Provider ${id} is not configured.`);
+  }
+  if (isJson()) {
+    emitJson(entry);
+    return;
+  }
+  log(`${entry.id}`);
+  log(`type=${entry.type}`);
+  log(`model=${entry.model}`);
+  if (entry.baseUrl) log(`baseUrl=${entry.baseUrl}`);
+  if (entry.apiKeyEnv) log(`apiKeyEnv=${entry.apiKeyEnv}`);
+  if (entry.capabilities.length) log(`capabilities=${entry.capabilities.join(",")}`);
+  if (entry.assignedTasks.length) log(`tasks=${entry.assignedTasks.join(",")}`);
+});
+provider.command("remove").description("Remove a configured provider and reassign its tasks to a fallback provider.").argument("<id>", "Provider id").option("--fallback <id>", "Fallback provider for tasks currently assigned to the removed provider").action(async (id, options) => {
+  const result = await removeProviderConfig({
+    rootDir: process2.cwd(),
+    providerId: id,
+    fallbackProviderId: options.fallback
+  });
+  if (isJson()) {
+    emitJson(result);
+    return;
+  }
+  log(`${result.removed ? "Removed" : "No provider named"} ${id}.`);
+  if (result.updatedTasks.length) {
+    log(`Reassigned tasks: ${result.updatedTasks.join(", ")}`);
+  }
+});
 async function confirmInteractive(message) {
   if (!process2.stdin.isTTY) return false;
   const rl = createInterface({ input: process2.stdin, output: process2.stderr });
@@ -2390,29 +2567,44 @@ program.command("mcp").description("Run SwarmVault as a local MCP server over st
     process2.exit(0);
   });
 });
-program.command("install").description("Install SwarmVault instructions for an agent in the current project.").requiredOption(
+var install = program.command("install").description("Install SwarmVault instructions for an agent in the current project.");
+install.command("status").description("Show whether SwarmVault instructions are installed for an agent.").requiredOption("--agent <agent>", "Agent name").option("--hook", "Include hook/plugin targets in the status check", false).option("--scope <scope>", "Install scope to inspect: project or user", "project").action(async (options) => {
+  const scope = options.scope === "user" ? "user" : "project";
+  const result = await getAgentInstallStatus(process2.cwd(), options.agent, { hook: options.hook ?? false, scope });
+  if (isJson()) {
+    emitJson(result);
+    return;
+  }
+  log(`${result.agent} ${result.installed ? "installed" : "not installed"} (${result.scope}${result.hook ? ", hook" : ""})`);
+  for (const target of result.targets) {
+    log(`${target.exists ? "ok" : "missing"} ${target.path}`);
+  }
+});
+install.option(
   "--agent <agent>",
-  "claude, codex, cursor, gemini, goose, opencode, copilot, aider, droid, pi, trae, claw, kiro, hermes, antigravity, vscode, amp, augment, adal, bob, cline, codebuddy, command-code, continue, cortex, crush, deepagents, firebender, iflow, junie, kilo-code, kimi, kode, mcpjam, mistral-vibe, mux, neovate, openclaw, openhands, pochi, qoder, qwen-code, replit, roo-code, trae-cn, warp, windsurf, or zencoder"
-).option("--hook", "Also install hook/plugin guidance when the target agent supports it", false).action(
-  async (options) => {
-    const hookCapableAgents = /* @__PURE__ */ new Set(["codex", "claude", "opencode", "gemini", "copilot"]);
-    if (options.hook && !hookCapableAgents.has(options.agent)) {
-      throw new Error("--hook is only supported for --agent codex, claude, opencode, gemini, or copilot");
+  "claude, codex, cursor, gemini, goose, opencode, copilot, aider, droid, pi, trae, claw, kiro, kilo, hermes, antigravity, vscode, amp, augment, adal, bob, cline, codebuddy, command-code, continue, cortex, crush, deepagents, devin, firebender, iflow, junie, kilo-code, kimi, kode, mcpjam, mistral-vibe, mux, neovate, openclaw, openhands, pochi, qoder, qwen-code, replit, roo-code, trae-cn, warp, windsurf, or zencoder"
+).option("--hook", "Also install hook/plugin guidance when the target agent supports it", false).option("--scope <scope>", "Install scope: project or user", "project").action(async (options) => {
+  if (!options.agent) {
+    throw new Error("Specify --agent <agent>.");
+  }
+  const hookCapableAgents = /* @__PURE__ */ new Set(["codex", "claude", "opencode", "gemini", "copilot", "kilo"]);
+  if (options.hook && !hookCapableAgents.has(options.agent)) {
+    throw new Error("--hook is only supported for --agent codex, claude, opencode, gemini, copilot, or kilo");
+  }
+  const scope = options.scope === "user" ? "user" : "project";
+  const result = await installAgent(process2.cwd(), options.agent, { hook: options.hook ?? false, scope });
+  if (isJson()) {
+    emitJson({ ...result, hook: options.hook ?? false, scope });
+  } else {
+    log(`Installed rules into ${result.target}`);
+    if (result.targets.length > 1) {
+      log(`Also wrote: ${result.targets.filter((entry) => entry !== result.target).join(", ")}`);
     }
-    const result = await installAgent(process2.cwd(), options.agent, { hook: options.hook ?? false });
-    if (isJson()) {
-      emitJson({ ...result, hook: options.hook ?? false });
-    } else {
-      log(`Installed rules into ${result.target}`);
-      if (result.targets.length > 1) {
-        log(`Also wrote: ${result.targets.filter((entry) => entry !== result.target).join(", ")}`);
-      }
-      for (const warning of result.warnings ?? []) {
-        emitNotice(warning);
-      }
+    for (const warning of result.warnings ?? []) {
+      emitNotice(warning);
     }
   }
-);
+});
 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: writeFile3, mkdir: mkdir3 } = await import("fs/promises");
   const { tmpdir } = await import("os");
@@ -2765,8 +2957,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.2",
+  "version": "3.16.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.2",
+    "@swarmvaultai/engine": "3.16.0",
     "commander": "^14.0.1"
   },
   "devDependencies": {