@mushi-mushi/cli 0.19.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.19.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
@@ -126,7 +126,10 @@ var HOSTED_CONSOLE_BASE = "https://kensaur.us/mushi-mushi/admin";
 var LOCAL_ADMIN_URL = "http://localhost:6464";
 var LOCAL_PROBE_MS = 800;
 function normalizeConsoleBase(url) {
-  return url.trim().replace(/\/+$/, "");
+  const trimmed = url.trim();
+  let end = trimmed.length;
+  while (end > 0 && trimmed.charCodeAt(end - 1) === 47) end--;
+  return trimmed.slice(0, end);
 }
 function consoleUrl(base, route) {
   const normalizedRoute = route.startsWith("/") ? route : `/${route}`;
@@ -201,10 +204,34 @@ function reportsUrl(base, reportId) {
   return reportId ? consoleUrl(base, `/reports/${reportId}`) : consoleUrl(base, "/reports");
 }
 async function openInBrowser(url) {
-  const { exec } = await import("child_process");
-  const openCmd = process.platform === "win32" ? `start "" "${url}"` : process.platform === "darwin" ? `open "${url}"` : `xdg-open "${url}"`;
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return;
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    return;
+  }
+  const safeUrl = parsed.toString();
+  const { spawn: spawn2 } = await import("child_process");
+  const [command, args] = process.platform === "win32" ? (
+    // Open via rundll32's FileProtocolHandler rather than `cmd /c start`.
+    // `start` is a cmd builtin, so the URL would be re-parsed by cmd.exe and
+    // characters like `&` / `|` / `^` could still break out — exactly the
+    // injection surface CodeQL flags. rundll32 never invokes a shell: the URL
+    // is handed to the default browser as one opaque argument.
+    ["rundll32", ["url.dll,FileProtocolHandler", safeUrl]]
+  ) : process.platform === "darwin" ? ["open", [safeUrl]] : ["xdg-open", [safeUrl]];
   await new Promise((resolve3) => {
-    exec(openCmd, () => resolve3());
+    try {
+      const child = spawn2(command, [...args], { stdio: "ignore", shell: false });
+      child.on("error", () => resolve3());
+      child.on("exit", () => resolve3());
+      child.unref();
+    } catch {
+      resolve3();
+    }
   });
 }
 
