fix: Update the deprecation message to link to the docs (openai#6211)

The deprecation message is currently a bit confusing. Users may not
understand what is `[features].x`. I updated the docs and the
deprecation message for more guidance.

---------

Co-authored-by: Gabriel Peal <[email protected]>

Author: aibrahim-oai

codex-rs/cli/src/mcp_cmd.rs

@@ -353,7 +353,9 @@ async fn run_login(config_overrides: &CliConfigOverrides, login_args: LoginArgs)
         .context("failed to load configuration")?;
 
     if !config.features.enabled(Feature::RmcpClient) {
-        bail!("OAuth login is only supported when [features].rmcp_client is true in config.toml.");
+        bail!(
+            "OAuth login is only supported when [features].rmcp_client is true in config.toml. See https://github.com/openai/codex/blob/main/docs/config.md#feature-flags for details."
+        );
     }
 
     let LoginArgs { name, scopes } = login_args;

codex-rs/core/src/codex.rs

@@ -553,7 +553,7 @@ impl Session {
                 None
             } else {
                 Some(format!(
-                    "You can either enable it using the CLI with `--enable {canonical}` or through the config.toml file with `[features].{canonical}`"
+                    "Enable it with `--enable {canonical}` or `[features].{canonical}` in config.toml. See https://github.com/openai/codex/blob/main/docs/config.md#feature-flags for details."
                 ))
             };
             post_session_configured_events.push(Event {

codex-rs/core/tests/suite/deprecation_notice.rs

@@ -43,7 +43,7 @@ async fn emits_deprecation_notice_for_legacy_feature_flag() -> anyhow::Result<()
     assert_eq!(
         details.as_deref(),
         Some(
-            "You can either enable it using the CLI with `--enable streamable_shell` or through the config.toml file with `[features].streamable_shell`"
+            "Enable it with `--enable streamable_shell` or `[features].streamable_shell` in config.toml. See https://github.com/openai/codex/blob/main/docs/config.md#feature-flags for details."
         ),
     );
 

docs/config.md

@@ -4,6 +4,7 @@ Codex configuration gives you fine-grained control over the model, execution env
 
 ## Quick navigation
 
+- [Feature flags](#feature-flags)
 - [Model selection](#model-selection)
 - [Execution environment](#execution-environment)
 - [MCP integration](#mcp-integration)
@@ -26,6 +27,36 @@ Codex supports several mechanisms for setting config values:
 
 Both the `--config` flag and the `config.toml` file support the following options:
 
+## Feature flags
+
+Optional and experimental capabilities are toggled via the `[features]` table in `$CODEX_HOME/config.toml`. If you see a deprecation notice mentioning a legacy key (for example `experimental_use_exec_command_tool`), move the setting into `[features]` or pass `--enable <feature>`.
+
+```toml
+[features]
+streamable_shell = true          # enable the streamable exec tool
+web_search_request = true        # allow the model to request web searches
+# view_image_tool defaults to true; omit to keep defaults
+```
+
+Supported features:
+
+| Key                                       | Default | Stage        | Description                                          |
+| ----------------------------------------- | :-----: | ------------ | ---------------------------------------------------- |
+| `unified_exec`                            |  false  | Experimental | Use the unified PTY-backed exec tool                 |
+| `streamable_shell`                        |  false  | Experimental | Use the streamable exec-command/write-stdin pair     |
+| `rmcp_client`                             |  false  | Experimental | Enable oauth support for streamable HTTP MCP servers |
+| `apply_patch_freeform`                    |  false  | Beta         | Include the freeform `apply_patch` tool              |
+| `view_image_tool`                         |  true   | Stable       | Include the `view_image` tool                        |
+| `web_search_request`                      |  false  | Stable       | Allow the model to issue web searches                |
+| `experimental_sandbox_command_assessment` |  false  | Experimental | Enable model-based sandbox risk assessment           |
+| `ghost_commit`                            |  false  | Experimental | Create a ghost commit each turn                      |
+| `enable_experimental_windows_sandbox`     |  false  | Experimental | Use the Windows restricted-token sandbox             |
+
+Notes:
+
+- Omit a key to accept its default.
+- Legacy booleans such as `experimental_use_exec_command_tool`, `experimental_use_unified_exec_tool`, `include_apply_patch_tool`, and similar `experimental_use_*` keys are deprecated; setting the corresponding `[features].<key>` avoids repeated warnings.
+
 ## Model selection
 
 ### model