CLAUDE.md for Next.js + Supabase

A CLAUDE.md with runnable commands, the server/client/admin Supabase split, reference-file conventions, and explicit do-nots.

# CLAUDE.md - Lumen (Next.js + Supabase)

## Commands
```bash
pnpm dev                     # dev server on :3000
pnpm vitest run              # one-shot tests (pnpm test is watch mode - avoid in CI)
pnpm vitest run -t "name"    # single test
pnpm lint && pnpm typecheck  # must pass before a PR
pnpm db:types                # regen lib/database.types.ts after any migration
```

## Architecture
- App Router; Server Components by default, `"use client"` only for interactivity.
- `lib/supabase/server.ts` for RSC + route handlers, `client.ts` for the browser,
  `admin.ts` (service role) for webhooks only - importing it elsewhere fails CI.
- Mutations: Server Actions in `app/actions/`, one file per domain, Zod-validated.
- Postgres schema lives in `supabase/migrations/`; every user table has RLS.

## Conventions
- Type DB rows from generated `lib/database.types.ts`; no `any`.
- New queries go in `lib/queries/` - follow `lib/queries/projects.ts` as the
  pattern (typed args, narrow selects, `throwOnError`).
- UI composes shadcn primitives from `components/ui/`; don't restyle them in place.
- Actions throw `AppError` (`lib/errors.ts`); route handlers map it to a response.

## Workflow
- Branch off `main`; CI = lint + typecheck + vitest + build.
- After schema edits: new migration file, run `pnpm db:types`, ship both together.
- Tasks touching auth or RLS start with the unauthenticated-request test.

## Do not
- Do not reach for the service-role client to bypass an RLS error - fix the policy.
- Do not edit applied migrations or generated types by hand.
- Do not add a client-side data-fetching library; use RSC + Server Actions.

These examples are released under CC0. Use them freely, no attribution required. They are provided as is, without warranty of any kind: review and adapt them to your project before use, as you are responsible for the outcome of applying them.