AGENTS.md template for Next.js

# Project instructions

This repository is a Next.js App Router application written in TypeScript. Preserve the existing architecture and reuse established components, utilities, and data-access patterns before introducing new abstractions.

## Start here

- Read the nearest layout, page, component, test, and data-access files before editing.
- Use the package manager and lockfile already present in the repository.
- Prefer the smallest change that fully satisfies the request.
- Treat uncommitted and user-authored changes as intentional. Never discard them.

## Commands

- `npm install`: install dependencies.
- `npm run dev`: start the local development server.
- `npm run lint`: run lint checks.
- `npm test`: run the test suite.
- `npm run build`: run the production build and type checks.

Replace these commands if this repository uses pnpm, Yarn, Bun, or different scripts.

## Architecture

- `app/`: routes, layouts, loading states, and server actions.
- `components/`: reusable interface components.
- `lib/`: shared utilities, services, validation, and data access.
- `public/`: static assets.
- Keep route-specific code close to its route. Promote code to shared folders only after genuine reuse appears.

## Next.js and React rules

- Use Server Components by default. Add `'use client'` only when browser state, effects, or event handlers are required.
- Keep client-component boundaries narrow; do not move server data fetching into effects without a concrete need.
- Use the framework metadata API for titles, descriptions, canonical URLs, and social previews.
- Provide loading, empty, error, and success states when a flow can reach them.
- Preserve keyboard access, semantic HTML, visible focus, and responsive behavior in UI changes.

## Data and security

- Validate untrusted input at the server boundary.
- Do not expose secrets or server-only environment variables to client bundles.
- Do not change schemas, migrations, authentication, or authorization rules without explicit task scope.
- Never log credentials, tokens, personal data, or full request payloads containing sensitive values.

## Testing and validation

- Add or update focused tests for changed behavior.
- Run the narrowest relevant test first, then the repository's full required checks.
- Run `npm run build` before completing changes that affect routes, rendering, types, or configuration.
- Fix failures caused by your work; report unrelated pre-existing failures without masking them.

## Definition of done

- The requested behavior works end to end.
- Relevant tests, lint, types, and the production build pass.
- New UI remains accessible and responsive.
- No secrets, migrations, lockfiles, or unrelated user changes were altered accidentally.
- The final handoff states what changed, what was verified, and any remaining risk.