scenescout 1.2.0 → 1.4.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # scenescout
 
+## 1.4.0
+
+### Minor Changes
+
+- 01fe452: The engine now notices when a value it typed comes back as markup. Any markup-shaped value the agent types — `<script>…</script>`, `<img src=x onerror=…>`, a `<b>` — is remembered by shape, and every page seen afterwards is checked for an element of that shape. When one is found, a `dom_injection` violation (severity high) names the field it was typed into, the page it was typed on, the page it rendered on and the element it became: whoever opens that page runs the input, which is a stored or reflected XSS. The oracle never chooses what to type; the method asks for markup in the fuzzing pass, and the rest is the agent's judgment.
+
+### Patch Changes
+
+- 2deca2a: Two findings that name the same endpoint no longer merge unless both name a failure status for it. A double submit and an accepted bad value can both mention `POST /api/orders` and are two bugs; the second one filed used to be absorbed into the first without a trace.
+- 4e10197: The live view's header keeps its two buttons together when it wraps on a narrow screen, numbers that tick every second (badges, feed times, the session counts) use tabular numerals so they no longer jitter, the feed's journey groups are marked by their tint with a hairline rather than a stripe, and the scrolling panels and text selection take the page's own palette.
+- 978022a: Every record a session creates is now named in the result of the action that created it (`created: /api/things id=44`), including the second and later ones on an endpoint. The state-changing-request notice reports each endpoint once per session, which in safe-write mode hid every creation after the first, so the agent could not tell from the result that it had just made one.
+- dd8927a: `scout_run_plan` now prints a type step's note about the field (such as "replaced existing content") on that step's own line. It used to appear under the previous step, so a reader concluded the wrong field was prefilled.
+
+## 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

package/README.md

@@ -35,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):
 
@@ -46,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.
 
@@ -136,9 +139,10 @@ Then download the browser once with `npx -y scenescout install --browser-only`.
 
 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 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`.
+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:
 
@@ -179,6 +183,32 @@ The agent scans the project (if there is one), attaches read-only, explores, and
 
 ---
 
+## 📺 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:
@@ -457,7 +487,8 @@ 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
 ```
 
 ---
@@ -475,6 +506,7 @@ src/
     probes.ts       in-page scroll + overlay + focus probes (needs a browser too)
     fingerprint.ts  route + element-set identity (state hashing)
     oracles.ts      console/page/network/HTTP error detection
+    injection.ts    the DOM-injection oracle's rules (what to watch for, how to find it)
     policy.ts       the write-policy safety net
     ownership.ts    safe-write: which records did this run create?
     uploads.ts      disk uploads, fenced to the project by real path
@@ -514,12 +546,12 @@ Working on SceneScout itself is the only reason to clone it:
 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,
+npm test           # build + 14 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 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
 
@@ -535,7 +567,7 @@ Found a way past the write policy, or another security problem? Please report it
 - **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.
+- **Oracles after every action.** Console errors, page errors, failed requests, HTTP 4xx/5xx drained into every tool result — and DOM injection: a markup-shaped value the agent typed that later renders as an element on any page (stored or reflected XSS).
 - **Multi-role, genuinely concurrent.** Commands to *different* sessions run in parallel; safe-write ownership is shared, so role A can create what role B approves. The report renders a role capability matrix.
 - **Task ease, not just correctness.** `scout_journey` measures interaction cost, distinct screens, path, and backtracks.
 - **Design audit with page scores.** Two tiers (⚠ measurable defects / → craft suggestions incl. AI-slop tells), per-page 0–100 score persisted per route, plus an automatic overlay/modal probe on every snapshot. Shared shell scored once, separately.
@@ -545,6 +577,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

