@iamu-dev/iamu 0.3.0-beta.0 → 0.3.0-beta.2

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

@@ -103,31 +103,31 @@ Ask the user how they would like to triage:
     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?
-  1. [Recommended] Walk through findings one by one
-  2. Focus only on Critical findings (<C> items)
-  3. Review by scenario group: <Top Scenario>
-
-Reply '1' to walk through all [default], select 2-3, or enter a finding number/slug:
+  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).
 
-Synthesize a comprehensive, dashboard-aligned triage summary. Do NOT force an artificial single `Source: file:line` (UX friction and user blockers often span entire flows, API errors, or policy). Instead, present:
+Synthesize a scannable triage summary. Do NOT output an undifferentiated wall of bullets or academic schema labels like "UI Fact:". The reviewer must be able to parse **What is broken** and **What to fix** in under 3 seconds.
 
+Format the visible finding in chat:
+
+```markdown
+### Finding #<N>/<total> [<SEVERITY>] — <title>
+> **Where:** `<Screen title or URL>` (Step <N>) · **Persona:** <Persona Name> (<Role>)
+> **Evidence:** [step-<N>.png](iamu/.runs/<run>/screenshots/step-<N>.png) · [View in Cloud Walkthrough](<url from iamu open <run-id> --print>)
+
+**❌ Problem:**
+<What went wrong on screen and why it hinders the persona (synthesizing ui_fact and consequence in 1–2 clear, direct sentences)>
+
+**💡 Recommendation:**
+<Concrete fix proposal from finding body>
 ```
-Finding <N>/<total>: [<SEVERITY> · <type>] <title>
-• Persona: <Persona Name> (<Role>) · <Screen title or URL, Step N>
-• UI Fact: <What the UI showed or did (ui_fact)>
-• Consequence: <Impact on the persona completing their task (consequence)>
-• Agent Insight: <1–2 plain-language sentences synthesizing why this happens and what it means in context>
-• Recommendation: <Concrete fix proposal from finding body>
-• Evidence: <iamu/.runs/<run>/screenshots/step-<N>.png> [Dashboard](<url if cloud_linked>)
-```
+*(For `type: "helps"` findings, omit `**❌ Problem:**` and `**💡 Recommendation:**`; render `**✓ Strength:** <Observation>`)*.
 
-If the project is cloud-linked, include the link to the finding in Iamu Cloud (from `iamu open --print`).
+If the project is cloud-linked, include the direct link to the walkthrough in Iamu Cloud (from `iamu open <run-id> --print`).
 
 Emit this card visibly into the conversation.
 
@@ -135,40 +135,20 @@ Emit this card visibly into the conversation.
 
 Every finding must land on a decision — never silently skip. Match the user's intent to the closest option.
 
-**CRITICAL: Embed Full Context in Interactive Prompt Modals:**
-Host interactive tools (e.g. `ask_question`, `ask_followup_question`) render a modal that obscures the terminal and displays ONLY the tool's `question` argument. **You must embed the complete finding summary inside the `question` argument** so the reviewer has full context directly in the dialog without having to close the modal.
+**Dual-Surface Triage Prompting (Sequencing Rule):**
+You MUST output the rich markdown finding card to the chat stream FIRST. In the SAME turn, invoke `ask_question`:
 
 - If your environment provides an interactive user-prompt tool (e.g. `ask_question`, `ask_followup_question`), invoke it:
-  - **Question:**
-    """
-    Finding #<N>/<total>: <title>
-
-    • Impact: [<SEVERITY> · <type>]
-    • Persona: <Persona Name> (<Role>) · <Screen title or URL, Step N>
-    • UI Fact: <ui_fact>
-    • Consequence: <consequence>
-    • Agent Insight: <1–2 sentences explaining why this happens in simple terms>
-    • Recommendation: <concrete recommendation>
-    • Evidence: <screenshot path, local file link, and cloud dashboard link if linked>
-
-    How should we triage this finding?
-    """
+  - **Question:** "Finding #<N>/<total> [<SEVERITY>]: <title> on <Screen title or URL, Step N> — How to triage?"
   - **Options:**
-    1. "[Recommended] Queue to fix (mark for fix & continue triage)"
-    2. "Dismiss / Won't fix (record reason & walker guidance rule)"
-    3. "Design change needed (open issue / design doc)"
-    4. "Defer (revisit in later milestone)"
+    1. "[Recommended] Queue to fix (<brief 3-5 word fix summary>)"
+    2. "Queue all remaining recommended fixes (batch accept)"
+    3. "Dismiss / Skip (<brief reason if obvious, e.g. keep current design>)"
+    4. "Discuss / Explore trade-offs"
     5. "Fix immediately (leave triage now)"
-- Otherwise (in CLI or text-only environments):
-
-Triage Finding #<N>/<total>: '<finding title>'
-  1. [Recommended] Queue to fix (mark for fix & continue triage)
-  2. Dismiss / Won't fix (record reason & walker guidance rule)
-  3. Design change needed (open issue / design doc)
-  4. Defer (revisit in later milestone)
-  5. Fix immediately (leave triage now)
-
-Reply '1' to queue fix [default], enter 2-5, or describe your decision:
+- Otherwise (CLI / text-only conversational fallback):
+  > **Recommended Action:** Queue to fix (<brief 3-5 word fix summary>).
+  > Say **"queue"** (or **"queue all"**), **"dismiss"** (to teach a rule), or **"discuss"** to explore trade-offs.
 
 Record the decision with `iamu triage` — it sets `triage_status` and `triage_note` in `iamu/findings/<slug>.md`, and for a dismissal it also teaches the next walk:
 
@@ -183,6 +163,10 @@ triage_status: addressed
 triage_note: "Made handoff notes optional on /sv/handoff; verified on screen."
 ```
 
