spine-rigc 0.11.0 → 0.12.0

package/README.md

@@ -36,6 +36,7 @@ parser and a list of named assertions all come back green.
 | a compiled rig | `rigc preview` | one self-contained `.html` that plays it in Spine's own web player |
 | two to four compiled rigs | `rigc vote` | one ballot page a human picks from, and the answer checked into a ledger |
 | a picture of a key pose | `rigc pose` | where each loose part PNG sits in it, in spec coordinates — the movement between two poses is then yours to key ([docs/MOTION.md](docs/MOTION.md)) |
+| the same picture, and a rig | `rigc chainfit` | the parts `pose` refuses because something is drawn over them — read through the candidate's own draw order and hierarchy, with the share of each part the answer was measured on |
 
 Everything in that table needs Bun and this package: no clone, no reference art, no
 art pipeline, no server.
@@ -353,6 +354,16 @@ self-contained `.html` that plays it in Spine's own web player; **`vote`** puts
 four candidates in one page and takes a human's answer back. Reach for them the moment
 a rig compiles green, because green says nothing at all about the picture.
 
+<p align="center">
+  <img src="https://raw.githubusercontent.com/firejune/rigc/main/assets/rigc-keypose.gif" alt="Two key poses read back by rigc pose, two candidate in-between motions compiled from them, and a rigc vote ballot picking one" width="600" />
+</p>
+
+<p align="center"><em>The whole loop on one character: two key poses are the given
+conditions, <code>rigc pose</code> reads where every part sits in each picture, two
+candidate in-betweenings are compiled from the same pair — and a real
+<code>rigc vote</code> ballot picks the winner, because the movement between the poses
+is the one thing no instrument here will grade.</em></p>
+
 Three properties of `vote` are worth stating, because they are what make its ledger
 usable by the next agent rather than by a reader: **a tie is a recorded outcome, not a
 missing one** — `both-unacceptable` is the tie that means *propose again*, and it is
@@ -371,7 +382,9 @@ it, so those coordinates go into the rig and the motion **by construction** and
 effort goes into the part no instrument can measure: the movement between two poses.
 A part that matches nowhere is refused by name, two near-equal placements are reported
 as both, and nothing it prints is a score. Fields, the coordinate contract and the
-limits: [AUTHORING.md §11](docs/AUTHORING.md).
+limits: [AUTHORING.md §11](docs/AUTHORING.md). The parts it refuses because
+something is drawn over them are `rigc chainfit`'s, once a candidate exists —
+[§12](docs/AUTHORING.md).
 
 ## The gallery — four complete rigs over art that ships with them
 
@@ -406,6 +419,7 @@ commands take it and what its default is.
 | `preview --candidate <dir>` | one self-contained `.html` that plays it |
 | `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 |
 | `diff <candidate.json> <reference.json>` | structural comparison of two skeletons, one ratio per measure and deliberately no combined score |
 | `check --candidate <dir> --frames <dir>` | the candidate against reference pictures — the only instrument here that can see a *wrong animation* |
 | `bench <rung> --candidate <dir>` | one rung of the benchmark ladder |

package/cli.ts

@@ -72,6 +72,18 @@ import {
   poseLines,
   type PoseOptions,
 } from './src/pose.ts';
+import {
+  ANCHOR_MAX_RESIDUAL,
+  ANCHOR_MAX_UNEXPLAINED,
+  chainFitLines,
+  ChainFitError,
+  DEFAULT_HINGE_MAX,
+  DEFAULT_HINGE_MIN,
+  DEFAULT_MIN_VISIBLE,
+  DEFAULT_PASSES,
+  estimateChainFit,
+  type ChainFitOptions,
+} from './src/chainfit.ts';
 import { buildPreview, PLAYER_LINE, type PreviewPage } from './src/preview.ts';
 import {
   atlasPageNames,
@@ -1060,6 +1072,100 @@ function cmdPose(flags: Record<string, string>): void {
   writeJson(out, report);
 }
 
+// ---------------------------------------------------------------------------
+// reading the half a picture hides — chainfit
+// ---------------------------------------------------------------------------
+//
+// ⭐ `pose` above reads a picture with nothing but the loose parts, and refuses
+// the parts another part is drawn over — a residual measured through an occluder
+// rises AT the correct placement, so the honest answer is a refusal. This reads
+// those, and the whole difference is that it is also given the CANDIDATE: with a
+// draw order the covered pixels can be excluded from a part's objective instead
+// of charged to it, and with a hierarchy a child of a placed bone has one degree
+// of freedom — the hinge about its own pivot — where `pose` has four.
+//
+// 🚫 Same phase and the same framing as `pose`: it reads a given condition into
+// spec coordinates and grades nothing. Every residual is a trust signal, every
+// threshold is reported, and `visibleShare` is how much of the part the number
+// was even computed on.
+//
+//   rigc chainfit --candidate <dir> --images <dir> --frame poseA.png [--anchor pose.json]
+
+const DEFAULT_CHAINFIT_OUT = 'chainfit.json';
+
+function cmdChainFit(flags: Record<string, string>): void {
+  if (flags.candidate === undefined) {
+    throw new UsageError('chainfit needs --candidate <dir | skeleton.json> — the compiled rig to read the frame through');
+  }
+  if (flags.images === undefined) {
+    throw new UsageError("chainfit needs --images <dir> — where the candidate's attachment image names resolve to PNGs");
+  }
+  if (flags.frame === undefined) throw new UsageError('chainfit needs --frame <path> — one pose frame to read the placements out of');
+  // Refused rather than ignored. Every other --candidate command takes --atlas, so
+  // passing it here is a reasonable thing to try — and a flag that silently does
+  // nothing is worse than one that says why it cannot.
+  if (flags.atlas !== undefined) {
+    throw new UsageError(
+      'chainfit reads no atlas: the part art comes from --images, one PNG per attachment image name, and the ' +
+        'skeleton is all it needs of the candidate. Drop --atlas',
+    );
+  }
+  const options: ChainFitOptions = {
+    candidatePath: flags.candidate,
+    imagesDir: flags.images,
+    framePath: flags.frame,
+  };
+  if (flags.anchor !== undefined) options.anchorPath = flags.anchor;
+  const hinge = readRange(flags, 'hinge');
+  if (hinge) {
+    if (hinge.high - hinge.low > 360) throw new UsageError('--hinge cannot span more than a full turn');
+    options.hinge = { minDeg: hinge.low, maxDeg: hinge.high };
+  }
+  if (flags.stretch !== undefined) {
+    const value = Number(flags.stretch);
+    if (!Number.isFinite(value) || value < 1) throw new UsageError('--stretch must be a ratio of 1 or more, e.g. 1.25');
+    options.stretch = value;
+  }
+  if (flags['min-visible'] !== undefined) {
+    const value = Number(flags['min-visible']);
+    if (!Number.isFinite(value) || value < 0 || value > 1) throw new UsageError('--min-visible must be a number in [0, 1]');
+    options.minVisible = value;
+  }
+  if (flags['max-residual'] !== undefined) {
+    const value = Number(flags['max-residual']);
+    if (!Number.isFinite(value) || value <= 0 || value > 1) throw new UsageError('--max-residual must be a number in (0, 1]');
+    options.maxResidual = value;
+  }
+  if (flags.passes !== undefined) {
+    const value = Number(flags.passes);
+    if (!Number.isInteger(value) || value < 1 || value > 8) throw new UsageError('--passes must be a whole number in 1..8');
+    options.passes = value;
+  }
+  if (flags['anchor-residual'] !== undefined) {
+    const value = Number(flags['anchor-residual']);
+    if (!Number.isFinite(value) || value <= 0 || value > 1) throw new UsageError('--anchor-residual must be a number in (0, 1]');
+    options.anchorMaxResidual = value;
+  }
+  const scale = readRange(flags, 'scale');
+  if (scale) {
+    if (scale.low <= 0) throw new UsageError('--scale minimum must be greater than zero');
+    options.scale = { min: scale.low, max: scale.high };
+  }
+  const rotation = readRange(flags, 'rotation');
+  if (rotation) {
+    if (rotation.high - rotation.low > 360) throw new UsageError('--rotation cannot span more than a full turn');
+    options.rotation = { minDeg: rotation.low, maxDeg: rotation.high };
+  }
+
+  console.log('rigc chainfit');
+  const report = estimateChainFit(options);
+  for (const line of chainFitLines(report)) console.log(line);
+
+  const target = resolve(flags.out ?? DEFAULT_CHAINFIT_OUT);
+  const out = existsSync(target) && statSync(target).isDirectory() ? join(target, DEFAULT_CHAINFIT_OUT) : target;
+  writeJson(out, report);
+}
+
 // ---------------------------------------------------------------------------
 // choosing between results — vote
 // ---------------------------------------------------------------------------
@@ -1870,6 +1976,27 @@ const FLAG_MEANINGS: Record<string, string> = {
   'max-residual':
     `above this residual a placement is refused by name instead of reported flat (default ${DEFAULT_MAX_RESIDUAL}); ` +
     'it is a reporting threshold, not a pass bar',
+  anchor:
+    'a `rigc pose` report for THIS frame, whose confident placements become the anchors the chains hang off ' +
+    '(default: run that pass internally over exactly the parts the candidate draws)',
+  hinge:
+    `the window each child bone's local rotation is searched over, in Spine degrees about its setup value ` +
+    `(default \`${DEFAULT_HINGE_MIN},${DEFAULT_HINGE_MAX}\`, a full turn — one degree of freedom is cheap enough not ` +
+    'to risk a window that does not contain the truth)',
+  stretch:
+    'also search a uniform scale on every bone, over this ratio either way (e.g. 1.25). Without it the stretch ' +
+    "degree of freedom is searched only where the candidate's own animations key a `scale` timeline, because a rig " +
+    'that never scales a bone is a rig saying that bone does not stretch',
+  'min-visible':
+    `below this share of a part surviving the parts drawn over it, the placement is refused by name instead of ` +
+    `reported flat (default ${DEFAULT_MIN_VISIBLE}); the best one found is still printed, and it is a reporting ` +
+    'threshold, not a pass bar',
+  passes:
+    `how many times the occluder masks are rebuilt from the answers and the fit rerun (default ${DEFAULT_PASSES}); ` +
+    "pass 1 freezes each part's visible set where the RIG predicts it, later passes where the last one landed",
+  'anchor-residual':
+    `the residual a \`pose\` placement must be within to anchor a chain (default ${ANCHOR_MAX_RESIDUAL}, with ` +
+    `unexplained ≤ ${ANCHOR_MAX_UNEXPLAINED} and unambiguous — the 2026-09-03 measurement run's own clean-frame criterion)`,
   animation: 'which animation to show; the default is every one for `render` and the first for `preview`',
   max: 'longest side of a rendered frame, in pixels (default 256)',
   record: 'a saved vote to check against its ballot and append to the ledger, instead of writing a ballot',
