@asrunjs/asrun 0.10.0 → 0.11.0

package/.claude/skills/exploring-cases/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: exploring-cases
-description: Explores the real pages for one case document (cases/<id>.md) before its spec is generated, for every logged-in profile or only the ones named with --profiles. Checks the case against profiles.yaml and the pages, fixes wording mistakes, records what the pages show, turns unknowns into answerable TODO blocks, and, in an attended run, lets the person do the steps that write data or need a choice while it waits and records a general recipe under that step's `- Recipe:` lines. Ends with RESULT ready or needs-input. Use when asked to explore, review, check, clean up or narrow down a case, or for /explore-case. Its open-question rules are shared with generating-specs.
+description: Explores the real pages for one case document (cases/<id>.md) before its spec is generated, for every logged-in profile or only the ones named with --profiles. Checks the case against profiles.yaml and the pages, fixes wording mistakes, records what the pages show, turns unknowns into answerable TODO blocks, and, in an attended run, lets the person do the steps that write data or need a choice while it waits and records a general recipe under that step's `- Recipe:` lines. Also writes a local exploration note (locators and data-call paths) under `.explore/` for `/gen-spec` to verify instead of rediscovering. Ends with RESULT ready or needs-input. Use when asked to explore, review, check, clean up or narrow down a case, or for /explore-case. Its open-question rules are shared with generating-specs.
 ---
 
 # Exploring a case document
@@ -9,8 +9,10 @@ Read the workspace `AGENTS.md` (hard rules and project rules), `cases/_template.
 (how a case's `## Rules` are read, applied and maintained), `references/open-questions.md` (how
 questions are written, resolved and reported), `references/assertion-targets.md` (which exact image, text, file or
 place a check looks at, and when to ask instead of picking), `references/readiness.md` (wait for the content before
-you read it) and `references/user-handoff.md` (how a person works in the browser while the agent waits, and how it is
-recorded). All but the last are binding for `/gen-spec` and healing too.
+you read it), `references/tools.md` (the browser tools this MCP can run, and the substitutes for the ones it cannot),
+`references/notes.md` (the local exploration note `/gen-spec` reads) and `references/user-handoff.md` (how a person works
+in the browser while the agent waits, and how it is recorded). All but the last are binding for `/gen-spec` and healing
+too.
 
 ## Before you start
 Read the workspace `AGENTS.md`: its §2 holds the project rules, and it points at the framework baseline. If
@@ -23,14 +25,14 @@ Three steps, each learns one thing:
 1. `/make-case` (making-cases): the **intent**. Turns raw notes into case documents. No browser.
 2. `/explore-case` (this skill): the **facts and the inputs**. What the pages really show, and what a person has to
    do for the steps that write or need a choice. The only step where a person and the agent work together.
-3. `/gen-spec` (generating-specs): the **implementation**. Replays the case and its step recipes to find locators and
-   writes the spec. It does not judge the case again.
+3. `/gen-spec` (generating-specs): the **implementation**. Replays the case, its step recipes and the exploration note to
+   find locators and writes the spec. It does not judge the case again.
 
 The purpose of this skill is to leave a case that can be replayed without anybody: no ambiguity, every fact marked
 as observed, every input step described as a general recipe.
 
-This skill edits `cases/<id>.md` only. It never edits `profiles.yaml`, `tests/`, the framework folder or anything
-under `.auth/`.
+This skill edits `cases/<id>.md` and writes its local exploration note under `.explore/notes/`. It never edits
+`profiles.yaml`, `tests/`, the framework folder or anything under `.auth/`.
 **The agent never writes data**, in staging or in production: a person does every step that writes or needs a
 choice (see `references/user-handoff.md`).
 
@@ -77,22 +79,14 @@ one exception is a handoff in an attended run, where waiting for the person is t
 3. **Repair the wording** (edit the file). Fix typos and grammar, make steps one action or one check each, put
    assumptions in `## Notes` (not in `## Expected`), remove duplicates and template placeholders, make paths relative
    to the app. Do not add checks the case did not ask for and do not drop any. Never edit the `## Source` table.
