@klhapp/skillmux 1.10.0 → 1.11.1

package/src/mcp-registration.ts

@@ -0,0 +1,89 @@
+import {
+  getAgentDefinition,
+  SUPPORTED_AGENT_IDS,
+  type AgentId,
+  type McpRegistrationScope,
+} from "./init-agents";
+
+export type { McpRegistrationScope };
+
+export const MCP_REGISTRABLE_AGENTS = SUPPORTED_AGENT_IDS.filter(
+  (agent) => getAgentDefinition(agent).mcpRegistration !== undefined,
+);
+
+export const MCP_PROJECT_REGISTRABLE_AGENTS = MCP_REGISTRABLE_AGENTS.filter(
+  (agent) => getAgentDefinition(agent).mcpRegistration!.buildArgs("project") !== undefined,
+);
+
+export function isMcpRegistrable(agent: AgentId): boolean {
+  return getAgentDefinition(agent).mcpRegistration !== undefined;
+}
+
+export interface McpRegistrationResult {
+  agent: AgentId;
+  ok: boolean;
+  error?: string;
+}
+
+type SpawnFn = (
+  cmd: string[],
+  opts?: { cwd?: string },
+) => {
+  exited: Promise<number>;
+  stderr: ReadableStream<Uint8Array> | number;
+};
+
+/**
+ * Runs the agent's own CLI to register skillmux as an MCP server. Never
+ * throws — registration failure (tool not installed, command rejected,
+ * etc.) is reported in the result, not fatal to the caller's larger flow.
+ */
+export async function registerMcpServer(
+  agent: AgentId,
+  options: {
+    spawn?: SpawnFn;
+    scope?: McpRegistrationScope;
+    cwd?: string;
+  } = {},
+): Promise<McpRegistrationResult> {
+  const entry = getAgentDefinition(agent).mcpRegistration;
+  const scope = options.scope ?? "user";
+  const args = entry?.buildArgs(scope);
+  if (!entry || !args) {
+    return {
+      agent,
+      ok: false,
+      error: `no ${scope === "project" ? "project-scoped " : ""}MCP registration command known for agent "${agent}"`,
+    };
+  }
+  const spawn: SpawnFn =
+    options.spawn ??
+    ((cmd, opts) => Bun.spawn(cmd, { stdout: "pipe", stderr: "pipe", cwd: opts?.cwd }));
+  try {
+    const proc = spawn([entry.command, ...args], { cwd: options.cwd });
+    const stderrText =
+      typeof proc.stderr === "number"
+        ? ""
+        : await new Response(proc.stderr).text();
+    const exitCode = await proc.exited;
+    if (exitCode !== 0) {
+      return {
+        agent,
+        ok: false,
+        error:
+          stderrText.trim() || `${entry.command} exited with code ${exitCode}`,
+      };
+    }
+    return { agent, ok: true };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const notFound = /ENOENT|not found|no such file/i.test(message);
+    return {
+      agent,
+      ok: false,
+      error: notFound
+        ? `"${entry.command}" is not installed or not on PATH`
+        : message,
+    };
+  }
+}

package/src/output.ts