@@ -265,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;
@@ -300,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 = {}) {
@@ -329,6 +361,151 @@ function pad(s, width) {
   return s.length >= width ? s : s + " ".repeat(width - s.length);
 }
 
+// src/device-auth.ts
+var DEVICE_FETCH_TIMEOUT_MS = 15e3;
+function trimTrailingSlash(endpoint) {
+  let end = endpoint.length;
+  while (end > 0 && endpoint.charCodeAt(end - 1) === 47) end--;
+  return endpoint.slice(0, end);
+}
+async function deviceFetch(url, init = {}) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), DEVICE_FETCH_TIMEOUT_MS);
+  try {
+    return await fetch(url, { ...init, signal: controller.signal });
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function startDeviceAuth(endpoint) {
+  const base = trimTrailingSlash(endpoint);
+  const res = await deviceFetch(`${base}/v1/cli/auth/device/start`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" }
+  });
+  const json = await res.json().catch(() => null);
+  if (!res.ok || !json?.ok || !json.data) {
+    throw new Error(json?.error?.message ?? `Could not start browser sign-in (HTTP ${res.status}).`);
+  }
+  return json.data;
+}
+async function pollDeviceToken(endpoint, deviceCode) {
+  const base = trimTrailingSlash(endpoint);
+  try {
+    const res = await deviceFetch(`${base}/v1/cli/auth/device/token`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ device_code: deviceCode })
+    });
+    const json = await res.json().catch(() => ({}));
+    if (res.ok && json.ok && json.data?.cli_token) {
+      return { status: "approved", cliToken: json.data.cli_token, userId: json.data.user_id };
+    }
+    switch (json.error) {
+      case "authorization_pending":
+        return { status: "pending" };
+      case "access_denied":
+        return { status: "denied" };
+      case "expired_token":
+        return { status: "expired" };
+      default:
+        return {
+          status: "error",
+          message: json.error_description ?? json.error ?? `HTTP ${res.status}`,
+          // 5xx is a server hiccup the next poll may clear; a 4xx is a definitive
+          // rejection (already claimed / invalid_grant) that won't fix itself.
+          retryable: res.status >= 500
+        };
+    }
+  } catch (err) {
+    return { status: "error", message: err instanceof Error ? err.message : String(err), retryable: true };
+  }
+}
+var defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+async function waitForCliToken(endpoint, session, opts = {}) {
+  const sleep = opts.sleep ?? defaultSleep;
+  const now = opts.now ?? Date.now;
+  const intervalMs = (session.interval || 5) * 1e3;
+  const deadline = now() + (session.expires_in || 600) * 1e3;
+  const maxConsecutiveErrors = opts.maxConsecutiveErrors ?? 5;
+  let consecutiveErrors = 0;
+  let firstPoll = true;
+  while (now() < deadline) {
+    if (!firstPoll) {
+      await sleep(intervalMs);
+    }
+    firstPoll = false;
+    const outcome = await pollDeviceToken(endpoint, session.device_code);
+    switch (outcome.status) {
+      case "approved":
+        return outcome.cliToken;
+      case "pending":
+        consecutiveErrors = 0;
+        opts.onPending?.();
+        continue;
+      case "denied":
+        throw new Error("Login was denied in the browser.");
+      case "expired":
+        throw new Error("The login code expired. Run sign-in again.");
+      case "error":
+        if (!outcome.retryable) {
+          throw new Error(outcome.message);
+        }
+        consecutiveErrors += 1;
+        if (consecutiveErrors >= maxConsecutiveErrors) {
+          throw new Error(outcome.message);
+        }
+        opts.onTransientError?.(outcome.message, consecutiveErrors);
+        continue;
+    }
+  }
+  throw new Error("Login timed out before approval. Run sign-in again.");
+}
+function cliAuthHeaders(cliToken) {
+  return {
+    "Content-Type": "application/json",
+    Authorization: `Bearer ${cliToken}`
+  };
+}
+async function listProjects(endpoint, cliToken) {
+  const base = trimTrailingSlash(endpoint);
+  try {
+    const res = await deviceFetch(`${base}/v1/cli/projects`, { headers: cliAuthHeaders(cliToken) });
+    const json = await res.json().catch(() => null);
+    if (res.ok && json?.ok) return json.data?.projects ?? [];
+  } catch {
+  }
+  return [];
+}
+async function createProject(endpoint, cliToken, name) {
+  const base = trimTrailingSlash(endpoint);
+  const res = await deviceFetch(`${base}/v1/cli/projects`, {
+    method: "POST",
+    headers: cliAuthHeaders(cliToken),
+    body: JSON.stringify({ name })
+  });
+  const json = await res.json().catch(() => null);
+  if (!res.ok || !json?.ok || !json.data) {
+    throw new Error(json?.error?.message ?? `Could not create project (HTTP ${res.status}).`);
+  }
+  const { id, name: created, slug, apiKey } = json.data;
+  return { id, name: created, slug, apiKey: apiKey ?? null };
+}
+async function mintProjectKey(endpoint, cliToken, projectId) {
+  const base = trimTrailingSlash(endpoint);
+  try {
+    const res = await deviceFetch(`${base}/v1/cli/projects/${projectId}/keys`, {
+      method: "POST",
+      headers: cliAuthHeaders(cliToken),
+      body: JSON.stringify({})
+    });
+    const json = await res.json().catch(() => null);
+    if (res.ok && json?.ok) return json.data?.key ?? null;
+  } catch {
+  }
+  return null;
+}
+
 // src/freshness.ts
 var REGISTRY = "https://registry.npmjs.org";
 var DEFAULT_TIMEOUT_MS = 2e3;
