@mushi-mushi/cli 0.20.0 → 0.22.0

package/dist/index.js

@@ -18,7 +18,7 @@ import {
   sanitizeProjectId,
   saveConfig,
   writeMcpServerEntry
-} from "./chunk-D5IDNBJO.js";
+} from "./chunk-R2HPR2FV.js";
 import {
   CLOUD_API_ENDPOINT,
   TEST_REPORT_FETCH_TIMEOUT_MS,
@@ -78,6 +78,23 @@ var MushiCliError = class extends Error {
     };
   }
 };
+function printAndExit(err, asJson = false) {
+  const cliErr = err instanceof MushiCliError ? err : new MushiCliError(
+    "E_INTERNAL",
+    err instanceof Error ? err.message : String(err),
+    "this is unexpected \u2014 re-run with MUSHI_DEBUG=1 and report at https://github.com/kensaurus/mushi-mushi/issues",
+    err
+  );
+  if (asJson) {
+    process.stderr.write(JSON.stringify(cliErr.toJSON()) + "\n");
+  } else {
+    process.stderr.write(`error [${cliErr.code}]: ${cliErr.message}
+`);
+    if (cliErr.hint) process.stderr.write(`  \u2192 fix: ${cliErr.hint}
+`);
+  }
+  process.exit(cliErr.exitCode);
+}
 
 // src/signals.ts
 var installed = false;
@@ -110,13 +127,13 @@ function getAbortSignal(external) {
 }
 
 // src/version.ts
-var MUSHI_CLI_VERSION = true ? "0.20.0" : "0.0.0-dev";
+var MUSHI_CLI_VERSION = true ? "0.22.0" : "0.0.0-dev";
 
 // src/init.ts
 import * as p from "@clack/prompts";
 import { spawn } from "child_process";
 import { randomUUID } from "crypto";
-import { appendFileSync, existsSync as existsSync3, readFileSync as readFileSync3 } from "fs";
+import { appendFileSync, existsSync as existsSync3, readFileSync as readFileSync3, writeFileSync } from "fs";
 import { join as join3 } from "path";
 
 // src/console-url.ts
