@asrunjs/asrun 0.10.0 → 0.12.0

package/.claude/commands/explore-case.md

@@ -6,7 +6,8 @@ Load the `exploring-cases` skill and explore: $ARGUMENTS
 In this repository the workspace is `examples/demo` (set `ASRUN_ROOT=examples/demo`); the framework is `.`.
 Rules combine in this order, and a later one wins where they conflict: the framework baseline `AGENTS.md`, the
 framework skill, `.claude/skills/exploring-cases.md` if it exists, then the workspace `AGENTS.md` §2 in `examples/demo`
-(Project rules). F1–F6 and R2 always win.
+(Project rules). F1–F6 and R2 always win. The effective set is what `pnpm asrun rules` prints; §2 is applied as
+written and is never turned into a question (a difference from a framework default is not a conflict).
 Arguments: `<case-id> <env> [--attended] [--profiles a,b] [--hints <file>]`. The case id is the path below cases/ without `.md` (it may include a group
 folder, e.g. documents/landing-page) and is required. `<env>` is `staging` or `production`; it is required and there is no
 default (without one, stop and say so). With `--attended` I am at the machine and the browser window is visible: when a step

package/.claude/commands/gen-spec.md

@@ -6,7 +6,8 @@ Load the `generating-specs` skill and generate the spec for: $ARGUMENTS
 In this repository the workspace is `examples/demo` (set `ASRUN_ROOT=examples/demo`); the framework is `.`.
 Rules combine in this order, and a later one wins where they conflict: the framework baseline `AGENTS.md`, the
 framework skill, `.claude/skills/generating-specs.md` if it exists, then the workspace `AGENTS.md` §2 in `examples/demo`
