@swarmvaultai/cli 3.15.0 → 3.16.1

package/README.md

@@ -672,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:
 
@@ -683,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
 
@@ -713,11 +722,11 @@ 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>` 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.
+`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:
 
@@ -727,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:
@@ -741,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.
 
@@ -754,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.
 
@@ -775,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

@@ -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.15.0";
+    return typeof packageJson.version === "string" && packageJson.version.trim() ? packageJson.version : "3.16.1";
   } catch {
-    return "3.15.0";
+    return "3.16.1";
   }
 }
 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);
@@ -1853,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 = [
@@ -1866,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 = [];
@@ -2010,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()) {
@@ -2193,6 +2272,91 @@ 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.reassignedTasks.length) {
+    log(`Reassigned tasks to ${result.fallbackProviderId}: ${result.reassignedTasks.join(", ")}`);
+  }
+  if (result.clearedTasks.length) {
+    log(`Cleared task assignments: ${result.clearedTasks.join(", ")}`);
+  }
+});
 async function confirmInteractive(message) {
   if (!process2.stdin.isTTY) return false;
   const rl = createInterface({ input: process2.stdin, output: process2.stderr });
@@ -2406,29 +2570,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");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmvaultai/cli",
-  "version": "3.15.0",
+  "version": "3.16.1",
   "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.15.0",
+    "@swarmvaultai/engine": "3.16.1",
     "commander": "^14.0.1"
   },
   "devDependencies": {