-4. **Explore**. The exploration runs through the `playwright-test` MCP only. Read `references/tools.md` before the
-   first browser call: that MCP lists many tools it cannot run, and a call that answers `Tool "<name>" not found`
-   means exactly that — the server is up, use the substitute in that file, do not stop and do not report a missing
-   MCP server. If the tools are not registered in this session at all (no `browser_*` / `generator_*` tool) or the
-   server reports that it failed to start, do not fall back to ad-hoc Playwright scripts: they see a different browser
-   and their network view does not count as `browser_network_requests` (A2). Stop, tell the user which MCP server is
-   missing and to run `pnpm asrun doctor` (it names the broken `.mcp.json` / `opencode.jsonc` and the fix), make no
-   observations, and end with `RESULT: needs-input`.
-   Run `pnpm status --env <env>`. If it cannot run (a sandbox error such as
-   `listen EPERM` or a Chromium start failure), do not give up: open the profile's page through the MCP, and a page
-   that lands on the login page means the profile is not logged in. Explore each profile `--profiles` names that is
-   logged in, and, without `--profiles`, at least one logged-in profile per domain, with the `playwright-test` MCP
-   (`generator_setup_page` with `project=<profile-id>`, `seedFile=tests/seed.spec.ts` and `plan=""`). Never explore a
-   profile the selection leaves out, and never add a profile to fill
-   a gap. Profiles that are selected but not logged in are skipped and named in the report; a human runs
-   `pnpm signin <profile-id>`.
+4. **Explore**. The exploration runs through the `playwright-test` MCP only: read `references/tools.md` before the
+   first browser call and follow its "Starting a session" and "Short calls" sections. If the tools are not registered
+   in this session at all (no `browser_*` / `generator_*` tool) or the server reports that it failed to start, do not
+   fall back to ad-hoc Playwright scripts: stop, tell the user which MCP server is missing and to run `pnpm asrun
+   doctor`, make no observations, and end with `RESULT: needs-input`.
+   Explore each profile `--profiles` names that is logged in, and, without `--profiles`, at least one logged-in profile
+   per domain. Never explore a profile the selection leaves out, and never add a profile to fill a gap. Profiles that
+   are selected but not logged in are skipped and named in the report; a human runs `pnpm signin <profile-id>`.
    - Do the read-only steps yourself: open, look, read, hover, switch tabs, open and close dialogs and menus.
    - **A step that writes or needs a choice is done by the person**, per `references/user-handoff.md`: announce it,
      name the finish condition, run the wait loop (the card records what the person does), then write down what
@@ -109,38 +103,23 @@ one exception is a handoff in an attended run, where waiting for the person is t
      avoid is followed on every profile. Re-check each rule against the page: one that no longer holds gets a TODO
      with evidence under it, never silent deletion or rewriting. A rule never lets you write data or do a person's
      step.
