Update job detail page to track revisions and display document image next to transcription text.

.dockerignore

@@ -0,0 +1,13 @@
+.git
+.gitignore
+.vscode
+.venv
+.pytest_cache
+.ruff_cache
+__pycache__/
+*.py[cod]
+*.db
+.env
+tests/
+docs/
+uploads/

.env.example

@@ -0,0 +1,8 @@
+PROVIDER=openrouter
+OPENROUTER_API_KEY=sk-or-...
+# PROVIDER_MODEL=          # optional: OpenRouter adapter supplies default
+# OPENROUTER_HTTP_REFERER=https://example.com
+# OPENROUTER_APP_TITLE=Historical Transcription MVP
+# DATABASE_URL=sqlite:///./transcription.db
+# UPLOAD_DIR=./uploads
+# PROMPT_DIR=./prompts

.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

.github/instructions/services.instructions.md

@@ -0,0 +1,77 @@
+---
+description: Follow these guidelines when editing the services
+applyTo: 'src/transcription/services/*.py'
+---
+
+# Services
+
+## Structure
+
+- Project core data models defined in [models](../../src/transcription/models.py)
+- 1 service class per data model
+- Only services directly interact with the database, and only through async methods
+- Services are completely independent of one another. Any operation that needs to use more than a single service, which is most of them, needs to have a separate orchestration function.
+
+## Error Handling
+
+- Service-specific errors defined at the top of the respective module and inherit from `AppError`
+- Use a context manager for large `try/except` blocks like in [transcription](../../src/transcription/services/transcription.py)
+
+## Checklist
+
+- [ ] Uses `ServiceBase` for common logic
+- [ ] CRUD methods created at the top
+- [ ] Session kwarg for `AsyncSession` to pass in a session object to each method
+- [ ] Services use `self._session_scope` in their methods to pass the session thru.
+    - Multiple operations on the same object(s) require sharing a session between all the methods used.
+
+## CRUD Methods
+
+- Create, read, update, and delete, created in that order
+- Name format `<operation>_<model >`, for example `create_document` or `update_job`
+- All services must define these 4 methods first, and in that order
+
+## Transaction Finalization
+
+When a service method accepts an optional `session` kwarg, write methods must use `self._finalize` to finalize the transaction properly according to whether or not they are sharing a session.
+
+- If `session` is `None`: the method owns the transaction and should `commit()`.
+- If `session` is provided: the method must **not** commit; it should `flush()` so IDs and FK values are available to the caller's transaction.
+- Use `refresh()` on returned ORM objects when the caller needs DB-populated values (defaults, triggers, merged state).
+
+Recommended helper behavior:
+
+- Inputs: active session object, original `session` arg (or a boolean ownership flag), and an optional list of objects to refresh.
+- Logic: `commit` when service-owned session, `flush` when caller-owned session, then refresh requested objects.
+
+This keeps orchestration functions atomic: they can pass one shared session across multiple services and commit exactly once at the workflow boundary.
+
+## Workflow Transaction Boundaries
+
+For multi-step job lifecycles (for example queued transcription jobs), orchestration functions must use explicit transaction phases.
+
+Required boundary model:
+
+- **Transaction A (claim):** transition `JobStatus.QUEUED -> JobStatus.PROCESSING` and commit immediately.
+- Perform provider/network work **outside** database transactions.
+- **Transaction B (terminal success):** write transcript content and set `JobStatus.TRANSCRIBED` in the same shared-session commit.
+- **Transaction B (terminal failure):** write transcript error detail and set `JobStatus.FAILED` in the same shared-session commit.
+- **Transaction C (retry path):** write transcript error detail, increment retry count, and set `JobStatus.QUEUED` in one shared-session commit.
+
+Atomicity rules:
+
+- Never commit transcript updates separately from the paired terminal/retry job status change.
+- Terminal state (`TRANSCRIBED` or `FAILED`) and transcript row changes must succeed or roll back together.
+- Retry persistence (`QUEUED` + retry increment + error detail) must succeed or roll back together.
+
+Separation of concerns:
+
+- Worker modules should stay lightweight and delegate lifecycle transitions to service/workflow orchestration functions.
+- In `workflows.py`, `process_queued_job` should own one complete attempt lifecycle: `QUEUED -> PROCESSING -> TRANSCRIBED|FAILED`.
+- In `workflows.py`, `advance_job` should coordinate broader status progression around attempts (for example retry scheduling from `FAILED -> QUEUED`).
+- Services should expose session-aware write helpers (flush on caller-owned session) so orchestration controls commit boundaries.
+- Backoff/sleep behavior must run outside transactional scopes.
+
+# Service Composition
+
+Some operations, like uploading a picutre, require modifications to multiple tables, which can be done by composing methods from the service object into a separate function.

.gitignore

@@ -8,3 +8,9 @@ wheels/
 
 # Virtual environments
 .venv
+
+# Environment secrets
+.env
+
+# SQLite database
+*.db

.vscode/launch.json

@@ -0,0 +1,27 @@
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Python: Debug transcription app",
+            "type": "debugpy",
+            "request": "launch",
+            "module": "debugpy",
+            "args": [
+                "-m",
+                "uvicorn",
+                "transcription.app:create_app",
+                "--factory",
+                "--host",
+                // "127.0.0.1",
+                "0.0.0.0",
+                "--port",
+                "8080"
+            ],
+            "justMyCode": true,
+            "console": "integratedTerminal",
+            "env": {
+                "PYTHONPATH": "${workspaceFolder}/src"
+            }
+        }
+    ]
+}

Dockerfile

@@ -0,0 +1,47 @@
+FROM python:3.12-slim AS builder
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    UV_LINK_MODE=copy
+
+WORKDIR /app
+
+COPY --from=ghcr.io/astral-sh/uv:0.5.24 /uv /uvx /bin/
+
+COPY pyproject.toml uv.lock README.md ./
+RUN uv sync --frozen --no-dev --no-install-project
+
+COPY src ./src
+COPY prompts ./prompts
+RUN uv sync --frozen --no-dev
+
+
+FROM python:3.12-slim AS runtime
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PATH="/app/.venv/bin:$PATH" \
+    PYTHONPATH="/app/src" \
+    UPLOAD_DIR="/app/uploads" \
+    PROMPT_DIR="/app/prompts"
+
+WORKDIR /app
+
+RUN groupadd --system --gid 1001 appgroup \
+    && useradd --system --uid 1001 --gid appgroup --create-home appuser
+
+COPY --from=builder /app/.venv /app/.venv
+COPY --from=builder /app/src /app/src
+COPY --from=builder /app/prompts /app/prompts
+
+RUN mkdir -p /app/uploads /app/data \
+    && chown -R appuser:appgroup /app
+
+USER appuser
+
+EXPOSE 8000
+
+HEALTHCHECK --interval=30s --timeout=3s --start-period=3s --retries=3 \
+    CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/healthz')"
+
+CMD ["uvicorn", "transcription.app:create_app", "--factory", "--host", "0.0.0.0", "--port", "8000", "--proxy-headers"]

README.md

@@ -0,0 +1,76 @@
+# Transcription
+
+Historical document transcription system for family-history documents.
+
+The app lets you upload a document image/PDF, queues a background transcription job, and then shows job status and results in a web UI.
+
+## What the app does
+
+- Upload document files (`.jpg`, `.jpeg`, `.png`, `.tif`, `.tiff`, `.pdf`)
+- Persist document + job records in SQLite
+- Process jobs in a background worker (`queued -> processing -> transcribed/failed`)
+- Store transcript text (or failure detail)
+- Track transcript revisions (AI-generated and manual updates)
+- Show status and results in the NiceGUI interface
+
+## Quick start
+
+### 1) Install dependencies
+
+```bash
+uv sync
+```
+
+### 2) Configure environment
+
+Create a `.env` file in the project root (minimum required setting shown):
+
+```env
+OPENROUTER_API_KEY=your_openrouter_api_key
+```
+
+Optional settings (defaults shown):
+
+```env
+DATABASE_URL=sqlite:///./transcription.db
+UPLOAD_DIR=./uploads
+PROMPT_DIR=./prompts
+```
+
+### 3) Run the app
+
+```bash
+uv run uvicorn transcription.app:create_app --factory --reload
+```
+
+### 4) Open in browser
+
+- GUI: [http://[IP_ADDRESS]:8000/ui](http://[IP_ADDRESS]:8000/ui)
+- Health check: [http://[IP_ADDRESS]:8000/healthz](http://[IP_ADDRESS]:8000/healthz)
+
+## How to navigate the GUI
+
+- **Upload page** (`/ui`)
+  - Select a supported file to upload.
+  - The app creates a queued transcription job.
+  - Use the **View jobs** link to inspect progress.
+
+- **Jobs page** (`/ui/jobs`)
+  - See all jobs and their status.
+  - Use **Refresh** to reload current states.
+  - Open a specific job to see details.
+
+- **Job detail page** (`/ui/jobs/{job_id}`)
+  - Shows job metadata and status.
+  - Shows transcript metadata, including provider and model.
+  - Shows a version table with `Created` and `Version`.
+  - Displays latest version text in an editable textbox.
+  - **Update** creates a new transcript version.
+  - Displays failure detail for failed revisions.
+
+## Prompt artifacts
+
+Prompt files are stored in `prompts/` and loaded from `PROMPT_DIR` (default: `./prompts`).
+
+The canonical MVP prompt is:
+- `prompts/transcribe_document.md`

docker-compose.yml

@@ -0,0 +1,21 @@
+services:
+  transcription:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    container_name: transcription-app
+    env_file:
+      - .env
+    environment:
+      DATABASE_URL: sqlite:////app/data/transcription.db
+      UPLOAD_DIR: /app/uploads
+      PROMPT_DIR: /app/prompts
+    ports:
+      - "8002:8000"
+    volumes:
+      - ./uploads:/app/uploads
+      - transcription_data:/app/data
+    restart: unless-stopped
+
+volumes:
+  transcription_data:

docs/Intent.md

@@ -0,0 +1,40 @@
+# Historical Document Transcription
+I have several thousand pages of family history told through letters, postcards, books, and other documents that I want to transcribe to text. 
+
+## Goals
+1. Preserve our family history
+2. Unburden my family (and descendants) from having to store and care for the physical media. Once the documents have been transcribed and organized, they can be donated (or kept by a family member that wants to retain them).
+3. Make the text easily available and searchable by family members, as well as AI (which may have different requirements).
+4. Ability create timelines or assemble the historical record of the family or specific individuals from across the complete document archive. Perhaps use AI to create the timelines in a more narrative form.
+
+## Source material
+1. **letters, cards, diaries** - handwritten; mostly stored in tubs, with little organization
+2. **books** - typed or typeset; mostly self-published books 50-100 pages in length. This may be expanded to include selected pages from other publications.
+3. **newspaper clippings, event programs, invitations, and other ephemera**
+
+ ## Methodology
+### Verbatim vs. Clean Copy
+Transcriptions should be Verbatim and follow scholarly research guidelines, with no modifications to the original text.
+
+### Prompt Curation Policy
+Transcription behavior should be implemented with prompt assets that are human-maintainable over time.
+
+1. Each transcription prompt is stored as an individual Markdown file.
+2. Prompt files are refined iteratively as document quality and edge cases are discovered.
+3. Prompt changes should be scoped to one prompt file at a time whenever possible to keep review history clear.
+
+### Potential Document Issues
+| Document Issue | How to Handle It | Example |
+| :--- | :--- | :--- |
+| **Misspellings & Errors** | Retain original spelling and insert italicized `[sic]` directly after the error. | `The weather was very cold and publick [sic] business delayed.` |
+| **Missing Words / Slips** | Insert the missing word inside square brackets to restore basic readability. | `We went [to] the store to buy supplies.` |
+| **Uncertain / Guesswork** | Place your best hypothesis followed by a question mark inside square brackets. | `He went to [Boston?] yesterday to meet the governor.` |
+| **Completely Illegible** | Use a clear descriptive term like `[illegible]` or specify the reason (e.g., `[torn]`, `[ink blot]`). | `The total cost was [illegible] dollars.` or `The letter ends here [remainder of page torn].` |
+| **Crossed-out Text** | Wrap the removed word or phrase in a deleted tag to preserve the author's edits. | `We left at [deleted: noon] one o'clock instead.` |
+| **Squeezed-in Text** | Wrap text that was added above the line or in a tight space in an inserted tag. | `The [inserted: red] house on the hill was abandoned.` |
+| **Superscripts & Abbreviations** | Bring raised letters down to the main line, or optionally expand them in brackets. | `Change Gen^l to Genl` OR `Change to Gen[era]l depending on project preference.` |
+| **Images / Seals / Signs** | Describe the non-textual element using italicized text inside square brackets. | `[wax notary seal attached here]` or `[sketch of a fort layout]` |
+| **Marginalia / Notes** | Note the spatial transition clearly before transcribing the note itself. | `[written in left margin:] Do not share this with anyone.` |
+| **Line Breaks / Hyphens** | Rejoin words split across a page margin silently, dropping the line-break hyphen. | `Original: "estab- / lishment" becomes "establishment"` |
+| **Ambiguous Capitalization** | Default to modern capitalization rules unless an archaic uppercase letter is clearly intentional. | `If a standard noun like 'Farm' looks randomly capitalized, type 'farm'.` |
+**Hierarchical Outlines** | Preserve exact numbering characters (including lowercase Roman numerals or terminal 'j'). Replicate indentation levels using spaces/tabs. Do not correct math or sequence errors silently. | `I. Main Topic`<br>`&nbsp;&nbsp;a. Sub-point`<br>`&nbsp;&nbsp;b. Next point`<br>`III. [sic] Third Topic` |

docs/architecture.md

@@ -0,0 +1,294 @@
+# Architecture
+
+This document describes the production architecture of the personal historical-document transcription system. The system is intentionally optimized for single-user operation, low operational overhead, and clean internal boundaries that support future growth without rewrites.
+
+## Architecture Objectives
+
+The production architecture is designed to:
+
+- preserve verbatim family-history source material as searchable text
+- keep operational complexity low for a personal deployment
+- support asynchronous transcription without requiring distributed infrastructure
+- maintain clear module boundaries so extensions can be added incrementally
+
+## Production Scope And Scale
+
+The deployed system targets personal use and a corpus of several thousand documents processed over time. The architecture favors simple, composable building blocks over distributed orchestration.
+
+Current scope includes:
+
+- document upload and metadata capture
+- asynchronous transcription jobs
+- prompt-library driven transcription behavior, with one Markdown file per prompt
+- transcript review and revision history
+- full-text search over accepted transcripts
+- export of transcript data
+
+## Deployment Topology
+
+The production deployment uses [Docker Compose](https://docs.docker.com/compose/) and treats containerized databases as extremely lightweight operational dependencies.
+
+Running [PostgreSQL](https://www.postgresql.org/docs/) in its own container is considered simple by default for this system.
+
+Running [MongoDB](https://www.mongodb.com/docs/) in its own container is also considered simple when document-centric storage is enabled.
+
+Container count is not a hard architectural limit; a three-container deployment (app, PostgreSQL, MongoDB) is an acceptable baseline.
+
+### Baseline Topology (Two Containers)
+
+- one application container
+- one PostgreSQL container
+- embedded background worker execution inside the app process
+
+### Expanded Topology (Three Containers)
+
+- application container
+- PostgreSQL container
+- MongoDB container
+
+No additional queue, scheduler, or search-engine containers are required in the baseline production setup.
+
+## Runtime Architecture
+
+```mermaid
+flowchart LR
+    User[Browser User] --> App[FastAPI + NiceGUI Service]
+    App --> Worker[In-process Background Worker]
+    App --> PG[(PostgreSQL)]
+    App --> MG[(MongoDB Document Store)]
+    Worker --> AI[Transcription Provider]
+    Worker --> PG
+    Worker --> MG
+```
+
+## Runtime Ownership And Startup Policy (V1 Step 1)
+
+The current implementation now uses explicit lifespan-owned runtime resources.
+
+- application lifespan initializes and disposes database runtime resources
+- worker lifecycle is owned by application lifespan startup/shutdown
+- worker receives lifespan-owned database engine dependency explicitly
+- schema bootstrap policy is environment-aware and explicit:
+  - development/test default to bootstrap enabled
+  - production defaults to bootstrap disabled
+  - explicit override is available via configuration
+
+This aligns implementation toward REQ-7 and REQ-10 while preserving personal-scale operational simplicity.
+
+## Layered Module Structure
+
+### Interface Layer
+
+Responsibility:
+
+- HTTP API and UI routes
+- request/response validation
+- status and result presentation
+
+Out of scope:
+
+- business-rule enforcement
+- data-access implementation
+
+### Application Layer
+
+Responsibility:
+
+- upload and job orchestration
+- state transitions and retry policy
+- coordination across domain and infrastructure ports
+
+Out of scope:
+
+- provider-specific protocol details
+- ORM or storage-specific logic
+
+### Domain Layer
+
+Responsibility:
+
+- verbatim transcription policy
+- revision and provenance invariants
+- confidence and annotation semantics
+
+Out of scope:
+
+- web framework concerns
+- database and network I/O
+
+### Infrastructure Layer
+
+Responsibility:
+
+- persistence adapters (PostgreSQL and MongoDB)
+- transcription-provider adapter
+
+Out of scope:
+
+- business policy decisions
+
+## Processing Workflow
+
+Production transcription flow:
+
+1. A user uploads an image or PDF through the UI or API.
+2. The application validates payloads and creates document and job records.
+3. The in-process worker dequeues the job and calls the transcription provider.
+4. The application persists transcript output, confidence metadata, and provenance events.
+5. Job status transitions from queued to processing to transcribed or failed.
+6. The UI and API expose status, revision history, and searchable transcript text.
+
+## Data Model Ownership
+
+System-of-record entities:
+
+- documents and pages
+- transcription jobs and status events
+- transcript revisions
+- provenance metadata
+
+Storage strategy:
+
+- PostgreSQL for relational system-of-record entities
+- MongoDB for document-oriented payloads and large transcription artifacts
+- versioned prompt artifacts stored as individual Markdown files for human editing and refinement
+- in-memory execution state treated as ephemeral
+
+## Transcription Prompt Asset Policy
+
+The production system treats transcription prompts as maintainable content assets.
+
+- each transcription prompt is stored in its own Markdown file
+- prompt files are designed for direct human editing and iterative refinement
+- prompt updates are independent and do not require bundling unrelated prompt changes
+- prompt file identity and revision history are tracked through normal repository version control
+
+## Simplicity Guardrails
+
+The production system enforces these constraints to prevent accidental over-engineering:
+
+- PostgreSQL in a container is treated as a lightweight default dependency
+- MongoDB in a container is treated as a lightweight optional dependency
+- three containers (app, PostgreSQL, MongoDB) is an acceptable simple deployment
+- no dedicated queue or search cluster is introduced without measured need
+- external infrastructure is added only behind existing ports/adapters
+
+## Extension Path
+
+The architecture supports additive growth without changing domain contracts.
+
+### Stage 1: Foundation (Current)
+
+- upload, transcription, review, search, export
+- in-process worker execution
+- single provider adapter
+- app plus PostgreSQL deployment
+
+### Stage 2: Throughput Hardening
+
+- optional MongoDB document-store enablement
+- optional external worker/queue process
+- stronger retry and dead-letter handling
+
+### Stage 3: Intelligence Features
+
+- entity extraction and cross-document linking
+- timeline and narrative assembly
+- optional multi-provider routing
+
+Each stage preserves existing module boundaries and keeps migration risk low.
+
+## Test Strategy
+
+The test strategy is aligned to personal-scale operation with fast, deterministic feedback.
+
+### Unit Tests
+
+- domain transcription rules and annotation behavior
+- revision-history invariants
+- job state-transition logic
+
+### Integration Tests
+
+- repository behavior and transaction boundaries
+- persistence-adapter and provider adapter contract mapping
+- upload-to-persistence roundtrip
+
+### End-to-End Tests
+
+- happy path: upload, transcribe, review, search, export
+- failure path: provider error, retry, surfaced failed status
+
+### CI Execution Model
+
+- fast suite on each push
+- optional slower provider-sandbox checks on scheduled runs
+
+## Risks And Controls
+
+### Runtime Responsiveness
+
+Risk:
+
+- long jobs can reduce responsiveness in a single-process deployment
+
+Control:
+
+- bounded concurrency and visible job status in the UI
+
+### Database Concurrency Limits
+
+Risk:
+
+- contention can appear under sustained concurrent writes in personal-scale infrastructure
+
+Control:
+
+- tuned connection pooling and phased use of MongoDB for document-heavy workloads
+
+### Provider Output Variance
+
+Risk:
+
+- transcription quality varies by document type, handwriting legibility, and image quality
+
+Control:
+
+- first-class human review and immutable revision history
+
+## Technology References
+
+- [FastAPI documentation](https://fastapi.tiangolo.com/)
+- [NiceGUI documentation](https://nicegui.io/documentation)
+- [Docker Compose documentation](https://docs.docker.com/compose/)
+- [PostgreSQL documentation](https://www.postgresql.org/docs/)
+- [MongoDB documentation](https://www.mongodb.com/docs/)
+
+## Related Pages
+
+- [System overview](index.md)
+- [Version 1 plan](ver1/ver1.md)
+- [Version 1 Step 1 plan](ver1/ver1-step1.md)
+- [Version 1 Step 1 results](ver1/ver1-step1-results.md)
+- [Architecture decision records index](adr/README.md)
+
+## Glossary
+
+- Adapter: A component that translates between internal interfaces and external systems such as databases or AI services.
+- Background job: Work executed outside the request/response path so the UI remains responsive.
+- Boundary: A strict separation between modules with different responsibilities.
+- CI (Continuous Integration): Automated test execution for code changes.
+- Contract test: A test that verifies an adapter follows expected input/output behavior at a boundary.
+- Domain layer: The module that contains core business rules and invariants.
+- End-to-end test: A test that validates a full user flow across the running system.
+- Full-text search: Text indexing and querying optimized for natural-language search.
+- In-process worker: A background executor that runs within the same application process.
+- Integration test: A test that verifies interactions between real modules and infrastructure components.
+- MongoDB: A document-oriented database used for flexible, high-variance data structures.
+- Modular monolith: A single deployable application with strongly separated internal modules.
+- Port/Interface: A stable contract used by application/domain code to call infrastructure implementations.
+- Prompt artifact: A single Markdown file that defines one transcription prompt and can be revised independently.
+- Provenance: Metadata that records where generated data came from and how it was produced.
+- Revision history: Versioned record of transcript edits over time.
+- System of record: The authoritative persistent store for canonical data.
+- Vertical slice: A minimal end-to-end feature path spanning UI/API, application logic, and persistence.

docs/error_handling.md

@@ -0,0 +1,282 @@
+# Error Handling
+
+This document defines the canonical error-handling policy for the document transcription system. It is the single source of truth for how errors are classified, surfaced to users, logged for diagnosis, and handled across UI, API, service, worker, and provider boundaries.
+
+## Error Handling Objectives
+
+The production error-handling model is designed to:
+
+- make failures visible to the user in clear, actionable language
+- preserve enough diagnostic detail for fast troubleshooting
+- keep module behavior consistent across all boundaries
+- distinguish expected domain failures from unexpected defects
+- support safe retries for transient failures without hiding persistent faults
+
+## Scope And Authority
+
+This page governs error-handling behavior for:
+
+- UI interactions (NiceGUI pages)
+- API endpoints (FastAPI routes)
+- application services and orchestration logic
+- in-process background worker execution
+- external provider adapters and persistence adapters
+
+If implementation behavior conflicts with this document, this document is authoritative and implementation should be updated.
+
+## Core Principles
+
+- **Clarity first:** user-facing messages should explain what failed in plain language.
+- **Actionability required:** each surfaced error should include a suggested next step.
+- **Safety by default:** internal details are logged; sensitive details are not exposed by default in UI/API.
+- **Consistency across boundaries:** category and structure should remain stable from source to surface.
+- **Fail explicitly:** silent failure is prohibited.
+- **Traceability:** every non-trivial error should be traceable with an error reference ID.
+
+## Error Taxonomy
+
+The system uses stable, implementation-independent categories:
+
+| Category | Definition | Typical Source | Retriable |
+| --- | --- | --- | --- |
+| `validation_error` | Payload or parameter shape/content is invalid | UI/API input validation, service guards | no |
+| `user_input_error` | User-provided artifact is unacceptable though structurally valid | unsupported file type, empty file, oversized upload | sometimes |
+| `not_found_error` | Requested resource does not exist | missing job/document/transcript | no |
+| `conflict_error` | Requested operation violates current state constraints | invalid state transition | no |
+| `external_provider_error` | External AI/provider call fails | upstream HTTP/API/provider failures | sometimes |
+| `infrastructure_transient_error` | Temporary environment issue | network timeout, DB connection reset | yes |
+| `infrastructure_persistent_error` | Non-transient environment issue | missing permissions, misconfiguration | no |
+| `internal_unexpected_error` | Unhandled defect or unknown failure | uncaught exceptions, logic errors | unknown (default no) |
+
+### Classification Rules
+
+- Classification occurs as close as possible to the origin boundary.
+- Provider-specific exceptions must be normalized into taxonomy categories before crossing service boundaries.
+- Unknown exceptions are classified as `internal_unexpected_error` and logged with traceback.
+- Category names are stable contracts and must not be changed casually.
+
+## User-Facing Error Experience Contract
+
+When an error is shown in the GUI, it must include:
+
+1. **Title** (short context, e.g., “Upload failed”)
+2. **Message** (plain-language explanation)
+3. **Suggested action** (explicit next step)
+4. **Error reference ID** (for support/debug traceability)
+5. **Technical details** (optional/collapsible for advanced users)
+
+### UI Message Rules
+
+- Do not expose raw stack traces by default.
+- Do not expose secrets, credentials, connection strings, or filesystem internals unless explicitly in debug tooling.
+- Prefer domain language over implementation language.
+- Use persistent visibility for important failures (dialog/card), not only transient toasts.
+
+### Suggested Action Requirements
+
+Every user-visible error must include a suggested course of action, such as:
+
+- retry the operation
+- check file type/size constraints
+- refresh the jobs page
+- verify environment configuration
+- contact operator with error ID and timestamp
+
+## API Error Response Contract
+
+API errors should return a structured envelope with stable fields:
+
+- `error_id`: short unique reference ID
+- `category`: taxonomy category
+- `message`: safe human-readable summary
+- `suggestion`: recommended next step
+- `details`: optional, only when safe and appropriate
+- `timestamp`: UTC ISO-8601
+
+HTTP status mapping guidance:
+
+- `validation_error`, `user_input_error` -> `400`
+- `not_found_error` -> `404`
+- `conflict_error` -> `409`
+- `external_provider_error` -> `502` or `503` (depending on failure mode)
+- `infrastructure_transient_error` -> `503`
+- `infrastructure_persistent_error` -> `500`
+- `internal_unexpected_error` -> `500`
+
+## Logging And Observability Contract
+
+All logged errors must include, where available:
+
+- `error_id`
+- `category`
+- `operation` (e.g., `upload.submit`, `worker.process_job`, `jobs.refresh`)
+- `exception_type`
+- `job_id`, `document_id` (when relevant)
+- UTC timestamp
+
+Rules:
+
+- Use structured logging fields where practical.
+- Use full traceback for unexpected errors (`internal_unexpected_error`).
+- Log at boundary handoff points to preserve causal trail.
+- Avoid duplicate noisy logging for the same exception at every layer.
+
+## Recovery And Retry Policy
+
+### Retriable Conditions
+
+Retriable failures include:
+
+- transient network/provider timeouts
+- intermittent provider unavailability
+- temporary DB/network interruptions
+
+### Non-Retriable Conditions
+
+Non-retriable failures include:
+
+- invalid file formats
+- missing required data
+- permission/configuration failures
+- deterministic domain conflicts
+
+### Worker Behavior
+
+- The worker must classify and persist failure details consistently.
+- Retries should be bounded by configured limits.
+- Exhausted retries must end in explicit failed status with recorded reason.
+- No infinite retry loops are allowed.
+
+## Boundary-Specific Responsibilities
+
+### UI Layer
+
+Responsibility:
+
+- display user-safe error summaries and suggested actions
+- show persistent error visibility for critical failures
+- include error reference IDs in visible output
+
+Out of scope:
+
+- low-level exception parsing
+- provider-specific protocol interpretation
+
+### API Layer
+
+Responsibility:
+
+- map application exceptions into stable error envelopes and HTTP statuses
+- preserve category and error_id continuity
+
+Out of scope:
+
+- domain-specific remediation logic
+
+### Service Layer
+
+Responsibility:
+
+- classify domain and infrastructure exceptions
+- convert adapter-specific failures into taxonomy categories
+- return deterministic error types to callers
+
+Out of scope:
+
+- presentation formatting for UI
+
+### Worker Layer
+
+Responsibility:
+
+- execute retry policy for retriable failures
+- persist terminal failure details for jobs
+- emit operational logs with category and identifiers
+
+Out of scope:
+
+- direct UI messaging
+
+### Provider Adapter Layer
+
+Responsibility:
+
+- normalize provider SDK/HTTP failures into domain-neutral exceptions
+- preserve raw provider context for logs (safely)
+
+Out of scope:
+
+- choosing user-facing wording
+
+## Error Lifecycle Workflow
+
+Standard lifecycle:
+
+1. Failure occurs at a boundary or operation.
+2. Exception is classified into taxonomy category.
+3. `error_id` is created (or propagated).
+4. Error is logged with required structured fields.
+5. User/API receives safe message + suggested action.
+6. Persistent job/resource state is updated when applicable.
+7. Tests verify contract behavior for the pathway.
+
+## Test Strategy For Error Handling
+
+### Unit Tests
+
+- category classification behavior
+- retry eligibility decisions
+- exception-to-message mapping safety
+
+### Integration Tests
+
+- UI pathways show clear message + suggested action for known failures
+- API returns structured error envelope with expected status/category
+- worker persists failed status and failure detail as required
+
+### Regression Tests
+
+- each previously observed production issue should have a guarding test
+- contract tests must cover adapter error normalization behavior
+
+## Known Failure Patterns And Prescribed Responses
+
+| Pattern | Category | User Message | Suggested Action |
+| --- | --- | --- | --- |
+| Upload payload cannot be parsed by UI handler | `internal_unexpected_error` (until narrowed) | Upload failed due to unexpected processing error | Retry once; if repeated, report error ID and check runtime version compatibility |
+| Unsupported extension | `user_input_error` | File type is not supported | Upload JPG, PNG, TIFF, or PDF |
+| Empty file upload | `validation_error` | Uploaded file is empty | Choose a valid non-empty file and retry |
+| Provider timeout | `external_provider_error` or `infrastructure_transient_error` | Transcription provider timed out | Retry from jobs page; if repeated, check provider status |
+| Job lookup missing | `not_found_error` | Requested job was not found | Refresh jobs list and open a valid job |
+
+## Governance And Update Process
+
+This document is a living policy artifact.
+
+Update this document when:
+
+- new error categories are introduced
+- handling behavior changes at any boundary
+- a production incident reveals missing guidance
+- API/UI error contracts change
+
+Change requirements:
+
+- update this document and associated tests in the same change set
+- preserve taxonomy stability; if changed, document migration impact
+- record noteworthy policy changes in project release notes or changelog
+
+## Related Pages
+
+- [System overview](index.md)
+- [Architecture](architecture.md)
+- [Requirements](requirements.md)
+- [Intent](intent.md)
+
+## Glossary
+
+- Error category: Stable classification used to drive handling, messaging, and status mapping.
+- Error envelope: Structured API payload describing a failure.
+- Error reference ID: Short identifier used to correlate user-visible failure with logs.
+- Retriable error: Failure likely to succeed on a later attempt without code changes.
+- Terminal failure: Failure state after retries are exhausted or retry is not allowed.

docs/index.md

@@ -0,0 +1,57 @@
+## Document Transcription System
+
+This project is a production application for transcribing and preserving historical family documents. It is intentionally designed for personal-scale use, with a simplicity-first architecture that is easy to operate and easy to extend.
+
+## Start Here
+
+Read [architecture.md](architecture.md) first.
+
+Then review [ver1/ver1.md](ver1/ver1.md) for completion scope and [ver1/ver1-step1-results.md](ver1/ver1-step1-results.md) for current architecture-consolidation status.
+
+The architecture page is the primary technical reference and defines:
+
+- deployed topology and infrastructure limits
+- module boundaries and dependency flow
+- processing life cycle and data ownership
+- test strategy, risk controls, and extension path
+
+## What The Application Does
+
+At a high level, users upload images of handwritten, typed, or typeset documents, run asynchronous transcription jobs, review and edit transcript revisions, and search across accepted text.
+
+Core capabilities:
+
+- document upload and metadata capture
+- asynchronous transcription with visible job status
+- transcription prompt management with one Markdown file per prompt for human refinement over time
+- revision history for transcript edits
+- full-text search over accepted transcripts
+- export of transcript data
+
+## Production Operating Model
+
+The system runs with minimal operational overhead:
+
+- PostgreSQL in a dedicated Docker container is considered extremely lightweight and simple for this system
+- MongoDB in a dedicated Docker container is also considered extremely lightweight and simple for document-centric persistence
+- a three-container deployment (app, PostgreSQL, MongoDB) is a simple and acceptable baseline
+- no required queue or search-engine containers in the baseline setup
+
+This operating model keeps deployment and maintenance simple while preserving clean boundaries for future scale.
+
+## Documentation Map
+
+- Architecture and technical design: [architecture.md](architecture.md)
+- Version 1 implementation plan: [ver1/ver1.md](ver1/ver1.md)
+- Version 1 Step 1 plan: [ver1/ver1-step1.md](ver1/ver1-step1.md)
+- Version 1 Step 1 results: [ver1/ver1-step1-results.md](ver1/ver1-step1-results.md)
+- Architecture decision records (ADR index): [adr/README.md](adr/README.md)
+- Runtime and deployment requirements: [requirements.md](requirements.md)
+- Error handling policy and operational guidance: [error_handling.md](error_handling.md)
+- Domain context and transcription policy: [intent.md](intent.md)
+
+## Glossary
+
+- Document-oriented persistence: Storing data as flexible records instead of fixed relational rows.
+- Prompt artifact: A single Markdown file that defines one transcription prompt and is edited independently.
+- System of record: The authoritative persistent store for canonical data.

docs/mvp/mvp-step1.md

@@ -0,0 +1,572 @@
+# Step 1 Implementation Plan: `config.py` + `models.py` + `db.py`
+
+## Purpose
+
+Establish the foundational data layer and configuration system that every subsequent MVP step builds on. At the end of this step, the project has a runnable Python package with a validated schema, typed configuration, and a test suite proving the data layer works — before any UI, worker, or AI provider code exists.
+
+---
+
+## 1. Prerequisite: Project Structure Scaffolding
+
+Before writing any logic, create the package skeleton so imports work correctly.
+
+### Files to create (empty `__init__.py` stubs)
+
+```
+src/
+└── transcription/
+    ├── __init__.py
+    ├── providers/
+    │   └── __init__.py
+    ├── services/
+    │   └── __init__.py
+    └── ui/
+        └── __init__.py
+```
+
+### Files to create (with logic — the Step 1 deliverables)
+
+```
+src/transcription/config.py
+src/transcription/models.py
+src/transcription/db.py
+```
+
+### Test files to create
+
+```
+tests/
+├── __init__.py
+├── conftest.py
+├── test_config.py
+├── test_models.py
+└── test_db.py
+```
+
+### Update `pyproject.toml`
+
+Add the dependencies that Step 1 requires and won't change later:
+
+```toml pyproject.toml
+[project]
+name = "transcription"
+version = "0.1.0"
+description = "Historical document transcription system"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "openrouter>=0.7.0",
+    "pydantic>=2.13.4",
+    "pydantic-settings>=2.9.1",
+    "sqlmodel>=0.0.25",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.25",
+]
+
+[tool.pytest.ini_options]
+addopts = "--strict-markers -q"
+markers = [
+    "unit: pure logic tests with no external dependencies",
+    "integration: tests that touch framework or database contracts",
+    "external: tests that call external services (slow, requires credentials)",
+]
+```
+
+Key additions:
+- **`openrouter`** — official OpenRouter Python SDK used for model calls
+- **`pydantic-settings`** — for `BaseSettings` with env-var loading (this was split out of `pydantic` core in v2)
+- **`sqlmodel`** — provides SQLModel (which bundles SQLAlchemy + Pydantic model integration) and the SQLite driver
+- **`pytest` + `pytest-asyncio`** — in `dev` extras for test execution
+- **`[tool.pytest.ini_options]`** — strict marker checking enabled from the start; markers registered upfront per pytesting skill conventions
+
+### Delete `hello.py`
+
+The placeholder file is no longer needed.
+
+---
+
+## 2. `config.py` — Centralized Configuration
+
+**Satisfies:** REQ-8 (centralized config and logging at startup)
+
+### Design Decisions
+
+| Decision | Rationale |
+|----------|-----------|
+| Use `pydantic-settings` `BaseSettings` | Type-safe, validates on construction, loads from env vars and `.env` files automatically |
+| `PROVIDER` constrained to `openrouter` for MVP | Keeps configuration explicit while avoiding premature multi-provider complexity |
+| `OPENROUTER_API_KEY` required | Matches official SDK docs and avoids ambiguous provider-agnostic naming |
+| `PROVIDER_MODEL` defaults to `None` | OpenRouter adapter (Step 3) supplies a sensible default when `None` |
+| `OPENROUTER_HTTP_REFERER` and `OPENROUTER_APP_TITLE` optional | Matches SDK optional app-attribution fields |
+| `DATABASE_URL` defaults to SQLite | Zero-setup local development; PostgreSQL swap is a single env-var change post-MVP |
+| `UPLOAD_DIR` and `PROMPT_DIR` as `Path` objects | Enables `.mkdir(parents=True, exist_ok=True)` and path validation at startup |
+| Logging configured via `logging.config.dictConfig` in `setup_logging()` | Centralized, explicit formatter/handler/root logger topology; called once at startup with `disable_existing_loggers=False` |
+
+### Proposed Implementation
+
+```python src/transcription/config.py
+"""Centralized application configuration.
+
+All settings are loaded from environment variables (or a .env file)
+once at startup. Provider-specific defaults (model names, base URLs)
+are resolved by the provider adapters, not here.
+"""
+
+from enum import StrEnum
+from functools import lru_cache
+from pathlib import Path
+import logging
+import logging.config
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Provider(StrEnum):
+    OPENROUTER = "openrouter"
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    # --- AI provider ---
+    provider: Provider = Provider.OPENROUTER
+    openrouter_api_key: str
+    provider_model: str | None = None
+    openrouter_http_referer: str | None = None
+    openrouter_app_title: str | None = None
+
+    # --- persistence ---
+    database_url: str = "sqlite:///./transcription.db"
+
+    # --- filesystem paths ---
+    upload_dir: Path = Path("./uploads")
+    prompt_dir: Path = Path("./prompts")
+
+
+LOGGING_CONFIG: dict[str, object] = {
+    "version": 1,
+    "disable_existing_loggers": False,
+    "formatters": {
+        "standard": {
+            "format": "%(asctime)s | %(levelname)-8s | %(name)s | %(message)s",
+            "datefmt": "%Y-%m-%d %H:%M:%S",
+        }
+    },
+    "handlers": {
+        "console": {
+            "class": "logging.StreamHandler",
+            "formatter": "standard",
+            "stream": "ext://sys.stdout",
+        }
+    },
+    "root": {
+        "level": "INFO",
+        "handlers": ["console"],
+    },
+}
+
+
+@lru_cache(maxsize=1)
+def get_settings() -> Settings:
+    """Return the singleton Settings instance.
+
+    Cached so the entire application shares one validated config.
+    """
+    return Settings()
+
+
+def setup_logging() -> None:
+    """Configure root logging once at startup."""
+    logging.config.dictConfig(LOGGING_CONFIG)
+```
+
+### Key Behaviors
+
+- **Startup validation**: If `OPENROUTER_API_KEY` is missing from the environment, `Settings()` raises a `ValidationError` immediately — the app won't start with a missing key.
+- **`.env` support**: Developers can create a `.env` file in the project root for local keys; it's never committed (already covered by the existing `.gitignore` pattern or a new entry).
+- **`extra="ignore"`**: Unknown env vars don't cause errors, keeping the config resilient to unrelated environment variables.
+- **`lru_cache`**: `get_settings()` is the single access point. All modules import and call this function rather than constructing `Settings` directly.
+- **Centralized logging**: `setup_logging()` calls `dictConfig` exactly once at startup; all modules should use `logging.getLogger(__name__)` and avoid `basicConfig`.
+
+### `.env` template (not committed — add to `.gitignore`)
+
+```bash .env.example
+PROVIDER=openrouter
+OPENROUTER_API_KEY=sk-or-...
+# PROVIDER_MODEL=          # optional: OpenRouter adapter supplies default
+# OPENROUTER_HTTP_REFERER=https://example.com
+# OPENROUTER_APP_TITLE=Historical Transcription MVP
+# DATABASE_URL=sqlite:///./transcription.db
+# UPLOAD_DIR=./uploads
+# PROMPT_DIR=./prompts
+```
+
+### `.gitignore` addition
+
+```gitignore .gitignore
+# ... existing entries ...
+
+# Environment secrets
+.env
+```
+
+---
+
+## 3. `models.py` — SQLModel Domain Models
+
+**Satisfies:** REQ-3 (persist and expose job states), REQ-4 (persist transcription output and failure details)
+
+### Design Decisions
+
+| Decision | Rationale |
+|----------|-----------|
+| Three models: `Document`, `Job`, `Transcript` | Minimal set from MVP Feature 5. One-to-many from Document→Job and one-to-one from Job→Transcript |
+| `JobStatus` as a `StrEnum` | Readable in the database (`"queued"` not `1`), type-safe in Python, trivially serializable to JSON for the UI |
+| Status values: `queued`, `processing`, `transcribed`, `failed` | Matches MVP Feature 2 lifecycle. REQ-3 also lists `upload` and `completed` — these are deferred to post-MVP when revision/review workflows exist |
+| UUIDs for primary keys | Avoids auto-increment collision concerns if we later move to PostgreSQL; safe for distributed ID generation; `uuid4` is simple |
+| `uploaded_at`, `created_at`, `updated_at` as UTC `datetime` | Timezone-naive UTC by convention for MVP. Sufficient for single-user, single-timezone operation |
+| `Transcript.text` is nullable | A failed job creates a Transcript with `text=None` and `error_detail` populated, keeping the query model uniform |
+| Relationships via SQLModel `Relationship` | Enables `document.jobs` and `job.transcript` navigation in service code without manual joins |
+
+### Proposed Implementation
+
+- `resource://skills/fastapi-async-sqlalchemy-modernization/document`
+
+```python src/transcription/models.py
+"""SQLModel domain models for the transcription system.
+
+Three models capture the MVP lifecycle:
+  Document  →  one-to-many  →  Job  →  one-to-one  →  Transcript
+"""
+
+from datetime import datetime, timezone
+from enum import StrEnum
+from uuid import UUID, uuid4
+
+from sqlmodel import Field, Relationship, SQLModel
+
+
+class JobStatus(StrEnum):
+    QUEUED = "queued"
+    PROCESSING = "processing"
+    TRANSCRIBED = "transcribed"
+    FAILED = "failed"
+
+
+class Document(SQLModel, table=True):
+    """An uploaded document image."""
+
+    id: UUID = Field(default_factory=uuid4, primary_key=True)
+    filename: str
+    file_path: str
+    uploaded_at: datetime = Field(
+        default_factory=lambda: datetime.now(timezone.utc),
+    )
+
+    # --- relationships ---
+    jobs: list["Job"] = Relationship(back_populates="document")
+
+
+class Job(SQLModel, table=True):
+    """A transcription job tied to a single document."""
+
+    id: UUID = Field(default_factory=uuid4, primary_key=True)
+    document_id: UUID = Field(foreign_key="document.id")
+    status: JobStatus = Field(default=JobStatus.QUEUED)
+    created_at: datetime = Field(
+        default_factory=lambda: datetime.now(timezone.utc),
+    )
+    updated_at: datetime = Field(
+        default_factory=lambda: datetime.now(timezone.utc),
+    )
+
+    # --- relationships ---
+    document: Document = Relationship(back_populates="jobs")
+    transcript: "Transcript | None" = Relationship(back_populates="job")
+
+
+class Transcript(SQLModel, table=True):
+    """The output of a transcription job."""
+
+    id: UUID = Field(default_factory=uuid4, primary_key=True)
+    job_id: UUID = Field(foreign_key="job.id", unique=True)
+    text: str | None = None
+    error_detail: str | None = None
+    created_at: datetime = Field(
+        default_factory=lambda: datetime.now(timezone.utc),
+    )
+
+    # --- relationships ---
+    job: Job = Relationship(back_populates="transcript")
+```
+
+### Entity-Relationship Summary
+
+```
+┌──────────┐       ┌──────────┐       ┌─────────────┐
+│ Document │ 1───* │   Job    │ 1───1 │ Transcript  │
+├──────────┤       ├──────────┤       ├─────────────┤
+│ id (PK)  │       │ id (PK)  │       │ id (PK)     │
+│ filename │       │ doc_id   │──FK──▶│ job_id (FK) │
+│ file_path│       │ status   │       │ text        │
+│ uploaded │       │ created  │       │ error_detail│
+│          │       │ updated  │       │ created     │
+└──────────┘       └──────────┘       └─────────────┘
+```
+
+### Why Only Four Status Values
+
+REQ-3 lists six states: `upload`, `queued`, `processing`, `transcribed`, `failed`, `completed`. The MVP simplifies this:
+
+| REQ-3 State | MVP Treatment |
+|-------------|---------------|
+| `upload` | Implicit — the Document record exists before a Job is created. No separate job state needed. |
+| `queued` | ✅ Included — job created, waiting for worker pickup |
+| `processing` | ✅ Included — worker is actively transcribing |
+| `transcribed` | ✅ Included — AI output received and stored |
+| `failed` | ✅ Included — error captured |
+| `completed` | Deferred — implies human review/acceptance. In MVP, `transcribed` is the terminal success state. |
+
+---
+
+## 4. `db.py` — Database Engine and Session Management
+
+**Satisfies:** MVP Feature 5 (SQLite auto-created on first startup)
+
+### Design Decisions
+
+| Decision | Rationale |
+|----------|-----------|
+| Module-level `create_engine` + `Session` factory | REQ-7 (lifespan-owned resources) is deferred. A module-level engine is adequate for MVP's single-process, single-user operation |
+| `create_all()` as an explicit function | Called at app startup. MVP auto-creates tables (REQ-10 deferred), but the function is isolated so it's easy to gate behind a flag later |
+| `get_session()` as a generator | Standard FastAPI/SQLModel pattern — yields a session, ensures cleanup. Compatible with `Depends()` when the API layer arrives in Step 5 |
+| `echo=False` default | Keeps logs clean. Can be toggled for debugging |
+
+### Proposed Implementation
+
+```python src/transcription/db.py
+"""Database engine, session factory, and schema bootstrap.
+
+MVP uses SQLite with auto-create-tables at startup.
+PostgreSQL migration is a post-MVP configuration change.
+"""
+import contextlib
+from collections.abc import Generator
+
+from sqlmodel import Session, SQLModel, create_engine
+
+from transcription.config import get_settings
+
+
+def _build_engine():
+    settings = get_settings()
+    connect_args = {}
+    if settings.database_url.startswith("sqlite"):
+        connect_args["check_same_thread"] = False
+    return create_engine(
+        settings.database_url,
+        echo=False,
+        connect_args=connect_args,
+    )
+
+
+engine = _build_engine()
+
+
+def create_all() -> None:
+    """Create all tables. Called once at application startup."""
+    SQLModel.metadata.create_all(engine)
+
+
+@contextlib.contextmanager
+def get_session() -> Generator[Session]:
+    """Yield a database session and ensure cleanup."""
+    with Session(engine) as session:
+        yield session
+```
+
+### SQLite-Specific Note
+
+`check_same_thread=False` is required for SQLite when the session may be accessed from different threads (e.g., a background worker on a different thread than the request handler). This setting is harmless and ignored for PostgreSQL connection strings.
+
+---
+
+## 5. Test Plan
+
+Refer to these resources for rules and guidelines about structure:
+
+- `resource://skills/pytesting/document`
+- `resource://catalog/prompts/pytest-scaffold`
+- `resource://catalog/prompts/pytest-fill-scaffold`
+
+Hierarchy pattern used in this step:
+
+```text
+tests/
+    conftest.py
+    test_config.py
+        TestSettingsLoading
+            test_loads_from_env
+            test_requires_api_key
+        TestProviderSettings
+            test_defaults_to_openrouter
+            test_rejects_invalid_value
+            test_optional_fields_default_to_none
+        TestPathSettings
+            test_path_fields_are_path_objects
+    test_models.py
+        TestDocumentModel
+            test_can_be_persisted
+            test_defaults_are_populated
+        TestJobModel
+            test_can_be_created_for_document
+            test_defaults_are_populated
+            test_transitions_to_transcribed
+            test_transitions_to_failed
+        TestTranscriptModel
+            test_success_record_persists
+            test_failure_record_persists
+            test_job_id_is_unique
+        TestRelationships
+            test_document_exposes_jobs
+            test_job_exposes_transcript
+    test_db.py
+        TestSchemaBootstrap
+            test_create_all_creates_expected_tables
+        TestSessionFactory
+            test_get_session_yields_session
+            test_session_is_closed_after_generator_exit
+```
+
+### `tests/conftest.py` — Shared Fixtures
+
+```python tests/conftest.py
+"""Shared test fixtures.
+
+Every test gets a fresh in-memory SQLite database so tests are
+isolated, fast, and leave no artifacts on disk.
+"""
+
+import pytest
+from sqlmodel import Session, SQLModel, create_engine
+from sqlmodel.pool import StaticPool
+
+
+@pytest.fixture
+def session():
+    """Provide a clean database session for each test."""
+    engine = create_engine(
+        "sqlite://",
+        connect_args={"check_same_thread": False},
+        poolclass=StaticPool,
+    )
+    SQLModel.metadata.create_all(engine)
+    with Session(engine) as session:
+        yield session
+```
+
+`StaticPool` ensures a single in-memory SQLite connection is shared across threads, which is required when `TestClient` (Step 5) spawns threads that would otherwise get separate in-memory databases. Establishing it now keeps the fixture stable across all future steps.
+
+### `tests/test_config.py` — Configuration Hierarchy
+
+| Class | Method | What It Verifies |
+|------|--------|------------------|
+| `TestSettingsLoading` | `test_loads_from_env` | `Settings` constructs successfully when `OPENROUTER_API_KEY` is set via env var |
+| `TestSettingsLoading` | `test_requires_api_key` | `Settings()` raises `ValidationError` when `OPENROUTER_API_KEY` is missing |
+| `TestProviderSettings` | `test_defaults_to_openrouter` | Default provider is `openrouter` when not explicitly set |
+| `TestProviderSettings` | `test_rejects_invalid_value` | Setting `PROVIDER=invalid` raises `ValidationError` |
+| `TestProviderSettings` | `test_optional_fields_default_to_none` | `provider_model`, `openrouter_http_referer`, and `openrouter_app_title` are `None` when unset |
+| `TestPathSettings` | `test_path_fields_are_path_objects` | `upload_dir` and `prompt_dir` are `Path` instances |
+
+### `tests/test_models.py` — Model & Relationship Hierarchy
+
+| Class | Method | What It Verifies |
+|------|--------|------------------|
+| `TestDocumentModel` | `test_can_be_persisted` | A `Document` can be persisted and read back with correct fields |
+| `TestDocumentModel` | `test_defaults_are_populated` | `id` is auto-generated UUID, `uploaded_at` is populated |
+| `TestJobModel` | `test_can_be_created_for_document` | A `Job` linked to a `Document` via FK persists correctly |
+| `TestJobModel` | `test_defaults_are_populated` | Default status is `queued`, `created_at` and `updated_at` are populated |
+| `TestJobModel` | `test_transitions_to_transcribed` | Status can be updated from `queued` → `processing` → `transcribed` |
+| `TestJobModel` | `test_transitions_to_failed` | Status can be updated from `processing` → `failed` |
+| `TestTranscriptModel` | `test_success_record_persists` | A `Transcript` with `text` set and `error_detail=None` persists correctly |
+| `TestTranscriptModel` | `test_failure_record_persists` | A `Transcript` with `text=None` and `error_detail` set persists correctly |
+| `TestRelationships` | `test_document_exposes_jobs` | `document.jobs` returns the linked `Job` list |
+| `TestRelationships` | `test_job_exposes_transcript` | `job.transcript` returns the linked `Transcript` |
+| `TestTranscriptModel` | `test_job_id_is_unique` | Inserting two transcripts with the same `job_id` raises an integrity error |
+
+### `tests/test_db.py` — Database Bootstrap Hierarchy
+
+| Class | Method | What It Verifies |
+|------|--------|------------------|
+| `TestSchemaBootstrap` | `test_create_all_creates_expected_tables` | After `create_all()`, the expected tables (`document`, `job`, `transcript`) exist in the database |
+| `TestSessionFactory` | `test_get_session_yields_session` | `get_session()` yields a usable `Session` object |
+| `TestSessionFactory` | `test_session_is_closed_after_generator_exit` | After the generator is exhausted, the session is closed |
+
+### Marker Strategy (Step 1)
+
+- Markers (`unit`, `integration`, `external`) are registered upfront in `pyproject.toml` with `--strict-markers` enabled, per pytesting skill conventions.
+- All Step 1 tests are unmarked — they run in the default lane since they are fast, deterministic, and have no external dependencies.
+- When slower integration or external tests are introduced in later steps, apply explicit markers and keep test names unchanged.
+
+### Test Workflow
+
+Follow the two-phase approach from `resource://catalog/prompts/pytest-scaffold` and `resource://catalog/prompts/pytest-fill-scaffold`:
+
+1. **Scaffold phase**: Create test files with class hierarchy, method names, and one-line docstrings only. Validate collection:
+   - `uv run pytest --collect-only -q`
+2. **Fill phase**: Implement assertions, fixtures, and minimal test data. Treat scaffolded names and docstrings as locked. Validate execution:
+   - `uv run pytest -q`
+
+Scaffolded structure is treated as a stable baseline — do not rename, move, merge, split, or re-nest tests once the scaffold is reviewed.
+
+---
+
+## 6. Step 1 Completion Checklist
+
+When all of the following are true, Step 1 is done and Step 2 can begin:
+
+| # | Criterion | How to Verify |
+|---|-----------|---------------|
+| 1 | `src/transcription/` package exists with `config.py`, `models.py`, `db.py` | `ls` / file inspection |
+| 2 | Empty `__init__.py` stubs exist for `providers/`, `services/`, `ui/` | `ls` / file inspection |
+| 3 | `Settings` loads from environment and validates `OPENROUTER_API_KEY` is present | `test_config.py` passes |
+| 4 | `Document`, `Job`, `Transcript` models create tables in SQLite | `test_models.py` passes |
+| 5 | `JobStatus` enum has exactly four values: `queued`, `processing`, `transcribed`, `failed` | `test_models.py` passes |
+| 6 | Foreign key relationships work: Document→Job→Transcript | `test_models.py` passes |
+| 7 | `create_all()` bootstraps the schema; `get_session()` yields a working session | `test_db.py` passes |
+| 8 | All tests pass: `uv run pytest -q` | CI / local run |
+| 9 | `hello.py` is deleted | File inspection |
+| 10 | `pyproject.toml` includes `openrouter`, `sqlmodel`, `pydantic-settings`, `pytest`, `pytest-asyncio` | File inspection |
+| 10a | `pyproject.toml` has `[tool.pytest.ini_options]` with `--strict-markers` and registered markers | File inspection |
+| 11 | `.env.example` documents all config vars; `.env` is in `.gitignore` | File inspection |
+| 12 | `setup_logging()` uses `logging.config.dictConfig` with centralized formatter/handler/root config | File inspection |
+| 13 | `uv run pytest --collect-only -q` shows expected test hierarchy | Local run |
+| 14 | `uv run pytest -q` passes all tests | Local run |
+
+---
+
+## 7. What This Step Does NOT Include
+
+Explicitly out of scope to prevent scope creep:
+
+| Excluded | Reason |
+|----------|--------|
+| FastAPI / NiceGUI app entrypoint | Step 5 |
+| Additional provider adapters beyond OpenRouter | Post-MVP |
+| Upload service logic | Step 4 |
+| Worker / background processing | Step 4 |
+| Transcription prompt files | Step 2 |
+| Alembic or migration tooling | Post-MVP (REQ-10 deferred) |
+| Async session factory | Post-MVP (REQ-7 deferred) |
+
+---
+
+This plan produces a fully tested, importable data foundation. Every subsequent step imports from `transcription.config`, `transcription.models`, and `transcription.db` without modification.

docs/mvp/mvp-step2.md

@@ -0,0 +1,278 @@
+## Step 2: prompts/transcribe_document.md
+
+### Goal
+
+Implement the MVP prompt artifact system by creating a curated transcription prompt file:
+
+- `prompts/transcribe_document.md`
+
+This step primarily satisfies:
+
+- **REQ-12**: prompts stored as individual Markdown artifacts
+- MVP Feature 3: prompt-driven verbatim transcription behavior grounded in `docs/intent.md`
+
+---
+
+## Scope for Step 2
+
+### In scope
+1. Create prompt artifact directory and first prompt file.
+2. Encode transcription rules from `docs/intent.md` into a model-facing prompt.
+3. Define stable prompt structure so future revisions are easy to diff/review.
+4. Add lightweight tests that validate artifact presence and baseline quality constraints.
+5. Update docs/README references so Step 3 can consume prompt file directly.
+
+### Out of scope
+- Provider integration logic (Step 3)
+- Worker/job orchestration (Step 4)
+- UI behavior (Step 5)
+
+---
+
+## Proposed Deliverables
+
+1. **`prompts/transcribe_document.md`**
+   - production prompt text for historical document transcription
+
+2. **`prompts/README.md`** (recommended)
+   - conventions for prompt files, revision policy, naming
+
+3. **`tests/test_prompts.py`** (recommended)
+   - artifact existence + structure checks
+
+4. **Small docs update** (README or docs reference)
+   - indicate that prompts are file-based and loaded from `PROMPT_DIR`
+
+---
+
+## Detailed Work Breakdown
+
+### 1) Create prompt artifact folder and canonical file
+- Add `prompts/` at repo root.
+- Add `transcribe_document.md` as the first curated artifact.
+- Keep filename stable; this becomes the default in Step 3 unless overridden.
+
+### 2) Author prompt content using a strict, sectioned format
+Use section headers so future diffs are clean and policy changes are isolated.
+
+Suggested sections:
+
+1. **Purpose**
+   - verbatim scholarly transcription of historical documents
+
+2. **Output requirements**
+   - plain text only
+   - no summaries, no paraphrasing
+   - preserve reading order and meaningful structure
+
+3. **Core fidelity rules**
+   - preserve original wording and punctuation
+   - don’t silently normalize grammar/spelling
+   - no invented content
+
+4. **Issue-handling rules (mapped from Intent table)**
+   - misspellings with `[sic]`
+   - missing words with `[word]`
+   - uncertainty with `[guess?]`
+   - illegible with `[illegible]` / reason tags
+   - crossed-out text as `[deleted: ...]`
+   - inserted text as `[inserted: ...]`
+   - superscripts handling guidance
+   - non-text elements as `[description]`
+   - marginalia format `[written in left margin: ...]`
+   - line-break hyphen rejoin behavior
+   - capitalization policy
+   - hierarchical outline preservation (including unusual numbering)
+
+5. **Confidence/ambiguity policy**
+   - prefer explicit uncertainty markers over hallucination
+
+6. **Final self-checklist for model**
+   - did I preserve structure?
+   - did I mark uncertain text?
+   - did I avoid silent corrections?
+
+### 3) Add prompt-library conventions (`prompts/README.md`)
+Recommended conventions:
+- one prompt per file
+- snake_case names
+- each file starts with purpose + behavior contract
+- iterative edits, one prompt per PR where possible
+- no secrets in prompt files
+
+### 4) Add tests for prompt assets (`tests/test_prompts.py`)
+Keep tests robust but not brittle.
+
+Recommended tests:
+1. `test_prompt_file_exists`
+2. `test_prompt_file_is_not_empty`
+3. `test_prompt_mentions_verbatim_behavior`
+4. `test_prompt_includes_uncertainty_and_illegible_markers`
+5. `test_prompt_includes_deleted_and_inserted_conventions`
+
+Avoid exact full-text matching; verify key semantic anchors only.
+
+### 5) Optional config alignment check
+Current config already has:
+- `prompt_dir: Path = Path("./prompts")`
+
+In Step 2, ensure docs reflect this and that Step 3 will resolve:
+- `PROMPT_DIR / "transcribe_document.md"`
+
+---
+
+## Task-by-Task Execution Checklist
+
+## Phase A — Scaffold files
+
+- [ ] **A1. Create prompt directory**
+  - Path: `prompts/`
+  - Verify: directory exists at repo root
+
+- [ ] **A2. Create canonical prompt file**
+  - Path: `prompts/transcribe_document.md`
+  - Verify: file exists and is non-empty
+
+- [ ] **A3. (Recommended) Create prompt library README**
+  - Path: `prompts/README.md`
+  - Verify: includes naming + revision conventions
+
+---
+
+## Phase B — Author prompt content (core work)
+
+- [ ] **B1. Add Purpose section**
+  - States verbatim historical transcription objective
+  - Explicitly disallows summarization/paraphrase
+
+- [ ] **B2. Add Output Contract section**
+  - Plain text output expectation
+  - Preserve meaningful structure and reading order
+  - No fabricated text
+
+- [ ] **B3. Add Rule Set from `docs/intent.md`**
+  - Misspellings/errors: `[sic]`
+  - Missing words: `[word]`
+  - Uncertain readings: `[guess?]`
+  - Illegible regions: `[illegible]` / reason labels
+  - Crossed-out text: `[deleted: ...]`
+  - Squeezed-in text: `[inserted: ...]`
+  - Superscripts/abbrev handling guidance
+  - Non-text visuals: bracketed descriptive labels
+  - Marginalia formatting cue
+  - Rejoin line-break hyphenated words silently
+  - Ambiguous capitalization policy
+  - Hierarchical outline numbering preservation
+
+- [ ] **B4. Add Ambiguity and Confidence policy**
+  - “Mark uncertainty instead of guessing”
+  - “Never silently normalize uncertain passages”
+
+- [ ] **B5. Add Final Self-Check section**
+  - Checklist for fidelity, uncertainty labeling, and format compliance
+
+---
+
+## Phase C — Add validations (tests)
+
+- [ ] **C1. Create prompt tests file**
+  - Path: `tests/test_prompts.py`
+
+- [ ] **C2. Add existence/health checks**
+  - Prompt file exists
+  - Prompt file has content (non-whitespace)
+
+- [ ] **C3. Add semantic anchor checks**
+  - Mentions verbatim behavior
+  - Mentions uncertainty marker pattern (`?` in brackets conceptually)
+  - Mentions illegible handling
+  - Mentions deleted/inserted conventions
+
+- [ ] **C4. Keep tests resilient**
+  - Avoid exact full-file snapshot assertions
+  - Assert required concepts, not precise phrasing
+
+---
+
+## Phase D — Documentation alignment
+
+- [ ] **D1. Update top-level docs/README reference**
+  - Mention that prompts live in `prompts/`
+  - Mention Step 3 loads from `PROMPT_DIR`
+
+- [ ] **D2. Confirm config compatibility**
+  - `src/transcription/config.py` already uses `prompt_dir = Path("./prompts")`
+  - No code change needed unless naming/path mismatch appears
+
+---
+
+## Phase E — Verification
+
+- [ ] **E1. Run targeted test file**
+  - `uv run pytest tests/test_prompts.py -q`
+
+- [ ] **E2. Run full suite**
+  - `uv run pytest -q`
+
+- [ ] **E3. Confirm no regressions**
+  - All existing tests still green (expected: previous 20 + new prompt tests)
+
+---
+
+## Phase F — Commit plan (recommended granularity)
+
+- [ ] **F1. Commit 1: scaffold**
+  - `prompts/transcribe_document.md` (initial structure)
+  - `prompts/README.md` (if included)
+
+- [ ] **F2. Commit 2: finalized prompt content**
+  - full rule-complete prompt text
+
+- [ ] **F3. Commit 3: tests + docs alignment**
+  - `tests/test_prompts.py`
+  - README/docs mention of prompt artifact pattern
+
+---
+
+## Done Criteria (quick gate)
+
+- [ ] Canonical prompt exists and is curated for verbatim transcription.
+- [ ] Prompt encodes all high-value handling rules from `docs/intent.md`.
+- [ ] Prompt tests pass.
+- [ ] Full project tests pass with `uv`.
+- [ ] Ready for Step 3 provider integration.
+
+---
+
+## Acceptance Criteria (Definition of Done)
+
+Step 2 is complete when all are true:
+
+1. `prompts/transcribe_document.md` exists and is committed.
+2. Prompt includes all critical handling rules from `docs/intent.md`.
+3. Prompt is structured with stable section headings for future curation.
+4. Prompt tests pass under `uv run pytest -q`.
+5. Existing tests remain green (total suite still passes).
+6. Docs indicate prompt artifact location and curation policy.
+
+---
+
+## Risks and Mitigations
+
+1. **Risk: prompt too vague → hallucinated reconstructions**
+   - Mitigation: explicit uncertainty/illegible conventions and “no invention” rule.
+
+2. **Risk: prompt too rigid for mixed document types**
+   - Mitigation: include neutral defaults + clear annotation formats.
+
+3. **Risk: brittle tests block iterative prompt tuning**
+   - Mitigation: test semantic anchors, not exact wording.
+
+---
+
+## Handoff to Step 3
+
+After Step 2, Step 3 can immediately:
+1. Load `transcribe_document.md` from `PROMPT_DIR`
+2. Inject prompt into OpenRouter request
+3. Start validating real transcription behavior with minimal glue code

docs/mvp/mvp-step3.md

@@ -0,0 +1,236 @@
+## Step 3: services/transcription.py + providers/ 
+
+### Objective
+
+Implement the **AI transcription integration layer** so the app can:
+
+1. Read the curated prompt from `PROMPT_DIR`
+2. Send prompt + image to the configured provider (OpenRouter)
+3. Return normalized transcription output (or structured failure)
+
+This corresponds to MVP Step 3 from `docs/mvp.md`:
+- `services/transcription.py`
+- `providers/` adapter(s)
+
+---
+
+## Scope for Step 3
+
+### In scope
+- Provider abstraction and OpenRouter adapter
+- Prompt file loading utility in service layer
+- Image payload preparation
+- One high-level transcription service function usable by Step 4 worker
+- Unit tests (mocked provider SDK, no external calls)
+
+### Out of scope
+- Job polling/background loop (Step 4)
+- DB status transition orchestration in worker loop (Step 4)
+- UI invocation/wiring (Step 5)
+
+---
+
+## Planned Deliverables
+
+### Source files
+- `src/transcription/providers/base.py`
+- `src/transcription/providers/openrouter.py`
+- `src/transcription/providers/__init__.py` (exports + factory)
+- `src/transcription/services/transcription.py`
+- `src/transcription/services/__init__.py` (optional export)
+
+### Tests
+- `tests/providers/test_openrouter.py`
+- `tests/services/test_transcription.py`
+
+### Test directory convention
+- Mirror source domains under `tests/`.
+- Provider adapter tests live under `tests/providers/`.
+- Service-layer tests live under `tests/services/`.
+- Prefer one focused test module per production module (for Step 3: `test_openrouter.py`, `test_transcription.py`).
+
+---
+
+## Design Decisions (before coding)
+
+1. **Provider interface first**
+   - Define a stable contract independent of SDK specifics.
+   - Prevent Step 4 from depending on raw SDK response shapes.
+
+2. **Service returns normalized result object**
+   - Include: `text`, `provider`, `model`, `raw_error`/exception metadata.
+   - Worker can map this cleanly to `Transcript` and `JobStatus`.
+
+3. **Prompt loaded from file at call time**
+   - Uses `get_settings().prompt_dir / "transcribe_document.md"`.
+   - Keeps prompt edits hot-swappable without code changes.
+
+4. **Clear exception boundary**
+   - SDK/network/model failures become predictable domain exceptions:
+     - `ProviderError`
+     - `PromptLoadError`
+     - `TranscriptionError` (optional top-level wrapper)
+
+5. **Model resolution policy**
+   - Use `settings.provider_model` if set
+   - Otherwise use adapter default constant (e.g., vision-capable model slug)
+
+---
+
+## Task-by-Task Execution Checklist
+
+## Phase A — Provider contract
+
+- [ ] Create `src/transcription/providers/base.py`
+- [ ] Define protocol/ABC for transcription providers:
+  - [ ] method signature accepts prompt text + image bytes (or data URL) + mime type
+  - [ ] returns normalized text result (and optional metadata)
+- [ ] Define shared provider exceptions:
+  - [ ] `ProviderError`
+  - [ ] optional subclasses (`ProviderAuthError`, `ProviderResponseError`)
+
+---
+
+## Phase B — OpenRouter adapter
+
+- [ ] Create `src/transcription/providers/openrouter.py`
+- [ ] Implement `OpenRouterTranscriptionProvider` with:
+  - [ ] config-driven API key usage
+  - [ ] optional referer/title attribution headers
+  - [ ] model resolution fallback when `provider_model` is unset
+- [ ] Implement request building:
+  - [ ] prompt included as instruction content
+  - [ ] image included in supported format for vision call
+- [ ] Implement response parsing:
+  - [ ] extract final transcript text from SDK response
+  - [ ] validate non-empty text
+- [ ] Wrap SDK failures into `ProviderError` with clean message
+
+---
+
+## Phase C — Provider factory
+
+- [ ] Update `src/transcription/providers/__init__.py`
+- [ ] Add `get_transcription_provider()` factory:
+  - [ ] reads `settings.provider`
+  - [ ] returns OpenRouter adapter for `openrouter`
+  - [ ] raises explicit error for unsupported provider values
+
+---
+
+## Phase D — Transcription service (Step 3 core)
+
+- [ ] Create `src/transcription/services/transcription.py`
+- [ ] Add prompt loader function:
+  - [ ] default file: `transcribe_document.md`
+  - [ ] raises `PromptLoadError` on missing/empty file
+- [ ] Add image loader/validator:
+  - [ ] path existence check
+  - [ ] allowed mime detection (`.jpg/.jpeg/.png/.tiff/.pdf` policy aligned to MVP)
+- [ ] Add high-level function (name example):
+  - [ ] `transcribe_document_image(image_path, prompt_name="transcribe_document.md")`
+  - [ ] loads prompt + image
+  - [ ] calls provider from factory
+  - [ ] returns normalized transcription result object
+- [ ] Add structured logging at key boundaries:
+  - [ ] prompt loaded
+  - [ ] provider invoked
+  - [ ] success/failure outcome (no sensitive data in logs)
+
+---
+
+## Phase E — Tests (two-phase scaffold -> fill)
+
+### Required execution resources
+
+Load and reference these directly during test planning/implementation so the two-phase flow is enforced:
+
+- [ ] `resource://catalog/prompts/pytest-scaffold`
+- [ ] `resource://prompts/pytest-scaffold/document`
+- [ ] `resource://catalog/prompts/pytest-fill-scaffold`
+- [ ] `resource://prompts/pytest-fill-scaffold/document`
+
+### Phase E1 — Scaffold test structure first
+
+Prompt: `resource://catalog/prompts/pytest-scaffold`
+
+Suggested arguments:
+- [ ] `target_modules` = `src/transcription/providers/openrouter.py`, `src/transcription/services/transcription.py`
+- [ ] `mode` = `scaffold`
+- [ ] `path_strategy` = `src-to-tests-mirror`
+- [ ] `naming_style` = `concise-behavior`
+
+Expected scaffold outcomes:
+- [ ] `tests/providers/test_openrouter.py` exists with class/method skeletons and one-line docstrings
+- [ ] `tests/services/test_transcription.py` exists with class/method skeletons and one-line docstrings
+- [ ] collection succeeds on scaffold-only tests
+
+Scaffold coverage targets:
+- [ ] adapter initializes from settings
+- [ ] model fallback when `provider_model is None`
+- [ ] referer/title options included when set
+- [ ] successful SDK response parses transcript text
+- [ ] SDK exception maps to `ProviderError`
+- [ ] empty/invalid response maps to `ProviderError`
+- [ ] prompt loader reads canonical prompt file
+- [ ] missing prompt raises `PromptLoadError`
+- [ ] transcription function loads file and calls provider once
+- [ ] image path missing raises clear error
+- [ ] provider error is propagated/wrapped predictably
+- [ ] returned result includes transcript text and metadata
+
+### Phase E2 — Fill scaffolded tests with assertions
+
+Prompt: `resource://catalog/prompts/pytest-fill-scaffold`
+
+Suggested arguments:
+- [ ] `target_files` = `tests/providers/test_openrouter.py`, `tests/services/test_transcription.py`
+- [ ] `stack` = `pure-python`
+- [ ] `strategy` = `minimal`
+- [ ] `marker_lane` = `unit`
+
+Fill constraints:
+- [ ] preserve scaffold class/method names and one-line docstrings
+- [ ] keep mocks to an absolute minimum; mock only network boundaries and non-deterministic failures
+- [ ] keep one behavior target per test method
+
+> Default suite should remain deterministic and fast, but mocking should be minimal and intentional.
+
+### Optional real-endpoint validation lane
+
+- [ ] Add an opt-in integration lane for real provider calls (for example `@pytest.mark.integration` and `@pytest.mark.live_api`).
+- [ ] Gate live tests behind explicit env vars (for example `OPENROUTER_API_KEY`, optional `RUN_LIVE_API_TESTS=1`).
+- [ ] Exclude live tests from default CI/local runs unless explicitly requested.
+- [ ] Keep at least one thin smoke path that can validate request/response compatibility against the real endpoint.
+
+---
+
+## Phase F — Verification commands
+
+- [ ] E1 scaffold validation: `uv run pytest --collect-only -q`
+- [ ] E2 fill validation (unit lane): `uv run pytest -m unit -q`
+- [ ] E2 targeted provider file: `uv run pytest tests/providers/test_openrouter.py -q`
+- [ ] E2 targeted service file: `uv run pytest tests/services/test_transcription.py -q`
+- [ ] E2 final full-suite check: `uv run pytest -q`
+
+---
+
+## Implementation Notes / Guardrails
+
+- Avoid coupling Step 3 service to DB models directly (that belongs in Step 4 orchestration).
+- Do not silently swallow provider errors.
+- Keep prompt filename stable (`transcribe_document.md`) unless explicitly parameterized.
+- Keep request/response normalization inside provider adapter, not worker/UI layers.
+
+---
+
+## Definition of Done (Step 3)
+
+Step 3 is done when:
+
+1. Provider abstraction exists and OpenRouter adapter is implemented.
+2. Service can transcribe a local image using prompt file content.
+3. Failures are returned as structured exceptions, not raw SDK traceback noise.
+4. Unit tests for provider and service pass.
+5. Full suite remains green under `uv run pytest -q`.
+6. Step 4 can call a single service function to process queued jobs.

docs/mvp/mvp-step4.md

@@ -0,0 +1,262 @@
+## Step 4: `services/upload.py` + `worker.py`
+
+### Objective
+
+Implement the MVP upload and background-processing pipeline so the system can:
+
+1. Save uploaded files into `UPLOAD_DIR`
+2. Create `Document` + `Job(status="queued")`
+3. Process queued jobs in a worker loop:
+   - `queued -> processing`
+   - call Step 3 transcription service
+   - persist `Transcript`
+   - finalize as `transcribed` or `failed`
+
+This step advances MVP Feature 1 + Feature 2 and supports REQ-1, REQ-2, REQ-3, REQ-4, REQ-6.
+
+---
+
+## Scope
+
+### In scope
+- `src/transcription/services/upload.py`
+- `src/transcription/worker.py`
+- Upload persistence logic and initial job creation
+- Worker polling and single-job lifecycle execution
+- Deterministic test coverage for upload + worker (default suite)
+
+### Out of scope
+- UI integration and pages (Step 5)
+- Queue infrastructure beyond in-process loop
+- Async DB/session architecture refactor
+- Broad production hardening beyond MVP needs
+
+---
+
+## Planned Deliverables
+
+### Source files
+- `src/transcription/services/upload.py`
+- `src/transcription/worker.py`
+- `src/transcription/services/__init__.py` (export updates as needed)
+
+### Test files
+- `tests/services/test_upload.py`
+- `tests/services/test_worker.py`
+
+### Optional external lane (already present pattern)
+- reuse `external` marker for live-provider checks where appropriate
+- keep external out of default lane
+
+---
+
+## Required MCP Prompt References (for test workflow)
+
+Apply these resources directly during Step 4 test creation:
+
+1. `resource://catalog/prompts/pytest-scaffold`
+2. `resource://prompts/pytest-scaffold/document`
+3. `resource://catalog/prompts/pytest-fill-scaffold`
+4. `resource://prompts/pytest-fill-scaffold/document`
+
+And (as referenced by those prompts) apply relevant pytest skill references for:
+- naming/hierarchy
+- marker defaults
+- SQLAlchemy sync testing behavior where applicable
+
+---
+
+## Design Decisions
+
+1. **Upload service owns initial file + record creation**
+   - Writes file, creates `Document`, creates queued `Job`, returns IDs/path.
+
+2. **Worker owns lifecycle transitions**
+   - Worker is the single owner of `queued -> processing -> terminal` job state changes.
+
+3. **Worker uses Step 3 service boundary**
+   - Worker calls `transcribe_document_image(...)`; no provider-specific SDK logic in worker.
+
+4. **Failure information is always persisted**
+   - On failure: store `Transcript(text=None, error_detail=...)` and set `Job.status=failed`.
+
+5. **Loop remains simple and stoppable**
+   - In-process polling loop with stop event and poll interval for MVP simplicity and testability.
+
+---
+
+## Task-by-Task Execution Checklist
+
+## Phase A — Implement upload service (`src/transcription/services/upload.py`)
+
+- [ ] Create `UploadError` exception
+- [ ] Create `UploadJobResult` dataclass with:
+  - [ ] `document_id`
+  - [ ] `job_id`
+  - [ ] `stored_path`
+  - [ ] `original_filename`
+- [ ] Add filename safety handling:
+  - [ ] normalize to basename
+  - [ ] avoid path traversal
+  - [ ] collision-safe stored name (e.g., UUID prefix/suffix)
+- [ ] Validate upload payload:
+  - [ ] non-empty bytes required
+  - [ ] extension in supported set (`.jpg/.jpeg/.png/.tif/.tiff/.pdf`)
+- [ ] Ensure upload directory exists (`mkdir(parents=True, exist_ok=True)`)
+- [ ] Write file bytes to `UPLOAD_DIR`
+- [ ] Persist DB records in one transaction:
+  - [ ] `Document(filename, file_path)`
+  - [ ] `Job(document_id=..., status=queued)`
+- [ ] Return `UploadJobResult`
+- [ ] Add logging for success/failure boundaries
+
+---
+
+## Phase B — Implement worker core (`src/transcription/worker.py`)
+
+- [ ] Add `process_next_queued_job(...) -> bool`
+- [ ] Fetch oldest queued job
+- [ ] Return `False` when no queued jobs exist
+- [ ] Transition picked job to `processing` and update timestamp
+- [ ] Resolve associated `Document.file_path`
+- [ ] Call `transcribe_document_image(image_path=...)`
+- [ ] On success:
+  - [ ] insert/update transcript text
+  - [ ] clear error detail
+  - [ ] mark job `transcribed`
+  - [ ] update timestamp
+- [ ] On failure:
+  - [ ] insert/update transcript with `text=None`, `error_detail=...`
+  - [ ] mark job `failed`
+  - [ ] update timestamp
+- [ ] Commit terminal state and return `True`
+- [ ] Add logs around job pickup, transition, and terminal outcome
+
+---
+
+## Phase C — Implement worker loop (`src/transcription/worker.py`)
+
+- [ ] Add `run_worker_loop(...)`
+- [ ] Accept configurable stop event/signal
+- [ ] Accept configurable poll interval
+- [ ] Repeatedly call `process_next_queued_job`
+- [ ] Sleep only when queue is empty
+- [ ] Exit cleanly when stop event is set
+
+---
+
+## Phase D — Exports
+
+- [ ] Update `src/transcription/services/__init__.py` to expose upload APIs
+- [ ] Keep existing transcription exports intact
+
+---
+
+## Phase E — Tests via MCP scaffold -> fill flow
+
+## E1 Scaffold (structure only)
+
+Use scaffold prompt workflow first for:
+- `src/transcription/services/upload.py`
+- `src/transcription/worker.py`
+
+Expected scaffold targets:
+- `tests/services/test_upload.py`
+- `tests/services/test_worker.py`
+
+Scaffold rules:
+- [ ] Class hierarchy + method names + one-line docstrings only
+- [ ] No assertions or implementation details in scaffold phase
+- [ ] Keep method names concise and behavior-focused
+
+Validation:
+- [ ] `uv run pytest --collect-only -q`
+
+## E2 Fill scaffold (implementation)
+
+Use fill prompt workflow for:
+- `tests/services/test_upload.py`
+- `tests/services/test_worker.py`
+- stack: `sqlalchemy-sync` (or `mixed` if combining pure + DB behaviors)
+- marker lane preference: `unit` and `integration` as appropriate
+- strategy: minimal deterministic implementation
+
+Fill rules (invariants):
+- [ ] Preserve scaffold class names, method names, and one-line docstrings
+- [ ] Do not rename/re-nest scaffolded tests unless explicitly approved
+- [ ] One behavior target per test
+- [ ] Minimal mocking; mock only network/nondeterministic boundaries
+
+Suggested test coverage:
+
+### `tests/services/test_upload.py`
+- [ ] creates file + document + queued job (`integration`)
+- [ ] rejects empty bytes (`unit`)
+- [ ] rejects unsupported extension (`unit`)
+- [ ] writes collision-safe unique filename (`integration`)
+- [ ] persisted job status is `queued` (`integration`)
+
+### `tests/services/test_worker.py`
+- [ ] returns `False` when queue empty (`integration`)
+- [ ] transitions `queued -> processing -> transcribed` on success (`integration`)
+- [ ] stores transcript text on success (`integration`)
+- [ ] transitions to `failed` and stores `error_detail` on failure (`integration`)
+- [ ] updates existing transcript instead of duplicate create (`integration`)
+- [ ] worker loop exits when stop event set (`unit`)
+
+---
+
+## Marker Strategy
+
+- `unit`: pure logic tests (filename handling, loop stop behavior, validation logic)
+- `integration`: DB + service orchestration tests (SQLite/session/contracts)
+- `external`: opt-in live provider tests only (not part of default Step 4 lane)
+
+No new marker needed; reuse existing marker registration.
+
+---
+
+## Validation Sequence (strict order)
+
+- [ ] `uv run pytest --collect-only -q`
+- [ ] `uv run pytest -m unit -q` *(if unit tests touched)*
+- [ ] `uv run pytest tests/services/test_upload.py -q`
+- [ ] `uv run pytest tests/services/test_worker.py -q`
+- [ ] `uv run pytest -q`
+
+---
+
+## Reporting Requirements (after implementation)
+
+Implementation report must include:
+
+1. Files created/updated
+2. Fixture and marker decisions
+3. MCP references used and why
+4. Validation command results
+5. Remaining risks/open questions (only blockers)
+
+---
+
+## Guardrails
+
+- Keep Step 4 independent from UI concerns.
+- Do not call provider SDK directly from worker.
+- Do not silently swallow exceptions.
+- Always persist terminal job outcome.
+- Keep default suite deterministic and fast.
+- Preserve scaffold invariants during fill phase.
+
+---
+
+## Definition of Done (Step 4)
+
+Step 4 is complete when:
+
+- [ ] Upload service writes file and creates `Document` + queued `Job`
+- [ ] Worker processes queued jobs end-to-end using Step 3 transcription service
+- [ ] Success path persists transcript text and sets `transcribed`
+- [ ] Failure path persists error detail and sets `failed`
+- [ ] Queue-empty path returns cleanly
+- [ ] New tests pass and full suite is green (`uv run pytest -q`)
+- [ ] Output report includes MCP reference usage + validation evidence

docs/mvp/mvp-step5-results.md

@@ -0,0 +1,70 @@
+Step 5 is implemented and passing ✅
+
+### What I implemented
+
+#### App/bootstrap
+- Added `src/transcription/app.py`:
+  - `create_app()` factory
+  - FastAPI lifespan startup/shutdown:
+    - `setup_logging()`
+    - `create_all()`
+    - ensure `upload_dir` and `prompt_dir`
+    - start/stop worker thread (`run_worker_loop`)
+  - includes health router
+  - registers NiceGUI pages
+
+#### API
+- Added `src/transcription/api/__init__.py`
+- Added `src/transcription/api/health.py`:
+  - `GET /healthz` returns `{"status": "ok"}`
+
+#### UI
+- Added `src/transcription/ui/upload_page.py`:
+  - upload page route
+  - accepted extensions helper
+  - upload submit helper to Step 4 service (`create_upload_job`)
+  - success/error state messaging
+- Added `src/transcription/ui/jobs_page.py`:
+  - jobs list page
+  - job detail page
+  - `fetch_jobs()` and `fetch_job_detail()` helpers
+- Updated `src/transcription/ui/__init__.py`:
+  - explicit page registration
+  - NiceGUI mounted via `ui.run_with(app, mount_path="/ui", ...)`
+
+#### Dependencies
+- Added runtime dependencies:
+  - `fastapi`
+  - `nicegui`
+
+---
+
+### Tests created and filled (scaffold → fill)
+
+- `tests/test_app.py`
+- `tests/api/test_health.py`
+- `tests/ui/test_pages_registration.py`
+- `tests/ui/test_upload_page.py`
+- `tests/ui/test_jobs_page.py`
+
+All scaffolded method names/docstrings were preserved and filled with executable assertions.
+
+---
+
+### Validation results (strict sequence)
+
+- `uv run pytest --collect-only -q` ✅
+- `uv run pytest -m unit -q` ✅
+- `uv run pytest tests/api/test_health.py -q` ✅
+- `uv run pytest tests/ui/test_pages_registration.py -q` ✅
+- `uv run pytest tests/test_app.py -q` ✅
+- `uv run pytest tests/ui/test_upload_page.py -q` ✅
+- `uv run pytest tests/ui/test_jobs_page.py -q` ✅
+- `uv run pytest -q` ✅
+
+Full suite is green.
+
+---
+
+### Note
+You’ll see one warning from FastAPI/Starlette test client about `httpx` deprecation; it does not affect correctness and all tests pass.

docs/mvp/mvp-step5.md

@@ -0,0 +1,310 @@
+## Step 5: `app.py` + UI Pages (NiceGUI + FastAPI composition)
+
+## Objective
+
+Implement the MVP user-facing application layer so users can:
+
+1. Upload a document from the UI
+2. Trigger Step 4 upload/job creation flow
+3. See live job lifecycle status (`queued`, `processing`, `transcribed`, `failed`)
+4. Open a job detail view to read transcript text or failure details
+
+This step composes Steps 1–4 into a usable UI.
+
+---
+
+## Architecture Summary (NiceGUI-aligned)
+
+Step 5 uses a **FastAPI app factory + lifespan orchestration** and mounts/registers NiceGUI pages via explicit page modules.
+
+Reference baseline: `resource://skills/nicegui/document`
+
+### Core architecture decisions
+
+- **App factory:** `create_app()`
+- **Lifespan-managed resources:** worker start/stop managed in startup/shutdown
+- **Modular pages:** upload and jobs pages in separate modules (no monolithic UI file)
+- **Health endpoint:** FastAPI-side `/healthz`
+- **UI composition:** route pages stay modular and reusable shared shell/components live under `ui/components` as needed
+- **Styling architecture:** shared CSS loaded once at startup; avoid ad-hoc per-page styling drift
+- **Dependency direction (one-way):**
+  - `app` -> `config/logging/db/worker/ui/api`
+  - `ui/pages` -> `ui/components` + `services`
+  - `services` -> `db/models/providers`
+  - no reverse imports from services into UI/API
+
+### DB and AI stance (explicit)
+
+- **DB:** already enabled (SQLModel + SQLite), session lifecycle remains request/service-scoped as built in prior steps.
+- **AI workflow:** already in place via Step 3 transcription service + Step 4 worker; UI does not call provider SDK directly.
+- **Mounted docs:** not in Step 5 scope; docs mounting remains disabled for MVP.
+
+### Async and responsiveness stance
+
+- Prefer `async def` for page handlers and service boundaries when I/O is involved.
+- Keep UI handlers non-blocking (no blocking sleeps or synchronous long I/O calls).
+- For long-running user actions, always provide explicit loading/progress/error states.
+- Keep cancellation/timeout behavior explicit for refresh/poll operations where applicable.
+
+---
+
+## Scope
+
+### In scope
+- `src/transcription/app.py`
+- `src/transcription/ui/upload_page.py`
+- `src/transcription/ui/jobs_page.py`
+- `src/transcription/ui/__init__.py`
+- `src/transcription/api/health.py` (or equivalent FastAPI health route module)
+- UI/app tests with MCP scaffold->fill flow
+
+### Out of scope
+- Auth
+- advanced filtering/search UX
+- batch upload UX beyond MVP
+- deployment/container hardening
+
+---
+
+## Planned Deliverables
+
+### Source files
+- `src/transcription/app.py` (app factory + lifespan wiring)
+- `src/transcription/api/health.py` (GET `/healthz`)
+- `src/transcription/ui/upload_page.py` (upload flow)
+- `src/transcription/ui/jobs_page.py` (status list + detail)
+- `src/transcription/ui/__init__.py` (explicit `register_pages(...)` export)
+- `src/transcription/ui/components/*` (shared shell/navigation/status components if introduced)
+- `src/transcription/ui/static/*.css` (optional shared CSS loaded once at startup)
+
+### Test files
+- `tests/test_app.py`
+- `tests/api/test_health.py`
+- `tests/ui/test_pages_registration.py`
+- `tests/ui/test_upload_page.py`
+- `tests/ui/test_jobs_page.py`
+
+---
+
+## Implementation Plan + Checklist
+
+Plan baseline and guardrails source: `resource://skills/nicegui/document`
+
+## Phase A — App factory and lifespan orchestration
+
+- [ ] Create `create_app()` in `src/transcription/app.py`
+- [ ] Add FastAPI lifespan startup/shutdown handlers
+- [ ] Startup responsibilities:
+  - [ ] `setup_logging()`
+  - [ ] `create_all()`
+  - [ ] ensure directories exist (`upload_dir`, `prompt_dir`)
+  - [ ] create worker stop event
+  - [ ] start worker background thread/task
+- [ ] Shutdown responsibilities:
+  - [ ] signal stop event
+  - [ ] join/cleanup worker thread/task cleanly
+- [ ] Register API router(s), including health route
+- [ ] Register NiceGUI pages via explicit page registration function
+- [ ] Load shared CSS once at startup (if present)
+
+## Phase B — FastAPI health endpoint
+
+- [ ] Create `src/transcription/api/health.py`
+- [ ] Add `GET /healthz` returning simple healthy payload
+- [ ] Wire route into app factory
+
+## Phase C — Upload page (`ui/upload_page.py`)
+
+- [ ] Add upload route/page registration function
+- [ ] Render file input accepting supported extensions
+- [ ] On submit:
+  - [ ] show loading/progress state
+  - [ ] call `create_upload_job(filename, file_bytes, ...)`
+  - [ ] show success state with job reference/link
+- [ ] On error:
+  - [ ] show user-safe error message
+  - [ ] restore ready UI state
+- [ ] Ensure non-blocking I/O in UI event handlers; offload CPU-heavy work to worker path
+- [ ] Make timeout/cancellation behavior explicit for any long-running action
+
+## Phase D — Jobs page (`ui/jobs_page.py`)
+
+- [ ] Add jobs list route/page registration function
+- [ ] Display jobs with status + timestamps
+- [ ] Add job detail route/view
+- [ ] Show transcript on success, error detail on failure
+- [ ] Include explicit refresh action and loading state
+- [ ] Ensure error states are surfaced to user and logged
+- [ ] Keep refresh path async and bounded to avoid UI freeze
+
+## Phase E — UI registration module
+
+- [ ] Update `src/transcription/ui/__init__.py`
+- [ ] Export `register_pages(...)`
+- [ ] Ensure each page module exports `register_page(...)`
+- [ ] Keep page registration explicit and modular
+
+## Phase F — Shared components and style consistency
+
+- [ ] Add `ui/components` module only for reusable shell elements (header/nav/status chips), not page-local logic
+- [ ] Keep structural layout in Python; keep visual polish in shared CSS
+- [ ] Avoid one-off styling duplication across upload/jobs pages
+
+---
+
+## MCP Testing Workflow (Required)
+
+Use these resources directly:
+
+- `resource://catalog/prompts/pytest-scaffold`
+- `resource://prompts/pytest-scaffold/document`
+- `resource://catalog/prompts/pytest-fill-scaffold`
+- `resource://prompts/pytest-fill-scaffold/document`
+
+## E1 — Scaffold tests first (structure only)
+
+Target modules:
+- `src/transcription/app.py`
+- `src/transcription/api/health.py`
+- `src/transcription/ui/upload_page.py`
+- `src/transcription/ui/jobs_page.py`
+
+Scaffold test files:
+- `tests/test_app.py`
+- `tests/api/test_health.py`
+- `tests/ui/test_pages_registration.py`
+- `tests/ui/test_upload_page.py`
+- `tests/ui/test_jobs_page.py`
+
+Scaffold constraints:
+- [ ] class/method skeletons only
+- [ ] one-line docstrings
+- [ ] concise behavior-focused names
+- [ ] no implementation assertions yet
+
+Validation:
+- [ ] `uv run pytest --collect-only -q`
+
+## E2 — Fill scaffold tests
+
+Fill constraints from MCP guidance:
+- [ ] preserve scaffold class/method names and docstrings (locked baseline)
+- [ ] one behavior target per method
+- [ ] deterministic tests preferred
+- [ ] minimal mocking; only nondeterministic boundaries
+
+Stack:
+- [ ] `fastapi` (or `mixed` if needed for UI+DB fixture combination)
+
+Suggested coverage:
+
+### `tests/api/test_health.py`
+- [ ] `/healthz` returns success status and expected payload shape
+
+### `tests/ui/test_pages_registration.py`
+- [ ] page registration wiring succeeds
+- [ ] expected routes are present
+
+### `tests/test_app.py`
+- [ ] startup path initializes runtime dependencies
+- [ ] worker start is invoked on startup
+- [ ] worker shutdown signal/cleanup is invoked on shutdown
+
+### `tests/ui/test_upload_page.py`
+- [ ] upload action calls upload service
+- [ ] success feedback displayed
+- [ ] error feedback displayed for `UploadError`
+- [ ] loading/progress state behavior covered
+- [ ] timeout/cancellation behavior covered (if implemented)
+
+### `tests/ui/test_jobs_page.py`
+- [ ] list renders job statuses
+- [ ] detail shows transcript text for successful job
+- [ ] detail shows error detail for failed job
+- [ ] refresh/loading state behavior covered
+
+Marker strategy:
+- [ ] `unit` for pure helpers/state formatting
+- [ ] `integration` for app/page/service+DB contracts
+- [ ] `external` not required for default Step 5 lane
+
+Async behavior assertions:
+- [ ] long-running actions keep button/inputs in expected disabled state
+- [ ] completion/failure returns controls to ready state
+
+---
+
+## Validation Sequence (strict)
+
+- [ ] `uv run pytest --collect-only -q`
+- [ ] `uv run pytest -m unit -q` *(if unit tests touched)*
+- [ ] `uv run pytest tests/api/test_health.py -q`
+- [ ] `uv run pytest tests/ui/test_pages_registration.py -q`
+- [ ] `uv run pytest tests/test_app.py -q`
+- [ ] `uv run pytest tests/ui/test_upload_page.py -q`
+- [ ] `uv run pytest tests/ui/test_jobs_page.py -q`
+- [ ] `uv run pytest -q`
+
+---
+
+## Guardrails (NiceGUI + MVP)
+
+- [ ] Do not collapse pages into one file.
+- [ ] Do not use implicit global side effects for runtime wiring.
+- [ ] Keep UI responsive with explicit loading/progress/error states.
+- [ ] Do not block UI handlers with synchronous long I/O.
+- [ ] Do not place provider SDK calls in UI handlers.
+- [ ] Keep dependency direction one-way and maintainable.
+- [ ] Keep shared UI in `ui/components`; keep service logic out of page modules.
+
+---
+
+## Definition of Done
+
+- [ ] App factory + lifespan are in place
+- [ ] Health endpoint exists and is tested
+- [ ] Upload page creates queued jobs through service boundary
+- [ ] Jobs list/detail pages render status/transcript/failure data
+- [ ] Worker lifecycle is started/stopped by app lifespan
+- [ ] Async UI states (loading/success/error) are deterministic and tested
+- [ ] Scaffold->fill testing flow completed and validated
+- [ ] Full suite passes: `uv run pytest -q`
+
+## Completion Checks (NiceGUI skill aligned)
+
+- [ ] Uses app factory and FastAPI lifespan
+- [ ] Pages are modularized (not single-file UI)
+- [ ] Health endpoint exists on FastAPI side
+- [ ] Dependency direction is clean and one-way
+- [ ] Async-first guidance is applied where I/O exists, with explicit non-blocking UX states
+- [ ] DB/AI/docs decisions are explicit and reflected in structure
+- [ ] Plan references baseline URI: `resource://skills/nicegui/document`
+
+---
+
+## PR Checklist (Integrated)
+
+### Implementation
+- [ ] `app.py` app factory + lifespan implemented
+- [ ] FastAPI health route (`/healthz`) implemented
+- [ ] `ui/upload_page.py` implemented
+- [ ] `ui/jobs_page.py` implemented
+- [ ] `ui/__init__.py` explicit page registration implemented
+- [ ] Worker startup/shutdown managed by lifespan
+
+### Testing (MCP-compliant)
+- [ ] Scaffold phase completed first for all Step 5 tests
+- [ ] `--collect-only` passed on scaffolds
+- [ ] Fill phase completed without renaming/re-nesting scaffolded tests
+- [ ] Marker decisions documented (`unit` vs `integration`)
+- [ ] Targeted tests passed
+- [ ] Full suite passed
+
+### Evidence
+- [ ] Validation command outputs captured
+- [ ] Files created/updated listed
+- [ ] MCP prompt resources referenced in implementation notes
+- [ ] Any residual risks/questions documented
+
+---
+

docs/mvp/mvp-step6-results.md

@@ -0,0 +1,50 @@
+Step 6 implemented ✅
+
+### Files added
+- `tests/integration/test_pipeline_flow.py`
+- `tests/test_traceability.py`
+
+### What was implemented
+
+#### 1) End-to-end pipeline integration coverage
+`tests/integration/test_pipeline_flow.py` now verifies:
+
+- **Success path**
+  - upload creates queued job
+  - worker processes job
+  - job becomes `transcribed`
+  - transcript text is persisted
+  - error detail remains `None`
+
+- **Failure path**
+  - upload creates queued job
+  - worker processing failure is handled
+  - job becomes `failed`
+  - transcript has `text=None`
+  - `error_detail` contains provider failure reason
+
+#### 2) MVP requirement traceability check
+`tests/test_traceability.py` adds a concrete map:
+
+- REQ-0, REQ-1, REQ-2, REQ-3, REQ-4, REQ-5, REQ-6, REQ-8, REQ-12
+- each REQ maps to one or more existing test files
+- test asserts each mapped path exists (guards against drift)
+
+---
+
+### Validation run results
+
+Executed and passed:
+
+1. `uv run pytest --collect-only -q` ✅  
+2. `uv run pytest -m unit -q` ✅  
+3. `uv run pytest -m integration -q` ✅  
+4. `uv run pytest -m "not external" -q` ✅  
+5. `uv run pytest tests/integration/test_pipeline_flow.py -q` ✅  
+6. `uv run pytest tests/ui/test_upload_page.py -q` ✅  
+7. `uv run pytest tests/ui/test_jobs_page.py -q` ✅  
+8. `uv run pytest -q` ✅  
+
+All green.  
+(Only existing non-blocking FastAPI TestClient deprecation warning remains.)
+

docs/mvp/mvp-step6.md

@@ -0,0 +1,229 @@
+## Step 6: Test and Verification Hardening (MVP closeout)
+
+## Objective
+
+Complete MVP verification by building a **requirements-traceable, deterministic test strategy** across unit/integration/external lanes, then enforcing stable validation commands and reporting.
+
+This step finalizes the MVP implementation sequence from `docs/mvp.md` (Step 6 in the build order: tests and automated verification).
+
+---
+
+## MCP Resource Integration (what was applied)
+
+I reviewed all top-level skills/prompts from `john-stream-mcp` and integrated the relevant guidance into this plan:
+
+### Directly applied
+- `resource://skills/pytesting/document`
+- `resource://catalog/prompts/pytest-scaffold`
+- `resource://prompts/pytest-scaffold/document`
+- `resource://catalog/prompts/pytest-fill-scaffold`
+- `resource://prompts/pytest-fill-scaffold/document`
+- `resource://skills/nicegui/document`
+- `resource://skills/nicegui-ui-customization/document`
+- `resource://skills/fastapi-uv-docker/document`
+- `resource://skills/python-logging-dictconfig/document`
+- `resource://skills/python-typing/document`
+- `resource://skills/ruff-linting-formating/document`
+
+### Reviewed but informational/non-blocking for Step 6
+- `copilot-customization`, `mcp-details`, `vscode-configuration`, `zensical-docs`, and authoring/shim prompts.
+  - These are primarily customization/documentation tooling resources, not core MVP test-lane blockers.
+  - Step 6 includes optional workflow follow-ups where relevant (e.g., VS Code task conveniences).
+
+---
+
+## Scope
+
+### In scope
+- Strengthen and complete test coverage for the shipped MVP slice (Steps 1–5)
+- Add requirement-to-test traceability for REQ-0..REQ-12 (MVP subset emphasized)
+- Enforce deterministic default lanes (`unit`, `integration`)
+- Keep `external` lane opt-in and isolated
+- Validate app/UI/service/worker contracts end-to-end at test level
+
+### Out of scope
+- Major architecture rewrites (async SQLAlchemy migration, queue system, etc.)
+- Full production deployment rollout
+- Post-MVP feature expansion (revision history, search, export)
+
+---
+
+## Planned Deliverables
+
+### Test files (new/updated)
+- `tests/test_traceability.py` *(or docs-based traceability matrix if preferred)*
+- `tests/integration/test_pipeline_flow.py` *(upload -> queued -> worker -> transcript/failed)*
+- `tests/ui/test_upload_page.py` (augment loading/error/ready-state checks as practical)
+- `tests/ui/test_jobs_page.py` (augment refresh/error behavior checks as practical)
+- Existing tests touched only when needed; preserve naming/hierarchy unless explicitly approved.
+
+### Optional docs output
+- `docs/tests.md` or `docs/verification.md` with lane definitions and command matrix
+- REQ-to-test mapping table
+
+---
+
+## Design and Policy Decisions (MCP-aligned)
+
+1. **Scaffold-first, fill-second workflow is mandatory**
+   - First create/adjust skeletons and collect.
+   - Then fill test bodies.
+   - Preserve scaffold names/docstrings during fill.
+
+2. **Deterministic-first default lanes**
+   - `unit` and `integration` run by default.
+   - `external` remains explicit opt-in.
+
+3. **One behavior target per test**
+   - Short, behavior-focused names.
+   - Precise assertions on observable outcomes.
+
+4. **Test double discipline (from pytesting skill)**
+   - Prefer real-input/real-object paths first.
+   - If monkeypatch/mocks/fakes are needed for a boundary, keep narrowly scoped.
+   - Avoid call-only assertions.
+
+5. **NiceGUI responsiveness expectations**
+   - Verify loading/success/error state transitions where testable.
+   - Ensure user-facing feedback behavior is covered.
+
+6. **FastAPI/ops baseline checks**
+   - Keep `/healthz` route validation in default lanes.
+   - Keep startup/shutdown lifecycle assertions present.
+
+---
+
+## Implementation Plan + Checklist
+
+## Phase A — Coverage and traceability audit
+
+- [ ] Build a REQ-to-test matrix for MVP requirements:
+  - [ ] REQ-0, REQ-1, REQ-2, REQ-3, REQ-4, REQ-5, REQ-6, REQ-8, REQ-12
+- [ ] Identify weak spots:
+  - [ ] full pipeline integration (service + worker + persistence)
+  - [ ] UI state transition assertions (loading/error/ready)
+  - [ ] failure-path persistence verification robustness
+- [ ] Record current baseline command results before edits
+
+## Phase B — Scaffold phase (pytest-scaffold resources)
+
+Target modules/areas:
+- pipeline integration flow
+- UI behavior augmentations
+- traceability checks/document validators (if test-backed)
+
+- [ ] Scaffold new/adjusted test files/classes/methods only
+- [ ] Keep one-line intent docstrings
+- [ ] Keep behavior-focused names
+- [ ] Run: `uv run pytest --collect-only -q`
+
+## Phase C — Fill phase (pytest-fill-scaffold resources)
+
+- [ ] Fill scaffolded methods with deterministic setup/assertions
+- [ ] Preserve scaffold names/hierarchy/docstrings
+- [ ] Add/adjust fixtures at nearest useful scope
+- [ ] Keep DB tests in `integration`; pure helper tests in `unit`
+
+### Required coverage additions
+
+#### Pipeline integration
+- [ ] Upload service creates document/job and file path persists
+- [ ] Worker success path creates transcript and terminal status
+- [ ] Worker failure path persists error detail and terminal failed status
+- [ ] Queue-empty behavior remains stable (`False` return / no side effects)
+
+#### UI behavior (practical, testable boundaries)
+- [ ] Upload helper flow success and UploadError surfacing
+- [ ] Jobs data helpers return stable normalized view models
+- [ ] Refresh/detail fallback behavior for missing/invalid job IDs
+
+#### Traceability
+- [ ] Every in-scope MVP REQ has at least one mapped test/assertion point
+- [ ] Document and/or enforce mapping consistency
+
+## Phase D — External lane stability
+
+- [ ] Keep real-image external tests isolated under `@pytest.mark.external`
+- [ ] Ensure no external test leaks into default runs
+- [ ] Confirm artifact capture behavior remains stable
+
+## Phase E — Quality gates and workflow
+
+- [ ] Confirm logging/lifecycle startup tests still pass after changes
+- [ ] (If enabled) add/update lint/type check commands in docs:
+  - [ ] Ruff lane (if configured)
+  - [ ] typing lane (if configured)
+- [ ] Optionally add VS Code task aliases for test lanes (non-blocking)
+
+---
+
+## Marker and Fixture Strategy
+
+- `unit`: pure logic, helper behavior, formatting/normalization
+- `integration`: DB + service + app lifecycle contracts
+- `external`: live provider/real image checks only
+
+Fixture policy:
+- Prefer reusable fixtures in `tests/conftest.py` only when broadly shared
+- Use subtree/local fixtures for domain-specific setup
+- Keep setup explicit and readable
+
+---
+
+## Validation Sequence (strict)
+
+- [ ] `uv run pytest --collect-only -q`
+- [ ] `uv run pytest -m unit -q`
+- [ ] `uv run pytest -m integration -q`
+- [ ] `uv run pytest -m "not external" -q`
+- [ ] `uv run pytest tests/integration/test_pipeline_flow.py -q` *(if added)*
+- [ ] `uv run pytest tests/ui/test_upload_page.py -q`
+- [ ] `uv run pytest tests/ui/test_jobs_page.py -q`
+- [ ] `uv run pytest -q`
+
+Optional external verification:
+- [ ] `uv run pytest -m external -q`
+
+---
+
+## Guardrails
+
+- Do not rename/re-nest scaffolded tests during fill unless explicitly requested.
+- Do not broaden external dependencies in default lane.
+- Do not add flaky timing-based assertions; keep deterministic boundaries.
+- Keep business logic out of UI tests; test through service/helper boundaries.
+- Preserve one-way dependency direction in test setup patterns.
+
+---
+
+## Definition of Done (Step 6)
+
+- [ ] MVP requirement coverage is explicitly traceable
+- [ ] Deterministic lanes (`unit` + `integration`) are stable and green
+- [ ] External lane remains opt-in and green when enabled
+- [ ] Pipeline success/failure lifecycle paths are verified end-to-end
+- [ ] UI helper/state behavior has explicit success/error assertions
+- [ ] Full suite passes with `uv run pytest -q`
+- [ ] Verification evidence is captured in implementation report
+
+---
+
+## PR Checklist (Step 6)
+
+### Implementation
+- [ ] Added/updated test files per scoped gaps
+- [ ] Added REQ traceability mapping
+- [ ] Kept default lanes deterministic
+- [ ] Preserved scaffold invariants during fill
+
+### Testing (MCP-compliant)
+- [ ] Used scaffold prompt flow first
+- [ ] Used fill prompt flow second
+- [ ] Preserved naming/docstrings/hierarchy
+- [ ] Marker usage documented (`unit`, `integration`, `external`)
+
+### Evidence
+- [ ] Collected command outputs in strict order
+- [ ] Listed files changed
+- [ ] Listed MCP resources used and why
+- [ ] Noted residual risks/open questions (if any)

docs/mvp/mvp-step7-results.md

@@ -0,0 +1,134 @@
+## Step 7 Results: Error Handling Standardization and Operational Visibility
+
+## Summary
+
+Step 7 was implemented across the MVP runtime boundaries with a shared error taxonomy, actionable UI error surfacing, worker failure normalization, and API error envelope handling.
+
+All required validation gates in `docs/step7.md` were executed and passed.
+
+---
+
+## Scope Delivered
+
+### Implemented
+- Shared application error contract and taxonomy
+- Service-layer error normalization (upload + transcription)
+- UI error presentation helpers with suggested actions and error references
+- Worker failure persistence format with category/suggestion/error_id markers
+- API exception handlers for structured error responses
+- Targeted tests for new error contract behavior
+
+### Not implemented in this step
+- External lane execution (`-m external`) was not required for Step 7 completion and was not run in this pass.
+
+---
+
+## Files Added
+
+- `src/transcription/errors.py`
+- `src/transcription/api/errors.py`
+- `src/transcription/ui/error_presenter.py`
+- `tests/test_errors.py`
+- `tests/api/test_error_responses.py`
+- `docs/step7.md`
+
+## Files Updated
+
+- `src/transcription/app.py`
+- `src/transcription/services/upload.py`
+- `src/transcription/services/transcription.py`
+- `src/transcription/ui/upload_page.py`
+- `src/transcription/ui/jobs_page.py`
+- `src/transcription/worker.py`
+- `tests/services/test_upload.py`
+- `tests/services/test_transcription.py`
+- `tests/services/test_worker.py`
+- `tests/integration/test_pipeline_flow.py`
+- `uv.lock`
+
+---
+
+## Implementation Notes by Phase
+
+### Phase A/B (Foundation)
+- Added `ErrorCategory` enum and `AppError` base type in `src/transcription/errors.py`.
+- Added helper utilities:
+  - `new_error_id()`
+  - `build_error_envelope(...)`
+  - `classify_unexpected_error(...)`
+  - `format_error_detail(...)`
+
+### Phase C (Service/Provider normalization)
+- `UploadError` now extends `AppError` and includes category/suggestion/retriable metadata.
+- `PromptLoadError` and `TranscriptionError` now extend `AppError`.
+- Provider failures are mapped with deterministic category semantics (auth/payload/provider-failure cases).
+
+### Phase D (UI visibility)
+- Added `src/transcription/ui/error_presenter.py`.
+- Upload and jobs pages now use centralized UI error rendering and summary helpers.
+- UI error paths now include more visible/actionable guidance and reference IDs.
+
+### Phase E (Worker failure handling)
+- Worker now normalizes exception handling into structured persisted `error_detail` strings with:
+  - category marker
+  - suggestion marker
+  - error_id marker
+- Logging now includes category/error_id context in failure paths.
+
+### Phase F (API envelope)
+- Added `src/transcription/api/errors.py` and registered handlers in app factory.
+- AppError and unexpected exceptions now serialize to stable API envelopes with mapped status codes.
+
+---
+
+## Validation Commands and Outcomes
+
+All commands were executed with `uv run python -m pytest ...` and completed successfully.
+
+1. `uv run python -m pytest tests/test_errors.py -q` ✅
+2. `uv run python -m pytest tests/services/test_upload.py -q` ✅
+3. `uv run python -m pytest tests/services/test_transcription.py -q` ✅
+4. `uv run python -m pytest tests/providers/test_openrouter.py -q` ✅
+5. `uv run python -m pytest tests/services/test_worker.py -q` ✅
+6. `uv run python -m pytest tests/integration/test_pipeline_flow.py -q` ✅
+7. `uv run python -m pytest tests/api/test_error_responses.py -q` ✅
+8. `uv run python -m pytest tests/ui/test_upload_page.py -q` ✅
+9. `uv run python -m pytest tests/ui/test_jobs_page.py -q` ✅
+10. `uv run python -m pytest -m "not external" -q` ✅
+11. `uv run python -m pytest --collect-only -q` ✅
+12. `uv run python -m pytest -m unit -q` ✅
+13. `uv run python -m pytest -m integration -q` ✅
+14. `uv run python -m pytest tests/integration/test_pipeline_flow.py -q` ✅
+15. `uv run python -m pytest tests/ui/test_upload_page.py -q` ✅
+16. `uv run python -m pytest tests/ui/test_jobs_page.py -q` ✅
+17. `uv run python -m pytest -q` ✅
+
+Observed warning (non-blocking): Starlette/FastAPI TestClient deprecation warning related to `httpx` package naming.
+
+---
+
+## Policy Alignment Check (`docs/error_handling.md`)
+
+Aligned items:
+- Stable taxonomy categories are implemented.
+- Unexpected errors are normalized.
+- User-facing UI paths include actionable guidance and references.
+- Worker persistence includes trace-friendly failure detail.
+- API error responses are structured and category-aware.
+
+Follow-up candidates:
+- Add richer UI tests that validate rendered suggested-action content end-to-end (current tests focus helper/service contracts).
+- Consider typed storage fields for error metadata instead of packed `error_detail` strings in a future schema revision.
+
+---
+
+## Step 7 Definition of Done Status
+
+- [x] Shared error taxonomy implemented across MVP layers
+- [x] GUI error paths upgraded for visibility/actionability
+- [x] Worker failure persistence and log context standardized
+- [x] API error envelope handling added and tested
+- [x] Phase-level and full-suite validation gates passed
+- [x] Results documented in this report
+
+Step 7 is complete.

docs/mvp/mvp-step7.md

@@ -0,0 +1,267 @@
+## Step 7: Error Handling Standardization and Operational Visibility
+
+## Objective
+
+Apply the canonical error policy from `docs/error_handling.md` to the MVP implementation so failures are:
+
+- consistently classified
+- visibly surfaced in the GUI
+- paired with suggested corrective actions
+- traceable through logs via error reference IDs
+- validated through deterministic tests after each phase
+
+This step extends MVP hardening by converting current ad hoc exception behavior into a stable cross-layer contract.
+
+---
+
+## Scope
+
+### In scope
+- Introduce a shared application error contract and taxonomy implementation
+- Normalize service/provider exceptions into taxonomy categories
+- Improve GUI error visibility and suggested-action UX
+- Standardize worker failure persistence and logging context
+- Add API error-envelope policy hooks for current/future endpoints
+- Add targeted tests and phase-level/full-suite validation gates
+
+### Out of scope
+- Major architecture rewrites (distributed queue, multi-service decomposition)
+- Post-MVP feature expansion unrelated to error handling
+- Full observability platform rollout (tracing backends, APM)
+
+---
+
+## Policy Source of Truth
+
+- Canonical policy document: `docs/error_handling.md`
+- If implementation and policy diverge, policy is authoritative and code/tests must be updated.
+
+---
+
+## Planned Deliverables
+
+### Runtime code
+- `src/transcription/errors.py` *(new shared contract module)*
+- `src/transcription/ui/error_presenter.py` *(new UI error rendering helper)*
+- Updates to:
+  - `src/transcription/services/upload.py`
+  - `src/transcription/services/transcription.py`
+  - `src/transcription/providers/openrouter.py`
+  - `src/transcription/worker.py`
+  - `src/transcription/ui/upload_page.py`
+  - `src/transcription/ui/jobs_page.py`
+  - `src/transcription/api/*` *(as needed for envelope/handlers)*
+
+### Tests
+- `tests/test_errors.py` *(new shared error contract tests)*
+- updates/additions in:
+  - `tests/services/test_upload.py`
+  - `tests/services/test_transcription.py` *(add if missing)*
+  - `tests/providers/test_openrouter.py`
+  - `tests/services/test_worker.py`
+  - `tests/ui/test_upload_page.py`
+  - `tests/ui/test_jobs_page.py`
+  - `tests/api/test_error_responses.py` *(new, if API handlers added)*
+
+### Documentation
+- Update `docs/error_handling.md` only if implementation reveals policy gaps
+- Capture validation evidence in a Step 7 results artifact (`docs/step7-results.md`)
+
+---
+
+## Design and Policy Decisions
+
+1. **Stable taxonomy contract**
+   - Use policy categories as stable identifiers (`validation_error`, `user_input_error`, etc.).
+
+2. **Actionable UX is mandatory**
+   - User-visible errors must include a suggested course of action.
+
+3. **Traceability by default**
+   - Non-trivial errors include an `error_id` in both logs and user-facing output.
+
+4. **Safe surface / rich logs**
+   - UI/API show safe summaries; logs retain diagnostic detail and traceback.
+
+5. **Deterministic verification cadence**
+   - Targeted tests after each change batch, then phase-level regression gates.
+
+---
+
+## Implementation Plan + Checklist
+
+## Phase A — Baseline Validation and Gap Confirmation
+
+- [ ] Run baseline tests before changes
+- [ ] Record baseline outputs and any known flaky behavior
+- [ ] Confirm current behavior against `docs/error_handling.md` requirements
+
+### Validation gate
+- [ ] `uv run pytest -m "not external" -q`
+- [ ] `uv run pytest -q`
+
+## Phase B — Shared Error Contract Foundation
+
+- [ ] Add `src/transcription/errors.py` with:
+  - [ ] stable category enum
+  - [ ] base `AppError` (category/message/suggestion/error_id/retriable)
+  - [ ] helpers for error-id generation and fallback classification
+- [ ] Keep category names aligned with `docs/error_handling.md`
+
+### Tests
+- [ ] Add `tests/test_errors.py`
+  - [ ] category stability assertions
+  - [ ] error_id creation behavior
+  - [ ] fallback classification for unexpected exceptions
+
+### Validation gate
+- [ ] `uv run pytest tests/test_errors.py -q`
+- [ ] `uv run pytest -m "not external" -q`
+
+## Phase C — Service and Provider Normalization
+
+- [ ] Refactor upload service exceptions to shared taxonomy
+- [ ] Refactor transcription service exceptions to shared taxonomy
+- [ ] Normalize provider adapter failures into deterministic categories
+- [ ] Preserve causal chaining (`raise ... from exc`)
+
+### Tests
+- [ ] Extend `tests/services/test_upload.py`:
+  - [ ] empty payload category/suggestion
+  - [ ] unsupported extension category/suggestion
+  - [ ] persistence failure category mapping
+- [ ] Add/extend `tests/services/test_transcription.py`:
+  - [ ] missing/empty prompt behavior
+  - [ ] unsupported file type behavior
+  - [ ] provider failure mapping behavior
+- [ ] Extend `tests/providers/test_openrouter.py`:
+  - [ ] auth error mapping
+  - [ ] malformed response mapping
+
+### Validation gate
+- [ ] `uv run pytest tests/services/test_upload.py -q`
+- [ ] `uv run pytest tests/services/test_transcription.py -q`
+- [ ] `uv run pytest tests/providers/test_openrouter.py -q`
+- [ ] `uv run pytest -m "not external" -q`
+
+## Phase D — GUI Visibility and Suggested Actions
+
+- [ ] Add `src/transcription/ui/error_presenter.py`
+- [ ] Update upload/jobs pages to use centralized error presentation
+- [ ] Ensure GUI surfaces:
+  - [ ] user-safe message
+  - [ ] suggested action
+  - [ ] error reference ID
+  - [ ] optional technical details panel
+- [ ] Replace raw `str(exc)` UX where policy requires safer messaging
+
+### Tests
+- [ ] Extend `tests/ui/test_upload_page.py` for actionable error UX paths
+- [ ] Extend `tests/ui/test_jobs_page.py` for refresh/detail error guidance
+- [ ] Add `tests/ui/test_error_presenter.py` *(optional but recommended)*
+
+### Validation gate
+- [ ] `uv run pytest tests/ui/test_upload_page.py -q`
+- [ ] `uv run pytest tests/ui/test_jobs_page.py -q`
+- [ ] `uv run pytest -m "not external" -q`
+
+## Phase E — Worker Failure Persistence and Logging Context
+
+- [ ] Update worker failure handling to classify errors before persistence
+- [ ] Ensure failed jobs persist actionable, structured error detail
+- [ ] Add log context fields where available (`error_id`, `category`, `operation`, `job_id`)
+- [ ] Ensure retry semantics are explicit and bounded (or clearly documented as deferred)
+
+### Tests
+- [ ] Extend `tests/services/test_worker.py`:
+  - [ ] missing document failure contract
+  - [ ] provider/transcription failure contract
+  - [ ] persisted error detail includes category/suggestion/error_id markers
+- [ ] Validate integration failure flow in `tests/integration/test_pipeline_flow.py`
+
+### Validation gate
+- [ ] `uv run pytest tests/services/test_worker.py -q`
+- [ ] `uv run pytest tests/integration/test_pipeline_flow.py -q`
+- [ ] `uv run pytest -m "not external" -q`
+
+## Phase F — API Error Envelope Alignment (Current + Future Routes)
+
+- [ ] Add shared API error serialization utilities/handlers (as needed)
+- [ ] Ensure API responses can include:
+  - [ ] `error_id`
+  - [ ] `category`
+  - [ ] `message`
+  - [ ] `suggestion`
+  - [ ] `timestamp`
+- [ ] Map categories to HTTP status guidance from `docs/error_handling.md`
+
+### Tests
+- [ ] Add `tests/api/test_error_responses.py` *(if handlers added)*
+- [ ] Keep `tests/api/test_health.py` passing
+
+### Validation gate
+- [ ] `uv run pytest tests/api/test_error_responses.py -q` *(if added)*
+- [ ] `uv run pytest tests/api/test_health.py -q`
+- [ ] `uv run pytest -m "not external" -q`
+
+## Phase G — Final Regression and Documentation Closure
+
+- [ ] Reconcile implementation details with `docs/error_handling.md`
+- [ ] Update policy doc only where required by confirmed implementation learning
+- [ ] Capture execution evidence in `docs/step7-results.md`
+
+### Final validation sequence (strict)
+- [ ] `uv run pytest --collect-only -q`
+- [ ] `uv run pytest -m unit -q`
+- [ ] `uv run pytest -m integration -q`
+- [ ] `uv run pytest -m "not external" -q`
+- [ ] `uv run pytest tests/integration/test_pipeline_flow.py -q`
+- [ ] `uv run pytest tests/ui/test_upload_page.py -q`
+- [ ] `uv run pytest tests/ui/test_jobs_page.py -q`
+- [ ] `uv run pytest -q`
+
+Optional:
+- [ ] `uv run pytest -m external -q`
+
+---
+
+## Guardrails
+
+- Do not weaken user-facing clarity to expose raw internals.
+- Do not introduce silent exception swallowing.
+- Do not break category-name stability without policy update.
+- Do not merge phase changes without passing that phase validation gate.
+- Keep targeted tests fast and deterministic; isolate external-provider tests under `external`.
+
+---
+
+## Definition of Done (Step 7)
+
+- [ ] Shared error taxonomy is implemented and used across MVP layers
+- [ ] GUI error experiences are visible, actionable, and traceable
+- [ ] Worker persists and logs failure context consistently
+- [ ] API error contract path is aligned for current/future endpoints
+- [ ] Phase-by-phase test gates pass
+- [ ] Full suite remains green (`uv run pytest -q`)
+- [ ] Step 7 results are documented with evidence
+
+---
+
+## PR Checklist (Step 7)
+
+### Implementation
+- [ ] Added shared error contract module
+- [ ] Updated service/provider/worker/UI error handling paths
+- [ ] Added actionable GUI guidance for user-visible failures
+- [ ] Added error reference IDs for traceability
+
+### Testing
+- [ ] Added/updated tests per phase scope
+- [ ] Ran targeted phase tests after each change batch
+- [ ] Ran `not external` regression at each phase boundary
+- [ ] Ran full suite before closeout
+
+### Documentation and Evidence
+- [ ] `docs/error_handling.md` reviewed for alignment
+- [ ] `docs/step7-results.md` includes executed command outputs
+- [ ] Residual risks and deferred items explicitly recorded

docs/mvp/mvp.md

@@ -0,0 +1,209 @@
+## MVP Definition: Historical Document Transcription System
+
+### 1. MVP Objective
+Deliver the thinnest possible end-to-end vertical slice — a user uploads an image of a document, the system transcribes it via the OpenRouter Python SDK, and the user reads the resulting transcript — with just enough persistence and structure to validate the core value proposition: *can AI-driven transcription, guided by curated prompts, produce useful verbatim transcripts of historical family documents?*  
+
+The MVP deliberately defers full-text search, export, revision history, MongoDB, and timeline assembly. These are additive features that don't need validation before the core transcription loop is proven.
+
+---
+
+### 2. Core User Story
+*As a family historian, I can upload a photo of a historical document, wait for it to be transcribed, and read the verbatim transcript — so I can evaluate whether this system will work for my thousands of documents.*
+
+---
+
+### 3. In-Scope Requirements (from ```requirements.md```)  
+
+| Requirement | ID | MVP Rationale |
+| --- |  --- |  --- |
+| End-to-end transcription with lifecycle state | REQ-0 | This is the MVP. |
+| Upload one or more images from the web UI | REQ-1 | Core entry point. MVP supports single-image upload (multi-image is a stretch goal). |
+| Asynchronous processing → transcription or failure | REQ-2 | Validates the AI transcription pipeline. |
+| Persist and expose job states (queued → processing → transcribed/failed) | 	REQ-3 | Minimum feedback loop for the user. |
+| Persist transcription output and failure details | REQ-4 | User must be able to read the result. |
+| UI views for status and transcript reading | REQ-5 | The user needs to see what happened. |
+| Background processing to keep UI responsive | REQ-6 | Essential for usability during long AI calls. |
+| Centralized config and logging at startup | REQ-8 | Small effort, high payoff for debugging. |
+| Store transcription prompts as Markdown files | REQ-12 | Core to the Prompt Curation Policy in intent.md. Start with a single prompt file. |
+
+
+### Deferred to Post-MVP
+| Requirement | ID | Why Deferred |
+| ---  | --- | --- |
+| Lifespan-owned runtime resources (engine, session factory, etc.) | REQ-7 | Important for production robustness, but a simple global or module-level setup is adequate for MVP validation. |
+| Docker Compose (app + PostgreSQL + optional MongoDB) | REQ-9 | MVP runs locally with SQLite to eliminate container overhead during rapid iteration. PostgreSQL migration is Stage 1 hardening. |
+| Explicit, opt-in schema bootstrap | REQ-10 | MVP uses auto-create-tables at startup (SQLModel create_all). Production schema discipline comes after the model stabilizes. |
+| Service-backed persistence for core data | REQ-11 | MVP uses a thin repository layer over SQLite. Full service abstraction follows once the domain model is proven. |
+
+---
+
+### 4. MVP Feature Set
+#### Feature 1: Document Upload (UI)
+* A single NiceGUI page with a file-upload widget (accepts .jpg, .png, .tiff, .pdf).
+* On upload: save the file to a local uploads/ directory, create a Document record, create a Job record with status queued.
+* Minimal metadata capture: original filename, upload timestamp.
+
+#### Feature 2: Asynchronous Transcription Worker
+* An in-process background worker (Python asyncio task or BackgroundTasks) that:
+    1. Picks up queued jobs.
+    2. Transitions status to processing.
+    3. Sends the image + the curated Markdown prompt to an AI vision model via OpenRouter.
+    4. On success: saves the transcript text, transitions to transcribed.
+    5. On failure: saves the error detail, transitions to failed.
+
+#### Feature 3: Transcription Prompt (Markdown Asset)
+* A single Markdown file (prompts/transcribe_document.md) encoding the verbatim transcription rules from intent.md (the Document Issues table, scholarly guidelines, etc.).
+* The worker reads this file at invocation time and injects it as the system/user prompt.
+
+#### Feature 4: Job Status & Transcript Viewer (UI)
+* A job list page showing all jobs with their current status (queued / processing / transcribed / failed).
+* A transcript detail page showing:
+    * The original uploaded image (rendered inline).
+    * The transcription text (or the failure reason).
+    * Timestamp metadata.
+
+#### Feature 5: Minimal Persistence (SQLite + SQLModel)
+* Three tables/models:
+    * Document: id, filename, file_path, uploaded_at.
+    * Job: id, document_id (FK), status, created_at, updated_at.
+    * Transcript: id, job_id (FK), text, error_detail, created_at.
+* SQLite database file stored locally. Auto-created on first startup.
+
+#### Feature 6: Centralized Configuration
+* A single config.py (or Pydantic BaseSettings) loading:
+    * PROVIDER (fixed to openrouter for MVP)
+    * OPENROUTER_API_KEY (required)
+    * PROVIDER_MODEL (default: OpenRouter model slug for vision transcription)
+    * OPENROUTER_HTTP_REFERER (optional; app attribution)
+    * OPENROUTER_APP_TITLE (optional; app attribution)
+    * DATABASE_URL (default: sqlite:///./transcription.db)
+    * UPLOAD_DIR (default: ./uploads)
+    * PROMPT_DIR (default: ./prompts)
+
+#### Feature 7: MVP Dependency Baseline (OpenRouter-Centric)
+* Runtime dependencies:
+    * openrouter (official OpenRouter Python SDK)
+    * pydantic
+    * pydantic-settings
+    * sqlmodel
+* Explicitly out of MVP runtime dependencies:
+    * google-genai (deferred until/if Gemini is introduced post-MVP)
+
+---
+
+### 5. MVP Architecture (Simplified)
+
+```Apply
+┌─────────────────────────────────────────────┐
+│              NiceGUI Web UI                 │
+│  ┌──────────────┐   ┌───────────────────┐   │
+│  │ Upload Page  │   │ Jobs / Transcript │   │
+│  └──────┬───────┘   └───────┬───────────┘   │
+│         │                   │               │
+│         ▼                   ▼               │
+│     ┌───────────────────────────┐           │
+│     │   Application Service     │           │
+│     │  (upload, job lifecycle)  │           │
+│     └─────┬─────────────┬───────┘           │
+│           │             │                   │
+│     ┌─────▼─────┐ ┌─────▼───────────────┐   │
+│     │ SQLite DB │ │ Background Worker   │   │
+│     │ (SQLModel)│ │ → AI Vision Provider│   │
+│     └───────────┘ └─────────────────────┘   │
+│                          │                  │
+│                    ┌─────▼──────┐           │
+│                    │ prompts/   │           │
+│                    │ *.md files │           │
+│                    └────────────┘           │
+└─────────────────────────────────────────────┘
+```
+
+---
+
+#### 6. Proposed File Structure
+
+```Apply
+project-root/
+├── docs/                          # (existing)
+├── prompts/
+│   └── transcribe_document.md     # curated transcription prompt
+├── src/
+│   └── transcription/
+│       ├── __init__.py
+│       ├── app.py                 # FastAPI + NiceGUI app entrypoint
+│       ├── config.py              # Pydantic BaseSettings
+│       ├── models.py              # SQLModel: Document, Job, Transcript
+│       ├── db.py                  # engine, session, create_all
+│       ├── providers/
+│       │   ├── __init__.py
+│       │   ├── base.py            # provider interface (transcribe contract)
+│       │   ├── openrouter.py      # OpenRouter via official Python SDK
+│       ├── services/
+│       │   ├── __init__.py
+│       │   ├── upload.py          # save file + create records
+│       │   └── transcription.py   # call provider, update job
+│       ├── worker.py              # background job loop
+│       └── ui/
+│           ├── __init__.py
+│           ├── upload_page.py     # NiceGUI upload page
+│           └── jobs_page.py       # NiceGUI job list + detail
+├── tests/
+│   ├── test_models.py
+│   ├── test_upload.py
+│   └── test_transcription.py
+├── pyproject.toml
+└── README.md
+```
+
+---
+
+#### 7. MVP Validation Criteria
+The MVP is considered validated when:
+
+1. ✅ A user can upload an image of a document through the browser.
+2. ✅ The system asynchronously sends the image to the configured AI vision model with the curated prompt.
+3. ✅ The transcript (or failure reason) is persisted and visible in the UI.
+4. ✅ The transcription follows verbatim scholarly rules defined in intent.md (spot-checked by the user on real family documents).
+5. ✅ The transcription prompt is stored as a standalone Markdown file and can be edited without code changes.
+6. ✅ Job status transitions are visible: queued → processing → transcribed/failed.
+
+---
+
+### 8. Key Feedback Questions the MVP Should Answer
+These are the real unknowns this MVP exists to resolve:
+
+| #	| Question | How We Learn |
+| --- | --- | --- |
+| 1	| Is AI transcription quality good enough for this document corpus?	| User reviews 20–50 real transcriptions against originals. |
+| 2	| Does the verbatim prompt produce scholarly-quality output, or does it need major rework?	| Compare output to the Document Issues table rules in intent.md. |
+| 3	| What document types are hardest (old cursive, faded ink, pencil, postcards)?	| Track which uploads produce failed or low-quality results. |
+| 4	| Is single-image upload sufficient, or is batch upload needed early?	| User friction during real scanning sessions. |
+| 5	| What metadata is missing that the user wishes they could capture at upload time?	| User feedback after processing real batches. |
+
+---
+
+#### 9. What Comes After MVP (Immediate Post-MVP)
+Once the core transcription loop is validated, the next priorities (aligned to Architecture Stage 1) are:
+
+1. **Multi-image upload** — process a batch from a scanning session.
+2. **PostgreSQL migration** — swap SQLite for containerized PostgreSQL (REQ-9, REQ-10).
+3. **Revision history** — allow the user to edit/correct transcripts with immutable version tracking.
+4. **Full-text search** — search across all accepted transcripts.
+5. **Repository/service layer formalization** — proper ports/adapters as the domain model stabilizes.
+6. **Docker Compose deployment** — containerize the app for reproducible operation.
+
+---
+
+#### 10. Implementation Approach
+Recommended build order for the MVP (each step produces a testable increment):
+
+| Step | Deliverable | Validates |
+| --- | --- | --- |
+| 1 | config.py + models.py + db.py — data layer with SQLite | Schema and config foundation |
+| 2 | prompts/transcribe_document.md — curated prompt from intent.md | Prompt asset pattern |
+| 3 | services/transcription.py + providers/ — call AI vision provider with prompt + image | Core AI integration |
+| 4 | services/upload.py + worker.py — upload handling + background job loop | End-to-end pipeline (CLI-testable) |
+| 5 | ui/upload_page.py + ui/jobs_page.py — NiceGUI pages | User-facing interface |
+| 6 | tests/ — unit + integration tests	Automated verification |
+
+This MVP is deliberately narrow: **one prompt, one provider (OpenRouter), one user, one image at a time, SQLite, no containers**. Every omission is intentional — the goal is to get real family documents through the transcription pipeline as fast as possible and let the quality of the output guide every subsequent decision.

docs/requirements.md

@@ -0,0 +1,84 @@
+## Document Transcription System Requirements
+
+This page captures a SysML v1.6-style requirements baseline for the production system described in [index.md](index.md). The model is represented as concise tables and traceability lists that preserve SysML-style IDs and relationship semantics.
+
+## Scope
+
+- System of interest: the single Python application service (NiceGUI + FastAPI) with PostgreSQL as the relational system of record and optional MongoDB for document-oriented persistence.
+- Operational context: local-first execution with Docker Compose and an intentionally lightweight production trajectory.
+- Primary concern: end-to-end transcription job lifecycle from upload through completion or failure.
+
+## Requirements Model (Concise Text Form)
+
+### Requirements
+
+| ID | Category | Requirement | Risk | Verify Method |
+| --- | --- | --- | --- | --- |
+| REQ-0 | System | Provide end-to-end document transcription with persistent, inspectable lifecycle state. | medium | demonstration |
+| REQ-1 | Functional | Allow users to upload one or more document images from the web UI. | low | test |
+| REQ-2 | Functional | Run each upload through asynchronous processing that returns a transcription or explicit failure. | high | test |
+| REQ-3 | Functional | Persist and expose job states: upload, queued, processing, transcribed, failed, completed. | high | inspection |
+| REQ-4 | Functional | Persist transcription output, processing history, and failure details. | medium | test |
+| REQ-5 | Interface | Expose API and UI views for status inspection and completed transcription reading. | medium | demonstration |
+| REQ-6 | Performance | Trigger background processing on upload to preserve UI responsiveness. | medium | analysis |
+| REQ-7 | Design Constraint | Keep lifespan-owned runtime resources: SQLAlchemy engine, async session factory, worker resources, provider clients. | medium | inspection |
+| REQ-8 | Design Constraint | Initialize configuration and logging once at startup through centralized mechanisms. | low | inspection |
+| REQ-9 | Design Constraint | Use Docker Compose baseline of app plus PostgreSQL; allow optional MongoDB container when enabled. | medium | demonstration |
+| REQ-10 | Design Constraint | Keep schema bootstrap explicit and opt-in; normal startup does not mutate production schema. | high | inspection |
+| REQ-11 | Design Constraint | Use service-backed persistence for core document and job data. | medium | inspection |
+| REQ-12 | Design Constraint | Store transcription prompts as individual Markdown artifacts for iterative refinement. | medium | inspection |
+
+### Requirement Relationships
+
+- Contains: REQ-0 contains REQ-1 through REQ-12.
+- Derives: REQ-2 -> REQ-3, REQ-3 -> REQ-4.
+- Traces: REQ-5 -> REQ-3.
+- Refines: REQ-6 -> REQ-2.
+
+### Architecture Elements
+
+| Element | Type | Doc Reference |
+| --- | --- | --- |
+| UI | NiceGUI pages | src/transcription/ui/pages |
+| API | FastAPI routes | src/transcription/api/routes.py |
+| GRAPH | Async processing workflow | src/transcription/services, src/transcription/ai |
+| DBREL | PostgreSQL + SQLModel relational persistence | src/transcription/db |
+| DBDOC | MongoDB document persistence | src/transcription/db, src/transcription/services |
+| OPS | Docker Compose runtime | docker-compose.yml |
+| PROMPTS | Transcription prompt artifact library (Markdown files) | .github/prompts, docs |
+| TESTS | Pytest verification suite | tests |
+
+### Satisfaction Mapping
+
+- UI satisfies REQ-1, REQ-5.
+- API satisfies REQ-5.
+- GRAPH satisfies REQ-2, REQ-6.
+- DBREL satisfies REQ-3, REQ-10.
+- DBDOC satisfies REQ-4, REQ-11.
+- OPS satisfies REQ-9.
+- PROMPTS satisfies REQ-12.
+
+### Verification Mapping
+
+- TESTS verifies REQ-1, REQ-2, REQ-3, REQ-4, REQ-5, REQ-10, REQ-11, REQ-12.
+
+## Requirement Notes
+
+- Requirement IDs (`REQ-*`) are stable references for planning, implementation, and test traceability.
+- The model uses compact tables and traceability lists for renderer compatibility while preserving SysML-style requirement IDs and relationship semantics.
+- Requirement categories (functional, interface, performance, and design constraints) are preserved as explicit REQ entries and relationship labels to keep change impact visible.
+- PostgreSQL containerization and optional MongoDB containerization are both treated as extremely lightweight and simple operational choices in this architecture.
+
+## Verification Intent
+
+- Demonstration: validate end-to-end behavior via running system flows and operator-visible outcomes.
+- Inspection: verify architecture and startup/runtime policies in code and configuration.
+- Analysis: evaluate asynchronous execution behavior and design sufficiency.
+- Test: automate behavioral checks through pytest suites and service-level tests.
+
+## Glossary
+
+- Document-oriented persistence: A storage approach that uses flexible document structures for variable data shapes.
+- Prompt artifact: A single Markdown file that defines one transcription prompt and is revised independently.
+- SysML: Systems Modeling Language used to express structured requirements and traceability.
+- System of record: The authoritative persistent store for canonical business data.

docs/ver1/ver1.md

@@ -0,0 +1,320 @@
+# Version 1 Implementation Plan
+
+This plan defines the path from MVP to **Version 1 complete**.  
+The objective is to deliver the full scoped product with production readiness, while explicitly separating refinements/enhancements into a future document.
+
+---
+
+## 0) Plan Governance & Scope Control (Foundation)
+
+**Goal:** Keep execution focused on V1 completion, not optimization/perfection.
+
+### Implementation Steps
+1. Create and maintain a **V1 Traceability Matrix**:
+   - Requirement ID
+   - Current status (`done`, `partial`, `not started`)
+   - Owner
+   - Validation method
+2. Define V1 completion gates:
+   - Functional complete
+   - Operationally complete
+   - Production-ready complete
+3. Snapshot the MVP baseline (tag/changelog reference).
+4. Create a standing rule: any non-V1 idea is logged to a separate enhancements backlog document (to be named later), not added to active V1 scope unless explicitly approved.
+
+### Deliverables
+- `docs/ver1/ver1.md` (this plan)
+- V1 traceability artifact (linked from here when created)
+
+### Exit Criteria
+- Every in-scope requirement has explicit ownership and status.
+- Scope-change process is agreed and followed.
+
+---
+
+## 1) Architecture Consolidation
+
+**Goal:** Align implementation with the intended architecture and reduce MVP shortcuts.
+
+### Implementation Steps
+1. Compare implemented modules/components with architecture documentation.
+2. Identify and classify architectural debt:
+   - Temporary coupling
+   - Missing interfaces
+   - Placeholder services/components
+3. Resolve high-risk architectural gaps first.
+4. Record key decisions and tradeoffs in ADRs.
+
+### Deliverables
+- Updated architecture diagrams and boundaries
+- ADR entries for major decisions
+
+### Exit Criteria
+- Architecture documentation reflects system reality.
+- Critical architecture risks are addressed or scheduled with owners/dates.
+
+---
+
+## 2) Error Handling & Reliability Hardening
+
+**Goal:** Ensure predictable, safe behavior under failure conditions.
+
+### Implementation Steps
+1. Standardize error taxonomy and envelope format across all layers.
+2. Ensure clear distinction between:
+   - User-facing errors
+   - Internal/system errors
+   - Retryable vs non-retryable failures
+3. Add resilience controls where needed:
+   - Timeouts
+   - Retries with backoff
+   - Circuit breaking / fallback logic
+4. Add failure-path tests for critical workflows.
+
+### Deliverables
+- Error code catalog/reference
+- Failure mode test coverage for critical paths
+
+### Exit Criteria
+- Error behavior is consistent across major flows.
+- Known failure scenarios are tested and pass.
+
+---
+
+## 3) Functional Completion by Requirement Domain
+
+**Goal:** Complete all V1 functional requirements in a risk-aware order.
+
+### Recommended Order
+1. Business-critical end-user flows
+2. Data integrity and consistency capabilities
+3. Admin/operational controls
+4. Lower-priority UX and quality-of-life items that are in V1 scope
+
+### Implementation Steps
+For each requirement slice:
+1. Finalize contract/schema
+2. Implement domain logic
+3. Implement persistence/state changes
+4. Integrate API/UI
+5. Add automated tests
+6. Update docs
+
+### Deliverables
+- Requirement completion report with validation evidence
+
+### Exit Criteria
+- All V1 “must-have” requirements are complete and validated.
+
+---
+
+## 4) Data Model, Migration, and Backfill Safety
+
+**Goal:** Ensure data model and migrations are production-safe.
+
+### Implementation Steps
+1. Validate schema against final V1 domain needs.
+2. Implement forward-safe migrations.
+3. Define rollback/mitigation plans for migration failures.
+4. Build and verify backfill scripts (if needed).
+5. Add migration rehearsal in staging with representative data.
+
+### Deliverables
+- Migration runbook
+- Backfill verification checklist
+
+### Exit Criteria
+- Migration plan validated in staging.
+- No unresolved data-loss risk for V1 rollout.
+
+---
+
+## 5) Security, Access Control, and Compliance Baseline
+
+**Goal:** Close MVP security gaps and establish V1 baseline controls.
+
+### Implementation Steps
+1. Complete authn/authz coverage for all routes/actions.
+2. Enforce input validation and output sanitization.
+3. Verify secret management and credential rotation process.
+4. Add audit logging for sensitive operations.
+5. Run dependency/security scanning in CI and remediate findings.
+
+### Deliverables
+- Security checklist with status
+- Threat/risk update for V1 scope
+
+### Exit Criteria
+- No unresolved critical/high vulnerabilities for V1 launch.
+- Access control behavior verified by tests.
+
+---
+
+## 6) Observability & Operability
+
+**Goal:** Make system behavior observable and supportable in production.
+
+### Implementation Steps
+1. Standardize structured logging and correlation IDs.
+2. Add core metrics:
+   - Latency
+   - Throughput
+   - Error rates
+   - Resource saturation
+3. Add tracing for critical request/workflow paths.
+4. Define SLOs/SLIs and alert thresholds.
+5. Prepare incident response and rollback runbooks.
+
+### Deliverables
+- Dashboards and alerts
+- Operations runbooks
+
+### Exit Criteria
+- Team can detect, triage, and remediate incidents quickly.
+- Core production signals are available and reliable.
+
+---
+
+## 7) Test Strategy Expansion & Quality Gates
+
+**Goal:** Raise confidence for repeatable, low-risk releases.
+
+### Implementation Steps
+1. Expand unit and integration tests across V1 features.
+2. Add contract tests between key components/services.
+3. Add end-to-end tests for critical user journeys.
+4. Add non-functional tests where relevant:
+   - Performance/load
+   - Soak
+   - Failure-injection scenarios
+5. Enforce CI quality gates (tests, lint, type checks, security scans).
+
+### Deliverables
+- Test matrix with ownership
+- CI gate definition and thresholds
+
+### Exit Criteria
+- Critical-path regressions are blocked automatically.
+- Test coverage and reliability thresholds meet V1 targets.
+
+---
+
+## 8) Performance & Scalability Validation
+
+**Goal:** Meet expected V1 performance at projected load.
+
+### Implementation Steps
+1. Define performance budgets per key flow.
+2. Benchmark current behavior in staging.
+3. Optimize bottlenecks (queries, caching, concurrency, etc.).
+4. Re-test after each optimization and compare against budget.
+5. Document known limits and safe operating bounds.
+
+### Deliverables
+- Performance benchmark report
+- Optimization log
+
+### Exit Criteria
+- V1 performance targets met for expected usage profile.
+
+---
+
+## 9) Release Engineering & Environment Readiness
+
+**Goal:** Make deployment repeatable, controlled, and reversible.
+
+### Implementation Steps
+1. Harden CI/CD pipeline with clear promotion gates.
+2. Ensure config parity and consistency across environments.
+3. Define rollout strategy (phased/canary/limited release as applicable).
+4. Validate rollback procedures in staging.
+5. Produce release checklist and ownership model.
+
+### Deliverables
+- Release playbook
+- Environment readiness checklist
+
+### Exit Criteria
+- Deployment and rollback are rehearsed and reliable.
+- Release process is executable without tribal knowledge.
+
+---
+
+## 10) Documentation Completion
+
+**Goal:** Ensure V1 can be built, operated, and supported from documentation.
+
+### Implementation Steps
+1. Update core project docs to match final V1 behavior:
+   - Architecture
+   - Error handling
+   - Requirements status
+   - Index/navigation
+   - Intent alignment summary
+2. Add operator troubleshooting guides.
+3. Add integration/API examples for consumers.
+4. Publish changelog/version notes for V1.
+
+### Deliverables
+- Updated documentation set for V1
+- V1 release notes
+
+### Exit Criteria
+- A new team member can run/support the system using docs alone.
+
+---
+
+## 11) Final Validation, UAT, and Launch
+
+**Goal:** Confirm readiness and launch V1 safely.
+
+### Implementation Steps
+1. Run full-system acceptance validation against the V1 traceability matrix.
+2. Conduct stakeholder UAT and capture sign-off.
+3. Execute production readiness review.
+4. Launch in controlled phases and monitor key signals.
+
+### Deliverables
+- UAT/PRR sign-off records
+- Launch checklist and monitoring plan
+
+### Exit Criteria
+- Stakeholder approval achieved.
+- Launch metrics are stable within defined thresholds.
+
+---
+
+## 12) Post-Launch Stabilization (30–60 Days)
+
+**Goal:** Consolidate V1 in production before major expansion.
+
+### Implementation Steps
+1. Track incidents, defects, and user feedback.
+2. Prioritize stabilization fixes with short cycle times.
+3. Remove temporary flags/mitigations introduced during launch.
+4. Produce post-launch retrospective and handoff to standard roadmap cadence.
+
+### Deliverables
+- Stabilization report
+- Prioritized backlog update
+
+### Exit Criteria
+- Incident/error rates converge to steady-state targets.
+- V1 transitions from launch mode to normal operations.
+
+---
+
+## Recommended Execution Rhythm
+
+- **Weekly:** Requirement closure + risk review
+- **Biweekly:** Release train with quality gates
+- **Milestone reviews:** After phases 2, 6, 9, and 11
+
+---
+
+## Scope Discipline Rule (V1 Focus)
+
+To preserve delivery focus:
+- V1 execution prioritizes completion of scoped requirements.
+- Refinements/enhancements are captured in a separate future document and backlog.
+- Only explicitly approved scope changes may enter this plan.

hello.py

@@ -1,6 +0,0 @@
-def main():
-    print("Hello from transcription!")
-
-
-if __name__ == "__main__":
-    main()

prompts/README.md

@@ -0,0 +1,13 @@
+# Prompt Artifacts
+
+This directory stores transcription prompts as individual Markdown artifacts.
+
+## Conventions
+- Keep one prompt per file.
+- Use stable, descriptive snake_case file names.
+- Prefer incremental edits to a single prompt per change for clean history.
+- Keep prompts human-readable and policy-focused.
+- Do not store secrets in prompt files.
+
+## Current Prompt
+- `transcribe_document.md`: baseline verbatim transcription policy for historical documents.

prompts/system.txt

@@ -0,0 +1,10 @@
+You are an assistant that may call tools.
+
+Tool safety rules:
+1) Tool arguments MUST be strict JSON matching the schema exactly.
+2) Never place disallowed, sensitive, explicit, or policy-violating text directly into tool arguments.
+3) If user content may be unsafe, first produce a brief neutral summary and pass only that summary.
+4) Prefer IDs, enums, booleans, and short fields over raw free-form text.
+5) Keep all string arguments <= 300 chars unless schema says otherwise.
+6) If you cannot safely provide valid tool args, do not call the tool; respond with "NO_TOOL_CALL" and explain briefly.
+7) Never include markdown/code fences in tool arguments.