+- **Discuss / Explore trade-offs (Conversational Dialogue Mode — NO MODAL LOOPS)** → when the user chooses "Discuss", asks a question, or wants to explore architectural trade-offs:
+  **DO NOT invoke `ask_question` or present multiple-choice menus.** Stay in natural conversational chat as a senior pair programmer. Answer follow-up questions, inspect code, benchmark against competitors, and discuss options in plain markdown. Converse naturally back and forth until you reach a conclusion together.
+  Once the user says "queue it", "dismiss it", "fix it now", or "let's do that", execute `iamu triage`, confirm in 1 line: "✓ Decision recorded. Ready for finding #<N+1>?", and immediately emit Finding #<N+1> to chat with its triage prompt. Do NOT trap the user with modal dialogs after each conversational turn.
+
 - **Queue to fix [Recommended in list-mode]** → add to the session's fix queue. Tell the user in 1 line: "✓ Queued for fix. Advancing to next finding..." and loop to the next finding. Complete the triage queue across all findings first.
 
 - **Fix immediately (leave triage now)** → the change is small, one-or-two files, and user explicitly chose to leave triage now. Make the edit, verify it loads (if a dev server is running, open the affected screen and check), then record: `iamu triage <slug> --status addressed --note "<one-line change summary>"`. Do not close a finding as addressed before the change lands and is inspected. Tell the user the fix now awaits a re-run: only a later walkthrough of the scenario turns it verified.
@@ -193,12 +177,19 @@ triage_note: "Made handoff notes optional on /sv/handoff; verified on screen."
 
 - **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.
 
-- **Not relevant / walker got it wrong** → the finding should never have been reported. Ask which, because they teach different things:
-  - *Not relevant* (by design, out of scope): `iamu triage <slug> --status dismissed --reason not_relevant --note "<why it is not a problem>"`.
-  - *Walker error* (the walker misread the screen): `iamu triage <slug> --status dismissed --reason walker_error --note "<what it misread>"`.
+- **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>"`.
   - *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 — future walkthroughs are told not to report this"** and name the rule file. One-word notes ("nope") degrade future runs — name the reason specifically.
+  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."`.
 
@@ -241,10 +232,8 @@ If `<N> > 0` findings were queued for fix:
       1. "[Recommended] Apply queued fixes in workspace now"
       2. "Done for now (keep fixes open in iamu/findings/)"
   - Otherwise (CLI / text-only):
-    Apply fixes for the <N> queued findings now?
-      1. [Recommended] Apply queued fixes in workspace now
-      2. Done for now (keep fixes open in iamu/findings/)
-    Reply '1' to apply fixes [default], or select 2:
+    Triage complete. I recommend: Apply queued fixes in workspace now.
+    Proceeding with code edits — say "done" to keep fixes open in iamu/findings/.
 
 - **Executing the queued fixes:**
   When Option 1 is chosen, apply code edits for each queued finding sequentially in the workspace. Verify the changes once (run test/typecheck suite). Update each finding with `iamu triage <slug> --status addressed --note "<summary of fix>"`.
@@ -258,10 +247,8 @@ If `<N> > 0` findings were queued for fix:
       1. "[Recommended] Re-run walkthrough for <scenario-slug> to verify fixes hold"
       2. "Done for now (leave verification for later)"
   - Otherwise (CLI / text-only):
