diff --git a/AGENTS.md b/AGENTS.md
index 08b18d9..2bddd42 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -72,9 +72,10 @@ Module-by-module intent is in `docs/PLAN.md`'s "Backend layout".
     conditions. Read it before touching anything under that branch.
   - `docs/IRIS.md`, `docs/IRIS_TODO.md`, `docs/DECISIONS.md`,
     `docs/LAYOUT.md`, `docs/TEXTURES.md`, `docs/CLIENT_CORE.md` — iris's
-    own public API log, working list, decisions log, layout/render design,
-    and texture-atlas design, and the client-core crate's design,
-    respectively.
+    own build log (**any major addition or design decision, not only
+    public API** -- Iris, 2026-09-08), working list, decisions log,
+    layout/render design, and texture-atlas design, and the client-core
+    crate's design, respectively.
 - `.dev-updater.ron` — what Dev Updater builds here: the server (run as
   `service: Managed(…)`, supervised by Dev Updater's own implementation
   rather than a script kept here) and the APK, in parallel. It points at
diff --git a/docs/IRIS.md b/docs/IRIS.md
index 23ca1c3..34625c3 100644
--- a/docs/IRIS.md
+++ b/docs/IRIS.md
@@ -1,9 +1,13 @@
-# iris: notable public API changes
+# iris: the log of how it is being built
 
-For Iris to read on her own time. Each entry is a change to iris's public
-surface that a widget author or app author would notice: a trait method
-added, removed or re-shaped; a type that callers construct differently; a
-capability that moved. Small and trivial changes do not go here.
+For Iris to read on her own time. An entry is anything **major**: a new
+capability or widget, a design decision and what it was chosen over, a
+mechanism that changed shape, a defect whose root cause says something
+about the framework -- and the public-surface changes a widget or app
+author would notice, which is all this file used to hold (widened on
+Iris's instruction, 2026-09-08: "any major additions or design things
+should be added there, not just public API stuff"). Small and trivial
+things still stay out.
 
 An entry gives the date, what changed, why, and a short before/after where
 it helps judge the change without the session that made it. Newest first.
@@ -65,6 +69,17 @@ what everything did before. A code fence was opening at the end of its
 longest line, in the middle of a word. `Scroll::new` takes the edge as a
 third argument rather than deciding for its caller.
 
+The design point behind that bug is worth more than the bug: `Scroll`
+held its content's length as an `f32` that was `0.0` both for "there is
+nothing here" and for "I have not drawn yet". Those lead somewhere
+different, and the code could not ask which it had -- so the first
+frame's clamp computed a scroll range of zero, read `amt == len` as
+"sitting at the end", and pinned itself there. It is an `Option` now,
+and the clamp declines to answer a question it cannot yet answer. Any
+measurement iris caches from a previous frame has this shape (LAYOUT.md
+section 4's one-frame lag is the general case), so the rule is: give the
+unmeasured state its own value, not a plausible number.
+
 ## 2026-09-08: masks have a shape -- `.masked_by(shape)`, and clipping applies to touch
 
 A mask no longer carries a rectangle. It carries **the slot of a