prompts/transcribe_document.md

@@ -0,0 +1,72 @@
+# Historical Document Verbatim Transcription Prompt
+
+## Purpose
+Transcribe the provided historical document image as a faithful **verbatim** transcript.
+Do not summarize. Do not paraphrase. Do not modernize style.
+
+## Output Contract
+- Return only the transcription text.
+- Preserve original wording, punctuation, and meaningful structure.
+- Keep line/section flow readable while preserving intent and document organization.
+- Never invent missing content.
+
+## Rules for Ambiguous or Damaged Text
+
+### Misspellings and original errors
+- Preserve original spelling.
+- Add `[sic]` immediately after an evident original error.
+
+### Missing words or clear omissions
+- If a single missing word is obvious from context, insert it in square brackets.
+- Example form: `[to]`
+
+### Uncertain readings
+- If best-effort interpretation is uncertain, use bracketed guess with question mark.
+- Example form: `[Boston?]`
+
+### Completely illegible text
+- Use a clear bracketed label.
+- Preferred forms: `[illegible]`, `[torn]`, `[ink blot]`, `[remainder of page torn]`
+
+### Crossed-out text
+- Preserve it using: `[deleted: ...]`
+
+### Squeezed-in or above-line insertions
+- Preserve it using: `[inserted: ...]`
+
+### Superscripts and abbreviations
+- Bring superscript letters down to baseline text.
+- Expand only when clearly intended; if expanded, place added letters in brackets.
+
+### Non-text visual elements
+- Describe briefly in square brackets.
+- Example forms: `[wax notary seal attached here]`, `[sketch of a fort layout]`
+
+### Marginalia and side notes
+- Signal location before the note text.
+- Example form: `[written in left margin: ...]`
+
+### Line-break hyphenation
+- Rejoin words split across line breaks when they are clearly one word.
+- Remove only line-break hyphens used for wrapping.
+
+### Ambiguous capitalization
+- Prefer modern capitalization only when uncertainty is high.
+- Preserve clearly intentional archaic capitalization.
+
+### Hierarchical outlines and numbering
+- Preserve original numbering characters exactly (including roman numerals and unusual suffixes).
+- Preserve indentation levels.
+- Do not silently correct sequence mistakes; if clearly erroneous, preserve and use `[sic]` where appropriate.
+
+## Confidence and Integrity Policy
+- When uncertain, mark uncertainty explicitly rather than guessing silently.
+- If text cannot be read, use a bracketed illegibility label instead of fabrication.
+- Do not add commentary outside the transcription.
+
+## Final Self-Check
+Before finalizing, ensure:
+1. The transcript is verbatim and not summarized.
+2. Uncertain/illegible areas are explicitly marked.
+3. Crossed-out and inserted text are preserved with required tags.
+4. Structure/ordering is preserved as faithfully as possible.

