@carrierllc/mcp 0.2.17 → 0.2.19

package/dist/cli.js

@@ -2,8 +2,8 @@
 
 // src/cli/index.ts
 import { Command } from "commander";
-import * as p from "@clack/prompts";
-import pc from "picocolors";
+import * as p2 from "@clack/prompts";
+import pc3 from "picocolors";
 import { resolve as resolve2 } from "path";
 
 // src/cli/lib/brand.ts
@@ -224,12 +224,12 @@ async function replaceInTree(dir, subs) {
   }
   return touched;
 }
-async function exists(p2) {
-  return existsSync2(p2);
+async function exists(p3) {
+  return existsSync2(p3);
 }
-async function isDir(p2) {
+async function isDir(p3) {
   try {
-    return (await stat(p2)).isDirectory();
+    return (await stat(p3)).isDirectory();
   } catch {
     return false;
   }
@@ -242,10 +242,37 @@ function run(cmd, args, opts = {}) {
     const child = spawn(cmd, args, { cwd: opts.cwd, shell: false });
     let stdout = "";
     let stderr = "";
+    let settled = false;
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      resolve3(result);
+    };
+    let timer;
+    if (opts.timeoutMs && opts.timeoutMs > 0) {
+      timer = setTimeout(() => {
+        try {
+          child.kill("SIGTERM");
+        } catch {
+        }
+        finish({
+          ok: false,
+          code: null,
+          stdout,
+          stderr: stderr || `timeout after ${opts.timeoutMs}ms`
+        });
+      }, opts.timeoutMs);
+    }
     child.stdout?.on("data", (d) => stdout += d.toString());
     child.stderr?.on("data", (d) => stderr += d.toString());
-    child.on("error", () => resolve3({ ok: false, code: null, stdout, stderr }));
-    child.on("close", (code) => resolve3({ ok: code === 0, code, stdout, stderr }));
+    child.on("error", () => {
+      if (timer) clearTimeout(timer);
+      finish({ ok: false, code: null, stdout, stderr });
+    });
+    child.on("close", (code) => {
+      if (timer) clearTimeout(timer);
+      finish({ ok: code === 0, code, stdout, stderr });
+    });
   });
 }
 function runInherit(cmd, args, opts = {}) {
@@ -261,9 +288,41 @@ async function which(bin) {
   return r.ok && r.stdout.trim().length > 0;
 }
 
+// src/cli/lib/urls.ts
+import { spawn as spawn2 } from "child_process";
+var MCP_URL = "https://mcp.carrier.llc/mcp";
+var MCP_HOME = "https://mcp.carrier.llc";
+var SIGN_UP_URL = "https://accounts.carrier.llc/sign-up";
+var SIGN_IN_URL = "https://accounts.carrier.llc/sign-in";
+var CONSOLE_URL = "https://app.carrier.llc";
+var ONBOARDING_URL = "https://app.carrier.llc/onboarding";
+async function openUrl(url) {
+  const platform = process.platform;
+  if (platform === "darwin") {
+    const r = await run("open", [url]);
+    return r.ok ? { ok: true, hint: `Opened ${url}` } : { ok: false, hint: `Could not open browser. Visit:
+  ${url}` };
+  }
+  if (platform === "win32") {
+    const r = await run("cmd", ["/c", "start", "", url]);
+    return r.ok ? { ok: true, hint: `Opened ${url}` } : { ok: false, hint: `Could not open browser. Visit:
+  ${url}` };
+  }
+  for (const bin of ["xdg-open", "open"]) {
+    const r = await run(bin, [url]);
+    if (r.ok) return { ok: true, hint: `Opened ${url}` };
+  }
+  try {
+    spawn2("xdg-open", [url], { detached: true, stdio: "ignore" }).unref();
+    return { ok: true, hint: `Launched browser for ${url}` };
+  } catch {
+    return { ok: false, hint: `Could not open browser. Visit:
+  ${url}` };
+  }
+}
+
 // src/cli/lib/plugin.ts
 var MCP_NAME = "carrier";
-var MCP_URL = "https://mcp.carrier.llc/mcp";
 async function installPlugin() {
   const marketplace = pluginSourceDir();
   const pluginRoot = pluginManifestDir();
@@ -311,6 +370,15 @@ function manualCommands() {
     `claude mcp add --transport http ${MCP_NAME} ${MCP_URL}`
   ];
 }
+function installAuthGuidance() {
+  return [
+    `MCP URL (zero credentials): ${MCP_URL}`,
+    "OAuth on first use: when Claude first calls Carrier, your browser opens",
+    "  Clerk sign-in / sign-up (Google, GitHub, or email). No API token to paste.",
+    "Stuck on auth?  claude mcp auth carrier",
+    "Headless/CI only: org API key (ak_\u2026) from https://app.carrier.llc \u2192 Settings \u2192 API Keys"
+  ];
+}
 
 // src/cli/lib/whitelabel.ts
 import { join as join4 } from "path";
@@ -440,42 +508,534 @@ async function deploySite(target, brand) {
   return r.ok ? { ok: true, projectName } : { ok: false, projectName, reason: "wrangler deploy failed \u2014 run `wrangler login` then retry `carrier site deploy`." };
 }
 
+// src/cli/lib/status.ts
+import { homedir as homedir2 } from "os";
+import { join as join6 } from "path";
+function detectEnvToken() {
+  const api = process.env.CARRIER_API_KEY?.trim() || process.env.CARRIER_ORG_API_KEY?.trim() || "";
+  if (api.startsWith("ak_") || api.length > 0) {
+    return { present: true, kind: "api-key" };
+  }
+  const ocs = process.env.ESIMVAULT_API_TOKEN?.trim() || process.env.CARRIER_OCS_API_TOKEN?.trim() || "";
+  if (ocs) return { present: true, kind: "ocs-token" };
+  return { present: false, kind: "none" };
+}
+function rankHit(name, url) {
+  let rank = 0;
+  if (name.toLowerCase() === MCP_NAME) rank += 100;
+  else if (/^carrier[-_]?/i.test(name) && !/test|staging|stg|dev|local/i.test(name)) rank += 40;
+  else if (/carrier/i.test(name) && !/test|staging|stg|dev|local/i.test(name)) rank += 20;
+  else if (/carrier/i.test(name)) rank += 5;
+  if (url === MCP_URL || url.includes("https://mcp.carrier.llc/mcp")) rank += 50;
+  else if (/mcp\.carrier\.llc/i.test(url)) rank += 25;
+  return rank;
+}
+function scanMcpServers(servers) {
+  if (!servers || typeof servers !== "object") return null;
+  let best = null;
+  for (const [name, entry] of Object.entries(servers)) {
+    if (!/carrier/i.test(name) && !(typeof entry?.url === "string" && /carrier\.llc/i.test(entry.url))) {
+      continue;
+    }
+    const url = typeof entry?.url === "string" ? entry.url : "";
+    const rank = rankHit(name, url);
+    if (rank < 20 && !url.includes("mcp.carrier.llc")) {
+      continue;
+    }
+    const urlMatches = url === MCP_URL || url.includes("https://mcp.carrier.llc/mcp");
+    const hit = {
+      registered: true,
+      urlMatches,
+      detail: url ? `${name}: ${url}` : `${name}: ${entry?.command ?? "configured"}`,
+      rank
+    };
+    if (!best || hit.rank > best.rank) best = hit;
+  }
+  return best;
+}
+async function probeMcpFromConfig() {
+  const candidates = [
+    join6(homedir2(), ".claude.json"),
+    join6(claudeHome(), "settings.json"),
+    join6(claudeHome(), ".mcp.json"),
+    join6(process.cwd(), ".mcp.json")
+  ];
+  let best = null;
+  let configSeen = false;
+  for (const file of candidates) {
+    if (!await exists(file)) continue;
+    try {
+      const json = JSON.parse(await readFile(file, "utf8"));
+      configSeen = true;
+      const direct = scanMcpServers(json.mcpServers);
+      if (direct && (!best || direct.rank > best.rank)) best = direct;
+      if (json.projects) {
+        for (const proj of Object.values(json.projects)) {
+          const hit = scanMcpServers(proj?.mcpServers);
+          if (hit && (!best || hit.rank > best.rank)) best = hit;
+        }
+      }
+    } catch {
+    }
+  }
+  if (!best) return { hit: null, configSeen };
+  return {
+    hit: { registered: best.registered, urlMatches: best.urlMatches, detail: best.detail },
+    configSeen
+  };
+}
+async function probeMcpRegistration() {
+  const { hit, configSeen } = await probeMcpFromConfig();
+  if (hit) return hit;
+  if (configSeen) {
+    return {
+      registered: false,
+      urlMatches: false,
+      detail: "carrier not registered (no production MCP URL in Claude config)"
+    };
+  }
+  const claudeFound = await which("claude");
+  if (!claudeFound) {
+    return {
+      registered: false,
+      urlMatches: false,
+      detail: "claude CLI not on PATH"
+    };
+  }
+  const r = await run("claude", ["mcp", "list"], { timeoutMs: 5e3 });
+  const out = `${r.stdout}
+${r.stderr}`;
+  if (!r.ok && !out.trim()) {
+    return { registered: false, urlMatches: false, detail: "claude mcp list failed or timed out" };
+  }
+  if (/timeout after/i.test(r.stderr) && !/carrier/i.test(out)) {
+    return {
+      registered: false,
+      urlMatches: false,
+      detail: "claude mcp list timed out \u2014 run `claude mcp list` manually"
+    };
+  }
+  const lines = out.split("\n").map((l) => l.trim()).filter(Boolean);
+  const carrierLine = lines.find((l) => new RegExp(`^${MCP_NAME}\\s*:`, "i").test(l)) ?? lines.find((l) => /carrier/i.test(l) && /mcp\.carrier\.llc/i.test(l));
+  if (!carrierLine) {
+    return { registered: false, urlMatches: false, detail: "carrier not in claude mcp list" };
+  }
+  const urlMatches = carrierLine.includes(MCP_URL) || /mcp\.carrier\.llc\/mcp/i.test(carrierLine);
+  return { registered: true, urlMatches, detail: carrierLine.slice(0, 200) };
+}
+function buildNextSteps(s) {
+  const steps = [];
+  if (!s.claudeFound) {
+    steps.push("Install Claude Code (https://claude.ai/code), then re-run: carrier plugin install");
+  } else if (!s.pluginInstalled) {
+    steps.push("Install the Carrier plugin: carrier plugin install");
+  } else if (!s.mcpRegistered) {
+    steps.push(`Register the zero-cred MCP URL: claude mcp add --transport http ${MCP_NAME} ${MCP_URL}`);
+  } else if (!s.mcpUrlMatches) {
+    steps.push(`Update MCP to production URL: claude mcp add --transport http ${MCP_NAME} ${MCP_URL}`);
+  }
+  if (s.mcpRegistered || s.pluginInstalled) {
+    steps.push(
+      "Talk to your fleet in Claude \u2014 first tool call opens Clerk OAuth (Google / GitHub / email). No API token needed."
+    );
+  } else {
+    steps.push("Create a free account (browser): carrier open signup");
+    steps.push("Or sign in: carrier open signin");
+  }
+  if (!s.tokenPresent) {
+    steps.push(
+      "Optional headless key: Console \u2192 Settings \u2192 API Keys (ak_\u2026) then export CARRIER_API_KEY=ak_\u2026 for `carrier ask`."
+    );
+  } else {
+    steps.push('Try a natural-language fleet query: carrier ask "show fleet health"');
+  }
+  steps.push("Scaffold a white-label storefront anytime: carrier site create");
+  return steps;
+}
+async function gatherStatus() {
+  const [plugin2, mcp, claudeFound] = await Promise.all([
+    pluginStatus(),
+    probeMcpRegistration(),
+    which("claude")
+  ]);
+  const token = detectEnvToken();
+  let authMode = "none";
+  if (token.kind === "api-key") authMode = "api-key";
+  else if (token.kind === "ocs-token") authMode = "ocs-token";
+  else if (mcp.registered || plugin2.installed) authMode = "oauth-first-use";
+  const base = {
+    pluginInstalled: plugin2.installed,
+    pluginVersion: plugin2.version,
+    pluginDir: plugin2.dir,
+    claudeFound,
+    mcpRegistered: mcp.registered,
+    mcpUrlMatches: mcp.urlMatches,
+    mcpDetail: mcp.detail,
+    tokenPresent: token.present,
+    tokenKind: token.kind,
+    authMode
+  };
+  return { ...base, nextSteps: buildNextSteps(base) };
+}
+function resolveCliToken() {
+  const api = process.env.CARRIER_API_KEY?.trim() || process.env.CARRIER_ORG_API_KEY?.trim() || "";
+  if (api) return api;
+  const ocs = process.env.ESIMVAULT_API_TOKEN?.trim() || process.env.CARRIER_OCS_API_TOKEN?.trim() || "";
+  return ocs || null;
+}
+
+// src/cli/lib/guidance.ts
+import pc from "picocolors";
+var FLEET_NL_EXAMPLES = [
+  { label: "Fleet health", prompt: "Show my fleet health \u2014 accounts, eSIMs, low-balance alerts" },
+  { label: "Subscriber lookup", prompt: "Look up subscriber ICCID 8944\u2026 and diagnose connectivity" },
+  { label: "Usage anomalies", prompt: "Detect usage anomalies and burn-rate risks this week" },
+  { label: "Issue from inventory", prompt: "Issue 3 free eSIMs from inventory on my account and assign the starter package" },
+  { label: "Billing check", prompt: "What's my platform credit balance and Stripe Connect payout status?" },
+  { label: "Wallet balance", prompt: "What's my managed prepaid wallet balance and auto-top-up status?" },
+  { label: "Churn risk", prompt: "List high churn-risk subscribers with retention ideas" }
+];
+function oauthFirstUseNote() {
+  return [
+    "Entry A \u2014 zero credentials up front",
+    `  MCP URL:  ${MCP_URL}`,
+    "  Auth:     OAuth on first use (Clerk \u2014 Google, GitHub, or email)",
+    "  Token:    none required in Claude / Cursor / Windsurf",
+    "",
+    "When you first talk to Carrier in your MCP client, the browser opens",
+    "sign-in/sign-up. After authorize, tools work. Headless? Use an org API key",
+    `(ak_\u2026) from ${CONSOLE_URL} \u2192 Settings \u2192 API Keys.`
+  ].join("\n");
+}
+function formatStatusBlock(st) {
+  const yn = (ok2, yes = "yes", no = "no") => ok2 ? pc.green(yes) : pc.yellow(no);
+  const authLabel = st.authMode === "oauth-first-use" ? pc.cyan("OAuth on first use (no token needed)") : st.authMode === "api-key" ? pc.green("org API key in env (CARRIER_API_KEY)") : st.authMode === "ocs-token" ? pc.green("OCS token in env") : pc.yellow("not ready \u2014 install MCP or open sign-up");
+  return [
+    `Claude Code:   ${yn(st.claudeFound, "found", "not on PATH")}`,
+    `Plugin:        ${st.pluginInstalled ? pc.green(`installed v${st.pluginVersion ?? "?"}`) : pc.yellow("not installed")}`,
+    `MCP registered:${st.mcpRegistered ? pc.green(" yes") : pc.yellow(" no")}${st.mcpDetail ? pc.dim(`  (${st.mcpDetail})`) : ""}`,
+    `MCP URL:       ${st.mcpUrlMatches ? pc.green(MCP_URL) : pc.yellow("not production / missing")}`,
+    `Auth path:     ${authLabel}`,
+    `Headless token:${st.tokenPresent ? pc.green(` ${st.tokenKind}`) : pc.dim(" none (optional)")}`
+  ].join("\n");
+}
+function formatNextSteps(st) {
+  return st.nextSteps.map((s, i) => `  ${i + 1}. ${s}`).join("\n");
+}
+function formatNlExamples() {
+  return FLEET_NL_EXAMPLES.map((e) => `  \u2022 ${pc.bold(e.label)}: "${e.prompt}"`).join("\n");
+}
+function accountLinksNote() {
+  return [
+    `Sign up:     ${SIGN_UP_URL}`,
+    `Sign in:     ${SIGN_IN_URL}`,
+    `Console:     ${CONSOLE_URL}`,
+    `Onboarding:  ${ONBOARDING_URL}`,
+    `MCP home:    https://mcp.carrier.llc`
+  ].join("\n");
+}
+function withNextStep(errorMsg, next) {
+  return [errorMsg, "", "What to do next:", ...next.map((s) => `  \u2192 ${s}`)].join("\n");
+}
+
+// src/cli/lib/home.ts
+import * as p from "@clack/prompts";
+import pc2 from "picocolors";
+
+// src/cli/lib/ask.ts
+function parseRpcBody(raw) {
+  const trimmed = raw.trim();
+  if (!trimmed) return {};
+  if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+    return JSON.parse(trimmed);
+  }
+  const dataLine = trimmed.split("\n").map((l) => l.trim()).find((l) => l.startsWith("data:"));
+  if (!dataLine) return {};
+  return JSON.parse(dataLine.slice(5).trim());
+}
+async function carrierAsk(intent) {
+  const token = resolveCliToken();
+  if (!token) {
+    return {
+      ok: false,
+      text: withNextStep("No headless token in the environment.", [
+        "Interactive path: open Claude and say your intent \u2014 OAuth runs on first use.",
+        "Or export CARRIER_API_KEY=ak_\u2026 from Console \u2192 Settings \u2192 API Keys.",
+        'Then retry: carrier ask "show fleet health"'
+      ])
+    };
+  }
+  const headers = {
+    Authorization: `Bearer ${token}`,
+    "Content-Type": "application/json",
+    Accept: "application/json, text/event-stream"
+  };
+  try {
+    const initRes = await fetch(MCP_URL, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "initialize",
+        params: {
+          protocolVersion: "2024-11-05",
+          capabilities: {},
+          clientInfo: { name: "carrier-cli", version: "0.2.19" }
+        }
+      })
+    });
+    if (initRes.status === 401 || initRes.status === 403) {
+      return {
+        ok: false,
+        text: withNextStep(`MCP returned ${initRes.status} (auth rejected).`, [
+          "Confirm CARRIER_API_KEY is a valid org key (ak_\u2026) from app.carrier.llc",
+          "Or complete OCS onboarding: https://app.carrier.llc/onboarding",
+          "Interactive: use Claude + OAuth instead of a headless key"
+        ])
+      };
+    }
+    const sessionId = initRes.headers.get("mcp-session-id") ?? initRes.headers.get("Mcp-Session-Id");
+    await initRes.arrayBuffer().catch(() => void 0);
+    if (!sessionId) {
+      return {
+        ok: false,
+        text: withNextStep("MCP initialize did not return a session id.", [
+          "Check network access to https://mcp.carrier.llc/mcp",
+          "Retry later, or use Claude with the registered MCP (OAuth path)"
+        ])
+      };
+    }
+    const sessionHeaders = { ...headers, "Mcp-Session-Id": sessionId };
+    await fetch(MCP_URL, {
+      method: "POST",
+      headers: sessionHeaders,
+      body: JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" })
+    }).catch(() => void 0);
+    const res = await fetch(MCP_URL, {
+      method: "POST",
+      headers: sessionHeaders,
+      body: JSON.stringify({
+        jsonrpc: "2.0",
+        id: 2,
+        method: "tools/call",
+        params: { name: "carrier_ask", arguments: { intent } }
+      })
+    });
+    if (!res.ok) {
+      const snippet = (await res.text().catch(() => "")).slice(0, 240);
+      return {
+        ok: false,
+        text: withNextStep(`MCP call failed (${res.status}). ${snippet}`, [
+          "Check network access to https://mcp.carrier.llc/mcp",
+          "Retry later, or use Claude with the registered MCP (OAuth path)"
+        ])
+      };
+    }
+    const json = parseRpcBody(await res.text());
+    if (json.error?.message) {
+      return {
+        ok: false,
+        text: withNextStep(json.error.message, [
+          "Rephrase the intent more specifically (include ICCID / MSISDN if relevant)",
+          "Or open Claude and ask there with full tool routing"
+        ])
+      };
+    }
+    const parts = json.result?.content ?? [];
+    const text3 = parts.map((p3) => p3.text).filter(Boolean).join("\n").trim() || JSON.stringify(json.result ?? json, null, 2);
+    return { ok: !json.result?.isError, text: text3 };
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    return {
+      ok: false,
+      text: withNextStep(`Could not reach MCP: ${msg}`, [
+        "Verify outbound HTTPS to mcp.carrier.llc",
+        "Use the interactive Claude path while offline from this machine"
+      ])
+    };
+  }
+}
+
+// src/cli/lib/home.ts
+function mark(ok2) {
+  return ok2 ? pc2.green("\u25CF") : pc2.yellow("\u25CB");
+}
+function printStatus(st) {
+  p.note(formatStatusBlock(st), "Status");
+  p.note(formatNextSteps(st), "Next steps");
+}
+async function showHomeStatus() {
+  const s = p.spinner();
+  s.start("Checking Claude plugin + MCP registration");
+  const st = await gatherStatus();
+  s.stop("Status ready");
+  printStatus(st);
+  return st;
+}
+async function openAndReport(url, label) {
+  const r = await openUrl(url);
+  if (r.ok) p.log.success(r.hint);
+  else {
+    p.log.warn(r.hint);
+    p.note(url, label);
+  }
+}
+async function runHome(opts) {
+  let st = await showHomeStatus();
+  p.note(oauthFirstUseNote(), "How auth works");
+  for (; ; ) {
+    const hasToken = !!resolveCliToken();
+    const choice = await p.select({
+      message: "What do you want to do?",
+      options: [
+        {
+          value: "refresh",
+          label: `${mark(st.mcpRegistered && st.pluginInstalled)} Refresh status`,
+          hint: "Re-check plugin + MCP"
+        },
+        {
+          value: "install",
+          label: `${mark(st.pluginInstalled && st.mcpRegistered)} Install / re-register plugin + MCP`,
+          hint: "Zero-cred URL \xB7 OAuth on first use"
+        },
+        {
+          value: "signup",
+          label: "Open sign-up",
+          hint: "Create a Carrier account (Google / GitHub / email)"
+        },
+        {
+          value: "signin",
+          label: "Open sign-in",
+          hint: "Existing account"
+        },
+        {
+          value: "console",
+          label: "Open console",
+          hint: CONSOLE_URL
+        },
+        {
+          value: "onboarding",
+          label: "Open onboarding (link OCS / managed setup)",
+          hint: ONBOARDING_URL
+        },
+        {
+          value: "ask",
+          label: hasToken ? "Ask the fleet (carrier ask)" : "Ask the fleet (needs CARRIER_API_KEY)",
+          hint: hasToken ? "Uses env token" : "Optional headless path"
+        },
+        {
+          value: "site",
+          label: "Scaffold white-label storefront",
+          hint: "carrier site create"
+        },
+        { value: "exit", label: "Exit" }
+      ]
+    });
+    if (p.isCancel(choice) || choice === "exit") {
+      p.outro(pc2.dim("Run `carrier` anytime for this menu. Talk to your fleet in Claude."));
+      return;
+    }
+    switch (choice) {
+      case "refresh":
+        st = await showHomeStatus();
+        break;
+      case "install":
+        await opts.onInstall();
+        p.note(oauthFirstUseNote(), "OAuth on first use");
+        st = await showHomeStatus();
+        break;
+      case "signup":
+        await openAndReport(SIGN_UP_URL, "Sign-up URL");
+        p.log.info("After sign-up, return here or open Claude and talk to Carrier \u2014 OAuth may already be done.");
+        break;
+      case "signin":
+        await openAndReport(SIGN_IN_URL, "Sign-in URL");
+        break;
+      case "console":
+        await openAndReport(CONSOLE_URL, "Console");
+        break;
+      case "onboarding":
+        await openAndReport(ONBOARDING_URL, "Onboarding");
+        p.log.info("Link OCS credentials (BYO) or finish managed setup, then use Claude MCP.");
+        break;
+      case "ask": {
+        if (!resolveCliToken()) {
+          p.log.warn("No CARRIER_API_KEY / OCS token in env.");
+          p.note(
+            [
+              "Interactive (recommended): install MCP, open Claude, ask in plain English.",
+              "Headless: Console \u2192 Settings \u2192 API Keys \u2192 export CARRIER_API_KEY=ak_\u2026",
+              "",
+              "Example prompts:",
+              ...FLEET_NL_EXAMPLES.slice(0, 3).map((e) => `  carrier ask "${e.prompt}"`)
+            ].join("\n"),
+            "How to ask"
+          );
+          break;
+        }
+        const intent = await p.text({
+          message: "What should Carrier do?",
+          placeholder: "show fleet health"
+        });
+        if (p.isCancel(intent) || !String(intent).trim()) break;
+        const spin = p.spinner();
+        spin.start("Asking Carrier MCP\u2026");
+        const result = await carrierAsk(String(intent).trim());
+        spin.stop(result.ok ? "Answer" : "Could not complete ask");
+        if (result.ok) p.note(result.text.slice(0, 4e3), "carrier ask");
+        else p.log.error(result.text);
+        break;
+      }
+      case "site":
+        await opts.onSiteCreate();
+        return;
+      default:
+        break;
+    }
+  }
+}
+
 // src/cli/index.ts
