docs(internal): refresh ha_manage_addon ESPHome dashboard guidance (#1656)

* docs(internal): refresh ha_manage_addon ESPHome dashboard guidance

The ESPHome Device Builder dashboard was rewritten (aiohttp SPA, server 0.1.0b100). Its old surface — GET /edit?configuration=, and the /compile /validate /logs WebSocket paths with {"type": "spawn"} bodies — is gone and now returns the SPA shell. The ha_manage_addon docstring, the websocket/wait_for_close field descriptions, and the WS examples still described that old protocol, sending agents to dead ends.

Update them to the current API: HTTP GET /devices for the device list, and the WebSocket /ws command channel ({command, message_id, args}) with devices/get_config, devices/update_config, devices/logs, devices/validate, firmware/compile. Note the one-shot pattern (wait_for_close=False + message_limit) and that direct port= does not reach this dashboard. Also refresh the matching stale /compile example in read_only.py.

Verified against a live ESPHome 2026.5.3 dashboard: the old /logs WS path now returns HTTP 200 (SPA); /ws devices/get_config and devices/logs work. Docs-only (docstrings + one comment); no behavior change.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* docs(internal): tighten ESPHome WS guidance per review

Address pr-review-toolkit comment-analyzer findings: (1) separate wire-confirmed commands (devices/get_config, devices/logs) from frontend-only ones (devices/update_config, devices/validate, firmware/compile) so confidence is not overstated; (2) split the legacy-removal note precisely — GET /edit returns the SPA, the old WS paths reject the upgrade (HTTP 200) — instead of lumping both as "return the SPA". Also note body doubles as the WS initial message in its Field description.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: kingpanther13 <kingpanther13@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: kingpanther13

src/ha_mcp/read_only.py

@@ -93,8 +93,8 @@ def _addon_write(args: dict[str, Any]) -> str | None:
         return "array_patch modification"
     if args.get("websocket"):
         # A WebSocket session's initial message can command mutations
-        # (e.g. ESPHome /compile), so it is not statically classifiable
-        # as a read — fail closed.
+        # (e.g. an ESPHome firmware/compile or devices/update_config command),
+        # so it is not statically classifiable as a read — fail closed.
         return "WebSocket proxy session"
     method = str(args.get("method") or "GET").strip().upper()
     if method != "GET":

src/ha_mcp/tools/tools_addons.py

@@ -958,7 +958,7 @@ async def _call_addon_ws(
     Args:
         client: Home Assistant REST client
         slug: Add-on slug (e.g., "<prefix>_esphome")
-        path: WebSocket endpoint path (e.g., "/compile", "/validate")
+        path: WebSocket endpoint path (e.g., "/ws" for the ESPHome dashboard's command channel)
         body: Message to send after connecting (JSON-encoded if dict, raw if string)
         timeout: Max seconds to wait for messages (default 60)
         debug: Include diagnostic info
@@ -2622,7 +2622,7 @@ async def ha_manage_addon(
         body: Annotated[
             dict[str, Any] | str | None,
             Field(
-                description="Proxy mode only. Request body for POST/PUT/PATCH. Pass a JSON object or JSON string.",
+                description="Proxy mode only. Request body for POST/PUT/PATCH — or, with websocket=True, the initial WebSocket message. Pass a JSON object or JSON string.",
                 default=None,
             ),
         ] = None,
@@ -2658,17 +2658,20 @@ async def ha_manage_addon(
         websocket: Annotated[
             bool,
             Field(
-                description="Proxy mode only. Use WebSocket instead of HTTP. For streaming endpoints "
-                "(e.g., ESPHome /compile, /validate). Sends 'body' as initial message, "
-                "collects responses. Default: false.",
+                description="Proxy mode only. Use WebSocket instead of HTTP — for an add-on's "
+                "WebSocket API (e.g. the ESPHome dashboard's '/ws' command channel; see the "
+                "docstring's ESPHome section). Sends 'body' as the initial message, collects "
+                "responses. Default: false.",
                 default=False,
             ),
         ] = False,
         wait_for_close: Annotated[
             bool,
             Field(
-                description="Proxy mode only. WebSocket: True: wait for server to close (for compile/validate). "
-                "False: return after first response batch (for quick commands). Default: true.",
+                description="Proxy mode only. WebSocket: True: wait for the server to close the stream "
+                "(run-to-completion ops like an ESPHome compile/validate). False: return after the first "
+                "response batch — use for a one-shot command/response or a bounded log capture on a channel "
+                "that stays open (e.g. ESPHome '/ws'). Default: true.",
                 default=True,
             ),
         ] = True,
@@ -2839,6 +2842,29 @@ async def ha_manage_addon(
         share Home Assistant's container network (i.e. only the HAOS addon).
         Use ha_get_addon(slug="...") to discover available ports and endpoints.
 
+        **ESPHome Device Builder dashboard (current rewrite):** config and log
+        access is a WebSocket JSON-command API, NOT REST. The legacy endpoints
+        are gone — `GET /edit?configuration=` now returns the dashboard SPA, and
+        the old `/compile` `/validate` `/logs` WebSocket paths (which took
+        `{"type": "spawn", ...}` bodies) reject the upgrade (HTTP 200). Use
+        instead:
+        - HTTP `GET /devices` → JSON list of configured devices; each entry's
+          `configuration` field is the YAML filename to pass below.
+        - WebSocket `path="/ws"` with body
+          `{"command": "<cmd>", "message_id": "1", "args": {...}}`. The server
+          sends a `server_info` message first, then one reply per `message_id`.
+          Wire-confirmed commands: `devices/get_config` `{configuration}` → raw
+          YAML (in the reply's `result`); `devices/logs` (stream)
+          `{configuration, port: "OTA"}` → live device logs. Also exposed by the
+          dashboard frontend (command/arg names not wire-tested here):
+          `devices/update_config` `{configuration, content}` → save,
+          `devices/validate`, `firmware/compile`.
+        - The `/ws` channel stays open, so for a one-shot read or a bounded log
+          capture pass `wait_for_close=False` with `message_limit` (and
+          `message_offset` to skip the server_info / config-banner preamble).
+          Reach the dashboard through Ingress — omit `port`; direct `port=` does
+          not route to it.
+
         **Array-patch mode** (when path AND array_patch are provided):
         Atomic "GET array, mutate, POST array" workflow for addon APIs whose write
         contract is "send the whole resource collection back". Operations are applied
@@ -2847,8 +2873,8 @@ async def ha_manage_addon(
         full array. Designed for Node-RED /flows and similar endpoints.
 
         **Response shaping (proxy mode):**
-        - WebSocket streams can be noisy (ESPHome /validate often emits hundreds of
-          config-dump lines). By default, `summarize=True` collapses long runs of
+        - WebSocket streams can be noisy (e.g. the ESPHome dashboard's devices/logs
+          dumps the device's full config banner on connect). By default, `summarize=True` collapses long runs of
           non-signal messages into short elision markers; INFO/WARNING/ERROR/exit
           lines always pass through. Pagination via `message_offset` / `message_limit`
           works on the raw collected list before summarize runs.
@@ -2881,9 +2907,10 @@ async def ha_manage_addon(
         - Set boot mode: ha_manage_addon(slug="...", boot="manual")
         - Call HTTP API: ha_manage_addon(slug="...", path="/api/events")
         - Direct port: ha_manage_addon(slug="...", path="/flows", port=1880)
-        - WebSocket: ha_manage_addon(slug="...", path="/validate", port=6052, websocket=True, body={"type": "spawn", "configuration": "device.yaml"})
-        - Quick WS health check (50 msgs, raw): ha_manage_addon(slug="...", path="/logs", websocket=True, message_limit=50, summarize=False)
-        - Filter WS errors only: ha_manage_addon(slug="...", path="/validate", websocket=True, python_transform="response = [m for m in response if 'ERROR' in str(m) or 'WARN' in str(m)]")
+        - ESPHome list devices (HTTP): ha_manage_addon(slug="<prefix>_esphome", path="/devices")
+        - ESPHome read a device's YAML (WS one-shot): ha_manage_addon(slug="<prefix>_esphome", path="/ws", websocket=True, wait_for_close=False, message_limit=2, body={"command": "devices/get_config", "message_id": "1", "args": {"configuration": "device.yaml"}})
+        - ESPHome live logs (WS, bounded): ha_manage_addon(slug="<prefix>_esphome", path="/ws", websocket=True, wait_for_close=False, message_limit=60, body={"command": "devices/logs", "message_id": "1", "args": {"configuration": "device.yaml", "port": "OTA"}})
+        - Filter WS errors only: ha_manage_addon(slug="...", path="/ws", websocket=True, python_transform="response = [m for m in response if 'ERROR' in str(m) or 'WARN' in str(m)]")
         - HTTP subset: ha_manage_addon(slug="...", path="/flows", python_transform="response = [f['id'] for f in response]")
         - Array-patch (Node-RED, rename a node):
             ha_manage_addon(