From 41760f8a093d576453873adb91e81f727f98b91f Mon Sep 17 00:00:00 2001
From: Kaden Gruizenga <kjgruiz@pm.me>
Date: Mon, 1 Dec 2025 13:46:53 -0500
Subject: [PATCH] docs: clarify codex max defaults and xhigh availability
 (#7449)

## Summary
Adds the missing `xhigh` reasoning level everywhere it should have been
documented, and makes clear it only works with `gpt-5.1-codex-max`.

## Changes

* `docs/config.md`

* Add `xhigh` to the official list of reasoning levels with a note that
`xhigh` is exclusive to Codex Max.

* `docs/example-config.md`

* Update the example comment adding `xhigh` as a valid option but only
for Codex Max.

* `docs/faq.md`

  * Update the model recommendation to `GPT-5.1 Codex Max`.
* Mention that users can choose `high` or the newly documented `xhigh`
level when using Codex Max.
---
 docs/config.md         | 1 +
 docs/example-config.md | 2 +-
 docs/faq.md            | 2 +-
 3 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/docs/config.md b/docs/config.md
index df4da3b00..a3e6ed266 100644
--- a/docs/config.md
+++ b/docs/config.md
@@ -195,6 +195,7 @@ If the selected model is known to support reasoning (for example: `o3`, `o4-mini
 - `"low"`
 - `"medium"` (default)
 - `"high"`
+- `"xhigh"` (available only on `gpt-5.1-codex-max`)
 
 Note: to minimize reasoning, choose `"minimal"`.
 
diff --git a/docs/example-config.md b/docs/example-config.md
index bd220a41e..cc53efa61 100644
--- a/docs/example-config.md
+++ b/docs/example-config.md
@@ -37,7 +37,7 @@ model_provider = "openai"
 # Reasoning & Verbosity (Responses API capable models)
 ################################################################################
 
-# Reasoning effort: minimal | low | medium | high (default: medium)
+# Reasoning effort: minimal | low | medium | high | xhigh (default: medium; xhigh only on gpt-5.1-codex-max)
 model_reasoning_effort = "medium"
 
 # Reasoning summary: auto | concise | detailed | none (default: auto)
diff --git a/docs/faq.md b/docs/faq.md
index 72cbdff79..37b9ef39d 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -8,7 +8,7 @@ In 2021, OpenAI released Codex, an AI system designed to generate code from natu
 
 ### Which models are supported?
 
-We recommend using Codex with GPT-5.1 Codex, our best coding model. The default reasoning level is medium, and you can upgrade to high for complex tasks with the `/model` command.
+We recommend using Codex with GPT-5.1 Codex Max, our best coding model. The default reasoning level is medium, and you can upgrade to high or xhigh (Codex Max only) for complex tasks with the `/model` command.
 
 You can also use older models by using API-based auth and launching codex with the `--model` flag.