docs: clarify mac gateway launch behavior

docs/platforms/mac/bundled-gateway.md

@@ -9,8 +9,9 @@ read_when:
 # Gateway on macOS (external launchd)
 
 Clawdbot.app no longer bundles Node/Bun or the Gateway runtime. The macOS app
-expects an **external** `clawdbot` CLI install and manages a per‑user launchd
-service to keep the Gateway running.
+expects an **external** `clawdbot` CLI install, does not spawn the Gateway as a
+child process, and manages a per‑user launchd service to keep the Gateway
+running (or attaches to an existing local Gateway if one is already running).
 
 ## Install the CLI (required for local mode)
 
@@ -38,6 +39,8 @@ Manager:
 Behavior:
 - “Clawdbot Active” enables/disables the LaunchAgent.
 - App quit does **not** stop the gateway (launchd keeps it alive).
+- If a Gateway is already running on the configured port, the app attaches to
+  it instead of starting a new one.
 
 Logging:
 - launchd stdout/err: `/tmp/clawdbot/clawdbot-gateway.log`

docs/platforms/mac/child-process.md

@@ -5,9 +5,11 @@ read_when:
 ---
 # Gateway lifecycle on macOS
 
-The macOS app **manages the Gateway via launchd** by default. The launchd job
-uses the external `clawdbot` CLI (no embedded runtime). This gives you reliable
-auto‑start at login and restart on crashes.
+The macOS app **manages the Gateway via launchd** by default and does not spawn
+the Gateway as a child process. It first tries to attach to an already‑running
+Gateway on the configured port; if none is reachable, it enables the launchd
+service via the external `clawdbot` CLI (no embedded runtime). This gives you
+reliable auto‑start at login and restart on crashes.
 
 Child‑process mode (Gateway spawned directly by the app) is **not in use** today.
 If you need tighter coupling to the UI, run the Gateway manually in a terminal.