@iamu-dev/iamu 0.2.0-beta.10 → 0.2.0-beta.12

package/dist/templates/prompts/walk.md

@@ -80,6 +80,8 @@ Follow the persona's motivation. Spend time on what matters to them. When you ha
 
 Browser failures — blank page, stuck spinner, cryptic error, 404 — are signal, not noise. Screenshot the failure state, record it as a finding, move on. Do not retry silently or open developer tools: the persona cannot.
 
+If a step command fails with `The user stopped this run from the live viewer. End the walk now.`, do not retry or continue: stop the walkthrough immediately and proceed to Synthesis with what you observed so far.
+
 ## Tooling limitations vs product bugs
 
 Your browser tooling has limitations that can look like product bugs. Before recording a finding, ask: "Is this a real product issue, or is my tooling failing?"

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

@@ -196,13 +196,16 @@ iamu start-run <scenario-slug> --target <target> --json
 
 This creates the run directory, writes `walkthrough.json` with resolved persona/outline slugs and the build under test (git SHA and branch, whether there are uncommitted changes outside `iamu/` with a fingerprint of them, CI run when in CI), and returns:
 ```json
-{ "run_id": "...", "path": "...", "scenario_slug": "...", "target_url": "...", "persona_slug": "...", "outline_slug": "...", "build": { "git_sha": "...", "git_branch": "...", "git_dirty": false }, "environment": "https://staging.example.com" }
+{ "run_id": "...", "path": "...", "scenario_slug": "...", "target_url": "...", "live_viewer_url": "https://app.iamu.dev/projects/.../live/...", "persona_slug": "...", "outline_slug": "...", "build": { "git_sha": "...", "git_branch": "...", "git_dirty": false }, "environment": "https://staging.example.com" }
 ```
 
 Pass `--build <label>` to name the build (a version or release tag) and `--env <name>` to name the environment (`staging`, `production`); without `--env` the environment is the target URL's origin. Neither is needed for a local walk.
 
 Use the returned `run_id` and `path` for all subsequent operations.
 
+**If `live_viewer_url` is returned**, immediately output it to the user so the operator can follow along live in their browser:
+> 🔴 **Live stream:** `<live_viewer_url>`
+
 **Size the browser for this persona** (`iamu browse` only), every run — also when a browser is already open from an earlier run:
 
 ```bash
@@ -253,6 +256,15 @@ The subagent inherits the driving-surface tools and drives the product independe
 
 After the walker returns, continue to the post-walk pipeline below.
 
+**Live progress reporting (terminal monitoring):**
+While the walker subagent executes, maintain visible feedback in the terminal:
+- At start (if cloud-linked): output the live dashboard viewer link: `Live stream: <viewer_url>`
+- As progress occurs (on subagent notifications or milestone steps): output a concise single-line progress update:
+  `step <N> · <action/surface> · <F> finding(s)`
+  This gives the terminal operator immediate real-time visibility into the persona's progress.
+- If the walker stops because the user pressed Stop in the viewer (`The user stopped this run from the live viewer. End the walk now.`), respect the cancellation and proceed to post-walk assembly with existing steps.
+- Once the walker finishes, announce completion and proceed immediately to the post-walk pipeline.
+
 **Recording steps:**
 
 Use atomic CLI commands to drive and record in one step — do NOT manually author JSON files:

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

@@ -11,10 +11,12 @@ Model reminder (internal — users never type these): `capability → scenario
 What this skill does, end to end:
 
 - **Scaffold** — `iamu/` tree on disk via `iamu init`. No login, no cloud.
