From 4e28ca7c8fd69ab8b2d951f2f6a6eb460b5f7d96 Mon Sep 17 00:00:00 2001
From: William Valentin <william.valentin.info@gmail.com>
Date: Sun, 15 Feb 2026 11:22:59 -0800
Subject: [PATCH] docs: align gateway auth docs with config schema

---
 docs/api/PROTOCOL.md          |  6 +++---
 docs/deployment/PRODUCTION.md | 26 ++++++++++++++++++++------
 docs/plans/state.json         |  5 +++++
 3 files changed, 28 insertions(+), 9 deletions(-)

diff --git a/docs/api/PROTOCOL.md b/docs/api/PROTOCOL.md
index 48a664b..be4e463 100644
--- a/docs/api/PROTOCOL.md
+++ b/docs/api/PROTOCOL.md
@@ -115,7 +115,7 @@ Common close codes:
 
 ### Bearer Token Auth
 
-If `gateway.auth.token` is configured, all WebSocket connections must provide authentication:
+If `server.token` is configured, all WebSocket connections must provide authentication:
 
 ```javascript
 const ws = new WebSocket('ws://localhost:18800', {
@@ -127,7 +127,7 @@ const ws = new WebSocket('ws://localhost:18800', {
 
 ### Tailscale Identity
 
-If `gateway.auth.trustTailscaleIdentity` is enabled, connections from Tailscale are trusted based on the `Tailscale-User-Login` header.
+If `server.tailscale_identity` is enabled, connections from Tailscale are trusted based on the `Tailscale-User-Login` header.
 
 ```javascript
 // Automatic when connecting via Tailscale
@@ -136,7 +136,7 @@ If `gateway.auth.trustTailscaleIdentity` is enabled, connections from Tailscale
 
 ### HTTP Auth
 
-If `gateway.auth.applyToHttp` is `true` (default when token is set), HTTP requests also require bearer token:
+If `server.auth_http` is `true` (default: true), HTTP requests also require bearer token when `server.token` is set:
 
 ```javascript
 fetch('http://localhost:18800/api/health', {
diff --git a/docs/deployment/PRODUCTION.md b/docs/deployment/PRODUCTION.md
index 3d0326e..04e847a 100644
--- a/docs/deployment/PRODUCTION.md
+++ b/docs/deployment/PRODUCTION.md
@@ -289,12 +289,11 @@ rm /tmp/anthropic_key.txt
 
 ```yaml
 # config/production.yaml
-gateway:
-  enabled: true
-  auth:
-    token: 'your-random-token-here'  # Generate with: openssl rand -hex 32
-    trustTailscaleIdentity: true
-    applyToHttp: true
+server:
+  token: 'your-random-token-here'  # Generate with: openssl rand -hex 32
+  tailscale_identity: true
+  auth_http: true
+  lock: false
 ```
 
 Generate a secure token:
@@ -302,6 +301,21 @@ Generate a secure token:
 openssl rand -hex 32
 ```
 
+#### Safe Defaults (Recommended)
+
+These defaults align with `docs/security/SAFE_PERSONAL_AGENT.md`:
+
+```yaml
+pairing:
+  enabled: true
+
+tools:
+  profile: messaging
+
+sandbox:
+  enabled: true
+```
+
 #### Channel Whitelists
 
 Restrict who can interact with Flynn:
diff --git a/docs/plans/state.json b/docs/plans/state.json
index a7369ab..7edae87 100644
--- a/docs/plans/state.json
+++ b/docs/plans/state.json
@@ -14,6 +14,11 @@
       "date": "2026-02-15",
       "summary": "Added docs/architecture/GATEWAY_SESSIONS_AND_QUEUE.md to document how gateway connectionIds map to durable sessionIds, how per-session FIFO lane queueing works, and how agent.cancel behaves."
     },
+    "docs-gateway-auth-config-keys": {
+      "status": "completed",
+      "date": "2026-02-15",
+      "summary": "Docs fix: updated docs/api/PROTOCOL.md and docs/deployment/PRODUCTION.md to use the current config schema keys for gateway auth (server.token/server.tailscale_identity/server.auth_http) and added a short safe-defaults snippet (pairing/tools.profile/sandbox)."
+    },
     "openclaw-gap-roadmap": {
       "file": "2026-02-15-openclaw-gap-roadmap.md",
       "status": "planned",