@klhapp/skillmux 1.10.0 → 1.11.1

package/src/commands/project.ts

@@ -1,7 +1,11 @@
 import { existsSync, lstatSync } from "node:fs";
 import { basename } from "node:path";
 import { expandHome } from "../config";
-import { planClientSurfaces, SUPPORTED_CLIENT_IDS } from "../init-clients";
+import { planAgentSurfaces, SUPPORTED_AGENT_IDS, type AgentId } from "../init-agents";
+import {
+  applyInstructionPlan,
+  planProjectInstructionSetup,
+} from "../init-instructions";
 import {
   parseManifest,
   pinProject,
@@ -12,6 +16,11 @@ import {
   validateManifest,
   writeManifestAtomic,
 } from "../manifest";
+import {
+  MCP_PROJECT_REGISTRABLE_AGENTS,
+  registerMcpServer,
+  type McpRegistrationResult,
+} from "../mcp-registration";
 import { resolveProjectDirectory, suggestProjectName } from "../project-setup";
 import {
   parseCommaList,
@@ -19,18 +28,19 @@ import {
   promptText,
   shouldUseWizard,
 } from "../prompts";
-import { emitSuccess, isInteractive } from "../output";
+import { emitSuccess, isInteractive, unknownSubcommandError } from "../output";
 import { confirmAction, confirmIfNeeded, loadManifestContext } from "./shared";
 import { isGlobalFlag } from "../global-flags";
 const PROJECT_INIT_USAGE =
-  "usage: skillmux project init [path] [--name <group>] [--skill <id>...] [--client <id>...] [--target <name>...] [--yes] [--no-sync]";
+  "usage: skillmux project init [path] [--name <group>] [--skill <id>...] [--agent <id>...] [--target <name>...] [--register-mcp] [--yes] [--no-sync]";
 
 interface ProjectInitArgs {
   path: string;
   name: string;
   skills: string[];
-  clients: string[];
+  agents: string[];
   targets: string[];
+  registerMcp: boolean;
   yes: boolean;
   sync: boolean;
 }
@@ -45,16 +55,32 @@ export function configuredTargetForSurface(
   )?.[0];
 }
 
-function configuredTargetsForClients(
+function configuredTargetsForAgents(
   manifest: ReturnType<typeof parseManifest>,
-  clients: readonly string[],
+  agents: readonly string[],
 ): string[] {
-  return planClientSurfaces(clients).surfaces.map((surface) => {
+  const plan = planAgentSurfaces(agents);
+
+  // planAgentSurfaces silently drops any agent with no surfaceId, which is how
+  // full-vault agents (goose, hermes) are modelled: they get the whole vault
+  // rather than a sync target directory. Dropping one here used to make
+  // "project attach --agent goose" a successful no-op, so refuse instead.
+  const covered = new Set<string>(plan.surfaces.flatMap((surface) => surface.agents));
+  for (const agent of agents) {
+    if (!covered.has(agent)) {
+      throw new Error(
+        `agent "${agent}" uses full-vault delivery and maps to no sync target; ` +
+          `name a target directly with --target instead`,
+      );
+    }
+  }
+
+  return plan.surfaces.map((surface) => {
     const target = configuredTargetForSurface(manifest, surface);
     if (target) return target;
-    const client = surface.clients[0]!;
+    const agent = surface.agents[0]!;
     throw new Error(
-      `client target for "${client}" is not configured; run "skillmux init --client ${client} --yes" first`,
+      `agent target for "${agent}" is not configured; run "skillmux init --agent ${agent} --yes" first`,
     );
   });
 }
@@ -63,8 +89,9 @@ function parseProjectInitArgs(args: string[]): ProjectInitArgs {
   let projectPath: string | undefined;
   let name: string | undefined;
   const skills: string[] = [];
-  const clients: string[] = [];
+  const agents: string[] = [];
   const targets: string[] = [];
+  let registerMcp = false;
   let yes = false;
   let sync = true;
 
@@ -81,10 +108,12 @@ function parseProjectInitArgs(args: string[]): ProjectInitArgs {
       const target = args[++i];
       if (!target) throw new Error("--target requires a name");
       targets.push(target);
-    } else if (arg === "--client") {
-      const client = args[++i];
-      if (!client) throw new Error("--client requires a name");
-      clients.push(client);
+    } else if (arg === "--agent") {
+      const agent = args[++i];
+      if (!agent) throw new Error("--agent requires a name");
+      agents.push(agent);
+    } else if (arg === "--register-mcp") {
+      registerMcp = true;
     } else if (arg === "--yes") {
       yes = true;
     } else if (arg === "--no-sync") {
@@ -110,8 +139,9 @@ function parseProjectInitArgs(args: string[]): ProjectInitArgs {
     path,
     name: name ?? suggestProjectName(basename(path)),
     skills,
-    clients,
+    agents,
     targets,
+    registerMcp,
     yes,
     sync,
   };
@@ -263,15 +293,15 @@ export async function runProject(
     const group = args[0];
     if (!group)
       throw new Error(
-        `usage: skillmux project ${subCommand} <group> (--client <id>... | --target <name>...) --yes`,
+        `usage: skillmux project ${subCommand} <group> (--agent <id>... | --target <name>...) --yes`,
       );
-    const clients: string[] = [];
+    const agents: string[] = [];
     const requestedTargets: string[] = [];
     for (let i = 1; i < args.length; i++) {
-      if (args[i] === "--client") {
+      if (args[i] === "--agent") {
         const value = args[++i];
-        if (!value) throw new Error("--client requires a name");
-        clients.push(value);
+        if (!value) throw new Error("--agent requires a name");
+        agents.push(value);
       } else if (args[i] === "--target") {
         const value = args[++i];
         if (!value) throw new Error("--target requires a name");
@@ -286,11 +316,20 @@ export async function runProject(
     }
     const { config, vaultPath, manifestPath, manifest } =
       await loadManifestContext();
-    const clientTargets = configuredTargetsForClients(manifest, clients);
-    const targets = [...new Set([...requestedTargets, ...clientTargets])];
+    const agentTargets = configuredTargetsForAgents(manifest, agents);
+    const targets = [...new Set([...requestedTargets, ...agentTargets])];
     if (targets.length === 0) {
-      throw new Error(`project ${subCommand} requires --client or --target`);
+      throw new Error(`project ${subCommand} requires --agent or --target`);
     }
+    // Several agents can share one target (e.g. opencode/windsurf both use
+    // agent-skills) — show the resolved directory, not just the target name,
+    // so it's clear at confirmation time which physical folder this affects.
+    const targetDirs = Object.fromEntries(
+      targets.map((t) => [t, manifest.targets[t]?.dir ?? "(unknown)"]),
+    );
+    const targetsDisplay = targets
+      .map((t) => `${t} (${targetDirs[t]})`)
+      .join(", ");
     const updated = updateProjectTargets(manifest, group, {
       ...(subCommand === "attach" ? { attach: targets } : { detach: targets }),
     });
@@ -302,10 +341,10 @@ export async function runProject(
     if (options.dryRun) {
       emitSuccess(
         { isJson: options.isJson },
-        { subcommand: subCommand, group, targets },
+        { subcommand: subCommand, group, targets, target_dirs: targetDirs },
         () =>
           console.log(
-            `${subCommand}: [project.${group}] ${targets.join(", ")} (dry-run)`,
+            `${subCommand}: [project.${group}] ${targetsDisplay} (dry-run)`,
           ),
       );
       return;
@@ -314,7 +353,7 @@ export async function runProject(
       !(await confirmIfNeeded({
         confirmed: args.includes("--yes"),
         isJson: options.isJson,
-        prompt: `${subCommand} [project.${group}] to ${targets.join(", ")}?`,
+        prompt: `${subCommand} [project.${group}] to ${targetsDisplay}?`,
         nonInteractiveError: `skillmux project ${subCommand} requires --yes when run non-interactively`,
       }))
     )
@@ -322,12 +361,23 @@ export async function runProject(
     writeManifestAtomic(manifestPath, updated);
     emitSuccess(
       { isJson: options.isJson },
-      { subcommand: subCommand, group, targets },
-      () => console.log(`${subCommand}: [project.${group}] ${targets.join(", ")}`),
+      { subcommand: subCommand, group, targets, target_dirs: targetDirs },
+      () => console.log(`${subCommand}: [project.${group}] ${targetsDisplay}`),
     );
     return;
   }
-  if (subCommand !== "init") throw new Error(PROJECT_INIT_USAGE);
+  if (subCommand !== "init")
+    throw unknownSubcommandError("project", subCommand, [
+      "init",
+      "list",
+      "show",
+      "add-path",
+      "remove-path",
+      "pin",
+      "unpin",
+      "attach",
+      "detach",
+    ]);
   let request = parseProjectInitArgs(args);
   const guided = shouldUseWizard(args, {
     interactive: isInteractive(),
@@ -345,20 +395,20 @@ export async function runProject(
   const localVaultPaths = config.local_vault_paths.map(expandHome);
   if (guided) {
     const name = await promptText("Project group", request.name);
-    const availableClients = SUPPORTED_CLIENT_IDS.filter((client) => {
-      const surface = planClientSurfaces([client]).surfaces[0];
+    const availableAgents = SUPPORTED_AGENT_IDS.filter((agent) => {
+      const surface = planAgentSurfaces([agent]).surfaces[0];
       return (
         surface !== undefined &&
         configuredTargetForSurface(manifest, surface) !== undefined
       );
     });
-    const clients = await promptMultiSelect(
-      "Which clients should receive project skills?",
-      availableClients.map((client) => ({
-        value: client,
-        label: client,
+    const agents = await promptMultiSelect(
+      "Which agents should receive project skills?",
+      availableAgents.map((agent) => ({
+        value: agent,
+        label: agent,
         selected:
-          request.clients.length === 0 || request.clients.includes(client),
+          request.agents.length === 0 || request.agents.includes(agent),
       })),
     );
     const skills = parseCommaList(
@@ -367,10 +417,25 @@ export async function runProject(
         request.skills.join(","),
       ),
     );
-    request = { ...request, name, clients, skills };
+    request = { ...request, name, agents, skills };
+  }
+  // Local MCP registration + instruction writing are independent of skill
+  // pins — only offered for agents with a verified project-scoped CLI
+  // command (currently just claude-code; see MCP_PROJECT_REGISTRABLE_AGENTS).
+  const registrableAgents = request.agents.filter((agent) =>
+    MCP_PROJECT_REGISTRABLE_AGENTS.includes(agent as AgentId),
+  ) as AgentId[];
+  if (guided && registrableAgents.length > 0) {
+    request = {
+      ...request,
+      registerMcp: await confirmAction(
+        `Also register skillmux as a project-scoped MCP server for ${registrableAgents.join(", ")}? ` +
+          `This writes ${request.path}/.mcp.json, shared via git.`,
+      ),
+    };
   }
-  const clientTargets = configuredTargetsForClients(manifest, request.clients);
-  const targets = [...new Set([...request.targets, ...clientTargets])];
+  const agentTargets = configuredTargetsForAgents(manifest, request.agents);
+  const targets = [...new Set([...request.targets, ...agentTargets])];
   const updated = upsertProject(manifest, {
     name: request.name,
     paths: [request.path],
@@ -378,15 +443,34 @@ export async function runProject(
     targets,
   });
   const { notes } = validateManifest(updated, vaultPath, localVaultPaths);
+
+  // The project-local instruction block only teaches an agent to call
+  // resolve_skill/fetch_skill (MCP tools) — write it only for agents that
+  // are actually getting a project-scoped MCP registration this run.
+  const mcpInstructionAgents = request.registerMcp ? registrableAgents : [];
+  const instructionPlan = planProjectInstructionSetup(
+    mcpInstructionAgents,
+    request.path,
+  );
+  const hasInstructionWrites = instructionPlan.changes.some(
+    (change) => change.status !== "unchanged",
+  );
+
   const plan = {
     mode: "project",
     project: request.name,
     path: request.path,
     skills: request.skills,
-    clients: request.clients,
+    agents: request.agents,
     targets,
     sync: request.sync,
     notes,
+    instructions: instructionPlan.changes.map(({ path, agents, status }) => ({
+      path,
+      agents,
+      status,
+    })),
+    register_mcp_for: mcpInstructionAgents,
   };
 
   if (options.dryRun) {
@@ -401,8 +485,14 @@ export async function runProject(
         console.log("\nReview");
         console.log(`  project: ${request.name}`);
         console.log(`  path: ${request.path}`);
-        console.log(`  clients: ${request.clients.join(", ") || "(none)"}`);
+        console.log(`  agents: ${request.agents.join(", ") || "(none)"}`);
         console.log(`  skills: ${request.skills.join(", ") || "(none)"}`);
+        console.log(
+          `  instructions: ${instructionPlan.changes.filter((change) => change.status !== "unchanged").length} file(s)`,
+        );
+        console.log(
+          `  MCP registration: ${mcpInstructionAgents.join(", ") || "(none)"}`,
+        );
         console.log(`  sync: ${request.sync ? "yes" : "no"}`);
       }
       if (
@@ -421,6 +511,17 @@ export async function runProject(
   }
 
   writeManifestAtomic(manifestPath, updated);
+  if (hasInstructionWrites) {
+    try {
+      applyInstructionPlan(instructionPlan);
+    } catch (error) {
+      throw new Error(
+        `project configuration was saved, but writing instruction files failed: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      );
+    }
+  }
   if (request.sync) {
     try {
       // Reaching here already required approval above (request.yes, or an
@@ -437,7 +538,39 @@ export async function runProject(
       );
     }
   }
-  emitSuccess({ isJson: options.isJson }, { result: plan }, () =>
-    console.log(`project "${request.name}" ready at ${request.path}`),
+
+  // Best-effort and outside the checks above: this mutates another tool's
+  // own config, not skillmux's, so a registration failure is reported, never
+  // rolled back — the successful project setup above still stands either way.
+  const mcpRegistrations: McpRegistrationResult[] = [];
+  if (request.registerMcp) {
+    for (const agent of registrableAgents) {
+      mcpRegistrations.push(
+        await registerMcpServer(agent, { scope: "project", cwd: request.path }),
+      );
+    }
+  }
+
+  emitSuccess(
+    { isJson: options.isJson },
+    {
+      result: {
+        ...plan,
+        instructions_changed: instructionPlan.changes
+          .filter((change) => change.status !== "unchanged")
+          .map((change) => change.path),
+        mcp_registrations: mcpRegistrations,
+      },
+    },
+    () => {
+      console.log(`project "${request.name}" ready at ${request.path}`);
+      for (const registration of mcpRegistrations) {
+        console.log(
+          registration.ok
+            ? `MCP registered: ${registration.agent} (project scope)`
+            : `MCP registration failed for ${registration.agent}: ${registration.error}`,
+        );
+      }
+    },
   );
 }

package/src/commands/report.ts

@@ -1,5 +1,5 @@
 import { Database } from "bun:sqlite";
-import type { TargetAdapter } from "../adapters";
+import type { ContextAdapter } from "../adapters";
 import type { ResolvedContext } from "../context";
 import { emitSuccess } from "../output";
 import { getStats, renderStatsText } from "../stats";
@@ -36,14 +36,14 @@ function parseReportArgs(args: string[]): {
 
 export async function runReport(
   args: string[],
-  options: { isJson: boolean; target: ResolvedContext; allowInsecure: boolean; adapter: TargetAdapter },
+  options: { isJson: boolean; context: ResolvedContext; allowInsecure: boolean; adapter: ContextAdapter },
 ): Promise<void> {
   const { db: dbPath, since } = parseReportArgs(args);
   if (!since)
     throw new Error(
       "usage: skillmux report [--context <name> | --server <url> | --db <path>] --since <window> [--json]",
     );
-  if (dbPath && options.target.type === "remote")
+  if (dbPath && options.context.type === "remote")
     throw new Error("--db and --context/--server are mutually exclusive");
 
   if (dbPath) {

package/src/commands/scan.ts

@@ -1,6 +1,7 @@
 import { expandHome, loadConfig } from "../config";
-import { emitSuccess } from "../output";
+import { emitSuccess, warn } from "../output";
 import {
+  parseFailOn,
   renderScanJson,
   renderScanText,
   scanExitCode,
@@ -12,10 +13,12 @@ import { isGlobalFlag } from "../global-flags";
 function parseScanArgs(args: string[]): {
   path?: string;
   format: "text" | "json";
+  formatExplicit: boolean;
   failOn?: ScanSeverity;
 } {
   let path: string | undefined;
   let format: "text" | "json" = "text";
+  let formatExplicit = false;
   let failOn: ScanSeverity | undefined;
   for (let i = 0; i < args.length; i++) {
     const option = args[i];
@@ -24,12 +27,13 @@ function parseScanArgs(args: string[]): {
       if (value !== "text" && value !== "json")
         throw new Error("--format must be text or json");
       format = value;
+      formatExplicit = true;
     } else if (option === "--fail-on") {
-      const value = args[++i];
-      if (value !== "low" && value !== "medium" && value !== "high") {
-        throw new Error("--fail-on must be low, medium, or high");
-      }
-      failOn = value;
+      // scan accepts "none" for symmetry with install/update, where it is the
+      // opt-out. Here it is already the default: scan reports, and the caller
+      // opts into a non-zero exit code.
+      const parsed = parseFailOn(args[++i]);
+      failOn = parsed === "none" ? undefined : parsed;
     } else if (isGlobalFlag(option, "--json")) {
       // handled globally by main()'s isJson flag; recognized here so it isn't rejected
     } else if (option?.startsWith("--")) {
@@ -40,14 +44,20 @@ function parseScanArgs(args: string[]): {
       path = option;
     }
   }
-  return { path, format, failOn };
+  return { path, format, formatExplicit, failOn };
 }
 
 export async function runScan(
   args: string[],
   options: { isJson: boolean },
 ): Promise<void> {
-  const { path, format, failOn } = parseScanArgs(args);
+  const { path, format, formatExplicit, failOn } = parseScanArgs(args);
+  if (formatExplicit) {
+    // --format predates the shared --json envelope and is the last command
+    // flag that emits JSON outside it. Kept working for existing callers;
+    // the warning goes to stderr so stdout stays machine-parseable.
+    warn("--format is deprecated and will be removed in a future 1.x release; use --json instead");
+  }
   const rootPath = path
     ? expandHome(path)
     : expandHome((await loadConfig()).vault_path);

package/src/commands/shared.ts

@@ -1,21 +1,14 @@
-import { createInterface } from "node:readline/promises";
 import { expandHome, loadConfig } from "../config";
 import { parseManifest, resolveManifestPath } from "../manifest";
 import { isInteractive } from "../output";
+import { askQuestion, type PromptIO } from "../prompts";
 
-export async function confirmAction(prompt: string): Promise<boolean> {
-  const readline = createInterface({
-    input: process.stdin,
-    output: process.stdout,
-  });
-  try {
-    const answer = (await readline.question(`${prompt} [y/N] `))
-      .trim()
-      .toLowerCase();
-    return answer === "y" || answer === "yes";
-  } finally {
-    readline.close();
-  }
+export async function confirmAction(
+  prompt: string,
+  io: PromptIO = {},
+): Promise<boolean> {
+  const answer = (await askQuestion(`${prompt} [y/N] `, io)).trim().toLowerCase();
+  return answer === "y" || answer === "yes";
 }
 
 export async function loadManifestContext() {

package/src/commands/skill.ts

@@ -1,10 +1,11 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { expandHome, loadConfig } from "../config";
+import { unknownSubcommandError } from "../output";
 import { vaultResolutionOrder } from "../vault";
 
 export async function runSkill(subCommand: string, args: string[]): Promise<void> {
-  if (subCommand !== "which") throw new Error("usage: skillmux skill <which>");
+  if (subCommand !== "which") throw unknownSubcommandError("skill", subCommand, ["which"]);
   await runWhich(args);
 }
 

package/src/commands/target.ts

@@ -1,9 +1,15 @@
 import { expandHome } from "../config";
-import { planClientSurfaces, SUPPORTED_CLIENT_IDS } from "../init-clients";
+import {
+  BUILT_IN_TARGET_NAMES,
+  planAgentSurfaces,
+  resolveBuiltInTarget,
+  SUPPORTED_AGENT_IDS,
+} from "../init-agents";
 import { planInitManifest, applyInit } from "../init";
 import { writeManifestAtomic } from "../manifest";
-import { emitSuccess } from "../output";
+import { emitSuccess, unknownSubcommandError } from "../output";
 import { confirmIfNeeded, loadManifestContext } from "./shared";
+
 export async function runTarget(
   subCommand: string,
   args: string[],
@@ -19,11 +25,11 @@ export async function runTarget(
     }
     const targets = names.map((name) => {
       const target = manifest.targets[name]!;
-      const clients = SUPPORTED_CLIENT_IDS.filter((client) => {
-        const surface = planClientSurfaces([client]).surfaces[0];
+      const agents = SUPPORTED_AGENT_IDS.filter((agent) => {
+        const surface = planAgentSurfaces([agent]).surfaces[0];
         return surface !== undefined && surface.path === expandHome(target.dir);
       });
-      return { name, ...target, clients };
+      return { name, ...target, agents };
     });
     emitSuccess({ isJson: options.isJson }, { targets }, () => {
       if (targets.length === 0) {
@@ -33,7 +39,7 @@ export async function runTarget(
           console.log(`${target.name}:`);
           console.log(`  dir: ${target.dir}`);
           console.log(`  host: ${target.host ?? "(global)"}`);
-          console.log(`  clients: ${target.clients.join(", ") || "(custom)"}`);
+          console.log(`  agents: ${target.agents.join(", ") || "(custom)"}`);
           console.log(
             `  projects: ${target.project_groups.join(", ") || "(none)"}`,
           );
@@ -47,9 +53,21 @@ export async function runTarget(
     const name = args[0];
     const dirIndex = args.indexOf("--dir");
     const rawPath = dirIndex === -1 ? undefined : args[dirIndex + 1];
-    if (!name || !rawPath)
+    if (!name)
       throw new Error("usage: skillmux target add <name> --dir <dir> --yes");
-    const path = expandHome(rawPath);
+
+    let path: string;
+    if (rawPath) {
+      path = expandHome(rawPath);
+    } else if (BUILT_IN_TARGET_NAMES.has(name)) {
+      path = resolveBuiltInTarget(name, {
+        codexHome: process.env.CODEX_HOME ? expandHome(process.env.CODEX_HOME) : undefined,
+      }).path;
+    } else {
+      throw new Error(
+        "usage: skillmux target add <name> --dir <dir> --yes  (--dir may be omitted for built-in target names: agent-skills, claude-code, codex)",
+      );
+    }
     if (options.dryRun) {
       const planned = planInitManifest(vaultPath, [{ name, dir: path }], []);
       emitSuccess(
@@ -118,5 +136,5 @@ export async function runTarget(
     return;
   }
 
-  throw new Error("usage: skillmux target <list|show|add|remove>");
+  throw unknownSubcommandError("target", subCommand, ["list", "show", "add", "remove"]);
 }

package/src/commands/update.ts

@@ -14,7 +14,15 @@ import {
 import { emitSuccess } from "../output";
 import { hashSkillContent, readSkillOrigin, writeSkillOrigin } from "../provenance";
 import type { SkillOrigin } from "../provenance";
-import { type ScanFinding, type ScanSeverity, scanExitCode } from "../scan";
+import {
+  FAIL_ON_USAGE,
+  parseFailOn,
+  resolveMutatingFailOn,
+  scanExitCode,
+  type FailOnOption,
+  type ScanFinding,
+  type ScanSeverity,
+} from "../scan";
 import { SKILL_ID_PATTERN } from "../vault";
 import { confirmIfNeeded } from "./shared";
 import { checkOutdated } from "./outdated";
@@ -175,14 +183,14 @@ function parseUpdateArgs(args: string[]): {
   yes: boolean;
   dryRun: boolean;
   force: boolean;
-  failOn?: ScanSeverity;
+  failOn?: FailOnOption;
   allowLocalSource: boolean;
 } {
   let skillId: string | undefined;
   let yes = false;
   let dryRun = false;
   let force = false;
-  let failOn: ScanSeverity | undefined;
+  let failOn: FailOnOption | undefined;
   let allowLocalSource = false;
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
@@ -191,11 +199,7 @@ function parseUpdateArgs(args: string[]): {
     else if (arg === "--force") force = true;
     else if (arg === "--allow-local-source") allowLocalSource = true;
     else if (arg === "--fail-on") {
-      const value = args[++i];
-      if (value !== "low" && value !== "medium" && value !== "high") {
-        throw new Error("--fail-on must be low, medium, or high");
-      }
-      failOn = value;
+      failOn = parseFailOn(args[++i]);
     } else if (isGlobalFlag(arg, "--json")) {
       // handled globally
     } else if (arg?.startsWith("--")) {
@@ -215,7 +219,10 @@ export async function runUpdate(args: string[], options: { isJson: boolean }): P
   const vaultPath = expandHome(config.vault_path);
 
   const candidates = await resolveCandidateOrigins(vaultPath, skillId, allowLocalSource, config.egress?.allowed_hosts);
-  const plan = await buildPlan(vaultPath, candidates, failOn, force, config.egress?.allowed_hosts);
+  // Same default as install: block on a high-severity finding unless the
+  // caller explicitly opts out with --fail-on none.
+  const effectiveFailOn = resolveMutatingFailOn(failOn);
+  const plan = await buildPlan(vaultPath, candidates, effectiveFailOn, force, config.egress?.allowed_hosts);
   try {
     const toWrite = plan.filter((item) => item.kind === "update");