@carrierllc/mcp 0.2.19 → 0.2.20

package/dist/cli.js

@@ -1,9 +1,16 @@
 #!/usr/bin/env node
+import {
+  CARRIER_VERSION,
+  OCS_MAX_USAGE_WINDOW_DAYS,
+  clampUsagePeriod,
+  generateStorefrontLogo,
+  lastNDaysPeriod
+} from "./chunk-NHQDO2E7.js";
 
 // src/cli/index.ts
 import { Command } from "commander";
-import * as p2 from "@clack/prompts";
-import pc3 from "picocolors";
+import * as p3 from "@clack/prompts";
+import pc4 from "picocolors";
 import { resolve as resolve2 } from "path";
 
 // src/cli/lib/brand.ts
@@ -224,12 +231,12 @@ async function replaceInTree(dir, subs) {
   }
   return touched;
 }
-async function exists(p3) {
-  return existsSync2(p3);
+async function exists(p4) {
+  return existsSync2(p4);
 }
-async function isDir(p3) {
+async function isDir(p4) {
   try {
-    return (await stat(p3)).isDirectory();
+    return (await stat(p4)).isDirectory();
   } catch {
     return false;
   }
@@ -446,8 +453,27 @@ ${socialBody}
   await writeFile(path, src);
 }
 
-// src/cli/lib/site.ts
+// src/cli/lib/logo.ts
+import { mkdir as mkdir2, writeFile as writeFile2 } from "fs/promises";
 import { join as join5 } from "path";
+async function writeStorefrontLogo(target, brand) {
+  const logo = await generateStorefrontLogo({
+    name: brand.name,
+    accent: brand.colors.accent,
+    tagline: brand.tagline
+  });
+  const dir = join5(target, "public", "brand");
+  await mkdir2(dir, { recursive: true });
+  const svgPath = join5(dir, "logo.svg");
+  await writeFile2(svgPath, logo.svg, "utf8");
+  if (logo.pngBase64) {
+    await writeFile2(join5(dir, "logo.png"), Buffer.from(logo.pngBase64, "base64"));
+  }
+  return { path: svgPath, source: logo.source };
+}
+
+// src/cli/lib/site.ts
+import { join as join6 } from "path";
 function slug(s) {
   return s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40) || "storefront";
 }
@@ -462,7 +488,7 @@ async function buildSite(target) {
   return r.ok;
 }
 async function loadStorefrontBrand(target, overrides) {
-  const configPath = join5(target, "src", "brand.config.ts");
+  const configPath = join6(target, "src", "brand.config.ts");
   if (!await exists(configPath)) {
     return { ...CARRIER_BRAND, ...overrides };
   }
@@ -491,7 +517,7 @@ async function loadStorefrontBrand(target, overrides) {
 }
 async function deploySite(target, brand) {
   const projectName = slug(brand.name);
-  const workerBundle = join5(target, ".open-next", "worker.js");
+  const workerBundle = join6(target, ".open-next", "worker.js");
   if (!await exists(workerBundle)) {
     return {
       ok: false,
@@ -510,7 +536,7 @@ async function deploySite(target, brand) {
 
 // src/cli/lib/status.ts
 import { homedir as homedir2 } from "os";
-import { join as join6 } from "path";
+import { join as join7 } 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) {
@@ -555,10 +581,10 @@ function scanMcpServers(servers) {
 }
 async function probeMcpFromConfig() {
   const candidates = [
-    join6(homedir2(), ".claude.json"),
-    join6(claudeHome(), "settings.json"),
-    join6(claudeHome(), ".mcp.json"),
-    join6(process.cwd(), ".mcp.json")
+    join7(homedir2(), ".claude.json"),
+    join7(claudeHome(), "settings.json"),
+    join7(claudeHome(), ".mcp.json"),
+    join7(process.cwd(), ".mcp.json")
   ];
   let best = null;
   let configSeen = false;
@@ -743,6 +769,10 @@ import * as p from "@clack/prompts";
 import pc2 from "picocolors";
 
 // src/cli/lib/ask.ts
+var DEFAULT_ERROR_HINTS = [
+  "Re-check the arguments: carrier <domain> <command> --help",
+  "Or open Claude and ask there with full tool routing"
+];
 function parseRpcBody(raw) {
   const trimmed = raw.trim();
   if (!trimmed) return {};
@@ -753,7 +783,7 @@ function parseRpcBody(raw) {
   if (!dataLine) return {};
   return JSON.parse(dataLine.slice(5).trim());
 }
-async function carrierAsk(intent) {
+async function callMcpTool(tool, args, opts = {}) {
   const token = resolveCliToken();
   if (!token) {
     return {
@@ -761,7 +791,8 @@ async function carrierAsk(intent) {
       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"'
+        'Then retry: carrier ask "show fleet health"',
+        "Or run a discrete command: carrier subscribers list --account-id 123"
       ])
     };
   }
@@ -781,7 +812,7 @@ async function carrierAsk(intent) {
         params: {
           protocolVersion: "2024-11-05",
           capabilities: {},
-          clientInfo: { name: "carrier-cli", version: "0.2.19" }
+          clientInfo: { name: "carrier-cli", version: CARRIER_VERSION }
         }
       })
     });
@@ -819,7 +850,7 @@ async function carrierAsk(intent) {
         jsonrpc: "2.0",
         id: 2,
         method: "tools/call",
-        params: { name: "carrier_ask", arguments: { intent } }
+        params: { name: tool, arguments: args }
       })
     });
     if (!res.ok) {
@@ -836,14 +867,11 @@ async function carrierAsk(intent) {
     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"
-        ])
+        text: withNextStep(json.error.message, opts.errorHints ?? DEFAULT_ERROR_HINTS)
       };
     }
     const parts = json.result?.content ?? [];
-    const text3 = parts.map((p3) => p3.text).filter(Boolean).join("\n").trim() || JSON.stringify(json.result ?? json, null, 2);
+    const text3 = parts.map((p4) => p4.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);
@@ -856,6 +884,18 @@ async function carrierAsk(intent) {
     };
   }
 }
