# CLAUDE.md

<!-- Template from the State of CLAUDE.md study (locul.ai/research/state-of-claude-md). Replace every <...>, delete what does not apply, and delete this line. Aim to stay under 200 lines. -->

## Project overview

<One or two sentences: what this repo is, who uses it, and the main stack.>
Example: "REST API and admin dashboard for <product>. TypeScript, Next.js 15, Postgres via Prisma."

## Commands

Swap in your own tools; keep the exact flags.

```bash
pnpm install                          # install dependencies
pnpm dev                              # dev server on http://localhost:3000
pnpm test                             # full test suite
pnpm test -- path/to/file.test.ts     # one test file
pnpm lint                             # lint (must pass before a PR)
pnpm typecheck                        # type check
pnpm build                            # production build
```

## Architecture

- `<dir>/`: <what lives here and why>
- `<dir>/`: <what lives here and why>
- <How a request or job flows through the system, in one or two lines.>
- <Where config and environment variables are read.>

## Code style

- <The conventions a linter does not enforce: naming, file layout, error handling.>
- <Preferred patterns, with one real example path to copy from: see `<path/to/good/example>`.>
- <Anything Claude tends to get wrong here, stated as a concrete rule.>

## Testing

- Run `pnpm test` before saying a change is done. Run a single file while iterating.
- New code gets a test next to it in `<test dir or naming pattern>`.
- <Test data, fixtures or services the tests need, and how to start them.>

## Git and pull requests

- Branch from `<main branch>`; never push to it directly.
- Commit messages: <format, e.g. Conventional Commits: feat:, fix:, chore:>.
- <PR checklist: tests pass, lint clean, screenshots for UI changes.>

## Rules

- Never commit secrets. Keys live in `<.env.local or secret manager>`, which is gitignored.
- Do not edit `<generated or vendored paths>`; regenerate them with `<command>`.
- Ask before adding a dependency or changing the database schema.

## Gotchas

- <The non-obvious thing that costs a new contributor an hour.>
- <Known flaky test, required service, or OS-specific step.>