# Understand Decision Log

This file tracks product and UX decisions for Understand so future design studies can cite the reasoning, evidence, alternatives, and prototype impact.

## How To Use This Log

Each entry should include:

- Decision: what changed or what we are committing to
- Status: proposed, accepted, prototyped, validated, superseded
- Date: when the decision was made
- Context: what problem forced the decision
- Rationale: the visible product/design reasoning
- Evidence: user conversation, prototype file, research source, or roadmap reference
- Impact: where this affects UI, object model, copy, engineering, or roadmap
- Open questions: what still needs to be tested or decided

## Decision Index

| ID | Decision | Status | Primary Surface |
|---|---|---|---|
| D001 | Source is the core reading object | Accepted | Reader, Library |
| D002 | Passage as a visible artifact is deferred during OOUX | Superseded by D024 | Reader, selected text |
| D003 | Chunk stays invisible as a technical processing unit | Accepted | Generation pipeline |
| D004 | Annotation groups highlights, comments, notes, and bookmarks | Accepted | Future reader annotation tools |
| D005 | Personify edits the current Source Performance | Superseded by D025 | Personify drawer |
| D006 | Performance changes use one Save action from here forward | Prototyped | Personify drawer |
| D007 | Utility rewrite styles use precise labels; personas can be characterful | Prototyped | Writing style list |
| D008 | Drawer should use progressive disclosure for voice and advanced controls | Prototyped | Personify drawer |
| D009 | Performance Save belongs in a sticky bottom commitment area | Prototyped | Personify drawer |
| D010 | Long-running Performance generation belongs on the reader surface | Prototyped | Reader, Personify drawer |
| D011 | Source lifecycle runs Library -> first listenable position -> Contents continuation | Prototyped | Library, Contents, Reader |
| D012 | Generated Performance waits for explicit user switch | Prototyped | Reader generation banner |
| D013 | Writing style selection uses a compact grouped picker | Prototyped | Personify drawer |
| D014 | Created/imported material becomes a Source with a first listenable position | Prototyped | Library, Intake, Contents, Reader |
| D015 | Imported files show processing before fallback Source readiness | Prototyped | Import, Reader, Contents |
| D016 | Test stories are the design batch spine | Documented | Roadmap, Test stories |
| D017 | Test stories stay at wireframe/OOUX fidelity | Documented | Roadmap, Test stories |
| D018 | Import recovery states live on the reader Source job banner | Prototyped | Import, Reader, Contents |
| D019 | Trust checks live beside the reader text | Superseded | Reader, Performance |
| D020 | Trust uses Original toggle plus Performance fidelity | Prototyped | Reader, Performance |
| D021 | Selected range menu unifies annotation and recovery | Prototyped | Reader, Annotations, Performance |
| D022 | Visible labels use reader-facing nouns and actions | Prototyped | Library, Reader, Performance |
| D023 | Selected text actions are the next design batch | Prototyped | Reader, Annotations |
| D024 | Do not expand Passage terminology during OOUX | Prototyped | Reader, selected text menu |
| D025 | Personify is a view switch, not a drawer trigger | Prototyped | Reader, Performance |
| D026 | Retelling is the visible version label; settings are an adjacent affordance | Prototyped | Reader, Retelling settings |
| D027 | Use a layered Open Design context stack for vision, design posture, stories, roadmap, decisions, and rules | Documented | Project docs |
| D028 | Promote North Star principles into verified rules and make B7 the next alignment pass | Documented | Project docs, Memory rules |
| D045 | Discuss is a later action on saved annotations | Prototyped | Reader, Annotations |
| D046 | Selected text splits native popover from Understand drawer | Prototyped | Reader, Annotations |
| D047 | V1 closure keeps search and OS share as explicit thresholds | Documented | Roadmap, Library, handoff |

## D001 - Source Is The Core Reading Object

- Status: accepted
- Date: 2026-07-06
- Context: We needed to decide whether the app is organized around passages, parts, chunks, or the full text the user is trying to get through.
- Decision: Treat Source as the core product object: a book, article, PDF, essay, or pasted text.
- Rationale: Users recognize and return to the full thing they are trying to read. Source maps cleanly to Library, Continue, Contents, progress, and trust in the original.
- Evidence:
  - User direction: app should not invent objects just because the system processes text in chunks.
  - Project memory: Understand is a source/listening app, not a generic TTS app or document manager.
  - Prototype: `index.html` Library and Reader are source-oriented.
- Impact:
  - Visible reader copy should prefer book, text, Original, retelling, selected text, or from here instead of standalone Source/Current labels.
  - Contents should navigate the selected book or text, not act as sample switching.
- Open questions:
  - How much source structure should be exposed when PDFs or pasted text have weak/no headings?

## D002 - Passage Is A Saved/Shareable Artifact

- Status: superseded by D024
- Date: 2026-07-06
- Context: We needed to resolve whether passage is the normal unit of listening or something more meaningful.
- Decision: Earlier thinking reserved Passage for meaningful excerpts users save, share, trade, remix, collect, or turn into scripts. D024 supersedes this as a current OOUX decision: do not expose Passage as a visible object yet.
- Rationale: The artifact idea may still be useful later, but the current structure pass should keep the active concepts tighter: book/text, Original, Personify, selected text, and Annotation.
- Evidence:
  - User phrasing: "passage is the shit" and "people trade passages."
  - Object test: users can save, share, compare, replay, remix, tag, and collect passages.
- Impact:
  - Reader should not feel like a passage manager.
  - Highlight/comment should remain Annotation behavior until a later object test proves a separate artifact is needed.
- Open questions:
  - If a shareable excerpt object returns later, what user job proves it is distinct from a highlight or note?

## D003 - Chunk Stays Invisible

- Status: accepted
- Date: 2026-07-06
- Context: The rewrite/audio system needs a processing unit, but users do not think in context windows or generation batches.
- Decision: Chunk remains an internal technical unit.
- Rationale: Chunk is useful for latency, cost, prompt context, and audio generation, but it does not pass the user-object test.
- Evidence:
  - User knew what chunk meant technically but questioned why the app would surface part/passage distinctions.
  - OOUX direction: objects should match the user's mental model.
- Impact:
  - Do not expose chunk, segment map, paragraph batch, token window, or context window in UI.
  - Generation can happen chunk-by-chunk behind a source/position model.
- Open questions:
  - How should failure/retry messages talk about generated ranges without exposing chunks?

## D004 - Annotation Groups Highlights, Comments, Notes, And Bookmarks

- Status: accepted
- Date: 2026-07-06
- Context: The product should eventually support basic e-reader behaviors without confusing them with Passages.
- Decision: Treat highlight, comment, note, and bookmark as types of Annotation.
- Rationale: Annotation is an in-reader mark attached to a source range. Passage is an artifact created when a marked range becomes worth saving/sharing/remixing.
- Evidence:
  - User direction: keep e-reader basics in mind, but they are not core-core right now.
  - Object relationship: highlighted or noted text can later support sharing if a separate artifact proves necessary.
- Impact:
  - Future reader tools can add highlight/comment without changing the Personify model.
  - Annotation should remain the current reader mark object during OOUX.
- Open questions:
  - If users highlight a Retelling, how should that map back to the Original?

## D005 - Personify Edits The Saved Performance For This Book Or Text

- Status: superseded by D025
- Date: 2026-07-06
- Context: Personify was drifting toward a style/voice picker. We needed a clearer object model.
- Decision: Earlier pass treated Personify as the entry point into Performance: how this book or text should sound from here. D025 supersedes the interaction pattern: Personify remains the active retelling view, while Performance opens from a separate setup affordance.
- Rationale: Performance groups version, writing style, fidelity, voice, and playback feel. This answers the user question: "What am I hearing right now, and how can I change it?"
- Evidence:
  - Prototype: `index.html` Personify drawer now labels the setup as Listening setup.
  - User direction: Performance should feel broader than backend voice/TTS settings.
- Impact:
  - Drawer copy should use concrete reader-facing labels while keeping Source as the internal object.
  - Summary should map every term to a visible control.
  - The Personify tab itself should not be the drawer trigger.
- Open questions:
  - Should the user-facing label remain Personify while the object is Performance?

## D006 - Performance Changes Use One Save Action From Here Forward

- Status: prototyped
- Date: 2026-07-06
- Context: The previous model split "Rewrite passage" and "Save as default," which made the action model harder to understand.
- Decision: Use one Save action. Saving applies the draft Performance to the current Source from here forward and starts generation.
- Rationale: One action matches the user's stated flow: choose Drunk Uncle, tap Save, generate, then continue listening in the new style.
- Evidence:
  - User direction: "it should you hit save and it begins rewriting it period."
  - Prototype: `index.html` now uses `Save` and a generating state.
- Impact:
  - No version-history UI yet.
  - Generation state should explain that Original remains available.