-var VERSION = "0.2.17";
+var VERSION = "0.2.19";
 function header() {
-  p.intro(`${pc.bold(pc.yellow("\u25C6 carrier"))} ${pc.dim("\xB7 the Stripe of telecom \u2014 CLI v" + VERSION)}`);
+  p2.intro(`${pc3.bold(pc3.yellow("\u25C6 carrier"))} ${pc3.dim("\xB7 the Stripe of telecom \u2014 CLI v" + VERSION)}`);
 }
 function ok(msg) {
-  p.log.success(pc.green(msg));
+  p2.log.success(pc3.green(msg));
 }
 function info(msg) {
-  p.log.info(msg);
+  p2.log.info(msg);
+}
+function fail(msg, next) {
+  p2.log.error(msg);
+  p2.note(next.map((s) => `\u2192 ${s}`).join("\n"), "What to do next");
 }
 async function promptBrand(seed) {
-  const name = await p.text({
+  const name = await p2.text({
     message: "Brand name",
     placeholder: seed.name,
     defaultValue: seed.name
   });
-  if (p.isCancel(name)) process.exit(0);
-  const domain = await p.text({
+  if (p2.isCancel(name)) process.exit(0);
+  const domain = await p2.text({
     message: "Domain",
     placeholder: seed.domain,
     defaultValue: seed.domain
   });
-  if (p.isCancel(domain)) process.exit(0);
-  const accent = await p.text({
+  if (p2.isCancel(domain)) process.exit(0);
+  const accent = await p2.text({
     message: "Accent color (hex)",
     placeholder: seed.colors.accent,
     defaultValue: seed.colors.accent
   });
-  if (p.isCancel(accent)) process.exit(0);
-  const supportEmail = await p.text({
+  if (p2.isCancel(accent)) process.exit(0);
+  const supportEmail = await p2.text({
     message: "Support email",
     placeholder: `support@${domain}`,
     defaultValue: `support@${domain}`
   });
-  if (p.isCancel(supportEmail)) process.exit(0);
+  if (p2.isCancel(supportEmail)) process.exit(0);
   const accentDark = deriveAccentDark(accent, seed);
   const isCarrier = name === CARRIER_BRAND.name && domain === CARRIER_BRAND.domain;
   return {
@@ -492,69 +1052,183 @@ async function promptBrand(seed) {
   };
 }
 async function doPluginInstall() {
-  const s = p.spinner();
-  s.start("Installing Carrier Claude Code plugin");
-  const r = await installPlugin();
+  const s = p2.spinner();
+  s.start("Installing Carrier Claude Code plugin + zero-cred MCP");
+  let r;
+  try {
+    r = await installPlugin();
+  } catch (e) {
+    s.stop("Install failed");
+    fail(String(e instanceof Error ? e.message : e), [
+      "Reinstall the package: npm i -g @carrierllc/mcp  (or npx @carrierllc/mcp)",
+      "Or finish manually with the commands under `carrier plugin install` help",
+      `Sign up anytime: ${SIGN_UP_URL}`
+    ]);
+    return;
+  }
   s.stop("Plugin staged");
   ok(`Plugin \u2192 ${r.copiedTo}`);
   info(
-    `MCP: ${r.mcpAdded ? pc.green("registered") : pc.yellow("manual")}  \xB7  marketplace: ${r.marketplaceAdded ? pc.green("added") : pc.yellow("manual")}  \xB7  install: ${r.pluginInstalled ? pc.green("done") : pc.yellow("manual")}`
+    `MCP: ${r.mcpAdded ? pc3.green("registered") : pc3.yellow("manual")}  \xB7  marketplace: ${r.marketplaceAdded ? pc3.green("added") : pc3.yellow("manual")}  \xB7  install: ${r.pluginInstalled ? pc3.green("done") : pc3.yellow("manual")}`
   );
+  p2.note(installAuthGuidance().join("\n"), "OAuth on first use (Entry A)");
   if (!r.claudeFound || r.notes.length) {
-    p.note(manualCommands().join("\n"), "Finish wiring (run in your terminal)");
-    if (r.notes.length) info(pc.dim(r.notes.join("\n")));
+    p2.note(manualCommands().join("\n"), "Finish wiring (run in your terminal)");
+    if (r.notes.length) info(pc3.dim(r.notes.join("\n")));
+    p2.note(
+      [
+        "You can still create an account now:",
+        `  carrier open signup`,
+        "Then open Claude and talk to your fleet \u2014 browser OAuth completes auth."
+      ].join("\n"),
+      "Next"
+    );
+  } else {
+    p2.note(
+      [
+        "Open Claude Code and say something like:",
+        '  "Show my fleet health"',
+        "First call opens the browser for sign-in / sign-up. No token paste.",
+        "",
+        "More prompts: carrier examples"
+      ].join("\n"),
+      "Talk to your fleet"
+    );
   }
 }
 async function doSiteCreate(target, brand) {
-  const s = p.spinner();
+  const s = p2.spinner();
   s.start(`Scaffolding ${brand.name} storefront \u2192 ${target}`);
-  await scaffoldStorefront(target, brand);
+  try {
+    await scaffoldStorefront(target, brand);
+  } catch (e) {
+    s.stop("Scaffold failed");
+    fail(String(e instanceof Error ? e.message : e), [
+      "Pick a free directory: carrier site create ./my-storefront",
+      "Ensure the package templates shipped with @carrierllc/mcp",
+      "Still stuck? carrier open console"
+    ]);
+    throw e;
+  }
   s.stop("Storefront scaffolded");
   ok(`Created ${target} (white-labeled: ${brand.name}, accent ${brand.colors.accent})`);
 }
 async function maybeBuildDeploy(target, brand, opts) {
   if (opts.install) {
-    const s = p.spinner();
+    const s = p2.spinner();
     s.start("Installing storefront dependencies");
     const oki = await installDeps(target);
     s.stop(oki ? "Dependencies installed" : "Dependency install reported errors");
-    if (!oki) return;
+    if (!oki) {
+      p2.note(
+        [
+          `cd ${target} && pnpm install`,
+          "Fix any Node/pnpm version issues, then retry build"
+        ].join("\n"),
+        "Next"
+      );
+      return;
+    }
   }
   if (opts.build) {
-    const s = p.spinner();
+    const s = p2.spinner();
     s.start("Building storefront (next build)");
     const okb = await buildSite(target);
     s.stop(okb ? "Build succeeded" : "Build failed \u2014 see output above");
-    if (!okb) return;
+    if (!okb) {
+      p2.note(
+        [`cd ${target}`, "pnpm build", "Check env keys in .env.local if the build mentions Clerk"].join("\n"),
+        "Next"
+      );
+      return;
+    }
   }
   if (opts.deploy) {
-    const s = p.spinner();
+    const s = p2.spinner();
     s.start("Deploying to Cloudflare Workers");
     const r = await deploySite(target, brand);
     s.stop(r.ok ? `Deployed: ${r.projectName}` : "Deploy skipped");
-    if (!r.ok && r.reason) info(pc.yellow(r.reason));
+    if (!r.ok && r.reason) {
+      info(pc3.yellow(r.reason));
+      p2.note(
+        [
+          "Install wrangler and login: npx wrangler login",
+          `Then: carrier site deploy ${target}`
+        ].join("\n"),
+        "Next"
+      );
+    }
   }
 }
-var program = new Command();
-program.name("carrier").description("Carrier CLI \u2014 install the Claude Code plugin and roll out a white-labeled eSIM storefront.").version(VERSION);
-program.command("init").description("Interactive: install the plugin AND scaffold/deploy a storefront.").option("--dir <path>", "Storefront output directory", "./storefront").option("--yes", "Use Carrier defaults, no prompts").action(async (o) => {
-  header();
-  await doPluginInstall();
-  const brand = o.yes ? CARRIER_BRAND : await promptBrand(CARRIER_BRAND);
-  const target = resolve2(o.dir);
+async function interactiveSiteCreate() {
+  const brand = await promptBrand(CARRIER_BRAND);
+  const dir = await p2.text({
+    message: "Output directory",
+    placeholder: "./storefront",
+    defaultValue: "./storefront"
+  });
+  if (p2.isCancel(dir)) return;
+  const target = resolve2(dir);
   if (await exists(target)) {
-    const go = await p.confirm({ message: `${target} exists \u2014 write into it anyway?`, initialValue: false });
-    if (p.isCancel(go) || !go) {
-      p.outro("Stopped. Re-run with --dir <new path>.");
+    const go = await p2.confirm({ message: `${target} exists \u2014 write into it anyway?`, initialValue: false });
+    if (p2.isCancel(go) || !go) {
+      p2.outro("Stopped. Re-run with a different directory.");
       return;
     }
   }
   await doSiteCreate(target, brand);
-  let install = !!o.yes;
-  let build = !!o.yes;
-  let deploy = false;
-  if (!o.yes) {
-    const next = await p.select({
+  p2.outro(pc3.green(`Scaffolded. cd ${dir} && pnpm install && pnpm dev`));
+}
+var program = new Command();
+program.name("carrier").description(
+  "Carrier CLI \u2014 clear TUI for non-developers: status, OAuth-ready MCP install, storefront scaffold, and fleet NL helpers."
+).version(VERSION).action(async () => {
+  header();
+  await runHome({
+    onInstall: doPluginInstall,
+    onSiteCreate: interactiveSiteCreate
+  });
+});
+program.command("init").description("Interactive home: status, install plugin+MCP (OAuth on first use), optional storefront.").option("--dir <path>", "Storefront output directory", "./storefront").option("--yes", "Use Carrier defaults, no prompts (plugin + scaffold + build)").option("--full", "After install, continue into storefront scaffold (default interactive path offers both)").action(async (o) => {
+  header();
+  if (o.yes) {
+    await doPluginInstall();
+    const brand = CARRIER_BRAND;
+    const target = resolve2(o.dir);
+    if (await exists(target)) {
+      info(pc3.yellow(`${target} exists \u2014 writing into it (--yes).`));
+    }
+    await doSiteCreate(target, brand);
+    await maybeBuildDeploy(target, brand, { install: true, build: true, deploy: false });
+    p2.note(oauthFirstUseNote(), "Auth");
+    p2.note(
+      [
+        `cd ${o.dir}`,
+        `Edit src/brand.config.ts to re-brand anytime`,
+        `pnpm dev   # local preview`,
+        `MCP endpoint: ${MCP_URL}`,
+        'In Claude: "Show my fleet health" (browser OAuth on first use)'
+      ].join("\n"),
+      "Next"
+    );
+    p2.outro(pc3.green("Done. Your connectivity business is wired."));
+    return;
+  }
+  if (o.full) {
+    const st = await gatherStatus();
+    printStatus(st);
+    await doPluginInstall();
+    const brand = await promptBrand(CARRIER_BRAND);
+    const target = resolve2(o.dir);
+    if (await exists(target)) {
+      const go = await p2.confirm({ message: `${target} exists \u2014 write into it anyway?`, initialValue: false });
+      if (p2.isCancel(go) || !go) {
+        p2.outro("Stopped. Re-run with --dir <new path>.");
+        return;
+      }
+    }
+    await doSiteCreate(target, brand);
+    const next = await p2.select({
       message: "Roll it out now?",
       options: [
         { value: "build", label: "Install deps + build" },
@@ -563,34 +1237,147 @@ program.command("init").description("Interactive: install the plugin AND scaffol
       ],
       initialValue: "build"
     });
-    if (p.isCancel(next)) process.exit(0);
-    install = next !== "none";
-    build = next !== "none";
-    deploy = next === "deploy";
+    if (p2.isCancel(next)) process.exit(0);
+    await maybeBuildDeploy(target, brand, {
+      install: next !== "none",
+      build: next !== "none",
+      deploy: next === "deploy"
+    });
+    p2.note(oauthFirstUseNote(), "Auth");
+    p2.note(
+      [
+        `cd ${o.dir}`,
+        `Edit src/brand.config.ts to re-brand anytime`,
+        `pnpm dev   # local preview`,
+        `MCP endpoint: ${MCP_URL}`
+      ].join("\n"),
+      "Next"
+    );
+    p2.outro(pc3.green("Done. Your connectivity business is wired."));
+    return;
   }
-  await maybeBuildDeploy(target, brand, { install, build, deploy });
-  p.note(
-    [
-      `cd ${o.dir}`,
-      `Edit src/brand.config.ts to re-brand anytime`,
-      `pnpm dev   # local preview`,
-      `MCP endpoint: ${MCP_URL}`
-    ].join("\n"),
-    "Next"
-  );
-  p.outro(pc.green("Done. Your connectivity business is wired."));
+  await runHome({
+    onInstall: doPluginInstall,
+    onSiteCreate: async () => {
+      const brand = await promptBrand(CARRIER_BRAND);
+      const target = resolve2(o.dir);
+      if (await exists(target)) {
+        const go = await p2.confirm({ message: `${target} exists \u2014 write into it anyway?`, initialValue: false });
+        if (p2.isCancel(go) || !go) {
+          p2.log.info("Skipped storefront. Pick Install or Exit from the menu, or re-run with --dir.");
+          return;
+        }
+      }
+      await doSiteCreate(target, brand);
+      const next = await p2.select({
+        message: "Roll it out now?",
+        options: [
+          { value: "build", label: "Install deps + build" },
+          { value: "deploy", label: "Install + build + deploy to Cloudflare Workers" },
+          { value: "none", label: "Just scaffold \u2014 I'll build later" }
+        ],
+        initialValue: "build"
+      });
+      if (p2.isCancel(next)) return;
+      await maybeBuildDeploy(target, brand, {
+        install: next !== "none",
+        build: next !== "none",
+        deploy: next === "deploy"
+      });
+      p2.note(
+        [
+          `cd ${o.dir}`,
+          `pnpm dev`,
+          `MCP: ${MCP_URL} \xB7 OAuth on first use in Claude`
+        ].join("\n"),
+        "Next"
+      );
+    }
+  });
 });
 var plugin = program.command("plugin").description("Manage the Carrier Claude Code plugin.");
-plugin.command("install").description("Install/register the Carrier plugin + MCP into Claude Code.").action(async () => {
+plugin.command("install").description("Install/register the Carrier plugin + zero-cred MCP (OAuth on first use).").action(async () => {
   header();
   await doPluginInstall();
-  p.outro(pc.green("Plugin ready. Restart Claude Code to load it."));
+  p2.outro(pc3.green("Plugin ready. Restart Claude Code, then talk to your fleet."));
 });
-plugin.command("status").description("Show plugin install status.").action(async () => {
-  const st = await pluginStatus();
+plugin.command("status").description("Show plugin + MCP registration + auth next steps.").action(async () => {
   header();
-  info(st.installed ? pc.green(`Installed v${st.version ?? "?"} \u2192 ${st.dir}`) : pc.yellow(`Not installed (${st.dir})`));
-  p.outro("");
+  const st = await gatherStatus();
+  printStatus(st);
+  p2.note(oauthFirstUseNote(), "Auth");
+  p2.outro("");
+});
+program.command("status").description("Show MCP / plugin / auth status and next steps.").action(async () => {
+  header();
+  const s = p2.spinner();
+  s.start("Checking status");
+  const st = await gatherStatus();
+  s.stop("Done");
+  p2.note(formatStatusBlock(st), "Status");
+  p2.note(formatNextSteps(st), "Next steps");
+  p2.note(oauthFirstUseNote(), "Auth");
+  p2.outro("");
+});
+var openCmd = program.command("open").description("Open Carrier account / product URLs in your browser.");
+for (const [name, url, desc] of [
+  ["signup", SIGN_UP_URL, "Create a Carrier account (Clerk sign-up)"],
+  ["signin", SIGN_IN_URL, "Sign in to Carrier"],
+  ["console", CONSOLE_URL, "Open the Carrier console"],
+  ["onboarding", ONBOARDING_URL, "Open console onboarding (link OCS / managed)"],
+  ["mcp", MCP_HOME, "Open mcp.carrier.llc product page"]
+]) {
+  openCmd.command(name).description(desc).action(async () => {
+    header();
+    const r = await openUrl(url);
+    if (r.ok) ok(r.hint);
+    else {
+      p2.log.warn(r.hint);
+      p2.note(url, "Open this URL");
+    }
+    p2.note(accountLinksNote(), "Account links");
+    p2.outro("");
+  });
+}
+program.command("examples").description("Print natural-language fleet prompts for Claude / MCP.").action(async () => {
+  header();
+  p2.note(formatNlExamples(), "Talk to fleet \u2014 paste into Claude");
+  p2.note(
+    [
+      "After `carrier plugin install` (or this menu \u2192 Install):",
+      "  1. Open Claude Code",
+      '  2. Say: "Show my fleet health"',
+      "  3. Browser opens for sign-in/sign-up on first use",
+      "",
+      "Slash commands: /carrier:fleet  /carrier:status  /carrier:wallet  /carrier:onboard"
+    ].join("\n"),
+    "How"
+  );
+  p2.outro("");
+});
+program.command("ask").description('Optional headless NL: carrier ask "show fleet health" (needs CARRIER_API_KEY or OCS token).').argument("<intent...>", "Natural-language intent").action(async (parts) => {
+  header();
+  const intent = parts.join(" ").trim();
+  if (!intent) {
+    fail("Missing intent.", [
+      'carrier ask "show fleet health"',
+      "Or use Claude interactively (no token): carrier plugin install"
+    ]);
+    process.exitCode = 1;
+    return;
+  }
+  const s = p2.spinner();
+  s.start("Asking Carrier MCP\u2026");
+  const result = await carrierAsk(intent);
+  s.stop(result.ok ? "Done" : "Failed");
+  if (result.ok) {
+    p2.note(result.text.slice(0, 6e3), "Answer");
+    p2.outro("");
+  } else {
+    p2.log.error(result.text);
+    p2.outro(pc3.yellow("See next steps above."));
+    process.exitCode = 1;
+  }
 });
 var site = program.command("site").description("Scaffold and deploy a white-labeled storefront.");
 site.command("create [dir]").description("Scaffold a white-labeled storefront from the Mango template.").option("--name <name>", "Brand name").option("--domain <domain>", "Domain").option("--accent <hex>", "Accent color").option("--yes", "Carrier defaults, no prompts").action(async (dir, o) => {
@@ -621,24 +1408,50 @@ site.command("create [dir]").description("Scaffold a white-labeled storefront fr
   }
   const target = resolve2(dir ?? "./storefront");
   if (await exists(target)) {
-    const go = await p.confirm({ message: `${target} exists \u2014 write into it anyway?`, initialValue: false });
-    if (p.isCancel(go) || !go) {
-      p.outro("Stopped. Re-run with a different directory.");
+    const go = await p2.confirm({ message: `${target} exists \u2014 write into it anyway?`, initialValue: false });
+    if (p2.isCancel(go) || !go) {
+      p2.outro("Stopped. Re-run with a different directory.");
       return;
     }
   }
-  await doSiteCreate(target, brand);
-  p.outro(pc.green(`Scaffolded. cd ${dir ?? "storefront"} && pnpm install && pnpm dev`));
+  try {
+    await doSiteCreate(target, brand);
+  } catch {
+    process.exitCode = 1;
+    return;
+  }
+  p2.outro(pc3.green(`Scaffolded. cd ${dir ?? "storefront"} && pnpm install && pnpm dev`));
 });
 site.command("deploy [dir]").description("Build + deploy a storefront to Cloudflare Workers.").option("--name <name>", "Cloudflare Worker name (defaults from brand)").action(async (dir, o) => {
   header();
   const target = resolve2(dir ?? "./storefront");
-  const brand = await loadStorefrontBrand(target, o.name ? { name: o.name } : void 0);
-  await maybeBuildDeploy(target, brand, { install: true, build: true, deploy: true });
-  p.outro("");
+  try {
+    const brand = await loadStorefrontBrand(target, o.name ? { name: o.name } : void 0);
+    await maybeBuildDeploy(target, brand, { install: true, build: true, deploy: true });
+  } catch (e) {
+    fail(String(e instanceof Error ? e.message : e), [
+      "Scaffold first: carrier site create",
+      "Ensure wrangler is logged in for deploy"
+    ]);
+    process.exitCode = 1;
+    return;
+  }
+  p2.outro("");
 });
 program.parseAsync(process.argv).catch((e) => {
-  console.error(pc.red(String(e instanceof Error ? e.message : e)));
+  console.error(pc3.red(String(e instanceof Error ? e.message : e)));
+  console.error(
+    pc3.dim(
+      [
+        "",
+        "What to do next:",
+        "  \u2192 carrier status",
+        "  \u2192 carrier open signup",
+        "  \u2192 carrier plugin install",
+        "  \u2192 carrier --help"
+      ].join("\n")
+    )
+  );
   process.exit(1);
 });
 //# sourceMappingURL=cli.js.map