@rig-c/core 2.81.1 → 2.82.1

package/README.md

@@ -51,6 +51,22 @@ Everything in that table needs Bun and this package — `preview` and `vote` als
 `@esotericsoftware/spine-core` installed beside it (see below) — and no clone, no
 reference art, no art pipeline, no server.
 
+### Depth-driven rigging
+
+Explicit depth, which a drawing alone does not state, makes facial features
+shift by different amounts during a small head turn: [`gallery/portrait`](https://github.com/rig-c/core/tree/main/gallery/portrait)
+uses per-part depths, while [`gallery/look`](https://github.com/rig-c/core/tree/main/gallery/look)
+samples a depth map at the mesh vertices.
+With [`@rig-c/parts`' depth fields](https://github.com/rig-c/parts/blob/main/docs/AUTHORING.md#per-layer-depth-sheets-773),
+See-through's per-layer sheets are bound explicitly with `near` and `zScale`,
+then consumed by head-turn roles in `turn.roles`.
+The [depth-yaw flow](docs/FACE.md#a-measured-alpha-aperture) shows how a turning
+surface and its alpha clipping aperture move together.
+The [value-driven turn](docs/FACE.md#the-turn-as-a-value-rather-than-a-time) is a
+rig control; the consumer chooses when to move it, and
+[getting-started](https://github.com/rig-c/getting-started) is the painting-to-rig
+walkthrough.
+
 ### Alpha-derived clipping
 
 Alpha-derived clipping takes a named source slot/skin/attachment plus explicit
@@ -59,7 +75,8 @@ Region, authored/resolved linked mesh and generated grid/contour depth sources u
 ordinary weighted clipping, with the existing validation gate before emission.
 See [AUTHORING: Alpha-derived clipping](docs/AUTHORING.md#alpha-derived-clipping)
 for source-motion limits, fit reports and named refusals, and
-[the face guide](docs/FACE.md#a-measured-alpha-aperture) for the depth-yaw flow.
+[the face guide](docs/FACE.md#a-measured-alpha-aperture) for the depth-yaw flow
+used in depth-driven rigging.
 
 ## What rigc is, and what it is not
 
@@ -89,45 +106,7 @@ it cuts both ways:
 
 ### Licensing, stated plainly
 
-rigc's own code is MIT (see [LICENSE](LICENSE)). That says nothing about Spine, and
-the following is a restatement of Esoteric Software's terms, not a term of ours:
-
-1. rigc's output **is Spine skeleton data**.
-2. A product that plays it with **a Spine Runtime** — the official runtimes, the Web
-   Player — has integrated the Spine Runtimes. rigc also writes the model document
-   its own core poses, and a product may play that or anything else; what the terms
-   turn on is the integration.
-3. Integrating a Spine Runtime into a product is permitted **under Section 2 of the
-   [Spine Editor License Agreement](https://esotericsoftware.com/spine-editor-license)**,
-   or otherwise on the condition that **each user of the product obtains their own
-   Spine editor licence** and the product carries the Runtimes licence and copyright
-   notice — the Runtimes licence's own two routes, in its words.
-4. The published rigc **links no Spine runtime**. This repository does — `spine-core`
-   as a development dependency, for its own gate — and so does an install with the
-   runtime added beside it.
-
-> **If a product integrates a Spine Runtime to play rigc's output, that integration
-> is subject to the terms above** — rigc neither adds those terms nor removes them.
-> Running the published rigc links no Spine runtime, and whether its output is then
-> played by one, by rigc's own core, or by something else is the consumer's choice.
-
-See [NOTICE.md](NOTICE.md) for the full notice.
-
-📐 **What of Esoteric Software's is in this repository, and under what grant.** No
-example asset is committed: `bun run fetch-examples` downloads the example projects
-into a gitignored `examples/`. What *is* committed is `bench/reference/` — 1,293 PNG
-frames **this project renders** from those examples' own exports, so a frame carries
-those images' pixels and committing one **is** redistribution. Each example's own
-`license.txt` permits exactly that, *"as long as they are accompanied by this license
-file"*, and a verbatim copy of it sits at each example root here — all eight, written
-there by the render script rather than left to memory. The same file's
-**non-commercial** condition rides along with those images, and
-[LICENSE](LICENSE) says so: rigc's MIT grant covers rigc's own code, documentation
-and art, not this material. `7-anticipation` publishes no `license.txt` upstream, so
-no such grant exists for it and its frames are never committed — they render only
-into a gitignored directory, enforced by `git check-ignore`. Full reasoning:
-[`bench/reference/README.md`](https://github.com/rig-c/core/blob/main/bench/reference/README.md)
-(repository material, not in the npm package).
+See [NOTICE.md](NOTICE.md) for licensing and third-party terms.
 
 The problem rigc is aimed at is narrow. An agent asked to author a rig has no way
 to tell whether it succeeded: Spine's JSON parser accepts a great deal of nonsense
@@ -467,39 +446,7 @@ origin and tip in world units and in pixels, so a position read off the picture
 straight back into the spec. [AUTHORING §13](docs/AUTHORING.md#13-asking-the-picture-a-question--rigc-inspect)
 maps each question to its view.
 
-**`render`** samples every animation at 12 fps and writes `render/<animation>/f0000.png…`
-with a `contact.png` beside them — every frame of the shot as one labelled grid,
-which is the picture to open first, because spacing is a comparison *across*
-frames. It draws with rigc's own rasteriser (the one `check` measures with), so
-it needs no browser and no network, and the `frames.json` it leaves beside the
-directories makes the result a frame set like any other — the world box every
-frame is a picture of. `--animation <name>` narrows it to one, `--fps` and
-`--max` change the rate and the frame size. A set drawn at any rate but the
-default is written to `<anim>@<fps>fps/` rather than `<anim>/`, so two rates sit
-side by side: `--fps 24` writes `<anim>@24fps/`, and the default 12 writes
-`<anim>/`. Each set's summary line ends with the directory it wrote.
-
-> 🚨 **`--skin <name>` if your rig has more than one.** With no `--skin` no skin
-> is set at all, so every slot resolves through the **default** skin alone — and
-> a slot whose art lives only in a named skin draws *nothing*. That is not a
-> quirk of `render`: `check` compares `render`'s frames, so a multi-skin rig
-> checked with no skin compares blank against blank and reports a perfect
-> `0.0000` about art nobody drew. `render --skin` records the name in
-> `frames.json`, `check --skin` poses the candidate under it, and a candidate
-> scored against frames rendered under a *different* skin is refused by name
-> rather than measured.
-
-**`preview`** writes a single self-contained `.html`: your skeleton, your atlas
-and every page's PNG bytes are embedded in it as data URIs, and it plays them in
-the **official [Spine Web Player](https://esotericsoftware.com/spine-player)**.
-Double-click it, or attach it to a message — the file carries the whole artifact.
-It is also the strongest interop statement in this repository: a rig that plays
-there has been played by Esoteric Software's own runtime rather than by ours.
-
-> ⚖️ The player itself is **referenced, not embedded** — the page loads it from
-> unpkg, so the first open needs a network, and rigc redistributes nothing
-> Esoteric Software owns (see [NOTICE.md](NOTICE.md)). Everything the player
-> draws is inside your file.
+**`render`** writes PNG frames and a contact sheet; **`preview`** writes a playable HTML file — see [AUTHORING §0](docs/AUTHORING.md#0-the-loop).
 
 **7. Let someone choose.** Sooner or later you will have two builds that both pass
 the gate and no instrument that can separate them. `vote` puts them in one page
@@ -523,7 +470,7 @@ that does not belong to it. See
   field by field, the emission rules, every named failure mapped to the file that
   has to change, and §8–§9 for reproducing a shot you were given as pictures. It
   ships inside the npm package too, at
-  `node_modules/rig-c/docs/AUTHORING.md`.
+  `node_modules/@rig-c/core/docs/AUTHORING.md`.
 - `rigc explain --rig buoy.rig.json --motion buoy.motion.json --out spine` prints
   the compiled rig as a table — every bone with its resolved parent, the slots in
   draw order, every timeline key by key — and writes nothing. It is what to reach
@@ -631,203 +578,42 @@ material, like the gallery: a clone runs them.
 
 ## Commands
 
-Every command takes its paths explicitly. `rigc <command> --help` prints its flags —
-`rigc help <command>` prints the same page — and
-[AUTHORING.md §0](docs/AUTHORING.md) is the same list with what each flag means, which
-commands take it and what its default is.
+`rigc help <command>` prints the command’s flags; [AUTHORING §0](docs/AUTHORING.md#0-the-loop) is the CLI reference.
 
 | Command | Does |
 | --- | --- |
-| `build --rig … --motion … --out …` | compiles, gates, and **writes only if the gate is green**. `--images <dir>` says where the rig spec's `image` names resolve, `--manifest` adds measured art, and `--copy-images` copies every page PNG into `--out` so the directory is self-contained, with `skeleton.images` pointing at it so the editor's import finds the parts |
-| `build … --pack` | the same build with every part arranged onto **shared** atlas pages, written into `--out` — losslessly, and gated a second time as the pair that ships. `--page-size`, `--padding`, `--page-edges` and `--pack-shape` tune it — `--pack-shape polygon` lets a neighbour sit inside a mesh's rectangle where its hull is not, and with `--page-edges free` costs 12–56 times `rect`'s pack (3–11 s against 0.2–0.3 s on 90–144 parts over two to four pages; past 5 s from about 60 parts, a second or so below 45 on one page — AUTHORING §0.1) |
-| `build … --atlas-in <file.atlas>` | the same build with every part resolved to a **region of an existing pack** instead of a loose PNG; a name the atlas lacks, a size the spec disagrees with or a rectangle off its page is refused by name |
-| `validate <dir>` | re-gates artifacts already on disk |
-| `repack <dir> --out <dir>` | a packed build **repacked from its own output** — `skeleton.json`, `skeleton.atlas` and the pages, with no parts kept — under the packing flags `build --pack` takes, so a packer improvement reaches a build whose parts are gone. Every region is lifted off its page, the skeleton read back with `ingest`, and `build --pack` run over the lifted parts with the same gate; it writes only after every region is shown pixel-identical to the input's, the skeleton byte-identical and the gate green, and refuses by name an atlas it cannot lift exactly. A skeleton the rebuild does not reproduce byte for byte — a build written before 2.2.0, whose header box was its stage — is refused naming every differing path, and written, every path printed, only under `--accept-skeleton-differences`. `--stage-box <slot>` reads the stage from the box a build carries for it (`skeleton.stageBox`), the one way the three files alone carry the stage exactly ([AUTHORING §0.4](docs/AUTHORING.md)) |
-| `repack <dir> --out <dir> --keep-pages` | **`skeleton.model.json` alone, for the pages already in place** — for a player that reads the document beside an atlas and pages that already shipped. The same read and stage rules, then `build --atlas-in` over the input atlas in place of the lift and the pack; it writes the document, and nothing else, only after its `pages` are shown to state the atlas as it stands, the rebuilt skeleton byte-identical to the one on disk (so `spine.sha256` names it — no acceptance flag here) and the gate green. `--out` is usually the build's own directory and must not already hold a `skeleton.model.json`; a page or region line the document has no field for is refused by name ([AUTHORING §0.4](docs/AUTHORING.md)) |
-| `ingest <skeleton.json> --out <dir>` | `build` run backwards: reads a Spine 4.3 skeleton and writes the rig spec and motion spec that **rebuild it**, plus a findings report naming everything it could not carry. a skeleton that declares no stage is carried as declaring none, `--stage x,y,w,h` adds a box to one — and is refused, rather than ignored, beside one that declares a box — and `--images <dir>` writes the spec's own images directory — the opposite direction from `build --images`, which overrides it — so the rebuild carries no flag at all |
-| `split --rig … --motion … --slot <name> --out <dir>` | the answer to a mesh refused because its triangles are **several pieces that share no vertex** — two legs after the triangles bridging them were deleted. It reads the two specs and writes them back into an absent or empty `--out` with one mesh per piece: piece 1 stays in the slot, piece k gets a new slot `<slot>_<k>` after it, each with the original's uvs and weights unchanged, its triangles renumbered outline first where the hull rule needs it, and every deform key re-sliced to the new indices — plus `split.json`, where every original vertex and triangle went. One piece is said so and nothing is written; what it cannot carry is refused by name ([AUTHORING §3.4.11](docs/AUTHORING.md)) |
-| `explain --rig … --motion …` | the compiled rig as a table — every bone with its resolved parent, the slots in draw order, every timeline key by key. Writes nothing. What to reach for when a rig compiles and still looks wrong |
-| `render --candidate <dir>` | PNG frames plus a contact sheet, in `render/`, one directory per set: `<anim>@<fps>fps/` rather than `<anim>/` at any rate but the default — `--fps 24` writes `<anim>@24fps/`, and the default 12 writes `<anim>/`. `--hide <slot,…>` or `--slot <slot,…>` draws part of the rig on the **same grid** as the whole, so the two frames overlay and the difference is the part; `frames.json` records the subset and `check` refuses such a set as a reference. `--geometry` adds a `geometry.json` per set: every frame's bone world transforms and skinned attachment vertices, with the rest geometry, on the frames' own grid. `--folds` adds a `folds.json` per set and prints one line per mesh with a triangle turned over against the setup pose: the frames, the worst frame's count and which triangles, their world box and their setup-pose area. `--pass-through <cloth>:<leg>` adds a `pass-through.json` per set and prints the frames where a cloth drawn over a leg has its side inside the leg's drawn outline, with the depth and the world box — a reading, not a gate. `--seam <slot>:<slot>` adds a `seam.json` per set and prints, per pair, the frames where two slots that meet open background inside the joint (a gap) or show the overlap band of one past the other (a ghost), with the worst frame's cell count and world box; `ghostA` and `ghostB` partition the same ghost by which named pair member drew it, each with its own frames, spans and worst; `gapOpen` and `gapCovered` partition `gap` by zero versus positive rendered alpha from the whole skeleton, including faint and clipped drawings ([AUTHORING §8.8](docs/AUTHORING.md#88-where-two-slots-stop-meeting--render---seam)) — a reading, not a gate; the exit status never moves. `--overlaps` adds an `overlaps.json` per set and prints one `OVERLAP "<under>" under "<over>"` line per pair of slots where the one drawn later covers the earlier one and the motion moves it — the frames, and the most pixels covered and the frame of them — with an outline plate per covered frame; the render reports what was drawn, and the draw-order key is the author's remedy — a reading, not a gate. `--extremes` adds `extremes.json` and a native six-panel `extremes.png` (setup, geometry-pair min/max and three premultiplied RGBA diffs with a legend), plus one `EXTREMES` line per set. Per-channel minima/maxima and the farthest original-vertex geometry pair are distinct readings; valid channel extrema survive a geometry/image SKIP, with channel refusals reported separately; still or uncomparable geometry reports a named SKIP without changing render exit status. Look at min, max and diff before a person does ([AUTHORING §8.11](docs/AUTHORING.md#811-min-max-and-diff-before-a-person-looks--render---extremes)). `--angle-range <bone>:<relative-to>` prints how far one bone turns against another over each set: the lowest and highest angle and the frames they fall on — a reading, not a gate. `--viewport <x,y,w,h>` or `--viewport-from <frames.json>` draws over a given box instead of a fitted one, so two builds land on one pixel grid; a slot that reaches past it is named by set and frame, and `frames.json` records it. `--environment <schedule.json>` draws the rig under the wind and gravity its physics answers, in time — the same frames on the core and on spine-core; an inspection of the response the rig states, not a scene. `--sheet [--sheet-format json-hash] [--page-edges pot\|free]` also packs each set's straight-alpha transparent frames into `sheet.png` + `sheet.json` (TexturePacker JSON Hash with a shared world-origin `anchor` and `2`-px clamped edge extrusion, verified through `pixi.js@8.22.0` and `phaser@3.90.0` by `tools/sheet_readers.ts`) and `sheet-manifest.json` (`rigc-sheet/1`), leaving diagnostic `f####.png` and `contact.png` unchanged ([AUTHORING §8.10](docs/AUTHORING.md#810-sprite-sheets-from-a-render--render---sheet)) — a self-contained sprite object per animation set; when animations play and how a scene is composed remains the consumer's |
-| `preview --candidate <dir>` | one self-contained `.html` that plays it, headed by the line `validate <dir>` prints for it and the rigc version — a refused candidate is still previewed, and its header says so in the gate's words. Repeat `--candidate` for one page with a pane per candidate, in the order given; a green `build` ends by naming this command for its own `--out` |
-| `vote --candidate a --candidate b` | one `.html` that asks a human which; `vote --record <file>` checks the answer into `votes.jsonl` |
-| `pose --images <dir> --frame <png>` | reads part placements **out of** a picture |
-| `chainfit --candidate <dir> --images <dir> --frame <png>` | reads the parts `pose` refuses, through the candidate's own draw order and hierarchy: masked residuals over **visible** pixels, one hinge per child instead of four degrees of freedom, and the `rotate` key value each answer implies. A bone with two or more anchored descendants is **determined** rather than searched, and the residual that over-determination leaves is reported |
-| `diff <candidate.json> <reference.json>` | structural comparison of two skeletons, one ratio per measure and deliberately no combined score |
-| `bonedist --candidate … --reference … --bones …` | per-frame, per-bone world-transform distance against another skeleton — the ladder's stage 3, run on its own. `--bones <correspondence.json \| identity>` is required rather than defaulted: a candidate is entitled to its own bone names, so the pairing is stated |
-| `check --candidate <dir> --frames <dir> [--out <dir>]` | the candidate against reference pictures — the only instrument here that can see a *wrong animation*. `--out` also writes, for every frame the table lists, the picture its figures came from: reference, candidate, difference and overlay at native size |
-| `bench <rung> --candidate <dir>` | one rung of the benchmark ladder |
-| `guide <RULE>` / `guide §<n>[.<m>[.<k>]] [--all]` | the guide's row for the rule a failure line names — every `FAIL` line, `vote --record` refusal, `ingest` finding and coded compile error ends with ` (see rigc guide <RULE>)`; only legacy uncoded library errors point at `§5.1` — or a section's heading, own prose and subsection index, read from the installed `docs/AUTHORING.md` when it runs. `--all` includes the subsection bodies; a leaf prints its full text either way. Sizes describe full ledger spans. `--all` with a rule is refused, exit 2; an unknown name is refused with the nearest real ones, exit 1 |
-| `skills install [--dir …] [--copy]` | links every agent skill the package ships into `.agents/skills` (or `--dir`) as relative symlinks, or copies them with `--copy` — where Codex, Gemini CLI and Antigravity look. A second run has nothing to do; an entry already there that is not this command's is refused by name and nothing is written |
-| `review <dir> […]` | the human review of a build, handed to the `rig-review` bin of `@rig-c/review` installed beside the package; rigc does not depend on it and never installs it. `rigc review <dir> [--reference <video>] [--animation <name>] [--compare <dir>]` is `rig-review open <dir> …` with those flags 1:1 and prints the loopback URL to give a person; a first argument that is one of review's own words (`open`, `check`, `feedback`, `control`, `strip`, `compare`) or starts with `-` (`--help`, `--`) is handed over untouched. stdout is review's byte for byte, stderr review's plus the launcher's own refusals, the exit code review's. Refused by name, exit 2, before the bin starts: `REVIEW_OUTPUT_MISSING <path>` (the target is not a directory); `REVIEW_NOT_INSTALLED` with two lines, `bun add -d @rig-c/review` and `bunx @rig-c/review open <dir> …` carrying the flags given — the same on a terminal and off, with nothing installed or written; `REVIEW_BUN_TOO_OLD: Bun <found>, @rig-c/review needs <required>`, the floor read off the installed package's `engines.bun`; and an empty argument (`""`) under a Bun that drops one (Bun 1.2.0, measured by a probe), `rigc review: argument N is empty, and Bun <version>, the Bun running this, drops an empty argument when it starts a process — …`. docs/AUTHORING.md lists every line |
-
-`diff`, `bonedist`, `check` and `bench` measure against something you were given; the
-first three work on any reference you have, and `bench` is a repository workflow that needs a clone
-and `bun run fetch-examples`. The reasoning behind them is in
-[the benchmark dossier](https://github.com/rig-c/core/blob/main/docs/BENCHMARK.md).
-
-`build` and `validate` both default to `--profile spine` — the 36 validity rules, which
-ask *is this valid Spine 4.3 that any runtime plays correctly?* `--profile rig-play`
-adds all 50: the other 14 are one renderer's policy and one canvas budget's, and they
-fire on perfectly correct editor-produced Spine data, which is why they are opt-in.
-⇒ **That reason is about foreign data and does not carry to a rig you are authoring
-yourself: author under `--profile rig-play` and read the extra 14 as findings, and
-gate the release under `--profile spine`.** A `deform` key that folds a mesh inside
-out is written out under the default and refused by name under `rig-play`, which
-is the shape of what that split buys you. A report always names
-the profile it ran and lists what that profile left out.
-
-Several cuts can also be registered in a `cuts.json` and built by name
-(`build --cut my_cut --cuts path/to/cuts.json`); every path in that table resolves
-relative to the `cuts.json` file itself, so the table lives with the project that owns
-the art. Its shape is under
-[Usage](https://github.com/rig-c/core/blob/main/docs/BENCHMARK.md#usage).
+| `build` | Compile, gate and write the rig. [Reference](docs/AUTHORING.md#0-the-loop). |
+| `validate` | Re-gate artifacts already on disk. [Reference](docs/AUTHORING.md#0-the-loop). |
+| `repack` | Repack a build from its output. [Reference](docs/AUTHORING.md#0-the-loop). |
+| `ingest` | Read a skeleton back into specs. [Reference](docs/AUTHORING.md#0-the-loop). |
+| `split` | Separate disconnected mesh pieces. [Reference](docs/AUTHORING.md#0-the-loop). |
+| `explain` | Print the compiled rig as a table. [Reference](docs/AUTHORING.md#0-the-loop). |
+| `render` | Write PNG frames and a contact sheet. [Reference](docs/AUTHORING.md#0-the-loop). |
+| `preview` | Write a playable HTML preview. [Reference](docs/AUTHORING.md#0-the-loop). |
+| `vote` | Make a ballot and record its answer. [Reference](docs/AUTHORING.md#0-the-loop). |
+| `pose` | Read part placements from a picture. [Reference](docs/AUTHORING.md#0-the-loop). |
+| `chainfit` | Read occluded parts through a candidate rig. [Reference](docs/AUTHORING.md#0-the-loop). |
+| `diff` | Compare two skeletons structurally. [Reference](docs/AUTHORING.md#0-the-loop). |
+| `bonedist` | Measure per-bone world-transform distance. [Reference](docs/AUTHORING.md#0-the-loop). |
+| `check` | Compare a candidate against reference pictures. [Reference](docs/AUTHORING.md#0-the-loop). |
+| `bench` | Run a rung of the benchmark ladder. [Reference](docs/AUTHORING.md#0-the-loop). |
+| `guide` | Read a named failure or guide section. [Reference](docs/AUTHORING.md#0-the-loop). |
+| `skills install` | Install the packaged agent skills. [Reference](docs/AUTHORING.md#0-the-loop). |
+| `review` | Hand a build to the review package. [Reference](docs/AUTHORING.md#0-the-loop). |
 
 ### Starting from a skeleton you already have
 
-`rigc ingest` reads a Spine 4.3 `skeleton.json` and writes the two spec files that
-rebuild it. It is the only command that runs against `build`'s direction, and the
-only one whose contract is an equality rather than a rulebook:
-
-```bash
-rigc ingest hero.json --out specs/ --images parts/
-rigc build --rig specs/rig.json --motion specs/motion.json --out build/
-rigc diff build/skeleton.json hero.json
-```
-
-`--images parts/` is what makes the second line carry no flag: it writes the spec's
-own `images` directory, spelled from `--out`, so the specs are self-contained from
-there on. Leave it off and the `image` names resolve against `specs/` itself, which
-holds no art — every rebuild then has to repeat `build --images parts/`.
-
-**`build(ingest(x))` is `x`.** Over the eleven rigs this repository builds — the seven
-gallery examples, the three generated probes and a coverage probe written for the
-purpose — the rebuilt `skeleton.json` is byte for byte the file the decompiler read.
-The atlas is held to a weaker
-claim on purpose, and the weakening is measured rather than assumed: it comes back
-equal as a **multiset of region blocks**, because the order the pages are collected in
-is in no field of the skeleton.
-
-**And over twelve skeletons nobody here wrote.** Every editor export in the fetched
-example corpus, ingested, rebuilt through the pack beside it and `diff`ed against the
-source, comes back **12 of 12, no blockers, 1.000 on every measure the report
-carries** — and each rebuild is its export's own text in canonical form, apart from
-the header's `hash` and `spine`: the editor's project hash and the runtime version
-rigc stamps, the two keys the rig spec has no field for by design (12 of 12) — and
-the header's box, which `build` computes rather than carries (issue #907): the rebuild
-writes spine-core's `getBounds` over the export on the header's 1e-6 grid at float32, equal on all twelve,
-where the editor wrote its own arithmetic, up to 0.0071 units away.
-[INGEST.md §2.3](docs/INGEST.md) states that pass line and why those two are the
-exceptions.
-
-**What it reads is skeleton JSON and nothing else** — no `.spine` project, no binary
-`.skel`, no atlas, no art. So it never invents, and the things it cannot get out of
-the file are **findings** with codes rather than plausible values: a construct the
-spec format cannot hold (`point`, a `sequence` block, an unknown field
-on a bone, slot or constraint) is a blocker, the command exits non-zero, and both
-specs are still written — a spec plus a list of what is missing from it beats no spec.
-
-⚠️ **Two values are not in a skeleton at all.**
-
-- **The stage.** `skeleton.width`/`height`. A skeleton that declares none is carried as
-  declaring none — the rig spec states `"width": null, "height": null` and the rebuild
-  carries no box either, byte for byte — and `--stage x,y,w,h` is how a
-  caller *adds* one, recorded as a judgement. It is not derivable — posing the rig gives
-  the *animated* extent, which is a different number from the setup box. ⛔ **And `--stage` beside a box the file already states is refused
-  too**, for the opposite reason: two sources for one value, where the file is the record
-  of what was measured. **All twelve exports in the example corpus carry a stage** and
-  none of them needs the flag. It is the value that costs least to get wrong, because
-  `diff` reports the box and gates nothing on it. 🔁 The box an export's header carries
-  is its setup-pose bounding box, and it becomes the rebuild's *stage*; the rebuild's own
-  header is computed again, because since issue #907 `build` writes the setup-pose
-  bounding box there — never the stage — held to spine-core's `getBounds`. 📦 A rig
-  that has to carry its stage in the Spine files asks for it as a bounding box
-  (`skeleton.stageBox`, written by `build` from the stage and held by
-  `A50_STAGE_BOX_IS_THE_STAGE`), and `ingest --stage-box <slot>` reads that box back as
-  the rebuild's stage — [AUTHORING §3.1](docs/AUTHORING.md) has the field and the
-  paragraph for a consumer of the files.
-- **An animation's duration.** The format has no such field. The largest key time is
-  the only derivable answer and it is what a runtime plays to; it is wrong for an
-  animation that holds its last pose past its last key, so it is recorded as a finding
-  on every animation rather than chosen quietly.
-
-Both specs carry a `note` that `ingest` writes itself, saying the file is decompiled
-and naming the skeleton it came from — because a decompiled spec is indistinguishable
-from an authored one by inspection, every gate here calls it green (it *is* green),
-and no gate can catch a missing note.
-
-[docs/INGEST.md](docs/INGEST.md) is the whole page on working from a file you were
-handed; [docs/AUTHORING.md](docs/AUTHORING.md) §0.3 is the loop.
+See [INGEST: Starting from a skeleton you already have](docs/INGEST.md#starting-from-a-skeleton-you-already-have) for the ingest-and-rebuild loop.
 
 ### The editor round trip — for a licence holder, never in CI
 
-`tools/editor_roundtrip.ts` drives the loop the output's whole premise rests on:
-build → **import into the Spine editor** → export back to JSON → gate, `diff`,
-`render` and `check` the export against the build it came from.
-
-```
-bun cli.ts build --rig … --motion … --out build/ --copy-images
-bun tools/editor_roundtrip.ts --build build/ --editor /Applications/Spine.app/Contents/MacOS/Spine
-```
-
-Of the editor's `--version` it records one line, the `Spine <x.y.z> …` line that
-carries the version, and nothing else that command prints — the rest of it
-names the licence holder — or `editor version: not found in --version output`
-where no such line is there. That call carries the same `-u` as the import and
-the export, so a trip pinned with `--editor-version <v>` names the editor it
-pinned and says so on the line (`(read from --version under -u <v>, …)`); an
-unpinned trip names the launcher's default. Once the export exists the version
-is held against the export's own `skeleton.spine`, and a disagreement is a FAIL
-naming both values — the line would otherwise name an editor the trip did not
-run on. It prints the import and export exit codes, the
-validator's verdict on the export, every `diff` measure that moved, `check`'s mean MAE and worst drift per
-animation **for each skin the build and the export both declare** — one
-render-and-check block per skin, with a per-skin roll-up under them, because a
-rig's contested art lives in its named skins and a single un-skinned check draws
-none of it; a skin only one side declares is a FAIL naming it as **lost** (or
-**added**) **by the export**, with `diff`'s `attachments.skins` beside it, and is
-rendered on neither side — and a
-field-by-field list of what the editor rewrote. Every step quotes what its child
-said when that child did not do what it was for, the renderers included — the
-editor's words in full and in order, except its `Licensed to:` line, which names
-the licence holder and is replaced by a line saying it was withheld; a skin
-**neither** side can draw — a hit-box rig, say — is a **SKIP** naming that, not a
-red, because `check` had nothing to compare and `diff` and `validate` have
-already measured the rig. One side drawing where the other does not is the
-divergence the trip exists to find and stays a failure. A human edit made in the
-editor survives the trip back.
-
-🔒 **It requires a licensed Spine editor on the machine, by construction**, and
-drives only the [documented command line](https://esotericsoftware.com/spine-command-line-interface)
-— never the UI, and it produces nothing the editor did not produce. With no
-editor present it refuses by name and exits non-zero, and so does the **trial**:
-the trial cannot save projects or export animation data, so the refusal names
-what it found — the executable, the bundle, the `CFBundleName` that bundle
-declares, or the banner the binary prints about itself — rather than starting it
-and failing downstream. Both refusals point at `--exported <file>`, which
-measures an export the editor already made and is the half of this tool that
-needs no editor at all. A build whose `skeleton.json` is missing, is not JSON, or
-holds JSON that is not one object is refused by name before the editor starts,
-and so is a build with no atlas or an atlas that is a directory, or an
-`--exported` file that is not one JSON object.
-
-⛔ **Run the round trip by hand, on a machine that has the editor.** CI has no
-editor, so no automated check runs it. The by-hand measurement before a landing
-trips the production rigs and one **parts-built** rig, the exam's task-01
-painting through `@rig-c/parts`. The production rigs were authored in the editor,
-so they are already in the editor's own shape. A refusal that only a generated
-rig carries cannot show up on them. Issue #1407 was such a refusal: a green build
-whose meshes listed their bones in two orders, which the editor would not import.
-
-⚠️ Build with `--copy-images`. An ordinary build's atlas names its pages by a
-relative path back to the art directory, and the round trip copies that atlas to
-a directory at another depth — the tool refuses such a build by name rather than
-letting `A17` blame the editor for the harness's own doing.
+See [INGEST: The editor round trip](docs/INGEST.md#the-editor-round-trip--for-a-licence-holder-never-in-ci) for the licensed-editor workflow.
 
 ## Documentation
 
 | Document | For |
 | --- | --- |
-| 📘 **[docs/AUTHORING.md](docs/AUTHORING.md)** | **the format guide, and the one to read before writing a spec.** Both input files field by field with a complete minimal example each, every field with its Spine meaning, the rules that decide what is emitted, the build → read the report → fix → repeat loop, the map from every named failure to the file that has to change, and the features rigc refuses by name so you do not spend a loop discovering them. It travels **inside the npm package**, at `node_modules/rig-c/docs/AUTHORING.md` |
+| 📘 **[docs/AUTHORING.md](docs/AUTHORING.md)** | **the format guide, and the one to read before writing a spec.** Both input files field by field with a complete minimal example each, every field with its Spine meaning, the rules that decide what is emitted, the build → read the report → fix → repeat loop, the map from every named failure to the file that has to change, and the features rigc refuses by name so you do not spend a loop discovering them. It travels **inside the npm package**, at `node_modules/@rig-c/core/docs/AUTHORING.md` |
 | 🦴 **[docs/RIGGING.md](docs/RIGGING.md)** | **authoring the hierarchy.** Where a bone goes and why the art is pushed out on an offset, why a pivot in the wrong place looks like a search failure and what identifies one, moving a pivot and the child row that gets forgotten, gauges, siblings-not-a-chain, what a chain can reach and how many links it needs, why a local key is not a world key, duplicate art at mirrored pivots, and constraints as structure. Every section is a stumble the run records hold more than once, ranked by how often. Ships in the package too |
 | 🎞️ **[docs/MOTION.md](docs/MOTION.md)** | **the key-pose recipe.** How to get two poses, what a pair of poses does and does not fix, the in-betweening rules and where each comes from, and how to spread candidates so a ballot informs. Ships in the package too |
 | 🙂 **[docs/FACE.md](docs/FACE.md)** | **authoring a face.** A blink, a gaze and a 2.5D head turn on plain Spine data: the one line of yaw arithmetic every number in a turn comes from, depth as the parameter you are actually authoring, where to put a grid's columns and the angle at which any grid folds, what foreshortens and what does not, channel allocation before the first key, and the three cliffs with their angles. Also the deform audit gap, demonstrated — a folded mesh gates green — and the differential check that works today |
@@ -836,12 +622,13 @@ letting `A17` blame the editor for the harness's own doing.
 | 🔬 **[docs/SPEC_COVERAGE.md](docs/SPEC_COVERAGE.md)** | **the Spine 4.3 format, field by field.** Every key the 4.3 JSON parser and atlas reader take, what each defaults to, and the parser line it comes from — the rows rigc's refusals cite by part number. Ships in the package too |
 | 🎓 **[the benchmark dossier](https://github.com/rig-c/core/blob/main/docs/BENCHMARK.md)** | **why you can trust the output.** The yardstick, `diff` and `check` and what neither can see, the eight-rung ladder and the spineboy graduation exam, the run viewer, the 50 named assertions with their profiles, and the selftest that has watched every one of them fire. Repository material — it is not in the npm package |
 | 📋 [LADDER.md](https://github.com/rig-c/core/blob/main/docs/LADDER.md) · [GATE.md](https://github.com/rig-c/core/blob/main/docs/GATE.md) · [PILOT.md](https://github.com/rig-c/core/blob/main/docs/PILOT.md) | the live rung ledger, the clause statements a candidate is graded against, and how to run an agent through the ladder and score what comes back |
-| 🔬 [SURVEY_2026-08-22.md](https://github.com/rig-c/core/blob/main/docs/SURVEY_2026-08-22.md) | the survey the ladder was climbed by: rigc and the official examples as measured on 2026-08-22, and the gap list ordered by rung. A dated record, not kept current. Repository material |
 | 🧬 [GENERATIONS.md](https://github.com/rig-c/core/blob/main/docs/GENERATIONS.md) | **Spine data from another generation.** Why a 3.8–4.2 file read as 4.3 fails in silence, the policy that follows (detect from `skeleton.spine`, never guess, play on the matching runtime), what `A16` and `ingest` do with such a file, and the editor as the migration path. Repository material |
 | 📓 [CASES.md](https://github.com/rig-c/core/blob/main/docs/CASES.md) | **converting a Live2D model to Spine, and verifying the conversion.** The method — the source's own player headless, parts from its texture along the drawables, motion baked as deform keys, reference frames first, `check` — run once end to end on two Live2D sample models with no editor and no converter, and verified against the source's renderer and Spine's own runtime: the three instruments, the two rigc defects verifying it led to and v1.2.1 fixed, and where the method stops. Figures only — the models' licence keeps every asset out. Repository material |
 | 🗺️ [ROADMAP.md](https://github.com/rig-c/core/blob/main/ROADMAP.md) | where this is going, and where it has been. What 1.0 had to mean before the number was claimed, and what it was claimed on — conditions rather than a feature list, because direction here comes from what users hit |
 | 📐 [CLAUDE.md](https://github.com/rig-c/core/blob/main/CLAUDE.md) | **the doctrine** — why the validator's messages are the product, why nothing reaches disk before green, why no number is ever invented, and what a change has to keep. [CONTRIBUTING.md](https://github.com/rig-c/core/blob/main/CONTRIBUTING.md) calls it worth ten minutes before a first patch. Repository material |
 
+[Dated survey](https://github.com/rig-c/core/blob/main/docs/SURVEY_2026-08-22.md).
+
 ## Why you can trust the output
 
 rigc is measured against **Spine's own official example projects** — the
@@ -897,5 +684,4 @@ has to clear before it lands. Releases are cut by release-please —
 
 ## Licence
 
-MIT — see [LICENSE](LICENSE). Third-party terms, including the Spine editor licence
-requirement that this project inherits, are in [NOTICE.md](NOTICE.md).
+See [NOTICE.md](NOTICE.md) for licensing and third-party terms.

package/docs/AUTHORING.md

@@ -20,7 +20,7 @@ and has no way to answer. This is not a caveat: a build with **every easing in t
 file reversed** gates green. If you were given pictures, `check` (**§9**) is the half of the loop
 that can see that, and a run that skips it has verified nothing about the motion.
 
-- Formats and CLI reference: [README.md](../README.md)
+- Formats and CLI reference: this guide, starting with [§0](#0-the-loop)
 - The rig spec's own source-level documentation: [`src/rig.ts`](../src/rig.ts)
 - The motion spec and emitted shapes: [`src/types.ts`](../src/types.ts)
 - What the motion spec's own parser proves, and which refusals it deliberately
@@ -113,6 +113,97 @@ can see where Spine stops.
 
 ## 0. The loop
 
+Every command takes its paths explicitly. `rigc <command> --help` prints its flags —
+`rigc help <command>` prints the same page — and
+[AUTHORING.md §0](../docs/AUTHORING.md) is the same list with what each flag means, which
+commands take it and what its default is.
+
+| Command | Does |
+| --- | --- |
+| `build --rig … --motion … --out …` | compiles, gates, and **writes only if the gate is green**. `--images <dir>` says where the rig spec's `image` names resolve, `--manifest` adds measured art, and `--copy-images` copies every page PNG into `--out` so the directory is self-contained, with `skeleton.images` pointing at it so the editor's import finds the parts |
+| `build … --pack` | the same build with every part arranged onto **shared** atlas pages, written into `--out` — losslessly, and gated a second time as the pair that ships. `--page-size`, `--padding`, `--page-edges` and `--pack-shape` tune it — `--pack-shape polygon` lets a neighbour sit inside a mesh's rectangle where its hull is not, and with `--page-edges free` costs 12–56 times `rect`'s pack (3–11 s against 0.2–0.3 s on 90–144 parts over two to four pages; past 5 s from about 60 parts, a second or so below 45 on one page — AUTHORING §0.1) |
+| `build … --atlas-in <file.atlas>` | the same build with every part resolved to a **region of an existing pack** instead of a loose PNG; a name the atlas lacks, a size the spec disagrees with or a rectangle off its page is refused by name |
+| `validate <dir>` | re-gates artifacts already on disk |
+| `repack <dir> --out <dir>` | a packed build **repacked from its own output** — `skeleton.json`, `skeleton.atlas` and the pages, with no parts kept — under the packing flags `build --pack` takes, so a packer improvement reaches a build whose parts are gone. Every region is lifted off its page, the skeleton read back with `ingest`, and `build --pack` run over the lifted parts with the same gate; it writes only after every region is shown pixel-identical to the input's, the skeleton byte-identical and the gate green, and refuses by name an atlas it cannot lift exactly. A skeleton the rebuild does not reproduce byte for byte — a build written before 2.2.0, whose header box was its stage — is refused naming every differing path, and written, every path printed, only under `--accept-skeleton-differences`. `--stage-box <slot>` reads the stage from the box a build carries for it (`skeleton.stageBox`), the one way the three files alone carry the stage exactly ([AUTHORING §0.4](../docs/AUTHORING.md)) |
+| `repack <dir> --out <dir> --keep-pages` | **`skeleton.model.json` alone, for the pages already in place** — for a player that reads the document beside an atlas and pages that already shipped. The same read and stage rules, then `build --atlas-in` over the input atlas in place of the lift and the pack; it writes the document, and nothing else, only after its `pages` are shown to state the atlas as it stands, the rebuilt skeleton byte-identical to the one on disk (so `spine.sha256` names it — no acceptance flag here) and the gate green. `--out` is usually the build's own directory and must not already hold a `skeleton.model.json`; a page or region line the document has no field for is refused by name ([AUTHORING §0.4](../docs/AUTHORING.md)) |
+| `ingest <skeleton.json> --out <dir>` | `build` run backwards: reads a Spine 4.3 skeleton and writes the rig spec and motion spec that **rebuild it**, plus a findings report naming everything it could not carry. a skeleton that declares no stage is carried as declaring none, `--stage x,y,w,h` adds a box to one — and is refused, rather than ignored, beside one that declares a box — and `--images <dir>` writes the spec's own images directory — the opposite direction from `build --images`, which overrides it — so the rebuild carries no flag at all |
+| `split --rig … --motion … --slot <name> --out <dir>` | the answer to a mesh refused because its triangles are **several pieces that share no vertex** — two legs after the triangles bridging them were deleted. It reads the two specs and writes them back into an absent or empty `--out` with one mesh per piece: piece 1 stays in the slot, piece k gets a new slot `<slot>_<k>` after it, each with the original's uvs and weights unchanged, its triangles renumbered outline first where the hull rule needs it, and every deform key re-sliced to the new indices — plus `split.json`, where every original vertex and triangle went. One piece is said so and nothing is written; what it cannot carry is refused by name ([AUTHORING §3.4.11](../docs/AUTHORING.md)) |
+| `explain --rig … --motion …` | the compiled rig as a table — every bone with its resolved parent, the slots in draw order, every timeline key by key. Writes nothing. What to reach for when a rig compiles and still looks wrong |
+| `render --candidate <dir>` | PNG frames plus a contact sheet, in `render/`, one directory per set: `<anim>@<fps>fps/` rather than `<anim>/` at any rate but the default — `--fps 24` writes `<anim>@24fps/`, and the default 12 writes `<anim>/`. `--hide <slot,…>` or `--slot <slot,…>` draws part of the rig on the **same grid** as the whole, so the two frames overlay and the difference is the part; `frames.json` records the subset and `check` refuses such a set as a reference. `--geometry` adds a `geometry.json` per set: every frame's bone world transforms and skinned attachment vertices, with the rest geometry, on the frames' own grid. `--folds` adds a `folds.json` per set and prints one line per mesh with a triangle turned over against the setup pose: the frames, the worst frame's count and which triangles, their world box and their setup-pose area. `--pass-through <cloth>:<leg>` adds a `pass-through.json` per set and prints the frames where a cloth drawn over a leg has its side inside the leg's drawn outline, with the depth and the world box — a reading, not a gate. `--seam <slot>:<slot>` adds a `seam.json` per set and prints, per pair, the frames where two slots that meet open background inside the joint (a gap) or show the overlap band of one past the other (a ghost), with the worst frame's cell count and world box; `ghostA` and `ghostB` partition the same ghost by which named pair member drew it, each with its own frames, spans and worst; `gapOpen` and `gapCovered` partition `gap` by zero versus positive rendered alpha from the whole skeleton, including faint and clipped drawings ([AUTHORING §8.8](../docs/AUTHORING.md#88-where-two-slots-stop-meeting--render---seam)) — a reading, not a gate; the exit status never moves. `--overlaps` adds an `overlaps.json` per set and prints one `OVERLAP "<under>" under "<over>"` line per pair of slots where the one drawn later covers the earlier one and the motion moves it — the frames, and the most pixels covered and the frame of them — with an outline plate per covered frame; the render reports what was drawn, and the draw-order key is the author's remedy — a reading, not a gate. `--extremes` adds `extremes.json` and a native six-panel `extremes.png` (setup, geometry-pair min/max and three premultiplied RGBA diffs with a legend), plus one `EXTREMES` line per set. Per-channel minima/maxima and the farthest original-vertex geometry pair are distinct readings; valid channel extrema survive a geometry/image SKIP, with channel refusals reported separately; still or uncomparable geometry reports a named SKIP without changing render exit status. `--extremes-only` writes the same `extremes.json` and readable `extremes.png` bytes while skipping ordinary frame rasterization/encoding, `contact.png` and `frames.json`; it implies `--extremes` and takes no other diagnostic or sheet output flags. Look at min, max and diff before a person does ([AUTHORING §8.11](../docs/AUTHORING.md#811-min-max-and-diff-before-a-person-looks--render---extremes)). `--angle-range <bone>:<relative-to>` prints how far one bone turns against another over each set: the lowest and highest angle and the frames they fall on — a reading, not a gate. `--viewport <x,y,w,h>` or `--viewport-from <frames.json>` draws over a given box instead of a fitted one, so two builds land on one pixel grid; a slot that reaches past it is named by set and frame, and `frames.json` records it. `--environment <schedule.json>` draws the rig under the wind and gravity its physics answers, in time — the same frames on the core and on spine-core; an inspection of the response the rig states, not a scene. `--sheet [--sheet-format json-hash] [--page-edges pot\|free]` also packs each set's straight-alpha transparent frames into `sheet.png` + `sheet.json` (TexturePacker JSON Hash with a shared world-origin `anchor` and `2`-px clamped edge extrusion, verified through `pixi.js@8.22.0` and `phaser@3.90.0` by `tools/sheet_readers.ts`) and `sheet-manifest.json` (`rigc-sheet/1`), leaving diagnostic `f####.png` and `contact.png` unchanged ([AUTHORING §8.10](../docs/AUTHORING.md#810-sprite-sheets-from-a-render--render---sheet)) — a self-contained sprite object per animation set; when animations play and how a scene is composed remains the consumer's |
+| `preview --candidate <dir>` | one self-contained `.html` that plays it, headed by the line `validate <dir>` prints for it and the rigc version — a refused candidate is still previewed, and its header says so in the gate's words. Repeat `--candidate` for one page with a pane per candidate, in the order given; a green `build` ends by naming this command for its own `--out` |
+| `vote --candidate a --candidate b` | one `.html` that asks a human which; `vote --record <file>` checks the answer into `votes.jsonl` |
+| `pose --images <dir> --frame <png>` | reads part placements **out of** a picture |
+| `chainfit --candidate <dir> --images <dir> --frame <png>` | reads the parts `pose` refuses, through the candidate's own draw order and hierarchy: masked residuals over **visible** pixels, one hinge per child instead of four degrees of freedom, and the `rotate` key value each answer implies. A bone with two or more anchored descendants is **determined** rather than searched, and the residual that over-determination leaves is reported |
+| `diff <candidate.json> <reference.json>` | structural comparison of two skeletons, one ratio per measure and deliberately no combined score |
+| `bonedist --candidate … --reference … --bones …` | per-frame, per-bone world-transform distance against another skeleton — the ladder's stage 3, run on its own. `--bones <correspondence.json \| identity>` is required rather than defaulted: a candidate is entitled to its own bone names, so the pairing is stated |
+| `check --candidate <dir> --frames <dir> [--out <dir>]` | the candidate against reference pictures — the only instrument here that can see a *wrong animation*. `--out` also writes, for every frame the table lists, the picture its figures came from: reference, candidate, difference and overlay at native size |
+| `bench <rung> --candidate <dir>` | one rung of the benchmark ladder |
+| `guide <RULE>` / `guide §<n>[.<m>[.<k>]] [--all]` | the guide's row for the rule a failure line names — every `FAIL` line, `vote --record` refusal, `ingest` finding and coded compile error ends with ` (see rigc guide <RULE>)`; only legacy uncoded library errors point at `§5.1` — or a section's heading, own prose and subsection index, read from the installed `docs/AUTHORING.md` when it runs. `--all` includes the subsection bodies; a leaf prints its full text either way. Sizes describe full ledger spans. `--all` with a rule is refused, exit 2; an unknown name is refused with the nearest real ones, exit 1 |
+| `skills install [--dir …] [--copy]` | links every agent skill the package ships into `.agents/skills` (or `--dir`) as relative symlinks, or copies them with `--copy` — where Codex, Gemini CLI and Antigravity look. A second run has nothing to do; an entry already there that is not this command's is refused by name and nothing is written |
+| `review <dir> […]` | the human review of a build, handed to the `rig-review` bin of `@rig-c/review` installed beside the package; rigc does not depend on it and never installs it. `rigc review <dir> [--reference <video>] [--animation <name>] [--compare <dir>]` is `rig-review open <dir> …` with those flags 1:1 and prints the loopback URL to give a person; a first argument that is one of review's own words (`open`, `check`, `feedback`, `control`, `strip`, `compare`) or starts with `-` (`--help`, `--`) is handed over untouched. stdout is review's byte for byte, stderr review's plus the launcher's own refusals, the exit code review's. Refused by name, exit 2, before the bin starts: `REVIEW_OUTPUT_MISSING <path>` (the target is not a directory); `REVIEW_NOT_INSTALLED` with two lines, `bun add -d @rig-c/review` and `bunx @rig-c/review open <dir> …` carrying the flags given — the same on a terminal and off, with nothing installed or written; `REVIEW_BUN_TOO_OLD: Bun <found>, @rig-c/review needs <required>`, the floor read off the installed package's `engines.bun`; and an empty argument (`""`) under a Bun that drops one (Bun 1.2.0, measured by a probe), `rigc review: argument N is empty, and Bun <version>, the Bun running this, drops an empty argument when it starts a process — …`. docs/AUTHORING.md lists every line |
+
+`diff`, `bonedist`, `check` and `bench` measure against something you were given; the
+first three work on any reference you have, and `bench` is a repository workflow that needs a clone
+and `bun run fetch-examples`. The reasoning behind them is in
+[the benchmark dossier](https://github.com/rig-c/core/blob/main/docs/BENCHMARK.md).
+
+`build` and `validate` both default to `--profile spine` — the 36 validity rules, which
+ask *is this valid Spine 4.3 that any runtime plays correctly?* `--profile rig-play`
+adds all 50: the other 14 are one renderer's policy and one canvas budget's, and they
+fire on perfectly correct editor-produced Spine data, which is why they are opt-in.
+⇒ **That reason is about foreign data and does not carry to a rig you are authoring
+yourself: author under `--profile rig-play` and read the extra 14 as findings, and
+gate the release under `--profile spine`.** A `deform` key that folds a mesh inside
+out is written out under the default and refused by name under `rig-play`, which
+is the shape of what that split buys you. A report always names
+the profile it ran and lists what that profile left out.
+
+Several cuts can also be registered in a `cuts.json` and built by name
+(`build --cut my_cut --cuts path/to/cuts.json`); every path in that table resolves
+relative to the `cuts.json` file itself, so the table lives with the project that owns
+the art. Its shape is under
+[Usage](https://github.com/rig-c/core/blob/main/docs/BENCHMARK.md#usage).
+
+**`render`** samples every animation at 12 fps and writes `render/<animation>/f0000.png…`
+with a `contact.png` beside them — every frame of the shot as one labelled grid,
+which is the picture to open first, because spacing is a comparison *across*
+frames. It draws with rigc's own rasteriser (the one `check` measures with), so
+it needs no browser and no network, and the `frames.json` it leaves beside the
+directories makes the result a frame set like any other — the world box every
+frame is a picture of. `--animation <name>` narrows it to one, `--fps` and
+`--max` change the rate and the frame size. A set drawn at any rate but the
+default is written to `<anim>@<fps>fps/` rather than `<anim>/`, so two rates sit
+side by side: `--fps 24` writes `<anim>@24fps/`, and the default 12 writes
+`<anim>/`. Each set's summary line ends with the directory it wrote.
+
+> 🚨 **`--skin <name>` if your rig has more than one.** With no `--skin` no skin
+> is set at all, so every slot resolves through the **default** skin alone — and
+> a slot whose art lives only in a named skin draws *nothing*. That is not a
+> quirk of `render`: `check` compares `render`'s frames, so a multi-skin rig
+> checked with no skin compares blank against blank and reports a perfect
+> `0.0000` about art nobody drew. `render --skin` records the name in
+> `frames.json`, `check --skin` poses the candidate under it, and a candidate
+> scored against frames rendered under a *different* skin is refused by name
+> rather than measured.
+
+**`preview`** writes a single self-contained `.html`: your skeleton, your atlas
+and every page's PNG bytes are embedded in it as data URIs, and it plays them in
+the **official [Spine Web Player](https://esotericsoftware.com/spine-player)**.
+Double-click it, or attach it to a message — the file carries the whole artifact.
+It is also the strongest interop statement in this repository: a rig that plays
+there has been played by Esoteric Software's own runtime rather than by ours.
+
+> ⚖️ The player itself is **referenced, not embedded** — the page loads it from
+> unpkg, so the first open needs a network, and rigc redistributes nothing
+> Esoteric Software owns (see [NOTICE.md](../NOTICE.md)). Everything the player
+> draws is inside your file.
+
+Further repository material:
+
+| Document | For |
+| --- | --- |
+| 🔬 [SURVEY_2026-08-22.md](https://github.com/rig-c/core/blob/main/docs/SURVEY_2026-08-22.md) | the survey the ladder was climbed by: rigc and the official examples as measured on 2026-08-22, and the gap list ordered by rung. A dated record, not kept current. Repository material |
+
 ```bash
 bun install                                   # once
 
@@ -286,6 +377,7 @@ What the flags mean:
 | `--max` | `render` and `inspect`: the longest side of the frame in pixels (default `256`, finite and at least `16`). On `render`, refused with `--viewport-from`, which already fixes the pixel size — **§8.6**, **§13** |
 | `--show`, `--dim`, `--at`, `--zoom` | `inspect` only — what it draws, whether the art is faded, which times of `--animation` it poses and the bone, slot or folds it frames to; §13 says each, with the refusals |
 | `--geometry` | `render` only: also write a `geometry.json` into each frame directory — per frame, every bone's world transform and every slot's region or mesh vertices in world units after skinning, plus each attachment's rest geometry and topology, on the frames' own grid and viewport. Every other file is byte for byte what the render writes without it. Refused with `--slot`/`--hide`, because the geometry is the whole pose whatever is drawn — **§8.2** |
+| `--extremes-only` | `render` only: imply `--extremes`, but write only `extremes.json` and readable `extremes.png` with the same bytes. Pose the same grid; rasterize only the setup/min/max pictures used by the plate. No ordinary frame PNGs, contact sheet or `frames.json`. Takes no `--sheet`, `--sheet-format`, `--page-edges`, `--geometry`, `--folds`, `--pass-through`, `--seam`, `--overlaps` or `--angle-range`; drop the named flag or use `--extremes` instead — **§8.11** |
 | `--extremes` | `render` only: add `extremes.json` and an `EXTREMES` line per set; a moving set with comparable geometry and readable images also gets a native six-panel `extremes.png`: setup, geometry-pair min/max and three premultiplied RGBA diffs with a legend. Per-channel extrema are independent of that geometry pair; valid channels survive geometry/image SKIPs, and channel refusals are named separately. Still or uncomparable geometry is a named SKIP, with no invented pair or PNG; observation failures do not change a successful render's exit status. Supports `--slot`/`--hide` on both posers, on the whole rig's viewport. Without the flag, no extremes observations are added — **§8.11** |
 | `--folds` | `render` only: also read which mesh triangles **fold** — turn over against the setup pose — and write a `folds.json` into each frame directory: per mesh, the frames with a folded triangle, the worst frame's count and which triangles, by index, with their world box and setup-pose area. One printed line per mesh that folds; a triangle degenerate or inverted at the setup pose is said once and never counted. A reading, not a gate. Every other file is byte for byte what the render writes without it, `geometry.json` included. Refused with `--slot`/`--hide`, for `--geometry`'s reason — **§8.3** |
 | `--pass-through` | `render` only: `<cloth>:<leg>[,<cloth>:<leg>…]` — also read where each cloth slot **passes through** its leg slot, and write a `pass-through.json` into each frame directory: the frames where the cloth draws over the leg and its drawn side lies inside the leg's drawn outline by 2 steps or more, each with the depth and the world box. One printed line per pair, and one per frame that passes through. The first name must draw over the second for a frame to be read — the declared order, never both. A reading, not a gate. Every other file is byte for byte what the render writes without it. An unknown slot, a slot that draws on no frame, a malformed list and a pair named twice are refused by name, and so is `--slot`/`--hide` beside it — **§8.5** |
@@ -9478,6 +9570,25 @@ bounds plus its `2`-px border on each side exceed `2048` (`w + 4 > 2048` or
 bun cli.ts render --candidate path/to/build --extremes [--animation turn] [--fps 12] [--max 256]
 ```
 
+Use `--extremes-only` instead when only those observations are needed:
+
+```sh
+bun cli.ts render --candidate path/to/build --extremes-only --out extremes/
+```
+
+It implies `--extremes` and writes the same `extremes.json` and readable
+`extremes.png` bytes, sampling the same poses and fitting the same viewport.
+Only the setup/min/max pictures needed by the plate are rasterized; ordinary
+frame PNGs, the contact sheet and `frames.json` are not produced. A still or
+refused set writes its JSON SKIP with no PNG. Skin, subset, environment, fps,
+animation and viewport options keep their meanings. Other diagnostic and sheet
+output flags listed in the `--extremes-only` row above are refused together
+rather than silently ignored. Use `--extremes` when those outputs are needed.
+Selected set directories are replaced just as in an ordinary render; a prior
+root `frames.json` is removed because it would advertise frames no longer there.
+Unselected set directories are left alone. Use a dedicated output root when
+retaining an ordinary render beside these observations.
+
 Look at **min · max · diff before a person does**. A baked line carried by a
 moving part can be obvious in the difference image while a seam metric misses
 it. This flag makes the picture; it does not classify tears or ghosts and does

package/docs/FACE.md

@@ -1947,7 +1947,9 @@ turning, blinking and looking — and the one general lesson that might carry in
 that work is §7's: **allocate the channels before the first key, because Spine
 blends and does not add.**
 
-### A measured alpha aperture
+<a id="a-measured-alpha-aperture"></a>
+
+### Depth-driven rigging: a measured alpha aperture
 
 A named socket plate can supply an `alphaClip` clipping attachment (AUTHORING,
 **Alpha-derived clipping**). This also accepts a generated grid/contour source

package/docs/INGEST.md

@@ -20,7 +20,7 @@ reproduces* — so deliberately extending or renaming a foreign skeleton **lower
 them**, by design (§4.2, §4.3). Neither one has a pass bar, and this page does not
 invent one.
 
-- Formats and the CLI reference: [README.md](../README.md)
+- Formats and the CLI reference: [AUTHORING §0](AUTHORING.md#0-the-loop)
 - The rig spec, field by field: **AUTHORING §3**, and [`src/rig.ts`](../src/rig.ts)
 - The motion spec, field by field: **AUTHORING §4**
 - Named failures, and the file each one points at: **AUTHORING §5–§6**
@@ -1490,3 +1490,142 @@ The transcription these recipes start from is
 unmodified. The re-pivoted, renamed and extended variants in §4 were built from copies
 of it; none is committed, because each is an illustration of an edit rather than a
 transcription of anything.
+
+### Starting from a skeleton you already have
+
+`rigc ingest` reads a Spine 4.3 `skeleton.json` and writes the two spec files that
+rebuild it. It is the only command that runs against `build`'s direction, and the
+only one whose contract is an equality rather than a rulebook:
+
+```bash
+rigc ingest hero.json --out specs/ --images parts/
+rigc build --rig specs/rig.json --motion specs/motion.json --out build/
+rigc diff build/skeleton.json hero.json
+```
+
+`--images parts/` is what makes the second line carry no flag: it writes the spec's
+own `images` directory, spelled from `--out`, so the specs are self-contained from
+there on. Leave it off and the `image` names resolve against `specs/` itself, which
+holds no art — every rebuild then has to repeat `build --images parts/`.
+
+**`build(ingest(x))` is `x`.** Over the eleven rigs this repository builds — the seven
+gallery examples, the three generated probes and a coverage probe written for the
+purpose — the rebuilt `skeleton.json` is byte for byte the file the decompiler read.
+The atlas is held to a weaker
+claim on purpose, and the weakening is measured rather than assumed: it comes back
+equal as a **multiset of region blocks**, because the order the pages are collected in
+is in no field of the skeleton.
+
+**And over twelve skeletons nobody here wrote.** Every editor export in the fetched
+example corpus, ingested, rebuilt through the pack beside it and `diff`ed against the
+source, comes back **12 of 12, no blockers, 1.000 on every measure the report
+carries** — and each rebuild is its export's own text in canonical form, apart from
+the header's `hash` and `spine`: the editor's project hash and the runtime version
+rigc stamps, the two keys the rig spec has no field for by design (12 of 12) — and
+the header's box, which `build` computes rather than carries (issue #907): the rebuild
+writes spine-core's `getBounds` over the export on the header's 1e-6 grid at float32, equal on all twelve,
+where the editor wrote its own arithmetic, up to 0.0071 units away.
+[INGEST.md §2.3](../docs/INGEST.md) states that pass line and why those two are the
+exceptions.
+
+**What it reads is skeleton JSON and nothing else** — no `.spine` project, no binary
+`.skel`, no atlas, no art. So it never invents, and the things it cannot get out of
+the file are **findings** with codes rather than plausible values: a construct the
+spec format cannot hold (`point`, a `sequence` block, an unknown field
+on a bone, slot or constraint) is a blocker, the command exits non-zero, and both
+specs are still written — a spec plus a list of what is missing from it beats no spec.
+
+⚠️ **Two values are not in a skeleton at all.**
+
+- **The stage.** `skeleton.width`/`height`. A skeleton that declares none is carried as
+  declaring none — the rig spec states `"width": null, "height": null` and the rebuild
+  carries no box either, byte for byte — and `--stage x,y,w,h` is how a
+  caller *adds* one, recorded as a judgement. It is not derivable — posing the rig gives
+  the *animated* extent, which is a different number from the setup box. ⛔ **And `--stage` beside a box the file already states is refused
+  too**, for the opposite reason: two sources for one value, where the file is the record
+  of what was measured. **All twelve exports in the example corpus carry a stage** and
+  none of them needs the flag. It is the value that costs least to get wrong, because
+  `diff` reports the box and gates nothing on it. 🔁 The box an export's header carries
+  is its setup-pose bounding box, and it becomes the rebuild's *stage*; the rebuild's own
+  header is computed again, because since issue #907 `build` writes the setup-pose
+  bounding box there — never the stage — held to spine-core's `getBounds`. 📦 A rig
+  that has to carry its stage in the Spine files asks for it as a bounding box
+  (`skeleton.stageBox`, written by `build` from the stage and held by
+  `A50_STAGE_BOX_IS_THE_STAGE`), and `ingest --stage-box <slot>` reads that box back as
+  the rebuild's stage — [AUTHORING §3.1](../docs/AUTHORING.md) has the field and the
+  paragraph for a consumer of the files.
+- **An animation's duration.** The format has no such field. The largest key time is
+  the only derivable answer and it is what a runtime plays to; it is wrong for an
+  animation that holds its last pose past its last key, so it is recorded as a finding
+  on every animation rather than chosen quietly.
+
+Both specs carry a `note` that `ingest` writes itself, saying the file is decompiled
+and naming the skeleton it came from — because a decompiled spec is indistinguishable
+from an authored one by inspection, every gate here calls it green (it *is* green),
+and no gate can catch a missing note.
+
+[docs/INGEST.md](../docs/INGEST.md) is the whole page on working from a file you were
+handed; [docs/AUTHORING.md](../docs/AUTHORING.md) §0.3 is the loop.
+
+### The editor round trip — for a licence holder, never in CI
+
+`tools/editor_roundtrip.ts` drives the loop the output's whole premise rests on:
+build → **import into the Spine editor** → export back to JSON → gate, `diff`,
+`render` and `check` the export against the build it came from.
+
+```
+bun cli.ts build --rig … --motion … --out build/ --copy-images
+bun tools/editor_roundtrip.ts --build build/ --editor /Applications/Spine.app/Contents/MacOS/Spine
+```
+
+Of the editor's `--version` it records one line, the `Spine <x.y.z> …` line that
+carries the version, and nothing else that command prints — the rest of it
+names the licence holder — or `editor version: not found in --version output`
+where no such line is there. That call carries the same `-u` as the import and
+the export, so a trip pinned with `--editor-version <v>` names the editor it
+pinned and says so on the line (`(read from --version under -u <v>, …)`); an
+unpinned trip names the launcher's default. Once the export exists the version
+is held against the export's own `skeleton.spine`, and a disagreement is a FAIL
+naming both values — the line would otherwise name an editor the trip did not
+run on. It prints the import and export exit codes, the
+validator's verdict on the export, every `diff` measure that moved, `check`'s mean MAE and worst drift per
+animation **for each skin the build and the export both declare** — one
+render-and-check block per skin, with a per-skin roll-up under them, because a
+rig's contested art lives in its named skins and a single un-skinned check draws
+none of it; a skin only one side declares is a FAIL naming it as **lost** (or
+**added**) **by the export**, with `diff`'s `attachments.skins` beside it, and is
+rendered on neither side — and a
+field-by-field list of what the editor rewrote. Every step quotes what its child
+said when that child did not do what it was for, the renderers included — the
+editor's words in full and in order, except its `Licensed to:` line, which names
+the licence holder and is replaced by a line saying it was withheld; a skin
+**neither** side can draw — a hit-box rig, say — is a **SKIP** naming that, not a
+red, because `check` had nothing to compare and `diff` and `validate` have
+already measured the rig. One side drawing where the other does not is the
+divergence the trip exists to find and stays a failure. A human edit made in the
+editor survives the trip back.
+
+🔒 **It requires a licensed Spine editor on the machine, by construction**, and
+drives only the [documented command line](https://esotericsoftware.com/spine-command-line-interface)
+— never the UI, and it produces nothing the editor did not produce. With no
+editor present it refuses by name and exits non-zero, and so does the **trial**:
+the trial cannot save projects or export animation data, so the refusal names
+what it found — the executable, the bundle, the `CFBundleName` that bundle
+declares, or the banner the binary prints about itself — rather than starting it
+and failing downstream. Both refusals point at `--exported <file>`, which
+measures an export the editor already made and is the half of this tool that
+needs no editor at all. A build whose `skeleton.json` is missing, is not JSON, or
+holds JSON that is not one object is refused by name before the editor starts,
+and so is a build with no atlas or an atlas that is a directory, or an
+`--exported` file that is not one JSON object.
+
+⛔ **Run the round trip by hand, on a machine that has the editor.** CI has no
+editor, so no automated check runs it. The
+[pre-landing fixture policy](https://github.com/rig-c/core/blob/main/CLAUDE.md#the-selftest-and-its-fixtures)
+is the canonical explanation of which rigs the by-hand measurement covers and why.
+
+⚠️ Build with `--copy-images`. An ordinary build's atlas names its pages by a
+relative path back to the art directory, and the round trip copies that atlas to
+a directory at another depth — the tool refuses such a build by name rather than
+letting `A17` blame the editor for the harness's own doing.
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rig-c/core",
-  "version": "2.81.1",
+  "version": "2.82.1",
   "description": "AI-authored 2D rigging and animation, verified before it is written. rigc compiles a rig spec into skeleton data in the Spine 4.3 format, gates it with named assertions held to a spine-core round trip's verdicts, and emits nothing that fails. Ships as an agent skill.",
   "type": "module",
   "bin": {

package/skills/rigc/SKILL.md

@@ -148,5 +148,7 @@ spec files field by field, the emission rules, the loop, and the failure map. Th
 Every guide linked here is in the installed package at `node_modules/@rig-c/core/docs/`,
 which is the copy that matches the rigc you run; the links go to the repository's
 `main`. Inside the Claude Code plugin the same files are at `${CLAUDE_PLUGIN_ROOT}/docs/`.
-Formats, the CLI reference and the licence chain:
-[README.md](https://github.com/rig-c/core/blob/main/README.md), installed at `node_modules/@rig-c/core/README.md`.
+Formats and the CLI reference: [AUTHORING §0](https://github.com/rig-c/core/blob/main/docs/AUTHORING.md#0-the-loop),
+installed at `node_modules/@rig-c/core/docs/AUTHORING.md`;
+existing skeletons: [INGEST](https://github.com/rig-c/core/blob/main/docs/INGEST.md);
+licensing: [NOTICE](https://github.com/rig-c/core/blob/main/NOTICE.md).

package/src/cli/core_commands.ts

@@ -658,6 +658,14 @@ export function cmdRender(flags: Record<string, string>): void {
   const maxSide = readPositiveNumber(flags, 'max', 256, 16);
   // A box given rather than fitted (issue #1414), read before a line is printed, so a malformed one is refused first.
   const given = readGivenViewport(flags);
+  const extremesOnly = flags['extremes-only'] !== undefined;
+  if (extremesOnly) {
+    for (const flag of ['sheet', 'sheet-format', 'page-edges', 'geometry', 'folds', 'pass-through', 'seam', 'overlaps', 'angle-range']) {
+      if (flags[flag] !== undefined) {
+        throw new UsageError(`--extremes-only takes no --${flag}: it writes only extremes.json and, when readable, extremes.png. Drop --${flag}, or use --extremes for ordinary frames and additional outputs`);
+      }
+    }
+  }
   const wantsSheet = flags.sheet !== undefined;
   if (flags['sheet-format'] !== undefined && !wantsSheet) {
     throw new UsageError('--sheet-format takes --sheet: pass --sheet alongside --sheet-format <format>, or drop --sheet-format');
@@ -672,7 +680,7 @@ export function cmdRender(flags: Record<string, string>): void {
   const sheetPageEdges = wantsSheet ? readPageEdges(flags) : undefined;
   const outRoot = resolve(flags.out ?? 'render');
   const geometry = flags.geometry !== undefined;
-  const extremes = flags.extremes !== undefined;
+  const extremes = extremesOnly || flags.extremes !== undefined;
   // The fold reading (issue #1383) is its own flag rather than a part of --geometry, so a caller that asked for
   // neither, or for --geometry alone, gets the bytes it always got: geometry.json is the pose, and a reading derived
   // from it is a second file beside it, written only when asked for.
@@ -1063,6 +1071,22 @@ export function cmdRender(flags: Record<string, string>): void {
   }
 
   mkdirSync(outRoot, { recursive: true });
+  if (extremesOnly) {
+    // Reuse the same posed grid and plates; selecting extremes needs no ordinary pixels.
+    // Clear only the selected sets, just as the ordinary render does. No frames.json
+    // is written: this output is an observation, not a frame set consumable by check.
+    for (const [name, extreme] of extremeReadings) {
+      const dir = join(outRoot, frameSetDir(name, fps));
+      if (existsSync(dir)) rmSync(dir, { recursive: true });
+      mkdirSync(dir, { recursive: true });
+      writeFileSync(join(dir, 'extremes.json'), extremesText(extreme.reading));
+      if (extreme.plate !== null) extreme.plate.writePng(join(dir, 'extremes.png'));
+      console.log(`  ..    ${extremesLine(extreme.reading)}`);
+    }
+    // A prior ordinary render's index would falsely advertise now-removed frames.
+    rmSync(join(outRoot, FRAMES_SIDECAR), { force: true });
+    return;
+  }
   const sets: FrameSet[] = [];
   // A mesh's setup faults are a property of the mesh, not of an animation: said once, the first time a set shows it.
   const faultsSaid = new Set<string>();

package/src/cli/shared.ts

@@ -152,7 +152,7 @@ export { PACKAGE_ROOT, readPackageMeta, readVersion };
  * needs a value` (issue #328). `CLI10`/`CLI11` in `selftest.ts` now hold the two
  * halves together by reading `--help` rather than by naming a flag.
  */
-const BOOLEAN_FLAGS = new Set(['all', 'all-frames', 'all-bones', 'help', 'copy-images', 'again', 'pack', 'copy', 'geometry', 'folds', 'extremes', 'overlaps', 'sheet', 'accept-skeleton-differences', 'keep-pages', 'dim']);
+const BOOLEAN_FLAGS = new Set(['all', 'all-frames', 'all-bones', 'help', 'copy-images', 'again', 'pack', 'copy', 'geometry', 'folds', 'extremes', 'extremes-only', 'overlaps', 'sheet', 'accept-skeleton-differences', 'keep-pages', 'dim']);
 
 /**
  * The flags a command is allowed to spell more than once.
@@ -1066,6 +1066,7 @@ const FLAG_MEANINGS: Record<string, string> = {
     'Each frame with a moving pair also gets an outline plate, overlaps-f<NNNN>.png: every slot in a moving pair as its contour in its own ' +
     'colour, dashed where a slot drawn later covers it, named at its top. The render reports what was drawn; who should be in front is the ' +
     "author's, and the draw-order key in the motion spec is the remedy. A reading, not a gate. Not with --slot/--hide",
+  'extremes-only': 'write only extremes.json and readable extremes.png per set, with the same posed grid and bytes as --extremes; no ordinary frame PNGs, contact.png or frames.json. Implies --extremes; takes no --sheet, --sheet-format, --page-edges, --geometry, --folds, --pass-through, --seam, --overlaps or --angle-range',
   extremes: 'also write extremes.json and a native six-panel extremes.png per set: setup, geometry-pair min/max and premultiplied RGBA diffs, with a legend. Per-channel extrema are recorded separately and valid channels survive geometry/image SKIPs; channel refusals are named separately. Still geometry reports SKIP; a reading, not a gate. Attachment identity/count changes record a named SKIP without changing render exit; supports --slot/--hide on both posers',
   seam:
     `also read, for each <slot>:<slot> pair, where the two drawings stop meeting, and write ${SEAM_FILE} into each frame directory: ` +
@@ -1757,7 +1758,7 @@ export const COMMANDS: CommandDoc[] = [
     runtime: false,
     spineFormat: false,
     usage: [
-      'rigc render --candidate <dir | skeleton.json> [--animation <name>] [--skin <name>] [--fps 12] [--max 256] [--geometry] [--folds] [--extremes] [--poser core|spine] [--out render/]',
+      'rigc render --candidate <dir | skeleton.json> [--animation <name>] [--skin <name>] [--fps 12] [--max 256] [--geometry] [--folds] [--extremes | --extremes-only] [--poser core|spine] [--out render/]',
       'rigc render … --slot <name[,name…]> | --hide <name[,name…]>   (a subset of the slots, on the whole rig\'s grid)',
       'rigc render … --environment <schedule.json>   (the wind and gravity the physics answers, in time)',
       'rigc render … --pass-through <cloth>:<leg>[,…]   (the frames where a cloth drawn over a leg passes through it)',
@@ -1767,7 +1768,7 @@ export const COMMANDS: CommandDoc[] = [
       'rigc render … --viewport <x,y,w,h> | --viewport-from <frames.json>   (a box given, not fitted: two renders on one pixel grid)',
       'rigc render … --sheet [--sheet-format json-hash] [--page-edges pot|free]   (deterministic sprite sheets + JSON hash table + sheet-manifest.json per set)',
     ],
-    flags: ['candidate', 'atlas', 'animation', 'skin', 'slot', 'hide', 'fps', 'max', 'viewport', 'viewport-from', 'geometry', 'folds', 'extremes', 'pass-through', 'seam', 'overlaps', 'angle-range', 'sheet', 'sheet-format', 'page-edges', 'environment', 'poser', 'out'],
+    flags: ['candidate', 'atlas', 'animation', 'skin', 'slot', 'hide', 'fps', 'max', 'viewport', 'viewport-from', 'geometry', 'folds', 'extremes', 'extremes-only', 'pass-through', 'seam', 'overlaps', 'angle-range', 'sheet', 'sheet-format', 'page-edges', 'environment', 'poser', 'out'],
     overrides: {
       'page-edges': {
         meaning: