diff --git a/docs/cli/index.md b/docs/cli/index.md
index 550706c53cf..81c1d56590f 100644
--- a/docs/cli/index.md
+++ b/docs/cli/index.md
@@ -1460,6 +1460,8 @@ Notes:
 
 Common RPCs:
 
+- `config.schema.lookup` (inspect one config subtree with field docs)
+- `config.get` (read current config snapshot + hash)
 - `config.set` (validate + write full config; use `baseHash` for optimistic concurrency)
 - `config.apply` (validate + write config + restart + wake)
 - `config.patch` (merge a partial update + restart + wake)
@@ -1467,6 +1469,7 @@ Common RPCs:
 
 Tip: when calling `config.set`/`config.apply`/`config.patch` directly, pass `baseHash` from
 `config.get` if a config already exists.
+Tip: for partial edits, inspect with `config.schema.lookup` first and prefer `config.patch`.
 Tip: these config write RPCs preflight active SecretRef resolution for refs in the submitted config payload and reject writes when an effectively active submitted ref is unresolved.
 
 ## Models
diff --git a/docs/gateway/configuration.md b/docs/gateway/configuration.md
index 7df771da285..5508602b669 100644
--- a/docs/gateway/configuration.md
+++ b/docs/gateway/configuration.md
@@ -522,6 +522,17 @@ Most fields hot-apply without downtime. In `hybrid` mode, restart-required chang
 Control-plane write RPCs (`config.apply`, `config.patch`, `update.run`) are rate-limited to **3 requests per 60 seconds** per `deviceId+clientIp`. When limited, the RPC returns `UNAVAILABLE` with `retryAfterMs`.
 </Note>
 
+Safe/default flow:
+
+- `config.schema.lookup`: inspect one path-scoped config subtree with field docs
+- `config.get`: fetch the current snapshot + hash
+- `config.patch`: preferred partial update path
+- `config.apply`: full-config replacement only
+- `update.run`: explicit self-update + restart
+
+When you are not replacing the entire config, prefer `config.schema.lookup`
+then `config.patch`.
+
 <AccordionGroup>
   <Accordion title="config.apply (full replace)">
     Validates + writes the full config and restarts the Gateway in one step.
diff --git a/docs/gateway/security/index.md b/docs/gateway/security/index.md
index 479c4924cc5..d6898a5385e 100644
--- a/docs/gateway/security/index.md
+++ b/docs/gateway/security/index.md
@@ -542,7 +542,7 @@ change other sessions.
 
 Two built-in tools can make persistent control-plane changes:
 
-- `gateway` can call `config.apply`, `config.patch`, and `update.run`.
+- `gateway` can inspect config with `config.schema.lookup` / `config.get`, and can make persistent changes with `config.apply`, `config.patch`, and `update.run`.
 - `cron` can create scheduled jobs that keep running after the original chat/task ends.
 
 For any agent/surface that handles untrusted content, deny these by default: