# Understand information architecture **Status:** Pre-approval map for the consolidated 78-state package. Canonical artifact: `consolidated-state-package-05.html`; synthesis and open decisions: `FLEET-SYNTHESIS.md`. **Product:** Understand mobile listening companion. **Primary job:** Help a listener bring in difficult text, start local listening, and stay with the heard sentence. ## Site map / app map - Library - Empty library - Continue card - Expanded saved-text row - Newly added text - Settings - Add text - Paste from clipboard - Share from another app - Unsupported PDF/EPUB - Replace-open-text confirmation - First run - Welcome - How it works - Local voice setup - Idle - Downloading - Verifying - Ready - Error - Cancelled - Local retelling disclosure - Reader - Empty Reader - Loaded Original - Idle - Cold gather - Synthesizing - Live sentence - Paused - Seeking - Completed - Playback error - Large text - Retelling - Loading - Ready - Disclosure - Local quota - Retry - Reader overflow - Contents - Edit stub - Report output - Clear current text - Voice sheet - Ready - Preview playing - Unavailable - Downloading - Verifying - Error - Retelling settings sheet - Clean - Dirty - Cloud/Premium choice - Loading - Contents sheet - Available - Current chapter - Unavailable - Listening view - Reply listening - Back to Reader - Settings - Default - Large text - Reduced motion - Account and Premium stub - Premium - Cloud choice - Premium details - Checkout/continue - Cancelled - Active - Unavailable - Local fallback - Data and recovery - Delete history confirmation/success/failure - Delete model confirmation/progress/success/failure - Delete all local data success - Model recovery - Cloud recovery - Generic data recovery - Platform contracts - Share handoff - Share returned - Notification and lock-screen controls - Permission denied ## Navigation model - **Primary navigation:** Library and Reader are the two product contexts. Library is the durable root. Reader is entered when a text is open. - **Secondary navigation:** Reader dock controls Original/Retelling, Retelling settings, voice, speed, and transport. Contents and overflow are contextual to the current text. - **Utility navigation:** Settings is entered from Library and remains a focused sheet. Premium is entered only when a cloud feature is requested or an entitlement state needs explanation. - **Mobile navigation:** Do not add a persistent bottom tab bar. The listening dock is not navigation. Back returns to Library without stopping playback unless the user leaves the Reader session. ## Content hierarchy ### Library 1. Continue listening, when a saved session exists. 2. Add or paste text. 3. Recent saved sessions. 4. Settings and account stub. ### Reader 1. Current heard sentence and readable passage. 2. Matter/playback state. 3. Original/Retelling choice. 4. Voice, speed, contents, and secondary actions. ### Sheets and dialogs 1. Sheet/dialog title that names the choice. 2. The selected value or consequence. 3. The next direct action. 4. Cancellation, fallback, or recovery. ### Onboarding 1. Local-first promise. 2. What the listener can do. 3. Voice/model readiness. 4. Entry into Library or Reader. ## Critical user flows ### New listener to first local playback 1. User opens Understand. 2. User sees the local listening promise. 3. User continues through the short explanation. 4. App shows voice setup. 5. User starts or resumes the local voice download. 6. App verifies the model. - If it fails, user retries or keeps browsing without losing text. 7. App opens Library. 8. User pastes or shares text. 9. Reader opens with Original selected. 10. Matter gathers, first voice arrives, then the rest of the Reader chrome settles. ### Paste text while another text is open 1. User opens Add text. 2. User chooses Paste from clipboard. 3. App shows Replace what is open? 4. User confirms or cancels. 5. On confirm, playback stops, old text moves to Recent, and new text opens. 6. Reader offers the first listening action. ### Switch to retelling 1. User opens Reader with Original or a saved retelling. 2. User chooses Retelling. 3. App explains the rewrite the first time. 4. App prepares local retelling. 5. The original remains available while it loads. 6. When ready, the persona rewrite becomes the heard text. - If local quota/model fails, user can use Original or choose the cloud option. ### Change persona or location 1. User opens Retelling settings from the Reader dock. 2. User changes Persona or Where it runs. 3. Sheet shows an unsaved/dirty state. 4. User applies or closes. 5. Apply starts the necessary rewrite work and preserves the current text. ### Choose a different voice 1. User opens Voice from Reader. 2. User previews an installed voice or selects an unavailable voice. 3. App downloads and verifies the voice when needed. 4. User can cancel or keep the current voice. 5. The selected ready voice is used for the next playable sentence. ### Recover from a failure 1. App names the failed operation. 2. App confirms the text/session is safe. 3. User chooses Retry, an installed/local fallback, or Close. 4. App returns to the same product context without a dead end. ### Delete data 1. User opens the relevant Settings action. 2. App explains exactly what will be removed. 3. User can Cancel without side effects. 4. App shows progress for a long deletion. 5. App reports success or leaves data intact on failure. ## Naming conventions | Concept | UI label | Rule | | --- | --- | --- | | Saved text and playback position | Session | Use `session` in docs; use the text title in the UI. | | Source wording | Original | Never call it `raw` or `input` in user-facing copy. | | Persona rewrite | Retelling | Never call it a summary. | | Voice package | Voice | Say `model` only when explaining download/setup. | | Local processing | On device / local | Use `On device` in selectors and `local` in explanatory copy. | | Cloud processing | Cloud rewrite | Keep this exact term across Premium and Retelling settings. | | Text scale | Large text | Do not mix `large`, `2×`, and `accessibility mode` in controls. | | Destructive removal | Delete | Use `Clear` only for removing the current Reader text. | | Reader secondary menu | More | Avoid `overflow` in user-facing copy. | ## Component reuse map | Component | Used on | Behavior differences | | --- | --- | --- | | Matter | Onboarding, setup, Reader, recovery | Size and texture change by state; it remains the signature voice cue. | | Reader dock | Loaded Reader and completed Reader | Full controls after chrome settles; transport stays available during cold start. | | Bottom sheet | Add text, Voice, Retelling settings, Contents, Settings | One focused sheet at a time; same radius, inset, backdrop, and close behavior. | | Dialog | Replace, Report, Clear, Delete | Centered, direct consequence copy, Cancel plus named action. | | Progress | Model and voice downloads, model deletion | Determinate when known; no fake completion. | | Recovery action pair | Errors and unavailable states | Retry plus a truthful fallback. | | State announcement | Playback, setup, report, deletion | One live announcement for the state change; visual banner may remain. | ## Content growth plan - Library Recent grows over time. Keep newest sessions first and retain the Continue card separately. - Contents grows with available chapter metadata. If metadata is absent, show unavailable rather than a fabricated outline. - Voice catalog grows by installed/downloadable model. Keep the selected voice and model status at the top. - Report history does not need an in-app list in this pass. A sent/failed result is enough. - Notes and future editing remain outside this state package until their Flow design is approved. - Reply listening (listening view → reply → back to Reader) is post-vc25 and **out of scope** for the 78-state package; it must not be added back silently (fleet F-13). ## URL / route strategy Understand is a mobile app, not a URL-first site. Use named internal destinations and state IDs in tests instead of pretending sheets are routes. - Root context: `library` or `reader`. - Contextual surfaces: `sheet/` and `dialog/`. - Async states: `/`. - Destructive states: `/`. - Platform contracts: `platform/`. The canonical Flow state IDs are the test identifiers. Flutter keys and semantic labels should map to those IDs where a state is visually approved.