@iamu-dev/iamu 0.0.0-stage → 0.2.0-beta.1

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

@@ -0,0 +1,400 @@
+---
+name: iamu-run
+description: Execute a scenario walkthrough. Accepts scenario slug / UUID / free-form intent / no-arg. Intent chains into iamu-new first, then runs.
+generatedBy: __IAMU_VERSION__
+---
+
+Run a scenario against a running product. The walkthrough executes in your agent session using a driving surface you control — a browser MCP for a web product, or the iOS Simulator for a native app — no separate Iamu runner involved for local flows.
+
+This skill resolves what you want to run from your argument:
+
+- Scenario slug or UUID → load + execute.
+- Free-form intent ("checkout abandonment", "returning customer friction") → fuzzy-match against existing scenarios; if nothing fits, chain into `iamu-new` to draft first, then execute.
+- No argument → pickable list of scenarios: scenarios that need a re-run first, then drafts and ready-to-run.
+
+$ARGUMENTS
+
+## Prerequisites
+
+Before starting, check that `iamu/context.yml` exists and has `domain` filled in. If it is missing or empty, run the `iamu-setup` skill first — context grounds every walkthrough. If `iamu/` does not exist at all, run `iamu init` first.
+
+## Steps
+
+### 0. Verify a driving surface
+
+A walkthrough needs something that drives the product the way a person does. Two surfaces are supported — pick the one the product actually IS, not the one that is easiest to reach.
+
+Look at the tools actually available in this session and match on what they can do, not on what they are called — tool names differ per host, plugin, and install method, so any name written here would be wrong somewhere.
+
+**Web product** — you need a browser-driving tool set that can: open a URL, click and type into elements, read the page structure (accessibility snapshot or DOM), and save a screenshot to a file path on disk.
+
+When more than one qualifies, prefer in this order:
+
+1. **One attached to the user's own running Chrome** (a Chrome DevTools-style MCP or a Chrome extension bridge). The user can watch the walk live, the session and dev state they already have is present, and console and network output are available to tell a tooling glitch from a product bug.
+2. **One that launches its own browser** (a Playwright-style MCP). Works, but starts from a blank profile and the user cannot see it happen.
+3. **`iamu browse`** — the CLI's own shell-driven browser, when no tool above can save a screenshot to a file (many hosts' browser tools return screenshots to the model only, and every step then records `screenshot: null`). It drives the installed Chrome in a visible window: `iamu browse start --run <run-id>` after each `start-run` (step 4), then `goto`, `snapshot` (ARIA roles and names), `click <role> "<name>"`, `click-text`, `fill <role> "<name>" "<text>" [--submit]`, `press`, `scroll`, `back`, each with `--shot <png>`; `iamu browse stop` when done. Start it yourself before dispatching the walker, never leave that to the walker; `iamu instructions walk --surface browse` (the default) writes the command list into the walker prompt.
+
+Tell the user in one line which one you picked and why. If the project's own agent docs name a preferred browser tool or constrain where screenshots may be written, that wins over the order above.
+
+**Native iOS / iPadOS app** — you need a simulator control tool that can tap, type, and launch an app on a named device.
+
+A native app has no URL, and a browser tool is not a substitute for one. If the product is native, the target is a device plus a build (step 3).
+
+If no surface is available, stop and tell the user:
+
+> A walkthrough needs a driving surface. For a web product, `iamu browse` works wherever Chrome or Chromium is installed (or set `IAMU_BROWSER`); a browser-driving MCP that attaches to Chrome also works — restart your agent session after installing one and re-run `iamu-run`. For a native iOS app, a simulator control tool must be available in this session.
+
+Do NOT proceed to step 1 before a driving surface is confirmed.
+
+**Unfinished runs.** Run `iamu status --json` and look at `runs.incomplete`. A run listed there was started but never reached `iamu complete` — the walker died or the session ended — so its steps and findings exist but it has no report, no verdicts, and no delta. If there are any, tell the user how many and offer, once:
+
+- **Finish** one that has step files: run the post-walk pipeline (step 4, A→B→C→D) on it as it stands. A partial walk with a report is worth more than a complete one nobody assembled.
+- **Discard** ones with no steps: delete the run directory. Runs are ephemeral; findings already written to `iamu/findings/` are kept.
+- **Leave them** and carry on.
+
+Do not block the new run on this, and do not ask again in the same session.
+
+**Cloud state.** Run `iamu auth status --json` once. It sets the mode for the rest of this skill:
+
+- **Linked** (`cloud_linked` and `authenticated` both true) → pull teammates' changes before resolving the scenario: `iamu pull --json`. Pull only adds new entities and fast-forwards files that are unedited here; it never overwrites a local edit (those come back as `diverged` — mention them, never `--force`). This is how a teammate's new scenario, or a dismissal that taught the walker what not to report, reaches this run. If pull fails (offline, cloud down), say so in one line and walk locally.
+- **Linked, no credentials** (`cloud_linked` true, `authenticated` false) → say once: "This project is cloud-linked, but this machine has no credentials — the run stays local until `iamu auth login`." Continue.
+- **Local-only** → nothing to do here.
+
+### 1. Resolve the argument
+
+Four paths based on `$ARGUMENTS`:
+
+**UUID or exact slug match** → Read scenario files from `iamu/scenarios/` directory, or run `iamu list scenarios --json`, and match. Load and skip to step 3.
+
+**Slug-like arg with no exact match** → Run fuzzy match against existing scenario slugs (simple substring / levenshtein — the agent should judge similarity). If the best match is obviously close (shared two or more tokens), confirm with the user: "Did you mean `<slug>`?" Accept / correct / treat as free-form intent.
+
+**Free-form intent string** (quoted or multi-word, no match) → Chain into `iamu-new` with the intent as seed. After `iamu-new` completes and returns a scenario slug, continue here with that slug.
+
+**No arg** → Run `iamu status --json` and `iamu list scenarios --json` (or read `iamu/scenarios/`). `rerun` in the status output lists scenarios holding fixes that no later run has proven yet — a fix counts only once a re-run of its scenario shows it working. Present that group first, most awaiting fixes first, with its `reason`; then drafts and ready-to-run (a scenario in the first group is not repeated below):
+
+```
+Needs a re-run (fixes awaiting proof):
+  1. maria-gomez--busy-shift — 2 fixes applied after the last run
+
+Drafts (need persona):
+  2. busy-shift-draft — Busy shift situation (no persona)
+  3. checkout-abandon-draft — Abandoned cart situation (no persona)
+
+Ready to run:
+  4. dev-patel--checkout-abandon — Abandoned cart x Dev Patel
+```
+
+Omit the first group when `rerun` is empty. User picks a number or slug. Drafts get a bind prompt before execution (step 2); ready-to-run scenarios skip to step 3.
+
+If `requests.open` in the status output is above zero, put one line above the list: `Team requests: <N> waiting — iamu-findings picks them up.` Teammates queued those in Iamu Cloud; a verify or run request names the scenario to walk.
+
+### 2. Bind persona (draft path only)
+
+If the resolved scenario has `persona: null`, prompt to bind before executing:
+
+"This scenario is a draft — no persona bound. Pick one, or draft a new persona."
+
+1. Read `iamu/personas/` directory or run `iamu list personas`; present as pickable list + "new" option.
+2. Picked existing → bind that persona by updating the scenario file's `persona` field.
+3. Picked "new" → generate 3 persona candidates grounded in the situation narrative and project context → user picks one + refines → write persona file to `iamu/personas/<slug>.md` → bind.
+4. After binding the persona, generate a 3--5 sentence first-person brief and write it as the scenario file's markdown body:
+
+   ```yaml
+   ---
+   id: <uuid>
+   slug: maria-gomez--busy-shift-handoff
+   outline: busy-shift-handoff
+   persona: maria-gomez
+   ---
+   I've got five open incidents and my relief is already here...
+   ```
+
+After bind + brief, the scenario is ready to execute. Continue to step 3.
+
+### 3. Target
+
+**Web** — ask for the target URL (live product, staging, or localhost). If the scenario has a default `target_url` in its frontmatter, offer that with a confirm.
+
+Where the walk *starts* is part of the situation, not of the environment: a persona arriving from a video, an email or a search result lands on a specific page, not the home page. If the scenario has `entry_path`, `iamu start-run` resolves it against the target — pass the product's base URL as `--target`. If it has none but the situation clearly begins on a particular page, set `entry_path` in the scenario frontmatter first (a path like `/en/episodes/1`, never a full URL), so this run and every later one start there. A walk started on the wrong page reports the detour as a finding.
+
+**Native iOS** — the target is a device plus a build. Establish three things:
+
+- **Which simulator.** Use a DEDICATED device, never the one the project builds to. An `xcrun simctl install` from any other session terminates the app and relaunches it WITHOUT its launch arguments — so a seeded state silently becomes first-run onboarding, mid-scenario. The walker records that as a product defect, and she is right to: nothing visible to her distinguishes it from the product breaking.
+- **Which build.** An installed bundle id, or a freshly built `.app` to install first. Never walk a build that is still being edited — findings from a half-finished screen cannot be attributed to any commit.
+- **Launch arguments**, if the scenario needs a particular state or entry point.
+
+Record it as a target string the run can carry, for example `sim://<device-name>/<bundle-id>`.
+
+**Then verify the starting state before spawning anyone.** Launch the app and take ONE screenshot confirming the product is where the scenario assumes it starts. Wait a few seconds after launch first: a screen rendered before its state lands shows the wrong thing, and verifying too early makes the verification itself lie — in the direction of "the harness is broken", which costs a debugging detour or, worse, waves a real seeding bug through.
+
+**Web: check the product is ready, not just up.** A server that answers is not a product that has its data. Before spawning the walker, confirm the thing the scenario depends on actually exists — the list the persona will open is populated, the seeded records are there, background setup (seeding, migrations, indexing) has finished. Use the project's documented readiness signal if it has one; otherwise look at one screen or one API response yourself. A walk started too early reports "the feature is missing" as a critical finding, and nothing in the walker's view distinguishes that from a real defect.
+
+**Access — how the walker becomes this persona.** A walk as a forklift driver that runs with an administrator's session reports nothing true about what the driver can see or reach. Access is recorded in two places, and `iamu instructions walk` (step 4) returns both as `access`:
+
+- `access.project` — from `iamu/context.yml` `access`: HOW switching user is done in this product (a dev persona switcher, a storage key, seeded test accounts, a login form). Written once per project.
+- `access.persona` — from the persona file's `access`: WHICH user this persona is (an account name, a role, a switcher key).
+
+If both are present, use them as they are. If either is missing, fill the gap now and SAVE it so no later run has to ask:
+
+1. Check the project's own agent docs (`CLAUDE.md`, `AGENTS.md`, anything they point to for the dev environment) for a documented way to switch user or role.
+2. Map the persona to the closest account or role the product actually has. If nothing fits, say so — a persona the product cannot represent is itself worth telling the user.
+3. If the docs are silent, ask the user once. "No login, everyone is the same user" is a valid answer.
+4. Write what you learned: the mechanism into `iamu/context.yml` as `access:`, the persona's own key into `iamu/personas/<slug>.md` frontmatter as `access:`. Passwords and tokens never go in either — name where they live (an env var, a vault entry) instead.
+
+Carry the result into the walking prompt as the `## Access` section: the exact steps to become the persona, with the instruction to do them BEFORE the first recorded step.
+
+### 4. Execute the walkthrough
+
+**Set up the run directory.** Use the CLI to scaffold a valid run:
+
+```bash
+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" }
+```
+
+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.
+
+**Size the browser for this persona** (`iamu browse` only), every run — also when a browser is already open from an earlier run:
+
+```bash
+iamu browse start --run <run-id>
+```
+
+It sizes the page as the device the persona's tags name (`mobile`/`phone`, `tablet`/`ipad`, `desktop`/`laptop`; `start-run` prints it as `device`) and resizes a browser left at another persona's size.
+
+**Get the walker prompt.** The CLI composes the whole thing — persona, situation, brief, access, driving surface, methodology, dismissed findings and the run-directory contract (steps, screenshots, findings, `summary.json`):
+
+```bash
+iamu instructions walk --scenario <scenario-slug> --run <run-id> --surface browse --json
+```
+
+`--surface browse` (the default) describes `iamu browse`; start it first (`iamu browse start --run <run-id>`, above). Using your own browser tool instead, pass one sentence naming it and how it saves screenshots, e.g. `--surface "Chrome DevTools MCP attached to the user's Chrome; take_screenshot with filePath"`. For a native app, describe the simulator tool and add the native notes below.
+
+The result's `walker_prompt` is the walker's entire prompt. Pass it verbatim — do not rewrite, summarize or trim it. The prompt already carries the dismissed findings, the active tester guidance rules (`iamu/guidance/`) for this scenario, and — when fixes await a re-run — the places they were seen (places only, never what was wrong; the list is in `revisit`). The rest of the bundle (`persona`, `outline`, `access`, `dismissed_findings`, `tester_guidance`, …) is there for you, not the walker. If `access` is missing a half, fill it in first (step 3) and re-run this command.
+
+**Preflight: Unattended execution check.** A walkthrough executes 15–30 terminal commands sequentially (`iamu browse step`, `iamu new-finding`). If your agent host requires manual confirmation for terminal/shell commands (standard interactive mode in Claude Code, Cursor, Antigravity, Cline, Windsurf, etc.), the walker subagent will stall waiting for approval on every step. Before dispatching, verify that command auto-approval / unattended execution is enabled in your environment, or warn the user once:
+> "Autonomous walkthroughs require auto-approving terminal commands so the walker can drive the product unattended. If command approvals are prompted, please enable auto-approval or expect to approve steps manually."
+
+**CRITICAL: Dispatch the walker as an isolated subagent.** Spawn a fresh subagent using your host editor's subagent mechanism (e.g. `Agent(...)` in Claude Code, `invoke_subagent` in Antigravity, or host-native subagent launcher). The subagent gets ONLY the walking prompt (`walker_prompt`) — no prior conversation history.
+
+A fresh subagent is NOT blind by default. On most hosts it still loads the project's agent instructions and can read files in the repo, so it may know the domain model, the route table, and why a screen was built the way it was — none of which the persona knows. The methodology's "Stay outside the product" rule is what keeps it honest; it is part of `walker_prompt` — never remove or soften it. If the host lets you restrict a subagent's tools, give the walker only the driving surface, file write/edit, and a shell for `iamu` commands.
+
+```
+# In Claude Code:
+Agent({ description: "Walk <scenario-slug> as <persona.name>", prompt: "<walker_prompt, verbatim>" })
+
+# In Antigravity / generic subagent hosts:
+invoke_subagent(Role="Persona Walker", Prompt="<walker_prompt, verbatim>")
+```
+
+The subagent inherits the driving-surface tools and drives the product independently. It does not see this conversation.
+
+**For a native walkthrough, append these to `walker_prompt`** (the one addition allowed), or the run produces instrument artefacts instead of findings:
+
+- **She is deaf.** The simulator returns no audio. She may report "I tapped the speaker and nothing visibly confirmed it played" — never anything about what the audio said.
+- **Taps miss.** She taps a coordinate read from a screenshot taken BEFORE the action; mid-animation it lands nowhere. One no-change is never a finding — retry once at the same target, and only a second no-change becomes one.
+- **Screenshot every 3-4 taps at most.** Batching more desyncs the moment an answer opens a screen she did not expect.
+- **Coordinates are device points, origin top-left.** A scaled screenshot must be mapped back to that space before tapping.
+
+**If subagent dispatch is not supported by your host editor** (e.g. standard Cursor without subagent tools), fall back to walking in the same context — but strictly adhere to the persona behavioral constraints in `walker_prompt`.
+
+After the walker returns, continue to the post-walk pipeline below.
+
+**Recording steps:**
+
+Use atomic CLI commands to drive and record in one step — do NOT manually author JSON files:
+
+- **When using `iamu browse` (web):**
+  ```bash
+  iamu browse step --run <run-id> --action "Opened dashboard" --note "First thing I see is the overview panel" goto https://app.example.com/dashboard
+  iamu browse step --run <run-id> --action "Click checkout" --note "Button was hard to find" click button "Checkout"
+  ```
+  This executes the browser action, waits for the DOM, takes the screenshot into `screenshots/step-N.png`, captures the URL, and writes `steps/NNN.json` atomically.
+
+- **When using an external surface (iOS Simulator / custom MCP):**
+  ```bash
+  iamu step --run <run-id> --action "Tapped proceed" --note "Next screen loaded" --shot <screenshot-path>
+  ```
+
+Step files live at `iamu/.runs/<run-id>/steps/<NNN>.json`. The CLI manages monotonic step numbers, timestamps, and screenshots. Never write raw JSON files with glue code.
+
+**Recording findings:**
+
+Use the CLI to create findings with valid frontmatter, UUID, and slug:
+
+```bash
+iamu new-finding --scenario <slug> --run <run-id> --title "Short title" --type hinders --severity major --ui-fact "What the UI showed" --consequence "Impact on persona" --task-impact impairs --confidence high --json
+```
+
+This generates a valid UUID, derives the slug from the title, and writes a frontmatter-valid file to `iamu/findings/<slug>.md`. Returns `{ "slug": "...", "path": "...", "id": "..." }`.
+
+After the CLI scaffolds the file, edit the file to add the finding body (description + recommendation) below the frontmatter.
+
+Valid `--type` values: `helps`, `hinders`, `missing`, `irrelevant`, `incorrect`.
+Valid `--severity` values: `critical`, `major`, `minor`, `observation`.
+Valid `--task-impact` values (effect on the persona's task): `blocks`, `impairs`, `slows`, `neutral`, `accelerates`, `enables`. A `helps` finding is never `blocks`/`impairs`/`slows`; a problem is never `accelerates`/`enables`.
+Valid `--confidence` values: `high`, `medium`, `low` (use `low` when it may be a tooling limitation).
+
+Findings never name a human test: the walker does not see them. The judge links findings to the human tests they bear on (`evaluate-record` writes `human_test_id`).
+
+**DEPTH GATE:** Both `--ui-fact` and `--consequence` should be provided. If you cannot articulate both, record as a step note instead — do not create a finding file.
+
+**Post-walk pipeline (MANDATORY — do NOT skip any step):**
+
+After the walker returns, you MUST complete ALL of the following before presenting findings to the user. Do NOT present findings early. Do NOT ask the user anything. Execute steps A→B→C→D→E in order.
+
+**A. Assemble canonical + report.** Use the CLI:
+
+```bash
+iamu complete <run-id> --no-prompt
+```
+
+This reads all steps, findings, and entity files, assembles `canonical.json`, generates `report.md`, computes the delta against prior runs, and flips the manifest to completed. All in one command.
+
+To get the canonical data for presentation, run with `--json`:
+```bash
+iamu complete <run-id> --no-prompt --json
+```
+
+**B. Match findings to earlier runs.** A fresh walker never words a recurring problem the same way twice, so `complete` alone reports recurrences as new and earlier findings as "not seen". Get the matcher bundle:
+
+```bash
+iamu match <run-id> --json
+```
+
+If `needed` is `false` (no earlier findings for this scenario, or none this run), skip to C. Otherwise dispatch a matcher subagent with `match_prompt` as its only context — NOT the walker, which must never see earlier findings. Write its JSON answer to a file and record it:
+
+```bash
+iamu match-record <run-id> --file <matches.json>
+```
+
+This links recurrences to their earlier canonical finding, marks earlier findings the run's steps show fixed (only with cited steps), and re-derives the delta and report. If the matcher's output is rejected, show the error to the matcher once and retry; if it fails again, continue without it — the exact-text delta from A stands.
+
+**C. Evaluate human tests.** Use the CLI to get the evaluation prompt:
+
+```bash
+iamu evaluate <run-id> --json
+```
+
+This returns the judge prompt input bundle. Dispatch the evaluator as a subagent with that prompt. After the evaluator returns verdicts, record them:
+
+```bash
+iamu evaluate-record <run-id> --file <verdicts.json> --no-prompt
+```
+
+This also links the findings each verdict cites to that human test (`human_test_id` on the finding file, only where none is set), so `iamu sync` carries the link to the cloud.
+
+**D. Read the completed canonical.** Read `iamu/.runs/<run-id>/canonical.json` for the final data including verification delta (if a prior run exists). Use this for step 5 presentation.
+
+**E. Publish (linked mode only).** `complete` and `evaluate-record` already pushed the run itself — report, steps, screenshots, verdicts. What they do not push are the finding files the matcher and judge updated (recurrence links, `human_test_id`); those go with sync:
+
+```bash
+iamu sync --json
+```
+
+Then get the run's link:
+
+```bash
+iamu open <run-id> --print
+```
+
+It prints the URL only if the run is on the cloud; otherwise it exits 1 and says why. Keep the URL — or the reason — for step 5. From the sync result, keep `conflicts` (a teammate changed the same finding) and `pending_deletes` for step 5 too. Never run `iamu sync --keep-mine` or `--confirm-deletes` yourself: both overwrite or delete team data, and only the user decides that.
+
+In linked-no-credentials or local-only mode, skip E.
+
+Only after A→E are complete, proceed to step 5.
+
+### 4a. Walk methodology summary
+
+The `walker_prompt` from `iamu instructions walk` is the source of truth and contains full walking methodology for the subagent.
+
+- **Depth gate**: Ensure findings articulate both the specific UI fact and the consequence for this persona.
+- **Dedup**: Skip findings in the dismissed list or already logged in the current run.
+- **Graceful degradation**: On judge evaluation failure, set verdicts to pending/null and proceed with report presentation.
+
+### 5. Present assessment — stay in the conversation
+
+Render results **inline** so the user can act without leaving the conversation. Lead with the overall assessment, not a findings dump.
+
+1. **Overall assessment** — answer the research question from the outline's human test. Read the outline's `human_tests[0].question` (the focus question the user defined when creating the scenario). Frame the verdict around it:
+
+   > **Could the admin complete bulk-import without consulting documentation?** No. The import flow requires knowledge of the role hierarchy that isn't documented in-app. 3 issues found, 1 critical.
+
+   If the evaluation subagent ran, use its verdict. If it failed or wasn't run, synthesize from findings: count hinders/missing by severity, state whether the persona could complete their task.
+
+   **This is the most important part of the output.** The user defined this question as their focus — answer it directly.
+
+2. **Progress since last run** (only when canonical.json contains a `verification` section). Present the delta:
+
+   ```
+   Since this scenario's last run:
+     ✓ 1 fixed, re-checked (handoff note saves — step 6)
+     ✗ 1 persists (timeout warning)
+     ○ 2 not seen this run (handoff list filtering, submit confirmation)
+     + 1 new since that run (date picker locale)
+   ```
+
+   `resolved` means the matcher saw this run's steps do the thing the finding said failed — say which step. `not_observed` means only that this walk did not record the finding again. Never present it as fixed: the walker may have stopped before that screen or taken another route. Say which ones were not seen and, if the walk plainly never reached the screen they live on, say that too. `iamu complete` reports whether the walk reached the places where fixes await a re-run (`Re-check places: reached N of M`, `revisit_coverage` in `--json`); name the ones not reached — their fixes stay awaiting.
+
+   If no prior run exists, skip this.
+
+3. **Findings** — severity-first (CRITICAL → MAJOR → MINOR), grouped by type (hinders and missing first — the actionable ones — then helps at the bottom):
+
+   **Hinders / Missing** (act on these):
+
+   | # | Severity | Type | Finding | Recommendation |
+   |---|----------|------|---------|----------------|
+   | 1 | CRITICAL | hinders | Submit fails opaquely when required field empty | Show validation inline before submit |
+   | 2 | MAJOR | hinders | Date picker has no "today" shortcut | Add quick-select for common dates |
+   | 3 | MINOR | missing | Help text uses jargon ("slutdatum") | Use plain language ("end date") |
+
+   **Helps** (preserve these):
+
+   | # | Type | Finding |
+   |---|------|---------|
+   | 4 | helps | Search auto-suggests from recent entries |
+
+4. **What worked** — supportive moments worth preserving (brief, from `what_worked` in the canonical JSON).
+
+5. **Next-scenario suggestion** — read `iamu/scenarios/` to check coverage, then suggest one of:
+   - Same scenario with a different persona (if other personas exist for this situation)
+   - Adjacent untested scenario in the same capability
+   - Nothing (if coverage is good)
+
+6. **Cloud** — one line, by mode:
+   - **Linked, run on the cloud** → `Shareable report: <url>` (screenshots and step replay for anyone on the team).
+   - **Linked, run not on the cloud** → the reason from step E and its remedy, e.g. `Cloud: queued — retries on the next iamu sync` or `Cloud: not pushed — <reason>`.
+   - **Linked, no credentials** → `Cloud: not pushed — this machine has no credentials; iamu auth login restores them.`
+   - **Sync conflicts or pending deletions** (step E) → one line each: name the findings a teammate changed and give the CLI's resolution (`iamu pull --force` to take theirs after copying your edits aside, or `iamu sync --keep-mine` to keep yours — the user runs that one); for deletions, tell the user to review them and run `iamu sync --confirm-deletes` themselves.
+   - **Local-only** → nothing, with one exception: on the project's first completed run (`iamu status --json` → `runs.count` is 1), add `Want a link to share this report? iamu auth login connects the project to Iamu Cloud — optional, everything keeps working locally.` Never repeat it on later runs unless the user asks how to share a report.
+
+7. **End with a verb**: "Which ones should I fix? (You can also dismiss any finding — it won't show up in future runs.)"
+
+**Stay conversational.** The user says "fix 1 and 2" → you read the finding details from the canonical JSON (already in your context from the canonical assembly), look at the relevant code, and make the fix. Mark findings addressed by editing their frontmatter (`triage_status: addressed`, `triage_note: "..."`) as you go.
+
+If the user says "skip 3" or "not relevant" or "dismiss" for a finding, set `triage_status: dismissed` with a `triage_note` explaining why. **Tell the user:** "Dismissed — this won't be reported in any future walkthrough."
+
+**Linked mode: publish triage decisions.** When the user is done fixing and dismissing, run `iamu sync --json` once so teammates see the decisions (and any team request for these findings closes). Report it in one line (`Synced 3 findings to Iamu Cloud.`), with conflicts handled as in item 6. Do not sync after every single edit.
+
+**Do NOT** dump the user at file paths. The report and finding files exist for later reference, but the conversation is the triage surface. Mention artifacts only if the user asks for them or wants to share the report externally. The cloud link is the exception: in linked mode it IS the shareable report, so it always goes in the presentation.
+
+Run `iamu validate --all` to verify all entities before reporting done. If older finding files fail on schema drift (legacy status words, a finding type stored in `severity`, home-made ids), `iamu validate --all --fix` repairs what is mechanical — preview with `--dry-run`. Whatever it leaves invalid is missing information only a person has; report those, do not fill them in.
+
+## Guidelines
+
+- **Drafts bind in-line, not as a detour.** If the user picks a draft, the persona-bind step should feel like part of running — not a separate invocation.
+- **All generation is local.** All generation — persona suggestions, brief — uses the local LLM directly. No server-side LLM calls.
+- **Scenario vocabulary.** Say "scenario" — never "outline" — when addressing the user.
+- **Adopt, do not audit.** The walkthrough's value is seeing the product through the persona's eyes. Do not narrate as an observer — live it.
+- **The driving surface drives.** Every tool call that navigates the product goes through the driving surface picked in step 0. The `iamu` CLI records observations; it never drives.
+- **Close cleanly but stay present.** Canonical assembly ships the report + findings. Present findings inline and offer to fix — do not eject the user to files or another command. The conversation is the triage surface.
+- **Validate before done.** Always run `iamu validate --all` after a walkthrough to catch any issues.
+- **Use CLI for scaffolding.** `iamu start-run` for runs, `iamu new-finding` for findings, `iamu complete` for assembly. Never manually create run directories or generate UUIDs.
+- **Step files:** Record steps via the CLI (`iamu browse step` or `iamu step`), which manages step numbering, screenshots, and atomic writes to `steps/001.json`.
+- **Finding bodies:** After `iamu new-finding` scaffolds the file, edit the file to add the description and recommendation below the frontmatter.

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

@@ -0,0 +1,192 @@
+---
+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.
+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`.
+
+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.
+
+$ARGUMENTS
+
+## Steps
+
+### 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.
+
+```
+iamu init [project-name]
+```
+
+The command scaffolds `iamu/config.json`, entity subdirs, `.runs/`, `.cache/`, `.gitignore`.
+
+- 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.
+
+On fresh scaffold, 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.
+
+On re-run (already scaffolded), skip the intro — the user knows what iamu is.
+
+### 2. Understand the project
+
+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:
+
+- `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:
+
+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)
+
+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.
+
+Do NOT collect architecture (agent reads the codebase directly — tech stack doesn't affect walkthroughs).
+
+**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?
+
+**Present a short proposal for confirmation:**
+
+```
+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>
+
+Confirm context & scaffold these personas? (yes / edit / suggest-others / skip-personas)
+```
+
+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.
+
+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
+   ```
+
+   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.
+
+   If `iamu/context.yml` has an `access` mechanism, set the persona's `access` field in frontmatter to match an existing product account/role.
+
+   Run `iamu validate --all`.
+
+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).
+
+### 4. Offer cloud link (optional)
+
+Check the current state first:
+
+```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:
+
+  > 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.
+
+Three outcomes:
+
+- **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.
+
+**Linking:**
+
+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).
+
+If login fails (cloud unreachable, sign-in timed out), report the error in one line and continue — setup is complete without the cloud.
+
+All three outcomes leave a usable local setup. Cloud is strictly additive.
+
+### 5. How to use iamu from here
+
+Close with one line pointing at the next step:
+
+```
+Setup complete. Next: run iamu-new to draft your first scenario.
+```
+
+## 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`.
+- **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.