diff --git a/docs/control-api.md b/docs/control-api.md
index 6458852f0..adca0dceb 100644
--- a/docs/control-api.md
+++ b/docs/control-api.md
@@ -5,9 +5,10 @@ read_when:
 ---
 # Control channel API (newline-delimited JSON)
 
-**Deprecated:** superseded by the WebSocket Gateway protocol (`clawdis gateway`, see `docs/architecture.md` and `docs/gateway.md`). Use only for legacy builds predating the Gateway rollout.
+**Deprecated (historical):** superseded by the WebSocket Gateway protocol (`clawdis gateway`, see `docs/architecture.md` and `docs/gateway.md`).
+Current builds use a WebSocket server on `ws://127.0.0.1:18789` and do **not** expose this TCP control channel.
 
-Endpoint: `127.0.0.1:18789` (TCP, localhost only). Clients reach it via SSH port forward in remote mode.
+Legacy endpoint (if present in an older build): `127.0.0.1:18789` (TCP, localhost only), typically reached via SSH port forward in remote mode.
 
 ## Frame format
 Each line is a JSON object. Two shapes exist:
@@ -45,4 +46,4 @@ Each line is a JSON object. Two shapes exist:
 4) For user toggles, send `set-heartbeats` and await response.
 
 ## Backward compatibility
-- If the control port is unavailable (older gateway), the client may fall back to the legacy CLI path, but the intended path is to rely solely on this API.
+- If the control channel is unavailable: that’s expected on modern builds. Use the Gateway WS protocol instead.
diff --git a/docs/health.md b/docs/health.md
index b155decc3..d57a3bf6e 100644
--- a/docs/health.md
+++ b/docs/health.md
@@ -16,7 +16,7 @@ Short guide to verify the WhatsApp Web / Baileys stack without guessing.
 
 ## Deep diagnostics
 - Creds on disk: `ls -l ~/.clawdis/credentials/creds.json` (mtime should be recent).
-- Session store: `ls -l ~/.clawdis/sessions.json` (path can be overridden in config). Count and recent recipients are surfaced via `status`.
+- Session store: `ls -l ~/.clawdis/sessions/sessions.json` (legacy: `~/.clawdis/sessions.json`; path can be overridden in config). Count and recent recipients are surfaced via `status`.
 - Relink flow: `clawdis logout && clawdis login --verbose` when status codes 409–515 or `loggedOut` appear in logs.
 
 ## When something fails