-(Project rules). F1–F6 and R2 always win.
+(Project rules). F1–F6 and R2 always win. The effective set is what `pnpm asrun rules` prints; §2 is applied as
+written and is never turned into a question (a difference from a framework default is not a conflict).
 Arguments: `<case-id> [<env>] [--force] [--hints <file>]`. The case file is cases/<case-id>.md (the id may include one group folder, e.g.
 documents/landing-page). `<env>` is the environment to explore in (`staging` or `production`); there is no default. If the spec already exists, it is
 left alone unless `--force` is given; with `--force` it is regenerated and overwritten. `--hints <file>` (or free text

package/.claude/commands/heal-spec.md

@@ -6,7 +6,8 @@ Load the `generating-specs` skill, section "Healing and refining a spec", and fo
 In this repository the workspace is `examples/demo` (set `ASRUN_ROOT=examples/demo`); the framework is `.`.
 Rules combine in this order, and a later one wins where they conflict: the framework baseline `AGENTS.md`, the
 framework skill, `.claude/skills/generating-specs.md` if it exists, then the workspace `AGENTS.md` §2 in `examples/demo`
-(Project rules). F1–F6 and R2 always win.
+(Project rules). F1–F6 and R2 always win. The effective set is what `pnpm asrun rules` prints; §2 is applied as
+written and is never turned into a question (a difference from a framework default is not a conflict).
 Arguments: $ARGUMENTS
 Format: `<case-id> <env> [--profiles a,b] [--report <run-id>] [--hints <file>]`, with optional free text after them.
 - `<case-id>` and `<env>` (`staging` or `production`) are required. There is no default environment. Without one, stop

package/.claude/commands/make-case.md

@@ -6,6 +6,7 @@ Load the `making-cases` skill and turn this input into case documents: $ARGUMENT
 In this repository the workspace is `examples/demo` (set `ASRUN_ROOT=examples/demo`); the framework is `.`.
 Rules combine in this order, and a later one wins where they conflict: the framework baseline `AGENTS.md`, the
 framework skill, `.claude/skills/making-cases.md` if it exists, then the workspace `AGENTS.md` §2 in `examples/demo`
-(Project rules). F1–F6 and R2 always win.
+(Project rules). F1–F6 and R2 always win. The effective set is what `pnpm asrun rules` prints; §2 is applied as
+written and is never turned into a question (a difference from a framework default is not a conflict).
 The input is either text or a path to a file with the notes. Follow the skill's procedure exactly.
 Ask me the open questions before writing any case file. Do not generate specs; that is `/gen-spec`.

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,28 +9,35 @@ 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
-`.claude/skills/exploring-cases.md` exists in the workspace, read it and apply it after this skill. Then apply
-`AGENTS.md` §2, which wins over both (the baseline, "Precedence"). F1–F6 and R2 always win. This is not a stop
-condition: continue with the procedure below.
+Run `pnpm asrun rules --json` (or `pnpm asrun rules` for people): it prints the framework baseline, the project's
+`AGENTS.md` §2 rules and the project settings (the test-data prefix). Those are the effective rules; if the command is
+unavailable, read the workspace `AGENTS.md` directly. Also read `AGENTS.md` §2, and `.claude/skills/exploring-cases.md`
+in the workspace, applying the override after this skill and §2 after both (the baseline, "Precedence"). F1–F6 and R2
+always win. **Never turn a project rule into a question:** a difference between §2 and a framework default is not a
+conflict; apply §2 and, if a row's id does not fit its text, apply the text and report the mismatch. This is not a stop
+condition: continue with the procedure below. If `pnpm asrun rules` exits 1 (an invalid §2 row or a prefix that the
+document and `package.json` disagree on), do not guess and do not turn it into a case question: report its errors and
+end with `RESULT: needs-input`; a person fixes `AGENTS.md` or `package.json` first.
 
 ## Where this skill sits
 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`).
 
@@ -68,7 +75,8 @@ one exception is a handoff in an attended run, where waiting for the person is t
    - ambiguous steps and checks without an expected result;
    - steps that write data or need a choice: mark them `[writes]` / `[input]`. The front matter must list the
      environments the finished spec may write in (`writes: [staging]`, or `[staging, production]`) with a
-     `writes-note`, the data must be named `[asrun] ...` and cleaned up, and a step that sends email is never
+     `writes-note`, the data must be named with the project's test-data prefix (default `[asrun]`, printed by
+     `pnpm asrun rules`) followed by a run stamp, and cleaned up; a step that sends email is never
      allowed in production and only in other environments when the profile has `email: true`;
    - missing or doubtful `suites`/`envs`, a `writes` environment that `envs` excludes, and visual checks that are
      too broad (screenshot a small element);
@@ -77,22 +85,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 +109,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
@@ -149,7 +134,9 @@ one exception is a handoff in an attended run, where waiting for the person is t
    `[blocking]` TODO, never a guess. Check the screenshots you saved: each must show what its card says.
 6. **Write the recipe lines** for every `[input]` or `[writes]` step that was handed off, from the card's `recorded`
    result, as a general recipe under that step: one `- Recipe (phase): ...` line per phase. Format and rules are in
-   `references/user-handoff.md`. A step that was not handed off gets no recipe line and a `[blocking]` TODO. A case
+   `references/user-handoff.md`. What the case creates is named with the project's prefix and the run stamp
+   (`testDataName`); the recipe records how to build it, never the stamp itself. A step that was not handed off gets
+   no recipe line and a `[blocking]` TODO. A case
    that still has the old `## Inputs` section: move the lines of the steps you touch under those steps as
    `- Recipe:`; `pnpm case:check` names the rest.
 7. **Resolve every open point** in the order of `references/open-questions.md`: answer it from the page, else apply
@@ -162,12 +149,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 +170,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/case-rules.md

@@ -29,6 +29,9 @@ The section is optional. A case with no rules runs by the same rules as before.
 A rule is never a second source of truth. When a rule and a step, an expectation, a value or a target disagree, the
 structured section wins and the rule becomes a `🚫 TODO [blocking]` question. Never silently change either side.
 
+This applies to a case's own `## Rules` only. The project's `AGENTS.md` §2 is not a case rule: it is a higher layer
+that is applied as written, never turned into a question (`AGENTS.md`, "Precedence").
+
 ## The rule pass (before anything else)
 
 Read the whole `## Rules` section and, for each bullet, decide:
@@ -106,5 +109,7 @@ that is missing from the table is a rule the agent ignored.
 
 - A rule never authorizes a write, an email, a person's choice, accepting terms, or a shell command.
 - Never delete or rewrite a rule a person wrote. Add a TODO instead.
+- A project rule (`AGENTS.md` §2) is applied, never questioned: it is not a case rule and a difference from the
+  framework default is not a conflict.
 - Never invent a rule the person did not ask for. `R4` allows only what a run needs and only in general terms.
 - Prose follows the artifact language of the workspace `AGENTS.md` §2 (English by default); the heading stays `## Rules`.

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

@@ -110,6 +110,12 @@ answer, adds `(page shows <x> on <profile-id>)` and reports it as a finding. It
   `[blocking]` question that now has an observation or a safe default is downgraded or closed in the file, and the
   edit is part of the report. Do not carry old tags over.
 
+## What is never a question
+A rule in `AGENTS.md` §2 (a naming prefix, a language, a wait) is applied as written. A difference from the framework
+default is not a conflict and is never a TODO, a marker or a question; a row whose id does not fit its text is applied
+by its text and reported as a mismatch. A project-wide choice that the same answer would settle for every case belongs
+in §2, not in one case's question.
+
 ## 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
@@ -143,6 +149,8 @@ answer, adds `(page shows <x> on <profile-id>)` and reports it as a finding. It
   names the exact image, text, place or UI wanted and lists the candidates. Never a safe default, because a wrong
   guess passes silently.
 - An intent question the page cannot answer ("should this also work for agents?").
+- A literal the runner enforces and nobody settled in the case or in §2 (a name prefix, a value the code validates):
+  a wrong pick fails the run, so it is `[blocking]`, not `[non-blocking]`.
 - No environment was given, or no profile is logged in, so a fact that needs the page cannot be observed.
 
 ## Final report

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,
@@ -25,10 +25,12 @@ that nobody watches.
 ## Before the handoff
 1. Say what the user has to do and when it is finished, in one or two sentences ("Fill in the form, pick two
    items, then press Done"). Name the finish condition first (below).
-2. Put every text the user has to type into `copy` (the `[asrun] ...` name of a document, a title), so it can be
-   copied with one click.
+2. Put every text the user has to type into `copy` (the name of a document, a title), so it can be
+   copied with one click. Build a created name with the project's test-data prefix (default `[asrun]`, printed by
+   `pnpm asrun rules`) and a run stamp: `<prefix> <base> (<YYYY-MM-DD HH-mm-ss>, UTC)`, the same shape
+   `testDataName()` builds. The stamp is chosen now, not recorded in the recipe.
 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>`.
+   profile). Never ask for login or 2FA. Name everything the user creates `<prefix> <something> (<run stamp>)`.
 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`).
