# Understand Feature Roadmap

Last updated: 2026-07-08

This is the working roadmap for the Understand prototype. It tracks product ideas, unresolved design risks, user stories, jobs-to-be-done, and the next Open Design deliverables. It is not an implementation spec yet.

## Canonical Product Vision

Use `product-vision.md` as the North Star source for Understand's purpose, emotional promise, first-run goals, Library/content direction, trust goals, growth goals, and open tensions.

Use `DESIGN.md` as the interaction/copy/component design-system layer for future prototype work. Keep roadmap items here focused on bets, batches, unresolved risks, and next deliverables rather than restating the full vision.

## Current Direction

Understand is moving from a generic reader utility toward an active comprehension and listening stage.

Settled principles:

- Internal root object is the active Source; visible UI should say book, text, Original, retelling, selected text, or a direct action.
- Primary spine is Retelling / Original.
- Retelling / Original is a stable view switch. Retelling settings opens only from an explicit adjacent sliders control while Retelling is active.
- Primary payoff is playing the active version.
- Voice, style, and fidelity belong in a contextual Retelling settings sheet.
- Reader drawer shows recommended voices only.
- Settings -> Voice -> All voices owns the comprehensive catalog.
- Library / Continue replaces bottom Reader / History navigation.
- Premium improves quality and power; it should not block the local core.
- Samples prove the promise before asking for setup.
- First-run should feel like a real listening session, not a miniature demo object.
- Public-domain starter books should imply whole-text continuity rather than throwaway excerpts.
- Growth reels should seed the same aha moment the product delivers: recognition, freshness, and continued listening.

## Canonical Test Story Inventory

Use `test-stories.md` as the working wireframe/OOUX story map for design batches, review checkpoints, and prototype handoffs. It groups the product into P0/P1/P2 test stories and defines the next large batches:

- B1 Import failures and weak structure.
- B2 Compare, trust, and fidelity.
- B3 Performance persistence and generation rules.
- B4 Voice, offline, cloud, and premium.
- B5 Library, Continue, and source navigation.
- B6 Selected text actions and Annotations.
- B7 Onboarding and first-run proof.
- B8 Settings and account boundaries.

Every prototype pass should cite the story IDs it changes and end with a change -> test steps -> expected behavior map.

Use `v1-flow-next-plan.md` as the current execution spine for closing the v1 wireframe. It orders the remaining batches, defines exit criteria, and lists pivot questions.

Current design mode: comprehensive core wireframes first. Review object model, core user flows, state coverage, and layout hierarchy before spending time on visual design, typography, color, illustration, or polish.

B2 status: simplified wireframes use the Retelling/Original toggle for comparison, Retelling settings for Closer/Balanced/Explain fidelity, selected-range Rewrite, and Contents-row Rewrite for chapter/section transformation. Retelling now switches view without auto-opening settings. P14 is covered at wireframe level through explicit Save-from-here copy, selected-range Transform scope choices, and chapter/section scope from Contents.

Selected text action status: selected text now uses two surfaces. Copy, Highlight, and Share sit in a compact e-reader-style popover anchored to the selected range. Rewrite selection, Translate selection, Add note, and quiet Mark problem live in the bottom selected-range drawer as Understand-enhanced actions. Add note is treated as AI-enhanced because saved notes can later become AI discussions. Discuss remains a later action on saved annotations, not a second creation path. Saved notes can be edited, another note can be added to the same selection, and Discuss with AI can be started from the saved-note state. Voice commands still converge on the same source-aware Annotation behavior. Rich AI discussion is deferred to V1.1; native share is scoped to text-only V1.

V1 closure status: the current wireframe covers all P0 stories and the selected-text/Annotation depth needed for V1 review. Library visual QA now passes with one dominant Continue listening card and compact starter-book grid. Reader, Contents, Import/Paste, Annotation, and Voice/Settings QA now pass at static wireframe level, including row-level background chapter/section rewriting from Contents for long free-user preparation. Production thresholds, Library growth, native share scope, AI discussion scope, and implementation contracts are documented. Final render QA caught and fixed stale search-source copy. Remaining work is implementation handoff.

## Next North-Star Alignment Pass

After V1 closure QA, revisit B7: Onboarding and first-run proof only if the final story run shows the first session still teaches the wrong product model. The goal is not visual redesign; it is to test whether the current prototype teaches the right product model.

Audit reference: `b7-first-run-audit.md`.

B7 should answer:

- Does cold-open begin from Library/Continue rather than a standalone demo?
- Can a starter public-domain book move directly into a real listening session?
- Does first play happen before account setup, voice setup, notes, highlights, or advanced controls?
- Does the user understand that Retelling is accountable to Original?
- Does the experience imply a whole text worth continuing, not a one-off excerpt?
- Does the first-run aha moment feel like difficult text becoming living, listenable, and worth continuing?

Adjacent follow-up batches:

- B5 Library, Continue, and source navigation, because B7 depends on Library being the entry root.
- B3 Retelling settings persistence and generation rules, because first-run should not teach settings behavior that later breaks.
- B6 Selected text actions and Annotations, because secondary tools should remain discoverable after the listening session is established.

## Idea Intake

Add raw ideas here first before turning them into designed stories.

| Date | Idea | Source | Status |
|---|---|---|---|
| 2026-07-03 | Keep a canonical feature roadmap / backlog inside the Open Design project. | Conversation | Added |
| 2026-07-03 | Personify has a contextual Performance drawer with separate Style and Voice sections. | Conversation | Superseded by Retelling settings direction |
| 2026-07-03 | Personify should keep a compact current setup summary, but each summary term must map to a visible control in the drawer. | Conversation | In prototype |
| 2026-07-03 | Settings voice catalog should be organized by model first, then voices with use cases and labels. | Conversation | In prototype, needs deeper wireframes |
| 2026-07-03 | Reader voice options should correspond to Settings voice catalog voices, but only show recommended voices. | Conversation | In prototype |
| 2026-07-03 | Reader dock should include 15 second back and forward controls. | Conversation | In prototype |
| 2026-07-03 | Playback timer should not compete with the audio title/status row. | Conversation | In prototype |
| 2026-07-03 | Library should eventually search public-domain ebook sources. | Conversation | Backlog |
| 2026-07-06 | Selected text should open one e-reader-style action menu grouped by Reader, Understand, and Keep intents without introducing a separate Passage object during this OOUX pass. | Conversation | First pass in prototype |
| 2026-07-06 | Switching Original -> Retelling should only change the view; Retelling settings should open from an explicit adjacent sliders control while Retelling is active. | Conversation | In prototype |
| 2026-07-06 | Personify is a verb/action idea, not the visible name for the generated version or settings object. | Conversation | Decision logged |
| 2026-07-06 | Keep `product-vision.md` as the canonical North Star and use `DESIGN.md` for interaction/copy/component posture. | Conversation | Added |
| 2026-07-06 | Distill stable product-vision claims into test stories and verified rules instead of stuffing the entire vision into memory. | Conversation | Added |
| 2026-07-06 | B7 audit found the first listening moment is one tap too late: Library card selection opens Reader but does not start playback. | `b7-first-run-audit.md` | Patched |
| 2026-07-07 | Settings should be object-led, not a dense control drawer: Voice, Reading, Accessibility, Retelling language, Plan, and Storage/account each need one clear job. | Settings IA audit | Prototyped |

## Priority Roadmap

### P1 - Lock Reader Retelling Settings Drawer

Design the contextual sheet opened from the Retelling settings control while Retelling is active.

Status: prototype pass updated. Current prototype uses `Retelling / Original` as the stable view switch, with a small adjacent sliders icon for Retelling settings. The sheet is titled Retelling settings, shows the active retelling summary ("Accurate - Balanced - Zoe"), makes the from-here scope plain text under that summary, keeps selected voice and Preview above the fold, and lets writing style, fidelity, and voice edits form a pending setup. Writing style is now a compact selected row that opens a grouped picker for Clear rewrites, Guided listening, and Personas. Save closes the drawer and starts a reader-level on-phone generation banner, because free generation may take several minutes. The reader banner now supports Cancel, local failure, Retry on phone, Try cloud (upgrade), ready-but-not-applied, and Use now. The Retelling settings drawer cannot open while a failed/ready reader decision is unresolved. The longer favorite/premium voice list is behind Choose voice, while the full catalog stays in Settings.

Must cover:

- Version context: Retelling / Original.
- Explicit settings entry point that is separate from the Retelling/Original view switch.
- Compact saved setup summary that explains writing style, fidelity, voice, and from-here scope without turning the summary into a button.
- Writing style: Accurate Modern, Simple Modern, Patient Professor, Dramatic Storyteller, Drunk Uncle, Very Online Gen Z, Influencer.
- Style taxonomy: utility styles should use accurate, succinct labels/descriptors; persona styles can be more characterful when the frame is helpful or cool for readers.
- Recommended/favorite voices only.
- Selected voice above the fold.
- Voice preview.
- Bottom-sticky Save action that applies the pending setup to this book or text from here and shows generation status.
- Reader-level generation status for long on-phone generation.
- Local / cloud / premium labels.
- All voices link into Settings.
- Fidelity control or a clear decision to defer it.

Open questions:

- Does fidelity live in this drawer or in a compare/trust drawer? Current pass tests it in the drawer.
- Should saved defaults apply globally, per book, or per source type?
- Should Save pause playback, queue behind current audio, or replace audio immediately after generation?
- Can recommended voices include locked premium voices, or should locked voices only appear in Settings? Current pass tests one locked premium recommendation with preview-only styling.
- Should Original and Retelling be able to use different voices?

JTBD:

> When I change how this book or text sounds, I want to choose a listening feel, not a TTS backend.

Needed wireframes:

- Retelling settings drawer, default state.
- Reader drawer, voice preview state. Covered in current prototype pass.
- Reader drawer, locked premium voice state. Covered as preview-only inside the disclosed favorites list.
- Reader drawer, "All voices" link to Settings.
- Save retelling settings from here state. Covered in current prototype pass; needs persistence rules.
- Background generation banner. Covered with cancel, failure, retry, cloud-upgrade fallback, ready, and use-now states; needs real timeout/error thresholds later.
- Style picker modal. Covered with a compact selected style row and grouped picker; needs style preview examples later.

### P2 - Design Settings -> Voice -> All Voices

Create the comprehensive voice catalog.

Status: prototype pass in progress. Current prototype turns Settings -> Voice into an All Voices library with a current default summary, model-first groups, included Supertonic local voices, premium Kokoro / Orpheus cloud voices, preview-only premium handling, a voice detail panel, favorite management, and a Supertonic local pack download/manage state.

Must cover:

- Model-first organization.
- Included voices.
- Premium voices.
- Downloaded voices.
- Available downloads.
- Advanced details.
- Voice detail sheet.
- Preview locked premium voices.
- Download model action.

Voice labels to include:

- Provider / model.
- Local / cloud.
- Included / premium.
- Downloaded / not downloaded.
- Download size when known.
- Language / accent.
- Quality or source grade when known.
- Preview availability.
- Privacy behavior.
- Usage limits when applicable.

Known included/local Supertonic voices:

| App voice | Source voice | Description |
|---|---|---|
| Emma | F1 | Calm, steady, composed female voice. |
| Sarah | F2 | Bright, cheerful, playful female voice. |
| Olivia | F3 | Clear, professional announcer-style female voice. |
| Chloe | F4 | Crisp, confident, expressive female voice. |
| Zoe | F5 | Kind, gentle, soft-spoken, soothing female voice. |
| James | M1 | Lively, upbeat male voice with confident energy. |
| David | M2 | Deep, robust, calm, serious male voice. |
| Alex | M3 | Polished, authoritative, trustworthy male voice. |
| Ryan | M4 | Soft, neutral, gentle, approachable male voice. |
| Chris | M5 | Warm, soft-spoken, calm storytelling male voice. |

Known premium/cloud voices:

| App voice | Provider/model | Known details |
|---|---|---|
| Heart Cloud | Kokoro af_heart | American English, female, overall grade A. |
| Michael Cloud | Kokoro am_michael | American English, male, overall C+. |
| Alice Cloud UK | Kokoro bf_alice | British English, female. |
| Lewis Cloud UK | Kokoro bm_lewis | British English, male. |
| Tara Orpheus | Orpheus tara | Expressive Orpheus voice; first/default conversational realism order. |
| Leo Orpheus | Orpheus leo | Expressive Orpheus voice; male Orpheus voice. |

JTBD:

> When I want control, I need one place to browse, preview, download, and understand all voice options without cluttering the reader.

Needed wireframes:

- Settings voice landing. Covered in current prototype pass.
- All voices list. Covered in current prototype pass.
- Voice detail sheet. Covered in current prototype pass.
- Download model flow. Covered as a lightweight manage/download state; needs real storage-size and failure states later.
- Premium voice locked state. Covered as preview-only premium cards and detail actions.
- Privacy/detail disclosure. Covered in the detail panel; needs final legal/privacy wording later.

