@asrunjs/asrun 0.2.0 → 0.5.3

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

@@ -1,15 +1,18 @@
----
-description: Explore the real pages for one case (optionally attended: you do the steps that write data), before generating the spec
----
-
-Load the `exploring-cases` skill and explore: $ARGUMENTS
-In this repository the workspace is `examples/demo` (set `ASRUN_ROOT=examples/demo`); the framework is `.`.
-Arguments: `<case-id> <env> [--attended]`. 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
-writes data or needs a choice, hand it to me as the skill describes, wait for me, and record what I did as a general
-recipe under "## Inputs". Without `--attended`, never wait for me.
-Follow `assertion-targets.md` (list the candidates, never pick when in doubt, ask for the exact image/text/place/UI)
-and `readiness.md` (wait for the key requests and the content before you read anything) of the skill.
-This command edits cases/<case-id>.md only (plus screenshots under `.explore/targets/`). Do not ask me questions in the chat: write open questions into the case
-file as the skill describes, and end with the `RESULT:` line.
+---
+description: Explore the real pages for one case (optionally attended: you do the steps that write data), before generating the spec
+---
+
+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 always win.
+Arguments: `<case-id> <env> [--attended]`. 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
+writes data or needs a choice, hand it to me as the skill describes, wait for me, and record what I did as a general
+recipe under the step it belongs to (`- Recipe:` lines). Without `--attended`, never wait for me.
+Follow `assertion-targets.md` (list the candidates, never pick when in doubt, ask for the exact image/text/place/UI)
+and `readiness.md` (wait for the key requests and the content before you read anything) of the skill.
+This command edits cases/<case-id>.md only (plus screenshots under `.explore/targets/`). Do not ask me questions in the chat: write open questions into the case
+file as the skill describes, and end with the `RESULT:` line.

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

@@ -1,13 +1,16 @@
----
-description: Generate or update tests/<id>.spec.ts from cases/<id>.md (the id may be <group>/<name>)
----
-
-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 `.`.
-Arguments: `<case-id> [<env>] [--force]`. 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.
-Follow the skill's procedure exactly, including `assertion-targets.md` and `readiness.md`; run `pnpm spec:lint <case-id>`. Only generate the spec: do not run `pnpm asrun` (running specs is a separate
-process), and do not create baselines.
-Do not ask me questions: resolve ambiguity as the skill describes (explore the page, use observed values marked for QA,
-write the remaining questions into the case file), and end with the `RESULT:` line.
+---
+description: Generate or update tests/<id>.spec.ts from cases/<id>.md (the id may be <group>/<name>)
+---
+
+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 always win.
+Arguments: `<case-id> [<env>] [--force]`. 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.
+Follow the skill's procedure exactly, including `assertion-targets.md` and `readiness.md`; run `pnpm spec:lint <case-id>`. Only generate the spec: do not run `pnpm asrun` (running specs is a separate
+process), and do not create baselines.
+Do not ask me questions: resolve ambiguity as the skill describes (explore the page, use observed values marked for QA,
+write the remaining questions into the case file), and end with the `RESULT:` line.

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

