diff --git a/examples/gen-grammar.rs b/examples/gen-grammar.rs
index 18c65b5a..2809f0f5 100644
--- a/examples/gen-grammar.rs
+++ b/examples/gen-grammar.rs
@@ -1,21 +1,8 @@
-//! Generate a random valid example matching a rule from `improv.pest`.
-//!
-//! Usage:
-//!   cargo run --example gen-grammar -- <rule_name>
-//!
-//! Examples:
-//!   cargo run --example gen-grammar -- file
-//!   cargo run --example gen-grammar -- category_section
-//!   cargo run --example gen-grammar -- bare_name
-//!
-//! Each invocation generates one example seeded from the current time + PID.
-//!
-//! The generator adds constraints beyond what the grammar requires to produce
-//! realistic, round-trippable output:
-//! - bare names are drawn from a word pool instead of random letters
-//! - pipe_inner is never empty
-//! - rest_of_line always produces at least one character
-//! - repetitions (`*`) produce 1–4 items, not 0
+//! `cargo run --example gen-grammar -- <rule_name>` — one random valid example
+//! of a rule from `improv.pest`, seeded from the current time + PID.
+
+// The generator constrains the grammar to produce realistic, round-trippable
+// output rather than degenerate minima — `context/test-evidence/tui.md`.
 
 use pest_meta::ast::{Expr, RuleType};
 use pest_meta::parser;
diff --git a/examples/pretty-print.rs b/examples/pretty-print.rs
index a0ceacb7..97393c89 100644
--- a/examples/pretty-print.rs
+++ b/examples/pretty-print.rs
@@ -1,8 +1,5 @@
-//! Parse a `.improv` file from stdin and print the formatted result to stdout.
-//!
-//! Usage:
-//!   cargo run --example pretty-print < file.improv
-//!   cargo run --example gen-grammar -- file | cargo run --example pretty-print
+//! Parse a `.improv` file from stdin and print the formatted result to stdout:
+//! `cargo run --example pretty-print < file.improv`.
 
 use std::io::Read;
 
diff --git a/src/ui/formula_panel.rs b/src/ui/formula_panel.rs
index 9b601abe..6dcb7fab 100644
--- a/src/ui/formula_panel.rs
+++ b/src/ui/formula_panel.rs
@@ -102,9 +102,8 @@ mod tests {
         app
     }
 
-    /// The panel used to read `model.formulas()[i].raw` straight off the
-    /// model (improvise-35e); it now reads `FormulaCache::formulas`. The
-    /// cache must carry the same strings in the same order.
+    /// `FormulaCache::formulas` must carry what `model.formulas()[i].raw`
+    /// carried (improvise-35e) — `context/test-evidence/tui.md`.
     #[test]
     fn the_cache_carries_what_the_widget_used_to_read_off_the_model() {
         let app = app_with_formulas();
diff --git a/src/ui/panel.rs b/src/ui/panel.rs
index 89b8223e..e526c9d4 100644
--- a/src/ui/panel.rs
+++ b/src/ui/panel.rs
@@ -9,9 +9,8 @@ use crate::ui::app::{AppMode, Panel as PanelKind};
 
 /// Trait for panel-specific content. Implement this to create a new side panel.
 pub trait PanelContent {
-    /// Which panel this content renders. The widget compares it against
-    /// `AppMode::panel()` to decide whether to draw the panel as active, so
-    /// each impl declares its identity instead of restating the mode match.
+    /// Which panel this content renders. Compared against `AppMode::panel()`,
+    /// so no impl restates the mode match.
     fn panel(&self) -> PanelKind;
     /// Color used for the active border AND the selection highlight background.
     fn active_color(&self) -> Color;
diff --git a/src/ui/tile_bar.rs b/src/ui/tile_bar.rs
index ef0b0131..fe1694aa 100644
--- a/src/ui/tile_bar.rs
+++ b/src/ui/tile_bar.rs
@@ -64,9 +64,8 @@ impl<'a> Widget for TileBar<'a> {
         // Available space for tiles (after prefix)
         let avail = area.width.saturating_sub(prefix_w);
 
-        // Find the minimal starting index so the selected tile is fully visible.
-        // We scroll by whole tiles: find the first tile to draw such that the
-        // selected tile fits within the available width.
+        // Scroll by whole tiles: the smallest start index at which the
+        // selected tile still fits in `avail`.
         let sel = selected_cat_idx.unwrap_or(0);
         let mut start = 0;
         loop {
@@ -181,10 +180,8 @@ mod tests {
             .join("\n")
     }
 
-    /// The tile bar used to read `view.tileable_cats(&model.category_names())`
-    /// and `view.axis_of(cat)` off the model directly (improvise-35e). It now
-    /// reads a `TileBarCache`, so the cache must carry exactly those pairs — a
-    /// divergence here is a rendering change nobody asked for.
+    /// The cache must carry exactly the pairs the widget used to read off the
+    /// model (improvise-35e) — `context/test-evidence/tui.md`.
     #[test]
     fn the_cache_carries_what_the_widget_used_to_read_off_the_model() {
         let app = app_with_two_categories();
diff --git a/src/ui/view_panel.rs b/src/ui/view_panel.rs
index 896e8859..1e9560c0 100644
--- a/src/ui/view_panel.rs
+++ b/src/ui/view_panel.rs
@@ -11,9 +11,8 @@ use crate::view::Axis;
 
 pub struct ViewContent<'a> {
     views: &'a ViewListCache,
-    /// Which view this client is on. Read off `ViewState`, not the workbook:
-    /// the active view is per-client and is deliberately absent from
-    /// `ViewListCache` (improvise-8uz).
+    /// Which view this client is on. Read off `ViewState`, not the workbook —
+    /// per-client, and deliberately absent from `ViewListCache` (improvise-8uz).
     active_view: &'a str,
 }
 
@@ -121,10 +120,8 @@ mod tests {
         app
     }
 
-    /// The axis summary used to be built from `workbook.views` plus
-    /// `View::categories_on` (improvise-35e); it is now built from
-    /// `ViewSummary::axes`. Same names, same order, same virtual-category
-    /// filtering — this asserts the two agree on a real workbook.
+    /// `ViewSummary::axes` must reproduce what `View::categories_on` built
+    /// (improvise-35e) — `context/test-evidence/tui.md`.
     #[test]
     fn the_cache_reproduces_the_summary_the_widget_used_to_build() {
         let app = app_with_two_views();