@@ -3,6 +3,8 @@ import type { ResolvedContext } from "./context";
 export interface JsonEnvelope<T = any> {
   schema_version: 1;
   ok: boolean;
+  context: string | { name: string; server: string };
+  /** @deprecated Use `context` instead. Retained as a compatibility alias; no removal planned. */
   target: string | { name: string; server: string };
   data: T | null;
   error: { code: string; message: string; details?: any } | null;
@@ -10,27 +12,34 @@ export interface JsonEnvelope<T = any> {
 
 export function formatJsonEnvelope<T>(opts: {
   ok: boolean;
-  target: ResolvedContext | string | { name: string; server: string };
+  /** @deprecated Use `context` instead. Retained as a compatibility alias; no removal planned. */
+  target?: ResolvedContext | string | { name: string; server: string };
+  context?: ResolvedContext | string | { name: string; server: string };
   data?: T;
   error?: { code: string; message: string; details?: any } | null;
 }): JsonEnvelope<T> {
-  let targetVal: string | { name: string; server: string };
-  if (typeof opts.target === "string" || (typeof opts.target === "object" && "server" in opts.target && !("type" in opts.target))) {
-    targetVal = opts.target as any;
-  } else if (typeof opts.target === "object" && "type" in opts.target) {
-    if (opts.target.type === "local") {
-      targetVal = "local";
+  const input: ResolvedContext | string | { name: string; server: string } =
+    opts.context ?? opts.target ?? "local";
+  let contextVal: string | { name: string; server: string };
+  if (typeof input === "string") {
+    contextVal = input;
+  } else if (typeof input === "object" && input !== null) {
+    if ("type" in input && (input as any).type === "local") {
+      contextVal = "local";
+    } else if ("name" in input && "server" in input) {
+      contextVal = { name: input.name, server: input.server };
     } else {
-      targetVal = { name: opts.target.name, server: opts.target.server };
+      contextVal = "local";
     }
   } else {
-    targetVal = "local";
+    contextVal = "local";
   }
 
   return {
     schema_version: 1,
     ok: opts.ok,
-    target: targetVal,
+    context: contextVal,
+    target: contextVal,
     data: opts.data ?? null,
     error: opts.error ?? null,
   };
@@ -51,12 +60,18 @@ export class CliError extends Error {
 }
 
 export function emitSuccess<T>(
-  ctx: { isJson: boolean; target?: ResolvedContext | string | { name: string; server: string } },
+  ctx: {
+    isJson: boolean;
+    /** @deprecated Use `context` instead. Retained as a compatibility alias; no removal planned. */
+    target?: ResolvedContext | string | { name: string; server: string };
+    context?: ResolvedContext | string | { name: string; server: string };
+  },
   data: T,
   renderText: () => void,
 ): void {
   if (ctx.isJson) {
-    console.log(JSON.stringify(formatJsonEnvelope({ ok: true, target: ctx.target ?? "local", data })));
+    const contextVal = ctx.context ?? ctx.target ?? "local";
+    console.log(JSON.stringify(formatJsonEnvelope({ ok: true, context: contextVal, target: contextVal, data })));
   } else {
     renderText();
   }
@@ -112,6 +127,28 @@ export function suggestCorrection(input: string, candidates: string[]): string |
   return bestMatch;
 }
 
+/**
+ * Builds the error for an unrecognized subcommand: "did you mean X" when
+ * close to a valid one, otherwise the full <a|b|c> usage list — never a
+ * fixed, possibly-unrelated usage string for just one of several valid
+ * subcommands (that's what `config`'s fallback used to do before this
+ * existed: any invalid subcommand got told "usage: skillmux config show",
+ * silently omitting get/set/validate/diff/status/init).
+ */
+export function unknownSubcommandError(
+  command: string,
+  subCommand: string,
+  validSubcommands: string[],
+): Error {
+  const suggestion = subCommand ? suggestCorrection(subCommand, validSubcommands) : null;
+  if (suggestion) {
+    return new Error(
+      `Unknown "${command} ${subCommand}" subcommand. Did you mean "${command} ${suggestion}"?`,
+    );
+  }
+  return new Error(`usage: skillmux ${command} <${validSubcommands.join("|")}>`);
+}
+
 export function isInteractive(
   env: NodeJS.ProcessEnv = process.env,
   stdoutIsTTY = process.stdout.isTTY,
@@ -144,12 +181,12 @@ export function warn(line: string): void {
   console.error(yellow(`warning: ${line}`));
 }
 
-export function renderTargetBanner(target: ResolvedContext): void {
+export function renderContextBanner(context: ResolvedContext): void {
   if (!isInteractive()) return;
-  if (target.type === "local") {
-    console.log(`Target: local`);
+  if (context.type === "local") {
+    console.log(`Context: local`);
   } else {
-    console.log(`Target: remote (${target.name} -> ${target.server})`);
+    console.log(`Context: remote (${context.name} -> ${context.server})`);
   }
 }
 

package/src/prompts.ts

@@ -1,4 +1,63 @@
 import { createInterface } from "node:readline/promises";
+import type { Readable, Writable } from "node:stream";
+
+/**
+ * Streams a prompt reads from and writes to. Injectable so prompts can be
+ * tested without a terminal; defaults to the real process streams.
+ */
+export interface PromptIO {
+  input?: Readable;
+  output?: Writable;
+}
+
+export const NO_INPUT_ERROR = "no input available on stdin; re-run with --yes";
+
+/**
+ * Asks one question and resolves with the raw answer.
+ *
+ * `isInteractive()` only inspects stdout, so a caller can legitimately reach a
+ * prompt while stdin is already at EOF (a pty'd stdout under CI, a wrapper
+ * process, `skillmux init < /dev/null`). A bare `readline.question()` never
+ * settles in that case and the CLI hangs forever, so the input stream ending
+ * before an answer arrives is turned into an actionable error instead.
+ *
+ * Piped answers (`printf 'y\n' | skillmux ...`) still work: `close` only wins
+ * the race when the stream ends with the question still outstanding.
+ */
+export async function askQuestion(query: string, io: PromptIO = {}): Promise<string> {
+  const readline = createInterface({
+    input: io.input ?? process.stdin,
+    output: io.output ?? process.stdout,
+  });
+  let settled = false;
+  try {
+    return await new Promise<string>((resolve, reject) => {
+      readline.question(query).then(
+        (answer) => {
+          settled = true;
+          resolve(answer);
+        },
+        (error) => {
+          settled = true;
+          reject(error);
+        },
+      );
+      // Fires on EOF, and also from the `finally` below. A piped stream ends
+      // immediately after delivering its answer, so `close` can arrive before
+      // the resolution microtask runs — deferring past pending microtasks lets
+      // a real answer win the race, leaving only a genuine EOF to reject.
+      readline.once("close", () => {
+        setImmediate(() => {
+          if (settled) return;
+          settled = true;
+          reject(new Error(NO_INPUT_ERROR));
+        });
+      });
+    });
+  } finally {
+    readline.close();
+  }
+}
 
 export interface SelectOption<T extends string> {
   value: T;
@@ -35,35 +94,31 @@ export function shouldUseWizard(
 export async function promptMultiSelect<T extends string>(
   question: string,
   options: readonly SelectOption<T>[],
+  io: PromptIO = {},
 ): Promise<T[]> {
-  console.log(`\n${question}`);
+  const output = io.output ?? process.stdout;
+  output.write(`\n${question}\n`);
   options.forEach((option, index) => {
     const checked = option.selected ? "x" : " ";
     const detail = option.detail ? `  ${option.detail}` : "";
-    console.log(`  ${index + 1}. [${checked}] ${option.label}${detail}`);
+    output.write(`  ${index + 1}. [${checked}] ${option.label}${detail}\n`);
   });
   const defaults = options
     .map((option, index) => option.selected ? String(index + 1) : "")
     .filter(Boolean)
     .join(",");
-  const readline = createInterface({ input: process.stdin, output: process.stdout });
-  try {
-    const suffix = defaults ? ` [${defaults}]` : "";
-    const answer = await readline.question(`Select numbers, comma-separated${suffix}: `);
-    const selection = answer.trim() === "" && defaults ? defaults : answer;
-    return parseNumberSelection(selection, options.length).map((index) => options[index]!.value);
-  } finally {
-    readline.close();
-  }
+  const suffix = defaults ? ` [${defaults}]` : "";
+  const answer = await askQuestion(`Select numbers, comma-separated${suffix}: `, io);
+  const selection = answer.trim() === "" && defaults ? defaults : answer;
+  return parseNumberSelection(selection, options.length).map((index) => options[index]!.value);
 }
 
-export async function promptText(question: string, defaultValue = ""): Promise<string> {
-  const readline = createInterface({ input: process.stdin, output: process.stdout });
-  try {
-    const suffix = defaultValue ? ` [${defaultValue}]` : "";
-    const answer = (await readline.question(`${question}${suffix}: `)).trim();
-    return answer || defaultValue;
-  } finally {
-    readline.close();
-  }
+export async function promptText(
+  question: string,
+  defaultValue = "",
+  io: PromptIO = {},
+): Promise<string> {
+  const suffix = defaultValue ? ` [${defaultValue}]` : "";
+  const answer = (await askQuestion(`${question}${suffix}: `, io)).trim();
+  return answer || defaultValue;
 }

package/src/scan.ts

@@ -156,7 +156,7 @@ export interface ScanResult {
   findings: ScanFinding[];
 }
 
-interface ScanContentTarget {
+interface ScanContentFile {
   skill_id: string;
   file: string;
   content: string;
@@ -177,21 +177,21 @@ export async function readTextFileOrNull(path: string): Promise<string | null> {
   }
 }
 
-async function collectSkillTargets(
+async function collectSkillFiles(
   vaultPath: string,
   skillId: string,
   skillMdBody: string,
-): Promise<ScanContentTarget[]> {
-  const targets: ScanContentTarget[] = [{ skill_id: skillId, file: "SKILL.md", content: skillMdBody }];
+): Promise<ScanContentFile[]> {
+  const files: ScanContentFile[] = [{ skill_id: skillId, file: "SKILL.md", content: skillMdBody }];
   for (const rel of listSupportingFiles(vaultPath, skillId)) {
     const content = await readTextFileOrNull(join(vaultPath, skillId, rel));
-    if (content !== null) targets.push({ skill_id: skillId, file: rel, content });
+    if (content !== null) files.push({ skill_id: skillId, file: rel, content });
   }
-  return targets;
+  return files;
 }
 
-interface ResolvedScanTargets {
-  targets: ScanContentTarget[];
+interface ResolvedScanFiles {
+  files: ScanContentFile[];
   /** skill_ids whose SKILL.md could not be parsed/decoded — must still be counted and
    *  flagged, never silently dropped, or a malformed SKILL.md becomes a scan-evasion trick. */
   unparseable: string[];
@@ -199,32 +199,32 @@ interface ResolvedScanTargets {
 
 /** Single-skill-dir mode when `rootPath` itself holds a SKILL.md; otherwise treats
  *  `rootPath` as a vault root and enumerates every skill dir under it. */
-async function resolveScanTargets(rootPath: string): Promise<ResolvedScanTargets> {
+async function resolveScanFiles(rootPath: string): Promise<ResolvedScanFiles> {
   if (existsSync(join(rootPath, "SKILL.md"))) {
     const skillId = basename(rootPath);
     const vaultPath = dirname(rootPath);
     const body = await readTextFileOrNull(join(rootPath, "SKILL.md"));
-    if (body === null) return { targets: [], unparseable: [skillId] };
-    return { targets: await collectSkillTargets(vaultPath, skillId, body), unparseable: [] };
+    if (body === null) return { files: [], unparseable: [skillId] };
+    return { files: await collectSkillFiles(vaultPath, skillId, body), unparseable: [] };
   }
 
   const unparseable: string[] = [];
   const skills = await scanVault(rootPath, (skillId) => unparseable.push(skillId));
-  const targets: ScanContentTarget[] = [];
+  const files: ScanContentFile[] = [];
   for (const skill of skills) {
-    targets.push(...(await collectSkillTargets(rootPath, skill.skill_id, skill.body)));
+    files.push(...(await collectSkillFiles(rootPath, skill.skill_id, skill.body)));
   }
-  return { targets, unparseable };
+  return { files, unparseable };
 }
 
 export async function scanPath(rootPath: string): Promise<ScanResult> {
-  const { targets, unparseable } = await resolveScanTargets(rootPath);
+  const { files, unparseable } = await resolveScanFiles(rootPath);
   const findings: ScanFinding[] = [];
   const skillIds = new Set<string>();
-  for (const target of targets) {
-    skillIds.add(target.skill_id);
-    for (const match of scanContent(target.content)) {
-      findings.push({ ...match, skill_id: target.skill_id, file: target.file });
+  for (const file of files) {
+    skillIds.add(file.skill_id);
+    for (const match of scanContent(file.content)) {
+      findings.push({ ...match, skill_id: file.skill_id, file: file.file });
     }
   }
   for (const skillId of unparseable) {
@@ -264,3 +264,37 @@ export function scanExitCode(findings: RuleMatch[], failOn: ScanSeverity | undef
   const threshold = SEVERITY_RANK[failOn];
   return findings.some((f) => SEVERITY_RANK[f.severity] >= threshold) ? 1 : 0;
 }
+
+/**
+ * A parsed `--fail-on` value. "none" is accepted on the command line to mean
+ * "never fail" and is not a finding severity, which is why it is kept out of
+ * ScanSeverity itself.
+ *
+ * Note the ordering: a lower threshold is stricter. `low` fails on low, medium
+ * and high; `high` fails only on high.
+ */
+export type FailOnOption = ScanSeverity | "none";
+
+export const FAIL_ON_USAGE = "low|medium|high|none";
+
+export function parseFailOn(value: string | undefined): FailOnOption {
+  if (value !== "low" && value !== "medium" && value !== "high" && value !== "none") {
+    throw new Error("--fail-on must be low, medium, high, or none");
+  }
+  return value;
+}
+
+/**
+ * Resolves the threshold for the commands that fetch remote content into the
+ * vault (install, update). They default to blocking on a high-severity finding,
+ * because printing a warning and proceeding anyway is the wrong default on the
+ * supply-chain path. `--fail-on none` restores the permissive behavior.
+ *
+ * `skillmux scan` deliberately does NOT use this: it is a reporting command
+ * whose exit code the caller opts into, and giving it a default would change
+ * the exit code of existing CI pipelines that just run `skillmux scan`.
+ */
+export function resolveMutatingFailOn(failOn: FailOnOption | undefined): ScanSeverity | undefined {
+  if (failOn === undefined) return "high";
+  return failOn === "none" ? undefined : failOn;
+}

package/src/server.ts

@@ -668,7 +668,7 @@ export async function startServer(opts?: {
               const auditChanges: AdminAuditChange[] = [];
               for (const [k, v] of Object.entries(body.changes ?? {})) {
                 lastResult = await setDottedKey(k, String(v), {
-                  targetName: "remote",
+                  contextName: "remote",
                 });
                 auditChanges.push({
                   key: k,

package/src/init-clients.ts

@@ -1,220 +0,0 @@
-import { existsSync } from "node:fs";
-import { homedir } from "node:os";
-import { join } from "node:path";
-
-export const SUPPORTED_CLIENT_IDS = [
-  "claude-code",
-  "codex",
-  "gemini-cli",
-  "opencode",
-  "github-copilot",
-  "windsurf",
-  "antigravity",
-  "goose",
-  "hermes",
-  "skillmux-mcp",
-] as const;
-
-export type ClientId = (typeof SUPPORTED_CLIENT_IDS)[number];
-export type DeliveryMode = "managed-pins" | "full-vault" | "mcp";
-
-export interface DetectedClient {
-  client: ClientId;
-  evidence: string;
-}
-
-interface ClientDefinition {
-  id: ClientId;
-  surfaceId?: "agent-skills" | "claude-code" | "codex" | "antigravity";
-  deliveryMode: DeliveryMode;
-}
-
-export interface PlannedClientSurface {
-  id: string;
-  targetName: string;
-  path: string;
-  deliveryMode: "managed-pins";
-  clients: ClientId[];
-}
-
-export interface ClientSurfacePlan {
-  clients: ClientDefinition[];
-  surfaces: PlannedClientSurface[];
-}
-
-type ReadinessStatus = "ready" | "planned" | "manual" | "not-applicable";
-
-export interface ReadinessAxis {
-  status: ReadinessStatus;
-  detail: string;
-}
-
-export interface ClientReadiness {
-  client: ClientId;
-  skillSurface: ReadinessAxis;
-  mcpRegistration: ReadinessAxis;
-  instructionSetup: ReadinessAxis;
-}
-
-export interface ResolvedBuiltInTarget {
-  targetName: string;
-  path: string;
-  warning?: string;
-}
-
-const CLIENTS: Record<ClientId, ClientDefinition> = {
-  "claude-code": { id: "claude-code", surfaceId: "claude-code", deliveryMode: "managed-pins" },
-  codex: { id: "codex", surfaceId: "codex", deliveryMode: "managed-pins" },
-  "gemini-cli": { id: "gemini-cli", surfaceId: "agent-skills", deliveryMode: "managed-pins" },
-  opencode: { id: "opencode", surfaceId: "agent-skills", deliveryMode: "managed-pins" },
-  "github-copilot": { id: "github-copilot", surfaceId: "agent-skills", deliveryMode: "managed-pins" },
-  windsurf: { id: "windsurf", surfaceId: "agent-skills", deliveryMode: "managed-pins" },
-  antigravity: { id: "antigravity", surfaceId: "antigravity", deliveryMode: "managed-pins" },
-  goose: { id: "goose", deliveryMode: "full-vault" },
-  hermes: { id: "hermes", deliveryMode: "full-vault" },
-  "skillmux-mcp": { id: "skillmux-mcp", deliveryMode: "mcp" },
-};
-
-export function detectInstalledClients(
-  options: {
-    home?: string;
-    codexHome?: string;
-    exists?: (path: string) => boolean;
-  } = {},
-): DetectedClient[] {
-  const home = options.home ?? homedir();
-  const codexHome = options.codexHome ?? join(home, ".codex");
-  const exists = options.exists ?? existsSync;
-  const candidates: Array<[ClientId, string]> = [
-    ["claude-code", join(home, ".claude")],
-    ["codex", codexHome],
-    ["gemini-cli", join(home, ".gemini")],
-    ["opencode", join(home, ".config", "opencode")],
-    ["github-copilot", join(home, ".config", "github-copilot")],
-    ["windsurf", join(home, ".codeium", "windsurf")],
-    ["goose", join(home, ".config", "goose")],
-    ["hermes", join(home, ".hermes")],
-  ];
-  return candidates
-    .filter(([, evidence]) => exists(evidence))
-    .map(([client, evidence]) => ({ client, evidence }));
-}
-
-function surfacePath(
-  surfaceId: NonNullable<ClientDefinition["surfaceId"]>,
-  options: { home: string; codexHome?: string },
-): string {
-  if (surfaceId === "agent-skills") return join(options.home, ".agents", "skills");
-  if (surfaceId === "claude-code") return join(options.home, ".claude", "skills");
-  if (surfaceId === "codex") return join(options.codexHome ?? join(options.home, ".codex"), "skills");
-  return join(options.home, ".gemini", "config", "skills");
-}
-
-export function resolveBuiltInTarget(
-  name: string,
-  options: { home?: string; codexHome?: string; customPath?: string } = {},
-): ResolvedBuiltInTarget {
-  const home = options.home ?? homedir();
-  if (name === "custom") {
-    if (!options.customPath) throw new Error("--target custom requires --path <dir>");
-    return { targetName: name, path: options.customPath };
-  }
-  if (name === "agent-skills" || name === "agents") {
-    return {
-      targetName: name,
-      path: surfacePath("agent-skills", { home }),
-      ...(name === "agents"
-        ? { warning: "--target agents is deprecated; use --target agent-skills" }
-        : {}),
-    };
-  }
-  if (name === "claude-code" || name === "claude") {
-    return {
-      targetName: name,
-      path: surfacePath("claude-code", { home }),
-      ...(name === "claude"
-        ? { warning: "--target claude is deprecated; use --target claude-code" }
-        : {}),
-    };
-  }
-  if (name === "codex") {
-    return {
-      targetName: name,
-      path: surfacePath("codex", { home, codexHome: options.codexHome }),
-    };
-  }
-  throw new Error(
-    `unknown --target "${name}"; supported targets: agent-skills, claude-code, codex, custom`,
-  );
-}
-
-export function planClientSurfaces(
-  requestedClients: readonly string[],
-  options: { home?: string; codexHome?: string } = {},
-): ClientSurfacePlan {
-  const clients = [...new Set(requestedClients)].map((id) => {
-    if (!SUPPORTED_CLIENT_IDS.includes(id as ClientId)) {
-      throw new Error(
-        `unsupported client "${id}"; supported clients: ${SUPPORTED_CLIENT_IDS.join(", ")}`,
-      );
-    }
-    return CLIENTS[id as ClientId];
-  });
-  const home = options.home ?? homedir();
-  const surfaces = new Map<string, PlannedClientSurface>();
-
-  for (const client of clients) {
-    if (!client.surfaceId) continue;
-    const path = surfacePath(client.surfaceId, { home, codexHome: options.codexHome });
-    const existing = surfaces.get(path);
-    if (existing) {
-      if (!existing.clients.includes(client.id)) existing.clients.push(client.id);
-      continue;
-    }
-    surfaces.set(path, {
-      id: client.surfaceId,
-      targetName: client.surfaceId,
-      path,
-      deliveryMode: "managed-pins",
-      clients: [client.id],
-    });
-  }
-
-  return { clients, surfaces: [...surfaces.values()] };
-}
-
-export function assessClientReadiness(
-  plan: ClientSurfacePlan,
-  instructionReadiness: Partial<Record<ClientId, ReadinessAxis>> = {},
-): ClientReadiness[] {
-  return plan.clients.map((client) => {
-    const surface = plan.surfaces.find((candidate) => candidate.clients.includes(client.id));
-    let skillSurface: ReadinessAxis;
-    if (surface) {
-      skillSurface = { status: "planned", detail: surface.path };
-    } else if (client.id === "goose") {
-      skillSurface = { status: "manual", detail: "configure the full vault in Goose" };
-    } else if (client.id === "hermes") {
-      skillSurface = { status: "manual", detail: "configure the full vault in Hermes external_dirs" };
-    } else {
-      skillSurface = {
-        status: "not-applicable",
-        detail: "skills resolve through Skillmux MCP",
-      };
-    }
-
-    const mcpRegistration: ReadinessAxis = client.deliveryMode === "mcp"
-      ? { status: "manual", detail: "register the Skillmux MCP server" }
-      : { status: "not-applicable", detail: "native skill loading" };
-
-    return {
-      client: client.id,
-      skillSurface,
-      mcpRegistration,
-      instructionSetup: instructionReadiness[client.id] ?? {
-        status: "manual",
-        detail: "instruction adapter not applied",
-      },
-    };
-  });
-}