# Understand Test Stories

Last updated: 2026-07-08

This file is the comprehensive wireframe/OOUX test-story inventory for Understand. Use it to choose design batches, verify core flows, and keep handoffs concrete.

Current scope:

- Design the core experience, object model, user flows, states, and layout structure.
- Treat stories as wireframe tests, not production QA or visual-design criteria.
- Do not optimize typography, color, icon style, illustration, or polish yet.
- A story is "covered" when the wireframe makes the object, action, state, and next step understandable.

Priority key:

- P0: must be designed before the core product model is believable
- P1: important for a strong v1
- P2: useful after the core flow is stable

Status key:

- Covered: represented clearly enough in the current wireframe/prototype
- Partial: represented, but important flow/state cases are missing
- Open: not wireframed yet

Closure note: an Open story can be intentionally open when the correct behavior depends on production-native capability or an upstream product decision. In the current V1 closure pass, `L06` and `L07` are open by design rather than missing in-app screens.

## Vision-Derived Review Lenses

Use `product-vision.md` before selecting or reviewing batches. These lenses are not extra UI requirements by themselves; they help decide whether a wireframe still matches the product promise.

- Does first-run reach the aha moment quickly: difficult text becoming listenable, alive, and worth continuing?
- Does the screen feel like part of a real listening session rather than a fake mini-demo?
- Does Library act as a meaningful cold-open root with real public-domain books?
- Does the design imply whole-text continuity instead of throwaway excerpts?
- Does shared text enter the same listening-session model rather than a separate mode?
- Does Original stay available enough to preserve trust without slowing playback?
- Are secondary tools discoverable without making first play feel like work?
- Are we protecting recognition and renewed comprehension, not reducing the app to summary or generic TTS?

## Batch Plan

Review checkpoints should focus on the user's mental model, object relationships, flow order, state transitions, and layout hierarchy. Visual design is intentionally out of scope until the core wireframes are correct.

| Batch | Focus | Goal | Review checkpoint |
|---|---|---|---|
| B1 | Import failures and weak structure | Prove file intake is honest when extraction is slow, weak, or fails. | Review selected file -> processing -> failure/weak-structure recovery. |
| B2 | Compare, trust, and fidelity | Prove users can trust the retelling because Original stays available and closeness to Original is legible. | Review Retelling/Original switching, fidelity, and meaning-change anxiety. |
| B3 | Retelling settings persistence and generation rules | Prove Save settings, ready states, cancel/retry, and saved retelling rules do not conflict. | Review pending setup, generation, ready, use-now, cancel, and switching books/texts. |
| B4 | Voice, offline, cloud, and premium | Prove the local path works and premium/cloud improves quality without blocking listening. | Review offline, cloud unavailable, premium preview, local fallback. |
| B5 | Library, Continue, and book/text navigation | Prove users can return to books/texts and continue without document-manager clutter. | Review Library Continue reading, Contents, completion, and where-you-left-off behavior. |
| B6 | Selected text actions, voice notes, and Annotations | Prove the selection menu and hands-free voice layer can handle e-reader actions, recovery, and durable marks without becoming a generic tool drawer. | Review Copy, Highlight, Transform, Listen, note/question creation, voice note/question, saved-annotation Discuss, Share, Mark problem, and Original/Retelling. |
| B7 | Onboarding and first-run proof | Prove the first session teaches the promise before asking for setup. | Review sample play, compare Original, choose Retelling settings, import next source. |
| B8 | Settings and account boundaries | Prove deep controls live outside the reader and cannot interrupt listening accidentally. | Review voice catalog, storage, privacy, destructive actions, downloads. |

## P0 Stories

### Source Intake And Import

