# <App name>

<One sentence: what it is and who uses it.> Live at https://<app>.<domain>.
Start with README.md (stack, how it fits together, local development) and DEPLOY.md
(shipping). Requirements: REQUIREMENTS.md. Design system: DESIGN.md.

## Stack (locked)

`api/`: Fastify 5, Prisma 6.19.3 (pinned — ignore the CLI's upgrade nag), zod 4,
argon2, TypeScript ~5.9. `web/`: React 19, Vite 8, Tailwind v4, shadcn/ui (radix-nova),
TanStack Query. Postgres <version>.
Don't add a framework, upgrade a major version, or swap a library without asking.

## Commands

| | |
|---|---|
| Install | `npm install` (root, workspaces) |
| Dev | `npm run dev` (api on :<api-port>, web on :5173) |
| Typecheck | `npm run typecheck` |
| Tests | `npm test` (API tests use the `<app>_test` database in `api/.env.test`) |
| Browser flows | `node scripts/browser-flows/<flow>.mjs <base-url> <profile-dir>` — see `scripts/browser-flows/README.md` |
| Deploy | `./scripts/deploy.sh` (builds locally, never on the server) |

## Design

All UI follows DESIGN.md. Reuse its components, use tokens only (never raw hex in a
screen), keep tap targets ≥ 44px, check at 390px. Anything new that DESIGN.md does not
cover: design it first, don't improvise.

## After each change

1. `npm run typecheck && npm test`.
2. The browser flows for the screens you touched, against local dev. A flow must
   compare the DOM with the API after each action, then reload and compare again.
3. Deploy only per the rule below, then run the same flow on production as the test
   account and clean up anything it wrote.
Never say "done" or "fixed" without the output of these steps.

## Deploy rule

<Pick one and delete the others>
- **PR and stop:** open a PR and stop. Deploy only when the owner writes "deploy",
  "ship it" or "make it live" on the ticket. "Done when it works" is not a deploy
  instruction. If unsure, ask.
- **Branch:** commit to `develop`. The owner fast-forwards `main` and deploys.
- **Agent deploys:** commit, `./scripts/deploy.sh`, push `main` with `Fixes <KEY>-n`.

When deploying: tests and flows pass first (never deploy around a failure); deploy the
merged `main`, not a branch; apply new migrations to the test DB first; the deploy must
end with `Deployed <sha>`; after a deploy, `git checkout develop` again if you use one.

## Branches

- `main` = what is live. `develop` (if used) = next.
- Another session (human or AI) may be editing this repo. Check `git status` and
  `git log` for work you did not make before merging or deploying.
- Never force-push `main`. Never rewrite published history.

## Test account (production)

A throwaway login for checking changes live: `<tester>@example.com` / `<password>`.
Use it, never a real person's account, for anything that writes. Flows that change a
password or delete an account run on local dev only.

## Privacy and secrets

- Never print, commit or paste secrets, tokens, `.env` values, server IPs or real
  users' data. Print key *names* only (`cut -d= -f1 .env`).
- `.env*` files are git-ignored. Quote any value containing `<`, spaces or quotes
  (deploy scripts source them with bash).
- Test data uses `@example.com` addresses.

## Server

Runs as systemd service `<app>-api` with `node --max-old-space-size=128` and
`MemoryMax=256M`. Check memory after each deploy:
`systemctl show <app>-api -p MemoryCurrent`. A number that keeps climbing is a leak:
fix it, don't raise the cap.