Mockup Lab journey: from a shelf of tools to a path through them

A · A pile of mockups

Today. Seed, then choose among peer buttons with no sign of what's next

After. Seed, then pick the least-ready unit in the rail and follow the strip

B · A spec, no mockups

Today. The empty state is a dead end. New Unit → Flows → spec (if the filename matches) → generate one screen at a time

After. "Start from a spec" in the empty state creates unit, screens and flows in one review; generate the planned screens in flow order

C · An idea, nothing on disk

Today. The empty grid offers only Lab starts

After. The empty grid offers "Sketch one screen" and "Plan the app first"

D · A mockup arrives from outside

Today. An unfiled pill visible only in the Registry; the take and variant menus vanish when no names overlap

After. A badge on the nav bar; "newer take" always available, with search

E · Another take on one screen

Today. ~8 steps across three surfaces; a Lab take is overwritten

After. "New take" on the screen; "Refine in Lab" updates this design's take; "Try a different design" makes a variant

F · "Do these agree?"

Today. Boards → hand-picked board → groups → review; 45 frames get refused

After. "Check consistency" on a unit; row-scoped review on boards

G · "What is built?"

Today. The answer appears in a sheet and closes with it

After. A status filter plus a legend; strip step 7

H · Place a browser mockup (Sarah's scenario)

Today. Filing, then improvised tools, one trip outside the app, and no ways in

After. "Place this mockup": screens + states, ways in from the lobby, case board and training, needed changes, a board

R1 · A readiness strip on every unit (resolves F1, part of F2, F3)

The strip shows the next step for a unit, and every step stays open. The parent plan rejected a linear wizard because the registry is re-entrant and never finished. The strip keeps that property: it never blocks, and every step stays clickable out of order.

• MUST compute, per unit, from existing data only: Filed (the unit's files claimed), Read the files (Fill from files has nothing left to propose), Screens and flows from spec (a spec is linked and at least one flow exists, or the step was skipped), States declared (screens with ≥1 state / screens with a file), Filled in (no purpose, beat, loop or summary gaps), Ways in (units of kind Game only: ≥1 inbound link), Built links (screens matched or explicitly unbuilt).
• MUST show each step's count ("3 of 5 screens have states") and a done, partial or next mark.
• MUST make the first incomplete step the pane's single primary button. Completed steps stay visible as ticks and can be re-run.
• MUST keep the spec step present when no spec matches, offering a picker over every *spec*.md in docs/ and a Skip that is remembered per unit.
• MUST count "screens with no states" as a gap in RegistryFillPass.gaps.
• SHOULD show "N of 7" in the unit rail and allow sorting the rail by it.
• Done when: a unit fresh from seeding shows step 2 as next. Completing each step moves the primary button forward. Every step can still be invoked out of order.

R2 · Declare states inside the app (resolves F2) (D1: writing is allowed)

• MUST offer "Declare states" on a screen and on a unit.
• MUST derive states from the harness the way RegistryFillService does. SHOULD fall back to a model pass for a file with no harness.
• MUST write the manifest and the crSetState message listener, extending FrameContract.retrofit, and MUST never overwrite an existing cr-frames block.
• MUST adopt declared states on scan when a screen has none, and leave a screen's hand-set states alone otherwise.
• MUST explain on the board when Matrix has no beats, with a link to Declare states.
• Done when: a harnessed mockup with no contract becomes a matrix of its states without leaving the app, and cr-frames.md describes what the app actually does.

R3 · One door to boards (resolves F4)

• MUST offer Whole registry, A unit, A flow, A screen with its ways in (after R8), Files I pick, and All files in the New Board sheet.
• MUST show source and resolved counts on list cards, counting through StoryboardResolver.
• MUST label every Registry board action "Show on a board".
• MUST link every derived board back to its unit, flow or screen.
• MUST start a new hand-picked board with one group.
• MUST treat states-on as a view choice that doesn't rewrite the board's stored layout.
• SHOULD let Arrange add registry screens as screen-backed slots (the model already supports screenId on a slot).
• Done when: every board kind can be created from the Boards tab, and no card reads "0 frames" while its board renders frames.

R4 · Say what happened, and what it costs (resolves F3, F9)

• MUST render the fill pass's note and lastError.
• MUST explain an empty seed.
• MUST confirm clipboard and file writes with what was copied or written.
• MUST ask for a unit when the canon packet has none.
• MUST label AI actions with approximate cost and time, taken from the parent plan's measured runs until a usage log exists: fill pass ≈ $0.33 · 1 min, conversation ≈ $0.30 · 1 min, spec reading ≈ $0.35 · 20 s.
• MUST badge the unfiled count on the nav bar's Registry segment.
• MUST use one name per place: Mockups, Registry, Boards, Mood Board, and "takes" in UI copy.
• MUST give the status dot and the beat picker a legend drawn from the glossary.
• MUST keep "As a newer take on" available with a searchable list when ranking finds nothing.

R5 · One review sheet (resolves F5)

• MUST share one shell across the seed, fill, spec, match, edit and placement sheets:
  • the title shape "N proposed changes to {scope}";
  • a provenance tag per row (READ · DERIVED · AI with confidence);
  • destructive rows start unticked;
  • one verb, "Apply N".
• MAY keep each sheet's body. The seed sheet's tree editing stays.

R6 · Check consistency where you work (resolves F6)

• MUST add "Check consistency" to a unit in the Registry, and a row-scoped review on boards through runReview(scope:).
• MUST show the 2–16 frame limit before the review runs.
• MUST resolve the canon through StoryboardCanonResolver for the review, Append to canon and both canon panes.
• MUST persist handled, applied and declined marks on the report.
• SHOULD let a finding propose registry edits alongside amendments. This takes over the open Phase 10 task in the parent plan.

R7 · New take, new design, in place (resolves F7) (per D2, confirm the reading first)

• MUST add "New take" to the Takes section. It generates from a change request plus the current take, canon and siblings, and lands as the new current version of the current variant with the old one kept.
• MUST add "Refine in Lab", which opens a session bound to the screen's current variant. Its exports update that variant's current take, and the session's revisions hold the steps.
• MUST add "Try a different design", which forks a session bound to a new, named variant of the screen. Its exports land there, so the two designs sit side by side under Takes.
• Done when: a screen with a file gains a second take and a second variant without leaving the Registry. Refining a design in the Lab no longer produces an unfiled file.

R8 · Place a new mockup (resolves F8; Sarah's scenario)

Ways in to a game usually come from other units: the lobby, case board and training (Sarah, 2026-09-23). Links are therefore a registry-wide record. Flows stay what they are, one path through one unit.

Data (Phase 3).

• MUST add ScreenLink { id, fromScreenId, toScreenId, control: String, shownInSource: Bool?, note: String?, createdAt } stored in a links array on DesignRegistry, allowed to cross units.
• MUST add stateId: String? to ScreenVersion, so a screen that shares a file names its own state. StoryboardResolver MUST use it as the cell's state when no flow step pins one.
• MUST add a "Ways in" section to the screen detail pane (add, edit, remove, and open the source screen).
• MUST add a .screen(UUID) StoryboardSource. It renders ways in as a row, the screen and its sibling screens that share its file in state order as the next row, and ways out after that.
• MUST add createLink and setScreenState to RegistryEdit, the conversation prompt's vocabulary and op list, and RegistryEditParser.

Reading (Phase 4).

• MUST add "Place this mockup" to each unfiled item. It asks which unit the file belongs to, defaulting to the best-ranked unit, and which source screens to consider. The default is the screens of Meta and Shell units: in Peregrine, after the Phase 3 correction, the Lobby, Training and Case Board (D3). It MUST NOT match unit names to choose sources.
• SHOULD also be offered on an already-filed screen whose file walks through several screens. That is how Training comes out of peregrine-v3-mockups-with-training-ground.html.
• MUST send one prompt carrying the new file and the source screens' mockups, reduced by FrameReducer to the cohesion budget, plus the canon and the glossary.
• MUST return, in one R5 sheet:
  • the screens the file walks through, each bound to the file with a stateId;
  • proposed links, each naming its control and whether the source mockup already shows it, with confidence;
  • for each link whose control is missing, the change the source screen needs.
• MUST start weak shownInSource judgements unticked.
• MUST, on apply, file the file, create the screens and links, and open the .screen board. Accepted changes become QuickTasks, or New take requests once R7 lands.
• MUST write the frame contract for the split screens through the Phase 3 contract writer (D1), so each screen renders its own view on apply. When the file already declares states, it MUST map screens onto those states and write nothing.
• MUST parse the CLI result subtype on a non-zero exit (error_max_turns) and show a readable error.
• Done when: a new Peregrine game mockup saved from the browser becomes its screens, its ways in and a needed-changes list in one pass, measured for cost, time and accuracy.