Billing Lifecycle

• User selects a plan on /pricing or /checkout/[plan].
• components/CheckoutButton.tsx posts { plan } to /api/checkout/stripe.
• The checkout route requires a signed-in user, required Supabase env vars, service-role key, Stripe secret key, and the selected plan price id.
• The server ensures an organization and creates a Stripe Checkout Session in subscription mode.
• The checkout session is inserted into checkout_sessions with status created.
• Stripe redirects the user to Checkout. On success, Stripe sends checkout.session.completed to the webhook endpoint.
• The webhook resolves the checkout session, upserts customer/subscription rows, marks checkout completed, writes audit/billing events, and the dashboard reads subscription status.

POST /api/billing/portal creates a Stripe Billing Portal session for signed-in users with a known Stripe customer id. Stripe handles payment method changes, cancellation, invoice/payment management, and subscription updates in the hosted portal.

invoice.payment_failed refreshes subscription state and can trigger payment-failure email behavior when SES is configured. Access checks in lib/usage.ts only treat active and trialing as active.