From 5946867ff30a52591ef9585d3cbea4998d46aeee Mon Sep 17 00:00:00 2001
From: Jim Lancaster <40281233+zoltan57@users.noreply.github.com>
Date: Sun, 2 Aug 2026 11:23:04 -0500
Subject: [PATCH] UI update initial phase complete. Still need to create
 schema-mapping for the two many-to-many tables.

---
 docs/ui/README.md                           |  21 ++
 docs/ui/entities/job/acceptance-criteria.md | 162 +++++++++++
 docs/ui/entities/job/schema-mapping.md      | 238 ++++++++++++++++
 docs/ui/entities/job/user-journey.md        | 286 ++++++++++++++++++++
 docs/ui/entities/traceability-matrix.md     |  68 +++++
 5 files changed, 775 insertions(+)
 create mode 100644 docs/ui/entities/job/acceptance-criteria.md
 create mode 100644 docs/ui/entities/job/schema-mapping.md
 create mode 100644 docs/ui/entities/job/user-journey.md
 create mode 100644 docs/ui/entities/traceability-matrix.md

diff --git a/docs/ui/README.md b/docs/ui/README.md
index 65712e0..4142358 100644
--- a/docs/ui/README.md
+++ b/docs/ui/README.md
@@ -27,11 +27,32 @@ Use this document to describe:
 - intended target behavior
 - implementation gaps between current code and intended UX
 
+### acceptance-criteria.md
+
+An implementation-ready checklist for CRUD behavior and quality gates.
+
+Use this document to describe:
+- testable acceptance statements by flow (Create, Read, Update, Delete)
+- success and failure behaviors
+- first-release constraints
+- cross-criteria quality gates
+
+### traceability-matrix.md
+
+A criteria-to-code mapping that identifies implementation anchors and status.
+
+Use this document to describe:
+- acceptance criteria group to implementation file mapping
+- delivery status (implemented, partial, planned)
+- ordered implementation priorities
+
 ## Organization Rules
 
 - Store documents under `docs/ui/entities/<entity-name>/`.
 - Create both `user-journey.md` and `schema-mapping.md` for user-facing entities.
+- Create `acceptance-criteria.md` for user-facing entities.
 - Create only `schema-mapping.md` for supporting tables that do not currently have standalone UI.
+- Keep one shared `traceability-matrix.md` under `docs/ui/entities/` to map criteria to implementation anchors.
 - Keep top-level `docs/` reserved for core architecture, requirements, schema, and system-wide reference material.
 
 ## Current Entity Plan
