feat: product and QA review against the PRD, twenty findings fixed and driven in the web harness

[jag3773]

What this is

A product-owner and QA review of the built app against docs/PRD.md, then the fixes. Every Must requirement in sections 7 to 13 was compared with its code, its scenario and its strings. Twenty misalignments were found where a scenario proved a kernel fact the screen did not show, or proved a narrower proxy than the requirement. GitHub refused issue creation from the session at the time, so the findings were fixed directly; they are listed below with the extra defects found while testing.

The twenty findings

Study

• ST-3, ST-1: a saved "Everyday words" choice made a literal-only language unreadable, with no toggle to escape. The reading now falls back to the text the language carries.
• ST-7: a downloaded Hebrew or Greek text could not be opened unless the language had both a literal and a simplified text. The originals join the reading choices whenever installed, and a language with no text offers them from its empty state, with a way back.
• ST-1, ST-10: Study reopened at the chapter and bookmarks were chapter-only. A tapped verse is journaled through a new corpus.opened, so last-read, Home's Continue reading and bookmarks are at the verse.
• ST-4: the audio bar offered a download for a chapter the installed Audio Pack did not carry. It now says the chapter has no audio.
• ST-5: most library cards had no count. Every card counts in its own unit; the header counts resource types.
• ST-6, ST-2: an unresolvable article link was silent, and "helps not on this phone" showed when the chapter simply had none.

Home, onboarding, settings

• HO-5: the download card hid what was on the phone and what was missing. It now states both, and shows the last install failure for the language in place.
• HO-5, ON-2: "Downloading continues when you are online" promised a resumption nothing performed. The copy now says to connect, then tap.
• ON-3: the Settings first-name field did not opt out of system autofill the way onboarding did. It does, and ON-4 refuses a name field that does not.
• SE-1: the Settings footer named four of the seven counted folds. It now summarises without a partial list.

Formation

• FO-2, FO-3: a movement's text was dropped whenever it had questions. Text and questions render together, with the kernel naming where the questions came from.
• FO-5: turning on the English movements removed the local-language study questions. "Alongside" now means both.
• FO-1: Training was a flat lesson walk. It has a course outline grouped by manual, with the active group's lesson marked.
• FO-3, FO-4: Play silently moved a group forward. It starts the session at the opened story and asks in one sentence before moving the group.

Languages

• LA-1: the offline copy said only installed languages were listed while the cached catalog was shown; the empty state misreported its cause. Both are honest now.
• LA-1, PRD 8.4: language rows showed no size before download, and the resource count included other publishers' copies. Catalog releases carry the sum of their ingredient sizes, rows say "about {size}", and the count is what the pack offers.

Partners and About

• PA-2, PA-6, PRD 9: opening the full story from the Home invitation was not counted as an impact-story open. It goes through partners.open now.
• PA-6: a placeholder security note was asserted for feed stories that had none. The note shows only when the story carries one; the shipped story carries its own.
• PA-2: the region test was locale OR time zone, which would show the partner card to any en-US phone worldwide. It now needs a United States time zone and a locale region that is US or unknown (decision 97).
• PRD 10.2, decision 68: About lacked the full lockup, and "opens in your browser" was only a screen-reader hint. Both are visible now.
• PRD 10.1: product names left the running copy in Languages and Transfer.

Found while testing, also fixed

Driving the real screens in Chromium over the memory adapters found four defects the extended scenarios had not caught: choosing the Hebrew text did nothing when Study opened at its last-read place (open() ignored the request); the library's Five movements card could not install the formation row; "Continue in English" on a fresh phone failed with pack.empty-plan because no catalog had been fetched yet and Home showed nothing wrong; and Home never redrew its download card when a pack landed in the background, because it listened to preferences and bookmarks only. The packs module now records an install-wide failure per pack and exposes onChange.

An adversarial read of the diff found seven more: the original-text view was a dead end for a language with no text, every verse tap re-assembled the chapter and journaled an event, the Home count over-counted during an update, the Training outline could split a manual in two, its empty state misreported the cause, the Languages count and size disagreed, and the move prompt appeared after a failed start.

Decisions taken

Recorded in the PRD decision log (row 97) and the scenarios: the invitation's region test needs both signals; last-read and bookmarks are at the verse; Play never moves a group without a confirm; the Languages count is what the language pack offers; the Library header counts resource types. Each is a product call the PRD left open; say so if any should go the other way.

Strings

21 keys added and 9 reworded in English and drafted in the 15 locales with each locale's plural categories (docs/strings-review.md). impact.securityNote, formation.coverage.questions and study.audio.streaming removed everywhere. strings check: 491 keys in 16 locales, each 491/491.

Verification

• npm run verify green on the final tree: lint and format, typecheck, 822 tests, knip, 9 checks, 63 scenarios, 51 Must requirements traced (0 unproven), 21 fixture burritos, both bundles clean of sim code. The live contract step was skipped: git.door43.org answers 403 from the sandbox.
• Each extended scenario was observed red before its fix (ST-1, ST-3, ST-4, ST-5, ST-7, HO-5, HO-7, ON-2, ON-4, FO-1, FO-3, FO-4, FO-5, LA-1, PA-2, PA-6).
• npm run shots: 182 screenshots across light, dark, reduced blur, RTL, Urdu, Hindi and large text; 0 text boxes escaping their parent; 39 targets under 44 px, all inline links exempt under decision 86; no page errors.
• Driven flows in Chromium, light and dark: onboarding and Continue in English, Home, Study with verse taps and bookmarks, the library downloads, the originals, Formation sessions with and without the five movements, the Training outline, the move-the-group confirm, Languages, Settings, About and the impact story. No page errors.
• Not run: anything on a phone, an emulator or a simulator. The sandbox has no KVM or CPU virtualization and cannot reach the Android SDK host. The device CI on this PR is the first native run of these changes. Please look at the new Training screen, the move confirm in the session dock and the no-audio state in light, dark and reduced blur, and with VoiceOver or TalkBack.

Progress tracker entry: docs/progress_tracker.md, 2026-10-05 Q1.

No new dependencies.

🤖 Generated with Claude Code

https://claude.ai/code/session_01SLy4DDVTydCyFA38LqekuJ

---

Generated by Claude Code

[jag3773]

CI on 0aae23f: verify, shots and ios are green. android shows cancelled, not failed: its required main pass passed in 4m37s and the optional pass finished at 18:28 (large-text passed), then the emulator runner's own "Terminate Emulator" post step hung for 43 minutes until the job's 75-minute timeout cancelled it. Nothing in this diff touches that step, and the first run of the same workflow on this PR tore the emulator down normally. Re-running the cancelled job once; a second hang would be the runner, and then the job needs a shorter emulator teardown, not a change here.

The earlier ios failure is explained and fixed in 0aae23f: on main a fresh phone never actually downloaded English in CI (the pack.empty-plan path this PR fixes), so Home sat idle during the flows; with a real install running, the software-rendered simulator's progress card kept XCTest from snapshotting the view tree. The required iOS pass now runs with the content hosts offline; the optional pass keeps them online for download-language.yaml.

---

Generated by Claude Code