@klhapp/skillmux 0.6.0 → 1.0.0

package/src/cli.ts

@@ -7,7 +7,12 @@ import { createInterface } from "node:readline/promises";
 import { generateDataset } from "./dataset-generator";
 
 import { createClients } from "./clients";
-import { expandHome, loadConfig, migrateLegacyPaths, resolveConfigPath } from "./config";
+import {
+  expandHome,
+  loadConfig,
+  migrateLegacyPaths,
+  resolveConfigPath,
+} from "./config";
 import { openIndex } from "./db";
 import { diagnose } from "./doctor";
 import { evalVault } from "./eval";
@@ -57,9 +62,20 @@ import {
 } from "./manifest";
 import { downloadLocalModels } from "./models";
 import { resolveProjectDirectory, suggestProjectName } from "./project-setup";
-import { parseCommaList, promptMultiSelect, promptText, shouldUseWizard } from "./prompts";
+import {
+  parseCommaList,
+  promptMultiSelect,
+  promptText,
+  shouldUseWizard,
+} from "./prompts";
 import { backfillEmbeddings, configure, rebuildIndex } from "./router-core";
-import { renderScanJson, renderScanText, scanExitCode, scanPath, type ScanSeverity } from "./scan";
+import {
+  renderScanJson,
+  renderScanText,
+  scanExitCode,
+  scanPath,
+  type ScanSeverity,
+} from "./scan";
 import {
   applyConfigInit,
   inspectVault,
@@ -87,7 +103,15 @@ import {
   type ResolvedTarget,
 } from "./context";
 import { createTargetAdapter, type TargetAdapter } from "./adapters";
-import { formatJsonEnvelope, isInteractive, mapExitCode, renderTable, renderTargetBanner, suggestCorrection } from "./output";
+import {
+  emitSuccess,
+  formatJsonEnvelope,
+  isInteractive,
+  mapExitCode,
+  renderTable,
+  renderTargetBanner,
+  suggestCorrection,
+} from "./output";
 import { generateCompletions, type ShellType } from "./completions";
 
 const KNOWN_COMMANDS = [
@@ -101,14 +125,14 @@ const KNOWN_COMMANDS = [
   "init",
   "project",
   "target",
+  "core",
   "report",
   "scan",
   "install",
   "eval",
   "doctor",
   "models",
-  "which",
-  "manifest",
+  "skill",
   "local-vault",
 ];
 
@@ -143,9 +167,17 @@ async function main() {
 
   // Only resolve target if command is target-aware or context/config/calibrate
   const isLocalConfigInit = command === "config" && rawArgv[1] === "init";
-  if ((["context", "config", "calibrate"].includes(command) && !isLocalConfigInit) || flagContext || flagServer) {
+  if (
+    (["context", "config", "calibrate"].includes(command) &&
+      !isLocalConfigInit) ||
+    flagContext ||
+    flagServer
+  ) {
     try {
-      resolvedTarget = await resolveTarget({ context: flagContext, server: flagServer });
+      resolvedTarget = await resolveTarget({
+        context: flagContext,
+        server: flagServer,
+      });
     } catch (err: any) {
       handleError(err, { target: resolvedTarget, isJson, isVerbose });
       return;
@@ -159,13 +191,23 @@ async function main() {
   try {
     switch (command) {
       case "context":
-        await handleContextCommand(subCommand, commandArgs, { target: resolvedTarget, isJson });
+        await handleContextCommand(subCommand, commandArgs, {
+          target: resolvedTarget,
+          isJson,
+        });
         break;
       case "config":
-        await handleConfigCommand(adapter, subCommand, commandArgs, { target: resolvedTarget, isJson, dryRun: isDryRun });
+        await handleConfigCommand(adapter, subCommand, commandArgs, {
+          target: resolvedTarget,
+          isJson,
+          dryRun: isDryRun,
+        });
         break;
       case "calibrate":
-        await handleCalibrateCommand(adapter, subCommand, rawArgv.slice(1), { target: resolvedTarget, isJson });
+        await handleCalibrateCommand(adapter, subCommand, rawArgv.slice(1), {
+          target: resolvedTarget,
+          isJson,
+        });
         break;
       case "completions":
         await handleCompletionsCommand(subCommand);
@@ -207,40 +249,50 @@ async function main() {
       case "target":
         await runTarget(subCommand, commandArgs, { isJson, dryRun: isDryRun });
         break;
+      case "core":
+        await runCore(subCommand, commandArgs, { isJson, dryRun: isDryRun });
+        break;
       case "report":
-        await runReport(rawArgv.slice(1));
+        await runReport(rawArgv.slice(1), { isJson });
         break;
       case "scan":
-        await runScan(rawArgv.slice(1));
+        await runScan(rawArgv.slice(1), { isJson });
         break;
       case "install":
-        await runInstall(rawArgv.slice(1));
+        await runInstall(rawArgv.slice(1), { isJson });
         break;
       case "eval":
-        await runEval();
+        await runEval({ isJson });
         break;
       case "doctor":
-        await runDoctor();
+        await runDoctor({ isJson });
         break;
       case "which":
-        await runWhich(rawArgv.slice(1));
+        throw new Error(
+          `skillmux which is removed - use "skillmux skill which ${subCommand || "<skill_id>"}" instead`,
+        );
+      case "skill":
+        await runSkill(subCommand, commandArgs);
         break;
       case "manifest":
-        await runManifest(subCommand, commandArgs);
-        break;
+        throw new Error(
+          `skillmux manifest is removed - use "skillmux core ${subCommand || "pin|unpin"}" for [core] skills, or "skillmux project ${subCommand || "pin|unpin"} <group>" for [project.*] skills`,
+        );
       case "local-vault":
-        if (subCommand !== "init") throw new Error("usage: skillmux local-vault init <path>");
-        await runLocalVaultInit(commandArgs);
+        if (subCommand !== "init")
+          throw new Error("usage: skillmux local-vault init <path>");
+        await runLocalVaultInit(commandArgs, { isJson, dryRun: isDryRun });
         break;
       case "models":
-        if (subCommand !== "download") throw new Error("usage: skillmux models download");
-        await runModelDownload();
+        if (subCommand !== "download")
+          throw new Error("usage: skillmux models download");
+        await runModelDownload({ isJson });
         break;
       default: {
         const suggestion = suggestCorrection(command, KNOWN_COMMANDS);
         const msg = suggestion
           ? `Unknown command "${command}". Did you mean "${suggestion}"?`
-          : `usage: skillmux <serve|index|sync|init|project|target|report|scan|install|eval|doctor|which|manifest pin/unpin|local-vault init|config show|models download|calibrate generate-dataset>`;
+          : `usage: skillmux <serve|index|sync|init|project|target|core pin/unpin|report|scan|install|eval|doctor|skill which|local-vault init|config show|models download|calibrate generate-dataset>`;
         throw new Error(msg);
       }
     }
@@ -252,13 +304,11 @@ async function main() {
 async function handleContextCommand(
   sub: string,
   args: string[],
-  ctx: { target: ResolvedTarget; isJson: boolean }
+  ctx: { target: ResolvedTarget; isJson: boolean },
 ) {
   if (sub === "list") {
     const contexts = await listContexts();
-    if (ctx.isJson) {
-      console.log(JSON.stringify(formatJsonEnvelope({ ok: true, target: ctx.target, data: contexts })));
-    } else {
+    emitSuccess({ isJson: ctx.isJson, target: ctx.target }, contexts, () => {
       renderTargetBanner(ctx.target);
       renderTable(
         [
@@ -267,20 +317,22 @@ async function handleContextCommand(
           { key: "token_env", header: "TOKEN_ENV" },
           { key: "isDefault", header: "DEFAULT" },
         ],
-        contexts.map((c) => ({ ...c, token_env: c.token_env ?? "-", isDefault: c.isDefault ? "*" : "" }))
+        contexts.map((c) => ({
+          ...c,
+          token_env: c.token_env ?? "-",
+          isDefault: c.isDefault ? "*" : "",
+        })),
       );
-    }
+    });
     return;
   }
 
   if (sub === "current") {
     const current = await getCurrentContext();
-    if (ctx.isJson) {
-      console.log(JSON.stringify(formatJsonEnvelope({ ok: true, target: ctx.target, data: current })));
-    } else {
+    emitSuccess({ isJson: ctx.isJson, target: ctx.target }, current, () => {
       renderTargetBanner(ctx.target);
       console.log(`Current context: ${current.name} (${current.server})`);
-    }
+    });
     return;
   }
 
@@ -293,14 +345,18 @@ async function handleContextCommand(
       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>]");
+      throw new Error(
+        "usage: skillmux context add <name> --server <url> [--token-env <env_name>]",
+      );
     }
     await addContext(name, { server, token_env: tokenEnv });
-    if (ctx.isJson) {
-      console.log(JSON.stringify(formatJsonEnvelope({ ok: true, target: ctx.target, data: { name, server, token_env: tokenEnv } })));
-    } else {
-      console.log(`Added context "${name}" -> ${server}`);
-    }
+    emitSuccess(
+      { isJson: ctx.isJson, target: ctx.target },
+      { name, server, token_env: tokenEnv },
+      () => {
+        console.log(`Added context "${name}" -> ${server}`);
+      },
+    );
     return;
   }
 
@@ -308,11 +364,13 @@ async function handleContextCommand(
     const name = args[0];
     if (!name) throw new Error("usage: skillmux context use <name>");
     await useContext(name);
-    if (ctx.isJson) {
-      console.log(JSON.stringify(formatJsonEnvelope({ ok: true, target: ctx.target, data: { default_context: name } })));
-    } else {
-      console.log(`Switched default context to "${name}"`);
-    }
+    emitSuccess(
+      { isJson: ctx.isJson, target: ctx.target },
+      { default_context: name },
+      () => {
+        console.log(`Switched default context to "${name}"`);
+      },
+    );
     return;
   }
 
@@ -320,22 +378,56 @@ async function handleContextCommand(
     const name = args[0];
     if (!name) throw new Error("usage: skillmux context remove <name>");
     await removeContext(name);
-    if (ctx.isJson) {
-      console.log(JSON.stringify(formatJsonEnvelope({ ok: true, target: ctx.target, data: { removed: name } })));
-    } else {
-      console.log(`Removed context "${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>");
 }
 
+function emitConfigInitOutcome(
+  ctx: { isJson: boolean },
+  opts: {
+    phase: "plan" | "result";
+    dryRun: boolean;
+    applied: boolean;
+    plan: ConfigInitPlan;
+    action: "create" | "preserve";
+    text: string;
+  },
+): void {
+  if (ctx.isJson) {
+    console.log(
+      JSON.stringify({
+        schema_version: 1,
+        ok: true,
+        command: "config init",
+        phase: opts.phase,
+        dry_run: opts.dryRun,
+        applied: opts.applied,
+        plan: {
+          config_path: opts.plan.configPath,
+          vault_path: opts.plan.vaultPath,
+          action: opts.action,
+        },
+      }),
+    );
+    return;
+  }
+  console.log(opts.text);
+}
+
 async function handleConfigCommand(
   adapter: TargetAdapter,
   sub: string,
   args: string[],
-  ctx: { target: ResolvedTarget; isJson: boolean; dryRun: boolean }
+  ctx: { target: ResolvedTarget; isJson: boolean; dryRun: boolean },
 ) {
   if (sub === "init") {
     let vaultPath: string | undefined;
@@ -344,7 +436,8 @@ async function handleConfigCommand(
       const option = args[i];
       if (option === "--vault") {
         vaultPath = args[++i];
-        if (!vaultPath) throw new Error("usage: skillmux config init --vault <path> --yes");
+        if (!vaultPath)
+          throw new Error("usage: skillmux config init --vault <path> --yes");
       } else if (option === "--yes") {
         yes = true;
       } else if (option === "--dry-run" || option === "--json") {
@@ -364,69 +457,65 @@ async function handleConfigCommand(
     migrateLegacyPaths();
     const plan = planConfigInit(resolveConfigPath(), expandHome(vaultPath));
     if (plan.action === "preserve") {
-      console.log(ctx.isJson
-        ? JSON.stringify({
-            schema_version: 1,
-            ok: true,
-            command: "config init",
-            phase: "result",
-            dry_run: ctx.dryRun,
-            applied: false,
-            plan: { config_path: plan.configPath, vault_path: plan.vaultPath, action: "preserve" },
-          })
-        : `preserved existing config: ${plan.configPath}`);
+      emitConfigInitOutcome(ctx, {
+        phase: "result",
+        dryRun: ctx.dryRun,
+        applied: false,
+        plan,
+        action: "preserve",
+        text: `preserved existing config: ${plan.configPath}`,
+      });
       return;
     }
     if (ctx.dryRun) {
-      console.log(ctx.isJson
-        ? JSON.stringify({
-            schema_version: 1,
-            ok: true,
-            command: "config init",
-            phase: "plan",
-            dry_run: true,
-            applied: false,
-            plan: { config_path: plan.configPath, vault_path: plan.vaultPath, action: "create" },
-          })
-        : `config create: ${plan.configPath} (dry-run)`);
+      emitConfigInitOutcome(ctx, {
+        phase: "plan",
+        dryRun: true,
+        applied: false,
+        plan,
+        action: "create",
+        text: `config create: ${plan.configPath} (dry-run)`,
+      });
       return;
     }
     if (!yes) {
       if (!ctx.isJson && isInteractive()) {
-        if (!(await confirmAction(`Create ${plan.configPath} with vault_path ${plan.vaultPath}?`))) {
+        if (
+          !(await confirmAction(
+            `Create ${plan.configPath} with vault_path ${plan.vaultPath}?`,
+          ))
+        ) {
           console.log("config init cancelled; nothing written");
           return;
         }
       } else {
-        throw new Error("config initialization requires --yes in noninteractive mode");
+        throw new Error(
+          "config initialization requires --yes in noninteractive mode",
+        );
       }
     }
 
     const result = applyConfigInit(plan);
-    console.log(ctx.isJson
-      ? JSON.stringify({
-          schema_version: 1,
-          ok: true,
-          command: "config init",
-          phase: "result",
-          dry_run: false,
-          applied: result === "created",
-          plan: { config_path: plan.configPath, vault_path: plan.vaultPath, action: plan.action },
-        })
-      : result === "created"
-        ? `created ${plan.configPath}`
-        : `preserved existing config: ${plan.configPath}`);
+    emitConfigInitOutcome(ctx, {
+      phase: "result",
+      dryRun: false,
+      applied: result === "created",
+      plan,
+      action: plan.action,
+      text:
+        result === "created"
+          ? `created ${plan.configPath}`
+          : `preserved existing config: ${plan.configPath}`,
+    });
     return;
   }
 
   if (sub === "show") {
     const data = await adapter.getConfigShow();
-    if (ctx.isJson) {
-      console.log(JSON.stringify(formatJsonEnvelope({ ok: true, target: ctx.target, data })));
-    } else {
+    emitSuccess({ isJson: ctx.isJson, target: ctx.target }, data, () => {
       renderTargetBanner(ctx.target);
       console.log(JSON.stringify(data.effective, null, 2));
-    }
+    });
     return;
   }
 
@@ -434,32 +523,34 @@ async function handleConfigCommand(
     const key = args[0];
     if (!key) throw new Error("usage: skillmux config get <key>");
     const val = await adapter.getConfigGet(key);
-    if (ctx.isJson) {
-      console.log(JSON.stringify(formatJsonEnvelope({ ok: true, target: ctx.target, data: { key, value: val } })));
-    } else {
-      console.log(typeof val === "object" ? JSON.stringify(val) : String(val));
-    }
+    emitSuccess(
+      { isJson: ctx.isJson, target: ctx.target },
+      { key, value: val },
+      () => {
+        console.log(
+          typeof val === "object" ? JSON.stringify(val) : String(val),
+        );
+      },
+    );
     return;
   }
 
   if (sub === "validate") {
     const res = await adapter.configValidate();
-    if (ctx.isJson) {
-      console.log(JSON.stringify(formatJsonEnvelope({ ok: true, target: ctx.target, data: res })));
-    } else {
-      console.log(res.valid ? "Configuration is valid." : "Configuration is invalid.");
-    }
+    emitSuccess({ isJson: ctx.isJson, target: ctx.target }, res, () => {
+      console.log(
+        res.valid ? "Configuration is valid." : "Configuration is invalid.",
+      );
+    });
     return;
   }
 
   if (sub === "diff") {
     const res = await adapter.configDiff();
-    if (ctx.isJson) {
-      console.log(JSON.stringify(formatJsonEnvelope({ ok: true, target: ctx.target, data: res })));
-    } else {
+    emitSuccess({ isJson: ctx.isJson, target: ctx.target }, res, () => {
       renderTargetBanner(ctx.target);
       console.log(JSON.stringify(res.diff, null, 2));
-    }
+    });
     return;
   }
 
@@ -470,27 +561,27 @@ async function handleConfigCommand(
       throw new Error("usage: skillmux config set <key> <value> [--dry-run]");
     }
     const res = await adapter.configSet(key, value, { dryRun: ctx.dryRun });
-    if (ctx.isJson) {
-      console.log(JSON.stringify(formatJsonEnvelope({ ok: true, target: ctx.target, data: res })));
-    } else {
+    emitSuccess({ isJson: ctx.isJson, target: ctx.target }, res, () => {
       renderTargetBanner(ctx.target);
       const prefix = ctx.dryRun ? "[dry-run] " : "";
-      console.log(`${prefix}${key}: ${JSON.stringify(res.prior_val)} -> ${JSON.stringify(res.resulting_val)}`);
-      console.log(`Persistence: ${res.persistence}, Application: ${res.application}`);
-    }
+      console.log(
+        `${prefix}${key}: ${JSON.stringify(res.prior_val)} -> ${JSON.stringify(res.resulting_val)}`,
+      );
+      console.log(
+        `Persistence: ${res.persistence}, Application: ${res.application}`,
+      );
+    });
     return;
   }
 
   if (sub === "status") {
     const res = await adapter.configStatus();
-    if (ctx.isJson) {
-      console.log(JSON.stringify(formatJsonEnvelope({ ok: true, target: ctx.target, data: res })));
-    } else {
+    emitSuccess({ isJson: ctx.isJson, target: ctx.target }, res, () => {
       renderTargetBanner(ctx.target);
       console.log(`Runtime: ${res.runtime}`);
       console.log(`Active revision: ${res.active_revision}`);
       console.log(`Readiness: ${res.readiness.status}`);
-    }
+    });
     return;
   }
 
@@ -498,9 +589,14 @@ async function handleConfigCommand(
 }
 
 async function confirmAction(prompt: string): Promise<boolean> {
-  const readline = createInterface({ input: process.stdin, output: process.stdout });
+  const readline = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
   try {
-    const answer = (await readline.question(`${prompt} [y/N] `)).trim().toLowerCase();
+    const answer = (await readline.question(`${prompt} [y/N] `))
+      .trim()
+      .toLowerCase();
     return answer === "y" || answer === "yes";
   } finally {
     readline.close();
@@ -511,7 +607,7 @@ async function handleCalibrateCommand(
   adapter: TargetAdapter,
   sub: string,
   args: string[],
-  ctx: { target: ResolvedTarget; isJson: boolean }
+  ctx: { target: ResolvedTarget; isJson: boolean },
 ) {
   if (sub === "run") {
     let datasetPath: string | undefined;
@@ -519,21 +615,17 @@ async function handleCalibrateCommand(
       if (args[i] === "--dataset") datasetPath = args[++i];
     }
     const res = await adapter.calibrateRun({ datasetPath });
-    if (ctx.isJson) {
-      console.log(JSON.stringify(formatJsonEnvelope({ ok: true, target: ctx.target, data: res })));
-    } else {
+    emitSuccess({ isJson: ctx.isJson, target: ctx.target }, res, () => {
       renderTargetBanner(ctx.target);
       console.log(`Calibration run complete.`);
       if (res.result) console.log(JSON.stringify(res.result, null, 2));
-    }
+    });
     return;
   }
 
   if (sub === "list") {
     const res = await adapter.calibrateList();
-    if (ctx.isJson) {
-      console.log(JSON.stringify(formatJsonEnvelope({ ok: true, target: ctx.target, data: res })));
-    } else {
+    emitSuccess({ isJson: ctx.isJson, target: ctx.target }, res, () => {
       renderTargetBanner(ctx.target);
       renderTable(
         [
@@ -541,9 +633,9 @@ async function handleCalibrateCommand(
           { key: "created_at", header: "CREATED_AT" },
           { key: "status", header: "STATUS" },
         ],
-        res
+        res,
       );
-    }
+    });
     return;
   }
 
@@ -551,12 +643,10 @@ async function handleCalibrateCommand(
     const runId = args[1];
     if (!runId) throw new Error("usage: skillmux calibrate show <run_id>");
     const res = await adapter.calibrateShow(runId);
-    if (ctx.isJson) {
-      console.log(JSON.stringify(formatJsonEnvelope({ ok: true, target: ctx.target, data: res })));
-    } else {
+    emitSuccess({ isJson: ctx.isJson, target: ctx.target }, res, () => {
       renderTargetBanner(ctx.target);
       console.log(JSON.stringify(res, null, 2));
-    }
+    });
     return;
   }
 
@@ -564,12 +654,10 @@ async function handleCalibrateCommand(
     const runId = args[1];
     if (!runId) throw new Error("usage: skillmux calibrate apply <run_id>");
     const res = await adapter.calibrateApply(runId);
-    if (ctx.isJson) {
-      console.log(JSON.stringify(formatJsonEnvelope({ ok: true, target: ctx.target, data: res })));
-    } else {
+    emitSuccess({ isJson: ctx.isJson, target: ctx.target }, res, () => {
       renderTargetBanner(ctx.target);
       console.log(`Applied calibration run "${runId}"`);
-    }
+    });
     return;
   }
 
@@ -578,7 +666,9 @@ async function handleCalibrateCommand(
     return;
   }
 
-  throw new Error("usage: skillmux calibrate generate-dataset [--vault <path>] [--out <file>]");
+  throw new Error(
+    "usage: skillmux calibrate generate-dataset [--vault <path>] [--out <file>]",
+  );
 }
 
 async function handleCompletionsCommand(shell: string) {
@@ -590,7 +680,7 @@ async function handleCompletionsCommand(shell: string) {
 
 function handleError(
   err: any,
-  opts: { target: ResolvedTarget; isJson: boolean; isVerbose: boolean }
+  opts: { target: ResolvedTarget; isJson: boolean; isVerbose: boolean },
 ) {
   const code = mapExitCode(err);
   process.exitCode = code;
@@ -605,7 +695,13 @@ function handleError(
     });
     console.log(JSON.stringify(env));
   } else {
-    console.error(msg.startsWith("usage:") || msg.startsWith("Unknown") || msg.startsWith("error:") ? msg : `error: ${msg}`);
+    console.error(
+      msg.startsWith("usage:") ||
+        msg.startsWith("Unknown") ||
+        msg.startsWith("error:")
+        ? msg
+        : `error: ${msg}`,
+    );
     if (opts.isVerbose && err instanceof Error && err.stack) {
       console.error(err.stack);
     }
@@ -617,7 +713,7 @@ function printHelp(): void {
 
 Setup:
   skillmux config init --vault <path> --yes
-  skillmux init [--client <name>...] [--target <name>...] [--path <dir>]
+  skillmux init [--client <name>...] [--target <name>...] [--dir <dir>]
                 [--vault <path>] [--core <skill_id>...]
                 [--migrate-full-vault] [--no-instructions] [--no-sync]
                 [--interactive|--yes|--dry-run] [--json]
@@ -626,6 +722,8 @@ Setup:
                 [--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,
@@ -635,8 +733,8 @@ Init targets:
   agent-skills, claude-code, codex, custom
 
 Commands:
-  serve, index, sync, init, project, target, report, scan, install, eval, doctor, which,
-  manifest, local-vault, config, models, calibrate, context, completions`);
+  serve, index, sync, init, project, target, core, report, scan, install, eval, doctor, skill,
+  local-vault, config, models, calibrate, context, completions`);
 }
 
 // ---------------------------------------------------------------------------
@@ -645,7 +743,10 @@ Commands:
 
 type Transport = "stdio" | "http";
 
-function parseServeArgs(args: string[]): { transport: Transport; port?: number } {
+function parseServeArgs(args: string[]): {
+  transport: Transport;
+  port?: number;
+} {
   let transport: Transport = "stdio";
   let port: number | undefined;
   for (let i = 0; i < args.length; i++) {
@@ -675,7 +776,9 @@ 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}`);
+    console.error(
+      `warning: keeping previous index entry for ${skillId}: ${error}`,
+    );
   });
   const retainedNote =
     report.retained.length > 0
@@ -687,43 +790,56 @@ async function runIndex(): Promise<void> {
     const backfilled = await backfillEmbeddings();
     console.log(`embeddings: ${backfilled} backfilled`);
   } catch {
-    console.log("embeddings: skipped (endpoint unreachable; lexical-only recall until next index)");
+    console.log(
+      "embeddings: skipped (endpoint unreachable; lexical-only recall until next index)",
+    );
   }
 }
 
-async function runEval(): Promise<void> {
+async function runEval(options: { isJson: boolean }): 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)}`);
   });
-  console.log(`holdout queries: ${report.queries}`);
-  console.log(`lexical recall@3: ${report.lexical.recall_at_3.toFixed(3)}`);
-  console.log(`lexical recall@5: ${report.lexical.recall_at_5.toFixed(3)}`);
-  console.log(`lexical MRR:      ${report.lexical.mrr.toFixed(3)}`);
-  console.log(`hybrid recall@3:  ${report.hybrid.recall_at_3.toFixed(3)}`);
-  console.log(`hybrid recall@5:  ${report.hybrid.recall_at_5.toFixed(3)}`);
-  console.log(`hybrid MRR:       ${report.hybrid.mrr.toFixed(3)}`);
+  emitSuccess({ isJson: options.isJson }, report, () => {
+    console.log(`holdout queries: ${report.queries}`);
+    console.log(`lexical recall@3: ${report.lexical.recall_at_3.toFixed(3)}`);
+    console.log(`lexical recall@5: ${report.lexical.recall_at_5.toFixed(3)}`);
+    console.log(`lexical MRR:      ${report.lexical.mrr.toFixed(3)}`);
+    console.log(`hybrid recall@3:  ${report.hybrid.recall_at_3.toFixed(3)}`);
+    console.log(`hybrid recall@5:  ${report.hybrid.recall_at_5.toFixed(3)}`);
+    console.log(`hybrid MRR:       ${report.hybrid.mrr.toFixed(3)}`);
+  });
 }
 
-async function runDoctor(): Promise<void> {
+async function runDoctor(options: { isJson: boolean }): Promise<void> {
   const report = await diagnose(await loadConfig());
-  console.log(`inference mode: ${report.mode}`);
-  console.log(`routing capability: ${report.capability}`);
-  for (const check of report.checks)
-    console.log(`${check.ok ? "ok" : "fail"}: ${check.name} - ${check.detail}`);
+  emitSuccess({ isJson: options.isJson }, report, () => {
+    console.log(`inference mode: ${report.mode}`);
+    console.log(`routing capability: ${report.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 which <skill_id>");
+  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")),
+  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`);
@@ -731,10 +847,10 @@ async function runWhich(args: string[]): Promise<void> {
     return;
   }
   console.log(`${skillId}: serving from ${roots[0]}`);
-  for (const shadowedRoot of roots.slice(1)) console.log(`  shadows: ${shadowedRoot}`);
+  for (const shadowedRoot of roots.slice(1))
+    console.log(`  shadows: ${shadowedRoot}`);
 }
 
-const MANIFEST_USAGE = "usage: skillmux manifest <pin|unpin> <skill_id> (--core | --project <group> [--path <path>...])";
 const PROJECT_INIT_USAGE =
   "usage: skillmux project init [path] [--name <group>] [--skill <id>...] [--client <id>...] [--target <name>...] [--yes] [--no-sync]";
 
@@ -802,7 +918,11 @@ function parseProjectInitArgs(args: string[]): ProjectInitArgs {
       yes = true;
     } else if (arg === "--no-sync") {
       sync = false;
-    } else if (arg === "--dry-run" || arg === "--json" || arg === "--interactive") {
+    } else if (
+      arg === "--dry-run" ||
+      arg === "--json" ||
+      arg === "--interactive"
+    ) {
       continue;
     } else if (arg.startsWith("-")) {
       throw new Error(`unknown project init option: ${arg}`);
@@ -813,8 +933,44 @@ function parseProjectInitArgs(args: string[]): ProjectInitArgs {
     }
   }
 
-  const path = resolveProjectDirectory(projectPath ? expandHome(projectPath) : undefined);
-  return { path, name: name ?? suggestProjectName(basename(path)), skills, clients, targets, yes, sync };
+  const path = resolveProjectDirectory(
+    projectPath ? expandHome(projectPath) : undefined,
+  );
+  return {
+    path,
+    name: name ?? suggestProjectName(basename(path)),
+    skills,
+    clients,
+    targets,
+    yes,
+    sync,
+  };
+}
+
+async function loadManifestContext() {
+  const config = await loadConfig();
+  const vaultPath = expandHome(config.vault_path);
+  const manifestPath = resolveManifestPath(vaultPath);
+  if (!manifestPath) {
+    throw new Error(
+      `no skillmux.toml found at ${vaultPath}; run skillmux init first`,
+    );
+  }
+  const manifest = parseManifest(await Bun.file(manifestPath).text());
+  return { config, vaultPath, manifestPath, manifest };
+}
+
+async function confirmIfNeeded(opts: {
+  confirmed: boolean;
+  isJson: boolean;
+  prompt: string;
+  nonInteractiveError: string;
+}): Promise<boolean> {
+  if (opts.confirmed) return true;
+  if (opts.isJson || !isInteractive()) {
+    throw new Error(opts.nonInteractiveError);
+  }
+  return confirmAction(opts.prompt);
 }
 
 async function runProject(
@@ -823,14 +979,11 @@ async function runProject(
   options: { isJson: boolean; dryRun: boolean },
 ): Promise<void> {
   if (subCommand === "list" || subCommand === "show") {
-    const config = await loadConfig();
-    const vaultPath = expandHome(config.vault_path);
-    const manifestPath = resolveManifestPath(vaultPath);
-    if (!manifestPath) throw new Error(`no skillmux.toml found at ${vaultPath}; run skillmux init first`);
-    const manifest = parseManifest(await Bun.file(manifestPath).text());
-    const names = subCommand === "show"
-      ? [args[0] ?? ""]
-      : Object.keys(manifest.project ?? {});
+    const { manifest } = await loadManifestContext();
+    const names =
+      subCommand === "show"
+        ? [args[0] ?? ""]
+        : Object.keys(manifest.project ?? {});
     if (subCommand === "show" && !manifest.project?.[names[0]!]) {
       throw new Error(`[project.${names[0]}] does not exist`);
     }
@@ -858,33 +1011,43 @@ async function runProject(
   }
   if (subCommand === "add-path" || subCommand === "remove-path") {
     const group = args[0];
-    if (!group) throw new Error(`usage: skillmux project ${subCommand} <group> [path] --yes`);
+    if (!group)
+      throw new Error(
+        `usage: skillmux project ${subCommand} <group> [path] --yes`,
+      );
     const rawPath = args[1]?.startsWith("-") ? undefined : args[1];
-    const projectPath = resolveProjectDirectory(rawPath ? expandHome(rawPath) : undefined);
+    const projectPath = resolveProjectDirectory(
+      rawPath ? expandHome(rawPath) : undefined,
+    );
     const yes = args.includes("--yes");
     if (!existsSync(projectPath) || !lstatSync(projectPath).isDirectory()) {
       throw new Error(`project path is not a directory: ${projectPath}`);
     }
-    const config = await loadConfig();
-    const vaultPath = expandHome(config.vault_path);
-    const manifestPath = resolveManifestPath(vaultPath);
-    if (!manifestPath) throw new Error(`no skillmux.toml found at ${vaultPath}; run skillmux init first`);
-    const manifest = parseManifest(await Bun.file(manifestPath).text());
+    const { config, vaultPath, manifestPath, manifest } =
+      await loadManifestContext();
     const updated = updateProjectPaths(manifest, group, {
-      ...(subCommand === "add-path" ? { add: [projectPath] } : { remove: [projectPath] }),
+      ...(subCommand === "add-path"
+        ? { add: [projectPath] }
+        : { remove: [projectPath] }),
     });
-    validateManifest(updated, vaultPath, config.local_vault_paths.map(expandHome));
+    validateManifest(
+      updated,
+      vaultPath,
+      config.local_vault_paths.map(expandHome),
+    );
     if (options.dryRun) {
       console.log(`${subCommand}: [project.${group}] ${projectPath} (dry-run)`);
       return;
     }
-    if (!yes) {
-      if (!options.isJson && isInteractive()) {
-        if (!(await confirmAction(`${subCommand} ${projectPath} in [project.${group}]?`))) return;
-      } else {
-        throw new Error(`skillmux project ${subCommand} requires --yes when run non-interactively`);
-      }
-    }
+    if (
+      !(await confirmIfNeeded({
+        confirmed: yes,
+        isJson: options.isJson,
+        prompt: `${subCommand} ${projectPath} in [project.${group}]?`,
+        nonInteractiveError: `skillmux project ${subCommand} requires --yes when run non-interactively`,
+      }))
+    )
+      return;
     writeManifestAtomic(manifestPath, updated);
     console.log(`${subCommand}: [project.${group}] ${projectPath}`);
     return;
@@ -893,38 +1056,50 @@ async function runProject(
     const group = args[0];
     const skills = args.slice(1).filter((arg) => !arg.startsWith("-"));
     if (!group || skills.length === 0) {
-      throw new Error(`usage: skillmux project ${subCommand} <group> <skill_id>... --yes`);
+      throw new Error(
+        `usage: skillmux project ${subCommand} <group> <skill_id>... --yes`,
+      );
     }
     const yes = args.includes("--yes");
-    const config = await loadConfig();
-    const vaultPath = expandHome(config.vault_path);
-    const manifestPath = resolveManifestPath(vaultPath);
-    if (!manifestPath) throw new Error(`no skillmux.toml found at ${vaultPath}; run skillmux init first`);
-    let updated = parseManifest(await Bun.file(manifestPath).text());
+    const { config, vaultPath, manifestPath, manifest } =
+      await loadManifestContext();
+    let updated = manifest;
     for (const skill of skills) {
-      updated = subCommand === "pin"
-        ? pinProject(updated, skill, group)
-        : unpinProject(updated, skill, group);
+      updated =
+        subCommand === "pin"
+          ? pinProject(updated, skill, group)
+          : unpinProject(updated, skill, group);
     }
-    validateManifest(updated, vaultPath, config.local_vault_paths.map(expandHome));
+    validateManifest(
+      updated,
+      vaultPath,
+      config.local_vault_paths.map(expandHome),
+    );
     if (options.dryRun) {
-      console.log(`${subCommand}: [project.${group}] ${skills.join(", ")} (dry-run)`);
+      console.log(
+        `${subCommand}: [project.${group}] ${skills.join(", ")} (dry-run)`,
+      );
       return;
     }
-    if (!yes) {
-      if (!options.isJson && isInteractive()) {
-        if (!(await confirmAction(`${subCommand} ${skills.join(", ")} in [project.${group}]?`))) return;
-      } else {
-        throw new Error(`skillmux project ${subCommand} requires --yes when run non-interactively`);
-      }
-    }
+    if (
+      !(await confirmIfNeeded({
+        confirmed: yes,
+        isJson: options.isJson,
+        prompt: `${subCommand} ${skills.join(", ")} in [project.${group}]?`,
+        nonInteractiveError: `skillmux project ${subCommand} requires --yes when run non-interactively`,
+      }))
+    )
+      return;
     writeManifestAtomic(manifestPath, updated);
     console.log(`${subCommand}: [project.${group}] ${skills.join(", ")}`);
     return;
   }
   if (subCommand === "attach" || subCommand === "detach") {
     const group = args[0];
-    if (!group) throw new Error(`usage: skillmux project ${subCommand} <group> (--client <id>... | --target <name>...) --yes`);
+    if (!group)
+      throw new Error(
+        `usage: skillmux project ${subCommand} <group> (--client <id>... | --target <name>...) --yes`,
+      );
     const clients: string[] = [];
     const requestedTargets: string[] = [];
     for (let i = 1; i < args.length; i++) {
@@ -936,15 +1111,16 @@ async function runProject(
         const value = args[++i];
         if (!value) throw new Error("--target requires a name");
         requestedTargets.push(value);
-      } else if (args[i] !== "--yes" && args[i] !== "--dry-run" && args[i] !== "--json") {
+      } else if (
+        args[i] !== "--yes" &&
+        args[i] !== "--dry-run" &&
+        args[i] !== "--json"
+      ) {
         throw new Error(`unknown project ${subCommand} option: ${args[i]}`);
       }
     }
-    const config = await loadConfig();
-    const vaultPath = expandHome(config.vault_path);
-    const manifestPath = resolveManifestPath(vaultPath);
-    if (!manifestPath) throw new Error(`no skillmux.toml found at ${vaultPath}; run skillmux init first`);
-    const manifest = parseManifest(await Bun.file(manifestPath).text());
+    const { config, vaultPath, manifestPath, manifest } =
+      await loadManifestContext();
     const clientTargets = configuredTargetsForClients(manifest, clients);
     const targets = [...new Set([...requestedTargets, ...clientTargets])];
     if (targets.length === 0) {
@@ -953,18 +1129,26 @@ async function runProject(
     const updated = updateProjectTargets(manifest, group, {
       ...(subCommand === "attach" ? { attach: targets } : { detach: targets }),
     });
-    validateManifest(updated, vaultPath, config.local_vault_paths.map(expandHome));
+    validateManifest(
+      updated,
+      vaultPath,
+      config.local_vault_paths.map(expandHome),
+    );
     if (options.dryRun) {
-      console.log(`${subCommand}: [project.${group}] ${targets.join(", ")} (dry-run)`);
+      console.log(
+        `${subCommand}: [project.${group}] ${targets.join(", ")} (dry-run)`,
+      );
       return;
     }
-    if (!args.includes("--yes")) {
-      if (!options.isJson && isInteractive()) {
-        if (!(await confirmAction(`${subCommand} [project.${group}] to ${targets.join(", ")}?`))) return;
-      } else {
-        throw new Error(`skillmux project ${subCommand} requires --yes when run non-interactively`);
-      }
-    }
+    if (
+      !(await confirmIfNeeded({
+        confirmed: args.includes("--yes"),
+        isJson: options.isJson,
+        prompt: `${subCommand} [project.${group}] to ${targets.join(", ")}?`,
+        nonInteractiveError: `skillmux project ${subCommand} requires --yes when run non-interactively`,
+      }))
+    )
+      return;
     writeManifestAtomic(manifestPath, updated);
     console.log(`${subCommand}: [project.${group}] ${targets.join(", ")}`);
     return;
@@ -976,33 +1160,38 @@ async function runProject(
     json: options.isJson,
     dryRun: options.dryRun,
   });
-  if (!existsSync(request.path)) throw new Error(`project path does not exist: ${request.path}`);
+  if (!existsSync(request.path))
+    throw new Error(`project path does not exist: ${request.path}`);
   if (!lstatSync(request.path).isDirectory()) {
     throw new Error(`project path is not a directory: ${request.path}`);
   }
 
-  const config = await loadConfig();
-  const vaultPath = expandHome(config.vault_path);
+  const { config, vaultPath, manifestPath, manifest } =
+    await loadManifestContext();
   const localVaultPaths = config.local_vault_paths.map(expandHome);
-  const manifestPath = resolveManifestPath(vaultPath);
-  if (!manifestPath) throw new Error(`no skillmux.toml found at ${vaultPath}; run skillmux init first`);
-  const manifest = parseManifest(await Bun.file(manifestPath).text());
   if (guided) {
     const name = await promptText("Project group", request.name);
     const availableClients = SUPPORTED_CLIENT_IDS.filter((client) => {
       const surface = planClientSurfaces([client]).surfaces[0];
-      return surface !== undefined && configuredTargetForSurface(manifest, surface) !== undefined;
+      return (
+        surface !== undefined &&
+        configuredTargetForSurface(manifest, surface) !== undefined
+      );
     });
     const clients = await promptMultiSelect(
       "Which clients should receive project skills?",
       availableClients.map((client) => ({
         value: client,
         label: client,
-        selected: request.clients.length === 0 || request.clients.includes(client),
+        selected:
+          request.clients.length === 0 || request.clients.includes(client),
       })),
     );
     const skills = parseCommaList(
-      await promptText("Project skill IDs, comma-separated", request.skills.join(",")),
+      await promptText(
+        "Project skill IDs, comma-separated",
+        request.skills.join(","),
+      ),
     );
     request = { ...request, name, clients, skills };
   }
@@ -1027,7 +1216,11 @@ async function runProject(
   };
 
   if (options.dryRun) {
-    console.log(options.isJson ? JSON.stringify({ schema_version: 1, plan }) : `project plan: ${JSON.stringify(plan)}`);
+    console.log(
+      options.isJson
+        ? JSON.stringify({ schema_version: 1, plan })
+        : `project plan: ${JSON.stringify(plan)}`,
+    );
     return;
   }
   if (!request.yes) {
@@ -1040,12 +1233,18 @@ async function runProject(
         console.log(`  skills: ${request.skills.join(", ") || "(none)"}`);
         console.log(`  sync: ${request.sync ? "yes" : "no"}`);
       }
-      if (!(await confirmAction(`Apply project setup for ${request.name} at ${request.path}?`))) {
+      if (
+        !(await confirmAction(
+          `Apply project setup for ${request.name} at ${request.path}?`,
+        ))
+      ) {
         console.log("project setup cancelled");
         return;
       }
     } else {
-      throw new Error("skillmux project init requires --yes when run non-interactively");
+      throw new Error(
+        "skillmux project init requires --yes when run non-interactively",
+      );
     }
   }
 
@@ -1068,19 +1267,65 @@ async function runProject(
   }
 }
 
+async function runCore(
+  subCommand: string,
+  args: string[],
+  options: { isJson: boolean; dryRun: boolean },
+): Promise<void> {
+  if (subCommand !== "pin" && subCommand !== "unpin") {
+    throw new Error("usage: skillmux core <pin|unpin>");
+  }
+  const skillIds = args.filter((arg) => !arg.startsWith("-"));
+  if (skillIds.length === 0) {
+    throw new Error(`usage: skillmux core ${subCommand} <skill_id>... --yes`);
+  }
+  const yes = args.includes("--yes");
+  const { config, vaultPath, manifestPath, manifest } =
+    await loadManifestContext();
+  let updated = manifest;
+  for (const skillId of skillIds) {
+    updated =
+      subCommand === "pin"
+        ? pinCore(updated, skillId)
+        : unpinCore(updated, skillId);
+  }
+  validateManifest(
+    updated,
+    vaultPath,
+    config.local_vault_paths.map(expandHome),
+  );
+  if (options.dryRun) {
+    emitSuccess(
+      { isJson: options.isJson },
+      { subcommand: subCommand, skill_ids: skillIds },
+      () =>
+        console.log(`${subCommand}: [core] ${skillIds.join(", ")} (dry-run)`),
+    );
+    return;
+  }
+  if (
+    !(await confirmIfNeeded({
+      confirmed: yes,
+      isJson: options.isJson,
+      prompt: `${subCommand} ${skillIds.join(", ")} in [core]?`,
+      nonInteractiveError: `skillmux core ${subCommand} requires --yes when run non-interactively`,
+    }))
+  )
+    return;
+  writeManifestAtomic(manifestPath, updated);
+  console.log(`${subCommand}: [core] ${skillIds.join(", ")}`);
+}
+
 async function runTarget(
   subCommand: string,
   args: string[],
   options: { isJson: boolean; dryRun: boolean },
 ): Promise<void> {
-  const config = await loadConfig();
-  const vaultPath = expandHome(config.vault_path);
-  const manifestPath = resolveManifestPath(vaultPath);
-  if (!manifestPath) throw new Error(`no skillmux.toml found at ${vaultPath}; run skillmux init first`);
-  const manifest = parseManifest(await Bun.file(manifestPath).text());
+  const { vaultPath, manifestPath, manifest } = await loadManifestContext();
 
   if (subCommand === "list" || subCommand === "show") {
-    const names = subCommand === "show" ? [args[0] ?? ""] : Object.keys(manifest.targets);
+    const names =
+      subCommand === "show" ? [args[0] ?? ""] : Object.keys(manifest.targets);
     if (subCommand === "show" && !manifest.targets[names[0]!]) {
       throw new Error(`target "${names[0]}" does not exist`);
     }
@@ -1102,7 +1347,9 @@ async function runTarget(
         console.log(`  dir: ${target.dir}`);
         console.log(`  host: ${target.host ?? "(global)"}`);
         console.log(`  clients: ${target.clients.join(", ") || "(custom)"}`);
-        console.log(`  projects: ${target.project_groups.join(", ") || "(none)"}`);
+        console.log(
+          `  projects: ${target.project_groups.join(", ") || "(none)"}`,
+        );
       }
     }
     return;
@@ -1110,24 +1357,30 @@ async function runTarget(
 
   if (subCommand === "add") {
     const name = args[0];
-    const pathIndex = args.indexOf("--path");
-    const rawPath = pathIndex === -1 ? undefined : args[pathIndex + 1];
-    if (!name || !rawPath) throw new Error("usage: skillmux target add <name> --path <dir> --yes");
+    const dirIndex = args.indexOf("--dir");
+    const rawPath = dirIndex === -1 ? undefined : args[dirIndex + 1];
+    if (!name || !rawPath)
+      throw new Error("usage: skillmux target add <name> --dir <dir> --yes");
     const path = expandHome(rawPath);
     if (options.dryRun) {
       const planned = planInitManifest(vaultPath, [{ name, dir: path }], []);
-      console.log(options.isJson
-        ? JSON.stringify({ schema_version: 1, target: planned.targets[name] })
-        : `target add: ${name} -> ${path} (dry-run)`);
+      console.log(
+        options.isJson
+          ? JSON.stringify({ schema_version: 1, target: planned.targets[name] })
+          : `target add: ${name} -> ${path} (dry-run)`,
+      );
       return;
     }
-    if (!args.includes("--yes")) {
-      if (!options.isJson && isInteractive()) {
-        if (!(await confirmAction(`Adopt target ${name} at ${path}?`))) return;
-      } else {
-        throw new Error("skillmux target add requires --yes when run non-interactively");
-      }
-    }
+    if (
+      !(await confirmIfNeeded({
+        confirmed: args.includes("--yes"),
+        isJson: options.isJson,
+        prompt: `Adopt target ${name} at ${path}?`,
+        nonInteractiveError:
+          "skillmux target add requires --yes when run non-interactively",
+      }))
+    )
+      return;
     applyInit(vaultPath, [{ name, dir: path }]);
     console.log(`target "${name}" added at ${path}`);
     return;
@@ -1136,93 +1389,97 @@ async function runTarget(
   if (subCommand === "remove") {
     const name = args[0];
     if (!name || !manifest.targets[name]) {
-      throw new Error(name ? `target "${name}" does not exist` : "usage: skillmux target remove <name> --yes");
+      throw new Error(
+        name
+          ? `target "${name}" does not exist`
+          : "usage: skillmux target remove <name> --yes",
+      );
     }
     if (options.dryRun) {
       console.log(`target remove: ${name} (files preserved, dry-run)`);
       return;
     }
-    if (!args.includes("--yes")) {
-      if (!options.isJson && isInteractive()) {
-        if (!(await confirmAction(`Remove target ${name} from the manifest and preserve its files?`))) return;
-      } else {
-        throw new Error("skillmux target remove requires --yes when run non-interactively");
-      }
-    }
+    if (
+      !(await confirmIfNeeded({
+        confirmed: args.includes("--yes"),
+        isJson: options.isJson,
+        prompt: `Remove target ${name} from the manifest and preserve its files?`,
+        nonInteractiveError:
+          "skillmux target remove requires --yes when run non-interactively",
+      }))
+    )
+      return;
     const targets = { ...manifest.targets };
     delete targets[name];
     writeManifestAtomic(manifestPath, { ...manifest, targets });
-    console.log(`target "${name}" removed from the manifest; files preserved at ${manifest.targets[name]!.dir}`);
+    console.log(
+      `target "${name}" removed from the manifest; files preserved at ${manifest.targets[name]!.dir}`,
+    );
     return;
   }
 
   throw new Error("usage: skillmux target <list|show|add|remove>");
 }
 
-function parseManifestPinArgs(args: string[]): { skillId: string; core: boolean; project?: string; paths: string[] } {
-  const skillId = args[0];
-  if (!skillId) throw new Error(MANIFEST_USAGE);
-  let core = false;
-  let project: string | undefined;
-  const paths: string[] = [];
-  for (let i = 1; i < args.length; i++) {
-    const arg = args[i];
-    if (arg === "--core") core = true;
-    else if (arg === "--project") {
-      const value = args[++i];
-      if (!value) throw new Error("--project requires a group name");
-      project = value;
-    } else if (arg === "--path") {
-      const value = args[++i];
-      if (!value) throw new Error("--path requires a path");
-      paths.push(value);
-    } else throw new Error(`unknown manifest option: ${arg}`);
-  }
-  if (core === (project !== undefined)) throw new Error(MANIFEST_USAGE);
-  return { skillId, core, project, paths };
-}
-
-async function runManifest(subCommand: string, args: string[]): Promise<void> {
-  if (subCommand !== "pin" && subCommand !== "unpin") throw new Error(MANIFEST_USAGE);
-  const { skillId, core, project, paths } = parseManifestPinArgs(args);
-  const config = await loadConfig();
-  const vaultPath = expandHome(config.vault_path);
-  const localVaultPaths = config.local_vault_paths.map(expandHome);
-  const manifestPath = resolveManifestPath(vaultPath);
-  if (!manifestPath) throw new Error(`no skillmux.toml found at ${vaultPath}`);
-  const manifest = parseManifest(await Bun.file(manifestPath).text());
-
-  let updated;
-  if (core) {
-    updated = subCommand === "pin" ? pinCore(manifest, skillId) : unpinCore(manifest, skillId);
-  } else {
-    updated =
-      subCommand === "pin"
-        ? pinProject(manifest, skillId, project!, paths)
-        : unpinProject(manifest, skillId, project!);
-  }
-  validateManifest(updated, vaultPath, localVaultPaths);
-  await Bun.write(manifestPath, serializeManifest(updated));
-  console.log(`${subCommand === "pin" ? "pinned" : "unpinned"} "${skillId}" ${core ? "[core]" : `[project.${project}]`}`);
-}
-
-async function runLocalVaultInit(args: string[]): Promise<void> {
+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>");
+  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`);
+    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) {
+    console.log(
+      options.isJson
+        ? JSON.stringify({
+            schema_version: 1,
+            marker_path: markerPath,
+            vault_path: expandHome(config.vault_path),
+          })
+        : `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));
-  console.log(`wrote ${join(expanded, ".skillmux")} (role: local_vault, vault_path: ${expandHome(config.vault_path)})`);
+  if (options.isJson) {
+    console.log(
+      JSON.stringify({
+        schema_version: 1,
+        marker_path: markerPath,
+        vault_path: expandHome(config.vault_path),
+      }),
+    );
+  } else {
+    console.log(
+      `wrote ${markerPath} (role: local_vault, vault_path: ${expandHome(config.vault_path)})`,
+    );
+  }
 }
 
-async function runModelDownload(): Promise<void> {
+async function runModelDownload(options: { isJson: boolean }): Promise<void> {
   const cacheDir = await downloadLocalModels(await loadConfig());
-  console.log(`models ready in ${cacheDir}`);
+  emitSuccess({ isJson: options.isJson }, { cache_dir: cacheDir }, () =>
+    console.log(`models ready in ${cacheDir}`),
+  );
 }
 
 function parseSyncArgs(args: string[]): {
@@ -1289,10 +1546,18 @@ async function runSync(args: string[]): Promise<void> {
 
     const suffix = dryRun ? " (dry-run)" : "";
     const result = syncTarget(
-      { vaultPath, targetDir, targetName, coreSkillIds: manifest.core.skills, localVaultPaths },
+      {
+        vaultPath,
+        targetDir,
+        targetName,
+        coreSkillIds: manifest.core.skills,
+        localVaultPaths,
+      },
       { dryRun },
     );
-    console.log(`${targetName}: +${result.added.length} -${result.removed.length}${suffix}`);
+    console.log(
+      `${targetName}: +${result.added.length} -${result.removed.length}${suffix}`,
+    );
 
     if (target.project_groups.length > 0) {
       const allGroups = manifest.project ?? {};
@@ -1349,9 +1614,9 @@ function parseInitArgs(args: string[]): {
       if (!value) throw new Error("--vault requires a path");
       vaultPath = value;
       i++;
-    } else if (option === "--path") {
+    } else if (option === "--dir") {
       const value = args[i + 1];
-      if (!value) throw new Error("--path requires a directory");
+      if (!value) throw new Error("--dir requires a directory");
       customPath = value;
       i++;
     } else if (option === "--core") {
@@ -1359,7 +1624,11 @@ function parseInitArgs(args: string[]): {
       if (!value) throw new Error("--core requires a skill_id");
       coreSkillIds.push(value);
       i++;
-    } else if (option === "--dry-run" || option === "--json" || option === "--interactive") {
+    } else if (
+      option === "--dry-run" ||
+      option === "--json" ||
+      option === "--interactive"
+    ) {
       continue;
     } else if (option === "--migrate-full-vault") {
       migrateFullVault = true;
@@ -1411,10 +1680,13 @@ async function runInit(
   let configPlan: ConfigInitPlan | undefined;
   let vaultPath: string;
   if (!existsSync(configPath)) {
-    const bootstrapVaultPath = requestedVaultPath ??
+    const bootstrapVaultPath =
+      requestedVaultPath ??
       (!options.isJson && isInteractive() ? "~/skills" : undefined);
     if (!bootstrapVaultPath) {
-      throw new Error(`machine config does not exist: ${configPath}; re-run with --vault <path>`);
+      throw new Error(
+        `machine config does not exist: ${configPath}; re-run with --vault <path>`,
+      );
     }
     configPlan = planConfigInit(configPath, expandHome(bootstrapVaultPath));
     vaultPath = configPlan.vaultPath;
@@ -1439,15 +1711,21 @@ async function runInit(
   let selectedClients = requestedClients;
   if (guided) {
     const detected = detectInstalledClients({
-      codexHome: process.env.CODEX_HOME ? expandHome(process.env.CODEX_HOME) : undefined,
+      codexHome: process.env.CODEX_HOME
+        ? expandHome(process.env.CODEX_HOME)
+        : undefined,
     });
-    const evidence = new Map(detected.map((item) => [item.client, item.evidence]));
+    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,
+        detail: evidence.has(client)
+          ? `detected: ${evidence.get(client)}`
+          : undefined,
         selected: evidence.has(client) || requestedClients.includes(client),
       })),
     );
@@ -1455,16 +1733,26 @@ async function runInit(
   let selectedCoreSkillIds = coreSkillIds;
   if (guided) {
     selectedCoreSkillIds = parseCommaList(
-      await promptText("Core skill IDs to add, comma-separated", coreSkillIds.join(",")),
+      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,
+    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) {
@@ -1475,25 +1763,39 @@ async function runInit(
     }
   }
   for (const manual of instructionPlan.manual) {
-    instructionReadiness[manual.client] = { status: "manual", detail: manual.reason };
+    instructionReadiness[manual.client] = {
+      status: "manual",
+      detail: manual.reason,
+    };
   }
-  const builtInNames = new Set(["agent-skills", "claude-code", "codex", "custom", "agents", "claude"]);
+  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,
+        codexHome: process.env.CODEX_HOME
+          ? expandHome(process.env.CODEX_HOME)
+          : undefined,
         customPath: customPath ? expandHome(customPath) : undefined,
       }),
     );
   if (customPath && !explicitTargets.includes("custom")) {
-    throw new Error("--path may only be used with --target 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),
+    explicitSurfaceTargets.map(
+      (target) => [target.path, target.targetName] as const,
+    ),
   );
   const existingManifestPath = resolveManifestPath(vaultPath);
   const existingManifest = existingManifestPath
@@ -1504,7 +1806,8 @@ async function runInit(
       targetByPath.set(
         surface.path,
         existingManifest
-          ? configuredTargetForSurface(existingManifest, surface) ?? surface.targetName
+          ? (configuredTargetForSurface(existingManifest, surface) ??
+              surface.targetName)
           : surface.targetName,
       );
     }
@@ -1518,7 +1821,8 @@ async function runInit(
   const candidates = detectSurfaces(candidatePaths, vaultPath);
   if (!options.isJson) {
     for (const candidate of candidates) {
-      const name = targetByPath.get(candidate.path) ?? deriveTargetName(candidate.path);
+      const name =
+        targetByPath.get(candidate.path) ?? deriveTargetName(candidate.path);
       if (candidate.state === "missing") {
         console.log(`${name} (${candidate.path}): not found`);
         continue;
@@ -1528,26 +1832,45 @@ async function runInit(
         continue;
       }
       if (candidate.state === "full-vault") {
-        console.log(`${name} (${candidate.path}): full-vault -> ${candidate.canonicalPath}`);
+        console.log(
+          `${name} (${candidate.path}): full-vault -> ${candidate.canonicalPath}`,
+        );
         continue;
       }
       if (candidate.state === "external-symlink") {
-        console.log(`${name} (${candidate.path}): external symlink -> ${candidate.canonicalPath}`);
+        console.log(
+          `${name} (${candidate.path}): external symlink -> ${candidate.canonicalPath}`,
+        );
         continue;
       }
       if (candidate.state === "unsupported") {
-        console.log(`${name} (${candidate.path}): unsupported filesystem entry`);
+        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}`);
+      const marked = candidate.alreadyMarked
+        ? ", already skillmux-managed"
+        : "";
+      console.log(
+        `${name} (${candidate.path}): ${kind}, ${candidate.skillCount} skills${marked}`,
+      );
     }
-    for (const readiness of assessClientReadiness(clientPlan, instructionReadiness)) {
+    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}`);
+      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(
@@ -1578,20 +1901,28 @@ async function runInit(
 
   const byName = new Map(
     candidates
-      .filter((candidate) =>
-        candidate.deliveryMode === "managed-pins" ||
-        (migrateFullVault && candidate.state === "full-vault"),
+      .filter(
+        (candidate) =>
+          candidate.deliveryMode === "managed-pins" ||
+          (migrateFullVault && candidate.state === "full-vault"),
       )
-      .map((candidate) => [
-        targetByPath.get(candidate.path) ?? deriveTargetName(candidate.path),
-        candidate,
-      ] as const),
+      .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),
+    candidates.map(
+      (candidate) =>
+        [
+          targetByPath.get(candidate.path) ?? deriveTargetName(candidate.path),
+          candidate,
+        ] as const,
+    ),
   );
   for (const name of requestedTargets) {
     if (!byName.has(name)) {
@@ -1600,7 +1931,9 @@ async function runInit(
           `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`);
+      throw new Error(
+        `unknown --target "${name}": not among detected surfaces`,
+      );
     }
   }
 
@@ -1612,7 +1945,11 @@ async function runInit(
       ...(candidate.state === "full-vault" ? { migrateFullVault: true } : {}),
     };
   });
-  const plannedManifest = planInitManifest(vaultPath, confirmedTargets, selectedCoreSkillIds);
+  const plannedManifest = planInitManifest(
+    vaultPath,
+    confirmedTargets,
+    selectedCoreSkillIds,
+  );
   const serializedPlan = {
     vault_path: vaultPath,
     config: configPlan
@@ -1630,44 +1967,50 @@ async function runInit(
   };
   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,
-      }));
+      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)) {
+    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`,
+          `${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,
-      }));
+      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)"}`,
+          `${instructionPlan.changes.filter((change) => change.status !== "unchanged").length} instruction file(s), ` +
+          `core: ${plannedManifest.core.skills.join(", ") || "(unchanged)"}`,
       );
     }
     return;
@@ -1684,7 +2027,9 @@ async function runInit(
         console.log(
           `  instructions: ${instructionPlan.changes.filter((change) => change.status !== "unchanged").length} file(s)`,
         );
-        console.log(`  core: ${plannedManifest.core.skills.join(", ") || "(none)"}`);
+        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");
@@ -1692,10 +2037,14 @@ async function runInit(
         }
       } else {
         const prompts = [
-          ...confirmedTargets.map((target) => `Adopt ${target.name} at ${target.dir}?`),
+          ...confirmedTargets.map(
+            (target) => `Adopt ${target.name} at ${target.dir}?`,
+          ),
           ...instructionPlan.changes
             .filter((change) => change.status !== "unchanged")
-            .map((change) => `${change.status} instruction file ${change.path}?`),
+            .map(
+              (change) => `${change.status} instruction file ${change.path}?`,
+            ),
           ...(hasConfigWrite ? [`Create machine config ${configPath}?`] : []),
           ...(selectedCoreSkillIds.length > 0
             ? [`Pin core skills: ${selectedCoreSkillIds.join(", ")}?`]
@@ -1754,42 +2103,53 @@ async function runInit(
   }
 
   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,
-      },
-    }));
+    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(", ")}`);
+    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 manifest pin <skill_id> --core");
+    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")) {
+  if (
+    selectedClients.length === 0 ||
+    selectedClients.includes("skillmux-mcp")
+  ) {
     console.log(`\n${printLastMile()}`);
   }
   if (guided && sync && confirmedTargets.length > 0) await runSync([]);
 }
 
-function parseReportArgs(args: string[]): { server?: string; db?: string; since?: string } {
+function parseReportArgs(args: string[]): {
+  server?: string;
+  db?: string;
+  since?: string;
+} {
   let server: string | undefined;
   let db: string | undefined;
   let since: string | undefined;
@@ -1808,6 +2168,8 @@ function parseReportArgs(args: string[]): { server?: string; db?: string; 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 {
       throw new Error(`unknown report option: ${option}`);
     }
@@ -1816,24 +2178,45 @@ function parseReportArgs(args: string[]): { server?: string; db?: string; since?
   return { server, db, since };
 }
 
-async function runReport(args: string[]): Promise<void> {
+async function runReport(
+  args: string[],
+  options: { isJson: boolean },
+): Promise<void> {
   const { server, db: dbPath, since } = parseReportArgs(args);
-  if (!since) throw new Error("usage: skillmux report [--server <url> | --db <path>] --since <window>");
+  if (!since)
+    throw new Error(
+      "usage: skillmux report [--server <url> | --db <path>] --since <window> [--json]",
+    );
 
   if (server) {
     const url = `${server.replace(/\/$/, "")}/stats?since=${encodeURIComponent(since)}`;
     const res = await fetch(url);
-    if (!res.ok) throw new Error(`skillmux report --server failed: ${res.status} ${await res.text()}`);
-    console.log(renderStatsText((await res.json()) as StatsResponse));
+    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 }) : openIndex(expandHome((await loadConfig()).state_dir));
-  console.log(renderStatsText(getStats(db, since)));
+  const db = dbPath
+    ? new Database(dbPath, { readonly: true })
+    : openIndex(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 } {
+function parseScanArgs(args: string[]): {
+  path?: string;
+  format: "text" | "json";
+  failOn?: ScanSeverity;
+} {
   let path: string | undefined;
   let format: "text" | "json" = "text";
   let failOn: ScanSeverity | undefined;
@@ -1841,7 +2224,8 @@ function parseScanArgs(args: string[]): { path?: string; format: "text" | "json"
     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");
+      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];
@@ -1849,6 +2233,8 @@ function parseScanArgs(args: string[]): { path?: string; format: "text" | "json"
         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) {
@@ -1860,11 +2246,20 @@ function parseScanArgs(args: string[]): { path?: string; format: "text" | "json"
   return { path, format, failOn };
 }
 
-async function runScan(args: string[]): Promise<void> {
+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 rootPath = path
+    ? expandHome(path)
+    : expandHome((await loadConfig()).vault_path);
   const result = await scanPath(rootPath);
-  console.log(format === "json" ? renderScanJson(result) : renderScanText(result));
+  emitSuccess({ isJson: options.isJson }, result, () => {
+    console.log(
+      format === "json" ? renderScanJson(result) : renderScanText(result),
+    );
+  });
   process.exitCode = scanExitCode(result.findings, failOn);
 }
 
@@ -1888,6 +2283,8 @@ function parseInstallArgs(args: string[]): {
         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 install option: ${option}`);
     } else if (repo !== undefined) {
@@ -1899,39 +2296,73 @@ function parseInstallArgs(args: string[]): {
   return { repo, force, dryRun, failOn };
 }
 
-async function runInstall(args: string[]): Promise<void> {
+async function runInstall(
+  args: string[],
+  options: { isJson: boolean },
+): Promise<void> {
   const { repo, force, dryRun, failOn } = parseInstallArgs(args);
   if (!repo) {
-    throw new Error("usage: skillmux install <repo>[/path] [--force] [--fail-on low|medium|high] [--dry-run]");
+    throw new Error(
+      "usage: skillmux install <repo>[/path] [--force] [--fail-on low|medium|high] [--dry-run] [--json]",
+    );
   }
 
   const source = resolveRepoSource(repo);
   const cloneDir = await cloneToTemp(source.url);
   try {
-    const resolved = resolveSkillDir(cloneDir, deriveRepoName(source.url), source.skillPath);
-    const { findings } = await validateSkillCandidate(resolved.skillId, resolved.dir);
-    console.log(renderScanText({ scanned: 1, findings }));
+    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`);
+      console.error(
+        `aborting install: a finding met the --fail-on ${failOn} threshold`,
+      );
       return;
     }
 
     const vaultPath = expandHome((await loadConfig()).vault_path);
     if (dryRun) {
-      console.log(`dry-run: would install "${resolved.skillId}" into ${join(vaultPath, resolved.skillId)}`);
+      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 targetDir = installIntoVault(vaultPath, resolved.skillId, resolved.dir, force);
-    console.log(`installed "${resolved.skillId}" into ${targetDir}`);
+    const targetDir = installIntoVault(
+      vaultPath,
+      resolved.skillId,
+      resolved.dir,
+      force,
+    );
+    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 });
   }
 }
 
-function parseCalibrateGenerateDatasetArgs(args: string[]): { vault?: string; out?: string } {
+function parseCalibrateGenerateDatasetArgs(args: string[]): {
+  vault?: string;
+  out?: string;
+} {
   let vault: string | undefined;
   let out: string | undefined;
   for (let i = 0; i < args.length; i++) {
@@ -1952,7 +2383,8 @@ function parseCalibrateGenerateDatasetArgs(args: string[]): { vault?: string; ou
 }
 
 async function runCalibrateGenerateDataset(args: string[]): Promise<void> {
-  const { vault: vaultArg, out: outArg } = parseCalibrateGenerateDatasetArgs(args);
+  const { vault: vaultArg, out: outArg } =
+    parseCalibrateGenerateDatasetArgs(args);
   const config = await loadConfig();
   const vaultPath = expandHome(vaultArg ?? config.vault_path);
   const outPath = expandHome(outArg ?? join(config.state_dir, "queries.json"));
@@ -1963,7 +2395,9 @@ async function runCalibrateGenerateDataset(args: string[]): Promise<void> {
   const parentDir = join(outPath, "..");
   mkdirSync(parentDir, { recursive: true });
   await Bun.write(outPath, JSON.stringify(dataset, null, 2) + "\n");
-  console.log(`generated synthetic dataset with ${dataset.length} cases at ${outPath}`);
+  console.log(
+    `generated synthetic dataset with ${dataset.length} cases at ${outPath}`,
+  );
 }
 
 if (import.meta.main) {