-    Verify fixes now?
-      1. [Recommended] Re-run walkthrough for <scenario-slug> to verify fixes hold
-      2. Done for now (leave verification for later)
-    Reply '1' to re-run [default], or select 2:
+    Fixes applied and validated. I recommend: Re-run walkthrough for <scenario-slug> to verify fixes hold.
+    Proceeding with verification re-run — say "done" to leave verification for later.
 
   When Option 1 is chosen, hand off to `iamu-run <scenario-slug>` to re-run the walkthrough, visit the revisit places, verify resolutions in `canonical.json`, and report the verified delta.
 
@@ -277,9 +264,7 @@ Report it in one line: `Synced <N> findings to Iamu Cloud.` If the result has `c
 
 Then end with the dashboard link from `iamu open --print` (step replay, screenshots side by side, the team's view of the same findings):
 
-```
-Team view: <url>
-```
+> ☁️ **Cloud Walkthrough:** [Open in Iamu Cloud](<url from iamu open --print>)
 
 In linked-no-credentials mode, end with `Decisions are local only — iamu auth login, then iamu sync, to share them.` Skip this section entirely in local-only mode. The terminal surface is complete.
 

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

@@ -85,26 +85,20 @@ Present 2–3 scannable scenario proposals. Each proposal MUST bundle the situat
     3. "Select alternative: '<Bundle 2 Title>' as <Persona 2 Name>"
     4. "Customize situation, checkpoint, or brief"
 - Otherwise (in CLI or text-only environments):
-
-Scaffold this scenario for walkthrough?
-  1. [Recommended] Scaffold '<Bundle 1 Title>' as <Persona 1 Name>
-  2. Switch persona: Walk as <Alternative Persona Name> (<Role>)
-  3. Select alternative: '<Bundle 2 Title>' as <Persona 2 Name>
-  4. Customize situation, checkpoint, or brief
-
-Reply '1' to scaffold [default], select 2-3, or type adjustments:
+  I recommend scaffolding '<Bundle 1 Title>' as <Persona 1 Name>.
+  Proceeding to scaffold scenario — say "switch persona", "select alternative", or describe adjustments to customize.
 
 *Execution Flow:*
-- **Selecting Option 1 (or hitting Enter):** Proceed IMMEDIATELY to Step 6 (Persist everything). Zero intermediate question modals.
+- **Selecting Option 1 (or conversational confirmation):** Proceed IMMEDIATELY to Step 6 (Persist everything). Zero intermediate question modals.
 - **Selecting Option 2:** Present the persona switcher (Step 4) then persist.
 - **Selecting Option 3:** Swap primary bundle and prompt to persist.
 - **Selecting Option 4 / typing adjustments:** Expand into Step 3 to refine details before persisting.
 
 ### 3. Develop the situation (Scenario Spec-Sheet)
 
-In Fast-Path mode or when customizing, present the complete scenario as a structured, scannable Spec-Sheet before creating anything. Every field shown here is written verbatim to disk on confirmation:
+In Fast-Path mode or when customizing, present the complete scenario as a structured, scannable Spec-Sheet before creating anything. Every field shown here is written verbatim to disk on confirmation.
 
-Do NOT output markdown header hashes (`#`, `##`, `###`) or markdown blockquote syntax (`>`), which render as stray hashes or `|` pipe characters in terminal frontends. Keep the narrative capped at 2–3 punchy sentences (problem-space only, zero UI terms).
+Keep the narrative capped at 2–3 punchy sentences (problem-space only, zero UI terms). (Note: When passing text to modal prompt tools like `ask_question`, use plain text without header hashes or blockquotes; in normal chat output, format clearly with standard markdown).
 
 ```
 Scenario Spec-Sheet: <Outline Title>
@@ -133,15 +127,10 @@ Persona & Brief:
     2. "Switch persona: Walk as <Alternative Persona> (<Role>)"
     3. "Adjust situation, checkpoint, or brief"
 - Otherwise (in CLI or text-only environments):
+  I recommend scaffolding scenario '<Outline Title>' and preparing the walkthrough.
+  Proceeding to scaffold scenario — say "switch persona" or describe adjustments.
 
-Scaffold scenario '<Outline Title>'?
-  1. [Recommended] Scaffold scenario and prepare walkthrough
-  2. Switch persona: Walk as <Alternative Persona> (<Role>)
-  3. Adjust situation, checkpoint, or brief
-
-Reply '1' to scaffold [default], select 2, or type adjustments:
-
-*Selecting Option 1 or hitting Enter proceeds IMMEDIATELY to Step 6 (Persist everything).*
+*Selecting Option 1 proceeds IMMEDIATELY to Step 6 (Persist everything).*
 
 ### 4. Pick or swap personas (on demand)
 
@@ -170,7 +159,8 @@ If no existing persona fits, or if testing an uncovered perspective is needed, p
     1. "[Recommended] Bind existing persona: <slug> (<role>)" (if one fits)
     2. "Create candidate: <Name> (<Role>)"
     3. "Leave as draft (no persona bound yet)"
-- Otherwise, prompt: "Pick a persona (1–N), 'new' to propose candidates, or 'skip' to save as draft without a persona."
+- Otherwise, state the recommended persona and conversational default:
+  "I recommend binding <slug> (<role>). Proceeding with this persona — name a candidate or say 'skip' to save as draft."
 
 ### 5. Classify into capabilities
 

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

@@ -96,7 +96,8 @@ Existing coverage: <N> scenarios ([<slug1>](iamu/scenarios/<slug1>.md), ...). Un
     2. "Scaffold '<Candidate 2 Title>' (<Actor>)"
     3. "Scaffold '<Candidate 3 Title>' (<Actor>)"
 - Otherwise (in CLI or text-only environments):
-Reply '1' to scaffold [default], select 2-3, or describe adjustments:
+  I recommend scaffolding Candidate 1: '<Candidate 1 Title>' (<Actor>).
+  Proceeding to scaffold scenario — name another candidate or describe adjustments.
 
 #### B. When proposing Personas:
 
@@ -126,7 +127,8 @@ Existing personas: [<slug1>](iamu/personas/<slug1>.md), ... Uncovered roles from
     2. "Add <Name 2> (<Actor role>)"
     3. "Add <Name 3> (<Actor role>)"
 - Otherwise (in CLI or text-only environments):
-Reply '1' to add [default], select 2-3, or describe adjustments:
+  I recommend adding Candidate 1: <Name 1> (<Actor role>).
+  Proceeding to add persona — name another candidate or describe adjustments.
 
 Ground rules for generation:
 

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

@@ -57,8 +57,8 @@ When `$ARGUMENTS` is empty and no active scenario exists in context, check `iamu
     1. "[Recommended] Ignore and continue with new run"
     2. "Finish run `<run-id>`: Run post-walk assembly on existing steps"
     3. "Discard empty unfinished runs"
