@carrierllc/mcp 0.2.16 → 0.2.18

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@carrierllc/mcp",
-  "version": "0.2.16",
-  "description": "Carrier MCP — natural-language control of MVNO/eSIM fleets via eSIMVault OCS. Stdio mode for direct integration with Claude Desktop, Cursor, Windsurf, and MCP-compatible clients.",
+  "version": "0.2.18",
+  "description": "Carrier MCP \u2014 natural-language control of MVNO/eSIM fleets via eSIMVault OCS. Stdio mode for direct integration with Claude Desktop, Cursor, Windsurf, and MCP-compatible clients. Ships the `carrier` CLI (plugin install + white-label eSIM storefront scaffold).",
   "license": "MIT",
   "author": "Carrier (Lifecycle Innovations Limited)",
   "homepage": "https://mcp.carrier.llc",
@@ -13,32 +13,39 @@
   "main": "./dist/index.js",
   "files": [
     "dist",
+    "plugin",
+    "templates",
     "README.md"
   ],
   "scripts": {
     "build": "tsup",
     "type-check": "tsc --noEmit",
     "lint": "eslint src",
-    "prepublishOnly": "pnpm run build"
+    "prepublishOnly": "pnpm run build",
+    "test": "pnpm run build && node --test test/*.test.js"
   },
   "dependencies": {
-    "@clerk/backend": "^3.4.7",
-    "@modelcontextprotocol/ext-apps": "^1.7.1",
+    "@clack/prompts": "^0.7.0",
+    "@clerk/backend": "^3.11.3",
+    "@modelcontextprotocol/ext-apps": "^1.7.4",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@noble/hashes": "^1.8.0",
-    "@sentry/cloudflare": "^10.52.0",
+    "@sentry/cloudflare": "^10.65.0",
     "aws4fetch": "^1.0.20",
-    "zod": "^4.0.0"
+    "commander": "^12.1.0",
+    "picocolors": "^1.1.1",
+    "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@carrier/ocs-spec": "workspace:*",
-    "@cloudflare/workers-types": "^4",
-    "@types/node": "^22",
-    "@typescript-eslint/eslint-plugin": "^8.0.0",
-    "@typescript-eslint/parser": "^8.0.0",
-    "eslint": "^9",
+    "@cloudflare/workers-types": "^4.20260521.1",
+    "@types/node": "^22.19.19",
+    "@typescript-eslint/eslint-plugin": "^8.59.4",
+    "@typescript-eslint/parser": "^8.59.4",
+    "eslint": "^9.39.4",
     "tsup": "^8.5.1",
-    "typescript": "^5.5.0"
+    "typescript": "^5.9.3",
+    "@carrier/ocs-client": "workspace:*",
+    "@carrier/ocs-spec": "workspace:*"
   },
   "keywords": [
     "mcp",
@@ -56,6 +63,7 @@
     "access": "public"
   },
   "bin": {
-    "carrier-mcp": "./dist/index.js"
+    "carrier-mcp": "dist/index.js",
+    "carrier": "dist/cli.js"
   }
 }

package/plugin/.claude-plugin/marketplace.json

@@ -0,0 +1,31 @@
+{
+  "name": "carrier",
+  "owner": {
+    "name": "Lifecycle Innovations Limited",
+    "url": "https://carrier.llc"
+  },
+  "metadata": {
+    "description": "Carrier — natural-language MVNO/eSIM fleet control + white-label storefront for Claude Code.",
+    "version": "0.1.1"
+  },
+  "plugins": [
+    {
+      "name": "carrier",
+      "source": "./carrier",
+      "description": "Provision eSIMs, manage subscribers/packages/billing/usage/SMS/churn/fleet, and roll out a white-labeled storefront — all in natural language via the Carrier MCP.",
+      "version": "0.1.1",
+      "author": {
+        "name": "Lifecycle Innovations Limited",
+        "url": "https://carrier.llc"
+      },
+      "keywords": [
+        "carrier",
+        "esim",
+        "mvno",
+        "telecom",
+        "mcp",
+        "storefront"
+      ]
+    }
+  ]
+}

package/plugin/carrier/.claude-plugin/plugin.json

