spine-rigc 0.6.0 → 0.8.0

package/docs/AUTHORING.md

@@ -70,6 +70,12 @@ can see where Spine stops.
 ```bash
 bun install                                   # once
 
+# …but if what you were HANDED is a picture of the pose rather than numbers, read
+# the numbers out of it first. This one runs BEFORE the loop, not inside it:
+bun cli.ts pose --images path/to/parts --frame path/to/poseA.png --out poseA.json
+#   ↳ one entry per part PNG: where it sits, how confident that is, and where two
+#     answers are equally good — §11
+
 bun cli.ts build \
   --rig    path/to/my.rig.json \
   --motion path/to/my.motion.json \
@@ -89,6 +95,11 @@ bun cli.ts check \
 # …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
+
+# …and where you have several green candidates and no instrument that separates
+# them, ask a human — the one loop step this toolchain cannot run for you:
+bun cli.ts vote --candidate path/to/spine-a --candidate path/to/spine-b   # -> ballot.html
+bun cli.ts vote --record vote-<id>.json                                   # -> votes.jsonl
 ```
 
 `build` compiles, round-trips the result through `@esotericsoftware/spine-core`,
@@ -122,16 +133,25 @@ What the flags mean:
 | `--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) |
+| `--images` | where the rig spec's `image` names resolve (overrides the rig's own `images` field, and is relative to your working directory). For `pose` it is the directory of **loose part PNGs to place** — every `.png` in it is a part, in name order |
 | `--manifest` | a cut manifest. Only for a rig with **measured art** behind it; a foreign skeleton has none |
-| `--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 |
+| `--profile` | `spine` = the 22 validity rules (**the default**) · `spine-html` = all 36, opt-in |
+| `--candidate` | `check`, `bench`, `render`, `preview` and `vote` 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. **`vote` is the one command that takes it more than once** — repeat it 2–4 times, one per pane, labelled A, B, C, D in the order given; everywhere else a repeat is a typo and is refused |
+| `--animation` | `render`, `preview` and `vote` only: which animation to show. The default is **every** one for `render`, the **first** for `preview`, and for `vote` the first of candidate A. A name the skeleton does not have is refused, with the ones it does have listed — and for `vote`, so is a name that only *some* candidates have |
+| `--record` | `vote` only: a saved vote to check against its ballot and append to the ledger, instead of writing a ballot. This is the command's second mode; it takes no `--candidate` |
+| `--ballot` | `vote --record` only: the ballot the vote answers (default `ballot.html`). Its embedded manifest is what the vote is checked against, so the ballot file is the record of the question |
+| `--ledger` | `vote --record` only: the append-only JSONL the vote lands in (default `votes.jsonl`), one vote per line |
+| `--again` | `vote --record` only: record a second vote on a ballot the ledger already has. Without it a repeat is refused by name rather than doubled |
+| `--frame` | `pose` only: one pose frame — the picture to read part placements out of. One frame per call; several key poses are several calls, and correlating them is yours (§11) |
+| `--scale` | `pose` only: the scale window to search, as **frame pixels per part pixel**, `<min>,<max>` (default `0.5,2`). The report states what it searched, and a window that does not contain the truth does not reliably refuse — §11 |
+| `--rotation` | `pose` only: the rotation window to search, in screen degrees, `<min>,<max>` (default `-180,180`, a full turn). Narrow it when you know the art is upright |
+| `--max-residual` | `pose` only: above this residual a placement is **refused by name** instead of reported flat (default `0.25`). A reporting threshold, not a pass bar — the placement is still in the JSON |
 
 `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`).
