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