| ID | Story | Status | What to test | Expected behavior |
|---|---|---|---|---|
| S01 | As a reader, I can paste text and create a listenable Source. | Covered | Paste 8+ words, tap Create source. | Reader opens with pasted text as the active reading item. |
| S02 | As a reader, I can select a file and create an import placeholder Source. | Covered | Choose a PDF/EPUB, tap Create source. | Reader opens in a processing/fallback Source state, not parsed file text. |
| S03 | As a reader, I see import processing after adding a file. | Covered | Add a selected file. | Reader banner says the Source is preparing; playback is disabled until the first listenable position is ready. |
| S04 | As a reader, I see a ready state after import processing. | Covered | Wait for import processing to finish. | Banner changes to Ready to listen; Start listening begins playback. |
| S05 | As a reader, I understand fallback positions are not real chapters. | Covered | Open Contents after placeholder import. | Contents labels fallback positions clearly. |
| S06 | As a reader, I can recover when a PDF is scanned/image-only. | Covered | Import a scanned-PDF state. | App explains no selectable text was found and offers useful next steps. |
| S07 | As a reader, I can recover when a PDF is password-protected. | Covered | Import password-protected state. | App names the issue and offers unlock/choose another file. |
| S08 | As a reader, I can recover when extraction produces messy text. | Covered | Import weak-OCR state. | App offers fallback positions, paste-clean-text option, or try anyway. |
| S09 | As a reader, I can cancel a long import. | Covered | Start import processing, tap Cancel import. | Processing stops and user returns to Library/Source context without a broken Source. |
| S10 | As a reader, I can retry a failed import. | Covered | Trigger import failure, tap Retry. | The same file tries again without losing the selected Source context. |
| S11 | As a reader, I can choose another file after failure. | Covered | Trigger import failure, choose another file. | Intake opens with file selection, not a dead-end error. |
| S12 | As a reader, I can import a very large file without feeling trapped. | Covered | Start long-file state, leave to Library, then reopen the current item. | Reader preserves the import job/progress and lets the user return without resetting the Source. |

Prototype test note: import scenarios can be forced by test filenames in the static wireframe only. Production should detect scanned PDFs, locked files, empty extraction, weak structure, and file limits from parser results and metadata.

### Reader And Playback

| ID | Story | Status | What to test | Expected behavior |
|---|---|---|---|---|
| R01 | As a reader, I can start listening to the active Source. | Covered | Tap Play on a ready Source. | Playback starts and active sentence highlighting advances. |
| R02 | As a reader, I can pause and resume. | Covered | Tap Play/Pause. | Audio state toggles without losing current sentence. |
| R03 | As a reader, I can skip back 15 seconds. | Covered | Tap -15. | Playback position moves back and sentence state updates. |
| R04 | As a reader, I can skip forward 15 seconds. | Covered | Tap +15. | Playback position moves forward and sentence state updates. |
| R05 | As a reader, the timer does not crowd the title row. | Covered | Inspect dock while playing. | Time stays with progress, not beside the title/status. |
| R06 | As a reader, I can complete a part and continue through Contents. | Covered | Let playback reach the end of a position. | Playback advances to the next available Contents position; at final end it pauses quietly with Contents/Library available. |
| R07 | As a reader, I can leave Reader and come back to the same Source position. | Covered | Navigate Library -> Reader after progress. | Source resumes from the saved elapsed time and active sentence. |
| R08 | As a reader, I can keep reading Original while generation/import work happens. | Covered | Trigger generation or import processing, then switch Original. | Text remains accessible; import states use honest Original placeholders until extraction succeeds. |

### Original, Retelling, And Trust

| ID | Story | Status | What to test | Expected behavior |
|---|---|---|---|---|
| T01 | As a reader, I can switch between Retelling and Original. | Covered | Tap Original, then tap Retelling. | Reader switches versions without losing position and does not open Retelling settings automatically. |
| T02 | As a reader, I know Original is available for trust. | Covered | Switch to Original. | Original copy appears and explains comparison. |
| T03 | As a reader, I can control how close the retelling stays to the Original. | Covered | Open Retelling settings, choose Closer/Balanced/Explain. | Draft changes until Save; closeness to Original is framed as retelling fidelity. |
| T04 | As a reader, I can compare the retelling with Original. | Covered | Tap Retelling/Original. | Reader switches versions from the same place without adding a separate compare panel. |
| T05 | As a reader, I can recover if the retelling feels wrong. | Covered | Tap the selected range, use Transform text or Mark problem. | Transform starts selected-text regeneration; Mark problem flags the same selected range that maps across Retelling and Original. |
| T06 | As a reader, I can ask for more explanation without turning the app into chat. | Covered | Open Retelling settings and choose Explain. | Explain is a retelling fidelity choice, not a separate reader action or chat thread. |

### Retelling Settings And Generation

| ID | Story | Status | What to test | Expected behavior |
|---|---|---|---|---|
| P01 | As a reader, I can open Retelling settings from an explicit control. | Covered | While Retelling is active, tap the sliders control beside the Retelling/Original switch. | Retelling settings opens with the current style, fidelity, and voice. |
| P02 | As a reader, I can change writing style compactly. | Covered | Open writing-style picker, choose style. | Draft updates; drawer stays manageable. |
| P03 | As a reader, style changes do not immediately replace the active retelling. | Covered | Change style, close drawer without Save. | Active retelling remains unchanged. |
| P04 | As a reader, I can change voice from recommended voices. | Covered | Open Choose voice, pick included voice. | Draft voice updates; Save becomes active. |
| P05 | As a reader, premium voice preview does not look selected. | Covered | Preview premium voice. | Preview reads as action; selected voice remains clear. |
| P06 | As a reader, Save settings starts generation from here. | Covered | Change Retelling settings, tap Save. | Drawer closes and reader-level generation begins. |
| P07 | As a reader, I can keep listening during retelling generation. | Covered | Trigger generation. | Reader remains usable; Original remains available. |
| P08 | As a reader, local generation can fail without losing the saved retelling. | Covered | First on-phone generation fails. | Saved retelling remains active. |
| P09 | As a reader, I can retry on phone. | Covered | Tap Retry on phone. | Generation restarts locally. |
| P10 | As a reader, I can choose cloud as an upgrade path. | Covered | Tap Try cloud (upgrade). | Cloud generation begins as upgrade path, not neutral fallback. |
| P11 | As a reader, I can cancel unresolved generation. | Covered | Tap Cancel in failed/ready state. | Pending change is discarded and current Performance remains. |
| P12 | As a reader, a ready retelling does not auto-switch. | Covered | Let generation finish. | Ready state waits for Use now. |
| P13 | As a reader, I cannot open Retelling settings while an unresolved decision blocks it. | Covered | Leave failed/ready banner unresolved, tap the Retelling settings control. | Drawer does not open until decision is resolved. |
| P14 | As a reader, I know whether Save applies globally, per Source, or from here. | Covered | Open Retelling settings, then Transform text from selected text or Rewrite from Contents. | Save settings says changes apply from here; Transform text supports selection, from-here, whole book/text, and background chapter/section rewrite scopes without hiding Original. |
| P15 | As a reader, I can queue or reject another Performance after one is ready. | Covered | Let a new retelling reach ready/failed state, then try opening Retelling settings. | Retelling settings are locked until the user uses, retries, or cancels the reader-level decision. |

## P1 Stories

### Voice, Offline, Cloud, And Premium

| ID | Story | Status | What to test | Expected behavior |
|---|---|---|---|---|
| V01 | As a reader, I can browse all voices from Settings without crowding Reader. | Covered | Open Settings -> Voice -> Voice catalog. | Full catalog appears outside Reader as a focused Settings subview. |
| V02 | As a reader, I can preview voices without selecting them. | Covered | Tap Preview on included/premium voice. | Preview does not change selected voice. |
| V03 | As a reader, I can identify included local voices. | Covered | Inspect Settings voice catalog. | Included/local labels are visible. |
| V04 | As a reader, I can identify premium cloud voices. | Covered | Inspect premium voices. | Premium/cloud/preview labels are visible and not selected-looking. |
| V05 | As a reader, I see only recommended included voices in the Retelling drawer. | Covered | Open Retelling settings, then Choose voice for this retelling. | Reader drawer shows a short included/offline list and links to Settings for the full catalog. |
| V06 | As a reader, I can download or manage local voice packs. | Covered | Tap Manage, then Retry download. | Settings represents removed, failed, retry, and downloaded states. |
| V07 | As a reader, I can continue offline with a local voice. | Covered | Use offline voice from cloud fallback. | Emma, an included local voice, becomes the active voice and playback remains available. |
| V08 | As a reader, cloud voice failure falls back to an included local voice. | Covered | Tap Use offline voice after viewing premium/cloud voice details. | App offers a local included voice and preserves retry-cloud copy. |
| V09 | As a reader, premium locked voices never block the core free path. | Covered | Open premium voice details and tap Upgrade to use. | Premium voice does not become selected; playback stays on an included local voice until upgrade. |

### Library, Continue, And Navigation

