AGENTS.md for Next.js + Supabase

A production-shaped AGENTS.md for a Next.js App Router + Supabase SaaS: exact commands, RLS rules, server/client boundaries, and PR gates.

# Lumen (Next.js + Supabase)

## Project Overview
Next.js 15 App Router SaaS: TypeScript strict, Supabase (Postgres + Auth, RLS on
every user table), Tailwind + shadcn/ui, deployed on Vercel. Server Components
by default; client components only where interactivity requires them.

## Setup & Commands
```bash
pnpm install                 # Node 20+, pnpm 9
pnpm dev                     # http://localhost:3000
pnpm vitest run              # tests once (pnpm test is watch mode)
pnpm vitest run -t "name"    # single test by name
pnpm lint && pnpm typecheck  # both gate CI
pnpm db:types                # regenerate lib/database.types.ts after schema changes
```

## Structure
- `app/` - routes; server components unless the file starts with `"use client"`
- `lib/supabase/` - `server.ts` (RSC + route handlers), `client.ts` (browser)
- `lib/queries/` - typed data-access helpers; the only place queries live
- `supabase/migrations/` - numbered SQL migrations, applied with `supabase db push`
- `components/ui/` - generated shadcn primitives; compose above, don't restyle

## Code Style
- No `any`; type DB rows from the generated `lib/database.types.ts`.
- Zod-parse every route-handler body and search param; schemas in `lib/schemas/`.
- Mutations are Server Actions in `app/actions/`, revalidated with `revalidatePath`.

## Testing
- Unit tests colocate as `*.test.ts`; new route handlers need an
  unauthenticated-request case (expect 401).
- E2E: `pnpm exec playwright test` (starts its own dev server).

## Security
- New user tables ship an RLS policy in the same migration, no exceptions.
- Only `lib/supabase/admin.ts` may import the service-role key; it is reserved
  for webhook handlers and cron.

## Boundaries
- Never edit an applied migration; add a new numbered file instead.
- Do not fetch data in client components; lift to a server component or action.
- `lib/database.types.ts` is generated - regenerate it, don't hand-edit.

## PR Guidelines
- Title: `feat|fix|chore(scope): summary`. CI runs lint, typecheck, vitest, build.
- Schema changes include the migration and regenerated types in the same PR.

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.