docs/IRIS.md: it is the log of how iris is being built, not an API changelog

Iris, 2026-09-08: 'any major additions or design things should be added
there, not just public API stuff. You may as well remove the public API
bit at this point.' Widened the header, pointed AGENTS.md at the new
scope, and added the design point behind the scroll bug -- a cached
measurement needs its own value for 'not measured yet'.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

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

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