@tyroneross/build-loop 0.30.3

package/skills/attribution-standard/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: attribution-standard
+description: "Apply the canonical four-layer Apache-2.0 attribution model (NOTICE, per-file SPDX, REUSE.toml, canary markers) to a repo. Triggers on 'stamp attribution', 'add NOTICE', 'license headers', 'attribution layers', a newly public repo, or a repo with .git but no NOTICE / no REUSE.toml / no CONTRIBUTING.md. Build-loop Phase 1 Assess can advise running this when shipped source files lack SPDX headers."
+user-invocable: false
+---
+
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Attribution Standard
+
+Four overlapping mechanisms make stripping attribution either illegal, mechanically tedious, or detectable. Each survives a different removal pattern. The research backing this skill is at `~/dev/research/apache-2.0-attribution-watermarking-2026-05-22.md`.
+
+## The four layers
+
+| Layer | Survives | Legally binding? | Effort |
+|---|---|---|---|
+| 1. NOTICE file | Wholesale repo lift | **Yes** (Apache 2.0 §4(d)) | one-off |
+| 2. Per-file SPDX headers (`SPDX-FileCopyrightText` + `SPDX-License-Identifier`) | Per-file copy-paste | **Yes** (Apache 2.0 §4(c)) | scripted |
+| 3. REUSE.toml | Files that cannot carry a comment (JSON, binaries) | Reinforces #2 | scripted |
+| 4. Canary markers | Naive copy-paste; detectable via GitHub code search | No | low |
+
+## Canonical strings
+
+Apply identically wherever they appear. Memorise these — do not paraphrase.
+
+| Field | Value |
+|---|---|
+| Copyright holder | `Tyrone Ross, Jr` |
+| SPDX email tail | `<46267523+tyroneross@users.noreply.github.com>` |
+| Year range | `2025-2026` |
+| Full SPDX header value | `2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com>` |
+| NOTICE AI mention | "Portions of this software were developed with the assistance of Anthropic's Claude (via Claude Code) and OpenAI's Codex (via Codex CLI); AI-pair-programming contributions are attributed via Co-Authored-By trailers in the git history." |
+| Claude co-author trailer | `Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>` (substitute actual model + tier) |
+| Codex co-author trailer | `Co-Authored-By: OpenAI Codex <noreply@openai.com>` |
+
+## Language → comment-style table
+
+The `attribution_stamp.py` script applies the right comment syntax automatically based on extension.
+
+| Extension | Style | Header form |
+|---|---|---|
+| `.py`, `.sh`, `.bash`, `.zsh`, `.rb`, `.toml`, `.yml`, `.yaml` | `hash` | `# SPDX-FileCopyrightText: ...` (after shebang if present) |
+| `.ts`, `.tsx`, `.js`, `.jsx`, `.mjs`, `.cjs`, `.css`, `.scss`, `.go`, `.rs`, `.swift`, `.java`, `.kt` | `slash` | `// SPDX-FileCopyrightText: ...` |
+| `.md`, `.mdx`, `.html` | `html_comment` | `<!-- SPDX-FileCopyrightText: ... \| SPDX-License-Identifier: Apache-2.0 -->` (after YAML frontmatter if present) |
+| `.json` and binary assets | n/a | covered by `REUSE.toml` |
+
+## Target paths
+
+Default shipped-source roots: `src scripts hooks skills agents commands references`. Override via `--paths`.
+
+Default excluded path components: `node_modules dist build .git .venv venv archive tests/fixtures docs/test-fixtures __pycache__ .pytest_cache .mypy_cache .ruff_cache`. Extend via `--excludes`.
+
+For Python-heavy repos with no `src/` directory (like agent-rally-point), pass the actual package path: `--paths agent_rally_point` or whatever directory holds the .py files.
+
+## How to apply (the script)
+
+```bash
+python scripts/attribution_stamp.py \
+  --repo <path-to-repo> \
+  --name "Tyrone Ross, Jr" \
+  --email "46267523+tyroneross@users.noreply.github.com" \
+  --years 2025-2026 \
+  --canary-files <path1> <path2> \
+  [--paths <override-paths...>] \
+  [--restamp]
+```
+
+The script is **idempotent**:
+
+- Re-running with the same args is a no-op when canonical strings already match.
+- `--restamp` REPLACES existing SPDX header lines so a string change (e.g. adding `, Jr` or an email tail) can be rolled across the tree.
+- NOTICE is always rewritten from the canonical template (the canonical strings are the source of truth, not what's on disk).
+- LICENSE appendix and README "License & Attribution" section are added when missing; CONTRIBUTING.md is written unless already canonical.
+
+## Canary files — pick two
+
+Pick two central, stable files — one near the package entry point and one in the user-facing documentation. The canary marker is invisible to users but indexable by GitHub code search. Stable choices:
+
+- A package's `__init__.py` or main module
+- The orchestrator/coordinator skill or main markdown file
+- A central agent definition
+
+Avoid: test files, generated code, vendored libraries, files that frequently change shape.
+
+## Build-loop Phase 1 advisory wiring
+
+Build-loop's Phase 1 Assess fires an advisory (routes to the run report; **never** asks the user mid-run, per `feedback_advisory_checks_are_automated`) when a public repo (has a GitHub origin) is missing any of:
+
+- `NOTICE`
+- `REUSE.toml`
+- `CONTRIBUTING.md`
+- SPDX headers on at least 80% of shipped source files
+
+The advisory line is exactly: `Repo is missing standard attribution layers — run \`python scripts/attribution_stamp.py --repo <path>\``. When the build scope is ≥ S and the advisory fires, Phase 2 Plan queues an automatic chunk to run the stamper. Hard-blocking is out of scope — this is advisory, not a gate.
+
+## Verification
+
+After stamping, verify:
+
+```bash
+# Canonical name present in shipped source
+grep -rln 'Tyrone Ross, Jr' src scripts skills agents commands references | wc -l
+
+# No bare 'Tyrone Ross' (without ', Jr') in stamped files
+grep -rln 'SPDX-FileCopyrightText:.*Tyrone Ross$' src scripts skills agents commands references | wc -l   # expect 0
+
+# No SPDX line without the email tail
+grep -rL 'noreply.github.com' \
+  $(grep -rl 'SPDX-FileCopyrightText: 2025-2026 Tyrone Ross' src scripts skills agents commands references) \
+  | wc -l   # expect 0
+
+# REUSE compliance
+uvx reuse lint
+```
+
+NOTICE must mention both Claude (via Claude Code) and OpenAI Codex (via Codex CLI).
+
+## When NOT to use this skill
+
+- Repos that aren't Apache 2.0 (the SPDX line hardcodes it; for other SPDX IDs, modify the script or invoke per-language manually).
+- Repos that don't ship source (pure design assets, datasets, etc.).
+- Forks of someone else's project — Apache 2.0 §4(c) requires you to PRESERVE the upstream copyright, not replace it. The script's `--restamp` flag is dangerous here.

package/skills/authentication/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: authentication
+description: Use when wiring auth to a new project, debugging login errors (redirect_uri_mismatch, invalid_grant, session callback, refresh_token), or adding social/magic link flows. Covers Better Auth (Drizzle/Neon), Supabase Auth (SSR), Google OAuth, and Resend transactional email.
+user-invocable: false
+---
+
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Authentication
+
+Reference library for wiring external authentication and authorization into a web or mobile app. Each service has its own reference file — load the one you need, don't pre-load all.
+
+**Stack default for new Next.js work**: Neon + Better Auth + Drizzle. Supabase is covered for legacy projects and as an alternate. Magic-link delivery and transactional email default to Resend.
+
+## When to use this skill
+
+- Setting up third-party sign-in (Google, Apple, magic-link, etc.) on a Better Auth or Supabase backend
+- Wiring API keys / service accounts / OAuth callbacks
+- Debugging `redirect_uri_mismatch`, `invalid_grant`, token refresh loops, session callback failures
+- Sending magic-link / OTP emails and handling delivery webhooks
+- SSR cookie handling and the Supabase `getAll`/`setAll` ≥0.3 breaking change
+- Migrating away from legacy auth SDKs (e.g., `gapi.auth2`, `@supabase/ssr` <0.3)
+
+## Routing table
+
+| If the user is asking about... | Load | Context7 lib id |
+|---|---|---|
+| Better Auth setup, Drizzle adapter, social providers, refresh_token | `references/better-auth-setup.md` | `/better-auth/better-auth` |
+| Magic links / OTP via Better Auth | `references/better-auth-magic-link.md` | `/better-auth/better-auth` |
+| Example Web App Better Auth real-build lessons | `references/lessons-example-web-app-better-auth.md` | — |
+| Supabase Auth (SSR cookies, RLS, env validation, when-to-use vs Better Auth) | `references/supabase-auth.md` | `/supabase/supabase` |
+| Resend transactional + Better Auth `sendVerificationEmail` integration + webhook signatures | `references/resend-email.md` | `/websites/resend` |
+| Resend OTP / magic-link delivery + retries + bounce handling | `references/resend-otp-magic-link.md` | `/websites/resend`, `/resend/resend-skills` |
+| Google OAuth sign-in | `references/google-oauth-setup.md` + `references/google-cloud-console.md` | — |
+| Google Maps in a UI | `references/google-maps.md` | — |
+| Google Places API (New) | `references/google-places.md` | — |
+| Google Geocoding / Directions | `references/google-geocoding-directions.md` | — |
+| Google Calendar sync | `references/google-calendar-sync.md` | — |
+| Broad Google Cloud Console walkthrough (4-layer mental model: identity, APIs, credentials, quotas) | `references/google-cloud-console.md` | — |
+| Real Google build incident lessons (Example Web App, Next.js + Supabase) | `references/google-lessons-example-web-app.md` | — |
+
+Services not yet documented (planned as additional references): GitHub OAuth, generic OAuth 2.0 callbacks, service-account key handling, API key rotation. Add them as `references/<service>-<topic>.md` following the same pattern.
+
+## Universal auth footguns (applies to any service)
+
+1. **Redirect URIs are exact-match.** `https://app.com/cb` ≠ `https://app.com/cb/` ≠ `http://app.com/cb`. Register every variant you use in dev and prod.
+2. **Don't store tokens in localStorage for SPAs that redirect.** Use httpOnly cookies or the platform's session store.
+3. **Token refresh fails silently when the refresh token is expired/rotated.** Log refresh failures explicitly; don't swallow them.
+4. **Scopes are sticky across authorizations.** If you add a scope later, existing users need to re-consent — the original grant doesn't auto-upgrade.
+5. **"Invalid grant" usually means one of: clock skew, expired refresh token, revoked authorization, or JWT signature mismatch.** Check system clock first.
+6. **Service accounts ≠ user accounts.** Service accounts act on their own identity with their own quota. User-delegated access (domain-wide delegation) is a separate flow with separate risks.
+7. **`NEXT_PUBLIC_APP_URL` / `BETTER_AUTH_URL` mismatch on Vercel CNAMEs.** Preview/production URLs diverge from the registered redirect; bind detection to the actual `VERCEL_URL` fallback and verify at boot. Example Web App shipped a production-only auth failure from this exact mismatch.
+8. **Refresh-token guarantee on Google.** Better Auth's Google provider must explicitly request `accessType: 'offline'` AND `prompt: 'select_account consent'` — otherwise `refresh_token` is missing on second consent. Verify the `account.refresh_token` and `account.expires_at` columns populate before shipping. (See `references/better-auth-setup.md`.)
+9. **IDOR via shared DB connection.** Per-request `dbForUser(userId)` wrappers (or RLS) — never trust client-supplied user IDs in queries. Example Web App's `lib/db/index.ts` is the canonical pattern.
+10. **Magic-link expiry & idempotency.** Default 10 min; single-use; rate-limit by email; log delivery failures (Resend bounces ≠ user error). example-app's `magicLink({ expiresIn: 60 * 10 })` is the reference config.
+11. **Cookie config is non-negotiable.** `httpOnly: true`, `secure: true` (prod), `sameSite: 'lax'` for OAuth redirects. `sameSite: 'strict'` breaks Google callback. Better Auth defaults are correct; override with care.
+
+## Pattern: adding a new auth reference
+
+When expanding this skill:
+1. Add `references/<service>-<topic>.md` with a clear `## When to use` section at top.
+2. Add a row to the routing table above.
+3. If the service has a shared footgun class (e.g., OAuth redirect URIs), cross-link to the universal footguns section instead of repeating.
+4. Do **not** promote a single-service reference to a top-level skill unless it grows past ~500 lines *and* has multiple distinct sub-topics. Single services belong as references.
+
+## Looking up current API surface
+
+Auth SDKs change frequently — Better Auth in particular adds plugins and provider options on a fast cadence. Before writing config or debugging a session callback, fetch live docs via the Context7 MCP (mirrors the pattern in `building-with-deepagents/SKILL.md:33`):
+
+1. **Resolve** the library id once per session:
+   `mcp__plugin_context7_context7__resolve-library-id("better-auth")` → `/better-auth/better-auth`
+2. **Query** with the resolved id and a focused topic:
+   `mcp__plugin_context7_context7__query-docs` with `library: "/better-auth/better-auth"` and `topic: "magic link plugin config"` (or `"social provider refresh_token"`, `"SSR getAll setAll"`, `"webhook signature verification"`).
+
+Known Context7 ids (verified 2026-05-02): `/better-auth/better-auth`, `/supabase/supabase`, `/websites/resend`, `/resend/resend-skills`. If a query returns thin results, retry with the alternate (`/resend/resend-skills` is better tuned for agent-flavored questions; `/websites/resend` covers the broader SDK surface).
+
+## History
+
+Originally imported from a standalone `google-cloud-console` skill (2025, Example Web App build). Converted to a general `authentication` parent skill on 2026-04-21 so GitHub OAuth, generic OAuth 2.0, and API-key patterns can share the routing layer and universal footgun section without each becoming its own island.
+
+Extended on 2026-05-02 to multi-provider coverage: added Better Auth (Drizzle/Neon, magic-link, Google + Apple social), Supabase Auth (legacy + alternate), and Resend (transactional, magic-link/OTP, webhook verification). Lessons harvested from Example Web App, example-app, Example App, and example-app. Adopted the Context7 lookup pattern so SKILL.md stays light while doc depth lives in references and the live Context7 index.

package/skills/authentication/references/better-auth-magic-link.md

@@ -0,0 +1,135 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Better Auth — Magic Link / OTP
+
+## When to use
+
+- Email-only auth (no password, no social) — example-app and Example App both use this
+- Adding magic-link as an alternative sign-in method on top of social providers
+- OTP / verification-code flows (uses the same plugin with a different delivery template)
+
+For the broader Better Auth setup (database, providers, routes), start at `better-auth-setup.md`.
+For Resend wiring on the email delivery side, see `resend-email.md` (transactional) or `resend-otp-magic-link.md` (delivery + retry patterns).
+
+## Server config (example-app pattern)
+
+```ts
+// lib/auth.ts
+import { betterAuth } from 'better-auth'
+import { prismaAdapter } from 'better-auth/adapters/prisma'
+import { magicLink } from 'better-auth/plugins'
+import { prisma } from '@/lib/prisma'
+import { sendMagicLinkEmail } from '@/lib/email/send-magic-link'
+
+export const auth = betterAuth({
+  database: prismaAdapter(prisma, { provider: 'postgresql' }),
+  baseURL: process.env.BETTER_AUTH_URL || 'http://localhost:3150',
+  secret: process.env.BETTER_AUTH_SECRET,
+  emailAndPassword: { enabled: false },
+  plugins: [
+    magicLink({
+      // 10-minute expiry. Single-use is the plugin default — do not weaken.
+      expiresIn: 60 * 10,
+      sendMagicLink: async ({ email, url }) => {
+        await sendMagicLinkEmail({ email, url })
+      },
+    }),
+  ],
+})
+```
+
+For Drizzle, swap `prismaAdapter(prisma, { provider: 'postgresql' })` with `drizzleAdapter(db, { provider: 'pg' })` (Example Web App / Example App use Drizzle).
+
+## Client (with magic-link plugin)
+
+```ts
+// lib/auth-client.ts
+'use client'
+import { createAuthClient } from 'better-auth/react'
+import { magicLinkClient } from 'better-auth/client/plugins'
+
+export const authClient = createAuthClient({
+  baseURL: process.env.NEXT_PUBLIC_BETTER_AUTH_URL || 'http://localhost:3150',
+  plugins: [magicLinkClient()],
+})
+
+export const { signIn, signOut, useSession } = authClient
+
+// Usage:
+// await authClient.signIn.magicLink({ email, callbackURL: '/dashboard' })
+```
+
+## Email delivery handoff (dev-friendly, prod-strict)
+
+example-app's `lib/email/send-magic-link.ts` shows a useful pattern: log to console in dev, throw in prod, with the actual Resend block ready to uncomment.
+
+```ts
+interface SendMagicLinkParams { email: string; url: string }
+
+export async function sendMagicLinkEmail({ email, url }: SendMagicLinkParams): Promise<void> {
+  const hasEmailProvider = Boolean(process.env.RESEND_API_KEY)
+
+  if (!hasEmailProvider) {
+    if (process.env.NODE_ENV === 'production') {
+      throw new Error(
+        '[auth] sendMagicLinkEmail: no email provider configured. ' +
+          'Set RESEND_API_KEY or wire up a different provider.'
+      )
+    }
+    // Dev mode: print the link to the terminal so you can click it directly.
+    console.log('\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━')
+    console.log('  📧 MAGIC LINK (dev mode — email not sent)')
+    console.log(`  To:   ${email}`)
+    console.log(`  Link: ${url}`)
+    console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n')
+    return
+  }
+
+  const { Resend } = await import('resend')
+  const resend = new Resend(process.env.RESEND_API_KEY)
+
+  const { error } = await resend.emails.send({
+    from: process.env.AUTH_EMAIL_FROM || 'YourApp <noreply@example.com>',
+    to: email,
+    subject: 'Sign in to YourApp',
+    html: `
+      <div style="font-family: -apple-system, system-ui, sans-serif; max-width: 480px; margin: 0 auto;">
+        <h1 style="font-size: 20px; color: #111;">Sign in to YourApp</h1>
+        <p style="color: #555; line-height: 1.5;">Click the button below to sign in. This link expires in 10 minutes.</p>
+        <a href="${url}" style="display: inline-block; padding: 12px 20px; background: #111; color: #fff; text-decoration: none; border-radius: 6px; font-weight: 500;">Sign in</a>
+        <p style="color: #888; font-size: 12px; margin-top: 24px;">If you didn't request this, you can safely ignore this email.</p>
+      </div>
+    `,
+  })
+
+  if (error) throw new Error(`[auth] Resend send failed: ${error.message}`)
+}
+```
+
+Key behaviors:
+- **Dev never blocks on missing API key** — link goes to terminal
+- **Prod hard-fails** when key is absent (no silent skip)
+- **Dynamic import** of `resend` keeps it out of the cold-start bundle if unused
+
+## Footguns specific to magic-link
+
+1. **Don't lengthen `expiresIn`.** 10 minutes is the right default. Longer windows widen the attack surface for email-account compromise.
+2. **Rate-limit by email.** A loop submitting `/sign-in/magic-link` for `victim@x.com` is an email-flood vector. Use a per-email rate limiter (Upstash, Vercel KV, or a simple in-memory LRU for low traffic).
+3. **Log delivery failures, not delivery successes.** Bouncebacks from Resend (`email.bounced`) are NOT the user's fault — log them and surface to ops, not to the user.
+4. **Single-use is built-in.** Don't extend `magicLink({ ... })` to allow re-use; that defeats the security model.
+5. **Idempotent click handlers.** If a user double-clicks the magic-link, the second hit should land them in their session, not 401. Better Auth's default does this; verify if you customize.
+
+## Verification
+
+1. Trigger a magic-link send. Confirm the magicLink record in `verification` (Better Auth) / equivalent table.
+2. Click the link. Confirm session created, link record marked consumed.
+3. Click the same link again — should fail with `INVALID_TOKEN` or redirect to a "link already used" state.
+4. Wait 11 minutes, retry — should fail with `EXPIRED_TOKEN`.
+5. In prod with `RESEND_API_KEY` unset, sign-in should hard-fail with the error message above (not silently succeed).
+
+## Cross-references
+
+- Universal footgun #10 (magic-link expiry & idempotency) in `../SKILL.md`
+- `resend-email.md` for transactional + webhook integration
+- `resend-otp-magic-link.md` for delivery patterns
+- For OTP (numeric code) instead of clickable link, query Context7: `library: "/better-auth/better-auth"`, `topic: "OTP plugin"` — same plugin, different delivery template.

package/skills/authentication/references/better-auth-setup.md

@@ -0,0 +1,224 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Better Auth — Setup
+
+## When to use
+
+- New Next.js project on Neon + Drizzle (the documented stack default)
+- Adding social providers (Google, Apple) to an existing Better Auth instance
+- Wiring an iOS/mobile client via the Bearer plugin
+- Verifying that Google sign-in produces a usable `refresh_token`
+- Migrating away from `@supabase/ssr` (Example Web App did this — see `lessons-example-web-app-better-auth.md`)
+
+For magic-link / OTP setup, see `better-auth-magic-link.md`.
+For runtime API doc lookups, use `mcp__plugin_context7_context7__query-docs` with library `/better-auth/better-auth`.
+
+## Server instance (Drizzle + Neon + Google + Apple)
+
+Pattern from `Example Web App/lib/auth.ts` (production-grade, multi-platform). Adjust provider list to your needs.
+
+```ts
+// lib/auth.ts
+import { betterAuth } from 'better-auth'
+import { drizzleAdapter } from 'better-auth/adapters/drizzle'
+import { bearer } from 'better-auth/plugins'
+import { db } from '@/lib/db'
+
+const TRUSTED_ORIGINS = [
+  process.env.BETTER_AUTH_URL ?? 'http://localhost:3000',
+  'http://localhost:3000',
+  // Add native URL schemes here for mobile callbacks, e.g.:
+  // 'travelplanner://auth-callback',
+]
+
+export const auth = betterAuth({
+  database: drizzleAdapter(db, { provider: 'pg' }),
+  secret: process.env.BETTER_AUTH_SECRET!,
+  baseURL: process.env.BETTER_AUTH_URL ?? 'http://localhost:3000',
+  trustedOrigins: TRUSTED_ORIGINS,
+  socialProviders: {
+    google: {
+      clientId: process.env.GOOGLE_CLIENT_ID!,
+      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
+      // CRITICAL: both are required to guarantee refresh_token on every sign-in.
+      // See Universal footgun #8 in SKILL.md.
+      accessType: 'offline',
+      prompt: 'select_account consent',
+      scope: [
+        'openid',
+        'email',
+        'profile',
+        // Pre-approve any scopes you'll need later so the user doesn't hit a
+        // second consent screen mid-flow:
+        // 'https://www.googleapis.com/auth/calendar.app.created',
+      ],
+    },
+  },
+  plugins: [bearer()], // Bearer plugin only needed if you have a mobile/native client
+})
+
+export type Session = typeof auth.$Infer.Session
+```
+
+### Apple provider (conditional)
+
+For mobile apps with Apple Sign-In, register the provider only when `APPLE_CLIENT_ID` is present so unconfigured environments fall back gracefully:
+
+```ts
+const appleProvider = (() => {
+  const clientId = process.env.APPLE_CLIENT_ID
+  if (!clientId) return undefined
+  return {
+    clientId,
+    // For iOS native ID-token sign-in, clientSecret is OPTIONAL.
+    // For web OAuth code-exchange, clientSecret is REQUIRED (a JWT signed with
+    // your .p8 private key; max 6-month lifetime — pre-generate or sign at startup).
+    ...(process.env.APPLE_CLIENT_SECRET && { clientSecret: process.env.APPLE_CLIENT_SECRET }),
+    ...(process.env.APPLE_APP_BUNDLE_IDENTIFIER && {
+      appBundleIdentifier: process.env.APPLE_APP_BUNDLE_IDENTIFIER,
+    }),
+  }
+})()
+
+// then inside socialProviders:
+//   ...(appleProvider ? { apple: appleProvider } : {}),
+```
+
+## Catch-all route handler (Next.js App Router)
+
+```ts
+// app/api/auth/[...all]/route.ts
+import { auth } from '@/lib/auth'
+import { toNextJsHandler } from 'better-auth/next-js'
+
+export const { GET, POST } = toNextJsHandler(auth)
+```
+
+That single file replaces every Supabase callback / NextAuth route handler.
+
+## Client (React)
+
+Two patterns ship in the wild. Pick by need:
+
+**Minimal (Example Web App)** — uses `window.location.origin` by default, no `basePath` override:
+
+```ts
+// lib/auth-client.ts
+'use client'
+import { createAuthClient } from 'better-auth/react'
+
+export const authClient = createAuthClient({
+  baseURL: process.env.NEXT_PUBLIC_BETTER_AUTH_URL ?? '',
+})
+
+export const { signIn, signUp, signOut, useSession } = authClient
+```
+
+**Explicit basePath + `credentials: include` (Example App)** — needed when the client and API are on different origins, or when you've mounted the handler under a non-default path:
+
+```ts
+// client/src/lib/auth.ts
+import { createAuthClient } from 'better-auth/react'
+import { magicLinkClient } from 'better-auth/client/plugins'
+
+const authOrigin =
+  typeof window !== 'undefined'
+    ? window.location.origin
+    : 'http://localhost:3000'
+
+export const authClient = createAuthClient({
+  baseURL: authOrigin,
+  basePath: '/api/auth',
+  fetchOptions: {
+    credentials: 'include' as RequestCredentials,
+  },
+  plugins: [magicLinkClient()],
+})
+```
+
+## Feature flag with anonymous fallback (example-app pattern)
+
+When auth is being introduced incrementally and existing routes were written assuming an anonymous user, this gate keeps everything working until you flip `ENABLE_AUTH=true`:
+
+```ts
+// lib/auth.ts (continued)
+import { headers } from 'next/headers'
+
+export const ENABLE_AUTH = process.env.ENABLE_AUTH === 'true'
+
+export async function getUserIdFromSession(): Promise<string> {
+  if (!ENABLE_AUTH) return 'anonymous'
+  try {
+    const session = await auth.api.getSession({ headers: await headers() })
+    return session?.user?.id ?? 'anonymous'
+  } catch (error) {
+    console.warn('[auth] getUserIdFromSession failed, falling back to anonymous:', error)
+    return 'anonymous'
+  }
+}
+```
+
+Important: this is a transitional pattern. Remove it before declaring auth "shipped" — `anonymous` user IDs are not a real auth boundary.
+
+## IDOR guard — `dbForUser(userId)`
+
+Better Auth gives you a session, but it does NOT enforce per-row authorization. Every query must scope to the session's user id. Example Web App's `lib/db/index.ts` exports a `dbForUser(userId)` helper that returns CRUD methods pre-bound to that user:
+
+```ts
+// lib/db/index.ts (sketch)
+export function dbForUser(userId: string) {
+  return {
+    camps: {
+      list: () =>
+        db.select().from(schema.camps).where(eq(schema.camps.userId, userId)),
+      get: (id: string) =>
+        db
+          .select()
+          .from(schema.camps)
+          .where(and(eq(schema.camps.userId, userId), eq(schema.camps.id, id)))
+          .limit(1),
+      create: (input: Omit<typeof schema.camps.$inferInsert, 'userId'>) =>
+        db.insert(schema.camps).values({ ...input, userId }).returning(),
+      // update / remove follow the same and(eq(userId), eq(id)) pattern
+    },
+    // ... one block per table
+  }
+}
+```
+
+Call sites read like `dbForUser(session.user.id).camps.list()` — there's no way to forget the user filter, and a code review can grep for `from(schema.X)` outside `dbForUser` to spot violations.
+
+## Verification checklist (before declaring auth shipped)
+
+1. Sign in via Google. Confirm in DB:
+   - `user.id` is set
+   - `account.refresh_token` is non-null
+   - `account.access_token` is set with a future `expires_at`
+2. Sign out, sign back in. Confirm `refresh_token` is still set (not cleared by re-consent).
+3. Wait past the access-token expiry. Confirm the next API call refreshes silently (Better Auth handles this if `accessType: 'offline'` is set).
+4. Verify cookies are `httpOnly`, `secure` (prod), `sameSite: 'lax'`. (See Universal footgun #11.)
+5. In production, confirm `BETTER_AUTH_URL` matches the actual Vercel URL — boot-time validation recommended (Universal footgun #7).
+6. Hit a protected API route from a logged-out browser; confirm 401, not anonymous fallback (unless `ENABLE_AUTH=false` is intentional).
+
+## Required env vars
+
+```env
+BETTER_AUTH_SECRET=<32-byte random string>
+BETTER_AUTH_URL=https://your-app.com   # MUST match production URL exactly
+NEXT_PUBLIC_BETTER_AUTH_URL=https://your-app.com   # client uses this
+GOOGLE_CLIENT_ID=...
+GOOGLE_CLIENT_SECRET=...
+# Optional Apple:
+APPLE_CLIENT_ID=...
+APPLE_CLIENT_SECRET=...   # web flow only; iOS native skips
+APPLE_APP_BUNDLE_IDENTIFIER=com.example.app
+```
+
+For Drizzle schema, see Better Auth docs: `mcp__plugin_context7_context7__query-docs` with `library: "/better-auth/better-auth"` and `topic: "drizzle schema"`.
+
+## Cross-references
+
+- Universal footguns #7 (Vercel URL mismatch), #8 (refresh_token guarantee), #9 (IDOR guard), #11 (cookie config) in `../SKILL.md`
+- `lessons-example-web-app-better-auth.md` — incident-style narrative of these issues hitting production
+- `better-auth-magic-link.md` — magic-link plugin setup
+- `resend-email.md` — wiring `sendVerificationEmail` to Resend