@klhapp/skillmux 1.10.0 → 1.11.0

package/src/cli.ts

@@ -17,7 +17,7 @@ import { type StatsResponse } from "./stats";
 import { scanVault } from "./vault";
 
 import { resolveContext, type ResolvedContext } from "./context";
-import { createTargetAdapter, isLoopbackHost, type TargetAdapter } from "./adapters";
+import { createContextAdapter, isLoopbackHost, type ContextAdapter } from "./adapters";
 import {
   emitSuccess,
   CliError,
@@ -28,6 +28,7 @@ import {
   warn,
 } from "./output";
 import { generateCompletions, type ShellType } from "./completions";
+import { SUPPORTED_AGENT_IDS } from "./init-agents";
 import { runAudit } from "./commands/audit";
 import { handleConfigCommand } from "./commands/config";
 import { handleContextCommand } from "./commands/context";
@@ -45,7 +46,7 @@ import { runTarget } from "./commands/target";
 import { runSync } from "./commands/sync";
 import { runInit } from "./commands/init";
 
-const KNOWN_COMMANDS = [
+export const KNOWN_COMMANDS = [
   "context",
   "config",
   "completions",
@@ -69,39 +70,120 @@ const KNOWN_COMMANDS = [
   "local-vault",
 ];
 
-const LOCAL_ONLY_COMMANDS = new Set([
-  "install",
-  "update",
-  "outdated",
-  "sync",
-  "core",
-  "project",
-  "target",
-  "local-vault",
-  "index",
-  "models",
-  "scan",
-  "init",
-  "serve",
-]);
+/**
+ * Declared context support for every command in KNOWN_COMMANDS — the single
+ * source of truth getLocalOnlyCommand() enforces against. A command missing
+ * from here, or misclassified, is a bug: see tests/cli-context-support.test.ts,
+ * which fails the build rather than letting a command silently drift out of
+ * sync the way `config init` did (it was never rejected for a remote context,
+ * nor actually remote-capable — it just silently ran local logic that choked
+ * on an unrecognized --context/--server flag with a confusing error).
+ *
+ * - "local-only": operates on this machine's vault/filesystem/agents only;
+ *   a remote context is rejected outright.
+ * - "remote-capable": routed through ContextAdapter — same command, backed by
+ *   LocalAdapter or RemoteAdapter depending on the resolved context.
+ * - "context-agnostic": the resolved context isn't used to decide behavior at
+ *   all (context management is inherently local; completions never touch
+ *   vault/server state).
+ *
+ * Subcommand-level exceptions within an otherwise-classified command (e.g.
+ * `config init`, which bootstraps *this machine's* config file and so is
+ * local-only despite `config` overall being remote-capable) are handled in
+ * getLocalOnlyCommand() itself, not in this top-level map.
+ */
+export type CommandContextSupport = "local-only" | "remote-capable" | "context-agnostic";
+
+export const COMMAND_CONTEXT_SUPPORT: Record<string, CommandContextSupport> = {
+  context: "context-agnostic",
+  config: "remote-capable",
+  completions: "context-agnostic",
+  serve: "local-only",
+  index: "local-only",
+  sync: "local-only",
+  init: "local-only",
+  project: "local-only",
+  target: "local-only",
+  core: "local-only",
+  report: "remote-capable",
+  audit: "remote-capable",
+  scan: "local-only",
+  install: "local-only",
+  outdated: "local-only",
+  update: "local-only",
+  eval: "remote-capable",
+  doctor: "remote-capable",
+  models: "local-only",
+  skill: "local-only",
+  "local-vault": "local-only",
+};
 
-function getLocalOnlyCommand(command: string, subCommand: string): string | null {
-  if (LOCAL_ONLY_COMMANDS.has(command)) {
-    return command;
-  }
+const LOCAL_ONLY_COMMANDS = new Set(
+  Object.entries(COMMAND_CONTEXT_SUPPORT)
+    .filter(([, support]) => support === "local-only")
+    .map(([command]) => command),
+);
+
+export function getLocalOnlyCommand(command: string, subCommand: string): string | null {
   if (command === "skill" && (subCommand === "which" || !subCommand)) {
     return "skill which";
   }
+  if (command === "config" && subCommand === "init") {
+    return "config init";
+  }
+  if (LOCAL_ONLY_COMMANDS.has(command)) {
+    return command;
+  }
   return null;
 }
 
+/**
+ * Why a local-only command can't take a remote context, keyed by the exact
+ * string getLocalOnlyCommand() returns. Drives the guidance sentence
+ * remoteContextUnsupported() appends, so the rejection points somewhere
+ * useful instead of just saying no.
+ */
+type LocalOnlyReason = "vault-content" | "native-delivery" | "local-runtime" | "local-config";
+
+const LOCAL_ONLY_REASON: Record<string, LocalOnlyReason> = {
+  install: "vault-content",
+  update: "vault-content",
+  outdated: "vault-content",
+  scan: "vault-content",
+  init: "native-delivery",
+  sync: "native-delivery",
+  target: "native-delivery",
+  core: "native-delivery",
+  project: "native-delivery",
+  "local-vault": "native-delivery",
+  "skill which": "native-delivery",
+  serve: "local-runtime",
+  models: "local-runtime",
+  index: "local-runtime",
+  "config init": "local-config",
+};
+
+const LOCAL_ONLY_GUIDANCE: Record<LocalOnlyReason, string> = {
+  "vault-content":
+    "To change a remote deployment's vault contents, update its git-backed source and redeploy or pull on that host — skillmux doesn't replicate vault checkouts over the network.",
+  "native-delivery":
+    "This manages skill delivery into agent directories on the machine you run it from; there's no remote equivalent — run it on the machine that owns those directories.",
+  "local-runtime":
+    "This operates on the local runtime process on the machine you run it from.",
+  "local-config":
+    "This bootstraps this machine's own config file. To inspect or change a remote deployment's configuration, use \"skillmux config show/set --context <name>\" instead.",
+};
+
 function remoteContextUnsupported(rejectedCommand: string): CliError {
+  const reason = LOCAL_ONLY_REASON[rejectedCommand];
+  const guidance = reason ? ` ${LOCAL_ONLY_GUIDANCE[reason]}` : "";
   return new CliError(
-    `\`${rejectedCommand}\` operates on the local vault only; --context/--server isn't supported here`,
+    `\`${rejectedCommand}\` operates on the local vault only; --context/--server isn't supported here.${guidance}`,
     2,
     "REMOTE_CONTEXT_UNSUPPORTED",
     {
       rejected_command: rejectedCommand,
+      ...(reason ? { reason } : {}),
     },
   );
 }
@@ -196,14 +278,14 @@ async function main() {
     else if (arg === "--server") flagServer = rawArgv[++i];
   }
 
-  let resolvedTarget: ResolvedContext = { type: "local", name: "local" };
+  let resolvedContext: ResolvedContext = { type: "local", name: "local" };
 
   if (
     process.env.RUNNING_IN_DOCKER === "true" &&
     isDockerHostManagementCommand(command, subCommand)
   ) {
     await handleError(containerCommandUnsupported(command, subCommand), {
-      target: resolvedTarget,
+      context: resolvedContext,
       isJson,
       isVerbose,
     });
@@ -218,38 +300,38 @@ async function main() {
   }
 
   try {
-    resolvedTarget = await resolveContext({
+    resolvedContext = await resolveContext({
       context: flagContext,
       server: flagServer,
     });
   } catch (err: any) {
-    await handleError(err, { target: resolvedTarget, isJson, isVerbose });
+    await handleError(err, { context: resolvedContext, isJson, isVerbose });
     return;
   }
 
   const localOnlyCommand = getLocalOnlyCommand(command, subCommand);
-  if (localOnlyCommand && resolvedTarget.type === "remote") {
+  if (localOnlyCommand && resolvedContext.type === "remote") {
     await handleError(remoteContextUnsupported(localOnlyCommand), {
-      target: resolvedTarget,
+      context: resolvedContext,
       isJson,
       isVerbose,
     });
     return;
   }
 
-  const adapter = createTargetAdapter(resolvedTarget, { allowInsecure });
+  const adapter = createContextAdapter(resolvedContext, { allowInsecure });
 
   try {
     switch (command) {
       case "context":
         await handleContextCommand(subCommand, commandArgs, {
-          target: resolvedTarget,
+          context: resolvedContext,
           isJson,
         });
         break;
       case "config":
         await handleConfigCommand(adapter, subCommand, commandArgs, {
-          target: resolvedTarget,
+          context: resolvedContext,
           isJson,
           dryRun: isDryRun,
         });
@@ -308,7 +390,7 @@ async function main() {
       case "report":
         await runReport(rawArgv.slice(1), {
           isJson,
-          target: resolvedTarget,
+          context: resolvedContext,
           allowInsecure,
           adapter,
         });
@@ -317,7 +399,7 @@ async function main() {
         await runAudit(subCommand, commandArgs, {
           isJson,
           dryRun: isDryRun,
-          target: resolvedTarget,
+          context: resolvedContext,
           adapter,
         });
         break;
@@ -339,11 +421,16 @@ async function main() {
         } else if (subCommand === "") {
           await runEval({ isJson, adapter });
         } else {
-          throw new Error(`usage: skillmux eval [promote --since <window> [--target <path>] [--dry-run] [--yes] [--json]]`);
+          throw new Error(`usage: skillmux eval [promote --since <window> [--out <path>] [--dry-run] [--yes] [--json]]`);
         }
         break;
       case "doctor":
-        await runDoctor({ isJson, target: resolvedTarget, adapter });
+        await runDoctor({
+          isJson,
+          context: resolvedContext,
+          adapter,
+          args: rawArgv.slice(1),
+        });
         break;
       case "which":
         throw new Error(
@@ -375,7 +462,7 @@ async function main() {
       }
     }
   } catch (err: any) {
-    await handleError(err, { target: resolvedTarget, isJson, isVerbose });
+    await handleError(err, { context: resolvedContext, isJson, isVerbose });
   }
 }
 
@@ -390,7 +477,7 @@ async function handleCompletionsCommand(shell: string) {
 
 async function handleError(
   err: any,
-  opts: { target: ResolvedContext; isJson: boolean; isVerbose: boolean },
+  opts: { context: ResolvedContext; isJson: boolean; isVerbose: boolean },
 ) {
   const code = mapExitCode(err);
   process.exitCode = code;
@@ -411,7 +498,7 @@ async function handleError(
   if (opts.isJson) {
     const env = formatJsonEnvelope({
       ok: false,
-      target: opts.target,
+      context: opts.context,
       error: {
         code: err instanceof CliError ? err.code : `EXIT_${code}`,
         message: msg,
@@ -476,7 +563,7 @@ alongside a stdio transport without opening the full HTTP surface.`,
 usage:
   skillmux index`,
 
-  sync: `sync: apply the manifest to native client target directories
+  sync: `sync: apply the manifest to native agent target directories
 
 usage:
   skillmux sync [--dry-run] [--restore-monolith] [--install-hook] [--yes] [--json]`,
@@ -484,37 +571,62 @@ usage:
   init: `init: guided setup for native skill management
 
 usage:
-  skillmux init [--client <name>...] [--target <name>...] [--dir <dir>]
-                [--vault <path>] [--core <skill_id>...]
-                [--migrate-full-vault] [--no-instructions] [--no-sync]
+  skillmux init [--agent <name>...] [--vault <path>] [--core <skill_id>...]
+                [--migrate-full-vault] [--show-mcp-setup] [--register-mcp]
+                [--no-instructions] [--no-sync]
                 [--interactive|--yes|--dry-run] [--json]
 
-clients: claude-code, codex, gemini-cli, opencode, github-copilot, windsurf,
-         antigravity, goose, hermes, skillmux-mcp
-targets: agent-skills, claude-code, codex, custom`,
+agents: ${SUPPORTED_AGENT_IDS.join(", ")}
+
+Native pins and MCP are independent — skip both of the flags below for
+native-only setup, and init writes no instruction files (the managed
+block only teaches resolve_skill/fetch_skill, which are MCP tools).
+--show-mcp-setup prints the MCP registration snippet to copy in yourself,
+for any agent, and also writes the instruction block for every selected
+agent. --register-mcp instead runs that agent's own CLI to register
+skillmux automatically, but only for claude-code and codex (the only
+agents with a verified registration command), and writes the instruction
+block just for those; interactively, init asks about this only when
+you've selected one of those two. --no-instructions forces instruction
+writes off even when an MCP flag is set. A tool not in the agents list
+above isn't supported by init yet — add it to SUPPORTED_AGENT_IDS rather
+than guessing a directory. To adopt an arbitrary existing directory
+directly, use "skillmux target add <name> --dir <dir>" instead of init.`,
 
   project: `project: manage project-scoped skill pins and sync groups
 
 usage:
   skillmux project init [path] [--name <group>] [--skill <skill_id>...]
-                [--client <name>...] [--target <name>...] [--no-sync]
-                [--interactive|--yes|--dry-run] [--json]
+                [--agent <name>...] [--target <name>...] [--register-mcp]
+                [--no-sync] [--interactive|--yes|--dry-run] [--json]
   skillmux project list
   skillmux project show <group>
   skillmux project add-path <group> [path] --yes
   skillmux project remove-path <group> [path] --yes
   skillmux project pin <group> <skill_id>... --yes
   skillmux project unpin <group> <skill_id>... --yes
-  skillmux project attach <group> (--client <id>... | --target <name>...) --yes
-  skillmux project detach <group> (--client <id>... | --target <name>...) --yes`,
+  skillmux project attach <group> (--agent <id>... | --target <name>...) --yes
+  skillmux project detach <group> (--agent <id>... | --target <name>...) --yes
+
+--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
+global). It runs "claude mcp add -s project" for this project directory,
+which writes a committed .mcp.json shared with your team, and writes a
+project-root CLAUDE.md with the resolve_skill/fetch_skill discovery
+paragraph — same reasoning as init: no instruction file is written unless
+MCP is actually being registered.`,
 
   target: `target: manage native sync target directories
 
 usage:
   skillmux target list
   skillmux target show <name>
-  skillmux target add <name> --dir <dir> --yes
-  skillmux target remove <name> --yes`,
+  skillmux target add <name> [--dir <dir>] --yes
+  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.`,
 
   core: `core: pin or unpin core-tier skills
 
@@ -558,7 +670,7 @@ usage:
 
 usage:
   skillmux eval [--json]
-  skillmux eval promote --since <window> [--target <path>] [--dry-run] [--yes] [--json]
+  skillmux eval promote --since <window> [--out <path>] [--dry-run] [--yes] [--json]
 
 Accepts --context <name> / --server <url> to evaluate a remote deployment.`,
 
@@ -614,29 +726,27 @@ See docs/deployment.md for server deployment examples.`);
 
 Setup:
   skillmux config init --vault <path> --yes
-  skillmux init [--client <name>...] [--target <name>...] [--dir <dir>]
-                [--vault <path>] [--core <skill_id>...]
+  skillmux init [--agent <name>...] [--vault <path>] [--core <skill_id>...]
                 [--migrate-full-vault] [--no-instructions] [--no-sync]
                 [--interactive|--yes|--dry-run] [--json]
   skillmux project init [path] [--name <group>] [--skill <skill_id>...]
-                [--client <name>...] [--target <name>...] [--no-sync]
+                [--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 core <pin|unpin> <skill_id>... [--yes] [--dry-run] [--json]
   skillmux skill which <skill_id>  (local vault shadow resolution; unrelated to MCP routing)
 
-Init clients:
-  claude-code, codex, gemini-cli, opencode, github-copilot, windsurf,
-  antigravity, goose, hermes, skillmux-mcp
-
-Init targets:
-  agent-skills, claude-code, codex, custom
+Init agents:
+  ${SUPPORTED_AGENT_IDS.join(", ")}
+  ("skillmux init --show-mcp-setup" also prints the MCP registration
+  snippet, independent of which agents you select. A tool not in this
+  list isn't supported by init yet — see "skillmux init --help".)
 
 Operations:
   skillmux report [--context <name> | --server <url> | --db <path>] --since <window> [--json]
   skillmux audit prune [--older-than <window>] [--dry-run] [--yes] [--json]
-  skillmux eval promote --since <window> [--target <path>] [--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]
 
@@ -713,7 +823,7 @@ async function runIndex(): Promise<void> {
   }
 }
 
-async function runEval(options: { isJson: boolean; adapter: TargetAdapter }): Promise<void> {
+async function runEval(options: { isJson: boolean; adapter: ContextAdapter }): Promise<void> {
   const config = await loadConfig();
   configure({ config, clients: createClients(config) });
 

package/src/commands/audit.ts

@@ -1,13 +1,13 @@
 import { emitSuccess } from "../output";
 import { confirmIfNeeded } from "./shared";
-import type { TargetAdapter } from "../adapters";
+import type { ContextAdapter } from "../adapters";
 import type { ResolvedContext } from "../context";
 import { isGlobalFlag, isGlobalFlagWithValue } from "../global-flags";
 
 export async function runAudit(
   subCommand: string,
   args: string[],
-  options: { isJson: boolean; dryRun: boolean; target: ResolvedContext; adapter: TargetAdapter },
+  options: { isJson: boolean; dryRun: boolean; context: ResolvedContext; adapter: ContextAdapter },
 ): Promise<void> {
   if (subCommand !== "prune") {
     throw new Error("usage: skillmux audit prune [--older-than <window>] [--dry-run] [--yes] [--json]");

package/src/commands/config.ts

@@ -1,8 +1,8 @@
 import { expandHome, migrateLegacyPaths, resolveConfigPath } from "../config";
-import { type TargetAdapter } from "../adapters";
+import { type ContextAdapter } from "../adapters";
 import { type ResolvedContext } from "../context";
 import { applyConfigInit, planConfigInit, type ConfigInitPlan } from "../setup";
-import { emitSuccess, isInteractive, renderTargetBanner } from "../output";
+import { emitSuccess, isInteractive, renderContextBanner, unknownSubcommandError } from "../output";
 import { confirmAction } from "./shared";
 import { isGlobalFlag } from "../global-flags";
 function emitConfigInitOutcome(
@@ -38,10 +38,10 @@ function emitConfigInitOutcome(
 }
 
 export async function handleConfigCommand(
-  adapter: TargetAdapter,
+  adapter: ContextAdapter,
   sub: string,
   args: string[],
-  ctx: { target: ResolvedContext; isJson: boolean; dryRun: boolean },
+  ctx: { context: ResolvedContext; isJson: boolean; dryRun: boolean },
 ) {
   if (sub === "init") {
     let vaultPath: string | undefined;
@@ -127,8 +127,8 @@ export async function handleConfigCommand(
   if (sub === "show") {
     const withSources = args.includes("--sources");
     const data = await adapter.getConfigShow();
-    emitSuccess({ isJson: ctx.isJson, target: ctx.target }, data, () => {
-      renderTargetBanner(ctx.target);
+    emitSuccess({ isJson: ctx.isJson, context: ctx.context }, data, () => {
+      renderContextBanner(ctx.context);
       if (withSources) {
         const policy =
           data.effective.config?.environment_overrides === false
@@ -151,7 +151,7 @@ export async function handleConfigCommand(
     if (!key) throw new Error("usage: skillmux config get <key>");
     const val = await adapter.getConfigGet(key);
     emitSuccess(
-      { isJson: ctx.isJson, target: ctx.target },
+      { isJson: ctx.isJson, context: ctx.context },
       { key, value: val },
       () => {
         console.log(
@@ -164,7 +164,7 @@ export async function handleConfigCommand(
 
   if (sub === "validate") {
     const res = await adapter.configValidate();
-    emitSuccess({ isJson: ctx.isJson, target: ctx.target }, res, () => {
+    emitSuccess({ isJson: ctx.isJson, context: ctx.context }, res, () => {
       console.log(res.valid ? "configuration is valid" : "configuration is invalid");
     });
     return;
@@ -172,8 +172,8 @@ export async function handleConfigCommand(
 
   if (sub === "diff") {
     const res = await adapter.configDiff();
-    emitSuccess({ isJson: ctx.isJson, target: ctx.target }, res, () => {
-      renderTargetBanner(ctx.target);
+    emitSuccess({ isJson: ctx.isJson, context: ctx.context }, res, () => {
+      renderContextBanner(ctx.context);
       console.log(JSON.stringify(res.diff, null, 2));
     });
     return;
@@ -186,8 +186,8 @@ export async function handleConfigCommand(
       throw new Error("usage: skillmux config set <key> <value> [--dry-run]");
     }
     const res = await adapter.configSet(key, value, { dryRun: ctx.dryRun });
-    emitSuccess({ isJson: ctx.isJson, target: ctx.target }, res, () => {
-      renderTargetBanner(ctx.target);
+    emitSuccess({ isJson: ctx.isJson, context: ctx.context }, res, () => {
+      renderContextBanner(ctx.context);
       const prefix = ctx.dryRun ? "[dry-run] " : "";
       console.log(
         `${prefix}${key}: ${JSON.stringify(res.prior_val)} -> ${JSON.stringify(res.resulting_val)}`,
@@ -201,8 +201,8 @@ export async function handleConfigCommand(
 
   if (sub === "status") {
     const res = await adapter.configStatus();
-    emitSuccess({ isJson: ctx.isJson, target: ctx.target }, res, () => {
-      renderTargetBanner(ctx.target);
+    emitSuccess({ isJson: ctx.isJson, context: ctx.context }, res, () => {
+      renderContextBanner(ctx.context);
       console.log(`runtime: ${res.runtime}`);
       console.log(`deployment runtime: ${res.deployment_runtime}`);
       console.log(`image variant: ${res.image_variant ?? "none"}`);
@@ -212,5 +212,13 @@ export async function handleConfigCommand(
     return;
   }
 
-  throw new Error("usage: skillmux config show");
+  throw unknownSubcommandError("config", sub, [
+    "init",
+    "show",
+    "get",
+    "set",
+    "validate",
+    "diff",
+    "status",
+  ]);
 }

package/src/commands/context.ts

@@ -9,18 +9,19 @@ import {
 import {
   emitSuccess,
   renderTable,
-  renderTargetBanner,
+  renderContextBanner,
+  unknownSubcommandError,
 } from "../output";
 
 export async function handleContextCommand(
   sub: string,
   args: string[],
-  ctx: { target: ResolvedContext; isJson: boolean },
+  ctx: { context: ResolvedContext; isJson: boolean },
 ) {
   if (sub === "list") {
     const contexts = await listContexts();
-    emitSuccess({ isJson: ctx.isJson, target: ctx.target }, contexts, () => {
-      renderTargetBanner(ctx.target);
+    emitSuccess({ isJson: ctx.isJson, context: ctx.context }, contexts, () => {
+      renderContextBanner(ctx.context);
       renderTable(
         [
           { key: "name", header: "NAME" },
@@ -40,8 +41,8 @@ export async function handleContextCommand(
 
   if (sub === "current") {
     const current = await getCurrentContext();
-    emitSuccess({ isJson: ctx.isJson, target: ctx.target }, current, () => {
-      renderTargetBanner(ctx.target);
+    emitSuccess({ isJson: ctx.isJson, context: ctx.context }, current, () => {
+      renderContextBanner(ctx.context);
       console.log(`Current context: ${current.name} (${current.server})`);
     });
     return;
@@ -62,7 +63,7 @@ export async function handleContextCommand(
     }
     await addContext(name, { server, token_env: tokenEnv });
     emitSuccess(
-      { isJson: ctx.isJson, target: ctx.target },
+      { isJson: ctx.isJson, context: ctx.context },
       { name, server, token_env: tokenEnv },
       () => {
         console.log(`Added context "${name}" -> ${server}`);
@@ -76,7 +77,7 @@ export async function handleContextCommand(
     if (!name) throw new Error("usage: skillmux context use <name>");
     await useContext(name);
     emitSuccess(
-      { isJson: ctx.isJson, target: ctx.target },
+      { isJson: ctx.isJson, context: ctx.context },
       { default_context: name },
       () => {
         console.log(`Switched default context to "${name}"`);
@@ -90,7 +91,7 @@ export async function handleContextCommand(
     if (!name) throw new Error("usage: skillmux context remove <name>");
     await removeContext(name);
     emitSuccess(
-      { isJson: ctx.isJson, target: ctx.target },
+      { isJson: ctx.isJson, context: ctx.context },
       { removed: name },
       () => {
         console.log(`Removed context "${name}"`);
@@ -99,5 +100,5 @@ export async function handleContextCommand(
     return;
   }
 
-  throw new Error("usage: skillmux context <add|list|current|use|remove>");
+  throw unknownSubcommandError("context", sub, ["add", "list", "current", "use", "remove"]);
 }

package/src/commands/core.ts

@@ -1,6 +1,6 @@
 import { expandHome } from "../config";
 import { pinCore, unpinCore, validateManifest, writeManifestAtomic } from "../manifest";
-import { emitSuccess } from "../output";
+import { emitSuccess, unknownSubcommandError } from "../output";
 import { confirmIfNeeded, loadManifestContext } from "./shared";
 export async function runCore(
   subCommand: string,
@@ -8,7 +8,7 @@ export async function runCore(
   options: { isJson: boolean; dryRun: boolean },
 ): Promise<void> {
   if (subCommand !== "pin" && subCommand !== "unpin") {
-    throw new Error("usage: skillmux core <pin|unpin>");
+    throw unknownSubcommandError("core", subCommand, ["pin", "unpin"]);
   }
   const skillIds = args.filter((arg) => !arg.startsWith("-"));
   if (skillIds.length === 0) {