spine-rigc 0.4.0 → 0.6.0

package/docs/AUTHORING.md

@@ -29,22 +29,27 @@ that can see that, and a run that skips it has verified nothing about the motion
   attachment, keying practice, curve kind, draw order — sourced from Spine's own
   public documentation: **§10**
 
+If you were given no brief and no reference frames, this section does not apply to
+you — skip to **§0**. You are rigging somebody's own art rather than reproducing a
+measured shot, so none of what follows applies: it is the ladder's protocol, not a
+property of the tool.
+
 🔒 **A ladder run reads this guide in full and does not follow its references out of
 it.** The guide is allowed reading; not everything it cites is. Citations here are
 provenance for a reader of record — the loop that hit a trap, the issue that closed it —
 and following one can arrive at a stored candidate's own spec, at the corpus inventory,
-or at the gate a verdict is read against, none of which a run may open. So: read the
+or at the **derivation** of the gate a verdict is read against, none of which a run may
+open. ⭐ The gate's **clause statements** are a different matter and a run may read them:
+they are in `docs/GATE.md`, item 11 of the allowed list (owner ruling 2026-08-29) — the
+measure, the comparator, the number and the SKIP semantics, with no recorded figure in it.
+So: read the
 document, take its numbered sections as the input, and leave its footprints to whoever
 is maintaining it. The rule this states is that an **allowed-reading surface has to be
 closed under reading**; the criterion behind it is under *The honesty rule* in
