spine-rigc 0.5.0 → 0.7.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,15 @@ 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
+
+# …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`,
@@ -112,16 +126,31 @@ 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 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 |
+
+`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). 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",
+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 +160,10 @@ 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]
+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]
 ```
 
 - **`explain`** is the one to reach for when a rig compiles but looks wrong. It
@@ -144,12 +177,46 @@ 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.
+- 🗳️ **`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.
 
 ---
 
@@ -294,7 +361,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 +549,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
 
@@ -582,6 +649,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
@@ -592,6 +662,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]` |
@@ -650,7 +727,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
@@ -784,6 +861,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
@@ -822,6 +1125,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
 
@@ -867,7 +1178,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 |
@@ -882,6 +1193,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.
@@ -912,16 +1225,21 @@ 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).
 
 ---
 
 ## 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
@@ -1557,13 +1875,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

package/docs/PROMPTING.md

@@ -0,0 +1,106 @@
+# Prompting an AI to author with rigc
+
+This page is for the person **operating** an AI agent — any AI agent — that will
+author a rig with rigc. It is not authoring guidance; that is
+[AUTHORING.md](AUTHORING.md), and the agent should read that file, not this one.
+This page tells you what to put in the prompt, and it earns its claims from a
+measured case: in August 2026 a deliberately small model — Gemini 3.7 Flash on
+the Antigravity harness — authored a benchmark rung unattended for three hours,
+and every stumble below is one it actually made, priced by the instruments in
+[PILOT.md](https://github.com/firejune/rigc/blob/main/docs/PILOT.md)'s protocol. A large model makes fewer of these mistakes
+unprompted; the clauses cost you three lines and make the small model's run
+land and the large model's run land cleaner.
+
+## The prompt skeleton
+
+For ordinary use (not a benchmark), the whole prompt is short:
+
+> Author a Spine rig with rigc for <what you want>. The images are in
+> `<dir>`. Read `docs/AUTHORING.md` in full before writing either spec —
+> sections 1–5 are the two file formats and the failure map, section 8 is how
+> to fit poses against picture references, section 10 is the editor's
+> conventions. Build with `rigc build`, keep going until `rigc validate` is
+> green, and treat every named failure as pointing at the file to change.
+
+Then add the clauses below. If you are running the **benchmark**, do not
+improvise a prompt at all — hand the agent
+[pilot/rung3-runner-prompt.md](https://github.com/firejune/rigc/blob/main/docs/pilot/rung3-runner-prompt.md) verbatim; it
+carries the honesty rule, and an improvised summary of that rule is how a run
+stops being scorable.
+
+## Five clauses the pilot paid for
+
+**1. Any search loop must print progress and carry a time-box.**
+The pilot wrote a pose-fitting script with no output and no bound, and its
+operator spent part of the evening deciding whether a silent 99 %-CPU process
+was working or hung. (It was working — but nobody could tell.) Say:
+
+> Long-running scripts must print one progress line per unit of work and state
+> an expected total up front. If a search would exceed ten minutes, stop and
+> narrow it instead.
+
+**2. Intermediate results go to files, not scrollback.**
+The pilot's first fitters printed results to stdout; a crashed step would have
+lost the lot. It later switched to JSON files on its own — start there. Say:
+
+> Write measured values (placements, angles, fitted poses) to files in the
+> working directory as you go. Treat your transcript as disposable.
+
+**3. Point the fitting method at AUTHORING §8, by number.**
+Given frames to match, the pilot's first instinct was a nested grid over every
+knob at once — tens of thousands of renders per frame. §8 describes the cheap
+loop (one knob at a time, render back, keep what the measurement keeps). The
+pilot had the file "in hand" and did not apply the section until it had burned
+hours. Say:
+
+> Fit poses the way AUTHORING §8 does — one variable at a time against a
+> render-back measurement. Do not grid-search several knobs jointly.
+
+**4. Keys are structure, not samples.**
+A fitter produces one pose per frame, and the pilot keyed nearly every one of
+them. The result *placed* its parts well — and still scored poorly on every
+timing measure, because animation data is sparse keys plus interpolation
+(AUTHORING §10.3–§10.4), and a key on every frame is a pixel transcription
+wearing a skeleton. Say:
+
+> Key extremes and contacts, then let curves carry the in-betweens, per
+> AUTHORING §10.3–10.4. If your fitted poses disagree with a curve, move the
+> curve, not key count. Also §4.4: when a bone's two axes need different
+> timing or easing, key the single-axis timelines, not the paired one.
+
+**5. Keep the loop log live.**
+The pilot wrote its `LOOP.md` at the end, from memory — two entries for a
+three-hour session, with eight generations of fitting scripts invisible
+between them. A log written afterwards records the story, not the work. Say:
+
+> Append to `LOOP.md` at the moment each build/measure/change step happens,
+> not at the end. One line per step is enough.
+
+**6. Make the agent typecheck its own helper scripts.**
+Bun strips types and runs, so an agent can call methods that do not exist and
+watch the script fail — or worse, silently misbehave — without ever learning
+the API was imagined. The pilot left behind a helper written against
+spine-core methods that were never real; the repository's `typecheck` gate
+caught it at landing, hours too late to help the run. Say:
+
+> After writing any helper script, run `bunx tsc --noEmit <file>` (or the
+> project's `typecheck` task) before trusting its output.
+
+## What you do not need to say
+
+The same pilot, unprompted, did all of this correctly: it looped
+`build → validate` until green and read the named failures as pointers; it ran
+the whole thing without a human answer for three hours; it killed its own
+stray processes; it recorded its model name honestly; and under the benchmark
+protocol it ran the scored diff exactly once, at the end, editing nothing
+after. The tool's own error surface carries that part of the conversation —
+prompt for the five clauses above and then let the agent work.
+
+## If you are scoring the run
+
+That is a different document: [PILOT.md](https://github.com/firejune/rigc/blob/main/docs/PILOT.md) is the protocol,
+`pilot/rung3-runner-prompt.md` is the exact prompt, and the evaluator sheet it
+names is for the judge only. The one rule that reaches this page: **never put
+baseline figures, reference structure, or previous runs' measures into the
+runner's prompt** — a number in the prompt is a target, and a run that aimed
+at a target measured nothing.