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.

Estes exemplos são publicados sob CC0. Use livremente, sem atribuição. São fornecidos como estão, sem garantia de qualquer tipo: revise e adapte ao seu projeto antes de usar, pois você é responsável pelo resultado de aplicá-los.