spine-rigc 0.22.2 → 0.24.0

package/README.md

@@ -352,6 +352,16 @@ directories makes the result a frame set like any other — the world box every
 frame is a picture of. `--animation <name>` narrows it to one, `--fps` and
 `--max` change the rate and the frame size.
 
+> 🚨 **`--skin <name>` if your rig has more than one.** With no `--skin` no skin
+> is set at all, so every slot resolves through the **default** skin alone — and
+> a slot whose art lives only in a named skin draws *nothing*. That is not a
+> quirk of `render`: `check` compares `render`'s frames, so a multi-skin rig
+> checked with no skin compares blank against blank and reports a perfect
+> `0.0000` about art nobody drew. `render --skin` records the name in
+> `frames.json`, `check --skin` poses the candidate under it, and a candidate
+> scored against frames rendered under a *different* skin is refused by name
+> rather than measured.
+
 **`preview`** writes a single self-contained `.html`: your skeleton, your atlas
 and every page's PNG bytes are embedded in it as data URIs, and it plays them in
 the **official [Spine Web Player](https://esotericsoftware.com/spine-player)**.
@@ -493,6 +503,7 @@ commands take it and what its default is.
 | `build … --pack` | the same build with every part arranged onto **shared** atlas pages, written into `--out` — losslessly, and gated a second time as the pair that ships. `--page-size` and `--padding` tune it |
 | `build … --atlas-in <file.atlas>` | the same build with every part resolved to a **region of an existing pack** instead of a loose PNG; a name the atlas lacks, a size the spec disagrees with or a rectangle off its page is refused by name |
 | `validate <dir>` | re-gates artifacts already on disk |
+| `ingest <skeleton.json> --out <dir>` | `build` run backwards: reads a Spine 4.3 skeleton and writes the rig spec and motion spec that **rebuild it**, plus a findings report naming everything it could not carry. `--stage x,y,w,h` supplies the one value a skeleton does not hold, and `--images <dir>` writes the spec's own images directory — the opposite direction from `build --images`, which overrides it — so the rebuild carries no flag at all |
 | `explain --rig … --motion …` | the compiled rig as a table — every bone with its resolved parent, the slots in draw order, every timeline key by key. Writes nothing. What to reach for when a rig compiles and still looks wrong |
 | `render --candidate <dir>` | PNG frames plus a contact sheet, in `render/` |
 | `preview --candidate <dir>` | one self-contained `.html` that plays it |
@@ -521,6 +532,71 @@ relative to the `cuts.json` file itself, so the table lives with the project tha
 the art. Its shape is under
 [Usage](https://github.com/firejune/rigc/blob/main/docs/BENCHMARK.md#usage).
 
+### Starting from a skeleton you already have
+
+`rigc ingest` reads a Spine 4.3 `skeleton.json` and writes the two spec files that
+rebuild it. It is the only command that runs against `build`'s direction, and the
+only one whose contract is an equality rather than a rulebook:
+
+```bash
+rigc ingest hero.json --out specs/ --stage 0,0,1024,768 --images parts/
+rigc build --rig specs/rig.json --motion specs/motion.json --out build/
+rigc diff build/skeleton.json hero.json
+```
+
+`--images parts/` is what makes the second line carry no flag: it writes the spec's
+own `images` directory, spelled from `--out`, so the specs are self-contained from
+there on. Leave it off and the `image` names resolve against `specs/` itself, which
+holds no art — every rebuild then has to repeat `build --images parts/`.
+
+**`build(ingest(x))` is `x`.** Over the eleven rigs this repository builds — the seven
+gallery examples, the three generated probes and a coverage probe written for the
+purpose — the rebuilt `skeleton.json` is byte for byte the file the decompiler read,
+and `bun run selftest` holds it there on every run. The atlas is held to a weaker
+claim on purpose, and the weakening is measured rather than assumed: it comes back
+equal as a **multiset of region blocks**, because the order the pages are collected in
+is in no field of the skeleton.
+
+**And over twelve skeletons nobody here wrote.** The same run ingests every editor
+export in the fetched example corpus, rebuilds it through the pack beside it and
+`diff`s the result against the source: **12 of 12, no blockers, 1.000 on every measure
+the report carries.** Byte identity is not the claim there and the reason is the input
+rather than the round trip — an editor header carries `hash` and `audio`, which the rig
+spec has no field for — so the contract is the structural one `diff` measures.
+[INGEST.md §2.3](docs/INGEST.md) has the three kinds of difference that remain, with
+what each is worth.
+
+**What it reads is skeleton JSON and nothing else** — no `.spine` project, no binary
+`.skel`, no atlas, no art. So it never invents, and the things it cannot get out of
+the file are **findings** with codes rather than plausible values: a construct the
+spec format cannot hold (`linkedmesh`, `point`, a `sequence` block, an unknown field
+on a bone, slot or constraint) is a blocker, the command exits non-zero, and both
+specs are still written — a spec plus a list of what is missing from it beats no spec.
+One thing it drops on purpose and says so: a path attachment's `lengths`, which is
+`PathConstraint`'s own measurement and which rigc re-measures.
+
+⚠️ **Two values are not in a skeleton at all.**
+
+- **The stage.** `skeleton.width`/`height`: rigc always writes one, and a skeleton that
+  carries none is refused by name unless `--stage x,y,w,h` supplies it. It is not
+  derivable — posing the rig gives the *animated* extent, which is a different number
+  from the setup box. ⚠️ This said *"an editor export carries none"* until #594 measured
+  it: **all twelve exports in the example corpus carry a stage** and none of them needs
+  the flag. It is still the value that costs least to get wrong, because `diff` reports
+  the box and gates nothing on it.
+- **An animation's duration.** The format has no such field. The largest key time is
+  the only derivable answer and it is what a runtime plays to; it is wrong for an
+  animation that holds its last pose past its last key, so it is recorded as a finding
+  on every animation rather than chosen quietly.
+
+Both specs carry a `note` that `ingest` writes itself, saying the file is decompiled
+and naming the skeleton it came from — because a decompiled spec is indistinguishable
+from an authored one by inspection, every gate here calls it green (it *is* green),
+and no gate can catch a missing note.
+
+[docs/INGEST.md](docs/INGEST.md) is the whole page on working from a file you were
+handed; [docs/AUTHORING.md](docs/AUTHORING.md) §0.3 is the loop.
+
 ### The editor round trip — for a licence holder, never in CI
 
 `tools/editor_roundtrip.ts` drives the loop the output's whole premise rests on:
@@ -534,7 +610,10 @@ bun tools/editor_roundtrip.ts --build build/ --editor /Applications/Spine.app/Co
 
 It prints the import and export exit codes, the validator's verdict on the
 export, every `diff` measure that moved, `check`'s mean MAE and worst drift per
-animation, and a field-by-field list of what the editor rewrote. On its first
+animation **for each skin the build declares** — one render-and-check block per
+skin, with a per-skin roll-up under them, because a rig's contested art lives in
+its named skins and a single un-skinned check draws none of it — and a
+field-by-field list of what the editor rewrote. On its first
 run it found three emitter defects — [#368](https://github.com/firejune/rigc/issues/368),
 [#369](https://github.com/firejune/rigc/issues/369),
 [#370](https://github.com/firejune/rigc/issues/370) — and then showed that a

package/cli.ts

@@ -57,7 +57,7 @@ import {
   type BoneDistReport,
 } from './src/bonedist.ts';
 import { checkAgainstFrames, checkLines, CheckError, type CheckOptions, type CheckReport } from './src/check.ts';
-import { compile, CompileError, type CompileOptions } from './src/compile.ts';
+import { compile, CompileError, relativeImagesPath, type CompileOptions } from './src/compile.ts';
 import {
   skeletonDataFromText,
   surveyDeformKeys,
@@ -67,6 +67,7 @@ import {
   type DeformSpan,
 } from './src/deformmeasure.ts';
 import { diffLines, diffSkeletons, reportedFigures, sectionFigures, type DiffReport } from './src/diff.ts';
+import { ingest, type IngestFindingKind, type IngestStage } from './src/ingest.ts';
 import { copyAtlasImages } from './src/emit.ts';
 import { DEFAULT_PADDING, DEFAULT_PAGE_SIZE, packAtlas } from './src/atlas.ts';
 import { parseJsonWithPosition } from './src/json-position.ts';
@@ -1415,8 +1416,8 @@ function cmdDiff(flags: Record<string, string>, positional: string[]): void {
  */
 function readCheckFlags(
   flags: Record<string, string>,
-): Pick<CheckOptions, 'fps' | 'viewport' | 'as' | 'framing' | 'textureFrom'> {
-  const out: Pick<CheckOptions, 'fps' | 'viewport' | 'as' | 'framing' | 'textureFrom'> = {};
+): Pick<CheckOptions, 'fps' | 'viewport' | 'as' | 'framing' | 'textureFrom' | 'skin'> {
+  const out: Pick<CheckOptions, 'fps' | 'viewport' | 'as' | 'framing' | 'textureFrom' | 'skin'> = {};
   if (flags.framing !== undefined) {
     if (flags.framing !== 'per-shot' && flags.framing !== 'shared') {
       throw new UsageError('--framing takes per-shot (the default) or shared');
@@ -1437,6 +1438,10 @@ function readCheckFlags(
     out.viewport = { x: parts[0], y: parts[1], width: parts[2], height: parts[3] };
   }
   if (flags.as !== undefined) out.as = flags.as;
+  // The name is not checked against the candidate here: `check` owns that
+  // refusal, because it is the side that has the skeleton open and can list the
+  // skins it declares. `render` checks its own for the same reason.
+  if (flags.skin !== undefined) out.skin = flags.skin;
   if (flags['texture-from'] !== undefined) {
     const path = resolve(flags['texture-from']);
     if (!existsSync(path)) {
@@ -1528,6 +1533,29 @@ function readAnimationFlag(flags: Record<string, string>, available: string[]):
   return name;
 }
 
+/**
+ * `--skin`, checked against what the skeleton actually declares.
+ *
+ * ⭐ Absent is not `default`: it is "set no skin at all", which is what every
+ * render did before issue #571 and what `spine-core` starts a skeleton in. The
+ * distinction is the whole of the default path's byte-identity — see
+ * `FramesSidecar.skin`.
+ *
+ * The miss is refused by name with the declared names beside it, the way
+ * `--animation` is: a skin name is the one place a typo draws a whole rig's
+ * worth of the wrong art and reports a number about it.
+ */
+function readSkinFlag(flags: Record<string, string>, declared: string[]): string | undefined {
+  const name = flags.skin;
+  if (name === undefined) return undefined;
+  if (!declared.includes(name)) {
+    throw new UsageError(
+      `no skin ${JSON.stringify(name)} in this skeleton; it declares [${declared.join(', ') || 'none'}]`,
+    );
+  }
+  return name;
+}
+
 function readPositiveNumber(flags: Record<string, string>, key: string, fallback: number, least: number): number {
   const raw = flags[key];
   if (raw === undefined) return fallback;
@@ -1555,11 +1583,20 @@ function cmdRender(flags: Record<string, string>): void {
   console.log(`  ..    atlas    ${atlasPath}`);
   const { data, pages } = loadPosable(skeletonPath, atlasPath, atlasDir);
   const only = readAnimationFlag(flags, data.animations.map((a) => a.name));
-
-  const viewport = framingViewport(data, maxSide);
+  const skin = readSkinFlag(flags, data.skins.map((s) => s.name));
+  // One object, so the framing and the frames cannot be posed under two
+  // different skins — which would frame one shot with another shot's box.
+  // Not annotated `PoseOptions`: that name is `src/pose.ts`'s in this file, and
+  // `src/render.ts` has one of its own. The inferred shape is the render one.
+  const pose = skin === undefined ? undefined : { skin };
+  if (skin !== undefined) console.log(`  ..    skin     ${skin}`);
+
+  const viewport = framingViewport(data, maxSide, pose);
   if (!viewport) {
     throw new UsageError(
-      `${skeletonPath} posed no drawable attachment in any animation or in its setup pose — there is nothing to draw`,
+      `${skeletonPath} posed no drawable attachment in any animation or in its setup pose${
+        skin === undefined ? '' : ` under skin ${JSON.stringify(skin)}`
+      } — there is nothing to draw`,
     );
   }
 
@@ -1567,7 +1604,7 @@ function cmdRender(flags: Record<string, string>): void {
   // setup-pose frame under the reserved name. Narrowing to one animation reuses
   // the same sampler rather than a second path through it.
   const sampled: Map<string, Frame[]> =
-    only === undefined ? sampleAll(data, fps) : new Map([[only, sampleAnimation(data, only, fps)]]);
+    only === undefined ? sampleAll(data, fps, pose) : new Map([[only, sampleAnimation(data, only, fps, pose)]]);
   console.log(`  ..    ${viewport.width}x${viewport.height}px at ${fps} fps, ${sampled.size} set(s) -> ${outRoot}`);
 
   mkdirSync(outRoot, { recursive: true });
@@ -1609,6 +1646,10 @@ function cmdRender(flags: Record<string, string>): void {
   // render something else into the same grid later.
   const sidecar: FramesSidecar = {
     spec: FRAMES_SPEC,
+    // Written only when a skin was asked for: absent says "no skin was set",
+    // which is both what this run did and what every frame set written before
+    // #571 did. See `FramesSidecar.skin`.
+    ...(skin === undefined ? {} : { skin }),
     background: BACKGROUND,
     viewport: {
       x: viewport.minX,
@@ -2395,7 +2436,15 @@ function cmdExplain(flags: Record<string, string>): void {
   // last one in the repository and issue #307 was about exactly that.
   const motion = parseMotionSpec(readJsonFile(opts.motionPath), opts.motionPath);
 
-  console.log(`\nstage  ${result.skeleton.skeleton.width} x ${result.skeleton.skeleton.height}  (spine ${result.skeleton.skeleton.spine})`);
+  // A rig may state that it has no stage at all (issue #578), and the two must
+  // not print alike: `undefined x undefined` is what a template does with an
+  // absence, and it reads like a defect in the tool rather than a claim in the
+  // spec.
+  const stage =
+    result.skeleton.skeleton.width === undefined || result.skeleton.skeleton.height === undefined
+      ? 'none declared'
+      : `${result.skeleton.skeleton.width} x ${result.skeleton.skeleton.height}`;
+  console.log(`\nstage  ${stage}  (spine ${result.skeleton.skeleton.spine})`);
 
   // The crop note describes where the numbers CAME from, and without a manifest
   // they came from the rig spec's own literals — there is no crop to be relative
@@ -2679,6 +2728,135 @@ function cmdExplain(flags: Record<string, string>): void {
   console.log(`  default=${motion.mix?.default ?? 0} pairs=${JSON.stringify(motion.mix?.pairs ?? [])}`);
 }
 
+/**
+ * ingest — a skeleton back into the two specs that rebuild it.
+ *
+ * The only command that runs against `build`'s direction, and the contract is an
+ * equality rather than a rulebook: `build(ingest(A))` is `A`. Everything it
+ * cannot carry is a **finding** printed here with its code, because those lines
+ * are what tells an author what the rebuilt rig will not have — they are this
+ * command's whole UI, exactly as the validator's messages are `build`'s.
+ *
+ * ⚠️ It writes both specs even when a blocker was found, and then exits
+ * non-zero: a blocker means the rebuild will not be the file that was read, and
+ * the useful thing at that point is the spec plus the list of what is missing
+ * from it. `build`'s "nothing written" rule is not this rule — that one is about
+ * a **gated artifact** on disk, and these two files are inputs to the gate
+ * rather than output of it.
+ */
+function cmdIngest(flags: Record<string, string>, positional: string[]): void {
+  const [source] = positional;
+  if (!source) throw new UsageError('ingest takes one path: <skeleton.json>');
+  const skeletonPath = resolve(source);
+  if (!existsSync(skeletonPath)) throw new UsageError(`nothing at ${skeletonPath}`);
+  // The same sentence `resolveArtifacts` refuses a `.spine` with, for the same
+  // reason (docs/INGEST.md §5): this reads Spine 4.3 skeleton JSON and nothing
+  // else — not a project file, not a binary `.skel`, not the atlas.
+  if (!skeletonPath.endsWith('.json')) {
+    throw new UsageError(
+      `${skeletonPath} is not a .json skeleton — ingest reads Spine 4.3 skeleton JSON and nothing else: not a ` +
+        '.spine project, not a binary .skel, not an atlas. Re-export as JSON',
+    );
+  }
+  if (flags.out === undefined) throw new UsageError('ingest needs --out <dir> — the directory to write rig.json and motion.json into');
+  const art = flags.art ?? 'loose';
+  if (art !== 'loose' && art !== 'none') {
+    throw new UsageError(
+      `--art is ${JSON.stringify(art)}; it is "loose" (name an image per attachment, for \`build --images <dir>\`) ` +
+        'or "none" (state width/height only, for `build --atlas-in <pack>`). A skeleton encodes neither, which is ' +
+        'why this is a flag',
+    );
+  }
+  let stage: IngestStage | undefined;
+  if (flags.stage !== undefined) {
+    const parts = flags.stage.split(',').map(Number);
+    if (parts.length !== 4 || parts.some((n) => !Number.isFinite(n))) {
+      throw new UsageError(`--stage is ${JSON.stringify(flags.stage)}; give four numbers, x,y,width,height`);
+    }
+    stage = { x: parts[0], y: parts[1], width: parts[2], height: parts[3] };
+  }
+  const outDir = resolve(flags.out);
+  /**
+   * The rig spec's own `images`, spelled from `--out` the way `build` spells
+   * `skeleton.images` from its own output directory — the SAME function, so the
+   * two conventions cannot drift (issue #595). Without it the field is left out,
+   * an `image` name resolves against the spec's own directory, and every rebuild
+   * of the spec has to carry `build --images <dir>`.
+   */
+  let specImages: string | undefined;
+  if (flags.images !== undefined) {
+    // Refused rather than ignored, for the reason `chainfit` refuses `--atlas`:
+    // a flag that silently does nothing is worse than one that says why it
+    // cannot. Measured — an `--art none` spec rebuilt with `--images` naming a
+    // directory that does not exist is byte-identical to one rebuilt without
+    // it, because no attachment carries an `image` for that directory to be the
+    // base of.
+    if (art === 'none') {
+      throw new UsageError(
+        '--images <dir> and --art none contradict: `none` writes width/height and no `image` at all, so the rig ' +
+          "spec's `images` directory would be the base of nothing and no rebuild would read it. Use --art loose to " +
+          'name an image per attachment, or drop --images — an `--art none` spec rebuilds with `build --atlas-in ' +
+          '<pack.atlas>`',
+      );
+    }
+    // Not checked for existence, deliberately: `ingest` reads the skeleton and
+    // nothing else, so the parts may well be extracted AFTER the specs are
+    // written, and refusing a directory this command never opens would refuse a
+    // legitimate order of work. `build` is where a missing PNG is named.
+    specImages = relativeImagesPath(outDir, resolve(flags.images));
+  }
+  console.log(`rigc ingest ${skeletonPath}`);
+  console.log(`  ..    out  ${outDir}`);
+  console.log(`  ..    art  ${art}`);
+  if (specImages !== undefined) console.log(`  ..    images ${specImages}  (the rig spec's own, from ${outDir})`);
+
+  const result = ingest(readJsonFile(skeletonPath), {
+    name: flags.name ?? basename(skeletonPath, '.json'),
+    art,
+    images: specImages,
+    stage,
+    source: basename(skeletonPath),
+    version: readVersion(),
+  });
+
+  mkdirSync(outDir, { recursive: true });
+  // Indent 2, which is what `compile` writes the skeleton with. One emitter
+  // convention, so a spec and the skeleton it came from read the same way.
+  writeFileSync(join(outDir, 'rig.json'), `${JSON.stringify(result.rig, null, 2)}\n`);
+  writeFileSync(join(outDir, 'motion.json'), `${JSON.stringify(result.motion, null, 2)}\n`);
+  writeFileSync(join(outDir, 'findings.json'), `${JSON.stringify(result.findings, null, 2)}\n`);
+
+  // Grouped by kind rather than printed in discovery order: a blocker is what
+  // decides the exit code, and a reader scanning for one should not have to
+  // read past a hundred DURATION lines to find it.
+  const GUTTER: Record<IngestFindingKind, string> = { blocker: 'BLOCK', judgement: 'JUDGE', lossy: 'LOSS ' };
+  for (const kind of ['blocker', 'judgement', 'lossy'] as const) {
+    for (const finding of result.findings.filter((f) => f.kind === kind)) {
+      console.log(`  ${GUTTER[kind]} ${finding.code}: ${finding.where} — ${finding.detail}`);
+    }
+  }
+  console.log(`rigc: wrote ${join(outDir, 'rig.json')}`);
+  console.log(`rigc: wrote ${join(outDir, 'motion.json')}`);
+  console.log(`rigc: wrote ${join(outDir, 'findings.json')}`);
+  // The hint is the command the caller will actually run, so it drops `--images`
+  // exactly when the spec now carries the directory itself — a hint that asks for
+  // a flag the spec made unnecessary is the defect issue #595 is about, printed.
+  const artFlag = art === 'none' ? ' --atlas-in <pack.atlas>' : specImages === undefined ? ' --images <dir>' : '';
+  console.log(
+    `rigc: build it with  rigc build --rig ${join(outDir, 'rig.json')} --motion ${join(outDir, 'motion.json')}` +
+      `${artFlag} --out <dir>`,
+  );
+
+  const blockers = result.findings.filter((f) => f.kind === 'blocker');
+  if (blockers.length > 0) {
+    console.error(
+      `rigc: ${blockers.length} blocker(s) — both specs were written, and a build from them will NOT be the ` +
+        `skeleton that was read (${[...new Set(blockers.map((f) => f.code))].join(', ')})`,
+    );
+    process.exit(1);
+  }
+}
+
 // ---------------------------------------------------------------------------
 // usage / per-command help
 // ---------------------------------------------------------------------------
@@ -2767,11 +2945,25 @@ const FLAG_MEANINGS: Record<string, string> = {
     `printed (default ${DEFAULT_MIN_LEVER_PX}); below it the bone is refused \`no-bracket\` naming the measured ` +
     'lever, because an angle read across a short lever turns a half-pixel anchor error into several degrees',
   animation: 'which animation to show; the default is every one for `render` and the first for `preview`',
+  skin:
+    'pose under this skin, by the name the skeleton declares. Without it NO skin is set — every slot resolves ' +
+    'through the default skin alone, so a slot whose art lives only in a named skin draws nothing. A name the ' +
+    'skeleton does not declare is refused with the ones it does. `render` records the skin in frames.json and ' +
+    '`check` reads it back, so a skin-A candidate is not scored against skin-B frames in silence',
   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',
   ballot: `the ballot the --record'd vote answers (default \`${DEFAULT_BALLOT}\`); its embedded manifest is what the vote is checked against`,
   ledger: `the append-only JSONL the vote lands in (default \`${DEFAULT_LEDGER}\`)`,
   again: 'record a second vote on a ballot the ledger already has; without it, a repeat is refused rather than doubled',
+  name: "the rig spec's own name, which the motion spec's archetype must match (default: the skeleton file's basename)",
+  art: 'how the written spec reaches the art, which a skeleton does not encode: `loose` names an image per ' +
+    "attachment, measured out of the rig spec's own images directory (--images writes it; without it, `build " +
+    '--images <dir>` on every rebuild), `none` states width/height only for `build --atlas-in <pack>` to ' +
+    'resolve (default: loose)',
+  stage:
+    "the setup bounding box — `skeleton.x,y,width,height`. An editor export carries none and rigc refuses a " +
+    'compile without one; posing the rig gives the ANIMATED extent, which is a different number, so this is the ' +
+    "caller's value and is never derived. Without it the missing stage is reported as a blocker",
   help: "show this command's flags and exit",
 };
 
@@ -2812,10 +3004,14 @@ const FLAG_VALUES: Record<string, string> = {
   'anchor-residual': '<0..1>',
   'inward-lever': '<px>',
   animation: '<name>',
+  skin: '<name>',
   max: '<px>',
   record: '<result.json>',
   ballot: '<ballot.html>',
   ledger: '<votes.jsonl>',
+  name: '<n>',
+  art: 'loose|none',
+  stage: '<x,y,w,h>',
 };
 
 interface CommandDoc {
@@ -2828,14 +3024,25 @@ interface CommandDoc {
    * Per-command wording for a flag whose value or meaning genuinely differs here.
    *
    * ⚠️ The default above it — one meaning per flag name, everywhere — is the rule
-   * and this is the named exception to it, not a second table. Three flags earn it:
-   * `--out` is a directory of artifacts to `build`, a directory of pictures to
+   * and this is the named exception to it, not a second table. What earns an entry
+   * is the criterion rather than a headcount: the flag is **shared with another
+   * command**, and it means something different in this one. Examples, and not an
+   * inventory: `--out` is a directory of artifacts to `build`, a directory of specs
+   * to `ingest`, a directory of pictures to
    * `render` and one file to `preview` and `vote`; `--fps` is the rate a frame set
    * was RECORDED at to `check`, which reads it off a sidecar, and the rate to
    * SAMPLE at to `render`, which is choosing it; `--candidate` is one artifact
    * everywhere except `vote`, which is the one command that takes several and is
    * the reason there is a ballot at all. Writing any of them as one sentence
    * covering every command would leave every command's own help less true.
+   *
+   * ⛔ The other side of the criterion, which is the one that keeps this from
+   * becoming the second table it says it is not: a flag no other command takes has
+   * nothing to differ FROM, so its wording belongs in `FLAG_MEANINGS` /
+   * `FLAG_VALUES` above and an entry here for it buys only a second place to look.
+   * Both halves are read off `--help` by `CLI71` in `selftest.ts`, which is why
+   * this sentence no longer counts anything: it said *"three"* where #605 counted
+   * nine, and nothing had ever compared the two.
    */
   overrides?: Record<string, { value?: string; meaning?: string }>;
 }
@@ -2878,6 +3085,25 @@ const COMMANDS: CommandDoc[] = [
     ],
     flags: ['atlas', 'profile', 'cut', 'cuts', 'rig', 'motion', 'out', 'manifest', 'images'],
   },
+  {
+    name: 'ingest',
+    usage: ['rigc ingest <skeleton.json> --out <dir> [--name <n>] [--art loose|none] [--images <dir>] [--stage x,y,w,h]'],
+    flags: ['out', 'name', 'art', 'images', 'stage'],
+    overrides: {
+      out: {
+        value: '<dir>',
+        meaning: 'directory to write rig.json, motion.json and findings.json into — the two specs that rebuild this skeleton',
+      },
+      images: {
+        value: '<dir>',
+        meaning:
+          "WRITE the rig spec's own images directory, spelled relative to --out, so the rebuild is a plain `build " +
+          '--rig … --motion … --out …` with no flag. ⚠️ The opposite direction from `build --images`, which ' +
+          'OVERRIDES that field: this one fills it in. Without it the field is left out and every `image` resolves ' +
+          'against --out itself. Refused together with --art none, which writes no `image` for it to be the base of',
+      },
+    },
+  },
   {
     name: 'diff',
     usage: ['rigc diff <candidate.json> <reference.json> [--json <out>]'],
@@ -2886,7 +3112,16 @@ const COMMANDS: CommandDoc[] = [
   {
     name: 'check',
     usage: ['rigc check --candidate <dir | skeleton.json> --frames <dir> [flags]'],
-    flags: ['candidate', 'frames', 'atlas', 'texture-from', 'fps', 'viewport', 'framing', 'as', 'all-frames', 'json'],
+    flags: ['candidate', 'frames', 'atlas', 'texture-from', 'fps', 'viewport', 'framing', 'as', 'skin', 'all-frames', 'json'],
+    overrides: {
+      skin: {
+        meaning:
+          'pose the CANDIDATE under this skin, by the name it declares. Without it no skin is set and the ' +
+          'default skin alone is compared, which for a multi-skin rig is a comparison that can see none of the ' +
+          'contested art. The frames are checked back: a set whose frames.json records a different skin is ' +
+          'REFUSED by name, and one that records none says so in the report rather than pretending to agree',
+      },
+    },
   },
   {
     name: 'bench',
@@ -2914,9 +3149,9 @@ const COMMANDS: CommandDoc[] = [
   {
     name: 'render',
     usage: [
-      'rigc render --candidate <dir | skeleton.json> [--animation <name>] [--fps 12] [--max 256] [--out render/]',
+      'rigc render --candidate <dir | skeleton.json> [--animation <name>] [--skin <name>] [--fps 12] [--max 256] [--out render/]',
     ],
-    flags: ['candidate', 'atlas', 'animation', 'fps', 'max', 'out'],
+    flags: ['candidate', 'atlas', 'animation', 'skin', 'fps', 'max', 'out'],
     overrides: {
       out: { value: '<dir>', meaning: 'directory to write the frame series into (default `render/`)' },
       fps: { meaning: `frames per second to sample the animation at (default ${PROTOCOL_FPS})` },
@@ -3070,6 +3305,20 @@ const USAGE = [
   'draws with rigc\'s own rasteriser; preview embeds the artifact in a page that plays',
   'it in the official Spine Web Player, which is also the interop proof.',
   '',
+  'ingest runs build backwards: it reads a Spine 4.3 skeleton.json and writes the rig',
+  'spec and motion spec that rebuild it, so an existing skeleton becomes a starting',
+  'point instead of something to retype:',
+  '  rigc ingest hero.json --out specs/ --stage 0,0,1024,768   rig.json + motion.json',
+  'The contract is an equality, not a rulebook: build(ingest(x)) is x, byte for byte.',
+  'It reads the skeleton and nothing else — no .spine project, no binary .skel, no',
+  'atlas — so two things are the caller\'s and are refused rather than guessed: the',
+  'setup stage (--stage; an export carries none) and how the spec reaches the art',
+  '(--art). --images <dir> is the third and the only optional one: it WRITES the rig',
+  'spec\'s own images directory, relative to --out, so the rebuild needs no flag.',
+  'Everything the spec format cannot hold is printed as a named finding and',
+  'exits non-zero, with both files still written, because a spec plus a list of what',
+  'is missing from it beats no spec at all.',
+  '',
   'pose runs the other way round from everything above: it reads a picture you already',
   'have — one key pose — and reports where each loose part PNG sits in it (x, y, rotation,',
   'scale) so an agent can state those poses in a spec by construction:',
@@ -3130,6 +3379,7 @@ try {
     process.exit(0);
   }
   if (command === 'build') cmdBuild(flags);
+  else if (command === 'ingest') cmdIngest(flags, positional);
   else if (command === 'validate') cmdValidate(flags, positional);
   else if (command === 'explain') cmdExplain(flags);
   else if (command === 'diff') cmdDiff(flags, positional);