diff --git a/codex-rs/app-server-protocol/src/protocol/common.rs b/codex-rs/app-server-protocol/src/protocol/common.rs
index 2aaf419440..b9c58a5883 100644
--- a/codex-rs/app-server-protocol/src/protocol/common.rs
+++ b/codex-rs/app-server-protocol/src/protocol/common.rs
@@ -23,12 +23,22 @@ impl GitSha {
     }
 }
 
+/// Authentication mode for OpenAI-backed providers.
+///
+/// This is used internally to determine the base URL for generating responses, and to gate
+/// ChatGPT-only behaviors like rate limits and available models (as opposed to API key-based
+/// auth).
 #[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq, Display, JsonSchema, TS)]
 #[serde(rename_all = "lowercase")]
 pub enum AuthMode {
+    /// OpenAI API key provided by the caller and stored by Codex.
     ApiKey,
+    /// ChatGPT OAuth managed by Codex (tokens persisted and refreshed by Codex).
     ChatGPT,
     /// [UNSTABLE] FOR OPENAI INTERNAL USE ONLY - DO NOT USE.
+    ///
+    /// ChatGPT auth tokens are supplied by an external host app and are only
+    /// stored in memory. Token refresh must be handled by the external host app.
     #[serde(rename = "chatgptAuthTokens")]
     #[ts(rename = "chatgptAuthTokens")]
     #[strum(serialize = "chatgptAuthTokens")]