scenescout 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # scenescout
 
+## 1.1.0
+
+### Minor Changes
+
+- d3ebd73: Snapshots now list images that failed to load, under `BROKEN IMAGES`, read from the DOM. This catches an image whose URL answers 200 with something that is not an image, which the HTTP oracle cannot see because no request failed. Images that occupy no space (inside a closed panel, tracking pixels) are not reported.
+  
+  An `<img>` is now named by its alt text and listed with the role `image`; it previously appeared as `generic "(unnamed)"`. For the uncommon `<img>` that is collected without a `data-testid` (one with `onclick` or an explicit role), this changes its element key, so states containing it are seen as new once.
+- 5706a55: `scout_scan` now reads routes from source for React Router, Vue Router and Angular projects, including nested children, `<Route>` elements and Angular `loadChildren` files. These projects previously started with an empty route list and relied on link discovery alone, so a page nothing linked to was outside the completion contract. The reader is static and skips anything it cannot resolve: computed paths, spreads, identifiers, and relative paths whose parent is unknown.
+- 6b6b786: The geometry oracle now reports a pinned control that sits underneath other pinned chrome, for example a sticky Save row covered by a fixed bar. Box overlap cannot tell which of two pinned elements is on top, so that pair was skipped; the new check hit-tests the control's centre in the page. It stays quiet for controls inside a scrollable pane, for dialogs, and for overlays covering half the viewport.
+- 0d320b1: New write mode `observe` (`--observe`): nothing but `GET`, `HEAD` and `OPTIONS` requests leaves the page, except logging in, logging out and refreshing a token. Signing up and password changes are blocked. WebSocket frames are not inspected, and the engine says so when the app opens one. `read-only` lets an ordinary form `POST` through, which on a target holding real data creates a record. The skill now attaches in `observe` for a remote URL with no source unless told that form submissions are acceptable. Forms that could not be submitted stay in the gap ledger, worded as the mode's doing.
+
+### Patch Changes
+
+- 0d320b1: The login exemption in the write policy no longer applies to destructive-looking requests in any mode. A path that merely contained a word such as `session` or `auth` previously carried a request like `POST /api/session/123/delete` through `read-only`. A form navigation blocked by the write policy is now reported as blocked; it was reported as an off-origin navigation, and the follow-up note blamed the app for discarding data.
+- 4107696: `scenescout doctor` now suggests `npx -y scenescout install` when the tool was installed from npm. It previously suggested `npm run setup`, which exists only in a source checkout.
+
 ## 1.0.0
 
 ### Major Changes

package/README.md