pyproject.toml

@@ -1,10 +1,46 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/transcription"]
+
 [project]
 name = "transcription"
 version = "0.1.0"
-description = "Add your description here"
+description = "Historical document transcription system"
 readme = "README.md"
 requires-python = ">=3.12"
 dependencies = [
-    "openai>=2.43.0",
+    "aiosqlite>=0.21.0",
+    "asyncpg>=0.31.0",
+    "fastapi>=0.138.0",
+    "nicegui==3.13.0",
+    "openrouter>=0.7.0",
+    "psycopg2-binary>=2.9.12",
     "pydantic>=2.13.4",
+    "pydantic-settings>=2.9.1",
+    "sqlmodel>=0.0.25",
+]
+
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.25",
+    "httpx2>=2.5.0",
+    "ipykernel>=7.3.0",
+    "ipywidgets>=8.1.8",
+    "pre-commit>=4.6.0",
+    "rich>=15.0.0",
+    "ruff>=0.15.20",
+    "ty>=0.0.54",
+]
+
+[tool.pytest.ini_options]
+addopts = "--strict-markers -q"
+markers = [
+    "unit: pure logic tests with no external dependencies",
+    "integration: tests that touch framework or database contracts",
+    "external: tests that call external services (slow, requires credentials)",
 ]

ruff.toml

@@ -0,0 +1,62 @@
+line-length = 120
+indent-width = 4
+target-version = "py313"
+
+exclude = [
+    ".venv",
+    ".devenv",
+    ".git",
+    ".vscode",
+    "build",
+    "site",
+    "__pycache__",
+]
+
+[lint]
+preview = true
+
+extend-select = [
+    "ARG",      # https://docs.astral.sh/ruff/rules/#flake8-unused-arguments-arg
+	"B",        # https://docs.astral.sh/ruff/rules/#flake8-bugbear-b
+	"C4",       # https://docs.astral.sh/ruff/rules/#flake8-comprehensions-c4
+    "DOC102",   # https://docs.astral.sh/ruff/rules/docstring-extraneous-parameter/
+    "DOC202",   # https://docs.astral.sh/ruff/rules/docstring-extraneous-returns/
+    "DOC403",   # https://docs.astral.sh/ruff/rules/docstring-extraneous-yields/
+    "DOC502",   # https://docs.astral.sh/ruff/rules/docstring-extraneous-exception/
+	"E", "W",   # https://docs.astral.sh/ruff/rules/#pycodestyle-e-w
+	"F",        # https://docs.astral.sh/ruff/rules/#pyflakes-f
+    "FURB",     # https://docs.astral.sh/ruff/rules/#refurb-furb
+	"I",        # https://docs.astral.sh/ruff/rules/#isort-i
+    "N",        # https://docs.astral.sh/ruff/rules/#pep8-naming-n
+    "PD",       # https://docs.astral.sh/ruff/rules/#pandas-vet-pd
+    "PTH",      # https://docs.astral.sh/ruff/rules/#flake8-use-pathlib-pth
+	"UP",       # https://docs.astral.sh/ruff/rules/#pyupgrade-up
+	"SIM",      # https://docs.astral.sh/ruff/rules/#flake8-simplify-sim
+    "PLR0202",  # https://docs.astral.sh/ruff/rules/no-classmethod-decorator/
+    "PLR0203",  # https://docs.astral.sh/ruff/rules/no-staticmethod-decorator/
+    "PLR0206",  # https://docs.astral.sh/ruff/rules/property-with-parameters/
+    "PLR0915",  # https://docs.astral.sh/ruff/rules/too-many-statements/
+    "PLR1702",  # https://docs.astral.sh/ruff/rules/too-many-nested-blocks/
+    "TRY002",
+]
+extend-fixable = ["ALL"]
+ignore = [
+    "UP046",
+    "UP047",
+]
+
+[lint.extend-per-file-ignores]
+"*.ipynb" = [
+    "F401", # unused imports
+    "F841", # unused local variable
+    "F821", # undefined name in exploratory notebook cells
+]
+
+[lint.isort]
+force-single-line = true
+
+[format]
+quote-style = "double"
+indent-style = "space"
+skip-magic-trailing-comma = false
+line-ending = "auto"