-- Otherwise (in text-only/conversational environments), state that you are proceeding with Option 1 by default:
-  "Note: Found <N> unfinished walkthrough run(s). Proceeding with a new run [1]. (Reply 2 to finish run `<run-id>` or 3 to discard empty runs)."
+- Otherwise (in text-only/conversational environments), state the recommended action and default:
+  "Found <N> unfinished walkthrough run(s). Proceeding with a new run. (Say 'finish <run-id>' or 'discard empty' to adjust)."
 
 Do not block the new run on this, and do not ask again in the same session.
 
@@ -110,7 +110,8 @@ Omit the first group when `rerun` is empty. If `requests.open` in the status out
     1. "[Recommended] <Slug or Title>" (e.g. top rerun needing proof, or primary ready scenario)
     2. "<Alternative Scenario Slug or Title>"
     3. "Draft a new scenario..."
-- Otherwise, prompt: "Pick a scenario number (1–N), enter a slug, or type an intent to draft a new one."
+- Otherwise, state the recommended scenario and conversational default:
+  "Recommended scenario: `<Slug or Title>`. Proceeding with this scenario — say '<Alternative Slug>' or describe a new intent to change course."
 
 Drafts get a bind prompt before execution (step 2); ready-to-run scenarios skip to step 3.
 
@@ -125,7 +126,8 @@ If the resolved scenario has `persona: null`, prompt to bind before executing:
     1. "[Recommended] <Existing Persona 1> (<Role>)"
     2. "<Existing Persona 2> (<Role>)"
     3. "Draft a new persona candidate"
-- Otherwise, ask: "This scenario is a draft — no persona bound. Pick an existing persona (1–N), or type 'new' to propose candidates."
+- Otherwise, state the recommended persona and conversational default:
+  "This scenario is a draft with no persona bound. I recommend binding `<Existing Persona 1>` (<Role>). Proceeding with this persona — name another persona or type 'new' to propose candidates."
 
 1. Read `iamu/personas/` directory or run `iamu list personas`; present as pickable list + "new" option.
 2. Picked existing → bind that persona by updating the scenario file's `persona` field.
@@ -162,11 +164,8 @@ If the target is a local URL (e.g. `http://localhost:*`, `http://127.0.0.1:*`) a
        2. "I will start the dev server manually (wait for port)"
        3. "Specify a different target URL"
    - Otherwise (CLI / text-only):
-     Target URL <url> is unreachable. Boot dev server now?
-       1. [Recommended] Boot dev server in background (`<dev_command>`) and proceed
-       2. I will start the dev server manually (wait for port)
-       3. Specify a different target URL
-     Reply '1' to boot dev server [default], select 2-3, or provide target URL:
+     Target URL <url> is unreachable. I recommend Option 1: Boot dev server in background (`<dev_command>`) and proceed.
+     Proceeding with dev server boot — say "wait" to start manually or provide a different target URL.
 3. If Option 1 is chosen:
    - Launch `<dev_command>` in the background as a managed daemon process.
    - Poll `<url>` with HTTP requests until it responds (timeout: 30s).
