Usability wave plan¶

Status: [~] active — authoritative sequencing for the current product focus (ROADMAP Now — Usability wave). Hardening Phases 1–6 (U0–U1) are done; U3 daily workbench is done; open track is U2 (Home and Diagnostics shipped; sample notebook and first-run install docs remain); U4 acceptance gate is green (Inbox polish may continue). Post-U3 deepen-in-place (OCR fail-fast circuits, Moments/chart jump → Reading, Overview/Mood corpus/period charts, Analyse launcher vs View consume split, OCR Review workbench with tabbed Transcription / Date / Tags / Other lanes) is shipped — not a new wave track.

0.9.0 cut: U2 acceptance is required together with infrastructure I0–I6 (ROADMAP Path to 0.9.0). After 0.9.0: 0.9-1 unfamiliar testing (dev/user_testing_0_9.md), then 1.0.

Thesis: Transcribe already has a complete core analysis set and durable OCR/analysis execution. Ordinary users still meet module-mechanics chrome, thin first-run guidance, and weak daily-workflow surfaces. This wave makes the workbench trustworthy and usable end-to-end — from install to export — without scheduling new analysis modules or deferred reinterpretations.

Trust foundation          Daily workbench              Living corpus
(phases 3–6)       →      (onboard · review · read)  →  (inbox · bulk · search+)

