@paradigma-inc/flywheel 0.1.111 → 0.1.134

package/src/setup/modes/mcp-command.mjs

@@ -5,345 +5,345 @@ import { rm } from "node:fs/promises";
 import path from "node:path";
 
 import {
-  ALL_HOST_NAMES,
-  SERVER_NAME,
-  detectHosts,
-  getHost,
-  isSkillOnlyHost,
-  normalizeHosts,
+ ALL_HOST_NAMES,
+ SERVER_NAME,
+ detectHosts,
+ getHost,
+ isSkillOnlyHost,
+ normalizeHosts,
 } from "../../agents.mjs";
 import {
-  readEntryServerUrl,
-  readNamedConfigEntry,
-  readJsonConfig,
-  readTomlServerEntry,
-  readYamlConfig,
-  resolveMcpPath,
+ readEntryServerUrl,
+ readNamedConfigEntry,
+ readJsonConfig,
+ readTomlServerEntry,
+ readYamlConfig,
+ resolveMcpPath,
 } from "../../mcp-writer.mjs";
 import { resolveSetupApiKey } from "../../setup-auth.mjs";
 import {
-  cleanupInstalledSkillArtifactsForHosts,
-  formatSupportedInstallSkillHosts,
-  inspectInstalledSkillArtifactsForHosts,
-  installBundledSkillForHosts,
-  isDirectCopySkillHost,
-  listBundledSkills,
-  partitionInstallSkillHosts,
-  resolveInstalledSkillDir,
-  resolvePackageRoot,
-  resolveSkillsAgentName,
+ cleanupInstalledSkillArtifactsForHosts,
+ formatSupportedInstallSkillHosts,
+ inspectInstalledSkillArtifactsForHosts,
+ installBundledSkillForHosts,
+ isDirectCopySkillHost,
+ listBundledSkills,
+ partitionInstallSkillHosts,
+ resolveInstalledSkillDir,
+ resolvePackageRoot,
+ resolveSkillsAgentName,
 } from "../../skill-installer.mjs";
 import { runMcpSetupMode } from "./mcp.mjs";
 import { SetupModeUsageError } from "../mode.mjs";
 import { recordResolvedHosts } from "../resolved-selection-record.mjs";
 import {
-  detectPriorModeForSetup,
-  formatPriorModeConflictError,
+ detectPriorModeForSetup,
+ formatPriorModeConflictError,
 } from "../shared/prior-mode-detect.mjs";
 import { renderSetupSummary } from "../shared/summary.mjs";
 import { resolveSetupBaseUrl } from "../base-url.mjs";
 
 const NON_INTERACTIVE_SKILL_DECISION_ERROR =
-  "Non-interactive setup requires one of --install-skill or --skip-skill.";
+ "Non-interactive setup requires one of --install-skill or --skip-skill.";
 const MUTUALLY_EXCLUSIVE_SKILL_FLAGS_ERROR =
-  "--install-skill and --skip-skill cannot be used together.";
+ "--install-skill and --skip-skill cannot be used together.";
 const GUIDED_SKILL_DECISION_TEST_ENV =
