AGENTS.md template for React + Vite

# Project instructions

This repository is a React application built with Vite and TypeScript. Extend the existing design system and application patterns instead of creating parallel components, state stores, or styling approaches.

## Start here

- Read the target screen, its components, hooks, tests, and styles before editing.
- Reuse installed UI primitives and utilities.
- Keep changes scoped to the requested user flow.
- Preserve user changes, the current package manager, and the existing lockfile.

## Commands

- `pnpm install`: install dependencies.
- `pnpm dev`: start Vite locally.
- `pnpm test`: run Vitest.
- `pnpm lint`: run lint checks.
- `pnpm build`: run TypeScript and create the production bundle.

Replace these commands if the repository uses npm, Yarn, Bun, or different scripts.

## Architecture

- `src/components/`: reusable interface components.
- `src/features/`: feature-specific UI, state, and domain logic.
- `src/hooks/`: reusable React hooks.
- `src/lib/`: framework-agnostic utilities and clients.
- `src/routes/` or `src/pages/`: route-level composition.
- Keep state close to its consumer. Introduce shared state only when unrelated branches genuinely need it.

## React rules

- Prefer derived values during render over synchronizing redundant state in effects.
- Use effects only to synchronize with external systems, not for ordinary data transformation.
- Keep components focused; extract reusable behavior after a real second use case appears.
- Preserve stable keys, controlled form behavior, and cleanup for subscriptions or timers.
- Follow the existing data-fetching and error-handling pattern; do not add an overlapping client library.

## Interface quality

- Use semantic elements and accessible names for interactive controls.
- Preserve keyboard navigation, visible focus, readable contrast, and reduced-motion preferences.
- Include loading, empty, error, disabled, and success states when the flow can reach them.
- Verify layouts at narrow and wide viewports when UI structure changes.

## Testing and validation

- Test observable user behavior rather than implementation details.
- Add focused coverage for changed branches and regressions.
- Run the focused test first, then lint and the production build.
- Treat console errors, unhandled promises, and broken asset paths as failures.

## Definition of done

- The requested flow works with keyboard, pointer, and touch where relevant.
- Tests, lint, types, and the production build pass.
- New code follows established components, tokens, and state patterns.
- No unrelated dependencies, lockfiles, or user changes were modified.
- The final handoff states what changed, what was verified, and any remaining risk.