docs: align entity and UX docs with merged PRD model

Author: kdy1

docs/entities.md

@@ -185,6 +185,34 @@ enum StreamEventType {
 }
 ```
 
+## PRD Terminology Mapping
+
+| PRD term | Canonical entity model |
+|---|---|
+| Task | UnitTask |
+| Session | AgentSession (scoped by SubTask) |
+| PR Creation step | SubTask (`type = PR_CREATE`) |
+| Review/CI remediation step | SubTask (`type = PR_REVIEW_FIX` or `PR_CI_FIX`) |
+
+## PRD Task State Mapping (Derived UI Labels)
+
+PRD task labels are presentation-oriented states.
+Persisted source of truth remains `UnitTaskStatus`, `SubTaskStatus`, and `AgentSessionStatus`.
+
+| PRD label | Derived mapping in canonical model |
+|---|---|
+| Draft | client-side draft before UnitTask is created |
+| Queued | `UnitTaskStatus = QUEUED` and initial `SubTaskStatus = QUEUED` |
+| Running | `UnitTaskStatus = IN_PROGRESS` with active `SubTaskStatus = IN_PROGRESS` |
+| WaitingForHuman | `UnitTaskStatus = ACTION_REQUIRED` with `SubTaskStatus = WAITING_FOR_USER_INPUT` or `WAITING_FOR_PLAN_APPROVAL` |
+| PlanReady | `UnitTaskStatus = ACTION_REQUIRED` with `SubTaskStatus = WAITING_FOR_PLAN_APPROVAL` |
+| Approved | derived UI checkpoint after plan approval; persisted execution continues as `UnitTaskStatus = IN_PROGRESS` |
+| Building | derived UI checkpoint while build-phase SubTask is `IN_PROGRESS` |
+| PRCreating | derived UI checkpoint while `SubTaskType = PR_CREATE` and `SubTaskStatus = IN_PROGRESS` |
+| Completed | `UnitTaskStatus = COMPLETED` |
+| Failed | `UnitTaskStatus = FAILED` or active SubTask/session failed |
+| Canceled | `UnitTaskStatus = CANCELLED` or `SubTaskStatus = CANCELLED` |
+
 ## Core Entities
 
 ### Workspace

docs/notifications.md

@@ -15,6 +15,13 @@ DexDex uses Web Notification API as the primary desktop and mobile notification
 3. PR review activity requires remediation
 4. PR CI failure
 5. AgentSession failure
+6. Agent session requires human input (`WAITING_FOR_USER_INPUT`)
+7. Authentication/session refresh required for continued workflow
+
+Trigger mapping note:
+
+1. trigger semantics use existing notification enums in `docs/entities.md`
+2. auth-required prompts are represented through action-required notification categories
 
 ## Notification Flow
 

docs/ui.md

@@ -27,6 +27,12 @@ Desktop layout:
 3. Center pane: task and PR list with filters
 4. Right pane: details, timeline, and actions
 
+Focused three-pane variant for detail-heavy workflows:
+
+1. left: task list and workspace switcher
+2. center: active task detail and timeline
+3. right: collapsed history, side activity, and auxiliary context
+
 Mobile layout:
 
 1. top segmented tabs (Tasks, PRs, Review Assist, Notifications)
@@ -103,6 +109,9 @@ Sections:
 3. PR Attention queue
 4. Completed recently
 
+Completed work is retained, not deleted.
+The default behavior is collapsed history that users can expand on demand.
+
 Each card includes:
 
 1. title
@@ -135,6 +144,22 @@ Contains:
 9. stop controls for in-progress UnitTask and SubTask
 10. inline comment threads anchored to diff lines
 
+## Task Creation UX
+
+Task creation uses a modal flow with keyboard-first submit.
+
+Required inputs:
+
+1. Repository Group
+2. Task Prompt
+
+Optional and policy-driven inputs:
+
+1. execution mode selector (local or remote, workspace policy dependent)
+2. coding agent selection
+3. plan-mode preference when supported by selected agent
+4. suggested task title
+
 ### Stop Controls
 
 Users can stop running work with minimal friction:

docs/workspace-connectivity.md

@@ -45,3 +45,9 @@ Both types use the same:
 
 Mobile clients use the same workspace concept.
 A mobile app can connect to local endpoints (same network or tunneled) and remote endpoints.
+
+Capability rollout is phased:
+
+1. baseline mobile flow focuses on remote monitoring, logs, plan actions, and stop actions
+2. expanded mobile flow adds broader remediation and review interactions
+3. connectivity contract stays identical across desktop and mobile