scenescout 1.1.0 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # scenescout
 
+## 1.3.0
+
+### Minor Changes
+
+- a7c978a: `scenescout install` now puts the `scenescout` command on your PATH. Until now neither an `npx` run nor a source checkout left it there, so `scenescout status`, `scenescout doctor` and the other commands the tool itself tells you to run answered "command not found".
+  
+  Run through `npx`, install does `npm install -g` of the version you ran. From a checkout it does `npm link`, so the command always runs what you last built, and From a checkout it runs `npm link`, taking the name over from any other copy the way install already takes over the MCP registration. Run through `npx`, a command that is already there is left alone. On Windows the step prints the command to run by hand. If npm refuses, the step prints the command to run by hand and does not fail the setup. `--no-command` skips it.
+- 195cb59: Watch a run live. `scout_attach` now returns a `Live view:` address, which the agent passes on to you, and `scenescout watch <project>` opens the same page from a terminal. It shows one card per session: the tool it is running, how long it has been there, the page it is on, a thumbnail of that page, a rolling feed of what it just did (each action, its target and how it turned out, read from the same action log a finding's repro trace uses), and a live stream you can switch on per session or for all of them. Opening a card's close-up shows a longer stretch of that feed beside the session's brief: the task the agent gave it at `scout_attach {task}`, and the goal of the journey it is on right now. Actions of one journey share a tint in the feed, and pointing at a group shows the goal those actions served. The Report button shows the run's report as it stands, rendered from the current state without writing it, so it can be read while the run is still going. It works for headless runs, and a session whose call is still running past its own tool's watchdog budget is marked as stuck.
+  
+  `status.json` now describes every session instead of the last one to write, and `scenescout status` prints a line for each.
+  
+  The live view is served on `127.0.0.1` only, behind a per-process token, answers GET and nothing else, and writes no frame to disk ([ADR 7](docs/adr/0007-the-live-view-is-local-read-only-and-leaves-nothing-behind.md)). A stream runs only while someone is watching it. Set `SCENESCOUT_LIVE=off` to keep the engine from opening the port. The engine now also shuts down, closing its browsers and removing the token file, when its client closes the connection instead of sending a signal.
+
+## 1.2.0
+
+### Minor Changes
+
+- 2932164: `scenescout install --browsers <list>` chooses what to download: `chromium` (the default, unchanged), `chromium-headless-shell` for the smallest working setup, `firefox`, `webkit`, or `all`. `scout_attach` takes a `browser` option, and `SCENESCOUT_BROWSER` sets the default. In Firefox and WebKit the engine keeps service workers from registering, because a request issued by one cannot be intercepted there and would pass the write policy. The missing-browser message and `doctor` now name the build that is actually missing, and the sizes quoted are the sizes on disk.
+  
+  Pages are no longer given shared workers unless the mode is `destructive`. A request a shared worker sends cannot be intercepted in any browser, and a `DELETE` sent from one reached the server in read-only mode.
+  
+  Hover no longer reports text that was already on the page and only moved to a new line, and the keyboard focus audit uses Option+Tab in WebKit on macOS, where plain Tab skips buttons and links.
+- ad0f31d: `scenescout install --client <list>` registers the server with clients other than Claude Code: `cursor`, `vscode`, `codex`, `gemini`, `copilot` and `windsurf`. Clients that have a command for adding a server are registered through it; Cursor and Windsurf get an entry added to their JSON server list, with every other entry kept and an unreadable file left untouched. For VS Code, a `code` command that belongs to another editor is not used. The skill is installed only when `claude-code` is among the clients.
+- 5504c63: The testing method now reaches every MCP client, not only Claude Code. A new `scout_playbook` tool returns it, the server's instructions tell an agent to call that tool before its first attach, and an `explore` prompt loads the method together with the target URL for clients that list server prompts as commands. It is the same text Claude Code loads as a skill, read from the same file.
+
+### Patch Changes
+
+- d0aa6aa: The package description, keywords and README now present SceneScout as a tool for any MCP client, with Claude Code as one of them. `doctor --engine` ends with what to ask an agent instead of a Claude Code command.
+
 ## 1.1.0
 
 ### Minor Changes

package/README.md

@@ -2,7 +2,9 @@
 
 # 🔭 SceneScout
 
-**Exploratory UI testing, driven by an AI agent.**
+**Exploratory UI testing, driven by the AI agent you already use.**
+
+Works with Claude Code · Cursor · VS Code (Copilot) · Codex CLI · Gemini CLI · Copilot CLI · Windsurf · any [MCP](https://modelcontextprotocol.io) client
 
 [![test](https://github.com/brunoboto96/SceneScout/actions/workflows/test.yml/badge.svg)](https://github.com/brunoboto96/SceneScout/actions/workflows/test.yml)
 [![npm](https://img.shields.io/npm/v/scenescout.svg)](https://www.npmjs.com/package/scenescout)
@@ -14,11 +16,11 @@
 
 </div>
 
-SceneScout is an [MCP](https://modelcontextprotocol.io) server that hands an agent a *structured view* of a running web app — every element, its geometry, and a set of always-on correctness oracles — and lets the agent explore it like a curious user. Claude Code is the brain; SceneScout is the hands, eyes, and memory.
+SceneScout is an [MCP](https://modelcontextprotocol.io) server that hands an agent a *structured view* of a running web app — every element, its geometry, and a set of always-on correctness oracles — and lets the agent explore it like a curious user. Your coding agent is the brain; SceneScout is the hands, eyes, and memory. Any MCP client can drive it, and the testing method comes with the server, so the agent knows how to use the tools wherever it runs.
 
 ```
 ┌─────────────────────┐   MCP (stdio)   ┌───────────────────────────────┐
-│ Claude Code + skill │ ──────────────▶ │ SceneScout engine             │
+│ Your coding agent   │ ──────────────▶ │ SceneScout engine             │
 │ (intent, judgment,  │ ◀────────────── │ Playwright · oracles · memory │
 │  your subscription) │  tool results   │ findings · report — no LLM    │
 └─────────────────────┘                 └───────────────────────────────┘
@@ -33,7 +35,7 @@ This is a real run against the small demo app bundled in this repository. The ap
 
 <p align="center"><img src="examples/screenshots/dashboard-annotated.png" alt="The demo app's dashboard with two defects outlined in red: 1, a yellow badge covering the All orders button; 2, the weekly chart image failing to load" width="760" /></p>
 
-**The broken chart is the demo app's bug, not this page's** — it is one of the ten findings SceneScout filed, next to the badge sitting on a button. The red callouts were added for this README; the [unmarked screenshots](examples/screenshots/) are the ones the engine took.
+**The broken chart is the demo app's bug, not this page's** — it is one of the twelve findings SceneScout filed, next to the badge sitting on a button. The red callouts were added for this README; the [unmarked screenshots](examples/screenshots/) are the ones the engine took.
 
 An excerpt of the report it wrote — [read the whole thing](examples/report.md):
 
@@ -44,13 +46,16 @@ An excerpt of the report it wrote — [read the whole thing](examples/report.md)
 > **🔴 [HIGH] Filtering orders by Archived fails, and the page shows an empty table instead of an error**
 > Evidence: `GET /api/orders?status=archived → HTTP 500`
 >
+> **🔴 [HIGH] A clerk can approve an order by calling the endpoint the page hides from them**
+> Evidence: `POST /api/orders/1037/approve 200 as clerk; POST /api/orders/1038/reject 403 as clerk` — the button was hidden, the server did not agree.
+>
 > **🟠 [MEDIUM] The "New: bulk import" badge sits on top of the All orders button** *(callout 1)*
 > Evidence: `"All orders" overlaps "New: bulk import" (81%)` — measured from layout boxes, no screenshot needed.
 >
 > **🟡 [LOW] The dashboard chart image is missing** *(callout 2)*
 > Evidence: `GET /img/weekly-chart.png → HTTP 404`
 >
-> **Gap ledger — what was NOT tested:** 4/7 visited routes never design-audited · single-role run, so permission boundaries are untested
+> **Gap ledger — what was NOT tested:** 9/12 visited routes never design-audited · single-role run, so permission boundaries are untested
 
 Every finding comes with a repro trace and a Playwright regression-test skeleton. To try it yourself, clone this repository, run `npm run demo:serve`, then `/scenescout --url http://127.0.0.1:4173` — see [demo-app/](demo-app/). Its README lists every seeded defect and which oracle catches it.
 
@@ -58,7 +63,7 @@ Every finding comes with a repro trace and a Playwright regression-test skeleton
 
 ## ✨ Why it's different
 
-- 🧠 **Claude is the brain — no API key.** The engine contains no LLM. Exploration runs on your Claude Code subscription; SceneScout just gives it deterministic tools.
+- 🧠 **Your agent is the brain — no API key.** The engine contains no LLM. Exploration runs on the agent and subscription you already have (Claude Code, Cursor, Copilot, Codex, Gemini CLI and others); SceneScout just gives it deterministic tools and the method for using them.
 - 📐 **Structured scene, not pixels.** The agent reads element lists *with layout geometry*, not screenshots. Overlap and off-screen bugs are computed from boxes — deterministic, no vision guessing. Images that failed to load are read from the DOM too. (Screenshots exist only for pixel-native residue like a canvas or a rendering glitch.)
 - 🛡️ **Read-only by default, enforced on the wire.** Destructive actions are blocked at the network layer, not by asking the model nicely. Opt into writes only against disposable data.
 - ✅ **Completion is a contract, not a vibe.** The engine knows the app's routes and *refuses* to file an "extensive" report while any known route is unvisited, unexercised, or un-audited. "Explored a bit and stopped" is structurally impossible.
@@ -80,7 +85,7 @@ SceneScout needs only a URL. Give it the source code as well and it gets noticea
 | **What a finding looks like** | the symptom, **plus** the file behind it and a suggested fix | the symptom, a repro trace, and a regression-test skeleton |
 | **Typical target** | `localhost` while you build | staging, a preview deploy, a client's site |
 
-**Why the codebase helps.** The agent driving SceneScout is Claude Code, which can already read your repository. With the source at hand it knows the app's static routes before opening the browser, so coverage is measured against the real app instead of whatever happened to be linked. It can also check a suspicion against the code before reporting it: "there is no way to export this table" is a much stronger finding once the agent has confirmed no export handler exists. And when something breaks it can open the component or handler responsible and tell you *where* and *how* to fix it — "the save button does nothing" becomes "`OrderForm` swallows the rejected promise in `onSubmit`; surface the error and re-enable the button".
+**Why the codebase helps.** The agent driving SceneScout is a coding agent, which can already read your repository. With the source at hand it knows the app's static routes before opening the browser, so coverage is measured against the real app instead of whatever happened to be linked. It can also check a suspicion against the code before reporting it: "there is no way to export this table" is a much stronger finding once the agent has confirmed no export handler exists. And when something breaks it can open the component or handler responsible and tell you *where* and *how* to fix it — "the save button does nothing" becomes "`OrderForm` swallows the rejected promise in `onSubmit`; surface the error and re-enable the button".
 
 **Why it still works without it.** Everything SceneScout *observes* comes from the running page — elements, layout geometry, console and network errors, design-audit scores, task-ease measurements — and none of that needs source code. Point it at a URL you are allowed to test and it behaves like a thorough QA tester: it explores, reproduces, and files findings with evidence.
 
@@ -104,7 +109,7 @@ SceneScout needs only a URL. Give it the source code as well and it gets noticea
 | | |
 |---|---|
 | **Node** | ≥ 20 |
-| **An MCP client** | [Claude Code](https://claude.ai/code) is the first-class one (it loads the skill); [others work too](#-other-mcp-clients) |
+| **An MCP client** | Claude Code, Cursor, VS Code with Copilot, Codex CLI, Gemini CLI, GitHub Copilot CLI, Windsurf, or [any other](#-other-mcp-clients) |
 | **A web app to test** | SceneScout tests a *live* app: start yours locally first (e.g. `npm run dev`, `make dev-up`), or have the URL of a deployed one you're allowed to test |
 
 ### 1️⃣ Install
@@ -112,9 +117,12 @@ SceneScout needs only a URL. Give it the source code as well and it gets noticea
 It is on npm. Nothing to clone:
 
 ```bash
-npx -y scenescout install      # skill + Chromium (~150 MB, one-time) + registers the server with Claude Code
+npx -y scenescout install                      # Claude Code: skill + server + Chromium (one-time download)
+npx -y scenescout install --client cursor      # or: vscode, codex, gemini, copilot, windsurf (comma-separated for several)
 ```
 
+Either way it downloads the browser and registers the server with the client you named. Claude Code also gets the method as a skill; every other client receives the same method from the server. [What each client gets](#-other-mcp-clients).
+
 **Prefer a Claude Code plugin?** The skill and the server arrive together:
 
 ```
@@ -124,16 +132,17 @@ npx -y scenescout install      # skill + Chromium (~150 MB, one-time) + register
 
 Then download the browser once with `npx -y scenescout install --browser-only`. The command becomes `/scenescout:scenescout`. A plugin's skill comes from this repository and its server from the latest npm release, so right after a release lands here the two can differ for a short while; `/plugin marketplace update scenescout-marketplace` brings the skill up to date.
 
-**Another MCP client?** Run `npx -y scenescout install --browser-only` and [add the server to its config](#-other-mcp-clients).
+**A client that is not in that list?** Run `npx -y scenescout install --browser-only` and [add the server to its config by hand](#-other-mcp-clients).
 
 <details>
 <summary>What <code>install</code> actually does</summary>
 
 1. puts the `/scenescout` skill into `~/.claude/skills/` (or `$CLAUDE_CONFIG_DIR/skills/`) — a `scenescout` folder it didn't create is moved aside to a `.backup-…` copy, never deleted,
-2. downloads the Chromium build SceneScout drives (skipped if you already have it),
-3. registers the MCP server with Claude Code at user scope. Run through `npx`, the launcher is `npx -y scenescout serve`, with the absolute path of `npx` where one sits beside node, so it works under nvm/fnm. From a clone or a global install it is the absolute node path plus that install's `dist/mcp-server.js`.
+2. downloads the browser SceneScout drives (skipped if you already have it). By default that is Chromium, as two builds: the full browser for headed runs and the headless shell every other run uses. [Choose something else](#-choosing-browsers) with `--browsers`,
+3. registers the MCP server with Claude Code at user scope. Run through `npx`, the launcher is `npx -y scenescout serve`, with the absolute path of `npx` where one sits beside node, so it works under nvm/fnm. From a clone or a global install it is the absolute node path plus that install's `dist/mcp-server.js`,
+4. puts the `scenescout` command on your PATH, so `scenescout status`, `scenescout watch` and `scenescout doctor` work from any terminal. Run through `npx`, that is `npm install -g` of the version you just ran; from a clone it is `npm link`, so the command always runs what you last built. If npm refuses (a system-wide node usually needs `sudo` for this), the step prints the command to run by hand and the rest of the setup still counts as done: `npx -y scenescout <command>` works without it.
 
-Re-run it any time: after moving the folder or switching node versions it refreshes the stored paths. It exits non-zero if any step failed, so it is safe to chain. Opt out of a step with `--no-register` or `--skip-browser`.
+Re-run it any time: after moving the folder or switching node versions it refreshes the stored paths. It exits non-zero if a step the tool depends on failed, so it is safe to chain. Opt out of a step with `--no-register`, `--skip-browser` or `--no-command`.
 
 If `claude` isn't on the PATH of the shell you ran it from, it prints the registration command instead of running it:
 
@@ -146,8 +155,8 @@ claude mcp add --scope user scenescout -- npx -y scenescout serve
 ### 2️⃣ Check it
 
 ```bash
-npx -y scenescout doctor            # everything, for the default install
-npx -y scenescout doctor --engine   # plugin install or another MCP client: node + build + browser only
+npx -y scenescout doctor --engine   # any client: node + build + browser
+npx -y scenescout doctor            # Claude Code: the above, plus the skill and the registration
 ```
 
 Every line should be a ✓. Anything that isn't prints the exact command that fixes it. Then **start a fresh session** in your client so it picks up the new tools.
@@ -156,18 +165,50 @@ Every line should be a ✓. Anything that isn't prints the exact command that fi
 
 No app handy? Clone this repository and run `npm run demo:serve`: the [demo app](demo-app/) starts on `http://127.0.0.1:4173`.
 
-From Claude Code, inside the project you want to test (or, for a [remote URL](#-two-ways-to-use-it), any folder):
+Open your agent inside the project you want to test (or, for a [remote URL](#-two-ways-to-use-it), any folder) and ask:
+
+```
+Use SceneScout to test http://localhost:3000 at medium level
+```
+
+In Claude Code the skill gives you a command with flags for the same thing:
 
 ```
 /scenescout --level medium --url http://localhost:3000 --role qa
 ```
 
-The skill scans the project (if there is one), attaches read-only, explores, and writes findings to `.scenescout/report.md`. That's it.
+The agent scans the project (if there is one), attaches read-only, explores, and writes findings to `.scenescout/report.md`. That's it.
 
 **Common flags** — `--level minimal|medium|extensive` · `--url <app>` · `--role <name\|path>` (a Playwright storage-state to explore as: a name found by the scan, or a path to the JSON file) · `--observe` / `--safe-write` / `--allow-destructive`.
 
 ---
 
+## 📺 Watching a run live
+
+When a session attaches, the engine starts a small live view and hands the agent its address on a `Live view:` line, which the agent passes on to you. From a terminal, `scenescout watch` opens the same page. There is one card per session:
+
+<p align="center"><img src="examples/screenshots/live-view.png" alt="The live view during a run of six parallel agents against the demo app: one card per session, each with its role, the tool it is running and for how long, the page it is on, a thumbnail, and a feed of the actions it just took" width="880" /></p>
+
+- **What it is doing:** the tool it is running and for how long, the page it is on, and a thumbnail of that page. This works for headless runs too, which have no window to look at.
+- **What it just did:** a rolling feed of its actions, each with its target and how it turned out, with failures in red. It is the same trail a finding's repro trace uses. The engine never sees the agent's reasoning, so this is what the session *did*, not what it thought.
+- **Stuck, not slow:** a call still running past its own tool's watchdog budget turns the card red, so a wedged session is visible without asking. A crawl legitimately runs for minutes; it is judged against the crawl's budget, not a click's.
+- **Live stream:** switch it on for one card, or for all of them. Click a thumbnail for a close-up.
+- **The report, as it stands:** the Report button in the top bar shows the same document `scout_report` writes at the end, rendered from the run's current state, so findings can be read while the agents are still working.
+- **What it is for:** the close-up puts the feed beside the session's brief: the task the agent gave it when it attached (`scout_attach {task}`), and the goal of the journey it is on right now (`scout_journey`). Actions of one journey share a tint in the feed; point at a group and the brief shows the goal those actions served.
+
+<p align="center"><img src="examples/screenshots/live-view-closeup.png" alt="A close-up of one session: its page streaming live, the feed of its recent actions grouped by journey, and beside it the task and current objective" width="880" /></p>
+
+<p align="center"><img src="examples/screenshots/live-view-report.png" alt="The report opened from the live view's top bar while the run is still going: summary table, gap ledger and the findings filed so far" width="880" /></p>
+
+The view is served on `127.0.0.1` only, behind a token that changes every time the engine starts. It answers `GET` and nothing else, so a viewer can watch a run but not act in it, and no frame is ever written to disk ([ADR 7](docs/adr/0007-the-live-view-is-local-read-only-and-leaves-nothing-behind.md)). A stream runs only while someone is watching it. `SCENESCOUT_LIVE=off` keeps the port closed.
+
+**Try it with parallel agents.** The demo app has three roles and several separate areas, so a run can be split between agents. Start it with `npm run demo:serve`, then ask your agent to explore it with several agents in parallel, one role and one area each. The pictures above come from a run of six. Two things keep a parallel run efficient:
+
+- **Each agent opens its own session when it starts and closes it when it is done.** An agent waiting for its turn then holds no browser. Opening every session up front leaves browsers idling while the machine runs out of memory for the agents that are working.
+- **Run about as many agents at once as your machine has cores, less two.** Each one drives a real browser.
+
+---
+
 ## 🔄 How a run works
 
 One curiosity loop, repeated — breadth first, then judgment where it matters:
@@ -192,11 +233,11 @@ Snapshots are cheap: re-snapshotting a route returns only *what changed*, with s
 
 ## 🧰 The toolbox
 
-24 deterministic tools. The agent picks; you rarely call these by hand.
+25 deterministic tools. The agent picks; you rarely call these by hand.
 
 | Phase | Tools | What they do |
 |---|---|---|
-| **Set up** | `scout_scan` `scout_attach` `scout_session` | Discover routes; launch a browser in a write-mode; keep several authenticated roles alive at once |
+| **Set up** | `scout_playbook` `scout_scan` `scout_attach` `scout_session` | Hand the testing method to an agent that has no skill loaded; discover routes; launch a browser in a write-mode; keep several authenticated roles alive at once |
 | **Explore** | `scout_crawl` `scout_coverage` | Sweep every route in one call; ask what's still untested |
 | **Look** | `scout_snapshot` `scout_hover` `scout_screenshot` | Read the structured scene (diffed); reveal tooltips/hover cards; capture pixels only when needed |
 | **Act** | `scout_click` `scout_type` `scout_select` `scout_upload` `scout_press` `scout_scroll` `scout_navigate` `scout_back` `scout_run_plan` | Drive the UI like a user; `scout_run_plan` batches a whole mechanical sequence into one call |
@@ -263,7 +304,7 @@ Run `npx -y scenescout doctor` first — it checks every setup item below (every
 | The `scout_*` tools don't appear | The MCP server isn't registered, or points at an old path. `npx -y scenescout install` re-registers it; `claude mcp list` should show `scenescout` as connected. |
 | *"Executable not found in $PATH"* | The server was registered with a bare `node`. `npx -y scenescout install` registers an absolute path. |
 | Installed as a plugin, and the tools fail with *"Executable not found in $PATH: npx"* | A plugin starts the server with a bare `npx`, which Claude Code can only find if it was launched from an environment that has Node on its `PATH`. Under nvm or fnm that means starting Claude Code from a terminal, not from a dock or launcher. Or use `npx -y scenescout install` instead, which registers the absolute path of `npx`. |
-| *"Executable doesn't exist … chromium"* | The browser download was skipped or failed. `npx playwright install chromium` (on Linux add `--with-deps`). |
+| *"… build has not been downloaded yet"* on attach | The browser download was skipped or failed, or the run asked for a browser you did not install. Run the command the message names, for example `npx -y scenescout install --browser-only --browsers firefox`. On Linux, system libraries may be missing too: `npx playwright install --with-deps chromium`. |
 | Tools broke after moving the folder or changing node version | The registration stores absolute paths. `npx -y scenescout install` refreshes them. |
 | Attach fails or every route lands on the login page | Your app isn't running at `--url`, or the `--role` storage state has expired — regenerate it the way your project's Playwright setup does. |
 
@@ -275,17 +316,69 @@ Run `npx -y scenescout doctor` first — it checks every setup item below (every
 ### 🧹 Uninstall
 
 ```bash
+# Claude Code
 claude mcp remove --scope user scenescout
 rm -rf ~/.claude/skills/scenescout
+# Codex / Gemini / Copilot CLI
+codex mcp remove scenescout        # likewise: gemini mcp remove …, copilot mcp remove …
 ```
 
+For Cursor, Windsurf and VS Code, delete the `scenescout` entry from the client's MCP server list.
+
 Nothing else is installed: `npx` runs the package from npm's cache. Per-project memory lives in each tested project's `.scenescout/` folder; delete it there if you want it gone.
 
 ---
 
+## 🌐 Choosing browsers
+
+`install` downloads Chromium and nothing else unless you ask. `--browsers` takes one name, a comma-separated list, or `all`:
+
+| `--browsers` | What is downloaded | About, on disk |
+|---|---|---|
+| `chromium` *(default)* | the full browser and the headless shell | 550 MB |
+| `chromium-headless-shell` | the headless shell only: every run works except `headed` | 200 MB |
+| `firefox` | Firefox | 270 MB |
+| `webkit` | WebKit, the engine behind Safari | 290 MB |
+| `all` | Chromium, Firefox and WebKit | 1.1 GB |
+
+```bash
+npx -y scenescout install --browsers chromium-headless-shell   # the smallest working setup
+npx -y scenescout install --browser-only --browsers firefox,webkit   # add two more later
+```
+
+Sizes vary by platform. The builds go to Playwright's shared cache, so a build another tool already fetched is not downloaded again.
+
+To drive another browser, pass `browser` when attaching (`scout_attach { browser: "firefox" }`), or set `SCENESCOUT_BROWSER=webkit` in the server's environment to change the default. `scenescout doctor` checks the browser named by that variable in the shell it runs from, so check another one with `SCENESCOUT_BROWSER=webkit scenescout doctor`. Two things differ outside Chromium:
+
+- **Service workers are not allowed to register** in Firefox and WebKit. The write policy works by intercepting requests, and only Chromium lets a request issued by a service worker be intercepted. An app that depends on its worker may behave differently there.
+- **A Firefox or WebKit left behind by a crash is not cleaned up** on the next start the way a leftover Chromium is.
+
+In every browser, pages are not given shared workers unless the mode is `destructive`: a request a shared worker sends cannot be intercepted anywhere, so the app is made to do that work on the page, where the policy sees it.
+
 ## 🔌 Other MCP clients
 
-The engine is a plain MCP server over stdio, so any client can drive it. The Claude Code route is the one this project tests. The entries below follow each client's own documentation for a local stdio server and have not been run by the maintainer; if one is out of date, a correction is welcome (say which client version you checked). The server entry is always the same command — `npx -y scenescout serve` — only the config file differs. Download the browser once with `npx -y scenescout install --browser-only`.
+The engine is a plain MCP server over stdio, so any client can drive it, and the testing method reaches the agent through the server itself (see the end of this section). `install` can register it for you:
+
+```bash
+npx -y scenescout install --client cursor            # one client
+npx -y scenescout install --client vscode,codex      # several; add claude-code to keep that one too
+```
+
+| `--client` | How it is registered |
+|---|---|
+| `claude-code` *(default)* | `claude mcp add`, plus the skill |
+| `cursor` | adds an entry to `~/.cursor/mcp.json`, keeping the others |
+| `vscode` | VS Code's own `code --add-mcp`. A `code` command that belongs to another editor is not used |
+| `codex` | `codex mcp add` |
+| `gemini` | `gemini mcp add --scope user` |
+| `copilot` | `copilot mcp add` (GitHub Copilot CLI) |
+| `windsurf` | adds an entry to `~/.codeium/windsurf/mcp_config.json`, keeping the others |
+
+A config file that is not valid JSON is left untouched, and the entry to add by hand is printed instead; a config that is a link into a dotfiles repository is written through the link. When a client that is registered through its own command is not installed, `install` says so and prints the command to run later. Cursor and Windsurf are files, so their entry is written whether or not the editor is installed yet. On Windows, a client installed through npm is a `.cmd` shim that `install` cannot start; it prints the command for you to run instead. Then restart the client and ask its agent: *"Use SceneScout to test http://localhost:3000"*.
+
+What has been checked: registering through each command above was run against Codex CLI, Gemini CLI, GitHub Copilot CLI and VS Code, and Cursor's command line agent read the entry `install` wrote, connected and listed the tools. The Windsurf path follows its documentation. A full test session has been run in Claude Code, with and without the skill. If a client behaves differently for you, a correction is welcome (say which client version you checked).
+
+To register by hand instead, the server entry is always the same command, `npx -y scenescout serve`:
 
 <details>
 <summary><strong>Cursor</strong> — <code>~/.cursor/mcp.json</code> (or <code>.cursor/mcp.json</code> in a project)</summary>
@@ -383,13 +476,19 @@ Most clients accept the same `mcpServers` JSON shape shown for Cursor.
 
 </details>
 
-**The skill is what makes it good.** The tools are only hands and eyes; [`skills/scenescout/SKILL.md`](skills/scenescout/SKILL.md) is the method — what to look at first, when to stop, what counts as a finding. Claude Code loads it as a skill. In another client, give the agent that file as its instructions (a rule, a custom mode, or pasted into the first message).
+**The method travels with the server.** The tools are only hands and eyes; [`skills/scenescout/SKILL.md`](skills/scenescout/SKILL.md) is the method: what to look at first, when to stop, what counts as a finding. Claude Code loads it as a skill. Every other client gets the same text from the server, with nothing to copy:
+
+- the server's instructions tell the agent to call `scout_playbook` before its first attach, and that tool returns the method,
+- clients that list server prompts as commands also get an `explore` prompt, which loads the method and takes an optional URL, level and focus.
+
+So in any client, a first message like *"Use SceneScout to test http://localhost:3000"* is enough. If an agent starts clicking without having called `scout_playbook`, tell it to call that first; how closely a model follows server instructions varies by client.
 
 The CLI is also useful on its own:
 
 ```bash
 npx -y scenescout scan <path>       # project discovery: framework, routes, saved logins
-npx -y scenescout status <path>     # what a running engine is doing right now
+npx -y scenescout status <path>     # what every session of a running engine is doing right now
+npx -y scenescout watch <path>      # the same, live in your browser, with each session's page
 ```
 
 ---
@@ -398,7 +497,7 @@ npx -y scenescout status <path>     # what a running engine is doing right now
 
 ```
 src/
-  mcp-server.ts     the 24 tools + per-session dispatch
+  mcp-server.ts     the 25 tools + per-session dispatch
   scan.ts           project discovery (framework, routes, auth)
   cli.ts            scan · serve · install · doctor · status
   installer.ts      setup logic (skill link, MCP registration, diagnostics)
@@ -417,7 +516,7 @@ src/
     …               collector · dispatch · fixtures · authloss · reaper
 scripts/            the 12 test suites (smoke/ holds the real-browser ones)
 test-app/           fixtures for the real-browser smoke tests
-skills/scenescout/   the Claude Code skill (SKILL.md)
+skills/scenescout/   the testing method (SKILL.md): a skill in Claude Code, served by the server everywhere else
 docs/adr/           why it's built this way
 ```
 
@@ -451,7 +550,7 @@ npm test           # build + 12 suites: scan, oracle, policy, fixture, dispatch,
 npm run demo       # regenerate examples/ from the demo app
 ```
 
-Contributing? Start with [VISION.md](VISION.md) (what is in scope) and [CONTRIBUTING.md](CONTRIBUTING.md) (how changes land), then see [CLAUDE.md](CLAUDE.md) for the house rules — chiefly: bug fixes need a regression test at the cheapest layer that can fail, keep the repo project-agnostic (ADR 6), and `npm test` must pass.
+Contributing? Start with [VISION.md](VISION.md) (what is in scope) and [CONTRIBUTING.md](CONTRIBUTING.md) (how changes land), then see [AGENTS.md](AGENTS.md) for the house rules — chiefly: bug fixes need a regression test at the cheapest layer that can fail, keep the repo project-agnostic (ADR 6), and `npm test` must pass.
 
 ## 🔐 Security
 
@@ -477,6 +576,6 @@ Found a way past the write policy, or another security problem? Please report it
 - **A trustworthy gap ledger.** Entries must be actionable (a search box or wizard sub-step isn't "form filled but never submitted"); API/download URLs never enter the route contract.
 - **Honest reporting.** Shared chrome counted once, stale scores marked, role matrix compares only roles that actually attempted a route.
 - **Cross-run written knowledge.** `scout_note` curates `.scenescout/ASSUMPTIONS.md` — app model, personas, constraints, risks — in prose.
-- **Daemon-grade robustness.** Per-tool watchdogs, orphaned-browser reaping, bounded teardown, live status via `scenescout status <project>`.
+- **Daemon-grade robustness.** Per-tool watchdogs, orphaned-browser reaping, bounded teardown, live status via `scenescout status <project>`, and a live view of every session's page: the agent gives you its address when it attaches, or run `scenescout watch <project>` (loopback only, read-only, nothing written to disk: [ADR 7](docs/adr/0007-the-live-view-is-local-read-only-and-leaves-nothing-behind.md)).
 
 </details>

package/dist/browsers.js

@@ -0,0 +1,196 @@
+/**
+ * Which browsers SceneScout can drive, which builds `scenescout install`
+ * downloads for them, and which build a given launch needs.
+ *
+ * Kept free of Playwright so the rules can be table-tested: the CLI and the
+ * engine pass in the paths Playwright reports and get decisions back.
+ */
+import fs from "node:fs";
+import path from "node:path";
+/** A browser the engine can launch. */
+export const BROWSER_ENGINES = ["chromium", "firefox", "webkit"];
+/**
+ * A build Playwright downloads. Chromium comes as two: the full browser, which
+ * a headed run opens, and the headless shell, which every headless run uses.
+ * Installing "chromium" brings both, which is what install has always done.
+ */
+export const INSTALL_TARGETS = ["chromium", "chromium-headless-shell", "firefox", "webkit"];
+export const DEFAULT_ENGINE = "chromium";
+/** Environment variable naming the browser an attach uses when it does not name one. */
+export const DEFAULT_ENGINE_ENV = "SCENESCOUT_BROWSER";
+/** Approximate size on disk, so the install output can say what it is about to fetch. */
+export const APPROX_DISK_MB = {
+    chromium: 550,
+    "chromium-headless-shell": 200,
+    firefox: 270,
+    webkit: 290,
+};
+export function isBrowserEngine(value) {
+    return BROWSER_ENGINES.includes(value);
+}
+/** The engine an attach uses when the caller names none: the environment's choice, else Chromium. */
+export function defaultEngine(env) {
+    const raw = env[DEFAULT_ENGINE_ENV]?.trim().toLowerCase();
+    if (!raw)
+        return DEFAULT_ENGINE;
+    if (!isBrowserEngine(raw)) {
+        throw new Error(`${DEFAULT_ENGINE_ENV}="${env[DEFAULT_ENGINE_ENV]}" is not a browser SceneScout can drive. Use one of: ${BROWSER_ENGINES.join(", ")}.`);
+    }
+    return raw;
+}
+/**
+ * Read the value of `--browsers`. Absent means what install has always done.
+ * `all` is every engine; a comma-separated list picks several. "chromium"
+ * already includes the headless shell, so naming both is the same as naming it.
+ */
+export function parseBrowserSelection(value) {
+    if (value === undefined)
+        return { targets: ["chromium"] };
+    const names = value
+        .split(",")
+        .map((s) => s.trim().toLowerCase())
+        .filter(Boolean);
+    const choices = `${INSTALL_TARGETS.join(", ")}, all`;
+    if (names.length === 0)
+        return { error: `--browsers needs a value. Choose from: ${choices}.` };
+    const picked = new Set();
+    for (const name of names) {
+        if (name === "all") {
+            for (const t of ["chromium", "firefox", "webkit"])
+                picked.add(t);
+        }
+        else if (INSTALL_TARGETS.includes(name)) {
+            picked.add(name);
+        }
+        else {
+            return { error: `"${name}" is not a browser SceneScout can install. Choose from: ${choices}.` };
+        }
+    }
+    if (picked.has("chromium"))
+        picked.delete("chromium-headless-shell");
+    return { targets: INSTALL_TARGETS.filter((t) => picked.has(t)) };
+}
+/** The arguments for Playwright's own installer. Target names are Playwright's names. */
+export function playwrightInstallArgs(targets) {
+    return ["install", ...targets];
+}
+/** The build a launch needs on disk. */
+export function launchTarget(engine, headed) {
+    if (engine !== "chromium")
+        return engine;
+    return headed ? "chromium" : "chromium-headless-shell";
+}
+/** The engine each build belongs to. */
+export function engineOf(target) {
+    return target === "chromium-headless-shell" ? "chromium" : target;
+}
+/**
+ * Where the headless shell lives, worked out from the full browser's path.
+ * Playwright exposes no path for the shell, but it keeps the two side by side
+ * under one revision: `chromium-1234/…` next to `chromium_headless_shell-1234/`.
+ * Null when the path does not have that shape.
+ */
+export function headlessShellDir(chromiumExecutable) {
+    if (!chromiumExecutable)
+        return null;
+    const parts = chromiumExecutable.split(/[\\/]/);
+    // The LAST such segment: a cache kept under a directory that happens to be
+    // named the same way must not be mistaken for the build directory.
+    let at = -1;
+    for (let i = parts.length - 1; i >= 0 && at < 0; i--)
+        if (/^chromium-\d+$/.test(parts[i]))
+            at = i;
+    if (at < 0)
+        return null;
+    const sep = chromiumExecutable.includes("\\") && !chromiumExecutable.includes("/") ? "\\" : "/";
+    return [...parts.slice(0, at), parts[at].replace(/^chromium-/, "chromium_headless_shell-")].join(sep);
+}
+/**
+ * Which builds are on disk. `executables` is what Playwright reports for each
+ * engine; a path Playwright names is not proof the file is there. The shell is
+ * counted only once Playwright has marked its download complete.
+ */
+export function browserPresence(executables, exists = fs.existsSync) {
+    const at = (p) => ({ installed: !!p && exists(p), path: p });
+    const shellDir = headlessShellDir(executables.chromium);
+    const shellMarker = shellDir ? path.join(shellDir, "INSTALLATION_COMPLETE") : null;
+    const chromium = at(executables.chromium);
+    return {
+        chromium: { installed: chromium.installed && !!shellMarker && exists(shellMarker), path: chromium.path },
+        "chromium-headless-shell": { installed: !!shellMarker && exists(shellMarker), path: shellDir },
+        firefox: at(executables.firefox),
+        webkit: at(executables.webkit),
+    };
+}
+/** The command that downloads one build, for the way this copy of SceneScout was installed. */
+export function installCommandFor(target, fromCheckout) {
+    const flags = `--browser-only --browsers ${target}`;
+    return fromCheckout ? `node dist/cli.js install ${flags}` : `npx -y scenescout install ${flags}`;
+}
+/**
+ * Whether pages may register service workers in this browser.
+ *
+ * The write policy works by intercepting requests. Only Chromium lets the
+ * driver intercept a request a service worker issues; in Firefox and WebKit
+ * such a request goes straight to the network, so an app that syncs its writes
+ * from a worker would send a DELETE through read-only mode with nothing
+ * logged. Blocking registration there makes the page send those requests
+ * itself, where the policy sees them.
+ */
+export function serviceWorkerPolicy(engine) {
+    return engine === "chromium" ? "allow" : "block";
+}
+/**
+ * How the live view gets frames of a page.
+ *
+ * Chromium can push a frame on every repaint through the DevTools protocol,
+ * which costs nothing while the page sits still. Firefox and WebKit have no
+ * such channel in the driver, so a stream there is a screenshot taken on a
+ * timer for as long as somebody is watching.
+ */
+export function screencastSupport(engine) {
+    return engine === "chromium" ? "cdp" : "poll";
+}
+/**
+ * The key that moves keyboard focus to the next control, links and buttons
+ * included. WebKit on macOS follows Safari: plain Tab stops only at text
+ * fields, and Option+Tab stops everywhere. A focus audit that pressed Tab
+ * there would walk past every button and report nothing.
+ */
+export function focusAdvanceKey(engine, platform) {
+    return engine === "webkit" && platform === "darwin" ? "Alt+Tab" : "Tab";
+}
+/**
+ * Run in every page before its own scripts: takes shared workers away.
+ *
+ * A request issued by a shared worker cannot be intercepted in any browser, so
+ * a write sent from one passes the policy unseen and unlogged. Removing the
+ * constructor makes feature detection fail, and an app then does that work on
+ * the page, where the policy sees it. Not applied in `destructive` mode, where
+ * the policy blocks nothing and the person has opted in to everything.
+ */
+export const REMOVE_SHARED_WORKER_SCRIPT = `(() => {
+  try { delete globalThis.SharedWorker; } catch {}
+  if ("SharedWorker" in globalThis) {
+    try { Object.defineProperty(globalThis, "SharedWorker", { value: undefined, configurable: true, writable: true }); } catch {}
+  }
+})()`;
+/** Whether pages may use shared workers in this write mode. */
+export function sharedWorkersAllowed(mode) {
+    return mode === "destructive";
+}
+/**
+ * What install says when the browsers it was asked for do not include the one
+ * a default attach launches, and that one is not on disk either. Without it,
+ * `install --browsers firefox` on a fresh machine ends in "ready" and the first
+ * attach fails. Null when there is nothing to say.
+ */
+export function defaultAttachNote(opts) {
+    if (opts.defaultInstalled || opts.selected.length === 0)
+        return null;
+    if (opts.selected.some((t) => engineOf(t) === opts.defaultEngine))
+        return null;
+    const engine = engineOf(opts.selected[0]);
+    return (`an attach drives ${opts.defaultEngine} unless told otherwise, and that build is not installed. ` +
+        `Pass browser: "${engine}" when attaching, or set ${DEFAULT_ENGINE_ENV}=${engine} in the MCP server's environment.`);
+}