UI update planning complete

docs/ui/entities/document-person/schema-mapping.md

@@ -0,0 +1,182 @@
+# DocumentPerson Schema-to-UI Mapping
+
+Purpose: Map the DocumentPerson schema to UI-facing workflows, while separating intended target behavior from current implementation.
+
+Supporting entity note: DocumentPerson does not currently have a standalone UI surface.
+
+## 1. Entity Snapshot
+
+- Table: document_person
+- Primary key: id (UUID)
+- Related entities: Document, Person
+- Canonical schema references:
+  - src/transcription/db/models.py
+  - docs/schema_v2.md
+
+## 2. Mapping Rules
+
+This document uses three lenses:
+1. Intended behavior: what user-facing workflows should support indirectly.
+2. Current behavior: what code supports today.
+3. Gap to target: what must change to align implementation with intended UX.
+
+## 3. Field Inventory
+
+| Field | DB Type | Nullable | Default/Auto Value | Intended UI Treatment | Notes |
+|---|---|---|---|---|---|
+| id | UUID | No | uuid4() | Hidden, system-managed | Primary key |
+| document_id | UUID FK | No | None | Context-managed | Selected Document context |
+| person_id | UUID FK | No | None | Context-managed | Selected Person context |
+| role | enum DocumentPersonRole | No | author | Visible in relationship context | First-release behavior may default to author |
+| created_at | datetime | No | datetime.now(UTC) | Hidden or read-only | System-managed timestamp |
+
+Constraint behavior:
+1. document_id, person_id, and role are unique as a tuple.
+2. duplicate links for the same document, person, and role must be rejected.
+
+## 4. CREATE Mapping
+
+### 4.1 Intended Create Flow
+
+Entry points are indirect through user-facing entities:
+1. Document create or update workflows may create one or more DocumentPerson links.
+2. Person relationship workflows may create DocumentPerson links.
+
+| Field | Intended User Input | Required | Visible | Notes |
+|---|---|---|---|---|
+| document_id | None | Yes | No | Derived from selected Document |
+| person_id | None | Yes | No | Derived from selected Person |
+| role | Select or default | Yes | Indirectly | Defaults to author in first-release behavior |
+| created_at | None | No | No | System-generated |
+
+### 4.2 Current Implementation
+
+Current entry point: service-level creation via DocumentService.create_document_person()  
+Current user action: no dedicated DocumentPerson UI  
+Current backend path: Document and Person workflows call DocumentPerson CRUD in DocumentService
+
+| Field | Current Value at Create | Source | Visible to User | Evidence |
+|---|---|---|---|---|
+| id | Generated UUID | System | No | src/transcription/db/models.py |
+| document_id | Caller-provided | Service/API caller | No | src/transcription/services/documents.py |
+| person_id | Caller-provided | Service/API caller | No | src/transcription/services/documents.py |
+| role | Caller-provided or default author | Service/model default | No | src/transcription/db/models.py, src/transcription/services/documents.py |
+| created_at | Current UTC timestamp | System | No | src/transcription/db/models.py |
+
+### 4.3 Gap to Target
+
+To satisfy intended supporting behavior, implementation must add:
+1. explicit UI relationship controls in Document and/or Person detail flows.
+2. duplicate-link handling with clear user feedback.
+3. role-selection UX when role expansion is enabled beyond default author.
+
+## 5. READ Mapping
+
+### 5.1 Intended Read Behavior
+
+Users should see DocumentPerson relationships indirectly in user-facing surfaces:
+1. Document detail shows linked people.
+2. Person detail shows linked documents.
+3. Relationship role is shown where relevant.
+
+### 5.2 Current Implementation
+
+Current read behavior is mainly service-level.
+
+| Field | Current Rendering | Visible to User | Notes | Evidence |
+|---|---|---|---|---|
+| document_id/person_id link | Indirect relationship usage in workflows | Partial | Document/Person dedicated relationship surfaces are planned | docs/ui/entities/document/*, docs/ui/entities/person/* |
+| role | Not shown in current job-centric pages | No | Role expansion is deferred in user-facing workflows | docs/ui/entities/person/user-journey.md |
+| created_at | Not rendered | No | Operational metadata only | current UI pages |
+
+Service read/query coverage:
+1. read_document_person() returns one link by id.
+2. list_document_people() supports filtering by document_id and person_id.
+
+### 5.3 Gap to Target
+
+To satisfy intended read behavior, implementation must add:
+1. linked-people and linked-documents UI sections backed by list_document_people().
+2. relationship role display where role context is required.
+
+## 6. UPDATE Mapping
+
+### 6.1 Intended Update Behavior
+
+DocumentPerson updates are limited to relationship role or relationship-management actions.
+
+Intended editable fields:
+- role (when role management is enabled)
+
+Intended read-only fields:
+- id
+- document_id
+- person_id
+- created_at
+
+### 6.2 Current Implementation
+
+| Field | Updatable via UI | Updatable via Service | Notes |
+|---|---|---|---|
+| role | No | Yes | DocumentService.update_document_person() supports updates |
+| document_id/person_id | No | Technically yes via full-row update | Should generally be treated as immutable link identity |
+| created_at | No | Technically yes | Should remain system-managed |
+
+### 6.3 Gap to Target
+
+Implementation should add:
+1. explicit relationship-role edit controls when product scope enables them.
+2. safeguards against mutating link identity instead of recreating links.
+
+## 7. DELETE Mapping
+
+### 7.1 Intended Delete Behavior
+
+Deletion of DocumentPerson should be exposed as unlink behavior in Document and Person flows.
+
+Rules:
+1. unlink should remove only the selected relationship.
+2. unlink must not delete the underlying Document or Person records.
+
+### 7.2 Current Implementation
+
+| Action | UI Exposed | Backend Capability | Notes |
+|---|---|---|---|
+| Delete DocumentPerson link | No | Yes | DocumentService.delete_document_person() exists |
+
+### 7.3 Gap to Target
+
+Implementation must add:
+1. unlink controls in relationship sections.
+2. confirmation and success feedback for relationship removal.
+3. blocked-delete guidance if policy constraints are added later.
+
+## 8. Hidden and System-Managed Fields
+
+| Field | Category | Why Hidden or Protected |
+|---|---|---|
+| id | System-managed | Internal identifier |
+| document_id | Context-managed | Derived from selected Document |
+| person_id | Context-managed | Derived from selected Person |
+| created_at | System-managed | Audit timestamp |
+
+## 9. Traceability Anchors
+
+Schema and models:
+- docs/schema_v2.md
+- src/transcription/db/models.py
+
+Current implementation:
+- src/transcription/services/documents.py
+- tests/services/test_v2_crud.py
+
+Related user-facing workflows:
+- docs/ui/entities/document/user-journey.md
+- docs/ui/entities/person/user-journey.md
+
+## 10. Coverage Summary
+
+- Every DocumentPerson schema field appears in the field inventory.
+- Intended behavior is defined as supporting workflow behavior rather than standalone UI.
+- Current behavior reflects service-level CRUD with no dedicated UI.
+- Gaps between intended and current behavior are explicit.

docs/ui/entities/document/acceptance-criteria.md

@@ -119,8 +119,8 @@ This checklist does not cover:
 ## Cross-Criteria Quality Gates
 
 ### QG-1 Separation of intent and implementation
-1. Journey intent remains in docs/ui/entities/document/user-journey.md
+1. UX intent remains in user-journey.md
-2. Current versus target implementation mapping remains in docs/ui/entities/document/schema-mapping.md
+2. Current versus target implementation mapping remains in schema-mapping.md
 
 ### QG-2 Traceability
 1. Each accepted behavior maps to at least one future UI action or service call path

docs/ui/entities/document/user-journey.md

@@ -4,6 +4,7 @@ Purpose: Define how a user should interact with the UI to create and manage a Do
 
 Scope: This document describes intended user interaction for the Document UI. It is the UX contract for the Document entity.
 
+Companion schema mapping: schema-mapping.md
 Companion acceptance criteria: acceptance-criteria.md
 
 ## 1. Overview
@@ -273,7 +274,7 @@ A user can reach a Document detail page by:
 The Document detail page should include:
 1. a header area with document name, document type, and key date values
 2. a metadata section with location_created, notes, and archive_identifier
-3. system metadata where created_at and updated_at are shown as read-only values
+3. System metadata where created_at and updated_at are shown as read-only values
 4. a related people section
 5. a Sources section
 6. a Jobs section
@@ -294,9 +295,9 @@ If no related records exist:
 ### 11.5 Read Success Criteria
 
 A successful Read experience means:
-1. user can identify the Document immediately
+1. The user can identify the Document immediately
-2. user can see whether work has started
+2. The user can see whether work has started
-3. user can navigate directly to document-scoped Jobs and Sources workflows
+3. The user can navigate directly to document-scoped Jobs and Sources workflows
 
 ## 12. Update Document Journey
 
@@ -307,7 +308,7 @@ The user wants to correct or enrich metadata after creation without touching job
 ### 12.2 Update Entry Point
 
 From the Document detail page:
-1. user selects Edit document
+1. The user selects Edit document
 2. UI opens edit mode or a dedicated edit view
 
 ### 12.3 Editable Fields
@@ -346,10 +347,10 @@ On save:
 ### 12.6 Update Failure Behavior
 
 If save fails:
-1. show a clear error message
+1. Show a clear error message
 2. keep user edits in form where possible
 3. do not show stale success messaging
-4. allow retry without losing context
+4. Allow retry without losing context
 
 ## 13. Delete Document Journey
 
@@ -360,7 +361,7 @@ The user wants to remove a Document only when it is safe and unambiguous.
 ### 13.2 Delete Entry Point
 
 From the Document detail page:
-1. user selects Delete document
+1. The user selects Delete document
 2. UI opens a confirmation dialog explaining permanence
 
 ### 13.3 Delete Guardrails
@@ -376,15 +377,15 @@ Delete is blocked when:
 ### 13.4 Blocked Delete UX
 
 When blocked:
-1. show an explicit reason that related Jobs or Sources exist
+1. Show an explicit reason that related Jobs or Sources exist
-2. show which dependency types are present
+2. Show which dependency types are present
 3. provide links to filtered Sources and Jobs for cleanup
 4. keep the Document unchanged
 
 ### 13.5 Allowed Delete UX
 
 When allowed:
-1. show final confirmation with document name
+1. Show final confirmation with document name
 2. perform delete
 3. show success confirmation
 4. return user to Document page list
@@ -392,7 +393,7 @@ When allowed:
 ### 13.6 Delete Failure Behavior
 
 If delete fails due to system error:
-1. show a clear error message
+1. Show a clear error message
 2. keep user on Document detail page
 3. preserve ability to retry
 

docs/ui/entities/job-source/schema-mapping.md

@@ -0,0 +1,206 @@
+# JobSource Schema-to-UI Mapping
+
+Purpose: Map the JobSource schema to UI-facing workflows, while separating intended target behavior from current implementation.
+
+Supporting entity note: JobSource does not currently have a standalone UI surface.
+
+## 1. Entity Snapshot
+
+- Table: job_source
+- Primary key: id (UUID)
+- Related entities: Job, 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 user-facing workflows should support indirectly.
+2. Current behavior: what code supports today.
+3. Gap to target: what must change to align implementation with intended UX.
+
+## 3. Field Inventory
+
+| Field | DB Type | Nullable | Default/Auto Value | Intended UI Treatment | Notes |
+|---|---|---|---|---|---|
+| id | UUID | No | uuid4() | Hidden, system-managed | Primary key |
+| job_id | UUID FK | No | None | Context-managed | Selected Job context |
+| source_id | UUID FK | No | None | Context-managed | Selected Source context |
+| status | enum JobSourceStatus | No | pending | Shown in job detail source context | Per-source execution state |
+| raw_transcription | str | Yes | None | Shown read-only in review context | Machine output per source |
+| ai_metadata | JSONB/JSON | Yes | None | Hidden or advanced diagnostics | Provider metadata |
+| raw_api_response | JSONB/JSON | Yes | None | Hidden or advanced diagnostics | Low-level provider payload |
+| error_detail | str | Yes | None | Shown when status is failed | Execution failure details |
+| executed_at | datetime | No | datetime.now(UTC) | Shown read-only | Execution timestamp |
+
+## 4. CREATE Mapping
+
+### 4.1 Intended Create Flow
+
+JobSource creation is indirect through Job and transcription workflows:
+1. Job create flow should create a JobSource row for each uploaded source page.
+2. Processing workflow may create missing JobSource rows when persisting transcription output.
+
+| Field | Intended User Input | Required | Visible | Notes |
+|---|---|---|---|---|
+| job_id | None | Yes | No | Derived from active Job |
+| source_id | None | Yes | No | Derived from created/selected Source |
+| status | None | No | Indirectly | Defaults to pending at create |
+| raw_transcription | None | No | No at create | Filled after processing |
+| ai_metadata | None | No | No | Operational metadata |
+| raw_api_response | None | No | No | Operational payload |
+| error_detail | None | No | No at create | Filled on failure |
+| executed_at | None | No | No | System-generated |
+
+### 4.2 Current Implementation
+
+Current entry points:
+1. upload create path adds pending JobSource link in _create_upload_records().
+2. transcription update path creates or updates JobSource row during output persistence.
+
+Current backend paths:
+1. src/transcription/services/store.py -> _create_upload_records()
+2. src/transcription/services/transcription.py -> update_job_transcription()
+
+| Field | Current Value at Create/Update | Source | Visible to User | Evidence |
+|---|---|---|---|---|
+| id | Generated UUID | System | No | src/transcription/db/models.py |
+| job_id | Caller or workflow derived | Service/workflow | Indirectly | store.py, transcription.py |
+| source_id | Caller or workflow derived | Service/workflow | Indirectly | store.py, transcription.py |
+| status | pending at create, transcribed or failed on update | Workflow logic | Partial | transcription.py |
+| raw_transcription | Set on successful transcription update | Workflow/provider result | Yes in review context | transcription.py, jobs UI |
+| ai_metadata | Available in model; not currently filled in update path | Workflow potential | No | models.py, transcription.py |
+| raw_api_response | Available in model; not currently filled in update path | Workflow potential | No | models.py, transcription.py |
+| error_detail | Set on failed transcription update | Workflow/provider error | Partial | transcription.py |
+| executed_at | Set at row creation and refreshed on updates | System/workflow | Partial | models.py, transcription.py |
+
+### 4.3 Gap to Target
+
+To satisfy intended supporting behavior, implementation must add:
+1. explicit per-source status display for all linked sources in Job detail.
+2. clear surfaced error_detail for failed source executions.
+3. optional diagnostics surface for ai_metadata/raw_api_response when needed.
+4. first-class multi-source create path from Job create flow.
+
+## 5. READ Mapping
+
+### 5.1 Intended Read Behavior
+
+Users should see JobSource data indirectly in job detail and review workflows:
+1. per-source execution status.
+2. per-source raw transcription output.
+3. per-source failure details where applicable.
+4. execution timestamp context.
+
+### 5.2 Current Implementation
+
+Current read behavior is partial and job-detail-centric.
+
+| Field | Current Rendering | Visible to User | Notes | Evidence |
+|---|---|---|---|---|
+| status | Job-level status is visible; source-level status is limited | Partial | Source-level status not fully surfaced as a dedicated list | src/transcription/ui/pages/jobs_page.py |
+| raw_transcription | Original transcription card is visible | Yes | Primary source is shown in current detail flow | src/transcription/ui/components/transcript.py |
+| error_detail | Not prominently surfaced in current detail UI | Partial | Stored in JobSource rows during failures | src/transcription/services/transcription.py |
+| executed_at | Not first-class rendered | Partial | Available in model for future display | src/transcription/db/models.py |
+
+Service read/query coverage:
+1. read_job_source() reads one row with source relation.
+2. list_job_sources() lists rows and supports job_id filtering.
+
+### 5.3 Gap to Target
+
+To satisfy intended read behavior, implementation must add:
+1. source-level execution table in Job detail.
+2. explicit failed-source messaging from error_detail.
+3. multi-source navigation in job review UI.
+
+## 6. UPDATE Mapping
+
+### 6.1 Intended Update Behavior
+
+JobSource updates are workflow-managed, not directly user-edited.
+
+Intended user-editable fields:
+- none in first-release behavior
+
+Workflow-managed fields:
+- status
+- raw_transcription
+- error_detail
+- executed_at
+- optional diagnostics payload fields
+
+### 6.2 Current Implementation
+
+| Field | Updatable via UI | Updatable via Service/Workflow | Notes |
+|---|---|---|---|
+| status | No | Yes | Set by transcription update and job lifecycle handling |
+| raw_transcription | No | Yes | Persisted in update_job_transcription() |
+| error_detail | No | Yes | Persisted on transcription failure |
+| executed_at | No | Yes | Updated when existing JobSource rows are changed |
+| ai_metadata/raw_api_response | No | Potentially yes | Model supports them; active population is limited |
+
+### 6.3 Gap to Target
+
+Implementation should add:
+1. clearer job-detail visualization of per-source execution updates.
+2. optional operator diagnostics views for advanced troubleshooting.
+
+## 7. DELETE Mapping
+
+### 7.1 Intended Delete Behavior
+
+JobSource deletion should be policy-driven and usually tied to Job/Source lifecycle operations.
+
+Rules:
+1. direct user deletion is not required in first-release behavior.
+2. cleanup should occur through Job or Source deletion policies.
+
+### 7.2 Current Implementation
+
+| Action | UI Exposed | Backend Capability | Notes |
+|---|---|---|---|
+| Delete JobSource row | No | Yes | TranscriptionService.delete_job_source() exists |
+
+### 7.3 Gap to Target
+
+Implementation may add:
+1. maintenance tooling for cleanup operations.
+2. policy-aware cascade guidance in Job and Source delete flows.
+
+## 8. Hidden and System-Managed Fields
+
+| Field | Category | Why Hidden or Protected |
+|---|---|---|
+| id | System-managed | Internal identifier |
+| job_id | Context-managed | Derived from Job context |
+| source_id | Context-managed | Derived from Source context |
+| ai_metadata | Operational metadata | Advanced diagnostics payload |
+| raw_api_response | Operational metadata | Raw provider response payload |
+| executed_at | System-managed | Execution timestamp |
+
+## 9. Traceability Anchors
+
+Schema and models:
+- docs/schema_v2.md
+- src/transcription/db/models.py
+
+Current implementation:
+- src/transcription/services/store.py
+- src/transcription/services/transcription.py
+- src/transcription/services/workflows.py
+- src/transcription/ui/pages/jobs_page.py
+- src/transcription/ui/components/transcript.py
+- tests/services/test_v2_crud.py
+
+Related user-facing workflows:
+- docs/ui/entities/job/user-journey.md
+- docs/ui/entities/source/user-journey.md
+
+## 10. Coverage Summary
+
+- Every JobSource schema field appears in the field inventory.
+- Intended behavior is defined as supporting workflow behavior rather than standalone UI.
+- Current behavior reflects workflow/service-driven CRUD with partial job-detail visibility.
+- Gaps between intended and current behavior are explicit.

docs/ui/entities/job/acceptance-criteria.md

@@ -98,7 +98,7 @@ This checklist does not cover:
 
 ### UP-2 Revision validation
 1. revised_text cannot be saved as empty after trimming
-2. warning feedback is shown for invalid empty input
+2. Warning feedback is shown for invalid empty input
 
 ### UP-3 Successful revision save
 1. Given valid revision text
@@ -149,7 +149,7 @@ This checklist does not cover:
 
 ### 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
+2. Current versus target implementation mapping remains in schema-mapping.md
 
 ### QG-2 Traceability
 1. Each accepted behavior maps to at least one UI action or service path

docs/ui/entities/job/user-journey.md

@@ -76,9 +76,9 @@ The user wants to start a transcription run by selecting the right Document and
 
 ### 5.2 Create Entry
 
-1. user opens the Jobs page
+1. The user opens the Jobs page
-2. user selects Create job
+2. The user selects Create job
-3. system opens Job detail/create page in create mode
+3. The system opens Job detail/create page in create mode
 
 ### 5.3 Create Inputs
 
@@ -93,9 +93,9 @@ The user wants to start a transcription run by selecting the right Document and
 
 ### 5.4 Source Handling Rules
 
-1. each uploaded file becomes a Source linked to the selected Document
+1. Each uploaded file becomes a Source linked to the selected Document
-2. each created Source is linked to the Job through JobSource
+2. Each created Source is linked to the Job through JobSource
-3. multi-file or folder uploads are processed alphabetically by original filename
+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
 
@@ -124,7 +124,7 @@ On submit:
 
 Recommended transactional behavior:
 1. intended create writes should succeed or fail together
-2. user should not receive false success when required records fail
+2. The user should not receive false success when required records fail
 
 ### 5.7 Create Success Result
 
@@ -132,12 +132,12 @@ 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
+4. The user can monitor progress and open page-level review
 
 ### 5.8 Create Failure Result
 
 If create fails:
-1. show clear error message
+1. Show clear error message
 2. preserve entered selections where possible
 3. keep retry path available
 4. do not show false success feedback
@@ -177,11 +177,11 @@ If no jobs exist:
 2. list shows Create job action
 
 If a job id is invalid or missing:
-1. show clear not found state
+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
+1. Show clear warning state
 2. keep recovery guidance visible
 
 ## 7. Job Status Lifecycle UX
@@ -199,23 +199,23 @@ The UI should map to model-backed job states:
 ### 7.2 In-Progress States
 
 When status is queued or processing:
-1. show active progress state
+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
+1. Show completion success state
 2. direct user to revision workflow
 
 When status is partial_success:
-1. show mixed outcome state
+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
+1. Show failure state with actionable message
 2. keep navigation and retry guidance available
 
 ## 8. Update Job Journey
@@ -243,9 +243,9 @@ On revision save:
 4. show success feedback
 
 On save failure:
-1. show clear error feedback
+1. Show clear error feedback
 2. preserve entered text where possible
-3. allow retry
+3. Allow retry
 
 ## 9. Delete and Retention Policy
 

docs/ui/entities/person/acceptance-criteria.md

@@ -132,7 +132,7 @@ This checklist does not cover:
 
 ### QG-1 Separation of intent and implementation
 1. UX intent remains in user-journey.md
-2. current versus target implementation mapping remains in schema-mapping.md
+2. Current versus target implementation mapping remains in schema-mapping.md
 
 ### QG-2 Traceability
 1. Each accepted behavior maps to at least one future UI action or service call path

docs/ui/entities/person/user-journey.md

@@ -131,10 +131,10 @@ Date handling rule:
 ## 7. Submission Behavior
 
 On submit:
-1. system validates required fields
+1. The system validates required fields
-2. system creates Person record
+2. The system creates the Person record
-3. system returns user to Person detail page
+3. The system returns the user to the Person detail page
-4. system shows success message
+4. The system shows a success message
 
 Recommended transactional behavior:
 1. Person writes are atomic
@@ -143,16 +143,16 @@ Recommended transactional behavior:
 ## 8. Expected Result After Success
 
 After successful creation:
-1. user sees Person detail page for the new record
+1. The user sees the Person detail page for the new record
 2. full_name is visible in the header or summary
 3. empty Related Documents section is shown if no links exist
-4. user can proceed to link this person from Document workflows
+4. The user can proceed to link this person from Document workflows
 
 ## 9. Expected Result After Failure
 
 If creation fails:
-1. show clear error message
+1. Show a clear error message
-2. show field-level feedback for validation failures
+2. Show field-level feedback for validation failures
 3. preserve entered data where possible
 4. do not show false success messaging
 
@@ -176,7 +176,7 @@ The Person detail page should show:
 ### 10.3 Read Empty State
 
 If no linked documents exist:
-1. show No linked documents yet
+1. Show No linked documents yet
 2. provide guidance to link from Document workflow
 
 ## 11. Update Person Journey
@@ -217,9 +217,9 @@ On save:
 
 ### 11.4 Update Failure Behavior
 
-1. show clear error feedback
+1. Show clear error feedback
 2. preserve form state where possible
-3. allow retry
+3. Allow retry
 
 ## 12. Delete Person Journey
 
@@ -238,12 +238,12 @@ Delete is blocked when:
 ### 12.3 Blocked Delete UX
 
 1. explain that linked Document relationships exist
-2. show link count or list
+2. Show link count or list
 3. provide cleanup path
 
 ### 12.4 Allowed Delete UX
 
-1. show confirmation dialog
+1. Show a confirmation dialog
 2. confirm permanent action
 3. delete Person
 4. return to Person list with success message

docs/ui/entities/source/acceptance-criteria.md

@@ -128,7 +128,7 @@ This checklist does not cover:
 
 ### 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
+2. Current versus target implementation mapping remains in schema-mapping.md
 
 ### QG-2 Traceability
 1. Each accepted behavior maps to at least one future UI action or service path

docs/ui/entities/source/user-journey.md

@@ -61,11 +61,11 @@ The user wants to attach one or more files to a Document so each page can be pro
 
 ### 5.2 Create from Job Context
 
-1. user starts from a job-creation or job-configuration flow
+1. The user starts from a job-creation or job-configuration flow
-2. user can upload one or more files, or upload a whole folder
+2. The user can upload one or more files, or upload a whole folder
-3. system creates Source rows linked to the selected Document
+3. The system creates Source rows linked to the selected Document
-4. system creates JobSource links for the active Job as part of this flow
+4. The system creates JobSource links for the active Job as part of this flow
-5. source creation fails if required Document or Job linkage cannot be established
+5. Source creation fails if required Document or Job linkage cannot be established
 
 ### 5.3 Source Create Inputs
 
@@ -106,7 +106,7 @@ After successful source create:
 1. Source is linked to the Document
 2. Source appears in page order derived from alphabetical upload filename ordering
 3. Source is linked to the Job through JobSource at create time
-4. user can open preview and revision workflow
+4. The user can open preview and revision workflow
 
 ### 5.8 Source Creation Invariant
 
@@ -135,13 +135,13 @@ The UI should show:
 ### 6.3 Read Empty and Missing States
 
 If source is missing:
-1. show clear not found or no source available messaging
+1. Show clear not found or no source available messaging
 
 If source has no revision:
-1. show empty-state guidance and create-revision action
+1. Show empty-state guidance and create-revision action
 
 If source metadata is partially unavailable:
-1. show fallback labels and keep preview and revision actions available where possible
+1. Show fallback labels and keep preview and revision actions available where possible
 
 ## 7. Update Source Journey
 
@@ -175,9 +175,9 @@ On save:
 ### 7.4 Revision Failure Behavior
 
 If save fails:
-1. show clear error feedback
+1. Show clear error feedback
 2. keep user input where possible
-3. allow retry
+3. Allow retry
 
 ## 8. Delete Source Journey
 
@@ -197,7 +197,7 @@ Delete is blocked when:
 
 When blocked:
 1. explain dependency constraints
-2. show cleanup guidance
+2. Show cleanup guidance
 
 When allowed:
 1. confirm permanent removal

docs/ui/entities/traceability-matrix.md

@@ -57,6 +57,13 @@ Status legend:
 | 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. |
 
+## Supporting Entity Coverage
+
+| Supporting Entity | Documentation | Status | Notes |
+|---|---|---|---|
+| document-person | docs/ui/entities/document-person/schema-mapping.md | Completed | Supporting-entity schema mapping created; no standalone UI contract file by design. |
+| job-source | docs/ui/entities/job-source/schema-mapping.md | Completed | Supporting-entity schema mapping created; no standalone UI contract file by design. |
+
 ## Suggested Implementation Order
 
 1. Document: add dedicated detail/read surface and metadata rendering.