| ID | Story | Status | What to test | Expected behavior |
|---|---|---|---|---|
| L01 | As a reader, I can choose a starter public-domain book. | Covered | Tap a Library book. | Reader opens that book. |
| L02 | As a reader, the item I am reading now is prominent. | Covered | Return to Library. | Large Continue reading card reflects the active book or text. |
| L03 | As a reader, books do not look like audio snippets. | Covered | Inspect Library cards. | Cards use title/book metadata, not durations or generic Source labels. |
| L04 | As a reader, I can open Contents for the active book or text. | Covered | Tap Contents. | Contents sheet opens for the active book or text. |
| L05 | As a reader, Contents navigates the active book or text, not sample tabs. | Covered | Choose another Contents position. | Listening position updates in Reader. |
| L06 | As a reader, I can search public-domain books. | Contracted | Inspect the Library search area. | Search is visibly planned around the Gutenberg catalog index; the prototype does not fake results before implementation. |
| L07 | As a reader, I can share text into Understand. | Contracted | From another app, select text, open the OS share sheet, and choose Understand. | Native share is scoped to text-only V1 and remains a production/native integration path, not an in-app Library workaround. |
| L08 | As a reader, I can see recent/imported text separately from starter books. | Covered | Add or import text, then open Library. | Library groups Reading now, Your texts/imports, and Starter books. |
| L09 | As a reader, I can rewrite a chapter or Contents position in the background. | Covered | Open Contents and tap Rewrite on a chapter/position row. | The row stays separate from navigation, does not move the listening position, and marks that chapter or section as rewriting in the background. |
| L10 | As a free reader, I understand a rewrite may take time without needing a separate Contents panel. | Covered | Tap Rewrite on more than one Contents row. | Each row shows its own rewriting state, progress cue, and ETA while the reader can keep listening. |
| L11 | As a reader, I can decide when to use a prepared chapter rewrite. | Covered | Let a Contents row rewrite become ready. | The row shows Ready and waits for explicit Listen/Use instead of auto-switching playback. |
| L12 | As a reader, I can recover from or cancel a chapter rewrite. | Covered | Start a row rewrite, then cancel or trigger a fallback-position failure. | Cancel returns the row to Rewrite; failure offers Retry/Cloud and preserves the previous retelling. |
| L13 | As a reader, I can trust which style prepared a chapter rewrite. | Covered | Start a row rewrite, then change Retelling settings. | The row labels the saved style snapshot or says it was prepared with the previous style. |

### Import Quality And Recovery

| ID | Story | Status | What to test | Expected behavior |
|---|---|---|---|---|
| I01 | As a reader, weak structure produces fallback positions. | Covered | Import weak-structure file. | Fallback positions are clearly labeled. |
| I02 | As a reader, real EPUB chapters are preserved when available. | Covered | Import structured EPUB state. | Contents shows real chapters. |
| I03 | As a reader, poor OCR is explained. | Covered | Import poor-OCR state. | App warns text may be messy and offers retry/paste. |
| I04 | As a reader, empty extraction is recoverable. | Covered | Import empty-text state. | App explains no readable text was found and offers retry, choose another file, or paste clean text. |
| I05 | As a reader, file too large is recoverable. | Covered | Import oversized file. | App names the size limit and offers smaller file, split file, or cloud-later alternatives. |
| I06 | As a reader, processing can take minutes without blocking reading. | Covered | Long import state. | Reader-level status persists with cancel/return actions. |

## P2 Stories

### Selected Text And Annotations

| ID | Story | Status | What to test | Expected behavior |
|---|---|---|---|---|
| A01 | As a reader, I can highlight text in the reader. | Covered | Tap an active sentence/range, choose Highlight. | Highlight becomes an Annotation on the selected range using the default highlight treatment. |
| A02 | As a reader, I can add, edit, and discuss notes on selected text. | Covered | Tap an active sentence/range. Use Copy/Highlight/Share from the compact popover. Use Add note from the selected-range drawer, save a note, then reopen the saved mark from Library Notes and marks. Tap Edit note, Add another note, and Discuss with AI. | Native reader actions stay in the popover; Add note sits with Rewrite and Translate as an Understand-enhanced drawer action because saved notes can become AI discussions. Saved marks reopen in Reader with Retelling/Original still connected, and saved-note detail offers Edit note, Add another note, and Discuss with AI rather than threaded-reply copy. Rich AI discussion remains a later detail pass. |
| A03 | As a reader, highlighted text stays a reader mark without creating a new object. | Covered | Tap an active sentence/range, choose Highlight, then reopen the range menu. | The selected range remains highlighted; no separate save-as-Passage action appears. |
| A04 | As a reader, I can compare selected text to Original. | Covered | Open the range menu, switch Retelling/Original. | The same range remains highlighted across versions. |
| A05 | As a reader, I can share selected text later. | Covered | Tap an active sentence/range, choose Share, then choose a share option. | Share offers Retelling copy, Original copy, and share-card placeholder without creating a Passage object. |
| A06 | As a hands-free listener, I can add a voice note while audio ducks. | Covered | While listening, trigger the voice command state, review the selected current sentence, edit the transcript, and save. | The note is saved through the same selected-range annotation composer as touch Add note; real speech recognition remains later implementation. |
| A07 | As a hands-free listener, I can cancel or edit a captured voice note. | Covered | Trigger a voice command state, edit the transcript, then save or cancel. | The draft can be discarded or corrected without creating a broken Annotation. |
| A08 | As a hands-free listener, I can save a question about the current spot by voice. | Covered | Trigger the question voice command state and save the transcript. Reopen the saved mark and tap Discuss note. | The question attaches to the current sentence/range as an Annotation, with Original still reachable. Discuss is a later action on that saved Annotation. |
| A09 | As a hands-free listener, I can mark a problem by voice. | Covered | Trigger the Mark problem voice command state and save the transcript. | The current sentence/range is marked as a localized problem Annotation without immediately changing the retelling. |

