diff --git a/AGENTS.md b/AGENTS.md
index 15fb73a6b..d8cde1e59 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -153,3 +153,34 @@ reviewers (Codex, CodeRabbit).
   keep translated locales from contradicting the English source).
 - **Privacy:** `bun run privacy:scan` must stay green; never introduce logging
   of request bodies, API keys, or account identifiers.
+
+## Cursor Cloud specific instructions
+
+Environment prerequisites (Bun 1.3.14, root + `gui/` deps) are installed by the
+startup update script; the commands below are already documented in
+[Commands](#commands) and the README's Development section. Notes here cover
+only non-obvious gotchas for this container:
+
+- **Runtime location:** `bun` is on `PATH` via `/usr/local/bin/bun` (symlink to
+  `~/.bun/bin`); interactive shells also get it from `~/.bashrc`. `node` is the
+  VM default and only used to launch tooling.
+- **GUI lint needs the Bun runtime, not Node.** `gui/eslint.config.js` imports
+  `.ts` helpers, and the VM's Node cannot strip TS types on import, so plain
+  `bun run lint:gui` (which shells out to Node via eslint's shebang) fails with
+  `ERR_UNKNOWN_FILE_EXTENSION ".ts"`. Run `bun --bun run lint:gui` so eslint
+  executes under Bun. CI is unaffected because its runner ships Node 24.
+- **`gui/bun.lock` drifts from `gui/package.json`** on this base (missing
+  `posthog-js` + fontsource entries), so any `--frozen-lockfile` install fails.
+  Plain `bun install` reconciles it. Consequence: `bun run build:gui` (its first
+  step is a frozen install) fails here — for local dashboard work use the Vite
+  dev server instead of the packaged build.
+- **Dev workflow (two processes):** `bun run dev:proxy` serves the proxy + API +
+  dashboard on `10100`; for live GUI edits run
+  `OPENCODEX_PROXY_TARGET=http://127.0.0.1:10100 bun run dev:gui`, which serves
+  the dashboard on `5173` and proxies `/api` + `/healthz` to the daemon.
+- **Expected `bun run test` failures in this container (not regressions):**
+  Docker detection makes `ocx status`/service report "unsupported in Docker",
+  failing 3 CLI/service tests (`tests/cli-help.test.ts`, `tests/service.test.ts`);
+  two more are base-branch content drift where tests expect text not present in
+  `.github/workflows/release.yml` and the source-Bun docs paragraph. Treat these
+  five as pre-existing; the other ~5108 tests pass.