@paradigma-inc/flywheel 0.1.53 → 0.1.72

package/src/cli.mjs

@@ -2,18 +2,21 @@ import { Command } from "commander";
 import { checkbox, select } from "@inquirer/prompts";
 import ora from "ora";
 import pc from "picocolors";
-import { readFile } from "node:fs/promises";
+import { access, readFile, rm } from "node:fs/promises";
 import path from "node:path";
 
 import {
   ALL_HOST_NAMES,
   SERVER_NAME,
   SETUP_HOST_NAMES,
+  SKILL_ONLY_HOST_NAMES,
   detectHosts,
   getHost,
+  isSkillOnlyHost,
   normalizeHosts,
 } from "./agents.mjs";
 import {
+  readEntryServerUrl,
   readNamedConfigEntry,
   readJsonConfig,
   readTomlServerEntry,
@@ -28,10 +31,13 @@ import {
   listBundledSkills,
   partitionInstallSkillHosts,
   removeInstalledSkillsForHosts,
+  resolveInstalledSkillDir,
+  resolveFlywheelInstalledMarkerPath,
   SUPPORTED_INSTALL_SKILL_HOSTS,
   resolvePackageRoot,
 } from "./skill-installer.mjs";
 import { normalizeSetupAuthMode } from "./setup-auth.mjs";
+import { resolveSetupBaseUrl } from "./setup/base-url.mjs";
 import { runSetupRouter } from "./setup/command.mjs";
 import { SetupModeUsageError } from "./setup/mode.mjs";
 import { runCliSetupMode } from "./setup/modes/cli.mjs";
@@ -42,11 +48,17 @@ import {
 import { findFlywheelMcpEntryNames } from "./setup/shared/prior-mode-detect.mjs";
 import { renderSetupSummary } from "./setup/shared/summary.mjs";
 
+async function pathExists(targetPath) {
+  try {
+    await access(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 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 log = {
   info: (message) => console.log(pc.cyan(message)),
   warn: (message) => console.log(pc.yellow(`⚠ ${message}`)),
@@ -62,6 +74,12 @@ const CHECKBOX_THEME = {
   },
 };
 
+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.";
+}
+
 function normalizeBaseUrl(value) {
   const normalized = String(value || "").trim();
   let parsedUrl;
@@ -95,9 +113,12 @@ function normalizeAuthMode(value) {
 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.cursor) hosts.push("cursor");
+  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");
@@ -109,6 +130,9 @@ const UNINSTALL_OPTION_KEY_BY_HOST = Object.freeze({
   codex: "codex",
   opencode: "opencode",
   cursor: "cursor",
+  gemini: "gemini",
+  universal: "universal",
+  antigravity: "antigravity",
   "pi-mono": "piMono",
   "hermes-agent": "hermesAgent",
   openclaw: "openclaw",
@@ -167,6 +191,9 @@ async function isAlreadyConfigured(hostName, scope, serverName) {
 
 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") {
@@ -181,7 +208,7 @@ async function readExistingServerState(hostName, scope, serverName) {
   const entry = readNamedConfigEntry(existing, host.mcp.configKey, serverName);
   return {
     exists: entry !== null,
-    url: typeof entry?.url === "string" ? entry.url : null,
+    url: readEntryServerUrl(entry),
     mcpPath,
   };
 }
@@ -202,6 +229,11 @@ async function promptHosts(
       return {
         name: SETUP_HOST_NAMES[hostName],
         value: hostName,
+        short: SETUP_HOST_NAMES[hostName],
+        description: hostChoiceDescription({
+          detected: detected.includes(hostName),
+          configured,
+        }),
         checked: detected.includes(hostName),
         disabled:
           disableAlreadyConfigured && configured
@@ -272,15 +304,23 @@ export function buildSetupModePromptConfig() {
     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")}`,
+        name: "MCP + bundled skills",
         value: "mcp",
+        short: "MCP + skills",
+        description:
+          "Configure MCP tools plus bundled skills for supported AI hosts.",
       },
       {
-        name: `CLI + bundled skills\n  ${pc.dim("Agent shells out to the flywheel binary to manage nodes, artifacts, and compute")}`,
+        name: "CLI + bundled skills",
         value: "cli",
+        short: "CLI + skills",
+        description:
+          "Install bundled skills for agents that call the flywheel binary.",
       },
     ],
     default: "mcp",
+    loop: false,
+    pageSize: 4,
     theme: CHECKBOX_THEME,
   };
 }
@@ -289,7 +329,19 @@ async function promptSetupMode() {
   return await select(buildSetupModePromptConfig());
 }
 
-function validateCliModeSkillFlags(options) {
+/**
+ * Validate the flag combination for --mode cli. Rejections raise
+ * `SetupModeUsageError` so the top-level handler reports them as usage
+ * errors (exit code 2) and not as operational failures.
+ *
+ * `--oauth` controls the MCP config written in --mode mcp (it omits the
+ * Authorization header so the IDE can discover MCP 2.0 OAuth instead).
+ * --mode cli writes no MCP config at all, so there is nothing for --oauth
+ * to modify. Silently accepting it would look successful but still fall
+ * back to API-key auth in the runtime config — a misconfiguration. Reject
+ * it up front with guidance toward the correct invocation.
+ */
+function validateCliModeFlags(options) {
   if (options.installSkill && options.skipSkill) {
     throw new SetupModeUsageError(
       "--install-skill and --skip-skill cannot be used together.",
@@ -302,12 +354,19 @@ function validateCliModeSkillFlags(options) {
       "--skip-skill is not supported with --mode cli; use --mode mcp --skip-skill for MCP-only setup.",
     );
   }
+  if (options.oauth === true) {
+    throw new SetupModeUsageError(
+      "--oauth is not supported with --mode cli. --oauth only affects the MCP config written by --mode mcp; re-run with --mode mcp --oauth, or drop --oauth for a CLI-mode setup.",
+    );
+  }
 }
 
 async function runCliModeCommand(options) {
-  validateCliModeSkillFlags(options);
+  validateCliModeFlags(options);
   const scope = options.project ? "project" : "global";
-  const baseUrl = normalizeBaseUrl(options.baseUrl || DEFAULT_BASE_URL);
+  const baseUrl = normalizeBaseUrl(
+    resolveSetupBaseUrl({ explicitBaseUrl: options.baseUrl }),
+  );
   const serverUrl = `${baseUrl}/mcp-server`;
   const serverName = normalizeServerName(options.name || SERVER_NAME);
   const hosts = await resolveHosts(options, scope, serverName, {
@@ -380,7 +439,8 @@ async function runCliModeCommand(options) {
 
 async function runSetupCommandViaRouter(options) {
   return await runSetupRouter(options, {
-    isInteractive: process.stdin.isTTY === true && process.stdout.isTTY === true,
+    isInteractive:
+      process.stdin.isTTY === true && process.stdout.isTTY === true,
     promptMode: promptSetupMode,
     runMcpMode: async () =>
       await runMcpModeCommand(options, {
@@ -460,8 +520,12 @@ function readConfigSection(config, configKey) {
 
 function parseTomlServerNames(tomlText) {
   const serverNames = new Set();
-  for (const line of String(tomlText || "").replace(/\r\n/g, "\n").split("\n")) {
-    const match = line.trim().match(/^\[mcp_servers\.([A-Za-z0-9_-]+)\](?:\s*#.*)?$/);
+  for (const line of String(tomlText || "")
+    .replace(/\r\n/g, "\n")
+    .split("\n")) {
+    const match = line
+      .trim()
+      .match(/^\[mcp_servers\.([A-Za-z0-9_-]+)\](?:\s*#.*)?$/);
     if (!match) {
       continue;
     }
@@ -484,6 +548,9 @@ function isLikelyFlywheelMcpUrl(url) {
 
 async function listHostMcpEntries(hostName, scope) {
   const host = getHost(hostName);
+  if (isSkillOnlyHost(host)) {
+    return [];
+  }
   const filePath = await resolveMcpPath(mcpCandidatesForScope(host, scope));
 
   if (host.mcp.configType === "toml") {
@@ -514,10 +581,13 @@ async function listHostMcpEntries(hostName, scope) {
       : await readJsonConfig(filePath);
   const section = readConfigSection(config, host.mcp.configKey);
   return Object.entries(section)
-    .filter(([, entry]) => entry && typeof entry === "object" && !Array.isArray(entry))
+    .filter(
+      ([, entry]) =>
+        entry && typeof entry === "object" && !Array.isArray(entry),
+    )
     .map(([serverName, entry]) => ({
       serverName,
-      url: typeof entry.url === "string" ? entry.url : null,
+      url: readEntryServerUrl(entry),
     }));
 }
 
@@ -525,7 +595,9 @@ async function resolveHostsWithRemainingFlywheelMcpEntries({ scope }) {
   const remainingHosts = [];
   for (const hostName of SUPPORTED_INSTALL_SKILL_HOSTS) {
     // eslint-disable-next-line no-await-in-loop
-    const hostEntries = await listHostMcpEntries(hostName, scope).catch(() => []);
+    const hostEntries = await listHostMcpEntries(hostName, scope).catch(
+      () => [],
+    );
     if (hostEntries.some((entry) => isLikelyFlywheelMcpUrl(entry.url))) {
       remainingHosts.push(hostName);
     }
@@ -533,14 +605,68 @@ async function resolveHostsWithRemainingFlywheelMcpEntries({ scope }) {
   return remainingHosts;
 }
 
+/**
+ * Determine which non-uninstalled hosts still claim bundled skill artifacts
+ * via their install marker, and therefore must keep their (possibly shared)
+ * skill directories intact.
+ *
+ * The install marker (`.flywheel-installed-by-<host>`) is written by
+ * `installBundledSkillForHosts` for any host whose install path produces no
+ * MCP entry:
+ *
+ *   - skill-only hosts (universal, antigravity): marker always written.
+ *   - MCP-capable hosts (codex, opencode, cursor, claude, pi-mono, openclaw,
+ *     gemini): marker written ONLY when the host was installed via
+ *     `--mode cli`, because CLI-mode installs write no MCP entry.
+ *
+ * A marker at a skill-root is therefore the unambiguous "this host still
+ * owns these skills" signal for both categories. Narrowing the retain pass
+ * to skill-only hosts would let `uninstall --universal` silently wipe the
+ * shared `.agents/skills/` dir out from under a still-installed CLI-mode
+ * codex. Using dir existence alone would over-retain for hosts that never
+ * installed anything. The per-host marker resolves both.
+ *
+ * `excludedHostNames` is the list of hosts currently being uninstalled;
+ * their markers will be removed and their artifacts are expected to go, so
+ * they are excluded from retention here.
+ */
+async function resolveSkillOnlyHostsRetainingArtifacts({
+  scope,
+  excludedHostNames = [],
+}) {
+  const excluded = new Set(excludedHostNames);
+  const retained = [];
+  for (const hostName of SUPPORTED_INSTALL_SKILL_HOSTS) {
+    if (excluded.has(hostName)) continue;
+    let markerPath;
+    try {
+      markerPath = resolveFlywheelInstalledMarkerPath(
+        process.cwd(),
+        hostName,
+        scope,
+      );
+    } catch {
+      // Host isn't registered with the flywheel skill installer; no marker
+      // to consult, nothing to retain.
+      continue;
+    }
+    // eslint-disable-next-line no-await-in-loop
+    const markerExists = await pathExists(markerPath);
+    if (markerExists) {
+      retained.push(hostName);
+    }
+  }
+  return retained;
+}
+
 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").
+  // catch renamed or drifted entries (e.g. a non-default TOML section name
+  // under `[mcp_servers.*]`) 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(() => []);
 }
 
@@ -574,10 +700,92 @@ async function isConfiguredForUninstallScope(
       { explicitServerName },
     );
     if (targets.length > 0) return true;
+    // Skill-only hosts and CLI-mode MCP-capable hosts never write an MCP
+    // entry, so the sweep above finds nothing for them. Fall back to the
+    // install marker: if this host wrote its own ownership marker in the
+    // selected scope, it IS configured for the purposes of the uninstall
+    // prompt.
+    if (SUPPORTED_INSTALL_SKILL_HOSTS.includes(hostName)) {
+      try {
+        const markerPath = resolveFlywheelInstalledMarkerPath(
+          process.cwd(),
+          hostName,
+          singleScope,
+        );
+        // eslint-disable-next-line no-await-in-loop
+        if (await pathExists(markerPath)) return true;
+      } catch {
+        // Host isn't registered with the skill installer; nothing to check.
+      }
+    }
   }
   return false;
 }
 
+/**
+ * Public wrapper exposing the uninstall-eligibility check used by the
+ * interactive prompt. Returns true when the host has either a Flywheel MCP
+ * entry OR a Flywheel install marker in the requested scope. Exported so
+ * tests can verify that skill-only hosts surface as configurable in the
+ * prompt even though they write no MCP entry.
+ */
+export async function isHostConfiguredForUninstall({
+  hostName,
+  scope = "project",
+  serverName = SERVER_NAME,
+} = {}) {
+  // Mirror `runUninstallCommand`'s derivation: only treat the caller's
+  // `serverName` as "explicit" when it differs from the package default.
+  // An explicit name short-circuits the Flywheel-identifying sweep in
+  // `resolveUninstallServerNamesForHost`, which the default-named case
+  // needs to run so drifted entries (and the marker fallback for
+  // skill-only / CLI-mode hosts) are reachable.
+  const explicitServerName =
+    typeof serverName === "string" &&
+    serverName.length > 0 &&
+    serverName !== SERVER_NAME
+      ? serverName
+      : null;
+  return isConfiguredForUninstallScope(hostName, scope, { explicitServerName });
+}
+
+/**
+ * Remove every Flywheel install marker for the requested hosts across the
+ * requested scopes. Exported and implemented as a standalone helper so it
+ * can run independently of bundled-skill discovery: a package with a
+ * missing or trimmed `skills/` directory must still be able to uninstall
+ * cleanly, otherwise stale markers leak into later prompt-eligibility,
+ * retention, and prior-mode-detection logic. `rm ..., { force: true }`
+ * makes the operation idempotent — hosts that never wrote a marker (e.g.
+ * MCP-capable hosts installed only via `--mode mcp`) are silent no-ops.
+ *
+ * Hosts not registered with the Flywheel skill installer are skipped
+ * rather than throwing, so callers can pass the full uninstall host list
+ * without pre-filtering.
+ */
+export async function cleanupHostInstallMarkers({
+  cwd = process.cwd(),
+  scopes = ["project"],
+  hostNames = [],
+} = {}) {
+  for (const singleScope of scopes) {
+    for (const hostName of hostNames) {
+      let markerPath;
+      try {
+        markerPath = resolveFlywheelInstalledMarkerPath(
+          cwd,
+          hostName,
+          singleScope,
+        );
+      } catch {
+        continue;
+      }
+      // eslint-disable-next-line no-await-in-loop
+      await rm(markerPath, { force: true });
+    }
+  }
+}
+
 async function promptUninstallScope(defaultScope) {
   try {
     return await select({
@@ -674,6 +882,14 @@ async function resolveUninstallTargets(options, { explicitServerName }) {
 
 async function removeHostConfig(hostName, scope, serverName) {
   const host = getHost(hostName);
+  if (isSkillOnlyHost(host)) {
+    return {
+      host: host.displayName,
+      scope,
+      filePath: null,
+      status: "not present",
+    };
+  }
   const filePath = await resolveMcpPath(mcpCandidatesForScope(host, scope));
 
   if (host.mcp.configType === "toml") {
@@ -733,7 +949,8 @@ async function runUninstallCommand(options) {
       // 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.
+      // entries (non-default TOML section names under `[mcp_servers.*]`) are
+      // actually cleared.
       // eslint-disable-next-line no-await-in-loop
       const targetNames = await resolveUninstallServerNamesForHost(
         host,
@@ -743,10 +960,16 @@ async function runUninstallCommand(options) {
       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),
-        );
+        // Skill-only hosts (universal, antigravity) have no MCP surface
+        // at all — `host.mcp` is null, so dereferencing `projectPaths` via
+        // `mcpCandidatesForScope` throws. Report the absence without
+        // consulting a path that doesn't exist for them.
+        const filePath = isSkillOnlyHost(hostForDisplay)
+          ? null
+          : // eslint-disable-next-line no-await-in-loop
+            await resolveMcpPath(
+              mcpCandidatesForScope(hostForDisplay, singleScope),
+            );
         mcpResults.push({
           host: hostForDisplay.displayName,
           scope: singleScope,
@@ -774,12 +997,28 @@ async function runUninstallCommand(options) {
     if (bundledSkillNames.length > 0) {
       const skillSpinner = ora("Removing Flywheel bundled skills...").start();
       for (const singleScope of scopes) {
-        // Prevent deleting shared skill directories while non-selected hosts
-        // mapped to the same location still have Flywheel MCP entries.
+        // Retain any skill directory still claimed by a non-uninstalled host.
+        // Two signals combine: (a) MCP-backed hosts whose Flywheel entries
+        // survived the MCP-removal pass above, and (b) any host with bundled
+        // skill artifacts still on disk (including skill-only hosts like
+        // universal/antigravity, which never advertise themselves via MCP
+        // entries). Without (b), uninstalling one MCP host would silently
+        // wipe a shared `.agents/skills/<skill>/` that another host still
+        // relies on.
         // eslint-disable-next-line no-await-in-loop
-        const configuredRetainHostNames = await resolveHostsWithRemainingFlywheelMcpEntries({
+        const mcpRetained = await resolveHostsWithRemainingFlywheelMcpEntries({
           scope: singleScope,
         });
+        // eslint-disable-next-line no-await-in-loop
+        const skillOnlyRetained = await resolveSkillOnlyHostsRetainingArtifacts(
+          {
+            scope: singleScope,
+            excludedHostNames: supportedHosts,
+          },
+        );
+        const configuredRetainHostNames = [
+          ...new Set([...mcpRetained, ...skillOnlyRetained]),
+        ];
         skillSpinner.text = `Removing bundled skills from ${supportedHosts.length} host(s) (${singleScope})...`;
         // eslint-disable-next-line no-await-in-loop
         bundledSkillResults.push(
@@ -794,10 +1033,25 @@ async function runUninstallCommand(options) {
       }
       skillSpinner.succeed("Bundled skill uninstall complete");
     }
+
+    // Install-marker cleanup runs independently of bundled-skill discovery.
+    // A broken or trimmed package (missing `skills/`) can leave
+    // `bundledSkillNames` empty — the skill-removal pass above legitimately
+    // no-ops in that case, but the ownership markers must still be cleared,
+    // otherwise a later `uninstall`/`setup` would treat the uninstalled
+    // host as still owning shared skill dirs (wrong retention) or as a
+    // prior CLI install (false cross-mode conflict).
+    await cleanupHostInstallMarkers({
+      cwd: process.cwd(),
+      scopes,
+      hostNames: supportedHosts,
+    });
   }
 
   log.blank();
-  log.plain(pc.green("✔ Flywheel uninstall complete (MCP entries and bundled skills)"));
+  log.plain(
+    pc.green("✔ Flywheel uninstall complete (MCP entries and bundled skills)"),
+  );
   log.blank();
   for (const result of mcpResults) {
     const icon = result.status === "removed" ? pc.green("-") : pc.dim("~");
@@ -830,11 +1084,13 @@ async function runUninstallCommand(options) {
       }
     }
 
-    const sortedGroups = [...groupedSkillResults.values()].sort((left, right) => {
-      const leftKey = `${left.hostName}:${left.scope}`;
-      const rightKey = `${right.hostName}:${right.scope}`;
-      return leftKey.localeCompare(rightKey);
-    });
+    const sortedGroups = [...groupedSkillResults.values()].sort(
+      (left, right) => {
+        const leftKey = `${left.hostName}:${left.scope}`;
+        const rightKey = `${right.hostName}:${right.scope}`;
+        return leftKey.localeCompare(rightKey);
+      },
+    );
     for (const groupedResult of sortedGroups) {
       log.plain(
         `  ${pc.bold(getHost(groupedResult.hostName).displayName)} ${pc.dim(`(${groupedResult.scope})`)}`,
@@ -850,7 +1106,9 @@ async function runUninstallCommand(options) {
           entry.status === "retained" && Array.isArray(entry.retainedHostNames)
             ? ` (shared with configured host(s): ${entry.retainedHostNames.join(", ")})`
             : "";
-        log.plain(`    ${icon} ${entry.status}${retainedSuffix}: ${entry.skillNames.join(", ")}`);
+        log.plain(
+          `    ${icon} ${entry.status}${retainedSuffix}: ${entry.skillNames.join(", ")}`,
+        );
         log.plain(`      ${pc.dim(entry.installedSkillDir)}`);
       }
     }
@@ -861,7 +1119,9 @@ async function runUninstallCommand(options) {
       log.plain(
         `  ${pc.bold(getHost(unsupportedHostName).displayName)} ${pc.dim(`(${singleScope})`)}`,
       );
-      log.plain(`    ${pc.dim("~")} skill uninstall not supported (MCP-only host)`);
+      log.plain(
+        `    ${pc.dim("~")} skill uninstall not supported (MCP-only host)`,
+      );
     }
   }
   log.blank();
@@ -882,15 +1142,32 @@ Examples:
   ${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",
-  )}
+  ${pc.green("npx --yes @paradigma-inc/flywheel uninstall --yes --scope all")}
 `,
     );
 
   program
     .command("setup")
     .description("Set up Flywheel for your AI coding host")
+    .addHelpText(
+      "before",
+      `${pc.bold(pc.cyan("✻ Flywheel Setup"))}
+
+Configure the Flywheel CLI, MCP host entries, and bundled skills without changing command names or setup modes.
+`,
+    )
+    .optionsGroup("Hosts:")
+    .option("--claude", "Set up for Claude Code")
+    .option("--cursor", "Set up for Cursor")
+    .option("--universal", "Set up for Universal (.agents/skills)")
+    .option("--antigravity", "Set up for Antigravity (.agent/skills)")
+    .option("--opencode", "Set up for OpenCode")
+    .option("--codex", "Set up for Codex")
+    .option("--gemini", "Set up for Gemini CLI")
+    .option("--pi-mono", "Set up for Pi (pi-mono)")
+    .option("--hermes-agent", "Set up for Hermes Agent")
+    .option("--openclaw", "Set up for OpenClaw")
+    .optionsGroup("Mode:")
     .option(
       "--mode <mode>",
       "Install mode: mcp | cli (required in non-interactive; prompted in TTY, default: mcp)",
@@ -899,50 +1176,78 @@ Examples:
     )
     .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")
-    .option("--cursor", "Set up for Cursor")
-    .option("--pi-mono", "Set up for Pi (pi-mono)")
-    .option("--hermes-agent", "Set up for Hermes Agent")
-    .option("--openclaw", "Set up for OpenClaw")
+    .optionsGroup("Scope:")
     .option(
       "-p, --project",
       "Configure for current project instead of globally",
     )
-    .option("-y, --yes", "Skip host selection prompts")
-    .option("--force", "Reconcile prior install mode automatically via uninstall")
+    .option("-y, --yes", "Skip confirmation prompts")
+    .optionsGroup("Authentication:")
     .option("--api-key <key>", "Use API key authentication")
+    .option("--oauth", "Use OAuth endpoint (IDE handles auth flow)")
+    .optionsGroup("Skills:")
+    .option("--install-skill", "Install or refresh the bundled Flywheel skills")
+    .option("--skip-skill", "Skip bundled skill installation (MCP-only setup)")
+    .optionsGroup("Advanced:")
     .option(
       "--auth-mode <mode>",
-      "Authentication mode: auto | loopback | device (default: auto)",
+      "API-key mint flow: auto | loopback | device (default: auto)",
       normalizeAuthMode,
       "auto",
     )
-    .option("--install-skill", "Install or refresh the bundled Flywheel skills")
-    .option("--skip-skill", "Skip bundled skill installation (MCP-only setup)")
     .option(
       "--base-url <url>",
-      `Public Flywheel origin used for setup and MCP config (default: ${DEFAULT_BASE_URL})`,
+      `Public Flywheel origin used for setup and MCP config (default: ${resolveSetupBaseUrl()})`,
     )
     .option("--name <name>", `MCP server name (default: ${SERVER_NAME})`)
+    .option(
+      "--force",
+      "Reconcile prior install mode automatically via uninstall",
+    )
+    .addHelpText(
+      "after",
+      `
+Examples:
+  ${pc.green("npx --yes @paradigma-inc/flywheel setup --mode mcp --install-skill")}
+  ${pc.green("npx --yes @paradigma-inc/flywheel setup --mode mcp --skip-skill --codex --project")}
+  ${pc.green("npx --yes @paradigma-inc/flywheel setup --mode cli --codex --project")}
+
+Next steps:
+  ${pc.green("flywheel help")}
+  ${pc.green("flywheel auth:status")}
+`,
+    )
     .action(async (options) => {
       await runSetupCommandViaRouter(options);
     });
 
   program
     .command("uninstall")
-    .description("Remove Flywheel MCP entries and bundled skills from selected hosts")
+    .description(
+      "Remove Flywheel MCP entries and bundled skills from selected hosts",
+    )
+    .addHelpText(
+      "before",
+      `${pc.bold(pc.cyan("✻ Flywheel Uninstall"))}
+
+Remove Flywheel MCP entries and bundled skills from selected hosts without changing command names or uninstall scopes.
+`,
+    )
+    .optionsGroup("Hosts:")
     .option("--claude", "Uninstall for Claude Code")
+    .option("--cursor", "Uninstall for Cursor")
+    .option("--universal", "Uninstall bundled skills from .agents/skills")
+    .option("--antigravity", "Uninstall bundled skills from .agent/skills")
     .option("--opencode", "Uninstall for OpenCode")
     .option("--codex", "Uninstall for Codex")
-    .option("--cursor", "Uninstall for Cursor")
+    .option("--gemini", "Uninstall for Gemini CLI")
     .option("--pi-mono", "Uninstall for Pi (pi-mono)")
     .option("--hermes-agent", "Uninstall for Hermes Agent")
     .option("--openclaw", "Uninstall for OpenClaw")
+    .optionsGroup("Selection:")
     .option(
       "--hosts <list>",
-      "Comma-separated: codex,claude,opencode,cursor,pi-mono,hermes-agent,openclaw",
+      "Comma-separated: claude,cursor,universal,antigravity,opencode,codex,gemini,pi-mono,hermes-agent,openclaw",
     )
     .option("--scope <scope>", "all | global | project")
     .option(
@@ -950,6 +1255,18 @@ Examples:
       `MCP server name to remove (default: ${SERVER_NAME})`,
     )
     .option("-y, --yes", "Skip uninstall selection prompts")
+    .addHelpText(
+      "after",
+      `
+Examples:
+  ${pc.green("npx --yes @paradigma-inc/flywheel uninstall --codex --scope project")}
+  ${pc.green("npx --yes @paradigma-inc/flywheel uninstall --hosts claude,codex --scope all --yes")}
+
+Next steps:
+  ${pc.green("flywheel help setup")}
+  ${pc.green("npx --yes @paradigma-inc/flywheel setup --mode mcp")}
+`,
+    )
     .action(async (options) => {
       await runUninstallCommand(options);
     });