@iamu-dev/iamu 0.6.0-beta.0 → 0.8.0-beta.0

package/dist/templates/prompts/advise.md

@@ -66,6 +66,7 @@ Work in this order. Do not skip ahead to writing fixes.
 - Recommendations, quick fixes and direction texts are prose for a product person and a developer reading together. Plain, specific, in the product's own words.
 - **No file paths or code symbols in the prose.** They go in `builds_on` only. The prose is shown to a later walker who must stay outside the code.
 - A recommendation says what the person would see and why it meets their need, then how it fits this product.
+- **Titles** of directions and observations: A title is a headline someone scans in a list: what changes for the person (a direction) or what is missing or risky (an observation), in a few words. Aim for about 60 characters; the detail belongs in the fields below it. Meaning comes first: never drop a word that carries it just to be shorter. A clear title of 75 characters beats a cryptic one of 40. Too long: "The equipment picker has no mobile vehicles and its menu captures focus over the free-text field". Better: "Equipment list has no forklifts; open menu blocks free text".
 
 ## Answer
 

package/dist/templates/prompts/complete.md

@@ -31,7 +31,7 @@ Write `iamu/.runs/<run-id>/canonical.json`:
     "browser": "chrome-devtools"
   },
   "provenance": {
-    "walker_prompt": { "id": "walkthroughPhilosophy", "version": "2.0.0" },
+    "walker_prompt": { "id": "walkthroughPhilosophy", "version": "<the walker prompt version; iamu complete records the current one>" },
     "model": "unspecified",
     "started_at": "<created_at from manifest>",
     "completed_at": "<current ISO timestamp>"

package/dist/templates/prompts/design-review.md

@@ -16,17 +16,26 @@ You review one surface of the product: a page, its states, and the flows that pa
 - **Name the rule.** When an issue breaks a rule in the design docs, give the rule's name exactly as the doc writes it (its heading, or the bold words that open it) as `rule`, and the entry it is in (from `design.files`) as `file`. When the same name occurs twice in one file, write `Section > Name`.
 - **When a rule hurts a need, say so.** If following a rule is what fails a visitor (the rule keeps a caveat small and grey, and the person missed it), report a `conflict`: the rule and its file, the rule's text copied exactly from the doc as `before`, better wording as `after`, the evidence, and why. Do not silently break the rule or silently follow it. A person decides.
 - **Prefer removing, merging and hiding by role to adding.** Every element must earn its place.
+- **Confirm resolved problems.** When a problem in `problems` or an unverified fix in `fix_history` (`state: "awaiting_rerun"`, carrying a `ref` like `F1`, `F2`, ...) is now visibly fixed on the live surface, list it in `resolved` with its `ref` (`"F1"`) and one sentence (`how`) describing what on the live screen resolves the visitor's need. Never list the same ref in both `issues[].evidence` and `resolved`.
 - **Be specific.** "The approve button and the reject link share one grey; the reject reads as disabled", not "improve hierarchy". Do not manufacture issues: a clean surface is a valid answer.
 
 Severity: `critical` (broken, unreachable, unreadable), `major` (a visitor's need is not met, or the surface is clearly inconsistent), `minor` (polish), `nit` (preference).
 
 ## Answer
 
+**Titles.** A title is a headline someone scans in a list: what is wrong and where, in a few words. Aim for about 60 characters; the detail belongs in `what` and `why`. Meaning comes first: never drop a word that carries it just to be shorter. A clear title of 75 characters beats a cryptic one of 40. Too long: "The equipment picker has no mobile vehicles and its menu captures focus over the free-text field". Better: "Equipment list has no forklifts; open menu blocks free text".
+
 Reply with one JSON object and nothing else:
 
 ```json
 {
   "summary": "What this surface is for, for whom, and how well it serves them (two to four sentences).",
+  "resolved": [
+    {
+      "ref": "F1",
+      "how": "What on the live screen now resolves this visitor's need"
+    }
+  ],
   "issues": [
     {
       "title": "Short title",

package/dist/templates/prompts/designer.md

@@ -50,6 +50,8 @@ A correct refusal whose reason is on the screen is not `critical`: the product i
 
 ## Answer
 
+**Titles.** A title is a headline someone scans in a list: what is wrong and where, in a few words. Aim for about 60 characters; the detail belongs in `what` and `why`. Meaning comes first: never drop a word that carries it just to be shorter. A clear title of 75 characters beats a cryptic one of 40. Too long: "The equipment picker has no mobile vehicles and its menu captures focus over the free-text field". Better: "Equipment list has no forklifts; open menu blocks free text".
+
 Reply with one JSON object and nothing else:
 
 ```json

package/dist/templates/prompts/walk.md

@@ -192,6 +192,7 @@ The CLI automatically handles sequential numbering, timestamps, screenshot captu
 iamu new-finding --scenario <slug> --run <run-id> --title "Short title" --type hinders --severity major --ui-fact "What the UI showed" --consequence "Impact on persona" --task-impact impairs --confidence high --need "What I needed at that moment" --description "What happened and why it mattered" --json
 ```
 
+- `--title`: A title is a headline someone scans in a list: what goes wrong (or works) and where, in a few words. Aim for about 60 characters; the detail belongs in `--ui-fact`, `--consequence` and `--description`. Meaning comes first: never drop a word that carries it just to be shorter. A clear title of 75 characters beats a cryptic one of 40. Too long: "The equipment picker has no mobile vehicles and its menu captures focus over the free-text field". Better: "Equipment list has no forklifts; open menu blocks free text".
 - `--type`: `helps | hinders | missing | irrelevant | incorrect`
 - `--severity`: `critical | major | minor | nit`
 - `--task-impact`: `blocks | impairs | slows | neutral | accelerates | enables`

package/dist/templates/skills/iamu-design.md

@@ -1,6 +1,6 @@
 ---
 name: iamu-design
-description: Use when recording where the project's design docs are, reviewing the design of a page (interaction, layout, look and feel), deciding proposed edits to the design docs, pointing agents at the docs, or fixing a finding with a visual check.
+description: Use when recording where the project's design docs are, starting a design doc from a template when there is none, reviewing the design of a page (interaction, layout, look and feel), deciding proposed edits to the design docs, pointing agents at the docs, or fixing a finding with a visual check.
 generatedBy: __IAMU_VERSION__
 ---
 
@@ -19,6 +19,7 @@ Run `iamu design status --json`. It lists the recorded design files (`files`, ea
 Pick the mode from the user's words, or from the status when they asked generally:
 
 - no files recorded → **A. Record the design docs**;
+- no design doc recorded and none found, or "write us a design doc" → **E. Start a design doc from the template**;
 - a legacy `iamu/design.md` not yet migrated → **A3. Migrate the legacy doc** (offer it once);
 - "review this page / the request form / this finding's page / this direction" → **B. Review a surface**;
 - open proposals, or "what should change in our design docs" → **C. Decide proposed edits**;
@@ -37,7 +38,7 @@ Show the candidates once as a short list (kind, path, why) and ask once which to
 - a kind detection got wrong: `--kind design | product | tokens | components`;
 - in a monorepo, the part of the product a doc covers: `--applies-to /app` (URL path prefixes) or `--applies-to apps/dashboard` (an app's folder). Runs, reviews and fixes then use the right doc.
 
-If nothing is found, say so in one line. Walks and reviews run without design docs; iamu does not write one for the team.
+If no design doc is found (only tokens and components, or nothing), say so in one line and offer **E** once, as a question the user may skip. Walks and reviews run without design docs.
 
 ### A2. Point agents at the docs
 
@@ -75,12 +76,40 @@ Run `iamu design proposals --json` and decide each open proposal exactly as the
 
 ## D. The fix loop
 
-Fix by looking, not by hoping. For one finding:
+Fix by looking, not by hoping:
 
-1. `iamu fix-brief <finding> --json` (a slug, id, or id prefix). It gives the **before** (page, step and screenshot where the persona hit it), what they **needed**, the full recommendation, the design rules tied to this finding by name with the file and line where each is now (`found: false` when the docs no longer have it), the design docs that apply (`design_files`), what the last design review said about it, the strengths on the same page that must keep working, other open problems there, fixes already tried there, the direction it belongs to, where to save screenshots (`shots_dir`), and the **loop** itself.
-2. Follow `loop` step by step. Save before and after screenshots in `shots_dir` and show their absolute paths when you report.
-3. If the change that meets the need breaks a design rule, stop and report it (the rule, the need, both screenshots) and propose a challenge: never ship either side silently.
-4. If fix-brief says the finding has no known page, take the page from the finding's step and still screenshot it before you edit.
+- **One finding:** `iamu fix-brief <finding> --json` (a slug, id, or `<run-id>#D<n>`).
+- **One surface (all open findings on a page):** `iamu fix-brief /path --json` (e.g. `iamu fix-brief /approvals`).
+- **A multi-scenario wave (all open surfaces in order):** `iamu fix-brief --wave --json`.
+
+1. Run the matching `iamu fix-brief` command. It gives the **before** screenshots, what each visitor **needed**, the design rules tied to the findings with the file and line where each is now (`found: false` when the docs no longer have it), the design docs that apply (`design_files`), what the last design review said, the strengths on the page that must keep working (`protect`), fixes already tried there (`fix_history`, with `verified` patterns that held and `recurred` approaches that failed alongside what the post-fix walk still saw), where to save screenshots (`shots_dir`), and the **loop** itself.
+2. Check `fix_history` before editing: never repeat a `recurred` approach, and keep the patterns from `verified` fixes intact.
+3. Follow `loop` step by step. Save before and after screenshots in `shots_dir` and show their absolute paths when you report. When fixing a surface or a wave, use `iamu design review <path> --blind` as the fast designer inner check on the page, and batch persona walkthrough re-runs (`rerun` / `scenarios_to_rerun`) once at the end of the wave.
+4. If the change that meets the need breaks a design rule, stop and report it (the rule, the need, both screenshots) and propose a challenge: never ship either side silently.
+5. If fix-brief says a finding has no known page, take the page from the finding's step and still screenshot it before you edit.
+
+## E. Start a design doc from the template
+
+Only when no design doc is recorded: `iamu design template` refuses otherwise, and a recorded doc changes only through proposals (**C**). The template is filled in from the code, never by a model: the token values in the frontmatter (light theme), the token groups by name, the contrast clashes the tokens have, each component with the props it takes, and the roles people come in (from the personas and situations, never their names). Everything a person decides is a `<placeholder>`. You and the user fill those in together, and the result becomes the team's doc.
+
+1. **Template.** Run `iamu design template --out iamu/.analysis/design-draft.md --json`. It is for the app the recorded tokens and components apply to, else the root; add `--dir <app>` when the user names another app, and pass the same `--dir` to the later commands. If it answers `out_exists`, a draft is in progress: ask whether to continue it (step 2 with that file) or start over (delete the file and run it again). Tell the user in two lines what came from the code (`sources`, the components, `roles`, `clashes`) and where the doc will go (`target`).
+2. **Fill it in with the user, one placeholder at a time.** Go through the `placeholders` in this order, one question per message, and edit the draft after each answer. Each question carries a suggested answer drawn from what is known: `iamu/context.yml`, the roles and situations, what runs and findings showed of the screens, the components and tokens. The user accepts it, changes it, or skips it (the placeholder stays; a decision still open also goes under Open Questions).
+   1. **Who it is for:** by role, and what they come to do. Suggest it from the roles and situations the Overview lists, then replace that list with the agreed words. Roles only, never a persona's name.
+   2. **How it should feel:** a few words (calm and plain, dense and fast). Suggest from the domain and the roles' dispositions.
+   3. **Accessibility target:** suggest WCAG 2.2 AA, or more when the domain asks for it (a public service, long reading).
+   4. **Look:** what each token group is for, and for each contrast clash, how to keep the two apart or where one may not be used.
+   5. **States:** how forms report errors, loading, failure, empty. Suggest from what the runs saw and the components that exist (an empty-state component, a field with an error prop). Only the states the product has.
+   6. **Content and voice:** the product's words for its things, tone by role, and date and number formats (suggest from the locale and what the screens show).
+   7. **Checks:** yes/no questions a reviewer answers by looking at one screen, where yes is a pass. Suggest them from the answers so far.
+   8. **Not in the library yet**, then **Open Questions:** components screens need that do not exist, and policy decisions still open.
+
+   Write a policy value (a notice period, a limit, a percentage) only when the user gives it as the product's rule; otherwise it stays a placeholder and an open question. Name tokens, never raw colours or lengths.
+3. **Check.** Run `iamu design draft-check --file iamu/.analysis/design-draft.md --json`. Fix each of its `errors` in the draft (a value or path the code does not have, a prop a component lacks, a persona's name) and check again; ask the user only when the fix is a choice.
+4. **Show it once.** Show the whole draft, then the remaining `warnings` in one list (line and message). Ask once: **adopt it**, or **edit** (what to change; edit, check again, and show it once more).
+5. **Adopt.** Run `iamu design adopt --file iamu/.analysis/design-draft.md --json` (`--to <path>` when the user wants it elsewhere). It refuses only when the target already exists: then ask for another path. It writes the doc and records it, with `applies_to` for its app. From then on it is the team's doc: iamu changes it only through proposals a person accepts.
+6. Offer **A2** (point agents at the doc).
+
+When the user declines the template outright ("no", not "later"), run `iamu design template --decline`: runs stop offering it.
 
 ## Guidelines
 

package/dist/templates/skills/iamu-findings.md

@@ -39,7 +39,7 @@ Follow this precedence cascade:
 
 When `iamu/config.json` has `cloud_linked: true` and the `iamu_requests` tool is available, call it once before listing. If it returns `ok: false` (not linked, not authenticated, or `cloud_too_old`), skip this section silently.
 
-If `count > 0`, show the requests first, before the findings tables:
+If `count > 0`, show the requests first, before the findings list:
 
 ```
 Requests from the team (2)
@@ -53,7 +53,7 @@ Ask whether to pick one up. When the user picks a request:
 
 1. Call `iamu_requests_claim` with its `id`. If it fails with `lease_held`, say who holds it and when the lease expires, and return to the list.
 2. Follow `next` from the result:
-   - `fix` → go to step 4's **Fix now** branch for the finding. The claim payload carries `canonical.findingIds`; open the matching `iamu/findings/*.md` (frontmatter `id`) for the walkthrough context. Use `canonical.uiFact` and `canonical.consequence` as the problem statement.
+   - `fix` → go to step 4's **Fix immediately** branch for the finding. The claim payload carries `canonical.findingIds`; open the matching `iamu/findings/*.md` (frontmatter `id`) for the walkthrough context. Use `canonical.uiFact` and `canonical.consequence` as the problem statement.
    - `verify` or `run` → run `iamu-run <scenario.id>`; offer `scenario.targetUrl` as the target when present.
 3. Tell the user the request closes itself on the next `iamu sync` — step 6 runs it.
 
@@ -61,7 +61,7 @@ Ask whether to pick one up. When the user picks a request:
 
 ### 2. List mode: present open findings grouped by scenario
 
-Run `iamu findings --open --json`. Each finding carries `slug`, `source` (`persona` or `designer`), `basis` (the designer's: evidence, seen or taste), `design_causes` (how many designer findings explain it), `scenario`, `type`, `severity`, `title`, `where` (page and step), `recommendation` (the advisor's, or null) and `fix_state`. One list, worst first, with both sources: say on every row who found it ("Ana found" / "the designer found (seen)"), never sum their counts into one number, and say "taste" plainly when a designer finding's basis is taste. A designer finding with no `scenario` came from a page review; group it under its page. For how each scenario is doing, run `iamu report --json` and keep the newest row per `scenario`: its `summary.verdict` (label, question, answer) is the scenario's current outcome.
+Run `iamu findings --open --json`. Each finding carries `slug`, `source` (`persona` or `designer`), `basis` (the designer's: evidence, seen or taste), `design_causes` (how many designer findings explain it), `scenario`, `type`, `severity`, `title`, `where` (page and step), `recommendation` (the advisor's, or null) and `fix_state`. One list, worst first, with both sources: every line says who found it (the persona through its block, the designer on the line itself), never sum their counts into one number, and say "taste" plainly when a designer finding's basis is taste. A designer finding with no `scenario` came from a page review; group it under its page. For how each scenario is doing, run `iamu report --json` and keep the newest row per `scenario`: its `summary.verdict` (label, question, answer) is the scenario's current outcome.
 
 Filter to `triage_status: open`.
 
@@ -85,39 +85,33 @@ A run that simply did not come across a finding proves nothing — never call a
 
 When open findings span three or more scenarios and there are no open directions, or the user asks what to change first, offer a project synthesis: `iamu advise --project --json`, dispatch a thorough-tier subagent with `iamu/.analysis/advise_prompt.md` as its only context, and record its answer with `iamu advise-record --project --data '<json>'`. It proposes directions across every scenario.
 
-Render it as Markdown, not inside a code fence, so the tables render. Start with a one-line tally, then one block per scenario, scenarios with the worst verdict first:
+Render it as Markdown, not inside a code fence. It is read in a terminal: no tables, one line per finding, so the list can be taken in at a glance. Start with a one-line tally, then one block per scenario, scenarios with the worst verdict first:
 
-**<N> open problems** (<C> critical · <M> major · <m> minor) across <S> scenarios · <K> fixes awaiting a re-run
+**<N> open problems** · <counts by severity, only the ones above zero, e.g. "1 critical · 4 major · 4 minor"> · <S> scenarios · <K> fixes awaiting a re-run
 
 ### <persona> · <situation> — **<NO / PARTIAL / YES>**
-<the scenario's latest `summary.verdict.answer`, first sentence or two>
+> <the scenario's latest `summary.verdict.answer`, its first sentence>
 
-| # | Finding | Severity | Where | What to do |
-|---|---|---|---|---|
-| 1 | <title> | **Critical** | <where> | <first sentence of recommendation, or — > |
+1. **Critical** · <title> · <where>
+2. **Major** · designer (seen) · <title> · <where>
 
-Number findings continuously across scenarios, so "fix 3" means one finding. Sort each table worst first (critical → major → minor → nit; incorrect, hinders and missing before irrelevant). Leave strengths (`helps`) out of the tables. Keep the "What to do" cell to one sentence: the full recommendation belongs in the finding card (step 3).
+A persona finding's line needs no name: the block's heading names the persona who found it. A designer finding's line says `designer (<basis>)` after the severity, and `designer (taste)` plainly when its basis is taste. Add ` ↳ design cause` to a persona finding the designer explained (`design_causes` above zero). A page-review designer finding with no `scenario` goes in a block headed `### <page> — page review`.
 
-Ask the user how they would like to triage:
+Number findings continuously across scenarios, so "fix 3" means one finding. Sort each block worst first (critical → major → minor → nit; incorrect, hinders and missing before irrelevant). Leave strengths (`helps`) out. No recommendation on the line: it belongs in the finding card (step 3). With more than 7 in a block, show the worst 7 and end it with `+<n> more (<counts by severity>)`.
 
-- **"walk through them"** → iterate through all open findings one-by-one in order with compact card (`[Fix now]  [Skip / Dismiss]  [Discuss]  [Next]`).
-- **"all critical"** → iterate through all critical findings in order.
-- **Scenario group name** (e.g. "group 1") → iterate through that scenario's findings.
+End with the choices on one line, the recommended one first, and **stop**. Do not use a question tool here, since it covers the list:
+
+`Next: **walk through** (one by one from #1) · **critical only** · **<persona> · <situation>** (one scenario) · **fix 3** · **dismiss 3**`
+
+Recommend **walk through**; recommend a direction first when one is open (see "Directions before findings"). Then, on the user's word:
+
+- **"walk through"** → iterate through all open findings one-by-one in order with compact card (`[Fix now]  [Skip / Dismiss]  [Discuss]  [Next]`).
+- **"critical only"** → iterate through all critical findings in order.
+- **A scenario** (its heading, or "group 1") → iterate through that scenario's findings.
 - **Single number or slug** → single finding (skip to step 3).
-- **"fix 1 and 2"** → make code fixes and mark addressed immediately.
+- **"fix 1 and 2"** → the list shows no recommendations, so never fix from a number alone: show each named finding's card (step 3, without the decision prompt), then one line: `Fix <these N> as shown? Say "yes", or name the ones to leave out.` Only on a yes, fix each as step 4's **Fix immediately** branch does.
 - **"skip 3" / "dismiss 3"** → dismiss with reason (`out_of_scope`, `not_relevant`, `walker_error`, `duplicate`).
 
-**Interactive Triage Strategy:**
-- If your environment provides an interactive user-prompt tool (e.g. `ask_question`, `ask_followup_question`), invoke it:
-  - Question: "How would you like to review these <N> open findings?"
-  - Options:
-    1. "[Recommended] Walk through findings one by one"
-    2. "Focus only on Critical findings (<C> items)"
-    3. "Review by scenario group: <Top Scenario>"
-- Otherwise (in CLI or text-only environments):
-  How would you like to triage these <N> open findings? I recommend walking through findings one by one.
-  Proceeding with one-by-one triage. (Say "critical only", specify a scenario group, or enter a finding number/slug).
-
 ### 3. Direct triage: review one finding
 
 Read the finding file at `iamu/findings/<slug>.md`. Parse the YAML frontmatter (`severity`, `type`, `title`, `ui_fact`, `consequence`, `persona`, `walkthrough_step_id`, `screen_title`, `page_url`, `run`) and markdown body (description and recommendation).
@@ -204,6 +198,9 @@ triage_note: "Made handoff notes optional on /sv/handoff; verified on screen."
   Once the user provides their rationale:
   - *Not relevant* (by design, out of scope): `iamu triage <slug> --status dismissed --reason not_relevant --note "<why it is not a problem>" --rule "<rule string>"`.
   - *Walker error* (the walker misread the screen): `iamu triage <slug> --status dismissed --reason walker_error --note "<what it misread>" --rule "<rule string>"`.
+  - *Project-wide sweep ("we never want X" / "X is a test harness everywhere")*: When the user's intent applies across the entire product (including designer findings or other scenarios), pass `--sweep` (or `--sweep "<keyword>"`):
+    `iamu triage [slug] --status dismissed --note "<why>" --rule "Don't report: <X>" --sweep "<keyword>"`.
+    This sweeps and dismisses every matching open persona and designer finding across all scenarios and surfaces in one command, and records a project-wide guidance rule that the walker, matcher, judge, designer, and `fix-brief` all respect.
   - *Duplicate* of another finding: `--reason duplicate --note "Duplicate of <slug>"` (no rule is written).
 
   Not relevant and walker error write a **tester guidance rule** to `iamu/guidance/<slug>.md` that every later walker reads (and the matcher uses to flag repeats). The rule text defaults to "Don't report: <title>"; pass `--rule "<one sentence the walker can act on>"` when the title is too narrow or too broad. The rule applies to the whole project unless you pass `--scope outline` or `--scope capability` — narrow it when the finding is only irrelevant in this situation. Several findings dismissed for the same reason go in one call and share one rule. **Tell the user: "✓ Dismissed (<reason>) — Guidance rule taught to future walks in iamu/guidance/<slug>.md: '<rule string>'."** One-word notes ("nope") degrade future runs — capture the user's specific rationale.
@@ -254,7 +251,7 @@ If `<N> > 0` findings were queued for fix:
     Proceeding with code edits — say "done" to keep fixes open in iamu/findings/.
 
 - **Executing the queued fixes:**
-  When Option 1 is chosen, fix each queued finding in turn with the fix loop (`iamu fix-brief <slug>`, before and after screenshots of its page, helped / hurt / no visible change) — the fix shown on its card or agreed in Discuss, not the walker's original text. Findings on the same page go together: fix them as one change to that surface. Verify once at the end (run test/typecheck suite). Update each finding with `iamu triage <slug> --status addressed --note "<summary of fix>"`.
+  When Option 1 is chosen, findings on the same page go together as one coherent change to that surface (`iamu fix-brief /path --json` for one page, or `iamu fix-brief --wave --json` across multiple pages/scenarios; `iamu fix-brief <slug>` for a single isolated finding). Check `fix_history` first so you never repeat a `recurred` approach, and keep every strength in `protect` intact. Save before and after screenshots in `shots_dir`, use `iamu design review <path> --blind` as a fast inner check when a surface has multiple or structural edits, and do not re-run persona walkthroughs between individual findings. Verify once at the end (run test/typecheck suite). Update each fixed finding with `iamu triage <slug...> --status addressed --note "<summary of fix>"`.
   Run `iamu validate --all` to verify all entities before reporting done.
 
 - **Closed-Loop Regression Verification (1-Click):**

package/dist/templates/skills/iamu-run.md

@@ -14,6 +14,8 @@ This skill resolves what scenario to run following a clear **Target Scenario Res
 
 **`--no-ux`:** when `$ARGUMENTS` contains `--no-ux`, take it out before resolving the scenario and skip the designer's review (step C3) for this run only: after A, record `iamu designer-record <run-id> --skipped "--no-ux"` so the report says it was skipped. There is no project setting for it: every other run gets a designer's review.
 
+**`--critic`:** when `$ARGUMENTS` contains `--critic`, take it out before resolving the scenario. This run is one critic pass in a builder ↔ critic loop (a gauntlet loop) the user orchestrates: the builder needs the verdict and the findings fast, not fixes or a design review. Skip the advisor (C2) entirely and skip the designer's review (C3): after A, record `iamu designer-record <run-id> --skipped "critic mode"`. Run A, B, C, D (and E in linked mode) as usual. In step 5, present the glance without the Advisor and Designer lines, and do not offer **directions** or **designer**. Per invocation only, like `--no-ux`. When the loop looks converged (every human test passes, or no open major or critical findings), add one line: `Loop looks converged: run once without --critic for the advisor's and designer's review.`
+
 $ARGUMENTS
 
 ## Prerequisites
@@ -249,6 +251,12 @@ iamu browse start --run <run-id>
 
 It sizes the page as the device the persona's tags name (`mobile`/`phone`, `tablet`/`ipad`, `desktop`/`laptop`; `start-run` prints it as `device`) and resizes a browser left at another persona's size.
 
+**Fresh walk in a loop (`--fresh`, `iamu browse` only).** When running iterative passes against a running browser (e.g. with `--critic` or `--fresh`), clear the origin's storage after `browse start` so each walk starts from clean app storage:
+
+```bash
+iamu browse clear-storage --run <run-id>
+```
+
 **Get the walker prompt.** The CLI composes the whole thing — persona, situation, brief, access, driving surface, methodology, dismissed findings and the run-directory contract (steps, screenshots, findings, `summary.json`). It also automatically writes `walker_prompt.txt` to the run directory (`iamu/.runs/<run-id>/walker_prompt.txt`):
 
 ```bash
@@ -273,7 +281,8 @@ A fresh subagent is NOT blind by default. On most hosts it still loads the proje
 
 **Model tiering & subagent dispatch:**
 - **Walker (Browser Navigation):** High turn count, mechanical tool-use. Use the **fast** model tier (`flash` or `haiku`) by default to cut walk time by ~60% and conserve session quota.
-- **Matcher & Judge:** Broad synthesis and semantic comparison. Use the **thorough** frontier tier (`pro`, `sonnet`, or active model) to prevent severity inflation.
+- **Matcher:** Short-text classification (same problem or not) into strict JSON that `match-record` validates. Use the **fastest** tier (`haiku` in Claude Code, `flash_lite` in Antigravity, else the fast tier).
+- **Judge:** Evaluates the human tests from the walk's recorded steps and findings (`judge_prompt.md`, text-only reading comprehension). Use the **fast** tier (`sonnet` in Claude Code, `flash` in Antigravity).
 
 ```
 # In Claude Code:
@@ -356,7 +365,7 @@ iamu summary <run-id> --worked "What worked 1" --worked "What worked 2" --questi
 
 **Post-walk pipeline (MANDATORY — do NOT skip any step):**
 
-After the walker returns, you MUST complete ALL of the following before presenting findings to the user. Do NOT present findings early. Do NOT ask the user anything. Execute steps A→B→C→D→E in order; the designer's review (C3) starts right after A and runs beside them.
+After the walker returns, you MUST complete ALL of the following before presenting findings to the user. Do NOT present findings early. Do NOT ask the user anything. Execute A, then B and C in parallel, then C2, D and E in order; the designer's review (C3) starts right after A and runs beside them.
 
 > **CRITICAL EXECUTION RULE (Zero Host File Tools):**
 > Never invoke host edit or write tools (`write_to_file`, `create_file`, `replace_file_content`, etc.) on any files in `iamu/` (including run artifacts, steps, findings, outlines, personas, scenarios, or guidance). All files in `iamu/` must be generated and modified exclusively via `iamu` CLI commands (`iamu new`, `iamu set`, `iamu step`, `iamu new-finding`, `iamu evaluate-record`, `iamu match-record`, etc.). If an entity needs a field updated (e.g. adding a capability to an outline), run `iamu set <type> <slug> ...` instead of editing files by hand. Record subagent JSON outputs directly through the CLI using `--data '<json>'` (or pipe via stdin).
@@ -371,13 +380,17 @@ This reads all steps, findings, and entity files, assembles `canonical.json`, ge
 
 **If the result has `blocked`**, the walker could not start the walk as it was set up (`iamu summary --blocked`): it could not become the persona, or the world the situation needs was not there. That is a setup problem, not a product finding. Skip B and C — a blocked run is never compared with earlier runs and never counts as a re-run. Tell the user in one line what was missing (`blocked.reason`), then run the `iamu-stage` skill with that reason as the starting point: fix the scenario's `state`, the persona's access, or the seed, and offer to run the scenario again. Findings the walker recorded before it stopped stay as they are. E still runs in linked mode; the report says the run was blocked.
 
+**B and C run in parallel.** The matcher (B) and the judge (C) answer different questions from different inputs, and the judge never reads the matcher's output. Run `iamu match` and `iamu evaluate` one after the other (both are instant), then dispatch both subagents at the same time. Record their answers one after the other as they arrive (`match-record` and `evaluate-record` both rewrite the report; never run them at the same time). Keep them separate: the judge must not see earlier runs' findings, so its verdict cannot drift toward "it was fixed, so it passes".
+
+**How to dispatch the matcher and the judge.** Do not paste the prompt into the dispatch; give the absolute path. Their whole prompt is: `Read <absolute path to match_prompt.md / judge_prompt.md> and answer exactly as it says. Everything you need is in that file. Do not open any other file, run any command or search any code. Reply with the JSON only.` Both are pure reading tasks; a subagent that goes looking for context (the repo, the CLI's source, other runs) costs minutes and can see things it must not.
+
 **B. Match findings to earlier runs.** Get the matcher bundle:
 
 ```bash
 iamu match <run-id> --json
 ```
 
-If `needed` is `false` (no earlier findings for this scenario, or none this run), skip to C. Otherwise, read the prompt from `iamu/.runs/<run-id>/match_prompt.md` directly and dispatch a matcher subagent with it as its only context (use the **thorough** model tier, e.g. `Model="pro"` in Antigravity, to accurately evaluate semantic equivalence). Record its JSON answer via `--data` (do NOT create a `matches.json` file yourself; pass the JSON string directly into `--data`):
+If `needed` is `false` (no earlier findings for this scenario, or none this run), there is no matcher subagent. Otherwise, read the prompt from `iamu/.runs/<run-id>/match_prompt.md` directly and dispatch a matcher subagent with it as its only context (use the **fastest** model tier: `haiku` in Claude Code, `Model="flash_lite"` in Antigravity). Record its JSON answer via `--data` (do NOT create a `matches.json` file yourself; pass the JSON string directly into `--data`):
 
 ```bash
 iamu match-record <run-id> --data '<raw_matches_json>'
@@ -391,7 +404,7 @@ This links recurrences to their earlier canonical finding, marks earlier finding
 iamu evaluate <run-id> --json
 ```
 
-Read the evaluation prompt from `iamu/.runs/<run-id>/judge_prompt.md` directly. Dispatch the evaluator as a subagent with that prompt (use the **thorough** model tier, e.g. `Model="pro"` in Antigravity, to prevent severity inflation). After the evaluator returns verdicts, record them locally with `--no-push` via `--data` (do NOT create a `verdicts.json` file yourself; pass the JSON string directly into `--data`):
+Read the evaluation prompt from `iamu/.runs/<run-id>/judge_prompt.md` directly. Dispatch the evaluator as a subagent with that prompt, at the same time as the matcher (use the **fast** model tier: `sonnet` in Claude Code, `Model="flash"` in Antigravity). After the evaluator returns verdicts, record them locally with `--no-push` via `--data` (do NOT create a `verdicts.json` file yourself; pass the JSON string directly into `--data`):
 
 ```bash
 iamu evaluate-record <run-id> --data '<raw_verdicts_json>' --no-prompt --no-push
@@ -399,7 +412,7 @@ iamu evaluate-record <run-id> --data '<raw_verdicts_json>' --no-prompt --no-push
 
 This links findings to human tests (`human_test_id`) and updates the report with judge verdicts.
 
-**C2. Advise: fixes and directions.** Get the advisor prompt:
+**C2. Advise: fixes and directions.** Skip in `--critic` mode. Otherwise get the advisor prompt:
 
 ```bash
 iamu advise <run-id> --json
@@ -415,7 +428,7 @@ Each entry is checked on its own. Entries that come back rejected (an invented f
 
 The judge (C) and the advisor (C2) are independent, so their subagents may run in parallel, but run `evaluate-record` and `advise-record` one after the other: both rewrite finding files. On a host without subagents, run the advise prompt yourself inline and record it the same way.
 
-**C3. Designer's review.** For every run (unless `--no-ux` was given), start it as soon as A is done:
+**C3. Designer's review.** For every run (unless `--no-ux` or `--critic` was given), start it as soon as A is done:
 
 ```bash
 iamu designer <run-id> --json
@@ -429,7 +442,7 @@ Nothing waits for it: the advisor never waits for the designer, and D and E go a
 iamu designer-record <run-id> --data '<raw_designer_json>'
 ```
 
-Never run two record commands at the same time: `match-record`, `evaluate-record` and `advise-record` keep their order, and `designer-record` runs between them when its answer arrives. It re-derives the report and never touches the persona's finding files. If the subagent fails or its answer is rejected, retry once, then continue without it and record `iamu designer-record <run-id> --skipped "the designer failed"`. If `designer-record` says `rederive_failed`, run the `fix` it prints. On a host without subagents, answer the prompt yourself after C2 and record with `iamu designer-record <run-id> --by-orchestrator --data '<raw_designer_json>'`; the report then says the review was not written by a separate agent. Keep the result's `proposals` for step 5.
+Never run two record commands at the same time: `match-record`, `evaluate-record` and `advise-record` keep their order, and `designer-record` runs between them when its answer arrives. It re-derives the report and never touches the persona's finding files. If the subagent fails or its answer is rejected, retry once, then continue without it and record `iamu designer-record <run-id> --skipped "the designer failed"`. If `designer-record` says `rederive_failed`, run the `fix` it prints. On a host without subagents, answer the prompt yourself after C2 and record with `iamu designer-record <run-id> --by-orchestrator --data '<raw_designer_json>'`; the report then says the review was not written by a separate agent. Keep the result's `proposals`, and `offer_template` from `iamu designer`, for step 5.
 
 **D. Read the completed canonical.** Read `iamu/.runs/<run-id>/canonical.json` for the final data including the verification delta (if a prior run exists) and `analysis.directions` (if the advisor ran). Use this for step 5 presentation.
 
@@ -459,72 +472,61 @@ The `walker_prompt` from `iamu instructions walk` is the source of truth and con
 - **Dedup**: Skip findings in the dismissed list or already logged in the current run.
 - **Graceful degradation**: On judge evaluation failure, set verdicts to pending/null and proceed with report presentation.
 
-### 5. Present assessment — stay in the conversation
-
-You MUST output the complete Executive Scorecard to the chat stream FIRST. Build it from `iamu report <scenario-slug> --json`: the first row is this run, and its `summary` holds everything below already assembled (verdict, per-test labels, the since-last-run outcome of each earlier finding, findings with titles, where and recommendations, directions, observations). Do not re-read `canonical.json` or `verdicts.json` yourself. Output rich Markdown, not inside a code fence, so tables render. Write addresses and file paths out in full so a terminal can open them:
-
-### <summary.persona> · <summary.situation>
-<summary.steps> steps · Cloud: <cloud_url, the full https address> *(not on the cloud: the row's `report_path`, the absolute path to report.md)*
-
-If `summary.checks` is set, say first what this run was checking, in one line: `Re-checked <fixes> fixes waiting for a re-check: <fixed> confirmed fixed, <cameBack> came back, the rest not confirmed`, plus the directions that landed. Name the ones that came back.
-
-> **<summary.verdict.question>** **<summary.verdict.label>**
-> <summary.verdict.answer>
-
-If `summary.tests` has more than one test, add one line per test: `**<label>** · <question>`.
-
-If `summary.since` is set, show what happened to every earlier finding this run re-checked (`summary.since.items`), then one line for the new ones:
+### 5. Present the result — a glance, then the user decides
 
-**Since the last run** (<date of summary.since.baselineAt>)
+Build it from `iamu report <scenario-slug> --json`: the first row is this run, and its `summary` holds everything already assembled (verdict, per-test labels, the since-last-run outcome of each earlier finding, findings with titles and where, directions, observations). Do not re-read `canonical.json` or `verdicts.json` yourself.
 
-| Earlier finding | Now | Notes |
-|---|---|---|
-| <title> | **Resolved** / **Persists** / Not seen / Unclear | <item.note, or — > |
+The result is read in a terminal first. Show a **glance** the user can take in without scrolling: about 15 lines, no tables, one line per item, the verdict on top. The depth (the persona's reasoning step by step, the screenshots, every recommendation) lives in the walkthrough report; link it and do not retell it. Output Markdown, not inside a code fence. Write addresses and paths out in full so a terminal can open them.
 
-For a persisting finding, put its qualifiers in brackets: the `shift` ("less severe, major → minor") and "the fix did not hold" when `fixedBefore` is true (it was marked fixed before this run).
+**The glance**, in this order. Leave out every line whose data is empty:
 
-`+ <summary.since.added> new problems this run.` "Not seen" means the walk did not pass that way: never call it fixed.
+### <summary.persona> · <summary.situation> — **<summary.verdict.label>**
+> <summary.verdict.question> <summary.verdict.answer, its first sentence>
 
-**Findings** (<N> problems, <K> strengths), worst first:
+- `summary.tests` with more than one test: one line, `Tests: **<label>** <question, shortened to a few words> · **<label>** …`.
+- `summary.checks`: `↻ Re-checked <fixes> fixes: <fixed> confirmed fixed, <cameBack> came back (<their titles>)`.
+- `summary.since`: `Since <date of summary.since.baselineAt>: <n> resolved · <n> persist · <n> not seen · +<summary.since.added> new`. Name a persisting finding whose fix did not hold (`fixedBefore`): `(fix did not hold: <title>)`.
 
-| # | Finding | Severity | Where | What to do |
-|---|---|---|---|---|
-| 1 | <title> | **Major** | <where> | <first sentence or two of recommendation, or — > |
+Then the problems, worst first:
 
-Mark a finding that persists from the last run with `(persists)` after its title. When the designer gave a finding's design cause (a `summary.designer.issues` entry whose `design_cause_of` is that finding's `id`), add it under the row as `↳ Design cause (designer, <basis>): <what>`. Strengths go on one line under the table: `✓ Strengths: <title>; <title>`.
+**<N> problems** · <counts by severity, only the ones above zero, e.g. "1 major · 2 minor">
+1. **<Severity>** · <title> · <where>
+2. **<Severity>** · <title> · <where>
 
-If `summary.directions` is non-empty:
+One line per finding, numbered as in step 6, so "fix 2" means one finding. Add ` (persists)` after a title that persists from the last run, ` (unstable)` when the finding's `stability` is `unstable`, and ` ↳ design cause` when the designer gave one (a `summary.designer.issues` entry whose `design_cause_of` is that finding's `id`). No recommendation here: it is in the card. Show at most 7; past that, end with `+<n> more (<counts by severity>)`. With no problems, write `No problems found.` instead: the verdict still stands on its own, a run without findings can still answer NO.
 
-**Directions** (structural changes the advisor proposes)
+An **unstable** finding has come and gone across this scenario's runs without a fix recorded against it: it may be critic noise rather than a product problem. Whoever acts on the findings (the user, or a builder agent in a loop) confirms an unstable finding (re-run, or a person checks the screen) before changing code for it. When any are shown, add one line under the list: `(unstable) = came and went across runs without a fix; confirm before acting.`
 
-| Direction | Size | Absorbs | Re-run to check |
-|---|---|---|---|
-| <title> | <size> | <absorbs> findings | <verify> scenarios |
+`✓ <K> strengths: <title>; <title>` on one line.
 
-Reach is a prediction until those scenarios run again.
+Then, one short line each, only the ones that apply. These are counts; the detail is behind the words in the last line:
+- Designer (`summary.designer`): `Designer: <n> major or critical · <n> minor · <n> rules broken`, its count apart from the persona's, never one total. Add `judged against general craft` when `judged_against` is `general-craft`, and `written by the orchestrator` when `dispatch` is `inline`.
+- Advisor: `Advisor: <n> directions (absorb <n> findings)`, plus `· <n> notes` for `summary.observations` and `· <n> entries rejected` when the advise record (C2) rejected entries.
+- Design docs: `Design docs: <N> proposed edits — decided after the findings` (`design_proposals` from C2, `proposals` from C3). They wait for a person; never apply them yourself.
+- ⚠ Test setup (`summary.setupNotes`): `⚠ Test setup: <n> doubts about the test, not the product. A finding resting on one may not be real.` Never fold this one away.
+- Sync (E): `⚠ Sync: <n> findings changed by a teammate too` when the result has `conflicts`: name them and give the resolution (`iamu pull --force` to take theirs after copying your edits aside, or `iamu sync --keep-mine` to keep yours). When it has `pending_deletes`: `<n> deletions wait for you: check them, then run iamu sync --confirm-deletes`. Never run either yourself.
+- Design doc offer: only when the designer's result (C3) had `offer_template: true`: `No design doc yet: say "start it" and I'll draft one from your code with you, or "no" and I won't offer again.` On "start it", after triage, follow the `iamu-design` skill, mode E. On "no", run `iamu design template --decline`.
 
-If `summary.designer` is set, add the **Designer's review**: the designer's judgement of these screens, never the persona's experience. Give its count apart from the persona's ("2 designer findings"), never one total.
-- One line on what it was judged against: the design docs in `summary.designer.design_files`, or, when `judged_against` is `general-craft`, `Judged against general craft: recording the project's design docs makes this review sharper`, followed by the `hint` command `iamu designer` printed. Say so when `dispatch` is `inline` ("written by the orchestrator, less independent").
-- The rule breaks (`summary.designer.rules_broken`), one line each: `"<rule>" (<file>) on <screen>, step <n>`, then `<rules_held> rules held`.
-- The major and critical designer findings that are not a design cause (`summary.designer.issues` with no `design_cause_of`), one line each: `<id> · designer · <severity> · <basis> · <screen> · <title>`, with `breaks "<rule>"` when it breaks one; then the count of minor and nit ones in one line.
+Then the link to the full walkthrough, which shows the persona's reasoning beside each screenshot:
 
-If `summary.observations` is non-empty, end with **Also worth knowing** (the advisor's notes): one bullet each, `Not walked: <title>` (coverage_gap) or `Feature risk: <title>` (feature_risk).
+`Walkthrough: <the cloud URL from E>`. Not on the cloud: run `iamu open <run-id> --local --print` and give the path it prints (the local HTML report).
 
-If the advise step or the designer proposed design doc edits (`design_proposals` in the advise result, `proposals` in the designer result), add one line: `Design docs: <N> proposed edits — decided after the findings`. They wait for a person; never apply them yourself.
+End with the choices on one line, the recommended one first, and **stop**: the user reads the result before deciding. Do not open Finding #1, and do not use a question tool here, since it covers the glance.
 
-If `summary.setupNotes` is non-empty, add **Test setup** with one bullet each. These are doubts about the test, not the product (missing data, an account that cannot see enough, a date the scenario assumes). Offer the `iamu-stage` skill to fix the setup before the next run; a finding that rests on a setup doubt may not be real.
+`Next: **triage** (one by one from #1) · **fix 2** · **directions** · **designer** · **since** · **setup**`
 
-Do NOT output `### What Worked` paragraphs or lengthy bullet essays. Keep the scorecard scannable: the tables are the summary.
+Name only the words that apply. Recommend **directions** when the advisor proposed any, **setup** when there are setup doubts, else **triage**. With no problems and no major or critical designer findings, offer only the open words (`designer`, `since`), or nothing.
 
-**Zero-Friction Triage Transition (Eliminate Meta-Prompt Gate):**
-Do NOT prompt the user with a generic "How would you like to proceed?" multiple-choice modal. That intermediate prompt adds cognitive friction, duplicates the triage options, and obscures the assessment scorecard.
+**Behind the words.** When the user says one, show it, then offer the same Next line again (without the word just used):
 
-- **If `summary.findings` is empty (no problems):**
-  Output: "No problems found in this run." The verdict above still stands on its own: a run without findings can still answer NO.
-  Do not enter finding triage for the persona; when the designer's review has major or critical designer findings, triage those (step 6 lists them the same way), then the proposed design doc edits.
+- **triage** / a number: step 6. **fix 2** / "fix 1 and 3": step 6B, which shows the cards and waits for a yes before any edit.
+- **directions**: step 6, "Directions come first".
+- **since**: each item of `summary.since.items` on one line, `<Resolved / Persists / Not seen / Unclear> · <title> · <item.note>`, with a persisting one's `shift` ("less severe, major → minor") and "the fix did not hold" when `fixedBefore`. "Not seen" means the walk did not pass that way: never call it fixed.
+- **designer**: the designer's judgement of these screens, never the persona's experience. One line on what it was judged against (the files in `summary.designer.design_files`, or for `general-craft`: `Judged against general craft: recording the project's design docs makes this review sharper`, and the `hint` command `iamu designer` printed). Then the rule breaks, one line each: `"<rule>" (<file>) on <screen>, step <n>`, then `<rules_held> rules held`. Then the major and critical designer findings that are not a design cause, one line each: `<id> · <severity> · <basis> · <screen> · <title>`, with `breaks "<rule>"` when set; then the count of minor and nit ones.
+- **notes**: the advisor's `summary.observations`, one bullet each, `Not walked: <title>` (coverage_gap) or `Feature risk: <title>` (feature_risk).
+- **setup**: `summary.setupNotes`, one bullet each (missing data, an account that cannot see enough, a date the scenario assumes); offer the `iamu-stage` skill to fix the setup before the next run.
 
-- **If `summary.findings` is not empty:**
-  Output the Executive Scorecard above to chat FIRST, and advance IMMEDIATELY to triage on **Finding #1 of <total>** (Step 6 below) in the same turn. The user can choose to queue to fix, queue all remaining fixes (batch accept), dismiss, or discuss directly from Finding #1.
+Do NOT output `### What Worked` paragraphs, open-question lists or the recommendations in the glance: the walkthrough report holds them.
 
 ### 6. Conversational Triage & Guided Review
 
@@ -676,12 +678,12 @@ When the user asks to review findings one by one:
      6. In linked mode, run `iamu sync --json` once so teammates see the verified decisions.
 
 #### B. Direct Batch Actions ("fix 1 and 2", "fix all critical")
-Read the finding details from the canonical JSON (already in context), inspect the code, make the edits, and update frontmatter to `triage_status: addressed` with `triage_note`.
+The glance shows no recommendations, so never fix from a number alone. First show each named finding's card (step 6A format, without the decision prompt), then one line: `Fix <these N> as shown? Say "yes", or name the ones to leave out.` Only on a yes, fix each with the fix loop (`iamu fix-brief <slug> --json` and its `loop`; findings on one page go together as one change; a designer finding from `iamu fix-brief <run-id>#D<n> --json`) and record each with `iamu triage <slug> --status addressed --note "<summary of fix>"`. Then continue as in item 3's "Executing the queued fixes" from `iamu validate --all`.
 
 #### C. Ad-hoc Questions & Challenges ("why did Karl do that?", "is #2 really a bug?")
 Answer directly using persona brief context and step evidence. If the walker got confused or misinterpreted intended behavior, recommend dismissing as `walker_error` or `not_relevant` rather than adding unnecessary code.
 
-**Linked mode: publish triage decisions.** When the user is done fixing and dismissing, run `iamu sync --json` once so teammates see the decisions (and any team request for these findings closes). Report it in one line (`Synced 3 findings to Iamu Cloud.`), with conflicts handled as in item 6. Do not sync after every single edit.
+**Linked mode: publish triage decisions.** When the user is done fixing and dismissing, run `iamu sync --json` once so teammates see the decisions (and any team request for these findings closes). Report it in one line (`Synced 3 findings to Iamu Cloud.`), with conflicts and pending deletions handled as in step 5's Sync line. Do not sync after every single edit.
 
 **Do NOT** dump the user at file paths. The report and finding files exist for later reference, but the conversation is the triage surface. Mention artifacts only if the user asks for them or wants to share the report externally. The cloud link is the exception: in linked mode it IS the shareable report, so it always goes in the presentation.
 

package/dist/templates/skills/iamu-setup.md

@@ -233,15 +233,16 @@ iamu set context \
 
 ---
 
-### 4b. Optional: design docs (quick, skippable)
+### 4b. Design docs (quick; the user may skip it, you may not)
 
-The team's design docs are part of the product's context, like the domain. Iamu reads them wherever they are and never edits them on its own. Run `iamu design detect --json`.
+The team's design docs are part of the product's context, like the domain. Iamu reads them wherever they are and never edits them on its own. Run `iamu design detect --json` and always show the user its result, even when every candidate looks unrelated. Never drop a candidate yourself: one in a spike, sandbox or example folder is listed with that note, unticked, and the user decides.
 
-- **Found docs** (a `DESIGN.md` in any format, design-system, brand, voice or interaction docs, design sections of `CLAUDE.md` or `AGENTS.md` shown as `CLAUDE.md#<heading>`, a `PRODUCT.md`, token files, a component library): list them once, one line each (kind, path). Show a candidate with a `note` (tokens in a template, export or fixture folder) with its note, unticked. Ask once whether to record them; the user may drop some or add others. On yes, `iamu design sources <paths…>` (in a monorepo, `--applies-to` with the URL prefix or the app's folder each doc covers).
+- **Found docs** (a `DESIGN.md` in any format, design-system, brand, voice or interaction docs, design sections of `CLAUDE.md` or `AGENTS.md` shown as `CLAUDE.md#<heading>`, a `PRODUCT.md`, token files, a component library): list them once, one line each (kind, path). Show a candidate with a `note` (anything in a sample, export, fixture or spike folder) with its note, unticked. Ask once whether to record them; the user may drop some or add others. On yes, `iamu design sources <paths…>` (in a monorepo, `--applies-to` with the URL prefix or the app's folder each doc covers).
 - **A legacy `iamu/design.md`** (`iamu design status --json` shows `legacy.doc` and no `legacy.migrated_at`): fold it into the same single question. Run `iamu design migrate --json` first, and offer three answers next to the files: **move it** to a plain `DESIGN.md` the team owns (`iamu design migrate --move-to DESIGN.md --apply`), **keep** `iamu/design.md` as it is (`iamu design migrate --apply`, which records the choice so it is not offered again), or **not now** (run nothing; it is offered again next time). Only an explicit "keep" runs `--apply` without a move.
-- **Nothing found:** say so in one line and continue. Walks run without design docs.
+- **Nothing found:** say so in one line: "No design docs found. The designer reviews each run by general craft until you record some (`iamu-design`)."
+- **No written design doc** (detection found only tokens or components, or nothing, and no design doc is recorded): after the question above, or in its place when there was nothing to record, ask one question the user may skip: "There is no design doc yet. Shall I start one from your code? I fill in your tokens, components and contrast clashes, then ask you a few short questions (who it is for, how it should feel, an accessibility target, states, formats). **Yes** / **not now** / **no**." Yes: follow the `iamu-design` skill, mode E, then carry on with setup. No: run `iamu design template --decline`, so runs stop offering it. Not now: run nothing; it is offered again after the first run.
 
-Do not assess or draft design docs here. Never block setup on this step.
+Do not assess design docs here, and never write one without the user filling it in (mode E). Never block setup on this step.
 
 ---
 

package/dist/ui/report-view.d.ts

@@ -14,6 +14,11 @@ export interface RunFindingRow {
     recommendation: string | null;
     persists: boolean;
     isNew: boolean;
+    /**
+     * Spike (fast-critic-loop D6): how the finding behaved across its
+     * scenario's runs. `unstable` means confirm before acting on it.
+     */
+    stability?: "stable" | "unstable" | "first_seen";
 }
 export type SinceOutcome = "resolved" | "persists" | "not_seen" | "uncertain";
 export interface RunView {

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@iamu-dev/iamu",
-  "version": "0.6.0-beta.0",
+  "version": "0.8.0-beta.0",
   "type": "module",
   "description": "Test your product as realistic personas — scenario-driven development CLI",
-  "license": "UNLICENSED",
+  "license": "MIT",
   "author": "Iamu <hello@iamu.dev>",
   "homepage": "https://iamu.dev",
   "repository": {
@@ -58,9 +58,9 @@
     "tsup": "^8.5.1",
     "typescript": "^5.8.0",
     "vitest": "^4.1.11",
-    "@iamu-dev/protocol": "0.1.0",
     "@iamu-dev/local-store": "0.1.0",
-    "@iamu/tsconfig": "0.1.0"
+    "@iamu/tsconfig": "0.1.0",
+    "@iamu-dev/protocol": "0.1.0"
   },
   "scripts": {
     "build": "tsup && tsc -b --force tsconfig.build.json --emitDeclarationOnly && node scripts/copy-assets.mjs",