@iamu-dev/iamu 0.2.0-beta.1 → 0.2.0-beta.11

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: Set up a project for iamu — scaffold the iamu/ tree, capture domain context, seed primary persona, and draft inaugural scenario. Ready to run immediately via iamu-run.
 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: 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
 
@@ -23,170 +24,313 @@ $ARGUMENTS
 
 ### 1. Scaffold the iamu/ tree
 
-Run `iamu init` in the terminal. Pass a project name when the user names one explicitly; otherwise the tool derives it from the directory basename.
+Check whether `iamu/config.json` already exists:
+
+- **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 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
+
+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. **Domain Narrative & Candidate Roles:**
+   - Read `README.md`, `CLAUDE.md`, docs, OpenAPI / JSON schemas, user models.
+   - 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. **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:
+> - 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
+
+---
+
+### 3. Step 1/3: Establish the Safety Fence (`iamu/testability.md`)
+
+Present the detected environment and safety fence. Explain clearly *why* this boundary is required before any autonomous agent runs:
 
+```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.
+
+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>
 ```
-iamu init [project-name]
+
+**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
+
+Press Enter to accept [1], select 2, or tell me what to adjust:
 ```
 
-The command scaffolds `iamu/config.json`, entity subdirs, `.runs/`, `.cache/`, `.gitignore`.
+**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>
+---
 
-- If `iamu/` was already present, existing files are not overwritten. Treat as success and continue.
-- Error containing "legacy `.iamu/` layout" → tell the user to remove the legacy directory, then re-run.
+# Project Testability & Environment
 
-On fresh scaffold, introduce iamu first:
+## Target & Run Instructions
+- Command: <dev command>
+- Base URL: <target_url>
 
-> **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.
+## Auth & Access Boundary
+- <How a walker becomes this persona in dev or test mode>
 
-On re-run (already scaffolded), skip the intro — the user knows what iamu is.
+## Reachable Surfaces
+- <List discovered routes/entry points>
 
-### 2. Understand the project
+## Mocks & Data Fixtures
+- <List existing MSW mock files, DB seed scripts, or fixture directories>
 
-Explore the codebase automatically — do NOT ask the user what files to read. Build a **project-context summary** (3–6 sentences) the downstream skills will use as grounding. Read the following files when present:
+## Untestable Boundaries (Do Not Walk)
+- <List un-mocked external dependencies and external submission portals>
+```
 
-- `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`
+---
 
-Extract these key dimensions:
+### 4. Step 2/3: Ground Domain Reality & Role Candidates (`iamu/context.yml`)
 
-1. **Domain** — what does this product do, in one phrase (mandatory).
-2. **Jurisdiction** — country / region (optional — only include if evident from codebase/locale/terms or if legal frameworks apply).
-3. **Regulations (`governed_by`)** — specific compliance frameworks (AFS 2023:2, GDPR, HIPAA, ISO 27001, etc.). **Strictly optional:** only extract if the repo explicitly references legal or compliance standards. Most software is not in a regulated domain; do NOT invent or guess regulations for standard SaaS/apps.
-4. **Primary Personas** — determine the 1–2 most important user archetypes that stress-test this product (e.g. End User / Consumer vs. Admin / Operator, or First-Timer vs. Power User). Propose:
-   - Name and Role
-   - Disposition / perspective (patience level, tech literacy, primary friction triggers)
+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.
 
-Also collect silently (write to `context.yml` but do NOT present for confirmation):
-- **Actors** — all identified roles and their responsibilities.
-- **Glossary** — domain-specific terms (helps persona language fidelity).
-- **Access** — if the project documents how to switch user or role in a dev or test environment (a persona switcher, seeded accounts, a storage key), record that mechanism as `access`. It is what lets a walkthrough run as the persona instead of as whoever happens to be signed in. Never record passwords or tokens — name where they live.
+Present the discovered domain reality and candidate roles:
 
