Roadmap, rest: studio, walkthroughs, the design step held by the instrument, blind pairwise preference, a second ticket

.claude/skills/uxcli/SKILL.md

@@ -65,6 +65,12 @@ Use this bounded path for ordinary UI work. Read a reference only where a step n
    Then read what the person goes through: `npx -y @junixlabs/uxcli experience --page` — steps, clicks,
    typing, scrolls, waits and a keystroke-level estimate per journey, each finding pinned on the step's
    screenshot, and what moved since the walk before. Report each finding in its words; they never block.
+   To see the whole board — every journey's screens as drawn, as built and per version, findings
+   pinned — run `npx -y @junixlabs/uxcli studio --shot=.uxcli/studio/board.png` and look at the picture.
+   When a person has to pick a drawing or look at the work, tell them to open
+   `npx -y @junixlabs/uxcli studio --serve`: they pan and zoom it like a design file, choose a drawing or
+   ask for a redraw there, and it refreshes as you change files. Their choice lands in `pick.json` or
+   `revise.json`; read it from there.
 6. **Say done only at exit 0**, and say what was measured. Anything else, say what stands in the way.
    `references/before-done.md` is the full sequence and the list of what exit 0 does not cover.
 
@@ -80,6 +86,7 @@ Before you design or change a screen, you read `uxcli context show` for the jour
 | `unmeasurable` | say what could not be measured and why; do not retry until it passes |
 | `not-applicable` | nothing to do here; the condition did not occur |
 | `blocked` (exit 1) | no verdict was reached; read the reason and the `fix` line (identity, fixture, reach) and report it; this is not a UX fail |
+| `DESIGN STEP OPEN` (exit 3) | the walk measured clean, but the policy holds this project to a design step and a walked screen has no drawing, review or pick; draw and review it, then ask the person to pick — never write a pick yourself without their say-so. Not done |
 | exit 0 | no probe found a fail; report what ran and what it did not look at |
 
 ## Invariants
@@ -101,7 +108,9 @@ Before you design or change a screen, you read `uxcli context show` for the jour
 | `references/journey.md` | the card says no journey, or a flow has changed shape: states as signals, hooks, workflows |
 | `references/mockups.md` | a screen the journey names has no mockup or no pick: variants, hooks, `pick.json` |
 | `references/understand.md` | the card says no understanding, or an insight the screen leans on is missing or a hypothesis |
+| `references/walkthrough.md` | a journey was walked and you need to know whether a person could follow it: the four questions at every step, as one of the project's actors |
 | `references/versions.md` | a walk showed something worth changing: naming versions, a redesign proposal with evidence, comparing two versions |
+| `references/prefer.md` | two versions exist and someone asks which people would rather use: a blind pairwise study you prepare and people judge |
 | `references/research.md` | you do not know the product's field from sources yet: where to look, what to come back with, how to write it down |
 | `templates/<id>.md` | the product is a kind uxcli has a template for — `workspace`, `shop`, `landing`: screens and their lens, journeys to walk, what to research |
 | `lenses/<kind>.md` | before you draw or change a screen: the checklist for its kind of UI — `marketing`, `content`, `data`, `workspace`, `shop`, `transaction` |

.claude/skills/uxcli/references/before-done.md

@@ -10,6 +10,8 @@ ends with a word you may or may not say.
 
 `uxcli run` exits 0 when no probe reports `fail`, 2 when at least one does, 1 when it could not run. You say done only after a run you made yourself, on the final state of the files, exited 0. A `fail` blocks the word done until it is fixed and re-measured, or until the human has seen it and decided; in that case you report the fail, you do not report done. A `finding` is not a pass: it is a would-be fail from a probe whose method is not yet validated. Name it as a finding and say what it says; never fold it into "passes" or "no issues". `unmeasurable` and `not-applicable` are not passes either.
 
+A journey walk can also exit 3 (`DESIGN STEP OPEN`): it found no fail, but the project's policy holds the work to a design step (`project.design`) that a walked screen has not had — two variants and a lens review, or under `picked` a person's pick. Exit 3 is not a verdict on the interface; it is the work not being finished, and it blocks the word done like any exit that is not 0.
+
 ## What exit 0 does not cover
 
 `uxcli run <url>` runs five probes, and only these: `focus-visible` (2.4.7), `contrast` (1.4.3),

.claude/skills/uxcli/references/mockups.md

@@ -4,6 +4,10 @@ Read when: `uxcli init` says a screen has no mockup or no pick, or `context show
 nobody has drawn. A mockup is a page you draw; a pick is a person's choice among your drawings; the
 picked variant is what you build.
 
+A project can make this step part of done: with `project.design: drawn` in its policy, a journey walk
+exits 3 while a screen it passed through has fewer than two drawings or no complete lens review; with
+`picked`, also until a person has picked. Drawing and reviewing are yours to do; the pick is not.
+
 ## What a mockup is
 
 One static HTML file per variant of a screen, at `.uxcli/mockups/<state>/<variant>.html`, where

.claude/skills/uxcli/references/prefer.md

@@ -0,0 +1,32 @@
+# prefer — a person's eye on two versions, blind
+
+Read when: two versions of a screen exist (two drawings, two builds, before and after a redesign) and
+someone wants to know which one people would rather use. You prepare the study; people judge it.
+
+uxcli's probes and walks say what a page did. They do not say which of two pages a person prefers.
+That takes people who look at both without knowing which is which. `uxcli prefer` makes that cheap to
+run and hard to bias: the pictures are renamed so nothing names a group, each judge sees the pairs in
+their own order with the sides swapped by their own seed, and the side a group sat on is recorded by
+the server, never by the page.
+
+## The sequence
+
+1. Put the pictures in two folders, the same screen under the same file name in each — for example
+   the `-before.png` of a step from two walks, or the `.shots/` of two variants.
+2. `uxcli prefer make <study> --a=<folder> --b=<folder> [--question="…"]` writes
+   `.uxcli/preferences/<study>/study.json` and `img/`. A study is never rewritten once made; a new
+   question is a new study.
+3. Each judge — a designer, a user of the product — runs
+   `uxcli prefer serve <study> --judge=<their name>` and answers every pair: left, right or cannot
+   tell, and why. Their answers land in `judgments/<judge>.json`.
+4. `uxcli prefer tally <study>` counts wins per group and a two-sided sign test with ties set aside;
+   `--json` carries every reason.
+
+## What is yours, and what is not
+
+- You may make the study, start the page for a judge, and read the tally out in its words.
+- You are never a judge. A judgment signed by anything but a person is refused, on anybody's say-so:
+  the study exists to put an eye other than yours on the work.
+- Do not choose which pictures go in after seeing a tally, and do not drop a judge whose answers you
+  do not like. Report the tally with its numbers: who judged, how many answers, the split, p.
+- A preference is not a verdict. Fewer than six decided answers mean little whatever the split.

.claude/skills/uxcli/references/walkthrough.md

@@ -0,0 +1,35 @@
+# walkthrough — the four questions at every step
+
+Read when: a journey has been walked and you need to know whether a person could follow it, not only
+whether the page is built right. The metrics say how far, how long, how many; the walkthrough says
+whether the person would know what to do. It is the method of Wharton, Rieman, Lewis & Polson (1994).
+
+```bash
+npx -y @junixlabs/uxcli walkthrough <journey> --as=<actor> --for=<person running you>   # one file per walk and persona
+npx -y @junixlabs/uxcli walkthrough check
+```
+
+`--as` names an actor under `.uxcli/understanding/actors/`. Answer as that person — their contexts,
+their pains, what is still unknown about them — never as a persona you imagined. Without `--as` you
+answer as a first-time user of this screen.
+
+## At each step, looking at its screenshot
+
+| Question | Ask |
+|---|---|
+| `goal` | Is this what the person is trying to do at this point? |
+| `notice` | Will they notice that the correct action is available? |
+| `associate` | Will they connect that action with the effect they want? |
+| `progress` | After the action, will they see that they are getting closer? |
+
+Answer `yes`, `no` or `unsure`, with `why` (what on the screenshot makes it so) and, for `no` or
+`unsure`, `where` (the element or region). Open the screenshot the card names; do not answer from the
+source or from what you built.
+
+## What check does
+
+It refuses a step left out, an answer without why, a no without where, an actor nobody wrote, an
+agent answering on nobody's behalf, and a `yes` the walk contradicts: `notice` where the control was
+measured below the fold, `progress` where the step did not arrive or the screen took past a second to
+settle. Every `no` and `unsure` is a finding in your words. None of it is a fail, and nobody was watched:
+report findings as what a careful reviewer saw, not as what users do.

.claude/skills/uxcli/templates/content.md

@@ -0,0 +1,83 @@
+# Docs and help centre — the `content` template
+
+Documentation, help centres, knowledge bases and publications: people arrive with a question and leave when it is answered.
+
+A template is where research starts, not what it found. Nothing below is a fact about this product's users: the screens and journeys are what products of this kind usually have, and every question is yours to answer from a source before it becomes an insight. `uxcli template apply content` writes the actor questions into `.uxcli/understanding/actors/`; `references/research.md` in this skill is how to answer them.
+
+## Who uses it
+
+### `question_seeker`
+
+Someone in the middle of a task who hit a problem and came to find the answer.
+
+- Which questions bring people here most often, in the words they type into search?
+- Where do they arrive from: a search engine, a link inside the product, an error message, a colleague?
+- Do they read the page or scan it for one step, a code sample or a setting name?
+- What do they do when the page does not answer them: search again, contact support, give up?
+- Which device and which language do they read on?
+
+### `learner`
+
+Someone new to the product working through it in order, from first steps to a working setup.
+
+- What does a first working result look like for them, and how long should it take?
+- Which concepts do they need before which tasks?
+- Where do they stop and why — a missing prerequisite, an unexplained term, a broken example?
+
+## Screens, and the lens each is read against
+
+| Screen | Lens | What the person does there |
+|---|---|---|
+| Docs home (`home`) | `content` | Sees what is covered and picks a starting point or searches. |
+| Search results (`search-results`) | `content` | Recognises the page that answers the question from its title and excerpt. |
+| Article or guide (`article`) | `content` | Finds the answer on the page and acts on it. |
+| Reference page (`reference`) | `data` | Looks up one exact value, parameter or setting. |
+| Was this helpful (`feedback`) | `transaction` | Says the page did or did not answer the question, in one action. |
+| Contact support (`contact`) | `transaction` | Asks for help without retyping what the page already knows. |
+
+## Journeys to walk first
+
+### `search-and-answer` — Find the answer to one question
+
+Actor `question_seeker`, through: `home` → `search-results` → `article`.
+
+Watch when you walk it:
+
+- The answer is visible without scrolling past an introduction at a phone viewport.
+- Search results show enough of each page to choose without opening several.
+- The article's headings let the person jump to the part they need.
+
+### `get-started` — Reach a first working result
+
+Actor `learner`, through: `home` → `article` → `article` → `reference`.
+
+Watch when you walk it:
+
+- Each guide says what it needs before it starts and what the reader will have at the end.
+- Code and values can be copied without retyping.
+- The next step is linked from the end of each page.
+
+### `give-up-and-ask` — Get help when the docs did not answer
+
+Actor `question_seeker`, through: `article` → `feedback` → `contact`.
+
+Watch when you walk it:
+
+- The way to ask for help is reachable from the page that failed, not only from the home page.
+- The contact form does not ask again for what the page already knows (the page, the product version).
+- After sending, the page says when to expect an answer.
+
+## What to research about the domain
+
+- Which search terms bring people to the docs, and which of them return nothing useful?
+- Which pages have the most exits to support, and what do those support tickets ask?
+- What vocabulary do people use for the product's features, as opposed to the product's own names?
+- Which versions of the product do readers run, and do pages say which version they describe?
+- What reading level and languages does the audience need?
+
+## Where research starts
+
+- [GOV.UK — content design: writing for GOV.UK](https://www.gov.uk/guidance/content-design/writing-for-gov-uk) — Researched guidance on how people read on screens and how to write so they find the answer.
+- [Nielsen Norman Group — 10 usability heuristics](https://www.nngroup.com/articles/ten-usability-heuristics/) — Help and documentation is heuristic 10; the baseline vocabulary for any screen.
+- [Diátaxis](https://diataxis.fr/) — A documentation framework separating tutorials, how-to guides, reference and explanation by what the reader needs.
+- [GitHub Primer](https://primer.style/) — Content and navigation patterns from a documentation-heavy product.

.claude/skills/uxcli/templates/mobile-app.md

@@ -0,0 +1,84 @@
+# Mobile app — the `mobile-app` template
+
+Phone-first apps and mobile web apps: short sessions, one hand, interruptions, unreliable connections.
+
+A template is where research starts, not what it found. Nothing below is a fact about this product's users: the screens and journeys are what products of this kind usually have, and every question is yours to answer from a source before it becomes an insight. `uxcli template apply mobile-app` writes the actor questions into `.uxcli/understanding/actors/`; `references/research.md` in this skill is how to answer them.
+
+## Who uses it
+
+### `on_the_go_user`
+
+Someone using the app in short bursts between other things, often one-handed.
+
+- Which task do they open the app for most, and how long is a typical session?
+- Where are they when they use it: walking, commuting, at a counter, at home?
+- How reliable is their connection, and what should happen when it drops mid-task?
+- Which phone sizes and operating system versions do they use?
+- What interrupts them, and what do they expect to find when they come back?
+
+### `new_installer`
+
+Someone who just installed the app and is deciding in the first minute whether to keep it.
+
+- What did they install it for, in their own words?
+- What are they willing to give before seeing value: an account, permissions, notifications?
+- What makes them uninstall in the first session?
+
+## Screens, and the lens each is read against
+
+| Screen | Lens | What the person does there |
+|---|---|---|
+| Onboarding (`onboarding`) | `transaction` | Gets to the first useful screen with as little setup as possible. |
+| Permission request (`permission`) | `transaction` | Understands why a permission is asked before deciding. |
+| Home (`home`) | `workspace` | Starts the task they opened the app for, within thumb reach. |
+| List (`list`) | `workspace` | Scans and opens an item; pulls to refresh. |
+| Detail (`detail`) | `workspace` | Reads one item and takes its main action. |
+| Form (`form`) | `transaction` | Enters data with the right keyboard and without losing it to an interruption. |
+| Offline or error state (`offline`) | `workspace` | Knows what happened and what still works without a connection. |
+
+## Journeys to walk first
+
+### `first-minute` — Reach the first useful screen after installing
+
+Actor `new_installer`, through: `onboarding` → `permission` → `home`.
+
+Watch when you walk it:
+
+- Count the steps and fields before the first useful screen; each must earn its place.
+- A permission is asked when its feature is first used, with the reason on screen.
+- Skipping a permission still leads somewhere useful.
+
+### `main-task` — Do the task the app is opened for
+
+Actor `on_the_go_user`, through: `home` → `list` → `detail`.
+
+Watch when you walk it:
+
+- The primary action on each screen is within thumb reach without scrolling at 390x844.
+- Every tap answers within a second; anything longer shows progress.
+- Going back returns to the same place in the list.
+
+### `interrupted-entry` — Finish a form after an interruption or a lost connection
+
+Actor `on_the_go_user`, through: `form` → `offline` → `form`.
+
+Watch when you walk it:
+
+- What was typed is still there after the error or the interruption.
+- The offline state says what failed and offers to retry.
+- Each field brings up the keyboard its answer needs.
+
+## What to research about the domain
+
+- Which task opens the app most often, and how long does it take today?
+- What share of sessions start from a notification, a link or the home screen?
+- Which platform conventions do users expect here (back gestures, tab bars, share sheets)?
+- Which store reviews of this app and its competitors complain about what?
+- What data must stay on the device or work offline, and what do privacy rules require for it?
+
+## Where research starts
+
+- [Apple Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/) — Platform conventions iOS users expect: navigation, controls, permissions, layout.
+- [Material Design 3](https://m3.material.io/) — Platform conventions Android users expect, with component usage guidance.
+- [Nielsen Norman Group — 10 usability heuristics](https://www.nngroup.com/articles/ten-usability-heuristics/) — The baseline vocabulary for reviewing any screen.
+- [WCAG 2.2 — target size](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html) — The minimum touch target size and spacing a phone screen must meet.

.gitignore

@@ -30,6 +30,8 @@ experiments/*/results/*/transcript.jsonl
 **/.uxcli/mockups/.shots/
 **/.uxcli/mockups/index.html
 **/.uxcli/map/
+**/.uxcli/studio/
+**/.uxcli/experience/
 
 # experiment results stay on the machine that ran them
 experiments/*/results/