@rig-c/core 3.0.0 → 3.0.1

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="https://raw.githubusercontent.com/rig-c/core/main/assets/banner.svg" alt="rigc — AI-authored 2D rigging and animation, verified before it is written" width="100%" />
+  <img src="https://raw.githubusercontent.com/rig-c/core/main/assets/banner.svg" alt="@rig-c/core — AI-authored 2D rigging and animation, verified before it is written" width="100%" />
 </p>
 
 <p align="center">
@@ -8,6 +8,8 @@
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-38BDF8.svg?style=flat-square" alt="license" /></a>
 </p>
 
+# @rig-c/core
+
 **AI-authored 2D rigging and animation, verified before it is written.** rigc is
 a rig compiler: a rig spec and a motion spec in, skeleton data out — in the Spine 4.3
 format, with rigc's own compiled model beside it —

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rig-c/core",
-  "version": "3.0.0",
+  "version": "3.0.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

@@ -28,7 +28,7 @@ index within that same limit; only legacy uncoded library errors point at `§5.1
 ## Non-negotiables
 
 - **Validation is never bypassed.** `build` writes nothing on a red gate; there is
-  no `--no-validate`, and none may be added — AUTHORING §0 says so in as many
+  no flag to skip it, and none may be added — AUTHORING §0 says so in as many
   words. Correctness is the whole of the reason: the assertions are what make the
   output trustworthy, and they are held to the official parser's verdicts in the
   repository's CI — all but the parse itself, which runs only where the runtime is
@@ -55,20 +55,23 @@ 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 package links no Spine runtime. `validate`, `preview` and `vote` below run
-through `@esotericsoftware/spine-core`: install it beside the package
-(`bun add -d @esotericsoftware/spine-core`) and the same `rigc` runs them, and
-`build` runs the round trip as well. Without it they are refused by name, and
-`build` writes the same files gated without the parse — `rigc --version` names the
-entry that ran. In the parse's place that `build` runs two rules of its own over
-rigc's model document, `A00_MODEL_READ` and `A00_MODEL_REGIONS_ON_PAGES`; they are
-not registry assertions, so its summary counts two more, and AUTHORING §5.2 has a
-row for each.
+The package links no Spine runtime. `build` writes `skeleton.json`,
+`skeleton.atlas` and `skeleton.model.json`. `preview`, `vote`, `bench` and `bonedist`
+run through `@esotericsoftware/spine-core`: install it beside
+the package (`bun add -d @esotericsoftware/spine-core`) and the same `rigc` runs
+them, and `build` runs the round trip as well. Without it those commands are refused
+by name, while `build`, `validate`, `explain`, `diff`, `render`, `check` and `inspect`
+(`--poser core|spine`) run on rigc's own core over `skeleton.model.json` —
+`rigc --version` names the entry that ran (AUTHORING §0). In the parse's place that
+`build` runs two rules of its own over rigc's model document, `A00_MODEL_READ` and
+`A00_MODEL_REGIONS_ON_PAGES`; they are not registry assertions, so its summary
+counts two more, and AUTHORING §5.2 has a row for each.
 
 ## The loop
 
 1. `rigc build --rig <spec> --motion <spec> --images <dir> --out <dir>` compiles,
-   gates, and writes only on green.
+   gates (under `--profile spine`, the default, or `--profile rig-play`), and writes
+   `skeleton.json`, `skeleton.atlas` and `skeleton.model.json` only on green.
 2. Read the report. Every red line names the file to change; fix the spec and
    build again.
 3. `rigc explain --rig <spec> --motion <spec> --out <dir>` when the red line is
@@ -85,11 +88,17 @@ row for each.
    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.
-   When the question is geometry — is this bone where the art is, which way does it
-   squash, where in rig units is this point — `rigc inspect --candidate <out> --show
-   art,bones,names --dim` draws the bones over the art and writes a legend beside the
-   picture that puts every mark back in world units; AUTHORING §13 maps each
-   question to its view.
+   For motion and dial readings, `render --pass-through <cloth>:<leg>` names the
+   frames where a cloth drawn over a leg passes through it (AUTHORING §8.5),
+   `render --angle-range <bone>:<relative-to>` prints how far a bone turns against
+   another (AUTHORING §8.7), `render --seam <slot>:<slot>` reads joint gaps,
+   visible ghosts and background exposure (AUTHORING §8.8), and
+   `render --parallax <dial>` reads a slider dial across its value grid
+   (AUTHORING §8.12). When the question is geometry — is this bone where the art is,
+   which way does it squash, where in rig units is this point —
+   `rigc inspect --candidate <out> --show art,bones,names --dim` draws the bones
+   over the art and writes a legend beside the picture that puts every mark back in
+   world units; AUTHORING §13 maps each question to its view.
 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).
    Read its output from the top: the framing block says whether the figures under
@@ -100,17 +109,21 @@ row for each.
    `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. `rigc repack <out>
-   --out <dir>` packs a build again under `build --pack`'s packing flags when its
-   parts were not kept, and writes only after every region and the skeleton are
-   shown unchanged (`--accept-skeleton-differences` writes a rebuild whose skeleton
-   differs, every difference printed; `--stage-box <slot>` reads a build's stage box)
-   — AUTHORING §0.4. A mesh refused because its triangles are several pieces that
-   share no vertex: `rigc split --rig … --motion … --slot <slot> --out <dir>` writes
-   both specs back with one mesh per piece and every deform key renumbered — build
-   that — AUTHORING §3.4.11.
-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.
+   `rigc <command> --help` is each command's own flag table.
+   `rigc repack <out> --out <dir>` packs a build again under `build --pack`'s
+   packing flags when its parts were not kept, and writes only after every region and
+   the skeleton are shown unchanged (`--keep-pages` refreshes `skeleton.model.json`
+   over the existing atlas pages; `--accept-skeleton-differences` writes a rebuild
+   whose skeleton differs, every difference printed; `--stage-box <slot>` reads a
+   build's stage box) — AUTHORING §0.4. A mesh refused because its triangles are
+   several pieces that share no vertex: `rigc split --rig … --motion … --slot <slot> --out <dir>`
+   writes both specs back with one mesh per piece and every deform key renumbered —
+   build that — AUTHORING §3.4.11.
+7. Every finished unit ends with `rigc preview --candidate <out>` (or
+   `rigc review <out>` when `@rig-c/review` is installed beside the project and a
+   person reviews the build via its loopback URL, AUTHORING §0), and the report
+   names the `.html` or URL it produced. 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.
@@ -141,7 +154,7 @@ spec files field by field, the emission rules, the loop, and the failure map. Th
 | --- | --- | --- |
 | a **skeleton** — how many bones, where each pivot sits, what hangs off what | [RIGGING.md](https://github.com/rig-c/core/blob/main/docs/RIGGING.md) | `rigc-rigging` |
 | a **movement** — an idle, a loop, from this pose to that one | [MOTION.md](https://github.com/rig-c/core/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/rig-c/core/blob/main/docs/FACE.md) | `rigc-face` |
+| a **face** — a blink, a gaze, a head turn or a value-driven face dial | [FACE.md](https://github.com/rig-c/core/blob/main/docs/FACE.md) | `rigc-face` |
 | a **skeleton.json somebody else authored** — read it, repair it, extend it | [INGEST.md](https://github.com/rig-c/core/blob/main/docs/INGEST.md) | `rigc-ingest` |
 | you are the **person operating** the agent rather than the agent | [PROMPTING.md](https://github.com/rig-c/core/blob/main/docs/PROMPTING.md) | — |
 

package/skills/rigc-face/SKILL.md

@@ -1,16 +1,17 @@
 ---
 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.
+description: Author a face on plain Spine data with rigc — a blink, a gaze shift, a breathing portrait, a head turn (from a flat sheet a few degrees off axis or a per-vertex depth map across its turn ceiling) and slider-driven face dials, built from closed-form deform transforms, derived group tracks, per-part parallax and socket alpha clipping. Use when the request is a talking or living portrait, a standing character, an expression, a head turn or a look dial, 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.4 or later and the npm package @rig-c/core (rig-c is the convenience name).
 ---
 
-# Face — a turn, a gaze and a blink
+# Face — a turn, a gaze, a blink and a dial
 
 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](https://github.com/rig-c/core/blob/main/docs/FACE.md); this file says when to open it and what
-it will not do for you.
+breathes, blinks, moves its eyes, turns off axis (on a flat sheet or a per-vertex
+`depth` map) or exposes its turn as a slider-driven dial. Every rule below is owned
+by [FACE.md](https://github.com/rig-c/core/blob/main/docs/FACE.md); this file says when to open it and what it will
+not do for you.
 
 📖 **A failure line ends with the command that prints its row of the guide** —
 ` (see rigc guide <RULE>)`. Run that command first, before reading anything else:
@@ -27,9 +28,22 @@ index within that same limit; only legacy uncoded library errors point at `§5.1
 
 - **Validation is never bypassed.** `build` writes nothing on a red gate, and there
   is no flag that changes that — AUTHORING §0.
-- **The compiler never invents a value.** A `deform` key states every vertex it
-  moves; the geometry a turn implies is evaluated by you and written into the spec,
-  never inferred by the compiler — AUTHORING §4 and FACE §1.
+- **The compiler never invents a value.** A `deform` key states either explicit
+  vertex deltas or `transform` (`yaw`/`pitch` with `radius` and `degrees`, or over
+  the mesh's per-vertex `depth` sheet, AUTHORING §3.4.5 and FACE §2.1, §2.2), and a
+  bone group track states `derive` (`depth` per member, `carried` shared shift); the
+  compiler evaluates the closed form from the parameters you declare and never
+  guesses a radius, angle or depth — AUTHORING §4, §4.5.1, §4.11.1 and FACE §1,
+  §1.1, §3.1.
+- **A face angle exposed as a dial is a slider constraint, not a playback time.**
+  Map a control bone across `[−1, +1]` onto the turn animation with a slider
+  (AUTHORING §3.5.2, FACE §8), bound its degrees by the turn ceiling `build` and
+  `explain` print for the depth sheet (FACE §2.2), set `additive: true` when yaw and
+  pitch dials share a target (`A40_SLIDERS_COMPOSE_ON_A_SHARED_TARGET`), keep driven
+  constraints after their driver (`A42_DRIVEN_CONSTRAINTS_UPDATE_AFTER_THEIR_DRIVER`),
+  read the dial across its value grid with `rigc render --candidate <out> --parallax <dial>`
+  (AUTHORING §8.12), and clip an iris or highlight to its painted socket with
+  `alphaClip` (AUTHORING §3.4, FACE §11).
 - **The validator's messages are the instructions.** Read each named failure as the
   pointer to the file that has to change — AUTHORING §5.
 
@@ -46,19 +60,23 @@ nothing about the fold, so author under `--profile rig-play`.
 
 What `A39` still cannot say is whether the projection was the right one —
 nothing measures whether 12° was the angle the shot wanted. FACE §9.2 is that
-demonstration, three builds with one of them refused, and §9.3 is the
-differential audit and the three limits it does not lift.
+demonstration, three builds with one of them refused, and §9.3 is the differential
+audit and the three limits it does not lift.
 
 ## Read, in this order
 
-1. [AUTHORING.md](https://github.com/rig-c/core/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).
+1. [AUTHORING.md](https://github.com/rig-c/core/blob/main/docs/AUTHORING.md) — `alphaClip` and per-vertex `depth` maps
+   (§3.4, §3.4.5), slider constraints (§3.5.2), the `deform` timeline, `derive` and
+   `transform` field by field (§4, §4.5.1, §4.11, §4.11.1), the failure map
+   (§5–§6), `render --parallax <dial>` (§8.12), and the editor's conventions (§10).
 2. [MOTION.md](https://github.com/rig-c/core/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](https://github.com/rig-c/core/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).
+3. [FACE.md](https://github.com/rig-c/core/blob/main/docs/FACE.md) — the face's own geometry: the closed form and
+   `transform` (§1, §1.1), per-vertex depth sheets and turn ceilings (§2, §2.1,
+   §2.2), the shared-shift hierarchy and `derive` (§3, §3.1), the 3×5 mesh and its
+   silhouette cliff (§4), what foreshortens (§5), the blink and channel allocation
+   (§6–§7), the three cliffs and the turn as a slider-driven value (§8), the deform
+   audit gap (§9), and non-goals and `alphaClip` socket clipping (§11).
 4. Then [RIGGING.md](https://github.com/rig-c/core/blob/main/docs/RIGGING.md) for the hierarchy as a general rule
    rather than this closed form, and [INGEST.md](https://github.com/rig-c/core/blob/main/docs/INGEST.md) if the head
    arrived as a compiled skeleton.

package/skills/rigc-rigging/SKILL.md

@@ -36,17 +36,24 @@ index within that same limit; only legacy uncoded library errors point at `§5.1
 ## What this guide will not do
 
 Nothing grades a hierarchy. A rig with its head off its torso passes the gate, the
-pixels are nearly blind to structure, and the two instruments that see it at all
-are named in RIGGING §11 — neither as a pass bar.
+pixels are nearly blind to structure, and the instruments that see it at all are
+named in RIGGING §11 and §11.2 — none as a pass bar. `rigc pose` and `rigc chainfit`
+read part placements and chain hinges from a key-pose picture inside the loop
+(AUTHORING §11, RIGGING §9–§10); `rigc bonedist` measures per-frame bone
+world-transform distance against the same rig's own `home` setup-pose animation
+(RIGGING §7.3) or, at the finish line only, against another skeleton (RIGGING
+§11.2, subject to the honesty rule in AUTHORING §9.1).
 
 ## Read, in this order
 
 1. [AUTHORING.md](https://github.com/rig-c/core/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).
+   the failure map (§5–§6), reading a pose out of a picture and diagnostic render
+   flags (§8.1, §8.5, §8.7, §8.8, §11, §12), the honesty rule (§9.1), and the
+   editor's own conventions (§10).
 2. [RIGGING.md](https://github.com/rig-c/core/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).
+   pivot and what moving one costs (§2–§3), gauges (§4), what a chain can reach and
+   `bonedist` against `home` (§6–§7, §7.3), and the instruments that see structure
+   (§11, §11.2).
 3. Then [MOTION.md](https://github.com/rig-c/core/blob/main/docs/MOTION.md) once the skeleton exists;
    [FACE.md](https://github.com/rig-c/core/blob/main/docs/FACE.md) if the figure is a head;
    [INGEST.md](https://github.com/rig-c/core/blob/main/docs/INGEST.md) if the skeleton was handed to you already