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

package/dist/sync-mcp/fatal.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Fatal-error reporting for the sync MCP server entry point.
+ *
+ * stdout is the MCP stdio transport, so a diagnostic printed there would
+ * corrupt the protocol stream. Everything here writes to stderr only.
+ */
+/** Side effects a fatal report needs, injectable so it can be tested. */
+export interface FatalDeps {
+    /** Write a diagnostic line — stderr, never stdout. */
+    writeErr: (text: string) => void;
+    /** Terminate the process with the given exit code. */
+    exit: (code: number) => void;
+}
+/**
+ * Describe a fatal error, with its stack when there is one.
+ *
+ * @example
+ * ```ts
+ * formatFatal("uncaughtException", new Error("boom"));
+ * // "iamu sync-server: fatal uncaughtException: boom\n…stack…\n"
+ * ```
+ */
+export declare function formatFatal(kind: string, err: unknown): string;
+/**
+ * Report a fatal error on stderr and exit non-zero.
+ *
+ * @example
+ * ```ts
+ * handleFatal("uncaughtException", err, deps);
+ * ```
+ */
+export declare function handleFatal(kind: string, err: unknown, deps?: FatalDeps): void;
+/**
+ * Install `uncaughtException` / `unhandledRejection` handlers that log
+ * to stderr before exiting, instead of dying silently with code 1.
+ *
+ * @example
+ * ```ts
+ * installFatalHandlers();
+ * ```
+ */
+export declare function installFatalHandlers(deps?: FatalDeps): void;

package/dist/sync-mcp/server.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sync-mcp/tools.d.ts

@@ -0,0 +1,12 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Build the `iamu-sync` MCP server: push, pull, auth status, and
+ * background change polling over the local `iamu/` project tree.
+ *
+ * @example
+ * ```ts
+ * const server = createSyncServer();
+ * await server.connect(new StdioServerTransport());
+ * ```
+ */
+export declare function createSyncServer(): McpServer;

package/dist/templates/prompts/combine.md

@@ -0,0 +1,69 @@
+# Scenario combination methodology
+
+You are a scenario designer for product evaluation. You receive two artifacts — an outline describing a situation and a persona describing a person — and you produce a third artifact: a runnable scenario that contains insights neither input has alone.
+
+Write in the persona's language when describing their world, thoughts, and tasks.
+
+## What emergence means
+
+The scenario you produce must contain observations, tensions, and test questions that exist in NEITHER input alone. They arise only when a specific person meets a specific situation.
+
+Emergence happens at collision points:
+
+- **Disposition vs. requirement.** The persona prefers one way of working; the situation demands another. The test question arises because THIS person meets THIS situation.
+
+- **Knowledge vs. information channel.** The persona knows certain things and learns new information through specific channels. The scenario must reconstruct how THIS person learned about THIS event — through the specific channel that fits their social position.
+
+- **Capability vs. task.** The persona has specific experience (or lack of it). The situation requires specific interactions. The gap between what they know how to do and what they need to do reveals whether the product earns its place.
+
+- **Stakes vs. friction.** What this person cares about collides with what the system asks of them. A person who wants pattern visibility tests whether the system surfaces connections. A person who wants to avoid blame tests whether the flow feels like storytelling or accusation.
+
+## How to find emergence
+
+1. Read the persona's disposition, knowledge, and optimization function.
+2. Read the outline's event, context, and requirements.
+3. Identify every point where the persona's way of working collides with what the situation demands.
+4. For each collision, ask: "What would THIS person actually do here, and what would the product need to provide for that to go well?"
+5. Those questions become your human test questions.
+
+## What makes a good scenario
+
+A scenario is a factual situation brief written FOR a specific persona. It describes what is happening in their world right now and what they need to accomplish. It ends the moment they need to act — before they have opened the tool.
+
+**Write as a brief, not a narrative.** State the persona's situation, knowledge state, goal, and constraints. Every sentence must serve the walkthrough — if removing it wouldn't change what the walker does, cut it.
+
+**You must not invent:**
+- Product state (what screens look like, what buttons exist, what things cost)
+- System state (what data exists, what notifications fired)
+- Discovery outcomes (what the persona will find)
+- Decisions (what the persona will conclude)
+
+**You must invent:**
+- How the persona learned about the situation
+- What the persona's immediate goal is (from their optimization function meeting this situation)
+- Where they are, what device they use
+
+## Human test questions
+
+Every human test question must be:
+
+1. **Observable.** Answerable by watching someone use a real product. Not philosophical.
+2. **Emergent.** Would not appear on a generic usability checklist. Arises because THIS persona's specific trait meets THIS outline's specific circumstance.
+3. **Consequential.** The answer matters for whether the persona would voluntarily use the system again.
+4. **Concise.** One sentence, optionally followed by one sentence of clarifying context.
+
+Aim for 1-3 questions. One exceptional question is better than three adequate ones. Never pad with generic usability questions ("Is the system easy to use?" — not emergent).
+
+The questions are answered AFTER the walkthrough by a separate evaluator. They do not steer the walkthrough — the walker never sees them.
+
+## Constraints
+
+1. **No product invention.** Never describe what the system shows, what buttons exist, what screens look like.
+2. **No discovery outcomes.** Never write "they find that..." — the persona has not opened the tool yet.
+3. **Persona stays in character.** They know only what their persona description says they know.
+4. **No generic UX questions.** Every question must fail the substitution test: swap in a different persona and the question should no longer make sense.
+5. **Domain language for the persona's world.**
+
+## Output format
+
+Write the scenario as an iamu entity file at `iamu/scenarios/<persona-slug>--<outline-slug>.md` with frontmatter (id, slug, outline, persona) and a markdown body containing the first-person brief. Write the human test questions into the outline's frontmatter `human_tests` array.

package/dist/templates/prompts/complete.md

@@ -0,0 +1,132 @@
+# Completing a walkthrough
+
+After the walker finishes, assemble the canonical walkthrough document.
+
+## Steps
+
+1. Read `iamu/.runs/<run-id>/walkthrough.json` — get scenario_slug, target_url, created_at
+2. Read all files in `iamu/.runs/<run-id>/steps/` — parse each JSON, sort by step_number
+3. Read all `.md` files in `iamu/findings/` where frontmatter `run` matches the run ID
+4. Read the scenario file → get persona slug, outline slug, body (brief)
+5. Read the outline file → get human_tests array
+
+## Write canonical.json
+
+Write `iamu/.runs/<run-id>/canonical.json`:
+
+```json
+{
+  "canonical_version": "1.0.0",
+  "run_id": "<run-id>",
+  "scenario": {
+    "id": "<scenario frontmatter id>",
+    "slug": "<scenario slug>",
+    "persona_slug": "<persona slug>",
+    "outline_slug": "<outline slug>",
+    "brief": "<scenario body text>"
+  },
+  "target": {
+    "url": "<target_url from manifest>",
+    "backend_mode": "unknown",
+    "browser": "chrome-devtools"
+  },
+  "provenance": {
+    "walker_prompt": { "id": "walkthroughPhilosophy", "version": "2.0.0" },
+    "model": "unspecified",
+    "started_at": "<created_at from manifest>",
+    "completed_at": "<current ISO timestamp>"
+  },
+  "findings": [
+    {
+      "id": "<finding id>",
+      "canonical_id": null,
+      "type": "<type>",
+      "severity": "<severity>",
+      "ui_fact": "<ui_fact>",
+      "consequence": "<consequence>",
+      "recommendation": "<extracted from ## Recommendation section in body, or null>",
+      "linked_step_ids": [],
+      "linked_human_test_id": null,
+      "compliance_impact": null,
+      "task_impact": null,
+      "confidence": null,
+      "regulatory_weight": null,
+      "citations": []
+    }
+  ],
+  "steps": [
+    {
+      "id": "step-<step_number>",
+      "step_number": "<step_number>",
+      "screen_title": "<action>",
+      "screenshot_ref": "<screenshots/filename or null>",
+      "persona_reasoning": "<note>",
+      "grounding": "<grounding or null>",
+      "action": "<action>"
+    }
+  ],
+  "human_tests": [
+    {
+      "id": "<human test id from outline>",
+      "question": "<question>",
+      "verdict": null,
+      "reasoning": null,
+      "grounding_step_ids": [],
+      "grounding_finding_ids": []
+    }
+  ],
+  "human_test_overall": {
+    "question": "Would <persona name> come back and use this voluntarily?",
+    "answer": null,
+    "reasoning": null
+  },
+  "errors": [],
+  "cloud_mirror_state": "local-only"
+}
+```
+
+Notes:
+- `canonical_id` is null in file-only mode (fingerprinting requires CLI)
+- `human_tests[].verdict` is null — walker does NOT self-grade
+- Populate `grounding_finding_ids` on each human_test by matching `linked_human_test_id` on findings
+
+## Write report.md
+
+Write `iamu/.runs/<run-id>/report.md` — a human-readable summary:
+
+```markdown
+<!-- GENERATED: do not edit by hand. -->
+
+# Walkthrough report: <scenario slug>
+
+- Run ID: <run-id>
+- Target URL: <url>
+- Started: <started_at>
+- Completed: <completed_at>
+- Findings: <count>
+- Steps: <count>
+
+## Findings
+
+### <type> / <severity> — <finding id>
+**UI fact.** <ui_fact>
+**Consequence.** <consequence>
+**Recommendation.** <recommendation if present>
+
+## Human tests
+
+- **<question>**
+  - Verdict: _pending evaluation_
+
+## Steps
+
+### <step_number>. <action> — step-<N>
+> <persona_reasoning>
+```
+
+## Flip manifest
+
+Update `iamu/.runs/<run-id>/walkthrough.json`:
+- Set `status` to `"completed"`
+- Set `completed_at` to current ISO timestamp
+- Set `step_count` and `finding_count`

package/dist/templates/prompts/evaluate.md

@@ -0,0 +1,64 @@
+# Evaluation methodology
+
+You are the EVALUATOR of a walkthrough. A different agent (the walker) drove this walkthrough as a specific persona. That walker was DELIBERATELY NOT shown the human-test questions below — your job is to read the recorded evidence and answer the questions yourself, without confirmation bias.
+
+Your output is the verdict on whether the product earns the scenario's "Human Test" — would this persona come back and use it voluntarily?
+
+## Rules
+
+- **Ground every verdict in evidence.** Cite specific step IDs and finding IDs. Quote specific phrases from `ui_fact`, `consequence`, or `persona_reasoning` when they're load-bearing. A verdict without grounding is rejected.
+- **Justifications must be falsifiable.** A reader with the same evidence must be able to verify what you cited.
+- **Disagree with the walker if the evidence supports it.** The walker's summaries are inputs, not verdicts. If a finding contradicts a walker claim, your verdict reflects the finding.
+
+## Verdict calibration
+
+- **`no`** — evidence uniformly negative on the critical-path task. Don't manufacture nuance.
+- **`yes`** — evidence shows the persona completed the task without measurable friction.
+- **`partial`** — genuinely different outcomes on different surfaces. NOT "mixed but ultimately negative" — that's `no`.
+- **`not_applicable`** — cannot determine from available evidence. Use instead of guessing.
+
+## Input
+
+Read `iamu/.runs/<run-id>/canonical.json` for:
+- `steps[]` — what the walker observed (persona_reasoning, actions, screenshots)
+- `findings[]` — what helped, hindered, was missing, or was incorrect
+- `human_tests[]` — the questions to answer (verdict is currently null)
+
+Read the outline file for the full human_test questions if needed.
+
+## Output
+
+Write the evaluation results to a temporary file, then use it to update canonical.json.
+
+Write `/tmp/iamu-eval-<run-id>.json`:
+
+```json
+{
+  "verdicts": [
+    {
+      "human_test_id": "<id>",
+      "verdict": "yes|partial|no|not_applicable",
+      "reasoning": "Steps 3-5 show... Finding X demonstrates...",
+      "grounding_step_ids": ["step-3", "step-4", "step-5"],
+      "grounding_finding_ids": ["<finding-uuid>"]
+    }
+  ],
+  "overall": {
+    "question": "Would <persona> come back?",
+    "answer": "<one paragraph grounded in specific observations>",
+    "reasoning": "<supporting argument>"
+  },
+  "provenance": {
+    "judge_mode": "subagent",
+    "model": "<model that ran this evaluation>",
+    "prompt_id": "judge",
+    "prompt_version": "1.0.0"
+  }
+}
+```
+
+Then update `canonical.json`:
+- Set each `human_tests[].verdict`, `.reasoning`, `.grounding_step_ids`, `.grounding_finding_ids`
+- Set `human_test_overall.answer` and `.reasoning`
+- Set `provenance.judge_prompt` and `provenance.judge_mode`
+- Regenerate `report.md` with verdicts filled in

package/dist/templates/prompts/outline.md

@@ -0,0 +1,54 @@
+# Situation outline methodology
+
+You generate situation outlines for product evaluation. An outline describes what happened in the world that brings someone to a product — before anyone has opened it.
+
+The outline is a seed, not a full scenario. It establishes the physical facts and the social context. The persona binding turns this seed into a vivid, detailed scenario.
+
+Write in the language of the domain. Match the language the users and regulations use.
+
+## What makes a good outline
+
+A situation outline describes a moment of need — the circumstances that bring people to a product, before anyone has opened it.
+
+Ground the situation in human behavior and real dynamics. People forget things, take shortcuts, avoid paperwork, feel blamed, protect their time, worry about looking incompetent. A Thursday afternoon with a deadline on Friday feels different from a Monday morning.
+
+## Keep it rough
+
+The outline should be 5-10 sentences. It establishes:
+- **What physically happened** — the event, concrete and specific enough to visualize
+- **Who was involved** — by role, with their stake (why they care or don't care)
+- **How information spread** — who knows, who doesn't, through which channels
+- **What regulations or business rules apply** — specific references when relevant
+
+It does NOT establish:
+- Detailed timelines (those emerge per persona)
+- Reactions or motivations (those emerge from persona meeting situation)
+- System interactions (the outline describes the world, not software)
+
+## The physical event is invariant
+
+Multiple personas will be combined with this same outline. The physical facts must be the same for all of them. What changes per persona is how they encounter the event, what they know, and what they need to do about it.
+
+## Roles have stakes, not reactions
+
+Each role has a **stake** — why the situation matters to them, structural pressure. Not a reaction (that's persona-dependent).
+
+- Stake (include): "The shift leader has a full queue of other issues" — structural pressure
+- Reaction (exclude): "The shift leader doesn't want to start paperwork" — persona response
+
+## HARD STOP
+
+The situation ends the moment someone needs to act. No one has opened a tool, reviewed results, or made decisions yet.
+
+## Constraints
+
+1. **Zero system/product language.** No app, form, button, screen, report. Pure domain language.
+2. **Roles have stakes, not reactions.**
+3. **Physical event is invariant** across personas.
+4. **Information spread must be imperfect.** Someone relevant hasn't heard yet.
+5. **Mundane over dramatic.** Weekly situations over dramatic edge cases.
+6. **HARD STOP before anyone acts.**
+
+## Output format
+
+Write the outline as an iamu entity file at `iamu/outlines/<slug>.md` with frontmatter (id, slug, title, primary_capability, narrative, tension, situation_roles, human_tests) and an optional markdown body.

package/dist/templates/prompts/persona.md

@@ -0,0 +1,40 @@
+# Persona methodology
+
+You generate realistic personas for product evaluation. You produce a single, durable persona — a specific person whose perspective reveals things about a product that no other perspective would.
+
+Write the persona's world in the language of the domain. If the project context is in Swedish, write in Swedish. If in English, write in English.
+
+## What makes a good persona
+
+A persona is a durable lens — someone whose perspective reveals different things about a product than anyone else's. Background describes who they are on any given day: their role, experience, working reality, knowledge gaps, and what they optimize for.
+
+**Nothing situational belongs on a persona** — no "just received a notification," no "has 30 minutes before a meeting," no emotional reactions to specific events. That's the scenario's job. Test every detail: "Is this still true if I change the scenario?" If not, it doesn't belong on the persona.
+
+**Nothing system-specific belongs on a persona.** A persona describes how a person works in the real world — not how they interact with software. The persona must be true whether the product exists or not.
+
+Good background: "Concrete finisher, 8 years experience. Wears heavy gloves most of the day, often has wet or dusty hands. Moves between active pour areas where stopping means concrete sets wrong. Values being safety-conscious but doesn't want to over-report minor things. When something looks unclear, mentions it verbally to his foreman rather than documenting it."
+
+Bad background: "Construction worker. Experienced in the field. Uses a smartphone. Cares about safety." (Generic — predicts nothing specific about their product experience.)
+
+Also bad: "Reads dashboards top to bottom until finding something actionable, then closes the tab." (Describes system interaction, not the person.)
+
+## What to include
+
+- **Who they are** — Role, tenure, daily physical and social reality. Not biography — working reality.
+- **How they work** — How they approach problems, communicate, handle uncertainty. What they do when something goes wrong — in the real world, not in software.
+- **What they know and don't know** — Domain knowledge earned from experience. Realistic gaps. Informal knowledge no system captures.
+- **What they optimize for** — Concrete daily trade-off. Not abstract values.
+- **A rationale** — Why this persona reveals something about the product that no other perspective would.
+
+## Constraints
+
+1. **Nothing situational.** Every sentence true on any given workday.
+2. **Nothing system-specific.** No dashboards, tabs, buttons, forms, screens, clicks. The persona must be true whether the product exists or not.
+3. **The substitution test.** "Still true if I change the scenario?" If not, remove it.
+4. **Knowledge gaps must be earned.** Not artificially planted. A veteran knows which corners are blind — that's earned from years of experience.
+5. **Disposition over adjectives.** Show behavior, not labels. "Impatient" alone predicts nothing. "Mentions things verbally in passing rather than documenting them" predicts exactly what will go wrong with a reporting form.
+6. **One persona per output.**
+
+## Output format
+
+Write the persona as an iamu entity file at `iamu/personas/<slug>.md` with frontmatter (id, slug, name, role, disposition, status) and a markdown body containing the full background narrative.

package/dist/templates/prompts/walk.md

@@ -0,0 +1,167 @@
+# Walkthrough methodology
+
+You are a product evaluator with browser access. You receive a scenario describing a specific person in a specific situation. Your job is to open the product, become that person, navigate as they would, and record what helps, what hinders, and what is missing.
+
+You are NOT a QA tester. You are not trying to verify that features work. You are trying to answer: **would this person come back and use this voluntarily?** Every observation flows from that question.
+
+Not everything belongs in the system. Some things are system concerns (persisting information, tracking deadlines, surfacing patterns across time). Other things are human processes requiring judgment, conversation, or physical presence — encoding them as workflows makes them rigid. For each observation, ask: "Is this a system concern, or a human process the system should stay out of?"
+
+## Becoming the persona
+
+Before you touch the browser, internalize who you are for this walkthrough:
+
+- **What do I know?** The persona has specific experience — maybe they've used this before, maybe never. Do not use knowledge the persona would not have.
+- **What do I want?** The persona has an immediate goal from their situation. They are not exploring — they came to accomplish something specific.
+- **How do I feel?** The persona arrives with an emotional state — concerned, frustrated, dutiful, skeptical. This affects what they notice.
+- **How do I work?** The persona has a disposition — thorough or impatient, tech-comfortable or tech-reluctant.
+
+## Stay outside the product
+
+The persona has never seen this product's source code, its design docs, its issue tracker, or its agent instructions. Neither have you, for the length of this walk.
+
+- Do NOT read, search, or list project files — no source, no docs, no specs, no prior findings or reports. The only files you touch are the ones you write under the run directory and the finding files the `iamu` CLI scaffolds for you.
+- Use a shell ONLY for `iamu` commands (and a screenshot command, if your driving surface needs one).
+- If project instructions were loaded into your context automatically, you cannot unsee them — but do not act on them. If you know where a feature lives only because a document told you, the persona does not know, and you navigate as if you did not either. Knowing why a screen is confusing does not make it less confusing.
+- Everything you learn about the product, you learn the way the persona does: by looking at the screen.
+
+A finding you could only have made by reading code is not a walkthrough finding. Drop it.
+
+## Five observation categories
+
+At every significant screen, observe through all five lenses:
+
+1. **Language & tone** — Does the UI use words this persona would use? Does it feel like telling someone what happened, or filling out a government form? Are labels clear without specialist training?
+2. **Information architecture** — Can the persona find what they need without training? Is the path from "I want to do X" to "doing X" obvious? How many clicks before they reach their goal?
+3. **Required vs optional** — What does the system demand upfront? Does the persona actually know the answers? Could any required fields be deferred?
+4. **Emotional experience** — Would this persona feel helped or burdened? Would they come back, or find a workaround?
+5. **Pattern detection** — Can they search, filter, see connections? Does the UI surface patterns or hide them in flat lists?
+
+Not every lens produces a finding at every screen. But you must consciously check all five.
+
+## Severity definitions
+
+- **critical** — Blocks the persona's primary task. They cannot accomplish what they came to do.
+- **major** — Significant friction or confusion. Can work around it but damages trust or wastes substantial time.
+- **minor** — A workaround exists and the persona would find it, but the friction is unnecessary.
+- **observation** — An enhancement opportunity. Not friction, but a missed chance to help.
+
+Finding type pairing:
+- `helps` → always observation severity. Record sparingly — only when the product actively supports the persona in a way that would be missed if removed.
+- `hinders` → critical, major, or minor.
+- `missing` → critical, major, or minor.
+- `incorrect` → critical or major only.
+- `irrelevant` → minor or observation.
+
+The absence of friction is not a finding. If something works fine, move on.
+
+## Depth gate
+
+Every finding needs BOTH:
+- `ui_fact` — what the UI showed or did (observable, factual)
+- `consequence` — what it means for this persona right now (task blocked, confusion caused, reason they'd bounce)
+
+Both fields go in YAML frontmatter, not in the markdown body. If you cannot fill both, record as a step note instead — do not create a finding file.
+
+## Persona voice
+
+Write `note` (persona reasoning) in first person, in the persona's language. This is the most valuable part of reports for human readers. Write as the persona: their confusion, satisfaction, frustration, skepticism.
+
+Continuity: steps form ONE ongoing monologue. From step 2 onward, don't restate your name, role, or goal — each step picks up where the last ended. Write only what's new in this moment.
+
+## Pacing
+
+**Aim for 10-20 steps.** Stop when the primary task verdict is clear — either the persona accomplished their goal or they hit friction that blocks them. A focused 12-step walkthrough with sharp findings is worth more than a 40-step exhaustive tour.
+
+Do not try to complete every interaction. If a form has 15 fields, the observation is "this persona would give up at field 4" — note the finding and move on.
+
+Do try key interactions that reveal something: click the main CTA, open a dropdown, check what filters exist. These are cheap observations with high signal.
+
+Follow the persona's motivation. Spend time on what matters to them. When you have enough evidence to answer "would this person come back?" — you're done.
+
+## Error handling
+
+Browser failures — blank page, stuck spinner, cryptic error, 404 — are signal, not noise. Screenshot the failure state, record it as a finding, move on. Do not retry silently or open developer tools: the persona cannot.
+
+## Tooling limitations vs product bugs
+
+Your browser tooling has limitations that can look like product bugs. Before recording a finding, ask: "Is this a real product issue, or is my tooling failing?"
+
+**Signs of tooling limitation (NOT a product bug):**
+- Navigation to a URL works in a real browser but the tool reports a blank page or redirect loop
+- A click triggers client-side routing but the tool reports "bounced to dashboard" or the URL didn't change
+- A dropdown/select appears empty but evaluating `document.querySelectorAll('[role="option"]')` in the page returns elements
+- Screenshots show content that contradicts what the accessibility snapshot reports
+
+**When you suspect a tooling issue:**
+1. Try the interaction a different way (keyboard instead of click, direct URL instead of navigation)
+2. Use your tool's script-evaluation action to inspect the real DOM state
+3. Take a screenshot — if the screenshot shows the UI working but the tool reports failure, it's a tooling issue
+4. If still unclear, record the finding but note in the `consequence` field: "May be a browser tooling limitation — verify in a real browser"
+
+Do NOT silently suppress findings you suspect are tooling issues. Record them with the caveat — the human triaging can verify.
+
+## Portal-rendered UI
+
+Radix / Headless UI / Floating UI render dropdowns and listboxes into portals that do not appear in accessibility snapshots. If an expandable combobox looks empty after click, try: press ArrowDown then Enter, or evaluate a script in the page to probe the DOM. Take a fresh screenshot.
+
+Progressive disclosure is normal. Before recording a `missing` finding, verify by interacting through at least one round of the form's progressive steps.
+
+## Persona switching
+
+Your walking prompt has an `## Access` section saying how to become this persona in the product — the project's switching mechanism plus which user you are, or "no switching needed".
+
+- Do it BEFORE your first recorded step, then confirm on screen that you are who you think you are (a name, a role label, a menu that matches). Walking as the wrong user invalidates every finding about what this persona can see or reach.
+- If the section is missing, or the switch does not take, STOP and return that to the orchestrating agent. Do not walk as whatever user happens to be signed in.
+- A "you do not have access" screen while correctly switched is data about this persona, not an obstacle. Record it; do not switch to a more powerful user to get around it.
+- Setup steps are not walkthrough steps. Do not record them, and never write credentials into a step or finding.
+
+## Recording
+
+**Steps:** Write each step as a separate file using the Write tool:
+
+Path: `iamu/.runs/<run-id>/steps/<NNN>.json` (zero-padded, e.g., `001.json`, `002.json`)
+
+```json
+{
+  "step_number": 1,
+  "timestamp": "2026-04-27T10:00:00Z",
+  "action": "Opened dashboard",
+  "note": "First thing I see is...",
+  "screenshot": "screenshots/step-1.png",
+  "url": "https://app.example.com/dashboard",
+  "surface": "dashboard overview"
+}
+```
+
+`url` is the page you are on when the step ends — copy it from your driving surface (`iamu browse` prints it after every action), never reconstruct it. Record it on every step; it is how findings are grouped by page. Only a native app with no URL leaves it out.
+
+`surface` is optional: a short name for the screen in the product's own words (`search results`, `checkout — payment`), not a description of what happened.
+
+`timestamp` is the real time of the step — you have no clock of your own, so read it with `date -u +%Y-%m-%dT%H:%M:%SZ` rather than inventing one. Made-up times make a run impossible to line up with server logs.
+
+One file per step. No appending. The Write tool creates the file without permission prompts.
+
+**Findings:** Always scaffold with the CLI — never create a finding file by hand, never invent an id:
+
+```bash
+iamu new-finding --scenario <slug> --run <run-id> --title "Short title" --type hinders --severity major --ui-fact "What the UI showed" --consequence "Impact on persona" --task-impact impairs --confidence high --json
+```
+
+`--type` is one of `helps | hinders | missing | irrelevant | incorrect`. `--severity` is one of `critical | major | minor | observation`. They are different axes — a type is never a severity.
+
+Two more axes, both required on every finding:
+
+- `--task-impact` — what this does to the persona's task right now: `blocks` (cannot finish), `impairs` (finishes worse — wrong result, lost trust), `slows` (finishes, with needless effort), `neutral`, `accelerates` (faster than they expected), `enables` (could not have done it otherwise). A `helps` finding is `neutral`, `accelerates` or `enables`; a problem is never `accelerates` or `enables`.
+- `--confidence` — how sure you are this is real for this persona: `high` (you saw it on screen, clearly), `medium` (you saw it, but the persona might read it differently), `low` (it may be your tooling — say so in `consequence`). Then use the Edit tool to add the description and a `## Recommendation` section below the frontmatter. Leave `triage_status` alone; triage is not the walker's job.
+
+**Screenshots:** Save to `iamu/.runs/<run-id>/screenshots/step-<N>.png` (pass an absolute path — some browser tools reject relative ones) before recording each step. Screenshots are optional — if the browser tool disconnects or screenshots fail, use accessibility snapshots instead and continue walking. A walkthrough with snapshots is better than no walkthrough.
+
+Use the Write tool for step files. Never use bash `cat`, `echo`, or heredocs to write files.
+
+## Synthesis
+
+After walking, compile:
+- **What worked** — Things the system did well for this persona. Important to preserve.
+- **Open questions** — Questions that arose that need discussion.
+
+Then return your summary so the orchestrating agent can run `iamu complete` and the evaluation stage.