- Open questions:
  - Should Save pause playback, continue current audio while generating, or switch when ready?

## D007 - Utility Styles Use Precise Labels; Personas Can Be Characterful

- Status: prototyped
- Date: 2026-07-06
- Context: Style labels were mixing accurate transformations with persona-like/gimmicky options.
- Decision: Rename Modernize to Accurate Modern and Simple Modernize to Simple Modern. Keep persona labels like Drunk Uncle and Influencer when useful.
- Rationale: Some styles should read like accurate descriptors; others can be playful archetypes when they help users predict the listening feel.
- Evidence:
  - User correction: "this is the tense we want to use."
  - Prototype: `index.html` style labels updated.
  - Roadmap: `feature-roadmap.md` includes style taxonomy note.
- Impact:
  - Future style labels should be checked against utility-vs-persona framing.
- Open questions:
  - Resolved in D013: the visible picker uses "Patient Professor" and groups it under Guided listening.

## D008 - Use Progressive Disclosure For Voice And Advanced Controls

- Status: prototyped
- Date: 2026-07-06
- Context: The current drawer shows too much at once. Voice is below the fold even though it is part of Performance.
- Decision: Use a compact Performance-first drawer: saved setup summary, plain from-here scope, selected voice with Preview, then style and fidelity. Reveal the longer favorite/premium voice list only when the user taps Choose voice.
- Rationale: The first screen should answer what the user is hearing, what can change, and what happens when they save. Advanced lists can come second.
- Evidence:
  - Rendered audit: voice is below the fold in the current drawer.
  - Prototype: `index.html` now shows a compact selected-voice row above style and fidelity, with the favorite voice list inside a disclosure.
  - Research: NN/g Progressive Disclosure recommends showing important controls first and revealing specialized controls on request.
  - Research: NN/g input-control guidance supports matching control type to parameter type.
- Impact:
  - Reader drawer now keeps voice visible without making the full voice catalog dominate the first screen.
  - Save copy distinguishes saved current Performance from draft changes and generation.
  - Full voice catalog stays in Settings.
- Open questions:
  - Should style selection open a secondary sheet, inline expansion, or segmented group?

## D009 - Put Performance Save In A Sticky Bottom Commitment Area

- Status: prototyped
- Date: 2026-07-06
- Context: A Save button near the top of the drawer asked users to commit before they had seen or changed the controls. The scope chip under the setup summary also looked like loose metadata rather than part of the decision.
- Decision: Move Save to a sticky bottom action area. Disabled state reads Saved, changed state reads Save performance, and helper copy sits with the action. Scope becomes plain text under Listening setup.
- Rationale: Mobile sheets usually keep destructive or committing actions at the bottom, after the user has reviewed options. This also lets the top of the sheet focus on orientation: what is currently saved and what can be changed.
- Evidence:
  - User audit note: "the save button at the very top is weird" and should be sticky to the bottom.
  - Prototype: `index.html` now places `Save performance` in the sticky bottom action area and uses `Choose voice` instead of `Change favorite voice`.
- Impact:
  - Save state is now visually tied to pending changes.
  - The drawer better separates orientation, selection, and commitment.
- Open questions:
  - Should the sticky action also show a compact dirty-state summary when multiple settings change?

## D010 - Move Long-Running Performance Generation To The Reader Surface

- Status: prototyped
- Date: 2026-07-06
- Context: On-device generation for the free version may take several minutes. Keeping the user inside the Personify drawer with an in-button generating state makes the app feel blocked and hides the text they came to read.
- Decision: After Save performance, close the drawer and show a reader-level generation banner above the passage. The banner explains that generation is happening on the phone, Original remains available, and the new Performance becomes active when ready.
- Rationale: The drawer is for choosing a Performance. The reader is where long-running source work should be tracked, because users can keep reading, listening, or comparing while the job runs.
- Evidence:
  - User audit note: free generation can take several minutes, so the state should appear on the actual text screen.
  - Prototype: `index.html` now starts a background generation banner and closes the Personify drawer after Save performance.
- Impact:
  - Save commits the draft setup and launches a background job instead of acting like an immediate rewrite.
  - Performance controls are locked while the active job is running.
  - Reader/audio copy acknowledges background generation.
- Open questions:
  - Should users be able to cancel generation, queue multiple styles, or switch to Original automatically during generation?

## D011 - Make The Source Lifecycle Explicit

- Status: prototyped
- Date: 2026-07-06
- Context: The prototype had the right OOUX objects, but several labels still implied excerpts, passages, import tasks, or audio snippets. That made the path from Library to Reader less durable for long books, PDFs, and pasted text.
- Decision: Treat Library as the place where users choose or create a Source, Contents as navigation within the active Source, Reader as the primary listening surface, and completion as a transition to the next source position.
- Rationale: Users should not have to manage chunks or decide where generation starts. They choose a book or text; Understand chooses a sensible first listenable position and lets them continue by chapter, section, or from where they left off.
- Evidence:
  - OOUX audit after D001-D010: the product model was Source-first, but stale UI copy still said excerpt, passage, chunks, and import from Reader.
  - Prototype: `index.html` now frames Library cards with reader-facing labels, intake as Add text / Start listening, Contents as position navigation, and completion as "This part is complete" with a Contents-forward path.
- Impact:
  - Reader no longer invites import/paste after completion.
  - Book/source cards avoid duration-like metadata.
  - Intake copy promises source creation and first-position selection instead of exposing chunking.
- Open questions:
  - What should the first-position picker look like when an imported PDF has weak structure?
  - Should completion auto-suggest the next real chapter/section when available?

## D012 - Wait Before Switching To A Newly Generated Performance

- Status: prototyped
- Date: 2026-07-06
- Context: A Performance save can take minutes on a free on-phone path. If the app auto-switches when generation finishes, playback may change style or voice while the user is listening.
- Decision: Generation completion creates a reader-level ready state. The new Performance does not take over until the user taps Use now. If local generation fails, the user must resolve the banner by canceling, retrying on the phone, or choosing the cloud upgrade path.
- Rationale: Save starts the job, but switching playback is a separate moment of user control. This keeps long-running work visible without making the app feel blocked or surprising the listener.
- Evidence:
  - Prototype: `index.html` now supports generating, failed, ready, applied, retry-on-phone, cloud-upgrade, and cancel states.
  - User direction: free on-phone generation can take several minutes, so the state belongs on the actual text screen.
- Impact:
  - The drawer remains a selection/commit surface.
  - The reader owns long-running job recovery.
  - The Performance drawer cannot open while a failed/ready generation decision is unresolved.
  - Current Performance and Original remain available during failure and waiting states.
- Open questions:
  - Should the cloud upgrade path be premium-only, metered, or automatic after repeated local failure?
  - Should users be able to queue another Performance while one is ready but not yet applied?

## D013 - Use A Compact Grouped Writing Style Picker

- Status: prototyped
- Date: 2026-07-06
- Context: The Performance drawer had a seven-option inline writing-style list. It made the drawer tall and mixed accurate utility styles with persona styles without enough structure.
- Decision: Show one compact current-style row in the drawer. Tapping it opens a small grouped picker with Clear rewrites, Guided listening, and Personas.
- Rationale: Style is important, but it should not crowd voice, fidelity, and the sticky Save action. Grouping also makes Accurate Modern and Simple Modern read as practical rewrite styles while keeping Drunk Uncle, Very Online Gen Z, and Influencer clearly persona-like.
- Evidence:
  - Prototype: `index.html` now uses `current-writing-style` plus a grouped `style-picker-panel`.
  - User direction: compact mobile controls should preserve vertical space and persona/style selection should use a modal-style picker rather than inline dropdown bloat.
- Impact:
  - Selecting a style changes the draft Performance only.
  - Save performance remains the only commit action.
  - The picker cannot open while a failed, ready, or generating Performance decision is unresolved on the reader.
- Open questions:
  - Should the style picker eventually include previews or short examples per style?

## D014 - Create Sources From Pasted Or Imported Material

- Status: prototyped
- Date: 2026-07-06
- Context: The Library and intake copy already framed paste/import as Source creation, but the prototype only said it "would" open the first listenable position.
- Decision: Make intake create a Source object. Pasted text uses the pasted sentences, imported files create a processing-style Source using the file name and fallback structure, and Reader opens at the first listenable position.
- Rationale: The user's first serious trust test is bringing their own material. The app should choose a clear starting point and preserve the Source -> Reader -> Contents flow instead of exposing chunks or making users organize the text first.
- Evidence:
  - Prototype: `index.html` now creates custom Source entries internally, updates the Library Continue reading card, opens Reader, and lets Contents navigate generated positions.
  - Product direction: Understand should make hard text listenable while preserving the original, and import belongs in Library rather than Reader.
