docs: document hosted cloud worker architecture and connect model

AGENTS.md

@@ -9,14 +9,35 @@ OpenWork is a practical control surface for agentic work:
 * Run local and remote agent workflows from one place.
 * Use OpenCode capabilities directly through OpenWork.
 * Compose desktop app, server, and messaging connectors without lock-in.
+* Treat the OpenWork app as a client of the OpenWork server API surface.
+* Connect to hosted workers through a simple user flow: `Add a worker` -> `Connect remote`.
 
 ## Core Philosophy
 
 * **Local-first, cloud-ready**: OpenWork runs on your machine in one click and can connect to cloud workflows when needed.
+* **Server-consumption first**: the app should consume OpenWork server surfaces (self-hosted or hosted), not invent parallel behavior.
 * **Composable**: use the desktop app, WhatsApp/Slack/Telegram connectors, or server mode based on the task.
 * **Ejectable**: OpenWork is powered by OpenCode, so anything OpenCode can do is available in OpenWork, even before a dedicated UI exists.
 * **Sharing is caring**: start solo, then share quickly; one CLI or desktop command can spin up an instantly shareable instance.
 
+## Core Runtime Model (Updated)
+
+OpenWork now has three production-grade ways to run the same product surface:
+
+1. **Desktop-hosted app/server**
+   - OpenWork app runs locally and can host server functionality on-device.
+2. **CLI-hosted server (openwork-orchestrator)**
+   - OpenWork server surfaces can be provided by the orchestrator/CLI on a trusted machine.
+3. **Hosted OpenWork Cloud server**
+   - OpenWork-hosted infrastructure provisions workers and exposes the same remote-connect semantics.
+
+User mental model:
+
+* The app is the UI and control layer.
+* The server is the execution/control API layer.
+* A worker is a remote runtime destination.
+* Connecting to a worker happens through `Add worker` -> `Connect remote` using URL + token (or deep link).
+
 Read INFRASTRUCTURE.md
 
 ## Why OpenWork Exists

ARCHITECTURE.md

@@ -74,7 +74,16 @@ These are all opencode primitives you can read the docs to find out exactly how
 
 ## Core Architecture
 
-OpenWork is a Tauri application with two runtime modes:
+OpenWork is a client experience that consumes OpenWork server surfaces.
+
+Historically, users reached OpenWork server capabilities in two ways:
+
+- a running desktop OpenWork app acting as host
+- a running `openwork-orchestrator` (CLI host)
+
+Now there is a third, first-class path: hosted OpenWork Cloud workers.
+
+OpenWork therefore has three runtime connection modes:
 
 ### Mode A - Host (Desktop/Server)
 
@@ -88,7 +97,27 @@ OpenWork is a Tauri application with two runtime modes:
 - It connects to an already-running OpenCode server hosted by a trusted device.
 - Pairing uses a QR code / one-time token and a secure transport (LAN or tunneled).
 
-This split makes mobile "first-class" without requiring the full engine to run on-device.
+### Mode C - Hosted OpenWork Cloud
+
+- User signs in to hosted OpenWork web/app surfaces.
+- User launches a cloud worker from hosted control plane.
+- OpenWork returns remote connect credentials (`/w/ws_*` URL + access token).
+- User connects from OpenWork app using `Add a worker` -> `Connect remote`.
+
+This model keeps the user experience consistent across self-hosted and hosted paths while preserving OpenCode parity.
+
+## Cloud Worker Connect Flow (Canonical)
+
+1. Authenticate in OpenWork Cloud control surface.
+2. Launch worker (with checkout/paywall when needed).
+3. Wait for provisioning and health.
+4. Generate/retrieve connect credentials.
+5. Connect in OpenWork app via deep link or manual URL + token.
+
+Technical note:
+
+- Default connect URL should be workspace-scoped (`/w/ws_*`) when available.
+- Technical diagnostics (host URL, worker ID, raw logs) should be progressive disclosure, not default UI.
 
 ## Web Parity + Filesystem Actions
 

INFRASTRUCTURE.md

@@ -27,6 +27,7 @@ OpenWork is an experience layer. `opencode` is the engine. This document defines
 5.  Local-first, graceful degradation
 
 * Default to local execution.
+* Hosted cloud is a first-class option, not a separate product.
 * If a sidecar is missing or offline, the UI falls back to read-only or explicit user guidance.
 
 6.  Portable configuration
@@ -73,6 +74,16 @@ But what you can do is:
 * Runs standalone via `openwork-server` CLI.
 * Provides filesystem-backed config surfaces (skills, plugins, MCP, commands).
 * Sidecar lifecycle is described in `packages/app/pr/openwork-server.md`.
