docs(#5269): document gateway approval runs API opt-in

docs/advanced-chat-setup.md

@@ -63,6 +63,18 @@ HERMES_WEBUI_GATEWAY_API_KEY=... \
 ./ctl.sh restart
 ```
 
+Gateway-backed approval prompts need one more explicit opt-in because they use the Gateway runs API path:
+
+```bash
+HERMES_WEBUI_CHAT_BACKEND=gateway \
+HERMES_WEBUI_GATEWAY_BASE_URL=http://127.0.0.1:8642 \
+HERMES_WEBUI_GATEWAY_API_KEY=... \
+HERMES_WEBUI_GATEWAY_USE_RUNS_API=true \
+./ctl.sh restart
+```
+
+Use this when the connected gateway advertises approval support and you want tool approval cards to appear in WebUI. Without `HERMES_WEBUI_GATEWAY_USE_RUNS_API=true`, gateway chat stays on the legacy chat-completions transport and approval-capable commands can remain pending in the agent without a WebUI approval card.
+
 `HERMES_WEBUI_CHAT_BACKEND` is intentionally strict: only `gateway`,
 `api_server`, or `api-server` enable the bridge. Generic truthy values such as
 `1` or `true` are ignored so existing deployments do not change execution

docs/docker.md

@@ -185,6 +185,20 @@ services:
       # HERMES_WEBUI_GATEWAY_BASE_URL=http://hermes-agent:8642 also works.
 ```
 
+If WebUI browser chat is routed through that gateway and you expect approval prompts for guarded tools, set the gateway chat backend and opt into the runs API path in the **WebUI service**:
+
+```yaml
+services:
+  hermes-webui:
+    environment:
+      - HERMES_WEBUI_CHAT_BACKEND=gateway
+      - HERMES_WEBUI_GATEWAY_BASE_URL=http://hermes-agent:8642
+      - HERMES_WEBUI_GATEWAY_USE_RUNS_API=true
+      # HERMES_WEBUI_GATEWAY_API_KEY=... when the gateway requires API auth.
+```
+
+`HERMES_WEBUI_GATEWAY_USE_RUNS_API=true` is required for gateway approval cards because approval-capable gateway runs emit approval requests on the runs API transport. Leaving it unset keeps browser chat on the legacy chat-completions path.
+
 Do not copy only `API_SERVER_ENABLED=true` / `API_SERVER_HOST=0.0.0.0` into the
 agent service as a standalone fix. If you intentionally enable the agent API
 server, the agent also requires a real `API_SERVER_KEY` (at least 8 characters),

tests/test_issue5269_gateway_approval_docs.py

@@ -0,0 +1,22 @@
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+ADVANCED = (ROOT / "docs" / "advanced-chat-setup.md").read_text(encoding="utf-8")
+DOCKER = (ROOT / "docs" / "docker.md").read_text(encoding="utf-8")
+
+
+def test_advanced_chat_docs_name_gateway_approval_runs_api_opt_in():
+    assert "HERMES_WEBUI_CHAT_BACKEND=gateway" in ADVANCED
+    assert "HERMES_WEBUI_GATEWAY_USE_RUNS_API=true" in ADVANCED
+    assert "approval prompts" in ADVANCED
+    assert "approval card" in ADVANCED
+    assert "legacy chat-completions transport" in ADVANCED
+
+
+def test_docker_docs_name_webui_service_runs_api_opt_in_for_approval_cards():
+    assert "HERMES_WEBUI_CHAT_BACKEND=gateway" in DOCKER
+    assert "HERMES_WEBUI_GATEWAY_BASE_URL=http://hermes-agent:8642" in DOCKER
+    assert "HERMES_WEBUI_GATEWAY_USE_RUNS_API=true" in DOCKER
+    assert "approval cards" in DOCKER
+    assert "WebUI service" in DOCKER