diff --git a/codex-rs/tui/src/tui/replay_clear.rs b/codex-rs/tui/src/tui/replay_clear.rs
index cb7c9ce5f0..d5bdad30b3 100644
--- a/codex-rs/tui/src/tui/replay_clear.rs
+++ b/codex-rs/tui/src/tui/replay_clear.rs
@@ -1,3 +1,9 @@
+//! Coordinates clearing and replaying terminal history inside one synchronized draw.
+//!
+//! A requested clear remains pending until buffered history has been written successfully. Once
+//! replay is committed, later draw or terminal-flush failures must not retry the clear because the
+//! buffered lines have already been consumed.
+
 use std::io::Result;
 use std::io::Write;