# AGENTS.md

## Cursor Cloud specific instructions

This repo is the **React 19 / Vite** SPA for SHOC (Sea Haven Industries), a facility
maintenance / work-order & vendor-dispatch platform. It talks to the .NET 8 Web API in
the `shoc-backend` repo. Standard scripts live in `package.json` / `README.md`.

### Node version

`package.json` engines require **Node `>=22.22.1`**. On Cloud Agent VMs, prefer nvm and
put that binary ahead of `/exec-daemon/node` (often an older 22.14.x):

```bash
export PATH="$HOME/.nvm/versions/node/v22.22.2/bin:$PATH"
```

### Running (dev)

- Install deps with `npm install` (committed `package-lock.json`), then
  `npm run dev` (Vite on `http://localhost:3000`). Use
  `BROWSER=none npm run dev -- --host 0.0.0.0 --port 3000` in headless VMs.
- In dev, `.env.development` sets `VITE_API_URL=/api` and
  `VITE_API_TARGET=http://localhost:5141`. Vite proxies `/api` → that target, so the
  **backend Web API must be running on `:5141`** (see `shoc-backend` AGENTS.md) for
  auth and data to work.
- Log in with the backend-seeded dev admin using Cursor Cloud secrets
  **`TEST_LOGIN_USERNAME`** and **`TEST_LOGIN_PASSWORD`**. Do not commit plaintext
  credentials.

### Lint / test / build

- **Lint**: `npm run lint` (`eslint . --max-warnings=0`).
- **Unit tests**: `npm test` (`vitest run`).
- **E2E**: `npm run test:e2e` (Playwright; needs app + usually API).
- **Build**: `npm run build` (`tsc -b && vite build`). Day-to-day work uses
  `npm run dev`, not the production build.

### Known pre-existing app / backend bugs (NOT environment problems)

- Several list/detail pages can error when the backend joins the drifted `Locations`
  table or missing `Events` table (see `shoc-backend` AGENTS.md). Prefer hello-world
  paths that avoid those joins (login + Employee create/list).
- Contact / other forms may still have product bugs; do not treat those as setup
  failures.