# AGENTS.md: Express 5 API

## Commands
`npm run dev` · `npm test` · `npm run lint` · `npx tsc --noEmit`

## Layout
- `src/app.ts` builds the app (no `listen`), `src/server.ts` starts it. Tests import `app.ts`.
- `src/routes/<resource>.ts` defines an `express.Router()`; handlers call `src/services/*`.

## Rules
- Express 5 forwards rejected promises to error middleware, so use `async` handlers and don't wrap them in try/catch just to call `next(err)`.
- Validate `req.body`, `req.params` and `req.query` with zod schemas at the top of each handler; respond 400 with the flattened issues.
- One error middleware (4 args) at the end maps known errors to status codes and logs the rest. Never leak stack traces in production responses.
- Express 5 path syntax: named wildcards (`/*splat`) and `{optional}` segments; the old `?` and bare `*` patterns don't work.
- Security baseline: `helmet()`, `express.json({ limit: '100kb' })`, CORS with an explicit origin list, rate limiting on auth routes.
- Config from a validated env module; fail fast at startup if something is missing.
- Structured logging (pino) with a request id.

## Don't
- Don't use `body-parser` (built in) or `req.param()` (removed).
- Don't put DB queries directly in route files.

## Done
Typecheck, lint and `supertest` tests for every new route (happy path + validation error) pass.