@asrunjs/asrun 0.2.0 → 0.5.3

package/docs/troubleshooting.md

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

package/docs/web-ui.md

@@ -0,0 +1,139 @@
+# The web UI
+
+The UI is a local page for the daily work: profiles and logins, case editing, AI runs with live logs, and reports.
+It runs on your machine and only listens on `127.0.0.1`.
+
+```bash
+pnpm go          # install + build + start + open the browser (the usual command)
+pnpm ui          # build the web app and serve http://127.0.0.1:4173
+pnpm ui:dev      # development: Vite on :5173 with hot reload, API in watch mode
+```
+
+Set `ASRUN_UI_PORT` to change the port of the served app (`ASRUN_UI_WEB_PORT` for the Vite dev server).
+
+Everything the UI does is a fixed action mapped to a command of this repository; there is no free shell. An AI job
+runs the AI tool you selected (Claude Code or OpenCode) with the same commands as the terminal.
+
+## The top bar
+
+- **Sections:** Profiles, Cases, Run tests, Reports, AI guide, Help, and the Jobs bar at the bottom.
+- **AI tool switch:** Claude Code (the default) or OpenCode. The choice is remembered in this browser and applies to
+  every AI command.
+- **Model picker:** the models that the selected CLI knows on this machine. OpenCode lists its providers
+  (`opencode models`); Claude Code lists what its own settings, environment, aliases and gateway expose, and does not
+  query cloud providers. The choice is remembered per CLI and shown in the command line of every AI run. On a
+  project that sets no model, a one-shot OpenCode run uses OpenCode's built-in free model, which has a daily limit.
+- **Thinking:** passes `--thinking` to OpenCode. Off by default (it costs tokens and slows a run). Claude Code has no
+  such flag, so the icon is disabled there.
+- **Bell:** browser notifications for "your turn" (a login to finish, an attended step waiting, answers an AI run
+  needs) and for a run that ends while the tab is in the background. It stays until you click or close it; clicking
+  opens that job. The tab title shows the section and, in front, how many things wait for you: `(1) AsRun | Cases`.
+
+The UI's look is the **Inkstone** theme; the palette, buttons, badges and icons are documented in
+`theme-guide.html` in the framework package (also linked from the top bar).
+
+## Profiles
+
+One row per profile, with the same login check as `pnpm status`.
+
+- **Log in** starts `pnpm signin <profile-id>`: log in in the browser window that opens, then press **Done, save the
+  session** on the card in that window (the job's "I've logged in, save the session" button does the same). A
+  logged-in profile shows `Login YES`.
+- The **...** menu: **Verify** (the same read-only session check) and **Re-login** for a logged-in profile, **Logout**
+  for a saved session (deletes the session file, after a confirmation), **Duplicate** (a second entry with the same
+  settings under a new id; the saved login is not copied) and **Delete** (removes the entry and its saved login, after
+  a confirmation; baselines and old reports keep the id in their names and stay on disk).
+- **Visit** opens a logged-in browser window at the profile's `startPath` (or the site root). While it is open the
+  button turns into **Close browser**. Downloads in that window are saved to `~/Downloads` without overwriting an
+  existing file, and the saved path is printed in the job log.
+- **Add a new profile** has a form (environment, URL, account label, tags, start path) that appends an entry to
+  `profiles.yaml`, plus the next steps: log in, update the cases, a copyable AI prompt.
+
+## Cases
+
+The case list is grouped by folder and collapses. The editor opens in **Single** with the **Panel** full width; the
+toolbar switches to **Split** (source left, one pane right; drag the divider to resize, double-click to reset) or, in
+Single, to **Editor** or **Doc**.
+
+- **Source and preview** scroll together, the preview block at the caret is shaded, and a click in the preview puts
+  the caret on that line. `Ctrl/Cmd+S` saves.
+- **What needs a person is highlighted** in both: `TODO` in any spelling (red for `🚫 TODO [blocking]`, gold
+  otherwise), `🔍 to be confirmed by QA` / `👁️ not observed` / `TBC` / `TBD` in blue, and your `✍️ Answer:` lines in
+  green. Hover for a tooltip; the small X after a marker removes it (or the whole question block for a `TODO`) in one
+  step, with Undo; the file is saved when you save it.
+- **New case** takes an optional folder and runs `pnpm case:new`.
+- **The Panel** shows the case as a form, with the open questions first (accept one to delete the question, or write an
+  answer and the AI folds it in). Then the front matter (title, login, suites, writes and its note, environments), the
+  steps (sentence, `[writes]` / `[input]` / `[email]` tags, `- Ready when:` lines, `- Recipe:` lines), the
+  `## Expected` and `## Visual checks` bullets (drag to reorder), the `## Values` table (one column per profile; an
+  empty cell inherits `default`), and the `## Targets` cards read-only, with what each is missing. `[T1]` chips open
+  the card: what it is, where, how it is identified, what it must not be, and its reference screenshots. Every section
+  collapses and has a **?** with a short help card. Panel edits land in the same draft as the source editor, so one
+  save covers both, and **Discard** throws them away together.
+- **Spec view** is editable too (`Ctrl/Cmd+S`; refused when the file changed on disk meanwhile). **Open in editor**
+  opens it in the default application for `.spec.ts`, **Copy path** copies its absolute path.
+- Click the file name (or the pencil icon) to **rename** or move the case: the spec and the baselines move with it and
+  the spec is rewritten. **Delete** (type the id, or fill it in with the feather icon) removes the case, its spec and
+  its baselines; both dialogs list exactly what they touch, and are refused while an AI or test run is in progress.
+- **Toolbar:** command (explore / generate / heal, explore by default), **Environment** (required, no default),
+  **Attended** (only for explore, ticked by default), **Run AI**, copy the shell command, open the AI guide.
+- **From memo** opens a Markdown editor with a preview for raw notes. **Make cases** saves them to `.tmp/memos/` and
+  runs `/make-case` one-shot (defaults for gaps, `TODO` for unknown values, no page exploration, existing cases never
+  overwritten); **Copy /make-case** copies the memo for the interactive dialogue. When the run ends, **What to do
+  next** shows the new cases and **Review** lists them, each with **Explore**: a case written from a memo has not been
+  checked against the real pages yet.
+
+## Run tests
+
+The form builds `pnpm asrun`: environment (required; no run starts without one), profiles, suite, read-only, case,
+step text.
+
+- **Case** is a searchable picker of the cases that have a spec.
+- **Cases to run** shows what the filters select, with an **Update baselines** box per case (`--update-baselines`,
+  unticked by default; it asks before overwriting and shows the new images next to their target cards when the run
+  ends).
+- It asks for confirmation when write cases would run in production.
+
+Running is a job: its output streams into the Jobs bar.
+
+## Reports
+
+One entry per run, with a PRODUCTION or STAGING badge (runs from before environments existed show PRODUCTION).
+
+- **Results** lists every case × profile with the failure reason on one line, failed first.
+- Selecting one shows a red **Why it failed** block (failed step and error) above the screenshot and the video, with a
+  folded **Technical details** (call log, stack trace).
+- **Full Playwright report** embeds the standard HTML report, where the videos and traces work.
+- The latest run opens first.
+
+## Jobs
+
+The bottom bar shows every command started from the UI with live stdout/stderr and the exit code; a job can be
+cancelled there. Opening it shrinks the page instead of covering it.
+
+- An AI job's log is structured: a timestamp, one line per tool call (name, what it touched, how long it took), the
+  first lines of what it returned with the colors the command printed, the agent's thinking dimmed while **Thinking**
+  is ticked, and its messages rendered as Markdown. Long output is a preview with a count. The same text is kept in
+  `.tmp/ui-jobs/`.
+- When an AI job ends, a thin **What to do next** bar appears under the log (or **Details** opens it in a sheet):
+  open questions with an answer box and **Use the suggested defaults**, the confirmations the exploration marked, and
+  the next action (**Generate spec**, **Open Run tests**). A run that ends with `needs-input` gets an amber *Needs
+  your input* badge; sending answers continues the same conversation, once per turn and only while the UI server has
+  not restarted. After a restart, answer in the case file and run the command again.
+
+## Help and AI guide
+
+- **Help** (the **?** icon) is "How to start": nine short steps with screenshots, from installing AsRun to reading a
+  report. The screenshots are in `ui/web/public/help/` in the framework package; retake them when a page changes.
+- **AI guide** explains each AI step in the UI and has the same `/make-case`, `/explore-case`, `/gen-spec`,
+  `/heal-spec` commands for the terminal, ready to copy.
+
+## Where the UI keeps its state
+
+| Path | What |
+|---|---|
+| `.tmp/ui-jobs/` | the log of every job started from the UI (git-ignored) |
+| `.tmp/hints/` | the text you type in the Heal dialog, passed to the agent as `--hints` |
+| `.explore/` | reference screenshots of the target cards (git-ignored) |
+| `reports/` | one folder per run, `reports/latest` points at the newest |
+| `.auth/` | the saved logins (git-ignored, never shared) |

package/package.json

@@ -1,9 +1,17 @@
 {
   "name": "@asrunjs/asrun",
-  "version": "0.2.0",
+  "version": "0.5.3",
   "description": "Multi-profile end-to-end test suite: plain-language cases, AI-written Playwright specs, evidence for every run.",
   "license": "MIT",
   "author": "Zoro Chen",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wizcas/asrun.git"
+  },
+  "homepage": "https://github.com/wizcas/asrun#readme",
+  "bugs": {
+    "url": "https://github.com/wizcas/asrun/issues"
+  },
   "type": "module",
   "engines": {
     "node": ">=22"
@@ -55,7 +63,11 @@
     "@codemirror/lang-yaml": "^6.1.3",
     "@codemirror/language": "^6.13.1",
     "@codemirror/language-data": "^6.5.2",
+    "@codemirror/state": "^6.7.6",
     "@codemirror/view": "^6.43.15",
+    "@dnd-kit/core": "^6.3.1",
+    "@dnd-kit/sortable": "^10.0.0",
+    "@dnd-kit/utilities": "^3.2.2",
     "@hono/node-server": "^2.1.5",
     "@lezer/highlight": "^1.2.5",
     "@napi-rs/canvas": "^1.0.13",
@@ -92,6 +104,13 @@
     "spec:lint": "tsx scripts/lint-specs.ts",
     "baselines:review": "tsx scripts/review-baselines.ts",
     "pdf:render": "tsx scripts/render-pdf.ts",
+    "demo:up": "node scripts/demo.mjs up",
+    "demo:build": "node scripts/demo.mjs build",
+    "demo:seed": "node scripts/demo.mjs seed",
+    "demo:reset": "node scripts/demo.mjs reset",
+    "demo:down": "node scripts/demo.mjs down",
+    "demo:logs": "node scripts/demo.mjs logs",
+    "demo:status": "node scripts/demo.mjs status",
     "typecheck": "tsc --noEmit && tsc --noEmit -p ui/tsconfig.json",
     "ui": "tsx scripts/ui.ts",
     "ui:build": "tsx scripts/ui-build.ts",

package/templates/.claude/commands/explore-case.md

@@ -1,21 +1,22 @@
----
-description: Explore the real pages for one case (optionally attended: you do the steps that write data), before generating the spec
----
-
-Load the framework skill `{{framework}}/.claude/skills/exploring-cases/SKILL.md` and explore: $ARGUMENTS
-
-If `.claude/skills/exploring-cases.md` exists, apply it after the framework skill; on conflict it wins, except rules
-tagged `[non-negotiable]`. Project facts are in `AGENTS.md` §3.
-
-Arguments: `<case-id> <env> [--attended]`. The case id is the path below `cases/` without `.md` (it may include a
-group folder, e.g. `documents/landing-page`) and is required. `<env>` is `staging` or `production`; it is required and there
-is no default (without one, stop and say so). With `--attended` I am at the machine and the browser window is
-visible: when a step writes data or needs a choice, hand it to me as the skill describes, wait for me, and record
-what I did as a general recipe under "## Inputs". Without `--attended`, never wait for me.
-
-Follow `{{framework}}/.claude/skills/exploring-cases/references/assertion-targets.md` (list the candidates, never
-pick when in doubt, ask for the exact image/text/place/UI) and `readiness.md` (wait for the key requests and the
-content before you read anything) of the skill.
-
-This command edits `cases/<case-id>.md` only (plus screenshots under `.explore/targets/`). Do not ask me questions in
-the chat: write open questions into the case file as the skill describes, and end with the `RESULT:` line.
+---
+description: Explore the real pages for one case (optionally attended: you do the steps that write data), before generating the spec
+---
+
+Load the framework skill `{{framework}}/.claude/skills/exploring-cases/SKILL.md` and explore: $ARGUMENTS
+
+Rules combine in this order, and a later one wins where they conflict: the framework baseline
+`{{framework}}/AGENTS.md`, the framework skill, `.claude/skills/exploring-cases.md` if it exists, then the workspace
+`AGENTS.md` §2 (Project rules). F1–F6 always win. Project facts are in `AGENTS.md` §3.
+
+Arguments: `<case-id> <env> [--attended]`. The case id is the path below `cases/` without `.md` (it may include a
+group folder, e.g. `documents/landing-page`) and is required. `<env>` is `staging` or `production`; it is required and there
+is no default (without one, stop and say so). With `--attended` I am at the machine and the browser window is
+visible: when a step writes data or needs a choice, hand it to me as the skill describes, wait for me, and record
+what I did as a general recipe under the step it belongs to (`- Recipe:` lines). Without `--attended`, never wait for me.
+
+Follow `{{framework}}/.claude/skills/exploring-cases/references/assertion-targets.md` (list the candidates, never
+pick when in doubt, ask for the exact image/text/place/UI) and `readiness.md` (wait for the key requests and the
+content before you read anything) of the skill.
+
+This command edits `cases/<case-id>.md` only (plus screenshots under `.explore/targets/`). Do not ask me questions in
+the chat: write open questions into the case file as the skill describes, and end with the `RESULT:` line.

package/templates/.claude/commands/gen-spec.md

@@ -1,20 +1,21 @@
----
-description: Generate or update tests/<id>.spec.ts from cases/<id>.md (the id may be <group>/<name>)
----
-
-Load the framework skill `{{framework}}/.claude/skills/generating-specs/SKILL.md` and generate the spec for:
-$ARGUMENTS
-
-If `.claude/skills/generating-specs.md` exists, apply it after the framework skill; on conflict it wins, except rules
-tagged `[non-negotiable]`. Project facts are in `AGENTS.md` §3.
-
-Arguments: `<case-id> [<env>] [--force]`. The case file is `cases/<case-id>.md` (the id may include one group folder,
-e.g. `documents/landing-page`). `<env>` is the environment to explore in (`staging` or `production`); there is no default. If
-the spec already exists, it is left alone unless `--force` is given; with `--force` it is regenerated and overwritten.
-
-Follow the skill's procedure exactly, including its `assertion-targets.md` and `readiness.md`; run
-`pnpm spec:lint <case-id>`. Only generate the spec: do not run `pnpm asrun` (running specs is a separate
-process), and do not create baselines.
-
-Do not ask me questions: resolve ambiguity as the skill describes (explore the page, use observed values marked for
-QA, write the remaining questions into the case file), and end with the `RESULT:` line.
+---
+description: Generate or update tests/<id>.spec.ts from cases/<id>.md (the id may be <group>/<name>)
+---
+
+Load the framework skill `{{framework}}/.claude/skills/generating-specs/SKILL.md` and generate the spec for:
+$ARGUMENTS
+
+Rules combine in this order, and a later one wins where they conflict: the framework baseline
+`{{framework}}/AGENTS.md`, the framework skill, `.claude/skills/generating-specs.md` if it exists, then the workspace
+`AGENTS.md` §2 (Project rules). F1–F6 always win. Project facts are in `AGENTS.md` §3.
+
+Arguments: `<case-id> [<env>] [--force]`. The case file is `cases/<case-id>.md` (the id may include one group folder,
+e.g. `documents/landing-page`). `<env>` is the environment to explore in (`staging` or `production`); there is no default. If
+the spec already exists, it is left alone unless `--force` is given; with `--force` it is regenerated and overwritten.
+
+Follow the skill's procedure exactly, including its `assertion-targets.md` and `readiness.md`; run
+`pnpm spec:lint <case-id>`. Only generate the spec: do not run `pnpm asrun` (running specs is a separate
+process), and do not create baselines.
+
+Do not ask me questions: resolve ambiguity as the skill describes (explore the page, use observed values marked for
+QA, write the remaining questions into the case file), and end with the `RESULT:` line.

package/templates/.claude/commands/heal-spec.md

@@ -1,30 +1,31 @@
----
-description: Diagnose and fix a failing spec from its last report (without hiding real product regressions)
----
-
-Load the framework skill `{{framework}}/.claude/skills/generating-specs/SKILL.md`, section "Healing a failing
-spec", and follow it exactly.
-
-If `.claude/skills/generating-specs.md` exists, apply it after the framework skill; on conflict it wins, except rules
-tagged `[non-negotiable]`. Project facts are in `AGENTS.md` §3.
-
-Arguments: $ARGUMENTS
-Format: `<case-id> <env> [--profiles a,b] [--report <run-id>] [--hints <file>]`, with optional free text after them.
-- `<case-id>` and `<env>` (`staging` or `production`) are required. There is no default environment. Without one,
-  stop and say so.
-- `--profiles`: the profiles to heal. Without it, every profile that is logged in in `<env>`.
-- `--report`: the report (folder name under `reports/`) to read first. Without it, the newest report of this case.
-- `--hints <file>`: a file with what the user knows (what to heal, evidence, clues). Read it first. Any free text
-  after the arguments is the same kind of clue. Both are optional.
-
-Before you decide "product or test", audit the assertion itself (target card, baseline content, readiness): see
-step 4 of the skill's healing section, `assertion-targets.md` and `readiness.md`. Run `pnpm spec:lint <case-id>`.
-Read the existing report first (`pnpm heal:evidence --case <case-id> --env <env>`), and run the case again only when
-the skill says it is needed. Always run with `--logged-in`. Tell me whether it is a test problem or a product
-finding.
-
-Run `pnpm asrun ...`, `pnpm heal:evidence ...`, `pnpm spec:lint ...`, `pnpm baselines:review ...` and
-`pnpm status ...` as plain commands, optionally piped to `tail` or `head`, and do not chain other commands with them
-(`;` or `&&`). Only these exact forms run outside Claude Code's sandbox, which tsx and the browser need. If a
-command still fails with `listen EPERM` or a sandbox error, stop and report it. Do not ask to disable the sandbox,
-and never add `--allow-writes` or set `ASRUN_ALLOW_WRITES`.
+---
+description: Diagnose and fix a failing spec from its last report (without hiding real product regressions)
+---
+
+Load the framework skill `{{framework}}/.claude/skills/generating-specs/SKILL.md`, section "Healing a failing
+spec", and follow it exactly.
+
+Rules combine in this order, and a later one wins where they conflict: the framework baseline
+`{{framework}}/AGENTS.md`, the framework skill, `.claude/skills/generating-specs.md` if it exists, then the workspace
+`AGENTS.md` §2 (Project rules). F1–F6 always win. Project facts are in `AGENTS.md` §3.
+
+Arguments: $ARGUMENTS
+Format: `<case-id> <env> [--profiles a,b] [--report <run-id>] [--hints <file>]`, with optional free text after them.
+- `<case-id>` and `<env>` (`staging` or `production`) are required. There is no default environment. Without one,
+  stop and say so.
+- `--profiles`: the profiles to heal. Without it, every profile that is logged in in `<env>`.
+- `--report`: the report (folder name under `reports/`) to read first. Without it, the newest report of this case.
+- `--hints <file>`: a file with what the user knows (what to heal, evidence, clues). Read it first. Any free text
+  after the arguments is the same kind of clue. Both are optional.
+
+Before you decide "product or test", audit the assertion itself (target card, baseline content, readiness): see
+step 4 of the skill's healing section, `assertion-targets.md` and `readiness.md`. Run `pnpm spec:lint <case-id>`.
+Read the existing report first (`pnpm heal:evidence --case <case-id> --env <env>`), and run the case again only when
+the skill says it is needed. Always run with `--logged-in`. Tell me whether it is a test problem or a product
+finding.
+
+Run `pnpm asrun ...`, `pnpm heal:evidence ...`, `pnpm spec:lint ...`, `pnpm baselines:review ...` and
+`pnpm status ...` as plain commands, optionally piped to `tail` or `head`, and do not chain other commands with them
+(`;` or `&&`). Only these exact forms run outside Claude Code's sandbox, which tsx and the browser need. If a
+command still fails with `listen EPERM` or a sandbox error, stop and report it. Do not ask to disable the sandbox,
+and never add `--allow-writes` or set `ASRUN_ALLOW_WRITES`.

package/templates/.claude/commands/make-case.md

@@ -1,12 +1,13 @@
----
-description: Turn raw test notes (pasted text or a file) into case documents in cases/
----
-
-Load the framework skill `{{framework}}/.claude/skills/making-cases/SKILL.md` and turn this input into case
-documents: $ARGUMENTS
-
-If `.claude/skills/making-cases.md` exists, apply it after the framework skill; on conflict it wins, except rules
-tagged `[non-negotiable]`. Project facts are in `AGENTS.md` §3.
-
-The input is either text or a path to a file with the notes. Follow the skill's procedure exactly. Ask me the open
-questions before writing any case file. Do not generate specs; that is `/gen-spec`.
+---
+description: Turn raw test notes (pasted text or a file) into case documents in cases/
+---
+
+Load the framework skill `{{framework}}/.claude/skills/making-cases/SKILL.md` and turn this input into case
+documents: $ARGUMENTS
+
+Rules combine in this order, and a later one wins where they conflict: the framework baseline
+`{{framework}}/AGENTS.md`, the framework skill, `.claude/skills/making-cases.md` if it exists, then the workspace
+`AGENTS.md` §2 (Project rules). F1–F6 always win. Project facts are in `AGENTS.md` §3.
+
+The input is either text or a path to a file with the notes. Follow the skill's procedure exactly. Ask me the open
+questions before writing any case file. Do not generate specs; that is `/gen-spec`.

package/templates/.mcp.json

@@ -1,8 +1,8 @@
-{
-  "mcpServers": {
-    "playwright-test": {
-      "command": "./node_modules/.bin/playwright",
-      "args": ["run-test-mcp-server"]
-    }
-  }
-}
+{
+  "mcpServers": {
+    "playwright-test": {
+      "command": "{{playwright}}",
+      "args": ["run-test-mcp-server"]
+    }
+  }
+}

package/templates/AGENTS.md

@@ -1,45 +1,66 @@
-# <project name> — asrun workspace
-
-This project uses the asrun framework, which lives in `{{framework}}` as an installed dependency. The framework is
-read-only here: never edit files inside it, and never commit test data into it.
-
-Read this file, then the framework baseline, before any AI step.
-
-## 1. Framework baseline (binding)
-
-Read `{{framework}}/AGENTS.md` in full. It is part of this project's rules. Its hard rules carry ids `F1`..`F10`,
-its browser rules `B1`..`B4`, its assertion rules `A1`..`A6`. Rules tagged `[non-negotiable]` cannot be narrowed.
-
-The framework skills are in `{{framework}}/.claude/skills/`. The commands in `.claude/commands/` load them. A
-project that needs different wording puts an override at `.claude/skills/<skill>.md` (for example
-`.claude/skills/exploring-cases.md`); the command applies the framework skill first and the override afterwards, and
-on conflict the override wins except for `[non-negotiable]` rules. `pnpm asrun doctor` lists every override.
-
-## 2. Project rules (only stricter)
-
-Add rules that narrow the baseline for this project, and name the baseline rule each one narrows. The rules `F1`..`F6`
-cannot be narrowed, so they never appear here. Example:
-
-| Rule | Project rule |
-|---|---|
-| F9  | Staging writes are limited to accounts named `qa-*` and names starting with `[asrun]`. |
-| F7  | This project runs production profiles only from a scheduled job; people use `--env staging`. |
-
-`pnpm asrun doctor` fails when this table names a `[non-negotiable]` rule.
-
-## 3. Project facts
-
-- Profiles and environments: `profiles.yaml`.
-- Areas: one folder per area below `cases/` (for example `cases/<area>/<name>.md`).
-- Expected values: they live in each case's `## Values` block, never here and never in `profiles.yaml`.
-- Who owns a finding, and where findings are reported: <fill in>.
-
-## Layout of this workspace
-
-- `cases/**/*.md`       human-written test cases (committed)
-- `tests/**/*.spec.ts`  generated Playwright specs and their `*-snapshots/` baselines (committed)
-- `profiles.yaml`       one entry per environment, connection settings only (committed)
-- `.auth/`              saved logins: never read, never commit
-- `reports/`            run reports: never commit
-- `{{framework}}/`  the framework (installed package): never edit
-- `.env`            local settings (`ASRUN_ROOT`): never commit
+# <project name> — asrun workspace
+
+This project uses the asrun framework, which lives in `{{framework}}` as an installed dependency. The framework is
+read-only here: never edit files inside it, and never commit test data into it.
+
+Read this file and the framework baseline it points at, before any AI step.
+
+## 1. How rules combine
+
+Rules are applied in this order, and a later layer wins where they conflict (the framework baseline, "Precedence"):
+
+1. `F1`–`F6` of the framework baseline: safety, in every project. Nothing here can change them.
+2. The framework baseline, `{{framework}}/AGENTS.md`.
+3. The framework skill (`{{framework}}/.claude/skills/<skill>/SKILL.md`).
+4. A project skill override, `.claude/skills/<skill>.md` (optional; the command and the skill read it).
+5. This file, §2 below: what this project does differently.
+
+The framework skills are loaded by the commands in `.claude/commands/` (Claude Code) and `.opencode/commands/`
+(OpenCode). The skills live in the framework package; §3 holds this project's facts.
+
+## 2. Project rules
+
+Only what differs from the baseline: name the rule id, and whether it `narrows` (stricter) or `replaces` (a different
+default, for example the artifact language) the baseline rule. `replaces` is refused for `F1`–`F6`. Rows whose first
+cell is not a rule id are ignored, so the placeholder below can stay until you need it.
+
+| Rule | Project rule | Effect |
+|---|---|---|
+| <rule id, e.g. F10> | <what this project does differently from the baseline> | narrows |
+
+Examples (delete what you do not use; the fenced block is an example, not a rule):
+
+```markdown
+| F10 | Case prose, report summaries and assertion messages in Simplified Chinese; code and commit messages stay English. | replaces |
+| F9  | Staging writes are limited to accounts named `qa-*` and names starting with `[asrun]`. | narrows |
+| F7  | This project runs production profiles only from a scheduled job; people use `--env staging`. | narrows |
+```
+
+`pnpm asrun doctor` fails when this table names a `[non-negotiable]` rule, an unknown rule id, or an `Effect` that is
+not `narrows` or `replaces`.
+
+The structural tokens are fixed English whatever the project language: the section headings (`## Values`, `## Targets`,
+...), a step's `- Recipe (phase): ...` lines, `### T<n>`, the `TODO` blocks with their `Answer:` line,
+`[input]`/`[writes]`/`[email]`, `RESULT:`, and the front-matter keys. See "Fixed tokens" in the framework baseline.
+
+## 3. Project facts
+
+- Profiles and environments: `profiles.yaml`.
+- Areas: one folder per area below `cases/` (for example `cases/<area>/<name>.md`).
+- Expected values: they live in each case's `## Values` block, never here and never in `profiles.yaml`.
+- Case document contract (front matter, steps, values, target cards, how a spec consumes them):
+  `{{framework}}/docs/agents/case-format.md`.
+- Who owns a finding, and where findings are reported: <fill in>.
+
+## Layout of this workspace
+
+- `cases/**/*.md`       human-written test cases (committed)
+- `tests/**/*.spec.ts`  generated Playwright specs and their `*-snapshots/` baselines (committed)
+- `profiles.yaml`       one entry per environment, connection settings only (committed)
+- `.claude/commands/`   `/make-case`, `/explore-case`, `/gen-spec`, `/heal-spec` for Claude Code
+- `.opencode/commands/` the same commands for OpenCode (it does not read `.claude/commands`)
+- `.claude/skills/`     optional overrides of a framework skill: `<skill>.md`
+- `.auth/`              saved logins: never read, never commit
+- `reports/`            run reports: never commit
+- `{{framework}}/`  the framework (installed package): never edit
+- `.env`            local settings (`ASRUN_ROOT`): never commit