@@ -140,6 +140,17 @@ export function installCommandFor(target, fromCheckout) {
 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

package/dist/cli.js

@@ -15,8 +15,9 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { APPROX_DISK_MB, BROWSER_ENGINES, browserPresence, defaultAttachNote, defaultEngine, launchTarget, parseBrowserSelection, playwrightInstallArgs, } from "./browsers.js";
 import { CLIENT_LABELS, firstMessageHint, manualFor, parseClients, registerWithClient, vscodeBinary } from "./clients.js";
-import { diagnose, installSkill, launchCommand, manualRegisterCommand, registerMcp, resolveClaudeDir, spawnRunner } from "./installer.js";
+import { CLI_NAME, diagnose, ensureCommand, findOnUserPath, installSkill, isEphemeralRoot, launchCommand, manualRegisterCommand, planCommand, registerMcp, resolveClaudeDir, spawnRunner, } from "./installer.js";
 import { LEGACY_MEMORY_DIRNAME, MEMORY_DIRNAME } from "./engine/memory.js";
+import { formatStatus, localClock, LIVE_TOKEN_FILE, watchTarget } from "./engine/live.js";
 import { formatScan, scanProject } from "./scan.js";
 const here = path.dirname(fileURLToPath(import.meta.url));
 const packageRoot = path.resolve(here, "..");
@@ -27,7 +28,8 @@ Usage:
   scenescout scan <projectPath>     Discover framework, routes, auth states
   scenescout serve                  Run the MCP server (stdio)
   scenescout install                One-step setup: skill + Chromium + MCP registration
-                                    (--skip-browser, --no-register to opt out of a step;
+                                    It also puts the \`scenescout\` command on your PATH.
+                                    (--skip-browser, --no-register, --no-command to opt out of a step;
                                      --browser-only when the skill and server came from a plugin;
                                      --browsers <list> to choose what to download: chromium (default),
                                      chromium-headless-shell, firefox, webkit, all — comma-separated)
@@ -37,52 +39,67 @@ Usage:
   scenescout doctor                 Check the setup and print the fix for anything missing
                                     (--engine: only node, the build and the browser — for plugin
                                      installs and other MCP clients)
-  scenescout status [projectPath]   What is the engine doing right now? (live status + recent actions)
+  scenescout status [projectPath]   What is the engine doing right now? (every session + recent actions)
+  scenescout watch [projectPath]    Open the live view in a browser: what each session is doing, a thumbnail
+                                    of its page, and a live stream you can switch on per session
+                                    (--no-open to print the address only)
 `);
     process.exit(exitCode);
 }