### Onboarding And First-Run Proof

| ID | Story | Status | What to test | Expected behavior |
|---|---|---|---|---|
| O01 | As a first-time reader, I understand the promise quickly. | Covered | First launch. | Library states the promise and shows a first-listen path: play first, then compare, tune, annotate, and bring own text. |
| O02 | As a first-time reader, I can play a sample before setup. | Covered | Start sample. | Sample plays without account/setup friction. |
| O03 | As a first-time reader, I can compare Original after hearing easier text. | Covered | Switch Original during sample. | Original is accessible for trust. |
| O04 | As a first-time reader, I can try a persona without thinking it is a toy. | Covered | Open Retelling settings and inspect writing styles. | Accurate/Simple Modern stay first; personas are labeled as optional transformations with Original nearby. |
| O05 | As a first-time reader, I know importing my own text is next. | Covered | Complete or leave the first listening session and return to Library. | First-listen progress and Library actions make Paste text / Upload PDF/EPUB the next continuation, not a separate demo mode. |

Next B7 pass should test:

- Cold-open starts in Library/Continue.
- Public-domain starter books feel like whole texts.
- Play begins a real Reader listening session.
- Retelling/Original is available for trust without opening settings.
- Retelling settings remain optional until after first play.
- Import or share-your-own-text appears as a continuation, not a mode switch.
- Completion points to continue, Contents, or next listenable position rather than ending the demo.

### Settings, Privacy, And Account

| ID | Story | Status | What to test | Expected behavior |
|---|---|---|---|---|
| G01 | As a reader, I can manage voice defaults in Settings. | Covered | Open Settings -> Voice. | Default voice controls are outside Reader, while catalog and offline storage have their own subviews. |
| G02 | As a reader, I can understand local/cloud privacy. | Covered | Inspect included and premium voice detail. | Local/cloud privacy copy appears in voice detail; legal wording remains production work. |
| G03 | As a reader, I can manage downloaded models. | Covered | Toggle manage/download. | Settings shows removed, failed, retry, and downloaded states for the local voice pack. |
| G04 | As a reader, destructive actions are separated from listening. | Covered | Open Settings -> Storage and account. | Delete actions live in a focused Settings subview, not Reader or the Settings root. |
| G05 | As a reader, account deletion requires confirmation. | Covered | Tap Delete my account once, then again. | First tap arms confirmation; second tap opens the final confirmation placeholder without deleting from Reader. |
| G06 | As a reader, Settings is organized by recognizable objects. | Covered | Open Settings. | The top map exposes Voice, Reading, Accessibility, Retelling language, Plan, and Storage/account as separate jobs. |
| G07 | As a reader, accessibility controls visibly affect the Reader. | Covered | Open Settings -> Accessibility, then change Text size, Mode, High contrast, Reduced motion, or Reading spacing. | Reader text/chrome/spacing/motion changes immediately in the wireframe. |
| G08 | As a reader, placeholder settings do not look like unexplained primary actions. | Covered | Inspect Plan, language, catalog, and storage controls. | Deep or future controls are behind explicit panels, and Upgrade is labeled by status as a placeholder path. |

## V1 Closure Remaining Work

### Current Closure Status

Covered at wireframe level:

- All P0 stories.
- Retelling/Original trust, Retelling settings, generation conflict handling, and standard playback continuation.
- Import placeholder, processing, failure, retry, long-processing return, and weak-structure states.
- Selected text native popover plus Understand-enhanced drawer.
- Source-aware Annotation review, saved-note edit, add-another-note, bookmark variants, voice-created notes, and saved-note Discuss with AI handoff.
- Settings object routes for Voice, Voice catalog, Offline voices, Reading, Accessibility, Retelling language, Plan, and Storage/account.

Still implementation-owned:

- `L06` public-domain search: implement the Gutenberg catalog index and returned-field contract before showing real results.
- `L07` share text into Understand: implement text-only native OS share-extension behavior, not an in-app Library button.
- Rich AI discussion output: V1 keeps the saved-note-to-discuss handoff; full answer output is V1.1.

Final QA checklist:

- Run all P0 stories once in the current prototype.
- Run P1 stories with special attention to `L06` and `L07` being threshold decisions, not missing product screens.
- Confirm no UI introduces Passage, Chunk, demo mode, document-manager tabs, or a separate voice-notes object.
- Confirm production-only capabilities are named as thresholds rather than implied as working backend behavior.
- Saved-note detail now supports Edit note, Add another note, and Discuss with AI.
- Full note deletion, real speech recognition, headset/lock-screen/spoken-wake surfaces, and AI discussion output remain later states.

## Archived Batch Notes

The notes below record earlier batch groupings. They are useful for provenance, but the active next work is the V1 closure checklist above.

### Big Batch 1: Import Failure And Weak Structure

Design together:

- I01 weak structure fallback
- I02 EPUB real chapters
- I03 poor OCR
- I04 empty extraction
- I05 file too large
- S06 scanned PDF
- S07 password-protected PDF
- S09 cancel long import
- S10 retry import
- S11 choose another file

Review checkpoint:

- Does the user always know whether Understand is parsing, using fallback positions, or blocked?
- Does the UI avoid implying PDF/EPUB parsing works when it does not?
- Does every failure leave a practical next action?

### Big Batch 2: Compare, Trust, And Fidelity

Design together:

- T03 closeness-to-Original/fidelity clarity
- T04 compare via Original toggle
- T05 recover from bad retelling through selected-range actions
- T06 explain-more as Performance fidelity, not chat
- P14 Save scope clarity

Review checkpoint:

- Can a skeptical reader prove the original is preserved?
- Does fidelity feel like a clear Performance setting, not a separate reader tool?
- Do recovery actions attach to the same range as highlight/comment/save?

### Big Batch 3: Performance Persistence And Generation Rules

Design together:

- P12 ready Performance wait state
- P13 unresolved decision lock
- P14 per-book/text/global/from-here scope
- P15 queue/reject another Performance
- generation cancel/retry/cloud upgrade thresholds

Review checkpoint:

- Can the user tell what is active, what is draft, what is generating, and what is ready?
- Are long jobs visible without trapping the user?

### Big Batch 4: Offline, Cloud, Premium, And Voice

Design together:

- V05 favorite/recommended voice rules
- V06 download model failure/storage states
- V07 offline local voice
- V08 cloud fallback
- V09 premium path without blocking free path

Review checkpoint:

- Does the free/local path always keep the reader listening?
- Does premium feel like quality/power, not a broken core feature?

## Handoff Requirements For Every Prototype Pass

Every pass should end with:

1. Changed files.
2. What changed in the wireframe, object model, flow, or state rules.
3. What did not change, especially anything visual/polish-related that remains intentionally out of scope.
4. Change -> user story -> test steps -> expected behavior map.
5. Explicit note when behavior is placeholder/fallback rather than real extraction, generation, or parsing.

## B7 Patch Test Checkpoint - 2026-07-06

Current prototype coverage added in `index.html`:

- O02 / R01: Library book cards and Continue now begin playback immediately after opening Reader.
- O01 / L01: Starter book cards now read as whole public-domain works with Contents continuity, not timed demo snippets.
- O05 / R06: Completion now offers a next-step action instead of ending at a static message.

Run these checks before expanding B7:

| Check | Steps | Expected behavior |
|---|---|---|
| First play from Library | Cold-open the prototype and tap Alice, Hamlet, Frankenstein, Sherlock, or Meditations. | Reader opens and audio state changes to listening without requiring Retelling settings, notes, import, or account setup. |
| Whole-text starter cues | Inspect Library starter cards. | Cards identify books/works by title and continuity cues, not durations or sample-clip language. |
| Continue after completion | Let playback reach completion, then tap Continue next. | The current position advances to the next Contents item and playback starts again. |
| Trust path remains available | While listening, switch between Retelling and Original. | The user stays in the same reader position and Original remains available for comparison. |

## End-Of-Section Direction - 2026-07-06

Do not prioritize a special end-of-section design pass next.

