@asrunjs/asrun 0.5.2 → 0.6.0

package/docs/agents/framework-dev.md

@@ -4,26 +4,50 @@ Read `AGENTS.md` first: it is the product baseline, and this file only adds how
 is relevant to a project that uses asrun as a dependency.
 
 ## Framework layout
+
 `<framework>` for a project is `node_modules/@asrunjs/asrun`. In this repository it is the root folder:
-- `lib/`              fixtures (`profile`, session guard) and assertion helpers; specs import them as
+
+- `lib/`              fixtures (`profile`, session guard, write gate) and helpers; specs import them as
                       `@asrunjs/asrun/<module>` (for example `@asrunjs/asrun/fixtures`, `@asrunjs/asrun/values`)
-- `scripts/`          user-facing commands, see README.md
+- `scripts/`          the user-facing commands; every command and flag is documented in `docs/commands.md`
 - `templates/`        the files `pnpm asrun init` writes into a workspace
 - `ui/`               local web UI (`pnpm ui`). It may only run the fixed actions in `ui/server/actions.ts`
                       and must never serve anything under `.auth/`.
-- `docs/theme-guide.html` the Inkstone theme guide of the web UI: color tokens, buttons, badges, icons, surfaces
+- `docs/`             user documentation (`install.md`, `profiles.md`, `cases.md`, `ai-workflow.md`,
+                      `commands.md`, `web-ui.md`, `troubleshooting.md`) and `docs/theme-guide.html`
+- `docs/agents/`      documents for AI agents: this file, and `case-format.md` (the case document contract)
 - `examples/demo/`    a workspace for developing the framework itself against a local Docker stack (Conduit);
                       it is committed (`.auth/` and `reports/` never are), see its README
+- `.claude/`          skills + slash commands for Claude Code; the skills are shared with OpenCode
+- `.opencode/commands/` the same commands for OpenCode (it does not read `.claude/commands`)
+- `AGENTS.md`         the product baseline rules (OpenCode reads it); `CLAUDE.md` imports it for Claude Code
+- `README.md`         the user-facing overview: what it does, install, first test, cookbook, links to `docs/`
+
+`package.json` `files` ships `README.md`, `AGENTS.md`, `CLAUDE.md`, `docs/`, `templates/`, `.claude/`, `bin/`,
+`dist/` and `ui/dist/`, so a project can read the same documentation from
+`node_modules/@asrunjs/asrun/docs/`.
 
 ## Working on the framework itself
+
 - The framework repository holds no workspace content at the root: no `profiles.yaml`, `cases/`, `tests/` or
   reports there. The one workspace is `examples/demo`, which is committed because it runs its own local site; its
-  `.auth/`, `reports/` and other run output are not. Develop against it: `pnpm demo:up` and `pnpm demo:seed` start
-  and fill the local stack, `pnpm asrun init --root examples/demo` (it also writes the framework's `.env` with
-  `ASRUN_ROOT=examples/demo`), then `pnpm asrun --env staging --read-only`.
+  `.auth/`, `reports/` and other run output are not.
+- Develop against the demo:
+
+  ```bash
+  pnpm demo:up                                  # build and start the local stack
+  pnpm demo:seed                                # accounts, articles, follows, favorites
+  pnpm asrun init --root examples/demo          # also writes the framework's .env (ASRUN_ROOT=examples/demo)
+  pnpm build                                    # the demo's specs import the package, which resolves to dist/
+  pnpm asrun --env staging --read-only
+  ```
+
+  `pnpm demo:reset` deletes the database and seeds it again; logins must be redone afterwards. Demo accounts are in
+  `examples/demo/README.md`.
 - Everything the framework reads for a project goes through `ROOT` in `lib/paths.ts` (the workspace root); its own
   assets (templates, docs, skills, its `node_modules`) go through `FRAMEWORK_ROOT`. Never write into
   `FRAMEWORK_ROOT` at run time.
+- After changing `lib/`, run `pnpm build` before exercising the demo's specs.
 - `templates/` is the source of the files a workspace gets. When a template changes, bump `version` in
   `package.json` so `pnpm asrun doctor` in a project shows that it is behind.
 - `init` owns two lists: `GENERATED` (rewritten by `--update`; the commands and the Playwright files) and `ONCE`
@@ -33,7 +57,51 @@ is relevant to a project that uses asrun as a dependency.
 - A project's rules never flow back here. The framework reads a workspace only through `ROOT` at run time; nothing
   under `templates/` or `.claude/skills/` is generated from a project.
 
+### Installing this repository as a Git dependency (private)
+
+The npm package is the public channel for users. This repository is private, so a Git dependency works only on a
+machine that can clone it:
+
+```bash
+pnpm add -D github:wizcas/asrun#<tag>
+```
+
+pnpm 12 resolves a GitHub spec through the canonical HTTPS URL, not SSH. That machine therefore needs HTTPS
+credentials (a credential helper or a token), or a rewrite to SSH:
+
+```bash
+git config --global url."git@github.com:".insteadOf https://github.com/
+```
+
+On CI, give the runner a `GITHUB_TOKEN`, for example:
+
+```bash
+git config --global \
+  url."https://x-access-token:${GITHUB_TOKEN}@github.com/".insteadOf "https://github.com/"
+```
+
+or a deploy key with the SSH rewrite above. A Git install also runs the package's `prepare` (it builds `dist/` and
+`ui/dist/`), so it is slower than the registry: use it only to pin a commit, a branch or a tag that is not published
+yet. For a one-off change, `pnpm patch @asrunjs/asrun` and commit the patch instead.
+
+## Documentation
+
+The split is intentional; keep it:
+
+- `README.md` — the user's first page: what AsRun does, requirements, install, the first test, customizing the
+  prompts, the every-day cookbook, safety in short, a documentation index, maintainer notes. It should stay readable
+  in one sitting; a section that grows past a screen belongs in `docs/`.
+- `docs/*.md` — the user reference. `docs/commands.md` is the only place that lists every command and flag.
+- `docs/agents/*.md` — for AI agents. `case-format.md` is the contract of the case document (fixed tokens, values,
+  targets); `AGENTS.md` references it, and the template `AGENTS.md` does too.
+
+When behavior changes, update the matching document in the same change. A command or flag goes into
+`docs/commands.md` and, if it is a daily one, into the README cookbook. A change to the case format goes into
+`docs/agents/case-format.md` and `docs/cases.md` together. Keep the relative links working and the fixed tokens
+spelled exactly as the parser reads them.
+
 ## The commands and the two agent CLIs
+
 - Claude Code reads `.claude/commands/*` and `.claude/skills/<name>/SKILL.md`.
 - OpenCode reads `.opencode/commands/*`, `.claude/skills/<name>/SKILL.md`, `.opencode/skills/<name>/SKILL.md` and
   `.agents/skills/<name>/SKILL.md`. It does **not** read `.claude/commands`, and it does **not** read a flat
@@ -46,8 +114,10 @@ is relevant to a project that uses asrun as a dependency.
   plain file read. That is why the skill itself must read the project override (`.claude/skills/<skill>.md`).
 
 ## Web UI (`ui/web`)
+
 Before adding or changing any UI element, read `docs/theme-guide.html` (open the file; it is static HTML) and follow it.
 Its rules are binding, in particular:
+
 - Icons: Feather via the `react-feather` package only (`import {ChevronDown} from 'react-feather'`). Never draw, paste
   or hand-write SVGs, and never add another icon library. Size 14 in buttons, 16-20 elsewhere; decorative icons get
   `aria-hidden="true"`, icon-only buttons get an `aria-label`. Do not use Unicode symbols (`▲ ▼ ◀ ▶ ⤢`) as icons.
@@ -59,6 +129,9 @@ Its rules are binding, in particular:
   `ui/web/src/components/search-select.tsx`: an input with a filtered list below it, which a native `<select>` cannot
   do. It keeps `Select`'s height, border and focus ring, so the two look like one family; do not build a third variant.
 - If a change adds or alters a token, update `ui/web/src/index.css` and `docs/theme-guide.html` together.
+- The Help page ("How to start") shows screenshots from `ui/web/public/help/`: retake one when the page it shows
+  changes.
+
 Before reaching for a new dependency or writing a helper component, grep `package.json` and `ui/web/src` for what the
 project already uses.
 
@@ -77,3 +150,18 @@ Every lead, label and tooltip is written for the person using the UI, never for
   `CopyBlock`, or a folded `<details>` block titled "For the command line".
 - **Say what the user sees.** "The run appears in the Jobs bar", not "the command runs in a one-shot session"; "the
   browser shows a small card", not "the agent pauses on a `writes` step".
+
+## Before you open a pull request
+
+```bash
+pnpm typecheck
+pnpm build          # dist/ must match lib/ and scripts/
+pnpm case:check     # examples/demo cases
+pnpm spec:lint      # examples/demo specs
+pnpm ui:build       # ui/dist/ must match ui/web and ui/server
+```
+
+- `pnpm build` and `pnpm ui:build` also run from `prepare` and `prepack`, so a published package is complete.
+- Bump `version` when `templates/` or the shipped docs change; `pnpm asrun doctor` in a project compares it.
+- Keep the demo's committed expectations (`profiles.yaml`, `cases/`, `tests/`, baselines) in step with the demo site.
+  Baselines are a person's decision: never let an agent regenerate them.

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.