-- **Understand** — read the repo to identify domain, primary user archetypes, reachable routes, and testability.
-- **Propose & Scaffold Baseline** — present a single unified briefing: domain narrative, primary persona, and inaugural scenario. On confirmation ("yes"), scaffold `context.yml`, `testability.md`, persona, outline, and scenario to disk.
-- **Next Action** — point directly to `iamu-run <scenario>` with copy-pasteable execution command.
-- **Cloud (optional)** — offer to link to Iamu cloud for sharing / teams / managed runs via `iamu auth login`. User can accept, skip, or defer.
+- **Understand** — read the repo automatically to detect dev server, mock fixtures, external boundaries, domain stakes, and user roles.
+- **Step 1: Safety & Testability Fence** — agree on the sandbox boundaries (`iamu/testability.md`) so the autonomous browser agent never leaks data or hits real external services.
+- **Step 2: Domain Reality & Role Pool** — verify domain context and candidate roles (`iamu/context.yml`) to ground UX evaluations.
+- **Step 3: Co-Design First Journey** — co-create a high-friction scenario, verify auth preconditions (`personas/`, `outlines/`, `scenarios/`), and validate.
+- **Next Action** — copy-pasteable command to launch your first walkthrough.
+- **Cloud (optional)** — link to Iamu Cloud if you want to share findings with your team.
 
 $ARGUMENTS
 
@@ -24,11 +26,17 @@ $ARGUMENTS
 
 Check whether `iamu/config.json` already exists:
 
-- **If already scaffolded (`iamu/config.json` exists):** Do not re-run `iamu init`. Introduce the step concisely and proceed directly to Step 2:
-  > Analyzing your codebase now to map the domain, primary persona, and first test scenario.
+- **If already scaffolded (`iamu/config.json` exists):** Do not re-run `iamu init`. Introduce the workflow roadmap concisely and proceed directly to Step 2:
+  > **Setting up Iamu.** We'll build your testing foundation together in three clear steps:
+  > 1. **Safety Boundary (`testability.md`)**: Ensure the autonomous browser agent is fenced to local dev and cannot trigger real-world external side effects.
+  > 2. **Domain Grounding (`context.yml`)**: Teach Iamu what the application does, its real stakes, and candidate roles.
+  > 3. **First Journey (`personas/` + `scenarios/`)**: Design a realistic human friction test and verify how your persona logs in.
 - **If not yet scaffolded:** Run `iamu init [project-name]` in the terminal (pass a project name if the user named one explicitly; otherwise omit). The command scaffolds `iamu/config.json`, entity subdirs, `.runs/`, `.cache/`, `.gitignore`.
-  Introduce iamu first:
-  > **iamu** tests your product as realistic personas and reports what works, what doesn't, and how to fix it. I'll analyze your codebase now to map the domain and prepare your first test scenario.
+  Introduce the workflow roadmap:
+  > **iamu** tests your product as realistic personas and reports what works, what doesn't, and how to fix it. We'll build your testing foundation together in three collaborative steps:
+  > 1. **Safety Boundary (`testability.md`)**: Define where the browser agent is allowed to go, and what external services must never be touched.
+  > 2. **Domain Grounding (`context.yml`)**: Ground Iamu in what your product actually is, its operational reality, and key user roles.
+  > 3. **First Journey (`personas/` + `scenarios/`)**: Design a realistic human friction test and verify how your persona logs in.
 - **Error containing "legacy `.iamu/` layout"** → tell the user to remove the legacy directory, then re-run.
 
 ### 2. Understand the project
@@ -51,20 +59,13 @@ Explore the codebase automatically — do NOT ask the user what files to read. E
 3. **Auth & Persona Access:**
    - Inspect auth route guards (`middleware.ts`, ProtectedRoute, session hooks).
    - Identify dev bypass (`MOCK_AUTH`), test accounts/fixtures, persona switcher, or public access.
-4. **Domain Narrative & Cast:**
+4. **Domain Narrative & Candidate Roles:**
    - Read `README.md`, `CLAUDE.md`, docs, OpenAPI / JSON schemas, user models.
-   - Extract 1 primary protagonist and 2 secondary actors from real user roles.
+   - Extract candidate roles from real user models in code.
    - **STRICT REGULATION RULE:** Never infer regulations from industry keywords. Only include `governed_by` if the codebase explicitly references specific legislation or statutory standards. Non-regulated software is the default — omit `governed_by` entirely if absent.