- Impact:
  - New Sources reset stale generation/draft state so old Performance jobs do not follow the user into a different source.
  - Contents can move the listening position rather than only describing a possible future move.
  - Imported-file behavior stays honest: it shows extraction/structure fallback rather than pretending the prototype parsed hidden file contents.
- Open questions:
  - What should the real extraction pipeline show while an imported PDF or EPUB is still processing?
  - How should users confirm or override the chosen first listenable position when structure is weak?

## D015 - Show Import Processing Before Source Ready

- Status: prototyped
- Date: 2026-07-06
- Context: File import does not actually parse PDFs or EPUBs in this prototype, so the product should not jump straight to a ready state or imply real extraction worked.
- Decision: After selecting a file and tapping Start listening, Reader opens in a processing state. The reader banner says Understand is preparing the first listenable position, playback is disabled while processing, and the state resolves into a clearly labeled Ready to listen state.
- Rationale: This makes the long-running import job visible on the primary work surface without pretending PDF/EPUB parsing is implemented. It also matches the broader rule that long jobs should leave drawers/sheets and belong on the reader surface.
- Evidence:
  - Prototype: `index.html` now has `sourceJobStatus`, a reader-level processing banner, disabled playback during processing, and a Ready to listen dismissal.
  - User correction: import behavior should be understood as preparation/fallback text, not parsed PDF text.
- Impact:
  - Import handoffs must call this a processing/fallback Source.
  - Contents can show fallback positions, but not fake chapters.
  - Performance changes are locked while the imported Source is still processing.
- Open questions:
  - Should import processing support Cancel?
  - What should happen if extraction fails, takes minutes, or finds scanned/image-only pages?

## D016 - Use Test Stories As The Design Batch Spine

- Status: documented
- Date: 2026-07-06
- Context: The prototype now covers several interacting product areas: Source intake, Reader playback, Performance generation, voice selection, Library/Contents, and import placeholder behavior. The next work should happen in larger batches, but those batches need concrete review checkpoints so design passes do not become vague.
- Decision: Create `test-stories.md` as the canonical inventory of P0/P1/P2 test stories. Future prototype passes should cite changed story IDs, group related states into batchable work, and hand off with test steps plus expected behavior.
- Rationale: A story map lets Understand move quickly in larger design batches while preserving the critical details: import placeholder vs real extraction, current/draft/ready Performance states, Original availability, local/cloud/premium fallback, and Source-first navigation.
- Evidence:
  - Prototype: `index.html` already contains covered and partial stories across Source intake, Reader playback, Performance generation, voice catalog, and Library/Contents.
  - Project docs: `test-stories.md` now lists P0/P1/P2 stories and batch checkpoints for import recovery, compare/trust, generation rules, voice fallback, Library navigation, annotations, onboarding, and settings/account boundaries.
- Impact:
  - Every artifact handoff should include a change -> user story -> test steps -> expected behavior map.
  - The next recommended batch is import failure and weak-structure recovery.
  - Handoffs must explicitly say when behavior is a placeholder/fallback instead of real PDF/EPUB parsing, extraction, or generation.
- Open questions:
  - Which batch should follow import recovery: compare/trust or Performance persistence?
  - How often should larger batches pause for review before continuing?

## D017 - Keep Test Stories At Wireframe And OOUX Fidelity

- Status: documented
- Date: 2026-07-06
- Context: The current work is still about OOUX/OOUUS and core wireframes. The test-story inventory should not pull the team into visual design before the core experience, object relationships, and states are correct.
- Decision: Treat `test-stories.md` as a wireframe/OOUX test inventory. Stories validate objects, actions, flow order, state transitions, layout hierarchy, and next steps. They do not evaluate visual style, brand polish, final typography, illustration, or high-fidelity UI treatment yet.
- Rationale: Understand still needs comprehensive, correct core flows before visual design. Separating wireframe coverage from visual polish keeps the next batches focused on product-model correctness.
- Evidence:
  - User direction: "our user stories are still for just wireframes" and "we're still going through the OOUUS process."
  - Project docs: `test-stories.md` now states that covered means understandable at the wireframe level, not visually final.
- Impact:
  - Future pass summaries should describe wireframe/object/flow/state changes first.
  - Review checkpoints should ask whether the experience is conceptually correct, not whether the UI is visually polished.
  - Visual design should wait until the core wireframes and test stories are stable.
- Open questions:
  - What threshold marks the OOUX/wireframe pass complete enough to begin visual design?

## D018 - Put Import Recovery On The Reader Source Job Banner

- Status: prototyped
- Date: 2026-07-06
- Context: The placeholder import flow showed processing and fallback readiness, but it did not yet cover weak structure, scanned/image-only PDFs, password-protected files, long imports, cancel, retry, or choose-another-file recovery.
- Decision: Extend the reader-level Source job banner to cover import recovery states. Source jobs can now be processing, ready, or failed. Failed states offer Retry, Choose another file, and Remove source. Processing states offer Cancel import. Ready states distinguish detected EPUB chapters from fallback positions.
- Rationale: Import work belongs on the primary reader surface because users should understand whether Understand is preparing, blocked, or ready without being trapped in the intake sheet. Recovery actions stay attached to the Source job instead of becoming disconnected error screens.
- Evidence:
  - Prototype: `index.html` uses filename-based test-only triggers for wireframe import scenarios: scanned/image, locked/password, large, messy/weak OCR, and EPUB. These triggers are not product logic.
  - Test stories: S06-S11 and I01-I03/I06 are covered at wireframe fidelity; S12/I04/I05 remain partial because real large-file limits and empty-extraction details need product thresholds.
- Impact:
  - File import still does not claim real PDF/EPUB parsing.
  - Contents uses real EPUB chapter labels only in the structured EPUB wireframe state.
  - Weak or large files show fallback positions and explicitly avoid presenting them as real chapters.
  - Failed imports do not leave the user with a broken active Source.
- Open questions:
  - What real backend signals map to scanned/image-only, password-protected, empty extraction, weak OCR, and file-too-large?
  - Should Remove source always delete the placeholder Source, or can it preserve a queued Source in Library?

## D019 - Keep Compare, Trust, And Explanation Beside The Reader Text

- Status: superseded by D020
- Date: 2026-07-06
- Context: Original was available, and Performance had a fidelity control, but there was no compact reader-level way to check the current retelling against Original, recover when meaning felt wrong, or ask for more explanation without turning Understand into a chat app.
- Decision: Add a reader-level Trust module with Compare, Meaning off?, and Explain actions. Compare aligns the active Personify and Original sentences. Meaning off? offers Original, Use Closer, Regenerate, and Report spot. Explain selects the Explain fidelity as a draft Performance change rather than opening a separate chat thread.
- Rationale: Trust work belongs next to the text the user is evaluating. It should preserve playback position, keep Original available, and route durable changes through Performance so the object model stays Source -> Performance -> Retelling.
- Evidence:
  - Previous prototype pass: `index.html` included `trust-tools`, aligned sentence comparison, meaning recovery actions, and Explain-as-Performance behavior.
  - Superseded test framing: T03-T06 were treated as covered at wireframe fidelity; D020 revises T05 back to partial because recovery needs a clearer object model.
- Impact:
  - Fidelity now reads as a trust/source-distance control, not an abstract tuning knob.
  - Meaning recovery does not overwrite the active retelling unless the user explicitly regenerates or saves a Performance draft.
  - Explanation stays within Performance instead of becoming a generic assistant/chat surface.
- Open questions:
  - Should Compare eventually show paragraph-level alignment or only current-sentence alignment?
  - Should Report spot become an Annotation, a generation-quality report, or both?
  - Where should global/default Performance rules live relative to Settings?

## D020 - Trust Uses Original Toggle Plus Performance Fidelity

- Status: prototyped
- Date: 2026-07-06
- Context: The reader-level Trust module duplicated the existing Personify/Original comparison and introduced too many competing recovery actions for the wireframe phase.
- Decision: Remove the separate Trust/Compare panel from the reader. Use the Personify/Original toggle as the core comparison mechanism, and keep Closer/Balanced/Explain inside Performance as fidelity choices.
- Rationale: Trust should come from a simple preserved-original model: switch to Original when skeptical, then adjust Performance if the retelling should stay closer or explain more. This keeps the reader focused and avoids turning recovery into a separate tool cluster.
- Evidence:
  - Prototype: `index.html` no longer includes the `trust-tools` reader panel.
  - Test stories: T03, T04, and T06 are covered through Performance and Original switching; T05 is partial until the wrong-retelling recovery path is explicitly designed.
- Impact:
  - Reader comparison is simpler and reuses the existing Original toggle.
  - Fidelity remains part of the Performance object.
  - Regenerate and Report spot move out of the B2 core wireframe and need a later recovery/annotation decision.
- Open questions:
  - Should a wrong-retelling recovery flow live in Performance, Annotation, or a future generation-quality report?
  - What exact scope copy should explain Save from here versus source default?

