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

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

@@ -115,16 +115,20 @@ Reply '1' to walk through all [default], select 2-3, or enter a finding number/s
 
 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.
 
-```
-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>)
+Format the visible finding in chat:
+
+```markdown
+### Finding #<N>/<total> [<SEVERITY>] — <title>
+> **Where:** `<Screen title or URL>` (Step <N>) · **Persona:** <Persona Name> (<Role>)
+> **Evidence:** `iamu/.runs/<run>/screenshots/step-<N>.png` [Dashboard](<url if cloud_linked>)
+
+**❌ 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`).
@@ -135,38 +139,45 @@ 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.
+**CRITICAL: Embed Scannable Finding 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. **Embed this exact scannable structure inside the `question` argument** with blank lines separating the sections:
 
 - If your environment provides an interactive user-prompt tool (e.g. `ask_question`, `ask_followup_question`), invoke it:
   - **Question:**
     """
-    Finding #<N>/<total>: <title>
+    Finding #<N>/<total> [<SEVERITY>]: <title>
+    Where: <Screen title or URL, Step N> · Persona: <Persona Name> (<Role>)
+
+    ❌ PROBLEM:
+    <What is broken or awkward on screen and why it hinders the persona in 1–2 direct sentences>
 
-    • 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>
+    💡 RECOMMENDATION:
+    <Concrete fix proposal from finding body>
 
     How should we triage this finding?
     """
   - **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)"
-    5. "Fix immediately (leave triage now)"
+    1. "[Recommended] Queue to fix (<brief 3-5 word fix summary>)"
+    2. "Dismiss / Skip (<brief reason if obvious, e.g. keep current design>)"
+    3. "Discuss / Explore trade-offs"
+    4. "Fix immediately (leave triage now)"
+    5. "Next finding (keep open / defer)"
 - 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)
+Finding #<N>/<total> [<SEVERITY>]: <title>
+Where: <Screen title or URL, Step N> · Persona: <Persona Name> (<Role>)
+
+❌ PROBLEM:
+<What went wrong and why it hinders the persona in 1–2 direct sentences>
+
+💡 RECOMMENDATION:
+<Concrete fix proposal>
+
+  1. [Recommended] Queue to fix (<brief 3-5 word fix summary>)
+  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], enter 2-5, or describe your decision:
 
@@ -183,6 +194,9 @@ 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. Only when a consensus or decision is reached ("let's queue it", "dismiss it", "fix it now"), record the decision and proceed. 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 +207,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."`.
 

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

@@ -216,7 +216,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 +248,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 +357,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 +376,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 +390,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.
@@ -475,52 +476,63 @@ 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:** `iamu/.runs/<run>/screenshots/step-<N>.png` [Dashboard](<url if cloud_linked>)
+
+   **❌ 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`).
 
    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.
+   **CRITICAL: Embed Scannable Finding 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. **Embed this exact scannable structure inside the `question` argument** with blank lines separating the sections (never a solid block of bullets):
 
    - If interactive tool available (e.g. `ask_question`, `ask_followup_question`), invoke it:
      - **Question:**
        """
-       Finding #<N>/<total>: <title>
+       Finding #<N>/<total> [<SEVERITY>]: <title>
+       Where: <Screen title or URL, Step N> · Persona: <Persona Name> (<Role>)
 
-       • 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>
+       ❌ PROBLEM:
+       <What is broken or awkward on screen and why it hinders the persona in 1–2 direct sentences>
+
+       💡 RECOMMENDATION:
+       <Concrete fix proposal from finding body>
 
        How should we triage this finding?
        """
      - **Options:**
-       1. "[Recommended] Queue to fix (mark for fix & continue triage)"
-       2. "Dismiss / Skip (not relevant or walker error)"
+       1. "[Recommended] Queue to fix (<brief 3-5 word fix summary>)"
+       2. "Dismiss / Skip (<brief reason if obvious, e.g. keep current design>)"
        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)
+     Finding #<N>/<total> [<SEVERITY>]: <title>
+     Where: <Screen title or URL, Step N> · Persona: <Persona Name> (<Role>)
+
+     ❌ PROBLEM:
+     <What went wrong and why it hinders the persona in 1–2 direct sentences>
+
+     💡 RECOMMENDATION:
+     <Concrete fix proposal>
+
+     1. [Recommended] Queue to fix (<brief 3-5 word fix summary>)
+     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:
 
 2. **Handle the user's decision**:
@@ -528,21 +540,29 @@ When the user asks to review findings one by one:
      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>"`.

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

