Add cross-platform ADRs and xplat planning doc (#2737)

docs/adrs/0001-host-capability-interface.md

+# ADR-0001: Host Capability Interface
+
+- Status: Proposed
+- Date: 2026-02-15
+- Owners: Platform Core
+- Related plan: `plans/desktop-mobile-web-unification.md`
+
+## Context
+
+Dyad currently routes privileged actions through Electron IPC (`src/preload.ts`, `src/ipc/types/*`, `src/ipc/handlers/*`). This tightly couples product logic to desktop-only primitives:
+
+- local filesystem access
+- local process execution
+- local git and shell operations
+- desktop-only OS/system APIs
+
+Web and mobile clients cannot reuse this runtime model directly. We need one product core that can run against multiple execution hosts:
+
+- desktop local host
+- cloud host
+
+## Decision
+
+Adopt a host capability interface as the canonical execution boundary for privileged operations.
+
+The shared product core will depend on a `HostProvider` contract, not directly on Electron IPC channels or HTTP endpoints.
+
+### Interface shape
+
+`HostProvider` exposes capability groups:
+
+- `project`: read/write/rename/delete/list/search file operations
+- `exec`: run/stop commands, stream logs/output
+- `git`: branch/commit/status/sync operations
+- `preview`: start/stop/status/getPreviewUrl
+- `integration`: provider-specific operations (supabase/vercel/neon/mcp)
+- `system`: optional host/system functions (open external URL, show in folder, clipboard/screenshot)
+- `session`: session cache/state controls
+
+Each operation must include a standard envelope:
+
+- `workspaceId`
+- `projectId`
+- `requestId`
+- `idempotencyKey`
+- `actor` (user/system/assistant)
+- `timestamp`
+
+Each operation returns:
+
+- success payload OR typed error payload
+- `correlationId` for tracing
+
+### Streaming model
+
+Streaming operations must follow a uniform event contract:
+
+- `start`
+- `chunk`
+- `end`
+- `error`
+
+Desktop provider maps this to IPC streams; cloud provider maps this to WebSocket/SSE streams.
+
+### Capability negotiation
+
+Hosts must declare supported capabilities at runtime (for example `supportsProcess`, `supportsNativeDialogs`, `supportsShowItemInFolder`), and UI/features must gate behavior accordingly.
+
+## Consequences
+
+### Positive
+
+- Enables shared domain logic across desktop/web/mobile.
+- Prevents transport-specific logic from leaking into features.
+- Creates deterministic observability across hosts.
+- Simplifies adding future hosts.
+
+### Negative
+
+- Requires incremental refactor of existing IPC handlers and call sites.
+- Adds short-term complexity with compatibility adapters.
+- Requires strict contract/version governance.
+
+## Alternatives Considered
+
+### A. Keep Electron IPC as primary and build web/mobile translators
+
+Rejected because it preserves desktop coupling and creates brittle emulation layers.
+
+### B. Build separate APIs per platform
+
+Rejected because it duplicates business logic and causes long-term behavior drift.
+
+### C. Move everything to cloud and remove local mode
+
+Rejected for now because it breaks existing local-first desktop workflows.
+
+## Rollout Plan
+
+1. Introduce interface and adapter layers in shared packages.
+2. Wrap desktop local flows with `ElectronLocalHostProvider`.
+3. Migrate critical flows first: chat stream, response apply, app run/stop, git core.
+4. Enforce host capability checks in UI.
+5. Add `CloudHostProvider` for desktop cloud mode, then web/mobile.
+
+## Acceptance Criteria
+
+- Desktop local mode behavior remains functionally equivalent on migrated flows.
+- At least one end-to-end flow runs through both providers with identical domain behavior.
+- Stream contracts are transport-agnostic and versioned.
+
+## Open Questions
+
+1. Should integration-specific capabilities be in `integration.*` or split into first-class capability groups?
+2. What is the minimum backward compatibility window for provider contract versions?

docs/adrs/0002-cloud-runtime-topology.md

+# ADR-0002: Cloud Runtime Topology
+
+- Status: Proposed
+- Date: 2026-02-15
+- Owners: Runtime Services
+- Related plan: `plans/desktop-mobile-web-unification.md`
+
+## Context
+
+Web and mobile clients need privileged execution capabilities that currently exist only in Electron main process:
+
+- filesystem mutation
+- command/process execution
+- git operations
+- preview lifecycle management
+
+These capabilities require a secure multi-tenant backend architecture with strong isolation, streaming support, and auditability.
+
+## Decision
+
+Adopt a control-plane + worker-plane topology.
+
+### Control plane
+
+Services:
+
+- `api-gateway`: external API entry, auth verification, rate limiting
+- `workspace-service`: workspace/project metadata and permissions
+- `operation-orchestrator`: validates and queues privileged operations
+- `stream-broker`: fan-out for operation events and chat/runtime streams
+- `audit-service`: immutable operation/audit log ingestion
+
+### Worker plane
+
+Services:
+
+- `runtime-scheduler`: allocates isolated runtime instances
+- `runtime-worker`: executes filesystem/command/preview operations per project
+- `git-worker`: executes git operations in isolated workspaces (can be separate or embedded initially)
+
+### Data plane
+
+- relational store for control metadata (workspaces, projects, operations)
+- object storage for snapshots/artifacts/log archives
+- secret vault for credentials (never persisted in plain metadata tables)
+
+## Isolation and Security Constraints
+
+- Strong tenant isolation at runtime instance boundary.
+- Project execution roots are sandboxed per runtime instance.
+- Command execution must run with deny-by-default security policies.
+- Network egress policy controls by workspace/project tier.
+- Every privileged operation must emit an auditable event with actor, scope, and result.
+
+## Streaming and Execution Semantics
+
+- Operations are asynchronous with queued execution where needed.
+- Each operation emits typed lifecycle events: `queued`, `started`, `chunk`, `completed`, `failed`.
+- Clients reconnect using `correlationId` and replay cursor.
+- Idempotency keys prevent duplicate writes on retries.
+
+## Region and Availability Strategy
+
+Initial:
+
+- single region deployment with disaster recovery backups
+- active-passive failover for control services
+
+Follow-up:
+
+- multi-region runtime placement
+- project region pinning for data residency and latency
+
+## Consequences
+
+### Positive
+
+- Enables web/mobile execution with desktop-comparable capabilities.
+- Separates policy/orchestration from execution for safer scaling.
+- Supports consistent observability and auditing.
+
+### Negative
+
+- Operational complexity and infra cost increase.
+- Requires robust SRE, security, and incident response maturity.
+- Cold starts and queue latency can degrade UX if not controlled.
+
+## Alternatives Considered
+
+### A. Single monolithic runtime service
+
+Rejected because it mixes orchestration and execution concerns, making scaling and security controls harder.
+
+### B. Fully serverless per-operation execution only
+
+Rejected because long-lived previews and streaming command output need persistent runtime context.
+
+### C. Desktop relay model (browser/mobile tunnel into user desktop)
+
+Rejected for v1 due to reliability, availability, and connectivity constraints.
+
+## Rollout Plan
+
+1. Build minimal control plane and runtime worker for file ops + command execution.
+2. Add stream broker and reliable event replay.
+3. Add preview lifecycle management and runtime pooling.
+4. Add git worker path and integration-specific execution policies.
+5. Introduce multi-region strategy after stable single-region operations.
+
+## Acceptance Criteria
+
+- Cloud project can execute core file and command operations with audited traces.
+- Stream reliability meets defined SLOs under target concurrency.
+- Isolation and security checks pass internal and external reviews.
+
+## Open Questions
+
+1. Should git run in dedicated workers from day one, or inside runtime workers initially?
+2. What runtime class tiers are required for cost/performance segmentation at beta launch?

docs/adrs/0003-authentication-authorization-model.md

+# ADR-0003: Authentication and Authorization Model
+
+- Status: Proposed
+- Date: 2026-02-15
+- Owners: Platform Security
+- Related plan: `plans/desktop-mobile-web-unification.md`
+
+## Context
+
+A multi-platform Dyad requires remote privileged execution. This introduces security requirements not present in desktop-only local mode:
+
+- user identity across devices
+- workspace-level access control
+- operation-level authorization and consent
+- secure storage and use of provider secrets
+- end-to-end auditing for sensitive actions
+
+## Decision
+
+Adopt an identity-first model using OIDC authentication, workspace RBAC authorization, and policy-gated privileged operations.
+
+## Authentication Model
+
+- Use OIDC/OAuth2 for user authentication across desktop/web/mobile.
+- Use short-lived access tokens and rotatable refresh tokens.
+- Desktop, web, and mobile clients use platform-appropriate secure token storage.
+- Service-to-service communication uses mTLS and signed service identities.
+
+## Authorization Model
+
+### Workspace RBAC
+
+Base roles:
+
+- `owner`
+- `admin`
+- `editor`
+- `viewer`
+
+Permissions are evaluated against:
+
+- workspace
+- project
+- operation type
+- host capability
+
+### Operation policy layer
+
+In addition to RBAC, high-risk operations require policy checks:
+
+- destructive file deletes
+- destructive SQL
+- force push/history rewrite
+- shell commands outside safe policy
+
+Policy outcomes:
+
+- allow
+- require user approval
+- deny
+
+## Secrets Model
+
+- Provider credentials stored in centralized secret vault.
+- Secrets encrypted with envelope encryption (KMS-managed keys).
+- Secrets scoped minimally (workspace/project/provider).
+- Runtime workers receive short-lived scoped secret grants, not raw long-lived credentials.
+- Secret access events are fully audited.
+
+## Audit and Compliance Requirements
+
+Every privileged operation must log:
+
+- actor id
+- workspace/project scope
+- operation type
+- policy decision
+- result status
+- correlation id
+- timestamp
+
+Audit logs must be immutable and queryable for incident response.
+
+## Consequences
+
+### Positive
+
+- Unified identity and access model across all platforms.
+- Defense-in-depth for privileged cloud operations.
+- Clear compliance and forensic posture.
+
+### Negative
+
+- Higher implementation complexity than simple API key auth.
+- Requires policy engine ownership and ongoing governance.
+- Increased onboarding complexity for workspace/admin concepts.
+
+## Alternatives Considered
+
+### A. API key only auth for clients
+
+Rejected due to poor revocation, weak identity semantics, and high leakage risk.
+
+### B. RBAC only without operation policy layer
+
+Rejected because role permissions alone are too coarse for high-risk operations.
+
+### C. Store all secrets client-side and forward on demand
+
+Rejected because it increases exposure and complicates cross-device continuity.
+
+## Rollout Plan
+
+1. Implement OIDC auth + workspace/session primitives.
+2. Introduce baseline RBAC enforcement across API endpoints.
+3. Add operation policy engine for high-impact actions.
+4. Migrate provider secrets to centralized vault and deprecate legacy paths.
+5. Add immutable audit log store and admin audit views.
+
+## Acceptance Criteria
+
+- All cloud API operations require authenticated identity and scoped authorization.
+- High-risk operations enforce policy with approval/deny semantics.
+- Secret access is scoped, short-lived, and auditable.
+- Security testing validates token, RBAC, and policy boundaries.
+
+## Open Questions
+
+1. Do we need custom enterprise SSO/SAML in beta or post-GA?
+2. What is the default approval policy for non-destructive command execution?
+3. What audit retention period is required by target compliance commitments?

docs/adrs/README.md

+# Architecture Decision Records
+
+This directory stores Architecture Decision Records (ADRs) for major technical decisions.
+
+## ADR List
+
+- [ADR-0001: Host Capability Interface](./0001-host-capability-interface.md)
+- [ADR-0002: Cloud Runtime Topology](./0002-cloud-runtime-topology.md)
+- [ADR-0003: Authentication and Authorization Model](./0003-authentication-authorization-model.md)
+
+## Status Definitions
+
+- `Proposed`: drafted and under review
+- `Accepted`: approved and should guide implementation
+- `Superseded`: replaced by a newer ADR
+- `Rejected`: considered but not adopted

plans/desktop-mobile-web-unification.md

+# Dyad Universal Platform Plan (Desktop + Web + Mobile)
+
+> Generated by swarm planning workflow on 2026-02-15
+
+## Summary
+
+Evolve Dyad from a desktop-only Electron runtime into a multi-platform product with one core experience available on desktop, web, and mobile. Preserve Dyad's local-first strengths on desktop while introducing a secure cloud execution runtime that powers equivalent capabilities on web/mobile where local process and filesystem access are unavailable. Deliver this in phased releases with strict compatibility, observability, and rollback controls.
+
+## Problem Statement
+
+Dyad's architecture currently assumes a privileged local host (Electron main process) that can mutate files, spawn processes, run git/npm/docker, handle native protocol links, and store secrets via OS APIs. That creates three constraints:
+
+1. Users cannot use Dyad from browsers, tablets, or phones.
+2. Collaboration and continuity across devices is limited.
+3. Product growth depends on desktop installation and local toolchain reliability.
+
+The core user problem is cross-device continuity for AI app building without losing the trust, transparency, and production-grade workflows Dyad already supports.
+
+## Product Principles Alignment
+
+This plan explicitly preserves Dyad's principles:
+
+- `Backend-Flexible`: runtime providers (local host, cloud runtime) are pluggable behind one capability interface.
+- `Productionizable`: generated code remains standard user-owned code; cloud runtime is execution infrastructure, not a proprietary app runtime.
+- `Intuitive + Power User Friendly`: default paths are simplified, advanced knobs remain available per host.
+- `Transparent Over Magical`: every remote execution action is surfaced with logs, diffs, approvals, and host/source labels.
+- `Bridge, Don't Replace`: existing git, npm, Docker, Supabase workflows continue; web/mobile use remote bridges where local host access is impossible.
+- `Delightful`: consistent high-quality interactions across platforms with platform-native ergonomics.
+
+## Scope
+
+### In Scope (MVP to GA)
+
+- Introduce a host-agnostic execution architecture: `LocalHost` (desktop) + `CloudHost` (web/mobile, optional desktop).
+- Extract shared product core (domain logic, schemas, query keys, prompts, contract models) into reusable packages.
+- Deliver:
+  - Desktop app (Electron) with both local and cloud host modes.
+  - Web app (browser) using cloud host mode.
+  - Mobile app (React Native) using cloud host mode with mobile-specific UX.
+- Build secure cloud runtime services for:
+  - Project filesystem operations
+  - Command/process execution
+  - Streaming logs/events/chunks
+  - Git operations
+  - Secret storage and provider credentials
+  - Project/session persistence
+- Implement identity, auth, authorization, org/workspace model, and audit trails for remote operations.
+- Add deterministic operation model for approvals and replay safety.
+- Provide migration tools to import desktop projects into cloud workspaces and export back to local repos.
+- Establish full testing matrix (unit/integration/e2e/load/security) across all three clients.
+
+### Out of Scope (Initial)
+
+- Full offline web/mobile parity with local process execution.
+- Mobile local code execution sandbox equivalent to desktop Node/Docker.
+- Real-time multiplayer editing (beyond single-user multi-device continuity).
+- Replacing existing desktop local mode as default for current users.
+
+## Target Users
+
+1. Existing desktop power users who want optional cloud continuity.
+2. New users who want instant web onboarding without installing desktop tooling.
+3. Mobile-first users who need monitoring/approval/light editing and AI interaction on the go.
+4. Teams needing shared cloud workspaces and centralized auditability.
+
+## User Stories
+
+- As a desktop user, I want to keep local mode exactly as today while optionally enabling cloud sync so I can work from any device.
+- As a web user, I want to create/import a project and run previews without local setup so I can start immediately.
+- As a mobile user, I want to review AI changes, approve/reject actions, and trigger fixes so I can keep momentum away from my laptop.
+- As a power user, I want explicit visibility into whether an action runs locally or remotely so I can trust the system.
+- As a security-conscious user, I want granular permissions, audit logs, and scoped credentials for all remote operations.
+
+## UX Design
+
+### Universal IA
+
+Global top-level structure across platforms:
+
+1. Workspace switcher
+2. Project list
+3. Chat + plan + execution timeline
+4. Code/preview/problem surfaces (platform-adapted)
+5. Settings (provider + runtime + integrations + security)
+
+### Host Awareness UX
+
+Every execution surface displays host source:
+
+- `Local Host (Desktop)`
+- `Cloud Host (Region)`
+
+Every action card includes:
+
+- actor (`user`, `assistant`, `system`)
+- host
+- operation type (`write`, `rename`, `command`, `git`, `sql`, etc.)
+- approval state
+- request/correlation ids
+
+### Platform-specific UX
+
+Desktop:
+
+- Retain full editor + preview + process console + branch workflows.
+- Add host toggle per project (`Local`, `Cloud`, `Hybrid` later).
+
+Web:
+
+- Same interaction model as desktop, minus local-only controls.
+- Web-safe file pickers and managed imports.
+- Browser-native auth/session management.
+
+Mobile:
+
+- Chat-first and task-first workflow.
+- Focus on review/approval, logs, quick edits, plan management, and notifications.
+- Optional compact code diff viewer, not full IDE parity in v1.
+
+### Key States (All Platforms)
+
+- Default: last opened project, host badge visible.
+- Loading: stream-level progress and host-labeled steps.
+- Empty: onboarding flows (create/import/connect repo).
+- Error: user-actionable messages with host context and retry semantics.
+- Degraded: partial capability mode when host lacks permissions.
+
+### Accessibility
+
+- Keyboard-first behavior on desktop/web.
+- VoiceOver/TalkBack screen reader semantics on mobile.
+- Reduced motion settings propagated from platform preferences.
+- High contrast, robust focus states, and large touch targets on mobile.
+
+## Technical Design
+
+## Architecture
+
+### Current State (Desktop-only)
+
+- Renderer React app calls contract-generated IPC clients.
+- Preload mediates channel allowlist.
+- Main process owns privileged capabilities.
+
+### Target State (Universal)
+
+Introduce a `Host Capability Layer` and split concerns:
+
+1. `Client Shells`
+   - Electron desktop shell
+   - Web shell
+   - Mobile shell
+2. `Shared Product Core`
+   - Shared types/schemas/validation
+   - Shared domain state machine
+   - Shared query key + API contract definitions
+   - Shared chat/tag parsing/rendering primitives
+3. `Host Providers`
+   - `ElectronLocalHostProvider` (desktop local)
+   - `CloudHostProvider` (web/mobile + optional desktop)
+4. `Dyad Cloud Runtime Services`
+   - Project FS service
+   - Exec service
+   - Git service
+   - Streaming broker
+   - Secret service
+   - Workspace/project metadata service
+   - Telemetry/audit service
+
+### Host Capability Interface
+
+Define one canonical interface consumed by shared product logic:
+
+- `host.project.readFile/writeFile/rename/delete/list/search`
+- `host.exec.runCommand/stop/streamLogs`
+- `host.git.*`
+- `host.preview.start/stop/getUrl`
+- `host.db.executeSql` (or delegated integration service)
+- `host.secrets.get/set/listScopes`
+- `host.system.openExternal/showInFolder` (optional capability)
+- `host.session.*`
+
+Each method includes:
+
+- idempotency key
+- actor context
+- workspace/project context
+- auth context
+- correlation id
+
+### Transport Strategy
+
+Desktop local:
+
+- Existing IPC transport remains.
+- Gradual migration from raw channel usage to host interface adapter.
+
+Web/mobile:
+
+- HTTPS + WebSocket/SSE for RPC + stream channels.
+- Unified event model mirroring IPC stream contracts.
+
+### Data Model Changes
+
+Introduce platform-neutral IDs and workspace ownership:
+
+- `workspaces`
+- `projects`
+- `project_hosts` (local/cloud binding + capabilities)
+- `sessions`
+- `operations`
+- `operation_logs`
+- `credentials` (scoped/rotatable/encrypted)
+- `runtime_instances`
+
+Desktop local DB remains for local-only metadata and cache; cloud state is source of truth for cloud projects.
+
+### Security Model
+
+- OAuth/OIDC sign-in with device session management.
+- Workspace RBAC (`owner`, `admin`, `editor`, `viewer`).
+- Operation policy engine for dangerous actions.
+- Explicit consent model for high-impact operations (`rm`, destructive SQL, force push).
+- Secret encryption with KMS/HSM-backed envelope keys.
+- Signed short-lived runtime tokens.
+- Tenant isolation at filesystem + process + network layers.
+- Full audit trail for every remote privileged operation.
+
+### Preview/Runtime Model
+
+- Desktop local preview uses existing local process workflow.
+- Cloud preview runs in isolated runtime instances (container/sandbox).
+- Preview URLs proxied through policy-aware gateway for script injection and security headers.
+- Mobile/web connect to the same preview stream endpoints and event bus.
+
+### Compatibility Strategy
+
+- Keep existing desktop local paths functional behind adapters during migration.
+- Contract compatibility versioning:
+  - `v1`: legacy IPC contracts
+  - `v2`: host API contracts
+- Dual-write and read-fallback for transitional metadata.
+
+## Components Affected
+
+### Desktop Existing Areas (Refactor Required)
+
+- `src/main.ts` — split shell bootstrap from capability execution wiring.
+- `src/preload.ts` + `src/ipc/preload/channels.ts` — transition to host adapter entrypoints.
+- `src/ipc/contracts/core.ts` + `src/ipc/types/*` — extract reusable contract/core package.
+- `src/ipc/handlers/*` — split into:
+  - local provider implementations
+  - shared domain orchestration handlers
+- `src/ipc/processors/response_processor.ts` — host-agnostic operation application engine.
+- `src/ipc/handlers/chat_stream_handlers.ts` — move stream orchestration into shared domain + host-specific execution delegates.
+- `src/main/settings.ts` — evolve to multi-host config model.
+- `src/db/*` — local cache role clarification and migration helpers.
+
+### New Package/Module Structure (Proposed)
+
+- `packages/core-domain/`
+  - state machines
+  - operation orchestration
+  - validation and policies
+- `packages/contracts/`
+  - shared contract schemas (zod/openapi derivation)
+- `packages/client-sdk/`
+  - web/mobile/desktop transport adapters
+- `packages/ui-shared/`
+  - cross-platform primitives and design tokens
+- `apps/desktop-electron/`
+- `apps/web/`
+- `apps/mobile/`
+- `services/runtime-api/`
+- `services/runtime-worker/`
+- `services/git-api/`
+- `services/ops-audit/`
+
+### Mobile Stack Recommendation
+
+- React Native + Expo (or bare RN if native modules become mandatory quickly).
+- Reuse shared domain + contracts + query/state logic.
+- Native-only wrappers for push notifications, secure storage, deep links.
+
+### Web Stack Recommendation
+
+- React + TanStack Router/Query shared with desktop where possible.
+- SSR optional; start with SPA + API gateway.
+- Progressive enhancement for heavier features.
+
+## Implementation Plan
+
+### Phase 0: Alignment, Constraints, and Success Contracts
+
+- [ ] Define platform parity goals by feature tier (`Core`, `Advanced`, `Desktop-only`).
+- [ ] Publish cross-platform capability matrix with explicit non-goals.
+- [ ] Finalize SLOs for cloud runtime (`p95 latency`, `stream reliability`, `runtime startup time`).
+- [ ] Define compliance/security baseline (SOC2 controls, secret handling, audit retention).
+- [ ] Create architecture decision records (ADRs) for host interface and cloud runtime topology.
+
+Exit criteria:
+
+- Stakeholder signoff on scope and phased parity guarantees.
+- Measurable release gates approved.
+
+### Phase 1: Monorepo Restructure and Shared Core Extraction
+
+- [ ] Create `packages/contracts` from `src/ipc/contracts` + `src/ipc/types`.
+- [ ] Create `packages/core-domain` for shared orchestration logic.
+- [ ] Move shared schema utilities out of Electron-only folders.
+- [ ] Introduce platform-agnostic logger, event model, and error taxonomy.
+- [ ] Keep desktop app compiling via compatibility wrappers.
+
+Exit criteria:
+
+- Desktop builds unchanged behavior behind wrappers.
+- Shared packages consumed by desktop with zero functional regression in e2e smoke suite.
+
+### Phase 2: Host Capability Layer on Desktop
+
+- [ ] Implement `ElectronLocalHostProvider` that wraps existing handlers.
+- [ ] Route key flows (`chat stream`, `response apply`, `run app`, `git`) through host interface.
+- [ ] Add capability negotiation mechanism (`supportsProcess`, `supportsNativeDialogs`, etc.).
+- [ ] Instrument host operation timings and failures.
+
+Exit criteria:
+
+- Desktop local mode fully driven through host abstraction.
+- Legacy direct paths removed for migrated flows.
+
+### Phase 3: Cloud Runtime Foundation
+
+- [ ] Build `runtime-api` service with authn/authz + workspace/project model.
+- [ ] Build `runtime-worker` for isolated filesystem/process execution.
+- [ ] Implement operation queue, idempotency, and stream broker.
+- [ ] Introduce cloud secret vault integration.
+- [ ] Implement project persistence and snapshot strategy.
+
+Exit criteria:
+
+- Can create cloud project, write/read files, run command, stream logs via API.
+- End-to-end audited operations with trace ids.
+
+### Phase 4: Cloud Host Provider + Desktop Cloud Mode
+
+- [ ] Implement `CloudHostProvider` SDK in client packages.
+- [ ] Add desktop runtime mode toggle (`Local`, `Cloud`).
+- [ ] Support project import/sync between local and cloud.
+- [ ] Add conflict resolution strategy for divergent histories.
+- [ ] Add host badges and per-action host attribution in UI.
+
+Exit criteria:
+
+- Desktop can operate entirely against cloud host for selected projects.
+- Existing local workflows remain stable.
+
+### Phase 5: Web App MVP
+
+- [ ] Create `apps/web` shell using shared core/domain/contracts.
+- [ ] Implement auth/session/bootstrap flows.
+- [ ] Integrate cloud host provider for project/chat/preview workflows.
+- [ ] Add browser-safe file import flows.
+- [ ] Deliver first web e2e suite with parity against desktop cloud mode for core flows.
+
+Exit criteria:
+
+- Web supports create/import project, prompt->apply, preview, git basic operations.
+
+### Phase 6: Mobile App MVP
+
+- [ ] Create `apps/mobile` shell with shared domain and cloud provider.
+- [ ] Implement mobile chat + approvals + timeline + lightweight diff view.
+- [ ] Add push notifications for long-running operations and approval requests.
+- [ ] Add mobile-friendly preview handoff (deep link to preview URL/webview).
+- [ ] Harden reconnect/resume behavior on app backgrounding.
+
+Exit criteria:
+
+- Mobile supports review/approve/change-request workflows and basic prompting on cloud projects.
+
+### Phase 7: Integration Hardening (Git, Supabase, Vercel, MCP)
+
+- [ ] Move integration handlers behind host/service boundaries.
+- [ ] Define cloud-safe equivalents for local shell-dependent tasks.
+- [ ] Add provider-level policy controls and rate limits.
+- [ ] Add integration fallback messaging when host lacks specific capability.
+
+Exit criteria:
+
+- Core integrations function consistently across desktop cloud/web/mobile.
+
+### Phase 8: Data Migration and Interop
+
+- [ ] Build desktop migration assistant:
+  - project selection
+  - credential remapping
+  - dry-run diff
+  - import execution
+- [ ] Build export assistant from cloud project to local git repo.
+- [ ] Implement reversible migration metadata for rollback.
+
+Exit criteria:
+
+- User can migrate a desktop project to cloud and back with deterministic results.
+
+### Phase 9: Security, Compliance, and Abuse Protection
+
+- [ ] Threat model all privileged cloud operations.
+- [ ] Add abuse limits (process quotas, network egress policy, command allow/deny policies).
+- [ ] Add malware/exfiltration safeguards in runtime sandboxes.
+- [ ] Complete security penetration test and incident response runbooks.
+
+Exit criteria:
+
+- Security review gates passed for public web/mobile beta.
+
+### Phase 10: Observability, Reliability, and Cost Controls
+
+- [ ] Distributed tracing across client -> API -> worker.
+- [ ] Runtime utilization dashboards and budget guardrails.
+- [ ] Auto-scaling + cold-start mitigation strategies.
+- [ ] SLO-based alerting and on-call playbooks.
+
+Exit criteria:
+
+- Runtime meets agreed SLOs under synthetic and beta traffic.
+
+### Phase 11: GA Rollout
+
+- [ ] Controlled alpha (internal), private beta, public beta, GA.
+- [ ] Feature flags by platform and workspace tier.
+- [ ] In-app education and migration guides.
+- [ ] Post-GA stabilization sprint and backlog reprioritization.
+
+Exit criteria:
+
+- Multi-platform GA with stable desktop local mode and production-grade cloud mode.
+
+## Detailed Change-by-Change Mitigation Matrix
+
+| Current Desktop-Tied Change Area                       | Why It Breaks on Web/Mobile                               | Planned Solution                                                                | Migration Steps                                                           | Risks                      | Mitigations                                             |
+| ------------------------------------------------------ | --------------------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | -------------------------- | ------------------------------------------------------- |
+| Electron window lifecycle                              | Browser/mobile don't expose app-level window control APIs | Abstract `window controls` as optional capabilities; no-op/alt UX on web/mobile | Add `capabilities.system.windowControls` checks and branch UI actions     | UX inconsistency           | Platform-specific UI patterns with explicit affordances |
+| Preload/IPC channel model                              | No `contextBridge` outside Electron                       | Replace IPC with shared host API transport adapters                             | Build `client-sdk` with IPC adapter + HTTP/WS adapter                     | Contract drift             | Shared contract package + compatibility tests           |
+| Direct FS mutation (`fs`, recursive ops)               | Browser sandbox and mobile filesystem constraints         | Move FS ops to cloud runtime service for web/mobile                             | Route all file ops through host provider interface                        | Latency, partial failures  | Operation queue + optimistic UI + retry/idempotency     |
+| Local process spawn (`spawn`, `npm`, `pnpm`, `docker`) | Impossible in browser and limited on mobile               | Cloud execution workers provide command runtime                                 | Map command operations to runtime API endpoints                           | Multi-tenant security      | Sandbox isolation, policy engine, egress restrictions   |
+| Local git binaries and repo operations                 | Browser/mobile lack full git CLI integration              | Cloud git service + optional libgit implementation                              | Wrap existing git utils behind host provider                              | Repo corruption/conflicts  | Transactional git ops + snapshot + conflict UI          |
+| Local SQLite + settings files                          | Different storage semantics across platforms              | Split metadata: cloud source of truth + local cache                             | Introduce workspace/project cloud schema and cache layer                  | Data divergence            | Versioned sync protocol + conflict resolution policies  |
+| `safeStorage` OS secret encryption                     | Not portable to web runtime                               | Centralized secret vault + device secure storage for tokens                     | Migrate secrets to scoped vault entries                                   | Secret exposure            | KMS encryption, short-lived tokens, RBAC + audit        |
+| `dyad://` protocol deep links                          | Different deep-link systems per platform                  | Unified auth/deeplink router abstraction                                        | Implement desktop protocol + web redirect + mobile deep links             | Auth loop bugs             | End-to-end deep-link integration tests                  |
+| Auto-update packaging model                            | Web/mobile release channels differ                        | Per-platform release orchestration                                              | Desktop keeps auto-update; web CI deploy; mobile app-store release tracks | Version skew               | API contract version checks + forced upgrade gates      |
+| Clipboard/screenshot/system dialogs                    | Limited browser/mobile APIs                               | Capability-based action model with platform fallbacks                           | Add `capabilities.system.*` gating and alternate UX                       | Missing features confusion | UI labels for unavailable actions + docs                |
+| Node PATH / environment probing                        | Not meaningful in web/mobile                              | Host-specific environment diagnostics                                           | Keep on desktop only; cloud diagnostics endpoints for remote runtime      | Support complexity         | Host-tagged diagnostics bundle                          |
+| Local preview proxy assumptions                        | Remote preview URLs and CORS/security differences         | Cloud preview gateway + signed access tokens                                    | Refactor preview proxy to support remote sources                          | Security headers misconfig | Security review + automated integration checks          |
+| Local-only backup/reset semantics                      | Cloud data is multi-tenant and persistent                 | Cloud snapshot/restore service                                                  | Replace destructive reset with scoped project reset endpoints             | Accidental data loss       | Confirmation gates + point-in-time restore              |
+| Existing e2e Electron-only test harness                | No coverage for web/mobile runtime paths                  | Multi-platform CI matrix and contract tests                                     | Add web playwright, mobile detox/appium flows, shared contract test suite | Test explosion             | Risk-based test pyramid + shared fixtures               |
+
+## API and Contract Evolution Plan
+
+### Contract Versions
+
+- `Host API v1`:
+  - project/file operations
+  - command execution
+  - stream channels
+  - git subset
+  - preview lifecycle
+- `Host API v2` (follow-up):
+  - advanced integration capabilities
+  - multi-user collaboration hooks
+
+### Compatibility Policy
+
+- Additive changes only within minor versions.
+- Breaking changes require version bump + dual support window.
+- Desktop app ships bridge adapters for at least two server versions.
+
+## Rollout and Migration Strategy
+
+### User Cohorts
+
+1. Internal team
+2. Existing pro desktop users (opt-in cloud mode)
+3. New web users
+4. Mobile beta users
+
+### Migration Controls
+
+- Feature flags by account and project.
+- Per-project host mode with explicit migration wizard.
+- Import/export dry-run and validation.
+- One-click rollback to prior stable mode during beta.
+
+## Testing Strategy
+
+### Unit
+
+- Host capability interface contract tests.
+- Operation policy tests (approval/denial paths).
+- Idempotency and retry behavior tests.
+- Schema/version compatibility tests.
+
+### Integration
+
+- Desktop local provider tests.
+- Cloud provider API workflow tests.
+- Git and command runtime execution tests.
+- Secret vault permission boundary tests.
+
+### E2E
+
+- Desktop local and desktop cloud parity scenarios.
+- Web end-to-end core workflows.
+- Mobile approval/chat/review flows.
+- Cross-device continuity scenarios.
+
+### Performance/Load
+
+- Runtime cold start and warm path benchmarks.
+- Stream throughput and latency under load.
+- Command queue saturation and backpressure behavior.
+
+### Security
+
+- Authn/authz penetration tests.
+- Tenant isolation red-team tests.
+- Command injection and path traversal tests.
+- Secret leakage and audit trail validation.
+
+## Risks & Mitigations
+
+| Risk                                       | Likelihood | Impact | Mitigation                                                           |
+| ------------------------------------------ | ---------- | ------ | -------------------------------------------------------------------- |
+| Cloud runtime complexity delays schedule   | High       | High   | Phase gates, strict MVP slice, dedicated platform team               |
+| Desktop regressions during refactor        | Medium     | High   | Adapter-first migration, dual-path fallbacks, heavy regression e2e   |
+| Security incident in remote execution      | Medium     | High   | Defense-in-depth sandboxing, policy engine, external security review |
+| Cost overrun for cloud execution           | High       | Medium | Quotas, metering, auto-hibernate, runtime class tiers                |
+| Poor mobile UX if desktop parity is forced | Medium     | Medium | Mobile-native scope (review/approval first), defer full IDE parity   |
+| Data migration failures                    | Medium     | High   | Dry-run validation, reversible migrations, snapshot restore          |
+| API version drift across clients           | Medium     | Medium | Shared contracts package, CI compatibility gates                     |
+| Adoption confusion (local vs cloud modes)  | Medium     | Medium | Clear host labels, onboarding decision guides, safe defaults         |
+
+## Success Metrics
+
+Product:
+
+- Web activation rate (project created within first session).
+- Cross-device retention (users active on 2+ platforms weekly).
+- Mobile approval completion rate.
+- Time-to-first-preview on web.
+
+Reliability:
+
+- Runtime startup p95.
+- Stream interruption rate.
+- Operation failure rate per capability.
+- Incident count/severity.
+
+Business:
+
+- Conversion uplift from web funnel.
+- Pro retention for users adopting cloud mode.
+- Infrastructure cost per active cloud project.
+
+## Team Topology and Ownership
+
+- Platform Core Team: host abstraction, shared packages, contract evolution.
+- Runtime Services Team: cloud execution, security, scaling.
+- Client Experience Team:
+  - Desktop stream
+  - Web stream
+  - Mobile stream
+- Integrations Team: git/supabase/vercel/mcp cross-host support.
+- QA/Release Team: matrix testing + staged rollout orchestration.
+
+## Delivery Timeline (Indicative)
+
+- Q1: Phases 0-2 (foundation + desktop host layer)
+- Q2: Phases 3-4 (cloud runtime + desktop cloud mode)
+- Q3: Phase 5 (web MVP) + phase 7 partial
+- Q4: Phase 6 (mobile MVP) + phases 8-10
+- Q1 next year: Phase 11 GA stabilization
+
+## Open Questions
+
+1. Should web/mobile be Pro-only at launch or include free tier with strict quotas?
+2. Do we want per-project region pinning for data residency in v1?
+3. Is mobile expected to support direct code editing beyond diff comments in v1?
+4. Which integrations are mandatory for web GA (GitHub, Supabase, Vercel, MCP)?
+5. What SLA/uptime commitments are required before public GA?
+6. Should cloud projects support collaborative multi-user editing in the first year, or remain single-user with sharing only?