docs: unify ws protocol + platform guides

docs/gateway/bridge-protocol.md

@@ -1,18 +1,17 @@
 ---
-summary: "Bridge protocol (nodes): TCP JSONL, pairing, scoped RPC"
+summary: "Bridge protocol (legacy nodes): TCP JSONL, pairing, scoped RPC"
 read_when:
   - Building or debugging node clients (iOS/Android/macOS node mode)
   - Investigating pairing or bridge auth failures
   - Auditing the node surface exposed by the gateway
 ---
 
-# Bridge protocol (Node transport)
+# Bridge protocol (legacy node transport)
 
-The Bridge protocol is a **narrow, authenticated** transport for nodes
-(iOS/Android/macOS node mode). It keeps the Gateway WS control plane loopback‑only
-and exposes only a scoped set of methods for nodes.
+The Bridge protocol is a **legacy** node transport (TCP JSONL). New node clients
+should use the unified Gateway WebSocket protocol instead.
 
-If you are building an operator client (CLI, web UI, automations), use the
+If you are building an operator or node client, use the
 [Gateway protocol](/gateway/protocol).
 
 ## Why we have both

docs/gateway/protocol.md

@@ -8,12 +8,10 @@ read_when:
 
 # Gateway protocol (WebSocket)
 
-The Gateway WS protocol is the **full control plane** for Clawdbot. It is
-loopback-only by default and is intended for local clients (CLI, web UI,
-automations).
-
-If you are building a **node client** (iOS/Android/macOS node mode), use the
-[Bridge protocol](/gateway/bridge-protocol) instead.
+The Gateway WS protocol is the **single control plane + node transport** for
+Clawdbot. All clients (CLI, web UI, macOS app, iOS/Android nodes, headless
+nodes) connect over WebSocket and declare their **role** + **scope** at
+handshake time.
 
 ## Transport
 
@@ -38,7 +36,11 @@ Client → Gateway:
       "platform": "macos",
       "mode": "operator"
     },
+    "role": "operator",
+    "scopes": ["operator.read", "operator.write"],
     "caps": [],
+    "commands": [],
+    "permissions": {},
     "auth": { "token": "…" },
     "locale": "en-US",
     "userAgent": "clawdbot-cli/1.2.3"
@@ -57,6 +59,40 @@ Gateway → Client:
 }
 ```
 
+### Node example
+
+```json
+{
+  "type": "req",
+  "id": "…",
+  "method": "connect",
+  "params": {
+    "minProtocol": 3,
+    "maxProtocol": 3,
+    "client": {
+      "id": "ios-node",
+      "version": "1.2.3",
+      "platform": "ios",
+      "mode": "node"
+    },
+    "role": "node",
+    "scopes": [],
+    "caps": ["camera", "canvas", "screen", "location", "voice"],
+    "commands": ["camera.snap", "canvas.navigate", "screen.record", "location.get"],
+    "permissions": { "camera.capture": true, "screen.record": false },
+    "auth": { "token": "…" },
+    "locale": "en-US",
+    "userAgent": "clawdbot-ios/1.2.3",
+    "device": {
+      "id": "device_fingerprint",
+      "publicKey": "…",
+      "signature": "…",
+      "signedAt": 1737264000000
+    }
+  }
+}
+```
+
 ## Framing
 
 - **Request**: `{type:"req", id, method, params}`  
@@ -65,6 +101,28 @@ Gateway → Client:
 
 Side-effecting methods require **idempotency keys** (see schema).
 
+## Roles + scopes
+
+### Roles
+- `operator` = control plane client (CLI/UI/automation).
+- `node` = capability host (camera/screen/canvas/system.run).
+
+### Scopes (operator)
+Common scopes:
+- `operator.read`
+- `operator.write`
+- `operator.admin`
+- `operator.approvals`
+- `operator.pairing`
+
+### Caps/commands/permissions (node)
+Nodes declare capability claims at connect time:
+- `caps`: high-level capability categories.
+- `commands`: command allowlist for invoke.
+- `permissions`: granular toggles (e.g. `screen.record`, `camera.capture`).
+
+The Gateway treats these as **claims** and enforces server-side allowlists.
+
 ## Versioning
 
 - `PROTOCOL_VERSION` lives in `src/gateway/protocol/schema.ts`.
@@ -79,8 +137,22 @@ Side-effecting methods require **idempotency keys** (see schema).
 - If `CLAWDBOT_GATEWAY_TOKEN` (or `--token`) is set, `connect.params.auth.token`
   must match or the socket is closed.
 
+## Device identity + pairing
+
+- Nodes should include a stable device identity (`device.id`) derived from a
+  keypair fingerprint.
+- Gateways issue tokens per device + role.
+- Pairing approvals are required for new device IDs unless local auto-approval
+  is enabled.
+
+## TLS + pinning
+
+- TLS is supported for WS connections.
+- Clients may optionally pin the gateway cert fingerprint (see `gateway.tls`
+  config and client TLS settings).
+
 ## Scope
 
-This protocol exposes the **full gateway API** (status, channels, models,
-chat, agent, sessions, nodes, etc.). The exact surface is defined by the
+This protocol exposes the **full gateway API** (status, channels, models, chat,
+agent, sessions, nodes, approvals, etc.). The exact surface is defined by the
 TypeBox schemas in `src/gateway/protocol/schema.ts`.