docs: consolidate repository guides and preserve audit history

2026-09-11 14:22:41 +02:00
parent 115441a409
commit 682a3028bb
404 changed files with 3402 additions and 2621 deletions
@@ -0,0 +1,35 @@
+# Stripe activation
+
+Billing code is present, but production activation is an operator gate. Configure and test one
+recurring monthly Pro price in Stripe test mode before creating live-mode values. Test and live mode
+use different keys, price IDs, webhook endpoints, signing secrets, and customer data.
+
+## Required configuration
+
+1. Create one recurring monthly Pro price and enable the customer portal.
+2. Register `<APP_PUBLIC_BASE_URL>/api/billing/webhook` for
+   `customer.subscription.created`, `customer.subscription.updated`, and
+   `customer.subscription.deleted`.
+3. Supply these deployment-only values through the server environment:
+
+   ```text
+   STRIPE_SECRET_KEY=<test-or-live-secret-key>
+   STRIPE_PRICE_PREMIUM=<recurring-price-id>
+   STRIPE_WEBHOOK_SECRET=<endpoint-signing-secret>
+   ```
+
+Never put these values in Git, chat, screenshots, issue text, or CI logs. The webhook must receive the
+raw request body for signature verification.
+
+## Acceptance check
+
+Use a disposable authenticated account: Upgrade opens hosted Checkout for the configured price;
+completion returns to the billing-success route; the signed webhook stores the subscription and grants
+the expected entitlement; Manage billing opens the customer portal; cancellation removes the
+entitlement when the subscription is no longer active or trialing; and replaying an event remains
+idempotent.
+
+For live mode, repeat the product, portal, endpoint, and secret setup as one coordinated change. If
+activation must be stopped, removing the three values disables new Checkout/portal sessions without
+deleting billing history; repair webhook delivery and replay the authoritative event instead of
+manually changing roles.