@carrierllc/mcp 0.5.0 → 0.7.0

package/dist/cli.js

@@ -39,7 +39,7 @@ import {
   verifyStorefront,
   walletScreen,
   which
-} from "./chunk-QZBALDKD.js";
+} from "./chunk-CQ6EOLA7.js";
 import {
   copyTree,
   exists,
@@ -94,6 +94,7 @@ function installedPluginDir() {
 // src/cli/lib/urls.ts
 import { spawn } from "child_process";
 var MCP_URL = "https://mcp.carrier.llc/mcp";
+var API_URL = "https://api.carrier.llc";
 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";
@@ -683,6 +684,9 @@ function isExpired(creds, skewMs = 6e4) {
   if (!creds.expiresAt) return false;
   return Date.now() >= creds.expiresAt - skewMs;
 }
+function redact(text3) {
+  return text3.replace(/\b(ak_|sk_|rt_)[A-Za-z0-9._-]{6,}/g, "$1***").replace(/\bBearer\s+[A-Za-z0-9._-]{8,}/gi, "Bearer ***");
+}
 
 // src/cli/lib/auth.ts
 var DISCOVERY_PATH = "/.well-known/oauth-authorization-server";
@@ -2276,251 +2280,1633 @@ var CLI_DOMAINS = [
         ]
       }
     ]
