@asrunjs/asrun 0.0.0-stage → 0.2.0

package/.claude/skills/generating-specs/references/conventions.md

@@ -0,0 +1,148 @@
+# Spec conventions
+
+## Shape
+A case id is its path below `cases/` without `.md`: `hub-landing`, or `documents/landing-page` when the case is in a
+folder (one level only). The spec is at the same path below `tests/` (`tests/documents/landing-page.spec.ts`).
+
+```ts
+// case: cases/<id>.md
+import {caseTags} from '@asrunjs/asrun/cases';
+import {configureCase, expect, test} from '@asrunjs/asrun/fixtures';
+import {requireValues} from '@asrunjs/asrun/values';
+
+test.use({mustLogin: false}); // only for login: none cases (public pages)
+
+test.describe('<Case title>', {tag: caseTags('<id>')}, () => {
+  configureCase('<id>'); // from asrun/fixtures; no retries and a longer timeout for cases that write data
+  test('<single outcome>', async ({page, profile}) => {
+    const expected = requireValues<{...}>('<id>', profile); // the case's "## Values": default + this profile
+    // Locators are lazy: declare them here when several steps share them.
+
+    await test.step('1. <step text from the case>', async () => {
+      ...
+    });
+
+    await test.step('Visual check: <what is compared>', async () => {
+      await expect(locator).toHaveScreenshot('<name>.png');
+    });
+  });
+});
+```
+- Import `test`/`expect` from `@asrunjs/asrun/fixtures`, never from `@playwright/test`. The package name is the import path
+  (the package's `exports` map points at its `dist/` build), so a spec in a group folder uses the same imports as one
+  at the top of `tests/`.
+- `profile` fixture = the current project's profile (`profile.id`, `profile.env`, `profile.baseURL`, `profile.account`,
+  `profile.tags`, `profile.email`). Never branch on `profile.id` or `profile.env` inside a spec: profile differences go
+  into the case's `## Values`, and the selectors come from `## Targets`.
+- Paths are relative (`page.goto('/account/')`); the project sets `baseURL` per profile.
+
+## Tags
+The case's front matter (`suites: [...]`, `writes`) is the single source of truth. The spec never hard-codes
+tags: it passes `{tag: caseTags('<id>')}` (from `@asrunjs/asrun/cases`) to the top-level `test.describe`.
+`caseTags` returns one `@<suite>` per suite (shown as badges in the HTML report, drives `pnpm asrun --suite <name>`)
+and `@writes` for cases that write data (drives `--read-only`).
+- Do not copy suites into the describe title.
+- If the front matter is invalid, `caseTags` throws; ask the user to fix the case.
+- Write permission and `envs` limits are enforced by the `caseGate` fixture in `@asrunjs/asrun/fixtures`; specs do nothing.
+  A case that writes only in some environments is skipped (not failed) in the others, with a notice.
+
+## Cases that write data (`writes: [<env>, ...]`)
+- Name everything the case creates `[asrun] <something>` (`TEST_DATA_PREFIX` in `@asrunjs/asrun/records`). `records.track`
+  refuses other names, so cleanup can never touch real data.
+- Register data with the `records` fixture right after creating it, together with the function that removes it:
+  `await records.track({kind: 'Document draft', name, where: '/app/documents'}, async () => {...delete it from the documents list...});`
+  Everything tracked is removed after the test, newest first, also when the test failed. The remove function opens
+  its own page (it cannot know where the test stopped) and must not fail if the data is already gone.
+- The case's last step is normally the deletion itself; `track` is the safety net. Do not rely on it alone.
+- If a cleanup fails, the test fails, the data is listed in the run summary (web UI banner and terminal) and
+  `pnpm cleanup --env <env>` lists it until a person deleted it and ran `--forget`.
+- `configureCase('<id>')` turns retries off (a retry would create the data twice) and raises the timeout.
+  Cases that write run one at a time per profile, whatever the number of workers.
+- Mark steps in the case text with `[writes]`; keep their titles unchanged in `test.step`.
+- Email: wrap steps that send email in `if (!emailStepAllowed(profile, '<step title>')) return;` (`@asrunjs/asrun/email`).
+  It is false in production and for profiles with `email: false`; the skip is written to the report annotations.
+
+## Steps (`test.step`)
+Every numbered step of the case is wrapped in `await test.step('<n>. <step text>', async () => {...})`.
+The report and the trace then show the case's own steps, so a reviewer can check what was executed
+without reading the spec.
+- Step title = the case's step text, verbatim, with its number. Do not paraphrase.
+- Put the assertions that belong to a step inside that step.
+- One extra step, titled `Visual check: <what is compared>`, per visual check from the case.
+- A value needed by a later step (for example a page opened in a new tab) is returned from the step:
+  `const previewPage = await test.step('3. ...', async () => {...; return opened;});`
+- Do not put `test.step` inside helpers in the framework (`@asrunjs/asrun/*`), and do not nest steps.
+- Use step comments only for things the title cannot say; the title replaces the old `// 1. ...` comments.
+
+## Assertion layers (use all that apply)
+1. Text: `toHaveText`, `toHaveTitle`, `toContainText`, with values from `requireValues('<id>', profile)`.
+2. DOM of images: `expectLogo(container, expected.logo)` / `expectImageLoaded`
+   (alt, src, loaded). Use `expectImageSha256` when the exact file must match.
+3. Pixels: `await expect(locator).toHaveScreenshot('<name>.png')`. Baselines are stored per
+   profile automatically. Screenshot a small element, not the full page (full pages are flaky).
+
+## Readable failures
+The UI shows the first line of the error to QA and non-technical people, and hides the call log and stack
+trace behind a "Technical details" fold. Write errors so that first line makes sense on its own.
+- Read per-profile data with `requireValues<T>('<id>', profile)` (from `@asrunjs/asrun/values`), never by reading the case
+  yaml yourself. A case with no entry for the profile, or with `TODO`/empty values, then fails with
+  "Missing values: cases/<id>.md has no \"## Values\" for profile ..." instead of a cryptic crash.
+- Give every `expect` a message in plain words about the product, not the code:
+  `expect(locator, 'The documents page did not finish loading').toBeVisible()`.
+  Say what is wrong ("The product logo has the wrong name"), not what the matcher is ("expected true").
+- Guard preconditions that need manual data (for example "at least one published document exists") with an
+  `expect(..., 'No published document found. Create one manually; this test never writes data.')` in the step,
+  so the failure says what the human has to do.
+- Messages are English, one sentence, no selectors or test ids.
+
+## Ready, targets and downloads (`@asrunjs/asrun/ready`, `@asrunjs/asrun/downloads`)
+Binding rules are in `../exploring-cases/references/readiness.md` and `.../assertion-targets.md`. In short:
+- An action that loads data (opens a dialog, a composer, a tab, a list, a preview) goes through
+  `actAndWait(page, () => click(), {responses: [/api-url/], ready: [locator]})`: the response waiters exist before the
+  action, then the content signal must be visible. Read the result only afterwards. `expectNotBusy(scope)` waits until
+  no spinner, skeleton or `aria-busy` is left.
+- A confirmation that may or may not appear after an action (the "Save as Draft?" dialog when closing a composer) is
+  handled with `clickOptionalUntilHidden(confirmButton, target, {message})`: one retry loop that clicks the confirmation
+  when it is visible and checks that the target is hidden. Never `if (await x.isVisible(...)) await x.click()`; see
+  `readiness.md`, "Optional confirmations".
+- A check on a logo, image, file or screenshot has `// target: T<n>` on the line before it (a card in the case's
+  `## Targets`). The element is found by the card's `Identified by` (role and name, test id, alt/title), never `.first()` or
+  a bare `img`/`svg`. Semantic assertion first (name/alt/src, where it is), pixels second, on that element only.
+- A check for absence ("no", "missing", "empty", "hidden") has `// ready: <signal>` in front of it and a positive wait
+  before it. The page must have loaded before "nothing" means anything.
+- A download is `await verifyDownload(page, () => option.click(), {kind: 'pdf'})`. It checks, and fails the step on
+  any failure or timeout: the download starts, finishes, the file exists, the file is valid for its kind (PDF: `%PDF-`
+  start, `%%EOF` end, opens with pages). Add `validate` for the case's own check of the content. Never
+  `waitForEvent('download')` or a magic-number check on its own.
+- A PDF's content is checked with `expectPdf(file.pdf!, {...})` (`@asrunjs/asrun/pdf`): pages rendered to images, regions that must not
+  be blank and are compared with the profile's baseline (2%), extracted text. Pages follow the case: every page by default
+  (`pages: 'all'`), only the named ones when the case says ONLY (a strong requirement) with `// pages: <the case's words>`.
+  The call has `// target: T<n>`. Take names and texts to avoid from `requireValues('<id>', profile)`, never literals.
+  ```ts
+  const file = await verifyDownload(page, () => option.click(), {kind: 'pdf'});
+  // target: T3
+  await expectPdf(file.pdf!, {
+    regions: [{name: 'profile-logo', pages: 'all', region: corner('top-left')}],
+    textNotContains: expected.otherProfileNames,
+  });
+  ```
+- `pnpm spec:lint <id>` (static) must have no `FAIL`. `pnpm baselines:review <id>` lists every baseline with the card
+  that says what it must show.
+
+## Do
+- Locators: `getByTestId` (data-tn) > `getByRole` > `getByLabel` > text.
+- Web-first assertions only; they auto-wait. Never `waitForTimeout`, never `networkidle`, never `if (await x.isVisible())`
+  to decide something that may not have loaded.
+- Keep every test read-only unless the case lists environments under `writes`.
+
+## Don't
+- No login code in specs, and no cases that test the login page or the login flow. Sessions come from
+  `.auth/<profile-id>.json` via the project config; a profile without a valid session fails fast (see
+  `@asrunjs/asrun/fixtures`).
+- No hard-coded profile names or expected values in specs; they come from the case's `## Values` through
+  `requireValues('<id>', profile)`. Site addresses come from `profile.baseURL`.
+- No screenshots of areas with dynamic data (rows, prices, dates, avatars).
+- No `.first()` / `.nth()` / bare `img`, `svg` or `img, svg` to find a logo or image.
+- No hard assertion about something that was never seen on a page.
+- No `isVisible({timeout})` / `isHidden({timeout})` (the timeout is ignored, nothing is waited for), no
+  `if (await x.isVisible()) await x.click()` outside a retry loop, and no `.catch(() => false)` to fake a wait.