@@ -1908,6 +2035,12 @@ const FLAG_VALUES: Record<string, string> = {
   scale: '<min,max>',
   rotation: '<min,max>',
   'max-residual': '<0..1>',
+  anchor: '<pose.json>',
+  hinge: '<min,max>',
+  stretch: '<ratio>',
+  'min-visible': '<0..1>',
+  passes: '<n>',
+  'anchor-residual': '<0..1>',
   animation: '<name>',
   max: '<px>',
   record: '<result.json>',
@@ -2044,6 +2177,50 @@ const COMMANDS: CommandDoc[] = [
       },
     },
   },
+  {
+    name: 'chainfit',
+    usage: [
+      `rigc chainfit --candidate <dir | skeleton.json> --images <dir> --frame <path> [--anchor pose.json] [--out ${DEFAULT_CHAINFIT_OUT}]`,
+    ],
+    flags: [
+      'candidate',
+      'images',
+      'frame',
+      'anchor',
+      'hinge',
+      'stretch',
+      'min-visible',
+      'max-residual',
+      'passes',
+      'anchor-residual',
+      'scale',
+      'rotation',
+      'out',
+    ],
+    overrides: {
+      images: {
+        value: '<dir>',
+        meaning:
+          "where each attachment's image name resolves to a loose PNG. ⚠️ NOT a part list the way `pose --images` " +
+          'is one — the candidate decides what the parts are, so extra PNGs in here are simply unused and a name ' +
+          'the directory lacks is refused by name',
+      },
+      scale: {
+        meaning:
+          'the scale window the INTERNAL anchor pass searches, as frame pixels per part pixel (default ' +
+          `\`${DEFAULT_SCALE_MIN},${DEFAULT_SCALE_MAX}\`). Refused together with --anchor, which means there is no internal pass`,
+      },
+      rotation: {
+        meaning:
+          'the rotation window the INTERNAL anchor pass searches, in screen degrees (default `-180,180`). Refused ' +
+          'together with --anchor — the chains\' own window is --hinge',
+      },
+      out: {
+        value: '<file>',
+        meaning: `the .json report to write (default \`${DEFAULT_CHAINFIT_OUT}\`); a directory means "the default name in here"`,
+      },
+    },
+  },
   {
     name: 'vote',
     usage: [
@@ -2131,6 +2308,19 @@ const USAGE = [
   'canvas cannot contain and a part whose rotation is a free degree of freedom are each',
   'named as such. See `rigc pose --help`.',
   '',
+  'chainfit reads the half of that picture pose refuses. It is the same question with',
+  'one more input — the candidate rig — and that input buys two things: draw order, so',
+  'the pixels another part covers are EXCLUDED from a part\'s residual instead of',
+  'charged to it, and hierarchy, so a child of a placed bone is searched over one hinge',
+  'instead of four degrees of freedom:',
+  '  rigc chainfit --candidate build/ --images parts/ --frame poseA.png',
+  'Every residual is over the part\'s VISIBLE pixels and comes with the `visibleShare` it',
+  'was computed on, so a mostly-hidden answer carries its own uncertainty. It grades',
+  'nothing either: a part too far behind the others is refused by the visibility floor,',
+  'a limb with no trusted part on it or above it is refused `no-anchor`, and two hinge',
+  'answers that explain the picture equally well are both reported. See',
+  '`rigc chainfit --help`.',
+  '',
   'vote is the same page with two to four builds in it and an answer coming back:',
   '  rigc vote --candidate <build A> --candidate <build B>   ballot.html, panes labelled A and B',
   '  rigc vote --record vote-<id>.json --ballot ballot.html  check it, append it to votes.jsonl',
@@ -2177,6 +2367,7 @@ try {
   else if (command === 'render') cmdRender(flags);
   else if (command === 'preview') cmdPreview(flags);
   else if (command === 'pose') cmdPose(flags);
+  else if (command === 'chainfit') cmdChainFit(flags);
   else if (command === 'vote') cmdVote(flags, lists.candidate ?? []);
 } catch (err) {
   if (err instanceof UsageError) {
@@ -2208,5 +2399,12 @@ try {
     console.error(`rigc pose: ${err.message}`);
     process.exit(2);
   }
+  // Same kind as a PoseError, and printed the same way for the same reason: the
+  // messages name a path, a bone or an attachment, and reprinting the whole
+  // usage under them buries the one line that says what to change.
+  if (err instanceof ChainFitError) {
+    console.error(`rigc chainfit: ${err.message}`);
+    process.exit(2);
+  }
   throw err;
 }

package/docs/AUTHORING.md

@@ -81,6 +81,14 @@ bun install                                   # once
 bun cli.ts pose --images path/to/parts --frame path/to/poseA.png --out poseA.json
 #   ↳ one entry per part PNG: where it sits, how confident that is, and where two
 #     answers are equally good — §11
+#
+# …and once a candidate EXISTS, the half of that picture pose refuses — the parts
+# another part is drawn over — is readable through the rig's own draw order and
+# hierarchy. This one runs after a first build, not before it:
+bun cli.ts chainfit --candidate path/to/spine --images path/to/parts \
+                    --frame path/to/poseA.png --out chainfitA.json
+#   ↳ one entry per drawn slot: where it sits, over how much of it that was
+#     measured, and the `rotate` key value it implies — §12
 
 bun cli.ts build \
   --rig    path/to/my.rig.json \
@@ -143,19 +151,25 @@ What the flags mean:
 | `--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** |
 | `--padding` | `build --pack` only: the gutter each region reserves on every side (default `2`), filled by extending the region's own edge pixels outwards. `0` is not a legal-but-tight choice, it is bleed — **§0.1** |
 | `--atlas-in` | `build` only: resolve every part against the **regions of a pre-packed `.atlas`** instead of against loose PNGs. Region geometry is read from the file and sizes are descaled by the page's `scale:`; the atlas is re-emitted into `--out`, re-anchored — **§0.2** |
-| `--images` | where the rig spec's `image` names resolve (overrides the rig's own `images` field, and is relative to your working directory). For `pose` it is the directory of **loose part PNGs to place** — every `.png` in it is a part, in name order |
+| `--images` | where the rig spec's `image` names resolve (overrides the rig's own `images` field, and is relative to your working directory). For `pose` it is the directory of **loose part PNGs to place** — every `.png` in it is a part, in name order. For `chainfit` it is only where each attachment's image name **resolves**: the candidate decides what the parts are, so extra PNGs are unused and a missing name is refused by name (§12.3) |
 | `--manifest` | a cut manifest. Only for a rig with **measured art** behind it; a foreign skeleton has none |
 | `--profile` | `spine` = the 22 validity rules (**the default**) · `spine-html` = all 36, opt-in |
-| `--candidate` | `check`, `bench`, `render`, `preview` 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 |
+| `--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 |
 | `--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 |
 | `--again` | `vote --record` only: record a second vote on a ballot the ledger already has. Without it a repeat is refused by name rather than doubled |
-| `--frame` | `pose` only: one pose frame — the picture to read part placements out of. One frame per call; several key poses are several calls, and correlating them is yours (§11) |
-| `--scale` | `pose` only: the scale window to search, as **frame pixels per part pixel**, `<min>,<max>` (default `0.5,2`). The report states what it searched, and a window that does not contain the truth does not reliably refuse — §11 |
-| `--rotation` | `pose` only: the rotation window to search, in screen degrees, `<min>,<max>` (default `-180,180`, a full turn). Narrow it when you know the art is upright |
-| `--max-residual` | `pose` only: above this residual a placement is **refused by name** instead of reported flat (default `0.25`). A reporting threshold, not a pass bar — the placement is still in the JSON |
+| `--frame` | `pose` and `chainfit`: one pose frame — the picture to read part placements out of. One frame per call; several key poses are several calls, and correlating them is yours (§11) |
+| `--scale` | the scale window to search, as **frame pixels per part pixel**, `<min>,<max>` (default `0.5,2`). The report states what it searched, and a window that does not contain the truth does not reliably refuse — §11. For `chainfit` it sizes the **internal anchor pass** and is refused beside `--anchor` — §12.4 |
+| `--rotation` | the rotation window to search, in screen degrees, `<min>,<max>` (default `-180,180`, a full turn). Narrow it when you know the art is upright. For `chainfit`, again the internal anchor pass — the chains' own window is `--hinge` |
+| `--max-residual` | `pose` and `chainfit`: above this residual a placement is **refused by name** instead of reported flat (default `0.25`). A reporting threshold, not a pass bar — the placement is still in the JSON |
+| `--anchor` | `chainfit` only: a `rigc pose` report for **this** frame, whose confident placements become the anchors the chains hang off. Without it that pass runs internally — §12.2 |
+| `--hinge` | `chainfit` only: the window each child bone's local rotation is searched over, in **Spine** degrees about its setup value, `<min>,<max>` (default `-180,180`) — §12.4 |
+| `--stretch` | `chainfit` only: also search a uniform bone scale, this ratio either way. Without it, stretch is free only where the candidate's own animations key a `scale` timeline — §12.4 |
+| `--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 |
 
 `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
@@ -366,6 +380,17 @@ bun cli.ts pose     --images path/to/parts --frame poseA.png [--out pose.json]
   a given condition, not a target, and the residual it reports is how far to trust
   a placement rather than how good the placement is. Reach for it the moment a
   request arrives as *"make it go from this picture to this one"*. **§11.**
+- 🧩 **`chainfit` is that same reading of an input, through a rig you already
+  have.** `pose` is handed nothing but the parts and the picture, so on a dense
+  figure it refuses the half another part is drawn over — the residual it would
+  report there is measuring the occluder. Give the same frame a **candidate** and
+  two things become available that `pose` structurally cannot have: a draw order,
+  so the pixels a later part covers are taken OUT of the objective instead of
+  charged to it, and a hierarchy, so a child of a placed bone is searched over one
+  hinge about its own pivot rather than over four degrees of freedom. It reports the
+  `rotate` key value each answer implies, and the share of the part that answer was
+  actually measured on. Reach for it after a first build, when the frame still has
+  parts in it you cannot read. **§12.**
 - 🗳️ **`vote` is `preview` with more than one candidate in it and an answer
   coming back**, and it is the one step of this loop you cannot run yourself.
   Reach for it where the instruments have run out: two builds that `check` and
@@ -3871,3 +3896,154 @@ and threshold that was applied), and `caveats`.
 - **One frame per call.** Several key poses are several calls, and correlating A
   with B — which placement of a repeated part belongs to which limb, across two
   frames — is the authoring job, not this tool's.
+
+## 12. Reading the half of that picture `pose` refuses — `rigc chainfit`
+
+```bash
+bun cli.ts chainfit --candidate path/to/spine --images path/to/parts \
+                    --frame path/to/poseA.png [--anchor poseA.json] [--out chainfit.json]
+```
+
+§11 ends on a limitation it is honest about and cannot fix: *"a part drawn behind
+another has the occluder's pixels where its own should be, so its residual rises
+**at the correct placement**"*. On a ball that costs nothing. On a figure it costs
+half the figure — the far arm behind the torso, both thighs behind the torso and
+each other, the feet, the fists, whatever the hands hold.
+
+This is the same question with **one more input: your candidate rig**. That input
+is what makes the difference measurable rather than a caveat, and it buys exactly
+two things.
+
+- **Draw order**, so occlusion can be taken out of the arithmetic instead of
+  apologised for. The parts drawn after a part are what covers it, and the pixels
+  they cover are **excluded** from that part's objective rather than charged to it.
+  Every residual here is over the part's **visible** pixels, and every one comes
+  with the `visibleShare` it was computed on.
+- **Hierarchy and attachment geometry**, so the search collapses. A child bone
+  whose parent is already placed does not have four degrees of freedom: the rig
+  fixes its pivot, so what is left is **one hinge** about that pivot — plus a
+  stretch, and only where your own timelines say the rig leaves scale free. One
+  degree of freedom is also what removes the ambiguity §11 has to report: two
+  identical limbs stop being two equal answers once each of them hangs off a
+  different placed shoulder.
+
+### 12.1 Which one to reach for
+
+| The question | The command |
+| --- | --- |
+| *"Where does each of these loose PNGs sit in this picture?"* — you have parts and a picture and nothing else | **`pose`** (§11) |
+| *"Where does this rig's own `rear-upper-arm` sit in this picture?"* — you already have a compiled candidate | **`chainfit`** |
+| A part that is big, distinctive and **unoccluded** | either; they agree, and `pose` needs no rig |
+| A part another part is drawn over | **`chainfit`** — this is the whole reason it exists |
+| A part that appears **twice** (two arms, two shins) | **`chainfit`**, if the two hang off different bones. `pose` is right to call it ambiguous and cannot do better |
+| You have **no rig yet** | **`pose`**. There is nothing to chain from, and inventing one would be a rig you then have to un-invent |
+| Your rig's joint offsets are **guesses** | **`pose` first.** Every hinge here turns about a pivot your rig declares; a wrong joint moves every answer below it. `pivotDisagreementPx` is what says so |
+
+The normal order is **`pose` → author → `chainfit`**: read what you can with no
+rig, write a first rig from it, then read the rest of the frame through that rig.
+And `chainfit` runs `pose` for you unless you hand it one — see `--anchor`.
+
+### 12.2 The anchor, and why the walk only goes outward
+
+A chain needs a trunk. `chainfit` takes its anchors from a **`rigc pose` report
+for the same frame** — `--anchor poseA.json` — and without one it runs that pass
+internally, over exactly the parts your candidate draws. A part becomes an anchor
+when `pose` came back **unambiguous** with `residual ≤ 0.16` and
+`unexplained ≤ 0.45`; those two numbers are `--anchor-residual` and a reported
+field, and they are the 2026-09-03 measurement run's own *clean frame* criterion
+rather than a line invented here.
+
+An anchored part fixes its **whole bone** — four numbers read off the picture for
+the four a similarity has — and every descendant then follows from the rig. A bone
+**above** an anchor does not: recovering it would need to know what the link
+between them did, and that is precisely the unknown the anchor does not carry.
+
+⚠️ **So a limb with no trusted part on it or above it is refused `no-anchor`**, not
+guessed at from a cousin. If a whole side of your figure comes back that way, the
+repair is upstream: give `pose` a better frame, pin its `--scale`, or loosen
+`--anchor-residual` deliberately and read the consequences.
+
+### 12.3 What the report adds to a `pose` report
+
+The coordinate contract is **identical** to §11.2 — frame pixels, y down, origin
+top-left, `(x, y)` where the part image's own centre lands, `rotationDeg` in screen
+degrees — so the two reports are readable side by side. On top of that, per
+placement:
+
+| Field | Meaning |
+| --- | --- |
+| `residual` | the same objective as §11, over the part's **visible** pixels only: covered pixels are dropped from both sums rather than charged. **Not the same number as `pose`'s on an occluded part**, and never to be read without the next field |
+| `visibleShare` | the share of the part's own alpha weight the residual was computed on. A low residual on a `0.08` share is a confident statement about a sliver |
+| `scoredPixels` | how many part pixels that share actually is |
+| `visibleShareAtFit` | the share recomputed **where the answer landed**, rather than where the visible set was frozen. Far from `visibleShare` means the fit moved out of its own measurement; `--passes` is the repair |
+| `hingeDeg` | ⭐ the searched degree of freedom, in **Spine** degrees relative to the bone's setup rotation — **the value a `rotate` key would carry**. `null` on an anchor whose own parent is unplaced, where the quantity does not exist |
+| `localRotationDeg` | the bone's local rotation this implies, Spine degrees. The other half of the same answer |
+| `stretch` | the uniform scale on the bone; `1` where that DOF was not free |
+| `unexplained`, `offCanvas`, `footprint`, `bbox` | as §11.3, with `residual` and `unexplained` over the visible set and `offCanvas` over the whole part |
+
+And per part:
+
+| Field | Meaning |
+| --- | --- |
+| `role` | `anchor` (taken from the anchor pass, not re-fitted), `chain` (fitted through the rig), `unplaced` |
+| — | ⭐ **A refused ANCHOR is not a contradiction, and it is the most useful row in the table.** The anchor pass judged that placement over the part's *whole* footprint — all `pose` can see, and blind to what covers it — while this instrument has just measured how much of the part is visible at all. Both readings are true. A refused anchor means *the placement may well be right and the confirmation is missing*, and every part whose `anchoredTo` names that bone rests on it. Measured on the 2026-09-03 corpus, `rear-bracer` clears `pose`'s criterion on 81 of 147 frames at a median visible share of **0.1%** — suppressing the refusal there was tried and prints that as READ |
+| — | The **other** parts on an anchored bone are refused on their own numbers too, and there they mean something different again: their placement is the **rig's** prediction from that anchor, so their residual is a measurement of the rig (a goggle plate that will not sit on the head it is parented to shows up exactly here) |
+| `bone` | the bone this hangs off: its `parent`, its `setupRotationDeg`, its `depth` in links from the anchor, `anchoredTo`, the `dof` searched, the `window` taken, the other parts `sharedWith` it on that bone, and `carriedBones` |
+| `bone.dof.pivotFree` | your candidate keys a `translate` timeline on this bone, so the arc this answer sits on has a centre the rig itself moves. The placement is still read off pixels; `localRotationDeg` alone will not reproduce it |
+| `bone.carriedBones` | bones between the anchor and here that carry nothing scoreable. Their hinge could not be fitted, their setup rotation was carried through, and every number below them inherits that |
+| `bone.pivotDisagreementPx` | anchored bones only: how far the chain's own prediction of this bone's pivot is from where the anchor put it. **This is the one direct measurement of your rig against the picture** — a large value says the joint offset you declared is not the joint the frame shows |
+| `anchorVerdict` | what the anchor pass made of this same part: `residual`, `unexplained`, `ambiguous`, `eligible`. ⭐ `eligible: false` beside a `chain` placement is **a part the chain bought** |
+| `refusal` | `{ reason, detail }` or `null`. Reasons: `occluded`, `no-match`, `no-anchor`, `empty-part`, `no-part-image`, `unsupported-geometry` |
+
+`⚠️ --images is not a part list here.` For `pose` every `.png` in the directory is
+a part; for `chainfit` **the candidate decides what the parts are** and the
+directory is only where each attachment's image name resolves. Extra PNGs in it are
+simply unused; a name the directory lacks is refused `no-part-image` by name.
+
+### 12.4 The flags that steer it
+
+| Flag | What it does |
+| --- | --- |
+| `--anchor <pose.json>` | use this `rigc pose` report instead of running one. Refused together with `--scale` / `--rotation`, which size the internal pass that then does not happen |
+| `--atlas` | **refused by name.** Every other `--candidate` command takes it, so trying it here is reasonable — but the part art comes from `--images` and the skeleton is all this needs of the candidate, so a flag that silently did nothing would be worse than one that says why |
+| `--hinge <min,max>` | the window each child's local rotation is searched over, in Spine degrees about its setup value. Default `-180,180` — **a full turn, on purpose**: one degree of freedom is cheap enough to sweep exhaustively, and §11.4's warning about a window that does not contain the truth applies here too |
+| `--stretch <ratio>` | also search a uniform bone scale, this ratio either way. Without it, stretch is searched **only where your own animations key a `scale` timeline on that bone** — a rig that never scales a bone is a rig saying that bone does not stretch |
+| `--min-visible <0..1>` | below this visible share a placement is refused `occluded` instead of reported flat (default `0.25`). A reporting threshold, not a pass bar; the placement is still in the JSON |
+| `--max-residual <0..1>` | as §11, over the visible pixels (default `0.25`) |
+| `--passes <n>` | how many times the masks are rebuilt from the answers and the fit rerun (default `2`) |
+| `--anchor-residual <0..1>` | the residual a `pose` placement must be within to anchor (default `0.16`) |
+| `--scale`, `--rotation` | passed to the **internal anchor pass**, meaning exactly what they mean to `pose` |
+
+### 12.5 What it cannot see — read this before using the numbers
+
+- 🚨 **The occlusion is your candidate's, and so is the geometry.** A wrong draw
+  order masks the wrong pixels. A joint offset the rig gets wrong moves the pivot
+  every hinge below it turns about. An answer here is only as good as the structure
+  it was read through, and that is a different failure mode from anything in §11 —
+  `pose` can be wrong about a part, `chainfit` can be wrong about a *limb*, in a
+  way that looks internally consistent. `pivotDisagreementPx` and
+  `bone.carriedBones` are the two fields that expose it.
+- ⚠️ **`residual` here and `residual` in a `pose` report are not the same
+  measurement on an occluded part**, by construction: one drops the covered pixels
+  and the other charges them. Do not put them in one column. What *is* comparable
+  is each against its own `visibleShare` / `unexplained`.
+- ⚠️ **Setup draw order, on one frame.** A `drawOrder` timeline reorders your slots
+  at runtime and this cannot know the time, so a candidate that has one is masked in
+  the order its setup pose declares. The report says so in `caveats` when it finds
+  one.
+- ⚠️ **The hinge is searched; the pivot is not.** Nothing here searches a bone's
+  translation, so a bone you key `translate` on is reported `pivotFree` rather than
+  solved.
+- **A constraint moves bones after their local transforms compose.** With IK,
+  transform, path or physics constraints in the candidate, a fitted
+  `localRotationDeg` is still a placement but not necessarily a value you can key
+  and reproduce. The report lists the constraints it found.
+- **Shear, a non-uniform scale and any `inherit` but `normal`** are refused
+  `unsupported-geometry` by bone, and a non-region attachment by attachment.
+  Composing through them would put a plausible number on geometry this instrument
+  does not model — the same shape of wrongness as a search window that excludes the
+  truth.
+- **Nothing here grades anything either.** Same phase as §11, same reason: the pose
+  is a given condition and once your spec states it there is nothing left to be
+  close to. Every threshold in the report is a reporting threshold. There is no pass
+  bar and `caveats` says so in the file.

package/docs/INGEST.md

@@ -1069,6 +1069,13 @@ rigc pose --images examples/3-timing-and-spacing/images \
 PNG where you expected several is the tell, and the `..    parts` line prints the
 count. AUTHORING §11.4 is the rest of what that command cannot see.
 
+⭐ **And on ingest work you usually have the thing `pose` is missing.** A skeleton you
+are transcribing IS a compiled candidate, so the parts `pose` refuses because
+something is drawn over them are readable through its own draw order and hierarchy —
+`rigc chainfit --candidate <that skeleton> --images <dir> --frame <png>`, AUTHORING
+§12. It is the natural second pass here: `pose` reads the trunk of a foreign figure,
+`chainfit` reads the limbs it hides, and both report placements rather than grades.
+
 📎 To be exact about what is missing: rigc *can* lift a region's drawing back off a
 page — `extractRegion` does it, and the contour mesh generator uses it under
 `--atlas-in` — so what is absent is a **command**, not the capability. It refuses by

package/docs/MOTION.md

@@ -22,6 +22,9 @@ toolchain and this page does not invent one.
 - What the Spine editor does when nobody tells it otherwise: **AUTHORING §10**
 - Reading a pose out of a picture — the instrument this recipe consumes:
   **AUTHORING §11**
+- The parts of that picture `pose` refuses because something is drawn over them,
+  once a first candidate exists: **AUTHORING §12** (`rigc chainfit`). It reports the
+  `rotate` key value each answer implies, which is the form this recipe wants them in
 - If what you were handed is a **compiled skeleton** rather than loose parts — reading
   it, transcribing it into specs, re-pivoting it, extending it with an animation:
   [INGEST.md](INGEST.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spine-rigc",
-  "version": "0.11.0",
+  "version": "0.12.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": {