@iamu-dev/iamu 0.2.0-beta.7 → 0.3.0-beta.0

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

@@ -1,21 +1,22 @@
 ---
 name: iamu-setup
-description: Set up a project for iamu — scaffold the iamu/ tree, capture domain context, and seed primary personas. Stops after context and initial personas; use iamu-new to draft scenarios next.
+description: Use when initializing or onboarding a project to Iamu, scaffolding the iamu/ directory, configuring testability boundaries, or seeding initial personas and inaugural scenarios.
 generatedBy: __IAMU_VERSION__
 ---
 
-Set up a project for scenario-driven walkthroughs — all local, no cloud required. Scaffolds an `iamu/` tree under your project root, analyzes the repo to compose a project-context summary, persists that context to `iamu/context.yml`, seeds 1–2 baseline personas to the casting panel, and optionally links to Iamu cloud. Stops there. Scenario creation belongs to `iamu-new`.
+Set up a project for scenario-driven walkthroughs — all local, no cloud required. Scaffolds an `iamu/` tree under your project root, analyzes the repo to compose a project-context summary, persists context to `iamu/context.yml`, seeds 1 primary persona into `iamu/personas/`, and drafts 1 inaugural scenario into `iamu/scenarios/`. Ready to run immediately with `iamu-run`.
 
 Model reminder (internal — users never type these): `capability → scenario → run → finding`. A scenario is the runnable thing — a situation narrative bound to a persona. Capabilities are optional labels that group scenarios. `iamu-new` creates scenarios; `iamu-run` executes them; `iamu-findings` reviews results.
 
 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, and any applicable regulations (if present).
