diff --git a/AGENTS.md b/AGENTS.md
index 51fb34f..f212607 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -890,3 +890,34 @@ Forager is a well-architected media management system with:
 - Migration-based schema evolution
 
 When working on this codebase, prioritize type safety, follow established patterns, write tests, and maintain the clean separation of concerns across layers.
+
+## Cursor Cloud specific instructions
+
+### Environment
+
+- **Deno stable** (not canary) must be used for the web package build. Deno canary has a regression where bare specifiers (e.g. `import 'zimmerframe'` inside `svelte/src/compiler/index.js`) are resolved as relative paths during vite's config evaluation, causing `Unable to load .../svelte/compiler` errors. The root cause: when vite loads vite.config.ts, it evaluates `@sveltejs/kit`'s `import_peer('svelte/compiler')` which loads `node_modules/svelte/src/compiler/index.js`; that file's `import 'zimmerframe'` is then incorrectly resolved as `./zimmerframe` instead of using Node module resolution. `nodeModulesDir: "manual"` + `npm install` does NOT fix this because the issue is in Deno canary's module loader (not the node_modules layout). Use Deno stable 2.7.x.
+- **FFmpeg** is pre-installed at `/usr/bin/ffmpeg` and `/usr/bin/ffprobe`.
+- **No external services** are needed — the database is embedded SQLite and the web server is built into the CLI.
+
+### Running services
+
+- **GUI server**: `deno task --cwd packages/cli develop --config <config_path> gui` starts the web UI on `127.0.0.1:8000`. Requires a YAML config file (see AGENTS.md main section for schema). A minimal config needs `core.database.folder`, `core.database.filename`, `core.thumbnails.folder`, `core.migrations.automatic: true`, and `web.port`.
+- **Dev mode** (with HMR): `deno task develop` first builds the web package then starts the CLI GUI. This is the recommended dev workflow.
+
+### Key commands
+
+| Task | Command |
+|------|---------|
+| Lint (core) | `deno task --cwd packages/core lint` |
+| Test (core) | `deno task --cwd packages/core test` |
+| Test (CLI) | `deno task --cwd packages/cli test` (requires web build first) |
+| Build (web) | `deno task --cwd packages/web build` or `build:local` |
+| Dev (web HMR) | `deno task --cwd packages/web dev` (vite dev on port 5173) |
+| Format | `deno fmt` |
+| Full dev | `deno task develop` |
+
+### Known test quirks
+
+- Core tests have 4 failures related to FFmpeg version-specific floating-point precision (duration values differ slightly from expected). These are not code bugs.
+- CLI tests require the web package to be built first (`deno task --cwd packages/web build`).
+- The `--env-file=../../.env` warning from CLI develop tasks is harmless if no `.env` file exists.