+frame, default 256). Three commands take `--out`: a directory for `render`
+(default `render/`), the `.html` file for `preview` (default `preview.html`) and
+for `vote` (default `ballot.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",
@@ -152,6 +172,9 @@ 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]
+bun cli.ts vote     --candidate path/to/a --candidate path/to/b [--out ballot.html]
+bun cli.ts vote     --record vote-<id>.json [--ballot ballot.html] [--ledger votes.jsonl]
+bun cli.ts pose     --images path/to/parts --frame poseA.png [--out pose.json]
 ```
 
 - **`explain`** is the one to reach for when a rig compiles but looks wrong. It
@@ -185,6 +208,34 @@ bun cli.ts preview  --candidate path/to/spine [--animation …] [--out preview.h
   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.
+- 📐 **`pose` is the only command here that reads an INPUT rather than a result.**
+  Everything else takes a spec or a build and tells you something about it; `pose`
+  takes a picture the user already has — a key pose — and reports where each loose
+  part PNG sits in it, so you can write those coordinates into a rig and a motion
+  **by construction**. Nothing about it grades anything: at that point the pose is
+  a given condition, not a target, and the residual it reports is how far to trust
+  a placement rather than how good the placement is. Reach for it the moment a
+  request arrives as *"make it go from this picture to this one"*. **§11.**
+- 🗳️ **`vote` is `preview` with more than one candidate in it and an answer
+  coming back**, and it is the one step of this loop you cannot run yourself.
+  Reach for it where the instruments have run out: two builds that `check` and
+  `diff` cannot separate, a pose fit with two local optima, a key density that is
+  a matter of taste, a first draft with no reference at all. **The intended loop
+  is: you compile 2–4 candidates that every one of them passes the gate → `rigc
+  vote` writes one `ballot.html` → a human opens it, watches the panes loop, and
+  picks a winner or declares a tie → they save the small JSON result the page
+  hands them → `rigc vote --record <that file>` checks it against the ballot and
+  appends one line to `votes.jsonl` → you read the ledger and proceed.**
+  Compile first, vote last: never put a candidate on a ballot that did not build
+  green, and never ask the human to read JSON, a diff or a spec — the page holds
+  playable pixels and nothing else. The panes are labelled `A`/`B`/`C`/`D` and
+  carry no paths, so do not describe the candidates to the voter either. What
+  comes back is machine-checkable rather than prose: each line names the winner
+  by content **digest** (a label means nothing outside one ballot), carries the
+  `coverage` set so you can compute what is still unreviewed, and carries a
+  reason code from a closed enumeration. A **tie is a recorded answer**, and
+  `both-unacceptable` is the one that means *propose again* rather than *adopt
+  either* — check for it before you treat a ballot as settled.
 
 ---
 
@@ -617,6 +668,9 @@ time puts it here.
 | `tracks` | the timelines |
 | `drawOrder` | the draw-order timeline — §4.7. Not a track: it names no target |
 | `events` | the event timeline — §4.8. Not a track, for the same reason |
+| `ik` | IK constraint timelines — §4.9. Not a track: its keys carry named fields, not one `v` |
+| `transform` | transform constraint timelines — §4.10. Same reason |
+| `deform` | deform timelines — §4.11. Same reason |
 
 `groups` (`name → [member, …]`) lets one track target several bones or slots at
 once; `lag` shifts every key of a track, and `stagger` adds a per-member delay in
@@ -627,6 +681,13 @@ member order.
 A track names **exactly one** of `bone`, `slot`, `group`, `physics`. Two tracks on
 the same `target.property` is a compile error: merge them.
 
+Three families are **not** tracks and sit beside `tracks` instead — `ik` (§4.9),
+`transform` (§4.10) and `deform` (§4.11). The reason is the key rather than the
+target: a track's key carries one `v`, and those three carry named fields each
+(two for an IK constraint, six for a transform constraint, a sparse vertex run for
+a deform). Folding them in would make `v` mean four different things depending on
+`property`. 4.3 also writes them as their own groups beside `bones` and `slots`.
+
 | Target | `property` | Key `v` |
 | --- | --- | --- |
 | `bone` | `translate`, `scale`, `shear` | `[x, y]` |
@@ -819,6 +880,232 @@ decreasing time builds an `EventTimeline` whose earlier firing is simply
 unreachable, with a perfectly clean load.
 `A32_EVENT_KEYS_RESOLVE` checks all three from the other side.
 
+### 4.9 `ik` — mixing an IK constraint in over time
+
+The rig spec declares the constraint (§3.5); this keys it. 4.3 writes the group as
+`animations.<a>.ik.<constraint>` — **one unnamed timeline per constraint**, so the
+constraint name is the only target there is, and there is no timeline name between
+the two the way a bone has `rotate` and `translate`.
+
+```json
+"animations": {
+  "walk": {
+    "duration": 0.8666666,
+    "loop": true,
+    "tracks": [],
+    "ik": [
+      {
+        "constraint": "rear-leg-ik",
+        "keys": [
+          { "t": 0,         "mix": 1, "softness": 0 },
+          { "t": 0.2666666, "mix": 1, "softness": 14, "ease": "settle" },
+          { "t": 0.5333333, "mix": 0, "softness": 0 },
+          { "t": 0.8666666, "mix": 1, "softness": 0 }
+        ]
+      }
+    ]
+  }
+}
+```
+
+⚠️ **Every number above is invented.** They are shaped like a walk cycle — the leg
+under load is solved to the ground and the leg in flight is let go — and nothing
+here was measured off a real rig. Copy the shape, not the values.
+
+| Field | Meaning | Absent means |
+| --- | --- | --- |
+| `mix` | 0..1, how much of the solved rotation is applied | `1` |
+| `softness` | distance from full reach at which the bones stop straightening | `0` |
+| `bendPositive` | two-bone bend direction | `true` |
+| `compress` | one-bone IK scales the bone down to reach a close target | `false` |
+| `stretch` | scales the bone up to reach a far target | `false` |
+
+- **`mix` and `softness` are the two curve channels, in that order.** A raw
+  `curve` is therefore 8 numbers, and the three booleans are stepped by nature —
+  nothing interpolates a bend direction.
+- `mix` outside `0..1` is a compile error: `IkConstraintPose.mix` is documented as
+  a percentage. A **transform** mix is documented *unbounded*, which is why §4.10
+  has no such rule — the asymmetry is the runtime's, not ours.
+- 🚨 **A field stated on one key and not the next is a compile error.** This is the
+  refusal worth reading twice, because the format's shape invites the mistake: the
+  parser reads every field **fresh per key** with its own default, so a key that
+  omits `softness` does not hold the previous key's 14 — it snaps to 0, and
+  interpolates down to it on the way. It loads. It plays. It is not what you
+  wrote. So state a field on every key of a track or on none of them; writing the
+  default out loud is how you opt in.
+- Its last key counts towards the declared duration like any other (R7).
+
+rigc refuses four things here:
+
+| You wrote | You get |
+| --- | --- |
+| a constraint the rig does not declare | `keys unknown ik constraint "X"; the rig declares ik constraint(s): …` |
+| a `transform` constraint's name | `keys "X" as an ik constraint, but the rig declares it as a "transform" constraint` |
+| `softness` on the first key only | `key 0 names "softness" and key 1 (t=…) does not … it would snap to 0` |
+| `mix: 1.5` | `mix is 1.5, outside 0..1 — the runtime documents it as a percentage 0-1` |
+
+The type check matters because the parser resolves a timeline's target by name
+**and** type: `findConstraint(name, IkConstraintData)` misses a transform
+constraint of the same name, returns null, and `readAnimation` throws — in the
+consumer's process, which is late. `A34_CONSTRAINT_TIMELINE_TARGETS` checks the
+same two from the other side, plus one thing the compiler cannot produce and a
+hand-edited file can: an **empty key array**, which the parser skips in silence.
+
+### 4.10 `transform` — turning a muted transform constraint on
+
+Same shape as §4.9 and the same absent-means-default rule; six mixes instead of
+two. The idiom this exists for is an aim rig: the constraints are declared with
+`mixRotate: 0` in the rig spec — muted at setup, so the figure is posed by its own
+bones — and the animation that needs them mixes them in.
+
+```json
+"animations": {
+  "aim": {
+    "duration": 0.3333333,
+    "loop": false,
+    "tracks": [],
+    "transform": [
+      { "constraint": "aim-head-transform",      "keys": [{ "t": 0, "mixRotate": 1 }] },
+      { "constraint": "aim-torso-transform",     "keys": [{ "t": 0, "mixRotate": 0.6 }] },
+      { "constraint": "aim-front-arm-transform", "keys": [{ "t": 0, "mixRotate": 1 }] }
+    ]
+  }
+}
+```
+
+⚠️ **Every number above is invented**, including the 0.6 — a torso that follows the
+aim less than the head is a plausible rig and not a measured one.
+
+A single key at `t: 0` is the whole timeline here, and that is not a degenerate
+case: it says "while this animation is playing, this constraint is on", which is
+exactly what a mix that was 0 at setup needs said.
+
+| Field | Absent means |
+| --- | --- |
+| `mixRotate` | `1` |
+| `mixX` | `1` |
+| `mixY` | **this key's own `mixX`** — not `1` |
+| `mixScaleX` | `1` |
+| `mixScaleY` | `1` |
+| `mixShearY` | `1` |
+
+- **Six curve channels, in the order above.** A raw `curve` is 24 numbers.
+- No range check: every one of these is documented **unbounded**, and an over-mix
+  above 1 is a real editor idiom rather than a mistake.
+- ⚠️ A mix is only read by the runtime if the constraint declares the matching
+  `properties` mapping (§3.5). Keying `mixScaleY` on a constraint that maps
+  rotation only is dead data — legal, loaded, and it moves nothing.
+- The refusals are §4.9's, with `transform` in place of `ik`.
+
+### 4.11 `deform` — moving an attachment's vertices
+
+The one timeline whose keys mean something different depending on what they are
+attached to, and the only one keyed on a **skin / slot / attachment** triple:
+`animations.<a>.attachments.<skin>.<slot>.<attachment>.deform`.
+
+```json
+"animations": {
+  "hoverboard": {
+    "duration": 1.6666666,
+    "loop": true,
+    "tracks": [],
+    "deform": [
+      {
+        "slot": "board",
+        "attachment": "board",
+        "keys": [
+          { "t": 0 },
+          { "t": 0.5,       "fromVertex": 4, "vertices": [0, -7, 0, -7], "ease": "settle" },
+          { "t": 1.1666666, "fromVertex": 4, "vertices": [0, 4, 0, 4],  "ease": "settle" },
+          { "t": 1.6666666 }
+        ]
+      }
+    ]
+  }
+}
+```
+
+⚠️ **Every number above is invented** — the vertex indices, the offsets and the
+times alike. A real deform's numbers come from the geometry it is bending, and
+there is no way to guess which vertices of somebody's board are its middle.
+
+| Field | Meaning |
+| --- | --- |
+| `skin` | which skin the attachment lives in. Absent = `"default"` |
+| `slot` | the slot |
+| `attachment` | the attachment's **placeholder** name inside that skin and slot |
+
+Per key:
+
+| Field | Meaning |
+| --- | --- |
+| `vertices` | the run: `x, y` offset pairs. **Absent** = back to the setup pose |
+| `fromVertex` | which VERTEX the run starts at — rigc translates it |
+| `offset` | the same start as a raw index into the deform array. Never with `fromVertex` |
+| `ease` / `curve` | one channel, and it eases the **blend**, not a coordinate |
+
+Four things are worth having straight before you write one.
+
+**A key is a sparse edit, and a key with no `vertices` is the setup pose.** The
+parser builds an array as long as the attachment's own, copies your run into it at
+`offset`, and leaves the rest at zero. So a run only has to cover the vertices that
+move, and the `{ "t": 0 }` and `{ "t": 1.6666666 }` keys above are how a looping
+deform starts and ends undeformed. That is the format's own encoding for it, not a
+convention — which is why rigc refuses a start index on such a key: there would be
+nothing for it to point at.
+
+**Offsets, not positions.** The numbers are relative to the setup geometry in both
+encodings. On an unweighted attachment the parser literally adds the setup vertex
+back on load; on a weighted one zero *is* "unmoved".
+
+**The array is indexed by vertex on an unweighted attachment and by bone influence
+on a weighted one.** Its length is `vertices.length` in the first case and
+`vertices.length / 3 * 2` in the second, because a weighted attachment stores
+`x, y, weight` per influence. A vertex with three bones on it therefore occupies
+**three** pairs, each in that bone's own bind space. This is the whole reason
+`fromVertex` exists and the whole reason it is sometimes refused:
+
+- on an **unweighted** attachment `fromVertex` always works — vertex *v* is array
+  index `2v`, exactly;
+- on a **weighted** one it works while every vertex the run covers has exactly one
+  bone on it, and rigc computes the true start index for you (which is *not*
+  `2v` — earlier multi-bone vertices push it along);
+- on a **multi-bone** vertex it is a compile error, and deliberately so. One
+  `x, y` for such a vertex is not a thing the array can hold: its world offset is
+  `Σ weightᵦ · Mᵦ · offsetᵦ` over its bones, so a single pair only means what you
+  meant if every influencing bone happens to share one world matrix. rigc will not
+  guess. Either key the control bone instead — which is what a rigc-generated ring
+  or ribbon mesh is *for* — or write the bind-space pairs yourself and start the
+  run with `offset`. The refusal tells you the index that vertex starts at.
+
+**The curve eases the blend.** A deform timeline has exactly one channel and
+`readCurve` builds it between **0 and 1** — the fraction of the way from this key's
+geometry to the next one's. So a named `ease` behaves as it does anywhere, and a
+raw `curve` is 4 numbers whose value axis runs 0..1, not the range of your vertex
+offsets.
+
+rigc refuses six things here, and the first is the quietest defect in the whole
+animation half of the format:
+
+| You wrote | You get |
+| --- | --- |
+| a run that ends past the array | `the run starts at deform index 4 and is 6 long, which ends at 10; this attachment's deform array is 8 long (4 vertices)` |
+| an odd `offset` | `offset 3 is odd. The deform array is x, y pairs, so an odd start puts every x of this run on a y` |
+| an odd number of `vertices` | `"vertices" holds 3 numbers; the deform array is x, y PAIRS` |
+| `fromVertex` on a multi-bone vertex | `"fromVertex" counts VERTICES, and this attachment is weighted … vertex 2 has 2 of them` |
+| an attachment that is not there | `slot "flat" in skin "default" has no attachment "flatt" (it has: flat)` |
+| a deform on a region attachment | `a deform timeline keys the vertices of an attachment, and this one is a "region"` |
+
+The overrun is the one to fear. `readAnimation` copies with
+`Utils.arrayCopy(vertices, 0, deform, offset, vertices.length)` into a
+`Float32Array`, and writing past the end of a typed array is a **no-op in
+JavaScript** — no throw, no warning, no `NaN`. A run one pair too long loses its
+tail and deforms the rest of the mesh correctly, which looks nearly right, and
+"nearly right" is the hardest kind of wrong to find.
+`A35_DEFORM_KEYS_FIT_THE_ATTACHMENT` checks all of it from the other side, on the
+emitted file, measuring the array's length from the attachment rather than assuming
+an encoding.
+
 ---
 
 ## 5. Reading a failure
@@ -857,6 +1144,14 @@ the frequent ones, verbatim:
 | `vertexCount N wants M unweighted numbers and "vertices" holds K` | fix the count or the array; they decide the encoding between them |
 | `end names slot "X", which this rig does not declare` | fix the clipping attachment's `end`, or add the slot |
 | `bone "X" takes its position from …, which needs a cut manifest` | R8 — pass `--manifest`, or write literal `x`/`y` |
+| `animation "A" keys unknown ik constraint "X"; the rig declares ik constraint(s): …` | §4.9 — fix the name, or declare the constraint in the rig spec |
+| `animation "A" keys "X" as an ik constraint, but the rig declares it as a "transform" constraint` | §4.9 — a timeline's target resolves by name AND type; put the entry under the right group |
+| `ik constraint "X": key 0 names "softness" and key 1 (t=…) does not` | §4.9 — every key is read with its own default, so state the field on every key or on none |
+| `ik constraint "X" (t=…): mix is 1.5, outside 0..1` | §4.9 — an IK mix is a percentage; a transform mix is unbounded |
+| `deform …: the run starts at deform index 4 and is 6 long, which ends at 10; this attachment's deform array is 8 long` | §4.11 — shorten the run or move its start; the parser would drop the tail in silence |
+| `deform … (t=…): offset 3 is odd` | §4.11 — the deform array is `x, y` pairs, so a run starts on an even index |
+| `deform …: "fromVertex" counts VERTICES, and this attachment is weighted … vertex 2 has 2 of them` | §4.11 — key the control bone, or write bind-space pairs and start with `offset` |
+| `deform …: slot "X" in skin "default" has no attachment "Y" (it has: …)` | §4.11 — fix the placeholder name |
 
 ### 5.2 Assertions — the gate
 
@@ -917,6 +1212,8 @@ The report prints one line per assertion:
 | `A31_DRAW_ORDER_OFFSETS_RESOLVE` | both | a draw-order key names a slot the skeleton does not have, offsets one slot twice, puts a slot outside the slots array, or lists its offsets out of slot order (§4.7). The only assertion that runs **before** `A00` — the last of those shapes makes the loader spin rather than return, so the round trip is refused instead of attempted |
 | `A32_EVENT_KEYS_RESOLVE` | both | an event key fires a name the skeleton's `events` block does not declare, sits earlier in time than the key before it, or sets `volume`/`balance` on an event with no `audio` (§4.8). **SKIP** when no animation carries an event timeline |
 | `A33_VERTEX_ATTACHMENT_GEOMETRY` | both | a bounding box or clipping polygon whose `vertexCount` is missing or disagrees with its vertex array, a weighted run that decodes to the wrong number of vertices or an out-of-range bone index, or a clipping `end` naming a slot the skeleton does not have (§3.4). **SKIP** when the skeleton carries neither type |
+| `A34_CONSTRAINT_TIMELINE_TARGETS` | both | an `ik` or `transform` timeline names a constraint the skeleton does not declare, names one of the other type, or carries no keys at all (§4.9, §4.10). The last is silent: the parser reads key 0, finds nothing, and skips the timeline. **SKIP** when no animation carries one |
+| `A35_DEFORM_KEYS_FIT_THE_ATTACHMENT` | both | a deform key's run runs past the end of the attachment's deform array, starts on an odd index, holds an odd count of numbers or a non-finite one, or names a skin/slot/attachment triple that does not resolve (§4.11). The overrun is the quiet one — the parser copies into a `Float32Array` and drops the tail. **SKIP** when no animation carries a deform timeline |
 
 `both ◑` marks a mixed assertion: its validity half always runs and its policy
 clauses are gated by profile.
@@ -947,10 +1244,13 @@ Two more limits that are not errors but will shape what you can attempt:
   region covers its whole page, `pma: false`. To reproduce a skeleton whose art
   ships as a packed atlas you either supply loose PNGs and let rigc build its own
   atlas, or hand the packed atlas to `validate`/`bench` alongside the candidate.
-- **Sequences, `drawOrderFolder`, event timelines and deform timelines** are walked
-  by the validator but are not motion-spec properties: the track table in §4.4 is
-  the complete list of what a *track* can key, and §4.7's `drawOrder` is the only
-  timeline outside it.
+- **`sequence` timelines, `drawOrderFolder` and `slider` / `path` constraint
+  timelines** are walked by the validator (so `A05` checks their curves and `diff`
+  counts their keys) and cannot be *written*: there is no motion-spec property for
+  any of them. The two constraint groups are blocked one level down — rigc emits no
+  `path` or `slider` constraint to key. Everything a motion spec **can** key is
+  §4.4's track table plus the five families that sit beside `tracks`: `drawOrder`
+  (§4.7), `events` (§4.8), `ik` (§4.9), `transform` (§4.10) and `deform` (§4.11).
 
 ---
 
@@ -2772,3 +3072,119 @@ answer read off the exports:
 
 If one of those turns out to matter, it belongs in the run's `log.md` as something
 the frames had to teach you — not here.
+
+---
+
+## 11. Reading a pose you were given — `rigc pose`
+
+```bash
+bun cli.ts pose --images path/to/parts --frame path/to/poseA.png [--out pose.json]
+```
+
+Every other command in this guide takes something you wrote and tells you about
+it. This one runs the other way: it takes a **picture the user already has** and
+reports, for each loose part PNG, where that part sits in it — `x`, `y`,
+`rotationDeg`, `scale` — plus a residual saying how well the placed part explains
+the frame's pixels underneath it.
+
+Reach for it when a request arrives as *"make it go from this picture to this
+one"*. Read both frames, write the two key poses into the rig and the motion from
+the numbers it gives you, and spend your loops on the part no instrument can
+measure: the movement between them.
+
+📘 **The recipe that consumes this report is [MOTION.md](MOTION.md)** — how these
+placements become a rig and a motion, what goes between two key poses when nothing
+was given for the in-betweens, and how to spread candidates so a `vote` ballot
+informs.
+
+### 11.1 It measures an input, so nothing here is a score
+
+🚨 **No number in this report has a pass bar, and none of them is a grade.** The
+distinction is not modesty, it decides how to read the output. `check` and `bench`
+compare a build against a reference, so their numbers mean *how close*. A pose
+frame is not a reference — it is a **given condition**, and once the spec states
+those coordinates there is nothing left to be close to. The residual exists so you
+know **how far to trust each placement** and **where two answers are equally
+good**.
+
+That is why the command's output is shaped as help rather than as a verdict:
+
+- a placement that matches nowhere is **refused by name** and its best guess is
+  still printed, because a refusal tells you not to trust a number rather than
+  hiding it;
+- two near-equal optima are reported as **both**, flagged `ambiguous`, never
+  silently resolved;
+- a part whose rotation genuinely does not matter is reported as having a **free
+  degree of freedom**, not as a failure.
+
+### 11.2 The coordinate contract
+
+Placements are in the **frame's own pixels: y down, origin top-left** — the same
+convention a cut manifest uses, and the `space` field of every report repeats it.
+
+- `x`, `y` — where the part image's own centre, `(width / 2, height / 2)`, lands.
+- `rotationDeg` — **screen** degrees, positive turning **clockwise** on screen.
+- `scale` — uniform, as **frame pixels per part pixel**.
+
+Reconstruct a part pixel `p` as `centre + scale · R(rotationDeg) · (p − (width/2,
+height/2))`. To get to Spine's y-up, counter-clockwise world, use the two
+conversions that already exist and open-code neither:
+`screenToSpineDegrees(rotationDeg)` and `cropToSpineY(y, frameHeight)`
+([`src/transform.ts`](../src/transform.ts)).
+
+### 11.3 The fields, and what each one is for
+
+Per part:
+
+| Field | Meaning |
+| --- | --- |
+| `part`, `path`, `width`, `height` | the PNG, by the name every message uses |
+| `placement` | the best placement found — `null` **only** for `empty-part` and `larger-than-canvas`, where nothing was searched |
+| `alternates` | other optima worth reporting, best first. Non-empty means the answer was not unique |
+| `ambiguous` | at least one alternate is inside the ambiguity margin. **Choose with something this instrument cannot see** — anatomy, the other frame, or `rigc vote` |
+| `rotationFree` | the part is self-similar under rotation, so `rotationDeg` is a placeholder and the value is yours |
+| `rotationSelfSimilarity` | the number `rotationFree` is a threshold on. A part just over the line is worth a look |
+| `refusal` | `{ reason, detail }` or `null`. Reasons: `no-match`, `larger-than-canvas`, `empty-part` |
+| `coarse` | the grid this part was actually searched on. A handful of cells means the part is small relative to the frame and the first pass had little to go on |
+| `notes` | the same facts in prose, in the order they were found |
+
+Per placement:
+
+| Field | Meaning |
+| --- | --- |
+| `residual` | alpha-weighted mean absolute colour error over the part's own footprint, `0..1`. **Lower is better explained** — that is all it means |
+| `unexplained` | the share of the part's material that disagrees with the frame at this placement. **Read this next to the residual** — see §11.4 |
+| `offCanvas` | the share of the part's material that falls outside the frame at this placement |
+| `footprint` | frame pixels of material the placement accounts for; the tie-break between two equal residuals |
+| `bbox` | the axis-aligned box the placed part occupies, in frame pixels |
+
+The report also carries `frame.background` (how the picture's empty space was
+identified — a flat colour, transparency, or `unknown`), `search` (every window
+and threshold that was applied), and `caveats`.
+
+### 11.4 What it cannot see — read this before using the numbers
+
+- ⚠️ **Residuals degrade under occlusion, and there is no depth solver here.** A
+  part drawn *behind* another has the occluder's pixels where its own should be, so
+  its residual rises **at the correct placement**. `unexplained` separates the two
+  readings: a middling residual with a high `unexplained` usually means *right
+  place, seen through something else*, not *wrong place*. The only robustness in
+  the objective is that it is measured on the part's **own alpha footprint** — a
+  part is never charged for pixels of the picture it does not claim. Weigh
+  accordingly; do not treat either number as a verdict.
+- ⚠️ **A search window that does not contain the truth does not reliably refuse.**
+  A part shrunk inside the region it came from still explains those pixels, so the
+  answer is the best placement available *inside* `--scale` / `--rotation` and its
+  residual can look reasonable. This is why the window is a reported field: if the
+  numbers surprise you, check `search` before you trust them.
+- ⚠️ **A frame whose border has no dominant colour reports `background.unknown`.**
+  Every pixel then counts as material, the silhouette signal is gone, and the
+  residual is colour agreement alone. The report says so rather than being quietly
+  weaker.
+- **An `ambiguous` part is genuinely ambiguous.** Two identical limbs, a part that
+  fits its own silhouette at more than one angle, and a shape whose interior is one
+  flat colour all look like this. The instrument has run out; that is what
+  `rigc vote` is for.
+- **One frame per call.** Several key poses are several calls, and correlating A
+  with B — which placement of a repeated part belongs to which limb, across two
+  frames — is the authoring job, not this tool's.