@@ -485,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;
@@ -510,8 +734,8 @@ async function runInit(options = {}) {
   const detected = detectFramework(cwd, pkg);
   const framework = await chooseFramework(detected, options);
   const consoleBase = await resolveConsoleUrl({ cwd });
-  await maybeGuideConsoleSetup(options, consoleBase);
-  const credentials = await collectCredentials(options, consoleBase);
+  const endpoint = resolveCloudEndpoint(options.endpoint);
+  const credentials = await acquireCredentials(options, consoleBase, endpoint);
   await verifyCredentials(credentials, options, consoleBase);
   const pm = detectPackageManager(cwd);
   const packagesToInstall = framework.needsWebPackage ? [framework.packageName, "@mushi-mushi/web"] : [framework.packageName];
@@ -520,8 +744,7 @@ async function runInit(options = {}) {
   } else {
     p.log.info(`Skipped install. Run \`${installCommand(pm, packagesToInstall)}\` yourself.`);
   }
-  const endpoint = resolveCloudEndpoint(options.endpoint);
-  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);
@@ -567,63 +790,17 @@ async function chooseFramework(detected, options) {
   }
   return FRAMEWORKS[confirmed];
 }
-async function maybeGuideConsoleSetup(options, consoleBase) {
-  if (options.yes) return;
-  if (options.projectId && options.apiKey) return;
-  const existing = loadConfig();
-  if (existing.projectId && existing.apiKey) return;
-  const choice = await p.select({
-    message: "Do you already have a Mushi project?",
-    options: [
-      {
-        value: "create",
-        label: "No \u2014 open the console to create one",
-        hint: "Recommended for first-time setup"
-      },
-      {
-        value: "have",
-        label: "Yes \u2014 I have Project ID + API key",
-        hint: "Paste values from the admin console"
-      },
-      {
-        value: "login",
-        label: "Use mushi login first",
-        hint: "Run `mushi login` in another terminal, then re-run this wizard"
-      }
-    ]
-  });
-  if (p.isCancel(choice)) {
-    p.cancel("Aborted.");
-    process.exit(0);
-  }
-  if (choice === "login") {
-    p.log.info("Run `mushi login` to save credentials, then re-run `mushi init`.");
-    p.cancel("Aborted.");
-    process.exit(0);
-  }
-  if (choice !== "create") return;
-  const setupUrl = cliSetupDeepLink(consoleBase);
-  p.log.info(`Opening the Mushi console:
-  ${setupUrl}`);
-  await openInBrowser(setupUrl);
-  p.log.message("In the console:");
-  p.log.message("  1. Enter a project name and click Create");
-  p.log.message("  2. Copy the Project ID from the success panel");
-  p.log.message("  3. Generate an API key (Verify tab \u2014 report:write scope)");
-  p.log.message("  4. Return here and paste both values");
-  const ready = await p.confirm({
-    message: "Created your project and ready to paste credentials?",
-    initialValue: false
-  });
-  if (p.isCancel(ready) || !ready) {
-    p.log.warn(`Finish in the console first: ${setupUrl}`);
+async function acquireCredentials(options, consoleBase, endpoint) {
+  if (options.projectId && options.apiKey) {
+    return {
+      projectId: sanitizeSecret(options.projectId),
+      apiKey: sanitizeSecret(options.apiKey)
+    };
   }
-}
-async function collectCredentials(options, consoleBase) {
   const existing = loadConfig();
   if (!options.projectId && !options.apiKey && existing.projectId && existing.apiKey) {
     const reuse = options.yes ? true : await p.confirm({
-      message: "Use Project ID + API key from ~/.config/mushi/config.json?",
+      message: "Use the Mushi credentials saved from your last sign-in?",
       initialValue: true
     });
     if (p.isCancel(reuse)) {
@@ -637,6 +814,144 @@ async function collectCredentials(options, consoleBase) {
       };
     }
   }
+  if (options.yes) {
+    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 {
+    const method = await p.select({
+      message: "Connect this app to Mushi",
+      initialValue: "browser",
+      options: [
+        {
+          value: "browser",
+          label: "Sign in with your browser",
+          hint: "Recommended \u2014 no copy-paste, creates the project + key for you"
+        },
+        {
+          value: "manual",
+          label: "Paste a Project ID + API key",
+          hint: "Self-hosted or expert setup \u2014 run npx mushi-mushi (not mushi setup)"
+        }
+      ]
+    });
+    if (p.isCancel(method)) {
+      p.cancel("Aborted.");
+      process.exit(0);
+    }
+    if (method === "browser") {
+      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, consoleBase) {
+  const startSpin = p.spinner();
+  startSpin.start("Starting secure browser sign-in\u2026");
+  let session;
+  try {
+    session = await startDeviceAuth(endpoint);
+  } catch (err) {
+    startSpin.stop("Could not start browser sign-in.");
+    p.log.warn(err instanceof Error ? err.message : String(err));
+    return null;
+  }
+  startSpin.stop("Browser sign-in ready.");
+  try {
+    await openInBrowser(session.verification_uri);
+  } catch {
+  }
+  printAuthBanner(session.user_code, session.verification_uri);
+  const waitSpin = p.spinner();
+  waitSpin.start("Waiting for you to approve in the browser\u2026");
+  let cliToken;
+  try {
+    cliToken = await waitForCliToken(endpoint, session);
+  } catch (err) {
+    waitSpin.stop("Browser sign-in didn't complete.");
+    p.log.warn(err instanceof Error ? err.message : String(err));
+    return null;
+  }
+  waitSpin.stop("Approved.");
+  let projectId = options.projectId ? sanitizeSecret(options.projectId) : void 0;
+  let apiKey;
+  if (!projectId) {
+    let projects = [];
+    const fetchSpin = p.spinner();
+    fetchSpin.start("Loading your projects\u2026");
+    try {
+      projects = await listProjects(endpoint, cliToken);
+      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({
+      message: "Choose a project",
+      initialValue: projects[0]?.id ?? NEW,
+      options: [
+        ...projects.map((pr) => ({ value: pr.id, label: pr.name, hint: pr.id.slice(0, 8) })),
+        { value: NEW, label: "Create a new project", hint: "mints an SDK key automatically" }
+      ]
+    });
+    if (p.isCancel(choice)) {
+      p.cancel("Aborted.");
+      process.exit(0);
+    }
+    if (choice === NEW) {
+      const name = await p.text({
+        message: "Project name",
+        placeholder: "My app",
+        validate: (v) => v && v.trim().length > 0 ? void 0 : "Required"
+      });
+      if (p.isCancel(name)) {
+        p.cancel("Aborted.");
+        process.exit(0);
+      }
+      const createSpin = p.spinner();
+      createSpin.start(`Creating "${name.trim()}"\u2026`);
+      try {
+        const created = await createProject(endpoint, cliToken, name.trim());
+        projectId = created.id;
+        apiKey = created.apiKey ?? void 0;
+        createSpin.stop(`Created project "${created.name}".`);
+      } catch (err) {
+        createSpin.stop("Could not create the project.");
+        p.log.warn(err instanceof Error ? err.message : String(err));
+        return null;
+      }
+    } else {
+      projectId = choice;
+    }
+  }
+  if (projectId && !apiKey) {
+    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 };
+}
+async function collectCredentialsManually(options, consoleBase) {
+  const existing = loadConfig();
   const rawProjectId = options.projectId ?? existing.projectId ?? await promptText({
     message: "Project ID",
     placeholder: "e.g. bdafa28d-b153-482f-bd4f-42981f3fd3a4",
@@ -736,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" : "";
@@ -803,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) {
@@ -820,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,
@@ -1105,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();
@@ -1147,19 +1492,19 @@ 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 {
-      const res = await fetch(`${endpoint}/v1/cli/auth/device/start`, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" }
-      });
-      const json = await res.json();
-      if (!res.ok || !json.ok || !json.data) {
-        throw new Error(json.error?.message ?? `HTTP ${res.status}`);
-      }
-      deviceData = json.data;
+      deviceData = await startDeviceAuth(endpoint);
     } catch (err) {
       process.stderr.write(`
 error: Could not start login session: ${err instanceof Error ? err.message : String(err)}
@@ -1169,77 +1514,56 @@ 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));
-      try {
-        const pollRes = await fetch(`${endpoint}/v1/cli/auth/device/token`, {
-          method: "POST",
-          headers: { "Content-Type": "application/json" },
-          body: JSON.stringify({ device_code: deviceData.device_code })
-        });
-        const pollJson = await pollRes.json();
-        if (pollRes.ok && pollJson.ok && pollJson.data?.cli_token) {
-          cliToken = pollJson.data.cli_token;
-          break;
-        }
-        const errCode = pollJson.error ?? "";
-        if (errCode === "authorization_pending") {
-          process.stdout.write(".");
-          continue;
-        }
-        if (errCode === "access_denied") {
-          console.log("");
-          process.stderr.write("\nerror: Login denied in the browser.\n");
-          process.exit(1);
-        }
-        if (errCode === "expired_token") {
-          console.log("");
-          process.stderr.write("\nerror: Login code expired. Run mushi login again.\n");
-          process.exit(1);
+      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;
+        break;
+      }
+      if (outcome.status === "pending") {
+        consecutiveErrors = 0;
+        continue;
+      }
+      if (outcome.status === "error") {
+        if (outcome.retryable) {
+          consecutiveErrors += 1;
+          if (consecutiveErrors < MAX_CONSECUTIVE_ERRORS) continue;
         }
-        throw new Error(pollJson.error_description ?? errCode ?? `HTTP ${pollRes.status}`);
-      } catch (err) {
-        console.log("");
-        process.stderr.write(`
-error: Poll failed: ${err instanceof Error ? err.message : String(err)}
-`);
+        printAuthFailed("error", outcome.message);
+        process.exit(1);
+      }
+      if (outcome.status === "denied") {
+        printAuthFailed("denied");
+        process.exit(1);
+      }
+      if (outcome.status === "expired") {
+        printAuthFailed("timeout");
         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!");
-    const cliHeaders = {
-      "Content-Type": "application/json",
-      "Authorization": `Bearer ${cliToken}`
-    };
-    let projectsList = [];
-    try {
-      const listRes = await fetch(`${endpoint}/v1/cli/projects`, { headers: cliHeaders });
-      const listJson = await listRes.json();
-      if (listRes.ok && listJson.ok) projectsList = listJson.data?.projects ?? [];
-    } catch {
-    }
+    printAuthApproved();
+    const projectsList = await listProjects(endpoint, cliToken);
     let chosenProjectId = projectId;
     let chosenProjectName;
     if (!chosenProjectId) {
@@ -1271,18 +1595,10 @@ error: Poll failed: ${err instanceof Error ? err.message : String(err)}
           process.exit(2);
         }
         try {
-          const createRes = await fetch(`${endpoint}/v1/cli/projects`, {
-            method: "POST",
-            headers: cliHeaders,
-            body: JSON.stringify({ name: newName.trim() })
-          });
-          const createJson = await createRes.json();
-          if (!createRes.ok || !createJson.ok || !createJson.data) {
-            throw new Error(createJson.error?.message ?? `HTTP ${createRes.status}`);
-          }
-          chosenProjectId = createJson.data.id;
-          chosenProjectName = createJson.data.name;
-          apiKey = createJson.data.apiKey ?? void 0;
+          const created = await createProject(endpoint, cliToken, newName.trim());
+          chosenProjectId = created.id;
+          chosenProjectName = created.name;
+          apiKey = created.apiKey ?? void 0;
           console.log(`  \u2713 Created project "${chosenProjectName}"`);
         } catch (err) {
           process.stderr.write(`
@@ -1296,15 +1612,7 @@ error: Could not create project: ${err instanceof Error ? err.message : String(e
     }
     if (!apiKey && chosenProjectId) {
       try {
-        const keyRes = await fetch(`${endpoint}/v1/cli/projects/${chosenProjectId}/keys`, {
-          method: "POST",
-          headers: cliHeaders,
-          body: JSON.stringify({})
-        });
-        const keyJson = await keyRes.json();
-        if (keyRes.ok && keyJson.ok) {
-          apiKey = keyJson.data?.key ?? void 0;
-        }
+        apiKey = await mintProjectKey(endpoint, cliToken, chosenProjectId) ?? void 0;
       } catch {
       }
     }
@@ -1317,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.
@@ -2145,56 +2458,115 @@ Examples:
 // src/commands/project.ts
 function registerProjectCommands(program2) {
   const project = program2.command("project").description("Project management");
-  project.command("create").description("Create a new Mushi project, mint an API key, and write config files").option("--name <name>", "Project name (skip the prompt)").option("--no-browser", "Skip opening the browser for the sign-up / magic-link step").option("--endpoint <url>", "Override API endpoint (self-hosted)").addHelpText("after", `
-Creates a project on the Mushi console, mints an API key with mcp:read+write scope,
-and writes the following to the current directory:
+  project.command("create").description("Create or select a Mushi project via browser sign-in, then write config files").option("--name <name>", "Project name for a new project (skips the prompt)").option("--no-browser", "Print the verification URL instead of opening the browser").option("--endpoint <url>", "Override API endpoint (self-hosted)").addHelpText("after", `
+Signs you in through the browser (no copy-paste), creates or selects a project,
+mints a report:write SDK key, and writes the following to the current directory:
   .env.local            \u2014 MUSHI_API_KEY, MUSHI_PROJECT_ID, MUSHI_API_ENDPOINT
   .cursor/mcp.json      \u2014 pre-filled mcpServers.mushi block for Cursor
 
 Typical first-time flow:
   npx mushi-mushi project create
-  # Browser opens \u2192 sign up / magic-link \u2192 come back to terminal
+  # 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 endpoint = opts.endpoint ?? loadConfig().endpoint ?? "https://api.mushimushi.dev";
-    const consoleBase = resolveConsoleUrlSync();
-    const signUpUrl = consoleUrl(consoleBase, "/sign-up");
+    const savedConfig = loadConfig();
+    const endpoint = resolveCloudEndpoint(
+      opts.endpoint ?? process.env.MUSHI_API_ENDPOINT?.trim() ?? savedConfig.endpoint
+    );
+    const consoleBase = await resolveConsoleUrl();
     console.log("");
     console.log("  Mushi project create");
     console.log("  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
     console.log("");
+    let session;
+    try {
+      session = await startDeviceAuth(endpoint);
+    } catch (err) {
+      process.stderr.write(`
+error: Could not start browser sign-in: ${err instanceof Error ? err.message : String(err)}
+`);
+      process.stderr.write("  Fallback: mushi login --api-key <key> --project-id <uuid>\n");
+      process.exit(1);
+    }
     if (opts.browser !== false) {
-      console.log("  1. Opening the Mushi sign-up page in your browser...");
       try {
-        const { exec } = await import("child_process");
-        const openCmd = process.platform === "win32" ? `start "" "${signUpUrl}"` : process.platform === "darwin" ? `open "${signUpUrl}"` : `xdg-open "${signUpUrl}"`;
-        exec(openCmd);
+        await openInBrowser(session.verification_uri);
       } catch {
       }
-    } else {
-      console.log(`  1. Sign up or log in at: ${signUpUrl}`);
     }
-    console.log("");
-    console.log("  2. Create a project in the console, then paste your credentials below.");
-    console.log("     (Settings \u2192 API Keys \u2192 New key \u2192 Copy as .env.local)");
-    console.log("");
+    printAuthBanner(session.user_code, session.verification_uri);
+    let cliToken;
+    try {
+      cliToken = await waitForCliToken(endpoint, session);
+    } catch (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);
+    }
+    printAuthApproved();
+    const projectsList = await listProjects(endpoint, cliToken);
     const { createInterface } = await import("readline");
     const rl = createInterface({ input: process.stdin, output: process.stdout });
     const ask = (q) => new Promise((resolve3) => rl.question(q, (a) => resolve3(a.trim())));
-    const projectId = await ask("  Project ID (uuid): ");
-    const apiKey = await ask("  API key (mushi_...): ");
+    let chosen;
+    let projectId;
+    let projectName;
+    let apiKey;
+    if (!opts.name && projectsList.length > 0) {
+      console.log("");
+      console.log("  Your projects:");
+      projectsList.forEach((pr, i) => {
+        console.log(`    ${i + 1}. ${pr.name} (${pr.id})`);
+      });
+      console.log(`    ${projectsList.length + 1}. Create a new project`);
+      console.log("");
+      const choice = await ask(`  Pick a project [1-${projectsList.length + 1}]: `);
+      const num = parseInt(choice, 10);
+      if (num >= 1 && num <= projectsList.length) {
+        chosen = projectsList[num - 1];
+        projectId = chosen.id;
+        projectName = chosen.name;
+      }
+    }
+    if (!projectId) {
+      const newName = opts.name?.trim() || await ask("  Project name: ");
+      if (!newName) {
+        rl.close();
+        process.stderr.write("\nerror: Project name is required.\n");
+        process.exit(2);
+      }
+      try {
+        const created = await createProject(endpoint, cliToken, newName);
+        projectId = created.id;
+        projectName = created.name;
+        apiKey = created.apiKey ?? void 0;
+        console.log(`  \u2713 Created project "${projectName}"`);
+      } catch (err) {
+        rl.close();
+        process.stderr.write(`
+error: Could not create project: ${err instanceof Error ? err.message : String(err)}
+`);
+        process.exit(1);
+      }
+    }
     rl.close();
+    if (projectId && !apiKey) {
+      apiKey = await mintProjectKey(endpoint, cliToken, projectId) ?? void 0;
+    }
     if (!projectId || !apiKey) {
-      process.stderr.write("\nerror: Project ID and API key are required.\n");
-      process.exit(2);
+      process.stderr.write("\nerror: Could not obtain an SDK key for the project. Run `mushi login` and try again.\n");
+      process.exit(1);
     }
     const config = loadConfig();
     config.apiKey = apiKey;
     config.endpoint = endpoint;
     config.projectId = projectId;
+    config.consoleUrl = consoleBase;
     saveConfig(config);
     const cwd = process.cwd();
     const envPath = nodePath.join(cwd, ".env.local");
@@ -2223,7 +2595,7 @@ Typical first-time flow:
 
 // 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
@@ -2427,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) {
@@ -2637,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 [
       {
@@ -2839,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 {
@@ -2916,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) {
@@ -2949,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));
@@ -2968,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);
@@ -2995,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.`);
@@ -3240,7 +3802,7 @@ Examples:
     }
     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", "Write SDK env vars to .env.local (default: enabled)").option("--wire-ide", "Wire Cursor MCP into .cursor/mcp.json (default: enabled)").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", `
+  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) => {
@@ -3254,8 +3816,10 @@ Examples:
       projectId: opts.projectId,
       endpoint: opts.endpoint,
       cwd: opts.cwd,
-      writeEnv: opts.env !== false,
-      wireIde: opts.ide !== false,
+      // 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
@@ -3281,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({
@@ -4367,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", `
@@ -4399,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);