feat(healthcare): OIG/SAM exclusion screening as $79/mo Stripe Subscription

Convert OIG/SAM from one-time $299/yr to recurring $79/month (card+ACH only) -
the first real recurring-billing product in the system. Exclusion screening is
a *monthly* federal obligation, so recurring monitoring fits the requirement and
is the biggest valuation lever (vs a one-time annual run).

Catalog (single source of truth):
- service-catalog.ts: add billing_interval + allowed_methods to ComplianceService;
  oig-sam-screening -> 7900c, billing_interval:"month", allowed_methods:[card,ach],
  name "(Monthly Monitoring)".
- gen-service-catalog.py + check-service-catalog-drift.py: carry/guard the two new
  fields; regenerate site catalog.

Checkout (api/src/routes/checkout.ts):
- mode:"subscription" with recurring price_data when billing_interval is set;
  surcharge absorbed for recurring (clean $79/mo); server-side METHOD_NOT_ALLOWED
  re-validation against allowed_methods.
- ensureColumns + migration 100: compliance_orders.stripe_subscription_id,
  bundle_upsell_sent_at (+ subscription index).

Webhooks (api/src/routes/webhooks.ts):
- record stripe_subscription_id on checkout.session.completed (subscription mode).
- invoice.paid (subscription_cycle only) -> re-dispatch screening for the cycle;
  invoice.payment_failed -> admin alert + first-failure customer nudge;
  customer.subscription.deleted -> mark order cancelled. (API 2026-03-25 moved the
  subscription link to invoice.parent.subscription_details.subscription.)

Fulfillment:
- job_server.py: pass recurring_cycle/invoice_id into the order.
- npi_provider.py: OIG handler labels renewal cycles "[Monthly cycle]" + re-screen
  note; bundle action runs only the FIRST screening + flags the $79/mo upsell.

Bundle land-and-expand:
- Provider Compliance Bundle now includes only the first OIG/SAM screening (was
  giving away $948/yr of monitoring inside an $899 bundle).
- new worker scripts/workers/bundle_upsell.py (+ pw-bundle-upsell timer): ~3 weeks
  after a paid bundle, emails the customer to continue $79/mo monitoring; dedup via
  bundle_upsell_sent_at; skips customers who already have an OIG/SAM order.

Surfaces updated to $79/mo: PaymentStep (filters methods, "Billed every month,
cancel anytime"), order pages, healthcare index, npi-compliance-check tool (also
fixed stale $699 bundle drift -> $899), hc_oig_screening + hc_compliance_bundle
emails.

Docs: billing.md gains a "Stripe-native Subscriptions" section + a reality-check
banner (Adyen/ERPNext-gateway model documented there is NOT live; Stripe is the
real rail). Fixed run-migrations.yml container name bug
(performancewest-postgres-1 -> performancewest-api-postgres-1, overridable).

Tests: api/tests/recurring-subscription.test.ts (28 assertions) covers catalog
gating, method validation, surcharge suppression, recurring line-item build,
invoiceSubscriptionId extraction, renewal-cycle gating. tsc clean; site build
clean; catalog drift OK.

Manual deploy step: enable invoice.paid, invoice.payment_failed,
customer.subscription.deleted on the Stripe webhook endpoint.

docs/billing.md

@@ -1,6 +1,20 @@
 # Billing & Payments Architecture
 
