@asrunjs/asrun 0.5.2 → 0.6.0

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).

package/docs/install.md

@@ -0,0 +1,174 @@
+# Installing AsRun
+
+AsRun is a normal devDependency. A **workspace** is the folder that owns `profiles.yaml`, `cases/` and `tests/`;
+everything AsRun needs at run time is read through it. The framework itself lives in `node_modules/@asrunjs/asrun`
+and is never edited: a project commits only its own test content.
+
+## Requirements
+
+- **Node.js 22 or newer** and **pnpm**.
+- **ffmpeg** joins the recordings of one test (a new browser tab has its own video) into one video for the report.
+  `pnpm go` installs it with Homebrew on macOS or winget on Windows; on Linux run `sudo apt install ffmpeg`. When it
+  is missing, the optional `ffmpeg-static` package is used instead; if neither works, the report lists the videos
+  separately. Not fatal.
+- **Claude Code or OpenCode** for the AI steps (make cases, explore, generate, heal). Everything else works without
+  them; `pnpm go` warns when neither command is found.
+
+## Install in a project
+
+```bash
+pnpm dlx @asrunjs/asrun init --install
+pnpm go
+```
+
+`init --install` scaffolds the workspace and then adds the dependency. Running `init` first matters on pnpm 12: it
+writes `pnpm-workspace.yaml` with the `allowBuilds` entry (`esbuild` through `tsx`, `ffmpeg-static`), and without it
+`pnpm add` exits with `ERR_PNPM_IGNORED_BUILDS`. An existing `pnpm-workspace.yaml` that lacks the entry gets a note
+instead: add the block by hand (see "Manual install").
+
+`pnpm go` then does the rest and is the command to remember:
+
+1. checks Node (22+) and ffmpeg, and warns when no AI CLI is installed;
+2. installs the dependencies and the Chromium browser (`pnpm install` + `playwright install chromium`);
+3. runs `asrun init` (workspace files and `.env`) and `asrun doctor`;
+4. starts the web UI at http://127.0.0.1:4173 and opens it.
+
+Run it again on any day: the install step then takes seconds, and if the UI is already running it only opens it.
+`pnpm go --no-open` does not open a browser. Set `ASRUN_UI_PORT` to change the port.
+
+The UI is optional: all commands in [commands.md](./commands.md) work without it.
+
+### Manual install
+
+Same result, step by step:
+
+```bash
+pnpm add -D @asrunjs/asrun
+pnpm asrun init
+pnpm go
+```
+
+If pnpm refuses the build scripts of `esbuild` / `ffmpeg-static`, add this to `pnpm-workspace.yaml` and run the
+install again:
+
+```yaml
+allowBuilds:
+  esbuild: true
+  ffmpeg-static: true
+```
+
+To pin a version:
+
+```bash
+pnpm add -D @asrunjs/asrun@<version>
+```
+
+`pnpm asrun init` is safe to run many times: it never overwrites a file the project owns.
+
+## What `init` writes
+
+| Kind | Files | On `--update` |
+|---|---|---|
+| Generated | `playwright.config.ts`, `tests/seed.spec.ts`, `.claude/commands/*`, `.opencode/commands/*` | rewritten |
+| Once | `AGENTS.md`, `CLAUDE.md`, `.mcp.json`, `opencode.jsonc`, `.claude/settings.json`, `tsconfig.json`, `pnpm-workspace.yaml`, `profiles.yaml`, `cases/_template.md`, `package.json` (scripts and devDependencies merged in) | kept |
+
+It also writes the asrun block in `.gitignore`, the `ASRUN_ROOT` line in `.env`, and `.asrun.json` (the marker with
+the framework version and the generated file list).
+
+Flags:
+
+| Flag | Meaning |
+|---|---|
+| `--root <dir>` | initialize that folder instead of the current one |
+| `--update` | refresh only the generated files |
+| `--force <path>` | overwrite one file init owns (repeatable) |
+| `--reset-rules` | allow `--force` on `AGENTS.md`, `CLAUDE.md` or `.claude/skills/**` |
+| `--no-env` | do not write `.env` |
+| `--install [spec]` | also add the dependency (default `@asrunjs/asrun`) |
+
+`AGENTS.md`, `CLAUDE.md` and `.claude/skills/**` belong to the project. `init --force` refuses them without
+`--reset-rules`, so a framework update can never replace a project's rules.
+
+## Update
+
+```bash
+pnpm add -D @asrunjs/asrun@latest
+pnpm asrun init --update
+pnpm asrun doctor
+```
+
+`init --update` rewrites only the generated files and leaves project rules, case files, values and baselines alone.
+`doctor` tells you when the workspace is behind the installed version.
+
+There is no folder to move: the framework lives in `node_modules`, which the package manager owns. To change the
+framework itself, `pnpm patch @asrunjs/asrun` (a committed patch).
+
+## `pnpm asrun doctor`
+
+Run it after changing profiles, rules or overrides, and after an update. It checks:
+
+- every entry in `profiles.yaml` (ids, environments, URLs, session check settings);
+- `tsconfig.json`, `playwright.config.ts` (its re-export of the framework config) and the generated files;
+- that `.gitignore` ignores `.auth/` and `reports/`;
+- whether the installed version is behind the package's templates, and whether `dist/` is out of date;
+- the project rule table in `AGENTS.md` §2 (unknown ids, a missing `Effect`, a non-negotiable rule);
+- the framework skills and the project overrides under `.claude/skills/<skill>.md`, and lists the ones it sees.
+
+## Which workspace a command runs against
+
+The order is:
+
+1. a real environment variable `ASRUN_ROOT` (it wins over everything);
+2. `ASRUN_ROOT` in the `.env` next to the command, or in the framework package's own `.env` (relative to that file);
+3. otherwise the nearest folder at or above the working directory that has `profiles.yaml` or `.asrun.json`;
+4. in the framework repository, the framework's own `.env` points at `examples/demo`.
+
+A real environment variable always wins, so one checkout can point at another project for a single command:
+
+```bash
+ASRUN_ROOT=../my-real-project pnpm asrun --env staging --read-only
+```
+
+## Workspace layout
+
+```
+profiles.yaml       one entry per environment: URL, account label, tags, environment (no expected values)
+cases/              human-written cases (+ _template.md); optional group folders: cases/<group>/<name>.md
+tests/              generated specs (same folders as cases/) and *-snapshots/ baselines per profile
+playwright.config.ts  re-exports node_modules/@asrunjs/asrun/dist/playwright.config.js
+tsconfig.json       plain compiler options (specs import the framework by package name)
+AGENTS.md           project rules: they point at the framework baseline; §2 says what differs
+CLAUDE.md           imports AGENTS.md for Claude Code
+.claude/commands/   /make-case, /explore-case, /gen-spec, /heal-spec (thin shells that load the framework skill)
+.claude/skills/     optional project overrides of a skill: <skill>.md
+.opencode/commands/ the same commands for OpenCode (it does not read .claude/commands)
+.mcp.json           the playwright-test MCP server for Claude Code
+opencode.jsonc      the same for OpenCode, plus an optional model
+.asrun.json         marker: framework version and the generated file list
+package.json        the workspace scripts (`asrun`, `signin`, ...) and devDependencies
+.env                ASRUN_ROOT (which workspace the commands use) and local settings
+node_modules/@asrunjs/asrun/   the framework (installed dependency; never edited)
+.auth/              saved logins, one per profile
+reports/            one folder per run; reports/latest points at the newest
+.tmp/ .explore/     job logs, hints, reference screenshots (local state)
+```
+
+The framework repository's own layout is in [agents/framework-dev.md](./agents/framework-dev.md).
+
+## What to commit
+
+Commit `profiles.yaml`, `cases/`, `tests/` (with `*-snapshots/`), `AGENTS.md`, `CLAUDE.md`, `.claude/`,
+`.opencode/commands/`, `.mcp.json`, `opencode.jsonc`, `.asrun.json`, the generated files, `package.json`, `tsconfig.json`
+and `pnpm-workspace.yaml`.
+
+Never commit or share `.auth/` (one saved login per profile, as sensitive as a password), `reports/`, `.tmp/`,
+`.explore/`, `.env` or `node_modules/`. The asrun block of `.gitignore` covers them.
+
+## Uninstall
+
+```bash
+pnpm remove @asrunjs/asrun
+```
+
+Then delete the workspace files you no longer want (`profiles.yaml`, `cases/`, `tests/`, the generated commands and
+configs, `.asrun.json`). They are ordinary files: keep them if another tool still uses them.

