@klhapp/skillmux 1.10.0 → 1.11.0

package/src/commands/project.ts

@@ -1,7 +1,11 @@
 import { existsSync, lstatSync } from "node:fs";
 import { basename } from "node:path";
 import { expandHome } from "../config";
-import { planClientSurfaces, SUPPORTED_CLIENT_IDS } from "../init-clients";
+import { planAgentSurfaces, SUPPORTED_AGENT_IDS, type AgentId } from "../init-agents";
+import {
+  applyInstructionPlan,
+  planProjectInstructionSetup,
+} from "../init-instructions";
 import {
   parseManifest,
   pinProject,
@@ -12,6 +16,11 @@ import {
   validateManifest,
   writeManifestAtomic,
 } from "../manifest";
+import {
+  MCP_PROJECT_REGISTRABLE_AGENTS,
+  registerMcpServer,
+  type McpRegistrationResult,
+} from "../mcp-registration";
 import { resolveProjectDirectory, suggestProjectName } from "../project-setup";
 import {
   parseCommaList,
@@ -19,18 +28,19 @@ import {
   promptText,
   shouldUseWizard,
 } from "../prompts";
-import { emitSuccess, isInteractive } from "../output";
+import { emitSuccess, isInteractive, unknownSubcommandError } from "../output";
 import { confirmAction, confirmIfNeeded, loadManifestContext } from "./shared";
 import { isGlobalFlag } from "../global-flags";
 const PROJECT_INIT_USAGE =
-  "usage: skillmux project init [path] [--name <group>] [--skill <id>...] [--client <id>...] [--target <name>...] [--yes] [--no-sync]";
+  "usage: skillmux project init [path] [--name <group>] [--skill <id>...] [--agent <id>...] [--target <name>...] [--register-mcp] [--yes] [--no-sync]";
 
 interface ProjectInitArgs {
   path: string;
   name: string;
   skills: string[];
-  clients: string[];
+  agents: string[];
   targets: string[];
+  registerMcp: boolean;
   yes: boolean;
   sync: boolean;
 }
@@ -45,16 +55,16 @@ export function configuredTargetForSurface(
   )?.[0];
 }
 
-function configuredTargetsForClients(
+function configuredTargetsForAgents(
   manifest: ReturnType<typeof parseManifest>,
-  clients: readonly string[],
+  agents: readonly string[],
 ): string[] {
-  return planClientSurfaces(clients).surfaces.map((surface) => {
+  return planAgentSurfaces(agents).surfaces.map((surface) => {
     const target = configuredTargetForSurface(manifest, surface);
     if (target) return target;
-    const client = surface.clients[0]!;
+    const agent = surface.agents[0]!;
     throw new Error(
-      `client target for "${client}" is not configured; run "skillmux init --client ${client} --yes" first`,
+      `agent target for "${agent}" is not configured; run "skillmux init --agent ${agent} --yes" first`,
     );
   });
 }
@@ -63,8 +73,9 @@ function parseProjectInitArgs(args: string[]): ProjectInitArgs {
   let projectPath: string | undefined;
   let name: string | undefined;
   const skills: string[] = [];
-  const clients: string[] = [];
+  const agents: string[] = [];
   const targets: string[] = [];
+  let registerMcp = false;
   let yes = false;
   let sync = true;
 
@@ -81,10 +92,12 @@ function parseProjectInitArgs(args: string[]): ProjectInitArgs {
       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 === "--agent") {
+      const agent = args[++i];
+      if (!agent) throw new Error("--agent requires a name");
+      agents.push(agent);
+    } else if (arg === "--register-mcp") {
+      registerMcp = true;
     } else if (arg === "--yes") {
       yes = true;
     } else if (arg === "--no-sync") {
@@ -110,8 +123,9 @@ function parseProjectInitArgs(args: string[]): ProjectInitArgs {
     path,
     name: name ?? suggestProjectName(basename(path)),
     skills,
-    clients,
+    agents,
     targets,
+    registerMcp,
     yes,
     sync,
   };
@@ -263,15 +277,15 @@ export async function runProject(
     const group = args[0];
     if (!group)
       throw new Error(
-        `usage: skillmux project ${subCommand} <group> (--client <id>... | --target <name>...) --yes`,
+        `usage: skillmux project ${subCommand} <group> (--agent <id>... | --target <name>...) --yes`,
       );
-    const clients: string[] = [];
+    const agents: string[] = [];
     const requestedTargets: string[] = [];
     for (let i = 1; i < args.length; i++) {
-      if (args[i] === "--client") {
+      if (args[i] === "--agent") {
         const value = args[++i];
-        if (!value) throw new Error("--client requires a name");
-        clients.push(value);
+        if (!value) throw new Error("--agent requires a name");
+        agents.push(value);
       } else if (args[i] === "--target") {
         const value = args[++i];
         if (!value) throw new Error("--target requires a name");
@@ -286,11 +300,20 @@ export async function runProject(
     }
     const { config, vaultPath, manifestPath, manifest } =
       await loadManifestContext();
-    const clientTargets = configuredTargetsForClients(manifest, clients);
-    const targets = [...new Set([...requestedTargets, ...clientTargets])];
+    const agentTargets = configuredTargetsForAgents(manifest, agents);
+    const targets = [...new Set([...requestedTargets, ...agentTargets])];
     if (targets.length === 0) {
-      throw new Error(`project ${subCommand} requires --client or --target`);
+      throw new Error(`project ${subCommand} requires --agent or --target`);
     }
+    // Several agents can share one target (e.g. opencode/windsurf both use
+    // agent-skills) — show the resolved directory, not just the target name,
+    // so it's clear at confirmation time which physical folder this affects.
+    const targetDirs = Object.fromEntries(
+      targets.map((t) => [t, manifest.targets[t]?.dir ?? "(unknown)"]),
+    );
+    const targetsDisplay = targets
+      .map((t) => `${t} (${targetDirs[t]})`)
+      .join(", ");
     const updated = updateProjectTargets(manifest, group, {
       ...(subCommand === "attach" ? { attach: targets } : { detach: targets }),
     });
@@ -302,10 +325,10 @@ export async function runProject(
     if (options.dryRun) {
       emitSuccess(
         { isJson: options.isJson },
-        { subcommand: subCommand, group, targets },
+        { subcommand: subCommand, group, targets, target_dirs: targetDirs },
         () =>
           console.log(
-            `${subCommand}: [project.${group}] ${targets.join(", ")} (dry-run)`,
+            `${subCommand}: [project.${group}] ${targetsDisplay} (dry-run)`,
           ),
       );
       return;
@@ -314,7 +337,7 @@ export async function runProject(
       !(await confirmIfNeeded({
         confirmed: args.includes("--yes"),
         isJson: options.isJson,
-        prompt: `${subCommand} [project.${group}] to ${targets.join(", ")}?`,
+        prompt: `${subCommand} [project.${group}] to ${targetsDisplay}?`,
         nonInteractiveError: `skillmux project ${subCommand} requires --yes when run non-interactively`,
       }))
     )
@@ -322,12 +345,23 @@ export async function runProject(
     writeManifestAtomic(manifestPath, updated);
     emitSuccess(
       { isJson: options.isJson },
-      { subcommand: subCommand, group, targets },
-      () => console.log(`${subCommand}: [project.${group}] ${targets.join(", ")}`),
+      { subcommand: subCommand, group, targets, target_dirs: targetDirs },
+      () => console.log(`${subCommand}: [project.${group}] ${targetsDisplay}`),
     );
     return;
   }
-  if (subCommand !== "init") throw new Error(PROJECT_INIT_USAGE);
+  if (subCommand !== "init")
+    throw unknownSubcommandError("project", subCommand, [
+      "init",
+      "list",
+      "show",
+      "add-path",
+      "remove-path",
+      "pin",
+      "unpin",
+      "attach",
+      "detach",
+    ]);
   let request = parseProjectInitArgs(args);
   const guided = shouldUseWizard(args, {
     interactive: isInteractive(),
@@ -345,20 +379,20 @@ export async function runProject(
   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];
+    const availableAgents = SUPPORTED_AGENT_IDS.filter((agent) => {
+      const surface = planAgentSurfaces([agent]).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,
+    const agents = await promptMultiSelect(
+      "Which agents should receive project skills?",
+      availableAgents.map((agent) => ({
+        value: agent,
+        label: agent,
         selected:
-          request.clients.length === 0 || request.clients.includes(client),
+          request.agents.length === 0 || request.agents.includes(agent),
       })),
     );
     const skills = parseCommaList(
@@ -367,10 +401,25 @@ export async function runProject(
         request.skills.join(","),
       ),
     );
-    request = { ...request, name, clients, skills };
+    request = { ...request, name, agents, skills };
   }
-  const clientTargets = configuredTargetsForClients(manifest, request.clients);
-  const targets = [...new Set([...request.targets, ...clientTargets])];
+  // Local MCP registration + instruction writing are independent of skill
+  // pins — only offered for agents with a verified project-scoped CLI
+  // command (currently just claude-code; see MCP_PROJECT_REGISTRABLE_AGENTS).
+  const registrableAgents = request.agents.filter((agent) =>
+    MCP_PROJECT_REGISTRABLE_AGENTS.includes(agent as AgentId),
+  ) as AgentId[];
+  if (guided && registrableAgents.length > 0) {
+    request = {
+      ...request,
+      registerMcp: await confirmAction(
+        `Also register skillmux as a project-scoped MCP server for ${registrableAgents.join(", ")}? ` +
+          `This writes ${request.path}/.mcp.json, shared via git.`,
+      ),
+    };
+  }
+  const agentTargets = configuredTargetsForAgents(manifest, request.agents);
+  const targets = [...new Set([...request.targets, ...agentTargets])];
   const updated = upsertProject(manifest, {
     name: request.name,
     paths: [request.path],
@@ -378,15 +427,34 @@ export async function runProject(
     targets,
   });
   const { notes } = validateManifest(updated, vaultPath, localVaultPaths);
+
+  // The project-local instruction block only teaches an agent to call
+  // resolve_skill/fetch_skill (MCP tools) — write it only for agents that
+  // are actually getting a project-scoped MCP registration this run.
+  const mcpInstructionAgents = request.registerMcp ? registrableAgents : [];
+  const instructionPlan = planProjectInstructionSetup(
+    mcpInstructionAgents,
+    request.path,
+  );
+  const hasInstructionWrites = instructionPlan.changes.some(
+    (change) => change.status !== "unchanged",
+  );
+
   const plan = {
     mode: "project",
     project: request.name,
     path: request.path,
     skills: request.skills,
-    clients: request.clients,
+    agents: request.agents,
     targets,
     sync: request.sync,
     notes,
+    instructions: instructionPlan.changes.map(({ path, agents, status }) => ({
+      path,
+      agents,
+      status,
+    })),
+    register_mcp_for: mcpInstructionAgents,
   };
 
   if (options.dryRun) {
@@ -401,8 +469,14 @@ export async function runProject(
         console.log("\nReview");
         console.log(`  project: ${request.name}`);
         console.log(`  path: ${request.path}`);
-        console.log(`  clients: ${request.clients.join(", ") || "(none)"}`);
+        console.log(`  agents: ${request.agents.join(", ") || "(none)"}`);
         console.log(`  skills: ${request.skills.join(", ") || "(none)"}`);
+        console.log(
+          `  instructions: ${instructionPlan.changes.filter((change) => change.status !== "unchanged").length} file(s)`,
+        );
+        console.log(
+          `  MCP registration: ${mcpInstructionAgents.join(", ") || "(none)"}`,
+        );
         console.log(`  sync: ${request.sync ? "yes" : "no"}`);
       }
       if (
@@ -421,6 +495,17 @@ export async function runProject(
   }
 
   writeManifestAtomic(manifestPath, updated);
+  if (hasInstructionWrites) {
+    try {
+      applyInstructionPlan(instructionPlan);
+    } catch (error) {
+      throw new Error(
+        `project configuration was saved, but writing instruction files failed: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      );
+    }
+  }
   if (request.sync) {
     try {
       // Reaching here already required approval above (request.yes, or an
@@ -437,7 +522,39 @@ export async function runProject(
       );
     }
   }
-  emitSuccess({ isJson: options.isJson }, { result: plan }, () =>
-    console.log(`project "${request.name}" ready at ${request.path}`),
+
+  // Best-effort and outside the checks above: this mutates another tool's
+  // own config, not skillmux's, so a registration failure is reported, never
+  // rolled back — the successful project setup above still stands either way.
+  const mcpRegistrations: McpRegistrationResult[] = [];
+  if (request.registerMcp) {
+    for (const agent of registrableAgents) {
+      mcpRegistrations.push(
+        await registerMcpServer(agent, { scope: "project", cwd: request.path }),
+      );
+    }
+  }
+
+  emitSuccess(
+    { isJson: options.isJson },
+    {
+      result: {
+        ...plan,
+        instructions_changed: instructionPlan.changes
+          .filter((change) => change.status !== "unchanged")
+          .map((change) => change.path),
+        mcp_registrations: mcpRegistrations,
+      },
+    },
+    () => {
+      console.log(`project "${request.name}" ready at ${request.path}`);
+      for (const registration of mcpRegistrations) {
+        console.log(
+          registration.ok
+            ? `MCP registered: ${registration.agent} (project scope)`
+            : `MCP registration failed for ${registration.agent}: ${registration.error}`,
+        );
+      }
+    },
   );
 }

package/src/commands/report.ts

@@ -1,5 +1,5 @@
 import { Database } from "bun:sqlite";
-import type { TargetAdapter } from "../adapters";
+import type { ContextAdapter } from "../adapters";
 import type { ResolvedContext } from "../context";
 import { emitSuccess } from "../output";
 import { getStats, renderStatsText } from "../stats";
@@ -36,14 +36,14 @@ function parseReportArgs(args: string[]): {
 
 export async function runReport(
   args: string[],
-  options: { isJson: boolean; target: ResolvedContext; allowInsecure: boolean; adapter: TargetAdapter },
+  options: { isJson: boolean; context: ResolvedContext; allowInsecure: boolean; adapter: ContextAdapter },
 ): Promise<void> {
   const { db: dbPath, since } = parseReportArgs(args);
   if (!since)
     throw new Error(
       "usage: skillmux report [--context <name> | --server <url> | --db <path>] --since <window> [--json]",
     );
-  if (dbPath && options.target.type === "remote")
+  if (dbPath && options.context.type === "remote")
     throw new Error("--db and --context/--server are mutually exclusive");
 
   if (dbPath) {

package/src/commands/shared.ts

@@ -1,21 +1,14 @@
-import { createInterface } from "node:readline/promises";
 import { expandHome, loadConfig } from "../config";
 import { parseManifest, resolveManifestPath } from "../manifest";
 import { isInteractive } from "../output";
+import { askQuestion, type PromptIO } from "../prompts";
 
-export async function confirmAction(prompt: string): Promise<boolean> {
-  const readline = createInterface({
-    input: process.stdin,
-    output: process.stdout,
-  });
-  try {
-    const answer = (await readline.question(`${prompt} [y/N] `))
-      .trim()
-      .toLowerCase();
-    return answer === "y" || answer === "yes";
-  } finally {
-    readline.close();
-  }
+export async function confirmAction(
+  prompt: string,
+  io: PromptIO = {},
+): Promise<boolean> {
+  const answer = (await askQuestion(`${prompt} [y/N] `, io)).trim().toLowerCase();
+  return answer === "y" || answer === "yes";
 }
 
 export async function loadManifestContext() {

package/src/commands/skill.ts

@@ -1,10 +1,11 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { expandHome, loadConfig } from "../config";
+import { unknownSubcommandError } from "../output";
 import { vaultResolutionOrder } from "../vault";
 
 export async function runSkill(subCommand: string, args: string[]): Promise<void> {
-  if (subCommand !== "which") throw new Error("usage: skillmux skill <which>");
+  if (subCommand !== "which") throw unknownSubcommandError("skill", subCommand, ["which"]);
   await runWhich(args);
 }
 

package/src/commands/target.ts

@@ -1,9 +1,15 @@
 import { expandHome } from "../config";
-import { planClientSurfaces, SUPPORTED_CLIENT_IDS } from "../init-clients";
+import {
+  BUILT_IN_TARGET_NAMES,
+  planAgentSurfaces,
+  resolveBuiltInTarget,
+  SUPPORTED_AGENT_IDS,
+} from "../init-agents";
 import { planInitManifest, applyInit } from "../init";
 import { writeManifestAtomic } from "../manifest";
-import { emitSuccess } from "../output";
+import { emitSuccess, unknownSubcommandError } from "../output";
 import { confirmIfNeeded, loadManifestContext } from "./shared";
+
 export async function runTarget(
   subCommand: string,
   args: string[],
@@ -19,11 +25,11 @@ export async function runTarget(
     }
     const targets = names.map((name) => {
       const target = manifest.targets[name]!;
-      const clients = SUPPORTED_CLIENT_IDS.filter((client) => {
-        const surface = planClientSurfaces([client]).surfaces[0];
+      const agents = SUPPORTED_AGENT_IDS.filter((agent) => {
+        const surface = planAgentSurfaces([agent]).surfaces[0];
         return surface !== undefined && surface.path === expandHome(target.dir);
       });
-      return { name, ...target, clients };
+      return { name, ...target, agents };
     });
     emitSuccess({ isJson: options.isJson }, { targets }, () => {
       if (targets.length === 0) {
@@ -33,7 +39,7 @@ export async function runTarget(
           console.log(`${target.name}:`);
           console.log(`  dir: ${target.dir}`);
           console.log(`  host: ${target.host ?? "(global)"}`);
-          console.log(`  clients: ${target.clients.join(", ") || "(custom)"}`);
+          console.log(`  agents: ${target.agents.join(", ") || "(custom)"}`);
           console.log(
             `  projects: ${target.project_groups.join(", ") || "(none)"}`,
           );
@@ -47,9 +53,21 @@ export async function runTarget(
     const name = args[0];
     const dirIndex = args.indexOf("--dir");
     const rawPath = dirIndex === -1 ? undefined : args[dirIndex + 1];
-    if (!name || !rawPath)
+    if (!name)
       throw new Error("usage: skillmux target add <name> --dir <dir> --yes");
-    const path = expandHome(rawPath);
+
+    let path: string;
+    if (rawPath) {
+      path = expandHome(rawPath);
+    } else if (BUILT_IN_TARGET_NAMES.has(name)) {
+      path = resolveBuiltInTarget(name, {
+        codexHome: process.env.CODEX_HOME ? expandHome(process.env.CODEX_HOME) : undefined,
+      }).path;
+    } else {
+      throw new Error(
+        "usage: skillmux target add <name> --dir <dir> --yes  (--dir may be omitted for built-in target names: agent-skills, claude-code, codex)",
+      );
+    }
     if (options.dryRun) {
       const planned = planInitManifest(vaultPath, [{ name, dir: path }], []);
       emitSuccess(
@@ -118,5 +136,5 @@ export async function runTarget(
     return;
   }
 
-  throw new Error("usage: skillmux target <list|show|add|remove>");
+  throw unknownSubcommandError("target", subCommand, ["list", "show", "add", "remove"]);
 }

package/src/completions.ts

@@ -1,3 +1,5 @@
+import { MANAGED_PINS_AGENT_IDS, SUPPORTED_AGENT_IDS } from "./init-agents";
+
 export type ShellType = "bash" | "zsh" | "fish";
 
 const TOP_LEVEL_COMMANDS: { name: string; description: string }[] = [
@@ -6,7 +8,7 @@ const TOP_LEVEL_COMMANDS: { name: string; description: string }[] = [
   { name: "serve", description: "Start MCP server" },
   { name: "index", description: "Rebuild local search index" },
   { name: "sync", description: "Synchronize vault skills" },
-  { name: "init", description: "Configure this machine and its clients" },
+  { name: "init", description: "Configure this machine and its agents" },
   { name: "project", description: "Configure project-scoped skills" },
   { name: "target", description: "Manage advanced skill-delivery targets" },
   { name: "core", description: "Pin/unpin skills into [core]" },
@@ -62,18 +64,25 @@ _skillmux_completions() {
         local-vault)
             COMPREPLY=( $(compgen -W "init" -- "$cur") )
             ;;
-        --client)
-            COMPREPLY=( $(compgen -W "claude-code codex gemini-cli opencode github-copilot windsurf antigravity goose hermes skillmux-mcp" -- "$cur") )
+        eval)
+            COMPREPLY=( $(compgen -W "promote" -- "$cur") )
             ;;
-        --target)
-            COMPREPLY=( $(compgen -W "agent-skills claude-code codex custom" -- "$cur") )
+        --agent)
+            if [ "\${COMP_WORDS[1]}" = "project" ]; then
+                COMPREPLY=( $(compgen -W "${MANAGED_PINS_AGENT_IDS.join(" ")}" -- "$cur") )
+            else
+                COMPREPLY=( $(compgen -W "${SUPPORTED_AGENT_IDS.join(" ")}" -- "$cur") )
+            fi
             ;;
     esac
     if [ "\${COMP_WORDS[1]}" = "init" ] && [ "\${#COMPREPLY[@]}" -eq 0 ]; then
-        COMPREPLY=( $(compgen -W "--client --target --dir --vault --core --migrate-full-vault --no-instructions --no-sync --interactive --yes --dry-run --json" -- "$cur") )
+        COMPREPLY=( $(compgen -W "--agent --vault --core --migrate-full-vault --show-mcp-setup --register-mcp --no-instructions --no-sync --interactive --yes --dry-run --json" -- "$cur") )
     fi
     if [ "\${COMP_WORDS[1]}" = "project" ] && [ "\${COMP_WORDS[2]}" = "init" ]; then
-        COMPREPLY=( $(compgen -W "--name --skill --client --target --no-sync --interactive --yes --dry-run --json" -- "$cur") )
+        COMPREPLY=( $(compgen -W "--name --skill --agent --target --register-mcp --no-sync --interactive --yes --dry-run --json" -- "$cur") )
+    fi
+    if [ "\${COMP_WORDS[1]}" = "eval" ] && [ "\${COMP_WORDS[2]}" = "promote" ]; then
+        COMPREPLY=( $(compgen -W "--since --out --dry-run --yes --json" -- "$cur") )
     fi
 }
 complete -F _skillmux_completions skillmux
@@ -92,12 +101,12 @@ ${commands}
         _describe -t commands 'skillmux command' commands
     elif [[ "$words[2]" == "init" ]]; then
         _arguments \\
-          '*--client[select a client]:client:(claude-code codex gemini-cli opencode github-copilot windsurf antigravity goose hermes skillmux-mcp)' \\
-          '*--target[select a delivery target]:target:(agent-skills claude-code codex custom)' \\
-          '--dir[custom target directory]:directory:_directories' \\
+          '*--agent[select an agent]:agent:(${SUPPORTED_AGENT_IDS.join(" ")})' \\
           '--vault[vault directory]:directory:_directories' \\
           '*--core[seed a core skill]:skill id:' \\
           '--migrate-full-vault[convert a full-vault symlink to managed pins]' \\
+          '--show-mcp-setup[also print the MCP registration snippet]' \\
+          '--register-mcp[register skillmux via the agent own CLI]' \\
           '--no-instructions[skip managed instruction files]' \\
           '--no-sync[save setup without synchronizing targets]' \\
           '--interactive[force guided setup]' \\
@@ -109,8 +118,9 @@ ${commands}
           '1:project directory:_directories' \\
           '--name[project group name]:group:' \\
           '*--skill[project skill]:skill id:' \\
-          '*--client[select a client]:client:(claude-code codex gemini-cli opencode github-copilot windsurf antigravity)' \\
+          '*--agent[select an agent]:agent:(${MANAGED_PINS_AGENT_IDS.join(" ")})' \\
           '*--target[select an advanced target]:target:' \\
+          '--register-mcp[register a project-scoped MCP server for claude-code]' \\
           '--no-sync[save setup without synchronizing targets]' \\
           '--interactive[force guided setup]' \\
           '--yes[apply without prompts]' \\
@@ -118,6 +128,15 @@ ${commands}
           '--json[emit a JSON envelope]'
     elif [[ "$words[2]" == "project" && CURRENT == 3 ]]; then
         _values 'project command' init list show add-path remove-path pin unpin attach detach
+    elif [[ "$words[2]" == "eval" && "$words[3]" == "promote" ]]; then
+        _arguments \
+          '--since[time window]:window:' \
+          '--out[output file]:file:_files' \
+          '--dry-run[print the plan without writing]' \
+          '--yes[apply without prompts]' \
+          '--json[emit a JSON envelope]'
+    elif [[ "$words[2]" == "eval" && CURRENT == 3 ]]; then
+        _values 'eval command' promote
     elif [[ "$words[2]" == "target" && CURRENT == 3 ]]; then
         _values 'target command' list show add remove
     elif [[ "$words[2]" == "skill" && CURRENT == 3 ]]; then
@@ -139,12 +158,12 @@ _skillmux "$@"
     return `# fish completion for skillmux
 complete -c skillmux -f
 ${topLevel}
-complete -c skillmux -n "__fish_seen_subcommand_from init" -l client -x -a "claude-code codex gemini-cli opencode github-copilot windsurf antigravity goose hermes skillmux-mcp" -d "Select a client"
-complete -c skillmux -n "__fish_seen_subcommand_from init" -l target -x -a "agent-skills claude-code codex custom" -d "Select a delivery target"
-complete -c skillmux -n "__fish_seen_subcommand_from init" -l dir -r -d "Custom target directory"
+complete -c skillmux -n "__fish_seen_subcommand_from init" -l agent -x -a "${SUPPORTED_AGENT_IDS.join(" ")}" -d "Select an agent"
 complete -c skillmux -n "__fish_seen_subcommand_from init" -l vault -r -d "Vault directory"
 complete -c skillmux -n "__fish_seen_subcommand_from init" -l core -x -d "Seed a core skill"
 complete -c skillmux -n "__fish_seen_subcommand_from init" -l migrate-full-vault -d "Convert a full-vault symlink"
+complete -c skillmux -n "__fish_seen_subcommand_from init" -l show-mcp-setup -d "Also print the MCP registration snippet"
+complete -c skillmux -n "__fish_seen_subcommand_from init" -l register-mcp -d "Register skillmux via the agent's own CLI"
 complete -c skillmux -n "__fish_seen_subcommand_from init" -l no-instructions -d "Skip managed instruction files"
 complete -c skillmux -n "__fish_seen_subcommand_from init" -l no-sync -d "Save without synchronizing"
 complete -c skillmux -n "__fish_seen_subcommand_from init" -l interactive -d "Force guided setup"
@@ -154,11 +173,18 @@ complete -c skillmux -n "__fish_seen_subcommand_from init" -l json -d "Emit a JS
 complete -c skillmux -n "__fish_seen_subcommand_from project" -a "init list show add-path remove-path pin unpin attach detach" -d "Manage projects"
 complete -c skillmux -n "__fish_seen_subcommand_from project" -l name -x -d "Project group name"
 complete -c skillmux -n "__fish_seen_subcommand_from project" -l skill -x -d "Project skill"
-complete -c skillmux -n "__fish_seen_subcommand_from project" -l client -x -a "claude-code codex gemini-cli opencode github-copilot windsurf antigravity" -d "Select a client"
+complete -c skillmux -n "__fish_seen_subcommand_from project" -l agent -x -a "${MANAGED_PINS_AGENT_IDS.join(" ")}" -d "Select an agent"
 complete -c skillmux -n "__fish_seen_subcommand_from project" -l target -x -d "Select an advanced delivery target"
+complete -c skillmux -n "__fish_seen_subcommand_from project" -l register-mcp -d "Register a project-scoped MCP server for claude-code"
 complete -c skillmux -n "__fish_seen_subcommand_from project" -l no-sync -d "Save without synchronizing"
 complete -c skillmux -n "__fish_seen_subcommand_from project" -l interactive -d "Force guided setup"
 complete -c skillmux -n "__fish_seen_subcommand_from project" -l yes -d "Apply without prompts"
+complete -c skillmux -n "__fish_seen_subcommand_from eval" -a "promote" -d "Promote correlated fetches into eval cases"
+complete -c skillmux -n "__fish_seen_subcommand_from eval; and __fish_seen_subcommand_from promote" -l since -x -d "Time window"
+complete -c skillmux -n "__fish_seen_subcommand_from eval; and __fish_seen_subcommand_from promote" -l out -r -d "Output file"
+complete -c skillmux -n "__fish_seen_subcommand_from eval; and __fish_seen_subcommand_from promote" -l dry-run -d "Print the plan without writing"
+complete -c skillmux -n "__fish_seen_subcommand_from eval; and __fish_seen_subcommand_from promote" -l yes -d "Apply without prompts"
+complete -c skillmux -n "__fish_seen_subcommand_from eval; and __fish_seen_subcommand_from promote" -l json -d "Emit a JSON envelope"
 complete -c skillmux -n "__fish_seen_subcommand_from target" -a "list show add remove" -d "Manage targets"
 complete -c skillmux -n "__fish_seen_subcommand_from core" -a "pin unpin" -d "Manage [core] pins"
 complete -c skillmux -n "__fish_seen_subcommand_from skill" -a "which" -d "Show which root resolves a skill_id"

package/src/config-service.ts

@@ -309,7 +309,7 @@ export async function getDottedKey(key: string, configPath?: string): Promise<un
 export async function setDottedKey(
   key: string,
   rawValStr: string,
-  opts?: { configPath?: string; dryRun?: boolean; targetName?: string }
+  opts?: { configPath?: string; dryRun?: boolean; contextName?: string }
 ): Promise<SetConfigResult> {
   validateDottedKey(key);
   if (isEnvMasked(key)) {
@@ -317,7 +317,7 @@ export async function setDottedKey(
   }
 
   const path = opts?.configPath ?? process.env.SKILLMUX_CONFIG ?? DEFAULT_CONFIG_PATH;
-  const targetName = opts?.targetName ?? "local";
+  const contextName = opts?.contextName ?? "local";
 
   const { effective: priorEffective, rawToml } = await getEffectiveConfig(path);
   const priorVal = getNestedValue(priorEffective as Record<string, any>, key);
@@ -364,7 +364,7 @@ export async function setDottedKey(
     key,
     prior_val: priorVal,
     resulting_val: parsedVal,
-    target: targetName,
+    target: contextName,
     prior_revision: priorRevision,
     resulting_revision: resultingRevision,
     persistence,