# AGENTS.md: Nuxt 4

## Commands
`npm run dev` · `npm run build` · `npx nuxi typecheck` · `npm run lint` · `npx vitest run` (with `@nuxt/test-utils`)

## Layout (Nuxt 4)
- App code in `app/` (`app/pages`, `app/components`, `app/composables`, `app/layouts`, `app/middleware`). Server code in `server/` (`server/api`, `server/routes`, `server/utils`). Shared types/utils in `shared/`.
- Auto-imports are on; don't add manual imports for Vue/Nuxt composables or components in those folders.

## Data
- Fetch with `useFetch('/api/orders')` or `useAsyncData('orders', () => $fetch(...))` with a stable key; don't call `$fetch` directly in `setup` for SSR data (it double-fetches).
- Handle `pending`/`status` and `error` in templates. Use `watch` options or reactive params for refetching.
- Shared SSR-safe state via `useState('key', () => init)`, Pinia for larger stores.

## Server routes
- `server/api/orders.post.ts` with `defineEventHandler`. Validate with `readValidatedBody(event, schema.parse)` / `getValidatedQuery` (zod). Throw `createError({ statusCode: 400, statusMessage })`.
- Auth checked in each handler via a `server/utils` helper (`requireUser(event)`).

## Config
- `runtimeConfig` in `nuxt.config.ts` for secrets (server only) and `runtimeConfig.public` for client-safe values; override with `NUXT_*` env vars. Never read `process.env` in app code.

## Done
Typecheck, lint, tests, and `npm run build` pass.