Manual acceptance suite (1.0) — maintainer runbook

Status: executable kit for a 1.0 freeze pass
Related: release_severity_triage.md, install_verification_matrix.md, first_notebook.md, known_limitations.md

Authoritative maintainer acceptance checklist for the notebook workbench. Automated pytest is complementary, not a substitute. 0.9.0 still keys off U2 + I6; this runbook joins the 1.0 checklist in release_governance.md.

Offline steps are written so CI / # light-test can cover them. Live OCR is a human / # deep-test step and is skipped when Ollama is down — never a silent pass.

0. Prerequisites

Check

Criterion

Candidate identity

Record package version + exact git SHA

Clean worktree intent

Prefer a tagged/candidate commit; note dirty files

Disposable data root

Do not contaminate a production projects dir

Install profile

Docker Compose (recommended) and/or native as claimed

Streamlit

Record streamlit.__version__ for the profile under test

1. Journey classification

Class

Rule

required

Must pass for this profile, or 1.0 is blocked

conditional

Required when the profile claims the capability (live OCR, native GUI)

optional

Strongly expected when practical; skip needs reason + severity

Skipping a required journey needs: skip rationale, severity, and evidence.

2. Ordered journeys

2.1 Installation and launch — required

  • Install / launch UI per chosen profile on port 8510 (never 8501).

  • Home loads without traceback.

Offline: python -c "import transcribe; print(transcribe.__version__)" plus make test-smoke on the SHA. Live UI: Docker or ./transcribe.sh ui.

2.2 Import or Open sample — required

  • Offline: New notebook → Open sample, or import tests/fixtures/mini_page.png with the fake VisionOCRProvider.

  • Library / notebook list shows the new notebook.

Do not require live Ollama for this journey.

2.3 Transcribe or pre-seeded text — required (one of)

Path

When

Class

Pre-seeded edited_text (sample notebook)

Always available offline

required

Fake vision provider on mini_page.png

Default suite / light-test

required (offline)

Live Ollama vision OCR

Human / deep-test

conditional — skip if daemon or vision tag is missing

Live OCR skip is skipped (Ollama down), not a pass.

2.4 Review correction survives — required (offline)

  • Edit a page’s edited_text in Review.

  • Re-run OCR (fake or live) and confirm the human edit is still the published text.

  • Contract: notebook identity, original scans, and human edits survive re-OCR.

Covered in the default suite; record the pytest node id when using tests as evidence.

2.5 Analyse Quick — required (offline)

  • Run Analyse Quick (no text LLM, no heavy modules) on the sample or mini notebook.

  • Overview opens without crash. Missing optional extras (bertopic) stay unavailable_extra, not a silent substitute.

2.6 Export — required (offline)

  • Export Markdown (or HTML) of the notebook.

  • Ignored pages stay omitted from reading formats when the export toggle is on. Reading hides the same pages unless Show ignored pages is on.

2.7 Backup verify — required (offline)

  • transcribe backup create then transcribe backup verify <archive.zip>.

  • Schema bumps that Transcribe cannot load refuse with a clear message; recover via backup (backup_and_restore.md).

2.8 Failure recovery — required (at least two cases)

Case

Expected

Severity if broken

Missing Ollama when a vision/text module is selected

Clear message; no silent hang

must-fix

Fake provider / mini_page import of a missing path

Rejected; no corrupt index

must-fix / blocker

Optional BERTopic extra absent

unavailable_extra; pipeline continues

must-fix

Cancelled OCR job

Cancel acknowledged; no corrupt half-commit

must-fix

Exercise ≥2 cases. Offline suite already covers several; live missing-Ollama is conditional.

3. Environments

Env

Notes

Docker Compose (recommended)

Port 8510, loopback bind, host Ollama

Native (if claiming support)

./transcribe.sh; same port

4. Evidence table

Copy one row per journey:

Field

Value

environment

Docker / native

package version

SHA

date

journey id

e.g. 2.3 live OCR

class

required / conditional / optional

outcome

pass / fail / skip

skip rationale

required if skip

severity

blocker / must-fix / known limitation / post-1.0 / —

evidence link

pytest node id, log path, or ticket