-Do NOT collect architecture (agent reads the codebase directly — tech stack doesn't affect walkthroughs).
+```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.
 
-**If there is no code (greenfield, design phase):** ask the user: what does this project do, who are the users, what domain, and are there any specific regulations?
+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)*
 
-**Present a short proposal for confirmation:**
+<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] 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):
+
+```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:
 ```
-Your project: <domain> (<jurisdiction if known>)
-[Regulations: <reg1>, <reg2>]  <-- omit line entirely if none
 
-Proposed primary personas:
-  1. <Name> (<Role>) — <Key disposition & perspective>
-  2. <Name> (<Role>) — <Key disposition & perspective>
+**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>
+---
 
-Confirm context & scaffold these personas? (yes / edit / suggest-others / skip-personas)
+<The substantive 1–2 paragraph project description and core user journeys>
 ```
 
-Wait for the user to confirm or correct before writing. The user only needs to verify domain and choose whether to accept, edit, suggest alternative personas, or defer persona creation.
-
-### 3. Capture domain context and scaffold personas
-
-Persist the step-2 summary as structured fields so every scenario draft and walkthrough loads the same grounding. Downstream skills auto-read this file.
-
-1. Check existing state by reading `iamu/context.yml` directly.
-
-2. **Branch on what you find:**
-
-   - **Empty / not present** → synthesize structured fields from step 2 and write `iamu/context.yml` with your file-editing tool (not a shell heredoc — it avoids permission prompts).
-   - **Present but thin** (missing domain) → show what's missing and offer to fill it. User picks **refine** or **replace**.
-   - **Present and complete** (domain set) → show summary and ask "Use as-is, refine, or replace?" Default is **skip**.
-
-3. **Write `iamu/context.yml`**:
-
-   ```yaml
-   ---
-   schema_version: 1
-   domain: e-commerce storefront
-   # jurisdiction: EU / US          # optional
-   # governed_by:                    # strictly optional - omit if not regulated
-   #   - name: GDPR
-   #     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
-   glossary:
-     - term: SKU
-       definition: Stock Keeping Unit
-   access: >-
-     No login in dev. In the page, set localStorage "dev_persona" to the
-     persona's access value and reload.
-   ---
-   ```
-
-   Rules:
-   - `domain` — one line. Mandatory.
-   - `jurisdiction` — optional. Only if evident or relevant.
-   - `governed_by[]` — strictly optional. Order by authority (legislation > regulation > standard > company_policy > guideline > informational). Specific names, not categories. Omit entirely if no regulations apply.
-   - `actors[]` — all identified roles and their responsibilities.
-   - `glossary[]` — domain terms only. Thin is better than padded with generic terms.
-   - `access` — optional. Only what the docs actually say; leave it out rather than guess. `iamu-run` fills it in on the first walk if it is missing.
-   - Do NOT add `industry` or `architecture` — these don't affect walkthroughs.
+*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. **Scaffold confirmed personas (unless `skip-personas` selected):**
+---
 
-   Always use the CLI to scaffold valid persona entities with schema-compliant UUIDs, slugs, and timestamps:
-   ```bash
-   iamu new persona --name "<Name>" --role "<Role>" --disposition "<Disposition>" --json
-   ```
+### 5. Step 3/3: Co-Design Your First Test Journey (`personas/`, `outlines/`, `scenarios/`)
 
-   Then open the created file (`iamu/personas/<slug>.md`) and write 2–4 sentences of background narrative into the markdown body below the frontmatter, detailing their technical habits, patience level, and specific friction triggers.
+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).
 
-   If `iamu/context.yml` has an `access` mechanism, set the persona's `access` field in frontmatter to match an existing product account/role.
+Present the proposed test journey, including explicit **Auth Precondition Verification**:
 
-   Run `iamu validate --all`.
+```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.
 
-5. Confirm: "Context saved and personas seeded in iamu/personas/. Run `iamu-new` to draft your first scenario." (or "Context saved. Run `iamu-new` to draft your first scenario." if personas were skipped).
+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.>"
+```
 
-### 4. Offer cloud link (optional)
+**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
+
+Press Enter to accept [1], select 2, or tell me what to adjust:
+```
 
-Check the current state first:
+**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
+   ```
 
-```bash
-iamu auth status --json
-```
+---
 
-- **`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:
+### 6. Completion & First Walkthrough Handoff
 
-  > 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.
+Present the completion handoff cleanly.
 
-Three outcomes:
+**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)`.
 
-- **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.
+Render the output:
 
-**Linking:**
+```text
+✓ Scaffolding complete:
 
-1. Run `iamu auth login` (add `--url <api-url>` only if the user names a self-hosted cloud). It opens the sign-in page in the user's browser and waits up to two minutes — tell the user to approve it there. Allow the command at least 150 seconds before your shell tool times out. 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. Linking pushes every local persona, scenario and finding into the chosen project; a wrong guess leaks them into someone else's.
-3. On success the output ends with `Dashboard: <url>` and, when an agent host was detected, `iamu-sync MCP server registered`. Relay both in two lines: the dashboard link, and that restarting the agent session loads the team tools (work requests, teammate-change alerts).
+  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
 
-If login fails (cloud unreachable, sign-in timed out), report the error in one line and continue — setup is complete without the cloud.
+Next step:
+  Ensure your dev server is running on <target_url>, then trigger the walkthrough in your agent:
 
-All three outcomes leave a usable local setup. Cloud is strictly additive.
+    iamu-run <persona-slug>--<outline-slug>
 
-### 5. How to use iamu from here
+  Or run directly from your shell:
 
-Close with one line pointing at the next step:
+    $ 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)
 ```
-Setup complete. Next: run iamu-new to draft your first scenario.
-```
+
+### 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 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.
+
+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.

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

@@ -21,24 +21,28 @@ $ARGUMENTS
 
 Do NOT use `find`, `grep`, or `cat` to dump raw `.md` files in `iamu/`. The CLI outputs clean, validated data.
 
-### 2. Format entity responses as compact tables
+### 2. Format entity responses with an executive tally and clickable links
 
-When the user asks for personas, scenarios, or findings, respond with a scannable Markdown table. Never dump full psychological profiles, vocabulary lists, or raw frontmatter unless the user explicitly asks for deep detail on one entity.
+When the user asks for project status, lead with an executive tally banner, followed by scannable tables with clickable markdown file links:
+
+```
+Project Status: <P> Personas · <S> Scenarios (<R> Tested, <U> Untested) · <F> Open Findings · <C> Capabilities
+```
 
 **Personas:**
 | Slug | Name | Role | Status |
 |---|---|---|---|
-| `elin-dahl` | Elin Dahl | Architect & first-time house owner in Falun | active |
+| [`elin-dahl`](iamu/personas/elin-dahl.md) | Elin Dahl | Architect & first-time house owner in Falun | active |
 
 **Scenarios:**
 | Slug | Persona | Outline | Status / Target |
 |---|---|---|---|
-| `replacing-windows` | `elin-dahl` | `measure-and-order` | ready |
+| [`replacing-windows`](iamu/scenarios/replacing-windows.md) | [`elin-dahl`](iamu/personas/elin-dahl.md) | [`measure-and-order`](iamu/outlines/measure-and-order.md) | ready |
 
 **Findings:**
-| # | Severity | Type | Finding | Status |
+| # | Severity | Type | Finding | File |
 |---|---|---|---|---|
-| 1 | CRITICAL | hinders | Submit fails opaquely on empty field | open |
+| 1 | CRITICAL | hinders | Submit fails opaquely on empty field | [`view`](iamu/findings/<slug>.md) |
 
 ### 3. Ignore internal templates
 
@@ -52,13 +56,16 @@ For a project-status question, add one line on the cloud from `iamu status --jso
 - **Linked, no credentials** → `Cloud: linked, but this machine has no credentials — iamu auth login.`
 - **Local-only** → `Cloud: local-only.` Nothing more; no upgrade pitch.
 
-### 5. Provide clear next steps
+### 5. Provide copy-pasteable next actions
+
+Conclude with exact copy-pasteable commands:
 
-Conclude with one concise action prompt:
-- To run a scenario: `iamu-run <scenario-slug>`
-- To propose new personas or scenarios: `iamu-propose`
-- To draft a persona or scenario directly: `iamu-new`
-- To review open findings or team requests: `iamu-findings`
-- To inspect reports: `iamu report`, or `iamu open` for the cloud dashboard (linked projects)
-- To share unpushed work with the team: `iamu sync` (linked projects)
+```
+Next actions:
+  iamu-run <scenario-slug>              # Run a walkthrough for this scenario
+  iamu-propose                          # Propose missing personas or scenarios
+  iamu-new                              # Draft a new scenario or persona
+  iamu-findings                         # Triage open findings
+  iamu open                             # Open project in cloud dashboard
+```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iamu-dev/iamu",
-  "version": "0.2.0-beta.1",
+  "version": "0.2.0-beta.11",
   "type": "module",
   "description": "Test your product as realistic personas — scenario-driven development CLI",
   "license": "UNLICENSED",
@@ -54,19 +54,22 @@
   "devDependencies": {
     "@types/node": "^22.0.0",
     "@vitest/coverage-v8": "^4.1.11",
+    "google-auth-library": "^11.1.0",
     "tsup": "^8.5.1",
     "typescript": "^5.8.0",
     "vitest": "^4.1.11",
-    "@iamu-dev/protocol": "0.1.0",
     "@iamu-dev/local-store": "0.1.0",
-    "@iamu/tsconfig": "0.1.0"
+    "@iamu/tsconfig": "0.1.0",
+    "@iamu-dev/protocol": "0.1.0"
   },
   "scripts": {
-    "build": "tsup && tsc -b tsconfig.build.json --emitDeclarationOnly && node scripts/copy-assets.mjs",
+    "build": "tsup && tsc -b --force tsconfig.build.json --emitDeclarationOnly && node scripts/copy-assets.mjs",
     "clean": "node -e \"fs.rmSync('dist', { recursive: true, force: true }); fs.rmSync('tsconfig.tsbuildinfo', { force: true }); fs.rmSync('tsconfig.build.tsbuildinfo', { force: true })\"",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
+    "eval:walkthroughs": "vitest run --config vitest.benchmark.config.ts",
+    "eval:gemini": "node dist/eval/gemini-eval-cli.js",
     "pack:dry-run": "npm pack --dry-run"
   }
 }