@@ -0,0 +1,19 @@
+{
+  "name": "carrier",
+  "version": "0.1.1",
+  "description": "Natural-language control of your MVNO/eSIM fleet — the Stripe of telecom. Provision eSIMs, manage subscribers, packages, billing, usage, SMS, churn, and fleet health, and roll out a white-labeled storefront. Wraps the Carrier MCP (113 tools over OAuth 2.1).",
+  "author": {
+    "name": "Lifecycle Innovations Limited",
+    "url": "https://carrier.llc"
+  },
+  "homepage": "https://carrier.llc",
+  "repository": "https://github.com/Lifecycle-Innovations-Limited/carrier.llc",
+  "license": "MIT",
+  "keywords": ["carrier", "esim", "mvno", "telecom", "mcp", "fleet", "billing", "storefront"],
+  "mcpServers": {
+    "carrier": {
+      "type": "http",
+      "url": "https://mcp.carrier.llc/mcp"
+    }
+  }
+}

package/plugin/carrier/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "carrier": {
+      "type": "http",
+      "url": "https://mcp.carrier.llc/mcp"
+    }
+  }
+}

package/plugin/carrier/README.md

@@ -0,0 +1,75 @@
+# Carrier — Claude Code plugin
+
+Natural-language control of your MVNO/eSIM fleet, plus a white-labeled storefront — the Stripe of telecom, inside Claude Code.
+
+## Install (recommended)
+
+```bash
+npx @carrierllc/mcp
+# or, after global install:
+carrier
+carrier init
+```
+
+The CLI opens a clear TUI: status (plugin / MCP / auth), sign-up & sign-in links, storefront scaffold, and “talk to fleet” examples.
+
+```bash
+carrier plugin install
+```
+
+### Zero credentials · OAuth on first use (Entry A)
+
+The MCP server is registered as a plain HTTPS URL — **no API token in config**:
+
+```text
+https://mcp.carrier.llc/mcp
+```
+
+When Claude first calls a Carrier tool, your browser opens Clerk sign-in / sign-up
+(Google, GitHub, or email). Authorize once; tokens stay in the client.
+
+Headless / CI only: create an org API key (`ak_…`) in the console
+(https://app.carrier.llc → Settings → API Keys) and pass it as a Bearer token
+or `CARRIER_API_KEY` for `carrier ask "…"`.
+
+…or wire Claude Code manually:
+
+```bash
+claude plugin marketplace add <path-to-bundled-plugin>
+claude plugin install carrier@carrier
+claude mcp add --transport http carrier https://mcp.carrier.llc/mcp
+# stuck on auth?
+claude mcp auth carrier
+```
+
+## Commands
+
+| Command | Does |
+|---|---|
+| `/carrier:provision` | Provision eSIMs + assign a starter package |
+| `/carrier:subscribers` | List / inspect / suspend / resume / terminate subscribers |
+| `/carrier:packages` | Create, assign, optimize data packages |
+| `/carrier:usage` | Usage, projections, depletion, anomalies |
+| `/carrier:billing` | Balances, thresholds, Stripe Connect payouts |
+| `/carrier:credits` | Platform credit, top-ups, credential health |
+| `/carrier:wallet` | Managed prepaid wallet balance / bulk top-up / auto-top-up |
+| `/carrier:sms` | Send an SMS to a subscriber |
+| `/carrier:esim-status` | eSIM activation / SIM state / provider health |
+| `/carrier:churn` | Churn risk + marketing intelligence |
+| `/carrier:greenzone` | Fair-use whitelist + steering policy |
+| `/carrier:fleet` | One-screen fleet health dashboard |
+| `/carrier:status` | Fast control-plane + auth ping |
+| `/carrier:storefront` | Scaffold / rebrand / deploy your storefront |
+| `/carrier:onboard` | Zero-to-live: stand up a connectivity business |
+
+## Agents
+
+- **carrier-fleet-ops** — autonomous provisioning + lifecycle + remediation
+- **carrier-billing-auditor** — read-only revenue/cost audit, proposes adjustments
+- **carrier-storefront-builder** — scaffold, white-label, deploy the storefront
+
+## Skill
+
+- **carrier-operations** — the full MCP tool map + safety rules
+
+All operations run through the Carrier MCP (`https://mcp.carrier.llc/mcp`, OAuth 2.1 + PKCE). Money- and service-affecting actions always confirm first.

package/plugin/carrier/agents/carrier-billing-auditor.md

@@ -0,0 +1,16 @@
+---
+name: carrier-billing-auditor
+description: Audits fleet billing, balances, cost outliers, and Stripe Connect payouts via the Carrier MCP. Read-only by default; proposes adjustments for approval. Use for revenue/cost reviews and reconciliation.
+---
+
+You are a Carrier billing & revenue auditor working through the **Carrier MCP**.
+
+Default to **read-only**. You investigate and recommend; you do not move money without explicit approval.
+
+Audit playbook:
+- **Revenue & events** — `billing_events`, `stripe_connect_status`, `stripe_connect_balance`, `stripe_connect_payouts`, `stripe_connect_dispute_list`.
+- **Cost outliers** — `high_cost_subscribers`, `detect_usage_anomalies`, `subscriber_depletion_events`. Flag SIMs whose cost exceeds their plan price.
+- **Balances & runway** — `credit_balance` (platform), `wallet_balance` (managed prepaid Atlas wallet), per-reseller `get_reseller_info`. Project when credit or wallet blocks provisioning. Do not conflate wallet with Connect payouts.
+- **Leakage** — packages still billing on suspended subscribers, recurring packages that should have stopped (`list_subscriber_packages`, `stop_resume_recurring_package`).
+
+Deliver a findings report: top cost drivers, anomalies, reconciliation gaps, and a prioritized list of corrective actions with the exact tool call for each. Only execute a `modify_*_balance` / billing change after the user approves that specific line.

package/plugin/carrier/agents/carrier-fleet-ops.md

@@ -0,0 +1,15 @@
+---
+name: carrier-fleet-ops
+description: Autonomous MVNO/eSIM fleet operator. Use for multi-step provisioning, subscriber lifecycle, package assignment, and fleet remediation via the Carrier MCP. Confirms money/service-affecting actions before executing.
+---
+
+You are a Carrier fleet operations specialist. You manage a live MVNO/eSIM fleet through the **Carrier MCP** (HTTP, OAuth-gated). The MCP exposes 100+ tools across provisioning, subscribers, packages, usage, billing, intelligence, and fleet health.
+
+Operating rules:
+- **Read before write.** Establish current state (`get_subscriber`, `fleet_health`, `list_subscriber_packages`, `esim_status_per_account`) before any mutation.
+- **Confirm anything that moves money or changes live service** — `modify_subscriber_status`, `change_sim_status`, balance/package mutations, `clean_all_packages`, `rotate_credentials`. State the exact target and effect, then act.
+- **Right quantity only.** Never over-provision. Check `credit_balance` before batches.
+- **Diagnose, don't guess.** When a SIM misbehaves, run `diagnose_subscriber` + `subscriber_network_events` and propose the specific fix.
+- Surface activation QR / LPA strings for newly provisioned eSIMs.
+
+Common flows: provision (`provision_esim_wizard` → `assign_package` → verify), lifecycle (`modify_subscriber_status`), package tuning (`optimize_package`, `modify_package_limits`), and remediation. Report concise before/after state. End with what's done and any human gate still open.

package/plugin/carrier/agents/carrier-storefront-builder.md

@@ -0,0 +1,17 @@
+---
+name: carrier-storefront-builder
+description: Scaffolds, white-labels, and deploys the customer-facing eSIM storefront (Mango template) via @carrierllc/cli, and keeps its plans in sync with the Carrier fleet. Use to launch or rebrand a storefront.
+---
+
+You build and ship white-labeled eSIM storefronts on top of a Carrier fleet.
+
+The storefront is a Next.js app (Mango-derived template) scaffolded by `@carrierllc/cli`. Its single white-label surface is `src/brand.config.ts` (name, tagline, colors, domain, support, social).
+
+Workflow:
+1. **Scaffold** — `npx @carrierllc/cli site create <dir>` with the operator's brand (name, domain, accent hex, support email).
+2. **Brand** — verify `src/brand.config.ts` and `globals.css` reflect the brand; the default accent is Carrier Flame `#FF6B35` on dark `#080C16` — replace with the operator's palette. Check there are no leftover "Mango" strings.
+3. **Wire** — set `NEXT_PUBLIC_CARRIER_API_URL` in `.env.local`; ensure the plans shown match `pricing_plans` / `list_package_templates` from the fleet.
+4. **Build & deploy** — `npx @carrierllc/cli site deploy <dir>` → Cloudflare Pages (`wrangler login` first).
+5. **Verify** — load the live URL, confirm it renders, plans are correct, and checkout reaches the control plane.
+
+Report the live URL, the brand applied, and any plan mismatch between the storefront and the fleet. Never deploy with placeholder/test Clerk or Stripe keys to a production domain — flag missing secrets instead.

package/plugin/carrier/commands/billing.md

@@ -0,0 +1,23 @@
+---
+description: Billing, balances, thresholds, and Stripe Connect payouts
+argument-hint: "[events|balance|topup|payouts|configure] [subscriber/account]"
+---
+
+# Billing
+
+Manage money movement across the fleet. Keep the three money domains distinct:
+
+| Domain | Tools / command | Purpose |
+|--------|-----------------|---------|
+| Platform credit | `credit_balance`, `balance_topup_form` · also `/carrier:credits` | Carrier platform runway |
+| Stripe Connect | `stripe_connect_status\|balance\|payouts\|dispute_list` | Operator payouts / disputes |
+| Managed prepaid wallet | `wallet_*` · **`/carrier:wallet`** | Atlas prepaid drawdown (managed mode) |
+
+- **events** → `billing_events` (recent charges, renewals, adjustments).
+- **balances** → `credit_balance` (platform credit), `modify_subscriber_balance` / `modify_account_balance` for adjustments. Generate a customer-facing top-up with `balance_topup_form`.
+- **thresholds / config** → `configure_billing` to set low-balance alerts and auto-renew behavior.
+- **cost watch** → `high_cost_subscribers` to find the fleet's most expensive SIMs.
+- **payouts (Stripe Connect)** → `stripe_connect_status`, `stripe_connect_balance`, `stripe_connect_payouts`, `stripe_connect_dispute_list`.
+- **managed wallet** → do not use Connect or platform credit tools; use `/carrier:wallet` (`wallet_balance`, `wallet_topup_checkout`, `wallet_auto_topup`).
+
+Any balance modification is money movement — state the exact amount, account, and direction, and confirm before executing. Never adjust a balance without explicit confirmation.

package/plugin/carrier/commands/churn.md

@@ -0,0 +1,15 @@
+---
+description: Churn risk and marketing intelligence across the fleet
+argument-hint: "[subscriber|fleet]"
+---
+
+# Churn & Intelligence
+
+Surface retention risk and growth opportunities.
+
+- **churn risk** → `churn_risk` (per-subscriber or fleet-wide ranking with drivers).
+- **marketing intelligence** → `marketing_intelligence` for segments, upsell candidates, and campaign ideas.
+- **cost / anomaly signals** → `high_cost_subscribers`, `detect_usage_anomalies` (silent churn often shows as a usage drop first).
+- **diagnose at-risk accounts** → `diagnose_subscriber` for the top risks.
+
+Deliver a ranked, actionable list: who's at risk, why, and the single best retention action per account (top-up nudge, plan right-size via `optimize_package`, proactive SMS via `send_sms`). Offer to execute the top action.

package/plugin/carrier/commands/credits.md

@@ -0,0 +1,15 @@
+---
+description: Platform credit balance, top-ups, and credential status
+argument-hint: "[balance|topup|status]"
+---
+
+# Credits & Credentials
+
+Keep the platform funded and authenticated.
+
+- **balance** → `credit_balance` — current platform credit and burn rate.
+- **top-up** → `balance_topup_form` to generate a funding link / form.
+- **credential status** → `credential_status` (OCS + provider auth health); `rotate_credentials` if a key is stale (confirm first — rotation can interrupt provisioning).
+- **reseller funding** → `list_reseller_accounts` + `get_reseller_info` to see per-reseller balances.
+
+Warn clearly when credit is low enough to block provisioning, and recommend the top-up amount based on recent burn.

package/plugin/carrier/commands/esim-status.md

@@ -0,0 +1,15 @@
+---
+description: Check eSIM/SIM status, activation, and provider health
+argument-hint: "[account/ICCID]"
+---
+
+# eSIM Status
+
+Inspect activation and connectivity state of eSIMs.
+
+- **per account** → `esim_status_per_account` (installed / active / suspended, activation QR availability).
+- **SIM state change** → `change_sim_status` to activate, suspend, or resume a SIM (confirm before changing a live SIM).
+- **provider health** → `get_sim_provider_status` and `audit_network_coverage` for the destination.
+- **HLR / bitrate** → `hlr_get_bitrate` / `hlr_set_bitrate` for throttling at the network layer.
+
+Report each eSIM's lifecycle state and, when not yet activated, surface the activation QR / LPA string. If a SIM is stuck, run `diagnose_subscriber` and propose the fix.

package/plugin/carrier/commands/fleet.md

@@ -0,0 +1,17 @@
+---
+description: Fleet-wide health, OCS events, and rate-limit status
+argument-hint: ""
+---
+
+# Fleet Health
+
+Give a one-screen operational overview of the whole MVNO.
+
+Gather in parallel:
+- `fleet_health` (+ `fleet_health_app` for the rich view) — active SIMs, suspended, errored, total data in flight.
+- `list_recent_ocs_events` — recent charging-system events and any errors.
+- `rate_limit_status` + `carrier_ocs_calls_per_min` — control-plane headroom.
+- `environment_info` + `credential_status` — which environment + auth state.
+- `credit_balance` — platform runway.
+
+Present a compact dashboard: 🟢/🟡/🔴 per area, the top 3 issues needing attention, and recommended next actions. If anything is red, offer to drill in with `/carrier:subscribers view` or `/carrier:billing`.

package/plugin/carrier/commands/greenzone.md

@@ -0,0 +1,16 @@
+---
+description: Manage green-zone (fair-use / whitelist) policy
+argument-hint: "[list|add|remove|reset] [subscriber/destination]"
+---
+
+# Green Zone
+
+Manage fair-use whitelisting and traffic steering.
+
+- **list** → `greenzone_whitelist_list` (and `list_steering_lists`, `list_destination_lists`, `list_destination_prefixes` for routing).
+- **add / remove** → `greenzone_whitelist_add` / `greenzone_whitelist_remove`.
+- **reset counter** → `reset_subscriber_gz_counter` for a subscriber who hit the fair-use cap.
+- **steering** → `modify_subscriber_steering_list`, `push_steering_to_subscriber`.
+- **restrictions** → `set_subscriber_traffic_restrictions`.
+
+Explain the policy effect of each change in plain language before applying it. Confirm subscriber-affecting changes.

package/plugin/carrier/commands/onboard.md

@@ -0,0 +1,17 @@
+---
+description: Zero-to-live — stand up a connectivity business end to end
+argument-hint: "[brand name]"
+---
+
+# Onboard a Connectivity Business
+
+Take a new operator from nothing to a live, sellable eSIM brand. Drive the whole flow, confirming at each gate.
+
+1. **Verify access** — `environment_info`, `credential_status`, `credit_balance`. Stop if auth is bad or credit can't cover a first batch.
+2. **Define the offer** — review `service_catalog` + `pricing_plans`; create the launch packages with `create_package_template` (e.g. a regional and a global plan). Set retail price.
+3. **Pilot provision** — `provision_esim_wizard` for a small test batch, `assign_package`, verify with `esim_status_per_account`.
+4. **Storefront** — scaffold + deploy the white-labeled site: `npx @carrierllc/cli site create` then `site deploy` (see `/carrier:storefront`). Brand it for the operator.
+5. **Billing** — `configure_billing` thresholds; confirm `stripe_connect_status` so payouts work.
+6. **Go-live checklist** — fleet `fleet_health` green, plans live on the storefront, top-up form (`balance_topup_form`) working, support SMS (`send_sms`) tested.
+
+End with a punch list of anything still manual and the live storefront URL.

package/plugin/carrier/commands/packages.md

@@ -0,0 +1,18 @@
+---
+description: Manage data packages and package templates
+argument-hint: "[list|create|assign|modify|remove] [subscriber] [template]"
+---
+
+# Packages & Plans
+
+Create, assign, and tune data packages across the fleet.
+
+- **list templates** → `list_package_templates` (+ `pricing_plans`, `service_catalog`, `get_tariff` for economics).
+- **per-subscriber** → `list_subscriber_packages`.
+- **create template** → `create_package_template`; refine with `modify_template_core`, `modify_template_recurring`, `modify_template_throttling`.
+- **assign** → `assign_package` (one-off) or `assign_recurring_package` (monthly). Use `stop_resume_recurring_package` to pause/resume.
+- **modify live package** → `modify_package_limits`, `modify_package_expiry`, `modify_package_status`, `modify_subscriber_package_active_period`.
+- **optimize** → `optimize_package` to right-size a subscriber's plan to their actual usage.
+- **remove** → `delete_subscriber_package` (or `clean_all_packages` — destructive, confirm explicitly).
+
+When assigning, verify the subscriber exists (`get_subscriber`) and there's sufficient credit. Show cost impact before committing.

package/plugin/carrier/commands/provision.md

@@ -0,0 +1,30 @@
+---
+description: Provision a new eSIM and assign a starter package
+argument-hint: "[account/reseller] [country or package] [qty]"
+---
+
+# Provision eSIM
+
+Issue free eSIM stock and assign a starter package so SIMs are ready to activate.
+
+Inputs from `$ARGUMENTS` (ask for anything missing): target **account/reseller**, destination **country/region** or **package template**, and **quantity** (default 1).
+
+## Preferred path — issue from inventory (Console parity)
+
+Matches Console / API `POST /v1/subscribers/issue-from-inventory`: OCS auto-picks a free eSIM on the account and assigns the package in one call.
+
+1. Confirm the account with `list_reseller_accounts` / `get_reseller_info` if not given (need numeric account id).
+2. Pick the package with `list_package_templates` (and `pricing_plans` / `service_catalog` for cost). If none fits, propose `create_package_template`.
+3. For each unit requested, call `assign_package` with **`account_for_subs` = account id** and **`packageTemplateId`** — **omit `iccid`**. Do not send both.
+4. Surface returned **ICCID**, packageId, and **activation QR / LPA / smdp** fields in a copyable block.
+5. Confirm stock with `esim_status_per_account` if the operator wants a fleet view.
+
+If OCS reports no free inventory, stop and tell the operator to add stock SIMs (eSIMVault), then retry.
+
+## Alternate paths
+
+- **Existing free ICCID known** → `assign_package` with `iccid` + `packageTemplateId` (no `account_for_subs`).
+- **Pro+ guided UI** → `provision_esim_wizard` (selects an existing subscriber, not raw inventory stock).
+- **Monthly auto-renew** → after issue, `assign_recurring_package` on the returned ICCID (or use recurring template at issue time only if the one-shot path is not appropriate).
+
+Never provision more than the requested quantity. If platform credit is low (`credit_balance`) or managed wallet is empty (`wallet_balance` via `/carrier:wallet`), warn before provisioning.

package/plugin/carrier/commands/sms.md

@@ -0,0 +1,18 @@
+---
+description: Send an SMS to a subscriber
+argument-hint: "[subscriber/MSISDN] [message]"
+---
+
+# Send SMS
+
+Send a text message to a subscriber via the Carrier network.
+
+From `$ARGUMENTS`: the **recipient** (subscriber id / MSISDN) and the **message**.
+
+Steps:
+1. Resolve the recipient with `get_subscriber` if only a name/id was given; confirm the MSISDN.
+2. Show the final recipient + message and **get confirmation before sending** (outbound message to a real person).
+3. Send with `send_sms`.
+4. Report delivery result.
+
+Keep messages within a single segment (160 GSM-7 chars) unless the user explicitly wants a multipart message. Never send to a list in bulk from this command.

package/plugin/carrier/commands/status.md

@@ -0,0 +1,15 @@
+---
+description: Quick control-plane + auth status check
+argument-hint: ""
+---
+
+# Carrier Status
+
+Fast health ping of the Carrier control plane. Run and summarize in one short block:
+
+- `environment_info` — which environment you're pointed at.
+- `credential_status` — OCS + provider auth OK?
+- `rate_limit_status` — API headroom.
+- `credit_balance` — funded?
+
+Output a single line per check with 🟢/🔴 and the key value. If anything is red, name the exact fix command. Keep it to a glance — no drilling unless asked.

package/plugin/carrier/commands/storefront.md

@@ -0,0 +1,21 @@
+---
+description: Scaffold, white-label, and deploy your eSIM storefront
+argument-hint: "[create|deploy|rebrand] [dir]"
+---
+
+# Storefront
+
+Roll out the customer-facing eSIM storefront (Mango template, white-labeled) that sits on top of your Carrier fleet.
+
+This wraps the `@carrierllc/cli` scaffolder.
+
+- **create** → run `npx @carrierllc/cli site create <dir>` (or `carrier site create`). Capture brand name, domain, accent color, support email; it generates `src/brand.config.ts` and a buildable Next.js storefront.
+- **rebrand** → edit `src/brand.config.ts` in the storefront dir (name, colors, tagline, domain, support, social) — the single white-label surface — then rebuild.
+- **deploy** → `npx @carrierllc/cli site deploy <dir>` → builds and pushes to Cloudflare Pages. Requires `wrangler login`.
+
+Wire-up notes:
+- The storefront talks to your control plane via `NEXT_PUBLIC_CARRIER_API_URL` (`.env.local`).
+- Plans shown to customers come from `pricing_plans` / `list_package_templates`; keep them in sync.
+- Checkout provisions through the same fleet — confirm `credential_status` is healthy before going live.
+
+After deploy, verify the live URL renders and the plans match `pricing_plans`.

package/plugin/carrier/commands/subscribers.md

@@ -0,0 +1,18 @@
+---
+description: List, inspect, and manage subscriber lifecycle
+argument-hint: "[list|view|suspend|resume|terminate] [subscriber/MSISDN/ICCID]"
+---
+
+# Subscribers
+
+Manage the subscriber lifecycle on the Carrier MVNO.
+
+Parse the action + target from `$ARGUMENTS`.
+
+- **list** → `list_subscribers` (paginate; summarize status, plan, last activity).
+- **view / diagnose** → `get_subscriber` + `diagnose_subscriber` for a full health picture (status, balance, active packages, recent network events).
+- **suspend / resume / terminate** → `modify_subscriber_status` with the appropriate state. **Confirm the exact subscriber and the destructive action before executing.**
+- **contact / plan changes** → `modify_subscriber_contact_info`, `modify_subscriber_mobile_plan`, `modify_subscriber_voip_plan`, `affect_subscriber_phone_number`.
+- **location** → `get_subscriber_location` / `get_subscriber_location_by_cell_id`.
+
+Always echo back the before/after state. For any status change affecting live service, require explicit confirmation naming the subscriber.

package/plugin/carrier/commands/usage.md

@@ -0,0 +1,16 @@
+---
+description: Inspect data usage, projections, and anomalies
+argument-hint: "[subscriber/MSISDN] [period]"
+---
+
+# Usage
+
+Report and forecast data consumption.
+
+- **current usage** → `subscriber_usage` for the subscriber/period in `$ARGUMENTS`.
+- **projection** → `usage_projection` to forecast depletion and recommend top-up timing.
+- **depletion / network events** → `subscriber_depletion_events`, `subscriber_network_events`.
+- **travel pattern** → `subscriber_country_history` (which networks/countries the SIM has roamed).
+- **anomalies** → `detect_usage_anomalies` across the fleet to catch runaway consumption or fraud.
+
+Summarize: used vs allotment, burn rate, projected depletion date, and a clear recommendation (top up, upsize, throttle, or no action). Flag anything anomalous prominently.

package/plugin/carrier/commands/wallet.md

@@ -0,0 +1,31 @@
+---
+description: Managed prepaid wallet balance, bulk pack top-up, and auto-top-up
+argument-hint: "[balance|topup|packs|auto]"
+---
+
+# Managed prepaid wallet
+
+Operate the **Atlas prepaid wallet** (managed-mode drawdown). This is **not** platform credit and **not** Stripe Connect.
+
+Money domain map (do not mix them up):
+
+| Domain | Tools | When |
+|--------|-------|------|
+| **Managed wallet** (this command) | `wallet_balance`, `wallet_topup_checkout`, `wallet_auto_topup` | Prepaid EUR balance that funds managed connectivity usage |
+| Platform credit | `credit_balance`, `balance_topup_form` | Carrier platform call/credit runway — see `/carrier:credits` |
+| Stripe Connect | `stripe_connect_*` | Operator payouts / disputes — see `/carrier:billing` |
+
+Inputs from `$ARGUMENTS` (ask if missing): subcommand **balance** | **topup** | **packs** | **auto**, and optional pack id.
+
+Steps:
+
+1. **balance** (default) → `wallet_balance` — EUR cents, auto-top-up enabled/threshold/pack.
+2. **packs** → `wallet_topup_checkout` with no `pack` — list pack_500 / pack_1000 / pack_2500 / pack_5000 (paid + bonus credit).
+3. **topup** → pick a pack with the operator, then `wallet_topup_checkout` with `pack` — return the hosted Checkout URL; wallet credits after payment completes.
+4. **auto** → only after explicit confirm: `wallet_auto_topup` (charges the saved payment method off-session). Prefer dry discussion of threshold first via `wallet_balance`.
+
+Safety:
+
+- Treat top-up and auto-top-up as money movement — confirm pack amount and org before executing.
+- If the operator asks for "credit" or "Connect payouts", redirect to `/carrier:credits` or `/carrier:billing`.
+- Never invent pack sizes outside the catalog returned by the tools.

package/plugin/carrier/skills/carrier-operations/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: carrier-operations
+description: Reference map of the Carrier MCP tool surface — domains, key tools, and safety rules for operating an MVNO/eSIM fleet. Load when planning multi-step fleet, billing, or storefront operations.
+---
+
+# Carrier Operations — MCP Tool Map
+
+Carrier is a programmable connectivity control plane (the "Stripe of telecom") exposed as an MCP server at `https://mcp.carrier.llc/mcp` (OAuth 2.1 + PKCE). Tools span these domains:
+
+## Provisioning & SIM lifecycle
+`assign_package` with `account_for_subs` (issue free eSIM from inventory — Console `issue-from-inventory` parity) · `provision_esim_wizard` (Pro+ UI on existing subscribers) · `change_sim_status` · `esim_status_per_account` · `get_sim_provider_status` · `audit_network_coverage` · `hlr_get_bitrate` / `hlr_set_bitrate`
+
+## Subscribers
+`list_subscribers` · `get_subscriber` · `diagnose_subscriber` · `modify_subscriber_status` · `modify_subscriber_contact_info` · `modify_subscriber_mobile_plan` · `modify_subscriber_voip_plan` · `affect_subscriber_phone_number` · `move_subscriber_range_to_account` · `get_subscriber_location[_by_cell_id]`
+
+## Packages & pricing
+`list_package_templates` · `create_package_template` · `modify_template_core|recurring|throttling` · `assign_package` · `assign_recurring_package` · `stop_resume_recurring_package` · `list_subscriber_packages` · `modify_package_limits|expiry|status` · `modify_subscriber_package_active_period` · `optimize_package` · `delete_subscriber_package` · `clean_all_packages` · `pricing_plans` · `service_catalog` · `get_tariff`
+
+## Usage & intelligence
+`subscriber_usage` · `usage_projection` · `subscriber_depletion_events` · `subscriber_network_events` · `subscriber_country_history` · `detect_usage_anomalies` · `churn_risk` · `marketing_intelligence` · `high_cost_subscribers`
+
+## Billing, credit & wallet (three money domains)
+- Platform credit: `credit_balance` · `balance_topup_form` · `billing_events` · `configure_billing` · `modify_subscriber_balance` · `modify_account_balance`
+- Stripe Connect: `stripe_connect_status|balance|payouts|dispute_list` (Radar / `stripe_proxy_call` are Pro/ops-gated)
+- Managed prepaid wallet: `wallet_balance` · `wallet_topup_checkout` · `wallet_auto_topup` (slash: `/carrier:wallet`)
+
+## Green zone / steering
+`greenzone_whitelist_list|add|remove` · `reset_subscriber_gz_counter` · `list_steering_lists` · `list_destination_lists` · `list_destination_prefixes` · `modify_subscriber_steering_list` · `push_steering_to_subscriber` · `set_subscriber_traffic_restrictions`
+
+## Fleet & platform
+`fleet_health` · `fleet_health_app` · `list_recent_ocs_events` · `rate_limit_status` · `carrier_ocs_calls_per_min` · `environment_info` · `credential_status` · `rotate_credentials` · `list_reseller_accounts` · `get_reseller_info` · `send_sms`
+
+## Gated surfaces (not free-tier defaults)
+- **Steel ui_agent_*** — requires `STEEL_API_KEY` / ops config; UI-only OCS ops.
+- **`stripe_proxy_call`** — Pro/Enterprise Stripe Agent Toolkit multiplexer.
+- **`provision_esim_wizard`** — Pro+ MCP App; free tier uses `assign_package` inventory path.
+
+## Safety rules (always)
+1. **Read before write.** Establish current state before any mutation.
+2. **Confirm money & live-service changes** — status changes, balance/package mutations, wallet top-ups, `clean_all_packages`, `rotate_credentials`, outbound `send_sms`.
+3. **Right quantity only** — never over-provision; check `credit_balance` and (managed mode) `wallet_balance` first.
+4. **Diagnose, don't guess** — use `diagnose_subscriber` + event tools for faults.
+5. The storefront layer (white-label Mango template) is scaffolded/deployed via `@carrierllc/cli`; keep its plans synced with `pricing_plans`.

package/templates/storefront/eslint.config.mjs

@@ -0,0 +1,15 @@
+import js from "@eslint/js";
+import nextPlugin from "eslint-config-next/flat.js";
+
+/** @type {import('eslint').Linter.Config[]} */
+const eslintConfig = [
+  js.configs.recommended,
+  ...nextPlugin,
+  {
+    rules: {
+      "no-unused-vars": "off",
+    },
+  },
+];
+
+export default eslintConfig;