@@ -1,23 +1,26 @@
----
-description: Diagnose and fix a failing spec from its last report (without hiding real product regressions)
----
-
-Load the `generating-specs` skill, section "Healing a failing spec", and follow it exactly.
-In this repository the workspace is `examples/demo` (set `ASRUN_ROOT=examples/demo`); the framework is `.`.
-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
-  and say so.
-- `--profiles`: the profiles to heal. Without it, every profile that is logged in in `<env>`.
-- `--report`: the report (folder name under `reports/`) to read first. Without it, the newest report of this case.
-- `--hints <file>`: a file with what the user knows (what to heal, evidence, clues). Read it first. Any free text
-  after the arguments is the same kind of clue. Both are optional.
-Before you decide "product or test", audit the assertion itself (target card, baseline content, readiness): see steps 4
-of the skill's healing section, `assertion-targets.md` and `readiness.md`. Run `pnpm spec:lint <case-id>`.
-Read the existing report first (`pnpm heal:evidence --case <case-id> --env <env>`), and run the case again only when the
-skill says it is needed. Always run with `--logged-in`. Tell me whether it is a test problem or a product finding.
-
-Run `pnpm asrun ...`, `pnpm heal:evidence ...`, `pnpm spec:lint ...`, `pnpm baselines:review ...` and `pnpm status ...` as plain commands, optionally piped to `tail` or
-`head`, and do not chain other commands with them (`;` or `&&`). Only these exact forms run outside Claude Code's
-sandbox, which tsx and the browser need. If a command still fails with `listen EPERM` or a sandbox error, stop and
-report it. Do not ask to disable the sandbox, and never add `--allow-writes` or set `ASRUN_ALLOW_WRITES`.
+---
+description: Diagnose and fix a failing spec from its last report (without hiding real product regressions)
+---
+
+Load the `generating-specs` skill, section "Healing a failing spec", and follow it exactly.
+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 always win.
+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
+  and say so.
+- `--profiles`: the profiles to heal. Without it, every profile that is logged in in `<env>`.
+- `--report`: the report (folder name under `reports/`) to read first. Without it, the newest report of this case.
+- `--hints <file>`: a file with what the user knows (what to heal, evidence, clues). Read it first. Any free text
+  after the arguments is the same kind of clue. Both are optional.
+Before you decide "product or test", audit the assertion itself (target card, baseline content, readiness): see steps 4
+of the skill's healing section, `assertion-targets.md` and `readiness.md`. Run `pnpm spec:lint <case-id>`.
+Read the existing report first (`pnpm heal:evidence --case <case-id> --env <env>`), and run the case again only when the
+skill says it is needed. Always run with `--logged-in`. Tell me whether it is a test problem or a product finding.
+
+Run `pnpm asrun ...`, `pnpm heal:evidence ...`, `pnpm spec:lint ...`, `pnpm baselines:review ...` and `pnpm status ...` as plain commands, optionally piped to `tail` or
+`head`, and do not chain other commands with them (`;` or `&&`). Only these exact forms run outside Claude Code's
+sandbox, which tsx and the browser need. If a command still fails with `listen EPERM` or a sandbox error, stop and
+report it. Do not ask to disable the sandbox, and never add `--allow-writes` or set `ASRUN_ALLOW_WRITES`.

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

