@klhapp/skillmux 1.9.3 → 1.11.0

package/src/cli.ts

@@ -1,129 +1,52 @@
 #!/usr/bin/env bun
 import packageJson from "../package.json" with { type: "json" };
-import { Database } from "bun:sqlite";
-import { existsSync, lstatSync, mkdirSync, rmSync } from "node:fs";
-import { hostname } from "node:os";
-import { join } from "node:path";
+import { lstatSync, mkdirSync } from "node:fs";
 
 import { createClients } from "./clients";
-import {
-  expandHome,
-  loadConfig,
-  migrateLegacyPaths,
-  resolveConfigPath,
-} from "./config";
+import { loadConfig } from "./config";
 import { openAudit } from "./db";
-import { diagnose } from "./doctor";
 import { getEffectiveConfig } from "./config-service";
 import { buildRedactor } from "./redact";
 import { evalVault } from "./eval";
-import {
-  assessClientReadiness,
-  detectInstalledClients,
-  planClientSurfaces,
-  resolveBuiltInTarget,
-  SUPPORTED_CLIENT_IDS,
-  type ClientId,
-  type ReadinessAxis,
-} from "./init-clients";
-import {
-  applyInstructionPlan,
-  planInstructionSetup,
-  rollbackInstructionPlan,
-} from "./init-instructions";
-import {
-  applyInit,
-  deriveTargetName,
-  detectSurfaces,
-  planInitManifest,
-  printLastMile,
-  surfaceCandidates,
-} from "./init";
-import {
-  assertHostAllowed,
-  cloneToTemp,
-  deriveRepoName,
-  installIntoVault,
-  isLocalFileUrl,
-  resolveCloneCommit,
-  resolveRepoSource,
-  resolveSkillDir,
-  validateSkillCandidate,
-} from "./install";
 import { runOutdated } from "./commands/outdated";
 import { runUpdate } from "./commands/update";
-import { hashSkillContent, writeSkillOrigin } from "./provenance";
-import {
-  parseManifest,
-  resolveManifestPath,
-  serializeManifest,
-  validateManifest,
-} from "./manifest";
-import { downloadLocalModels } from "./models";
+import { serializeManifest } from "./manifest";
 
-import {
-  parseCommaList,
-  promptMultiSelect,
-  promptText,
-  shouldUseWizard,
-} from "./prompts";
 import { backfillEmbeddings, configure, rebuildIndex } from "./router-core";
-import {
-  renderScanJson,
-  renderScanText,
-  scanExitCode,
-  scanPath,
-  type ScanSeverity,
-} from "./scan";
-import {
-  applyConfigInit,
-  inspectVault,
-  planConfigInit,
-  rollbackConfigInit,
-  type ConfigInitPlan,
-} from "./setup";
-import { getStats, renderStatsText, type StatsResponse } from "./stats";
-import {
-  installPostMergeHook,
-  resolveProjectPinDir,
-  restoreMonolith as restoreMonolithTarget,
-  syncProjectTargets,
-  syncTarget,
-  writeLocalVaultMarker,
-  type ProjectGroupInput,
-} from "./sync";
-import { scanVault, vaultResolutionOrder } from "./vault";
+import { type StatsResponse } from "./stats";
+import { scanVault } from "./vault";
 
