[pull] main from liveblocks:main

AGENTS.md

@@ -92,3 +92,63 @@ changes to them directly here — prefer editing the source in the backend repo.
 
 - `packages/liveblocks-server`
 - `tools/liveblocks-cli`
+
+# Cursor Cloud specific instructions
+
+## When you do NOT need to build/run anything
+
+Many tasks require no build, dev server, or running app. Editing `docs/`,
+`examples/`, `tutorial/`, `guides/`, and `starter-kits/` (all outside the pnpm
+workspace and depending on _published_ packages) does not require building the
+local packages or starting a dev server. Skip that setup for those tasks.
+
+## Toolchain
+
+- Node `>=24` is required and enforced (`engineStrict: true`). The environment
+  installs Node 24 via `nvm` and pins it in `~/.bashrc`; the default
+  `/exec-daemon/node` is an older Node that fails `pnpm install`. If a shell
+  shows the wrong version, run `nvm use 24.14.1`.
+- `pnpm` comes from `corepack` (pinned via `packageManager`).
+- `bun` is installed (on `PATH` via `~/.bashrc`). It is required by the local
+  Liveblocks dev server and by `@liveblocks/react`'s `lint:package`
+  (`scripts/check-exports.ts`).
+- Standard build/test/lint commands are documented above (use `pnpm exec turbo`).
+
+## Local Liveblocks dev server (backend for tests and e2e apps)
+
+There is no Liveblocks backend in this repo; everything talks to a Liveblocks
+server. Prefer the local dev server (per the guidance above) over cloud keys.
+It is provided by the `liveblocks` CLI and runs on Bun — no Docker needed:
+
+    pnpm dlx liveblocks dev --port 1153          # persistent server
+    pnpm dlx liveblocks dev -P -c '<command>'    # one-off server for a command (random port)
+
+Health check: `curl localhost:1153/health` → `200`. It accepts the local keys
+`pk_localdev` (public) and `sk_localdev` (secret). The package `test` scripts
+already wrap Vitest with `liveblocks dev` (e.g. `@liveblocks/core`), so
+`*.devserver.test.ts` suites get a fresh server automatically. `*.mockserver.test.ts`
+suites need no server at all.
+
+Note: the `*.devserver.test.ts` suites read `LIVEBLOCKS_DEV_SERVER_PORT` (the
+`-P` flag injects it); don't hardcode a port when running them yourself.
+
+## Running an e2e app
+
+Each `e2e/` app reads env from its own `.env.local` (git-ignored). For the local
+dev server use:
+
+    LIVEBLOCKS_SECRET_KEY=sk_localdev
+    NEXT_PUBLIC_LIVEBLOCKS_PUBLIC_KEY=pk_localdev
+    NEXT_PUBLIC_LIVEBLOCKS_BASE_URL=http://localhost:1153
+
+Ports (`pnpm run dev`): next-sandbox `3007`, next-ai-kitchen-sink `3008`,
+next-react-flow-kitchen-sink `3008` (conflicts with ai-kitchen-sink — don't run
+both), next-feeds `3009`. `node-sandbox` has no dev server (Vitest only).
+
+Both public-key pages (`/auth/pubkey`) and access-token pages (`/presence`,
+`/api/auth/access-token` → `session.FULL_ACCESS` → `*:write` scope) work against
+the CLI dev server. (An older published `ghcr.io/liveblocks/dev-server:latest`
+Docker image rejected `*:write` with HTTP 422; the CLI server does not.)
+
+The e2e apps' _production_ `next build` collects page data and fails without a
+reachable server/keys; that's expected — use `pnpm run dev` for development.