diff --git a/docs/ui/entities/job/acceptance-criteria.md b/docs/ui/entities/job/acceptance-criteria.md
new file mode 100644
index 0000000..a44d745
--- /dev/null
+++ b/docs/ui/entities/job/acceptance-criteria.md
@@ -0,0 +1,162 @@
+# Job Acceptance Criteria
+
+Purpose: Define implementation-ready acceptance criteria for Job Create, Read, Update, and Delete workflows.
+
+Companion documents:
+- docs/ui/entities/job/user-journey.md
+- docs/ui/entities/job/schema-mapping.md
+
+## Scope
+
+This checklist covers:
+1. Create flow
+2. Read flow
+3. Update flow
+4. Delete flow
+
+This checklist does not cover:
+1. provider-specific transcription internals
+2. advanced workflow scheduling and queue orchestration controls
+3. multi-job bulk operations
+
+## Create Acceptance Criteria
+
+### CR-1 Job creation entry
+1. Given the user is on the Jobs page
+2. When the user selects Create job
+3. Then the user is taken to Job detail/create mode
+
+### CR-2 Required create values
+1. document_id must be selected before submit
+2. at least one source file must be uploaded before submit
+3. each uploaded file creates a Source linked to the selected Document
+4. each created Source is linked to the new Job through JobSource
+
+### CR-3 Source ordering behavior
+1. Given multi-file or folder upload
+2. When source records are created
+3. Then page ordering follows alphabetical order of original filenames
+4. Then helper text explains how filename conventions control ordering
+
+### CR-4 Provider/model/prompt visibility
+1. provider, model, and prompt_name are visible in create flow when known
+2. provider, model, and prompt_name are visible in detail flow when known
+3. if values are unknown at create time, UI shows clear unknown or pending state without blocking submit
+
+### CR-5 Successful create outcome
+1. Given valid inputs
+2. When the user submits create
+3. Then the Job record is created and linked to selected Document
+4. Then source and JobSource records are created for uploads
+5. Then job status is queued or processing based on execution timing
+6. Then the user is routed to Job detail mode
+
+### CR-6 Create failure outcome
+1. Given create validation or persistence failure
+2. Then clear error feedback is shown
+3. Then no false success feedback is shown
+4. Then entered selections are preserved where possible
+5. Then retry path remains available
+
+## Read Acceptance Criteria
+
+### RD-1 Jobs list retrieval
+1. Given one or more jobs exist
+2. When the user opens the Jobs page
+3. Then all jobs are listed in a table or equivalent list surface
+
+### RD-2 Jobs list fields
+1. Jobs list shows job id
+2. Jobs list shows status
+3. Jobs list shows created or updated timestamps
+4. Jobs list shows retry_count when available
+5. Jobs list provides navigation to Job detail for each row
+
+### RD-3 Job detail retrieval
+1. Given a valid job id
+2. When the user opens Job detail
+3. Then job metadata for that record only is shown
+4. Then source preview or source warning state is shown
+
+### RD-4 Detail execution context visibility
+1. provider, model, and prompt_name are displayed when known
+2. status lifecycle value is visible
+3. source-level transcription and revision context is visible
+
+### RD-5 Missing and invalid id states
+1. Given an invalid job id format
+2. Then UI shows invalid job id state without crashing
+3. Given a valid but nonexistent job id
+4. Then UI shows job not found state without crashing
+
+## Update Acceptance Criteria
+
+### UP-1 Revision edit entry
+1. Given a job detail page with source context
+2. When the user enters revision edit flow
+3. Then revised_text input is available
+
+### UP-2 Revision validation
+1. revised_text cannot be saved as empty after trimming
+2. warning feedback is shown for invalid empty input
+
+### UP-3 Successful revision save
+1. Given valid revision text
+2. When the user saves
+3. Then revised_text persists
+4. Then success feedback is shown
+5. Then refreshed revision content is visible
+
+### UP-4 Revision save failure
+1. Given backend failure during revision save
+2. Then clear error feedback is shown
+3. Then the user-entered text remains available for retry where possible
+
+### UP-5 Job lifecycle state update visibility
+1. status changes from queued to processing to terminal states are reflected in UI
+2. retry_count updates are reflected when retry logic runs
+3. users cannot directly edit lifecycle state fields in first release
+
+## Delete Acceptance Criteria
+
+### DL-1 Delete entry and confirmation
+1. Given a job detail context with delete affordance
+2. When the user selects delete job
+3. Then a permanent-action confirmation dialog appears
+
+### DL-2 Dependency guardrails
+1. If deletion policy requires retention handling for related JobSource history, delete is blocked
+2. If deletion policy allows dependent cleanup path, delete can proceed
+
+### DL-3 Blocked delete behavior
+1. When blocked
+2. Then UI explains dependency constraints
+3. Then UI provides cleanup guidance
+
+### DL-4 Successful delete
+1. Given no blocking dependencies
+2. When the user confirms deletion
+3. Then job is removed
+4. Then success feedback is shown
+5. Then the user returns to Jobs list
+
+### DL-5 Delete failure
+1. Given backend failure during delete
+2. Then clear error feedback is shown
+3. Then the user remains in Job context with retry path
+
+## Cross-Criteria Quality Gates
+
+### QG-1 Separation of intent and implementation
+1. UX intent remains in user-journey.md
+2. current versus target mapping remains in schema-mapping.md
+
+### QG-2 Traceability
+1. Each accepted behavior maps to at least one UI action or service path
+2. No acceptance criterion contradicts first-release deferred items
+
+### QG-3 First-release constraints
+1. Jobs page remains list-all with explicit Create job action
+2. Job create requires Document selection and source upload
+3. provider/model/prompt_name are visible to users when known
+4. manual retry controls may remain deferred while status visibility is required
diff --git a/docs/ui/entities/job/schema-mapping.md b/docs/ui/entities/job/schema-mapping.md
new file mode 100644
index 0000000..804de6c
--- /dev/null
+++ b/docs/ui/entities/job/schema-mapping.md
@@ -0,0 +1,238 @@
+# Job Schema-to-UI Mapping
+
+Purpose: Map the Job schema to the UI, while clearly separating intended target behavior from current implementation.
+
+Companion document: user-journey.md
+Acceptance criteria: acceptance-criteria.md
+
+## 1. Entity Snapshot
+
+- Table: Job
+- Primary key: id (UUID)
+- Related entities: Document, JobSource, Source
+- Canonical schema references:
+  - src/transcription/db/models.py
+  - docs/schema_v2.md
+
+## 2. Mapping Rules
+
+This document uses three lenses:
+1. Intended behavior: what the UX should support.
+2. Current behavior: what the code supports today.
+3. Gap to target: what must change to align implementation with the intended UX.
+
+## 3. Field Inventory
+
+| Field | DB Type | Nullable | Default/Auto Value | Intended UI Treatment | Notes |
+|---|---|---|---|---|---|
+| id | UUID | No | uuid4() | Shown read-only in list and detail | Primary key |
+| document_id | UUID FK | No | None | Required create input via Document selection | Job belongs to one Document |
+| status | enum JobStatus | No | queued | Shown read-only as lifecycle state | System-managed transitions |
+| retry_count | int | No | 0 | Shown read-only | Operational counter |
+| date_created | datetime | No | datetime.now(UTC) | Shown read-only | System-managed timestamp |
+| date_updated | datetime | No | datetime.now(UTC) | Shown read-only | System-managed timestamp |
+| provider | str | Yes | None | Visible when known; editable if create-time options are available | Processing metadata |
+| model | str | Yes | None | Visible when known; editable if create-time options are available | Processing metadata |
+| prompt_name | str | Yes | None | Visible when known; editable if create-time options are available | Prompt metadata |
+
+Related execution fields rendered in Job detail via relationships:
+- JobSource.status
+- JobSource.error_detail
+- JobSource.executed_at
+- Source.upload_name, Source.filename, Source.page_number
+- Source.raw_transcription, Source.revised_text
+
+## 4. CREATE Mapping
+
+### 4.1 Intended Create Flow
+
+Entry point: Jobs page Create job action  
+User action: open create mode, select Document, upload one or more source files or a folder, submit for transcription  
+Success destination: Job detail page in detail mode
+
+| Field | Intended User Input | Required | Visible | Notes |
+|---|---|---|---|---|
+| document_id | Select/search | Yes | Yes | Required create selection |
+| status | None | No | Yes (read-only) | Starts at queued and changes by workflow |
+| retry_count | None | No | Yes (read-only) | Starts at 0 |
+| date_created | None | No | Yes (read-only) | System-generated |
+| date_updated | None | No | Yes (read-only) | System-generated |
+| provider | Display or select | No | Yes | Visible when known during create and detail |
+| model | Display or select | No | Yes | Visible when known during create and detail |
+| prompt_name | Display or select | No | Yes | Visible when known during create and detail |
+
+Create-related relationship rules:
+1. source file upload is required for create.
+2. each uploaded file creates a Source linked to the selected Document.
+3. each created Source must be linked to the new Job through JobSource.
+4. processing order for multi-file and folder uploads is alphabetical by original filename.
+
+### 4.2 Current Implementation
+
+Current entry point: upload page through create_upload_job()  
+Current user action: upload one file through upload flow  
+Current backend path: upload submit -> create_upload_job -> _create_upload_records
+
+| Field | Current Value at Create | Source | Visible to User | Evidence |
+|---|---|---|---|---|
+| id | Generated UUID | System | Yes on jobs list/detail | src/transcription/ui/pages/jobs_page.py |
+| document_id | Newly created Document id | Service | Indirectly | src/transcription/services/store.py |
+| status | queued | Service/model default | Yes | src/transcription/services/store.py, src/transcription/db/models.py |
+| retry_count | 0 | Model default | Yes | src/transcription/db/models.py, src/transcription/ui/pages/jobs_page.py |
+| date_created | current UTC timestamp | System | Yes | src/transcription/db/models.py, src/transcription/ui/pages/jobs_page.py |
+| date_updated | current UTC timestamp | System | Yes | src/transcription/db/models.py, src/transcription/ui/pages/jobs_page.py |
+| provider | None at create, set after transcription update | Workflow/service | Partially | src/transcription/services/workflows.py |
+| model | None at create, set after transcription update | Workflow/service | Partially | src/transcription/services/workflows.py |
+| prompt_name | None at create, set by workflow updates | Workflow/service | Partially | src/transcription/services/workflows.py |
+
+Current create constraints:
+1. no dedicated Create job action in the Jobs page.
+2. upload flow currently creates Document, Job, Source, and JobSource together.
+3. current upload path accepts a single file per submission.
+
+### 4.3 Gap to Target
+
+To satisfy intended Create flow, implementation must add:
+1. Jobs list Create job action that opens Job detail/create mode.
+2. explicit Document selection and source upload controls in create mode.
+3. multi-file and folder upload support in create mode.
+4. deterministic alphabetical page ordering and user guidance.
+5. explicit visibility of provider, model, and prompt_name in create/detail when known.
+
+## 5. READ Mapping
+
+### 5.1 Intended Read Behavior
+
+On Job list/detail surfaces, users should be able to see:
+1. all jobs in one list.
+2. status and timeline context.
+3. selected Document context.
+4. source-level processing and transcription results.
+5. provider/model/prompt_name when known.
+
+### 5.2 Current Implementation
+
+Current read behavior exists in jobs list and jobs detail routes.
+
+| Field | Current Rendering | Visible to User | Notes | Evidence |
+|---|---|---|---|---|
+| id | Jobs list row and detail header | Yes | Primary visible identifier | src/transcription/ui/pages/jobs_page.py |
+| status | Jobs list and detail | Yes | Chip styling for transcribed; text for others | src/transcription/ui/pages/jobs_page.py |
+| retry_count | Jobs list table | Yes | Included in row model | src/transcription/ui/components/table/jobs.py |
+| date_created | Jobs list table | Yes | Included in row model | src/transcription/ui/components/table/jobs.py |
+| date_updated | Jobs list table | Yes | Included in row model | src/transcription/ui/components/table/jobs.py |
+| document_id | Not rendered directly as labeled field | Partial | Document context exists by relationship but limited direct display | src/transcription/ui/pages/jobs_page.py |
+| provider/model/prompt_name | Not rendered as first-class labels | Partial | Stored in job records after processing updates | src/transcription/services/workflows.py |
+
+Source-related read behavior:
+1. one primary source preview is shown in detail.
+2. original transcription and revision editor are rendered for source context.
+3. invalid or missing job ids show explicit UI states.
+
+### 5.3 Gap to Target
+
+To satisfy intended Read flow, implementation must add:
+1. list-level create affordance and enhanced filtering/search UX.
+2. explicit Document context rendering in list and detail.
+3. explicit provider/model/prompt_name rendering in detail when known.
+4. richer multi-source detail navigation when more than one source is linked.
+
+## 6. UPDATE Mapping
+
+### 6.1 Intended Update Behavior
+
+Primary user updates in first release are revision edits in job detail source context.
+
+Intended editable scope (first release):
+- Source.revised_text through Job detail review
+
+Intended read-only Job fields in first release:
+- id
+- document_id after create
+- status
+- retry_count
+- date_created
+- date_updated
+
+Job metadata visibility policy:
+- provider, model, and prompt_name should be visible when known.
+- create-time editing of provider/model/prompt_name is optional and depends on available options.
+
+### 6.2 Current Implementation
+
+| Field/Area | Updatable via UI | Updatable via Service | Notes |
+|---|---|---|---|
+| Source.revised_text from job detail | Yes | Yes | Saved via transcription service revision path |
+| status | No | Yes | Updated by workflow lifecycle services |
+| retry_count | No | Yes | Incremented by workflow retry logic |
+| provider/model/prompt_name | No | Yes | Set during transcription result finalization |
+| document_id | No | Technically via model/service update | Treated as fixed post-create in intended UX |
+
+### 6.3 Gap to Target
+
+Implementation should add:
+1. explicit create-mode handling for provider/model/prompt visibility and optional selection.
+2. richer detail display for provider/model/prompt and source-level execution outcomes.
+3. optional future manual controls for retry and state transitions.
+
+## 7. DELETE Mapping
+
+### 7.1 Intended Delete Behavior
+
+Job deletion should include dependency-aware guardrails.
+
+Rules:
+1. deletion is allowed only when policy allows cleanup or retention handling for related JobSource records.
+2. blocked deletion must explain constraints and required cleanup path.
+3. successful deletion requires confirmation and returns user to Jobs list.
+
+### 7.2 Current Implementation
+
+| Action | UI Exposed | Backend Capability | Notes |
+|---|---|---|---|
+| Delete Job | No | Yes | JobService.delete_job() exists; no dedicated UI delete flow |
+
+### 7.3 Gap to Target
+
+Implementation must add:
+1. delete control in Job detail.
+2. dependency checks and blocked-delete messaging.
+3. success navigation and confirmation UX.
+
+## 8. Hidden and System-Managed Fields
+
+| Field | Category | Why Hidden or Protected |
+|---|---|---|
+| status | System-managed lifecycle | Managed by worker lifecycle transitions |
+| retry_count | System-managed operational state | Reflects retry behavior, not direct user input |
+| date_created | System-managed | Audit timestamp |
+| date_updated | System-managed | Audit timestamp |
+
+## 9. Traceability Anchors
+
+Schema and models:
+- docs/schema_v2.md
+- src/transcription/db/models.py
+
+Current implementation:
+- src/transcription/ui/pages/jobs_page.py
+- src/transcription/ui/components/table/jobs.py
+- src/transcription/ui/components/transcript.py
+- src/transcription/services/jobs.py
+- src/transcription/services/workflows.py
+- src/transcription/services/store.py
+
+Companion UX spec:
+- docs/ui/entities/job/user-journey.md
+
+Acceptance checklist:
+- docs/ui/entities/job/acceptance-criteria.md
+
+## 10. Acceptance Checklist Summary
+
+- Every Job schema field appears in the field inventory.
+- Intended Create behavior matches the companion user journey.
+- Current behavior reflects existing upload-first creation and jobs read surfaces.
+- Provider/model/prompt visibility intent is explicit for create and detail views.
+- Gaps between intended and current behavior are explicit.
+- Read, Update, and Delete sections distinguish target behavior from current code.
diff --git a/docs/ui/entities/job/user-journey.md b/docs/ui/entities/job/user-journey.md
new file mode 100644
index 0000000..655bb88
--- /dev/null
+++ b/docs/ui/entities/job/user-journey.md
@@ -0,0 +1,286 @@
+# Job User Journey
+
+Purpose: Define how a user should interact with the UI to create and manage a Job record, including document linking, source uploads, processing status, and page-level review.
+
+Scope: This document describes intended user interaction for the Job UI. It is the UX contract for the Job entity.
+
+Companion schema mapping: schema-mapping.md
+Companion acceptance criteria: acceptance-criteria.md
+
+## 1. Overview
+
+A Job represents one transcription run for a selected Document and one or more uploaded source files.
+
+Managing a Job is run-first:
+1. The user opens the Jobs page.
+2. The user selects Create job.
+3. The user lands on a Job detail/create surface.
+4. The user links a Document and uploads one or more source files.
+5. The user submits for transcription.
+6. The system creates and processes the Job.
+7. The user reviews per-source output and saves revisions.
+
+## 2. User Goal
+
+The user wants to:
+1. see all jobs in one place
+2. create a new transcription run intentionally
+3. attach the run to the correct Document
+4. upload source file(s) for that run
+5. submit and monitor processing state
+6. review and revise page-level outputs
+
+## 3. Page Model
+
+### 3.1 Jobs List Page
+
+The Jobs page is the primary UI surface where users manage jobs.
+
+It should support:
+1. listing all jobs
+2. searching or filtering jobs
+3. opening job detail for any row
+4. starting Create job
+5. clear empty state when no jobs exist
+
+### 3.2 Job Detail/Create Page
+
+The Job detail/create page is used for both creating a new Job and viewing an existing Job.
+
+Create mode should include:
+1. document selection
+2. source upload controls
+3. submit for transcription action
+
+Detail mode should include:
+1. job metadata and status
+2. per-source processing state
+3. original transcription output
+4. revision editor and save actions
+
+## 4. Entry Points
+
+Primary entry points:
+1. from Jobs page, Create job
+2. from Jobs page row selection, open existing Job detail
+
+Current implementation note:
+1. current code path is upload-first and auto-creates Job records
+2. intended UX is explicit Create job from the Jobs page
+
+## 5. Create Job Flow
+
+### 5.1 User Intent
+
+The user wants to start a transcription run by selecting the right Document and providing source files in one guided flow.
+
+### 5.2 Create Entry
+
+1. user opens the Jobs page
+2. user selects Create job
+3. system opens Job detail/create page in create mode
+
+### 5.3 Create Inputs
+
+| UI Label | Schema Area | Input Type | Required | Notes |
+|---|---|---|---|---|
+| Document | Job.document_id | Select/search | Yes | Links the run to one Document |
+| Source files | Source upload fields | Multi-file upload or folder upload | Yes | User may select one file, many files, or a folder |
+| Processing order | Source.page_number assignment rule | System rule | Yes | If multiple files are uploaded, order is alphabetical by original filename |
+| Provider | Job.provider | Display or select | No | Visible to user when known; selectable when options are available |
+| Model | Job.model | Display or select | No | Visible to user when known; selectable when options are available |
+| Prompt | Job.prompt_name | Display or select | No | Visible to user when known; selectable when options are available |
+
+### 5.4 Source Handling Rules
+
+1. each uploaded file becomes a Source linked to the selected Document
+2. each created Source is linked to the Job through JobSource
+3. multi-file or folder uploads are processed alphabetically by original filename
+4. upload_name stores the original filename
+5. stored filename uses UUID plus original extension in the form UUID.extension
+
+Suggested helper text:
+1. Files are processed alphabetically by original filename. Use leading numbers such as 001, 002, 003 to control page order.
+
+### 5.5 Validation Rules
+
+Create submission must be blocked when:
+1. no Document is selected
+2. no source file is uploaded
+
+Create submission should provide clear feedback when:
+1. uploaded files are invalid or unreadable
+2. persistence fails for Job, Source, or JobSource linkage
+
+### 5.6 Submission Behavior
+
+On submit:
+1. validate create inputs
+2. create Job record linked to selected Document
+3. create Source records for uploaded files
+4. create JobSource links for each Source in the Job
+5. queue processing for transcription
+6. route user to Job detail mode
+
+Recommended transactional behavior:
+1. intended create writes should succeed or fail together
+2. user should not receive false success when required records fail
+
+### 5.7 Create Success Result
+
+After successful create:
+1. job appears in Jobs list
+2. job detail shows selected Document and created source set
+3. status appears as queued or processing based on execution timing
+4. user can monitor progress and open page-level review
+
+### 5.8 Create Failure Result
+
+If create fails:
+1. show clear error message
+2. preserve entered selections where possible
+3. keep retry path available
+4. do not show false success feedback
+
+## 6. Read Job Journey
+
+### 6.1 User Intent
+
+The user wants to quickly understand what the job is, its current status, and which source pages need review.
+
+### 6.2 Jobs List Expectations
+
+The Jobs list should show, at minimum:
+1. job identifier
+2. document context
+3. current status
+4. creation or update timestamp
+5. quick action to open detail
+
+Optional first-release columns if available:
+1. retry count
+2. provider/model summary
+
+### 6.3 Job Detail Expectations
+
+The Job detail should show:
+1. job status and summary metadata
+2. selected Document context
+3. per-source status (pending, transcribed, failed)
+4. original transcription output per source
+5. revision editor and latest revised content
+
+### 6.4 Read Empty and Missing States
+
+If no jobs exist:
+1. list shows no jobs yet empty state
+2. list shows Create job action
+
+If a job id is invalid or missing:
+1. show clear not found state
+2. do not crash the page
+
+If a job has no source items due to failure:
+1. show clear warning state
+2. keep recovery guidance visible
+
+## 7. Job Status Lifecycle UX
+
+### 7.1 Status Values
+
+The UI should map to model-backed job states:
+1. queued
+2. processing
+3. transcribed
+4. completed
+5. partial_success
+6. failed
+
+### 7.2 In-Progress States
+
+When status is queued or processing:
+1. show active progress state
+2. keep detail page refresh-safe
+3. indicate that source-level results may still be arriving
+
+### 7.3 Terminal States
+
+When status is completed:
+1. show completion success state
+2. direct user to revision workflow
+
+When status is partial_success:
+1. show mixed outcome state
+2. identify failed pages
+3. guide user to review available successful pages and retry strategy
+
+When status is failed:
+1. show failure state with actionable message
+2. keep navigation and retry guidance available
+
+## 8. Update Job Journey
+
+### 8.1 User Intent
+
+The user primarily updates job-related review outcomes by editing revised transcription text per source page.
+
+### 8.2 First-Release Editable Scope
+
+Editable in first release:
+1. source-level revised_text through job detail review
+
+Read-only in first release:
+1. Job.document_id after create
+2. job status values managed by processing workflow
+3. provider/model/prompt values may be system-managed, but should remain visible in UI when known
+
+### 8.3 Update Save Behavior
+
+On revision save:
+1. validate revised text
+2. persist revised text for selected source
+3. update revised timestamp fields by system policy
+4. show success feedback
+
+On save failure:
+1. show clear error feedback
+2. preserve entered text where possible
+3. allow retry
+
+## 9. Delete and Retention Policy
+
+### 9.1 User Intent
+
+The user may need to remove invalid or duplicate jobs safely.
+
+### 9.2 First-Release Policy
+
+Delete behavior is policy-controlled:
+1. deletion may be blocked when related JobSource or source history must be retained
+2. blocked delete must explain constraints and cleanup path
+3. if allowed, delete requires explicit confirmation
+
+## 10. Relationship to Other Workflows
+
+Job workflow integrates with:
+1. Document workflow for ownership context
+2. Source workflow for uploaded page records and ordering
+3. Revision workflow for human correction lifecycle
+4. Worker processing workflow for queued execution and status transitions
+
+## 11. Relationship to Schema Mapping
+
+The companion schema-mapping document should specify:
+1. field visibility per CRUD action
+2. current implementation status
+3. intended behavior
+4. gap-to-target items
+
+## 12. Deferred Items
+
+Deferred to future revisions:
+1. manual retry controls from job detail
+2. advanced provider/model/prompt policy controls beyond basic create-time visibility
+3. advanced bulk actions across multiple jobs
+4. live streaming progress updates beyond refresh-based updates
+5. job templates or preset configurations
diff --git a/docs/ui/entities/traceability-matrix.md b/docs/ui/entities/traceability-matrix.md
new file mode 100644
index 0000000..fd73eb2
--- /dev/null
+++ b/docs/ui/entities/traceability-matrix.md
@@ -0,0 +1,68 @@
+# UI Entity Traceability Matrix
+
+Purpose: Map acceptance criteria to concrete implementation anchors and current delivery status.
+
+Updated: 2026-08-02
+
+Status legend:
+- Implemented: behavior exists in current UI and service flow
+- Partial: parts exist, but user-facing behavior or guardrails are incomplete
+- Planned: documented intent with no dedicated UI implementation yet
+
+## Document
+
+| Criteria Group | Acceptance IDs | Status | Primary Implementation Anchors | Notes |
+|---|---|---|---|---|
+| Read detail and metadata | RD-1, RD-2, RD-7 | Planned | src/transcription/ui/pages/jobs_page.py; src/transcription/ui/components/table/jobs.py; src/transcription/ui/components/transcript.py | No dedicated Document detail page yet; Document metadata is not rendered as first-class UI. |
+| Related sections and empty states | RD-3, RD-4, RD-5, RD-6 | Planned | src/transcription/ui/pages/jobs_page.py | Document-scoped related sections are defined in docs, not yet implemented in a dedicated Document view. |
+| Update entry and validation | UP-1, UP-2, UP-3, UP-4, UP-5, UP-6 | Planned | src/transcription/services/documents.py | Service update path exists; no dedicated Document edit UI flow yet. |
+| Delete controls and guardrails | DL-1, DL-2, DL-3, DL-4, DL-5 | Planned | src/transcription/services/documents.py | Service delete path exists; no UI delete control or dependency guard UX yet. |
+
+## Person
+
+| Criteria Group | Acceptance IDs | Status | Primary Implementation Anchors | Notes |
+|---|---|---|---|---|
+| Create flow and validation | CR-1, CR-2, CR-3, CR-4, CR-5 | Planned | src/transcription/services/documents.py | Person create service exists; no dedicated Person page/form yet. |
+| Read detail and linked documents | RD-1, RD-2, RD-3, RD-4 | Planned | src/transcription/services/documents.py; src/transcription/ui | No dedicated Person detail UI in current pages. |
+| Update behavior | UP-1, UP-2, UP-3, UP-4, UP-5 | Planned | src/transcription/services/documents.py | Service update exists; no first-class Person edit surface yet. |
+| Delete behavior and guardrails | DL-1, DL-2, DL-3, DL-4, DL-5 | Planned | src/transcription/services/documents.py | Service delete exists; relationship-aware UI guard flow is not implemented. |
+
+## Source
+
+| Criteria Group | Acceptance IDs | Status | Primary Implementation Anchors | Notes |
+|---|---|---|---|---|
+| Create entry and required links | CR-1, CR-2, CR-4, CR-5 | Partial | src/transcription/services/store.py; src/transcription/ui/pages/upload_page.py | Upload flow creates Document, Job, Source, and JobSource together; first-release job-context-only Source create intent is documented but not exposed as dedicated Source create UI. |
+| Ordering and filename policy | CR-3 | Partial | src/transcription/services/store.py | Current implementation persists generated filenames and assigns page_number in upload flow; target policy requires strict alphabetical ordering guidance and UUID.extension convention. |
+| Read and revision visibility | RD-1, RD-2, RD-3 | Implemented | src/transcription/ui/pages/jobs_page.py; src/transcription/ui/components/job_detail.py; src/transcription/ui/components/transcript.py | Source preview and revision context are available primarily in job detail flow. |
+| Revision update behavior | UP-1, UP-2, UP-3, UP-4 | Implemented | src/transcription/services/transcription.py; src/transcription/ui/pages/jobs_page.py; src/transcription/ui/components/transcript.py | Revised text editing and save feedback path exists in job detail revision flow. |
+| Delete and dependency guardrails | DL-1, DL-2, DL-3, DL-4, DL-5 | Planned | src/transcription/services/transcription.py | Source delete service path exists; dedicated UI delete control and guardrail messaging are not implemented. |
+
+## Job
+
+| Criteria Group | Acceptance IDs | Status | Primary Implementation Anchors | Notes |
+|---|---|---|---|---|
+| Create entry and required links | CR-1, CR-2, CR-5, CR-6 | Partial | src/transcription/services/store.py; src/transcription/ui/pages/upload_page.py; src/transcription/ui/pages/jobs_page.py | Current create path is upload-first and implicit; target requires explicit Create job flow from Jobs page. |
+| Source ordering and upload behavior | CR-3 | Partial | src/transcription/services/store.py | Current upload path is single-file create and uses service-assigned page defaults; target requires multi-file or folder handling with alphabetical ordering guidance. |
+| Provider/model/prompt visibility | CR-4, RD-4 | Partial | src/transcription/services/workflows.py; src/transcription/ui/pages/jobs_page.py | Values are populated in workflow updates but not rendered as first-class fields in current job detail. |
+| Jobs list and detail read states | RD-1, RD-2, RD-3, RD-5 | Implemented | src/transcription/ui/pages/jobs_page.py; src/transcription/ui/components/table/jobs.py; tests/ui/test_jobs_page.py | Jobs list, detail route, and invalid/missing id states are present. |
+| Revision update behavior | UP-1, UP-2, UP-3, UP-4 | Implemented | src/transcription/ui/pages/jobs_page.py; src/transcription/ui/components/transcript.py; src/transcription/services/transcription.py | Revision editing and save feedback exist in job detail source context. |
+| Lifecycle visibility and retry indicators | UP-5 | Partial | src/transcription/services/jobs.py; src/transcription/services/workflows.py; src/transcription/ui/pages/jobs_page.py | Status and retry_count are visible, but lifecycle controls remain system-managed and create-mode visibility targets are still pending. |
+| Delete and dependency guardrails | DL-1, DL-2, DL-3, DL-4, DL-5 | Planned | src/transcription/services/jobs.py | Backend delete exists; dedicated UI delete flow and policy messaging are not implemented. |
+
+## Quality Gate Coverage
+
+| Quality Gate | Acceptance IDs | Status | Notes |
+|---|---|---|---|
+| Separation of intent vs implementation | QG-1 across entities | Implemented | user-journey.md, schema-mapping.md, and acceptance-criteria.md are maintained per entity. |
+| Traceability from criteria to implementation | QG-2 across entities | Implemented | This matrix provides criterion-to-code anchors and current status tags. |
+| First-release constraints | QG-3 across entities | Partial | Constraints are documented for Document, Person, Source, and Job; implementation remains mixed across entities. |
+
+## Suggested Implementation Order
+
+1. Document: add dedicated detail/read surface and metadata rendering.
+2. Document: add edit and delete UI with dependency guardrails.
+3. Person: add create/read/update/delete pages and relationship-aware delete constraints.
+4. Job: add explicit Create job flow from Jobs page with Document selection and source upload controls.
+5. Job: render provider/model/prompt_name visibility in create and detail when known.
+6. Source: align create flow behavior with documented job-context-only invariant and ordering/filename policy.
+7. Source: add delete UI with dependency checks and blocked-delete guidance.