@klhapp/skillmux 0.5.0 → 1.0.0

package/src/cli.ts

@@ -1,20 +1,27 @@
 #!/usr/bin/env bun
 import { Database } from "bun:sqlite";
-import { existsSync, mkdirSync, rmSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, rmSync } from "node:fs";
 import { hostname } from "node:os";
-import { join } from "node:path";
+import { basename, join } from "node:path";
 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";
 import {
   assessClientReadiness,
+  detectInstalledClients,
   planClientSurfaces,
   resolveBuiltInTarget,
+  SUPPORTED_CLIENT_IDS,
   type ClientId,
   type ReadinessAxis,
 } from "./init-clients";
@@ -47,11 +54,28 @@ import {
   serializeManifest,
   unpinCore,
   unpinProject,
+  upsertProject,
+  updateProjectPaths,
+  updateProjectTargets,
   validateManifest,
+  writeManifestAtomic,
 } from "./manifest";
 import { downloadLocalModels } from "./models";
+import { resolveProjectDirectory, suggestProjectName } from "./project-setup";
+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,
@@ -79,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 = [
@@ -91,14 +123,16 @@ const KNOWN_COMMANDS = [
   "index",
   "sync",
   "init",
+  "project",
+  "target",
+  "core",
   "report",
   "scan",
   "install",
   "eval",
   "doctor",
   "models",
-  "which",
-  "manifest",
+  "skill",
   "local-vault",
 ];
 
@@ -133,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;
@@ -149,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);
@@ -191,40 +243,56 @@ async function main() {
       case "init":
         await runInit(rawArgv.slice(1), { isJson, dryRun: isDryRun });
         break;
+      case "project":
+        await runProject(subCommand, commandArgs, { isJson, dryRun: isDryRun });
+        break;
+      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|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);
       }
     }
@@ -236,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(
         [
@@ -251,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;
   }
 
@@ -277,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;
   }
 
@@ -292,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;
   }
 
@@ -304,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;
@@ -328,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") {
@@ -348,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;
   }
 
@@ -418,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;
   }
 
@@ -454,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;
   }
 
@@ -482,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();
@@ -495,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;
@@ -503,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(
         [
@@ -525,9 +633,9 @@ async function handleCalibrateCommand(
           { key: "created_at", header: "CREATED_AT" },
           { key: "status", header: "STATUS" },
         ],
-        res
+        res,
       );
-    }
+    });
     return;
   }
 
@@ -535,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;
   }
 
@@ -548,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;
   }
 
@@ -562,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) {
@@ -574,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;
@@ -589,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);
     }
@@ -601,9 +713,17 @@ 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] [--yes|--dry-run] [--json]
+                [--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]
+                [--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,
@@ -613,8 +733,8 @@ Init targets:
   agent-skills, claude-code, codex, custom
 
 Commands:
-  serve, index, sync, init, 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`);
 }
 
 // ---------------------------------------------------------------------------
@@ -623,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++) {
@@ -653,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
@@ -665,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`);
@@ -709,75 +847,639 @@ 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]";
 
-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}`);
+interface ProjectInitArgs {
+  path: string;
+  name: string;
+  skills: string[];
+  clients: string[];
+  targets: string[];
+  yes: boolean;
+  sync: boolean;
+}
+
+function configuredTargetForSurface(
+  manifest: ReturnType<typeof parseManifest>,
+  surface: { targetName: string; path: string },
+): string | undefined {
+  if (manifest.targets[surface.targetName]) return surface.targetName;
+  return Object.entries(manifest.targets).find(
+    ([, target]) => expandHome(target.dir) === surface.path,
+  )?.[0];
+}
+
+function configuredTargetsForClients(
+  manifest: ReturnType<typeof parseManifest>,
+  clients: readonly string[],
+): string[] {
+  return planClientSurfaces(clients).surfaces.map((surface) => {
+    const target = configuredTargetForSurface(manifest, surface);
+    if (target) return target;
+    const client = surface.clients[0]!;
+    throw new Error(
+      `client target for "${client}" is not configured; run "skillmux init --client ${client} --yes" first`,
+    );
+  });
+}
+
+function parseProjectInitArgs(args: string[]): ProjectInitArgs {
+  let projectPath: string | undefined;
+  let name: string | undefined;
+  const skills: string[] = [];
+  const clients: string[] = [];
+  const targets: string[] = [];
+  let yes = false;
+  let sync = true;
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]!;
+    if (arg === "--name") {
+      name = args[++i];
+      if (!name) throw new Error("--name requires a group name");
+    } else if (arg === "--skill") {
+      const skill = args[++i];
+      if (!skill) throw new Error("--skill requires a skill_id");
+      skills.push(skill);
+    } else if (arg === "--target") {
+      const target = args[++i];
+      if (!target) throw new Error("--target requires a name");
+      targets.push(target);
+    } else if (arg === "--client") {
+      const client = args[++i];
+      if (!client) throw new Error("--client requires a name");
+      clients.push(client);
+    } else if (arg === "--yes") {
+      yes = true;
+    } else if (arg === "--no-sync") {
+      sync = false;
+    } else if (
+      arg === "--dry-run" ||
+      arg === "--json" ||
+      arg === "--interactive"
+    ) {
+      continue;
+    } else if (arg.startsWith("-")) {
+      throw new Error(`unknown project init option: ${arg}`);
+    } else if (projectPath) {
+      throw new Error(PROJECT_INIT_USAGE);
+    } else {
+      projectPath = arg;
+    }
   }
-  if (core === (project !== undefined)) throw new Error(MANIFEST_USAGE);
-  return { skillId, core, project, paths };
+
+  const path = resolveProjectDirectory(
+    projectPath ? expandHome(projectPath) : undefined,
+  );
+  return {
+    path,
+    name: name ?? suggestProjectName(basename(path)),
+    skills,
+    clients,
+    targets,
+    yes,
+    sync,
+  };
 }
 
-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);
+async function loadManifestContext() {
   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}`);
