diff --git a/codex-rs/config/src/config_toml.rs b/codex-rs/config/src/config_toml.rs
index 89eb30b798..d2eeaf927f 100644
--- a/codex-rs/config/src/config_toml.rs
+++ b/codex-rs/config/src/config_toml.rs
@@ -176,7 +176,10 @@ pub struct ConfigToml {
     pub compact_prompt: Option<String>,
 
     /// Optional commit attribution text for commit message co-author trailers.
+    /// This top-level setting only takes effect when `[features].codex_git_commit`
+    /// is enabled.
     ///
+    /// When enabled and unset, Codex uses `Codex <noreply@openai.com>`.
     /// Set to an empty string to disable automatic commit attribution.
     pub commit_attribution: Option<String>,
 
diff --git a/codex-rs/core/config.schema.json b/codex-rs/core/config.schema.json
index 17343ed86f..fe3e48a2df 100644
--- a/codex-rs/core/config.schema.json
+++ b/codex-rs/core/config.schema.json
@@ -3838,7 +3838,7 @@
       "description": "Preferred backend for storing CLI auth credentials. file (default): Use a file in the Codex home directory. keyring: Use an OS-specific keyring service. auto: Use the keyring if available, otherwise use a file."
     },
     "commit_attribution": {
-      "description": "Optional commit attribution text for commit message co-author trailers.\n\nSet to an empty string to disable automatic commit attribution.",
+      "description": "Optional commit attribution text for commit message co-author trailers. This top-level setting only takes effect when `[features].codex_git_commit` is enabled.\n\nWhen enabled and unset, Codex uses `Codex <noreply@openai.com>`. Set to an empty string to disable automatic commit attribution.",
       "type": "string"
     },
     "compact_prompt": {
diff --git a/codex-rs/core/src/config/mod.rs b/codex-rs/core/src/config/mod.rs
index 75d99f4b18..ed355a0ae7 100644
--- a/codex-rs/core/src/config/mod.rs
+++ b/codex-rs/core/src/config/mod.rs
@@ -476,6 +476,8 @@ pub struct Config {
     pub compact_prompt: Option<String>,
 
     /// Optional commit attribution text for commit message co-author trailers.
+    /// This top-level setting only takes effect when `[features].codex_git_commit`
+    /// is enabled.
     ///
     /// - `None`: use default attribution (`Codex <noreply@openai.com>`)
     /// - `Some("")` or whitespace-only: disable commit attribution
diff --git a/docs/config.md b/docs/config.md
index 950a631fc5..e0a0c5fc2f 100644
--- a/docs/config.md
+++ b/docs/config.md
@@ -5,3 +5,24 @@ For basic configuration instructions, see [this documentation](https://developer
 For advanced configuration instructions, see [this documentation](https://developers.openai.com/codex/config-advanced).
 
 For a full configuration reference, see [this documentation](https://developers.openai.com/codex/config-reference).
+
+## Commit attribution
+
+Codex can add a [git trailer](https://git-scm.com/docs/git-interpret-trailers) to
+generated commit messages so commits make Codex's involvement explicit. This
+behavior is gated by the `codex_git_commit` feature flag; the top-level
+`commit_attribution` setting is only used when that feature is enabled.
+
+Add the following to `~/.codex/config.toml`:
+
+```toml
+commit_attribution = "Codex <noreply@openai.com>"
+
+[features]
+codex_git_commit = true
+```
+
+When enabled, Codex appends a `Co-authored-by:` trailer using the configured
+attribution value. If `commit_attribution` is omitted, Codex uses
+`Codex <noreply@openai.com>`. Set `commit_attribution = ""` to disable the
+trailer while leaving the feature flag enabled.