Detection Prompt Hub / Detect UI is a shipped parallel track (detection_wave2_plan.md via PR #6). It is not the centerpiece of this wave and must not steal naming (“Wave 2”).

1. Goals and non-goals¶

Goals¶

Trust without literacy — Ordinary Analyse / Export workflows never require understanding module ids, cache identity, plan hashes, or capability enums.
Honest health — Every analysis surface answers the same question: “is this current and healthy?”
Provenance — Exports identify the notebook revision that produced them.
First successful notebook — A new user can install, pull a model, import, OCR, review, and export without reading contracts.
Daily correction loop — Review is a queue of work (dates, edits), not only a page browser.
Living with notebooks — Search, organisation, and reading improve on today’s project model; bulk inbox is supported after the corpus acceptance gate.

Non-goals (explicit)¶

Out of scope	Why
New analysis modules / deferred reinterpretations / `ocr_quality`	ROADMAP.md deferral stands
OpenCV preprocess pipelines	Pillow-only policy
Cloud OCR providers	Product boundary
Treating Detection Wave 2 as this wave’s definition of done	Parallel track (shipped)
Shipping supported bulk-import UI/CLI before the corpus-integrity acceptance gate	Contracts-first rule (gate now green; keep suite green)
Corpus-level Analyse / cross-notebook links / bookmarks	Later candidates — light this vs corpus/period average charts on Overview/Mood are shipped as product read-models over published metrics (dev/analysis_visual_compare.md); not a corpus Analyse runner. Related pages / Slices / reconstruction are After 1.0 on ROADMAP.md, gated on 1.0 — not this wave

Naming¶

Say	Do not say
Usability wave, tracks U0–U4	Wave 2 (reserved for Detection drafts)
Core modules	Wave 1 (internal history only — analysis_wave1_plan.md)
Product views / status strip	“Module console”, “payload dump” as primary UI

2. Relationship to existing work¶

Artifact	Role in this wave
product_hardening_plan.md Phases 3–5 (#5/#6/#11/#12/#13)	U0 — done on `main` (PR #5)
Hardening Phase 6 (#7–9)	U1 — done (product views, status strip, OCR Advanced)
analysis_wave1_hardening_plan.md	Done infra; do not reopen as UI work
Detection wave 2 (PR #6)	Shipped parallel track; coordinate only where Prompt Hub / page-viewer findings share chrome
Corpus contracts	U4 acceptance gate green; bulk-import UI/CLI supported; Inbox polish may continue
infrastructure_wave_0_9_plan.md	Parallel 0.9 maintainer-infra programme (CI/docs/release hygiene). Together with U2 enables 0.9.0 cut. Does not own U2 product content; do not serialize U2 behind it. Unfamiliar testing is 0.9-1, not this wave

Dependency rule: U1 consumes AnalysisHealth / content_revision from U0 (both landed). Do not invent a second freshness model.

        flowchart LR
  U0[U0 Trust foundation]
  U1[U1 Analyse product UX]
  U2[U2 First-run operability]
  U3[U3 Daily workbench]
  U4[U4 Corpus UX]
  U0 --> U1
  U0 --> U2
  U1 --> U3
  U2 --> U3
  U3 --> U4

U2 may start in parallel with U1 once U0 is merged (onboarding does not depend on Analyse chrome). U3 prefers U1’s status-strip patterns. U4 mechanics (acceptance gate) are done; Inbox polish may continue independently.

3. Track overview¶

Track	Intent	Hardening IDs	Status
U0 — Trust foundation	Preset identity, plan-hash bind, content revision, shared health, export provenance	#5 #6 #11 #12 #13	[x] done (PR #5)
U1 — Analyse product UX	Product views, shared status strip, OCR Advanced	#7 #8 #9	[x] done
U2 — First-run & operability	Install path, sample notebook, model guidance, doctor/diagnostics in UI	—	Planned
U3 — Daily workbench	Review queues, reading mode, search/org polish (no bulk corpus activation); Library activity bins + cover-grid paging + page delete + model-info picker wiring	—	[x] done
U4 — Corpus UX	Inbox / import recovery / bulk import; acceptance gate green	—	[x] gate green (polish open)

4. U0 — Trust foundation¶

Outcome: Users can trust exactly what a preset will run; every analysis surface shares one health answer; exports cite a notebook revision.

Status: [x] done on main via PR #5 (cursor/hardening-phases-3-5-4764). Hardening checklist rows #5/#6/#11/#12/#13 are closed.

Deliverables (landed — do not fork semantics)¶

ID	Deliverable	Contract authority
#5	Freeze `AnalysisRunPlan` + `plan_hash` at launch; start refuses mismatch; no live re-snapshot	analysis-run-storage.md
#6	Named presets `content_version` + policy fingerprint; Custom = module-list fingerprint	workspace-settings.md
#11	Hex `content_revision` over exportable page content	project-on-disk.md
#12	Derived `AnalysisHealth` shared across Overview / Themes / Mood / Moments / Summaries; Ask out of batch scope	analysis-result.md
#13	Same `content_revision` on JSON, manifest, Markdown header, plaintext header	notebook-export.md

Acceptance¶

Offline tests for plan-hash bind, preset version bumps, revision stability, health aggregate priority, export stamp coherence (landed with PR #5).
ROADMAP hardening table marks Phases 3–5 [x].
Known limitations updated for health / plan_hash / preset versions / export stamps.
Does not remove module-id banners or st.json dumps — that is U1.

Key files¶

src/transcribe/analysis/{plan,presets,coordinator,health}.py, domain/content_revision.py, services/export.py, ui/{run_analysis,analysis_health_view,app,settings_analysis}.py, phase 3–5 tests, contracts listed above.

5. U1 — Analyse product UX (hardening Phase 6)¶

Status: [x] done on main (hardening exit gate + Phase 6 notes).

Outcome: Analyse and Transcribe surfaces read as user tasks, not module/OCR consoles. Builds on U0 health/revision.

Later deepen-in-place (shipped, not a new U1 reopen): Analyse is the launcher only (This notebook | Batch). Product read-models live under View (Reading, Overview, Themes, Mood, Summaries, People & Places, Detect) and consume current published.json. Mood hosts Moments; Summaries hosts Ask. Jump-to-page / page-series clicks open Reading, not Review. See public_surfaces.md.

Parse checklist parenthetical #7–9 as three shippable items:

#7 — Product views¶

Replace module-console chrome with task-shaped read-models.

Surface	Primary content	Demote / hide from default path
Overview	Counts, diversity, entities, theme chips, charts	Raw module ids as section titles; capability/`outcome=` banners; payload `st.json`
Themes	Topics, wordclouds, similarity narrative	Per-module JSON expanders
Mood & tone	Emotion / affect / hedging strips	Enum dumps
Moments	Salient quotes with jump-to-page	Internal module labels
Summaries	Highlights → summary → insights (and LLM when healthy)	Parent-cache literacy
Ask	Question + answer	Stale batch payloads; treat as ad-hoc (already)
Last run	Short product summary (“Balanced v3 · 12 modules · healthy”)	Per-module `outcome=` lists as default

Rules

Capability honesty stays, but in product language (“Needs a text model”, “Optional BERTopic not installed”, “Not enough text yet”) — not unavailable_model as first-class chrome.
Power users may still open an Advanced / technical details expander per tab or once globally.
Existing read-model helpers and module_ui_groups stay the composition layer; do not invent a second analysis runner.

#8 — Status strip¶

One shared health strip (consume render_aggregate_caption / AnalysisHealth from U0):

Placement: on View consume pages (and optionally in Workflow Analyse header while a run is active). Originally above Analyse result tabs; those tabs moved to View.
Answers: revision short prefix · aggregate state · whether a run is active/interrupted.
Per-tab duplicate freshness banners collapse into the strip; tab bodies show content or a single empty/unavailable state.
Ask caption continues to state it does not update batch health.

#9 — OCR Advanced¶

Transcribe (Run OCR) primary chrome:

Vision model
Start transcription
Optional one-line cleanup toggle (or clearly secondary)

Collapse under Advanced: workers, force re-OCR, cleanup mode/model detail, unverified-identity tips, capability dumps, remote-host acknowledgement (keep safety-critical acknowledgement visible or confirm-gated — never bury the privacy footgun without a confirm).

Acceptance (U1 exit)¶

No ordinary Analyse path requires reading module ids or st.json to understand results.
One status strip is the sole default freshness/health answer across batch tabs.
Transcribe primary path is model + run (+ optional cleanup); power controls under Advanced.
Acceptance / UI contract tests: tests/unit/test_analyse_ui_contract.py (extend) asserts product copy for common unavailable states; smoke on port 8510.
public_surfaces.md + user_guide.md describe product views, not module consoles.
Hardening Phase 6 and ROADMAP hardening exit gate close when U0+U1 acceptance tests pass.

Key files¶

src/transcribe/ui/notebook_views.py, ui/app.py, ui/analysis_health_view.py, ui/run_analysis.py, ui/module_ui_groups.py, docs above, Analyse UI contract tests.

6. U2 — First-run & operability¶

Outcome: A motivated non-expert reaches a first exported notebook via Docker (preferred) without digging into contracts or host Python setup.

U2.1 — Home (shipped; replaces the setup-wizard sketch)¶

This Home replaces the earlier U2.1 sketch (setup checklist + Open sample on empty Home). Sample notebook stays U2.2. Do not ship a wizard TranscriptX already removed.

Step	Behavior
Empty workspace	Home empty state: Create notebook + Import (at most two CTAs). No Open sample.
One-line health	Ollama reachable / not reachable, plus a vision-model count when discovery works
Non-empty Home	Cheap archive counts (notebooks / pages), bounded recent list (8) with action strips. Does not scan every `published.json` on load.

No telemetric onboarding — local session / workspace only.

U2.2 — Sample / demo notebook¶

Ship a small fixture notebook (few pages of public-domain or synthetic handwriting scans or text-backed pages with placeholder images) under a documented path (e.g. samples/demo-notebook/ or generated into projects on demand).
One-click Open sample copies into TRANSCRIBE_PROJECTS_DIR via existing init + import services — not a second project format.
Sample should be analysable offline for deterministic modules (so Analyse demos without LLM).

U2.3 — Diagnostics in UI¶

Status: [x] shipped (System → Diagnostics).

Capability	Behavior
Workspace doctor	Always available (`corpus-doctor`, optional deep hashing)
Notebook doctor	When a notebook is selected in View
Ollama	Same one-line reachability as Home
Recovery / paths	Short copy; Settings still explains inbox/export mounts

Speaker-profile repair is out of scope.

U2.4 — Docs & install path¶

Tighten runtime/installation.md / runtime/docker.md into a “first notebook in 15 minutes” path linked from README empty-state — Docker preferred, host/Python under Advanced.
Document port 8510, absolute HOST_PROJECTS_DIR, Linux extra_hosts, UID/GID once in the first-run doc — not scattered only in deep runtime notes.
Surface known_limitations.md items that bite first run (encrypted PDF, large budgets, cleanup latency).

Acceptance (U2)¶

Empty Home presents Create + Import (no sample wizard).
Sample notebook path works offline for import → (optional OCR skip if pre-seeded text) → Analyse Quick → Export.
Doctor results visible in System → Diagnostics with workspace always / notebook when selected.
README / user guide point at the first-run install path; no contract reading required for the happy path.

U2 close enables the 0.9.0 cut (with I0–I6). Next product phase after 0.9.0: 0.9-1 unfamiliar testing — not more usability-wave tracks.

Key files¶

ui/home.py, ui/diagnostics.py, ui/shell.py, ui/settings_hub.py, services/doctor.py, samples/ (U2.2), README, docs/runtime/*, docs/user_guide.md.

7. U3 — Daily workbench¶

Status: [x] done — Review queue, Reading mode, Search period parity, org tag chips, model product copy.

Outcome: After first success, living with one or many notebooks feels deliberate: correct faster, read comfortably, find things, organise lightly — without activating bulk corpus contracts.

U3.1 — Review as a work queue¶

Today Review opens the shared page viewer with thin empty states (app.py Review section; page_viewer.py).

Add	Detail
Needs-attention filters	Unapproved suggested dates · pages with no text · failed OCR · (optional) edited-vs-raw
Batch date actions	Approve/ignore visible suggestions for N pages with clear feedback
Faster edit loop	Keep ←/→; emphasize save affordance; reduce hover-only destructive controls where practical
Honesty	Time-of-day still ignored until Future metadata ships; unapproved dates still timeline-indexed — call out in Review chrome

U3.2 — Reading mode¶

Distinct from Review (edit) and Analyse:

Chronological page image + text pairing, distraction-free chrome, jump-by-date when dates exist.
Reuse page viewer data path; presentation mode / route under View → Reading — no new on-disk format.
Optional “continue reading” remembers last page in session or lightweight UI state (not a new contract).

U3.3 — Search & Library deepening (FTS, not corpus index)¶

Stay on rebuildable archive SQLite (known_limitations.md):

Improvement	Notes
Date range on Search	Library already has period/range; bring coherent filters to Search
Clearer empty states	Distinguish “no notebooks” vs “no hits” vs “cache rebuilding”
Jump richness	Preserve highlight + open-in-viewer; raise discoverability of jump-to-page
Activity-bin filter	Landed on Library: click a timeline bar to filter to that date bin
Strip paging	Landed: `ui.archive_notebooks_initial` (Settings → Configuration → Library); `0` = show all
Not yet	Entity filters, saved searches — design stubs OK; implement only if cheap on current FTS

Do not treat archive.sqlite as backup authority (unchanged support policy).

U3.4 — Notebook organisation polish¶

On existing title / tags / cover_page_id (no schema expansion required for MVP):

Library: cover thumbnails, tag chips, sort clarity, rename/delete discoverability (menus already exist — tighten empty/error copy).
Page delete in the page viewer landed (refuses last page / OCR job lock).
Optional soft fields only if contract bump is justified: short description — otherwise skip.
Collections / archive-state / user sort order → defer to post-U4 or later candidates unless a tiny settings-only sort lands without corpus index.

U3.5 — Model & runtime management (product abstraction)¶

Transcribe panel already lists/refreshes models. Deepen:

Model information expander follows the live picker selection on This-notebook / Compare forms (landed).
Show availability, approximate size when known, last-used, verified vs unverified identity.
Short recommendations for “first OCR” vs “quality” without hard-coding a single vendor promise.
Text-model requirements for Analyse LLM modules explained in the same vocabulary as U1 product copy.

Acceptance (U3)¶

Review offers at least one needs-attention filter and batch date approve/ignore.
Reading mode ships as a distinct presentation (documented in public surfaces).
Search gains date-range (or documented parity with Library filters) and clearer empties.
Model panel explains verified identity and text-model needs in product language.
No dependency on corpus index / ImportRun activation.

Key files¶

ui/page_viewer.py, ui/archive_views.py, ui/shell.py, ui/app.py, services/archive.py, docs/public_surfaces.md, docs/user_guide.md.

8. U4 — Corpus UX¶

Outcome: Human continuation of bulk import: inbox / import recovery as the corpus home screen. The corpus-integrity acceptance gate is green; bulk-import UI/CLI are supported. Inbox polish (richer outcomes taxonomy / TRANSCRIBE_INBOX_DIR scan) may continue.

Hard gate (satisfied)¶

Supported bulk-import UI/CLI and inbox-as-product required:

Corpus index writers + locks (notebook-corpus.md) — done
ImportRun / plan / resume (import-run.md) — done
Duplicate policy on commit (source-asset.md) — done
Corpus doctor checks + synthetic multi-notebook suite (corpus-integrity.md) — done

Product UX (polish continuing)¶

Surface	Intent
Inbox	Path-typed folder / parent-of-folders ImportPlan (shipped); optional later: scan `TRANSCRIBE_INBOX_DIR`; richer imported / failed / duplicated / needs-review taxonomy
Recovery	Resume interrupted ImportRun; explain skip_existing vs create_duplicate
Corpus home	Natural landing after a dump of scans — not only Workflow → Import uploader
Doctor	Deep corpus doctor from U2 diagnostics when index present

Acceptance (U4)¶

Acceptance gate green before any “supported” bulk/inbox claim in public surfaces.
Inbox workflow shows outcomes for imported / failed / duplicated / needs-review (polish).
Crash-injection and idempotency covered by corpus suite; doctor recovers index.
ROADMAP corpus section moves from planned → done for the shipped slice; remaining lifecycle items (quality thumbs; longevity/upgrades beyond backup) stay candidates unless explicitly pulled in. Workspace backup/restore is shipped (see ROADMAP lifecycle table).

Key files¶

src/transcribe/corpus/*, services import orchestration, ui inbox/recovery views, settings_hub.py, corpus contracts + tests under the integrity suite.

9. Parallel tracks (coordination only)¶

Track	Coordination rule
Detection Wave 2 (PR #6; detection_wave2_plan.md)	Shipped; may share page-viewer finding captions and Prompt Hub settings; must not redefine Analyse health or block U1
Visual declutter expansion	Remains ROADMAP preprocessing candidate; explicit re-apply is shipped; further ops not required for usability-wave exit
OCR lifecycle (multipass / prefer / promote / composite / fine-tune)	Shipped (W0–W5 / PR #15); Review queue only needs honesty around suggested dates / force re-OCR
Quality thumbs / prompt management UI	Candidates; Detection Prompt Hub may absorb prompt browse — do not duplicate

10. Wave exit gates¶

Hardening close (U0 + U1)¶

Matches ROADMAP.md hardening exit gate:

Crash/reopen, stale detection, offline operation, export provenance, and normal Analyse workflows covered by acceptance tests.
No ordinary user workflow requires understanding module/cache internals.

Usability-wave close (U0–U3; U4 polish separately)¶

Gate	Evidence
Trust	Phases 3–6 checklist `[x]`; UI contract tests green
First-run	Sample path + checklist + doctor UI documented and smoke-tested
Daily loop	Review queue + reading mode + search filter parity smoke-tested
Honesty	known_limitations + public_surfaces updated
Corpus	Acceptance gate green; bulk/inbox claimed as supported in public surfaces

U4 Inbox polish may remain open after the usability wave is declared done for U0–U3; say so in ROADMAP status.

11. Documentation updates required as tracks land¶

Doc	When
product_hardening_plan.md	U0/U1 status rows
ROADMAP.md	Point Now at this plan; tick phases; move U2/U3 into active sequencing
public_surfaces.md	Product views, Reading mode, Diagnostics, Inbox (only when supported)
user_guide.md	First-run, Review queue, Reading
known_limitations.md	Health, presets, export revision, Review date caveats
TERMS.md	`plan_hash`, `content_revision`, `AnalysisHealth` (landed with U0)
USER_INDEX.md / DEV_INDEX.md / index.md	Link this plan

13. Success metrics (qualitative)¶

This product does not ship analytics telemetry. Use local evidence:

Maintainer can complete sample → Analyse Quick → Export with LLM offline and without opening st.json.
Fresh install checklist catches missing Ollama / vision model before a mysterious OCR hang.
Review batch-approves a notebook of suggested dates in one pass.
Export artifacts share one content_revision a user can cite.
Settings inbox / Import → Batch is a real recovery home (never a dead caption).

Usability wave plan¶

1. Goals and non-goals¶

Goals¶

Non-goals (explicit)¶

Naming¶

2. Relationship to existing work¶

3. Track overview¶

4. U0 — Trust foundation¶

Deliverables (landed — do not fork semantics)¶

Acceptance¶

Key files¶

5. U1 — Analyse product UX (hardening Phase 6)¶

#7 — Product views¶

#8 — Status strip¶

#9 — OCR Advanced¶

Acceptance (U1 exit)¶

Key files¶

6. U2 — First-run & operability¶

U2.1 — Home (shipped; replaces the setup-wizard sketch)¶

U2.2 — Sample / demo notebook¶

U2.3 — Diagnostics in UI¶

U2.4 — Docs & install path¶

Acceptance (U2)¶

Key files¶

7. U3 — Daily workbench¶

U3.1 — Review as a work queue¶

U3.2 — Reading mode¶

U3.3 — Search & Library deepening (FTS, not corpus index)¶

U3.4 — Notebook organisation polish¶

U3.5 — Model & runtime management (product abstraction)¶

Acceptance (U3)¶

Key files¶

8. U4 — Corpus UX¶

Hard gate (satisfied)¶

Product UX (polish continuing)¶

Acceptance (U4)¶

Key files¶

9. Parallel tracks (coordination only)¶

10. Wave exit gates¶

Hardening close (U0 + U1)¶

Usability-wave close (U0–U3; U4 polish separately)¶

11. Documentation updates required as tracks land¶

12. Implementation checklist (track-level)¶

U0¶

U1¶

U2¶

U3¶

U4¶

13. Success metrics (qualitative)¶