chore(dev): Support Claude Code cloud (remote) sessions

.claude/CLOUD.md

@@ -0,0 +1,27 @@
+# Running this repo in Claude Code cloud (remote sessions)
+
+Most of the setup is committed to the repo and works automatically:
+
+- **`scripts/claude-cloud-setup.sh`** — bootstrap: `yarn install --frozen-lockfile` + `yarn build:dev`. Runs **every** session so the checkout is always built against the current branch. Repeated runs are cheap (frozen install is a no-op when warm; Nx only rebuilds changed packages).
+- **`.claude/settings.json`** — a `SessionStart` hook runs that script, but only in cloud sessions (`CLAUDE_CODE_REMOTE=true`). Local sessions are unaffected.
+
+## One-time environment setup (done in the `claude.ai/code` UI)
+
+These cannot live in the repo and must be set once per environment:
+
+1. **Setup script** — install the language runtime the sandbox lacks, e.g.:
+
+   ```bash
+   bash scripts/claude-cloud-setup.sh
+   ```
+
+   Do not rely on the cached result for freshness: install + build re-run on every session via the SessionStart hook, because the working branch changes constantly. This runs the same script mostly to warm the caches (node_modules, Nx) so the first real session is fast.
+
+2. **Network access:** `Trusted` (default) is sufficient — it already allows the npm registry and GitHub, which is all the install needs.
+
+3. **Environment variables:** none required for build/test. Add any Sentry DSNs or tokens here only if you intend to run E2E/integration suites that need them (visible to anyone who can edit the environment — do not put long-lived secrets here).
+
+## Notes
+
+- Node/Yarn versions come from `package.json` (Volta locally). In the cloud we use the sandbox runtime and pass `--ignore-engines`, matching CI.
+- The full production `yarn build` is not run at startup; `build:dev` (transpile + types) is enough for editing and running unit tests. Run `yarn build` manually if you need bundles.

.claude/settings.json

@@ -1,5 +1,18 @@
 {
   "env": { "ENABLE_LSP_TOOL": "1" },
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "if [ \"$CLAUDE_CODE_REMOTE\" = \"true\" ]; then bash \"$CLAUDE_PROJECT_DIR\"/scripts/claude-cloud-setup.sh; fi"
+          }
+        ]
+      }
+    ]
+  },
   "permissions": {
     "allow": [
       "Bash(find:*)",

scripts/claude-cloud-setup.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+#
+# Bootstrap the Sentry JavaScript monorepo for a Claude Code cloud session.
+#
+# Wired as the repo's SessionStart hook (see .claude/settings.json), gated to
+# cloud sessions. It runs on every session so the checkout is always installed
+# and built against the *current* branch -- the code changes constantly, so a
+# build cached at environment-creation time would be stale. Repeated runs are
+# cheap: a frozen-lockfile install is a no-op when node_modules is warm, and Nx
+# only rebuilds packages whose inputs actually changed.
+#
+# Node/Yarn versions come from `package.json` (managed by Volta locally); in the
+# cloud we rely on whatever runtime the sandbox provides and pass --ignore-engines
+# to match CI (.github/actions/install-dependencies).
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+# Required by the repo's package-manager setup (some workspaces use pnpm via Volta).
+export VOLTA_FEATURE_PNPM=1
+
+echo "node: $(node --version 2>/dev/null || echo 'not found')"
+echo "yarn: $(yarn --version 2>/dev/null || echo 'not found')"
+
+echo "Installing dependencies (yarn install --frozen-lockfile)..."
+yarn install --ignore-engines --frozen-lockfile
+
+echo "Building packages (yarn build:dev)..."
+yarn build:dev
+
+echo "Cloud setup complete."