feat: add first-run admin bootstrap flow and site-admin badge

README.md

@@ -36,12 +36,36 @@ If you open the app from another machine on your LAN, set `VITE_API_BASE_URL` an
 4. Start the worker:
    `npm run dev:worker`
 
+## First Run Checklist
+
+- [ ] Install dependencies: `npm install`
+- [ ] Copy `.env.example` to `.env.local` and fill required keys: `DATABASE_URL`, `COOKIE_SECRET`, `GOOGLE_MAPS_SERVER_KEY`, `VITE_GOOGLE_MAPS_PLATFORM_KEY`, and Stripe keys if testing billing
+- [ ] Run migrations: `npm run migrate`
+- [ ] Set `ALLOW_ADMIN_BOOTSTRAP=true` and define `ADMIN_BOOTSTRAP_TOKEN`
+- [ ] Start web, API, and worker: `npm run dev:web`, `npm run dev:api`, `npm run dev:worker`
+- [ ] Visit `/auth` and create the first site admin
+- [ ] Disable bootstrap after first admin creation: `ALLOW_ADMIN_BOOTSTRAP=false`
+- [ ] Verify admin billing access at `/api/admin/billing/workspaces`
+
+## First-run Admin Bootstrap
+
+Bootstrap mode is only needed when no active application admin exists.
+
+- The DB-backed `application_admins` table is the primary source of truth for app-admin access.
+- `ADMIN_EMAILS` and `BILLING_ADMIN_EMAILS` are fallback allowlists during rollout.
+
+1. Run migrations first: `npm run migrate`
+2. Set `ALLOW_ADMIN_BOOTSTRAP=true` and `ADMIN_BOOTSTRAP_TOKEN` in your env file
+3. Visit `/auth`, then create the first account in "Create first site admin" mode
+4. After the first admin is created, set `ALLOW_ADMIN_BOOTSTRAP=false`
+
 ## Stripe Billing Setup
 
 Stripe is now the active payments integration for self-serve subscriptions and one-time export packs.
 
 Configure these server-side env vars to enable billing routes:
 
+- `STRIPE_PUBLISHABLE_KEY`
 - `STRIPE_SECRET_KEY`
 - `STRIPE_WEBHOOK_SECRET`
 - `STRIPE_PRICE_STARTER_MONTHLY`