diff --git a/crates/kebab-tui/src/cheatsheet.rs b/crates/kebab-tui/src/cheatsheet.rs
index a030489..d7743a5 100644
--- a/crates/kebab-tui/src/cheatsheet.rs
+++ b/crates/kebab-tui/src/cheatsheet.rs
@@ -15,6 +15,13 @@
 //! * The verb hint line redesign sits in the existing `render_footer`
 //!   path; the per-pane string already serves the same role. A
 //!   future PR can split it into mode-aware verb fragments.
+//!
+//! **Maintenance**: the `push_section(...)` calls below hold every
+//! key binding as a literal string — there is NO automated link
+//! from `handle_key_*` to the cheatsheet entries. A future PR that
+//! changes a binding (e.g. swap `r` → `R` for ingest) MUST update
+//! the matching entry here. Drift would be silently invisible
+//! (the cheatsheet still renders, but lies about the live key).
 
 use ratatui::Frame;
 use ratatui::layout::Rect;
diff --git a/crates/kebab-tui/src/run.rs b/crates/kebab-tui/src/run.rs
index ed2846e..9e42954 100644
--- a/crates/kebab-tui/src/run.rs
+++ b/crates/kebab-tui/src/run.rs
@@ -399,7 +399,10 @@ pub fn mode_intercept(app: &mut crate::app::App, key: crossterm::event::KeyEvent
 /// - **`Esc` while visible** → close. Returning `true` here means
 ///   the global `mode_intercept` does NOT also see the Esc, so the
 ///   user's "close cheatsheet" action stays a single keystroke
-///   instead of also flipping mode.
+///   instead of also flipping mode. **Trade-off**: a user in
+///   Insert mode with the cheatsheet open needs a SECOND `Esc` to
+///   flip to Normal. Single-effect-per-keystroke wins over
+///   compound actions.
 /// - Any other key while visible → fall through (so the key reaches
 ///   the active pane normally — useful if the user wants to keep
 ///   the popup open and still navigate). The popup auto-closes