-[LADDER.md](LADDER.md), and the enumerated allowed and forbidden lists are in
+[LADDER.md](https://github.com/firejune/rigc/blob/main/docs/LADDER.md), and the enumerated allowed and forbidden lists are in
 `bench/runs/README.md`, *What a run may read* — the prompt that starts a run quotes them
 outright, which is the copy that binds.
 
-If you were given no brief and no frames — you are rigging somebody's own art rather
-than reproducing a measured shot — none of this applies to you. It is the ladder's
-protocol, not a property of the tool.
-
 ## The vocabulary is Spine's
 
 Wherever rigc has no better abstraction it uses **Spine 4.3's own concept, its own
@@ -80,6 +85,10 @@ bun cli.ts check \
 
 # read the table → fix the spec → build again → check again
 #   ↳ read its per-frame column before its MAE — §9.2
+
+# …and if nobody gave you frames, LOOK at it instead — neither needs a reference:
+bun cli.ts render  --candidate path/to/spine    # PNG frames + a contact sheet grid
+bun cli.ts preview --candidate path/to/spine    # one .html that plays it in Spine's own player
 ```
 
 `build` compiles, round-trips the result through `@esotericsoftware/spine-core`,
@@ -112,16 +121,26 @@ What the flags mean:
 | `--rig` | the rig spec — skeleton structure |
 | `--motion` | the motion spec — time |
 | `--out` | directory for `skeleton.json` + `skeleton.atlas`; atlas page paths are written relative to it |
+| `--copy-images` | `build` only: also copies every referenced page PNG into `--out` and rewrites the atlas to the copies, so the directory is self-contained enough to zip or commit on its own. Default is unchanged — page paths still point at the source art (issue #217) |
 | `--images` | where the rig spec's `image` names resolve (overrides the rig's own `images` field, and is relative to your working directory) |
 | `--manifest` | a cut manifest. Only for a rig with **measured art** behind it; a foreign skeleton has none |
-| `--profile` | `spine` = the 20 validity rules · `spine-html` = all 34 (**the default**) |
-
-Pick the profile deliberately. `spine-html` adds one renderer's policy and one
-project's canvas budget, and those rules fire on perfectly correct Spine data
-(clipping attachments, unweighted meshes, packed atlases). If what you are
-authoring is "valid Spine 4.3 that any runtime plays correctly", use
-`--profile spine`. A report always prints which profile ran and lists what that
-profile left out, on `PROF` lines.
+| `--profile` | `spine` = the 20 validity rules (**the default**) · `spine-html` = all 34, opt-in |
+| `--candidate` | `check`, `bench`, `render` and `preview` only: a **compiled** artifact — the directory `build --out` wrote, or a `skeleton.json` path. `--atlas <path>` names the atlas when it does not sit beside the skeleton |
+| `--animation` | `render` and `preview` only: which animation to show. The default is **every** one for `render` and the **first** for `preview`. A name the skeleton does not have is refused, with the ones it does have listed |
+
+`render` also takes `--fps <n>` (the rate it samples at, default 12 — the same
+protocol rate the reference frames use) and `--max <px>` (the long side of a
+frame, default 256). Both commands take `--out`: a directory for `render`
+(default `render/`), the `.html` file for `preview` (default `preview.html`).
+
+Pick the profile deliberately, and know which one you got by saying nothing. The
+default is `spine`: "is this valid Spine 4.3 that any runtime plays correctly",
+which is the question a rig authored anywhere is asking. `--profile spine-html`
+adds one renderer's policy and one project's canvas budget on top, and those
+extra rules fire on perfectly correct Spine data (clipping attachments,
+unweighted meshes, packed atlases) — reach for it when you are shipping into
+*that* project, not to be thorough. A report always prints which profile ran and
+lists what that profile left out, on `PROF` lines.
 
 The other commands:
 
@@ -131,6 +150,8 @@ bun cli.ts validate path/to/spine                # re-gate artifacts already on
 bun cli.ts diff     candidate.json reference.json
 bun cli.ts check    --candidate path/to/spine --frames path/to/frames
 bun cli.ts bench    3 --candidate path/to/spine [--frames path/to/frames]
+bun cli.ts render   --candidate path/to/spine [--animation …] [--fps 12] [--max 256]
+bun cli.ts preview  --candidate path/to/spine [--animation …] [--out preview.html]
 ```
 
 - **`explain`** is the one to reach for when a rig compiles but looks wrong. It
@@ -144,12 +165,26 @@ bun cli.ts bench    3 --candidate path/to/spine [--frames path/to/frames]
   for opposite fixes. A measure with nothing to compare says `0/0` and says so.
 - **`check`** renders your candidate into the reference frames' own pixel grid and
   compares pixels — the only thing here that can see a wrong animation. **§9.**
-- **`bench <rung>`** runs one rung of [the benchmark ladder](LADDER.md): validate
+- **`bench <rung>`** runs one rung of [the benchmark ladder](https://github.com/firejune/rigc/blob/main/docs/LADDER.md): validate
   under `--profile spine`, then diff against that rung's reference export, and with
   `--frames` the `check` table as well. Unlike the three above it is a **finish
   line, not a loop**: it opens the reference export, so a run that consults it and
   then edits is no longer an authoring run. `check` carries no such restriction —
   see §9.
+- 🚨 **`render` and `preview` are how you LOOK at what you built**, and they are
+  the two that need no reference at all. Reach for them the moment a rig compiles
+  green, because green says nothing about the picture: a head that sits visibly
+  off its torso passes every assertion, loads in `spine-core` and steps
+  numerically clean — the offsets are the ones you asked for, and nothing in the
+  gate can know you did not mean them. `render` writes
+  `render/<animation>/f0000.png…` with a `contact.png` grid of **every** frame
+  beside them (open that one first — spacing is a comparison across frames) and a
+  `frames.json` sidecar naming the world box they are pictures of. `preview`
+  writes one self-contained `.html`: your skeleton, atlas and page PNGs are
+  embedded in it as data URIs and played by the official **Spine Web Player**, so
+  double-clicking it is also the interop proof — what plays there was played by
+  Esoteric Software's runtime, not by rigc's. The player is loaded from a CDN
+  rather than copied into the file, so the first open needs a network.
 
 ---
 
@@ -294,7 +329,7 @@ must be non-empty. `slots` must be present (it may be empty).
 payloads in this guide are written to illustrate a field, never copied out of a
 reference export — an example lifted from one would be handing an authoring agent an
 answer to the rung it is standing on, which is the rule §10.6 states and the honesty
-rule in [LADDER.md](LADDER.md) turns on. If a snippet here matches a reference file,
+rule in [LADDER.md](https://github.com/firejune/rigc/blob/main/docs/LADDER.md) turns on. If a snippet here matches a reference file,
 that is a defect in this guide: report it. (It has happened — 2026-08-23; the incident
 is recorded in `bench/runs/README.md`, *What a run may read*.)
 
@@ -482,10 +517,10 @@ and takes every slot below it out of the frame. rigc refuses a name the rig does
 not declare. Omitting `end` entirely is the format's own way of saying "clip
 everything after this one", and is left alone.
 
-🚫 Under the default `spine-html` profile a clipping attachment is refused by
+🚫 Under `--profile spine-html` a clipping attachment is refused by
 `A11_NO_CLIPPING_ATTACHMENTS` — that renderer skips them silently, so a mask that
-was supposed to hide something would not. It is valid Spine and `--profile spine`
-accepts it; the refusal is policy, not validity.
+was supposed to hide something would not. It is valid Spine and the default
+`--profile spine` accepts it; the refusal is policy, not validity.
 
 ### 3.5 `constraints` — 4.3's single typed array
 
@@ -650,7 +685,7 @@ stepped.
   declared duration `6.5` never fired at all against an accumulated
   `6.499999999999994` — which read as a frame-change disagreement the pose series had
   already fixed, and cost that run three builds
-  ([`2026-08-26-rung5-1`](../bench/runs/2026-08-26-rung5-1/LOOP.md), §8). ⇒ **For a
+  ([`2026-08-26-rung5-1`](https://github.com/firejune/rigc/blob/main/bench/runs/2026-08-26-rung5-1/LOOP.md), §8). ⇒ **For a
   stepped timeline, write `T − 1e-6` rather than `T`.** One grid step early cannot
   reach the previous sample — 83,333 µs away at 12 fps — and is always seen by the
   sample it was written for; one ULP late loses the frame. This is the same asymmetry
@@ -867,7 +902,7 @@ The report prints one line per assertion:
 | `A16_SKELETON_VERSION_4_3` | both | the `skeleton.spine` label is not on the 4.3 line (`4.3`, `4.3.N`, `4.3.N-suffix`) |
 | `A17_ATLAS_PAGE_FILES_EXIST` | both | a page the atlas declares is not a file. Check `--images` and `--out` |
 | `A18_DETERMINISTIC_EMIT` | both | a second compile of the same inputs differed. That is a compiler bug, not a spec bug — report it |
-| `A19_OVERLAY_PNGS_HAVE_ALPHA` | renderer | an overlay page has a colour type with no alpha channel. Only the full-stage base plate may be opaque |
+| `A19_OVERLAY_PNGS_HAVE_ALPHA` | renderer | an overlay part image can never be transparent: no alpha channel (colour type 4 or 6) and no `tRNS` chunk either, so it would paint a solid rectangle over what is behind it. Re-export it as RGBA, or as an indexed / greyscale PNG that keeps its `tRNS`. Only the full-stage base plate may be opaque. Indexed-with-`tRNS` — the usual output of ImageMagick, "Export as PNG-8", GIMP's indexed mode, aseprite and pngquant — **passes**: it is transparent art |
 | `A20_MESH_WEIGHTS_COHERENT` | both ◑ | a weighted vertex with no bone, a negative weight, a bone index out of range, or weights that do not sum to 1. Under `spine-html` also: an unweighted mesh, or a binding at weight 0 |
 | `A21_MESH_RIM_PINNED` | archetype | a generated ring's rim, or a ribbon's entry row, is not pinned to its anchor bone at weight 1 |
 | `A22_MESH_UVS_IN_UNIT_RANGE` | both | a mesh UV outside its region, or a UV array that disagrees with the vertex count |
@@ -922,6 +957,8 @@ Two more limits that are not errors but will shape what you can attempt:
 ## 7. Before you call it done
 
 1. `build --profile <the one you meant>` exits 0 and the report has **no FAIL**.
+   Saying nothing means `spine`, so "the one you meant" is a decision either way —
+   the report's first line names the profile that judged it.
 2. Read the `SKIP` lines. Each one is a check that did *not* run — make sure none of
    them is a check you were relying on.
    ⚠️ Under `--profile spine` a foreign skeleton usually produces **no SKIP lines
@@ -1022,6 +1059,34 @@ gone by construction, and the reading needs no knowledge of which parts are invo
 beside the figure too, because an edge the frames really decide wins shot after shot
 rather than on a couple of them.
 
+⭐ **That dilution has a *temporal* cousin, and it bites inside a single shot's own
+per-frame fit.** The paragraph above is about two builds and a whole-shot figure; this is
+about one build and a whole-*figure* objective. Where a passage's motion is **a small
+part moving against a large, nearly still body** — a hand, a head, a prop, while
+everything else holds — the moving part is a tiny share of the ink, so a whole-figure
+score is dominated by the still majority. Every frame then reports a good number
+*individually*, the fit converges, and the passage comes out **static**: the mover was
+never worth enough of the objective to pull the search toward it.
+
+⚠️ **Nothing else in the loop catches this.** The MAE is fine, the drift is fine on every
+part that is not moving, and `validate` and `diff` never look at a rendered frame. What
+does see it is §10.3's change column, in its **under-change** direction — and by the time
+it tells you, the poses are already wrong, because a key plan cannot add motion the poses
+do not have.
+
+⇒ **Weight the objective by the reference's own frame-to-frame change.** Build a mask
+from where the reference *changes* between the two frames bracketing the one you are
+fitting, and weight the score by it — so the pixels that carry the passage's motion carry
+the passage's objective. It costs one extra difference per frame, needs nothing but the
+frames, and it turns an untrackable passage into an ordinary one.
+
+📌 **Read the mask itself before you trust the fit, because it also tells you what is
+actually moving** — which is frequently not what the shot looks like it is about. A
+passage that reads as one limb waving can turn out to carry most of its change somewhere
+else entirely (a body-wide micro-rocking, a shadow, a trailing part), and a fitter aimed
+at the limb would have been chasing the minority of the evidence. The mask is the cheap
+way to find that out first.
+
 **Calibrate the band with a control on an edge the brief has already settled by
 measurement.** Run the same test on that edge, read how far apart the two builds
 come out over the pixels that decide it, and treat that separation as the scale a
@@ -1210,6 +1275,26 @@ of the chain in question**, never a whole foreign pose: a foreign pose puts the
 where this shot never goes, and the rest of the search then spends itself fighting
 what the borrow brought with it.
 
+🚨 **Before you fit a chain at all, check that it can *reach* the extremes the shot
+visits — a reach deficit is invisible to every per-frame fit.** This is the precondition
+the borrow rule assumes and the loop does not check. If a chain's segment lengths are
+short — read off a pose where the chain is **folded**, which is the easiest reading to
+take and the one most likely to be wrong — then every frame where the chain is folded
+fits beautifully, and the fitter *silently absorbs* the deficit on every other frame by
+rotating the parts it does have. Nothing reports a failure. The number is merely a little
+worse everywhere, which reads like an ordinary residual, until a passage needs the full
+extension and then no start converges anywhere near it — and multi-start does not help,
+because the pose being searched for is **outside the chain's reachable set**.
+
+⇒ **The check is arithmetic and needs no fit.** Take the chain's total reach from your own
+rig; take the longest excursion the shot's own frames show that chain's end travelling —
+a pendulum's full swing, a limb's extreme, a prop's sweep — and compare. If the shot asks
+for markedly more than the chain has, the rig is wrong and no amount of searching will say
+so. ⭐ **A frames-side reading beats a rig-side one here**: the shot's own extremes are a
+measurement, while segment lengths taken off a folded pose are an estimate — so when they
+disagree, suspect the estimate. And do this **per chain, before its first fit**, because
+the surgery to fix it invalidates every pose already fitted with the short chain.
+
 **Re-fit the setup pose against frames drawn from every shot, not against one.** Every
 animation is measured from the setup pose, so an error in it is an error in all of
 them — and it is exactly the error one frame cannot show you. Fit an attachment's
@@ -1222,6 +1307,47 @@ against a handful of frames drawn from **every** animation at once, and hold it
 while the per-frame poses are fitted. It is the spread that identifies it — a
 sequence of single-frame fits, one per shot, is not the same thing.
 
+🚨 **That rule is not sufficient for a *joint*, and the difference is not a matter of
+degree.** An attachment offset is identified by a spread of *rotations*; a **pivot** — the
+point one bone turns about relative to its parent — is identified only by frames whose
+**relative rotation across that joint actually differs**. So a spread can draw frames from
+every single shot, satisfy the paragraph above to the letter, and still be
+**ill-conditioned**: if every shot holds that joint at much the same relative angle, the
+pivot is barely constrained, and a wrong one re-solves far away *at equal residuals*. Equal
+residuals is the trap — nothing in the fit reports a problem, because there genuinely is no
+better answer within the data you gave it.
+
+🚫 **And a structural descent that holds the fitted poses fixed cannot recover a
+mis-triangulated pivot at all.** This is the part worth internalising, because it looks
+like the obvious repair and it is inert: the per-frame poses were *fitted against the wrong
+pivot*, so they have already absorbed its error. Move the pivot with those poses held and
+every frame gets worse; hold the pivot and refit the poses and they re-absorb it. **The
+gradient at fixed poses points nowhere**, so the descent reports convergence on the wrong
+geometry — and multi-start does not help either, because the defect is not a basin you
+failed to reach, it is a parameter the objective is no longer a function of.
+
+⇒ **Triangulate a joint from part template matches across *configurations*, not from the
+whole-figure objective.** Match the two parts the joint connects — each is its own art file
+and its own reading — on frames that put the joint in **genuinely different relative
+angles**, and solve for the one point that is fixed in both parts' own coordinates. Then
+refit the poses against the corrected pivot. Two practical notes:
+
+- ⭐ **"Different configurations" means what the shot list looks like, not how many frames
+  you took.** A figure standing, walking and running may hold one joint at nearly the same
+  angle throughout; a figure **lying down**, or inverted, or reaching across itself, is what
+  makes that joint observable. Pick frames for *angular diversity across the joint*, and if
+  the shot list has only one configuration, say in the log that the pivot is a prior.
+- 📌 **Check the conditioning rather than trusting the fit**: re-solve the joint from a
+  subset that excludes the diverse configurations and see how far the answer moves. If it
+  moves a long way at comparable residuals, the diverse frames were carrying the whole
+  identification — which is exactly the state in which an earlier triangulation goes wrong
+  silently.
+- ⚠️ **Sequence matters, because the surgery invalidates work.** Correcting a pivot
+  invalidates every pose fitted under the old one, so do it **before** the per-frame fitting
+  budget is spent, not after. When it has to be done late, expect to re-settle every channel
+  hung off that joint — and freeze the ones that are not, so the two effects stay separable
+  in the record.
+
 **Seed each frame's search from its neighbour's solution — as one start among the
 full-range scans, never instead of them.** Adjacent frames are adjacent poses, so the
 answer next door is a better first guess than the middle of any range, and it costs one
@@ -1276,6 +1402,23 @@ not a quiet one.** The matcher refuses to name a distance past the part's own si
 (§9.2), so a limb far enough out reports no match rather than a large number — read
 that beside a high figure per pixel as the strongest signal the table has.
 
+⚠️ **Excess adjacency change has a second diagnosis, and the rule above assumes the
+first.** *A limb has left its place* is one cause — a fit that teleported, which is what
+a blank drift and a high figure per pixel together point at. The other is **two
+independent per-frame residuals adding**: every pose inside its own accuracy, nothing
+lost, and the *difference* between two neighbours nonetheless several times the
+reference's. The fixes are opposite — the first wants the search bounded or restarted,
+the second wants the neighbouring poses drawn toward each other (§10.3's own note on
+this) — so guessing costs a round either way.
+
+⇒ **Separate them by asking how much freedom the neighbour-mean step actually had.**
+Measure, over every neighbouring pair in the shot, how many of those steps your own
+constraints left **free** to move: if the answer is a percent or two of them, then the
+search was not free to teleport anything, and the excess is residuals adding rather than
+a lost limb. It is one count over data the
+fit already produced, and it is worth more than an afternoon of restarts aimed at the
+wrong cause.
+
 **What comes out is a pose per frame, and a pose per frame is not a key.** Two things
 decide what survives the reduction, and **§10.3** states both: declare one tolerance
 in pixels at the end of what each bone swings rather than a figure in degrees, and
@@ -1319,6 +1462,27 @@ tile has a fraction of a frame's pixels, so the per-frame change measure stays o
 the committed stills, where it reports `no two compared frames are adjacent` and
 means it.
 
+⭐ **Do not treat such a set's two stills as bookends. They are full-resolution frames
+at their own rate, and one of them is routinely a pose no other set on disk carries.**
+The temptation is to read a strided set as *a sheet, plus two files that fix the
+framing* — the sheet is where the shot is, so the stills look like plumbing. But the
+last still is the animation's **own last sample at that rate**, and a finer rate lands
+on a different instant: a shot whose length is not a multiple of the coarse interval
+ends *between* two coarse samples, so the coarse set's last frame is not the end of the
+shot and the finer set's is. If the shot is still moving there — and an end pose usually
+is the part that moves most — that pose exists in exactly one file, at full resolution,
+and it is worth fitting like any other frame.
+
+⇒ **Two consequences for a run.** ① **Fit every committed still**, at every rate, and
+do not let a "sheets are for timing" habit skip them; a pose you never fitted is a pose
+you guessed, and a hold written across the gap because nothing on disk contradicted it
+is a **fabrication** rather than a simplification. ② This is the same fact a brief
+states from the timing side when it warns you against declaring the coarse set's
+rounded length: the rounding and the missing pose are one arithmetic, seen twice. If
+your shot's length is not a whole number of coarse intervals, expect **both** — a
+duration the coarse sidecar understates, and a terminal pose only the finer set shows
+you.
+
 `--fps <n>` exists for frame sets that have no `frames.json` beside them, which are
 sets rendered before the sidecar existed: it gives the rate those frames were
 sampled at, and without it the 12 fps protocol rate is assumed and the report says
@@ -1430,13 +1594,13 @@ that drew the reference frames, onto the same pixel grid, and reports what diffe
 you specifically: it means **you may run `check` as often as you like** without
 your run ceasing to be an honest authoring run. It is a loop, in the way `build` is
 a loop. `bench` and `diff` against a rung's export are not — they read the answer,
-and [the ladder's honesty rule](LADDER.md) makes them a finish line you reach once.
+and [the ladder's honesty rule](https://github.com/firejune/rigc/blob/main/docs/LADDER.md) makes them a finish line you reach once.
 
 📌 **That is also why the MAE figures quoted through this section stay.** Every one of
 them is a candidate's own reading against rendered frames — the exam question, not the
 answer key — so none of them narrows a reference-side measure, and a guide that censored
 them would be teaching less for no gain in honesty. The criterion is under *The honesty
-rule* in [LADDER.md](LADDER.md) (issue #158); what it *does* seal is a score written
+rule* in [LADDER.md](https://github.com/firejune/rigc/blob/main/docs/LADDER.md) (issue #158); what it *does* seal is a score written
 over a reference's own count, and no such figure appears here.
 
 🚨 **If you drive the runtime yourself, a bone's local transform lives on
@@ -1484,6 +1648,145 @@ of these inert writes and not a wrong animation.** The parameter you swept was
 never read; a wrong rig moves the number, a write to a field nothing reads
 cannot.
 
+🚨 **And the mirror image of all three: an objective that *improves by removing the
+subject*.** The traps above are each *"the number will not move"*, and they train you
+to distrust a still figure. The twin is a figure that moves, in the right direction,
+for the wrong reason — and it is the more dangerous one, because progress is what it
+looks like.
+
+The shape is arithmetic, not a bug. **Any symmetric error over two silhouettes charges
+a mismatch in both directions**, so it charges your ink that the reference has none
+under *and* the reference's ink you leave bare. Give it a candidate that draws
+**nothing** and only the second term survives: the score is the reference's own ink,
+once, and it is a *finite, respectable-looking number*. A part that is present but
+badly posed pays both terms and can score **worse than absence**. ⇒ A search with a
+free enough range finds the cliff and walks off it, and every step of the walk reports
+as an improvement. Synthetic illustration of the whole failure in three rows — one
+part, one objective, nothing else changed:
+
+| what the candidate does | part error |
+| --- | --- |
+| posed roughly right | 2.15 |
+| posed badly — overlapping the wrong reference ink | 2.48 |
+| **translated clean off the frame** | **1.00** |
+
+The search reports **1.00 against 2.15** and calls it a 53 % gain. What it found was
+the absence of a subject. ⚠️ **1.00 is not a coincidence in that table, it is the
+construction**: absence pays the reference's ink exactly once, so on any objective
+normalised by that ink, *"draw nothing"* sits at 1.0 by arithmetic — which is why it is
+worth evaluating deliberately rather than discovering.
+
+⇒ **Four defences, and the first is the cheap one.**
+
+- **Bound the search to the frame.** A part cannot legitimately leave the picture on a
+  shot whose frames all draw it, so a translation range wide enough to exit the
+  viewport is a range that contains a false optimum. Bound each parameter by what the
+  frames can *show*, not by what the format permits.
+  - ⚠️ **And its converse, which is the easier half to get wrong: a bound has to
+    *reach* what the frames show, not merely stop where they stop.** The two failures
+    look nothing alike — a bound that is too wide loses a fit to the cliff, a bound
+    that is too narrow loses one to a wall it never reports hitting. Bounding a
+    vertical channel to the range the *rest* pose occupies is the classic case: a shot
+    that drops its subject in from hundreds of pixels above the standing pose puts its
+    own entry outside the search entirely, and the fitter returns the best pose *it was
+    allowed*, which is the top of the box, silently. ⇒ **Take each channel's range from
+    the brief and the frames — the extremes the shot actually visits — and then check
+    afterwards how many converged values are sitting on a bound.** A knob resting
+    exactly on its limit is the signature, and it costs one line to print.
+- **Assert the part is drawn, every iteration.** Count your own ink for that part and
+  reject any candidate whose count is zero or a small fraction of the reference's. This
+  is one comparison and it makes the cliff unreachable rather than merely unattractive.
+  - ⚠️ **Write it at the resolution the level is actually being evaluated at.** On a
+    coarse-to-fine pyramid, a threshold expressed in full-resolution pixel counts
+    refuses **every** coarse pose — and a rejection that fires on everything is
+    indistinguishable from an objective with no gradient. You get `Infinity`, or a
+    figure far worse than the same search reaches with the assert switched off, and
+    nothing in either says *"your guard is the problem"*. ⇒ Express the count as a
+    **fraction of the reference's ink at that same level**, so the test means the same
+    thing at every rung of the pyramid.
+- **Charge ink that leaves the window, because the cliff has a second entrance.** If
+  your objective is computed inside a window around the reference's own drawn box —
+  and it usually is, since that is what makes it cheap — then ink outside the window
+  costs **nothing**, and the three defences above do not reach that: the part is still
+  drawn, its count is still healthy, and the score still falls. The fitter hangs a part
+  a few hundred pixels below the frame and reports progress every step. ⇒ **Count your
+  own ink further than a small margin outside the reference's drawn box and charge it.**
+  One line, in the same place as the ink count, and it closes the entrance the bound
+  closes only when the bound happens to be tight enough.
+- **Read the objective's floor before you trust its direction.** Evaluate *"draw
+  nothing"* once, deliberately, and keep the figure. Any score at or below it is the
+  cliff, whatever the search says — and if your best honest pose is *above* that floor,
+  the objective is ranking absence over effort and needs an asymmetry (charge bare
+  reference ink more than stray candidate ink) before it is safe to optimise against.
+
+📌 **`check` itself is not exposed to this** — its `MAE in it` and `share` columns
+divide over the **reference's** own drawn pixels and a chain that draws nothing reads
+0 % on 0 slots, which §9.2 says is the loudest row in the table and not the quietest.
+The trap lives in the objectives **you** write inside a fit, where the denominator is
+yours to choose.
+
+🚨 **The cliff's nearest cousin, and the one that survives all four defences:
+*sacrificial cover*.** Every defence above protects a part from being **removed**. None
+protects a part from being **moved somewhere wrong on purpose**. A whole-figure objective
+scores one number over every pixel, so when part A is mis-placed and leaves reference ink
+bare, the cheapest available improvement is frequently to drag **part B off its own correct
+place to cover that ink**. Both parts are drawn, both counts are healthy, nothing leaves
+the window — and the score genuinely falls, because covering bare ink is worth more to a
+blunt objective than B's own displacement costs it.
+
+⚠️ **What makes it expensive is that the objective is not lying.** The pose it prefers
+really is better *by that measure*. So the loop offers no signal at all: the fit converges,
+the number improves, and what you have is one part visibly out of place standing in for
+another. It surfaces later as a **drift** on the sacrificed part — a slot several pixels
+from where the frames put it inside a pose whose overall figure looks fine — which is the
+one measure that reads parts individually.
+
+⇒ **Two ways to catch it, and the first is nearly free.**
+
+- **Read a per-part residual beside the composite, never only the composite.** Score each
+  part against its own template match as well, and flag any frame where the composite
+  improves while a part's own residual worsens. That divergence *is* the signature; the
+  composite alone cannot express it.
+- **Seed the parts analytically from their own measured features, then refine jointly with
+  the sacrificed part pinned.** If a part's place is independently measurable — a colour
+  feature, a template peak, a contact row the brief gives you — put it there first rather
+  than letting the composite negotiate it, and hold the part that was being abused fixed
+  while the rest re-settles.
+
+⚖️ **Expect the corrected pose to score *worse* on the composite, and record that as a
+trade.** A few percent worse on your own objective while decisively better on every
+frame-derived placement instrument is the **expected** shape of this repair, not a
+regression — the composite's preference was the defect. Declare an accept threshold before
+you need it, say how often you used it, and name the frames. ⭐ **And prefer the
+frame-derived instruments when they disagree with the composite about a single part's
+place**: the composite is one number over everything, while a template match on that part's
+own art is a measurement of the thing in question.
+
+🚨 **One more inert-write trap, and it is on the way *out* of the fit rather than
+inside it: your compiled animation is not your pose series.** Everything above is about
+a search that reads the wrong thing; this is about a search that was right and an
+emission that was not. The formats differ in a way that is easy to miss — **a translate
+key is an offset from the setup pose, while a fitter almost always drives the absolute
+local position** — so writing the fitted numbers straight into keys applies the setup
+offset a second time and displaces the whole figure by it.
+
+⚠️ **What makes it expensive is how it presents.** `build` is green: the numbers are
+finite, the durations agree, nothing is degenerate. And `check` does not say *"your keys
+are offset"* — it says the union box is a fifth larger than the reference's, the MAE is
+several times anything a wrong pose produces, and no slot is attributable anywhere.
+That reads like a **wrong rig**, so the hours go into the rig.
+
+⇒ **Before reading a single measure, sample your own compiled animation and diff it
+against the pose series the fitter produced.** `sampleAnimation` in
+[`src/render.ts`](../src/render.ts) is the same stepper the frames were made with, so
+this is a handful of lines and it is exact: for every frame, for every bone, the local
+transform the file plays back against the local transform you fitted. A constant offset
+per channel is this bug; a constant *factor* is a unit or lever mistake; zeros
+everywhere are §9.1's `bone.pose` trap one level earlier. ⭐ **The general rule: a
+pipeline with a fit at one end and a file at the other needs one check that the file
+plays what the fit found**, and it belongs before the measures rather than after a day
+of them.
+
 ### 9.2 Reading the table
 
 ```
@@ -1660,6 +1963,81 @@ pair the reference moves *one pixel* across stopped being visible at half scale,
 the diagnostic run reported a frame-change disagreement the graded run does not have.
 Read it for the floor, never as the verdict.
 
+🚨 **And a third, which decides whether the recipe measures anything at all: `--atlas`
+substitutes region *geometry* as well as texture.** The diagnostic's logic is *"same
+skeleton, same keys, the reference's own texture"* — but an atlas entry is not only a
+page and a rectangle. It also carries how the region was packed: **`rotate`**, and the
+trim offsets that say where the opaque part sits inside the original image. Swap the
+atlas and your attachments are re-seated on those, so the quads change too.
+
+⇒ **The recipe measures a floor only when the substitution is *"same quads, coarser
+texture"*.** Where the supplied atlas packs its regions **rotated or trimmed** and your
+attachments were measured off the loose PNGs, it is not — and the tell is unmistakable:
+**the number goes the wrong way.** A texture floor can only *explain* error, so a
+diagnostic that sends the MAE **up** on every set has substituted geometry, not just
+pixels, and the run's own atlas was the more faithful of the two.
+
+⚠️ **Then the honest verdict is *inconclusive*, not *no floor*.** Both readings stay
+open — there may be a texture floor this diagnostic cannot isolate — so record the
+figures, say the substitution changed the quads, and do **not** convert a failed
+diagnostic into a claim about the shot. ⇒ Check the atlas's own entries for `rotate` and
+for trim before you run it; that is one look at a text file, and it tells you in advance
+whether the number you are about to take will mean anything.
+
+🚨 **The precondition the advice above does not state: a floor measured with another
+part misplaced is not a floor.** Measuring at the rest pose is right — it is the one
+pose you can often *prove*, because the setup pose is the art at its own scale and the
+frames state the standing dimensions — but "the pose is provably right" is a claim
+about **one part**, and the floor you read is a whole-figure number. Any other part
+that can occlude the one you are measuring is inside that number too, and a part
+sitting tens of units off its place occludes the **wrong** pixels: the ones it hides
+count as yours-and-not-theirs, the ones it should have hidden count as
+theirs-and-not-yours, and both land on the part you thought you were isolating.
+
+The damage is that you then hold a *plausible* floor and calibrate against it. A
+synthetic case with the same shape — one part measured three ways, nothing about that
+part changed between the rows:
+
+| what else is placed | silhouette IoU read for the measured part |
+| --- | --- |
+| a neighbour still tens of units out of place | 0.74 |
+| that neighbour placed | **0.95** |
+| (the difference) | 0.21, all of it the neighbour |
+
+A fifth of an IoU is larger than most of what a fit is trying to buy, so two or three
+experiments get read against the wrong baseline before anything exposes it — and what
+usually exposes it is the setup fit finishing, which is *after* you needed the number.
+
+⇒ **Before believing a floor, check that every part which can occlude the one you are
+measuring is already placed** — and prefer a frame where the parts are **far apart or
+only one is drawn** to one where they overlap, which is §8.1's rule for calibrating a
+two-part assignment applied to a floor. If no such frame exists, say in the log that
+the floor is an upper bound on the error rather than a floor under it. ⚠️ This is the
+same failure as capturing a guard's expected value from a screen that is already
+broken: the baseline records the defect, and then the *repair* is what looks wrong.
+
+⚖️ **`frames.json`'s own box can be refused for a reason that is not a coordinate
+error, and there is an honest answer.** The test is on **extent**: a candidate authored
+in the frames' own world units — one whose setup box lands on the reference's to the
+pixel — still fails it if its union content box differs by a few pixels at the
+extremes, because one part reaching somewhere nothing in the frames reaches is enough.
+`check` then fits its own box, and on a multi-shot root the fitted framing costs every
+set some MAE against the declared one — the same order as the shared-versus-per-set gap
+the `--framing` flag's own help quotes, and easily more than a round of fitting buys.
+That cost is real and it is **not** a sign you got the coordinates wrong.
+
+⇒ **Report both, label which is which, and say what separates them.** Run `check`
+unaided — that is the figure the artifact produces on its own and the one that belongs
+in a run's record — then run it once more with `--viewport` on the declared box and keep
+that output as a **named diagnostic file** beside the first. The gap between them is the
+framing; what is left is the keys, which is the only reason to want the second number.
+🚫 **The pinned run is never the record.** `--viewport` is a claim about your own
+coordinates and `check` says so above every figure it prints under one: *nothing checks
+it*. And do not chase the refusal by shrinking a part to fit the box — that trades a
+framing cost for a wrong silhouette, which is worse in every column that matters.
+Instead read the `content` line's own advice: it names how much wider and shorter you
+cover, and **which part reaches too far is a drift question**, not a framing one.
+
 **`Δpx` and `ref Δ`** are the two columns that do **not** compare you against the
 reference. They compare each side against **itself one frame earlier**: how many
 pixels of your own frame moved since your own previous frame, and the same for the
@@ -1796,6 +2174,19 @@ a per-shot list. **§8.1** is how to act on it: the next iteration goes to the w
 chain by error per pixel, and a chain already at the floor is frozen rather than
 re-fitted.
 
+⚠️ **One exception to "0 % is the loudest row", and on a mesh rig it is the common
+case: a chain whose roster reads `(draws nothing)` rather than `0/n`.** Those are two
+different states and the table prints them differently. `0 %` on `0/3` **slots drawn**
+means three slots exist on that chain and none of them put ink on the frame — that is
+the loud row, and it is a missing part. `(draws nothing)` in the **bones** roster means
+the chain carries **no slot at all**, and a mesh's control bones are exactly that: the
+mesh attachment lives on the slot of the bone the mesh hangs from, so the bones that
+*deform* it own nothing to draw. ⇒ **On a mesh rig that row is normal and quiet.** Read
+the roster at the foot of the report before reacting to a chain's share: if the chain's
+slots column is a parenthesis rather than a fraction, the deformation it carries is
+already being scored inside the chain that owns the slot, and the row is telling you
+about your bone tree rather than about a hole in your figure.
+
 ### 9.3 What it still cannot see
 
 - **Anything a frame does not contain.** Bone `length`, the setup `inherit` mode,
@@ -2019,6 +2410,86 @@ smallest single-frame move inside that span**. It is one line in the planner, it
 a handful of keys, and it is the difference between a reduction that is accurate and
 one that is accurate *in proportion to what is happening*.
 
+⚠️ **The opposite defect exists and forcing keys makes it worse.** Everything above is
+one direction — *my curve slopes through a plateau the reference holds* — and its fix is
+to force both ends as keys. The other direction is *my candidate moves several times
+what the reference does on a pair the reference barely moves across*, and if you reach
+for the same fix you will pin the excess in place instead of removing it. **The cause is
+different**: there the key plan was smoothing away motion the shot has; here the key
+plan is faithful and what disagrees is the **per-frame residual** — two neighbouring
+poses each a little off, in opposite directions, so the *difference* between them is
+several times either error. Forcing both as keys asks the planner to reproduce exactly
+the two poses whose disagreement is the problem.
+
+⭐ **Diagnose it before you fix it, with one comparison.** Take the two frames the column
+flags and ask whether your **poses** at those two frames are each inside your own fitting
+accuracy. If they are — and the pair still disagrees — the defect is the residual and not
+the plan. Synthetic case, one pair:
+
+| | reference moves | candidate moves | each pose's own error |
+| --- | --- | --- | --- |
+| a quiet pair | 0.8 px | 4.1 px | 1.6 px and 1.7 px, opposite signs |
+
+Both poses are ordinary; the pair is a five-fold disagreement built out of them.
+
+⇒ **The fix has the same shape as the relative floor above: make the smoothing slack
+relative to the reference's own local change.** Where the reference barely moves,
+contract your neighbouring poses toward each other until your own frame-to-frame change
+is inside the band — accepting a small, *bounded* loss of fidelity on those frames in
+exchange for the one measure that can see a hold. ⚠️ **That is a trade and it is recorded
+as a trade**: name the frames, name the cost per frame, and say in the log that you took
+it. A contraction reported as a fit is the same dishonesty as a hold reported as a
+measurement, and the cost is real — the frames you contracted are slightly less faithful
+than they were.
+
+🚨 **Contract the *planned curves*, not the pose series — the report never sees the pose
+series.** This is one sentence and it is worth two builds: the change column measures
+your **compiled animation sampled at the frames' own rate**, and between your poses and
+that lie the key reduction and the curves. Contract before the reduction and you have
+adjusted a series nothing downstream reads — the planner then re-fits its spans through
+the adjusted poses, the interpolants land where the tolerance allows, and the pair you
+were aiming at comes back out of band having *moved*. ⇒ **Apply the contraction where
+the measurement is taken**: plan the keys, sample the planned curves, find the offending
+pairs, and contract *those samples* by forcing or moving the keys that produce them —
+then re-plan and re-sample. That is the closing loop below, and its subject is the curve
+series throughout.
+
+⚠️ **And aim *inside* the band, not at it.** `check`'s thresholds are exact and stated in
+[`src/check.ts`](../src/check.ts), so it is tempting to converge until every pair is
+just inside. But a run measuring its own change renders in **its own framing**, and the
+report renders in the one `check` chose — and a fraction of a percent of scale is worth
+a few percent of a pixel count. A pair you cleared by a hair in your loop can sit the
+wrong side of the same threshold in the report, on a difference that is entirely
+framing. ⇒ Converge to a **margin** — clear the band by enough that a percent of scale
+cannot cross it — and re-read the real report before believing the column.
+
+🚨 **There is a third direction, and on a busy shot it is the binding one: your candidate
+moving too *little*.** The two cases above are both *you moved when you should not have*
+— a hold that is not held, and excess change on a quiet pair. But `check`'s rule is
+**two-sided**: it faults a pair when **either** side moves several times the other by
+more than its pixel floor. So the mirror case is a reference that is genuinely busy and
+a candidate that reproduces a fraction of it, and nothing in the two paragraphs above
+names it.
+
+⭐ **The practical form is a floor rather than a ceiling: on every pair the reference
+moves, yours has to move at least about a quarter as much.** Read the exact multiple and
+the pixel floor out of [`src/check.ts`](../src/check.ts) rather than trusting the
+approximation — but plan against the floor, because it behaves quite differently from
+the ceiling:
+
+- **It is not fixed by keys.** Over-change is a planning artefact you can force or
+  contract away. Under-change means the *poses themselves* barely differ, so no key plan
+  recovers it — the fit has to find more motion before the planner sees any.
+- **It is where a whole-figure objective fails hardest**, which is why the item below
+  belongs beside it: a passage whose motion is a small part against a large still body
+  contributes almost nothing to a whole-shot score, so a fitter converges happily on a
+  near-static series and every pose looks fine on its own.
+- ⚠️ **And the band will accept a shot that is visibly underplayed.** Clearing the floor
+  at a quarter is not reproducing the motion; it is not *failing* it. A run whose busy
+  passage sits near the floor should say so in the log as a known-weak passage rather than
+  quote the column as if it were a fidelity result — the column is a **band**, and a band
+  is the widest thing that passes, not the thing you were aiming at.
+
 ⭐ **Then stop trusting the floor and close the loop on the frames, because a floor is
 a heuristic and the column is a measurement.** The floor above cut rung 3's
 disagreements from three to one and could not reach the last: **sample your own planned
@@ -2115,6 +2586,50 @@ tolerance**, which costs nothing and needs no reference: scan each knob around i
 converged value and read how far it moves before the objective does. Then declare a
 tolerance at or above the widest of them, and record both numbers.
 
+⚖️ **Read that last sentence with the rule two paragraphs up, because taken literally
+the two pull apart — and the resolution is that the basin is a *per-channel floor*,
+not a second global declaration.** The tension is real: *declare one tolerance* asks
+for a single figure in one unit so the density trade reads as one curve, while
+*declare at or above the widest basin* points at the worst-identified knob in the rig.
+Those can differ by **an order of magnitude** — a well-levered channel the objective
+pins to a fraction of a pixel sitting in the same rig as a part the objective barely
+sees at all, whose basin is several pixels wide. Take the widest and every good channel
+is keyed to the worst one's ignorance; take the declared figure alone and the bad
+channel ships the fitter's wander as data.
+
+⭐ **What decides it: a basin belongs to the estimator that wrote the channel, and a
+run that fits poses has more than one.** The two rules are answering different
+questions. *One tolerance* is about the **unit and comparability** of the figure you
+declare — that survives untouched. *The basin* is about the **noise under a particular
+series**, and noise is a property of the estimator on that channel, not of the rig. So:
+
+> **Declare one tolerance, in pixels at the end of what each bone swings. Then floor it
+> per channel at that channel's own basin, capped.** Effective tolerance for a channel
+> = `max(declared, min(that channel's basin, cap))`.
+
+- **Why per channel** — the thing the floor protects against is encoding wander, and
+  wander is per channel. A global maximum spends keys nowhere they were needed and
+  removes them nowhere they were wrong.
+- **Why a cap, and this is the part worth understanding.** The basin bounds **what you
+  know**; the tolerance also bounds **what you render**, and the rendered series is read
+  by `check`'s change column at *zero* slack (§9.2). So an uncapped floor lets a
+  badly-identified channel buy a reduction error large enough to show up as motion the
+  reference does not have — trading a measure nothing reads for one read at zero
+  tolerance, which is the wrong direction. A cap of a pixel or two, declared and
+  recorded, bounds the reduction error whatever the identifiability.
+- ⇒ **And a channel whose basin exceeds the cap is telling you it is not identified,
+  which is a different problem with a different fix.** The answer there is a **prior** —
+  regularise the channel toward a smooth trend and say in the log that you did — not a
+  tolerance wide enough to key it three times and call the result a measurement. ⚠️ Such
+  a channel is *partly a prior rather than a measurement*, and a run that does this
+  records which channels and over which passages, exactly as it records a contraction
+  trade below.
+
+📌 **Record all three numbers**: the declared tolerance, each floored channel's basin,
+and the cap. `diff`'s `key_counts` is the finish line and a run gets one shot at it, so
+the arithmetic that produced the density is the only thing that makes the figure
+readable afterwards.
+
 **A rig's parameters are not identified by its pixels — remove the gauges before you
 key.** A bone that carries no attachment is an exact gauge: turn it by δ, turn its
 children back by δ, and **not one pixel changes**. Anything optimising against pixels