## D021 - Selected Range Menu Unifies Annotation And Recovery

- Status: prototyped
- Date: 2026-07-06
- Context: Wrong-retelling recovery overlaps with normal reader annotation behavior. The user noted that the app already needs controls after highlighting, similar to Lingua, including highlight and comment actions.
- Decision: Use one selected-range menu for reader marks and recovery. The first pass opens actions for Highlight, Comment, Regenerate, Mark problem, and View Original/Personify; D023 expands this into the full selected text action menu.
- Rationale: The comparison surface is the text itself. A selected range can map across Personify and Original, become an Annotation, or become the target for regeneration/recovery without exposing chunk terminology.
- Evidence:
  - Prototype: `index.html` now opens a selected-range sheet from tapped sentence ranges.
  - Test stories: T05 and A01-A04 now share the same selected-range menu surface.
- Impact:
  - Annotation and recovery stories should be designed together.
  - Mark problem is a localized signal; Regenerate changes output.
  - Selected text stays a range state while a separate excerpt artifact remains deferred.
- Open questions:
  - Which exact Lingua actions should be copied into the first-row range menu?
  - Should selected ranges support multiple sentences immediately or start with the active sentence only?
  - Does Mark problem become an Annotation subtype, a quality report, or both?

## D022 - Visible Labels Use Reader-Facing Nouns And Actions

- Status: prototyped
- Date: 2026-07-06
- Context: The Library and reader surfaces used internal object labels like Source and Current as visible UI labels. The user flagged that these are not meaningful on their own.
- Decision: Keep Source as the internal product object, but use concrete reader-facing copy in the UI: Continue reading, Book, Reading now, In library, Add text, Start listening, Ready to listen, Original, and this book or text.
- Rationale: Reader UI should name what the user recognizes or can do next. Source and Current are useful architecture terms, but when shown alone they force users to decode the model instead of acting.
- Evidence:
  - Prototype: `index.html` replaces standalone Source/Current labels across Library cards, dynamic Library list badges, intake copy, audio status, Contents copy, and Performance helper copy.
  - Test stories: S01-S04 and L01-L08 now test reader-facing labels instead of Source/Current label comprehension.
- Impact:
  - The Source object remains valid in architecture, docs, and processing states.
  - Visible labels should prefer book, text, Original, retelling, selected text, or a direct action.
  - Import placeholder handoffs still distinguish fallback behavior from real file extraction.
- Open questions:
  - Should the Library eventually separate starter books, user text, and imported files into distinct sections?
  - Should Performance remain the long-term user-facing name, or become Listening setup throughout the UI?

## D023 - Selected Text Actions Are The Next Design Batch

- Status: prototyped
- Date: 2026-07-06
- Context: The import-recovery batch has a first-pass wireframe, while the selected-range menu is becoming the shared surface for e-reader actions, annotations, and wrong-retelling recovery.
- Decision: Promote selected text actions as the next design batch and expand the prototype menu as a first-pass wireframe grouped by intent: Reader actions (Copy, Highlight, Share), Understand actions (Listen, Transform text, Discuss), and Keep actions (Add note, Mark problem, View Original/Personify).
- Rationale: These actions share the same selected range and should not be designed as separate drawers or disconnected tools. Treating them together protects the object model: Annotation is a reader mark, Transform changes output, Mark problem flags a localized issue, and selected text does not need a second object name yet.
- Evidence:
  - Prototype: `index.html` now opens an expanded selected-range sheet from tapped sentence ranges, including first-pass states for copy, one-tap highlight, listen, note stub, share stub, transform, discussion placeholder, problem marking, and Original/Personify switching.
  - Test stories: the Recommended Next Batch in `test-stories.md` now groups A01-A05, T05, and P14 around selected text actions.
  - Roadmap: `feature-roadmap.md` now lists the selected text action menu as the next design deliverable.
- Impact:
  - The selected-range menu now has enough structure to test before moving into voice fallback or Library organization.
  - The menu should continue to feel like an extended e-reader selection menu, not a generic tool drawer.
  - Scope rules still need to be decided for Transform text: this selection, from here, whole book/text, or saved defaults.
- Open questions:
  - Should Explain/Discuss be one action or two?
  - Does Add note immediately open a thread composer, or start with a lightweight note field?
  - What should the full share sheet include?
  - Does the grouped Reader / Understand / Keep structure stay compact enough on mobile?

## D024 - Do Not Expand Passage Terminology During OOUX

- Status: prototyped
- Date: 2026-07-06
- Context: The selected-text batch started to introduce Save passage and Passage detail states, but the current design goal is OOUX structure, interaction design, and information architecture rather than expanding the product vocabulary.
- Decision: Remove Save passage from the selected-text menu and keep highlighted text as selected-text Annotation behavior for now. Do not expose Passage as a separate visible object in the reader during this OOUX pass.
- Rationale: The tighter model is easier to test: a reader selects text, marks it, adds a note, shares it, transforms it, or flags a problem. Introducing Passage now risks adding a second noun before the selection and annotation relationships are proven.
- Evidence:
  - User direction: "lets remove 'save passage'" and "we dont need to expand the terminology... since we're working on ooux - structure, ixd, ia."
  - Prototype: `index.html` removes the Save passage action and groups selected-text actions by Reader, Understand, and Keep.
  - Test stories: `test-stories.md` now tests highlighted text as an Annotation, not a Passage creation path.
- Impact:
  - Visible UI should say selected text, highlight, note, share, Mark problem, Original, or Personify.
  - Share remains a selected-text action; a later shareable excerpt object must be justified by a separate object test.
  - Highlight uses the default treatment in the main menu; color selection is deferred to an edit-highlight state if needed.
- Open questions:
  - Should Add note open a small composer immediately in the next pass?
  - Does Keep need a better label than Keep, or is it clear enough as an intent group?

## D025 - Personify Is A View Switch, Not A Drawer Trigger

- Status: superseded by D026
- Date: 2026-07-06
- Context: The Personify/Original control was doing two jobs: switching the visible text and opening the Performance drawer. That made switching from Original back to Personify feel like a trap instead of a stable comparison action.
- Decision: Make Personify/Original a stable view switch. Performance opens only from a separate setup control while Personify is active.
- Rationale: Comparison needs to be cheap and reversible. Users should be able to check Original and return to Personify without being forced into settings. Editing how the retelling sounds is a different intent from changing which version is visible.
- Evidence:
  - User direction: switching from Original to Personify should not automatically pop up the Performance drawer.
  - Prototype: `index.html` now switches Personify without opening Performance, and the adjacent setup control opens Performance explicitly.
  - Test stories: `test-stories.md` now tests Original -> Personify as a view switch and Performance as an explicit setup action.
- Impact:
  - Personify remains part of the primary reader spine.
  - Performance remains the tuning surface for style, fidelity, and voice.
  - Any future persona/settings icon must be an explicit affordance, not hidden inside the tab switch.
- Open questions:
  - Should the setup affordance stay as text (`Setup: Accurate + Zoe`) or become a compact icon once the OOUX is stable?
  - Should active Personify support a second tap to open setup, or is that still too hidden?

## D026 - Retelling Is The Visible Version Label

- Status: prototyped
- Date: 2026-07-06
- Context: The setup button label `Setup: Accurate + Zoe` read like state text pretending to be a control. A proposed `Change Personify` label was also wrong because Personify was intended as a verb/action, not a product object or version name.
- Decision: Use `Retelling / Original` as the stable reader view switch. Treat Retelling as the visible rewritten result, Original as the source view, and reserve Personify only for a future action/brand verb if it remains useful. Open retelling configuration from a small sliders affordance attached to the Retelling side of the switch, not from the Retelling tab itself.
- Rationale: A view switch should name the state being viewed; a button should name the action or control it opens. `Retelling` passes the object test better than `Personify` for the generated easier text, while an adjacent icon keeps settings discoverable without making view switching feel like a trap.
- Evidence:
  - User correction: Personify was intended as a verb label, not a special keyword, version, or object.
  - User correction: `Setup: Accurate + Zoe` was not a valid button label.
  - Prototype: `index.html` now uses `Retelling / Original`, with an adjacent Retelling settings icon that opens the drawer.
- Impact:
  - Reader comparison copy should use Retelling / Original.
  - Drawer copy should say Retelling settings, Writing style, Fidelity, and Voice rather than exposing Performance as the user-facing object in this surface.
  - The settings affordance must be explicit and visible, but visually subordinate to the main playback and view-switch controls.
- Open questions:
  - Should the drawer title remain `Retelling settings` or become a more natural phrase like `How it reads` after user testing?
  - Should the icon sit inside the active Retelling segment or remain adjacent to the segmented control?

## D027 - Use A Layered Open Design Context Stack

