@iamu-dev/iamu 0.8.0-beta.2 → 0.8.0-beta.3

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

@@ -13,7 +13,7 @@ You review one surface of the product: a page, its states, and the flows that pa
 
 - **Several people, one surface.** When visitors need different things here (one wants a firm answer, another a fast decision), say who should see what. Role clarity often beats explaining more to everyone.
 - **Evidence, seen or taste, always labelled.** `evidence`: a visitor's walk shows it; cite the refs (`F3`). `seen`: you saw or measured it yourself in the browser (a clipped control, a 3.1:1 contrast); give the screenshot path. `taste`: your judgement against the rules or general craft. All are welcome; never pass one off as another.
-- **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`.
+- **Name the rule.** When an issue breaks a rule in the design docs, give the rule's canonical name from that file's `rules` array in `design.files` (or, if none is listed, 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`.

package/dist/templates/prompts/designer.md

@@ -16,10 +16,11 @@ The person already judged what it was like: whether the product fits their role,
 - `findings`: what the person filed on this run, as refs: `F<n>` for problems, `S<n>` for what helped, each with its `step`. A finding's `severity` is the one the person filed.
 - `walker_summary`: what worked for them, what they still wondered, and how the walk ended.
 - `screens`: the run's screens in walk order. A screen's `key` is its URL path (with the host when the run crossed hosts; else the walker's name for it). A screen visited twice has two `visits`. Screenshot paths are relative to `run_dir`. Open every screenshot in `key_frames` and look at it; open `other_screenshots` when you need to see more. `steps` carry what the person did and thought at each step.
-- `design.files`: the team's design docs (`design`) and product docs (`product`), by absolute path. A file with a `heading` means that section only. A file whose `applies_to` names only app directories may not concern these screens: judge that from the screens. `design.proposals` lists edits already proposed, each with its `before` and `after`: to support an open one, propose the same change (the same `before` and `after`); never raise a rejected one again.
+- `design.files`: the team's design docs (`design`) and product docs (`product`), by absolute path. A file with a `heading` means that section only. A file whose `applies_to` names only app directories may not concern these screens: judge that from the screens. Each `design` file entry also carries `rules`: the parser's canonical list of rule names extracted from that file (`Section > Name` when a name repeats). `design.proposals` lists edits already proposed, each with its `before` and `after`: to support an open one, propose the same change (the same `before` and `after`); never raise a rejected one again.
 - `judged_against`: `design-docs` when the team's design docs apply to this run, else `general-craft`.
 - `ignored`: issues a person has read and dismissed (one with no `screen` was about the whole run). Do not raise them again unless they got worse; if one did, say how.
-- `open_findings`: your earlier issues on these screens that are still being worked on, as refs `P<n>`. When you see one again on this run, raise it as an issue of this run with `same_as: "P<n>"`; one you no longer see, leave out (that is how a fix is confirmed). In the summary, say which still show and which are gone.
+- `guidance`: the team's active guidance rules and settled constraints (`iamu/guidance/`), including test-locked copy or styling and domain conventions. Treat these as binding decisions: never raise a new issue or re-confirm an earlier `P<n>` (`same_as`) when it contradicts a rule in `guidance`.
+- `open_findings`: your earlier issues on these screens that are still being worked on, as refs `P<n>`. When you see one again on this run (and it is not covered by `ignored` or `guidance`), raise it as an issue of this run with `same_as: "P<n>"`; one you no longer see, leave out (that is how a fix is confirmed). In the summary, say which still show and which are gone.
 - `setup_notes`: about the test setup (accounts, seeded data), not the product. Never judge the product by them.
 
 ## What you open
@@ -30,7 +31,7 @@ Open only the screenshots the bundle lists and the files `design.files` lists. N
 
 1. **Read the design docs first** (every file in `design.files`), then the persona and the situation.
 2. **Go screen by screen, in walk order.** For each screen, say what it is for this person at this moment, and what on it serves them.
-3. **With design docs** (`design-docs`): apply the rules that concern each screen. Cite each rule by its exact name as the doc writes it (its heading, or the bold words that open it, without a closing full stop or colon) and the entry it is in (from `design.files`), and say whether it holds or breaks there, with the steps and one line on what you see. When the same name occurs twice in one file, write `Section > Name`. **Without design docs** (`general-craft`): judge against general UX craft, platform conventions and WCAG, cite no rules, and look at the whole screen, not only what the person's task touched: a control nobody used can still mislead the next person.
+3. **With design docs** (`design-docs`): apply the rules that concern each screen. Cite each rule by its exact canonical string from that file's `rules` array in `design.files` (or, if none is listed, its heading or the bold words that open it, without a closing full stop or colon) and the `entry` it is in (from `design.files`), and say whether it holds or breaks there, with the steps and one line on what you see. When the same name occurs twice in one file, write `Section > Name`. **Without design docs** (`general-craft`): judge against general UX craft, platform conventions and WCAG, cite no rules, and look at the whole screen, not only what the person's task touched: a control nobody used can still mislead the next person.
 4. **Judge the craft the person could not see:** consistency across the screens, contrast and accessibility (estimated from the screenshot: say so), copy and formats, interaction and states (what is shown after an action, while loading, when empty, when it fails), and hierarchy and density where they explain a finding or concern what the walk passed by.
 5. **Label every claim.** `evidence`: a finding shows it; cite its refs. `seen`: you see it in a screenshot; cite the steps. `taste`: your judgement against the docs or general craft. All are welcome; never pass one off as another.
 6. **Never restate a finding, except as its design cause.** Before you write an issue, check the findings: if it is about the same problem on the same screen as an `F<n>`, in any words, it is not a new issue. Either give its design cause, citing that `F<n>` in `evidence` and its `step` in `steps` (that is what links your issue to the finding as its cause), or leave it out. Role fit, overload and "this is not for me" are the person's findings; raise them only as such a cause.

package/dist/templates/prompts/walk.md

@@ -147,6 +147,12 @@ When an environment is unseeded or test records are missing:
 - If your persona role is a creator (e.g. employee or consultant creating an item), click the creation CTA (e.g. "+ Ny reseräkning", "+ New") and proceed with your task.
 - If your persona role is read-only (e.g. an auditor or manager) and cannot create data, do NOT record false "missing data" bugs against the product. Conclude the walk noting that the environment lacks the required preconditions.
 
+## Host product vs. subject payload (Seeded defects & inspected content)
+
+Many products display, inspect, or triage a **subject** — an embedded preview or screenshot of another app, a customer submission, a failing test run, a security alert, an audit log, or a document with errors.
+- **Separate the host UI from the subject payload:** When your persona's job is to review, flag, or act on defects inside an inspected subject (e.g. spotting a squeezed sidebar or wrong notice inside a previewed app screenshot, or triaging a failing check), those defects belong to the **subject** you are inspecting — they are NOT bugs in the **host product** you are using.
+- **Evaluate the host product's tools:** Act on the seeded subject defects using the host product's workflow as the persona would. Only file an `iamu` finding (`hinders`, `missing`, `incorrect`) if the **host product** makes it hard, confusing, or impossible to see, flag, or resolve the subject's defects.
+
 ## Semantic squinting (Adapting to environmental mismatch)
 
 Your prompt may include an approximation strategy (e.g. "If Malmö is missing, choose Göteborg").

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

@@ -184,28 +184,20 @@ triage_note: "Made handoff notes optional on /sv/handoff; verified on screen."
 
 - **Design change needed** → the change requires design thinking (restructuring a flow, new capability, API contract touch, multiple files). Do NOT fix inline. Use the project's own change process if it has one — check the agent docs and the repo for it (an `openspec/` directory and its change skills, an ADR or RFC folder, an issue tracker the docs name) and start the change there with the finding's persona + scenario context pre-filled. Only if the project has none, draft a short design doc. Then leave the finding `open` until the change ships. Attach the change reference in `triage_note`: `"Design change: <reference>. Re-triage when the change ships."`.
 
-- **Defer** → the finding is real but not urgent. Set `triage_status: deferred` with an explicit `triage_note` naming the condition to revisit: `"Defer: revisit after <trigger, e.g. Q3 mobile release / next round of persona feedback>."`.
+- **Dismiss (`not_relevant` / `walker_error` / `out_of_scope` / `duplicate`)** → the finding is not a problem to fix:
+  - Quick 1-step dismiss (defaults to `not_relevant` and writes `"Don't report: <title>"`): `iamu triage <slug> --status dismissed`.
+  - With custom rationale or rule:
+    - *Not relevant* (by design): `iamu triage <slug> --status dismissed --reason not_relevant [--note "<why>"] [--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>"]`.
+    - *Out of scope* (handled outside the system): `iamu triage <slug> --status dismissed --reason out_of_scope [--note "<how it is handled>"] [--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, the matcher, the judge (`evaluate`) and `fix-brief` respect. The designer never reads tester guidance: a swept designer finding is dismissed, and later designer's reviews are told not to raise it again.
+    - *Duplicate* of another finding: `iamu triage <slug> --status dismissed --duplicate-of <other-slug> [--note "<note>"]` (no rule is written).
 
-- **Won't fix (accepted trade-off)** → the problem is real but the team accepts it. `iamu triage <slug> --status wont_fix --note "<the trade-off>"`. It stays out of future walks' dismissed list only as a known issue — no guidance rule is written, unless you pass `--sweep`, which dismisses every matching finding and records a project-wide rule as a dismissal would.
+  `not_relevant`, `walker_error`, and `out_of_scope` 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, or `--no-guidance` to skip writing a rule. 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>'."**
 
-- **Not relevant / walker got it wrong (Load-Bearing Guidance Learning)** → the finding should never have been reported. **Never infer the reason silently.** Always ask the user:
-  > "To teach future walkthroughs what not to report, why should this be dismissed?
-  > • **By design / intended behavior:** (Why this pattern is expected)
-  > • **Walker error:** (What the walker misread or did wrong)
-  > • **Out of scope:** (Non-issue for this product/flow)
-  > What specific rule should future walkers follow?"
-  
-  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, the matcher, the judge (`evaluate`) and `fix-brief` respect. The designer never reads tester guidance: a swept designer finding is dismissed, and later designer's reviews are told not to raise it again.
-  - *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.
-
-- **Keep (no decision yet)** → rare. Use only when the reviewer genuinely needs more information. Leave `triage_status: open` and add a `triage_note` noting what you are waiting for: `"Waiting on <thing> before triage."`.
+- **Keep open (no decision yet)** → leave `triage_status: open` and optionally attach a `triage_note`: `iamu triage <slug> --status open --note "Waiting on <thing> before triage."`.
 
 Report back with the action taken:
 
@@ -213,11 +205,8 @@ Report back with the action taken:
 addressed (fix now): <finding-slug>
   Change: made handoff notes optional on /sv/handoff
 
-deferred: <finding-slug>
-  Note: revisit after Q3 mobile release
-
 dismissed (duplicate): <finding-slug>
-  Reason: duplicates frontline-worker--incident-report-overwhelm-a7b2c1
+  Duplicate of: frontline-worker--incident-report-overwhelm-a7b2c1
 
 dismissed (not_relevant): <finding-slug>
   Reason: the beta badge is intentional until launch

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

@@ -388,9 +388,18 @@ iamu summary <run-id> --worked "What worked 1" --worked "What worked 2" --questi
 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; the designer's review (C3) starts right after A and runs beside B, C and C2. D and E wait until every record (B, C, C2, C3) is in, so the report you read and the run you publish are complete.
 
 > **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).
+> 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`, `iamu post-walk`, 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 via stdin heredoc (`--file - <<'EOF' ... EOF`), `--file <path>`, or `--data '<json>'`.
 
-**A. Assemble canonical + report (local).** Use `--no-push` so post-processing stays fast, local, and synchronous:
+**Fast path — prepare all post-walk prompts in one hop:**
+You can complete the run locally AND generate `match_prompt.md`, `judge_prompt.md`, `advise_prompt.md`, and `designer_prompt.md` in a single command:
+
+```bash
+iamu post-walk <run-id> --json
+```
+
+`iamu post-walk <run-id> --json` returns the `needed` status, `prompt_file_abs`, and `answer_file_abs` for `match`, `evaluate`, `advise`, and `designer` in one JSON object (pass `--critic` or `--no-ux` when applicable). If subagent JSON outputs are later written to their `answer_file_abs` paths in `<run-dir>/`, running `iamu post-walk <run-id> --json` again records all of them in lock-safe order automatically.
+
+**A. Assemble canonical + report (local).** Use `--no-push` so post-processing stays fast, local, and synchronous (already done if you ran `iamu post-walk <run-id> --json`):
 
 ```bash
 iamu complete <run-id> --no-prompt --no-push --json
@@ -400,48 +409,59 @@ 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".
+**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 post-walk <run-id> --json` (or `iamu match` and `iamu evaluate`), then dispatch the needed 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:
+**Avoid zsh quote-escaping failures when recording JSON:** Subagent outputs are 5–15 KB of JSON that frequently contain single quotes (`"Something's off"`) and escaped double quotes (`"\"Hall rules\""`). Prefer piping via a single-quoted heredoc (`--file - <<'EOF'`) or `--file <path>` so the shell never interprets quotes inside the JSON.
+
+**B. Match findings to earlier runs.** Get the matcher bundle (if not already prepared via `iamu post-walk`):
 
 ```bash
 iamu match <run-id> --json
 ```
 
-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`):
+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 `--file - <<'EOF'` (or `--data`):
 
 ```bash
-iamu match-record <run-id> --data '<raw_matches_json>'
+iamu match-record <run-id> --file - <<'EOF'
+<raw_matches_json>
+EOF
+# or: iamu match-record <run-id> --data '<raw_matches_json>'
 ```
 
 This links recurrences to their earlier canonical finding, marks earlier findings the run's steps show fixed (only with cited steps), and re-derives the delta and report. If the matcher's output is rejected, show the error to the matcher once and retry; if it fails again, continue without it — the exact-text delta from A stands.
 
-**C. Evaluate human tests.** Get the evaluation prompt:
+**C. Evaluate human tests.** Get the evaluation prompt (if not already prepared via `iamu post-walk`):
 
 ```bash
 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, at the same time as the matcher (use the **mid** model tier: `sonnet` in Claude Code, `Model="flash"` in Antigravity). After the evaluator returns verdicts, record them via `--data` (do NOT create a `verdicts.json` file yourself; pass the JSON string directly into `--data`). Like every record command it stays local and never prompts; E publishes:
+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 **mid** model tier: `sonnet` in Claude Code, `Model="flash"` in Antigravity). After the evaluator returns verdicts, record them via `--file - <<'EOF'` (or `--data`). Like every record command it stays local and never prompts; E publishes:
 
 ```bash
-iamu evaluate-record <run-id> --data '<raw_verdicts_json>'
+iamu evaluate-record <run-id> --file - <<'EOF'
+<raw_verdicts_json>
+EOF
+# or: iamu evaluate-record <run-id> --data '<raw_verdicts_json>'
 ```
 
 This links findings to human tests (`human_test_id`) and updates the report with judge verdicts.
 
