@unotest/web 0.30.0 → 0.32.0

package/.claude/skills/write-e2e-test/SKILL.md

@@ -604,11 +604,23 @@ the old browser context, then `run_test` again.
 | `wait_for_url`     | `value` (the pattern)                   | `options`            |
 | `enter_frame`      | `locator`                               |                      |
 | `exit_frame`       |                                         |                      |
+| `screenshot`       |                                         | `name`, `fullPage`, `locator`, `outline`, `evidenceOnly` |
 
 When recording (`explorationId` present): `description` + `section`
 are required. Ad-hoc (no `explorationId`): no description/section,
 no recording.
 
+`screenshot` is the **evidence** step: it files a PNG under the session
+(`.unotest/explorations/<explorationId>/screenshots/<NNN>-<name>.png`,
+`adhoc/` without a session), replies with `{path, width, height}` and
+the image itself, and becomes `screenshot(name)` in the saved test.
+`name` defaults to the section slug; `locator` captures one element
+(the saved test degrades that to a page capture); `outline: true` adds
+the page outline to the reply; `evidenceOnly: true` keeps the file but
+records no step. `explore_stop` lists every file in `artifacts`. Take
+one wherever a human would want to check a green run after the fact —
+do not write throwaway scenarios just to get a picture.
+
 ## Failure modes you will hit
 
 - **`StaleRefError`** — ref no longer in the DOM. Re-`get_page_snapshot`

package/.claude/skills/write-e2e-test-ground/SKILL.md

@@ -735,11 +735,23 @@ the old browser context, then `run_test` again.
 | `wait_for_url`     | `value` (the pattern)                   | `options`            |
 | `enter_frame`      | `locator`                               |                      |
 | `exit_frame`       |                                         |                      |
+| `screenshot`       |                                         | `name`, `fullPage`, `locator`, `outline`, `evidenceOnly` |
 
 When recording (`explorationId` present): `description` + `section`
 are required. Ad-hoc (no `explorationId`): no description/section,
 no recording.
 
+`screenshot` is the **evidence** step: it files a PNG under the session
+(`.unotest/explorations/<explorationId>/screenshots/<NNN>-<name>.png`,
+`adhoc/` without a session), replies with `{path, width, height}` and
+the image itself, and becomes `screenshot(name)` in the saved test.
+`name` defaults to the section slug; `locator` captures one element
+(the saved test degrades that to a page capture); `outline: true` adds
+the page outline to the reply; `evidenceOnly: true` keeps the file but
+records no step. `explore_stop` lists every file in `artifacts`. Take
+one wherever a human would want to check a green run after the fact —
+do not write throwaway scenarios just to get a picture.
+
 ## Failure modes you will hit
 
 - **`StaleRefError`** — a ref from an earlier lookup is no longer in

package/CHANGELOG.md

@@ -1,5 +1,388 @@
 # Changelog
 
