@iamu-dev/iamu 0.2.0-beta.17 → 0.2.0-beta.19

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

@@ -8,8 +8,8 @@ You are a brainstorming partner, not a form filler. Your job is to help the user
 
 **You bring:**
 - Understanding of the domain from `iamu/context.yml` (actors, jurisdiction, regulations if applicable)
-- Knowledge of the codebase from prior exploration (what features exist, what flows are built)
-- Awareness of the gap between "what the product supports" and "what real users actually need to do"
+- What the product is for, from `iamu/context.yml` and `iamu/capabilities/` (titles and descriptions)
+- Awareness of what real users actually need to do, whether or not the product supports it today
 
 **The user brings:**
 - Knowledge of which area they want to test (or nothing — you propose)
@@ -17,6 +17,8 @@ You are a brainstorming partner, not a form filler. Your job is to help the user
 
 Scenarios are written in **problem-space only** — they describe human situations, not UI flows. No screen references, no button names, no feature names. The scenario says "a shift leader needs to hand off open incidents under time pressure" — the walkthrough discovers whether the product supports that.
 
+**Drafting is not staging.** Do not read the product's source code, routes, `iamu/testability.md` or `iamu explore` output while drafting, and do not decide entry pages, starting data, accounts or mocks. Knowing what the product already does pulls a draft toward what was built and away from what the person needs. Getting the product into the state a situation needs happens when the scenario first runs: `iamu-run` stages it (start page, expected data, approximation guidance, which account the persona uses) before the walk.
+
 **Methodology prompts:** Before drafting, read the methodology files. These contain the quality standards for each artifact:
 - `iamu/.prompts/persona.md` — how to write a durable persona
 - `iamu/.prompts/outline.md` — how to write a situation outline
@@ -45,35 +47,32 @@ Determine the mode based on `$ARGUMENTS` and user intent:
      iamu new persona --name "<Name>" --role "<Role>" --disposition "<Disposition>" --json
      ```
   5. Write the persona's background narrative and test expectations as the markdown body.
-  6. If `iamu/context.yml` has an `access` mechanism, set the persona's `access` field to match an existing product account/role.
-  7. Run `iamu validate --all`.
-  8. Summarize: persona created in `iamu/personas/<slug>.md`. Prompt user: "You can now pair `<slug>` with a scenario draft via `iamu-new`, or propose situations for them via `iamu-propose`." Stop here for standalone persona requests.
+  6. Run `iamu validate --all`.
+  7. Summarize: persona created in `iamu/personas/<slug>.md`. Prompt user: "You can now pair `<slug>` with a scenario draft via `iamu-new`, or propose situations for them via `iamu-propose`." Stop here for standalone persona requests.
 
 - **Fast-Path Scenario mode** (when intent, topic, or a handoff candidate from `iamu-propose` is provided, e.g. `iamu-new "checkout friction"`, `iamu-new "Maria Gomez shift handoff"`):
   Do NOT drag the user through multiple question modals. Skip Step 2 entirely!
-  Jump directly to Step 3 and present the **Complete Scenario Spec-Sheet** (Situation + Bound Persona + Preconditions + Evaluation Checkpoint + Walker Brief) for **1-click / 1-key acceptance**.
+  Jump directly to Step 3 and present the **Complete Scenario Spec-Sheet** (Situation + Bound Persona + Evaluation Checkpoint + Walker Brief) for **1-click / 1-key acceptance**.
 
 - **Exploratory Scenario mode** (no arguments or broad exploration):
   Proceed through Step 2 (Propose complete scenario bundles) and Step 3.
   Inspect `iamu/personas/` (`iamu list personas`) first. If personas already exist in the casting panel (e.g. seeded during `iamu-setup`), deliberately frame scenario proposals around those existing cast members to build longitudinal test history, rather than inventing new personas.
-  If the user gives a direction, ground it in the codebase: what capabilities exist in this area? What flows are built? This helps you propose scenarios that test what's actually there, not what's imagined.
+  If the user gives a direction, ground it in the domain: who in `context.yml` deals with this, how often, under what pressure, and what goes wrong for them? Propose what those people need to get done, not what the product happens to offer.
 
 ### 2. Propose Complete Scenario Bundles (Exploratory Mode)
 
-Present 2–3 scannable scenario proposals. Each proposal MUST bundle the situation narrative, bound persona (prioritizing existing cast members), human evaluation checkpoint, and entry surface:
+Present 2–3 scannable scenario proposals. Each proposal MUST bundle the situation narrative, bound persona (prioritizing existing cast members), and human evaluation checkpoint:
 
 ```
 1. <Title> (<Primary Capability>)
    • Persona: <Persona Name> (<Role>) — Reused from cast / New candidate
    • Tension: <1 concise sentence on the human or organizational tension>
    • Evaluation Checkpoint: "<Concrete binary yes/partial/no question>"
