re: finish the --help audit -- a stale percentage and a missing noun, both shipped

The METHOD entry I wrote an hour ago says to read your tool's own --help as if a
stranger wrote it. I had done that for ONE of sixteen leaf commands, which is the
"a rule written down is not a rule applied" failure this corpus already records
twice. Finished it across the whole surface.

One survivor, and it fails in two ways at once. `screen render --settle` said a
narrow window means the bundle never settles, "(42 % of them, mostly loop*
fragments)".

MISSING NOUN: inside `screen render`, "them" reads as the builds you would render.
The 42 % is over composable bundles -- a different and much larger set including
~1 700 two-element fragments a user of that flag never renders. ui-settle-time.md
states its population precisely; the help inherited the number without it.

STALE: recomputed under the corrected reader, the composable figure is 862/2211 =
39 %, not 731/1758 = 42 %. The POPULATION GREW BY 453, which is the keyframe
record-layout fix's signature -- it times a group's final pose, so bundles that
previously showed one timed keyframe now show two and qualify. Third consequence
of that fix not being swept, after fade_quads.py and screen-transitions.md's
0.87-4.08 s fade-in.

And the share a --settle user actually faces is 38 %: 185 of 491 screen builds.

Corrected in the help text with all three numbers and their populations, and in
ui-settle-time.md, whose three-row table is marked pre-fix and superseded rather
than edited in place. Verified by artifact -- the tool's --help output is quoted,
not merely recompiled.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Wuu56cE8vJGTBtn1ppsk8v

crates/sylpheed-cli/src/main.rs