### P3 - Design Long Text Intake And Source Lifecycle

Define how real user content becomes a book or text the reader can start listening to from a sensible first position.

Status: prototype pass updated. Library now frames starter books, pasted text, and imported files with reader-facing labels. Intake is labeled Create a source with a Create source action. Pasted text creates a custom Source internally using the pasted sentences; selected files create a processing-style Source internally using the file name and fallback positions. File imports now open Reader in a Source preparing state before resolving to Ready to listen. Reader opens at the first listenable position, the Library Continue reading card updates, and Contents can move the listening position. Reader completion points users back to Contents for the next real position instead of asking them to paste/import from the reader.

Big Batch 1 status: first-pass wireframes added for import failure, weak structure, scanned/image-only PDFs, password-protected PDFs, messy OCR, large-file processing, Cancel import, Retry, Remove source, and choose-another-file states. Keep the prototype honest: when extraction is not implemented, the UI should show processing/fallback behavior rather than parsed PDF/EPUB text.

Prototype note: filename-based import scenarios are test-only triggers for the static HTML wireframe. Production behavior must use parser results, file metadata, size limits, and extraction confidence, not filenames.

Remaining B1 questions: define real backend thresholds for empty extraction, file-too-large, scanned/image-only, weak OCR, and password-protected states; decide whether canceled imports disappear or remain queued in Library.

Must cover:

- Paste short text.
- Paste long essay.
- Import PDF.
- Import EPUB.
- Share text from Safari, Notes, Kindle, or Files.
- Extraction/loading. Covered as a reader-level processing banner for placeholder import; needs real extraction progress later.
- First listenable position selected.
- Continue with the next section or generated range after completion.
- Continue reading card updates after user-added text or imported file.

Design constraints:

- Do not present fallback sections as real chapters; label weak structure honestly until real source structure exists.
- Avoid user-facing words like chunk, segment map, section id, or paragraph batch.
- Prefer from here, next chapter/section when real structure exists, and continue where you left off.

JTBD:

> When I give Understand a long document, I want it to choose a sensible listenable piece so I can start understanding without managing document structure.

Needed wireframes:

- Paste intake, short text. Partially covered in current prototype.
- Paste intake, long essay. Covered as pasted text with generated fallback Contents; needs real background processing states later.
- PDF import confirmation. Covered as selected-file import with processing then fallback structure; needs extraction-quality states later.
- EPUB import confirmation. Covered as selected-file import with processing then fallback structure; needs real chapter preservation later.
- Long text loaded with first listenable position selected.
- Next part transition after completion. Partially covered in current prototype through Contents-forward completion copy.

### P4 - Design Offline, Cloud, and Premium Fallback States

Make the local/free path resilient.

Must cover:

- Offline with local voice selected.
- Offline with cloud voice selected.
- Cloud synthesis failure.
- Premium voice unavailable.
- Switched to included local voice.
- Download required state.
- Retry cloud voice.
- Continue with local voice.

Desired fallback copy:

> Cloud voice unavailable. Switched to Emma, an included offline voice.

JTBD:

> When I lose connection, I still want to keep listening if an offline voice is available.

Needed wireframes:

- Offline banner/inline state.
- Cloud voice fallback toast or sheet.
- Download required state.
- Retry cloud voice.
- Continue with local voice.
- Text too long / rate limited / timeout states.

### P5 - Design Selected Text Actions, Trust, Voice Notes, and Annotations

Support trust and reader marking without letting comparison or annotation tools take over the listening experience.

Status: selected text now splits native reader actions from Understand-enhanced actions. Copy, Highlight, and Share stay in a small anchored popover so the interaction feels like mobile text selection instead of a flat tool menu. Rewrite selection, Translate selection, Add note, and quiet Mark problem live in the bottom drawer. Add note remains an Annotation creation action and is also AI-enhanced because saved notes can be discussed with AI later. Discuss appears after an annotation exists, using the saved note plus selected range, surrounding text, Original, Retelling, and book metadata. Saved note detail now favors Edit note, Add another note, and Discuss with AI over reply/thread language. Voice commands still save into the same source-aware Annotation model; Library Notes/marks can reopen the saved range in Reader.

Must cover:

- Compare with Original. Covered through the Retelling/Original toggle.
- Closeness-to-Original / fidelity label. Covered through Retelling settings copy.
- Closer-to-original adjustment. Covered through Retelling settings fidelity.
- Explain-more adjustment. Covered through Explain fidelity in Retelling settings.
- Transform selected text and rewrite Contents positions. Covered as scoped first-pass generation trigger for selected text/from-here/whole-book changes, plus row-level background rewriting for chapter/section rows in Contents.
- Mark localized problem. Covered through selected-range menu.
- Voice note capture while listening. Covered at wireframe level: in-app mic command opens the selected-range annotation composer; saved transcript creates the same Annotation object as Add note. Real speech recognition remains later.
- Voice question capture while listening. Covered at wireframe level: voice command opens the selected-range composer; captured question/comment anchors to the current range as an Annotation without turning the reader into chat.
- Voice problem marking. Covered at wireframe level: voice command opens the selected-range composer; saved problem mark anchors to the current sentence/range and does not immediately change output.
- Copy selected text. Covered.
- Highlight selected text. Covered.
- Add note/question/bookmark review. Covered at wireframe level: selected-range note/question composer, Bookmark variant, Library Notes/marks review, source-aware reopen behavior, saved-note edit/add-another-note actions, and saved-annotation Discuss handoff. Rich AI discussion output is deferred to V1.1.
- Listen to selected text. Covered.
- Share selected text. Covered at wireframe level: selected-range Share offers Retelling copy, Original copy, and share-card placeholder; production OS share remains open.
- Original playback state. Covered.
- Retelling playback state. Covered.
- Return to Retelling listening.

Key distinction:

- Version = Original / Retelling.
- Writing style = Accurate Modern, Simple Modern, Patient Professor, Dramatic Storyteller, humorous archetypes, etc.
- Fidelity = close / explanatory / looser.

JTBD:

> When the text is rewritten, I want to trust that I can get back to the original and control how much it changes.

> When I am listening hands-free, I need to capture thoughts, questions, and problems by voice without stopping the session.

Needed wireframes:

- Paragraph-level compare or deeper alignment, if current-sentence comparison is not enough.
- Global/default retelling settings scope rules.
- Original playback state.
- Retelling playback state.
- Hands-free voice command capture through the selected-range annotation sheet, anchored to the current sentence while audio ducks.
- Voice-note confirmation/edit/cancel state that saves the same Annotation object as touch Add note. First pass covered.
- Voice question and Mark problem command states for the current sentence/range, without creating a separate voice-notes menu. First pass covered.
- Two-surface selected-text interaction: compact popover for Copy/Highlight/Share; bottom drawer for Rewrite, Translate, Add note, and Mark problem. First pass covered; saved-annotation Discuss handoff exists, while deeper AI discussion states are V1.1.
- Scope rules for regeneration: selected range, from here, whole book/text, and row-level background chapter/section preparation from Contents.

Selected-text action flow audit:

- Copy: compact popover action; instant clipboard utility with no durable object.
- Highlight: compact popover action; toggles an Annotation on the selected range.
- Share: compact popover action; opens selected-range share options without creating a Passage object.
- Rewrite selection: drawer action; starts a selected-range generation job.
- Translate selection: drawer action; keeps Original connected.
- Add note: drawer action; opens the Annotation composer and is AI-enhanced because the saved note can later become a discussion.
- Discuss with AI: later action on saved annotations; AI explanation output remains v1.1 or production design.
- Voice note: captures dictated text against the current sentence/range and offers a lightweight confirmation, edit, or cancel path.
- Mark problem: quiet drawer action; records a localized quality/recovery annotation and keeps output unchanged.
- View Original / View Retelling: switches comparison view while keeping the selected range active.

## Secondary Roadmap

### Import Errors and Extraction Quality

Stories:

- PDF import succeeds.
- PDF has poor OCR.
- PDF is scanned/image-only.
- PDF is password-protected.
- EPUB has chapters.
- File is too large.
- Extraction produces bad text.
- User needs paste instead.

JTBD:

> When import fails or text extraction is messy, I want a clear next step instead of a dead end.

### Ask / Extra Help / Secondary Comprehension Tools

Stories:

- User asks a question about the source.
- User highlights a confusing line.
- User asks for key terms.
- User asks for section gist.
- User asks for context.
- User wants risks/implications for legal or business text.
- User wants the answer read aloud.

Constraint:

- Extra help stays secondary after the rewrite/listening loop.

JTBD:

> After I hear the easier version, I may need one extra explanation, but I do not want the app to become a generic chatbot.

### Completion / Session End / Continue Next

Stories:

- Current listening range completed.
- Continue to next chapter, section, or generated range.
- Replay.
- Compare original after completion.
- Save to Continue.
- Stop and resume later.

JTBD:

> When I finish listening, I want the next useful action to be obvious.

### Library / Continue / Search / Organization

Stories:

- Search library/history.
- Search public-domain ebook sources.
- Filter by source type.
- Delete/archive item.
- Rename item.
- Resume exact passage/time.
- Distinguish source document from generated/listened sessions.

JTBD:

> When I return later, I want to find the thing I was listening to and continue without remembering where I left off.

### Privacy, Trust, and Local-vs-Cloud Disclosures

Required labels:

- Local: local, works offline, text stays on device.
- Cloud: cloud, requires internet, text is sent to generate audio/rewrite.

JTBD:

> When I use sensitive text, I want to know whether it stays on my device.

### Accessibility and Reading Support

Stories:

- Larger text.
- Dyslexia-friendly type / spacing.
- High contrast.
- Reduced motion.
- Captions / active sentence highlight.
- Speed controls.
- Scrubbing / back 15 / forward 15.

JTBD:

> When reading is hard for me, I need the visual and audio controls to reduce friction, not add it.

## Next Design Deliverables

1. Implementation handoff using `v1-production-threshold-handoff.md` and `v1-implementation-contracts.md`.
2. Visual design pass only after final QA confirms the wireframe/OOUX model.

## Current Next Batch Direction - 2026-07-07

Do not make end-of-section behavior the next batch. Standard playback should continue through available text until the user pauses or chooses another position.

Execution plans:

- `v1-flow-next-plan.md` - broad flow-next spine.
- `v1-closure-triple-batch.md` - active triple-size V1 closure batch.
- `contents-background-rewrite-plan.md` - Contents row-level Rewrite lifecycle, playback-arrival rules, free/cloud delay policy, persistence cues, storage cleanup, and weak-structure import handling.

Closure audit update - 2026-07-08:

- P15, R06, R08, S12, L08, A02, and O04 are now covered at wireframe level.
- Library visual QA passes: one dominant Continue listening card, compact two-column starter-book grid, Paste/Upload actions below, and paused search kept honest.
- Reader and Import/Paste QA passes: playback controls, Original/Retelling switching, Continue next, paste intake, import processing, failed import recovery, retry, choose-another-file, cancel, and long-import return paths are wired.
- Annotation and Voice/Settings QA passes: selected-text popover, annotation composer/detail/follow-ups, voice-created annotations, voice catalog, local/cloud labels, offline fallback, accessibility controls, and account/storage confirmation paths are wired.
- Visible product copy no longer exposes Passage object language in playback controls, sharing, voice privacy, voice descriptions, or sample retelling text.
- Visible Import/Reader copy no longer exposes capitalized Source object language in user-facing states.
- Visible Settings copy now says Reader text instead of passage text.
- Library growth decision is complete: V1 public-domain search uses a Project Gutenberg catalog index; Open Library and OPDS are deferred to enrichment/adapter layers.
- Native share scope decision is complete: V1 native share is text-only; PDF/EPUB native file share is deferred until the extraction threshold work is implemented.
- AI discussion scope decision is complete: V1 keeps the saved-note-to-discuss handoff; rich answer output is V1.1.
- Implementation contracts are documented for public-domain search results, text-only native share payloads, Contents background rewrite payloads, and saved-annotation Discuss handoff payloads.
- Final rendered Library QA confirmed the dominant current-listening card plus starter-book grid; stale disabled-search copy was corrected to reference the Gutenberg catalog index work.
- Contents chapter/section Rewrite is now covered as row-level background work: each Contents row has separate navigation and Rewrite actions, no automatic navigation, inline ETA/progress, ready/failure/cancel actions, style snapshots, Reader/Contents return cues, playback-arrival copy, and static storage cleanup copy. Remaining production-policy work is tracked in `contents-background-rewrite-plan.md`.

Recommended next work:

1. Implementation handoff: use `v1-production-threshold-handoff.md` for production gates and `v1-implementation-contracts.md` for payload/result contracts.
2. Visual design pass only after implementation handoff confirms the wireframe/OOUX model still holds.

## V1 Production Threshold Map - 2026-07-08

Dedicated handoff: `v1-production-threshold-handoff.md`.

These are not blockers for the wireframe, but they must be explicit before implementation handoff.