src/transcription/api/__init__.py

@@ -0,0 +1 @@
+"""API route modules for the transcription app."""

src/transcription/api/errors.py

@@ -0,0 +1,56 @@
+"""Centralized API exception handlers."""
+
+from __future__ import annotations
+
+import logging
+
+from fastapi import FastAPI
+from fastapi import Request
+from fastapi.responses import JSONResponse
+
+from transcription.errors import AppError
+from transcription.errors import ErrorCategory
+from transcription.errors import build_error_envelope
+
+logger = logging.getLogger(__name__)
+
+
+_STATUS_BY_CATEGORY: dict[ErrorCategory, int] = {
+    ErrorCategory.VALIDATION: 400,
+    ErrorCategory.USER_INPUT: 400,
+    ErrorCategory.NOT_FOUND: 404,
+    ErrorCategory.CONFLICT: 409,
+    ErrorCategory.EXTERNAL_PROVIDER: 503,
+    ErrorCategory.INFRA_TRANSIENT: 503,
+    ErrorCategory.INFRA_PERSISTENT: 500,
+    ErrorCategory.INTERNAL_UNEXPECTED: 500,
+}
+
+
+def _status_for(error: AppError) -> int:
+    return _STATUS_BY_CATEGORY.get(error.category, 500)
+
+
+def register_error_handlers(app: FastAPI) -> None:
+    """Register API exception handlers on the app."""
+
+    @app.exception_handler(AppError)
+    async def app_error_handler(_request: Request, exc: AppError) -> JSONResponse:
+        envelope = build_error_envelope(exc)
+        return JSONResponse(status_code=_status_for(exc), content=envelope.__dict__)
+
+    @app.exception_handler(Exception)
+    async def fallback_error_handler(_request: Request, exc: Exception) -> JSONResponse:
+        normalized = AppError(
+            "Unexpected error while handling request",
+            category=ErrorCategory.INTERNAL_UNEXPECTED,
+            suggestion="Retry once. If it persists, report the error reference id.",
+        )
+        logger.exception(
+            "Unhandled API exception operation=api.request error_id=%s category=%s exception_type=%s",
+            normalized.error_id,
+            normalized.category.value,
+            type(exc).__name__,
+        )
+        envelope = build_error_envelope(normalized)
+        return JSONResponse(status_code=_status_for(normalized), content=envelope.__dict__)

src/transcription/api/health.py

@@ -0,0 +1,16 @@
+"""Health endpoint routes."""
+
+from fastapi import APIRouter
+
+router = APIRouter()
+
+
+def healthz() -> dict[str, str]:
+    """Return a simple health status payload."""
+    return {"status": "ok"}
+
+
+@router.get("/healthz")
+def healthz_route() -> dict[str, str]:
+    """Route wrapper for health status payload."""
+    return healthz()

src/transcription/app.py

@@ -0,0 +1,67 @@
+"""Application factory and lifespan wiring for the transcription app."""
+
+from __future__ import annotations
+
+from contextlib import AsyncExitStack
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from fastapi import status
+from fastapi.responses import RedirectResponse
+
+from .api.errors import register_error_handlers
+from .api.health import router as health_router
+from .config import configure_logging
+from .config import get_settings
+from .db import create_all
+from .db import dispose_database_runtime
+from .db import initialize_database_runtime
+from .services import ServiceBundle
+from .ui import register_pages
+from .worker import worker_consumer_lifespan
+
+
+@asynccontextmanager
+async def _lifespan(app: FastAPI):
+    configure_logging()
+
+    settings = get_settings()
+    app.state.settings = settings
+    app.state.services = ServiceBundle()
+    app.state.runtime = initialize_database_runtime(settings=settings)
+
+    if settings.should_bootstrap_schema:
+        await create_all(engine=app.state.runtime.engine)
+
+    settings.upload_dir.mkdir(parents=True, exist_ok=True)
+    settings.prompt_dir.mkdir(parents=True, exist_ok=True)
+
+    async with AsyncExitStack() as stack:
+        stack.push_async_callback(dispose_database_runtime)
+        stop_event, worker_notifier = await stack.enter_async_context(
+            worker_consumer_lifespan(
+                session_factory=app.state.runtime.session_factory,
+                poll_interval_seconds=1.0,
+            )
+        )
+        app.state.worker_stop_event = stop_event
+        app.state.worker_notifier = worker_notifier
+        yield
+
+
+def create_app() -> FastAPI:
+    """Create and configure the FastAPI application."""
+    app = FastAPI(title="Transcription", lifespan=_lifespan)
+
+    @app.get("/", include_in_schema=False)
+    async def root_redirect() -> RedirectResponse:
+        return RedirectResponse(url="/ui", status_code=status.HTTP_307_TEMPORARY_REDIRECT)
+
+    @app.get("/ui", include_in_schema=False)
+    async def ui_redirect() -> RedirectResponse:
+        return RedirectResponse(url="/ui/upload", status_code=status.HTTP_307_TEMPORARY_REDIRECT)
+
+    register_error_handlers(app)
+    register_pages(app)
+    app.include_router(health_router)
+    return app

src/transcription/app_state.py

@@ -0,0 +1,39 @@
+"""Helpers for accessing lifespan-owned application state resources."""
+
+from __future__ import annotations
+
+from fastapi import FastAPI
+from sqlalchemy.ext.asyncio import async_sessionmaker
+from sqlmodel.ext.asyncio.session import AsyncSession
+
+from transcription.db.runtime import DatabaseRuntime
+from transcription.db.runtime import get_session_factory
+from transcription.worker import WorkerNotifier
+from transcription.worker import resolve_worker_notifier
+
+
+def resolve_database_runtime(state: object) -> DatabaseRuntime | None:
+    """Return database runtime from app-like state objects when available."""
+    runtime = getattr(state, "runtime", None)
+    return runtime if isinstance(runtime, DatabaseRuntime) else None
+
+
+def require_database_runtime(state: object) -> DatabaseRuntime:
+    """Return database runtime or raise when app lifespan has not initialized it."""
+    runtime = resolve_database_runtime(state)
+    if runtime is None:
+        raise RuntimeError("Database runtime is not initialized on application state")
+    return runtime
+
+
+def resolve_session_factory(state: object) -> async_sessionmaker[AsyncSession]:
+    """Return DB session factory from state when available, otherwise shared runtime."""
+    runtime = resolve_database_runtime(state)
+    if runtime is not None:
+        return runtime.session_factory
+    return get_session_factory()
+
+
+def get_worker_notifier(app: FastAPI) -> WorkerNotifier:
+    """Return app worker notifier, or a no-op fallback when unavailable."""
+    return resolve_worker_notifier(app.state)

src/transcription/config.py

@@ -0,0 +1,106 @@
+"""Centralized application configuration.
+
+All settings are loaded from environment variables (or a .env file)
+once at startup. Provider-specific defaults (model names, base URLs)
+are resolved by the provider adapters, not here.
+"""
+
+import logging.config
+from contextvars import ContextVar
+from enum import StrEnum
+from pathlib import Path
+from typing import Literal
+
+from pydantic_settings import BaseSettings
+from pydantic_settings import SettingsConfigDict
+
+logger = logging.getLogger(__name__)
+
+
+class Provider(StrEnum):
+    OPENROUTER = "openrouter"
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    # --- AI provider ---
+    provider: Provider = Provider.OPENROUTER
+    openrouter_api_key: str
+    provider_model: str | None = None
+    openrouter_http_referer: str | None = None
+    openrouter_app_title: str | None = None
+
+    # --- runtime environment ---
+    environment: Literal["development", "test", "production"] = "development"
+
+    # --- persistence ---
+    database_url: str = "sqlite:///./transcription.db"
+    bootstrap_schema_on_startup: bool | None = None
+    sqlite_check_same_thread: bool = False
+
+    # --- filesystem paths ---
+    upload_dir: Path = Path("./uploads")
+    prompt_dir: Path = Path("./prompts")
+
+    # --- worker reliability ---
+    worker_max_retries: int = 0
+    worker_retry_backoff_seconds: float = 0.0
+
+    @property
+    def should_bootstrap_schema(self) -> bool:
+        """Return whether startup should auto-create schema for this environment."""
+        if self.bootstrap_schema_on_startup is not None:
+            return self.bootstrap_schema_on_startup
+        return self.environment in {"development", "test"}
+
+
+_settings: ContextVar[Settings | None] = ContextVar("settings", default=None)
+
+
+def get_settings(**kwargs) -> Settings:
+    settings = _settings.get()
+    if settings is None:
+        settings = Settings(**kwargs)  # pyright: ignore[reportCallIssue]
+        _settings.set(settings)
+    return settings
+
+
+LOGGING_CONFIG: dict[str, object] = {
+    "version": 1,
+    "disable_existing_loggers": False,
+    "formatters": {
+        "standard": {
+            "format": "%(asctime)s %(levelname)-8s | %(message)s",
+            "datefmt": "%Y-%m-%d %H:%M:%S",
+        }
+    },
+    "handlers": {
+        "console": {
+            "class": "logging.StreamHandler",
+            "formatter": "standard",
+            "stream": "ext://sys.stdout",
+        }
+    },
+    "root": {
+        "level": "INFO",
+        "handlers": ["console"],
+    },
+    "loggers": {
+        "transcription": {
+            "level": "DEBUG",
+            "handlers": ["console"],
+            "propagate": False,
+        }
+    },
+}
+
+
+def configure_logging() -> None:
+    """Configure root logging once at startup."""
+    logging.config.dictConfig(LOGGING_CONFIG)
+    logger.debug("Logging configured")

src/transcription/db/__init__.py

@@ -0,0 +1,6 @@
+from .operations import create_all
+from .runtime import dispose_database_runtime
+from .runtime import get_session
+from .runtime import initialize_database_runtime
+
+__all__ = ["create_all", "dispose_database_runtime", "get_session", "initialize_database_runtime"]

src/transcription/db/operations.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+import logging
+
+from sqlalchemy import inspect
+from sqlalchemy import text
+from sqlalchemy.engine import Connection
+from sqlalchemy.ext.asyncio import AsyncEngine
+from sqlmodel import SQLModel
+from sqlmodel import select
+from sqlmodel.ext.asyncio.session import AsyncSession
+
+from ..models import Job
+from ..models import JobStatus
+from .runtime import get_engine
+
+logger = logging.getLogger(__name__)
+
+
+async def get_next_queued_job(*, session: AsyncSession) -> Job | None:
+    """Get the next queued job, if any."""
+    result = await session.exec(
+        select(Job)
+        .where(Job.status == JobStatus.QUEUED)
+        .order_by(Job.created_at)  # pyright: ignore[reportArgumentType]
+        .limit(1)
+    )  # fmt: skip
+    return result.first()
+
+
+async def create_all(*, engine: AsyncEngine | None = None) -> None:
+    """Create all tables on the selected engine."""
+    # Import models so SQLModel metadata is fully registered before bootstrap.
+    from transcription import models as _models  # noqa: F401
+
+    active_engine = engine or get_engine()
+    async with active_engine.begin() as connection:
+        await connection.run_sync(SQLModel.metadata.create_all)
+        await connection.run_sync(_ensure_sqlite_compat_columns)
+    logger.debug("Database schema bootstrap complete for database_url=%s", active_engine.url)
+
+
+def _ensure_sqlite_compat_columns(connection: Connection) -> None:
+    """Apply lightweight dev/test SQLite compatibility column patches.
+
+    This keeps local bootstrap resilient when models evolve but no full
+    migration tooling is in place yet.
+    """
+    if connection.engine.url.get_backend_name() != "sqlite":
+        return
+
+    inspector = inspect(connection)
+    table_names = set(inspector.get_table_names())
+    if "job" not in table_names:
+        return
+
+    columns = {column["name"] for column in inspector.get_columns("job")}
+    if "retry_count" not in columns:
+        connection.execute(text("ALTER TABLE job ADD COLUMN retry_count INTEGER NOT NULL DEFAULT 0"))
+        logger.warning("Applied SQLite compatibility schema patch table=job column=retry_count default=0")
+
+    if "transcript" in table_names:
+        transcript_columns = {column["name"] for column in inspector.get_columns("transcript")}
+        if "model" not in transcript_columns:
+            connection.execute(text("ALTER TABLE transcript ADD COLUMN model VARCHAR"))
+            logger.warning("Applied SQLite compatibility schema patch table=transcript column=model")

src/transcription/db/runtime.py

@@ -0,0 +1,103 @@
+import logging
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+from contextvars import ContextVar
+from dataclasses import dataclass
+from functools import partial
+
+from sqlalchemy.ext.asyncio import AsyncEngine
+from sqlalchemy.ext.asyncio import async_sessionmaker
+from sqlalchemy.ext.asyncio import create_async_engine
+from sqlmodel.ext.asyncio.session import AsyncSession
+from sqlmodel.pool import StaticPool
+
+from ..config import Settings
+from ..config import get_settings
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class DatabaseRuntime:
+    """Database runtime resources owned by app lifespan."""
+
+    engine: AsyncEngine
+    session_factory: async_sessionmaker[AsyncSession]
+
+
+_runtime: ContextVar[DatabaseRuntime | None] = ContextVar("database_runtime", default=None)
+
+
+async def dispose_database_runtime() -> None:
+    """Dispose lifespan-owned async database resources."""
+    runtime = _runtime.get()
+    if runtime is None:
+        return
+    await runtime.engine.dispose()
+    _runtime.set(None)
+
+
+def _to_async_database_url(database_url: str) -> str:
+    """Normalize configured database URL to an async SQLAlchemy driver URL."""
+    if database_url.startswith("sqlite://") and not database_url.startswith("sqlite+aiosqlite://"):
+        return database_url.replace("sqlite://", "sqlite+aiosqlite://", 1)
+    if database_url.startswith("postgresql://") and not database_url.startswith("postgresql+asyncpg://"):
+        return database_url.replace("postgresql://", "postgresql+asyncpg://", 1)
+    return database_url
+
+
+def _build_engine(settings: Settings) -> AsyncEngine:
+    database_url = _to_async_database_url(settings.database_url)
+    engine_factory = partial(
+        create_async_engine,
+        url=database_url,
+        echo=False,
+        pool_pre_ping=True,
+    )
+
+    if database_url.startswith("sqlite"):
+        sqlite_connect_settings = {"check_same_thread": settings.sqlite_check_same_thread}
+        engine_factory = partial(engine_factory, connect_args=sqlite_connect_settings)
+        if ":memory:" in database_url:
+            engine_factory = partial(engine_factory, poolclass=StaticPool)
+
+    return engine_factory()
+
+
+def initialize_database_runtime(*, settings: Settings | None = None) -> DatabaseRuntime:
+    """Initialize lifespan-owned async DB resources once per process."""
+    runtime = _runtime.get()
+    if runtime is not None:
+        return runtime
+
+    active_settings = settings or get_settings()
+    engine = _build_engine(active_settings)
+    session_factory = async_sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)
+    runtime = DatabaseRuntime(engine=engine, session_factory=session_factory)
+    _runtime.set(runtime)
+    logger.debug("Initialized async database runtime for database_url=%s", engine.url)
+    return runtime
+
+
+def get_engine(settings: Settings | None = None) -> AsyncEngine:
+    """Return the current async SQLAlchemy engine."""
+    runtime = _runtime.get() or initialize_database_runtime(settings=settings)
+    return runtime.engine
+
+
+def get_session_factory(settings: Settings | None = None) -> async_sessionmaker[AsyncSession]:
+    """Return the shared async session factory."""
+    runtime = _runtime.get() or initialize_database_runtime(settings=settings)
+    return runtime.session_factory
+
+
+@asynccontextmanager
+async def get_session(
+    *,
+    settings: Settings | None = None,
+    session_factory: async_sessionmaker[AsyncSession] | None = None,
+) -> AsyncGenerator[AsyncSession]:
+    """Yield a database session and ensure cleanup."""
+    active_session_factory = session_factory or get_session_factory(settings)
+    async with active_session_factory() as session:
+        yield session

src/transcription/errors.py

@@ -0,0 +1,85 @@
+"""Shared error taxonomy and helpers for runtime boundaries."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import UTC
+from datetime import datetime
+from enum import StrEnum
+from uuid import uuid4
+
+
+class ErrorCategory(StrEnum):
+    """Stable error categories defined by docs/error_handling.md."""
+
+    VALIDATION = "validation_error"
+    USER_INPUT = "user_input_error"
+    NOT_FOUND = "not_found_error"
+    CONFLICT = "conflict_error"
+    EXTERNAL_PROVIDER = "external_provider_error"
+    PROCESSING = "processing_error"
+    INFRA_TRANSIENT = "infrastructure_transient_error"
+    INFRA_PERSISTENT = "infrastructure_persistent_error"
+    INTERNAL_UNEXPECTED = "internal_unexpected_error"
+
+
+def new_error_id() -> str:
+    """Return a short, user-shareable error reference id."""
+    return uuid4().hex[:8]
+
+
+class AppError(RuntimeError):
+    """Base application error carrying user-safe handling metadata."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        category: ErrorCategory = ErrorCategory.INTERNAL_UNEXPECTED,
+        suggestion: str = "Retry once. If it persists, review logs and report the error reference id.",
+        retriable: bool = False,
+        error_id: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.category = category
+        self.suggestion = suggestion
+        self.retriable = retriable
+        self.error_id = error_id or new_error_id()
+
+
+@dataclass(frozen=True)
+class ErrorEnvelope:
+    """Serializable API/UI error payload."""
+
+    error_id: str
+    category: str
+    message: str
+    suggestion: str
+    timestamp: str
+
+
+def build_error_envelope(error: AppError) -> ErrorEnvelope:
+    """Build an API-safe response envelope from an AppError."""
+    return ErrorEnvelope(
+        error_id=error.error_id,
+        category=error.category.value,
+        message=error.message,
+        suggestion=error.suggestion,
+        timestamp=datetime.now(UTC).isoformat(),
+    )
+
+
+def classify_unexpected_error(exc: Exception, *, operation: str) -> AppError:
+    """Normalize unknown exceptions into internal_unexpected_error."""
+    return AppError(
+        f"Unexpected error during {operation}: {exc}",
+        category=ErrorCategory.INTERNAL_UNEXPECTED,
+        suggestion="Retry once. If it persists, review logs and report the error reference id.",
+        retriable=False,
+    )
+
+
+def format_error_detail(error: AppError) -> str:
+    """Return a compact persisted failure string for transcript.error_detail."""
+    return f"[{error.category.value}] {error.message} | suggestion={error.suggestion} | error_id={error.error_id}"

src/transcription/models.py

@@ -0,0 +1,101 @@
+"""SQLModel domain models for the transcription system.
+
+Core models capture the MVP lifecycle:
+Document (1) -> (many) Job
+Job (1) -> (1) Transcript
+Job (1) -> (many) TranscriptRevision
+"""
+
+from datetime import UTC
+from datetime import datetime
+from enum import StrEnum
+from typing import Optional
+from uuid import UUID
+from uuid import uuid4
+
+from sqlalchemy import UniqueConstraint
+from sqlmodel import Field
+from sqlmodel import Relationship
+from sqlmodel import SQLModel
+
+
+class JobStatus(StrEnum):
+    QUEUED = "queued"
+    PROCESSING = "processing"
+    TRANSCRIBED = "transcribed"
+    FAILED = "failed"
+
+
+class Document(SQLModel, table=True):
+    """An uploaded document image."""
+
+    id: UUID = Field(default_factory=uuid4, primary_key=True)
+    filename: str
+    file_path: str
+    uploaded_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+
+    # --- relationships ---
+    jobs: list["Job"] = Relationship(back_populates="document")
+
+
+class Job(SQLModel, table=True):
+    """A transcription job tied to a single document."""
+
+    id: UUID = Field(default_factory=uuid4, primary_key=True)
+    document_id: UUID = Field(foreign_key="document.id")
+    status: JobStatus = Field(default=JobStatus.QUEUED)
+    retry_count: int = Field(default=0, ge=0)
+    created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    updated_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+
+    # --- relationships ---
+    document: Document = Relationship(back_populates="jobs")
+    transcript: Optional["Transcript"] = Relationship(back_populates="job")
+    transcript_revisions: list["TranscriptRevision"] = Relationship(back_populates="job")
+
+    @property
+    def filename(self) -> str:
+        """Return the filename of the associated document."""
+        return self.document.filename if self.document else "unknown"
+
+
+class Transcript(SQLModel, table=True):
+    """The output of a transcription job."""
+
+    id: UUID = Field(default_factory=uuid4, primary_key=True)
+    job_id: UUID = Field(foreign_key="job.id", unique=True)
+    """ID for the associated job. There's a 1-1 relationship bewteen transcripts and jobs."""
+    provider: str
+    """Name of the transcription provider used to generate this transcript."""
+    prompt_name: str
+    """Name of the prompt used to generate this transcript."""
+    model: str | None = None
+    """Provider model that generated the original AI transcript."""
+    text: str | None = None
+    """The transcribed text. This may be None if the job failed or is still in progress."""
+    error_detail: str | None = None
+    """Details of any error that occurred during transcription."""
+    created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+
+    # --- relationships ---
+    job: Job = Relationship(back_populates="transcript")
+
+
+class TranscriptRevision(SQLModel, table=True):
+    """Version history entries for a transcription job."""
+
+    __table_args__ = (UniqueConstraint("job_id", "version_number", name="uq_transcript_revision_job_version"),)
+
+    id: UUID = Field(default_factory=uuid4, primary_key=True)
+    job_id: UUID = Field(foreign_key="job.id", index=True)
+    version_number: int = Field(ge=1)
+    provider: str
+    prompt_name: str
+    model: str | None = None
+    source: str = Field(default="ai")
+    text: str | None = None
+    error_detail: str | None = None
+    created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+
+    # --- relationships ---
+    job: Job = Relationship(back_populates="transcript_revisions")

src/transcription/providers/__init__.py

@@ -0,0 +1,31 @@
+"""Provider exports and factory for transcription adapters."""
+
+from transcription.config import Provider
+from transcription.config import Settings
+from transcription.config import get_settings
+from transcription.providers.base import ProviderAuthError
+from transcription.providers.base import ProviderError
+from transcription.providers.base import ProviderResponseError
+from transcription.providers.base import TranscriptionProvider
+from transcription.providers.base import TranscriptionResult
+from transcription.providers.openrouter import OpenRouterTranscriptionProvider
+
+
+def get_transcription_provider(*, settings: Settings | None = None) -> TranscriptionProvider:
+    """Return the configured transcription provider adapter."""
+    runtime_settings = settings or get_settings()
+    if runtime_settings.provider == Provider.OPENROUTER:
+        return OpenRouterTranscriptionProvider(settings=runtime_settings)
+
+    raise ProviderError(f"Unsupported transcription provider: {runtime_settings.provider}")
+
+
+__all__ = [
+    "OpenRouterTranscriptionProvider",
+    "ProviderAuthError",
+    "ProviderError",
+    "ProviderResponseError",
+    "TranscriptionProvider",
+    "TranscriptionResult",
+    "get_transcription_provider",
+]

src/transcription/providers/base.py

@@ -0,0 +1,47 @@
+"""Provider interfaces and shared types for transcription adapters."""
+
+from dataclasses import dataclass
+from typing import Protocol
+from uuid import UUID
+
+from ..models import Transcript
+
+
+class ProviderError(RuntimeError):
+    """Base error for provider failures."""
+
+
+class ProviderAuthError(ProviderError):
+    """Raised when provider authentication fails."""
+
+
+class ProviderResponseError(ProviderError):
+    """Raised when provider responses are malformed or unusable."""
+
+
+@dataclass(frozen=True)
+class TranscriptionResult:
+    """Normalized output returned by any transcription provider."""
+
+    text: str
+    provider: str
+    prompt_name: str
+    model: str
+
+    def to_transcript(self, job_id: UUID) -> Transcript:
+        """Convert a TranscriptionResult to a Transcript model instance."""
+        return Transcript(
+            job_id=job_id,
+            provider=self.provider,
+            prompt_name=self.prompt_name,
+            model=self.model,
+            text=self.text,
+        )
+
+
+class TranscriptionProvider(Protocol):
+    """Contract every transcription provider adapter must satisfy."""
+
+    async def transcribe(self, *, prompt_text: str, image_bytes: bytes, mime_type: str) -> TranscriptionResult:
+        """Transcribe the provided image according to the prompt text."""
+        ...

src/transcription/providers/openrouter.py

@@ -0,0 +1,129 @@
+"""OpenRouter transcription provider adapter."""
+
+from __future__ import annotations
+
+import base64
+import logging
+from dataclasses import dataclass
+from typing import Any
+from typing import cast
+
+from openrouter import OpenRouter
+from openrouter.components.chatmessages import ChatMessagesTypedDict
+
+from transcription.config import Settings
+from transcription.config import get_settings
+from transcription.providers.base import ProviderAuthError
+from transcription.providers.base import ProviderError
+from transcription.providers.base import ProviderResponseError
+from transcription.providers.base import TranscriptionResult
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_OPENROUTER_MODEL = "google/gemini-2.5-flash"
+
+
+@dataclass(frozen=True)
+class OpenRouterRequest:
+    """Normalized request payload fields for OpenRouter calls."""
+
+    model: str
+    messages: list[dict[str, Any]]
+    http_referer: str | None
+    x_open_router_title: str | None
+
+
+class OpenRouterTranscriptionProvider:
+    """Adapter that performs image transcription through OpenRouter."""
+
+    def __init__(self, *, settings: Settings | None = None, client: OpenRouter | None = None):
+        self._settings = settings or get_settings()
+        self._model = self._settings.provider_model or DEFAULT_OPENROUTER_MODEL
+        self._client = client or OpenRouter(api_key=self._settings.openrouter_api_key)
+
+    @property
+    def model(self) -> str:
+        """Return the resolved OpenRouter model slug."""
+        return self._model
+
+    async def transcribe(self, *, prompt_text: str, image_bytes: bytes, mime_type: str) -> TranscriptionResult:
+        """Send prompt + image to OpenRouter and return normalized text output."""
+        request = self._build_request(prompt_text=prompt_text, image_bytes=image_bytes, mime_type=mime_type)
+        try:
+            response = await self._client.chat.send_async(
+                messages=cast(list[ChatMessagesTypedDict], request.messages),
+                model=request.model,
+                http_referer=request.http_referer,
+                x_open_router_title=request.x_open_router_title,
+            )
+        except Exception as exc:
+            message = str(exc).lower()
+            if "401" in message or "auth" in message or "api key" in message:
+                raise ProviderAuthError("OpenRouter authentication failed") from exc
+            raise ProviderError("OpenRouter request failed") from exc
+
+        text = self._extract_text(response)
+        model = self._get_optional_attr(response, "model") or self.model
+        logger.info("OpenRouter transcription completed using model=%s", model)
+        return TranscriptionResult(text=text, provider="openrouter", prompt_name="", model=model)
+
+    def _build_request(self, *, prompt_text: str, image_bytes: bytes, mime_type: str) -> OpenRouterRequest:
+        image_b64 = base64.b64encode(image_bytes).decode("ascii")
+        data_url = f"data:{mime_type};base64,{image_b64}"
+
+        messages: list[dict[str, Any]] = [
+            {
+                "role": "user",
+                "content": [
+                    {"type": "text", "text": prompt_text},
+                    {"type": "image_url", "image_url": {"url": data_url}},
+                ],
+            }
+        ]
+
+        return OpenRouterRequest(
+            model=self.model,
+            messages=messages,
+            http_referer=self._settings.openrouter_http_referer,
+            x_open_router_title=self._settings.openrouter_app_title,
+        )
+
+    def _extract_text(self, response: Any) -> str:
+        choices = self._get_optional_attr(response, "choices")
+        if not choices:
+            raise ProviderResponseError("OpenRouter response missing choices")
+
+        first_choice = choices[0]
+        message = self._get_optional_attr(first_choice, "message")
+        if message is None:
+            raise ProviderResponseError("OpenRouter response missing assistant message")
+
+        content = self._get_optional_attr(message, "content")
+        text = self._normalize_content(content)
+        if not text:
+            raise ProviderResponseError("OpenRouter response contained no transcription text")
+        return text
+
+    def _normalize_content(self, content: Any) -> str:
+        if isinstance(content, str):
+            return content.strip()
+
+        if isinstance(content, list):
+            parts: list[str] = []
+            for item in content:
+                text_part = None
+                text_part = item.get("text") if isinstance(item, dict) else self._get_optional_attr(item, "text")
+
+                if isinstance(text_part, str) and text_part.strip():
+                    parts.append(text_part.strip())
+            return "\n".join(parts).strip()
+
+        return ""
+
+    @staticmethod
+    def _get_optional_attr(obj: Any, key: str) -> Any:
+        if obj is None:
+            return None
+        if isinstance(obj, dict):
+            return obj.get(key)
+        return getattr(obj, key, None)

src/transcription/services/__init__.py

@@ -0,0 +1,19 @@
+"""Service layer exports."""
+
+from dataclasses import dataclass
+from dataclasses import field
+
+from .documents import DocumentService
+from .jobs import JobService
+from .transcription import TranscriptionService
+
+__all__ = ["DocumentService", "JobService", "ServiceBundle", "TranscriptionService"]
+
+
+@dataclass(frozen=True, slots=True)
+class ServiceBundle:
+    """Container for all service instances."""
+
+    documents: DocumentService = field(default_factory=DocumentService)
+    jobs: JobService = field(default_factory=JobService)
+    transcriptions: TranscriptionService = field(default_factory=TranscriptionService)

src/transcription/services/base.py

@@ -0,0 +1,60 @@
+import asyncio
+from abc import ABC
+from collections.abc import Sequence
+from contextlib import asynccontextmanager
+
+from sqlalchemy.ext.asyncio import async_sessionmaker
+from sqlmodel.ext.asyncio.session import AsyncSession
+
+from ..config import Settings
+from ..config import get_settings
+from ..db.runtime import get_session_factory
+
+
+class ServiceBase(ABC):
+    """Thin service class for managing documents in the database."""
+
+    settings: Settings
+    session_factory: async_sessionmaker[AsyncSession]
+    queue: asyncio.Queue
+
+    def __init__(
+        self,
+        session_factory: async_sessionmaker[AsyncSession] | None = None,
+        queue: asyncio.Queue | None = None,
+    ):
+        self.settings = get_settings()
+        self.session_factory = session_factory or get_session_factory()
+        self.queue = queue or asyncio.Queue()
+
+    @asynccontextmanager
+    async def _session_scope(self, session: AsyncSession | None = None):
+        """Provide a transactional scope around a series of operations."""
+        if session is not None:
+            # Reuse the provided session if one is passed in
+            yield session
+        else:
+            # Otherwise, create a new session for this scope
+            async with self.session_factory() as new_session:
+                yield new_session
+
+    async def _finalize(
+        self,
+        *,
+        session: AsyncSession,
+        caller_session: AsyncSession | None,
+        refresh: Sequence[object] = (),
+    ) -> None:
+        """Finalize a write based on transaction ownership.
+
+        Service-owned sessions commit immediately. Caller-owned sessions flush so
+        orchestration code can commit once at a larger transaction boundary.
+        """
+        should_commit = caller_session is None
+        if should_commit:
+            await session.commit()
+        else:
+            await session.flush()
+
+        for obj in refresh:
+            await session.refresh(obj)

src/transcription/services/documents.py

@@ -0,0 +1,127 @@
+import logging
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from uuid import UUID
+
+from sqlalchemy.exc import IntegrityError
+from sqlalchemy.orm import selectinload
+from sqlmodel import select
+from sqlmodel.ext.asyncio.session import AsyncSession
+
+from ..errors import AppError
+from ..errors import ErrorCategory
+from ..models import Document
+from .base import ServiceBase
+
+logger = logging.getLogger(__name__)
+
+
+class DocumentError(AppError):
+    """Raised when document operations fail."""
+
+
+class MissingImageError(DocumentError):
+    """Raised when a required image is missing."""
+
+
+class UploadError(DocumentError):
+    """Raised when uploaded content cannot be persisted safely."""
+
+
+class DocumentAlreadyExistsError(DocumentError):
+    """Raised when a document with the same filename already exists in the database."""
+
+
+@dataclass(frozen=True)
+class UploadJobResult:
+    """Summary of created upload records."""
+
+    document_id: UUID
+    job_id: UUID
+    stored_path: Path
+    original_filename: str
+
+
+class DocumentService(ServiceBase):
+    """Thin service class for managing documents in the database."""
+
+    #
+    # CRUD Operations
+    #
+
+    async def create_document(
+        self,
+        document: Document,
+        *,
+        session: AsyncSession | None = None,
+    ) -> Document:
+        """Create a new document in the database."""
+        async with self._session_scope(session) as _session:
+            _session.add(document)
+            try:
+                await self._finalize(session=_session, caller_session=session, refresh=(document,))
+            except IntegrityError as exc:
+                raise DocumentAlreadyExistsError(
+                    f"Document with id {document.id} already exists",
+                    category=ErrorCategory.VALIDATION,
+                    suggestion="Rename the file and try again.",
+                ) from exc
+            return document
+
+    async def read_document(self, document_id: UUID, *, session: AsyncSession | None = None) -> Document:
+        """Read an existing document from the database.
+
+        The selectinload option is used to eagerly load related jobs for the document.
+        """
+        async with self._session_scope(session) as _session:
+            document = await _session.get(
+                Document,
+                document_id,
+                options=(selectinload(Document.jobs),),  # pyright: ignore[reportArgumentType]
+            )
+        if document is None:
+            raise DocumentError(
+                f"Document with id {document_id} not found",
+                category=ErrorCategory.NOT_FOUND,
+                suggestion="Re-upload the source document and retry.",
+            )
+        elif not Path(document.file_path).exists():
+            raise MissingImageError(
+                f"Document with id {document_id} is missing its image file in {self.settings.upload_dir:!s}",
+                category=ErrorCategory.NOT_FOUND,
+                suggestion="Re-upload the source document and retry.",
+            )
+        return document
+
+    async def update_document(self, document: Document, *, session: AsyncSession | None = None) -> Document:
+        """Update an existing document in the database."""
+        async with self._session_scope(session) as _session:
+            merged = await _session.merge(document)
+            await self._finalize(session=_session, caller_session=session, refresh=(merged,))
+            return merged
+
+    async def delete_document(self, document: Document, *, session: AsyncSession | None = None) -> None:
+        """Delete a document from the database."""
+        async with self._session_scope(session) as _session:
+            await _session.delete(document)
+            await self._finalize(session=_session, caller_session=session)
+
+    # Query Operations
+
+    async def query_documents(
+        self, *, filename: str | None = None, session: AsyncSession | None = None
+    ) -> Sequence[Document]:
+        """Query documents from the database based on provided filters."""
+        async with self._session_scope(session) as _session:
+            query = select(Document)
+            if filename is not None:
+                query = query.where(Document.filename == filename)
+            result = await _session.exec(query)
+            return result.all()
+
+    async def list_documents(self, *, session: AsyncSession | None = None) -> Sequence[Document]:
+        """List all documents in the database."""
+        async with self._session_scope(session) as _session:
+            result = await _session.exec(select(Document))
+            return result.all()

src/transcription/services/jobs.py

@@ -0,0 +1,146 @@
+from collections.abc import Sequence
+from datetime import UTC
+from datetime import datetime
+from uuid import UUID
+
+from sqlalchemy.orm import selectinload
+from sqlmodel import select
+from sqlmodel.ext.asyncio.session import AsyncSession
+
+from ..models import Job
+from ..models import JobStatus
+from .base import ServiceBase
+
+
+class JobService(ServiceBase):
+    """Thin service class for managing jobs in the database."""
+
+    #
+    # CRUD Operations
+    #
+
+    async def create_job(self, job: Job, session: AsyncSession | None = None) -> Job:
+        """Create a new job in the database."""
+        async with self._session_scope(session) as _session:
+            _session.add(job)
+            await self._finalize(session=_session, caller_session=session, refresh=(job,))
+            return job
+
+    async def read_job(self, job_id: UUID, session: AsyncSession | None = None) -> Job:
+        """Read an existing job from the database.
+
+        The related document is always eagerly loaded so callers can safely
+        access ``job.document`` in async contexts without triggering lazy-load IO.
+        """
+        async with self._session_scope(session) as _session:
+            query = (
+                select(Job)
+                .options(selectinload(Job.document))  # pyright: ignore[reportArgumentType]
+                .where(Job.id == job_id)
+                .execution_options(populate_existing=True)
+            )
+            job = (await _session.exec(query)).first()
+        if job is None:
+            raise ValueError(f"Job with id {job_id} not found")
+        return job
+
+    async def update_job(self, job: Job, session: AsyncSession | None = None) -> Job:
+        """Update an existing job in the database."""
+        async with self._session_scope(session) as _session:
+            merged = await _session.merge(job)
+            await self._finalize(session=_session, caller_session=session, refresh=(merged,))
+            return merged
+
+    async def delete_job(self, job: Job, session: AsyncSession | None = None) -> None:
+        """Delete a job from the database."""
+        async with self._session_scope(session) as _session:
+            await _session.delete(job)
+            await self._finalize(session=_session, caller_session=session)
+
+    # Query Operations
+
+    async def query_jobs(
+        self,
+        *,
+        status: JobStatus | None = None,
+        filename: str | None = None,
+        session: AsyncSession | None = None,
+    ) -> Sequence[Job]:
+        """Query jobs from the database based on provided filters."""
+        async with self._session_scope(session) as _session:
+            query = select(Job).options(selectinload(Job.document))  # pyright: ignore[reportArgumentType]
+            if status is not None:
+                query = query.where(Job.status == status)
+            if filename is not None:
+                query = query.where(Job.document.filename == filename)
+            result = await _session.exec(query)
+            return result.all()
+
+    async def list_jobs(
+        self,
+        *,
+        load_docs: bool = False,
+        session: AsyncSession | None = None,
+    ) -> Sequence[Job]:
+        """List all jobs in the database with eagerly loaded documents."""
+        _ = load_docs
+        async with self._session_scope(session) as _session:
+            query = select(Job).options(selectinload(Job.document))  # pyright: ignore[reportArgumentType]
+            result = await _session.exec(query)
+            return result.all()
+
+    # Other Operations
+
+    async def mark_job_status(
+        self,
+        job_id: UUID,
+        status: JobStatus,
+        session: AsyncSession | None = None,
+    ) -> Job:
+        """Mark a job with a new status."""
+        return await self.update_job_state(job_id=job_id, status=status, session=session)
+
+    async def update_job_state(
+        self,
+        *,
+        job_id: UUID,
+        status: JobStatus,
+        retry_count_increment: int = 0,
+        session: AsyncSession | None = None,
+    ) -> Job:
+        """Update a job's lifecycle fields.
+
+        When ``session`` is provided, this method flushes so callers can commit
+        once at an orchestration boundary.
+        """
+        async with self._session_scope(session) as _session:
+            query = (
+                select(Job)
+                .options(selectinload(Job.document))  # pyright: ignore[reportArgumentType]
+                .where(Job.id == job_id)
+                .execution_options(populate_existing=True)
+            )
+            job = (await _session.exec(query)).first()
+            if job is None:
+                raise ValueError(f"Job with id {job_id} not found")
+            job.status = status
+            if retry_count_increment:
+                job.retry_count += retry_count_increment
+            job.updated_at = datetime.now(UTC)
+            await self._finalize(session=_session, caller_session=session, refresh=(job,))
+            return job
+
+    async def read_next_queued_job(
+        self,
+        *,
+        session: AsyncSession | None = None,
+    ) -> Job | None:
+        """Read the next queued job ordered by creation time."""
+        async with self._session_scope(session) as _session:
+            query = (
+                select(Job)
+                .options(selectinload(Job.document))  # pyright: ignore[reportArgumentType]
+                .where(Job.status == JobStatus.QUEUED)
+                .order_by(Job.created_at)  # pyright: ignore[reportArgumentType]
+            )
+            return (await _session.exec(query)).first()

