@asrunjs/asrun 0.9.0 → 0.11.0

package/.claude/skills/exploring-cases/references/handoff-card.js

@@ -9,6 +9,52 @@ async (page) => {
   const maxMs = cfg.maxMs || 600000;
   await ctx.grantPermissions(['clipboard-read', 'clipboard-write']).catch(() => {});
 
+  // Record what the person does. The card owns both ends of the recording, so every way out stops it and no handoff
+  // leaks a recording into the next one (see user-handoff.md, "Recording"). Never call browser_start_recording: the
+  // playwright-test MCP lists it but cannot run it (devtools-only; see tools.md in this folder).
+  const CARD_CONTROL = /AsRun handoff:/i;
+  const entries = [];
+  const entry = (action, code) => ({
+    code,
+    card: CARD_CONTROL.test(String((action && action.selector) || '')),
+  });
+  const sink = {
+    actionAdded: (p, action, code) => entries.push(entry(action, code)),
+    actionUpdated: (p, action, code) => {
+      const next = entry(action, code);
+      if (entries.length) entries[entries.length - 1] = next;
+      else entries.push(next);
+    },
+    signalAdded: (p, signal, code) => {
+      const last = entries[entries.length - 1];
+      if (last && code && !last.card) last.code = code;
+    },
+  };
+  let recording = false;
+  let recordingError = null;
+  // Library-mode code (`page`, `page1`, ...) keeps the `newPage`/`close` lines of tabs the person opened by hand; the
+  // test-runner generator drops `openPage`/`closePage`.
+  const recordingOptions = {language: 'javascript'};
+  try {
+    if (typeof ctx._startRecording !== 'function' || typeof ctx._stopRecording !== 'function')
+      throw new Error('this Playwright has no browser-context recording');
+    await ctx._startRecording(recordingOptions, sink);
+    recording = true;
+  } catch (e) {
+    // A card that died before stopping left the context recording: close that one and try once more.
+    if (/already in progress/i.test(String(e && e.message))) {
+      await ctx._stopRecording().catch(() => {});
+      try {
+        await ctx._startRecording(recordingOptions, sink);
+        recording = true;
+      } catch (e2) {
+        recordingError = String((e2 && e2.message) || e2);
+      }
+    } else {
+      recordingError = String((e && e.message) || e);
+    }
+  }
+
   const paint = (p) => p.evaluate(({message, copy}) => {
     if (document.getElementById('__ASRUN_panel')) return;
     const KEY = '__ASRUN_panel_state';
@@ -41,9 +87,9 @@ async (page) => {
       '.row{display:flex;gap:8px}.row .primary{background:#15803d}.row .primary:hover{background:#16a34a}' +
       '</style>' +
       '<div class="card" id="card"><div class="bar" id="bar" title="Drag to move"><span class="grip">' + ICON.move + '</span><b id="title">YOUR TURN</b>' +
-      '<button class="mini-done" data-a="done">Done</button><button id="toggle" title="Minimize or expand" aria-label="Minimize or expand"></button></div>' +
+      '<button class="mini-done" data-a="done" aria-label="AsRun handoff: done">Done</button><button id="toggle" title="Minimize or expand" aria-label="AsRun handoff: minimize or expand"></button></div>' +
       '<div class="body"><div id="msg"></div><div id="chips"></div><div class="row">' +
-      '<button class="primary" data-a="done">Done</button><button data-a="skip">Cannot do this</button></div></div></div>';
+      '<button class="primary" data-a="done" aria-label="AsRun handoff: done">Done</button><button data-a="skip" aria-label="AsRun handoff: cannot do this">Cannot do this</button></div></div></div>';
     const card = root.getElementById('card'), bar = root.getElementById('bar'), toggle = root.getElementById('toggle');
     root.getElementById('msg').textContent = message;
     const chips = root.getElementById('chips');
@@ -51,7 +97,7 @@ async (page) => {
     for (const text of copy) {
       const chip = document.createElement('div');
       chip.className = 'chip';
-      chip.innerHTML = '<span></span><button aria-label="Copy to clipboard" title="Copy">' + ICON.copy + '</button>';
+      chip.innerHTML = '<span></span><button aria-label="AsRun handoff: copy to clipboard" title="Copy">' + ICON.copy + '</button>';
       chip.firstChild.textContent = text;
       const btn = chip.lastChild;
       btn.addEventListener('click', async () => {
@@ -107,14 +153,18 @@ async (page) => {
   for (const p of ctx.pages()) await p.evaluate(() => { window.__handoff = null; }).catch(() => {});
   const started = Date.now();
   let outcome = null;
-  while (!outcome && Date.now() - started < maxMs) {
-    for (const p of ctx.pages()) {
-      await paint(p);
-      const flag = await p.evaluate(() => window.__handoff || null).catch(() => null);
-      if (flag) outcome = flag;
-      else if (doneText && await p.getByText(doneText).first().isVisible().catch(() => false)) outcome = 'condition';
+  try {
+    while (!outcome && Date.now() - started < maxMs) {
+      for (const p of ctx.pages()) {
+        await paint(p);
+        const flag = await p.evaluate(() => window.__handoff || null).catch(() => null);
+        if (flag) outcome = flag;
+        else if (doneText && await p.getByText(doneText).first().isVisible().catch(() => false)) outcome = 'condition';
+      }
+      if (!outcome) await page.waitForTimeout(500);
     }
-    if (!outcome) await page.waitForTimeout(500);
+  } finally {
+    if (recording) await ctx._stopRecording().catch(() => {});
   }
   for (const p of ctx.pages()) {
     await p.evaluate(() => {
@@ -124,5 +174,17 @@ async (page) => {
   }
   await page.waitForTimeout(2300);
   for (const p of ctx.pages()) await p.evaluate(() => sessionStorage.removeItem('__ASRUN_panel_state')).catch(() => {});
-  return {outcome: outcome || 'timeout', waitedMs: Date.now() - started};
+  const dedent = (text) => {
+    const lines = text.split('\n');
+    const indents = lines.filter((line) => line.trim()).map((line) => line.length - line.trimStart().length);
+    const indent = indents.length ? Math.min(...indents) : 0;
+    return lines.map((line) => line.substring(indent)).join('\n');
+  };
+  return {
+    outcome: outcome || 'timeout',
+    waitedMs: Date.now() - started,
+    recording,
+    recorded: entries.filter((e) => e.code && e.code.trim() && !e.card).map((e) => dedent(e.code)),
+    ...(recordingError ? {recordingError} : {}),
+  };
 }

package/.claude/skills/exploring-cases/references/notes.md

@@ -0,0 +1,87 @@
+# The exploration note: what a run saw, in a form `/gen-spec` can read
+
+Local, git-ignored and optional. `exploring-cases` writes it; `generating-specs` (and healing) read it to **verify**
+instead of rediscovering the page. It is not part of the case and never becomes part of it: expected values stay in
+`## Values`, behaviour in `## Expected`, ready signals in `Ready when:`, and assertions never appear here.
+
+## Where it lives
+
+```
+.explore/notes/<case-id>/<profile-id>.json
+```
+
+One file per profile. A `--profiles a,b` run writes only `a.json` and `b.json`; a later run with `c` adds `c.json`
+next to them, so nothing is merged and an earlier observation is never overwritten. A fresh checkout has no notes, and
+that is a normal state: generation falls back to replaying the case.
+
+## The shape
+
+```json
+{
+  "version": 1,
+  "caseId": "conduit/header-navigation",
+  "profile": "example-staging",
+  "env": "staging",
+  "caseSha256": "<pnpm asrun explore:notes <case-id> --hash>",
+  "capturedAt": "2026-11-09T10:20:31Z",
+  "steps": {
+    "2": {
+      "url": "/",
+      "locators": [{"purpose": "the header navigation link", "locator": "page.getByRole('link', {name: 'Home'})"}],
+      "requests": ["/api/articles"]
+    }
+  },
+  "targets": {"T1": {"locator": "page.getByRole('img', {name: 'Example'})", "matches": 1}}
+}
+```
+
+- Keys of `steps` are the case's step numbers, keys of `targets` are its card ids (`T1`).
+- `steps` may be `{}` and `targets` may be omitted; every other key is required (`env` and `updatedAt` are optional).
+  No other field is accepted.
+- `caseSha256` is the 64-character hash `pnpm asrun explore:notes <case-id> --hash` prints (not the placeholder above).
+- `pnpm asrun explore:notes <case-id> --check` validates the files: it fails on a malformed note and warns on a note
+  whose `caseSha256` no longer matches the case (the summary already prints it as `stale`; re-run the exploration, or
+  delete the note and let the case be replayed). A file that fails is ignored by `/gen-spec`.
+
+## What goes in
+
+`steps.<n>`
+- `url`: the path the step runs on, relative to `baseURL` (`/documents/`), when it is not the current page.
+- `locators`: the element the step acts on, not every element on the page. `purpose` says what it is in words; `locator`
+  is exactly what `browser_generate_locator` returned. Prefer the stable controls (`getByRole`, `getByTestId`,
+  `getByLabel`) and one entry per action.
+- `requests`: the data-call paths the step's action started, taken from `browser_network_requests` above the marker
+  (`tools.md`, "Network requests without a clear"). Path only: `/api/articles`, never a host, a query string or a token.
+  Images, fonts and analytics are not data calls.
+
+`targets.T1`
+- `locator`: the card's `Identified by`, confirmed on the page.
+- `matches`: how many elements it matched — `1` for a completed card. A card with open doubts gets no entry.
+
+## What never goes in
+
+- Expected values, counts, texts a check asserts: they belong in the case's `## Values` and `## Expected`.
+- Ready signals: they belong in `Ready when:` (the note holds the request paths, not the promise).
+- Assertions, test steps or a copy of the spec.
+- Cookies, headers, storage state, tokens or a URL with a query string. `.explore/` is local, but a note is still not a
+  place for a credential (`F5`).
+- A selector or an id that a future run would copy into `cases/*.md`. The case stays implementation-free; the note is
+  the only place a locator lives.
+
+## Lists and changing data
+
+A list, a row or a search result is recorded by its container and position (`page.getByRole('row').nth(0)`), never by
+the name of the item, because the data changes between runs. The same rule as a recipe (`user-handoff.md`).
+
+## Freshness and the write-back
+
+- `caseSha256` is the sha256 of `cases/<case-id>.md` at the moment the note was written. If the case changes after that,
+  the note is **stale**: `/gen-spec` replays the case and does not use it.
+- `/gen-spec` confirms an entry of a fresh note on the page and may write the verified locator or request back
+  (`updatedAt` gets the time). It never adds a step or a target, and it never touches a stale note.
+- Deleting `.explore/notes/` is always safe: generation then re-derives everything from the page.
+
+## Who reads it
+
+Both skills read this file and `tools.md`, `readiness.md` and `assertion-targets.md`; the details of a browser call are
+in `tools.md`, never repeated here.

package/.claude/skills/exploring-cases/references/open-questions.md

@@ -5,7 +5,7 @@ without anybody present (a one-shot `claude -p` / `opencode run`). The case file
 talk to each other, so nothing is lost between runs, tools or sessions.
 
 ## How a question is written in the case file
-Every marker starts with its emoji, which is part of the marker: `🚫 TODO [blocking]`, `❓ TODO [non-blocking]`, `✍️ Answer:`, `🔍 to be confirmed by QA` and `👁️ not observed`. The web UI colors the emoji with the marker and offers an X button that deletes it.
+Every marker starts with its emoji, which is part of the marker: `🚫 TODO [blocking]`, `❓ TODO [non-blocking]`, `✍️ Answer:`, `🔍 to be confirmed` and `👁️ not observed`. The web UI colors the emoji with the marker and offers an X button that deletes it. `(seen on <profile>)` is not a marker: it is a plain note, shown as ordinary text.
 Every question is a small block that hangs under a normal sentence. The sentence is the agent's suggestion, written
 exactly as it should read in the final case. The block holds the question and an empty answer slot:
 
@@ -15,7 +15,7 @@ exactly as it should read in the final case. The block holds the question and an
     - ✍️ Answer:
 ```
 
-The same shape is used under a step, under a bullet of "Expected" and under the yaml block of "Values":
+The same shape is used under a step, under a bullet of "Expected" and on the prose line above the `## Values` block:
 
 ```
 11. Delete the document with the "Delete" option of its "..." menu on the list page. [writes]
@@ -40,8 +40,52 @@ Rules for writing it:
   QA should confirm it later but nothing waits for it.
 - One question per block; narrow broad questions down instead of copying them ("which profile elements?" becomes
   "is the logo the only per-profile element in the left side bar?").
-- A value read from a page is not a question: write it as a statement marked `(observed, 🔍 to be confirmed by QA)`.
-  It needs no TODO block; the reviewer confirms it by deleting the marker.
+- A fact read from a page is not a question: either say it as a plain note `(seen on <profile>)`, or mark it
+  `(observed on <profile>, 🔍 to be confirmed: <what a person must decide>)` when a wrong reading would still pass.
+  It needs no TODO block. See "Marker or question, never both" below.
+
+## Where the block hangs
+The parent line is the sentence the question is about: the panel shows it on its own, next to "The text above this
+question", so it has to make sense without the rest of the document.
+- **The immediate line, not an ancestor.** Hang the block under the one sentence that makes the claim. Under a
+  nested bullet, indent it under that bullet, not under the top-level one above it; when the claim only makes sense
+  with an umbrella sentence, write the claim itself as a top-level bullet and hang the block there.
+- **One claim, one block.** Several bullets raising one question get one block, under the closest of them, with the
+  others' evidence in that block. Never end a long list with a single question that covers all of it.
+- **A sentence that stands alone.** No "see above", no pronoun whose referent is in a sibling bullet.
+- **Never inside the `## Values` yaml block.** A marker or a question there becomes part of the expected value: put
+  it on the prose line above the block.
+
+## Marker or question, never both
+A sentence carries at most one "not settled yet" signal, and the two marks are alternatives:
+- `🚫/❓ TODO`: there **is** a question. The parent sentence is a suggestion, the block says what to decide.
+- `(observed on <profile>, 🔍 to be confirmed: <what a person must decide>)`: there is **no** question, only a check
+  somebody has to make later. The part after the colon is required: "to be confirmed by QA" alone tells a person
+  nothing, and the panel shows that part as "why it needs you".
+- `(observed on <profile>, evidence: .explore/observations/<case-id>/<image>.png)`: the same, with a screenshot the
+  reviewer opens instead of going back to the page. Save it while exploring.
+- `(seen on <profile>)`: a plain note. The run checks it, so nobody has to; it gets no colour and no panel row.
+
+- Never put a marker inside a TODO block: not in the question, not in the evidence, not in a wrapped line. The words
+  "to be confirmed", "TBC", "TBD" and "not observed" are marker words even in prose there, and `pnpm case:check` fails
+  on them.
+- Never put a marker on the sentence a block hangs under: keep the question and drop the marker.
+- `👁️ not observed` is for an expectation that came from the notes and was never seen on a page. It is never the
+  evidence of a question.
+
+## Which sentences carry a marker
+A marker is for exactly one thing: a fact a person must settle because a wrong reading would still pass. Ask yourself:
+**if this line were read wrong, would the generated spec fail?**
+- **It would fail** → no marker. Locators, the flow of a step, navigation, request URLs, readiness signals, whether an
+  element exists. The run is the confirmation. Leave `(seen on <profile>)` when where it was seen matters.
+- **It would pass anyway** → marker, with the reason. The literals a check asserts (a `## Values` entry, the wording of
+  an `## Expected` bullet) and the identity of a `[T<n>]` target. This is the class that hides a wrong expectation
+  forever; `assertion-targets.md` records two real incidents of it.
+- A `## Rules` bullet the agent inferred from a page carries a marker only when the rule changes what is asserted;
+  otherwise it is `(seen on <profile>)`. A rule a person stated never carries one.
+
+After a passing run, `pnpm markers:confirm --case <id> --env <env>` settles the markers whose line the spec checks
+(`// unconfirmed: <the sentence>`), so a person does not have to open the page again to see whether it is still true.
 
 ## How the user answers
 Two ways, and the agent must understand both on the next run:
@@ -69,7 +113,9 @@ answer, adds `(page shows <x> on <profile-id>)` and reports it as a finding. It
 ## Resolution order (no question goes to the user while a better step exists)
 1. **The page answers it.** Facts such as exact labels, which controls exist, where the logo is, what a menu holds
    are answered by exploration (`/explore-case`; needs an environment and a logged-in profile; the agent only reads, a person does the steps that write). Rewrite the parent sentence
-   with the fact, mark it `(observed, 🔍 to be confirmed by QA)` and remove the block.
+   with the fact and remove the block. Then decide the mark by "Which sentences carry a marker": a fact the run checks
+   gets `(seen on <profile>)`, a fact that would pass while wrong gets
+   `(observed on <profile>, 🔍 to be confirmed: <what a person must decide>)`.
    - A check with no expected value ("check X", "can see Y") becomes: the observed behaviour, marked as observed.
      A spec may be generated from it.
    - Values that a check asserts (logo name, label, option list) are observed per profile and written into the case's
@@ -101,13 +147,19 @@ answer, adds `(page shows <x> on <profile-id>)` and reports it as a finding. It
 
 ## Final report
 Report in the user's language. List every open block with its question and the parent sentence it would confirm, so
-the user can see what deleting it accepts. The last line of the final message is exactly one of:
+the user can see what deleting it accepts. List the markers separately, each with its reason and whether it changes an
+assertion: that is the short list a person actually has to look at. The last line of the final message is plain text
+and nothing else, exactly one of:
 
 ```
 RESULT: ready
 RESULT: needs-input
 ```
 
+Never put that line in a code fence or inline code, never make it bold, a heading or a list item, and put no label,
+number or emoji in front of it: the panel reads it to show how the run ended. (The block above only lists the two
+tokens; write the one that applies as the last line of your message, not the block.)
+
 - `ready`: no `[blocking]` question remains. Non-blocking ones may remain; list them so QA can confirm them.
 - `needs-input`: at least one `[blocking]` question remains in the case file (list each with its parent sentence),
   or the work could not be done (no environment, nobody logged in, or no permission to write files: a plan-mode run,

package/.claude/skills/exploring-cases/references/readiness.md

@@ -22,9 +22,10 @@ A check for something **missing, empty or hidden** is only valid after a positiv
 means: the list finished loading and has rows, and none is X.
 
 ## Exploring
-- Know the key requests: after the action, call `browser_network_requests`, pick the data calls (XHR/fetch to the
-  app's API, the ones that return the content). Wait until they are finished; use `browser_network_clear` before the
-  action so the list only holds what the action started.
+- Know the key requests: after the action, call `browser_network_requests` (`static: false`), pick the data calls
+  (XHR/fetch to the app's API, the ones that return the content). Wait until they are finished. `browser_network_clear`
+  is not runnable in this MCP, so take a marker instead: read the list before the action, keep the highest number, and
+  after the action only the entries above it belong to it (`tools.md`, "Network requests without a clear").
 - Then wait for the content signal (`browser_wait_for` with text, or `browser_find` that the content is there), and
   take the snapshot only then. A snapshot taken right after a click is a frame, not a fact.
 - Observations record the ready signal: `(observed after <signal>, ...)`. A fact with no signal is not recorded.
@@ -62,8 +63,9 @@ await expectImageLoaded(logo);
 
 - Register the response wait **before** the action (`actAndWait` does).
 - Every action that opens a dialog, a tab, a menu with data, a list or a preview waits for its key requests and its content
-  signal. The request URL patterns come from `browser_network_requests` during exploration, not from guesses; if none was
-  seen (the action was not run), say "not verified on the page" in the report.
+  signal. The request URL patterns come from the exploration note (`notes.md`) or, when it holds none, from
+  `browser_network_requests` during this replay; never from guesses. If none was seen (the action was not run), say
+  "not verified on the page" in the report.
 - Never `waitForTimeout`, never `networkidle`. They wait for time or for silence, not for the content. `pnpm spec:lint` fails both.
 - Never `if (await x.isVisible()) ...` to decide something that may not have loaded yet. Wait for a ready signal, then branch.
   Where an element is genuinely optional, say what proves the page finished (`// ready: ...`) before looking for it.

package/.claude/skills/exploring-cases/references/tools.md

@@ -0,0 +1,151 @@
+# The browser tools this MCP can run, and the ones it only lists
+
+Shared by `exploring-cases`, `generating-specs` and healing. It is binding in all three: read it before the first
+browser call of a run.
+
+`playwright run-test-mcp-server` answers `tools/list` with **every** browser tool Playwright has, but a call runs
+inside a paused test, and that backend installs one capability set:
+
+```js
+const config = { capabilities: ["testing"] };   // playwright/lib/mcp/test/browserBackend.js
+const toolList = tools.filteredTools(config);   // core* + testing, minus `skillOnly`
+```
+
+Everything outside that set is listed and still cannot run: it answers `Tool "<name>" not found`. Two groups:
+- a capability other than `core`/`testing` (`devtools`, `storage`, `network`, `pdf`, `vision`, `config`);
+- `skillOnly: true` tools, which the backend never installs (`browser_network_clear`, `browser_console_clear`).
+
+**`Tool "<name>" not found` is not a broken MCP server.** The server is up and every other tool works. Never stop
+with `RESULT: needs-input` for it, never report a missing MCP server, and never fall back to an ad-hoc Playwright
+script (it sees a different browser and its network view is not `browser_network_requests`, see A2). Use the
+substitute below instead, and say in the report which substitute you used.
+
+`pnpm asrun doctor` prints how many tools the installed Playwright actually runs and warns when this file names one
+it cannot (it happens when Playwright changes the filter; the file then needs the same edit).
+
+## Starting a session
+
+Both `exploring-cases` and `generating-specs` (and healing) drive the browser through this MCP, one profile at a time.
+
+1. Check the session with `pnpm status --env <env>` (or `pnpm status` when the environment is the profile's). It can fail
+   with a sandbox error (`listen EPERM`, a Chromium start failure): then open the profile's page and judge by the login
+   page instead.
+2. Start the session with `generator_setup_page` (`project=<profile-id>`, `seedFile=tests/seed.spec.ts`, `plan=""`).
+   Every later call belongs to that profile.
+3. A profile that is not logged in is skipped and named in the report; a human runs `pnpm signin <profile-id>`. Never
+   explore a profile a selection leaves out (`--profiles` in exploration), and never add one to fill a gap.
+
+If no `browser_*` / `generator_*` tool is registered at all, or the server reports that it failed to start, stop: tell
+the user which MCP server is missing and to run `pnpm asrun doctor`, write nothing, and end with `RESULT: needs-input`.
+
+## Short calls
+
+A call that hangs is the normal failure mode of this MCP, so keep every call small.
+
+- One `browser_run_code_unsafe` call does one thing and finishes within about 60 seconds. Do not close a tab, click,
+  wait for a dialog and read it in one call: split it and take a `browser_snapshot` between the steps. Only the handoff
+  wait loop may take minutes.
+- The browser times out an action or a lookup after 15 s (the config sets it). Pass `{timeout: 5000}` when you wait for
+  something that may not appear, and use `.catch()` or `isVisible()` for a one-time look **while exploring only**.
+  `isVisible()` answers for this instant and ignores any `timeout` passed to it, so take a snapshot or wait for a signal
+  after an action first. Never copy this pattern into a spec (`readiness.md`, "Optional confirmations").
+- After a click that should open something, take a snapshot and see what opened before you wait for it by role. A dialog
+  that did not appear is a finding (what did open instead?), not something to wait for or retry.
+- A step that fails or times out twice is not tried a third time: record what you saw and go on (a `TODO [blocking]`
+  under the step in a case, a `needs-input` report when writing a spec).
+
+## Runnable
+
+Navigation and reading:
+`browser_navigate`, `browser_navigate_back`, `browser_snapshot`, `browser_find`, `browser_evaluate`,
+`browser_run_code_unsafe`, `browser_tabs`, `browser_resize`, `browser_close`, `browser_handle_dialog`,
+`browser_console_messages`, `browser_emulate_media`, `browser_wait_for`.
+
+Interaction: `browser_click`, `browser_type`, `browser_fill_form`, `browser_press_key`, `browser_hover`,
+`browser_drag`, `browser_drop`, `browser_select_option`, `browser_file_upload`.
+
+Screenshots: `browser_take_screenshot`.
+
+Network: `browser_network_requests`, `browser_network_request`.
+
+Test helpers: `browser_generate_locator`, `browser_verify_element_visible`, `browser_verify_text_visible`,
+`browser_verify_list_visible`, `browser_verify_value`.
+
+`browser_run_code_unsafe` takes Playwright's own API (a `page`, `context`, `expect` are in scope), which is what
+every substitute below uses.
+
+## Listed but not runnable
+
+| Tool | Why | Do this instead |
+|---|---|---|
+| `browser_highlight`, `browser_hide_highlight` | `devtools` | [Outline a target](#outlining-a-target-without-browser_highlight) |
+| `browser_network_clear` | `skillOnly` | [Network requests without a clear](#network-requests-without-a-clear) |
+| `browser_console_clear` | `skillOnly` | read `browser_console_messages` and note the messages you already saw |
+| `browser_start_recording`, `browser_stop_recording` | `devtools` | the handoff card (`user-handoff.md`, "Recording") |
+| `browser_annotate` | `devtools` | let the person name the element in the handoff card, then outline it yourself |
+| `browser_start/stop_tracing`, `browser_start/stop_video`, `browser_video_*`, `browser_resume` | `devtools` | not needed by a case |
+| `browser_cookie_*`, `browser_localstorage_*`, `browser_sessionstorage_*`, `browser_storage_state`, `browser_set_storage_state` | `storage` | never: saved logins are passwords (F5) |
+| `browser_route`, `browser_unroute`, `browser_route_list`, `browser_network_state_set` | `network` | never: a case checks the real page |
+| `browser_pdf_save` | `pdf` | a page that serves a PDF is downloaded and rendered (`pnpm pdf:render`) |
+| `browser_mouse_move_xy`, `browser_mouse_down`, `browser_mouse_up`, `browser_mouse_wheel`, `browser_mouse_click_xy`, `browser_mouse_drag_xy` | `vision` | `browser_click` with a locator |
+| `browser_get_config` | `config` | `pnpm status --env <env>` |
+
+## Arguments the schema requires
+
+A call that looks complete still fails when one of these is missing. Both come from the MCP's own schema, and both
+answer `Missing key`:
+
+1. **`intent` on every action, input and assertion tool.** The test runner adds it so the recorded step has a name.
+   One short sentence, imperative, about what this call is for: `intent: "open the article preview"`. It belongs on
+   `browser_navigate`, `browser_navigate_back`, `browser_click`, `browser_type`, `browser_fill_form`,
+   `browser_press_key`, `browser_hover`, `browser_drag`, `browser_drop`, `browser_select_option`,
+   `browser_file_upload`, `browser_evaluate`, `browser_run_code_unsafe`, `browser_tabs`, `browser_close`,
+   `browser_resize`, `browser_handle_dialog`, `browser_emulate_media`, and on `browser_wait_for` and every
+   `browser_verify_*`. The read-only tools (`browser_snapshot`, `browser_find`, `browser_take_screenshot`,
+   `browser_console_messages`, `browser_network_requests`, `browser_network_request`, `browser_generate_locator`) take
+   none.
+2. **A field with a default is published as required:**
+   - `browser_take_screenshot` → `scale: "css"` (CSS pixels, the size baselines expect).
+   - `browser_network_requests` → `static: false` (data calls only).
+   - `browser_network_request` → `index` (from the numbered list).
+   - `browser_tabs` → `action` (`"list"`, `"new"`, `"select"` or `"close"`).
+   - `browser_console_messages` → `level` (`"error"` is enough).
+   - `browser_handle_dialog` → `accept` (`true` to accept, `false` to dismiss).
+   - `generator_setup_page` → `project`, `seedFile` and `plan` (`plan: ""` when there is no plan).
+
+## Outlining a target without `browser_highlight`
+
+`browser_highlight` is a one-line wrapper over `locator.highlight()`, and that method is public Playwright API. The
+overlay is the real one, not an approximation, and nothing of the page is changed.
+
+1. Outline (one call, one element, the card's `Identified by` as the locator):
+   ```js
+   // browser_run_code_unsafe({intent: 'outline the target for the reference screenshot', code: ...})
+   async (page) => {
+     const target = page.getByRole('img', {name: '<the Identified by value of the card>'});
+     await target.highlight({style: 'outline: 3px solid #e11d48; outline-offset: 2px'});
+     return await target.toString();
+   }
+   ```
+2. Screenshot the page (not the element) so the reader sees where it sits:
+   `browser_take_screenshot({scale: 'css', filename: '.explore/targets/<case-id>/T<n>-<profile-id>.png'})`
+3. Remove it before the next step: `browser_run_code_unsafe` with `intent: 'remove the highlight overlay'` and
+   `async (page) => { await page.hideHighlight(); }`.
+
+A highlight overlay is not page state: it never appears in a snapshot, it is not part of what the case checks, and
+`page.hideHighlight()` clears all of them. Do this for every candidate when several elements are compared, and say in
+the card what the screenshot shows.
+
+## Network requests without a clear
+
+`browser_network_requests` returns a numbered list that only grows while the page stays open, so a marker works:
+
+1. Before the action: `browser_network_requests({static: false})`, note the highest number in the list (`mark`).
+2. Do the action.
+3. Read `browser_network_requests({static: false})` again and take the entries above `mark`: those, and only those,
+   were started by the action. `browser_network_request({index})` gives one request's detail and status.
+
+Record the marker as a plain note in the report (`after 12 new requests; the data call was 7`), never in the case.
+
+4. While exploring, write the data-call paths of the action into the profile's exploration note (`notes.md`): path only,
+   no host, no query string. `/gen-spec` turns them into the `responses` of `actAndWait`.

package/.claude/skills/exploring-cases/references/user-handoff.md

@@ -1,7 +1,7 @@
 # User handoff: a person works in the browser, the agent waits
 
 Used by `exploring-cases` (and by `making-cases` never: it does not open a browser). `generating-specs` never hands
-off; it replays the step recipes that an exploration recorded.
+off; it replays the step recipes and the exploration note (`notes.md`) that an exploration recorded.
 
 ## The rule
 **An agent never writes data.** Not in staging, not in production. Every step that creates, edits, publishes, shares,
@@ -29,7 +29,9 @@ that nobody watches.
    copied with one click.
 3. Never ask the user to send email (production: never; other environments: only when `email` is `true` for the
    profile). Never ask for login or 2FA. Name everything the user creates `[asrun] <something>`.
-4. Start recording with `browser_start_recording` (see "Recording").
+4. Do not start a recording yourself: the card starts and stops it (see "Recording"). Never call
+   `browser_start_recording` or `browser_stop_recording`: the `playwright-test` MCP lists them but cannot run them
+   (`devtools` tools; see `tools.md`).
 
 ## The wait loop
 Run it with one `browser_run_code_unsafe` call. A single call may wait for minutes (verified: 150 s without a
@@ -63,8 +65,9 @@ inside the call that runs the card: OpenCode reports a tool call only when it en
 way the web UI can see that a person is needed while the card waits. With the card alone there is no "Your turn"
 badge, no count in the tab title and no notification (a HINT in the job log says so).
 
-1. Set the options on the browser context (this call only sets data):
+1. Set the options on the browser context (this call only sets data; `browser_run_code_unsafe` needs `intent`):
    ```js
+   // browser_run_code_unsafe({intent: 'set the handoff card options', code: ...})
    async (page) => {
      page.context().__handoffCfg = {
        message: '<what the user does, one sentence>',
@@ -77,11 +80,16 @@ badge, no count in the tab title and no notification (a HINT in the job log says
    ```
 2. Run the card and wait: `browser_run_code_unsafe` with `filename` set to the absolute path of
    `<framework>/.claude/skills/exploring-cases/references/handoff-card.js` (use the absolute path of the repository, a
-   relative one is resolved against the workspace root, which may be the parent folder). It returns `{outcome: 'done' | 'skip' | 'condition' | 'timeout', waitedMs}`.
+   relative one is resolved against the workspace root, which may be the parent folder) and an `intent` such as
+   `'hand off step 5 to the person'`. It returns
+   `{outcome: 'done' | 'skip' | 'condition' | 'timeout', waitedMs, recording, recorded}`: `recorded` holds the
+   actions the person performed, one Playwright line each, across every tab (`page`, `page1`, ...), and is empty when
+   the recording was unavailable (`recording: false`; `recordingError` says why).
 
 Check once, after the card shows, that it looks right: take a screenshot and see a title bar with a move icon, a
-chevron button at its right and, when `copy` is not empty, a line per text with a copy icon. If not, stop and report
-it; do not hand off with a broken card.
+chevron button at its right and, when `copy` is not empty, a line per text with a copy icon. Playwright's own recording
+toolbar at the top of the page is expected and is not part of the card. If the card is not right, stop and report it;
+do not hand off with a broken card.
 
 Tell the user in the chat (the terminal or the UI job log) as well: "Your turn in the browser window: <task>. Press
 Done on the card (bottom-left; drag it if it is in the way) when you finish." When the run was started from the web
@@ -105,17 +113,21 @@ The Done button is always there (also on the minimized card) as the fallback, an
   for two seconds before it is removed, so the user knows when they may let go.
 - `outcome: 'timeout'` or `'skip'`: do not guess. Write a `TODO [blocking]` under the step and go on with what does
   not depend on it.
-- Take a snapshot and write down what the user did (see "Recording"), then continue read-only.
+- Take a snapshot, write down what the user did from the card's `recorded` (see "Recording"), then continue read-only.
 - At the end of the exploration hand off once more when the user created data: "Delete the [asrun] items you
   created, then press Done". The case must clean up after itself, and so must the exploration.
 
 ## Recording
-Between the start and the end of a handoff the agent records what the user does (`browser_start_recording`,
-`browser_stop_recording`). The recorded Playwright code is **raw material, never saved as it is**. It is turned into
-a general recipe and written under the step as `- Recipe (phase): ...` lines (format below). The recipe holds what the
-user did in words, plus the **labels and roles of the controls** they used ("the textbox 'Title'", "the button
-'Next'"), because `/gen-spec` cannot write data and so cannot see those controls itself. It never holds selectors,
-ids or the names of data that can change.
+The card records what the person does: it starts the recording when it shows and stops it on every way out (Done,
+"Cannot do this", the finish condition, the timeout, an error), in the same `browser_run_code_unsafe` call. The agent
+neither starts nor stops it. The result is the card's `recorded`: one Playwright line per action, `page` for the first
+tab that acted and `page1`, `page2`, ... for the others. The aliases follow the order in which actions first appear,
+not the order in which the tabs were opened, so read the actions before you describe tabs.
+
+The recorded Playwright code is **raw material, never saved as it is**. It is turned into a general recipe and written
+under the step as `- Recipe (phase): ...` lines (format below). The recipe holds what the user did in words, plus the
+**labels and roles of the controls** they used ("the textbox 'Title'", "the button 'Next'"), because `/gen-spec` cannot
+write data and so cannot see those controls itself. It never holds selectors, ids or the names of data that can change.
 
 Make the recipe as general as possible, because lists and data change:
 - **A choice from a list that can change** (items, search results, a contact list): record the position, never the
@@ -123,14 +135,31 @@ Make the recipe as general as possible, because lists and data change:
 - **Random is allowed only when the user asks for it** ("pick any 3"). The default is the position, because it can be
   repeated. A random pick must be written into the test's annotations when the spec runs.
 - **Text the case creates**: `[asrun] <something>`.
-- **A value that has to exist** (an existing name, a search term): write what it must be like ("a name that
-  returns a result") and the observed value as `(observed "<value>", 🔍 to be confirmed by QA)` plus a
-  `[non-blocking]` TODO block. Do not put a brittle literal in as the only truth.
+- **A value that has to exist** (an existing name, a search term): the recipe says what it must be like ("a name
+  that returns a result") and notes the observed value as plain text `(seen on <profile>: "<value>")`. Do not put a
+  brittle literal in as the only truth. One claim carries one signal: when a `[non-blocking]` TODO under the recipe
+  asks whether any such value is acceptable, the observed value gets **no** marker (`open-questions.md`, "Marker or
+  question, never both").
 - **Nothing that depends on the pick** may become an assertion (a total changes with the items). Say so in a
   TODO when a check would.
 - Settings that the user changed on purpose (a toggle, a template) are recorded as they were set, by label.
 
-If the recording tool fails or returns nothing, describe what the user did from before/after snapshots instead.
+The recording is raw: merge and prune it before you write the recipe.
+- **The same action can appear twice**, and clicking a checkbox or its label can give both a `click` and a `check`.
+  Write it once ("check 'Agree'").
+- **Side products**: clicking a textbox to focus it, `Cmd+C`, `Scroll`, `Escape`. Keep only actions that change data
+  or the page's state.
+- **The card's own buttons are filtered out** of `recorded`. A click on the card's text (not a button) can still show
+  up; ignore it.
+- **Not recorded at all**: drag and drop, native file pickers, OS dialogs. Describe those from before/after snapshots.
+
+If `recording` is `false` or `recorded` is empty, do not silently write a recipe from snapshots: write a
+`🚫 TODO [blocking]` under the step that says the step was not recorded (and why, from `recordingError` when there is
+one). A recipe from before/after snapshots may be added next to that block only, and must say that it came from
+snapshots, not from a recording.
+
+If Playwright's own recording toolbar shows at the top of the page while the card waits, it is not AsRun's: leave it
+alone.
 
 ## Recipe lines under a step
 One or more `- Recipe (phase): ...` lines directly under the `[input]` or `[writes]` step they belong to, indented by
@@ -139,7 +168,7 @@ keep in sync.
 
 ```
 3. Select an existing document and pick 3 items. [input]
-    - Recipe (start): search for an existing document and pick result #1 (observed search term "...", 🔍 to be confirmed by QA).
+    - Recipe (start): search for an existing document and pick result #1 (seen on example-staging: "quarterly report").
       - ❓ TODO [non-blocking]: Is any result that opens fine as the starting point? (seen on example-staging)
         - ✍️ Answer:
     - Recipe (items): select 3 items by position (#1 to #3) from the list.