# AGENTS.md

Instructions for AI coding agents working in this repository. Keep this file short and up to date.
Humans: this is also the fastest way to understand how the project works.

## Project overview
- What it is: [ONE OR TWO SENTENCES: what the app does and who it is for]
- Status: [prototype | live with real users]. [If live: be careful with anything that touches user data or payments.]
- Stack: [e.g. Next.js + TypeScript + Tailwind, SQLite via Prisma, deployed on Vercel]
- Package manager: [npm | pnpm | yarn | bun | uv | poetry]. Do not switch it.

## Commands
Run these from the repository root.
- Install: `[npm install]`
- Run locally: `[npm run dev]` (then open [http://localhost:3000])
- Tests: `[npm test]`   Single test file: `[npm test -- path/to/file.test.ts]`
- Lint and format: `[npm run lint]`   `[npm run format]`
- Type check: `[npx tsc --noEmit]`
- Build: `[npm run build]`

Before you say a task is done, run lint, the type check and the tests that cover the code you changed. If a command fails and you cannot fix it, say so clearly and paste the error.

## Project layout
- `[src/app/]` — [pages and routes]
- `[src/components/]` — [reusable UI]
- `[src/lib/]` — [business logic and helpers; keep it free of UI code]
- `[tests/]` — [tests]
- `[scripts/]` — [one-off scripts]
- Generated or vendored, never edit by hand: `[dist/, build/, .next/, node_modules/, generated/]`

## Conventions
- Language: [TypeScript with `strict` on]. No `any` unless there is a comment explaining why.
- Naming: [camelCase for variables and functions, PascalCase for components and types, kebab-case for file names].
- Keep functions small and focused. Prefer clear names over comments; add a comment when the "why" is not obvious.
- Follow the patterns already used in the file you are editing. When in doubt, copy the style of a nearby file such as `[path/to/good-example.ts]`.
- Errors: [how errors are handled, e.g. "return `{ ok: false, error }` from lib functions; never swallow errors silently"].
- Configuration and secrets come from environment variables listed in `.env.example`. Never hard-code secrets and never commit `.env` files.

## Do
- Read the relevant files before changing them.
- Make the smallest change that solves the task, and keep unrelated code untouched.
- Add or update a test when you change behavior or fix a bug.
- Ask a question when the request is ambiguous, instead of guessing.
- Summarize what you changed, which files you touched and how you verified it.

## Do not
- Do not add a new dependency without asking first. Say why it is needed and what it costs.
- Do not delete files, rewrite large parts of the code, or rename public APIs unless the task asks for it.
- Do not change database schemas or run migrations without asking first.
- Do not edit the lockfile by hand.
- Do not disable lint rules, type checks or tests to make an error go away.
- Do not run destructive commands (for example `rm -rf`, `git reset --hard`, `git push --force`, dropping a database) without explicit approval.
- Do not invent APIs, library functions or config options. If you are not sure something exists, check the installed version's docs or source first.

## Git
- Work on a branch, not directly on `main`: `[git switch -c feature/short-name]`.
- Small commits with clear messages, for example `fix: handle empty cart on checkout`.
- Never commit secrets, large binaries or generated build output.

## Notes for this project
- [Anything an agent keeps getting wrong, for example "Prices are stored in cents as integers", or "The `legacy/` folder is unused; ignore it."]