For now, the intended product behavior is standard continuous playback: if another part/section is available, listening should keep going until the user pauses, stops, or chooses another position. Treat visible completion UI in the current wireframe as temporary scaffolding, not the target product behavior.

Next tests should focus on:

- Shared text entering the same Reader/listening-session model in a preparing state.
- Import/fallback honesty for files that are not actually parsed yet.
- Selected-text notes, highlights, comments, and problem marks as Annotation behavior.
- Retelling/Original trust actions staying attached to the same selected range.

## Shared Text And Continuous Playback Patch - 2026-07-06

Prototype coverage added in `index.html`:

- Shared text now enters the same Reader/source model from the Add text sheet.
- Shared text appears immediately with Original available while Retelling prepares.
- Section playback now advances to the next available Contents position instead of stopping at every section as a special completion moment.
- The old completion panel is hidden as scaffolding; it should not be treated as the target product behavior.

Run these checks:

| Check | Steps | Expected behavior |
|---|---|---|
| Shared text entry | Use the OS share sheet from another app and choose Understand. | Native share extension work remains open; the Library should not show an in-app shared-text button. |
| Shared text ready state | After native share extension support exists, send selected text into Understand. | Shared text should enter the same Source/Reader model with Original available and Retelling preparation visible. |
| Continuous playback | Start a starter book and let the current position reach the end. | Playback advances to the next available Contents position instead of presenting a required completion decision. |
| Final fallback | Reach a source with no later position. | Playback pauses quietly; the user can use Contents or Library when ready. |

## Settings Routed Subviews Patch - 2026-07-07

Prototype coverage added in `index.html`:

- Settings root now routes to focused object subviews instead of scroll-jumping through a crowded settings stack.
- Voice management is split into Voice, Voice catalog, and Offline voices.
- Reading and Accessibility are separate testable jobs instead of one mixed section.
- Plan and Storage/account are separated so destructive actions do not sit under the upgrade card.
- Retelling settings now names its scoped action as choosing a voice for this retelling, while full voice catalog management remains in Settings.

Run these checks:

| Check | Steps | Expected behavior |
|---|---|---|
| Settings root is a map | Open Library, tap Settings. | Settings shows root cards for Voice, Reading, Accessibility, Retelling language, Plan, and Storage/account, with no full catalog or destructive controls visible at root. |
| Back behavior is local first | Tap Voice, then tap the top-left Settings button. | The view returns to Settings root. Tapping Library from root exits Settings. |
| Voice catalog is a focused subview | Open Settings -> Voice -> Voice catalog. | Included and premium voices appear with detail/preview behavior, and Reader Performance is not changed unless Use voice is chosen. |
| Offline voice storage is separate | Open Settings -> Voice -> Offline voices. | Local pack and cloud fallback controls appear without the full catalog crowding the view. |
| Reading and Accessibility are distinct | Open Reading, then Accessibility from root. | Reading shows continue/autoplay/speed/skip controls. Accessibility shows text size, mode, contrast, reduced motion, and spacing. |
| Retelling drawer deep-links correctly | Open Reader Retelling settings, then tap Open full voice catalog in Settings. | Settings opens directly to Voice catalog, and the Retelling drawer wording reads as a current-retelling voice choice, not favorite management. |

## Final Library Grid And Copy QA - 2026-07-08

Prototype coverage confirmed in `index.html`:

- Library keeps one dominant Continue listening card and a compact two-column starter-book grid.
- Starter books remain visually secondary to the current/starting item without becoming a vertical shelf/list.
- Visible UI copy no longer uses Passage object language in playback controls, sharing, voice privacy, voice catalog descriptions, or sample retelling text.
- Internal implementation names may still use passage-related identifiers where they do not appear in product copy.

Run these checks:

| Check | Steps | Expected behavior |
|---|---|---|
| Library grid remains intact | Cold-open Library and inspect the book area. | One large Continue listening card sits above compact starter-book cards arranged as a two-column grid. |
| Starter books stay secondary | Compare Alice/Continue against Hamlet, Frankenstein, Sherlock, and Meditations. | Alice/Continue is the dominant starting item; starter books are compact choices, not a document shelf or oversized list. |
| Visible Passage language is gone | Inspect playback controls, Share selection, voice details, and starter retelling copy. | User-facing copy refers to text, reading, selection, or audio rather than a Passage object. |
| Search/index honesty remains | Inspect Library search and Paste/Upload paths. | Public-domain search stays planned around the Gutenberg catalog index until implementation; Paste and Upload remain the real continuation actions. |

