What Problem This Solves

Three independent third-party clients (ClawX, openclaw-studio, PinchChat) reverse-engineered the Gateway protocol and embedder lifecycle from source because the contracts they needed were undocumented. With @openclaw/gateway-protocol (#111664) and @openclaw/gateway-client (#111707) shipping to npm at the next train, this adds the docs that make those packages usable without reading our internals.

Why This Change Was Made

• New docs/gateway/clients.md — Building a Gateway client: npm install, scopes + device pairing, the caps registry (incl. tool-events gating live tool streaming), the canonical reconnect recipe (chat.history + inFlightRun + per-run seq), __openclaw history-row metadata and compaction-survivable anchors, sessions.changed push-not-poll, exec.approval.list backfill, and the honest version policy (operator exact-v4, node N-1, additive-first, since vintage).
• New docs/gateway/embedding.md — Embedding OpenClaw: env preset with per-flag effects (incl. the Electron process.execPath snapshot popup), exit code 78 doctor-repair loop instead of stderr scraping, connect.challenge (socket) vs hello-ok (application) readiness, 1013 startup-sidecars retry contract, shutdown event restartExpectedMs as the real restart-vs-shutdown discriminator (close code 1012 is shared), and RPC-not-state-files guidance.
• docs/gateway/protocol.md + external-apps.md link the npm packages; nav registered in docs/docs.json.
• Every cited env var, exit code, close code, cap, and method name grep-verified against current source; outline claims that didn't survive verification were corrected, not shipped.

User Impact

Docs-only. Third-party client and embedder developers get supported, verified contracts instead of source archaeology.

Evidence

• pnpm docs:list shows both pages; MDX 747 files pass; link check 6,145 links 0 broken; formatting clean; docs.json valid; git diff --check clean. Verification greps included in the internal build report.