# Fleet synthesis — Understand design package

**Status:** Synthesis complete. Package revision 05 is the tracked canonical artifact, pending one owner approval and the decisions in the last section.
**Artifact:** `docs/design/brand/consolidated-state-package-05.html` (new file; prior previews 01–04 in `.superpowers/brainstorm/81813-1787986487/content/` are untouched).
**Inputs:** the five fleet reviews (visual, motion, accessibility, flow/copy, design-system), `docs/DESIGN.md`, `docs/design/brand/MISSING-STATES-BRIEF.md`, `INFORMATION-ARCHITECTURE.md`, `STATE-PACKAGE-REVIEW.md`, the latest consolidated browser artifact (preview 04), and the pinned Flow source `docs/design/mocks/brand-proof/flow.html` @ `30503a4`.

## Owner anchors applied

The owner-approved Ferrofluid direction and the owner's Reader correction are non-negotiable and are enforced in revision 05:

1. **One Reader play/pause control.** The matter orb is the only playback control in the Reader dock, with a visible play glyph when idle/paused and a pause glyph while playing/seeking (fleet V2, DS blocker). Cold-start shows a dimmed glyph labeled as preparing; error matter stays a retry affordance, never a fake transport.
2. **Voice preview only inside the Voice sheet.** Preview wording is explicit (`Preview voice` / `Stop preview`), visible copy and `aria-label` agree, the sheet has a `Close` action, and a caption states that preview never touches Reader playback (V14, M-14).
3. **No paused/seeking banner over reading text.** Paused and seeking carry their state in the dock: glyph, position row, timecode, and a `Paused` / `Seeking` status label inside the transport row — never a banner over the passage (V7, owner correction).

## Conflicts reconciled

| Conflict | Resolution |
| --- | --- |
| Rename state IDs (`report-sent` → `report-saved`, `premium-cancelled` → `purchase-dismissed`) vs. the 78-ID stability contract (DS review). | IDs stay stable technical keys; **user-facing labels** carry the correction (`Report saved`, `Purchase dismissed`). The 78 IDs and 13 group counts match preview 04 exactly. |
| `reader-quota` copy reversed local/cloud (F-01, P0). | Renamed in copy to **Cloud rewrite limit reached** with Original + local-rewrite fallbacks; local rewrite failure is now `reader-retry`'s job (`Local rewrite is unavailable`). |
| Preview 04 rendered Retelling selected for the Original state (V6/F-06). | Fixture data now separates `view` (original/retelling) from `playback` (idle/gather/synth/playing/paused/seeking/completed/error). Segment selection binds to `view`. |
| Pinned Flow applies mode changes mid-play (F-07) vs. locked next-play rule `pux-03`. | The package matrix records next-play semantics (`reader-retelling-ready` → play applies the view on next play). Aligning the pinned Flow and Flutter handler is a follow-up on the Flutter side, not an artifact change. |
| Reply listening: flow review said the IA names it; the current IA does not (it lives in the brief inventory and post-vc25 docs). | Boundary made explicit: reply/listening-view is **out of scope** for the 78-state package, marked post-vc25 in the brief and IA (F-13). |
| `Not now` / `Keep browsing` bypass vs. the blocking model gate (F-03). | Package keeps the actions wired to an honest browse-only Library; flagged as owner decision D-1 rather than silently deleting flows. |
| Platform cards could be mistaken for fake OS surfaces (visual Q7, F-09). | Platform states now render as **system-owned contracts** (badge, no matter, no fake primary for share; `share-handoff` explains choosing Share in the other app). |

## Improvements applied in revision 05

Mapped to fleet finding IDs:

- **Visual:** dialog/menu/backdrop contained by the phone (`position:relative` + clip) — V1; long two-paragraph large-text fixture with the live sentence mid-passage — V5; `paste-success` gets its headline/body/actions rendered — V8; must-read labels and sheet titles use `wake` (usage rule, palette untouched) — V9; ≥44px interactive bounds with focus-visible rings and pressed states (48dp remains the production bar via transparent hit boxes) — V10; table key/value hierarchy — V12; sheet geometry 16/22/28, 20px radius, 78% max-height, scrollable — V13; voice sheet close + synced semantics — V14.
- **Flow/copy:** transition matrix keyed by canonical IDs for all 78 states (159 rows), actions replay between states — F-05/V11/M-15; quota truth — F-01; report privacy copy names the retelling, the encrypted local queue, and metadata-only triage — F-02; share handoff actor fixed — F-09; disclosure gates have one meaning with a real `Not now` — F-12; duplicate/dead actions removed (`retelling-clean` Apply, `edit-stub` double exit, completed copy names Library) — F-14; full Settings rows in the reduced-motion view — F-15; catalog-style voice names marked illustrative — F-16; Library owns primary intake, Reader paste is secondary, sample entry present — F-17; terminology table applied (`Cloud rewrite`, `Report this retelling`, `Keep local`, `More`, `Contents are not available for this text`, `Local rewrite is being prepared`).
- **Accessibility:** `role="dialog"`, `aria-modal`, labelled sheets/dialogs/menu, `progressbar`/`slider` semantics with values, state labels off `quiet` — DS-medium, A-usage; wake-labeled eyebrows (A1 usage half).
- **Motion:** custom easing tokens, 120ms press feedback, reduced-motion media query, motion budgets documented in the fleet motion review remain the port contract (M-01…M-15 recorded, not re-litigated).
- **Design-system:** the package is now **git-tracked** at `docs/design/brand/` (resolves the 
"untracked package" blocker); token custom properties are organized primitive → semantic → component against the pinned Flow roles.

## Checks run

- node --check on the extracted script: pass.
- State ledger: 78 states, 78 unique IDs, 13 groups; IDs identical to preview 04 (none added, none removed).
- Transition matrix: 78 entries, 159 rows, every real target resolves to a state ID; every primary/secondary button is wired.
- Render smoke test: all 78 states and 13 groups render without error (DOM-shim).
- Owner-rule probes: paused/seeking emit no banner; glyph states correct (idle play, playing pause); Original/Retelling selection follows view; voice preview aria/copy sync inside the sheet.
- git status: only intended design docs changed; no Flutter code touched (pre-existing worktree modifications left as-is).

## Deliberately not done

- No Flutter code changes (task scope; V2/V3/V4 glyph, chrome-fade, and inset fixes are recorded for the port pass).
- No new state IDs for runtime-only outcomes (empty clipboard, archive failure, share-empty, purchase pending, account deletion). They are mapped in the matrix notes and flagged below; adding them is an owner decision.
- No palette value change: quiet #5c574e stays as pinned; revision 05 fixes usage (must-read text now wake). See D-3.

## Unresolved owner decisions

- **D-1 — Model gate bypass.** Is browse-only Library allowed with no installed voice (Not now / Keep browsing), matching the package wiring, or does the blocking ModelGateScreen rule win and the bypass actions get removed?
- **D-2 — Premium surface state.** Settings shows "not available in this build" while the package designs live checkout. One truth is needed: live Premium entry, or keep the stub and mark purchase states future. Hosted voices stay out of advertised benefits while arc-01 gates them.
- **D-3 — quiet token value.** At #5c574e it is 2.64–2.80:1 on all reading surfaces (below AA, below even the 3:1 large-text bar). Either raise it (e.g. #827c70 = 4.84/4.57/4.69 on field/lift/sheet) or codify "wake owns all must-read text; quiet is decorative only" in docs/DESIGN.md.
- **D-4 — Local rewrite model setup states.** The ~600 MB on-device rewrite model setup (idle/downloading/ready/failure, F-04) is folded into local-disclosure copy and the matrix. Add explicit states (breaks the 78-ID contract) or keep the fold with a named inline setup state.
- **D-5 — Contents current-row accent.** live text, spike accent, or both, identical in package and Flutter (fleet visual Q5).
- **D-6 — Voice sheet close behavior.** Does closing the Voice sheet (Back, outside tap) stop an active preview? Package assumes yes.
- **D-7 — Idle chrome fade.** Confirm the 5s timer and tap/scroll reveal for secondary dock rows (V3 approval question 2).
- **D-8 — Retelling settings as shipped action.** If it ships this pass, its dirty/apply/cancel/loading transitions need Flow-source proof; if not, the affordance stays a stub (V approval question 8).

## Recommended next step

One owner review of consolidated-state-package-05.html plus decisions D-1…D-8. After approval: port per the design-system handoff checklist (tokens → components → Reader geometry), keep the fleet reviews as acceptance evidence, and replay the user story on device before touching the store.