# AGENTS.md

<!--
  A starter context file for coding agents, from the atuitam library (atuitam.com).
  Fill in the parts in <angle brackets>, delete what does not apply.
  Keep it short: an agent reads this file on every task. Aim for one or two screens.
  Write facts and rules, not aspirations. If a rule is not enforced, say so.
-->

## What this system is

<One paragraph. What the product does, for whom, and the one thing that must never break.>

Example: *Booking platform for physiotherapy clinics. Clinics manage their calendars, patients book online. Double bookings must never happen.*

## Map

| Part | Path | Owns | Talks to |
|---|---|---|---|
| <Web app> | `apps/web` | <UI, session> | <API> |
| <API> | `apps/api` | <bookings, clinics, users> | <Postgres, queue> |
| <Worker> | `apps/worker` | <emails, reminders> | <queue, email provider> |
| <Shared types> | `packages/types` | <DTOs shared by web and API> | — |

Architecture decisions live in `<docs/adr/>`. Read the relevant ADR before changing anything it covers.

## Boundaries

- `<apps/web>` never talks to the database directly. It goes through the API.
- Only `<apps/api/src/bookings>` writes to the `<bookings>` table.
- `<packages/types>` contains types only. No logic, no runtime dependencies.
- External services are wrapped in adapters under `<apps/api/src/adapters>`. Business code imports the adapter, never the vendor SDK.

## Do not touch

Ask before changing any of these, even if the change looks small:

- `<migrations/>`: never edit an existing migration. Add a new one.
- `<infra/>`: infrastructure as code, deployed by CI. Changes need a human review.
- `<apps/api/src/billing>`: payment logic, covered by contracts with the provider.
- Anything under `<legacy/>`: scheduled for removal, see ADR `<0012>`.
- Secrets and `.env*` files. Never print, log or commit them.

## How to work here

- **Install:** `<pnpm install>`
- **Run locally:** `<pnpm dev>` (needs `<docker compose up db>`)
- **Test:** `<pnpm test>`. Run the tests for the package you changed before you finish.
- **Lint and types:** `<pnpm lint && pnpm typecheck>` must pass.
- **Branches and commits:** `<feature/short-name>`, commit messages in `<English, imperative>`.

## Conventions

- <Language and framework versions, e.g. TypeScript strict, Node 22.>
- <Error handling, e.g. the API returns problem+json, never stack traces.>
- <Naming, e.g. database columns in snake_case, TypeScript in camelCase.>
- <Dates, e.g. stored in UTC, shown in the clinic's time zone.>
- <Feature flags, logging, i18n: where they live and how to use them.>

## AI components

<Delete this section if the system has none.>

- Prompts live in `<apps/api/src/ai/prompts>`, versioned with the code.
- Model output is untrusted input: validate it against a schema before using it.
- Personal data is `<never / only in pseudonymised form>` sent to the model provider.
- Prompt changes need a run of `<pnpm eval>` before merging.

## When unsure

- If a task conflicts with a boundary or an ADR, stop and ask instead of working around it.
- If you find a decision that is not documented anywhere, say so in your summary. It is a candidate for a new ADR.
- Prefer the smallest change that solves the task. Do not refactor unrelated code.