spine-rigc 1.9.2 → 1.9.3

package/cli.ts

@@ -31,4400 +31,31 @@
  * Its paths resolve against the cuts.json file itself, so the table travels
  * with the project that owns the art rather than with this repository.
  */
-import {
-  appendFileSync,
-  cpSync,
-  existsSync,
-  lstatSync,
-  mkdirSync,
-  readdirSync,
-  readFileSync,
-  readlinkSync,
-  realpathSync,
-  rmSync,
-  statSync,
-  symlinkSync,
-  writeFileSync,
-} from 'node:fs';
-import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
-import {
-  BallotError,
-  buildBallot,
-  ledgerLineText,
-  MAX_CANDIDATES,
-  MIN_CANDIDATES,
-  parseLedger,
-  readBallotManifest,
-  resultFilename,
-  TIE,
-  verifyResult,
-  VOTE_RULES,
-  type BallotCandidateInput,
-  type BallotInput,
-} from './src/ballot.ts';
-import {
-  boneDistance,
-  BONEDIST_SPEC,
-  boneDistLines,
-  BoneDistError,
-  IDENTITY_CORRESPONDENCE,
-  type BoneDistReport,
-} from './src/bonedist.ts';
-import {
-  checkAgainstFrames,
-  checkLines,
-  CheckError,
-  CheckPlates,
-  type CheckOptions,
-  type CheckReport,
-} from './src/check.ts';
-import { writeCheckPictures } from './src/checkpics.ts';
-import { compile, CompileError, droppedStateReason, relativeImagesPath, type CompileOptions } from './src/compile.ts';
-import { MODEL_DOCUMENT_FILE, modelDocument } from './src/model.ts';
-import { deformReportBlock } from './src/deformreport.ts';
-import { surveyOfBuild, type DeformSurvey } from './src/deformmeasure.ts';
-import { CoreInputError } from './src/core/index.ts';
-import {
-  diffLines,
-  diffSkeletons,
-  reportedFigures,
-  sectionFigures,
-  type DiffAnimationPair,
-  type DiffReport,
-} from './src/diff.ts';
-import { ingest, IngestError, IngestSpecRefused, INGEST_GUTTERS, type IngestFinding, type IngestStage } from './src/ingest.ts';
-import { NotAPngError } from './src/png.ts';
-import { copyAtlasPages, plannedPageCopies } from './src/emit.ts';
-import {
-  DEFAULT_PADDING,
-  DEFAULT_PAGE_EDGES,
-  DEFAULT_PAGE_SIZE,
-  PAGE_EDGES,
-  packAtlas,
-  type PageEdges,
-  pageFootprint,
-  parseAtlasText,
-  type AtlasRegion,
-} from './src/atlas.ts';
-import { parseJsonWithPosition } from './src/json-position.ts';
-import { PARSER_DEFAULTS, parserReading } from './src/keyorder.ts';
-import { findRung, RUNG_IDS, type RungSkeleton } from './src/ladder.ts';
-import {
-  DEFAULT_MAX_RESIDUAL,
-  DEFAULT_SCALE_MAX,
-  DEFAULT_SCALE_MIN,
-  estimatePose,
-  PoseError,
-  poseLines,
-  type PoseOptions,
-} from './src/pose.ts';
-import {
-  ANCHOR_MAX_RESIDUAL,
-  ANCHOR_MAX_UNEXPLAINED,
-  chainFitLines,
-  ChainFitError,
-  DEFAULT_HINGE_MAX,
-  DEFAULT_HINGE_MIN,
-  DEFAULT_MIN_LEVER_PX,
-  DEFAULT_MIN_VISIBLE,
-  DEFAULT_PASSES,
-  estimateChainFit,
-  type ChainFitOptions,
-} from './src/chainfit.ts';
-import { buildPreview, buildPreviewPanes, PLAYER_LINE, type PreviewGate, type PreviewInput, type PreviewPage } from './src/preview.ts';
-import {
-  atlasPageNames,
-  BACKGROUND,
-  contactSheet,
-  FRAMES_SIDECAR,
-  FRAMES_SPEC,
-  framingViewport,
-  GEOMETRY_FILE,
-  GeometryError,
-  UnframeablePoseError,
-  geometryFileOf,
-  geometryText,
-  loadCandidate,
-  PROTOCOL_FPS,
-  renderFrame,
-  sampleAll,
-  sampleAnimation,
-  SETUP_POSE_DIR,
-  SHEET_FILE,
-  SHEET_TILE,
-  sidecarViewport,
-  SlotSubsetError,
-  POSER_NAMES,
-  PoserChoiceError,
-  refuseUnchosen,
-  CandidateAtlasError,
-  CandidatePairError,
-  SpineRuntimeError,
-  throughPoser,
-  type Frame,
-  type FramesSidecar,
-  type FrameSet,
-  type PoserName,
-  type SkeletonFacts,
-  type SlotSubset,
-} from './src/render.ts';
-import {
-  assertionCountForProfile,
-  attachmentRegionJoins,
-  CLI_DEFAULT_PROFILE,
-  reportLines,
-  validate,
-  VALIDATE_PROFILES,
-  type ValidateProfile,
-} from './src/validate.ts';
-import { parseMotionSpec } from './src/motion.ts';
-import { depthStepLevels, type FoldLimit, type TurnCeiling } from './src/depth.ts';
-import type { CompileResult, DroppedState } from './src/types.ts';
-
-/**
- * One entry of a cuts.json, every path relative to the cuts.json file.
- *
- * `rig` is required — it is the skeleton's structure, and until it was a file
- * that structure was three hard-coded tables in the compiler. `manifest` is
- * optional: a skeleton with no measured art behind it has none, and then the rig
- * spec carries its own attachments and stage size.
- */
-export interface CutEntry {
-  rig: string;
-  motion: string;
-  out: string;
-  manifest?: string;
-  /** Base directory for the rig spec's `image` references, if not the rig's own. */
-  images?: string;
-}
-
-export type CutTable = Record<string, CutEntry>;
-
-class UsageError extends Error {}
-
-/**
- * `explain` refusing a pair it cannot pose — a usage error in kind, printed
- * without the usage block for `PoseError`'s and `IngestError`'s reason: the
- * message names an attachment, a region and two flags, and reprinting every
- * command's usage under it buries the one line that says what to change.
- */
-class ExplainError extends Error {}
-
-// ---------------------------------------------------------------------------
-// package metadata — the installed version and repository, for `--version`
-// and for naming a remedy `bench` can only give from a repo checkout.
-// ---------------------------------------------------------------------------
-
-interface PackageMeta {
-  version?: string;
-  repository?: string | { url?: string };
-}
-
-let packageMeta: PackageMeta | null | undefined;
-
-/** `package.json` sits next to this file both in the repo and once installed. */
-function readPackageMeta(): PackageMeta | null {
-  if (packageMeta === undefined) {
-    try {
-      packageMeta = JSON.parse(readFileSync(join(import.meta.dir, 'package.json'), 'utf8')) as PackageMeta;
-    } catch {
-      packageMeta = null;
-    }
-  }
-  return packageMeta;
-}
-
-function readVersion(): string {
-  return readPackageMeta()?.version ?? 'unknown';
-}
-
-function repositoryUrl(): string {
-  const repo = readPackageMeta()?.repository;
-  const url = typeof repo === 'string' ? repo : repo?.url;
-  return (url ?? 'https://github.com/firejune/rigc').replace(/^git\+/, '').replace(/\.git$/, '');
-}
-
-// ---------------------------------------------------------------------------
-// argument parsing
-// ---------------------------------------------------------------------------
-
-/**
- * The flags that are switches rather than `--flag value` pairs.
- *
- * Listed by name rather than inferred from "the next argument looks like a
- * flag": inferring it would turn `--out --json report.json` — a real typo, a
- * missing value — into a silently accepted switch plus a stray positional.
- *
- * ⚠️ This set and `FLAG_VALUES` are two halves of one statement, and they are
- * the halves a reader and the parser read separately: a flag absent from
- * `FLAG_VALUES` is printed bare in every usage line and flag table, and a flag
- * present here is the only kind the parser will accept bare. `all-bones` was in
- * one half and not the other for two releases — documented bare in `bonedist`'s
- * usage line, in the shared flag table, and in the hint `src/bonedist.ts` prints
- * under a truncated bone table, while the parser fell through to the value
- * branch and answered the caller who followed that hint with `rigc: --all-bones
- * needs a value` (issue #328). `CLI10`/`CLI11` in `selftest.ts` now hold the two
- * halves together by reading `--help` rather than by naming a flag.
- */
-const BOOLEAN_FLAGS = new Set(['all-frames', 'all-bones', 'help', 'copy-images', 'again', 'pack', 'copy', 'geometry']);
-
-/**
- * The flags a command is allowed to spell more than once.
- *
- * `vote --candidate` is, because a ballot is *by definition* several
- * candidates; `preview --candidate` is, because a pane per candidate on one
- * page is what an agent otherwise builds by hand (issue #837); and `diff --as`
- * is, because a skeleton has as many shots as it has and one pairing per flag is the only spelling that keeps each pair a pair
- * (issue #720). Everywhere else a repeat is a mistake and is refused: `check
- * --candidate a --candidate b` used to take `b` silently, which is a report
- * about a rig the caller did not think they were asking about.
- */
-const REPEATABLE_FLAGS: Record<string, ReadonlySet<string>> = {
-  vote: new Set(['candidate']),
-  diff: new Set(['as']),
-  preview: new Set(['candidate']),
-};
-
-/**
- * `--flag value` pairs plus the leftover positionals, in order.
- *
- * `lists` carries every occurrence of every flag and `flags` carries the last
- * one, so a command that wants a repeated flag reads `lists` and the ones that
- * do not are untouched by the addition.
- */
-function parseArgs(
-  argv: string[],
-  repeatable: ReadonlySet<string> = new Set(),
-): { flags: Record<string, string>; lists: Record<string, string[]>; positional: string[] } {
-  const flags: Record<string, string> = {};
-  const lists: Record<string, string[]> = {};
-  const positional: string[] = [];
-  const take = (name: string, value: string): void => {
-    if (flags[name] !== undefined && !repeatable.has(name)) {
-      throw new UsageError(
-        `--${name} was given more than once (${JSON.stringify(flags[name])} then ${JSON.stringify(value)}); ` +
-          'this command takes it once',
-      );
-    }
-    flags[name] = value;
-    (lists[name] ??= []).push(value);
-  };
-  for (let i = 0; i < argv.length; i++) {
-    const arg = argv[i];
-    if (arg.startsWith('--')) {
-      const eq = arg.indexOf('=');
-      if (eq !== -1) {
-        take(arg.slice(2, eq), arg.slice(eq + 1));
-      } else if (BOOLEAN_FLAGS.has(arg.slice(2))) {
-        take(arg.slice(2), 'true');
-      } else {
-        const next = argv[i + 1];
-        if (next === undefined || next.startsWith('--')) throw new UsageError(`${arg} needs a value`);
-        take(arg.slice(2), next);
-        i++;
-      }
-    } else {
-      positional.push(arg);
-    }
-  }
-  return { flags, lists, positional };
-}
-
-/**
- * Read and parse a JSON file the caller named on the command line — a cuts
- * table, a candidate or reference skeleton to `diff`. A parse failure names the
- * file and, best-effort, where inside it the syntax broke (see
- * `parseJsonWithPosition`); left as a raw `JSON.parse`, it would surface as an
- * unhandled `SyntaxError` with a stack trace instead of a usage error.
- */
-function readJsonFile(path: string): unknown {
-  return parseJsonNamed(readFileSync(path, 'utf8'), path);
-}
-
-/** `text`, read from `path`, parsed — and refused naming the file and where it broke when it is not JSON. */
-function parseJsonNamed(text: string, path: string): unknown {
-  try {
-    return parseJsonWithPosition(text);
-  } catch (err) {
-    throw new UsageError(`cannot read ${path}: ${(err as Error).message}`);
-  }
-}
-
-/**
- * A skeleton a command was pointed at, as text — refused like every other JSON
- * file on the command line (`parseJsonNamed`) when it is not JSON (issue
- * #1042). `render`, `check`, `bench` and `bonedist` hand the text to a loader
- * that parses it again, and on a file that is not JSON that parse surfaced as
- * the runtime's `SyntaxError` and a stack, where `diff`, `preview`, `vote` and
- * `ingest` already said `cannot read <path>`.
- */
-function readSkeletonText(path: string): string {
-  const text = readFileSync(path, 'utf8');
-  parseJsonNamed(text, path);
-  return text;
-}
-
-/**
- * Read a cuts.json and resolve its three paths against the file's own
- * directory. Anchoring on the table rather than on the process cwd is what lets
- * the same command work from anywhere in the owning project.
- */
-function readCutTable(cutsPath: string): { dir: string; table: CutTable } {
-  const abs = resolve(cutsPath);
-  if (!existsSync(abs)) throw new UsageError(`no cuts file at ${abs}`);
-  const parsed = readJsonFile(abs);
-  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
-    throw new UsageError(`${abs}: expected an object of cut name -> { manifest, motion, out }`);
-  }
-  return { dir: dirname(abs), table: parsed as CutTable };
-}
-
-function entryToOptions(dir: string, name: string, entry: CutEntry): CompileOptions {
-  for (const key of ['rig', 'motion', 'out'] as const) {
-    if (typeof entry?.[key] !== 'string') throw new UsageError(`cut ${JSON.stringify(name)} has no "${key}" path`);
-  }
-  const opts: CompileOptions = {
-    rigPath: resolve(dir, entry.rig),
-    motionPath: resolve(dir, entry.motion),
-    outDir: resolve(dir, entry.out),
-  };
-  if (entry.manifest !== undefined) opts.manifestPath = resolve(dir, entry.manifest);
-  if (entry.images !== undefined) opts.imagesDir = resolve(dir, entry.images);
-  return opts;
-}
-
-/**
- * Resolve the cut a command was pointed at, either spelled out on the command
- * line or looked up by name in a cuts.json.
- */
-function resolveCut(flags: Record<string, string>): { label: string; opts: CompileOptions } {
-  const explicit =
-    flags.rig !== undefined || flags.manifest !== undefined || flags.motion !== undefined || flags.out !== undefined;
-  if (explicit) {
-    if (flags.cut !== undefined || flags.cuts !== undefined) {
-      throw new UsageError('--rig/--motion/--out and --cut/--cuts are two ways to say the same thing; pick one');
-    }
-    for (const key of ['rig', 'motion', 'out'] as const) {
-      if (flags[key] === undefined) throw new UsageError(`--${key} is required when the cut is spelled out`);
-    }
-    const opts: CompileOptions = {
-      rigPath: resolve(flags.rig),
-      motionPath: resolve(flags.motion),
-      outDir: resolve(flags.out),
-    };
-    if (flags.manifest !== undefined) opts.manifestPath = resolve(flags.manifest);
-    if (flags.images !== undefined) opts.imagesDir = resolve(flags.images);
-    if (flags['atlas-in'] !== undefined) opts.atlasInPath = resolve(flags['atlas-in']);
-    return { label: flags.rig, opts };
-  }
-  if (flags.cut === undefined) throw new UsageError('give either --cut <name> --cuts <cuts.json>, or --rig/--motion/--out');
-  if (flags.cuts === undefined) throw new UsageError('--cut needs --cuts <cuts.json> to look the name up in');
-  const { dir, table } = readCutTable(flags.cuts);
-  const entry = table[flags.cut];
-  if (!entry) {
-    throw new UsageError(
-      `unknown cut ${JSON.stringify(flags.cut)} in ${resolve(flags.cuts)}. known: ${Object.keys(table).join(', ') || '(none)'}`,
-    );
-  }
-  const opts = entryToOptions(dir, flags.cut, entry);
-  // `--atlas-in` is not part of the cuts table: a cut names its rig, motion and
-  // manifest, and where the pixels are delivered from is a property of the BUILD.
-  // Resolved against the working directory, like every other path on the command
-  // line, rather than against the table's directory.
-  if (flags['atlas-in'] !== undefined) opts.atlasInPath = resolve(flags['atlas-in']);
-  return { label: flags.cut, opts };
-}
-
-// ---------------------------------------------------------------------------
-// commands
-// ---------------------------------------------------------------------------
-
-/**
- * Read `--profile`, defaulting to `spine` — see `CLI_DEFAULT_PROFILE`.
- *
- * An unknown name is a usage error rather than a silent fallback, and that
- * matters in both directions: a typo used to re-apply the strictest rulebook to
- * data the caller was trying to exempt, and it would now drop the policy layer
- * from a caller who typed `--profile spine-htlm` and believes they asked for it.
- * Neither is something to discover from a green.
- */
-function readProfile(flags: Record<string, string>): ValidateProfile {
-  const raw = flags.profile;
-  if (raw === undefined) return CLI_DEFAULT_PROFILE;
-  const found = VALIDATE_PROFILES.find((p) => p === raw);
-  if (!found) throw new UsageError(`--profile ${JSON.stringify(raw)}; known profiles: ${VALIDATE_PROFILES.join(', ')}`);
-  return found;
-}
-
-/**
- * An atlas text to gate INSTEAD of the compile's own, with the second, independent
- * emit A18 compares it against.
- *
- * `--pack` is the only caller. A packed build is gated twice on purpose — once as
- * compiled (which is the gate that reads the loose PNGs, so `A06`'s size-vs-file
- * clause still measures the art R5 measures) and once as packed (which is the pair
- * that actually ships). Handing the second pass its texts rather than re-deriving
- * them here keeps `runGate` ignorant of what a pack is.
- */
-interface AtlasOverride {
-  text: string;
-  again: string;
-}
-
-function runGate(
-  result: CompileResult,
-  modelText: string,
-  opts: CompileOptions,
-  profile: ValidateProfile,
-  /** The atlas text `build` writes for a compile's own — `--copy-images` renames the pages — which the second compile's document is spelled from, as `modelText` was (issue #1016). */
-  written: (atlasText: string) => string,
-  atlas?: AtlasOverride,
-): number {
-  // The determinism check compares a second, independent compile — its model
-  // document included, which is the text `build` writes beside the pair, and
-  // which states where each region sits in the atlas written with it (`pages`,
-  // issue #1016): so the second document is spelled from the second compile's
-  // atlas as it would be written, or from the second, independent pack.
-  const again = compile(opts);
-  const report = validate({
-    skeletonText: result.skeletonText,
-    atlasText: atlas ? atlas.text : result.atlasText,
-    atlasDir: opts.outDir,
-    declaredDurations: result.declaredDurations,
-    modelText,
-    reEmit: { skeletonText: again.skeletonText, atlasText: atlas ? atlas.again : again.atlasText, modelText: modelDocument(again.model, again.skeletonText, atlas ? atlas.again : written(again.atlasText)) },
-    rig: result.rig,
-    profile,
-  });
-  for (const line of reportLines(report)) console.log(line);
-  console.log(
-    `  ..    ${Object.entries(report.stats)
-      .map(([k, v]) => `${k}=${v}`)
-      .join(' ')}`,
-  );
-  return report.failures.length;
-}
-
-/**
- * One line per mesh kind on this cut, printed above the table.
- *
- * A legend rather than a heading: the heading used to describe the ring tier
- * unconditionally, so a build whose only mesh was a ribbon or a contour got a
- * sentence about a rim ring and a seam it does not have.
- */
-/**
- * What a depth map and a soft region put on a mesh, when it named either.
- *
- * The digests are the reason this prints at all: a claim about a rig can name
- * WHICH sheet produced it, and two runs a reader believes differ can be shown to
- * have read the same pixels. The ranges and counts are what say the input
- * reached the geometry rather than merely being resolved — a `carried 0` never
- * gets here (it is refused) and a `ramped 0` is a hard-edged mask, which is
- * legal and usually not what somebody meant.
- */
-/**
- * One axis's two ceilings, as `+31.41 / -18.03`, or what is unbounded on it.
- *
- * ⚠️ `none` and a number are different claims and are printed differently. A
- * sheet with no gradient along an axis cannot fold anything on it AT ANY ANGLE,
- * which is a fact about the sheet worth reading; printing `90` for it would be
- * a limit nothing measured.
- */
-function ceilingPair(axis: { positive: FoldLimit | null; negative: FoldLimit | null }): string {
-  const one = (l: FoldLimit | null, sign: string) => (l === null ? `${sign}none` : `${sign}${l.degrees.toFixed(2)}°`);
-  return `${one(axis.positive, '+')} / ${one(axis.negative, '-')}`;
-}
-
-/**
- * The same axis's two 1st percentiles, each with its ratio to the ceiling above
- * it and the population it came out of — `+64.80° x1.003 of 5988`.
- *
- * ⭐ The ratio is the whole point and it is printed rather than judged. A
- * ceiling set by the FORM is the floor of a band: the steepest region of a
- * smooth sheet has area, so the 1st percentile sits a fraction of a percent
- * above the minimum. A ceiling set by one bad texel has 99 % of the mesh
- * surviving to the form's angle while the reported number collapses — 64.58°
- * against 6.08° for one texel of 160,000, with the percentile unmoved at 64.80°
- * in both ([#412](https://github.com/firejune/rigc/issues/412),
- * `bench/studies/2026-09-05-noise` §6).
- *
- * Three spellings, three different claims, for the reason `ceilingPair` prints
- * `none` rather than 90: `+none` is a side nothing folds on at all, `+unranked
- * of 36` is a side whose population is too small for a first percentile to be
- * anything but the minimum itself, and a number is a measurement.
- *
- * ⛔ No threshold lives here. What ratio means what is in `docs/AUTHORING.md`
- * §3.4, because a number rigc printed an adjective beside would be a policy the
- * compiler invented out of a measurement — and `A39` would go on refusing at the
- * raw angle either way.
- */
-function spreadPair(axis: { positive: FoldLimit | null; negative: FoldLimit | null }): string {
-  const one = (l: FoldLimit | null, sign: string) =>
-    l === null
-      ? `${sign}none`
-      : l.p1 === null
-        ? `${sign}unranked of ${l.count}`
-        : `${sign}${l.p1.toFixed(2)}° x${(l.p1 / l.degrees).toFixed(3)} of ${l.count}`;
-  return `${one(axis.positive, '+')} / ${one(axis.negative, '-')}`;
-}
-
-/** The tightest of the four, so the line that names a triangle names the right one. */
-function tightestFold(c: TurnCeiling): { kind: string; sign: string; limit: FoldLimit } | null {
-  const all = [
-    { kind: 'yaw', sign: '+', limit: c.yaw.positive },
-    { kind: 'yaw', sign: '-', limit: c.yaw.negative },
-    { kind: 'pitch', sign: '+', limit: c.pitch.positive },
-    { kind: 'pitch', sign: '-', limit: c.pitch.negative },
-  ].filter((e): e is { kind: string; sign: string; limit: FoldLimit } => e.limit !== null);
-  if (all.length === 0) return null;
-  return all.reduce((best, e) => (e.limit.degrees < best.limit.degrees ? e : best));
-}
-
-function meshDepthNote(m: CompileResult['meshes'][number]): string {
-  const parts: string[] = [];
-  if (m.depth) {
-    parts.push(
-      `depth "${m.depth.image}" ${m.depth.digest} near=${m.depth.near} zScale=${m.depth.zScale} ` +
-        `z=[${m.depth.range[0]}, ${m.depth.range[1]}]`,
-    );
-    // Directly under the sheet's own line, because it is the other half of
-    // "what did this mesh read": `z=[…]` says how much of the map's range
-    // reached the vertices, and this says how many of them read a texel that
-    // draws nothing (issue #449). Reported only when there is something to
-    // report, so a mesh whose every vertex sits on drawn art gains no line.
-    //
-    // ⭐ A `contour` gets the OTHER half of the sentence, because rigc built
-    // that outline and knows what it is: `buildContourMesh` returns
-    // `hullVertices: points.length` over `offsetPolygon(simplified, margin)`,
-    // so every vertex of a contour mesh is the traced silhouette pushed out by
-    // the margin — there are no interior vertices for the count to be about.
-    // Nothing is derived, inferred or thresholded to say so; it is what the
-    // generator returns, and `generatedHullAndEdges` already cross-checks that
-    // hull against the triangulation's own outline. Without it the line reads
-    // as a fault on every correct contour rig, which is a diagnostic authors
-    // learn to ignore.
-    // Withheld, and said where the count would have stood (issue #750): the
-    // part's texels could not be located on its page, so there is no count
-    // that is about this part.
-    if (m.depth.unlocated !== undefined) {
-      parts.push(`the count of vertices on undrawn texels is not measured: ${m.depth.unlocated}. ${PAGE_GRID_UNLOCATED}`);
-    } else if (m.depth.undrawn !== null && m.depth.undrawn > 0) {
-      parts.push(
-        `${m.depth.undrawn} of ${m.vertices} vertices sample a texel the part image does not draw — ` +
-          (m.kind === 'contour'
-            ? 'a contour\'s vertices are all traced outline, pushed out by the margin, so this is the topology and not the sheet'
-            : 'their z is the sheet\'s reading of somewhere the part is not'),
-      );
-    }
-    const c = m.depth.ceiling;
-    parts.push(`turn ceiling  yaw ${ceilingPair(c.yaw)}   pitch ${ceilingPair(c.pitch)}`);
-    const worst = tightestFold(c);
-    if (worst !== null) {
-      parts.push(`  1st pct     yaw ${spreadPair(c.yaw)}   pitch ${spreadPair(c.pitch)}`);
-    }
-    parts.push(
-      worst === null
-        ? `              nothing in this sheet folds: ${c.measured} triangle(s) measured, none with a depth gradient across it`
-        : `              first to fold: ${worst.kind} ${worst.sign} at ${worst.limit.degrees.toFixed(2)}°, ` +
-          `triangle ${worst.limit.triangle} [${worst.limit.ids.join(',')}], the sheet steps ` +
-          `${depthStepLevels(worst.limit.depthStep, m.depth.zScale).toFixed(2)} level(s) across it, ` +
-          // The same step over the range the mesh sampled (issue #448). A
-          // suffix and not a line of its own: it is an apposition on the step
-          // beside it, and the reading that matters is the two together — a
-          // discontinuity says "plenty of levels" and "nearly all of them" at
-          // once, and they have to be read in one breath to say the opposite.
-          `which is ${worst.limit.stepShare.toFixed(3)} of the range this mesh sampled` +
-          `${c.degenerate ? `; ${c.degenerate} triangle(s) too flat in setup to measure` : ''}`,
-    );
-  }
-  if (m.soft) {
-    parts.push(
-      `soft "${m.soft.mask}" ${m.soft.digest} -> ${m.soft.bone}, ${m.soft.carried} carried / ${m.soft.ramped} in the falloff`,
-    );
-  }
-  return parts.length === 0 ? '' : `\n        ${parts.join('\n        ')}`;
-}
-
-const MESH_KIND_NOTES: Record<CompileResult['meshes'][number]['kind'], string> = {
-  ring: 'ring      rim ring pinned on the window edge, seam ring pinned on the mask contour, aperture moves',
-  ribbon: 'ribbon    entry row pinned, rows share their weights so the strip lengthens without widening',
-  contour: 'contour   the art\'s own silhouette, every vertex pinned to the slot bone (geometry, not a deformation)',
-  grid: 'grid      a lattice over the part window at stated column and row positions, every vertex pinned to the slot bone',
-  segments: 'segments  a lattice over the part\'s alpha, every vertex weighted by distance to the bone segments it names',
-  authored: 'authored  geometry rigc did not build; it assumes nothing about the topology',
-};
-
-/**
- * The line under a `segments` mesh: how its bones share the vertices.
- *
- * ⭐ The weights are this generator's whole output, and the per-vertex numbers
- * are nowhere a reader can see them — so the three figures that say whether the
- * falloff did what was meant are printed where the mesh is: the most bones any
- * vertex binds (against `maxBones`), the mean, and how many vertices a single
- * bone owns outright. A named bone no vertex binds is said by name, because it
- * is in no weight and so in no other figure either.
- */
-function meshInfluenceNote(m: CompileResult['meshes'][number]): string {
-  const inf = m.influence;
-  if (inf === undefined) return '';
-  const unbound = m.bones.filter((b) => !inf.bound.includes(b));
-  const single = m.vertices === 0 ? 0 : (inf.singleBone / m.vertices) * 100;
-  const joined = inf.keptCells - inf.artCells;
-  return (
-    `\n        influence  max ${inf.maxBones} bone(s) per vertex, mean ${inf.meanBones.toFixed(2)}, ` +
-    `${inf.singleBone} of ${m.vertices} vertices (${single.toFixed(2)}%) on a single bone` +
-    (unbound.length ? `; named and bound by no vertex: ${unbound.join(', ')}` : '') +
-    `\n        lattice    cell ${inf.cell}px, ${inf.cols}x${inf.rows} cells, ${inf.artCells} with art, ${inf.keptCells} kept` +
-    (inf.islands > 1 || joined > 0
-      ? ` (${inf.islands} island(s) joined into one outline, ${joined} cell(s) added that hold no art)`
-      : '')
-  );
-}
-
-/**
- * Why a figure taken off a part's texels is withheld on a page whose file is
- * not the size its atlas declares — the tail of every line that withholds one
- * (issue #750). The page and its ratios come first, from `pageGridSaid`; this
- * says what that does to the reading and where the repair is named.
- */
-const PAGE_GRID_UNLOCATED =
-  'rigc lifts a part off its page at the coordinates the atlas states, and on this file those are not where the ' +
-  "part's texels are, so a figure taken there would describe another part of the page. " +
-  '`A06_ATLAS_PAGE_SIZE_MATCHES_PNG` refuses the page by the same ratio and names the `scale:` header that states it';
-
-/**
- * What a mesh measured about its own fit against the art it names, or nothing
- * for a mesh with no art to measure against.
- *
- * Printed for authored geometry as well as for a `contour` (issue #277): the
- * figure is a measurement between the emitted triangles and the PNG, so it means
- * the same thing whoever drew the vertices, and the silence was the defect —
- * an octagon rim placed on a round part's silhouette clips its own ink outline
- * at 94.31% and used to print nothing at all.
- *
- * The hole is appended only when there is one, so the common line is unchanged.
- * It is the one figure in the report that a hole moves: `coverage` and
- * `overshoot` are both measured against the FILLED silhouette, so spanning an
- * interior hole is neither missing coverage nor reaching past anything, and an
- * unintentional hole — a gap in the art, a stroke that failed to join — bought
- * fill over transparent pixels with nothing anywhere saying so (issue #275).
- */
-function meshFit(m: CompileResult['meshes'][number]): string {
-  // The fit is a measurement against the part's texels, and on a page whose
-  // file is not its declared size the region lift does not have them (issue
-  // #750). It printed 68.49% / 76.24px there for a mesh that measures 100.00% /
-  // 16.00px on the page it was packed from — two plausible numbers about
-  // another part of the picture. So the line says what was not measured and
-  // why, in the place the figures stood, and prints no figure.
-  if (m.fitWithheld !== undefined) return `  fit not measured: ${m.fitWithheld}. ${PAGE_GRID_UNLOCATED}`;
-  if (m.coverage === undefined) return '';
-  // A count of the plate's own cells, so on a `scale:` page it is texels and
-  // says so rather than borrowing the overshoot's unit beside it (issue #762).
-  const hole = m.holePixels ? `, enclosing ${m.holePixels}${m.pageScale === undefined ? 'px' : ' texel(s)'} of hole` : '';
-  return `  covers ${(m.coverage * 100).toFixed(2)}% of the art, reaching ${m.overshoot?.toFixed(2) ?? '?'}px past it${meshFitGrid(m)}${hole}`;
-}
-
-/**
- * The grid a fit was taken on, when it is not the drawing's own (issue #762).
- *
- * The overshoot is stated in the drawing's pixels on every route — the unit an
- * attachment's size is in — and on a page that declares a `scale:` other than
- * 1 it was measured on the page's texels and divided by that scale. So it
- * carries the coarser grid's step: on `scale: 0.5` a figure moves in steps of
- * 2.00px of the drawing, and it need not equal the figure the page it was
- * packed from reads except where the distance falls on whole texels. Said
- * beside the figure, and nothing at all on a loose part or a page at scale 1,
- * where the line is the one it always was.
- */
-function meshFitGrid(m: CompileResult['meshes'][number]): string {
-  if (m.pageScale === undefined) return '';
-  return (
-    ` (the drawing's pixels, measured on the page's texels at scale: ${m.pageScale} — a texel is ` +
-    `${(1 / m.pageScale).toFixed(2)}px of the drawing)`
-  );
-}
-
-/**
- * The triangle budget a `MESH` line is read against: the rig's, or nothing.
- *
- * 📐 It used to be the literal `80`, which was nobody's budget — the rig quoted
- * in issue #275 declared 64, `A13_MESH_BUDGET` measured against that 64
- * correctly, and the line an author actually reads printed 80. Under the default
- * `--profile spine` `A13` is `PROF`, so the printed number is the only budget
- * figure in the output and it has to be the declared one. A rig that declares
- * none says so in the same words `A13` SKIPs in, rather than being given a wall.
- */
-function meshBudget(rig: CompileResult['rig']): string {
-  return rig.meshTriangleBudget === null ? '(no budget declared)' : `(budget ${rig.meshTriangleBudget})`;
-}
-
-/**
- * The `MEMBER` report block — a group track's per-member values, side by side
- * (issue #295).
- *
- * ## Why side by side is the whole point
- *
- * The complaint that filed #295 was not the line count. `gallery/portrait`'s
- * held yaw put six sibling bones' `translatex` in six separate tracks, and the
- * reason that is bad is that **nobody can see a wrong sign in a column that is
- * eighty lines from its neighbours.** FACE §3 makes the same argument from the
- * other side: a residual is 1–6 units where a total is 30–40, and the split is
- * *an auditing decision before it is a rigging one*. So the report's job is to
- * put the numbers in the arrangement the audit needs — one row per member, one
- * block per key — which is exactly the arrangement the emitted format cannot
- * have, because Spine keys one bone per timeline.
- *
- * ## It quotes; it does not re-derive
- *
- * The same rule as the `DEFORM` block. Every value here is the one the compiler
- * **emitted**, carried on `result.trackDerivations`, so the block and the
- * artifact cannot disagree. `derived` and `formula` are the model's own strings
- * from `src/trackgen.ts`, so the block names the closed form the spec stated
- * rather than a second reading of it.
- *
- * ## What it deliberately does not print
- *
- * **Tracks whose members all share one value** — the ordinary `groups` entry.
- * There is one number there and the timelines above already show it on every
- * member; a table of six identical rows would be a tautology, and the block
- * exists to make a *difference* visible. `look_l`/`look_r` in the worked example
- * are exactly that case and they are right to be absent from here.
- *
- * **`stagger`.** A per-member time offset is printed as it always was — on each
- * member's own timeline, where the shifted key times are. Repeating it here
- * would put one lag in two places.
- */
-function memberReportLines(result: CompileResult): string[] {
-  if (result.trackDerivations.length === 0) return [];
-  const out: string[] = [
-    '',
-    'group members  (the per-member values of one track, side by side — issue #295)',
-    '  ..    a row per member and a block per key, because a wrong sign is visible in a column of six and',
-    '  ..    invisible in six tracks. Values are the EMITTED ones, so this and the artifact cannot disagree',
-    '  ..    a group whose members all share one value is not here: there is one number and the timelines',
-    '  ..    above already carry it. `stagger` is not here either — the shifted key times are on those timelines',
-  ];
-  for (const entry of result.trackDerivations) {
-    const states =
-      entry.model === null
-        ? 'stated per member'
-        : `derive ${entry.model.kind}  ${entry.model.stated}  -> ${entry.model.projection === 'shift' ? 'the displacement' : 'the narrowing'}`;
-    out.push(
-      `  MEMBER  ${entry.animation}  ${entry.targetKind} "${entry.target}".${entry.property}  ` +
-        `t=${entry.time.toFixed(6)}  ${entry.members.length} member(s)  ${states}`,
-    );
-    if (entry.model !== null) {
-      out.push(`          ${entry.model.formula}`);
-      for (const line of entry.model.derived) out.push(`            ${line}`);
-    }
-    const width = Math.max(6, ...entry.members.map((m) => m.member.length));
-    for (let i = 0; i < entry.members.length; i++) {
-      const m = entry.members[i];
-      const value = Array.isArray(m.value) ? m.value.join(', ') : JSON.stringify(m.value);
-      // The model's own row carries the two inputs that produced the value — the
-      // coordinate it read off the rig and the depth the spec stated — because
-      // "5.513" alone is a number a reader can only take on trust, and `−62` and
-      // `150` beside it are a claim they can check.
-      const from = entry.model === null ? '' : `  <- ${entry.model.members[i].at >= 0 ? ' ' : ''}${entry.model.members[i].at} at depth ${entry.model.members[i].depth}`;
-      out.push(`            ${m.member.padEnd(width)}  ${value.padStart(12)}${from}`);
-    }
-  }
-  return out;
-}
-
-/**
- * The `DEFORM` report block — what each deform key does to the geometry, per key
- * and then per animation (issue #316).
- *
- * ## Why this is a report and not an assertion
- *
- * Because a 3× stretch is a real thing to author, for the same reason issue #277
- * settled mesh coverage as a printed figure on authored geometry rather than a
- * bar. The one deformed-geometry fault that has no legitimate counter-example is
- * the fold, and that one already IS an assertion —
- * `A39_DEFORM_KEEPS_TRIANGLE_WINDING`. What this block adds is **the approach to
- * that wall**: FACE §4.2's table of ratios down to the fold at 31.37° was
- * measured by rendering seven variants of `gallery/portrait` and looking at them,
- * and `0.637` was a number an author derived from the closed form rather than one
- * the tool printed.
- *
- * ## It quotes; it does not re-derive
- *
- * - the reversal and collapse counts are the **survey's**, which is A39's own
- *   survey ([`src/deformmeasure.ts`](src/deformmeasure.ts)) — one measurement,
- *   two readers, so the block and the gate cannot disagree about a fold;
- * - 🔒 and so is **the frame each key was posed in** (issue #407), which every
- *   `DEFORM` line now names: `on a track`, or the slider that applies the
- *   animation and the dial value its own mapping had to be inverted to. The
- *   derivation moved and the report had to move with it — a block that went on
- *   printing the same figures under a changed meaning would be worse than the
- *   red it replaced;
- * - a key's model is the **compiler's** `transform` report (§4.11.1), so the
- *   block names the same `kind` and parameters the spec stated;
- * - the fold ANGLE is nowhere here. It is A39's, derived at run time from the
- *   grid, and a second copy of it printed beside a ratio would be a number that
- *   goes stale when somebody moves a column;
- * - and a key the gate read **no winding** off — because the slot draws no pixels
- *   of the mesh at that key's own time (issue #401) — says so on a `skipped` line
- *   with the survey's own sentence, and is kept out of the rollup's counts,
- *   because that line ends by claiming A39 reads the same two;
- * - the **spans** between the keys are the survey's too (issue #403). A `BETWEEN`
- *   line appears wherever the closed form found a fold at a time no key lands
- *   on, whether the gate refuses it or passes it over because nothing is drawn
- *   there — and a `spans` line says how many were scanned even when nothing was
- *   found, because a scan that ran and found nothing has to be distinguishable
- *   from a scan that never ran.
- *
- * ## And what it deliberately does not print
- *
- * **Deformed coverage**, which #296 asked for. The coverage figure is rasterised
- * from the attachment's **uvs** against the part's alpha, and a deform moves
- * positions and never uvs — so it is identical at every key by construction, and
- * a `coverage 100.00% (setup 100.00%)` line would be a tautology wearing a
- * measurement's clothes. The header line says so and points at `meshes`, because
- * an author who came here asking whether their deform broke the coverage
- * deserves the answer rather than a silence. What does move is the stretch.
- */
-function deformReportLines(result: CompileResult, exempt: ReadonlySet<string>, poser: PoserName | undefined, label: string): string[] {
-  // Read and posed through rigc's own core over the model document the build carries (issues #969, #1019) —
-  // spine-core is not touched — and through spine-core under `--poser spine` or when the core refuses the
-  // document, which the block then names; `tools/survey_hashes.ts` holds the two to one block. The block
-  // itself is `deformReportBlock` (`src/deformreport.ts`), so a control renders it off either reader's survey.
-  const input = { skeletonText: result.skeletonText, atlasText: result.atlasText, modelText: modelDocument(result.model, result.skeletonText, result.atlasText), label: `the deform survey of ${label}` };
-  let survey: DeformSurvey;
-  try {
-    survey = surveyOfBuild(input, new Set(), poser === undefined ? 'auto' : poser === 'core' ? 'model' : 'spine-core');
-  } catch (err) {
-    // `--poser core` on a build the core refuses: a refusal of the invocation, as `render` and `check` give it.
-    if (poser === 'core' && err instanceof CoreInputError) throw new ExplainError(`--poser core: the core refused to pose the deform survey's model document — ${err.message}`);
-    throw err;
-  }
-  return deformReportBlock(survey, result.deformTransforms, exempt);
-}
-
-/**
- * The header the `scale` rows carry, because the figure beside them lies without
- * it.
- *
- * ⛔ Three things it has to say, and each one is a way the number is wrong if
- * taken at face value:
- *   - it is the key's OWN factor. A nonuniform parent shears its children, so
- *     the drawn area is not this product;
- *   - a key that moved only one axis has no product to state, and gets none
- *     rather than an invented 1 on the other;
- *   - a uniform scale has a product too, and it is a zoom rather than a squash.
- */
-const SCALE_PRODUCT_NOTE =
-  '..  x·y is the key\'s own local area factor: ~1.00 is the volume kept, and it is a READING, never a rule — ' +
-  'a nonuniform parent shears this, and a uniform scale has a product without being a squash';
-
-/**
- * `x·y` for a `scale` key that states both, and nothing otherwise.
- *
- * ⭐ Why it is here at all: `explain` ALREADY prints this reading for the other
- * spelling of squash and stretch. A `transform: affine` deform key reports
- * `area x1.020800`, which is exactly its own `0.88 × 1.16` — so the author who
- * reaches for the advanced spelling is told whether the volume held and the
- * author who reaches for the cheap one is not, while `docs/MOTION.md` §7 points
- * a first candidate at the cheap one on purpose. That asymmetry is the defect;
- * this is not a new kind of number (issue #377).
- *
- * 🔒 A reading and never an assertion. `deformReportLines` states the test a
- * geometric figure has to pass to become a gate — no legitimate counter-example
- * — and this fails it in quantity: a shadow, a zoom, a cartoon squash that
- * gains mass on purpose. Volume preservation is a style commitment no spec can
- * declare, so a bar here would be one consumer's house style failing correct
- * foreign data. There is no honest SKIP either: an absent declaration is not
- * "nothing to measure", it is "no way to know what was meant".
- */
-/**
- * An emitted key as the 4.3 parser reads it: every field its kind's
- * `PARSER_DEFAULTS` row lists and the key leaves out, at the row's value, then
- * the key's own fields. The emitter leaves a field at its parser default out
- * (issue #716), so a report that reads the file needs the row to say what the
- * runtime reads there — and reads it from the one table the emitter used.
- */
-function asParsed(kind: string, key: Record<string, unknown>): Record<string, unknown> {
-  const row = PARSER_DEFAULTS[kind];
-  if (row === undefined) return key;
-  const site = { object: key, previous: () => null };
-  const filled: Record<string, unknown> = {};
-  for (const field of Object.keys(row)) {
-    const value = parserReading(row, site, field);
-    if (value !== undefined) filled[field] = value;
-  }
-  return { ...filled, ...key };
-}
-
-/** An emitted key's time as the parser reads it — `0` where the key leaves it out. */
-function keyTimeOf(kind: string, key: Record<string, unknown>): unknown {
-  return asParsed(kind, key).time;
-}
-
-function scaleProduct(timelineName: string, key: Record<string, unknown>): string {
-  if (timelineName !== 'scale') return '';
-  const x = key.x;
-  const y = key.y;
-  // Both axes, or nothing: a key that moved one axis has no area factor, and
-  // defaulting the other to 1 would invent the very number being reported.
-  if (typeof x !== 'number' || typeof y !== 'number') return '';
-  return `  x·y=${(x * y).toFixed(4)}`;
-}
-
-/**
- * Read one non-negative integer flag, or its default.
- *
- * A usage error rather than a `NaN` that reaches the packer: `--padding two`
- * would otherwise place every region at NaN and write a blank page, which is a
- * green build and an empty picture.
- */
-function readIntFlag(flags: Record<string, string>, name: string, fallback: number): number {
-  const raw = flags[name];
-  if (raw === undefined) return fallback;
-  if (!/^\d+$/.test(raw)) throw new UsageError(`--${name} takes a non-negative integer, got ${JSON.stringify(raw)}`);
-  return Number(raw);
-}
-
-/**
- * Read `--page-edges`, or its default — `pot`.
- *
- * An unknown value is a usage error for `readProfile`'s reason: a typo that fell
- * back to `pot` would hand the caller who asked for the smaller page the bigger
- * one, green, and say nothing.
- */
-function readPageEdges(flags: Record<string, string>): PageEdges {
-  const raw = flags['page-edges'];
-  if (raw === undefined) return DEFAULT_PAGE_EDGES;
-  const found = PAGE_EDGES.find((e) => e === raw);
-  if (!found) throw new UsageError(`--page-edges ${JSON.stringify(raw)}; known values: ${PAGE_EDGES.join(', ')}`);
-  return found;
-}
-
-/**
- * One `DROP` line, written once because two outcomes print it.
- *
- * A build that succeeds prints it in its report; a build that REFUSES prints it
- * under the refusal (issue #671), and the two have to be the same line or the
- * failing run would be quoting a different fact from the one the green run
- * shows. What it names — a file or a region — is `droppedStateReason`'s, in the
- * compiler, beside the code that decided which of the two was consulted.
- */
-function dropLine(dropped: DroppedState): string {
-  return `  DROP  ${dropped.slot}/${dropped.state}: ${droppedStateReason(dropped)} (state not emitted)`;
-}
-
-/**
- * The rectangle a region occupies **on its page**, for a line that has already
- * said where the region is — and the empty string where the page rectangle is
- * the one `bounds:` already states.
- *
- * ## The fact no surface an author reads carried (issue #718)
- *
- * The atlas line beside this clause prints the DRAWING's size, because that is
- * what an attachment's width and height mean. A packer that turned the drawing a
- * quarter to fit it wrote `bounds:` in the drawing's orientation too. So an
- * author holding the pack and the build report had neither end of the rectangle
- * they have to cut out of the page to measure a part against a rendered frame —
- * and the one place rigc printed it was `A06`'s overlap text, reachable only
- * under `--profile spine-html`. The knowledge was in the tree the whole time:
- * `pageFootprint` has derived this rectangle for every reader of it since issue
- * #579, and nothing an author reads said it.
- *
- * ⚠️ **The condition is `pageFootprint`'s own answer, not a second reading of
- * `degrees`.** Re-spelling that predicate here is the exact duplication #579 was
- * filed on — four readers derived this rectangle and two derived it wrongly — so
- * the clause asks the function whether its answer differs from the `bounds:`
- * line, and prints only then.
- *
- * 🔸 A consequence worth stating rather than leaving to be discovered: a region
- * whose KEPT rectangle is square is silent here, because a quarter turn leaves
- * its footprint the same two numbers and there is nothing the pack does not
- * already say. The general rule — `bounds` is the unturned size, the footprint
- * is its transpose at `rotate: 90` and `rotate: 270`, and which way to turn the
- * rectangle to recover the drawing — belongs to an author's own reading and is
- * stated in `docs/AUTHORING.md` §0.2, which holds for every region including
- * that one.
- */
-function pageRectangle(region: AtlasRegion): string {
-  const foot = pageFootprint(region);
-  return foot.width === region.width && foot.height === region.height
-    ? ''
-    : `, occupies ${foot.width}x${foot.height}`;
-}
-
-function cmdBuild(flags: Record<string, string>): void {
-  const { label, opts } = resolveCut(flags);
-  const profile = readProfile(flags);
-  const packing = flags.pack !== undefined;
-  // Two combinations are refused rather than silently resolved, because in each
-  // one the two flags disagree about a single question and there is no answer
-  // that is not a guess about which the caller meant. (There were three until
-  // issue #266 — see the note below the second.)
-  if (packing && opts.atlasInPath !== undefined) {
-    throw new UsageError(
-      '--pack and --atlas-in are opposite directions through the same door: --pack MAKES an atlas out of the ' +
-        'loose parts, --atlas-in resolves the parts against one somebody already made. Pick one',
-    );
-  }
-  if (packing && flags['copy-images'] !== undefined) {
-    throw new UsageError(
-      '--pack already writes self-contained pages into --out (that is what packing is), and --copy-images copies ' +
-        'the loose part PNGs, which a packed atlas does not reference. Drop --copy-images',
-    );
-  }
-  // The copy itself happens after the gate (below). The header has to know NOW,
-  // because the skeleton text the gate reads is the skeleton text that is written
-  // — `skeleton.images` says where the parts will be (issue #370).
-  if (flags['copy-images'] !== undefined) opts.copyImages = true;
-  // `--pack --profile spine-html` used to be the third refusal here, because
-  // A06's coverage clause was "one part per page" flat and a legitimate pack
-  // arrived at the gate reading as a defect. Since issue #266's second follow-up
-  // that clause is "one part per page OR a tiling page", so the combination is
-  // now a build like any other — and it is the only one that puts the renderer's
-  // own rulebook over shared-page sampling.
-  if (!packing) {
-    for (const name of ['page-size', 'padding', 'page-edges'] as const) {
-      if (flags[name] !== undefined) throw new UsageError(`--${name} only means something with --pack`);
-    }
-  }
-  console.log(`rigc build ${label}`);
-  // Named explicitly and on their own lines rather than folded into the header
-  // above: with two input files, a header that names only one of them (the rig,
-  // historically) reads as though it were the one at fault whenever the error
-  // that follows actually comes from the other.
-  console.log(`  ..    rig    ${opts.rigPath}`);
-  console.log(`  ..    motion ${opts.motionPath}`);
-  const result = compile(opts);
-
-  if (opts.atlasInPath !== undefined) console.log(`  ..    atlas-in ${opts.atlasInPath}`);
-  console.log(`  ..    ${result.images.length} part page(s):`);
-  for (const img of result.images) {
-    // An imported part says where on the page it came from, because "resolved
-    // against a region" is the claim `--atlas-in` makes and a line that only
-    // repeated the page filename would look identical for all of them. A page
-    // that declares a `scale:` also says so and shows the texels it was read
-    // from: the size on the left is the DRAWING's and the rectangle is the
-    // pack's, and issue #267 is the report that printed the second as the first.
-    //
-    // `pageRectangle` closes the line's last silence (issue #718), and it is
-    // placed LAST rather than beside the turn it follows from, which is where
-    // the card put it. The two clauses collide nowhere else, and the collision
-    // is real: `scale 0.5 (373x106 texels)` is itself a size, so
-    // `rotate 90, occupies 106x373 scale 0.5 (…)` reads as though the footprint
-    // were the scaled quantity. As a trailing clause of the whole location
-    // phrase it is unambiguous with a `scale:` line and identical to the card's
-    // wording without one, which is every pack that has no `scale:` to state.
-    const where =
-      img.atlas === undefined
-        ? img.page
-        : `${img.page} @ ${img.atlas.x},${img.atlas.y}${img.atlas.degrees ? ` rotate ${img.atlas.degrees}` : ''}` +
-          (img.atlasScale === undefined
-            ? ''
-            : ` scale ${img.atlasScale} (${img.atlas.originalWidth}x${img.atlas.originalHeight} texels)`) +
-          pageRectangle(img.atlas);
-    console.log(`  ..      ${img.region.padEnd(24)} ${img.width}x${img.height}  <- ${where}`);
-  }
-  for (const d of result.droppedStates) console.log(dropLine(d));
-  // "The optional slots are optional" is a claim about this code path, so this
-  // code path says which ones it left out rather than being silently right.
-  for (const a of result.absentParts) {
-    console.log(`  ABSENT ${a.slot}: ${a.why} — slot not emitted`);
-  }
-  for (const m of result.meshes) {
-    console.log(
-      `  MESH  ${m.slot.padEnd(12)} ${m.kind.padEnd(8)} ${m.vertices} vertices / ${m.triangles} triangles  ` +
-        `${meshBudget(result.rig)}  bones=[${m.bones.join(', ')}]  attachments=[${m.attachments.join(', ')}]${meshFit(m)}` +
-        meshDepthNote(m) +
-        meshInfluenceNote(m),
-    );
-  }
-  for (const ph of result.physics) {
-    console.log(
-      `  PHYS  ${ph.name.padEnd(12)} bone=${ph.bone.padEnd(14)} components=[${ph.components.join(', ')}] ` +
-        `mix=${ph.mix}${ph.drivesMesh ? '  <- drives a mesh: its canvas re-rasterises while the spring settles' : ''}`,
-    );
-  }
-
-  // The model's document is spelled before the gate, so the text A18 compares
-  // is the text written, and a model the document cannot carry is refused
-  // before anything is (issue #922). It states where each region sits in the
-  // atlas written beside it (`pages`, issue #1016), so it is spelled from that
-  // atlas: under `--copy-images` the text with the copies' page names, planned
-  // here from the text alone (`plannedPageCopies`) and copied after the gate.
-  // Under `--pack` the pages move again after this gate, and the document
-  // written is the one the packed gate below spells and compares.
-  const copying = flags['copy-images'] !== undefined;
-  const writtenAtlas = (atlasText: string): string => (copying ? plannedPageCopies(atlasText, opts.outDir).atlasText : atlasText);
-  let modelText = modelDocument(result.model, result.skeletonText, writtenAtlas(result.atlasText));
-  console.log(`  ..    validate (spine-core round trip + machine assertions, profile ${profile})`);
-  const failures = runGate(result, modelText, opts, profile, writtenAtlas);
-  if (failures > 0) {
-    console.error(`rigc: ${failures} assertion(s) failed — nothing written`);
-    process.exit(1);
-  }
-
-  mkdirSync(opts.outDir, { recursive: true });
-
-  // `--copy-images`: `--out` is otherwise NOT self-contained — a page's default
-  // path is relative to the source art (often `../parts/foo.png`), which is
-  // correct for a build sitting beside the project it came from and breaks the
-  // moment the directory is zipped, committed or moved on its own (issue #217).
-  // Opt-in only: the default stays exactly what it has always been.
-  //
-  // What is copied is what the ATLAS names, not what the image list holds: under
-  // `--atlas-in` the two are different lists, and rebuilding the text from the
-  // second wrote a file the pack never contained — zero bytes for a rig that
-  // declares no parts, one fabricated page per part for a rig that does, both of
-  // them green here because the gate above had already read the compile's own
-  // text (issue #693, `src/emit.ts`).
-  let atlasText = result.atlasText;
-  if (flags['copy-images'] !== undefined) {
-    const copied = copyAtlasPages(atlasText, opts.outDir);
-    // The document's pages were spelled from the plan; the copy is held to it before anything of the pair is written.
-    if (copied.atlasText !== writtenAtlas(result.atlasText)) {
-      throw new Error(`internal: --copy-images wrote an atlas whose page names are not the ones ${MODEL_DOCUMENT_FILE} was spelled with — nothing of the pair was written`);
-    }
-    atlasText = copied.atlasText;
-    console.log(`  ..    copy-images: ${copied.pages.length} page(s) copied into ${opts.outDir}`);
-    for (const p of copied.pages) {
-      const note = p.to === basename(p.from) ? '' : '  (renamed — basename collision)';
-      console.log(`  ..      ${p.to.padEnd(24)} <- ${p.from}  (${p.regions} region(s))${note}`);
-    }
-  }
-
-  // `--pack`: the parts go onto shared pages, which are written here as real
-  // PNGs, so `--out` is self-contained by construction. The atlas above stays
-  // the one the gate just read — packing changes only the ARRANGEMENT of the
-  // bytes, and the sizes in `result.images` are still the ones measured off the
-  // loose PNGs (see src/atlas.ts's header).
-  if (packing) {
-    const packOpts = {
-      pageSize: readIntFlag(flags, 'page-size', DEFAULT_PAGE_SIZE),
-      padding: readIntFlag(flags, 'padding', DEFAULT_PADDING),
-      pageEdges: readPageEdges(flags),
-      pageStem: 'skeleton',
-    };
-    const inputs = result.images.map((img) => ({
-      region: img.region,
-      absPath: img.absPath,
-      width: img.width,
-      height: img.height,
-    }));
-    const packed = packAtlas(inputs, packOpts);
-    atlasText = packed.atlasText;
-    for (const page of packed.pages) {
-      page.plate.writePng(join(opts.outDir, page.name));
-      console.log(
-        `  ..    pack: ${page.name} ${page.width}x${page.height}, ` +
-          `${packed.placements.filter((p) => packed.pages[p.page].name === page.name).length} region(s), ` +
-          `${(page.occupancy * 100).toFixed(1)}% covered, padding ${packed.padding}` +
-          (packOpts.pageEdges === 'free' ? ', page edges free' : ''),
-      );
-    }
-    for (const place of packed.placements) {
-      console.log(
-        `  ..      ${place.region.padEnd(24)} ${place.width}x${place.height} -> ` +
-          `${packed.pages[place.page].name} @ ${place.x},${place.y}`,
-      );
-    }
-    // The pages are on disk now, so the packed pair can be gated as an artifact
-    // rather than trusted as a construction: A17 stats every page, A06 reads its
-    // IHDR back, A07 re-reads the text shape, A08 re-joins every attachment onto
-    // a region, and A18 compares a second independent compile+pack. Two gates on
-    // one build is the cost of shipping a second atlas shape.
-    console.log('  ..    validate (packed atlas, pages on disk)');
-    const packAgain = packAtlas(
-      compile(opts).images.map((img) => ({
-        region: img.region,
-        absPath: img.absPath,
-        width: img.width,
-        height: img.height,
-      })),
-      packOpts,
-    );
-    // The document written is spelled from the packed atlas, and this gate's A18 compares it with a
-    // second compile's spelled from the second, independent pack (issue #1016).
-    modelText = modelDocument(result.model, result.skeletonText, atlasText);
-    const packFailures = runGate(result, modelText, opts, profile, (text) => text, { text: atlasText, again: packAgain.atlasText });
-    if (packFailures > 0) {
-      console.error(
-        `rigc: ${packFailures} assertion(s) failed on the PACKED atlas — the pages were written to ` +
-          `${opts.outDir}, the skeleton/atlas pair was not`,
-      );
-      process.exit(1);
-    }
-  }
-
-  writeFileSync(join(opts.outDir, 'skeleton.json'), result.skeletonText);
-  writeFileSync(join(opts.outDir, 'skeleton.atlas'), atlasText);
-  // rigc's own record of the compiled rig (`rigc-compiled/3`, issue #922;
-  // its `pages` the atlas just written, issue #1016), written with the pair
-  // and only after the same gate — under `--pack`, the packed one. rigc's own posing core
-  // reads it (`readModel`, `src/core/index.ts`, issue #380's step 2).
-  writeFileSync(join(opts.outDir, MODEL_DOCUMENT_FILE), modelText);
-  console.log(`rigc: wrote ${join(opts.outDir, 'skeleton.json')}`);
-  console.log(`rigc: wrote ${join(opts.outDir, 'skeleton.atlas')}`);
-  console.log(`rigc: wrote ${join(opts.outDir, MODEL_DOCUMENT_FILE)}`);
-  // The next command is part of the message (issue #837). A green build is the
-  // moment somebody wants to see what came out, and the one page rigc writes
-  // for that is `preview` of exactly this directory — so the line names it,
-  // with the path already resolved. Printed only here: a red build wrote
-  // nothing, so there is nothing to look at and no line.
-  console.log(`rigc: look at it: rigc preview --candidate ${opts.outDir}`);
-}
-
-/**
- * Where a pair of artifacts lives, given what the caller pointed at.
- *
- * Two shapes, because rigc's own output and a foreign export are named
- * differently and both have to be gateable. rigc writes `skeleton.json` +
- * `skeleton.atlas` into a directory. Everybody else writes whatever the editor
- * called the project, and the official examples are not even consistent with
- * themselves — `7-anticipation/export/` holds `sack-pro.json`, `spineboy/export/`
- * holds two skeletons and two atlases.
- *
- * ⚠️ When more than one atlas sits beside the skeleton, this refuses to choose.
- * Guessing by name would be wrong on the corpus that motivated it: `spineboy-ess`
- * shares a longer prefix with `spineboy-run.atlas` than with the `spineboy.atlas`
- * it actually uses, so the plausible heuristic picks the wrong file and every
- * attachment then resolves against the wrong pixels — silently, which is the
- * exact failure mode this tool exists to remove.
- */
-function resolveArtifacts(target: string, atlasFlag: string | undefined): { skeletonPath: string; atlasPath: string } {
-  const abs = resolve(target);
-  if (!existsSync(abs)) throw new UsageError(`nothing at ${abs}`);
-  if (statSync(abs).isDirectory()) {
-    return {
-      skeletonPath: join(abs, 'skeleton.json'),
-      atlasPath: atlasFlag ? resolve(atlasFlag) : join(abs, 'skeleton.atlas'),
-    };
-  }
-  if (!abs.endsWith('.json')) throw new UsageError(`${abs} is neither a directory nor a .json skeleton`);
-  if (atlasFlag) return { skeletonPath: abs, atlasPath: resolve(atlasFlag) };
-  const dir = dirname(abs);
-  const atlases = readdirSync(dir)
-    .filter((f) => f.endsWith('.atlas'))
-    .sort();
-  if (atlases.length === 1) return { skeletonPath: abs, atlasPath: join(dir, atlases[0]) };
-  if (atlases.length === 0) throw new UsageError(`no .atlas beside ${abs}; name one with --atlas <path>`);
-  throw new UsageError(
-    `${atlases.length} atlases beside ${abs} (${atlases.join(', ')}); name the right one with --atlas <path> ` +
-      '— guessing by filename is how an attachment quietly resolves against the wrong page',
-  );
-}
-
-function cmdValidate(flags: Record<string, string>, positional: string[]): void {
-  // A bare directory validates what is on disk. Naming the cut as well lets the
-  // gate re-derive the declared durations and the structural expectations, which
-  // a directory alone cannot supply — and the report says which it had.
-  const named = flags.cut !== undefined || flags.rig !== undefined;
-  const profile = readProfile(flags);
-  const derivedOpts = named ? resolveCut(flags).opts : null;
-  const { skeletonPath, atlasPath } = resolveArtifacts(derivedOpts ? derivedOpts.outDir : (positional[0] ?? '.'), flags.atlas);
-  console.log(`rigc validate ${skeletonPath}`);
-  console.log(`  ..    atlas ${atlasPath}`);
-  const skeletonText = readFileSync(skeletonPath, 'utf8');
-  const atlasText = readFileSync(atlasPath, 'utf8');
-  const derived = derivedOpts ? compile(derivedOpts) : null;
-
-  const report = validate({
-    skeletonText,
-    atlasText,
-    atlasDir: dirname(atlasPath),
-    declaredDurations: derived?.declaredDurations,
-    rig: derived?.rig,
-    profile,
-  });
-  for (const line of reportLines(report)) console.log(line);
-  if (report.failures.length > 0) {
-    console.error(`rigc: ${report.failures.length} assertion(s) failed`);
-    process.exit(1);
-  }
-  console.log('rigc: green');
-}
-
-/**
- * `--as <candidate>=<reference>`, one pair per occurrence.
- *
- * ⚠️ Spelled with a pair where `check --as <name>` takes one name, and the
- * difference is in what the two commands have on the other side. `check`
- * measures against a rendered frame SET, which already carries the reference
- * animation's name in its own directory, so one name closes the gap. `diff` has
- * two skeletons and either may have its own vocabulary, so one name says which
- * shot on which side and leaves the other unanswered. The direction — candidate
- * first — is the one `bonedist`'s correspondence file already writes its
- * `animations` map in.
- *
- * Every refusal here is a UsageError because every one of them is about the
- * flag's own value, and each names what it read: a value with no `=`, an empty
- * side, a name repeated on either side, and a name no animation on that side
- * answers to. ⛔ The last of those is a refusal rather than a dropped pair for
- * the reason a miss is refused by name everywhere else in this tool — a typo
- * that quietly measured less would be a report about a pairing the caller did
- * not ask for.
- */
-function readAnimationPairs(values: string[], candidate: unknown, reference: unknown): DiffAnimationPair[] {
-  const animationsOf = (root: unknown): string[] => {
-    const anims = (root as { animations?: unknown } | null)?.animations;
-    return typeof anims === 'object' && anims !== null && !Array.isArray(anims) ? Object.keys(anims) : [];
-  };
-  const have = { candidate: animationsOf(candidate), reference: animationsOf(reference) };
-  const pairs: DiffAnimationPair[] = [];
-  for (const value of values) {
-    const at = value.indexOf('=');
-    if (at < 0) {
-      throw new UsageError(
-        `--as ${JSON.stringify(value)} is not a pair. It takes <candidate>=<reference> — two animation names joined ` +
-          'by `=`, because diff compares two skeletons and either may have its own name for the shot. The candidate ' +
-          `has [${have.candidate.join(', ') || 'none'}] and the reference has [${have.reference.join(', ') || 'none'}].`,
-      );
-    }
-    const pair = { candidate: value.slice(0, at), reference: value.slice(at + 1) };
-    if (pair.candidate === '' || pair.reference === '') {
-      throw new UsageError(
-        `--as ${JSON.stringify(value)} leaves the ${pair.candidate === '' ? 'candidate' : 'reference'} side empty; ` +
-          'it takes <candidate>=<reference>, a name on each side',
-      );
-    }
-    for (const side of ['candidate', 'reference'] as const) {
-      if (!have[side].includes(pair[side])) {
-        throw new UsageError(
-          `--as ${JSON.stringify(value)} names no ${side} animation: the ${side} has ` +
-            `[${have[side].join(', ') || 'none'}] and not ${JSON.stringify(pair[side])}`,
-        );
-      }
-      if (pairs.some((p) => p[side] === pair[side])) {
-        throw new UsageError(
-          `--as pairs the ${side} animation ${JSON.stringify(pair[side])} twice; each animation may be in one pair, ` +
-            'or the block would compare one shot against two',
-        );
-      }
-    }
-    pairs.push(pair);
-  }
-  return pairs;
-}
-
-function cmdDiff(flags: Record<string, string>, lists: Record<string, string[]>, positional: string[]): void {
-  const [candidate, reference] = positional;
-  if (!candidate || !reference) throw new UsageError('diff takes two paths: <candidate.json> <reference.json>');
-  const candidatePath = resolve(candidate);
-  const referencePath = resolve(reference);
-  for (const path of [candidatePath, referencePath]) {
-    if (!existsSync(path)) throw new UsageError(`nothing at ${path}`);
-  }
-  const candidateJson = readJsonFile(candidatePath);
-  const referenceJson = readJsonFile(referencePath);
-  const animationPairs = readAnimationPairs(lists.as ?? [], candidateJson, referenceJson);
-  const report = diffSkeletons(candidateJson, referenceJson, { animationPairs });
-  console.log('rigc diff');
-  for (const line of diffLines(report, { candidate: candidatePath, reference: referencePath })) console.log(line);
-  if (flags.json !== undefined) {
-    // ⚠️ `...report` carries its OWN `candidate` and `reference` — the raw
-    // per-side counts. Spelling the paths under those two names put them on
-    // the losing side of the spread, so the written report named neither file
-    // it compared. The paths get their own keys.
-    writeJson(flags.json, { candidatePath, referencePath, ...report });
-  }
-}
-
-/**
- * check — how close does the candidate LOOK to the reference frames?
- *
- * ⭐ The gate cannot see a wrong animation. It parses, it steps, it refuses the
- * degenerate — and a rig whose easings are all reversed passes it green, which is
- * not a hypothetical: ladder rung 1's first honest run shipped exactly that build
- * and the validator was structurally incapable of noticing. `diff` cannot see it
- * either, because it compares structure and a reversed curve is the same curve
- * count. The only thing that can is a picture, so this renders the candidate into
- * the reference's own frame and compares pixels.
- *
- * 🔒 It never reads the reference skeleton — see `src/check.ts`. That is what
- * keeps it usable **inside** an authoring loop rather than at the finish line the
- * way `bench` is: an author may run it as often as they like without their run
- * stopping being an authoring run.
- *
- * There is no pass mark, for the same reason `diff` has none.
- */
-function readCheckFlags(
-  flags: Record<string, string>,
-): 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');
-    }
-    out.framing = flags.framing;
-  }
-  if (flags.fps !== undefined) {
-    const fps = Number(flags.fps);
-    if (!Number.isFinite(fps) || fps <= 0) throw new UsageError('--fps must be a positive number');
-    out.fps = fps;
-  }
-  if (flags.viewport !== undefined) {
-    const parts = flags.viewport.split(',').map((s) => Number(s.trim()));
-    if (parts.length !== 4 || parts.some((n) => !Number.isFinite(n))) {
-      throw new UsageError('--viewport takes four numbers: <x>,<y>,<width>,<height> — the world box, y up');
-    }
-    if (parts[2] <= 0 || parts[3] <= 0) throw new UsageError('--viewport width and height must be positive');
-    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)) {
-      throw new UsageError(
-        `--texture-from ${path} is not a file. It takes the ATLAS the reference frames were rendered through — the ` +
-          "example's own .atlas — so check can measure how much of the MAE is texture resampling.",
-      );
-    }
-    out.textureFrom = { atlasText: readFileSync(path, 'utf8'), atlasDir: dirname(path), label: flags['texture-from'] };
-  }
-  return out;
-}
-
-function runCheck(
-  candidate: string,
-  atlasFlag: string | undefined,
-  framesDir: string,
-  flags: Record<string, string>,
-  plates?: CheckPlates,
-): CheckReport {
-  const { skeletonPath, atlasPath, atlasText } = resolveDrawable(candidate, atlasFlag);
-  // The poser is `render`'s choice, over the same two files (issue #968): the
-  // paths are what `candidatePosers` looks beside for `skeleton.model.json`.
-  const poser = readPoserFlag(flags);
-  return checkAgainstFrames({
-    skeletonText: readSkeletonText(skeletonPath),
-    atlasText,
-    atlasDir: dirname(atlasPath),
-    framesDir,
-    labels: { skeleton: skeletonPath, atlas: atlasText === null ? `${atlasPath} — not there (${ATLAS_ABSENT})` : atlasPath },
-    candidatePaths: { skeleton: skeletonPath, atlas: atlasPath },
-    ...(poser === undefined ? {} : { poser }),
-    ...readCheckFlags(flags),
-    ...(plates === undefined ? {} : { plates }),
-  });
-}
-
-/**
- * `check --out <dir>`, refused before anything is compared when it cannot be
- * written — see `src/checkpics.ts` for what goes there.
- *
- * Two refusals and no others. A **file** at the path is not a directory of
- * pictures, and saying so beats the `ENOTDIR` a write would throw after the
- * whole comparison had run. And a directory that **is `--frames` or holds it**
- * is refused because `<out>/<set>/` is cleared and `<out>/frames.json` written,
- * as `render` does to its own: there, that is the reference set being deleted by
- * the command that reads it — `check --frames render --out render` would clear
- * `render/heavy` and put a picture sidecar where the frames' own was. A fresh
- * path, and an existing directory anywhere else, are written to.
- */
-function readCheckOut(outFlag: string, framesFlag: string): string {
-  const out = resolve(outFlag);
-  if (existsSync(out) && !statSync(out).isDirectory()) {
-    throw new UsageError(`check: --out ${out} is a file; it names a directory`);
-  }
-  const frames = resolve(framesFlag);
-  const within = relative(out, frames);
-  if (within === '' || (!within.startsWith('..') && !isAbsolute(within))) {
-    throw new UsageError(
-      `check: --out ${out} ${within === '' ? 'is' : 'holds'} --frames ${frames}; the pictures would be written ` +
-        'over the frames they are pictures of (each set directory under --out is cleared first) — name a directory ' +
-        'outside it',
-    );
-  }
-  return out;
-}
-
-function cmdCheck(flags: Record<string, string>): void {
-  if (flags.candidate === undefined) throw new UsageError('check needs --candidate <dir | skeleton.json>');
-  if (flags.frames === undefined) throw new UsageError('check needs --frames <dir> — a rendered reference frame set');
-  const out = flags.out === undefined ? null : readCheckOut(flags.out, flags.frames);
-  const allFrames = flags['all-frames'] !== undefined;
-  // Only asked for when there is somewhere to put the pictures: without --out
-  // nothing is kept, and the run is the run it was before --out existed.
-  const plates = out === null ? undefined : new CheckPlates({ allFrames });
-  const report = runCheck(flags.candidate, flags.atlas, flags.frames, flags, plates);
-  console.log('rigc check');
-  for (const line of checkLines(report, { allFrames })) console.log(line);
-  if (flags.json !== undefined) writeJson(flags.json, report);
-  if (out !== null && plates !== undefined) {
-    for (const set of writeCheckPictures(out, report, plates, { allFrames })) {
-      const which = set.frames.length === 0 ? 'nothing compared' : set.every ? 'every compared frame' : 'the frames worth reading';
-      console.log(`  ..    ${set.dir.padEnd(16)} ${set.frames.length} picture(s), ${which} -> ${set.path}`);
-    }
-    console.log(`rigc: wrote ${join(out, FRAMES_SIDECAR)}`);
-  }
-}
-
-function writeJson(target: string, body: unknown): void {
-  const out = resolve(target);
-  mkdirSync(dirname(out), { recursive: true });
-  writeFileSync(out, `${JSON.stringify(body, null, 2)}\n`);
-  console.log(`rigc: wrote ${out}`);
-}
-
-// ---------------------------------------------------------------------------
-// seeing the result — render and preview
-// ---------------------------------------------------------------------------
-//
-// ⭐ Why two commands exist for one question. `validate` says the artifact is
-// valid, `check` says how close it is to reference frames — and a first user has
-// neither a reference nor any way to look at what they built. A rig whose head
-// sits visibly off its torso passes the gate, loads in `spine-core` and steps
-// cleanly, because the offsets are the ones the spec asked for. The only remedy
-// is looking (issue #216).
-//
-// `render` looks with OUR rasteriser: PNGs on disk, no browser, no network, and
-// the same frame geometry `check` compares against — so its output is a frame set
-// like any other, sidecar included. `preview` looks with ESOTERIC'S, in one HTML
-// file, which is the stronger statement of the two: a rig that plays there has
-// been played by the reference implementation rather than by ours (issue #151).
-//
-// Both take a COMPILED artifact rather than a rig and motion spec. That is what
-// `check`, `bench` and `validate` all take, it is what `build --out` leaves
-// behind, and it keeps `--out` meaning one thing per command instead of naming
-// the build directory on the way in and the pictures on the way out.
-
-/** Both commands' shared front door: which artifact, and what is in it. */
-function resolveViewable(flags: Record<string, string>): {
-  skeletonPath: string;
-  atlasPath: string;
-  atlasDir: string;
-} {
-  if (flags.candidate === undefined) {
-    throw new UsageError('needs --candidate <dir | skeleton.json> — the directory `build --out` wrote');
-  }
-  const { skeletonPath, atlasPath } = resolveArtifacts(flags.candidate, flags.atlas);
-  for (const path of [skeletonPath, atlasPath]) {
-    if (!existsSync(path)) throw new UsageError(`nothing at ${path}`);
-  }
-  return { skeletonPath, atlasPath, atlasDir: dirname(atlasPath) };
-}
-
-/** What `render` and `check` say where a rigc build's atlas is not there (issue #1020). */
-const ATLAS_ABSENT = 'a build the core poses from a rigc-compiled/2 or /3 document needs none';
-
-/**
- * The candidate `render` and `check` draw, with its atlas text — or `null`
- * where the atlas file is not there and need not be (issue #1020).
- *
- * ⭐ A rigc build is drawn by the core from its `skeleton.model.json`, and a
- * `rigc-compiled/2` document states where each region sits on its page, so
- * the build's `skeleton.atlas` is not needed to draw it. Its absence is let
- * through here only where it can be that case — no `--atlas` named, a model
- * document beside the skeleton, and no atlas beside it at all — and the poser
- * choice decides the rest: anything that is read through an atlas after all
- * (a `rigc-compiled/1` document, a build the core refuses) is refused there
- * naming the file and why (`CandidateAtlasError`). An atlas that IS there is
- * read, as it always was: the core holds it to the document's `pages` and
- * draws through spine-core, saying why, when it is not the one the build
- * wrote (#1016), and `check` reads its `scale:` lines for the texture note.
- * Everywhere else this is `resolveViewable`'s refusal, word for word.
- */
-function resolveDrawable(target: string, atlasFlag: string | undefined): { skeletonPath: string; atlasPath: string; atlasText: string | null } {
-  const abs = resolve(target);
-  if (atlasFlag === undefined && existsSync(abs)) {
-    const directory = statSync(abs).isDirectory();
-    const skeletonPath = directory ? join(abs, 'skeleton.json') : abs;
-    const dir = dirname(skeletonPath);
-    const atlasPath = join(dir, 'skeleton.atlas');
-    const noAtlas = directory ? !existsSync(atlasPath) : abs.endsWith('.json') && !readdirSync(dir).some((f) => f.endsWith('.atlas'));
-    if (noAtlas && existsSync(join(dir, MODEL_DOCUMENT_FILE))) {
-      if (!existsSync(skeletonPath)) throw new UsageError(`nothing at ${skeletonPath}`);
-      return { skeletonPath, atlasPath, atlasText: null };
-    }
-  }
-  const { skeletonPath, atlasPath } = resolveViewable({ candidate: target, ...(atlasFlag === undefined ? {} : { atlas: atlasFlag }) });
-  return { skeletonPath, atlasPath, atlasText: readFileSync(atlasPath, 'utf8') };
-}
-
-/** `--animation`, checked against what the skeleton actually carries. */
-function readAnimationFlag(flags: Record<string, string>, available: string[]): string | undefined {
-  const name = flags.animation;
-  if (name === undefined) return undefined;
-  if (!available.includes(name)) {
-    throw new UsageError(
-      `no animation ${JSON.stringify(name)} in this skeleton; it has [${available.join(', ') || 'none'}]`,
-    );
-  }
-  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;
-}
-
-/**
- * `--slot` / `--hide`, resolved against the skeleton under the skin this run
- * poses it in — or refused as a usage error, nothing written (issue #835).
- *
- * The rule itself is `slotSubsetOf`'s in `src/render.ts`, which `piecesOf`
- * applies too: it is read here only so a miss exits 2 with the usage beside
- * it before a directory is created, rather than surfacing from the sampler.
- */
-function readSlotSubsetFlags(
-  flags: Record<string, string>,
-  facts: SkeletonFacts,
-  skin: string | undefined,
-): SlotSubset | undefined {
-  const list = (raw: string | undefined): string[] | undefined =>
-    raw === undefined ? undefined : raw.split(',').map((name) => name.trim()).filter((name) => name !== '');
-  try {
-    return facts.subset({ slots: list(flags.slot), hidden: list(flags.hide) }, skin);
-  } catch (err) {
-    if (err instanceof SlotSubsetError) throw new UsageError(err.message);
-    throw err;
-  }
-}
-
-/**
- * `--poser` as spelled, checked against the posers there are — shared by
- * `render` and `check`. On `render` it is read where its refusal has always
- * stood, after the candidate's own flags; the candidate is loaded before that
- * with the spelling as given (`posersAsked`), so a rigc build the core poses
- * is chosen without loading spine-core (issue #1014).
- */
-function readPoserFlag(flags: Record<string, string>): PoserName | undefined {
-  const raw = flags.poser;
-  const forced = POSER_NAMES.find((name) => name === raw);
-  if (raw !== undefined && forced === undefined) {
-    throw new UsageError(`--poser ${JSON.stringify(raw)}: known posers are ${POSER_NAMES.join(', ')}`);
-  }
-  return forced;
-}
-
-/** `--poser` as the candidate is loaded with: a known spelling, or the input's own choice — the spelling is refused later, by `readPoserFlag`. */
-function posersAsked(flags: Record<string, string>): PoserName | undefined {
-  return POSER_NAMES.find((name) => name === flags.poser);
-}
-
-/** A resolved subset as the one field it is spelled as, in `PoseOptions` and in `frames.json` alike. */
-function subsetFields(subset: SlotSubset | undefined): { slots?: string[]; hidden?: string[] } {
-  if (subset === undefined) return {};
-  return subset.mode === 'slots' ? { slots: subset.names } : { hidden: subset.names };
-}
-
-function readPositiveNumber(flags: Record<string, string>, key: string, fallback: number, least: number): number {
-  const raw = flags[key];
-  if (raw === undefined) return fallback;
-  const value = Number(raw);
-  if (!Number.isFinite(value) || value < least) throw new UsageError(`--${key} must be a number of at least ${least}`);
-  return value;
-}
-
-/**
- * Does this skeleton declare a setup stage — a numeric width AND height?
- *
- * Read off the file's header for `preview`, which never loads one; `render`
- * reads the same statement off its candidate (`SkeletonFacts.declaresStage`:
- * the header again on a rigc build the core poses, the loaded `SkeletonData`
- * on an export). Both are the same two fields, because
- * `SkeletonJson` copies them across unconditionally (`SkeletonJson.js:70-73`),
- * so a header that omits them leaves `undefined` on a field typed `number`.
- */
-function declaresSetupStage(header: { width?: unknown; height?: unknown }): boolean {
-  return typeof header.width === 'number' && typeof header.height === 'number';
-}
-
-/** The `skeleton` block of a skeleton file's text, or an empty one where it has none. */
-function skeletonHeaderOf(skeletonText: string): { width?: unknown; height?: unknown } {
-  const root = JSON.parse(skeletonText) as { skeleton?: { width?: unknown; height?: unknown } };
-  return root.skeleton ?? {};
-}
-
-/**
- * What `render` and `preview` say of their framing on a skeleton that declares
- * no stage (issue #714).
- *
- * ⚠️ **Neither frames to a stage on ANY skeleton**, so this is not a fallback
- * being announced: `framingViewport` is the union of every animation's posed
- * bounds, and the Spine Web Player's `calculateAnimationViewport` samples the
- * playing animation's bounds whenever its config states no viewport box, which
- * `buildPreview` never does. The line is printed only where a stage is absent
- * because that is the one case where a reader can ask *what box stood in for
- * it* — and the answer has to be "none", said, rather than a rectangle that looks
- * like a default. On a staged skeleton the output is the bytes it always was.
- */
-const STAGELESS_FRAMING = {
-  render:
-    'framing  the posed extent of every animation, padded — this skeleton declares no stage, and nothing stands ' +
-    'in for one: render frames to the posed extent whether or not a stage is declared',
-  preview:
-    "framing  the Spine Web Player's own: the posed extent of the animation it plays — this skeleton declares no " +
-    'stage, and nothing stands in for one: the player frames that way whether or not a stage is declared',
-} as const;
-
-/**
- * render — the frame series, drawn by the same rasteriser `check` measures with.
- *
- * The framing is measured across EVERY animation at `FRAMING_FPS` and not across
- * the one being written, which is `src/render.ts`'s own invariant: the viewport is
- * a property of the shot, so two animations of one rig — and the same animation at
- * two rates — land on one pixel grid and stay comparable.
- */
-function cmdRender(flags: Record<string, string>): void {
-  if (flags.candidate === undefined) {
-    throw new UsageError('needs --candidate <dir | skeleton.json> — the directory `build --out` wrote');
-  }
-  const { skeletonPath, atlasPath, atlasText } = resolveDrawable(flags.candidate, flags.atlas);
-  const atlasDir = dirname(atlasPath);
-  const fps = readPositiveNumber(flags, 'fps', PROTOCOL_FPS, 1);
-  const maxSide = readPositiveNumber(flags, 'max', 256, 16);
-  const outRoot = resolve(flags.out ?? 'render');
-  const geometry = flags.geometry !== undefined;
-  // Refused together rather than one of them ignored (issue #864). The export
-  // records every slot's whole geometry, because a subset is a statement about
-  // which pixels are DRAWN and the pose is the same whatever a picture leaves
-  // out — so a geometry.json beside a subset's frames would describe slots
-  // those frames do not draw, and one that dropped them would stop being the
-  // pose. The whole-rig run writes the same file either way.
-  if (geometry) {
-    for (const flag of ['slot', 'hide'] as const) {
-      if (flags[flag] !== undefined) {
-        throw new UsageError(
-          `--geometry takes no --${flag}: it records every slot's whole geometry, which a subset of the drawn slots ` +
-            `does not change. Run \`rigc render --geometry\` on the whole rig for the file, and --${flag} ` +
-            `${flags[flag]} without --geometry for the pictures — both land on the same grid`,
-        );
-      }
-    }
-  }
-
-  console.log('rigc render');
-  console.log(`  ..    skeleton ${skeletonPath}`);
-  console.log(`  ..    atlas    ${atlasPath}${atlasText === null ? ` — not there (${ATLAS_ABSENT})` : ''}`);
-  // Which implementation of the posing seam draws this (issue #968), chosen
-  // before anything is read off the candidate (issue #1014): a rigc build the
-  // core poses — `skeleton.model.json` beside the pair — reads its names, its
-  // subset roster and its pages without loading spine-core at all, and with a
-  // rigc-compiled/2 document without its atlas either (issue #1020).
-  const { choice, facts, pages } = loadCandidate(
-    { skeletonText: readSkeletonText(skeletonPath), atlasText, atlasDir, label: skeletonPath },
-    { skeleton: skeletonPath, atlas: atlasPath },
-    posersAsked(flags),
-  );
-  const only = readAnimationFlag(flags, [...facts.animations]);
-  const skin = readSkinFlag(flags, [...facts.skins]);
-  const subset = readSlotSubsetFlags(flags, facts, skin);
-  // 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.
-  // The subset rides on the same object and `framingViewport` takes it off, so
-  // the frames draw the subset and the box is still the whole rig's.
-  const pose =
-    skin === undefined && subset === undefined
-      ? undefined
-      : { ...(skin === undefined ? {} : { skin }), ...subsetFields(subset) };
-  if (skin !== undefined) console.log(`  ..    skin     ${skin}`);
-  if (subset !== undefined) console.log(`  ..    ${subset.mode.padEnd(8)} ${subset.names.join(', ')}`);
-
-  // Rigc's own core when the candidate is a rigc build, and spine-core
-  // otherwise, or where the core refuses the input by name. Never silently:
-  // the `poser` line below says which, and why. `--poser` is refused here, where
-  // it always was: a spelling there is no poser for, then `core` on an input
-  // that cannot carry it.
-  readPoserFlag(flags);
-  refuseUnchosen(choice);
-
-  // Everything is posed before anything is written, so a core refusal partway
-  // re-poses the whole input on spine-core rather than leaving half of a frame
-  // set drawn by each.
-  const posed = throughPoser(choice, (poser, roster) => {
-    // `null` is a skeleton that posed no vertex at all. One that posed a vertex
-    // it cannot frame — Infinity or NaN — is thrown from the framing as a
-    // `GeometryError` naming the number (issue #873), and one whose every vertex
-    // sits at one point — every drawn bone unposed by the skin, or collapsed — as
-    // an `UnframeablePoseError` (issue #997); neither reaches this. The roster is what
-    // lets the second name the skins that pose a bone, whichever poser draws.
-    const viewport = framingViewport(poser, maxSide, pose, roster);
-    if (!viewport) {
-      throw new UsageError(
-        `${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`,
-      );
-    }
-
-    // `sampleAll` covers the skeleton with no animation at all, which files its one
-    // setup-pose frame under the reserved name. Narrowing to one animation reuses
-    // the same sampler rather than a second path through it.
-    //
-    // `--geometry` rides on the SAME call (issue #864): the bones and the whole
-    // attachments are read off the skeleton at the step that drew each frame, so
-    // the export's grid is this frame set's by construction.
-    const sampling = geometry ? { ...pose, bones: true, geometry: true } : pose;
-    const sampled: Map<string, Frame[]> =
-      only === undefined
-        ? sampleAll(poser, fps, sampling)
-        : new Map([[only, sampleAnimation(poser, only, fps, sampling)]]);
-    // Every file's text before the first write, so a refused number leaves the
-    // output directory as it was rather than half of a frame set behind it.
-    const geometryTexts = new Map<string, string>();
-    if (geometry) {
-      for (const [name, frames] of sampled) {
-        const animation = name === SETUP_POSE_DIR && facts.animations.length === 0 ? null : name;
-        geometryTexts.set(name, geometryText(geometryFileOf(poser, animation, fps, frames, viewport, skin)));
-      }
-    }
-    return { viewport, sampled, geometryTexts };
-  });
-  const { viewport, sampled, geometryTexts } = posed.value;
-  console.log(`  ..    poser    ${posed.note}`);
-  console.log(`  ..    ${viewport.width}x${viewport.height}px at ${fps} fps, ${sampled.size} set(s) -> ${outRoot}`);
-  if (!facts.declaresStage) console.log(`  ..    ${STAGELESS_FRAMING.render}`);
-
-  mkdirSync(outRoot, { recursive: true });
-  const sets: FrameSet[] = [];
-  for (const [name, frames] of sampled) {
-    // Same naming as a reference render: the protocol rate says nothing, any
-    // other rate says itself, so two rates of one animation sit side by side.
-    const dirName = fps === PROTOCOL_FPS ? name : `${name}@${fps}fps`;
-    const dir = join(outRoot, dirName);
-    // Cleared rather than written over: a shorter animation would otherwise leave
-    // the tail of a longer previous run on disk, and stale frames in a frame set
-    // are indistinguishable from real ones.
-    if (existsSync(dir)) rmSync(dir, { recursive: true });
-    mkdirSync(dir, { recursive: true });
-    for (let i = 0; i < frames.length; i++) {
-      renderFrame(frames[i], pages, viewport, BACKGROUND).writePng(join(dir, `f${String(i).padStart(4, '0')}.png`));
-    }
-    // One frame has nothing to compare itself against, so it gets no sheet — it
-    // would be the same picture with a border and a "0" on it.
-    const sheet = frames.length > 1;
-    if (sheet) contactSheet(frames, pages, viewport, SHEET_TILE).writePng(join(dir, SHEET_FILE));
-    const geometryOut = geometryTexts.get(name);
-    if (geometryOut !== undefined) writeFileSync(join(dir, GEOMETRY_FILE), geometryOut);
-    const duration = frames[frames.length - 1].time;
-    sets.push({
-      dir: dirName,
-      animation: name === SETUP_POSE_DIR && facts.animations.length === 0 ? null : name,
-      fps,
-      sampled: frames.length,
-      written: frames.length,
-      stride: 1,
-      duration,
-    });
-    const how = frames.length === 1 ? 'a single pose' : `${duration.toFixed(3)}s`;
-    const extras = `${sheet ? ` + ${SHEET_FILE}` : ''}${geometryOut === undefined ? '' : ` + ${GEOMETRY_FILE}`}`;
-    console.log(`  ..    ${name.padEnd(16)} ${frames.length} frame(s), ${how}${extras} -> ${dir}`);
-  }
-
-  // The sidecar is what makes this a frame SET rather than a pile of pictures:
-  // the world box every frame is a picture of, so a distance measured in pixels
-  // converts back to the units the rig is authored in — and so `rigc check` can
-  // 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 }),
-    // Written only when a subset was asked for, for the same reason: a render of
-    // every slot says nothing and stays the bytes it always was (issue #835).
-    ...subsetFields(subset),
-    background: BACKGROUND,
-    // The one spelling `geometry.json` repeats, so the two files cannot state
-    // two boxes for one grid.
-    viewport: sidecarViewport(viewport),
-    sets: [...sets].sort((a, b) => a.dir.localeCompare(b.dir)),
-  };
-  writeFileSync(join(outRoot, FRAMES_SIDECAR), `${JSON.stringify(sidecar, null, 2)}\n`);
-  console.log(`rigc: wrote ${join(outRoot, FRAMES_SIDECAR)}`);
-}
-
-/** The animation names an emitted skeleton carries, in the order it lists them. */
-function skeletonAnimationNames(skeletonText: string, path: string): string[] {
-  const parsed = parseJsonNamed(skeletonText, path);
-  if (typeof parsed !== 'object' || parsed === null) throw new UsageError(`${path} is not a skeleton object`);
-  const animations = (parsed as { animations?: unknown }).animations;
-  if (animations === undefined) return [];
-  if (typeof animations !== 'object' || animations === null || Array.isArray(animations)) {
-    throw new UsageError(`${path} has an "animations" field that is not an object`);
-  }
-  return Object.keys(animations);
-}
-
-/**
- * The gate's reading of one candidate, taken the way `rigc validate <dir>`
- * takes it (issue #837).
- *
- * ⭐ The same call `cmdValidate` makes on a bare directory: the two texts, the
- * atlas's own directory, the default profile, and nothing a directory cannot
- * supply — no rig spec, no declared durations, no second compile. So `A09` and
- * `A18` report SKIP here exactly as they do there, and the line is the line
- * that command prints for these files, not the one `build` printed for the
- * compile that wrote them. Measured on every run, because the page must not
- * carry a figure this run did not measure.
- */
-function previewGate(skeletonText: string, atlasText: string, atlasDir: string): PreviewGate {
-  const lines = reportLines(validate({ skeletonText, atlasText, atlasDir, profile: CLI_DEFAULT_PROFILE }));
-  const refusal = lines.find((line) => line.startsWith('  FAIL  '));
-  return {
-    // `reportLines` ends on the summary by construction; the gutter is the
-    // report's layout, not part of what the gate said.
-    summary: lines[lines.length - 1].replace(/^ {2}\.\. {4}/, ''),
-    refusal: refusal === undefined ? null : refusal.trimStart(),
-  };
-}
-
-/**
- * preview — the artifact playing in Esoteric's own web player, as one file.
- *
- * ⚠️ Nothing is rasterised here and nothing is decoded. The pages go into the
- * page as the bytes they are on disk, so a preview works for any PNG a BROWSER
- * can draw rather than for the ones our own decoder reads — which is the right
- * direction for the command whose whole job is "just show me".
- */
-function cmdPreview(flags: Record<string, string>, candidates: string[]): void {
-  // Refused rather than ignored: a preview asked to hide `head` that plays the
-  // whole rig is a picture that answers a question it was not asked (issue #835).
-  for (const flag of ['slot', 'hide'] as const) {
-    if (flags[flag] !== undefined) {
-      throw new UsageError(
-        `preview takes no --${flag}: the Spine Web Player draws what the skeleton draws. A subset of the slots is ` +
-          `\`rigc render --${flag} ${flags[flag]}\`, on the whole rig's grid`,
-      );
-    }
-  }
-  const several = candidates.length > 1;
-  // `--atlas` names ONE atlas, and with several skeletons there is no
-  // unambiguous thing it could mean — the refusal `vote` makes, for the reason
-  // it makes it.
-  if (several && flags.atlas !== undefined) {
-    throw new UsageError(
-      `--atlas names one atlas and ${candidates.length} --candidate were given; each candidate's atlas has to sit ` +
-        'beside its skeleton, which is what `build --out` leaves behind',
-    );
-  }
-  const found = several
-    ? candidates.map((target) => {
-        const { skeletonPath, atlasPath } = resolveArtifacts(target, undefined);
-        for (const path of [skeletonPath, atlasPath]) {
-          if (!existsSync(path)) throw new UsageError(`nothing at ${path}`);
-        }
-        return { target, skeletonPath, atlasPath, atlasDir: dirname(atlasPath) };
-      })
-    : [{ target: flags.candidate, ...resolveViewable(flags) }];
-  // ⚠️ By the FILE each one resolves to, not by the text typed: `build/` and
-  // `build/skeleton.json` are two spellings of one candidate, and so are
-  // `/tmp/x` and `/private/tmp/x` on a machine where one is a link to the other
-  // — `resolve` alone left that pair unrefused, measured on macOS. A page
-  // showing one skeleton twice is two panes that look like a comparison of
-  // nothing. (`vote` accepts a repeat today, exit 0; that is its own card.)
-  const identities = found.map((f) => realpathSync(f.skeletonPath));
-  for (let i = 1; i < found.length; i++) {
-    const first = identities.indexOf(identities[i]);
-    if (first < i) {
-      throw new UsageError(
-        `--candidate ${JSON.stringify(found[i].target)} is ${identities[i]}, which --candidate ` +
-          `${JSON.stringify(found[first].target)} already names (candidates ${first + 1} and ${i + 1}); a pane per ` +
-          'candidate would show the same skeleton twice',
-      );
-    }
-  }
-
-  // Every candidate's texts and animation are read before a line is printed,
-  // so a refusal about any of them comes before the report, as it always has.
-  const loaded = found.map((f, i) => {
-    const skeletonText = readFileSync(f.skeletonPath, 'utf8');
-    const atlasText = readFileSync(f.atlasPath, 'utf8');
-    const animations = skeletonAnimationNames(skeletonText, f.skeletonPath);
-    let chosen: string | undefined;
-    try {
-      chosen = readAnimationFlag(flags, animations);
-    } catch (err) {
-      // With several candidates the refusal has to say WHICH one lacks it.
-      if (several && err instanceof UsageError) {
-        throw new UsageError(`candidate ${i + 1} (${f.skeletonPath}): ${err.message}`);
-      }
-      throw err;
-    }
-    return { ...f, skeletonText, atlasText, animations, chosen };
-  });
-
-  // A directory for --out is taken as "put the default name in here", because
-  // `--out render/` is what the sibling command means by the same flag and a
-  // preview written OVER a directory is not a recoverable mistake.
-  const target = resolve(flags.out ?? 'preview.html');
-  const out = existsSync(target) && statSync(target).isDirectory() ? join(target, 'preview.html') : target;
-  const version = readVersion();
-
-  console.log('rigc preview');
-  const inputs: PreviewInput[] = loaded.map((candidate, i) => {
-    const { skeletonPath, atlasPath, atlasDir, skeletonText, atlasText, animations, chosen } = candidate;
-    if (several) console.log(`  ..    pane ${i + 1} of ${loaded.length}`);
-    console.log(`  ..    skeleton ${skeletonPath}`);
-    console.log(`  ..    atlas    ${atlasPath}`);
-    const pages: PreviewPage[] = atlasPageNames(atlasText).map((name) => {
-      const path = join(atlasDir, name);
-      if (!existsSync(path)) {
-        throw new UsageError(
-          `the atlas declares page "${name}", which resolves to ${path} and is not there — ` +
-            'a page a preview cannot embed is a page the player could not have loaded either',
-        );
-      }
-      return { name, bytes: readFileSync(path) };
-    });
-    for (const page of pages) {
-      console.log(`  ..    page     ${page.name.padEnd(28)} ${(page.bytes.length / 1024).toFixed(1)} KiB`);
-    }
-    if (!declaresSetupStage(skeletonHeaderOf(skeletonText))) console.log(`  ..    ${STAGELESS_FRAMING.preview}`);
-    const gate = previewGate(skeletonText, atlasText, atlasDir);
-    console.log(`  ..    gate     ${gate.summary}`);
-    if (gate.refusal !== null) {
-      console.log(
-        `  ..    gate     refused — ${gate.refusal}. Previewed anyway: looking at a red build is what preview is ` +
-          'for, and the page header says the same',
-      );
-    }
-    return {
-      skeletonText,
-      atlasText,
-      pages,
-      animation: chosen ?? animations[0] ?? null,
-      animations,
-      label: skeletonPath,
-      version,
-      gate,
-    };
-  });
-
-  const html = several ? buildPreviewPanes(inputs, version) : buildPreview(inputs[0]);
-  mkdirSync(dirname(out), { recursive: true });
-  writeFileSync(out, html);
-  const pageCount = inputs.reduce((n, input) => n + input.pages.length, 0);
-  console.log(
-    several
-      ? `  ..    embedded ${pageCount} page(s) + ${inputs.length} skeletons and atlases as data URIs, one pane each; ` +
-          `the player itself loads from unpkg (@${PLAYER_LINE}), so the first open needs a network`
-      : `  ..    embedded ${pageCount} page(s) + the skeleton and atlas as data URIs; ` +
-          `the player itself loads from unpkg (@${PLAYER_LINE}), so the first open needs a network`,
-  );
-  console.log(`rigc: wrote ${out}  (${(html.length / 1024).toFixed(1)} KiB — open it in a browser)`);
-}
-
-// ---------------------------------------------------------------------------
-// reading a given condition — pose
-// ---------------------------------------------------------------------------
-//
-// ⭐ Every other command here takes a spec and looks at what came out. This one
-// runs the other way: it takes a PICTURE the user already has — a key pose — and
-// reads spec coordinates out of it, so an agent can state those poses in a rig and
-// a motion by construction and spend its loops on the part nobody can measure, the
-// movement between them.
-//
-// 🚫 It grades nothing, and the distinction is load-bearing rather than modest.
-// `check` and `bench` compare a build against a reference and their numbers mean
-// "how close"; a pose frame is not a reference, it is an INPUT, and once the spec
-// states it there is nothing left to be close to. So the residual here is a trust
-// signal — how much of the frame this placement actually explains — and the only
-// threshold in `src/pose.ts` is the one that decides whether to print an answer at
-// all, which the caller can move.
-//
-//   rigc pose --images parts/ --frame poseA.png [--out pose.json]
-
-const DEFAULT_POSE_OUT = 'pose.json';
-
-/** `--scale 0.5,2` / `--rotation -30,30` — a pair of numbers, low first. */
-function readRange(flags: Record<string, string>, key: string): { low: number; high: number } | undefined {
-  const raw = flags[key];
-  if (raw === undefined) return undefined;
-  const parts = raw.split(',').map((s) => Number(s.trim()));
-  if (parts.length !== 2 || parts.some((n) => !Number.isFinite(n))) {
-    throw new UsageError(`--${key} takes two numbers: <min>,<max>`);
-  }
-  if (parts[1] < parts[0]) throw new UsageError(`--${key} ${JSON.stringify(raw)}: the minimum must not exceed the maximum`);
-  return { low: parts[0], high: parts[1] };
-}
-
-function cmdPose(flags: Record<string, string>): void {
-  if (flags.images === undefined) throw new UsageError('pose needs --images <dir> — the directory the loose part PNGs are in');
-  if (flags.frame === undefined) throw new UsageError('pose needs --frame <path> — one pose frame to read the placements out of');
-  const options: PoseOptions = { imagesDir: flags.images, framePath: flags.frame };
-  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 };
-  }
-  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;
-  }
-
-  console.log('rigc pose');
-  const report = estimatePose(options);
-  for (const line of poseLines(report)) console.log(line);
-
-  // Same `--out` shape as `preview` and `vote`: one file, and a directory means
-  // "the default name in here" rather than a report written over a directory.
-  const target = resolve(flags.out ?? DEFAULT_POSE_OUT);
-  const out = existsSync(target) && statSync(target).isDirectory() ? join(target, DEFAULT_POSE_OUT) : target;
-  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['inward-lever'] !== undefined) {
-    const value = Number(flags['inward-lever']);
-    if (!Number.isFinite(value) || value < 0) throw new UsageError('--inward-lever must be a number of frame pixels, 0 or more');
-    options.minLeverPx = 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
-// ---------------------------------------------------------------------------
-//
-// ⭐ `preview` shows candidates and asks nothing; this shows two to four of them
-// side by side, hides where each came from, and takes an answer back. The rest of this toolchain is instruments, and it
-// should be — the vote opens only where the instruments have already run out.
-// See `src/ballot.ts` for why the ballot is ordered compile-first-vote-last,
-// why the labels are A and B, and why the record is hashes.
-//
-// Two modes on one command, because they share exactly one thing and it is the
-// contract between them: the ballot manifest. Splitting them would document
-// that format twice and let the halves drift.
-//
-//   rigc vote --candidate <a> --candidate <b> [--animation <n>] [--out ballot.html]
-//   rigc vote --record <result.json> [--ballot ballot.html] [--ledger votes.jsonl] [--again]
-
-const DEFAULT_BALLOT = 'ballot.html';
-const DEFAULT_LEDGER = 'votes.jsonl';
-
-/** Load one candidate off disk in the shape a ballot needs. */
-function loadBallotCandidate(target: string): { candidate: BallotCandidateInput; animations: string[] } {
-  const { skeletonPath, atlasPath } = resolveArtifacts(target, undefined);
-  for (const path of [skeletonPath, atlasPath]) {
-    if (!existsSync(path)) throw new UsageError(`nothing at ${path}`);
-  }
-  const skeletonText = readFileSync(skeletonPath, 'utf8');
-  const atlasText = readFileSync(atlasPath, 'utf8');
-  const atlasDir = dirname(atlasPath);
-  const pages: PreviewPage[] = atlasPageNames(atlasText).map((name) => {
-    const path = join(atlasDir, name);
-    if (!existsSync(path)) {
-      throw new UsageError(
-        `the atlas declares page "${name}", which resolves to ${path} and is not there — ` +
-          'a page a ballot cannot embed is a page the player could not have loaded either',
-      );
-    }
-    return { name, bytes: readFileSync(path) };
-  });
-  return {
-    candidate: { source: skeletonPath, skeletonText, atlasText, pages },
-    animations: skeletonAnimationNames(skeletonText, skeletonPath),
-  };
-}
-
-/**
- * The one animation every candidate plays.
- *
- * ⚠️ Refused rather than resolved per candidate. Two panes running two
- * different animations look like a comparison and are not one, and a voter has
- * no way to see that it happened — the labels are `A` and `B`, which is the
- * whole point, so nothing on the screen would say so.
- */
-function commonAnimation(
-  flags: Record<string, string>,
-  loaded: { animations: string[] }[],
-): string | null {
-  const asked = flags.animation;
-  if (asked === undefined) {
-    const first = loaded[0].animations[0];
-    if (first === undefined) {
-      const withAny = loaded.findIndex((l) => l.animations.length > 0);
-      if (withAny !== -1) {
-        throw new UsageError(
-          `candidate ${withAny + 1} has animations [${loaded[withAny].animations.join(', ')}] and candidate 1 has none — ` +
-            'a ballot plays one animation in every pane, so there is nothing to compare here',
-        );
-      }
-      return null;
-    }
-    const missing = loaded.findIndex((l) => !l.animations.includes(first));
-    if (missing !== -1) {
-      throw new UsageError(
-        `the default animation is candidate 1's first, ${JSON.stringify(first)}, and candidate ${missing + 1} does not ` +
-          `have it (it has [${loaded[missing].animations.join(', ') || 'none'}]); name one they share with --animation`,
-      );
-    }
-    return first;
-  }
-  const missing = loaded.findIndex((l) => !l.animations.includes(asked));
-  if (missing !== -1) {
-    throw new UsageError(
-      `no animation ${JSON.stringify(asked)} in candidate ${missing + 1}; it has ` +
-        `[${loaded[missing].animations.join(', ') || 'none'}]`,
-    );
-  }
-  return asked;
-}
-
-/** vote (ballot mode) — write the page a human opens. */
-function cmdVoteBallot(flags: Record<string, string>, candidates: string[]): void {
-  if (candidates.length < MIN_CANDIDATES) {
-    throw new UsageError(
-      `a ballot needs ${MIN_CANDIDATES}–${MAX_CANDIDATES} --candidate <dir | skeleton.json>, and ${candidates.length} ` +
-        'was given — one candidate on its own is `rigc preview`',
-    );
-  }
-  if (candidates.length > MAX_CANDIDATES) {
-    throw new UsageError(
-      `${candidates.length} candidates were given and a ballot holds at most ${MAX_CANDIDATES} — they go side by side ` +
-        'on one screen, and a comparison that needs scrolling is not a comparison',
-    );
-  }
-  // `--atlas` names ONE atlas and there are several skeletons here, so there is
-  // no unambiguous thing it could mean. Each candidate's atlas has to sit beside
-  // its skeleton, which is what `build --out` leaves behind.
-  if (flags.atlas !== undefined) {
-    throw new UsageError(
-      '--atlas names one atlas and a ballot has several candidates; each one\'s atlas has to sit beside its skeleton',
-    );
-  }
-
-  const loaded = candidates.map((target) => loadBallotCandidate(target));
-  const animation = commonAnimation(flags, loaded);
-
-  const target = resolve(flags.out ?? DEFAULT_BALLOT);
-  const out = existsSync(target) && statSync(target).isDirectory() ? join(target, DEFAULT_BALLOT) : target;
-
-  const input: BallotInput = {
-    candidates: loaded.map((l) => l.candidate),
-    animation,
-    version: readVersion(),
-  };
-  const { html, manifest } = buildBallot(input);
-
-  console.log('rigc vote');
-  console.log(`  ..    ballot    ${manifest.ballot}`);
-  console.log(`  ..    animation ${animation === null ? '(none — the setup pose)' : animation}`);
-  for (let i = 0; i < manifest.candidates.length; i++) {
-    const entry = manifest.candidates[i];
-    const bytes = loaded[i].candidate.pages.reduce((n, p) => n + p.bytes.length, 0);
-    console.log(
-      `  ..    ${entry.label}         ${entry.digest.slice(0, 'sha256:'.length + 12)}…  ` +
-        `${entry.pages.length} page(s), ${(bytes / 1024).toFixed(1)} KiB  <- ${entry.source}`,
-    );
-  }
-  mkdirSync(dirname(out), { recursive: true });
-  writeFileSync(out, html);
-  console.log(
-    `  ..    the page shows ${manifest.candidates.map((c) => c.label).join('/')} and nothing else — the paths above are ` +
-      'in its manifest, never on the screen',
-  );
-  console.log(
-    `  ..    embedded every candidate's skeleton, atlas and page(s) as data URIs; the player itself loads from ` +
-      `unpkg (@${PLAYER_LINE}), so the first open needs a network`,
-  );
-  console.log(`rigc: wrote ${out}  (${(html.length / 1024).toFixed(1)} KiB — open it in a browser)`);
-  console.log(
-    `rigc: then record the saved vote with  rigc vote --record ${resultFilename(manifest.ballot)} --ballot ${out}`,
-  );
-}
-
-/** vote (record mode) — check one saved vote and append it to the ledger. */
-function cmdVoteRecord(flags: Record<string, string>): void {
-  for (const key of ['candidate', 'out'] as const) {
-    if (flags[key] !== undefined) {
-      throw new UsageError(`--record and --${key} are the two halves of this command; run them one at a time`);
-    }
-  }
-  const resultPath = resolve(flags.record);
-  const ballotPath = resolve(flags.ballot ?? DEFAULT_BALLOT);
-  const ledgerPath = resolve(flags.ledger ?? DEFAULT_LEDGER);
-  for (const [what, path] of [
-    ['result', resultPath],
-    ['ballot', ballotPath],
-  ] as const) {
-    if (!existsSync(path)) {
-      throw new UsageError(
-        `no ${what} file at ${path}` + (what === 'ballot' ? ' — name the page this vote came from with --ballot' : ''),
-      );
-    }
-  }
-
-  console.log('rigc vote --record');
-  console.log(`  ..    result ${resultPath}`);
-  console.log(`  ..    ballot ${ballotPath}`);
-  console.log(`  ..    ledger ${ledgerPath}`);
-
-  const manifest = readBallotManifest(readFileSync(ballotPath, 'utf8'), ballotPath);
-  const result = readJsonFile(resultPath);
-  const existing = existsSync(ledgerPath) ? parseLedger(readFileSync(ledgerPath, 'utf8'), ledgerPath) : [];
-  const attempts = existing.filter((l) => l.ballot === manifest.ballot).length;
-  const again = flags.again !== undefined;
-
-  const { refusals, line } = verifyResult(manifest, result, { attempts, again });
-  if (line === null) {
-    for (const refusal of refusals) console.error(`  FAIL  ${refusal.rule}: ${refusal.detail}`);
-    console.error(`rigc: ${refusals.length} refusal(s) — nothing appended to ${ledgerPath}`);
-    process.exit(1);
-  }
-  for (const rule of VOTE_RULES) console.log(`  PASS  ${rule}`);
-
-  line.seq = existing.length + 1;
-  mkdirSync(dirname(ledgerPath), { recursive: true });
-  appendFileSync(ledgerPath, ledgerLineText(line));
-  console.log(
-    `  ..    ${line.choice === TIE ? 'tie' : `winner ${line.choice} = ${line.winner}`}, ` +
-      `reason code ${line.reasonCode}${line.attempt > 1 ? `, attempt ${line.attempt}` : ''}`,
-  );
-  console.log(
-    `  ..    coverage ${line.coverage.length} candidate(s): ` +
-      line.coverage.map((c) => `${c.label}=${c.digest.slice(0, 'sha256:'.length + 12)}…`).join(' '),
-  );
-  console.log(`rigc: appended line ${line.seq} to ${ledgerPath}`);
-}
-
-function cmdVote(flags: Record<string, string>, candidates: string[]): void {
-  if (flags.record !== undefined) cmdVoteRecord(flags);
-  else if (candidates.length > 0) cmdVoteBallot(flags, candidates);
-  else {
-    throw new UsageError(
-      'vote takes either 2–4 --candidate <dir | skeleton.json> to write a ballot, or --record <result.json> to ' +
-        'record one that came back',
-    );
-  }
-}
-
-/**
- * bench — run one rung of the benchmark ladder against a candidate rig.
- *
- * Two questions, asked in this order and never merged:
- *
- *   1. Is the candidate valid Spine at all? That is `validate --profile spine`,
- *      and it is the only part with a pass/fail. The profile is pinned here, not
- *      inherited from the CLI default: the thing being reproduced is an editor
- *      export, and holding it to this project's renderer policy would fail rungs
- *      for reasons the rung is not about.
- *   2. How close is it, structurally, to the reference? That is `diff`, and it
- *      has no threshold at all. There is no score to pass, on purpose — see
- *      `src/diff.ts`. A rung is called cleared by a human reading the measures,
- *      and `docs/LADDER.md` records that judgement.
- *
- * ⚠️ The candidate is validated against the SPINE profile and compared against
- * the reference; the reference is never validated here. It is editor output and
- * is the definition of correct for this exercise, so gating it would be gating
- * the yardstick with the ruler.
- */
-function cmdBench(flags: Record<string, string>, positional: string[]): void {
-  const rungId = positional[0];
-  if (!rungId) throw new UsageError(`bench takes a rung: ${RUNG_IDS.join(' | ')}`);
-  const rung = findRung(rungId);
-  if (!rung) throw new UsageError(`unknown rung ${JSON.stringify(rungId)}; known: ${RUNG_IDS.join(', ')}`);
-  if (flags.candidate === undefined) throw new UsageError('bench needs --candidate <dir | skeleton.json>');
-
-  // bench judges a reproduction of editor output, so `spine` is PINNED here
-  // rather than inherited. It reads the same as the CLI default today (#221) and
-  // is kept as its own statement anyway: the ladder's stage-1 gate is defined by
-  // `docs/GATE.md` as `validate --profile spine`, and a bench run must go on
-  // meaning that whatever a later release decides the default should be.
-  const profile: ValidateProfile = flags.profile === undefined ? 'spine' : readProfile(flags);
-  const exportDir = resolve(import.meta.dir, 'examples', rung.example, 'export');
-  if (!existsSync(exportDir)) {
-    // `bun run fetch-examples` runs `scripts/fetch-examples.sh`, and `scripts/`
-    // is not in package.json's `files` — an npm install has no such script to
-    // run. Its presence is what tells the two contexts apart, so the remedy
-    // named here is one that actually exists in whichever context this is.
-    const remedy = existsSync(resolve(import.meta.dir, 'scripts', 'fetch-examples.sh'))
-      ? 'run `bun run fetch-examples` first'
-      : `bench needs a checkout of ${repositoryUrl()} — its \`fetch-examples\` script is not part of the installed package`;
-    throw new UsageError(`no example corpus at ${exportDir} — ${remedy} (examples/ is gitignored, not shipped)`);
-  }
-
-  // Both files there and the skeleton JSON before the first line is printed, refused by name as `render` refuses
-  // them (issue #1042): a missing file and a skeleton that is not JSON surfaced as an ENOENT or a SyntaxError and a
-  // stack, the second only after the validate block had printed.
-  const { skeletonPath, atlasPath } = resolveViewable({ candidate: flags.candidate, ...(flags.atlas === undefined ? {} : { atlas: flags.atlas }) });
-  const skeletonText = readSkeletonText(skeletonPath);
-  const atlasText = readFileSync(atlasPath, 'utf8');
-
-  console.log(`rigc bench rung ${rung.id} — ${rung.example}`);
-  console.log(`  gates      ${rung.gates}`);
-  console.log(`  candidate  ${skeletonPath}`);
-  console.log(`  atlas      ${atlasPath}`);
-  console.log('');
-
-  console.log(`  ── validate (profile ${profile}) ──`);
-  const report = validate({ skeletonText, atlasText, atlasDir: dirname(atlasPath), profile });
-  for (const line of reportLines(report)) console.log(`  ${line}`);
-  console.log('');
-
-  const candidateJson: unknown = JSON.parse(skeletonText);
-  const diffs: Array<{ skeleton: RungSkeleton; reference: string; report: DiffReport }> = [];
-  for (const skeleton of rung.skeletons) {
-    const referencePath = join(exportDir, skeleton.file);
-    if (!existsSync(referencePath)) {
-      console.error(`  MISSING  ${referencePath} — re-run \`bun run fetch-examples\``);
-      continue;
-    }
-    const role = skeleton.role === 'stretch' ? ' (stretch — reported, does not count)' : '';
-    console.log(`  ── diff vs ${rung.example}/${skeleton.label}${role} ──`);
-    const diff = diffSkeletons(candidateJson, JSON.parse(readFileSync(referencePath, 'utf8')));
-    for (const line of diffLines(diff, { candidate: skeletonPath, reference: referencePath })) console.log(`  ${line}`);
-    console.log('');
-    diffs.push({ skeleton, reference: referencePath, report: diff });
-  }
-
-  // Stage 3, optional and behind a flag because the correspondence is an INPUT:
-  // a candidate is entitled to its own bone names, so there is nothing sensible
-  // to default to and a derived mapping would be a guess reported as a
-  // measurement (issue #8). Nothing here gates, and without the flag the report
-  // above is unchanged to the byte.
-  const boneDists: Array<{ skeleton: RungSkeleton; report: BoneDistReport }> = [];
-  if (flags.bones !== undefined) {
-    for (const skeleton of rung.skeletons) {
-      const referencePath = join(exportDir, skeleton.file);
-      if (!existsSync(referencePath)) continue;
-      console.log(`  ── bonedist vs ${rung.example}/${skeleton.label} (stage 3) ──`);
-      const boneDist = boneDistance({
-        candidateSkeleton: skeletonPath,
-        candidateAtlas: atlasPath,
-        referenceSkeleton: referencePath,
-        referenceAtlas: join(exportDir, skeleton.atlas),
-        bones: flags.bones,
-        // Deliberately NOT `flags.fps`. Inside `bench` that flag already means
-        // "the rate this frame set was recorded at, for a set with no sidecar",
-        // and one flag doing two unrelated things in one command is how a
-        // reader ends up quoting a figure measured at a rate they did not ask
-        // for. A run wanting another sampling rate calls `rigc bonedist`, where
-        // `--fps` has exactly one meaning.
-      });
-      for (const line of boneDistLines(boneDist, { allBones: flags['all-bones'] !== undefined })) console.log(`  ${line}`);
-      console.log('');
-      boneDists.push({ skeleton, report: boneDist });
-    }
-  }
-
-  // Third, optional and third for a reason: is it the same MOTION? `diff`
-  // compares structure, and a reversed easing is the same key count and the same
-  // curve kind — so a row of this ladder carrying only `validate` and `diff`
-  // records a rig that could be animated backwards. `--frames` folds `check`'s
-  // table into the report so a future row carries both.
-  let check: CheckReport | null = null;
-  if (flags.frames !== undefined) {
-    console.log(`  ── check vs frames ${resolve(flags.frames)} ──`);
-    check = runCheck(flags.candidate, flags.atlas, flags.frames, flags);
-    for (const line of checkLines(check, { allFrames: flags['all-frames'] !== undefined })) console.log(`  ${line}`);
-    console.log('');
-  }
-
-  console.log('  ── summary ──');
-  console.log(`  validate   ${report.failures.length === 0 ? 'green' : `${report.failures.length} FAILED`}  (profile ${profile})`);
-  for (const d of diffs) {
-    const means = d.report.sections.map((s) => `${s.name}=${s.ratio.toFixed(3)}`).join('  ');
-    console.log(`  ${d.skeleton.label.padEnd(10)} ${means}${d.skeleton.role === 'stretch' ? '   [stretch]' : ''}`);
-    // Second line, not folded into the first: the figures above are the ones
-    // every bench.json on disk already carries, and a ladder record is worth
-    // less the moment its headline stops meaning what the older ones meant.
-    // The sections whose measures are dominated by name-keyed ones get their
-    // name-agnostic figure printed beside — issue #21.
-    const split = d.report.sections.filter((s) => s.nameAgnostic !== undefined);
-    if (split.length > 0) console.log(`  ${''.padEnd(10)} ${split.map(sectionFigures).join('   ')}`);
-    // A third line, for the same reason the second one is not folded into the
-    // first: the reported measures are unobservable by construction, so they
-    // roll into no mean at all and cannot be shown as one. Each is named with
-    // its own figure — a per-section digest would be the mean this block exists
-    // to refuse.
-    const reported = reportedFigures(d.report);
-    if (reported !== null) console.log(`  ${''.padEnd(10)} reported: ${reported}`);
-  }
-  if (check) {
-    // The framing goes first because it is upstream of every MAE below it: a
-    // summary that reported those numbers without saying how the two shots were
-    // put on each other is how issue #34 stayed invisible for two ladder runs.
-    const framing = check.framingFit;
-    if (!framing && check.sharedFraming) {
-      const f = check.sharedFraming.fit;
-      console.log(
-        `  framing    one per set (${check.animations.length}); one shared box leaves ` +
-          `x${f.scale.toFixed(6)}, rms ${f.rms.toFixed(2)}px — see the check table above for each set's own`,
-      );
-    }
-    if (framing) {
-      const signed = (n: number): string => `${n >= 0 ? '+' : ''}${n.toFixed(2)}`;
-      const how = !framing.applied
-        ? 'measured only — --viewport pinned'
-        : framing.source === 'declared'
-          ? `frames.json's own box, the candidate measured into it`
-          : `fitted to the candidate's pixels, ${framing.passes} pass(es)${framing.settled ? '' : framing.cycled ? ', cycling' : ', unsettled'}`;
-      // The MAE-refined offset belongs on this line rather than only in `check`'s
-      // own table: it moved the box every figure below was measured in, so a row
-      // that quoted the figures without it would not say what they were measured
-      // against — issue #146's own version of the #34 lesson above.
-      const r = framing.refinement;
-      const refined =
-        r === null || !r.applied
-          ? ''
-          : `  MAE-refined ${signed(r.dx)}, ${signed(r.dy)}px (${r.before.toFixed(2)} → ${r.after.toFixed(2)} ref)`;
-      console.log(
-        `  framing    fit x${framing.fit.scale.toFixed(6)}  rms ${framing.fit.rms.toFixed(2)}px  union residual ` +
-          `${signed(framing.fit.residualWidth)} x ${signed(framing.fit.residualHeight)}px  (${how})${refined}`,
-      );
-    }
-    for (const anim of check.animations) {
-      const attributed = anim.compared - anim.framesWithoutDrift;
-      const drift =
-        anim.worstDriftFrame < 0
-          ? 'no slot attributable in any of them'
-          : `worst slot drift ${anim.worstDrift.toFixed(1)}px, attributed in ${attributed}`;
-      // The per-frame change count is carried here and not only in `check`'s own
-      // table because it is the one figure a flat MAE cannot imply: a shot can be
-      // right at every frame and still hold or blink at the wrong moments.
-      const change =
-        anim.changeDisagreements === 0
-          ? ''
-          : `, ${anim.changeDisagreements}/${anim.changePairs} pair(s) change unlike the reference`;
-      // Which of the candidate's own bone chains the error is in — one name, so a
-      // loop between builds reads a unit to fix rather than a verdict on the shot.
-      // The full table is in `check`'s own report; this is its headline.
-      const worstChain = [...anim.chains].sort((a, b) => b.maeShare - a.maeShare)[0];
-      const chain =
-        worstChain === undefined ? '' : `, ${worstChain.chain} carries ${(worstChain.maeShare * 100).toFixed(0)}%`;
-      // `ref=` is the same difference over the reference's own drawn pixels. It is
-      // carried here and not only in `check`'s own table because this is the line a
-      // loop reads between builds, and `mean=` has a denominator the candidate can
-      // grow — see `FrameCheck.maeReference`.
-      // ...and the contact sheet, when the set ships one: a row reading "over 2
-      // frame(s)" for a 311-frame shot is the hole issue #36 closed, and the whole
-      // -shot figure is the one that says the frames between the stills were seen.
-      const sheet =
-        anim.sheet === null
-          ? ''
-          : `, sheet ${anim.sheet.compared} tile(s) mean=${anim.sheet.meanMae.toFixed(2)} ` +
-            `worst=${anim.sheet.worstMae.toFixed(2)}`;
-      console.log(
-        `  ${anim.dir.padEnd(10)} MAE mean=${anim.meanMae.toFixed(2)} worst=${anim.worstMae.toFixed(2)} ` +
-          `ref=${anim.meanMaeReference.toFixed(2)}  over ${anim.compared} frame(s)  ${drift}${change}${chain}${sheet}`,
-      );
-    }
-  } else {
-    console.log('  check      not run — pass --frames <dir> to compare against the rendered reference frames.');
-    console.log('             Without it this report says nothing about whether the ANIMATION is right.');
-  }
-  if (boneDists.length > 0) {
-    for (const b of boneDists) {
-      const w = b.report.worst;
-      console.log(
-        `  ${b.skeleton.label.padEnd(10)} bonedist worst position ${w.position.value.toFixed(6)} skeleton-size(s), ` +
-          `rotation ${w.rotation.value.toFixed(4)}°, scale ${w.scale.value.toFixed(6)}, linear ${w.linear.value.toFixed(6)}  ` +
-          `over ${b.report.animations.reduce((n, a) => n + a.compared, 0)} frame(s) × ${b.report.correspondence.pairs} bone pair(s)`,
-      );
-    }
-  } else {
-    console.log('  bonedist   not run — pass --bones <correspondence.json | identity> for the stage-3 per-frame');
-    console.log('             bone world-transform distance. It reports and gates nothing.');
-  }
-  console.log('  Section figures are means of their own measures. There is no rung score:');
-  console.log('  a rung is cleared by a person reading the measures, and docs/LADDER.md records it.');
-
-  if (flags.json !== undefined) {
-    // No `gates` field, deliberately. The rung's gate string names its features
-    // and its per-skeleton counts, which `bench/runs/README.md` forbids a run
-    // from reading — and this report is one of the six files the run protocol
-    // requires committing, so a copy of it here would sit inside every future
-    // run's directory, which is exactly where the next author looks for process
-    // notes. `rung` identifies the rung and carries nothing (issue #137). The
-    // console block above still prints the gate string: that is for the person
-    // reading the run, not a file the protocol commits.
-    writeJson(flags.json, {
-      rung: rung.id,
-      example: rung.example,
-      profile,
-      candidate: { skeleton: skeletonPath, atlas: atlasPath },
-      validate: report,
-      // `referencePath`, not `reference`: a DiffReport already has a
-      // `reference` of its own (the raw counts), and the spread wins.
-      diffs: diffs.map((d) => ({
-        label: d.skeleton.label,
-        role: d.skeleton.role,
-        referencePath: d.reference,
-        ...d.report,
-      })),
-      check,
-      // Absent rather than null when the flag was not passed: `bonedist: null`
-      // in a stored record would read as "measured, nothing to report", and
-      // that is the opposite of "not measured".
-      ...(boneDists.length === 0
-        ? {}
-        : { boneDists: boneDists.map((b) => ({ label: b.skeleton.label, role: b.skeleton.role, ...b.report })) }),
-    });
-  }
-
-  if (report.failures.length > 0) {
-    console.error(`rigc: candidate is not valid Spine — ${report.failures.length} assertion(s) failed`);
-    process.exit(1);
-  }
-}
-
-/**
- * bonedist — the ladder's stage 3, run on its own.
- *
- * ⚠️ It reads BOTH skeletons, so it is a finish-line instrument like `bench` and
- * unlike `check`. Every convention behind every figure is printed above the
- * tables, and there is no score — see [`src/bonedist.ts`](src/bonedist.ts).
- */
-function cmdBoneDist(flags: Record<string, string>): void {
-  if (flags.candidate === undefined) throw new UsageError('bonedist needs --candidate <dir | skeleton.json>');
-  if (flags.reference === undefined) throw new UsageError('bonedist needs --reference <skeleton.json>');
-  if (flags.bones === undefined) {
-    throw new UsageError(
-      `bonedist needs --bones <correspondence.json | ${IDENTITY_CORRESPONDENCE}> — a candidate is entitled to its own bone ` +
-        'names, so the mapping is an input and never a guess; pass `identity` to state that the two use the same names',
-    );
-  }
-  // Each side's files there and its skeleton JSON, refused by name as `render` refuses them (issue #1042); a pair
-  // that does not load is `boneDistance`'s refusal (`CandidatePairError`, exit 2 below).
-  const sideOf = (target: string, atlas: string | undefined): { skeletonPath: string; atlasPath: string } => {
-    const side = resolveViewable({ candidate: target, ...(atlas === undefined ? {} : { atlas }) });
-    readSkeletonText(side.skeletonPath);
-    return side;
-  };
-  const candidate = sideOf(flags.candidate, flags.atlas);
-  const reference = sideOf(flags.reference, flags['reference-atlas']);
-  const report = boneDistance({
-    candidateSkeleton: candidate.skeletonPath,
-    candidateAtlas: candidate.atlasPath,
-    referenceSkeleton: reference.skeletonPath,
-    referenceAtlas: reference.atlasPath,
-    bones: flags.bones,
-    ...(flags.fps === undefined ? {} : { fps: Number(flags.fps) }),
-  });
-  console.log('rigc bonedist — per-frame bone world-transform distance (the ladder\'s stage 3)');
-  for (const line of boneDistLines(report, { allBones: flags['all-bones'] !== undefined })) console.log(line);
-  if (flags.json !== undefined) writeJson(flags.json, report);
-}
-
-/**
- * Refuse a compiled pair whose art `explain` cannot pose through, by name.
- *
- * 🚨 `explain` poses the rig — `deformReportLines` measures what each deform key
- * did — and spine-core's reading of the pair resolves EVERY attachment against
- * the atlas, whether or not anything deforms it. (Since issue #1019 a build's
- * survey is read off its model document and posed by the core, which resolves
- * nothing against the atlas; spine-core reads it under `--poser spine` and on a
- * fallback, and this refusal is unchanged and comes before either.) On the specs
- * `ingest --art none` writes there is nothing to resolve against: the entries
- * state a size and name no `image`, so the compile atlases nothing, and the load
- * threw the runtime's own `Region not found in atlas: rear-upper-arm (attachment:
- * rear-upper-arm)` with a spine-core stack trace under it and exit 1 (measured on
- * `examples/spineboy/export/spineboy-ess.json`, issue #697). That is the tool
- * telling an agent about its own internals instead of about the rig, on the one
- * input `docs/INGEST.md` §2.0 documents as the route through a foreign skeleton.
- *
- * ⭐ Both halves of the join are rigc's own readers rather than a second opinion
- * on somebody else's format: the walk is `attachmentRegionJoins`, which `PS127`
- * measures against the loader's own `findRegion` calls, and the region names come
- * from `parseAtlasText`, which is what `--atlas-in` already resolves against.
- * Names are compared EXACTLY — as `A08` compares them and as `findRegion`
- * matches them — so a padded region name is a miss on both sides.
- *
- * ⚠️ What it deliberately does not do is catch the pose. A blanket `try` around
- * `skeletonDataFromText` would convert any exception the runtime raises into a
- * sentence claiming the cause is missing art, and a rigc defect reported under
- * somebody else's name is the doctrine's second bullet inverted. This refuses
- * the case it can NAME, before a line of the report is printed, and leaves
- * anything else to arrive as itself.
- */
-function refuseUnposableArt(result: CompileResult, opts: CompileOptions): void {
-  const regionNames = parseAtlasText(result.atlasText).pages.flatMap((page) => page.regions.map((region) => region.name));
-  const have = new Set(regionNames);
-  const misses: Array<{ at: string; attachment: string; lookup: string }> = [];
-  let lookups = 0;
-  for (const join of attachmentRegionJoins(JSON.parse(result.skeletonText))) {
-    // A `sequence` this walk will not guess at names no region it can check, and
-    // `A08` passes over it for the same reason.
-    if (join.lookups === null) continue;
-    for (const lookup of join.lookups) {
-      lookups++;
-      if (!have.has(lookup)) {
-        misses.push({
-          at: `skin "${join.skin}" slot "${join.slot}" placeholder "${join.placeholder}"`,
-          attachment: join.name,
-          lookup,
-        });
-      }
-    }
-  }
-  if (misses.length === 0) return;
-  const first = misses[0];
-  // Reported because it was measured, and absent where there is none — `A08`'s
-  // own near-miss clause, in `A08`'s own words.
-  const near = regionNames.find((region) => region.trim().toLowerCase() === first.lookup.toLowerCase());
-  const has =
-    regionNames.length === 0
-      ? 'it declares no region at all'
-      : `it declares ${regionNames.length} region(s) and none of them is that${
-          near === undefined ? '' : `, though it does have ${JSON.stringify(near)}`
-        }`;
-  const remedy =
-    opts.atlasInPath === undefined
-      ? 'Art reaches a compile two ways and this run took neither: `--atlas-in <pack.atlas>` resolves the parts ' +
-        'against a pack somebody already made, and an "image" per attachment resolves them as loose PNGs under ' +
-        '`--images <dir>` — a spec that states a size and names no image is what `ingest --art none` writes, and ' +
-        '`--atlas-in` is what reads it'
-      : `Either the spec's region name or ${opts.atlasInPath} is the one that moved: fix the name, or point ` +
-        '`--atlas-in` at the pack that has it';
-  throw new ExplainError(
-    `${first.at}: attachment ${JSON.stringify(first.attachment)} wants region ${JSON.stringify(first.lookup)}, ` +
-      `which this build's atlas does not have (${has}). \`explain\` poses the rig to measure its deform keys and a ` +
-      `pose resolves every attachment against the atlas, so there is nothing to pose it against. ${remedy}. ` +
-      `${misses.length} of ${lookups} attachment lookup(s) here resolve to no region.`,
-  );
-}
-
-function cmdExplain(flags: Record<string, string>): void {
-  // `--poser` is refused by its spelling before anything compiles (issue #1019): it chooses the deform survey's reader and poser.
-  const poser = readPoserFlag(flags);
-  const { label, opts } = resolveCut(flags);
-  console.log(`rigc explain ${label}`);
-  // See the identical pair of lines in `cmdBuild` for why both paths are named
-  // here rather than only the one the header's `label` happens to carry.
-  console.log(`  ..    rig    ${opts.rigPath}`);
-  console.log(`  ..    motion ${opts.motionPath}`);
-  const result = compile(opts);
-  // Before a line of the report, rather than at the pose two hundred lines in:
-  // the blocks that need the art — DEFORM, meshes, dropped states — all sit
-  // BELOW the pose, so a run that printed the bone and timeline dump and then
-  // refused would be a report missing everything the missing art decides, with
-  // the sentence saying so scrolled off the top. It is the invocation that has
-  // to change, so it is refused before the report it cannot finish (issue #697).
-  refuseUnposableArt(result, opts);
-  // 📐 **A page whose file is not its declared size is said where the report
-  // starts, and nothing is refused for it** (issue #750). `explain` never
-  // gates, so on such a pack nothing stood between the region lift and the
-  // figures it fed: the mesh block printed a fit taken off another part of the
-  // page. The pack still compiles — a runtime draws it, and most of this report
-  // (bones, slots, timelines) reads no texel at all — so the page is named
-  // here, once, with the ratio `A06` refuses it by, and every figure that WOULD
-  // have been taken off its texels is withheld on its own line and says so.
-  // `build` prints no such line: `A06` is its statement of the same fact.
-  for (const grid of result.pageGrids) {
-    console.log(
-      `  ..    ${grid.said}: every figure below taken off this page's texels is withheld, and says so where it ` +
-        `would have stood. ${PAGE_GRID_UNLOCATED}`,
-    );
-  }
-  // `compile` has already parsed this file, so the read below cannot fail — but
-  // it goes through the same parser rather than a cast, because the cast was the
-  // last one in the repository and issue #307 was about exactly that.
-  const motion = parseMotionSpec(readJsonFile(opts.motionPath), opts.motionPath);
-
-  // 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
-  // to. Printing it anyway told a rung-3 author their bone positions were in a
-  // coordinate system that did not exist in their rig.
-  const frame = opts.manifestPath ? '  (crop y-down -> spine y-up, origin at the bottom-left of the crop)' : '  (spine world: y up)';
-  console.log(`\nbones${frame}`);
-  for (const b of result.skeleton.bones) {
-    // `rotation` is the axis keystone and the grips' radial facing, so it earns
-    // a column even though it is absent on most bones.
-    const rot = b.rotation === undefined ? '' : `  rotation=${b.rotation}`;
-    console.log(`  ${b.name.padEnd(12)} parent=${(b.parent ?? '-').padEnd(10)} x=${b.x ?? 0} y=${b.y ?? 0}${rot}`);
-  }
-
-  console.log('\nslots  (array order IS the draw order)');
-  // The DEFAULT skin's placeholders, resolved by name. It was `skins[0]` until
-  // issue #541, which is the same thing only because rigc pins `default` at
-  // index 0 — a property of the emitter that this report should not be quietly
-  // relying on. Reading it by name means a change to the skins ORDER cannot turn
-  // this line into a report about some other skin.
-  const defaultSkin = result.skeleton.skins.find((skin) => skin.name === 'default');
-  // ...and a skeleton may declare none (issue #801), in which case every
-  // `attachments=[]` below is true and says nothing — so the line above the
-  // column says where the placeholders are instead of letting it read as
-  // "this rig has no art".
-  if (defaultSkin === undefined) {
-    const names = result.skeleton.skins.map((skin) => JSON.stringify(skin.name));
-    console.log(
-      `  (this skeleton declares no default skin, so the attachments column lists none; its placeholders are in ` +
-        `${names.length === 0 ? 'no skin at all' : `the named skin(s) ${names.join(', ')}`})`,
-    );
-  }
-  for (const s of result.skeleton.slots) {
-    const atts = Object.keys(defaultSkin?.attachments[s.name] ?? {});
-    console.log(
-      `  ${s.name.padEnd(12)} bone=${s.bone.padEnd(12)} setup=${(s.attachment ?? 'null').padEnd(22)} color=${s.color ?? 'ffffffff'}  attachments=[${atts.join(', ')}]`,
-    );
-  }
-
-  console.log('\nanimations');
-  for (const [animName, anim] of Object.entries(result.skeleton.animations)) {
-    const spec = motion.animations[animName];
-    console.log(`  ${animName}  declared=${spec.duration}s loop=${spec.loop}`);
-    for (const [boneName, timelines] of Object.entries(anim.bones ?? {})) {
-      // "(mesh tier)" is a claim about what the bone DRIVES, and it was printed
-      // on every bone track regardless — which reads, on a rig with no mesh in
-      // it at all, as though the track were deforming one.
-      const drives = result.meshBones.includes(boneName) ? '  <- drives a mesh' : '';
-      for (const [timelineName, keys] of Object.entries(timelines)) {
-        console.log(`    ${boneName}.${timelineName}  ${keys.length} key(s)${drives}`);
-        if (timelineName === 'scale') console.log(`      ${SCALE_PRODUCT_NOTE}`);
-        for (const emitted of keys) {
-          // Every channel, as the parser reads it: a channel at its parser
-          // default is not in the file (issue #716), and this list shows the
-          // value a reader has to reason about rather than the bytes.
-          const key = asParsed(`bone ${timelineName} key`, emitted);
-          const fields = Object.entries(key)
-            .filter(([k]) => k !== 'time' && k !== 'curve')
-            .map(([k, v]) => `${k}=${String(v)}`)
-            .join(' ');
-          const curve = Array.isArray(key.curve)
-            ? `bezier[${key.curve.length}]`
-            : key.curve === 'stepped'
-              ? 'stepped'
-              : 'linear';
-          console.log(`      t=${String(key.time).padEnd(7)} ${fields.padEnd(30)} ${curve}${scaleProduct(timelineName, key)}`);
-        }
-      }
-    }
-    for (const [slotName, timelines] of Object.entries(anim.slots ?? {})) {
-      for (const [timelineName, keys] of Object.entries(timelines)) {
-        console.log(`    ${slotName}.${timelineName}  ${keys.length} key(s)`);
-        for (const emitted of keys) {
-          const key = asParsed(`slot ${timelineName} key`, emitted);
-          const curve = key.curve;
-          const shape = Array.isArray(curve)
-            ? `bezier[${curve.length}] ${curve.slice(12).join(', ')}  <- alpha channel, absolute (t,v)`
-            : curve === 'stepped'
-              ? 'stepped'
-              : timelineName === 'attachment'
-                ? 'stepped (attachment timelines always are)'
-                : 'linear';
-          const value = 'color' in key ? `#${String(key.color)}` : `attachment=${String(key.name)}`;
-          console.log(`      t=${String(key.time).padEnd(7)} ${value.padEnd(30)} ${shape}`);
-        }
-      }
-    }
-    // The two constraint groups: one unnamed timeline per constraint, so the
-    // name printed is the constraint's and there is no timeline name to print
-    // beside it. Every field a key carries is shown, because each one is
-    // optional in the file and the ABSENT ones are what a reader has to see —
-    // an omitted `softness` is 0, not "unchanged".
-    for (const group of ['ik', 'transform'] as const) {
-      for (const [name, keys] of Object.entries(anim[group] ?? {})) {
-        console.log(`    ${group}.${name}  ${keys.length} key(s)  <- one timeline per constraint`);
-        for (const key of keys) {
-          const fields = Object.entries(key)
-            .filter(([k]) => k !== 'time' && k !== 'curve')
-            .map(([k, v]) => `${k}=${String(v)}`)
-            .join(' ');
-          const curve = Array.isArray(key.curve) ? `bezier[${key.curve.length}]` : key.curve === 'stepped' ? 'stepped' : 'linear';
-          console.log(`      t=${String(keyTimeOf(`${group} key`, key)).padEnd(7)} ${(fields || '(all defaults)').padEnd(46)} ${curve}`);
-        }
-      }
-    }
-    // The other two constraint groups. These DO carry a timeline name under the
-    // constraint (`path.<name>.position`), which is the physics shape rather
-    // than the ik/transform one, so the name printed is both.
-    for (const group of ['path', 'slider'] as const) {
-      for (const [name, timelines] of Object.entries(anim[group] ?? {})) {
-        for (const [timelineName, keys] of Object.entries(timelines)) {
-          console.log(`    ${group}.${name}.${timelineName}  ${keys.length} key(s)`);
-          for (const key of keys) {
-            const fields = Object.entries(key)
-              .filter(([k]) => k !== 'time' && k !== 'curve')
-              .map(([k, v]) => `${k}=${String(v)}`)
-              .join(' ');
-            const curve = Array.isArray(key.curve) ? `bezier[${key.curve.length}]` : key.curve === 'stepped' ? 'stepped' : 'linear';
-            console.log(`      t=${String(keyTimeOf(`${group} ${timelineName} key`, key)).padEnd(7)} ${(fields || '(all defaults)').padEnd(46)} ${curve}`);
-          }
-        }
-      }
-    }
-    // Deform timelines are keyed on a skin/slot/attachment triple, and the run
-    // is printed as its span rather than its numbers: `offset` plus a length is
-    // what tells a reader whether the key lands where they meant, and a hundred
-    // vertex offsets on one line tells them nothing.
-    for (const [skinName, slotMap] of Object.entries(anim.attachments ?? {})) {
-      for (const [slotName, attMap] of Object.entries(slotMap)) {
-        for (const [attName, timelines] of Object.entries(attMap)) {
-          for (const [timelineName, keys] of Object.entries(timelines)) {
-            console.log(`    ${skinName}/${slotName}/${attName}.${timelineName}  ${keys.length} key(s)`);
-            for (const emitted of keys) {
-              const key = asParsed(`attachment ${timelineName} key`, emitted);
-              const run = Array.isArray(key.vertices) ? (key.vertices as number[]) : null;
-              const offset = typeof key.offset === 'number' ? key.offset : 0;
-              const span = run
-                ? `deform[${offset}..${offset + run.length}]  ${run.length / 2} pair(s)`
-                : 'back to the setup pose';
-              const curve = Array.isArray(key.curve) ? `bezier[${key.curve.length}]` : key.curve === 'stepped' ? 'stepped' : 'linear';
-              console.log(`      t=${String(key.time).padEnd(7)} ${span.padEnd(46)} ${curve}`);
-              // A generated key prints its MODEL and then every offset the model
-              // produced (issue #294). Both halves are the point: the model is
-              // what a reviewer checks a claim against, and the offsets are what
-              // reaches the file — printing only the first would ask a reader to
-              // trust an evaluation they cannot see, which is the gap FACE §9.3
-              // records. The numbers are the emitted ones, not a second
-              // evaluation, so this block and the artifact cannot disagree.
-              const gen = result.deformTransforms.find(
-                (g) => g.animation === animName && g.skin === skinName && g.slot === slotName && g.attachment === attName && g.time === key.time,
-              );
-              if (gen === undefined) continue;
-              console.log(`               transform ${gen.kind}  ${gen.stated}`);
-              console.log(`               ${gen.formula}`);
-              for (const line of gen.derived) console.log(`                 ${line}`);
-              console.log(
-                `               ${gen.vertexCount} vertices, largest offset ${gen.maxOffset}px at vertex ${gen.maxOffsetVertex}`,
-              );
-              for (let v = 0; v < gen.vertexCount; v += 4) {
-                const pairs: string[] = [];
-                for (let k = v; k < Math.min(v + 4, gen.vertexCount); k++) {
-                  pairs.push(`v${String(k).padStart(3)} (${gen.offsets[2 * k]}, ${gen.offsets[2 * k + 1]})`);
-                }
-                console.log(`                 ${pairs.join('  ')}`);
-              }
-              // On a multi-influence attachment those pairs are the model's
-              // WORLD displacements, and the file holds one `Mᵢ⁻¹·D` pair per
-              // influence instead (issue #389). Printing the first without the
-              // second would put numbers on the screen that are nowhere in the
-              // artifact — the exact gap this block exists to close.
-              if (gen.expanded !== undefined) {
-                console.log(
-                  `               written as ${gen.expanded.length / 2} per-influence pair(s), each vertex's D through ` +
-                    'its own bone inverse',
-                );
-                for (let i = 0; i < gen.expanded.length / 2; i += 4) {
-                  const pairs: string[] = [];
-                  for (let k = i; k < Math.min(i + 4, gen.expanded.length / 2); k++) {
-                    pairs.push(`i${String(k).padStart(3)} (${gen.expanded[2 * k]}, ${gen.expanded[2 * k + 1]})`);
-                  }
-                  console.log(`                 ${pairs.join('  ')}`);
-                }
-              }
-            }
-          }
-        }
-      }
-    }
-    // The draw-order timeline names no target, so it hangs off the animation
-    // rather than off a slot — and a timeline `explain` did not print would be a
-    // timeline nobody could check without reading the emitted JSON.
-    if (anim.drawOrder) {
-      console.log(`    drawOrder  ${anim.drawOrder.length} key(s)  <- whole animation, offsets against the SETUP order`);
-      for (const key of anim.drawOrder) {
-        const offsets = Array.isArray(key.offsets)
-          ? (key.offsets as Array<{ slot: string; offset: number }>)
-              .map((o) => `${o.slot}${o.offset >= 0 ? '+' : ''}${o.offset}`)
-              .join(' ')
-          : 'back to the setup order';
-        console.log(`      t=${String(keyTimeOf('drawOrder key', key)).padEnd(7)} ${offsets}`);
-      }
-    }
-  }
-
-  // The `MEMBER` block sits beside the `DEFORM` one and for the same reason:
-  // both re-print timelines the reader has just read, in the arrangement the
-  // question needs rather than the one the format has.
-  for (const line of memberReportLines(result)) console.log(line);
-
-  // The `DEFORM` block goes after the timelines and before the constraints,
-  // because it is a measurement OF the deform timelines printed above — the keys
-  // it names are the keys the reader has just read, by the same index.
-  for (const line of deformReportLines(result, new Set(result.rig.deformMayFold), poser, label)) console.log(line);
-
-  if (result.physics.length) {
-    console.log('\nphysics constraints (4.3 top-level `constraints` array, type per entry)');
-    for (const ph of result.physics) {
-      console.log(`  ${ph.name.padEnd(12)} bone=${ph.bone.padEnd(14)} components=[${ph.components.join(', ')}] mix=${ph.mix} drivesMesh=${ph.drivesMesh}`);
-    }
-  }
-
-  // Path constraints, with the curve each one follows MEASURED — its length and
-  // its curve count are the two numbers an author cannot get from the spec, and
-  // `position` means nothing without the first of them under `positionMode:
-  // "percent"`. Read off the emitted attachment rather than recomputed here.
-  const constraintsOf = (type: string) => (result.skeleton.constraints ?? []).filter((c) => c.type === type);
-  const pathConstraints = constraintsOf('path');
-  if (pathConstraints.length) {
-    console.log('\npath constraints  (position is a fraction of the measured length under positionMode "percent")');
-    for (const c of pathConstraints) {
-      const slot = String(c.slot);
-      const attachments = result.skeleton.skins.flatMap((skin) => Object.values(skin.attachments[slot] ?? {}));
-      const curve = attachments.find((att) => (att as { type?: string }).type === 'path') as
-        | { lengths?: number[]; closed?: boolean; constantSpeed?: boolean }
-        | undefined;
-      // `vertexCount / 3` entries on both shapes since issue #804, so an open
-      // path's curves are one fewer than its entries and its length is the last
-      // CURVE's entry — the trailing one is the wrap-around curve nothing reads.
-      const lengths = (curve?.lengths ?? []).slice(0, curve?.closed ? undefined : -1);
-      console.log(
-        `  ${c.name.padEnd(12)} slot=${slot.padEnd(12)} bones=[${(c.bones as string[]).join(', ')}] ` +
-          `position=${c.position ?? 0} ${String(c.positionMode ?? 'percent')}/${String(c.spacingMode ?? 'length')}/${String(c.rotateMode ?? 'tangent')}`,
-      );
-      console.log(
-        `  ${''.padEnd(12)} curve: ${lengths.length} curve(s), ${lengths[lengths.length - 1] ?? 0} long, ` +
-          `${curve?.closed ? 'closed' : 'open'}, constantSpeed=${curve?.constantSpeed ?? true}`,
-      );
-    }
-  }
-
-  const sliders = constraintsOf('slider');
-  if (sliders.length) {
-    console.log('\nsliders  (each applies one animation at a time it chooses)');
-    for (const c of sliders) {
-      const driver = c.bone === undefined ? `time=${c.time ?? 0} (keyed by slider.${c.name}.time)` : `bone=${String(c.bone)}.${String(c.property)}`;
-      console.log(
-        `  ${c.name.padEnd(12)} applies=${String(c.animation).padEnd(14)} ${driver}  ` +
-          `mix=${c.mix ?? 1} loop=${c.loop ?? false} additive=${c.additive ?? false}`,
-      );
-    }
-  }
-
-  // Which bones and constraints a skin switches on. Printed because the pairing
-  // with `skin: true` is invisible in the emitted file: a member list and a
-  // skinRequired flag are two keys in two places, and only together do they mean
-  // "this bone belongs to this skin".
-  const skinMembers = result.skeleton.skins.filter((skin) => skin.bones?.length || skin.ik?.length || skin.transform?.length || skin.path?.length || skin.physics?.length || skin.slider?.length);
-  if (skinMembers.length) {
-    console.log('\nskin members  (skinRequired bones and constraints, active only under their own skin)');
-    for (const skin of skinMembers) {
-      const lists = (['bones', 'ik', 'transform', 'path', 'physics', 'slider'] as const)
-        .filter((key) => skin[key]?.length)
-        .map((key) => `${key}=[${skin[key]!.join(', ')}]`)
-        .join(' ');
-      console.log(`  ${skin.name.padEnd(12)} ${lists}`);
-    }
-  }
-
-  if (result.meshes.length) {
-    console.log('\nmeshes');
-    for (const kind of new Set(result.meshes.map((m) => m.kind))) console.log(`  ${MESH_KIND_NOTES[kind]}`);
-    for (const m of result.meshes) {
-      // The depth block belongs here more than it belongs in `build`: `explain`
-      // is the command that says what a spec MEANS, and the turn ceiling is the
-      // number an author needs before writing a key rather than after a refusal.
-      // It was absent, while `docs/AUTHORING.md` said both commands printed it.
-      console.log(
-        `  ${m.slot.padEnd(12)} ${m.kind.padEnd(8)} ${m.vertices} vertices / ${m.triangles} triangles  ` +
-          `${meshBudget(result.rig)}  bones=[${m.bones.join(', ')}]${meshFit(m)}` +
-          meshDepthNote(m) +
-          meshInfluenceNote(m),
-      );
-    }
-  }
-
-  if (result.droppedStates.length) {
-    // The heading said "no PNG on disk" and the line printed the path, on a
-    // command that takes `--atlas-in` like `build` does — so an explain of a
-    // pack build named a file it never opened. Same renderer as the other two
-    // printers now, for the same reason they share one (issue #671).
-    console.log('\ndropped states (listed in the manifest, no art behind them)');
-    for (const d of result.droppedStates) console.log(`  ${d.slot}/${d.state}  ${droppedStateReason(d)}`);
-  }
-
-  console.log('\nmix table (player config, not skeleton JSON)');
-  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})`);
-
-  /**
-   * What the run has to report, however the parse went.
-   *
-   * 🔒 A spec the tree's own parser refuses is a **finding**, not an escape
-   * (issue #692): the three files are written, the coded `BLOCK` line is
-   * printed, and the exit code comes off the findings like every other run's.
-   * The two specs are read as `unknown` because that is all this function does
-   * with them — `JSON.stringify` — and a cast to `RigSpec` here would be this
-   * file claiming a parse that did not happen.
-   */
-  let result: { rig: unknown; motion: unknown; findings: IngestFinding[] };
-  try {
-    result = ingest(readJsonFile(skeletonPath), {
-      name: flags.name ?? basename(skeletonPath, '.json'),
-      art,
-      images: specImages,
-      stage,
-      source: basename(skeletonPath),
-      version: readVersion(),
-    });
-  } catch (err) {
-    if (!(err instanceof IngestSpecRefused)) throw err;
-    result = { rig: err.rig, motion: err.motion, findings: err.findings };
-  }
-
-  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.
-  // The gutter words are `INGEST_GUTTERS`, which is also the column
-  // `docs/INGEST.md` §2.0's finding-code table is keyed on (issue #675); the
-  // pad to one width is this printer's, so the codes line up.
-  const width = Math.max(...Object.values(INGEST_GUTTERS).map((gutter) => gutter.length));
-  for (const kind of ['blocker', 'judgement', 'lossy'] as const) {
-    for (const finding of result.findings.filter((f) => f.kind === kind)) {
-      console.log(`  ${INGEST_GUTTERS[kind].padEnd(width)} ${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);
-  }
-}
-
-// ---------------------------------------------------------------------------
-// skills install — put the shipped skills where an agent host looks (issue #831)
-// ---------------------------------------------------------------------------
-//
-// After `bun add -d spine-rigc` the skills sit at `node_modules/spine-rigc/skills/`,
-// which no host reads. Codex, Gemini CLI and Antigravity all read
-// `<workspace>/.agents/skills/<name>/`, so this links every `skills/<name>/` the
-// package ships into one directory — `.agents/skills` under the working
-// directory unless `--dir` says otherwise.
-//
-// ⭐ The skills are found from THIS FILE's location, never from the working
-// directory: the command installs the package it is, and a cwd that happens to
-// hold some other `skills/` is not a source. That is also why it lives here and
-// not in `src/`: its one input is where the CLI was installed, nothing else
-// calls it, and `src/` is about rigs.
-//
-// A RELATIVE symlink by default, so the directory survives the project being
-// moved or cloned elsewhere and an upgrade of the package is seen with no second
-// run. `--copy` writes the folder instead, for a host that does not follow a
-// linked skill folder.
-//
-// 🔒 **An entry that is already there and is not what this command would write is
-// refused by name, and then nothing at all is written.** The check runs over
-// every skill before the first write, so a refusal never leaves half an install
-// behind. The one entry that is NOT refused is the one this command would have
-// made — a link that already resolves to the same skill folder, however it is
-// spelled, or with `--copy` a folder whose files are byte for byte the package's
-// — and a run over only those says it had nothing to do. No lifecycle script
-// does this on install: a postinstall writing into a consumer's project root is
-// refused as design, and Bun does not run a dependency's lifecycle scripts
-// outside `trustedDependencies`, so half the installs would silently skip it.
-// ---------------------------------------------------------------------------
-
-/** The default `--dir`, resolved against the caller's working directory. */
-const DEFAULT_SKILLS_DIR = '.agents/skills';
-
-/** What `rigc skills` offers. One today; the list is what the refusal of any other word prints. */
-const SKILLS_SUBCOMMANDS = ['install'];
-
-/** An install refused before its first write — nothing to install, or an entry in the way. Exit 1. */
-class SkillsInstallError extends Error {}
-
-type SkillsInstallAction = 'linked' | 'copied' | 'already linked' | 'already copied';
-
-interface SkillsInstallEntry {
-  /** `<dir>/<name>`. */
-  target: string;
-  /** `<package>/skills/<name>`. */
-  source: string;
-  action: SkillsInstallAction;
-  /** The link text, relative to the directory it sits in, when the entry is a link. */
-  link: string;
-}
-
-/** Every `<name>/` under `source` that holds a `SKILL.md`, in name order, so two runs print the same lines. */
-function shippedSkills(source: string): string[] {
-  if (!existsSync(source) || !statSync(source).isDirectory()) return [];
-  return readdirSync(source)
-    .filter((name) => statSync(join(source, name)).isDirectory() && existsSync(join(source, name, 'SKILL.md')))
-    .sort();
-}
-
-/**
- * The real path of `path` whether or not it exists yet: the real path of its
- * nearest existing ancestor with the rest appended. A relative link has to be
- * computed between two paths spelled the same way, and on macOS the temp
- * directory alone is reached as `/var/…` and is really `/private/var/…`.
- */
-function realpathAhead(path: string): string {
-  const rest: string[] = [];
-  let at = resolve(path);
-  while (!existsSync(at)) {
-    const up = dirname(at);
-    if (up === at) break;
-    rest.unshift(basename(at));
-    at = up;
-  }
-  return join(realpathSync(at), ...rest);
-}
-
-/** Every file under `root`, relative and sorted, so two trees compare in one order. */
-function filesUnder(root: string, prefix = ''): string[] {
-  const out: string[] = [];
-  for (const name of readdirSync(join(root, prefix)).sort()) {
-    const rel = prefix === '' ? name : `${prefix}/${name}`;
-    if (lstatSync(join(root, rel)).isDirectory()) out.push(...filesUnder(root, rel));
-    else out.push(rel);
-  }
-  return out;
-}
-
-/** The first way `copy` differs from `original`, or null when every file is the same bytes. */
-function firstDifference(copy: string, original: string): string | null {
-  const theirs = filesUnder(copy);
-  const ours = filesUnder(original);
-  for (const rel of ours) {
-    if (!theirs.includes(rel)) return `${rel} is missing from it`;
-    if (!readFileSync(join(copy, rel)).equals(readFileSync(join(original, rel)))) return `${rel} differs`;
-  }
-  for (const rel of theirs) if (!ours.includes(rel)) return `${rel} is in it and not in the package`;
-  return null;
-}
-
-/**
- * Install every shipped skill into `dir`, or refuse and write nothing.
- *
- * The plan is made in full before the first write: every entry is classified as
- * absent, already this command's, or in the way, and one entry in the way
- * refuses the whole call with every such entry named.
- */
-function installSkills(source: string, dir: string, copy: boolean): SkillsInstallEntry[] {
-  const names = shippedSkills(source);
-  if (names.length === 0) {
-    throw new SkillsInstallError(
-      `no skill to install: ${source} ${existsSync(source) ? 'holds no <name>/SKILL.md' : 'is not there'}, and it is ` +
-        'the skills/ directory of the package this command ran from; nothing was written',
-    );
-  }
-  if (existsSync(dir) && !statSync(dir).isDirectory()) {
-    throw new SkillsInstallError(`${dir} exists and is not a directory, so no skill can be installed into it; nothing was written`);
-  }
-  const realDir = realpathAhead(dir);
-  const planned: SkillsInstallEntry[] = [];
-  const refused: string[] = [];
-  for (const name of names) {
-    const target = join(dir, name);
-    const from = join(source, name);
-    const realFrom = realpathSync(from);
-    const link = relative(realDir, realFrom);
-    let action: SkillsInstallAction = copy ? 'copied' : 'linked';
-    let found: string | null = null;
-    const stat = existsSync(target) || isLink(target) ? lstatSync(target) : null;
-    if (stat === null) {
-      // absent: this command writes it
-    } else if (stat.isSymbolicLink()) {
-      const text = readlinkSync(target);
-      const pointsAt = resolve(realDir, text);
-      const lands = existsSync(pointsAt) ? realpathSync(pointsAt) : null;
-      if (lands === realFrom && !copy) action = 'already linked';
-      else if (lands === realFrom) found = `a symlink to ${text}, the package's own folder, and --copy asks for a directory in its place`;
-      else found = `a symlink to ${text}, ${lands === null ? 'which resolves to nothing' : `which resolves to ${lands}`}`;
-    } else if (stat.isDirectory()) {
-      const difference = copy ? firstDifference(target, from) : null;
-      if (!copy) found = 'a directory';
-      else if (difference === null) action = 'already copied';
-      else found = `a directory that is not the package's copy (${difference})`;
-    } else {
-      found = 'a plain file';
-    }
-    if (found !== null) refused.push(`${target} is ${found}; ${copy ? `a copy of ${from}` : `a symlink to ${link}`} was required`);
-    else planned.push({ target, source: from, action, link });
-  }
-  if (refused.length > 0) {
-    throw new SkillsInstallError(
-      `${refused.length} of the ${names.length} skill(s) cannot be installed into ${dir}, and nothing was written:\n` +
-        refused.map((line) => `  ${line}`).join('\n') +
-        '\nRemove the entries named above, or pass --dir to install somewhere else.',
-    );
-  }
-  mkdirSync(dir, { recursive: true });
-  for (const entry of planned) {
-    if (entry.action === 'linked') symlinkSync(entry.link, entry.target, 'dir');
-    else if (entry.action === 'copied') cpSync(entry.source, entry.target, { recursive: true, errorOnExist: true, force: false });
-  }
-  return planned;
-}
-
-/** A dangling link is not `existsSync`, and is still an entry in the way. */
-function isLink(path: string): boolean {
-  try {
-    return lstatSync(path).isSymbolicLink();
-  } catch {
-    return false;
-  }
-}
-
-function cmdSkills(flags: Record<string, string>, positional: string[]): void {
-  const [sub, ...extra] = positional;
-  if (sub === undefined) {
-    throw new UsageError(
-      `skills takes a subcommand: ${SKILLS_SUBCOMMANDS.join(', ')} — \`rigc skills install\` links every skill this ` +
-        `package ships into ${DEFAULT_SKILLS_DIR}`,
-    );
-  }
-  if (!SKILLS_SUBCOMMANDS.includes(sub)) {
-    throw new UsageError(`unknown skills subcommand: ${sub} (rigc skills offers ${SKILLS_SUBCOMMANDS.join(', ')})`);
-  }
-  if (extra.length > 0) {
-    throw new UsageError(
-      `skills install takes no positional argument, and ${JSON.stringify(extra[0])} was given — the directory is --dir <path>`,
-    );
-  }
-  const takes = COMMANDS.find((c) => c.name === 'skills')?.flags ?? [];
-  const foreign = Object.keys(flags).filter((flag) => !takes.includes(flag));
-  if (foreign.length > 0) {
-    throw new UsageError(
-      `skills install takes ${takes.map((flag) => `--${flag}`).join(' and ')}; ` +
-        `${foreign.map((flag) => `--${flag}`).join(', ')} is not one of them`,
-    );
-  }
-  const copy = flags.copy !== undefined;
-  const dir = resolve(process.cwd(), flags.dir ?? DEFAULT_SKILLS_DIR);
-  const entries = installSkills(join(import.meta.dir, 'skills'), dir, copy);
-  for (const entry of entries) {
-    const ends = entry.action.endsWith('linked') ? `${entry.target} -> ${entry.link}  (${entry.source})` : `${entry.target} <- ${entry.source}`;
-    console.log(`  ${entry.action.padEnd(14)}  ${ends}`);
-  }
-  const wrote = entries.filter((entry) => entry.action === 'linked' || entry.action === 'copied').length;
-  const verb = copy ? 'copied' : 'linked';
-  console.log(
-    wrote === 0
-      ? `rigc skills install: nothing to do — all ${entries.length} skill(s) are already ${verb} into ${dir}`
-      : `rigc skills install: ${wrote} of ${entries.length} skill(s) ${verb} into ${dir}` +
-          (wrote < entries.length ? `, ${entries.length - wrote} already there` : ''),
-  );
-}
-
-// ---------------------------------------------------------------------------
-// usage / per-command help
-// ---------------------------------------------------------------------------
-
-/**
- * One meaning per flag name, shared by every command that takes it — the
- * single place this project states what a flag means. AUTHORING.md §0 quotes
- * this table for `build`'s `--rig`/`--motion`/`--out`/`--images`/`--manifest`/
- * `--profile`; if the two ever disagree, this is the one the code runs.
- */
-const FLAG_MEANINGS: Record<string, string> = {
-  rig: 'the rig spec — skeleton structure',
-  motion: 'the motion spec — time',
-  out: 'directory for skeleton.json + skeleton.atlas (and, from build, skeleton.model.json); atlas page paths and skeleton.images are written relative to it',
-  images: "override the rig spec's own images directory (relative to your working directory)",
-  manifest: 'a cut manifest, for a rig with measured art behind it; a foreign skeleton has none',
-  'copy-images':
-    'also copy every referenced page PNG into --out and rewrite the atlas to the copies, so the directory is ' +
-    'self-contained enough to zip or commit on its own, and point skeleton.images at --out itself so the editor finds ' +
-    'the parts beside the skeleton on import (default: page paths still point at the source art)',
-  pack: 'arrange every part PNG onto shared atlas page(s) written into --out as real PNGs, instead of one page ' +
-    'per part. Lossless: every region is a byte-for-byte copy and nothing is resampled, trimmed or rotated ' +
-    '(default: one part, one page, pointing at the source art)',
-  'page-size': `largest page edge, --pack only (default ${DEFAULT_PAGE_SIZE}); pages are powers of two and the ` +
-    'one written is the smallest that holds the pack, spilling to more pages only when the set will not fit',
-  padding: `gutter each region reserves on every side, --pack only (default ${DEFAULT_PADDING}); it is filled by ` +
-    "extending the region's own edge pixels outwards, which is what stops a neighbour bleeding in",
-  'page-edges': `what a page's edges may be, --pack only (default ${DEFAULT_PAGE_EDGES}): pot is a power of two on ` +
-    'both; free tries every width from the widest part up, takes the height the placement needs and keeps ' +
-    'the least area — a smaller page, at the cost of region attachments sampling within 1 LSB of the loose ' +
-    'build rather than exactly',
-  'atlas-in':
-    'resolve every part against the regions of this pre-packed .atlas instead of against loose PNGs — region ' +
-    'geometry (bounds/offsets/rotate) is read from the file and the atlas is re-emitted into --out, re-anchored',
-  cut: 'look up a named cut in --cuts <cuts.json>, instead of --rig/--motion/--out',
-  cuts: 'the cuts.json --cut names',
-  profile:
-    'which rulebook to check against (default: spine) — spine = valid Spine 4.3 that any runtime plays ' +
-    "correctly; spine-html = also this project's renderer/archetype policy",
-  atlas: "the candidate's atlas, when it is not beside the skeleton",
-  reference: 'the reference skeleton to pose beside the candidate — a directory or a skeleton.json path',
-  'reference-atlas': "the reference's atlas, when it is not beside the reference skeleton",
-  bones: `a bone correspondence — { "spec": "${BONEDIST_SPEC}", "bones": { "<candidate bone>": "<reference bone>" }, ` +
-    '"animations"?: { … } } — or `identity` to state that the two skeletons use the same names. An INPUT, never ' +
-    'derived: a candidate is entitled to its own vocabulary, so a mapping worked out here would be a guess reported ' +
-    'as a measurement',
-  'all-bones': 'print every bone pair, not just the worst by position',
-  geometry:
-    `also write ${GEOMETRY_FILE} into each frame directory: per frame, every bone's world transform and every ` +
-    "slot's region or mesh vertices in world units after skinning, plus each attachment's rest geometry — on the " +
-    'frames\' own grid and viewport. Not with --slot/--hide: the geometry is the whole pose whatever is drawn',
-  poser:
-    "`render` and `check`: which implementation poses the frames (on `check`, the candidate's) — `core` (rigc's own, reading the skeleton.model.json a " +
-    'build writes beside the pair) or `spine` (spine-core). Default: `core` when that document and the atlas sit ' +
-    "beside the skeleton and the skeleton is the one the document records (spine.sha256), `spine` otherwise and wherever the core refuses the input by name; the `poser` " +
-    'line of the render or the check report says which and why. `--poser core` on an input that cannot carry it is refused by name. ' +
-    "`explain`: which reads and poses the DEFORM block's survey — `core` (the model document the compile writes, spine-core untouched) or " +
-    '`spine` (the Spine skeleton parsed and posed by spine-core); default `core`, and `spine` where the core refuses the document, which the block names',
-  'texture-from':
-    "also measure this run through this atlas's texels, keeping the candidate's own geometry, and report how much " +
-    'of the MAE is texture resampling rather than the rig — pass the atlas the reference frames were rendered ' +
-    'through. ⚠️ NOT --atlas: that one names the candidate\'s own atlas and loading a foreign one there re-seats ' +
-    'every region attachment on its packing, so a rotated or trimmed pack moves the geometry too',
-  candidate: 'a compiled skeleton: a directory holding skeleton.json + skeleton.atlas, or a skeleton.json path',
-  frames: 'a rendered reference frame set (a skeleton root, or one animation directory)',
-  fps: 'frame rate, only for a frame set with no frames.json sidecar',
-  viewport: "pin the candidate's world box, y up, instead of fitting it",
-  framing: 'fit each frame set on its own (default) or once across all of them',
-  as: 'the candidate animation to play, when it is named differently from the frame set',
-  'all-frames': 'print every frame, not just the worst by MAE',
-  json: 'also write the whole report to this path',
-  frame: 'one pose frame — a picture of the pose to read the part placements out of',
-  scale: `the scale window to search, as frame pixels per part pixel (default \`${DEFAULT_SCALE_MIN},${DEFAULT_SCALE_MAX}\`)`,
-  rotation: 'the rotation window to search, in screen degrees (default `-180,180`, a full turn)',
-  '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)`,
-  'inward-lever':
-    `how far apart, in frame pixels, two anchored descendants have to sit before the rotation they determine is ` +
-    `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',
-  slot:
-    'draw only these slots, comma-separated, in the skeleton\'s draw order, on the SAME grid as the whole rig: the ' +
-    'viewport is still fitted to every slot, so this frame overlays the full one pixel for pixel. A name the ' +
-    'skeleton does not declare is refused with every one it does; a slot whose art lives only under another skin ' +
-    'is refused naming that skin. frames.json records the subset, and `check` refuses such a set as a reference',
-  hide:
-    'draw every slot but these, comma-separated — `--slot` the other way round, on the same grid, recorded and ' +
-    'refused the same way. Not with `--slot`: the two are one statement',
-  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',
-  dir:
-    `the directory to install into, resolved against your working directory (default \`${DEFAULT_SKILLS_DIR}\`, the ` +
-    'workspace directory Codex, Gemini CLI and Antigravity read skills from)',
-  copy:
-    'copy each skill folder instead of linking it, for a host that does not follow a linked skill folder. A copy ' +
-    'is not reached by an upgrade of the package, and one that is no longer the package\'s bytes is refused by name ' +
-    'on the next run — remove it and run again (default: a relative symlink, which an upgrade reaches with no ' +
-    'second run)',
-  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` — to ADD to a skeleton that declares none. It cannot be ' +
-    'derived: posing the rig gives the ANIMATED extent, which is a different number from the setup box, so this ' +
-    "is the caller's value, and without it the absence is carried: the spec states `\"width\": null, \"height\": " +
-    'null` and the rebuild declares no stage either. ⚠️ An editor export MAY ' +
-    'carry none; every editor export measured for this project carries one and ingest reads it straight through, ' +
-    'so the flag is for a file that really has none rather than for editor exports as a class. ⛔ Beside a ' +
-    'skeleton that already declares a box it is REFUSED rather than ignored: two sources for one value, and the ' +
-    'file is the record of what was measured',
-  help: "show this command's flags and exit",
-};
-
-/** The `<value>` a flag takes, for its column in a command's flag table. Absent for a boolean switch. */
-const FLAG_VALUES: Record<string, string> = {
-  rig: '<path>',
-  motion: '<path>',
-  out: '<dir>',
-  images: '<dir>',
-  manifest: '<path>',
-  cut: '<name>',
-  cuts: '<path>',
-  profile: 'spine|spine-html',
-  atlas: '<path>',
-  'atlas-in': '<file.atlas>',
-  'page-size': '<px>',
-  padding: '<px>',
-  'page-edges': 'pot|free',
-  'texture-from': '<path>',
-  poser: 'core|spine',
-  reference: '<dir|skeleton.json>',
-  'reference-atlas': '<path>',
-  bones: `<correspondence.json|${IDENTITY_CORRESPONDENCE}>`,
-  candidate: '<dir|skeleton.json>',
-  frames: '<dir>',
-  fps: '<n>',
-  viewport: '<x,y,w,h>',
-  framing: 'per-shot|shared',
-  as: '<name>',
-  json: '<out>',
-  frame: '<path>',
-  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>',
-  'inward-lever': '<px>',
-  animation: '<name>',
-  skin: '<name>',
-  slot: '<name[,name…]>',
-  hide: '<name[,name…]>',
-  max: '<px>',
-  record: '<result.json>',
-  ballot: '<ballot.html>',
-  ledger: '<votes.jsonl>',
-  name: '<n>',
-  art: 'loose|none',
-  stage: '<x,y,w,h>',
-  dir: '<path>',
-};
-
-interface CommandDoc {
-  name: string;
-  /** One or more invocation forms, each already spelling the command name. */
-  usage: string[];
-  /** Flag names (into FLAG_MEANINGS/FLAG_VALUES), in display order. `--help` is appended automatically. */
-  flags: string[];
-  /**
-   * 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. 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 }>;
-  /**
-   * Lines printed under the flag table: what this command's own figures mean.
-   *
-   * ⚠️ Not a second place to describe a flag. It exists for what is true of the
-   * **command** and of no flag it takes — and the case that earned it is issue
-   * #678: `pose` and `chainfit` each say *"it is a reporting threshold, not a
-   * pass bar"* on the flag that carries their threshold, and `check` has no such
-   * flag, so its page said nothing at all about whether any of its figures is a
-   * bar to beat. An agent reading `slot drift worst 3.7 px` off a correct rig had
-   * no page to consult and no exit code to read it in.
-   */
-  notes?: string[];
-}
-
-const COMMANDS: CommandDoc[] = [
-  {
-    name: 'build',
-    usage: [
-      'rigc build --rig <path> --motion <path> --out <dir> [--manifest <path>] [--images <dir>] [--profile spine|spine-html] [--copy-images]',
-      `rigc build … --pack [--page-size ${DEFAULT_PAGE_SIZE}] [--padding ${DEFAULT_PADDING}] [--page-edges pot|free]   (parts onto shared pages, written into --out)`,
-      'rigc build … --atlas-in <skeleton.atlas>                    (resolve the parts against a pack somebody already made)',
-      'rigc build --cut <name> --cuts <cuts.json>',
-    ],
-    flags: [
-      'rig',
-      'motion',
-      'out',
-      'manifest',
-      'images',
-      'copy-images',
-      'pack',
-      'page-size',
-      'padding',
-      'page-edges',
-      'atlas-in',
-      'cut',
-      'cuts',
-      'profile',
-    ],
-  },
-  {
-    name: 'explain',
-    usage: [
-      'rigc explain --rig <path> --motion <path> --out <dir> [--manifest <path>] [--images <dir>] [--poser core|spine]   (it never gates, and writes nothing)',
-      'rigc explain … --atlas-in <skeleton.atlas>                  (resolve the parts against a pack somebody already made, as build does)',
-      'rigc explain --cut <name> --cuts <cuts.json>',
-    ],
-    flags: ['rig', 'motion', 'out', 'manifest', 'images', 'atlas-in', 'cut', 'cuts', 'poser'],
-    notes: [
-      'this line said "the same arguments as build, minus --profile" and was false in both',
-      'directions (issue #697): --atlas-in was not listed here, so the one flag that lets this',
-      'command read what `ingest --art none` writes was reachable and undocumented, while',
-      '--pack, --page-size, --padding, --page-edges and --copy-images are build\'s and do nothing here —',
-      'they decide what is WRITTEN, and this command writes nothing. What it takes is listed',
-      'above, and that is now the whole of it.',
-    ],
-  },
-  {
-    name: 'validate',
-    usage: [
-      'rigc validate <dir | skeleton.json> [--atlas <path>] [--profile spine|spine-html]',
-      'rigc validate --cut <name> --cuts <cuts.json>   (also re-derives declared durations)',
-    ],
-    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> [--as <candidate>=<reference>]… [--json <out>]'],
-    flags: ['as', 'json'],
-    overrides: {
-      as: {
-        value: '<candidate>=<reference>',
-        meaning:
-          'pair a candidate animation with a reference one, so the name-agnostic `animations` block can be ' +
-          'measured over shots the two files call different things. Repeatable, one pair each. An INPUT and never ' +
-          'derived: two skeletons cannot say which of their shots are the same shot. Without it the block appears ' +
-          'only when each side has exactly one animation, which pairs by position, and is otherwise absent rather ' +
-          'than guessed',
-      },
-    },
-    notes: [
-      'the `animations` block reads two figures once something has paired the shots, exactly as',
-      '`bones` and `slots` do: name-matched, where `names` lives, and name-agnostic over the pair.',
-      'A candidate that followed a brief withholding the animation name reads `count` 1/1 and 0.000',
-      'on every other name-matched measure — including `duration` and `key_counts` it may have got',
-      'exactly right — so read the pair and not the section mean.',
-    ],
-  },
-  {
-    name: 'check',
-    usage: ['rigc check --candidate <dir | skeleton.json> --frames <dir> [flags]'],
-    flags: ['candidate', 'frames', 'atlas', 'texture-from', 'fps', 'viewport', 'framing', 'as', 'skin', 'poser', 'all-frames', 'json', 'out'],
-    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',
-      },
-      out: {
-        value: '<dir>',
-        meaning:
-          'also write the PICTURE each listed frame\'s figures came from, as <dir>/<set>/f####.png: reference, ' +
-          'candidate, difference and overlay side by side at the comparison grid\'s native size, with the table\'s ' +
-          'figures burned in and one row per slot under them, beside a frames.json that says what they are pictures ' +
-          'of. The frames are the ones the table lists, so --all-frames writes every compared one. Each <dir>/<set>/ ' +
-          'is cleared first; a file at <dir>, or a directory that is or holds --frames, is refused. See ' +
-          'docs/AUTHORING.md §9.2.1',
-      },
-    },
-    notes: [
-      'every figure here is a reporting threshold, not a pass bar. Nothing in this report',
-      'grades, no number has to beat anything, and the exit code says only whether the',
-      'comparison could be MADE: 0 when it ran — including the build with every easing',
-      'reversed, which is the defect this command exists for — 1 when it could not (frames',
-      'that are not there, a skin the frames do not record, a candidate that will not load),',
-      '2 on the flags.',
-      '',
-      'So read a figure against a floor you measured yourself: render the first green build',
-      'and keep its frames, then check every later build against them. The identity run of',
-      'that pair is the floor, and it is not zero — docs/AUTHORING.md §9.2 states it, what',
-      'it comes from, and which column separates a wrong curve from a moved key.',
-    ],
-  },
-  {
-    name: 'bench',
-    usage: [`rigc bench <${RUNG_IDS.join(' | ')}> --candidate <dir | skeleton.json> [--frames <dir>] [flags]`],
-    flags: ['candidate', 'atlas', 'frames', 'profile', 'bones', 'all-frames', 'all-bones', 'json'],
-    overrides: {
-      bones: {
-        meaning:
-          'also run the stage-3 per-frame bone world-transform distance against each of the rung\'s reference ' +
-          `skeletons, with this correspondence (or \`identity\`), at ${PROTOCOL_FPS} fps. Reports; gates nothing — ` +
-          'for another sampling rate call `rigc bonedist` directly, where --fps means only that',
-      },
-    },
-  },
-  {
-    name: 'bonedist',
-    usage: [
-      `rigc bonedist --candidate <dir | skeleton.json> --reference <dir | skeleton.json> --bones <path | ${IDENTITY_CORRESPONDENCE}> [--fps ${PROTOCOL_FPS}] [--all-bones] [--json <out>]`,
-    ],
-    flags: ['candidate', 'atlas', 'reference', 'reference-atlas', 'bones', 'fps', 'all-bones', 'json'],
-    overrides: {
-      fps: { meaning: `the rate both skeletons are sampled at, from t=0 over their own durations (default ${PROTOCOL_FPS})` },
-    },
-  },
-  {
-    name: 'render',
-    usage: [
-      'rigc render --candidate <dir | skeleton.json> [--animation <name>] [--skin <name>] [--fps 12] [--max 256] [--geometry] [--poser core|spine] [--out render/]',
-      'rigc render … --slot <name[,name…]> | --hide <name[,name…]>   (a subset of the slots, on the whole rig\'s grid)',
-    ],
-    flags: ['candidate', 'atlas', 'animation', 'skin', 'slot', 'hide', 'fps', 'max', 'geometry', 'poser', '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})` },
-    },
-  },
-  {
-    name: 'preview',
-    usage: ['rigc preview --candidate <dir | skeleton.json> [--candidate <another> …] [--animation <name>] [--out preview.html]'],
-    flags: ['candidate', 'atlas', 'animation', 'out'],
-    overrides: {
-      candidate: {
-        value: '<dir|skeleton.json>',
-        meaning:
-          'a compiled skeleton: a directory holding skeleton.json + skeleton.atlas, or a skeleton.json path. Repeat it ' +
-          'for one page with a pane per candidate, in the order given; the same skeleton twice is refused. Each ' +
-          'header carries the line `rigc validate <dir>` prints for that candidate, measured when the page is written',
-      },
-      atlas: { meaning: "the candidate's atlas, when it is not beside the skeleton — one candidate only" },
-      animation: {
-        meaning:
-          "the animation to start on (default: each candidate's own first). With several candidates every one of " +
-          'them must have it, or the run is refused naming the one that does not',
-      },
-      out: {
-        value: '<file>',
-        meaning: 'the .html file to write (default `preview.html`); a directory means "the default name in here"',
-      },
-    },
-  },
-  {
-    name: 'pose',
-    usage: [
-      `rigc pose --images <dir> --frame <path> [--scale ${DEFAULT_SCALE_MIN},${DEFAULT_SCALE_MAX}] [--rotation -180,180] [--out ${DEFAULT_POSE_OUT}]`,
-    ],
-    flags: ['images', 'frame', 'scale', 'rotation', 'max-residual', 'out'],
-    overrides: {
-      images: { value: '<dir>', meaning: 'the loose part PNGs to place; every `.png` in it is a part, in name order' },
-      out: {
-        value: '<file>',
-        meaning: `the .json report to write (default \`${DEFAULT_POSE_OUT}\`); a directory means "the default name in here"`,
-      },
-    },
-  },
-  {
-    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',
-      'inward-lever',
-      '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: [
-      `rigc vote --candidate <dir | skeleton.json> --candidate <…> [--candidate …] [--animation <name>] [--out ${DEFAULT_BALLOT}]`,
-      `rigc vote --record <result.json> [--ballot ${DEFAULT_BALLOT}] [--ledger ${DEFAULT_LEDGER}] [--again]`,
-    ],
-    flags: ['candidate', 'animation', 'out', 'record', 'ballot', 'ledger', 'again'],
-    overrides: {
-      candidate: {
-        value: '<dir|skeleton.json>',
-        meaning: `repeat it ${MIN_CANDIDATES}–${MAX_CANDIDATES} times — one compiled artifact per pane, labelled A, B, C, D in the order given`,
-      },
-      animation: {
-        meaning:
-          'the one animation every pane plays (default: the first of candidate A). A candidate that does not have ' +
-          'it is refused — two panes playing two animations is not a comparison',
-      },
-      out: {
-        value: '<file>',
-        meaning: `the .html ballot to write (default \`${DEFAULT_BALLOT}\`); a directory means "the default name in here"`,
-      },
-    },
-  },
-  {
-    name: 'skills',
-    usage: [`rigc skills install [--dir ${DEFAULT_SKILLS_DIR}] [--copy]   (every skill this package ships, where an agent host looks)`],
-    flags: ['dir', 'copy'],
-    notes: [
-      'the skills installed are the skills/ directory of the package this command runs from,',
-      'never whatever the working directory holds. Each becomes <dir>/<name>: a relative',
-      'symlink into that folder, or with --copy a copy of it. An entry already there that',
-      'is not a link to the same folder — or, with --copy, not the same bytes — is refused',
-      'by name, exit 1, and nothing is written; a run over only what this command made has',
-      'nothing to do and exits 0. Codex, Gemini CLI and Antigravity read',
-      `<workspace>/${DEFAULT_SKILLS_DIR}; Claude Code installs the plugin instead (README,`,
-      '"Install it into your agent").',
-    ],
-  },
-];
-
-const KNOWN_COMMANDS = COMMANDS.map((c) => c.name);
-
-/** `rigc <command> --help`: that command's own usage line(s) and flag table. */
-function commandHelp(name: string): string {
-  const doc = COMMANDS.find((c) => c.name === name);
-  if (!doc) throw new Error(`internal: no help text for command "${name}"`);
-  const keys = [...doc.flags, 'help'];
-  const value = (key: string): string | undefined => doc.overrides?.[key]?.value ?? FLAG_VALUES[key];
-  const meaning = (key: string): string => doc.overrides?.[key]?.meaning ?? FLAG_MEANINGS[key];
-  const labels = keys.map((key) => `--${key}${value(key) ? ` ${value(key)}` : ''}`);
-  const width = Math.max(...labels.map((l) => l.length)) + 2;
-  return [
-    'usage:',
-    ...doc.usage.map((u) => `  ${u}`),
-    '',
-    'flags:',
-    ...keys.map((key, i) => `  ${labels[i].padEnd(width)}${meaning(key)}`),
-    ...(doc.notes === undefined ? [] : ['', ...doc.notes]),
-  ].join('\n');
-}
-
-const USAGE = [
-  'rigc — the rig compiler',
-  '',
-  '(from a source checkout: `bun cli.ts <command>` is the same as `rigc <command>`)',
-  '',
-  'usage:',
-  ...COMMANDS.flatMap((c) => c.usage.map((u) => `  ${u}`)),
-  '',
-  '  rigc <command> --help    that command\'s own flag table',
-  '  rigc --version           print the installed version (-v works too)',
-  '',
-  'build, validate and bench take --profile spine|spine-html:',
-  '  spine       is this valid Spine 4.3 that any runtime plays correctly?',
-  `              THE DEFAULT — ${assertionCountForProfile('spine')} rules, and the question the output answers when`,
-  '              you import it into the Spine editor.',
-  '  spine-html  the above, plus this project\'s renderer and archetype policy:',
-  `              all ${assertionCountForProfile('spine-html')} rules, opt-in. Those extra ` +
-    `${assertionCountForProfile('spine-html') - assertionCountForProfile('spine')} fire on real, correct,`,
-  '              editor-produced Spine data, so they are somebody\'s policy rather',
-  '              than anybody\'s validity.',
-  '',
-  'Every report names the profile that judged it and lists, on PROF lines, the',
-  'rules that profile left out.',
-  '',
-  'check renders the candidate onto the reference frames\' own pixel grid, fitting it',
-  'there by its own drawn pixels, and compares. It reads the frames and never the',
-  'reference skeleton, so it belongs INSIDE an authoring loop — the validator cannot',
-  'see a wrong animation and this can. See `rigc check --help` for its flags.',
-  '',
-  'render and preview are how you LOOK at a build, and they need no reference at all:',
-  '  rigc render  --candidate <the dir build --out wrote>    PNG frames + a contact sheet',
-  '  rigc preview --candidate <the same dir>                 one .html file that plays it',
-  'A rig with its head off its torso passes the gate and steps cleanly — the offsets',
-  'are the ones you asked for — so looking is the only thing that catches it. render',
-  '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/ --images parts/         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 how the spec reaches the art is the caller\'s (--art) and is not guessed.',
-  'A setup stage the skeleton states is read; one it does not state is carried as',
-  'absent, and --stage is how a caller adds a box to such a file — beside a box the',
-  'file states, the flag is refused rather than ignored. --images <dir> 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:',
-  '  rigc pose --images parts/ --frame poseA.png       pose.json, one entry per part',
-  'It grades nothing and no pass bar attaches to its numbers. The residual is a trust',
-  'signal, and where two placements are equally good it reports BOTH rather than picking —',
-  'two identical limbs look exactly like that. A part that matches nowhere, a part the',
-  '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',
-  'Reach for it where the instruments have run out — a choice with no reference behind',
-  'it, two fits that measure the same. The panes carry no paths, a tie is a recorded',
-  'answer rather than a missing one, and a result whose hashes are not the ballot\'s is',
-  'refused by name instead of appended.',
-  '',
-  'skills install puts the agent skills this package ships where an agent host looks',
-  'for them, since none of them reads node_modules:',
-  `  rigc skills install               relative links in ${DEFAULT_SKILLS_DIR}, which Codex, Gemini CLI`,
-  '                                    and Antigravity read; --copy writes the folders instead',
-  'An entry already there that this command did not make is refused by name and',
-  'nothing is written; a second run has nothing to do. See `rigc skills --help`.',
-  '',
-  'a cuts.json is { "<name>": { "rig": "...", "motion": "...", "out": "...",',
-  '                             "manifest": "..." (optional) } }, with every path',
-  'resolved relative to the cuts.json file itself.',
-].join('\n');
-
-const [command, ...rest] = process.argv.slice(2);
-try {
-  if (command === undefined) {
-    console.error(USAGE);
-    process.exit(2);
-  }
-  if (command === '--version' || command === '-v') {
-    console.log(readVersion());
-    process.exit(0);
-  }
-  if (command === '--help' || command === '-h') {
-    console.log(USAGE);
-    process.exit(0);
-  }
-  if (!KNOWN_COMMANDS.includes(command)) {
-    throw new UsageError(`unknown command: ${command}`);
-  }
-
-  const { flags, lists, positional } = parseArgs(rest, REPEATABLE_FLAGS[command]);
-  if (flags.help !== undefined) {
-    console.log(commandHelp(command));
-    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, lists, positional);
-  else if (command === 'check') cmdCheck(flags);
-  else if (command === 'bench') cmdBench(flags, positional);
-  else if (command === 'bonedist') cmdBoneDist(flags);
-  else if (command === 'render') cmdRender(flags);
-  else if (command === 'preview') cmdPreview(flags, lists.candidate ?? []);
-  else if (command === 'pose') cmdPose(flags);
-  else if (command === 'chainfit') cmdChainFit(flags);
-  else if (command === 'vote') cmdVote(flags, lists.candidate ?? []);
-  else if (command === 'skills') cmdSkills(flags, positional);
-} catch (err) {
-  if (err instanceof UsageError) {
-    console.error(`rigc: ${err.message}\n\n${USAGE}`);
-    process.exit(2);
-  }
-  // A ballot refuses on its arguments, like a usage error, but its messages are
-  // long enough that reprinting the whole usage under them buries the reason.
-  if (err instanceof BallotError) {
-    console.error(`rigc vote: ${err.message}`);
-    process.exit(2);
-  }
-  if (err instanceof CompileError) {
-    console.error(`rigc compile error: ${err.message}`);
-    // The drops the compile recorded before it stopped, in the same line the
-    // green build prints (issue #671). They were reported from the compile
-    // RESULT alone, so the run that failed BECAUSE a file was missing was the
-    // one run that never named the file. On stderr with the refusal rather than
-    // on stdout, so redirecting one stream does not separate a fact from the
-    // sentence it explains.
-    for (const dropped of err.droppedStates ?? []) console.error(dropLine(dropped));
-    process.exit(1);
-  }
-  if (err instanceof CheckError) {
-    console.error(`rigc check error: ${err.message}`);
-    process.exit(1);
-  }
-  if (err instanceof BoneDistError) {
-    console.error(`rigc bonedist error: ${err.message}`);
-    process.exit(1);
-  }
-  // Like a usage error in kind — a missing directory, an unreadable frame — but
-  // its messages name a path and a reason, and reprinting the whole usage under
-  // them buries that.
-  if (err instanceof PoseError) {
-    console.error(`rigc pose: ${err.message}`);
-    process.exit(2);
-  }
-  // A refusal of the invocation, like the two below it, and exit 2 for the same
-  // reason: nothing was posed and nothing was written, so it is the command line
-  // that has to change (issue #697).
-  if (err instanceof ExplainError) {
-    console.error(`rigc explain: ${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);
-  }
-  // A usage error in kind — an option that contradicts the file it was given —
-  // and exit 2 for that reason rather than 1: nothing was compiled and nothing
-  // was written, so it is the invocation that has to change (issue #626). It is
-  // raised in `src/ingest.ts` rather than here because the library caller who
-  // passes the same contradiction deserves the same refusal, and one rule in one
-  // place is what stops the two from drifting apart.
-  if (err instanceof IngestError) {
-    console.error(`rigc ingest: ${err.message}`);
-    process.exit(2);
-  }
-  // A page or frame that is not a PNG rigc can read, from any command that
-  // opens one (`render`, `check`, `preview`, …) — issue #732. The sentence is
-  // the one reader's and already names the file, what it is and what rigc
-  // reads; a stack under it is the tool describing its own internals instead.
-  // Exit 1, like a compile error: the invocation was fine, a file was not.
-  // A pose that is not finite (issues #864, #873): the invocation was fine and
-  // the skeleton posed a NaN or an infinity, so exit 1 like a file that is not
-  // a PNG. Raised by the geometry export and by the framing — the one sentence
-  // naming the bone or vertex and its value — before the first file is written.
-  // A pose whose every drawn vertex sits at one point (issue #997), from
-  // `render` or `check`: exit 2 like *nothing to draw*, the other framing
-  // refusal, because the usual fix is the invocation's — `--skin` — and nothing
-  // was written. A `GeometryError` in kind, so it is caught before that.
-  if (err instanceof UnframeablePoseError) {
-    console.error(`rigc ${command}: ${err.message}`);
-    process.exit(2);
-  }
-  if (err instanceof GeometryError) {
-    console.error(`rigc render: ${err.message}`);
-    process.exit(1);
-  }
-  // `--poser core` on an input the core cannot carry (issue #968): a refusal of
-  // the invocation, nothing written, and the message names the input and why —
-  // the usage under it would bury that. Without the flag the same refusal is a
-  // fallback to spine-core, named on the render's `poser` line instead.
-  if (err instanceof PoserChoiceError) {
-    console.error(`rigc ${command}: ${err.message}`);
-    process.exit(2);
-  }
-  if (err instanceof NotAPngError) {
-    console.error(`rigc: ${err.message}`);
-    process.exit(1);
-  }
-  // An input posed through spine-core — a Spine export, `--poser spine`, a
-  // fallback — on a run where the runtime cannot be used (issue #1014). The
-  // sentence names the input and why it needs the runtime; exit 1, like a file
-  // that is not a PNG: the invocation was fine and the run could not pose it.
-  // A candidate with no atlas beside it that has to be read through one (issue
-  // #1020): a refusal of the invocation like a missing atlas on an export, exit
-  // 2 and nothing written, and the message names the file and why it is needed.
-  if (err instanceof CandidateAtlasError) {
-    console.error(`rigc ${command}: ${err.message}`);
-    process.exit(2);
-  }
-  // A skeleton spine-core could not load against the atlas beside it (issue #1033) — on a rigc build, a
-  // skeleton.json or an atlas from another build beside this one's model document. The same class as the
-  // missing atlas above: nothing was posed or written, and it is the directory the command was pointed at that
-  // has to change. The message names both files, the reason the runtime drew them and the runtime's own words.
-  // Since issue #1042 also `bonedist` and `bench --bones` on either side, and a page a candidate is drawn from that
-  // is not there, whichever poser draws it.
-  if (err instanceof CandidatePairError) {
-    console.error(`rigc ${command}: ${err.message}`);
-    process.exit(2);
-  }
-  if (err instanceof SpineRuntimeError) {
-    console.error(`rigc ${command}: ${err.message}`);
-    process.exit(1);
-  }
-  // An install refused before its first write (issue #831): the invocation was
-  // fine and an entry on disk was not what this command would write, so exit 1
-  // like a file that is not a PNG. The message names every such entry, what is
-  // there and what was required; the usage under it would bury that.
-  if (err instanceof SkillsInstallError) {
-    console.error(`rigc skills install: ${err.message}`);
-    process.exit(1);
-  }
-  throw err;
-}
+import { PROFILE_RULES, SPINE_COMMAND_REFUSALS, SPINE_COMMAND_RUNS } from './src/cli/spine_commands.ts';
+import { CORE_COMMAND_RUNS } from './src/cli/core_commands.ts';
+import { runCli } from './src/cli/shared.ts';
+// The Spine side of the seam (issue #1052): loading the modules that link spine-core registers what they pose and read
+// through it — an export's poser and loader, `--poser spine`, a fallback, the deform survey through the runtime — into
+// `src/spine_side.ts`, which the commands below reach it through.
+import './src/render.ts';
+import './src/deformmeasure.ts';
+
+/**
+ * One entry of a cuts.json, every path relative to the cuts.json file — the
+ * shape `src/cli/shared.ts` reads, re-exported where it was always declared.
+ */
+export type { CutEntry, CutTable } from './src/cli/shared.ts';
+
+// ⭐ Every command, every refusal and every exit code as they always were: the dispatch, the documentation and the
+// bodies moved to `src/cli/` unchanged (issue #1052), and this entry registers all of them. `cli_core.ts` registers the
+// commands whose bodies reach nothing of the runtime, and links none of it.
+runCli(
+  {
+    checkout: 'cli.ts',
+    linksRuntime: true,
+    runs: { ...CORE_COMMAND_RUNS, ...SPINE_COMMAND_RUNS },
+    profileRules: PROFILE_RULES,
+    refusals: SPINE_COMMAND_REFUSALS,
+  },
+  process.argv.slice(2),
+);