## Reader And Import QA - 2026-07-08

Prototype coverage confirmed in `index.html`:

- Reader playback controls are wired for play/pause, skip back, skip forward, progress, completion, and Continue next.
- Retelling/Original switching preserves the current position and keeps Original available during generation/import work.
- Paste and Upload open the intake sheet, gate the primary action until there is enough text or a selected file, and route into Reader.
- Import processing, ready, failed, retry, choose-another-file, cancel, and long-file return paths are wired at static wireframe level.
- Visible Import/Reader copy now avoids capitalized Source object language; user-facing states talk about text, file, reading, playback, or import recovery.

Run these checks:

| Check | Steps | Expected behavior |
|---|---|---|
| Reader playback | Open Reader, tap Play/Pause, -15, and +15. | Playback state, active sentence, progress, and timecode update without losing position. |
| Original trust path | Tap Original during normal playback and during a preparing/rewriting state. | Original remains visible from the same position; Retelling settings do not open automatically. |
| Continue next | Let a position complete, or tap Continue next when visible. | Playback advances to the next Contents position when one exists; otherwise the user can use Contents or Library. |
| Contents background rewrite | Open Contents, tap Rewrite on a non-current chapter/position. | Contents stays open, the reader does not move, and the row changes to Rewriting with progress and ETA. |
| Multiple rewrites | Open Contents, tap Rewrite on two different rows. | Each row independently shows background rewriting status without a separate Contents panel. |
| Rewrite ready state | Let a Contents row rewrite finish. | Row changes to Ready and offers explicit Listen/Use without auto-applying. |
| Rewrite failed/cancel state | Fail or cancel a Contents row rewrite. | Row offers Retry/Try cloud when failed, or returns to Rewrite when canceled. |
| Rewrite style snapshot | Start a row rewrite, change Retelling settings, then reopen Contents. | Row identifies the style used to prepare that rewrite and marks previous-style output when needed. |
| Playback reaches preparing row | Start a rewrite for the next row, then continue playback before it finishes. | Playback continues with the existing retelling and shows a quiet still-preparing cue. |
| Rewrite return cue | Start multiple row rewrites, then close Contents. | Contents button shows a small count and the audio row summarizes preparing/ready work without opening a separate management surface. |
| Paste intake | Tap Paste text, enter at least eight words, tap Continue. | Reader opens at the first listenable position with Retelling and Original connected. |
| Import recovery | Choose filenames containing `scanned`, `empty`, `password`, `timeout`, or `large`. | Reader shows honest preparing/failure/retry states; Retry and Choose another file remain available without treating fallback text as real extraction. |

## Annotation And Voice/Settings QA - 2026-07-08

Prototype coverage confirmed in `index.html`:

- Selected-text popover actions are wired for Copy, Highlight, and Share without creating a separate saved object.
- Understand-enhanced selected-range drawer actions are wired for Rewrite selection, Translate selection, Add note, and Mark problem.
- Saved annotation detail supports Edit note, Add another note, and Discuss with AI handoff while keeping Retelling and Original connected.
- Voice-command capture saves note, question, and problem states through the same annotation composer as touch input.
- Settings voice catalog distinguishes included/local/offline voices from premium/cloud preview voices, and premium voices do not block the included local path.
- Offline voice pack, cloud fallback, accessibility controls, and account/storage confirmation paths are wired at static wireframe level.
- Visible Settings copy now refers to Reader text instead of passage text.

Run these checks:

| Check | Steps | Expected behavior |
|---|---|---|
| Selected-text native actions | Tap a sentence, then use Copy, Highlight, and Share. | Native actions stay in the compact popover; Share opens selected-range options without creating a separate saved object. |
| Annotation detail | Add a note, save it, reopen Notes and marks, then use Edit note, Add another note, and Discuss with AI. | Saved marks reopen the Reader at the same range; follow-up actions stay attached to that range. |
| Voice-created annotation | Use the Mic button repeatedly for note, question, and problem capture states. | Captures use the same composer and save back to the selected/current sentence range. |
| Voice catalog and fallback | Open Settings -> Voice catalog and Offline voices. Preview premium voices, use included voices, manage pack download, and tap Use offline voice. | Premium previews never become selected by accident; local included voice remains the working fallback. |
| Accessibility and account | Open Accessibility, toggle text/mode/contrast/motion/spacing, then open Storage/account and tap Delete my account twice. | Reader accessibility state changes immediately; destructive account action requires a confirmation step and does not delete from Reader. |