-   • Entry Surface: `<entry_path>` (Target: `<target_url>`)
 
 2. <Alternative Title> (<Capability>)
    • Persona: <Alternative Persona Name> (<Role>)
    • Tension: <1 concise sentence>
    • Evaluation Checkpoint: "<Concrete binary question>"
-   • Entry Surface: `<entry_path>`
 ```
 
 **Interactive Decision:**
@@ -83,14 +82,14 @@ Present 2–3 scannable scenario proposals. Each proposal MUST bundle the situat
     1. "[Recommended] Scaffold '<Bundle 1 Title>' as <Persona 1 Name>"
     2. "Switch persona: Walk as <Alternative Persona Name> (<Role>)"
     3. "Select alternative: '<Bundle 2 Title>' as <Persona 2 Name>"
-    4. "Customize situation, checkpoint, or preconditions"
+    4. "Customize situation, checkpoint, or brief"
 - Otherwise (in CLI or text-only environments):
 
 Scaffold this scenario for walkthrough?
   1. [Recommended] Scaffold '<Bundle 1 Title>' as <Persona 1 Name>
   2. Switch persona: Walk as <Alternative Persona Name> (<Role>)
   3. Select alternative: '<Bundle 2 Title>' as <Persona 2 Name>
-  4. Customize situation, checkpoint, or preconditions
+  4. Customize situation, checkpoint, or brief
 
 Press Enter to scaffold [1], select 2-3, or type adjustments:
 (Treat empty Enter or return as Option 1)
@@ -119,18 +118,11 @@ Roles with Stakes:
   • <Role 1>: <Stake>
   • <Role 2>: <Stake>
 
-Execution Preconditions (resolved at iamu-run):
-  • Assumed State: <What records/data should exist, e.g. "Department with existing risk register containing open hazards">
-  • Squint Guidance: <How the walker should approximate if exact records are missing, e.g. "If no packaging hazard exists, select any physical safety hazard and proceed with delegation">
-  • Reachable Surface: <Entry route matched against iamu/testability.md, e.g. "/incidents/new">
-
 Persona & Brief:
   Persona:      <Existing slug from panel OR new candidate: Name (Role)>
   Friction:     <Diagnostic friction trigger and bounce risk>
   Walker Brief:
     "<First-person brief in persona voice (2–3 sentences). Describes what they intend to achieve before touching the product. Written verbatim to scenario markdown body.>"
-
-If the situation requires an un-mocked endpoint or missing data fixture to be walkable, offer to scaffold the missing MSW handler (e.g. in `src/mocks/handlers.ts`) or fixture file directly in the codebase before finalizing.
 ```
 
 **Interactive Draft Confirmation:**
@@ -139,13 +131,13 @@ If the situation requires an un-mocked endpoint or missing data fixture to be wa
   - Options:
     1. "[Recommended] Scaffold scenario and prepare walkthrough"
     2. "Switch persona: Walk as <Alternative Persona> (<Role>)"
-    3. "Adjust checkpoint, preconditions, or surface"
+    3. "Adjust situation, checkpoint, or brief"
 - Otherwise (in CLI or text-only environments):
 
 Scaffold scenario '<Outline Title>'?
   1. [Recommended] Scaffold scenario and prepare walkthrough
   2. Switch persona: Walk as <Alternative Persona> (<Role>)
-  3. Adjust checkpoint, preconditions, or surface
+  3. Adjust situation, checkpoint, or brief
 
 Press Enter to scaffold [1], select 2, or type adjustments:
 (Treat empty Enter or return as Option 1)
@@ -202,10 +194,10 @@ Use CLI commands to scaffold entities with valid frontmatter. The CLI generates
 ```bash
 iamu new capability --name "Incident Reporting" \
   --description "What staff can do when something goes wrong on shift" \
-  --paths "/incidents" \
   --area "Operations" \
   --json
 ```
+Leave `--paths` out: route prefixes are product structure, not part of the situation. Without them, `iamu explore coverage` matches pages whose first path segment equals the capability slug; add `paths` to the capability file later, outside drafting, if that groups the area's pages wrong.
 
 **2. Outline** (the situation — problem-space, no UI references):
 ```bash
@@ -223,14 +215,13 @@ The `--capability`, `--additional-capabilities`, `--tension`, `--narrative`, and
 ```bash
 iamu new persona --name "Maria Gomez" --role "Site Safety Coordinator" --disposition "Time-pressured, prefers physical paper over complex forms" --json
 ```
-The `--role` and `--disposition` flags populate frontmatter directly. If `iamu/context.yml` has an `access` mechanism, also set the persona's `access` to the account, role, or switcher key that matches this persona in the product — check what users the product actually has rather than inventing one; leave it out if nothing fits and say so. Write the persona's background narrative and test expectations as the markdown body.
+The `--role` and `--disposition` flags populate frontmatter directly. Leave `access` out — which product account the persona uses is decided when the scenario is staged in `iamu-run`. Write the persona's background narrative and test expectations as the markdown body.
 
 **4. Scenario** (the binding):
 ```bash
-iamu new scenario --name "maria-gomez--busy-shift-handoff" --outline busy-shift-handoff --persona maria-gomez [--entry /path/on/the/product] [--state-description "<Assumed state description>"] [--state-approximation "<Squint guidance for walker>"] --body "<First-person brief in persona voice (3–5 sentences)>" --json
+iamu new scenario --name "maria-gomez--busy-shift-handoff" --outline busy-shift-handoff --persona maria-gomez --body "<First-person brief in persona voice (3–5 sentences)>" --json
 ```
-When the situation begins on a specific page (the persona follows a link from a video, an email, a search result), add `--entry /path/on/the/product` — the run starts there instead of the home page.
-`--outline` is required. `--persona` is optional (omit for drafts). Pass `--state-description` and `--state-approximation` if preconditions were defined in step 3 to populate the scenario's `state:` frontmatter automatically.
+`--outline` is required. `--persona` is optional (omit for drafts). Do not pass `--entry` or the `--state-*` flags here: where the walk starts and what data it needs are set when `iamu-run` stages the scenario. If the situation begins somewhere specific (the persona follows a link from an email, a video, a search result), say so in the narrative or brief in the persona's words; staging turns that into a start page.
 
 For drafts (no persona): omit `--persona`, omit `--body`.
 
@@ -256,7 +247,7 @@ Run `iamu validate --all` to verify all entities before reporting done.
 
 - **Brainstorm, don't fill forms.** Propose varied seeds. Challenge assumptions. The best scenarios are ones the user hadn't considered.
 - **Problem-space only.** Scenarios describe human situations — never UI, screens, buttons, or features. The walkthrough discovers whether the product supports the situation.
-- **Ground in the codebase.** Use your knowledge of what the product actually does to propose scenarios that stress-test real capabilities. But keep the scenario language product-agnostic.
+- **Ground in the domain, not the codebase.** Start from what the persona's week demands. A situation the product cannot support yet is a good scenario: the walk shows the gap with evidence.
 - **Present before creating.** Show situation, personas, and capability to the user before writing files.
 - **Scenario vocabulary.** Say "scenario" in output, never "outline" or "capability."
 - **Multiple personas surface different problems.** A manager, a field worker, and an auditor will find completely different issues in the same situation. Propose personas that test the product differently, not personas that are cosmetically varied.
@@ -265,4 +256,4 @@ Run `iamu validate --all` to verify all entities before reporting done.
 - **Capability is quiet.** High-confidence matches fire silently.
 - **Slug references are load-bearing.** Write referenced entities before the entities that reference them.
 - **Validate before done.** Always run `iamu validate --all` after writing entities.
-- **Use CLI for scaffolding.** `iamu new <type>` creates valid frontmatter with UUIDs. Pass flags (`--role`, `--disposition`, `--capability`, `--tension`, `--human-test`, `--state-description`) directly instead of manual YAML editing.
+- **Use CLI for scaffolding.** `iamu new <type>` creates valid frontmatter with UUIDs. Pass flags (`--role`, `--disposition`, `--capability`, `--tension`, `--human-test`) directly instead of manual YAML editing.

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

@@ -31,7 +31,7 @@ If context is thin (few actors, sparse notes), say so upfront — "your context
 
 ## Steps
 
-### 1. Load domain context & testability boundaries
+### 1. Load domain context
 
 Read `iamu/context.yml`. Extract and hold:
 - **Domain + industry** — what world does this product operate in?
@@ -39,29 +39,19 @@ Read `iamu/context.yml`. Extract and hold:
 - **Governed_by** — regulations and standards (if applicable). These create structural tensions in regulated domains.
 - **Notes body** — extended context, often containing workflow descriptions, pain points, organizational dynamics.
 
-Read `iamu/testability.md` (if present) to enforce execution boundaries:
-- **Reachable surfaces:** Ground candidates in reachable routes. Avoid proposing scenarios for product areas with no navigable surfaces.
-- **Untestable boundaries:** Strictly avoid proposing scenarios in flows documented as untestable (e.g. un-mocked live payment gateways, SMS dispatch, third-party SSO).
-- **Mocks & Fixtures:** Note which candidates require existing database seeds or mock handlers.
+**Stay in the problem space.** Proposals come from the domain, not from the product's code, routes, pages or test setup. Do not read source files, `iamu/testability.md`, or `iamu explore` output while proposing, and never put a route, URL or screen into a candidate. Whether and how a situation can be set up in the product is decided when it first runs (`iamu-run` stages it), not here — a situation the product cannot support is worth walking: the persona hitting that wall is the finding.
 
 ### 2. Load existing coverage
 
 Read existing entities to understand what's already been tested:
-- `iamu/capabilities/` — what product areas exist?
-- `iamu/outlines/` — what situations are already drafted?
+- `iamu/capabilities/` — what product areas exist? Use each capability's title and description only; its `paths` are route prefixes and stay out of proposals.
+- `iamu/outlines/` — what situations are already drafted, and which capability each one covers?
 - `iamu/scenarios/` — what's already bound to personas?
 - `iamu/personas/` — who do we already have in our casting panel?
 
-**Check Live Product Map Coverage:**
-Inspect live surface coverage by checking `iamu status --json` (`explore`) or running `iamu explore coverage --json`:
-- **When an explore map exists:**
-  Extract unreached surfaces (`unreached` array) and `run_only_places`.
-  - **Grounding proposals in unreached topology:** Prioritize proposing scenarios that enter through or traverse these unreached surfaces, pairing them with actors from `context.yml` who have domain tension in those areas.
-  - Set each proposed scenario's `Reachable Surface` and entry route to the unreached surface path.
-- **When no explore map exists:**
-  Proceed with domain context grounding. Note: `Tip: run iamu explore <target_url> to map live surfaces so proposals target real unreached routes.`
+**Find untested product areas.** A capability no outline names (as `capability` or in `additional_capabilities`) is an area no persona has been near. Treat it as a prompt for the domain question — "who in this domain needs what this area is for, and when?" — never as a place to send a persona.
 
-Build a coverage picture: which capabilities have scenarios? Which actors from `context.yml` lack personas? Which discovered surfaces have 0 walkthrough coverage? Where are the gaps?
+Build a coverage picture: which capabilities have scenarios? Which actors from `context.yml` lack personas? Which kinds of situation (routine, deadline, handover, mistake to correct) are missing? Where are the gaps?
 
 ### 3. Determine focus
 
@@ -69,7 +59,7 @@ Four entry paths based on `$ARGUMENTS`:
 
 - **Persona / Tester panel** (e.g. `iamu-propose "personas"`, `"who else should we test with?"`, `"propose new personas"`) — analyze which actors from `context.yml` lack personas in `iamu/personas/`. Focus proposals on creating durable, diagnostically biased personas for uncovered roles.
 - **Area or capability** (e.g. `iamu-propose "employee provisioning"`) — focus proposals on this area. Match against capabilities and context actors/workflows.
-- **Open-ended** (e.g. `iamu-propose`, `iamu-propose "what's missing?"`) — analyze coverage gaps across scenarios, persona diversity, and unreached surfaces from `iamu explore coverage`. Prioritize uncovered capabilities, actors without personas, and unreached live surfaces.
+- **Open-ended** (e.g. `iamu-propose`, `iamu-propose "what's missing?"`) — analyze coverage gaps across scenarios and persona diversity. Prioritize untested product areas and actors without personas.
 - **Specific tension** (e.g. `iamu-propose "what happens when the safety coordinator disagrees with HR?"`) — use as seed but ground in context. Verify the tension is real (do these actors and dynamics exist in the domain?).
 
 ### 4. Present candidates (Numbered Cards)
@@ -82,23 +72,19 @@ Lead with existing coverage using clickable links, then render the candidates:
 
 ```
 Existing coverage: <N> scenarios ([<slug1>](iamu/scenarios/<slug1>.md), ...). Uncovered areas: <gaps>.
-Product map: <R>/<T> surfaces reached · <U> unreached ([view](iamu explore coverage)).
 
 1. <Short situation name> (<Actor from context>)
    • Capability: <Capability slug, e.g. billing-invoicing>
-   • Entry route: <Unreached route from map, e.g. /billing/invoices/new>
    • Tension: <1-line human/domain tension>
    • Stress-tests: <What this reveals about the product>
 
 2. <Short situation name> (<Actor from context>)
    • Capability: <Capability slug, e.g. team-access>
-   • Entry route: <Unreached route from map, e.g. /team/roles/custom>
    • Tension: <1-line human/domain tension>
    • Stress-tests: <What this reveals about the product>
 
 3. <Short situation name> (<Actor from context>)
    • Capability: <Capability slug, e.g. incident-response>
-   • Entry route: <Unreached route from map, e.g. /incidents/export>
    • Tension: <1-line human/domain tension>
    • Stress-tests: <What this reveals about the product>
 
@@ -147,7 +133,7 @@ Press Enter to add [1], select 2-3, or describe adjustments:
 Ground rules for generation:
 
 - **Start from the actor's week, not the feature list.** What does this person actually do on a Tuesday? What goes wrong? What requires judgment?
-- **Use authentic domain vocabulary.** Speak in the language of the domain and the product UI (e.g., "skyddsombud" rather than generic "safety representative"), avoiding abstract test jargon.
+- **Use authentic domain vocabulary.** Speak in the language of the domain (e.g., "skyddsombud" rather than generic "safety representative"), avoiding abstract test jargon.
 - **Prefer mundane frequency over dramatic edge cases.** The scenario that happens every week reveals more than the one that happens once a year.
 - **Structural tensions come from the domain, not from product limitations.** A real tension: "the regulation requires immediate reporting but the coordinator handles 3 sites." A fake tension: "the CSV upload has a 50-row limit."
 - **Never mention the product, its UI, its features, or its limitations.** The scenario exists in the domain. The product encounter happens during the walkthrough.
@@ -157,7 +143,7 @@ Ground rules for generation:
 
 ### 5. Selection and Handoff
 
-- **User picks a scenario candidate (e.g. "1" or Enter)** → Immediately invoke `iamu-new` in **Fast-Path Scenario Mode** passing the selected candidate title, actor, primary capability slug (`--capability`), entry path (`--entry`), tension, and evaluation checkpoint as structured arguments. Do NOT allow `iamu-new` to restart seed brainstorming. It must present the single Scenario Spec-Sheet directly for instant 1-click persistence.
+- **User picks a scenario candidate (e.g. "1" or Enter)** → Immediately invoke `iamu-new` in **Fast-Path Scenario Mode** passing the selected candidate title, actor, primary capability slug (`--capability`), tension, and evaluation checkpoint as structured arguments. Do NOT allow `iamu-new` to restart seed brainstorming. It must present the single Scenario Spec-Sheet directly for instant 1-click persistence.
 - **User picks a persona candidate** → Immediately invoke `iamu-new` in **Standalone Persona Mode** with the candidate's name, role, disposition, and friction triggers to scaffold directly into `iamu/personas/<slug>.md`.
 - **User refines** → regenerate candidates applying the requested adjustments.
 - **User rejects all** → ask what domain area or actor they want to explore. Loop back to step 4.

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

@@ -166,7 +166,7 @@ If the target is a local URL (e.g. `http://localhost:*`, `http://127.0.0.1:*`) a
    - Poll `<url>` with HTTP requests until it responds (timeout: 30s).
    - Once reachable, proceed immediately to the walkthrough.
 
-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.
+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 it first with `iamu set scenario <slug> --entry <path>` (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:
 
@@ -178,17 +178,26 @@ Record it as a target string the run can carry, for example `sim://<device-name>
 
 **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.
 
+**Stage the starting state — first run of a scenario.** Drafting a scenario deliberately leaves out the product's code, pages and data, so its first run is where it gets staged. If the scenario has no `state` yet, invoke the `iamu-stage` skill (or stage inline):
+
+1. From the outline, persona and brief, say in plain words what the world must contain for the situation to play out (which records, how old, in what condition, who else is involved) and who the persona must be signed in as.
+2. Check what the project already has to produce that world: seed scripts, fixtures, factories, mock handlers. `iamu/testability.md` lists the known ones; the codebase has the rest.
+3. Show the user each requirement and whether it is met, then agree how to get there: an existing seed, a change to a seed script or mock handler (propose it as a diff for the user to apply), data the user creates by hand, or letting the walker approximate.
+4. Record the outcome on the scenario so later runs do not ask again: `iamu set scenario <slug> --state-description "<the world, in domain words>" --state-approximation "<how the walker picks the closest record when the exact one is missing>"`. When the situation needs no particular data (a visitor reading a public page), record that too: `--state-description "No particular data needed"`. Project-wide facts learned on the way ("the seed needs Docker running") go in the `iamu/testability.md` body.
+
+Staging adds to a scenario and never changes what it is about: do not edit the narrative, tension, human tests or brief; if one looks wrong, tell the user. When the product cannot support the situation, walk it anyway — the persona hitting that wall is the finding. Stop only when the walk itself cannot be set up: the persona's account cannot be reached, the data cannot be produced, or the situation crosses an untestable boundary.
+
 **Expected State & Semantic Squinting — verify environment before walking.** A scenario testing triage, review, or audits requires a populated, realistic system.
 1. **Expected State:** If the scenario defines `state.description`, verify the landing screen matches what the persona expects to see (e.g. populated register, open incidents). If the screen is completely blank and the persona cannot self-seed, stop early and report the run as blocked by missing preconditions rather than logging false product bugs.
 2. **Data Squinting & Approximation:** If the exact record described in the narrative is absent (e.g. no "damaged conveyor belt" hazard), the walker must follow `state.approximation` — "squint" at the real data, pick the closest plausible record (e.g. an active mechanical or safety hazard), and proceed with the evaluation/delegation workflow.
    - **Squinting Guardrail:** Squinting is bounded to semantically related items within the same domain workflow. It does NOT permit drifting to unrelated modules (e.g. switching from risk assessment to user profile settings). If no plausible record exists, declare the run blocked.
 3. **Empty State Fallback:**
    - If the database is empty and the persona role has creation rights (e.g. Manager or Reporter), the persona may create the minimal viable record in-character to proceed with the core test.
-   - If the persona role is read-only or subordinate (cannot self-seed), stop and report the run as blocked by preconditions.
+   - If the persona role is read-only or subordinate (cannot self-seed), stop and report the run as blocked by preconditions (`iamu summary <run-id> --blocked "<what was missing>"`).
 
 **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.project` — from `iamu/testability.md` `access` (older projects: `iamu/context.yml`): 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).
 
 **Interactive Auth Handshake (for enterprise auth, SSO, 2FA, BankID):**
@@ -201,7 +210,7 @@ If the product is behind enterprise login where automated dev persona switching
 If automated switching exists:
 1. Check the project's own agent docs (`CLAUDE.md`, `AGENTS.md`) for a documented way to switch user or role.
 2. Map the persona to the closest account or role the product actually has. If nothing fits, say so.
-3. Write what you learned: the mechanism into `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.
+3. Write what you learned: the mechanism into the `iamu/testability.md` frontmatter as `access:` (it is test setup, so it does not belong in `context.yml`, which holds the domain; if `iamu doctor` finds it there, move it), and the persona's own key with `iamu set persona <slug> --access <key>`. Passwords and tokens never go in either — name where they live (an env var, a vault entry) instead.
 
 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.
 
@@ -345,6 +354,8 @@ iamu complete <run-id> --no-prompt --no-push --json
 
 This reads all steps, findings, and entity files, assembles `canonical.json`, generates `report.md`, and computes the delta against prior runs.
 
+**If the result has `blocked`**, the walker could not start the walk as it was set up (`iamu summary --blocked`): it could not become the persona, or the world the situation needs was not there. That is a setup problem, not a product finding. Skip B and C — a blocked run is never compared with earlier runs and never counts as a re-run. Tell the user in one line what was missing (`blocked.reason`), then run the `iamu-stage` skill with that reason as the starting point: fix the scenario's `state`, the persona's access, or the seed, and offer to run the scenario again. Findings the walker recorded before it stopped stay as they are. E still runs in linked mode; the report says the run was blocked.
+
 **B. Match findings to earlier runs.** Get the matcher bundle:
 
 ```bash

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

@@ -116,6 +116,7 @@ Write `iamu/testability.md`:
 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>
 ---

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

@@ -0,0 +1,155 @@
+---
+name: iamu-stage
+description: Prepare and verify environment state before a scenario runs. Bridges domain situations to codebase reality — scouts seeds, mocks, routes, and auth; recommends testability improvements or pragmatic semantic squinting; and writes staging fields with `iamu set`. Use when preparing an unstaged scenario, fixing a blocked walk, or auditing testability.
+generatedBy: __IAMU_VERSION__
+---
+
+You are a testability engineer and staging companion, not a passive form-filler or an unyielding blocker.
+
+Your mission: Bridge the scenario's human situation to the codebase's running reality. You do not change what a scenario is about (never edit narrative, tension, human tests, or persona background); you determine how the system can be staged to let that situation play out.
+
+The core tension you resolve:
+- A scenario written in pure problem space ("Maria triages open incidents under time pressure") cannot run against a blank database or as the wrong user.
+- If you run blindly with zero setup, the walker will wander, burn tokens, and get blocked.
+- If you demand a massive, flawless seed infrastructure before running anything, the developer gets bogged down in test setup.
+
+You strike the balance by acting as a **testability advisor**:
+1. You identify the world the scenario expects.
+2. You scout the codebase to see what already exists (seeds, factories, mocks, routes, auth).
+3. You present the **Strategic Fork**: offer to scaffold real testability improvements (seeds, presets, mocks), while ALWAYS providing the path of least resistance (semantic squinting) so the user can run immediately if they choose.
+4. You persist the decisions with `iamu set` so future runs execute automatically without asking again.
+
+$ARGUMENTS
+
+## Prerequisites
+
+Before starting, check that `iamu/context.yml` and `iamu/testability.md` exist.
+- If `iamu/` is missing, run `iamu init` first.
+- If `iamu/testability.md` is missing, scaffold it with environment safety fences and known test accounts.
+
+## Steps
+
+### 1. Identify the Scenario Contract (The "What")
+
+Determine the target scenario from `$ARGUMENTS`:
+- If a scenario slug is given (e.g. `iamu-stage "maria--handoff"` or `maria--handoff`), use it.
+- If no slug is given, inspect `iamu list scenarios --json` to find scenarios with missing `entry_path` or `state`, or review recently blocked runs.
+
+Read `iamu/scenarios/<slug>.md` and its bound outline (`iamu/outlines/<outline>.md`) and persona (`iamu/personas/<persona>.md`):
+- **Who:** Persona role, technical disposition, and required account access.
+- **Where:** What screen/page does the persona start on? (The landing URL / route prefix).
+- **What:** What world state must exist for the situation to make sense? (e.g. "Five open incidents at one site, one serious and unassigned, two older than a week").
+- **Human Tests:** What specific questions will be evaluated? (e.g. "Can Maria see which incident is unassigned without clicking each row?").
+
+### 2. Scout the Codebase & Environment (The "How")
+
+Inspect the project to understand what the system under test already supports:
+
+1. **Testability & Safety Fence:**
+   - Read `iamu/testability.md`: what environments are safe? Is there a documented dev login mechanism (switcher, header, token, seeded accounts)?
+
+2. **Database & Seeds:**
+   - Check `package.json` for seed and reset scripts (`db:seed`, `prisma db seed`, `seed:dev`, `docker compose up`, etc.).
+   - Inspect existing seed files (`prisma/seed.ts`, `drizzle/seed.ts`, `seeds/`, `test/fixtures/`) to see what records are already populated by default.
+   - Check schema models (`schema.prisma`, `schema.ts`) to see what fields and relations incidents/tickets/items require.
+
+3. **Routes & Entry Surface:**
+   - Search the app's route tree (`src/app/`, `src/pages/`, `src/routes/`) to verify the exact path corresponding to the scenario's starting point (e.g. `/incidents`, `/app/triage`, `/reports`).
+
+4. **Running Dev Server:**
+   - Verify the target URL (e.g. `http://localhost:3000`). If a local server is running, check what port it uses.
+
+### 3. Audit Gaps & Present the Strategic Fork
+
+Present an honest, concise audit of what the scenario needs vs. what the system currently provides:
+
+```markdown
+### Staging Audit for `<scenario-slug>`
+
+- **Persona Role:** Maria Gomez (Shift Coordinator)
+  - Need: Account with site-coordinator privileges.
+  - Found: `coordinator@site-a.test` in seed scripts.
+- **Entry Route:** `/incidents` (verified in `src/app/(dashboard)/incidents/page.tsx`).
+- **World State:** 5 open incidents, 1 serious and unassigned.
+  - Current DB / Seed: Default seed only creates 0 incidents, or empty demo state.
+```
+
+Now present the **Strategic Fork** to the user. Do not be an unyielding bureaucrat. Give the user two clear options:
+
+#### Option A: Build Testability (The High-Integrity Path)
+*Recommend this when a clean seed script or preset is easy to add.*
+- Explain what is needed: "We can make your system more testable by adding an open-incidents preset to your seed script."
+- Propose the concrete code diff for the seed script or test fixture (e.g. extending `prisma/seed.ts` or a new `scripts/seed-incidents.ts`).
+- **Safety invariant:** All test seeds must be non-destructive and idempotent using fixed test keys/IDs (upserts); never propose or execute destructive resets (`migrate reset`, `db:reset`, or table drops) on local dev databases.
+- **Auth efficiency:** When configuring access, prefer dev bypass headers/switchers or session cookies over automated form-fills whenever available.
+- Explain the benefit: 100% deterministic runs, zero flakiness, reusable across all incident-related scenarios.
+
+#### Option B: Semantic Squinting (The Path of Least Resistance)
+*Offer this so the user can test immediately without modifying code.*
+- Explain the approximation: "If you want to run against your existing dev database right now without changing code, we can instruct the walker to squint."
+- Formulate the semantic squinting rule:
+  > *"Squint at whatever active incidents or tickets exist on screen, even if only 1 exists and dates are today. Maria will evaluate triage workflows against available items."*
+- State the trade-off: Maria will walk and do her best, but human tests that strictly require multiple old incidents may report unobserved or inconclusive results.
+
+#### Option C: Zero Setup Needed (`strategy: none`)
+*Use when the scenario is on a public page, landing flow, or self-contained form that requires no pre-existing database records.*
+- State: "This situation reads a public page and requires no pre-existing world state."
+- Mark `--state-description "No particular data needed"`.
+
+### 4. Apply & Persist Staging
+
+Once the user chooses (or confirms):
+
+1. **If code scaffolding was chosen (Option A):**
+   - Apply the seed/mock code changes.
+   - Run the seed command to verify it populates the environment.
+
+2. **Save staging fields to the scenario with `iamu set`:**
+   ```bash
+   iamu set scenario <slug> \
+     --entry "/<route>" \
+     --state-description "<Description of required world in domain words>" \
+     --state-approximation "<How the walker approximates when exact records are missing>"
+   ```
+   If Option C was chosen:
+   ```bash
+   iamu set scenario <slug> --entry "/<route>" --state-description "No particular data needed"
+   ```
+
+3. **Save persona access if needed:**
+   If the persona requires a specific role or switcher key:
+   ```bash
+   iamu set persona <persona-slug> --access "<account-or-role-key>"
+   ```
+
+4. **Record project-wide learnings:**
+   If you discovered project-level conventions (e.g. "Seed requires `SEED_ORG=site-a`", or "Role switching uses `localStorage.setItem('dev-role', ...)`"), record them in `iamu/testability.md`.
+
+5. **Validate:**
+   Run `iamu validate iamu/scenarios/<slug>.md` to confirm the frontmatter is valid.
+
+### 5. Confirm Ready to Walk
+
+Summarize the staging setup cleanly in 3-4 bullet points:
+- **Scenario:** `<slug>` staged.
+- **Entry Path:** `/<route>`
+- **Starting State:** `<state description>`
+- **Approximation:** `<approximation guidance>`
+- **Persona Access:** `<access key or login mechanism>`
+
+Prompt the user with the 1-click execution command:
+```bash
+iamu-run <scenario-slug>
+```
+
+---
+
+## Handling Re-entry: Recovering a Blocked Run
+
+When invoked because a previous walkthrough ended with `blocked: { reason: "..." }`:
+1. **Focus directly on the blocker:** Read `blocked.reason` from `canonical.json` or `summary.json`.
+2. **Diagnose the failure mode:**
+   - *Was it missing seed data?* Offer Option A (scaffold seed) or Option B (loosen approximation).
+   - *Was it an auth / permissions error?* Update `persona.access` or adjust `testability.md` dev credentials.
+   - *Was it a 404 or bad entry route?* Inspect app routes and fix `scenario.entry_path`.
+3. **Re-stage with `iamu set scenario <slug>`** and immediately offer to re-run the walk.

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

@@ -47,7 +47,7 @@ If `iamu status` reports fixes awaiting a re-run:
 
 **Product Map & Unreached Surfaces:**
 If `iamu status --json` has `explore` data:
-• <T> surfaces mapped (<R> reached, <U> unreached) — run `iamu explore coverage` to inspect blind spots or `/iamu:propose` to target unreached surfaces.
+• <T> surfaces mapped (<R> reached, <U> unreached) — run `iamu explore coverage` to inspect blind spots. Unreached pages say where no persona has been, not what to test: `iamu-propose` finds situations for untested product areas from the domain.
 
 ### 3. Ignore internal templates
 

package/package.json

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