@asrunjs/asrun 0.8.0 → 0.10.0

package/docs/ai-workflow.md

@@ -8,16 +8,31 @@ so the procedure lives in one place and a project can refine it (see
 | Command | What it does |
 |---|---|
 | `/make-case <notes-or-path>` | Turn raw notes into case documents. Optional step. |
-| `/explore-case <case-id> <env> [--attended]` | Open the real pages and write what they show into the case. |
-| `/gen-spec <case-id> <env> [--force]` | Write `tests/<case-id>.spec.ts` and fill the case's `## Values`. |
-| `/heal-spec <case-id> <env> [--profiles a,b] [--report <run-id>] [--hints <file>]` | Diagnose a failing spec from its last report and fix it. |
+| `/explore-case <case-id> <env> [--attended] [--profiles a,b] [--hints <file>]` | Open the real pages and write what they show into the case. |
+| `/gen-spec <case-id> <env> [--force] [--hints <file>]` | Write `tests/<case-id>.spec.ts` and fill the case's `## Values`. |
+| `/heal-spec <case-id> <env> [--profiles a,b] [--report <run-id>] [--hints <file>]` | Repair a failing spec, or refine a case and its spec on request, from the last report and what you asked for. |
 
 The environment is **required** by every command except `/make-case`, which does not open pages. There is no default.
 
-Every command ends with `RESULT: ready` or `RESULT: needs-input`. `needs-input` means somebody has to answer a
+`--profiles` exists on `/explore-case` and `/heal-spec`, not on `/gen-spec`: a spec runs once per profile in the
+environment, so it is generated from every profile the case holds information for, never from a chosen subset.
+
+`--hints <file>` (or free text after the arguments) is optional on all three commands that read a case: what you know,
+want checked or want changed. It guides that run. After the work, a reusable instruction that is **method**, not an
+expectation, is written into the case's `## Rules`; a one-off clue stays in the report. See
+[Rules for one case](#rules-for-one-case).
+
+Every command ends with `RESULT: ready` or `RESULT: needs-input` as plain text on its last line (never in a code fence
+or in emphasis: the web UI reads that line to show the outcome). `needs-input` means somebody has to answer a
 question in the case file (or, in the web UI, in the job's **Answer** sheet). A one-shot run cannot ask in the chat:
 it writes its questions into the case and stops.
 
+A one-shot run is a **build** run: it writes the case or the spec, never a plan. AsRun starts OpenCode with
+`--agent build`, because OpenCode keeps the agent (build or plan) on the session and a plan session would only propose
+changes and ask a question nobody can answer. Whatever mode a run finds itself in, it still ends with the `RESULT:`
+line: a run that was not allowed to write files (plan mode, a read-only sandbox) is `needs-input`, not a plan and a
+question.
+
 In the web UI you never type a command: choose the step in a case toolbar and press **Run AI**, or paste notes on
 **Cases > From memo**. The UI runs the selected AI tool and streams the output into the Jobs bar.
 
@@ -40,6 +55,19 @@ It writes `cases/<id>.md` only, and never overwrites an existing case. `pnpm cas
 `pnpm case:new header-logo` creates `cases/header-logo.md` from the template, or use a case you already have. The
 format is in [cases.md](./cases.md). Write the steps, the expectations and — when you know them — the values.
 
+### Rules for one case
+
+A case can hold a `## Rules` section: case-local instructions on **how** to run it (dismiss a cookie banner first, wait
+for a dialog after a request, never use an entry that needs 2FA). It is the place to talk to the agent without putting
+a requirement into the wrong section. One bullet per rule; `Step 3:`, `Before step 3:` or `After step 3:` ties it to a
+step, and `pnpm case:check` fails when that step does not exist.
+
+Rules never say what the case proves, never replace a step or an expected value, and never allow writing data, sending
+email or doing a person's step: those stay in `## Expected`, `## Values` and tagged steps with a recipe. The AI reads
+and applies every rule in every run, re-checks them against the page, and lists them in its report. `/explore-case`,
+`/gen-spec` and `/heal-spec` re-check the rules and never delete or rewrite one on their own; a rule that no longer
+holds becomes a question for you.
+
 ## 2. Explore the case (only where a person and the agent work together)
 
 ```
@@ -49,12 +77,19 @@ format is in [cases.md](./cases.md). Write the steps, the expectations and — w
 The agent opens the real pages of the profiles that are logged in and only **reads** them. It never creates, edits,
 publishes, shares or deletes anything, in staging or in production. It:
 
-- fixes wording in the case file and writes what the pages show into it, marked `observed, 🔍 to be confirmed by QA`;
+- fixes wording in the case file and writes what the pages show into it: a plain note `(seen on <profile>)` when the
+  run checks it, and `(observed on <profile>, 🔍 to be confirmed: <what a person must decide>)` only for a line that
+  would pass even if it were wrong;
 - turns what it cannot know into `🚫 TODO [blocking]` / `❓ TODO [non-blocking]` questions, each under a sentence that
   is its suggestion and can stand in the case as it is, with a last line `- ✍️ Answer:`;
 - lists the candidates instead of guessing a target (`## Targets`);
 - edits the case file only (plus reference screenshots under `.explore/targets/`).
 
+With many profiles, `--profiles a,b` opens only those (ids from `profiles.yaml`, comma-separated). The others are not
+opened and nothing is written about them, so a case can be explored in passes: A and B first, C later. Runs add up; the
+case keeps what the earlier runs recorded. In the web UI the profile picker of the toolbar does the same: every profile
+that is logged in in that environment is ticked, and the list you tick is remembered for the next run there.
+
 **To accept the suggestion, delete the whole block.** **To answer, write after `Answer:`.** Then run the command
 again. In the web UI, the run's **What to do next** bar offers **Answer**: the question list, an answer box,
 **Use the suggested defaults** and **Generate spec**. A continued job keeps the same conversation and permissions, and
@@ -68,7 +103,9 @@ the browser window opens and the agent waits while you do those steps.
 - The window shows a small draggable card in the bottom-left corner with what to do, **Done** (hand control back) and
   **Cannot do this**. The agent also continues by itself when the finish condition it named shows up (for example a
   "Saved" message); the card turns green when control is back. It waits up to 10 minutes per step.
-- What you did is recorded in the case under the step as **general recipe lines**
+- Recording starts and stops by itself. If Playwright's own recording toolbar shows at the top of the page, leave it
+  alone: it can stop the recording.
+- The card records what you did, and the agent writes it into the case under the step as **general recipe lines**
   (`- Recipe (phase): ...`): positions instead of names of changeable data, `[asrun]` names for created data, control
   labels but no selectors.
 - Delete the `[asrun]` items you created before you press Done on the last step.
@@ -92,8 +129,14 @@ Skip this for a `login: none` case. Sessions are per profile; see [profiles.md](
 ```
 
 The agent replays the case on the real pages with your saved sessions (it never writes data) and writes
-`tests/header-logo.spec.ts`. It fills the case's `## Values` for the profiles it explored and checks the files
-(`pnpm typecheck`, `pnpm case:check`; `pnpm spec:lint <case-id>` must have no failure).
+`tests/header-logo.spec.ts`. It fills the case's `## Values` for the profiles the case holds information for and checks
+the files (`pnpm typecheck`, `pnpm case:check`; `pnpm spec:lint <case-id>` must have no failure).
+
+Its profile scope comes from the case, not from a selection: every profile id the case names — the keys of
+`## Values`, a target card's `Reference <profile-id>:` line, an observation — plus `default`. That is why one run per
+subset adds up: explore A and B first and C later, and `/gen-spec` covers all three. A profile the case says nothing
+about runs on `default` alone, and the report names it. A profile that is not logged in is not dropped: its part is
+written from the case and marked `not verified on the page`.
 
 It does **not** run the spec and does **not** create screenshot baselines: running is a separate step (6).
 
@@ -125,7 +168,7 @@ profile. Baselines are the source of truth for pixel checks.
 Then run all profiles and read the report: the video of each test, screenshots on failure, and the trace with the page
 and the network requests. See [commands.md](./commands.md) for filters and baselines.
 
-## Healing a failing spec
+## Healing or refining a spec
 
 ```
 /heal-spec header-logo staging
@@ -133,14 +176,17 @@ and the network requests. See [commands.md](./commands.md) for filters and basel
 
 or **Heal spec** in the case toolbar, or **Heal this failure** on a failed result of the Reports page.
 
-The agent decides whether the test needs updating or whether it found a real product problem. It **never** edits an
-expectation just to make a failure disappear.
+The command does two jobs: it repairs a spec that fails, and it refines a case and its spec when you ask for an
+improvement. A passing last run is not a reason to refuse a request. It decides whether the test needs updating or
+whether it found a real product problem, and it **never** edits an expectation just to make a failure disappear.
 
 - The environment is required. Only the profiles that are logged in there run (`--logged-in` leaves the others out
   instead of failing them).
-- The web UI first opens a dialog: which profiles to heal (every logged-in profile ticked) and an optional text box
-  for what you want healed, with evidence or clues. The text is stored in `.tmp/hints/` and passed as `--hints`.
-  Clues guide the diagnosis; they never lower the bar for a product finding.
+- The web UI first opens a dialog: which profiles to run (every logged-in profile ticked) and an optional text box
+  for what should be repaired or improved, with evidence. The text is stored in `.tmp/hints/` and passed as `--hints`.
+  It guides the work; it never lowers the bar for a product finding. A reusable instruction that is method rather than
+  an expectation is also written into the case's `## Rules` (see [Rules for one case](#rules-for-one-case)); a one-off
+  clue stays in the report.
 - It reads the existing report first:
 
   ```bash
@@ -149,13 +195,24 @@ expectation just to make a failure disappear.
 
   It prints status, failed step, error, call log and screenshots per profile, and whether the report is fresh or
   stale. The case is run again only when there is no report, the report is stale, it does not explain the failure, or
-  a clue has to be checked. After editing the spec, it runs the case once to confirm.
+  a request has to be checked. It reads the pages (read-only) when a change has to be judged on them, and it never
+  performs a step that writes data. After editing the spec, it runs the case once to confirm.
+- The case is the source of truth: a change to a step, an expectation, a value or a target is written into the case
+  first, then into the spec. A large change regenerates the spec from the case.
+- **Review gate.** If the change leaves an open question or a `🔍 to be confirmed` marker in the case, healing stops
+  before the spec: you review the case, answer what it asks or settle the marker (the panel shows why it needs you, and
+  `pnpm markers:confirm` settles the ones a passing run already checks), then run `/explore-case` again. The spec is
+  generated after that, not before. A plain `(seen on <profile>)` note never stops it: the run checks those. A marker
+  inside `## Rules` does not stop the spec either, unless it covers a literal the spec asserts.
 
 ## Why a generated spec can be trusted
 
-Three binding rules hold in exploring, generating and healing. They live in the framework's `AGENTS.md` and in
-`.claude/skills/exploring-cases/references/assertion-targets.md` and `readiness.md`.
+Several binding rules hold in exploring, generating and healing. They live in the framework's `AGENTS.md` and in
+`.claude/skills/exploring-cases/references/case-rules.md`, `assertion-targets.md` and `readiness.md`.
 
+- **Case rules.** A `## Rules` bullet says how to run the case, never what it proves. The agent applies it while
+  exploring and generating, marks code that exists only because of a rule with `// rule: <short quote>`, and lists every
+  rule in its report. It never becomes an assertion and never authorizes a write or a person's step.
 - **Targets.** A check on a logo, image, icon, file, PDF, screenshot or repeated text points to a `[T1]` card under
   `## Targets`: what it is (and what it is not), where it is, how it is identified (never `.first()` or a bare `img`),
   when it is ready, and a highlighted reference screenshot under `.explore/targets/`. When in doubt the agent does not
@@ -177,7 +234,8 @@ Checks you can run yourself:
 |---|---|
 | `pnpm spec:lint [case-id]` | fails on screenshots without a target, `.first()` on images, sleeps, `networkidle`, raw download events, a `%PDF` check on its own |
 | `pnpm baselines:review [case-id] [--new]` | lists every baseline with the card that says what it must show, so you can look at each new image |
-| `pnpm case:check [case-id]` | fails on an incomplete card or bad values; warns on an image check with no card |
+| `pnpm case:check [case-id]` | fails on an incomplete card, bad values, a marker inside a question or a question under a marked line; warns on an image check with no card and on a marker that does not say what to decide |
+| `pnpm markers:confirm --case <id> --env <env> [--report <run-id>]` | after a passing run, removes the `🔍 to be confirmed` markers whose line the spec checks with `// unconfirmed:`; `--dry-run` lists them |
 | `pnpm pdf:render <file.pdf> --out <dir> [--pages all] [--corner top-left]` | renders the pages to images and prints the text, to look at a PDF by hand |
 
 ## Customizing the prompts
@@ -198,11 +256,12 @@ A project refines a skill with a **flat override file**, named after the skill (
 The command and the skill read it; it is not discovered as a standalone skill. Rules combine in this order, and a
 later one wins where they conflict:
 
-1. `F1`–`F6` of the framework baseline: safety, in every project. Nothing can change them.
+1. `F1`–`F6` and `R2` of the framework baseline: safety, in every project. Nothing can change them.
 2. The framework baseline, `<framework>/AGENTS.md`.
 3. The framework skill.
 4. The project override `.claude/skills/<skill>.md`.
 5. The project's own `AGENTS.md` §2 (Project rules).
+6. A case's `## Rules`: how to run that one case, never what is true.
 
 An override is plain Markdown; write only what differs:
 
@@ -214,8 +273,8 @@ An override is plain Markdown; write only what differs:
 - The staging account has no published documents: assert the empty state there instead.
 ```
 
-The project's `AGENTS.md` §2 is the other place: a table of rule ids (`F7`–`F10`; `F1`–`F6` are fixed) with `narrows`
-(stricter) or `replaces` (a different default). For example, a project that writes cases in Simplified Chinese
+The project's `AGENTS.md` §2 is the other place: a table of rule ids (`F7`–`F10`, `R1`, `R3`, `R4`; `F1`–`F6` and
+`R2` are fixed) with `narrows` (stricter) or `replaces` (a different default). For example, a project that writes cases in Simplified Chinese
 `replaces` `F10`. `pnpm asrun doctor` fails on an unknown id, a missing `Effect`, or a non-negotiable rule, and lists
 the overrides it sees.
 

package/docs/cases.md

@@ -31,6 +31,9 @@ suites: [smoke, regression]
 ## Goal
 Why this case exists, in one or two sentences.
 
+## Rules
+- Before step 1: dismiss the cookie banner; it covers the header.
+
 ## Steps
 1. Open `/`.
     - Ready when: the header has rendered its menu.
@@ -63,8 +66,8 @@ example-staging:
 Anything a reviewer should know.
 ````
 
-The headings are fixed English tokens (`Goal`, `Steps`, `Expected`, `Values`, `Visual checks`, `Targets`, `Notes`,
-and `Source` when the case was made from raw notes). A project language never translates them.
+The headings are fixed English tokens (`Goal`, `Rules`, `Steps`, `Expected`, `Values`, `Visual checks`, `Targets`,
+`Notes`, and `Source` when the case was made from raw notes). A project language never translates them.
 
 ## Front matter
 
@@ -80,6 +83,21 @@ and `Source` when the case was made from raw notes). A project language never tr
 
 `priority: <level>` is the old name of `suites`; it is read as `suites: [<level>]`. Do not use both.
 
+## Rules
+
+Optional, case-local instructions for the AI agents that explore, generate and heal this case: **how** to run it, never
+**what it proves**. One bullet per rule. A bullet may start with `Step 3:`, `Before step 3:` or `After step 3:` to tie
+it to that step; `pnpm case:check` fails when the step does not exist. A rule without a prefix applies to the whole case.
+
+- Use it for a page quirk, a mandatory read-only preparation (dismiss a cookie banner), a control to avoid, or a
+  waiting/attention hint.
+- Do not put an expectation, a literal or a target here: those stay in `## Expected`, `## Values` and `## Targets`.
+- A rule never allows creating, changing or deleting data, sending email or doing a person's step. Those stay tagged
+  steps with a recipe.
+- A rule that conflicts with the rest of the case is a blocking question, not an override. `/explore-case` re-checks
+  each rule against the page and never deletes one silently.
+- The framework baseline's `R1`–`R4` define exactly what a rule may say.
+
 ## Steps
 
 Numbered lines. Keep them short and in plain language: the spec uses each step's text verbatim in `test.step`, so the
@@ -97,8 +115,13 @@ report and the trace read like the case.
   generated: `/gen-spec` stops with `needs-input`.
 - **Open questions** go in a `🚫 TODO [blocking]` or `❓ TODO [non-blocking]` block under the sentence they are about,
   with the agent's suggestion written above and a last line `- ✍️ Answer:`. Accepting a question means deleting the
-  whole block; answering means writing after `Answer:`. The marker `🔍 to be confirmed by QA` / `👁️ not observed`
-  marks something seen but not settled.
+  whole block; answering means writing after `Answer:`. Hang the block under the sentence that makes the claim, not
+  under a broader one above it, and one claim gets one block.
+- **What the AI saw** is marked by what happens if it is wrong: `(seen on <profile>)` is a plain note the run checks by
+  itself, and `(observed on <profile>, 🔍 to be confirmed: <what a person must decide>)` is a line that would pass even
+  if it were wrong, so a person settles it. A marker may name a screenshot (`evidence: .explore/.../x.png`) so nobody
+  has to open the page again. Never put a marker inside a TODO block, on the sentence a block hangs under, or inside
+  the `## Values` yaml: one claim carries one signal. `pnpm case:check` fails on the first two.
 
 ## Expected
 
@@ -174,6 +197,7 @@ It reads every case (or the ids you pass) and prints one line per case. It **fai
 - a target card without its required fields (`What`, `Where`, `Identified by`), or a reference image outside
   `.explore/targets/<case-id>/`;
 - a `[T<n>]` reference with no card;
+- a `## Rules` bullet that names `Step <n>`, `Before step <n>` or `After step <n>` when the case has no such step;
 - an invalid `## Values` block (bad YAML, an unknown profile, a non-map entry).
 
 It **warns** (usable, but something to settle) on: a reference image missing on this machine (`.explore/` is

package/docs/commands.md

@@ -21,6 +21,7 @@ thin wrappers, so `pnpm asrun`, `pnpm signin` and the rest work as below. The sa
 | Read what the last report says about a case | `pnpm heal:evidence --case <case-id> --env <env>` |
 | List or forget test data that could not be removed | `pnpm cleanup --env <env> [--forget]` |
 | Create or validate a case | `pnpm case:new <id>`, `pnpm case:check [case-id]` |
+| Settle the "to be confirmed" lines of a case from a passing run | `pnpm markers:confirm --case <case-id> --env <env> [--dry-run]` |
 | Check a spec | `pnpm spec:lint [case-id]`, `pnpm baselines:review [case-id] [--new]` |
 | Look at a PDF | `pnpm pdf:render <file.pdf> --out <dir> [--pages all] [--corner top-left]` |
 | Type-check the workspace | `pnpm typecheck` |
@@ -125,7 +126,11 @@ pnpm pdf:render report.pdf --out .explore/targets/header-logo --corner top-left
 ```
 
 - `case:new` creates the case from the template. One optional group folder, created on demand.
-- `case:check` validates front matter, values and target cards; see [cases.md](./cases.md).
+- `case:check` validates front matter, values and target cards; it fails on a marker inside a question block, a marker
+  on the line a question hangs under, and a marker inside the `## Values` yaml. See [cases.md](./cases.md).
+- `markers:confirm` reads the newest run report (or `--report <run-id|file>`) and removes the `🔍 to be confirmed`
+  markers whose line the spec carries as `// unconfirmed: ...`, but only when every test of the case passed. It answers
+  "does the page still say this?", never "is this the right expectation".
 - `spec:lint` is a static check of the specs: it fails on sleeps, `networkidle`, image checks without a target,
   `.first()` on images, raw download events, a magic-number-only PDF check. `pnpm spec:lint <case-id>` limits it.
 - `baselines:review` opens nothing; it lists every baseline next to the target card that says what it must show.

package/docs/theme-guide.html

@@ -257,6 +257,29 @@
   .side .item { padding: 8px 16px 8px 12px; border-bottom: 1px solid var(--line); border-left: 4px solid transparent; font-family: var(--mono); font-size: 14px; }
   .side .item.selected { background: var(--theme-bg); border-left-color: var(--theme); }
 
+  /* Filter bar (mirror components/filter-chips.tsx and components/search-field.tsx). */
+  .filters { display: flex; flex-wrap: wrap; align-items: center; gap: 4px; }
+  .filters .group-label { margin-right: 2px; font-size: 12px; color: var(--ink-3); }
+  .filter-chip {
+    display: inline-flex; align-items: center; gap: 4px; height: 24px; padding: 0 6px; border-radius: 2px;
+    background: var(--card); color: var(--ink-2); font-size: 12px; box-shadow: inset 0 0 0 1px var(--line-mid);
+  }
+  .filter-chip .count { color: var(--ink-3); }
+  .filter-chip.on {
+    background: var(--theme-btn); color: #fff; font-weight: 500;
+    box-shadow: inset 0 0 0 1px var(--theme-btn);
+  }
+  .filter-chip.on .count { color: rgb(255 255 255 / .75); }
+  .filter-chip.on.production { background: var(--jiang); box-shadow: inset 0 0 0 1px var(--jiang); }
+  .filter-chip.on.staging { background: var(--cheng); box-shadow: inset 0 0 0 1px var(--cheng); }
+  .filter-chip.on.other { background: var(--gold-deep); box-shadow: inset 0 0 0 1px var(--gold-deep); }
+  .filter-search { position: relative; width: 260px; max-width: 100%; }
+  .filter-search svg { position: absolute; left: 8px; top: 50%; transform: translateY(-50%); color: var(--ink-3); }
+  .filter-search .fake {
+    display: flex; align-items: center; height: 32px; padding: 0 8px 0 28px; border: 1px solid var(--line-mid);
+    border-radius: 4px; background: #fff; color: var(--ink-3); font-size: 14px;
+  }
+
   .seal-stamp {
     display: inline-flex; align-items: center; justify-content: center; width: 28px; height: 28px; border-radius: 3px;
     background: var(--seal); color: var(--paper); font-family: var(--serif); font-weight: 400; font-size: 16px; line-height: 1;
@@ -302,6 +325,7 @@
     <a href="#badges">Badges</a>
     <a href="#action-colors">Action colors</a>
     <a href="#dropdowns">Dropdowns</a>
+    <a href="#filter-bars">Filter bars</a>
     <a href="#multi-value">Multi-value fields</a>
     <a href="#icons">Icons</a>
     <a href="#tooltips">Tooltips</a>
@@ -503,6 +527,7 @@
         <tr><td><code>info</code> (light blue)</td><td>A view toggle that must be easy to find, not an action on data: "Full screen" / "Restore" in the Jobs drawer bar. Blue = read-only.</td></tr>
         <tr><td><code>secondary</code> (white)</td><td>Everything else: Verify, Visit, Discard, Copy, navigation.</td></tr>
         <tr><td><code>danger</code> (white, red text)</td><td>Cancel a running job, destructive confirmations.</td></tr>
+        <tr><td><code>invalid</code> (red field)</td><td>A control that is required and still empty, drawn as a button because it opens a panel instead of a native list (the environment picker of the case toolbar). The same red as an invalid dropdown; it is not an action.</td></tr>
       </tbody>
     </table>
     <p class="small muted">Hover lifts the button 1px; disabled is 50% opacity with no shadow. With an icon, add <code>gap-1.5</code> to the button.</p>
@@ -522,7 +547,7 @@
       <tbody>
         <tr><td><span class="badge green">green</span></td><td>ok: Logged in</td><td>Succeeded</td></tr>
         <tr><td><span class="badge red">red</span></td><td>expired, missing</td><td>Failed</td></tr>
-        <tr><td><span class="badge amber">amber</span></td><td>unverified, error</td><td>Needs your input (an AI run that ended with <code>RESULT: needs-input</code>)</td></tr>
+        <tr><td><span class="badge amber">amber</span></td><td>unverified, error</td><td>Needs your input (an AI run that ended with <code>RESULT: needs-input</code>) or No result (a run that printed no <code>RESULT:</code> line at all)</td></tr>
         <tr><td><span class="badge blue">blue</span></td><td>-</td><td>Running</td></tr>
         <tr><td><span class="badge gray">gray</span></td><td>-</td><td>Cancelled</td></tr>
       </tbody>
@@ -584,7 +609,7 @@
       <tbody>
         <tr><td><code>explore-case</code></td><td>blue (qing)</td><td>Edits only the case file (wording, observations, open questions, inputs). The agent only reads pages; you do the steps that write data.</td></tr>
         <tr><td><code>gen-spec</code></td><td>amber (gold)</td><td>Writes: creates the spec and fills the case's <code>## Values</code>. Does not run the tests.</td></tr>
-        <tr><td><code>heal-spec</code></td><td>red (seal)</td><td>Rewrites an existing spec and runs the tests.</td></tr>
+        <tr><td><code>heal-spec</code></td><td>red (seal)</td><td>Repairs the spec or refines the case and the spec, then runs the tests.</td></tr>
       </tbody>
     </table>
     <p class="small muted">
@@ -600,6 +625,14 @@
       <code>Select</code> is a button that draws its own list under it, in a <code>card-popup</code> panel, which is what
       gives every dropdown the same raised look.
     </p>
+    <p class="small muted">
+      Two controls put their label inside the button and open a panel with a title rather than a bare list: the
+      environment picker of the case toolbar (<code>Env: staging</code>, <code>components/env-picker.tsx</code>) and the
+      profile picker beside it (<code>Profiles: 2 of 3</code>, <code>components/profile-picker.tsx</code>). They are
+      buttons because their list needs a title and a line of explanation, not a <code>Select</code>; they keep this
+      section's height, <code>card-popup</code> panel, keyboard and click-outside rules. Do not turn them back into a
+      <code>Select</code> that repeats the label on every row.
+    </p>
     <div class="demo">
       <span class="select"><span class="fake">staging</span><svg class="chev" xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="6 9 12 15 18 9"></polyline></svg></span>
       <span class="select focus"><span class="fake">staging</span><svg class="chev" xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="6 9 12 15 18 9"></polyline></svg></span>
@@ -654,6 +687,60 @@
       </tbody>
     </table>
 
+    <h3 id="filter-bars">Filter bars</h3>
+    <p>
+      A list that can get long (the profiles of the workspace, the profiles of a case's Values table) gets a filter bar
+      above it: <code>SearchField</code> and <code>FilterChips</code> from <code>ui/web/src/components/</code>. They are
+      controls only; the page decides what a value means and filters its own rows.
+    </p>
+    <div class="demo" style="display:block">
+      <div class="filter-search" style="margin-bottom:8px">
+        <svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="11" cy="11" r="8"></circle><line x1="21" y1="21" x2="16.65" y2="16.65"></line></svg>
+        <span class="fake">atpil</span>
+      </div>
+      <div style="display:flex;flex-wrap:wrap;gap:8px 16px">
+        <div class="filters">
+          <span class="group-label">Env</span>
+          <span class="filter-chip">All <span class="count">17</span></span>
+          <span class="filter-chip on production">PRODUCTION <span class="count">7</span></span>
+          <span class="filter-chip on staging">STAGING <span class="count">8</span></span>
+          <span class="filter-chip">SANDBOX <span class="count">2</span></span>
+        </div>
+        <div class="filters">
+          <span class="group-label">Tag</span>
+          <span class="filter-chip">All <span class="count">17</span></span>
+          <span class="filter-chip on">atp <span class="count">6</span></span>
+          <span class="filter-chip">compass <span class="count">4</span></span>
+          <span class="filter-chip">corp <span class="count">4</span></span>
+        </div>
+      </div>
+      <p class="small muted" style="margin:8px 0 0">Showing 6 of 17 profiles · <span style="text-decoration:underline">Clear filters</span></p>
+    </div>
+    <p class="small muted">
+      Search "atpil" with the dashes left out, both environments pressed and one tag: the two groups are combined with
+      AND.
+    </p>
+    <pre class="card mono" style="overflow:auto">import {SearchField} from '../components/search-field';
+import {FilterChips} from '../components/filter-chips';
+
+&lt;SearchField value={query} onChange={setQuery} ariaLabel="Search profiles" placeholder="Search id, name..." /&gt;
+&lt;FilterChips label="Env" selected={envFilter} onChange={setEnvFilter} allCount={profiles.length}
+  options={envs.map((env) =&gt; ({value: env, label: env.toUpperCase(), count: countOf(env), tone: envFillClass(env)}))} /&gt;</pre>
+    <table>
+      <thead><tr><th>Part</th><th>Rule</th></tr></thead>
+      <tbody>
+        <tr><td>Search</td><td>One <code>SearchField</code> at the top. It looks in id, name, account, environment, tags and address; every word of the query must match one of them. A compact copy without <code>-</code>, <code>_</code>, <code>.</code> or spaces lets <code>atpil</code> find <code>atp-il-staging</code>.</td></tr>
+        <tr><td>Groups</td><td>One <code>FilterChips</code> per kind of value (environment, tag). Inside a group a row matches <b>any</b> pressed value; the groups are combined with <b>AND</b>. An empty group filters nothing.</td></tr>
+        <tr><td>All</td><td>The first chip of a group clears that group only. It is pressed while the group has no selection, so "no filter" can always be told from "everything selected".</td></tr>
+        <tr><td>Counts</td><td>Each option shows how many rows it would leave, and <code>All</code> shows the group's total. Counts come from the unfiltered list, so they do not dance while a value is pressed.</td></tr>
+        <tr><td>Pressed look</td><td>Neutral chips take the page accent (<code>theme-btn</code>, white text). Environment chips pass <code>envFillClass(env)</code>, the same solid marker as <code>EnvBadge</code>, so color means the environment here too.</td></tr>
+        <tr><td>State</td><td>The chip is the button: <code>aria-pressed</code>, a tooltip with its name (and "pressed" while on), and the count as a second, quieter part of the label.</td></tr>
+        <tr><td>Feedback</td><td>While a filter is active, show <code>Showing N of M</code> and <b>Clear filters</b>. When nothing matches, the empty state repeats the clear action instead of leaving a blank table.</td></tr>
+        <tr><td>Not remembered</td><td>A filter is a way of looking, not a setting: do not put it in <code>localStorage</code>. A reload shows everything, so nothing looks missing after lunch.</td></tr>
+        <tr><td>In the case panel</td><td>The Values table adds a two-button <b>Rows: Keys / Profiles</b> switch beside the search as soon as a case names two profiles, and shows the search and the environment chips only when it names more than three. The filters and the switch belong to that case; opening another case starts unfiltered.</td></tr>
+      </tbody>
+    </table>
+
     <h2 id="multi-value">Multi-value fields</h2>
     <p>
       A field whose value is a list is never a <a href="#dropdowns">Dropdown</a> plus an "Add" text input: that mixes a
@@ -829,11 +916,12 @@
     </p>
     <p class="muted">
       The preview block that holds the editor caret is shaded with <code>theme-bg</code> at 60% and a 2px <code>theme</code> left
-      border (an overlay, so it follows the page theme). The editor and the preview scroll together and a click in the preview
-      moves the caret; the logic is in <code>ui/web/src/lib/preview-sync.ts</code>.
+      border (an overlay, so it follows the page theme). The overlay paints <b>behind</b> the text, never over it: the
+      highlighted block keeps its own text color instead of looking washed out. The editor and the preview scroll together
+      and a click in the preview moves the caret; the logic is in <code>ui/web/src/lib/preview-sync.ts</code>.
     </p>
     <p class="muted">
-      The previous / next buttons of the case toolbar move the caret to the next marker and blink that marker for a moment in
+      The previous / next buttons at the right end of the editor toolbar move the caret to the next marker and blink that marker for a moment in
       both panes (<code>cm-kw-flash</code> in the editor, <code>kw-flash</code> over the <code>&lt;mark&gt;</code> of the
       document): <code>gold-glow</code> at 65% behind it and a 2px <code>dai-deep</code> ring with a wider
       <code>gold-glow</code> glow around it, the ring blinking on and off three times (0.45&nbsp;s each), then it goes away.

package/docs/troubleshooting.md

@@ -57,6 +57,11 @@ and regenerate the spec.
 `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 case:check` fails on a marker** — the same claim carries two signals: a marker word inside a question block, a
+marker on the line a question hangs under, or a marker inside the `## Values` yaml (where it would become part of the
+expected value). Keep one of the two, and move a `## Values` marker to the prose line above the block. A marker without
+a reason is only a warning: write `🔍 to be confirmed: <what a person must decide>`.
+
 **`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.
@@ -69,6 +74,10 @@ is recorded.
 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).
 
+**`/explore-case` takes long with many profiles** — pass `--profiles a,b` (the toolbar's profile picker does the same):
+only those profiles are opened, and a later run with the others adds what it finds. `/gen-spec` has nothing to pick: it
+covers every profile the case names.
+
 ## Installing
 
 **`pnpm add` installs the previous release instead of `latest`** — pnpm holds back versions published in the last
@@ -113,6 +122,41 @@ cases, specs, `profiles.yaml` and `package.json` stay. Then run `pnpm dlx @asrun
 `claude mcp list`; `failed: ... path specified` means the `playwright` path in that file does not resolve (repair it
 with `pnpm asrun init --force <file>`).
 
+**A `browser_*` tool says `Tool "<name>" not found`** — expected for part of them: the `playwright-test` MCP
+(`run-test-mcp-server`) lists every browser tool Playwright has, but a call runs in a paused test whose backend installs
+only the `core` and `testing` capabilities, plus it never installs the `skillOnly` tools. The server is up and the other
+tools work: use the substitute in `.claude/skills/exploring-cases/references/tools.md` and do not report a missing MCP
+server. `browser_highlight` / `browser_hide_highlight` become `locator.highlight()` / `page.hideHighlight()` through
+`browser_run_code_unsafe`, `browser_network_clear` becomes a marker on the request list,
+`browser_start_recording` / `browser_stop_recording` are never called (the handoff card,
+`.claude/skills/exploring-cases/references/handoff-card.js`, starts and stops the recording itself and returns
+`recorded`). `browser_annotate` cannot run either: the person names the element in the handoff card. `pnpm asrun doctor`
+prints how many tools the installed Playwright runs and warns when `tools.md` names one it cannot.
+
+**An AI run stops answering and never finishes** — the log keeps repeating `... still waiting for <tool call> (running
+5m 30s)` or `... no output from the agent for 5m`, and nothing else arrives. A workspace has exactly one
+`playwright-test` MCP server (the `run-test-mcp-server` child process OpenCode starts from `opencode.jsonc`), shared by
+every session in that workspace, and Playwright runs one paused test in it at a time. One interrupted browser call —
+closing the browser window by hand, cancelling a run while a call is in flight, or a second AI run using the same
+server — leaves that queue wedged: the call never returns and every later run hangs on its first
+`generator_setup_page` until the process is replaced. `pnpm asrun doctor` cannot see it, because it starts a fresh
+server of its own. Cancel the stuck run, quit and restart OpenCode (that ends its MCP processes), then start the run
+again. From the UI this is bounded: only one AI run at a time runs per workspace (the `ai` job lock, whatever case it is
+on), and a run that says nothing for 10 minutes — 15 while a handoff card waits for a person — is stopped with this
+instruction in its log.
+
+**The UI server restarted while an AI run was going** — the job is still in the Jobs drawer, marked **Interrupted**,
+and its log stops where the server died. If the agent (and the `playwright-test` MCP server below it) is still running,
+the job offers **Stop the leftover process**; stop it before starting another AI run, or both agents share one MCP
+server and wedge it. A job that had already written `RESULT: needs-input` is recovered as **Succeeded**, so its answers
+can still be sent. Every finished job has **Run again**, which reuses the inputs it was started with.
+
+**A call fails with `Missing key`** — the published schema requires two things that are easy to leave out: `intent` on
+every action, input and assertion tool (`browser_click`, `browser_type`, `browser_evaluate`, `browser_run_code_unsafe`,
+`browser_wait_for`, ...), and the fields that have a default (`browser_take_screenshot` needs `scale: "css"`,
+`browser_network_requests` needs `static: false`, `generator_setup_page` needs `plan`). The full list is in
+`.claude/skills/exploring-cases/references/tools.md`.
+
 **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,
@@ -131,6 +175,6 @@ read it. `doctor` lists the overrides it sees.
 project. Add `--reset-rules` to replace them with the template, and expect to lose the project's rules.
 
 **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.
+edits the case and the spec and runs the spec 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.