@iamu-dev/iamu 0.8.0-beta.0 → 0.8.0-beta.1

package/dist/templates/prompts/walk.md

@@ -172,10 +172,12 @@ Your walking prompt has an `## Access` section saying how to become this persona
 
 - For `iamu browse`:
   ```bash
-  iamu browse step --run <run-id> --action "<action>" --note "<first-person monologue>" <command> [args...]
+  iamu browse step --run <run-id> --action "<action>" --note "<first-person monologue>" <command> [args...] [--then '<command> [args...]']
   ```
   Commands: `click <role> "<name>"`, `click-text "<text>"`, `click-index <N>`, `fill <role> "<name>" "<text>"`, `fill-index <N> "<text>"`, `select <role> "<name>" "<val>"`, `upload <role> "<name>" "<file-path>"`, `upload-index <N> "<file-path>"`, `press <key>`, `scroll [px]`, `back`, `shot`, `wait [ms]`.
-  When accessibility names are ambiguous, missing, or broken, inspect indexed interactive elements and drive via `click-index <N>`, `fill-index <N> "<text>"`, or `upload-index <N> "<file-path>"`.
+  `iamu browse step` automatically saves the screenshot and prints the updated `[#N]` interactive elements and accessibility snapshot — do not run a separate `snapshot` command after `browse step`.
+  Chain consecutive form fills on the same screen into a single step using `--then '<command> [args...]'`.
+  Prefer driving via `click-index <N>`, `fill-index <N> "<text>"`, or `upload-index <N> "<file-path>"` using the `[#N]` numbers from the previous step's output.
   When a link or button opens a new window/tab (`target="_blank"`), manage tabs via `tabs`, `switch-tab <index>`, and `close-tab [index]`.
 - For other surfaces:
   ```bash
@@ -186,7 +188,7 @@ Your walking prompt has an `## Access` section saying how to become this persona
 `note` is your internal first-person persona reaction in character.
 The CLI automatically handles sequential numbering, timestamps, screenshot capture/linking, and live event streaming.
 
-**Findings:** Always scaffold with the CLI — never create finding files by hand or call host Edit/Write tools:
+**Findings:** Always scaffold with the CLI — never create finding files by hand or call host Edit/Write tools. When recording multiple findings, execute them together in a single shell command chained with `&&` rather than one turn per finding:
 
 ```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 --need "What I needed at that moment" --description "What happened and why it mattered" --json
@@ -204,7 +206,7 @@ iamu new-finding --scenario <slug> --run <run-id> --title "Short title" --type h
 
 Leave `triage_status` alone; triage is not the walker's job.
 
-**Screenshots:** Screenshots are captured automatically by `iamu browse step`. If driving manually, save to `iamu/.runs/<run-id>/screenshots/step-<N>.png` before recording each step. Screenshots are optional — if the browser tool disconnects or screenshots fail, use accessibility snapshots instead and continue walking.
+**Screenshots:** Screenshots are captured automatically by `iamu browse step`. Do not read step screenshot PNGs with your file-reading tool after routine steps — use the returned accessibility snapshot unless checking a visual layout discrepancy. If driving manually, save to `iamu/.runs/<run-id>/screenshots/step-<N>.png` before recording each step. Screenshots are optional — if the browser tool disconnects or screenshots fail, use accessibility snapshots instead and continue walking.
 
 **Execution rule:** Execute everything via CLI commands in the shell. Never invoke host Edit or Write tools on files in the workspace.
 
@@ -222,4 +224,4 @@ iamu summary <run-id> --reached "Sent the request; it shows Pending with my mana
 - `--question` — Questions for the product team: decisions the walk raised that the product does not settle and that you could not settle as the persona ("Should a reporter see the investigator's checklist at all?", "Is the 14-day notice rule enforced or only advised?"). Not doubts about the test itself.
 - `--setup-note` — Doubts about the test setup, not the product: data that seemed missing or unrealistic, an account that could not see what the situation needs, a date the scenario assumes ("No absences are recorded for summer 2027, so 'nobody is away' may only mean no data"). These go to whoever stages the scenario.
 
-Then return your final summary to the orchestrating agent so it can run `iamu complete` and the evaluation stage.
+Then reply to the orchestrating agent with a concise one-line status (`Walk complete: <N> steps, <M> findings`) so it can run `iamu complete` and the evaluation stage — do not re-type your findings or synthesis into chat.

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

@@ -90,22 +90,27 @@ Fix by looking, not by hoping:
 
 ## E. Start a design doc from the template
 
-Only when no design doc is recorded: `iamu design template` refuses otherwise, and a recorded doc changes only through proposals (**C**). The template is filled in from the code, never by a model: the token values in the frontmatter (light theme), the token groups by name, the contrast clashes the tokens have, each component with the props it takes, and the roles people come in (from the personas and situations, never their names). Everything a person decides is a `<placeholder>`. You and the user fill those in together, and the result becomes the team's doc.
-
-1. **Template.** Run `iamu design template --out iamu/.analysis/design-draft.md --json`. It is for the app the recorded tokens and components apply to, else the root; add `--dir <app>` when the user names another app, and pass the same `--dir` to the later commands. If it answers `out_exists`, a draft is in progress: ask whether to continue it (step 2 with that file) or start over (delete the file and run it again). Tell the user in two lines what came from the code (`sources`, the components, `roles`, `clashes`) and where the doc will go (`target`).
-2. **Fill it in with the user, one placeholder at a time.** Go through the `placeholders` in this order, one question per message, and edit the draft after each answer. Each question carries a suggested answer drawn from what is known: `iamu/context.yml`, the roles and situations, what runs and findings showed of the screens, the components and tokens. The user accepts it, changes it, or skips it (the placeholder stays; a decision still open also goes under Open Questions).
-   1. **Who it is for:** by role, and what they come to do. Suggest it from the roles and situations the Overview lists, then replace that list with the agreed words. Roles only, never a persona's name.
-   2. **How it should feel:** a few words (calm and plain, dense and fast). Suggest from the domain and the roles' dispositions.
-   3. **Accessibility target:** suggest WCAG 2.2 AA, or more when the domain asks for it (a public service, long reading).
-   4. **Look:** what each token group is for, and for each contrast clash, how to keep the two apart or where one may not be used.
-   5. **States:** how forms report errors, loading, failure, empty. Suggest from what the runs saw and the components that exist (an empty-state component, a field with an error prop). Only the states the product has.
-   6. **Content and voice:** the product's words for its things, tone by role, and date and number formats (suggest from the locale and what the screens show).
-   7. **Checks:** yes/no questions a reviewer answers by looking at one screen, where yes is a pass. Suggest them from the answers so far.
-   8. **Not in the library yet**, then **Open Questions:** components screens need that do not exist, and policy decisions still open.
-
-   Write a policy value (a notice period, a limit, a percentage) only when the user gives it as the product's rule; otherwise it stays a placeholder and an open question. Name tokens, never raw colours or lengths.
+Only when no design doc is recorded: `iamu design template` refuses otherwise, and a recorded doc changes only through proposals (**C**). The template is filled in from the code, never by a model: the token values in the frontmatter (light theme), the token groups by name, the contrast clashes the tokens have, each component with the props it takes, and the roles people come in (from the personas and situations, never their names). Everything else starts as a `<placeholder>`. Auto-extract what the code and `iamu/context.yml` already answer, ask the user only for the qualitative intent and clash decisions that code cannot answer, and the result becomes the team's doc.
+
+1. **Template & Auto-Extraction (0 questions to the user).** Run `iamu design template --out iamu/.analysis/design-draft.md --json`. It is for the app the recorded tokens and components apply to, else the root; add `--dir <app>` when the user names another app, and pass the same `--dir` to the later commands. If it answers `out_exists`, a draft is in progress: ask whether to continue it (step 2 with that file) or start over (delete the file and run it again). Tell the user in two lines what came from the code (`sources`, the components, `roles`, `clashes`) and where the doc will go (`target`).
+   Before asking the user anything, read the actual token files (`sources.tokens`), UI components (`sources.components`), page code, and `iamu/context.yml` (plus live rendered screens or recent runs if available), and pre-fill the code-evidenced placeholders in `iamu/.analysis/design-draft.md`:
+   - **Overview — Who it is for:** Synthesize who uses the product and what they come to do from `iamu/context.yml` and the roles and situations the Overview lists, then replace that list with the synthesized role-based words (roles only, never a persona's name or a single-scenario situation number).
+   - **Look — Token roles:** Fill in `<what each is for>` for each extracted token group from how stylesheets and components actually apply those tokens (always name tokens in backticks, never raw hex or px values in prose).
+   - **Interaction and States:** Extract how `Forms` (error reporting), `Loading`, `Failure`, and `Empty` states are actually implemented in `sources.components` and screens. Describe only the states the product has; missing state patterns go under `Not in the library yet` / `Open Questions`.
+   - **Content and Voice — Words & Formats:** Fill in the product's domain `Words` from product copy/`iamu/context.yml` and date/number `Formats` from formatters (`Intl`, `date-fns`, locale helpers) in the code.
+2. **Interview for Qualitative Intent & Clashes (2–3 focused questions, one question per message).** Never ask the user an open-ended blank question or make them describe their own code: each question MUST carry 2–3 concrete options (with `[Recommended]` first) drawn from `iamu/context.yml` and the codebase. Ask at most 2–3 questions, one question per message, using `ask_question` when available, and update the draft after each answer:
+   1. **Creative North Star, Feel & Accessibility Target (`Overview` & `Tone`):**
+      Propose 2–3 options for the system's visual personality and feel—each pairing a named **Creative North Star** metaphor with mood/density adjectives (`How it should feel`, e.g., *"The Quiet Workbench — calm, dense, and keyboard-first"*), `Tone` by role, and `Accessibility target` (recommend `WCAG 2.2 AA`, or stricter when the domain requires it, such as a public service or clinical tool)—and ask if there is any visual anti-reference (what the UI must *never* feel like).
+   2. **Palette Character, Contrast Clashes & Component Feel (`Look` & `Components`):**
+      Briefly show the auto-extracted token roles and component/elevation feel (flat vs. tonal layering vs. lifted, button/input character), and ask for the decision code alone cannot make:
+      - **When `clashes` is non-empty:** for each measured contrast clash in `Look`, propose a concrete `[Recommended]` rule (how to keep the pair apart or where one may not be used, e.g., restricting a low-contrast token to borders/decorators or pairing it with a darker text token) and ask the user to confirm or adjust.
+      - **When `clashes` is empty:** confirm the primary/accent usage doctrine (e.g., a Named Rule like *"The One Accent Rule — primary accent reserved for the single primary action per view"*) and any missing primitives for `Not in the library yet`.
+   3. **Unresolved States or Policy Gaps (only if needed):**
+      Skip this question when the codebase already covers states and formats cleanly. Ask a 3rd question only if key state patterns (`Forms`, `Loading`, `Failure`, `Empty`) are missing or contradictory in code, or if an open domain policy question needs a decision (establish a rule now vs. leave under `## Open Questions`).
+
+   After the user's answers, synthesize `## Review Checklist` (concrete yes/no questions a reviewer answers by looking at one screen, where yes is a pass, derived from the confirmed rules and extracted states) and `## Open Questions` (components screens need that do not exist yet, and policy decisions still open). Write a policy value (a notice period, a limit, a percentage) only when the user gives it as the product's rule; otherwise it stays a `<placeholder>` and an open question. Name tokens, never raw colours or lengths.
 3. **Check.** Run `iamu design draft-check --file iamu/.analysis/design-draft.md --json`. Fix each of its `errors` in the draft (a value or path the code does not have, a prop a component lacks, a persona's name) and check again; ask the user only when the fix is a choice.
-4. **Show it once.** Show the whole draft, then the remaining `warnings` in one list (line and message). Ask once: **adopt it**, or **edit** (what to change; edit, check again, and show it once more).
+4. **Show it once.** Show the whole draft, briefly highlight the non-obvious creative choices (North Star/feel, clash rules, review checks), and list the remaining `warnings` in one list (line and message). Ask once: **adopt it**, or **edit** (what to change; edit, check again, and show it once more).
 5. **Adopt.** Run `iamu design adopt --file iamu/.analysis/design-draft.md --json` (`--to <path>` when the user wants it elsewhere). It refuses only when the target already exists: then ask for another path. It writes the doc and records it, with `applies_to` for its app. From then on it is the team's doc: iamu changes it only through proposals a person accepts.
 6. Offer **A2** (point agents at the doc).
 

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

@@ -12,6 +12,8 @@ This skill resolves what scenario to run following a clear **Target Scenario Res
 2. **Active conversational context:** When `$ARGUMENTS` is empty or generic (e.g. "it", "that", "this", "run it", "walk it", "go"), and a scenario was created, modified, staged, or discussed in the active session — immediately resolve to that active scenario without prompting or re-scanning.
 3. **No argument & No active session scenario:** Check unfinished runs, then present a prioritized pickable list (reruns needing proof first, then drafts and ready-to-run).
 
+**`--target <url>` (or a bare `http(s)://...` URL in `$ARGUMENTS`):** when `$ARGUMENTS` contains `--target <url>` or a URL, take it out before resolving the scenario and persist it immediately with `iamu set testability --target <url>` (and if the resolved scenario had its own `target_url` override that was shadowing the project target, clear it with `iamu set scenario <slug> --no-target` unless the user asked for a scenario-only URL).
+
 **`--no-ux`:** when `$ARGUMENTS` contains `--no-ux`, take it out before resolving the scenario and skip the designer's review (step C3) for this run only: after A, record `iamu designer-record <run-id> --skipped "--no-ux"` so the report says it was skipped. There is no project setting for it: every other run gets a designer's review.
 
 **`--critic`:** when `$ARGUMENTS` contains `--critic`, take it out before resolving the scenario. This run is one critic pass in a builder ↔ critic loop (a gauntlet loop) the user orchestrates: the builder needs the verdict and the findings fast, not fixes or a design review. Skip the advisor (C2) entirely and skip the designer's review (C3): after A, record `iamu designer-record <run-id> --skipped "critic mode"`. Run A, B, C, D (and E in linked mode) as usual. In step 5, present the glance without the Advisor and Designer lines, and do not offer **directions** or **designer**. Per invocation only, like `--no-ux`. When the loop looks converged (every human test passes, or no open major or critical findings), add one line: `Loop looks converged: run once without --critic for the advisor's and designer's review.`
@@ -22,8 +24,6 @@ $ARGUMENTS
 
 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.
 
-**Fast Preflight Type/Lint Gate:** Run `iamu preflight` before booting dev servers or walkers. If syntax, typecheck, or lint checks fail, halt immediately with the compiler diagnostic and fix them before launching the browser. Never burn minutes on a browser session against code that will not compile.
-
 ## Steps
 
 ### 0. Verify a driving surface
@@ -152,14 +152,26 @@ After bind + brief, the scenario is ready to execute. Continue to step 3.
 
 ### 3. Target
 
-**Web** — determine the target URL:
-1. If the user passed an explicit target or the scenario has `target_url`, use that.
-2. Otherwise, check `iamu/testability.md` for `target_url`.
-3. If still unconfigured, prompt the user for the target URL (live product, staging, or localhost).
+**Web** — determine and confirm the target URL:
+1. If the user passed `--target <url>` (or a URL in `$ARGUMENTS`), persist it with `iamu set testability --target <url>` (and clear any stale scenario override with `iamu set scenario <slug> --no-target`) and use that.
+2. Otherwise, check the scenario's `target_url`, then check `iamu/testability.md` for `target_url` and `status`.
+3. **Unverified or missing target gate:** If `iamu/testability.md` is missing, has no `target_url`, or has `status: draft` (an unverified guess from `iamu init`), do NOT blindly trust the guess. Ask one focused question to confirm the Target URL and Dev Command before probing or booting:
+   - If your environment provides an interactive user-prompt tool (e.g. `ask_question`, `ask_followup_question`), invoke it:
+     - Question: "Target URL & Dev Command: Where does this app run locally?"
+     - Options:
+       1. "[Recommended] Use `<detected_url>` (`<dev_command>`)"
+       2. "Same command (`<dev_command>`), different port or URL — tell me the URL"
+       3. "Use a staging or remote URL — tell me the URL"
+   - Otherwise, state the detected URL and command and ask the user to confirm or provide the right URL.
+   - Persist the confirmed target immediately so `iamu/testability.md` is marked `status: verified`:
+     ```bash
+     iamu set testability --target <url> --dev-command "<dev_command>"
+     ```
+
 **Dev Server Preflight Check:**
 Verify target reachability before launching the walker with `iamu doctor --target <url>` (or a fast HTTP probe).
 If the target is a local URL (e.g. `http://localhost:*`, `http://127.0.0.1:*`) and is unreachable:
-1. Inspect `iamu/testability.md` for `Command:` under `## Target & Run Instructions` (or check `package.json` for a `dev` or `start` script).
+1. Inspect `iamu/testability.md` for `dev_command` (or `Command:` under `## Target & Run Instructions`, or `package.json` for a `dev` or `start` script).
 2. Prompt the user:
    - If interactive tool available:
      - Question: "Target URL <url> is unreachable. Boot dev server now?"
@@ -172,8 +184,11 @@ If the target is a local URL (e.g. `http://localhost:*`, `http://127.0.0.1:*`) a
      Proceeding with dev server boot — say "wait" to start manually or provide a different target URL.
 3. If Option 1 is chosen:
    - Launch `<dev_command>` in the background as a managed daemon process.
-   - Poll `<url>` with HTTP requests until it responds (timeout: 30s).
+   - Inspect the dev server stdout for the actual listening URL/port (e.g. if Vite or Next.js switches from `:5173` to `:5174`). If the actual URL differs from `<url>`, persist it immediately with `iamu set testability --target <actual_url>` and note the port change in one line.
+   - Poll the target URL with HTTP requests until it responds (timeout: 30s).
    - Once reachable, proceed immediately to the walkthrough.
+4. If Option 3 ("Specify a different target URL") is chosen:
+   - Ask for the URL and **persist it to disk** with `iamu set testability --target <new_url>` (and if the scenario had a stale `target_url` override, clear it with `iamu set scenario <slug> --no-target`) so future runs use the corrected URL automatically.
 
 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.
 
@@ -209,18 +224,27 @@ Staging adds to a scenario and never changes what it is about: do not edit the n
 - `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):**
-If the product is behind enterprise login where automated dev persona switching is not configured:
+**Confirm Login & Auth When Unconfigured:**
+Never silently guess login credentials or auth strategy without confirming with the user. If `iamu/testability.md` has no `auth_strategy` / `access` configured (or is still `status: draft`) and the scenario requires a signed-in persona:
+1. Check the codebase and agent docs (`CLAUDE.md`, `AGENTS.md`, seed files, auth routes) to see if a dev login mechanism exists so you can pre-fill a recommendation.
+2. Ask one focused question:
+   - If your environment provides an interactive user-prompt tool (e.g. `ask_question`, `ask_followup_question`), invoke it:
+     - Question: "Login & Auth for `<persona.name>` (`<persona.role>`): How should Iamu sign in as this persona?"
+     - Options:
+       1. "[Recommended] <Detected mechanism from codebase/docs, or 'Interactive login in Chrome' if none detected>"
+       2. "Use a dev switcher, header, storage key, or seeded test account — tell me how"
+       3. "Interactive login in Chrome (SSO / 2FA / manual sign-in)"
+       4. "No login needed (public / unauthenticated)"
+   - Otherwise, state the recommended login mechanism and ask the user to confirm or specify how to log in.
+3. Persist what the user confirmed: the project mechanism into `iamu/testability.md` via `iamu set testability --auth-strategy <strategy> --access "<mechanism>"`, and the persona's own account/role 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.
+
+**Interactive Auth Handshake (for `interactive_browser`, enterprise auth, SSO, 2FA, BankID):**
+If `auth_strategy` is `interactive_browser` or the product is behind enterprise login where automated dev persona switching is not configured:
 1. Open the browser to the target URL (`iamu browse start --run <run-id>` or browser tool).
 2. Prompt the human user:
    > 👉 **Please log in as `<persona.role>` (`<persona.name>`) in the opened browser window.** Tell me once you reach the dashboard (e.g. "I'm logged in") to hand control to the walker...
 3. Wait for the user to confirm, then let the walker drive the authenticated session.
 
-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. Persist what you learned: the mechanism into `iamu/testability.md` via `iamu set testability --access "<key>"`, 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.
 
 ### 4. Execute the walkthrough
@@ -505,7 +529,7 @@ Then, one short line each, only the ones that apply. These are counts; the detai
 - Design docs: `Design docs: <N> proposed edits — decided after the findings` (`design_proposals` from C2, `proposals` from C3). They wait for a person; never apply them yourself.
 - ⚠ Test setup (`summary.setupNotes`): `⚠ Test setup: <n> doubts about the test, not the product. A finding resting on one may not be real.` Never fold this one away.
 - Sync (E): `⚠ Sync: <n> findings changed by a teammate too` when the result has `conflicts`: name them and give the resolution (`iamu pull --force` to take theirs after copying your edits aside, or `iamu sync --keep-mine` to keep yours). When it has `pending_deletes`: `<n> deletions wait for you: check them, then run iamu sync --confirm-deletes`. Never run either yourself.
-- Design doc offer: only when the designer's result (C3) had `offer_template: true`: `No design doc yet: say "start it" and I'll draft one from your code with you, or "no" and I won't offer again.` On "start it", after triage, follow the `iamu-design` skill, mode E. On "no", run `iamu design template --decline`.
+- Design doc offer: only when the designer's result (C3) had `offer_template: true`: `No design doc yet (designer judged by general craft only — Iamu gets much sharper when it checks your own tokens, components, and rules): say "start it" (or run iamu-design) and I'll draft one from your code with you, or "no" and I won't offer again.` On "start it", after triage, follow the `iamu-design` skill, mode E. On "no", run `iamu design template --decline`.
 
 Then the link to the full walkthrough, which shows the persona's reasoning beside each screenshot:
 

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

@@ -78,70 +78,108 @@ No local codebase detected. To seed context, provide one of:
 
 ### 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.
+Never dump the target URL, dev command, login mechanism, and untestable boundaries into a single "take-it-or-leave-it" blob. Walk through them **one focused question at a time**, using what you found in the codebase to pre-fill the recommended choice and persisting each answer immediately with `iamu set testability`.
 
-**Dual-Surface Prompting (Sequencing Rule):**
-You MUST output the safety fence card to the chat stream FIRST. In the SAME turn, invoke `ask_question` with the full context embedded in the `question` argument:
+#### Step 1a: Target URL & Dev Command (1 question)
+
+Before asking, check whether a server is already responding on the detected port (`curl -I` or `iamu doctor --target <url> --json`). If this is a monorepo with multiple runnable apps (`apps/*`, `packages/*`), list each detected app and its URL as selectable options.
+
+Output the detected target briefly to chat first, then invoke `ask_question` in the same turn:
 
 ```text
-Step 1/3: Safety Fence & Environment Boundary
-Why this matters: Iamu drives a real headless browser with full agency. This boundary guarantees the agent stays confined to your local environment and never touches external services or triggers real-world side effects.
-
-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>
+Step 1a: Target URL & Dev Server
+  Detected URL:      <target_url, e.g. http://localhost:5173> (<currently running | not running>)
+  Dev Command:       <dev_command, e.g. pnpm dev>
 ```
 
-**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:**
     """
-    Step 1/3: Confirm Safety Fence & Dev Environment
+    Step 1a: Where should Iamu run browser tests against your app?
+
+    Detected URL: <target_url> (<currently running | not running>)
+    Dev Command:  <dev_command>
+    """
+  - **Options:**
+    1. "(Recommended) Use <target_url> (start with `<dev_command>`)"
+    2. "<Second detected workspace app URL + dev command, if monorepo; otherwise omit>"
+    3. "Use a different target URL or port"
+    4. "Change the dev startup command"
+- Otherwise (text-only/CLI):
+  Ask: `Where should Iamu test your app? Detected <target_url> (start command: <dev_command>). Reply to confirm, or give the right URL / dev command.`
+
+**If the user picks Option 3 or Option 4 (or writes in a correction):**
+- Ask for the exact URL (e.g. `http://localhost:4000` or a staging URL) and/or dev command, and wait for their reply before proceeding.
+
+**Persist immediately:**
+```bash
+iamu set testability \
+  --target "<confirmed_target_url>" \
+  --dev-command "<confirmed_dev_command>" \
+  --json
+```
 
-    Target URL:    <target_url>
-    Dev Command:   <dev_command>
-    Safe Fixtures: <detected seed scripts or mock handlers>
+#### Step 1b: How Tests Log In / Switch Users (1 question)
 
-    DO NOT WALK (Untestable Boundaries):
-    <detected external services, real SMS/email gateways, external submission portals>
+Next, ask **specifically** how the browser walker should log in or switch roles during tests. Never guess and save `--auth-strategy` or `--access` silently.
 
-    Confirm safety fence and dev environment?
+Output what you found in the codebase first, then invoke `ask_question` in the same turn:
+
+```text
+Step 1b: Test Login & User Switching
+  Detected Auth:     <What code inspection found, e.g. "Dev switcher via localStorage.sf_dev_persona", "Seeded test accounts in prisma/seed.ts (coordinator@site-a.test)", "Login form at /login (no seeded account found)", or "Public routes — no auth guard detected">
+```
+
+- If interactive user-prompt tools exist (`ask_question`, `ask_followup_question`), invoke it:
+  - **Question:**
+    """
+    Step 1b: How should Iamu log in or switch users when running tests?
+
+    Detected in codebase: <concise summary of detected auth guard / switcher / seed accounts>
     """
   - **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"
+    1. "(Recommended) <Specific mechanism detected in code, e.g. 'Use seeded test account (coordinator@site-a.test)' or 'Use dev persona switcher' or 'No login needed (public app)'>"
+    2. "Interactive login — open Chrome and let me log in manually before the test starts"
+    3. "Use specific test credentials or login instructions (I'll provide them)"
+    4. "No login needed (test public pages only)"
 - Otherwise (text-only/CLI):
-  Step 1/3: Safety Fence & Environment Boundary
-  Target URL:    <target_url>
-  Dev Command:   <dev_command>
-  Safe Fixtures: <detected seed scripts or mock handlers>
-  DO NOT WALK:   <detected external services>
+  Ask: `How should Iamu log in for tests? Detected: <summary>. Reply to confirm, say "interactive" to log in manually in Chrome, or tell me how to sign in.`
 
-  Safety boundaries look safe. I recommend saving fence and proceeding.
-  Proceeding to save safety fence — say "adjust" to change boundaries or "skip" to defer.
+**If the user picks Option 3 (or wants to specify how login works):**
+- Ask: *"Which test account, login URL, or dev bypass should the walker use? (For passwords or tokens, name the environment variable or dev seed rather than pasting production secrets.)"*
+- Wait for their answer before proceeding.
 
-**Action on confirmation (Option 1):**
-Persist the safety fence using `iamu set testability` (never invoke host file creation or edit tools):
+**Persist immediately:**
 ```bash
 iamu set testability \
-  --target "<target_url>" \
-  --dev-command "<dev_command>" \
   --auth-strategy "<dev_switcher | interactive | test_accounts | public>" \
-  [--access "<access mechanism>"] \
+  [--access "<confirmed login or user-switching instructions>"] \
+  --json
+```
+
+#### Step 1c: Untestable Boundaries (only when external side-effects exist)
+
+If code inspection found un-mocked external services or side-effect boundaries (e.g., Stripe checkout, real SMS/email gateways, external government submission portals, live production OAuth), ask one short question to confirm the `DO NOT WALK` fence:
+- Show the detected external boundaries and ask whether to block the walker from touching them (or add others).
+- If no external side-effect integrations exist, do not ask an extra question.
+
+Persist the complete testability summary body via `iamu set testability` (never invoke host file creation or edit tools):
+```bash
+iamu set testability \
+  --target "<confirmed_target_url>" \
+  --dev-command "<confirmed_dev_command>" \
+  --auth-strategy "<confirmed_auth_strategy>" \
+  [--access "<confirmed_access_mechanism>"] \
   [--harnesses "<detected harness 1>, <detected harness 2>"] \
   [--untestable-boundaries "<external dependency 1>, <external dependency 2>"] \
   --body "# Project Testability & Environment
 
 ## Target & Run Instructions
-- Command: <dev command>
-- Base URL: <target_url>
+- Command: <confirmed_dev_command>
+- Base URL: <confirmed_target_url>
 
 ## Auth & Access Boundary
-- <How a walker becomes this persona in dev or test mode>
+- <confirmed_access_mechanism>
 
 ## Reachable Surfaces
 - <List discovered routes/entry points>
@@ -162,6 +200,8 @@ Explain the purpose of project context: traditional tests only assert button cli
 
 Present the discovered domain and project description. Do NOT introduce or ask the user to approve personas or roles at this stage — personas are cast later when designing specific test journeys.
 
+**Treat codebase evidence as a hypothesis, not user approval.** Scan the repo so the user never has to repeat obvious facts, but if the codebase leaves a material gap (who the real primary users are, what high-stakes workflow matters most, or what real-world constraints apply), call out that gap explicitly in your question rather than inventing domain stakes.
+
 **Describe the product, not the environment you explored.** Persona drafting and the advisor read these fields and the description as the truth about the product. Write them as the product its people use in their real work. Leave out everything about how this copy runs, because Step 1 already recorded it in `testability.md`:
 - **Data and build:** seeded, mocked, fixture, sample or fake data; demo, prototype or staging status; where data is stored; frontend or backend architecture; dev servers.
 - **Seed numbers:** headcounts, named teams, stores or sites, and record counts taken from seed or fixture files describe the test data, not the customers. Say who the product is for in general terms ("small and mid-sized companies"). Rules and policies the code enforces (a notice period, an approval threshold) are product behaviour; keep them.
@@ -202,7 +242,7 @@ Host interactive tools (`ask_question`, `ask_followup_question`) render a modal
     Confirm project domain & description?
     """
   - **Options:**
-    1. "[Recommended] Project description is accurate — proceed to design first test"
+    1. "(Recommended) Project description is accurate — proceed to design first test"
     2. "Save project description only (skip scenario creation for now)"
     3. "Adjust domain or description"
 - Otherwise (text-only/CLI):
@@ -215,10 +255,12 @@ Host interactive tools (`ask_question`, `ask_followup_question`) render a modal
   Project Description:
   <1 cohesive paragraph>
 
-  Project description is accurate. I recommend proceeding to design your first test.
-  Proceeding to first test design — say "save only" or describe adjustments to change course.
+  Reply to confirm this project description, say "save only" to skip scenario creation, or tell me what to adjust.
+
+**If the user chooses Option 3 (Adjust domain or description):**
+- Ask what is inaccurate or missing, revise the domain fields and paragraph accordingly, and confirm before saving.
 
-**Action on confirmation (Option 1):**
+**Action on confirmation (Option 1 or after adjustment):**
 Persist the domain context using `iamu set context` (never invoke host file creation or edit tools). Put structured fields in frontmatter and the project description in the markdown body below the `---` via `--body`:
 ```bash
 iamu set context \
@@ -235,12 +277,25 @@ iamu set context \
 
 ### 4b. Design docs (quick; the user may skip it, you may not)
 
-The team's design docs are part of the product's context, like the domain. Iamu reads them wherever they are and never edits them on its own. Run `iamu design detect --json` and always show the user its result, even when every candidate looks unrelated. Never drop a candidate yourself: one in a spike, sandbox or example folder is listed with that note, unticked, and the user decides.
+The team's design docs are part of the product's context, like the domain—and **Iamu gets significantly sharper when it has them**. Without a design doc (`DESIGN.md`), Iamu's designer can only judge screens by generic UI craft; with a recorded `DESIGN.md`, every walkthrough checks your actual token roles, component contracts, form/loading/empty states, and contrast rules, links persona friction to broken rules, and proposes grounded `Before → After` edits when a rule hurts a user.
+
+Iamu reads design docs wherever they are and never edits them on its own. Run `iamu design detect --json` and always show the user its result, even when every candidate looks unrelated. Never drop a candidate yourself: one in a spike, sandbox or example folder is listed with that note, unticked, and the user decides.
 
 - **Found docs** (a `DESIGN.md` in any format, design-system, brand, voice or interaction docs, design sections of `CLAUDE.md` or `AGENTS.md` shown as `CLAUDE.md#<heading>`, a `PRODUCT.md`, token files, a component library): list them once, one line each (kind, path). Show a candidate with a `note` (anything in a sample, export, fixture or spike folder) with its note, unticked. Ask once whether to record them; the user may drop some or add others. On yes, `iamu design sources <paths…>` (in a monorepo, `--applies-to` with the URL prefix or the app's folder each doc covers).
 - **A legacy `iamu/design.md`** (`iamu design status --json` shows `legacy.doc` and no `legacy.migrated_at`): fold it into the same single question. Run `iamu design migrate --json` first, and offer three answers next to the files: **move it** to a plain `DESIGN.md` the team owns (`iamu design migrate --move-to DESIGN.md --apply`), **keep** `iamu/design.md` as it is (`iamu design migrate --apply`, which records the choice so it is not offered again), or **not now** (run nothing; it is offered again next time). Only an explicit "keep" runs `--apply` without a move.
-- **Nothing found:** say so in one line: "No design docs found. The designer reviews each run by general craft until you record some (`iamu-design`)."
-- **No written design doc** (detection found only tokens or components, or nothing, and no design doc is recorded): after the question above, or in its place when there was nothing to record, ask one question the user may skip: "There is no design doc yet. Shall I start one from your code? I fill in your tokens, components and contrast clashes, then ask you a few short questions (who it is for, how it should feel, an accessibility target, states, formats). **Yes** / **not now** / **no**." Yes: follow the `iamu-design` skill, mode E, then carry on with setup. No: run `iamu design template --decline`, so runs stop offering it. Not now: run nothing; it is offered again after the first run.
+- **Nothing found:** say so in one line: "No design docs found. The designer reviews each run by general craft until you record some (`iamu-design`) — strongly recommended so runs check your own tokens, components, and rules."
+- **No written design doc** (detection found only tokens or components, or nothing, and no design doc is recorded): after the question above, or in its place when there was nothing to record, explain in one sentence why a design doc makes Iamu much stronger (*"With a `DESIGN.md`, Iamu's designer checks your own tokens, components, states, and rules on every run instead of only general craft"*), and ask one question the user may skip:
+  - If interactive user-prompt tools exist (`ask_question`, `ask_followup_question`), invoke it:
+    - **Question:** "There is no `DESIGN.md` yet. Iamu gets much sharper with one (every run checks your own tokens, components, states, and rules instead of generic craft). Start one from your code now?"
+    - **Options:**
+      1. "(Recommended) Yes — start `DESIGN.md` from my code now (auto-extracts tokens, components, states & formats, then asks 2–3 quick intent questions)"
+      2. "Not now — finish setup first (keep reminding me to run `iamu-design`)"
+      3. "No — review by general craft only and stop offering `DESIGN.md`"
+  - Otherwise (text-only/CLI):
+    "There is no design doc yet, and Iamu gets much sharper with one (checking your own tokens, components, and rules on every run). Shall I start one from your code? I auto-extract your tokens, components, states, formats and contrast clashes from code, then ask 2–3 quick questions on feel and clash rules. **Yes** (recommended) / **not now** (keep recommending `iamu-design`) / **no**."
+  - **Yes:** follow the `iamu-design` skill, mode E, then carry on with setup.
+  - **Not now:** run nothing; it stays recommended at the end of setup, in `iamu status`, and after runs until a design doc is recorded.
+  - **No:** run `iamu design template --decline`, so runs stop offering it.
 
 Do not assess design docs here, and never write one without the user filling it in (mode E). Never block setup on this step.
 
@@ -250,16 +305,16 @@ Do not assess design docs here, and never write one without the user filling it
 
 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).
 
-Present the proposed test journey, including explicit **Auth Precondition Verification**.
+Split this into two quick questions: first agree on **who and what situation** to test (Step 3a), then confirm **which route and account** the walk starts with (Step 3b).
 
-**Dual-Surface Prompting (Sequencing Rule):**
-You MUST output the baseline test proposal to the chat stream FIRST. In the SAME turn, invoke `ask_question` with the full journey spec embedded in the `question` argument:
+#### Step 3a: Persona & Situation (Baseline Test Proposal)
 
-```text
-Step 3/3: Co-Design Your First Test Journey
-Why this matters: Validates whether a real human with specific operational pressures can complete a critical task without getting blocked or frustrated.
+Identify the top 2–3 high-stakes user workflows in the codebase. Lead with the strongest one in full detail as the recommended `Baseline Test Proposal`, and offer the other 1–2 discovered workflows as direct selectable options in the prompt so the user can switch flows in one click if they want to start elsewhere.
 
-Baseline Test Proposal (WYSIWGW Spec-Sheet):
+Output the proposed journey to the chat stream first, then invoke `ask_question` in the same turn:
+
+```text
+Step 3a: Baseline Test Proposal
   Capability:         <Capability Name> (<What staff can do in this area>)
   Persona:            <Name> (<Role / Title>)
                       • Reality: <Working context, physical habits, tenure, pressures>
@@ -267,40 +322,64 @@ Baseline Test Proposal (WYSIWGW Spec-Sheet):
   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.>"
 ```
 
-**CRITICAL: Embed Journey Spec in Interactive Prompt Modal:**
 - If interactive user-prompt tools exist (`ask_question`, `ask_followup_question`), invoke it:
   - **Question:**
     """
-    Step 3/3: Confirm Baseline Test Journey
+    Step 3a: Confirm First Test Scenario
 
-    Capability:        <Capability Name> (<What staff can do in this area>)
-    Persona:           <Name> (<Role / Title>) — Friction: <Diagnostic friction trigger>
-    Situation:         <Outline Title>
-    Core Tension:      <Core problem-space tension in X vs Y format>
-    Evaluation Check:  <Concrete binary yes/partial/no question for evaluator>
-    Walk Surface:      Entry: `<entry_path>` | Target: `<target_url>`
-    Auth Precondition: <Detected auth mechanism>
+    Persona:          <Name> (<Role / Title>) — Friction: <Diagnostic friction trigger>
+    Situation:        <Outline Title> (<Capability Name>)
+    Core Tension:     <Core problem-space tension in X vs Y format>
+    Evaluation Check: <Concrete binary yes/partial/no question for evaluator>
 
     WALKER BRIEF:
     "<2–3 sentence first-person test brief>"
 
-    Scaffold this baseline journey?
+    Test this persona and situation first?
     """
   - **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"
+    1. "(Recommended) Yes — test <Name> in '<Outline Title>'"
+    2. "Test another flow instead: <Candidate Flow 2 — Role & Situation from codebase>"
+    3. "Test a different user role or workflow (I'll describe it)"
+    4. "Skip scenario creation for now"
 - Otherwise (text-only/CLI):
-  I recommend Option 1: Scaffold journey with <detected auth mechanism>.
-  Proceeding to scaffold baseline journey — say "interactive login", "switch role", or "skip" to adjust.
+  Ask whether to use `<Name>` and `<Outline Title>`, pick `<Candidate Flow 2>`, or describe another role/situation to test first.
+
+**If Option 2 or Option 3 is chosen:** draft the persona and situation for the chosen flow and confirm before continuing to Step 3b.
+
+#### Step 3b: Confirm Starting Route & Persona Login (`entry_path` & `persona.access`)
+
+Now verify the exact landing route and user account for `<Name>` (using the login method established in Step 1b):
+
+```text
+Step 3b: Walk Surface & Persona Login
+  Walk Surface:       Entry: `<entry_path>` | Target: `<confirmed_target_url>`
+  Auth Precondition:  <Specific account/role for <Name> using Step 1b's auth strategy, e.g. "coordinator@site-a.test" or "Interactive manual login" or "Public">
+```
+
+- If interactive user-prompt tools exist (`ask_question`, `ask_followup_question`), invoke it:
+  - **Question:**
+    """
+    Step 3b: Confirm Starting Route & Account for <Name>
+
+    Starting URL:      <confirmed_target_url><entry_path> (entry path: `<entry_path>`)
+    Auth Precondition: <Specific account/role for <Name>, or "Interactive login" / "Public">
+
+    Where should <Name>'s walkthrough start, and as which user?
+    """
+  - **Options:**
+    1. "(Recommended) Start at `<entry_path>` (<confirmed_target_url><entry_path>) as <persona account or auth mode>"
+    2. "Start on a different route (e.g. `/` or `/login`)"
+    3. "Use a different account or role for <Name>"
+- Otherwise (text-only/CLI):
+  Ask: `Start <Name> at <confirmed_target_url><entry_path> as <account/auth>? Reply to confirm, or give the entry path / account to use.`
+
+**If Option 2 or Option 3 is chosen:** ask for the entry path (must start with `/`, e.g. `/dashboard`) or the account/role identifier for `<Name>`, and use their answer below.
 
-**Action on confirmation (Option 1 or Option 2):**
+**Scaffold & Persist Entities:**
 1. **Scaffold Primary Capability** (if not already existing):
    ```bash
    iamu new capability --name "<Capability Name>" --description "<What staff can do in this area>" --json
@@ -311,11 +390,11 @@ Baseline Test Proposal (WYSIWGW Spec-Sheet):
    ```
 3. **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
+   iamu new persona --name "<Name>" --role "<Role>" --disposition "<Disposition>" --body "<2-4 sentence narrative detailing technical habits, patience level, and specific friction triggers>" [--access "<confirmed-account-or-role>"] --json
    ```
 4. **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
+   iamu new scenario --name "<persona-slug>--<outline-slug>" --outline "<outline-slug>" --persona "<persona-slug>" --entry "<confirmed_entry_path>" --body "<Persona's first-person test brief describing what they intend to achieve>" --json
    ```
 5. **Validate all entities**:
    ```bash
@@ -343,7 +422,7 @@ Render the output:
   iamu/
   ├── testability.md       [safety fence active: <target_url>]
   ├── context.yml          [domain: <domain>]
-  ├── design/sources.json  [<N> design docs]   (only when recorded)
+  ├── design/sources.json  [<N> design docs]   (when recorded; if no DESIGN.md yet and not declined: [no DESIGN.md yet — run iamu-design to unlock project rule reviews])
   ├── personas/
   │   └── <persona-slug>.md
   ├── outlines/
@@ -357,9 +436,9 @@ Next step:
     iamu-run <persona-slug>--<outline-slug>
 
 Other commands when you're ready:
+• iamu-design   Create or record DESIGN.md from your code (strongly recommended if not set yet: makes every run check your own tokens, components, and rules instead of general craft)
 • iamu-new      Draft a scenario for a different product flow
 • iamu-propose  Brainstorm high-risk workflows and blind spots
-• iamu-design   Record the project's design docs, review a page, decide proposed edits
 • iamu doctor   Diagnose test environment and target health
 <If cloud_linked: true>
 • iamu sync     Sync completed runs and findings to Iamu Cloud