spine-rigc 0.22.1 → 0.23.0

package/docs/AUTHORING.md

@@ -329,28 +329,119 @@ Four things are refused rather than warned about, because each of them otherwise
 | a page the atlas names and the disk lacks | nothing to sample; caught on the way in, so the message names the atlas rather than the artifact rigc wrote from it |
 | a rectangle that runs off its page | `x + width` past the page width makes `u2 > 1`, which samples whatever the wrap mode does |
 
-Two limits, stated rather than discovered:
+One limit, stated rather than discovered:
 
 - an **optional state** (a manifest `states:` entry) whose region is not in the
   pack is a `DROP`, not a refusal — the same documented absence a missing PNG has
-  always been, and the line names the atlas rather than a file nobody opened;
-- a generator that **measures a part's pixels** — the `contour` mesh — lifts the
-  drawing back off the page, and refuses by name on a region packed `rotate: 90`.
-  Supply the loose PNG for that part instead. rigc's own packs never rotate, so
-  only a foreign pack reaches it.
+  always been, and the line names the atlas rather than a file nobody opened.
+
+A **turned** region is not one of them, and used to be (issue #570). A pack made
+by somebody else routinely rotates a region to save space — `rotate: 90`,
+`rotate: 180`, `rotate: 270`, or the format's older `rotate: true` — and rigc
+reads all of them: anything that measures a part's pixels sees the same grid it
+would have seen from the loose PNG, so a `contour` mesh traces the same
+silhouette and an authored mesh's fit figure is the same number. The one thing
+that does not change is what rigc **writes**: its own packer never turns a
+region.
+
+⚠️ Two limits here are real and neither is about rotation:
+
+- `--atlas-in` cannot recover what a `scale:` quantised away (above), turned or not;
+- the **renderer** profile still refuses a turned region outright
+  (`A06`, `--profile spine-html`), because that profile is about artifacts rigc
+  itself emits and it never packs one turned. Reading a foreign pack and gating
+  one under somebody else's renderer policy are different questions.
 
 `--pack` and `--atlas-in` are opposite directions through the same door and are
 refused together.
 
+### 0.3 Starting from a skeleton somebody else made — `ingest`
+
+Everything above starts from two spec files you wrote. `rigc ingest` starts from a
+**Spine 4.3 `skeleton.json` you were handed** and writes those two files for you, so
+an existing rig is a starting point instead of 250 KB of arrays to retype.
+
+```bash
+bun cli.ts ingest hero.json --out specs/ --stage 0,0,1024,768
+#   ..    out  /abs/path/specs
+#   ..    art  loose
+#   JUDGE DURATION: animation "idle" — skeleton JSON carries no duration; the largest key time (2.667) is used …
+#   LOSS  PATH_LENGTHS: skin "default" slot "track" attachment "track" — the source states `lengths`; rigc RE-MEASURES it …
+# rigc: wrote /abs/path/specs/rig.json
+# rigc: wrote /abs/path/specs/motion.json
+# rigc: wrote /abs/path/specs/findings.json
+
+bun cli.ts build --rig specs/rig.json --motion specs/motion.json --images parts/ --out spine
+bun cli.ts diff spine/skeleton.json hero.json      # 1.000 on every measure
+```
+
+**The loop it belongs in is the one above, with a different first step.** `ingest`
+writes the specs; you *edit* them the way you would edit specs you wrote; `build`
+gates; `explain`, `render`, `preview` and `check` read the result. Nothing
+downstream knows or cares that the file started somewhere else — which is the point,
+and also the hazard the `note` below exists for.
+
+**The contract is an equality, not a rulebook.** `build(ingest(x))` is `x`: the
+rebuilt `skeleton.json` is byte for byte the file `ingest` read, and the rebuilt
+atlas holds the same **region blocks** — as a multiset, because the order the pages
+come out in is in no field of the skeleton and a decompiled spec cannot know it.
+That is a gate rather than a claim: `bun run selftest` round-trips every rig this
+repository builds on every run.
+
+**Two flags, for the two things a skeleton does not encode.**
+
+| flag | what it decides |
+| --- | --- |
+| `--art loose` (default) | name an `image` per attachment — `<path or placeholder>.png` — so the rebuild is `build --images <dir>` and rigc measures the PNGs |
+| `--art none` | state `width`/`height` only, so the rebuild is `build --atlas-in <pack.atlas>` and every part resolves out of the pack |
+| `--stage x,y,w,h` | the setup bounding box. **Required for an editor export**, which carries none |
+| `--name <n>` | the rig spec's `name`, which the motion spec's `archetype` must equal (default: the file's basename) |
+
+🚨 **The stage is the one value `ingest` will not guess.** rigc always emits
+`skeleton.width`/`height` and an editor export never does, so a foreign file needs
+`--stage`; without it the missing box is a **blocker**, named. It is not derivable —
+posing the rig gives the *animated* extent, which is a different number from the
+editor's setup box — and it is the value that costs least to get wrong, because no
+measure `diff` reports reads the skeleton header at all. Supply it from the project
+the file came from, or from the editor's own canvas.
+
+⚠️ **The duration is a convention, and it is recorded as one.** Skeleton JSON has no
+duration field. The largest key time is the only derivable answer and it is what a
+runtime plays to — but it is wrong for an animation that holds its last pose past its
+last key, and nothing in the file can tell the two apart. `ingest` writes the largest
+key time, states the convention in the motion spec's `note`, and records a finding per
+animation. If you know the real number, edit it: the declared duration is checked
+against the compiled keys, so an honest one costs you nothing.
+
+**Read the findings; they are the product.** Three kinds, and the exit code turns on
+the first:
+
+| gutter | meaning |
+| --- | --- |
+| `BLOCK` | the spec format cannot say it, so the rebuild will **not** be the file that was read — `linkedmesh`, `point`, an attachment `sequence`, an unknown field on a bone, slot or constraint, a timeline family the motion spec has no track for. The command exits non-zero **and still writes both specs**, because a spec plus a list of what is missing from it beats no spec |
+| `JUDGE` | the skeleton cannot answer and somebody has to: the stage, and each animation's duration |
+| `LOSS` | the skeleton says it and rigc re-derives it, on purpose. A path attachment's `lengths` is the one that matters — it is `PathConstraint`'s own four-sample measurement rather than an arc length (#560), so a transcribed one would freeze whatever produced the source |
+
+📝 **Do not delete the `note`.** Both written specs carry one saying the file is
+decompiled and naming the skeleton it came from. A decompiled spec is
+indistinguishable from an authored one by inspection, every gate here calls it green —
+because it *is* green — and no gate can catch the note's absence. It carries no
+timestamp, deliberately: `A18_DETERMINISTIC_EMIT` compares two independent compiles
+byte for byte, and a dated note would break the first rebuild from the spec.
+
+⛔ **It reads skeleton JSON and nothing else** — not a `.spine` project, not a binary
+`.skel`, not the atlas, not the art. A path that is not a `.json` is refused by name.
+[INGEST.md](INGEST.md) is the whole page on working from a file you were handed.
+
 The other commands:
 
 ```bash
 bun cli.ts explain  --rig … --motion … --out …   # the compiled rig as a table
 bun cli.ts validate path/to/spine                # re-gate artifacts already on disk
 bun cli.ts diff     candidate.json reference.json
-bun cli.ts check    --candidate path/to/spine --frames path/to/frames
+bun cli.ts check    --candidate path/to/spine --frames path/to/frames [--skin …]
 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 render   --candidate path/to/spine [--animation …] [--skin …] [--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]
@@ -372,6 +463,9 @@ bun cli.ts pose     --images path/to/parts --frame poseA.png [--out pose.json]
   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.**
+  🚨 What it certifies is the **default skin** unless you pass `--skin <name>`:
+  on a rig with named skins, a run with no skin draws none of their art on either
+  side and reports a perfect `0.0000` about it (**§9**).
 - **`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
@@ -642,11 +736,17 @@ against `mike2`). Both of those *build* as animation names and are refused as sk
 names, and the two refusals say which is which.
 
 **R12 — A placeholder that more than one skin fills gets a per-skin attachment
-`name`.** rigc writes `"name": "<skin>/<placeholder>"` on each of those entries,
-and restates `path` beside it so the texture still resolves where it did. You do
-not author this and there is nothing to do about it — but it is visible in the
-emitted file, so §3.4.2 says what it is and why. A placeholder only one skin fills
-is emitted exactly as before.
+`name`, and the `default` skin may not be one of those skins.** rigc writes
+`"name": "<skin>/<placeholder>"` on each of those entries and restates `path`
+beside it so the texture still resolves where it did; you do not author that and
+there is nothing to do about it, but it is visible in the emitted file, so §3.4.2
+says what it is and why. What you *do* author is where the shared art lives: a
+placeholder the `default` skin shares with a named skin is a **compile error**,
+because the Spine editor has no representation for it in either spelling (#567,
+measured on 4.3.26 — named, the export re-keys it and the default skin draws
+nothing; unnamed, the import is refused). Put the shared entry in a named skin —
+`base` — and every filler is a named skin. A placeholder only one skin fills is
+emitted exactly as before, in the default skin or anywhere else.
 
 ---
 
@@ -667,8 +767,8 @@ is recorded in `bench/runs/README.md`, *What a run may read*.)
 
 | Field | Spine meaning | Default |
 | --- | --- | --- |
-| `x`, `y` | setup-pose bounding box origin | `0` |
-| `width`, `height` | setup-pose bounding box size | falls back to the manifest's crop; **with neither, the compile fails** |
+| `x`, `y` | setup-pose bounding box origin | `0` — and refused outright beside a stated absence, below |
+| `width`, `height` | setup-pose bounding box size, **or both `null` for "this skeleton declares no stage"** | falls back to the manifest's crop; **with neither the number nor the `null`, the compile fails** |
 | `fps` | nonessential editor hint | `SkeletonData.fps` stays 30 |
 | `referenceScale` | 4.2+ physics/scale reference | parser default 100 |
 | `images` | where the editor's import looks for the part PNGs, as a path from the skeleton file | **written for you**: under `--copy-images` the `--out` directory itself, spelled `../<its basename>/` (a literal `./` is dropped by the editor on import; a named directory is kept and every part is found — measured on 4.3.23); otherwise the relative path from `--out` to the one directory the spec names every part PNG in (the rig's images directory, or the manifest's plates). A declared value is carried through verbatim — and overridden by `--copy-images`, which moved the parts. Parts spread over several directories have no single true path, so nothing is written (issue #370) |
@@ -684,6 +784,40 @@ links, not the editor that will open the file, and the warning is harmless
 `width`/`height` are what `A14` and `A19` measure against, so a guessed stage is a
 gate measuring against a number nobody wrote down.
 
+⭐ **A skeleton may declare no stage, and saying so is not the same as saying
+nothing** (issue #578). Write the pair as `null`:
+
+```json
+"skeleton": { "width": null, "height": null }
+```
+
+and the emitted header carries **none** of `x`/`y`/`width`/`height` — which is
+what an export of a skeleton whose stage was never set looks like, and the shape a
+transcriber of one now has something to write. `null` is this spec's spelling for
+a stated absence wherever it has one (`slots[].attachment` is `null` for "show
+nothing"), so nothing new is introduced here but a third value of a field that
+already existed.
+
+Three readings stay apart, and the middle one is the point of the other two:
+
+| What the spec says | What happens |
+| --- | --- |
+| a number for each | the stage, as before; a manifest `crop` is the fallback |
+| `"width": null, "height": null` | builds, and emits a header with no stage at all — and this **beats** a manifest's `crop`, because a rig spec is where a claim about the skeleton is made |
+| neither | **refused**, exactly as before: `no stage size: …` |
+| one `null`, one number | refused — a stage has both extents or neither, and which half was meant is not derivable |
+| the pair `null` **and** an `x` or `y` | refused — an origin for a box that is not there |
+
+⚠️ A stage-less skeleton is **unmeasured, not certified**: `A14_NO_FULL_FRAME_MESH`
+reports **SKIP** on one, because there is no full frame for a mesh to span. And
+`rigc diff` reports it — `skeleton.stage_present` and `skeleton.stage_box`, in the
+header block at the top of the report — so a stage somebody invented now reads
+below 1.000 against a source that has none. Both are reported and gate nothing, for
+the reason every reported measure is: no reading of the rendered frames could have
+decided a setup-pose bounding box. The measure inventory that says so lives in
+[BENCHMARK.md](https://github.com/firejune/rigc/blob/main/docs/BENCHMARK.md), which
+is repository material and not in the published package.
+
 ### 3.2 `bones` — Spine's bone list
 
 `parent` is resolved **by name against bones already declared**, exactly as the
@@ -714,17 +848,38 @@ and the inheritance silently falls back to Normal — assertion `A02` refuses it
 | --- | --- | --- |
 | `name` | required, unique | — |
 | `bone` | required; must be a bone this rig declares | — |
-| `attachment` | the **setup pose** attachment name, or `null` for "show nothing" | must come from here or from `motion.setup` (R3) |
+| `attachment` | the **setup pose** attachment name, or `null` for "show nothing" | must come from here or from `motion.setup` (R3) — **except** on a slot nothing fills, where it can only be `null` and may be left out |
 | `color` | `rrggbbaa` tint | opaque white |
 | `dark` | two-colour tint, `rrggbb` | — (🚫 `A12` under `spine-html`) |
 | `blend` | `normal` · `additive` · `multiply` · `screen` | `normal` |
 
-⚠️ **A slot with no attachments is not emitted.** If nothing fills it — no skin
-entry, no manifest part — it is dropped from the skeleton without an error, and the
-emitted slots array is a *subsequence* of the rig's. That is deliberate: the rig's
-slot list is the canonical table and declaring a slot no cut fills is legitimate,
-because it fixes where that slot will sit when one does. It also means a typo in a
-skin's slot key can cost you a slot quietly, so check `explain`'s slot table.
+✅ **Every slot you declare is emitted, in this order.** A slot nothing fills — no
+skin entry, no manifest part — is emitted **empty**: `name` and `bone`, and no
+`attachment` key at all, which is how the format spells "shows nothing"
+(`SkeletonJson`'s slot reader takes `attachment` with a `null` default; 34 of the 52 slots of the
+official `spineboy-pro` export omit the key, though those are slots a skin fills
+whose setup pose shows nothing). So the emitted slots array
+**is** the rig's slot table, and `A26_SLOT_DRAW_ORDER` checks it in both directions:
+nothing out of order, and nothing missing.
+
+Declaring a slot no cut fills is therefore normal — it fixes where that slot sits
+whether or not this cut has art for it — and transcribing a foreign skeleton that
+carries an empty slot reproduces it exactly.
+
+⚠️ **This changed with issue #575.** Such a slot used to be *dropped*, with no message, and
+the gate allowed the emitted array to be any subsequence of the rig's. What it cost
+is the index: every slot below the dropped one moved up one place, which is what a
+`drawOrder` key's offsets are counted against and what an index-keyed consumer
+splits on. Two production exports declaring 53 and 61 slots built green at 51 and 57
+and read 0.962 and 0.934 under `diff` against the file they were transcribed from.
+If you have a rig that leaned on the drop, the emitted array simply grows; nothing
+else about it moves.
+
+🚫 **Naming an attachment on a slot nothing fills is refused by name**: `the setup
+pose shows attachment "x" on slot "y", which no skin and no manifest part fills`.
+That is the half-finished wiring-up the old silence hid — the slot is emitted empty
+and the name resolves to nothing, so either give the slot an attachment or state the
+setup pose as `null`.
 
 ### 3.4 `skins` — placeholder → attachment maps
 
@@ -745,7 +900,7 @@ the default `type`:
 | `type` | `"region"`, or omit |
 | `image` | **rigc extension.** A PNG relative to the rig's `images` directory; rigc measures it (R5) |
 | `width`, `height` | required by the format — give them, or give an `image` |
-| `path` | the atlas region to resolve; defaults to the attachment's own name. rigc sets it for you when the PNG basename differs from the placeholder, and whenever it composes a `name` because more than one skin fills this placeholder (§3.4.2) |
+| `path` | the atlas region to resolve; defaults to the attachment's own name. rigc sets it for you when the PNG basename differs from the placeholder, and whenever it composes a `name` because more than one skin fills this placeholder (§3.4.2). **One rule, both kinds** — see the note under *Mesh attachment* |
 | `x`, `y` | offset from the bone, in the bone's local space |
 | `rotation` | degrees; cancels a rotated bone for a plate authored screen-upright |
 | `scaleX`, `scaleY`, `color` | as Spine |
@@ -754,7 +909,19 @@ the default `type`:
 either authored geometry (`uvs` + `triangles` + geometry) **or** a `generator`,
 never both. `hull`, `edges`, `width` and `height` may be stated; whichever is
 omitted, rigc derives — `hull` and `edges` from the triangles, the size from the
-PNG — and the rules are a few paragraphs down.
+PNG — and the rules are a few paragraphs down. `type`, `image`, `path` and `color`
+mean exactly what they mean on a region.
+
+🔑 **`path` is one rule for both kinds.** A mesh derives it from `image` the way a
+region does: stated wins, otherwise the PNG's basename when that differs from the
+placeholder, otherwise nothing. The parser reads `path` off both with the same line
+(`getValue(map, "path", name)`, `SkeletonJson.ts:541` and `:570`), and `path`
+defaults to the attachment's **name** rather than to the placeholder — so a mesh
+with `image: hair_short.png` under a placeholder called `hair` resolves the region
+`hair`, which no atlas has. Until
+[#577](https://github.com/firejune/rigc/issues/577) a region derived it and an
+authored mesh did not, so that rig **built** and then failed
+`A00_ROUNDTRIP_PARSE: threw: Region not found in atlas: hair`.
 
 Geometry comes in one of two fields:
 
@@ -1430,20 +1597,80 @@ names you already gave it:
 
 ```json
 "skins": {
-  "default": { "patch": { "patch": { "image": "patch_a.png" } } },
+  "default": { "block": { "block": { "image": "block.png" } } },
+  "base":    { "patch": { "patch": { "image": "patch_a.png" } } },
   "zulu":    { "patch": { "patch": { "image": "patch_a.png", "x": 4 } } }
 }
 ```
 
-emits
+emits, for slot `patch`
 
 ```json
-{ "name": "default/patch", "path": "patch", "width": 64, "height": 64 }
-{ "name": "zulu/patch",    "path": "patch", "width": 64, "height": 64, "x": 4 }
+{ "name": "base/patch", "path": "patch", "width": 64, "height": 64 }
+{ "name": "zulu/patch", "path": "patch", "width": 64, "height": 64, "x": 4 }
 ```
 
-Three things to know about it and nothing to author:
-
+🚨 **Every skin that shares a placeholder has to be a named one — the default
+skin may not be among them, and rigc refuses the rig if it is.** That is not a
+style rule; it is the editor's model, and two round trips through Spine
+**4.3.26** established it by ruling out both of the only two spellings there are
+([#567](https://github.com/firejune/rigc/issues/567)):
+
+- **Give the default skin's entry a name of its own** (`"name": "default/patch"`)
+  and the import succeeds — then the export comes back with that name as the
+  JSON **key** (`"default/patch": { … }`, the `name` field gone), because the
+  editor's default skin holds no skin placeholders: an attachment there hangs on
+  the slot and is known by its name alone. The slot's setup `attachment: "patch"`
+  now names a key the default skin does not have, so the default skin **draws
+  nothing** — `diff` read `attachments.names 3/5`, `check` read 98.52 mean MAE
+  with `drewSlots: 0` on that chain, and `validate --profile spine` stayed green
+  throughout.
+- **Leave it as its placeholder** (no `name`, which is the obvious repair) and
+  the editor **refuses the import**:
+
+  ```
+  ERROR: Unable to import skeleton.
+  Cause: [error] Error reading attachment: mike/patch (nSX)
+  Cause: [error] Multiple attachments have the same name:
+  patch
+  patch
+  ```
+
+  In one slot, a default-skin attachment name and a named skin's placeholder name
+  are the same namespace, and both are `patch`.
+
+⇒ **The rule: move the shared art into a named skin.** Call it `base`. Every
+filler of that placeholder is then a named skin, rigc composes all of them, and
+the names are unique within the slot — which is all
+[#541](https://github.com/firejune/rigc/issues/541) needed: `base/patch`,
+`zulu/patch` and `mike/patch` are three names. That shape is the one the editor
+does hold: the same three fillers in named skins imported, exported and measured
+**0.00 mean MAE** with names and paths intact.
+
+📎 **The earlier reading, kept because it was reasonable and wrong.** Between the
+two trips this guide said *compose off the default skin only* — keep the default
+skin's entry as its placeholder and name the others. Trip 7 supported it and trip
+8 refuted it: that is the spelling the editor refuses at the door. There is no
+third spelling, which is why this is a refusal rather than a naming scheme.
+
+What to know about it, and nothing to author:
+
+- **The renderer accepts this shape too, and that is measured rather than
+  assumed.** `spine-html@0.4.1` resolves a part in two steps and neither one
+  reads a placeholder or an attachment name: `DomTexture.js:78,102` builds its
+  image map with `put(atlasRegion.name, …)` over every region of the atlas, and
+  `SpineHtmlRenderer.js:172` reads it back as
+  `const regionImage = region && this.regionImages.get(region.name)`, where
+  `region` came off the attachment — which `AtlasAttachmentLoader` resolved
+  through `path`. Every published version of that renderer keys the same way.
+  ⚠️ `A08` used to carry a `--profile spine-html` clause requiring a
+  placeholder to be spelled exactly like the region it resolves to, which made
+  this shape and a green `spine-html` **mutually exclusive** from
+  [#567](https://github.com/firejune/rigc/issues/567) onwards; the first
+  production rig with named skins hit it three times. That clause is retired —
+  restated as the join the renderer actually performs it was a tautology over
+  the resolve check beside it
+  ([#574](https://github.com/firejune/rigc/issues/574)).
 - **`path` is restated, and it has to be.** `path` defaults to the attachment's
   **name**, not to its placeholder, so an entry given a name and no path would
   resolve its texture at `zulu/patch` and find no such region. `A00_ROUNDTRIP_PARSE`
@@ -1454,6 +1681,9 @@ Three things to know about it and nothing to author:
 - **A composed name that collides is a compile error, not a surprise.** If some
   other placeholder in the same slot is literally called `zulu/patch`, rigc refuses
   and names both sites rather than emitting two attachments with one name again.
+  The walk covers every *uncontested* entry's plain name too, the default skin's
+  included — a name that composed nothing can still be the one another skin
+  composes.
   (`/` is the separator because it appears in **0** of the 160 placeholder names and
   159 atlas region names in `examples/` and `gallery/`, where `-` appears in 85 and
   `_` in 37.)
@@ -1472,6 +1702,15 @@ bounding box in slot `head-bb`, and reuses `hoverglow-small` across eight slots.
 a name shared between slots is normal and rigc leaves it alone; what #541 refused
 was one slot holding two.
 
+🚨 **Once a rig has named skins, no instrument here can see them until you say
+which one** ([#571](https://github.com/firejune/rigc/issues/571)). `render` and
+`check` set no skin unless told to, so every slot resolves through the *default*
+skin alone and the art you just moved into `base`, `zulu` and `mike` draws
+nothing at all. `check` then compares blank against blank and reports a perfect
+`0.0000` — about the very placeholder this subsection is about. Pass
+`--skin <name>` to both, once per skin (**§9**); `tools/editor_roundtrip.ts`
+loops over every skin the build declares for the same reason.
+
 ### 3.5 `constraints` — 4.3's single typed array
 
 Spine 4.3 folds every constraint into one `constraints` array with a `type`
@@ -2533,6 +2772,18 @@ here was measured off a real rig. Copy the shape, not the values.
   runtime. **Stating a flag on every key still overrides the rig** — the format
   keys them per key on purpose, a bend that flips partway through is a real thing
   to write, and it is what the editor's own export does.
+- 🔁 **A spec that came out of `ingest` (§0.3) states all three on every key, and
+  that is not noise.** The stamping above reads a silent key as *"the rig's
+  value"*, which is right for a spec somebody wrote; in a **decompiled** spec a
+  silent key means *"the parser's default"*, because that is what the export the
+  spec came from actually plays. The two readings differ exactly when the rig
+  declares a non-default flag and the export's keys omit it — measured: an ik
+  timeline keying only `mix` under a constraint declaring `bendPositive: false`
+  rebuilds with `bendPositive: false` on every key if the flag is left silent,
+  and with `true` — what the source plays — when `ingest` writes it out. So
+  `ingest` restates every field any key of a track names, at the parser's default
+  where the source omits one, and records a `CONSTRAINT_KEY_RESTATED` finding. On
+  rigc's own output the two agree and the round trip is byte-identical.
 - `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.
@@ -2653,7 +2904,7 @@ Per key:
 
 | Field | Meaning |
 | --- | --- |
-| `vertices` | the run: `x, y` offset pairs. **Absent** = back to the setup pose |
+| `vertices` | the run: consecutive numbers copied into the deform array from the start index on, `x, y` per vertex or influence — an **odd** count is legal and ends on a lone x (§ the 📌 below). **Absent** = back to the setup pose |
 | `transform` | the run stated as a **model** instead, evaluated over the attachment's own geometry — §4.11.1. Never with `vertices`, `fromVertex` or `offset` |
 | `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` |
@@ -2703,14 +2954,12 @@ 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:
+rigc refuses these, 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"` |
@@ -2728,15 +2977,30 @@ tail and deforms the rest of the mesh correctly, which looks nearly right, and
 emitted file, measuring the array's length from the attachment rather than assuming
 an encoding.
 
-📌 **The two parity rows above are an AUTHORING rule and not a validity one, and
-the distinction is deliberate** (issue #262). Nothing in the runtime aligns a run
-to a pair — `arrayCopy` copies at the raw index and the `deform[i] += vertices[i]`
-after it walks the whole array — so a run may legitimately begin and end mid-pair,
-which is what an editor's trimmed delta run looks like. In *this* spec an odd
-`offset` is a typo with a better spelling (`fromVertex`), so it is refused here,
-where the remedy is a line you own. `A35` does **not** refuse it: it is pointed at
-other people's files, and a rule stricter than the runtime tells its reader to go
-and break correct data.
+📌 **A run is not required to be an even number of numbers, and it is not required
+to start on an even index.** Two rows stood here saying otherwise until issue
+#576. Nothing in either reader aligns a run to a pair: `SkeletonJson` does
+`Utils.arrayCopy(vertices, 0, deform, offset, vertices.length)` — a raw copy, at
+the raw index the key gives — and `SkeletonBinary` reads a count and a start and
+fills `for (let v = start; v < end; v++)`. So a run may begin and end mid-pair,
+which is exactly what an editor's trimmed delta run looks like: `spineboy-pro`'s
+`hoverboard-board` key starts at 1 and carries 147 numbers of a 148-long array,
+the whole delta minus one leading zero.
+
+⭐ **An odd run's last number is an x with no y beside it, and that is a
+statement, not an accident.** It moves that vertex in x and leaves its y at the
+setup value, because the parser copies your numbers and touches nothing else. It
+is also the reason the rule could not stay as an authoring convenience: padding a
+`0` to make the run even *changes what plays* wherever that setup y is non-zero,
+so there is no second spelling of such a key — refusing it would mean no
+transcription of that file can be written in this spec at all. `A35` reached the
+same conclusion from the other side in issue #262, and between that fix and this
+one the two halves of rigc disagreed about what the format holds.
+
+⚠️ What you lose with those rows is a typo filter: `offset: 3` written where
+`fromVertex: 3` was meant now compiles. It always half-did — `offset: 4` meant as
+vertex 4 lands on vertex 2 and was never refused — so read the field name twice.
+`offset` is an index into the deform array; `fromVertex` is a vertex.
 
 🖼️ **Worked examples, and they use a deform for four different things** — all
 four are repository material rather than part of the published package, so the
@@ -3456,9 +3720,13 @@ or the key's position in its own track. These are the frequent ones, verbatim:
 | `bone "X" names parent "Y", which is not declared before it` | move `Y` earlier in `bones` |
 | `two bones are called "X"` | bone names are the join key; rename one |
 | `slot "X" names bone "Y", which this rig does not declare` | add the bone, or fix the slot's `bone` |
-| `no setup pose for slot "X": give the motion spec a \`setup\` entry or the rig slot an \`attachment\`` | R3 — pick one file and declare it there |
+| `no setup pose for slot "X": give the motion spec a \`setup\` entry or the rig slot an \`attachment\`` | R3 — pick one file and declare it there. A slot **nothing** fills is exempt: its setup pose can only be "show nothing" and is not asked for |
+| `the setup pose shows attachment "A" on slot "X", which no skin and no manifest part fills` | §3.3 — the slot is emitted empty, so `A` resolves to nothing. Give the slot an attachment (a skin entry or a manifest part), or state the setup pose as `null` |
 | `a region needs width and height — give them, or give an "image" and rigc will measure the PNG` | add `image`, or both sizes |
 | `a mesh needs width and height — give them, or give an "image" and rigc will measure the PNG` | §3.4 — the same rule for a mesh |
+| `"type" is null, which is not a name. An attachment's type is one of region, mesh, linkedmesh, … or the key is absent and reads as "region"` | §6 — **remove the key**. Absent is the format's own default; present-and-null matches no parser case and the attachment is dropped in silence |
+| `attachment type "X" is not one of the 7 the Spine 4.3 format defines (…)` | §6 — a name the format does not have. Not a deferral, and not something rigc will grow: fix the spelling (`sequence` is a key on a region or a mesh, not a type) |
+| `this attachment is a "linkedmesh"` / `"point"` … `rigc does not emit it yet` | §6 — a construct the format has and rigc does not write. The message says what it would carry; SPEC_COVERAGE part 1-6 is the row it reads from |
 | `hull N disagrees with the triangles, whose outline has K vertices (0 → …)` | §3.4 — delete `hull`, or state K |
 | `hull vertices must come first; vertex i is on the boundary and vertex j is not. The triangles' outline runs …: list those K vertices first, in that order, then the M interior vertices` | §3.4 — renumber the vertices: the printed walk first, then the interior |
 | `hull vertices must trace the outline in order; the triangles' outline runs …, so vertex a has to follow vertex b in the list, and vertex c does` | §3.4 — renumber along the printed walk |
@@ -3488,7 +3756,9 @@ or the key's position in its own track. These are the frequent ones, verbatim:
 | `animation "A" group "G" P (t=…): derive <kind> projects onto "scaleX" and member "M" states depth −z` | §4.5.1 — a foreshortening needs the part in front of the axis; a part behind it takes the displacement projection |
 | `animation "A" group "G" P (t=…): derive <kind> states carried=… on a "scalex" track` | §4.5.1 — the foreshortening reads no depth difference, so `carried` belongs on the displacement track |
 | `animation "A" group "G" P (t=…): derive <kind> turns member "M" … past its own edge` | §4.5.1 — `cos(α − t) ≤ 0` would mirror the drawing; the turn is past what this construction carries (FACE §8) |
-| `no stage size: give the rig spec a \`skeleton.width\`/\`skeleton.height\`` | §3.1 |
+| `no stage size: give the rig spec a \`skeleton.width\`/\`skeleton.height\`` | §3.1 — or state `"width": null, "height": null` if the skeleton you are transcribing declares no stage |
+| `"skeleton" states width: null and a height of N` / `states height: null and a width of N` | §3.1 — a stage has both extents or neither |
+| `"skeleton" declares no stage (width: null, height: null) and still states x` | §3.1 — an origin for a box that is not there |
 | `N mesh slot(s) emitted but the rig "X" allows 0 — a mesh rigc GENERATED counts against \`invariants.meshSlots\`…` | §3.4 / §3.7 — a rig that invokes a mesh generator declares the budget; undeclared is zero. Add `"invariants": { "meshSlots": N, "meshTriangles": M }` |
 | `drawOrder at t=…: slot "X" is not one this rig emits` / `is offset twice in one key` / `puts it at N, outside the … emitted slots` | §4.7 |
 | `events at t=…: event "X" is not declared in the rig spec's "events" block` | declare it in the rig spec (§3.6), or fix the name |
@@ -3503,7 +3773,6 @@ or the key's position in its own track. These are the frequent ones, verbatim:
 | `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 — in **this spec** a run starts on an even index, or names its vertex with `fromVertex`. Not a validity rule; the runtime allows either (issue #262) |
 | `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 |
 | `deform … (t=…): the key carries both a "transform" and a "vertices" run` | §4.11.1 — a model and a table are two answers to one question; drop one |
@@ -3529,7 +3798,8 @@ or the key's position in its own track. These are the frequent ones, verbatim:
 | `animation "A": "position" is a path constraint timeline, and this track names no constraint` | §4.12 — put the name in `"path"` |
 | `N pair(s) of animation names have no one order: … "turn" / "Turn" (case) — they are one name in two cases, and which of them the editor puts first is not measured; rename one of them so they differ by more than letter case` | **R10** — rename until no pair is left. The kind in brackets says which of the editor comparator's four UNMEASURED choices decides the pair: `case` (a pure case tie), `number` (one number written two ways, or a run of digits against a word) or `separator` (make the first character that differs a letter or a digit). rigc keys `animations` in the editor's own comparator — natural and case-insensitive ([#539](https://github.com/firejune/rigc/issues/539), [#543](https://github.com/firejune/rigc/issues/543)) — so a pair that comparator settles is emitted rather than refused, and only the four choices nobody has measured are a compile error; on those, the editor's re-key repoints every slider whose animation moves index ([#535](https://github.com/firejune/rigc/issues/535)) |
 | `N pair(s) of skin names have no one order: … "Zulu" / "mike" (case) — folded to one case "Zulu" and "mike" order the other way round, so whether the editor folds SKIN names decides this pair` | **R11** — rename until no pair is left. The same shape as the row above with a **wider** family: #539 measured the editor's comparator for animation names and thereby ruled codepoint out, and nothing has ruled anything out for skin names, so a pair the candidates could disagree about is refused even where the animation rule would emit it. `Zulu`/`mike` and `mike10`/`mike2` build as animation names and are refused as skin names ([#541](https://github.com/firejune/rigc/issues/541)) |
-| `N attachment name collision(s): a placeholder that more than one skin fills is emitted with the name "<skin>/<placeholder>" … slot "patch": skin "default" placeholder "zulu/patch" and skin "zulu" placeholder "patch" would both be named "zulu/patch"` | **R12** — rename the placeholder or the skin. rigc composes an attachment name for every placeholder more than one skin fills (§3.4.2), and this fires when the composed name is one another entry in the same slot already answers to. Both sites are named; either rename ends it |
+| `slot "patch": placeholder "patch" is filled by the "default" skin AND by skins "zulu", "mike", and the Spine editor has no way to hold that … Move the default skin's entry for this slot into a named skin — call it "base"` | **R12** — do what it says: move that entry out of `default` into a named skin. The editor has no representation for a placeholder the default skin shares with a named one, in either spelling, and §3.4.2 has both measurements. Renaming the placeholder does not help; the shape is what is refused |
+| `N attachment name collision(s): a placeholder that more than one skin fills is emitted with the name "<skin>/<placeholder>" … slot "patch": skin "base" placeholder "zulu/patch" and skin "zulu" placeholder "patch" would both be named "zulu/patch"` | **R12** — rename the placeholder or the skin. rigc composes an attachment name for every placeholder more than one skin fills (§3.4.2), and this fires when a composed name is one another entry in the same slot already answers to — including a plain name in the default skin, which composed nothing. Both sites are named; either rename ends it |
 
 ### 5.2 Assertions — the gate
 
@@ -3555,9 +3825,31 @@ The report prints one line per assertion:
 - **FAIL** — the detail names the object, the value found and the value required.
   That detail is the instruction; the table below says which file to change.
 
+**Every assertion leaves exactly one row, on every run.** The four kinds partition
+the registry, so the rows you can see are the whole of what was asked — there is
+no fifth state in which a rule quietly did not come up. The last line of the
+report states that partition, and every figure in it is a count of *assertions*
+you can reproduce by counting rows:
+
+```
+  ..    <N> assertions: <M> measured (<P> passed, <F> failed), <S> skipped, <X> not in profile "<profile>"
+```
+
+`<M>` is `<P> + <F>`, and `<N>` is all four added together. ⚠️ `<F>` counts
+assertions and not `FAIL` lines: one assertion that finds six wrong vertices
+prints six rows and is one failure here.
+
+🚨 **When `A00_ROUNDTRIP_PARSE` fails, read the report as a report about A00 and
+nothing else.** Most of the rules read the skeleton or the atlas that A00 loads,
+and with no parse there is nothing for them to look at — so they report `SKIP`
+naming that, *the round trip did not produce a skeleton to measure* or *…an atlas
+to measure*, and the summary's `<S>` goes up while `<M>` collapses. A run in that
+state is not a rig that nearly passed; it is a rig that was measured on one rule.
+Fix A00 and run it again ([#568](https://github.com/firejune/rigc/issues/568)).
+
 | Assertion | Profile | What tripped it, and where to fix it |
 | --- | --- | --- |
-| `A00_ROUNDTRIP_PARSE` | both | `spine-core` could not parse the skeleton or the atlas. Everything else in the report is downstream of this one — fix it first |
+| `A00_ROUNDTRIP_PARSE` | both | `spine-core` could not parse the skeleton or the atlas. Everything else in the report is downstream of this one — fix it first. When it fails, every rule that reads the loaded skeleton or the loaded atlas reports **SKIP** saying so by name, so the row count stays at the full registry and the summary's *measured* figure tells you how little was actually asked ([#568](https://github.com/firejune/rigc/issues/568)) |
 | `A01_NO_LEGACY_TOPLEVEL_CONSTRAINT_ARRAYS` | both | a 4.1/4.2-shaped `ik`/`transform`/`path`/`physics`/`slider` array. rigc emits the 4.3 `constraints` array, so this normally means hand-edited JSON |
 | `A02_NO_BONE_TRANSFORM_KEY` | both | a bone uses 4.2's `transform`; rename it `inherit` in the rig spec |
 | `A03_REGION_WIDTH_HEIGHT_FINITE` | both | a region loaded `NaN` or a non-positive size — the attachment has no `image` and no `width`/`height` |
@@ -3565,14 +3857,14 @@ The report prints one line per assertion:
 | `A05_CURVE_ARRAY_LENGTH` | both | a raw `curve` with the wrong number of values, a non-finite number in one, or a curve on a timeline that cannot take one. Four numbers **per value channel** |
 | `A06_ATLAS_PAGE_SIZE_MATCHES_PNG` | both ◑ | the atlas `size:` disagrees with the PNG on disk. Under `spine-html` also: `pma`, rotation, and a page that is neither **one part covering it exactly** (the unpacked convention) nor a **tiling** — a page whose regions all sit inside it and none of which overlap ([#266](https://github.com/firejune/rigc/issues/266)). A packed atlas therefore gates under this profile; what the message names is the region that runs off its page, or the pair that shares texels |
 | `A07_ATLAS_TEXT_SHAPE` | both | atlas text: a region name with stray whitespace, or a blank line splitting a page block. rigc writes the atlas, so this means a hand-edited file |
-| `A08_REGION_NAMES_MATCH_ATTACHMENTS` | both ◑ | an attachment resolves to a region the atlas does not have — usually a `path`/`image` basename mismatch. Under `spine-html` the placeholder and the region name must also be *identical* |
+| `A08_REGION_NAMES_MATCH_ATTACHMENTS` | both | an atlas region name carrying stray whitespace. rigc writes the atlas, so this means a hand-edited file, and `A07` names the same line with its line number. ⚠️ A `path` that resolves to **no** region never reaches here: `AtlasAttachmentLoader` throws `Region not found in atlas: <path> (attachment: <name>)` while the skeleton is still loading, so it arrives as `A00_ROUNDTRIP_PARSE`. There is no `spine-html` clause here any more — a placeholder is free to differ from the region its `path` names ([#574](https://github.com/firejune/rigc/issues/574)) |
 | `A09_ANIMATION_DURATION_MATCHES_SPEC` | both | the loaded duration ≠ the declared one, or the two sides disagree about which animations exist (R7). Asymmetric by design: a frame of slack for an animation that ends early, and none worth the name for a key *past* the declared end, which is the same rule §4.5 states at compile time — held here against a skeleton the compiler never saw. **SKIP** when neither side has an animation at all — a static rig has no duration |
 | `A10_NO_NAN_AFTER_STEPPING` | both | stepping the animation produced a `NaN` pose. Look for a degenerate curve or a zero scale |
 | `A11_NO_CLIPPING_ATTACHMENTS` | renderer | a clipping attachment; the target renderer skips them silently |
 | `A12_NO_DARK_COLOR` | renderer | a slot `dark` colour or an `rgba2`/`rgb2` timeline; parsed, then ignored |
 | `A13_MESH_BUDGET` | renderer | more mesh slots than the rig's `invariants.meshSlots`, or a mesh over its `invariants.meshTriangles`. Thin the mesh, or raise the budget in the rig spec. **SKIP** when the rig declares neither — which means *unmeasured*, not that the budget is inert: the same `meshSlots` is a **compile-time** refusal for rigc's own generators, before the gate (§3.7, issue #274) |
-| `A14_NO_FULL_FRAME_MESH` | renderer | a mesh spans the whole stage — a full-frame canvas that can never dirty-skip |
-| `A15_IDLE_NO_MESH_BONE_KEYS` | renderer | the `idle` animation keys a bone that drives a mesh, directly or as a control bone |
+| `A14_NO_FULL_FRAME_MESH` | renderer | a mesh spans the whole stage — a full-frame canvas that can never dirty-skip. **SKIP** when the skeleton declares no stage (§3.1): there is no full frame to span, and *unmeasured* must not print the same green as *measured and clear* |
+| `A15_IDLE_NO_MESH_BONE_KEYS` | renderer | the `idle` animation keys a bone that drives a mesh, directly or as a control bone. **SKIP** when there is no `idle` animation, or when the one there is carries no bone timeline — a rule whose subject does not exist is unmeasured and not satisfied ([#568](https://github.com/firejune/rigc/issues/568)) |
 | `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 |
@@ -3583,7 +3875,7 @@ The report prints one line per assertion:
 | `A23_PHYSICS_CONSTRAINT_EFFECTIVE` | both | a physics constraint that drives no component, is muted by `mix: 0`, has `mass: 0`, has `strength: 0`, or has `damping` outside `(0, 1)` so it never settles |
 | `A24_AXIS_SPACE_STROKE` | archetype | a bone under the rig's `axisBone` was keyed with a screen-space Y component, or the axis bone itself was keyed |
 | `A25_DETACHED_BONE_PARENTAGE` | archetype | a bone the rig declares `detached` is a descendant of the bone it must never hang under |
-| `A26_SLOT_DRAW_ORDER` | archetype | the emitted slots are not a subsequence of the rig's slot table — a slot is out of order, or is not in the table at all |
+| `A26_SLOT_DRAW_ORDER` | archetype | the emitted slots are not the rig's slot table — a slot is out of order, is not in the table at all, or is in the table and missing from the skeleton (§3.3) |
 | `A27_REGION_NAME_MATCHES_PAGE_FILENAME` | renderer | a single-region page whose region name is not the PNG's basename |
 | `A28_RIBBON_ROWS_SHARE_WEIGHTS` | archetype | the two vertices of a ribbon row carry different weights, so the strip would change width. **SKIPs** on authored geometry and on a contour mesh — neither has rows rigc paired |
 | `A29_STROKE_WITHIN_CONTACT_DEPTH` | archetype | the animation drives deeper than the manifest's measured contact depth |
@@ -3607,19 +3899,30 @@ clauses are gated by profile.
 
 ## 6. What rigc will refuse — do not spend a loop on these
 
-These are in the Spine 4.3 format, and the emitter does not write them. Each one is
-a **`NotImplementedError` naming the field**, because the parser's own behaviour is
-worse: an unknown attachment `type` returns `null` and the attachment disappears,
-and a constraint entry with an unrecognised `type` matches no case and vanishes.
+Most of these are in the Spine 4.3 format and the emitter does not write them. Each
+of *those* is a **`NotImplementedError` naming the construct**, because the parser's
+own behaviour is worse: an unknown attachment `type` returns `null` and the
+attachment disappears, and a constraint entry with an unrecognised `type` matches no
+case and vanishes.
 
-Each is deferred for a stated reason, and the reason is the same one in every row:
-**neither of these types appears anywhere in the benchmark corpus** (SPEC_COVERAGE
+A deferral carries its reason, and the reason is the same one in every deferred row:
+**neither of those types appears anywhere in the benchmark corpus** (SPEC_COVERAGE
 parts 3-1 and 4-2), so neither is on the ladder's critical path. The message
 says so, because a deferral without its reason is a wall rather than a work item.
 
+⚠️ **A spelling the format does not have is a different refusal and says so.**
+`sequence` is not an attachment type, and a `"type"` that is `null` is not an absent
+one — telling either author that "rigc does not emit it yet" promises work that will
+never be done, on a map the parser would have dropped in silence. Those rows below
+are `CompileError`s, and they name what the format actually defines
+([#577](https://github.com/firejune/rigc/issues/577)).
+
 | You wrote | You get |
 | --- | --- |
-| attachment `type` of `point` or `linkedmesh` | `attachment type "X" is in the Spine 4.3 format and rigc does not emit it yet. Implemented: region, mesh, boundingbox, clipping, path. point and linkedmesh are deliberately deferred: neither appears anywhere in the benchmark corpus …` |
+| attachment `type` of `point` or `linkedmesh` | `this attachment is a "linkedmesh" — a mesh that takes its geometry from another mesh instead of stating any — a region/mesh head, then "source" …. rigc does not emit it yet, deliberately: it emits region, mesh, boundingbox, clipping, path, and neither a point nor a linked mesh appears anywhere in the benchmark corpus …` — the message names the **construct**, not just its type string, and part 1-6 is where the sentence comes from |
+| a mesh carrying `source` (`type: "mesh"` **or** `type: "linkedmesh"`) | the same refusal, prefixed `(a mesh carrying "source" is one)`. The two spellings share one parser branch and `source` is what decides between them (SPEC_COVERAGE part 1-6), so `source` on a mesh is a linked mesh whatever `type` says. It used to be refused as *2 keys this compiler does not read: "source", "skin" … fix the spelling or remove it*, whose remedy destroys the construct ([#577](https://github.com/firejune/rigc/issues/577)) |
+| attachment `type` of anything else — `sequence`, a typo | `attachment type "X" is not one of the 7 the Spine 4.3 format defines (region, mesh, linkedmesh, boundingbox, path, point, clipping). … the attachment is dropped from the skeleton without a word` — a **`CompileError`**, not a deferral: rigc is not going to implement a name the format does not have. (`sequence` is a key on a region or a mesh, not a type of its own.) |
+| `"type": null` | `"type" is null, which is not a name. … PRESENT-and-null is not absent: getValue(map, "type", "region") takes the default only when the key is missing, so this map matches no case, readAttachment returns null, and the attachment is dropped from the skeleton without a word. Remove the key, or name a type.` Leaving the key **out** is legal and reads as `region`; writing it as `null` is not the same thing ([#577](https://github.com/firejune/rigc/issues/577)) |
 | constraint `type` of anything else | `constraint type "X" is not one Spine 4.3 knows. The five are: ik, transform, path, physics, slider.` — all five are emitted, so this is a typo, and a typo is what the parser drops in silence |
 | a path attachment's `lengths` | `"lengths" is not authored — rigc measures the setup arc length of each curve off the geometry` (§3.4). Not a deferral: a second copy of a number the vertices already fix |
 | a `deform` timeline on a path attachment | `a path attachment does have a vertex array, and rigc does not key it yet` — the format allows it and an animated track is a real idiom, but a deformed path invalidates the `lengths` a `constantSpeed: false` traversal reads. Move the curve by posing the bones its vertices are bound to |
@@ -3648,19 +3951,35 @@ Two more limits that are not errors but will shape what you can attempt:
 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.
+   📎 The two profiles judge attachment **naming** identically since
+   [#574](https://github.com/firejune/rigc/issues/574): `spine-html` adds the
+   renderer and archetype rules and has no opinion about how an attachment is
+   spelled, so a rig whose named skins share a placeholder (§3.4.2) is green
+   under either. Before that it was green under exactly one of them, and which
+   one was not a property of the rig.
 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.
+   them is a check you were relying on. The summary's *measured* figure is the
+   shortest version of this step: it is how many of the rules actually looked at
+   anything, and it is the number to quote when you say a rig gated green.
    ⚠️ Under `--profile spine` a foreign skeleton usually produces **no SKIP lines
    at all**, and that is not a clean bill of health. The archetype assertions are
    excluded by the profile before the missing `invariants` block could make them
    skip, so they come back `PROF` instead. Do not go looking for a SKIP that the
    profile already accounted for; read step 3 instead.
+   ⚠️ And a **red** report is where this step matters most, which is the opposite
+   of how it reads: if `A00` failed, most of the SKIP lines say the round trip
+   denied them a result, and the handful of `PASS` rows beside them were measured
+   on the raw text alone. Step 1 already sent you back; do not take anything from
+   the rest of that report on the way ([#568](https://github.com/firejune/rigc/issues/568)).
 3. Read the `PROF` lines. They are where "was this rig held to that rule at all"
    gets answered for everything the profile left out — the renderer policy *and*
    the archetype rules. A green under `spine` has been held to neither; a green
    under `spine-html` has been held to both.
-4. Run `explain` and read the slots table: every slot you declared should be there
-   (§3.3), in the order you meant, showing the setup attachment you meant.
+4. Run `explain` and read the slots table: every slot you declared **is** there
+   (§3.3 — `A26_SLOT_DRAW_ORDER` holds that, and a slot nothing fills reads
+   `setup=null attachments=[]`), so what this step is for is the two things the
+   gate cannot check — that the order is the one you meant, and that each slot
+   shows the setup attachment you meant.
 5. If you were given **frames**, run `check` and read the table (§9). Steps 1–4 are
    all about validity and structure; none of them can tell you the animation is
    wrong, and this is the step that can. Do it before step 6, not after — `bench`
@@ -4142,10 +4461,48 @@ your animation is called something the frame directory is not, `--framing shared
 to fit one framing across every set instead of one each,
 `--texture-from <atlas>` to attribute how much of the MAE is texture resampling
 rather than the rig (**§9.2**'s atlas floor — and note that it is *not* `--atlas`,
-which re-seats your geometry on that atlas's packing), `--all-frames` to list
+which re-seats your geometry on that atlas's packing), `--skin <name>` to pose
+your candidate under one of its skins (below), `--all-frames` to list
 every frame instead of the worst by MAE, `--json <out>` for the whole per-frame,
 per-slot report.
 
+🚨 **What `check` certifies is the DEFAULT skin, unless you pass `--skin`**
+(issue #571). With no `--skin` no skin is set at all, which is `spine-core`'s own
+initial state: every slot resolves through `SkeletonData.defaultSkin` alone, and a
+slot whose art lives only in a named skin draws **nothing** — on both sides, since
+the reference frames came out of the same renderer. A multi-skin rig checked that
+way compares blank against blank and reports `MAE mean 0.00`, which reads like the
+best possible answer and is a measurement of no art at all. On a single-skin rig
+this is the whole rig and there is nothing to pass.
+
+So a multi-skin rig is checked **once per skin**, and both sides are rendered
+under the same one:
+
+```bash
+bun cli.ts render --candidate path/to/spine --skin patch --out frames/patch
+bun cli.ts check  --candidate path/to/spine --frames frames/patch --skin patch
+```
+
+Three things keep that honest, and none of them is a convention you have to
+remember:
+
+- `render --skin` writes the name into `frames.json`, so a frame set says which
+  picture of the rig it is. A set rendered with **no** `--skin` records nothing,
+  because "no skin was set" and "this file predates the field" are the same bytes
+  on disk and neither is a claim.
+- `check` reads that back. A candidate posed under a **different** skin from the
+  one the frames record — or under none, where the frames name one — is
+  **refused by name** rather than scored, because the number would be about the
+  difference between two skins. Frames that record nothing cannot be checked, and
+  the report says so in a `⚠️` note instead of implying agreement.
+- The report header names the skin on both sides on every run, `--skin` or not:
+  `skin  candidate patch   frames patch`, or `candidate no skin set (the default
+  skin alone)`. `check.json` carries the same two under `skin` and
+  `referenceSkin`.
+
+A skin name the candidate does not declare is refused with the ones it does —
+`the candidate declares no skin "path"; it declares [default, patch, torn]`.
+
 ⭐ **A frame set may ship a contact sheet instead of every frame, and the sheet is
 compared too.** A long shot does not commit 311 near-duplicate PNGs: rung 2's sets
 ship `f0000.png` and `f0310.png` plus a `contact.png` holding all 311 sampled