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.

Estos ejemplos se publican bajo CC0: úsalos libremente, sin atribución. Se proveen tal cual, sin garantía de ningún tipo: revísalos y adáptalos a tu proyecto antes de usarlos, ya que eres responsable del resultado de aplicarlos.