CLAUDE.md, AGENTS.md, and Cursor rules: starter templates that actually bind

# AGENTS.md

## Commands
- Install: `pnpm install`
- Test (single file): `pnpm vitest run path/to/file.test.ts`
- Full check before any commit: `pnpm check` (types + lint + tests)
- Never run `pnpm build` to validate changes; `pnpm check` is faster and sufficient.

## Boundaries
- Never edit files in `src/generated/` or `migrations/applied/`. Regenerate instead.
- Never add a dependency without stating why in the PR description.
- Never weaken CI: no test deletions, no `|| true`, no coverage threshold changes.
- Secrets come from `env.ts` accessors only. Never read `process.env` directly.

## Conventions the linter cannot see
- New API routes copy the shape of `src/api/health/route.ts` (validation, error envelope, logging).
- Database access goes through `src/db/queries/`. No inline SQL in route handlers.
- Feature flags: check `flags.ts`; never hardcode a flag name as a string.

## PR
- One concern per PR. If the diff mixes a fix and a refactor, split it.
- PR description states the user-visible behavior change in 2 sentences.

Read AGENTS.md and follow it. Claude-specific additions only below this line.

- Use plan mode for changes touching more than 3 files.
- When a test fails twice with the same fix attempted, stop and report instead of retrying.

# CLAUDE.md

## Commands
- Dev server: `pnpm dev` (assume it is already running; never start a second one)
- Typecheck: `pnpm tsc --noEmit`
- Test one file: `pnpm vitest run <path>` (never the full suite during iteration)

## Architecture facts the model will guess wrong
- App Router only. `pages/` is legacy and frozen; never add to it.
- Server components by default. Add `"use client"` only for event handlers or browser APIs, and say why in the PR.
- All fetches go through `src/lib/api.ts`. It handles auth headers and retries; raw `fetch` in components is a bug.
- Route handlers validate input with the zod schemas in `src/schemas/`. New endpoint = new schema first.

## Hard rules
- Never use `any` or `as unknown as`. If types fight back, the design is wrong; stop and explain.
- Never suppress with `eslint-disable` or `@ts-expect-error` without a linked issue.
- State lives in the URL or the database. Introducing client state libraries requires a human decision.

## Done means
- `pnpm check` passes, and the change is visible at a URL you name in the summary.

# CLAUDE.md

## Commands
- Env: `uv sync` (this repo uses uv, not pip; requirements.txt does not exist)
- Test one file: `uv run pytest tests/test_x.py -x -q`
- Lint + format: `uv run ruff check --fix . && uv run ruff format .`

## Architecture facts the model will guess wrong
- FastAPI routers live in `app/routers/`, one file per resource. Business logic lives in `app/services/`; routers stay thin.
- All DB access is async SQLAlchemy through `app/db/session.py`. Never create a second engine or session factory.
- Exceptions: raise the typed errors in `app/errors.py`. Bare `except Exception` that logs-and-continues is the number one bug pattern in this codebase; never add one.
- Background work goes through the task queue in `app/tasks/`. No `asyncio.create_task` fire-and-forget in request handlers.

## Hard rules
- Never edit `alembic/versions/` by hand. Schema change = new autogenerated migration, reviewed.
- Pydantic models are the only serialization boundary. No raw dicts across module edges.
- New third-party packages require a human decision; propose in the summary instead of installing.

## Done means
- `uv run pytest -x -q` passes and ruff is clean.

---
description: API route conventions
globs: ["src/api/**"]
alwaysApply: false
---

- New routes copy `src/api/health/route.ts`: zod validation, typed error envelope, request logging.
- Auth: call `requireUser()` first line of every handler except routes listed in `src/api/PUBLIC.md`.
- Response shapes change only with a version bump; breaking an existing field is never a refactor.