-  }
-];
-
-// src/cli/lib/capability.ts
-import * as p2 from "@clack/prompts";
-import pc3 from "picocolors";
-var MAX_PRETTY_CHARS = 8e3;
-function optionKey(flags) {
-  const long = flags.split(/[ ,|]+/).find((t) => t.startsWith("--"));
-  if (!long) throw new Error(`Option "${flags}" has no long flag`);
-  return long.replace(/^--/, "").split("-").map((part, i) => i === 0 ? part : part.charAt(0).toUpperCase() + part.slice(1)).join("");
-}
-function setArg(target, path, value) {
-  const parts = path.split(".");
-  let node = target;
-  for (const part of parts.slice(0, -1)) {
-    const next = node[part];
-    if (typeof next !== "object" || next === null) node[part] = {};
-    node = node[part];
-  }
-  node[parts[parts.length - 1]] = value;
-}
-function coerce(opt, raw) {
-  if (opt.type === "boolean") {
-    if (raw === true) return { value: true };
-    const text3 = String(raw).toLowerCase();
-    if (text3 === "true") return { value: true };
-    if (text3 === "false") return { value: false };
-    return { error: `${opt.flags} expects true or false, got "${String(raw)}"` };
-  }
-  if (opt.type === "number") {
-    const n = Number(raw);
-    if (!Number.isFinite(n)) return { error: `${opt.flags} expects a number, got "${String(raw)}"` };
-    return { value: n };
-  }
-  return { value: String(raw) };
-}
-function buildToolArgs(cmd, opts) {
-  const args = {};
-  const errors = [];
-  const notes = [];
-  for (const opt of cmd.options) {
-    const raw = opts[optionKey(opt.flags)];
-    if (raw === void 0 || raw === false) {
-      if (opt.required) errors.push(`Missing required ${opt.flags}`);
-      continue;
-    }
-    const { value, error } = coerce(opt, raw);
-    if (error) errors.push(error);
-    else setArg(args, opt.arg, value);
-  }
-  if (cmd.requireOneOf && !cmd.requireOneOf.some((name) => args[name] !== void 0)) {
-    const flags = cmd.options.filter((opt) => cmd.requireOneOf.includes(opt.arg)).map((opt) => opt.flags);
-    errors.push(`Pass one of: ${flags.join(", ")}`);
-  }
-  if (cmd.usageWindow) {
-    const start = args.startDate;
-    const end = args.endDate;
-    if (!start && !end) {
-      const window = lastNDaysPeriod();
-      args.startDate = window.start;
-      args.endDate = window.end;
-      notes.push(`Window defaulted to ${window.start} \u2026 ${window.end} (last ${OCS_MAX_USAGE_WINDOW_DAYS} days).`);
-    } else if (!start || !end) {
-      errors.push("Pass both --start and --end, or neither for the last 7 days");
-    } else {
-      const clamped = clampUsagePeriod(start, end);
-      if (clamped.start !== start) {
-        notes.push(
-          `Start moved to ${clamped.start} \u2014 OCS rejects windows wider than ${OCS_MAX_USAGE_WINDOW_DAYS} days.`
-        );
+  },
+  {
+    name: "api-keys",
+    summary: "Mint Carrier API keys (ak_\u2026) for headless and CI use",
+    commands: [
+      {
+        name: "create",
+        transport: "rest",
+        restMethod: "POST",
+        restPath: "/v1/api-keys",
+        summary: "Create an org API key. The secret is shown once and never stored by the CLI.",
+        options: [
+          {
+            flags: "--name <name>",
+            description: "Label for the key, max 64 characters",
+            arg: "name",
+            type: "string",
+            required: true
+          },
+          {
+            flags: "--description <text>",
+            description: "Optional note, max 256 characters",
+            arg: "description",
+            type: "string"
+          },
+          {
+            flags: "--seconds-until-expiration <n>",
+            description: "Expiry in seconds, 60 to 31536000. Omit for a key that does not expire.",
+            arg: "secondsUntilExpiration",
+            type: "number"
+          }
+        ]
       }
-      args.startDate = clamped.start;
-      args.endDate = clamped.end;
-    }
-  }
-  if (cmd.write) args.dry_run = true;
-  return { args, errors, notes };
-}
-function formatJsonOutput(text3) {
-  try {
-    JSON.parse(text3);
-    return text3;
-  } catch {
-    return JSON.stringify(text3);
-  }
-}
-async function runCapability(domain, cmd, opts) {
-  const label = `${domain.name} ${cmd.name}`;
-  const quiet = opts.json === true;
-  const { args, errors, notes } = buildToolArgs(cmd, opts);
-  if (cmd.write && opts.commit === true) delete args.dry_run;
-  if (errors.length) {
-    const message = withNextStep(`Cannot run \`carrier ${label}\`.`, [
-      ...errors,
-      `See every flag: carrier ${label} --help`
-    ]);
-    if (quiet) console.error(message);
-    else p2.log.error(message);
-    process.exitCode = 1;
-    return;
-  }
-  const dryRun = cmd.write === true && args.dry_run === true;
-  const warnings = dryRun ? [...notes, "Dry run \u2014 nothing changes. Re-run with --commit to apply."] : notes;
-  for (const note4 of warnings) {
-    if (quiet) console.error(note4);
-    else p2.log.info(pc3.dim(note4));
-  }
-  const s = quiet ? null : p2.spinner();
-  s?.start(`Calling ${cmd.tool}`);
-  const result = await callMcpTool(cmd.tool, args, {
-    errorHints: [
-      `Check the arguments: carrier ${label} --help`,
-      'Or describe the task in words: carrier ask "\u2026"'
     ]
-  });
-  s?.stop(result.ok ? "Done" : "Failed");
-  if (!result.ok) {
-    if (quiet) console.error(result.text);
-    else p2.log.error(result.text);
-    process.exitCode = 1;
-    return;
-  }
-  if (quiet) {
-    process.stdout.write(`${formatJsonOutput(result.text)}
-`);
-    return;
-  }
-  const body = result.text.length > MAX_PRETTY_CHARS ? `${result.text.slice(0, MAX_PRETTY_CHARS)}
-\u2026truncated. Re-run with --json for the whole response.` : result.text;
-  p2.note(body, cmd.tool);
-}
-
-// src/cli/index.ts
-var VERSION = CARRIER_VERSION;
-function header() {
-  p3.intro(`${pc4.bold(pc4.yellow("\u25C6 carrier"))} ${pc4.dim("\xB7 the Stripe of telecom \u2014 CLI v" + VERSION)}`);
-}
-function ok(msg) {
-  p3.log.success(pc4.green(msg));
-}
-function info(msg) {
-  p3.log.info(msg);
-}
-function fail(msg, next) {
-  p3.log.error(msg);
-  p3.note(next.map((s) => `\u2192 ${s}`).join("\n"), "What to do next");
-}
-async function promptBrand(seed) {
-  const name = await p3.text({
-    message: "Brand name",
-    placeholder: seed.name,
-    defaultValue: seed.name
-  });
-  if (p3.isCancel(name)) process.exit(0);
-  const domain = await p3.text({
-    message: "Domain",
-    placeholder: seed.domain,
-    defaultValue: seed.domain
-  });
-  if (p3.isCancel(domain)) process.exit(0);
-  const accent = await p3.text({
-    message: "Accent color (hex)",
-    placeholder: seed.colors.accent,
-    defaultValue: seed.colors.accent
-  });
-  if (p3.isCancel(accent)) process.exit(0);
-  const supportEmail = await p3.text({
-    message: "Support email",
-    placeholder: `support@${domain}`,
-    defaultValue: `support@${domain}`
-  });
-  if (p3.isCancel(supportEmail)) process.exit(0);
-  const accentDark = deriveAccentDark(accent, seed);
-  const isCarrier = name === CARRIER_BRAND.name && domain === CARRIER_BRAND.domain;
-  return {
-    ...seed,
-    name,
-    legalName: name,
-    tagline: isCarrier ? seed.tagline : `Mobile connectivity by ${name}.`,
-    domain,
-    supportEmail,
-    supportUrl: `https://${domain}/help`,
-    supportWhatsapp: isCarrier ? seed.supportWhatsapp : "",
-    social: isCarrier ? seed.social : {},
-    colors: { ...seed.colors, accent, accentDark }
-  };
-}
-async function doPluginInstall() {
-  const s = p3.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 ? pc4.green("registered") : pc4.yellow("manual")}  \xB7  marketplace: ${r.marketplaceAdded ? pc4.green("added") : pc4.yellow("manual")}  \xB7  install: ${r.pluginInstalled ? pc4.green("done") : pc4.yellow("manual")}`
-  );
-  p3.note(installAuthGuidance().join("\n"), "OAuth on first use (Entry A)");
-  if (!r.claudeFound || r.notes.length) {
-    p3.note(manualCommands().join("\n"), "Finish wiring (run in your terminal)");
-    if (r.notes.length) info(pc4.dim(r.notes.join("\n")));
-    p3.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 {
-    p3.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 = p3.spinner();
-  s.start(`Scaffolding ${brand.name} storefront \u2192 ${target}`);
-  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"
-    ]);
+  },
+  // <generated:catalog-domains>
+  // Generated from the MCP catalog by scripts/generate-domains.mjs. Do not edit by hand:
+  // rebuild the server, re-run the generator, and review the diff.
+  {
+    name: "billing",
+    summary: "Carrier plan credits, spend thresholds and rate-limit state",
+    commands: [
+      {
+        name: "events",
+        tool: "billing_events",
+        summary: "View recent billing threshold events: notifications, invoice triggers, hard cap alerts, and overage pauses.",
+        options: [
+          {
+            flags: "--limit <n>",
+            description: "Maximum number of events to return (default: 20, max: 50).",
+            arg: "limit",
+            type: "number"
+          }
+        ]
+      },
+      {
+        name: "configure",
+        tool: "configure_billing",
+        summary: "Configure your billing preferences: enable/disable overages, set billing thresholds (bill shock prevention), configure notification percentages, and set hard spending caps.",
+        requireConfirm: true,
+        options: [
+          {
+            flags: "--overages-enabled <bool>",
+            description: "Enable or disable auto-billed overages when monthly credits are exhausted.",
+            arg: "overages_enabled",
+            type: "boolean"
+          },
+          {
+            flags: "--billing-threshold-cents <n>",
+            description: "Amount in cents at which an invoice is automatically generated (e.g., 10000 = $100).",
+            arg: "billing_threshold_cents",
+            type: "number"
+          },
+          {
+            flags: "--hard-cap-cents <n>",
+            description: "Maximum overage spend in cents before overages are paused (0 = no cap).",
+            arg: "hard_cap_cents",
+            type: "number"
+          },
+          {
+            flags: "--auto-pause-on-cap <bool>",
+            description: "Whether to automatically pause overages when hard cap is reached.",
+            arg: "auto_pause_on_cap",
+            type: "boolean"
+          },
+          {
+            flags: "--notify-at-pct <list>",
+            description: "Percentage thresholds at which to send notifications (e.g., [50, 80, 95, 100]). Comma-separated.",
+            arg: "notify_at_pct",
+            type: "number[]"
+          },
+          {
+            flags: "--notification-email <email>",
+            description: "Email address for billing threshold notifications.",
+            arg: "notification_email",
+            type: "string"
+          },
+          {
+            flags: "--notification-phone <phone>",
+            description: "E.164 phone number for SMS billing threshold notifications via Twilio (e.g. +14155552671).",
+            arg: "notification_phone",
+            type: "string"
+          },
+          {
+            flags: "--webhook-url <url>",
+            description: "Webhook URL for billing threshold events.",
+            arg: "webhook_url",
+            type: "string"
+          }
+        ]
+      },
+      {
+        name: "credits",
+        tool: "credit_balance",
+        summary: "Read how much of this Carrier MCP plan is left: credits remaining, daily free credits, overage state, volume discount tier, and billing threshold state.",
+        options: []
+      },
+      {
+        name: "plans",
+        tool: "pricing_plans",
+        summary: "View all available Carrier MCP pricing plans with credit allotments, features, overage rates, and volume discount tiers.",
+        options: []
+      },
+      {
+        name: "projection",
+        tool: "usage_projection",
+        summary: "Project your credit usage and costs for the remainder of the billing period based on current consumption rate.",
+        options: [
+          {
+            flags: "--days-to-project <n>",
+            description: "Number of days to project forward (default: remaining days in month).",
+            arg: "days_to_project",
+            type: "number"
+          }
+        ]
+      },
+      {
+        name: "rate-limit",
+        tool: "rate_limit_status",
+        summary: "Inspect Bridge4IP OCS rate-limit governor state \u2014 bucket fill levels, per-endpoint limits, and 80% alert thresholds.",
+        options: [
+          {
+            flags: "--endpoint <endpoint>",
+            description: "OCS method name in camelCase (e.g. 'subscriberUsageOverPeriod').",
+            arg: "endpoint",
+            type: "string"
+          }
+        ]
+      }
+    ]
+  },
+  {
+    name: "wallet",
+    summary: "The Carrier prepaid wallet: balance and top-ups",
+    commands: [
+      {
+        name: "balance",
+        tool: "wallet_balance",
+        summary: "Read the caller organisation's Carrier prepaid wallet: current balance and auto-top-up settings.",
+        options: []
+      },
+      {
+        name: "topup",
+        tool: "wallet_topup_checkout",
+        summary: "Create a Stripe Checkout link so a human can top up the Carrier prepaid wallet by card.",
+        options: [
+          {
+            flags: "--pack <pack>",
+            description: "Pack id (pack_500/pack_1000/pack_2500/pack_5000) or exact EUR-cents amount.",
+            arg: "pack",
+            type: "string"
+          }
+        ]
+      },
+      {
+        name: "auto-topup",
+        tool: "wallet_auto_topup",
+        summary: "Charge the organisation's saved card off-session, right now, and credit the Carrier prepaid wallet with the pack.",
+        requireConfirm: true,
+        options: [
+          {
+            flags: "--pack-cents <n>",
+            description: "Override pack amount in EUR cents (must match a catalog pack).",
+            arg: "pack_cents",
+            type: "number"
+          }
+        ]
+      }
+    ]
+  },
+  {
+    name: "stripe",
+    summary: "Money in the operator's connected Stripe account",
+    commands: [
+      {
+        name: "balance",
+        tool: "stripe_connect_balance",
+        summary: "Read the money sitting in the operator's connected Stripe account: available and pending, split per currency.",
+        options: []
+      },
+      {
+        name: "payouts",
+        tool: "stripe_connect_payouts",
+        summary: "List money Stripe has already sent from the operator's connected account to their bank, newest first.",
+        options: [
+          {
+            flags: "--limit <n>",
+            description: "Number of payouts to return. Default 10.",
+            arg: "limit",
+            type: "number"
+          },
+          {
+            flags: "--status <status>",
+            description: "Filter by payout status. One of: pending, paid, failed, canceled, in_transit.",
+            arg: "status",
+            type: "string"
+          }
+        ]
+      },
+      {
+        name: "disputes",
+        tool: "stripe_connect_dispute_list",
+        summary: "List chargebacks customers have raised with their bank against the operator's connected Stripe account.",
+        options: [
+          {
+            flags: "--limit <n>",
+            description: "limit (number). Default 10.",
+            arg: "limit",
+            type: "number"
+          },
+          {
+            flags: "--status <status>",
+            description: "Filter by dispute status (e.g. needs_response, under_review).",
+            arg: "status",
+            type: "string"
+          }
+        ]
+      },
+      {
+        name: "refund",
+        tool: "stripe_connect_refund",
+        summary: "Refund money to a customer on one charge in the operator's connected Stripe account.",
+        options: [
+          {
+            flags: "--charge-id <id>",
+            description: "Stripe charge ID (ch_...).",
+            arg: "charge_id",
+            type: "string",
+            required: true
+          },
+          {
+            flags: "--amount-cents <n>",
+            description: "Partial refund amount in cents.",
+            arg: "amount_cents",
+            type: "number"
+          },
+          {
+            flags: "--reason <reason>",
+            description: "reason (string). One of: duplicate, fraudulent, requested_by_customer.",
+            arg: "reason",
+            type: "string"
+          },
+          {
+            flags: "--confirm-token <token>",
+            description: "Confirmation token from previous call.",
+            arg: "confirm_token",
+            type: "string"
+          }
+        ]
+      }
+    ]
+  },
+  {
+    name: "radar",
+    summary: "Stripe Radar fraud reviews and value lists",
+    commands: [
+      {
+        name: "reviews",
+        tool: "radar_review_list",
+        summary: "List the Stripe Radar fraud reviews waiting on a manual approve/decline decision, newest first.",
+        options: [
+          {
+            flags: "--open-only <bool>",
+            description: "If true, only returns open (undecided) reviews. Default true.",
+            arg: "open_only",
+            type: "boolean"
+          },
+          {
+            flags: "--limit <n>",
+            description: "limit (number). Default 10.",
+            arg: "limit",
+            type: "number"
+          }
+        ]
+      },
+      {
+        name: "approve",
+        tool: "radar_review_approve",
+        summary: "Clear a Stripe Radar fraud review so the held charge is captured and the money is taken.",
+        options: [
+          {
+            flags: "--review-id <id>",
+            description: "Stripe Radar review ID (prv_...).",
+            arg: "review_id",
+            type: "string",
+            required: true
+          },
+          {
+            flags: "--confirm-token <token>",
+            description: "confirm token (string).",
+            arg: "confirm_token",
+            type: "string"
+          }
+        ]
+      },
+      {
+        name: "decline",
+        tool: "radar_review_decline",
+        summary: "Close a Stripe Radar fraud review as fraudulent, so the held charge is blocked and the customer is never billed.",
+        options: [
+          {
+            flags: "--review-id <id>",
+            description: "review id (string).",
+            arg: "review_id",
+            type: "string",
+            required: true
+          },
+          {
+            flags: "--confirm-token <token>",
+            description: "confirm token (string).",
+            arg: "confirm_token",
+            type: "string"
+          }
+        ]
+      },
+      {
+        name: "rule-toggle",
+        tool: "radar_rule_toggle",
+        summary: "Report a Stripe Radar rule's state. Stripe exposes no API to change it, so this changes nothing.",
+        options: [
+          {
+            flags: "--rule-id <id>",
+            description: "Stripe Radar rule ID.",
+            arg: "rule_id",
+            type: "string",
+            required: true
+          },
+          {
+            flags: "--enabled <bool>",
+            description: "true = enable, false = disable.",
+            arg: "enabled",
+            type: "boolean",
+            required: true
+          }
+        ]
+      },
+      {
+        name: "value-list add",
+        tool: "radar_value_list_add",
+        summary: "Add one value to an existing Stripe Radar value list, changing how every future charge is scored.",
+        options: [
+          {
+            flags: "--value-list-id <id>",
+            description: "Stripe Radar value list ID (rsl_...).",
+            arg: "value_list_id",
+            type: "string",
+            required: true
+          },
+          {
+            flags: "--value <value>",
+            description: "The value to add (email, IP address, country code, etc.).",
+            arg: "value",
+            type: "string",
+            required: true
+          },
+          {
+            flags: "--confirm-token <token>",
+            description: "confirm token (string).",
+            arg: "confirm_token",
+            type: "string"
+          }
+        ]
+      }
+    ]
+  },
+  {
+    name: "greenzone",
+    summary: "The Bridge4IP Greenzone whitelist",
+    commands: [
+      {
+        name: "list",
+        tool: "greenzone_whitelist_list",
+        summary: "List current Greenzone whitelist entries from the KV cache.",
+        options: [
+          {
+            flags: "--from-portal <bool>",
+            description: "When true, return Kapture steps to read live portal state instead of KV cache.",
+            arg: "from_portal",
+            type: "boolean"
+          }
+        ]
+      },
+      {
+        name: "add",
+        tool: "greenzone_whitelist_add",
+        summary: "Add a host or IP to the Greenzone whitelist. Needs Kapture running in the operator's own Chrome \u2014 without it the dry run still returns the portal steps to follow by hand.",
+        write: true,
+        options: [
+          {
+            flags: "--host <host>",
+            description: "Hostname to whitelist (e.g. 'example.com').",
+            arg: "host",
+            type: "string"
+          },
+          {
+            flags: "--ip <ip>",
+            description: "IP address or CIDR to whitelist (e.g. '203.0.113.0/24').",
+            arg: "ip",
+            type: "string"
+          }
+        ]
+      },
+      {
+        name: "remove",
+        tool: "greenzone_whitelist_remove",
+        summary: "Remove a host or IP from the Greenzone whitelist. Needs Kapture running in the operator's own Chrome \u2014 without it the dry run still returns the portal steps to follow by hand.",
+        write: true,
+        options: [
+          {
+            flags: "--host <host>",
+            description: "Hostname to remove from whitelist.",
+            arg: "host",
+            type: "string"
+          },
+          {
+            flags: "--ip <ip>",
+            description: "IP address or CIDR to remove from whitelist.",
+            arg: "ip",
+            type: "string"
+          }
+        ]
+      }
+    ]
+  },
+  {
+    name: "agent",
+    summary: "Steel browsing agents: one-off tasks and cron schedules",
+    commands: [
+      {
+        name: "ask",
+        tool: "ui_agent_ask",
+        summary: "Send a plain-language task to a Steel browsing agent, which drives a real browser on the open web \u2014 navigating pages, searching via Tavily, extracting content, filling forms outside the OCS portal.",
+        write: true,
+        options: [
+          {
+            flags: "--prompt <prompt>",
+            description: "Natural-language task description for the Steel browsing agent.",
+            arg: "prompt",
+            type: "string",
+            required: true
+          },
+          {
+            flags: "--max-steps <n>",
+            description: "Maximum agent steps (1\u201330, default 15).",
+            arg: "max_steps",
+            type: "number"
+          }
+        ]
+      },
+      {
+        name: "status",
+        tool: "ui_agent_status",
+        summary: "Poll the status of a Steel browser agent task dispatched by ui_agent_ask or any ui_* tool.",
+        options: [
+          {
+            flags: "--task-id <id>",
+            description: "Steel task ID returned by ui_agent_ask or any ui_* tool dispatch.",
+            arg: "task_id",
+            type: "string",
+            required: true
+          }
+        ]
+      },
+      {
+        name: "pending",
+        tool: "ui_agent_list_pending",
+        summary: "Returns all Steel browser automation tasks that are currently paused waiting for human input (stop_reason 'ask').",
+        options: []
+      },
+      {
+        name: "reply",
+        tool: "ui_agent_reply",
+        summary: "Resumes a Steel browser automation task that paused with stop_reason 'ask'.",
+        options: [
+          {
+            flags: "--task-id <id>",
+            description: "Steel task ID to resume (from ui_agent_list_pending).",
+            arg: "task_id",
+            type: "string",
+            required: true
+          },
+          {
+            flags: "--reply <reply>",
+            description: "Your answer to the agent's question (e.g. a 2FA code or confirmation).",
+            arg: "reply",
+            type: "string",
+            required: true
+          }
+        ]
+      },
+      {
+        name: "usage",
+        tool: "ui_agent_usage",
+        summary: "Returns an estimated Anthropic API cost for Steel agent tasks dispatched this calendar month.",
+        options: []
+      },
+      {
+        name: "schedule list",
+        tool: "ui_agent_schedule_list",
+        summary: "Lists all Steel recurring schedules stored in KV.",
+        options: []
+      },
+      {
+        name: "schedule create",
+        tool: "ui_agent_schedule_create",
+        summary: "Creates a recurring Steel agent run on a cron schedule.",
+        requireConfirm: true,
+        options: [
+          {
+            flags: "--name <name>",
+            description: "Human-readable name for this schedule.",
+            arg: "name",
+            type: "string",
+            required: true
+          },
+          {
+            flags: "--cron <cron>",
+            description: "Standard 5-field cron expression (minute hour day month weekday).",
+            arg: "cron",
+            type: "string",
+            required: true
+          },
+          {
+            flags: "--prompt-template <template>",
+            description: "Agent prompt/task template the Steel agent will execute on each run.",
+            arg: "prompt_template",
+            type: "string",
+            required: true
+          }
+        ]
+      },
+      {
+        name: "schedule pause",
+        tool: "ui_agent_schedule_pause",
+        summary: "Pauses an active Steel recurring schedule.",
+        requireConfirm: true,
+        options: [
+          {
+            flags: "--schedule-id <id>",
+            description: "ID of the schedule to pause.",
+            arg: "schedule_id",
+            type: "string",
+            required: true
+          }
+        ]
+      },
+      {
+        name: "schedule resume",
+        tool: "ui_agent_schedule_resume",
+        summary: "Resumes a paused Steel recurring schedule.",
+        requireConfirm: true,
+        options: [
+          {
+            flags: "--schedule-id <id>",
+            description: "ID of the schedule to resume.",
+            arg: "schedule_id",
+            type: "string",
+            required: true
+          }
+        ]
+      },
+      {
+        name: "schedule delete",
+        tool: "ui_agent_schedule_delete",
+        summary: "Permanently deletes a Steel recurring schedule.",
+        requireConfirm: true,
+        options: [
+          {
+            flags: "--schedule-id <id>",
+            description: "ID of the schedule to delete.",
+            arg: "schedule_id",
+            type: "string",
+            required: true
+          }
+        ]
+      }
+    ]
+  },
+  {
+    name: "portal",
+    summary: "OCS portal changes that only exist in the web UI, driven by Kapture",
+    commands: [
+      {
+        name: "account create",
+        tool: "ui_create_account",
+        summary: "Creates a new sub-account under the reseller via the OCS web dashboard.",
+        write: true,
+        options: [
+          {
+            flags: "--name <name>",
+            description: "Name for the new account.",
+            arg: "name",
+            type: "string",
+            required: true
+          },
+          {
+            flags: "--description <description>",
+            description: "Optional description.",
+            arg: "description",
+            type: "string"
+          },
+          {
+            flags: "--initial-balance <n>",
+            description: "Initial balance in account currency (default 0).",
+            arg: "initial_balance",
+            type: "number"
+          }
+        ]
+      },
+      {
+        name: "steering build",
+        tool: "ui_build_steering_list",
+        summary: "Change which mobile operators sit on a steering list that already exists, by driving the OCS web dashboard \u2014 the OCS REST API cannot edit list membership.",
+        write: true,
+        options: [
+          {
+            flags: "--steering-list-id <n>",
+            description: "ID of the steering list to modify.",
+            arg: "steering_list_id",
+            type: "number",
+            required: true
+          },
+          {
+            flags: "--add-operators <list>",
+            description: "MCC-MNC codes to add (e.g. ['20801', '26201']). Comma-separated.",
+            arg: "add_operators",
+            type: "string[]"
+          },
+          {
+            flags: "--remove-operators <list>",
+            description: "MCC-MNC codes to remove. Comma-separated.",
+            arg: "remove_operators",
+            type: "string[]"
+          },
+          {
+            flags: "--operator-type <type>",
+            description: 'Whether operators are priority or excluded. One of: priority, excluded. Default "priority".',
+            arg: "operator_type",
+            type: "string"
+          }
+        ]
+      },
+      {
+        name: "steering create",
+        tool: "ui_create_steering_list",
+        summary: "Create a new, empty network steering list (OPLMN preference set) by driving the OCS web dashboard, because the OCS REST API cannot create one.",
+        write: true,
+        options: [
+          {
+            flags: "--name <name>",
+            description: "Name for the new steering list.",
+            arg: "name",
+            type: "string",
+            required: true
+          },
+          {
+            flags: "--description <description>",
+            description: "Optional description for the steering list.",
+            arg: "description",
+            type: "string"
+          }
+        ]
+      },
+      {
+        name: "steering set-account",
+        tool: "ui_set_account_steering_list",
+        summary: "Assigns or removes a steering list at the account level via the OCS web dashboard.",
+        write: true,
+        options: [
+          {
+            flags: "--account-id <n>",
+            description: "Account ID to assign the steering list to.",
+            arg: "account_id",
+            type: "number",
+            required: true
+          },
+          {
+            flags: "--steering-list-id <n>",
+            description: "Steering list ID to assign (0 to remove/unset).",
+            arg: "steering_list_id",
+            type: "number",
+            required: true
+          }
+        ]
+      },
+      {
+        name: "destinations create",
+        tool: "ui_create_destination_list",
+        summary: "Creates a new destination list (named set of phone number prefixes for MOC call permissions) via the OCS web dashboard.",
+        write: true,
+        options: [
+          {
+            flags: "--name <name>",
+            description: "Name for the new destination list.",
+            arg: "name",
+            type: "string",
+            required: true
+          },
+          {
+            flags: "--prefixes <list>",
+            description: "Phone number prefixes to include (e.g. ['+31', '+49']). Comma-separated.",
+            arg: "prefixes",
+            type: "string[]"
+          },
+          {
+            flags: "--description <description>",
+            description: "Optional description.",
+            arg: "description",
+            type: "string"
+          }
+        ]
+      },
+      {
+        name: "destinations edit",
+        tool: "ui_edit_destination_list",
+        summary: "Edits an existing destination list via the OCS web dashboard.",
+        write: true,
+        options: [
+          {
+            flags: "--destination-list-id <n>",
+            description: "ID of the destination list to edit.",
+            arg: "destination_list_id",
+            type: "number",
+            required: true
+          },
+          {
+            flags: "--add-prefixes <list>",
+            description: "Prefixes to add. Comma-separated.",
+            arg: "add_prefixes",
+            type: "string[]"
+          },
+          {
+            flags: "--remove-prefixes <list>",
+            description: "Prefixes to remove. Comma-separated.",
+            arg: "remove_prefixes",
+            type: "string[]"
+          },
+          {
+            flags: "--new-name <name>",
+            description: "Rename the destination list.",
+            arg: "new_name",
+            type: "string"
+          }
+        ]
+      },
+      {
+        name: "destinations delete",
+        tool: "ui_delete_destination_list",
+        summary: "Delete a destination list \u2014 a named set of phone-number prefixes \u2014 by driving the OCS web dashboard.",
+        write: true,
+        options: [
+          {
+            flags: "--destination-list-id <n>",
+            description: "ID of the destination list to delete.",
+            arg: "destination_list_id",
+            type: "number",
+            required: true
+          }
+        ]
+      },
+      {
+        name: "zones edit",
+        tool: "ui_edit_location_zone",
+        summary: "Edits an existing location zone via the OCS web dashboard. `create_location_zone` is available via API; edit is UI-only.",
+        write: true,
+        options: [
+          {
+            flags: "--zone-id <n>",
+            description: "ID of the location zone to edit.",
+            arg: "zone_id",
+            type: "number",
+            required: true
+          },
+          {
+            flags: "--new-name <name>",
+            description: "Rename the location zone.",
+            arg: "new_name",
+            type: "string"
+          },
+          {
+            flags: "--add-countries <list>",
+            description: "ISO country codes to add (e.g. ['NL', 'DE']). Comma-separated.",
+            arg: "add_countries",
+            type: "string[]"
+          },
+          {
+            flags: "--remove-countries <list>",
+            description: "ISO country codes to remove. Comma-separated.",
+            arg: "remove_countries",
+            type: "string[]"
+          }
+        ]
+      },
+      {
+        name: "zones delete",
+        tool: "ui_delete_location_zone",
+        summary: "Delete a location zone by driving the OCS web dashboard, because the OCS REST API can create a zone (`create_location_zone`) but not remove one.",
+        write: true,
+        options: [
+          {
+            flags: "--zone-id <n>",
+            description: "ID of the location zone to delete.",
+            arg: "zone_id",
+            type: "number",
+            required: true
+          }
+        ]
+      },
+      {
+        name: "templates delete",
+        tool: "ui_delete_package_template",
+        summary: "Remove a package template from the reseller's product catalogue for good, by driving the OCS web dashboard \u2014 the OCS REST API cannot delete a template.",
+        write: true,
+        options: [
+          {
+            flags: "--template-id <n>",
+            description: "ID of the package template to delete.",
+            arg: "template_id",
+            type: "number",
+            required: true
+          }
+        ]
+      }
+    ]
+  },
+  {
+    name: "events",
+    summary: "Buffered OCS event history per subscriber",
+    commands: [
+      {
+        name: "ocs",
+        tool: "list_recent_ocs_events",
+        summary: "Return the last N OCS events buffered for a given ICCID.",
+        options: [
+          {
+            flags: "--iccid <iccid>",
+            description: "ICCID, 19 or 20 digits, ITU-T E.118 format.",
+            arg: "iccid",
+            type: "string",
+            required: true
+          },
+          {
+            flags: "--limit <n>",
+            description: "Max events to return, newest first. Default 20.",
+            arg: "limit",
+            type: "number"
+          },
+          {
+            flags: "--event-types <list>",
+            description: "Filter to specific event types. Comma-separated.",
+            arg: "event_types",
+            type: "string[]"
+          },
+          {
+            flags: "--since <since>",
+            description: "ISO-8601 timestamp; only events after this point.",
+            arg: "since",
+            type: "string"
+          }
+        ]
+      },
+      {
+        name: "countries",
+        tool: "subscriber_country_history",
+        summary: "Return cross-border movement history for a subscriber from Relay LU events.",
+        options: [
+          {
+            flags: "--subscriber-id <id>",
+            description: "Subscriber ICCID (19\u201320 digits, ITU-T E.118).",
+            arg: "subscriberId",
+            type: "string",
+            required: true
+          },
+          {
+            flags: "--limit <n>",
+            description: "Maximum number of events to return, newest first (default 20, max 50). Default 20.",
+            arg: "limit",
+            type: "number"
+          }
+        ]
+      },
+      {
+        name: "depletion",
+        tool: "subscriber_depletion_events",
+        summary: "Look up bundle depletion events for a subscriber (or list recent fleet-wide depletions).",
+        options: [
+          {
+            flags: "--subscriber-id <id>",
+            description: "OCS subscriber ID to look up.",
+            arg: "subscriberId",
+            type: "string"
+          },
+          {
+            flags: "--since <since>",
+            description: "ISO-8601 timestamp \u2014 only return events at or after this time (for single-subscriber lookup).",
+            arg: "since",
+            type: "string"
+          }
+        ]
+      }
+    ]
+  },
+  {
+    name: "panels",
+    summary: "MCP UI surfaces. A terminal sees the underlying data, not the panel.",
+    commands: [
+      {
+        name: "fleet",
+        tool: "fleet_health_app",
+        summary: "Fleet overview as a UI panel. Prefer `carrier intelligence fleet-health` in a terminal; use --json to read the panel's data.",
+        options: [
+          {
+            flags: "--account-id <n>",
+            description: "Filter to a specific account (omit for all).",
+            arg: "accountId",
+            type: "number"
+          }
+        ]
+      },
+      {
+        name: "topup",
+        tool: "balance_topup_form",
+        summary: "Adjust the OCS account balance behind one subscriber. Previews unless --preview false.",
+        requireConfirm: true,
+        options: [
+          {
+            flags: "--iccid <iccid>",
+            description: "The subscriber ICCID for the account lookup.",
+            arg: "iccid",
+            type: "string",
+            required: true
+          },
+          {
+            flags: "--delta <n>",
+            description: "Amount to add (positive) or deduct (negative) from the account balance.",
+            arg: "delta",
+            type: "number",
+            required: true
+          },
+          {
+            flags: "--preview <bool>",
+            description: "If true, return preview without writing. Default true.",
+            arg: "preview",
+            type: "boolean"
+          }
+        ]
+      },
+      {
+        name: "provision",
+        tool: "provision_esim_wizard",
+        summary: "Step through the provisioning wizard. Pass --step confirm to execute; every earlier step only reads.",
+        options: [
+          {
+            flags: "--step <step>",
+            description: "Current wizard step. One of: init, select-package, preview, confirm.",
+            arg: "step",
+            type: "string",
+            required: true
+          },
+          {
+            flags: "--wizard-id <id>",
+            description: "Wizard session ID (absent on init).",
+            arg: "wizardId",
+            type: "string"
+          },
+          {
+            flags: "--subscriber-iccid <iccid>",
+            description: "Subscriber ICCID (required for select-package).",
+            arg: "subscriber_iccid",
+            type: "string"
+          },
+          {
+            flags: "--package-template-id <n>",
+            description: "Package template ID (required for preview).",
+            arg: "package_template_id",
+            type: "number"
+          }
+        ]
+      }
+    ]
+  },
+  {
+    name: "env",
+    summary: "This environment: credentials, catalog and machine-readable context",
+    commands: [
+      {
+        name: "info",
+        tool: "environment_info",
+        summary: "View your Carrier environment configuration \u2014 active organization, reseller details, connected services, and deployment environment.",
+        options: []
+      },
+      {
+        name: "credentials",
+        tool: "credential_status",
+        summary: "Report on the stored eSIMVault credential without changing it: whether a token is present, whether it is encrypted, how old it is, and whether rotation is recommended (over 90 days).",
+        options: []
+      },
+      {
+        name: "rotate",
+        tool: "rotate_credentials",
+        summary: "Replace the stored eSIMVault API token with one you supply.",
+        options: [
+          {
+            flags: "--new-token <token>",
+            description: "New eSIMVault API token to encrypt and store.",
+            arg: "new_token",
+            type: "string",
+            required: true
+          },
+          {
+            flags: "--confirm <bool>",
+            description: "Confirm rotation \u2014 this will replace the current token immediately.",
+            arg: "confirm",
+            type: "boolean",
+            required: true
+          }
+        ]
+      },
+      {
+        name: "catalog",
+        tool: "service_catalog",
+        summary: "Browse the Carrier service catalog \u2014 discover available services, their requirements, endpoints, and documentation.",
+        options: [
+          {
+            flags: "--category <category>",
+            description: "Filter services by category. One of: connectivity, analytics, marketplace, coverage, billing, integration, dashboard.",
+            arg: "category",
+            type: "string"
+          },
+          {
+            flags: "--tier <tier>",
+            description: "Filter services accessible at this tier level. One of: free, pro, enterprise.",
+            arg: "tier",
+            type: "string"
+          }
+        ]
+      },
+      {
+        name: "llm-context",
+        tool: "llm_context",
+        summary: "Generate a comprehensive LLM context document describing your Carrier environment, available tools, current tier, usage patterns, and best practices.",
+        options: [
+          {
+            flags: "--format <format>",
+            description: "Output format for the context document (default: markdown). One of: markdown, json, yaml.",
+            arg: "format",
+            type: "string"
+          },
+          {
+            flags: "--include-examples <bool>",
+            description: "Include example tool invocations (default: true).",
+            arg: "include_examples",
+            type: "boolean"
+          }
+        ]
+      },
+      {
+        name: "describe",
+        tool: "carrier_ask_describe",
+        summary: "Get full documentation for any registered Carrier MCP tool: description, parameters, 2-3 example invocations, required scope, destructive flag, and guidance.",
+        options: [
+          {
+            flags: "--tool-name <name>",
+            description: "The exact MCP tool name to describe (e.g. 'assign_package', 'hlr_set_bitrate').",
+            arg: "tool_name",
+            type: "string",
+            required: true
+          }
+        ]
+      }
+    ]
+  },
+  {
+    name: "brand",
+    summary: "Storefront brand assets",
+    commands: [
+      {
+        name: "logo",
+        tool: "generate_storefront_logo",
+        summary: "Generate a storefront logo (SVG always; PNG when an image key is configured on the Carrier worker).",
+        options: [
+          {
+            flags: "--name <name>",
+            description: "Brand / shop name, e.g. Bananas.",
+            arg: "name",
+            type: "string",
+            required: true
+          },
+          {
+            flags: "--accent <accent>",
+            description: "Accent hex, e.g. #FF8A00.",
+            arg: "accent",
+            type: "string"
+          },
+          {
+            flags: "--tagline <tagline>",
+            description: "Optional tagline for AI-enhanced marks.",
+            arg: "tagline",
+            type: "string"
+          }
+        ]
+      }
+    ]
+  }
+  // </generated:catalog-domains>
+];
+function capabilityTarget(cmd) {
+  return cmd.transport === "rest" ? `${cmd.restMethod} ${cmd.restPath}` : cmd.tool;
+}
+
+// src/cli/lib/capability.ts
+import * as p2 from "@clack/prompts";
+import pc3 from "picocolors";
+
+// src/cli/lib/rest.ts
+var DEFAULT_ERROR_HINTS2 = [
+  "Re-check the arguments: carrier <domain> <command> --help",
+  "Or open Claude and ask there with full tool routing"
+];
+function resolveApiKey() {
+  return process.env.CARRIER_API_KEY?.trim() || process.env.CARRIER_ORG_API_KEY?.trim() || null;
+}
+function ocsTokenOnly() {
+  return Boolean(
+    process.env.ESIMVAULT_API_TOKEN?.trim() || process.env.CARRIER_OCS_API_TOKEN?.trim()
+  );
+}
+function applyPath(path, args) {
+  const rest = { ...args };
+  const missing = [];
+  const filled = path.replace(/\{(\w+)\}/g, (_match, name) => {
+    const value = rest[name];
+    if (value === void 0 || value === null || value === "") {
+      missing.push(name);
+      return `{${name}}`;
+    }
+    delete rest[name];
+    return encodeURIComponent(String(value));
+  });
+  return { path: filled, rest, missing };
+}
+function queryString(args) {
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(args)) {
+    if (value === void 0 || value === null) continue;
+    params.set(key, String(value));
+  }
+  const qs = params.toString();
+  return qs ? `?${qs}` : "";
+}
+function bodyText(raw) {
+  const trimmed = raw.trim();
+  if (!trimmed) return "";
+  try {
+    const parsed = JSON.parse(trimmed);
+    if (typeof parsed.error === "string") return parsed.error;
+    if (typeof parsed.message === "string") return parsed.message;
+    return trimmed;
+  } catch {
+    return trimmed;
+  }
+}
+async function callRestEndpoint(method, path, args, opts = {}) {
+  const token = resolveApiKey() ?? await getAccessToken();
+  if (!token) {
+    return {
+      ok: false,
+      text: withNextStep(
+        ocsTokenOnly() ? "Not signed in. An eSIMVault/OCS token is set, but the Carrier API only accepts Carrier credentials." : "Not signed in.",
+        [
+          "Sign in from this terminal: carrier login",
+          "No account yet? carrier open signup",
+          "Headless/CI instead: export CARRIER_API_KEY=ak_\u2026 from Console \u2192 Settings \u2192 API Keys"
+        ]
+      )
+    };
+  }
+  const { path: resolvedPath, rest, missing } = applyPath(path, args);
+  if (missing.length) {
+    return {
+      ok: false,
+      text: withNextStep(`Cannot build ${method} ${path}.`, [
+        `Missing path value(s): ${missing.join(", ")}`,
+        "See every flag: carrier <domain> <command> --help"
+      ])
+    };
+  }
+  const sendsBody = method === "POST" || method === "PUT" || method === "PATCH";
+  const url = `${API_URL}${resolvedPath}${sendsBody ? "" : queryString(rest)}`;
+  const headers = {
+    Authorization: `Bearer ${token}`,
+    Accept: "application/json",
+    "User-Agent": `carrier-cli/${CARRIER_VERSION}`
+  };
+  if (sendsBody) headers["Content-Type"] = "application/json";
+  if (opts.confirmToken) headers["X-Confirm-Token"] = opts.confirmToken;
+  const timeoutMs = mcpTimeoutMs();
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, {
+      method,
+      headers,
+      signal: controller.signal,
+      body: sendsBody ? JSON.stringify(rest) : void 0
+    });
+    const raw = await res.text();
+    if (res.status === 202) {
+      let confirmToken;
+      let expires;
+      let message = "";
+      try {
+        const parsed = JSON.parse(raw);
+        confirmToken = parsed.confirm_token;
+        expires = parsed.expires_in_seconds;
+        message = parsed.message ?? "";
+      } catch {
+      }
+      return {
+        ok: false,
+        text: withNextStep(
+          message || `${method} ${path} needs an explicit confirmation.`,
+          confirmToken ? [
+            `Re-run the same command with: --confirm-token ${confirmToken}`,
+            `The token is single-use and expires in ${expires ?? 120}s.`
+          ] : ["The server asked for confirmation but returned no token \u2014 retry the command."]
+        )
+      };
+    }
+    if (res.status === 401 || res.status === 403) {
+      return {
+        ok: false,
+        text: withNextStep(
+          `Carrier API returned ${res.status} (auth rejected).`,
+          [
+            "Confirm CARRIER_API_KEY is a valid org key (ak_\u2026) from app.carrier.llc",
+            "Or sign in from this terminal: carrier login",
+            ...res.status === 403 ? ["A 403 here usually means the key lacks write scope."] : []
+          ]
+        )
+      };
+    }
+    if (!res.ok) {
+      return {
+        ok: false,
+        text: withNextStep(
+          redact(`${method} ${path} failed (${res.status}). ${bodyText(raw).slice(0, 500)}`),
+          opts.errorHints ?? DEFAULT_ERROR_HINTS2
+        )
+      };
+    }
+    return { ok: true, text: raw.trim() || JSON.stringify({ status: res.status }) };
+  } catch (e) {
+    const aborted = e instanceof Error && (e.name === "AbortError" || e.name === "TimeoutError");
+    if (aborted) {
+      const secs = Math.round(timeoutMs / 1e3);
+      return {
+        ok: false,
+        text: withNextStep(`${method} ${path} timed out after ${secs}s (no response).`, [
+          `Raise the deadline for one slow call: CARRIER_MCP_TIMEOUT_MS=${timeoutMs * 2} carrier \u2026`,
+          "Confirm the service is up: check network access to https://api.carrier.llc"
+        ])
+      };
+    }
+    const msg = e instanceof Error ? e.message : String(e);
+    return {
+      ok: false,
+      text: withNextStep(redact(`Could not reach the Carrier API: ${msg}`), [
+        "Verify outbound HTTPS to api.carrier.llc",
+        "Use the interactive Claude path while offline from this machine"
+      ])
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// src/cli/lib/capability.ts
+var MAX_PRETTY_CHARS = 8e3;
+function optionKey(flags) {
+  const long = flags.split(/[ ,|]+/).find((t) => t.startsWith("--"));
+  if (!long) throw new Error(`Option "${flags}" has no long flag`);
+  return long.replace(/^--/, "").split("-").map((part, i) => i === 0 ? part : part.charAt(0).toUpperCase() + part.slice(1)).join("");
+}
+function setArg(target, path, value) {
+  const parts = path.split(".");
+  let node = target;
+  for (const part of parts.slice(0, -1)) {
+    const next = node[part];
+    if (typeof next !== "object" || next === null) node[part] = {};
+    node = node[part];
+  }
+  node[parts[parts.length - 1]] = value;
+}
+function coerce(opt, raw) {
+  if (opt.type === "boolean") {
+    if (raw === true) return { value: true };
+    const text3 = String(raw).toLowerCase();
+    if (text3 === "true") return { value: true };
+    if (text3 === "false") return { value: false };
+    return { error: `${opt.flags} expects true or false, got "${String(raw)}"` };
+  }
+  if (opt.type === "number") {
+    const n = Number(raw);
+    if (!Number.isFinite(n)) return { error: `${opt.flags} expects a number, got "${String(raw)}"` };
+    return { value: n };
+  }
+  if (opt.type === "string[]" || opt.type === "number[]") {
+    const items = String(raw).split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+    if (!items.length) return { error: `${opt.flags} expects a comma-separated list, got "${String(raw)}"` };
+    if (opt.type === "string[]") return { value: items };
+    const numbers = items.map(Number);
+    const bad = items.find((_, i) => !Number.isFinite(numbers[i]));
+    if (bad !== void 0) return { error: `${opt.flags} expects numbers, got "${bad}"` };
+    return { value: numbers };
+  }
+  return { value: String(raw) };
+}
+function buildToolArgs(cmd, opts) {
+  const args = {};
+  const errors = [];
+  const notes = [];
+  for (const opt of cmd.options) {
+    const raw = opts[optionKey(opt.flags)];
+    if (raw === void 0 || raw === false) {
+      if (opt.required) errors.push(`Missing required ${opt.flags}`);
+      continue;
+    }
+    const { value, error } = coerce(opt, raw);
+    if (error) errors.push(error);
+    else setArg(args, opt.arg, value);
+  }
+  if (cmd.requireOneOf && !cmd.requireOneOf.some((name) => args[name] !== void 0)) {
+    const flags = cmd.options.filter((opt) => cmd.requireOneOf.includes(opt.arg)).map((opt) => opt.flags);
+    errors.push(`Pass one of: ${flags.join(", ")}`);
+  }
+  if (cmd.usageWindow) {
+    const start = args.startDate;
+    const end = args.endDate;
+    if (!start && !end) {
+      const window = lastNDaysPeriod();
+      args.startDate = window.start;
+      args.endDate = window.end;
+      notes.push(`Window defaulted to ${window.start} \u2026 ${window.end} (last ${OCS_MAX_USAGE_WINDOW_DAYS} days).`);
+    } else if (!start || !end) {
+      errors.push("Pass both --start and --end, or neither for the last 7 days");
+    } else {
+      const clamped = clampUsagePeriod(start, end);
+      if (clamped.start !== start) {
+        notes.push(
+          `Start moved to ${clamped.start} \u2014 OCS rejects windows wider than ${OCS_MAX_USAGE_WINDOW_DAYS} days.`
+        );
+      }
+      args.startDate = clamped.start;
+      args.endDate = clamped.end;
+    }
+  }
+  if (cmd.write && cmd.transport !== "rest") args.dry_run = true;
+  return { args, errors, notes };
+}
+function formatJsonOutput(text3) {
+  try {
+    JSON.parse(text3);
+    return text3;
+  } catch {
+    return JSON.stringify(text3);
+  }
+}
+async function runCapability(domain, cmd, opts) {
+  const label = `${domain.name} ${cmd.name}`;
+  const quiet = opts.json === true;
+  const { args, errors, notes } = buildToolArgs(cmd, opts);
+  if (cmd.write && opts.commit === true) delete args.dry_run;
+  if (cmd.requireConfirm && opts.confirm !== true) {
+    errors.push(`${capabilityTarget(cmd)} has no preview mode. Pass --confirm to run it for real.`);
+  }
+  if (errors.length) {
+    const message = withNextStep(`Cannot run \`carrier ${label}\`.`, [
+      ...errors,
+      `See every flag: carrier ${label} --help`
+    ]);
+    if (quiet) console.error(message);
+    else p2.log.error(message);
+    process.exitCode = 1;
+    return;
+  }
+  if (cmd.transport === "rest" && cmd.write && opts.commit !== true) {
+    const preview = [
+      `${cmd.restMethod} ${cmd.restPath}`,
+      JSON.stringify(args, null, 2),
+      "",
+      "Dry run \u2014 nothing sent. Re-run with --commit to apply."
+    ].join("\n");
+    if (quiet) process.stdout.write(`${formatJsonOutput(preview)}
+`);
+    else p2.note(preview, `carrier ${label}`);
+    return;
+  }
+  const dryRun = cmd.write === true && args.dry_run === true;
+  const warnings = dryRun ? [...notes, "Dry run \u2014 nothing changes. Re-run with --commit to apply."] : notes;
+  for (const note4 of warnings) {
+    if (quiet) console.error(note4);
+    else p2.log.info(pc3.dim(note4));
+  }
+  const target = capabilityTarget(cmd);
+  const errorHints = [
+    `Check the arguments: carrier ${label} --help`,
+    'Or describe the task in words: carrier ask "\u2026"'
+  ];
+  const s = quiet ? null : p2.spinner();
+  s?.start(`Calling ${target}`);
+  const result = cmd.transport === "rest" ? await callRestEndpoint(cmd.restMethod, cmd.restPath, args, {
+    errorHints,
+    confirmToken: opts.confirmToken
+  }) : await callMcpTool(cmd.tool, args, { errorHints });
+  s?.stop(result.ok ? "Done" : "Failed");
+  if (!result.ok) {
+    if (quiet) console.error(result.text);
+    else p2.log.error(result.text);
+    process.exitCode = 1;
+    return;
+  }
+  if (quiet) {
+    process.stdout.write(`${formatJsonOutput(result.text)}
+`);
+    return;
+  }
+  const body = result.text.length > MAX_PRETTY_CHARS ? `${result.text.slice(0, MAX_PRETTY_CHARS)}
+\u2026truncated. Re-run with --json for the whole response.` : result.text;
+  p2.note(body, target);
+}
+function parseArgValue(text3) {
+  if (text3 === "true") return true;
+  if (text3 === "false") return false;
+  if (text3 === "null") return null;
+  if (/^[[{"]/.test(text3)) {
+    try {
+      return JSON.parse(text3);
+    } catch {
+      return text3;
+    }
+  }
+  if (/^-?\d+(?:\.\d+)?$/.test(text3)) {
+    const n = Number(text3);
+    if (Number.isFinite(n) && String(n) === text3) return n;
+  }
+  return text3;
+}
+async function runRawTool(name, pairs, opts) {
+  const quiet = opts.json === true;
+  const args = {};
+  const errors = [];
+  for (const pair of pairs) {
+    const eq = pair.indexOf("=");
+    if (eq < 1) {
+      errors.push(`--arg ${pair} is not key=value`);
+      continue;
+    }
+    setArg(args, pair.slice(0, eq), parseArgValue(pair.slice(eq + 1)));
+  }
+  if (errors.length) {
+    const message = withNextStep(`Cannot call \`${name}\`.`, [
+      ...errors,
+      "Arguments look like: --arg iccid=8931000000000000000 --arg limit=20"
+    ]);
+    if (quiet) console.error(message);
+    else p2.log.error(message);
+    process.exitCode = 1;
+    return;
+  }
+  const s = quiet ? null : p2.spinner();
+  s?.start(`Calling ${name}`);
+  const result = await callMcpTool(name, args, {
+    errorHints: [
+      "List every tool this server registers: carrier env catalog",
+      'Or describe the task in words: carrier ask "\u2026"'
+    ]
+  });
+  s?.stop(result.ok ? "Done" : "Failed");
+  if (!result.ok) {
+    if (quiet) console.error(result.text);
+    else p2.log.error(result.text);
+    process.exitCode = 1;
+    return;
+  }
+  if (quiet) {
+    process.stdout.write(`${formatJsonOutput(result.text)}
+`);
+    return;
+  }
+  const body = result.text.length > MAX_PRETTY_CHARS ? `${result.text.slice(0, MAX_PRETTY_CHARS)}
+\u2026truncated. Re-run with --json for the whole response.` : result.text;
+  p2.note(body, name);
+}
+
+// src/cli/index.ts
+var VERSION = CARRIER_VERSION;
+function header() {
+  p3.intro(`${pc4.bold(pc4.yellow("\u25C6 carrier"))} ${pc4.dim("\xB7 the Stripe of telecom \u2014 CLI v" + VERSION)}`);
+}
+function ok(msg) {
+  p3.log.success(pc4.green(msg));
+}
+function info(msg) {
+  p3.log.info(msg);
+}
+function fail(msg, next) {
+  p3.log.error(msg);
+  p3.note(next.map((s) => `\u2192 ${s}`).join("\n"), "What to do next");
+}
+async function promptBrand(seed) {
+  const name = await p3.text({
+    message: "Brand name",
+    placeholder: seed.name,
+    defaultValue: seed.name
+  });
+  if (p3.isCancel(name)) process.exit(0);
+  const domain = await p3.text({
+    message: "Domain",
+    placeholder: seed.domain,
+    defaultValue: seed.domain
+  });
+  if (p3.isCancel(domain)) process.exit(0);
+  const accent = await p3.text({
+    message: "Accent color (hex)",
+    placeholder: seed.colors.accent,
+    defaultValue: seed.colors.accent
+  });
+  if (p3.isCancel(accent)) process.exit(0);
+  const supportEmail = await p3.text({
+    message: "Support email",
+    placeholder: `support@${domain}`,
+    defaultValue: `support@${domain}`
+  });
+  if (p3.isCancel(supportEmail)) process.exit(0);
+  const accentDark = deriveAccentDark(accent, seed);
+  const isCarrier = name === CARRIER_BRAND.name && domain === CARRIER_BRAND.domain;
+  return {
+    ...seed,
+    name,
+    legalName: name,
+    tagline: isCarrier ? seed.tagline : `Mobile connectivity by ${name}.`,
+    domain,
+    supportEmail,
+    supportUrl: `https://${domain}/help`,
+    supportWhatsapp: isCarrier ? seed.supportWhatsapp : "",
+    social: isCarrier ? seed.social : {},
+    colors: { ...seed.colors, accent, accentDark }
+  };
+}
+async function doPluginInstall() {
+  const s = p3.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 ? pc4.green("registered") : pc4.yellow("manual")}  \xB7  marketplace: ${r.marketplaceAdded ? pc4.green("added") : pc4.yellow("manual")}  \xB7  install: ${r.pluginInstalled ? pc4.green("done") : pc4.yellow("manual")}`
+  );
+  p3.note(installAuthGuidance().join("\n"), "OAuth on first use (Entry A)");
+  if (!r.claudeFound || r.notes.length) {
+    p3.note(manualCommands().join("\n"), "Finish wiring (run in your terminal)");
+    if (r.notes.length) info(pc4.dim(r.notes.join("\n")));
+    p3.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 {
+    p3.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 = p3.spinner();
+  s.start(`Scaffolding ${brand.name} storefront \u2192 ${target}`);
+  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");
@@ -3085,10 +4471,16 @@ for (const domain of CLI_DOMAINS) {
       }
       parent = nested;
     }
-    const sub = parent.command(parts[parts.length - 1]).description(cmd.write ? `${cmd.summary} Dry run unless --commit.` : cmd.summary);
+    const sub = parent.command(parts[parts.length - 1]).description(
+      cmd.write ? `${cmd.summary} Dry run unless --commit.` : cmd.requireConfirm ? `${cmd.summary} Refuses without --confirm.` : cmd.summary
+    );
     for (const opt of cmd.options) sub.option(opt.flags, opt.description);
     sub.option("--json", "Print the raw tool response on stdout and nothing else");
     if (cmd.write) sub.option("--commit", "Apply the change instead of previewing it");
+    if (cmd.transport === "rest") {
+      sub.option("--confirm-token <token>", "Token from a prior 202, to confirm this call");
+    }
+    if (cmd.requireConfirm) sub.option("--confirm", "Required. This call takes effect immediately.");
     sub.action(async (opts) => {
       if (opts.json !== true) header();
       await runCapability(domain, cmd, opts);
@@ -3096,6 +4488,16 @@ for (const domain of CLI_DOMAINS) {
     });
   }
 }
+program.command("tool <name>").description("Call one MCP tool directly, by name, with raw arguments").option(
+  "--arg <key=value>",
+  "One tool argument. Repeat for more. Dots nest: context.iccid=8931\u2026",
+  (value, prev) => [...prev, value],
+  []
+).option("--json", "Print the raw tool response on stdout and nothing else").action(async (name, o) => {
+  if (o.json !== true) header();
+  await runRawTool(name, o.arg, o);
+  if (o.json !== true) p3.outro("");
+});
 program.command("dash [domain]").description(`Render a status screen in the terminal: ${DASH_DOMAINS.join(" | ")}`).option("--json", "Emit the screen model as JSON instead of drawing it").option("--no-color", "Plain text, safe to pipe").option("--width <n>", "Terminal width override").action(async (domain, o) => {
   const target = domain ?? "fleet";
   if (!isDashDomain(target)) {