# Handheld journey and flow matrix

| Flow | User goal | Start / visible state | Action | Expected visible result | Escape / recovery | Accessibility check | Owner | Dependency | Evidence class | Citation | Open gate |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| First use | Know the device is progressing to a usable shell | Boot splash then shell | Wait for handoff | Persistent controls and a usable first app route appear | Serial capture/recovery image if boot fails | Camera must distinguish panel visibility from timestamped boot duration | splash/initial scene | boot-splash change | camera, native | `docs/evidence/splash-initial-scene-ready/video-audit.md` | Cold USB-powered first boot and optical continuity are `UNVERIFIED`. |
| Discovery | Open or resume an app | Persistent Apps control | Tap Apps, then a catalog/built-in card | Named card and page count are visible; app launches or existing app focuses | Back returns to work; failed optional launch keeps controls | Large labels; page actions remain visible | launcher/catalog | shell runtime | native, injected | `docs/evidence/offline-wifi-image/README.md` | New catalog entries need real-finger/readability review. |
| Repeat use | Return to a running app | Any eligible app | Apps then Terminal, or Windows then card | App is focused and launcher yields | Home opens/focuses Terminal; Back closes launcher | Every gesture has a visible bar/button route | gesture overview; card lifecycle | `touch-launcher-gestures-overview`; app-card plan | real-finger, injected | `docs/evidence/shell-real-touch-apps/README.md` | Ordering and stale-card guard need their named physical gate. |
| Keyboard-visible | Enter text without losing orientation | Focused app, keyboard hidden | Keyboard then type | Keyboard occupies lower area; remaining launcher routes stay reachable | Keyboard control hides it; Back/Home remain available | Asymmetric sequence and camera visibility are separate checks | shell keyboard | shell runtime | real-finger, native | `docs/evidence/shell-real-touch-keyboard/README.md` | Full directional-drag and uniform sharpness are `UNVERIFIED`. |
| Window overview | Switch windows | Apps or Windows control | Open overview, select card | Current windows are named as cards; selection returns to chosen app | Back/down return to Apps; empty/stale/loading shows recoverable status | Card and fallback targets remain reachable | gesture overview | window catalog helper | injected, real-finger | `docs/evidence/launcher-gestures/real-finger/README.md` | Empty/stale physical acceptance remains `UNVERIFIED`. |
| Video | Stop media or return home | Playing video | Stop, Home, or let EOF occur | Controller/player cleanup then shell recovery | Persistent Apps/Home path remains | Status must state ending/failure rather than silently strand the user | network-video | video session controller | injected | `docs/evidence/network-video/installed-controls/README.md` | Network error and physical playback review remain `UNVERIFIED`. |
| System | Avoid accidental shutdown and recover after reboot | System menu | Pick action; cancel or confirm | Action-specific confirmation; cancel returns; confirmed reboot returns to shell | Cancel, serial recovery, known-good image | Confirmation wording and targets must be readable | shell system controls | NixOS service policy | camera, real-finger, serial | `docs/evidence/shell-real-touch-system/README.md` | Cold USB-powered power-on timing is `UNVERIFIED`. |
| Card shell | Manage live applications directly | Arbitrary eligible running app | Global entry, shrink/drag/deck/tap/throw | Live card content follows finger and returns/focuses or refuses close visibly | Button entry, Back/Home, refusal recovery | Direct manipulation and reduced motion preserve core sequence | card-composition; app-card plan | architecture decision | UNVERIFIED | UNVERIFIED | Implementation and all physical proof remain `UNVERIFIED`. |