From 06764e092419ec0d0fb4431d3432524ac10ef4f3 Mon Sep 17 00:00:00 2001
From: Rod Boev <rod.boev@gmail.com>
Date: Sat, 4 Jul 2026 13:37:39 -0400
Subject: [PATCH] docs(#5269): document gateway approval runs API opt-in

---
 docs/advanced-chat-setup.md                   | 12 ++++++++++
 docs/docker.md                                | 14 ++++++++++++
 tests/test_issue5269_gateway_approval_docs.py | 22 +++++++++++++++++++
 3 files changed, 48 insertions(+)
 create mode 100644 tests/test_issue5269_gateway_approval_docs.py

diff --git a/docs/advanced-chat-setup.md b/docs/advanced-chat-setup.md
index f0c65077..1d70c4ad 100644
--- a/docs/advanced-chat-setup.md
+++ b/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
diff --git a/docs/docker.md b/docs/docker.md
index b5c7d45a..e351507e 100644
--- a/docs/docker.md
+++ b/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),
diff --git a/tests/test_issue5269_gateway_approval_docs.py b/tests/test_issue5269_gateway_approval_docs.py
new file mode 100644
index 00000000..9277017e
--- /dev/null
+++ b/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