M7: polish + E2E + docs (layout pass, theming, states, e2e driver, schema, setup.md, security)

gateway-plugin/protocol.py

@@ -12,7 +12,7 @@ Milestone M2: message.start/update/stop, reasoning (on message /
 message.stop), tool.start/progress/end, commentary.
 Milestone M3: channel.*, search, sync.
 Milestone M4: media.*.
-Milestone M5: notification, fcm.register, read.receipt.
+Milestone M5: notification, fcm.register, read.receipt, status.
 """
 
 import json
@@ -79,6 +79,10 @@ TYPE_MEDIA_PULL_END = "media.pull.end"
 # Push / notifications (M5)
 TYPE_NOTIFICATION = "notification"
 TYPE_FCM_REGISTER = "fcm.register"
+TYPE_READ_RECEIPT = "read.receipt"
+
+# Gateway health (M5)
+TYPE_STATUS = "status"
 
 # ---------------------------------------------------------------------------
 # Error codes (``error`` frame payload.code)
@@ -116,6 +120,14 @@ NOTIF_GENERIC = "generic"
 # it decides whether to also show an in-app banner).
 HIGH_PRIORITY_NOTIF_KINDS = frozenset({NOTIF_APPROVAL, NOTIF_CLARIFY, NOTIF_CRON})
 
+# ---------------------------------------------------------------------------
+# Gateway health states (``status`` frame payload.state)
+# ---------------------------------------------------------------------------
+
+STATUS_ONLINE = "online"
+STATUS_RESTARTING = "restarting"
+STATUS_DEGRADED = "degraded"
+
 
 # ---------------------------------------------------------------------------
 # Envelope
@@ -507,6 +519,25 @@ def fcm_register(
     return Frame(type=TYPE_FCM_REGISTER, payload=payload)
 
 
+def read_receipt(chat_id: str, message_id: str) -> Frame:
+    """Ack to the originating device: the agent received and started
+    processing the user's message (the app shows ✓✓ on the user bubble)."""
+    return Frame(
+        type=TYPE_READ_RECEIPT,
+        chat_id=chat_id,
+        payload={"message_id": message_id},
+    )
+
+
+# ---------------------------------------------------------------------------
+# Gateway health frame (M5)
+# ---------------------------------------------------------------------------
+
+def status(state: str) -> Frame:
+    """Gateway health state (``state`` is one of the ``STATUS_*`` constants)."""
+    return Frame(type=TYPE_STATUS, payload={"state": state})
+
+
 # ---------------------------------------------------------------------------
 # Media frames (M4)
 # ---------------------------------------------------------------------------