scenescout 3.15.0 → 3.17.0

package/CHANGELOG.md

@@ -1,5 +1,92 @@
 # scenescout
 
+## 3.17.0
+
+### Minor Changes
+
+- b0709f0: `scenescout check` accepts `--ignore-path`: a path drops every rule filed on that route, and `rule:/path` drops that one rule there. A page meant to answer HTTP 500 can stay off the gate while the same status on another path still fails `--fail-on high`. The GitHub Action takes the same input.
+- 547d006: Add the `live` and `login` MCP prompts. `live` returns the current session's loopback live-view URL. `login` takes a role and tells the agent to call `scout_login`, with no password argument.
+- 7ba8712: Add `scout_status`, a run-status pane built as an MCP App (`io.modelcontextprotocol/ui`, specification 2026-01-26). In a client that renders MCP Apps it shows each session's objective and task, open findings by severity, coverage and a button for the live view, and refreshes itself every 2.5 seconds through the app-only `scout_status_poll` tool. Every other client gets the same as text, starting with the live view's loopback address. The pane's page loads nothing from outside and shows only what the live view already shows.
+
+### Patch Changes
+
+- 745a38e: On Windows, `scenescout install --client` starts an npm-installed client (a `.cmd` or `.bat` shim) through `cmd.exe`, so registration runs the client's own command instead of stopping and printing it to run by hand.
+
+## 3.16.0
+
+### Minor Changes
+
+- 8dacac8: `scout_select` matches the value against the dropdown's options before picking: an exact value or label, either ignoring case, then a label it starts with ("Low" picks "Low — minor impact"). A value that matches no option, or several, is refused at once with the options listed, instead of waiting out the action limit. Typing into a date or time field puts an obvious near miss in the field's format (a plain date into a date-and-time field is entered at T00:00) and refuses anything else naming the format the field takes, instead of failing with "Malformed value". A click forced past something on top of its target names that element, and says when it came after a write-policy block. `scout_run_plan` takes `onViolation: "continue"` for a sweep of independent steps: a new error status is listed on its step's line and the plan goes on, while a failed step, a policy refusal or any other violation still stops it.
+- 11fa895: A run can answer the tickets it was given. `scout_tickets` reads acceptance criteria from pasted text or a ticket file (`.md`, `.txt`, `.feature`): Given/When/Then scenarios, checklists, numbered or `AC1:` criteria, and lists under an "Acceptance criteria" heading; a ticket with none of these is reported as having no recognisable criteria rather than guessed at. `scout_criterion` records each criterion as passed, failed (linked to the findings that show it) or not tested (`no-access`, `observe-blocked` or `out-of-scope`), with the agent's confidence. The report answers each ticket at the top of the plain section, with a failing criterion's pictures, and lists every verdict with its confidence in a new "Acceptance criteria" section of the technical report. A parallel run's lane briefs list the criteria, and the plain questions' "what to check" reads tickets this way.
+- 9ebbce6: Add visual regression baselines to `scenescout check`. List pages and elements in a `targets.json` in the baselines folder (`page`, or an element named the way a saved flow names its target), take their pictures with `--baseline update`, and `--baseline compare` takes them again and compares pixel by pixel: a picture where more pixels changed than `--baseline-threshold` allows (default 0.1%, so anti-aliasing noise between machines and browser builds does not fail the gate; `0` counts every changed pixel), whose size changed, or that could not be taken is a high `visual-change` issue that fails the default gate, with the share of pixels changed and the baseline, the picture now and a diff with the changed pixels in red written under `visual/` beside the report. A baseline that cannot be used (half there, unreadable, or taken with other settings) is filed the same way; a target with no baseline yet is listed, counted beside the verdict, and never fails. Pictures are taken in a fixed 1280×900 window at one pixel per CSS pixel, after a fresh load, with reduced motion requested, fonts loaded, animations stopped and the caret hidden; baselines are kept per browser with a JSON of the settings they were taken with. They live in `.scenescout/baselines/`, which git ignores, unless `--baselines <dir>` names a folder the project commits, and only `--baseline update` writes one, rewriting those compare would not accept and any taken on another operating system. The GitHub Action takes the same three inputs (`baseline`, `baselines`, `baseline-threshold`) and keeps the pictures in its artifact.
+- 819fa87: `scenescout ci --lanes <n>` (and the ci action's `lanes` input) splits an unattended run between up to 8 model loops that explore at once, each in its own browser session and its own modules of the app. A crawl plans the split with no model call, the lanes share the run's turn, token and time caps rather than getting them each, and their findings fold into one report; the summary and `ci.json` list each lane. The default stays one loop: at the default caps, four lanes found no more than one loop on the benchmark's demo app, so raise `--max-turns` and `--max-tokens` with `--lanes`; `--lanes 4 --max-turns 160 --max-tokens 6000000` found the most, at about 2.3 times one loop's cost.
+- 5a83d6e: New tool `scout_network` lists the fetch and XHR requests the current page made since it loaded, with method, path, status and time. Each request shows the route it was sent from, so requests after a client-side route change can be placed. A request that failed, one still pending and one that never ran can be told apart. The tool is read-only, query-string credentials are redacted, the list is bounded, and `scout_request`'s own calls are marked.
+  
+  `scout_request` takes `select` (one value of a JSON body by dotted path, such as `stats.open` or `items.0.name`) and `offset`/`limit` (a window of characters), so a field past the 2000-character cut can be read. Without them the output is the same as before, except that the truncation line now names the options.
+  
+  `scout_coverage` shows a session its own work when other sessions share the project: the routes it reached this run and the forms it saw. `scope: "project"` shows every session's coverage and tags each route and form with the sessions that saw it.
+  
+  Smaller fixes:
+  
+  - A form whose date or time field the app pre-fills, for example with the current time, counts as submitted empty when that value is left as the app set it and every other field is blank. A pre-filled text field still counts as filled, so saving an edit form unchanged is not taken for the empty submit.
+  - "Seen in N runs" counts runs, not filings. When the same session files a finding again in the same run, its newer convention and detail replace the earlier ones, and the result says which fields changed or which were kept.
+  - A path crawled by name that answers as a page joins the route list. A crawled path that ends on another route is marked `REDIRECTED → <route>`.
+  - A journey's time is active time. Gaps over 30 seconds between steps are left out, and the result says how many were left out.
+- 86e9537: Finding dedup no longer merges two findings that both carry evidence on a quoted literal that one names in its title and the other only mentions in its detail: a control's label quoted in passing names where two defects were found, not one defect. The literal must be in the other finding's title or evidence; with no evidence on one side the detail still counts. A finding merged from another page now records that page (`seenOn`, at most 20), and the report prints it as "also seen on" beside the finding's route; the merge note returned to the lane says so. A lane report's decision can name the finding it was filed as (`finding`, the id `scout_finding` returned), and the fold's check for judged defects nobody filed counts it as filed when the project holds that defect. The check's text match also reads underscores inside kebab-case ids and treats ids in paths (`/things/5,/1`) as the route's (`/things/:id`).
+- 8f1cb0f: `scout_attach` and `scout_login` no longer need a `projectPath`; left out, both choose the same folder for a site, so a sign-in saved by `scout_login` is found by the attach after it. Given, it still always wins. Left out, a client that offers a workspace folder gets that folder, and otherwise each tested site gets its own folder, `Documents/SceneScout/<host>/` by default (`localhost-3000` for `http://localhost:3000`), created on first use and named in the attach's result so the person knows where the report is. `SCENESCOUT_PROJECTS_DIR` moves that folder, or `off` makes `projectPath` required again. The default is refused when it would sit inside a git repository below the home folder; a home folder that is itself a repository, as with dotfiles, does not count.
+- 561bc4e: SceneScout installs in Claude Desktop as a desktop extension. Each release now carries `scenescout-X.Y.Z.mcpb`, a bundle in the MCPB manifest format (manifest version 0.3) holding the engine and its dependencies; opening it installs SceneScout with no new chat or restart needed for the install itself. `scenescout doctor` recognises the extension: it checks that the extension's server is in place, checks the Chromium build the extension launches when that differs from its own, with the command that downloads it, and it no longer asks a Claude Desktop-only user to set up the Claude Code skill and registration. After a plugin install, `scenescout install --browser-only` now ends with "Start a new chat to use SceneScout."
+- fd610f0: The first `scout_attach` on a machine without the browser build it needs downloads that build itself, once, saying "Getting the test browser ready" while it does, then carries on with the attach. A Claude Desktop extension or a plugin install needs no terminal step before the first test. CI keeps its explicit install step: there the attach names the command instead, unless `SCENESCOUT_BROWSER_DOWNLOAD=on`. `SCENESCOUT_BROWSER_DOWNLOAD=off` turns the download off for a machine where nothing may be fetched. A failed download names the command to run by hand. `scenescout doctor` no longer fails a desktop extension whose browser is not downloaded yet when the extension is at least as new as `doctor`, since it downloads on first use; it still names the command to have it ready beforehand.
+- d7af6e7: Add `scenescout export --to github|jira`, which files the project's open findings as GitHub or Jira issues, each once: every issue carries the `scenescout` label and a marker with the finding's id, and an export skips every finding that already has an issue, open or closed (`--refile-closed` files one again when its issue is closed), so a second export of the same run files only what the first left over the cap. It is a dry run that lists what it would file unless `--yes` is given, and files at most `--max-issues` (default 20) per export. Issue text is rendered inert (no mention, link, cross-reference or markup from a finding does anything); severity becomes a label on GitHub and a priority in Jira (`--severity-map`); a recorded run's frames are attached in Jira and named in a GitHub issue. Credentials come from `GH_TOKEN` or `GITHUB_TOKEN`, or `JIRA_EMAIL` and `JIRA_API_TOKEN`, only, and are never printed; requests time out, wait out short rate limits, retry failed reads with backoff, never re-send a create the tracker may have carried out without first looking for its marker, and refuse redirects.
+- 362e52d: Every finding is filed with a picture of what it is about: the element `scout_finding {ref}` names, with a margin, or the page as it was. The picture is kept in `.scenescout/recordings/`, shown under the finding in `report.html` and in the live view's report, named in `report.md`, and returned in the `scout_finding` result as image content so a chat client shows it as the finding is filed. Pictures are bounded by `SCENESCOUT_EVIDENCE_MAX_PX` (default 800 pixels on the longer side) and `SCENESCOUT_EVIDENCE_MAX_KB` (default 200), and a session returns at most `SCENESCOUT_EVIDENCE_INLINE` (default 10) in its results. `scout_attach {evidence}` or `SCENESCOUT_EVIDENCE` chooses `inline`, `file` or `off`; a CI job, and `scenescout ci`, default to `file`. `SCENESCOUT_RECORD=on` makes every session record a frame after each action without each attach asking.
+- ffb9a38: `scenescout export --to jira` keeps a filed issue up to date and links it to the ticket it fails. A later export rewrites an open issue's summary and description when the finding has changed, unless someone has edited them in Jira since, and adds the picture, frames and ticket links it lacks, rather than leaving it as first filed (`--jira-update off` only lists it). The finding's picture is attached first, and a finding that fails a ticket's acceptance criterion is linked to that ticket (`--jira-link-type`, default `Relates`, or `JIRA_LINK_TYPE`; `none` links nothing). GitHub issues name the picture and list the failed criteria.
+- 267e24a: `scenescout login` no longer needs Enter in a terminal: the window saves the role's profile and closes by itself once the person is signed in, meaning back on the app, with no password or code field on the page, past any return from a single sign-on provider, and holding a session cookie or storage entry it did not hold when the window opened. A round trip through an identity provider on another site, a sign-in popup still open on one, and the app's own page before it has exchanged the provider's code are never taken for the end. Enter still saves at once; `--save enter` makes it the only way, as before, and `--success-url` names the signed-in address instead. The new `scout_login { url, role, projectPath }` tool opens the same window from a conversation and returns once the sign-in is saved, or after `waitSeconds` (default 120) with the window still open, so the agent can call it again; a window nobody finishes closes after 15 minutes, saving nothing. A role with no saved login now names `scout_login` beside the command when an attach is refused.
+- df40cfe: The engine can open the live view in the default browser when a session attaches, and report.html when `scout_report` writes it. The new `open` setting (`scout_attach {open}` or `SCENESCOUT_OPEN`: `live`, `report`, `both` or `none`) defaults to both on a local desktop session, headed or headless, and to none in CI, over SSH, or on Linux with no display. `scenescout ci` opens nothing unless `SCENESCOUT_OPEN` is set. The live view keeps its loopback-and-token rules.
+- 180d502: The report now opens in plain words: a short summary, then each problem with its impact (blocks users, annoying or cosmetic), numbered steps, what was expected, what happened and its picture, with the technical detail folded beneath each one. `report.md` puts this section before the technical report, and `report.html` opens on it. `scout_report {report}` chooses the parts: `both` (default), `qa` for the plain section alone, or `dev` for the technical report alone.
+- 8046682: Start a run with plain questions instead of settings. `/scenescout` with no flags, or the `explore` prompt with no arguments, now asks for the address, whether and how to sign in, what to check (tickets or a description) and whether the site holds real data, and chooses the URL, the sign-in, the objective and the write mode from the answers: real data, or an unsure answer, means observe. Any flag skips the questions. The skill gains `--focus <text>` and `--read-only`.
+- 4d4443d: Observe mode can be told which POST endpoints only read, and the label check no longer refuses controls for the record text they show.
+  
+  - `scout_attach` takes `readPosts` (`["POST /api/search"]`), and `SCENESCOUT_READ_POSTS` sets the same for `check`, `ci` and a first look. Observe then lets those POSTs out, so a search or query page that loads its data through POST can be tested. Nothing is named by default. A named endpoint is still refused when its path or body looks destructive or its body is a GraphQL mutation, and each one let out is logged. The gap ledger names the pages where observe refused a script's POST, with the endpoint.
+  - A row, card, heading or panel is judged by its test id and the control at its centre, not by the record text it shows. Its own text counts only for a clickable element whose text is a short command, and a heading's never does.
+  - Removing a filter chip ("Remove Status: Open filter") is allowed; "Remove member" is still refused.
+  - "Sign off" is refused only as a command, at the start of a label or joined to another verb ("Save and sign off"). "Manager sign-off", "Final sign-off recorded" and "Confirm sign off" are allowed.
+- 1a98cb4: Snapshot refs last longer and re-snapshots cost less. Refs from the last snapshot keep working after a search or filter that rewrites only the query string, and a control a re-render replaced is found again by its unique test id (the action says it was re-bound); a route change still refuses them, and the next diff now says when refs were dropped instead of calling them stable. A route you come back to is shown as a diff against its own last snapshot, and another tab of the same screen as a diff against that screen's last tab. Repeated rows are matched by their text or link, so a filtered list reads as the rows that went rather than as the first row relabeled. A truncated snapshot says what it cut, by role and test-id family, and keeps pager and "Load more" controls in the list. An element listed without a control role that a click or Tab still reaches is marked `[clickable]` or `[focusable]`.
+
+### Patch Changes
+
+- c6a75e2: `scout_request` replays the Authorization header the page last sent to the app's own origin on any request, reads included. It used to replay the header of the page's last write, which went stale once the app rotated its access token and then only read, so a replay got 401 while the page's own calls got 200. A header sent to another origin is never replayed, nor is one a `scout_request` call chose for itself. When a replay still gets 401 while the page's latest authorised call succeeded, the result says the replayed credential may be stale.
+  
+  The refresh broker's write-back keeps the profile's IndexedDB. It used to save the page's storage state without it, so an app keeping part of its sign-in in IndexedDB lost it from the role's profile at the first brokered refresh.
+  
+  An action's result now says when the refresh broker acted during it: the token refreshed and stored, another session's rotated token loaded and sent, an endpoint learned, or a refresh that could not be brokered. Counts only, no token values.
+- fe6ca3c: `false_success` no longer pairs a write sent as a clicked link loads the next page (the old page's save as it is left, the new page's beacon as it loads) with that page's static text, and it now reports, at medium, a refused write whose control or counter shows the change as kept with no error. Errors an HTTP client raises over the write policy's stand-in 403 ("Request failed with status code 403", "403 Forbidden") are attributed to the policy, an alert that appeared after a block is marked `(after a write-policy block)` in the snapshot, and the silent-submit note no longer fires when the click opened a dialog or client-side validation answered. Error-monitor tunnel and client-error endpoints count as infrastructure writes.
+- 4cb1441: The gap ledger's three route lines now count over the known routes and name that set (`3 of 54 known route(s) …`), treat a tab or section of a page as part of that page, and judge "nothing exercised" and "never design-audited" over the routes this run reached rather than every earlier run's. `scout_coverage` in a session's scope lists only the controls on the pages that session saw, not another role's on the same route, and labels the route figure as the project's. A wrapper flagged as not a control in any state of a route no longer counts in coverage because an older state left it unflagged. Record ids shaped like codes (`WID-2025-001`, `A1B2C3`) collapse to `:id` like numeric ones, and a dropdown's option already selected when the page loaded is no longer listed as never chosen.
+- 313dfab: Make the design audit agree with the page it measures:
+  
+  - A filter panel is no longer judged as a form. With no `<form>` on the page, the form-burden lines ("NONE marked required", "no obvious submit") count only the fields a user types into, and fields in a panel that names itself a filter or facet (its test id, id, label or legend) are left out wherever they are. Six text fields with no `<form>` and no submit are still flagged.
+  - The shadow census counts the layers a box-shadow draws. Empty ring layers (no offset, blur or spread) and transparent layers are dropped, so utility-CSS rings are no longer counted as elevations, and each example shows the layer that sets it apart instead of a truncated value.
+  - Tinted grays (a slate, a warm stone) are counted as grays: any colour with no hue family is one. Grays within a few units of each other count as one step of the scale.
+  - Elements are named in audit lines by their accessible name, computed as the snapshot computes it, so an icon button with `aria-label="Dismiss"` reads as "Dismiss" rather than "(no text)". The focus-indicator line names tab stops the same way.
+  - A new NAMES section lists controls with no accessible name and fields labelled only by their placeholder, and both now lower the a11y subscore (a link or button whose only content is an image with alt text, or an svg with a title or aria-label, is named by it and not listed), which before measured contrast, focus visibility and target size only. Page scores on pages with such controls go down.
+- c6a75e2: A click that submits a native form to a refresh endpoint the refresh broker handles returns once the navigation commits, with the broker's line in its own result. In Chromium it used to wait out the action limit, because loading another session's rotated profile opened a page that Chromium did not finish while the form's navigation was held. While it holds a navigation, the broker now loads only the profile's cookies; the rest of the profile is loaded at the next refresh a script sends, and the form's write-back saves the page's cookies while keeping the profile's storage.
+- 664c24d: A request still loading when its page is left, its frame is removed or its frame navigates away is no longer counted as in flight, so the next wait for the page to go quiet no longer runs to its 2 s cap.
+- c6dc360: Stop the layout checks reporting intended layering as defects, while the defective form of each layout is still reported:
+  
+  - A skip link parked off the page until it takes focus (a link to a place in the page, or any control a `:focus` rule moves) is no longer "outside the reachable page area", and once focused it is not reported as covering the header under it. A link parked off the page with nothing to bring it back, or a hash-route link, still is.
+  - A control inside a list that scrolls within an overflow-hidden card is no longer UNREACHABLE, nor is a slide of a viewer that a control naming it in `aria-controls`, or a next, previous or numbered control beside a row of slides, reveals. The same content with no scroller and no pager still is, and so is a column a card clips beside a "Next page" that pages rows.
+  - The overlap check skips a decorative overlay with `pointer-events: none` and a clear button or icon lying in the padding a text field reserves for it. A button over the field's text, an overlay that takes clicks, or a disabled control drawn over another still overlaps.
+  - The small-target rule measures a native input together with the label that wraps or touches it, and a visually hidden input as the label or drop zone that operates it, and applies the WCAG 2.5.8 spacing exception: a small target with nothing else inside its 24px circle passes.
+- 327e0c6: A path given to `scout_navigate`, `scout_crawl`, a plan or a replayed flow now resolves against the attached origin, as `scout_request` already did, so a session attached on a page below the root (`/things`) goes to `/widgets` for `/widgets` instead of `/things/widgets`, and a crawl given a full same-origin URL visits it as given. A crawled route whose main area holds only an alert or a loading placeholder is flagged `ERROR-VIEW` or `STILL-LOADING`, listed under problem routes, and no longer joins the route contract.
+- 28f9b79: The write policy's notices and label check are easier to work with, and refuse as much as before.
+  
+  - A blocked endpoint is named and explained once per session; later blocks of it are counted on one line, so a page that beacons on every load no longer buries each tool result.
+  - A control is judged by its own label. A dropdown is judged by the option picked, so a filter that offers "Delete" can be set to "Create". A row or panel is judged by its own text, not by the buttons inside it, plus any control covering its centre. A pick whose label cannot be read is refused.
+  - "Discard changes" and similar labels, which drop only unsent input, are no longer refused. "Discard draft" or "Discard record" still is, and `discard` in a request path is now treated as destructive on the network.
+  - When a page asks to confirm leaving unsent input, the result says so by name instead of failing with `ERR_ABORTED`. `scout_navigate`, `scout_click` and `scout_back` take `leave`: observe and read-only stay unless it is `true`, and other modes leave unless it is `false`. Every native dialog the page opens is reported in the action's result.
+- f0c8bf3: `check.sarif` and `ci.sarif` results now point at a repository file, so GitHub code scanning keeps them instead of dropping every one. An issue a saved flow raised points at that flow's file; every other result points at the anchor: the new `--sarif-file-anchor` option (and `sarif-file-anchor` action input) when given, else the running workflow's file from `GITHUB_WORKFLOW_REF`, else `package.json`, else `README.md`, whichever exists first; a missing option or workflow file is named in a warning, and when none exists the SARIF is still written with a warning that code scanning will drop its results. The page each result was seen on moves to the message, a logical location and `properties`; fingerprints are unchanged, so existing alerts keep their identity. In `check.json`, an issue a saved flow raised names that flow's file in `flow`.
+- e698580: The snapshot names a link or button whose only content is an image by that image: an `<img>`'s alt text, or an `<svg>`'s or `role="img"` element's aria-label or `<title>`, skipping anything under `aria-hidden="true"`. `<a href="/"><img alt="Home"></a>` is now listed as `link "Home"` rather than `link ""`, so the crawl, `scenescout check` and the a11y counts no longer report it as unnamed, and the read-only policy now judges an image button by the name it is announced with. Text still comes first: a control with both text and an image is named by its text, as before. The design audit reads this same name, so the audit and the snapshot use one rule.
+  
+  The name is half of a control's coverage key, so such a control gets a new key (`button "Search"` instead of `button ""`), and two unnamed image buttons that shared one key now have one each. Memory written before this change carries over: each snapshot records the key a control had under the earlier rule, and coverage reads older states through it, so what was exercised stays exercised and the earlier key is not left as a gap. On a route this run does not reach, the earlier keys stay as they are until a snapshot there lists the controls under their new names.
+
 ## 3.15.0
 
 ### Minor Changes

package/README.md

@@ -55,7 +55,7 @@ An excerpt of the report it wrote — [read the whole thing](examples/report.md)
 > **🟡 [LOW] The dashboard chart image is missing** *(callout 2)*
 > Evidence: `GET /img/weekly-chart.png → HTTP 404`
 >
-> **Gap ledger — what was NOT tested:** 9/12 visited routes never design-audited · single-role run, so permission boundaries are untested
+> **Gap ledger — what was NOT tested:** 9 of 12 known routes visited this run and 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.
 
@@ -152,9 +152,11 @@ Either way it downloads the browser and registers the server with the client you
 /plugin install scenescout@scenescout-marketplace
 ```
 
-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.
+Then start a new chat to use SceneScout; the test browser downloads on first use (to have it ready beforehand: `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.
 
-**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).
+**Using Claude Desktop?** Install the extension: download `scenescout-X.Y.Z.mcpb` from the [latest release](https://github.com/brunoboto96/SceneScout/releases/latest) and open it (or Settings > Extensions > Advanced settings > Install Extension). It works as soon as it is installed, with no terminal step: the test browser downloads on first use. Start a new chat and ask *"Use SceneScout to test http://localhost:3000"*. [More in the guide](docs/guide/Start-here.md#as-a-claude-desktop-extension).
+
+**A client that is not in that list?** [Add the server to its config by hand](#-other-mcp-clients); the test browser downloads on first use.
 
 <details>
 <summary>What <code>install</code> actually does</summary>
@@ -201,7 +203,9 @@ In Claude Code the skill gives you a command with flags for the same thing:
 
 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>` (who to explore as: a login saved with `scenescout login`, a storage state found by the scan, or a path to a Playwright storage-state JSON) · `--observe` / `--safe-write` / `--allow-destructive`.
+**Common flags** — `--level minimal|medium|extensive` · `--url <app>` · `--role <name\|path>` (who to explore as: a login saved with `scenescout login`, a storage state found by the scan, or a path to a Playwright storage-state JSON) · `--focus <text>` (a ticket or a sentence to check) · `--observe` / `--read-only` / `--safe-write` / `--allow-destructive`.
+
+**No flags at all** (`/scenescout` on its own) and the agent asks four plain questions instead: the address, whether and how you sign in, what to check (tickets or a description), and whether the site holds real data. Real data, or not being sure, means nothing but `GET` requests leave the page; you are never asked to pick a mode. Any flag skips the questions. See [Plain questions instead of flags](docs/guide/Ways-to-use-it.md#plain-questions-instead-of-flags).
 
 ### 🔑 Signing in as a role
 
@@ -211,7 +215,7 @@ For an app behind SSO or MFA, sign in once yourself and let every session reuse
 scenescout login http://localhost:3000 --role admin
 ```
 
-A browser window opens at the URL. Sign in however the app asks, then come back to the terminal and press **Enter**: the session is saved as `.scenescout/auth/admin.json` in the project. Closing the window or pressing Ctrl+C saves nothing. The file is readable by your account only, `.scenescout/` keeps itself out of git, and the command prints where it saved, how many cookies, origins and databases it holds, never what they are, and how long it will last: read from each cookie's expiry and the `exp` of any JWT in a cookie or in localStorage (the payload is decoded for that one claim, never verified, never printed). The profile keeps cookies, localStorage, IndexedDB and sessionStorage, so an app whose sign-in library keeps its token in sessionStorage or IndexedDB still comes back signed in; sessionStorage is put back only on the origin it came from, once per tab, so a lane that signs out stays signed out. A login saved by an earlier version has no sessionStorage or IndexedDB: record it again if the app keeps its token there. `--project <dir>` saves into another project; `--browser firefox|webkit` records in another browser.
+A browser window opens at the URL. Sign in however the app asks: once you are back on the app with a new session, the window saves it as `.scenescout/auth/admin.json` in the project and closes by itself. A trip through a single sign-on provider and back is followed, not taken for the end. Pressing **Enter** in the terminal saves at once, and `--save enter` makes Enter the only way, as before. Closing the window or pressing Ctrl+C saves nothing. From a conversation, the agent opens the same window with `scout_login`, so no terminal is needed. The file is readable by your account only, `.scenescout/` keeps itself out of git, and the command prints where it saved, how many cookies, origins and databases it holds, never what they are, and how long it will last: read from each cookie's expiry and the `exp` of any JWT in a cookie or in localStorage (the payload is decoded for that one claim, never verified, never printed). The profile keeps cookies, localStorage, IndexedDB and sessionStorage, so an app whose sign-in library keeps its token in sessionStorage or IndexedDB still comes back signed in; sessionStorage is put back only on the origin it came from, once per tab, so a lane that signs out stays signed out. A login saved by an earlier version has no sessionStorage or IndexedDB: record it again if the app keeps its token there. `--project <dir>` saves into another project; `--browser firefox|webkit` records in another browser.
 
 Then `/scenescout --role admin`, or `scout_attach { role: "admin" }` from any agent. Every session attached with the same role gets its own browser built from that one login, so parallel lanes can all run as `admin`. A role with no saved login is refused with the command to run. `role` and `storageStatePath` are alternatives: pass one.
 
@@ -225,7 +229,7 @@ Before a parallel run, `scout_lane_brief` checks that the planner's saved login
 
 ## 📺 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:
+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. On a local desktop it also opens that page in your default browser as the session attaches, and opens `report.html` when `scout_report` writes it, whether or not the browser window is shown. Nothing opens in CI, over SSH, or on Linux with no display. `SCENESCOUT_OPEN` (`live`, `report`, `both` or `none`) in the server's environment chooses otherwise, and `scout_attach {open}` wins over it. `scenescout ci` opens nothing unless `SCENESCOUT_OPEN` is set. 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 three parallel agents against the demo app: one card per session, each with its role and objective, the task it is on, the tool it is running, the page it is on, a live thumbnail, and a feed of the actions it just took, tinted one colour per task" width="880" /></p>
 
@@ -254,21 +258,33 @@ The view is served on `127.0.0.1` only, behind a token that changes every time t
 ## 🎬 Recording a run, and reading it back
 
 A report says what happened. For QA work that is not always enough — the point
-is often to *show* what was checked, not to assert it. Ask for a recorded run
-and the engine keeps a frame of the page after every action:
+is often to *show* what was checked, not to assert it.
+
+Every finding already carries a picture: the element it is about, with a margin,
+or the page as it was. It is kept in `.scenescout/recordings/`, shown under the
+finding in `report.html`, and returned with the `scout_finding` result, so a
+chat client shows the evidence the moment it is filed. Pictures are bounded in
+size and in how many reach the conversation, and a CI job keeps them on file
+only; `SCENESCOUT_EVIDENCE` and `scout_attach {evidence}` change that
+([configuration reference](docs/guide/Configuration-reference.md#environment-variables)).
+
+Ask for a recorded run and the engine also keeps a frame of the page after every action:
 
 ```
 Use SceneScout to test http://localhost:3000, record the run
 ```
 
-or, on the tool directly, `scout_attach {record: true}`.
+or, on the tool directly, `scout_attach {record: true}`. `SCENESCOUT_RECORD=on` in
+the server's environment records every run.
 
 Then `scout_report` writes two files side by side in `.scenescout/`:
 `report.md` as always, and `report.html` — the whole run as one self-contained
 page. It opens from the file system with nothing running, needs no network, and
 holds:
 
-- **The report**, rendered from the same Markdown.
+- **The report**, rendered from the same Markdown: the plain-language view
+  first (each problem's steps, what was expected, what happened and its
+  picture), with each problem's technical detail one click away.
 - **The screenshots around each finding**, in an accordion under it, from the
   session that filed it.
 - **Every session's trail**, in the blocks its tasks made, each step with the
@@ -313,17 +329,18 @@ Snapshots are cheap: re-snapshotting a route returns only *what changed*, with s
 
 ## 🧰 The toolbox
 
-29 deterministic tools. The agent picks; you rarely call these by hand.
+34 deterministic tools. The agent picks; you rarely call these by hand.
 
 | Phase | Tools | What they do |
 |---|---|---|
 | **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` `scout_capture` | Read the structured scene (diffed); reveal tooltips/hover cards; capture pixels only when needed; save one element as a PNG to show someone |
-| **Ask the server** | `scout_request` | Call the app's own API as this session, with the UI bypassed — the check that turns a hidden button into a proven refusal |
+| **Ask the server** | `scout_request` `scout_network` | Call the app's own API as this session, with the UI bypassed — the check that turns a hidden button into a proven refusal; list the requests the page itself made since it loaded |
 | **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 |
 | **Assess** | `scout_design_audit` `scout_journey` | Score a page's craft/a11y/consistency; measure how hard a task is to complete |
 | **Record** | `scout_note` `scout_finding` `scout_resolve` `scout_report` | Curate durable notes; file deduped findings; mark fixes; write the report, and on a recorded run the whole run as one page |
+| **Answer tickets** | `scout_tickets` `scout_criterion` | Read the acceptance criteria in pasted or uploaded tickets; record each criterion as passed, failed (with the findings that show it) or not tested (and why), with a confidence |
 | **Re-test** | `scout_verify` | List the findings earlier runs left open, worst route first, and record whether each is gone, still present, or changed |
 | **Split the work** | `scout_lane_brief` `scout_lane_report` | Divide the app between parallel agents by whole module, each with its own landing route and rules; fold what each hands back as one typed JSON object, and name any defect it judged but never filed |
 | **Close** | `scout_close` | Tear down one session or all |
@@ -361,14 +378,18 @@ That refusal *is* the guarantee: an extensive report can only exist when nothing
 - 🟢 **`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.
-- 📂 Findings, memory, and reports live in a `.scenescout/` folder where you ran it. It ignores itself in git, so a stray `git add -A` never commits test data.
+- 📂 Findings, memory, and reports live in a `.scenescout/` folder in the project. A client with no project folder, such as a desktop chat, gets one folder per tested site under `Documents/SceneScout/<host>/` by default, and the attach says where; `SCENESCOUT_PROJECTS_DIR` moves it. The folder ignores itself in git, so a stray `git add -A` never commits test data.
 
 A `🛡 WRITE-POLICY blocked` notice is the safety net doing its job, not an app bug. The server never sees a blocked request, but a page's own `fetch` or XHR is answered with a `403` in its place rather than dropped, so the page's handling of a refusal really runs: a page that then claims success is reported as a `false_success` ([ADR 9](docs/adr/0009-a-refused-write-is-answered-not-dropped.md)).
 
+A control is judged by its own label: a dropdown by the option picked, a row by its own text rather than the buttons inside it, and "Discard changes" on an unsent form is allowed. When a page asks to confirm leaving unsent input, the result says so; `observe` and `read-only` stay unless the call passes `leave: true`. See the [safety model](docs/guide/Safety-model.md).
+
 ---
 
 ## 📋 What you get
 
+`.scenescout/report.md` and `report.html` open **In plain words**: a short summary, then each problem this run found, worst first, with its impact, the steps that led to it, what was expected, what happened and a picture when there is one. The technical detail (id, category, evidence, route) stays one click away.
+
 `.scenescout/report.md` — a deduplicated, worst-first report with:
 
 - 🐛 **Findings** with repro traces and generated Playwright regression-test skeletons.
@@ -379,9 +400,9 @@ A `🛡 WRITE-POLICY blocked` notice is the safety net doing its job, not an app
 - ⏱️ **How the run was paced** — how closely each session kept working, and apart from that, how long finished lanes held their browsers waiting to be collected, so neither hides the other.
 - 🎯 **How well the lanes judged** — on a parallel run, whether the confidence each lane stated matched what the project went on to file, beside what later re-tests found ([ADR 10](docs/adr/0010-a-confidence-is-checked-not-trusted.md)).
 
-`.scenescout/report.html` — the same report as one self-contained page, with every session's trail beside it, and on a [recorded run](#-recording-a-run-and-reading-it-back) the screenshots under each finding.
+`.scenescout/report.html` — the same report as one self-contained page, with every session's trail beside it. Each finding shows a picture of the element it is about, or of the page as it was. A [recorded run](#-recording-a-run-and-reading-it-back) also shows the screenshots around each finding.
 
-👀 Watch a run live: `node dist/cli.js status <project-path>`.
+👀 Watch a run live: `npx scenescout watch`, or `npx scenescout status <project-path>` for the same information as text.
 
 ---
 
@@ -430,6 +451,7 @@ With the default settings its saved flows send no HTTP write (they replay under
 - `--flow-writes never|allow` (default `never`): `never` replays flows under observe's rule whatever `--mode` says; `allow` replays them under `--mode`, so in `read-only` a flow's form submissions are sent to the target on every run.
 - `--on-refused-step report|stop` (default `report`): `report` marks a flow whose step was refused "could not run", keeps every other verdict and exits 2; `stop` exits 2 at that step with no results.
 - `--gate-retests never|high|all` (default `high`): which still-reproducing re-tested findings fail the gate.
+- `--baseline off|compare|update` (default `off`), with `--baselines <dir>` and `--baseline-threshold <percent>` (default `0.1`, so small anti-aliasing noise between machines passes): visual baselines, below.
 
 The defaults are what an unconfigured check does, for a first try or an AI agent running it unattended: its flows send no HTTP write and it never silently hides a result. Each setting is a choice for the project; the report and `check.json` print the values a check ran with.
 
@@ -437,6 +459,8 @@ The defaults are what an unconfigured check does, for a first try or an AI agent
 
 It also replays the flows saved in `.scenescout/flows/*.json`, with no model: the steps `scout_run_plan` takes (navigate, click, type, select, press) plus `expect-text`, `expect-url` and `expect-request`. A flow whose step breaks fails the gate, naming the flow and the step. And it re-tests the open findings earlier runs left in the project's memory that a page load can reproduce, reporting each as still reproducing or possibly fixed; by default a finding filed high that still reproduces fails the gate. [docs/ci.md](docs/ci.md#saved-flows) has the flow format; [ADR 12](docs/adr/0012-a-check-replays-saved-flows-and-reports-re-tests.md) says why it works this way.
 
+With `--baseline compare` it also holds pages and elements to approved pictures: list them in a `targets.json`, take the baselines once with `--baseline update`, and a later check that finds one changed past `--baseline-threshold` fails the gate with the share of pixels changed and a diff picture beside the report. Baselines are kept per browser, in a git-ignored folder unless `--baselines` names one the project commits, and only `--baseline update` ever writes one. [The guide](docs/guide/Ways-to-use-it.md#visual-baselines) has the details; [ADR 19](docs/adr/0019-a-visual-baseline-changes-only-when-asked.md) says why.
+
 Beyond those flows it explores nothing and fills no forms. That is the exploratory run's job, and its findings belong in a report, not a gate.
 
 ## 🤖 In CI: an unattended exploratory run
@@ -459,6 +483,26 @@ There is a GitHub Action for it (`uses: brunoboto96/SceneScout/ci@…`). [docs/c
 
 On a pull request, an allowed account can comment `/scenescout qa` to run it against that pull request's deployed preview and get the results as a reply. The job that holds the key checks out nothing and runs SceneScout from an exact release tag, so the pull request's code never runs beside the key. [docs/ci.md](docs/ci.md#a-qa-review-from-a-pull-request-comment) has the workflow to copy and what a project configures; [ADR 15](docs/adr/0015-a-qa-comment-tests-a-preview-and-never-runs-the-pull-requests-code.md) says why.
 
+## 📮 Filing findings as issues
+
+`scenescout export` turns the project's open findings into GitHub or Jira issues, where the team already works. It reads `.scenescout/memory.json`, so it runs after an interactive run, `scenescout ci` or anything else that wrote findings:
+
+```bash
+export GH_TOKEN=…        # or GITHUB_TOKEN; for Jira, JIRA_EMAIL and JIRA_API_TOKEN. Read from the environment only
+npx scenescout export --to github --repo owner/app          # a dry run: lists what it would file
+npx scenescout export --to github --repo owner/app --yes    # files it
+npx scenescout export --to jira --jira-url https://your-site.atlassian.net --jira-project QA --yes
+```
+
+- **Each finding once.** Every issue carries the `scenescout` label and a marker with the finding's id. Before filing, the export reads the labelled issues, open or closed, and skips every finding already filed, naming its issue, so a second export of the same run files only what the first left over the cap. A closed won't-fix is not filed again; `--refile-closed` files a finding again when its issue is closed.
+- **Jira issues are kept up to date and linked to the ticket.** A later export updates an open Jira issue instead of filing another, leaving text someone edited in Jira as they wrote it. The finding's picture is attached, and a finding that fails a ticket's acceptance criterion is linked to that ticket (`--jira-link-type`, default `Relates`).
+- **A dry run unless `--yes`**, and at most `--max-issues` (default 20) per export; the next export files the rest. `--min-severity`, `--only <ids>` and `--include-worth-a-look` choose what goes.
+- **Inert issues.** Titles, descriptions, steps and evidence come from the run and the app's pages, so no `@mention`, link, `#123` reference, HTML or Markdown in them does anything.
+- **Severity** becomes a label on GitHub and a priority in Jira; `--severity-map` renames them or turns them off. **Screenshots** from a recorded run are attached in Jira; GitHub's API takes no uploads, so a GitHub issue names the frames in the run's `.scenescout/` folder.
+- **Credentials** are never printed. Every request has a timeout, a short rate limit is waited out, failed reads are retried with backoff, and redirects are refused. Jira's search can take a little while to show a new issue, so leave a few minutes between two exports to the same Jira project.
+
+[The guide](docs/guide/Ways-to-use-it.md#filing-findings-as-issues) has the details and a GitHub Actions step.
+
 ---
 
 ## 🩺 Troubleshooting
@@ -471,7 +515,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`. |
-| *"… 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`. |
+| *"… build has not been downloaded yet"* on attach | The attach downloads a missing browser itself, once, except in CI or with `SCENESCOUT_BROWSER_DOWNLOAD=off`; there, or when that download failed, it names the command to run. 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` session has expired. For a saved login, run `scenescout login <url> --role <name>` again; for a storage-state file, regenerate it the way your project's Playwright setup does. |
 
@@ -515,6 +559,8 @@ npx -y scenescout install --browser-only --browsers firefox,webkit   # add two m
 
 Sizes vary by platform. The builds go to Playwright's shared cache, so a build another tool already fetched is not downloaded again.
 
+The first attach that needs a build which is not on disk downloads it itself, once, and says so ("Getting the test browser ready"). It does not in CI unless `SCENESCOUT_BROWSER_DOWNLOAD=on` is set, and never with `SCENESCOUT_BROWSER_DOWNLOAD=off`, for a machine where nothing may be downloaded.
+
 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.
@@ -671,10 +717,11 @@ npx -y scenescout login <url> --role admin   # sign in once in a visible browser
 src/
   mcp-server.ts     the 29 tools + per-session dispatch
   scan.ts           project discovery (framework, routes, auth)
-  cli.ts            scan · serve · install · doctor · check · ci · login · status · watch
+  cli.ts            scan · serve · install · doctor · check · ci · login · export · status · watch
   check-run.ts      drives a check: attach, crawl every route, collect what was measured
   ci-run.ts         drives a CI run: the MCP server as a child, the model's API, the agent loop
-  login-run.ts      drives `scenescout login`: a visible browser, Enter to save the role's profile; or --script, headless from the environment
+  login-run.ts      drives `scenescout login` and scout_login: a visible browser that saves the role's profile once the sign-in is seen to finish (or on Enter); or --script, headless from the environment
+  export-run.ts     drives `scenescout export`: reads the findings, asks GitHub or Jira what is filed, files the rest
   installer.ts      setup logic (skill link, MCP registration, diagnostics)
   engine/
     browser.ts      the engine class: attach, snapshot, actions, crawl, plans
@@ -698,10 +745,14 @@ src/
     profiles.ts     saved sign-ins: role names, where a profile lives, owner-only files, attach by role, sessionStorage restore
     refresh.ts      the refresh broker: which values are a role's refresh tokens, the lock beside the profile, swapping a spent token
     scripted-login.ts  a CI sign-in: env and flags, TOTP (RFC 6238) or a fixed code, which field is which, redaction
+    signed-in.ts    when a person's sign-in in the window has finished: back on the app, a new session, past any SSO round trip
     expiry.ts       how long a saved sign-in lasts: cookie dates and JWT exp, checked before lanes start
     report.ts       the gap ledger + report generation
     check.ts        the check's rules, gate, report and SARIF
+    baseline.ts     visual baselines: targets.json, where each picture is kept, when one is met
+    sarif.ts        which repository file a SARIF result points at, so code scanning keeps it
     ci.ts           a CI run's options, provider choice, caps, key redaction, tools and files
+    export.ts       which findings an export files, the inert issue it writes, the marker that dedups it
     provider.ts     the Anthropic and OpenAI message shapes, and retries
     replay.ts       the run as one page: steps, tasks, frames under each finding
     …               collector · dispatch · fixtures · authloss · reaper
@@ -738,6 +789,7 @@ The load-bearing choices are recorded as ADRs — read the relevant one before c
 - [11 · A gate is deterministic, and fails only on what it can prove](docs/adr/0011-a-gate-is-deterministic-and-fails-only-on-what-it-can-prove.md)
 - [12 · A check replays saved flows and re-tests open findings, within settings whose defaults do the least harm](docs/adr/0012-a-check-replays-saved-flows-and-reports-re-tests.md)
 - [13 · What depends on a project's convention is the project's to decide](docs/adr/0013-a-convention-is-the-projects-to-decide.md)
+- [21 · Update the docs in the same pull request, unless the change has no user-facing surface](docs/adr/0021-update-the-docs-in-the-pull-request.md)
 
 ---
 

package/dist/browsers.js

@@ -7,6 +7,7 @@
  */
 import fs from "node:fs";
 import path from "node:path";
+import { isCiEnv } from "./engine/capture.js";
 /** A browser the engine can launch. */
 export const BROWSER_ENGINES = ["chromium", "firefox", "webkit"];
 /**
@@ -283,3 +284,30 @@ export function defaultAttachNote(opts) {
     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.`);
 }
+/** Environment variable deciding whether an attach downloads a missing browser build itself. */
+export const BROWSER_DOWNLOAD_ENV = "SCENESCOUT_BROWSER_DOWNLOAD";
+/** `auto` downloads except in CI; `on` downloads in CI too; `off` never downloads, for a machine where nothing may be fetched. */
+export const BROWSER_DOWNLOAD_SETTINGS = ["auto", "on", "off"];
+export const DEFAULT_BROWSER_DOWNLOAD = "auto";
+/**
+ * What an attach does when the build it needs is not on disk: download it
+ * itself, refuse because the setting says never, or tell CI to keep its
+ * explicit install step (a CI job downloads only when it asks to, so a
+ * pipeline's browser is never fetched behind its back). An unknown setting
+ * refuses the attach rather than being read as a default.
+ */
+export function browserDownloadDecision(env) {
+    const raw = env[BROWSER_DOWNLOAD_ENV]?.trim().toLowerCase() || DEFAULT_BROWSER_DOWNLOAD;
+    if (!BROWSER_DOWNLOAD_SETTINGS.includes(raw)) {
+        throw new Error(`${BROWSER_DOWNLOAD_ENV}="${env[BROWSER_DOWNLOAD_ENV]}" is not a setting SceneScout knows. Use one of: ${BROWSER_DOWNLOAD_SETTINGS.join(", ")}.`);
+    }
+    if (raw === "off")
+        return "refuse";
+    if (raw === "on")
+        return "download";
+    return isCiEnv(env) ? "tell" : "download";
+}
+/** The plain-words line shown while an attach downloads the build it needs. */
+export function attachDownloadLine(target) {
+    return `Getting the test browser ready — a one-time download of about ${APPROX_DISK_MB[target]} MB (${target}). The test carries on once it is done.`;
+}