spine-rigc 0.5.0 → 0.7.0

package/cli.ts

@@ -31,13 +31,50 @@
  * 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 { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
+import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, 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 { checkAgainstFrames, checkLines, CheckError, type CheckOptions, type CheckReport } from './src/check.ts';
 import { compile, CompileError, type CompileOptions } from './src/compile.ts';
 import { diffLines, diffSkeletons, sectionFigures, type DiffReport } from './src/diff.ts';
+import { copyAtlasImages } from './src/emit.ts';
+import { parseJsonWithPosition } from './src/json-position.ts';
 import { findRung, RUNG_IDS, type RungSkeleton } from './src/ladder.ts';
-import { DEFAULT_PROFILE, reportLines, validate, VALIDATE_PROFILES, type ValidateProfile } from './src/validate.ts';
+import { buildPreview, PLAYER_LINE, type PreviewPage } from './src/preview.ts';
+import {
+  atlasPageNames,
+  BACKGROUND,
+  contactSheet,
+  FRAMES_SIDECAR,
+  FRAMES_SPEC,
+  framingViewport,
+  loadPosable,
+  PROTOCOL_FPS,
+  renderFrame,
+  sampleAll,
+  sampleAnimation,
+  SETUP_POSE_DIR,
+  SHEET_FILE,
+  SHEET_TILE,
+  type Frame,
+  type FramesSidecar,
+  type FrameSet,
+} from './src/render.ts';
+import { CLI_DEFAULT_PROFILE, reportLines, validate, VALIDATE_PROFILES, type ValidateProfile } from './src/validate.ts';
 import type { CompileResult, MotionSpec } from './src/types.ts';
 
 /**
@@ -61,6 +98,40 @@ export type CutTable = Record<string, CutEntry>;
 
 class UsageError 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
 // ---------------------------------------------------------------------------
@@ -72,31 +143,78 @@ class UsageError extends Error {}
  * flag": inferring it would turn `--out --json report.json` — a real typo, a
  * missing value — into a silently accepted switch plus a stray positional.
  */
-const BOOLEAN_FLAGS = new Set(['all-frames']);
+const BOOLEAN_FLAGS = new Set(['all-frames', 'help', 'copy-images', 'again']);
 
-/** `--flag value` pairs plus the leftover positionals, in order. */
-function parseArgs(argv: string[]): { flags: Record<string, string>; positional: string[] } {
+/**
+ * The flags a command is allowed to spell more than once.
+ *
+ * Only `vote --candidate` is, because a ballot is *by definition* several
+ * candidates. 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']),
+};
+
+/**
+ * `--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) {
-        flags[arg.slice(2, eq)] = arg.slice(eq + 1);
+        take(arg.slice(2, eq), arg.slice(eq + 1));
       } else if (BOOLEAN_FLAGS.has(arg.slice(2))) {
-        flags[arg.slice(2)] = 'true';
+        take(arg.slice(2), 'true');
       } else {
         const next = argv[i + 1];
         if (next === undefined || next.startsWith('--')) throw new UsageError(`${arg} needs a value`);
-        flags[arg.slice(2)] = next;
+        take(arg.slice(2), next);
         i++;
       }
     } else {
       positional.push(arg);
     }
   }
-  return { flags, positional };
+  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 {
+  try {
+    return parseJsonWithPosition(readFileSync(path, 'utf8'));
+  } catch (err) {
+    throw new UsageError(`cannot read ${path}: ${(err as Error).message}`);
+  }
 }
 
 /**
@@ -107,7 +225,7 @@ function parseArgs(argv: string[]): { flags: Record<string, string>; positional:
 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: unknown = JSON.parse(readFileSync(abs, 'utf8'));
+  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 }`);
   }
@@ -168,14 +286,17 @@ function resolveCut(flags: Record<string, string>): { label: string; opts: Compi
 // ---------------------------------------------------------------------------
 
 /**
- * Read `--profile`, defaulting to the profile every caller had before the flag
- * existed. An unknown name is a usage error rather than a silent fallback: the
- * fallback would be `spine-html`, so a typo would quietly re-apply the strictest
- * rulebook to data the caller was trying to exempt.
+ * 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 DEFAULT_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;
@@ -206,6 +327,12 @@ function cmdBuild(flags: Record<string, string>): void {
   const { label, opts } = resolveCut(flags);
   const profile = readProfile(flags);
   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);
 
   console.log(`  ..    ${result.images.length} part page(s):`);
@@ -241,8 +368,25 @@ function cmdBuild(flags: Record<string, string>): void {
   }
 
   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.
+  let atlasText = result.atlasText;
+  if (flags['copy-images'] !== undefined) {
+    const copied = copyAtlasImages(result.images, opts.outDir);
+    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 from ${basename(p.from)} — basename collision)`;
+      console.log(`  ..      ${p.region.padEnd(24)} <- ${p.to}${note}`);
+    }
+  }
+
   writeFileSync(join(opts.outDir, 'skeleton.json'), result.skeletonText);
-  writeFileSync(join(opts.outDir, 'skeleton.atlas'), result.atlasText);
+  writeFileSync(join(opts.outDir, 'skeleton.atlas'), atlasText);
   console.log(`rigc: wrote ${join(opts.outDir, 'skeleton.json')}`);
   console.log(`rigc: wrote ${join(opts.outDir, 'skeleton.atlas')}`);
 }
@@ -325,10 +469,7 @@ function cmdDiff(flags: Record<string, string>, positional: string[]): void {
   for (const path of [candidatePath, referencePath]) {
     if (!existsSync(path)) throw new UsageError(`nothing at ${path}`);
   }
-  const report = diffSkeletons(
-    JSON.parse(readFileSync(candidatePath, 'utf8')),
-    JSON.parse(readFileSync(referencePath, 'utf8')),
-  );
+  const report = diffSkeletons(readJsonFile(candidatePath), readJsonFile(referencePath));
   console.log('rigc diff');
   for (const line of diffLines(report, { candidate: candidatePath, reference: referencePath })) console.log(line);
   if (flags.json !== undefined) {
@@ -411,14 +552,452 @@ function writeJson(target: string, body: unknown): void {
   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) };
+}
+
+/** `--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;
+}
+
+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;
+}
+
+/**
+ * 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 {
+  const { skeletonPath, atlasPath, atlasDir } = resolveViewable(flags);
+  const fps = readPositiveNumber(flags, 'fps', PROTOCOL_FPS, 1);
+  const maxSide = readPositiveNumber(flags, 'max', 256, 16);
+  const outRoot = resolve(flags.out ?? 'render');
+
+  console.log('rigc render');
+  console.log(`  ..    skeleton ${skeletonPath}`);
+  console.log(`  ..    atlas    ${atlasPath}`);
+  const { data, pages } = loadPosable(skeletonPath, atlasPath, atlasDir);
+  const only = readAnimationFlag(flags, data.animations.map((a) => a.name));
+
+  const viewport = framingViewport(data, maxSide);
+  if (!viewport) {
+    throw new UsageError(
+      `${skeletonPath} posed no drawable attachment in any animation or in its setup pose — 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.
+  const sampled: Map<string, Frame[]> =
+    only === undefined ? sampleAll(data, fps) : new Map([[only, sampleAnimation(data, only, fps)]]);
+  console.log(`  ..    ${viewport.width}x${viewport.height}px at ${fps} fps, ${sampled.size} set(s) -> ${outRoot}`);
+
+  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 duration = frames[frames.length - 1].time;
+    sets.push({
+      dir: dirName,
+      animation: name === SETUP_POSE_DIR && data.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`;
+    console.log(`  ..    ${name.padEnd(16)} ${frames.length} frame(s), ${how}${sheet ? ` + ${SHEET_FILE}` : ''} -> ${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,
+    background: BACKGROUND,
+    viewport: {
+      x: viewport.minX,
+      y: viewport.minY,
+      width: viewport.maxX - viewport.minX,
+      height: viewport.maxY - viewport.minY,
+      scale: viewport.scale,
+      pixelWidth: viewport.width,
+      pixelHeight: viewport.height,
+    },
+    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[] {
+  let parsed: unknown;
+  try {
+    parsed = parseJsonWithPosition(skeletonText);
+  } catch (err) {
+    throw new UsageError(`cannot read ${path}: ${(err as Error).message}`);
+  }
+  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);
+}
+
+/**
+ * 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>): void {
+  const { skeletonPath, atlasPath, atlasDir } = resolveViewable(flags);
+  const skeletonText = readFileSync(skeletonPath, 'utf8');
+  const atlasText = readFileSync(atlasPath, 'utf8');
+  const animations = skeletonAnimationNames(skeletonText, skeletonPath);
+  const chosen = readAnimationFlag(flags, animations);
+
+  // 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;
+
+  console.log('rigc preview');
+  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`);
+  }
+
+  const html = buildPreview({
+    skeletonText,
+    atlasText,
+    pages,
+    animation: chosen ?? animations[0] ?? null,
+    animations,
+    label: skeletonPath,
+    version: readVersion(),
+  });
+  mkdirSync(dirname(out), { recursive: true });
+  writeFileSync(out, html);
+  console.log(
+    `  ..    embedded ${pages.length} 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)`);
+}
+
+// ---------------------------------------------------------------------------
+// choosing between results — vote
+// ---------------------------------------------------------------------------
+//
+// ⭐ `preview` shows one candidate; this shows two to four of them side by side
+// 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. `spine-html` is not the default
- *      here (it is everywhere else): the thing being reproduced is an editor
+ *      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
@@ -438,13 +1017,22 @@ function cmdBench(flags: Record<string, string>, positional: string[]): void {
   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 the default.
-  const profile = flags.profile === undefined ? 'spine' : readProfile(flags);
+  // 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)) {
-    throw new UsageError(
-      `no example corpus at ${exportDir} — run \`bun run fetch-examples\` first (examples/ is gitignored, not shipped)`,
-    );
+    // `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)`);
   }
 
   const { skeletonPath, atlasPath } = resolveArtifacts(flags.candidate, flags.atlas);
@@ -615,10 +1203,14 @@ function cmdBench(flags: Record<string, string>, positional: string[]): void {
 
 function cmdExplain(flags: Record<string, string>): void {
   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);
-  const motion = JSON.parse(readFileSync(opts.motionPath, 'utf8')) as MotionSpec;
+  const motion = readJsonFile(opts.motionPath) as MotionSpec;
 
-  console.log(`rigc explain ${label}`);
   console.log(`\nstage  ${result.skeleton.skeleton.width} x ${result.skeleton.skeleton.height}  (spine ${result.skeleton.skeleton.spine})`);
 
   // The crop note describes where the numbers CAME from, and without a manifest
@@ -684,6 +1276,46 @@ function cmdExplain(flags: Record<string, string>): void {
         }
       }
     }
+    // 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(key.time).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 key of keys) {
+              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}`);
+            }
+          }
+        }
+      }
+    }
     // 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.
@@ -725,35 +1357,238 @@ function cmdExplain(flags: Record<string, string>): void {
   console.log(`  default=${motion.mix?.default ?? 0} pairs=${JSON.stringify(motion.mix?.pairs ?? [])}`);
 }
 
+// ---------------------------------------------------------------------------
+// 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; atlas page paths 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 (default: page paths still point at the source art)',
+  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",
+  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',
+  animation: 'which animation to show; the default is every one for `render` and the first for `preview`',
+  max: 'longest side of a rendered frame, in pixels (default 256)',
+  record: 'a saved vote to check against its ballot and append to the ledger, instead of writing a ballot',
+  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',
+  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>',
+  candidate: '<dir|skeleton.json>',
+  frames: '<dir>',
+  fps: '<n>',
+  viewport: '<x,y,w,h>',
+  framing: 'per-shot|shared',
+  as: '<name>',
+  json: '<out>',
+  animation: '<name>',
+  max: '<px>',
+  record: '<result.json>',
+  ballot: '<ballot.html>',
+  ledger: '<votes.jsonl>',
+};
+
+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. Three flags earn it:
+   * `--out` is a directory of artifacts to `build`, 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.
+   */
+  overrides?: Record<string, { value?: string; meaning?: 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 --cut <name> --cuts <cuts.json>',
+    ],
+    flags: ['rig', 'motion', 'out', 'manifest', 'images', 'copy-images', 'cut', 'cuts', 'profile'],
+  },
+  {
+    name: 'explain',
+    usage: ['rigc explain  (same arguments as build, minus --profile — it never gates)'],
+    flags: ['rig', 'motion', 'out', 'manifest', 'images', 'cut', 'cuts'],
+  },
+  {
+    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: 'diff',
+    usage: ['rigc diff <candidate.json> <reference.json> [--json <out>]'],
+    flags: ['json'],
+  },
+  {
+    name: 'check',
+    usage: ['rigc check --candidate <dir | skeleton.json> --frames <dir> [flags]'],
+    flags: ['candidate', 'frames', 'atlas', 'fps', 'viewport', 'framing', 'as', 'all-frames', 'json'],
+  },
+  {
+    name: 'bench',
+    usage: [`rigc bench <${RUNG_IDS.join(' | ')}> --candidate <dir | skeleton.json> [--frames <dir>] [flags]`],
+    flags: ['candidate', 'atlas', 'frames', 'profile', 'all-frames', 'json'],
+  },
+  {
+    name: 'render',
+    usage: [
+      'rigc render --candidate <dir | skeleton.json> [--animation <name>] [--fps 12] [--max 256] [--out render/]',
+    ],
+    flags: ['candidate', 'atlas', 'animation', 'fps', 'max', 'out'],
+    overrides: {
+      out: { value: '<dir>', meaning: 'directory to write the frame series into (default `render/`)' },
+      fps: { meaning: `frames per second to sample the animation at (default ${PROTOCOL_FPS})` },
+    },
+  },
+  {
+    name: 'preview',
+    usage: ['rigc preview --candidate <dir | skeleton.json> [--animation <name>] [--out preview.html]'],
+    flags: ['candidate', 'atlas', 'animation', 'out'],
+    overrides: {
+      out: {
+        value: '<file>',
+        meaning: 'the .html file to write (default `preview.html`); 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"`,
+      },
+    },
+  },
+];
+
+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)}`)].join(
+    '\n',
+  );
+}
+
 const USAGE = [
+  'rigc — the rig compiler',
+  '',
+  '(from a source checkout: `bun cli.ts <command>` is the same as `rigc <command>`)',
+  '',
   'usage:',
-  '  bun cli.ts build    --rig <path> --motion <path> --out <dir> [--manifest <path>] [--images <dir>]',
-  '  bun cli.ts build    --cut <name> --cuts <cuts.json>',
-  '  bun cli.ts explain  (same arguments as build)',
-  '  bun cli.ts validate <dir | skeleton.json> [--atlas <path>]',
-  '  bun cli.ts diff     <candidate.json> <reference.json> [--json <out>]',
-  '  bun cli.ts check    --candidate <dir | skeleton.json> --frames <dir>',
-  `  bun cli.ts bench    <${RUNG_IDS.join(' | ')}> --candidate <dir | skeleton.json> [--frames <dir>]`,
+  ...COMMANDS.flatMap((c) => c.usage.map((u) => `  ${u}`)),
   '',
-  'build and validate take --profile spine|spine-html (default spine-html):',
+  '  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?',
-  '  spine-html  the above, plus this project\'s renderer and archetype policy.',
+  '              THE DEFAULT — 20 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 36 rules, opt-in. Those extra 14 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:',
-  '  --frames <dir>        a rendered frame set (a skeleton root, or one animation dir)',
-  '  --atlas <path>        the candidate\'s atlas, when it is not beside the skeleton',
-  '  --fps <n>             only for a frame set with no frames.json sidecar',
-  '  --viewport x,y,w,h    pin the candidate\'s world box, y up, instead of fitting it',
-  '  --framing per-shot|shared   decide the framing per frame set (default), or once',
-  '                        across all of them. Per set, a set whose own pixels land in',
-  '                        frames.json\'s box is measured there; on a multi-shot root that',
-  '                        is worth 15-25 MAE against one shared fit for every set',
-  '  --as <name>           the candidate animation to play, when it is named differently',
-  '  --all-frames          print every frame, not just the worst by MAE',
-  '  --json <out>          the whole per-frame, per-slot report',
+  '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.',
+  '',
+  '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.',
   '',
   'a cuts.json is { "<name>": { "rig": "...", "motion": "...", "out": "...",',
   '                             "manifest": "..." (optional) } }, with every path',
@@ -762,22 +1597,47 @@ const USAGE = [
 
 const [command, ...rest] = process.argv.slice(2);
 try {
-  const { flags, positional } = parseArgs(rest);
+  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 === 'validate') cmdValidate(flags, positional);
   else if (command === 'explain') cmdExplain(flags);
   else if (command === 'diff') cmdDiff(flags, positional);
   else if (command === 'check') cmdCheck(flags);
   else if (command === 'bench') cmdBench(flags, positional);
-  else {
-    console.error(USAGE);
-    process.exit(2);
-  }
+  else if (command === 'render') cmdRender(flags);
+  else if (command === 'preview') cmdPreview(flags);
+  else if (command === 'vote') cmdVote(flags, lists.candidate ?? []);
 } 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}`);
     process.exit(1);