@paradigma-inc/flywheel 0.1.35 → 0.1.52

package/src/cli.mjs

@@ -1,10 +1,9 @@
 import { Command } from "commander";
-import { checkbox, confirm, select } from "@inquirer/prompts";
+import { checkbox, select } from "@inquirer/prompts";
 import ora from "ora";
 import pc from "picocolors";
-import { readFile, rm } from "node:fs/promises";
+import { readFile } from "node:fs/promises";
 import path from "node:path";
-import { randomBytes } from "node:crypto";
 
 import {
   ALL_HOST_NAMES,
@@ -15,8 +14,6 @@ import {
   normalizeHosts,
 } from "./agents.mjs";
 import {
-  appendTomlServer,
-  mergeServerEntry,
   readNamedConfigEntry,
   readJsonConfig,
   readTomlServerEntry,
@@ -28,35 +25,28 @@ import {
   writeYamlConfig,
 } from "./mcp-writer.mjs";
 import {
-  acquireApiKeyViaBrowserBridge,
-  acquireApiKeyViaDeviceFlow,
-  resolveSetupAuthMode,
-} from "./setup-auth.mjs";
-import {
-  cleanupInstalledSkillArtifactsForHosts,
-  formatSupportedInstallSkillHosts,
-  inspectInstalledSkillArtifactsForHosts,
-  installBundledSkillForHosts,
   listBundledSkills,
   partitionInstallSkillHosts,
   removeInstalledSkillsForHosts,
-  resolveSkillsAgentName,
   SUPPORTED_INSTALL_SKILL_HOSTS,
-  resolveInstalledSkillDir,
   resolvePackageRoot,
 } from "./skill-installer.mjs";
+import { normalizeSetupAuthMode } from "./setup-auth.mjs";
+import { runSetupRouter } from "./setup/command.mjs";
+import { SetupModeUsageError } from "./setup/mode.mjs";
+import { runCliSetupMode } from "./setup/modes/cli.mjs";
+import {
+  buildGuidedSkillInstallPrompt,
+  runMcpModeCommand,
+} from "./setup/modes/mcp-command.mjs";
+import { findFlywheelMcpEntryNames } from "./setup/shared/prior-mode-detect.mjs";
+import { renderSetupSummary } from "./setup/shared/summary.mjs";
+
+export { buildGuidedSkillInstallPrompt };
 
 const INSTALL_SKILL_BASE_URL = "https://flywheel.paradigma.inc";
 const DEFAULT_BASE_URL =
   process.env.FLYWHEEL_PUBLIC_BASE_URL || INSTALL_SKILL_BASE_URL;
-const NON_INTERACTIVE_SKILL_DECISION_ERROR =
-  "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.";
-const GUIDED_SKILL_DECISION_TEST_ENV =
-  "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}`)),
@@ -99,17 +89,7 @@ function normalizeServerName(value) {
 }
 
 function normalizeAuthMode(value) {
-  const normalized = String(value || "auto")
-    .trim()
-    .toLowerCase();
-  if (
-    normalized === "auto" ||
-    normalized === "loopback" ||
-    normalized === "device"
-  ) {
-    return normalized;
-  }
-  throw new Error("Auth mode must be one of: auto, loopback, device.");
+  return normalizeSetupAuthMode(value);
 }
 
 function selectedHostsFromOptions(options) {
@@ -124,6 +104,37 @@ function selectedHostsFromOptions(options) {
   return hosts;
 }
 
+const UNINSTALL_OPTION_KEY_BY_HOST = Object.freeze({
+  claude: "claude",
+  codex: "codex",
+  opencode: "opencode",
+  cursor: "cursor",
+  "pi-mono": "piMono",
+  "hermes-agent": "hermesAgent",
+  openclaw: "openclaw",
+});
+
+function buildUninstallOptionsForHosts({
+  hostNames = [],
+  scope = "project",
+  serverName = SERVER_NAME,
+} = {}) {
+  const options = {
+    yes: true,
+    scope,
+    name: serverName,
+  };
+
+  for (const hostName of hostNames) {
+    const optionKey = UNINSTALL_OPTION_KEY_BY_HOST[hostName];
+    if (optionKey) {
+      options[optionKey] = true;
+    }
+  }
+
+  return options;
+}
+
 function parseHostsList(value) {
   if (!value) return [];
   return normalizeHosts(
@@ -134,6 +145,10 @@ function parseHostsList(value) {
   );
 }
 
+function collectModeValues(value, previousValues = []) {
+  return [...previousValues, value];
+}
+
 function mcpCandidatesForScope(host, scope) {
   if (scope === "global") return host.mcp.globalPaths;
   return host.mcp.projectPaths.map((candidate) =>
@@ -171,95 +186,12 @@ async function readExistingServerState(hostName, scope, serverName) {
   };
 }
 
-async function inspectInstallSkillHosts({
-  hostNames,
-  scope,
-  serverName,
-  serverUrl,
-}) {
-  const hostStates = new Map();
-  const needsSetupHosts = [];
-  const driftHosts = [];
-
-  for (const hostName of hostNames) {
-    // 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 };
-}
-
-function formatInstallSkillDriftError({
-  hostName,
+async function promptHosts(
   scope,
+  detected,
   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.`;
-}
-
-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.`,
-  );
-}
-
-async function promptHosts(scope, detected, serverName) {
+  { disableAlreadyConfigured = true } = {},
+) {
   const choices = await Promise.all(
     ALL_HOST_NAMES.map(async (hostName) => {
       const configured = await isAlreadyConfigured(
@@ -271,12 +203,18 @@ async function promptHosts(scope, detected, serverName) {
         name: SETUP_HOST_NAMES[hostName],
         value: hostName,
         checked: detected.includes(hostName),
-        disabled: configured ? "(already configured)" : false,
+        disabled:
+          disableAlreadyConfigured && configured
+            ? "(already configured)"
+            : false,
       };
     }),
   );
 
-  if (choices.every((choice) => Boolean(choice.disabled))) {
+  if (
+    disableAlreadyConfigured &&
+    choices.every((choice) => Boolean(choice.disabled))
+  ) {
     log.info("Flywheel is already configured for all detected hosts.");
     return null;
   }
@@ -295,7 +233,12 @@ async function promptHosts(scope, detected, serverName) {
   }
 }
 
-async function resolveHosts(options, scope, serverName, allowPrompt = true) {
+async function resolveHosts(
+  options,
+  scope,
+  serverName,
+  { allowPrompt = true, disableAlreadyConfigured = true } = {},
+) {
   const explicit = selectedHostsFromOptions(options);
   if (explicit.length > 0) return explicit;
 
@@ -314,7 +257,9 @@ async function resolveHosts(options, scope, serverName, allowPrompt = true) {
   }
 
   log.blank();
-  const selected = await promptHosts(scope, detected, serverName);
+  const selected = await promptHosts(scope, detected, serverName, {
+    disableAlreadyConfigured,
+  });
   if (!selected) {
     log.warn("Setup cancelled");
     return [];
@@ -322,483 +267,152 @@ async function resolveHosts(options, scope, serverName, allowPrompt = true) {
   return selected;
 }
 
-async function resolveApiKey(options, baseUrl) {
-  if (Object.hasOwn(options, "apiKey")) {
-    const normalizedApiKey = String(options.apiKey || "").trim();
-    if (normalizedApiKey.length === 0) {
-      throw new Error("--api-key cannot be empty.");
-    }
-    return normalizedApiKey;
-  }
-
-  const requestedAuthMode = normalizeAuthMode(options.authMode || "auto");
-  const resolvedAuthMode = resolveSetupAuthMode({
-    requestedMode: requestedAuthMode,
-  });
-
-  const spinner = ora("Configuring authentication...").start();
-  try {
-    const keyName = `flywheel-setup-${randomBytes(3).toString("hex")}`;
-    const authResult =
-      resolvedAuthMode === "device"
-        ? await acquireApiKeyViaDeviceFlow({
-            baseUrl,
-            keyName,
-            verificationBaseUrl: baseUrl,
-          })
-        : await acquireApiKeyViaBrowserBridge({
-            baseUrl,
-            keyName,
-          });
-    spinner.succeed(`Authenticated (${resolvedAuthMode})`);
-    return authResult.apiKey;
-  } catch (error) {
-    spinner.fail("Authentication failed");
-    const message =
-      error instanceof Error ? error.message : "Authentication failed.";
-    if (resolvedAuthMode === "loopback" && requestedAuthMode === "auto") {
-      throw new Error(`${message} Try --auth-mode device on remote shells.`);
-    }
-    throw new Error(message);
-  }
-}
-
-async function setupHost(hostName, scope, serverUrl, apiKey, serverName) {
-  const host = getHost(hostName);
-  const mcpPath = await resolveMcpPath(mcpCandidatesForScope(host, scope));
-
-  if (host.mcp.configType === "toml") {
-    const { alreadyExists } = await appendTomlServer(
-      mcpPath,
-      serverName,
-      host.mcp.buildEntry({ serverUrl, apiKey }),
-    );
-    return {
-      host: host.displayName,
-      status: alreadyExists ? "already configured" : "configured with API Key",
-      filePath: mcpPath,
-    };
-  }
-
-  const existing =
-    host.mcp.configType === "yaml"
-      ? await readYamlConfig(mcpPath)
-      : await readJsonConfig(mcpPath);
-  const { config, alreadyExists } = mergeServerEntry(
-    existing,
-    host.mcp.configKey,
-    serverName,
-    host.mcp.buildEntry({ serverUrl, apiKey }),
-  );
-  if (config !== existing) {
-    if (host.mcp.configType === "yaml") {
-      await writeYamlConfig(mcpPath, config);
-    } else {
-      await writeJsonConfig(mcpPath, config);
-    }
-  }
+export function buildSetupModePromptConfig() {
   return {
-    host: host.displayName,
-    status: alreadyExists ? "already configured" : "configured with API Key",
-    filePath: mcpPath,
+    message: "How should your agent access Flywheel?",
+    choices: [
+      {
+        name: `MCP + bundled skills\n  ${pc.dim("Agent calls Flywheel tools via MCP protocol to manage nodes, artifacts, and compute")}`,
+        value: "mcp",
+      },
+      {
+        name: `CLI + bundled skills\n  ${pc.dim("Agent shells out to the flywheel binary to manage nodes, artifacts, and compute")}`,
+        value: "cli",
+      },
+    ],
+    default: "mcp",
+    theme: CHECKBOX_THEME,
   };
 }
 
-function printSetupResults(
-  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("  Bundled skill refresh guidance");
-    log.plain(
-      `    Preferred: ${pc.bold("npx --yes @paradigma-inc/flywheel@latest setup --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(`npx skills experimental_sync --agent ${agentName} -y`)}`,
-        );
-      }
-    }
-  }
-  log.blank();
+async function promptSetupMode() {
+  return await select(buildSetupModePromptConfig());
 }
 
-function resolveExperimentalSyncAgentsForHosts(supportedHosts) {
-  const agentNames = [];
-  const seenAgentNames = new Set();
-
-  for (const hostName of supportedHosts) {
-    const agentName = resolveSkillsAgentName(hostName);
-    if (seenAgentNames.has(agentName)) {
-      continue;
-    }
-    seenAgentNames.add(agentName);
-    agentNames.push(agentName);
-  }
-
-  return agentNames;
-}
-
-async function promptGuidedSkillInstall(
-  bundledSkillNames,
-  unsupportedHosts,
-  guidedDecisionOverride = "",
-) {
-  if (guidedDecisionOverride === "accept") {
-    return true;
-  }
-  if (
-    guidedDecisionOverride === "decline" ||
-    guidedDecisionOverride === "abort"
-  ) {
-    return false;
-  }
-
-  const message = buildGuidedSkillInstallPrompt({
-    unsupportedHosts,
-    bundledSkillNames,
-  });
-
-  try {
-    return await confirm({
-      message,
-      default: true,
-      theme: CHECKBOX_THEME,
-    });
-  } catch {
-    return false;
-  }
-}
-
-export function buildGuidedSkillInstallPrompt({
-  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.`;
-  }
-  return usesPlural
-    ? "Also install or refresh the bundled Flywheel skills?"
-    : "Also install or refresh the bundled Flywheel skill?";
-}
-
-function logBundledSkillInstallPlan({
-  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(", ")}`,
-    );
-  }
-}
-
-function normalizeSkillDecisionMode(options) {
+function validateCliModeSkillFlags(options) {
   if (options.installSkill && options.skipSkill) {
-    throw new Error(MUTUALLY_EXCLUSIVE_SKILL_FLAGS_ERROR);
+    throw new SetupModeUsageError(
+      "--install-skill and --skip-skill cannot be used together.",
+    );
   }
-  if (options.installSkill) return "install";
-  if (options.skipSkill) return "skip";
-  return "guided";
-}
-
-async function discardInstallSkillCleanupState(cleanupState) {
-  if (!cleanupState?.backupRoot) {
-    return null;
+  // CLI mode is intentionally "skills only", so --skip-skill would contradict
+  // the mode contract and silently surprising behavior should be rejected.
+  if (options.skipSkill) {
+    throw new SetupModeUsageError(
+      "--skip-skill is not supported with --mode cli; use --mode mcp --skip-skill for MCP-only setup.",
+    );
   }
-  await rm(cleanupState.backupRoot, { force: true, recursive: true });
-  return null;
 }
 
-async function runSetupCommand(options) {
-  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);
-  }
-
+async function runCliModeCommand(options) {
+  validateCliModeSkillFlags(options);
   const scope = options.project ? "project" : "global";
   const baseUrl = normalizeBaseUrl(options.baseUrl || DEFAULT_BASE_URL);
   const serverUrl = `${baseUrl}/mcp-server`;
   const serverName = normalizeServerName(options.name || SERVER_NAME);
-  const hosts = await resolveHosts(
-    options,
-    scope,
-    serverName,
-    skillDecisionMode === "guided",
-  );
-  if (hosts.length === 0) return;
-
-  const { supportedHosts, unsupportedHosts } =
-    partitionInstallSkillHosts(hosts);
-  const packageRoot = resolvePackageRoot();
-  const bundledSkillNames =
-    skillDecisionMode === "skip" || supportedHosts.length === 0
-      ? []
-      : await listBundledSkills(packageRoot);
-
-  if (skillDecisionMode === "install" && supportedHosts.length === 0) {
-    throw new Error(
-      `--install-skill is not supported for: ${unsupportedHosts.join(", ")}. Supported hosts: ${formatSupportedInstallSkillHosts()}.`,
-    );
-  }
-  if (
-    skillDecisionMode !== "skip" &&
-    supportedHosts.length > 0 &&
-    bundledSkillNames.length === 0
-  ) {
-    throw new Error(`No bundled skills found under ${path.join(packageRoot, "skills")}.`);
+  const hosts = await resolveHosts(options, scope, serverName, {
+    allowPrompt: true,
+    // CLI mode is a skills refresh/install path, so existing MCP wiring should
+    // not make hosts ineligible for selection.
+    disableAlreadyConfigured: false,
+  });
+  if (hosts.length === 0) {
+    return { exitCode: 0 };
   }
 
-  const {
-    hostStates = new Map(),
-    needsSetupHosts = [],
-    driftHosts = [],
-  } = await inspectInstallSkillHosts({
-    hostNames: hosts,
+  const result = await runCliSetupMode({
+    selectedHosts: hosts,
     scope,
+    cwd: process.cwd(),
+    force: options.force === true,
+    apiKey: options.apiKey,
+    authMode: options.authMode,
+    baseUrl,
     serverName,
     serverUrl,
-  });
-
-  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,
-      }),
-    );
-  }
-
-  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(", ")}.`,
-        );
-      }
-    }
-
-    const hostsNeedingSetup = needsSetupHosts;
-    let apiKey = null;
-    if (hostsNeedingSetup.length > 0) {
-      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;
-      }
-    }
-
-    let setupResults = [];
-    const spinner = ora("Setting up Flywheel MCP...").start();
-    try {
-      const results = [];
-      for (const hostName of hosts) {
-        if (!needsSetupHosts.includes(hostName)) {
-          results.push({
-            host: getHost(hostName).displayName,
-            status: "already configured",
-            filePath: hostStates.get(hostName).mcpPath,
-          });
-          continue;
-        }
-
-        spinner.text = `Setting up ${getHost(hostName).displayName}...`;
+    reconcilePriorMode: async ({ hostNames, serverNames }) => {
+      // Uninstall each detected server name so renamed/drifted Flywheel MCP
+      // entries are actually removed. When the detector found no explicit
+      // names (prior CLI artifacts case), fall back to the current request's
+      // --name so the skill cleanup path still runs.
+      const targetNames =
+        Array.isArray(serverNames) && serverNames.length > 0
+          ? serverNames
+          : [serverName];
+      for (const targetName of targetNames) {
         // eslint-disable-next-line no-await-in-loop
-        results.push(
-          await setupHost(hostName, scope, serverUrl, apiKey, serverName),
+        await runUninstallCommand(
+          buildUninstallOptionsForHosts({
+            hostNames,
+            scope,
+            serverName: targetName,
+          }),
         );
       }
-      spinner.succeed("MCP setup complete");
-      setupResults = results;
-    } catch (error) {
-      spinner.fail("Setup failed");
-      throw error;
-    }
-
-    if (skillDecisionMode !== "guided") {
-      const completedCleanupState = cleanupState;
-      cleanupState = null;
-      await discardInstallSkillCleanupState(completedCleanupState);
-      const showSkillRefreshGuidance =
-        scope === "project" &&
-        skillDecisionMode === "install" &&
-        supportedHosts.length > 0;
-      printSetupResults(
-        setupResults,
-        scope,
-        serverUrl,
-        {
-          showSkillRefreshGuidance,
-          experimentalSyncAgents: showSkillRefreshGuidance
-            ? resolveExperimentalSyncAgentsForHosts(supportedHosts)
-            : [],
-        },
-      );
-      return;
-    }
+    },
+  });
 
-    if (supportedHosts.length === 0) {
-      log.plain(
-        `Bundled skill installation is unavailable for the selected hosts (${hosts.join(", ")}). Continuing with MCP-only setup.`,
-      );
-      printSetupResults(setupResults, scope, serverUrl);
-      return;
-    }
+  const lines = renderSetupSummary(result);
+  log.blank();
+  for (const line of lines) {
+    log.plain(`  ${line}`);
+  }
+  log.blank();
 
-    const shouldInstallSkill = await promptGuidedSkillInstall(
-      bundledSkillNames,
-      unsupportedHosts,
-      guidedSkillDecisionOverride,
+  if (result.exitCode !== 0) {
+    const failureDetails = result.agentResults
+      .filter((agentResult) => agentResult.success !== true)
+      .flatMap((agentResult) =>
+        Array.isArray(agentResult.warnings) ? agentResult.warnings : [],
+      )
+      .join(" | ");
+    const error = new Error(
+      failureDetails.length > 0
+        ? `CLI setup encountered host-level failures: ${failureDetails}`
+        : "CLI setup encountered host-level failures.",
     );
-    if (!shouldInstallSkill) {
-      printSetupResults(setupResults, scope, serverUrl);
-      return;
-    }
-
-    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(setupResults, scope, serverUrl, {
-      showSkillRefreshGuidance,
-      experimentalSyncAgents: showSkillRefreshGuidance
-        ? resolveExperimentalSyncAgentsForHosts(supportedHosts)
-        : [],
-    });
-  } catch (error) {
-    if (cleanupState) {
-      await cleanupInstalledSkillArtifactsForHosts({
-        projectRoot,
-        hostNames: supportedHosts,
-        priorState: cleanupState,
-        scope,
-        skillNames: bundledSkillNames,
-      });
-    }
+    error.exitCode = result.exitCode;
     throw error;
   }
+
+  return result;
+}
+
+async function runSetupCommandViaRouter(options) {
+  return await runSetupRouter(options, {
+    isInteractive: process.stdin.isTTY === true && process.stdout.isTTY === true,
+    promptMode: promptSetupMode,
+    runMcpMode: async () =>
+      await runMcpModeCommand(options, {
+        force: options.force === true,
+        reconcilePriorMode: async ({
+          hostNames,
+          serverNames,
+          scope: reconcileScope,
+          serverName: requestedServerName,
+        }) => {
+          // Prior CLI artifacts have no MCP entry name, so fall back to the
+          // current request's --name for the skill uninstall path. Prior MCP
+          // entries may carry drifted names; uninstall each detected name so
+          // the reconcile actually removes what we detected.
+          const targetNames =
+            Array.isArray(serverNames) && serverNames.length > 0
+              ? serverNames
+              : [requestedServerName];
+          for (const targetName of targetNames) {
+            // eslint-disable-next-line no-await-in-loop
+            await runUninstallCommand(
+              buildUninstallOptionsForHosts({
+                hostNames,
+                scope: reconcileScope,
+                serverName: targetName,
+              }),
+            );
+          }
+        },
+      }),
+    runCliMode: async () => await runCliModeCommand(options),
+  });
 }
 
 function parseUninstallScope(value) {
@@ -919,16 +533,47 @@ async function resolveHostsWithRemainingFlywheelMcpEntries({ scope }) {
   return remainingHosts;
 }
 
-async function isConfiguredForUninstallScope(hostName, scope, serverName) {
+async function findFlywheelServerNamesOnHost(hostName, scope) {
+  // Mirror setup's prior-mode detector: walk every MCP entry on the host and
+  // keep those whose URL is Flywheel-identifying (hostname contains "flywheel"
+  // or path === /mcp-server with a matching target origin). Uninstall must
+  // catch renamed/drifted entries (e.g. `[mcp_servers.flywheel-staging]`) that
+  // setup already detects; otherwise a user whose host has a non-default entry
+  // name is stuck between setup ("already installed") and uninstall ("not
+  // configured").
+  return await findFlywheelMcpEntryNames({ hostName, scope }).catch(() => []);
+}
+
+async function resolveUninstallServerNamesForHost(
+  hostName,
+  scope,
+  { explicitServerName },
+) {
+  if (explicitServerName) {
+    const configured = await isAlreadyConfigured(
+      hostName,
+      scope,
+      explicitServerName,
+    ).catch(() => false);
+    return configured ? [explicitServerName] : [];
+  }
+  return await findFlywheelServerNamesOnHost(hostName, scope);
+}
+
+async function isConfiguredForUninstallScope(
+  hostName,
+  scope,
+  { explicitServerName },
+) {
   const scopes = scopesFromUninstallScope(scope);
   for (const singleScope of scopes) {
     // eslint-disable-next-line no-await-in-loop
-    const configured = await isAlreadyConfigured(
+    const targets = await resolveUninstallServerNamesForHost(
       hostName,
       singleScope,
-      serverName,
-    ).catch(() => false);
-    if (configured) return true;
+      { explicitServerName },
+    );
+    if (targets.length > 0) return true;
   }
   return false;
 }
@@ -950,14 +595,12 @@ async function promptUninstallScope(defaultScope) {
   }
 }
 
-async function promptUninstallHosts(scope, serverName) {
+async function promptUninstallHosts(scope, { explicitServerName }) {
   const choices = await Promise.all(
     ALL_HOST_NAMES.map(async (hostName) => {
-      const configured = await isConfiguredForUninstallScope(
-        hostName,
-        scope,
-        serverName,
-      );
+      const configured = await isConfiguredForUninstallScope(hostName, scope, {
+        explicitServerName,
+      });
       return {
         name: SETUP_HOST_NAMES[hostName],
         value: hostName,
@@ -986,7 +629,7 @@ async function promptUninstallHosts(scope, serverName) {
   }
 }
 
-async function resolveUninstallTargets(options, serverName) {
+async function resolveUninstallTargets(options, { explicitServerName }) {
   const explicitHostsFromFlags = selectedHostsFromOptions(options);
   const explicitHostsFromList =
     explicitHostsFromFlags.length === 0 ? parseHostsList(options.hosts) : [];
@@ -1015,7 +658,9 @@ async function resolveUninstallTargets(options, serverName) {
     }
 
     if (!hasExplicitHosts) {
-      const selectedHosts = await promptUninstallHosts(scope, serverName);
+      const selectedHosts = await promptUninstallHosts(scope, {
+        explicitServerName,
+      });
       if (!selectedHosts) {
         log.warn("Uninstall cancelled");
         return null;
@@ -1069,8 +714,13 @@ async function removeHostConfig(hostName, scope, serverName) {
 }
 
 async function runUninstallCommand(options) {
-  const serverName = normalizeServerName(options.name || SERVER_NAME);
-  const resolved = await resolveUninstallTargets(options, serverName);
+  const explicitServerName =
+    typeof options.name === "string" && options.name.trim().length > 0
+      ? normalizeServerName(options.name)
+      : null;
+  const resolved = await resolveUninstallTargets(options, {
+    explicitServerName,
+  });
   if (!resolved) return;
   const { scope, hosts } = resolved;
   const scopes = scopesFromUninstallScope(scope);
@@ -1080,8 +730,35 @@ async function runUninstallCommand(options) {
   for (const singleScope of scopes) {
     for (const host of hosts) {
       mcpSpinner.text = `Removing from ${getHost(host).displayName} (${singleScope})...`;
+      // Resolve the concrete server name(s) to remove at the host/scope level.
+      // When --name was not given, this iterates every Flywheel-identifying
+      // entry (matching setup's prior-mode detector) so renamed or drifted
+      // entries (e.g. `[mcp_servers.flywheel-staging]`) are actually cleared.
       // eslint-disable-next-line no-await-in-loop
-      mcpResults.push(await removeHostConfig(host, singleScope, serverName));
+      const targetNames = await resolveUninstallServerNamesForHost(
+        host,
+        singleScope,
+        { explicitServerName },
+      );
+      if (targetNames.length === 0) {
+        // eslint-disable-next-line no-await-in-loop
+        const hostForDisplay = getHost(host);
+        // eslint-disable-next-line no-await-in-loop
+        const filePath = await resolveMcpPath(
+          mcpCandidatesForScope(hostForDisplay, singleScope),
+        );
+        mcpResults.push({
+          host: hostForDisplay.displayName,
+          scope: singleScope,
+          filePath,
+          status: "not present",
+        });
+        continue;
+      }
+      for (const targetName of targetNames) {
+        // eslint-disable-next-line no-await-in-loop
+        mcpResults.push(await removeHostConfig(host, singleScope, targetName));
+      }
     }
   }
   mcpSpinner.succeed("MCP uninstall complete");
@@ -1199,12 +876,12 @@ function buildProgram() {
       "after",
       `
 Examples:
-  ${pc.green("npx --yes @paradigma-inc/flywheel setup")}
-  ${pc.green("npx --yes @paradigma-inc/flywheel setup --install-skill")}
-  ${pc.green("npx --yes @paradigma-inc/flywheel setup --skip-skill")}
-  ${pc.green("npx --yes @paradigma-inc/flywheel setup --auth-mode device --codex --project")}
-  ${pc.green("npx --yes @paradigma-inc/flywheel setup --codex --project")}
-  ${pc.green("npx --yes @paradigma-inc/flywheel setup --yes --codex --claude --cursor")}
+  ${pc.green("npx --yes @paradigma-inc/flywheel setup --mode mcp")}
+  ${pc.green("npx --yes @paradigma-inc/flywheel setup --mode mcp --install-skill")}
+  ${pc.green("npx --yes @paradigma-inc/flywheel setup --mode mcp --skip-skill")}
+  ${pc.green("npx --yes @paradigma-inc/flywheel setup --mode mcp --auth-mode device --codex --project")}
+  ${pc.green("npx --yes @paradigma-inc/flywheel setup --mode cli --codex --project")}
+  ${pc.green("npx --yes @paradigma-inc/flywheel setup --mode mcp --yes --codex --claude --cursor")}
   ${pc.green(
     "npx --yes @paradigma-inc/flywheel uninstall --scope all --hosts codex,claude,opencode,cursor,pi-mono,hermes-agent,openclaw",
   )}
@@ -1214,6 +891,14 @@ Examples:
   program
     .command("setup")
     .description("Set up Flywheel for your AI coding host")
+    .option(
+      "--mode <mode>",
+      "Install mode: mcp | cli (required in non-interactive; prompted in TTY, default: mcp)",
+      collectModeValues,
+      [],
+    )
+    .option("--mcp", "Alias for --mode mcp")
+    .option("--cli", "Alias for --mode cli")
     .option("--claude", "Set up for Claude Code")
     .option("--opencode", "Set up for OpenCode")
     .option("--codex", "Set up for Codex")
@@ -1226,6 +911,7 @@ Examples:
       "Configure for current project instead of globally",
     )
     .option("-y, --yes", "Skip host selection prompts")
+    .option("--force", "Reconcile prior install mode automatically via uninstall")
     .option("--api-key <key>", "Use API key authentication")
     .option(
       "--auth-mode <mode>",
@@ -1241,7 +927,7 @@ Examples:
     )
     .option("--name <name>", `MCP server name (default: ${SERVER_NAME})`)
     .action(async (options) => {
-      await runSetupCommand(options);
+      await runSetupCommandViaRouter(options);
     });
 
   program