-**C2. Advise: fixes and directions.** Skip in `--critic` mode. Otherwise get the advisor prompt:
+**C2. Advise: fixes and directions.** Skip in `--critic` mode. Otherwise get the advisor prompt (if not already prepared via `iamu post-walk`):
 
 ```bash
 iamu advise <run-id> --json
 ```
 
-If `needed` is `false` (blocked run, nothing open to advise, or already advised), skip to D. Otherwise read the prompt from `iamu/.runs/<run-id>/advise_prompt.md` and dispatch an advisor subagent with it as its only context (use the **thorough** model tier). Unlike the walker, the advisor reads the project's code (read-only) and the screenshots: it classifies each finding local or systemic, writes the fix from the persona's need, looks at how leading systems in the domain handle the moment, and proposes directions for the flow with their predicted reach on other personas. Record its JSON answer via `--data`:
+If `needed` is `false` (blocked run, nothing open to advise, or already advised), skip to D. Otherwise read the prompt from `iamu/.runs/<run-id>/advise_prompt.md` and dispatch an advisor subagent with it as its only context (use the **thorough** model tier). Unlike the walker, the advisor reads the project's code (read-only) and the screenshots: it classifies each finding local or systemic, writes the fix from the persona's need, looks at how leading systems in the domain handle the moment, and proposes directions for the flow with their predicted reach on other personas. Record its JSON answer via `--file - <<'EOF'` (or `--data`):
 
 ```bash
-iamu advise-record <run-id> --data '<raw_advice_json>'
+iamu advise-record <run-id> --file - <<'EOF'
+<raw_advice_json>
+EOF
+# or: iamu advise-record <run-id> --data '<raw_advice_json>'
 ```
 
 Each entry is checked on its own. Entries that come back rejected (an invented file or symbol, a path in the prose, a direction with too little evidence) stay unadvised and the rest is kept; a run is advised once, so do not record again. Mention rejected entries in step 5. Keep the result's `directions` and `rerun` for step 5.