@@ -216,7 +215,7 @@ If the product is behind enterprise login where automated dev persona switching
 If automated switching exists:
 1. Check the project's own agent docs (`CLAUDE.md`, `AGENTS.md`) for a documented way to switch user or role.
 2. Map the persona to the closest account or role the product actually has. If nothing fits, say so.
-3. Write what you learned: the mechanism into the `iamu/testability.md` frontmatter as `access:` (it is test setup, so it does not belong in `context.yml`, which holds the domain; if `iamu doctor` finds it there, move it), and the persona's own key with `iamu set persona <slug> --access <key>`. Passwords and tokens never go in either — name where they live (an env var, a vault entry) instead.
+3. Persist what you learned: the mechanism into `iamu/testability.md` via `iamu set testability --access "<key>"`, and the persona's own key with `iamu set persona <slug> --access <key>`. Passwords and tokens never go in either — name where they live (an env var, a vault entry) instead.
 
 Carry the result into the walking prompt as the `## Access` section: the exact steps to become the persona, with the instruction to do them BEFORE the first recorded step.
 
@@ -248,15 +247,15 @@ 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.
 
-**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`):
+**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
 iamu instructions walk --scenario <scenario-slug> --run <run-id> --surface browse --json
 ```
 
-`--surface browse` (the default) describes `iamu browse`; start it first (`iamu browse start --run <run-id>`, above). Using your own browser tool instead, pass one sentence naming it and how it saves screenshots, e.g. `--surface "Chrome DevTools MCP attached to the user's Chrome; take_screenshot with filePath"`. For a native app, describe the simulator tool and add the native notes below.
+**Never create prompt generator scripts or temporary files.** The CLI generates and persists the prompt automatically. Never write custom `.cjs`, `.js`, or `.sh` generator scripts into `.cache/`, `iamu/`, or the workspace. Hand-crafting files triggers host IDE file permission prompts.
 
-The result's `walker_prompt` is the walker's entire prompt. Pass it verbatim — do not rewrite, summarize or trim it. The prompt already carries the dismissed findings, the active tester guidance rules (`iamu/guidance/`) for this scenario, and — when fixes await a re-run — the places they were seen (places only, never what was wrong; the list is in `revisit`). The rest of the bundle (`persona`, `outline`, `access`, `dismissed_findings`, `tester_guidance`, …) is there for you, not the walker. If `access` is missing a half, fill it in first (step 3) and re-run this command.
+The result's `walker_prompt` is the walker's entire prompt (also persisted at `walker_prompt_path`). Pass it verbatim — do not rewrite, summarize or trim it. The prompt already carries the dismissed findings, the active tester guidance rules (`iamu/guidance/`) for this scenario, and — when fixes await a re-run — the places they were seen (places only, never what was wrong; the list is in `revisit`). The rest of the bundle (`persona`, `outline`, `access`, `dismissed_findings`, `tester_guidance`, …) is there for you, not the walker. If `access` is missing a half, fill it in first (step 3) and re-run this command.
 
 **Preflight: Unattended execution check.** A walkthrough executes 15–30 terminal commands sequentially (`iamu browse step`, `iamu new-finding`). If your agent host requires manual confirmation for terminal/shell commands (standard interactive mode in Claude Code, Cursor, Antigravity, Cline, Windsurf, etc.), the walker subagent will stall waiting for approval on every step. Before dispatching, verify that command auto-approval / unattended execution is enabled in your environment, or warn the user once:
 "Autonomous walkthroughs require auto-approving terminal commands so the walker can drive the product unattended. If command approvals are prompted, please enable auto-approval or expect to approve steps manually."
@@ -357,6 +356,9 @@ iamu summary <run-id> --worked "What worked well 1" --worked "What worked well 2
 
 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.
 
+> **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).
+
 **A. Assemble canonical + report (local).** Use `--no-push` so post-processing stays fast, local, and synchronous:
 
 ```bash
@@ -373,11 +375,10 @@ This reads all steps, findings, and entity files, assembles `canonical.json`, ge
 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` (or `--file`):
+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`):
 
 ```bash