+## [0.32.0] - 2026-09-05
+
+### Minor Changes
+
+- 442fadf: `npx @unotest/web box …` reads a box's results from a terminal: `box envs` lists the environments a read token may look at, `box runs` their history (`--latest` collapses it to one line per scenario with its failing streak), `box run <id>` explains one run — the failure, the soft steps, the judge's verdicts — `box queue` shows who is waiting, and `box screenshot` saves a frame the run captured.
+
+  `box run --download` fetches the run's `*.unotest.zip` into `.unotest/box/` and unpacks its failure bundle into `.unotest/failures/`, where `list_failures`, `get_failure_*` and `agent_fix` already look — so a run that failed on a box is debugged with the commands a local failure is. `--no-screenshots` asks the box itself to leave the step frames out (`GET /api/runs/:id/export?screenshots=0`), which is what makes the download smaller rather than only the disk.
+
+  Reading needs a personal read token in `UNOTEST_BOX_READ_TOKEN`; the project's `UNOTEST_BOX_TOKEN` still pushes bundles and values and cannot read runs.
+
+  The viewer publishes its archive reader as `@unotest/viewer/snapshot`, so the three places that open a `*.unotest.zip` — its server, its browser bundle and now the CLI — share one implementation and one message for a file that is not an archive.
+
+- 69fbea1: Six MCP tools close the loop that `bundle push --run` opens: `box_run` says what became of a run the agent ordered on a box, `box_run_download` unpacks its failure bundle into `.unotest/failures/` so `get_failure_trace`, `get_failure_console`, `get_failure_a11y`, `get_failure_screenshot`, `get_failure_network` and `agent_fix` work on it unchanged, and `box_envs`, `box_runs`, `box_queue` and `box_screenshot` cover the cases where the agent has no run id, no environment name, a run that never started, or a page it would rather see than read about. Their descriptions carry the route, not just the arguments.
+
+  Without a read token the tools refuse with a message saying where to mint one, so an agent meets an instruction rather than an unexplained failure.
+
+- 9099f64: Box: personal read tokens, so an agent can read a box's runs without a browser.
+
+  A user mints a token for themselves on the guard's new **Read tokens** page
+  (`/_guard/tokens`), sees the value once, and points a client at the box with
+  `UNOTEST_BOX_READ_TOKEN`. The token is always `readonly` whatever its owner's
+  role, may only `GET`, and names the environment it means in
+  `X-Unotest-Environment: <project>/<environment>` (`GET /_guard/api/envs` lists
+  them). It is not a machine identity: it follows its owner — revoked, disabled
+  or a lapsed seat all stop it, and the refusal says which. An administrator
+  sees every token on the box and can revoke one that is not theirs; issuing,
+  first use and revocation all land in the audit trail.
+
+  `UNOTEST_BOX_TOKEN` is unchanged: the project token still pushes bundles and
+  environment values, and read tokens cannot — asking with the wrong one now
+  says which token the route wants instead of a bare "unauthenticated".
+
+  A read token is never passed on to the viewer behind the guard, so it cannot
+  end up in the logs of a service that has no use for it. A box whose licence
+  has lapsed, and an environment whose viewer is not up yet, answer a token in
+  the read contract's shape rather than with a page or a bare 503 — "wait" and
+  "renew the licence" are not the same instruction as "your token is wrong".
+
+### Patch Changes
+
+- 5266b30: The agent integration guide's tool catalog matches the server again. It listed fifteen per-action tools (`goto`, `click`, `fill`, `press`, …) that were removed when recording moved into `explore_step`, had no section at all for the ten exploration tools that replaced them, counted the debugger's eleven tools as six, and put the total at 39 when it is 50. An agent reading it as a map — which is exactly what this file is for — would call tools that do not exist and conclude the server is broken. Every name now comes from the list the test suite verifies against the real registry, and the section counts add up to the total.
+- 442fadf: `BoxReadClient` reads a box's runs — environments, run history, one run's whole journal, a collection's children, the queue, a run's export zip and its individual artifacts — over the same HTTP routes a browser uses, authenticated with the personal read token in `UNOTEST_BOX_READ_TOKEN`. Every refusal arrives as a typed `BoxReadError` whose `kind` says what to do next, so throttling is never mistaken for a rejected token and a live run's export says "wait" rather than looking like a broken box. Configuration mistakes surface when a read is attempted rather than at startup, so a stale token in a project's `.env` cannot stop a local run that never touches a box.
+
+  The viewer gains a `@unotest/viewer/wire` entry point exporting its HTTP contract types (the runs page, a run's full snapshot, the queue payload and the snapshot manifest), so a client can name the shapes it parses instead of keeping a second copy of them.
+
+- f770a25: The box address and the read token are resolved from `unotest/.env` and `unotest/.secrets` on every request, not once at startup, and the `box` CLI reads those files directly. `unotest-web box …` runs without loading the project config, so nothing had flattened `unotest/.env` into its environment — the command told people to put the address there and then refused with "no box address". And an MCP server that resolved once meant a token written while it ran was ignored until the editor reconnected it, which is exactly the restart this path exists to avoid. One rule for both settings, from both entry points: a flag, then the environment, then the project's files.
+- 8aa0f30: Protocol contract for reading a box's run results with a personal read token: `UNOTEST_BOX_READ_TOKEN` (distinct from the project's `UNOTEST_BOX_TOKEN`, which stays a write credential for bundles and environment values), the `X-Unotest-Environment: <project>/<environment>` header every bearer request names its own environment with, the `/_guard/api/envs` listing and its `BoxReadEnvironment` entry, and typed refusals (`unauthorized`, `forbidden`, `unknown-environment`, `not-found`, `rate-limited`, `run-in-progress`, `unavailable`, `malformed`) with parsers that reject anything that is not a box answering. Throttling gets a code of its own rather than an `unauthorized` carrying `Retry-After`: a rejected token means mint a new one, a throttled one means wait and resend the same one. The viewer's `ViewerEnvOption` is now that same protocol type rather than a second copy of it. An environment whose viewer is still starting — the common state right after a bundle push — answers `unavailable` rather than looking like an unreachable box, so the advice is to wait rather than to check the address.
+- 8aa0f30: A run exported as `*.unotest.zip` now carries everything needed to diagnose it away from the machine that produced it: `stdout.log` and `stderr.log` (previously dropped, which left the one artifact that explains a runner crash outside the bundle), the failing page's `page.html` reachable through the manifest, and the run's step screenshots — declared in a new `manifest.screenshots` list, because an importer keeps only what the manifest names and a frame absent from it did not survive the round trip.
+- 5266b30: `UNOTEST_BOX_READ_TOKEN` is now read from `unotest/.secrets` as well as from the environment, with an exported value winning. This is what makes the `box_*` tools usable from an agent at all: an MCP server is started by the editor, so a token that exists only in a shell is a token the server never receives — the alternative was editing the editor's own JSON config and reconnecting the server. `unotest/.env` is deliberately not consulted: it travels inside a pushed bundle, while `.secrets` does not. The CLI resolves the token the same way, so one token serves both.
+- 5266b30: `box run` and `box_run` now carry the `{tag}` of a failed soft step, in the JSON and in the printed line (`Rubric [judge-red]`, the shape a local run already prints). A data-driven test runs one `step.soft` over many cases, so its failures all share a label and the tag is the only thing that says which case failed — without it a remote reader saw "Rubric failed" three times and had to tell them apart by line number. The tag was in the run's journal all along; the summary dropped it.
+- ee6bb51: Secrets injected by a box are masked. Masking works by value, and the registry of values was built from `unotest/.secrets` alone — a file that does not exist on a box, where the daemon passes the values as environment variables and names them in `UNOTEST_BOX_SECRET_NAMES`. The registry was therefore empty on every box run, and a password a scenario typed reached the run journal, the run's `stdout.log`, the viewer's System pane and anything an agent downloaded, in the clear. The runner now registers those values alongside the ones it reads from files, so masking no longer depends on where the run happens to be. Nothing changes on a developer's machine, where the variable is not set.
+- 047ca68: Failure text no longer carries terminal colouring into files and replies.
+
+  Playwright paints its call log whenever the environment claims a terminal is
+  watching — `FORCE_COLOR`, which an MCP server inherits from whatever launched
+  it — and that message was copied verbatim into `steps.jsonl`, `runtime.json`
+  and the failure bundle. An agent reading the JSON got an escape sequence in
+  the middle of the sentence it was trying to parse, and the viewer rendered
+  it as a chewed-up word.
+
+  The colouring is dropped where a thrown error becomes our data, so every
+  reader of a failure gets the same clean text. Our own output is unaffected:
+  it paints at print time, which is where colour belongs.
+
+  The same on mobile: a failure's text in the run journal and in the report no
+  longer carries terminal escapes.
+
+- 047ca68: A failure somebody paused on stays a failure, with the evidence to show for it.
+
+  A run driven through the debugger — `run_test` then `resume`, or the viewer's
+  Continue — reported `completed` after a failure it had paused on, wrote no
+  failure bundle and no `failure/` artifacts, and left `list_failures` with
+  nothing to show. Continuing past a failure is how it gets inspected; it was
+  never meant to retract it. The verdict is now decided where the run's own
+  events are seen, so the journal, `runtime.json` and the reply agree, and a
+  debug run leaves the same evidence a plain `unotest-web e2e` run does.
+
+  `abort_runtime` (and Stop, and SIGTERM) now also ends the run in
+  `runtime.json`, not only in `steps.jsonl`: the control file used to keep
+  saying `paused-step` about a run that was over, so anything reading it rather
+  than the journal saw a pause that never ended.
+
+- c5d3cda: README links the documentation site instead of manuals that are not shipped in the package (`guides/manuals/*`), and says what a run on a box cannot reach: `localhost`, port-forwards, host tools, a judge service on your machine — with the recipe for the judge on a box.
+- 442fadf: Secret values registered from `unotest/.secrets` are now masked in what the runner prints, not only in what it writes. The run journal and every failure artifact were redacted; the terminal line was not, and that line is also copied into the run's `stdout.log` / `stderr.log` and streamed to the viewer's System pane. Masking is applied once, where the logger is built, so child loggers and message arguments are covered too. The collection runner is covered by the same rule: its messages go through its logger rather than straight to the stream, and the logger it builds when a caller passes none reads the project's secrets the way the composition root's does.
+- 047ca68: A `step.soft(...)` failure no longer stops a debug run — or goes missing from it.
+
+  Under a debugger (`run_test`, or `e2e --debug`), every soft failure raised
+  the debug wheel: the run stopped on each one and an agent had to `resume`
+  its way through them. Worse, it was then lost — a paused failure is consumed
+  where it paused, so it never reached the `step.soft` envelope that records
+  it, the envelope closed as if the block had passed, and a run with three
+  soft failures could finish green with none of them listed.
+
+  Pausing is now for a failure that ENDS the run. A failure under any
+  enclosing soft step is recorded and stepped over exactly as it is on the
+  command line, and `runtime.json` — which the `run_test` reply is built from —
+  carries every soft failure of the run, not just the last stop.
+
+  A hard failure still pauses: that is what the debugger is for.
+
+  The same holds on mobile: a `step.soft(...)` failure no longer stops a run
+  under the debugger, and every soft failure of a run is now part of its
+  runtime state instead of being lost at the pause.
+
+- Updated dependencies [442fadf]
+- Updated dependencies [442fadf]
+- Updated dependencies [8aa0f30]
+- Updated dependencies [8aa0f30]
+- Updated dependencies [047ca68]
+- Updated dependencies [047ca68]
+- Updated dependencies [047ca68]
+  - @unotest/viewer@0.32.0
+  - @unotest/protocol@0.32.0
+  - @unotest/dsl@0.32.0
+  - @unotest/core@0.32.0
+  - @unotest/grounder-client@0.32.0
+
+## [0.31.0] - 2026-09-04
+
+### Minor Changes
+
+- b8e105b: New DSL function `note(label, value)`: attach a labelled value to the
+  current step — the question a data-driven case asked, the answer it got
+  — kept in the run journal and shown in the viewer under the step, during
+  and after the run. Any value: a string as it is, anything else as JSON;
+  cut at 4 KB (marked `truncated`), secrets masked. `log(...)` now also
+  lands in the journal under the step that wrote it (the stdout line
+  stays), and `assertJudge` verdicts carry the position of their statement,
+  so the viewer can show a verdict under its step and the whole verdict on
+  a failed step's error card. Each of these events records the DSL call's
+  `file` / `line` / `col` and the nearest entry-file statement
+  (`entryLine` / `entryCol`) — a note from inside a helper is attributed to
+  the entry step that called the helper. Without a run journal
+  (exploration, an ad-hoc runtime) `note` goes to the logger; nothing
+  fails.
+- 56784b3: `ExecutionWalker.run` takes a trailing `entryArgs` list and binds it by
+  position onto the entry function's parameters (missing ones `null`) in
+  the root scope before the body runs — what `explore_run_flow` needs to
+  replay a parameterised `flow_*` helper live.
+- 56784b3: `explore_run_flow` replays parameterised flows: pass `args` (positional
+  JSON values, `"{{NAME}}"` for a variable) and the helper's parameters are
+  bound for the live replay — `flow_login(username, password)` no longer
+  fails with `Variable "username" is not defined`. `explore_start` lists
+  each flow's `params`; a wrong argument count is refused with the
+  signature. The recording keeps variable NAMES, so the saved test reads
+  `flow_login(LOGIN, PASSWORD);` — `flow_call` is now a regular action
+  plugin rendering the call with its arguments.
+- 307582f: New `explore_step` action `screenshot` — the evidence step of an
+  exploration. It files a PNG under the session
+  (`.unotest/explorations/<explorationId>/screenshots/<NNN>-<name>.png`,
+  `adhoc/` without a session), replies with the absolute `path`, `width`
+  and `height`, and returns the image itself as an MCP image block (a JPEG
+  copy when the PNG is over 1 MiB; path only when both are). `name`
+  defaults to the section slug, `fullPage` captures the whole page,
+  `locator` captures one element, `outline: true` adds the page outline
+  to the reply, `evidenceOnly: true` keeps the file but records no step.
+  A recorded screenshot becomes `screenshot(name)` in the saved test; an
+  element capture degrades to a page capture with a comment and a
+  non-blocking `DEGRADED_STEP` warning. `explore_stop` now lists the
+  session's files in `artifacts`. Driver: `DriverPage.screenshotElement`.
+- 6b61884: New linter rule `lint:external-variable-undeclared` (default `error`): a
+  bare `UPPER_SNAKE` identifier that no layer file declares — `unotest/.env`,
+  `unotest/.secrets`, or the `.env.<name>` / `.secrets.<name>` overlay of
+  the environment `lint --env <name>` / `UNOTEST_ENV` selects — is reported
+  with the files searched, instead of failing at that statement at run time
+  after the browser is up. A name bound in the file (assigned, a parameter,
+  a loop counter) is never flagged. The shell is not a declaration: a value
+  CI exports still needs its name in `unotest/.env` (`NAME=` with no value
+  declares it; the shell's value wins at run time, as before). As an error
+  it is not silenced by `// lint-ok:`; downgrade it in `linter.rules` if a
+  project needs that.
+
+  `run_test` (MCP) and `e2e` run the same check before the browser starts,
+  against what the run will actually resolve — files and the ambient shell
+  — so a suite that lives on a shell variable keeps running; a name that
+  would have failed in the scenario anyway now fails up front (`run_test`
+  answers `lint_failed`; `e2e` prints it and proceeds, like every pre-run
+  diagnostic).
+
+  The linter also descends into operator, array and property-access
+  operands now, so a regex or `{{mustache}}` literal inside `a + b` is
+  diagnosed the same as one on its own.
+
+- eddb1db: New linter rule `lint:one-test-per-file`: a second (third, …) top-level
+  `function test_*` in one scenario file is reported at its declaration.
+  A file is the unit a collection runs and the viewer shows — the Steps
+  tree projects a run onto the first `test_*`, so the others executed with
+  nowhere to be seen. Fold the cases into one test with tagged steps
+  (`step("…", {tag: id}, () => { … })`, `step.soft` when a case must not
+  stop the run) or move shared journeys into `flow_*` helpers under
+  `unotest/e2e/_helpers/`; `flow_*` functions in a scenario file are not
+  counted.
+
+  **Migration window:** the rule is a **warning** in 0.31 — visible in
+  `lint`, the editor and `run_test`'s warnings, silenced per line with
+  `// lint-ok: <reason>`, never blocking. A later minor release flips the
+  default to `error` (which the pre-run gate of `run_test` refuses); split
+  files that hold several `test_*` before then.
+
+- b0a00cb: New DSL function `readJsonLine(path, filter) → object`: read a JSONL file
+  that already exists and return the first line matching the key filter —
+  no polling. `waitForJsonLine` was the only structured input into a
+  scenario, and for a fixture or a finished export its 20s timeout only
+  masked a wrong path. `readJsonLine` takes the same filter (strict equality
+  per key, dot paths for nesting, unparsable lines skipped) and fails at
+  once: `file not found: <path>` when the file is missing, `no line matches
+{…} in <path>` with parse stats and the closest line when nothing matches.
+  Data-driven tests read their cases with it and name evidence after them
+  (`screenshot(q.id)`).
+- 100ab9d: Data-driven steps: `step("label", {tag: q.id}, () => { … })` names the
+  case an iteration is on, and `step.soft("label", [{tag}], () => { … })`
+  records a failure inside instead of stopping the run — the rest of that
+  body is skipped, the next case runs, and the test still ends **failed**
+  with every soft failure listed (`3 soft step(s) failed: Question [q17]:
+…`, one line per case in the CLI output; `run_test` answers
+  `next.softFailures`; `inspect_runtime`'s `lastFailure` carries `stepTag`
+  and `soft`). The failure bundle shows the page at the moment of the
+  **first** soft failure, with `soft: true` and `stepTag` in
+  `failure.json`; later soft failures live in the journal. `step.soft` is
+  allowed inside `test_*` only; nesting is free, and the outer step is a
+  group, not an assertion — a soft failure inside does not change its
+  outcome. The run journal gains `step-block:started` / `step-block:finished`
+  envelopes per block (label, tag, soft, outcome, whole-block duration).
+  Editor typings declare the new forms.
+- ad7c918: The run journal records every loop pass (`loop:iteration`, with the loop
+  statement's position and the pass index), which the viewer's new Trace
+  view uses to show a loop as one group per iteration. Also: when an error
+  unwinds through enclosing statements, `lastFailure` (the failure bundle's
+  position, `inspect_runtime`, the CLI's `in step "…" [tag]` line) now
+  names the innermost statement that raised it — the assert inside the
+  tagged step — instead of the outermost loop that re-threw it.
+
+### Patch Changes
+
+- 9ae6d59: A bundle no longer declares the runner's own `UNOTEST_*` settings
+  (`UNOTEST_HEADED`, `UNOTEST_LOG_LEVEL`, …) from the suite's `.env`, so a box
+  stops warning on every push that an environment "neither sets nor holds"
+  names `env push` never sends. Both sides now share one rule
+  (`isRunnerSetting` in `@unotest/protocol`): those variables configure the
+  machine a run happens on, not the suite. A per-suite value such as the
+  navigation timeout travels with the bundle through `unotest.config.mjs`
+  (`defaultNavigationTimeoutMs`), not through `.env`.
+- 917380d: `unotest.config.*` is merged with the defaults recursively. A partially
+  written section — `linter: { rules: { 'lint:deep-css': 'off' } }`,
+  `failureBundle: { tier3: { video: true } }`, `viewport: { width: 1920 }`
+  — now keeps the rest of that section's defaults instead of failing with
+  "config validation failed" (nested sections require all of their fields
+  at validation time, so a top-level replace made every partial section
+  invalid). Arrays and scalars still replace as a whole: `browsers:
+['firefox']` means firefox only. The setup manual's example config,
+  which was exactly such a partial `linter`, loads as written; its
+  `timeouts` block — never a config field — is corrected to
+  `defaultTimeoutMs` / `defaultNavigationTimeoutMs`.
+- e048334: The viewer's editor flags an undeclared external variable
+  (`lint:external-variable-undeclared`), the way `unotest-web lint` and the
+  pre-run lint already do: a bare `UPPER_SNAKE` identifier that no
+  `unotest/.env` / `.secrets` file of the active environment declares is an
+  error in the editor, naming the files searched. Protocol:
+  `DslValidateContext` gains `externalNames` / `externalSources`; the
+  viewer supplies them from the active target + environment's layer files
+  (the same files the variables panel shows) and `@unotest/web`'s language
+  service turns them into the linter's lookup.
+- dcf4c9e: Viewer editor: lint markers appear as soon as a file opens (or the page
+  reloads), not only after the first keystroke — the editor validates the
+  source it mounted with instead of waiting for a change event that a
+  reopened tab never fires.
+- 6646584: Docs: `hover` now lists its options (`force`, `position`, `timeout`) in
+  the DSL reference, the editor signature and the generated typings — it
+  used to read as if it took none, while `position` is exactly what a
+  hover-revealed menu at one edge of a tall element needs. The agent
+  integration guide gains "Watching a collection run": the collection's
+  `steps.jsonl` journal (path, the four `collection-run:*` events, how to
+  tail it) as the progress source for a run started in the background,
+  where the CLI's per-scenario lines only arrive when the process ends.
+- 630d6ce: `unotest-web lint` now receives its arguments: the bin dispatcher forwarded
+  only the command name, so `lint --env <name>` linted the base environment
+  and an explicit file argument was ignored (every file was linted instead).
+  `UNOTEST_ENV=<name>` worked all along, which is why the gap went unnoticed.
+- f3bd3cc: `lint` works on a project that has not migrated to the 0.28 layout yet.
+  A `unotest.config.*` still at the project root used to stop `lint` with
+  the same refusal `e2e` gives — right for a command that would RUN on
+  defaults, wrong for one that only grades: nobody lints a suite during
+  the very migration that touches every file. `lint` now builds its
+  context on the default settings (rule severities, helpers dir), reads
+  `unotest/.env`, `.secrets` and `_helpers/` as usual, and reports the
+  layout once as the new `lint:legacy-layout` warning (default `warn`,
+  configurable like any rule) with the migration on one line. The exit
+  code is unaffected by it. `e2e`, `collection` and `bundle push` refuse
+  exactly as before.
+- 224d016: The MCP server says when it is running a stale build. `run_test`'s
+  pre-spawn lint, flow discovery (`explore_start`), `explore_run_flow`,
+  `generate_dsl_from_exploration` and `save_exploration_as_test` parse and
+  render DSL in the server's own process, on the modules it loaded at
+  start — after a rebuild a new DSL feature came back as a false parse
+  error until the server was restarted, while the runner child was already
+  on the new build. Those replies now carry `serverStale: true` and a
+  `serverStaleWarning` ("restart the MCP server") once the code on disk is
+  newer than the server's start; nothing changes while it is fresh.
+- 02757c3: `serverStale` now also rides on `explore_step` / `explore_steps` (locator
+  resolution and recording run in the server's process), `find_element`
+  and `ground_element` replies — the same flag `run_test` and the
+  exploration tools already carry once the build on disk is newer than the
+  running MCP server.
+- dcf4c9e: `goto` with a relative path resolves against the runtime's own base URL
+  instead of the browser context's. In a CLI run the two coincide; in an
+  exploration recording against an `env` override, `explore_run_flow`
+  replayed `goto('/_guard/')` on the MCP session's shared context — created
+  with the server's base — and landed on the wrong host. The replay now
+  follows the session's `baseUrl` (and its variables, as before).
+- f3bd3cc: `screenshot(name)` accepts any string value, not only a literal. The
+  runtime always slugified whatever it received, but the validator (and
+  therefore `lint` and `run_test`) rejected `screenshot(q.id)` and
+  `screenshot(textJoin(['q-', id]))` — a data-driven test had to name every
+  capture the same. The `name` slot is now string-like, as in `fill`; a
+  non-string argument is still an `arg-kind` error.
+- dcf4c9e: A section label reopened after another section is called out instead of
+  silently splitting a step: `explore_step` / `explore_steps` reply with
+  `sectionHint` the moment it happens, and the generated draft carries a
+  non-blocking `SPLIT_SECTION` warning naming the reopened entries. The
+  recorded order of actions is never changed; `autoRun` and `save` are not
+  held back by it.
+- 9ae6d59: A scenario that finished in the same instant the viewer looked at it is no
+  longer recorded as `interrupted` with a finish an hour before its start.
+  The runner ends a run by appending `run:finished` and then backdating the
+  heartbeat; the viewer read those two files in the opposite order, so a
+  steps snapshot taken a few milliseconds early could meet the backdated
+  heartbeat, and the provisional verdict stuck in the run index while the
+  collection reported the scenario passed. The heartbeat is read first now.
+  A viewer restart (which rebuilds the index from disk) already corrected
+  such records; runs indexed live are right the first time.
+- 13a2d51: Viewer, Home tab: the tile of a scenario that is running now breathes
+  through colour and shadow only — the scale pulse is gone. It moved the
+  tile's box every frame, so an automation driver never saw the tile as
+  stable and a click on it waited out its timeout. A tile that never ran
+  no longer carries `data-age="fresh"`: it has no age, so the attribute is
+  absent.
+- 91fb562: Viewer, Home tab: clicking a scenario tile opens the scenario's LAST RUN —
+  the run whose verdict the tile's colour is showing — instead of the test
+  file. A tile that has never run still opens the test (there is no run to
+  open), and so does every tile in schedule mode, where the schedule is
+  edited from the test. The legend now reads "hover for history · click to
+  open the last run".
+- dcf4c9e: Viewer, Home tab: the tile field no longer refits itself in a loop. The
+  header and legend take the grid's width; when the legend wrapped at one
+  width and not at the next, the field's height changed, the fit followed,
+  the width changed back — at 60 fps every tile's box moved every frame,
+  and an automation click on ANY tile ("element is not stable") waited out
+  its timeout unless forced. Header and legend now never wrap (they grow
+  past the grid instead), so the fit converges and tiles stay put. A run
+  opened from a tile is titled by its scenario, like one opened from the
+  Runs tree, instead of by its run id.
+- dcf4c9e: Recording no longer bakes relative time or counters into a locator. An
+  accessible name such as `Run smoke — passed, 7m ago`, `just now`,
+  `yesterday`, `5 passed`, `7 runs` or a trailing badge (`Inbox · 3`,
+  `Errors: 12`) now counts as volatile: the recorder emits the stable prefix
+  (`{name: "Run smoke — passed", exact: true}`, then `/^Run smoke — passed\b/`)
+  instead of the literal, and the draft carries the `DYNAMIC_TEXT` warning
+  with that prefix. Bare numbers elsewhere stay stable (`Page 2`, `Q4 2026`,
+  `v2`, `2FA`).
+- Updated dependencies [b8e105b]
+- Updated dependencies [b8e105b]
+- Updated dependencies [b8e105b]
+- Updated dependencies [9ae6d59]
+- Updated dependencies [56784b3]
+- Updated dependencies [e048334]
+- Updated dependencies [dcf4c9e]
+- Updated dependencies [100ab9d]
+- Updated dependencies [100ab9d]
+- Updated dependencies [100ab9d]
+- Updated dependencies [100ab9d]
+- Updated dependencies [ad7c918]
+- Updated dependencies [ad7c918]
+- Updated dependencies [ad7c918]
+- Updated dependencies [9ae6d59]
+- Updated dependencies [13a2d51]
+- Updated dependencies [91fb562]
+- Updated dependencies [dcf4c9e]
+  - @unotest/core@0.31.0
+  - @unotest/protocol@0.31.0
+  - @unotest/viewer@0.31.0
+  - @unotest/dsl@0.31.0
+  - @unotest/grounder-client@0.31.0
+
 ## [0.30.0] - 2026-09-03
 
 ### Minor Changes

package/README.md

@@ -7,6 +7,11 @@ and commit.**
 MCP server + CLI runner + JavaScript DSL + semantic DOM snapshots +
 structured failure bundles.
 
+Full documentation — manuals, the box, CI, the judge — lives at
+[docs.unotest.com](https://docs.unotest.com). This README is the short
+tour; the package ships only `guides/dsl-reference.md` and
+`guides/agent-integration.md` alongside it.
+
 ---
 
 ## 1. Setup
@@ -170,7 +175,7 @@ a suite takes minutes, and a request held open that long is a timeout,
 not a result. Watch them in the viewer, or let the box report the checks
 back to GitHub. `--pr` makes a newer push withdraw the older runs of the
 same pull request that are still waiting, so three pushes in five minutes
-cost one suite. Recipe: `guides/manuals/ci-setup.md`.
+cost one suite. Recipe: [Pushing suites → A minimal CI job](https://docs.unotest.com/box/pushing-suites/#a-minimal-ci-job).
 
 The values a suite runs with on the box — `APP_BASE_URL`, its `.env`
 settings, its secrets — are sent separately, from the same files a local
@@ -184,7 +189,66 @@ printf '%s' "$KEY" | npx @unotest/web env set dev API_KEY --secret
 `.env*` become the environment's variables, `.secrets*` its secrets,
 `APP_BASE_URL` its target; `UNOTEST_*` stay home. A value never prints.
 The token must be minted with `--values` on the box. Admins also see and
-change them on the box's admin page. Manual: `guides/manuals/box-values.md`.
+change them on the box's admin page. Manual: [An environment's values on a
+box](https://docs.unotest.com/box/environments-and-values/).
+
+A run on the box happens inside the box's own container: nothing on your
+machine is reachable from it — no `localhost`, no `kubectl port-forward`,
+no tools installed on your laptop. Preconditions must probe the
+environment's public URL, and `assertJudge` runs its judge in-process there
+(`UNOTEST_JUDGE_MODE=local`, `@unotest/judge` in the suite's
+`package.json`, the API key as a secret). Details:
+[Judge on a box](https://docs.unotest.com/guides/judge/#on-a-box) and
+[What a box cannot reach](https://docs.unotest.com/box/troubleshooting/#what-a-box-cannot-reach).
+
+### Reading results from a box
+
+`bundle push --run` gives you a run id. Read what became of it from the
+same terminal — no browser, no shell on the box:
+
+```sh
+npx @unotest/web box runs --env acme/test --latest
+npx @unotest/web box run checkout-mqf3pwr1 --env acme/test
+```
+
+`box run` prints the failure, the results of soft steps and the judge's
+verdicts. When you want the artifacts too:
+
+```sh
+npx @unotest/web box run checkout-mqf3pwr1 --env acme/test --download
+```
+
+That saves the run's `*.unotest.zip` under `.unotest/box/` and unpacks its
+failure bundle into `.unotest/failures/` — where `list_failures`,
+`get_failure_*` and `agent_fix` already look, so your agent debugs a box
+failure with the commands it uses for a local one. Add `--no-screenshots`
+to leave the step frames on the box; they are usually most of the bytes.
+
+Reading uses a **personal** read token, not the project one. Put it in
+`unotest/.secrets`, next to your other project secrets:
+
+```sh
+UNOTEST_BOX_READ_TOKEN=ubr_...
+```
+
+and the box's address in `unotest/.env` as `UNOTEST_BOX_URL`. Both files
+are read directly, so this works the same from the terminal and from your
+agent. Exporting either value in your shell works too and wins over the
+file; `--box` and `--token` win over both.
+
+The token is never read from `unotest/.env` — that file travels inside a
+pushed bundle, and `.secrets` does not.
+
+Keeping it in the file is what lets your agent read runs: an MCP server is
+started by your editor, so a token that only exists in your shell is a
+token the agent never sees. A token added while the server is running is
+picked up on the next call — nothing to restart.
+
+You mint it for yourself on the box's guard ("Read tokens"), it is shown
+once, and it is revocable. It is read-only whatever your role on the box — it cannot start
+a run or change a value. `UNOTEST_BOX_TOKEN` is the project's push
+credential and cannot read runs. `box envs` lists the environments a token
+may look at.
 
 ## 5. Watch it run — the viewer
 

package/bin/unotest-web.js

@@ -75,7 +75,9 @@ function dispatch(sub) {
         forwardArgs: args.slice(1),
       };
     case "lint":
-      return { dist: "dist/runner/cli.js", src: "src/runner/cli.ts", forwardArgs: ["lint"] };
+      // Forwarded whole, like e2e: `--env <name>` and explicit file
+      // arguments belong to the command, not to the dispatcher.
+      return { dist: "dist/runner/cli.js", src: "src/runner/cli.ts", forwardArgs: args };
     case "viewer":
       return { dist: "dist/runner/cli.js", src: "src/runner/cli.ts", forwardArgs: ["viewer"] };
     case "prepare-fix":