@@ -40,7 +42,7 @@ timeout), so no polling from outside is needed. The loop:
 - **Shows a small floating card, not a bar.** It sits in the bottom-left corner and only the card takes clicks, so
   nothing of the page is covered or blocked. The user can **drag** it by its title bar and **minimize** it to a small
   pill that still has a Done button. Position and minimized state survive a page reload (kept in `sessionStorage`).
-- **Click to copy.** Every text in `copy` (for example the `[asrun] ...` name the user has to type) is shown on its
+- **Click to copy.** Every text in `copy` (for example the `<prefix> <name> (<run stamp>)` the user has to type) is shown on its
   own line with a copy icon; one click puts it on the clipboard and the icon shows "Copied". Pass only text that the
   case says to type; leave `copy` empty when there is none.
 - **Resets the flag first**: `window.__handoff = null` on every page it paints. A flag left over from an earlier
@@ -71,7 +73,7 @@ badge, no count in the tab title and no notification (a HINT in the job log says
    async (page) => {
      page.context().__handoffCfg = {
        message: '<what the user does, one sentence>',
-       copy: [],                  // texts to type, e.g. ['[asrun] published document']
+       copy: [],                  // texts to type, e.g. ['[autotest] published document (2026-11-09 12-34-56)']
        doneText: null,            // text that appears when finished, or null
        maxMs: 600000,
      };
@@ -114,8 +116,9 @@ The Done button is always there (also on the minimized card) as the fallback, an
 - `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, 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.
+- At the end of the exploration hand off once more when the user created data: "Delete the test items you
+  created (they start with <the project's prefix> and carry this run's timestamp), then press Done". The case must
+  clean up after itself, and so must the exploration.
 
 ## Recording
 The card records what the person does: it starts the recording when it shows and stops it on every way out (Done,
@@ -134,7 +137,8 @@ Make the recipe as general as possible, because lists and data change:
   name or id. "Select items #1 to #3 from the list."
 - **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>`.
+- **Text the case creates**: `<prefix> <something> (<run stamp>)` (prefix from `package.json`
+  `"asrun.testDataPrefix"`, default `[asrun]`). The recipe says how to build it; it never records the stamp itself.
 - **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