docs: clarify gateway remote node flow

docs/gateway/doctor.md

@@ -55,6 +55,7 @@ cat ~/.clawdbot/clawdbot.json
 ```
 
 ## What it does (summary)
+- Optional pre-flight update for git installs (interactive only).
 - Health check + restart prompt.
 - Skills status summary (eligible/missing/blocked).
 - Legacy config migration and normalization.
@@ -67,16 +68,21 @@ cat ~/.clawdbot/clawdbot.json
 - Sandbox image repair when sandboxing is enabled.
 - Legacy service migration and extra gateway detection.
 - Gateway runtime checks (service installed but not running; cached launchd label).
+- Provider status warnings (probed from the running gateway).
 - Supervisor config audit (launchd/systemd/schtasks) with optional repair.
 - Gateway runtime best-practice checks (Node vs Bun, version-manager paths).
 - Gateway port collision diagnostics (default `18789`).
 - Security warnings for open DM policies.
-- Gateway auth warnings when no `gateway.auth.token` is set (offers token generation).
+- Gateway auth warnings when no `gateway.auth.token` is set (local mode; offers token generation).
 - systemd linger check on Linux.
 - Writes updated config + wizard metadata.
 
 ## Detailed behavior and rationale
 
+### 0) Optional update (git installs)
+If this is a git checkout and doctor is running interactively, it offers to
+update (fetch/rebase/build) before running doctor.
+
 ### 1) Legacy config file migration
 If `~/.clawdis/clawdis.json` exists and `~/.clawdbot/clawdbot.json` does not,
 doctor migrates the file and normalizes old paths/image names. This prevents
@@ -165,39 +171,47 @@ Doctor also reports auth profiles that are temporarily unusable due to:
 - short cooldowns (rate limits/timeouts/auth failures)
 - longer disables (billing/credit failures)
 
-### 6) Sandbox image repair
+### 6) Hooks model validation
+If `hooks.gmail.model` is set, doctor validates the model reference against the
+catalog and allowlist and warns when it won’t resolve or is disallowed.
+
+### 7) Sandbox image repair
 When sandboxing is enabled, doctor checks Docker images and offers to build or
 switch to legacy names if the current image is missing.
 
-### 7) Gateway service migrations and cleanup hints
+### 8) Gateway service migrations and cleanup hints
 Doctor detects legacy Clawdis gateway services (launchd/systemd/schtasks) and
 offers to remove them and install the Clawdbot service using the current gateway
 port. It can also scan for extra gateway-like services and print cleanup hints.
 Profile-named Clawdbot gateway services are considered first-class and are not
 flagged as "extra."
 
-### 8) Security warnings
+### 9) Security warnings
 Doctor emits warnings when a provider is open to DMs without an allowlist, or
 when a policy is configured in a dangerous way.
 
-### 9) systemd linger (Linux)
+### 10) systemd linger (Linux)
 If running as a systemd user service, doctor ensures lingering is enabled so the
 gateway stays alive after logout.
 
-### 10) Skills status
+### 11) Skills status
 Doctor prints a quick summary of eligible/missing/blocked skills for the current
 workspace.
 
-### 11) Gateway auth checks (local token)
+### 12) Gateway auth checks (local token)
 Doctor warns when `gateway.auth` is missing on a local gateway and offers to
 generate a token. Use `clawdbot doctor --generate-gateway-token` to force token
 creation in automation.
 
-### 12) Gateway health check + restart
+### 13) Gateway health check + restart
 Doctor runs a health check and offers to restart the gateway when it looks
 unhealthy.
 
-### 13) Supervisor config audit + repair
+### 14) Provider status warnings
+If the gateway is healthy, doctor runs a provider status probe and reports
+warnings with suggested fixes.
+
+### 15) Supervisor config audit + repair
 Doctor checks the installed supervisor config (launchd/systemd/schtasks) for
 missing or outdated defaults (e.g., systemd network-online dependencies and
 restart delay). When it finds a mismatch, it recommends an update and can
@@ -210,24 +224,24 @@ Notes:
 - `clawdbot doctor --repair --force` overwrites custom supervisor configs.
 - You can always force a full rewrite via `clawdbot daemon install --force`.
 
-### 14) Gateway runtime + port diagnostics
+### 16) Gateway runtime + port diagnostics
 Doctor inspects the daemon runtime (PID, last exit status) and warns when the
 service is installed but not actually running. It also checks for port collisions
 on the gateway port (default `18789`) and reports likely causes (gateway already
 running, SSH tunnel).
 
-### 15) Gateway runtime best practices
+### 17) Gateway runtime best practices
 Doctor warns when the gateway service runs on Bun or a version-managed Node path
 (`nvm`, `fnm`, `volta`, `asdf`, etc.). WhatsApp + Telegram providers require Node,
 and version-manager paths can break after upgrades because the daemon does not
 load your shell init. Doctor offers to migrate to a system Node install when
 available (Homebrew/apt/choco).
 
-### 16) Config write + wizard metadata
+### 18) Config write + wizard metadata
 Doctor persists any config changes and stamps wizard metadata to record the
 doctor run.
 
-### 17) Workspace tips (backup + memory system)
+### 19) Workspace tips (backup + memory system)
 Doctor suggests a workspace memory system when missing and prints a backup tip
 if the workspace is not already under git.
 

docs/gateway/remote.md

@@ -15,6 +15,20 @@ This repo supports “remote over SSH” by keeping a single Gateway (the master
 - The Gateway WebSocket binds to **loopback** on your configured port (defaults to 18789).
 - For remote use, you forward that loopback port over SSH (or use a tailnet/VPN and tunnel less).
 
+## Command flow (what runs where)
+
+One gateway daemon owns state + providers. Nodes are peripherals.
+
+Flow example (Telegram → node):
+- Telegram message arrives at the **Gateway**.
+- Gateway runs the **agent** and decides whether to call a node tool.
+- Gateway calls the **node** over the Bridge (`node.*` RPC).
+- Node returns the result; Gateway replies back out to Telegram.
+
+Notes:
+- **Nodes do not run the gateway daemon.** Only one gateway should run per host.
+- macOS app “node mode” is just a node client over the Bridge.
+
 ## SSH tunnel (CLI + tools)
 
 Create a local tunnel to the remote Gateway WS:

docs/nodes/index.md

@@ -12,6 +12,10 @@ A **node** is a companion device (iOS/Android today) that connects to the Gatewa
 
 macOS can also run in **node mode**: the menubar app connects to the Gateway’s bridge and exposes its local canvas/camera commands as a node (so `clawdbot nodes …` works against this Mac).
 
+Notes:
+- Nodes are **peripherals**, not gateways. They don’t run the gateway daemon.
+- Telegram/WhatsApp/etc. messages land on the **gateway**, not on nodes.
+
 ## Pairing + status
 
 Pairing is gateway-owned and approval-based. See [Gateway pairing](/gateway/pairing) for the full flow.

docs/start/faq.md

@@ -219,6 +219,22 @@ The Gateway watches the config and supports hot‑reload:
 - `gateway.reload.mode: "hybrid"` (default): hot‑apply safe changes, restart for critical ones
 - `hot`, `restart`, `off` are also supported
 
+## Remote gateways + nodes
+
+### How do commands propagate between Telegram, the gateway, and nodes?
+
+Telegram messages are handled by the **gateway**. The gateway runs the agent and
+only then calls nodes over the **Bridge** when a node tool is needed:
+
+Telegram → Gateway → Agent → `node.*` → Node → Gateway → Telegram
+
+Nodes don’t see inbound provider traffic; they only receive bridge RPC calls.
+
+### Do nodes run a gateway daemon?
+
+No. Only **one gateway** should run per host. Nodes are peripherals that connect
+to the gateway (iOS/Android nodes, or macOS “node mode” in the menubar app).
+
 A full restart is required for `gateway`, `bridge`, `discovery`, and `canvasHost` changes.
 
 ### Is there an API / RPC way to apply config?