diff --git a/skills/omni-settings/SKILL.md b/skills/omni-settings/SKILL.md
index 55fae9a557..79d930097b 100644
--- a/skills/omni-settings/SKILL.md
+++ b/skills/omni-settings/SKILL.md
@@ -319,7 +319,15 @@ curl -X PUT https://localhost:20128/api/settings/system-prompt \
 
 Get thinking budget configuration
 
-Returns the current thinking/reasoning budget settings for AI models.
+Returns proxy-level thinking/reasoning **request rewrite** settings:
+
+| Field | Meaning |
+|-------|---------|
+| `mode` | `passthrough` (leave client reasoning alone — **required for Codex visible thinking**), `auto` (**strips** all client thinking fields), `custom`, `adaptive` |
+| `customBudget` | Fixed budget when `mode=custom` |
+| `effortLevel` | Base effort when `mode=adaptive` |
+
+**Not** compression and **not** “decrypt encrypted reasoning”. Full guide: `docs/guides/THINKING_BUDGET.md`.
 
 ```bash
 curl https://localhost:20128/api/settings/thinking-budget \
@@ -330,13 +338,17 @@ curl https://localhost:20128/api/settings/thinking-budget \
 
 Update thinking budget configuration
 
+Example — keep client-controlled reasoning (Codex/Desktop):
+
 ```bash
 curl -X PUT https://localhost:20128/api/settings/thinking-budget \
-  -H "Authorization: Bearer $OMNIROUTE_TOKEN"
+  -H "Authorization: Bearer $OMNIROUTE_TOKEN" \
   -H "Content-Type: application/json" \
-  -d '{}'
+  -d '{"mode":"passthrough","customBudget":10240,"effortLevel":"medium"}'
 ```
 
+Warning: `mode=auto` deletes `reasoning` / `reasoning_effort` / Claude `thinking` from the outbound body before upstream. That can empty thinking panels even when the client requested Ultra + summary.
+
 ### GET /api/tags
 
 List Ollama-compatible model tags