@asrunjs/asrun 0.2.0 → 0.5.2

package/.claude/skills/making-cases/references/writes-and-email.md

@@ -1,36 +1,37 @@
-# Steps that write data or send email
-
-## Classify every step
-| Class | Looks like | Marker |
-|---|---|---|
-| read-only | open, look, read, hover, switch tab or filter, open a preview, close a modal | none |
-| writes | create, save, edit, publish, share, delete, upload, accept, assign a label, change a setting | `[writes]` |
-| input | a step that needs a person's choice or typed value (an existing document, items, a contact name), writing or not | `[input]` |
-| email | any step that makes the product send an email or notification (share by email, send to a recipient, invite a collaborator) | `[email]` |
-
-A step can be several of these (a step that picks items and saves is `[input] [writes]`). A step is not read-only because the notes did not say it changes something: "Share" opens a
-dialog (read-only) but sending the share is `[writes]` and probably `[email]`. When in doubt, mark it and ask.
-
-## What a case with writes must look like
-- Front matter: `writes: [<env>, ...]`, the environments the finished spec may write in (`[staging]`; add `production`
-  only when the notes or the user say so), and a `writes-note` that says what is created, changed and removed, in one
-  sentence ("Creates one draft document named '[asrun] ...', publishes it, deletes it at the end").
-- A `## Data` section: what is created, its name, and how it is removed.
-- Everything created is named `[asrun] <something>` (the spec enforces this).
-- The case ends by deleting what it created. If the notes do not say how to delete it, that is a gap: ask, and
-  never guess a delete path. Until it is known, write the likeliest path as a sentence in Data ("Removal: the
-  "Delete" option of the item's menu on the list page.") with a `TODO [blocking]: How is <thing> deleted?` block
-  under it (see `gaps.md`).
-- The case needs only data of the test account of the profile. It never touches data that existed before.
-- Do not set `envs` just because a case writes. A case that does not list an environment under `writes` is skipped
-  there with a notice (not failed), and a human confirms a run in any environment except staging. When unsure, write
-  `writes: [staging]`.
-- The agent never performs a write step while making, exploring or generating: a person does it in
-  `/explore-case --attended`, which records a general recipe under `## Inputs`. Here, only mark the step.
-- Email: steps marked `[email]` are skipped by the runner in production and for profiles whose `email` is false.
-  Write the case so that skipping them does not break the following steps, or say in Notes that it does.
-
-## Non-linear flows
-Real flows often leave and come back (create a draft, stop before Publish, return to the list, check the draft,
-edit it again, publish). Write them as one case with the steps in the real order, including the "return to the
-list" steps. Do not split a flow only because it is long.
+# Steps that write data or send email
+
+## Classify every step
+| Class | Looks like | Marker |
+|---|---|---|
+| read-only | open, look, read, hover, switch tab or filter, open a preview, close a modal | none |
+| writes | create, save, edit, publish, share, delete, upload, accept, assign a label, change a setting | `[writes]` |
+| input | a step that needs a person's choice or typed value (an existing document, items, a contact name), writing or not | `[input]` |
+| email | any step that makes the product send an email or notification (share by email, send to a recipient, invite a collaborator) | `[email]` |
+
+A step can be several of these (a step that picks items and saves is `[input] [writes]`). A step is not read-only because the notes did not say it changes something: "Share" opens a
+dialog (read-only) but sending the share is `[writes]` and probably `[email]`. When in doubt, mark it and ask.
+
+## What a case with writes must look like
+- Front matter: `writes: [<env>, ...]`, the environments the finished spec may write in (`[staging]`; add `production`
+  only when the notes or the user say so), and a `writes-note` that says what is created, changed and removed, in one
+  sentence ("Creates one draft document named '[asrun] ...', publishes it, deletes it at the end"). The `writes-note`
+  is the only summary; there is no separate Data section, and the removal itself is a step in `## Steps`.
+- Everything created is named `[asrun] <something>` (the spec enforces this).
+- The case ends by deleting what it created. If the notes do not say how to delete it, that is a gap: ask, and
+  never guess a delete path. Until it is known, write the likeliest delete step ("Select the 'Delete' option of the
+  item's menu on the list page.") and put a `TODO [blocking]: How is <thing> deleted?` block under that step (see
+  `gaps.md`).
+- The case needs only data of the test account of the profile. It never touches data that existed before.
+- Do not set `envs` just because a case writes. A case that does not list an environment under `writes` is skipped
+  there with a notice (not failed), and a human confirms a run in any environment except staging. When unsure, write
+  `writes: [staging]`.
+- The agent never performs a write step while making, exploring or generating: a person does it in
+  `/explore-case --attended`, which records a general recipe under that step as `- Recipe (phase): ...`. Here, only
+  mark the step.
+- Email: steps marked `[email]` are skipped by the runner in production and for profiles whose `email` is false.
+  Write the case so that skipping them does not break the following steps, or say in Notes that it does.
+
+## Non-linear flows
+Real flows often leave and come back (create a draft, stop before Publish, return to the list, check the draft,
+edit it again, publish). Write them as one case with the steps in the real order, including the "return to the
+list" steps. Do not split a flow only because it is long.

package/AGENTS.md

@@ -1,154 +1,159 @@
-# AsRun — framework baseline
-
-This file is the binding baseline for every project that uses the AsRun framework, and for the framework itself.
-Its hard rules carry ids (`F1`..`F10`, `B1`..`B4`, `A1`..`A6`). A project may narrow one of them in its own
-`AGENTS.md` by naming the id; rules tagged `[non-negotiable]` may not be narrowed (`pnpm asrun doctor` checks it).
-
-Paths are relative to the **workspace root**: the project that owns `profiles.yaml`, `cases/` and `tests/`. In a
-project that uses asrun, the framework files are in `node_modules/@asrunjs/asrun` (an installed dependency: never edit it).
-`<framework>` below means that folder (`node_modules/@asrunjs/asrun` in a project, `.` in the framework repository).
-
-## Hard rules
-- **F1 — Read-only by default.** [non-negotiable] Tests never create, edit, delete, submit forms that change data,
-  send messages, or accept terms. Only a case that lists environments under `writes` in its front matter
-  (`writes: [staging]`, `writes: [staging, production]`; with a `writes-note`) may write, only in those environments,
-  and only data of the test accounts, which it must clean up. In any other environment the case is skipped with a
-  notice, not failed. The `writes` environments must be ones that `envs` lets the case run in. The permission is
-  checked at run time.
-- **F2 — No bypassing the write confirmation.** [non-negotiable] A case that writes in any environment except staging
-  needs a human's confirmation on every run (typing the environment name in the CLI, or the confirm dialog in the web
-  UI). AI agents must NEVER add `--allow-writes`, set `ASRUN_ALLOW_WRITES`, or bypass the confirmation. Use
-  staging, or `--read-only`, instead.
-- **F3 — Agents never write while exploring.** [non-negotiable] A step that creates, edits, publishes, shares or
-  deletes, and a step that needs a person's choice, is done by the person in the browser window
-  (`/explore-case --attended`, see `<framework>/.claude/skills/exploring-cases/references/user-handoff.md`). The
-  agent only reads. Without `--attended` an agent never waits for a person.
-- **F4 — No email in production.** [non-negotiable] Never send email from a test in production. In other
-  environments only if the profile has `email: true`; new and AI-generated profile entries always get `email: false`.
-- **F5 — Saved logins are passwords.** [non-negotiable] Never read, print, copy or commit anything under `.auth/`.
-- **F6 — No 2FA automation.** [non-negotiable] Login is always done by a human via `pnpm signin <profile-id>`.
-- **F7 — No default environment.** `--env <env>` is required by `pnpm asrun` and by every AI command.
-  `pnpm signin <profile-id>` and `pnpm explore <profile-id>` need no `--env`: the profile already names its
-  environment. Sessions are saved per profile in `.auth/<profile-id>.json`.
-- **F8 — Login is not a test case.** `pnpm asrun` checks the session of every profile first; a profile that is not
-  logged in (missing or expired token) fails right away with a hint to run `pnpm signin <profile-id>` or to skip it
-  with `--skip-profile <profile-id>`. Never write specs for the login page or login flow.
-- **F9 — Expected values live in the case document.** They go in its `## Values` block, never in `profiles.yaml`. A
-  profile holds connection settings only; adding or changing a profile must not touch any case value.
-- **F10 — Write in English.** Code, comments, docs, case files and commit messages. A Chinese version is only written
-  when the user explicitly asks for one.
-
-## Browser exploration rules (`B`)
-These apply to every agent that drives a browser to explore pages for cases or specs (`making-cases`,
-`exploring-cases`, `generating-specs`, the `playwright-test` MCP).
-- **B1 — Read-only for the agent.** Open, look, read, hover, switch tabs, open and close dialogs and menus.
-  Everything that writes is the person's (see F3).
-- **B2 — Waiting for a person.** Only in an attended run. Announce the task in the browser window (a small draggable
-  card with a Done button and click-to-copy for texts to type), name the finish condition, wait, and tell the person
-  when control is back. Record what they did as a general recipe in the case's `## Inputs` section: positions instead
-  of names of data that can change.
-- **B3 — Closing an email composer.** When closing an email composer makes a confirm dialog appear (for example
-  "Discard draft?"), choose "Discard" and continue. Never choose "Save" or "Send"; closing the composer must not keep
-  or send anything. The dialog can show up late: in a spec, clicking "Discard" and checking that the composer is
-  closed happen in one retry loop (`clickOptionalUntilHidden` in `@asrunjs/asrun/ready`), never after a single
-  `isVisible()` look.
-- **B4 — Record it in the case.** If the case file does not already contain this step, do not edit the flow silently.
-  Add it to the case as a step with a `❓ TODO [non-blocking]` block for the user's confirmation, in the format of
-  `<framework>/.claude/skills/exploring-cases/references/open-questions.md`, for example:
-  ```
-  4. Close the email composer; if a confirm dialog appears, choose "Discard".
-     - ❓ TODO [non-blocking]: Is choosing "Discard" in the close-composer confirm dialog correct for this case? (seen while exploring <profile-id>)
-       - ✍️ Answer:
-  ```
-  Put the step right after the step that opens the composer (or after the last step that uses it). Mention it in the
-  final report so the user can confirm it. If the case already has the step, just follow it and add nothing.
-
-## Assertions and readiness (`A`, binding for exploring, generating and healing)
-Details: `<framework>/.claude/skills/exploring-cases/references/assertion-targets.md` and `readiness.md`.
-- **A1 — Never guess what a check looks at.** A check on a logo, image, icon, file, PDF, screenshot or repeated text
-  names its exact target in a card in the case (`## Targets`: What, Where, Identified by, Not, Ready when, a
-  highlighted reference screenshot, referenced as `[T<n>]`). When in doubt (several candidates, only a position or a
-  generic locator, dynamic data in the area, no stable identity, the page differs from the case, it could not be
-  seen), write a `🚫 TODO [blocking]` that names the exact image, text, place or UI wanted and lists the candidates.
-  Do not pick. Look at the screenshot you saved: it must show what the card says.
-- **A2 — Wait for the content before you read it.** After every action that loads something, wait for its key
-  requests to finish and for a positive content signal, then read. The same in exploration
-  (`browser_network_requests`, `browser_wait_for`), in specs (`actAndWait` in `@asrunjs/asrun/ready`) and in healing. A
-  "missing", "empty" or "hidden" result is only valid after a positive ready signal. Never `waitForTimeout`, never
-  `networkidle`.
-- **A3 — Verify every download in five parts** with `verifyDownload` (`@asrunjs/asrun/downloads`): starts, finishes, file
-  exists, file is valid, and any failure or timeout fails the whole step.
-- **A4 — A PDF is read like a person reads it.** Its pages are rendered to images (logo regions must not be blank and
-  match the profile's baseline, 2%) and its text is extracted (`expectPdf` in `@asrunjs/asrun/pdf`; `pnpm pdf:render`
-  while exploring). Every page is checked unless the case limits the pages in strong words ("only", "exactly",
-  "must"); "should", "always", "usually" and no wording at all mean every page.
-- **A5 — No hard assertion on what nobody saw on a page.** Specs are checked with `pnpm spec:lint`; baselines with
-  `pnpm baselines:review` (open every new image and compare it with its card).
-- **A6 — Observe first, delete last.** Everything that needs the data (preview, share menus, composers, downloads)
-  is observed before the person deletes it.
-
-## Layout
-
-**The workspace** (committed by the project; the framework never holds these):
-- `cases/**/*.md`     human-written test cases (input of the AI workflow); `cases/<group>/<name>.md` groups an area
-- `tests/**/*.spec.ts` generated Playwright specs (output of the AI workflow), one per case, same folder as the case,
-  with their `*-snapshots/` baselines next to them
-- `profiles.yaml`       one entry per environment: URL, account label, tags, environment (connection settings only)
-- `.auth/` `reports/` `.tmp/` `.explore/`  local state, never committed
-
-**The framework** (this folder; read-only in a project that uses it, as `node_modules/@asrunjs/asrun/`):
-- `lib/`              fixtures (`profile`, session guard) and assertion helpers; specs import them as
-                      `@asrunjs/asrun/<module>` (for example `@asrunjs/asrun/fixtures`, `@asrunjs/asrun/values`)
-- `scripts/`          user-facing commands, see README.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
-- `examples/demo/`    a local workspace for developing the framework itself (not test content)
-
-## 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.
-- Colors: only the tokens in `ui/web/src/index.css` (the default Tailwind palette is removed). Pick the color by impact.
-- Buttons and badges: use `buttonClass()` and `Badge` from `ui/web/src/components/status.tsx`, never hand-style them.
-- Dropdowns: use `Select` from the same file, never a bare `<select>` or hand-copied classes (native arrow and height
-  differ). A required dropdown that is empty gets `invalid` (red). See the "Dropdowns" section of the theme guide.
-- If a change adds or alters a token, update `ui/web/src/index.css` and `docs/theme-guide.html` together.
-Before reaching for a new dependency or writing a helper component, grep `package.json` and `ui/web/src` for what the
-project already uses.
-
-## Workflow
-Three steps, each learns one thing: the intent, the facts and inputs, the implementation.
-1. `making-cases` (or `/make-case <notes>`) turns raw notes into case documents. It writes `cases/*.md` only and
-   never opens a browser. Check them with `pnpm case:check`.
-2. `exploring-cases` (or `/explore-case <case-id> <env> [--attended]`) explores the real pages for one case. It
-   edits that case file only: wording, observations, TODO blocks, and, with `--attended`, a `## Inputs` recipe of
-   what the person did for the steps that write or need a choice.
-3. `generating-specs` (or `/gen-spec <case-id> <env>`) turns the case into a spec. It replays the case and its
-   `## Inputs` and `## Values`, writes the spec (values stay in the case document), but never runs the tests, never
-   writes data and never creates baselines. A case with an `[input]` step that has no `## Inputs` recipe stops with
-   `needs-input`: run `/explore-case` first. Running specs is a separate step (`pnpm asrun`, or the Run page).
-Do not hand-write specs unless asked. Do not edit `lib/` to make a single spec pass.
-Every case step is wrapped in `test.step('<n>. <case step text>', ...)` so reports and traces show the
-case's own steps (see the skill's `references/conventions.md`).
-Every AI command needs an environment (`--env`/`<env>`); there is no default and no "no environment" mode.
-`/heal-spec <case-id> <env>` reads the existing report first (`pnpm heal:evidence --case <id> --env <env>`), reads the
-user's optional clues (`--hints <file>`), runs only the profiles that are logged in (`--logged-in`) and runs the case
-again only when the report is missing, stale or not enough.
-Run `pnpm typecheck`, `pnpm spec:lint <case-id>` and `pnpm case:check` before reporting that a spec was generated. Run
-`pnpm asrun --env <env> --profile <id> --grep <case-id>` only when healing a spec or when asked to.
-Pick `--env staging` while developing. A case that does not list `production` under `writes` is skipped in
-production with a notice; add `--read-only` to leave all write cases out.
-
-## Working on the framework itself
-- The framework repository holds no workspace content: no `profiles.yaml`, `cases/`, `tests/` or reports at the root.
-  Develop against `examples/demo`: `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`.
-- 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.
-- `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.
+# AsRun — framework baseline
+
+This file is the binding baseline for every project that uses the AsRun framework. It describes no particular
+product: a project adds its own rules in its own `AGENTS.md` §2, and they win where they differ (see "Precedence").
+Its hard rules carry ids (`F1`..`F10`, `B1`..`B4`, `A1`..`A6`).
+
+Paths are relative to the **workspace root**: the project that owns `profiles.yaml`, `cases/` and `tests/`. In a
+project that uses asrun, the framework files are in `node_modules/@asrunjs/asrun` (an installed dependency: never edit it).
+`<framework>` below means that folder (`node_modules/@asrunjs/asrun` in a project, `.` in the framework repository).
+
+## Precedence
+
+Rules are applied in this order; a later layer wins where they conflict.
+1. **F1–F6: safety.** Nothing overrides them, in any project. They are enforced in code as well
+   (`lib/write-gate.ts`, `lib/session.ts`, the run filters), so a rule file cannot weaken them.
+2. **This file.** The generic facts and defaults.
+3. **The framework skills** (`<framework>/.claude/skills/**`).
+4. **A project's skill override**: `.claude/skills/<skill>.md` in the workspace, if it exists. It refines that skill's
+   own procedure.
+5. **The project's `AGENTS.md` §2 (Project rules).** It states the project's intent and wins over layers 2–4.
+
+A project writes §2 only for what differs from the defaults here, names the rule id, and says whether it `narrows` or
+`replaces` the rule. `replaces` is refused for F1–F6; `pnpm asrun doctor` checks the table. A rule file never renames
+the structural tokens under "Fixed tokens".
+
+## Hard rules
+- **F1 — Read-only by default.** [non-negotiable] Tests never create, edit, delete, submit forms that change data,
+  send messages, or accept terms. Only a case that lists environments under `writes` in its front matter
+  (`writes: [staging]`, `writes: [staging, production]`; with a `writes-note`) may write, only in those environments,
+  and only data of the test accounts, which it must clean up. In any other environment the case is skipped with a
+  notice, not failed. The `writes` environments must be ones that `envs` lets the case run in. The permission is
+  checked at run time.
+- **F2 — No bypassing the write confirmation.** [non-negotiable] A case that writes in any environment except staging
+  needs a human's confirmation on every run (typing the environment name in the CLI, or the confirm dialog in the web
+  UI). AI agents must NEVER add `--allow-writes`, set `ASRUN_ALLOW_WRITES`, or bypass the confirmation. Use
+  staging, or `--read-only`, instead.
+- **F3 — Agents never write while exploring.** [non-negotiable] A step that creates, edits, publishes, shares or
+  deletes, and a step that needs a person's choice, is done by the person in the browser window
+  (`/explore-case --attended`, see `<framework>/.claude/skills/exploring-cases/references/user-handoff.md`). The
+  agent only reads. Without `--attended` an agent never waits for a person.
+- **F4 — No email in production.** [non-negotiable] Never send email from a test in production. In other
+  environments only if the profile has `email: true`; new and AI-generated profile entries always get `email: false`.
+- **F5 — Saved logins are passwords.** [non-negotiable] Never read, print, copy or commit anything under `.auth/`.
+- **F6 — No 2FA automation.** [non-negotiable] Login is always done by a human via `pnpm signin <profile-id>`.
+- **F7 — No default environment.** `--env <env>` is required by `pnpm asrun` and by every AI command.
+  `pnpm signin <profile-id>` and `pnpm explore <profile-id>` need no `--env`: the profile already names its
+  environment. Sessions are saved per profile in `.auth/<profile-id>.json`.
+- **F8 — Login is not a test case.** `pnpm asrun` checks the session of every profile first; a profile that is not
+  logged in (missing or expired token) fails right away with a hint to run `pnpm signin <profile-id>` or to skip it
+  with `--skip-profile <profile-id>`. Never write specs for the login page or login flow.
+- **F9 — Expected values live in the case document.** They go in its `## Values` block, never in `profiles.yaml`. A
+  profile holds connection settings only; adding or changing a profile must not touch any case value.
+- **F10 — Artifact language.** Human-readable artifacts (case prose, report summaries, assertion messages) are
+  written in English by default. A project replaces this in §2 of its own `AGENTS.md` (for example Simplified Chinese
+  for case prose and reports). Code, comments, identifiers, commit messages and the structural tokens under
+  "Fixed tokens" always stay in English.
+
+## Browser exploration rules (`B`)
+These apply to every agent that drives a browser to explore pages for cases or specs (`making-cases`,
+`exploring-cases`, `generating-specs`, the `playwright-test` MCP).
+- **B1 — Read-only for the agent.** Open, look, read, hover, switch tabs, open and close dialogs and menus.
+  Everything that writes is the person's (see F3).
+- **B2 — Waiting for a person.** Only in an attended run. Announce the task in the browser window (a small draggable
+  card with a Done button and click-to-copy for texts to type), name the finish condition, wait, and tell the person
+  when control is back. Record what they did as a general recipe under the step (`- Recipe (phase): ...`): positions
+  instead of names of data that can change.
+- **B3 — Closing an email composer.** When closing an email composer makes a confirm dialog appear (for example
+  "Discard draft?"), choose "Discard" and continue. Never choose "Save" or "Send"; closing the composer must not keep
+  or send anything. The dialog can show up late: in a spec, clicking "Discard" and checking that the composer is
+  closed happen in one retry loop (`clickOptionalUntilHidden` in `@asrunjs/asrun/ready`), never after a single
+  `isVisible()` look.
+- **B4 — Record it in the case.** If the case file does not already contain this step, do not edit the flow silently.
+  Add it to the case as a step with a `❓ TODO [non-blocking]` block for the user's confirmation, in the format of
+  `<framework>/.claude/skills/exploring-cases/references/open-questions.md`, for example:
+  ```
+  4. Close the email composer; if a confirm dialog appears, choose "Discard".
+     - ❓ TODO [non-blocking]: Is choosing "Discard" in the close-composer confirm dialog correct for this case? (seen while exploring <profile-id>)
+       - ✍️ Answer:
+  ```
+  Put the step right after the step that opens the composer (or after the last step that uses it). Mention it in the
+  final report so the user can confirm it. If the case already has the step, just follow it and add nothing.
+
+## Assertions and readiness (`A`, binding for exploring, generating and healing)
+Details: `<framework>/.claude/skills/exploring-cases/references/assertion-targets.md` and `readiness.md`.
+- **A1 — Never guess what a check looks at.** A check on a logo, image, icon, file, PDF, screenshot or repeated text
+  names its exact target in a card in the case (`## Targets`: What, Where, Identified by, Not, Ready when, a
+  highlighted reference screenshot, referenced as `[T<n>]`). When in doubt (several candidates, only a position or a
+  generic locator, dynamic data in the area, no stable identity, the page differs from the case, it could not be
+  seen), write a `🚫 TODO [blocking]` that names the exact image, text, place or UI wanted and lists the candidates.
+  Do not pick. Look at the screenshot you saved: it must show what the card says.
+- **A2 — Wait for the content before you read it.** After every action that loads something, wait for its key
+  requests to finish and for a positive content signal, then read. The same in exploration
+  (`browser_network_requests`, `browser_wait_for`), in specs (`actAndWait` in `@asrunjs/asrun/ready`) and in healing. A
+  "missing", "empty" or "hidden" result is only valid after a positive ready signal. Never `waitForTimeout`, never
+  `networkidle`.
+- **A3 — Verify every download in five parts** with `verifyDownload` (`@asrunjs/asrun/downloads`): starts, finishes, file
+  exists, file is valid, and any failure or timeout fails the whole step.
+- **A4 — A PDF is read like a person reads it.** Its pages are rendered to images (logo regions must not be blank and
+  match the profile's baseline, 2%) and its text is extracted (`expectPdf` in `@asrunjs/asrun/pdf`; `pnpm pdf:render`
+  while exploring). Every page is checked unless the case limits the pages in strong words ("only", "exactly",
+  "must"); "should", "always", "usually" and no wording at all mean every page.
+- **A5 — No hard assertion on what nobody saw on a page.** Specs are checked with `pnpm spec:lint`; baselines with
+  `pnpm baselines:review` (open every new image and compare it with its card).
+- **A6 — Observe first, delete last.** Everything that needs the data (preview, share menus, composers, downloads) is
+  observed before the person deletes it.
+
+## Fixed tokens
+`lib/case-doc.ts`, the scripts and the web panel parse these literals. A project language never translates them, and
+a project rule never renames them.
+- Section headings: `## Goal`, `## Steps`, `## Expected`, `## Values`, `## Visual checks`, `## Targets`, `## Notes`,
+  `## Source` (only when the case was made from notes).
+- A step's recipe lines: `- Recipe (phase): ...` under the step it belongs to.
+- `### T<n>` target cards and the `[T<n>]` references to them.
+- Question blocks: `🚫 TODO [blocking]`, `❓ TODO [non-blocking]`, `✍️ Answer:` (with its emoji), and the markers
+  `🔍 to be confirmed by QA` / `👁️ not observed`.
+- Step tags `[input]`, `[writes]`, `[email]`, and the last line `RESULT: ready` / `RESULT: needs-input`.
+- Front-matter keys: `id`, `title`, `login`, `suites`, `writes`, `writes-note`, `envs`.
+
+## Layout
+
+**The workspace** (committed by the project; the framework never holds these):
+- `cases/**/*.md`     human-written test cases (input of the AI workflow); `cases/<group>/<name>.md` groups an area
+- `tests/**/*.spec.ts` generated Playwright specs (output of the AI workflow), one per case, same folder as the case,
+  with their `*-snapshots/` baselines next to them
+- `profiles.yaml`       one entry per environment: URL, account label, tags, environment (connection settings only)
+- `AGENTS.md`           the project's own rules: they point at this baseline, and §2 holds what differs
+- `.auth/` `reports/` `.tmp/` `.explore/`  local state, never committed
+
+The framework folder is read-only in a project: never edit it. Its own layout and how to change it are in
+`docs/agents/framework-dev.md`.
+
+## Workflow
+Three steps, each learns one thing: the intent, the facts and inputs, the implementation.
+1. `making-cases` (or `/make-case <notes>`) turns raw notes into case documents. It writes `cases/*.md` only and
+   never opens a browser. Check them with `pnpm case:check`.
+2. `exploring-cases` (or `/explore-case <case-id> <env> [--attended]`) explores the real pages for one case. It
+   edits that case file only: wording, observations, TODO blocks, and, with `--attended`, the `- Recipe:` lines of
+   the steps that write or need a choice.
+3. `generating-specs` (or `/gen-spec <case-id> <env>`) turns the case into a spec. It replays the case and its
+   step recipes and `## Values`, writes the spec (values stay in the case document), but never runs the tests, never
+   writes data and never creates baselines. A tagged step with no `- Recipe:` line (an old `## Inputs` line counts
+   until it is moved) stops with `needs-input`: run `/explore-case` first. Running specs is a separate step
+   (`pnpm asrun`, or the Run page).
+Do not hand-write specs unless asked. Do not edit `lib/` to make a single spec pass.
+Every case step is wrapped in `test.step('<n>. <case step text>', ...)` so reports and traces show the
+case's own steps (see the skill's `references/conventions.md`).
+Every AI command needs an environment (`--env`/`<env>`); there is no default and no "no environment" mode.
+`/heal-spec <case-id> <env>` reads the existing report first (`pnpm heal:evidence --case <id> --env <env>`), reads the
+user's optional clues (`--hints <file>`), runs only the profiles that are logged in (`--logged-in`) and runs the case
+again only when the report is missing, stale or not enough.
+Run `pnpm typecheck`, `pnpm spec:lint <case-id>` and `pnpm case:check` before reporting that a spec was generated. Run
+`pnpm asrun --env <env> --profile <id> --grep <case-id>` only when healing a spec or when asked to.
+Pick `--env staging` while developing. A case that does not list `production` under `writes` is skipped in
+production with a notice; add `--read-only` to leave all write cases out.
+
+## Working on the framework itself
+This file is the product baseline. How to change asrun (repository layout, templates and versioning, the web UI
+theme, developing against `examples/demo`) is in `docs/agents/framework-dev.md`; read it only when working in the
+framework repository.

package/CLAUDE.md

@@ -1 +1,2 @@
-@AGENTS.md
+@AGENTS.md
+@docs/agents/framework-dev.md