+  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(
+  subCommand: string,
+  args: string[],
+  options: { isJson: boolean; dryRun: boolean },
+): Promise<void> {
+  if (subCommand === "list" || subCommand === "show") {
+    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`);
+    }
+    const projects = names.map((name) => ({
+      name,
+      paths: manifest.project?.[name]!.paths ?? [],
+      skills: manifest.project?.[name]!.skills ?? [],
+      targets: Object.entries(manifest.targets)
+        .filter(([, target]) => target.project_groups.includes(name))
+        .map(([target]) => target),
+    }));
+    if (options.isJson) {
+      console.log(JSON.stringify({ schema_version: 1, projects }));
+    } else if (projects.length === 0) {
+      console.log("no project groups configured");
+    } else {
+      for (const project of projects) {
+        console.log(`${project.name}:`);
+        console.log(`  paths: ${project.paths.join(", ") || "(none)"}`);
+        console.log(`  skills: ${project.skills.join(", ") || "(none)"}`);
+        console.log(`  targets: ${project.targets.join(", ") || "(none)"}`);
+      }
+    }
+    return;
+  }
+  if (subCommand === "add-path" || subCommand === "remove-path") {
+    const group = args[0];
+    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 yes = args.includes("--yes");
+    if (!existsSync(projectPath) || !lstatSync(projectPath).isDirectory()) {
+      throw new Error(`project path is not a directory: ${projectPath}`);
+    }
+    const { config, vaultPath, manifestPath, manifest } =
+      await loadManifestContext();
+    const updated = updateProjectPaths(manifest, group, {
+      ...(subCommand === "add-path"
+        ? { add: [projectPath] }
+        : { remove: [projectPath] }),
+    });
+    validateManifest(
+      updated,
+      vaultPath,
+      config.local_vault_paths.map(expandHome),
+    );
+    if (options.dryRun) {
+      console.log(`${subCommand}: [project.${group}] ${projectPath} (dry-run)`);
+      return;
+    }
+    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;
+  }
+  if (subCommand === "pin" || subCommand === "unpin") {
+    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`,
+      );
+    }
+    const yes = args.includes("--yes");
+    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);
+    }
+    validateManifest(
+      updated,
+      vaultPath,
+      config.local_vault_paths.map(expandHome),
+    );
+    if (options.dryRun) {
+      console.log(
+        `${subCommand}: [project.${group}] ${skills.join(", ")} (dry-run)`,
+      );
+      return;
+    }
+    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`,
+      );
+    const clients: string[] = [];
+    const requestedTargets: string[] = [];
+    for (let i = 1; i < args.length; i++) {
+      if (args[i] === "--client") {
+        const value = args[++i];
+        if (!value) throw new Error("--client requires a name");
+        clients.push(value);
+      } else if (args[i] === "--target") {
+        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"
+      ) {
+        throw new Error(`unknown project ${subCommand} option: ${args[i]}`);
+      }
+    }
+    const { config, vaultPath, manifestPath, manifest } =
+      await loadManifestContext();
+    const clientTargets = configuredTargetsForClients(manifest, clients);
+    const targets = [...new Set([...requestedTargets, ...clientTargets])];
+    if (targets.length === 0) {
+      throw new Error(`project ${subCommand} requires --client or --target`);
+    }
+    const updated = updateProjectTargets(manifest, group, {
+      ...(subCommand === "attach" ? { attach: targets } : { detach: targets }),
+    });
+    validateManifest(
+      updated,
+      vaultPath,
+      config.local_vault_paths.map(expandHome),
+    );
+    if (options.dryRun) {
+      console.log(
+        `${subCommand}: [project.${group}] ${targets.join(", ")} (dry-run)`,
+      );
+      return;
+    }
+    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;
+  }
+  if (subCommand !== "init") throw new Error(PROJECT_INIT_USAGE);
+  let request = parseProjectInitArgs(args);
+  const guided = shouldUseWizard(args, {
+    interactive: isInteractive(),
+    json: options.isJson,
+    dryRun: options.dryRun,
+  });
+  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, vaultPath, manifestPath, manifest } =
+    await loadManifestContext();
+  const localVaultPaths = config.local_vault_paths.map(expandHome);
+  if (guided) {
+    const name = await promptText("Project group", request.name);
+    const availableClients = SUPPORTED_CLIENT_IDS.filter((client) => {
+      const surface = planClientSurfaces([client]).surfaces[0];
+      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),
+      })),
+    );
+    const skills = parseCommaList(
+      await promptText(
+        "Project skill IDs, comma-separated",
+        request.skills.join(","),
+      ),
+    );
+    request = { ...request, name, clients, skills };
+  }
+  const clientTargets = configuredTargetsForClients(manifest, request.clients);
+  const targets = [...new Set([...request.targets, ...clientTargets])];
+  const updated = upsertProject(manifest, {
+    name: request.name,
+    paths: [request.path],
+    skills: request.skills,
+    targets,
+  });
+  const { notes } = validateManifest(updated, vaultPath, localVaultPaths);
+  const plan = {
+    mode: "project",
+    project: request.name,
+    path: request.path,
+    skills: request.skills,
+    clients: request.clients,
+    targets,
+    sync: request.sync,
+    notes,
+  };
 
-  let updated;
-  if (core) {
-    updated = subCommand === "pin" ? pinCore(manifest, skillId) : unpinCore(manifest, skillId);
+  if (options.dryRun) {
+    console.log(
+      options.isJson
+        ? JSON.stringify({ schema_version: 1, plan })
+        : `project plan: ${JSON.stringify(plan)}`,
+    );
+    return;
+  }
+  if (!request.yes) {
+    if (!options.isJson && isInteractive()) {
+      if (guided) {
+        console.log("\nReview");
+        console.log(`  project: ${request.name}`);
+        console.log(`  path: ${request.path}`);
+        console.log(`  clients: ${request.clients.join(", ") || "(none)"}`);
+        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}?`,
+        ))
+      ) {
+        console.log("project setup cancelled");
+        return;
+      }
+    } else {
+      throw new Error(
+        "skillmux project init requires --yes when run non-interactively",
+      );
+    }
+  }
+
+  writeManifestAtomic(manifestPath, updated);
+  if (request.sync) {
+    try {
+      await runSync([]);
+    } catch (error) {
+      throw new Error(
+        `project configuration was saved, but sync failed; fix the reported issue and run "skillmux sync": ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      );
+    }
+  }
+  if (options.isJson) {
+    console.log(JSON.stringify({ schema_version: 1, result: plan }));
   } else {
+    console.log(`project "${request.name}" ready at ${request.path}`);
+  }
+}
+
+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"
-        ? pinProject(manifest, skillId, project!, paths)
-        : unpinProject(manifest, skillId, project!);
+        ? 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 { vaultPath, manifestPath, manifest } = await loadManifestContext();
+
+  if (subCommand === "list" || subCommand === "show") {
+    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`);
+    }
+    const targets = names.map((name) => {
+      const target = manifest.targets[name]!;
+      const clients = SUPPORTED_CLIENT_IDS.filter((client) => {
+        const surface = planClientSurfaces([client]).surfaces[0];
+        return surface !== undefined && surface.path === expandHome(target.dir);
+      });
+      return { name, ...target, clients };
+    });
+    if (options.isJson) {
+      console.log(JSON.stringify({ schema_version: 1, targets }));
+    } else if (targets.length === 0) {
+      console.log("no targets configured");
+    } else {
+      for (const target of targets) {
+        console.log(`${target.name}:`);
+        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)"}`,
+        );
+      }
+    }
+    return;
+  }
+
+  if (subCommand === "add") {
+    const name = args[0];
+    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)`,
+      );
+      return;
+    }
+    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;
+  }
+
+  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",
+      );
+    }
+    if (options.dryRun) {
+      console.log(`target remove: ${name} (files preserved, dry-run)`);
+      return;
+    }
+    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}`,
+    );
+    return;
   }
