@tyroneross/build-loop 0.30.3

package/skills/authentication/references/google-lessons-example-web-app.md

@@ -0,0 +1,177 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Lessons from Example Web App (2025 Build)
+
+Real failures from shipping a Next.js + Supabase + Google OAuth app. Each one cost at least half a day. Read this when something breaks — there's a decent chance it's listed here.
+
+## 1. "Works in dev, fails in prod" Auth — Supabase SSR Cookie API
+
+**Symptom**: Sign-in works locally. In production, after Google consent the user lands back on `/signin`. No error in the UI. Vercel logs show:
+
+```
+TypeError: Cannot read properties of undefined (reading 'get')
+  at <supabase ssr internals>
+```
+
+**Root cause**: Supabase SSR ≥ 0.3 moved from `{ get, set, remove }` cookie methods to `{ getAll, setAll }`. Next.js 15 dev had fallback compat that masked the bug. Prod enforced the new contract.
+
+**Fix**: Use `await cookies()` and `getAll`/`setAll` everywhere. Full recipe in `oauth-setup.md`.
+
+**Prevention**: Test the prod build locally (`npm run build && npm start`) before every deploy. Dev-only bugs hide in the hot-reload fallback paths.
+
+## 2. Route-Group Conflict → Vercel `ENOENT` manifest failure
+
+**Symptom**: Local build works. Vercel build fails during "Collecting build traces":
+
+```
+Error: ENOENT: no such file or directory,
+lstat '/vercel/path0/.next/server/app/(app)/page_client-reference-manifest.js'
+```
+
+**Root cause**: `app/page.tsx` AND `app/(app)/page.tsx` both exist. Next.js generates the manifest at `.next/server/app/page_client-reference-manifest.js`, but the tracer expects it at `.next/server/app/(app)/page_client-reference-manifest.js`. The app won't deploy until one of the pages is removed.
+
+**Fix**:
+```bash
+rm app/page.tsx  # if using app/(app)/page.tsx as the real root
+npm run build
+ls .next/server/app/(app)/*manifest*  # verify manifest now exists
+```
+
+**Prevention**: Pick one root-level routing strategy up front — either a root `page.tsx` or a route group for authenticated views. Not both.
+
+## 3. "100% Complete" Claims Without End-to-End Testing
+
+**Symptom**: Status doc said "Stage 1: OAuth Authentication — 100% Complete". Actual state: sign-in was broken. This wasn't a technical bug — it was a process bug. Completion was claimed on "implementation written", not "flow works".
+
+**Fix**: Never mark auth "done" until:
+1. `npm run build` succeeds
+2. You can sign in via Google in the prod build
+3. Session survives hard refresh
+4. Session survives browser close/reopen
+5. Sign-out actually clears cookies
+6. A protected API route returns 401 when unauthenticated
+
+All six. Every time. See the verification checklist in `oauth-setup.md`.
+
+## 4. Production Trace Logs Are Essential
+
+**Observation**: Local debugging couldn't reproduce the Supabase SSR bug (#1). Only Vercel's production traces showed the exact error. Without them, debugging would have been blind guesses.
+
+**Prevention**:
+- Enable Vercel Log Drains or Sentry from day one
+- Add correlation IDs to auth callback logs (`callback_id=abc` so you can trace one user's flow)
+- Log the auth step at each stage: `auth.redirect`, `auth.callback_received`, `auth.tokens_exchanged`, `auth.session_set`
+
+Don't wait for production issues to add observability.
+
+## 5. `redirect_uri_mismatch` Chasing
+
+**Symptom**: After clicking "Sign in with Google", lands on a Google error page: `Error 400: redirect_uri_mismatch`.
+
+**Root cause — any of**:
+- Trailing slash difference (`http://localhost:3000` vs `http://localhost:3000/`)
+- Protocol difference (`http` vs `https`)
+- Wrong port
+- Using app URL as Google redirect when Supabase is in the middle (Supabase uses its own callback)
+- Stale entry in Google Cloud Console that doesn't match current env var
+
+**Fix**: The redirect URI you register in Google Cloud Console MUST match the one your app passes in the OAuth request **character-for-character**.
+
+For Supabase:
+```
+https://<project-ref>.supabase.co/auth/v1/callback
+```
+
+For direct OAuth:
+```
+https://your-domain.com/api/auth/callback/google
+http://localhost:3000/api/auth/callback/google
+```
+
+**Prevention**: Add a boot-time check that logs the exact redirect URI your app will send, and compare it manually with the Cloud Console list during setup.
+
+## 6. Credential Rotation Is Painful — Plan For It
+
+**Observation**: When a secret leaked, rotating the Google client secret required:
+1. Generate new secret in Google Cloud Console
+2. Update Supabase Dashboard → Providers → Google
+3. Update Vercel env var (`GOOGLE_CLIENT_SECRET`)
+4. Trigger redeploy
+5. Test sign-in flow
+6. After verifying, delete old secret in Cloud Console
+
+Steps 1-3 can be done with the old secret still active (Google supports two live secrets during rotation). If you skip the "both live" window, users in mid-session get `invalid_client`.
+
+**Prevention**: Document the rotation procedure BEFORE you need it. Store credentials in a secret manager (Vercel Env, Doppler, AWS Secrets Manager) so rotation is one place to change.
+
+## 7. "Demo" / "Placeholder" Values Shipped to Prod
+
+**Symptom**: `.env.example` had `GOOGLE_CLIENT_ID=your_client_id_here`. Someone copied it to `.env.local`, it got committed, CI pushed it to prod. Sign-in broke silently.
+
+**Fix**: Boot-time env validator that REFUSES to start in prod if any env var matches `your_|demo_|development|placeholder`:
+
+```ts
+const bad = Object.entries(requiredVars).filter(([, v]) =>
+  !v || /^(your_|demo_|development|placeholder)/i.test(v)
+)
+if (bad.length && process.env.NODE_ENV === 'production') {
+  throw new Error(`Missing env vars: ${bad.map(([k]) => k).join(', ')}`)
+}
+```
+
+## 8. CSRF Defense — State Parameter
+
+**Observation**: Without a state parameter, nothing stops a malicious site from forging an OAuth callback. Supabase's flow handles this internally; direct OAuth flows must generate + verify state themselves.
+
+**Pattern**:
+1. Generate a random state token, store in httpOnly cookie with 10-min TTL
+2. Pass state in the authorize URL
+3. On callback, compare returned state to the cookie
+4. Mismatch → reject, redirect to signin with `error=state_mismatch`
+
+See the code in `oauth-setup.md` section 6.
+
+## 9. Session Refresh Needs a Threshold
+
+**Symptom**: User's session expires mid-action, they lose unsaved work.
+
+**Fix**: Check expiry proactively. Refresh if `expires_at - now < 15 minutes`:
+
+```ts
+const timeUntilExpiry = session.expires_at - Math.floor(Date.now() / 1000)
+if (timeUntilExpiry < 15 * 60) {
+  await supabase.auth.refreshSession()
+}
+```
+
+Run this check on a 1-hour interval + on visibility change (user returns to tab).
+
+## 10. Open Redirect via `returnTo`
+
+**Symptom**: Code review flagged `?returnTo=http://evil.com` — sign-in flow would redirect to attacker's site.
+
+**Fix**: Allow-list validation on the redirect URL:
+
+```ts
+function isValidRedirect(url: string): boolean {
+  try {
+    const parsed = new URL(url, process.env.NEXT_PUBLIC_APP_URL)
+    const allowed = ['localhost', '127.0.0.1', new URL(process.env.NEXT_PUBLIC_APP_URL!).hostname]
+    return allowed.includes(parsed.hostname)
+  } catch {
+    return false
+  }
+}
+```
+
+Never trust a query param as a navigation target without validating its host.
+
+## Process Lessons (Not Technical)
+
+These aren't bugs, they're habits that would have prevented half the bugs:
+
+1. **Ship a sign-in E2E test before any other feature**. It's your canary. If sign-in breaks, everything else does.
+2. **Separate dev and prod Google Cloud projects**, not just credentials. Quota and consent-screen state are project-scoped.
+3. **Publish the OAuth consent screen early** so you hit Google verification before you have a deadline.
+4. **Use certainty markers** in status docs (✅ verified / ⚠️ untested / ❓ unknown) — not "100% complete".
+5. **Document rotation, scope changes, and env-var lifecycle** in a `docs/AUTH.md` — not buried in commits.

package/skills/authentication/references/google-maps.md

@@ -0,0 +1,162 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Google Maps JavaScript API — 2026 Modern Pattern
+
+## Enable and Restrict
+
+```
+Google Cloud Console → APIs & Services → Library
+  Enable: Maps JavaScript API
+  Enable: Places API (New)        ← for autocomplete/search
+  Enable: Geocoding API            ← for address ↔ lat/lng
+  Enable: Directions API           ← only if you need routing
+```
+
+Then:
+```
+APIs & Services → Credentials → + CREATE CREDENTIALS → API key
+```
+
+**Immediately restrict it** — unrestricted keys are scraped and billed within hours.
+
+- **Application restrictions**: HTTP referrers (web sites)
+  - `https://your-domain.com/*`
+  - `http://localhost:3000/*` (for dev)
+- **API restrictions**: Restrict key → select only the APIs you enabled above
+
+Create **one key per environment** (dev, staging, prod). Use the restriction to prevent a leaked dev key from calling prod APIs.
+
+Maps API keys are **public by design** — the browser sees them. Restriction, not secrecy, is what protects them.
+
+## Get a Map ID (Required for Advanced Markers)
+
+```
+Google Cloud Console → Google Maps Platform → Map Management → CREATE MAP ID
+  Map type: JavaScript
+  Raster or Vector: Vector (for cloud-based styling + Advanced Markers)
+```
+
+Save the Map ID — without it, `AdvancedMarkerElement` silently refuses to render.
+
+## Modern Async Loader Pattern
+
+Don't use `<script src="https://maps.googleapis.com/maps/api/js?key=...">` anymore. Use the inline bootstrap loader with `importLibrary()`.
+
+### Option A: Inline bootstrap (recommended — no npm dep)
+
+```html
+<script>
+(g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})
+({key: "YOUR_API_KEY", v: "weekly"});
+</script>
+```
+
+Paste that once in your root layout. It exposes `google.maps.importLibrary()` globally without actually fetching the API until you call it.
+
+### Option B: `@googlemaps/js-api-loader` (npm, typed)
+
+```ts
+import { Loader } from '@googlemaps/js-api-loader'
+
+const loader = new Loader({
+  apiKey: process.env.NEXT_PUBLIC_GOOGLE_MAPS_API_KEY!,
+  version: 'weekly',
+  libraries: ['maps', 'marker', 'places'],
+})
+```
+
+Per this repo's user preference (minimal deps, build from scratch), prefer **Option A** unless you already have the package for other reasons.
+
+## Render a Map with Advanced Markers
+
+```tsx
+'use client'
+import { useEffect, useRef } from 'react'
+
+declare global {
+  interface Window {
+    google: typeof google
+  }
+}
+
+export function CampMap({ camps }: { camps: { id: string; lat: number; lng: number; name: string }[] }) {
+  const ref = useRef<HTMLDivElement>(null)
+
+  useEffect(() => {
+    let cancelled = false
+    async function init() {
+      if (!ref.current) return
+      const { Map } = await google.maps.importLibrary('maps') as google.maps.MapsLibrary
+      const { AdvancedMarkerElement, PinElement } = await google.maps.importLibrary('marker') as google.maps.MarkerLibrary
+
+      if (cancelled) return
+
+      const map = new Map(ref.current, {
+        center: { lat: 40.7128, lng: -74.006 },
+        zoom: 11,
+        mapId: process.env.NEXT_PUBLIC_GOOGLE_MAPS_MAP_ID!,  // REQUIRED
+        disableDefaultUI: false,
+      })
+
+      for (const camp of camps) {
+        const pin = new PinElement({
+          background: '#4F46E5',
+          borderColor: '#312E81',
+          glyphColor: '#FFF',
+        })
+        new AdvancedMarkerElement({
+          map,
+          position: { lat: camp.lat, lng: camp.lng },
+          title: camp.name,
+          content: pin.element,
+        })
+      }
+    }
+    init()
+    return () => { cancelled = true }
+  }, [camps])
+
+  return <div ref={ref} className="h-[500px] w-full rounded-lg" />
+}
+```
+
+## Deprecated — DO NOT USE
+
+- `new google.maps.Marker(...)` — deprecated Feb 2024. Use `AdvancedMarkerElement`.
+- `google.maps.event.addListener(marker, 'click', ...)` on old Markers — use DOM events on the advanced marker's `content` element or its `.addListener('gmp-click', ...)`.
+- Synchronous script tag with `&callback=initMap` — still works but no IntelliSense/types and no lazy loading.
+
+## Types
+
+Install `@types/google.maps` (tiny, just ambient types):
+
+```bash
+npm i -D @types/google.maps
+```
+
+Or hand-roll the needed types to avoid the dep. The ambient types are not pulled into the bundle.
+
+## Common Failures
+
+- **"Google Maps JavaScript API error: InvalidKeyMapError"** — key doesn't exist, isn't enabled on this project, or the Maps JS API isn't enabled.
+- **"Google Maps JavaScript API error: ApiNotActivatedMapError"** — enable Maps JavaScript API on this project.
+- **"Google Maps JavaScript API error: RefererNotAllowedMapError"** — current origin not in the key's HTTP referrer allow-list. Common during local dev if you only whitelisted prod.
+- **Map renders but markers don't** — `mapId` missing, or you used `google.maps.Marker` without importing the `marker` library.
+- **Blank map / grey square** — container has height 0. `h-[500px]` or equivalent must resolve to pixels.
+- **"For development purposes only" watermark** — billing not enabled on the project. Google requires a billing account even for free-tier usage.
+
+## Cost Control
+
+Maps loads are $7/1000 after the free tier. Places API (New) Text Search is $32/1000 (without field mask). Aggressive field masks and client-side caching are critical.
+
+- Cache place details in your DB (with TTL per Google's usage terms — 30 days for most fields)
+- Use `fields` / `X-Goog-FieldMask` on every Places call
+- Prefer Autocomplete (cheaper) over Text Search when the user is typing
+- Session tokens on Autocomplete make a sequence of requests + one Place Details count as a single session (much cheaper)
+
+## Sources
+
+- [Load Maps JS API](https://developers.google.com/maps/documentation/javascript/load-maps-js-api)
+- [Advanced Markers migration](https://developers.google.com/maps/documentation/javascript/advanced-markers/migration)
+- [Advanced Markers reference](https://developers.google.com/maps/documentation/javascript/reference/advanced-markers)
+- [Libraries](https://developers.google.com/maps/documentation/javascript/libraries)

package/skills/authentication/references/google-oauth-setup.md

@@ -0,0 +1,343 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# OAuth Setup — Console + App Wiring
+
+End-to-end recipe for "Sign in with Google" on a web app. Includes Supabase flow (recommended for Next.js) and direct-OAuth flow (for when you're not using an auth provider).
+
+## 1. Create the Google Cloud Project
+
+```
+console.cloud.google.com → project selector → NEW PROJECT
+```
+
+Use **separate projects for dev and prod**. Not just separate credentials — separate projects. This isolates quotas, billing, and consent-screen state.
+
+## 2. Configure OAuth Consent Screen (DO THIS FIRST)
+
+You can't create an OAuth client until the consent screen exists.
+
+```
+APIs & Services → OAuth consent screen
+```
+
+- **User type**: External (unless you're inside a Workspace org and only need internal users)
+- **App name**: Your app's display name (shown on consent dialog — users see this)
+- **User support email**: Must be reachable
+- **App domain / privacy policy / terms of service**: Required before you can move out of "Testing" mode
+- **Authorized domains**: Root of your app URL (e.g. `your-domain.com` — no protocol)
+- **Developer contact**: Your email
+
+**Scopes**: Add only what you need. For basic sign-in:
+- `openid`
+- `https://www.googleapis.com/auth/userinfo.email`
+- `https://www.googleapis.com/auth/userinfo.profile`
+
+For Calendar read:
+- `https://www.googleapis.com/auth/calendar.readonly`
+
+For Calendar read+write:
+- `https://www.googleapis.com/auth/calendar.events`  (recommended — per-event access, narrower than `calendar`)
+
+**Test users**: While in Testing mode, add every email that needs to sign in. Testing mode is fine for dev; publish before prod.
+
+**Verification**: If you request any "sensitive" or "restricted" scopes (Calendar is sensitive), publishing the app triggers Google verification. Budget a week for first-time verification. Non-sensitive scopes (profile, email) don't need it.
+
+## 3. Create the OAuth Web Client
+
+```
+APIs & Services → Credentials → + CREATE CREDENTIALS → OAuth client ID
+```
+
+- **Application type**: Web application
+- **Name**: `<app> Web Client (prod)` — name it so you can tell dev from prod later
+- **Authorized JavaScript origins**:
+  - `https://your-domain.com`
+  - Local dev: `http://localhost:3000` (use the actual port)
+- **Authorized redirect URIs** — EXACT MATCH, no trailing slash:
+  - **If using Supabase**: `https://<your-supabase-project>.supabase.co/auth/v1/callback` (NOT your app URL — Supabase handles the exchange)
+  - **If direct OAuth**: `https://your-domain.com/api/auth/callback/google`
+  - Local dev: `http://localhost:3000/api/auth/callback/google`
+
+Copy the **Client ID** and **Client Secret** immediately. The secret is visible only until you navigate away; you can re-download later but it's easier to store now. Treat the secret like a password.
+
+## 4. Wire Up Supabase (Recommended for Next.js Apps)
+
+```
+Supabase Dashboard → Authentication → Providers → Google → ON
+```
+
+- Paste **Client ID** and **Client Secret**
+- Save
+- Then: `Authentication → URL Configuration`
+  - **Site URL**: `https://your-domain.com` (must match `NEXT_PUBLIC_APP_URL` in your app)
+  - **Redirect URLs**: `https://your-domain.com/**` and `http://localhost:3000/**`
+
+Supabase handles the token exchange, session cookies, and refresh-token storage. You don't write any OAuth code — you call `supabase.auth.signInWithOAuth({ provider: 'google' })`.
+
+## 5. Next.js 16 Cookie API (CRITICAL)
+
+This is the #1 production auth bug. Next.js 15+ made `cookies()` async; Supabase SSR ≥ 0.3 requires the `getAll`/`setAll` shape, not the old `get`/`set`/`remove`.
+
+### ❌ OLD — DO NOT USE
+```ts
+// This fails in production on Next.js 15+
+const cookieStore = cookies()
+createServerClient(url, key, {
+  cookies: {
+    get: cookieStore.get,
+    set: cookieStore.set,
+    remove: cookieStore.remove,
+  },
+})
+```
+
+### ✅ NEW — REQUIRED
+```ts
+// lib/supabase/server.ts
+import { createServerClient } from '@supabase/ssr'
+import { cookies } from 'next/headers'
+import type { Database } from '@/types/database'
+
+export async function createServerSupabase() {
+  const cookieStore = await cookies()  // NOTE: await
+  return createServerClient<Database>(
+    process.env.NEXT_PUBLIC_SUPABASE_URL!,
+    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
+    {
+      cookies: {
+        getAll() {
+          return cookieStore.getAll()
+        },
+        setAll(cookiesToSet) {
+          try {
+            cookiesToSet.forEach(({ name, value, options }) =>
+              cookieStore.set(name, value, options)
+            )
+          } catch {
+            // Called from a Server Component — set via middleware instead
+          }
+        },
+      },
+    }
+  )
+}
+```
+
+### Why the try/catch?
+
+Supabase SSR tries to `set` cookies during Server Component rendering, but Next.js disallows that (Server Components can't set cookies). The try/catch lets it fail silently; the middleware refresh below handles the actual cookie writes.
+
+### Middleware session refresh
+```ts
+// middleware.ts
+import { createServerClient } from '@supabase/ssr'
+import { NextResponse, type NextRequest } from 'next/server'
+
+export async function middleware(request: NextRequest) {
+  let response = NextResponse.next({ request })
+
+  const supabase = createServerClient(
+    process.env.NEXT_PUBLIC_SUPABASE_URL!,
+    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
+    {
+      cookies: {
+        getAll() { return request.cookies.getAll() },
+        setAll(cookiesToSet) {
+          cookiesToSet.forEach(({ name, value }) => request.cookies.set(name, value))
+          response = NextResponse.next({ request })
+          cookiesToSet.forEach(({ name, value, options }) =>
+            response.cookies.set(name, value, options)
+          )
+        },
+      },
+    }
+  )
+
+  // Must call getUser to refresh the session
+  await supabase.auth.getUser()
+  return response
+}
+
+export const config = {
+  matcher: ['/((?!_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)'],
+}
+```
+
+## 6. Direct OAuth Flow (No Supabase)
+
+Use this only if you're not using Supabase/Auth.js/Clerk. Most of the time, one of those is the right call.
+
+```ts
+// app/api/auth/google/route.ts
+import { NextResponse } from 'next/server'
+import { randomBytes } from 'crypto'
+import { cookies } from 'next/headers'
+
+export async function GET() {
+  const state = randomBytes(32).toString('hex')
+  const cookieStore = await cookies()
+
+  // Store state in httpOnly cookie for CSRF validation
+  cookieStore.set('oauth_state', state, {
+    httpOnly: true,
+    secure: process.env.NODE_ENV === 'production',
+    sameSite: 'lax',
+    maxAge: 600, // 10 min
+    path: '/',
+  })
+
+  const params = new URLSearchParams({
+    client_id: process.env.GOOGLE_CLIENT_ID!,
+    redirect_uri: `${process.env.NEXT_PUBLIC_APP_URL}/api/auth/callback/google`,
+    response_type: 'code',
+    scope: 'openid email profile',
+    state,
+    access_type: 'offline',   // get refresh token
+    prompt: 'consent',        // force refresh token on every consent
+  })
+
+  return NextResponse.redirect(
+    `https://accounts.google.com/o/oauth2/v2/auth?${params}`
+  )
+}
+```
+
+```ts
+// app/api/auth/callback/google/route.ts
+import { NextResponse, type NextRequest } from 'next/server'
+import { cookies } from 'next/headers'
+
+export async function GET(request: NextRequest) {
+  const url = new URL(request.url)
+  const code = url.searchParams.get('code')
+  const state = url.searchParams.get('state')
+  const cookieStore = await cookies()
+  const savedState = cookieStore.get('oauth_state')?.value
+
+  // CSRF check
+  if (!code) return NextResponse.redirect('/signin?error=missing_code')
+  if (!state || !savedState) return NextResponse.redirect('/signin?error=state_missing')
+  if (state !== savedState) return NextResponse.redirect('/signin?error=state_mismatch')
+
+  // Exchange code for tokens
+  const tokenRes = await fetch('https://oauth2.googleapis.com/token', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body: new URLSearchParams({
+      code,
+      client_id: process.env.GOOGLE_CLIENT_ID!,
+      client_secret: process.env.GOOGLE_CLIENT_SECRET!,
+      redirect_uri: `${process.env.NEXT_PUBLIC_APP_URL}/api/auth/callback/google`,
+      grant_type: 'authorization_code',
+    }),
+  })
+
+  if (!tokenRes.ok) return NextResponse.redirect('/signin?error=oauth_exchange_error')
+
+  const tokens = await tokenRes.json()
+  // tokens: { access_token, refresh_token, expires_in, id_token, scope, token_type }
+
+  // Store refresh_token securely server-side (e.g. encrypted DB column)
+  // Store a session cookie for the user
+
+  cookieStore.delete('oauth_state')
+  return NextResponse.redirect('/dashboard')
+}
+```
+
+## 7. Env Validation
+
+Refuse to run with missing or placeholder values. Add this to `instrumentation.ts` so it runs at boot.
+
+```ts
+// instrumentation.ts
+export function register() {
+  const required = {
+    NEXT_PUBLIC_SUPABASE_URL: process.env.NEXT_PUBLIC_SUPABASE_URL,
+    NEXT_PUBLIC_SUPABASE_ANON_KEY: process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY,
+    GOOGLE_CLIENT_ID: process.env.GOOGLE_CLIENT_ID,
+    GOOGLE_CLIENT_SECRET: process.env.GOOGLE_CLIENT_SECRET,
+    NEXT_PUBLIC_APP_URL: process.env.NEXT_PUBLIC_APP_URL,
+  }
+
+  const bad = Object.entries(required).filter(([, v]) =>
+    !v || /^(your_|demo_|development|placeholder)/i.test(v)
+  )
+
+  if (bad.length > 0) {
+    const names = bad.map(([k]) => k).join(', ')
+    if (process.env.NODE_ENV === 'production') {
+      throw new Error(`Missing/placeholder env vars: ${names}`)
+    }
+    console.warn(`⚠️  Auth config incomplete: ${names}`)
+  }
+
+  // Prod sanity
+  if (process.env.NODE_ENV === 'production') {
+    if (!process.env.NEXT_PUBLIC_APP_URL?.startsWith('https://')) {
+      throw new Error('NEXT_PUBLIC_APP_URL must use HTTPS in production')
+    }
+    if (process.env.NEXT_PUBLIC_APP_URL !== process.env.NEXT_PUBLIC_SITE_URL) {
+      throw new Error('APP_URL and SITE_URL must match in production')
+    }
+  }
+}
+```
+
+## 8. Redirect URL Validation
+
+Never blindly trust a `returnTo` query param — it's the classic open-redirect vector.
+
+```ts
+export function isValidRedirectUrl(url: string | null): boolean {
+  if (!url) return false
+  try {
+    const parsed = new URL(url, process.env.NEXT_PUBLIC_APP_URL)
+    const allowed = [
+      'localhost',
+      '127.0.0.1',
+      new URL(process.env.NEXT_PUBLIC_APP_URL!).hostname,
+    ]
+    return allowed.includes(parsed.hostname)
+  } catch {
+    return false
+  }
+}
+```
+
+## 9. Error Code Mapping
+
+Give users actionable messages. Don't expose raw Google/Supabase errors.
+
+```ts
+export function oauthErrorMessage(code: string): string {
+  const map: Record<string, string> = {
+    missing_code: 'Authorization failed. Please try signing in again.',
+    state_missing: 'Security validation failed. Please try again.',
+    state_mismatch: 'Security validation failed. Please try again.',
+    session_failed: 'Failed to create session. Please try again.',
+    oauth_exchange_error: 'OAuth token exchange failed. Please try again.',
+    access_denied: 'You denied access. Please grant permission to sign in.',
+    invalid_grant: 'Authorization expired. Please sign in again.',
+    invalid_client: 'Configuration error. Please contact support.',
+    browser_extension_conflict: 'Browser extension is blocking sign-in. Disable ad blockers and retry.',
+    nextjs_cookie_error: 'Cookies are disabled. Enable cookies and retry.',
+  }
+  return map[code] ?? 'Authentication failed. Please try again.'
+}
+```
+
+## 10. Verification Checklist
+
+Don't mark auth "done" until all of these pass:
+
+- [ ] `npm run build` succeeds
+- [ ] Sign-in button navigates to Google consent screen
+- [ ] Consent grants → redirect to callback → lands on dashboard
+- [ ] Hard refresh → still signed in
+- [ ] Close browser, reopen → still signed in
+- [ ] Sign-out clears cookies and redirects to `/signin`
+- [ ] Protected route redirects unauthenticated users
+- [ ] Protected API route returns 401 for unauthenticated requests
+- [ ] Works in prod build locally (`npm run build && npm start`)
+- [ ] Works in actual production deploy (NOT just dev)