docs(comments): rewrite comments across all crates to the guidelines

Sweep every first-party crate source (1956 .rs files) to the project comment
guidelines: delete redundant restatements, decorative banners, change
narration, and end-of-line comments; keep and tighten the crucial ones
(invariants, bug rationale, SAFETY blocks, ported-source attribution).

No functional code changed. Every edit is proven comment-only against the
prior tree by a comment-stripping lexer (string/char/raw-string aware) plus a
separate doctest-fence check. Where removing a comment made rustfmt or clippy
want to re-lay-out adjacent code, the minimal triggering comment is restored so
code tokens stay byte-identical.

Gates green: cargo fmt --all --check (0 diffs), cargo check and cargo clippy
--workspace --all-targets (0 warnings).

Adds scripts/check_codegen_comment_guidelines.py — the enforcement gate for
these guidelines (flags banners, end-of-line comments, change narration, and
commented-out code).

crates/codegen/kigi-pager-render/src/terminal/embedded_editor.rs

@@ -31,7 +31,7 @@ pub enum EmbeddedEditor {
 /// [`EmbeddedEditor::Emacs`]; else `None`. Empty values are treated as absent
 /// (matching the sibling `detect_*_from_env` detectors via `env_get`).
 ///
-/// Adding a new env marker here requires extending
+/// Including a new env marker here requires extending
 /// `HOST_TERMINAL_ENV_VARS` in `kigi-pager-pty-harness/src/pty.rs`
 /// (test-env hygiene).
 pub fn embedded_editor_from_env(env: &HashMap<String, String>) -> Option<EmbeddedEditor> {

crates/codegen/kigi-pager-render/src/terminal/hyperlinks.rs

@@ -56,7 +56,7 @@ pub struct HyperlinkCapabilities {
     pub id_param: bool,
     /// Which URL schemes the terminal handles.
     pub scheme_filter: SchemeFilter,
-    /// Whether the terminal supports OSC 22 cursor-shape changes
+    /// Whether the terminal supports OSC 22 cursor-shape shifts
     /// (e.g. switching to a hand/pointer cursor on link hover).
     pub osc22_cursor: bool,
     /// Whether the terminal handles link hover styling natively (so our
@@ -197,7 +197,7 @@ pub fn hyperlink_capabilities(brand: TerminalName) -> HyperlinkCapabilities {
     }
 }
 
-// ── OSC 22 cursor-shape commands ──────────────────────────────────────
+// OSC 22 cursor-shape commands
 //
 // These wrap raw OSC 22 sequences as crossterm `Command`s so call sites
 // can use `crossterm::execute!` / `queue!` instead of manual byte writes.

crates/codegen/kigi-pager-render/src/terminal/image.rs

@@ -3,7 +3,7 @@
 //! Provides escape-sequence helpers for rendering images inside the
 //! existing preview overlay. The text-fallback path in
 //! [`crate::render::image_overlay`] remains the primary preview; this
-//! module adds pixel-level rendering for supported terminals.
+//! module provides pixel-level rendering for supported terminals.
 //!
 //! # Supported protocols
 //!
@@ -27,9 +27,7 @@ use std::sync::atomic::{AtomicBool, Ordering};
 
 use super::{TerminalName, terminal_context};
 
-// -------------------------------------------------------------------------
 // Graphics protocol detection
-// -------------------------------------------------------------------------
 
 /// Graphics protocol supported by the current terminal.
 #[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
@@ -187,9 +185,7 @@ pub fn protocol_for_brand(brand: TerminalName, is_windows: bool) -> GraphicsProt
     }
 }
 
-// -------------------------------------------------------------------------
 // Kitty graphics protocol
-// -------------------------------------------------------------------------
 
 /// Shared placement ID; every renderer must coordinate through [`super::overlay`].
 pub(super) const KITTY_PLACEMENT_ID: u32 = 1;