-  validateManifest(updated, vaultPath, localVaultPaths);
-  await Bun.write(manifestPath, serializeManifest(updated));
-  console.log(`${subCommand === "pin" ? "pinned" : "unpinned"} "${skillId}" ${core ? "[core]" : `[project.${project}]`}`);
+
+  throw new Error("usage: skillmux target <list|show|add|remove>");
 }
 
-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[]): {
@@ -844,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 ?? {};
@@ -873,6 +1583,8 @@ function parseInitArgs(args: string[]): {
   coreSkillIds: string[];
   customPath?: string;
   migrateFullVault: boolean;
+  skipInstructions: boolean;
+  sync: boolean;
   vaultPath?: string;
   yes: boolean;
 } {
@@ -881,6 +1593,8 @@ function parseInitArgs(args: 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++) {
@@ -900,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") {
@@ -910,17 +1624,35 @@ 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") {
+    } 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, vaultPath, yes };
+  return {
+    targets,
+    clients,
+    coreSkillIds,
+    customPath,
+    migrateFullVault,
+    skipInstructions,
+    sync,
+    vaultPath,
+    yes,
+  };
 }
 
 async function runInit(
@@ -933,18 +1665,28 @@ async function runInit(
     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 ??
+    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;
@@ -966,12 +1708,51 @@ async function runInit(
     throw new Error(vaultHealth.message);
   }
 
-  const clientPlan = planClientSurfaces(requestedClients, {
-    codexHome: process.env.CODEX_HOME ? expandHome(process.env.CODEX_HOME) : undefined,
-  });
-  const instructionPlan = planInstructionSetup(clientPlan.clients.map((client) => client.id), {
-    codexHome: process.env.CODEX_HOME ? expandHome(process.env.CODEX_HOME) : undefined,
+  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) {
@@ -982,28 +1763,54 @@ 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
+    ? parseManifest(await Bun.file(existingManifestPath).text())
+    : undefined;
   for (const surface of clientPlan.surfaces) {
-    if (!targetByPath.has(surface.path)) targetByPath.set(surface.path, surface.targetName);
+    if (!targetByPath.has(surface.path)) {
+      targetByPath.set(
+        surface.path,
+        existingManifest
+          ? (configuredTargetForSurface(existingManifest, surface) ??
+              surface.targetName)
+          : surface.targetName,
+      );
+    }
   }
   const candidatePaths = [
     ...new Set([
@@ -1014,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;
@@ -1024,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(
@@ -1068,26 +1895,34 @@ async function runInit(
   const hasChanges = !(
     requestedTargets.length === 0 &&
     !hasInstructionWrites &&
-    coreSkillIds.length === 0 &&
+    selectedCoreSkillIds.length === 0 &&
     !hasConfigWrite
   );
 
   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)) {
@@ -1096,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`,
+      );
     }
   }
 
@@ -1108,7 +1945,11 @@ async function runInit(
       ...(candidate.state === "full-vault" ? { migrateFullVault: true } : {}),
     };
   });
-  const plannedManifest = planInitManifest(vaultPath, confirmedTargets, coreSkillIds);
+  const plannedManifest = planInitManifest(
+    vaultPath,
+    confirmedTargets,
+    selectedCoreSkillIds,
+  );
   const serializedPlan = {
     vault_path: vaultPath,
     config: configPlan
@@ -1126,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;
@@ -1171,19 +2018,44 @@ async function runInit(
 
   if (!yes) {
     if (!options.isJson && isInteractive()) {
-      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}?`] : []),
-        ...(coreSkillIds.length > 0 ? [`Pin core skills: ${coreSkillIds.join(", ")}?`] : []),
-      ];
-      for (const prompt of prompts) {
-        if (!(await confirmAction(prompt))) {
-          console.log("init cancelled; nothing written");
+      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(
@@ -1214,7 +2086,7 @@ async function runInit(
     if (configCreated && configPlan) rollbackConfigInit(configPlan);
   };
 
-  if (confirmedTargets.length === 0 && coreSkillIds.length === 0) {
+  if (confirmedTargets.length === 0 && selectedCoreSkillIds.length === 0) {
     applyAdditional();
   } else {
     applyInit(
@@ -1226,46 +2098,58 @@ async function runInit(
             rollback: rollbackAdditional,
           }
         : undefined,
-      coreSkillIds,
+      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,
-      },
-    }));
+    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 (coreSkillIds.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 manifest pin <skill_id> --core");
+    console.log("next: skillmux core pin <skill_id> --yes");
   }
   if (confirmedTargets.length > 0) console.log("next: skillmux sync");
-  if (requestedClients.length === 0 || requestedClients.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;
@@ -1284,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}`);
     }
@@ -1292,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;
@@ -1317,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];
@@ -1325,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) {
@@ -1336,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);
 }
 
@@ -1364,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) {
@@ -1375,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++) {
@@ -1428,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"));
@@ -1439,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) {