-- **Capture & Seed** — persist to `iamu/context.yml` and scaffold 1–2 primary personas into `iamu/personas/` (or defer if user prefers).
-- **Cloud (optional)** — offer to link to Iamu cloud for sharing / teams / managed runs via `iamu auth login`. User can accept, skip, or defer.
-
-This skill does NOT create capabilities, situation outlines, or scenarios. That is what `iamu-new` is for. Setup = context + casting panel seeding.
+- **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: Project Domain & Description** — verify domain context and project description (`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
 
@@ -25,197 +26,305 @@ $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 understand the domain and propose primary personas.
+- **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 primary workflows, and real-world stakes.
+  > 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 understand the domain and propose primary personas.
+  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 primary workflows, and key constraints.
+  > 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
 
-Explore the codebase automatically — do NOT ask the user what files to read. Build a **substantive project description** that serves as the foundation for all downstream analysis (personas, scenarios, and walkthroughs). Read the following files when present:
+Explore the codebase automatically — do NOT ask the user what files to read. Extract domain and environment facts strictly from code:
+
+1. **Framework & Dev Server Port Detection:**
+   - Inspect package manifests: `package.json`, `Cargo.toml`, `pyproject.toml`, `go.mod`.
+   - Read framework configs to reliably extract default dev ports:
+     - `vite.config.*` / `svelte.config.*` → default port 5173
+     - `astro.config.*` → default port 4321
+     - `next.config.*` / Rails / Remix → default port 3000
+     - `wrangler.toml` / `wrangler.json` (Cloudflare Workers/Pages)
+     - `docker-compose.yml`
+   - Read `.env`, `.env.development`, `.env.local` for `PORT`, `VITE_PORT`, `NEXT_PUBLIC_APP_URL`.
+   - If unsure, check port reachability on common ports (3000, 5173, 8080, 4321).
+2. **Reachable Entry Route:**
+   - Scan page directories: `app/**/page.tsx`, `pages/**/*.tsx`, `src/routes/**/*.svelte`, React Router `routes.ts`/`App.tsx`.
+   - Pick a concrete static route (e.g. `/incidents/new`, `/cart`, `/checkout`), NOT an unresolved parameterized path (`/projects/:id`) unless seed fixture IDs are known.
+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. **Project Description & Domain:**
+   - Read `README.md`, `CLAUDE.md`, docs, OpenAPI / JSON schemas, route structures.
+   - Formulate a clear, concise description of what the software does, its primary workflows, and who uses it.
+   - **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. **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).
 
-- `README.md`, `CLAUDE.md`, `agents.md`
-- Package manifests — `package.json`, `Cargo.toml`, `pyproject.toml`, `go.mod`
-- Routes, API schemas, navigation, components, auth/user models
-- `docs/`, OpenAPI / JSON / GraphQL schemas, `src/`-style source directories
-- `.env.example`
+**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:
+• A target URL (staging, production, or docs — e.g., `https://app.example.com`)
+• A one-sentence description of what this product does
+• Or type `"sandbox"` to seed a pre-configured B2B SaaS demo
 
-**Quality Standard for Project Context (Knowledgeable Observer):**
-Write as an objective domain expert describing the business and its users, NOT marketing jargon, cookie notices, or tech stack. Do NOT hedge with "appears to be" or "seems to".
+---
 
-The description MUST capture four substantive dimensions:
-1. **What the product fundamentally IS** — core workflow, product type, and problem space.
-2. **Who actually uses it and what they come here to do** — enumerate the real user journeys (e.g. reporting incidents, triaging risks, delegating actions, auditing).
-3. **What makes THIS product specific** — geography, jurisdiction, regulatory mandates, or business model.
-4. **Operational characteristics** — how users physically and organizationally encounter the software (e.g. deskless frontline mobile workers in high-hazard environments, strict statutory completion deadlines, immutable audit trails).
+### 3. Step 1/3: Establish the Safety Fence (`iamu/testability.md`)
 
-*Example of target substance:*
-> "IA-systemet is Sweden's national work environment and safety incident management platform, utilized by thousands of Swedish enterprises to comply with statutory systematic work environment requirements (AML / AFS). It enables frontline employees to quickly log near-misses (tillbud), workplace accidents (olycksfall), and risk observations from desktop or mobile devices in the field. Core user journeys include real-time hazard reporting, line manager root-cause investigations, safety committee review, and action plan delegation with statutory compliance tracking."
+Present the detected environment and safety fence. Explain clearly *why* this boundary is required before any autonomous agent runs. Do NOT wrap in markdown code fences (` ``` `) when presenting to the user:
 
-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, geography, and specific compliance frameworks (only if evident).
+```text
+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.
 
-Do NOT collect code architecture (agent reads the codebase directly — tech stack doesn't affect walkthroughs).
+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>
+```
 
-**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:
-> - A target URL (staging, production, or docs — e.g., `https://app.example.com`)
-> - A one-sentence description of what this product does
-> - Or type `"sandbox"` to seed a pre-configured B2B SaaS demo
+**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):
+
+```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
+
+Reply '1' to accept [default], select 2-3, or tell me what to adjust:
+```
 
-**Autonomous Enrichment:**
-- **URL provided:** Fetch or search public marketing/docs for that site. Automatically extract the substantive narrative, core user journeys, and key actors. If industry regulations are obvious (e.g., healthcare/HIPAA, Swedish workplace safety/AML), include them in the narrative.
-- **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.
-- **Do NOT ask upfront about auth mechanics (`access`) or compliance frameworks (`governed_by`).** Infer if obvious, otherwise leave them blank.
+**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>
+---
 
-**Present ONLY the narrative description for user confirmation (Do NOT include metadata bullets or personas):**
+# Project Testability & Environment
 
-```markdown
-### 📋 Discovered Project Context
+## Target & Run Instructions
+- Command: <dev command>
+- Base URL: <target_url>
 
-<1–2 cohesive paragraphs written as a knowledgeable observer: what the product fundamentally is, who actually uses it, key user journeys, operational reality (e.g. mobile floor use, audit deadlines), and regulatory/market context. No marketing fluff, no hedging, no tech stack descriptions, and no bullet points.>
+## 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>
 
-**Next step:**
-Reply **"yes"** to save this context to `iamu/context.yml`, or tell me what to adjust.
+## Untestable Boundaries (Do Not Walk)
+- <List un-mocked external dependencies and external submission portals>
 ```
 
-Wait for the user to confirm or correct before writing. The user only needs to verify the narrative description and choose whether to accept or edit.
-
-### 3. Capture domain context and seed personas (Two-Phase Confirmation)
-
-#### Phase A: Persist Context
-Once the user confirms the narrative description:
-1. 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
-   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.
-   - `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.
+### 4. Step 2/3: Ground Domain Context & Project Description (`iamu/context.yml`)
 
-#### Phase B: Persona Casting (Opt-In & Separate Confirmation)
-Immediately after saving `iamu/context.yml`, ask the user if they want to seed baseline personas:
+Explain the purpose of project context: traditional tests only assert button clicks; Iamu evaluates user confusion, workflow friction, and whether a real person can succeed under real-world constraints.
 
-> Context saved to `iamu/context.yml`.
-> 
-> Would you like to seed 1–2 baseline personas to your casting panel now?
-> Reply **"yes"** to propose personas, or **"skip"** to create scenarios directly via `iamu-new`.
+Present the discovered domain and project description. Do NOT introduce or ask the user to approve personas or roles at this stage — personas are cast later when designing specific test journeys. Do NOT wrap in markdown code fences (` ``` `) when presenting to the user:
 
-**If the user chooses "yes":**
-Propose 1–2 primary personas grounded in the confirmed actors and operational characteristics:
+```text
+Step 2/3: Project Domain & Description
+Why this matters: Grounds the AI evaluator in your domain's real stakes and vocabulary so it can spot human confusion rather than just syntax errors.
 
-```markdown
-### 🎭 Proposed Primary Personas
+Discovered Domain:
+  Domain:             <domain name, e.g. Workplace safety management (EHS)>
+  Industry:           <industry, e.g. Manufacturing / Industrial>
+  Jurisdiction:       <jurisdiction or omit if standard web app>
+  Governed By:        <statutory regulations or standards, or omit if unregulated>
 
-#### 1. <Name> — *<Role / Title>*
-- **Context & Usage:** <Where and how they use the app (e.g. mobile on the floor vs. desktop in office)>
-- **Disposition:** <Patience level, technical confidence, key motivations>
-- **Friction Triggers:** <Specific interactions that cause friction, drop-off, or failure>
+Project Description:
+<1 cohesive paragraph: what the software fundamentally does, its primary user workflows, and the real-world conditions under which it is used. No marketing buzzwords, no hedging, and no tech stack trivia.>
+```
 
-#### 2. <Name> — *<Role / Title>*
-- **Context & Usage:** <Where and how they use the app>
-- **Disposition:** <Patience level, technical confidence, key motivations>
-- **Friction Triggers:** <Specific interactions that cause friction, drop-off, or failure>
+**Interactive Decision Gate:**
+Prompt the user to verify the project description:
+- If interactive user-prompt tools exist (`ask_question`, `ask_followup_question`), invoke it:
+  - Question: "Confirm project domain & description?"
+  - Options:
+    1. "[Recommended] Project description is accurate — proceed to design first test"
+    2. "Save project description only (skip scenario creation for now)"
+    3. "Adjust domain or description"
+- Otherwise (text-only/CLI):
+
+```text
+Confirm project domain & description?
+  1. [Recommended] Project description is accurate — proceed to design first test
+  2. Save project description only (skip scenario creation for now)
+  3. Adjust domain or description
+
+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
 ---
 
-**Next step:**
-Reply **"yes"** to scaffold these personas into `iamu/personas/`, or tell me what to adjust.
+<The substantive 1–2 paragraph project description and core user workflows>
 ```
 
-Wait for the user to confirm or adjust. Once confirmed:
-1. Scaffold personas using the CLI:
-   ```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
-   ```
-2. Validate once:
-   ```bash
-   iamu validate --all
-   ```
-3. Confirm: "Context saved and personas seeded in iamu/personas/. Run `iamu-new` to draft your first scenario."
-
-**If the user chooses "skip":**
-Confirm: "Context saved. Run `iamu-new` to draft your first scenario."
+*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`."
 
-### 4. Offer cloud link (optional)
+---
 
-Check the current state first:
+### 5. Step 3/3: Co-Design Your First Test Journey (`personas/`, `outlines/`, `scenarios/`)
 
-```bash
-iamu auth status --json
-```
+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).
 