@@ -5,6 +5,7 @@
 **Exploratory UI testing, driven by an AI agent.**
 
 [![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)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 ![node >= 20](https://img.shields.io/badge/node-%E2%89%A5%2020-339933?logo=node.js&logoColor=white)
 ![MCP server](https://img.shields.io/badge/MCP-server-8A2BE2)
@@ -28,9 +29,11 @@ Scripted E2E suites answer one question — *"does this exact flow still work?"*
 
 ## 👀 See it work
 
-This is a real run against the small demo app bundled in this repository. The screenshot was taken by SceneScout; the badge sitting on top of a button and the missing chart are two of the nine findings it filed.
+This is a real run against the small demo app bundled in this repository. The app has bugs planted in it on purpose, and two of them are visible on its dashboard:
 
-<p align="center"><img src="examples/screenshots/dashboard.png" alt="The demo app's dashboard: a yellow badge covers the All orders button, and the weekly chart image is broken" width="720" /></p>
+<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.
 
 An excerpt of the report it wrote — [read the whole thing](examples/report.md):
 
@@ -41,19 +44,22 @@ 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`
 >
-> **🟠 [MEDIUM] The "New: bulk import" badge sits on top of the All orders button**
+> **🟠 [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
 
-Every finding comes with a repro trace and a Playwright regression-test skeleton. Try it yourself in two minutes: `npm run demo:serve`, then `/scenescout --url http://127.0.0.1:4173` — see [demo-app/](demo-app/). It also documents [one defect the tool deliberately does not flag](demo-app/README.md#what-it-deliberately-does-not-catch).
+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.
 
 ---
 
 ## ✨ 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.
-- 📐 **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. (Screenshots exist only for pixel-native residue like broken images.)
+- 📐 **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.
 - 🧭 **It remembers.** UI states are fingerprinted and stored in the project's `.scenescout/`. Run N+1 skips what run N already covered, and every run starts smarter than the last.
@@ -68,13 +74,13 @@ SceneScout needs only a URL. Give it the source code as well and it gets noticea
 |---|---|---|
 | **You run it from** | the app's repository | any folder — an empty `qa/` directory is fine |
 | **It plays the role of** | a developer-tester who can read the code | a black-box QA tester, like a person with a browser |
-| **How it finds pages** | 📂 reads file-based routes from the source (Next.js, SvelteKit, Nuxt) **and** follows links. Code-routed apps fall back to links | 🔗 follows same-origin links only — pages nothing links to, or on another subdomain, stay unknown |
+| **How it finds pages** | 📂 reads routes from the source **and** follows links: file-based routing (Next.js, SvelteKit, Nuxt) and router configuration written in code (React Router, Vue Router, Angular). Routes built at runtime are not seen | 🔗 follows same-origin links only — pages nothing links to, or on another subdomain, stay unknown |
 | **"Did we cover everything?"** | checked against the routes found in source *plus* discovered links — an unvisited one blocks the report | checked against the pages it managed to discover |
 | **Setup it figures out** | framework, dev command, saved Playwright logins (`playwright/.auth/`), whether the app uses `data-testid` | none — you pass the URL, and the path to a login state if the app needs one |
 | **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 — and a file-routed framework — 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 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 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.
 
@@ -87,7 +93,7 @@ SceneScout needs only a URL. Give it the source code as well and it gets noticea
 ```
 
 > [!IMPORTANT]
-> Only test sites you own or are authorized to test. A remote environment is more likely to hold real data. The default **read-only** mode blocks `PUT`/`PATCH`/`DELETE` and destructive-looking requests, but an ordinary form submission (a plain `POST`: contact form, comment, order, signup) still reaches the server and can create a record. On a site with real data, tell the agent which forms not to submit. See the [safety model](#-safety-model).
+> Only test sites you own or are authorized to test. A remote environment is more likely to hold real data, so for a remote URL with no source the skill attaches in **`observe`** mode: nothing but `GET` requests leaves the page. The default **read-only** mode blocks `PUT`/`PATCH`/`DELETE` and destructive-looking requests, but an ordinary form submission (a plain `POST`: contact form, comment, order, signup) still reaches the server and can create a record. Say so when that is acceptable on your target. See the [safety model](#-safety-model).
 
 ---
 
@@ -103,39 +109,29 @@ SceneScout needs only a URL. Give it the source code as well and it gets noticea
 
 ### 1️⃣ Install
 
-Pick one. All three end with the same 24 tools.
+It is on npm. Nothing to clone:
 
-**A · Claude Code plugin** — the skill and the server in one step:
+```bash
+npx -y scenescout install      # skill + Chromium (~150 MB, one-time) + registers the server with Claude Code
+```
+
+**Prefer a Claude Code plugin?** The skill and the server arrive together:
 
 ```
 /plugin marketplace add brunoboto96/SceneScout
 /plugin install scenescout@scenescout-marketplace
 ```
 
-Then download the browser once: `npx -y scenescout install --browser-only`. The command is `/scenescout:scenescout`.
-
-**B · npm, for Claude Code or any other MCP client:**
+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.
 
-```bash
-npx -y scenescout install      # skill + Chromium (~150 MB, one-time) + registers the server with Claude Code
-```
-
-Using a different client? Skip the registration and [add the server to its config](#-other-mcp-clients) instead: `npx -y scenescout install --browser-only`.
-
-**C · From source**, to hack on it:
-
-```bash
-git clone https://github.com/brunoboto96/SceneScout.git scenescout && cd scenescout
-npm install        # installs dependencies and builds
-npm run setup      # same as `scenescout install`, pointed at this checkout
-```
+**Another MCP client?** Run `npx -y scenescout install --browser-only` and [add the server to its config](#-other-mcp-clients).
 
 <details>
-<summary>What <code>install</code> / <code>npm run setup</code> actually does</summary>
+<summary>What <code>install</code> actually does</summary>
 
-1. links 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. When run through `npx` it copies instead of linking, because the npx cache is temporary,
+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, using an **absolute** node path so it works under nvm/fnm.
+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`.
 
 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`.
 
@@ -150,15 +146,15 @@ claude mcp add --scope user scenescout -- npx -y scenescout serve
 ### 2️⃣ Check it
 
 ```bash
-npx -y scenescout doctor            # routes B and C (from source: npm run doctor)
-npx -y scenescout doctor --engine   # route A, or another MCP client: node + build + browser only
+npx -y scenescout doctor            # everything, for the default install
+npx -y scenescout doctor --engine   # plugin install or another MCP client: node + build + browser only
 ```
 
 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.
 
 ### 3️⃣ Run it
 
-No app handy? `npm run demo:serve` in a source checkout starts the [demo app](demo-app/) on `http://127.0.0.1:4173`.
+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):
 
@@ -168,7 +164,7 @@ From Claude Code, inside the project you want to test (or, for a [remote URL](#-
 
 The skill 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) · `--safe-write` / `--allow-destructive`.
+**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`.
 
 ---
 
@@ -234,6 +230,7 @@ That refusal *is* the guarantee: an extensive report can only exist when nothing
 
 ## 🔒 Safety model
 
+- 🔵 **`observe`** (`--observe`) lets nothing but `GET` requests leave the page. The one exception is what a session needs in order to exist: logging in, logging out and refreshing a token. Signing up, changing or resetting a password and creating users are blocked like any other write. WebSocket frames are not inspected; the engine says so when the app opens a socket. It is what the skill picks for a remote URL with no source, where an ordinary form POST would create a real record. Forms that could not be submitted are listed in the gap ledger.
 - 🟢 **`read-only` by default.** Destructive-labeled elements (delete/revoke/archive/…) **and** all `PUT/PATCH/DELETE` + destructive `POST`s are blocked at the network layer — see [`src/engine/policy.ts`](src/engine/policy.ts). Non-destructive `POST`s are allowed, because submitting forms is how a tester finds validation bugs — so read-only means *nothing existing is changed or removed*, not *nothing is ever created*.
 - 🟡 **`safe-write`** (`--safe-write`) lets the agent create data and edit/delete **only what it created** this run — never pre-existing records.
 - 🔴 **`destructive`** (`--allow-destructive`) allows everything, and only ever when *you* confirm the environment is disposable. The skill will never choose this itself.
@@ -258,22 +255,22 @@ A `🛡 WRITE-POLICY blocked` notice is the safety net doing its job, not an app
 
 ## 🩺 Troubleshooting
 
-Run `npm run doctor` first — it checks every setup item below (everything but the last row, which is about your app) and prints the fix.
+Run `npx -y scenescout doctor` first — it checks every setup item below (everything but the last row, which is about your app) and prints the fix.
 
 | Symptom | Cause and fix |
 |---|---|
-| `/scenescout` isn't a known command | The skill isn't linked, or the session predates it. `npm run setup`, then start a **fresh** Claude Code session. |
-| The `scout_*` tools don't appear | The MCP server isn't registered, or points at an old path. `npm run setup` re-registers it; `claude mcp list` should show `scenescout` as connected. |
-| `npm install` fails at the build step | The build needs the dev dependencies (TypeScript). Don't pass `--omit=dev` or set `NODE_ENV=production` when installing from a clone. |
-| *"Executable not found in $PATH"* | The server was registered with a bare `node`. `npm run setup` registers the absolute path. |
+| `/scenescout` isn't a known command | The skill isn't linked, or the session predates it. `npx -y scenescout install`, then start a **fresh** Claude Code session. |
+| 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`). |
-| Tools broke after moving the folder or changing node version | The registration stores absolute paths. `npm run setup` refreshes them. |
+| 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. |
 
 ### ⬆️ Upgrading from an older version
 
-- **Tools are now `scout_*`.** Up to v0.23 they were prefixed `ft_`. The rename happened before the first npm release, with no aliases, so an agent's context carries one tool list rather than two. Re-run `npm run setup` so the installed skill matches the server.
-- **Earlier names.** This tool was previously called SceneCraft (and, before that, frontend-tester). `npm run setup` cleans up after both: it removes the old skill link and the old `scenecraft` MCP registration when they point at this install, and the first attach in a project moves its `.scenecraft/` memory folder to `.scenescout/` so earlier coverage and findings carry over.
+- **Tools are now `scout_*`.** Up to v0.23 they were prefixed `ft_`. The rename happened before the first npm release, with no aliases, so an agent's context carries one tool list rather than two. Re-run `npx -y scenescout install` so the installed skill matches the server.
+- **Earlier names.** This tool was previously called SceneCraft (and, before that, frontend-tester). `scenescout install` cleans up after both: it removes the old skill link and the old `scenecraft` MCP registration when they point at this install, and the first attach in a project moves its `.scenecraft/` memory folder to `.scenescout/` so earlier coverage and findings carry over.
 
 ### 🧹 Uninstall
 
@@ -282,13 +279,13 @@ claude mcp remove --scope user scenescout
 rm -rf ~/.claude/skills/scenescout
 ```
 
-Then delete the clone. Per-project memory lives in each tested project's `.scenescout/` folder; delete it there if you want it gone.
+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.
 
 ---
 
 ## 🔌 Other MCP clients
 
-The engine is a plain MCP server over stdio, so any client can drive it. 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. 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`.
 
 <details>
 <summary><strong>Cursor</strong> — <code>~/.cursor/mcp.json</code> (or <code>.cursor/mcp.json</code> in a project)</summary>
@@ -327,10 +324,62 @@ args = ["-y", "scenescout", "serve"]
 
 </details>
 
+<details>
+<summary><strong>Gemini CLI</strong> — <code>~/.gemini/settings.json</code> (or <code>.gemini/settings.json</code> in a project)</summary>
+
+```json
+{
+  "mcpServers": {
+    "scenescout": { "command": "npx", "args": ["-y", "scenescout", "serve"] }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><strong>Windsurf</strong> — <code>~/.codeium/windsurf/mcp_config.json</code></summary>
+
+```json
+{
+  "mcpServers": {
+    "scenescout": { "command": "npx", "args": ["-y", "scenescout", "serve"] }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><strong>Cline</strong> — MCP Servers → Configure → Configure MCP Servers (or <code>~/.cline/mcp.json</code> for the CLI)</summary>
+
+```json
+{
+  "mcpServers": {
+    "scenescout": { "command": "npx", "args": ["-y", "scenescout", "serve"], "disabled": false, "autoApprove": [] }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><strong>Zed</strong> — <code>settings.json</code> (command palette: <code>zed: open settings file</code>)</summary>
+
+```json
+{
+  "context_servers": {
+    "scenescout": { "command": "npx", "args": ["-y", "scenescout", "serve"], "env": {} }
+  }
+}
+```
+
+</details>
+
 <details>
 <summary><strong>Anything else</strong></summary>
 
-Most clients accept the same `mcpServers` JSON shape shown for Cursor. From a source checkout, the command is `node` with the absolute path to `dist/mcp-server.js`.
+Most clients accept the same `mcpServers` JSON shape shown for Cursor.
 
 </details>
 
@@ -366,7 +415,7 @@ src/
     memory.ts       cross-run storage + finding dedup
     report.ts       the gap ledger + report generation
     …               collector · dispatch · fixtures · authloss · reaper
-scripts/            the 11 test suites (smoke/ holds the real-browser ones)
+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)
 docs/adr/           why it's built this way
@@ -391,14 +440,18 @@ The load-bearing choices are recorded as ADRs — read the relevant one before c
 
 ## 🔧 Development
 
+Working on SceneScout itself is the only reason to clone it:
+
 ```bash
-npm run build     # tsc
-npm test          # build + 11 suites: scan, oracle, policy, fixture, dispatch, design,
-                  #                     contract, memory, install, smoke, mcp-check
-npm run dev       # run the CLI from source (tsx)
+git clone https://github.com/brunoboto96/SceneScout.git scenescout && cd scenescout
+npm install        # installs dependencies and builds
+npm run setup      # same as `scenescout install`, but registers THIS checkout (the skill is linked, so edits are live)
+npm test           # build + 12 suites: scan, oracle, policy, fixture, dispatch, design,
+                   #                     contract, memory, install, hygiene, smoke, mcp-check
+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 run build && npm test` must pass before committing.
+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.
 
 ## 🔐 Security
 
@@ -411,7 +464,7 @@ Found a way past the write policy, or another security problem? Please report it
 <details>
 <summary><strong>Full capability list</strong> — every behavior, for the curious</summary>
 
-- **Structured render-state, not pixels.** Element lists with geometry; screenshots reserved for pixel-native residue (broken images, canvas).
+- **Structured render-state, not pixels.** Element lists with geometry; screenshots reserved for pixel-native residue (canvas, rendering glitches). Images that failed to load are reported from the DOM, including ones whose URL answered 200 with something that is not an image.
 - **Diff snapshots with stable refs.** Re-snapshots return only what changed (10.7 kB → 0.7 kB on a 130-element page); old refs stay valid.
 - **Geometry oracles.** Overlap and off-screen defects computed from layout boxes.
 - **Oracles after every action.** Console errors, page errors, failed requests, HTTP 4xx/5xx drained into every tool result.

package/dist/cli.js

@@ -187,7 +187,7 @@ async function install(flags) {
         }
     }
     if (failed) {
-        console.log("\nSetup is incomplete — fix the lines marked ✗ or · above, then run:  npm run doctor");
+        console.log("\nSetup is incomplete — fix the lines marked ✗ or · above, then run:  scenescout doctor");
         process.exitCode = 1;
         return;
     }
@@ -196,7 +196,7 @@ async function install(flags) {
         return;
     }
     console.log("\nStart a FRESH Claude Code session, then in any project run:  /scenescout");
-    console.log("Something off? Run:  npm run doctor");
+    console.log("Something off? Run:  scenescout doctor");
 }
 async function doctor(flags) {
     const checks = diagnose({