-5. **Primary Persona Rigor:**
-   - Follow `iamu/.prompts/persona.md`: no generic marketing adjectives ("tech-savvy", "coffee lover"). Ground in working physical reality, time pressure, and concrete diagnostic friction / bounce conditions. True whether the product exists or not.
-
-Synthesize the project into a cohesive, substantive narrative (1–2 paragraphs):
-- What the product fundamentally is, its primary domain, and who uses it.
-- Key user journeys and operational characteristics (e.g. mobile floor use, audit deadlines).
-- Market and geography (only if evident).
-
-Audit testability and target environment:
-Inspect `package.json` dev scripts, existing mock harnesses (MSW, seed scripts), auth route guards (`middleware.ts`, ProtectedRoute, session hooks), and page/route directories (`app/`, `src/routes/`). Use these findings to populate `iamu/testability.md`.
+5. **Safety & Untestable Boundaries:**
+   - Scan for external API calls, third-party integrations (Stripe, Twilio, external government submission portals, live OAuth/Keycloak SSO).
+   - Identify local mock fixtures (`msw`, seed SQL scripts, mock services).
 
 **If there is no code (greenfield, design phase, or test sandbox):** do NOT interrogate the user with a multi-part survey or ask for dev auth plumbing. Ask for a single entry point:
 > No local codebase detected. To seed context, provide one of:
@@ -72,185 +73,250 @@ Inspect `package.json` dev scripts, existing mock harnesses (MSW, seed scripts),
 > - A one-sentence description of what this product does
 > - Or type `"sandbox"` to seed a pre-configured B2B SaaS demo
 
-**Autonomous Enrichment:**
-- **URL provided:** Fetch or search public marketing/docs for that site. Automatically extract the substantive narrative, core user journeys, and key actors.
-- **One-sentence summary provided:** Immediately expand into a full substantive narrative using domain knowledge.
-- **"sandbox" provided:** Seed a standard B2B SaaS narrative with Admin and End-User roles.
+---
 
-### 3. Present Unified Baseline Proposal (Single Confirmation Gate)
+### 3. Step 1/3: Establish the Safety Fence (`iamu/testability.md`)
 
-Present the discovered domain context, 1 primary persona, and 1 inaugural scenario in a single scannable briefing.
+Present the detected environment and safety fence. Explain clearly *why* this boundary is required before any autonomous agent runs:
 