- Status: documented
- Date: 2026-07-06
- Context: The product vision had become too large and multi-purpose to live cleanly in one backlog, memory entry, or prototype comment. We needed to decide where Open Design should store North Star goals, interaction principles, test criteria, roadmap ideas, and enforceable rules without overwriting existing project docs.
- Decision: Use a layered context stack:
  - `product-vision.md` for the durable North Star, emotional promise, product goals, first-run goals, content/library goals, trust goals, growth goals, process goals, and open tensions.
  - `DESIGN.md` for interaction, copy, component, and design-system posture.
  - `test-stories.md` for wireframe/OOUX validation stories and review lenses.
  - `feature-roadmap.md` for bets, batches, unresolved risks, idea intake, and next deliverables.
  - `decision-log.md` for dated product/UX decisions and rationale.
  - Open Design verified rules only for short, stable, checkable constraints.
- Rationale: This keeps the full vision readable without turning memory or rules into a giant strategy dump. It also lets Open Design use the material in native ways: design-system posture through `DESIGN.md`, repeatable validation through test stories, and enforcement through verified rules.
- Evidence:
  - User direction: do not completely override existing files; only add to them unless a refactor is discussed first.
  - Project state: roadmap, test stories, and decision log already exist and are actively used.
  - Open Design inspection: project-local skills and built-in plugins support design-system context, critique, roadmap-like planning, and verified rules, but no single native North Star object was found.
- Impact:
  - Future design passes should read `product-vision.md` and `DESIGN.md` before changing core reader, Library, Retelling, first-run, or public-domain content flows.
  - New product claims should be routed to the correct layer instead of being duplicated everywhere.
  - Large refactors of existing docs should be discussed before editing.
- Open questions:
  - Which product-vision principles should become verified rules now?
  - Should a future custom Understand skill require reading this context stack before every prototype pass?
  - Should `DESIGN.md` eventually split into visual, interaction, and content sub-files if it grows too large?

## D028 - Promote North Star Principles Into Verified Rules And Make B7 Next

- Status: documented
- Date: 2026-07-06
- Context: After creating `product-vision.md` and `DESIGN.md`, the next question was how to make the vision active in Open Design without starting a redesign or building a custom plugin too early.
- Decision: Promote five stable North Star constraints into Open Design verified rules, then make B7: Onboarding and first-run proof the next North-Star alignment pass after the then-current selected-text work.
- Added verified rules:
  - First-Run Is A Real Listening Session.
  - Library Is Cold-Open Root.
  - Starter Books Imply Whole Texts.
  - Retelling Stays Accountable To Original.
  - Secondary Tools Do Not Block First Play.
- Rationale: These rules are specific enough to be checked in future scorecards, but broad enough to protect the product promise across Library, Reader, Retelling, first-run, and secondary tools.
- Evidence:
  - User approval: the candidate rules sounded fine and the next work can continue without kicking off redesigns.
  - Product vision: first-run, Library, whole-text continuity, Retelling/Original trust, and non-blocking secondary tools are repeated North Star themes.
  - Roadmap/test stories: B7 already exists as the onboarding and first-run proof batch, but needed clearer next-pass framing.
- Impact:
  - Future artifact passes should be checked against the new rules.
  - B7 should test product-model correctness before visual redesign.
  - Selected text, Library, Retelling settings, and generation work should not crowd first play.
- Open questions:
  - Which B7 screen/state should be patched first: Library cold-open, Play-to-Reader transition, first completion, or import/share continuation?
  - Should the current prototype be audited before patching B7, or should the next pass directly patch the most obvious B7 gap?

## Research Sources

- NN/g: Progressive Disclosure — https://www.nngroup.com/articles/progressive-disclosure/
- NN/g: Input Controls for Parameters — https://www.nngroup.com/articles/sliders-knobs/
- NN/g: Response Times: The 3 Important Limits — https://www.nngroup.com/articles/response-times-3-important-limits/
- W3C WAI-ARIA: Dialog Modal Pattern — https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/

## D029 - Library Play Starts The Real Listening Session

- Status: prototyped
- Date: 2026-07-06
- Context: B7 first-run audit found that the Library was correctly acting as the cold-open root, but tapping a book only opened Reader in an idle state. That made the aha moment one tap too late and made the first-run feel closer to navigation than listening.
- Decision: Library book cards and the Continue card should open Reader and start playback immediately. Completion should point to the next listenable position with a direct Continue action, while Contents remains the detailed navigation surface.
- Rationale: The first-run promise is not "choose a document"; it is "hear difficult text become easier to stay with." Starting playback from Library keeps the root object as a real listening session and avoids making Retelling settings, notes, or import actions prerequisites.
- Evidence:
  - Product vision: cold-open users should begin in Library and get into the aha moment immediately.
  - B7 audit: the main prototype gap was Library selection not starting playback.
  - Prototype: `index.html` now starts playback from Library card actions and adds a completion Continue next action.
- Impact:
  - Future Library cards should distinguish Play/Continue actions from passive selection.
  - Starter books should keep whole-text cues and avoid duration-first sample language.
  - Import/share entry can stay separate until it can join the same listening-session model without delaying first play.
- Open questions:
  - Should the first playback start instantly or use a very brief "Retelling ready" transition for trust?
  - What should happen when the user reaches the final Contents position of a source?

## D030 - Defer Special End-Of-Section Behavior

- Status: decided
- Date: 2026-07-06
- Context: After testing the B7 first-run continuity patch, the open question was whether the end of a section/text needs a special completion state, next-step surface, or decision point.
- Decision: Do not design a special end-of-section flow right now. Standard behavior should be continuous listening: playback keeps going through the available text until the user pauses, stops, or chooses another position.
- Rationale: The product is audio-first. A special completion state risks making the session feel like a demo or task checkpoint instead of an ongoing listening experience. Deeper end-of-text behavior can wait until the app has clearer whole-source continuation rules.
- Evidence:
  - User direction: "how about nothing right now... standard behavior. it just plays until the user pauses it."
  - Product vision: playback should continue by default and the interface should support ongoing listening rather than interrupt it.
- Impact:
  - Do not spend the next batch designing completion modals, celebration states, or forced next-step decisions.
  - If the current prototype has a visible completion affordance, treat it as a temporary wireframe artifact to simplify later.
  - Focus the next batch on import/source states, selected-text annotations, Retelling trust rules, and native shared-text handoff rules.
- Open questions:
  - At the final end of a whole source, should playback stop quietly, return to Library/Continue, or suggest another source later?

## D031 - Shared Text Uses The Same Reader Session

- Status: superseded at UI level; model retained
- Date: 2026-07-06
- Context: The next B7 gap was whether text shared into Understand should become a separate import/demo flow or the same underlying listening-session flow in a different state.
- Decision: Shared text enters the same Reader/source model. The raw Original appears immediately, Retelling preparation runs in the reader-level banner, and the user stays in the same Retelling/Original/Contents model.
- Rationale: Shared text should not teach a second product model. It is another way to create a source and reach the current listening position, with preparation visible but not blocking access to the Original.
- Evidence:
  - Product vision: shared-text entry should be the same flow in a different state.
  - 2026-07-07 correction: the prototype should not expose shared text as an in-app Library or Add text button; the user starts this from another app's OS share sheet and chooses Understand there.
- Impact:
  - Future share-extension work should reuse Reader/source/generation states after native iOS/Android handoff, instead of adding a separate one-off screen or in-app share button.
  - Import, paste, share, and public-domain books should converge on the same source/listening-session model.
  - Shared-text testing should focus on continuity and trust, not visual polish.
- Open questions:
  - In the production app, should shared text bypass the Add text sheet entirely and open Reader directly from the OS share sheet?

## D032 - Voice Notes Are Part Of The Annotation System

- Status: decided
- Date: 2026-07-07
- Context: The v1 endgame plan treated selected-text Add note, Discuss, and Mark problem as primarily touch-driven annotation actions. The user clarified that Understand needs a whole voice notes system: annotations, Discuss, and Add note must be accessible by voice for a hands-free listening experience.
- Decision: Treat voice notes as a first-class Annotation creation path. Voice Add note, voice Discuss, and voice Mark problem should create or draft the same underlying reader marks as touch actions, anchored to the current sentence/range while listening.
- Rationale: Understand is audio-first. Users who are listening while working, walking, commuting, or doing service work cannot rely on touch selection every time they have a thought, question, or trust concern. Hands-free note capture makes annotations fit the listening mode instead of pulling the user out of it.
- Evidence:
  - User direction: "we need a whole voice notes system... all of annotations, like Discuss and Add note need to be accessible via voice."
  - Product vision: the core user may be busy or hands-occupied and needs difficult text made listenable without turning the app into document work.
  - Roadmap/test stories: selected-text annotations were already in scope, but lacked a hands-free capture layer.