-- **`cloud_linked: true`, `authenticated: true`** → already linked. Say so in one line with the dashboard link from `iamu open --print` and skip the offer.
-- **`cloud_linked: true`, `authenticated: false`** → the project is linked but this machine has no credentials, so nothing will push. Offer `iamu auth login`; it restores credentials for the same project without asking which one.
-- **`cloud_linked: false`** → ask once:
+Present the proposed test journey, including explicit **Auth Precondition Verification**. Do NOT wrap in markdown code fences (` ``` `) when presenting to the user:
 
-  > Want to link this project to Iamu Cloud? Every walkthrough then gets a shareable report link (screenshots and step replay), your team can triage findings together, and teammates can queue requests for you. Everything keeps working locally; `iamu auth disconnect` unlinks.
+```text
+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.
 
-Three outcomes:
+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.>"
+```
 
-- **Yes** → link it (below).
-- **Skip** → local-only project stays local-only. User can connect later by re-running `iamu-setup` or running `iamu auth login` directly.
-- **Later** → same as skip. No state change.
+**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
+
+Reply '1' to accept [default], select 2-4, or tell me what to adjust:
+```
 
-**Linking:**
+**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
+   ```
+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
+   ```
+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
+   ```
+4. **Validate all entities**:
+   ```bash
+   iamu validate --all
+   ```
 
-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. **Never pick the cloud project for the user.** 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 — the stored sign-in is reused, no second browser trip.
-3. On success the output ends with `Dashboard: <url>` and, when an agent host was detected, `iamu-sync MCP server registered`. Relay both: the dashboard link, and that restarting the agent session loads the team tools (work requests, teammate-change alerts).
+---
 
-If login times out or fails (cloud unreachable, sign-in timed out, or network error):
-- Explain clearly what happened: "Cloud linking could not be completed (<echo specific reason from command output>)."
-- Reassure the user: "Your local project setup is 100% complete and fully functional. Personas, scenarios, outlines, and walkthroughs run locally without cloud."
-- Provide the next step for linking: "You can link to Iamu Cloud anytime later by running `iamu auth login` in your terminal."
-- Point to the next creative action: "Next: run `iamu-new` to draft your first scenario."
+### 6. Completion & First Walkthrough Handoff
+
+Present the completion handoff cleanly.
+
+**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)`.
+
+Render the output:
+
+```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>
+
+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)
+```
 
-All three outcomes leave a usable local setup. Cloud is strictly additive.
+### 7. Cloud link (optional)
 
-### 5. How to use iamu from here
+Cloud linking is optional and non-blocking. It is recommended after executing your first walkthrough so you have run reports and findings to share.
 
-Close with one line pointing at the next step:
+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.
 
-```
-Setup complete. Next: run iamu-new to draft your first scenario.
-```
+If login times out or fails:
+- "Your local project setup is 100% complete and fully functional. Personas, scenarios, outlines, and walkthroughs run locally without cloud."
+- Point to: `iamu-run <persona-slug>--<outline-slug>`.
 
 ## Guidelines
 
-- **Plumbing and casting panel seeding.** This skill scaffolds configuration and seeds 1–2 baseline personas. It does not draft situation outlines or scenarios — that belongs to `iamu-new`.
+- **Baseline is runnable immediately.** Setup scaffolds configuration, 1 primary persona, 1 outline, and 1 bound scenario. The project graduates from setup in a 100% runnable state.
+- **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 3 writes `iamu/context.yml`, every downstream skill (`iamu-new`, `iamu-run`) auto-loads it. No need to pass `project_context` by hand.
-- **Handle re-runs gracefully.** An already-scaffolded project is a no-op on scaffold, a refresh on context/personas (if the user opts in), and a re-prompt on cloud link.
-- **Code-referenced vs inferred.** When drafting context in step 2, be explicit about which claims you read in the codebase vs which you inferred.
-- **Handle errors gracefully.** Unreachable file → note it, move on. Unreachable cloud (step 4) → report and let the user retry or defer.
+- **Context on disk is load-bearing.** Once step 4 writes `iamu/context.yml`, every downstream skill (`iamu-new`, `iamu-run`) auto-loads it.
+- **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.