package/.claude/skills/making-cases/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: making-cases
+description: Turns raw, informal test notes from a human (a QA memo, a list of buttons to check, a pasted chat) into well-formed case documents (cases/<id>.md) for the AsRun suite. Normalizes the text, classifies steps as read-only, writing or email, finds gaps and asks about them, never opens a browser, and splits the notes into cases. Use when asked to make, write or normalize cases from notes, or for /make-case. The next step after it is exploring-cases, then generating-specs.
+---
+
+# Making case documents from raw notes
+
+Read `AGENTS.md` (hard rules) and `cases/_template.md` (the target format) first. Then read the references:
+- `references/normalizing.md`: how to clean up the text and keep the original traceable.
+- `references/writes-and-email.md`: how to classify steps that write data or send email, and the data rules.
+- `references/gaps.md`: what to ask, and the default to suggest for each question.
+- `references/splitting.md`: how many cases to make.
+
+This skill writes `cases/*.md` only. It never writes specs, `profiles.yaml`, or anything under `tests/`.
+
+## Inputs
+- Raw notes: pasted text or a file path. Any language, any quality.
+- No environment: this skill never opens a browser. What the pages really show is found by `/explore-case`.
+
+## Procedure
+1. **Read everything and keep the original.** Number every distinct statement of the notes (N1, N2, ...). The
+   original wording is stored verbatim in each case's `## Source` table, so nothing is lost and a reviewer can check
+   what became of each line. Do not edit the input file.
+2. **Normalize.** Follow `references/normalizing.md`: English, one action or check per step, concrete UI wording,
+   quoted UI text kept exactly. Do not add checks the notes did not ask for, and do not drop any.
+3. **Classify each step**: read-only, `[writes]`, or `[email]` (`references/writes-and-email.md`). A step that
+   creates, edits, publishes, shares, deletes or sends is not read-only, even if the notes do not say so.
+4. **Find the gaps** (`references/gaps.md`): missing expected results, unknown values a spec must assert, unclear starting
+   state, steps that need data that may not exist, ordering that is not linear. Never invent an expected value.
+   Unknown values are written as the suggested default sentence with a `❓ TODO` block under it (see `gaps.md`), or as an
+   `Observed, 🔍 to be confirmed by QA` bullet. Every marker starts with its emoji. A literal nobody knows yet goes into
+   the case's `## Values` as `TODO` (the spec then fails with a clear message until it is filled), never into
+   `profiles.yaml`.
+5. **Ask before writing.** Show the user a short plan and the open questions in one message: the proposed split
+   into cases, the classification (which steps write, which send email), and the gaps with your suggested default
+   for each. Wait for answers. Do not write case files before that.
+6. **Split** (`references/splitting.md`) and **write** `cases/<id>.md` for each case from `cases/_template.md`.
+   - Group folder: when the notes (or the user) name an area (documents, search, account...), put the cases in
+     `cases/<group>/<name>.md` and set `id: <group>/<name>` in the front matter. Use one folder level and
+     lowercase kebab-case. Reuse an existing folder in `cases/` when the area matches. If the area is unclear,
+     ask in step 5. The group does not repeat in the name: `documents/landing-page`, not `documents/documents-landing-page`.
+   - Front matter: `id`, `title`, `login`, `suites`, `writes`, `writes-note` (required when `writes` is not `none`),
+     `envs` when a case must not run everywhere. When unsure: `suites: [regression]`, no `writes` (read-only), or `writes: [staging]` when a step writes.
+   - Fill the sections that apply (Goal, Steps, Expected, Values, Visual checks, Data, Source, Notes).
+     Remove template placeholders you do not use. Use `## Values` only for the literals a spec asserts; `default`
+     applies to every profile, and a profile id entry holds only what differs.
+   - Case ids are lowercase kebab-case and name the thing, not the ticket: `landing-page`.
+   - Existing case files: do not overwrite. If a new case overlaps one (for example another case about the same page), say so,
+     propose "keep", "merge" or "replace", and wait for the user.
+7. **Check.** Run `pnpm case:check`. Fix every FAIL. Re-read each written case against the numbered statements: every
+   N must appear in exactly one `## Source` table, or in the report as "not used, because ...".
+8. **Report** in the user's language: the cases written (id, suites, writes, envs), the traceability summary, the
+   questions that are still open, and the next steps per case: `/explore-case <id> <env> --attended` (after `pnpm signin`
+   for the profiles and environment; a person does the steps that write data), then `/gen-spec <id> <env>`.
+
+## Hard rules
+- Never open a browser and never write data. A step that writes is only described and marked; the case lists the
+  environments the spec may write in under `writes`. Never add `--allow-writes`, never set
+  `ASRUN_ALLOW_WRITES`; this skill does not run write cases at all.
+- Never send email in production. In other environments only for profiles with `email: true`. New profiles and AI-written
+  entries in `profiles.yaml` get `email: false`; do not change an existing `email: true`.
+- Never write a case for the login page or the login flow.
+- Never invent expected values, profile names, counts, or UI texts.
+- All files are written in English.