@@ -110,18 +110,16 @@ Reply '1' to accept [default], select 2-3, or tell me what to adjust:
 ```
 
 **Action on confirmation (Option 1):**
-Write `iamu/testability.md`:
-```markdown
----
-target_url: <target_url>
-dev_command: <dev_command>
-auth_strategy: <dev_switcher | interactive | test_accounts | public>
-access: <How a walker becomes a given user: the switching mechanism, e.g. 'In the page, run localStorage.setItem("dev_persona", "<persona access>") and reload.' Omit when unknown. Never passwords or tokens.>
-harnesses:
-  - <detected harnesses>
----
-
-# Project Testability & Environment
+Persist the safety fence using `iamu set testability` (never invoke host file creation or edit tools):
+```bash
+iamu set testability \
+  --target "<target_url>" \
+  --dev-command "<dev_command>" \
+  --auth-strategy "<dev_switcher | interactive | test_accounts | public>" \
+  [--access "<access mechanism>"] \
+  [--harnesses "<detected harness 1>, <detected harness 2>"] \
+  [--untestable-boundaries "<external dependency 1>, <external dependency 2>"] \
+  --body "# Project Testability & Environment
 
 ## Target & Run Instructions
 - Command: <dev command>
@@ -137,7 +135,8 @@ harnesses:
 - <List existing MSW mock files, DB seed scripts, or fixture directories>
 
 ## Untestable Boundaries (Do Not Walk)
-- <List un-mocked external dependencies and external submission portals>
+- <List un-mocked external dependencies and external submission portals>" \
+  --json
 ```
 
 ---
@@ -182,22 +181,16 @@ Reply '1' to accept [default], select 2-3, or tell me what to adjust:
 ```
 
 **Action on confirmation (Option 1):**
-Write `iamu/context.yml`. Put structured fields in frontmatter and the project description in the markdown body below the `---`:
-```yaml
----
-schema_version: 1
-domain: <domain>
-# industry: <industry>               # optional
-# jurisdiction: <jurisdiction>       # strictly optional - omit if standard web app
-# governed_by:                      # strictly optional - omit if not regulated
-#   - name: <statutory regulation>
-#     authority_level: regulation
----
-
-<The substantive 1–2 paragraph project description and core user workflows>
+Persist the domain context using `iamu set context` (never invoke host file creation or edit tools). Put structured fields in frontmatter and the project description in the markdown body below the `---` via `--body`:
+```bash
+iamu set context \
+  --domain "<domain>" \
+  [--industry "<industry>"] \
+  --body "<The substantive 1–2 paragraph project description and core user workflows>" \
+  --json
 ```
 
-*If user chooses Option 2 (Save context only):* write `context.yml` and exit cleanly:
+*If user chooses Option 2 (Save context only):* run `iamu set context ...` as above, and exit cleanly:
 "✓ Project context initialized. When you're ready to create your first test journey, run `/iamu:new`."
 
 ---
@@ -213,6 +206,7 @@ Step 3/3: Co-Design Your First Test Journey
 Why this matters: Validates whether a real human with specific operational pressures can complete a critical task without getting blocked or frustrated.
 
 Baseline Test Proposal (WYSIWGW Spec-Sheet):
+  Capability:         <Capability Name> (<What staff can do in this area>)
   Persona:            <Name> (<Role / Title>)
                       • Reality: <Working context, physical habits, tenure, pressures>
                       • Friction: <Diagnostic friction, skepticism, bounce trigger>
@@ -246,19 +240,23 @@ Reply '1' to accept [default], select 2-4, or tell me what to adjust:
 ```
 
 **Action on confirmation (Option 1 or Option 2):**
-1. **Scaffold Persona**:
+1. **Scaffold Primary Capability** (if not already existing):
    ```bash
-   iamu new persona --name "<Name>" --role "<Role>" --disposition "<Disposition>" --body "<2-4 sentence narrative detailing technical habits, patience level, and specific friction triggers>" [--access "<account-or-role>"] --json
+   iamu new capability --name "<Capability Name>" --description "<What staff can do in this area>" --json
    ```
 2. **Scaffold Situation Outline**:
    ```bash
-   iamu new outline --name "<Outline Title>" --tension "<Core Tension>" --human-test "<Concrete yes/partial/no evaluation question>" --narrative "<2-3 sentence problem-space narrative without UI terms>" --json
+   iamu new outline --name "<Outline Title>" --capability "<capability-slug>" --tension "<Core Tension>" --human-test "<Concrete yes/partial/no evaluation question>" --narrative "<2-3 sentence problem-space narrative without UI terms>" --json
+   ```
+3. **Scaffold Persona**:
+   ```bash
+   iamu new persona --name "<Name>" --role "<Role>" --disposition "<Disposition>" --body "<2-4 sentence narrative detailing technical habits, patience level, and specific friction triggers>" [--access "<account-or-role>"] --json
    ```
-3. **Scaffold Bound Scenario**:
+4. **Scaffold Bound Scenario**:
    ```bash
    iamu new scenario --name "<persona-slug>--<outline-slug>" --outline "<outline-slug>" --persona "<persona-slug>" --entry "<entry_path>" --body "<Persona's first-person test brief describing what they intend to achieve>" --json
    ```
-4. **Validate all entities**:
+5. **Validate all entities**:
    ```bash
    iamu validate --all
    ```
@@ -325,6 +323,7 @@ If login times out or fails:
 - **Clean terminal formatting.** Do not wrap agent briefings in markdown code fences (` ``` `). Use fixed column alignment for attributes and clean tree diagrams for generated files.
 - **Non-regulated software is the default.** Do not invent or force regulations (`governed_by`) on apps, developer tools, or consumer software. If the codebase has no compliance documentation, omit `governed_by` entirely.
 - **Explore automatically.** Read the codebase before asking the user anything. The user should only need to confirm or correct, not describe their own project from scratch.
-- **Context on disk is load-bearing.** Once step 4 writes `iamu/context.yml`, every downstream skill (`iamu-new`, `iamu-run`) auto-loads it.
+- **Context on disk is load-bearing.** Once `iamu set context` writes `iamu/context.yml`, every downstream skill (`iamu-new`, `iamu-run`) auto-loads it.
+- **Never invoke host Edit or Write tools.** Always scaffold or modify configuration and entities via `iamu set` and `iamu new` shell commands. Host tool edits trigger modal confirmation tripwires for the user.
 - **Handle re-runs gracefully.** An already-scaffolded project is a no-op on scaffold, a refresh on context/personas/scenarios (if the user opts in), and a re-prompt on cloud link.
 - **Handle errors gracefully.** Unreachable file → note it, move on. Unreachable cloud → report and let the user retry or defer.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iamu-dev/iamu",
-  "version": "0.3.0-beta.0",
+  "version": "0.3.0-beta.1",
   "type": "module",
   "description": "Test your product as realistic personas — scenario-driven development CLI",
   "license": "UNLICENSED",
@@ -59,8 +59,8 @@
     "typescript": "^5.8.0",
     "vitest": "^4.1.11",
     "@iamu-dev/local-store": "0.1.0",
-    "@iamu/tsconfig": "0.1.0",
-    "@iamu-dev/protocol": "0.1.0"
+    "@iamu-dev/protocol": "0.1.0",
+    "@iamu/tsconfig": "0.1.0"
   },
   "scripts": {
     "build": "tsup && tsc -b --force tsconfig.build.json --emitDeclarationOnly && node scripts/copy-assets.mjs",