AGENTS.md for Next.js + Supabase

# AGENTS.md

Instructions for coding agents working in this Next.js + Supabase repository. Cursor, Claude Code, Codex, Copilot, and other agents should follow this file before they guess.

## Stack

This repository is a Next.js app using Supabase. The browser uses the anon key only. Row Level Security is the authorization layer, and the service role stays on the server.

## Layout

- Server Components and route handlers create the server Supabase client.
- Client components talk to Supabase only for flows the project already does in the browser, such as the auth UI.
- SQL and policies live in the supabase folder if the repo tracks them.

## Commands

- Dev server: `npm run dev`
- Tests: `npm test`
- Types: `Generate Supabase types with the script the repo already has`

Use the script the repo already defines when it differs from the command above.

## Conventions

- Use the anon key in the browser. The service role key never ships to the client.
- Assume RLS is on. A query that only works with the service role is a bug unless the task is an admin job.
- Read the user from the server client. Do not trust a user id from the request body.
- Regenerate database types when columns change, using the project's script.
- Keep Server Components the default. Add a client component only for auth widgets or local state.
- Match the existing cookie and middleware session refresh.

## Testing

Add or update tests when behavior changes.

Test the server action or route with a mocked Supabase client. Cover the unauthorized case.

## Style

- Optimize for the next reader over the shortest diff.
- Comment only when the why is non-obvious.
- Name things the way neighboring files already do.
- Do not reformat code you did not change.

## Errors

- Fail at the boundary. Do not swallow errors.
- Return a clear error when RLS hides a row or the session is missing. Do not leak the service-role error to the browser.

## Scope

- Do the requested task. Do not refactor unrelated code.
- Match the rigor already in the repo. Fix what you touch.
- Ask one clarifying question only when the task cannot be finished without it. Otherwise state the assumption and continue.

## Avoid

- Do not disable RLS to make a query return rows.
- Do not call `supabase.auth.getSession()` in untrusted client code and treat it as proof on the server.
- Do not store the service role in NEXT_PUBLIC_.
- Do not invent a second auth library next to Supabase Auth.

## Done when

- The requested behavior works.
- The dev server renders the change, and a policy or type update is included when the table changed.
- The diff stays inside the task.
- You list anything you could not run.