src/transcription/services/store.py

@@ -0,0 +1,145 @@
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from uuid import uuid4
+
+from sqlmodel.ext.asyncio.session import AsyncSession
+
+from transcription.config import Settings
+from transcription.config import get_settings
+from transcription.errors import AppError
+from transcription.errors import ErrorCategory
+
+from ..models import Document
+from ..models import Job
+from .documents import UploadJobResult
+
+logger = logging.getLogger(__name__)
+
+SUPPORTED_UPLOAD_EXTENSIONS = {".jpg", ".jpeg", ".png", ".tif", ".tiff", ".pdf"}
+
+
+class UploadError(AppError):
+    """Raised when uploaded content cannot be persisted safely."""
+
+
+async def create_upload_job(
+    *,
+    filename: str,
+    file_bytes: bytes,
+    session: AsyncSession,
+    settings: Settings | None = None,
+) -> UploadJobResult:
+    """Create upload-backed document and queued job records."""
+    runtime_settings = settings or get_settings()
+    stored_path = store_file(
+        filename=filename,
+        file_bytes=file_bytes,
+        settings=runtime_settings,
+    )
+    try:
+        document, job = await _create_upload_records(
+            session=session,
+            original_filename=filename,
+            stored_path=stored_path,
+        )
+    except Exception as exc:
+        _best_effort_delete(stored_path)
+        raise UploadError(
+            "Failed to create upload database records",
+            category=ErrorCategory.INFRA_TRANSIENT,
+            suggestion="Retry upload. If this keeps happening, verify database availability.",
+            retriable=True,
+        ) from exc
+
+    logger.info("Created upload job document_id=%s job_id=%s", document.id, job.id)
+    return UploadJobResult(
+        document_id=document.id,
+        job_id=job.id,
+        stored_path=stored_path,
+        original_filename=Path(filename).name,
+    )
+
+
+async def _create_upload_records(
+    *,
+    session: AsyncSession,
+    original_filename: str,
+    stored_path: Path,
+) -> tuple[Document, Job]:
+    document = Document(
+        filename=Path(original_filename).name,
+        file_path=str(stored_path),
+    )
+    session.add(document)
+    await session.flush()
+
+    job = Job(document_id=document.id)
+    session.add(job)
+    await session.commit()
+    await session.refresh(document)
+    await session.refresh(job)
+    return document, job
+
+
+def _best_effort_delete(path: Path) -> None:
+    try:
+        if path.exists():
+            path.unlink()
+    except OSError:
+        logger.warning("Failed to clean up upload file after DB error: %s", path)
+
+
+def store_file(*, filename: str, file_bytes: bytes, settings: Settings | None = None) -> Path:
+    """Persist an uploaded file to the configured upload directory."""
+    runtime_settings = settings or get_settings()
+    _validate_upload(filename=filename, file_bytes=file_bytes)
+
+    upload_dir = runtime_settings.upload_dir
+    upload_dir.mkdir(parents=True, exist_ok=True)
+
+    stored_name = _build_stored_filename(filename)
+    stored_path = upload_dir / stored_name
+
+    try:
+        stored_path.write_bytes(file_bytes)
+    except OSError as exc:
+        raise UploadError(
+            "Failed to persist upload file",
+            category=ErrorCategory.INFRA_PERSISTENT,
+            suggestion="Check upload directory permissions and available disk space, then retry.",
+        ) from exc
+
+    logger.info("Stored uploaded file: %s", stored_path)
+    return stored_path
+
+
+def _validate_upload(*, filename: str, file_bytes: bytes) -> None:
+    if not file_bytes:
+        raise UploadError(
+            "Upload payload is empty",
+            category=ErrorCategory.VALIDATION,
+            suggestion="Select a non-empty file and try again.",
+        )
+
+    safe_name = Path(filename).name
+    if not safe_name:
+        raise UploadError(
+            "Upload filename is required",
+            category=ErrorCategory.VALIDATION,
+            suggestion="Choose a file with a valid filename and retry.",
+        )
+
+    suffix = Path(safe_name).suffix.lower()
+    if suffix not in SUPPORTED_UPLOAD_EXTENSIONS:
+        raise UploadError(
+            f"Unsupported upload extension: {suffix}",
+            category=ErrorCategory.USER_INPUT,
+            suggestion="Upload JPG, JPEG, PNG, TIFF, or PDF files only.",
+        )
+
+
+def _build_stored_filename(filename: str) -> str:
+    safe_name = Path(filename).name
+    return f"{uuid4()}_{safe_name}"

src/transcription/services/transcription.py

@@ -0,0 +1,364 @@
+"""Prompt loading and provider-backed transcription service."""
+
+from __future__ import annotations
+
+import logging
+import mimetypes
+from contextlib import contextmanager
+from pathlib import Path
+from uuid import UUID
+
+from sqlalchemy.ext.asyncio import async_sessionmaker
+from sqlalchemy.orm import selectinload
+from sqlmodel import select
+from sqlmodel.ext.asyncio.session import AsyncSession
+
+from transcription.config import Settings
+from transcription.config import get_settings
+from transcription.errors import AppError
+from transcription.errors import ErrorCategory
+from transcription.models import Transcript
+from transcription.models import TranscriptRevision
+from transcription.providers import ProviderAuthError
+from transcription.providers import ProviderError
+from transcription.providers import ProviderResponseError
+from transcription.providers import TranscriptionProvider
+from transcription.providers import TranscriptionResult
+from transcription.providers import get_transcription_provider
+
+from .base import ServiceBase
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_PROMPT_FILE = "transcribe_document.md"
+SUPPORTED_EXTENSIONS = {".jpg", ".jpeg", ".png", ".tif", ".tiff", ".pdf"}
+
+
+class PromptLoadError(AppError):
+    """Raised when prompt artifacts cannot be loaded safely."""
+
+
+class TranscriptionError(AppError):
+    """Raised when transcription execution fails."""
+
+
+class TranscriptionNotFoundError(TranscriptionError):
+    """Raised when a transcription is not found in the database."""
+
+
+class TranscriptionService(ServiceBase):
+    """Service class for managing transcription operations.
+
+    This is the top-level service that composes functionality from the other services."""
+
+    provider: TranscriptionProvider
+
+    def __init__(self, session_factory: async_sessionmaker[AsyncSession] | None = None):
+        super().__init__(session_factory=session_factory)
+        self.provider = get_transcription_provider(settings=self.settings)
+
+    async def create_transcript(self, transcript: Transcript, *, session: AsyncSession | None = None) -> Transcript:
+        """Create a new transcript in the database."""
+        async with self._session_scope(session) as _session:
+            _session.add(transcript)
+            await self._finalize(session=_session, caller_session=session, refresh=(transcript,))
+            return transcript
+
+    async def create_transcript_revision(
+        self,
+        transcript_revision: TranscriptRevision,
+        *,
+        session: AsyncSession | None = None,
+    ) -> TranscriptRevision:
+        """Create a new transcript revision in the database."""
+        async with self._session_scope(session) as _session:
+            _session.add(transcript_revision)
+            await self._finalize(session=_session, caller_session=session, refresh=(transcript_revision,))
+            return transcript_revision
+
+    async def read_transcript(self, transcript_id: UUID, *, session: AsyncSession | None = None) -> Transcript:
+        """Read an existing transcript from the database."""
+        async with self._session_scope(session) as _session:
+            transcript = await _session.get(
+                Transcript,
+                transcript_id,
+                # Makes the full Job model object available in the return Transcript object
+                options=(selectinload(Transcript.job),),  # pyright: ignore[reportArgumentType]
+            )
+        if transcript is None:
+            raise TranscriptionNotFoundError(
+                f"Transcript with id {transcript_id} not found",
+                category=ErrorCategory.NOT_FOUND,
+                suggestion="Verify the transcript id and retry.",
+            )
+        return transcript
+
+    async def read_transcript_revision(
+        self,
+        transcript_revision_id: UUID,
+        *,
+        session: AsyncSession | None = None,
+    ) -> TranscriptRevision:
+        """Read an existing transcript revision from the database."""
+        async with self._session_scope(session) as _session:
+            transcript_revision = await _session.get(
+                TranscriptRevision,
+                transcript_revision_id,
+                options=(selectinload(TranscriptRevision.job),),  # pyright: ignore[reportArgumentType]
+            )
+        if transcript_revision is None:
+            raise TranscriptionNotFoundError(
+                f"Transcript revision with id {transcript_revision_id} not found",
+                category=ErrorCategory.NOT_FOUND,
+                suggestion="Verify the transcript revision id and retry.",
+            )
+        return transcript_revision
+
+    async def update_transcript(self, transcript: Transcript, *, session: AsyncSession | None = None) -> Transcript:
+        """Update an existing transcript in the database."""
+        async with self._session_scope(session) as _session:
+            merged = await _session.merge(transcript)
+            await self._finalize(session=_session, caller_session=session, refresh=(merged,))
+            return merged
+
+    async def update_transcript_revision(
+        self,
+        transcript_revision: TranscriptRevision,
+        *,
+        session: AsyncSession | None = None,
+    ) -> TranscriptRevision:
+        """Update an existing transcript revision in the database."""
+        async with self._session_scope(session) as _session:
+            merged = await _session.merge(transcript_revision)
+            await self._finalize(session=_session, caller_session=session, refresh=(merged,))
+            return merged
+
+    async def delete_transcript(self, transcript: Transcript, *, session: AsyncSession | None = None) -> None:
+        """Delete a transcript from the database."""
+        async with self._session_scope(session) as _session:
+            await _session.delete(transcript)
+            await self._finalize(session=_session, caller_session=session)
+
+    async def delete_transcript_revision(
+        self,
+        transcript_revision: TranscriptRevision,
+        *,
+        session: AsyncSession | None = None,
+    ) -> None:
+        """Delete a transcript revision from the database."""
+        async with self._session_scope(session) as _session:
+            await _session.delete(transcript_revision)
+            await self._finalize(session=_session, caller_session=session)
+
+    async def transcribe_document(
+        self,
+        image_path: str | Path,
+        job_id: UUID,
+        *,
+        prompt_name: str = DEFAULT_PROMPT_FILE,
+        session: AsyncSession | None = None,
+    ):
+        """Transcribe a local image using the configured prompt and provider."""
+        result = await transcribe_document_image(
+            image_path=image_path,
+            prompt_name=prompt_name,
+            settings=self.settings,
+            provider=self.provider,
+        )
+        await self.create_transcript(transcript=result.to_transcript(job_id=job_id), session=session)
+
+    async def upsert_transcript_by_job(
+        self,
+        *,
+        job_id: UUID,
+        text: str | None,
+        error_detail: str | None,
+        provider: str | None = None,
+        prompt_name: str = DEFAULT_PROMPT_FILE,
+        model: str | None = None,
+        session: AsyncSession | None = None,
+    ) -> Transcript:
+        """Create or update a transcript for a job id."""
+        async with self._session_scope(session) as _session:
+            transcript = (await _session.exec(select(Transcript).where(Transcript.job_id == job_id))).first()
+            if transcript is None:
+                transcript = Transcript(
+                    job_id=job_id,
+                    provider=provider or self.settings.provider.value,
+                    prompt_name=prompt_name,
+                )
+
+            transcript.text = text
+            transcript.error_detail = error_detail
+            if provider is not None:
+                transcript.provider = provider
+            transcript.prompt_name = prompt_name
+            if model is not None:
+                transcript.model = model
+
+            _session.add(transcript)
+            await self._finalize(session=_session, caller_session=session, refresh=(transcript,))
+            return transcript
+
+    async def list_transcript_revisions_by_job(
+        self,
+        *,
+        job_id: UUID,
+        session: AsyncSession | None = None,
+    ) -> list[TranscriptRevision]:
+        """Return transcript revisions for a job ordered by version number."""
+        async with self._session_scope(session) as _session:
+            revisions = (
+                await _session.exec(
+                    select(TranscriptRevision)
+                    .where(TranscriptRevision.job_id == job_id)
+                    .order_by(TranscriptRevision.version_number)
+                )
+            ).all()
+            return list(revisions)
+
+    async def append_transcript_revision(
+        self,
+        *,
+        job_id: UUID,
+        text: str | None,
+        error_detail: str | None,
+        provider: str,
+        prompt_name: str,
+        model: str | None,
+        source: str,
+        session: AsyncSession | None = None,
+    ) -> TranscriptRevision:
+        """Append a new transcript revision and allocate the next version number."""
+        async with self._session_scope(session) as _session:
+            latest_version = (
+                await _session.exec(
+                    select(TranscriptRevision.version_number)
+                    .where(TranscriptRevision.job_id == job_id)
+                    .order_by(TranscriptRevision.version_number.desc())
+                    .limit(1)
+                )
+            ).first()
+            next_version = 1 if latest_version is None else latest_version + 1
+
+            revision = TranscriptRevision(
+                job_id=job_id,
+                version_number=next_version,
+                provider=provider,
+                prompt_name=prompt_name,
+                model=model,
+                source=source,
+                text=text,
+                error_detail=error_detail,
+            )
+            _session.add(revision)
+            await self._finalize(session=_session, caller_session=session, refresh=(revision,))
+            return revision
+
+
+async def transcribe_document_image(
+    image_path: str | Path,
+    *,
+    prompt_name: str = DEFAULT_PROMPT_FILE,
+    settings: Settings | None = None,
+    provider: TranscriptionProvider | None = None,
+) -> TranscriptionResult:
+    """Transcribe a local image using the configured prompt and provider."""
+    runtime_settings = settings or get_settings()
+    prompt_text = load_prompt_text(prompt_name=prompt_name, settings=runtime_settings)
+    image_bytes, mime_type = load_image_payload(image_path)
+
+    adapter = provider or get_transcription_provider(settings=runtime_settings)
+    logger.info("Starting transcription for image=%s mime_type=%s", image_path, mime_type)
+
+    with handle_transcription_errors():
+        result = await adapter.transcribe(
+            prompt_text=prompt_text,
+            image_bytes=image_bytes,
+            mime_type=mime_type,
+        )
+    logger.info("Transcription completed for image=%s provider=%s", image_path, result.provider)
+    return result
+
+
+def load_prompt_text(*, prompt_name: str = DEFAULT_PROMPT_FILE, settings: Settings | None = None) -> str:
+    """Load and validate prompt text from PROMPT_DIR."""
+    runtime_settings = settings or get_settings()
+    prompt_path = runtime_settings.prompt_dir / prompt_name
+
+    if not prompt_path.exists() or not prompt_path.is_file():
+        raise PromptLoadError(
+            f"Prompt file not found: {prompt_path}",
+            category=ErrorCategory.INFRA_PERSISTENT,
+            suggestion="Verify PROMPT_DIR and prompt file configuration, then retry.",
+        )
+
+    prompt_text = prompt_path.read_text(encoding="utf-8").strip()
+    if not prompt_text:
+        raise PromptLoadError(
+            f"Prompt file is empty: {prompt_path}",
+            category=ErrorCategory.VALIDATION,
+            suggestion="Populate the prompt file with valid instructions and retry.",
+        )
+
+    logger.info("Loaded prompt artifact: %s", prompt_path)
+    return prompt_text
+
+
+def load_image_payload(image_path: str | Path) -> tuple[bytes, str]:
+    """Read image bytes and detect mime type for supported uploads."""
+    path = Path(image_path)
+
+    if not path.exists() or not path.is_file():
+        raise TranscriptionError(
+            f"Image file not found: {path}",
+            category=ErrorCategory.NOT_FOUND,
+            suggestion="Verify the uploaded file exists and retry from the jobs page.",
+        )
+
+    suffix = path.suffix.lower()
+    if suffix not in SUPPORTED_EXTENSIONS:
+        raise TranscriptionError(
+            f"Unsupported file type: {suffix}",
+            category=ErrorCategory.USER_INPUT,
+            suggestion="Use JPG, JPEG, PNG, TIFF, or PDF files.",
+        )
+
+    mime_type, _ = mimetypes.guess_type(path.name)
+    if suffix in {".tif", ".tiff"}:
+        mime_type = "image/tiff"
+    if not mime_type:
+        raise TranscriptionError(
+            f"Unable to determine MIME type for: {path}",
+            category=ErrorCategory.VALIDATION,
+            suggestion="Re-save the file in a supported format and retry.",
+        )
+
+    return path.read_bytes(), mime_type
+
+
+@contextmanager
+def handle_transcription_errors():
+    """Context manager to handle transcription errors."""
+    try:
+        yield
+    except ProviderAuthError as exc:
+        raise TranscriptionError(
+            "Provider authentication failed",
+            category=ErrorCategory.INFRA_PERSISTENT,
+            suggestion="Verify provider API credentials and retry.",
+        ) from exc
+    except ProviderResponseError as exc:
+        raise TranscriptionError(
+            "Provider returned an invalid response",
+            category=ErrorCategory.EXTERNAL_PROVIDER,
+            suggestion="Retry once. If it persists, try a different provider model or inspect provider status.",
+            retriable=True,
+        ) from exc
+    except ProviderError as exc:
+        raise TranscriptionError(
+            "Provider transcription failed",
+            category=ErrorCategory.EXTERNAL_PROVIDER,
+            suggestion="Retry the transcription from jobs. If repeated, check provider availability.",
+            retriable=True,
+        ) from exc

src/transcription/services/workflows.py

@@ -0,0 +1,317 @@
+import asyncio
+import logging
+
+from sqlmodel.ext.asyncio.session import AsyncSession
+
+from ..config import Settings
+from ..config import get_settings
+from ..errors import AppError
+from ..errors import classify_unexpected_error
+from ..errors import format_error_detail
+from ..models import Job
+from ..models import JobStatus
+from ..providers import TranscriptionResult
+from . import ServiceBundle
+from .transcription import DEFAULT_PROMPT_FILE
+from .transcription import transcribe_document_image
+
+logger = logging.getLogger(__name__)
+
+
+async def advance_job(
+    job: Job,
+    services: ServiceBundle,
+    settings: Settings | None = None,
+    session: AsyncSession | None = None,
+) -> Job | None:
+    """Advance a single job by lifecycle status."""
+    settings = settings or get_settings()
+    match job.status:
+        case JobStatus.QUEUED:
+            return await process_queued_job(job=job, services=services, session=session)
+        case JobStatus.FAILED:
+            if job.retry_count < settings.worker_max_retries:
+                return await services.jobs.update_job_state(
+                    job_id=job.id,
+                    status=JobStatus.QUEUED,
+                    retry_count_increment=1,
+                    session=session,
+                )
+            else:
+                logger.error(f"Job {job.id} has failed and reached max retries.")
+                return
+        case _:
+            return
+
+
+async def process_queued_job(
+    *,
+    job: Job,
+    services: ServiceBundle,
+    session: AsyncSession | None = None,
+) -> Job | None:
+    """Process one complete transcription attempt for a queued job."""
+    if job.status != JobStatus.QUEUED:
+        logger.warning(f"Job {job.id} is not queued. Current status: {job.status}")
+        return
+
+    # Transaction A: claim job for processing.
+    if session is None:
+        job = await services.jobs.mark_job_status(job.id, JobStatus.PROCESSING)
+    else:
+        # If we're sharing the session, need to make sure setting the Job to PROCESSING is committed before we start
+        # the transcription, otherwise other workers may see the job as still QUEUED and try to process it.
+        job = await services.jobs.mark_job_status(job.id, JobStatus.PROCESSING, session=session)
+        await session.commit()
+
+    document = job.document
+    assert document is not None, (
+        f"Job {job.id} has no associated document or the document failed to be loaded by the job service."
+    )
+
+    try:
+        result = await transcribe_document_image(document.file_path)
+        job = await _finalize_transcribed(job=job, services=services, result=result, session=session)
+        logger.info(
+            "Job transcribed operation=worker.process_job job_id=%s document_id=%s provider=%s",
+            job.id,
+            document.id,
+            result.provider,
+        )
+    except Exception as exc:  # noqa: BLE001
+        match exc:
+            case AppError() as error:
+                pass
+            case _:
+                error = classify_unexpected_error(exc, operation="worker.process_job")
+
+        job = await _finalize_failed(job=job, services=services, error=error, session=session)
+        logger.error(
+            "Job failed operation=worker.process_job job_id=%s document_id=%s error_id=%s category=%s",
+            job.id,
+            document.id,
+            error.error_id,
+            error.category.value,
+        )
+    return job
+
+
+async def process_next_queued_job(
+    *,
+    services: ServiceBundle,
+    settings: Settings | None = None,
+    session: AsyncSession | None = None,
+) -> bool:
+    """Process the next queued job if one exists."""
+    job = await services.jobs.read_next_queued_job(session=session)
+    if job is None:
+        return False
+
+    await advance_job(job=job, services=services, settings=settings, session=session)
+    return True
+
+
+async def _finalize_transcribed(
+    *,
+    job: Job,
+    services: ServiceBundle,
+    result: TranscriptionResult,
+    session: AsyncSession | None = None,
+) -> Job:
+    """Transaction B: transcript + TRANSCRIBED in one commit."""
+    if session is None:
+        async with services.jobs._session_scope() as local_session:
+            prompt_name = result.prompt_name or DEFAULT_PROMPT_FILE
+            await services.transcriptions.upsert_transcript_by_job(
+                job_id=job.id,
+                text=result.text,
+                error_detail=None,
+                provider=result.provider,
+                prompt_name=prompt_name,
+                model=result.model,
+                session=local_session,
+            )
+            await services.transcriptions.append_transcript_revision(
+                job_id=job.id,
+                text=result.text,
+                error_detail=None,
+                provider=result.provider,
+                prompt_name=prompt_name,
+                model=result.model,
+                source="ai",
+                session=local_session,
+            )
+            updated_job = await services.jobs.mark_job_status(
+                job.id,
+                JobStatus.TRANSCRIBED,
+                session=local_session,
+            )
+            await local_session.commit()
+            return updated_job
+
+    prompt_name = result.prompt_name or DEFAULT_PROMPT_FILE
+    await services.transcriptions.upsert_transcript_by_job(
+        job_id=job.id,
+        text=result.text,
+        error_detail=None,
+        provider=result.provider,
+        prompt_name=prompt_name,
+        model=result.model,
+        session=session,
+    )
+    await services.transcriptions.append_transcript_revision(
+        job_id=job.id,
+        text=result.text,
+        error_detail=None,
+        provider=result.provider,
+        prompt_name=prompt_name,
+        model=result.model,
+        source="ai",
+        session=session,
+    )
+    updated_job = await services.jobs.mark_job_status(
+        job.id,
+        JobStatus.TRANSCRIBED,
+        session=session,
+    )
+    await session.commit()
+    return updated_job
+
+
+async def _finalize_retry(
+    *,
+    job: Job,
+    services: ServiceBundle,
+    error: AppError,
+    settings: Settings,
+    session: AsyncSession | None = None,
+) -> Job:
+    """Transaction C: transcript error + QUEUED + retry increment in one commit."""
+    if session is None:
+        async with services.jobs._session_scope() as local_session:
+            provider_name = services.transcriptions.settings.provider.value
+            await services.transcriptions.upsert_transcript_by_job(
+                job_id=job.id,
+                text=None,
+                error_detail=format_error_detail(error),
+                provider=provider_name,
+                prompt_name=DEFAULT_PROMPT_FILE,
+                model=services.transcriptions.settings.provider_model,
+                session=local_session,
+            )
+            await services.transcriptions.append_transcript_revision(
+                job_id=job.id,
+                text=None,
+                error_detail=format_error_detail(error),
+                provider=provider_name,
+                prompt_name=DEFAULT_PROMPT_FILE,
+                model=services.transcriptions.settings.provider_model,
+                source="ai",
+                session=local_session,
+            )
+            updated_job = await services.jobs.update_job_state(
+                job_id=job.id,
+                status=JobStatus.QUEUED,
+                retry_count_increment=1,
+                session=local_session,
+            )
+            await local_session.commit()
+    else:
+        provider_name = services.transcriptions.settings.provider.value
+        await services.transcriptions.upsert_transcript_by_job(
+            job_id=job.id,
+            text=None,
+            error_detail=format_error_detail(error),
+            provider=provider_name,
+            prompt_name=DEFAULT_PROMPT_FILE,
+            model=services.transcriptions.settings.provider_model,
+            session=session,
+        )
+        await services.transcriptions.append_transcript_revision(
+            job_id=job.id,
+            text=None,
+            error_detail=format_error_detail(error),
+            provider=provider_name,
+            prompt_name=DEFAULT_PROMPT_FILE,
+            model=services.transcriptions.settings.provider_model,
+            source="ai",
+            session=session,
+        )
+        updated_job = await services.jobs.update_job_state(
+            job_id=job.id,
+            status=JobStatus.QUEUED,
+            retry_count_increment=1,
+            session=session,
+        )
+        await session.commit()
+
+    if settings.worker_retry_backoff_seconds > 0:
+        await asyncio.sleep(settings.worker_retry_backoff_seconds)
+    return updated_job
+
+
+async def _finalize_failed(
+    *,
+    job: Job,
+    services: ServiceBundle,
+    error: AppError,
+    session: AsyncSession | None = None,
+) -> Job:
+    """Transaction B: transcript error + FAILED in one commit."""
+    if session is None:
+        async with services.jobs._session_scope() as local_session:
+            provider_name = services.transcriptions.settings.provider.value
+            await services.transcriptions.upsert_transcript_by_job(
+                job_id=job.id,
+                text=None,
+                error_detail=format_error_detail(error),
+                provider=provider_name,
+                prompt_name=DEFAULT_PROMPT_FILE,
+                model=services.transcriptions.settings.provider_model,
+                session=local_session,
+            )
+            await services.transcriptions.append_transcript_revision(
+                job_id=job.id,
+                text=None,
+                error_detail=format_error_detail(error),
+                provider=provider_name,
+                prompt_name=DEFAULT_PROMPT_FILE,
+                model=services.transcriptions.settings.provider_model,
+                source="ai",
+                session=local_session,
+            )
+            updated_job = await services.jobs.mark_job_status(
+                job.id,
+                JobStatus.FAILED,
+                session=local_session,
+            )
+            await local_session.commit()
+            return updated_job
+
+    provider_name = services.transcriptions.settings.provider.value
+    await services.transcriptions.upsert_transcript_by_job(
+        job_id=job.id,
+        text=None,
+        error_detail=format_error_detail(error),
+        provider=provider_name,
+        prompt_name=DEFAULT_PROMPT_FILE,
+        model=services.transcriptions.settings.provider_model,
+        session=session,
+    )
+    await services.transcriptions.append_transcript_revision(
+        job_id=job.id,
+        text=None,
+        error_detail=format_error_detail(error),
+        provider=provider_name,
+        prompt_name=DEFAULT_PROMPT_FILE,
+        model=services.transcriptions.settings.provider_model,
+        source="ai",
+        session=session,
+    )
+    updated_job = await services.jobs.mark_job_status(
+        job.id,
+        JobStatus.FAILED,
+        session=session,
+    )
+    await session.commit()
+    return updated_job

src/transcription/ui/__init__.py

@@ -0,0 +1,14 @@
+"""UI page registration exports."""
+
+from fastapi import FastAPI
+from nicegui import ui
+
+from transcription.ui.pages.jobs_page import register_page as register_jobs_page
+from transcription.ui.pages.upload_page import register_page as register_upload_page
+
+
+def register_pages(app: FastAPI) -> None:
+    """Register all NiceGUI pages and mount them onto the FastAPI app."""
+    register_upload_page()
+    register_jobs_page()
+    ui.run_with(app, mount_path="/ui", show_welcome_message=False)

src/transcription/ui/components/error_presenter.py

@@ -0,0 +1,42 @@
+"""Shared UI error rendering helpers."""
+
+from __future__ import annotations
+
+from nicegui import ui
+
+from transcription.errors import AppError
+from transcription.errors import ErrorCategory
+from transcription.errors import classify_unexpected_error
+
+
+def to_app_error(exc: Exception, *, operation: str) -> AppError:
+    """Normalize any exception for consistent UI display."""
+    if isinstance(exc, AppError):
+        return exc
+    return classify_unexpected_error(exc, operation=operation)
+
+
+def show_error(exc: Exception, *, title: str, operation: str) -> None:
+    """Display a visible, actionable UI error with trace id."""
+    error = to_app_error(exc, operation=operation)
+    ui.notify(
+        f"{title}: {error.message} (ref: {error.error_id})",
+        type="negative",
+        timeout=0,
+        close_button="Dismiss",
+    )
+
+    with ui.card().classes("bg-red-1 text-red-10 q-mt-md q-pa-md"):
+        ui.label(title).classes("text-subtitle1")
+        ui.label(error.message)
+        ui.label(f"Suggested action: {error.suggestion}").classes("text-weight-medium")
+        ui.label(f"Error reference: {error.error_id}").classes("text-caption")
+        ui.label(f"Category: {error.category.value}").classes("text-caption")
+
+
+def summarize_error(exc: Exception, *, operation: str) -> str:
+    """Return short one-line summary for status labels."""
+    error = to_app_error(exc, operation=operation)
+    if error.category == ErrorCategory.INTERNAL_UNEXPECTED:
+        return f"Unexpected error (ref: {error.error_id})"
+    return f"{error.message} (ref: {error.error_id})"

src/transcription/ui/components/job_detail.py

@@ -0,0 +1,304 @@
+"""Reusable job detail rendering helpers."""
+
+from __future__ import annotations
+
+import base64
+import mimetypes
+from collections.abc import Awaitable
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+
+from nicegui import ui
+
+from transcription.models import Document
+from transcription.models import Job
+from transcription.models import Transcript
+from transcription.models import TranscriptRevision
+
+
+@dataclass(frozen=True)
+class RevisionDisplayRow:
+    id: str
+    created: str
+    version: str
+    text: str
+    error_detail: str | None
+
+
+def _extract_row_id(args: object) -> str | None:
+    if isinstance(args, dict):
+        if isinstance(args.get("row"), dict):
+            row_id = args["row"].get("id")
+            return str(row_id) if row_id is not None else None
+        row_id = args.get("id")
+        return str(row_id) if row_id is not None else None
+
+    if isinstance(args, list):
+        for value in args:
+            if isinstance(value, dict):
+                row_id = value.get("id")
+                if row_id is not None:
+                    return str(row_id)
+
+    return None
+
+
+def _status_chip_classes(status: str) -> str:
+    if status == "queued":
+        return "bg-blue-1 text-blue-10"
+    if status == "processing":
+        return "bg-amber-1 text-amber-10"
+    if status == "transcribed":
+        return "bg-green-1 text-green-10"
+    if status == "failed":
+        return "bg-red-1 text-red-10"
+    return "bg-grey-2 text-grey-9"
+
+
+def _metadata_row(label: str, value: str) -> None:
+    with ui.row().classes("w-full items-start justify-between no-wrap q-gutter-x-md"):
+        ui.label(label).classes("text-caption text-grey-7 text-uppercase")
+        ui.label(value).classes("text-body2 text-right")
+
+
+def _render_document_section(document: Document) -> None:
+    with ui.card().classes("w-full bg-grey-1 q-pa-md"):
+        ui.label("Document").classes("text-subtitle1 text-weight-medium")
+        ui.separator().classes("q-my-sm")
+        with ui.column().classes("w-full q-gutter-y-xs"):
+            _metadata_row("Filename", document.filename)
+            _metadata_row("File path", document.file_path)
+
+
+def _document_data_url(document: Document) -> tuple[str | None, str | None]:
+    path = Path(document.file_path)
+    if not path.exists() or not path.is_file():
+        return None, "Document preview unavailable: file not found"
+
+    suffix = path.suffix.lower()
+    mime_type, _ = mimetypes.guess_type(path.name)
+    if suffix in {".tif", ".tiff"}:
+        mime_type = "image/tiff"
+    if mime_type is None:
+        return None, "Document preview unavailable: unsupported MIME type"
+
+    encoded = base64.b64encode(path.read_bytes()).decode("ascii")
+    return f"data:{mime_type};base64,{encoded}", None
+
+
+def _render_document_preview(document: Document) -> None:
+    source, error = _document_data_url(document)
+    if error is not None or source is None:
+        ui.label(error or "Document preview unavailable").classes("text-caption text-grey-7")
+        return
+
+    suffix = Path(document.file_path).suffix.lower()
+    if suffix == ".pdf":
+        ui.html(
+            (
+                '<iframe title="Document preview" '
+                f'src="{source}" '
+                'style="width:100%;height:520px;border:1px solid #ddd;border-radius:8px;"></iframe>'
+            )
+        )
+        ui.label("Zoom controls are currently available for image files.").classes("text-caption text-grey-7 q-mt-sm")
+        return
+
+    zoom_percent = {"value": 100}
+
+    with ui.element("div").style(
+        "width:100%;height:520px;overflow:auto;border:1px solid #ddd;border-radius:8px;padding:8px;background:#fafafa;"
+    ):
+        image = ui.image(source).classes("rounded-borders").style("width:100%;max-width:none;")
+
+    zoom_label = ui.label("Zoom: 100%").classes("text-caption text-grey-7 q-mt-sm")
+
+    def _apply_zoom() -> None:
+        image.style(f"width:{zoom_percent['value']}%;max-width:none;")
+        image.update()
+        zoom_label.text = f"Zoom: {zoom_percent['value']}%"
+        zoom_label.update()
+
+    def _zoom_in() -> None:
+        zoom_percent["value"] = min(300, zoom_percent["value"] + 25)
+        _apply_zoom()
+
+    def _zoom_out() -> None:
+        zoom_percent["value"] = max(50, zoom_percent["value"] - 25)
+        _apply_zoom()
+
+    def _zoom_reset() -> None:
+        zoom_percent["value"] = 100
+        _apply_zoom()
+
+    with ui.row().classes("q-gutter-sm q-mt-xs"):
+        ui.button("-", on_click=_zoom_out)
+        ui.button("+", on_click=_zoom_in)
+        ui.button("Reset", on_click=_zoom_reset)
+
+
+def _build_display_rows(transcript: Transcript, revisions: list[TranscriptRevision]) -> list[RevisionDisplayRow]:
+    ordered = sorted(revisions, key=lambda revision: revision.version_number)
+    rows: list[RevisionDisplayRow] = []
+
+    if ordered:
+        first = ordered[0]
+        rows.append(
+            RevisionDisplayRow(
+                id="original",
+                created=first.created_at.isoformat(),
+                version="original",
+                text=first.text or "",
+                error_detail=first.error_detail,
+            )
+        )
+        for revision in ordered[1:]:
+            rows.append(
+                RevisionDisplayRow(
+                    id=str(revision.version_number),
+                    created=revision.created_at.isoformat(),
+                    version=str(revision.version_number),
+                    text=revision.text or "",
+                    error_detail=revision.error_detail,
+                )
+            )
+    else:
+        rows.append(
+            RevisionDisplayRow(
+                id="original",
+                created=transcript.created_at.isoformat(),
+                version="original",
+                text=transcript.text or "",
+                error_detail=transcript.error_detail,
+            )
+        )
+
+    return rows
+
+
+def _render_transcript_versioned_section(
+    *,
+    document: Document | None,
+    transcript: Transcript | None,
+    revisions: list[TranscriptRevision],
+    on_update: Callable[[str], Awaitable[None]] | None,
+) -> None:
+    with ui.card().classes("w-full q-pa-md"):
+        ui.label("Transcript").classes("text-subtitle1 text-weight-medium")
+        ui.separator().classes("q-my-sm")
+
+        if transcript is None:
+            ui.label("Transcript not available yet.").classes("text-body2 text-grey-8")
+            return
+
+        with ui.column().classes("w-full q-gutter-y-xs"):
+            model_name = transcript.model
+            if model_name is None and revisions:
+                model_name = revisions[0].model
+            _metadata_row("Provider", transcript.provider)
+            _metadata_row("Model", model_name or "unknown")
+            _metadata_row("Prompt", transcript.prompt_name)
+
+        display_rows = _build_display_rows(transcript, revisions)
+        rows_by_id = {row.id: row for row in display_rows}
+
+        ui.separator().classes("q-my-sm")
+        ui.label("Versions").classes("text-subtitle2 text-weight-medium")
+        table = ui.table(
+            columns=[
+                {"name": "created", "label": "Created", "field": "created", "align": "left"},
+                {"name": "version", "label": "Version", "field": "version", "align": "left"},
+            ],
+            rows=[
+                {
+                    "id": row.id,
+                    "created": row.created,
+                    "version": row.version,
+                }
+                for row in display_rows
+            ],
+            row_key="id",
+        ).classes("w-full")
+
+        default_selected = display_rows[-1].id
+        selected_label = ui.label(f"Selected version: {rows_by_id[default_selected].version}").classes(
+            "text-caption text-grey-7"
+        )
+
+        ui.separator().classes("q-my-sm")
+        with ui.row().classes("w-full no-wrap items-start q-gutter-md"):
+            if document is not None:
+                with ui.column().classes("w-1/2"):
+                    ui.label("Document Preview").classes("text-subtitle2 text-weight-medium")
+                    _render_document_preview(document)
+
+            with ui.column().classes("w-1/2"):
+                editor = (
+                    ui.textarea(label="Transcript text", value=rows_by_id[default_selected].text)
+                    .props("autogrow outlined")
+                    .classes("w-full")
+                )
+                error_label = ui.label("").classes("text-body2 text-red-10")
+
+        def _set_selected(version_id: str) -> None:
+            selected = rows_by_id.get(version_id)
+            if selected is None:
+                return
+            selected_label.text = f"Selected version: {selected.version}"
+            editor.value = selected.text
+            editor.update()
+            error_label.text = selected.error_detail or ""
+            error_label.update()
+
+        def _on_row_click(event) -> None:  # noqa: ANN001
+            row_id = _extract_row_id(event.args)
+            if row_id is None:
+                return
+            _set_selected(row_id)
+
+        table.on("rowClick", _on_row_click)
+        _set_selected(default_selected)
+
+        if on_update is not None:
+            ui.button("Update", on_click=lambda: on_update(editor.value or ""))
+
+
+def render_job_detail(
+    *,
+    job: Job,
+    document: Document | None,
+    transcript: Transcript | None,
+    revisions: list[TranscriptRevision],
+    on_update: Callable[[str], Awaitable[None]] | None = None,
+) -> None:
+    """Render all sections for the job detail page."""
+    status_text = job.status.value
+    with ui.column().classes("w-full max-w-4xl q-gutter-md"):
+        with ui.card().classes("w-full q-pa-lg"):
+            with ui.row().classes("w-full items-center justify-between q-gutter-md"):
+                with ui.column().classes("q-gutter-none"):
+                    ui.label("Job overview").classes("text-h6 text-weight-bold")
+                    ui.label(str(job.id)).classes("text-caption text-grey-7")
+                status_chip_classes = (
+                    "q-px-sm q-py-xs rounded-borders "
+                    "text-weight-medium text-capitalize "
+                    f"{_status_chip_classes(status_text)}"
+                )
+                ui.label(status_text).classes(status_chip_classes)
+
+            ui.separator().classes("q-my-md")
+            with ui.column().classes("w-full q-gutter-y-xs"):
+                _metadata_row("Created", job.created_at.isoformat())
+                _metadata_row("Updated", job.updated_at.isoformat())
+                _metadata_row("Retries", str(job.retry_count))
+
+        if document is not None:
+            _render_document_section(document)
+
+        _render_transcript_versioned_section(
+            document=document,
+            transcript=transcript,
+            revisions=revisions,
+            on_update=on_update,
+        )