-iamu match-record <run-id> --data '<matches.json>'
-# or: iamu match-record <run-id> --file <matches.json>
+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.
@@ -388,11 +389,10 @@ 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` (or `--file`):
+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`):
 
 ```bash
-iamu evaluate-record <run-id> --data '<verdicts.json>' --no-prompt --no-push
-# or: iamu evaluate-record <run-id> --file <verdicts.json> --no-prompt --no-push
+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.
@@ -431,23 +431,23 @@ Render results **inline** as a concise executive scorecard.
 
 **ANTI-BLOAT DIRECTIVE:** Terminal viewports are small. Never output multi-screen walls of markdown text. The overview exists only to present the top-line score and orient the user for triage. Do NOT dump long quotes, recommendations, full descriptions, or "What Worked" essays here — those belong in the interactive triage step below.
 
-Keep the presentation under 15 lines total:
+Keep the presentation under 15 lines total. Output as rich Markdown (do NOT wrap the entire summary in a triple-backtick code block so links render as clickable):
 
-```
-Walkthrough: [<scenario-slug>](iamu/scenarios/<scenario-slug>.md) ([<persona>](iamu/personas/<persona>.md))
-Verdict: <FAIL / PARTIAL / PASS> · <N> Blockers (Critical) · <M> Friction points (Major/Minor) · <K> Helpers (Steps: <N>)
-Focus Checkpoint: "<human_tests[0].question>" → <No / Partial / Yes>: <1-sentence direct answer>
+### Walkthrough Complete: [<scenario-slug>](iamu/scenarios/<scenario-slug>.md) ([<persona>](iamu/personas/<persona>.md))
+**Verdict:** <FAIL / PARTIAL / PASS> · <N> Blockers (Critical) · <M> Friction points (Major/Minor) · <K> Helpers (<StepCount> steps)
+**Checkpoint:** "<human_tests[0].question>" → <No / Partial / Yes>: <1-sentence direct answer>
 
-Findings:
-1. [<CRITICAL|MAJOR|MINOR> · <type>] <Short title> (Step <N> at <short_url_path>)
-2. [<CRITICAL|MAJOR|MINOR> · <type>] <Short title> (Step <N> at <short_url_path>)
+#### Findings:
+1. **[CRITICAL]** · *<type>* · <Short title> (Step <N> at `<short_url_path>`)
+2. **[MAJOR]** · *<type>* · <Short title> (Step <N> at `<short_url_path>`)
 ...
 (Helps: • [helps] <short title> (Step <N>))
 
-Cloud: <Shareable report: <url> | Local only>
-```
-
 (If canonical.json contains a `verification` section, include a 1-line delta: `Since last run: ✓ <N> fixed · ✗ <M> persist · + <K> new`.)
+
+> ☁️ **Cloud Walkthrough:** [Open in Iamu Cloud](<url from iamu open <run-id> --print>)
+*(If local-only, render instead: `> **Artifact:** [iamu/.runs/<run-id>/report.md](iamu/.runs/<run-id>/report.md) (Local only)`)*
+
 Do NOT output `### What Worked` paragraphs or lengthy bullet essays. Keep the entire summary under 15 lines, then immediately present the triage prompt below.
 
 7. **Next actions (Interactive Triage Selection)**:
@@ -459,15 +459,9 @@ Do NOT output `### What Worked` paragraphs or lengthy bullet essays. Keep the en
        2. "Apply fixes for all clear findings (batch fix)"
        3. "Discuss findings and persona friction points"
        4. "Re-run walkthrough to test changes"
-   - Otherwise (in CLI or text-only environments):
-
-   Walkthrough complete: <F> findings reported.
-     1. [Recommended] Walk through findings one by one
-     2. Apply fixes for all clear findings (batch fix)
-     3. Discuss findings and persona friction points
-     4. Re-run walkthrough to test changes
-
-   Reply '1' to review findings [default], enter 2-4, or tell me how to proceed:
+    - Otherwise (in CLI or text-only environments):
+      Walkthrough complete: <F> findings reported. I recommend walking through findings one by one.
+      Proceeding with one-by-one triage. (Say "batch fix", "discuss", or "re-run" to change course).
 
 ### 6. Conversational Triage & Guided Review
 
@@ -475,74 +469,70 @@ The conversation is the triage surface. Do NOT eject the user to manual CLI comm
 
 #### A. Guided One-by-One Review ("walk through them" / "review one by one")
 When the user asks to review findings one by one:
-1. **Present Finding #N in a comprehensive, dashboard-aligned summary:**
-   Do NOT force an artificial single `Location: file:line` (UX friction and user blockers often span entire flows, API errors, or policy). Instead, present:
-   ```
-   Finding <N>/<total>: [<SEVERITY> · <type>] <title>
-   • Persona: <Persona Name> (<Role>) · <Screen title or URL, Step N>
-   • UI Fact: <What the UI showed or did (ui_fact)>
-   • Consequence: <Impact on the persona completing their task (consequence)>
-   • Agent Insight: <1–2 plain-language sentences synthesizing why this happens and what it means in context>
-   • Recommendation: <Concrete fix proposal from finding body>
-   • Evidence: <iamu/.runs/<run>/screenshots/step-<N>.png> [Dashboard](<url if cloud_linked>)
+1. **Present Finding #N in a scannable format (High Visual Hierarchy):**
+   Do NOT output an undifferentiated wall of bullets or academic schema labels like "UI Fact:". The reviewer must be able to parse **What is broken** and **What to fix** in under 3 seconds.
+
+   Format the visible finding in chat:
+   ```markdown
+   ### Finding #<N>/<total> [<SEVERITY>] — <title>
+   > **Where:** `<Screen title or URL>` (Step <N>) · **Persona:** <Persona Name> (<Role>)
+   > **Evidence:** [step-<N>.png](iamu/.runs/<run>/screenshots/step-<N>.png) · [View in Cloud Walkthrough](<url from iamu open <run-id> --print>)
+
+   **❌ Problem:**
+   <What went wrong on screen and why it hinders the persona (synthesizing ui_fact and consequence in 1–2 clear, direct sentences)>
+
+   **💡 Recommendation:**
+   <Concrete fix proposal from finding body>
    ```
-   If the project is cloud-linked, include the link to the finding in Iamu Cloud (from `iamu open --print`).
+   *(For `type: "helps"` findings, omit `**❌ Problem:**` and `**💡 Recommendation:**`; render `**✓ Strength:** <Observation>`)*.
+
+   If the project is cloud-linked, include the direct link to the walkthrough in Iamu Cloud (from `iamu open <run-id> --print`).
 
    Followed immediately by the decision prompt:
 
-   **CRITICAL: Embed Full Context in Interactive Prompt Modals:**
-   Host interactive tools (e.g. `ask_question`, `ask_followup_question`) render a modal that obscures the terminal and displays ONLY the tool's `question` argument. **You must embed the complete finding summary inside the `question` argument** so the reviewer has full context directly in the dialog without having to close the modal.
+   **Dual-Surface Triage Prompting (Sequencing Rule):**
+   You MUST output the rich markdown finding card to the chat stream FIRST. In the SAME turn, invoke `ask_question`:
 
    - If interactive tool available (e.g. `ask_question`, `ask_followup_question`), invoke it:
-     - **Question:**
-       """
-       Finding #<N>/<total>: <title>
-
-       • Impact: [<SEVERITY> · <type>]
-       • Persona: <Persona Name> (<Role>) · <Screen title or URL, Step N>
-       • UI Fact: <ui_fact>
-       • Consequence: <consequence>
-       • Agent Insight: <1–2 sentences explaining why this happens in simple terms>
-       • Recommendation: <concrete recommendation>
-       • Evidence: <screenshot path, local file link, and cloud dashboard link if linked>
-
-       How should we triage this finding?
-       """
+     - **Question:** "Finding #<N>/<total> [<SEVERITY>]: <title> on <Screen title or URL, Step N> — How to triage?"
      - **Options:**
-       1. "[Recommended] Queue to fix (mark for fix & continue triage)"
-       2. "Dismiss / Skip (not relevant or walker error)"
-       3. "Discuss / Explore trade-offs"
-       4. "Fix immediately (leave triage now)"
-       5. "Next finding (keep open / defer)"
-   - Otherwise (CLI / text-only):
-     Triage Finding #<N>/<total>: '<finding title>'
-       1. [Recommended] Queue to fix (mark for fix & continue triage)
-       2. Dismiss / Skip (not relevant or walker error)
-       3. Discuss / Explore trade-offs
-       4. Fix immediately (leave triage now)
-       5. Next finding (keep open / defer)
-     Reply '1' to queue fix [default], select 2-5, or describe your decision:
+       1. "[Recommended] Queue to fix (<brief 3-5 word fix summary>)"
+       2. "Queue all remaining recommended fixes (batch accept)"
+       3. "Dismiss / Skip (<brief reason if obvious, e.g. keep current design>)"
+       4. "Discuss / Explore trade-offs"
+       5. "Fix immediately (leave triage now)"
+   - Otherwise (CLI / text-only conversational fallback):
+     > **Recommended Action:** Queue to fix (<brief 3-5 word fix summary>).
+     > Say **"queue"** (or **"queue all"**), **"dismiss"** (to teach a rule), or **"discuss"** to explore trade-offs.
 
 2. **Handle the user's decision**:
    - **Queue to fix [Recommended]**:
      Add finding to the session's fix queue.
      Tell the user in 1 line: "✓ Queued for fix. Ready for finding #<N+1>?" and advance immediately.
      Do NOT edit code or leave triage yet — complete triage across all findings first.
-   - **Skip / Dismiss**:
-     If reason is not specified, ask or infer the appropriate category:
-     - `out_of_scope`: Not relevant to this project/flow scope.
-     - `not_relevant`: By design / intended behavior.
-     - `walker_error`: Walker misread the screen or made a navigational error.
-     - `duplicate`: Duplicate of another finding.
-     Execute: `iamu triage <slug> --status dismissed --reason <reason> --note "<why>"`.
-     Tell the user in 1 line: "✓ Dismissed as `<reason>` — guidance rule recorded."
+   - **Skip / Dismiss (Load-Bearing Guidance Learning)**:
+     **Never infer dismissal rationale silently.** If the user has not yet explained why this finding is dismissed, prompt them directly in conversational chat:
+     > "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 reasoning (or if already clear from discussion):
+     Derive a concise, actionable guidance rule string.
+     Execute: `iamu triage <slug> --status dismissed --reason <reason> --note "<user rationale>" --rule "<rule string>"`.
+     Tell the user in 1 line:
+     `✓ Dismissed (<reason>) — Guidance rule taught to future walks in iamu/guidance/<slug>.md: "<rule string>"`
      Then advance to finding #<N+1>.
-   - **Discuss / Why (STRICT CONSTRAINT: maximum 3-4 concise bullets, under 80 words total)**:
-     Never write multi-section essays, markdown headers (`### Trade-off Analysis`, `#### 1. Why it was built this way`, `#### 2. The Operational Failure`), or ASCII/markdown tables. Deliver a direct, surgical 3-bullet answer:
+   - **Discuss / Explore trade-offs (Conversational Dialogue Mode — NO MODAL LOOPS)**:
+     When the user chooses "Discuss", asks a question, or challenges an idea:
+     **DO NOT invoke `ask_question` or present multiple-choice menus.** Stay in natural conversational chat as a senior pair programmer:
      • **Root Cause:** 1 sentence on why the UI or workflow behaves this way (and source file if known).
      • **Persona Friction:** 1 sentence on the practical operational consequence.
