@withmata/blueprints 0.2.0

package/blueprints/features/auth-better-auth/BLUEPRINT.md

@@ -0,0 +1,794 @@
+# Auth Blueprint — Better Auth + Drizzle
+
+## Problem
+
+Full authentication and authorization for a TypeScript monorepo: multi-provider social login, email/password with verification, password reset, organization-based multi-tenancy with role-based permissions (owner/admin/member), invitation system, and session management with cookie-based route protection.
+
+## Status
+
+Complete.
+
+## Blueprint Dependencies
+
+| Blueprint | Type | Why |
+|-----------|------|-----|
+| `features/db-drizzle-postgres` | required | Auth creates schema files inside the database layer following the schema-group pattern (per-group drizzle.config.ts, barrel exports, explicit schema lists). Without it, auth must create a minimal db structure that lacks the full patterns. |
+| `foundation/monorepo-turbo` | recommended | Provides monorepo workspace structure (packages/, apis/, turbo tasks, pnpm workspaces). Works without it — adapts to single-repo projects automatically. |
+
+### If `db-drizzle-postgres` is not installed
+
+The scaffold command should ask: "Auth requires a database package. Do you want to install the db-drizzle-postgres blueprint first? (Y/n)"
+
+If the user accepts, run `/scaffold-db` first, then continue with auth. If the user declines, auth creates a minimal database structure with only the auth schema group — but warns that it will lack seed scripts, example entities, and the full schema-group conventions.
+
+If the database directory already exists (from manual setup or another tool), auth proceeds normally — it detects and merges into the existing structure.
+
+---
+
+## Architecture
+
+### Core Pattern
+
+Better Auth handles all auth logic (sign-in, sign-up, OAuth callbacks, session management, password reset, email verification) through a single handler mounted at `/api/auth/*`. The server validates sessions via `auth.api.getSession({ headers })`. The client uses `createAuthClient()` from `better-auth/react` for all auth operations.
+
+### Key Decisions
+
+- **Separate auth database** (recommended) — Auth tables live in their own PostgreSQL database, isolated from application data. Independent migrations, clean separation. Can use a shared database if preferred.
+
+- **Organization plugin** (optional) — Multi-tenant workspaces with invitations, roles (owner > admin > member), and per-org context. Omit for simpler single-tenant apps. See "Removing the Organization Plugin" below.
+
+- **Server-side session with cookie cache** — Sessions stored in DB, validated server-side. A 5-minute cookie cache avoids a DB round-trip on every request. 30-day session expiry, 24-hour refresh interval.
+
+- **Client context split** — Organization state is split into separate data and actions React contexts. Components consuming only actions don't re-render when data changes.
+
+- **SWR mutation hooks** (recommended) — All auth mutations use `useSWRMutation`. Each flow has its own hook with typed error handling using discriminated error codes.
+
+- **Email via Resend** (recommended) — Verification emails, password reset, and org invitations use Resend. Swappable to any provider.
+
+---
+
+## Hard Requirements vs Recommended Defaults
+
+**Hard requirements:**
+- Better Auth as the auth library
+- Drizzle ORM as the database adapter
+
+**Recommended defaults** — ask the user during scaffolding:
+
+| Choice | Recommended | Alternatives |
+|---|---|---|
+| Database | PostgreSQL | MySQL, SQLite |
+| Auth DB isolation | Separate database | Shared with app DB |
+| Env validation | t3-env + Zod | raw process.env, other validators |
+| Form validation | Zod | Valibot, Yup, ArkType |
+| Data fetching hooks | SWR (`useSWRMutation`) | TanStack Query, raw fetch |
+| Email provider | Resend | SendGrid, Postmark, AWS SES |
+| Server framework | Hono (standalone) | Next.js API routes, Express, Fastify |
+
+> **Note:** t3-env and Zod are project-wide preferences, not auth-specific. They may be extracted into their own blueprints in the future.
+
+---
+
+## Dependencies
+
+### npm packages
+
+**Server (both modes):**
+| Package | Version | Purpose |
+|---|---|---|
+| `better-auth` | ^1.4.6 | Auth library |
+| `drizzle-orm` | ^0.45.1 | Database ORM |
+| `pg` | ^8.18.0 | PostgreSQL driver |
+| `@t3-oss/env-core` | ^0.13.8 | Env validation (Hono mode) |
+| `zod` | ^4.x | Schema validation |
+| `resend` | ^6.x | Email sending (optional) |
+| `dotenv` | ^16.x | Env file loading |
+
+**Server (Hono mode only):**
+| Package | Version | Purpose |
+|---|---|---|
+| `hono` | ^4.9.x | HTTP framework |
+| `@hono/node-server` | ^1.19.x | Node.js adapter |
+
+**Client (Next.js frontend):**
+| Package | Version | Purpose |
+|---|---|---|
+| `better-auth` | ^1.4.6 | Auth client |
+| `swr` | ^2.x | Data fetching + mutations |
+| `react-hook-form` | ^7.x | Form management |
+| `@hookform/resolvers` | ^5.x | Zod resolver for forms |
+| `zod` | ^4.x | Form validation |
+| `@t3-oss/env-nextjs` | ^0.13.x | Env validation (Next.js) |
+
+**DB package (dev):**
+| Package | Version | Purpose |
+|---|---|---|
+| `drizzle-kit` | ^0.31.x | Migration generation + execution |
+
+### Environment Variables
+
+| Variable | Where | Description |
+|---|---|---|
+| `AUTH_DATABASE_URL` | Server + DB | PostgreSQL connection URL for auth database |
+| `BETTER_AUTH_URL` | Server | Base URL where auth API is accessible (for OAuth callbacks) |
+| `BETTER_AUTH_SECRET` | Server | Secret for signing sessions/tokens. Generate: `openssl rand -base64 32` |
+| `GOOGLE_CLIENT_ID` | Server | Google OAuth client ID |
+| `GOOGLE_CLIENT_SECRET` | Server | Google OAuth client secret. Redirect URI: `{BETTER_AUTH_URL}/api/auth/callback/google` |
+| `RESEND_API_KEY` | Server | Resend API key for transactional emails |
+| `FRONTEND_DOMAIN` | Server | Frontend URL for CORS, trusted origins, email links |
+| `PORT` | Server (Hono) | Port for standalone server |
+| `NEXT_PUBLIC_API_URL` | Client | Backend API URL |
+| `NEXT_PUBLIC_FRONTEND_URL` | Client | Frontend's own URL |
+
+---
+
+## Monorepo Wiring
+
+This section documents how auth integrates across a Turborepo monorepo — the part hardest to figure out from scratch.
+
+### DB Package (`packages/db/`)
+
+**`package.json` exports:**
+```json
+{
+  "exports": {
+    "./auth": {
+      "import": "./dist/auth/schema.js",
+      "types": "./dist/auth/schema.d.ts"
+    }
+  }
+}
+```
+
+**Scripts:**
+```json
+{
+  "auth:generate": "drizzle-kit generate --config ./drizzle/auth/drizzle.config.ts",
+  "auth:migrate": "drizzle-kit generate --config ./drizzle/auth/drizzle.config.ts && drizzle-kit migrate --config ./drizzle/auth/drizzle.config.ts",
+  "drizzle:studio:auth": "drizzle-kit studio --config ./drizzle/auth/drizzle.config.ts"
+}
+```
+
+**Dependencies:** `drizzle-orm`, `dotenv` | **Dev:** `drizzle-kit`, `pg`
+
+**File structure:**
+```
+packages/db/
+├── src/auth/schema.ts          # Auto-generated by Better Auth CLI
+├── drizzle/auth/
+│   ├── drizzle.config.ts       # Drizzle Kit config
+│   └── *.sql                   # Generated migrations
+└── .env                        # AUTH_DATABASE_URL
+```
+
+### Server Package (e.g. `apis/server/`)
+
+**Key script:**
+```json
+{
+  "auth:generate": "npx @better-auth/cli@latest generate --config ./src/auth/index.ts --output ../../packages/db/src/auth/schema.ts --yes"
+}
+```
+
+This reads your `betterAuth()` config and auto-generates the Drizzle schema in the DB package.
+
+**Dependencies:** `better-auth`, `drizzle-orm`, `pg`, `@t3-oss/env-core`, `zod`, `resend`
+**Workspace dep:** `{{SCOPE}}/db` (for importing `{{SCOPE}}/db/auth`)
+
+### Web App (`apps/web/`)
+
+**Import alias** (in `package.json`):
+```json
+{
+  "imports": {
+    "#auth/*": "./auth/*"
+  }
+}
+```
+
+This enables clean imports: `import { authClient } from "#auth/client"`.
+
+**`next.config.ts` — API proxy rewrites (for standalone server mode):**
+```typescript
+async rewrites() {
+  const apiUrl = process.env.NEXT_PUBLIC_API_URL;
+  if (!apiUrl || apiUrl.includes("localhost")) return [];
+  return [{ source: "/api/:path*", destination: `${apiUrl}/api/:path*` }];
+}
+```
+
+In production, this proxies `/api/*` through the frontend domain so cookies work across frontend/backend on the same domain.
+
+### Root `package.json`
+
+```json
+{
+  "scripts": {
+    "auth:generate": "turbo run auth:generate --filter={{SCOPE}}/server --no-cache",
+    "auth:migrate": "turbo run auth:migrate --filter={{SCOPE}}/db --no-cache",
+    "auth:setup": "pnpm run auth:generate && pnpm run auth:migrate"
+  }
+}
+```
+
+### `turbo.json`
+
+```json
+{
+  "tasks": {
+    "auth:generate": { "cache": false },
+    "auth:migrate": { "cache": false }
+  }
+}
+```
+
+### `pnpm-workspace.yaml`
+
+Ensure `apis/*` is included (for standalone server mode):
+```yaml
+packages:
+  - "apps/*"
+  - "apis/*"
+  - "packages/*"
+  - "config/*"
+```
+
+---
+
+## Single-Repo Adaptation
+
+For standalone applications (Next.js, Node, Bun) without a monorepo, auth integrates directly into the app. The core auth patterns are identical — only file placement and wiring differ.
+
+### Path Mapping
+
+| Aspect | Monorepo | Single-Repo |
+|--------|----------|-------------|
+| Auth server config | `apis/server/src/auth/index.ts` | `src/lib/auth/index.ts` |
+| Auth DB connection | `apis/server/src/db/auth.ts` | `src/lib/db/auth.ts` |
+| Auth middleware | `apis/server/src/middleware/auth.ts` | `src/middleware/auth.ts` or Next.js middleware |
+| Auth handler | Hono at `apis/server/` | Next.js API route `app/api/auth/[...all]/route.ts` |
+| Client code | `apps/web/auth/` | `src/auth/` or `auth/` |
+| Import alias | `#auth/*` → `./auth/*` | `#auth/*` or `@/auth/*` |
+| DB schema | `packages/db/src/auth/schema.ts` | `src/db/auth/schema.ts` |
+| Drizzle config | `packages/db/drizzle/auth/drizzle.config.ts` | `drizzle/auth/drizzle.config.ts` |
+| Workspace deps | `"@scope/db": "workspace:*"` | N/A (direct imports) |
+| CORS config | Required (separate frontend/backend) | Not needed (same origin) |
+| API proxy rewrites | `next.config.ts` rewrites for Hono mode | Not needed with API routes |
+| Scripts | Turbo wrappers (`turbo run auth:generate --filter=...`) | Direct CLI calls in root `package.json` |
+
+### Single-Repo Server Framework
+
+Single-repo projects typically use **Next.js API routes** directly instead of a standalone Hono server. This simplifies the setup:
+
+- No CORS configuration needed (same origin)
+- No API proxy rewrites needed
+- No separate server package
+- Auth handler mounts at `app/api/auth/[...all]/route.ts`
+
+### Single-Repo Scripts
+
+```json
+{
+  "scripts": {
+    "auth:generate": "npx @better-auth/cli@latest generate --config ./src/lib/auth/index.ts --output ./src/db/auth/schema.ts --yes",
+    "auth:migrate": "drizzle-kit generate --config ./drizzle/auth/drizzle.config.ts && drizzle-kit migrate --config ./drizzle/auth/drizzle.config.ts",
+    "auth:setup": "pnpm auth:generate && pnpm auth:migrate"
+  }
+}
+```
+
+### What Stays the Same
+
+All core auth patterns are project-type-agnostic:
+- Better Auth library + configuration shape
+- Drizzle adapter pattern
+- Session management (cookie cache, expiry, refresh)
+- Organization plugin (if used)
+- Client-side auth hooks (SWR mutations)
+- Form schemas (Zod validation)
+- Route protection middleware logic (cookie check)
+- Auth flows (sign-in, sign-up, verify, forgot-password, reset, invite)
+- Email sending pattern
+
+---
+
+## Platform Integration
+
+Better Auth is framework-agnostic. Here's how to mount it on different platforms.
+
+### Hono (Recommended)
+
+```typescript
+import { Hono } from "hono";
+import { cors } from "hono/cors";
+import auth from "./auth/index.js";
+import { env } from "./env.js";
+
+const app = new Hono();
+
+// CORS for auth routes
+app.use("/api/auth/*", cors({
+  origin: [env.FRONTEND_DOMAIN],
+  allowHeaders: ["Content-Type", "Authorization"],
+  allowMethods: ["POST", "GET", "OPTIONS"],
+  exposeHeaders: ["Content-Length"],
+  maxAge: 600,
+  credentials: true,
+}));
+
+// Mount Better Auth handler
+app.on(["POST", "GET"], "/api/auth/*", (c) => {
+  return auth.handler(c.req.raw);
+});
+```
+
+### Next.js API Routes
+
+Create `app/api/auth/[...all]/route.ts`:
+```typescript
+import { toNextJsHandler } from "better-auth/next-js";
+import auth from "@/lib/auth";
+
+export const { POST, GET } = toNextJsHandler(auth);
+```
+
+See: https://www.better-auth.com/docs/integrations/next-js
+
+### Other Platforms
+
+- **Express:** https://www.better-auth.com/docs/integrations/express
+- **Fastify:** https://www.better-auth.com/docs/integrations/fastify
+- **SvelteKit:** https://www.better-auth.com/docs/integrations/svelte-kit
+- **Nuxt:** https://www.better-auth.com/docs/integrations/nuxt
+
+---
+
+## Auth Flows
+
+Each flow below documents the page pattern, user flow, form fields, API calls, and error handling. When scaffolding, generate fresh UI matching the target project's design system using these specifications.
+
+### Visual Layout Pattern
+
+Auth pages use a **split-screen layout**:
+- **Left side:** Form content (logo, heading, form fields, action buttons, navigation links)
+- **Right side:** Decorative illustration or branding image (hidden on mobile, visible on `lg:` breakpoint)
+- Max form width: `max-w-sm` on desktop
+- Pages wrap in `Suspense` with skeleton loading states (pulse-animated placeholder rectangles)
+
+### Shared UI Components
+
+These patterns appear across multiple auth pages:
+- **AuthCard** — centered card with: optional icon (in circular muted background), title, description, children, footer
+- **PasswordInput** — password field with show/hide toggle (eye/eye-slash icon), optional "Must be at least 8 characters" hint
+- **ContinueWith** — pill-shaped button with icon + text for social sign-in
+- **BackLink** — left-arrow link for navigation to previous page
+- **Loading skeletons** — animated pulse rectangles matching form field heights
+
+---
+
+### Flow 1: Auth Landing (`/auth`)
+
+**Purpose:** Entry point — choose sign-in method.
+
+**Layout:** Logo centered, heading, subtitle, two buttons with "or" divider, terms footer.
+
+**Elements:**
+1. App logo
+2. Heading: "Get started with {{APP_NAME}}"
+3. Subtitle: descriptive tagline
+4. "Continue with Google" button → calls `authClient.signIn.social({ provider: "google", callbackURL })`
+5. "or" divider
+6. "Continue with Email" link → navigates to `/auth/email`
+7. Terms of Service + Privacy Policy links
+
+**Behavior:**
+- If user is already authenticated and visits `/auth` (exact), redirect to `/`
+- Google button respects `returnUrl` search param for post-auth redirect
+
+---
+
+### Flow 2: Email Entry (`/auth/email`)
+
+**Purpose:** Enter email, then route to sign-in (existing account) or sign-up (new account).
+
+**Form fields:**
+| Field | Type | Validation |
+|---|---|---|
+| email | email | Required, valid email |
+
+**API call:** Server action that checks if email exists in auth database (timing-safe to prevent enumeration).
+
+**Behavior:**
+- On submit: check email → if exists, redirect to `/auth/signin?email=...` → if not, redirect to `/auth/signup?email=...`
+- Also shows "Continue with Google" as alternate option
+- Back link → `/auth`
+
+---
+
+### Flow 3: Sign In (`/auth/signin`)
+
+**Purpose:** Email/password authentication.
+
+**Form fields:**
+| Field | Type | Validation | Notes |
+|---|---|---|---|
+| email | email | Required, valid email | Pre-filled + read-only if passed via URL params |
+| password | password | Required | Show/hide toggle via PasswordInput |
+
+**API call:** `authClient.signIn.email({ email, password })`
+
+**Error handling:**
+| Error Code | Message | Action |
+|---|---|---|
+| `USER_NOT_FOUND` | "No account found with this email" | Shows "Create an account instead" link |
+| `INVALID_CREDENTIALS` | "No account found with this email" | — |
+| `EMAIL_NOT_VERIFIED` | "Please verify your email first" | Redirects to `/auth/verify-email?email=...` |
+| `UNKNOWN` | Original error message | — |
+
+**Success:** `router.push(returnUrl || "/")`
+
+**Links:** "Forgot password?" → `/auth/forgot-password`, "Don't have an account? Sign up" → `/auth/signup`
+
+---
+
+### Flow 4: Sign Up (`/auth/signup`)
+
+**Purpose:** Create new account with email/password.
+
+**Form fields:**
+| Field | Type | Validation | Notes |
+|---|---|---|---|
+| email | email | Required, valid email | Pre-filled if passed via URL |
+| name | text | Required, trimmed | Auto-focused if email pre-filled |
+| password | password | Required, min 8 chars | Shows "Must be at least 8 characters" hint |
+| confirmPassword | password | Must match password | — |
+
+**API call:** `authClient.signUp.email({ email, name, password })`
+
+**Error handling:**
+| Error Code | Message | Action |
+|---|---|---|
+| `EMAIL_EXISTS` | "An account with this email already exists" | Shows "Sign in instead" link |
+
+**Success:** Redirect to `/auth/verify-email?email=...`
+
+**Links:** "Already have an account? Sign in" → `/auth/signin`
+
+---
+
+### Flow 5: Email Verification (`/auth/verify-email`)
+
+**Two pages:**
+
+**5a. Check your email** (`/auth/verify-email?email=...`)
+- Uses **AuthCard** layout with envelope icon
+- Title: "Check your email"
+- Description: "We sent a verification link to {email}"
+- "Resend verification email" button with 60-second cooldown timer
+- "Wrong email? Start over" footer link → `/auth`
+- **API call (resend):** `authClient.sendVerificationEmail({ email })`
+
+**5b. Token verification** (`/auth/verify-email/[token]`)
+- Automatically verifies on load via `authClient.verifyEmail({ query: { token } })`
+- States: loading (spinner), success (checkmark + "Email verified" + sign-in link), expired (warning + "Request new link"), invalid (error + "Request new link")
+- Uses `useSWR` (not mutation) — runs once, no retry
+
+---
+
+### Flow 6: Forgot Password (`/auth/forgot-password`)
+
+**Form fields:**
+| Field | Type | Validation |
+|---|---|---|
+| email | email | Required, valid email |
+
+**API call:** `authClient.forgetPassword({ email, redirectTo: "/auth/reset-password" })`
+
+**Behavior:** Always redirects to `/auth/forgot-password/sent?email=...` regardless of whether email exists (prevents enumeration).
+
+**Sent page** (`/auth/forgot-password/sent`):
+- AuthCard with envelope icon
+- "Check your email" title
+- "We sent a password reset link to {email}"
+- "Didn't receive the email? Check your spam folder" hint
+- Back link → `/auth/signin`
+
+---
+
+### Flow 7: Reset Password (`/auth/reset-password/[token]`)
+
+**Form fields:**
+| Field | Type | Validation |
+|---|---|---|
+| password | password | Required, min 8 chars (with hint) |
+| confirmPassword | password | Must match password |
+
+**API call:** `authClient.resetPassword({ token, newPassword })`
+
+**Error handling:**
+| Error Code | Page State | Display |
+|---|---|---|
+| `EXPIRED` | AuthCard with warning icon | "Link expired" + "Request new link" button → `/auth/forgot-password` |
+| `INVALID` | AuthCard with error icon | "Invalid link" + "Request new link" button |
+
+**Success:** AuthCard with checkmark icon, "Password updated" + "Sign in with new password" link → `/auth/signin`
+
+---
+
+### Flow 8: Accept Invitation (`/auth/invite/[token]`)
+
+**Purpose:** Accept an organization invitation.
+
+**States (sequential):**
+1. **Loading** — spinner while checking session
+2. **Not authenticated** — Card with "You've Been Invited", "Sign in to Accept" button → redirects to `/auth?returnUrl=/auth/invite/{token}`
+3. **Loading invitation** — spinner while fetching invitation details
+4. **Expired** — "Invitation Expired" card with "Go to Dashboard" button
+5. **Error/Invalid** — "Invalid Invitation" card with error message
+6. **Accepted** — "Welcome!" card with checkmark, auto-redirects to `/`
+7. **Main view** — Shows org name, role, invitee email in a bordered card, "Accept Invitation" button
+
+**API calls:**
+- `authClient.useSession()` — check if logged in
+- `authClient.organization.getInvitation({ query: { id: token } })` — fetch invitation details
+- `authClient.organization.acceptInvitation({ invitationId: token })` — accept
+- `authClient.organization.setActive({ organizationId })` — switch to new org after accepting
+
+---
+
+### Flow 9: Onboarding — Create Organization (`/onboarding/create-organization`)
+
+**Purpose:** After sign-up, create first organization/workspace.
+
+**Guard:** `OnboardingRedirect` component checks `needsOnboarding` from org context. If user has zero orgs after loading, redirects here.
+
+**Form fields:**
+| Field | Type | Validation |
+|---|---|---|
+| name | text | Required, max 50 chars, trimmed |
+
+**API call:** Uses `useCreateOrganization()` hook → `authClient.organization.create()` + `setActive()`
+
+**Success:** `router.push("/")`
+
+---
+
+### Flow 10: Organization Switching
+
+**Location:** Sidebar header dropdown.
+
+**Elements:**
+- Current org name + logo displayed in sidebar header
+- Dropdown shows all user's organizations with checkmark on active
+- Click to switch: `authClient.organization.setActive({ organizationId })`
+- "Create Organization" option at bottom → opens dialog
+
+**Create Organization Dialog:**
+- Form with name field (same schema as onboarding)
+- Uses `useOrganizationActions().createOrganization()`
+
+---
+
+### Flow 11: Team Management (`/settings/members`)
+
+**Purpose:** View members, invite new ones, manage roles, remove members.
+
+**Page layout:**
+- Header: "Members" title + member count badge + "Invite" button (admin+ only, via `useHasPermission("admin")`)
+- Member list: sorted by role (owner → admin → member)
+- Pending invitations section below members
+
+**Member row:** Avatar/initials, name, email, role badge. Dropdown menu with "Change Role" and "Remove" actions (permission-gated).
+
+**Invitation row:** Email, role badge, "pending" status badge, expiry date, cancel button.
+
+**Dialogs:**
+- **InviteMemberDialog** — email + role select (Admin/Member), calls `inviteMember()`
+- **ChangeMemberRoleDialog** — role select, calls `updateMemberRole()`
+- **RemoveMemberDialog** — confirmation, calls `removeMember()`
+- **CancelInvitationDialog** — confirmation, calls `authClient.organization.cancelInvitation()`
+
+**API calls:** All via `useOrganizationActions()` hooks + `authClient.organization.getFullOrganization()` for member/invitation data.
+
+---
+
+## Route Protection
+
+### Client-Side (Next.js Middleware)
+
+Checks for `better-auth.session_token` or `__Secure-better-auth.session_token` cookie:
+- **Public routes** (`/auth/*`): accessible without auth. Authenticated users on `/auth` (exact) redirected to `/`
+- **Protected routes** (everything else): unauthenticated users redirected to `/auth?returnUrl=...`
+- **Onboarding routes** (`/onboarding/*`): accessible if authenticated
+- **Skipped**: `/_next/*`, `/api/*`, files with `.` in path
+
+### Server-Side (Auth Middleware)
+
+The framework-agnostic core:
+```typescript
+const sessionData = await auth.api.getSession({ headers: request.headers });
+```
+
+Two middleware levels:
+- `requireAuth()` — validates session, attaches `{ user, session }` to context
+- `requireOrganization()` — validates session + checks `session.activeOrganizationId`
+
+### Protected Layout Pattern
+
+```
+(protected)/layout.tsx
+  → OrganizationProvider (wraps with org context)
+    → OnboardingRedirect (checks needsOnboarding, redirects if no orgs)
+      → children
+```
+
+---
+
+## File Manifest
+
+| File | Purpose | Monorepo Target | Single-Repo Target |
+|---|---|---|---|
+| `files/server/auth.ts` | Better Auth config | `apis/server/src/auth/index.ts` | `src/lib/auth/index.ts` |
+| `files/server/auth-db.ts` | Drizzle DB connection for auth | `apis/server/src/db/auth.ts` | `src/lib/db/auth.ts` |
+| `files/server/middleware.ts` | Session validation middleware | `apis/server/src/middleware/auth.ts` | `src/middleware/auth.ts` |
+| `files/server/env.ts` | Auth env validation (t3-env) | `apis/server/src/env.ts` | `env.ts` (merge into existing) |
+| `files/client/auth-client.ts` | `createAuthClient()` setup | `apps/web/auth/client.ts` | `src/auth/client.ts` |
+| `files/client/context/organization.ts` | Organization context | `apps/web/auth/context/organization.ts` | `src/auth/context/organization.ts` |
+| `files/client/hooks/use-organization.ts` | Org consumption hooks | `apps/web/auth/hooks/use-organization.ts` | `src/auth/hooks/use-organization.ts` |
+| `files/client/hooks/use-has-permission.ts` | Role-based permission | `apps/web/auth/hooks/use-has-permission.ts` | `src/auth/hooks/use-has-permission.ts` |
+| `files/client/hooks/use-create-organization.ts` | SWR mutation for org | `apps/web/auth/hooks/use-create-organization.ts` | `src/auth/hooks/use-create-organization.ts` |
+| `files/client/schema/auth.ts` | Shared Zod schemas | `apps/web/auth/schema/auth.ts` | `src/auth/schema/auth.ts` |
+| `files/client/schema/organization.ts` | Org form schemas | `apps/web/auth/schema/organization.ts` | `src/auth/schema/organization.ts` |
+| `files/client/types/organization.ts` | Organization types | `apps/web/auth/types/organization.ts` | `src/auth/types/organization.ts` |
+| `files/db/auth-schema.ts` | Drizzle schema (auto-generated) | `packages/db/src/auth/schema.ts` | `src/db/auth/schema.ts` |
+| `files/db/drizzle.config.ts` | Drizzle Kit config for auth | `packages/db/drizzle/auth/drizzle.config.ts` | `drizzle/auth/drizzle.config.ts` |
+| `files/middleware/route-protection.ts` | Next.js route guard | `apps/web/middleware.ts` | `middleware.ts` |
+
+---
+
+## Integration Steps
+
+When scaffolding this blueprint into a new project, follow this order:
+
+### Phase 1: Database
+
+1. Create `packages/db/src/auth/` directory
+2. Copy `files/db/drizzle.config.ts` → `packages/db/drizzle/auth/drizzle.config.ts`
+3. Add `"./auth"` export to `packages/db/package.json`
+4. Add `auth:generate`, `auth:migrate`, `drizzle:studio:auth` scripts to `packages/db/package.json`
+5. Install deps: `drizzle-orm`, `dotenv` + dev: `drizzle-kit`, `pg`
+6. Set `AUTH_DATABASE_URL` in `packages/db/.env`
+
+### Phase 2: Server
+
+7. Adapt `files/server/auth.ts` — replace `{{APP_NAME}}`, `{{EMAIL_FROM}}`, configure providers/plugins
+8. Adapt `files/server/auth-db.ts` — set correct import path for DB package
+9. Adapt `files/server/env.ts` — merge auth vars into your server's env validation
+10. Mount auth handler on your server (see Platform Integration)
+11. Copy `files/server/middleware.ts` — adapt for your server framework if not Hono
+12. Set env vars: `BETTER_AUTH_URL`, `BETTER_AUTH_SECRET`, `FRONTEND_DOMAIN`, social provider credentials, `RESEND_API_KEY`
+13. Run `npx @better-auth/cli@latest generate` to produce the Drizzle schema
+14. Run `drizzle-kit generate && drizzle-kit migrate` to create database tables
+
+### Phase 3: Client
+
+15. Install deps: `better-auth`, `swr`, `react-hook-form`, `@hookform/resolvers`, `zod`
+16. Copy `files/client/auth-client.ts` → `apps/web/auth/client.ts`
+17. Add `"#auth/*": "./auth/*"` to `apps/web/package.json` imports
+18. Copy `files/client/context/`, `hooks/`, `schema/`, `types/` → `apps/web/auth/`
+19. Set env vars: `NEXT_PUBLIC_API_URL`, `NEXT_PUBLIC_FRONTEND_URL`
+
+### Phase 4: Route Protection
+
+20. Copy `files/middleware/route-protection.ts` → `apps/web/middleware.ts`
+21. Add API proxy rewrites to `next.config.ts` (for standalone server mode only)
+
+### Phase 5: UI
+
+22. Build auth pages following the Auth Flows documentation above
+23. Build protected layout with `OrganizationProvider` + `OnboardingRedirect`
+24. Build onboarding flow (create organization page)
+25. Build team management pages (if using org plugin)
+
+### Phase 6: Project Scripts (monorepo)
+
+> Skip this phase for single-repo projects — use Phase 6-alt instead.
+
+26. Add `auth:generate` script to server package (runs `@better-auth/cli generate`)
+27. Add `auth:generate`, `auth:migrate`, `auth:setup` to root `package.json` (Turbo wrappers)
+28. Add `auth:generate` and `auth:migrate` tasks to `turbo.json` (both `cache: false`)
+
+### Phase 6-alt: Project Scripts (single-repo)
+
+> Use this phase instead of Phase 6 for standalone applications.
+
+26. Add `auth:generate`, `auth:migrate`, `auth:setup` scripts to root `package.json` (direct CLI calls — see Single-Repo Scripts in the Single-Repo Adaptation section)
+27. Add auth dependencies to root `package.json`
+
+---
+
+## Maintenance Hooks
+
+Rules that should be added to the target project's CLAUDE.md during scaffolding. These ensure auth stays consistent after code changes.
+
+### Schema & Config Hooks
+
+| When you... | Then run... | Why |
+|---|---|---|
+| Modify the Better Auth server config (`auth.ts`) — plugins, providers, fields, session settings | `pnpm auth:generate` then `pnpm auth:migrate` | Config changes can alter the database schema |
+| Add or remove a social provider | `pnpm auth:generate` | Provider changes affect the account schema |
+| Change organization plugin settings (roles, limits, membership config) | `pnpm auth:generate` then `pnpm auth:migrate` | Org config changes affect member/invitation tables |
+| Edit `auth-schema.ts` manually | `pnpm auth:migrate` | Manual schema edits need migrations applied |
+| Update the `better-auth` package version | `pnpm auth:generate` then check for schema diff, migrate if needed | New versions may include schema changes |
+
+### Environment Hooks
+
+| When you... | Then run... | Why |
+|---|---|---|
+| Add a new env var to server `env.ts` | Add it to all relevant `.env` files and verify with `pnpm dev` | Missing env vars crash at startup due to t3-env validation |
+| Add a new `NEXT_PUBLIC_` env var | Add to `apps/web/.env.local` and restart dev server | Next.js requires restart to pick up new env vars |
+| Change `BETTER_AUTH_URL` or `FRONTEND_DOMAIN` | Update CORS config and verify OAuth callback URLs still work | Mismatched URLs break OAuth flows and cookie sharing |
+
+### Validation Checks
+
+After any auth-related changes, verify:
+- Dev server starts without errors: `pnpm dev`
+- Auth API responds: visit `{BETTER_AUTH_URL}/api/auth/ok`
+- If schema changed: `pnpm drizzle:studio:auth` shows expected tables
+- If middleware changed: unauthenticated requests to protected routes redirect to `/auth`
+- If org plugin changed: verify org creation and member invitation flows
+
+### Condensed Rules for CLAUDE.md
+
+This is the version that gets injected into the target project's CLAUDE.md during scaffolding:
+```markdown
+### auth-better-auth maintenance
+- After modifying Better Auth server config, plugins, or providers: run `pnpm auth:generate && pnpm auth:migrate`
+- After updating `better-auth` package: run `pnpm auth:generate`, check for schema changes, migrate if needed
+- After adding/changing env vars: update all `.env` files and verify `pnpm dev` starts clean
+- After changing `BETTER_AUTH_URL` or `FRONTEND_DOMAIN`: verify CORS config and OAuth callback URLs
+- After any auth changes: verify `{BETTER_AUTH_URL}/api/auth/ok` responds
+- Never edit the auto-generated auth schema directly — modify the Better Auth config and regenerate
+```
+
+---
+
+## Removing the Organization Plugin
+
+If your app doesn't need multi-tenancy:
+
+1. **Server:** Remove `organization()` from plugins array in `auth.ts`. Remove `currentOrganizationId` from `user.additionalFields`.
+2. **Client:** Remove `organizationClient()` from `createAuthClient()` plugins. Delete `context/`, `hooks/use-organization.ts`, `hooks/use-has-permission.ts`, `hooks/use-create-organization.ts`, `schema/organization.ts`, `types/organization.ts`.
+3. **Middleware:** Remove `requireOrganization()` — use only `requireAuth()`.
+4. **UI:** Remove onboarding flow, org switcher, team management. Simplify protected layout (no `OrganizationProvider` or `OnboardingRedirect`).
+5. **Schema:** The auto-generated schema will not include `organization`, `member`, or `invitation` tables.
+
+---
+
+## Claude Code Skills (Optional)
+
+The official Better Auth skills provide additional context during scaffolding. They are **not required** — this BLUEPRINT.md contains everything needed. Install them for quick-reference guides on configuration and best practices:
+
+```bash
+npx skillsadd better-auth/skills
+```
+
+This installs all Better Auth skills from [github.com/better-auth/skills](https://github.com/better-auth/skills), including:
+
+- **`/create-auth`** — Decision tree for new vs existing projects, framework-specific route handlers, database adapter setup, plugin configuration, security checklist
+- **`/best-practices`** — Core config options, session management strategies, cookie cache modes, security hardening, hooks, type safety, common gotchas
+- **`/organization`** — Organization plugin setup and multi-tenancy patterns
+- **`/twoFactor`** — Two-factor authentication implementation
+
+---
+
+## References
+
+- **Better Auth Docs:** https://www.better-auth.com/docs
+- **Better Auth LLMs.txt:** https://www.better-auth.com/llms.txt
+- **Better Auth GitHub:** https://github.com/better-auth/better-auth
+- **Better Auth Plugins:** https://www.better-auth.com/docs/plugins
+- **Drizzle ORM Docs:** https://orm.drizzle.team/docs/overview
+- **Drizzle PostgreSQL:** https://orm.drizzle.team/docs/get-started/postgresql-new
+- **t3-env Docs:** https://env.t3.gg
+- **Resend Docs:** https://resend.com/docs