src/transcription/ui/components/table/__init__.py

@@ -0,0 +1,4 @@
+from .jobs import JobTableRow
+from .jobs import render_jobs_table
+
+__all__ = ["JobTableRow", "render_jobs_table"]

src/transcription/ui/components/table/common.py

@@ -0,0 +1,68 @@
+"""Common logic for generating table widgets."""
+
+from collections.abc import Callable
+from typing import Any
+
+from nicegui import events
+from nicegui import ui
+
+
+def _extract_row_id(args: Any) -> str | None:
+    if isinstance(args, dict):
+        if isinstance(args.get("row"), dict):
+            row_id = args["row"].get("id")
+            return str(row_id) if row_id is not None else None
+        row_id = args.get("id")
+        return str(row_id) if row_id is not None else None
+
+    if isinstance(args, list):
+        for value in args:
+            if isinstance(value, dict):
+                row_id = value.get("id")
+                if row_id is not None:
+                    return str(row_id)
+
+    return None
+
+
+def _bind_row_click_handler(
+    table: Any,
+    *,
+    on_row_click_id: Callable[[str], None],
+) -> None:
+    def handle_row_click(event: events.GenericEventArguments) -> None:
+        row_id = _extract_row_id(event.args)
+        if row_id is None:
+            return
+        on_row_click_id(row_id)
+
+    table.on("rowClick", handle_row_click)
+
+
+def build_table(
+    rows: list[dict[str, Any]],
+    columns: list[dict[str, Any]],
+    *,
+    default_sort_by: str | None = None,
+    default_descending: bool = False,
+    classes: str = "app-table",
+    on_row_click_id: Callable[[str], None] | None = None,
+) -> Any:
+    pagination: dict[str, Any] = {"rowsPerPage": 25}
+    if default_sort_by is not None:
+        pagination["sortBy"] = default_sort_by
+        pagination["descending"] = default_descending
+
+    table = (
+        ui.table(
+            rows=rows,
+            columns=columns,
+            row_key="id",
+            pagination=pagination,
+        )
+        .classes(classes)
+        .props('table-style="table-layout: fixed; width: 100%;"')
+    )
+    if on_row_click_id is not None:
+        _bind_row_click_handler(table, on_row_click_id=on_row_click_id)
+    return table

src/transcription/ui/components/table/jobs.py

@@ -0,0 +1,75 @@
+"""Jobs table rendering helpers."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from datetime import UTC
+from datetime import datetime
+from typing import Any
+from uuid import UUID
+
+from nicegui import ui
+
+from .common import build_table
+
+
+@dataclass(frozen=True, slots=True)
+class JobTableRow:
+    """Read model consumed by the jobs table component."""
+
+    id: UUID
+    status: str
+    filename: str
+    retry_count: int
+    created_at: str
+    updated_at: str
+
+
+def _format_timestamp(value: str) -> str:
+    """Return a friendly UTC timestamp for table display."""
+    try:
+        parsed = datetime.fromisoformat(value)
+    except ValueError:
+        return value
+    parsed = parsed.replace(tzinfo=UTC) if parsed.tzinfo is None else parsed.astimezone(UTC)
+    return parsed.astimezone().strftime("%b %d, %I:%M %p")
+
+
+def _serialize_rows(rows: Sequence[JobTableRow]) -> list[dict[str, Any]]:
+    return [
+        {
+            "id": str(row.id),
+            "status": row.status,
+            "filename": row.filename,
+            "retry_count": row.retry_count,
+            "created_at": _format_timestamp(row.created_at),
+            "updated_at": _format_timestamp(row.updated_at),
+            "created_sort": row.created_at,
+            "updated_sort": row.updated_at,
+        }
+        for row in rows
+    ]
+
+
+def render_jobs_table(rows: Sequence[JobTableRow]) -> None:
+    """Render jobs table and open a detail page when clicking a row."""
+    if not rows:
+        ui.label("No jobs yet.")
+        return
+
+    build_table(
+        rows=_serialize_rows(rows),
+        columns=[
+            {"name": "id", "label": "Job ID", "field": "id", "sortable": True},
+            {"name": "status", "label": "Status", "field": "status", "sortable": True},
+            {"name": "filename", "label": "Filename", "field": "filename", "sortable": True},
+            {"name": "retry_count", "label": "Retries", "field": "retry_count", "sortable": True},
+            {"name": "created_at", "label": "Created", "field": "created_at", "sortable": True},
+            {"name": "updated_at", "label": "Updated", "field": "updated_at", "sortable": True},
+        ],
+        default_sort_by="created_sort",
+        default_descending=True,
+        classes="app-table w-full",
+        on_row_click_id=lambda job_id: ui.navigate.to(f"/jobs/{job_id}"),
+    )

src/transcription/ui/components/upload.py

@@ -0,0 +1,66 @@
+"""Reusable upload widget for document submission."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable
+from collections.abc import Callable
+
+from nicegui import ui
+from nicegui.binding import bindable_dataclass
+from nicegui.events import UploadEventArguments
+
+from transcription.errors import AppError
+from transcription.services.documents import UploadJobResult
+from transcription.ui.components.error_presenter import show_error
+from transcription.ui.components.error_presenter import summarize_error
+from transcription.worker import WorkerNotifier
+
+type UploadSubmitter = Callable[[str, bytes], Awaitable[UploadJobResult]]
+
+
+@bindable_dataclass
+class UploadWidgetState:
+    """Simple state container for upload feedback."""
+
+    loading: bool = False
+    message: str = ""
+
+
+def render_upload_widget(*, submitter: UploadSubmitter, notifier: WorkerNotifier | None = None) -> None:
+    """Render upload controls and common status/error handling."""
+    state = UploadWidgetState()
+    status_label = ui.label("Upload a document to start transcription.")
+    status_label.bind_text(state, "message")
+
+    async def on_upload(event: UploadEventArguments) -> None:
+        if state.loading:
+            ui.notify("Upload already in progress. Please wait.", type="warning")
+            return
+
+        state.loading = True
+        status_label.text = "Uploading..."
+        try:
+            payload = await event.file.read()
+            result = await submitter(event.file.name, payload)
+            job_id = result.job_id
+            state.message = f"Created job {job_id}" if job_id is not None else "Upload complete"
+            status_label.text = state.message
+            if notifier is not None:
+                notifier.notify()
+            ui.notify(state.message, type="positive")
+        except AppError as exc:
+            state.message = summarize_error(exc, operation="upload.submit")
+            status_label.text = f"Upload failed: {state.message}"
+            show_error(exc, title="Upload failed", operation="upload.submit")
+        except Exception as exc:  # noqa: BLE001
+            state.message = summarize_error(exc, operation="upload.submit")
+            status_label.text = f"Upload failed: {state.message}"
+            show_error(exc, title="Upload failed", operation="upload.submit")
+        finally:
+            state.loading = False
+
+    ui.upload(
+        on_upload=on_upload,
+        auto_upload=True,
+        label="Select document file",
+    ).props('accept=".jpg,.jpeg,.png,.tif,.tiff,.pdf"')

src/transcription/ui/pages/jobs_page.py

@@ -0,0 +1,163 @@
+"""Jobs list and detail page registration."""
+
+from __future__ import annotations
+
+from uuid import UUID
+
+from nicegui import ui
+from sqlalchemy.orm import selectinload
+from sqlmodel import desc
+from sqlmodel import select
+
+from transcription.db import get_session
+from transcription.models import Document
+from transcription.models import Job
+from transcription.models import Transcript
+from transcription.models import TranscriptRevision
+from transcription.services import ServiceBundle
+from transcription.ui.components.error_presenter import show_error
+from transcription.ui.components.error_presenter import summarize_error
+from transcription.ui.components.job_detail import render_job_detail
+from transcription.ui.components.table.jobs import JobTableRow
+from transcription.ui.components.table.jobs import render_jobs_table
+
+
+async def fetch_job_rows() -> list[JobTableRow]:
+    """Return jobs for display in most-recent-first order."""
+    async with get_session() as session:
+        jobs = (
+            await session.exec(
+                select(Job)
+                .options(selectinload(Job.document))  # pyright: ignore[reportArgumentType]
+                .order_by(desc(Job.created_at))
+            )
+        ).all()
+        return [
+            JobTableRow(
+                id=job.id,
+                status=job.status.value,
+                filename=job.filename,
+                retry_count=job.retry_count,
+                created_at=job.created_at.isoformat(),
+                updated_at=job.updated_at.isoformat(),
+            )
+            for job in jobs
+        ]
+
+
+async def fetch_job_detail(job_id: UUID) -> tuple[Job | None, Document | None, Transcript | None, list[TranscriptRevision]]:
+    """Return job, document, transcript snapshot, and revisions for detail view."""
+    async with get_session() as session:
+        job = await session.get(Job, job_id)
+        if job is None:
+            return None, None, None, []
+        document = await session.get(Document, job.document_id)
+        transcript = (await session.exec(select(Transcript).where(Transcript.job_id == job.id))).first()
+        revisions = (
+            await session.exec(
+                select(TranscriptRevision)
+                .where(TranscriptRevision.job_id == job.id)
+                .order_by(TranscriptRevision.version_number)
+            )
+        ).all()
+        return job, document, transcript, list(revisions)
+
+
+def register_page() -> None:
+    """Register jobs list and detail routes."""
+
+    @ui.page("/jobs")
+    async def jobs_page() -> None:
+        ui.label("Transcription Jobs")
+        status = ui.label("Ready")
+
+        @ui.refreshable
+        async def render_table() -> None:
+            jobs = await fetch_job_rows()
+            render_jobs_table(jobs)
+
+        async def refresh() -> None:
+            status.text = "Refreshing..."
+            try:
+                await render_table.refresh()
+                status.text = "Refreshed"
+            except Exception as exc:  # noqa: BLE001
+                status.text = f"Refresh failed: {summarize_error(exc, operation='jobs.refresh')}"
+                show_error(exc, title="Jobs refresh failed", operation="jobs.refresh")
+
+        ui.button("Refresh", on_click=refresh)
+        await render_table()
+        ui.link("Back to upload", "/upload")
+
+    @ui.page("/jobs/{job_id}")
+    async def job_detail_page(job_id: str) -> None:
+        ui.label("Job Detail")
+        content = ui.column().classes("w-full")
+        try:
+            parsed_id = UUID(job_id)
+        except ValueError:
+            ui.label("Invalid job id")
+            ui.link("Back to jobs", "/jobs")
+            return
+
+        async def refresh_content() -> None:
+            content.clear()
+            job, document, transcript, revisions = await fetch_job_detail(parsed_id)
+            if job is None:
+                with content:
+                    ui.label("Job not found")
+                return
+
+            services = ServiceBundle()
+
+            async def update_transcript_text(value: str) -> None:
+                try:
+                    update_text = value.strip()
+                    async with get_session() as session:
+                        current_transcript = (
+                            await session.exec(select(Transcript).where(Transcript.job_id == parsed_id))
+                        ).first()
+                        provider_name = current_transcript.provider if current_transcript is not None else "openrouter"
+                        prompt_name = (
+                            current_transcript.prompt_name if current_transcript is not None else "transcribe_document.md"
+                        )
+                        model_name = current_transcript.model if current_transcript is not None else None
+
+                        await services.transcriptions.upsert_transcript_by_job(
+                            job_id=parsed_id,
+                            text=update_text,
+                            error_detail=None,
+                            provider=provider_name,
+                            prompt_name=prompt_name,
+                            model=model_name,
+                            session=session,
+                        )
+                        await services.transcriptions.append_transcript_revision(
+                            job_id=parsed_id,
+                            text=update_text,
+                            error_detail=None,
+                            provider=provider_name,
+                            prompt_name=prompt_name,
+                            model=model_name,
+                            source="user",
+                            session=session,
+                        )
+                        await session.commit()
+
+                    ui.notify("Transcript updated", type="positive")
+                    await refresh_content()
+                except Exception as exc:  # noqa: BLE001
+                    show_error(exc, title="Transcript update failed", operation="jobs.detail.update")
+
+            with content:
+                render_job_detail(
+                    job=job,
+                    document=document,
+                    transcript=transcript,
+                    revisions=revisions,
+                    on_update=update_transcript_text,
+                )
+
+        await refresh_content()
+
+        ui.link("Back to jobs", "/jobs")

src/transcription/ui/pages/upload_page.py

@@ -0,0 +1,34 @@
+"""Upload page registration and handlers."""
+
+from __future__ import annotations
+
+from fastapi import Request
+from nicegui import ui
+
+from transcription.app_state import resolve_session_factory
+from transcription.db import get_session
+from transcription.services.store import create_upload_job
+from transcription.ui.components.upload import render_upload_widget
+from transcription.worker import resolve_worker_notifier
+
+
+def register_page() -> None:
+    """Register the upload page route."""
+
+    @ui.page("/upload", title="Upload Document")
+    def upload_page(request: Request) -> None:
+        session_factory = resolve_session_factory(request.app.state)
+
+        async def submit_upload(filename: str, file_bytes: bytes):
+            async with get_session(session_factory=session_factory) as session:
+                return await create_upload_job(
+                    filename=filename,
+                    file_bytes=file_bytes,
+                    session=session,
+                )
+
+        notify_worker = resolve_worker_notifier(request.app.state)
+        render_upload_widget(submitter=submit_upload, notifier=notify_worker)
+
+        with ui.row():
+            ui.link("View jobs", "/jobs")

src/transcription/worker.py

