diff --git a/.changeset/cloud-dev-environment-setup.md b/.changeset/cloud-dev-environment-setup.md
new file mode 100644
index 00000000000..a845151cc84
--- /dev/null
+++ b/.changeset/cloud-dev-environment-setup.md
@@ -0,0 +1,2 @@
+---
+---
diff --git a/AGENTS.md b/AGENTS.md
index 99e9b9bfbbb..3df2467469e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -18,3 +18,12 @@ Clerk's JavaScript SDK and library monorepo.
 - For the Mosaic design system (tokens, CVA utility, `MosaicProvider`, migration from existing system), see `references/mosaic-architecture.md`.
 - For dev setup, testing, JSDoc/Typedoc, publishing, changesets, and commit conventions, see `docs/CONTRIBUTING.md`.
 - For working in the repo day to day (setup ordering and footguns, the package map, dev-loop recipes, and the breaking-change checklist), the `clerk-monorepo` Claude Code skill in `.claude/skills/clerk-monorepo/` restates these rules in actionable form.
+
+## Cursor Cloud specific instructions
+
+Node/pnpm are already set up in the VM image; you do not need to install or activate anything. Node `24.15.0` is installed via nvm and made to win over the daemon's bundled `/exec-daemon/node` (v22) through symlinks in `/usr/local/cargo/bin` (which precedes `/exec-daemon` in `PATH`). Because the Cursor shell is non-interactive and does not source `~/.bashrc`, that symlink layer — not a profile edit — is what makes bare `node`/`pnpm`/`npx` resolve to v24 in every shell. If bare `node` ever reports v22, re-point those symlinks at `~/.nvm/versions/node/v24.15.0/bin`; do not edit `/exec-daemon`.
+
+- Dependency install is handled by the startup update script (`pnpm install --frozen-lockfile`). Standard build/test/lint/dev commands live in `docs/CONTRIBUTING.md` and the `clerk-monorepo` skill; run `pnpm build` before `dev`/tests since packages consume each other's `dist/`.
+- Runnable browser app: `pnpm dev:sandbox` serves the clerk-js UI sandbox at `http://localhost:4000` (it also starts the `@clerk/ui` bundle server on `:4011`, a hard dependency). No secrets needed — a staging publishable key is baked into `packages/clerk-js/sandbox/template.html`, so Clerk auth components render and talk to a live staging instance out of the box. Routes: `/sign-in`, `/sign-up`, `/user-profile`, etc. The Mosaic explorer (`pnpm dev:swingset`, `http://localhost:6006`) is a secondary secret-free app.
+- Root `pnpm lint` currently exits non-zero on a clean checkout for reasons unrelated to environment setup: `scripts/lint.mjs` runs `turbo lint -- --quiet`, and `--quiet` gets appended to packages whose `lint` chains `typecheck` (e.g. `@clerk/headless` → `tsc --noEmit --quiet`), which TypeScript `6.0.3` rejects; there are also pre-existing eslint errors under `scripts/` and `integration/`. To lint a package's tooling cleanly, use `pnpm turbo lint --filter=<pkg>` (no `--quiet`).
+- `pnpm test:integration:*` (Playwright E2E) needs 1Password-sourced `INTEGRATION_INSTANCE_KEYS` and live Clerk instances; it cannot run in this environment without those secrets. Unit tests (`pnpm test`, or `pnpm turbo test --filter=<pkg>`) run fully offline.