diff --git a/.agents/skills/testing-livepeer-fal-deploy/SKILL.md b/.agents/skills/testing-livepeer-fal-deploy/SKILL.md
new file mode 100644
index 000000000..e9aec715f
--- /dev/null
+++ b/.agents/skills/testing-livepeer-fal-deploy/SKILL.md
@@ -0,0 +1,327 @@
+---
+name: testing-livepeer-fal-deploy
+description: End-to-end test harness for Scope's Livepeer cloud path against a deployed fal.ai app — the only supported cloud path going forward (the old cloud-relay / direct mode using `fal_app.py` + `CloudConnectionManager` is being deprecated). Primary path is a Playwright browser test that drives the full UI flow (camera → local scope WebRTC → livepeer trickle → fal runner → back), producing every session-lifecycle Kafka event. Secondary path is `test-cloud-connect.sh` — a bash/curl smoke test for the `/api/v1/cloud/connect` path only. Has two modes: "deploy then test" (default — runs `deploy-staging.sh` first) and "test existing deploy" (skips deploy, points at whatever is already live, e.g. `scope-livepeer--prod`). TRIGGER any time a user says "test cloud", "test the fal deploy", "test cloud streaming", "run the e2e test", "run playwright", "verify cloud connect", "verify kafka events", "diagnose fal", "debug fal deploy", "did my stream work", "deploy-staging.sh", "test against prod", "test prod cloud", "test the prod deploy", "don't deploy", "skip deploy", "no deploy", "target the existing deploy", "target prod", "scope-livepeer--prod", OR pastes any of these errors — "All orchestrators failed (N tried)", "ACCESS_DENIED", "did not receive ready message from websocket", "discover_orchestrators requires discovery_url", "cold start" — OR has just changed `src/scope/cloud/livepeer_fal_app.py` / `src/scope/cloud/livepeer_app.py` / `src/scope/server/livepeer.py` / `src/scope/server/livepeer_client.py`. Use `testing-livepeer` instead for a fully-local livepeer stack (prebuilt go-livepeer binary, no fal involvement).
+---
+
+# Testing Livepeer fal Deploy
+
+## When to use
+
+Use when testing the **deployed** livepeer path end-to-end — local Scope
+client → daydream orchestrator → deployed fal app. This exercises:
+
+- The wrapper in `src/scope/cloud/livepeer_fal_app.py` that fal runs
+- The runner in `src/scope/cloud/livepeer_app.py` that spawns inside the
+  fal container
+- The orchestrator → fal handshake (headers, auth, cold start)
+- Kafka event publishing across wrapper + runner (full lifecycle)
+
+**Two paths, pick the right one:**
+
+- **Playwright (primary)** — real browser drives the Perform-mode UI
+  with a synthetic camera, streams through, verifies the output video
+  comes back from the cloud. This is the only path that exercises the
+  full livepeer trickle round-trip and produces every lifecycle Kafka
+  event (`pipeline_loaded`, `session_created`, `stream_started`,
+  `stream_heartbeat`, `session_closed`). Takes 2–5 minutes.
+- **`test-cloud-connect.sh` (secondary, HTTP-only)** — bash script that
+  POSTs `/api/v1/cloud/connect` and polls `/api/v1/cloud/status`. Only
+  verifies the `websocket_connected` / `websocket_disconnected` pair at
+  the wrapper layer. Useful as a fast smoke test ("did the container
+  come up?") or in `git bisect run` against cloud-connect regressions.
+  Does not produce pipeline/session/stream events.
+
+Do **not** use this skill for local-only livepeer testing — that's
+`testing-livepeer` (prebuilt go-livepeer + local runner, no fal).
+
+## One-time setup
+
+1. **`.env.local`**: copy `.env.example` to `.env.local` (gitignored)
+   and fill in real values:
+   - `SCOPE_CLOUD_APP_ID` — your fal app URL. For the default `main`
+     env, the URL does **not** include a `--main` suffix (e.g.
+     `daydream/scope-livepeer-emran/ws`). Non-default envs do include
+     the suffix (e.g. `--preview/ws`).
+   - `SCOPE_CLOUD_API_KEY` — daydream cloud API key (sk_...). Without
+     this the scope client can't hit `signer.daydream.live` and fails
+     with `discover_orchestrators requires discovery_url or signer_url`.
+   - `SCOPE_USER_ID` — daydream user id. The runner's
+     `validate_user_access` rejects with `ACCESS_DENIED` when missing.
+     Find it in `~/.daydream-scope/logs/scope-logs-*.log` after a
+     successful UI connect, or in devtools Network on
+     `/api/v1/cloud/connect`.
+   - (Optional) `LIVEPEER_DEBUG=1` — surfaces per-orchestrator
+     rejection reasons in scope.log; essential for diagnosing
+     `All orchestrators failed (N tried)`.
+2. **Frontend rebuild with baked-in auth** (once per local workspace):
+   ```bash
+   source .env.local
+   cd frontend && VITE_DAYDREAM_API_KEY="$SCOPE_CLOUD_API_KEY" npm run build
+   cd ..
+   ```
+   This bakes the API key into the dist bundle so the app appears
+   signed-in (otherwise Playwright hits the login screen).
+3. **Playwright setup** (once per machine):
+   ```bash
+   cd e2e
+   npm install
+   npx playwright install chromium
+   ```
+   Then install Chromium's system deps (sudo required — one-time):
+   ```bash
+   sudo apt-get install -y libnss3 libnspr4 libasound2t64
+   # or the Playwright-managed superset:
+   sudo npx playwright install-deps chromium
+   ```
+   Without these the browser fails to launch with
+   `error while loading shared libraries: libnspr4.so`.
+
+## Running the Playwright test (primary)
+
+There are two modes. Pick by what the user said:
+
+- **Deploy-then-test (default)** — user said "test cloud" / "test the
+  fal deploy" / changed cloud code and wants to verify it. Run all
+  steps below including Step 3 (deploy).
+- **Test-existing-deploy (no deploy)** — user said "test against
+  prod", "don't deploy", "no deploy", "target the existing deploy",
+  "scope-livepeer--prod", or otherwise made clear they want to test
+  whatever is *already live*. **Skip Step 3 entirely.** See
+  ["Variant: target an existing deploy"](#variant-target-an-existing-deploy-no-deploy)
+  below before running.
+
+When the user says "test cloud" (or any trigger in the description)
+without indicating they want to skip deploy, **always deploy their
+current working tree before running Playwright**. Otherwise the test
+runs against whatever stale code was last deployed and can
+false-positive on their change.
+
+### Step 0 — Ask the user where to deploy
+
+Before anything else, confirm the deploy target. Use AskUserQuestion
+(or plain text prompts) and persist answers for the session:
+
+1. **Fal app name** — required. If `SCOPE_FAL_APP_NAME` is set in
+   `.env.local`, show that value and ask the user to confirm or
+   override. Otherwise ask outright (e.g. `scope-livepeer-<name>`).
+2. **Fal env** — defaults to `main`. If `SCOPE_FAL_ENV` is set in
+   `.env.local`, show and offer to override. Non-default envs (e.g.
+   `preview`) change the URL suffix in `SCOPE_CLOUD_APP_ID` — see
+   below.
+
+Once confirmed, export both for the current shell, and derive /
+overwrite `SCOPE_CLOUD_APP_ID`:
+
+| Env | `SCOPE_CLOUD_APP_ID` |
+|---|---|
+| `main` | `daydream/<app>/ws`         (no suffix) |
+| anything else | `daydream/<app>--<env>/ws`  (with suffix) |
+
+This is a fal convention — the default `main` env is exposed without
+a suffix; all other envs include `--<env>` in the URL. Getting this
+wrong produces `did not receive ready message from websocket`.
+
+### Step 1 — Sanity-check `.env.local`
+
+- `SCOPE_CLOUD_API_KEY` must be set (otherwise:
+  `discover_orchestrators requires discovery_url or signer_url`)
+- `SCOPE_USER_ID` must be set (otherwise the runner's
+  `validate_user_access` rejects with `ACCESS_DENIED`)
+
+If either is missing, stop and ask the user before deploying.
+
+### Step 2 — Kill any scope already on :8000
+
+If another scope process is bound to the port, stop it (or ask the
+user) before continuing. The run-app.sh the script starts must be the
+one under test.
+
+### Step 3 — Deploy
+
+```bash
+SCOPE_FAL_APP_NAME=<app> SCOPE_FAL_ENV=<env> ./deploy-staging.sh
+```
+
+Abort with a clear error if this fails — don't run Playwright against
+stale deployed code. Common failure: the `{git-short-sha}-cloud`
+Docker base image isn't built yet (CI for the current commit is still
+running). If that's the case, either wait for CI or have the user
+confirm they want to deploy against an older base image.
+
+### Step 4 — Start scope and run Playwright
+
+```bash
+# Terminal 1 — scope (port 8000)
+SCOPE_CLOUD_APP_ID=<derived-url> ./run-app.sh
+
+# Terminal 2 — test
+cd e2e && npx playwright test
+```
+
+Expected on success (≤5 min cold, ~20 s warm):
+
+```
+Enabling cloud mode...          ✅
+Waiting for cloud connection... ✅
+Selecting passthrough model...  ✅
+Switching input source to Camera... ✅
+Starting stream...              ✅
+Verifying output stream processing... ✅ Output frames flowing
+Stopping stream...              ✅
+1 passed
+```
+
+**What the test does in livepeer terms:**
+
+1. Navigates to `localhost:8000`, switches the UI to Perform mode.
+2. Opens settings, flips Remote Inference on, waits for Connection ID
+   (proves the fal WebSocket handshake completed and
+   `websocket_connected` fired in Kafka).
+3. Selects the `passthrough` pipeline — triggers `pipeline/load`, which
+   runs on the fal runner and emits `pipeline_load_start` +
+   `pipeline_loaded`.
+4. Switches the input source to Camera — Playwright's launch args
+   `--use-fake-device-for-media-stream` and
+   `--use-fake-ui-for-media-stream` (configured in
+   `e2e/playwright.config.ts`) give `getUserMedia()` a synthetic feed.
+   This is essential: without a real MediaStream, the browser↔local
+   scope WebRTC ICE never completes, `CloudTrack._start()` is never
+   called, and the runner never gets `start_stream`.
+5. Clicks the play overlay (`[data-testid="start-stream-button"]`).
+   Frames flow via livepeer trickle through the orchestrator to the
+   fal runner; the runner emits `session_created` and `stream_started`.
+6. Waits 15 s so at least one `stream_heartbeat` fires on the runner.
+7. Asserts the **output** `<video>` inside the "Video Output" card is
+   actively playing (`currentTime > 0`). Checking any `<video>` would
+   false-positive on the local input preview.
+8. Stops the stream. Runner emits `session_closed` and eventually
+   `websocket_disconnected` when the session is reaped.
+
+### Variant: target an existing deploy (no deploy)
+
+Use this when the user has made clear they do **not** want to deploy
+— typical phrasings: "test against prod", "don't deploy", "no
+deploy", "target the existing deploy", "test scope-livepeer--prod",
+"verify prod cloud". The point is to exercise whatever is already
+live (most often the prod fal app), not the user's working tree.
+
+**Run order — Step 3 is omitted:**
+
+1. Sanity-check `.env.local` (same as Step 1 above):
+   `SCOPE_CLOUD_API_KEY` and `SCOPE_USER_ID` must be set.
+2. Free port :8000 (same as Step 2 above).
+3. *(Skipped — do NOT run `deploy-staging.sh`.)*
+4. Start scope pointed at the existing deploy, then run Playwright:
+
+   ```bash
+   # Terminal 1 — scope (port 8000), pointed at the live app
+   SCOPE_CLOUD_APP_ID=daydream/<app>--<env>/ws ./run-app.sh
+
+   # Terminal 2 — test
+   cd e2e && npx playwright test
+   ```
+
+**Deriving `SCOPE_CLOUD_APP_ID` for common targets:**
+
+| Target | `SCOPE_FAL_APP_NAME` | `SCOPE_FAL_ENV` | `SCOPE_CLOUD_APP_ID` |
+|---|---|---|---|
+| prod | `scope-livepeer` | `prod` | `daydream/scope-livepeer--prod/ws` |
+| preview | `scope-livepeer` | `preview` | `daydream/scope-livepeer--preview/ws` |
+| main (default env) | `scope-livepeer` | `main` | `daydream/scope-livepeer/ws` (no suffix) |
+
+Same fal env-suffix rule as the deploy path: `main` has no suffix, all
+other envs include `--<env>`.
+
+**Before running, surface this caveat to the user:**
+
+> Heads up — this run tests whatever code is currently deployed to
+> `<app>--<env>`, not your local working tree. A green run is not
+> evidence your local diff works.
+
+Everything else (success output, the 8-step "what the test does"
+explanation, common failure signatures) is identical to the
+deploy-then-test mode.
+
+## Running the quick HTTP smoke (secondary)
+
+```bash
+./test-cloud-connect.sh [flags]
+```
+
+Flags: `--skip-push`, `--skip-build-wait`, `--skip-deploy`,
+`--keep-scope`, `--port N`. Env overrides:
+`TIMEOUT_CONNECT`, `TIMEOUT_HEALTH`, `TIMEOUT_CI`, etc.
+
+Exit codes (bisect-friendly — `git bisect run` works):
+
+| Code | Meaning |
+|---|---|
+| 0 | Connected to cloud |
+| 1 | Cloud reported an `error` in `/cloud/status` |
+| 2 | Timed out waiting for connect |
+| 3 | Infra failure (push / CI / deploy / scope startup) |
+
+This only hits `POST /api/v1/cloud/connect` and polls status — it does
+**not** start a stream, load a pipeline on the cloud, or produce the
+session/stream events. If those are what you're after, use Playwright.
+
+A `--full-session` flag exists but hits a known gap: `/api/v1/session/start`
+is not livepeer-compatible (TODO at `src/scope/server/mcp_router.py:252`)
+and will error with `Pipeline X not loaded` in livepeer mode. The
+Playwright path is the supported way to exercise a full session.
+
+## Logs
+
+- `/tmp/test-cloud-connect/scope.log` — local scope stdout/stderr
+  (grep for `livepeer_gateway` when `LIVEPEER_DEBUG=1`)
+- `~/.daydream-scope/logs/scope-logs-*.log` — scope's rolling app logs
+- `e2e/test-results/` — Playwright screenshots + traces on failure
+- fal dashboard — runner stdout/stderr, including `[Kafka] Published
+  event: …` lines from `scope.server.kafka_publisher` in the runner.
+  Not accessible via CLI; open <https://fal.ai/dashboard/logs>.
+
+## Common failure signatures
+
+- **`All orchestrators failed (N tried)`** — set `LIVEPEER_DEBUG=1` to
+  get the per-orchestrator reason. Typical root causes:
+  - `did not receive ready message from websocket` → fal URL wrong
+    (e.g. stray `--main` suffix) or container cold-starting.
+  - `serverless handshake failed (ACCESS_DENIED)` → runner's
+    `validate_user_access` rejected (missing `SCOPE_USER_ID`, or
+    daydream API couldn't find the user).
+- **`discover_orchestrators requires discovery_url or signer_url`** →
+  `SCOPE_CLOUD_API_KEY` not set; signer fallback isn't configured.
+- **Playwright: `error while loading shared libraries: libnspr4.so`** →
+  Chromium system deps missing; run the `sudo apt-get install`
+  command from setup.
+- **Playwright: test passes but ClickHouse only has
+  `websocket_connected`** — the test probably clicked stop before ICE
+  completed. Confirm the fake-device launch args are set and the
+  Camera input was selected (not File).
+- **Playwright: `FrameProcessor failed to start: Pipeline X not
+  loaded`** — you're running the HTTP script's `--full-session` flag,
+  not the Playwright test. Switch to `npx playwright test`.
+
+## What "round-trip verified" looks like in ClickHouse
+
+After a successful Playwright run, `scope_cloud_events` filtered by
+your `user_id` and the `connection_id` from the `websocket_connected`
+row should contain:
+
+```
+websocket_connected          (wrapper)
+pipeline_load_start          (runner)
+pipeline_loaded              (runner)
+session_created              (runner)
+stream_started               (runner)
+stream_heartbeat × 1..N      (runner, ~every 10 s)
+stream_stopped               (runner)
+session_closed               (runner)
+websocket_disconnected       (wrapper, on session reap)
+```
+
+All sharing the same `user_id` and `connection_id` (= `manifest_id`).
+If any runner-emitted row is missing, something in
+`src/scope/cloud/livepeer_app.py` regressed — check the FrameProcessor
+construction around the `start_stream` handler and the explicit
+`publish_event` calls for `session_created` / `session_closed`.
diff --git a/.env.example b/.env.example
new file mode 100644
index 000000000..2015e5d54
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,40 @@
+# Copy this file to `.env.local` (gitignored) and fill in real values.
+# Used by run-app.sh, deploy-staging.sh, and test-cloud-connect.sh.
+
+# --- Client-side (the local scope process) ---
+
+# Required — fal app URL for your livepeer deployment.
+# Format: daydream/<app-name>/ws  (no --main suffix for the default env;
+# for non-default envs the URL includes the env, e.g. --preview/ws).
+# This MUST match SCOPE_FAL_APP_NAME + SCOPE_FAL_ENV below — the skill
+# derives it for you when it asks which app + env to test against.
+export SCOPE_CLOUD_APP_ID=daydream/<your-app>/ws
+
+# Required — daydream cloud API key (used to auth with signer.daydream.live).
+export SCOPE_CLOUD_API_KEY=sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+
+# Required for the full automated test — your daydream user id.
+# Find it via the Scope UI cloud-connect request body, or in
+# ~/.daydream-scope/logs/scope-logs-*.log after a UI-driven connect.
+export SCOPE_USER_ID=user_xxxxxxxxxxxxxxxxxxxxxxxxx
+
+# --- Deploy-side (what deploy-staging.sh pushes to) ---
+
+# Optional default app name for deploy-staging.sh. If unset, the skill
+# asks the user. Example: scope-livepeer-<your-name>
+export SCOPE_FAL_APP_NAME=scope-livepeer-<your-name>
+
+# Optional default env for deploy-staging.sh. Defaults to "main". For
+# non-default envs remember that the URL in SCOPE_CLOUD_APP_ID includes
+# a --<env> suffix (e.g. "daydream/scope-livepeer-foo--preview/ws").
+# export SCOPE_FAL_ENV=main
+
+# Optional — auth mode for the fal deploy. Defaults to "public".
+# export SCOPE_FAL_AUTH=public
+
+# --- Optional ---
+
+# Enable DEBUG logs from livepeer_gateway so per-orchestrator rejection
+# reasons appear in scope.log (e.g. "ACCESS_DENIED", "did not receive
+# ready message from websocket").
+# export LIVEPEER_DEBUG=1
diff --git a/CLAUDE.md b/CLAUDE.md
index 517acb259..b86223ceb 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -90,7 +90,111 @@ This documentation can be used to understand the architecture of the project:
 
 ## Local Cloud Testing
 
+<<<<<<< HEAD
 For local Livepeer cloud testing, follow `.agents/skills/testing-livepeer/SKILL.md`.
+=======
+> **DEPRECATED.** This section describes the old direct/cloud-relay
+> mode (`SCOPE_CLOUD_MODE=direct`, `fal_app.py`,
+> `CloudConnectionManager`) which is being removed. For all new
+> cloud testing, use the `testing-livepeer-fal-deploy` skill (see the
+> "Cloud testing — use this skill" section above). This section is
+> kept only for in-flight work on the legacy path.
+
+Test the cloud relay flow locally by running two Scope instances — one acting as the "cloud" relay server.
+
+**Environment variables:**
+
+- `SCOPE_CLOUD_WS=1` — enables the `/ws` WebSocket endpoint on a Scope instance, making it act as a cloud relay server
+- `SCOPE_CLOUD_WS_URL` — overrides the cloud WebSocket URL so the connecting instance points to your local "cloud" instead of fal.ai
+- `SCOPE_CLOUD_APP_ID` — any non-empty value (e.g., `local`) to satisfy the app ID requirement
+
+**Setup (two terminals):**
+
+```bash
+# Terminal 1 — "cloud" instance (relay server):
+SCOPE_CLOUD_WS=1 uv run daydream-scope --port 8002
+
+# Terminal 2 — "local" instance (connects to cloud):
+SCOPE_CLOUD_WS_URL=ws://localhost:8002/ws SCOPE_CLOUD_APP_ID=local uv run daydream-scope --port 8022
+```
+
+Open <http://localhost:8022>, connect to cloud from the UI, load a pipeline, and start streaming. The local instance connects via WebSocket to the "cloud" instance on port 8002, which proxies WebRTC signaling and API requests back to itself.
+
+**Key files:**
+
+- `cloud/dev_app.py` — development-only WebSocket handler mimicking the fal.ai cloud protocol
+- `server/cloud_connection.py` — client-side connection manager (`SCOPE_CLOUD_WS_URL` override in `_build_ws_url()`)
+- `server/mcp_router.py` — headless session endpoints and cloud output wiring (`_wire_cloud_outputs`)
+- `server/cloud_webrtc_client.py` — WebRTC client that sends frames to cloud and receives output
+- `server/cloud_relay.py` — frame relay between FrameProcessor and cloud WebRTC
+- `server/headless.py` — HeadlessSession with frame consumer and per-sink frame capture
+- `server/sink_manager.py` — per-sink queue routing and recording coordination
+- `server/graph_executor.py` — graph validation and pipeline wiring
+- `server/pipeline_manager.py` — pipeline loading and aliasing (node_id → pipeline_id mapping)
+
+**Cloud frame flow architecture (local cloud dev):**
+
+```
+Local (8022)                              Cloud (8002)
+─────────────                             ────────────
+SourceManager reads video files
+  → FrameProcessor._on_hardware_source_frame()
+  → CloudRelay.send_frame_to_source()
+  → CloudWebRTCClient.input_tracks[i]    → WebRTC track received
+     (WebRTC)                             → VideoProcessingTrack.recv()
+                                          → FrameProcessor.put_to_source()
+                                          → GraphExecutor processes pipeline(s)
+                                          → SinkOutputTrack(s) send output
+  CloudWebRTCClient receives tracks ←     ← WebRTC output tracks
+  output_handlers[0] = primary sink       (track 0: primary sink)
+  output_handlers[1..N] = extra sinks     (track 1+: extra sinks, record nodes)
+  _wire_cloud_outputs() routes to:
+    - sink_manager._sink_queues_by_node (per-sink queues)
+    - recording_coordinator queues (per-record-node)
+  HeadlessSession._consume_frames()
+    reads from per-sink queues → _last_frames_by_sink
+```
+>>>>>>> 48909aa6 (docs: route all "test cloud" prompts to the livepeer skill)
+
+## Cloud testing — use this skill
+
+**Livepeer cloud mode is the only supported cloud path going forward.**
+The older direct/cloud-relay mode (`fal_app.py` +
+`CloudConnectionManager` + `SCOPE_CLOUD_MODE=direct`) is being
+deprecated.
+
+**Whenever a user says "test cloud", "test the fal deploy", "verify
+cloud streaming", "run the e2e test", or pastes any cloud-connect
+error (`All orchestrators failed`, `ACCESS_DENIED`, `did not receive
+ready message`, `discover_orchestrators requires discovery_url`),
+route to the `testing-livepeer-fal-deploy` skill at
+`.agents/skills/testing-livepeer-fal-deploy/SKILL.md`.** Also
+route there for changes to `src/scope/cloud/livepeer_fal_app.py`,
+`src/scope/cloud/livepeer_app.py`, or the cloud-connect flow on the
+client side (`src/scope/server/livepeer.py`,
+`src/scope/server/livepeer_client.py`).
+
+The skill provides two paths:
+
+- **Playwright e2e test** (`e2e/tests/cloud-streaming.spec.ts`) —
+  primary. Drives the real Perform-mode UI with a synthetic camera
+  and verifies the full trickle round-trip. Produces every lifecycle
+  Kafka event (`websocket_connected`, `pipeline_loaded`,
+  `session_created`, `stream_started`, `stream_heartbeat`,
+  `session_closed`, `websocket_disconnected`).
+- **`test-cloud-connect.sh`** at the repo root — fast bash/curl smoke
+  test for `/api/v1/cloud/connect` only. Useful in `git bisect run`
+  or for "did the fal container come up?". Does not produce
+  pipeline/session/stream events.
+
+**Do NOT use the `Local Cloud Testing` or `MCP Server Testing with
+Local Cloud Dev` sections below for general cloud testing — those
+describe the deprecated direct-mode path and are kept only to
+unblock in-flight work on that legacy path until it's removed.**
+
+For a fully-local livepeer stack (prebuilt go-livepeer + local
+runner, no fal involved), use the separate `testing-livepeer` skill
+instead.
 
 ## MCP Server Testing
 
@@ -246,6 +350,53 @@ for name, color in [('test', (0,0,255)), ('test1', (0,255,0)), ('test2', (255,0,
 - All sinks return same frame → per-sink routing issue in HeadlessSession
 - Syphon source black/missing → check logs for `"Syphon server not found"` — verify source_name matches display name from discovery
 
+<<<<<<< HEAD
+=======
+## MCP Server Testing with Local Cloud Dev
+
+> **DEPRECATED.** Describes MCP testing against the old direct-mode
+> two-instance setup. For cloud MCP testing going forward, combine
+> the `testing-livepeer-fal-deploy` skill with the MCP patterns
+> above. Kept for in-flight work on the legacy path only.
+
+**Only use this section when the user explicitly asks for local cloud / two-instance testing.**
+
+Test the cloud relay flow locally by running two Scope instances — one acting as the "cloud" relay server. This is for testing the cloud WebRTC relay path specifically.
+
+**Setup (two instances):**
+
+NOTE: Port 8022 is often used by Cursor IDE on macOS. Use port 8033 instead for the local instance.
+
+```bash
+lsof -ti:8002 -ti:8033 | xargs kill -9 2>/dev/null
+
+# Cloud instance (start first):
+CUDA_VISIBLE_DEVICES="" SCOPE_CLOUD_WS=1 uv run daydream-scope --port 8002 > /tmp/cloud.log 2>&1 &
+for i in $(seq 1 30); do curl -s http://localhost:8002/health > /dev/null 2>&1 && break; sleep 1; done
+
+# Local instance (start after cloud is healthy):
+CUDA_VISIBLE_DEVICES="" SCOPE_CLOUD_WS_URL=ws://localhost:8002/ws SCOPE_CLOUD_APP_ID=local uv run daydream-scope --port 8033 > /tmp/local.log 2>&1 &
+for i in $(seq 1 30); do curl -s http://localhost:8033/health > /dev/null 2>&1 && break; sleep 1; done
+```
+
+**Additional cloud-specific steps (before resolve/load):**
+
+```bash
+# Connect to cloud:
+curl -s -X POST http://localhost:8033/api/v1/cloud/connect -H 'Content-Type: application/json' -d '{"app_id": "local"}'
+# Wait and verify:
+sleep 2 && curl -s http://localhost:8033/api/v1/cloud/status
+```
+
+Then follow the same test sequence as single-instance mode above. All session/frame/recording endpoints go to port 8033 (local), not 8002 (cloud). Pipeline load is automatically proxied to cloud.
+
+**Cloud-specific debugging:**
+
+- `frames_to_cloud > 0, frames_from_cloud = 0` → cloud is not sending output back; check cloud logs
+- Both instances write separate log files to `~/.daydream-scope/logs/` — the `/api/v1/logs/tail` endpoint returns the most recent file alphabetically, which may be the wrong instance's logs. Read the actual log files with `ls -t ~/.daydream-scope/logs/scope-logs-*.log | head -2` to find both
+- Cloud status: `GET /api/v1/cloud/status` on port 8033
+
+>>>>>>> 48909aa6 (docs: route all "test cloud" prompts to the livepeer skill)
 ## Contributing Requirements
 
 - All commits must be signed off (DCO): `git commit -s`
diff --git a/deploy-staging.sh b/deploy-staging.sh
new file mode 100755
index 000000000..333c9ed74
--- /dev/null
+++ b/deploy-staging.sh
@@ -0,0 +1,51 @@
+#!/bin/bash
+# Deploy the Livepeer fal wrapper to a fal.ai app.
+#
+# Reads from env (typically sourced from .env.local):
+#   SCOPE_FAL_APP_NAME  required, e.g. "scope-livepeer-emran"
+#   SCOPE_FAL_ENV       optional, defaults to "main"
+#   SCOPE_FAL_AUTH      optional, defaults to "public"
+#
+# Exits non-zero on any failure so callers can fail fast.
+
+set -euo pipefail
+
+HERE="$(cd "$(dirname "$0")" && pwd)"
+
+if [ -f "$HERE/.env.local" ]; then
+    # shellcheck disable=SC1091
+    source "$HERE/.env.local"
+fi
+
+: "${SCOPE_FAL_APP_NAME:?Set SCOPE_FAL_APP_NAME in .env.local (see .env.example). Example: scope-livepeer-<your-name>}"
+SCOPE_FAL_ENV="${SCOPE_FAL_ENV:-main}"
+SCOPE_FAL_AUTH="${SCOPE_FAL_AUTH:-public}"
+
+VENV_DIR="$HERE/.venv-fal"
+
+# Ensure a Python 3.12 venv for fal (matches the scope image).
+if [ ! -d "$VENV_DIR" ]; then
+    echo "Creating Python 3.12 venv at $VENV_DIR..."
+    uv venv --python 3.12 "$VENV_DIR"
+fi
+
+if ! "$VENV_DIR/bin/python" -c "import fal" &>/dev/null; then
+    echo "Installing fal..."
+    uv pip install --python "$VENV_DIR/bin/python" fal
+fi
+
+if ! "$VENV_DIR/bin/fal" auth whoami &>/dev/null; then
+    echo "Not logged in to fal. Running 'fal auth login' (interactive)..."
+    "$VENV_DIR/bin/fal" auth login
+fi
+
+echo "Deploying src/scope/cloud/livepeer_fal_app.py"
+echo "  → app:  $SCOPE_FAL_APP_NAME"
+echo "  → env:  $SCOPE_FAL_ENV"
+echo "  → auth: $SCOPE_FAL_AUTH"
+
+"$VENV_DIR/bin/fal" deploy \
+    "$HERE/src/scope/cloud/livepeer_fal_app.py" \
+    --app "$SCOPE_FAL_APP_NAME" \
+    --auth "$SCOPE_FAL_AUTH" \
+    --env "$SCOPE_FAL_ENV"
diff --git a/e2e/README.md b/e2e/README.md
index 40bfc88b3..2cf95ee11 100644
--- a/e2e/README.md
+++ b/e2e/README.md
@@ -1,44 +1,102 @@
 # Scope E2E Tests
 
+<<<<<<< HEAD
 End-to-end tests for Scope onboarding and Livepeer cloud workflows.
+=======
+End-to-end Playwright test for Scope's Livepeer cloud streaming path.
+>>>>>>> 6a177ad5 (docs: make the testing-livepeer-fal-deploy skill discoverable)
 
-## Overview
+## What it verifies
 
+<<<<<<< HEAD
 These tests verify the full cloud flow:
 1. Login to Daydream web app
 2. Connect to Livepeer cloud mode
 3. Start a stream with the passthrough model
 4. Verify frames are being processed
 5. Stop stream
-
-## Prerequisites
-
+=======
+The single test in `tests/cloud-streaming.spec.ts` drives the full
+round-trip via a real browser:
+>>>>>>> 6a177ad5 (docs: make the testing-livepeer-fal-deploy skill discoverable)
+
+1. App loads (signed-in via a baked-in API key)
+2. Switch to Perform mode
+3. Toggle Remote Inference on, wait for cloud connection
+4. Select the `passthrough` pipeline
+5. Switch input to Camera (headless Chromium gets a synthetic feed)
+6. Start the stream
+7. Verify the **output** `<video>` in the "Video Output" card is
+   actually playing (frames round-tripped through the fal runner)
+8. Stop the stream
+
+<<<<<<< HEAD
 - Node.js 22+
 - A Daydream test account
 - A deployed Livepeer runner to test against
+=======
+## For the full setup guide
+>>>>>>> 6a177ad5 (docs: make the testing-livepeer-fal-deploy skill discoverable)
+
+This directory is intentionally minimal. The canonical setup and
+workflow instructions — including `.env.local` contents, sudo system
+deps for Chromium (`libnss3 libnspr4 libasound2t64`), expected
+Kafka/ClickHouse event sequence, and common failure signatures — live
+in the Claude Code skill:
 
-## Setup
+```
+.agents/skills/testing-livepeer-fal-deploy/SKILL.md
+```
+
+Ask Claude to "test the fal deploy" (or any other trigger phrase from
+the skill's `description`) and it will walk the flow. Or read the
+SKILL.md directly.
+
+## Quick reference
 
 ```bash
+# One-time setup
 cd e2e
 npm install
-npx playwright install --with-deps chromium
+npx playwright install chromium
+sudo apt-get install -y libnss3 libnspr4 libasound2t64  # first time only
+
+# Bake the API key into the frontend
+source ../.env.local
+(cd ../frontend && VITE_DAYDREAM_API_KEY="$SCOPE_CLOUD_API_KEY" npm run build)
+
+# Run
+../run-app.sh &           # scope on :8000
+npx playwright test       # ~2–5 min
+
+# Debug variants
+npm run test:headed       # visible browser
+npm run test:ui           # interactive UI
+npm run test:debug        # step through
+npm run report            # open last HTML report
 ```
 
-## Running Tests
+## Env vars (via `.env.local`)
 
-### Environment Variables
+See `.env.example` at the repo root. Required: `SCOPE_CLOUD_APP_ID`,
+`SCOPE_CLOUD_API_KEY`, `SCOPE_USER_ID`. Optional: `LIVEPEER_DEBUG=1`.
 
+<<<<<<< HEAD
 | Variable | Required | Description |
 |----------|----------|-------------|
 | `SCOPE_CLOUD_APP_ID` | Yes | Livepeer fal app ID (e.g., `daydream/scope-livepeer-pr-123--preview/ws`) |
 | `DAYDREAM_TEST_EMAIL` | Yes | Test user email for Daydream login |
 | `DAYDREAM_TEST_PASSWORD` | Yes | Test user password |
 | `DAYDREAM_BASE_URL` | No | Base URL for Daydream app (default: `https://app.daydream.live`) |
+=======
+## Fast HTTP-only smoke (no browser)
+>>>>>>> 6a177ad5 (docs: make the testing-livepeer-fal-deploy skill discoverable)
 
-### Run Tests
+For a quick "did the fal container come up?" check — bisect-friendly,
+no Playwright needed:
 
 ```bash
+<<<<<<< HEAD
 # Headless mode (CI)
 SCOPE_CLOUD_APP_ID=daydream/scope-livepeer--prod/ws \
 DAYDREAM_TEST_EMAIL=test@example.com \
@@ -111,3 +169,12 @@ test("my new cloud test", async ({ page }) => {
   await expect(element).toBeVisible();
 });
 ```
+=======
+../test-cloud-connect.sh --skip-push --skip-build-wait --skip-deploy
+```
+
+This only exercises `/api/v1/cloud/connect`; it will not produce the
+`pipeline_loaded` / `session_created` / `stream_started` Kafka events
+that the Playwright test does. Use it for infrastructure-level
+regressions; use Playwright for everything else.
+>>>>>>> 6a177ad5 (docs: make the testing-livepeer-fal-deploy skill discoverable)
diff --git a/e2e/playwright.config.ts b/e2e/playwright.config.ts
index 0adf100b7..9e440f28d 100644
--- a/e2e/playwright.config.ts
+++ b/e2e/playwright.config.ts
@@ -29,9 +29,12 @@ export default defineConfig({
     // Longer timeout for cloud operations
     actionTimeout: 30000,
     navigationTimeout: 60000,
+    // Grant camera/mic so getUserMedia() succeeds without a UI prompt
+    // (the browser launch flags below provide a synthetic feed).
+    permissions: ["camera", "microphone"],
   },
   // Global timeout per test
-  timeout: 180000, // 3 minutes for cloud streaming tests
+  timeout: 300000, // 5 minutes (cold-start fal containers can run long)
   expect: {
     timeout: 30000,
   },
@@ -40,6 +43,16 @@ export default defineConfig({
       name: "chromium",
       use: {
         ...devices["Desktop Chrome"],
+        launchOptions: {
+          // Feed getUserMedia a synthetic video source so a real WebRTC
+          // peer connection can complete end-to-end — without these
+          // flags, headless Chromium has no camera and ICE stalls.
+          args: [
+            "--use-fake-device-for-media-stream",
+            "--use-fake-ui-for-media-stream",
+            "--auto-select-desktop-capture-source=fake",
+          ],
+        },
       },
     },
   ],
diff --git a/e2e/tests/cloud-streaming.spec.ts b/e2e/tests/cloud-streaming.spec.ts
new file mode 100644
index 000000000..e16ecb8a1
--- /dev/null
+++ b/e2e/tests/cloud-streaming.spec.ts
@@ -0,0 +1,306 @@
+import { test, expect, Page } from "@playwright/test";
+
+/**
+ * E2E tests for Scope cloud streaming via fal.ai.
+ *
+ * The app is started with:
+ *   VITE_DAYDREAM_API_KEY=... → baked into the frontend, makes the app
+ *                              behave as signed-in so the cloud toggle
+ *                              is enabled
+ *   SCOPE_CLOUD_APP_ID=daydream/<app>/ws → points scope at a fal deploy
+ *
+ * Flow:
+ * 1. App loads (already logged in via baked-in API key)
+ * 2. Switch to Perform mode (default is Workflow/graph mode after the
+ *    graph-mode redesign)
+ * 3. Toggle Remote Inference on from the settings dialog
+ * 4. Wait for cloud connection (Connection ID rendered)
+ * 5. Select the passthrough pipeline
+ * 6. Click the play overlay to start the stream
+ * 7. Verify the output <video> is actually playing
+ * 8. Stop the stream
+ */
+
+test.describe("Cloud Streaming", () => {
+  test("connects to cloud and runs passthrough stream", async ({ page }) => {
+    // Increase timeout for this test — cold-start on fal can take ~2min
+    test.setTimeout(240000);
+
+    // Mock the onboarding status API to skip onboarding.
+    await page.route("**/api/v1/onboarding/status", async (route) => {
+      if (route.request().method() === "GET") {
+        await route.fulfill({
+          status: 200,
+          contentType: "application/json",
+          body: JSON.stringify({ completed: true, inference_mode: null }),
+        });
+      } else {
+        await route.fulfill({ status: 200, body: "{}" });
+      }
+    });
+
+    await page.goto("/");
+    await page.waitForLoadState("domcontentloaded");
+
+    // App is loaded once the Workflow/Perform mode toggle is present.
+    const performToggle = page.locator('[aria-label="Perform Mode"]');
+    await expect(performToggle).toBeVisible({ timeout: 15000 });
+    await page.screenshot({ path: "test-results/01-initial-load.png" });
+
+    // Step 1: Switch to Perform mode. Default after the graph-mode
+    // redesign is Workflow; Perform is where the cloud toggle,
+    // pipeline selector, and start button live.
+    await performToggle.click();
+    await page.waitForTimeout(1000);
+    await page.screenshot({ path: "test-results/02-perform-mode.png" });
+
+    // Step 2: Enable cloud mode via settings dialog
+    await enableCloudMode(page);
+
+    // Step 3: Wait for cloud connection (cold-start can be slow)
+    await waitForCloudConnection(page);
+
+    // Step 4: Select passthrough pipeline
+    await selectPassthroughModel(page);
+
+    // Step 5: Switch input source to Camera so getUserMedia() fires.
+    // Combined with the --use-fake-device-for-media-stream launch flag
+    // (see playwright.config.ts), this gives the browser a real
+    // MediaStreamTrack, which lets the browser↔local-scope WebRTC
+    // actually deliver frames — which is what triggers CloudTrack
+    // to call start_webrtc() and send the start_stream trickle
+    // message to the runner.
+    await selectCameraInput(page);
+
+    // Step 6: Start streaming
+    await startStream(page);
+
+    // Step 7: Verify the OUTPUT video is actually playing (frames
+    // round-tripped through the livepeer runner). Checking only
+    // "any video is playing" would false-positive on the input.
+    await verifyOutputStreamProcessing(page);
+
+    // Step 8: Stop stream
+    await stopStream(page);
+
+    console.log("✅ Cloud streaming test passed");
+  });
+});
+
+/**
+ * Open settings via the cloud button in the header and toggle the
+ * Remote Inference switch on.
+ */
+async function enableCloudMode(page: Page) {
+  console.log("Enabling cloud mode...");
+
+  // The cloud button in the header has title "Connect to cloud" (or
+  // "Cloud connected" once active). Match by title so we find it in
+  // any state.
+  const cloudButton = page.locator(
+    'button[title="Connect to cloud"], button[title="Cloud connected"], button[title="Connecting to cloud..."]'
+  );
+  await expect(cloudButton).toBeVisible({ timeout: 10000 });
+  await cloudButton.click();
+  await page.waitForTimeout(500);
+  await page.screenshot({ path: "test-results/03-settings-opened.png" });
+
+  // The Remote Inference switch lives inside the settings dialog's
+  // account tab.
+  const cloudToggle = page.locator('[data-testid="cloud-toggle"]');
+  await expect(cloudToggle).toBeVisible({ timeout: 10000 });
+  await expect(cloudToggle).toBeEnabled({ timeout: 30000 });
+
+  const checked = await cloudToggle.getAttribute("aria-checked");
+  if (checked !== "true") {
+    await cloudToggle.click();
+    await expect(cloudToggle).toHaveAttribute("aria-checked", "true", {
+      timeout: 10000,
+    });
+  }
+
+  await page.screenshot({ path: "test-results/04-cloud-toggled.png" });
+  console.log("✅ Cloud mode toggled on");
+}
+
+/**
+ * Connection ID text only renders once `status.connected` is true.
+ * Cold starts on fal can take ~2 minutes.
+ */
+async function waitForCloudConnection(page: Page) {
+  console.log("Waiting for cloud connection...");
+
+  await expect(page.getByText(/connection id/i)).toBeVisible({
+    timeout: 180000,
+  });
+  await page.screenshot({ path: "test-results/05-cloud-connected.png" });
+  console.log("✅ Cloud connection established");
+
+  // Close the settings dialog so the Perform UI is fully interactive.
+  await page.keyboard.press("Escape");
+  await page.waitForTimeout(500);
+}
+
+/**
+ * Select the passthrough pipeline from the Pipeline ID selector in
+ * the Settings panel (Perform mode).
+ */
+async function selectPassthroughModel(page: Page) {
+  console.log("Selecting passthrough model...");
+
+  // "Pipeline ID" is an <h3>; its Radix <Select> trigger is the
+  // combobox in the same surrounding container.
+  const pipelineSection = page
+    .locator("h3")
+    .filter({ hasText: /^Pipeline ID$/ })
+    .locator("..");
+  const selectTrigger = pipelineSection.getByRole("combobox");
+
+  await expect(selectTrigger).toBeVisible({ timeout: 10000 });
+  await selectTrigger.click();
+
+  const passthroughOption = page.getByRole("option", {
+    name: /passthrough/i,
+  });
+  await expect(passthroughOption).toBeVisible({ timeout: 5000 });
+  await passthroughOption.click();
+
+  // Wait a moment for the pipeline to swap in the UI (loading state,
+  // config form refresh).
+  await page.waitForTimeout(1500);
+  await page.screenshot({ path: "test-results/06-model-selected.png" });
+  console.log("✅ Passthrough model selected");
+}
+
+/**
+ * Start button is a PlayOverlay rendered with
+ * data-testid="start-stream-button". Retry a few times — the overlay
+ * can intercept clicks while the input video is still loading.
+ */
+async function startStream(page: Page) {
+  console.log("Starting stream...");
+
+  const startButton = page.locator('[data-testid="start-stream-button"]');
+
+  const MAX_ATTEMPTS = 5;
+  for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+    await expect(startButton).toBeVisible({ timeout: 10000 });
+    await startButton.click();
+    await page.waitForTimeout(2000);
+
+    const stillVisible = await startButton.isVisible().catch(() => false);
+    if (!stillVisible) {
+      break;
+    }
+
+    console.log(
+      `⚠️ Start button still visible after click (attempt ${attempt}/${MAX_ATTEMPTS}), retrying...`
+    );
+    await page.screenshot({
+      path: `test-results/07-stream-retry-${attempt}.png`,
+    });
+
+    if (attempt === MAX_ATTEMPTS) {
+      throw new Error(
+        "Start stream button still visible after max retries — input video may not have loaded"
+      );
+    }
+    await page.waitForTimeout(3000);
+  }
+
+  await page.waitForTimeout(2000);
+  await page.screenshot({ path: "test-results/07-stream-started.png" });
+  console.log("✅ Stream started");
+}
+
+/**
+ * Switch the input source to Camera. Combined with the
+ * --use-fake-device-for-media-stream browser flag, this gives the
+ * browser a synthetic MediaStreamTrack via getUserMedia(), which is
+ * what enables a real WebRTC peer connection between the browser and
+ * local scope — the trigger for CloudTrack.start_webrtc() and the
+ * runner's start_stream control message in Livepeer mode.
+ */
+async function selectCameraInput(page: Page) {
+  console.log("Switching input source to Camera...");
+  const cameraToggle = page.locator('[aria-label="Camera"]');
+  await expect(cameraToggle).toBeVisible({ timeout: 10000 });
+  await cameraToggle.click();
+  // Give the app a moment to request getUserMedia and attach the
+  // resulting stream to the input video element.
+  await page.waitForTimeout(2000);
+  await page.screenshot({ path: "test-results/06b-camera-selected.png" });
+  console.log("✅ Camera input selected");
+}
+
+/**
+ * Verify the *output* video inside the "Video Output" card is actually
+ * playing — i.e., frames round-tripped through the livepeer runner and
+ * came back to the browser. Checking any <video> would false-positive
+ * on the local input preview.
+ */
+async function verifyOutputStreamProcessing(page: Page) {
+  console.log("Verifying output stream processing...");
+
+  // The Video Output card owns the output <video>. The element is
+  // only rendered when `remoteStream` is set, so waiting for it to be
+  // visible implicitly waits for the stream to come up.
+  const outputCard = page
+    .locator("text=Video Output")
+    .locator("..")
+    .locator("..");
+  const outputVideo = outputCard.locator("video");
+
+  await expect(outputVideo).toBeVisible({ timeout: 120000 });
+  await page.screenshot({ path: "test-results/08a-output-rendered.png" });
+
+  // Poll until the output video is actually playing with a non-zero
+  // currentTime (frames arriving, not just the element attached).
+  const MAX_WAIT_MS = 60000;
+  const POLL_MS = 2000;
+  const start = Date.now();
+
+  while (Date.now() - start < MAX_WAIT_MS) {
+    const playing = await outputVideo.evaluate((el) => {
+      const v = el as HTMLVideoElement;
+      return !v.paused && v.readyState >= 2 && v.currentTime > 0;
+    });
+    if (playing) {
+      await page.screenshot({ path: "test-results/08b-frames-flowing.png" });
+      console.log("✅ Output frames flowing");
+      // Let the stream run briefly so stream_heartbeat events fire
+      // on the runner side (frame_processor.py:707 emits roughly
+      // every ~10s while the FrameProcessor is running).
+      await page.waitForTimeout(15000);
+      return;
+    }
+    await page.waitForTimeout(POLL_MS);
+  }
+
+  await page.screenshot({ path: "test-results/08c-no-output-frames.png" });
+  throw new Error(
+    `Output <video> element present but not playing after ${MAX_WAIT_MS}ms — frames not round-tripping`
+  );
+}
+
+/**
+ * Click the start-stream-button again to stop (it's a toggle — the
+ * PlayOverlay turns into a stop overlay when the stream is running),
+ * with a fallback to a button with a stop-like aria-label.
+ */
+async function stopStream(page: Page) {
+  console.log("Stopping stream...");
+
+  const stopOverlay = page.locator('[data-testid="start-stream-button"]');
+  if (await stopOverlay.isVisible().catch(() => false)) {
+    await stopOverlay.click();
+  } else {
+    const stopButton = page.getByRole("button", { name: /stop/i });
+    if (await stopButton.isVisible().catch(() => false)) {
+      await stopButton.click();
+    }
+  }
+  await page.waitForTimeout(1000);
+  await page.screenshot({ path: "test-results/09-stream-stopped.png" });
+  console.log("✅ Stream stopped");
+}
diff --git a/run-app.sh b/run-app.sh
new file mode 100755
index 000000000..2d826c187
--- /dev/null
+++ b/run-app.sh
@@ -0,0 +1,28 @@
+#!/bin/bash
+# Run daydream-scope in livepeer cloud mode.
+#
+# Requires `.env.local` (gitignored) exporting at minimum:
+#   SCOPE_CLOUD_APP_ID   e.g. daydream/scope-livepeer-<user>/ws
+#   SCOPE_CLOUD_API_KEY  daydream cloud API key (sk_...)
+# Optional in `.env.local`:
+#   SCOPE_USER_ID        daydream user id (used by test-cloud-connect.sh)
+#   LIVEPEER_DEBUG=1     surface per-orchestrator rejection reasons
+#
+# See .env.example for a template.
+
+set -euo pipefail
+HERE="$(cd "$(dirname "$0")" && pwd)"
+
+if [ -f "$HERE/.env.local" ]; then
+    # shellcheck disable=SC1091
+    source "$HERE/.env.local"
+fi
+
+: "${SCOPE_CLOUD_APP_ID:?Set SCOPE_CLOUD_APP_ID in .env.local (see .env.example)}"
+
+# Env vars sourced from .env.local are already exported; the previous
+# attempt to inline-prefix them with ${VAR:+VAR=$VAR} broke under
+# bash's word-splitting rules ("SCOPE_CLOUD_API_KEY=sk_... command not
+# found"). Just re-export and exec.
+export SCOPE_CLOUD_MODE=livepeer
+exec uv run daydream-scope "$@"
diff --git a/test-cloud-connect.sh b/test-cloud-connect.sh
new file mode 100755
index 000000000..6366de1b3
--- /dev/null
+++ b/test-cloud-connect.sh
@@ -0,0 +1,390 @@
+#!/bin/bash
+# End-to-end cloud-connect test for the livepeer fal deploy.
+#
+# Flow:
+#   1. (optional) push current branch to origin
+#   2. (optional) wait for CI `build-cloud` to succeed for HEAD
+#   3. (optional) run deploy-staging.sh to deploy the fal wrapper
+#   4. start daydream-scope locally via ./run-app.sh
+#   5. POST /api/v1/cloud/connect
+#   6. poll /api/v1/cloud/status until connected, errored, or timed out
+#   7. (--full-session) load pipeline, start session, wait for frames,
+#      stop session, cloud disconnect
+#
+# Exit codes (bisect-friendly):
+#   0  success (connected, and if --full-session then frames flowed)
+#   1  cloud reported error
+#   2  timed out waiting for connect / pipeline / frames
+#   3  infra failure (push / CI / deploy / scope startup)
+#   4  session-level failure (pipeline load, session start, no frames)
+
+set -euo pipefail
+
+PORT="${PORT:-8000}"
+TIMEOUT_CONNECT="${TIMEOUT_CONNECT:-180}"
+TIMEOUT_HEALTH="${TIMEOUT_HEALTH:-60}"
+TIMEOUT_CI="${TIMEOUT_CI:-1800}"
+TIMEOUT_PIPELINE="${TIMEOUT_PIPELINE:-300}"
+TIMEOUT_FRAMES="${TIMEOUT_FRAMES:-60}"
+PIPELINE_ID="${PIPELINE_ID:-passthrough}"
+TEST_VIDEO="${TEST_VIDEO:-/tmp/test_input.mp4}"
+SKIP_PUSH=0
+SKIP_BUILD_WAIT=0
+SKIP_DEPLOY=0
+KEEP_SCOPE=0
+FULL_SESSION=0
+
+usage() {
+    cat <<EOF
+Usage: $0 [options]
+
+Options:
+  --skip-push         do not git push
+  --skip-build-wait   do not wait for GitHub Actions build-cloud
+  --skip-deploy       do not run deploy-staging.sh
+  --keep-scope        leave scope running after test (do not kill)
+  --full-session      after connect, load pipeline + start session +
+                      verify frames + stop + cloud-disconnect (exercises
+                      full Kafka event stream: pipeline_loaded /
+                      session_created / stream_started / stream_heartbeat)
+  --port N            scope port (default 8000, env PORT)
+  -h, --help          show this help
+
+Env overrides: PORT, TIMEOUT_CONNECT, TIMEOUT_HEALTH, TIMEOUT_CI,
+               TIMEOUT_PIPELINE, TIMEOUT_FRAMES, PIPELINE_ID, TEST_VIDEO
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --skip-push) SKIP_PUSH=1; shift ;;
+        --skip-build-wait) SKIP_BUILD_WAIT=1; shift ;;
+        --skip-deploy) SKIP_DEPLOY=1; shift ;;
+        --keep-scope) KEEP_SCOPE=1; shift ;;
+        --full-session) FULL_SESSION=1; shift ;;
+        --port) PORT="$2"; shift 2 ;;
+        -h|--help) usage; exit 0 ;;
+        *) echo "Unknown arg: $1"; usage; exit 3 ;;
+    esac
+done
+
+SCOPE_URL="http://localhost:${PORT}"
+LOG_DIR="/tmp/test-cloud-connect"
+mkdir -p "$LOG_DIR"
+DRIVER_LOG="$LOG_DIR/driver.log"
+SCOPE_LOG="$LOG_DIR/scope.log"
+: > "$DRIVER_LOG"
+: > "$SCOPE_LOG"
+
+log() { echo "[$(date +%H:%M:%S)] $*" | tee -a "$DRIVER_LOG"; }
+fail() { log "FAIL: $*"; exit "${2:-3}"; }
+
+SCOPE_PID=""
+cleanup() {
+    local ec=$?
+    if [[ $KEEP_SCOPE -eq 0 && -n "$SCOPE_PID" ]]; then
+        log "Stopping scope (pid=$SCOPE_PID)"
+        kill "$SCOPE_PID" 2>/dev/null || true
+        wait "$SCOPE_PID" 2>/dev/null || true
+    elif [[ $KEEP_SCOPE -eq 1 && -n "$SCOPE_PID" ]]; then
+        log "Leaving scope running (pid=$SCOPE_PID, logs $SCOPE_LOG)"
+    fi
+    log "Exit code: $ec"
+    exit $ec
+}
+trap cleanup EXIT INT TERM
+
+# JSON field extractor via python3 (jq not available everywhere)
+json_get() {
+    # $1 = field path (e.g. ".connected" or ".error")
+    # stdin = json
+    python3 -c "
+import json, sys
+try:
+    d = json.load(sys.stdin)
+except Exception as e:
+    print(f'<parse_err:{e}>', file=sys.stderr)
+    sys.exit(0)
+path = '$1'.lstrip('.').split('.')
+v = d
+for p in path:
+    if isinstance(v, dict):
+        v = v.get(p)
+    else:
+        v = None
+        break
+if v is None:
+    print('')
+elif isinstance(v, bool):
+    print('true' if v else 'false')
+else:
+    print(v)
+"
+}
+
+# --- 1. Push -------------------------------------------------------
+if [[ $SKIP_PUSH -eq 0 ]]; then
+    if ! git diff-index --quiet HEAD --; then
+        fail "Uncommitted changes present. Commit first or pass --skip-push." 3
+    fi
+    BRANCH=$(git rev-parse --abbrev-ref HEAD)
+    log "Pushing $BRANCH to origin..."
+    git push origin "$BRANCH" 2>&1 | tee -a "$DRIVER_LOG"
+fi
+
+SHA=$(git rev-parse HEAD)
+SHORT_SHA=$(git rev-parse --short HEAD)
+log "Testing commit: $SHORT_SHA"
+
+# --- 2. Wait for CI build-cloud ------------------------------------
+if [[ $SKIP_BUILD_WAIT -eq 0 ]]; then
+    log "Locating CI build-cloud run for $SHORT_SHA..."
+    START=$(date +%s)
+    RUN_ID=""
+    while [[ -z "$RUN_ID" ]]; do
+        if [[ $(($(date +%s) - START)) -gt 180 ]]; then
+            fail "No CI run found for $SHORT_SHA after 3 min" 3
+        fi
+        RUN_ID=$(gh run list --workflow=docker-build.yml --commit "$SHA" \
+            --json databaseId --jq '.[0].databaseId' 2>/dev/null || true)
+        [[ -z "$RUN_ID" ]] && sleep 5
+    done
+    log "Watching CI run $RUN_ID (timeout ${TIMEOUT_CI}s)..."
+    if ! timeout "$TIMEOUT_CI" gh run watch "$RUN_ID" --exit-status --interval 15 \
+            2>&1 | tee -a "$DRIVER_LOG"; then
+        fail "CI run $RUN_ID did not succeed" 3
+    fi
+    log "CI succeeded"
+fi
+
+# --- 3. Deploy -----------------------------------------------------
+if [[ $SKIP_DEPLOY -eq 0 ]]; then
+    if [[ ! -x ./deploy-staging.sh ]]; then
+        fail "./deploy-staging.sh not found or not executable. Create one that runs \`fal deploy src/scope/cloud/livepeer_fal_app.py --app <your-app> --auth public --env main\`, or pass --skip-deploy." 3
+    fi
+    log "Running ./deploy-staging.sh..."
+    if ! ./deploy-staging.sh 2>&1 | tee -a "$DRIVER_LOG"; then
+        fail "deploy-staging.sh failed" 3
+    fi
+    log "Deploy completed"
+fi
+
+# --- 4. Start scope ------------------------------------------------
+log "Freeing port $PORT..."
+lsof -ti:"$PORT" 2>/dev/null | xargs -r kill -9 2>/dev/null || true
+sleep 1
+
+log "Starting scope (logs: $SCOPE_LOG)..."
+./run-app.sh --port "$PORT" > "$SCOPE_LOG" 2>&1 &
+SCOPE_PID=$!
+log "Scope pid=$SCOPE_PID"
+
+log "Waiting for /health..."
+START=$(date +%s)
+while ! curl -sf "$SCOPE_URL/health" > /dev/null 2>&1; do
+    if [[ $(($(date +%s) - START)) -gt $TIMEOUT_HEALTH ]]; then
+        log "Scope health timeout. Last 50 log lines:"
+        tail -50 "$SCOPE_LOG" | tee -a "$DRIVER_LOG"
+        fail "Scope did not become healthy" 3
+    fi
+    if ! kill -0 "$SCOPE_PID" 2>/dev/null; then
+        log "Scope process died. Last 50 log lines:"
+        tail -50 "$SCOPE_LOG" | tee -a "$DRIVER_LOG"
+        fail "Scope process exited" 3
+    fi
+    sleep 1
+done
+log "Scope healthy"
+
+# --- 5. Connect ----------------------------------------------------
+# Source .env.local so SCOPE_USER_ID is available for the connect body.
+if [ -f "$(dirname "$0")/.env.local" ]; then
+    # shellcheck disable=SC1091
+    source "$(dirname "$0")/.env.local"
+fi
+CONNECT_BODY='{}'
+if [[ -n "${SCOPE_USER_ID:-}" ]]; then
+    CONNECT_BODY=$(python3 -c "import json,os; print(json.dumps({'user_id': os.environ['SCOPE_USER_ID']}))")
+fi
+log "POST /api/v1/cloud/connect (user_id=${SCOPE_USER_ID:-<unset>})"
+CONNECT_RESP=$(curl -sf -X POST "$SCOPE_URL/api/v1/cloud/connect" \
+    -H 'Content-Type: application/json' -d "$CONNECT_BODY")
+log "Connect response: $CONNECT_RESP"
+
+# --- 6. Poll status ------------------------------------------------
+log "Polling /api/v1/cloud/status (timeout ${TIMEOUT_CONNECT}s)..."
+START=$(date +%s)
+LAST_STAGE=""
+while true; do
+    ELAPSED=$(($(date +%s) - START))
+    if [[ $ELAPSED -gt $TIMEOUT_CONNECT ]]; then
+        log "TIMEOUT after ${ELAPSED}s"
+        curl -s "$SCOPE_URL/api/v1/cloud/status" | tee -a "$DRIVER_LOG"
+        echo
+        log "Last 30 scope log lines:"
+        tail -30 "$SCOPE_LOG" | tee -a "$DRIVER_LOG"
+        exit 2
+    fi
+    STATUS=$(curl -s "$SCOPE_URL/api/v1/cloud/status")
+    CONNECTED=$(echo "$STATUS" | json_get ".connected")
+    ERROR=$(echo "$STATUS" | json_get ".error")
+    STAGE=$(echo "$STATUS" | json_get ".connect_stage")
+
+    if [[ "$CONNECTED" == "true" ]]; then
+        log "CONNECTED (${ELAPSED}s)"
+        echo "$STATUS" | tee -a "$DRIVER_LOG"
+        echo
+        break
+    fi
+    if [[ -n "$ERROR" && "$ERROR" != "None" ]]; then
+        log "CLOUD ERROR (${ELAPSED}s): $ERROR"
+        echo "$STATUS" | tee -a "$DRIVER_LOG"
+        echo
+        log "Last 30 scope log lines:"
+        tail -30 "$SCOPE_LOG" | tee -a "$DRIVER_LOG"
+        exit 1
+    fi
+    if [[ "$STAGE" != "$LAST_STAGE" ]]; then
+        log "  stage: $STAGE (${ELAPSED}s)"
+        LAST_STAGE="$STAGE"
+    fi
+    sleep 3
+done
+
+if [[ $FULL_SESSION -eq 0 ]]; then
+    exit 0
+fi
+
+# --- 7. Full session: pipeline + session + frames + cleanup --------
+
+# 7a. Ensure test video exists
+if [[ ! -f "$TEST_VIDEO" ]]; then
+    log "Creating $TEST_VIDEO (512x512 red frames @30fps, 10s)..."
+    uv run --with opencv-python --with numpy python -c "
+import cv2, numpy as np
+w = cv2.VideoWriter('$TEST_VIDEO', cv2.VideoWriter_fourcc(*'mp4v'), 30, (512, 512))
+frame = np.zeros((512, 512, 3), dtype=np.uint8)
+frame[:] = (0, 0, 255)
+for _ in range(300):
+    w.write(frame)
+w.release()
+" 2>&1 | tee -a "$DRIVER_LOG"
+    [[ -f "$TEST_VIDEO" ]] || fail "Failed to create $TEST_VIDEO" 4
+fi
+log "Test video: $TEST_VIDEO"
+
+# 7b. Load pipeline
+log "POST /api/v1/pipeline/load (pipeline_id=$PIPELINE_ID)"
+LOAD_BODY=$(python3 -c "import json; print(json.dumps({'pipeline_ids': ['$PIPELINE_ID']}))")
+LOAD_RESP=$(curl -sf -X POST "$SCOPE_URL/api/v1/pipeline/load" \
+    -H 'Content-Type: application/json' -d "$LOAD_BODY") \
+    || fail "pipeline/load request failed" 4
+log "Load response: $LOAD_RESP"
+
+# 7c. Poll pipeline status — require both status=loaded AND pipeline_id
+# matches what we loaded (cloud-mode status can show a stale "loaded"
+# from a previous session for a brief window after POST).
+log "Polling /api/v1/pipeline/status (timeout ${TIMEOUT_PIPELINE}s)..."
+# Give the async load a moment to propagate before first check.
+sleep 5
+START=$(date +%s)
+LAST_KEY=""
+while true; do
+    ELAPSED=$(($(date +%s) - START))
+    if [[ $ELAPSED -gt $TIMEOUT_PIPELINE ]]; then
+        log "Pipeline load TIMEOUT after ${ELAPSED}s. Last status:"
+        curl -s "$SCOPE_URL/api/v1/pipeline/status" | tee -a "$DRIVER_LOG"
+        echo
+        exit 2
+    fi
+    PSTATUS=$(curl -s "$SCOPE_URL/api/v1/pipeline/status")
+    PS=$(echo "$PSTATUS" | json_get ".status")
+    PID=$(echo "$PSTATUS" | json_get ".pipeline_id")
+    STAGE=$(echo "$PSTATUS" | json_get ".loading_stage")
+    if [[ "$PS" == "loaded" && "$PID" == "$PIPELINE_ID" ]]; then
+        log "Pipeline loaded (${ELAPSED}s, id=$PID)"
+        break
+    fi
+    if [[ "$PS" == "error" ]]; then
+        log "Pipeline load ERROR after ${ELAPSED}s"
+        echo "$PSTATUS" | tee -a "$DRIVER_LOG"
+        echo
+        exit 4
+    fi
+    KEY="${PS}|${PID}|${STAGE}"
+    if [[ "$KEY" != "$LAST_KEY" ]]; then
+        log "  pipeline status=$PS pipeline_id=$PID stage=$STAGE (${ELAPSED}s)"
+        LAST_KEY="$KEY"
+    fi
+    sleep 3
+done
+
+# 7d. Start session with video-file input
+log "POST /api/v1/session/start (pipeline=$PIPELINE_ID, source=$TEST_VIDEO)"
+SESSION_BODY=$(python3 -c "
+import json, os
+body = {
+    'pipeline_id': '$PIPELINE_ID',
+    'input_mode': 'video',
+    'input_source': {
+        'enabled': True,
+        'source_type': 'video_file',
+        'source_name': os.environ.get('TEST_VIDEO', '$TEST_VIDEO'),
+    },
+}
+print(json.dumps(body))
+")
+SESSION_RESP=$(curl -s -o /tmp/session_start.json -w '%{http_code}' \
+    -X POST "$SCOPE_URL/api/v1/session/start" \
+    -H 'Content-Type: application/json' -d "$SESSION_BODY") || true
+if [[ "$SESSION_RESP" != "200" ]]; then
+    log "session/start failed (http $SESSION_RESP)"
+    cat /tmp/session_start.json | tee -a "$DRIVER_LOG"
+    echo
+    exit 4
+fi
+log "Session started"
+
+# 7e. Wait for frames
+log "Waiting for frames to flow (timeout ${TIMEOUT_FRAMES}s)..."
+START=$(date +%s)
+FRAMES_IN=0
+FRAMES_OUT=0
+while true; do
+    ELAPSED=$(($(date +%s) - START))
+    if [[ $ELAPSED -gt $TIMEOUT_FRAMES ]]; then
+        log "Frame-wait TIMEOUT (frames_in=$FRAMES_IN frames_out=$FRAMES_OUT)"
+        curl -s "$SCOPE_URL/api/v1/session/metrics" | tee -a "$DRIVER_LOG"
+        echo
+        exit 2
+    fi
+    METRICS=$(curl -s "$SCOPE_URL/api/v1/session/metrics")
+    FRAMES_IN=$(echo "$METRICS" | json_get ".frames_in")
+    FRAMES_OUT=$(echo "$METRICS" | json_get ".frames_out")
+    FRAMES_IN=${FRAMES_IN:-0}
+    FRAMES_OUT=${FRAMES_OUT:-0}
+    if [[ "$FRAMES_OUT" != "0" && "$FRAMES_OUT" != "" ]]; then
+        log "Frames flowing: in=$FRAMES_IN out=$FRAMES_OUT (${ELAPSED}s)"
+        break
+    fi
+    sleep 2
+done
+
+# 7f. Let it run a bit so stream_heartbeat events fire
+log "Streaming for 10s to let heartbeat events fire..."
+sleep 10
+METRICS=$(curl -s "$SCOPE_URL/api/v1/session/metrics")
+log "Final metrics: $METRICS"
+
+# 7g. Stop session
+log "POST /api/v1/session/stop"
+curl -sf -X POST "$SCOPE_URL/api/v1/session/stop" > /dev/null \
+    || log "session/stop returned non-2xx (continuing)"
+
+# 7h. Cloud disconnect (explicit, to cleanly fire websocket_disconnected)
+log "POST /api/v1/cloud/disconnect"
+curl -sf -X POST "$SCOPE_URL/api/v1/cloud/disconnect" > /dev/null \
+    || log "cloud/disconnect returned non-2xx (continuing)"
+
+log "Full-session test OK"
+exit 0