Next.js AGENTS.md Template

# AGENTS.md — Next.js

## Stack

- Next.js App Router, React, TypeScript, and [styling system].
- Package manager: [pnpm/npm/yarn]. Use the existing lockfile.
- Server state: [database/API]. Client state: [library or React state].

## Commands

- Install: `pnpm install`
- Develop: `pnpm dev`
- Lint: `pnpm lint`
- Type check: `pnpm tsc --noEmit`
- Test: `pnpm test`
- Build: `pnpm build`

## Next.js rules

- Default to Server Components. Add `"use client"` only when browser APIs, effects, event handlers, or client state require it.
- Keep secrets, admin clients, and privileged data access in server-only modules.
- Use Route Handlers or Server Actions for mutations and validate all input at the boundary.
- Do not fetch from the app's own HTTP endpoints inside Server Components; call the underlying service directly.
- Use `next/image` and `next/link` where appropriate.
- Provide stable keys; do not use array indexes for reorderable lists.
- Preserve streaming and caching behavior. Document any use of `force-dynamic`, `no-store`, or revalidation.

## UI and accessibility

- Use semantic HTML before ARIA.
- Every control must have an accessible name and visible focus state.
- Support keyboard use, reduced motion, loading, empty, and error states.
- Check responsive layouts at small and large widths.

## SEO

- Public pages need a unique title, description, canonical URL, Open Graph image, and Twitter card.
- Use one descriptive H1 and a logical heading order.
- Add structured data only when it matches visible page content.
- Add indexable pages to the sitemap; exclude private and utility routes.

## Verification

- Run lint, type check, relevant tests, and `pnpm build`.
- Check the browser console and verify metadata in rendered HTML.