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-ratatui-inline/src/common.rs

@@ -28,7 +28,6 @@ pub trait TerminalLike {
     /// Reset the back buffer without clearing the screen
     fn reset_back_buffer(&mut self);
 
-    /// Set the viewport area
     fn set_viewport_area(&mut self, area: Rect);
 
     /// Get a mutable reference to the writer

crates/codegen/kigi-ratatui-inline/src/resize.rs

@@ -55,7 +55,8 @@ pub fn resize_purge_rerender<T: TerminalLike>(terminal: &mut T, history: &str) -
         .as_bytes()
         .iter()
         .filter(|&&c| c == b'\n')
-        .take(size.height.into()) // Only count up to screen height for efficiency
+        // Only count up to screen height for efficiency
+        .take(size.height.into())
         .count() as u16;
 
     // Re-output the entire scrollback history
@@ -191,14 +192,16 @@ mod tests {
     #[test]
     fn test_viewport_resize_shrink() {
         let mut terminal = MockTerminal::new(80, 25, 5);
-        let original_y = terminal.viewport_area.y; // Should be 20 (25-5)
+        // Should be 20 (25-5)
+        let original_y = terminal.viewport_area.y;
 
         // Shrink viewport from 5 to 3 (always anchors at top)
         resize_viewport_height(&mut terminal, 3).unwrap();
 
-        // Check viewport was updated - y should stay the same
+        // Check viewport reflects resize - y should stay the same
         assert_eq!(terminal.viewport_area.height, 3);
-        assert_eq!(terminal.viewport_area.y, original_y); // Should still be 20
+        // Should still be 20
+        assert_eq!(terminal.viewport_area.y, original_y);
 
         // Should have cleared once
         assert_eq!(terminal.clear_count, 1);
@@ -216,13 +219,14 @@ mod tests {
 
         // Check that it expanded down (kept same y)
         assert_eq!(terminal.viewport_area.height, 5);
-        assert_eq!(terminal.viewport_area.y, 20); // Should stay at 20
+        // Should stay at 20
+        assert_eq!(terminal.viewport_area.y, 20);
         assert_eq!(terminal.clear_count, 1);
 
-        // Now expand more - should hit bottom and push content up
         resize_viewport_height(&mut terminal, 6).unwrap();
         assert_eq!(terminal.viewport_area.height, 6);
-        assert_eq!(terminal.viewport_area.y, 19); // Should move up to 19
+        // Should move up to 19
+        assert_eq!(terminal.viewport_area.y, 19);
         assert_eq!(terminal.clear_count, 2);
     }
 
@@ -255,7 +259,8 @@ mod tests {
     #[test]
     fn test_resize_purge_rerender_empty_history() {
         let mut terminal = MockTerminal::new(80, 25, 3);
-        terminal.viewport_area.y = 22; // Bottom position
+        // Bottom position
+        terminal.viewport_area.y = 22;
 
         // Test with empty history
         resize_purge_rerender(&mut terminal, "").unwrap();
@@ -269,7 +274,8 @@ mod tests {
     #[test]
     fn test_resize_purge_rerender_small_history() {
         let mut terminal = MockTerminal::new(80, 25, 3);
-        terminal.viewport_area.y = 22; // Bottom position
+        // Bottom position
+        terminal.viewport_area.y = 22;
 
         // Test with small history (just a few lines)
         let history = "Line 1\r\nLine 2\r\nLine 3\r\n";
@@ -285,7 +291,8 @@ mod tests {
     #[test]
     fn test_resize_purge_rerender_full_screen_history() {
         let mut terminal = MockTerminal::new(80, 25, 3);
-        terminal.viewport_area.y = 22; // Bottom position
+        // Bottom position
+        terminal.viewport_area.y = 22;
 
         // Create history with more lines than screen height
         let mut history = String::new();
@@ -296,18 +303,21 @@ mod tests {
         resize_purge_rerender(&mut terminal, &history).unwrap();
 
         // With full screen of content, viewport should be at bottom
-        assert_eq!(terminal.viewport_area.y, 25 - 3); // screen_height - viewport_height
+        // screen_height - viewport_height
+        assert_eq!(terminal.viewport_area.y, 25 - 3);
         assert_eq!(terminal.viewport_area.height, 3);
         assert_eq!(terminal.clear_count, 1);
     }
 
     #[test]
     fn test_resize_purge_rerender_with_wrapped_lines() {
-        let mut terminal = MockTerminal::new(40, 10, 2); // Narrow terminal
+        // Narrow terminal
+        let mut terminal = MockTerminal::new(40, 10, 2);
         terminal.viewport_area.y = 8;
 
         // Create a line that will wrap
-        let long_line = "A".repeat(100); // Will wrap to ~3 lines on 40-column terminal
+        // Will wrap to ~3 lines on 40-column terminal
+        let long_line = "A".repeat(100);
         let history = format!("{}\r\nShort line\r\n", long_line);
 
         resize_purge_rerender(&mut terminal, &history).unwrap();

crates/codegen/kigi-ratatui-inline/src/scrollback.rs

@@ -38,10 +38,10 @@ pub fn emit_to_scrollback<T: TerminalLike>(terminal: &mut T, content: &str) -> i
         Print(ANSI_CLEAR_FROM_CURSOR_DOWN),
     )?;
 
-    // Now print the content
     queue!(MoveTo(0, viewport_area.y))?;
     for segment in &segments {
-        queue!(Print(segment))?; // this already includes crlfs if there's any
+        // this already includes crlfs if there's any
+        queue!(Print(segment))?;
     }
 
     // Create exact viewport space
@@ -174,7 +174,8 @@ mod tests {
         assert_eq!(terminal.writer.flush_count, 1);
 
         // Viewport should remain at bottom
-        assert_eq!(terminal.viewport_area.y, 22); // 25 - 3
+        // 25 - 3
+        assert_eq!(terminal.viewport_area.y, 22);
     }
 
     #[test]

crates/codegen/kigi-ratatui-inline/src/segment.rs

@@ -156,7 +156,8 @@ pub fn split_into_line_segments<'a>(input: &'a str, term_width: usize) -> Vec<Li
                     push_segment!(segment_end, false);
                     segment_start = segment_end;
                     segment_end += char_bytes;
-                    visual_width = char_width; // Reset to just this character's width
+                    // Reset to just this character's width
+                    visual_width = char_width;
                     has_visual = true;
                     // Very unlikely edge case: char_width > term size and we have to flush it again
                     if char_width > term_width {
@@ -316,7 +317,8 @@ mod tests {
 
     #[test]
     fn test_wrap_at_exact_width() {
-        let input = "12345678"; // exactly 8 chars
+        // exactly 8 chars
+        let input = "12345678";
         let segments = split_into_line_segments(input, 8);
         assert_eq!(segments.len(), 1);
         assert_eq!(segments[0].content, "12345678");
@@ -364,9 +366,11 @@ mod tests {
         // "你好" is 4 visual width (2 per character)
         let input = "hello 你好";
         let segments = split_into_line_segments(input, 10);
-        assert_eq!(segments.len(), 1); // "hello 你好" = 6 + 4 = 10, exactly fits
+        // "hello 你好" = 6 + 4 = 10, exactly fits
+        assert_eq!(segments.len(), 1);
 
         let segments2 = split_into_line_segments(input, 9);
-        assert_eq!(segments2.len(), 2); // Doesn't fit, must wrap
+        // Doesn't fit, must wrap
+        assert_eq!(segments2.len(), 2);
     }
 }

crates/codegen/kigi-ratatui-inline/src/terminal.rs

@@ -88,6 +88,11 @@ pub struct OurFrame<'a> {
     pub(crate) count: usize,
 }
 
+// `OurFrame` mirrors ratatui's `Frame` field for field so that construction
+// is possible at all: every `Frame` field is private to ratatui. The
+// transmute is sound only while the two layouts stay identical, which the
+// size assertion checks weakly — a field reorder of equal-sized fields would
+// slip through, so re-verify these against ratatui on every version bump.
 impl<'a> From<OurFrame<'a>> for Frame<'a> {
     fn from(value: OurFrame<'a>) -> Self {
         assert_eq!(
@@ -167,7 +172,6 @@ where
     current: usize,
     /// Whether the cursor is currently hidden
     hidden_cursor: bool,
-    /// Viewport
     viewport: Viewport,
     /// Area of the viewport
     viewport_area: Rect,
@@ -278,7 +282,7 @@ where
             buffer: self.current_buffer_mut(),
             count,
         }
-        .into() // HACK
+        .into()
     }
 
     /// Gets the current buffer as a mutable reference.
@@ -955,14 +959,14 @@ where
             buffer_height -= to_draw;
         }
 
-        // There is now enough room on the screen for the remaining buffer plus the viewport,
+        // There is enough room on the screen for the remaining buffer plus the viewport,
         // though we may still need to scroll up some of the existing text first. It's possible
         // that by this point we've drained the buffer, but we may still need to scroll up to make
         // room for the viewport.
         //
         // We want to scroll up the exact amount that will leave us completely filling the screen.
         // However, it's possible that the viewport didn't start on the bottom of the screen and
-        // the added lines weren't enough to push it all the way to the bottom. We deal with this
+        // the extra lines weren't enough to push it all the way to the bottom. We deal with this
         // case by just ensuring that our scroll amount is non-negative.
         //
         // We want:
@@ -1165,8 +1169,8 @@ fn diff_large<'a>(prev: &Buffer, next: &'a Buffer) -> Vec<(u16, u16, &'a Cell)>
     updates
 }
 
-/// Like [`diff_large`] but a cell is also considered changed when its hyperlink
-/// changed between the previous and current frame (even if the glyph/style is
+/// Like [`diff_large`] but a cell is also considered dirty when its hyperlink
+/// differs between the prior and current frame (even if the glyph/style is
 /// identical). This is what makes OSC 8 links participate in the frame diff:
 /// adding, removing, or retargeting a link forces the affected cells to be
 /// rewritten so the terminal's link state stays in sync.
@@ -1301,7 +1305,7 @@ fn compute_inline_size<B: Backend>(
 }
 
 impl<B: Backend> Terminal<B> {
-    /// HACK: this is added
+    /// HACK: this exists
     pub fn viewport_area(&self) -> Rect {
         self.viewport_area
     }
@@ -1378,7 +1382,7 @@ mod inline_resize_tests {
     }
 
     /// Shrinking must also track the terminal and must not position the viewport
-    /// off-screen (which previously panicked the strict `TestBackend` buffer and
+    /// off-screen (which earlier panicked the strict `TestBackend` buffer and
     /// would leave a real terminal's UI invisible/garbled).
     #[test]
     fn inline_full_height_shrinks_with_terminal() {

crates/codegen/kigi-ratatui-inline/src/tests.rs

@@ -227,7 +227,7 @@ mod links {
         // A small inline viewport near the bottom of the screen, grown to full
         // height, must scroll the rows it will cover up into native scrollback
         // (append_lines) instead of overwriting them. Regression guard for the
-        // previously-commented-out scroll_up in set_viewport_height's grow path
+        // earlier-commented-out scroll_up in set_viewport_height's grow path
         // (the overlay host depends on this in minimal mode).
         let mut t = Terminal::with_options(
             RecordingBackend::default(),