diff --git a/docs/pod-factory.md b/docs/pod-factory.md
index fe8776af..3b91a139 100644
--- a/docs/pod-factory.md
+++ b/docs/pod-factory.md
@@ -188,7 +188,7 @@ scheme 側が吸収する。
 | key | 型 | 既定 | 内容 |
 |---|---|---|---|
 | `instruction` | `String` | `$insomnia/default` | システムプロンプト本体として使う prompt asset 参照 |
-| `max_tokens` | `u32` | 未指定 | 1 request の最大出力 token。scheme が provider の該当 wire field に投影 |
+| `max_tokens` | `u32` | 未指定 | 1 request の最大出力 token。scheme が provider の該当 wire field に投影。scheme ごとのセマンティクス差は `docs/reasoning.md` |
 | `max_turns` | `NonZeroU32` | 未指定 | 1 run 内で Worker が進められる最大 turn 数 |
 | `temperature` | `f32` | 未指定 | sampling temperature |
 | `top_p` | `f32` | 未指定 | nucleus sampling |
diff --git a/docs/reasoning.md b/docs/reasoning.md
index b87bb439..0c6f364d 100644
--- a/docs/reasoning.md
+++ b/docs/reasoning.md
@@ -67,6 +67,21 @@ ref = "gemini/gemini-2.5-pro"
 reasoning = -1
 ```
 
+## `max_tokens` との関係
+
+`[worker] max_tokens` は scheme ごとに wire field 名も意味論も異なる。reasoning モデルで併用するときは特に注意:
+
+| Provider / scheme | wire field | `max_tokens` の意味 |
+|---|---|---|
+| OpenAI Chat (`openai_chat`) | `max_completion_tokens`（Ollama 互換は legacy `max_tokens`） | reasoning tokens を **含む** 合計上限 |
+| OpenAI Responses (`openai_responses`) | `max_output_tokens` | reasoning tokens を **含む** 合計上限 |
+| Anthropic (`anthropic`) | `max_tokens`（必須） | thinking tokens を **含む** 合計上限 |
+| Gemini (`gemini`) | `generationConfig.maxOutputTokens` | visible のみ。thinking tokens は **別計上** |
+
+OpenAI / Anthropic で `max_tokens` を小さく取りつつ高 effort / 大 budget の reasoning を立てると、reasoning に枠を食われて visible output が空で返ることがある。Gemini は別計上なのでこの事故は起きない。
+
+codex-oauth (ChatGPT backend) 経路では `max_output_tokens` が `Unsupported parameter` で 400 を返すため、`openai_responses` scheme は `send_max_output_tokens=false` で wire に載せない。manifest に `max_tokens` を書いても黙って落ちるが、scheme の `validate_config` が `ConfigWarning` を返すので worker 起動時に通知される。
+
 ## 範囲外
 
 - UI プリセット（Low / Medium / High → 各 provider 値）の変換テーブル