-   - **Ready before you read** (`references/readiness.md`): note the highest number of
-     `browser_network_requests` (`static: false`) before an action that loads something, then the action, then wait for
-     its key requests (the numbers above that mark) and for the content signal, and only then take the snapshot.
-     `browser_network_clear` is not runnable in this MCP: the marker replaces it (`references/tools.md`). When the
-     first read is empty or missing something, wait and read again before you record or ask anything. Record the
-     signal as a plain note, `(seen on <profile>, after <signal>)`: the spec waits for it, so no person has to confirm
-     it.
-   - **Targets, not guesses** (`references/assertion-targets.md`): for every check on a logo, image, icon, file, PDF,
-     screenshot or repeated text, list ALL candidates, outline the one that is meant (`locator.highlight()` through
-     `browser_run_code_unsafe`, see `references/tools.md`), take the screenshot to `.explore/targets/<case-id>/`,
-     **open that screenshot and look at it**, then clear it with `page.hideHighlight()`, and write the card under
-     `## Targets`. If there are several candidates, only a position to tell them apart, a generic locator, dynamic
-     data in the area, or the page differs from the case: write a `[blocking]` TODO that names the exact image, text,
-     place or UI wanted and lists the candidates. In an attended run let the person name the element in the handoff
-     card, then outline what they named (`browser_annotate` is not runnable here).
-   - **Downloads and email composers are opened for real** (the composer is closed with "Discard"). A download is
-     verified in five parts: starts, finishes, file exists, file valid, and a failure or timeout fails the check
-     (see `references/readiness.md`). Record the file name, size and kind as observed. A downloaded PDF is rendered
-     (`pnpm pdf:render`) and its page images are opened and looked at: record which pages show the target, where, and
-     the text. Which pages the check covers follows the case: every page unless the case says ONLY (strong wording).
+   - **Ready before you read**: follow `references/readiness.md`, "Exploring". Record the signal it proves as a plain
+     note, `(seen on <profile>, after <signal>)`: the spec waits for it, so no person has to confirm it. When the first
+     read is empty or missing something, wait and read again before you record or ask anything.
+   - **Targets, not guesses**: follow `references/assertion-targets.md`, "How a card is made (exploring)". List ALL
+     candidates, outline the one that is meant, take the screenshot to `.explore/targets/<case-id>/`, **open it and look
+     at it**, clear the highlight and write the card under `## Targets`. When candidates cannot be told apart, or only a
+     position, a generic locator or dynamic data would decide it, write a `[blocking]` TODO that names the exact image,
+     text, place or UI wanted and lists the candidates. In an attended run let the person name the element in the
+     handoff card, then outline what they named (`browser_annotate` is not runnable here).
+   - **Downloads and email composers are opened for real** (the composer is closed with "Discard"). Verify a download
+     in the five parts of `references/readiness.md`, "Downloads", and record the file name, size and kind. Render a
+     downloaded PDF (`pnpm pdf:render`), open its page images and record which pages show the target, where, and the
+     text; the pages follow the case (every page unless the case says ONLY).
    - Compare every step with what is really there.
-
-   **Keep every browser call short, so nothing hangs** (`generating-specs` follows the same rules):
-   - One `browser_run_code_unsafe` call does one thing and should finish within about 60 seconds. Do not close a tab,
-     click, wait for a dialog and read it in one call: split it, and read the page (`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 a shorter `{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 after an action take a snapshot or
-      wait for a signal first. Never copy this pattern into a spec (see `references/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.
+   - **Record the exploration note** for this profile as you go, in the shape of `references/notes.md`: the locator of
+     each step's main control, the data-call paths of each loading action, and each target it confirmed. It is local
+     cache under `.explore/`, never case content, and `/gen-spec` reads it; step 8 writes the file.
    - A step that fails or times out twice is not tried a third time: write what you saw, add a `TODO [blocking]` under
      the step and go on with the next one.
 5. **Write the `## Targets` section and the ready signals.** One card per target, in the format of
@@ -162,12 +141,18 @@ one exception is a handoff in an attended run, where waiting for the person is t
    the rules: apply what holds, move what belongs in another section, and leave a question under a rule that conflicts
    or is obsolete. Then apply the `--hints` gate of `references/case-rules.md`: a reusable, general instruction goes
    into `## Rules` (with a marker only when it changes what is asserted); a one-off clue stays in the report.
-8. **Check**: run `pnpm case:check` (it fails on an incomplete target card, a rule that names a missing step, and
-   warns on a check that has none) and fix every FAIL. If it fails with a sandbox error (`listen EPERM`), run
+8. **Write the exploration note, then check.** After the case edits are done (so `caseSha256` is the case's final hash;
+   `pnpm asrun explore:notes <case-id> --hash`), write `.explore/notes/<case-id>/<profile-id>.json` for every profile
+   explored in this run, in the shape of `references/notes.md` and with only what was seen. Then run `pnpm case:check`
+   (it fails on an incomplete target card, a rule that names a missing step, and warns on a check that has none) and
+   `pnpm asrun explore:notes <case-id> --check` (it fails on a malformed note and warns on a stale one; the summary
+   line of every profile you explored must say `fresh`), and fix every FAIL. If
+   `case:check` fails with a sandbox error (`listen EPERM`), run
    `node --import tsx <framework>/scripts/check-cases.ts` instead; it checks the same thing.
 9. **Report** in the user's language: what was changed (wording fixes, observations added, TODOs closed or narrowed),
    what was explored (profile ids), which profiles `--profiles` left out (and that a run with them covers the rest),
-   which steps the person did and what was recorded for them, what was skipped and
+   which steps the person did and what was recorded for them, what the exploration note covers (and what it does not),
+   what was skipped and
    why, the target cards written (and which ones are still questions), the steps whose first read was too early,
    the steps that could not be observed (and why), the questions that remain
    with the sentence that deleting each block would confirm, the markers with their reason and whether each changes an
@@ -177,7 +162,9 @@ one exception is a handoff in an attended run, where waiting for the person is t
    requires: plain text on the last line, never inside a code fence or in emphasis.
 
 ## Hard rules
-- Edit `cases/<id>.md` only. Do not touch the `## Source` table.
+- Edit `cases/<id>.md` only. Do not touch the `## Source` table. The exploration note under `.explore/notes/` is the
+  other file this run writes, and a locator never moves from there into the case.
+- Never put a cookie, a token, a header or a URL with a query string into a note (`references/notes.md`).
 - A `## Rules` bullet is a person's instruction: never delete it or change what it says, and never treat it as
   permission to write data, send email or do a person's step (`R1`–`R4`, `references/case-rules.md`).
 - The agent never writes data (see above). Never add `--allow-writes`, never set `ASRUN_ALLOW_WRITES`.

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/readiness.md

@@ -63,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

@@ -23,6 +23,37 @@ 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:
@@ -115,3 +146,6 @@ the card what the screenshot shows.
    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,

package/.claude/skills/generating-specs/SKILL.md

@@ -9,8 +9,10 @@ Read `references/conventions.md` first. It defines the spec shape, fixtures, ass
 the read-only rules. Read the workspace `AGENTS.md` for the hard rules and the project rules. Read `../exploring-cases/references/open-questions.md`: it
 defines how open questions are written into the case file, resolved and reported. Also read
 `../exploring-cases/references/case-rules.md` (how a case's `## Rules` are read, applied and maintained),
-`../exploring-cases/references/assertion-targets.md` (the exact thing each check looks at) and
-`../exploring-cases/references/readiness.md` (wait for the content, verify downloads in five parts). All four are binding here.
+`../exploring-cases/references/assertion-targets.md` (the exact thing each check looks at),
+`../exploring-cases/references/readiness.md` (wait for the content, verify downloads in five parts),
+`../exploring-cases/references/notes.md` (the local exploration note this run reads first) and
+`../exploring-cases/references/tools.md` (the browser tools this MCP can run). All six are binding here.
 
 This skill never stops to ask the user in the chat, because it may run without anybody present (a one-shot
 `claude -p` / `opencode run`). This holds whatever mode or agent the run is in: plan mode changes what you may write,
@@ -116,42 +118,42 @@ Decide this first, before exploring anything. The spec path is `tests/<id>.spec.
      never for what the check asserts about it: that goes to `test.fixme` with the reason, or `needs-input`.
    - Do not invent expected values. If the case's `## Values` and the spec disagree, the case wins: fix the spec and
      mention the change in the report.
-3. **Check sessions** if `login: required`: run `pnpm status --env <env>`. If a profile needs login, tell the
-   user to run `pnpm signin <profile-id>` and continue with the profiles that are ready. A profile the case holds
-   information for is never dropped because it is not logged in: write its part from the case and mark it
-   `not verified on the page` in the report. If `pnpm status` cannot run (a sandbox error such as `listen EPERM` or a
-   Chromium start failure), judge by the page instead: a page that lands on the login page means the profile is not
-   logged in.
-4. **Replay the case on the real page** with the `playwright-test` MCP. Read `../exploring-cases/references/tools.md`
-   first: that MCP lists tools it cannot run, and a call that answers `Tool "<name>" not found` means exactly that (the
-   server is up; use the substitute). If its tools are not registered in this session at all (no `browser_*` /
-   `generator_*` tool) or it reports that it failed to start, do not fall back to ad-hoc Playwright scripts: stop, tell
-   the user which MCP server is missing and to run `pnpm asrun doctor`, write no spec, and end with
-   `RESULT: needs-input`.
-   Call `generator_setup_page` with
-   `project=<profile-id>` (for example `example-staging`), `seedFile=tests/seed.spec.ts` and `plan=""`, then perform the
-   steps in the environment you were given (never ask for it; there is no default) to learn the locators.
+3. **Check sessions** if `login: required`: follow `../exploring-cases/references/tools.md`, "Starting a session". A
+   profile that needs login is named with `pnpm signin <profile-id>`, and the run continues with the profiles that are
+   ready. A profile the case holds information for is never dropped because it is not logged in: write its part from
+   the case and mark it `not verified on the page` in the report.
+4. **Replay the case on the real page** with the `playwright-test` MCP, following
+   `../exploring-cases/references/tools.md` ("Starting a session", "Short calls") and `readiness.md` ("Exploring"). If
+   its tools are not registered in this session at all (no `browser_*` / `generator_*` tool) or it reports that it
+   failed to start, do not fall back to ad-hoc Playwright scripts: stop, tell the user which MCP server is missing and
+   to run `pnpm asrun doctor`, write no spec, and end with `RESULT: needs-input`.
+   **Read each profile's exploration note first** (`../exploring-cases/references/notes.md`): run
+   `pnpm asrun explore:notes <case-id> --json`. A fresh note (its `caseSha256` matches the case) supplies the locator,
+   the request pattern and the target's match count for a step; confirm each on the page instead of rediscovering it,
+   and skip what it does not hold. A missing or stale note means the plain replay below. After confirming an entry of
+   a fresh note, you may write the verified locator or request back into that file (`updatedAt` gets the time); never
+   add a step or a target, and never touch a stale note. Say in the report what came from a note and what was
+   refreshed. Perform the steps in the environment you were given (never ask for it; there is no default).
    Do the read-only steps as written, and follow the `## Rules` that say how to prepare, wait or which control to
    avoid. **Never perform a step that writes or needs a choice**: the agent does not write
    data, in staging or in production, and it does not hand off to a person here or wait for one. A rule never
    authorizes one of those steps. Write those steps
    of the spec from the `- Recipe:` lines under the step (positions, `[asrun]` names, control labels and roles that
    `/explore-case` recorded). Pages that only exist after such a step cannot be seen from here: write their locators
-   from what the recipe and the exploration notes say, mark them in the report as "not verified on the page", and
-   leave the first run of the spec (or `/heal-spec`) to confirm them. Do this for at least one logged-in profile
-   per domain (example.com and exampleshop.com differ in markup). A profile the case holds information for that is
-   not logged in is skipped and named in the report; its part is written from the case and marked `not verified` in
-   the assertion table. Use this exploration to answer the open points of step 2, and read each profile's value from
-   the case's `## Values`: open that profile's page only when a value or a behavior still has to be resolved for it.
-   Keep every browser call short (one action, about 60 s at most, a snapshot between steps, `{timeout: 5000}` when
-   something may not appear, no third retry): see "Keep every browser call short" in `../exploring-cases/SKILL.md`.
-   **Ready before you read, here too** (`readiness.md`): take a marker on `browser_network_requests`
-   (`static: false`), act, wait for the key requests above that mark and the content signal, then snapshot. The request
-   URL patterns for `actAndWait` and the `Ready when` signals of the case are taken from what you see here.
-   **Check every target on the page:** for each target card, find its `Identified by` locator, confirm that it matches
-   exactly one element and that this element is what `What` says (outline it with `locator.highlight()` and look at the
-   screenshot, see `tools.md`). A locator that matches several elements or the wrong one is fixed or becomes a
-   question, never `.first()`.
+   from a fresh note first, then from the recipe, and mark them in the report as "observed by explore on <profile>" or
+   "not verified on the page"; leave the first run of the spec (or `/heal-spec`) to confirm the latter. Do this for at
+   least one logged-in profile per domain (example.com and exampleshop.com differ in markup). A profile the case holds
+   information for that is not logged in is skipped and named in the report; its part is written from the case and
+   marked `not verified` in the assertion table. Use this exploration to answer the open points of step 2, and read each
+   profile's value from the case's `## Values`: open that profile's page only when a value or a behavior still has to be
+   resolved for it.
+   **Ready before you read, here too**: follow `readiness.md`. The request URL patterns for `actAndWait` come from a
+   fresh note or from `browser_network_requests` during this replay, never from a guess; the `Ready when` signal comes
+   from the case.
+   **Check every target on the page:** follow `../exploring-cases/references/assertion-targets.md`, "What the spec does
+   with a card (generating)". Confirm that the card's `Identified by` matches exactly one element and that this element
+   is what `What` says (outline it with `locator.highlight()` and look at the screenshot, see `tools.md`). A locator that
+   matches several elements or the wrong one is fixed or becomes a question, never `.first()`.
    Prefer `getByTestId` (the project uses `data-tn`), then role/label locators. No CSS chains or XPath.
    Update the case file with what you learned: fold observations into the right section, marked `(seen on <profile>)`
    or, for a literal the spec asserts, `(observed on <profile>, 🔍 to be confirmed: <what to decide>)`; remove the
@@ -179,7 +181,8 @@ Decide this first, before exploring anything. The spec path is `tests/<id>.spec.
    never decided by one `isVisible()` look (its `timeout` option is ignored): use `clickOptionalUntilHidden`
    (`@asrunjs/asrun/ready`) or a waiting `expect(...).toBeVisible({timeout})`; see `readiness.md`, "Optional confirmations".
 7. **Check the files**: run `pnpm typecheck`, `pnpm spec:lint <id>` and `pnpm case:check` (or `node --import tsx <framework>/scripts/check-cases.ts` if
-   it fails with a sandbox error such as `listen EPERM`). Fix every error, including every `FAIL` of the spec lint (a lint failure is never silenced: fix the spec or turn the check
+   it fails with a sandbox error such as `listen EPERM`). When you wrote an exploration note back, also run
+   `pnpm asrun explore:notes <id> --check --profile <profile-id>` for each profile you refreshed. Fix every error, including every `FAIL` of the spec lint (a lint failure is never silenced: fix the spec or turn the check
    into a question). Every lint `WARN` is handled too: fix it, or name it in the report with the reason it is acceptable.
    Then do the **self-review**: for each assertion answer in writing "if the product were broken, would this fail?"
    and "if the product is right, could this fail by timing?" (a check that cannot fail, or that races the page, is rewritten).
@@ -188,7 +191,8 @@ Decide this first, before exploring anything. The spec path is `tests/<id>.spec.
    Do NOT run `pnpm asrun`, do not use
    `--update-snapshots` and do not create baselines: the first run of the spec does that, and a person reviews them.
 8. **Report** in the user's language: spec path, **an assertion table** (step, what is asserted, target card, ready signal, and
-   `observed on the page` or `not verified`; no row may be missing), profiles explored, profiles skipped (and why),
+   `observed on the page` or `not verified`; no row may be missing), profiles explored, which steps were written from a
+   fresh exploration note and which notes were refreshed (or that there were none), profiles skipped (and why),
    the profiles of `profiles.yaml` the case holds no information for (they run on `default` alone), whether the case file was
    translated, what was added to the case file as `(seen on <profile>)` and which lines still need a person
    (`🔍 to be confirmed`, with the reason), checks generated from observations, visual checks that need a baseline on
@@ -250,12 +254,15 @@ Heal from evidence, not from a habit of rerunning. A report that already exists
    leaves out the profiles that are not logged in instead of failing them. A profile that is not logged in is never healed:
    name it in the report with `pnpm signin <profile-id>`.
 4. **Look at the pages when the change depends on them.** Reading a page is not a run and is always allowed, also for an
-   improvement request with no failure behind it. Use the `playwright-test` MCP exactly as `/gen-spec` step 4 describes
-   (`generator_setup_page` with `project=<profile-id>`, one action per call, ready before you read). Do the read-only
+   improvement request with no failure behind it. Use the `playwright-test` MCP exactly as `/gen-spec` step 4 describes,
+   following `../exploring-cases/references/tools.md` ("Starting a session", "Short calls"), `readiness.md` and the
+   exploration note (`../exploring-cases/references/notes.md`). Do the read-only
    steps only: **never perform a step that writes or needs a choice**, in any environment. What you see goes into the
    case by the gate in `open-questions.md` ("Which sentences carry a marker"): `(seen on <profile>)` for a locator, a
    flow or a request, and `(observed on <profile>, 🔍 to be confirmed: <what a person must decide>)` only for a
-   literal the spec asserts, so the person settles that in the review gate below.
+   literal the spec asserts, so the person settles that in the review gate below. If the note was stale, edit the case
+   as usual; if it was fresh, a verified locator may be written back
+   (`../exploring-cases/references/notes.md`).
 5. **Audit the assertion before you blame anyone.** Read the `assertion-targets.md` and `readiness.md` sections on healing.
    - Is the locator still what the target card says (`What`, `Identified by`)? Open the failure screenshot and the
      baseline (`pnpm baselines:review <case-id>`) and look at each: a baseline that shows something other than the card

package/AGENTS.md

@@ -184,15 +184,16 @@ Three steps, each learns one thing: the intent, the facts and inputs, the implem
 1. `making-cases` (or `/make-case <notes>`) turns raw notes into case documents. It writes `cases/*.md` only and
    never opens a browser. Check them with `pnpm case:check`.
 2. `exploring-cases` (or `/explore-case <case-id> <env> [--attended] [--profiles a,b]`) explores the real pages for one
-   case. It edits that case file only: wording, observations, TODO blocks, and, with `--attended`, the `- Recipe:` lines
-   of the steps that write or need a choice. `--profiles` narrows the run to those profiles; runs add up, so the case
-   can be explored in passes.
-3. `generating-specs` (or `/gen-spec <case-id> <env>`) turns the case into a spec. It replays the case and its
-   step recipes and `## Values`, writes the spec (values stay in the case document), but never runs the tests, never
-   writes data and never creates baselines. There is no profile selection here: it covers every profile the case names,
-   which is why a case explored in passes generates one spec for all of them. A tagged step with no `- Recipe:` line
-   (an old `## Inputs` line counts until it is moved) stops with `needs-input`: run `/explore-case` first. Running specs
-   is a separate step (`pnpm asrun`, or the Run page).
+   case. It edits that case file: wording, observations, TODO blocks, and, with `--attended`, the `- Recipe:` lines
+   of the steps that write or need a choice, and it writes a local note under `.explore/notes/` with the locators and
+   data-call paths it saw. `--profiles` narrows the run to those profiles; runs add up, so the case can be explored in
+   passes.
+3. `generating-specs` (or `/gen-spec <case-id> <env>`) turns the case into a spec. It replays the case, its
+   step recipes and the exploration note, and `## Values`, writes the spec (values stay in the case document), but never
+   runs the tests, never writes data and never creates baselines. There is no profile selection here: it covers every
+   profile the case names, which is why a case explored in passes generates one spec for all of them. A tagged step with
+   no `- Recipe:` line (an old `## Inputs` line counts until it is moved) stops with `needs-input`: run
+   `/explore-case` first. Running specs is a separate step (`pnpm asrun`, or the Run page).
 Workspace maintenance is separate from the AI steps: `pnpm asrun upgrade` installs the newest framework, refreshes the
 generated files and applies the release's workspace migrations (it checks the target release for breaking changes
 before installing), `pnpm asrun init [--update] [--force]` writes or refreshes the workspace files, `pnpm asrun

package/README.md

@@ -99,11 +99,12 @@ exempts `@asrunjs/asrun` from pnpm's 24-hour release age, so a fresh release ins
 3. **Write a case.** `pnpm case:new header-logo` creates `cases/header-logo.md` from the template; or start from raw
    notes with `/make-case notes.md`. Fill in the steps, what is expected and the exact values.
 4. **Check it against the real pages.** `/explore-case header-logo staging` opens the pages (with your saved session),
-   writes what they show into the case and turns what it cannot know into questions. Answer them in the case file, or
-   in the UI's **Answer** sheet, and run it again. With many profiles, `--profiles a,b` opens only those; a later run
-   with the others adds theirs, and the case keeps both.
-5. **Generate, run, read.** `/gen-spec header-logo staging` writes `tests/header-logo.spec.ts` and fills the case's
-   `## Values`. Then:
+   writes what they show into the case and turns what it cannot know into questions. It also saves a local note of the
+   locators and data calls it saw. Answer the questions in the case file, or in the UI's **Answer** sheet, and run it
+   again. With many profiles, `--profiles a,b` opens only those; a later run with the others adds theirs, and the case
+   keeps both.
+5. **Generate, run, read.** `/gen-spec header-logo staging` reads those notes, writes `tests/header-logo.spec.ts` and
+   fills the case's `## Values`. Then:
 
    ```bash
    pnpm asrun --env staging --grep header-logo

package/bin/asrun.mjs

@@ -23,6 +23,7 @@ const SCRIPTS = {
   status: 'status.js',
   report: 'report.js',
   explore: 'explore.js',
+  'explore:notes': 'explore-notes.js',
   cleanup: 'cleanup.js',
   'case:new': 'new-case.js',
   'case:check': 'check-cases.js',

package/dist/lib/explore-notes.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The local exploration note: what `/explore-case` saw on the page, in a form `/gen-spec` can read.
+ *
+ * It lives under `.explore/notes/<case-id>/<profile-id>.json`, one file per profile, so a run with `--profiles` never
+ * has to merge with an earlier one. `.explore/` is git-ignored local state: a note is optional, may be deleted at any
+ * time, and a fresh checkout simply has none (generation then replays the case as before).
+ *
+ * A note holds only what the case does not: locators the agent confirmed on the page, the data-call paths of the
+ * actions that load something, and the match count of a target card's element. Expected values stay in the case's
+ * `## Values`, ready signals in the case's `Ready when:` lines, and assertions nowhere near this file.
+ */
+export declare const NOTES_VERSION = 1;
+export interface ExploreLocator {
+    /** What the locator is for, in words ("the header navigation link"). */
+    purpose: string;
+    /** A Playwright locator as `browser_generate_locator` returned it, for example `page.getByRole('link', {name: 'Home'})`. */
+    locator: string;
+}
+export interface ExploreNoteStep {
+    /** The path the step runs on, relative to `baseURL` (for example `/documents/`). */
+    url?: string;
+    locators?: ExploreLocator[];
+    /** Data-call paths the step's action starts, path only (`/api/articles`). */
+    requests?: string[];
+}
+export interface ExploreNoteTarget {
+    locator: string;
+    /** How many elements the locator matched when it was confirmed (1 for a target that is not a question). */
+    matches?: number;
+}
+export interface ExploreNote {
+    version: typeof NOTES_VERSION;
+    caseId: string;
+    profile: string;
+    env?: string;
+    /** sha256 of `cases/<case-id>.md` when the note was written; a different one makes the note stale. */
+    caseSha256: string;
+    capturedAt: string;
+    /** Set when a later `/gen-spec` refreshed an entry it confirmed on the page. */
+    updatedAt?: string;
+    steps: Record<string, ExploreNoteStep>;
+    targets?: Record<string, ExploreNoteTarget>;
+}
+export interface ExploreNoteError {
+    file: string;
+    problems: string[];
+}
+/** The folder that holds one case's notes; `<case-id>` may contain its group folder (`documents/landing-page`). */
+export declare function exploreNotesDir(caseId: string): string;
+/** The note of one profile: `.explore/notes/<case-id>/<profile-id>.json`. */
+export declare function exploreNotesFile(caseId: string, profileId: string): string;
+/** sha256 of the case document, or null when it does not exist. */
+export declare function caseSha256(caseId: string): string | null;
+export type NoteFreshness = 'fresh' | 'stale' | 'no-case';
+/**
+ * Whether a note still describes the case. A stale note is not an error: `/gen-spec` replays the case and ignores it.
+ */
+export declare function noteFreshness(note: ExploreNote): {
+    state: NoteFreshness;
+    reason?: string;
+};
+/** Every reason the note is not usable, in plain words. An empty list means it is valid. */
+export declare function validateExploreNote(value: unknown, expected: {
+    caseId: string;
+    profile: string;
+}): string[];
+/**
+ * Reads every note of a case (or one profile's), parses and validates it. A malformed file is reported, never thrown:
+ * the caller decides whether it matters, and generation treats an unreadable note as a missing one.
+ */
+export declare function readExploreNotes(caseId: string, profileId?: string): {
+    notes: ExploreNote[];
+    errors: ExploreNoteError[];
+};