docs: unify PRD into canonical architecture docs

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,8 +1,23 @@
 # DexDex Design
 
+DexDex is a desktop-first orchestration UI for CLI-based coding agents.
 DexDex uses a Connect RPC-first architecture with Tauri clients and Rust 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.
@@ -11,13 +26,31 @@ This document is the primary architecture reference.
 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. Support iOS and Android as first-wave 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 is the primary platform for full authoring and remediation workflows.
+
+### Mobile
+
+Mobile uses the same API and data model as desktop.
+Capability rollout is phased:
+
+1. baseline support: remote task monitoring, log viewing, approval and stop actions
+2. expanded support: broader remediation and review actions as UX matures
+
+Mobile is not a separate business-logic path.
 
 ## Top-Level Architecture
 
@@ -41,6 +74,12 @@ This document is the primary architecture reference.
             │                                         └────────────────────┘
 ```
 
+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)
@@ -97,6 +136,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 +175,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 +188,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 +230,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 +305,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 +339,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 +385,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 +414,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/main-server.md

@@ -1,4 +1,4 @@
-# Main Server (Go)
+# Main Server (Rust)
 
 Main Server is the control plane for DexDex.
 It exposes Connect RPC APIs and coordinates task, PR, and event lifecycles.
@@ -19,7 +19,7 @@ It exposes Connect RPC APIs and coordinates task, PR, and event lifecycles.
 
 ```
 ┌──────────────────────────────────────────────────────────────┐
-│ Main Server (Go)                                             │
+│ Main Server (Rust)                                           │
 │                                                              │
 │  Connect RPC Handlers                                        │
 │   ├── WorkspaceService                                       │
@@ -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/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 provides the full authoring workflow.
+Mobile uses phased rollout on the same contracts:
+
+1. baseline: task monitoring, log viewing, plan decisions, and stop actions
+2. expansion: broader remediation and review interaction flows
+
 ## 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
 

docs/worker-server.md

@@ -1,4 +1,4 @@
-# Worker Server (Go)
+# Worker Server (Rust)
 
 Worker Server executes SubTasks using AI coding agents in isolated worktree environments.
 
@@ -22,7 +22,7 @@ Worker Server executes SubTasks using AI coding agents in isolated worktree envi
 
 ```
 ┌──────────────────────────────────────────────────────────────┐
-│ Worker Server (Go)                                           │
+│ Worker Server (Rust)                                         │
 │                                                              │
 │  Job Receiver (Connect RPC client/server)                    │
 │    └── SubTask Runner                                        │
@@ -50,6 +50,12 @@ Worker Server executes SubTasks using AI coding agents in isolated worktree envi
 8. export patch and metadata derived from commits
 9. cleanup according to retention policy
 
+Execution mode note:
+
+1. remote and local modes may use different repository bootstrap strategies
+2. both modes execute task runs in worktrees after bootstrap
+3. worker does not expose a direct business API for client-side calls
+
 Path convention:
 
 - cache: `~/.dexdex/repo-cache/<repo-hash>/`