@mushi-mushi/cli 0.12.0 → 0.14.0

package/dist/index.js

@@ -35,10 +35,11 @@ function loadConfig(path = CONFIG_PATH) {
   } else if (path === CONFIG_PATH && existsSync(LEGACY_CONFIG_PATH)) {
     file = migrateLegacyConfig() ?? {};
   }
+  const endpointFromEnv = process.env["MUSHI_API_ENDPOINT"] ?? process.env["MUSHI_ENDPOINT"] ?? void 0;
   const fromEnv = {
     ...process.env["MUSHI_API_KEY"] ? { apiKey: process.env["MUSHI_API_KEY"] } : {},
     ...process.env["MUSHI_PROJECT_ID"] ? { projectId: process.env["MUSHI_PROJECT_ID"] } : {},
-    ...process.env["MUSHI_API_ENDPOINT"] ? { endpoint: process.env["MUSHI_API_ENDPOINT"] } : {}
+    ...endpointFromEnv ? { endpoint: endpointFromEnv } : {}
   };
   return { ...file, ...fromEnv };
 }
@@ -444,7 +445,7 @@ function normalizeEndpoint(url) {
 var REGISTRY = "https://registry.npmjs.org";
 var DEFAULT_TIMEOUT_MS = 2e3;
 async function checkFreshness(packageName, currentVersion, opts = {}) {
-  if (process.env.MUSHI_NO_UPDATE_CHECK === "1") return null;
+  if (!opts.ignoreOptOut && process.env.MUSHI_NO_UPDATE_CHECK === "1") return null;
   const registry = opts.registry ?? REGISTRY;
   const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
   const controller = new AbortController();
@@ -482,11 +483,13 @@ function isNewerStableVersion(latest, current) {
   return lc > cc;
 }
 function stripPreRelease(version) {
-  const idx = version.indexOf("-");
+  const idx = version.search(/[-+]/);
   return idx === -1 ? version : version.slice(0, idx);
 }
 function hasPreReleaseTag(version) {
-  return version.includes("-");
+  const plus = version.indexOf("+");
+  const hyphen = version.indexOf("-");
+  return hyphen !== -1 && (plus === -1 || hyphen < plus);
 }
 function parse(version) {
   const parts = version.split(".").map((part) => Number(part));
@@ -595,7 +598,7 @@ function getFrameworkFromPkg(pkg) {
 }
 
 // src/version.ts
-var MUSHI_CLI_VERSION = true ? "0.12.0" : "0.0.0-dev";
+var MUSHI_CLI_VERSION = true ? "0.14.0" : "0.0.0-dev";
 
 // src/init.ts
 var ENV_FILES = [".env.local", ".env"];
@@ -744,7 +747,7 @@ async function installPackages(pm, packages, cwd) {
 function runCommand(pm, packages, cwd) {
   const verb = pm === "npm" ? "install" : "add";
   const command = process.platform === "win32" ? `${pm}.cmd` : pm;
-  return new Promise((resolve2, reject) => {
+  return new Promise((resolve4, reject) => {
     const child = spawn(command, [verb, ...packages], {
       stdio: "inherit",
       shell: false,
@@ -753,7 +756,7 @@ function runCommand(pm, packages, cwd) {
     });
     child.on("error", reject);
     child.on("exit", (code) => {
-      if (code === 0) resolve2();
+      if (code === 0) resolve4();
       else reject(new Error(`${pm} exited with code ${code ?? "null"}`));
     });
   });
@@ -1108,11 +1111,11 @@ async function findMapFiles(dir) {
   return results;
 }
 function fileHash(path) {
-  return new Promise((resolve2, reject) => {
+  return new Promise((resolve4, reject) => {
     const hash = createHash("sha256");
     const stream = createReadStream(path);
     stream.on("data", (chunk) => hash.update(chunk));
-    stream.on("end", () => resolve2(hash.digest("hex")));
+    stream.on("end", () => resolve4(hash.digest("hex")));
     stream.on("error", reject);
   });
 }
@@ -1416,13 +1419,83 @@ function renderNudgeExplainer(phase) {
   return lines.join("\n");
 }
 
+// src/heartbeat-wait.ts
+var IngestSetupHttpError = class extends Error {
+  status;
+  constructor(status) {
+    super(`ingest-setup HTTP ${status}`);
+    this.name = "IngestSetupHttpError";
+    this.status = status;
+  }
+};
+var NON_RETRYABLE_STATUSES = /* @__PURE__ */ new Set([401, 403, 404]);
+async function fetchIngestSetup(config, doFetch = globalThis.fetch) {
+  const safeKey = config.apiKey.replace(/[\r\n]/g, "");
+  const res = await doFetch(`${config.endpoint}/v1/sync/ingest-setup`, {
+    headers: {
+      Authorization: `Bearer ${safeKey}`,
+      "X-Mushi-Api-Key": safeKey,
+      ...config.projectId ? { "X-Mushi-Project": config.projectId } : {}
+    },
+    signal: AbortSignal.timeout(8e3)
+  });
+  if (!res.ok) {
+    if (NON_RETRYABLE_STATUSES.has(res.status)) throw new IngestSetupHttpError(res.status);
+    return null;
+  }
+  const body = await res.json();
+  return body.ok && body.data ? body.data : null;
+}
+async function waitForIngestReady(options) {
+  const doFetch = options.fetch ?? globalThis.fetch;
+  const maxAttempts = options.maxAttempts ?? 40;
+  const intervalMs = options.intervalMs ?? 3e3;
+  let lastPayload = null;
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    if (options.signal?.aborted) {
+      return { ok: false, payload: lastPayload, attempts: attempt - 1, reason: "aborted" };
+    }
+    try {
+      lastPayload = await fetchIngestSetup(
+        { endpoint: options.endpoint, apiKey: options.apiKey, projectId: options.projectId },
+        doFetch
+      );
+      if (lastPayload) {
+        options.onPoll?.(lastPayload, attempt);
+        if (lastPayload.ready) {
+          return { ok: true, payload: lastPayload, attempts: attempt, reason: "ready" };
+        }
+        const sdkStep = lastPayload.steps.find((s) => s.id === "sdk_installed");
+        if (sdkStep?.complete) {
+          return { ok: true, payload: lastPayload, attempts: attempt, reason: "heartbeat" };
+        }
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (err instanceof IngestSetupHttpError) {
+        return { ok: false, payload: lastPayload, attempts: attempt, reason: "unauthorized", error: msg };
+      }
+      if (options.signal?.aborted) {
+        return { ok: false, payload: lastPayload, attempts: attempt, reason: "aborted", error: msg };
+      }
+      if (attempt === maxAttempts) {
+        return { ok: false, payload: lastPayload, attempts: attempt, reason: "fetch-error", error: msg };
+      }
+    }
+    if (attempt < maxAttempts) {
+      await new Promise((r) => setTimeout(r, intervalMs));
+    }
+  }
+  return { ok: false, payload: lastPayload, attempts: maxAttempts, reason: "timeout" };
+}
+
 // src/doctor.ts
 function checkCliConfig(config) {
   return [
     {
       name: "CLI config file",
       ok: Boolean(config.endpoint),
-      detail: config.endpoint ? `endpoint=${config.endpoint}` : "No endpoint in ~/.mushirc \u2014 run `mushi init` or `mushi config endpoint <url>`"
+      detail: config.endpoint ? `endpoint=${config.endpoint}` : "No endpoint \u2014 set MUSHI_API_ENDPOINT, run `mushi connect`, or `mushi config endpoint <url>`"
     },
     {
       name: "API key configured",
@@ -1453,11 +1526,11 @@ async function checkEndpointReachability(endpoint, doFetch = globalThis.fetch) {
 }
 async function checkSdkInstall(cwd) {
   try {
-    const { readFile: readFile2 } = await import("fs/promises");
-    const { join: join6, resolve: resolve2 } = await import("path");
-    const root = resolve2(cwd);
-    const pkgPath = join6(root, "package.json");
-    const pkg = JSON.parse(await readFile2(pkgPath, "utf8"));
+    const { readFile: readFile3 } = await import("fs/promises");
+    const { join: join7, resolve: resolve4 } = await import("path");
+    const root = resolve4(cwd);
+    const pkgPath = join7(root, "package.json");
+    const pkg = JSON.parse(await readFile3(pkgPath, "utf8"));
     const deps = { ...pkg.dependencies ?? {}, ...pkg.devDependencies ?? {} };
     const sdks = [
       "@mushi-mushi/react",
@@ -1503,7 +1576,7 @@ async function checkServerPreflight(config, doFetch = globalThis.fetch) {
       return serverChecks.map((sc) => ({
         name: `[server] ${sc.label}`,
         ok: sc.ready,
-        detail: sc.hint
+        detail: sc.ready ? "" : sc.hint
       }));
     }
     const text2 = await res.text().catch(() => "");
@@ -1519,6 +1592,132 @@ async function checkServerPreflight(config, doFetch = globalThis.fetch) {
     return [{ name: "Server preflight", ok: false, detail: `Fetch failed: ${msg}` }];
   }
 }
+async function checkIngestSetup(config, doFetch = globalThis.fetch) {
+  if (!config.apiKey || !config.endpoint) {
+    return [
+      {
+        name: "Ingest setup",
+        ok: false,
+        detail: "Need apiKey and endpoint. Run `mushi connect`."
+      }
+    ];
+  }
+  try {
+    const data = await fetchIngestSetup(
+      { endpoint: config.endpoint, apiKey: config.apiKey, projectId: config.projectId },
+      doFetch
+    );
+    if (!data) {
+      return [{ name: "Ingest setup", ok: false, detail: "Request to /v1/sync/ingest-setup failed or returned invalid payload" }];
+    }
+    const steps = data.steps ?? [];
+    const checks = steps.filter((s) => s.required).map((s) => ({
+      name: `[ingest] ${s.label}`,
+      ok: s.complete,
+      detail: s.complete ? "" : s.hint ?? ""
+    }));
+    const diag = data.diagnostic;
+    if (diag?.last_sdk_seen_at) {
+      checks.push({
+        name: "[ingest] Last SDK heartbeat",
+        ok: true,
+        detail: `${diag.last_sdk_seen_at}${diag.last_sdk_endpoint_host ? ` @ ${diag.last_sdk_endpoint_host}` : ""}`
+      });
+    }
+    return checks.length > 0 ? checks : [{ name: "Ingest setup", ok: false, detail: "Empty response from /v1/sync/ingest-setup" }];
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return [{ name: "Ingest setup", ok: false, detail: `Fetch failed: ${msg}` }];
+  }
+}
+async function checkQaStoriesHealth(config, doFetch = globalThis.fetch) {
+  if (!config.projectId || !config.apiKey || !config.endpoint) {
+    return [
+      {
+        name: "QA stories health",
+        ok: false,
+        detail: "Need projectId, apiKey, and endpoint for QA story checks."
+      }
+    ];
+  }
+  const checks = [];
+  try {
+    const storiesRes = await doFetch(
+      `${config.endpoint}/v1/admin/projects/${config.projectId}/qa-coverage`,
+      {
+        headers: {
+          Authorization: `Bearer ${config.apiKey}`,
+          "X-Mushi-Api-Key": config.apiKey,
+          "X-Mushi-Project": config.projectId
+        },
+        signal: AbortSignal.timeout(8e3)
+      }
+    );
+    if (!storiesRes.ok) {
+      checks.push({ name: "[qa] Fetch QA stories", ok: false, detail: `HTTP ${storiesRes.status}` });
+      return checks;
+    }
+    const storiesBody = await storiesRes.json();
+    const stories2 = storiesBody.data?.coverage ?? [];
+    const enabled = stories2.filter((s) => s.enabled);
+    if (enabled.length === 0) {
+      checks.push({ name: "[qa] Enabled QA stories", ok: true, detail: "No enabled stories \u2014 create one at /qa-coverage" });
+      return checks;
+    }
+    checks.push({
+      name: "[qa] Enabled QA stories",
+      ok: true,
+      detail: `${enabled.length} enabled story/stories configured`
+    });
+    const slackRes = await doFetch(
+      `${config.endpoint}/v1/admin/projects/${config.projectId}/integrations/probe/slack`,
+      {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${config.apiKey}`,
+          "X-Mushi-Api-Key": config.apiKey,
+          "X-Mushi-Project": config.projectId
+        },
+        signal: AbortSignal.timeout(6e3)
+      }
+    );
+    const slackBody = slackRes.ok ? await slackRes.json() : null;
+    const slackOk = slackBody?.status === "ok";
+    checks.push({
+      name: "[qa] Slack notifications configured",
+      ok: slackOk,
+      detail: slackOk ? "Slack connected \u2014 failures will notify your channel" : "Slack not connected \u2014 you won't be notified when stories fail. Visit /integrations \u2192 Add to Slack."
+    });
+    const fcRes = await doFetch(
+      `${config.endpoint}/v1/admin/projects/${config.projectId}/integrations/probe/firecrawl`,
+      {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${config.apiKey}`,
+          "X-Mushi-Api-Key": config.apiKey,
+          "X-Mushi-Project": config.projectId
+        },
+        signal: AbortSignal.timeout(6e3)
+      }
+    );
+    const fcBody = fcRes.ok ? await fcRes.json() : null;
+    const hasFirecrawlStories = enabled.some(
+      (s) => !s.browser_provider || s.browser_provider === "firecrawl_actions"
+    );
+    if (hasFirecrawlStories) {
+      const fcOk = fcBody?.status === "ok";
+      checks.push({
+        name: "[qa] Firecrawl API key configured",
+        ok: fcOk,
+        detail: fcOk ? "Firecrawl key is resolvable \u2014 stories will run without Unauthorized errors" : "No Firecrawl key found \u2014 enabled stories using firecrawl_actions will 401. Add a key at /integrations \u2192 BYOK keys."
+      });
+    }
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    checks.push({ name: "[qa] QA stories health", ok: false, detail: `Fetch failed: ${msg}` });
+  }
+  return checks;
+}
 async function runDoctor(config, options = {}) {
   const doFetch = options.fetch ?? globalThis.fetch;
   const checks = [];
@@ -1532,6 +1731,14 @@ async function runDoctor(config, options = {}) {
     const serverChecks = await checkServerPreflight(config, doFetch);
     checks.push(...serverChecks);
   }
+  if (options.ingest) {
+    const ingestChecks = await checkIngestSetup(config, doFetch);
+    checks.push(...ingestChecks);
+  }
+  if (options.qaStories) {
+    const qaChecks = await checkQaStoriesHealth(config, doFetch);
+    checks.push(...qaChecks);
+  }
   return { checks, ready: checks.every((c) => c.ok) };
 }
 function formatDoctorResult(result) {
@@ -1540,7 +1747,7 @@ function formatDoctorResult(result) {
   const lines = [];
   for (const c of result.checks) {
     lines.push(`${c.ok ? PASS : FAIL} ${c.name}`);
-    lines.push(`  ${c.detail}`);
+    if (c.detail) lines.push(`  ${c.detail}`);
   }
   const failed = result.checks.filter((c) => !c.ok);
   if (failed.length === 0) {
@@ -1553,6 +1760,237 @@ ${failed.length} check${failed.length === 1 ? "" : "s"} failed.`);
   return lines.join("\n");
 }
 
+// src/upgrade.ts
+import { resolve as resolve2 } from "path";
+import { execSync } from "child_process";
+var SAFE_NPM_VERSION = /^\d+\.\d+\.\d+(-[\w.]+)?$/;
+var MUSHI_PACKAGES = [
+  "@mushi-mushi/web",
+  "@mushi-mushi/core",
+  "@mushi-mushi/react",
+  "@mushi-mushi/react-native",
+  "@mushi-mushi/capacitor",
+  "@mushi-mushi/node",
+  "@mushi-mushi/cli"
+];
+async function planUpgrade(cwd) {
+  const root = resolve2(cwd);
+  const pkg = readPackageJson(root);
+  const pm = detectPackageManager(root);
+  const deps = {
+    ...pkg?.dependencies ?? {},
+    ...pkg?.devDependencies ?? {}
+  };
+  const installed2 = MUSHI_PACKAGES.filter((name) => deps[name]);
+  const entries = await Promise.all(
+    installed2.map(async (name) => {
+      const current = deps[name] ?? "";
+      const currentCore = current.replace(/^[\^~>=<]*/, "");
+      if (!/^\d/.test(currentCore)) {
+        return { name, current, latest: null, willUpgrade: false };
+      }
+      const freshness = await checkFreshness(name, currentCore, {
+        timeoutMs: 4e3,
+        ignoreOptOut: true
+      });
+      const latest = freshness?.latest ?? null;
+      const safeLatest = latest && SAFE_NPM_VERSION.test(latest) ? latest : null;
+      const willUpgrade = Boolean(freshness?.isOutdated && safeLatest);
+      return {
+        name,
+        current,
+        latest: safeLatest,
+        willUpgrade,
+        migrateToWeb: name === "@mushi-mushi/react" && willUpgrade
+      };
+    })
+  );
+  const toBump = entries.filter((e) => e.willUpgrade && e.latest).map((e) => `${e.name}@${e.latest}`);
+  return {
+    cwd: root,
+    packageManager: pm,
+    entries,
+    installCmd: toBump.length > 0 ? installCommand(pm, toBump) : null
+  };
+}
+async function runUpgrade(opts = {}) {
+  const plan = await planUpgrade(opts.cwd ?? process.cwd());
+  if (plan.entries.length === 0) {
+    return {
+      plan,
+      upgraded: false,
+      message: "No @mushi-mushi/* packages in package.json \u2014 run `mushi init` first."
+    };
+  }
+  if (!plan.installCmd) {
+    const semverEntries = plan.entries.filter((e) => /\d/.test(e.current));
+    const allChecksFailed = semverEntries.length > 0 && semverEntries.every((e) => e.latest === null);
+    return {
+      plan,
+      upgraded: false,
+      message: allChecksFailed ? "Could not reach the npm registry to check for updates \u2014 try again in a moment." : "All installed Mushi packages are already at the latest stable version."
+    };
+  }
+  if (opts.dryRun) {
+    return { plan, upgraded: false, message: `[dry-run] Would run: ${plan.installCmd}` };
+  }
+  try {
+    execSync(plan.installCmd, { cwd: plan.cwd, stdio: "inherit", env: process.env });
+  } catch {
+    return {
+      plan,
+      upgraded: false,
+      message: `Install command failed \u2014 fix the error above or run it manually:
+  ${plan.installCmd}`
+    };
+  }
+  const reactEntry = plan.entries.find((e) => e.migrateToWeb);
+  const migrateNote = reactEntry ? "\nNote: @mushi-mushi/react is legacy \u2014 prefer @mushi-mushi/web for Vite/Capacitor/SPA apps." : "";
+  return {
+    plan,
+    upgraded: true,
+    message: `Upgraded Mushi SDK packages.
+  ${plan.installCmd}${migrateNote}`
+  };
+}
+
+// src/connect.ts
+import { appendFile, mkdir, readFile as readFile2, writeFile } from "fs/promises";
+import { join as join6, resolve as resolve3 } from "path";
+function envKeyPresent(content, key) {
+  const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return new RegExp(`^${escaped}=`, "m").test(content);
+}
+async function mergeEnvFile(path, lines) {
+  const block = `
+# Mushi \u2014 added by mushi connect
+${lines.join("\n")}
+`;
+  let existing = null;
+  try {
+    existing = await readFile2(path, "utf8");
+  } catch {
+  }
+  if (existing !== null) {
+    const needs = lines.filter((line) => {
+      const key = line.split("=")[0];
+      return !envKeyPresent(existing, key);
+    });
+    if (needs.length === 0) return false;
+    await appendFile(path, `
+# Mushi \u2014 added by mushi connect
+${needs.join("\n")}
+`, "utf8");
+    return true;
+  }
+  await writeFile(path, block, "utf8");
+  return true;
+}
+async function ensureMcpJsonGitignored(cwd, messages) {
+  const gitignorePath = join6(cwd, ".gitignore");
+  const patterns = [".cursor/mcp.json", ".cursor/"];
+  let content = null;
+  try {
+    content = await readFile2(gitignorePath, "utf8");
+  } catch {
+  }
+  if (content === null) {
+    messages.push(
+      "\u26A0 No .gitignore found \u2014 .cursor/mcp.json contains your API key. Add `.cursor/mcp.json` before committing."
+    );
+    return;
+  }
+  const covered = patterns.some((p3) => content.split("\n").some((line) => line.trim() === p3 || line.trim() === `${p3}/`));
+  if (covered) return;
+  await appendFile(gitignorePath, "\n# Mushi \u2014 keep MCP credentials out of git\n.cursor/mcp.json\n", "utf8");
+  messages.push("\u2713 Added .cursor/mcp.json to .gitignore (contains API key)");
+}
+async function runConnect(opts, baseConfig = {}) {
+  const cwd = resolve3(opts.cwd ?? process.cwd());
+  const endpoint = assertEndpoint(opts.endpoint);
+  const messages = [];
+  const config = {
+    ...baseConfig,
+    apiKey: opts.apiKey,
+    projectId: opts.projectId,
+    endpoint
+  };
+  saveConfig(config);
+  messages.push(`\u2713 Credentials saved to ${CONFIG_PATH}`);
+  let envPath = null;
+  if (opts.writeEnv !== false) {
+    const pkg = readPackageJson(cwd);
+    const framework = detectFramework(cwd, pkg);
+    const lines = envVarsToWrite(opts.apiKey, opts.projectId, framework).split("\n");
+    envPath = join6(cwd, ".env.local");
+    const wrote = await mergeEnvFile(envPath, lines);
+    messages.push(
+      wrote ? `\u2713 Env vars merged into ${envPath}` : `\u2713 Env vars already present in ${envPath} (existing values left untouched)`
+    );
+  }
+  let mcpPath = null;
+  if (opts.wireIde !== false) {
+    const mcpDir = join6(cwd, ".cursor");
+    mcpPath = join6(mcpDir, "mcp.json");
+    const serverName = `mushi-${opts.projectId.slice(0, 8)}`;
+    const mcpServerBlock = {
+      command: "npx",
+      args: ["-y", "@mushi-mushi/mcp@latest"],
+      env: {
+        MUSHI_API_ENDPOINT: endpoint,
+        MUSHI_PROJECT_ID: opts.projectId,
+        MUSHI_API_KEY: opts.apiKey
+      }
+    };
+    let merged = { mcpServers: {} };
+    try {
+      merged = JSON.parse(await readFile2(mcpPath, "utf8"));
+    } catch {
+    }
+    const servers = merged.mcpServers ?? {};
+    servers[serverName] = mcpServerBlock;
+    merged.mcpServers = servers;
+    await mkdir(mcpDir, { recursive: true });
+    await writeFile(mcpPath, JSON.stringify(merged, null, 2) + "\n", "utf8");
+    await ensureMcpJsonGitignored(cwd, messages);
+    messages.push(`\u2713 Wired ${mcpPath} \u2014 restart Cursor and run "list mushi tools"`);
+  }
+  let heartbeat = null;
+  if (opts.wait) {
+    const timeoutSec = opts.waitTimeoutSec ?? 120;
+    const maxAttempts = Math.max(1, Math.ceil(timeoutSec * 1e3 / 3e3));
+    messages.push(`\u2026 Waiting for SDK heartbeat (up to ${timeoutSec}s) \u2014 start your dev server with the snippet installed`);
+    heartbeat = await waitForIngestReady({
+      endpoint,
+      apiKey: opts.apiKey,
+      projectId: opts.projectId,
+      maxAttempts,
+      onPoll: (payload, attempt) => {
+        if (!opts.json && attempt % 3 === 0) {
+          const sdk = payload.steps.find((s) => s.id === "sdk_installed");
+          const seen = payload.diagnostic?.last_sdk_seen_at ?? "never";
+          process.stdout.write(`  poll ${attempt}: sdk_installed=${sdk?.complete ? "yes" : "no"} last_seen=${seen}
+`);
+        }
+      }
+    });
+    if (heartbeat.ok) {
+      const label = heartbeat.reason === "heartbeat" ? "SDK heartbeat detected" : "Ingest setup complete";
+      messages.push(`\u2713 ${label} \u2014 ingest pipeline is live`);
+    } else if (heartbeat.reason === "unauthorized") {
+      messages.push(
+        `\u2717 The backend rejected these credentials (${heartbeat.error ?? "auth error"}). Double-check --api-key, --project-id, and --endpoint, then re-run \`mushi connect --wait\`.`
+      );
+    } else {
+      messages.push(
+        `\u2717 No heartbeat before timeout (${heartbeat.reason}). Confirm env vars are in your build, restart the dev server, then re-run \`mushi connect --wait\`.`
+      );
+    }
+  }
+  const ok = !opts.wait || Boolean(heartbeat?.ok);
+  return { ok, envPath, mcpPath, heartbeat, messages };
+}
+
 // src/index.ts
 installSignalHandlers();
 var API_TIMEOUT_MS = 15e3;
@@ -1799,7 +2237,7 @@ Examples:
   mushi config endpoint https://...   # set endpoint
   mushi config projectId <uuid>       # set project`).action((key, value) => {
   const config = loadConfig();
-  const ALLOWED_KEYS = /* @__PURE__ */ new Set(["apiKey", "endpoint", "projectId"]);
+  const ALLOWED_KEYS = /* @__PURE__ */ new Set(["apiKey", "endpoint", "projectId", "consoleUrl"]);
   if (key && value) {
     if (!ALLOWED_KEYS.has(key)) {
       process.stderr.write(`error: unknown config key "${key}". Allowed: ${[...ALLOWED_KEYS].join(", ")}
@@ -2016,6 +2454,31 @@ reports.command("dismiss <id>").description("Dismiss a report (not a real bug /
     console.log(`\u2713 Dismissed report ${id}`);
   }
 });
+reports.command("reply <id> <message>").description("Send a visible reply to the reporter widget for a report").option("--author <name>", 'Display name for the sender (default: "Mushi Admin")').option("--json", "Machine-readable JSON output").addHelpText("after", `
+Examples:
+  mushi reports reply abc123 "Thanks for reporting \u2014 fixing this in the next release."
+  mushi reports reply abc123 "Can you share a screenshot?" --author "Alice"`).action(async (id, message, opts) => {
+  const config = requireConfig();
+  const body = { message };
+  if (opts.author) body["author_name"] = opts.author;
+  const result = await apiCall(`/v1/sync/reports/${id}/reply`, config, {
+    method: "POST",
+    body: JSON.stringify(body)
+  });
+  if (!result.ok) {
+    if (result.httpStatus === 404 || result.error.code === "NOT_FOUND") {
+      process.stderr.write(`error: report "${id}" not found
+`);
+      process.exit(3);
+    }
+    die(result);
+  }
+  if (opts.json) {
+    console.log(JSON.stringify(result.data, null, 2));
+  } else {
+    console.log(`\u2713 Reply sent to reporter for report ${id}`);
+  }
+});
 reports.command("search <query>").description("Search reports by keyword in summary and description").option("--limit <n>", "Max results (1\u201350)", "10").option("--status <status>", "Filter by status").option("--json", "Machine-readable JSON output").addHelpText("after", `
 Examples:
   mushi reports search "login button"
@@ -2117,7 +2580,7 @@ AI code review context.
 Typical CI usage:
   MUSHI_API_KEY=$KEY MUSHI_PROJECT_ID=$PID MUSHI_API_ENDPOINT=$URL \\
     npx @mushi-mushi/cli sync-lessons --cwd .`).action(async (opts) => {
-  const { writeFile, mkdir } = await import("fs/promises");
+  const { writeFile: writeFile2, mkdir: mkdir2 } = await import("fs/promises");
   const nodePath = await import("path");
   const config = requireConfig();
   const cwd = opts.cwd ?? process.cwd();
@@ -2144,8 +2607,8 @@ Typical CI usage:
     console.log(JSON.stringify(output, null, 2));
     return;
   }
-  await mkdir(nodePath.dirname(target), { recursive: true });
-  await writeFile(target, JSON.stringify(output, null, 2) + "\n", "utf8");
+  await mkdir2(nodePath.dirname(target), { recursive: true });
+  await writeFile2(target, JSON.stringify(output, null, 2) + "\n", "utf8");
   if (opts.json) {
     console.log(JSON.stringify({ ok: true, path: target, count: lessons2.length }));
   } else {
@@ -2194,7 +2657,7 @@ Examples:
   mushi index ./src
   mushi index ./src --language ts --dry-run`).action(async (path, opts) => {
   const config = requireConfig({ needsProject: true });
-  const { readdir: readdir2, readFile: readFile2, stat } = await import("fs/promises");
+  const { readdir: readdir2, readFile: readFile3, stat } = await import("fs/promises");
   const nodePath = await import("path");
   const SKIP = /node_modules|\.git|dist|build|\.next|\.turbo|coverage/;
   const EXTS = /* @__PURE__ */ new Set([".ts", ".tsx", ".js", ".jsx", ".py", ".go", ".rs"]);
@@ -2221,7 +2684,7 @@ Examples:
 `);
       continue;
     }
-    const source = await readFile2(file, "utf8");
+    const source = await readFile3(file, "utf8");
     const relative2 = nodePath.relative(root, file).replaceAll("\\", "/");
     count++;
     bytes += source.length;
@@ -2278,7 +2741,7 @@ Typical first-time flow:
   # Browser opens \u2192 sign up / magic-link \u2192 come back to terminal
   # CLI writes .env.local and .cursor/mcp.json
   # mushi whoami to confirm`).action(async (opts) => {
-  const { writeFile, mkdir } = await import("fs/promises");
+  const { writeFile: writeFile2, mkdir: mkdir2 } = await import("fs/promises");
   const { existsSync: existsSync5 } = await import("fs");
   const nodePath = await import("path");
   const endpoint = opts.endpoint ?? loadConfig().endpoint ?? "https://api.mushimushi.dev";
@@ -2304,7 +2767,7 @@ Typical first-time flow:
   console.log("");
   const { createInterface } = await import("readline");
   const rl = createInterface({ input: process.stdin, output: process.stdout });
-  const ask = (q) => new Promise((resolve2) => rl.question(q, (a) => resolve2(a.trim())));
+  const ask = (q) => new Promise((resolve4) => rl.question(q, (a) => resolve4(a.trim())));
   const projectId = await ask("  Project ID (uuid): ");
   const apiKey = await ask("  API key (mushi_...): ");
   rl.close();
@@ -2327,17 +2790,17 @@ Typical first-time flow:
     ""
   ];
   const envExisting = existsSync5(envPath);
-  await writeFile(envPath, envLines.join("\n"), "utf8");
+  await writeFile2(envPath, envLines.join("\n"), "utf8");
   console.log(`
   \u2713 ${envExisting ? "Updated" : "Created"} .env.local`);
   const mcpDir = nodePath.join(cwd, ".cursor");
-  await mkdir(mcpDir, { recursive: true });
+  await mkdir2(mcpDir, { recursive: true });
   const mcpPath = nodePath.join(mcpDir, "mcp.json");
   const mcpJson = {
     mcpServers: {
       mushi: {
         command: "npx",
-        args: ["-y", "mushi-mcp@latest"],
+        args: ["-y", "@mushi-mushi/mcp@latest"],
         env: {
           MUSHI_API_ENDPOINT: endpoint,
           MUSHI_PROJECT_ID: projectId,
@@ -2349,16 +2812,16 @@ Typical first-time flow:
   const mcpExisting = existsSync5(mcpPath);
   if (mcpExisting) {
     try {
-      const { readFile: readFile2 } = await import("fs/promises");
-      const raw = JSON.parse(await readFile2(mcpPath, "utf8"));
+      const { readFile: readFile3 } = await import("fs/promises");
+      const raw = JSON.parse(await readFile3(mcpPath, "utf8"));
       const existing = raw;
       existing.mcpServers = { ...existing.mcpServers ?? {}, mushi: mcpJson.mcpServers.mushi };
-      await writeFile(mcpPath, JSON.stringify(existing, null, 2) + "\n", "utf8");
+      await writeFile2(mcpPath, JSON.stringify(existing, null, 2) + "\n", "utf8");
     } catch {
-      await writeFile(mcpPath, JSON.stringify(mcpJson, null, 2) + "\n", "utf8");
+      await writeFile2(mcpPath, JSON.stringify(mcpJson, null, 2) + "\n", "utf8");
     }
   } else {
-    await writeFile(mcpPath, JSON.stringify(mcpJson, null, 2) + "\n", "utf8");
+    await writeFile2(mcpPath, JSON.stringify(mcpJson, null, 2) + "\n", "utf8");
   }
   console.log(`  \u2713 ${mcpExisting ? "Updated" : "Created"} .cursor/mcp.json`);
   console.log("");
@@ -2379,7 +2842,7 @@ Supported IDEs:
   zed       \u2014 writes ~/.config/zed/settings.json mcpServers block
 
 The command reads credentials from ~/.mushirc (run \`mushi login\` first).`).action(async (opts) => {
-  const { writeFile, mkdir, readFile: readFile2 } = await import("fs/promises");
+  const { writeFile: writeFile2, mkdir: mkdir2, readFile: readFile3 } = await import("fs/promises");
   const { existsSync: existsSync5 } = await import("fs");
   const nodePath = await import("path");
   const os = await import("os");
@@ -2401,7 +2864,7 @@ The command reads credentials from ~/.mushirc (run \`mushi login\` first).`).act
   const serverName = `mushi-${slug}`;
   const mcpServerBlock = {
     command: "npx",
-    args: ["-y", "mushi-mcp@latest"],
+    args: ["-y", "@mushi-mushi/mcp@latest"],
     env: {
       MUSHI_API_ENDPOINT: config.endpoint,
       MUSHI_PROJECT_ID: config.projectId ?? "",
@@ -2414,7 +2877,7 @@ The command reads credentials from ~/.mushirc (run \`mushi login\` first).`).act
     let merged = { mcpServers: {} };
     if (existsSync5(configPath)) {
       try {
-        const raw = await readFile2(configPath, "utf8");
+        const raw = await readFile3(configPath, "utf8");
         merged = JSON.parse(raw);
       } catch {
       }
@@ -2427,15 +2890,15 @@ The command reads credentials from ~/.mushirc (run \`mushi login\` first).`).act
       console.log(`[dry-run] Would write ${configPath}:`);
       console.log(output);
     } else {
-      await mkdir(configDir, { recursive: true });
-      await writeFile(configPath, output, "utf8");
+      await mkdir2(configDir, { recursive: true });
+      await writeFile2(configPath, output, "utf8");
       console.log(`\u2713 Written ${configPath}`);
     }
   } else if (ideEntry.format === "zed") {
     let settings = {};
     if (existsSync5(configPath)) {
       try {
-        const raw = await readFile2(configPath, "utf8");
+        const raw = await readFile3(configPath, "utf8");
         settings = JSON.parse(raw);
       } catch {
       }
@@ -2444,7 +2907,7 @@ The command reads credentials from ~/.mushirc (run \`mushi login\` first).`).act
     servers[serverName] = {
       command: {
         path: "npx",
-        args: ["-y", "mushi-mcp@latest"],
+        args: ["-y", "@mushi-mushi/mcp@latest"],
         env: {
           MUSHI_API_ENDPOINT: config.endpoint,
           MUSHI_PROJECT_ID: config.projectId ?? "",
@@ -2459,8 +2922,8 @@ The command reads credentials from ~/.mushirc (run \`mushi login\` first).`).act
       console.log(`[dry-run] Would write ${configPath}:`);
       console.log(output);
     } else {
-      await mkdir(configDir, { recursive: true });
-      await writeFile(configPath, output, "utf8");
+      await mkdir2(configDir, { recursive: true });
+      await writeFile2(configPath, output, "utf8");
       console.log(`\u2713 Written ${configPath}`);
     }
   }
@@ -2494,7 +2957,7 @@ The command reads credentials from ~/.mushirc (run \`mushi login\` first).`).act
       if (opts.dryRun) {
         console.log(`[dry-run] Would write ${rulesPath}`);
       } else {
-        await writeFile(rulesPath, rulesContent, "utf8");
+        await writeFile2(rulesPath, rulesContent, "utf8");
         console.log(`\u2713 Written .cursorrules`);
       }
     } else if (opts.ide === "claude") {
@@ -2503,8 +2966,8 @@ The command reads credentials from ~/.mushirc (run \`mushi login\` first).`).act
       if (opts.dryRun) {
         console.log(`[dry-run] Would write ${rulesPath}`);
       } else {
-        await mkdir(rulesDir, { recursive: true });
-        await writeFile(rulesPath, rulesContent, "utf8");
+        await mkdir2(rulesDir, { recursive: true });
+        await writeFile2(rulesPath, rulesContent, "utf8");
         console.log(`\u2713 Written .claude/rules/mushi.md`);
       }
     }
@@ -2558,6 +3021,7 @@ Examples:
   emitEvent("dispatch.start", { reportId, agent: opts.agent, model: opts.model ?? null });
   const body = {
     reportId,
+    projectId: cfg.projectId,
     agent: opts.agent
   };
   if (opts.agent === "cursor_cloud") {
@@ -2638,14 +3102,67 @@ program.command("nudge").description(
   }
   console.log(renderNudgeSnippet({ phase, overrides }));
 });
+program.command("upgrade").description("Bump installed @mushi-mushi/* packages to the latest stable npm release").option("--cwd <path>", "Target repo (default: cwd)").option("--dry-run", "Print the install command without running it").option("--json", "Machine-readable plan + result").addHelpText("after", `
+Examples:
+  mushi upgrade
+  mushi upgrade --dry-run
+  mushi upgrade --cwd ../glot.it`).action(async (opts) => {
+  const result = await runUpgrade({ cwd: opts.cwd, dryRun: opts.dryRun, json: opts.json });
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(result.message);
+    for (const e of result.plan.entries) {
+      const tag = e.willUpgrade && e.latest ? `\u2192 v${e.latest}` : "(current)";
+      console.log(`  ${e.name}@${e.current} ${tag}`);
+    }
+  }
+  if (!result.upgraded && result.plan.entries.some((e) => e.willUpgrade) && !opts.dryRun) {
+    process.exit(1);
+  }
+  if (result.plan.entries.length === 0) process.exit(1);
+});
+program.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("--no-env", "Skip writing .env.local").option("--no-ide", "Skip writing .cursor/mcp.json").option("--wait", "Poll ingest-setup until SDK heartbeat lands").option("--wait-timeout <sec>", "Max seconds for --wait", "120").option("--json", "Machine-readable output").addHelpText("after", `
+Examples:
+  MUSHI_API_KEY=mushi_xxx mushi connect --project-id <uuid> --endpoint https://<ref>.supabase.co/functions/v1/api --wait
+  mushi connect --api-key mushi_xxx --project-id <uuid> --endpoint <url> --no-ide`).action(async (opts) => {
+  const apiKey = process.env.MUSHI_API_KEY ?? opts.apiKey;
+  if (!apiKey) {
+    console.error("Provide the API key via the MUSHI_API_KEY env var (recommended) or --api-key <key>.");
+    process.exit(1);
+  }
+  const result = await runConnect({
+    apiKey,
+    projectId: opts.projectId,
+    endpoint: opts.endpoint,
+    cwd: opts.cwd,
+    writeEnv: opts.env !== false,
+    wireIde: opts.ide !== false,
+    wait: opts.wait,
+    waitTimeoutSec: parseInt(opts.waitTimeout, 10) || 120,
+    json: opts.json
+  });
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    for (const line of result.messages) console.log(line);
+  }
+  if (!result.ok) process.exit(1);
+});
 program.command("doctor").description(
   "Run pre-flight checks: CLI config, endpoint reachability, API key shape, SDK install status, and (with --server) the same 4 dispatch-readiness checks shown in the Mushi console. Mirrors the in-console dispatch preflight so you can spot setup gaps before opening the admin UI."
 ).option("--cwd <path>", "Run package detection from a different directory").option("--json", "Machine-readable output").option(
   "--server",
   "Also call GET /preflight on the backend and include the 4 dispatch checks (GitHub repo, codebase indexed, Anthropic key, autofix enabled). Requires a configured projectId and API key."
+).option(
+  "--ingest",
+  "Also call GET /v1/sync/ingest-setup for the 4 required ingest steps (API key, SDK heartbeat, first report). Composable with --server."
+).option(
+  "--qa-stories",
+  "Check enabled QA stories for common setup issues: missing Firecrawl key, missing target URL, Slack not connected. Requires --server credentials."
 ).action(async (opts) => {
   const config = loadConfig();
-  const result = await runDoctor(config, { cwd: opts.cwd, server: opts.server });
+  const result = await runDoctor(config, { cwd: opts.cwd, server: opts.server, ingest: opts.ingest, qaStories: opts.qaStories });
   const { checks } = result;
   if (opts.json) {
     console.log(JSON.stringify({ checks, ready: result.ready }, null, 2));
@@ -2957,4 +3474,374 @@ keys.command("add").description("Add a new API key to the pool").requiredOption(
   }
   console.log(`\u2713 Key added \u2014 id: ${res.data.id}`);
 });
-program.parse();
+var integrations = program.command("integrations").description("Manage service integrations");
+integrations.command("list").description("List all configured integrations and their current health status").option("--json", "Machine-readable output").action(async (opts) => {
+  const config = loadConfig();
+  if (!config.apiKey) {
+    console.error("Run `mushi login` first");
+    process.exit(2);
+  }
+  if (!config.projectId) {
+    console.error("No projectId. Run `mushi config projectId <uuid>`");
+    process.exit(2);
+  }
+  const result = await apiCall(
+    `/v1/admin/projects/${config.projectId}/integrations`,
+    config
+  );
+  const rawResult = result;
+  if (!rawResult.integrations && !result.ok) {
+    console.error("Failed:", result.error);
+    process.exit(1);
+  }
+  if (opts.json) {
+    console.log(JSON.stringify(rawResult, null, 2));
+    return;
+  }
+  const rows = rawResult.integrations ?? [];
+  if (rows.length === 0) {
+    console.log("No integrations configured. Visit the Integrations page to connect services.");
+    return;
+  }
+  const icons = {
+    slack: "\u{1F514}",
+    github: "\u{1F419}",
+    sentry: "\u{1FAB2}",
+    langfuse: "\u{1F52D}",
+    discord: "\u{1F4AC}",
+    linear: "\u{1F4D0}",
+    jira: "\u{1F5C2}\uFE0F",
+    cursor_cloud: "\u{1F5B1}\uFE0F",
+    claude_code_agent: "\u{1F916}"
+  };
+  console.log("\nIntegrations:\n");
+  for (const row of rows) {
+    const icon = icons[row.kind] ?? "\u{1F50C}";
+    const statusIcon = row.status === "ok" ? "\u2705" : row.status === "error" ? "\u274C" : "\u26AA";
+    console.log(`  ${icon}  ${row.kind.padEnd(20)} ${statusIcon}  ${row.detail ?? ""}`);
+  }
+  console.log();
+});
+integrations.command("test <kind>").description(
+  "Run a health probe for a specific integration (e.g. slack, sentry, github, langfuse, discord, cursor_cloud, claude_code_agent)"
+).option("--json", "Machine-readable output").action(async (kind, opts) => {
+  const config = loadConfig();
+  if (!config.apiKey) {
+    console.error("Run `mushi login` first");
+    process.exit(2);
+  }
+  if (!config.projectId) {
+    console.error("No projectId. Run `mushi config projectId <uuid>`");
+    process.exit(2);
+  }
+  const result = await apiCall(
+    `/v1/admin/projects/${config.projectId}/integrations/probe/${kind}`,
+    config,
+    { method: "POST" }
+  );
+  if (!result.ok) {
+    console.error("Request failed:", result.error);
+    process.exit(1);
+  }
+  if (opts.json) {
+    console.log(JSON.stringify(result.data, null, 2));
+    return;
+  }
+  const probeOk = result.data?.status === "ok";
+  console.log(
+    probeOk ? `\u2705  ${kind} integration is healthy${result.data.detail ? ": " + result.data.detail : ""}` : `\u274C  ${kind} integration check failed${result.data.detail ? ": " + result.data.detail : ""}`
+  );
+  if (!probeOk) process.exit(1);
+});
+var slack = program.command("slack").description("Slack integration commands");
+slack.command("status").description("Show whether Slack is connected and which channel receives notifications").option("--json", "Machine-readable output").action(async (opts) => {
+  const config = loadConfig();
+  if (!config.apiKey) {
+    console.error("Run `mushi login` first");
+    process.exit(2);
+  }
+  if (!config.projectId) {
+    console.error("No projectId. Run `mushi config projectId <uuid>`");
+    process.exit(2);
+  }
+  const result = await apiCall(
+    `/v1/admin/projects/${config.projectId}/integrations/probe/slack`,
+    config,
+    { method: "POST" }
+  );
+  if (!result.ok) {
+    console.error("Request failed:", result.error);
+    process.exit(1);
+  }
+  if (opts.json) {
+    console.log(JSON.stringify(result.data, null, 2));
+    return;
+  }
+  if (result.data?.status === "ok") {
+    console.log("\u2705  Slack connected");
+    if (result.data.detail) console.log(`    ${result.data.detail}`);
+    console.log("\n    To change the channel or notification prefs, visit /integrations in the Mushi console.");
+  } else {
+    console.log("\u26AA  Slack not connected");
+    console.log('    Visit /integrations in the Mushi console and click "Add to Slack".');
+  }
+});
+slack.command("test").description("Send a test Slack notification to confirm the current channel is working").option("--json", "Machine-readable output").action(async (opts) => {
+  const config = loadConfig();
+  if (!config.apiKey) {
+    console.error("Run `mushi login` first");
+    process.exit(2);
+  }
+  if (!config.projectId) {
+    console.error("No projectId. Run `mushi config projectId <uuid>`");
+    process.exit(2);
+  }
+  const result = await apiCall(
+    `/v1/admin/projects/${config.projectId}/integrations/slack/test`,
+    config,
+    { method: "POST" }
+  );
+  if (!result.ok) {
+    console.error("Request failed:", result.error);
+    process.exit(1);
+  }
+  if (opts.json) {
+    console.log(JSON.stringify(result.data, null, 2));
+    return;
+  }
+  if (result.data?.ok) {
+    console.log("\u2705  Test message sent! Check your Slack channel.");
+  } else {
+    console.error("\u274C  Test failed:", result.data?.error ?? "unknown error");
+    process.exit(1);
+  }
+});
+var qa = program.command("qa").description("QA story management");
+qa.command("stories").description("List QA stories for the current project").option("--json", "Machine-readable output").option("-n, --limit <n>", "Max stories to return (not applied server-side; all stories returned)", "20").action(async (opts) => {
+  const config = loadConfig();
+  if (!config.apiKey) {
+    console.error("Run `mushi login` first");
+    process.exit(2);
+  }
+  if (!config.projectId) {
+    console.error("No projectId. Run `mushi config projectId <uuid>`");
+    process.exit(2);
+  }
+  const result = await apiCall(
+    `/v1/admin/projects/${config.projectId}/qa-coverage`,
+    config
+  );
+  if (!result.ok) {
+    console.error("Failed:", result.error);
+    process.exit(1);
+  }
+  if (opts.json) {
+    console.log(JSON.stringify(result.data, null, 2));
+    return;
+  }
+  const stories2 = result.data?.coverage ?? [];
+  if (stories2.length === 0) {
+    console.log("No QA stories yet. Create one at /qa-coverage in the Mushi console.");
+    return;
+  }
+  console.log(`
+QA Stories (${stories2.length}):
+`);
+  for (const s of stories2) {
+    const statusIcon = s.last_run_status === "passed" ? "\u2705" : s.last_run_status === "failed" ? "\u274C" : s.last_run_status === "error" ? "\u{1F6A8}" : "\u26AA";
+    const enabled = s.enabled ? "" : " [disabled]";
+    const sid = s.story_id ?? s.id ?? "\u2014";
+    console.log(`  ${statusIcon}  ${s.name.slice(0, 50).padEnd(52)}  ${sid}${enabled}`);
+  }
+  console.log(`
+   Use 'mushi qa runs <storyId>' to see recent runs for a story.`);
+  console.log();
+});
+qa.command("runs <storyId>").description("Show recent runs for a QA story, including error heads").option("--json", "Machine-readable output").option("-n, --limit <n>", "Max runs to return", "10").action(async (storyId, opts) => {
+  const config = loadConfig();
+  if (!config.apiKey) {
+    console.error("Run `mushi login` first");
+    process.exit(2);
+  }
+  if (!config.projectId) {
+    console.error("No projectId. Run `mushi config projectId <uuid>`");
+    process.exit(2);
+  }
+  const limit = parseInt(opts.limit ?? "10", 10);
+  const result = await apiCall(
+    `/v1/admin/projects/${config.projectId}/qa-stories/${storyId}/runs?limit=${limit}`,
+    config
+  );
+  if (!result.ok) {
+    console.error("Failed:", result.error);
+    process.exit(1);
+  }
+  if (opts.json) {
+    console.log(JSON.stringify(result.data, null, 2));
+    return;
+  }
+  const runs = result.data?.runs ?? [];
+  if (runs.length === 0) {
+    console.log("No runs yet for this story. Trigger one with `mushi qa run <storyId>`.");
+    return;
+  }
+  console.log(`
+Recent runs for story ${storyId.slice(0, 8)}\u2026:
+`);
+  for (const r of runs) {
+    const statusIcon = r.status === "passed" ? "\u2705" : r.status === "failed" ? "\u274C" : r.status === "error" ? "\u{1F6A8}" : "\u23F3";
+    const ts = r.created_at ? new Date(r.created_at).toISOString().slice(0, 16).replace("T", " ") : "\u2014";
+    const latency = r.latency_ms ? ` (${(r.latency_ms / 1e3).toFixed(1)}s)` : "";
+    console.log(`  ${statusIcon}  ${ts}${latency}  ${r.id.slice(0, 8)}`);
+    if (r.error_message) {
+      console.log(`       Error: ${r.error_message.slice(0, 120)}`);
+    }
+    if (r.assertion_failures?.length) {
+      for (const af of r.assertion_failures.slice(0, 3)) {
+        console.log(`       \xB7 ${String(af).slice(0, 100)}`);
+      }
+    }
+  }
+  const consoleUrl = config.consoleUrl ?? "https://app.mushi.ai";
+  console.log(`
+   Open in console: ${consoleUrl}/qa-coverage?story=${storyId}`);
+  console.log(`   Tip: run 'mushi config consoleUrl http://localhost:6464' to set your local console URL`);
+  console.log();
+});
+qa.command("run <storyId>").description("Manually trigger a QA story run (fire-and-forget; check results with `mushi qa runs <id>`)").option("--json", "Machine-readable output").action(async (storyId, opts) => {
+  const config = loadConfig();
+  if (!config.apiKey) {
+    console.error("Run `mushi login` first");
+    process.exit(2);
+  }
+  if (!config.projectId) {
+    console.error("No projectId. Run `mushi config projectId <uuid>`");
+    process.exit(2);
+  }
+  const result = await apiCall(
+    `/v1/admin/projects/${config.projectId}/qa-stories/${storyId}/run`,
+    config,
+    { method: "POST" }
+  );
+  if (!result.ok) {
+    console.error("Failed:", result.error);
+    process.exit(1);
+  }
+  if (opts.json) {
+    console.log(JSON.stringify(result.data, null, 2));
+    return;
+  }
+  const runId = result.data?.run_id;
+  if (runId) {
+    console.log(`\u25B6  Run triggered: ${runId.slice(0, 8)}\u2026`);
+    console.log(`   Check results: mushi qa runs ${storyId}`);
+  } else {
+    console.error("\u274C  Trigger failed: no run_id in response", JSON.stringify(result.data));
+    process.exit(1);
+  }
+});
+program.command("audit").description("Run a full-stack health audit for the current project").option("--json", "Machine-readable JSON output").option("--project-id <id>", "Project ID to audit (defaults to MUSHI_PROJECT_ID from config)").addHelpText("after", `
+Description:
+  Fans out to the Mushi backend to run a full-stack health audit:
+    \u2022 DB schema + Supabase advisors (requires Supabase PAT in API Keys)
+    \u2022 Recent backend error logs
+    \u2022 Tables without RLS enabled
+    \u2022 Gate results: API contract (G3), spec drift (G6), orphan endpoints (G7),
+      unknown frontend calls (G8), schema drift, status claim (G5)
+
+  Returns a PM-readable scorecard with severity-ranked findings.
+
+  Prerequisites:
+    1. Configure your Supabase PAT: mushi settings set supabase-pat <token>
+    2. Set supabase_project_ref in Admin \u2192 Settings \u2192 Project.
+
+Examples:
+  mushi audit
+  mushi audit --json
+  mushi audit --project-id abc123`).action(async (opts) => {
+  const config = requireConfig();
+  const projectId = opts.projectId ?? config.projectId;
+  if (!projectId) {
+    process.stderr.write("error: project ID required. Run `mushi login` or pass --project-id\n");
+    process.exit(1);
+  }
+  const headers = {
+    "Content-Type": "application/json",
+    "X-Mushi-Project-Id": projectId
+  };
+  const jwt = config.jwt ?? null;
+  const apiKey = config.apiKey ?? null;
+  if (jwt) {
+    headers["Authorization"] = `Bearer ${jwt}`;
+  } else if (apiKey) {
+    headers["X-Mushi-Api-Key"] = apiKey;
+  } else {
+    process.stderr.write("error: no credentials found. Run `mushi login` first.\n");
+    process.exit(1);
+  }
+  if (!opts.json) process.stdout.write("Running full-stack audit\u2026 ");
+  try {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 3e4);
+    const res = await fetch(
+      `${config.endpoint}/v1/admin/projects/${projectId}/audit`,
+      { method: "POST", headers, body: "{}", signal: controller.signal }
+    );
+    clearTimeout(timer);
+    const body = await res.json();
+    if (!res.ok || !body.ok) {
+      if (opts.json) {
+        console.log(JSON.stringify(body));
+        process.exit(1);
+      }
+      process.stdout.write("FAIL\n");
+      process.stderr.write(`error: ${body.error?.message ?? `HTTP ${res.status}`}
+`);
+      process.exit(1);
+    }
+    if (opts.json) {
+      console.log(JSON.stringify(body.data, null, 2));
+      return;
+    }
+    const data = body.data;
+    const overallGlyph = data.summary.overall === "fail" ? "\u274C" : data.summary.overall === "warn" ? "\u26A0\uFE0F " : "\u2705";
+    process.stdout.write(`${overallGlyph}
+
+`);
+    console.log(`Full-Stack Audit \u2014 ${new Date(data.audit_at).toLocaleString()}`);
+    console.log(`Backend linked: ${data.backend_linked ? "yes" : "no (configure Supabase PAT + project ref)"}`);
+    console.log(`Summary: ${data.summary.error_count} error(s) \xB7 ${data.summary.warn_count} warning(s)
+`);
+    if (data.findings.length === 0) {
+      console.log("  \u2713 No findings. Your project looks healthy.");
+    } else {
+      for (const f of data.findings) {
+        const icon = f.severity === "error" ? "\u{1F534}" : f.severity === "warn" ? "\u{1F7E1}" : "\u2139\uFE0F ";
+        console.log(`  ${icon} ${f.title}`);
+        console.log(`     ${f.detail.slice(0, 120)}${f.detail.length > 120 ? "\u2026" : ""}`);
+      }
+    }
+    if (data.gate_runs.length > 0) {
+      console.log("\nGate Results:");
+      for (const run of data.gate_runs) {
+        const g = run.status === "pass" ? "\u2713" : run.status === "fail" ? "\u2717" : "~";
+        console.log(`  ${g} ${run.gate.padEnd(22)} ${run.status}  (${run.findings_count} finding${run.findings_count !== 1 ? "s" : ""})`);
+      }
+    }
+    if (data.summary.overall === "fail") process.exit(1);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (opts.json) {
+      console.log(JSON.stringify({ ok: false, error: msg }));
+    } else {
+      process.stdout.write("ERROR\n");
+      process.stderr.write(`error: ${msg}
+`);
+    }
+    process.exit(1);
+  }
+});
+program.parseAsync().catch((err) => {
+  console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+  process.exit(1);
+});