package/docs/profiles.md

@@ -0,0 +1,139 @@
+# Profiles and environments
+
+A **profile** is one environment of the system under test: a URL, an account label, optional tags and the environment
+name. Each entry in `profiles.yaml` becomes one Playwright project named after its `id`, and every spec runs once per
+profile. Two profiles of the same site give you two independent views, logins and baselines.
+
+```yaml
+profiles:
+  - id: example-staging
+    name: Example (staging)
+    env: staging
+    baseURL: https://staging.example.com
+    account: qa@example.com
+    tags: [core, us]
+    email: false
+    startPath: /app/home
+    sessionCheckPath: /settings
+    sessionCheck:
+      loggedOutUrl: /login
+      loggedInSelector: "input[name='username']"
+      timeoutMs: 5000
+```
+
+## Fields
+
+| Field | Meaning |
+|---|---|
+| `id` | Lowercase words with single dashes. It names the Playwright project, the saved session (`.auth/<id>.json`) and the baseline files. |
+| `name` | What people see in the UI and the reports. |
+| `env` | The environment this profile points at (`production`, `staging`, ...). `--env <env>` selects the profiles of one environment. Any environment except `staging` protects writing: a case that writes there needs a person's confirmation on every run. |
+| `baseURL` | The site address, without a path. Must be a full `http(s)` URL. |
+| `account` | A label for humans (a mailbox or username). Never a password: logins live in `.auth/`. |
+| `tags` | Optional lowercase words, for grouping and `pnpm asrun --tag <tag>`. Duplicates are refused. |
+| `email` | `true` only when a real mailbox is connected, so tests may send email. Defaults to `false`; `true` is refused for `production`. |
+| `startPath` | The page "Visit" opens after a login, for example `/app/home`. Empty (the default) opens the site root. A path on the site: one leading `/`, no spaces, never another host. |
+| `sessionCheckPath` | A page a signed-in visitor sees (default `/account/`). "Verify" and the pre-run check use it to tell whether a saved login still works. |
+| `sessionCheck` | How that page shows a missing login. See below. |
+
+Expected values are **not** here. They live in each case's `## Values` block: `profiles.yaml` holds connection
+settings only, so adding a profile never touches a case and two profiles can never fight over one case's values.
+
+## There is no default environment
+
+`pnpm asrun` and every AI command require `--env <env>`; the Run tests page requires one radio button. A run selects
+the profiles whose `env` matches.
+
+`pnpm signin <profile-id>` and `pnpm explore <profile-id>` take no `--env`: the profile already names its environment.
+
+## Logins
+
+Sessions are saved per profile in `.auth/<profile-id>.json`, one file per profile, and are as sensitive as passwords.
+
+```bash
+pnpm signin example-staging
+```
+
+A normal browser opens with a small card in its bottom-left corner. Log in yourself, including 2FA, wait for the
+logged-in page, then press **Done, save the session** on the card (or press Enter in the terminal, which does the
+same). The session is saved and verified. Nothing about 2FA is automated.
+
+`pnpm status` shows the login state of every profile; `pnpm status --env staging` only of one environment.
+
+Before every run, `pnpm asrun` checks the session of each profile in the chosen environment. A profile without a
+saved session, or with an expired one, fails right away (no retries) and the run prints what to do:
+
+```
+Not logged in (tests for these profiles will FAIL):
+  example-production           expired  -> pnpm signin example-production
+Or skip them for this run:  pnpm asrun --env production --skip-profile example-production
+```
+
+Either log in or leave the profile out (`--skip-profile`, or `--logged-in` to keep only the working ones). If a
+session expires in the middle of a run, the failed test is marked "session expired".
+
+Login itself is not a test case. Never write a spec for the login page or the login flow.
+
+### Making the session check fit your site
+
+The defaults fit a site that redirects a signed-out visitor to `/login`. Sites differ: a single-page app redirects
+after it has started, some answer `401` or `403`, some show the login form at the same address. `sessionCheck` names
+what your site does:
+
+| Key | What it says |
+|---|---|
+| `loggedOutUrl` | Where a signed-out visitor ends up (default `/login`): a path on the site or a full URL for single sign-on. A `401`/`403` response counts too. |
+| `loggedInSelector` | A selector that only exists while signed in, for example `"input[name='username']"`. |
+| `loggedOutSelector` | A selector that proves the visitor is signed out, for example the password field of a login form shown at the same address. |
+| `timeoutMs` | How long to wait for one of those signals (default 3000, 500–60000). |
+
+Without a `loggedInSelector`, "not sent to the login page" counts as signed in, which can mislead on a slow
+single-page app.
+
+## Visit and explore
+
+**Visit** (Profiles page, or `pnpm explore <profile-id> [path]`) opens a logged-in browser window at the profile's
+`startPath`, or at the site root when it is empty. Files downloaded in that window go to `~/Downloads` (an existing
+file is never overwritten; a ` (1)` is added) and the saved path is printed in the terminal or the job log.
+
+Use it when you need to see what a logged-in person sees, without writing anything. The exploring agent uses the same
+mechanism, with the Playwright MCP server and the profile's project.
+
+## Adding a profile
+
+1. Add an entry to `profiles.yaml` (or use **Add a new profile** on the Profiles page, which appends it for you).
+2. `pnpm signin <id>` and log in.
+3. Add the values for that profile to the cases it runs: a column in each `## Values` block, or nothing when
+   `default` already fits.
+
+Deleting a profile removes its entry and its saved login; screenshot baselines and old reports keep the id in their
+file names and stay on disk. Duplicating one copies the settings under a new id and does **not** copy the saved login.
+
+## How a profile becomes a test
+
+The profile id is the Playwright project name. The `profile` fixture exposes the running profile to a spec:
+
+```ts
+// case: cases/example.md
+import {caseTags} from '@asrunjs/asrun/cases';
+import {configureCase, expect, test} from '@asrunjs/asrun/fixtures';
+import {requireValues} from '@asrunjs/asrun/values';
+
+test.describe('Example', {tag: caseTags('example')}, () => {
+  configureCase('example');
+  test('one outcome', async ({page, profile}) => {
+    // profile.id, profile.env, profile.baseURL, profile.account, profile.tags, profile.email
+    const expected = requireValues<{homeTitle: string}>('example', profile);
+    await test.step('1. Open the home page', async () => {
+      await page.goto('/');
+      await expect(page).toHaveTitle(expected.homeTitle);
+    });
+  });
+});
+```
+
+Expected values come from the case document through `requireValues(caseId, profile)`: its `## Values` block with
+`default` deep-merged under the profile's own entry. A case with no values for the running profile, or with empty or
+`TODO` values, fails with a plain-language message instead of a crash.
+
+See [cases.md](./cases.md) for the document format and [commands.md](./commands.md) for the run filters.

