spine-rigc 0.22.2 → 0.23.0

package/docs/INGEST.md

@@ -50,12 +50,22 @@ invent one.
 Two facts decide everything below, and they pull in opposite directions:
 
 1. **rigc reads compiled skeleton JSON in more places than you would guess.**
-   `validate`, `render`, `preview`, `vote`, `check` and `diff` all take a
-   `skeleton.json` path directly, and none of them needs a rig spec to do it.
-2. **rigc cannot write one back.** There is no command that edits a skeleton, no
-   importer, and no route from skeleton JSON to specs. The only thing that produces a
-   skeleton is `build`, and `build`'s input is a rig spec plus a motion spec.
-   ⇒ **Every route that ends in a changed file goes through transcription** (§2).
+   `validate`, `render`, `preview`, `vote`, `check`, `diff` and — since #569 —
+   `ingest` all take a `skeleton.json` path directly, and none of them needs a rig
+   spec to do it.
+2. **rigc still cannot EDIT one.** There is no command that opens a skeleton and
+   changes it. The only thing that produces a skeleton is `build`, and `build`'s
+   input is a rig spec plus a motion spec.
+   ⇒ **Every route that ends in a changed file goes through the specs** — and
+   since #569 there are two ways to get them: write them (§2, transcription) or
+   have `ingest` write them for you from the file itself (§2.0).
+
+   ⚠️ This clause read *"rigc cannot write one back… no route from skeleton JSON
+   to specs"* until 2026-09-17, and the half that was wrong is the second half.
+   The route exists now and its contract is an equality — `build(ingest(x))` is
+   `x`, byte for byte — which is a stronger statement than anything transcription
+   could make. What survives is the first half: nothing **edits** a skeleton, and
+   the specs remain the only thing a change is expressed in.
 
 ### 0.1 The table
 
@@ -71,6 +81,7 @@ an upstream `license.txt` (Appendix, and [NOTICE.md](../NOTICE.md)).
 | **`vote --candidate <a> --candidate <b>`** | ✅ **yes, on either side** | a ballot page. Pairing a foreign export against your own transcription is a legitimate ballot, and the panes carry no paths |
 | **`check --candidate <skeleton.json> --frames <dir>`** | ✅ **yes** | ⭐ it reads **frames and never a reference skeleton**, so a foreign export enters this one *twice over*: as the candidate, or — via `render` — as the source of the frames. §1.4 |
 | **`diff <candidate.json> <reference.json>`** | ✅ **yes, both sides** | 49 structural measures over bones, slots, attachments, constraints, animations and events. ⛔ **Blind to every coordinate** — §1.3 |
+| **`ingest <skeleton.json> --out <dir>`** | ✅ **yes — and it is the only reader that WRITES specs** | the `.json` alone; no atlas, no art, no project file. Out come `rig.json`, `motion.json` and a findings report, such that `build`ing them reproduces the skeleton it read **byte for byte**. The seventh reader, and the one that ends §2's hand work — §2.0 and §5 |
 | **`pose --images <dir> --frame <png>`** | ⛔ **not the skeleton** | loose part PNGs and one picture. A packed atlas page is not loose parts, and pointing it at one produces a confident answer about nothing — §5 |
 | **`explain --rig … --motion … --out …`** | ⛔ **no** | rig spec + motion spec. It explains **what you wrote**, which makes it a transcription instrument rather than a reading one — §1.5 |
 | **`build --rig … --motion … --images …`** | ⛔ **no** | specs in, skeleton out. The only writer in the toolchain, and the reason §2 exists |
@@ -212,9 +223,11 @@ Spine runtime plays it, whatever rigc's own rasteriser or validator thinks.
 
 ### 1.3 `diff` — and the two things it cannot see
 