+async function carrierAsk(intent) {
+  return callMcpTool(
+    "carrier_ask",
+    { intent },
+    {
+      errorHints: [
+        "Rephrase the intent more specifically (include ICCID / MSISDN if relevant)",
+        "Or use a discrete command: carrier --help lists every domain"
+      ]
+    }
+  );
+}
 
 // src/cli/lib/home.ts
 function mark(ok2) {
@@ -996,46 +1036,666 @@ async function runHome(opts) {
   }
 }
 
+// src/cli/lib/domains.ts
+var ICCID = {
+  flags: "--iccid <iccid>",
+  description: "Subscriber ICCID",
+  arg: "iccid",
+  type: "string",
+  required: true
+};
+var ACCOUNT_ID = (description) => ({
+  flags: "--account-id <id>",
+  description,
+  arg: "accountId",
+  type: "number"
+});
+var RESELLER_ID = {
+  flags: "--reseller-id <id>",
+  description: "Reseller ID (omit for the token owner's reseller)",
+  arg: "resellerId",
+  type: "number"
+};
+var PACKAGE_ID = {
+  flags: "--package-id <id>",
+  description: "Package ID from `carrier packages list`",
+  arg: "packageId",
+  type: "number",
+  required: true
+};
+var TEMPLATE_ID = {
+  flags: "--template-id <id>",
+  description: "Template ID from `carrier templates list`",
+  arg: "templateId",
+  type: "number",
+  required: true
+};
+var PERIOD = [
+  {
+    flags: "--start <date>",
+    description: "Start date YYYY-MM-DD (default: 7 days ago)",
+    arg: "startDate",
+    type: "string"
+  },
+  {
+    flags: "--end <date>",
+    description: "End date YYYY-MM-DD, max 7 days from start (default: today)",
+    arg: "endDate",
+    type: "string"
+  }
+];
+var CLI_DOMAINS = [
+  {
+    name: "subscribers",
+    summary: "Look up, inspect and change subscribers.",
+    commands: [
+      {
+        name: "list",
+        tool: "list_subscribers",
+        summary: "List subscribers. OCS needs at least one of account/iccid/msisdn/imsi.",
+        options: [
+          ACCOUNT_ID("Filter by account ID"),
+          { flags: "--iccid <iccid>", description: "Filter by ICCID", arg: "iccid", type: "string" },
+          { flags: "--msisdn <msisdn>", description: "Filter by MSISDN", arg: "msisdn", type: "string" },
+          { flags: "--imsi <imsi>", description: "Filter by IMSI", arg: "imsi", type: "string" },
+          { flags: "--status <status>", description: "Filter by status, e.g. ACTIVE", arg: "status", type: "string" },
+          { flags: "--limit <n>", description: "Max rows to return", arg: "limit", type: "number" },
+          { flags: "--offset <n>", description: "Pagination offset", arg: "offset", type: "number" }
+        ]
+      },
+      {
+        name: "get",
+        tool: "get_subscriber",
+        summary: "Full record for one subscriber by ICCID or MSISDN.",
+        options: [
+          { flags: "--iccid <iccid>", description: "Subscriber ICCID", arg: "iccid", type: "string" },
+          { flags: "--msisdn <msisdn>", description: "Subscriber MSISDN", arg: "msisdn", type: "string" },
+          {
+            flags: "--gz-counter",
+            description: "Include the green-zone byte counter",
+            arg: "with_gz_counter",
+            type: "boolean"
+          }
+        ]
+      },
+      {
+        name: "location",
+        tool: "get_subscriber_location",
+        summary: "Last-known location from the most recent cell tower usage.",
+        options: [ICCID]
+      },
+      {
+        name: "usage",
+        tool: "subscriber_usage",
+        summary: "Daily data, voice and SMS usage over a window of up to 7 days.",
+        options: [ICCID, ...PERIOD],
+        usageWindow: true
+      },
+      {
+        name: "events",
+        tool: "subscriber_network_events",
+        summary: "Network attach/detach events over a window of up to 7 days.",
+        options: [ICCID, ...PERIOD],
+        usageWindow: true
+      },
+      {
+        name: "active-period",
+        tool: "subscriber_active_period",
+        summary: "First and last usage dates for one subscriber.",
+        options: [ICCID]
+      },
+      {
+        name: "esim-status",
+        tool: "esim_status_per_account",
+        summary: "eSIM state counts per account: active, suspended, inventory.",
+        options: [ACCOUNT_ID("Report on a single account"), RESELLER_ID]
+      },
+      {
+        name: "set-status",
+        tool: "modify_subscriber_status",
+        summary: "Change a subscriber's status.",
+        options: [
+          ICCID,
+          {
+            flags: "--status <status>",
+            description: "New status, e.g. ACTIVE or SUSPENDED",
+            arg: "status",
+            type: "string",
+            required: true
+          }
+        ],
+        write: true
+      },
+      {
+        name: "set-balance",
+        tool: "modify_subscriber_balance",
+        summary: "Add to or replace a subscriber's balance.",
+        options: [
+          ICCID,
+          {
+            flags: "--amount <amount>",
+            description: "Amount to add (adapt) or set to (set)",
+            arg: "amount",
+            type: "number",
+            required: true
+          },
+          {
+            flags: "--mode <mode>",
+            description: "'adapt' adds or subtracts, 'set' replaces",
+            arg: "mode",
+            type: "string",
+            required: true
+          }
+        ],
+        write: true
+      }
+    ]
+  },
+  {
+    name: "packages",
+    summary: "Packages assigned to a subscriber.",
+    commands: [
+      {
+        name: "list",
+        tool: "list_subscriber_packages",
+        summary: "Packages on one subscriber, with allowance and expiry.",
+        options: [ICCID]
+      },
+      {
+        name: "assign",
+        tool: "assign_package",
+        summary: "Assign a one-time package from a template.",
+        options: [
+          { ...ICCID, required: false },
+          {
+            flags: "--template-id <id>",
+            description: "Package template ID from `carrier templates list`",
+            arg: "packageTemplateId",
+            type: "number",
+            required: true
+          },
+          {
+            flags: "--account-id <id>",
+            description: "Auto-pick a free eSIM from this account instead of using --iccid",
+            arg: "account_for_subs",
+            type: "number"
+          }
+        ],
+        write: true,
+        requireOneOf: ["iccid", "account_for_subs"]
+      },
+      {
+        name: "set-status",
+        tool: "modify_package_status",
+        summary: "Activate or deactivate one package without deleting it.",
+        options: [
+          ICCID,
+          PACKAGE_ID,
+          {
+            flags: "--status <status>",
+            description: "New package status, e.g. ACTIVE or INACTIVE",
+            arg: "status",
+            type: "string",
+            required: true
+          }
+        ],
+        write: true
+      },
+      {
+        name: "set-expiry",
+        tool: "modify_package_expiry",
+        summary: "Move a package's expiry date. Pass an absolute date or a day count.",
+        options: [
+          ICCID,
+          PACKAGE_ID,
+          {
+            flags: "--expires <date>",
+            description: "Absolute expiry, ISO 8601 (e.g. 2026-06-01)",
+            arg: "expirationDate",
+            type: "string"
+          },
+          {
+            flags: "--validity-days <n>",
+            description: "Days from now until expiry (instead of --expires)",
+            arg: "validity_days",
+            type: "number"
+          }
+        ],
+        write: true
+      },
+      {
+        name: "set-limits",
+        tool: "modify_package_limits",
+        summary: "Change data, voice or SMS ceilings on an assigned package.",
+        options: [
+          ICCID,
+          PACKAGE_ID,
+          {
+            flags: "--limits <json>",
+            description: `New limits as JSON, e.g. '{"dataLimit":5368709120}'`,
+            arg: "limits",
+            type: "string",
+            required: true
+          }
+        ],
+        write: true
+      },
+      {
+        name: "delete",
+        tool: "delete_subscriber_package",
+        summary: "Permanently remove one package from a subscriber.",
+        options: [ICCID, PACKAGE_ID],
+        write: true
+      }
+    ]
+  },
+  {
+    name: "templates",
+    summary: "The package template catalog.",
+    commands: [
+      {
+        name: "list",
+        tool: "list_package_templates",
+        summary: "Browse package templates available for assignment.",
+        options: [ACCOUNT_ID("Filter templates visible to one account")]
+      },
+      {
+        name: "create",
+        tool: "create_package_template",
+        summary: "Create a package template from a JSON configuration.",
+        options: [
+          {
+            flags: "--template <json>",
+            description: `Template config as JSON, e.g. '{"name":"Europe 5GB","dataLimit":5368709120}'`,
+            arg: "template",
+            type: "string",
+            required: true
+          }
+        ],
+        write: true
+      },
+      {
+        name: "set-core",
+        tool: "modify_template_core",
+        summary: "Change name, limits, price, validity or zone on a template.",
+        options: [
+          TEMPLATE_ID,
+          {
+            flags: "--changes <json>",
+            description: `Core fields as JSON, e.g. '{"name":"Europe 5GB"}'`,
+            arg: "changes",
+            type: "string",
+            required: true
+          }
+        ],
+        write: true
+      },
+      {
+        name: "set-recurring",
+        tool: "modify_template_recurring",
+        summary: "Change auto-renewal settings on a template.",
+        options: [
+          TEMPLATE_ID,
+          {
+            flags: "--changes <json>",
+            description: `Recurring fields as JSON, e.g. '{"periodicity":"monthly"}'`,
+            arg: "changes",
+            type: "string",
+            required: true
+          }
+        ],
+        write: true
+      },
+      {
+        name: "set-throttling",
+        tool: "modify_template_throttling",
+        summary: "Change throttling thresholds. Applies to existing packages too.",
+        options: [
+          TEMPLATE_ID,
+          {
+            flags: "--changes <json>",
+            description: `Throttling fields as JSON, e.g. '{"throttlingActive":true}'`,
+            arg: "changes",
+            type: "string",
+            required: true
+          }
+        ],
+        write: true
+      }
+    ]
+  },
+  {
+    name: "zones",
+    summary: "Location zones and destination lists.",
+    commands: [
+      {
+        name: "list",
+        tool: "list_detailed_location_zones",
+        summary: "Location zones with countries and operators. Prefer this over `elements`.",
+        options: [RESELLER_ID]
+      },
+      {
+        name: "elements",
+        tool: "list_location_zones",
+        summary: "Raw zone elements. Upstream OCS returns malformed rows for some zones.",
+        options: [
+          {
+            flags: "--zone-id <id>",
+            description: "Filter to one location zone",
+            arg: "locationZoneId",
+            type: "number"
+          }
+        ]
+      },
+      {
+        name: "create",
+        tool: "create_location_zone",
+        summary: "Create a location zone from a JSON configuration.",
+        options: [
+          {
+            flags: "--zone <json>",
+            description: `Zone config as JSON, e.g. '{"name":"Europe","countries":["NL","DE"]}'`,
+            arg: "zone",
+            type: "string",
+            required: true
+          }
+        ],
+        write: true
+      },
+      {
+        name: "destinations",
+        tool: "list_destination_lists",
+        summary: "Destination list catalog for voice and SMS packages.",
+        options: [RESELLER_ID]
+      },
+      {
+        name: "prefixes",
+        tool: "list_destination_prefixes",
+        summary: "Dialling prefixes inside one destination list.",
+        options: [
+          {
+            flags: "--destination-list-id <id>",
+            description: "Destination list ID from `carrier zones destinations`",
+            arg: "destinationListId",
+            type: "number"
+          }
+        ]
+      }
+    ]
+  },
+  {
+    name: "steering",
+    summary: "Network steering lists and operator preference.",
+    commands: [
+      {
+        name: "list",
+        tool: "list_steering_lists",
+        summary: "Steering lists configured for this reseller.",
+        options: [RESELLER_ID]
+      },
+      {
+        name: "assign",
+        tool: "modify_subscriber_steering_list",
+        summary: "Assign a steering list to a subscriber. Follow with `push`.",
+        options: [
+          ICCID,
+          {
+            flags: "--list-id <id>",
+            description: "Steering list ID from `carrier steering list`",
+            arg: "steeringListId",
+            type: "number",
+            required: true
+          }
+        ],
+        write: true
+      },
+      {
+        name: "push",
+        tool: "push_steering_to_subscriber",
+        summary: "Push the assigned operator preference list to the device now.",
+        options: [ICCID],
+        write: true
+      }
+    ]
+  },
+  {
+    name: "intelligence",
+    summary: "Composite reports over the fleet.",
+    commands: [
+      {
+        name: "fleet-health",
+        tool: "fleet_health",
+        summary: "eSIM counts, low-balance accounts and what needs attention.",
+        options: [ACCOUNT_ID("Report on a single account")]
+      },
+      {
+        name: "diagnose",
+        tool: "diagnose_subscriber",
+        summary: "Why one subscriber is offline, throttled or failing to attach.",
+        options: [ICCID]
+      },
+      {
+        name: "anomalies",
+        tool: "detect_usage_anomalies",
+        summary: "Usage spikes and burn rates that exhaust the package early.",
+        options: [ICCID]
+      },
+      {
+        name: "churn",
+        tool: "churn_risk",
+        summary: "Churn risk score with contributing factors.",
+        options: [ICCID]
+      },
+      {
+        name: "optimize",
+        tool: "optimize_package",
+        summary: "Better-fitting package for one subscriber, with the saving.",
+        options: [ICCID]
+      },
+      {
+        name: "coverage",
+        tool: "audit_network_coverage",
+        summary: "Networks subscribers actually attach to, against your steering lists.",
+        options: [
+          ACCOUNT_ID("Report on a single account"),
+          { flags: "--limit <n>", description: "Subscribers to sample (default 50)", arg: "limit", type: "number" }
+        ]
+      },
+      {
+        name: "high-cost",
+        tool: "high_cost_subscribers",
+        summary: "Subscribers whose consumption erodes the margin.",
+        options: [
+          ACCOUNT_ID("Report on a single account"),
+          { flags: "--limit <n>", description: "Subscribers to analyse (default 100)", arg: "limit", type: "number" },
+          {
+            flags: "--threshold-pct <n>",
+            description: "Usage percentage that flags a subscriber (default 80)",
+            arg: "thresholdPct",
+            type: "number"
+          }
+        ]
+      },
+      {
+        name: "marketing",
+        tool: "marketing_intelligence",
+        summary: "Where subscribers and revenue concentrate, and which markets grow.",
+        options: [ACCOUNT_ID("Report on a single account")]
+      },
+      {
+        name: "country-entry",
+        tool: "detect_country_entry",
+        summary: "Country a subscriber is in now, optionally diffed against the last known one.",
+        options: [
+          { ...ICCID, arg: "subscriber.iccid" },
+          {
+            flags: "--expected-country <iso2>",
+            description: "Last known ISO 3166-1 alpha-2 country, e.g. NL",
+            arg: "expectedCountry",
+            type: "string"
+          }
+        ]
+      }
+    ]
+  }
+];
+
+// 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") return { value: raw === true };
+  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.`
+        );
+      }
+      args.startDate = clamped.start;
+      args.endDate = clamped.end;
+    }
+  }
+  if (cmd.write) args.dry_run = true;
+  return { args, errors, notes };
+}
+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(`${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 = "0.2.19";
+var VERSION = CARRIER_VERSION;
 function header() {
-  p2.intro(`${pc3.bold(pc3.yellow("\u25C6 carrier"))} ${pc3.dim("\xB7 the Stripe of telecom \u2014 CLI v" + VERSION)}`);
+  p3.intro(`${pc4.bold(pc4.yellow("\u25C6 carrier"))} ${pc4.dim("\xB7 the Stripe of telecom \u2014 CLI v" + VERSION)}`);
 }
 function ok(msg) {
-  p2.log.success(pc3.green(msg));
+  p3.log.success(pc4.green(msg));
 }
 function info(msg) {
-  p2.log.info(msg);
+  p3.log.info(msg);
 }
 function fail(msg, next) {
-  p2.log.error(msg);
-  p2.note(next.map((s) => `\u2192 ${s}`).join("\n"), "What to do 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 p2.text({
+  const name = await p3.text({
     message: "Brand name",
     placeholder: seed.name,
     defaultValue: seed.name
   });
-  if (p2.isCancel(name)) process.exit(0);
-  const domain = await p2.text({
+  if (p3.isCancel(name)) process.exit(0);
+  const domain = await p3.text({
     message: "Domain",
     placeholder: seed.domain,
     defaultValue: seed.domain
   });
-  if (p2.isCancel(domain)) process.exit(0);
-  const accent = await p2.text({
+  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 (p2.isCancel(accent)) process.exit(0);
-  const supportEmail = await p2.text({
+  if (p3.isCancel(accent)) process.exit(0);
+  const supportEmail = await p3.text({
     message: "Support email",
     placeholder: `support@${domain}`,
     defaultValue: `support@${domain}`
   });
-  if (p2.isCancel(supportEmail)) process.exit(0);
+  if (p3.isCancel(supportEmail)) process.exit(0);
   const accentDark = deriveAccentDark(accent, seed);
   const isCarrier = name === CARRIER_BRAND.name && domain === CARRIER_BRAND.domain;
   return {
@@ -1052,7 +1712,7 @@ async function promptBrand(seed) {
   };
 }
 async function doPluginInstall() {
-  const s = p2.spinner();
+  const s = p3.spinner();
   s.start("Installing Carrier Claude Code plugin + zero-cred MCP");
   let r;
   try {
@@ -1069,13 +1729,13 @@ async function doPluginInstall() {
   s.stop("Plugin staged");
   ok(`Plugin \u2192 ${r.copiedTo}`);
   info(
-    `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")}`
+    `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")}`
   );
-  p2.note(installAuthGuidance().join("\n"), "OAuth on first use (Entry A)");
+  p3.note(installAuthGuidance().join("\n"), "OAuth on first use (Entry A)");
   if (!r.claudeFound || r.notes.length) {
-    p2.note(manualCommands().join("\n"), "Finish wiring (run in your terminal)");
-    if (r.notes.length) info(pc3.dim(r.notes.join("\n")));
-    p2.note(
+    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`,
@@ -1084,7 +1744,7 @@ async function doPluginInstall() {
       "Next"
     );
   } else {
-    p2.note(
+    p3.note(
       [
         "Open Claude Code and say something like:",
         '  "Show my fleet health"',
@@ -1097,7 +1757,7 @@ async function doPluginInstall() {
   }
 }
 async function doSiteCreate(target, brand) {
-  const s = p2.spinner();
+  const s = p3.spinner();
   s.start(`Scaffolding ${brand.name} storefront \u2192 ${target}`);
   try {
     await scaffoldStorefront(target, brand);
@@ -1112,15 +1772,25 @@ async function doSiteCreate(target, brand) {
   }
   s.stop("Storefront scaffolded");
   ok(`Created ${target} (white-labeled: ${brand.name}, accent ${brand.colors.accent})`);
+  const logoSpin = p3.spinner();
+  logoSpin.start("Generating storefront logo");
+  try {
+    const logo = await writeStorefrontLogo(target, brand);
+    logoSpin.stop(`Logo ready (${logo.source})`);
+    ok(logo.path);
+  } catch (e) {
+    logoSpin.stop("Logo skipped");
+    info(pc4.yellow(String(e instanceof Error ? e.message : e)));
+  }
 }
 async function maybeBuildDeploy(target, brand, opts) {
   if (opts.install) {
-    const s = p2.spinner();
+    const s = p3.spinner();
     s.start("Installing storefront dependencies");
     const oki = await installDeps(target);
     s.stop(oki ? "Dependencies installed" : "Dependency install reported errors");
     if (!oki) {
-      p2.note(
+      p3.note(
         [
           `cd ${target} && pnpm install`,
           "Fix any Node/pnpm version issues, then retry build"
@@ -1131,12 +1801,12 @@ async function maybeBuildDeploy(target, brand, opts) {
     }
   }
   if (opts.build) {
-    const s = p2.spinner();
+    const s = p3.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) {
-      p2.note(
+      p3.note(
         [`cd ${target}`, "pnpm build", "Check env keys in .env.local if the build mentions Clerk"].join("\n"),
         "Next"
       );
@@ -1144,13 +1814,13 @@ async function maybeBuildDeploy(target, brand, opts) {
     }
   }
   if (opts.deploy) {
-    const s = p2.spinner();
+    const s = p3.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(pc3.yellow(r.reason));
-      p2.note(
+      info(pc4.yellow(r.reason));
+      p3.note(
         [
           "Install wrangler and login: npx wrangler login",
           `Then: carrier site deploy ${target}`
@@ -1162,26 +1832,31 @@ async function maybeBuildDeploy(target, brand, opts) {
 }
 async function interactiveSiteCreate() {
   const brand = await promptBrand(CARRIER_BRAND);
-  const dir = await p2.text({
+  const dir = await p3.text({
     message: "Output directory",
     placeholder: "./storefront",
     defaultValue: "./storefront"
   });
-  if (p2.isCancel(dir)) return;
+  if (p3.isCancel(dir)) return;
   const target = resolve2(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 a different directory.");
+    const go = await p3.confirm({ message: `${target} exists \u2014 write into it anyway?`, initialValue: false });
+    if (p3.isCancel(go) || !go) {
+      p3.outro("Stopped. Re-run with a different directory.");
       return;
     }
   }
   await doSiteCreate(target, brand);
-  p2.outro(pc3.green(`Scaffolded. cd ${dir} && pnpm install && pnpm dev`));
+  p3.outro(pc4.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."
+  [
+    "Carrier CLI \u2014 status, OAuth-ready MCP install, storefront scaffold, and fleet control.",
+    "",
+    "Domains: " + CLI_DOMAINS.map((d) => d.name).join(", "),
+    'Anything they do not cover: carrier ask "\u2026"'
+  ].join("\n")
 ).version(VERSION).action(async () => {
   header();
   await runHome({
@@ -1196,12 +1871,12 @@ program.command("init").description("Interactive home: status, install plugin+MC
     const brand = CARRIER_BRAND;
     const target = resolve2(o.dir);
     if (await exists(target)) {
-      info(pc3.yellow(`${target} exists \u2014 writing into it (--yes).`));
+      info(pc4.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(
+    p3.note(oauthFirstUseNote(), "Auth");
+    p3.note(
       [
         `cd ${o.dir}`,
         `Edit src/brand.config.ts to re-brand anytime`,
@@ -1211,7 +1886,7 @@ program.command("init").description("Interactive home: status, install plugin+MC
       ].join("\n"),
       "Next"
     );
-    p2.outro(pc3.green("Done. Your connectivity business is wired."));
+    p3.outro(pc4.green("Done. Your connectivity business is wired."));
     return;
   }
   if (o.full) {
@@ -1221,14 +1896,14 @@ program.command("init").description("Interactive home: status, install plugin+MC
     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>.");
+      const go = await p3.confirm({ message: `${target} exists \u2014 write into it anyway?`, initialValue: false });
+      if (p3.isCancel(go) || !go) {
+        p3.outro("Stopped. Re-run with --dir <new path>.");
         return;
       }
     }
     await doSiteCreate(target, brand);
-    const next = await p2.select({
+    const next = await p3.select({
       message: "Roll it out now?",
       options: [
         { value: "build", label: "Install deps + build" },
@@ -1237,14 +1912,14 @@ program.command("init").description("Interactive home: status, install plugin+MC
       ],
       initialValue: "build"
     });
-    if (p2.isCancel(next)) process.exit(0);
+    if (p3.isCancel(next)) process.exit(0);
     await maybeBuildDeploy(target, brand, {
       install: next !== "none",
       build: next !== "none",
       deploy: next === "deploy"
     });
-    p2.note(oauthFirstUseNote(), "Auth");
-    p2.note(
+    p3.note(oauthFirstUseNote(), "Auth");
+    p3.note(
       [
         `cd ${o.dir}`,
         `Edit src/brand.config.ts to re-brand anytime`,
@@ -1253,7 +1928,7 @@ program.command("init").description("Interactive home: status, install plugin+MC
       ].join("\n"),
       "Next"
     );
-    p2.outro(pc3.green("Done. Your connectivity business is wired."));
+    p3.outro(pc4.green("Done. Your connectivity business is wired."));
     return;
   }
   await runHome({
@@ -1262,14 +1937,14 @@ program.command("init").description("Interactive home: status, install plugin+MC
       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.");
+        const go = await p3.confirm({ message: `${target} exists \u2014 write into it anyway?`, initialValue: false });
+        if (p3.isCancel(go) || !go) {
+          p3.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({
+      const next = await p3.select({
         message: "Roll it out now?",
         options: [
           { value: "build", label: "Install deps + build" },
@@ -1278,13 +1953,13 @@ program.command("init").description("Interactive home: status, install plugin+MC
         ],
         initialValue: "build"
       });
-      if (p2.isCancel(next)) return;
+      if (p3.isCancel(next)) return;
       await maybeBuildDeploy(target, brand, {
         install: next !== "none",
         build: next !== "none",
         deploy: next === "deploy"
       });
-      p2.note(
+      p3.note(
         [
           `cd ${o.dir}`,
           `pnpm dev`,
@@ -1299,25 +1974,25 @@ var plugin = program.command("plugin").description("Manage the Carrier Claude Co
 plugin.command("install").description("Install/register the Carrier plugin + zero-cred MCP (OAuth on first use).").action(async () => {
   header();
   await doPluginInstall();
-  p2.outro(pc3.green("Plugin ready. Restart Claude Code, then talk to your fleet."));
+  p3.outro(pc4.green("Plugin ready. Restart Claude Code, then talk to your fleet."));
 });
 plugin.command("status").description("Show plugin + MCP registration + auth next steps.").action(async () => {
   header();
   const st = await gatherStatus();
   printStatus(st);
-  p2.note(oauthFirstUseNote(), "Auth");
-  p2.outro("");
+  p3.note(oauthFirstUseNote(), "Auth");
+  p3.outro("");
 });
 program.command("status").description("Show MCP / plugin / auth status and next steps.").action(async () => {
   header();
-  const s = p2.spinner();
+  const s = p3.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("");
+  p3.note(formatStatusBlock(st), "Status");
+  p3.note(formatNextSteps(st), "Next steps");
+  p3.note(oauthFirstUseNote(), "Auth");
+  p3.outro("");
 });
 var openCmd = program.command("open").description("Open Carrier account / product URLs in your browser.");
 for (const [name, url, desc] of [
@@ -1332,17 +2007,17 @@ for (const [name, url, desc] of [
     const r = await openUrl(url);
     if (r.ok) ok(r.hint);
     else {
-      p2.log.warn(r.hint);
-      p2.note(url, "Open this URL");
+      p3.log.warn(r.hint);
+      p3.note(url, "Open this URL");
     }
-    p2.note(accountLinksNote(), "Account links");
-    p2.outro("");
+    p3.note(accountLinksNote(), "Account links");
+    p3.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(
+  p3.note(formatNlExamples(), "Talk to fleet \u2014 paste into Claude");
+  p3.note(
     [
       "After `carrier plugin install` (or this menu \u2192 Install):",
       "  1. Open Claude Code",
@@ -1353,9 +2028,21 @@ program.command("examples").description("Print natural-language fleet prompts fo
     ].join("\n"),
     "How"
   );
-  p2.outro("");
+  p3.note(
+    [
+      "With CARRIER_API_KEY set, every capability also has its own command:",
+      ...CLI_DOMAINS.map((d) => `  carrier ${d.name} --help`.padEnd(34) + pc4.dim(d.summary)),
+      "",
+      "  --json   raw response on stdout, ready for jq",
+      "  --commit apply a change instead of previewing it"
+    ].join("\n"),
+    "Domain commands"
+  );
+  p3.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) => {
+program.command("ask").description(
+  'Natural-language fallback for whatever the domain commands miss: 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) {
@@ -1366,19 +2053,33 @@ program.command("ask").description('Optional headless NL: carrier ask "show flee
     process.exitCode = 1;
     return;
   }
-  const s = p2.spinner();
+  const s = p3.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("");
+    p3.note(result.text.slice(0, 6e3), "Answer");
+    p3.outro("");
   } else {
-    p2.log.error(result.text);
-    p2.outro(pc3.yellow("See next steps above."));
+    p3.log.error(result.text);
+    p3.outro(pc4.yellow("See next steps above."));
     process.exitCode = 1;
   }
 });
+for (const domain of CLI_DOMAINS) {
+  const group = program.command(domain.name).description(domain.summary);
+  for (const cmd of domain.commands) {
+    const sub = group.command(cmd.name).description(cmd.write ? `${cmd.summary} Dry run unless --commit.` : 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");
+    sub.action(async (opts) => {
+      if (opts.json !== true) header();
+      await runCapability(domain, cmd, opts);
+      if (opts.json !== true) p3.outro("");
+    });
+  }
+}
 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) => {
   header();
@@ -1408,9 +2109,9 @@ site.command("create [dir]").description("Scaffold a white-labeled storefront fr
   }
   const target = resolve2(dir ?? "./storefront");
   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 a different directory.");
+    const go = await p3.confirm({ message: `${target} exists \u2014 write into it anyway?`, initialValue: false });
+    if (p3.isCancel(go) || !go) {
+      p3.outro("Stopped. Re-run with a different directory.");
       return;
     }
   }
@@ -1420,7 +2121,7 @@ site.command("create [dir]").description("Scaffold a white-labeled storefront fr
     process.exitCode = 1;
     return;
   }
-  p2.outro(pc3.green(`Scaffolded. cd ${dir ?? "storefront"} && pnpm install && pnpm dev`));
+  p3.outro(pc4.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();
@@ -1436,12 +2137,28 @@ site.command("deploy [dir]").description("Build + deploy a storefront to Cloudfl
     process.exitCode = 1;
     return;
   }
-  p2.outro("");
+  p3.outro("");
+});
+site.command("logo [dir]").description("Generate a storefront logo (SVG always; PNG if an image key is on this box or Carrier).").action(async (dir) => {
+  header();
+  const target = resolve2(dir ?? "./storefront");
+  try {
+    const brand = await loadStorefrontBrand(target);
+    const logo = await writeStorefrontLogo(target, brand);
+    ok(`Logo (${logo.source}): ${logo.path}`);
+  } catch (e) {
+    fail(String(e instanceof Error ? e.message : e), [
+      "Scaffold first: carrier site create"
+    ]);
+    process.exitCode = 1;
+    return;
+  }
+  p3.outro("");
 });
 program.parseAsync(process.argv).catch((e) => {
-  console.error(pc3.red(String(e instanceof Error ? e.message : e)));
+  console.error(pc4.red(String(e instanceof Error ? e.message : e)));
   console.error(
-    pc3.dim(
+    pc4.dim(
       [
         "",
         "What to do next:",