-**Last updated:** 2026-04-05
+**Last updated:** 2026-06-18
+
+> ⚠️ **Reality check (2026-06):** Large parts of this doc describe a *planned*
+> "ERPNext owns all billing via Adyen" architecture that is **NOT live**. What is
+> actually wired today:
+> - **Live payment rail = Stripe Checkout** (card + ACH), plus **PayPal** (direct
+>   Orders v2) and **crypto** (SHKeeper) — all in `api/src/routes/checkout.ts`.
+>   **Klarna** runs via Stripe.
+> - **Adyen is NOT integrated** (account approval never completed). The
+>   `Adyen-*` gateway names below are aspirational labels, not active gateways.
+> - **Recurring billing = Stripe Subscriptions** (see "Stripe-native
+>   Subscriptions"), the only recurring billing actually shipping, used by
+>   `oig-sam-screening` ($79/mo). ERPNext `createSubscription()` is unused.
+> ERPNext is still the system of record for invoices/accounting, but it is **not**
+> the payment gateway. Treat Adyen/ERPNext-gateway sections as future plan.
 
 ## Principle: ERPNext Owns All Billing
 
@@ -138,14 +152,70 @@ Sales Invoice:
 ```
 
 ### Recurring Services (Subscriptions)
-ERPNext Subscription DocType handles:
+
+> **Status:** the only recurring billing actually wired today is **Stripe-native
+> Subscriptions** (see next section), used by `oig-sam-screening` ($79/mo). The
+> ERPNext-Subscription / Adyen model below is **planned, not yet live** — Adyen
+> is not integrated and ERPNext `createSubscription()` is currently unused. The
+> services listed here are aspirational pricing, not active subscriptions.
+
+ERPNext Subscription DocType is intended to handle (NOT YET LIVE):
 - Registered Agent: $99/year per state (Wyoming: $49/year)
 - Annual Report Filing: $99/year per state
 - Canada CRTC Annual Maintenance: $349/year
 - US Formation Maintenance Bundle: $179/year (annual report + RA renewal)
 - CA Formation Maintenance Bundle: $179/year (annual return + AMB/RA renewal)
 
-Subscriptions auto-generate invoices. Payment collected via Adyen (saved payment method) or manual payment link.
+When built, subscriptions would auto-generate invoices (payment via a saved
+payment method or manual payment link).
+
+### Stripe-native Subscriptions (healthcare monitoring)
+
+Some compliance services are sold as **Stripe Subscriptions** (the billing engine
+is Stripe, not ERPNext). A service opts in via the catalog
+(`api/src/service-catalog.ts`):
+
+```ts
+"oig-sam-screening": {
+  name: "OIG/SAM Exclusion Screening (Monthly Monitoring)",
+  price_cents: 7900,                 // $79/month
+  billing_interval: "month",         // -> checkout builds mode:"subscription"
+  allowed_methods: ["card", "ach"],  // recurring needs off-session-capable rails
+  ...
+}
+```
+
+Flow:
+1. `checkout.ts` sees `billing_interval` -> creates a `mode:"subscription"`
+   Checkout Session with recurring `price_data`. The gateway surcharge is
+   **absorbed** (a subscription can't carry a one-time surcharge line) so the
+   customer is billed a clean `$79/month`.
+2. `allowed_methods` filters the picker in `PaymentStep.astro` (PayPal/Klarna/
+   crypto are one-time only and disappear) and is **re-validated server-side**
+   in `checkout.ts` (`METHOD_NOT_ALLOWED`).
+3. `webhooks.ts` handles the subscription lifecycle:
+   - `checkout.session.completed` (mode=subscription) -> records
+     `compliance_orders.stripe_subscription_id`, then first fulfillment.
+   - `invoice.paid` with `billing_reason=subscription_cycle` -> re-dispatches the
+     service handler (`recurring_cycle:true`) to re-run the screening + deliver a
+     fresh dated certificate. (The first invoice is skipped here — already handled
+     by `checkout.session.completed`.)
+   - `invoice.payment_failed` -> admin alert + first-failure customer nudge.
+   - `customer.subscription.deleted` -> order marked `cancelled`, fulfillment stops.
+
+**Stripe Dashboard webhook events (MUST be enabled on the prod endpoint):**
+in addition to the existing `checkout.session.completed`, `payment_intent.*`,
+`charge.dispute.created`, `balance.available`, enable:
+- `invoice.paid`
+- `invoice.payment_failed`
+- `customer.subscription.deleted`
+
+Without these three the monthly cycles will charge but never fulfill/alert.
+
+The `provider-compliance-bundle` ($899/yr) includes **only the first** OIG/SAM
+screening; customers are converted to the $79/mo monitoring subscription after
+that first cycle (the standalone $948/yr of monitoring is no longer given away
+inside the bundle).
 
 ### Formation Maintenance Bundles