+* Can also be consumed as a hosted OpenWork Cloud control surface for remote worker lifecycle.
+
+### OpenWork Cloud Control Plane
+
+* Hosted deployment of OpenWork server capabilities for worker provisioning and remote connect.
+* Must preserve the same user-level contract as self-hosted paths:
+  - launch worker
+  - get connect credentials (URL + token)
+  - connect via `Add worker` -> `Connect remote`
+* Should not require a separate mental model for users moving between local and hosted modes.
 
 ### OpenCode Router
 
@@ -82,7 +93,7 @@ But what you can do is:
 ## Non-goals
 
 * Replacing OpenCode primitives with custom abstractions.
-* Building multi-tenant or cloud-managed infrastructure.
+* Forcing cloud-only lock-in (self-hosted desktop/CLI paths must remain valid).
 
 ## References
 

PRINCIPLES.md

@@ -14,10 +14,13 @@
 ## Principles
 
 - **Parity**: UI actions map to OpenCode server APIs.
+- **Server-consumption first**: OpenWork app consumes OpenWork server surfaces (desktop-hosted, orchestrator-hosted, or cloud-hosted) instead of inventing parallel behavior.
 - **Transparency**: plans, steps, tool calls, permissions are visible.
 - **Least privilege**: only user-authorized folders + explicit approvals.
 - **Prompt is the workflow**: product logic lives in prompts, rules, and skills.
 - **Graceful degradation**: if access is missing, guide the user.
+- **Progressive disclosure by default**: non-technical users should see clear primary actions first; IDs/URLs/diagnostics stay behind explicit "manual" or "advanced" sections.
+- **Cloud + self-hosted consistency**: the same connect mental model (`Add worker` -> `Connect remote`) should work regardless of where the server runs.
 
 ## Security & Privacy
 

PRODUCT.md

@@ -121,6 +121,15 @@ use the design from ./design.ts that is your core reference for building the ent
 - provider/model setup
 - first-run "hello world" task
 
+### Cloud Worker Onboarding (Current)
+
+- Sign in (or sign up) on OpenWork cloud control surface.
+- Launch worker with a human-readable name.
+- If needed, complete checkout and return.
+- Select launched worker from list/detail shell.
+- Connect from OpenWork app via `Add a worker` -> `Connect remote`.
+- Prefer one-click deep link when available; always provide manual URL + token fallback.
+
 ### Task Execution
 
 - create task
@@ -245,3 +254,12 @@ use the design from ./design.ts that is your core reference for building the ent
 - separate profiles
 - separate allowed folders
 - separate providers/keys
+
+### 14. Hosted Cloud Worker Connect Flow (Current)
+
+1. User opens OpenWork cloud control page and authenticates.
+2. User launches a worker (with optional checkout).
+3. UI polls until worker is healthy.
+4. UI resolves workspace-scoped connect URL (`/w/ws_*`) and access token.
+5. User clicks `Open in OpenWork` or copies manual credentials.
+6. In OpenWork app, user uses `Add a worker` -> `Connect remote` and starts working.

VISION.md

@@ -4,11 +4,18 @@
 
 **How:** We give AI agents the tools your team already uses and let them learn from your behavior. The more you use OpenWork, the more connected your tools become, the more knowledge accumulates, and the bigger the chunks of work you can automate.
 
-**Today:** OpenWork is the simplest interface to `opencode`. Double-click, pick a folder, and you get three things instantly:
+**Today:** OpenWork is the simplest interface to `opencode` and OpenWork server surfaces. Double-click, pick a folder, and you get three things instantly:
 
 1. **Zero-friction setup** — your existing opencode configuration just works, no migration needed
 2. **Chat access** — WhatsApp and Telegram ready to go (one token, done)
-3. **Cloud-ready** — every app doubles as a client; deploy to the cloud and access from anywhere
+3. **Cloud-ready** — every app doubles as a client; connect to hosted workers from anywhere
+
+Current cloud mental model:
+
+- OpenWork app is the experience layer.
+- OpenWork server is the control/API layer.
+- OpenWork worker is the runtime destination.
+- Connect flow is intentionally simple: `Add a worker` -> `Connect remote`.
 
 OpenWork helps users ship agentic workflows to their team. It works on top of opencode (opencode.ai) an agentic coding platform that exposes apis and sdks. We care about maximally using the opencode primitives. And build the thinest possible layer - always favoring opencode apis over custom built ones.