| Area | Prototype behavior | Production threshold |
|---|---|---|
| PDF/EPUB extraction | Import creates a file preparation state, fallback positions, ready/failure states, honest Original placeholders, and filename-based test-only scenario triggers. | Real extraction must detect selectable text, EPUB structure, weak OCR, scanned/image-only files, password protection, oversized files, and timeout/error codes from parser results and file metadata. |
| Long imports | Reader-level progress persists and Library can return to the processing file/text item. | Background job persistence, cancellation, retry, and recoverable failed-file policy must be implemented. |
| Speech recognition | Voice command uses scripted transcript states for Add note/question and Mark problem. | Real in-app hold-to-capture, audio ducking, transcript editing, permission handling, and failure/cancel states. |
| Retelling generation | Simulated on-phone/cloud generation, failed/ready/use/cancel states. | Real generation queue, conflict prevention, local/cloud routing, cost/upgrade policy, and source-range scoping. |
| Contents row rewrites | Row-level Rewrite starts background work with inline ETA/progress, ready/failure/cancel actions, row-only Listen/Use, style snapshots, Reader/Contents return cues, and no automatic navigation. | Production persistence, expiration enforcement, cross-device sync policy, real provider errors, and entitlement routing from `contents-background-rewrite-plan.md`. |
| TTS voices | Included/premium/local/cloud labels, preview, local fallback, download failure/retry. | Real voice catalog, local pack download/storage, cloud fallback, premium entitlement, and provider failure handling. |
| OS share | No in-app Library button; OS share remains a native integration path. | Real iOS/Android share extension and supported payload handling. |
| Search | Library search is visibly planned around the Gutenberg catalog index. | Real public-domain indexing, returned-field audit, and rights-safe result handling. |
| Account/storage | Settings separates destructive actions and confirms account deletion. | Real confirmation, auth, deletion scope, local model cleanup, account data policy, and legal/privacy copy. |
| Accessibility persistence | Reader visibly responds to text size, contrast, reduced motion, spacing. | Persist defaults globally or per Source and map them to Flutter accessibility/theming behavior. |

## Decision Log

| Date | Decision |
|---|---|
| 2026-07-03 | Reader drawer should show recommended voices only. |
| 2026-07-03 | Settings -> Voice -> All voices should be comprehensive. |
| 2026-07-03 | Personify controls two aspects for now: Style and Voice. |
| 2026-07-03 | Voice catalog should be model-first, with Supertonic as the first included model. |
| 2026-07-03 | Premium/cloud/offline states must preserve a free local path. |

## Prototype Patch Log

