@mushi-mushi/cli 0.20.0 → 0.21.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,
@@ -110,13 +110,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.21.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
@@ -292,13 +292,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,6 +327,11 @@ 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 = {}) {
@@ -424,8 +429,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 +662,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;
@@ -688,7 +744,7 @@ 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);
@@ -759,7 +815,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 +831,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 +840,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 +859,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 +879,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 +928,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 +1051,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 +1142,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 +1161,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 +1446,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 +1492,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 +1514,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 +1539,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 +1625,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.
@@ -2382,33 +2491,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 });
@@ -2495,7 +2595,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
@@ -2699,6 +2799,54 @@ The command reads credentials from ~/.config/mushi/config.json (run \`mushi logi
       }
     }
     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) {
@@ -2909,6 +3057,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 unlock admin checks."
+          }
+        ];
+      }
+    }
     const text2 = await res.text().catch(() => "");
     return [
       {
@@ -3111,7 +3276,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,10 +3363,20 @@ async function checkMcpConfig(config, cwd, doFetch = globalThis.fetch) {
           detail: `Key is valid; ${projectCount} accessible project${projectCount === 1 ? "" : "s"}`
         });
       } else {
+        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: `GET /v1/admin/mcp/account-overview \u2192 HTTP ${res.status}. Verify the API key is active.`
+          detail
         });
       }
     } catch (err) {
@@ -3221,11 +3406,96 @@ function fixHintForCheck(name) {
   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 {
+        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
+      };
+    }
+    return {
+      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
+    };
+  }
+  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 {
+  }
+  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 {
+    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 {
+    nextAction: "Open the onboarding wizard in the console to check your setup status.",
+    ctaPath: "/onboarding",
+    done: false
+  };
+}
 async function runDoctor(config, options = {}) {
   const doFetch = options.fetch ?? globalThis.fetch;
   const checks = [];
-  const runServer = options.server !== false;
-  const runIngest = options.ingest !== false;
+  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));
@@ -3240,26 +3510,40 @@ async function runDoctor(config, options = {}) {
     const ingestChecks = await checkIngestSetup(config, doFetch);
     checks.push(...ingestChecks);
   }
-  if (options.qaStories) {
+  if (isFull || options.qaStories) {
     const qaChecks = await checkQaStoriesHealth(config, doFetch);
     checks.push(...qaChecks);
   }
-  if (options.hostApp) {
+  if (isFull || options.hostApp) {
     const hostChecks = await checkHostAppWiring(options.cwd ?? process.cwd());
     checks.push(...hostChecks);
   }
-  if (options.mcp) {
+  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`."
+      };
+    }
+  }
   return { checks, ready: checks.every((c) => c.ok) };
 }
 function formatDoctorResult(result) {
   const PASS = "\u2713";
+  const WARN = "\u26A0";
   const FAIL = "\u2717";
   const lines = [];
   for (const c of result.checks) {
-    lines.push(`${c.ok ? PASS : FAIL} ${c.name}`);
+    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);
@@ -3267,8 +3551,14 @@ function formatDoctorResult(result) {
     }
   }
   const failed = result.checks.filter((c) => !c.ok);
+  const warned = result.checks.filter((c) => c.ok && c.warn);
   if (failed.length === 0) {
-    lines.push("\nAll checks passed. The CLI is ready.");
+    if (warned.length > 0) {
+      lines.push(`
+All checks passed with ${warned.length} advisory warning${warned.length === 1 ? "" : "s"}. The CLI is ready.`);
+    } else {
+      lines.push("\nAll checks passed. The CLI is ready.");
+    }
   } else {
     lines.push(`
 ${failed.length} check${failed.length === 1 ? "" : "s"} failed.`);
@@ -3555,9 +3845,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(`\u2713 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({
@@ -4641,6 +4960,97 @@ ${"\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", `
@@ -4673,6 +5083,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);