@@ -459,12 +479,15 @@ If `needed` is `false` (`reason` is `blocked`, `no_screens` or `already_recorded
 The advisor (C2) does not wait for the designer, but D and E do: when its answer arrives, record it:
 
 ```bash
-iamu designer-record <run-id> --data '<raw_designer_json>'
+iamu designer-record <run-id> --file - <<'EOF'
+<raw_designer_json>
+EOF
+# or: iamu designer-record <run-id> --data '<raw_designer_json>'
 ```
 
 Record commands run one at a time: `match-record`, `evaluate-record` and `advise-record` keep their order, and `designer-record` goes between them when its answer arrives (the CLI also holds each run's record lock, so one that starts while another records waits for it). 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.
 
-**Never fabricate a review.** Where the host can dispatch a subagent that looks at images, the review is that subagent's. Only on a host that cannot dispatch one, and only when you can open and look at the screenshots yourself, answer `designer_prompt.md` yourself and record it with `iamu designer-record <run-id> --by-orchestrator --data '<raw_designer_json>'`: the report then says it was written by the orchestrator, which is less independent. If neither is possible, record `iamu designer-record <run-id> --skipped "no subagent can look at images"`. `--no-ux` and `--critic` record their own reasons (see the top of this skill).
+**Never fabricate a review.** Where the host can dispatch a subagent that looks at images, the review is that subagent's. Only on a host that cannot dispatch one, and only when you can open and look at the screenshots yourself, answer `designer_prompt.md` yourself and record it with `iamu designer-record <run-id> --by-orchestrator --file - <<'EOF'` (or `iamu designer-record <run-id> --by-orchestrator --data '<raw_designer_json>'`): the report then says it was written by the orchestrator, which is less independent. If neither is possible, record `iamu designer-record <run-id> --skipped "no subagent can look at images"`. `--no-ux` and `--critic` record their own reasons (see the top of this skill).
 
 Keep the result's `proposals`, and `offer_template` from `iamu designer`, for step 5.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iamu-dev/iamu",
-  "version": "0.8.0-beta.2",
+  "version": "0.8.0-beta.3",
   "type": "module",
   "description": "Test your product as realistic personas — scenario-driven development CLI",
   "license": "MIT",
@@ -59,8 +59,8 @@
     "typescript": "^5.8.0",
     "vitest": "^4.1.11",
     "@iamu-dev/local-store": "0.1.0",
-    "@iamu-dev/protocol": "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",