AGENTS.md for Next.js

# AGENTS.md

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

## Stack

This repository is a Next.js app on the App Router with TypeScript. Server Components are the default. Add a client component only for state, effects, or browser APIs.

## Layout

- Routes, layouts, and server code live in `app/`.
- Shared UI lives in `components/`. Shared logic lives in `lib/`.
- Keep route files thin. Move non-trivial logic into functions that can be tested without rendering a page.

## Commands

- Dev server: `npm run dev`
- Production build: `npm run build`
- Lint: `npm run lint`
- Tests: `npm test`

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

## Conventions

- Fetch data on the server. Do not fetch in `useEffect` for data the server can already load.
- Use `next/link`, `next/image`, and `next/font`. Do not add another image or font pipeline.
- Mutations go through the Server Actions or route handlers the repo already uses.
- Validate input at the boundary with the validator the repo already uses.
- Keep client components small and at the leaves of the tree.
- Match the existing styling system. Do not introduce a second CSS framework.

## Testing

Add or update tests when behavior changes.

Use the runner already in the repo (Vitest, Jest, or Playwright). Cover the behavior you changed, not every component.

## 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 from server actions and route handlers. Do not send stack traces to the client.

## Scope

- Do the requested task. Do not refactor unrelated code.
- Treat every instruction here as a constraint, not a suggestion.
- Ask one clarifying question only when the task cannot be finished without it. Otherwise state the assumption and continue.

## Avoid

- Do not import server-only modules into a client component.
- Do not put secrets in `NEXT_PUBLIC_` variables or client bundles.
- Do not mark a whole tree as a client component to silence one hook error.
- Do not add `pages/` routes to an App Router project.

## Done when

- The requested behavior works.
- `npm run lint` and `npm test` pass, or you name the command you could not run.
- The diff stays inside the task.
- You list anything you could not run.