feat: complete admin phase C and add safe mutation pilot

README.md

@@ -89,6 +89,36 @@ Notes:
 - Billing return notices now appear on the account page for completed and canceled checkout flows.
 - Internal billing support visibility is available through `/api/admin/billing/workspaces` for allowlisted admin emails.
 
+## Admin Operations Runbook
+
+Bootstrap/security hardening checklist after first-run admin setup:
+
+- Set `ALLOW_ADMIN_BOOTSTRAP=false` and redeploy API.
+- Rotate `ADMIN_BOOTSTRAP_TOKEN` and store it in your secrets manager.
+- Ensure at least two active app-admin identities are configured.
+- Prefer `ADMIN_EMAILS`; stop relying on deprecated `BILLING_ADMIN_EMAILS` fallback.
+
+Support diagnostics starting thresholds:
+
+- Failed webhooks: investigate when there are 5+ failures in 15 minutes or 20+ failures in 24 hours.
+- Stale sync accounts: investigate when 10+ workspaces are stale for more than 24 hours.
+- Repeated payment failures: investigate any workspace with 3+ `invoice_payment_failed` events in 7 days.
+- Pending plan effective in past: investigate when count remains above 0 for more than 2 hours.
+
+First-response sequence for repeated failures:
+
+1. Open Admin Console diagnostics and capture affected workspace IDs.
+2. Open each workspace detail and review recent timeline and webhook event history.
+3. Verify Stripe webhook delivery status and replay failed events where safe.
+4. Confirm billing sync recovers and anomaly counts return toward baseline.
+5. Escalate with captured event IDs and workspace IDs if issues persist.
+
+Safe mutation pilot:
+
+- Admin Console now includes a constrained billing resync mutation.
+- Required inputs: `workspaceId`, operational reason, and typed confirmation (`RESYNC`).
+- Optional input: `ticketRef` for support/incident traceability.
+
 ## Docker Deployment
 
 1. Copy `.env.example` to `.env` and set at least: