Ox Dot

When to use. Ask-mode cast prompt: paired TV came online during a session. 'Cast to <TV name>?' header + Yes/No pills. Auto-dismisses after 8s with No.

When not to. Don't show in Always mode (cast::Mode::Replace) — that mode casts implicitly. The overlay is only for Ask mode (cast::Mode::Ask).

When to use. Shared-space mode (kiosk deployments). Counts down ~30s before auto sign-out from inactivity. Tap to keep session alive. Gated on FEATURE_SHARED_SPACE_MODE — not in default build.

When not to. Don't enable in single-user deployments — sign-out friction is unwarranted. Gate at the feature flag, not the screen.

When to use. Mid-recording 'Still there?' countdown overlay (~10s). Fires when the recorder detects the user has wandered off (no audio activity threshold). Tap to keep recording, ignore to auto-finalize.

When not to. Don't fire too often during quiet meetings — false trigger is worse than missing one. Threshold lives in audio config.

When to use. First frame on power-up and during any post-restart cycle, before WiFi connects. Three pulsing dots + small status line below tell the user the device is alive while WiFi / NVS / auth come online.

When not to. Don't keep BOOT showing past WiFi handshake — switch to WIFI on failure or IDLE on success. Anything past ~5s on BOOT signals a broken first boot.

When to use. Active cast control: paired TV name, join URL QR (for participant phones), Disconnect pill, X close pill. Pills grey-out during in-flight disconnect operations.

When not to. Don't navigate AWAY from CAST_CONTROL while a stream is active without an explicit Disconnect — leaving silently leaves the TV showing stale content.

When to use. Cast-control screen during the connect handshake (CastV2 or AirPlay session establishment). Disconnect pill greyed out; status arc shows 'Connecting…'.

When not to. Don't allow taps on Disconnect during connecting — the session lifecycle is non-cancellable until the handshake completes or fails.

When to use. One-tap test cast to verify a paired TV works. 30s countdown + 'See SageOx on TV?' prompt + 720/1080/4K resolution segments. Lives under Settings > Cast > Test.

When not to. Don't fire CAST_TEST without a paired receiver — endpoint returns 409 if not paired. Pair-flow is its own overlay.

When to use. Test-cast failure or timeout. Shows the user-readable failure reason (TV unreachable, app launch failed, manifest rejected) + Retry pill.

When not to. Don't silently retry on cast-test failure — the user explicitly invoked the test and needs to see the cause.

When to use. Test-cast success state. Green check + 'Looks good' confirms the user tapped Yes on the countdown. Auto-dismisses to the cast settings page.

When not to. Don't infer success from absence of error — the user must explicitly tap Yes to confirm picture on TV.

When to use. Recording finalized + uploaded. Green checkmark, recording duration, team label, QR code linking to the cloud transcript. Auto-dismisses to IDLE after ~10s or on tap.

When not to. Don't show DONE if the upload failed — error path is ERROR screen with retry affordance.

When to use. Recording captured but device was offline at finalize — buffered locally, will drain when WiFi returns. QR + cloud link are omitted since transcript isn't live yet.

When not to. Don't show the green checkmark in offline-done — replace with a queued/buffered indicator so the user knows the recording isn't visible in the cloud yet.

When to use. Hard failure that needs the user's attention (auth lost, no team, repeated upload failure). Shows the user-readable message + a 'Try again' pill. Auto-dismisses after 10s.

When not to. Don't use ERROR for transient network blips — silently retry and queue chunks. ERROR is for failures that need a human decision.

When to use. Last gate before nvs_erase + reboot. Header: 'Erase device?'. Detail explicitly names what's lost (WiFi, pairing). Danger pill: 'Erase'. Cancel pill: ghost. Most destructive UI flow.

When not to. Never auto-trigger this overlay — only from Settings > Device after an explicit user navigation.

When to use. Default ready-to-record state. Ambient ring shows rolling 30-second buffer fill (rewind window). Team name in the lower curve. Single-tap anywhere starts a recording.

When not to. Don't add affordances inside the inner ring (those compete with the implicit 'tap anywhere to record' gesture). Status indicators live in the outer ring.

When to use. WiFi is down. Same idle layout + a small offline badge in the outer ring. Recording still works (captures locally + drains on reconnect). User gets a passive cue, not a modal.

When not to. Don't preempt to the WIFI screen mid-recording — recorder is capture-only and survives offline; only show WIFI from IDLE.

When to use. Active team is configured as PUBLIC (recordings shared across the org). Teal accent on the team-name lower curve is the canonical 'this is public' indicator.

When not to. Never use teal (CLR_TEAL_500) for anything else on any other screen — it's a reserved semantic for public-team context cueing.

When to use. Rewind buffer is filling (sage arc growing from 0% to 100% over 30s). Small rewind chevron affordance appears once buffer is full — tap to start a recording that includes the prior 30s.

When not to. Don't hide the rewind arc once full — it's the visual cue that the rewind feature is available. Even when not used, it signals capability.

When to use. OTA manifest reports a newer firmware version. Small badge in the outer ring; the actual prompt happens on next boot (or via Settings > Device > Check for updates).

When not to. Don't interrupt IDLE with a modal — the badge is enough; the user will see it on their schedule.

When to use. Confirmation overlay for the 'Sign Out' action in Settings. Header: 'Sign out?'. Danger pill: 'Sign Out'. Cancel pill: ghost. Sign-out wipes auth tokens but preserves WiFi.

When not to. Don't reuse this overlay for partial sign-outs (e.g., switching teams) — that's a non-destructive Team Picker tap.

When to use. Device-code OAuth pairing flow. Shows the 6-char user code, a QR linking to the verification URL, and a countdown ring for the code's 15-minute TTL. The single load-bearing first-run screen.

When not to. Don't reuse the QR + countdown layout for non-pairing flows — rewind consent and update prompt have their own scaffolds.

When to use. Pairing failed (network blip, code expired, OAuth denied). Shows the failure reason + a Retry pill that restarts the device-code flow with a fresh code.

When not to. Don't auto-retry — pairing failure usually means the user took too long; restart only on their explicit tap.

When to use. Post-code-entry intermediate state. User has scanned the QR and entered the code in the browser; firmware is polling the OAuth /device/token endpoint waiting for approval.

When not to. Don't drop the countdown ring here — it still owns the remaining TTL of the device code; if it expires the user has to restart pairing.

When to use. Large 'Record' CTA overlay that appears when the user is about to start a meeting but the device wants explicit confirmation (shared-space mode, or after a long idle).

When not to. Don't show on a tap that's clearly intentional — adds a second tap to the most common interaction. Reserve for ambiguous wake conditions.

When to use. Active capture for a PRIVATE team. Red pulsing ring + red background wash + elapsed-time digits (Mont 30 mono). Status arc top reads 'RECORDING'. Tap anywhere to enter the pause/stop sheet.

When not to. Never tint the recording screen any color other than the state-load-bearing red (active) / amber (paused or upload-failing). Status colour is the only state cue from a glance.

When to use. Recording with paired TV link healthy. Small TV-OK icon in the outer ring cues that this session is also live-casting.

When not to. Don't add a tap target on the cast icon during recording — the indicator is status-only; cast control lives behind Settings > Cast.

When to use. Recording proceeds normally but paired TV is unreachable. Greyed cast icon tells the user the TV is offline; recording itself is unaffected.

When not to. Never block recording on cast failure — cast is best-effort downstream; capture and upload are independent.

When to use. Recording paused mid-session. Amber background wash + 'PAUSED' status arc replace the active red. Timer keeps running (elapsed wall-clock) but new audio isn't captured.

When not to. Don't keep recording-paused open indefinitely — auto-resume after ~5 min idle to avoid leaving stale sessions open on shared devices.

When to use. Active capture for a PUBLIC team. Teal accents on the lower-curve team label cue that this recording will be shared across the org.

When not to. Don't drop the teal indicator when paused — even at rest, the public visibility status is load-bearing context.

When to use. Mid-recording status: chunks have queued faster than the uploader can drain (transient slow WiFi). Small 'Syncing N…' label tells the user upload is behind but recording is still capturing.

When not to. Never make this a modal or interrupt the recorder — the label is informational only; capture is independent of delivery (post-resilience plan §2.8).

When to use. Sustained upload failure (offline > N seconds). Amber background wash + 'Saving locally' label tell the user we're buffering to flash and will drain later.

When not to. Don't stop recording on upload failure — that defeats the purpose of the offline buffer. The amber wash communicates degraded delivery without interrupting capture.

When to use. One-time consent overlay before enabling the 30-second ambient buffer (rewind). Explains what the feature does + the privacy trade-off. Decision is sticky in NVS.

When not to. Don't show on every boot — once acknowledged, the answer persists. Re-show only if storage clears or user explicitly toggles in Settings.

When to use. Crash-recovery screen. Boot counter detected a panic loop; device drops to a minimal screen with a QR linking to support + an option to retry the OTA. Last-resort UI.

When not to. Never code paths that 'might' trigger safe mode — boot counter is the single source of truth. Triggered only by esp_reset_reason() + sequential panics.

When to use. Safe-mode with WiFi also down — QR with support URL + a static recovery hint ('connect via USB serial'). The lowest-capability state the firmware reaches before bricking.

When not to. Don't substitute a different message — the QR pointing at support docs is the canonical recovery anchor and must remain visible even without WiFi.

When to use. Horizontal swipe pager containing every settings subpage. Profile is the default landing page. Pager dots in the outer ring; current page title centred. Reached from IDLE via top-edge swipe down.

When not to. Don't add a 9th page without auditing the pager dot density — the outer ring fits ~8 dots before they crowd the bezel.

When to use. About subpage: firmware version, build SHA, copyright line, QR linking to release notes. The 'who am I and what version' page for support triage.

When not to. Don't dump every config knob here — About is identity + version only. Knobs live in the relevant feature subpages.

When to use. Cast subpage with paired TV: shows TV name, Test pill, Unpair pill, mode toggle (Off / Ask / Always).

When not to. Don't show pair affordances here once paired — pairing is a discrete flow under Settings > Cast > Select TV.

When to use. Discovered TV list (post-scan). Scrollable rows with TV name + mDNS host. Tap a row to start pairing.

When not to. Don't show the picker before scan completes — show the scanning state instead.

When to use. Active mDNS / SSDP scan for cast targets. Spinning ring + 'Scanning…' label + Cancel pill. Transitions to picker on results.

When not to. Don't block scanning longer than ~5s before showing partial results — slow-discovery TVs (DIAL, webOS pre-cache) trickle in over 5-15s.

When to use. Cast subpage with no paired TV: shows 'Select TV' CTA + explainer for what cast does. First-run state for this subpage.

When not to. Don't show pair affordances inline — pairing happens in a dedicated picker after the user taps Select TV.

When to use. Consent toggles: rewind buffer, telemetry, crash reporting. Each row is a yes/no with the privacy implication spelled out. Decision is sticky in NVS.

When not to. Don't bury consent UI behind multiple taps — the page lives at the top level of Settings precisely so it's discoverable.

When to use. Debug subpage (dev builds only — FEATURE_DEBUG_MODE). QR linking to the device's HTTP debug console at http://sageox-XXXX.local/ for log tailing.

When not to. Never enable the debug subpage in release builds — the debug HTTP server exposes log_ring contents which may contain redacted secret prefixes.

When to use. Device subpage: firmware version + 'Check for updates' / 'Download' / 'Reboot Now' CTA cycling per OTA state. Also houses the Factory Reset entry (gated by a confirm sheet).

When not to. Don't expose esoteric flags here (text scale, etc.) — those live in dedicated subpages or are derived from user account.

When to use. Manual OTA check in progress (CTA: 'Checking…' with spinner). Fires when user taps Check for updates and the device queries the manifest endpoint.

When not to. Don't reuse this layout for any other 'wait for network' action — it's wired to the OTA result transition.

When to use. Memory subpage: int / PSRAM free counters + a 'Reservations' drilldown linking to docs/memory/map.md. Dev / support tool, not for end-user consumption.

When not to. Don't show this in single-user release builds without the debug feature flag — it leaks build internals.

When to use. Profile / Account subpage: user name, email, paired team count, Sign Out pill (which fires the LOGOUT_CONFIRM overlay).

When not to. Don't show profile actions without a paired team — sign-out from a half-paired state would leave the device unauthenticated but with WiFi, which is a useless half-state.

When to use. WiFi subpage: current SSID, IP, MAC + 'Change' pill to enter the network picker (SETTINGS_WIFI list mode).

When not to. Don't show the picker as the default WiFi view — most users never need to change networks; the current-network summary is the right primary view.

When to use. WiFi-only lock mode: the supervisor has restricted the user to the WiFi settings screen until reconnection. Shows the specific reason that triggered the lock (no recovery known).

When not to. Never preempt to this lock during a live recording — recorder is capture-only and survives offline; lock only fires from IDLE state.

When to use. Active WiFi network scan. Spinning ring + 'Scanning…' label. Transitions to the network list once the scan completes.

When not to. Don't block longer than ~5s on a scan — show partial results as they arrive.

When to use. Brief 'still uploading' indicator after recording stops but the final chunks haven't drained yet. Shows progress bar + remaining chunk count. Auto-transitions to DONE on flush.

When not to. Don't block the user from starting a new recording during STREAMING — the upload queue is independent from capture.

When to use. Streaming screen with explicit remaining chunk count — shown when upload is slow (e.g., big recording on degraded WiFi) and the user wants to know progress.

When not to. Don't show chunk count for fast uploads — adds noise to a two-second screen. Threshold for showing the count lives in ui screen logic.

When to use. Horizontal swipe carousel of teams the user belongs to. Each card shows team name + an avatar / colour. Reached from IDLE via the team-name lower-curve tap. Selecting a team updates the recording target for the next session.

When not to. Don't show TEAM_PICKER if the user belongs to only one team — collapse to a no-op and skip the affordance.

When to use. Boot-time OTA prompt: '0.1.0 -> 0.4.6' + 10s countdown ring + release date + Update / Skip pills. Auto-accepts on countdown expiry.

When not to. Don't show during a recording (would interrupt capture). OTA check is gated behind UI_SCREEN_IDLE state.

When to use. OTA in progress. Accept pill replaced with 'Downloading…' label; ring fills as the binary streams. Device stays responsive (download is Core 0 task on PSRAM stack).

When not to. Don't reuse this layout for non-OTA downloads — the ring fill is semantically OTA progress and shouldn't be diluted.

When to use. OTA download or signature verify failed. Shows the user-readable failure reason + Skip pill. Device remains on current firmware; next boot retries.

When not to. Never auto-retry an OTA from this screen — failed signature verification can mask a real attack vector; user must opt in.

When to use. Brief post-pairing transition (~2s). Confirms success and hands off to IDLE. Shows the user's name + team affiliation as the first 'we know you' moment.

When not to. Don't extend the welcome screen beyond 2-3 seconds — the user is ready to record; WELCOME is a transitional polish frame, not a destination.

When to use. WiFi association in progress (or after disconnect during runtime). Shows current SSID in copper text + status message. Owns the screen while WiFi is the blocking dependency.

When not to. Don't use as a passive offline indicator on IDLE — that's the offline badge in the corner of the idle screen.

When to use. Password entry for a selected WiFi network. Shows the on-screen keyboard (v2: ABC / abc / 123! tabs + Go / Cancel pills). SSID name above the input.

When not to. Don't reuse for non-WiFi text input — keyboard component is shared but the password screen owns the SSID context and the connect-on-Go callback.

When to use. Per-known-network action sheet (Forget / Reconnect). Reached by long-press on a row in the WiFi network list.

When not to. Don't auto-open for non-known networks — Forget is only meaningful for stored credentials.