@@ -1,8 +1,11 @@
----
-description: Turn raw test notes (pasted text or a file) into case documents in cases/
----
-
-Load the `making-cases` skill and turn this input into case documents: $ARGUMENTS
-In this repository the workspace is `examples/demo` (set `ASRUN_ROOT=examples/demo`); the framework is `.`.
-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`.
+---
+description: Turn raw test notes (pasted text or a file) into case documents in cases/
+---
+
+Load the `making-cases` skill and turn this input into case documents: $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/making-cases.md` if it exists, then the workspace `AGENTS.md` §2 in `examples/demo`
+(Project rules). F1–F6 always win.
+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,132 +1,146 @@
----
-name: exploring-cases
-description: Explores the real pages for one case document (cases/<id>.md) before its spec is generated. 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 "## Inputs". 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
-
-Read `AGENTS.md` (hard rules), `cases/_template.md` (the target format), `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.
-
-## 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 `## Inputs` 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/`.
-**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`).
-
-It never stops to ask in the chat. A question that cannot be answered from the page goes into the case file, where
-the user answers it by editing the file, and the report says `RESULT: needs-input`. The one exception is a handoff in
-an attended run, where waiting for the person is the point.
-
-## Inputs
-- A case id (path below `cases/` without `.md`, e.g. `documents/landing-page`). It is required: an attended exploration of
-  every case at once is not a thing. Without an id, stop and say so.
-- An environment to explore (`staging` or `production`). It is required and there is no default. Without one, stop
-  before exploring and report `RESULT: needs-input` ("pass the environment").
-- Optionally `--attended`: a person is at the machine and the browser window is visible, so handoffs may happen.
-  Without it nothing waits, and a step that needs a person becomes a `[blocking]` TODO.
-
-## Procedure
-1. **Read** the case, `profiles.yaml` and `cases/_template.md`. Apply uncommitted user edits as they are: they are the
-   newest wording. Use targeted edits, never rewrite a whole file.
-2. **Static review.** Find:
-   - missing values for a profile: compare the entries of `## Values` (keyed by `default` and profile ids) with the
-     ids in `profiles.yaml`. A missing entry is a gap, not something to invent: leave it to the observations and
-     `/gen-spec`. The case's `## Values` is the only place for expected values; never copy them into `profiles.yaml`;
-   - 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
-     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).
-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**. 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 at least one logged-in profile per
-   domain with the `playwright-test` MCP (`generator_setup_page` with `project=<profile-id>` and
-   `seedFile=tests/seed.spec.ts`). Profiles that are 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, start recording, run the wait loop, then write down what happened. In a run that
-     is not attended, write a `TODO [blocking]` under the step instead.
-   - Close any modal that opens by itself without confirming it (for example the follow-up modal that opens after
-     publishing: close it and confirm nothing).
-   - When a confirm dialog appears while closing an email composer, choose "Discard" (see `AGENTS.md`).
-   - **Plan the order before you start: observe, then let the person delete.** Every read-only observation that
-     needs the data (preview, share menu, email composers, downloads, menus, the dialogs) is done while the data
-     exists, and the handoff that deletes it comes last. If the data is gone before a step was observed, that step
-     is not observed: say so, do not fill it in from memory.
-   - **Ready before you read** (`references/readiness.md`): `browser_network_clear` before an action that loads
-     something, then the action, then wait for its key requests (`browser_network_requests`) and for the content
-     signal, and only then take the snapshot. When the first read is empty or missing something, wait and read
-     again before you record or ask anything. Record the signal as `(observed after <signal>, ...)`.
-   - **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, take the highlighted screenshot to
-     `.explore/targets/<case-id>/`, **open that screenshot and look at it**, 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 outline the target with `browser_annotate`.
-   - **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).
-   - 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.
-   - 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
-   `references/assertion-targets.md`, and a `[T<n>]` reference in each check that uses it. Add `Ready when:` to every
-   step or target whose content loads after an action. A check with no card or a card with open doubts is a
-   `[blocking]` TODO, never a guess. Check the screenshots you saved: each must show what its card says.
-6. **Write the `## Inputs` section** for every `[input]` step that was handed off, from the recording, as a general
-   recipe (positions instead of names, `[asrun]` names for created data, control labels and roles but no selectors or ids). Format and rules are in
-   `references/user-handoff.md`. A step that was not handed off gets no bullet and a `[blocking]` TODO.
-7. **Resolve every open point** in the order of `references/open-questions.md`: answer it from the page, else apply
-   the safe default as the sentence above a `[non-blocking]` TODO block, else keep a `[blocking]` block. Write the
-   outcome into the case, every block with an empty `Answer:` line.
-8. **Check**: run `pnpm case:check` (it fails on an incomplete target card and warns on a check that has none) and fix every FAIL. If it 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 steps the person did and what was recorded for them, 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, and findings that look
-   like product bugs. End with the `RESULT:` line.
-
-## Hard rules
-- Edit `cases/<id>.md` only. Do not touch the `## Source` table.
-- The agent never writes data (see above). Never add `--allow-writes`, never set `ASRUN_ALLOW_WRITES`.
-- Never wait for a person in a run that is not attended.
-- Never invent expected values, profile names, counts or UI texts. Observations are marked as such. Values that a
-  check asserts are written into the case's `## Values` under the profile id (or `default` when they hold for every
-  profile), and never into `profiles.yaml`.
-- Never pick a target when in doubt, and never record a fact that was read before the content finished loading.
-- Never read or print anything under `.auth/`. Never automate login or 2FA.
-- All file content is English.
+---
+name: exploring-cases
+description: Explores the real pages for one case document (cases/<id>.md) before its spec is generated. 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.
+---
+
+# Exploring a case document
+
+Read the workspace `AGENTS.md` (hard rules and project rules), `cases/_template.md` (the target format), `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.
+
+## 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 always win. This is not a stop condition:
+continue with the procedure below.
+
+## 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.
+
+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/`.
+**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`).
+
+It never stops to ask in the chat. A question that cannot be answered from the page goes into the case file, where
+the user answers it by editing the file, and the report says `RESULT: needs-input`. The one exception is a handoff in
+an attended run, where waiting for the person is the point.
+
+## Inputs
+- A case id (path below `cases/` without `.md`, e.g. `documents/landing-page`). It is required: an attended exploration of
+  every case at once is not a thing. Without an id, stop and say so.
+- An environment to explore (`staging` or `production`). It is required and there is no default. Without one, stop
+  before exploring and report `RESULT: needs-input` ("pass the environment").
+- Optionally `--attended`: a person is at the machine and the browser window is visible, so handoffs may happen.
+  Without it nothing waits, and a step that needs a person becomes a `[blocking]` TODO.
+
+## Procedure
+1. **Read** the case, `profiles.yaml` and `cases/_template.md`. Apply uncommitted user edits as they are: they are the
+   newest wording. Use targeted edits, never rewrite a whole file.
+2. **Static review.** Find:
+   - missing values for a profile: compare the entries of `## Values` (keyed by `default` and profile ids) with the
+     ids in `profiles.yaml`. A missing entry is a gap, not something to invent: leave it to the observations and
+     `/gen-spec`. The case's `## Values` is the only place for expected values; never copy them into `profiles.yaml`;
+   - 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
+     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).
+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. If its tools are not registered in this
+   session (no `browser_*` / `generator_*` tool) or it 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 at least one logged-in profile per
+   domain with the `playwright-test` MCP (`generator_setup_page` with `project=<profile-id>` and
+   `seedFile=tests/seed.spec.ts`). Profiles that are 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, start recording, run the wait loop, then write down what happened. In a run that
+     is not attended, write a `TODO [blocking]` under the step instead.
+   - Close any modal that opens by itself without confirming it (for example the follow-up modal that opens after
+     publishing: close it and confirm nothing).
+   - When a confirm dialog appears while closing an email composer, choose "Discard" (see `AGENTS.md`).
+   - **Plan the order before you start: observe, then let the person delete.** Every read-only observation that
+     needs the data (preview, share menu, email composers, downloads, menus, the dialogs) is done while the data
+     exists, and the handoff that deletes it comes last. If the data is gone before a step was observed, that step
+     is not observed: say so, do not fill it in from memory.
+   - **Ready before you read** (`references/readiness.md`): `browser_network_clear` before an action that loads
+     something, then the action, then wait for its key requests (`browser_network_requests`) and for the content
+     signal, and only then take the snapshot. When the first read is empty or missing something, wait and read
+     again before you record or ask anything. Record the signal as `(observed after <signal>, ...)`.
+   - **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, take the highlighted screenshot to
+     `.explore/targets/<case-id>/`, **open that screenshot and look at it**, 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 outline the target with `browser_annotate`.
+   - **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).
+   - 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.
+   - 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
+   `references/assertion-targets.md`, and a `[T<n>]` reference in each check that uses it. Add `Ready when:` to every
+   step or target whose content loads after an action. A check with no card or a card with open doubts is a
+   `[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 recording, 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
+   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
+   the safe default as the sentence above a `[non-blocking]` TODO block, else keep a `[blocking]` block. Write the
+   outcome into the case, every block with an empty `Answer:` line.
+8. **Check**: run `pnpm case:check` (it fails on an incomplete target card and warns on a check that has none) and fix every FAIL. If it 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 steps the person did and what was recorded for them, 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, and findings that look
+   like product bugs. End with the `RESULT:` line.
+
+## Hard rules
+- Edit `cases/<id>.md` only. Do not touch the `## Source` table.
+- The agent never writes data (see above). Never add `--allow-writes`, never set `ASRUN_ALLOW_WRITES`.
+- Never wait for a person in a run that is not attended.
+- Never invent expected values, profile names, counts or UI texts. Observations are marked as such. Values that a
+  check asserts are written into the case's `## Values` under the profile id (or `default` when they hold for every
+  profile), and never into `profiles.yaml`.
+- Never pick a target when in doubt, and never record a fact that was read before the content finished loading.
+- Never read or print anything under `.auth/`. Never automate login or 2FA.
+- Prose follows the artifact language of the workspace `AGENTS.md` §2 (English by default); structural tokens stay English.