-`diff` takes two compiled skeletons and reports 49 measures in eight groups. Both
-sides may be foreign; the interesting pairing during ingest is **your transcription
-against the export it came from**:
+`diff` takes two compiled skeletons and reports 49 measures in eight groups, plus two
+blocks that report and gate nothing: the `(reported)` measures beside `attachments`
+and `animations`, and the `skeleton` header block at the top, which measures the stage
+(issue #578). Both sides may be foreign; the interesting pairing during ingest is
+**your transcription against the export it came from**:
 
 ```bash
 rigc diff work/t3/skeleton.json \
@@ -227,6 +240,10 @@ rigc diff
   reference  …/examples/3-timing-and-spacing/export/3-timing-and-spacing-ess.json
   ..         bones=3/3  slots=2/2  skins=1/1  attachments=2/2  constraints=0/0  animations=2/2  events=0/0   (candidate/reference)
 
+  skeleton (reported)   (no mean)   over 2 measures  — the stage, which no reading of the frames could decide
+      1.000  stage_present                1/1         both sides declare a setup-pose stage, or neither does  — …
+      1.000  stage_box                    4/4         the stage is the same box (x, y, width, height, exactly as stated)  — …
+
   bones                 mean 1.000  over 8 measures
       1.000  count                        3/3         how many bones
       1.000  names                        3/3         the bone names themselves
@@ -253,11 +270,18 @@ Each pair is **matched / total**, where the total is the larger of the two sides
 count of `2/3` means one side has three of something and only two were matched — and
 it does not say *which* side has three. The `..` line above is where you read that.
 
-⛔ **`diff` is blind to every coordinate.** No measure reads a bone's
-`x`/`y`/`rotation`, an attachment's offset, or a key's value — only *presence*,
-*names*, *counts*, *order* and *kinds*. §4.1 moves a pivot 236.5 units and every one
-of the 49 measures still reads **1.000**. ⇒ Never take a green `diff` as evidence that
-a geometric edit did not land, and never take it as evidence that one did.
+⛔ **`diff` is blind to every coordinate a bone, an attachment or a key carries.** No
+measure reads a bone's `x`/`y`/`rotation`, an attachment's offset, or a key's value —
+only *presence*, *names*, *counts*, *order* and *kinds*. §4.1 moves a pivot 236.5
+units and every one of the 49 measures still reads **1.000**. ⇒ Never take a green
+`diff` as evidence that a geometric edit did not land, and never take it as evidence
+that one did.
+
+⚠️ **The one exception is the skeleton's own declared box**, and it is an exception to
+the sentence and not to the rule: `skeleton.stage_box` compares four world numbers,
+but they are numbers an exporter *wrote into the header* rather than a pose anything
+measured, and the block they sit in gates nothing. Moving a pivot does not move them
+either.
 
 ⛔ **And its ratios are not a score.** [`src/diff.ts`](../src/diff.ts) says so in the
 type itself (*"Unweighted mean of the measures below. NOT a quality score"*), and the
@@ -377,17 +401,70 @@ is fine — it is not created.
 
 ---
 
-## 2. Transcription — the route that makes a foreign skeleton yours
+## 2. Getting specs out of a skeleton
+
+Everything in §1 reads. To **change** anything you need specs. There are two routes
+to them and you should almost always take the first.
 
-Everything in §1 reads. To **change** anything you need specs, and getting specs out
-of a skeleton is a job rigc does not do for you: the numbers come out of the JSON by
-hand, into a rig spec and a motion spec, and `build` emits a new skeleton from those.
+### 2.0 `ingest` — let the tool write them
+
+```bash
+rigc ingest examples/spineboy/export/spineboy-ess.json --out specs/ --art none
+rigc build --rig specs/rig.json --motion specs/motion.json --atlas-in examples/spineboy/export/spineboy.atlas --out spine
+rigc diff spine/skeleton.json examples/spineboy/export/spineboy-ess.json
+```
 
-⚠️ **Say this to the user before starting, because it is the part that surprises.**
-Transcription is not a conversion step you run; it *is* the work. What you get for it
-is that the file becomes editable by declaration — after transcription a pivot move is
-two numbers in a spec (§4.1) and a new animation is an added block (§4.3), where
-before it was a hand-edit of emitted JSON with nothing checking it.
+`ingest` reads the skeleton — **only** the skeleton — and writes `rig.json`,
+`motion.json` and `findings.json`. The contract is an equality rather than a
+rulebook: `build(ingest(x))` is `x`, byte for byte on `skeleton.json`, and the
+atlas comes back with the same region blocks (as a multiset — the page order is in
+no field of the file). `bun run selftest` holds every rig this repository builds to
+that on every run, which is the one gate here that compares an emitted file against
+a file rigc did not write.
+
+**What it will not do is invent.** Everything the spec format cannot hold is a
+finding with a code — `BLOCK` for a construct the rebuild will be missing, `JUDGE`
+for the two values a skeleton does not carry, `LOSS` for the one number rigc
+re-derives on purpose. A blocker exits non-zero and still writes both files.
+
+**Two values are not in a skeleton**, so `ingest` asks rather than guesses:
+
+- **the stage** (`skeleton.width`/`height`) — an editor export carries none, and
+  `--stage x,y,w,h` is how you supply it. Posing the rig would give the *animated*
+  extent, which is a different number from the setup box, so it is not derived. It
+  is also the value that costs least to get wrong: no measure `diff` reports reads
+  the skeleton header at all, so an absurd box is green everywhere;
+- **each animation's duration** — the format has no such field. The largest key time
+  is used, stated in the motion spec's `note`, and recorded as a finding per
+  animation. Edit it if you know the real number.
+
+And one flag for what the skeleton also does not encode: `--art loose` (the default)
+names an `image` per attachment for `build --images`, `--art none` states
+`width`/`height` for `build --atlas-in`. [AUTHORING §0.3](AUTHORING.md) is the loop
+in full.
+
+📝 Both written specs carry a `note` saying they are decompiled and naming the file
+they came from. Leave it there — §2.4 is why.
+
+### Transcription — the route that made a foreign skeleton yours
+
+⚠️ **The rest of §2 is the route that existed before #569, and it is kept because
+the reading it produces is still the right one** — it is what an author does *after*
+`ingest`, and it is what to fall back on for the constructs `ingest` reports as
+blockers. The numbers come out of the JSON into a rig spec and a motion spec by hand,
+and `build` emits a new skeleton from those.
+
+What you get for it is that the file becomes editable by declaration — a pivot move
+is two numbers in a spec (§4.1) and a new animation is an added block (§4.3), where
+before it was a hand-edit of emitted JSON with nothing checking it. That is now what
+`ingest` hands you in one command; the sections below are how to read and change what
+it hands you, and every rule in them applies to a spec `ingest` wrote.
+
+📌 **The cost this section used to warn about is measured, and it is why §5 changed.**
+The smallest skeleton of the corpus behind [#569](https://github.com/firejune/rigc/issues/569)
+transcribed to a **257,422-byte** rig spec, of which 91.8 % is the six geometry
+arrays — numbers, not decisions. A 558-line prototype decompiler reproduced 100 % of
+it, and the only differing paths were the name and the `note`.
 
 ### 2.1 The workflow
 
@@ -409,6 +486,32 @@ before it was a hand-edit of emitted JSON with nothing checking it.
    copying and not a detail. Leave `invariants` out entirely — it describes rigc's own
    formations, and an absent field makes an archetype assertion `SKIP`, never pass
    (AUTHORING §3.7).
+
+   📌 **Transcribe the export's empty slots too** — the ones no skin fills anywhere.
+   Such a slot still holds an index in the array, and everything below it is counted
+   from that index. Write it as `{ "name": …, "bone": … }` with no `attachment`, or
+   with `"attachment": null` if you prefer to say it out loud; either way it comes
+   back. Before issue #575 it did not: `build` dropped it in silence, so two exports
+   declaring 53 and 61 slots came back at 51 and 57 with a green gate, and `diff`
+   read 0.962 and 0.934 against the file they had been read from. If a
+   transcription's `slots.count` is under 1.000, this is the first thing to check.
+
+   ⚠️ **No skeleton in `examples/` has one**, which is why the corpus never showed
+   this: all twelve exports fill every slot they declare from some skin. What they
+   *do* carry is the neighbouring shape — a slot a skin DOES fill whose setup pose
+   shows nothing (34 of `spineboy-pro`'s 52 slots). Both are written the same way in
+   the file: `attachment` simply absent.
+
+   ⚠️ **If the export's `skeleton` block carries no `x`/`y`/`width`/`height`, write
+   `"width": null, "height": null` and do not invent one** (issue #578). That shape is
+   common — the twelve exports in `examples/` all carry the four, and 37 of 37 exports
+   in one production corpus carry none of them — and until the `null` pair existed the
+   only two moves were a made-up stage or a file that could not be transcribed. The
+   made-up stage was the worse one: it is a number nothing in this toolchain could
+   contradict, so it survived every gate and every `diff` in silence. Now it does not —
+   `diff`'s header block reports `skeleton.stage_present` and `skeleton.stage_box`
+   against the source you are copying. Copy the four numbers when they are there;
+   state the absence when they are not.
 4. **`explain`, then `build`.** `explain` first, because it prints what you wrote in a
    shape you can compare against the export by eye (§1.5) and it never gates. Then
    `build` under `--profile spine`.
@@ -656,12 +759,22 @@ other one is this project's own renderer and archetype policy.
 | **renderer policy** (7) | `A11_NO_CLIPPING_ATTACHMENTS`, `A12_NO_DARK_COLOR`, `A13_MESH_BUDGET`, `A14_NO_FULL_FRAME_MESH`, `A15_IDLE_NO_MESH_BONE_KEYS`, `A19_OVERLAY_PNGS_HAVE_ALPHA`, `A27_REGION_NAME_MATCHES_PAGE_FILENAME` |
 | **archetype policy** (8) | `A21_MESH_RIM_PINNED`, `A24_AXIS_SPACE_STROKE`, `A25_DETACHED_BONE_PARENTAGE`, `A26_SLOT_DRAW_ORDER`, `A28_RIBBON_ROWS_SHARE_WEIGHTS`, `A29_STROKE_WITHIN_CONTACT_DEPTH`, `A30_STROKE_WITHIN_CAP_CONTAINMENT`, `A39_DEFORM_KEEPS_TRIANGLE_WINDING` |
 
-Three further rules — **`A06`**, **`A08`** and **`A20`** — are *mixed*: their validity
-clauses run in both profiles and their policy clauses only under `spine-html`. `A06`'s
+Two further rules — **`A06`** and **`A20`** — are *mixed*: their validity clauses run
+in both profiles and their policy clauses only under `spine-html`. `A06`'s
 size-vs-PNG check is validity; one-part-per-page coverage, rotation and premultiplied
-alpha are policy. `A08`'s attachment→region join is validity; requiring the two names
-to be *identical* is policy. `A20`'s weight coherence is validity; requiring a mesh to
-be weighted at all is policy.
+alpha are policy. `A20`'s weight coherence is validity; requiring a mesh to be
+weighted at all is policy.
+
+**`A08` was the third until [#574](https://github.com/firejune/rigc/issues/574).** Its
+policy clause required a skin entry's placeholder to be spelled exactly like the region
+it resolves to — a rule the renderer it was gated under never performed, since
+`spine-html` keys its images on the atlas region name reached through the attachment's
+`path` and reads no placeholder at all. Measured before retiring it: the clause fired
+on **0** attachments across the whole example corpus (no export in `examples/` carries
+a `path` field), and on every rigc rig whose placeholder is not its PNG's basename —
+which is what `path` exists for (AUTHORING §2, R5) and what a placeholder two named
+skins share is emitted as. So it was policy that only ever refused this compiler's own
+correct output.
 
 ⚠️ **`--profile spine-html` on foreign data produces a wall of failures that mean
 nothing about the file.** Same `spineboy-pro.json`, same atlas, one flag changed — the
@@ -918,10 +1031,14 @@ Three things to read out of that, in order:
 something is invisible to every measure in that report. Pair it with a `check` against
 frames rendered from the original.
 
-⚠️ **Do not rename toward what a rule seems to want.** `A08`'s name-identity clause and
-`A27`'s region-name-matches-page-filename are both `spine-html` policy (§3.3): under
-the default profile they do not fire, and renaming somebody's attachments to satisfy a
-policy they never opted into is a change with no benefit to them.
+⚠️ **Do not rename toward what a rule seems to want.** `A27`'s
+region-name-matches-page-filename is `spine-html` policy (§3.3): under the default
+profile it does not fire, and renaming somebody's attachments to satisfy a policy they
+never opted into is a change with no benefit to them. `A08` carried a name-identity
+clause of the same kind until
+[#574](https://github.com/firejune/rigc/issues/574) retired it, and that one is the
+argument's own case study — the rename it seemed to want was one no renderer had ever
+asked for.
 
 ### 4.3 Extending a foreign skeleton with a new animation
 
@@ -1010,12 +1127,36 @@ dependency *can* read it and rigc *does not*:
 that already has the reader, not a parser to write. But it is not there, and nothing on
 this page works on a `.skel` today. Re-export as JSON.
 
-🚫 **No skeleton-to-spec decompiler.** Nothing turns skeleton JSON back into a rig spec
-and a motion spec. §2 is hand work, and that is the current state rather than a
-temporary one: a decompiler would have to invent the things the spec format exists to
-make explicit — which pivot, which generator, which invariant — and the compiler's own
-rule is that it never invents a value that is not in the spec. ⚠️ Not to be confused
-with the *atlas* importer below, which is a different direction and does exist.
+✅ **A skeleton-to-spec decompiler exists: `rigc ingest` (§2.0). This entry used to
+refuse one, and all three of its reasons were measured and refuted** — issue
+[#569](https://github.com/firejune/rigc/issues/569), 2026-09-17. The paragraph is
+kept below rather than deleted, because what it got wrong is more useful than a
+clean page:
+
+> 🚫 ~~**No skeleton-to-spec decompiler.** Nothing turns skeleton JSON back into a rig
+> spec and a motion spec. §2 is hand work, and that is the current state rather than a
+> temporary one: a decompiler would have to invent the things the spec format exists to
+> make explicit — **which pivot, which generator, which invariant** — and the compiler's
+> own rule is that it never invents a value that is not in the spec.~~
+
+| clause | what the measurement said |
+| --- | --- |
+| *which pivot* | ⛔ **refuted.** A bone's setup transform is in the skeleton, in full. 3,951 bones across 37 production exports and 15 rigs built from this tree were transcribed with **zero** decisions, and `diff`'s six bone measures — count, names, `parent_by_name`, order, `length_present`, `inherit_present` — read **1.000** on every file that built |
+| *which generator* | ⛔ **refuted, and the premise is the error.** A decompiler must choose **no** generator. A generator is a *model* (`src/rig.ts`: *"they encode a deformation model … and a model is not a table of numbers"*); the skeleton holds geometry, and geometry is what the rig spec's authored form takes. Inferring a model would be the invention this clause feared; writing the numbers is its opposite. `gallery/look`'s four generator-built meshes came back as authored geometry and the rebuild is **byte-identical** — so a generator can always be flattened, and that is the direction the information flows |
+| *which invariant* | ⛔ **refuted by omission, and this page already said how.** §2.1 step 3: *"Leave `invariants` out entirely — an absent field makes an archetype assertion SKIP, never pass."* `ingest` writes none. A decompiled spec is 91.8 % geometry, 8.2 % structure and **0 % intent**, and it says so instead of certifying something nobody measured |
+
+⇒ **What survives is the stage, and one value is not "the things the spec format
+exists to make explicit".** The clause was not wrong that a decompiler meets an
+invention — it was wrong about *which*, and wrong that it is unavoidable: a refusal
+naming the field is what this repository does with a missing number everywhere else,
+and it is what `ingest` does here (§2.0). ⚠️ Not to be confused with the *atlas*
+importer below, which is a different direction and also exists.
+
+⚠️ **What `ingest` is still not.** It reads skeleton JSON and writes two spec files.
+It does not read a `.spine` project or a binary `.skel` (the two entries above stand
+unchanged), it does not read the atlas or the art, it does not **edit** a skeleton,
+and it makes no claim about whether an agent could have *produced* the numbers it
+copied — only that the spec can carry them and `build` reproduces the file from them.
 
 ✅ **A packer and an importer both exist now, so do not report them as gaps.** This
 non-goal used to read *"rigc emits one region per page and cannot do otherwise"*, and
@@ -1090,9 +1231,12 @@ something is drawn over them are readable through its own draw order and hierarc
 
 📎 To be exact about what is missing: rigc *can* lift a region's drawing back off a
 page — `extractRegion` does it, and the contour mesh generator uses it under
-`--atlas-in` — so what is absent is a **command**, not the capability. It refuses by
-name on a region packed `rotate: 90` (AUTHORING §0.2), which a foreign pack can be and
-rigc's own never is.
+`--atlas-in` — so what is absent is a **command**, not the capability. Since issue
+#570 that includes a region the pack **turned** (`rotate: 90`, `180`, `270`, or the
+older `rotate: true`), which a foreign pack routinely is and rigc's own never is: the
+lift transcribes `MeshAttachment.computeUVs`, the one routine in spine-core that
+states where a turned region's texels are, so what a generator measures does not
+depend on how the art was delivered (AUTHORING §0.2).
 
 🚫 **No `validate --fix`, and no normalisation pass.** Every recipe in §4 is a change
 you state in a spec and rebuild. A tool that rewrote somebody's export in place would

package/docs/SPEC_COVERAGE.md

@@ -12,7 +12,7 @@ Reproduce the measurements with `bun run fetch-examples && bun run bench:usage`
 
 > 🔼 **This note is dated and does not move; the measurements below are the corpus as it
 > stood on 2026-08-22 and stay as written. Its statements about what rigc *does* have gone
-> stale in six places, and the live ledger is [LADDER.md](https://github.com/firejune/rigc/blob/main/docs/LADDER.md):**
+> stale in the places listed here, and the live ledger is [LADDER.md](https://github.com/firejune/rigc/blob/main/docs/LADDER.md):**
 >
 > - **B2 is fixed** — A16 accepts `4.3`, `4.3.N` and `4.3.N-<suffix>`, so all twelve example
 >   exports pass it.
@@ -48,6 +48,18 @@ Reproduce the measurements with `bun run fetch-examples && bun run bench:usage`
 >   `length`/`scale`/`shear`/`inherit`/`skin`/`color` setup fields, slot `dark`/`blend`, region
 >   `path`/`scaleX`/`scaleY`/`color`, mesh `path`/`edges`/`color`, and the header's `fps` /
 >   `referenceScale` / `images`. Part 2's coverage tables predate all of it.
+> - **A08's name-identity clause is retired (issue #574, 2026-09-17)** — so every line below
+>   that calls A08 *mixed* or names it as policy describes a rule that no longer exists:
+>   §2.1's `region` row ("the region name == attachment name == PNG basename convention
+>   **A08** + **A27** enforce" — A27 still enforces its half, A08 enforces none of it),
+>   §2.2's classification row and its "Nine assertions are renderer-profile or
+>   profile-mixed" paragraph, §4.1's row (c), and §4.3's item 2. A08 is plain **validity**
+>   now and identical under both profiles. The measurement behind it: `spine-html` resolves
+>   art through the attachment's `path` and keys its images on the atlas region name, in
+>   every published version of it, so the clause was a rule no renderer performed — and it
+>   fired on **0** attachments in this corpus, because no export in `examples/` carries a
+>   `path` field at all. The executive summary's item 8 is the one A08 line here that was
+>   already right and has only got more so: A08 is a Spine-validity rule.
 >
 > **The measurements of the CORPUS (Part 3) have not moved and stay as written.**
 >

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spine-rigc",
-  "version": "0.22.2",
+  "version": "0.23.0",
   "description": "Rig compiler for Spine — declarative rig specs in, Spine 4.3 skeleton data out, verified by a spine-core round-trip. Built so AI agents can author rigs and check their own work; the output imports into the Spine editor.",
   "type": "module",
   "bin": {

package/skills/ingest/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ingest
-description: Work with a Spine skeleton.json somebody else authored — exported from the Spine editor or another tool — using rigc. Read and validate it, understand a complaint rigc raised about it, transcribe it into rigc specs, normalise, re-pivot or rename it, and extend it with an animation it does not have. Use when the input is an existing skeleton.json with its .atlas and page images rather than loose part PNGs. Not for Live2D file conversion or runtime tracking.
+description: Work with a Spine skeleton.json somebody else authored — exported from the Spine editor or another tool — using rigc. Read and validate it, understand a complaint rigc raised about it, decompile it into rigc specs with `rigc ingest`, normalise, re-pivot or rename it, and extend it with an animation it does not have. Use when the input is an existing skeleton.json with its .atlas and page images rather than loose part PNGs. Not for Live2D file conversion or runtime tracking.
 license: MIT
 compatibility: Requires Bun 1.2 or later and the npm package spine-rigc.
 ---
@@ -17,26 +17,48 @@ not do for you.
 
 - **Validation is never bypassed.** `validate` reads a foreign file as it is, and
   `build` writes nothing on a red gate — AUTHORING §0.
-- **The compiler never invents a value.** A transcription states every bone, slot
-  and key the specs need; what the export left implicit has to be written down
-  before it compiles — INGEST §2.
+- **The compiler never invents a value, and neither does the decompiler.** The
+  specs state every bone, slot and key; what the export left implicit is written
+  down before it compiles. `rigc ingest` obeys the same rule from the other side —
+  what it cannot read out of the skeleton is a named **finding**, never a guess —
+  INGEST §2.0 and §2.
 - **The validator's messages are the instructions.** A red line on an export is a
   fact about the file, and sometimes about the rule — INGEST §3 says which, and
   AUTHORING §5 names the file to change.
 
+## Start here: `rigc ingest`
+
+```bash
+rigc ingest hero.json --out specs/ --stage 0,0,1024,768
+rigc build --rig specs/rig.json --motion specs/motion.json --images parts/ --out build/
+```
+
+It reads the skeleton — **only** the skeleton — and writes the rig spec and motion
+spec that rebuild it, byte for byte. Two values are not in the file and it refuses
+rather than guessing them: the **stage** (`--stage`, an editor export carries none)
+and each animation's **duration** (the largest key time, recorded as a finding).
+Read `findings.json`: a `BLOCK` line means the rebuild will be missing something and
+the command exits non-zero. Keep the `note` both specs carry. INGEST §2.0.
+
 ## What this guide will not do
 
-rigc cannot write a skeleton back. There is no command that edits a `skeleton.json`
-and no route from it to specs, so every change goes through transcription — INGEST
-§0 and §2. `diff`'s ratios say how much of a reference's structure a candidate
-reproduces, so extending or renaming a foreign skeleton lowers them by design, and
-neither `validate` nor `diff` has a pass bar — INGEST §0 and §4.
+rigc still cannot **edit** a skeleton: there is no command that opens one and
+changes it, so every change is expressed in the specs — INGEST §0. `diff`'s ratios
+say how much of a reference's structure a candidate reproduces, so extending or
+renaming a foreign skeleton lowers them by design, and neither `validate` nor `diff`
+has a pass bar — INGEST §0 and §4.
+
+⚠️ This section said *"there is no route from it to specs, so every change goes
+through transcription"* until 2026-09-17. That route exists now and it is the first
+thing to reach for; transcription by hand is what you fall back on for a construct
+`ingest` reports as a blocker.
 
 ## Read, in this order
 
 1. [INGEST.md](../../docs/INGEST.md) — what every command will and will not do with
-   a foreign file (§0), transcription (§2), what each validator complaint means on
-   an export (§3), and the re-pivot, rename and extend recipes (§4).
+   a foreign file (§0), `ingest` and transcription (§2), what each validator
+   complaint means on an export (§3), and the re-pivot, rename and extend
+   recipes (§4).
 2. [AUTHORING.md](../../docs/AUTHORING.md) — the two spec files the transcription
    targets (§3–§4), the failure map (§5–§6), and the coordinate contract (§11).
 3. Then [RIGGING.md](../../docs/RIGGING.md) for why the re-pivot edit has the shape

package/src/atlas.ts

@@ -919,25 +919,69 @@ export function packAtlas(inputs: PackInput[], opts: PackOptions = {}): PackResu
  * a plate's rows run downwards, so the kept rectangle's top row is
  * `originalHeight - offsetY - height`.
  *
- * ⛔ A rotated region is refused rather than guessed. `TextureAtlas` transposes
- * `u2/v2` at 90 and not at 270, and `RegionAttachment.computeUVs` assigns a
- * different corner order at 90 — there are already three opinions in the runtime
- * about that mapping and this file is not going to be a fourth. rigc's own packer
- * never rotates (`PACK_NO_ROTATE`), so only a foreign atlas can reach this.
+ * ## A rotated region is TRANSCRIBED, not guessed at (issue #570)
+ *
+ * This refused a rotated region until 2026-09-17, on the argument that the
+ * runtime holds "three opinions" about the mapping. Measurement refutes the
+ * argument: the three are not three readings of one mapping, they are one
+ * mapping and two places that do not implement it.
+ *
+ *   * `MeshAttachment.computeUVs` (spine-core 4.3.13,
+ *     `dist/attachments/MeshAttachment.js:126-162`) is the one routine that
+ *     states where a region's texels are for **all four** `degrees`, and it is
+ *     the routine `substituteTexture` in [`src/render.ts`](render.ts) already
+ *     goes through. The loop below is its inverse, term for term;
+ *   * `TextureAtlas`'s `u2`/`v2` (`dist/TextureAtlas.js:164-171`) transpose the
+ *     rectangle at 90 and not at 270, so at 270 they describe a rectangle the
+ *     page does not have — but `MeshAttachment.computeUVs` never reads them for
+ *     an atlas region, and neither does this;
+ *   * `RegionAttachment.computeUVs` (`dist/attachments/RegionAttachment.js:156-167`)
+ *     assigns the turned corner order at 90 and at nothing else, which is a
+ *     region-attachment rendering defect (issue #199) and not a statement about
+ *     where the drawing sits.
+ *
+ * Inverting the runtime's own expression on texel centres puts kept-rectangle
+ * pixel `(x, y)` — `x` from the drawing's left, `y` down from `top` — at page
+ * pixel `(X + x, Y + y)` unturned, `(X + y, Y + width - 1 - x)` at 90,
+ * `(X + width - 1 - x, Y + height - 1 - y)` at 180 and
+ * `(X + height - 1 - y, Y + x)` at 270, writing `X`/`Y` for the region's own
+ * `x`/`y`; the packed footprint is `height x width` for the two quarter turns
+ * and `width x height` for the other two. `repackRotatedTrimmed` in
+ * `selftest.ts` derived the same 270 mapping for issue #199's fixture, and had
+ * been shipping it green, while this comment claimed the mapping was unknowable.
+ *
+ * ⚠️ Any other `degrees` takes the unturned branch, because that is what the
+ * runtime does with it: `regionFields.rotate` (`dist/TextureAtlas.js:87-93`)
+ * `parseInt`s the value without checking it, and `computeUVs` falls to
+ * `default:` for everything that is not 90, 180 or 270. Reading such a region
+ * unturned is not a guess, it is agreement with the thing that will draw it.
+ *
+ * rigc's own packer still never rotates (`PACK_NO_ROTATE`), so only a foreign
+ * atlas reaches any branch but the first.
  */
 export function extractRegion(page: Plate, region: AtlasRegion): Plate {
-  if (region.degrees !== 0) {
-    throw new CompileError(
-      `region "${region.name.trim()}" is packed rotate: ${region.degrees}; reading a drawing back off a rotated ` +
-        'region is not implemented — rigc\'s own packer never rotates, so this is a foreign pack. Supply the loose ' +
-        'PNG instead of --atlas-in for the part that needs measuring.',
-    );
-  }
   const out = new Plate(region.originalWidth, region.originalHeight);
   const top = region.originalHeight - region.offsetY - region.height;
+  const { degrees } = region;
   for (let y = 0; y < region.height; y++) {
     for (let x = 0; x < region.width; x++) {
-      out.set(region.offsetX + x, top + y, page.get(region.x + x, region.y + y));
+      const px =
+        degrees === 90
+          ? region.x + y
+          : degrees === 180
+            ? region.x + region.width - 1 - x
+            : degrees === 270
+              ? region.x + region.height - 1 - y
+              : region.x + x;
+      const py =
+        degrees === 90
+          ? region.y + region.width - 1 - x
+          : degrees === 180
+            ? region.y + region.height - 1 - y
+            : degrees === 270
+              ? region.y + x
+              : region.y + y;
+      out.set(region.offsetX + x, top + y, page.get(px, py));
     }
   }
   return out;

package/src/check.ts

@@ -863,6 +863,24 @@ export interface CheckReport {
   candidate: { skeleton: string; atlas: string };
   framesDir: string;
   framesRoot: string;
+  /**
+   * The skin the CANDIDATE was posed under, or `null` for no skin at all.
+   *
+   * ⭐ In the report rather than only in the run's arguments because a figure is
+   * only readable beside what produced it: on a multi-skin rig the same
+   * candidate and the same frames give a different number per skin, and a
+   * `check.json` that did not say which one it was is a number with no subject
+   * (issue #571).
+   */
+  skin: string | null;
+  /**
+   * The skin `frames.json` records for the reference frames, or `null`.
+   *
+   * `null` covers two facts that are the same on disk — the frames set no skin,
+   * and the frames were rendered before the field existed — which is why a
+   * mismatch against it is refused and an absence is only noted. See `notes`.
+   */
+  referenceSkin: string | null;
   /** One framing per set, or one across every set — see `FramingScope`. */
   framingScope: FramingScope;
   /**
@@ -947,6 +965,17 @@ export interface CheckOptions {
   viewport?: { x: number; y: number; width: number; height: number };
   /** Play this candidate animation against the frames, when the names differ. */
   as?: string;
+  /**
+   * Pose the candidate under this skin — see `PoseOptions.skin` (issue #571).
+   *
+   * Absent sets no skin, which resolves every slot through the default skin
+   * alone: on a multi-skin rig that draws none of the art the named skins carry,
+   * and a `check` of it compares blank against blank and reads 0.0000. A name
+   * the candidate does not declare is refused with the ones it does, and the
+   * reference frames' own recorded skin is checked against this — see the
+   * `referenceSkin` field of `CheckReport` for what an absent record means.
+   */
+  skin?: string;
   /**
    * Fit one framing per frame set, or one across every set compared.
    *
@@ -1026,7 +1055,20 @@ export function checkAgainstFrames(options: CheckOptions): CheckReport {
   const substitution = options.textureFrom
     ? textureSubstitutionFromText(options.textureFrom.atlasText, options.textureFrom.atlasDir)
     : null;
-  const poseOptions: PoseOptions | undefined = substitution ? { texture: true } : undefined;
+  // The skin is refused here rather than deeper in the sampler, for the reason
+  // every miss in this project is refused where the names are: the skeleton is
+  // open on this line and the alternatives can be listed.
+  if (options.skin !== undefined && !posable.data.skins.some((s) => s.name === options.skin)) {
+    throw new CheckError(
+      `the candidate declares no skin ${JSON.stringify(options.skin)}; it declares [${
+        posable.data.skins.map((s) => s.name).join(', ') || 'none'
+      }]`,
+    );
+  }
+  const poseOptions: PoseOptions | undefined =
+    substitution || options.skin !== undefined
+      ? { ...(substitution ? { texture: true } : {}), ...(options.skin === undefined ? {} : { skin: options.skin }) }
+      : undefined;
   let background: RGBA;
   let sets: FrameSet[];
   let pixelWidth: number;
@@ -1086,6 +1128,35 @@ export function checkAgainstFrames(options: CheckOptions): CheckReport {
 
   if (sets.length === 0) throw new CheckError(`no frame set to compare in ${options.framesDir}`);
 
+  // --- the skin the frames were rendered under, against the one asked for ----
+  //
+  // ⭐ The asymmetry is the honest part (issue #571). A sidecar that RECORDS a
+  // skin is a claim, and a claim that disagrees is refused by name; a sidecar
+  // that records none is making no claim at all — it either set no skin or was
+  // written before the field existed, and those are the same bytes — so the run
+  // proceeds and says out loud that nothing checked it. Inventing a refusal out
+  // of an absent field would refuse every frame set in this repository.
+  const referenceSkin = located.sidecar?.skin ?? null;
+  if (referenceSkin !== null && referenceSkin !== options.skin) {
+    throw new CheckError(
+      `${FRAMES_SIDECAR} records that these frames were rendered under skin ${JSON.stringify(referenceSkin)}, and ` +
+        `this run poses the candidate ${
+          options.skin === undefined
+            ? 'under no skin at all (the default skin alone)'
+            : `under skin ${JSON.stringify(options.skin)}`
+        }. Two skins are two different pictures of one rig, so the comparison would be a number about the ` +
+        `difference between them. Pass --skin ${JSON.stringify(referenceSkin)}, or render the reference frames ` +
+        `${options.skin === undefined ? 'with no --skin' : `with --skin ${JSON.stringify(options.skin)}`}.`,
+    );
+  }
+  if (referenceSkin === null && options.skin !== undefined) {
+    notes.push(
+      `the candidate is posed under skin ${JSON.stringify(options.skin)} and the reference frames record no skin ` +
+        `at all, so nothing here could check that they are the same picture. A frame set rendered by \`rigc ` +
+        `render --skin\` since #571 carries the name in ${FRAMES_SIDECAR} and this run would have compared it.`,
+    );
+  }
+
   // Pose every set once. Its frames are wanted twice — to frame the candidate and
   // to compare it — and posing twice is both slower and a chance for the framing
   // and the comparison to disagree about what they measured.
@@ -1347,6 +1418,8 @@ export function checkAgainstFrames(options: CheckOptions): CheckReport {
     },
     framesDir: resolve(options.framesDir),
     framesRoot: located.root,
+    skin: options.skin ?? null,
+    referenceSkin,
     framingScope: scope,
     framing: topHow,
     viewport: topViewport === null ? null : framingOfViewport(topViewport),
@@ -3117,6 +3190,15 @@ export function checkLines(report: CheckReport, opts?: { allFrames?: boolean }):
   lines.push(`  candidate  ${report.candidate.skeleton}`);
   lines.push(`  atlas      ${report.candidate.atlas}`);
   lines.push(`  frames     ${report.framesDir}`);
+  // Always printed, on both sides, because the reading a reader has to be able
+  // to make is "which picture of this rig is this" — and a line that appears
+  // only when a skin was named cannot say that the run used none (issue #571).
+  lines.push(
+    `  skin       candidate ${report.skin === null ? 'no skin set (the default skin alone)' : report.skin}   ` +
+      `frames ${
+        report.referenceSkin === null ? `no skin recorded in ${FRAMES_SIDECAR}` : report.referenceSkin
+      }`,
+  );
   lines.push(
     `  scope      ${
       report.framingScope === 'per-shot'