OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add manaflow-ai/cmux --skill cmux-billing
Stripe checkout, pricing, subscription, Pro plan, webhook, and entitlement runbook for cmux billing work. Use when editing or debugging billing, pricing, Stripe Checkout, subscription recording, Pro plan status, webhooks, entitlement metadata, or pricing dev/prod tooling.
npx skills add manaflow-ai/cmux --skill cmux-billing
Read before changing billing, pricing, Stripe, Pro entitlement, checkout, webhook, or subscription code.
/api/billing/checkout creates Stripe Checkout Sessions for Pro when STRIPE_SECRET_KEY is set. It sets client_reference_id to the Stack user id, auto-creates an anonymous Stack user for signed-out buyers, and falls back to the legacy Stack purchase path when Stripe is unset or plan=team. The "already active" short-circuit lives here./api/billing/portal resolves the current Stack user, looks up their stripe_customers row, and creates a Stripe customer portal session returning to /pricing./api/billing/subscription cancels or resumes the active Stripe Pro subscription; /dashboard/billing renders localized in-dashboard plan state and self-serve actions.web/services/billing/purchase.ts is the shared idempotent recorder used by /api/billing/complete and /api/stripe/webhook. It attaches email to the purchaser, records billing_email_claims on conflict, and never cross-grants based on an unverified email.clientReadOnlyMetadata: a non-empty cmuxVmPlan (operator override) takes precedence, otherwise cmuxPlan (the Stripe mirror) supplies the entitlement. resolveProPlanStatus reports Pro for an active stripe_subscriptions row or a paid cmuxVmPlan override (pro, team, founders); billingManagement stays Stripe-only, so a granted account shows Pro without a portal link.admin/ in cmuxterm-hq) lets verified cmux.com, manaflow.ai, and manaflow.com accounts search users, teams, and emails and, after a confirmation dialog: grant or remove the user cmuxVmPlan override (/api/admin/users), grant or remove a team override of team (/api/admin/teams), grant Pro to an email with no account yet (/api/admin/email-grants, stored in admin_plan_grants and applied by the after-sign-in callback once the mailbox is verified), and downgrade a paying customer by cancelling the Stripe subscription at period end (/api/admin/subscriptions, same service as the self-serve form). services/admin/access.ts is the gate, services/admin/proGrants.ts writes under the account-mutation lease and records serverMetadata.cmuxAdminPlanGrant (who, when, which plan). Non-admins get 403 on the API; there is no admin page on cmux.com. The admin_plan_grants migration is an operator step; until it runs, pending email grants report 503 and search omits them./api/stripe/webhook is signature-verified, insert-first idempotent through stripe_webhook_events, safe for foreign events in the shared Stripe account, and gates cmux handling on metadata.app === "cmux". Return 2xx only after durable writes; return 500 to make Stripe retry.web/scripts/stripe/dev-stack.sh.bun dev accounts use the development Stack project and receive a
non-persistent Pro entitlement automatically. This applies only when
CMUX_LOCAL_DEV_PRO=1, NODE_ENV=development, VERCEL_ENV is unset, and
NEXT_PUBLIC_STACK_PROJECT_ID is the development project. Release and
preview deployments remain billing-backed. Use dev-grant.sh only when
testing an explicit manual grant or a non-local deployment.CMUX_PORT into Info.plist; run the dev server on the tag's printed port, never a hardcoded one.--db-port and never stop containers you did not create./app-pricing requires cmux_app=1. cmux_scheme threads the native deeplink return scheme; cmux-dev-* schemes are honored only for localhost requests.web/scripts/stripe/dev-reset.sh <email> to un-Pro a signed-in dev account before retesting checkout.web/scripts/stripe/dev-grant.sh <email> writes cmuxVmPlan: "pro" directly (same override as the admin page) (instant, no checkout; undo with dev-reset). For the full checkout path at $0, enter promotion code CMUXDEV100 in test-mode checkout — a 100%-off forever coupon in the test account; allow_promotion_codes is already set on checkout sessions.stripe config --list as key=value (older builds used key = 'value'); dev-stack.sh and dev-reset.sh accept both. If key extraction fails, re-run stripe login.Prices live in web/services/billing/plans.ts and are provisioned by web/scripts/stripe/provision-catalog.sh. Current checkout keys: cmux-go-monthly-10 ($10/mo), cmux-pro-monthly-50 ($50/mo), cmux-max-monthly-200 ($200/mo, monthly only, no yearly Price on purpose), cmux-team-monthly-60 ($60/user/mo), all billed monthly. Go and Max are personal plans like Pro: the user-scoped subscription row's plan column is derived from its Price lookup key (personalPlanIdForSubscription), cmuxPlan mirrors the exact purchased plan, and every isPro check passes. A Pro subscriber who buys Max goes through /api/billing/portal?flow=switch_plan&plan=max, which opens Stripe's subscription-update flow with the portal configuration stamped metadata.purpose=personal_plan_switch (the script provisions it; the account default configuration stays quantity-only). Stripe amounts are immutable, so a price change mints a new lookup key carrying the amount and adds the old key to LEGACY_PRICE_LOOKUP_KEYS; grandfathered Prices (cmux-pro-monthly $30, cmux-pro-yearly $240, cmux-pro-yearly-288 $288, cmux-team-monthly $35, cmux-team-yearly-336 $336, cmux-pro-yearly-480 $480, cmux-team-yearly-576 $576) stay active for the subscriptions on them and /dashboard/billing prices every row from its own Stripe amount. Env price-id overrides carry the amount in their name (STRIPE_PRO_MONTHLY_50_PRICE_ID and friends); a retired name fails env validation, so delete it from Vercel before deploying a price change. Test-mode Pro product prod_UyHgRPpmCzrkLJ, live prod_Uq4a28vk0fP3E6; test-mode Max product prod_VEpLXrLxxrIFTx (price price_1UELhFLbtiW1udY8YwbWvt0P, switch portal bpc_1UELhHLbtiW1udY89mZWzSi0); live Max product prod_VEpRwst8UwD5cm (price price_1UELmdGhInAdn3Jb8Gpe9ilK, switch portal bpc_1UELmeGhInAdn3JbgZqLIbP0). STRIPE_PERSONAL_PLAN_SWITCH_PORTAL_CONFIGURATION_ID is pinned in Vercel (production = live id, development and preview = test id) so the restricted production key never has to list portal configurations. Staging webhook endpoint we_1Tq1SZGhInAdn3JbWJReKNEN forwards to cmux-staging.vercel.app; its secrets are already in the cmux-staging Vercel project.
The paid Cloud VM allowance lives in web/services/vms/machineSpec.ts: Pro allows up to 50 machines for one paid account. Team grants 50 machines per paid seat. Each machine has its own CPU, memory, and disk; there is no aggregate resource pool. The default machine has 8 GB RAM and 32 GB disk. Free, Pro, Team, and Founder's machines stop at 24 GB RAM (PLAN_MAX_MEMORY_MB); the 32 GB and 64 GB ladder rows are what Max sells (maxMemoryMbForPlan("max")). The machine list publishes lockedMemoryOptionsMb and memoryUpgradePlanId, and a create that asks for a locked size gets 402 vm_memory_requires_plan instead of a silently smaller machine. Disk grows independently up to 256 GB. The repository enforces machine counts under the billing-team lock and tracks individual shapes for fork, snapshot, and resize recovery. Paid-limit environment overrides are retired; the create kill switch remains the incident control.
New annual checkout requests return annual_unavailable before creating Stripe state. Annual prices stay active only for existing subscriptions; new checkout price resolution and the personal plan-switch portal allow monthly offers only. Pricing views and CTA analytics always report interval: month and discount_percent: 0.
pro-upgrade-ui-enabled-release (PostHog id 741838) gates all Pro UI and stays OFF in release until launch; DEBUG builds default it on. Public Pro and Team pricing CTAs always route through /api/billing/checkout, never the download confirmation page. cmux __internal_flags, once merged, inspects and overrides flags locally.
Run web/scripts/stripe/provision-live.sh with an operator key, add the two Vercel envs, deploy, validate live with a 100-percent-off promotion code purchase, then cancel.
DB migrations: bun run cloud-vm:preflight, bun run cloud-vm:migrate -- staging, staging deploy, then bun run cloud-vm:migrate -- production. Never run migrations from builds. See the Cloud VM ops flow.
bun mock.module is process-global, so every module mock must carry every real export other suite files import. A missing export can surface only in CI's test order as Export named X not found.DATABASE_URL being set.DrizzleQueryError; read error.cause for the pg code and constraint.app/[locale] need a proxy.ts bypass (like /app-pricing and /billing), or next-intl rewrites them into the locale tree and they 404 through missing root layout tags. Those subtrees also need their own layout with html and body.