docs/clerk: social OAuth (Google/GitHub/Apple) dashboard setup steps

Co-Authored-By: Claude Opus 4.8 <[email protected]>

docs/clerk.md

@@ -94,3 +94,23 @@ The frontend half is smoked by building with `AUTH_MODE=clerk` and the
 same keys and confirming `/login` serves Clerk's `<SignIn />` wired to the
 instance — `npx next start` then `curl /login` shows the instance domain
 and `data-clerk` attributes.
+
+## Social OAuth (Google / GitHub / Apple)
+
+The redesigned `/login` renders Clerk's `<SignIn>` themed to the dark design
+system (`src/app/login/page.tsx` → `clerkAppearance`). The backend already
+validates any Clerk-issued JWT (generic OIDC), so **enabling social login is
+purely a Clerk-dashboard step — no code change**:
+
+1. **Clerk Dashboard → User & Authentication → Social Connections.**
+2. Toggle on **Google** and **GitHub** (Clerk's shared dev credentials work
+   immediately for testing; add your own OAuth client IDs/secrets for prod).
+3. **Apple** (uses the provided `AuthKey_*.p8`): enable Apple, then supply
+   - **Services ID** (your Apple "Sign in with Apple" identifier),
+   - **Apple Team ID**,
+   - **Key ID** + the **`.p8` private key** contents,
+   and add Clerk's callback URL to the Apple service's Return URLs.
+
+Once enabled, the "Continue with …" buttons appear automatically inside the
+themed `<SignIn>` — the frontend needs no redeploy. Local dev (`AUTH_MODE=local`)
+keeps the email/password form and shows no social buttons.