@@ -237,6 +254,20 @@ async function openInBrowser(url) {
 
 // src/cli-shared.ts
 var API_TIMEOUT_MS = 15e3;
+async function probeEndpointHealth(endpoint) {
+  const t0 = Date.now();
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), API_TIMEOUT_MS);
+  try {
+    const res = await fetch(`${endpoint}/health`, { signal: controller.signal });
+    clearTimeout(timer);
+    const body = res.headers.get("content-type")?.includes("json") ? await res.json().catch(() => ({})) : {};
+    return { ok: res.ok, status: res.status, latencyMs: Date.now() - t0, body };
+  } catch (err) {
+    clearTimeout(timer);
+    throw err;
+  }
+}
 async function apiCall(path, config, options = {}) {
   const endpoint = config.endpoint;
   if (!endpoint) {
@@ -292,13 +323,13 @@ async function apiCall(path, config, options = {}) {
     }
     if (!res.ok && typeof body === "object" && body !== null && !("ok" in body)) {
       const b = body;
+      const nested = b["error"];
+      const errCode = nested?.["code"] ?? b["code"] ?? `HTTP_${res.status}`;
+      const errMsg = nested?.["message"] ?? b["message"] ?? `Request failed (${res.status})`;
       return {
         ok: false,
         httpStatus: res.status,
-        error: {
-          code: b["code"] ?? `HTTP_${res.status}`,
-          message: b["message"] ?? `Request failed (${res.status})`
-        }
+        error: { code: errCode, message: errMsg }
       };
     }
     return body;
@@ -327,24 +358,31 @@ function die(result, exitCode = 1) {
   const status = result.httpStatus ? ` [${result.httpStatus}]` : "";
   process.stderr.write(`error${status}: ${code} \u2014 ${message}
 `);
+  if (code === "INSUFFICIENT_SCOPE") {
+    process.stderr.write(
+      "\n  Your current API key does not have the required scope for this command.\n  New keys minted by the wizard already include both scopes. Existing keys\n  can be upgraded with:\n\n    mushi login --upgrade-scope\n\n  Or visit your console \u2192 Projects \u2192 API Keys to mint a new key.\n"
+    );
+  }
   process.exit(exitCode);
 }
 function requireConfig(opts = {}) {
   const config = loadConfig();
   if (!config.apiKey) {
-    process.stderr.write(
-      "error: API key not configured.\n  Run:  mushi login --api-key <key>\n  Or:   export MUSHI_API_KEY=<key>\n"
-    );
-    process.exit(2);
+    printAndExit(new MushiCliError(
+      "E_AUTH_MISSING",
+      "API key not configured.",
+      "Run: mushi login --api-key <key>  Or: export MUSHI_API_KEY=<key>"
+    ));
   }
   if (!config.endpoint) {
     config.endpoint = process.env.MUSHI_API_ENDPOINT?.trim() || CLOUD_API_ENDPOINT;
   }
   if (opts.needsProject && !config.projectId) {
-    process.stderr.write(
-      "error: Project ID not configured.\n  Run:  mushi login --project-id <uuid>\n  Or:   export MUSHI_PROJECT_ID=<uuid>\n  Find your project ID: " + consoleUrl(resolveConsoleUrlSync(), "/projects") + "\n"
-    );
-    process.exit(2);
+    printAndExit(new MushiCliError(
+      "E_PROJECT_MISSING",
+      "Project ID not configured.",
+      `Run: mushi login --project-id <uuid>  Or find your project ID at ${consoleUrl(resolveConsoleUrlSync(), "/projects")}`
+    ));
   }
   return config;
 }
@@ -424,8 +462,12 @@ async function waitForCliToken(endpoint, session, opts = {}) {
   const deadline = now() + (session.expires_in || 600) * 1e3;
   const maxConsecutiveErrors = opts.maxConsecutiveErrors ?? 5;
   let consecutiveErrors = 0;
+  let firstPoll = true;
   while (now() < deadline) {
-    await sleep(intervalMs);
+    if (!firstPoll) {
+      await sleep(intervalMs);
+    }
+    firstPoll = false;
     const outcome = await pollDeviceToken(endpoint, session.device_code);
     switch (outcome.status) {
       case "approved":
@@ -653,6 +695,53 @@ function getFrameworkFromPkg(pkg) {
   return void 0;
 }
 
+// src/auth-ui.ts
+var LINE = "\u2500".repeat(58);
+function printAuthBanner(userCode, verificationUri) {
+  console.log("");
+  console.log(`  \u250C${LINE}\u2510`);
+  console.log(`  \u2502  Browser sign-in \u2014 follow these 3 steps              \u2502`);
+  console.log(`  \u251C${LINE}\u2524`);
+  console.log(`  \u2502                                                        \u2502`);
+  console.log(`  \u2502  1. A browser tab will open (or visit the URL below)  \u2502`);
+  console.log(`  \u2502  2. Sign in if prompted, then click "Approve"         \u2502`);
+  console.log(`  \u2502  3. Come back here \u2014 setup continues automatically    \u2502`);
+  console.log(`  \u2502                                                        \u2502`);
+  console.log(`  \u251C${LINE}\u2524`);
+  console.log(`  \u2502  Verification code (show in browser \u2014 NOT terminal):  \u2502`);
+  console.log(`  \u2502                                                        \u2502`);
+  console.log(`  \u2502    ${userCode.padEnd(52)}\u2502`);
+  console.log(`  \u2502                                                        \u2502`);
+  console.log(`  \u2502  \u26A0  Do NOT paste or type this code in your terminal   \u2502`);
+  console.log(`  \u2514${LINE}\u2518`);
+  console.log("");
+  console.log(`  If the browser didn't open, visit this URL and approve:`);
+  console.log(`    ${verificationUri}`);
+  console.log("");
+  console.log("  \u23F3 Waiting for browser approval\u2026 (Ctrl+C to cancel)");
+  console.log("");
+}
+function printAuthApproved() {
+  console.log("");
+  console.log("  \u2713 Approved! Continuing setup in this terminal\u2026");
+  console.log("");
+}
+function printAuthFailed(reason, detail) {
+  console.log("");
+  if (reason === "denied") {
+    console.error("  \u2717 Browser sign-in was denied.");
+    console.error("    If that was a mistake, run mushi login again.");
+  } else if (reason === "timeout") {
+    console.error("  \u2717 Browser sign-in timed out (10 minutes elapsed).");
+    console.error("    Run mushi login again \u2014 a new code will be generated.");
+  } else {
+    console.error(`  \u2717 Browser sign-in failed: ${detail ?? "unknown error"}`);
+    console.error("    Run mushi login again, or use:");
+    console.error("      mushi login --api-key <key> --project-id <uuid>");
+  }
+  console.log("");
+}
+
 // src/init.ts
 var ENV_FILES = [".env.local", ".env"];
 var PROJECT_ID_PATTERN = /^(?:proj_[A-Za-z0-9_-]{10,}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$/i;
@@ -660,7 +749,7 @@ var API_KEY_PATTERN = /^(mushi_|mush_pk_)[A-Za-z0-9_-]{10,}$/;
 async function runInit(options = {}) {
   const cwd = options.cwd ?? process.cwd();
   ensureInteractiveOrBailOut(options);
-  p.intro("\u{1F41B} Mushi Mushi setup wizard");
+  p.intro("Mushi setup");
   await printFreshnessHint();
   warnIfWorkspaceRoot(cwd);
   const pkg = readPackageJson(cwd);
@@ -688,13 +777,13 @@ async function runInit(options = {}) {
   } else {
     p.log.info(`Skipped install. Run \`${installCommand(pm, packagesToInstall)}\` yourself.`);
   }
-  writeEnvFile(cwd, credentials.apiKey, credentials.projectId, framework);
+  await writeEnvFile(cwd, credentials.apiKey, credentials.projectId, framework, endpoint, Boolean(options.yes));
   persistCliConfig(credentials.apiKey, credentials.projectId, endpoint);
   const enableRewards = await maybeEnableRewards(options);
   printNextSteps(framework, consoleBase, enableRewards);
   await maybeSendTestReport(credentials, { ...options, endpoint, consoleBase });
   await maybeOfferConnect(credentials, options, consoleBase);
-  p.outro("Setup complete. Happy bug squashing \u{1F41B}");
+  p.outro("Setup complete.");
 }
 function ensureInteractiveOrBailOut(options) {
   const isTTY = Boolean(process.stdin.isTTY && process.stdout.isTTY);
@@ -759,7 +848,7 @@ async function acquireCredentials(options, consoleBase, endpoint) {
     }
   }
   if (options.yes) {
-    const creds = await runBrowserSignIn(options, endpoint);
+    const creds = await runBrowserSignIn(options, endpoint, consoleBase);
     if (creds) return creds;
     p.log.warn("Browser sign-in didn't complete \u2014 switching to manual entry.");
   } else {
@@ -775,7 +864,7 @@ async function acquireCredentials(options, consoleBase, endpoint) {
         {
           value: "manual",
           label: "Paste a Project ID + API key",
-          hint: "Self-hosted or expert setup"
+          hint: "Self-hosted or expert setup \u2014 run npx mushi-mushi (not mushi setup)"
         }
       ]
     });
@@ -784,14 +873,14 @@ async function acquireCredentials(options, consoleBase, endpoint) {
       process.exit(0);
     }
     if (method === "browser") {
-      const creds = await runBrowserSignIn(options, endpoint);
+      const creds = await runBrowserSignIn(options, endpoint, consoleBase);
       if (creds) return creds;
       p.log.warn("Browser sign-in didn't complete \u2014 switching to manual entry.");
     }
   }
   return collectCredentialsManually(options, consoleBase);
 }
-async function runBrowserSignIn(options, endpoint) {
+async function runBrowserSignIn(options, endpoint, consoleBase) {
   const startSpin = p.spinner();
   startSpin.start("Starting secure browser sign-in\u2026");
   let session;
@@ -803,13 +892,11 @@ async function runBrowserSignIn(options, endpoint) {
     return null;
   }
   startSpin.stop("Browser sign-in ready.");
-  p.log.step(`Confirmation code: ${session.user_code}`);
-  p.log.info(`Opening ${session.verification_uri}`);
   try {
     await openInBrowser(session.verification_uri);
   } catch {
   }
-  p.log.message("Approve the request in your browser to continue. (Ctrl+C to cancel)");
+  printAuthBanner(session.user_code, session.verification_uri);
   const waitSpin = p.spinner();
   waitSpin.start("Waiting for you to approve in the browser\u2026");
   let cliToken;
@@ -825,9 +912,14 @@ async function runBrowserSignIn(options, endpoint) {
   let apiKey;
   if (!projectId) {
     let projects = [];
+    const fetchSpin = p.spinner();
+    fetchSpin.start("Loading your projects\u2026");
     try {
       projects = await listProjects(endpoint, cliToken);
-    } catch {
+      fetchSpin.stop(projects.length > 0 ? `Found ${projects.length} project(s).` : "No projects yet.");
+    } catch (err) {
+      fetchSpin.stop("Could not load projects \u2014 you can still create a new one.");
+      p.log.warn(err instanceof Error ? err.message : String(err));
     }
     const NEW = "__new__";
     const choice = await p.select({
@@ -869,7 +961,24 @@ async function runBrowserSignIn(options, endpoint) {
     }
   }
   if (projectId && !apiKey) {
-    apiKey = await mintProjectKey(endpoint, cliToken, projectId) ?? void 0;
+    const keySpin = p.spinner();
+    keySpin.start("Minting SDK key\u2026");
+    try {
+      const minted = await mintProjectKey(endpoint, cliToken, projectId);
+      apiKey = minted ?? void 0;
+      if (!apiKey) {
+        keySpin.stop("Could not mint an API key.");
+        p.log.warn(
+          `Open the console Verify tab to generate a key manually: ${consoleUrl(consoleBase, "/onboarding?tab=verify")}`
+        );
+        return null;
+      }
+      keySpin.stop("SDK key ready.");
+    } catch (err) {
+      keySpin.stop("Could not mint an API key.");
+      p.log.warn(err instanceof Error ? err.message : String(err));
+      return null;
+    }
   }
   if (!projectId || !apiKey) return null;
   return { apiKey, projectId };
@@ -975,13 +1084,37 @@ function runCommand(pm, packages, cwd) {
     });
   });
 }
-function writeEnvFile(cwd, apiKey, projectId, framework) {
+async function writeEnvFile(cwd, apiKey, projectId, framework, endpoint, overwrite) {
   const target = ENV_FILES.find((f) => existsSync3(join3(cwd, f))) ?? ENV_FILES[0];
   const targetPath = join3(cwd, target);
-  const newVars = envVarsToWrite(apiKey, projectId, framework);
+  const newVars = envVarsToWrite(apiKey, projectId, framework, endpoint);
   const existing = existsSync3(targetPath) ? readFileSync3(targetPath, "utf-8") : "";
   if (existing.includes("MUSHI_PROJECT_ID")) {
-    p.log.warn(`Existing MUSHI_* vars found in ${target} \u2014 leaving them untouched.`);
+    let shouldOverwrite = overwrite;
+    if (!shouldOverwrite) {
+      const answer = await p.confirm({
+        message: `Existing MUSHI_* vars found in ${target}. Update with new credentials?`,
+        initialValue: true
+      });
+      if (p.isCancel(answer)) {
+        p.log.info(`Kept existing env vars in ${target}.`);
+        return;
+      }
+      shouldOverwrite = Boolean(answer);
+    }
+    if (!shouldOverwrite) {
+      p.log.info(`Kept existing env vars in ${target}. Re-run and confirm to overwrite.`);
+      return;
+    }
+    const MUSHI_LINE_RE = /^(NEXT_PUBLIC_|NUXT_PUBLIC_|VITE_|EXPO_PUBLIC_)?MUSHI_[A-Z_]+=.*/gm;
+    const stripped = existing.replace(MUSHI_LINE_RE, "").replace(/\n{3,}/g, "\n\n").trimEnd();
+    const prefix2 = stripped.length > 0 ? "\n" : "";
+    writeFileSync(targetPath, `${stripped}${prefix2}
+# Mushi Mushi
+${newVars}
+`);
+    p.log.success(`Updated MUSHI_* env vars in ${target}`);
+    warnIfMissingFromGitignore(cwd, target);
     return;
   }
   const prefix = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
@@ -1042,12 +1175,14 @@ import { MushiRewardsBadge } from '@mushi-mushi/react';
     p.log.info(`Enable rewards in your project settings at ${consoleUrl(consoleBase, "/rewards")}`);
     p.log.info("Users will earn points for bug reports, screen navigation, and app activity.");
   }
-  p.log.message("Verify the install:");
-  p.log.message("  \u2022 Start your dev server");
-  p.log.message("  \u2022 Look for the \u{1F41B} button in the bottom-right corner (or shake on mobile)");
-  p.log.message(`  \u2022 Submit a test report \u2014 it should appear at ${reportsUrl(consoleBase)}`);
-  p.log.info(
-    "Tip: `mushi connect --write-env --wire-ide --wait` also wires Cursor MCP and waits for SDK heartbeat."
+  p.note(
+    [
+      "  [ ] 1. Paste the init snippet above into your app entry file",
+      "  [ ] 2. Start your dev server",
+      "  [ ] 3. Run: mushi connect --write-env --wire-ide --wait",
+      `  [ ] 4. Open the Verify tab to send a test report: ${consoleUrl(consoleBase, "/onboarding?tab=verify")}`
+    ].join("\n"),
+    "Next steps:"
   );
 }
 async function maybeOfferConnect(credentials, options, _consoleBase) {
@@ -1059,7 +1194,7 @@ async function maybeOfferConnect(credentials, options, _consoleBase) {
   if (p.isCancel(answer) || !answer) return;
   const endpoint = resolveCloudEndpoint(options.endpoint);
   try {
-    const { runConnect: runConnect2 } = await import("./connect-W2Q6N7K3.js");
+    const { runConnect: runConnect2 } = await import("./connect-JIEIWTF3.js");
     await runConnect2({
       apiKey: credentials.apiKey,
       projectId: credentials.projectId,
@@ -1344,11 +1479,15 @@ function registerAccountCommands(program2) {
     const { matches } = runMigrate({ cwd: opts.cwd, json: opts.json });
     if (matches.length === 0) process.exit(1);
   });
-  program2.command("login").description("Authenticate the CLI via browser (zero copy-paste), or pass --api-key to skip").option("--api-key <key>", "API key (mushi_...) \u2014 non-interactive / CI path").option("--endpoint <url>", "Override the Mushi API endpoint (self-hosted)").option("--project-id <id>", "Project UUID \u2014 skip the project picker").option("--no-browser", "Print the verification URL instead of opening the browser").addHelpText("after", `
+  program2.command("login").description("Authenticate the CLI via browser (zero copy-paste), or pass --api-key to skip").option("--api-key <key>", "API key (mushi_...) \u2014 non-interactive / CI path").option("--endpoint <url>", "Override the Mushi API endpoint (self-hosted)").option("--project-id <id>", "Project UUID \u2014 skip the project picker").option("--no-browser", "Print the verification URL instead of opening the browser").option(
+    "--upgrade-scope",
+    "Re-authenticate and mint a new key with report:write + mcp:read + mcp:write scopes. Use this to upgrade an existing ingest-only key so MCP and admin commands (including writes like `mushi billing cap`) work."
+  ).addHelpText("after", `
 Examples:
   mushi login                              # browser-guided (recommended)
   mushi login --api-key mushi_xxx         # non-interactive / CI
-  mushi login --api-key mushi_xxx --project-id <uuid>`).action(async (opts) => {
+  mushi login --api-key mushi_xxx --project-id <uuid>
+  mushi login --upgrade-scope             # re-auth to add mcp:read + mcp:write to your key`).action(async (opts) => {
     const { CLOUD_API_ENDPOINT: CLOUD_API_ENDPOINT2, resolveCloudEndpoint: resolveCloudEndpoint2 } = await import("./endpoint-DGS73AVM.js");
     const endpoint = opts.endpoint ? resolveCloudEndpoint2(opts.endpoint) : CLOUD_API_ENDPOINT2;
     const consoleBase = await resolveConsoleUrl();
@@ -1386,8 +1525,16 @@ Examples:
       return;
     }
     console.log("");
-    console.log("  Mushi login");
-    console.log("  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
+    if (opts.upgradeScope) {
+      console.log("  Mushi login \u2014 scope upgrade");
+      console.log("  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
+      console.log("  Re-authenticating to mint a new key with report:write + mcp:read + mcp:write scopes.");
+      console.log("  This lets the CLI admin commands (including writes) and MCP server both work with a single key.");
+      console.log("");
+    } else {
+      console.log("  Mushi login");
+      console.log("  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
+    }
     let deviceData;
     try {
       deviceData = await startDeviceAuth(endpoint);
@@ -1400,26 +1547,24 @@ error: Could not start login session: ${err instanceof Error ? err.message : Str
       process.exit(1);
     }
     const verifyUrl = deviceData.verification_uri;
-    console.log("");
-    console.log(`  Your confirmation code: ${deviceData.user_code}`);
-    console.log("");
     if (opts.browser !== false) {
-      console.log("  Opening the Mushi console in your browser\u2026");
       try {
         await openInBrowser(verifyUrl);
       } catch {
       }
     }
-    console.log(`  If the browser didn't open: ${verifyUrl}`);
-    console.log("");
-    console.log("  Waiting for you to approve in the browser\u2026  (Ctrl+C to cancel)");
+    printAuthBanner(deviceData.user_code, verifyUrl);
     let cliToken = null;
     const pollIntervalMs = (deviceData.interval ?? 5) * 1e3;
     const deadline = Date.now() + (deviceData.expires_in ?? 600) * 1e3;
     const MAX_CONSECUTIVE_ERRORS = 5;
     let consecutiveErrors = 0;
+    let firstPoll = true;
     while (Date.now() < deadline) {
-      await new Promise((r) => setTimeout(r, pollIntervalMs));
+      if (!firstPoll) {
+        await new Promise((r) => setTimeout(r, pollIntervalMs));
+      }
+      firstPoll = false;
       const outcome = await pollDeviceToken(endpoint, deviceData.device_code);
       if (outcome.status === "approved") {
         cliToken = outcome.cliToken;
@@ -1427,38 +1572,30 @@ error: Could not start login session: ${err instanceof Error ? err.message : Str
       }
       if (outcome.status === "pending") {
         consecutiveErrors = 0;
-        process.stdout.write(".");
         continue;
       }
       if (outcome.status === "error") {
         if (outcome.retryable) {
           consecutiveErrors += 1;
-          if (consecutiveErrors < MAX_CONSECUTIVE_ERRORS) {
-            process.stdout.write("\xB7");
-            continue;
-          }
+          if (consecutiveErrors < MAX_CONSECUTIVE_ERRORS) continue;
         }
-        console.log("");
-        process.stderr.write(`
-error: ${outcome.message}
-`);
+        printAuthFailed("error", outcome.message);
         process.exit(1);
       }
-      console.log("");
       if (outcome.status === "denied") {
-        process.stderr.write("\nerror: Login denied in the browser.\n");
-      } else if (outcome.status === "expired") {
-        process.stderr.write("\nerror: Login code expired. Run mushi login again.\n");
+        printAuthFailed("denied");
+        process.exit(1);
+      }
+      if (outcome.status === "expired") {
+        printAuthFailed("timeout");
+        process.exit(1);
       }
-      process.exit(1);
     }
     if (!cliToken) {
-      console.log("");
-      process.stderr.write("\nerror: Login timed out. Run mushi login again.\n");
+      printAuthFailed("timeout");
       process.exit(1);
     }
-    console.log("");
-    console.log("  \u2713 Approved!");
+    printAuthApproved();
     const projectsList = await listProjects(endpoint, cliToken);
     let chosenProjectId = projectId;
     let chosenProjectName;
@@ -1521,12 +1658,17 @@ error: Could not create project: ${err instanceof Error ? err.message : String(e
     console.log("");
     if (chosenProjectName) console.log(`  \u2713 Project: ${chosenProjectName}`);
     if (apiKey) {
-      console.log(`  \u2713 SDK key saved (${apiKey.slice(0, 12)}\u2026)`);
+      console.log(`  \u2713 Full-scope CLI key saved (${apiKey.slice(0, 12)}\u2026)`);
+      console.log(`    Scopes: report:write \xB7 mcp:read \xB7 mcp:write \u2014 SDK + MCP + admin CLI (incl. writes) all work with this key`);
     } else {
       console.log(`  \u2139  Get an SDK key at: ${apiKeyHint(consoleBase)}`);
     }
     console.log("");
-    console.log("  Run 'mushi init' to set up the SDK in this project.");
+    if (opts.upgradeScope) {
+      console.log("  Key upgraded! Re-run 'mushi setup' to update your .cursor/mcp.json, then restart Cursor.");
+    } else {
+      console.log("  Run 'mushi init' to set up the SDK in this project.");
+    }
   });
   program2.command("whoami").description("Verify API key and display project info").option("--json", "Machine-readable JSON output").addHelpText("after", `
 Verifies that MUSHI_API_KEY is valid and shows which project it belongs to.
@@ -1548,24 +1690,19 @@ Useful after 'mushi login' to confirm credentials are correct.`).action(async (o
     const config = requireConfig();
     const t0 = Date.now();
     try {
-      const controller = new AbortController();
-      const timer = setTimeout(() => controller.abort(), API_TIMEOUT_MS);
-      const res = await fetch(`${config.endpoint}/health`, { signal: controller.signal });
-      clearTimeout(timer);
-      const latency = Date.now() - t0;
+      const probe = await probeEndpointHealth(config.endpoint);
       if (opts.json) {
-        console.log(JSON.stringify({ ok: res.ok, status: res.status, latency_ms: latency }));
+        console.log(JSON.stringify({ ok: probe.ok, status: probe.status, latency_ms: probe.latencyMs }));
       } else {
-        const symbol = res.ok ? "\u2713" : "\u2717";
-        console.log(`${symbol} ${res.ok ? "OK" : "FAIL"} \u2014 ${res.status} (${latency}ms)`);
-        if (!res.ok) process.exit(1);
+        console.log(`${probe.ok ? "OK" : "FAIL"} \u2014 ${probe.status} (${probe.latencyMs}ms)`);
+        if (!probe.ok) process.exit(1);
       }
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       if (opts.json) {
         console.log(JSON.stringify({ ok: false, error: msg, latency_ms: Date.now() - t0 }));
       } else {
-        process.stderr.write(`\u2717 Unreachable: ${msg}
+        process.stderr.write(`FAIL Unreachable: ${msg}
 `);
       }
       process.exit(1);
@@ -1630,22 +1767,16 @@ function registerDeployCommands(program2) {
   const deploy = program2.command("deploy").description("Deployment management");
   deploy.command("check").description("Check edge function health and measure latency").option("--json", "Machine-readable JSON output").action(async (opts) => {
     const config = requireConfig();
-    const t0 = Date.now();
     try {
-      const controller = new AbortController();
-      const timer = setTimeout(() => controller.abort(), API_TIMEOUT_MS);
-      const res = await fetch(`${config.endpoint}/health`, { signal: controller.signal });
-      clearTimeout(timer);
-      const latency = Date.now() - t0;
-      const body = res.headers.get("content-type")?.includes("json") ? await res.json().catch(() => ({})) : {};
+      const probe = await probeEndpointHealth(config.endpoint);
       if (opts.json) {
-        console.log(JSON.stringify({ ok: res.ok, status: res.status, latency_ms: latency, ...body }));
+        console.log(JSON.stringify({ ok: probe.ok, status: probe.status, latency_ms: probe.latencyMs, ...probe.body }));
       } else {
-        console.log(`Health: ${res.status === 200 ? "OK" : "FAIL"} (${res.status}) \u2014 ${latency}ms`);
-        if (body["version"]) console.log(`  Version: ${body["version"]}`);
-        if (body["region"]) console.log(`  Region:  ${body["region"]}`);
+        console.log(`Health: ${probe.status === 200 ? "OK" : "FAIL"} (${probe.status}) \u2014 ${probe.latencyMs}ms`);
+        if (probe.body["version"]) console.log(`  Version: ${probe.body["version"]}`);
+        if (probe.body["region"]) console.log(`  Region:  ${probe.body["region"]}`);
       }
-      if (!res.ok) process.exit(1);
+      if (!probe.ok) process.exit(1);
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       if (opts.json) {
@@ -2049,11 +2180,11 @@ AI code review context.
 Typical CI usage:
   MUSHI_API_KEY=$KEY MUSHI_PROJECT_ID=$PID MUSHI_API_ENDPOINT=$URL \\
     npx @mushi-mushi/cli sync-lessons --cwd .`).action(async (opts) => {
-    const { writeFile, mkdir } = await import("fs/promises");
-    const nodePath = await import("path");
+    const { writeFile: writeFile2, mkdir } = await import("fs/promises");
+    const nodePath2 = await import("path");
     const config = requireConfig();
     const cwd = opts.cwd ?? process.cwd();
-    const target = nodePath.join(cwd, ".mushi", "lessons.json");
+    const target = nodePath2.join(cwd, ".mushi", "lessons.json");
     const result = await apiCall("/v1/sync/lessons?limit=500", config);
     if (!result.ok) die(result);
     const rows = Array.isArray(result.data) ? result.data : [];
@@ -2076,8 +2207,8 @@ Typical CI usage:
       console.log(JSON.stringify(output, null, 2));
       return;
     }
-    await mkdir(nodePath.dirname(target), { recursive: true });
-    await writeFile(target, JSON.stringify(output, null, 2) + "\n", "utf8");
+    await mkdir(nodePath2.dirname(target), { recursive: true });
+    await writeFile2(target, JSON.stringify(output, null, 2) + "\n", "utf8");
     if (opts.json) {
       console.log(JSON.stringify({ ok: true, path: target, count: lessons2.length }));
     } else {
@@ -2273,34 +2404,34 @@ Examples:
   mushi index ./src --language ts --dry-run`).action(async (path, opts) => {
     const config = requireConfig({ needsProject: true });
     const { readdir: readdir2, readFile: readFile2, stat } = await import("fs/promises");
-    const nodePath = await import("path");
+    const nodePath2 = await import("path");
     const SKIP = /node_modules|\.git|dist|build|\.next|\.turbo|coverage/;
     const EXTS = /* @__PURE__ */ new Set([".ts", ".tsx", ".js", ".jsx", ".py", ".go", ".rs"]);
     const MAX_FILE_BYTES = 5e5;
     async function* walk(dir) {
       const entries = await readdir2(dir, { withFileTypes: true });
       for (const e of entries) {
-        const full = nodePath.join(dir, e.name);
+        const full = nodePath2.join(dir, e.name);
         if (SKIP.test(full)) continue;
         if (e.isDirectory()) yield* walk(full);
-        else if (EXTS.has(nodePath.extname(e.name))) yield full;
+        else if (EXTS.has(nodePath2.extname(e.name))) yield full;
       }
     }
     let count = 0;
     let bytes = 0;
     let errors = 0;
-    const root = nodePath.resolve(path);
+    const root = nodePath2.resolve(path);
     for await (const file of walk(root)) {
-      const lang = nodePath.extname(file).slice(1);
+      const lang = nodePath2.extname(file).slice(1);
       if (opts.language && opts.language !== lang) continue;
       const stats = await stat(file);
       if (stats.size > MAX_FILE_BYTES) {
-        if (!opts.json) process.stdout.write(`  skip  ${nodePath.relative(root, file)} (>${MAX_FILE_BYTES / 1e3}KB)
+        if (!opts.json) process.stdout.write(`  skip  ${nodePath2.relative(root, file)} (>${MAX_FILE_BYTES / 1e3}KB)
 `);
         continue;
       }
       const source = await readFile2(file, "utf8");
-      const relative2 = nodePath.relative(root, file).replaceAll("\\", "/");
+      const relative2 = nodePath2.relative(root, file).replaceAll("\\", "/");
       count++;
       bytes += source.length;
       if (opts.dryRun) {
@@ -2346,6 +2477,37 @@ Examples:
   });
 }
 
+// src/project-bootstrap.ts
+import { writeFile } from "fs/promises";
+import { existsSync as existsSync4 } from "fs";
+import nodePath from "path";
+async function writeProjectBootstrapFiles(opts) {
+  const cwd = opts.cwd ?? process.cwd();
+  const envPath = nodePath.join(cwd, ".env.local");
+  const envLines = [
+    "# Mushi MCP \u2014 drop into .env.local (gitignored). The MCP binary picks these up on spawn.",
+    `MUSHI_API_ENDPOINT=${opts.endpoint}`,
+    `MUSHI_PROJECT_ID=${opts.projectId}`,
+    `MUSHI_API_KEY=${opts.apiKey}`,
+    ""
+  ];
+  const envUpdated = existsSync4(envPath);
+  await writeFile(envPath, envLines.join("\n"), "utf8");
+  const mcpPath = nodePath.join(cwd, ".cursor", "mcp.json");
+  const serverName = buildMcpServerName({ legacy: true });
+  const serverBlock = buildMcpServerBlock({
+    endpoint: opts.endpoint,
+    projectId: opts.projectId,
+    apiKey: opts.apiKey
+  });
+  const { created: mcpCreated } = await writeMcpServerEntry({
+    configPath: mcpPath,
+    serverName,
+    serverBlock
+  });
+  return { envUpdated, mcpUpdated: !mcpCreated };
+}
+
 // src/commands/project.ts
 function registerProjectCommands(program2) {
   const project = program2.command("project").description("Project management");
@@ -2360,9 +2522,6 @@ Typical first-time flow:
   # Browser opens \u2192 click Approve \u2192 pick or create a project
   # CLI writes .env.local and .cursor/mcp.json
   # mushi whoami to confirm`).action(async (opts) => {
-    const { writeFile } = await import("fs/promises");
-    const { existsSync: existsSync4 } = await import("fs");
-    const nodePath = await import("path");
     const savedConfig = loadConfig();
     const endpoint = resolveCloudEndpoint(
       opts.endpoint ?? process.env.MUSHI_API_ENDPOINT?.trim() ?? savedConfig.endpoint
@@ -2382,33 +2541,24 @@ error: Could not start browser sign-in: ${err instanceof Error ? err.message : S
       process.stderr.write("  Fallback: mushi login --api-key <key> --project-id <uuid>\n");
       process.exit(1);
     }
-    console.log(`  Confirmation code: ${session.user_code}`);
-    console.log("");
     if (opts.browser !== false) {
-      console.log("  Opening the Mushi console in your browser\u2026");
       try {
         await openInBrowser(session.verification_uri);
       } catch {
       }
     }
-    console.log(`  If the browser didn't open: ${session.verification_uri}`);
-    console.log("");
-    console.log("  Waiting for you to approve in the browser\u2026  (Ctrl+C to cancel)");
+    printAuthBanner(session.user_code, session.verification_uri);
     let cliToken;
     try {
-      cliToken = await waitForCliToken(endpoint, session, {
-        onPending: () => process.stdout.write("."),
-        onTransientError: () => process.stdout.write("\xB7")
-      });
+      cliToken = await waitForCliToken(endpoint, session);
     } catch (err) {
-      console.log("");
-      process.stderr.write(`
-error: ${err instanceof Error ? err.message : String(err)}
-`);
+      const msg = err instanceof Error ? err.message : String(err);
+      if (msg.includes("denied")) printAuthFailed("denied");
+      else if (msg.includes("timed out") || msg.includes("expired")) printAuthFailed("timeout");
+      else printAuthFailed("error", msg);
       process.exit(1);
     }
-    console.log("");
-    console.log("  \u2713 Approved!");
+    printAuthApproved();
     const projectsList = await listProjects(endpoint, cliToken);
     const { createInterface } = await import("readline");
     const rl = createInterface({ input: process.stdin, output: process.stdout });
@@ -2468,24 +2618,14 @@ error: Could not create project: ${err instanceof Error ? err.message : String(e
     config.projectId = projectId;
     config.consoleUrl = consoleBase;
     saveConfig(config);
-    const cwd = process.cwd();
-    const envPath = nodePath.join(cwd, ".env.local");
-    const envLines = [
-      "# Mushi MCP \u2014 drop into .env.local (gitignored). The MCP binary picks these up on spawn.",
-      `MUSHI_API_ENDPOINT=${endpoint}`,
-      `MUSHI_PROJECT_ID=${projectId}`,
-      `MUSHI_API_KEY=${apiKey}`,
-      ""
-    ];
-    const envExisting = existsSync4(envPath);
-    await writeFile(envPath, envLines.join("\n"), "utf8");
+    const { envUpdated, mcpUpdated } = await writeProjectBootstrapFiles({
+      endpoint,
+      projectId,
+      apiKey
+    });
     console.log(`
-  \u2713 ${envExisting ? "Updated" : "Created"} .env.local`);
-    const mcpPath = nodePath.join(cwd, ".cursor", "mcp.json");
-    const serverName = buildMcpServerName({ legacy: true });
-    const serverBlock = buildMcpServerBlock({ endpoint, projectId, apiKey });
-    const { created: mcpCreated } = await writeMcpServerEntry({ configPath: mcpPath, serverName, serverBlock });
-    console.log(`  \u2713 ${mcpCreated ? "Created" : "Updated"} .cursor/mcp.json`);
+  OK  ${envUpdated ? "Updated" : "Created"} .env.local`);
+    console.log(`  OK  ${mcpUpdated ? "Updated" : "Created"} .cursor/mcp.json`);
     console.log("");
     console.log('  Done! Restart Cursor and ask: "list mushi tools"');
     console.log("  Run `mushi whoami` to verify the connection.");
@@ -2495,7 +2635,7 @@ error: Could not create project: ${err instanceof Error ? err.message : String(e
 
 // src/commands/setup.ts
 function registerSetupCommands(program2) {
-  program2.command("setup").description("Wire Cursor MCP into your IDE (reads ~/.config/mushi/config.json \u2014 run `mushi login` first)").option("--ide <ide>", "Target IDE: cursor | claude | continue | zed", "cursor").option("--project-slug <slug>", "Override the project slug in the server name (default: fetched from API or ID prefix)").option("--all-projects", "Write a separate mushi-<name> server entry for every accessible project").option("--with-rules", "Also write the .cursorrules / .claude/rules/mushi.md lesson-library hook").option("--dry-run", "Print what would be written without making changes").addHelpText("after", `
+  program2.command("setup").description("Wire Cursor MCP into your IDE (reads ~/.config/mushi/config.json \u2014 run `mushi login` first)").option("--ide <ide>", "Target IDE: cursor | claude | continue | zed", "cursor").option("--project-slug <slug>", "Override the project slug in the server name (default: fetched from API or ID prefix)").option("--all-projects", "Write a separate mushi-<name> server entry for every accessible project").option("--with-rules", "Also write the .cursorrules / .claude/rules/mushi.md lesson-library hook").option("--dry-run", "Print what would be written without making changes").option("--verify", "Probe the MCP key after writing to confirm it has mcp:read scope (default: on)").option("--no-verify", "Skip the post-write key probe").addHelpText("after", `
 Examples:
   mushi setup                         # wire Cursor (default)
   mushi setup --all-projects          # one server entry per accessible project
@@ -2509,9 +2649,9 @@ Supported IDEs:
   zed       \u2014 writes ~/.config/zed/settings.json mcpServers block
 
 The command reads credentials from ~/.config/mushi/config.json (run \`mushi login\` first).`).action(async (opts) => {
-    const { writeFile, mkdir, readFile: readFile2 } = await import("fs/promises");
-    const { existsSync: existsSync4 } = await import("fs");
-    const nodePath = await import("path");
+    const { writeFile: writeFile2, mkdir, readFile: readFile2 } = await import("fs/promises");
+    const { existsSync: existsSync5 } = await import("fs");
+    const nodePath2 = await import("path");
     const os = await import("os");
     const config = requireConfig({ needsProject: true });
     const redactKeyForDisplay = (text2) => {
@@ -2554,7 +2694,7 @@ The command reads credentials from ~/.config/mushi/config.json (run \`mushi logi
       cursor: { dir: ".cursor", file: "mcp.json", format: "mcp-json" },
       claude: { dir: ".claude", file: "mcp.json", format: "mcp-json" },
       continue: { dir: ".continue", file: "mcp.json", format: "mcp-json" },
-      zed: { dir: nodePath.join(os.homedir(), ".config", "zed"), file: "settings.json", format: "zed" }
+      zed: { dir: nodePath2.join(os.homedir(), ".config", "zed"), file: "settings.json", format: "zed" }
     };
     const ideEntry = IDE_CONFIG[opts.ide];
     if (!ideEntry) {
@@ -2590,8 +2730,8 @@ The command reads credentials from ~/.config/mushi/config.json (run \`mushi logi
         MUSHI_API_KEY: config.apiKey
       }
     };
-    const configDir = ideEntry.dir.startsWith("/") ? ideEntry.dir : nodePath.join(cwd, ideEntry.dir);
-    const configPath = nodePath.join(configDir, ideEntry.file);
+    const configDir = ideEntry.dir.startsWith("/") ? ideEntry.dir : nodePath2.join(cwd, ideEntry.dir);
+    const configPath = nodePath2.join(configDir, ideEntry.file);
     if (ideEntry.format === "mcp-json") {
       if (allProjectsList && allProjectsList.length > 0) {
         for (const p3 of allProjectsList) {
@@ -2622,7 +2762,7 @@ The command reads credentials from ~/.config/mushi/config.json (run \`mushi logi
       }
     } else if (ideEntry.format === "zed") {
       let settings = {};
-      if (existsSync4(configPath)) {
+      if (existsSync5(configPath)) {
         try {
           const raw = await readFile2(configPath, "utf8");
           settings = JSON.parse(raw);
@@ -2649,7 +2789,7 @@ The command reads credentials from ~/.config/mushi/config.json (run \`mushi logi
         console.log(redactKeyForDisplay(output));
       } else {
         await mkdir(configDir, { recursive: true });
-        await writeFile(configPath, output, "utf8");
+        await writeFile2(configPath, output, "utf8");
         console.log(`\u2713 Written ${configPath}`);
       }
     }
@@ -2664,7 +2804,7 @@ The command reads credentials from ~/.config/mushi/config.json (run \`mushi logi
         "## Before writing a fix",
         "",
         "1. Call `get_fix_context` (MCP) for the report \u2014 get root cause + blast radius first.",
-        "2. Call `lessons.query` (MCP) or read .mushi/lessons.json \u2014 apply every matching rule.",
+        "2. Call `list_lessons` (MCP) or read .mushi/lessons.json \u2014 apply every matching rule.",
         "3. Prefer the smallest change that makes the test pass. Don't refactor unrelated code.",
         "",
         "## After writing a fix",
@@ -2679,178 +2819,642 @@ The command reads credentials from ~/.config/mushi/config.json (run \`mushi logi
         ""
       ].join("\n");
       if (opts.ide === "cursor") {
-        const rulesPath = nodePath.join(cwd, ".cursorrules");
+        const rulesPath = nodePath2.join(cwd, ".cursorrules");
         if (opts.dryRun) {
           console.log(`[dry-run] Would write ${rulesPath}`);
         } else {
-          await writeFile(rulesPath, rulesContent, "utf8");
+          await writeFile2(rulesPath, rulesContent, "utf8");
           console.log(`\u2713 Written .cursorrules`);
         }
       } else if (opts.ide === "claude") {
-        const rulesDir = nodePath.join(cwd, ".claude", "rules");
-        const rulesPath = nodePath.join(rulesDir, "mushi.md");
+        const rulesDir = nodePath2.join(cwd, ".claude", "rules");
+        const rulesPath = nodePath2.join(rulesDir, "mushi.md");
         if (opts.dryRun) {
           console.log(`[dry-run] Would write ${rulesPath}`);
         } else {
           await mkdir(rulesDir, { recursive: true });
-          await writeFile(rulesPath, rulesContent, "utf8");
+          await writeFile2(rulesPath, rulesContent, "utf8");
           console.log(`\u2713 Written .claude/rules/mushi.md`);
         }
       }
     }
     if (!opts.dryRun) {
+      const shouldVerify = opts.verify !== false;
+      if (shouldVerify && config.endpoint && config.apiKey && config.projectId) {
+        try {
+          const probeRes = await fetch(
+            `${config.endpoint.replace(/\/$/, "")}/v1/admin/mcp/account-overview`,
+            {
+              headers: {
+                "X-Mushi-Api-Key": config.apiKey,
+                "X-Mushi-Project": config.projectId
+              },
+              signal: AbortSignal.timeout(6e3)
+            }
+          );
+          if (probeRes.ok) {
+            console.log("\u2713 MCP key valid \u2014 restart Cursor (or your IDE) to activate");
+            void fetch(
+              `${config.endpoint.replace(/\/$/, "")}/v1/cli/funnel`,
+              {
+                method: "POST",
+                headers: {
+                  "Content-Type": "application/json",
+                  "X-Mushi-Api-Key": config.apiKey,
+                  "X-Mushi-Project": config.projectId
+                },
+                body: JSON.stringify({ event: "mcp_setup_done", source: "cli" }),
+                signal: AbortSignal.timeout(4e3)
+              }
+            ).catch(() => {
+            });
+          } else if (probeRes.status === 403) {
+            let errCode;
+            try {
+              const b = await probeRes.json();
+              errCode = b?.error?.code;
+            } catch {
+            }
+            if (errCode === "INSUFFICIENT_SCOPE") {
+              console.log("\n\u26A0  Your key has report:write scope only \u2014 MCP admin tools will not work.");
+              console.log("   New keys minted by the wizard include both scopes automatically.");
+              console.log("   To upgrade an existing key, run:\n");
+              console.log("     mushi login --upgrade-scope\n");
+            } else {
+              console.log(`\u26A0  Key probe returned HTTP ${probeRes.status} \u2014 check your credentials.`);
+            }
+          }
+        } catch {
+        }
+      }
       console.log("");
       console.log(`Done! Restart ${opts.ide === "cursor" ? "Cursor" : opts.ide === "claude" ? "Claude Code" : opts.ide} and ask: "list mushi tools"`);
       if (!opts.withRules) {
         console.log(`Tip: run with --with-rules to also write the lesson-library coding hook.`);
       }
-      const configRelPath = ideEntry.dir.startsWith("/") ? configPath : nodePath.relative(cwd, configPath);
+      const configRelPath = ideEntry.dir.startsWith("/") ? configPath : nodePath2.relative(cwd, configPath);
       console.log(`
 Note: ${configRelPath} contains your Mushi API key \u2014 add it to .gitignore if this is a shared repo.`);
     }
   });
 }
 
-// src/nudge.ts
-var PRESETS = {
-  // Alpha: noisy is OK because there are very few users and you need
-  // signal yesterday. Show all triggers, short cooldowns.
-  alpha: {
-    maxProactivePerSession: 3,
-    dismissCooldownHours: 6,
-    suppressAfterDismissals: 5,
-    pageDwellMinutes: 3,
-    firstSessionSeconds: 30,
-    rageClick: true,
-    longTask: true,
-    apiCascade: true,
-    errorBoundary: true,
-    betaMode: true,
-    featureRequestCard: true
-  },
-  // Beta: most apps spend the longest here. Conservative cadence so
-  // we don't poison the well, but every trigger still on.
-  beta: {
-    maxProactivePerSession: 2,
-    dismissCooldownHours: 24,
-    suppressAfterDismissals: 3,
-    pageDwellMinutes: 5,
-    firstSessionSeconds: 45,
-    rageClick: true,
-    longTask: true,
-    apiCascade: true,
-    errorBoundary: true,
-    betaMode: true,
-    featureRequestCard: true
-  },
-  // GA / production: only the technical signals (error boundary, rage
-  // click). No page-dwell, no welcome — those are explicitly beta-only
-  // patterns. Feature-request card still on because it's user-initiated.
-  ga: {
-    maxProactivePerSession: 1,
-    dismissCooldownHours: 168,
-    suppressAfterDismissals: 2,
-    pageDwellMinutes: 0,
-    firstSessionSeconds: 0,
-    rageClick: true,
-    longTask: false,
-    apiCascade: true,
-    errorBoundary: true,
-    betaMode: false,
-    featureRequestCard: true
-  }
-};
-function renderNudgeSnippet(opts) {
-  const p3 = { ...PRESETS[opts.phase], ...opts.overrides };
-  const dwellMs = p3.pageDwellMinutes > 0 ? `${p3.pageDwellMinutes} * 60 * 1000` : null;
-  const firstMs = p3.firstSessionSeconds > 0 ? `${p3.firstSessionSeconds} * 1000` : null;
-  const proactiveLines = [];
-  if (p3.rageClick) proactiveLines.push(`    rageClick: true,`);
-  if (p3.longTask) proactiveLines.push(`    longTask: true,`);
-  if (p3.apiCascade) proactiveLines.push(`    apiCascade: true,`);
-  if (p3.errorBoundary) proactiveLines.push(`    errorBoundary: true,`);
-  if (dwellMs) proactiveLines.push(`    pageDwell: { thresholdMs: ${dwellMs} }, // ${p3.pageDwellMinutes}min on the same route`);
-  if (firstMs) proactiveLines.push(`    firstSession: { delayMs: ${firstMs} }, // welcome new users after ${p3.firstSessionSeconds}s`);
-  proactiveLines.push(`    cooldown: {`);
-  proactiveLines.push(`      maxProactivePerSession: ${p3.maxProactivePerSession},`);
-  proactiveLines.push(`      dismissCooldownHours: ${p3.dismissCooldownHours},`);
-  proactiveLines.push(`      suppressAfterDismissals: ${p3.suppressAfterDismissals},`);
-  proactiveLines.push(`    },`);
-  const widgetLines = [];
-  if (p3.featureRequestCard) widgetLines.push(`    featureRequestCard: true,`);
-  if (p3.betaMode) {
-    widgetLines.push(`    betaMode: {`);
-    widgetLines.push(`      enabled: true,`);
-    widgetLines.push(`      label: 'BETA',`);
-    widgetLines.push(`      // changelogItems: [{ version: 'v0.42', date: '${(/* @__PURE__ */ new Date()).toISOString().slice(0, 10)}', items: ['\u2026'] }],`);
-    widgetLines.push(`    },`);
-  }
-  return [
-    `// Generated by \`mushi nudge --phase ${opts.phase}\``,
-    `// Phase: ${opts.phase} \u2014 tune via --max, --cooldown, --dwell, --welcome.`,
-    `Mushi.init({`,
-    `  projectId: process.env.MUSHI_PROJECT_ID!,`,
-    `  apiKey: process.env.MUSHI_API_KEY!,`,
-    `  proactive: {`,
-    ...proactiveLines,
-    `  },`,
-    ...widgetLines.length ? [`  widget: {`, ...widgetLines, `  },`] : [],
-    `})`,
-    ``
-  ].join("\n");
-}
-function renderNudgeExplainer(phase) {
-  const p3 = PRESETS[phase];
-  const lines = [];
-  lines.push(``);
-  lines.push(`Nudge preset for "${phase}" phase:`);
-  lines.push(`  - max ${p3.maxProactivePerSession} proactive prompts per session`);
-  lines.push(`  - ${p3.dismissCooldownHours}h cooldown after a dismissal`);
-  lines.push(`  - suppress permanently after ${p3.suppressAfterDismissals} consecutive dismissals`);
-  if (p3.pageDwellMinutes > 0) lines.push(`  - fire page-dwell trigger after ${p3.pageDwellMinutes} continuous minutes on a route`);
-  if (p3.firstSessionSeconds > 0) lines.push(`  - welcome new users with a button pulse ${p3.firstSessionSeconds}s after init`);
-  lines.push(`  - signals enabled: ${[
-    p3.rageClick && "rage-click",
-    p3.longTask && "long-task",
-    p3.apiCascade && "api-cascade",
-    p3.errorBoundary && "error-boundary"
-  ].filter(Boolean).join(", ")}`);
-  lines.push(`  - feature-request card: ${p3.featureRequestCard ? "shown" : "hidden"}`);
-  lines.push(`  - beta-mode UI: ${p3.betaMode ? "on" : "off"}`);
-  lines.push(``);
-  return lines.join("\n");
-}
+// src/commands/fix.ts
+function registerFixCommands(program2) {
+  const fixCmd = program2.command("fix").description("Dispatch an agentic fix for a report");
+  fixCmd.argument("<reportId>", "Report UUID to fix").option(
+    "--agent <name>",
+    "Agent adapter: claude_code (default), cursor_cloud, codex, mcp",
+    "claude_code"
+  ).option(
+    "--model <slug>",
+    "Model override for cursor_cloud (e.g. composer-latest)"
+  ).option(
+    "--no-auto-pr",
+    "For cursor_cloud: skip automatic PR creation (branch only)"
+  ).option(
+    "--wait",
+    "Poll until terminal state and exit non-zero on error/cancelled (CI-friendly)"
+  ).option("-e, --endpoint <url>", "API endpoint (overrides MUSHI_API_ENDPOINT)").option("--api-key <key>", "API key (overrides MUSHI_API_KEY)").option("--project-id <id>", "Project ID (overrides MUSHI_PROJECT_ID)").addHelpText("after", `
+Examples:
+  mushi fix abc123 --agent cursor_cloud --wait
+  mushi fix abc123 --agent cursor_cloud --model composer-latest --no-auto-pr
+  mushi fix abc123 --agent claude_code
 
-// src/doctor.ts
-function checkCliConfig(config) {
-  return [
-    {
-      name: "CLI config file",
-      ok: Boolean(config.endpoint),
-      detail: config.endpoint ? `endpoint=${config.endpoint}` : "No endpoint \u2014 set MUSHI_API_ENDPOINT, run `mushi connect`, or `mushi config endpoint <url>`"
-    },
-    {
-      name: "API key configured",
-      ok: Boolean(config.apiKey),
-      detail: config.apiKey ? `apiKey=${config.apiKey.slice(0, 8)}\u2026${config.apiKey.slice(-4)}` : "No API key set \u2014 run `mushi login --api-key <key>`"
-    },
-    {
-      name: "Project ID configured",
-      ok: Boolean(config.projectId),
-      detail: config.projectId ? `projectId=${config.projectId}` : "No default project \u2014 set via `mushi config projectId <uuid>`"
-    }
-  ];
-}
-async function checkEndpointReachability(endpoint, doFetch = globalThis.fetch) {
-  try {
-    const safeEndpoint = sanitizeEndpoint(endpoint);
-    const res = await doFetch(`${safeEndpoint}/health`, {
-      signal: AbortSignal.timeout(5e3)
-    });
-    return {
-      name: "Endpoint reachable",
-      ok: res.status === 200,
-      detail: `GET ${safeEndpoint}/health \u2192 ${res.status}`
+  # CI: fail the pipeline if the fix errors
+  mushi fix $REPORT_ID --agent cursor_cloud --wait && echo "Fix PR opened"`).action(async (reportId, opts) => {
+    const cfg = loadConfig();
+    if (opts.endpoint) cfg.endpoint = opts.endpoint;
+    if (opts.apiKey) cfg.apiKey = opts.apiKey;
+    if (opts.projectId) cfg.projectId = opts.projectId;
+    const isTTY = process.stdout.isTTY;
+    const emitEvent = (type, data) => {
+      if (isTTY) {
+        const ts = (/* @__PURE__ */ new Date()).toISOString();
+        console.log(`[${ts}] ${type}`, JSON.stringify(data));
+      } else {
+        process.stdout.write(JSON.stringify({ type, ...data }) + "\n");
+      }
+    };
+    emitEvent("dispatch.start", { reportId, agent: opts.agent, model: opts.model ?? null });
+    const body = {
+      reportId,
+      projectId: cfg.projectId,
+      agent: opts.agent
+    };
+    if (opts.agent === "cursor_cloud") {
+      if (opts.model) body.cursorModel = opts.model;
+      if (!opts.autoPr) body.cursorAutoCreatePR = false;
+    }
+    const result = await apiCall("/v1/admin/fixes/dispatch", cfg, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body)
+    });
+    if (!result.ok) {
+      console.error("Error dispatching fix:", result.error.message);
+      process.exit(1);
+    }
+    const { fixId, status, agentId, runId, prUrl } = result.data;
+    emitEvent("dispatch.ok", { fixId, status, agentId, runId, prUrl });
+    if (!opts.wait) {
+      process.exit(0);
+    }
+    if (!fixId) {
+      console.error("No fixId returned \u2014 cannot poll.");
+      process.exit(1);
+    }
+    const POLL_MS = 5e3;
+    const MAX_POLLS = 120;
+    const TERMINAL = /* @__PURE__ */ new Set(["completed", "failed", "error", "cancelled", "skipped", "skipped_unsupported_agent", "skipped_no_sandbox"]);
+    for (let i = 0; i < MAX_POLLS; i++) {
+      await new Promise((r) => setTimeout(r, POLL_MS));
+      const pollResult = await apiCall(
+        `/v1/admin/fixes/${fixId}`,
+        cfg
+      );
+      if (!pollResult.ok) {
+        emitEvent("poll.error", { error: pollResult.error.message });
+        continue;
+      }
+      const s = pollResult.data.status;
+      emitEvent("fix.status", { status: s, pr_url: pollResult.data.pr_url, cursor_agent_id: pollResult.data.cursor_agent_id });
+      if (s && TERMINAL.has(s)) {
+        const success = s === "completed";
+        if (!success) {
+          console.error(`Fix ended with status: ${s}${pollResult.data.error ? ` \u2014 ${pollResult.data.error}` : ""}`);
+          process.exit(1);
+        }
+        process.exit(0);
+      }
+    }
+    console.error("Polling timed out after 10 minutes. The fix may still be running.");
+    process.exit(1);
+  });
+  const fixes = program2.command("fixes").description("Fix dispatch management");
+  fixes.command("tail").description(
+    "Stream SSE dispatch events for a report in real time. Useful for headless debugging without opening the browser."
+  ).requiredOption("--report-id <id>", "Report ID to follow").action(async (opts) => {
+    const config = loadConfig();
+    if (!config.apiKey) {
+      console.error("Run `mushi login` first");
+      process.exit(1);
+    }
+    if (!config.endpoint) {
+      console.error("No endpoint configured. Run `mushi init`");
+      process.exit(1);
+    }
+    const url = `${config.endpoint}/v1/admin/reports/${opts.reportId}/dispatch/stream`;
+    console.log(`Tailing dispatch stream for report ${opts.reportId}\u2026`);
+    console.log(`(Ctrl-C to stop)
+`);
+    const res = await fetch(url, {
+      headers: {
+        "Authorization": `Bearer ${config.apiKey}`,
+        "X-Mushi-Api-Key": config.apiKey,
+        "X-Mushi-Project": config.projectId ?? "",
+        "Accept": "text/event-stream"
+      }
+    });
+    if (!res.ok || !res.body) {
+      console.error(`Failed to connect: HTTP ${res.status}`);
+      const text2 = await res.text().catch(() => "");
+      if (text2) console.error(text2.slice(0, 300));
+      process.exit(1);
+    }
+    const decoder = new TextDecoder();
+    const reader = res.body.getReader();
+    let done = false;
+    process.on("SIGINT", () => {
+      done = true;
+      void reader.cancel();
+      console.log("\nDisconnected.");
+      process.exit(0);
+    });
+    while (!done) {
+      const { value, done: streamDone } = await reader.read();
+      if (streamDone) break;
+      const chunk = decoder.decode(value, { stream: true });
+      for (const line of chunk.split("\n")) {
+        if (line.startsWith("data: ")) {
+          const raw = line.slice(6).trim();
+          if (raw === "[DONE]") {
+            console.log("\n[stream ended]");
+            process.exit(0);
+          }
+          try {
+            const event = JSON.parse(raw);
+            const ts = (/* @__PURE__ */ new Date()).toISOString();
+            const type = event.type ?? event.event ?? "event";
+            const status = event.status ?? event.data ?? "";
+            console.log(`${ts}  ${type.padEnd(24)}  ${status}`);
+          } catch {
+            console.log(line);
+          }
+        } else if (line.startsWith("event: ")) {
+        } else if (line && !line.startsWith(":")) {
+          console.log(line);
+        }
+      }
+    }
+  });
+  fixes.command("merge <fixId>").description(
+    "Squash-merge the fix PR on GitHub and mark the report Fixed (same as console merge)"
+  ).option(
+    "--method <method>",
+    "GitHub merge method: squash (default), merge, or rebase",
+    "squash"
+  ).option("--json", "Machine-readable JSON output").action(async (fixId, opts) => {
+    const config = loadConfig();
+    if (!config.apiKey) {
+      console.error("Run `mushi login` first");
+      process.exit(1);
+    }
+    if (!config.endpoint) {
+      console.error("No endpoint configured. Run `mushi init`");
+      process.exit(1);
+    }
+    const method = opts.method;
+    if (!["squash", "merge", "rebase"].includes(method)) {
+      console.error("--method must be squash, merge, or rebase");
+      process.exit(1);
+    }
+    const result = await apiCall(`/v1/admin/fixes/${fixId}/merge`, config, {
+      method: "POST",
+      body: JSON.stringify({ mergeMethod: method })
+    });
+    if (!result.ok) {
+      if (opts.json) {
+        console.log(JSON.stringify({ ok: false, error: result.error }, null, 2));
+      } else {
+        console.error("Merge failed:", result.error.message);
+      }
+      process.exit(1);
+    }
+    const data = result.data ?? {};
+    if (opts.json) {
+      console.log(JSON.stringify({ ok: true, ...data }, null, 2));
+      return;
+    }
+    if (data.alreadyMerged) {
+      console.log(`PR was already merged. Report status: ${data.reportStatus ?? "unknown"}`);
+    } else {
+      console.log(`Merged successfully. Report status: ${data.reportStatus ?? "fixed"}`);
+    }
+  });
+  fixes.command("refresh-ci <fixId>").description("Pull latest GitHub Actions check-run status for a fix attempt (on-demand ci-sync)").option("--json", "Machine-readable JSON output").action(async (fixId, opts) => {
+    const config = loadConfig();
+    if (!config.apiKey) {
+      console.error("Run `mushi login` first");
+      process.exit(1);
+    }
+    if (!config.endpoint) {
+      console.error("No endpoint configured. Run `mushi init`");
+      process.exit(1);
+    }
+    const result = await apiCall(`/v1/admin/fixes/${fixId}/refresh-ci`, config, { method: "POST" });
+    if (!result.ok) {
+      if (opts.json) {
+        console.log(JSON.stringify({ ok: false, error: result.error }, null, 2));
+      } else {
+        console.error("CI refresh failed:", result.error.message);
+      }
+      process.exit(1);
+    }
+    const data = result.data ?? {};
+    if (opts.json) {
+      console.log(JSON.stringify({ ok: true, ...data }, null, 2));
+      return;
+    }
+    const status = data.check_run_status ?? "unknown";
+    const conclusion = data.check_run_conclusion ?? "\u2014";
+    const updated = data.check_run_updated_at ? new Date(data.check_run_updated_at).toISOString() : "\u2014";
+    console.log(`CI status: ${status} \xB7 conclusion: ${conclusion} \xB7 updated: ${updated}`);
+  });
+}
+
+// src/nudge.ts
+var PRESETS = {
+  // Alpha: noisy is OK because there are very few users and you need
+  // signal yesterday. Show all triggers, short cooldowns.
+  alpha: {
+    maxProactivePerSession: 3,
+    dismissCooldownHours: 6,
+    suppressAfterDismissals: 5,
+    pageDwellMinutes: 3,
+    firstSessionSeconds: 30,
+    rageClick: true,
+    longTask: true,
+    apiCascade: true,
+    errorBoundary: true,
+    betaMode: true,
+    featureRequestCard: true
+  },
+  // Beta: most apps spend the longest here. Conservative cadence so
+  // we don't poison the well, but every trigger still on.
+  beta: {
+    maxProactivePerSession: 2,
+    dismissCooldownHours: 24,
+    suppressAfterDismissals: 3,
+    pageDwellMinutes: 5,
+    firstSessionSeconds: 45,
+    rageClick: true,
+    longTask: true,
+    apiCascade: true,
+    errorBoundary: true,
+    betaMode: true,
+    featureRequestCard: true
+  },
+  // GA / production: only the technical signals (error boundary, rage
+  // click). No page-dwell, no welcome — those are explicitly beta-only
+  // patterns. Feature-request card still on because it's user-initiated.
+  ga: {
+    maxProactivePerSession: 1,
+    dismissCooldownHours: 168,
+    suppressAfterDismissals: 2,
+    pageDwellMinutes: 0,
+    firstSessionSeconds: 0,
+    rageClick: true,
+    longTask: false,
+    apiCascade: true,
+    errorBoundary: true,
+    betaMode: false,
+    featureRequestCard: true
+  }
+};
+function renderNudgeSnippet(opts) {
+  const p3 = { ...PRESETS[opts.phase], ...opts.overrides };
+  const dwellMs = p3.pageDwellMinutes > 0 ? `${p3.pageDwellMinutes} * 60 * 1000` : null;
+  const firstMs = p3.firstSessionSeconds > 0 ? `${p3.firstSessionSeconds} * 1000` : null;
+  const proactiveLines = [];
+  if (p3.rageClick) proactiveLines.push(`    rageClick: true,`);
+  if (p3.longTask) proactiveLines.push(`    longTask: true,`);
+  if (p3.apiCascade) proactiveLines.push(`    apiCascade: true,`);
+  if (p3.errorBoundary) proactiveLines.push(`    errorBoundary: true,`);
+  if (dwellMs) proactiveLines.push(`    pageDwell: { thresholdMs: ${dwellMs} }, // ${p3.pageDwellMinutes}min on the same route`);
+  if (firstMs) proactiveLines.push(`    firstSession: { delayMs: ${firstMs} }, // welcome new users after ${p3.firstSessionSeconds}s`);
+  proactiveLines.push(`    cooldown: {`);
+  proactiveLines.push(`      maxProactivePerSession: ${p3.maxProactivePerSession},`);
+  proactiveLines.push(`      dismissCooldownHours: ${p3.dismissCooldownHours},`);
+  proactiveLines.push(`      suppressAfterDismissals: ${p3.suppressAfterDismissals},`);
+  proactiveLines.push(`    },`);
+  const widgetLines = [];
+  if (p3.featureRequestCard) widgetLines.push(`    featureRequestCard: true,`);
+  if (p3.betaMode) {
+    widgetLines.push(`    betaMode: {`);
+    widgetLines.push(`      enabled: true,`);
+    widgetLines.push(`      label: 'BETA',`);
+    widgetLines.push(`      // changelogItems: [{ version: '1.0.0', date: '${(/* @__PURE__ */ new Date()).toISOString().slice(0, 10)}', items: ['Fixed login timeout on slow networks'] }],`);
+    widgetLines.push(`    },`);
+  }
+  return [
+    `// Generated by \`mushi nudge --phase ${opts.phase}\``,
+    `// Phase: ${opts.phase} \u2014 tune via --max, --cooldown, --dwell, --welcome.`,
+    `Mushi.init({`,
+    `  projectId: process.env.MUSHI_PROJECT_ID!,`,
+    `  apiKey: process.env.MUSHI_API_KEY!,`,
+    `  proactive: {`,
+    ...proactiveLines,
+    `  },`,
+    ...widgetLines.length ? [`  widget: {`, ...widgetLines, `  },`] : [],
+    `})`,
+    ``
+  ].join("\n");
+}
+function renderNudgeExplainer(phase) {
+  const p3 = PRESETS[phase];
+  const lines = [];
+  lines.push(``);
+  lines.push(`Nudge preset for "${phase}" phase:`);
+  lines.push(`  - max ${p3.maxProactivePerSession} proactive prompts per session`);
+  lines.push(`  - ${p3.dismissCooldownHours}h cooldown after a dismissal`);
+  lines.push(`  - suppress permanently after ${p3.suppressAfterDismissals} consecutive dismissals`);
+  if (p3.pageDwellMinutes > 0) lines.push(`  - fire page-dwell trigger after ${p3.pageDwellMinutes} continuous minutes on a route`);
+  if (p3.firstSessionSeconds > 0) lines.push(`  - welcome new users with a button pulse ${p3.firstSessionSeconds}s after init`);
+  lines.push(`  - signals enabled: ${[
+    p3.rageClick && "rage-click",
+    p3.longTask && "long-task",
+    p3.apiCascade && "api-cascade",
+    p3.errorBoundary && "error-boundary"
+  ].filter(Boolean).join(", ")}`);
+  lines.push(`  - feature-request card: ${p3.featureRequestCard ? "shown" : "hidden"}`);
+  lines.push(`  - beta-mode UI: ${p3.betaMode ? "on" : "off"}`);
+  lines.push(``);
+  return lines.join("\n");
+}
+
+// src/commands/nudge.ts
+function registerNudgeCommand(program2) {
+  program2.command("nudge").description(
+    "Generate a Mushi.init() snippet tuned for your release phase (alpha, beta, ga). Customises proactive triggers, cooldowns, feature-request card, and beta-mode UI."
+  ).option("--phase <phase>", "Release phase: alpha | beta | ga", "beta").option("--explain", "Print a human-readable summary of what the preset does").option("--max <n>", "Override maxProactivePerSession").option("--cooldown <hours>", "Override dismissCooldownHours").option("--dwell <minutes>", "Override page-dwell threshold (0 disables)").option("--welcome <seconds>", "Override first-session welcome delay (0 disables)").action((opts) => {
+    const validPhases = ["alpha", "beta", "ga"];
+    if (!validPhases.includes(opts.phase)) {
+      console.error(`Unknown phase "${opts.phase}". Use one of: ${validPhases.join(", ")}`);
+      process.exit(1);
+    }
+    const phase = opts.phase;
+    const overrides = {};
+    const parseNumericFlag = (flag, raw, min) => {
+      const n = Number(raw);
+      if (!Number.isFinite(n) || n < min) {
+        console.error(
+          `error: --${flag} must be a finite number >= ${min} (got "${raw}")`
+        );
+        process.exit(1);
+      }
+      return n;
+    };
+    if (opts.max !== void 0) overrides.maxProactivePerSession = parseNumericFlag("max", opts.max, 1);
+    if (opts.cooldown !== void 0) overrides.dismissCooldownHours = parseNumericFlag("cooldown", opts.cooldown, 0);
+    if (opts.dwell !== void 0) overrides.pageDwellMinutes = parseNumericFlag("dwell", opts.dwell, 0);
+    if (opts.welcome !== void 0) overrides.firstSessionSeconds = parseNumericFlag("welcome", opts.welcome, 0);
+    if (opts.explain) {
+      console.log(renderNudgeExplainer(phase));
+    }
+    console.log(renderNudgeSnippet({ phase, overrides }));
+  });
+}
+
+// src/upgrade.ts
+import { resolve as resolve2 } from "path";
+import { execSync } from "child_process";
+var SAFE_NPM_VERSION = /^\d+\.\d+\.\d+(-[\w.]+)?$/;
+var MUSHI_PACKAGES = [
+  "@mushi-mushi/web",
+  "@mushi-mushi/core",
+  "@mushi-mushi/react",
+  "@mushi-mushi/react-native",
+  "@mushi-mushi/capacitor",
+  "@mushi-mushi/node",
+  "@mushi-mushi/cli"
+];
+async function planUpgrade(cwd) {
+  const root = resolve2(cwd);
+  const pkg = readPackageJson(root);
+  const pm = detectPackageManager(root);
+  const deps = {
+    ...pkg?.dependencies ?? {},
+    ...pkg?.devDependencies ?? {}
+  };
+  const installed2 = MUSHI_PACKAGES.filter((name) => deps[name]);
+  const entries = await Promise.all(
+    installed2.map(async (name) => {
+      const current = deps[name] ?? "";
+      const currentCore = current.replace(/^[\^~>=<]*/, "");
+      if (!/^\d/.test(currentCore)) {
+        return { name, current, latest: null, willUpgrade: false };
+      }
+      const freshness = await checkFreshness(name, currentCore, {
+        timeoutMs: 4e3,
+        ignoreOptOut: true
+      });
+      const latest = freshness?.latest ?? null;
+      const safeLatest = latest && SAFE_NPM_VERSION.test(latest) ? latest : null;
+      const willUpgrade = Boolean(freshness?.isOutdated && safeLatest);
+      return {
+        name,
+        current,
+        latest: safeLatest,
+        willUpgrade,
+        migrateToWeb: name === "@mushi-mushi/react" && willUpgrade
+      };
+    })
+  );
+  const toBump = entries.filter((e) => e.willUpgrade && e.latest).map((e) => `${e.name}@${e.latest}`);
+  return {
+    cwd: root,
+    packageManager: pm,
+    entries,
+    installCmd: toBump.length > 0 ? installCommand(pm, toBump) : null
+  };
+}
+async function runUpgrade(opts = {}) {
+  const plan = await planUpgrade(opts.cwd ?? process.cwd());
+  if (plan.entries.length === 0) {
+    return {
+      plan,
+      upgraded: false,
+      message: "No @mushi-mushi/* packages in package.json \u2014 run `mushi init` first."
+    };
+  }
+  if (!plan.installCmd) {
+    const semverEntries = plan.entries.filter((e) => /\d/.test(e.current));
+    const allChecksFailed = semverEntries.length > 0 && semverEntries.every((e) => e.latest === null);
+    return {
+      plan,
+      upgraded: false,
+      message: allChecksFailed ? "Could not reach the npm registry to check for updates \u2014 try again in a moment." : "All installed Mushi packages are already at the latest stable version."
+    };
+  }
+  if (opts.dryRun) {
+    return { plan, upgraded: false, message: `[dry-run] Would run: ${plan.installCmd}` };
+  }
+  try {
+    execSync(plan.installCmd, { cwd: plan.cwd, stdio: "inherit", env: process.env });
+  } catch {
+    return {
+      plan,
+      upgraded: false,
+      message: `Install command failed \u2014 fix the error above or run it manually:
+  ${plan.installCmd}`
+    };
+  }
+  const reactEntry = plan.entries.find((e) => e.migrateToWeb);
+  const migrateNote = reactEntry ? "\nNote: @mushi-mushi/react is legacy \u2014 prefer @mushi-mushi/web for Vite/Capacitor/SPA apps." : "";
+  return {
+    plan,
+    upgraded: true,
+    message: `Upgraded Mushi SDK packages.
+  ${plan.installCmd}${migrateNote}`
+  };
+}
+
+// src/commands/upgrade-cli.ts
+function registerUpgradeCommand(program2) {
+  program2.command("upgrade").description("Bump installed @mushi-mushi/* packages to the latest stable npm release").option("--cwd <path>", "Target repo (default: cwd)").option("--dry-run", "Print the install command without running it").option("--json", "Machine-readable plan + result").addHelpText("after", `
+Examples:
+  mushi upgrade
+  mushi upgrade --dry-run
+  mushi upgrade --cwd ../glot.it`).action(async (opts) => {
+    const result = await runUpgrade({ cwd: opts.cwd, dryRun: opts.dryRun, json: opts.json });
+    if (opts.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(result.message);
+      for (const e of result.plan.entries) {
+        const tag = e.willUpgrade && e.latest ? `\u2192 v${e.latest}` : "(current)";
+        console.log(`  ${e.name}@${e.current} ${tag}`);
+      }
+    }
+    if (!result.upgraded && result.plan.entries.some((e) => e.willUpgrade) && !opts.dryRun) {
+      process.exit(1);
+    }
+    if (result.plan.entries.length === 0) process.exit(1);
+  });
+}
+
+// src/commands/connect-cli.ts
+function registerConnectCommand(program2) {
+  program2.command("connect").description("Save credentials, merge env vars, wire Cursor MCP, optionally wait for SDK heartbeat").option("--api-key <key>", "Mushi API key (mushi_\u2026) \u2014 or set MUSHI_API_KEY to keep it out of shell history").requiredOption("--project-id <id>", "Project UUID").requiredOption("--endpoint <url>", "Supabase edge function URL").option("--cwd <path>", "Target repo").option("--write-env", "Force-write SDK env vars to .env.local (default; overrides --no-env)").option("--wire-ide", "Force-wire Cursor MCP into .cursor/mcp.json (default; overrides --no-ide)").option("--no-env", "Skip writing .env.local").option("--no-ide", "Skip writing .cursor/mcp.json").option("--wait", "Poll ingest-setup until SDK heartbeat lands").option("--wait-timeout <sec>", "Max seconds for --wait", "120").option("--json", "Machine-readable output").addHelpText("after", `
+Examples:
+  MUSHI_API_KEY=mushi_xxx mushi connect --project-id <uuid> --endpoint https://<ref>.supabase.co/functions/v1/api --wait
+  mushi connect --api-key mushi_xxx --project-id <uuid> --endpoint <url> --no-ide`).action(async (opts) => {
+    const apiKey = process.env.MUSHI_API_KEY ?? opts.apiKey;
+    if (!apiKey) {
+      console.error("Provide the API key via the MUSHI_API_KEY env var (recommended) or --api-key <key>.");
+      process.exit(1);
+    }
+    const result = await runConnect({
+      apiKey,
+      projectId: opts.projectId,
+      endpoint: opts.endpoint,
+      cwd: opts.cwd,
+      writeEnv: opts.writeEnv === true ? true : opts.env !== false,
+      wireIde: opts.wireIde === true ? true : opts.ide !== false,
+      wait: opts.wait,
+      waitTimeoutSec: parseInt(opts.waitTimeout, 10) || 120,
+      json: opts.json
+    });
+    if (opts.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      for (const line of result.messages) console.log(line);
+    }
+    if (!result.ok) process.exit(1);
+  });
+}
+
+// src/doctor.ts
+function checkCliConfig(config) {
+  return [
+    {
+      name: "CLI config file",
+      ok: Boolean(config.endpoint),
+      detail: config.endpoint ? `endpoint=${config.endpoint}` : "No endpoint \u2014 set MUSHI_API_ENDPOINT, run `mushi connect`, or `mushi config endpoint <url>`"
+    },
+    {
+      name: "API key configured",
+      ok: Boolean(config.apiKey),
+      detail: config.apiKey ? `apiKey=${config.apiKey.slice(0, 8)}\u2026${config.apiKey.slice(-4)}` : "No API key set \u2014 run `mushi login --api-key <key>`"
+    },
+    {
+      name: "Project ID configured",
+      ok: Boolean(config.projectId),
+      detail: config.projectId ? `projectId=${config.projectId}` : "No default project \u2014 set via `mushi config projectId <uuid>`"
+    }
+  ];
+}
+async function checkEndpointReachability(endpoint, doFetch = globalThis.fetch) {
+  try {
+    const safeEndpoint = sanitizeEndpoint(endpoint);
+    const res = await doFetch(`${safeEndpoint}/health`, {
+      signal: AbortSignal.timeout(5e3)
+    });
+    return {
+      name: "Endpoint reachable",
+      ok: res.status === 200,
+      detail: `GET ${safeEndpoint}/health \u2192 ${res.status}`
     };
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
@@ -2909,6 +3513,23 @@ async function checkServerPreflight(config, doFetch = globalThis.fetch) {
         detail: sc.ready ? "" : sc.hint
       }));
     }
+    if (res.status === 403) {
+      let errCode;
+      try {
+        const body = await res.json();
+        errCode = body?.error?.code;
+      } catch {
+      }
+      if (errCode === "INSUFFICIENT_SCOPE") {
+        return [
+          {
+            name: "Server preflight",
+            ok: true,
+            detail: "Skipped \u2014 your key has report:write scope only (pre-Jun 2026 key). Run `mushi login --upgrade-scope` to get mcp:read and run admin checks."
+          }
+        ];
+      }
+    }
     const text2 = await res.text().catch(() => "");
     return [
       {
@@ -3111,7 +3732,17 @@ async function checkMcpConfig(config, cwd, doFetch = globalThis.fetch) {
   let mcpRaw = null;
   for (const candidate of candidates) {
     try {
-      mcpRaw = await readFile2(candidate, "utf8");
+      const raw = await readFile2(candidate, "utf8");
+      let parsed = {};
+      try {
+        parsed = JSON.parse(raw);
+      } catch {
+      }
+      const hasEntries = Object.keys(parsed.mcpServers ?? {}).length > 0;
+      if (!hasEntries && candidates.indexOf(candidate) < candidates.length - 1) {
+        continue;
+      }
+      mcpRaw = raw;
       mcpPath = candidate;
       break;
     } catch {
@@ -3188,359 +3819,212 @@ async function checkMcpConfig(config, cwd, doFetch = globalThis.fetch) {
           detail: `Key is valid; ${projectCount} accessible project${projectCount === 1 ? "" : "s"}`
         });
       } else {
-        checks.push({
-          name: "[mcp] account-overview reachable",
-          ok: false,
-          detail: `GET /v1/admin/mcp/account-overview \u2192 HTTP ${res.status}. Verify the API key is active.`
-        });
-      }
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      checks.push({
-        name: "[mcp] account-overview reachable",
-        ok: false,
-        detail: `Probe failed: ${msg}. Check MUSHI_API_ENDPOINT and network connectivity.`
-      });
-    }
-  }
-  return checks;
-}
-var FIX_HINTS = {
-  "CLI config file": "Run `mushi connect --endpoint <url> --project-id <uuid> --api-key mushi_xxx` or `mushi config endpoint <url>`.",
-  "API key configured": "Mint a key in the console (Projects \u2192 API Keys) then `mushi login --api-key mushi_xxx`.",
-  "Project ID configured": "Copy the project UUID from the console Projects page \u2192 `mushi config projectId <uuid>`.",
-  "Endpoint reachable": "Check your network and that MUSHI_API_ENDPOINT points at `\u2026/functions/v1/api`.",
-  "[ingest]": "Open the console Onboarding wizard \u2192 Install SDK \u2192 submit a test report, or run `mushi connect --wait`.",
-  "[server]": "Open Settings \u2192 Integrations: connect GitHub, index codebase, add Anthropic BYOK key, enable autofix.",
-  "[mcp]": "Run `mushi setup` to regenerate .cursor/mcp.json with a fresh API key and endpoint."
-};
-function fixHintForCheck(name) {
-  if (FIX_HINTS[name]) return FIX_HINTS[name];
-  if (name.startsWith("[ingest]")) return FIX_HINTS["[ingest]"];
-  if (name.startsWith("[server]") || name.startsWith("[preflight]")) return FIX_HINTS["[server]"];
-  if (name.startsWith("[mcp]")) return FIX_HINTS["[mcp]"];
-  return void 0;
-}
-async function runDoctor(config, options = {}) {
-  const doFetch = options.fetch ?? globalThis.fetch;
-  const checks = [];
-  const runServer = options.server !== false;
-  const runIngest = options.ingest !== false;
-  checks.push(...checkCliConfig(config));
-  if (config.endpoint) {
-    checks.push(await checkEndpointReachability(config.endpoint, doFetch));
-  }
-  const sdkCheck = await checkSdkInstall(options.cwd ?? process.cwd());
-  if (sdkCheck) checks.push(sdkCheck);
-  if (runServer) {
-    const serverChecks = await checkServerPreflight(config, doFetch);
-    checks.push(...serverChecks);
-  }
-  if (runIngest) {
-    const ingestChecks = await checkIngestSetup(config, doFetch);
-    checks.push(...ingestChecks);
-  }
-  if (options.qaStories) {
-    const qaChecks = await checkQaStoriesHealth(config, doFetch);
-    checks.push(...qaChecks);
-  }
-  if (options.hostApp) {
-    const hostChecks = await checkHostAppWiring(options.cwd ?? process.cwd());
-    checks.push(...hostChecks);
-  }
-  if (options.mcp) {
-    const mcpChecks = await checkMcpConfig(config, options.cwd ?? process.cwd(), doFetch);
-    checks.push(...mcpChecks);
-  }
-  return { checks, ready: checks.every((c) => c.ok) };
-}
-function formatDoctorResult(result) {
-  const PASS = "\u2713";
-  const FAIL = "\u2717";
-  const lines = [];
-  for (const c of result.checks) {
-    lines.push(`${c.ok ? PASS : FAIL} ${c.name}`);
-    if (c.detail) lines.push(`  ${c.detail}`);
-    if (!c.ok) {
-      const hint = fixHintForCheck(c.name);
-      if (hint) lines.push(`  \u2192 Fix: ${hint}`);
-    }
-  }
-  const failed = result.checks.filter((c) => !c.ok);
-  if (failed.length === 0) {
-    lines.push("\nAll checks passed. The CLI is ready.");
-  } else {
-    lines.push(`
-${failed.length} check${failed.length === 1 ? "" : "s"} failed.`);
-    lines.push("Fix the items above and re-run `mushi doctor`.");
-  }
-  return lines.join("\n");
-}
-
-// src/upgrade.ts
-import { resolve as resolve2 } from "path";
-import { execSync } from "child_process";
-var SAFE_NPM_VERSION = /^\d+\.\d+\.\d+(-[\w.]+)?$/;
-var MUSHI_PACKAGES = [
-  "@mushi-mushi/web",
-  "@mushi-mushi/core",
-  "@mushi-mushi/react",
-  "@mushi-mushi/react-native",
-  "@mushi-mushi/capacitor",
-  "@mushi-mushi/node",
-  "@mushi-mushi/cli"
-];
-async function planUpgrade(cwd) {
-  const root = resolve2(cwd);
-  const pkg = readPackageJson(root);
-  const pm = detectPackageManager(root);
-  const deps = {
-    ...pkg?.dependencies ?? {},
-    ...pkg?.devDependencies ?? {}
-  };
-  const installed2 = MUSHI_PACKAGES.filter((name) => deps[name]);
-  const entries = await Promise.all(
-    installed2.map(async (name) => {
-      const current = deps[name] ?? "";
-      const currentCore = current.replace(/^[\^~>=<]*/, "");
-      if (!/^\d/.test(currentCore)) {
-        return { name, current, latest: null, willUpgrade: false };
+        let detail = `GET /v1/admin/mcp/account-overview \u2192 HTTP ${res.status}. Verify the API key is active.`;
+        try {
+          const errBody = await res.json();
+          const nested = errBody["error"];
+          const errCode = nested?.["code"] ?? errBody["code"] ?? "";
+          if (errCode === "INSUFFICIENT_SCOPE") {
+            detail = `Key has report:write scope only \u2014 run \`mushi login --upgrade-scope\` then \`mushi setup\` to get mcp:read.`;
+          }
+        } catch {
+        }
+        checks.push({
+          name: "[mcp] account-overview reachable",
+          ok: false,
+          detail
+        });
       }
-      const freshness = await checkFreshness(name, currentCore, {
-        timeoutMs: 4e3,
-        ignoreOptOut: true
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      checks.push({
+        name: "[mcp] account-overview reachable",
+        ok: false,
+        detail: `Probe failed: ${msg}. Check MUSHI_API_ENDPOINT and network connectivity.`
       });
-      const latest = freshness?.latest ?? null;
-      const safeLatest = latest && SAFE_NPM_VERSION.test(latest) ? latest : null;
-      const willUpgrade = Boolean(freshness?.isOutdated && safeLatest);
+    }
+  }
+  return checks;
+}
+var FIX_HINTS = {
+  "CLI config file": "Run `mushi connect --endpoint <url> --project-id <uuid> --api-key mushi_xxx` or `mushi config endpoint <url>`.",
+  "API key configured": "Mint a key in the console (Projects \u2192 API Keys) then `mushi login --api-key mushi_xxx`.",
+  "Project ID configured": "Copy the project UUID from the console Projects page \u2192 `mushi config projectId <uuid>`.",
+  "Endpoint reachable": "Check your network and that MUSHI_API_ENDPOINT points at `\u2026/functions/v1/api`.",
+  "[ingest]": "Open the console Onboarding wizard \u2192 Install SDK \u2192 submit a test report, or run `mushi connect --wait`.",
+  "[server]": "Open Settings \u2192 Integrations: connect GitHub, index codebase, add Anthropic BYOK key, enable autofix.",
+  "[mcp]": "Run `mushi setup` to regenerate .cursor/mcp.json with a fresh API key and endpoint."
+};
+function fixHintForCheck(name) {
+  if (FIX_HINTS[name]) return FIX_HINTS[name];
+  if (name.startsWith("[ingest]")) return FIX_HINTS["[ingest]"];
+  if (name.startsWith("[server]") || name.startsWith("[preflight]")) return FIX_HINTS["[server]"];
+  if (name.startsWith("[mcp]")) return FIX_HINTS["[mcp]"];
+  return void 0;
+}
+async function checkOnboardingStatus(config, _consoleBase, cwd, doFetch = globalThis.fetch) {
+  if (!config.apiKey || !config.projectId || !config.endpoint) {
+    if (config.apiKey && config.endpoint) {
       return {
-        name,
-        current,
-        latest: safeLatest,
-        willUpgrade,
-        migrateToWeb: name === "@mushi-mushi/react" && willUpgrade
+        nextAction: "Select or create a project: run `mushi project create` or pick one with `mushi project list`",
+        ctaPath: "/onboarding?tab=steps&setup=cli",
+        done: false
       };
-    })
-  );
-  const toBump = entries.filter((e) => e.willUpgrade && e.latest).map((e) => `${e.name}@${e.latest}`);
-  return {
-    cwd: root,
-    packageManager: pm,
-    entries,
-    installCmd: toBump.length > 0 ? installCommand(pm, toBump) : null
-  };
-}
-async function runUpgrade(opts = {}) {
-  const plan = await planUpgrade(opts.cwd ?? process.cwd());
-  if (plan.entries.length === 0) {
+    }
     return {
-      plan,
-      upgraded: false,
-      message: "No @mushi-mushi/* packages in package.json \u2014 run `mushi init` first."
+      nextAction: "Sign in to Mushi: run `npx mushi-mushi` (browser opens automatically \u2014 do NOT type the code in the terminal)",
+      ctaPath: "/onboarding?tab=steps&setup=cli",
+      done: false
     };
   }
-  if (!plan.installCmd) {
-    const semverEntries = plan.entries.filter((e) => /\d/.test(e.current));
-    const allChecksFailed = semverEntries.length > 0 && semverEntries.every((e) => e.latest === null);
-    return {
-      plan,
-      upgraded: false,
-      message: allChecksFailed ? "Could not reach the npm registry to check for updates \u2014 try again in a moment." : "All installed Mushi packages are already at the latest stable version."
-    };
+  try {
+    const { readFile: readFile2 } = await import("fs/promises");
+    const { join: join5, resolve: resolve3 } = await import("path");
+    const root = resolve3(cwd);
+    let envContent = "";
+    for (const f of [".env.local", ".env"]) {
+      try {
+        envContent = await readFile2(join5(root, f), "utf8");
+        break;
+      } catch {
+      }
+    }
+    const hasEnvVars = /(?:VITE_|NEXT_PUBLIC_|EXPO_PUBLIC_|NUXT_PUBLIC_)?MUSHI_PROJECT_ID=/.test(envContent);
+    if (!hasEnvVars) {
+      return {
+        nextAction: "Write env vars to your app: run `npx mushi-mushi` or `mushi connect --write-env`",
+        ctaPath: "/onboarding?tab=sdk",
+        done: false
+      };
+    }
+  } catch {
   }
-  if (opts.dryRun) {
-    return { plan, upgraded: false, message: `[dry-run] Would run: ${plan.installCmd}` };
+  try {
+    const sdkCheck = await checkSdkInstall(cwd);
+    if (sdkCheck && !sdkCheck.ok) {
+      return {
+        nextAction: `Install the Mushi SDK: ${sdkCheck.detail}`,
+        ctaPath: "/onboarding?tab=sdk",
+        done: false
+      };
+    }
+  } catch {
   }
   try {
-    execSync(plan.installCmd, { cwd: plan.cwd, stdio: "inherit", env: process.env });
+    const data = await fetchIngestSetup(
+      { endpoint: config.endpoint, apiKey: config.apiKey, projectId: config.projectId },
+      doFetch
+    );
+    if (data) {
+      const steps = data.steps ?? [];
+      const incomplete = steps.find((s) => s.required && !s.complete);
+      if (incomplete) {
+        const tabMap = {
+          project_created: "/onboarding?tab=steps&setup=cli",
+          api_key_generated: "/onboarding?tab=verify",
+          sdk_installed: "/onboarding?tab=sdk",
+          first_report_received: "/onboarding?tab=verify"
+        };
+        const tab = tabMap[incomplete.id] ?? "/onboarding?tab=verify";
+        return {
+          nextAction: incomplete.hint ?? `Complete setup step: ${incomplete.label}`,
+          ctaPath: tab,
+          done: false
+        };
+      }
+      return {
+        nextAction: "All 4 required setup steps are complete! Open the console to explore.",
+        ctaPath: "/reports",
+        done: true
+      };
+    }
   } catch {
-    return {
-      plan,
-      upgraded: false,
-      message: `Install command failed \u2014 fix the error above or run it manually:
-  ${plan.installCmd}`
-    };
   }
-  const reactEntry = plan.entries.find((e) => e.migrateToWeb);
-  const migrateNote = reactEntry ? "\nNote: @mushi-mushi/react is legacy \u2014 prefer @mushi-mushi/web for Vite/Capacitor/SPA apps." : "";
   return {
-    plan,
-    upgraded: true,
-    message: `Upgraded Mushi SDK packages.
-  ${plan.installCmd}${migrateNote}`
+    nextAction: "Open the onboarding wizard in the console to check your setup status.",
+    ctaPath: "/onboarding",
+    done: false
   };
 }
-
-// src/commands/fix.ts
-function registerFixCommands(program2) {
-  const fixCmd = program2.command("fix").description("Dispatch an agentic fix for a report");
-  fixCmd.argument("<reportId>", "Report UUID to fix").option(
-    "--agent <name>",
-    "Agent adapter: claude_code (default), cursor_cloud, codex, mcp",
-    "claude_code"
-  ).option(
-    "--model <slug>",
-    "Model override for cursor_cloud (e.g. composer-latest)"
-  ).option(
-    "--no-auto-pr",
-    "For cursor_cloud: skip automatic PR creation (branch only)"
-  ).option(
-    "--wait",
-    "Poll until terminal state and exit non-zero on error/cancelled (CI-friendly)"
-  ).option("-e, --endpoint <url>", "API endpoint (overrides MUSHI_API_ENDPOINT)").option("--api-key <key>", "API key (overrides MUSHI_API_KEY)").option("--project-id <id>", "Project ID (overrides MUSHI_PROJECT_ID)").addHelpText("after", `
-Examples:
-  mushi fix abc123 --agent cursor_cloud --wait
-  mushi fix abc123 --agent cursor_cloud --model composer-latest --no-auto-pr
-  mushi fix abc123 --agent claude_code
-
-  # CI: fail the pipeline if the fix errors
-  mushi fix $REPORT_ID --agent cursor_cloud --wait && echo "Fix PR opened"`).action(async (reportId, opts) => {
-    const cfg = loadConfig();
-    if (opts.endpoint) cfg.endpoint = opts.endpoint;
-    if (opts.apiKey) cfg.apiKey = opts.apiKey;
-    if (opts.projectId) cfg.projectId = opts.projectId;
-    const isTTY = process.stdout.isTTY;
-    const emitEvent = (type, data) => {
-      if (isTTY) {
-        const ts = (/* @__PURE__ */ new Date()).toISOString();
-        console.log(`[${ts}] ${type}`, JSON.stringify(data));
-      } else {
-        process.stdout.write(JSON.stringify({ type, ...data }) + "\n");
-      }
-    };
-    emitEvent("dispatch.start", { reportId, agent: opts.agent, model: opts.model ?? null });
-    const body = {
-      reportId,
-      projectId: cfg.projectId,
-      agent: opts.agent
-    };
-    if (opts.agent === "cursor_cloud") {
-      if (opts.model) body.cursorModel = opts.model;
-      if (!opts.autoPr) body.cursorAutoCreatePR = false;
-    }
-    const result = await apiCall("/v1/admin/fixes/dispatch", cfg, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify(body)
-    });
-    if (!result.ok) {
-      console.error("Error dispatching fix:", result.error.message);
-      process.exit(1);
-    }
-    const { fixId, status, agentId, runId, prUrl } = result.data;
-    emitEvent("dispatch.ok", { fixId, status, agentId, runId, prUrl });
-    if (!opts.wait) {
-      process.exit(0);
-    }
-    if (!fixId) {
-      console.error("No fixId returned \u2014 cannot poll.");
-      process.exit(1);
-    }
-    const POLL_MS = 5e3;
-    const MAX_POLLS = 120;
-    const TERMINAL = /* @__PURE__ */ new Set(["completed", "failed", "error", "cancelled", "skipped", "skipped_unsupported_agent", "skipped_no_sandbox"]);
-    for (let i = 0; i < MAX_POLLS; i++) {
-      await new Promise((r) => setTimeout(r, POLL_MS));
-      const pollResult = await apiCall(
-        `/v1/admin/fixes/${fixId}`,
-        cfg
-      );
-      if (!pollResult.ok) {
-        emitEvent("poll.error", { error: pollResult.error.message });
-        continue;
-      }
-      const s = pollResult.data.status;
-      emitEvent("fix.status", { status: s, pr_url: pollResult.data.pr_url, cursor_agent_id: pollResult.data.cursor_agent_id });
-      if (s && TERMINAL.has(s)) {
-        const success = s === "completed";
-        if (!success) {
-          console.error(`Fix ended with status: ${s}${pollResult.data.error ? ` \u2014 ${pollResult.data.error}` : ""}`);
-          process.exit(1);
-        }
-        process.exit(0);
-      }
-    }
-    console.error("Polling timed out after 10 minutes. The fix may still be running.");
-    process.exit(1);
-  });
-  program2.command("nudge").description(
-    "Generate a Mushi.init() snippet tuned for your release phase (alpha, beta, ga). Customises proactive triggers, cooldowns, feature-request card, and beta-mode UI."
-  ).option("--phase <phase>", "Release phase: alpha | beta | ga", "beta").option("--explain", "Print a human-readable summary of what the preset does").option("--max <n>", "Override maxProactivePerSession").option("--cooldown <hours>", "Override dismissCooldownHours").option("--dwell <minutes>", "Override page-dwell threshold (0 disables)").option("--welcome <seconds>", "Override first-session welcome delay (0 disables)").action((opts) => {
-    const validPhases = ["alpha", "beta", "ga"];
-    if (!validPhases.includes(opts.phase)) {
-      console.error(`Unknown phase "${opts.phase}". Use one of: ${validPhases.join(", ")}`);
-      process.exit(1);
-    }
-    const phase = opts.phase;
-    const overrides = {};
-    const parseNumericFlag = (flag, raw, min) => {
-      const n = Number(raw);
-      if (!Number.isFinite(n) || n < min) {
-        console.error(
-          `error: --${flag} must be a finite number >= ${min} (got "${raw}")`
-        );
-        process.exit(1);
-      }
-      return n;
-    };
-    if (opts.max !== void 0) overrides.maxProactivePerSession = parseNumericFlag("max", opts.max, 1);
-    if (opts.cooldown !== void 0) overrides.dismissCooldownHours = parseNumericFlag("cooldown", opts.cooldown, 0);
-    if (opts.dwell !== void 0) overrides.pageDwellMinutes = parseNumericFlag("dwell", opts.dwell, 0);
-    if (opts.welcome !== void 0) overrides.firstSessionSeconds = parseNumericFlag("welcome", opts.welcome, 0);
-    if (opts.explain) {
-      console.log(renderNudgeExplainer(phase));
-    }
-    console.log(renderNudgeSnippet({ phase, overrides }));
-  });
-  program2.command("upgrade").description("Bump installed @mushi-mushi/* packages to the latest stable npm release").option("--cwd <path>", "Target repo (default: cwd)").option("--dry-run", "Print the install command without running it").option("--json", "Machine-readable plan + result").addHelpText("after", `
-Examples:
-  mushi upgrade
-  mushi upgrade --dry-run
-  mushi upgrade --cwd ../glot.it`).action(async (opts) => {
-    const result = await runUpgrade({ cwd: opts.cwd, dryRun: opts.dryRun, json: opts.json });
-    if (opts.json) {
-      console.log(JSON.stringify(result, null, 2));
-    } else {
-      console.log(result.message);
-      for (const e of result.plan.entries) {
-        const tag = e.willUpgrade && e.latest ? `\u2192 v${e.latest}` : "(current)";
-        console.log(`  ${e.name}@${e.current} ${tag}`);
-      }
-    }
-    if (!result.upgraded && result.plan.entries.some((e) => e.willUpgrade) && !opts.dryRun) {
-      process.exit(1);
+async function runDoctor(config, options = {}) {
+  const doFetch = options.fetch ?? globalThis.fetch;
+  const checks = [];
+  const isFull = options.full === true;
+  const runServer = isFull || options.server !== false;
+  const runIngest = isFull || options.ingest !== false;
+  checks.push(...checkCliConfig(config));
+  if (config.endpoint) {
+    checks.push(await checkEndpointReachability(config.endpoint, doFetch));
+  }
+  const sdkCheck = await checkSdkInstall(options.cwd ?? process.cwd());
+  if (sdkCheck) checks.push(sdkCheck);
+  if (runServer) {
+    const serverChecks = await checkServerPreflight(config, doFetch);
+    checks.push(...serverChecks);
+  }
+  if (runIngest) {
+    const ingestChecks = await checkIngestSetup(config, doFetch);
+    checks.push(...ingestChecks);
+  }
+  if (isFull || options.qaStories) {
+    const qaChecks = await checkQaStoriesHealth(config, doFetch);
+    checks.push(...qaChecks);
+  }
+  if (isFull || options.hostApp) {
+    const hostChecks = await checkHostAppWiring(options.cwd ?? process.cwd());
+    checks.push(...hostChecks);
+  }
+  if (isFull || options.mcp) {
+    const mcpChecks = await checkMcpConfig(config, options.cwd ?? process.cwd(), doFetch);
+    checks.push(...mcpChecks);
+  }
+  const heartbeatPassed = checks.some((c) => c.name === "[ingest] Last SDK heartbeat" && c.ok);
+  if (heartbeatPassed) {
+    const idx = checks.findIndex((c) => c.name === "SDK installed in this repo" && !c.ok);
+    if (idx >= 0) {
+      checks[idx] = {
+        ...checks[idx],
+        ok: true,
+        warn: true,
+        detail: "No @mushi-mushi/* found in cwd package.json \u2014 but live heartbeats confirm the SDK is active. Run from your app repo or install with `mushi init`."
+      };
     }
-    if (result.plan.entries.length === 0) process.exit(1);
-  });
-  program2.command("connect").description("Save credentials, merge env vars, wire Cursor MCP, optionally wait for SDK heartbeat").option("--api-key <key>", "Mushi API key (mushi_\u2026) \u2014 or set MUSHI_API_KEY to keep it out of shell history").requiredOption("--project-id <id>", "Project UUID").requiredOption("--endpoint <url>", "Supabase edge function URL").option("--cwd <path>", "Target repo").option("--write-env", "Force-write SDK env vars to .env.local (default; overrides --no-env)").option("--wire-ide", "Force-wire Cursor MCP into .cursor/mcp.json (default; overrides --no-ide)").option("--no-env", "Skip writing .env.local").option("--no-ide", "Skip writing .cursor/mcp.json").option("--wait", "Poll ingest-setup until SDK heartbeat lands").option("--wait-timeout <sec>", "Max seconds for --wait", "120").option("--json", "Machine-readable output").addHelpText("after", `
-Examples:
-  MUSHI_API_KEY=mushi_xxx mushi connect --project-id <uuid> --endpoint https://<ref>.supabase.co/functions/v1/api --wait
-  mushi connect --api-key mushi_xxx --project-id <uuid> --endpoint <url> --no-ide`).action(async (opts) => {
-    const apiKey = process.env.MUSHI_API_KEY ?? opts.apiKey;
-    if (!apiKey) {
-      console.error("Provide the API key via the MUSHI_API_KEY env var (recommended) or --api-key <key>.");
-      process.exit(1);
+  }
+  return { checks, ready: checks.every((c) => c.ok) };
+}
+function formatDoctorResult(result) {
+  const PASS = "OK";
+  const WARN = "WARN";
+  const FAIL = "FAIL";
+  const lines = [];
+  for (const c of result.checks) {
+    const icon = !c.ok ? FAIL : c.warn ? WARN : PASS;
+    lines.push(`${icon} ${c.name}`);
+    if (c.detail) lines.push(`  ${c.detail}`);
+    if (!c.ok) {
+      const hint = fixHintForCheck(c.name);
+      if (hint) lines.push(`  \u2192 Fix: ${hint}`);
     }
-    const result = await runConnect({
-      apiKey,
-      projectId: opts.projectId,
-      endpoint: opts.endpoint,
-      cwd: opts.cwd,
-      // Explicit --write-env / --wire-ide force the action on even if --no-env /
-      // --no-ide was also passed; otherwise writing is the default.
-      writeEnv: opts.writeEnv === true ? true : opts.env !== false,
-      wireIde: opts.wireIde === true ? true : opts.ide !== false,
-      wait: opts.wait,
-      waitTimeoutSec: parseInt(opts.waitTimeout, 10) || 120,
-      json: opts.json
-    });
-    if (opts.json) {
-      console.log(JSON.stringify(result, null, 2));
+  }
+  const failed = result.checks.filter((c) => !c.ok);
+  const warned = result.checks.filter((c) => c.ok && c.warn);
+  if (failed.length === 0) {
+    if (warned.length > 0) {
+      lines.push(`
+All checks passed with ${warned.length} advisory warning${warned.length === 1 ? "" : "s"}. The CLI is ready.`);
     } else {
-      for (const line of result.messages) console.log(line);
+      lines.push("\nAll checks passed. The CLI is ready.");
     }
-    if (!result.ok) process.exit(1);
-  });
+  } else {
+    lines.push(`
+${failed.length} check${failed.length === 1 ? "" : "s"} failed.`);
+    lines.push("Fix the items above and re-run `mushi doctor`.");
+  }
+  return lines.join("\n");
+}
+
+// src/commands/doctor-cli.ts
+function registerDoctorCommand(program2) {
   program2.command("doctor").description(
     "Run pre-flight checks: CLI config, endpoint reachability, SDK install, ingest readiness (API key \u2192 heartbeat \u2192 first report), and dispatch readiness (GitHub, index, BYOK, autofix). Ingest + server checks run by default; pass --no-server or --no-ingest to skip."
   ).option("--cwd <path>", "Run package detection from a different directory").option("--json", "Machine-readable output").option("--no-server", "Skip dispatch-readiness /preflight checks").option("--no-ingest", "Skip ingest-setup checks (SDK heartbeat, first report)").option(
@@ -3555,9 +4039,38 @@ Examples:
   ).option(
     "--fix",
     "Apply safe local fixes when checks fail: write missing .env.local lines and wire Cursor MCP config."
+  ).option(
+    "--onboarding",
+    "Focused onboarding check: prints the single next action you need to take to finish SDK setup, with a console deep link."
+  ).option(
+    "--full",
+    "Run ALL check categories (server, ingest, host-app, mcp, qa-stories) in one shot. Good for first-run diagnostics. Exit 0 only when all checks pass."
   ).action(async (opts) => {
     const config = loadConfig();
-    const doctorOpts = { cwd: opts.cwd, server: opts.server, ingest: opts.ingest, qaStories: opts.qaStories, hostApp: opts.hostApp, mcp: opts.mcp };
+    if (opts.onboarding) {
+      const cwd = opts.cwd ?? process.cwd();
+      const consoleBase = await resolveConsoleUrl({ cwd });
+      const status = await checkOnboardingStatus(config, consoleBase, cwd);
+      const base = consoleBase.replace(/\/$/, "");
+      if (status.done) {
+        console.log(`OK  Setup complete. ${status.nextAction}`);
+        console.log(`    ${base}${status.ctaPath}`);
+      } else {
+        console.log(`\u2192 Next: ${status.nextAction}`);
+        console.log(`    Open: ${base}${status.ctaPath}`);
+      }
+      if (!status.done) process.exit(1);
+      return;
+    }
+    const doctorOpts = {
+      cwd: opts.cwd,
+      server: opts.server,
+      ingest: opts.ingest,
+      qaStories: opts.qaStories,
+      hostApp: opts.hostApp,
+      mcp: opts.mcp,
+      full: opts.full
+    };
     let result = await runDoctor(config, doctorOpts);
     if (!result.ready && opts.fix && config.apiKey && config.projectId && config.endpoint) {
       const connectResult = await runConnect({
@@ -3580,6 +4093,10 @@ Examples:
     console.log(formatDoctorResult(result));
     if (!result.ready) process.exit(1);
   });
+}
+
+// src/commands/reset-cli.ts
+function registerResetCommand(program2) {
   program2.command("reset [projectId]").description(
     "Archive a project and wipe its test data (codebase_files, fix_attempts, reports). Speeds up re-running the full onboarding flow from scratch. Requires `--confirm` to prevent accidents."
   ).option("--confirm", "Required safety flag \u2014 must pass to proceed").option("--json", "Machine-readable output").action(async (projectId, opts) => {
@@ -3614,146 +4131,6 @@ Re-run with --confirm to proceed.`
       process.exit(1);
     }
   });
-  const fixes = program2.command("fixes").description("Fix dispatch management");
-  fixes.command("tail").description(
-    "Stream SSE dispatch events for a report in real time. Useful for headless debugging without opening the browser."
-  ).requiredOption("--report-id <id>", "Report ID to follow").action(async (opts) => {
-    const config = loadConfig();
-    if (!config.apiKey) {
-      console.error("Run `mushi login` first");
-      process.exit(1);
-    }
-    if (!config.endpoint) {
-      console.error("No endpoint configured. Run `mushi init`");
-      process.exit(1);
-    }
-    const url = `${config.endpoint}/v1/admin/reports/${opts.reportId}/dispatch/stream`;
-    console.log(`Tailing dispatch stream for report ${opts.reportId}\u2026`);
-    console.log(`(Ctrl-C to stop)
-`);
-    const res = await fetch(url, {
-      headers: {
-        "Authorization": `Bearer ${config.apiKey}`,
-        "X-Mushi-Api-Key": config.apiKey,
-        "X-Mushi-Project": config.projectId ?? "",
-        "Accept": "text/event-stream"
-      }
-    });
-    if (!res.ok || !res.body) {
-      console.error(`Failed to connect: HTTP ${res.status}`);
-      const text2 = await res.text().catch(() => "");
-      if (text2) console.error(text2.slice(0, 300));
-      process.exit(1);
-    }
-    const decoder = new TextDecoder();
-    const reader = res.body.getReader();
-    let done = false;
-    process.on("SIGINT", () => {
-      done = true;
-      void reader.cancel();
-      console.log("\nDisconnected.");
-      process.exit(0);
-    });
-    while (!done) {
-      const { value, done: streamDone } = await reader.read();
-      if (streamDone) break;
-      const chunk = decoder.decode(value, { stream: true });
-      for (const line of chunk.split("\n")) {
-        if (line.startsWith("data: ")) {
-          const raw = line.slice(6).trim();
-          if (raw === "[DONE]") {
-            console.log("\n[stream ended]");
-            process.exit(0);
-          }
-          try {
-            const event = JSON.parse(raw);
-            const ts = (/* @__PURE__ */ new Date()).toISOString();
-            const type = event.type ?? event.event ?? "event";
-            const status = event.status ?? event.data ?? "";
-            console.log(`${ts}  ${type.padEnd(24)}  ${status}`);
-          } catch {
-            console.log(line);
-          }
-        } else if (line.startsWith("event: ")) {
-        } else if (line && !line.startsWith(":")) {
-          console.log(line);
-        }
-      }
-    }
-  });
-  fixes.command("merge <fixId>").description(
-    "Squash-merge the fix PR on GitHub and mark the report Fixed (same as console merge)"
-  ).option(
-    "--method <method>",
-    "GitHub merge method: squash (default), merge, or rebase",
-    "squash"
-  ).option("--json", "Machine-readable JSON output").action(async (fixId, opts) => {
-    const config = loadConfig();
-    if (!config.apiKey) {
-      console.error("Run `mushi login` first");
-      process.exit(1);
-    }
-    if (!config.endpoint) {
-      console.error("No endpoint configured. Run `mushi init`");
-      process.exit(1);
-    }
-    const method = opts.method;
-    if (!["squash", "merge", "rebase"].includes(method)) {
-      console.error("--method must be squash, merge, or rebase");
-      process.exit(1);
-    }
-    const result = await apiCall(`/v1/admin/fixes/${fixId}/merge`, config, {
-      method: "POST",
-      body: JSON.stringify({ mergeMethod: method })
-    });
-    if (!result.ok) {
-      if (opts.json) {
-        console.log(JSON.stringify({ ok: false, error: result.error }, null, 2));
-      } else {
-        console.error("Merge failed:", result.error.message);
-      }
-      process.exit(1);
-    }
-    const data = result.data ?? {};
-    if (opts.json) {
-      console.log(JSON.stringify({ ok: true, ...data }, null, 2));
-      return;
-    }
-    if (data.alreadyMerged) {
-      console.log(`PR was already merged. Report status: ${data.reportStatus ?? "unknown"}`);
-    } else {
-      console.log(`Merged successfully. Report status: ${data.reportStatus ?? "fixed"}`);
-    }
-  });
-  fixes.command("refresh-ci <fixId>").description("Pull latest GitHub Actions check-run status for a fix attempt (on-demand ci-sync)").option("--json", "Machine-readable JSON output").action(async (fixId, opts) => {
-    const config = loadConfig();
-    if (!config.apiKey) {
-      console.error("Run `mushi login` first");
-      process.exit(1);
-    }
-    if (!config.endpoint) {
-      console.error("No endpoint configured. Run `mushi init`");
-      process.exit(1);
-    }
-    const result = await apiCall(`/v1/admin/fixes/${fixId}/refresh-ci`, config, { method: "POST" });
-    if (!result.ok) {
-      if (opts.json) {
-        console.log(JSON.stringify({ ok: false, error: result.error }, null, 2));
-      } else {
-        console.error("CI refresh failed:", result.error.message);
-      }
-      process.exit(1);
-    }
-    const data = result.data ?? {};
-    if (opts.json) {
-      console.log(JSON.stringify({ ok: true, ...data }, null, 2));
-      return;
-    }
-    const status = data.check_run_status ?? "unknown";
-    const conclusion = data.check_run_conclusion ?? "\u2014";
-    const updated = data.check_run_updated_at ? new Date(data.check_run_updated_at).toISOString() : "\u2014";
-    console.log(`CI status: ${status} \xB7 conclusion: ${conclusion} \xB7 updated: ${updated}`);
-  });
 }
 
 // src/commands/tdd.ts
@@ -4010,7 +4387,7 @@ function registerIntegrationsCommands(program2) {
     console.log("\nIntegrations:\n");
     for (const row of rows) {
       const icon = icons[row.kind] ?? "\u{1F50C}";
-      const statusIcon = row.status === "ok" ? "\u2705" : row.status === "error" ? "\u274C" : "\u26AA";
+      const statusIcon = row.status === "ok" ? "OK" : row.status === "error" ? "FAIL" : "SKIP";
       console.log(`  ${icon}  ${row.kind.padEnd(20)} ${statusIcon}  ${row.detail ?? ""}`);
     }
     console.log();
@@ -4042,7 +4419,7 @@ function registerIntegrationsCommands(program2) {
     }
     const probeOk = result.data?.status === "ok";
     console.log(
-      probeOk ? `\u2705  ${kind} integration is healthy${result.data.detail ? ": " + result.data.detail : ""}` : `\u274C  ${kind} integration check failed${result.data.detail ? ": " + result.data.detail : ""}`
+      probeOk ? `OK   ${kind} integration is healthy${result.data.detail ? ": " + result.data.detail : ""}` : `FAIL ${kind} integration check failed${result.data.detail ? ": " + result.data.detail : ""}`
     );
     if (!probeOk) process.exit(1);
   });
@@ -4071,11 +4448,11 @@ function registerIntegrationsCommands(program2) {
       return;
     }
     if (result.data?.status === "ok") {
-      console.log("\u2705  Slack connected");
+      console.log("OK   Slack connected");
       if (result.data.detail) console.log(`    ${result.data.detail}`);
       console.log("\n    To change the channel or notification prefs, visit /integrations in the Mushi console.");
     } else {
-      console.log("\u26AA  Slack not connected");
+      console.log("SKIP Slack not connected");
       console.log('    Visit /integrations in the Mushi console and click "Add to Slack".');
     }
   });
@@ -4103,9 +4480,9 @@ function registerIntegrationsCommands(program2) {
       return;
     }
     if (result.data?.ok) {
-      console.log("\u2705  Test message sent! Check your Slack channel.");
+      console.log("OK   Test message sent. Check your Slack channel.");
     } else {
-      console.error("\u274C  Test failed:", result.data?.error ?? "unknown error");
+      console.error("FAIL Test failed:", result.data?.error ?? "unknown error");
       process.exit(1);
     }
   });
@@ -4145,7 +4522,7 @@ function registerQaCommands(program2) {
 QA Stories (${stories.length}):
 `);
     for (const s of stories) {
-      const statusIcon = s.last_run_status === "passed" ? "\u2705" : s.last_run_status === "failed" ? "\u274C" : s.last_run_status === "error" ? "\u{1F6A8}" : "\u26AA";
+      const statusIcon = s.last_run_status === "passed" ? "PASS" : s.last_run_status === "failed" ? "FAIL" : s.last_run_status === "error" ? "ERROR" : "SKIP";
       const enabled = s.enabled ? "" : " [disabled]";
       const sid = s.story_id ?? s.id ?? "\u2014";
       console.log(`  ${statusIcon}  ${s.name.slice(0, 50).padEnd(52)}  ${sid}${enabled}`);
@@ -4186,7 +4563,7 @@ QA Stories (${stories.length}):
 Recent runs for story ${storyId.slice(0, 8)}\u2026:
 `);
     for (const r of runs) {
-      const statusIcon = r.status === "passed" ? "\u2705" : r.status === "failed" ? "\u274C" : r.status === "error" ? "\u{1F6A8}" : "\u23F3";
+      const statusIcon = r.status === "passed" ? "PASS" : r.status === "failed" ? "FAIL" : r.status === "error" ? "ERROR" : "PEND";
       const ts = r.created_at ? new Date(r.created_at).toISOString().slice(0, 16).replace("T", " ") : "\u2014";
       const latency = r.latency_ms ? ` (${(r.latency_ms / 1e3).toFixed(1)}s)` : "";
       console.log(`  ${statusIcon}  ${ts}${latency}  ${r.id.slice(0, 8)}`);
@@ -4199,7 +4576,7 @@ Recent runs for story ${storyId.slice(0, 8)}\u2026:
         }
       }
     }
-    const consoleUrl2 = config.consoleUrl ?? "https://app.mushi.ai";
+    const consoleUrl2 = config.consoleUrl ?? resolveConsoleUrlSync();
     console.log(`
    Open in console: ${consoleUrl2}/qa-coverage?story=${storyId}`);
     console.log(`   Tip: run 'mushi config consoleUrl <url>' to override (e.g. http://localhost:6464 for local dev)`);
@@ -4230,10 +4607,10 @@ Recent runs for story ${storyId.slice(0, 8)}\u2026:
     }
     const runId = result.data?.run_id;
     if (runId) {
-      console.log(`\u25B6  Run triggered: ${runId.slice(0, 8)}\u2026`);
-      console.log(`   Check results: mushi qa runs ${storyId}`);
+      console.log(`RUN  Triggered: ${runId.slice(0, 8)}\u2026`);
+      console.log(`     Check results: mushi qa runs ${storyId}`);
     } else {
-      console.error("\u274C  Trigger failed: no run_id in response", JSON.stringify(result.data));
+      console.error("FAIL Trigger failed: no run_id in response", JSON.stringify(result.data));
       process.exit(1);
     }
   });
@@ -4250,10 +4627,10 @@ Description:
     \u2022 Gate results: API contract (G3), spec drift (G6), orphan endpoints (G7),
       unknown frontend calls (G8), schema drift, status claim (G5)
 
-  Returns a PM-readable scorecard with severity-ranked findings.
+  Returns a human-readable summary with severity-ranked findings.
 
   Prerequisites:
-    1. Configure your Supabase PAT: mushi settings set supabase-pat <token>
+    1. Add your Supabase PAT in Admin \u2192 Settings \u2192 API Keys
     2. Set supabase_project_ref in Admin \u2192 Settings \u2192 Project.
 
 Examples:
@@ -4313,8 +4690,8 @@ Examples:
         return;
       }
       const data = body.data;
-      const overallGlyph = data.summary.overall === "fail" ? "\u274C" : data.summary.overall === "warn" ? "\u26A0\uFE0F " : "\u2705";
-      process.stdout.write(`${overallGlyph}
+      const overallLabel = data.summary.overall === "fail" ? "FAIL" : data.summary.overall === "warn" ? "WARN" : "OK";
+      process.stdout.write(`${overallLabel}
 
 `);
       console.log(`Full-Stack Audit \u2014 ${new Date(data.audit_at).toLocaleString()}`);
@@ -4322,18 +4699,18 @@ Examples:
       console.log(`Summary: ${data.summary.error_count} error(s) \xB7 ${data.summary.warn_count} warning(s)
 `);
       if (data.findings.length === 0) {
-        console.log("  \u2713 No findings. Your project looks healthy.");
+        console.log("  OK  No findings. Your project looks healthy.");
       } else {
         for (const f of data.findings) {
-          const icon = f.severity === "error" ? "\u{1F534}" : f.severity === "warn" ? "\u{1F7E1}" : "\u2139\uFE0F ";
-          console.log(`  ${icon} ${f.title}`);
+          const icon = f.severity === "error" ? "FAIL" : f.severity === "warn" ? "WARN" : "INFO";
+          console.log(`  ${icon}  ${f.title}`);
           console.log(`     ${f.detail.slice(0, 120)}${f.detail.length > 120 ? "\u2026" : ""}`);
         }
       }
       if (data.gate_runs.length > 0) {
         console.log("\nGate Results:");
         for (const run of data.gate_runs) {
-          const g = run.status === "pass" ? "\u2713" : run.status === "fail" ? "\u2717" : "~";
+          const g = run.status === "pass" ? "OK" : run.status === "fail" ? "FAIL" : "SKIP";
           console.log(`  ${g} ${run.gate.padEnd(22)} ${run.status}  (${run.findings_count} finding${run.findings_count !== 1 ? "s" : ""})`);
         }
       }
@@ -4641,9 +5018,100 @@ ${"\u2500".repeat(60)}`);
   });
 }
 
+// src/commands/billing.ts
+function registerBillingCommands(program2) {
+  program2.command("usage").description("Show diagnoses used / limit / cap for the current billing period").option("--json", "Machine-readable JSON output").addHelpText("after", `
+Examples:
+  mushi usage
+  mushi usage --json`).action(async (opts) => {
+    const config = requireConfig();
+    const result = await apiCall("/v1/admin/billing/stats", config);
+    if (!result.ok) die(result);
+    const s = result.data;
+    if (opts.json) {
+      console.log(JSON.stringify(s, null, 2));
+      return;
+    }
+    const limitStr = s.diagnosesLimit != null ? String(s.diagnosesLimit) : "unlimited";
+    const pctStr = s.diagnosesUsagePct != null ? `${Math.round(s.diagnosesUsagePct)}%` : "\u2014";
+    const capStr = s.monthlySpendCapUsd != null ? `$${s.monthlySpendCapUsd}/mo` : "none";
+    const badge = s.overDiagnosisQuota ? " \u26A0 OVER LIMIT" : s.approachingDiagnosisQuota ? " \u26A0 approaching limit" : "";
+    console.log(`
+Diagnoses this period: ${s.diagnosesUsed} / ${limitStr} (${pctStr})${badge}`);
+    console.log(`Plan: ${s.planId ?? "\u2014"}`);
+    console.log(`Spend cap: ${capStr}`);
+    console.log(`Period ends: ${s.periodEnd ? s.periodEnd.slice(0, 10) : "?"}`);
+    if (s.overDiagnosisQuota) {
+      console.log("\n  Diagnoses paused \u2014 upgrade at https://kensaur.us/mushi-mushi/admin/billing");
+    } else if (s.approachingDiagnosisQuota) {
+      console.log("\n  You're at 80%+ of your included diagnoses. Consider upgrading.");
+    }
+  });
+  const billing = program2.command("billing").description("Show billing summary and manage spend cap");
+  billing.command("status").description("Show full billing summary (plan, usage, cap)").option("--json", "Machine-readable JSON output").addHelpText("after", `
+Examples:
+  mushi billing status
+  mushi billing status --json`).action(async (opts) => {
+    const config = requireConfig();
+    const result = await apiCall("/v1/admin/billing", config);
+    if (!result.ok) die(result);
+    const s = result.data;
+    if (opts.json) {
+      console.log(JSON.stringify(s, null, 2));
+      return;
+    }
+    const limitStr = s.diagnosesLimit != null ? String(s.diagnosesLimit) : "unlimited";
+    const pctStr = s.diagnosesUsagePct != null ? `${Math.round(s.diagnosesUsagePct)}%` : "\u2014";
+    const capStr = s.monthlySpendCapUsd != null ? `$${s.monthlySpendCapUsd}/mo` : "none";
+    const overageStr = s.overageRateDiagnoses != null ? `$${s.overageRateDiagnoses}/diagnosis` : "N/A";
+    console.log(`
+Plan:        ${s.planId ?? "\u2014"}`);
+    console.log(`Status:      ${s.subscriptionStatus ?? "free"}${s.cancelAtPeriodEnd ? " (cancels at period end)" : ""}`);
+    console.log(`Diagnoses:   ${s.diagnosesUsed} / ${limitStr} (${pctStr})`);
+    console.log(`Overage:     ${overageStr}`);
+    console.log(`Spend cap:   ${capStr}`);
+    console.log(`Renews:      ${s.periodEnd ? s.periodEnd.slice(0, 10) : "?"}`);
+  });
+  billing.command("cap [usd]").description("Set or clear the monthly spend cap (pass 0 to clear, omit to show current cap)").addHelpText("after", `
+Examples:
+  mushi billing cap           # show current cap
+  mushi billing cap 100       # set $100/mo hard cap
+  mushi billing cap 0         # clear cap`).action(async (usdArg) => {
+    const config = requireConfig();
+    if (usdArg === void 0) {
+      const result2 = await apiCall("/v1/admin/billing/stats", config);
+      if (!result2.ok) die(result2);
+      const cap2 = result2.data.monthlySpendCapUsd;
+      if (cap2 == null) {
+        console.log("No spend cap set. Pass a dollar amount to set one, e.g.: mushi billing cap 100");
+      } else {
+        console.log(`Current spend cap: $${cap2}/mo`);
+      }
+      return;
+    }
+    const capUsd = parseFloat(usdArg);
+    if (isNaN(capUsd) || capUsd < 0) {
+      console.error("Error: spend cap must be a non-negative number (or 0 to clear).");
+      process.exit(2);
+    }
+    const result = await apiCall("/v1/admin/billing/spend-cap", config, {
+      method: "PUT",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ project_id: config.projectId, spend_cap_usd: capUsd === 0 ? null : capUsd })
+    });
+    if (!result.ok) die(result);
+    const cap = result.data.spend_cap_usd;
+    if (cap == null) {
+      console.log("\u2713 Spend cap cleared \u2014 no hard monthly limit.");
+    } else {
+      console.log(`\u2713 Spend cap set to $${cap}/mo. Diagnoses will pause gracefully once reached.`);
+    }
+  });
+}
+
 // src/index.ts
 installSignalHandlers();
-var program = new Command().name("mushi").description("Mushi Mushi CLI \u2014 set up the SDK, manage bug reports, monitor pipeline").version(MUSHI_CLI_VERSION).addHelpText("after", `
+var program = new Command().name("mushi").description("Mushi CLI \u2014 set up the SDK, triage a report, fix from your editor").version(MUSHI_CLI_VERSION).addHelpText("after", `
 Environment variables:
   MUSHI_API_KEY        SDK ingest key (report:write scope \u2014 from Onboarding \u2192 Verify in the console)
   MUSHI_PROJECT_ID     Project UUID   (from the Projects page in the console)
@@ -4666,6 +5134,11 @@ registerLessonsCommands(program);
 registerDiagnosticsCommands(program);
 registerProjectCommands(program);
 registerSetupCommands(program);
+registerNudgeCommand(program);
+registerUpgradeCommand(program);
+registerConnectCommand(program);
+registerDoctorCommand(program);
+registerResetCommand(program);
 registerFixCommands(program);
 registerTddCommands(program);
 registerKeysCommands(program);
@@ -4673,6 +5146,7 @@ registerIntegrationsCommands(program);
 registerQaCommands(program);
 registerAuditCommands(program);
 registerSkillsCommands(program);
+registerBillingCommands(program);
 program.parseAsync().catch((err) => {
   console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
   process.exit(1);