diff --git a/codex-rs/cli/tests/auto_update_startup.rs b/codex-rs/cli/tests/auto_update_startup.rs
index c44cb0def4..19479ae1bd 100644
--- a/codex-rs/cli/tests/auto_update_startup.rs
+++ b/codex-rs/cli/tests/auto_update_startup.rs
@@ -1,3 +1,10 @@
+//! End-to-end PTY coverage for the startup auto-update handoff.
+//!
+//! This test seeds cached update state and a fake `npm` on `PATH`, then runs
+//! the real `codex` binary. Its job is to document and enforce the contract
+//! that startup reuses the existing updater path and preserves the updater
+//! working directory and argv.
+
 use std::collections::HashMap;
 use std::time::Duration;
 
diff --git a/codex-rs/tui/src/update_prompt.rs b/codex-rs/tui/src/update_prompt.rs
index cbe624b65e..020d565a33 100644
--- a/codex-rs/tui/src/update_prompt.rs
+++ b/codex-rs/tui/src/update_prompt.rs
@@ -1,4 +1,9 @@
 #![cfg(not(debug_assertions))]
+//! Renders the startup update prompt and reports which startup path to take.
+//!
+//! This module owns the selection layer for update prompts. It decides whether
+//! startup should continue normally or hand control back to the CLI to run an
+//! updater command, but it does not execute the updater itself.
 
 use crate::history_cell::padded_emoji;
 use crate::key_hint;
@@ -28,8 +33,15 @@ use ratatui::widgets::Clear;
 use ratatui::widgets::WidgetRef;
 use tokio_stream::StreamExt;
 
+/// Describes what startup should do after resolving update prompt state.
+///
+/// The TUI returns this instead of spawning updater processes directly so the
+/// CLI remains the single owner of command execution, exit behavior, and
+/// update status messaging.
 pub(crate) enum UpdatePromptOutcome {
+    /// Proceed into the normal TUI startup path.
     Continue,
+    /// Exit startup and run the detected updater command through the CLI.
     RunUpdate(UpdateAction),
 }