package/.claude/skills/making-cases/references/gaps.md

@@ -0,0 +1,36 @@
+# Gap analysis
+
+Ask every question in one message, each with a suggested default, so the user can answer "yes to all" or correct
+single lines. Never ask a question whose answer is already in the notes, `AGENTS.md`, `profiles.yaml` or the existing cases.
+
+## What to look for
+| Gap | Typical question | Suggested default |
+|---|---|---|
+| "check X" without an expected result | What exactly must be true for X (text, logo, count, color)? | Visible and not empty; the value per profile goes in `## Values` |
+| Logo checks | Which logo element and which value per profile? | The product logo is visible and not empty; the value per profile goes in `## Values`, and name the element as a target to settle in `/explore-case` (`[T<n>]`, see `exploring-cases/references/assertion-targets.md`). Ask the user for the exact image/text/place when the notes say only "the logo" and the page may hold several. |
+| A check on an image, logo, file or PDF | Which exact image, text, place or UI element, and where? | Write the check with a `[T<n>]` reference and leave the card to `/explore-case`; never describe it as "the first image" |
+| Page loads data after an action | What shows that the content is really there? | Add `Ready when: <signal>` if the notes name one; else leave it to `/explore-case` |
+| Starting state | Does the case need existing data (a published document, a shared document)? | The case creates what it needs; never depends on pre-existing data |
+| Delete path | How is the created data removed, and from where? | From the list page, with the item's menu; keep a `[blocking]` TODO block until confirmed |
+| Write level | Does this step write? | Yes if it creates, edits, publishes, shares or deletes |
+| Email | Does this step send email? | Yes for share/send/invite; skipped in production and for `email: false` profiles |
+| Environments | Must this case run in production, or only staging? | All environments; production writes need the usual confirmation |
+| Suites | Smoke, regression, or both? | A read-only landing check: `[smoke, regression]`; a flow that writes: `[regression]` |
+| Profiles | Do all profiles see the same UI? | Yes; the exact literals that differ go in `## Values`, never in the steps |
+| Unclear words | What does "collaborator button" / "..." button open? | Describe only what is observed; mark `(observed, 🔍 to be confirmed by QA)` |
+| Unused lines | A statement that fits no case | Ask where it belongs; never drop it silently |
+
+## Marking unknowns in a case
+- Unknown expected value: write the suggested default as a normal sentence and hang a TODO block under it, in the
+  shape of `<framework>/.claude/skills/exploring-cases/references/open-questions.md`:
+
+  ```
+  - The preview header shows the product logo, visible and not empty.
+    - ❓ TODO [non-blocking]: Which logo must it be? (👁️ not observed)
+      - ✍️ Answer:
+  ```
+
+  The user accepts the default by deleting the block, or types an answer. Never write a bare `TODO: ...` line, a
+  question as the only text, or `Suggested:`.
+- Seen on a page during exploration but not stated in the notes: `- <observation> (observed, 🔍 to be confirmed by QA)`.
+- Never turn an observation into a hard requirement on your own.

