@asrunjs/asrun 0.2.0 → 0.5.3

package/docs/ai-workflow.md

@@ -0,0 +1,235 @@
+# The AI workflow
+
+Four commands carry a test case from rough notes to a Playwright spec, and repair it when the product changes. They
+work the same in Claude Code and OpenCode: each command is a thin shell that loads a skill from the framework package,
+so the procedure lives in one place and a project can refine it (see
+[Customizing the prompts](#customizing-the-prompts)).
+
+| Command | What it does |
+|---|---|
+| `/make-case <notes-or-path>` | Turn raw notes into case documents. Optional step. |
+| `/explore-case <case-id> <env> [--attended]` | Open the real pages and write what they show into the case. |
+| `/gen-spec <case-id> <env> [--force]` | Write `tests/<case-id>.spec.ts` and fill the case's `## Values`. |
+| `/heal-spec <case-id> <env> [--profiles a,b] [--report <run-id>] [--hints <file>]` | Diagnose a failing spec from its last report and fix it. |
+
+The environment is **required** by every command except `/make-case`, which does not open pages. There is no default.
+
+Every command ends with `RESULT: ready` or `RESULT: needs-input`. `needs-input` means somebody has to answer a
+question in the case file (or, in the web UI, in the job's **Answer** sheet). A one-shot run cannot ask in the chat:
+it writes its questions into the case and stops.
+
+In the web UI you never type a command: choose the step in a case toolbar and press **Run AI**, or paste notes on
+**Cases > From memo**. The UI runs the selected AI tool and streams the output into the Jobs bar.
+
+## 0. Optional: start from raw notes
+
+```
+/make-case path/to/notes.md
+```
+
+or paste the text after the command. The agent normalizes the notes into steps in the project's artifact language
+(English by default), marks the steps that write data (`[writes]`) or send email (`[email]`), keeps the original lines
+in a `## Source` table, and lists the gaps with a suggested default for each. It never invents expected values
+(unknown ones become a sentence with a `TODO` block under it) and never opens a browser. What the pages really show
+is found in step 2.
+
+It writes `cases/<id>.md` only, and never overwrites an existing case. `pnpm case:check` validates the result.
+
+## 1. Write or open the case
+
+`pnpm case:new header-logo` creates `cases/header-logo.md` from the template, or use a case you already have. The
+format is in [cases.md](./cases.md). Write the steps, the expectations and — when you know them — the values.
+
+## 2. Explore the case (only where a person and the agent work together)
+
+```
+/explore-case header-logo staging
+```
+
+The agent opens the real pages of the profiles that are logged in and only **reads** them. It never creates, edits,
+publishes, shares or deletes anything, in staging or in production. It:
+
+- fixes wording in the case file and writes what the pages show into it, marked `observed, 🔍 to be confirmed by QA`;
+- turns what it cannot know into `🚫 TODO [blocking]` / `❓ TODO [non-blocking]` questions, each under a sentence that
+  is its suggestion and can stand in the case as it is, with a last line `- ✍️ Answer:`;
+- lists the candidates instead of guessing a target (`## Targets`);
+- edits the case file only (plus reference screenshots under `.explore/targets/`).
+
+**To accept the suggestion, delete the whole block.** **To answer, write after `Answer:`.** Then run the command
+again. In the web UI, the run's **What to do next** bar offers **Answer**: the question list, an answer box,
+**Use the suggested defaults** and **Generate spec**. A continued job keeps the same conversation and permissions, and
+can be continued once per turn, only while the UI server has not restarted.
+
+### Attended exploration (`--attended`)
+
+Use it for a case that creates or edits data, or needs a choice (an existing document, items). Stay at the computer:
+the browser window opens and the agent waits while you do those steps.
+
+- The window shows a small draggable card in the bottom-left corner with what to do, **Done** (hand control back) and
+  **Cannot do this**. The agent also continues by itself when the finish condition it named shows up (for example a
+  "Saved" message); the card turns green when control is back. It waits up to 10 minutes per step.
+- What you did is recorded in the case under the step as **general recipe lines**
+  (`- Recipe (phase): ...`): positions instead of names of changeable data, `[asrun]` names for created data, control
+  labels but no selectors.
+- Delete the `[asrun]` items you created before you press Done on the last step.
+- Without `--attended` the agent never waits: a step that needs a person becomes a `TODO [blocking]`.
+
+In the web UI the **Attended** box is ticked by default for Explore.
+
+## 3. Log in the profiles the case needs
+
+```bash
+pnpm status
+pnpm signin example-staging
+```
+
+Skip this for a `login: none` case. Sessions are per profile; see [profiles.md](./profiles.md).
+
+## 4. Generate the spec
+
+```
+/gen-spec header-logo staging
+```
+
+The agent replays the case on the real pages with your saved sessions (it never writes data) and writes
+`tests/header-logo.spec.ts`. It fills the case's `## Values` for the profiles it explored and checks the files
+(`pnpm typecheck`, `pnpm case:check`; `pnpm spec:lint <case-id>` must have no failure).
+
+It does **not** run the spec and does **not** create screenshot baselines: running is a separate step (6).
+
+- A case must be in the project's artifact language. If it is in another language, `/gen-spec` translates the case
+  file first and tells you.
+- A `[writes]` or `[input]` step with no `- Recipe:` line under it is not generated: the command stops with
+  `needs-input` and asks you to run step 2 with `--attended`.
+- An existing spec is left alone; `--force` regenerates it from the case. The case's `## Values` and the baseline
+  images are kept, and the report lists the baselines that may be out of date. In the web UI, **Run** on a case that
+  has a spec asks "Overwrite the spec?" first.
+
+## 5. Review what the AI produced
+
+Check that the spec reads like the case, and that `## Values` has the right values for each profile. The spec imports
+`test`/`expect` from `@asrunjs/asrun/fixtures`, never from `@playwright/test`, and every step is a `test.step` named
+after the case's step. You normally do not edit either file by hand, but you can.
+
+## 6. Run it and read the evidence
+
+```bash
+pnpm asrun --env staging --grep header-logo
+pnpm report
+```
+
+The first run of a spec with visual checks writes its baselines. Run it once with `--update-snapshots`, then open
+every new image under `tests/<case>.spec.ts-snapshots/` and confirm it shows the target card's element for that
+profile. Baselines are the source of truth for pixel checks.
+
+Then run all profiles and read the report: the video of each test, screenshots on failure, and the trace with the page
+and the network requests. See [commands.md](./commands.md) for filters and baselines.
+
+## Healing a failing spec
+
+```
+/heal-spec header-logo staging
+```
+
+or **Heal spec** in the case toolbar, or **Heal this failure** on a failed result of the Reports page.
+
+The agent decides whether the test needs updating or whether it found a real product problem. It **never** edits an
+expectation just to make a failure disappear.
+
+- The environment is required. Only the profiles that are logged in there run (`--logged-in` leaves the others out
+  instead of failing them).
+- The web UI first opens a dialog: which profiles to heal (every logged-in profile ticked) and an optional text box
+  for what you want healed, with evidence or clues. The text is stored in `.tmp/hints/` and passed as `--hints`.
+  Clues guide the diagnosis; they never lower the bar for a product finding.
+- It reads the existing report first:
+
+  ```bash
+  pnpm heal:evidence --case header-logo --env staging
+  ```
+
+  It prints status, failed step, error, call log and screenshots per profile, and whether the report is fresh or
+  stale. The case is run again only when there is no report, the report is stale, it does not explain the failure, or
+  a clue has to be checked. After editing the spec, it runs the case once to confirm.
+
+## Why a generated spec can be trusted
+
+Three binding rules hold in exploring, generating and healing. They live in the framework's `AGENTS.md` and in
+`.claude/skills/exploring-cases/references/assertion-targets.md` and `readiness.md`.
+
+- **Targets.** A check on a logo, image, icon, file, PDF, screenshot or repeated text points to a `[T1]` card under
+  `## Targets`: what it is (and what it is not), where it is, how it is identified (never `.first()` or a bare `img`),
+  when it is ready, and a highlighted reference screenshot under `.explore/targets/`. When in doubt the agent does not
+  pick: it writes a `🚫 TODO [blocking]` that names the exact image, text, place or UI, with the candidates listed.
+- **Readiness.** After an action that loads something, the key requests must finish and the content must be visible
+  before anything is read. Specs use `actAndWait` (`@asrunjs/asrun/ready`); "missing" and "empty" checks need a
+  positive ready signal first. Healing treats a "missing / empty / timeout" failure as a readiness problem first.
+- **Downloads.** `verifyDownload` (`@asrunjs/asrun/downloads`) checks that the download starts, finishes, the file
+  exists and the file is valid for its kind. Any failure or timeout fails the whole step with a message that names the
+  stage.
+- **PDFs are read like a person reads them.** `expectPdf` (`@asrunjs/asrun/pdf`) renders the pages to images (a logo
+  region must not be blank and must match the profile's baseline, 2% tolerance) and extracts the text. Every page is
+  checked unless the case limits the pages in strong words ("only", "exactly", "must"); "should", "always", "usually"
+  or no wording mean every page.
+
+Checks you can run yourself:
+
+| Command | What it checks |
+|---|---|
+| `pnpm spec:lint [case-id]` | fails on screenshots without a target, `.first()` on images, sleeps, `networkidle`, raw download events, a `%PDF` check on its own |
+| `pnpm baselines:review [case-id] [--new]` | lists every baseline with the card that says what it must show, so you can look at each new image |
+| `pnpm case:check [case-id]` | fails on an incomplete card or bad values; warns on an image check with no card |
+| `pnpm pdf:render <file.pdf> --out <dir> [--pages all] [--corner top-left]` | renders the pages to images and prints the text, to look at a PDF by hand |
+
+## Customizing the prompts
+
+The commands are shells; the procedure is a skill in the framework package:
+
+- commands: `.claude/commands/*.md` (Claude Code) and `.opencode/commands/*.md` (OpenCode);
+- skills: `<framework>/.claude/skills/{making-cases,exploring-cases,generating-specs}/`.
+
+A project refines a skill with a **flat override file**, named after the skill (not the command):
+
+```
+.claude/skills/generating-specs.md
+.claude/skills/exploring-cases.md
+.claude/skills/making-cases.md
+```
+
+The command and the skill read it; it is not discovered as a standalone skill. Rules combine in this order, and a
+later one wins where they conflict:
+
+1. `F1`–`F6` of the framework baseline: safety, in every project. Nothing can change them.
+2. The framework baseline, `<framework>/AGENTS.md`.
+3. The framework skill.
+4. The project override `.claude/skills/<skill>.md`.
+5. The project's own `AGENTS.md` §2 (Project rules).
+
+An override is plain Markdown; write only what differs:
+
+```markdown
+# generating-specs in this project
+
+- Step titles in `test.step` keep the case's wording, including the number.
+- A helper used by more than one spec goes in `tests/helpers/<name>.ts`.
+- The staging account has no published documents: assert the empty state there instead.
+```
+
+The project's `AGENTS.md` §2 is the other place: a table of rule ids (`F7`–`F10`; `F1`–`F6` are fixed) with `narrows`
+(stricter) or `replaces` (a different default). For example, a project that writes cases in Simplified Chinese
+`replaces` `F10`. `pnpm asrun doctor` fails on an unknown id, a missing `Effect`, or a non-negotiable rule, and lists
+the overrides it sees.
+
+An update never overwrites `AGENTS.md`, `CLAUDE.md` or `.claude/skills/**`: `pnpm asrun init --force` refuses them
+without `--reset-rules`. Never edit the framework package itself.
+
+Project-level AI tool configuration:
+
+| File | What it sets |
+|---|---|
+| `.mcp.json` | the `playwright-test` MCP server for Claude Code |
+| `opencode.jsonc` | the same MCP server for OpenCode, plus an optional `"model"` for one-shot runs |
+| `.claude/settings.json` | the sandbox exceptions for `pnpm asrun`, `pnpm status`, `pnpm heal:evidence` |
+
+In the web UI, the top bar chooses the AI tool and the model for every AI run, and **Thinking** passes `--thinking`
+to OpenCode. The choice is remembered per CLI in the browser. Without a model, a one-shot OpenCode run uses its
+built-in free model, which has a daily usage limit.

package/docs/cases.md

@@ -0,0 +1,189 @@
+# Writing case documents
+
+A case is a Markdown file that a person writes and reviews. It is the source of truth for the test: steps,
+expectations, the exact values and the visual targets. The spec is generated from it and never replaces it.
+
+## Where cases live
+
+- `cases/<name>.md`, or one group folder: `cases/<group>/<name>.md`.
+- The **id** is the path below `cases/` without `.md`: `header-logo` or `documents/landing-page`. Names are lowercase
+  words with single dashes.
+- The spec of a case lives at the same path below `tests/` (`tests/documents/landing-page.spec.ts`), with its
+  `*-snapshots/` folder next to it.
+- Files starting with `_` are ignored (`cases/_template.md` is the template).
+
+```bash
+pnpm case:new header-logo             # creates cases/header-logo.md from the template
+pnpm case:new documents/header-logo   # also creates the group folder
+pnpm case:check                       # validates every case (or: pnpm case:check <id>)
+```
+
+## The document
+
+````markdown
+---
+id: header-logo
+title: The header shows the product logo
+login: required
+suites: [smoke, regression]
+---
+
+## Goal
+Why this case exists, in one or two sentences.
+
+## Steps
+1. Open `/`.
+    - Ready when: the header has rendered its menu.
+2. The header shows the product logo. [T1]
+
+## Expected
+- The logo is the product logo for this profile, not a customer or partner logo.
+
+## Values
+```yaml
+default:
+  logoAlt: Acme
+example-staging:
+  logoAlt: Acme Staging
+```
+
+## Visual checks
+- The header logo matches its baseline. [T1]
+
+## Targets
+### T1 Header logo
+- What: the product logo, not the customer logo in the banner.
+- Where: top-left of the header.
+- Identified by: role `img`, name "Acme".
+- Not: the customer logo in the banner and the favicon.
+- Ready when: the image has a non-zero natural width.
+- Reference example-staging: .explore/targets/header-logo/T1-example-staging.png
+
+## Notes
+Anything a reviewer should know.
+````
+
+The headings are fixed English tokens (`Goal`, `Steps`, `Expected`, `Values`, `Visual checks`, `Targets`, `Notes`,
+and `Source` when the case was made from raw notes). A project language never translates them.
+
+## Front matter
+
+| Key | Meaning |
+|---|---|
+| `id` | The case id (the path without `.md`). |
+| `title` | One-line summary, shown in the editor and the spec. |
+| `login` | `required` (the default) or `none` for a public page that needs no saved session. A `login: none` spec sets `test.use({mustLogin: false})`. |
+| `suites` | Required. One or more lowercase words: `suites: [smoke, regression]`. A case runs in every suite it lists. |
+| `writes` | The environments in which the case may create or change data, for example `writes: [staging]`. Omit it for a read-only case. |
+| `writes-note` | Required with `writes`: what the case creates or changes, and that it is removed again. |
+| `envs` | Optional: run the case only in these environments; elsewhere it is skipped. Must include every environment in `writes`. |
+
+`priority: <level>` is the old name of `suites`; it is read as `suites: [<level>]`. Do not use both.
+
+## Steps
+
+Numbered lines. Keep them short and in plain language: the spec uses each step's text verbatim in `test.step`, so the
+report and the trace read like the case.
+
+- **`- Ready when:`** under a step says what positive signal shows that what the step loads is really there (the list
+  has its first row, the editor is visible). The generated spec waits for it before it reads anything. It is not an
+  assertion; what must be true goes under `## Expected`.
+- **Step tags**: `[writes]` for a step that creates or changes data, `[input]` for a step that needs a person's
+  choice (an existing document, items), `[email]` for a step that sends email. They are written at the end of the
+  step line.
+- **`- Recipe (phase):`** under a tagged step records what a person did in the browser during an attended
+  exploration: positions instead of names of changeable data (`select items #1 to #3`), `[asrun]` names for created
+  data, control labels but no selectors. Several lines per step are normal. A tagged step with no recipe is not
+  generated: `/gen-spec` stops with `needs-input`.
+- **Open questions** go in a `🚫 TODO [blocking]` or `❓ TODO [non-blocking]` block under the sentence they are about,
+  with the agent's suggestion written above and a last line `- ✍️ Answer:`. Accepting a question means deleting the
+  whole block; answering means writing after `Answer:`. The marker `🔍 to be confirmed by QA` / `👁️ not observed`
+  marks something seen but not settled.
+
+## Expected
+
+Bullets: behaviour that must hold for every profile. Profile differences belong in `## Values`, not in prose.
+
+## Values
+
+The exact literals the spec asserts, in one fenced `yaml` block: names, labels, options, test data names.
+
+```yaml
+default:
+  createButton: Create New
+  emptyList: No documents yet
+example-staging:
+  createButton: Create a document
+```
+
+- `default` applies to every profile; an entry named after a profile id is **deep-merged over it**. An empty cell in
+  the UI removes the key from that profile.
+- Only profile ids from `profiles.yaml` (or `default`) may appear at the top level. An unknown entry is an error.
+- The case document is the only place where expected values live. `profiles.yaml` holds connection settings only.
+- A profile with no entry (and no `default`) fails with "Missing values"; an empty value or one that starts with `TODO`
+  fails with "Incomplete values". Both messages say what to fill in.
+- Specs read them with `requireValues('<id>', profile)` and never parse the YAML themselves.
+
+## Visual checks and targets
+
+A visual check names the element that must match a screenshot baseline. A check on a logo, image, icon, file, PDF,
+screenshot or repeated text refers to a card under `## Targets` as `[T1]`, and the spec carries `// target: T1` on the
+line before the check.
+
+Each card has these fields:
+
+- `What`: the thing itself, and what it is **not** when a look-alike exists.
+- `Where`: the region of the page, dialog, tab or file page.
+- `Identified by`: role and name, test id, alt text or title; never a position.
+- `Not`: the look-alikes that must not be matched.
+- `Ready when`: what shows the content has loaded.
+- `Reference <profile-id>:` a screenshot under `.explore/targets/<case-id>/`, or `none: <reason>`.
+
+Do not guess a target: when it is unclear which element is meant, the exploring agent writes a `🚫 TODO [blocking]`
+that names the candidates, and a person settles it. The binding rules are in
+`../.claude/skills/exploring-cases/references/assertion-targets.md` of the framework package.
+
+## Data writing
+
+By default a case is read-only: look, read, compare. No creating, editing, deleting, submitting or accepting
+anything.
+
+A case may write only in the environments listed under `writes`, and only data of the test account:
+
+- everything it creates is named `[asrun] ...` (the `records` fixture refuses other names);
+- created data is registered with `records.track` and removed after the test, also after a failure;
+- the case's own last step is normally the deletion; `track` is the safety net;
+- staging needs no confirmation. In any other environment a person confirms every run (typing the environment name,
+  or the dialog in the web UI). `--read-only` leaves the write cases out, and `--allow-writes=<env>` skips the prompt
+  for unattended runs (AI agents never use it);
+- write cases are never retried and run one at a time per profile;
+- a case that is not allowed to write in the current environment is **skipped with a notice**, not failed;
+- whatever could not be removed is listed in red in the report and by `pnpm cleanup --env <env>`; delete it by hand,
+  then `--forget`.
+
+Email is never sent in production, and elsewhere only when the profile has `email: true`. A step that sends email is
+wrapped in the spec with `emailStepAllowed(profile, '<step title>')`, which records the skip in the report.
+
+Never write a case for the login page or the login flow: login is a person's job (`pnpm signin`), not a test.
+
+## What `pnpm case:check` validates
+
+It reads every case (or the ids you pass) and prints one line per case. It **fails** on:
+
+- invalid front matter (missing `suites`, a bad `writes`/`envs` combination, `writes` without `writes-note`);
+- a target card without its required fields (`What`, `Where`, `Identified by`), or a reference image outside
+  `.explore/targets/<case-id>/`;
+- a `[T<n>]` reference with no card;
+- an invalid `## Values` block (bad YAML, an unknown profile, a non-map entry).
+
+It **warns** (usable, but something to settle) on: a reference image missing on this machine (`.explore/` is
+git-ignored), a card without a reference line, a check on an image or file with no target card, no `## Values`, a
+`[input]`/`[writes]` step with no `- Recipe:` line, the old `## Inputs` / `## Data` sections, and question blocks
+that cannot be answered in place.
+
+## Rename or move a case
+
+Use the Cases page (click the file name or the pencil icon). The spec and the baseline images move with it and the
+spec is rewritten to match. By hand, move the three things together (`cases/...md`, `tests/...spec.ts`, its
+`*-snapshots/`), and keep the spec's `// case:` line and its imports unchanged: specs import the framework by package
+name, so their folder depth does not change the imports.

package/docs/commands.md

@@ -0,0 +1,175 @@
+# Command reference
+
+Every command runs in a workspace (the folder that owns `profiles.yaml`); see
+[install.md](./install.md#which-workspace-a-command-runs-against). In a project the scripts of `package.json` are
+thin wrappers, so `pnpm asrun`, `pnpm signin` and the rest work as below. The same commands through the package are
+`pnpm exec asrun ...`.
+
+| I want to... | Command |
+|---|---|
+| Install / update the framework | `pnpm dlx @asrunjs/asrun init --install`, `pnpm add -D @asrunjs/asrun@latest` |
+| Prepare or check the workspace | `pnpm asrun init [--update]`, `pnpm asrun doctor` |
+| Start the web UI | `pnpm go`, `pnpm ui`, `pnpm ui:dev` |
+| See which profiles are logged in | `pnpm status [--env <env>]` |
+| Log in a profile (a person, with 2FA) | `pnpm signin <profile-id>` |
+| Run tests | `pnpm asrun --env <env> [filters]` |
+| Open the last report | `pnpm report` |
+| Look around a page as a profile | `pnpm explore <profile-id> [path]` |
+| Read what the last report says about a case | `pnpm heal:evidence --case <case-id> --env <env>` |
+| List or forget test data that could not be removed | `pnpm cleanup --env <env> [--forget]` |
+| Create or validate a case | `pnpm case:new <id>`, `pnpm case:check [case-id]` |
+| Check a spec | `pnpm spec:lint [case-id]`, `pnpm baselines:review [case-id] [--new]` |
+| Look at a PDF | `pnpm pdf:render <file.pdf> --out <dir> [--pages all] [--corner top-left]` |
+| Type-check the workspace | `pnpm typecheck` |
+
+## Running tests: `pnpm asrun`
+
+```bash
+pnpm asrun --env staging
+```
+
+`--env` is **required**; there is no default. A run selects the profiles whose `env` matches, checks their sessions,
+runs the selected cases once per profile, and writes one report folder per run.
+
+```bash
+pnpm asrun --env production --profile example-production
+pnpm asrun --env production --skip-profile example-staging,example-production
+pnpm asrun --env staging --tag us
+pnpm asrun --env production --logged-in
+pnpm asrun --env production --suite smoke
+pnpm asrun --env production --suite smoke,regression
+pnpm asrun --env production --grep landing
+pnpm asrun --env production --read-only
+pnpm asrun --env staging --ui
+```
+
+| Flag | Effect |
+|---|---|
+| `--env <env>` | Required. The environment to run. |
+| `--profile a,b` | Only these profiles. |
+| `--skip-profile a,b` | Every profile except these (for example the ones that are not logged in). |
+| `--tag <tag>` | Only the profiles that carry the tag (comma-separated for several). |
+| `--logged-in` | Only the profiles whose saved session works; the others are left out instead of failing. |
+| `--suite <name>` | Only the cases whose front matter lists the suite (comma-separated; a case in two chosen suites runs once). `--priority` is the old name. |
+| `--grep <text>` | Only the cases whose title matches (Playwright `--grep`). |
+| `--read-only` | Leave out every case that writes data. |
+| `--allow-writes=<env>` | Run the write cases in that environment without the prompt. For unattended runs only; AI agents never use it. |
+| `--step-text` | Overlay the current test step on the videos (`=1\|true\|yes\|on`; off by default). |
+| `--update-baselines <case,case>` | Overwrite the screenshot baselines of exactly these cases. See below. |
+| `--report-id <id>` | Name of the report folder (default: the timestamp). |
+| `--ui`, other Playwright options | Passed through to Playwright. `--ui` opens its interactive mode. |
+
+A case that writes data runs only in the environments it lists under `writes`; elsewhere it is skipped with a notice.
+In **staging** no confirmation is needed. In any other environment a person confirms every run: `pnpm asrun` lists
+the write cases and asks you to type the environment name; the web UI asks in a dialog. Unattended runs combine the
+prompt with `--allow-writes=<env>`; AI agents must not. `--read-only` leaves the cases out instead.
+
+## Reports and evidence
+
+Every run writes to `reports/<run-id>/`, where the run id is the timestamp and the environment
+(`reports/2026-10-28T07-30-22-staging`), and points `reports/latest` at the newest one.
+
+- **Video:** one per test, with the recordings of every browser tab joined in order into `reports/<run>/videos/`.
+  Joining needs ffmpeg; without it the report lists the recordings separately. `--step-text` writes the current step
+  on the video.
+- **Trace:** the page before and after every action, plus every network request. Open a trace directly with
+  `pnpm exec playwright show-trace <trace.zip>`.
+- **Screenshots:** on failure, and the baselines of visual checks with their diff.
+- **Leftover test data:** listed in red in the report and in the terminal.
+
+`pnpm report` opens the HTML report of the latest run. `pnpm asrun` also prints the paths of the videos and traces
+when it finishes. Recordings contain real pages: do not share them outside the team.
+
+## Baselines
+
+Baselines are per profile (`...-example-staging-darwin.png`) and are the source of truth for pixel checks.
+
+Fix the spec first (the check must look at the element its target card names), then:
+
+```bash
+pnpm asrun --env staging --profile example-staging --grep header-logo --update-baselines header-logo
+pnpm baselines:review header-logo
+```
+
+- `--update-baselines` lists the cases whose images are overwritten; they must be among the cases the filters run.
+  Playwright has one global switch, so those cases run as a second pass with their own report
+  (`<run-id>-baselines`, for example `2026-10-28T07-30-22-staging-baselines`); every other case is compared with its
+  baselines as usual.
+- Without it, Playwright's own `--update-snapshots` still rewrites every image of the run.
+- In the web UI every case in **Cases to run** has an **Update baselines** box (unticked by default), with a
+  confirmation, and the new images are shown next to their target cards when the run ends.
+- An agent never updates a baseline: that is a person's decision.
+
+## Login and sessions
+
+```bash
+pnpm status                 # every profile, or: pnpm status --env staging
+pnpm signin example-staging
+```
+
+The login is done by a person, including 2FA; the session is saved to `.auth/<profile-id>.json` and verified. See
+[profiles.md](./profiles.md).
+
+## Cases and checks
+
+```bash
+pnpm case:new header-logo
+pnpm case:new documents/header-logo
+pnpm case:check
+pnpm spec:lint header-logo
+pnpm baselines:review --new
+pnpm pdf:render report.pdf --out .explore/targets/header-logo --corner top-left
+```
+
+- `case:new` creates the case from the template. One optional group folder, created on demand.
+- `case:check` validates front matter, values and target cards; see [cases.md](./cases.md).
+- `spec:lint` is a static check of the specs: it fails on sleeps, `networkidle`, image checks without a target,
+  `.first()` on images, raw download events, a magic-number-only PDF check. `pnpm spec:lint <case-id>` limits it.
+- `baselines:review` opens nothing; it lists every baseline next to the target card that says what it must show.
+  `--new` lists only the images that are new or changed (by git).
+- `pdf:render` writes page images and prints the text, so a person (or an exploring agent) can look at a PDF.
+
+## Exploring and healing evidence
+
+```bash
+pnpm explore example-staging /app/home
+pnpm heal:evidence --case header-logo --env staging
+```
+
+`explore` opens a logged-in browser at the profile's `startPath` (or the path you pass, or the site root). Downloads
+are saved to `~/Downloads` and never overwrite an existing file. `heal:evidence` prints the last run's status, failed
+step, error, call log and screenshots for a case, and whether the report is stale; it is what `/heal-spec` reads
+first.
+
+## Cleanup
+
+```bash
+pnpm cleanup --env staging
+pnpm cleanup --env staging --forget
+```
+
+A write case registers everything it creates (named `[asrun] ...`) and removes it after the test, also after a
+failure. Whatever could not be removed is listed in the report and by `cleanup`. Delete it by hand in the product,
+then run `--forget` so it is not listed again. `--env` is required.
+
+## Web UI
+
+```bash
+pnpm go          # install + build + start + open the browser (the usual command)
+pnpm ui          # build the web app and serve http://127.0.0.1:4173
+pnpm ui:dev      # Vite on :5173 with hot reload, API in watch mode
+```
+
+The UI only listens on `127.0.0.1`. Set `ASRUN_UI_PORT` to change the port (`ASRUN_UI_WEB_PORT` for the Vite dev
+server). See [web-ui.md](./web-ui.md).
+
+## Workspace
+
+```bash
+pnpm asrun init [--update] [--force <file>] [--reset-rules] [--root <dir>] [--no-env] [--install [spec]]
+pnpm asrun doctor
+```
+
+`init` writes the workspace files; `--update` refreshes only the generated ones. `doctor` checks profiles,
+`tsconfig.json`, `playwright.config.ts`, the generated files, the installed version, the project rule table and the
+skill overrides. Full details in [install.md](./install.md).