@@ -213,9 +213,15 @@ enum ScreenCommands {
         /// Pose every element at the instant the screen is SETTLED, derived from
         /// the disc: the midpoint of the longest interval containing no keyframe
         /// of any element. Prints the window it used, whose width is how much the
-        /// midpoint is worth — a narrow one means the bundle never settles (42 %
+        /// midpoint is worth — a narrow one means the bundle never settles.
-        /// of them, mostly `loop*` fragments). ⚠️ NOT established as better than the
+        /// ⚠️ That is **38 % of the screen builds this command renders** (185 of
-        /// resting pose — see the note on `--at`. See
+        /// 491 carrying two or more keyframe times) and 39 % of the wider set
+        /// `--all` admits (862 of 2 211), mostly `loop*` fragments. This help used
+        /// to say "42 % of them" without saying of WHAT: 42 % was 731/1 758 over
+        /// composable bundles, computed before the keyframe record-layout fix,
+        /// which times a group's final pose and so admits ~450 bundles that
+        /// previously had only one timed keyframe. ⚠️ NOT established as better
+        /// than the resting pose — see the note on `--at`. See
         /// `docs/re/structures/ui-settle-time.md`.
         #[arg(long)]
         settle: bool,

crates/sylpheed-formats/examples/settle_narrow_rate.rs

@@ -0,0 +1,49 @@
+//! What share of bundles have a NARROW settle window -- and of WHICH bundles?
+//!
+//! `screen render --settle`'s help says "a narrow one means the bundle never
+//! settles (42 % of them, mostly `loop*` fragments)". The 42 % is correct and is
+//! stated precisely in ui-settle-time.md: 731 of **1 758 composable bundles
+//! carrying two or more keyframe times**. But inside `screen render`, "them"
+//! reads as the bundles you would render -- the SCREEN BUILDS -- which is a
+//! different and much smaller population. This computes both.
+//!
+//!     cargo run -p sylpheed-formats --example settle_narrow_rate
+use sylpheed_formats::{pak::PakArchive, ui_layout};
+use std::path::PathBuf;
+
+fn main() {
+    let root = PathBuf::from(std::env::var("SYLPHEED_DISC").expect("SYLPHEED_DISC"));
+    let mut paks: Vec<PathBuf> = std::fs::read_dir(root.join("dat")).expect("dat/")
+        .filter_map(|e| e.ok().map(|e| e.path()))
+        .filter(|p| p.extension().is_some_and(|x| x == "pak")).collect();
+    paks.sort();
+    // (with >=2 keyframe times, narrow) for each population
+    let (mut b2, mut bn) = (0usize, 0usize);   // screen builds  (is_build)
+    let (mut c2, mut cn) = (0usize, 0usize);   // composable      (is_composable)
+    for pak in &paks {
+        let Ok(ar) = PakArchive::open(pak) else { continue };
+        for e in ar.entries() {
+            let Ok(by) = ar.read(e) else { continue };
+            let is_b = ui_layout::is_build(&by);
+            let is_c = ui_layout::is_composable(&by);
+            if !is_b && !is_c { continue }
+            let Some(b) = ui_layout::parse_build(&by) else { continue };
+            let mut ts: Vec<u32> = b.elements.iter()
+                .flat_map(|el| el.keyframes.iter().filter_map(|k| k.time)).collect();
+            ts.sort_unstable(); ts.dedup();
+            if ts.len() < 2 { continue }
+            let narrow = match b.settle_window() { Some((lo, hi)) => hi - lo < 10, None => true };
+            if is_b { b2 += 1; if narrow { bn += 1 } }
+            if is_c { c2 += 1; if narrow { cn += 1 } }
+        }
+    }
+    println!("population                                        n     narrow (<10 u)   share");
+    println!("SCREEN BUILDS (is_build, what `screen render` renders by default)");
+    println!("                                              {b2:5}   {bn:9}      {:.0} %",
+             100.0 * bn as f64 / b2.max(1) as f64);
+    println!("COMPOSABLE bundles (is_composable, what --all admits)");
+    println!("                                              {c2:5}   {cn:9}      {:.0} %",
+             100.0 * cn as f64 / c2.max(1) as f64);
+    println!("\nui-settle-time.md quotes 731 / 1758 = 42 % over composable bundles.");
+    println!("--- END ---");
+}

docs/re/data/settle-narrow-rate.txt

@@ -0,0 +1,20 @@
+# Narrow settle windows: what share, and OF WHAT. 2026-08-30.
+# instrument: crates/sylpheed-formats/examples/settle_narrow_rate.rs
+# Found by auditing sylpheed-cli's own --help against what the corpus
+# establishes -- the audit METHOD gained an hour earlier, applied to the
+# remaining 15 leaf commands rather than the one that prompted it.
+
+population                                        n     narrow (<10 u)   share
+SCREEN BUILDS (is_build, what `screen render` renders by default)
+                                                491         185      38 %
+COMPOSABLE bundles (is_composable, what --all admits)
+                                               2211         862      39 %
+
+ui-settle-time.md quotes 731 / 1758 = 42 % over composable bundles.
+--- END ---
+
+# The pre-fix figure was 731/1758 = 42 %. The population grew by 453 because
+# the keyframe record-layout fix times a group's FINAL pose, so bundles that
+# previously showed one timed keyframe now show two and qualify.
+# 🔴 Third consequence of that fix not being swept, after fade_quads.py and
+# screen-transitions.md's 0.87-4.08 s fade-in.

docs/re/structures/ui-settle-time.md

@@ -127,7 +127,25 @@ Of the **1 758** composable bundles carrying two or more keyframe times:
 | settle window < 10 units | 731 | 42 % |
 | mean window | 49 units | — |
 
-The 42 % are mostly `loop*` animation fragments, which are **meant** to be in
+🔴 **These three rows are PRE-FIX and are superseded (2026-08-30).** They were
+computed before the keyframe record-layout fix, which times a group's **final**
+pose — so bundles that previously showed one timed keyframe now show two and enter
+the population. Recomputed under the corrected reader
+([`data/settle-narrow-rate.txt`](../data/settle-narrow-rate.txt)):
+
+| population, ≥2 keyframe times | n | narrow (<10 u) | share |
+|---|---|---|---|
+| **screen builds** (`is_build` — what `screen render` renders) | 491 | 185 | **38 %** |
+| composable bundles (`is_composable` — what `--all` admits) | **2 211** | 862 | **39 %** |
+| *the pre-fix figures above* | *1 758* | *731* | *42 %* |
+
+⚠️ The **population grew by 453**, which is the fix's signature and the reason the
+share moved. And the share a user of `--settle` actually faces is **38 %**, over
+screen builds — not 42 % over a wider set that includes ~1 700 fragments they will
+never render. The tool's own help said "42 % of them" without saying of *what*;
+corrected there too.
+
+The narrow ones are mostly `loop*` animation fragments, which are **meant** to be in
 motion and have no settled pose to find. **Check the window width before trusting
 the midpoint.** A narrow window is the data saying "this bundle never settles",
 not a settle time with a small error bar.