docs: add CLAUDE.md with project conventions and architecture guide

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

CLAUDE.md

@@ -0,0 +1,89 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+```bash
+# Development
+pnpm dev          # Start dev server (http://localhost:3000)
+pnpm build        # Production build (standalone output)
+pnpm lint         # Run ESLint
+
+# Database (use pnpm instead of npx)
+pnpm prisma migrate dev --name <name>   # Create and apply migration
+pnpm prisma generate                    # Regenerate Prisma client
+pnpm prisma studio                      # Open DB GUI
+```
+
+## Stack
+
+- **Next.js 16** (App Router, standalone output)
+- **SQLite + Prisma 7** via `@prisma/adapter-better-sqlite3` (not the default SQLite adapter)
+- **NextAuth.js v5** (beta.30) — JWT sessions, Credentials provider only
+- **Tailwind CSS v4** — CSS Variables theming in `src/app/globals.css`
+- **Drag & Drop** — `@dnd-kit` and `@hello-pangea/dnd` (both present)
+- **pnpm** — package manager (use pnpm, not npm/yarn)
+
+## Architecture Overview
+
+### Workshop Types
+There are 5 workshop types: `swot` (sessions), `motivators`, `year-review`, `weekly-checkin`, `weather`.
+
+**Single source of truth**: `src/lib/workshops.ts` exports `WORKSHOPS`, `WORKSHOP_BY_ID`, and helpers. Every place that lists or routes workshop types must use this file.
+
+**All types and UI config constants** are in `src/lib/types.ts` (e.g. `MOTIVATORS_CONFIG`, `YEAR_REVIEW_SECTIONS`, `SWOT_QUADRANTS`, `EMOTIONS_CONFIG`).
+
+### Layer Structure
+
+```
+src/
+├── actions/          # Next.js Server Actions ('use server') — call services, revalidate paths
+├── services/         # Prisma queries + business logic (server-only)
+│   ├── database.ts   # Prisma singleton (global for dev HMR)
+│   ├── session-permissions.ts  # Shared permission factories
+│   └── session-share-events.ts # Shared share + SSE event handlers
+├── app/
+│   ├── api/          # Route handlers (SSE subscribe + auth)
+│   ├── (auth)/       # Login/register pages
+│   └── [workshop]/   # One folder per workshop type
+├── components/
+│   └── collaboration/ # BaseSessionLiveWrapper + share/live UI
+├── hooks/
+│   └── useLive.ts    # SSE client hook (EventSource + reconnect)
+└── lib/
+    ├── workshops.ts   # Workshop metadata registry
+    ├── types.ts       # All TypeScript types + UI config
+    └── share-utils.ts # Shared share types
+```
+
+### Real-Time Collaboration (SSE)
+Each workshop has `/api/[path]/[id]/subscribe` — a GET route that opens a `ReadableStream` (SSE). The server polls the DB every 1 second for new events and pushes them to connected clients. Server Actions write events to the DB after mutations.
+
+Client side: `useLive` hook (`src/hooks/useLive.ts`) connects to the subscribe endpoint with `EventSource`, filters out events from the current user (to avoid duplicates), and calls `router.refresh()` on incoming events.
+
+`BaseSessionLiveWrapper` (`src/components/collaboration/`) is the shared wrapper component that wires `useLive`, `CollaborationToolbar`, and `ShareModal` for all workshop session pages.
+
+### Shared Permission System
+`createSessionPermissionChecks(model)` in `src/services/session-permissions.ts` returns `canAccess`, `canEdit`, `canDelete` for any Prisma model that follows the session shape (has `userId` + `shares` relation). Team admins have implicit access to their members' sessions.
+
+`createShareAndEventHandlers(...)` in `src/services/session-share-events.ts` returns `share`, `removeShare`, `getShares`, `createEvent`, `getEvents` — used by all workshop services.
+
+### Auth
+- `src/lib/auth.ts` — NextAuth config (signIn, signOut, auth exports)
+- `src/lib/auth.config.ts` — config object (used separately for Edge middleware)
+- `src/middleware.ts` — protects all routes except `/api/auth`, `_next/static`, `_next/image`, `favicon.ico`
+- Session user ID is available via `auth()` call server-side; token includes `id` field
+
+### Database
+Prisma client is a singleton in `src/services/database.ts`. `DATABASE_URL` env var controls the SQLite file path (default: `file:./prisma/dev.db`). Schema is at `prisma/schema.prisma`.
+
+### Adding a New Workshop
+Pattern followed by all existing workshops:
+1. Add entry to `WORKSHOPS` in `src/lib/workshops.ts`
+2. Add Prisma models (Session, Item, Share, Event) following the existing pattern
+3. Create service in `src/services/` using `createSessionPermissionChecks` and `createShareAndEventHandlers`
+4. Create server actions in `src/actions/`
+5. Create API route `src/app/api/[path]/[id]/subscribe/route.ts` (copy from existing)
+6. Create pages under `src/app/[path]/`
+7. Use `BaseSessionLiveWrapper` for the session live page