package/docs/troubleshooting.md

@@ -0,0 +1,101 @@
+# Troubleshooting
+
+## Login
+
+**`Profile "x" is not logged in`** — run `pnpm signin <profile-id>` and log in. To leave that profile out instead:
+`pnpm asrun --env <env> --skip-profile <profile-id>`, or `--logged-in` to keep only the working ones. Login itself is
+never a test; a missing or expired session fails right away, without retries.
+
+**A saved session expires in the middle of a run** — the failed test is marked "session expired". Log in again and
+rerun.
+
+**`pnpm signin` opened a browser but nothing was saved** — the session is saved when you press **Done, save the
+session** on the card in the bottom-left corner of that window (or press Enter in the terminal). Nothing about 2FA is
+automated.
+
+## Running
+
+**`Choose the environment to test`** — there is no default. Add `--env production` or `--env staging`; the Run tests
+page needs one radio button.
+
+**A case is skipped, not failed** — a case that writes data runs only in the environments under `writes`; a case with
+`envs` runs only there. The run prints "skipped" with the reason.
+
+**`This case writes data and has no permission to run in PRODUCTION`** — a person confirms production writes on every
+run (type the environment name, or use the dialog in the web UI). `--read-only` leaves the write cases out. Unattended
+runs use `--allow-writes=<env>`; AI agents must not.
+
+**`--update-baselines` was refused** — the named cases must be among the cases the filters run, and cannot be combined
+with Playwright's own `--update-snapshots`.
+
+**The report is empty or missing** — run `pnpm asrun --env <env>` first. `pnpm report` opens `reports/latest`.
+
+**Screenshot mismatch** — open the report: the diff view shows expected, actual and diff. If the change is intended,
+update the baseline on purpose ([commands.md](./commands.md#baselines)); if not, fix the spec or the product. Never let
+an agent overwrite a baseline to hide a difference.
+
+**Videos are separate per tab, or there is no merged video** — ffmpeg is missing. `pnpm go` tries to install it
+(Homebrew, winget); on Linux run `sudo apt install ffmpeg`. Without it, the optional `ffmpeg-static` package is used;
+if neither works, the report lists the recordings separately.
+
+**Downloads did not arrive** — files downloaded in a **Visit** window (the UI) or with `pnpm explore` are saved to
+`~/Downloads` and never overwrite an existing file; the saved path is printed in the job log or terminal.
+
+**The UI port is busy** — set `ASRUN_UI_PORT` (and `ASRUN_UI_WEB_PORT` for `pnpm ui:dev`).
+
+## Cases and specs
+
+**`Missing values: cases/<id>.md has no "## Values" for profile ...`** — add the profile's values (or a `default`
+entry) to the case's `## Values` block. See [cases.md](./cases.md#values).
+
+**`Incomplete values: ... still has empty or TODO values`** — fill in the named keys, or answer the `TODO` in the case
+and regenerate the spec.
+
+**`pnpm case:check` fails on a target card** — the card is missing a required field (`What`, `Where`,
+`Identified by`), refers to a reference image outside `.explore/targets/<case-id>/`, or a check refers to a `[T<n>]`
+that has no card. A blocking question (`🚫 TODO [blocking]`) is the normal way to wait for a person's answer.
+
+**`pnpm spec:lint` fails** — read the rule name in the message: `no-sleep` (`waitForTimeout`), `no-networkidle`,
+download handling, a screenshot or image check without `// target: T<n>`, a PDF check on a magic number alone. The
+fixes are in the framework's `generating-specs` conventions; do not silence the rule.
+
+**A case step marked `[input]` or `[writes]` stops `/gen-spec` with `needs-input`** — that step has no
+`- Recipe:` line. Run `/explore-case <case-id> <env> --attended` and do the step in the browser once, so the recipe
+is recorded.
+
+**`pnpm case:check` warns that a reference image is not on this machine** — `.explore/` is git-ignored: a fresh
+checkout has the card but not the screenshot. Run the exploration again on this machine (or look at the card and the
+report's baseline).
+
+## AI steps
+
+**An AI command says the `playwright-test` MCP server is missing** — run `pnpm asrun doctor`. OpenCode reads only
+`opencode.jsonc`; Claude Code reads only `.mcp.json`. `pnpm asrun init` writes both. Check with `opencode mcp list` /
+`claude mcp list`; `failed: ... path specified` means the `playwright` path in that file does not resolve (repair it
+with `pnpm asrun init --force <file>`).
+
+**An AI job runs but uses a slow or limited model** — the top bar's **Model** picker sets the model for UI runs;
+without one, a one-shot OpenCode run uses its built-in free model, which has a daily usage limit. Set `"model"` in
+`opencode.jsonc` to stop depending on the browser's choice. For Claude Code, the picker lists what its settings,
+environment, aliases or gateway expose.
+
+**Thinking does nothing** — it is an OpenCode flag. Claude Code has no such flag; its model and settings decide.
+
+**A project rule does nothing** — `AGENTS.md` §2 needs the rule id and an `Effect` of `narrows` or `replaces`.
+`F1`..`F6` cannot be changed. `pnpm asrun doctor` names a wrong id, a missing `Effect` or a non-negotiable rule.
+
+**A skill override does nothing** — it must be `.claude/skills/<skill>.md` (the skill name, for example
+`generating-specs`, not the command name), and it is not discovered as a standalone skill: the command and the skill
+read it. `doctor` lists the overrides it sees.
+
+**`pnpm asrun init --force AGENTS.md` is refused** — `AGENTS.md`, `CLAUDE.md` and `.claude/skills/**` belong to the
+project. Add `--reset-rules` to replace them with the template, and expect to lose the project's rules.
+
+**`ERR_PNPM_IGNORED_BUILDS` while installing** — pnpm refused the build scripts of `esbuild` / `ffmpeg-static`. Run
+`pnpm dlx @asrunjs/asrun init` first (it writes the `allowBuilds` entry), or add it to `pnpm-workspace.yaml` by hand;
+see [install.md](./install.md#manual-install).
+
+**The AI did something you did not expect** — exploring and generating only read pages and edit the case file; healing
+edits the spec and runs it under the same write gate as any run (staging writes are allowed, any other environment
+needs a person's confirmation). None of them writes product data on its own, and none updates a baseline. If a step
+needs a person to write, run it with `--attended`; that is where a person acts, in the browser.