diff --git a/AGENTS.md b/AGENTS.md
index 8ebac930..fcf830d6 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -119,3 +119,29 @@ Each command extends `Command` from `@/lib/commands/base-command` and implements
 - `undo()` - restores the saved state
 
 Actions and commands work together: actions are "what triggered this", commands are "how to do it (and undo it)".
+
+## Cloud-specific instructions
+
+### Prerequisites
+
+- **Bun** (v1.2.18) must be installed. The update script handles this via `~/.bun/bin/bun`.
+- **No Docker required** for frontend-only development. Docker (PostgreSQL + Redis) is only needed for auth features, and no `docker-compose.yaml` exists in the repo yet.
+
+### Environment variables
+
+All env vars are validated by Zod at startup (`packages/env/src/web.ts`). Every field is required (no `.optional()`), so `.env.local` must exist under `apps/web/` with valid-looking values for all variables. For local development without external services, placeholder values work for: `MARBLE_WORKSPACE_KEY`, `FREESOUND_CLIENT_ID`, `FREESOUND_API_KEY`, `CLOUDFLARE_ACCOUNT_ID`, `R2_*`, and `MODAL_TRANSCRIPTION_URL` (must be a valid URL like `http://localhost:9999/transcription`).
+
+### Running services
+
+| Service | Command | Notes |
+|---------|---------|-------|
+| Dev server | `bun run dev` (from `apps/web`) | Runs Next.js 16 with Turbopack on port 3000 |
+| Lint | `bun run lint` (from `apps/web`) | Uses Biome. Pre-existing CSS/Tailwind directive warnings are expected. |
+| Tests | `bun test` (from repo root) | 60 tests across 7 files (storage migrations + sticker-id) |
+| Format | `bun run format` (from `apps/web`) | Biome formatter |
+
+### Gotchas
+
+- `@biomejs/biome` is a root devDependency needed for the lint/format scripts in `apps/web`. The lint script calls `biome` directly.
+- The env schema at `packages/env/src/web.ts` uses `z.url()` for several fields (`NEXT_PUBLIC_SITE_URL`, `NEXT_PUBLIC_MARBLE_API_URL`, `UPSTASH_REDIS_REST_URL`, `MODAL_TRANSCRIPTION_URL`), meaning they must be full valid URLs (with protocol). Plain strings will fail validation.
+- The repo's README references `docker-compose up -d` but no `docker-compose.yaml` exists. Auth features (login, signup) won't work without PostgreSQL and Redis.