docs: merge PRD into canonical design and align docs (#258)

## Summary
- merge the new PRD into docs/design.md as the single canonical
reference
- align architecture docs with main-server canonical communication and
Rust server stack wording
- add PRD-to-entity/state mapping and update UI/mobile/notification docs
for consistency

## What changed
- update design/api/main-server/worker-server/tauri docs to reflect the
merged architecture decisions
- add PRD terminology and task-state presentation mapping in entities
doc
- update UI and workspace/mobile connectivity wording for parity-focused
rollout

## Scope
- documentation only
- no proto or application code changes

Author: kdy1

docs/api.md

@@ -3,6 +3,11 @@
 This document defines the DexDex API contract.
 All business communication is Connect RPC-based.
 
+## Contract Alignment Note
+
+This document is the product and architecture source of truth for API behavior.
+Proto/code synchronization may lag this document and is tracked as follow-up work.
+
 ## Protocol
 
 - Transport: HTTP/2 (fallback HTTP/1.1 where needed)
@@ -17,6 +22,8 @@ All business communication is Connect RPC-based.
 3. Public requests and responses use enums for known variants.
 4. Streaming channels emit typed events with monotonic sequence IDs.
 5. Coding-agent session output contracts are normalized and provider-agnostic.
+6. Main server is the canonical business API boundary for clients.
+7. Client applications do not call worker-server internals directly for business flows.
 
 ## Service Overview
 

docs/design.md

@@ -1,30 +1,64 @@
 # DexDex Design
 
-DexDex uses a Connect RPC-first architecture with Tauri clients and Rust servers.
+DexDex is a cross-platform orchestration UI for CLI-based coding agents.
+DexDex uses a Connect RPC-first architecture with Tauri clients and Go servers.
 This document is the primary architecture reference.
 
+## Product Overview
+
+DexDex orchestrates coding agents such as Claude Code, OpenCode, and Codex CLI.
+DexDex does not implement model reasoning logic. It coordinates agent execution, stores execution history, and visualizes progress and outcomes.
+
+Primary outcomes:
+
+1. task orchestration with clear action states
+2. multi-repository execution with deterministic repository order
+3. plan approval and revision loop in UI
+4. PR creation and remediation as first-class flows
+5. real-time logs and event streaming
+6. local and remote execution through a unified API contract
+
 ## Product Goals
 
 1. Use Tauri as the desktop and mobile app container.
-2. Use Rust for `main-server` and `worker-server`.
+2. Use Go for `main-server` and `worker-server`.
 3. Use `Workspace` as the primary connectivity and scope concept.
 4. Use UnitTask-centric workflows with nested SubTask and AgentSession history.
 5. Make PR management and PR review assist first-class workflows.
 6. Provide real-time event streaming for UI updates and automation.
-7. Support iOS and Android as first-wave platforms.
+7. Treat desktop, iOS, and Android as first-class platforms with phased capability rollout.
 
 ## Non-Goals
 
 1. Direct local folder execution without worktree.
 2. Tauri-invoke-first business contracts.
 3. Native OS notification plugin as the primary notification channel.
+4. Building a proprietary coding-agent runtime that replaces CLI agents.
+5. Hosting git repositories.
+
+## Platform Strategy
+
+### Desktop
+
+Desktop and mobile are both product-priority platforms.
+Desktop is optimized for dense authoring workflows and keyboard-heavy interaction.
+
+### Mobile
+
+Mobile uses the same API and data model as desktop.
+Capability rollout is phased by interaction constraints, not platform priority:
+
+1. baseline support: task monitoring, log viewing, approval and stop actions, and core remediation triggers
+2. expanded support: broader remediation, review interaction, and authoring parity as UX matures
+
+Mobile is not a separate business-logic path.
 
 ## Top-Level Architecture
 
 ```
                         Connect RPC + Event Streams
 ┌───────────────────────┐   https://api endpoint   ┌───────────────────────┐
-│ Tauri Client          │ <----------------------> │ Main Server (Rust)    │
+│ Tauri Client          │ <----------------------> │ Main Server (Go)      │
 │ (Desktop / iOS /      │                          │ - RPC API             │
 │  Android)             │                          │ - Workspace/Task/PR   │
 │ - React UI            │                          │ - Event broker        │
@@ -34,19 +68,25 @@ This document is the primary architecture reference.
             │                                                   │ Connect RPC
             │                                                   │
             │                                         ┌─────────▼──────────┐
-            │                                         │ Worker Server (Rust) │
+            │                                         │ Worker Server (Go)   │
             │                                         │ - Worktree exec    │
             │                                         │ - Agent sessions   │
             │                                         │ - Log stream       │
             │                                         └────────────────────┘
 ```
 
+Communication rule:
+
+1. client business communication is main-server canonical
+2. client does not open direct business channels to worker server
+3. worker communication is server-to-server through Connect RPC
+
 ## Monorepo Structure
 
-- `apps/main-server/` (Rust)
-- `apps/worker-server/` (Rust)
+- `apps/main-server/` (Go)
+- `apps/worker-server/` (Go)
 - `apps/tauri-app/` (Tauri + React)
-- shared Rust crates under `crates/` with Cargo workspace management
+- shared crates and shared packages under `crates/`
 
 ## Deployment Profiles
 
@@ -97,6 +137,12 @@ Each workspace points to a main server endpoint.
 - endpoint runs on a network-hosted server
 - uses the same RPC and streaming contracts
 
+Workspace contains:
+
+1. repository groups
+2. UnitTasks and SubTasks
+3. workspace-scoped settings and policies
+
 ## Data Model Overview
 
 Detailed model is maintained in `docs/entities.md`.
@@ -130,6 +176,7 @@ SubTask is also used for small operational tasks triggered by UI actions.
 ### AgentSession
 
 Each SubTask can run one or more AI coding agent sessions.
+Only one AgentSession is active at a time for a given SubTask.
 
 ```
 UnitTask
@@ -142,6 +189,28 @@ UnitTask
         └── AgentSession #4
 ```
 
+Terminology mapping for PRD wording:
+
+1. PRD `Task` maps to `UnitTask`
+2. PRD `Session` maps to `AgentSession` (scoped by `SubTask`)
+
+## Execution Modes
+
+DexDex supports local and remote execution modes with a shared orchestration contract.
+
+### Local Mode
+
+1. execution happens on the user environment through worker runtime
+2. repository handling is worktree-only
+
+### Remote Mode
+
+1. execution happens on remote worker server
+2. repository bootstrap may use clone or cache refresh
+3. execution always runs in task-specific worktrees after bootstrap
+
+This keeps one invariant across both modes: `repo-cache/bootstrap + worktree execution`.
+
 ## Agent Message Normalization Boundary
 
 Worker server is the normalization boundary for all coding-agent outputs.
@@ -162,6 +231,8 @@ Worker-produced code changes must be represented as real git commits.
 4. PR creation and Commit to Local use this commit chain as the source of truth.
 5. Patch artifacts are derived from commits for diff viewing and are not authoritative.
 
+The ghost-commit concept is not used as a storage or orchestration model.
+
 ## Worktree-Only Policy
 
 DexDex does not support editing directly against arbitrary local folders.
@@ -235,6 +306,8 @@ For coding agents with plan mode:
 3. stream plan updates and rationale
 4. attach plan decisions to SubTask and AgentSession records
 
+Plan semantics remain agent-native. DexDex stores and orchestrates decisions, but does not replace the agent's planning logic.
+
 See `docs/plan-yaml.md`.
 
 ## Event Streaming
@@ -267,25 +340,34 @@ Notification delivery uses Web Notification API.
 
 See `docs/notifications.md`.
 
-## Mobile Strategy
+## UI Shell Strategy
 
-iOS and Android are first-wave platforms.
+DexDex uses a multi-tab triage-first shell as the default.
 
-Design implications:
+1. workspace-oriented navigation and action-required queues
+2. tabbed detail workflows with persistent draft state
+3. keyboard-first operation across primary screens
 
-1. core workflows must be API-driven and mobile-safe
-2. no desktop-only business logic path
-3. notification and streaming strategy must work with mobile runtime constraints
-4. workspace onboarding and PR remediation actions must be touch-friendly
+A focused three-pane detail layout can be used as a screen-level variant:
 
-## Multi-Tab UI Invariant
+1. left: task list or context rail
+2. center: task detail and timeline
+3. right: collapsed history or side activity
 
-The client provides multi-tab UI so users can work on multiple items concurrently.
+## Settings Scope
 
-1. detail views and workflow pages open as tabs in the app shell
-2. tab state is persisted per workspace
-3. tab switching does not discard running context or unsaved draft input
-4. tab state indicators surface running/action-required/unread-update signals
+Settings cover both currently implemented controls and staged integrations.
+
+Immediate scope:
+
+1. appearance mode (Light, Dark, System)
+2. keyboard shortcut settings and discoverability
+3. workspace and notification preferences
+
+Staged scope with security guardrails:
+
+1. agent credential import flows (for example OAuth token bridging)
+2. worker environment variable profiles with least-privilege handling, scoped exposure, and audit logs
 
 ## Keyboard Input Rule
 
@@ -304,6 +386,12 @@ Every screen includes appropriate keyboard shortcuts for its primary items and a
 5. shortcut matching uses physical key codes and modifiers so behavior is stable across input language modes
 6. tab management shortcuts are required (`new`, `close`, `previous`, `next`)
 
+## Task Status Presentation Model
+
+Storage status uses three-level enums (`UnitTaskStatus`, `SubTaskStatus`, `AgentSessionStatus`).
+UI may present simplified derived labels (for example Draft, PlanReady, Building) that map to underlying entity states.
+The persisted source of truth remains the three-level enum model in `docs/entities.md`.
+
 ## Observability and Logging
 
 Server-side structured logging is required for:
@@ -327,6 +415,12 @@ Client-side logging is required for:
 2. token-based auth for shared remote workspaces
 3. scoped secret usage with minimal runtime lifetime
 4. strict validation for repository URLs, branch names, prompts, and review payloads
+5. guarded handling for staged credential-transfer and worker-env settings
+
+## Documentation Alignment Scope
+
+This revision aligns architecture and product docs as the source of truth.
+Code and proto contract synchronization is tracked as follow-up work and is not part of this document-only integration.
 
 ## Related Docs
 

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/main-server.md

@@ -52,6 +52,7 @@ It exposes Connect RPC APIs and coordinates task, PR, and event lifecycles.
 
 Main server is the canonical business interface.
 No client workflow requires Tauri-only business contracts.
+Client business flows and streaming subscriptions are routed through main server; direct client-to-worker business channels are not part of the contract.
 
 ## Data Ownership
 

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/tauri-app.md

@@ -8,12 +8,21 @@ The app is Connect RPC-first.
 Business communication uses Connect RPC as the primary path.
 Tauri-specific APIs are only for platform integration.
 Client consumes normalized coding-agent message contracts only.
+The app does not use direct client-to-worker business APIs.
 
 ## Supported Platforms
 
 1. Desktop: macOS, Windows, Linux
 2. Mobile: iOS, Android
 
+## Capability Rollout
+
+Desktop and mobile are both first-class product targets on the same contracts.
+Capability rollout is phased by interaction constraints:
+
+1. baseline: task monitoring, log viewing, plan decisions, stop actions, and key remediation actions
+2. expansion: broader remediation, review interaction, and deeper authoring parity
+
 ## Client Architecture
 
 ```
@@ -164,6 +173,13 @@ Client exposes immediate stop actions:
 2. badge color mapping editor
 3. PR auto-fix preferences
 4. notification permission and display preferences
+5. appearance mode (Light, Dark, System)
+6. shortcut discoverability and keymap preferences
+
+Staged settings with security guardrails:
+
+1. agent credential import/bridge flows
+2. worker environment profile management with scoped secret handling
 
 ## Testing Focus