From 443fefde1a0645c0f4089a04cde03b8cf29a0d87 Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Fri, 24 Jul 2026 18:04:22 +0000
Subject: [PATCH] docs: add Cursor Cloud agent setup instructions

---
 AGENTS.md | 45 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 00000000..d8a200ec
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,45 @@
+# 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.