-Do NOT wrap the briefing in a markdown code fence (` ``` `). Output normal markdown so the user's terminal formats bolding and layout cleanly.
-Do NOT split this into multiple sequential permission questions. Present the complete baseline package at once:
+```markdown
+Step 1/3: Safety Fence & Environment Boundary
+Why this matters: Iamu drives a real headless browser with full agency. This boundary guarantees the agent stays confined to your local environment and never touches external services or triggers real-world side effects.
 
-Discovered Project Context:
-  Domain:       <domain name, e.g. workplace safety management>
-  Scope:        <Jurisdiction or "Standard Web App / Unregulated">
-  Cast:         <Primary Protagonist> (protagonist), <Secondary Actor 1>, <Secondary Actor 2>
-  Target:       <target_url, e.g. http://localhost:5173> (Dev Command: `<dev_command, e.g. pnpm dev>`)
-  Auth Access:  <How walker assumes role, e.g. "Dev persona switcher" or "Public">
+Detected Environment:
+  Target URL:       <target_url, e.g. http://localhost:5173>
+  Dev Command:      <dev_command, e.g. ./dev or pnpm dev>
+  Safe Fixtures:    <detected seed scripts or mock handlers, e.g. organization_realistic_seed.sql, MSW>
+  DO NOT WALK:      <detected external services, e.g. Arbetsmiljöverket external submission portal (anmalarbetsskada.se), Real SMS/Email gateways, Real OIDC Keycloak>
+```
 
-<1 cohesive paragraph: what the product fundamentally is, who actually uses it, and its core operational reality. No marketing fluff, no hedging, and no tech stack trivia.>
+**Interactive Decision Gate:**
+Prompt the user to verify the safety boundary:
+- If interactive user-prompt tools exist (`ask_question`, `ask_followup_question`), invoke it:
+  - Question: "Confirm safety fence and dev environment?"
+  - Options:
+    1. "[Recommended] Safety boundaries look safe — save fence and proceed"
+    2. "Adjust boundaries (add forbidden external URLs, change dev command or port)"
+    3. "Skip safety fence for now"
+- Otherwise (text-only/CLI):
 
-Baseline Test Proposal (WYSIWGW Spec-Sheet):
-  Persona:      <Name> (<Role / Title>)
-                • Reality: <Working context, physical habits, tenure>
-                • Friction: <Diagnostic friction, skepticism, bounce trigger>
-  Situation:    <Outline Title>
-                • Tension: <Core problem-space tension in X vs Y format — no UI button names>
-                • Evaluation Checkpoint: <Concrete binary yes/partial/no question for evaluator>
-  Walk Surface: Entry: `<entry_path>` | Target: `<target_url>`
-  Walker Brief: "<2–3 sentence first-person test brief that will be written verbatim to disk. States immediate intent and constraints before opening tool. Zero UI terminology.>"
+```text
+Confirm safety fence and dev environment?
+  1. [Recommended] Safety boundaries look safe — save fence and proceed
+  2. Adjust boundaries (add forbidden external URLs, change dev command or port)
+  3. Skip safety fence for now
+
+Press Enter to accept [1], select 2, 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>
+harnesses:
+  - <detected harnesses>
+---
+
+# Project Testability & Environment
+
+## Target & Run Instructions
+- Command: <dev command>
+- Base URL: <target_url>
+
+## Auth & Access Boundary
+- <How a walker becomes this persona in dev or test mode>
+
+## Reachable Surfaces
+- <List discovered routes/entry points>
+
+## Mocks & Data Fixtures
+- <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>
+```
 
 ---
 
-**Interactive Decision:**
-Prompt the user to confirm or adjust the baseline:
-- If your environment provides an interactive user-prompt tool (e.g. `ask_question`, `ask_followup_question`), invoke it:
-  - Question: "Scaffold this iamu test baseline?"
+### 4. Step 2/3: Ground Domain Reality & Role Candidates (`iamu/context.yml`)
+
+Explain the purpose of domain grounding: traditional tests only assert button clicks; Iamu evaluates user confusion, workflow friction, and whether a real person can succeed under operational pressure.
+
+Present the discovered domain reality and candidate roles:
+
+```markdown
+Step 2/3: Product Domain & Candidate Roles
+Why this matters: Grounds the AI evaluator in your domain's real operational stakes, vocabulary, and regulations so it can spot human confusion rather than just syntax errors.
+
+Discovered Domain Context:
+  Domain:             <domain name, e.g. Workplace safety management (EHS / SAM)>
+  Regulatory Scope:   <Jurisdiction or "Standard Web App / Unregulated">
+  Candidate Roles:    <Role 1>, <Role 2>, <Role 3>
+                      *(Open casting panel — your team can create unlimited personas anytime via /iamu:new)*
+
+<1 cohesive paragraph: what the product fundamentally is, who actually uses it, and its core operational reality. No marketing fluff, no hedging, and no tech stack trivia.>
+```
+
+**Interactive Decision Gate:**
+Prompt the user to verify the domain grounding:
+- If interactive user-prompt tools exist (`ask_question`, `ask_followup_question`), invoke it:
+  - Question: "Confirm domain grounding and role pool?"
   - Options:
-    1. "[Recommended] Scaffold baseline and prepare first walkthrough"
-    2. "Switch perspective: Walk as <Secondary Actor 1 Name> (<Role>)"
-    3. "Adjust domain context, target URL, or persona details"
-- Otherwise (in CLI or text-only environments), present them as an enumerated list:
+    1. "[Recommended] Domain grounding is accurate — proceed to design first test"
+    2. "Save domain context only (skip scenario creation for now)"
+    3. "Adjust domain narrative or role pool"
+- Otherwise (text-only/CLI):
 
-Scaffold this iamu test baseline?
-  1. [Recommended] Scaffold baseline and prepare first walkthrough
-  2. Switch perspective: Walk as <Secondary Actor 1 Name> (<Role>)
-  3. Adjust domain, target URL, or persona details
+```text
+Confirm domain grounding and role pool?
+  1. [Recommended] Domain grounding is accurate — proceed to design first test
+  2. Save domain context only (skip scenario creation for now)
+  3. Adjust domain narrative or role pool
 
 Press Enter to accept [1], select 2, or tell me what to adjust:
-(Treat empty Enter or return as Option 1)
-
-### 4. Scaffold the Test Suite Atomically
-
-When the user selects Option 1 (or confirms):
-
-1. **Write `iamu/context.yml`**:
-   Derive the structured frontmatter fields (`domain`, `actors`, `jurisdiction`, `governed_by`) from the confirmed text, and write `iamu/context.yml` with your file-editing tool. Put structured fields in frontmatter and the substantive narrative in the markdown body below the `---`:
-
-   ```yaml
-   ---
-   schema_version: 1
-   domain: workplace safety management
-   # jurisdiction: Sweden / EU          # optional
-   # governed_by:                       # strictly optional - omit if not regulated
-   #   - name: AFS 2023:2
-   #     authority_level: regulation
-   actors:
-     - name: Store Admin
-       role: Manages catalog, inventory, and order fulfillment
-     - name: First-Time Buyer
-       role: Explores products, adds to cart, and checks out
-     - name: Customer Support Agent
-       role: Handles order discrepancies, refunds, and customer inquiries
-   access: >-
-     No login in dev. In the page, set localStorage "dev_persona" to the
-     persona's access value and reload.
-   ---
-
-   <The substantive 1–2 paragraph project description and core user journeys>
-   ```
+```
 
-   Rules:
-   - `domain` — one line. Mandatory.
-   - Body markdown (below `---`) — substantive description and user journeys. Downstream skills read this as extended grounding.
-   - `jurisdiction` — optional. Only if evident or relevant.
-   - `governed_by[]` — strictly optional. Order by authority. Omit entirely if no regulations apply.
-   - `actors[]` — all identified roles and their responsibilities. Keep secondary roles here so context has cast depth.
-   - `access` — optional. Only what the docs actually say; leave it out rather than guess.
-   - Do NOT add `industry` or `architecture` — these don't affect walkthroughs.
+**Action on confirmation (Option 1):**
+Write `iamu/context.yml`. Put structured fields in frontmatter and the substantive narrative in the markdown body below the `---`:
+```yaml
+---
+schema_version: 1
+domain: <domain>
+# jurisdiction: <jurisdiction>       # optional
+# governed_by:                      # strictly optional - omit if not regulated
+#   - name: <statutory regulation>
+#     authority_level: regulation
+actors:
+  - name: <Role 1>
+    role: <Responsibilities>
+  - name: <Role 2>
+    role: <Responsibilities>
+---
 
-2. **Write `iamu/testability.md`**:
-   Scaffold the target environment, dev command, auth strategy, reachable surfaces, mock harnesses, and untestable boundaries discovered from the code:
+<The substantive 1–2 paragraph project description and core user journeys>
+```
 
-   ```markdown
-   ---
-   target_url: http://localhost:3000
-   dev_command: <detected dev script, e.g. pnpm dev or pnpm dev:mock>
-   auth_strategy: <dev_switcher | interactive | test_accounts | public>
-   harnesses:
-     - <detected harnesses, e.g. msw, seed>
-   ---
+*If user chooses Option 2 (Save context only):* write `context.yml` and exit cleanly:
+> ✓ Project context initialized. When you're ready to create your first test journey, run `/iamu:new`.
 
-   # Project Testability & Environment
+---
 
-   ## Target & Run Instructions
-   - Command: <dev command>
-   - Base URL: <target_url>
+### 5. Step 3/3: Co-Design Your First Test Journey (`personas/`, `outlines/`, `scenarios/`)
 
-   ## Auth & Access Boundary
-   - <How a walker becomes this persona in dev or test mode>
+Explain the journey model: an Iamu test binds a **Persona** (with habits, pressures, and impatience) to a **Situation** (a realistic high-stakes problem) with an **Evaluation Checkpoint** (a concrete binary question for the AI judge).
 
-   ## Reachable Surfaces
-   - <List discovered routes/entry points, e.g. /login, /dashboard, /incidents>
+Present the proposed test journey, including explicit **Auth Precondition Verification**:
 
-   ## Mocks & Data Fixtures
-   - <List existing MSW mock files, DB seed scripts, or fixture directories>
+```markdown
+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.
 
-   ## Untestable Boundaries (Do Not Walk)
-   - <List un-mocked external dependencies, e.g. live Stripe charges, SMS 2FA, external SSO>
-   ```
+Baseline Test Proposal (WYSIWGW Spec-Sheet):
+  Persona:            <Name> (<Role / Title>)
+                      • Reality: <Working context, physical habits, tenure, pressures>
+                      • Friction: <Diagnostic friction, skepticism, bounce trigger>
+  Situation:          <Outline Title>
+                      • Tension: <Core problem-space tension in X vs Y format — no UI button names>
+                      • Evaluation: <Concrete binary yes/partial/no question for evaluator>
+  Walk Surface:       Entry: `<entry_path>` | Target: `<target_url>`
+  Auth Precondition:  <Detected auth mechanism, e.g. "Dev persona switcher (localStorage.sf_dev_persona = 'anna')" or "Public">
+  Walker Brief:       "<2–3 sentence first-person test brief that will be written verbatim to disk. States immediate intent and constraints before opening tool. Zero UI terminology.>"
+```
+
+**Interactive Decision Gate:**
+Prompt the user to verify the scenario and its auth precondition:
+- If interactive user-prompt tools exist (`ask_question`, `ask_followup_question`), invoke it:
+  - Question: "Scaffold this baseline journey?"
+  - Options:
+    1. "[Recommended] Scaffold journey with <detected auth mechanism>"
+    2. "Use interactive human login handshake (pause browser for live login)"
+    3. "Switch role / design a different scenario (write-in)"
+    4. "Skip scenario for now"
+- Otherwise (text-only/CLI):
+
+```text
+Scaffold this baseline journey?
+  1. [Recommended] Scaffold journey with <detected auth mechanism>
+  2. Use interactive human login handshake (pause browser for live login)
+  3. Switch role / design a different scenario
+  4. Skip scenario for now
 
-   Keep `context.yml` strictly about domain reality (which the Walker subagent reads), and `testability.md` strictly about developer testability and execution boundaries (which orchestrator skills read).
+Press Enter to accept [1], select 2, or tell me what to adjust:
+```
 
-3. **Scaffold Primary Persona**:
-   Scaffold 1 primary protagonist into `iamu/personas/<persona-slug>.md` using the CLI:
+**Action on confirmation (Option 1 or Option 2):**
+1. **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
    ```
-
-4. **Scaffold Situation Outline**:
-   Scaffold the inaugural outline into `iamu/outlines/<outline-slug>.md` using the CLI:
+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
    ```
-
-5. **Scaffold Bound Scenario**:
-   Bind the persona and outline into `iamu/scenarios/<persona-slug>--<outline-slug>.md` using the CLI:
+3. **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
    ```
-
-6. **Validate all entities**:
+4. **Validate all entities**:
    ```bash
    iamu validate --all
    ```
 
-7. **Present Completion & Immediate Next Action**:
-   Render the visual scaffolding tree and provide the direct command to run the walkthrough:
+---
 
-   ```text
-   ✓ Scaffolding complete:
+### 6. Completion & First Walkthrough Handoff
 
-     iamu/
-     ├── context.yml          [domain: <domain>]
-     ├── testability.md       [target: <target_url>]
-     ├── personas/
-     │   └── <persona-slug>.md
-     ├── outlines/
-     │   └── <outline-slug>.md
-     └── scenarios/
-         └── <persona-slug>--<outline-slug>.md
+Present the completion handoff cleanly.
 
-   Next step:
-     Ensure your dev server is running on <target_url>, then run:
+**Formatting & Output Rules:**
+- Do NOT output markdown header hashes (`#`, `##`, `###`) in the terminal handoff. Use bold (`**Next Step:**`) or plain text.
+- Do NOT output a redundant bullet list of "Generated entities:" after the file tree. The visual tree already displays the files.
+- Check `iamu/config.json`:
+  - **If `cloud_linked: true`:** Output `• iamu sync      Sync completed runs and findings to Iamu Cloud`. Do NOT recommend `iamu auth login`.
+  - **If `cloud_linked: false`:** Output `• iamu auth login  Connect to Iamu Cloud to share run reports with your team (optional)`.
 
-       $ iamu-run <persona-slug>--<outline-slug>
+Render the output:
 
-   Other commands when you're ready:
-   • iamu-new      Draft a scenario for a different product flow
-   • iamu-propose  Brainstorm high-risk workflows and blind spots
-   • iamu doctor   Diagnose test environment and target health
-   • iamu auth login  Link to Iamu Cloud to share run reports with your team (optional)
-   ```
+```text
+✓ Scaffolding complete:
+
+  iamu/
+  ├── testability.md       [safety fence active: <target_url>]
+  ├── context.yml          [domain: <domain>]
+  ├── personas/
+  │   └── <persona-slug>.md
+  ├── outlines/
+  │   └── <outline-slug>.md
+  └── scenarios/
+      └── <persona-slug>--<outline-slug>.md
+
+Next step:
+  Ensure your dev server is running on <target_url>, then trigger the walkthrough in your agent:
+
+    iamu-run <persona-slug>--<outline-slug>
+
+  Or run directly from your shell:
+
+    $ iamu start-run <persona-slug>--<outline-slug> --target <target_url>
+
+Other commands when you're ready:
+• iamu-new      Draft a scenario for a different product flow
+• iamu-propose  Brainstorm high-risk workflows and blind spots
+• iamu doctor   Diagnose test environment and target health
+<If cloud_linked: true>
+• iamu sync     Sync completed runs and findings to Iamu Cloud
+<If cloud_linked: false>
+• iamu auth login  Connect to Iamu Cloud to share run reports with your team (optional)
+```
 
-### 5. Cloud link (optional)
+### 7. Cloud link (optional)
 
 Cloud linking is optional and non-blocking. It is recommended after executing your first walkthrough so you have run reports and findings to share.
 
-If the user explicitly asks to link during setup:
+If the project is not yet linked and the user explicitly asks to link during setup:
 1. Tell the user: "Opening browser for Iamu Cloud login..." then run `iamu auth login`. Allow the command at least 150 seconds for the user to complete sign-in in their browser. If your shell cannot wait that long, or runs where no browser can open (remote or container session), ask the user to run `iamu auth login` in their own terminal and tell you when it is done.
 2. In a non-interactive shell with existing cloud projects, login stops after sign-in and lists them as `iamu auth login --project <id>` lines plus `--project new`. Show that list, ask which project this repository belongs to, then re-run with their choice.
 3. On success the output ends with `Dashboard: <url>` and registered MCP server.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iamu-dev/iamu",
-  "version": "0.2.0-beta.10",
+  "version": "0.2.0-beta.12",
   "type": "module",
   "description": "Test your product as realistic personas — scenario-driven development CLI",
   "license": "UNLICENSED",
@@ -58,8 +58,8 @@
     "tsup": "^8.5.1",
     "typescript": "^5.8.0",
     "vitest": "^4.1.11",
-    "@iamu-dev/local-store": "0.1.0",
     "@iamu-dev/protocol": "0.1.0",
+    "@iamu-dev/local-store": "0.1.0",
     "@iamu/tsconfig": "0.1.0"
   },
   "scripts": {