spine-rigc 1.0.2 → 1.2.0

package/docs/AUTHORING.md

@@ -123,6 +123,8 @@ bun cli.ts check \
 # …and if nobody gave you frames, LOOK at it instead — neither needs a reference:
 bun cli.ts render  --candidate path/to/spine    # PNG frames + a contact sheet grid
 bun cli.ts preview --candidate path/to/spine    # one .html that plays it in Spine's own player
+#   ↳ a green build ends by naming this command for its own --out; repeat
+#     --candidate for a pane per candidate on one page
 
 # …and where you have several green candidates and no instrument that separates
 # them, ask a human — the one loop step this toolchain cannot run for you:
@@ -141,6 +143,27 @@ the animation is the one in the frames, and there is no assertion that could —
 §9. The two run in that order because `check` needs artifacts on disk and `build`
 only writes them when the gate is green.
 
+🎞️ **When the source is a foreign player — a Live2D model, a Unity scene, a video —
+make the reference frames first, from the source.** rigc reads none of those
+formats and will not ([FACE.md](FACE.md#11-non-goals--stated-so-nobody-proposes-them-as-gaps)
+§11, the paragraph that opens *No Live2D file is read or written*); what it reads
+is the pictures they produce. Render the source at the rate you will check at into
+one directory of `f0000.png`, `f0001.png`… named after the candidate animation it
+shows (or pair the two with `--as`): `check` accepts a set with no `frames.json`
+and takes its rate from `--fps` (§9). What that set cannot carry is its
+**background**, which the sidecar would have recorded — so render it onto an
+**opaque** background of the colour `check`'s no-`frames.json` note names
+(`232, 232, 232, 255` in this release). The content box is found against that
+colour and alpha is not read: measured on the 24 frames of `gallery/look`'s `turn`,
+the same drawn pixels read MAE mean **2.25** over that grey, **5.19** over white and
+**20.37** over a transparent background, where the fit took the whole 234×256
+frame for the figure — all three at exit 0 with the same notes. A port with no
+reference frames is **unmeasured, not finished**: green from `build` says the file
+is valid and nothing about whether it is the source's picture. And the parts are
+the source's own texture cut along its drawables, **never a screenshot of it** — a
+screenshot is the composed result, so a part cut from it carries every part under
+it, which is what the first of the three questions under *LOOK* below finds.
+
 🚨 **Read `check`'s per-frame column before its MAE.** The table's headline figures
 are the MAE and the slot drift, and a reader who came for those will skip the
 `per-frame` line printed under them — but that line is the only thing in this
@@ -159,7 +182,7 @@ What the flags mean:
 | --- | --- |
 | `--rig` | the rig spec — skeleton structure |
 | `--motion` | the motion spec — time |
-| `--out` | directory for `skeleton.json` + `skeleton.atlas`; atlas page paths and `skeleton.images` are written relative to it |
+| `--out` | directory for `skeleton.json` + `skeleton.atlas`; atlas page paths and `skeleton.images` are written relative to it. On `check` it is a directory of **pictures** instead: one per frame the table lists (every compared frame under `--all-frames`), reference · candidate · difference · overlay at the comparison grid's native size, as `<dir>/<set>/f####.png` beside a `frames.json` that says what they are pictures of. Each `<dir>/<set>/` is cleared first; a file at `<dir>`, or a directory that is or holds `--frames`, is refused by name — **§9.2.1** |
 | `--copy-images` | `build` only: also copies every page **the emitted atlas names** into `--out` and rewrites the atlas to the copies, so the directory is self-contained enough to zip or commit on its own, and points `skeleton.images` at `--out` itself so the editor's import finds the parts beside the skeleton (§3.1 says why it is spelled `../<out>/` and not `./`). Under `--atlas-in` those pages are the pack's, not one per part (**§0.2**). Without it, page paths point at the source art |
 | `--pack` | `build` only: arrange every part onto **shared** atlas page(s), written into `--out` as real PNGs, instead of one page per part. Lossless — nothing is resampled, trimmed or rotated. The default is one page per part — **§0.1** |
 | `--page-size` | `build --pack` only: the largest page edge (default `2048`). A ceiling, not the size: page edges are powers of two and the one written is the smallest that holds the pack — **§0.1** |
@@ -170,8 +193,8 @@ What the flags mean:
 | `--cut` | `build`, `explain` and `validate`: look up a named cut in `--cuts <cuts.json>`, **instead of** `--rig`/`--motion`/`--out` — the two spellings are one build stated two ways and are refused together. A `cuts.json` is `{ "<name>": { "rig": …, "motion": …, "out": …, "manifest"?: … } }`, every path in it relative to the table's own file, so the table lives with the project that owns the art |
 | `--cuts` | the `cuts.json` `--cut` names. Required beside it — `--cut` alone is refused, with no guess at where the table lives |
 | `--profile` | `spine` = the 34 validity rules (**the default**) · `spine-html` = all 49, opt-in |
-| `--candidate` | `check`, `bench`, `render`, `preview`, `chainfit` and `vote` only: a **compiled** artifact — the directory `build --out` wrote, or a `skeleton.json` path. `--atlas <path>` names the atlas when it does not sit beside the skeleton. **`vote` is the one command that takes it more than once** — repeat it 2–4 times, one per pane, labelled A, B, C, D in the order given; everywhere else a repeat is a typo and is refused |
-| `--animation` | `render`, `preview` and `vote` only: which animation to show. The default is **every** one for `render`, the **first** for `preview`, and for `vote` the first of candidate A. A name the skeleton does not have is refused, with the ones it does have listed — and for `vote`, so is a name that only *some* candidates have |
+| `--candidate` | `check`, `bench`, `render`, `preview`, `chainfit` and `vote` only: a **compiled** artifact — the directory `build --out` wrote, or a `skeleton.json` path. `--atlas <path>` names the atlas when it does not sit beside the skeleton. **`vote` and `preview` take it more than once**: `vote` 2–4 times, one per pane, labelled A, B, C, D in the order given; `preview` any number of times, one pane per candidate in the order given, each headed by its path and its gate line, and the same skeleton twice (a directory and its `skeleton.json` are one) is refused by name. `--atlas` goes with one candidate only. Everywhere else a repeat is a typo and is refused |
+| `--animation` | `render`, `preview` and `vote` only: which animation to show. The default is **every** one for `render`, the **first** for `preview` (each candidate's own first, with several), and for `vote` the first of candidate A. A name the skeleton does not have is refused, with the ones it does have listed — and for `vote` and a several-candidate `preview`, so is a name that only *some* candidates have, naming the one that lacks it |
 | `--record` | `vote` only: a saved vote to check against its ballot and append to the ledger, instead of writing a ballot. This is the command's second mode; it takes no `--candidate` |
 | `--ballot` | `vote --record` only: the ballot the vote answers (default `ballot.html`). Its embedded manifest is what the vote is checked against, so the ballot file is the record of the question |
 | `--ledger` | `vote --record` only: the append-only JSONL the vote lands in (default `votes.jsonl`), one vote per line |
@@ -186,6 +209,8 @@ What the flags mean:
 | `--min-visible` | `chainfit` only: below this share of a part surviving the parts drawn over it, the placement is refused `occluded` instead of reported flat (default `0.25`) — §12.4 |
 | `--passes` | `chainfit` only: how many times the occluder masks are rebuilt from the answers and the fit rerun (default `2`) — §12.4 |
 | `--anchor-residual` | `chainfit` only: the residual a `pose` placement must be within to anchor a chain (default `0.16`) — §12.2 |
+| `--dir` | `skills install` only: the directory to install the agent skills into, resolved against your working directory (default `.agents/skills`, which Codex, Gemini CLI and Antigravity read). The skills are the `skills/` directory of the package the command runs from, never the working directory's |
+| `--copy` | `skills install` only: copy each skill folder instead of writing a relative symlink to it. A copy is not reached by an upgrade of the package; one that is no longer the package's bytes is refused on the next run, naming the first file that differs |
 
 `render` also takes `--fps <n>` (the rate it samples at, default 12 — the same
 protocol rate the reference frames use) and `--max <px>` (the long side of a
@@ -193,6 +218,26 @@ frame, default 256). Three commands take `--out`: a directory for `render`
 (default `render/`), the `.html` file for `preview` (default `preview.html`) and
 for `vote` (default `ballot.html`).
 
+`skills install` is the one command that is not about a rig: it puts the agent
+skills the package ships where an agent host looks for them. Run it through the
+project's own install — `bun rigc skills install` — so the links point into that
+project's `node_modules/spine-rigc/skills/`. A second run has nothing to do and
+exits 0. An entry already at `<dir>/<name>` that is not a link to the same folder
+(or, under `--copy`, not the same bytes) is refused, exit 1, and **nothing is
+written** — every such entry is named with what is there and what was required:
+
+```text
+rigc skills install: <n> of the <m> skill(s) cannot be installed into <dir>, and nothing was written:
+  <dir>/rigc-motion is a plain file; a symlink to ../../node_modules/spine-rigc/skills/rigc-motion was required
+Remove the entries named above, or pass --dir to install somewhere else.
+```
+
+What is found is one of `a plain file`, `a directory`, `a symlink to <text>, which
+resolves to <path>` (or `to nothing`), and under `--copy` `a directory that is not
+the package's copy (<file> differs)`. A link to the package's own folder is not in
+the way however it is spelled, so an absolute link somebody else made is kept and
+reported `already linked`.
+
 Pick the profile deliberately, and know which one you got by saying nothing. The
 default is `spine`: "is this valid Spine 4.3 that any runtime plays correctly",
 which is the question a rig authored anywhere is asking. `--profile spine-html`
@@ -727,7 +772,8 @@ bun cli.ts diff     candidate.json reference.json [--as <candidate>=<reference>]
 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 …] [--skin …] [--fps 12] [--max 256]
-bun cli.ts preview  --candidate path/to/spine [--animation …] [--out preview.html]
+bun cli.ts render   --candidate path/to/spine --slot <name,…> | --hide <name,…>   # part of the rig, same grid
+bun cli.ts preview  --candidate path/to/spine [--candidate path/to/another …] [--animation …] [--out preview.html]
 bun cli.ts vote     --candidate path/to/a --candidate path/to/b [--out ballot.html]
 bun cli.ts vote     --record vote-<id>.json [--ballot ballot.html] [--ledger votes.jsonl]
 bun cli.ts pose     --images path/to/parts --frame poseA.png [--out pose.json]
@@ -802,12 +848,39 @@ bun cli.ts pose     --images path/to/parts --frame poseA.png [--out pose.json]
   gate can know you did not mean them. `render` writes
   `render/<animation>/f0000.png…` with a `contact.png` grid of **every** frame
   beside them (open that one first — spacing is a comparison across frames) and a
-  `frames.json` sidecar naming the world box they are pictures of. `preview`
+  `frames.json` sidecar naming the world box they are pictures of. `contact.png`
+  is for spacing across frames; a defect is read on **one frame at full size**,
+  because a tile is too small to say which part a pixel belongs to. When a frame
+  looks wrong, render it again with `--hide <slot>` — the **largest attachment**
+  first, since it covers the most and is the likeliest to hide what is under it —
+  and compare the two frames: `--hide` and `--slot <name,…>` draw a subset of the
+  slots on the **same grid** as the whole rig (the viewport is still fitted to
+  every slot), so the frames overlay pixel for pixel and the difference is the
+  part. Three questions to ask of that full-size frame, each answered that way.
+  **Is any picture drawn twice?** Hide the largest attachment and look for a second
+  copy of what it covered, since a ghost under an opaque part is invisible until the
+  part is gone. **Is there a straight edge where the art has none?** A part cut as a
+  rectangle carries a border its drawing never had, and `--slot <that slot>` shows it
+  alone. **Does a part cover a feature the art shows?** An eye slot drawn over the
+  eye is found by hiding the slot and watching the feature come back. A name the skeleton does not declare is refused with every slot it does,
+  in draw order; a slot whose art lives only under another skin is refused naming
+  that skin (pass `--skin`); the two flags together are refused. `frames.json`
+  records the subset as `slots` or `hidden`, and **`check` refuses such a set as
+  a reference** (§9). `preview`
   writes one self-contained `.html`: your skeleton, atlas and page PNGs are
   embedded in it as data URIs and played by the official **Spine Web Player**, so
   double-clicking it is also the interop proof — what plays there was played by
   Esoteric Software's runtime, not by rigc's. The player is loaded from a CDN
-  rather than copied into the file, so the first open needs a network.
+  rather than copied into the file, so the first open needs a network. Its
+  header carries the gate's line for the candidate — the `N assertions: …`
+  summary `rigc validate <dir>` prints for the same files, and its first `FAIL`
+  line when there is one — with the rigc version, measured when the page is
+  written; a refused candidate is still previewed, because looking at a red
+  build is what the page is for. Note that it is the **bare-directory** reading:
+  with no rig spec and no second compile beside the files, `A09` and `A18` report
+  SKIP there, so its counts are not the ones `build` printed. It takes
+  neither `--slot` nor `--hide` — the player draws what the skeleton draws — and
+  refuses both by name rather than playing the whole rig as if it had obeyed.
 - 📐 **`pose` is the only command here that reads an INPUT rather than a result.**
   Everything else takes a spec or a build and tells you something about it; `pose`
   takes a picture the user already has — a key pose — and reports where each loose
@@ -5996,7 +6069,8 @@ rather than the rig (**§9.2**'s atlas floor — and note that it is *not* `--at
 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.
+per-slot report, `--out <dir>` for the picture each listed frame's figures came from
+(**§9.2.1**).
 
 🚨 **What `check` certifies is the DEFAULT skin, unless you pass `--skin`.** 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
@@ -6034,6 +6108,21 @@ remember:
 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 of PART of a rig is not a reference.** `render --slot`/`--hide`
+(§0) records the subset in `frames.json`, and `check` refuses any set that carries
+`slots` or `hidden`, before posing anything:
+
+```
+rigc check error: --frames frames/ records a slot subset (hidden: head) in frames.json; a partial render is not a reference set — render the reference without --slot/--hide
+```
+
+It is the skin clause one step stronger: two skins are two pictures of one rig,
+while a reference with a part left out is not a picture of the whole rig at all,
+and scoring a whole candidate against it would print a real figure about art the
+reference never drew. There is no flag that makes it comparable. A set with
+neither key — every set rendered without the flags, and every set written before
+they existed — is compared exactly as before.
+
 📌 **Deform measurement needs no such flag, because the timeline carries the
 name.** `A39` and the `DEFORM` block pose each key with the skin that key is keyed
 on — a deform timeline's address is a `skin / slot / attachment` triple — so a
@@ -6979,6 +7068,66 @@ slots column is a parenthesis rather than a fraction, the deformation it carries
 already being scored inside the chain that owns the slot, and the row is telling you
 about your bone tree rather than about a hole in your figure.
 
+#### 9.2.1 Reading the pictures — `--out`
+
+```bash
+bun cli.ts check --candidate path/to/spine --frames path/to/reference/frames --out check-pictures
+```
+
+The table says **how much** a frame differs; `--out <dir>` writes **where**. For
+every frame the table lists — the frames worth reading, or every compared frame
+under `--all-frames` — it writes `<dir>/<set>/f####.png`, and beside them a
+`frames.json` recording what they are pictures of: the candidate, the frames
+directory, both skins, the framing scope, the grid, and per set the box it was
+framed in and which frames were written. Each picture is four panes, left to right:
+
+| Pane | What it is | The figure in its label |
+| --- | --- | --- |
+| `REFERENCE` | the frame as read from `--frames` | `REF D` — the table's `ref Δ`: pixels the reference moved since its own previous frame (`-` when that frame was not compared) |
+| `CANDIDATE` | your candidate exactly as `check` rendered it onto that grid — same framing, same skin, same texture | `DPX` — the table's `Δpx`, the same count on your side |
+| `DIFFERENCE` | per pixel, the largest of the three channel differences between the two, on a **fixed** grey ramp: 0 is black, 255 is white. Drawn over exactly the pixels the MAE averages over — what your geometry covers or the reference drew — and transparent everywhere else | `MAE` — the frame's MAE, as the table prints it |
+| `OVERLAY` | the two at 50 % each, so a displaced edge reads as a double line and a part drawn twice reads as a ghost | `UNION` — the table's `union px` |
+
+Under the panes, one row per slot of that frame: its drift at the table's
+precision and how it was matched, or why it has none (`not drawn`, `no attributable
+drift`). The frame's worst slot — the one its table row names — is marked `>`. The
+text is the tree's 5x7 bitmap font, so it prints in capitals, and a character the
+font does not carry draws as a solid block rather than disappearing.
+
+- **The ramp is fixed, and deliberately not stretched to the frame's own maximum.**
+  Two runs' pictures are then comparable by eye, and a quiet frame looks quiet. The
+  cost is the other side of the same choice: a frame whose MAE is a texture floor
+  of a few points reads as a **near-black silhouette** of the union, because 7 of
+  255 is dark. That silhouette is not nothing — it is where the two sides drew —
+  and the grey you have to find is the difference you have to fix.
+- **Every pane is at the grid's native size, and there is no upscaling option.** An
+  upscaled difference is a difference the instrument invented: a resampling filter
+  spreads ink into pixels the comparison never measured. Open the file and zoom in
+  your viewer instead, where the magnification is yours and visibly not the data.
+- **Nothing in a picture is a new number.** Every figure in it is one the report
+  already holds. The rasters are the ones the figures were computed on, kept at the
+  moment they were compared rather than rendered again.
+
+What a picture cannot tell you, and does not try to:
+
+- **Which side is right.** The difference pane is symmetric. A pixel lit there is
+  a pixel the two disagree about; whether yours or the reference's is the one to
+  move is yours to read off the other panes.
+- **Anything about a frame it does not show.** The set is the table's listing, so
+  a frame outside it was not pictured — not pictured clean. `--all-frames` widens
+  the set to every compared frame when the listing is not enough.
+
+`<dir>/<set>/` is cleared and rewritten, as `render` clears its own, and nothing
+else under `<dir>` is touched. Two things are refused before anything is compared:
+a **file** at `<dir>` (`check: --out <path> is a file; it names a directory`), and a
+directory that **is `--frames` or holds it** (`check: --out <path> is --frames …` /
+`… holds --frames …`), because clearing a set directory there deletes the frames the
+pictures are of. And a `check --out` directory is not a frame set: pointed at by
+`--frames`, it is refused by the field that says so —
+`` frames.json carries "comparison": it was written by `rigc check --out` `` and the
+rest of the sentence names the frames it was made against. The reference pane inside each
+picture is a frame; the file is four panes and a table.
+
 ### 9.3 What it still cannot see
 
 - **Anything a frame does not contain.** Bone `length`, the setup `inherit` mode,

package/docs/MOTION.md

@@ -1007,6 +1007,7 @@ rigc build --rig semaphore.rig.json --motion semaphore.motion.json --images part
   ..    pages=3 regions=3 bones=4 slots=3 animations=1 version=4.3.13 regionAttachments=3 meshAttachments=0 physicsConstraints=0 rig=semaphore profile=spine
 rigc: wrote …/semaphore/spine/skeleton.json
 rigc: wrote …/semaphore/spine/skeleton.atlas
+rigc: look at it: rigc preview --candidate …/semaphore/spine
 ```
 
 ```bash

package/package.json

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

package/skills/rigc/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rigc
-description: Author, build and validate Spine 4.3 skeleton data (skeleton.json plus its .atlas) from loose part PNGs with rigc, the rig compiler that verifies its own output through a spine-core round-trip before writing it. Use for any request to make a Spine rig or Spine animation from PNG parts, to run or read rigc build, validate, render, preview, check or vote, or to write or fix a *.rig.json or *.motion.json spec; it says which shipped guide to open for the need at hand. Not for Live2D conversion, cutting an illustration into parts, or real-time face tracking.
+description: Author, build and validate Spine 4.3 skeleton data (skeleton.json plus its .atlas) from loose part PNGs with rigc, the rig compiler that verifies its own output through a spine-core round-trip before writing it. Use for any request to make a Spine rig or Spine animation from PNG parts, or where the source is a Live2D, Unity or video model whose pictures you can render, to run or read rigc build, validate, render, preview, check or vote, or to write or fix a *.rig.json or *.motion.json spec; it says which shipped guide to open for the need at hand. Not for Live2D conversion, cutting an illustration into parts, or real-time face tracking.
 license: MIT
 compatibility: Requires Bun 1.2 or later. The tool is the npm package spine-rigc (bunx spine-rigc, or bun add -d spine-rigc); the command it installs is rigc.
 ---
@@ -34,8 +34,13 @@ whole interface, and this skill only says which of them to open.
 ```shell
 bunx spine-rigc --help       # run it without installing
 bun add -d spine-rigc        # or pin it in the project; the command is `rigc`
+bun rigc skills install      # then link these skills into .agents/skills
 ```
 
+Codex, Gemini CLI and Antigravity read skills from `.agents/skills/` in the
+workspace and none of them reads `node_modules`; `rigc skills install` puts every
+skill the package ships there, and `rigc skills --help` says what it refuses.
+
 ## The loop
 
 1. `rigc build --rig <spec> --motion <spec> --images <dir> --out <dir>` compiles,
@@ -50,28 +55,53 @@ bun add -d spine-rigc        # or pin it in the project; the command is `rigc`
    §4.11.2.
 4. `rigc render --candidate <out>` or `rigc preview --candidate <out>` — look at
    it. A rig with its head off its torso passes the gate; looking is what catches it.
-5. `rigc check --candidate <out> --frames <dir>` when you have reference pictures;
+   Open one frame at full size, not only `contact.png`: the sheet is for spacing
+   across frames, and a defect is read on a frame. Ask it three things — is any
+   picture drawn twice, is there a straight edge where the art has none, does a part
+   cover a feature the art shows — and answer each with `render --hide <slot>` (or
+   `--slot <slot,…>`), which draws the frame again without that part on the same
+   grid, so the two frames say which part a pixel is. AUTHORING §0 holds the three.
+5. `rigc check --candidate <out> --frames <dir>` when you have reference pictures
+   (`--out <dir>` writes the picture each of its numbers came from — open the worst);
    `rigc vote --candidate <a> --candidate <b>` when several candidates are green and
    only a person can choose between them.
 6. `rigc validate <out>` re-gates artifacts already on disk, and
    `rigc <command> --help` is each command's own flag table.
+7. Every finished unit ends with `rigc preview --candidate <out>`, and the report
+   names the `.html` it wrote. The hand-off to a person is part of the work.
 
 The loop in full, with `pose` before it and `chainfit` after the first build:
 AUTHORING §0.
 
+## When the source is not loose PNGs
+
+A Live2D model, a Unity scene or a video is a player, not a set of parts. Make the
+reference frames first: render the source at the rate you will check at, into one
+directory of `f0000.png`, `f0001.png`…, and `rigc check --frames <that dir> --fps <rate>`
+reads them with no `frames.json`. A port with no reference frames is unmeasured,
+not finished. The parts are the source's own texture cut along its drawables, never
+a screenshot: a screenshot is the composed result, and a part cut from it carries
+every part under it. rigc reads none of those formats — FACE §11, the paragraph
+that opens *No Live2D file is read or written*
+([FACE.md](https://github.com/firejune/rigc/blob/main/docs/FACE.md#11-non-goals--stated-so-nobody-proposes-them-as-gaps)) —
+only the pictures they produce. The rule, the background those frames need and
+what a wrong one costs: AUTHORING §0, *When the source is a foreign player*.
+
 ## Which guide, for which need
 
-Read [AUTHORING.md](../../docs/AUTHORING.md) first, whatever the need: the two
+Read [AUTHORING.md](https://github.com/firejune/rigc/blob/main/docs/AUTHORING.md) first, whatever the need: the two
 spec files field by field, the emission rules, the loop, and the failure map. Then:
 
 | The request is… | Open | Skill |
 | --- | --- | --- |
-| a **skeleton** — how many bones, where each pivot sits, what hangs off what | [RIGGING.md](../../docs/RIGGING.md) | `rigging` |
-| a **movement** — an idle, a loop, from this pose to that one | [MOTION.md](../../docs/MOTION.md) | `motion` |
-| a **face** — a blink, a gaze, a head turn a few degrees off axis | [FACE.md](../../docs/FACE.md) | `face` |
-| a **skeleton.json somebody else authored** — read it, repair it, extend it | [INGEST.md](../../docs/INGEST.md) | `ingest` |
-| you are the **person operating** the agent rather than the agent | [PROMPTING.md](../../docs/PROMPTING.md) | — |
-
-The same files are in the installed package at `node_modules/spine-rigc/docs/`;
-inside this plugin they are at `${CLAUDE_PLUGIN_ROOT}/docs/`. Formats, the CLI
-reference and the licence chain: [README.md](../../README.md).
+| a **skeleton** — how many bones, where each pivot sits, what hangs off what | [RIGGING.md](https://github.com/firejune/rigc/blob/main/docs/RIGGING.md) | `rigc-rigging` |
+| a **movement** — an idle, a loop, from this pose to that one | [MOTION.md](https://github.com/firejune/rigc/blob/main/docs/MOTION.md) | `rigc-motion` |
+| a **face** — a blink, a gaze, a head turn a few degrees off axis | [FACE.md](https://github.com/firejune/rigc/blob/main/docs/FACE.md) | `rigc-face` |
+| a **skeleton.json somebody else authored** — read it, repair it, extend it | [INGEST.md](https://github.com/firejune/rigc/blob/main/docs/INGEST.md) | `rigc-ingest` |
+| you are the **person operating** the agent rather than the agent | [PROMPTING.md](https://github.com/firejune/rigc/blob/main/docs/PROMPTING.md) | — |
+
+Every guide linked here is in the installed package at `node_modules/spine-rigc/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/firejune/rigc/blob/main/README.md), installed at `node_modules/spine-rigc/README.md`.

package/skills/{face → rigc-face}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: face
+name: rigc-face
 description: Author a face on plain Spine data with rigc — a blink, a gaze shift, a breathing portrait and a head turn a few degrees off axis, built from deform timelines and per-part parallax. Use when the request is a talking or living portrait, a standing character, an expression or a head turn, such as "rig this face", "make the portrait blink and look around" or "turn the head". Not for Live2D file conversion, cutting a face illustration into parts, or VTuber-style real-time face tracking.
 license: MIT
 compatibility: Requires Bun 1.2 or later and the npm package spine-rigc.
@@ -9,7 +9,7 @@ compatibility: Requires Bun 1.2 or later and the npm package spine-rigc.
 
 Load this when the request is a **head rather than a body**: a drawn face that
 breathes, blinks, moves its eyes and turns a few degrees off axis. Every rule below
-is owned by [FACE.md](../../docs/FACE.md); this file says when to open it and what
+is owned by [FACE.md](https://github.com/firejune/rigc/blob/main/docs/FACE.md); this file says when to open it and what
 it will not do for you.
 
 ## Non-negotiables
@@ -40,17 +40,21 @@ differential audit and the three limits it does not lift.
 
 ## Read, in this order
 
-1. [AUTHORING.md](../../docs/AUTHORING.md) — the `deform` timeline field by field
+1. [AUTHORING.md](https://github.com/firejune/rigc/blob/main/docs/AUTHORING.md) — the `deform` timeline field by field
    and what rigc refuses in it (§4), the failure map (§5–§6), the editor's
    conventions (§10).
-2. [MOTION.md](../../docs/MOTION.md) — timing, easing and the offset table (§3),
+2. [MOTION.md](https://github.com/firejune/rigc/blob/main/docs/MOTION.md) — timing, easing and the offset table (§3),
    candidates and the ballot (§4–§5). A blink and a gaze are ordinary motion work.
-3. [FACE.md](../../docs/FACE.md) — the face's own geometry: the closed form every
+3. [FACE.md](https://github.com/firejune/rigc/blob/main/docs/FACE.md) — the face's own geometry: the closed form every
    number in a turn comes from (§1), the hierarchy underneath (§3), what
    foreshortens (§5), and the deform audit gap (§9).
-4. Then [RIGGING.md](../../docs/RIGGING.md) for the hierarchy as a general rule
-   rather than this closed form, and [INGEST.md](../../docs/INGEST.md) if the head
+4. Then [RIGGING.md](https://github.com/firejune/rigc/blob/main/docs/RIGGING.md) for the hierarchy as a general rule
+   rather than this closed form, and [INGEST.md](https://github.com/firejune/rigc/blob/main/docs/INGEST.md) if the head
    arrived as a compiled skeleton.
 
+Every guide linked here is in the installed package at `node_modules/spine-rigc/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/`.
+
 The install line and the build → validate → render → check loop are in the `rigc`
 skill.

package/skills/{ingest → rigc-ingest}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: ingest
+name: rigc-ingest
 description: Work with a Spine skeleton.json somebody else authored — exported from the Spine editor or another tool — using rigc. Read and validate it, understand a complaint rigc raised about it, decompile it into rigc specs with `rigc ingest`, normalise, re-pivot or rename it, and extend it with an animation it does not have. Use when the input is an existing skeleton.json with its .atlas and page images rather than loose part PNGs. Not for Live2D file conversion or runtime tracking.
 license: MIT
 compatibility: Requires Bun 1.2 or later and the npm package spine-rigc.
@@ -10,7 +10,7 @@ compatibility: Requires Bun 1.2 or later and the npm package spine-rigc.
 Load this when what you were handed is **already a skeleton**: a `skeleton.json`
 with its `.atlas` and page images, and a request to understand it, answer a
 complaint about it, re-express it, or extend it. Every rule below is owned by
-[INGEST.md](../../docs/INGEST.md); this file says when to open it and what it will
+[INGEST.md](https://github.com/firejune/rigc/blob/main/docs/INGEST.md); this file says when to open it and what it will
 not do for you.
 
 ## Non-negotiables
@@ -61,14 +61,18 @@ thing to reach for; transcription by hand is what you fall back on for a constru
 
 ## Read, in this order
 
-1. [INGEST.md](../../docs/INGEST.md) — what every command will and will not do with
+1. [INGEST.md](https://github.com/firejune/rigc/blob/main/docs/INGEST.md) — what every command will and will not do with
    a foreign file (§0), `ingest` and transcription (§2), what each validator
    complaint means on an export (§3), and the re-pivot, rename and extend
    recipes (§4).
-2. [AUTHORING.md](../../docs/AUTHORING.md) — the two spec files the transcription
+2. [AUTHORING.md](https://github.com/firejune/rigc/blob/main/docs/AUTHORING.md) — the two spec files the transcription
    targets (§3–§4), the failure map (§5–§6), and the coordinate contract (§11.2).
-3. Then [RIGGING.md](../../docs/RIGGING.md) for why the re-pivot edit has the shape
-   it has, and [MOTION.md](../../docs/MOTION.md) for the animation you are adding.
+3. Then [RIGGING.md](https://github.com/firejune/rigc/blob/main/docs/RIGGING.md) for why the re-pivot edit has the shape
+   it has, and [MOTION.md](https://github.com/firejune/rigc/blob/main/docs/MOTION.md) for the animation you are adding.
+
+Every guide linked here is in the installed package at `node_modules/spine-rigc/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/`.
 
 The install line and the build → validate → render → check loop are in the `rigc`
 skill.

package/skills/{motion → rigc-motion}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: motion
+name: rigc-motion
 description: Author a Spine animation with rigc from key poses — an idle, a loop, a move from one picture to another — with timing and spacing, ease in and out, anticipation, arcs, overlap, follow-through, squash and stretch, and candidate variants a person can choose between. Use when the request is a movement on an existing or planned rig, in the animator's words too: "animate this rig", "make it breathe", "go from pose A to pose B", "make it feel heavier", "the cape should follow through". Not for Live2D, separating an image into parts, or real-time tracking.
 license: MIT
 compatibility: Requires Bun 1.2 or later and the npm package spine-rigc.
@@ -10,7 +10,7 @@ compatibility: Requires Bun 1.2 or later and the npm package spine-rigc.
 Load this when the request is a **movement rather than a skeleton**: a sentence of
 intent, between zero and N pictures of what the movement passes through, and a
 Spine animation somebody would choose coming back. Every rule below is owned by
-[MOTION.md](../../docs/MOTION.md); this file says when to open it and what it will
+[MOTION.md](https://github.com/firejune/rigc/blob/main/docs/MOTION.md); this file says when to open it and what it will
 not do for you.
 
 ## Non-negotiables
@@ -31,17 +31,21 @@ thing that judges a movement is a person's eye through `rigc vote` — MOTION §
 
 ## Read, in this order
 
-1. [AUTHORING.md](../../docs/AUTHORING.md) — the motion spec field by field (§4),
+1. [AUTHORING.md](https://github.com/firejune/rigc/blob/main/docs/AUTHORING.md) — the motion spec field by field (§4),
    the failure map (§5–§6), reading reference frames (§8) and checking against
    them (§9), what the editor does when nobody tells it otherwise (§10), and
    reading a pose out of a picture (§11–§12).
-2. [MOTION.md](../../docs/MOTION.md) — the normal form every motion request
+2. [MOTION.md](https://github.com/firejune/rigc/blob/main/docs/MOTION.md) — the normal form every motion request
    reduces to (§0), timing, easing and the per-bone offset table (§3), and how to
    spread candidates so a ballot informs (§4–§5).
-3. Then [RIGGING.md](../../docs/RIGGING.md) if the skeleton itself is what you have
-   to decide; [FACE.md](../../docs/FACE.md) if the movement is a blink, a gaze or a
-   head turn; [INGEST.md](../../docs/INGEST.md) if the rig arrived as a compiled
+3. Then [RIGGING.md](https://github.com/firejune/rigc/blob/main/docs/RIGGING.md) if the skeleton itself is what you have
+   to decide; [FACE.md](https://github.com/firejune/rigc/blob/main/docs/FACE.md) if the movement is a blink, a gaze or a
+   head turn; [INGEST.md](https://github.com/firejune/rigc/blob/main/docs/INGEST.md) if the rig arrived as a compiled
    skeleton rather than loose parts.
 
+Every guide linked here is in the installed package at `node_modules/spine-rigc/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/`.
+
 The install line and the build → validate → render → check loop are in the `rigc`
 skill.

package/skills/{rigging → rigc-rigging}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: rigging
+name: rigc-rigging
 description: Decide a Spine rig's hierarchy with rigc — how many bones, where each pivot sits, what hangs off what, offsets, chains and what a chain can reach, siblings versus chains, constraints as structure — and which of those decisions the reference frames can check. Use when the request is a skeleton from loose part PNGs, such as "rig these parts", "make a Spine skeleton" or "where do the joints go", before any motion is authored. Not for Live2D, cutting an illustration into parts, or VTuber-style tracking.
 license: MIT
 compatibility: Requires Bun 1.2 or later and the npm package spine-rigc.
@@ -9,7 +9,7 @@ compatibility: Requires Bun 1.2 or later and the npm package spine-rigc.
 
 Load this when the request is a **skeleton rather than a movement**: loose part
 PNGs in, a bone hierarchy out. Every rule below is owned by
-[RIGGING.md](../../docs/RIGGING.md); this file says when to open it and what it
+[RIGGING.md](https://github.com/firejune/rigc/blob/main/docs/RIGGING.md); this file says when to open it and what it
 will not do for you.
 
 ## Non-negotiables
@@ -30,16 +30,20 @@ are named in RIGGING §11 — neither as a pass bar.
 
 ## Read, in this order
 
-1. [AUTHORING.md](../../docs/AUTHORING.md) — the rig spec field by field (§3),
+1. [AUTHORING.md](https://github.com/firejune/rigc/blob/main/docs/AUTHORING.md) — the rig spec field by field (§3),
    the failure map (§5–§6), reading a pose out of a picture (§8.1, §11, §12),
    and the editor's own conventions (§10).
-2. [RIGGING.md](../../docs/RIGGING.md) — the structure itself: what identifies a
+2. [RIGGING.md](https://github.com/firejune/rigc/blob/main/docs/RIGGING.md) — the structure itself: what identifies a
    pivot and what moving one costs (§2–§3), gauges (§4), what a chain can reach
    (§6), and the instruments that see structure (§11).
-3. Then [MOTION.md](../../docs/MOTION.md) once the skeleton exists;
-   [FACE.md](../../docs/FACE.md) if the figure is a head;
-   [INGEST.md](../../docs/INGEST.md) if the skeleton was handed to you already
+3. Then [MOTION.md](https://github.com/firejune/rigc/blob/main/docs/MOTION.md) once the skeleton exists;
+   [FACE.md](https://github.com/firejune/rigc/blob/main/docs/FACE.md) if the figure is a head;
+   [INGEST.md](https://github.com/firejune/rigc/blob/main/docs/INGEST.md) if the skeleton was handed to you already
    compiled.
 
+Every guide linked here is in the installed package at `node_modules/spine-rigc/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/`.
+
 The install line and the build → validate → render → check loop are in the `rigc`
 skill.

package/src/ballot.ts

@@ -63,6 +63,9 @@ import {
   dataUri,
   embeddedJson,
   escapeHtml,
+  PANE_STAGE_CSS,
+  paneGridCss,
+  paneSection,
   PLAYER_LINE,
   PLAYER_SCRIPT_URL,
   PLAYER_STYLE_URL,
@@ -592,14 +595,10 @@ export function buildBallot(input: BallotInput): { html: string; manifest: Ballo
     },
   };
 
-  const panes = manifest.candidates
-    .map(
-      (c) => `<section class="pane">
-  <h2>${c.label}</h2>
-  <div class="stage" id="rigc-player-${c.label}"></div>
-</section>`,
-    )
-    .join('\n');
+  // The pane markup and its grid are `preview.ts`'s since issue #837, which
+  // borrowed them for a page of panes that asks nothing; the bytes here are
+  // the ones this page always wrote.
+  const panes = manifest.candidates.map((c) => paneSection(`rigc-player-${c.label}`, `<h2>${c.label}</h2>`)).join('\n');
 
   const choices = [...labels, TIE]
     .map(
@@ -649,11 +648,9 @@ export function buildBallot(input: BallotInput): { html: string; manifest: Ballo
   button { font: inherit; padding: 4px 12px; border: 1px solid rgba(0, 0, 0, 0.35); border-radius: 4px; background: rgba(255, 255, 255, 0.6); cursor: pointer; }
   button:hover { background: rgba(255, 255, 255, 0.95); }
   button[aria-pressed="true"] { background: #1a1a1a; color: #fff; border-color: #1a1a1a; }
-  #panes { display: grid; grid-template-columns: repeat(${manifest.candidates.length}, minmax(0, 1fr)); gap: 1px; background: rgba(0, 0, 0, 0.15); }
-  @media (max-width: 720px) { #panes { grid-template-columns: minmax(0, 1fr); } }
-  .pane { background: ${backgroundHex()}; display: flex; flex-direction: column; min-width: 0; }
+${paneGridCss(manifest.candidates.length)}
   .pane h2 { margin: 0; padding: 6px 14px; font-size: 15px; letter-spacing: 0.12em; }
-  .stage { height: 52vh; min-height: 260px; }
+${PANE_STAGE_CSS}
   #vote { border-top: 1px solid rgba(0, 0, 0, 0.15); display: flex; flex-direction: column; gap: 10px; }
   .row { display: flex; gap: 8px; align-items: center; flex-wrap: wrap; }
   .row > label, .caption { opacity: 0.65; }