@@ -434,9 +430,7 @@ pub fn clear_kitty_image(image_id: u32) -> String {
     format!("\x1b_Ga=d,d=i,i={},q=2\x1b\\", image_id)
 }
 
-// -------------------------------------------------------------------------
 // iTerm2 inline images protocol
-// -------------------------------------------------------------------------
 
 /// Build an iTerm2 inline image escape sequence.
 ///
@@ -452,9 +446,7 @@ pub fn render_iterm2_image(image_data: &[u8], cols: u16, rows: u16) -> String {
     )
 }
 
-// -------------------------------------------------------------------------
 // Shared overlay helpers
-// -------------------------------------------------------------------------
 
 /// Build the full escape-sequence string to render image data at a cell
 /// position using the provided graphics protocol.
@@ -506,7 +498,8 @@ pub(super) fn build_overlay_image_escapes_for_protocol(
                 KITTY_PLACEMENT_ID,
                 cols,
                 rows,
-                1, // above text (modal overlays)
+                // above text (modal overlays)
+                1,
             ));
         }
         GraphicsProtocol::ITerm2 => {
@@ -643,9 +636,7 @@ pub fn fit_image_to_cells(img_w: u32, img_h: u32, max_cols: u16, max_rows: u16)
     }
 }
 
-// =========================================================================
 // Tests
-// =========================================================================
 
 #[cfg(test)]
 mod tests;

crates/codegen/kigi-pager-render/src/terminal/keyboard.rs

@@ -4,7 +4,7 @@
 //! instead of branching on brand. The classification depends on the
 //! current `HostOs`, queried internally — today only macOS rows are
 //! populated. Extend [`KeyboardCapabilities`] with new fields (paste
-//! protocol, focus reporting, custom escapes) instead of adding more
+//! protocol, focus reporting, custom escapes) instead of stacking more
 //! `match self.brand` sites scattered through the pager.
 
 use super::TerminalName;