- Impact:
  - Selected-text annotation work must include a voice path, not only tap menus.
  - Voice note capture should anchor to the current sentence/range and preserve Original access for trust.
  - Voice Discuss should be framed as a question/comment on the current spot, not a generic chat mode.
  - Voice Mark problem should flag a localized issue without automatically changing the retelling.
- Open questions:
  - Should headset, lock-screen, or spoken-command capture be part of v1 or saved for v1.1?
  - Does voice note confirmation happen by speech, a small sheet, or both?
  - How should users review voice notes later: inline marks, a Notes list, or both?

## D033 - Reader-Level Voice Capture Anchors To The Current Sentence

- Status: prototyped
- Date: 2026-07-07
- Context: The v1 flow list included selected-text annotations, voice notes, import honesty, Library continuity, and offline/cloud fallback. The hands-free note requirement raised the question of whether voice notes should require selecting text first or work from the live listening position.
- Decision: Prototype voice Add note, voice Discuss, and voice Mark problem as command-driven entries into the existing selected-range annotation sheet. Voice chooses the action first, Understand selects the sentence playing now, and saving the transcript creates the same Annotation state used by touch actions. V1 defaults to an in-app mic/hold entry point, and playback audio ducks while dictating.
- Rationale: A hands-free listener should not need to stop and manually select text before capturing a thought, but voice should not become a separate annotation menu. The current playback position is the natural anchor, while the selected-range sheet remains the canonical annotation surface for touch and voice.
- Evidence:
  - Prototype: `index.html` now opens the selected-range sheet in a voice-command state, with the current sentence selected and Add note, Discuss, or Mark problem saving back to the same Annotation object.
  - Verified rule: Voice Access For Annotations requires Add note, Discuss, and Mark problem to be accessible while listening.
  - Form answer: trigger and playback behavior were skipped, so v1 uses the conservative default: in-app hold-to-capture plus ducked audio.
- Impact:
  - Future speech input should feed this same selected-range capture state rather than creating a separate recorder object or voice-notes menu.
  - Voice capture should preserve playback context and Original comparison.
  - Annotation review can later appear as inline marks, a Notes list, or both.
- Open questions:
  - Should headset, lock-screen, or spoken-command capture be part of v1 or saved for v1.1?
  - Should saving a voice problem offer immediate recovery actions, or only mark the spot first?

## D034 - Annotation Composer Is The Shared Save Surface

- Status: prototyped
- Date: 2026-07-07
- Context: After voice capture was added, the prototype briefly risked treating voice notes as a separate product surface. The user clarified that voice commands should behave like selecting the present sentence and using the same Add note / Discuss / Mark problem actions from the highlight menu.
- Decision: Use the selected-range sheet as the shared annotation composer for touch and voice. Touch selects text first and then chooses Add note, Discuss, or Mark problem. Voice chooses the action first, then Understand selects the current sentence and opens the same composer. Saving creates the same Annotation object in both paths.
- Rationale: This keeps the object model small and reader-like. Voice is an access path into annotations, not a new voice-notes menu, recorder object, or chat surface.
- Evidence:
  - Prototype: `index.html` now uses one composer state for touch Add note, touch Discuss, touch Mark problem, and the voice-command equivalents.
  - Roadmap: P5 marked first-pass composer convergence as covered; D035 later added annotation review, selected-range Share, and Transform scope wireframes.
- Impact:
  - Future annotation work should deepen the shared composer and review model rather than adding separate capture surfaces.
  - Inline marks and any future Notes list must be able to show whether an Annotation came from touch or voice without splitting the object.
- Open questions:
  - Does v1 need an annotation review list, or are inline marks enough for first release?
  - Does Discuss become an AI answer thread in v1, or remain a saved question/comment prompt?

## D035 - First-Run Proof, Scope, And Annotation Review Stay In Existing Surfaces

- Status: prototyped
- Date: 2026-07-07
- Context: The flow-next plan identified F1 first-run proof, F2 retelling scope/trust, and F3 annotation review depth as the highest-leverage batch after voice annotation convergence.
- Decision: Keep the next proof surfaces inside the existing product model. Library shows lightweight first-listen progress and a Notes/marks review list. Reader selected-range actions now open scoped Transform text and Share states inside the same selected-range sheet. Source progress is remembered when the reader leaves and returns.
- Rationale: These changes make the product more testable without adding a separate onboarding carousel, a document manager, a Passage object, or a new voice-notes menu. The first session remains Library -> Reader -> Play, while deeper tools appear only after listening starts.
- Evidence:
  - Prototype: `index.html` now tracks first-run milestones for Play, Original comparison, Retelling settings, Annotation, and own-text intake.
  - Prototype: Transform text requires choosing this selection, from here, or whole book/text before generation starts.
  - Prototype: Library Notes and marks can reopen saved highlights, notes, discussion prompts, problem marks, and shared selections.
  - Test stories: R07, P14, A05-A09, O01, and O05 now have testable wireframe coverage.
- Impact:
  - Future v1 work should move to import thresholds, voice/offline/premium hardening, and settings/accessibility boundaries before visual polish.
  - Annotation review can deepen into full note threads and bookmark variants without changing the underlying Annotation object.
  - Transform scope is now explicit enough to test, but production still needs backend rules for source-wide regeneration.
- Saved questions:
  - Does Discuss become an AI explanation thread in v1, or remain a saved prompt/comment?
  - Do failed imports remain in Library as recoverable Sources, or disappear after cancel?
  - Are cloud/premium voices required for v1 monetization, or should they stay v1.1 polish?
  - Which accessibility controls must be visible in v1 rather than buried in Settings?

## D036 - Import, Voice, And Settings Hardening Stay Recoverable

- Status: prototyped
- Date: 2026-07-07
- Context: After F1-F3, the flow-next plan pointed to F5 import thresholds, F6 voice/offline/premium, and F7 Settings/account/accessibility boundaries.
- Decision: Prototype recovery states in the same Library/Reader/Settings model. Import failures remain visible with retry, choose another file, cancel, and paste alternatives. Premium/cloud voices can preview but cannot replace the included local voice until upgrade. Settings carries download failure/retry, offline fallback, accessibility controls, and account deletion confirmation.
- Rationale: The app should feel reliable under failure. Users should not lose the source context, accidentally select a paid/cloud voice, or trigger destructive account/storage actions while listening.
- Evidence:
  - Prototype: `index.html` recognizes oversized and timeout import scenarios and names practical recovery paths.
  - Prototype: Settings local voice pack can move through removed, failed, retry, and downloaded states.
  - Prototype: Premium voice primary action now preserves the free local voice path until upgrade.
  - Prototype: Settings adds text size, high contrast, reduced motion, reading spacing, and two-step account deletion confirmation.
  - Test stories: I04-I05, V05-V09, and G02-G05 now have wireframe coverage.
- Impact:
  - Future import work should map these placeholder states to real parser/backend error codes.
  - Future voice work should decide actual local/cloud/provider fallback policy, but the user-facing recovery model is stable enough for v1 wireframe testing.
  - Future Settings work can deepen legal/privacy copy and accessibility behavior without moving these controls into Reader.
- Saved questions:
  - Should failed imports stay in Library as recoverable Sources after cancel, or should cancel remove them?
  - Which premium/cloud voice failures should offer retry versus automatic local fallback?
  - Which accessibility settings should affect Reader immediately in v1 versus persist as defaults?

## D037 - Settings Uses Object-Led IA Instead Of Dense Control Stacks

- Status: prototyped
- Date: 2026-07-07
- Context: The Settings and Retelling settings surfaces had accumulated too many controls at once: full voice catalog, provider/fallback controls, accessibility, language, plan, model deletion, and account deletion were visible in one dense stack. The user flagged the UX/IA as hard to figure out and full of buttons that felt inert.
- Decision: Reframe Settings around OOUX objects and one job per section. Settings now opens with a map for Voice, Reading/accessibility, Retelling language, and Storage/account. Full voice catalog, language choices, and storage/account actions move behind explicit panels. Retelling settings stays scoped to the current book/text Performance and only exposes style, fidelity, current voice, recommended included voices, and Save.
- Rationale: Progressive disclosure should keep first-level Settings scannable, while deeper catalog/storage/legal choices stay reachable without crowding the listening surface. A Reader drawer should tune the active Performance, not become a voice-store or account-management surface.
- Evidence:
  - Prototype: `index.html` now has a Settings object map and a hidden Manage all voices panel.
  - Prototype: Retelling settings no longer shows locked premium voices in the Reader drawer; it links to the full Settings catalog instead.
  - Prototype: text size, theme, high contrast, reading spacing, reduced motion, and skip interval now visibly affect the wireframe instead of only updating status copy.
  - Test stories: V01, V05, G04, and new G06-G08 describe the simplified IA and behavior.