| Date | Patch | Status | Notes |
|---|---|---|---|
| 2026-07-06 | B7 first-run continuity patch | Prototyped in `index.html` | Library card Play/Continue now starts playback, starter books show whole-text cues, and completion offers Continue next. Shared-text entry remains a later B7 state. |
| 2026-07-06 | End-of-section scope decision | Documented | Do not design special completion behavior next; standard playback should continue until the user pauses or changes position. |
| 2026-07-06 | Shared-text entry and continuous playback patch | Superseded at UI level | Shared text should still enter the Reader model, but the entry point is native OS share from another app, not an in-app Add text or Library button. Continuous playback behavior remains current. |
| 2026-07-07 | V1 flow consolidation pass | Prototyped in `index.html` | Reader routes voice Add note/question and Mark problem through the selected-range annotation sheet, Library groups current/user/starter texts, import handles empty extraction, and Settings exposes offline voice fallback. |
| 2026-07-07 | Annotation composer convergence pass | Prototyped in `index.html` | Touch Add note/question, Mark problem, and voice commands now use one selected-range annotation composer with save/cancel behavior. Later F1-F3 work added scope, share, review surfaces, and Discuss as a saved-annotation action. |
| 2026-07-07 | F1-F3 flow-next sweep | Prototyped in `index.html` | Library now shows first-listen proof progress and Notes/marks review, Reader resumes saved source position, Transform text asks for scope, and Share opens a selected-range sheet without creating a Passage object. |
| 2026-07-07 | F5-F7 hardening sweep | Prototyped in `index.html` | Import now covers oversized and timeout failures, Settings covers local voice download failure/retry, premium voice guardrails, offline fallback, accessibility controls, and account deletion confirmation. |
| 2026-07-07 | Settings IA/OOUX simplification pass | Prototyped in `index.html` | Settings now opens with an object map, full voice catalog is behind Manage all voices, Retelling drawer shows only current Performance controls and favorite included voices, accessibility controls visibly affect Reader, and storage/account actions are behind an advanced panel. |
| 2026-07-07 | Settings routed subviews pass | Prototyped in `index.html` | Settings root now routes to focused object subviews for Voice, Voice catalog, Offline voices, Reading, Accessibility, Retelling language, Plan, and Storage/account instead of scroll-jumping through one packed settings stack. |
| 2026-07-07 | V1 closure triple-batch plan | Planned in `v1-closure-triple-batch.md` | Active next batch combines closure audit, Performance conflict rules, completion/background access, Library growth, Annotation depth, persona seriousness, and production threshold mapping. |
| 2026-07-08 | Selected-text popover/drawer split | Prototyped in `index.html` | Copy, Highlight, and Share moved into a compact native-style popover; Rewrite, Translate, Add note, and Mark problem moved into the selected-range drawer. Saved notes now support Edit note, Add another note, and Discuss with AI instead of threaded-reply copy. |
| 2026-07-07 | V1 closure triple-batch sweep 1 | Prototyped in `index.html` | Added long-import return preservation, bookmark Annotation variant, clearer Performance conflict copy, and less novelty-forward persona copy; Library search and OS share were re-scoped as paused/native integration paths. |
| 2026-07-08 | V1 closure audit reconciliation | Documented | P0 stories are covered at wireframe level; follow-up decisions were moved into production thresholds, Library growth, native share, AI discussion, and implementation contracts. |
| 2026-07-08 | Library grid and copy QA | Prototyped in `index.html`; documented in `test-stories.md` | Restored the Library starter books to a compact grid under one dominant Continue listening card, removed visible Passage object language from product copy, and kept public-domain search honest until the Gutenberg contract is implemented. |
| 2026-07-08 | Reader and Import/Paste QA | Prototyped in `index.html`; documented in `test-stories.md` | Verified playback, Original/Retelling, Continue next, paste intake, import processing/recovery/long-return wiring, and removed visible capitalized Source object language from Reader/Import states. |
| 2026-07-08 | Annotation and Voice/Settings QA | Prototyped in `index.html`; documented in `test-stories.md` | Verified selected-text actions, saved annotation follow-ups, voice-created annotation paths, voice catalog/fallback behavior, accessibility controls, and account/storage confirmation; replaced remaining visible passage-text copy in Settings. |
| 2026-07-08 | Production threshold handoff | Documented in `v1-production-threshold-handoff.md` | Split prototype guarantees from production requirements and acceptance checks for extraction, long imports, speech recognition, generation, TTS voices, OS share, search, account/storage, and accessibility persistence. |
| 2026-07-08 | Library growth decisions | Documented in `library-growth-decisions.md` | Chose Project Gutenberg catalog index for V1 search, deferred Open Library/OPDS, and set native share to text-only for V1 with PDF/EPUB native share deferred. |
| 2026-07-08 | AI discussion scope decision | Documented in `ai-discussion-decision.md` | Kept V1 to saved-annotation Discuss handoff and deferred rich AI answer output, answer history, follow-ups, and answer playback to V1.1. |
| 2026-07-08 | V1 implementation contracts | Documented in `v1-implementation-contracts.md` | Defined required result fields and blocking rules for Project Gutenberg search, text-only native share payloads, Contents background rewrite payloads, and saved-annotation Discuss handoff payloads. |
| 2026-07-08 | Final Library render QA | Exported `qa-final-2026-07-08.png`; patched in `index.html` | Confirmed the Library grid structure and corrected stale disabled-search copy to “Gutenberg catalog index not connected yet.” |
| 2026-07-08 | Contents background rewrite patch | Prototyped in `index.html`; documented in `test-stories.md` | Removed the separate Contents-level rewrite panel; Rewrite now starts row-level background work with ETA/progress state and no automatic navigation. |
| 2026-07-08 | Contents background rewrite lifecycle plan | Planned in `contents-background-rewrite-plan.md` | Captured remaining row lifecycle, playback arrival, scope, free/cloud delay, persistence, storage, and fallback-position rules before the next prototype pass. |
| 2026-07-09 | Contents background rewrite lifecycle prototype | Prototyped in `index.html`; documented in `contents-background-rewrite-plan.md` and `test-stories.md` | Completed row states, row actions, style snapshot/previous-style copy, Reader/Contents cues, playback-arrival copy, fallback-position failure/retry/cloud path, and storage cleanup copy. |