docs(fork): add service-config checklist + auth verification section

README.md

@@ -32,6 +32,8 @@ A comprehensive Next.js starter kit featuring 32 themes, PWA capabilities, compo
 
 ## 🚀 Quick Start
 
+> 💡 **New to ScriptHammer?** Start at [`docs/FORK-CHECKLIST.md`](./docs/FORK-CHECKLIST.md) for the complete service-setup matrix — which env vars to set, which services are required vs. optional, where to sign up for each, and the suggested setup order. The Quick Start below is just the bare minimum to boot the dev server.
+
 ### Prerequisites
 
 - Docker and Docker Compose installed
@@ -103,6 +105,25 @@ Once configured, `/payment-demo` should work end-to-end against sandbox APIs. Th
 
 **Current payment implementation status**: [docs/prp-docs/PRP-STATUS.md#v040--payments-active-tracking](./docs/prp-docs/PRP-STATUS.md) — shows which features are built, which need routes, and which need UI work.
 
+## 🔐 Authentication Setup
+
+ScriptHammer ships with full email/password + OAuth (GitHub, Google) authentication via Supabase. Out of the box, the app won't authenticate users until you create a Supabase project and configure your auth providers.
+
+**For a brand-new forker**: start at [`docs/FORK-CHECKLIST.md`](./docs/FORK-CHECKLIST.md) — it's the master walkthrough covering every service this template integrates with.
+
+**For auth specifically**:
+
+1. **Create a Supabase project** at [supabase.com/dashboard](https://supabase.com/dashboard) (free tier is fine)
+2. **Run database migrations** — see [`docs/AUTH-SETUP.md` Part 1](./docs/AUTH-SETUP.md#part-1-database-setup)
+3. **Configure auth providers** (pick what you need):
+   - [Email/password](./docs/AUTH-SETUP.md#part-2-enable-emailpassword-authentication) — required for the messaging features
+   - [GitHub OAuth](./docs/AUTH-SETUP.md#part-3-enable-github-oauth-optional) — create a [GitHub OAuth App](https://github.com/settings/developers)
+   - [Google OAuth](./docs/AUTH-SETUP.md#part-4-enable-google-oauth-optional) — create a [Google Cloud OAuth client](https://console.cloud.google.com/apis/credentials)
+4. **Add Supabase keys to `.env`** — `NEXT_PUBLIC_SUPABASE_URL` and `NEXT_PUBLIC_SUPABASE_ANON_KEY` from [your project's API settings](https://supabase.com/dashboard)
+5. **Verify** — run the [Management API check](./docs/AUTH-SETUP.md#verification-via-management-api) to confirm your OAuth client IDs are real values, not placeholders. (Issue #85 was caused by placeholder strings sitting in this field for weeks before anyone noticed.)
+
+The full step-by-step is in [`docs/AUTH-SETUP.md`](./docs/AUTH-SETUP.md) (Parts 1-7, ~380 lines).
+
 ## 🔐 GitHub Actions Secrets
 
 Add these secrets to your repository at **Settings → Secrets and variables → Actions → Repository secrets**.

docs/AUTH-SETUP.md

@@ -2,6 +2,8 @@
 
 Complete guide for configuring Supabase authentication with email/password and OAuth providers.
 
+> **Forking ScriptHammer for the first time?** Start at [`docs/FORK-CHECKLIST.md`](FORK-CHECKLIST.md) — it's the master walkthrough covering every external service this template integrates with (auth, payments, email, analytics). This document is the deep-dive for the auth portion.
+
 ## Prerequisites
 
 - Supabase project created — substitute its ref for `<YOUR-PROJECT-REF>` in the URLs below
@@ -297,6 +299,54 @@ docker compose exec scripthammer pnpm run dev
 - Navigate to: https://supabase.com/dashboard/project/<YOUR-PROJECT-REF>/auth/users
 - You should see your GitHub/Google account in the user list
 
+## Verification via Management API
+
+The fastest way to confirm OAuth is actually wired up correctly — without trial-and-error in the dashboard — is to query the Supabase Management API directly. This is the exact check that would have caught [issue #85](https://github.com/TortoiseWolfe/ScriptHammer/issues/85): OAuth Client IDs left as the literal strings `placeholder_google_client_id` / `placeholder_github_client_id` for weeks, surfacing only as `Error 401: invalid_client` when a user clicked "Continue with Google."
+
+**Prerequisites:**
+
+- `SUPABASE_ACCESS_TOKEN` in your `.env` — generate at [supabase.com/dashboard/account/tokens](https://supabase.com/dashboard/account/tokens)
+- `jq` installed (already in the Docker container; on host: `apt install jq` / `brew install jq`)
+
+**Run the check:**
+
+```bash
+curl -sS -H "Authorization: Bearer $SUPABASE_ACCESS_TOKEN" \
+  "https://api.supabase.com/v1/projects/<YOUR-PROJECT-REF>/config/auth" \
+  | jq '{
+      google_enabled: .external_google_enabled,
+      google_client_id: .external_google_client_id,
+      github_enabled: .external_github_enabled,
+      github_client_id: .external_github_client_id,
+      site_url,
+      uri_allow_list
+    }'
+```
+
+**Expected output (correctly configured):**
+
+```json
+{
+  "google_enabled": true,
+  "google_client_id": "123456789012-abc.apps.googleusercontent.com",
+  "github_enabled": true,
+  "github_client_id": "Iv1.0123456789abcdef",
+  "site_url": "https://yourdomain.com",
+  "uri_allow_list": "https://yourdomain.com/auth/callback"
+}
+```
+
+**Red flags:**
+
+- `google_client_id` is the literal string `placeholder_google_client_id` — Google OAuth is misconfigured. Re-do [Part 4](#part-4-enable-google-oauth-optional).
+- `github_client_id` is the literal string `placeholder_github_client_id` — GitHub OAuth is misconfigured. Re-do [Part 3](#part-3-enable-github-oauth-optional).
+- `google_client_id` does NOT end in `.apps.googleusercontent.com` — not a real Google OAuth client ID.
+- `github_client_id` is not 20-character hex (or `Iv1.` prefix for GitHub Apps) — not a real GitHub OAuth client ID.
+- `site_url` is `http://localhost:3000` but you've deployed to production — update via [auth URL configuration](https://supabase.com/dashboard/project/<YOUR-PROJECT-REF>/auth/url-configuration).
+- `uri_allow_list` is empty but you've deployed to production — must include your production callback URL.
+
+This one-line check is fast enough to run as part of every deploy verification.
+
 ## Part 7: Environment Variables
 
 ### 7.1 Required Environment Variables