@@ -84,7 +84,7 @@ impl KeyboardCapabilities {
 /// Classify keyboard capabilities for a given `(brand, os, display_server)`.
 ///
 /// Today the table is populated only for macOS; other OSes return the
-/// default (all-`Unknown`). When a Linux/Windows probe lands, add a
+/// default (all-`Unknown`). When a Linux/Windows probe lands, include a
 /// per-OS arm here rather than forking the function.
 pub fn keyboard_capabilities(brand: TerminalName) -> KeyboardCapabilities {
     match HostOs::current() {

crates/codegen/kigi-pager-render/src/terminal/mod.rs

@@ -152,7 +152,8 @@ pub enum TerminalName {
 
 impl TerminalName {
     pub fn is_vte_based(self) -> bool {
-        matches!(self, Self::Vte | Self::Terminator) // WHY: single source of truth for the VTE family
+        // WHY: single source of truth for the VTE family
+        matches!(self, Self::Vte | Self::Terminator)
     }
 
     /// VS Code integrated terminal and xterm.js-based IDE embeds (including forks).
@@ -197,7 +198,8 @@ impl TerminalName {
 
 impl TerminalContext {
     pub fn is_vte_based(&self) -> bool {
-        self.brand.is_vte_based() || self.vte_version.is_some() // WHY: covers brand + legacy version marker
+        // WHY: covers brand + legacy version marker
+        self.brand.is_vte_based() || self.vte_version.is_some()
     }
 }
 
@@ -210,7 +212,6 @@ pub enum MultiplexerKind {
     /// GNU screen (including Byobu-on-screen).
     #[strum(to_string = "GNU screen")]
     Screen,
-    /// Zellij.
     Zellij,
     /// cmux (Ghostty-backed macOS terminal multiplexer).
     #[strum(to_string = "cmux")]
@@ -456,7 +457,8 @@ impl TerminalContext {
     /// In every case `Alt+Enter` (delivered as `ESC`+`CR`) is the reliable
     /// newline chord and is what the UI advertises.
     pub fn shift_enter_unavailable(&self) -> bool {
-        let is_vte = self.is_vte_based(); // WHY: central helper + version gating
+        // WHY: central helper + version gating
+        let is_vte = self.is_vte_based();
         if is_vte {
             return match self
                 .vte_version
@@ -671,7 +673,7 @@ fn env_get<'a>(env: &'a HashMap<String, String>, key: &str) -> Option<&'a str> {
 ///
 /// This is the pure equivalent of the original `detect_terminal_info`.
 ///
-/// Adding a new env marker to this brand chain (or to
+/// Including a new env marker to this brand chain (or to
 /// [`detect_byobu_from_env`] / [`detect_multiplexer_from_env`] below)
 /// requires extending `HOST_TERMINAL_ENV_VARS` in
 /// `kigi-pager-pty-harness/src/pty.rs` (test-env hygiene — the PTY
@@ -884,7 +886,8 @@ pub fn detect_multiplexer_from_env(env: &HashMap<String, String>) -> Multiplexer
         match backend {
             ByobuBackend::Tmux => return MultiplexerKind::Tmux,
             ByobuBackend::Screen => return MultiplexerKind::Screen,
-            ByobuBackend::Unknown => {} // fall through to standard markers
+            // fall through to standard markers
+            ByobuBackend::Unknown => {}
         }
     }
 
@@ -959,7 +962,6 @@ pub fn build_terminal_context_from_env(env: &HashMap<String, String>) -> Termina
     }
 }
 
-/// Map TERM_PROGRAM value to terminal name.
 fn terminal_name_from_term_program(value: &str) -> Option<TerminalName> {
     let normalized: String = value
         .trim()

crates/codegen/kigi-pager-render/src/terminal/overlay.rs

@@ -11,6 +11,9 @@ use super::image::{
 static NEXT_OWNER_ID: AtomicU64 = AtomicU64::new(1);
 
 thread_local! {
+    /// Owner whose image the terminal is believed to still hold; a matching
+    /// owner lets the next frame re-place that image without retransmitting
+    /// its pixel data.
     static OWNER: std::cell::Cell<Option<u64>> = const { std::cell::Cell::new(None) };
 }
 
@@ -20,6 +23,10 @@ pub(crate) enum Ownership {
     Clear,
 }
 
+/// Escape bytes plus the ownership transition they imply. The transition is
+/// applied only by [`Escapes::commit`] or [`PostFlush::write_to`], so escapes
+/// that are built and then dropped — or that fail to reach the terminal —
+/// leave `OWNER` describing what the terminal actually holds.
 #[derive(Debug)]
 pub struct Escapes {
     bytes: String,

crates/codegen/kigi-pager-render/src/terminal/test.rs

@@ -1,6 +1,6 @@
 use super::*;
 
-// -- terminal_name_from_term_program (existing coverage) ------------------
+// terminal_name_from_term_program (existing coverage)
 
 #[test]
 fn test_terminal_name_from_term_program() {
@@ -89,7 +89,7 @@ fn otty_skips_kitty_keyboard_like_unknown() {
     assert!(ctx.shift_enter_unavailable());
 }
 
-// -- detect_terminal_brand_from_env (pure) --------------------------------
+// detect_terminal_brand_from_env (pure)
 
 #[test]
 fn brand_ghostty_from_term_program() {
@@ -187,10 +187,11 @@ fn brand_vte_from_vte_version() {
 #[test]
 fn brand_terminator_from_term_program() {
     let env = env_from(&[("TERM_PROGRAM", "terminator")]);
+    // WHY: canonical per detect-terminal
     assert_eq!(
         detect_terminal_brand_from_env(&env),
         TerminalName::Terminator
-    ); // WHY: canonical per detect-terminal
+    );
 }
 
 #[test]
@@ -198,7 +199,8 @@ fn terminator_vte_version_interaction() {
     let env = env_from(&[("TERM_PROGRAM", "terminator"), ("VTE_VERSION", "8200")]);
     let ctx = build_terminal_context_from_env(&env);
     assert_eq!(ctx.brand, TerminalName::Terminator);
-    assert!(ctx.is_vte_based()); // WHY: helper covers version + brand
+    // WHY: helper covers version + brand
+    assert!(ctx.is_vte_based());
 }
 
 #[test]
@@ -221,10 +223,11 @@ fn terminator_over_ssh() {
 fn terminator_focus_tracking() {
     let env = env_from(&[("TERM_PROGRAM", "terminator")]);
     let ctx = build_terminal_context_from_env(&env);
+    // supports focus like VTE
     assert!(!matches!(
         ctx.brand,
         TerminalName::AppleTerminal | TerminalName::Unknown
-    )); // supports focus like VTE
+    ));
     assert!(ctx.is_vte_based());
 }
 
@@ -244,16 +247,18 @@ fn brand_unknown_empty_env() {
     assert_eq!(detect_terminal_brand_from_env(&env), TerminalName::Unknown);
 }
 
-// -- refine_unknown_brand_for_host ---------------------------------------
+// refine_unknown_brand_for_host
 
 #[test]
 fn refine_unknown_brand_defaults_to_wt_only_on_windows() {
     use super::TerminalName::{Unknown, VsCode, WindowsTerminal};
     use crate::host::HostOs::{Linux, Windows};
     let cases = [
-        (Unknown, Windows, WindowsTerminal), // DefTerm handoff: no WT_SESSION
+        // DefTerm handoff: no WT_SESSION
+        (Unknown, Windows, WindowsTerminal),
         (Unknown, Linux, Unknown),
-        (VsCode, Windows, VsCode), // never override a positively detected brand
+        // never override a positively detected brand
+        (VsCode, Windows, VsCode),
     ];
     for (brand, host, expected) in cases {
         assert_eq!(refine_unknown_brand_for_host(brand, host), expected);
@@ -301,7 +306,7 @@ fn mouse_reporting_leaks_only_for_jetbrains_on_windows() {
     assert!(!mouse_reporting_leaks(TerminalName::Kitty, HostOs::Windows));
 }
 
-// -- detect_byobu_from_env ------------------------------------------------
+// detect_byobu_from_env
 
 #[test]
 fn byobu_tmux_explicit_backend() {
@@ -342,7 +347,7 @@ fn no_byobu_markers_returns_none() {
     assert_eq!(detect_byobu_from_env(&env), None);
 }
 
-// -- detect_multiplexer_from_env ------------------------------------------
+// detect_multiplexer_from_env
 
 #[test]
 fn mux_plain_tmux() {
@@ -416,7 +421,7 @@ fn mux_tmux_nested_inside_cmux_wins() {
     assert_eq!(detect_multiplexer_from_env(&env), MultiplexerKind::Tmux);
 }
 
-// -- ambiguous marker precedence ------------------------------------------
+// ambiguous marker precedence
 
 #[test]
 fn tmux_beats_zellij_when_both_set() {
@@ -447,7 +452,7 @@ fn byobu_tmux_explicit_with_sty_stays_tmux() {
     assert_eq!(detect_multiplexer_from_env(&env), MultiplexerKind::Tmux);
 }
 
-// -- detect_tmux_meta_from_env --------------------------------------------
+// detect_tmux_meta_from_env
 
 #[test]
 fn tmux_meta_populated() {
@@ -470,7 +475,7 @@ fn tmux_meta_empty_outside_tmux() {
     assert_eq!(meta, TmuxClientMeta::default());
 }
 
-// -- build_terminal_context_from_env (integration) ------------------------
+// build_terminal_context_from_env (integration)
 
 #[test]
 fn context_plain_terminal() {
@@ -598,9 +603,7 @@ fn context_empty_env_values_ignored() {
     assert_eq!(ctx.multiplexer, MultiplexerKind::Undetected);
 }
 
-// =====================================================================
 // determine_alt_screen_policy: fullscreen policy matrix
-// =====================================================================
 
 fn plain_ctx() -> TerminalContext {
     TerminalContext {
@@ -660,7 +663,7 @@ fn byobu_screen_ctx() -> TerminalContext {
     }
 }
 
-// -- Alt-screen policy matrix (all modes × contexts × CLI override) -------
+// Alt-screen policy matrix (all modes × contexts × CLI override)
 
 #[derive(Debug)]
 struct AltScreenCase {
@@ -900,7 +903,7 @@ fn alt_screen_policy_matrix() {
     }
 }
 
-// -- Windows Terminal context integration ---------------------------------
+// Windows Terminal context integration
 
 #[test]
 fn context_windows_terminal() {
@@ -911,13 +914,11 @@ fn context_windows_terminal() {
     assert!(!ctx.is_ssh);
 }
 
-// -- Terminal brand detection edge cases -----------------------------------
+// Terminal brand detection edge cases
 
-// =====================================================================
 // Extended environment matrix (final hardening)
-// =====================================================================
 
-// -- Byobu-screen: auto keeps fullscreen (screen is not auto-disabled) ----
+// Byobu-screen: auto keeps fullscreen (screen is not auto-disabled)
 
 #[test]
 fn auto_byobu_screen_is_fullscreen() {
@@ -935,7 +936,7 @@ fn auto_byobu_screen_is_fullscreen() {
     ));
 }
 
-// -- Terminal brand detection edge cases -----------------------------------
+// Terminal brand detection edge cases
 
 #[test]
 fn brand_vscode_from_term_program() {
@@ -978,7 +979,7 @@ fn brand_term_program_takes_precedence_over_other_vars() {
     assert_eq!(detect_terminal_brand_from_env(&env), TerminalName::Ghostty);
 }
 
-// -- IDE family detection (VS Code forks / xterm.js embeds) ---------------
+// IDE family detection (VS Code forks / xterm.js embeds)
 
 #[test]
 fn brand_cursor_from_cursor_trace_id() {
@@ -1054,7 +1055,7 @@ fn brand_vscode_from_askpass_without_term_program() {
     assert_eq!(detect_terminal_brand_from_env(&env), TerminalName::VsCode);
 }
 
-// -- Zellij detection from ZELLIJ_VERSION (no ZELLIJ or SESSION_NAME) -----
+// Zellij detection from ZELLIJ_VERSION (no ZELLIJ or SESSION_NAME)
 
 #[test]
 fn mux_zellij_not_from_version_only() {
@@ -1067,7 +1068,7 @@ fn mux_zellij_not_from_version_only() {
     );
 }
 
-// -- Byobu inference edge cases -------------------------------------------
+// Byobu inference edge cases
 
 #[test]
 fn byobu_unknown_backend_string_with_tmux() {
@@ -1088,7 +1089,7 @@ fn byobu_unknown_backend_no_mux_returns_none() {
     assert_eq!(detect_byobu_from_env(&env), None);
 }
 
-// -- Context-level edge cases ---------------------------------------------
+// Context-level edge cases
 
 #[test]
 fn context_sty_takes_screen_when_no_tmux_or_zellij() {
@@ -1137,9 +1138,7 @@ fn context_is_byobu_returns_false_without_byobu_markers() {
     assert!(!build_terminal_context_from_env(&env).is_byobu());
 }
 
-// =====================================================================
 // parse_tmux_major_minor: version string parsing
-// =====================================================================
 
 #[test]
 fn parse_tmux_version_standard() {
@@ -1186,9 +1185,7 @@ fn parse_tmux_version_no_minor() {
     assert_eq!(parse_tmux_major_minor("tmux 3"), None);
 }
 
-// =====================================================================
 // parse_semver_major_minor: TERM_PROGRAM_VERSION parsing
-// =====================================================================
 
 #[test]
 fn parse_semver_standard() {
@@ -1220,7 +1217,6 @@ fn parse_semver_major_only() {
     assert_eq!(parse_semver_major_minor("3"), None);
 }
 
-// =====================================================================
 // graphics_protocol_skip_reason
 
 #[test]
@@ -1243,7 +1239,6 @@ fn graphics_protocol_skip_reason_plain_kitty() {
 }
 
 // kitty_skip_reason: Kitty keyboard protocol skip-reason matrix
-// =====================================================================
 
 #[test]
 fn kitty_skip_vscode() {
@@ -1466,9 +1461,7 @@ fn kitty_skip_vte_brand() {
     assert_eq!(ctx.kitty_skip_reason(), Some("vte"));
 }
 
-// =====================================================================
 // shift_enter_unavailable: VTE version gating for Shift+Enter
-// =====================================================================
 //
 // VTE 0.82.0 (= VTE_VERSION 8200) is the first release containing the
 // Kitty keyboard protocol; earlier versions cannot distinguish
@@ -1550,7 +1543,8 @@ fn shift_enter_available_kkp_terminals() {
     ] {
         let ctx = TerminalContext {
             brand,
-            env_brand: brand, // lockstep with brand (no Windows refinement)
+            // lockstep with brand (no Windows refinement)
+            env_brand: brand,
             ..Default::default()
         };
         assert!(
@@ -1738,7 +1732,7 @@ fn ctrl_dot_unreliable_on_unknown_no_multiplexer() {
     assert!(ctx.ctrl_dot_unreliable());
 }
 
-// -- tmux extended-keys interaction with kitty_skip_reason ---------------
+// tmux extended-keys interaction with kitty_skip_reason
 
 fn extended_keys_ctx(version: &str, extended_keys: Option<&str>) -> TerminalContext {
     TerminalContext {
@@ -1803,9 +1797,7 @@ fn kitty_skip_vte_takes_precedence_over_tmux_old() {
     assert_eq!(ctx.kitty_skip_reason(), Some("vte"));
 }
 
-// =====================================================================
 // JetBrains JediTerm detection
-// =====================================================================
 
 #[test]
 fn brand_jetbrains_from_terminal_emulator() {

crates/codegen/kigi-pager-render/src/terminal/xtversion.rs

@@ -21,7 +21,6 @@
 use std::sync::OnceLock;
 use std::sync::atomic::{AtomicBool, Ordering};
 
-/// Startup probe outcome.
 #[derive(Debug)]
 enum ProbeResult {
     Skipped,
@@ -32,7 +31,6 @@ enum ProbeResult {
 /// Unset while the query is in flight (or never sent).
 static XTVERSION: OnceLock<ProbeResult> = OnceLock::new();
 
-/// True once the query bytes were written to the terminal.
 static QUERY_SENT: AtomicBool = AtomicBool::new(false);
 
 /// XTVERSION query alone — no DA1 sentinel: nothing waits on reply
@@ -122,7 +120,6 @@ fn send_query() {
     let _ = XTVERSION.set(ProbeResult::Skipped);
 }
 
-/// Strip controls and trim; `None` for an empty payload.
 fn sanitize_payload(payload: &str) -> Option<String> {
     let cleaned: String = payload.chars().filter(|c| !c.is_control()).collect();
     let cleaned = cleaned.trim().to_owned();
@@ -183,12 +180,10 @@ mod tests {
                 gate_allows_probe(&ctx(brand, MultiplexerKind::Undetected)),
                 "{brand:?} should be probed"
             );
-            // Transparent mux (cmux) does not intercept CSI; probe still runs.
             assert!(
                 gate_allows_probe(&ctx(brand, MultiplexerKind::Cmux)),
                 "{brand:?} under cmux should still be probed"
             );
-            // CSI-intercepting multiplexers override the brand allowlist.
             assert!(
                 !gate_allows_probe(&ctx(brand, MultiplexerKind::Tmux)),
                 "{brand:?} under tmux should be skipped"