@@ -0,0 +1,184 @@
+"""Background worker for queued transcription jobs."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+from contextlib import contextmanager
+from contextlib import suppress
+from typing import Protocol
+from uuid import UUID
+
+from sqlalchemy.ext.asyncio import async_sessionmaker
+from sqlmodel.ext.asyncio.session import AsyncSession
+
+from transcription.db import get_session
+from transcription.errors import AppError
+from transcription.errors import classify_unexpected_error
+
+from .services import ServiceBundle
+from .services.documents import DocumentService
+from .services.jobs import JobService
+from .services.transcription import TranscriptionService
+from .services.workflows import advance_job
+from .services.workflows import process_next_queued_job as process_next_queued_job_workflow
+
+logger = logging.getLogger(__name__)
+
+
+class WorkerNotifier(Protocol):
+    """Abstraction for signaling the worker loop about new work."""
+
+    def notify(self) -> None:
+        """Signal the worker loop that work may be available."""
+
+
+class EventWorkerNotifier:
+    """Worker notifier backed by an asyncio.Event."""
+
+    def __init__(self, wake_event: asyncio.Event):
+        self._wake_event = wake_event
+
+    def notify(self) -> None:
+        self._wake_event.set()
+
+
+class NoopWorkerNotifier:
+    """Fallback notifier used when worker signaling is unavailable."""
+
+    def notify(self) -> None:
+        return
+
+
+def resolve_worker_notifier(state: object) -> WorkerNotifier:
+    """Resolve notifier from app-like state objects with no-op fallback."""
+    notifier = getattr(state, "worker_notifier", None)
+    if isinstance(notifier, NoopWorkerNotifier):
+        return notifier
+    if notifier is None:
+        return NoopWorkerNotifier()
+    return notifier
+
+
+@asynccontextmanager
+async def worker_consumer_lifespan(
+    *,
+    session_factory: async_sessionmaker[AsyncSession] | None = None,
+    poll_interval_seconds: float = 1.0,
+) -> AsyncGenerator[tuple[asyncio.Event, WorkerNotifier]]:
+    """Start and stop the worker consumer loop for app lifespan."""
+    stop_event = asyncio.Event()
+    wake_event = asyncio.Event()
+    worker_notifier: WorkerNotifier = EventWorkerNotifier(wake_event)
+    worker_task = asyncio.create_task(
+        run_worker_loop(
+            session_factory=session_factory,
+            stop_event=stop_event,
+            wake_event=wake_event,
+            poll_interval_seconds=poll_interval_seconds,
+        )
+    )
+    worker_notifier.notify()
+
+    try:
+        yield stop_event, worker_notifier
+    finally:
+        stop_event.set()
+        worker_notifier.notify()
+        try:
+            await asyncio.wait_for(worker_task, timeout=2.0)
+        except TimeoutError:
+            worker_task.cancel()
+            with suppress(asyncio.CancelledError):
+                await worker_task
+
+
+async def queue_consumer_loop(queue: asyncio.Queue[UUID], stop_event: asyncio.Event):
+    """Main worker loop that consumes jobs from the queue and processes them.
+
+    The queue is for Job UUIDs, and the corresponding documents should already have been uploaded.
+    """
+    service = JobService()
+    while not stop_event.is_set():
+        with handle_worker_exceptions():
+            async with _get_queue_item(queue) as job_id:
+                job = await service.read_job(job_id)
+                asyncio.create_task(advance_job(job=job, services=ServiceBundle()))
+
+
+@contextmanager
+def handle_worker_exceptions(operation: str = "worker.loop"):
+    """Context manager to log and suppress exceptions in the worker loop."""
+    try:
+        yield
+    except Exception as exc:
+        error = exc if isinstance(exc, AppError) else classify_unexpected_error(exc, operation=operation)
+        logger.exception(
+            "Worker loop exception error_id=%s category=%s",
+            error.error_id,
+            error.category.value,
+        )
+
+
+@asynccontextmanager
+async def _get_queue_item(queue: asyncio.Queue[UUID]) -> AsyncGenerator[UUID]:
+    """Context manager to enqueue a job and ensure it is marked done."""
+    yield await queue.get()
+    queue.task_done()
+
+
+async def run_worker_loop(
+    *,
+    session_factory: async_sessionmaker[AsyncSession] | None = None,
+    stop_event: asyncio.Event | None = None,
+    wake_event: asyncio.Event | None = None,
+    poll_interval_seconds: float = 1.0,
+) -> None:
+    """Run worker loop until stop_event is set.
+
+    If wake_event is provided, signal activity wakes the loop immediately while
+    timeout-based wakeups preserve current polling behavior.
+    """
+    while True:
+        if stop_event is not None and stop_event.is_set():
+            logger.info("Worker stop event received")
+            return
+
+        if wake_event is not None:
+            with suppress(TimeoutError):
+                await asyncio.wait_for(wake_event.wait(), timeout=poll_interval_seconds)
+                wake_event.clear()
+
+        processed_any = False
+        while await process_next_queued_job(session_factory=session_factory):
+            processed_any = True
+
+        if wake_event is None and not processed_any:
+            await asyncio.sleep(poll_interval_seconds)
+
+
+async def process_next_queued_job(
+    *,
+    session: AsyncSession | None = None,
+    session_factory: async_sessionmaker[AsyncSession] | None = None,
+) -> bool:
+    """Process the next queued job and persist terminal outcome.
+
+    Returns True when a job was processed, False when no queued job exists.
+    """
+    if session_factory is None:
+        services = ServiceBundle()
+    else:
+        services = ServiceBundle(
+            documents=DocumentService(session_factory=session_factory),
+            jobs=JobService(session_factory=session_factory),
+            transcriptions=TranscriptionService(session_factory=session_factory),
+        )
+
+    if session is None:
+        async with get_session(session_factory=session_factory) as local_session:
+            return await process_next_queued_job_workflow(services=services, session=local_session)
+
+    return await process_next_queued_job_workflow(services=services, session=session)

tests/api/test_error_responses.py

@@ -0,0 +1,56 @@
+"""Tests for API error response envelope handlers."""
+
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+import pytest
+
+from transcription.api.errors import register_error_handlers
+from transcription.errors import AppError, ErrorCategory
+
+
+@pytest.mark.integration
+class TestApiErrorResponses:
+    """Verify API-level error serialization and status mapping."""
+
+    def test_app_error_returns_structured_envelope(self):
+        """AppError maps to policy envelope fields and status code."""
+        app = FastAPI()
+        register_error_handlers(app)
+
+        @app.get("/boom")
+        def boom() -> dict[str, str]:
+            raise AppError(
+                "Bad upload payload",
+                category=ErrorCategory.VALIDATION,
+                suggestion="Upload a non-empty file",
+                error_id="abc12345",
+            )
+
+        client = TestClient(app)
+        response = client.get("/boom")
+
+        assert response.status_code == 400
+        payload = response.json()
+        assert payload["error_id"] == "abc12345"
+        assert payload["category"] == "validation_error"
+        assert payload["message"] == "Bad upload payload"
+        assert payload["suggestion"] == "Upload a non-empty file"
+        assert "timestamp" in payload
+
+    def test_unexpected_error_returns_internal_unexpected_envelope(self):
+        """Unexpected exceptions map to internal_unexpected_error with 500."""
+        app = FastAPI()
+        register_error_handlers(app)
+
+        @app.get("/explode")
+        def explode() -> dict[str, str]:
+            raise RuntimeError("unexpected failure")
+
+        client = TestClient(app, raise_server_exceptions=False)
+        response = client.get("/explode")
+
+        assert response.status_code == 500
+        payload = response.json()
+        assert payload["category"] == "internal_unexpected_error"
+        assert "error_id" in payload
+        assert payload["suggestion"]

tests/api/test_health.py

@@ -0,0 +1,21 @@
+"""Tests for transcription.api.health."""
+
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from transcription.api.health import router
+
+
+class TestHealthEndpoint:
+    """Verify /healthz endpoint behavior."""
+
+    def test_healthz_returns_ok_status(self):
+        """GET /healthz returns a healthy status payload."""
+        app = FastAPI()
+        app.include_router(router)
+        client = TestClient(app)
+
+        response = client.get("/healthz")
+
+        assert response.status_code == 200
+        assert response.json() == {"status": "ok"}

tests/artifacts/transcriptions/Book_Two_-_page_02.jpg.txt

@@ -0,0 +1,42 @@
+source: Book Two - page 02.jpg
+provider: openrouter
+model: google/gemini-2.5-flash
+---
+BY WAY OF INTRODUCTION:-
+
+These few paragraphs of introduction may help you read BOOK 2 which covers a
+wider range than did BOOK 1 (Pioneer Days).
+
+BOOK 1 had 54 pages; 14 chapters. BOOK 2 has 70 pages; 18 chapters. BOOK 1 con-
+sisted largely of first generation family history. BOOK 2 throws more light on
+the second generation. Sidney promises a BOOK 3 and that may begin to do justice
+to the third generation. We suggest that Sidney get the help of Louis Shinn
+who has a chapter in this book (Chapter 16 - The Last 25 Years on the Doumeeq
+Plains. Louis has the gift of seeing, recalling and telling. One sentence in
+his chapter gives a great tribute to the Doumeeqers - so far as he knows no one
+on the Doumeeq Plains went on relief during the depression. That in a nutshell
+shows the sturdy character of the residents of the Doumeeq Plains.
+
+We promised in BOOK 1 that in BOOK 2 we would give the story of the trip of
+John E. Cochran and wife to Tennessee, Cuba and the Panama Canal. You will see
+by the Table of Contents that the first four chapters have been given to those
+trips. Those chapters are worth reading and re-reading. Mr. Cochran has eyes
+to see and a pen to tell. We think the people in Tennessee will read with
+great pleasure the comments he makes on conditions today.
+
+Some who get this book will consider the group picture the best thing in the
+book. It took a lot of preliminary photographing to reduce some pictures, enlarge
+others and bring out the tin types. We wish that instead of 44 faces we could
+have given 88. Do not blame Ethel Cochran-Shinn for the selection. She furnished
+enough pictures but we had to take only part of them. We think there are great
+possibilities in reproducing old pictures. We wish we had a Pickard group. Some
+Pickard descendant may wish to make a collection.
+
+We are much impressed with the future possibilities of getting a complete geneol-
+ogy of the Pickard family. Mr. Cochran has a fine chapter on the Pickards but
+to date we have not had the pleasure of finding all of the family dates. We had
+intended to give more family data in this book but it takes time to get the
+correct dates. Often times it requires trips to cemeteries to get dates on the
+tombstones. Winter is no time to collect dates on tombstones.
+
+-2-

tests/artifacts/transcriptions/Omie_Writes_Home.pdf.txt

@@ -0,0 +1,116 @@
+source: Omie Writes Home.pdf
+provider: openrouter
+model: google/gemini-2.5-flash
+---
+JOHN E. COCHRAN
+FAMILY ASSOCIATION
+Family Only
+Home | Sibling's Stories | 1st Cousins | Ancestor's Stories | Reunion History | Next Reunion | JECMEF
+
+OMIE WRITES HOME
+
+Ed. Note: The following letter was written by Omie Cochran in Nome, Alaska and sent to her
+sister, Ethel Shinn, in Canfield, Idaho in 1923. It has been stored away these 63 years in the
+original envelope with its 2 cent stamp. The letter has a number of references to the Shinn
+children. Peter was Louis; Polly was Edith; and the 'little black rascal' referred to Maurice.
+Miss Saville was the nurse at the Nome Hospital that was mentioned in the article by Inez in
+the family newsletter two years ago.
+
+Nome Alaska August 26, 1923
+My Dear Ethel et al.
+
+I don't know when I did write or when you did
+but I am going to write now however and never
+the less. But I wish I could talk (I can yet but I
+mean to tell you all) instead and see ole Unc Pete
+and Polly sit up and listen and that little black
+rascal of yours would fairly sparkle with
+listening. Can't I see him listening now to all the
+yarns we told last summer?
+
+You see, we-Miss Saville and I, took a trip north
+on the Buford and it was very interesting. We
+went north thru the Bering Strait into the Arctic and as far as the Ice Pack. There the captain
+of our craft and some other mighty hunters went out first in kayaks and later in row boats and
+shot seven walrus. When they also took a movie man and camera, so you will likely see all
+this in the movies before I get to tell you. They came back on board and the ship went up
+along the icebergs and the walrus were 'heisted' on board by the use of the crane which loads
+tons of freight and the beasts were so huge that they made the pulleys just creak. They were
+over 12 feet long, as big around as three cows, had no feet but toenails on their flippers or
+flappers, no head but their body just suddenly ended with a hole for a mouth and big bristles
+
+all around it similar to a currycomb in coarseness; no ears but huge tusks of ivory. They are
+the most repulsive looking animals imaginable and tho I have always read about them I never
+expect such disagreeable looking creatures. They had a rough brown hairy skin and some of
+them looked warty. They must have weighed two ton at least. Ere we got them back to Nome
+to the natives they were getting extremely odiferous–in fact, you could scarcely stay on the
+ship with any degree of comfort unless you had per chance lost your sense of smell.
+
+Then we went north to a few minutes beyond the 70th degree of latitude and thot [sic] for awhile
+we would go to Wrangell Island where some men from Stefflonsons [sic] ship were supposed to be
+stranded but we didn't get there and instead stopped at a small native village at Cape Serdz [sic] in
+Siberia. These Eskimo were very primitive. One white squaw man lived there and had for 23
+years. He was a Swede–who else could. Their houses were circular and built up with dirt 2 or
+3 feet and then skins were stretched over it and weighted down with rocks. Inside, the room
+was partitioned off at the sides with skins for sleeping quarters. In the main part they had the
+fire on the ground and the fish drying on lines and the skins hanging around and the dogs and
+babies and children. They wore skin clothes entirely. The women's were made like bloomers
+and were heavily padded for warmth. They wore high mukluks and really looked very
+comfortable. The babies were in fur skins with the fur inside and they looked like little Teddy
+bears with faces. I guess they had never seen white women, not so many at one time anyway.
+We went ashore in 2 life boats and a launch pulling them. On the launch was a six piece band
+playing and the rear of the last life boat was the movie man. 'Twas very thrilling.
+
+The other place we stopped was at Whalen, a trading post in Siberia. There these 'towerists'
+went wild. They rushed helter-skelter, hither and thither, here and there, trying to find
+something to buy. Prices raised right before your eyes. One would but something for $1.00
+and the next might have to pay $2.00, $4.00 or $10.00. That made no difference. They had to
+have it. One man I was sort of taking care of, tho [sic] he had his son along for the purpose,
+bought 2 ivory tusks, 1 pup, 2 moccasins, 3 or 4 billi[illegible]s, 6 or 8 ivory and silver rings, one
+fishing line, hooks, floats, etc. and two bird slings. The slings have rocks at the end and the
+little natives throw them at the flocks of geese and ducks which fly close over the village and
+the slings entangle their wings and legs, sometimes more than one, and they can't fly. They
+come down and the natives capture them. There was more junk brot [sic] aboard than baggage, I
+do believe. And they say that at the first stop it was worse than here. The red flag was flying
+over Whalen and the Russian soldiers were there–a few, one or two or three, I forget the
+number.
+
+We got home yesterday morning at 5 a.m. but missed the first lighter in so had to stay out
+until 2:30. The girls had prepared a big meal for us and invited up the Hartfords and then let
+us talk. Miss Saville talked quite a bit. Any how if you folks don't like this I don't care, it is
+all I had to write about and I know Buster'd [sic] listen anyway and I'd soak ole Peter's head if he
+didn't and Polly would in my lap and I don't know much about the youngest one of yours so
+likely he would be squawling. But we did surely enjoy our trip and were gone just long enuf [sic].
+
+I expect there were 150 passengers on board and almost or more of the crew and helpers. We
+had a stateroom down next to the kitchen and 'twas pretty fierce for odor at times.
+
+I have had jobs nearly all summer but not very much in them. Next week, September 4,
+school opens. I wish they would wait for a week but you know these school men. Wouldn't
+make any special difference I suppose for I would just fritter away the time but still one likes
+to postpone the inevitable.
+
+I just now stopped and re-read your letter and it sure was a bird. I don't especially blame Ray
+for reading over your shoulder. It would seem, then that you have bright children. Maybe
+they do know something about Geography. But it is ridiculous to speak of Louis finishing the
+eighth grade. Why you and I were grown children when we finished and he is only a baby. I
+am rather afraid he doesn't know much. I quite remember your little timid Maurice and how
+he shifted his affection from his Aunt Om and yelled and howled and screamed steadily for a
+week while his mother went to S.S. Ask him is he recalls this little interview. Do you suppose
+he does?
+
+Ever hear from Zen? or Inez? They don't seem to be very writing inclined tho Zen has done
+well this year. Even sent me a telegram a few weeks ago. Well, if anything else ever happens,
+I'll write again. Don't suppose it ever will, tho.
+
+Lots of love to all,
+
+Ome
+
+Reprinted from Cochran Chronicles, Volume 9, Number 1, November 1986
+
+© [inserted: JECFA] 1986
+
+Up
+
+jecochranclan.org ~ Contact webmaster

tests/artifacts/transcriptions/Rod_Moser_Letter_-_p1.jpg.txt

@@ -0,0 +1,31 @@
+source: Rod Moser Letter - p1.jpg
+provider: openrouter
+model: google/gemini-2.5-flash
+---
+JOHN ISBILL
+R. T. MOSER
+ISBILL & MOSER
+DEALERS IN
+GENERAL MERCHANDISE
+
+Vonore, Tenn., Jany 27- 1913
+Dear Much Aunt Louie
+How are you a
+few nights ago I sewed a
+letter from your folks, so
+I decided to write you
+a few lines myself ok
+I am contemplateing a
+trip out west next summer
+& I want Some Olders to go
+where I and them.
+
+I am getting
+up in years & unmarried
+so you see the object of
+my trip, is to get a bunch
+of Young & old maids
+& widows out there. I
+want you to kiss them
+at my fans [sic] mug as they
+as soon as I get there

tests/conftest.py

@@ -0,0 +1,71 @@
+"""Shared test fixtures.
+
+Every test gets a fresh in-memory SQLite database so tests are
+isolated, fast, and leave no artifacts on disk.
+"""
+
+import pytest
+import pytest_asyncio
+from sqlmodel import Session
+from sqlmodel import SQLModel
+from sqlmodel import create_engine
+from sqlmodel.pool import StaticPool
+
+from transcription.config import Settings
+from transcription.config import get_settings
+from transcription.db.operations import create_all
+from transcription.db.runtime import dispose_database_runtime
+from transcription.db.runtime import get_engine
+from transcription.db.runtime import get_session
+from transcription.db.runtime import get_session_factory
+from transcription.services.documents import DocumentService
+from transcription.services.jobs import JobService
+
+
+@pytest.fixture
+def session():
+    """Provide a clean synchronous database session for sync tests."""
+    engine = create_engine(
+        "sqlite://",
+        connect_args={"check_same_thread": False},
+        poolclass=StaticPool,
+    )
+    SQLModel.metadata.create_all(engine)
+    with Session(engine) as sync_session:
+        yield sync_session
+
+
+@pytest_asyncio.fixture
+async def default_settings():
+    """Provide default settings for tests."""
+    settings = get_settings(database_url="sqlite:///:memory:")
+    await create_all(engine=get_engine(settings=settings))
+    return settings
+
+
+@pytest_asyncio.fixture
+async def async_session(default_settings: Settings):
+    """Provide a clean asynchronous database session for async tests."""
+    async with get_session(settings=default_settings) as async_session:
+        yield async_session
+
+    await dispose_database_runtime()
+
+
+@pytest.fixture
+def default_session_factory(default_settings: Settings):
+    """Provide a base fixture for tests that require database access."""
+    session_factory = get_session_factory(settings=default_settings)
+    return session_factory
+
+
+@pytest.fixture
+def job_service(default_session_factory) -> JobService:
+    """Provide a JobService instance for testing."""
+    return JobService(session_factory=default_session_factory)
+
+
+@pytest.fixture
+def document_service(default_session_factory) -> DocumentService:
+    """Provide a DocumentService instance for testing."""
+    return DocumentService(session_factory=default_session_factory)

tests/fixtures/images/invalid/wrong_extension.txt

@@ -0,0 +1 @@
+not an image fixture

tests/fixtures/images/valid/single_page_pdf.pdf

@@ -0,0 +1,2 @@
+%PDF-1.4
+%fixture

tests/fixtures/images/valid/small_jpg.jpg

@@ -0,0 +1 @@
+˙Ř˙ŕfixture

tests/fixtures/images/valid/small_png.png

@@ -0,0 +1,3 @@
+‰PNG
+
+fixture

tests/fixtures/prompts/valid/transcribe_document_min.md

@@ -0,0 +1,6 @@
+# Minimal Verbatim Prompt
+
+Transcribe the document verbatim.
+Do not summarize or paraphrase.
+Mark uncertain text using square brackets and a question mark.
+Mark unreadable text as [illegible].

tests/integration/test_pipeline_flow.py

@@ -0,0 +1,107 @@
+"""Integration tests for end-to-end upload and worker pipeline behavior."""
+
+from pathlib import Path
+
+import pytest
+from sqlmodel import select
+
+from transcription.config import Settings
+from transcription.models import Job, JobStatus, Transcript, TranscriptRevision
+from transcription.providers.base import TranscriptionResult
+from transcription.services.store import create_upload_job
+from transcription.worker import process_next_queued_job
+
+
+@pytest.mark.integration
+class TestPipelineSuccessFlow:
+    """Verify end-to-end success lifecycle behavior."""
+
+    @pytest.mark.asyncio
+    async def test_upload_then_worker_persists_transcribed_terminal_state(self, async_session, tmp_path: Path, monkeypatch):
+        """Upload followed by worker processing persists transcript and transcribed status."""
+        settings = Settings(openrouter_api_key="test-key", upload_dir=tmp_path)
+        upload_result = await create_upload_job(
+            filename="pipeline.jpg",
+            file_bytes=b"pipeline-bytes",
+            session=async_session,
+            settings=settings,
+        )
+
+        async def _fake_transcribe(_path: str) -> TranscriptionResult:
+            return TranscriptionResult(
+                text="Pipeline transcript",
+                provider="openrouter",
+                prompt_name="transcribe_document.md",
+                model="test-model",
+            )
+
+        monkeypatch.setattr("transcription.services.workflows.transcribe_document_image", _fake_transcribe)
+
+        processed = await process_next_queued_job(session=async_session)
+        job = await async_session.get(Job, upload_result.job_id)
+        transcript = (await async_session.exec(select(Transcript).where(Transcript.job_id == upload_result.job_id))).first()
+        revisions = (
+            await async_session.exec(
+                select(TranscriptRevision)
+                .where(TranscriptRevision.job_id == upload_result.job_id)
+                .order_by(TranscriptRevision.version_number)
+            )
+        ).all()
+
+        assert processed is True
+        assert job is not None
+        assert job.status == JobStatus.TRANSCRIBED
+        assert transcript is not None
+        assert transcript.text == "Pipeline transcript"
+        assert transcript.error_detail is None
+        assert transcript.model == "test-model"
+        assert len(revisions) == 1
+        assert revisions[0].version_number == 1
+        assert revisions[0].source == "ai"
+        assert revisions[0].text == "Pipeline transcript"
+
+
+@pytest.mark.integration
+class TestPipelineFailureFlow:
+    """Verify end-to-end failure lifecycle behavior."""
+
+    @pytest.mark.asyncio
+    async def test_upload_then_worker_persists_failed_terminal_state(self, async_session, tmp_path: Path, monkeypatch):
+        """Upload followed by worker processing persists error detail and failed status."""
+        settings = Settings(openrouter_api_key="test-key", upload_dir=tmp_path)
+        upload_result = await create_upload_job(
+            filename="pipeline.jpg",
+            file_bytes=b"pipeline-bytes",
+            session=async_session,
+            settings=settings,
+        )
+
+        async def _fake_transcribe(_path: str) -> TranscriptionResult:
+            raise RuntimeError("pipeline provider failure")
+
+        monkeypatch.setattr("transcription.services.workflows.transcribe_document_image", _fake_transcribe)
+
+        processed = await process_next_queued_job(session=async_session)
+        job = await async_session.get(Job, upload_result.job_id)
+        transcript = (await async_session.exec(select(Transcript).where(Transcript.job_id == upload_result.job_id))).first()
+        revisions = (
+            await async_session.exec(
+                select(TranscriptRevision)
+                .where(TranscriptRevision.job_id == upload_result.job_id)
+                .order_by(TranscriptRevision.version_number)
+            )
+        ).all()
+
+        assert processed is True
+        assert job is not None
+        assert job.status == JobStatus.FAILED
+        assert transcript is not None
+        assert transcript.text is None
+        assert "pipeline provider failure" in transcript.error_detail
+        assert "[internal_unexpected_error]" in transcript.error_detail
+        assert "error_id=" in transcript.error_detail
+        assert len(revisions) == 1
+        assert revisions[0].version_number == 1
+        assert revisions[0].source == "ai"
+        assert revisions[0].text is None
+        assert "pipeline provider failure" in (revisions[0].error_detail or "")

tests/providers/test_openrouter.py

@@ -0,0 +1,120 @@
+"""Tests for transcription.providers.openrouter."""
+
+from types import SimpleNamespace
+
+import pytest
+
+from transcription.config import Settings
+from transcription.providers.base import ProviderError, ProviderResponseError
+from transcription.providers.openrouter import DEFAULT_OPENROUTER_MODEL, OpenRouterTranscriptionProvider
+
+
+class _FakeChat:
+    def __init__(self, response=None, error: Exception | None = None):
+        self._response = response
+        self._error = error
+        self.calls = []
+
+    def send(self, **kwargs):
+        self.calls.append(kwargs)
+        if self._error:
+            raise self._error
+        return self._response
+
+
+class _FakeClient:
+    def __init__(self, response=None, error: Exception | None = None):
+        self.chat = _FakeChat(response=response, error=error)
+
+
+@pytest.mark.unit
+class TestOpenRouterProviderInit:
+    """Verify OpenRouter provider initialization behavior."""
+
+    def test_model_falls_back_to_default_when_unset(self):
+        """Provider uses adapter default model when provider_model is None."""
+        settings = Settings(openrouter_api_key="test-key", provider_model=None)
+        provider = OpenRouterTranscriptionProvider(settings=settings, client=_FakeClient())
+        assert provider.model == DEFAULT_OPENROUTER_MODEL
+
+    def test_model_uses_configured_value(self):
+        """Provider uses configured provider_model when present."""
+        settings = Settings(openrouter_api_key="test-key", provider_model="vendor/custom-model")
+        provider = OpenRouterTranscriptionProvider(settings=settings, client=_FakeClient())
+        assert provider.model == "vendor/custom-model"
+
+
+@pytest.mark.unit
+class TestOpenRouterProviderTranscribe:
+    """Verify OpenRouter request construction and response parsing."""
+
+    def test_includes_optional_referer_and_title_when_set(self):
+        """Transcribe sends app attribution fields when configured."""
+        response = {"model": "vendor/model-a", "choices": [{"message": {"content": "Transcript text"}}]}
+        client = _FakeClient(response=response)
+        settings = Settings(
+            openrouter_api_key="test-key",
+            openrouter_http_referer="https://example.test",
+            openrouter_app_title="Transcription App",
+        )
+        provider = OpenRouterTranscriptionProvider(settings=settings, client=client)
+
+        result = provider.transcribe(
+            prompt_text="Prompt body",
+            image_bytes=b"img-bytes",
+            mime_type="image/png",
+        )
+
+        send_call = client.chat.calls[0]
+        assert send_call["http_referer"] == "https://example.test"
+        assert send_call["x_open_router_title"] == "Transcription App"
+        assert result.text == "Transcript text"
+
+    def test_parses_successful_response_text(self):
+        """Transcribe returns normalized text from a valid response payload."""
+        response = {
+            "model": "vendor/model-b",
+            "choices": [{"message": {"content": [{"text": "Line 1"}, {"text": "Line 2"}]}}],
+        }
+        provider = OpenRouterTranscriptionProvider(
+            settings=Settings(openrouter_api_key="test-key"),
+            client=_FakeClient(response=response),
+        )
+
+        result = provider.transcribe(
+            prompt_text="Prompt body",
+            image_bytes=b"img-bytes",
+            mime_type="image/jpeg",
+        )
+
+        assert result.text == "Line 1\nLine 2"
+        assert result.provider == "openrouter"
+        assert result.model == "vendor/model-b"
+
+    def test_maps_sdk_exception_to_provider_error(self):
+        """Transcribe converts SDK failures to ProviderError."""
+        provider = OpenRouterTranscriptionProvider(
+            settings=Settings(openrouter_api_key="test-key"),
+            client=_FakeClient(error=RuntimeError("network down")),
+        )
+
+        with pytest.raises(ProviderError):
+            provider.transcribe(
+                prompt_text="Prompt body",
+                image_bytes=b"img-bytes",
+                mime_type="image/png",
+            )
+
+    def test_raises_on_empty_or_invalid_response(self):
+        """Transcribe raises ProviderResponseError for missing completion text."""
+        provider = OpenRouterTranscriptionProvider(
+            settings=Settings(openrouter_api_key="test-key"),
+            client=_FakeClient(response=SimpleNamespace(choices=[])),
+        )
+
+        with pytest.raises(ProviderResponseError):
+            provider.transcribe(
+                prompt_text="Prompt body",
+                image_bytes=b"img-bytes",
+                mime_type="image/png",
+            )

tests/services/test_job_service.py

@@ -0,0 +1,88 @@
+from uuid import uuid4
+
+import pytest
+
+from transcription.models import Document
+from transcription.models import Job
+from transcription.services.documents import DocumentService
+from transcription.services.jobs import JobService
+from transcription.services.jobs import JobStatus
+
+
+class TestJobService:
+    class TestBasicCRUD:
+        @pytest.mark.asyncio
+        async def test_create_job(self, job_service: JobService):
+            """Test creating a job."""
+
+            def fake_job_factory():
+                return Job(document_id=uuid4())
+
+            await job_service.create_job(job=fake_job_factory())
+
+            async with job_service._session_scope() as session:
+                for _ in range(10):
+                    await job_service.create_job(job=fake_job_factory(), session=session)
+
+        @pytest.mark.asyncio
+        async def test_backpropagation(self, job_service: JobService, document_service: DocumentService):
+            """Test that creating a job backpropagates to the related document."""
+            doc_id = uuid4()
+            document = Document(
+                id=doc_id,
+                filename="test.txt",
+                file_path="/path/to/test.txt",
+            )
+            await document_service.create_document(document=document)
+            job = Job(document_id=doc_id)
+            await job_service.create_job(job=job)
+
+            read_job = await job_service.read_job(job_id=job.id)
+            assert isinstance(read_job.document, Document)
+            assert read_job.document.id == document.id
+
+        @pytest.mark.asyncio
+        async def test_reading_job(self, job_service: JobService):
+            """Test reading a job."""
+            uuid = uuid4()
+            await job_service.create_job(job=Job(id=uuid, document_id=uuid4()))
+            job = await job_service.read_job(job_id=uuid)
+            assert job.id == uuid
+
+        @pytest.mark.asyncio
+        async def test_updating_job(self, job_service: JobService):
+            """Test updating a job."""
+            uuid = uuid4()
+            job = Job(id=uuid, document_id=uuid4())
+            async with job_service._session_scope() as session:
+                await job_service.create_job(job=job, session=session)
+                job.status = JobStatus.PROCESSING
+                await job_service.update_job(job=job, session=session)
+                read_job = await job_service.read_job(job_id=uuid, session=session)
+            assert read_job == job
+
+        @pytest.mark.asyncio
+        async def test_deleting_job(self, job_service: JobService):
+            """Test deleting a job."""
+
+    class TestServiceMethods:
+        @pytest.mark.asyncio
+        async def test_query_jobs(self, job_service: JobService):
+            """Test querying jobs."""
+            await job_service.create_job(job=Job(document_id=uuid4(), status=JobStatus.PROCESSING))
+            result = await job_service.query_jobs(status=JobStatus.PROCESSING)
+            jobs = {str(job.id).split("-")[0]: job.status for job in result}
+            assert len(jobs) == 1
+
+        @pytest.mark.asyncio
+        async def test_list_jobs(self, job_service: JobService):
+            """Test listing jobs."""
+            n = 5
+            for _ in range(n):
+                await job_service.create_job(job=Job(document_id=uuid4()))
+            jobs = await job_service.list_jobs()
+            assert len(jobs) == n
+
+        @pytest.mark.asyncio
+        async def test_mark_job_status(self, job_service: JobService):
+            """Test marking a job with a new status."""

tests/services/test_service_base.py

@@ -0,0 +1,36 @@
+import pytest
+
+
+class TestServiceBase:
+    class TestInitialization:
+        def test_initializes_with_defaults(self):
+            """Test initialization with default session factory and queue."""
+
+        def test_initializes_with_custom_session_factory(self):
+            """Test initialization with a provided session factory."""
+
+        def test_initializes_with_custom_queue(self):
+            """Test initialization with a provided queue."""
+
+    class TestSessionScope:
+        @pytest.mark.asyncio
+        async def test_uses_provided_session(self):
+            """Test that session scope reuses a provided session."""
+
+        @pytest.mark.asyncio
+        async def test_creates_new_session_when_none_provided(self):
+            """Test that session scope creates a new session when none is provided."""
+
+    class TestContextManagerBehavior:
+        @pytest.mark.asyncio
+        async def test_yields_session(self):
+            """Test that session scope yields a usable session object."""
+
+        @pytest.mark.asyncio
+        async def test_multiple_operations(self):
+            """Test multiple operations within a single session scope."""
+
+    class TestEdgeCases:
+        @pytest.mark.asyncio
+        async def test_handles_exception_propagation(self):
+            """Test exception propagation behavior inside session scope."""

tests/services/test_transcription_external.py

@@ -0,0 +1,70 @@
+"""Opt-in external tests for real document image transcription."""
+
+import os
+from pathlib import Path
+
+import pytest
+
+from transcription.services.transcription import transcribe_document_image
+
+
+HAS_OPENROUTER_KEY = bool(os.getenv("OPENROUTER_API_KEY"))
+
+REAL_IMAGES_DIR = Path(__file__).resolve().parents[1] / "fixtures" / "images" / "real"
+ARTIFACTS_DIR = Path(__file__).resolve().parents[1] / "artifacts" / "transcriptions"
+SUPPORTED_EXTENSIONS = {".jpg", ".jpeg", ".png", ".tif", ".tiff", ".pdf"}
+
+pytestmark = [
+    pytest.mark.external,
+    pytest.mark.skipif(
+        not HAS_OPENROUTER_KEY,
+        reason="Set OPENROUTER_API_KEY to run external real-image tests.",
+    ),
+]
+
+
+def _real_image_paths() -> list[Path]:
+    if not REAL_IMAGES_DIR.exists():
+        return []
+    return sorted(
+        [
+            p
+            for p in REAL_IMAGES_DIR.iterdir()
+            if p.is_file() and p.suffix.lower() in SUPPORTED_EXTENSIONS
+        ]
+    )
+
+
+def _artifact_filename(image_path: Path) -> str:
+    safe_stem = image_path.stem.replace(" ", "_")
+    safe_suffix = image_path.suffix.lower().replace(".", "")
+    return f"{safe_stem}.{safe_suffix}.txt"
+
+
+class TestRealImageExternalTranscription:
+    """Validate transcription against real local fixtures via live provider."""
+
+    def test_real_image_fixture_set_exists(self):
+        """At least one supported real-image fixture exists for external tests."""
+        assert REAL_IMAGES_DIR.exists()
+        assert _real_image_paths()
+
+    @pytest.mark.parametrize("image_path", _real_image_paths(), ids=lambda p: p.name)
+    def test_transcribes_real_image_fixture(self, image_path: Path):
+        """Real fixture image produces a non-empty transcription result."""
+        result = transcribe_document_image(image_path)
+        assert result.provider == "openrouter"
+        assert isinstance(result.model, str) and result.model.strip()
+        assert isinstance(result.text, str) and result.text.strip()
+
+        ARTIFACTS_DIR.mkdir(parents=True, exist_ok=True)
+        artifact_path = ARTIFACTS_DIR / _artifact_filename(image_path)
+        artifact_text = (
+            f"source: {image_path.name}\n"
+            f"provider: {result.provider}\n"
+            f"model: {result.model}\n"
+            "---\n"
+            f"{result.text}\n"
+        )
+        artifact_path.write_text(artifact_text, encoding="utf-8")
+        assert artifact_path.exists()

tests/test_app.py

@@ -0,0 +1,88 @@
+"""Tests for transcription.app."""
+
+import pytest
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from transcription.app import create_app
+
+
+@pytest.mark.unit
+class TestAppFactory:
+    """Verify FastAPI app factory wiring."""
+
+    def test_create_app_returns_fastapi_instance(self):
+        """create_app returns a FastAPI application instance."""
+        app = create_app()
+        assert isinstance(app, FastAPI)
+
+
+@pytest.mark.integration
+class TestAppLifespan:
+    """Verify startup and shutdown lifecycle behavior."""
+
+    def test_startup_initializes_runtime_dependencies(self, monkeypatch):
+        """Startup initializes logging, schema, directories, and worker resources."""
+        calls = []
+
+        monkeypatch.setattr("transcription.app.setup_logging", lambda: calls.append("logging"))
+        monkeypatch.setattr("transcription.app.create_all", lambda **_kwargs: calls.append("schema"))
+        monkeypatch.setattr(
+            "transcription.app.initialize_database_runtime",
+            lambda **_kwargs: type("_Runtime", (), {"engine": object()})(),
+        )
+        monkeypatch.setattr("transcription.app.dispose_database_runtime", lambda: calls.append("dispose_db"))
+        monkeypatch.setattr("transcription.app.should_bootstrap_schema", lambda _settings: True)
+        monkeypatch.setattr("transcription.app._start_worker", lambda _app: calls.append("start_worker"))
+        monkeypatch.setattr("transcription.app._stop_worker", lambda _app: calls.append("stop_worker"))
+
+        class _Dir:
+            def mkdir(self, parents: bool, exist_ok: bool):
+                calls.append("mkdir")
+
+        class _Settings:
+            upload_dir = _Dir()
+            prompt_dir = _Dir()
+
+        monkeypatch.setattr("transcription.app.get_settings", lambda: _Settings())
+
+        app = create_app()
+        with TestClient(app):
+            pass
+
+        assert "logging" in calls
+        assert "schema" in calls
+        assert "mkdir" in calls
+        assert "start_worker" in calls
+        assert "dispose_db" in calls
+
+    def test_shutdown_stops_worker_resources(self, monkeypatch):
+        """Shutdown signals and stops worker resources cleanly."""
+        calls = []
+
+        monkeypatch.setattr("transcription.app.setup_logging", lambda: None)
+        monkeypatch.setattr("transcription.app.create_all", lambda **_kwargs: None)
+        monkeypatch.setattr(
+            "transcription.app.initialize_database_runtime",
+            lambda **_kwargs: type("_Runtime", (), {"engine": object()})(),
+        )
+        monkeypatch.setattr("transcription.app.dispose_database_runtime", lambda: calls.append("dispose_db"))
+        monkeypatch.setattr("transcription.app.should_bootstrap_schema", lambda _settings: True)
+        monkeypatch.setattr("transcription.app._start_worker", lambda _app: calls.append("start_worker"))
+        monkeypatch.setattr("transcription.app._stop_worker", lambda _app: calls.append("stop_worker"))
+
+        class _Dir:
+            def mkdir(self, parents: bool, exist_ok: bool):
+                return None
+
+        class _Settings:
+            upload_dir = _Dir()
+            prompt_dir = _Dir()
+
+        monkeypatch.setattr("transcription.app.get_settings", lambda: _Settings())
+
+        app = create_app()
+        with TestClient(app):
+            pass
+
+        assert calls == ["start_worker", "stop_worker", "dispose_db"]

tests/test_config.py

@@ -0,0 +1,73 @@
+"""Tests for transcription.config — settings loading, provider defaults, and paths."""
+
+from pathlib import Path
+
+import pytest
+from pydantic import ValidationError
+
+from transcription.config import Provider, Settings
+
+
+def _make_settings(**overrides) -> Settings:
+    """Build a Settings instance with a dummy API key unless overridden."""
+    defaults = {"openrouter_api_key": "test-key-abc123"}
+    defaults.update(overrides)
+    return Settings(**defaults)
+
+
+class TestSettingsLoading:
+    """Verify Settings construction and required-field validation."""
+
+    def test_loads_from_env(self, monkeypatch):
+        """Settings constructs when OPENROUTER_API_KEY is provided."""
+        monkeypatch.setenv("OPENROUTER_API_KEY", "test-key-xyz")
+        settings = Settings()
+        assert settings.openrouter_api_key == "test-key-xyz"
+
+    def test_requires_api_key(self, monkeypatch):
+        """Settings raises ValidationError when OPENROUTER_API_KEY is missing."""
+        monkeypatch.delenv("OPENROUTER_API_KEY", raising=False)
+        with pytest.raises(ValidationError):
+            Settings(_env_file=None)
+
+
+class TestProviderSettings:
+    """Verify provider enum defaults and validation."""
+
+    def test_defaults_to_openrouter(self):
+        """Default provider is openrouter when not explicitly set."""
+        settings = _make_settings()
+        assert settings.provider == Provider.OPENROUTER
+        assert settings.provider == "openrouter"
+
+    def test_rejects_invalid_value(self):
+        """Setting PROVIDER to an invalid value raises ValidationError."""
+        with pytest.raises(ValidationError):
+            _make_settings(provider="not-a-provider")
+
+    def test_optional_fields_default_to_none(self):
+        """provider_model, openrouter_http_referer, and openrouter_app_title are None when unset."""
+        settings = _make_settings()
+        assert settings.provider_model is None
+        assert settings.openrouter_http_referer is None
+        assert settings.openrouter_app_title is None
+
+
+class TestPathSettings:
+    """Verify filesystem path field types."""
+
+    def test_path_fields_are_path_objects(self):
+        """upload_dir and prompt_dir are Path instances."""
+        settings = _make_settings()
+        assert isinstance(settings.upload_dir, Path)
+        assert isinstance(settings.prompt_dir, Path)
+
+
+class TestWorkerReliabilitySettings:
+    """Verify worker retry settings defaults."""
+
+    def test_worker_retry_defaults(self):
+        """worker retry settings default to no retries and no backoff."""
+        settings = _make_settings()
+        assert settings.worker_max_retries == 0
+        assert settings.worker_retry_backoff_seconds == 0.0

tests/test_db.py

@@ -0,0 +1,71 @@
+"""Tests for transcription.db — async schema bootstrap/runtime behavior."""
+
+from sqlalchemy import inspect
+from sqlalchemy import text
+import pytest
+
+
+class TestSchemaBootstrap:
+    """Verify async create_all produces the expected table set."""
+
+    @pytest.mark.asyncio
+    async def test_create_all_creates_expected_tables(self, default_settings):
+        """After async create_all(), document/job/transcript/revision tables exist."""
+        # Ensure models are imported so metadata is populated.
+        from transcription.models import Document, Job, Transcript, TranscriptRevision  # noqa: F401
+
+        from transcription.db.operations import create_all
+        from transcription.db.runtime import get_engine
+
+        engine = get_engine(settings=default_settings)
+        await create_all(engine=engine)
+
+        async with engine.begin() as connection:
+            table_names = set(await connection.run_sync(lambda sync_conn: inspect(sync_conn).get_table_names()))
+
+        assert "document" in table_names
+        assert "job" in table_names
+        assert "transcript" in table_names
+        assert "transcriptrevision" in table_names
+
+
+class TestSessionFactory:
+    """Verify async get_session yields a usable AsyncSession."""
+
+    @pytest.mark.asyncio
+    async def test_get_session_yields_session(self, default_settings):
+        """get_session() yields an AsyncSession with a live connection."""
+        from transcription.db.runtime import get_session
+
+        async with get_session(settings=default_settings) as session:
+            result = await session.exec(text("SELECT 1"))
+            assert result.first()[0] == 1
+
+
+class TestBootstrapPolicy:
+    """Verify startup schema bootstrap policy via Settings property."""
+
+    def test_production_defaults_to_no_bootstrap(self):
+        """Production defaults to explicit non-bootstrap startup behavior."""
+        from transcription.config import Settings
+
+        settings = Settings(openrouter_api_key="test-key", environment="production")
+        assert settings.should_bootstrap_schema is False
+
+    def test_development_defaults_to_bootstrap(self):
+        """Development defaults to schema bootstrap for local workflows."""
+        from transcription.config import Settings
+
+        settings = Settings(openrouter_api_key="test-key", environment="development")
+        assert settings.should_bootstrap_schema is True
+
+    def test_explicit_override_wins(self):
+        """Explicit bootstrap_schema_on_startup overrides environment default."""
+        from transcription.config import Settings
+
+        settings = Settings(
+            openrouter_api_key="test-key",
+            environment="production",
+            bootstrap_schema_on_startup=True,
+        )
+        assert settings.should_bootstrap_schema is True

tests/test_errors.py

@@ -0,0 +1,43 @@
+"""Tests for shared error taxonomy and helpers."""
+
+import pytest
+
+from transcription.errors import AppError, ErrorCategory, classify_unexpected_error, new_error_id
+
+
+@pytest.mark.unit
+class TestErrorCategoryContract:
+    """Verify stable category identifiers."""
+
+    def test_category_values_match_policy_contract(self):
+        """Error category values match docs/error_handling.md identifiers."""
+        assert ErrorCategory.VALIDATION.value == "validation_error"
+        assert ErrorCategory.USER_INPUT.value == "user_input_error"
+        assert ErrorCategory.NOT_FOUND.value == "not_found_error"
+        assert ErrorCategory.CONFLICT.value == "conflict_error"
+        assert ErrorCategory.EXTERNAL_PROVIDER.value == "external_provider_error"
+        assert ErrorCategory.INFRA_TRANSIENT.value == "infrastructure_transient_error"
+        assert ErrorCategory.INFRA_PERSISTENT.value == "infrastructure_persistent_error"
+        assert ErrorCategory.INTERNAL_UNEXPECTED.value == "internal_unexpected_error"
+
+
+@pytest.mark.unit
+class TestAppErrorHelpers:
+    """Verify helper behavior for IDs and normalization."""
+
+    def test_new_error_id_returns_short_identifier(self):
+        """new_error_id returns a short non-empty identifier."""
+        value = new_error_id()
+        assert isinstance(value, str)
+        assert len(value) == 8
+
+    def test_classify_unexpected_error_returns_internal_unexpected(self):
+        """Unexpected exceptions are normalized to internal_unexpected_error."""
+        err = classify_unexpected_error(RuntimeError("boom"), operation="unit.test")
+
+        assert isinstance(err, AppError)
+        assert err.category == ErrorCategory.INTERNAL_UNEXPECTED
+        assert "unit.test" in err.message
+        assert "boom" in err.message
+        assert err.suggestion
+        assert err.error_id

tests/test_models.py

@@ -0,0 +1,303 @@
+"""Tests for transcription.models — Document, Job, Transcript, TranscriptRevision models."""
+
+from uuid import UUID
+
+import pytest
+from sqlalchemy.exc import IntegrityError
+
+from transcription.models import Document, Job, JobStatus, Transcript, TranscriptRevision
+
+
+def _make_document(**overrides) -> Document:
+    """Create a Document with sensible defaults."""
+    defaults = {"filename": "letter.jpg", "file_path": "/uploads/letter.jpg"}
+    defaults.update(overrides)
+    return Document(**defaults)
+
+
+def _persist_document(session) -> Document:
+    """Create, persist, and return a Document."""
+    doc = _make_document()
+    session.add(doc)
+    session.commit()
+    session.refresh(doc)
+    return doc
+
+
+def _persist_job(session, document: Document) -> Job:
+    """Create, persist, and return a Job linked to a Document."""
+    job = Job(document_id=document.id)
+    session.add(job)
+    session.commit()
+    session.refresh(job)
+    return job
+
+
+class TestDocumentModel:
+    """Verify Document creation and default field population."""
+
+    def test_can_be_persisted(self, session):
+        """A Document round-trips through the database with correct fields."""
+        doc = _persist_document(session)
+        fetched = session.get(Document, doc.id)
+        assert fetched is not None
+        assert fetched.filename == "letter.jpg"
+        assert fetched.file_path == "/uploads/letter.jpg"
+
+    def test_defaults_are_populated(self, session):
+        """id is a UUID and uploaded_at is populated on creation."""
+        doc = _persist_document(session)
+        assert isinstance(doc.id, UUID)
+        assert doc.uploaded_at is not None
+
+
+class TestJobModel:
+    """Verify Job creation, defaults, and status transitions."""
+
+    def test_can_be_created_for_document(self, session):
+        """A Job linked to a Document via FK persists correctly."""
+        doc = _persist_document(session)
+        job = _persist_job(session, doc)
+        fetched = session.get(Job, job.id)
+        assert fetched is not None
+        assert fetched.document_id == doc.id
+
+    def test_defaults_are_populated(self, session):
+        """Default status is queued; created_at and updated_at are populated."""
+        doc = _persist_document(session)
+        job = _persist_job(session, doc)
+        assert job.status == JobStatus.QUEUED
+        assert job.retry_count == 0
+        assert job.created_at is not None
+        assert job.updated_at is not None
+
+    def test_transitions_to_transcribed(self, session):
+        """Status updates from queued to processing to transcribed."""
+        doc = _persist_document(session)
+        job = _persist_job(session, doc)
+        assert job.status == JobStatus.QUEUED
+
+        job.status = JobStatus.PROCESSING
+        session.add(job)
+        session.commit()
+        session.refresh(job)
+        assert job.status == JobStatus.PROCESSING
+
+        job.status = JobStatus.TRANSCRIBED
+        session.add(job)
+        session.commit()
+        session.refresh(job)
+        assert job.status == JobStatus.TRANSCRIBED
+
+    def test_transitions_to_failed(self, session):
+        """Status updates from processing to failed."""
+        doc = _persist_document(session)
+        job = _persist_job(session, doc)
+
+        job.status = JobStatus.PROCESSING
+        session.add(job)
+        session.commit()
+        session.refresh(job)
+
+        job.status = JobStatus.FAILED
+        session.add(job)
+        session.commit()
+        session.refresh(job)
+        assert job.status == JobStatus.FAILED
+
+
+class TestTranscriptModel:
+    """Verify Transcript persistence for success and failure cases."""
+
+    def test_success_record_persists(self, session):
+        """A Transcript with text set and error_detail None persists correctly."""
+        doc = _persist_document(session)
+        job = _persist_job(session, doc)
+        transcript = Transcript(job_id=job.id, provider="openrouter", prompt_name="transcribe_document.md", text="Dear Sir, ...")
+        session.add(transcript)
+        session.commit()
+        session.refresh(transcript)
+
+        fetched = session.get(Transcript, transcript.id)
+        assert fetched is not None
+        assert fetched.text == "Dear Sir, ..."
+        assert fetched.error_detail is None
+
+    def test_failure_record_persists(self, session):
+        """A Transcript with text None and error_detail set persists correctly."""
+        doc = _persist_document(session)
+        job = _persist_job(session, doc)
+        transcript = Transcript(
+            job_id=job.id,
+            provider="openrouter",
+            prompt_name="transcribe_document.md",
+            error_detail="Provider timeout",
+        )
+        session.add(transcript)
+        session.commit()
+        session.refresh(transcript)
+
+        fetched = session.get(Transcript, transcript.id)
+        assert fetched is not None
+        assert fetched.text is None
+        assert fetched.error_detail == "Provider timeout"
+
+    def test_job_id_is_unique(self, session):
+        """Inserting two transcripts with the same job_id raises an integrity error."""
+        doc = _persist_document(session)
+        job = _persist_job(session, doc)
+
+        t1 = Transcript(job_id=job.id, provider="openrouter", prompt_name="transcribe_document.md", text="First")
+        session.add(t1)
+        session.commit()
+
+        t2 = Transcript(job_id=job.id, provider="openrouter", prompt_name="transcribe_document.md", text="Duplicate")
+        session.add(t2)
+        with pytest.raises(IntegrityError):
+            session.commit()
+
+
+class TestTranscriptRevisionModel:
+    """Verify TranscriptRevision persistence and version uniqueness constraints."""
+
+    def test_revision_record_persists(self, session):
+        """A TranscriptRevision with version metadata persists correctly."""
+        doc = _persist_document(session)
+        job = _persist_job(session, doc)
+        revision = TranscriptRevision(
+            job_id=job.id,
+            version_number=1,
+            provider="openrouter",
+            prompt_name="transcribe_document.md",
+            model="google/gemini-2.5-flash",
+            source="ai",
+            text="Initial text",
+        )
+        session.add(revision)
+        session.commit()
+        session.refresh(revision)
+
+        fetched = session.get(TranscriptRevision, revision.id)
+        assert fetched is not None
+        assert fetched.version_number == 1
+        assert fetched.text == "Initial text"
+        assert fetched.source == "ai"
+
+    def test_job_version_pair_is_unique(self, session):
+        """Duplicate version_number for same job raises integrity error."""
+        doc = _persist_document(session)
+        job = _persist_job(session, doc)
+
+        first = TranscriptRevision(
+            job_id=job.id,
+            version_number=1,
+            provider="openrouter",
+            prompt_name="transcribe_document.md",
+            source="ai",
+            text="Initial",
+        )
+        duplicate = TranscriptRevision(
+            job_id=job.id,
+            version_number=1,
+            provider="openrouter",
+            prompt_name="transcribe_document.md",
+            source="user",
+            text="Edited",
+        )
+        session.add(first)
+        session.commit()
+
+        session.add(duplicate)
+        with pytest.raises(IntegrityError):
+            session.commit()
+
+    def test_same_version_number_allowed_for_different_jobs(self, session):
+        """Version numbers are scoped per job, not globally."""
+        doc1 = _persist_document(session)
+        job1 = _persist_job(session, doc1)
+        doc2 = _make_document(filename="letter2.jpg", file_path="/uploads/letter2.jpg")
+        session.add(doc2)
+        session.commit()
+        session.refresh(doc2)
+        job2 = _persist_job(session, doc2)
+
+        r1 = TranscriptRevision(
+            job_id=job1.id,
+            version_number=1,
+            provider="openrouter",
+            prompt_name="transcribe_document.md",
+            source="ai",
+            text="Job1 v1",
+        )
+        r2 = TranscriptRevision(
+            job_id=job2.id,
+            version_number=1,
+            provider="openrouter",
+            prompt_name="transcribe_document.md",
+            source="ai",
+            text="Job2 v1",
+        )
+        session.add(r1)
+        session.add(r2)
+        session.commit()
+
+
+class TestRelationships:
+    """Verify SQLModel relationship navigation between models."""
+
+    def test_document_exposes_jobs(self, session):
+        """document.jobs returns the linked Job list."""
+        doc = _persist_document(session)
+        _persist_job(session, doc)
+        _persist_job(session, doc)
+
+        session.refresh(doc)
+        assert len(doc.jobs) == 2
+        assert all(isinstance(j, Job) for j in doc.jobs)
+
+    def test_job_exposes_transcript(self, session):
+        """job.transcript returns the linked Transcript."""
+        doc = _persist_document(session)
+        job = _persist_job(session, doc)
+        transcript = Transcript(
+            job_id=job.id,
+            provider="openrouter",
+            prompt_name="transcribe_document.md",
+            text="Transcribed text",
+        )
+        session.add(transcript)
+        session.commit()
+
+        session.refresh(job)
+        assert job.transcript is not None
+        assert isinstance(job.transcript, Transcript)
+        assert job.transcript.text == "Transcribed text"
+
+    def test_job_exposes_transcript_revisions(self, session):
+        """job.transcript_revisions returns all linked revisions."""
+        doc = _persist_document(session)
+        job = _persist_job(session, doc)
+        session.add(
+            TranscriptRevision(
+                job_id=job.id,
+                version_number=1,
+                provider="openrouter",
+                prompt_name="transcribe_document.md",
+                source="ai",
+                text="v1",
+            )
+        )
+        session.add(
+            TranscriptRevision(
+                job_id=job.id,
+                version_number=2,
+                provider="openrouter",
+                prompt_name="transcribe_document.md",
+                source="user",
+                text="v2",
+            )
+        )
+        session.commit()
+
+        session.refresh(job)
+        assert len(job.transcript_revisions) == 2

tests/test_prompts.py

@@ -0,0 +1,42 @@
+"""Tests for prompt artifacts in prompts/."""
+
+from pathlib import Path
+
+
+PROMPT_PATH = Path("prompts/transcribe_document.md")
+
+
+def _prompt_text() -> str:
+    """Read prompt text from the canonical prompt file."""
+    return PROMPT_PATH.read_text(encoding="utf-8")
+
+
+class TestPromptArtifact:
+    """Verify prompt artifact presence and baseline semantics."""
+
+    def test_prompt_file_exists(self):
+        """Canonical transcription prompt file exists."""
+        assert PROMPT_PATH.exists()
+
+    def test_prompt_file_is_not_empty(self):
+        """Canonical prompt file has non-whitespace content."""
+        text = _prompt_text()
+        assert text.strip()
+
+    def test_prompt_mentions_verbatim_behavior(self):
+        """Prompt explicitly enforces verbatim transcription behavior."""
+        text = _prompt_text().lower()
+        assert "verbatim" in text
+        assert "do not summarize" in text
+
+    def test_prompt_includes_uncertainty_and_illegible_markers(self):
+        """Prompt contains conventions for uncertainty and illegible text."""
+        text = _prompt_text().lower()
+        assert "[boston?]" in text
+        assert "[illegible]" in text
+
+    def test_prompt_includes_deleted_and_inserted_conventions(self):
+        """Prompt contains conventions for deleted and inserted text."""
+        text = _prompt_text().lower()
+        assert "[deleted:" in text
+        assert "[inserted:" in text

tests/test_traceability.py

@@ -0,0 +1,61 @@
+"""Requirement-to-test traceability checks for MVP in-scope requirements."""
+
+from pathlib import Path
+
+import pytest
+
+MVP_REQUIREMENT_TEST_MAP: dict[str, list[str]] = {
+    "REQ-0": [
+        "tests/integration/test_pipeline_flow.py",
+    ],
+    "REQ-1": [
+        "tests/services/test_upload.py",
+        "tests/ui/test_upload_page.py",
+    ],
+    "REQ-2": [
+        "tests/services/test_worker.py",
+        "tests/integration/test_pipeline_flow.py",
+    ],
+    "REQ-3": [
+        "tests/services/test_worker.py",
+        "tests/ui/test_jobs_page.py",
+    ],
+    "REQ-4": [
+        "tests/services/test_worker.py",
+        "tests/integration/test_pipeline_flow.py",
+    ],
+    "REQ-5": [
+        "tests/ui/test_jobs_page.py",
+        "tests/ui/test_pages_registration.py",
+    ],
+    "REQ-6": [
+        "tests/test_app.py",
+        "tests/services/test_worker.py",
+    ],
+    "REQ-8": [
+        "tests/test_app.py",
+        "tests/test_config.py",
+    ],
+    "REQ-12": [
+        "tests/test_prompts.py",
+        "tests/services/test_transcription.py",
+    ],
+}
+
+
+@pytest.mark.integration
+class TestMvpRequirementTraceability:
+    """Verify MVP in-scope requirements are mapped to executable tests."""
+
+    def test_mvp_requirements_have_mapped_test_targets(self):
+        """Each MVP in-scope REQ id maps to at least one existing test path."""
+        project_root = Path(__file__).resolve().parents[1]
+
+        assert MVP_REQUIREMENT_TEST_MAP
+        for requirement_id, mapped_tests in MVP_REQUIREMENT_TEST_MAP.items():
+            assert requirement_id.startswith("REQ-")
+            assert mapped_tests, f"No mapped tests for {requirement_id}"
+
+            for relative_path in mapped_tests:
+                test_path = project_root / relative_path
+                assert test_path.exists(), f"Missing mapped test file for {requirement_id}: {relative_path}"

tests/ui/test_jobs_page.py

@@ -0,0 +1,37 @@
+"""Tests for the jobs page route."""
+
+import pytest
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from transcription.ui import register_pages
+from transcription.ui.pages import jobs_page
+
+
+@pytest.fixture
+def client(monkeypatch):
+    """Provide a minimal app client with jobs data patched for rendering."""
+
+    async def _fetch_jobs_stub():
+        return []
+
+    monkeypatch.setattr(jobs_page, "fetch_jobs", _fetch_jobs_stub)
+
+    app = FastAPI()
+    register_pages(app)
+    with TestClient(app) as test_client:
+        yield test_client
+
+
+@pytest.mark.integration
+class TestPageRendering:
+    """Verify the jobs page is available and includes the main controls."""
+
+    def test_jobs_page_renders_expected_controls(self, client):
+        """GET /ui/jobs returns the page shell and jobs controls."""
+        response = client.get("/ui/jobs")
+
+        assert response.status_code == 200
+        assert "Transcription Jobs" in response.text
+        assert "Refresh" in response.text
+        assert "Back to upload" in response.text

tests/ui/test_pages_registration.py

@@ -0,0 +1,38 @@
+"""Tests for UI page registration wiring."""
+
+import pytest
+from fastapi import FastAPI
+
+from transcription.ui import register_pages
+
+
+@pytest.mark.integration
+class TestPageRegistration:
+    """Verify page registration and route wiring."""
+
+    def test_register_pages_wires_upload_jobs_and_mount(self, monkeypatch):
+        """register_pages registers pages and mounts NiceGUI at /ui."""
+        calls: list[str] = []
+
+        def _record_upload() -> None:
+            calls.append("upload")
+
+        def _record_jobs() -> None:
+            calls.append("jobs")
+
+        def _record_run_with(
+            _app: FastAPI,
+            *,
+            mount_path: str,
+            show_welcome_message: bool,
+        ) -> None:
+            calls.append(f"run_with:{mount_path}:{show_welcome_message}")
+
+        monkeypatch.setattr("transcription.ui.register_upload_page", _record_upload)
+        monkeypatch.setattr("transcription.ui.register_jobs_page", _record_jobs)
+        monkeypatch.setattr("transcription.ui.ui.run_with", _record_run_with)
+
+        app = FastAPI()
+        register_pages(app)
+
+        assert calls == ["upload", "jobs", "run_with:/ui:False"]

tests/ui/test_upload_page.py

@@ -0,0 +1,55 @@
+"""Tests for the upload page route."""
+
+from pathlib import Path
+
+import pytest
+from fastapi.testclient import TestClient
+
+from transcription.app import create_app
+from transcription.config import Settings
+from transcription.config import _settings
+
+
+@pytest.fixture
+def client(tmp_path: Path):
+    """Provide a real app client backed by in-memory SQLite."""
+    settings = Settings(
+        openrouter_api_key="test-key",
+        database_url="sqlite:///:memory:",
+        environment="test",
+        upload_dir=tmp_path / "uploads",
+        prompt_dir=tmp_path / "prompts",
+    )
+    _settings.set(settings)
+
+    app = create_app()
+    with TestClient(app) as test_client:
+        yield test_client
+
+
+@pytest.mark.integration
+class TestPageRendering:
+    """Verify the upload page is available and includes the main controls."""
+
+    def test_root_redirects_to_ui(self, client):
+        """GET / redirects to the UI mount point."""
+        response = client.get("/", follow_redirects=False)
+
+        assert response.status_code == 307
+        assert response.headers["location"] == "/ui"
+
+    def test_ui_redirects_to_upload(self, client):
+        """GET /ui redirects to the upload page."""
+        response = client.get("/ui", follow_redirects=False)
+
+        assert response.status_code == 307
+        assert response.headers["location"] == "/ui/upload"
+
+    def test_upload_page_renders_expected_controls(self, client):
+        """GET /ui/upload returns the page shell and upload controls."""
+        response = client.get("/ui/upload")
+
+        assert response.status_code == 200
+        assert "Upload Document" in response.text
+        assert "Select document file" in response.text
+        assert "View jobs" in response.text

tools/schemas/search_docs.json

@@ -0,0 +1,26 @@
+{
+  "name": "search_docs",
+  "description": "Search internal docs with a short safe query.",
+  "parameters": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "query": {
+        "type": "string",
+        "description": "Short neutral search phrase",
+        "minLength": 1,
+        "maxLength": 180
+      },
+      "scope": {
+        "type": "string",
+        "enum": ["public", "internal"]
+      },
+      "top_k": {
+        "type": "integer",
+        "minimum": 1,
+        "maximum": 10
+      }
+    },
+    "required": ["query", "scope"]
+  }
+}