docs: document that device_id in discover triggers device wake-up

Added a Discovery API section to initiation-protocol.md explaining
that device_id must be included to wake the target device. Updated
SDK docstrings in TypeScript, Python, and Rust to clarify that
omitting device_id skips the FCM/SSE notification.

Author: shimondoodkin

docs/initiation-protocol.md

@@ -26,6 +26,24 @@ Phone/CLI                 Discovery API              WS Server             Redis
   │                            │                        │                    │
 ```
 
+## Discovery API
+
+`POST /api/discover` — returns a worker WebSocket URL for connecting.
+
+**Request body:**
+```json
+{ "device_id": "a1b2c3d4e5f67890..." }
+```
+
+**Response:**
+```json
+{ "wsUrl": "wss://worker0.screenmcp.com" }
+```
+
+When `device_id` is included, the server sends a wake-up notification (FCM push or SSE event) to the target device, telling it to connect to the worker. **If `device_id` is omitted, the server returns a worker URL but does NOT wake the device** — the caller must ensure the device is already connected.
+
+Controllers should always pass `device_id` to ensure the target device is online and routed to the same worker.
+
 ## Message Format
 
 All messages are JSON over WebSocket.

sdk/python/src/screenmcp/client.py

@@ -115,7 +115,10 @@ async def connect(self, device_id: str = "") -> "DeviceConnection":
         ----------
         device_id:
             Target device UUID. If empty the server picks the first device
-            registered to the authenticated user.
+            registered to the authenticated user, but does **not** send a
+            wake-up notification — the device must already be connected.
+            Pass a device_id to ensure the server wakes the target device
+            via FCM/SSE.
 
         Returns
         -------

sdk/rust/src/client.rs

@@ -113,6 +113,11 @@ impl ScreenMCPClient {
 
     /// Discover a worker for the given device, open a WebSocket connection,
     /// authenticate, and return a ready-to-use [`DeviceConnection`].
+    ///
+    /// The `device_id` is sent to the server which triggers a wake-up
+    /// notification (FCM/SSE) to the target device. If you pass an empty
+    /// string, the server returns a worker URL but does **not** wake the
+    /// device — it must already be connected.
     pub async fn connect(&self, device_id: &str) -> Result<DeviceConnection> {
         let ws_url = self.discover(device_id).await?;
         let mut conn = DeviceConnection::new(

sdk/typescript/src/client.ts

@@ -88,7 +88,9 @@ export class ScreenMCPClient {
    * Returns a {@link DeviceConnection} that provides all command methods.
    *
    * @param options - Optional connect options. If `deviceId` is omitted the
-   *   server picks the first available device.
+   *   server picks the first available device but does NOT send a wake-up
+   *   notification — the device must already be connected. Pass `deviceId`
+   *   to ensure the server wakes the target device via FCM/SSE.
    */
   async connect(options?: ConnectOptions): Promise<DeviceConnection> {
     const deviceId = options?.deviceId;