-     • **Recommended Fix & Trade-off:** 1-2 sentences with concrete approach and any trade-offs.
-     Immediately re-prompt the triage decision for finding #<N>.
+     • **Recommended Fix & Trade-off:** Concrete architectural approach, competitor benchmarks, and trade-offs.
+     Converse naturally with the user back and forth in plain markdown text. Answer follow-up questions, inspect code, and discuss options until a conclusion is reached.
+     **Only when a consensus is reached** (e.g. user says: "let's do that", "queue it", "dismiss it", "fix it now"):
+     Record the agreed decision and advance to finding #<N+1>. Do NOT trap the user with modal dialogs after each conversational turn.
    - **Fix immediately (leave triage now)**:
      If the user explicitly chooses to drop out of triage and fix right now:
      Make the code edit, verify it loads (or check local tests/types), update the finding with `iamu triage <slug> --status addressed --note "<summary of fix>"`.
@@ -564,11 +554,8 @@ When the user asks to review findings one by one:
          2. "Re-run walkthrough to verify dismissed items first"
          3. "Done for now (keep fixes open in iamu/findings/)"
      - Otherwise (CLI / text-only):
-       Apply fixes for the <K> queued findings now?
-         1. [Recommended] Apply fixes for queued findings in workspace now
-         2. Re-run walkthrough to verify dismissed items first
-         3. Done for now (keep fixes open in iamu/findings/)
-       Reply '1' to apply fixes [default], or select 2-3:
+       Triage complete. I recommend: Apply fixes for queued findings in workspace now.
+       Proceeding with code fixes — say "re-run first" or "done for now" to adjust.
 
    - **Executing the queued fixes:**
      When Option 1 is chosen, apply code edits for each queued finding sequentially in the workspace. Verify the changes once (run test/typecheck suite). Update each finding with `iamu triage <slug> --status addressed --note "<summary of fix>"`.
@@ -584,10 +571,8 @@ When the user asks to review findings one by one:
          1. "[Recommended] Re-run walkthrough to verify fixes hold"
          2. "Done for now (leave verification for later)"
      - Otherwise (CLI / text-only):
-       Verify fixes now?
-         1. [Recommended] Re-run walkthrough to verify fixes hold
-         2. Done for now (leave verification for later)
-       Reply '1' to re-run [default], or select 2:
+       Fixes applied and validated. I recommend: Re-run walkthrough to verify fixes hold.
+       Proceeding with verification re-run — say "done" to leave verification for later.
 
      When Option 1 is chosen:
      1. Start the verification run: `iamu start-run <scenario-slug> --target <target> --json`. Note: `start-run` automatically pulls all awaiting findings into `revisit` places in `walkthrough.json`.