diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 000000000..8c645fb24
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,49 @@
+# AGENTS.md
+
+## Cursor Cloud specific instructions
+
+Rivet is the `@ironclad/rivet` monorepo: a visual, node-based IDE for building AI
+agents / prompt chains. It ships as a Tauri (Rust + React/Vite) desktop app plus
+supporting TypeScript libraries. It is a **Yarn 4 (PnP) monorepo** with workspaces
+under `packages/*` (`app`, `core`, `node`, `app-executor`, `cli`, `trivet`, `docs`,
+`community`). Standard commands live in the root `package.json` scripts and
+`CONTRIBUTING.md`; this section only records non-obvious caveats.
+
+### Toolchain / environment caveats
+- **Node 20 is required.** The repo pins `node@20.4.0` (Volta) and CI uses `20.4.x`.
+  The VM's default `node` on `PATH` (`/exec-daemon/node`) is Node 22 and shadows
+  nvm, so you must put Node 20 first on `PATH` before running any yarn command:
+  `export PATH="$HOME/.nvm/versions/node/v20.4.0/bin:$PATH"`. The startup update
+  script already installs Node 20 via nvm.
+- **`NPM_TOKEN` must be defined (even if empty).** `.yarnrc.yml` references
+  `${NPM_TOKEN}`, and every yarn invocation errors with
+  `Environment variable not found (NPM_TOKEN)` if it is unset. Export `NPM_TOKEN=""`
+  for install/build/test/lint against the public npm registry (a real token is only
+  needed for publishing).
+- Yarn is pinned to `4.8.1` via corepack (`corepack prepare yarn@4.8.1 --activate`),
+  despite some `packageManager`/Volta fields still saying `3.5.0`.
+- After install, run `yarn unplug tsx` (also done in CI) so `tsx` works under PnP ESM.
+
+### Running the app (dev)
+- **Browser / Vite mode (recommended in headless cloud):**
+  `yarn workspace @alpic80/rivet-app run start` serves the full IDE at
+  `http://localhost:5173` with **no Rust/Tauri needed**. `core` and `trivet` are
+  aliased to their source in `packages/app/vite.config.ts`, so you do NOT need to
+  prebuild them for app dev. This is the fastest way to exercise the core product
+  (add nodes, edit them, run a graph).
+- **Desktop / Tauri mode:** root `yarn dev` builds the `app-executor` sidecar then
+  runs `tauri dev`. This requires a Rust toolchain plus Linux GTK/WebKit system libs
+  (`libgtk-3-dev`, `libwebkit2gtk-4.0-dev`, `libappindicator3-dev`, `librsvg2-dev`)
+  and a display, so it is not suitable for a headless VM. Browser mode covers the
+  core node-editor functionality without it.
+- Tauri-only features (native filesystem, the Node Executor sidecar, auto-update,
+  global shortcuts) are gated behind `isInTauri()` and are simply unavailable in
+  browser mode — that is expected, not a bug.
+
+### Lint / test / build
+- `yarn test` runs only `@alpic80/rivet-core` tests (Node's built-in test runner).
+- `yarn lint` runs ESLint across all packages; it currently passes with warnings
+  only (import-cycle and `react-hooks/exhaustive-deps` warnings are pre-existing).
+- `yarn build` builds every package including the Vite production bundle; it needs
+  more heap: `NODE_OPTIONS=--max_old_space_size=6000` (as in CI).
+- There are no git pre-commit/pre-push hooks; lint/prettier only run in CI.