-/** Realtime observability: read the status file + recent action log the running engine maintains. */
-function status(projectPath) {
-    // A project last touched before the rename (or one a pre-rename engine is
-    // using right now) still keeps its status under the legacy directory.
-    const dir = [MEMORY_DIRNAME, LEGACY_MEMORY_DIRNAME]
+/**
+ * A project last touched before the rename (or one a pre-rename engine is using
+ * right now) still keeps its status under the legacy directory.
+ */
+function statusDir(projectPath) {
+    return ([MEMORY_DIRNAME, LEGACY_MEMORY_DIRNAME]
         .map((name) => path.join(projectPath, name))
-        .find((candidate) => fs.existsSync(path.join(candidate, "status.json"))) ?? path.join(projectPath, MEMORY_DIRNAME);
+        .find((candidate) => fs.existsSync(path.join(candidate, "status.json"))) ?? path.join(projectPath, MEMORY_DIRNAME));
+}
+/** null when there is no file; "unreadable" when there is one and it does not parse. */
+function readStatusFile(dir) {
     const statusPath = path.join(dir, "status.json");
-    if (!fs.existsSync(statusPath)) {
-        console.log(`No status file at ${statusPath} — no SceneScout engine has attached to this project (or it predates v0.8).`);
-        return;
-    }
-    let st;
+    if (!fs.existsSync(statusPath))
+        return null;
     try {
-        st = JSON.parse(fs.readFileSync(statusPath, "utf8"));
+        return JSON.parse(fs.readFileSync(statusPath, "utf8"));
     }
     catch {
         // status.json is written fire-and-forget on every tool call, so a process
         // killed mid-write leaves a truncated file. That is a diagnosable state,
         // not a reason for the diagnostic tool itself to crash.
-        console.log(`Status file at ${statusPath} is unreadable or truncated — the engine was probably killed mid-write. Re-attach to refresh it.`);
+        return "unreadable";
+    }
+}
+function pidAlive(pid) {
+    if (!pid)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        // EPERM means the process EXISTS but belongs to another user — only
+        // ESRCH actually means "no such process". Treating both as dead reported
+        // a live engine as stale.
+        return err?.code === "EPERM";
+    }
+}
+/** Realtime observability: read the status file + recent action log the running engine maintains. */
+function status(projectPath) {
+    const dir = statusDir(projectPath);
+    const statusPath = path.join(dir, "status.json");
+    const st = readStatusFile(dir);
+    if (st === null) {
+        console.log(`No status file at ${statusPath} — no SceneScout engine has attached to this project (or it predates v0.8).`);
         return;
     }
-    let alive = false;
-    if (st.pid) {
-        try {
-            process.kill(st.pid, 0);
-            alive = true;
-        }
-        catch (err) {
-            // EPERM means the process EXISTS but belongs to another user — only
-            // ESRCH actually means "no such process". Treating both as dead reported
-            // a live engine as stale.
-            alive = err?.code === "EPERM";
-        }
+    if (st === "unreadable") {
+        console.log(`Status file at ${statusPath} is unreadable or truncated — the engine was probably killed mid-write. Re-attach to refresh it.`);
+        return;
     }
-    const age = st.at ? Math.round((Date.now() - new Date(st.at).getTime()) / 1000) : null;
-    console.log(`Engine pid ${st.pid ?? "?"} — ${alive ? "ALIVE" : "not running (stale status)"}`);
-    console.log(`${st.phase === "running" ? "⏳ running" : "· idle after"}: ${st.tool ?? "?"}${age !== null ? ` (as of ${age}s ago)` : ""}`);
-    console.log(`Session: ${st.session ?? "?"} (${st.role ?? "?"})${st.sessions && st.sessions.length > 1 ? ` · all sessions: ${st.sessions.join(", ")}` : ""}`);
-    if (st.url)
-        console.log(`URL: ${st.url}`);
+    const alive = pidAlive(st.pid);
+    for (const line of formatStatus(st, alive, Date.now()))
+        console.log(line);
     // Recent actions from the newest session log — the "what has it been doing" trail.
     const logs = fs.existsSync(dir)
         ? fs
@@ -108,7 +125,7 @@ function status(projectPath) {
         for (const line of lines) {
             try {
                 const e = JSON.parse(line);
-                console.log(`  ${e.at.slice(11, 19)} ${e.action}${e.target ? ` ${e.target}` : ""} @ ${e.url}`);
+                console.log(`  ${localClock(e.at)} ${e.action}${e.target ? ` ${e.target}` : ""} @ ${e.url}`);
             }
             catch {
                 /* skip malformed line */
@@ -116,6 +133,43 @@ function status(projectPath) {
         }
     }
 }
+/** Open the engine's live view. The engine serves it; this only finds the address and hands it to a browser. */
+function watch(projectPath, open) {
+    const dir = statusDir(projectPath);
+    const st = readStatusFile(dir);
+    let token = null;
+    try {
+        token = fs.readFileSync(path.join(dir, LIVE_TOKEN_FILE), "utf8");
+    }
+    catch {
+        // watchTarget explains a missing token in context.
+    }
+    const target = watchTarget({ status: st, alive: st !== null && st !== "unreadable" && pidAlive(st.pid), token });
+    if ("problem" in target) {
+        console.log(target.problem);
+        process.exitCode = 1;
+        return;
+    }
+    console.log(`Live view: ${target.url}`);
+    console.log("It is served on this machine only, and the address holds its access token: treat it like a password.");
+    if (!open)
+        return;
+    const { command, args } = browserOpener(target.url);
+    const result = spawnSync(command, args, { stdio: "ignore" });
+    if (result.error || result.status !== 0)
+        console.log("Could not open a browser from here. Open the address above yourself.");
+}
+/** The platform's own "open this URL" command. */
+function browserOpener(url) {
+    switch (process.platform) {
+        case "darwin":
+            return { command: "open", args: [url] };
+        case "win32":
+            return { command: "cmd", args: ["/c", "start", "", url] };
+        default:
+            return { command: "xdg-open", args: [url] };
+    }
+}
 /** Which browser builds are on disk, going by the paths Playwright reports for the version we depend on. */
 async function presentBrowsers() {
     const executables = { chromium: null, firefox: null, webkit: null };
@@ -303,8 +357,39 @@ async function install(flags) {
             }
         }
     }
+    // `scenescout status`, `watch` and `doctor` are typed by a person, and neither
+    // a checkout nor an npx run leaves the command on PATH. Not having it costs
+    // convenience, never a working setup, so this step reports and does not fail.
+    let cli = isEphemeralRoot(packageRoot) ? `npx -y ${CLI_NAME}` : `node ${path.join(packageRoot, "dist", "cli.js")}`;
+    if (browserOnly) {
+        // a plugin install has no package of its own to put on PATH
+    }
+    else if (flags.includes("--no-command")) {
+        console.log(`· Putting \`${CLI_NAME}\` on PATH skipped (--no-command). Until then the command is:  ${cli}`);
+    }
+    else {
+        const onPath = () => findOnUserPath({ names: process.platform === "win32" ? [`${CLI_NAME}.cmd`] : [CLI_NAME], pathValue: process.env.PATH ?? "" });
+        const pkg = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8"));
+        const done = ensureCommand(planCommand({ packageRoot, nodePath: process.execPath, version: pkg.version, resolved: onPath(), platform: process.platform }), spawnRunner);
+        if (done.status === "present") {
+            cli = CLI_NAME;
+            console.log(`✓ \`${CLI_NAME}\` command already on PATH: ${done.at}`);
+        }
+        else if (done.status === "installed") {
+            const at = onPath();
+            if (at)
+                cli = CLI_NAME;
+            const what = done.how === "link" ? "linked to this checkout, so it runs whatever was last built" : "installed globally";
+            console.log(at
+                ? `✓ \`${CLI_NAME}\` command ${what}: ${at}${done.replaced ? `   (it replaces ${done.replaced})` : ""}`
+                : `· \`${CLI_NAME}\` was ${what}, but npm's global bin directory is not on this shell's PATH. Add it (\`npm prefix -g\` names it; the commands are in its bin folder), or use:  ${cli}`);
+        }
+        else {
+            console.log(`· \`${CLI_NAME}\` was not put on PATH (${done.detail}). To do it by hand:  ${done.manual}\n  Until then the command is:  ${cli}`);
+        }
+    }
     if (failed) {
-        console.log(`\nSetup is incomplete — fix the lines marked ✗ or · above, then run:  scenescout doctor${forClaude ? "" : " --engine"}`);
+        console.log(`\nSetup is incomplete — fix the lines marked ✗ or · above, then run:  ${cli} doctor${forClaude ? "" : " --engine"}`);
         process.exitCode = 1;
         return;
     }
@@ -317,7 +402,7 @@ async function install(flags) {
     // Telling someone to restart a client nothing was registered with sends them looking for a server that is not there.
     if (others.length > 0 && !flags.includes("--no-register"))
         console.log(`\n${firstMessageHint(others)}`);
-    console.log(`Something off? Run:  scenescout doctor${forClaude ? "" : " --engine"}`);
+    console.log(`Something off? Run:  ${cli} doctor${forClaude ? "" : " --engine"}`);
 }
 async function doctor(flags) {
     const checks = diagnose({
@@ -387,6 +472,11 @@ try {
             status(path.resolve(args[0] ?? process.cwd()));
             break;
         }
+        case "watch": {
+            const positional = args.filter((a) => !a.startsWith("--"));
+            watch(path.resolve(positional[0] ?? process.cwd()), !args.includes("--no-open"));
+            break;
+        }
         default:
             usage();
     }