diff --git a/docs/gateway/clients.md b/docs/gateway/clients.md
index 9933e1991fae..255ddaa283da 100644
--- a/docs/gateway/clients.md
+++ b/docs/gateway/clients.md
@@ -140,9 +140,13 @@ System-agent setup is administrative. Request `operator.admin` when pairing the
 device; every `openclaw.chat` call in this flow, including setup, polling,
 cancellation, and reset, requires that scope.
 
-Advertise `GATEWAY_CLIENT_CAPS.SYSTEM_AGENT_QR_CODE` only when the client can
-render a QR image. A capable `openclaw.chat` session can then receive a QR
-`step` through the same wizard-step contract used for other setup controls:
+Advertise `GATEWAY_CLIENT_CAPS.SYSTEM_AGENT_QR_CODE` only when the client
+implements the complete passive QR lifecycle: render and expire the image,
+poll through `wizardSettling`, resume the same poll after a same-owner
+reconnect, handle invalidation and reset, and scrub every QR reference after
+completion, expiry, cancellation, or disconnect. Rendering alone is not
+sufficient. A capable `openclaw.chat` session can then receive a QR `step`
+through the same wizard-step contract used for other setup controls:
 
 ```json
 {
diff --git a/packages/gateway-protocol/src/client-info.ts b/packages/gateway-protocol/src/client-info.ts
index 099eb6b60e7f..d98528aafe8c 100644
--- a/packages/gateway-protocol/src/client-info.ts
+++ b/packages/gateway-protocol/src/client-info.ts
@@ -86,6 +86,7 @@ export const GATEWAY_CLIENT_CAPS = {
   RUN_TOOL_BINDINGS: "run-tool-bindings",
   SESSION_SCOPED_EVENTS: "session-scoped-events",
   PLUGIN_APPROVALS: "plugin-approvals",
+  /** Renders and securely retires passive QR steps, including polling and reconnect recovery. */
   SYSTEM_AGENT_QR_CODE: "system-agent-qr-code",
   TASK_SUGGESTIONS: "task-suggestions",
   TERMINAL_OFFSET_SEQ: "terminal-offset-seq",