-import {
-  addContext,
-  getCurrentContext,
-  listContexts,
-  removeContext,
-  resolveTarget,
-  useContext,
-  type ResolvedTarget,
-} from "./context";
-import { createTargetAdapter, isLoopbackHost, type TargetAdapter } from "./adapters";
+import { resolveContext, type ResolvedContext } from "./context";
+import { createContextAdapter, isLoopbackHost, type ContextAdapter } from "./adapters";
 import {
   emitSuccess,
   CliError,
   formatJsonEnvelope,
-  isInteractive,
   mapExitCode,
-  renderTable,
-  renderTargetBanner,
+  red,
   suggestCorrection,
+  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";
+import { runDoctor } from "./commands/doctor";
 import { runEvalPromote } from "./commands/eval";
+import { runInstall } from "./commands/install";
 import { runCore } from "./commands/core";
-import { configuredTargetForSurface, runProject } from "./commands/project";
-import { confirmAction, confirmIfNeeded } from "./commands/shared";
+import { runLocalVaultInit } from "./commands/local-vault";
+import { runModelDownload } from "./commands/models";
+import { runProject } from "./commands/project";
+import { runReport } from "./commands/report";
+import { runScan } from "./commands/scan";
+import { runSkill } from "./commands/skill";
 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",
@@ -147,6 +70,124 @@ const KNOWN_COMMANDS = [
   "local-vault",
 ];
 
+/**
+ * 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",
+};
+
+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.${guidance}`,
+    2,
+    "REMOTE_CONTEXT_UNSUPPORTED",
+    {
+      rejected_command: rejectedCommand,
+      ...(reason ? { reason } : {}),
+    },
+  );
+}
+
 function isDockerHostManagementCommand(command: string, subCommand: string): boolean {
   if (
     [
@@ -167,7 +208,7 @@ function isDockerHostManagementCommand(command: string, subCommand: string): boo
   }
 
   // eval promote only touches the mounted state_dir, unlike bare `eval`
-  // (vault ranking evaluation), which needs local embeddings and the vault.
+  // (vault ranking evaluation), which needs an embeddings client and the vault.
   if (command === "eval" && subCommand !== "promote") return true;
 
   return command === "config" && ["init", "set"].includes(subCommand);
@@ -237,52 +278,60 @@ async function main() {
     else if (arg === "--server") flagServer = rawArgv[++i];
   }
 
-  let resolvedTarget: ResolvedTarget = { 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,
     });
     return;
   }
 
-  // Only resolve target if command is target-aware or context/config
-  const isLocalConfigInit = command === "config" && rawArgv[1] === "init";
   if (
-    (["context", "config"].includes(command) &&
-      !isLocalConfigInit) ||
-    flagContext ||
-    flagServer
+    (rawArgv.includes("--help") || rawArgv.includes("-h")) &&
+    printCommandHelp(command)
   ) {
-    try {
-      resolvedTarget = await resolveTarget({
-        context: flagContext,
-        server: flagServer,
-      });
-    } catch (err: any) {
-      await handleError(err, { target: resolvedTarget, isJson, isVerbose });
-      return;
-    }
+    return;
   }
 
-  const adapter = createTargetAdapter(resolvedTarget, { allowInsecure });
+  try {
+    resolvedContext = await resolveContext({
+      context: flagContext,
+      server: flagServer,
+    });
+  } catch (err: any) {
+    await handleError(err, { context: resolvedContext, isJson, isVerbose });
+    return;
+  }
+
+  const localOnlyCommand = getLocalOnlyCommand(command, subCommand);
+  if (localOnlyCommand && resolvedContext.type === "remote") {
+    await handleError(remoteContextUnsupported(localOnlyCommand), {
+      context: resolvedContext,
+      isJson,
+      isVerbose,
+    });
+    return;
+  }
+
+  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,
         });
@@ -341,12 +390,18 @@ async function main() {
       case "report":
         await runReport(rawArgv.slice(1), {
           isJson,
-          target: resolvedTarget,
+          context: resolvedContext,
           allowInsecure,
+          adapter,
         });
         break;
       case "audit":
-        await runAudit(subCommand, commandArgs, { isJson, dryRun: isDryRun });
+        await runAudit(subCommand, commandArgs, {
+          isJson,
+          dryRun: isDryRun,
+          context: resolvedContext,
+          adapter,
+        });
         break;
       case "scan":
         await runScan(rawArgv.slice(1), { isJson });
@@ -362,15 +417,20 @@ async function main() {
         break;
       case "eval":
         if (subCommand === "promote") {
-          await runEvalPromote(commandArgs, { isJson, dryRun: isDryRun });
+          await runEvalPromote(commandArgs, { isJson, dryRun: isDryRun, adapter });
         } else if (subCommand === "") {
-          await runEval({ isJson });
+          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 });
+        await runDoctor({
+          isJson,
+          context: resolvedContext,
+          adapter,
+          args: rawArgv.slice(1),
+        });
         break;
       case "which":
         throw new Error(
@@ -402,99 +462,11 @@ async function main() {
       }
     }
   } catch (err: any) {
-    await handleError(err, { target: resolvedTarget, isJson, isVerbose });
+    await handleError(err, { context: resolvedContext, isJson, isVerbose });
   }
 }
 
-async function handleContextCommand(
-  sub: string,
-  args: string[],
-  ctx: { target: ResolvedTarget; isJson: boolean },
-) {
-  if (sub === "list") {
-    const contexts = await listContexts();
-    emitSuccess({ isJson: ctx.isJson, target: ctx.target }, contexts, () => {
-      renderTargetBanner(ctx.target);
-      renderTable(
-        [
-          { key: "name", header: "NAME" },
-          { key: "server", header: "SERVER" },
-          { key: "token_env", header: "TOKEN_ENV" },
-          { key: "isDefault", header: "DEFAULT" },
-        ],
-        contexts.map((c) => ({
-          ...c,
-          token_env: c.token_env ?? "-",
-          isDefault: c.isDefault ? "*" : "",
-        })),
-      );
-    });
-    return;
-  }
-
-  if (sub === "current") {
-    const current = await getCurrentContext();
-    emitSuccess({ isJson: ctx.isJson, target: ctx.target }, current, () => {
-      renderTargetBanner(ctx.target);
-      console.log(`Current context: ${current.name} (${current.server})`);
-    });
-    return;
-  }
-
-  if (sub === "add") {
-    const name = args[0];
-    let server: string | undefined;
-    let tokenEnv: string | undefined;
-    for (let i = 1; i < args.length; i++) {
-      if (args[i] === "--server") server = args[++i];
-      else if (args[i] === "--token-env") tokenEnv = args[++i];
-    }
-    if (!name || !server) {
-      throw new Error(
-        "usage: skillmux context add <name> --server <url> [--token-env <env_name>]",
-      );
-    }
-    await addContext(name, { server, token_env: tokenEnv });
-    emitSuccess(
-      { isJson: ctx.isJson, target: ctx.target },
-      { name, server, token_env: tokenEnv },
-      () => {
-        console.log(`Added context "${name}" -> ${server}`);
-      },
-    );
-    return;
-  }
 
-  if (sub === "use") {
-    const name = args[0];
-    if (!name) throw new Error("usage: skillmux context use <name>");
-    await useContext(name);
-    emitSuccess(
-      { isJson: ctx.isJson, target: ctx.target },
-      { default_context: name },
-      () => {
-        console.log(`Switched default context to "${name}"`);
-      },
-    );
-    return;
-  }
-
-  if (sub === "remove") {
-    const name = args[0];
-    if (!name) throw new Error("usage: skillmux context remove <name>");
-    await removeContext(name);
-    emitSuccess(
-      { isJson: ctx.isJson, target: ctx.target },
-      { removed: name },
-      () => {
-        console.log(`Removed context "${name}"`);
-      },
-    );
-    return;
-  }
-
-  throw new Error("usage: skillmux context <add|list|current|use|remove>");
-}
 
 async function handleCompletionsCommand(shell: string) {
   if (shell !== "bash" && shell !== "zsh" && shell !== "fish") {
@@ -505,7 +477,7 @@ async function handleCompletionsCommand(shell: string) {
 
 async function handleError(
   err: any,
-  opts: { target: ResolvedTarget; isJson: boolean; isVerbose: boolean },
+  opts: { context: ResolvedContext; isJson: boolean; isVerbose: boolean },
 ) {
   const code = mapExitCode(err);
   process.exitCode = code;
@@ -526,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,
@@ -536,11 +508,13 @@ async function handleError(
     console.log(JSON.stringify(env));
   } else {
     console.error(
-      msg.startsWith("usage:") ||
-        msg.startsWith("Unknown") ||
-        msg.startsWith("error:")
-        ? msg
-        : `error: ${msg}`,
+      red(
+        msg.startsWith("usage:") ||
+          msg.startsWith("Unknown") ||
+          msg.startsWith("error:")
+          ? msg
+          : `error: ${msg}`,
+      ),
     );
     if (opts.isVerbose && err instanceof Error && err.stack) {
       console.error(redact(err.stack));
@@ -548,6 +522,188 @@ async function handleError(
   }
 }
 
+const COMMAND_HELP: Record<string, string> = {
+  context: `context: manage named CLI contexts for remote administration
+
+usage:
+  skillmux context list
+  skillmux context current
+  skillmux context add <name> --server <url> [--token-env <env_name>]
+  skillmux context use <name>
+  skillmux context remove <name>`,
+
+  config: `config: inspect or update server/machine configuration
+
+usage:
+  skillmux config init --vault <path> --yes
+  skillmux config show [--sources]
+  skillmux config get <key>
+  skillmux config set <key> <value> [--dry-run]
+  skillmux config validate
+  skillmux config diff
+  skillmux config status
+
+Accepts --context <name> / --server <url> to target a remote deployment.`,
+
+  completions: `completions: generate a shell completion script
+
+usage:
+  skillmux completions <bash|zsh|fish>`,
+
+  serve: `serve: start the MCP server
+
+usage:
+  skillmux serve [--transport stdio|http] [--port <port>] [--stats-port <port>]
+
+--transport defaults to stdio. --stats-port exposes GET /health and GET /stats
+alongside a stdio transport without opening the full HTTP surface.`,
+
+  index: `index: rebuild the local retrieval index and backfill embeddings
+
+usage:
+  skillmux index`,
+
+  sync: `sync: apply the manifest to native agent target directories
+
+usage:
+  skillmux sync [--dry-run] [--restore-monolith] [--install-hook] [--yes] [--json]`,
+
+  init: `init: guided setup for native skill management
+
+usage:
+  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]
+
+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>...]
+                [--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> (--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
+
+--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
+
+usage:
+  skillmux core pin <skill_id>... --yes
+  skillmux core unpin <skill_id>... --yes`,
+
+  report: `report: show routing/fetch-outcome audit statistics
+
+usage:
+  skillmux report [--context <name> | --server <url> | --db <path>] --since <window> [--json]`,
+
+  audit: `audit: prune the audit database
+
+usage:
+  skillmux audit prune [--older-than <window>] [--dry-run] [--yes] [--json]
+
+Accepts --context <name> / --server <url> to prune a remote deployment's audit db.`,
+
+  scan: `scan: check the vault for install-time or integrity issues
+
+usage:
+  skillmux scan [path] [--format text|json] [--fail-on low|medium|high] [--json]`,
+
+  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]`,
+
+  outdated: `outdated: list installed skills with a newer upstream version
+
+usage:
+  skillmux outdated [--allow-local-source] [--json]`,
+
+  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]`,
+
+  eval: `eval: run retrieval evaluation against the holdout set
+
+usage:
+  skillmux eval [--json]
+  skillmux eval promote --since <window> [--out <path>] [--dry-run] [--yes] [--json]
+
+Accepts --context <name> / --server <url> to evaluate a remote deployment.`,
+
+  doctor: `doctor: check server/environment readiness
+
+usage:
+  skillmux doctor [--json]
+
+Accepts --context <name> / --server <url> to check a remote deployment.`,
+
+  skill: `skill: inspect local vault skill resolution
+
+usage:
+  skillmux skill which <skill_id>  (local vault shadow resolution; unrelated to MCP routing)`,
+
+  "local-vault": `local-vault: register an additional local vault checkout
+
+usage:
+  skillmux local-vault init <path> --yes`,
+
+  models: `models: manage local embedding model downloads
+
+usage:
+  skillmux models download`,
+};
+
+function printCommandHelp(command: string): boolean {
+  const help = COMMAND_HELP[command];
+  if (!help) return false;
+  console.log(help);
+  return true;
+}
+
 function printHelp(): void {
   if (process.env.RUNNING_IN_DOCKER === "true") {
     console.log(`Skillmux server image
@@ -570,35 +726,35 @@ 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>
-
-Init clients:
-  claude-code, codex, gemini-cli, opencode, github-copilot, windsurf,
-  antigravity, goose, hermes, skillmux-mcp
+  skillmux skill which <skill_id>  (local vault shadow resolution; unrelated to MCP routing)
 
-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]
 
 Commands:
   serve, index, sync, init, project, target, core, report, audit, scan, install, outdated, update,
-  eval, doctor, skill, local-vault, config, models, context, completions`);
+  eval, doctor, skill, local-vault, config, models, context, completions
+
+Run "skillmux <command> --help" for a command's full usage.`);
 }
 
 // ---------------------------------------------------------------------------
@@ -649,9 +805,7 @@ async function runIndex(): Promise<void> {
   const config = await loadConfig();
   configure({ config, clients: createClients(config) });
   const report = await rebuildIndex((skillId, error) => {
-    console.error(
-      `warning: keeping previous index entry for ${skillId}: ${error}`,
-    );
+    warn(`keeping previous index entry for ${skillId}: ${error}`);
   });
   const retainedNote =
     report.retained.length > 0
@@ -669,12 +823,14 @@ async function runIndex(): Promise<void> {
   }
 }
 
-async function runEval(options: { isJson: boolean }): Promise<void> {
+async function runEval(options: { isJson: boolean; adapter: ContextAdapter }): Promise<void> {
   const config = await loadConfig();
   configure({ config, clients: createClients(config) });
 
-  const report = await evalVault().catch((error: unknown) => {
-    throw new Error(`eval requires local embeddings: ${String(error)}`);
+  const report = await options.adapter.evalRun().catch((error: unknown) => {
+    throw new Error(
+      `eval requires an embeddings client (local model or a configured remote endpoint): ${String(error)}`,
+    );
   });
   emitSuccess({ isJson: options.isJson }, report, () => {
     console.log(`holdout queries:   ${report.queries}`);
@@ -691,1085 +847,6 @@ async function runEval(options: { isJson: boolean }): Promise<void> {
   });
 }
 
-async function runDoctor(options: { isJson: boolean }): Promise<void> {
-  const effective = await getEffectiveConfig(resolveConfigPath());
-  const report = await diagnose(effective.effective, process.env, effective.sources);
-  emitSuccess({ isJson: options.isJson }, report, () => {
-    console.log(`version: ${report.version}`);
-    console.log(`runtime: ${report.runtime}`);
-    console.log(`image variant: ${report.image_variant ?? "none"}`);
-    console.log(`vault path: ${report.vault_path}`);
-    console.log(`state directory: ${report.state_dir}`);
-    console.log(`inference mode: ${report.mode}`);
-    console.log(`routing capability: ${report.capability}`);
-    console.log(`retrieval capability: ${report.retrieval_capability}`);
-    for (const check of report.checks)
-      console.log(
-        `${check.ok ? "ok" : "fail"}: ${check.name} - ${check.detail}`,
-      );
-  });
-  if (report.checks.some((check) => !check.ok)) process.exitCode = 1;
-}
-
-async function runSkill(subCommand: string, args: string[]): Promise<void> {
-  if (subCommand !== "which") throw new Error("usage: skillmux skill <which>");
-  await runWhich(args);
-}
-
-async function runWhich(args: string[]): Promise<void> {
-  const skillId = args[0];
-  if (!skillId) throw new Error("usage: skillmux skill which <skill_id>");
-  const config = await loadConfig();
-  const vaultPath = expandHome(config.vault_path);
-  const localVaultPaths = config.local_vault_paths.map(expandHome);
-  const roots = vaultResolutionOrder(vaultPath, localVaultPaths).filter(
-    (root) => existsSync(join(root, skillId, "SKILL.md")),
-  );
-  if (roots.length === 0) {
-    console.log(`${skillId}: not found in vault_path or local_vault_paths`);
-    process.exitCode = 1;
-    return;
-  }
-  console.log(`${skillId}: serving from ${roots[0]}`);
-  for (const shadowedRoot of roots.slice(1))
-    console.log(`  shadows: ${shadowedRoot}`);
-}
-
-async function runLocalVaultInit(
-  args: string[],
-  options: { isJson: boolean; dryRun: boolean },
-): Promise<void> {
-  const path = args[0];
-  if (!path) throw new Error("usage: skillmux local-vault init <path> --yes");
-  const expanded = expandHome(path);
-  const config = await loadConfig();
-  const localVaultPaths = config.local_vault_paths.map(expandHome);
-  if (!localVaultPaths.includes(expanded)) {
-    throw new Error(
-      `"${path}" is not one of the configured local_vault_paths — add it to config.toml first`,
-    );
-  }
-  if (!existsSync(expanded)) throw new Error(`"${path}" does not exist`);
-  const markerPath = join(expanded, ".skillmux");
-  if (options.dryRun) {
-    emitSuccess(
-      { isJson: options.isJson },
-      {
-        marker_path: markerPath,
-        vault_path: expandHome(config.vault_path),
-      },
-      () =>
-        console.log(
-          `local-vault init: ${markerPath} (role: local_vault, vault_path: ${expandHome(config.vault_path)}) (dry-run)`,
-        ),
-    );
-    return;
-  }
-  if (
-    !(await confirmIfNeeded({
-      confirmed: args.includes("--yes"),
-      isJson: options.isJson,
-      prompt: `Mark ${expanded} as a local_vault (role: local_vault, vault_path: ${expandHome(config.vault_path)})?`,
-      nonInteractiveError:
-        "skillmux local-vault init requires --yes when run non-interactively",
-    }))
-  )
-    return;
-  writeLocalVaultMarker(expanded, expandHome(config.vault_path));
-  emitSuccess(
-    { isJson: options.isJson },
-    {
-      marker_path: markerPath,
-      vault_path: expandHome(config.vault_path),
-    },
-    () =>
-      console.log(
-        `wrote ${markerPath} (role: local_vault, vault_path: ${expandHome(config.vault_path)})`,
-      ),
-  );
-}
-
-async function runModelDownload(options: { isJson: boolean }): Promise<void> {
-  const cacheDir = await downloadLocalModels(await loadConfig());
-  emitSuccess({ isJson: options.isJson }, { cache_dir: cacheDir }, () =>
-    console.log(`models ready in ${cacheDir}`),
-  );
-}
-
-function parseSyncArgs(args: string[]): {
-  dryRun: boolean;
-  restoreMonolith: boolean;
-  installHook: boolean;
-  yes: boolean;
-} {
-  let dryRun = false;
-  let restoreMonolith = false;
-  let installHook = false;
-  let yes = false;
-  for (const arg of args) {
-    if (arg === "--dry-run") dryRun = true;
-    else if (arg === "--restore-monolith") restoreMonolith = true;
-    else if (arg === "--install-hook") installHook = true;
-    else if (arg === "--yes") yes = true;
-    else throw new Error(`unknown sync option: ${arg}`);
-  }
-  return { dryRun, restoreMonolith, installHook, yes };
-}
-
-/**
- * A target directory that doesn't exist yet is about to be created by `sync`.
- * `manifest.targets[*].dir` is vault content — readable and writable by whatever
- * populated the vault (a shared git-backed vault pulled in, or a hand-edit) — and
- * `sync` can run unattended via the `--install-hook` post-merge hook. Without this
- * gate, a tampered manifest naming a brand-new path gets that directory silently
- * created (and populated with symlinks) the next time anyone pulls. Creation for
- * an as-yet-unseen directory therefore requires either `--yes` or an interactive
- * confirmation; once the directory exists, later syncs never hit this path again.
- */
-async function confirmNewSyncTarget(label: string, dir: string, yes: boolean): Promise<boolean> {
-  if (yes) return true;
-  if (!isInteractive()) {
-    console.log(
-      `${label}: skipped — ${dir} does not exist yet; creating it requires approval. Re-run "skillmux sync --yes", or run "skillmux sync" interactively, once you've confirmed this target is expected.`,
-    );
-    return false;
-  }
-  return confirmAction(`${label}: create new target directory ${dir}?`);
-}
-
-async function runSync(args: string[]): Promise<void> {
-  const { dryRun, restoreMonolith, installHook, yes } = parseSyncArgs(args);
-  const config = await loadConfig();
-  const vaultPath = expandHome(config.vault_path);
-
-  if (installHook) {
-    const result = installPostMergeHook(vaultPath);
-    console.log(
-      result.installed
-        ? "installed post-merge hook"
-        : "post-merge hook already installed",
-    );
-  }
-
-  const manifestPath = resolveManifestPath(vaultPath);
-  if (!manifestPath) {
-    console.log("no skillmux.toml found at vault root — nothing to sync");
-    return;
-  }
-
-  const manifest = parseManifest(await Bun.file(manifestPath).text());
-  const localVaultPaths = config.local_vault_paths.map(expandHome);
-  const { notes } = validateManifest(manifest, vaultPath, localVaultPaths);
-  for (const note of notes) console.log(`note: ${note}`);
-
-  const currentHost = hostname();
-  for (const [targetName, target] of Object.entries(manifest.targets)) {
-    if (target.host !== undefined && target.host !== currentHost) {
-      console.log(
-        `${targetName}: skipped (host ${target.host} does not match current host ${currentHost})`,
-      );
-      continue;
-    }
-    const targetDir = expandHome(target.dir);
-
-    if (restoreMonolith) {
-      const result = restoreMonolithTarget(targetDir, vaultPath);
-      console.log(
-        result.restored
-          ? `${targetName}: restored to a vault symlink`
-          : `${targetName}: not owned by skillmux, left untouched`,
-      );
-      continue;
-    }
-
-    if (!dryRun && !existsSync(targetDir)) {
-      const approved = await confirmNewSyncTarget(targetName, targetDir, yes);
-      if (!approved) {
-        if (isInteractive()) {
-          console.log(`${targetName}: skipped — creating ${targetDir} was not approved`);
-        }
-        continue;
-      }
-    }
-
-    const suffix = dryRun ? " (dry-run)" : "";
-    const result = syncTarget(
-      {
-        vaultPath,
-        targetDir,
-        targetName,
-        coreSkillIds: manifest.core.skills,
-        localVaultPaths,
-      },
-      { dryRun },
-    );
-    console.log(
-      `${targetName}: +${result.added.length} -${result.removed.length}${suffix}`,
-    );
-    if (result.skipped.length > 0) {
-      console.log(
-        `  warning: refused to sync ${result.skipped.join(", ")} — skill directory contains a symlink`,
-      );
-    }
-
-    if (target.project_groups.length > 0) {
-      const allGroups = manifest.project ?? {};
-      const projectGroups: Record<string, ProjectGroupInput> = {};
-      for (const groupName of target.project_groups) {
-        const group = allGroups[groupName]!;
-        const approvedPaths: string[] = [];
-        for (const path of group.paths) {
-          // Mirror syncProjectTargets' own `if (!existsSync(path)) continue` so we
-          // never prompt for a project path it would silently skip anyway.
-          if (!existsSync(path)) continue;
-          const pinDir = resolveProjectPinDir(targetDir, path);
-          if (dryRun || existsSync(pinDir)) {
-            approvedPaths.push(path);
-            continue;
-          }
-          const approved = await confirmNewSyncTarget(`${targetName}/${groupName}`, pinDir, yes);
-          if (approved) approvedPaths.push(path);
-        }
-        projectGroups[groupName] = { ...group, paths: approvedPaths };
-      }
-      const projectResults = syncProjectTargets(
-        { vaultPath, targetDir, targetName, projectGroups, localVaultPaths },
-        { dryRun },
-      );
-      for (const projectResult of projectResults) {
-        console.log(
-          `  ${projectResult.group} -> ${projectResult.pinDir}: +${projectResult.added.length} -${projectResult.removed.length}${suffix}`,
-        );
-        if (projectResult.skipped.length > 0) {
-          console.log(
-            `    warning: refused to sync ${projectResult.skipped.join(", ")} — skill directory contains a symlink`,
-          );
-        }
-      }
-    }
-  }
-}
-
-function parseInitArgs(args: string[]): {
-  targets: string[];
-  clients: string[];
-  coreSkillIds: string[];
-  customPath?: string;
-  migrateFullVault: boolean;
-  skipInstructions: boolean;
-  sync: boolean;
-  vaultPath?: string;
-  yes: boolean;
-} {
-  const targets: string[] = [];
-  const clients: string[] = [];
-  const coreSkillIds: string[] = [];
-  let customPath: string | undefined;
-  let migrateFullVault = false;
-  let skipInstructions = false;
-  let sync = true;
-  let vaultPath: string | undefined;
-  let yes = false;
-  for (let i = 0; i < args.length; i++) {
-    const option = args[i];
-    if (option === "--target") {
-      const value = args[i + 1];
-      if (!value) throw new Error("--target requires a name");
-      targets.push(value);
-      i++;
-    } else if (option === "--client") {
-      const value = args[i + 1];
-      if (!value) throw new Error("--client requires a name");
-      clients.push(value);
-      i++;
-    } else if (option === "--vault") {
-      const value = args[i + 1];
-      if (!value) throw new Error("--vault requires a path");
-      vaultPath = value;
-      i++;
-    } else if (option === "--dir") {
-      const value = args[i + 1];
-      if (!value) throw new Error("--dir requires a directory");
-      customPath = value;
-      i++;
-    } else if (option === "--core") {
-      const value = args[i + 1];
-      if (!value) throw new Error("--core requires a skill_id");
-      coreSkillIds.push(value);
-      i++;
-    } else if (
-      option === "--dry-run" ||
-      option === "--json" ||
-      option === "--interactive"
-    ) {
-      continue;
-    } else if (option === "--migrate-full-vault") {
-      migrateFullVault = true;
-    } else if (option === "--no-instructions") {
-      skipInstructions = true;
-    } else if (option === "--no-sync") {
-      sync = false;
-    } else if (option === "--yes") {
-      yes = true;
-    } else {
-      throw new Error(`unknown init option: ${option}`);
-    }
-  }
-  return {
-    targets,
-    clients,
-    coreSkillIds,
-    customPath,
-    migrateFullVault,
-    skipInstructions,
-    sync,
-    vaultPath,
-    yes,
-  };
-}
-
-async function runInit(
-  args: string[],
-  options: { isJson: boolean; dryRun: boolean },
-): Promise<void> {
-  const {
-    targets: explicitTargets,
-    clients: requestedClients,
-    coreSkillIds,
-    customPath,
-    migrateFullVault,
-    skipInstructions,
-    sync,
-    vaultPath: requestedVaultPath,
-    yes,
-  } = parseInitArgs(args);
-  const guided = shouldUseWizard(args, {
-    interactive: isInteractive(),
-    json: options.isJson,
-    dryRun: options.dryRun,
-  });
-  migrateLegacyPaths();
-  const configPath = resolveConfigPath();
-  let configPlan: ConfigInitPlan | undefined;
-  let vaultPath: string;
-  if (!existsSync(configPath)) {
-    const bootstrapVaultPath =
-      requestedVaultPath ??
-      (!options.isJson && isInteractive() ? "~/skills" : undefined);
-    if (!bootstrapVaultPath) {
-      throw new Error(
-        `machine config does not exist: ${configPath}; re-run with --vault <path>`,
-      );
-    }
-    configPlan = planConfigInit(configPath, expandHome(bootstrapVaultPath));
-    vaultPath = configPlan.vaultPath;
-    if (!options.isJson) {
-      console.log(`config create: ${configPath}`);
-    }
-  } else {
-    const config = await loadConfig();
-    vaultPath = expandHome(config.vault_path);
-    if (requestedVaultPath && expandHome(requestedVaultPath) !== vaultPath) {
-      throw new Error(
-        `machine config already uses vault_path ${vaultPath}; --vault does not overwrite existing config`,
-      );
-    }
-  }
-
-  const vaultHealth = inspectVault(vaultPath);
-  if (!vaultHealth.ok) {
-    throw new Error(vaultHealth.message);
-  }
-
-  let selectedClients = requestedClients;
-  if (guided) {
-    const detected = detectInstalledClients({
-      codexHome: process.env.CODEX_HOME
-        ? expandHome(process.env.CODEX_HOME)
-        : undefined,
-    });
-    const evidence = new Map(
-      detected.map((item) => [item.client, item.evidence]),
-    );
-    selectedClients = await promptMultiSelect(
-      "Which clients do you use?",
-      SUPPORTED_CLIENT_IDS.map((client) => ({
-        value: client,
-        label: client,
-        detail: evidence.has(client)
-          ? `detected: ${evidence.get(client)}`
-          : undefined,
-        selected: evidence.has(client) || requestedClients.includes(client),
-      })),
-    );
-  }
-  let selectedCoreSkillIds = coreSkillIds;
-  if (guided) {
-    selectedCoreSkillIds = parseCommaList(
-      await promptText(
-        "Core skill IDs to add, comma-separated",
-        coreSkillIds.join(","),
-      ),
-    );
-  }
-
-  const clientPlan = planClientSurfaces(selectedClients, {
-    codexHome: process.env.CODEX_HOME
-      ? expandHome(process.env.CODEX_HOME)
-      : undefined,
-  });
-  const instructionPlan = planInstructionSetup(
-    skipInstructions ? [] : clientPlan.clients.map((client) => client.id),
-    {
-      codexHome: process.env.CODEX_HOME
-        ? expandHome(process.env.CODEX_HOME)
-        : undefined,
-    },
-  );
-  const instructionReadiness: Partial<Record<ClientId, ReadinessAxis>> = {};
-  for (const change of instructionPlan.changes) {
-    for (const client of change.clients) {
-      instructionReadiness[client] = {
-        status: change.status === "unchanged" ? "ready" : "planned",
-        detail: change.path,
-      };
-    }
-  }
-  for (const manual of instructionPlan.manual) {
-    instructionReadiness[manual.client] = {
-      status: "manual",
-      detail: manual.reason,
-    };
-  }
-  const builtInNames = new Set([
-    "agent-skills",
-    "claude-code",
-    "codex",
-    "custom",
-    "agents",
-    "claude",
-  ]);
-  const explicitSurfaceTargets = explicitTargets
-    .filter((name) => builtInNames.has(name))
-    .map((name) =>
-      resolveBuiltInTarget(name, {
-        codexHome: process.env.CODEX_HOME
-          ? expandHome(process.env.CODEX_HOME)
-          : undefined,
-        customPath: customPath ? expandHome(customPath) : undefined,
-      }),
-    );
-  if (customPath && !explicitTargets.includes("custom")) {
-    throw new Error("--dir may only be used with --target custom");
-  }
-  for (const target of explicitSurfaceTargets) {
-    if (target.warning) console.error(`warning: ${target.warning}`);
-  }
-  const targetByPath = new Map(
-    explicitSurfaceTargets.map(
-      (target) => [target.path, target.targetName] as const,
-    ),
-  );
-  const existingManifestPath = resolveManifestPath(vaultPath);
-  const existingManifest = existingManifestPath
-    ? parseManifest(await Bun.file(existingManifestPath).text())
-    : undefined;
-  for (const surface of clientPlan.surfaces) {
-    if (!targetByPath.has(surface.path)) {
-      targetByPath.set(
-        surface.path,
-        existingManifest
-          ? (configuredTargetForSurface(existingManifest, surface) ??
-              surface.targetName)
-          : surface.targetName,
-      );
-    }
-  }
-  const candidatePaths = [
-    ...new Set([
-      ...surfaceCandidates().map(expandHome),
-      ...targetByPath.keys(),
-    ]),
-  ];
-  const candidates = detectSurfaces(candidatePaths, vaultPath);
-  if (!options.isJson) {
-    for (const candidate of candidates) {
-      const name =
-        targetByPath.get(candidate.path) ?? deriveTargetName(candidate.path);
-      if (candidate.state === "missing") {
-        console.log(`${name} (${candidate.path}): not found`);
-        continue;
-      }
-      if (candidate.state === "broken-symlink") {
-        console.log(`${name} (${candidate.path}): broken symlink`);
-        continue;
-      }
-      if (candidate.state === "full-vault") {
-        console.log(
-          `${name} (${candidate.path}): full-vault -> ${candidate.canonicalPath}`,
-        );
-        continue;
-      }
-      if (candidate.state === "external-symlink") {
-        console.log(
-          `${name} (${candidate.path}): external symlink -> ${candidate.canonicalPath}`,
-        );
-        continue;
-      }
-      if (candidate.state === "unsupported") {
-        console.log(
-          `${name} (${candidate.path}): unsupported filesystem entry`,
-        );
-        continue;
-      }
-      const kind = "real dir";
-      const marked = candidate.alreadyMarked
-        ? ", already skillmux-managed"
-        : "";
-      console.log(
-        `${name} (${candidate.path}): ${kind}, ${candidate.skillCount} skills${marked}`,
-      );
-    }
-    for (const readiness of assessClientReadiness(
-      clientPlan,
-      instructionReadiness,
-    )) {
-      console.log(`\n${readiness.client} readiness:`);
-      console.log(
-        `  skill surface: ${readiness.skillSurface.status} — ${readiness.skillSurface.detail}`,
-      );
-      console.log(
-        `  MCP registration: ${readiness.mcpRegistration.status} — ${readiness.mcpRegistration.detail}`,
-      );
-      console.log(
-        `  instructions: ${readiness.instructionSetup.status} — ${readiness.instructionSetup.detail}`,
-      );
-    }
-    for (const change of instructionPlan.changes) {
-      console.log(
-        `instructions ${change.status}: ${change.path} (${change.clients.join(", ")})`,
-      );
-    }
-    for (const manual of instructionPlan.manual) {
-      console.log(`instructions manual: ${manual.client} — ${manual.reason}`);
-    }
-  }
-
-  const requestedTargets = [
-    ...new Set([
-      ...explicitTargets.filter((name) => !builtInNames.has(name)),
-      ...targetByPath.values(),
-    ]),
-  ];
-  const hasInstructionWrites = instructionPlan.changes.some(
-    (change) => change.status !== "unchanged",
-  );
-  const hasConfigWrite = configPlan?.action === "create";
-  const hasChanges = !(
-    requestedTargets.length === 0 &&
-    !hasInstructionWrites &&
-    selectedCoreSkillIds.length === 0 &&
-    !hasConfigWrite
-  );
-
-  const byName = new Map(
-    candidates
-      .filter(
-        (candidate) =>
-          candidate.deliveryMode === "managed-pins" ||
-          (migrateFullVault && candidate.state === "full-vault"),
-      )
-      .map(
-        (candidate) =>
-          [
-            targetByPath.get(candidate.path) ??
-              deriveTargetName(candidate.path),
-            candidate,
-          ] as const,
-      ),
-  );
-  const allCandidatesByName = new Map(
-    candidates.map(
-      (candidate) =>
-        [
-          targetByPath.get(candidate.path) ?? deriveTargetName(candidate.path),
-          candidate,
-        ] as const,
-    ),
-  );
-  for (const name of requestedTargets) {
-    if (!byName.has(name)) {
-      if (allCandidatesByName.get(name)?.state === "full-vault") {
-        throw new Error(
-          `target "${name}" is a full-vault surface; re-run with --migrate-full-vault to convert it to managed pins`,
-        );
-      }
-      throw new Error(
-        `unknown --target "${name}": not among detected surfaces`,
-      );
-    }
-  }
-
-  const confirmedTargets = requestedTargets.map((name) => {
-    const candidate = byName.get(name)!;
-    return {
-      name,
-      dir: candidate.path,
-      ...(candidate.state === "full-vault" ? { migrateFullVault: true } : {}),
-    };
-  });
-  const plannedManifest = planInitManifest(
-    vaultPath,
-    confirmedTargets,
-    selectedCoreSkillIds,
-  );
-  const serializedPlan = {
-    vault_path: vaultPath,
-    config: configPlan
-      ? { path: configPlan.configPath, action: configPlan.action }
-      : { path: configPath, action: "preserve" },
-    clients: clientPlan.clients.map((client) => client.id),
-    targets: confirmedTargets,
-    core: plannedManifest.core.skills,
-    instructions: instructionPlan.changes.map(({ path, clients, status }) => ({
-      path,
-      clients,
-      status,
-    })),
-    manual: instructionPlan.manual,
-  };
-  if (!hasChanges) {
-    if (options.isJson) {
-      console.log(
-        JSON.stringify({
-          schema_version: 1,
-          ok: true,
-          command: "init",
-          phase: "plan",
-          dry_run: options.dryRun,
-          applied: false,
-          plan: serializedPlan,
-        }),
-      );
-    } else {
-      console.log("\nno managed-pins surface selected — nothing written.");
-    }
-    return;
-  }
-  if (!options.isJson) {
-    for (const target of confirmedTargets.filter(
-      (target) => target.migrateFullVault,
-    )) {
-      console.log(
-        `full-vault migration ${target.name}: ${vaultHealth.skillCount} visible skills -> ` +
-          `${plannedManifest.core.skills.length} core ${plannedManifest.core.skills.length === 1 ? "skill" : "skills"} after sync`,
-      );
-    }
-  }
-  if (options.dryRun) {
-    if (options.isJson) {
-      console.log(
-        JSON.stringify({
-          schema_version: 1,
-          ok: true,
-          command: "init",
-          phase: "plan",
-          dry_run: true,
-          applied: false,
-          plan: serializedPlan,
-        }),
-      );
-    } else {
-      console.log(
-        `\ndry-run: ${confirmedTargets.length} target(s), ` +
-          `${instructionPlan.changes.filter((change) => change.status !== "unchanged").length} instruction file(s), ` +
-          `core: ${plannedManifest.core.skills.join(", ") || "(unchanged)"}`,
-      );
-    }
-    return;
-  }
-
-  if (!yes) {
-    if (!options.isJson && isInteractive()) {
-      if (guided) {
-        console.log("\nReview");
-        console.log(`  clients: ${selectedClients.join(", ") || "(none)"}`);
-        console.log(
-          `  targets: ${confirmedTargets.map((target) => `${target.name} -> ${target.dir}`).join(", ") || "(none)"}`,
-        );
-        console.log(
-          `  instructions: ${instructionPlan.changes.filter((change) => change.status !== "unchanged").length} file(s)`,
-        );
-        console.log(
-          `  core: ${plannedManifest.core.skills.join(", ") || "(none)"}`,
-        );
-        console.log(`  sync: ${sync ? "yes" : "no"}`);
-        if (!(await confirmAction("Apply this setup plan?"))) {
-          console.log("init cancelled");
-          return;
-        }
-      } else {
-        const prompts = [
-          ...confirmedTargets.map(
-            (target) => `Adopt ${target.name} at ${target.dir}?`,
-          ),
-          ...instructionPlan.changes
-            .filter((change) => change.status !== "unchanged")
-            .map(
-              (change) => `${change.status} instruction file ${change.path}?`,
-            ),
-          ...(hasConfigWrite ? [`Create machine config ${configPath}?`] : []),
-          ...(selectedCoreSkillIds.length > 0
-            ? [`Pin core skills: ${selectedCoreSkillIds.join(", ")}?`]
-            : []),
-        ];
-        for (const prompt of prompts) {
-          if (!(await confirmAction(prompt))) {
-            console.log("init cancelled; nothing written");
-            return;
-          }
-        }
-      }
-    } else {
-      throw new Error(
-        "skillmux init requires --yes before applying target, instruction, or core changes non-interactively",
-      );
-    }
-  }
-
-  let configCreated = false;
-  let instructionsApplied = false;
-  const applyAdditional = () => {
-    try {
-      if (configPlan?.action === "create") {
-        configCreated = applyConfigInit(configPlan) === "created";
-      }
-      if (hasInstructionWrites) {
-        applyInstructionPlan(instructionPlan);
-        instructionsApplied = true;
-      }
-    } catch (error) {
-      if (configCreated && configPlan) rollbackConfigInit(configPlan);
-      configCreated = false;
-      throw error;
-    }
-  };
-  const rollbackAdditional = () => {
-    if (instructionsApplied) rollbackInstructionPlan(instructionPlan);
-    if (configCreated && configPlan) rollbackConfigInit(configPlan);
-  };
-
-  if (confirmedTargets.length === 0 && selectedCoreSkillIds.length === 0) {
-    applyAdditional();
-  } else {
-    applyInit(
-      vaultPath,
-      confirmedTargets,
-      hasInstructionWrites || hasConfigWrite
-        ? {
-            apply: applyAdditional,
-            rollback: rollbackAdditional,
-          }
-        : undefined,
-      selectedCoreSkillIds,
-    );
-  }
-
-  if (options.isJson) {
-    console.log(
-      JSON.stringify({
-        schema_version: 1,
-        ok: true,
-        command: "init",
-        phase: "result",
-        dry_run: false,
-        applied: true,
-        plan: serializedPlan,
-        result: {
-          config_created: configCreated,
-          targets_adopted: confirmedTargets.map((target) => target.name),
-          instructions_changed: instructionPlan.changes
-            .filter((change) => change.status !== "unchanged")
-            .map((change) => change.path),
-          core: plannedManifest.core.skills,
-        },
-      }),
-    );
-    return;
-  }
-  if (configCreated) console.log(`created ${configPath}`);
-  if (confirmedTargets.length > 0) {
-    console.log(
-      `\nwrote ${join(vaultPath, "skillmux.toml")}, adopted: ${confirmedTargets.map((t) => t.name).join(", ")}`,
-    );
-  } else if (selectedCoreSkillIds.length > 0) {
-    console.log(`\nwrote ${join(vaultPath, "skillmux.toml")}`);
-  }
-  if (plannedManifest.core.skills.length === 0 && confirmedTargets.length > 0) {
-    console.log("next: skillmux core pin <skill_id> --yes");
-  }
-  if (confirmedTargets.length > 0) console.log("next: skillmux sync");
-  if (
-    selectedClients.length === 0 ||
-    selectedClients.includes("skillmux-mcp")
-  ) {
-    console.log(`\n${printLastMile()}`);
-  }
-  // Reaching this point already required approval above (--yes, or an accepted
-  // confirmAction naming these exact targets/dirs) — that approval covers whatever
-  // new target directories this init just adopted, so runSync's own new-target
-  // confirmation gate would just be a redundant (and non-interactively,
-  // silently-skipping) re-ask.
-  if (guided && sync && confirmedTargets.length > 0) await runSync(["--yes"]);
-}
-
-function parseReportArgs(args: string[]): {
-  db?: string;
-  since?: string;
-} {
-  let db: string | undefined;
-  let since: string | undefined;
-  for (let i = 0; i < args.length; i++) {
-    const option = args[i];
-    const value = args[i + 1];
-    if (option === "--db") {
-      if (!value) throw new Error("--db requires a path");
-      db = value;
-      i++;
-    } else if (option === "--since") {
-      if (!value) throw new Error("--since requires a window");
-      since = value;
-      i++;
-    } else if (option === "--json") {
-      // handled globally by main()'s isJson flag; recognized here so it isn't rejected
-    } else if (option === "--server" || option === "--context") {
-      // handled globally by main()'s resolveTarget(); recognized here so it isn't rejected
-      i++;
-    } else if (option === "--allow-insecure") {
-      // handled globally by main()'s allowInsecure flag; recognized here so it isn't rejected
-    } else {
-      throw new Error(`unknown report option: ${option}`);
-    }
-  }
-  return { db, since };
-}
-
-async function runReport(
-  args: string[],
-  options: { isJson: boolean; target: ResolvedTarget; allowInsecure: boolean },
-): 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")
-    throw new Error("--db and --context/--server are mutually exclusive");
-
-  if (options.target.type === "remote") {
-    const { server, token_env } = options.target;
-    const url = new URL(`${server.replace(/\/$/, "")}/stats`);
-    url.searchParams.set("since", since);
-    if (
-      url.protocol === "http:" &&
-      !isLoopbackHost(url.hostname) &&
-      !options.allowInsecure
-    ) {
-      throw new Error(
-        `Plaintext HTTP report target not allowed for non-loopback server "${server}". Pass --allow-insecure to bypass.`,
-      );
-    }
-    const headers: Record<string, string> = {};
-    if (token_env) {
-      const token = process.env[token_env];
-      if (token) headers.Authorization = `Bearer ${token}`;
-    }
-    const res = await fetch(url, { headers });
-    if (!res.ok)
-      throw new Error(
-        `skillmux report --server failed: ${res.status} ${await res.text()}`,
-      );
-    const stats = (await res.json()) as StatsResponse;
-    emitSuccess({ isJson: options.isJson }, stats, () =>
-      console.log(renderStatsText(stats)),
-    );
-    return;
-  }
-
-  const db = dbPath
-    ? new Database(dbPath, { readonly: true })
-    : openAudit(expandHome((await loadConfig()).state_dir));
-  const stats = getStats(db, since);
-  emitSuccess({ isJson: options.isJson }, stats, () =>
-    console.log(renderStatsText(stats)),
-  );
-  db.close();
-}
-
-function parseScanArgs(args: string[]): {
-  path?: string;
-  format: "text" | "json";
-  failOn?: ScanSeverity;
-} {
-  let path: string | undefined;
-  let format: "text" | "json" = "text";
-  let failOn: ScanSeverity | undefined;
-  for (let i = 0; i < args.length; i++) {
-    const option = args[i];
-    if (option === "--format") {
-      const value = args[++i];
-      if (value !== "text" && value !== "json")
-        throw new Error("--format must be text or json");
-      format = value;
-    } 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;
-    } else if (option === "--json") {
-      // handled globally by main()'s isJson flag; recognized here so it isn't rejected
-    } else if (option?.startsWith("--")) {
-      throw new Error(`unknown scan option: ${option}`);
-    } else if (path !== undefined) {
-      throw new Error("skillmux scan accepts at most one <path> argument");
-    } else {
-      path = option;
-    }
-  }
-  return { path, format, failOn };
-}
-
-async function runScan(
-  args: string[],
-  options: { isJson: boolean },
-): Promise<void> {
-  const { path, format, failOn } = parseScanArgs(args);
-  const rootPath = path
-    ? expandHome(path)
-    : expandHome((await loadConfig()).vault_path);
-  const result = await scanPath(rootPath);
-  emitSuccess({ isJson: options.isJson }, result, () => {
-    console.log(
-      format === "json" ? renderScanJson(result) : renderScanText(result),
-    );
-  });
-  process.exitCode = scanExitCode(result.findings, failOn);
-}
-
-function parseInstallArgs(args: string[]): {
-  repo?: string;
-  force: boolean;
-  dryRun: boolean;
-  failOn?: ScanSeverity;
-  allowLocalSource: boolean;
-} {
-  let repo: string | undefined;
-  let force = false;
-  let dryRun = false;
-  let failOn: ScanSeverity | undefined;
-  let allowLocalSource = false;
-  for (let i = 0; i < args.length; i++) {
-    const option = args[i];
-    if (option === "--force") force = 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;
-    } else if (option === "--json" || option === "--verbose") {
-      // handled globally by main()'s isJson/isVerbose flags; recognized here so they aren't rejected
-    } else if (option?.startsWith("--")) {
-      throw new Error(`unknown install option: ${option}`);
-    } else if (repo !== undefined) {
-      throw new Error("skillmux install accepts at most one <repo> argument");
-    } else {
-      repo = option;
-    }
-  }
-  return { repo, force, dryRun, failOn, allowLocalSource };
-}
-
-async function runInstall(
-  args: string[],
-  options: { isJson: boolean },
-): Promise<void> {
-  const { repo, force, dryRun, failOn, allowLocalSource } = parseInstallArgs(args);
-  if (!repo) {
-    throw new Error(
-      "usage: skillmux install <repo>[/path] [--force] [--fail-on low|medium|high] [--dry-run] [--allow-local-source] [--json]",
-    );
-  }
-
-  const source = resolveRepoSource(repo);
-  if (!allowLocalSource && isLocalFileUrl(source.url)) {
-    throw new Error(
-      `"${repo}" is a local (file://) source — pass --allow-local-source to install from it`,
-    );
-  }
-  const config = await loadConfig();
-  assertHostAllowed(source.url, config.egress?.allowed_hosts);
-  const cloneDir = await cloneToTemp(source.url);
-  try {
-    const resolved = resolveSkillDir(
-      cloneDir,
-      deriveRepoName(source.url),
-      source.skillPath,
-    );
-    const { findings } = await validateSkillCandidate(
-      resolved.skillId,
-      resolved.dir,
-    );
-    if (!options.isJson) console.log(renderScanText({ scanned: 1, findings }));
-
-    if (scanExitCode(findings, failOn) !== 0) {
-      process.exitCode = 1;
-      console.error(
-        `aborting install: a finding met the --fail-on ${failOn} threshold`,
-      );
-      return;
-    }
-
-    const vaultPath = expandHome(config.vault_path);
-    if (dryRun) {
-      const plannedPath = join(vaultPath, resolved.skillId);
-      emitSuccess(
-        { isJson: options.isJson },
-        { skill_id: resolved.skillId, would_install_at: plannedPath },
-        () =>
-          console.log(
-            `dry-run: would install "${resolved.skillId}" into ${plannedPath}`,
-          ),
-      );
-      return;
-    }
-
-    const commit = resolveCloneCommit(cloneDir);
-    const targetDir = installIntoVault(
-      vaultPath,
-      resolved.skillId,
-      resolved.dir,
-      force,
-    );
-    writeSkillOrigin(targetDir, {
-      source_url: source.url,
-      skill_path: source.skillPath,
-      commit,
-      installed_at: new Date().toISOString(),
-      content_hash: hashSkillContent(targetDir),
-    });
-    emitSuccess(
-      { isJson: options.isJson },
-      { skill_id: resolved.skillId, installed_at: targetDir },
-      () => console.log(`installed "${resolved.skillId}" into ${targetDir}`),
-    );
-  } finally {
-    rmSync(cloneDir, { recursive: true, force: true });
-  }
-}
 
 if (import.meta.main) {
   await main();