Add cloud-specific instructions to AGENTS.md

Co-authored-by: Maze <mazeincoding@users.noreply.github.com>

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.

bun.lock

@@ -10,6 +10,7 @@
         "next": "^16.1.3",
       },
       "devDependencies": {
+        "@biomejs/biome": "^2.4.4",
         "turbo": "^2.7.5",
         "typescript": "5.8.3",
       },
@@ -152,6 +153,24 @@
 
     "@better-fetch/fetch": ["@better-fetch/fetch@1.1.21", "", {}, "sha512-/ImESw0sskqlVR94jB+5+Pxjf+xBwDZF/N5+y2/q4EqD7IARUTSpPfIo8uf39SYpCxyOCtbyYpUrZ3F/k0zT4A=="],
 
+    "@biomejs/biome": ["@biomejs/biome@2.4.4", "", { "optionalDependencies": { "@biomejs/cli-darwin-arm64": "2.4.4", "@biomejs/cli-darwin-x64": "2.4.4", "@biomejs/cli-linux-arm64": "2.4.4", "@biomejs/cli-linux-arm64-musl": "2.4.4", "@biomejs/cli-linux-x64": "2.4.4", "@biomejs/cli-linux-x64-musl": "2.4.4", "@biomejs/cli-win32-arm64": "2.4.4", "@biomejs/cli-win32-x64": "2.4.4" }, "bin": { "biome": "bin/biome" } }, "sha512-tigwWS5KfJf0cABVd52NVaXyAVv4qpUXOWJ1rxFL8xF1RVoeS2q/LK+FHgYoKMclJCuRoCWAPy1IXaN9/mS61Q=="],
+
+    "@biomejs/cli-darwin-arm64": ["@biomejs/cli-darwin-arm64@2.4.4", "", { "os": "darwin", "cpu": "arm64" }, "sha512-jZ+Xc6qvD6tTH5jM6eKX44dcbyNqJHssfl2nnwT6vma6B1sj7ZLTGIk6N5QwVBs5xGN52r3trk5fgd3sQ9We9A=="],
+
+    "@biomejs/cli-darwin-x64": ["@biomejs/cli-darwin-x64@2.4.4", "", { "os": "darwin", "cpu": "x64" }, "sha512-Dh1a/+W+SUCXhEdL7TiX3ArPTFCQKJTI1mGncZNWfO+6suk+gYA4lNyJcBB+pwvF49uw0pEbUS49BgYOY4hzUg=="],
+
+    "@biomejs/cli-linux-arm64": ["@biomejs/cli-linux-arm64@2.4.4", "", { "os": "linux", "cpu": "arm64" }, "sha512-V/NFfbWhsUU6w+m5WYbBenlEAz8eYnSqRMDMAW3K+3v0tYVkNyZn8VU0XPxk/lOqNXLSCCrV7FmV/u3SjCBShg=="],
+
+    "@biomejs/cli-linux-arm64-musl": ["@biomejs/cli-linux-arm64-musl@2.4.4", "", { "os": "linux", "cpu": "arm64" }, "sha512-+sPAXq3bxmFwhVFJnSwkSF5Rw2ZAJMH3MF6C9IveAEOdSpgajPhoQhbbAK12SehN9j2QrHpk4J/cHsa/HqWaYQ=="],
+
+    "@biomejs/cli-linux-x64": ["@biomejs/cli-linux-x64@2.4.4", "", { "os": "linux", "cpu": "x64" }, "sha512-R4+ZCDtG9kHArasyBO+UBD6jr/FcFCTH8QkNTOCu0pRJzCWyWC4EtZa2AmUZB5h3e0jD7bRV2KvrENcf8rndBg=="],
+
+    "@biomejs/cli-linux-x64-musl": ["@biomejs/cli-linux-x64-musl@2.4.4", "", { "os": "linux", "cpu": "x64" }, "sha512-gGvFTGpOIQDb5CQ2VC0n9Z2UEqlP46c4aNgHmAMytYieTGEcfqhfCFnhs6xjt0S3igE6q5GLuIXtdQt3Izok+g=="],
+
+    "@biomejs/cli-win32-arm64": ["@biomejs/cli-win32-arm64@2.4.4", "", { "os": "win32", "cpu": "arm64" }, "sha512-trzCqM7x+Gn832zZHgr28JoYagQNX4CZkUZhMUac2YxvvyDRLJDrb5m9IA7CaZLlX6lTQmADVfLEKP1et1Ma4Q=="],
+
+    "@biomejs/cli-win32-x64": ["@biomejs/cli-win32-x64@2.4.4", "", { "os": "win32", "cpu": "x64" }, "sha512-gnOHKVPFAAPrpoPt2t+Q6FZ7RPry/FDV3GcpU53P3PtLNnQjBmKyN2Vh/JtqXet+H4pme8CC76rScwdjDcT1/A=="],
+
     "@drizzle-team/brocli": ["@drizzle-team/brocli@0.10.2", "", {}, "sha512-z33Il7l5dKjUgGULTqBsQBQwckHh5AbIuxhdsIxDDiZAzBOrZO6q9ogcWC65kU382AfynTfgNumVcNIjuIua6w=="],
 
     "@emnapi/runtime": ["@emnapi/runtime@1.8.1", "", { "dependencies": { "tslib": "^2.4.0" } }, "sha512-mehfKSMWjjNol8659Z8KxEMrdSJDDot5SXMq00dM8BN4o+CLNXQ0xH2V7EchNHV4RmbZLmmPdEaXZc5H2FXmDg=="],

package.json

@@ -24,6 +24,7 @@
 		"next": "^16.1.3"
 	},
 	"devDependencies": {
+		"@biomejs/biome": "^2.4.4",
 		"turbo": "^2.7.5",
 		"typescript": "5.8.3"
 	},