package/.claude/skills/making-cases/references/normalizing.md

@@ -0,0 +1,38 @@
+# Normalizing raw notes
+
+## Goal
+Turn informal notes into steps that someone who never saw the notes can follow, without changing what was asked.
+
+## Rules
+1. **Translate to English.** Keep text the page shows exactly as written in the notes (button labels such as
+   "Create New", pill names such as "My documents", "Shared with me"). Do not translate or "fix" those.
+2. **One action or one check per step.** Split "create, publish and preview it" into three steps. A check that
+   belongs to an action stays in the same step as its action ("Open Share and check the logo").
+3. **Make the wording concrete.** Say where (page, path, card, corner), what (exact label), and what happens.
+   "Check the logo" is not a step by itself: it needs an expected result (see `gaps.md`). Until it has one, write
+   the default as a sentence under "Expected" ("The <thing> is visible and not empty.") with a
+   `TODO [non-blocking]` block under it (see `gaps.md`).
+4. **Keep the order of the notes** unless the notes say otherwise, then fix the order and say so in the Source table.
+5. **Do not add checks** the notes did not ask for (no extra assertions "while we are at it"), and do not drop any.
+   When a line is a heading or a list of things on one page ("Landing: Create New, All, My documents, Shared with me,
+   search bar"), each item becomes a check: "is visible" is the only meaning you may assume, and you say so.
+6. **Mark steps** with `[writes]` or `[email]` at the end of the step text (see `writes-and-email.md`).
+7. **Use paths relative to the app** (`/app/documents`), never a full domain. Domains differ per profile and environment.
+8. **No profile-specific values in steps.** The exact literals go in `## Values`; a sentence about behaviour goes in `Expected`.
+
+## Traceability (`## Source` section in every case)
+Number every statement of the raw notes once (N1, N2, ...). Each case ends with:
+
+```markdown
+## Source
+Original notes, verbatim. Do not edit this table; it only exists so a reviewer can check what became of each line.
+
+| # | Original text | Became |
+|---|---------------|--------|
+| N3 | `Published document: publish (a follow-up modal opens by itself)` | Steps 6-7 |
+```
+
+- The original text is copied character by character, in a code span, in its original language.
+- "Became" points at step numbers, or says "Expected", "Visual checks", "Not used: <reason>".
+- A statement used by two cases appears in both tables.
+- A statement that is not used anywhere is a gap: ask about it, do not silently drop it.

package/.claude/skills/making-cases/references/splitting.md

@@ -0,0 +1,28 @@
+# Splitting notes into cases
+
+## Principle
+One case = one real user path. Split only when something real differs:
+1. **Starting state** differs (a landing page you simply open, versus a flow that needs data it creates itself).
+2. **Write level** differs (read-only versus `writes: [<env>, ...]`). Keep read-only checks out of write cases: they can
+   run anywhere, without confirmation, in the smoke suite.
+3. **Independence** differs (the checks can pass or fail without the other part, and a failure in one should not hide
+   the other).
+
+Do not split because a case is long, or because the notes list things under separate headings.
+
+## Typical result
+- A read-only landing or overview check (what is on the page): small, fast, `suites: [smoke, regression]`, no `writes` (read-only).
+- A user flow that creates data and cleans it up: `writes: [staging]`, one case, steps in the real order (even if the
+  flow is not linear), ending with the deletion.
+- A logo or visual check of data that already exists, kept read-only: its own case when it does not need the flow.
+
+## Existing cases
+Look at `cases/` before writing. If a new case overlaps an existing one, do not overwrite it: propose keep, merge or
+replace, with the reason, and wait for the user. Never rename or move an existing case yourself; the Cases page of the web UI does that and keeps the spec in step.
+
+## Naming and folders
+Cases of one area live in a folder: `cases/documents/landing-page.md` has the id `documents/landing-page`. The name is
+`<what>` in kebab-case (`hub-landing`, `draft-to-publish`), the folder is the area (`documents`). One folder level only.
+Look at the folders that already exist in `cases/` and reuse them. A case that fits no area stays directly in
+`cases/`. The `title` says what the case proves. Two ids that differ only in `-` versus `/` (`documents-x` and
+`documents/x`) are not allowed: one group level only, so ids stay unambiguous.

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

@@ -0,0 +1,36 @@
+# 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.

package/AGENTS.md

@@ -0,0 +1,154 @@
+# 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.

package/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zoro Chen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.