# AGENTS.md

Guidance for AI agents working in this repository.

## Cursor Cloud specific instructions

### Product

Single-package **QA Studio** app (SvelteKit 2 + Svelte 5 + Prisma + PostgreSQL). Not a monorepo. Dev server binds **port 3000** (`vite.config.ts`); README still mentions 5173 in places.

### Required environment variables

The VM typically provides these via injected secrets (no `.env.local` required if set at process level):

| Variable                               | Purpose                               |
| -------------------------------------- | ------------------------------------- |
| `DATABASE_URL`                         | PostgreSQL (Neon or local)            |
| `SESSION_SECRET`                       | Session HMAC                          |
| `TOTP_ENCRYPTION_KEY`                  | 64 hex chars (`openssl rand -hex 32`) |
| `BLOB_READ_WRITE_TOKEN`                | Vercel Blob for attachments           |
| `ENCRYPTION_KEY`, `URL_SIGNING_SECRET` | Integrations / signed trace URLs      |

Optional but common: Upstash Redis REST URL/token (`KV_*`); caching is disabled in dev if unset. Set self-hosted mode (`SELF_HOSTED=true`) to skip Stripe/subscription gates for local full-feature testing.

See `.env.example` for the full list.

### Paraglide (i18n)

`src/lib/paraglide` is gitignored and **not** created by `npm install` alone. Before `npm run check` or if the dev server returns 500 with missing `$lib/paraglide/*` modules, run:

```bash
npx @inlang/paraglide-js compile --project ./project.inlang --outdir ./src/lib/paraglide
```

`npm run dev` also compiles via the Vite plugin once the server starts.

### Services

| Service            | Local dev                                                                                                                   |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------- |
| **App**            | `npm run dev` (port 3000)                                                                                                   |
| **PostgreSQL**     | Use `DATABASE_URL` from env, or `docker compose up postgres` (Docker optional)                                              |
| **Playwright E2E** | Default config hits production `the hosted deployment`; local E2E needs `webServer` + credentials in `playwright.config.ts` |

Docker Compose (`npm run docker:dev`) includes Redis/MinIO/MailHog, but the app code uses **Upstash** (`KV_*`) and **Vercel Blob**, not the compose Redis/MinIO env vars.

### Standard commands

| Task                          | Command                                                      |
| ----------------------------- | ------------------------------------------------------------ |
| Install                       | `npm install`                                                |
| DB schema                     | `npx prisma migrate deploy` (or `db push` for throwaway DBs) |
| **Format (before commit)**    | `npm run format` — CI fails if unformatted files remain      |
| **Typecheck (before commit)** | `npm run check` — required for TS/Svelte changes             |
| Lint                          | `npm run lint` (large pre-existing eslint backlog in repo)   |
| Unit tests                    | `npm run test:unit -- --run`                                 |
| Build                         | `npm run build`                                              |
| Dev                           | `npm run dev`                                                |

### Before committing

Always run **`npm run format`** and **`npm run check`** locally before `git commit`. Stage any files Prettier rewrites. See [CONTRIBUTING.md](CONTRIBUTING.md#creating-a-pull-request) for the full pre-commit checklist.

### Long-running processes

Use **tmux** (`tmux -f /exec-daemon/tmux.portal.conf`) for `npm run dev` and other background servers so sessions survive agent disconnects.

### Gotchas

- **Do not reset the DB tables.** The `DATABASE_URL` points at a shared, already-provisioned Postgres (Neon) whose schema is up to date (`npx prisma migrate status` reports "up to date"). Never run `prisma migrate reset` / `prisma db push --force-reset` or otherwise drop/recreate tables; use `npx prisma migrate deploy` only if new migrations need applying. Creating rows (e.g. a test signup/project) is fine.
- `postinstall` runs `prisma generate` but may skip if `.svelte-kit` is missing; run `npx svelte-kit sync` first on a clean clone.
- Lint reports many `svelte/no-navigation-without-resolve` issues repo-wide; do not treat as introduced by your change unless you touched those files.
- Default `npm run test:e2e` does **not** start a local server.