-  "FLYWHEEL_GUIDED_SKILL_DECISION_FOR_TESTS";
+ "FLYWHEEL_GUIDED_SKILL_DECISION_FOR_TESTS";
 const ENABLE_TEST_SEAMS_ENV = "FLYWHEEL_ENABLE_TEST_SEAMS";
 
 const log = {
-  info: (message) => console.log(pc.cyan(message)),
-  warn: (message) => console.log(pc.yellow(`⚠ ${message}`)),
-  error: (message) => console.log(pc.red(`✖ ${message}`)),
-  plain: (message) => console.log(message),
-  blank: () => console.log(""),
+ info: (message) => console.log(pc.cyan(message)),
+ warn: (message) => console.log(pc.yellow(`⚠ ${message}`)),
+ error: (message) => console.log(pc.red(`✖ ${message}`)),
+ plain: (message) => console.log(message),
+ blank: () => console.log(""),
 };
 
 const CHECKBOX_THEME = {
-  style: {
-    highlight: (text) => pc.green(text),
-    disabledChoice: (text) => ` ${pc.dim("◯")} ${pc.dim(text)}`,
-  },
+ style: {
+  highlight: (text) => pc.green(text),
+  disabledChoice: (text) => ` ${pc.dim("◯")} ${pc.dim(text)}`,
+ },
 };
 
 function hostChoiceDescription({ detected = false, configured = false } = {}) {
-  if (configured) return "Already has a Flywheel entry for this scope.";
-  if (detected) return "Detected on this machine.";
-  return "Supported host; select it if you use it here.";
+ if (configured) return "Already has a Flywheel entry for this scope.";
+ if (detected) return "Detected on this machine.";
+ return "Supported host; select it if you use it here.";
 }
 
 function normalizeBaseUrl(value) {
-  const normalized = String(value || "").trim();
-  let parsedUrl;
-  try {
-    parsedUrl = new URL(normalized);
-  } catch {
-    throw new Error("Base URL must be a valid absolute URL.");
-  }
-
-  if (parsedUrl.pathname !== "/" || parsedUrl.search || parsedUrl.hash) {
-    throw new Error(
-      "Base URL must be a public Flywheel origin without a path, query, or hash.",
-    );
-  }
+ const normalized = String(value || "").trim();
+ let parsedUrl;
+ try {
+  parsedUrl = new URL(normalized);
+ } catch {
+  throw new Error("Base URL must be a valid absolute URL.");
+ }
+
+ if (parsedUrl.pathname !== "/" || parsedUrl.search || parsedUrl.hash) {
+  throw new Error(
+   "Base URL must be a public Flywheel origin without a path, query, or hash.",
+  );
+ }
 
-  return parsedUrl.origin;
+ return parsedUrl.origin;
 }
 
 function normalizeServerName(value) {
-  const normalized = String(value || "").trim();
-  if (!normalized) {
-    throw new Error("Server name cannot be empty.");
-  }
-  return normalized;
+ const normalized = String(value || "").trim();
+ if (!normalized) {
+  throw new Error("Server name cannot be empty.");
+ }
+ return normalized;
 }
 
 function selectedHostsFromOptions(options) {
-  const hosts = [];
-  if (options.claude) hosts.push("claude");
-  if (options.cursor) hosts.push("cursor");
-  if (options.universal) hosts.push("universal");
-  if (options.antigravity) hosts.push("antigravity");
-  if (options.opencode) hosts.push("opencode");
-  if (options.codex) hosts.push("codex");
-  if (options.gemini) hosts.push("gemini");
-  if (options.piMono) hosts.push("pi-mono");
-  if (options.hermesAgent) hosts.push("hermes-agent");
-  if (options.openclaw) hosts.push("openclaw");
-  return hosts;
+ const hosts = [];
+ if (options.claude) hosts.push("claude");
+ if (options.cursor) hosts.push("cursor");
+ if (options.universal) hosts.push("universal");
+ if (options.antigravity) hosts.push("antigravity");
+ if (options.opencode) hosts.push("opencode");
+ if (options.codex) hosts.push("codex");
+ if (options.gemini) hosts.push("gemini");
+ if (options.piMono) hosts.push("pi-mono");
+ if (options.hermesAgent) hosts.push("hermes-agent");
+ if (options.openclaw) hosts.push("openclaw");
+ return hosts;
 }
 
 function mcpCandidatesForScope(host, scope) {
-  if (scope === "global") return host.mcp.globalPaths;
-  return host.mcp.projectPaths.map((candidate) =>
-    path.join(process.cwd(), candidate),
-  );
+ if (scope === "global") return host.mcp.globalPaths;
+ return host.mcp.projectPaths.map((candidate) =>
+  path.join(process.cwd(), candidate),
+ );
 }
 
 async function readExistingServerState(hostName, scope, serverName) {
-  const host = getHost(hostName);
-  if (isSkillOnlyHost(host)) {
-    return { exists: false, url: null, mcpPath: null };
-  }
-  const mcpPath = await resolveMcpPath(mcpCandidatesForScope(host, scope));
-
-  if (host.mcp.configType === "toml") {
-    const { exists, url } = await readTomlServerEntry(mcpPath, serverName);
-    return { exists, url, mcpPath };
-  }
-
-  const existing =
-    host.mcp.configType === "yaml"
-      ? await readYamlConfig(mcpPath)
-      : await readJsonConfig(mcpPath);
-  const entry = readNamedConfigEntry(existing, host.mcp.configKey, serverName);
-  return {
-    exists: entry !== null,
-    url: readEntryServerUrl(entry),
-    mcpPath,
-  };
+ const host = getHost(hostName);
+ if (isSkillOnlyHost(host)) {
+  return { exists: false, url: null, mcpPath: null };
+ }
+ const mcpPath = await resolveMcpPath(mcpCandidatesForScope(host, scope));
+
+ if (host.mcp.configType === "toml") {
+  const { exists, url } = await readTomlServerEntry(mcpPath, serverName);
+  return { exists, url, mcpPath };
+ }
+
+ const existing =
+  host.mcp.configType === "yaml"
+   ? await readYamlConfig(mcpPath)
+   : await readJsonConfig(mcpPath);
+ const entry = readNamedConfigEntry(existing, host.mcp.configKey, serverName);
+ return {
+  exists: entry !== null,
+  url: readEntryServerUrl(entry),
+  mcpPath,
+ };
 }
 
 async function isAlreadyConfigured(hostName, scope, serverName) {
-  const existingState = await readExistingServerState(
-    hostName,
-    scope,
-    serverName,
-  );
-  return existingState.exists;
+ const existingState = await readExistingServerState(
+  hostName,
+  scope,
+  serverName,
+ );
+ return existingState.exists;
 }
 
 async function inspectInstallSkillHosts({
-  hostNames,
-  scope,
-  serverName,
-  serverUrl,
+ hostNames,
+ scope,
+ serverName,
+ serverUrl,
 }) {
-  const hostStates = new Map();
-  const needsSetupHosts = [];
-  const driftHosts = [];
-
-  for (const hostName of hostNames) {
-    const host = getHost(hostName);
-    // Skill-only hosts (universal, antigravity) never write an MCP config, so
-    // they are not candidates for "needs setup" / "drift" / "matching"
-    // classification. Skipping them here is what keeps the auth-resolution
-    // gate downstream accurate: without this branch they would land in
-    // `needsSetupHosts` and force an API-key mint on `setup --mode mcp
-    // --universal --skip-skill`, which is a pure no-op path that must stay
-    // hermetic (no browser, no blocking prompt).
-    if (isSkillOnlyHost(host)) {
-      hostStates.set(hostName, {
-        classification: "skill-only",
-        mcpPath: null,
-      });
-      continue;
-    }
-    // eslint-disable-next-line no-await-in-loop
-    const existingState = await readExistingServerState(
-      hostName,
-      scope,
-      serverName,
-    );
-    if (!existingState.exists) {
-      needsSetupHosts.push(hostName);
-      hostStates.set(hostName, {
-        classification: "needs-setup",
-        mcpPath: existingState.mcpPath,
-      });
-      continue;
-    }
+ const hostStates = new Map();
+ const needsSetupHosts = [];
+ const driftHosts = [];
 
-    if (existingState.url === serverUrl) {
-      hostStates.set(hostName, {
-        classification: "matching",
-        mcpPath: existingState.mcpPath,
-      });
-      continue;
-    }
-
-    driftHosts.push({
-      hostName,
-      mcpPath: existingState.mcpPath,
-      existingUrl: existingState.url ?? "(missing URL)",
-    });
-    hostStates.set(hostName, {
-      classification: "drift",
-      mcpPath: existingState.mcpPath,
-    });
+ for (const hostName of hostNames) {
+  const host = getHost(hostName);
+  // Skill-only hosts (universal, antigravity) never write an MCP config, so
+  // they are not candidates for "needs setup" / "drift" / "matching"
+  // classification. Skipping them here is what keeps the auth-resolution
+  // gate downstream accurate: without this branch they would land in
+  // `needsSetupHosts` and force an API-key mint on `setup --mode mcp
+  // --universal --skip-skill`, which is a pure no-op path that must stay
+  // hermetic (no browser, no blocking prompt).
+  if (isSkillOnlyHost(host)) {
+   hostStates.set(hostName, {
+    classification: "skill-only",
+    mcpPath: null,
+   });
+   continue;
   }
+  // eslint-disable-next-line no-await-in-loop
+  const existingState = await readExistingServerState(
+   hostName,
+   scope,
+   serverName,
+  );
+  if (!existingState.exists) {
+   needsSetupHosts.push(hostName);
+   hostStates.set(hostName, {
+    classification: "needs-setup",
+    mcpPath: existingState.mcpPath,
+   });
+   continue;
+  }
+
+  if (existingState.url === serverUrl) {
+   hostStates.set(hostName, {
+    classification: "matching",
+    mcpPath: existingState.mcpPath,
+   });
+   continue;
+  }
+
+  driftHosts.push({
+   hostName,
+   mcpPath: existingState.mcpPath,
+   existingUrl: existingState.url ?? "(missing URL)",
+  });
+  hostStates.set(hostName, {
+   classification: "drift",
+   mcpPath: existingState.mcpPath,
+  });
+ }
 
-  return { hostStates, needsSetupHosts, driftHosts };
+ return { hostStates, needsSetupHosts, driftHosts };
 }
 
 function formatInstallSkillDriftError({
-  hostName,
-  scope,
-  serverName,
-  existingUrl,
-  requestedUrl,
+ hostName,
+ scope,
+ serverName,
+ existingUrl,
+ requestedUrl,
 }) {
-  const host = getHost(hostName);
-  const scopeFlag = scope === "project" ? "--scope project" : "--scope global";
-  return `Flywheel MCP entry '${serverName}' for ${host.displayName} already points to ${existingUrl}, not ${requestedUrl}. Run 'flywheel uninstall ${scopeFlag} --${hostName} --name ${serverName}' first or choose a different --name.`;
+ const host = getHost(hostName);
+ const scopeFlag = scope === "project" ? "--scope project" : "--scope global";
+ return `Flywheel MCP entry '${serverName}' for ${host.displayName} already points to ${existingUrl}, not ${requestedUrl}. Run 'flywheel uninstall ${scopeFlag} --${hostName} --name ${serverName}' first or choose a different --name.`;
 }
 
 function getGuidedSkillDecisionOverrideForTests() {
-  const testSeamsEnabled =
-    String(process.env[ENABLE_TEST_SEAMS_ENV] || "").trim() === "1";
-  if (!testSeamsEnabled) {
-    return "";
-  }
-
-  const normalizedGuidedDecisionOverride = String(
-    process.env[GUIDED_SKILL_DECISION_TEST_ENV] || "",
-  )
-    .trim()
-    .toLowerCase();
-  if (normalizedGuidedDecisionOverride.length === 0) {
-    return "";
-  }
-  if (
-    normalizedGuidedDecisionOverride === "accept" ||
-    normalizedGuidedDecisionOverride === "decline" ||
-    normalizedGuidedDecisionOverride === "abort"
-  ) {
-    return normalizedGuidedDecisionOverride;
-  }
-
-  throw new Error(
-    `${GUIDED_SKILL_DECISION_TEST_ENV} must be one of: accept, decline, abort`,
-  );
+ const testSeamsEnabled =
+  String(process.env[ENABLE_TEST_SEAMS_ENV] || "").trim() === "1";
+ if (!testSeamsEnabled) {
+  return "";
+ }
+
+ const normalizedGuidedDecisionOverride = String(
+  process.env[GUIDED_SKILL_DECISION_TEST_ENV] || "",
+ )
+  .trim()
+  .toLowerCase();
+ if (normalizedGuidedDecisionOverride.length === 0) {
+  return "";
+ }
+ if (
+  normalizedGuidedDecisionOverride === "accept" ||
+  normalizedGuidedDecisionOverride === "decline" ||
+  normalizedGuidedDecisionOverride === "abort"
+ ) {
+  return normalizedGuidedDecisionOverride;
+ }
+
+ throw new Error(
+  `${GUIDED_SKILL_DECISION_TEST_ENV} must be one of: accept, decline, abort`,
+ );
 }
 
 async function promptHosts(scope, detected, serverName) {
-  const choices = [];
-  for (const hostName of ALL_HOST_NAMES) {
-    // eslint-disable-next-line no-await-in-loop
-    const configured = await isAlreadyConfigured(
-      hostName,
-      scope,
-      serverName,
-    ).catch(() => false);
-    choices.push({
-      name: getHost(hostName).displayName,
-      value: hostName,
-      short: getHost(hostName).displayName,
-      description: hostChoiceDescription({
-        detected: detected.includes(hostName),
-        configured,
-      }),
-      checked: detected.includes(hostName),
-      disabled: configured ? "(already configured)" : false,
-    });
-  }
-
-  try {
-    return await checkbox({
-      message: "Which hosts do you want to set up?",
-      choices,
-      loop: false,
-      theme: CHECKBOX_THEME,
-      validate: (selected) =>
-        selected.length > 0 || "Select at least one host.",
-    });
-  } catch {
-    return null;
-  }
+ const choices = [];
+ for (const hostName of ALL_HOST_NAMES) {
+  // eslint-disable-next-line no-await-in-loop
+  const configured = await isAlreadyConfigured(
+   hostName,
+   scope,
+   serverName,
+  ).catch(() => false);
+  choices.push({
+   name: getHost(hostName).displayName,
+   value: hostName,
+   short: getHost(hostName).displayName,
+   description: hostChoiceDescription({
+    detected: detected.includes(hostName),
+    configured,
+   }),
+   checked: detected.includes(hostName),
+   disabled: configured ? "(already configured)" : false,
+  });
+ }
+
+ try {
+  return await checkbox({
+   message: "Which hosts do you want to set up?",
+   choices,
+   loop: false,
+   theme: CHECKBOX_THEME,
+   validate: (selected) =>
+    selected.length > 0 || "Select at least one host.",
+  });
+ } catch {
+  return null;
+ }
 }
 
 async function resolveHosts(options, scope, serverName, allowPrompt = true) {
-  const explicit = selectedHostsFromOptions(options);
-  if (explicit.length > 0) return explicit;
-
-  const detected = await detectHosts(scope);
-  const promptDisabled =
-    options.yes || process.stdout.isTTY !== true || !allowPrompt;
-  if (detected.length > 0 && promptDisabled) {
-    return detected;
-  }
-
-  if (promptDisabled) {
-    log.warn(
-      "No hosts were detected for prompt-free setup. Pass explicit host flags such as --codex.",
-    );
-    return [];
-  }
-
-  log.blank();
-  const selected = await promptHosts(scope, detected, serverName);
-  if (!selected) {
-    log.warn("Setup cancelled");
-    return [];
-  }
-  return selected;
+ const explicit = selectedHostsFromOptions(options);
+ if (explicit.length > 0) return explicit;
+
+ const detected = await detectHosts(scope);
+ const promptDisabled =
+  options.yes || process.stdout.isTTY !== true || !allowPrompt;
+ if (detected.length > 0 && promptDisabled) {
+  return detected;
+ }
+
+ if (promptDisabled) {
+  log.warn(
+   "No hosts were detected for prompt-free setup. Pass explicit host flags such as --codex.",
+  );
+  return [];
+ }
+
+ log.blank();
+ const selected = await promptHosts(scope, detected, serverName);
+ if (!selected) {
+  log.warn("Setup cancelled");
+  return [];
+ }
+ return selected;
 }
 
 async function resolveApiKey(options, baseUrl) {
-  if (Object.hasOwn(options, "apiKey")) {
-    const resolved = await resolveSetupApiKey({
-      options,
-      baseUrl,
-    });
-    return resolved.apiKey;
-  }
-
-  const spinner = ora("Configuring authentication...").start();
-  try {
-    const resolved = await resolveSetupApiKey({
-      options,
-      baseUrl,
-    });
-    spinner.succeed(`Authenticated (${resolved.authMode})`);
-    return resolved.apiKey;
-  } catch (error) {
-    spinner.fail("Authentication failed");
-    const message = error instanceof Error ? error.message : String(error);
-    if (/cancelled/i.test(message)) {
-      return null;
-    }
-    throw new Error(message);
-  }
+ if (Object.hasOwn(options, "apiKey")) {
+  const resolved = await resolveSetupApiKey({
+   options,
+   baseUrl,
+  });
+  return resolved.apiKey;
+ }
+
+ const spinner = ora("Configuring authentication...").start();
+ try {
+  const resolved = await resolveSetupApiKey({
+   options,
+   baseUrl,
+  });
+  spinner.succeed(`Authenticated (${resolved.authMode})`);
+  return resolved.apiKey;
+ } catch (error) {
+  spinner.fail("Authentication failed");
+  const message = error instanceof Error ? error.message : String(error);
+  if (/cancelled/i.test(message)) {
+   return null;
+  }
+  throw new Error(message);
+ }
 }
 
 /**
@@ -366,593 +366,602 @@ async function resolveApiKey(options, baseUrl) {
  *                                 a Bearer token into the host config.
  */
 function classifyAgentOutcome(agentResult, { oauthMode = false } = {}) {
-  if (agentResult.success === false) {
-    return "failed";
-  }
-  if (
-    agentResult.success === null ||
-    agentResult.status === "skipped" ||
-    (Array.isArray(agentResult.skippedSteps) &&
-      (agentResult.skippedSteps.includes("skill-only-host") ||
-        agentResult.skippedSteps.includes("unsupported-host")))
-  ) {
-    return "skipped";
-  }
-  const alreadyConfigured =
-    Array.isArray(agentResult.skippedSteps) &&
-    agentResult.skippedSteps.includes("already-configured");
-  if (alreadyConfigured) {
-    return "already configured";
-  }
-  return oauthMode ? "configured (OAuth)" : "configured with API Key";
+ if (agentResult.success === false) {
+  return "failed";
+ }
+ if (
+  agentResult.success === null ||
+  agentResult.status === "skipped" ||
+  (Array.isArray(agentResult.skippedSteps) &&
+   (agentResult.skippedSteps.includes("skill-only-host") ||
+    agentResult.skippedSteps.includes("unsupported-host")))
+ ) {
+  return "skipped";
+ }
+ const alreadyConfigured =
+  Array.isArray(agentResult.skippedSteps) &&
+  agentResult.skippedSteps.includes("already-configured");
+ if (alreadyConfigured) {
+  return "already configured";
+ }
+ return oauthMode ? "configured (OAuth)" : "configured with API Key";
 }
 
 function buildSetupResultRows({
-  selectedHosts,
-  hostStates,
-  setupResult,
-  oauthMode = false,
+ selectedHosts,
+ hostStates,
+ setupResult,
+ oauthMode = false,
 }) {
-  const byAgent = new Map(
-    setupResult.agentResults.map((result) => [result.agent, result]),
-  );
+ const byAgent = new Map(
+  setupResult.agentResults.map((result) => [result.agent, result]),
+ );
 
-  return selectedHosts.map((hostName) => {
-    const host = getHost(hostName);
-    const agentResult = byAgent.get(hostName);
-    if (!agentResult) {
-      return {
-        host: host.displayName,
-        status: "unknown",
-        filePath: hostStates.get(hostName)?.mcpPath || "(unknown)",
-      };
-    }
+ return selectedHosts.map((hostName) => {
+  const host = getHost(hostName);
+  const agentResult = byAgent.get(hostName);
+  if (!agentResult) {
+   return {
+    host: host.displayName,
+    status: "unknown",
+    filePath: hostStates.get(hostName)?.mcpPath || "(unknown)",
+   };
+  }
 
-    const status = classifyAgentOutcome(agentResult, { oauthMode });
-    return {
-      host: host.displayName,
-      status,
-      filePath:
-        agentResult.touchedFiles?.[0] ||
-        hostStates.get(hostName)?.mcpPath ||
-        "(unknown)",
-    };
-  });
+  const status = classifyAgentOutcome(agentResult, { oauthMode });
+  return {
+   host: host.displayName,
+   status,
+   filePath:
+    agentResult.touchedFiles?.[0] ||
+    hostStates.get(hostName)?.mcpPath ||
+    "(unknown)",
+  };
+ });
 }
 
 function printSetupResults(
-  results,
-  scope,
-  serverUrl,
-  { showSkillRefreshGuidance = false, experimentalSyncAgents = [] } = {},
+ results,
+ scope,
+ serverUrl,
+ { showSkillRefreshGuidance = false, experimentalSyncAgents = [] } = {},
 ) {
+ log.blank();
+ log.plain(pc.green("✔ Flywheel setup complete"));
+ log.blank();
+ log.plain(`  Scope: ${pc.bold(scope)}`);
+ log.plain(`  Server URL: ${pc.bold(serverUrl)}`);
+ for (const result of results) {
+  const icon = result.status.startsWith("configured")
+   ? pc.green("+")
+   : pc.dim("~");
+  log.plain(`  ${pc.bold(result.host)}`);
+  log.plain(`    ${icon} ${result.status}`);
+  log.plain(`      ${pc.dim(result.filePath)}`);
+ }
+ if (showSkillRefreshGuidance) {
   log.blank();
-  log.plain(pc.green("✔ Flywheel setup complete"));
-  log.blank();
-  log.plain(`  Scope: ${pc.bold(scope)}`);
-  log.plain(`  Server URL: ${pc.bold(serverUrl)}`);
-  for (const result of results) {
-    const icon = result.status.startsWith("configured")
-      ? pc.green("+")
-      : pc.dim("~");
-    log.plain(`  ${pc.bold(result.host)}`);
-    log.plain(`    ${icon} ${result.status}`);
-    log.plain(`      ${pc.dim(result.filePath)}`);
-  }
-  if (showSkillRefreshGuidance) {
-    log.blank();
-    log.plain("  Bundled skill refresh guidance");
-    log.plain(
-      `    Preferred: ${pc.bold("npx --yes @paradigma-inc/flywheel@latest setup --mode mcp --install-skill --project")}`,
-    );
+  log.plain("  Bundled skill refresh guidance");
+  log.plain(
+   `    Preferred: ${pc.bold("npx --yes @paradigma-inc/flywheel@latest setup --mode mcp --install-skill --project")}`,
+  );
+  log.plain(
+   `      ${pc.bold("npm install --save-dev @paradigma-inc/flywheel@latest")}`,
+  );
+  if (experimentalSyncAgents.length === 1) {
+   log.plain("    Optional path via skills experimental_sync:");
+   log.plain(
+    `      ${pc.bold(`npx skills experimental_sync --agent ${experimentalSyncAgents[0]} -y`)}`,
+   );
+  } else if (experimentalSyncAgents.length > 1) {
+   log.plain(
+    "    Optional path via skills experimental_sync for selected hosts:",
+   );
+   for (const agentName of experimentalSyncAgents) {
     log.plain(
-      `      ${pc.bold("npm install --save-dev @paradigma-inc/flywheel@latest")}`,
+     `      ${pc.bold(`npx skills experimental_sync --agent ${agentName} -y`)}`,
     );
-    if (experimentalSyncAgents.length === 1) {
-      log.plain("    Optional path via skills experimental_sync:");
-      log.plain(
-        `      ${pc.bold(`npx skills experimental_sync --agent ${experimentalSyncAgents[0]} -y`)}`,
-      );
-    } else if (experimentalSyncAgents.length > 1) {
-      log.plain(
-        "    Optional path via skills experimental_sync for selected hosts:",
-      );
-      for (const agentName of experimentalSyncAgents) {
-        log.plain(
-          `      ${pc.bold(`npx skills experimental_sync --agent ${agentName} -y`)}`,
-        );
-      }
-    }
+   }
   }
-  log.blank();
+ }
+ log.blank();
 }
 
 function resolveExperimentalSyncAgentsForHosts(supportedHosts) {
-  const agentNames = [];
-  const seenAgentNames = new Set();
-
-  for (const hostName of supportedHosts) {
-    // Direct-copy hosts (gemini, universal, antigravity) bypass the `skills`
-    // CLI entirely, so they have no agent name to sync with. Skip them from
-    // the experimental_sync guidance block.
-    if (isDirectCopySkillHost(hostName)) {
-      continue;
-    }
-    const agentName = resolveSkillsAgentName(hostName);
-    if (seenAgentNames.has(agentName)) {
-      continue;
-    }
-    seenAgentNames.add(agentName);
-    agentNames.push(agentName);
+ const agentNames = [];
+ const seenAgentNames = new Set();
+
+ for (const hostName of supportedHosts) {
+  // Direct-copy hosts (gemini, universal, antigravity) bypass the `skills`
+  // CLI entirely, so they have no agent name to sync with. Skip them from
+  // the experimental_sync guidance block.
+  if (isDirectCopySkillHost(hostName)) {
+   continue;
   }
+  const agentName = resolveSkillsAgentName(hostName);
+  if (seenAgentNames.has(agentName)) {
+   continue;
+  }
+  seenAgentNames.add(agentName);
+  agentNames.push(agentName);
+ }
 
-  return agentNames;
+ return agentNames;
 }
 
 export function buildGuidedSkillInstallPrompt({
-  unsupportedHosts,
-  bundledSkillNames,
+ unsupportedHosts,
+ bundledSkillNames,
 }) {
-  const usesPlural = bundledSkillNames.length > 1;
-  if (unsupportedHosts.length > 0) {
-    return usesPlural
-      ? `Also install or refresh the bundled Flywheel skills for supported hosts? Unsupported hosts (${unsupportedHosts.join(", ")}) will remain MCP-only.`
-      : `Also install or refresh the bundled Flywheel skill for supported hosts? Unsupported hosts (${unsupportedHosts.join(", ")}) will remain MCP-only.`;
-  }
+ const usesPlural = bundledSkillNames.length > 1;
+ if (unsupportedHosts.length > 0) {
   return usesPlural
-    ? "Also install or refresh the bundled Flywheel skills?"
-    : "Also install or refresh the bundled Flywheel skill?";
+   ? `Also install or refresh the bundled Flywheel skills for supported hosts? Unsupported hosts (${unsupportedHosts.join(", ")}) will remain MCP-only.`
+   : `Also install or refresh the bundled Flywheel skill for supported hosts? Unsupported hosts (${unsupportedHosts.join(", ")}) will remain MCP-only.`;
+ }
+ return usesPlural
+  ? "Also install or refresh the bundled Flywheel skills?"
+  : "Also install or refresh the bundled Flywheel skill?";
 }
 
 async function promptGuidedSkillInstall(
-  bundledSkillNames,
-  unsupportedHosts,
-  guidedSkillDecisionOverride,
+ bundledSkillNames,
+ unsupportedHosts,
+ guidedSkillDecisionOverride,
 ) {
-  if (guidedSkillDecisionOverride === "accept") {
-    return true;
-  }
-  if (
-    guidedSkillDecisionOverride === "decline" ||
-    guidedSkillDecisionOverride === "abort"
-  ) {
-    return false;
-  }
+ if (guidedSkillDecisionOverride === "accept") {
+  return true;
+ }
+ if (
+  guidedSkillDecisionOverride === "decline" ||
+  guidedSkillDecisionOverride === "abort"
+ ) {
+  return false;
+ }
+
+ log.blank();
+ const message = buildGuidedSkillInstallPrompt({
+  unsupportedHosts,
+  bundledSkillNames,
+ });
 
-  log.blank();
-  const message = buildGuidedSkillInstallPrompt({
-    unsupportedHosts,
-    bundledSkillNames,
+ try {
+  return await confirm({
+   message,
+   default: true,
+   theme: CHECKBOX_THEME,
   });
-
-  try {
-    return await confirm({
-      message,
-      default: true,
-      theme: CHECKBOX_THEME,
-    });
-  } catch {
-    return false;
-  }
+ } catch {
+  return false;
+ }
 }
 
 function logBundledSkillInstallPlan({
-  bundledSkillNames,
-  projectRoot,
-  scope,
-  supportedHosts,
+ bundledSkillNames,
+ projectRoot,
+ scope,
+ supportedHosts,
 }) {
-  for (const hostName of supportedHosts) {
-    const hostDisplayName = getHost(hostName).displayName;
-    const resolvedSkillRoot = path.dirname(
-      resolveInstalledSkillDir(
-        projectRoot,
-        hostName,
-        scope,
-        bundledSkillNames[0],
-      ),
-    );
-    log.plain(
-      `Installing bundled skills for ${hostDisplayName} (${scope}: ${resolvedSkillRoot}): ${bundledSkillNames.join(", ")}`,
-    );
-  }
+ for (const hostName of supportedHosts) {
+  const hostDisplayName = getHost(hostName).displayName;
+  const resolvedSkillRoot = path.dirname(
+   resolveInstalledSkillDir(
+    projectRoot,
+    hostName,
+    scope,
+    bundledSkillNames[0],
+   ),
+  );
+  log.plain(
+   `Installing bundled skills for ${hostDisplayName} (${scope}: ${resolvedSkillRoot}): ${bundledSkillNames.join(", ")}`,
+  );
+ }
 }
 
 function normalizeSkillDecisionMode(options) {
-  if (options.installSkill && options.skipSkill) {
-    throw new Error(MUTUALLY_EXCLUSIVE_SKILL_FLAGS_ERROR);
-  }
-  if (options.installSkill) return "install";
-  if (options.skipSkill) return "skip";
-  return "guided";
+ if (options.installSkill && options.skipSkill) {
+  throw new Error(MUTUALLY_EXCLUSIVE_SKILL_FLAGS_ERROR);
+ }
+ if (options.installSkill) return "install";
+ if (options.skipSkill) return "skip";
+ return "guided";
 }
 
 async function discardInstallSkillCleanupState(cleanupState) {
-  if (!cleanupState?.backupRoot) {
-    return null;
-  }
-  await rm(cleanupState.backupRoot, { force: true, recursive: true });
+ if (!cleanupState?.backupRoot) {
   return null;
+ }
+ await rm(cleanupState.backupRoot, { force: true, recursive: true });
+ return null;
 }
 
 function printSetupResultSummary(setupResult) {
-  const lines = renderSetupSummary(setupResult);
-  log.blank();
-  for (const line of lines) {
-    log.plain(`  ${line}`);
-  }
-  log.blank();
+ const lines = renderSetupSummary(setupResult);
+ log.blank();
+ for (const line of lines) {
+  log.plain(`  ${line}`);
+ }
+ log.blank();
 }
 
 export async function runMcpModeCommand(options, deps = {}) {
-  const projectRoot = process.cwd();
-  const skillDecisionMode = normalizeSkillDecisionMode(options);
-  const guidedSkillDecisionOverride = getGuidedSkillDecisionOverrideForTests();
-  const nonInteractive = process.stdout.isTTY !== true;
-  const hasGuidedDecisionOverride = guidedSkillDecisionOverride.length > 0;
-  if (
-    nonInteractive &&
-    skillDecisionMode === "guided" &&
-    !hasGuidedDecisionOverride
-  ) {
-    throw new Error(NON_INTERACTIVE_SKILL_DECISION_ERROR);
-  }
-
-  const oauthMode = options.oauth === true;
-  if (oauthMode && Object.hasOwn(options, "apiKey")) {
-    throw new SetupModeUsageError(
-      "--api-key and --oauth are mutually exclusive: choose one.",
+ const projectRoot = process.cwd();
+ const skillDecisionMode = normalizeSkillDecisionMode(options);
+ const guidedSkillDecisionOverride = getGuidedSkillDecisionOverrideForTests();
+ const nonInteractive = process.stdout.isTTY !== true;
+ const hasGuidedDecisionOverride = guidedSkillDecisionOverride.length > 0;
+ if (
+  nonInteractive &&
+  skillDecisionMode === "guided" &&
+  !hasGuidedDecisionOverride
+ ) {
+  throw new Error(NON_INTERACTIVE_SKILL_DECISION_ERROR);
+ }
+
+ const oauthMode = options.oauth === true;
+ if (oauthMode && (Object.hasOwn(options, "apiKey") || options.apiKeyStdin === true)) {
+  throw new SetupModeUsageError(
+   "--api-key and --oauth are mutually exclusive: choose one.",
+  );
+ }
+
+ const scope = options.project ? "project" : "global";
+ const baseUrl = normalizeBaseUrl(
+  resolveSetupBaseUrl({ explicitBaseUrl: options.baseUrl }),
+ );
+ const serverUrl = `${baseUrl}/mcp-server`;
+ const serverName = normalizeServerName(options.name || SERVER_NAME);
+ const resolveHostsForSetup =
+  deps.resolveHostsForSetup ||
+  (async ({
+   options: hostOptions,
+   scope: hostScope,
+   serverName: hostServerName,
+   allowPrompt,
+  }) =>
+   await resolveHosts(hostOptions, hostScope, hostServerName, allowPrompt));
+ const hosts = await resolveHostsForSetup({
+  options,
+  scope,
+  serverName,
+  // `--install-skill` is an explicit refresh request. Keep the advertised
+  // no-host update command prompt-free on detected hosts; `--skip-skill`
+  // remains guided unless host flags or --yes are provided.
+  allowPrompt: skillDecisionMode !== "install",
+ });
+ recordResolvedHosts(hosts);
+ if (options.apiKeyStdin === true &&
+  (scope !== "global" || hosts.length !== 1 || hosts[0] !== "codex")) {
+  throw new SetupModeUsageError(
+   "--api-key-stdin in MCP mode requires only Codex in the home directory. Use --codex without --project.",
+  );
+ }
+ const authResult = options.apiKeyStdin === true ? await deps.readStdinAuth() : undefined;
+ if (hosts.length === 0) {
+  return { exitCode: 0 };
+ }
+
+ const { supportedHosts, unsupportedHosts } =
+  partitionInstallSkillHosts(hosts);
+ const packageRoot = resolvePackageRoot();
+ const bundledSkillNames =
+  skillDecisionMode === "skip" || supportedHosts.length === 0
+   ? []
+   : await listBundledSkills(packageRoot);
+
+ if (skillDecisionMode === "install" && supportedHosts.length === 0) {
+  if (options.allowUnsupportedSkillInstall !== true) {
+   throw new Error(
+    `--install-skill is not supported for: ${unsupportedHosts.join(", ")}. Supported hosts: ${formatSupportedInstallSkillHosts()}.`,
+   );
+  }
+  log.plain(
+   `Bundled skill install skipped (unsupported-only host selection: ${unsupportedHosts.join(", ")}).`,
+  );
+ }
+ if (
+  skillDecisionMode !== "skip" &&
+  supportedHosts.length > 0 &&
+  bundledSkillNames.length === 0
+ ) {
+  throw new Error(
+   `No bundled skills found under ${path.join(packageRoot, "skills")}.`,
+  );
+ }
+
+ const {
+  hostStates = new Map(),
+  needsSetupHosts = [],
+  driftHosts = [],
+ } = await inspectInstallSkillHosts({
+  hostNames: hosts,
+  scope,
+  serverName,
+  serverUrl,
+ });
+
+ // Capture prior-mode state before any install/auth side effects so the
+ // detector does not classify artifacts created by this same command as
+ // pre-existing CLI-mode installs, and so a refuse or reconcile decision
+ // happens before we touch disk or start a browser auth flow. Running this
+ // inside runMcpSetupMode (the prior placement) meant --force would uninstall
+ // the freshly installed bundled skills, and the non-force path would still
+ // have run auth before surfacing the conflict.
+ const priorModeSnapshot = await detectPriorModeForSetup({
+  targetMode: "mcp",
+  selectedHosts: hosts,
+  scope,
+  cwd: projectRoot,
+  serverName,
+  serverUrl,
+ });
+ const reconciled = [];
+ if (
+  priorModeSnapshot.priorMode &&
+  priorModeSnapshot.affectedHosts.length > 0
+ ) {
+  if (deps.force !== true) {
+   throw new SetupModeUsageError(
+    formatPriorModeConflictError(priorModeSnapshot),
+   );
+  }
+  if (typeof deps.reconcilePriorMode !== "function") {
+   throw new Error(
+    "reconcilePriorMode dependency is required when --force is used.",
+   );
+  }
+  const reconcileEntries = Array.isArray(priorModeSnapshot.entries)
+   ? priorModeSnapshot.entries
+   : priorModeSnapshot.affectedHosts.map((hostName) => ({
+    hostName,
+    serverNames: [],
+   }));
+  for (const entry of reconcileEntries) {
+   try {
+    // eslint-disable-next-line no-await-in-loop
+    await deps.reconcilePriorMode({
+     priorMode: priorModeSnapshot.priorMode,
+     targetMode: "mcp",
+     hostNames: [entry.hostName],
+     serverNames: entry.serverNames,
+     scope,
+     cwd: projectRoot,
+     serverName,
+     serverUrl,
+    });
+   } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const reconcileError = new Error(
+     `Failed to reconcile prior --mode ${priorModeSnapshot.priorMode} artifacts for host ${entry.hostName}: ${message}`,
     );
+    reconcileError.exitCode = 4;
+    throw reconcileError;
+   }
   }
-
-  const scope = options.project ? "project" : "global";
-  const baseUrl = normalizeBaseUrl(
-    resolveSetupBaseUrl({ explicitBaseUrl: options.baseUrl }),
+  reconciled.push(
+   `removed prior --mode ${priorModeSnapshot.priorMode} artifacts for host(s): ${priorModeSnapshot.affectedHosts.join(", ")}`,
   );
-  const serverUrl = `${baseUrl}/mcp-server`;
-  const serverName = normalizeServerName(options.name || SERVER_NAME);
-  const resolveHostsForSetup =
-    deps.resolveHostsForSetup ||
-    (async ({
-      options: hostOptions,
-      scope: hostScope,
-      serverName: hostServerName,
-      allowPrompt,
-    }) =>
-      await resolveHosts(hostOptions, hostScope, hostServerName, allowPrompt));
-  const hosts = await resolveHostsForSetup({
-    options,
-    scope,
-    serverName,
-    // `--install-skill` is an explicit refresh request. Keep the advertised
-    // no-host update command prompt-free on detected hosts; `--skip-skill`
-    // remains guided unless host flags or --yes are provided.
-    allowPrompt: skillDecisionMode !== "install",
-  });
-  recordResolvedHosts(hosts);
-  if (hosts.length === 0) {
-    return { exitCode: 0 };
-  }
+ }
 
-  const { supportedHosts, unsupportedHosts } =
-    partitionInstallSkillHosts(hosts);
-  const packageRoot = resolvePackageRoot();
-  const bundledSkillNames =
-    skillDecisionMode === "skip" || supportedHosts.length === 0
-      ? []
-      : await listBundledSkills(packageRoot);
-
-  if (skillDecisionMode === "install" && supportedHosts.length === 0) {
-    if (options.allowUnsupportedSkillInstall !== true) {
-      throw new Error(
-        `--install-skill is not supported for: ${unsupportedHosts.join(", ")}. Supported hosts: ${formatSupportedInstallSkillHosts()}.`,
-      );
-    }
-    log.plain(
-      `Bundled skill install skipped (unsupported-only host selection: ${unsupportedHosts.join(", ")}).`,
-    );
-  }
-  if (
-    skillDecisionMode !== "skip" &&
-    supportedHosts.length > 0 &&
-    bundledSkillNames.length === 0
-  ) {
-    throw new Error(
-      `No bundled skills found under ${path.join(packageRoot, "skills")}.`,
-    );
-  }
+ const installDriftHosts = driftHosts;
 
-  const {
-    hostStates = new Map(),
-    needsSetupHosts = [],
-    driftHosts = [],
-  } = await inspectInstallSkillHosts({
-    hostNames: hosts,
+ if (skillDecisionMode === "install" && installDriftHosts.length > 0) {
+  throw new Error(
+   formatInstallSkillDriftError({
+    hostName: installDriftHosts[0].hostName,
     scope,
     serverName,
-    serverUrl,
-  });
+    existingUrl: installDriftHosts[0].existingUrl,
+    requestedUrl: serverUrl,
+   }),
+  );
+ }
 
-  // Capture prior-mode state before any install/auth side effects so the
-  // detector does not classify artifacts created by this same command as
-  // pre-existing CLI-mode installs, and so a refuse or reconcile decision
-  // happens before we touch disk or start a browser auth flow. Running this
-  // inside runMcpSetupMode (the prior placement) meant --force would uninstall
-  // the freshly installed bundled skills, and the non-force path would still
-  // have run auth before surfacing the conflict.
-  const priorModeSnapshot = await detectPriorModeForSetup({
-    targetMode: "mcp",
-    selectedHosts: hosts,
+ let cleanupState = null;
+ try {
+  if (skillDecisionMode === "install") {
+   logBundledSkillInstallPlan({
+    bundledSkillNames,
+    projectRoot,
+    scope,
+    supportedHosts,
+   });
+   cleanupState = await inspectInstalledSkillArtifactsForHosts({
+    projectRoot,
+    hostNames: supportedHosts,
+    scope,
+    skillNames: bundledSkillNames,
+   });
+   await installBundledSkillForHosts({
+    projectRoot,
+    hostNames: supportedHosts,
     scope,
-    cwd: projectRoot,
     serverName,
     serverUrl,
-  });
-  const reconciled = [];
-  if (
-    priorModeSnapshot.priorMode &&
-    priorModeSnapshot.affectedHosts.length > 0
-  ) {
-    if (deps.force !== true) {
-      throw new SetupModeUsageError(
-        formatPriorModeConflictError(priorModeSnapshot),
-      );
-    }
-    if (typeof deps.reconcilePriorMode !== "function") {
-      throw new Error(
-        "reconcilePriorMode dependency is required when --force is used.",
-      );
-    }
-    const reconcileEntries = Array.isArray(priorModeSnapshot.entries)
-      ? priorModeSnapshot.entries
-      : priorModeSnapshot.affectedHosts.map((hostName) => ({
-          hostName,
-          serverNames: [],
-        }));
-    for (const entry of reconcileEntries) {
-      try {
-        // eslint-disable-next-line no-await-in-loop
-        await deps.reconcilePriorMode({
-          priorMode: priorModeSnapshot.priorMode,
-          targetMode: "mcp",
-          hostNames: [entry.hostName],
-          serverNames: entry.serverNames,
-          scope,
-          cwd: projectRoot,
-          serverName,
-          serverUrl,
-        });
-      } catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        const reconcileError = new Error(
-          `Failed to reconcile prior --mode ${priorModeSnapshot.priorMode} artifacts for host ${entry.hostName}: ${message}`,
-        );
-        reconcileError.exitCode = 4;
-        throw reconcileError;
-      }
-    }
-    reconciled.push(
-      `removed prior --mode ${priorModeSnapshot.priorMode} artifacts for host(s): ${priorModeSnapshot.affectedHosts.join(", ")}`,
-    );
-  }
-
-  const installDriftHosts = driftHosts;
-
-  if (skillDecisionMode === "install" && installDriftHosts.length > 0) {
-    throw new Error(
-      formatInstallSkillDriftError({
-        hostName: installDriftHosts[0].hostName,
-        scope,
-        serverName,
-        existingUrl: installDriftHosts[0].existingUrl,
-        requestedUrl: serverUrl,
-      }),
+    skillNames: bundledSkillNames,
+   });
+   if (unsupportedHosts.length > 0) {
+    log.plain(
+     `--install-skill skipped unsupported hosts (MCP-only): ${unsupportedHosts.join(", ")}.`,
     );
+   }
   }
 
-  let cleanupState = null;
-  try {
-    if (skillDecisionMode === "install") {
-      logBundledSkillInstallPlan({
-        bundledSkillNames,
-        projectRoot,
-        scope,
-        supportedHosts,
-      });
-      cleanupState = await inspectInstalledSkillArtifactsForHosts({
-        projectRoot,
-        hostNames: supportedHosts,
-        scope,
-        skillNames: bundledSkillNames,
-      });
-      await installBundledSkillForHosts({
-        projectRoot,
-        hostNames: supportedHosts,
-        scope,
-        serverName,
-        serverUrl,
-        skillNames: bundledSkillNames,
-      });
-      if (unsupportedHosts.length > 0) {
-        log.plain(
-          `--install-skill skipped unsupported hosts (MCP-only): ${unsupportedHosts.join(", ")}.`,
-        );
-      }
-    }
-
-    let apiKey = null;
-    const explicitApiKeyProvided = Object.hasOwn(options, "apiKey");
-    const shouldResolveApiKey =
-      !oauthMode && (needsSetupHosts.length > 0 || explicitApiKeyProvided);
-    if (shouldResolveApiKey) {
-      apiKey = await resolveApiKey(options, baseUrl);
-      if (!apiKey) {
-        if (cleanupState) {
-          await cleanupInstalledSkillArtifactsForHosts({
-            projectRoot,
-            hostNames: supportedHosts,
-            priorState: cleanupState,
-            scope,
-            skillNames: bundledSkillNames,
-          });
-          cleanupState = null;
-        }
-        log.warn("Setup cancelled");
-        return { exitCode: 0 };
-      }
-    }
-
-    const setupResult = await runMcpSetupMode({
-      selectedHosts: hosts,
-      scope,
-      cwd: projectRoot,
-      // Prior-mode enforcement already ran before install/auth (above); skip
-      // the inner detector so a --force reconcile cannot re-uninstall the
-      // skills this command just installed, and so the non-force conflict
-      // path short-circuits before we reach this point.
-      force: false,
-      serverName,
-      serverUrl,
-      apiKey,
-      // Tell the writers to reconcile auth-mode mismatches (Authorization
-      // header added/removed) only when the user explicitly set `--oauth` or
-      // `--api-key`. Without that, a passive rerun must stay idempotent and
-      // preserve the existing bearer header on disk rather than stripping it.
-      enforceAuthMode: oauthMode || explicitApiKeyProvided,
-      detectPriorMode: async () => ({
-        priorMode: null,
-        affectedHosts: [],
-        entries: [],
-      }),
-      reconcilePriorMode: deps.reconcilePriorMode,
-    });
-    if (reconciled.length > 0) {
-      setupResult.reconciled = [
-        ...(Array.isArray(setupResult.reconciled)
-          ? setupResult.reconciled
-          : []),
-        ...reconciled,
-      ];
-    }
-
-    if (setupResult.exitCode !== 0) {
-      printSetupResultSummary(setupResult);
-      const failureDetails = setupResult.agentResults
-        .filter((result) => result.success !== true)
-        .flatMap((result) =>
-          Array.isArray(result.warnings) ? result.warnings : [],
-        )
-        .join(" | ");
-      const error = new Error(
-        failureDetails.length > 0
-          ? `MCP setup encountered host-level failures: ${failureDetails}`
-          : "MCP setup encountered host-level failures.",
-      );
-      error.exitCode = setupResult.exitCode;
-      throw error;
-    }
-
-    const setupRows = buildSetupResultRows({
-      selectedHosts: hosts,
-      hostStates,
-      setupResult,
-      oauthMode,
-    });
-
-    if (skillDecisionMode !== "guided") {
-      const completedCleanupState = cleanupState;
-      cleanupState = null;
-      await discardInstallSkillCleanupState(completedCleanupState);
-      const showSkillRefreshGuidance =
-        scope === "project" &&
-        skillDecisionMode === "install" &&
-        supportedHosts.length > 0;
-      printSetupResults(setupRows, scope, serverUrl, {
-        showSkillRefreshGuidance,
-        experimentalSyncAgents: showSkillRefreshGuidance
-          ? resolveExperimentalSyncAgentsForHosts(supportedHosts)
-          : [],
-      });
-      return setupResult;
-    }
-
-    if (supportedHosts.length === 0) {
-      log.plain(
-        `Bundled skill installation is unavailable for the selected hosts (${hosts.join(", ")}). Continuing with MCP-only setup.`,
-      );
-      printSetupResults(setupRows, scope, serverUrl);
-      return setupResult;
-    }
-
-    const shouldInstallSkill = await promptGuidedSkillInstall(
-      bundledSkillNames,
-      unsupportedHosts,
-      guidedSkillDecisionOverride,
-    );
-    if (!shouldInstallSkill) {
-      printSetupResults(setupRows, scope, serverUrl);
-      return setupResult;
-    }
-
-    if (installDriftHosts.length > 0) {
-      throw new Error(
-        formatInstallSkillDriftError({
-          hostName: installDriftHosts[0].hostName,
-          scope,
-          serverName,
-          existingUrl: installDriftHosts[0].existingUrl,
-          requestedUrl: serverUrl,
-        }),
-      );
-    }
-
-    logBundledSkillInstallPlan({
-      bundledSkillNames,
-      projectRoot,
-      scope,
-      supportedHosts,
-    });
-    cleanupState = await inspectInstalledSkillArtifactsForHosts({
-      projectRoot,
-      hostNames: supportedHosts,
-      scope,
-      skillNames: bundledSkillNames,
-    });
-    await installBundledSkillForHosts({
+  let apiKey = null;
+  const explicitApiKeyProvided = Object.hasOwn(options, "apiKey") || options.apiKeyStdin === true;
+  const shouldResolveApiKey =
+   !oauthMode && (needsSetupHosts.length > 0 || explicitApiKeyProvided);
+  if (shouldResolveApiKey) {
+   apiKey = authResult?.apiKey ?? await resolveApiKey(options, baseUrl);
+   if (!apiKey) {
+    if (cleanupState) {
+     await cleanupInstalledSkillArtifactsForHosts({
       projectRoot,
       hostNames: supportedHosts,
+      priorState: cleanupState,
       scope,
-      serverName,
-      serverUrl,
       skillNames: bundledSkillNames,
-    });
-    if (unsupportedHosts.length > 0) {
-      log.plain(
-        `Guided skill install skipped unsupported hosts (MCP-only): ${unsupportedHosts.join(", ")}.`,
-      );
-    }
-    const completedCleanupState = cleanupState;
-    cleanupState = null;
-    await discardInstallSkillCleanupState(completedCleanupState);
-    const showSkillRefreshGuidance =
-      scope === "project" && supportedHosts.length > 0;
-    printSetupResults(setupRows, scope, serverUrl, {
-      showSkillRefreshGuidance,
-      experimentalSyncAgents: showSkillRefreshGuidance
-        ? resolveExperimentalSyncAgentsForHosts(supportedHosts)
-        : [],
-    });
-    return setupResult;
-  } catch (error) {
-    if (cleanupState) {
-      await cleanupInstalledSkillArtifactsForHosts({
-        projectRoot,
-        hostNames: supportedHosts,
-        priorState: cleanupState,
-        scope,
-        skillNames: bundledSkillNames,
-      });
+     });
+     cleanupState = null;
     }
-    throw error;
+    log.warn("Setup cancelled");
+    return { exitCode: 0 };
+   }
+  }
+
+  const setupResult = await runMcpSetupMode({
+   selectedHosts: hosts,
+   scope,
+   cwd: projectRoot,
+   // Prior-mode enforcement already ran before install/auth (above); skip
+   // the inner detector so a --force reconcile cannot re-uninstall the
+   // skills this command just installed, and so the non-force conflict
+   // path short-circuits before we reach this point.
+   force: false,
+   serverName,
+   serverUrl,
+   apiKey,
+   privateCodexConfig: options.apiKeyStdin === true,
+   replaceExisting: options.force === true,
+   // Tell the writers to reconcile auth-mode mismatches (Authorization
+   // header added/removed) only when the user explicitly set `--oauth` or
+   // `--api-key`. Without that, a passive rerun must stay idempotent and
+   // preserve the existing bearer header on disk rather than stripping it.
+   enforceAuthMode: oauthMode || explicitApiKeyProvided,
+   detectPriorMode: async () => ({
+    priorMode: null,
+    affectedHosts: [],
+    entries: [],
+   }),
+   reconcilePriorMode: deps.reconcilePriorMode,
+  });
+  if (reconciled.length > 0) {
+   setupResult.reconciled = [
+    ...(Array.isArray(setupResult.reconciled)
+     ? setupResult.reconciled
+     : []),
+    ...reconciled,
+   ];
+  }
+
+  if (setupResult.exitCode !== 0) {
+   printSetupResultSummary(setupResult);
+   const failureDetails = setupResult.agentResults
+    .filter((result) => result.success !== true)
+    .flatMap((result) =>
+     Array.isArray(result.warnings) ? result.warnings : [],
+    )
+    .join(" | ");
+   const error = new Error(
+    failureDetails.length > 0
+     ? `MCP setup encountered host-level failures: ${failureDetails}`
+     : "MCP setup encountered host-level failures.",
+   );
+   error.exitCode = setupResult.exitCode;
+   throw error;
+  }
+
+  const setupRows = buildSetupResultRows({
+   selectedHosts: hosts,
+   hostStates,
+   setupResult,
+   oauthMode,
+  });
+
+  if (skillDecisionMode !== "guided") {
+   const completedCleanupState = cleanupState;
+   cleanupState = null;
+   await discardInstallSkillCleanupState(completedCleanupState);
+   const showSkillRefreshGuidance =
+    scope === "project" &&
+    skillDecisionMode === "install" &&
+    supportedHosts.length > 0;
+   printSetupResults(setupRows, scope, serverUrl, {
+    showSkillRefreshGuidance,
+    experimentalSyncAgents: showSkillRefreshGuidance
+     ? resolveExperimentalSyncAgentsForHosts(supportedHosts)
+     : [],
+   });
+   return setupResult;
+  }
+
+  if (supportedHosts.length === 0) {
+   log.plain(
+    `Bundled skill installation is unavailable for the selected hosts (${hosts.join(", ")}). Continuing with MCP-only setup.`,
+   );
+   printSetupResults(setupRows, scope, serverUrl);
+   return setupResult;
+  }
+
+  const shouldInstallSkill = await promptGuidedSkillInstall(
+   bundledSkillNames,
+   unsupportedHosts,
+   guidedSkillDecisionOverride,
+  );
+  if (!shouldInstallSkill) {
+   printSetupResults(setupRows, scope, serverUrl);
+   return setupResult;
+  }
+
+  if (installDriftHosts.length > 0) {
+   throw new Error(
+    formatInstallSkillDriftError({
+     hostName: installDriftHosts[0].hostName,
+     scope,
+     serverName,
+     existingUrl: installDriftHosts[0].existingUrl,
+     requestedUrl: serverUrl,
+    }),
+   );
+  }
+
+  logBundledSkillInstallPlan({
+   bundledSkillNames,
+   projectRoot,
+   scope,
+   supportedHosts,
+  });
+  cleanupState = await inspectInstalledSkillArtifactsForHosts({
+   projectRoot,
+   hostNames: supportedHosts,
+   scope,
+   skillNames: bundledSkillNames,
+  });
+  await installBundledSkillForHosts({
+   projectRoot,
+   hostNames: supportedHosts,
+   scope,
+   serverName,
+   serverUrl,
+   skillNames: bundledSkillNames,
+  });
+  if (unsupportedHosts.length > 0) {
+   log.plain(
+    `Guided skill install skipped unsupported hosts (MCP-only): ${unsupportedHosts.join(", ")}.`,
+   );
+  }
+  const completedCleanupState = cleanupState;
+  cleanupState = null;
+  await discardInstallSkillCleanupState(completedCleanupState);
+  const showSkillRefreshGuidance =
+   scope === "project" && supportedHosts.length > 0;
+  printSetupResults(setupRows, scope, serverUrl, {
+   showSkillRefreshGuidance,
+   experimentalSyncAgents: showSkillRefreshGuidance
+    ? resolveExperimentalSyncAgentsForHosts(supportedHosts)
+    : [],
+  });
+  return setupResult;
+ } catch (error) {
+  if (cleanupState) {
+   await cleanupInstalledSkillArtifactsForHosts({
+    projectRoot,
+    hostNames: supportedHosts,
+    priorState: cleanupState,
+    scope,
+    skillNames: bundledSkillNames,
+   });
   }
+  throw error;
+ }
 }