@klhapp/skillmux 1.11.0 → 1.11.1

package/CHANGELOG.md

@@ -5,6 +5,19 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.11.1](https://github.com/klhq/skillmux/compare/v1.11.0...v1.11.1) (2026-09-03)
+
+
+### Added
+
+* **cli:** install asks before writing to the vault ([#185](https://github.com/klhq/skillmux/issues/185)) ([7f12d02](https://github.com/klhq/skillmux/commit/7f12d02def0f306d963d37920f2407c8cffe1c04))
+
+
+### Fixed
+
+* **cli:** reject full-vault agents on project attach, clarify agent vs target ([#184](https://github.com/klhq/skillmux/issues/184)) ([118aff5](https://github.com/klhq/skillmux/commit/118aff5f46fb9e83c8c0e068890b96fe0a02311d))
+* **security:** gate install/update on scan findings, plus CLI help cleanup ([#182](https://github.com/klhq/skillmux/issues/182)) ([daffd8a](https://github.com/klhq/skillmux/commit/daffd8af89ebee1fbd4c05870c328baf747bbea3))
+
 ## [1.11.0](https://github.com/klhq/skillmux/compare/v1.10.0...v1.11.0) (2026-09-02)
 
 

package/README.md

@@ -207,7 +207,14 @@ skillmux install owner/repo
 skillmux install owner/repo/path/to/skill
 ```
 
-Skillmux validates `SKILL.md` and scans candidate content before copying it into the vault. Use `--fail-on low|medium|high` to turn selected findings into an install gate.
+Skillmux validates `SKILL.md` and scans candidate content before copying it
+into the vault, then asks before writing. Pass `--yes` to approve up front;
+a non-interactive run needs it, because `install` refuses to write unattended.
+
+A high-severity finding aborts the install by default. `--fail-on
+low|medium|high|none` moves that threshold, and it names the lowest severity
+that still aborts, so a lower value is stricter: `low` aborts on low, medium
+and high, while `none` installs despite any finding.
 
 Useful management commands:
 
@@ -260,7 +267,7 @@ Read [MCP routing](docs/mcp-routing.md) for transports, client instructions, ret
 | --- | --- | --- |
 | Claude Code | `~/.claude/skills` | Configure in the agent |
 | Codex | `$CODEX_HOME/skills` or `~/.codex/skills` | Configure in the agent |
-| Gemini CLI, OpenCode, GitHub Copilot, Windsurf | `~/.agents/skills` | Configure in the agent |
+| OpenCode, GitHub Copilot, Windsurf | Shared `~/.agents/skills` | Configure in the agent |
 | Antigravity | `~/.gemini/config/skills` | Configure in the agent |
 | Goose, Hermes | Manual full-vault setup | Manual registration |
 | Custom agents | Any directory through a custom target | Stdio or Streamable HTTP |

package/docs/cli.md

@@ -494,13 +494,20 @@ When `--json` or `SKILLMUX_JSON=true` is set, all output is emitted to `stdout`
 }
 ```
 
-The `context` field identifies the execution context (`"local"` or `{ "name": "<context>", "server": "<url>" }`). The `target` field carries identical content but is deprecated and slated for removal in the next major version; consumers should read `context`.
+The `context` field identifies the execution context (`"local"` or `{ "name": "<context>", "server": "<url>" }`). The `target` field carries identical content but is deprecated; consumers should read `context`. It stays in the payload as a compatibility alias so existing automation keeps parsing, and no removal is planned.
 
 `skillmux init` additionally repeats its payload as deprecated top-level
 `command`, `phase`, `dry_run`, `applied`, `plan`, and `result` keys, which
 predate this envelope. They carry exactly the same content as `data` and are
-kept only so existing automation keeps working. Read `data` instead; the
-duplicated keys will be removed in the next major version.
+kept only so existing automation keeps working. Read `data` instead. The
+duplicated keys stay for the same reason as `target` above, and no removal
+is planned.
+
+`skillmux scan --format json` is the one exception to the envelope. It
+predates this contract and prints a bare `{"scanned": N, "findings": [...]}`
+object instead. It is deprecated and warns on stderr, which leaves stdout
+parseable for existing consumers. Use the global `--json` for anything new,
+and read `data` for the same fields.
 
 ### Exit codes
 

package/docs/concepts.md

@@ -116,9 +116,13 @@ Skillmux maps it to the product's skill directory and safe instruction-file
 conventions.
 
 A **target** is a physical directory managed by sync. Several agents can map
-to one target. Gemini CLI, OpenCode, GitHub Copilot, and Windsurf share
+to one target. OpenCode, GitHub Copilot, and Windsurf share
 `~/.agents/skills`, so Skillmux deduplicates that directory.
 
+The mapping is not total. `goose` and `hermes` use full-vault delivery and
+map to no target at all, so commands that take `--agent` as a stand-in for a
+target reject them.
+
 Custom targets let you manage another directory without adding a product
 adapter:
 

package/docs/getting-started.md

@@ -102,6 +102,10 @@ skillmux install owner/repo
 skillmux install owner/repo/path/to/skill
 ```
 
+`install` scans the skill, shows what it found, and asks before writing to
+the vault. Add `--yes` to approve up front, which a non-interactive run
+requires. See [Managing skills](skill-management.md#install-from-git).
+
 Or create a small skill:
 
 ```sh

package/docs/skill-management.md

@@ -27,20 +27,32 @@ Skillmux clones into a temporary directory, validates the selected skill,
 scans its text files, and copies it to `vault_path`. Existing skill IDs require
 `--force`.
 
-Preview the destination without copying:
+Nothing is written to the vault until you approve it. The scan result prints
+first, then `install` asks for confirmation, so you decide with the findings
+already on screen. Pass `--yes` to approve up front. A non-interactive run
+(no TTY, or `--json`) fails instead of installing unattended, the same way
+`skillmux update` behaves, so scripts and CI must opt in explicitly:
 
 ```sh
-skillmux install owner/repo --dry-run
+skillmux install owner/repo --yes
 ```
 
-Set a scan gate when you want findings to block installation:
+Preview the destination without copying. `--dry-run` writes nothing, so it
+never asks for confirmation:
 
 ```sh
-skillmux install owner/repo --fail-on high
+skillmux install owner/repo --dry-run
 ```
 
 The scanner detects suspicious prompt-injection patterns, secrets, and risky
-instructions. Findings remain advisory unless you pass `--fail-on`.
+instructions. A high-severity finding aborts the install by default. Use
+`--fail-on` to move that threshold, where a lower one is stricter, and
+`--fail-on none` to install despite any finding:
+
+```sh
+skillmux install owner/repo --fail-on low     # also abort on low and medium
+skillmux install owner/repo --fail-on none    # never abort on findings
+```
 
 `install` refuses a `file://` source by default — a `file://` URL reaches the
 local filesystem directly, so honoring one unconditionally would let anything
@@ -74,13 +86,21 @@ Leaving `allowed_hosts` unset (the default) leaves both commands unrestricted.
 ```sh
 skillmux scan
 skillmux scan ~/skills/candidate
-skillmux scan --format json
+skillmux scan --json
 skillmux scan --fail-on medium
 ```
 
 With no path, `scan` checks the configured vault. `--json` wraps the result in
-the standard CLI automation envelope, while `--format json` selects the
-scanner's raw JSON rendering.
+the standard CLI automation envelope.
+
+Unlike `install` and `update`, `scan` has no default threshold: it reports
+what it finds and exits 0 regardless, so adding it to a pipeline never
+changes that pipeline's exit code by itself. Pass `--fail-on` when you want
+it to gate. The value names the lowest severity that still fails, so a lower
+value is stricter.
+
+`--format text|json` is deprecated. It still works, but it prints JSON
+outside the standard envelope and now warns on stderr. Use `--json` instead.
 
 ## Check and pull upstream updates
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@klhapp/skillmux",
-  "version": "1.11.0",
+  "version": "1.11.1",
   "description": "Skill management and retrieval for AI agents: sync native skills across clients and route the long tail over MCP",
   "type": "module",
   "private": false,

package/src/cli.ts

@@ -543,6 +543,11 @@ usage:
   skillmux config diff
   skillmux config status
 
+config init bootstraps this machine's config file from a populated vault. It
+is not a prerequisite for anything: "skillmux init --vault <path>" runs the
+same bootstrap when no config exists, so reach for config init only when you
+are setting up the config without the guided init.
+
 Accepts --context <name> / --server <url> to target a remote deployment.`,
 
   completions: `completions: generate a shell completion script
@@ -566,7 +571,20 @@ usage:
   sync: `sync: apply the manifest to native agent target directories
 
 usage:
-  skillmux sync [--dry-run] [--restore-monolith] [--install-hook] [--yes] [--json]`,
+  skillmux sync [--dry-run] [--restore-monolith] [--install-hook] [--yes] [--json]
+
+--dry-run prints what would change without writing. --yes approves creating
+a target directory that does not exist yet; without it, an unseen directory
+is skipped rather than created.
+
+--install-hook installs a git post-merge hook in the vault checkout so a
+"git pull" re-syncs the targets automatically.
+
+--restore-monolith undoes managed-pin delivery for a target: instead of
+individual pinned skills, the target directory is replaced by a single
+symlink to the whole vault. It refuses to touch a directory skillmux does
+not own, one carrying a local_vault marker, or one whose marker points at a
+different vault.`,
 
   init: `init: guided setup for native skill management
 
@@ -608,6 +626,15 @@ usage:
   skillmux project attach <group> (--agent <id>... | --target <name>...) --yes
   skillmux project detach <group> (--agent <id>... | --target <name>...) --yes
 
+--agent and --target both name sync targets, and either may be repeated.
+--target <name> names a target directly, including a custom one created by
+"skillmux target add". --agent <id> is shorthand for "whatever target that
+agent maps to", resolved from the targets init already configured, so it
+fails if that agent was never set up or maps to no target at all (goose and
+hermes use full-vault delivery and have none). Several agents can share one
+target, so attaching two agents that map to the same directory attaches it
+once.
+
 --register-mcp is the project-local counterpart to "skillmux init
 --register-mcp": only for claude-code (the only agent whose own CLI has a
 project MCP scope — codex's mcp add has no scope flag, so it's always
@@ -626,7 +653,12 @@ usage:
   skillmux target remove <name> --yes
 
 --dir may be omitted when <name> is a built-in target with a deterministic
-path: agent-skills, claude-code, codex. Any other <name> requires --dir.`,
+path: agent-skills, claude-code, codex. Any other <name> requires --dir.
+
+A target is a directory, not a product. Several agents can map to the same
+one (opencode, github-copilot and windsurf all share agent-skills), which is
+why "skillmux project attach" accepts --agent as shorthand for the target
+that agent resolves to.`,
 
   core: `core: pin or unpin core-tier skills
 
@@ -649,22 +681,60 @@ Accepts --context <name> / --server <url> to prune a remote deployment's audit d
   scan: `scan: check the vault for install-time or integrity issues
 
 usage:
-  skillmux scan [path] [--format text|json] [--fail-on low|medium|high] [--json]`,
+  skillmux scan [path] [--fail-on low|medium|high|none] [--json]
+
+Scans [path], or the configured vault when omitted. Reporting only: it
+exits 0 whatever it finds unless --fail-on names a severity, which is why
+it has no default threshold while install and update default to high.
+
+--format text|json is deprecated: it emits JSON outside the standard
+envelope. Use --json instead; --format will be removed in a future 1.x
+release.`,
 
   install: `install: install a skill from a git source
 
 usage:
-  skillmux install <repo>[/path] [--force] [--fail-on low|medium|high] [--dry-run] [--allow-local-source] [--json]`,
+  skillmux install <repo>[/path] [--yes] [--force] [--fail-on low|medium|high|none] [--dry-run] [--allow-local-source] [--json]
+
+--yes approves writing the skill into the vault. Without it an interactive
+run asks first, and a non-interactive one (no TTY, or --json) fails rather
+than installing unattended, matching "skillmux update".
+
+The fetched skill is scanned before it is written to the vault. --fail-on
+sets the severity that aborts the install and defaults to high; pass
+--fail-on none to install despite findings. A lower threshold is stricter:
+low aborts on low, medium and high.
+
+--force overwrites a skill that already exists in the vault instead of
+refusing. --dry-run reports where the skill would land without writing.
+--allow-local-source permits a file:// or local path source, which is
+otherwise rejected.`,
 
   outdated: `outdated: list installed skills with a newer upstream version
 
 usage:
-  skillmux outdated [--allow-local-source] [--json]`,
+  skillmux outdated [--allow-local-source] [--json]
+
+Read-only: it reports what "skillmux update" would change and writes
+nothing. --allow-local-source includes skills installed from a local or
+file:// source, which are skipped by default because their upstream is a
+path on this machine rather than a shared remote.`,
 
   update: `update: update one or all skills to their latest source version
 
 usage:
-  skillmux update [skill-id] [--yes] [--dry-run] [--force] [--allow-local-source] [--fail-on low|medium|high] [--json]`,
+  skillmux update [skill-id] [--yes] [--dry-run] [--force] [--allow-local-source] [--fail-on low|medium|high|none] [--json]
+
+Updates every installed skill, or just <skill-id>. --yes is required to
+apply non-interactively. --dry-run prints the plan without writing.
+
+--fail-on works exactly as it does for install and defaults to high, so a
+skill whose new version carries a high-severity finding is skipped rather
+than updated; --fail-on none restores the old permissive behavior.
+
+--force updates a skill whose local content no longer matches the hash
+recorded at install time, which otherwise blocks the update to avoid
+discarding local edits. --allow-local-source permits local/file:// sources.`,
 
   eval: `eval: run retrieval evaluation against the holdout set
 
@@ -725,17 +795,20 @@ See docs/deployment.md for server deployment examples.`);
   console.log(`usage: skillmux <command> [options]
 
 Setup:
-  skillmux config init --vault <path> --yes
   skillmux init [--agent <name>...] [--vault <path>] [--core <skill_id>...]
-                [--migrate-full-vault] [--no-instructions] [--no-sync]
+                [--migrate-full-vault] [--show-mcp-setup] [--register-mcp]
+                [--no-instructions] [--no-sync]
                 [--interactive|--yes|--dry-run] [--json]
   skillmux project init [path] [--name <group>] [--skill <skill_id>...]
                 [--agent <name>...] [--target <name>...] [--no-sync]
                 [--interactive|--yes|--dry-run] [--json]
   skillmux project <list|show|add-path|remove-path|pin|unpin|attach|detach>
-  skillmux target <list|show|add|remove>
+  skillmux target <list|show|add|remove>  (a target is a directory sync writes into)
   skillmux core <pin|unpin> <skill_id>... [--yes] [--dry-run] [--json]
   skillmux skill which <skill_id>  (local vault shadow resolution; unrelated to MCP routing)
+  skillmux config init --vault <path> --yes
+                (bootstraps this machine's config on its own; not a
+                prerequisite, since "skillmux init --vault" does the same)
 
 Init agents:
   ${SUPPORTED_AGENT_IDS.join(", ")}
@@ -748,7 +821,7 @@ Operations:
   skillmux audit prune [--older-than <window>] [--dry-run] [--yes] [--json]
   skillmux eval promote --since <window> [--out <path>] [--dry-run] [--yes] [--json]
   skillmux outdated [--allow-local-source] [--json]
-  skillmux update [skill-id] [--yes] [--dry-run] [--force] [--allow-local-source] [--fail-on low|medium|high] [--json]
+  skillmux update [skill-id] [--yes] [--dry-run] [--force] [--allow-local-source] [--fail-on low|medium|high|none] [--json]
 
 Commands:
   serve, index, sync, init, project, target, core, report, audit, scan, install, outdated, update,

package/src/commands/init.ts

@@ -144,9 +144,9 @@ interface InitJsonPayload {
  * through the shared handler and needs no bridging.
  *
  * DEPRECATED: the duplicated top-level `command`/`phase`/`dry_run`/`applied`/
- * `plan`/`result` keys should be dropped in the next major version, leaving
- * only the standard envelope. init is local-only, so `target` is always
- * "local".
+ * `plan`/`result` keys are a compatibility alias for `data`. They stay so
+ * existing automation keeps parsing, and no removal is planned. init is
+ * local-only, so `target` is always "local".
  */
 function initJsonEnvelope(payload: InitJsonPayload): string {
   return JSON.stringify({

package/src/commands/install.ts

@@ -14,32 +14,39 @@ import {
 } from "../install";
 import { emitSuccess } from "../output";
 import { hashSkillContent, writeSkillOrigin } from "../provenance";
-import { renderScanText, scanExitCode, type ScanSeverity } from "../scan";
+import {
+  FAIL_ON_USAGE,
+  parseFailOn,
+  renderScanText,
+  resolveMutatingFailOn,
+  scanExitCode,
+  type FailOnOption,
+} from "../scan";
 import { isGlobalFlag } from "../global-flags";
+import { confirmIfNeeded } from "./shared";
 
 function parseInstallArgs(args: string[]): {
   repo?: string;
   force: boolean;
   dryRun: boolean;
-  failOn?: ScanSeverity;
+  failOn?: FailOnOption;
   allowLocalSource: boolean;
+  yes: boolean;
 } {
   let repo: string | undefined;
   let force = false;
   let dryRun = false;
-  let failOn: ScanSeverity | undefined;
+  let failOn: FailOnOption | undefined;
   let allowLocalSource = false;
+  let yes = false;
   for (let i = 0; i < args.length; i++) {
     const option = args[i];
     if (option === "--force") force = true;
+    else if (option === "--yes") yes = true;
     else if (option === "--dry-run") dryRun = true;
     else if (option === "--allow-local-source") allowLocalSource = 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;
+      failOn = parseFailOn(args[++i]);
     } else if (isGlobalFlag(option, "--json", "--verbose")) {
       // handled globally by main()'s isJson/isVerbose flags; recognized here so they aren't rejected
     } else if (option?.startsWith("--")) {
@@ -50,17 +57,17 @@ function parseInstallArgs(args: string[]): {
       repo = option;
     }
   }
-  return { repo, force, dryRun, failOn, allowLocalSource };
+  return { repo, force, dryRun, failOn, allowLocalSource, yes };
 }
 
 export async function runInstall(
   args: string[],
   options: { isJson: boolean },
 ): Promise<void> {
-  const { repo, force, dryRun, failOn, allowLocalSource } = parseInstallArgs(args);
+  const { repo, force, dryRun, failOn, allowLocalSource, yes } = parseInstallArgs(args);
   if (!repo) {
     throw new Error(
-      "usage: skillmux install <repo>[/path] [--force] [--fail-on low|medium|high] [--dry-run] [--allow-local-source] [--json]",
+      `usage: skillmux install <repo>[/path] [--yes] [--force] [--fail-on ${FAIL_ON_USAGE}] [--dry-run] [--allow-local-source] [--json]`,
     );
   }
 
@@ -85,10 +92,16 @@ export async function runInstall(
     );
     if (!options.isJson) console.log(renderScanText({ scanned: 1, findings }));
 
-    if (scanExitCode(findings, failOn) !== 0) {
+    // Defaults to blocking on a high-severity finding. Printing the findings
+    // and installing anyway is the wrong default for the command that pulls
+    // remote content into the vault.
+    const effectiveFailOn = resolveMutatingFailOn(failOn);
+    if (scanExitCode(findings, effectiveFailOn) !== 0) {
       process.exitCode = 1;
       console.error(
-        `aborting install: a finding met the --fail-on ${failOn} threshold`,
+        `aborting install: a finding met the --fail-on ${effectiveFailOn} threshold` +
+          (failOn === undefined ? " (the default)" : "") +
+          `; re-run with --fail-on none to install anyway`,
       );
       return;
     }
@@ -107,6 +120,16 @@ export async function runInstall(
       return;
     }
 
+    // Confirm after the scan, so an interactive user decides with the findings
+    // already on screen, and after the --dry-run return, which writes nothing.
+    const proceed = await confirmIfNeeded({
+      confirmed: yes,
+      isJson: options.isJson,
+      prompt: `install:\n  ${resolved.skillId} <- ${source.url}\n?`,
+      nonInteractiveError: "skillmux install requires --yes when run non-interactively",
+    });
+    if (!proceed) return;
+
     const commit = resolveCloneCommit(cloneDir);
     const targetDir = installIntoVault(
       vaultPath,

package/src/commands/project.ts

@@ -59,7 +59,23 @@ function configuredTargetsForAgents(
   manifest: ReturnType<typeof parseManifest>,
   agents: readonly string[],
 ): string[] {
-  return planAgentSurfaces(agents).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 agent = surface.agents[0]!;

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/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");
 

package/src/output.ts

@@ -4,7 +4,7 @@ export interface JsonEnvelope<T = any> {
   schema_version: 1;
   ok: boolean;
   context: string | { name: string; server: string };
-  /** @deprecated Slated for removal in the next major version. Use `context` instead. */
+  /** @deprecated Use `context` instead. Retained as a compatibility alias; no removal planned. */
   target: string | { name: string; server: string };
   data: T | null;
   error: { code: string; message: string; details?: any } | null;
@@ -12,7 +12,7 @@ export interface JsonEnvelope<T = any> {
 
 export function formatJsonEnvelope<T>(opts: {
   ok: boolean;
-  /** @deprecated Slated for removal in the next major version. Use `context` instead. */
+  /** @deprecated Use `context` instead. Retained as a compatibility alias; no removal planned. */
   target?: ResolvedContext | string | { name: string; server: string };
   context?: ResolvedContext | string | { name: string; server: string };
   data?: T;
@@ -62,7 +62,7 @@ export class CliError extends Error {
 export function emitSuccess<T>(
   ctx: {
     isJson: boolean;
-    /** @deprecated Slated for removal in the next major version. Use `context` instead. */
+    /** @deprecated Use `context` instead. Retained as a compatibility alias; no removal planned. */
     target?: ResolvedContext | string | { name: string; server: string };
     context?: ResolvedContext | string | { name: string; server: string };
   },

package/src/scan.ts

@@ -264,3 +264,37 @@ export function scanExitCode(findings: RuleMatch[], failOn: ScanSeverity | undef
   const threshold = SEVERITY_RANK[failOn];
   return findings.some((f) => SEVERITY_RANK[f.severity] >= threshold) ? 1 : 0;
 }
+
+/**
+ * A parsed `--fail-on` value. "none" is accepted on the command line to mean
+ * "never fail" and is not a finding severity, which is why it is kept out of
+ * ScanSeverity itself.
+ *
+ * Note the ordering: a lower threshold is stricter. `low` fails on low, medium
+ * and high; `high` fails only on high.
+ */
+export type FailOnOption = ScanSeverity | "none";
+
+export const FAIL_ON_USAGE = "low|medium|high|none";
+
+export function parseFailOn(value: string | undefined): FailOnOption {
+  if (value !== "low" && value !== "medium" && value !== "high" && value !== "none") {
+    throw new Error("--fail-on must be low, medium, high, or none");
+  }
+  return value;
+}
+
+/**
+ * Resolves the threshold for the commands that fetch remote content into the
+ * vault (install, update). They default to blocking on a high-severity finding,
+ * because printing a warning and proceeding anyway is the wrong default on the
+ * supply-chain path. `--fail-on none` restores the permissive behavior.
+ *
+ * `skillmux scan` deliberately does NOT use this: it is a reporting command
+ * whose exit code the caller opts into, and giving it a default would change
+ * the exit code of existing CI pipelines that just run `skillmux scan`.
+ */
+export function resolveMutatingFailOn(failOn: FailOnOption | undefined): ScanSeverity | undefined {
+  if (failOn === undefined) return "high";
+  return failOn === "none" ? undefined : failOn;
+}