- Impact:
  - Future Settings work should add subpages or detail sheets rather than expanding the root Settings stack.
  - Favorite voice management is no longer claimed as a dynamic v1 behavior until the favorite list is actually generated from state.
  - Premium/catalog/voice-download work belongs in Settings; the Reader drawer should only expose enough voice choice to keep listening.
- Saved questions:
  - Should Settings eventually become separate native screens instead of inline disclosure panels?
  - Should v1 include dynamic favorite voice management, or keep recommended included voices fixed?
  - Which accessibility defaults should persist globally versus per book/text?

## D038 - Settings Root Routes To Focused Object Subviews

- Status: prototyped
- Date: 2026-07-07
- Context: The first Settings IA pass made the top of Settings more object-led, but the prototype still behaved like one long settings page with scroll-jump cards and nested disclosures. That kept the same cognitive problem: Voice catalog, offline storage, accessibility, language, plan, and account actions still competed in one packed surface.
- Decision: Make Settings a real routed wireframe surface. Settings now has a root map and focused subviews for Voice, Voice catalog, Offline voices, Reading, Accessibility, Retelling language, Plan, and Storage/account. The top-left Settings button returns to the Settings root before leaving Settings. The Retelling drawer deep-links to Voice catalog instead of opening a dense disclosure.
- Rationale: Each Settings object should answer one user question at a time: how does it sound, how do I read, what language are retellings in, what plan am I on, what is stored. This follows the OOUX model more honestly than putting all controls in one vertical stack.
- Evidence:
  - Prototype: `index.html` now tracks `settingsPanel` and uses `data-settings-panel` routing instead of `data-settings-focus` scrolling.
  - Prototype: Voice, catalog, offline voice storage, Reading, Accessibility, Plan, and Storage/account are shown as focused panels.
  - Prototype: Retelling settings now says `Choose voice for this retelling`, while full catalog management remains in Settings.
- Impact:
  - Future Settings work should add new objects as root cards or subviews, not as more rows inside existing panels.
  - This makes Settings easier to translate into native Flutter routes later.
  - Remaining v1 decisions can be tested at the object level: Voice, Reading, Accessibility, Plan, Storage/account.
- Saved questions:
  - Should plan/billing stay in v1 Settings, or be deferred behind an upgrade sheet?
  - Which accessibility controls persist globally versus per book/text?
  - Does Voice catalog need search/filter for v1, or is grouped browsing enough?

## D039 - V1 Closure Sweep Prioritizes Return Paths And Honest Thresholds

- Status: prototyped
- Date: 2026-07-07
- Context: The triple-size V1 closure plan identified remaining open/partial stories around Performance conflict rules, long imports, Library growth, annotation/bookmark depth, persona seriousness, and production thresholds.
- Decision: Patch the current prototype toward V1 closure without adding new product objects. Public-domain search stays visible but paused until the source/API behavior is understood, shared text is treated as a native OS share-extension path rather than an in-app Library button, long imports preserve their processing job when the user leaves and returns, Bookmark is an Annotation variant, and ready/failed Performance decisions block further Retelling edits until resolved.
- Rationale: V1 should close the current OOUX model rather than expand into a document manager, chat assistant, or style toy. The important implementation handoff distinction is now explicit: the wireframe proves the product behavior, while real extraction, speech recognition, generation queues, OS share, and provider handling remain production thresholds.
- Evidence:
  - Prototype: `index.html` keeps Library search paused, removes the misleading in-app shared-text button, adds import return preservation, bookmark action/review, and stronger Performance decision copy.
  - Roadmap: `feature-roadmap.md` now includes a V1 production threshold map.
  - Test stories: S12, R06, R08, P15, L08, and O04 are covered at wireframe level; L06/L07 remain open for public-domain search API and native OS share extension; D041 later covers A02 source-aware note/bookmark review, with threaded replies still open.
- Impact:
  - Future closure work should focus on threaded annotation detail and final QA rather than inventing new surfaces.
  - Public-domain search and OS share remain product paths, but the prototype should not fake either path as an in-app button or starter-book-only search.
  - Performance queueing is intentionally conservative: resolve the current ready/failed decision before editing again.
- Saved questions:
  - Is full note-thread depth required for V1, or can bookmark/note review be V1 with thread detail in V1.1?
  - Should failed imports remain in Library permanently, or be removable after the user cancels?
  - Which public-domain search source is acceptable for production?

## D040 - Import Lifecycle Uses Source, Preparation Job, Contents Positions, And Recovery Actions

- Status: prototyped
- Date: 2026-07-07
- Context: After Library source creation was clarified, the next risk was that PDF/EPUB intake could still read like fake parsing or a generic upload error. The Reader needed to show what object exists, what work is happening, what navigation is available, and what the user can do when the file is blocked.
- Decision: Treat imported material as a Source immediately, then show preparation as a Reader-level job state. Contents may show detected chapters only when structure is readable; otherwise it shows fallback positions. Failed imports stay framed as blocked Sources with concrete recovery actions: Retry, Choose another file, or Remove source.
- Rationale: This keeps the OOUX model clear. A Source is the user's book/text/file; preparation is temporary work on that Source; Contents positions are navigation, not proof of real extraction; recovery actions resolve the blocked Source without blaming the reader.
- Evidence:
  - Prototype: `index.html` now labels the Reader banner as Source preparation, uses Cancel import during processing, uses Remove source on failure, and avoids treating unreadable file content as Original text.
  - Prototype: filename-based import scenarios are explicitly marked test-only; production must use parser results, file metadata, size limits, and extraction confidence.
  - Prototype: imported Source placeholder copy now separates extracted Original, fallback Contents positions, and Retelling readiness.
  - Test stories: S01-S03 and S09 now use Create source / Source preparing / Cancel import language.
  - Roadmap: `feature-roadmap.md` now records Create a source, Source preparing, Remove source, and choose-another-file states.
- Impact:
  - Future implementation can map real parser/backend error codes onto the existing Source lifecycle without adding a separate upload mode.
  - Failed-import policy remains a product decision: remove immediately on cancel, keep recoverable in Library, or archive as failed Source.
- Saved questions:
  - Should Remove source always delete a failed import, or should failed Sources be recoverable from a Library history?
  - Which parser signals distinguish detected chapters from fallback positions in production?

## D041 - Annotation Review Reopens The Saved Source Range

- Status: prototyped
- Date: 2026-07-07
- Context: Notes and marks existed in Library, but Annotation state was keyed only by sentence index. That made saved marks ambiguous once the reader moved between starter books, pasted text, and imported Sources.
- Decision: Store Annotation marks with the Source key and selected sentence/range, then let Library Notes and marks reopen the saved range back in Reader. Highlight, Bookmark, Add note, Discuss, Mark problem, Share, and voice-captured notes remain variants or actions on the same Annotation object.
- Rationale: Annotation is a reader mark attached to a specific Source range. Review should help the reader return to the exact place in the book/text, not create a second note-taking product, a Passage object, or a detached voice-notes list.
- Evidence:
  - Prototype: `index.html` now keys annotations by Source plus range, shows Source/sentence context in Library Notes and marks, and opens the selected range with Retelling/Original still connected.
  - Test stories: A02 is now covered at wireframe level for note/bookmark review and reopen behavior.
  - Roadmap: `feature-roadmap.md` now separates covered Annotation review from later full threaded replies and AI discussion.
- Impact:
  - Future note-thread depth should extend the Annotation object instead of adding a new Library object.
  - Voice-created notes can show their capture path in review, but voice remains an access path into Annotation creation.
- Saved questions:
  - Do notes need replies/thread history in v1, or is single-note review enough until V1.1?
  - Should Discuss become a saved prompt only, or a later AI conversation attached to the same Annotation?

## D042 - Annotation Thread Detail Lives In The Selected Range

- Status: prototyped
- Date: 2026-07-07
- Context: Source-aware Annotation review made saved marks returnable, but the selected-range sheet still only showed action buttons after reopening a mark. The next risk was creating a detached notes screen or chat surface just to show saved note detail.
- Decision: Keep Annotation thread detail inside the selected-range sheet. Saved highlights, bookmarks, notes, discussion prompts, problem marks, and follow-ups render as compact thread entries on the selected range. Add follow-up and Add question reuse the same annotation composer.
- Rationale: The selected range is the object anchor. Review should deepen the Annotation object while preserving Reader context, Retelling/Original continuity, and the existing touch/voice composer path.
- Evidence:
  - Prototype: `index.html` now renders an Annotation detail panel inside the selected-range sheet whenever the selected range has saved marks.
  - Prototype: follow-up notes/questions append to the same Annotation thread rather than creating a new Notes object or voice-notes menu.
  - Test stories: A02 now covers reopening a saved mark and adding a follow-up from the selected-range sheet.
- Impact:
  - Rich AI discussion can later attach to the same Annotation thread without changing the core object model.
  - Voice-created entries and touch-created entries can be distinguished in the thread while still behaving as one Annotation.
- Saved questions:
  - Should v1 support editing/deleting individual thread entries, or only adding follow-ups?
  - When Discuss becomes AI-backed, does the answer appear in this thread or in a separate temporary conversation view anchored to the Annotation?

## D043 - Selected-Range Drawer Prioritizes Annotation Creation

- Status: superseded by D045
- Date: 2026-07-07
- Context: The selected-range drawer had become an equal-weight grid of Reader, Understand, and Keep actions. Add note and Discuss were buried beside utilities, making the drawer feel like a generic tool menu instead of a reader action surface.
- Decision: Make Add note and Discuss the primary selected-range actions. Keep Highlight, Bookmark, Original/Retelling, Listen, Transform, Share, Copy, and Problem as compact utility actions below them. Existing saved marks and thread entries still appear above the action area.
- Rationale: When a reader selects text, the highest-value creation actions are saving a thought or question. Other actions are useful, but they should not compete with the Annotation spine.
- Evidence:
  - Prototype: `index.html` now uses two primary action cards for Add note and Discuss, plus a compact utility grid for secondary actions.
  - Test stories: A02 now tests the primary Add note card and compact Bookmark action.
  - Roadmap: `feature-roadmap.md` now describes the selected-range drawer hierarchy rather than only listing available actions.
- Impact:
  - Future selected-range additions should be grouped by reader intent and should not return to an equal-weight action wall.
  - Discuss remains a saved question on the Annotation thread until the AI-backed discussion behavior is designed.
- Saved questions:
  - Should Problem stay visible as a compact utility, or move behind an overflow once recovery behavior is richer?
  - Should Transform stay in the range drawer, or move closer to Performance when scope decisions mature?

## D044 - Selected-Range Actions Must Be Thumb-Sized

- Status: prototyped; primary-action model superseded by D045
- Date: 2026-07-07
- Context: After D043 improved hierarchy, the selected-range drawer still had 34px secondary action targets. That was too small for a mobile reader where users may be listening, walking, or using one hand.
- Decision: Keep Add note and Discuss as large primary cards, and make all visible secondary selected-range actions at least 44px tall. Use a two-column utility grid instead of four tiny columns.
- Rationale: The selected-range drawer is a mobile control surface. It should prioritize thumb accuracy and confidence over fitting every action into the smallest possible vertical space.
- Evidence:
  - Prototype: `index.html` now uses 74px primary cards and 48px secondary utility buttons in the selected-range drawer.
  - Test stories: A02 now checks thumb-sized selected-range actions.
  - Roadmap: `feature-roadmap.md` now records thumb targets as part of the selected-range drawer status.
- Impact:
  - Future drawer actions should either meet the same target-size floor or move behind a secondary surface.
  - Compact does not mean tiny; secondary actions can be visually quieter while remaining easy to tap.
- Saved questions:
  - Should Share and Copy move behind a More action if the drawer becomes too tall after future additions?
  - Should Mark problem stay visible at all times or appear only after Original comparison?

## D045 - Discuss Is A Later Action On Saved Annotations

- Status: prototyped
- Date: 2026-07-07
- Context: The selected-range drawer still treated Add note and Discuss as two sibling creation actions. The user questioned whether they were actually the same object, with the difference only appearing later in what someone does with saved notes.
- Decision: Collapse note and question creation into one primary Add note or question path. Discuss becomes a later action on one or more saved Annotations, using the selected range, surrounding source context, Original, Retelling, and book/text metadata. Mark problem remains separate because it signals retelling quality/recovery.
- Rationale: Annotation is the durable object. A question, reminder, highlight, bookmark, or voice note is saved first; discussion is a use of that saved material. This keeps the Reader from turning into a chat surface and avoids duplicating Add note with a second creation button.
- Evidence:
  - User direction: Add note and Discuss should be the same thing; the distinction is what the user later does with saved notes.
  - Prototype: `index.html` now has one large Add note or question card in the selected-range drawer and a Discuss note action inside saved Annotation review.
  - Test stories: A02 and A08 now test note/question creation plus later saved-annotation Discuss behavior.
  - Roadmap/design docs: `feature-roadmap.md` and `DESIGN.md` now describe Discuss as a later saved-annotation action.
- Impact:
  - Future AI discussion should attach to saved Annotations rather than becoming a free-floating chat entry point.
  - Voice question capture remains valid, but it saves a question Annotation first.
  - Selected-range creation actions stay simpler and more thumb-friendly.
- Saved questions:
  - Does V1 need an actual AI discussion result, or is selecting saved annotations for future discussion enough?
  - Should users be able to discuss multiple saved annotations together from Library Notes and marks?

## D046 - Selected Text Splits Native Popover From Understand Drawer

- Status: prototyped
- Date: 2026-07-08
- Context: The selected-text interaction still felt like a flat menu even after the first hierarchy pass. The user pointed out two problems: basic reader actions and AI-enhanced actions were not distinct enough, and Add note had been under-classified as basic even though saved notes can later become AI discussions. A visual bug also made some action buttons read as white text on a white background.
- Decision: Split selected text into two surfaces. Copy, Highlight, and Share live in a compact anchored popover that behaves like familiar mobile text selection. Rewrite selection, Translate selection, Add note, and quiet Mark problem live in the bottom selected-range drawer as Understand-enhanced actions. Add note remains an Annotation creation path, but it is grouped with AI-enhanced actions because the saved note can later become a discussion. Saved-note detail now offers Edit note, Add another note, and Discuss with AI instead of reply/thread copy.
- Rationale: Native text actions are immediate utilities; Understand actions need more context, larger targets, and clearer helper copy. Separating them keeps the e-reader feel while preserving the product-specific comprehension layer. Treating Add note as AI-enhanced also matches the real object model: discussion is a later use of a saved Annotation, not a separate creation action.
- Evidence:
  - User direction: Copy, Highlight, and Share as a small popover; Rewrite, Translate, and Add note in a bottom drawer.
  - User correction: Add note is AI-enhanced because notes can become discussions.
  - Prototype: `index.html` now renders the compact popover for Copy/Highlight/Share and the drawer for Rewrite/Translate/Add note/Mark problem.
  - Prototype: saved notes can be edited, another note can be added, and Discuss with AI starts from the saved-note state.
  - Roadmap/test stories: `feature-roadmap.md` and `test-stories.md` now describe the popover/drawer split and updated saved-note test path.
- Impact:
  - Future selected-text additions should decide whether they are native reader utilities or Understand-enhanced actions before adding controls.
  - Add note should not be treated as merely basic text annotation if the current flow can turn it into AI discussion later.
  - Reply/thread language should stay out of the v1 UI unless the product deliberately commits to threaded note history.
- Saved questions:
  - Does Translate stay in the selected-range drawer, or should it become a compact native-style action if it is used frequently enough?
  - Does V1 need full AI discussion output, or is the saved-note-to-discuss handoff enough until v1.1?

## D047 - V1 Closure Keeps Search And OS Share As Explicit Thresholds

- Status: documented
- Date: 2026-07-08
- Context: The V1 closure audit found the prototype now covers all P0 stories and the selected-text/Annotation depth needed for review, but two Library/growth stories still depend on implementation choices outside the current wireframe.
- Decision: Keep public-domain search and share-in as explicit thresholds instead of faking them in the prototype. Public-domain search remains visibly paused until a source/API and result fields are chosen. Share text into Understand remains a native OS share-extension path, not an in-app Library or import button. Rich AI discussion output is also left as a V1/V1.1 product decision; the current V1 wireframe covers the saved-note-to-discuss handoff.
- Rationale: Faking search results or adding an in-app share button would make the app look more complete while teaching the wrong product model. V1 closure should preserve the core Source -> Retelling/Original -> Audio -> Annotation model and mark production-native capabilities honestly.
- Evidence:
  - Prototype: `index.html` shows paused Library search, no in-app share-import button, selected-text share for existing ranges, and saved-note Discuss with AI handoff.
  - Test stories: `test-stories.md` now distinguishes covered P0/P1 wireframe behavior from intentionally open threshold stories `L06` and `L07`.
  - Roadmap: `feature-roadmap.md` now narrows next work to final QA, production thresholds, public-domain search source/API, OS share extension, and AI discussion output scope.
- Impact:
  - The next prototype pass should be visual/QA or a targeted threshold decision, not another broad feature-discovery batch.
  - Implementation handoff must include search source/API, share-extension payload handling, backend extraction, generation queues, speech recognition, storage/account deletion, and accessibility persistence.
- Saved questions:
  - Which public-domain catalog/API is acceptable for rights-safe starter-book search?
  - What payloads should the iOS/Android share extension accept at launch?
  - Does V1 need visible AI answer output, or can Discuss with AI remain a saved-annotation handoff until V1.1?