spine-rigc 1.0.2 → 1.2.0

package/cli.ts

@@ -31,8 +31,22 @@
  * 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, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
-import { basename, dirname, join, resolve } from 'node:path';
+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,
@@ -56,7 +70,15 @@ import {
   IDENTITY_CORRESPONDENCE,
   type BoneDistReport,
 } from './src/bonedist.ts';
-import { checkAgainstFrames, checkLines, CheckError, type CheckOptions, type CheckReport } from './src/check.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 {
   skeletonDataFromText,
@@ -111,7 +133,7 @@ import {
   estimateChainFit,
   type ChainFitOptions,
 } from './src/chainfit.ts';
-import { buildPreview, PLAYER_LINE, type PreviewPage } from './src/preview.ts';
+import { buildPreview, buildPreviewPanes, PLAYER_LINE, type PreviewGate, type PreviewInput, type PreviewPage } from './src/preview.ts';
 import {
   atlasPageNames,
   BACKGROUND,
@@ -127,9 +149,13 @@ import {
   SETUP_POSE_DIR,
   SHEET_FILE,
   SHEET_TILE,
+  SlotSubsetError,
+  slotSubsetOf,
   type Frame,
   type FramesSidecar,
   type FrameSet,
+  type Posable,
+  type SlotSubset,
 } from './src/render.ts';
 import {
   assertionCountForProfile,
@@ -229,14 +255,15 @@ function repositoryUrl(): string {
  * 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']);
+const BOOLEAN_FLAGS = new Set(['all-frames', 'all-bones', 'help', 'copy-images', 'again', 'pack', 'copy']);
 
 /**
  * The flags a command is allowed to spell more than once.
  *
  * `vote --candidate` is, because a ballot is *by definition* several
- * candidates, 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
+ * 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.
@@ -244,6 +271,7 @@ const BOOLEAN_FLAGS = new Set(['all-frames', 'all-bones', 'help', 'copy-images',
 const REPEATABLE_FLAGS: Record<string, ReadonlySet<string>> = {
   vote: new Set(['candidate']),
   diff: new Set(['as']),
+  preview: new Set(['candidate']),
 };
 
 /**
@@ -1470,6 +1498,12 @@ function cmdBuild(flags: Record<string, string>): void {
   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')}`);
+  // 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}`);
 }
 
 /**
@@ -1686,7 +1720,13 @@ function readCheckFlags(
   return out;
 }
 
-function runCheck(candidate: string, atlasFlag: string | undefined, framesDir: string, flags: Record<string, string>): CheckReport {
+function runCheck(
+  candidate: string,
+  atlasFlag: string | undefined,
+  framesDir: string,
+  flags: Record<string, string>,
+  plates?: CheckPlates,
+): CheckReport {
   const { skeletonPath, atlasPath } = resolveArtifacts(candidate, atlasFlag);
   return checkAgainstFrames({
     skeletonText: readFileSync(skeletonPath, 'utf8'),
@@ -1695,16 +1735,59 @@ function runCheck(candidate: string, atlasFlag: string | undefined, framesDir: s
     framesDir,
     labels: { skeleton: skeletonPath, atlas: atlasPath },
     ...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 report = runCheck(flags.candidate, flags.atlas, flags.frames, flags);
+  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: flags['all-frames'] !== undefined })) console.log(line);
+  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 {
@@ -1787,6 +1870,35 @@ function readSkinFlag(flags: Record<string, string>, declared: string[]): string
   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>,
+  data: Posable['data'],
+  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 slotSubsetOf(data, { slots: list(flags.slot), hidden: list(flags.hide) }, skin);
+  } catch (err) {
+    if (err instanceof SlotSubsetError) throw new UsageError(err.message);
+    throw err;
+  }
+}
+
+/** 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;
@@ -1855,12 +1967,19 @@ function cmdRender(flags: Record<string, string>): void {
   const { data, pages } = loadPosable(skeletonPath, atlasPath, atlasDir);
   const only = readAnimationFlag(flags, data.animations.map((a) => a.name));
   const skin = readSkinFlag(flags, data.skins.map((s) => s.name));
+  const subset = readSlotSubsetFlags(flags, data, 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.
-  const pose = skin === undefined ? undefined : { skin };
+  // 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(', ')}`);
 
   const viewport = framingViewport(data, maxSide, pose);
   if (!viewport) {
@@ -1922,6 +2041,9 @@ function cmdRender(flags: Record<string, string>): void {
     // 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,
     viewport: {
       x: viewport.minX,
@@ -1955,6 +2077,29 @@ function skeletonAnimationNames(skeletonText: string, path: string): string[] {
   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.
  *
@@ -1963,52 +2108,130 @@ function skeletonAnimationNames(skeletonText: string, path: string): string[] {
  * 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);
+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');
-  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',
+  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 { name, bytes: readFileSync(path) };
+    return {
+      skeletonText,
+      atlasText,
+      pages,
+      animation: chosen ?? animations[0] ?? null,
+      animations,
+      label: skeletonPath,
+      version,
+      gate,
+    };
   });
-  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 html = buildPreview({
-    skeletonText,
-    atlasText,
-    pages,
-    animation: chosen ?? animations[0] ?? null,
-    animations,
-    label: skeletonPath,
-    version: readVersion(),
-  });
+  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(
-    `  ..    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`,
+    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)`);
 }
@@ -2181,8 +2404,8 @@ function cmdChainFit(flags: Record<string, string>): void {
 // 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
+// ⭐ `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.
@@ -3270,6 +3493,223 @@ function cmdIngest(flags: Record<string, string>, positional: string[]): void {
   }
 }
 
+// ---------------------------------------------------------------------------
+// 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
 // ---------------------------------------------------------------------------
@@ -3363,11 +3803,27 @@ const FLAG_MEANINGS: Record<string, string> = {
     '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 " +
@@ -3423,6 +3879,8 @@ const FLAG_VALUES: Record<string, string> = {
   'inward-lever': '<px>',
   animation: '<name>',
   skin: '<name>',
+  slot: '<name[,name…]>',
+  hide: '<name[,name…]>',
   max: '<px>',
   record: '<result.json>',
   ballot: '<ballot.html>',
@@ -3430,6 +3888,7 @@ const FLAG_VALUES: Record<string, string> = {
   name: '<n>',
   art: 'loose|none',
   stage: '<x,y,w,h>',
+  dir: '<path>',
 };
 
 interface CommandDoc {
@@ -3572,7 +4031,7 @@ const COMMANDS: CommandDoc[] = [
   {
     name: 'check',
     usage: ['rigc check --candidate <dir | skeleton.json> --frames <dir> [flags]'],
-    flags: ['candidate', 'frames', 'atlas', 'texture-from', 'fps', 'viewport', 'framing', 'as', 'skin', 'all-frames', 'json'],
+    flags: ['candidate', 'frames', 'atlas', 'texture-from', 'fps', 'viewport', 'framing', 'as', 'skin', 'all-frames', 'json', 'out'],
     overrides: {
       skin: {
         meaning:
@@ -3581,6 +4040,16 @@ const COMMANDS: CommandDoc[] = [
           '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',
@@ -3623,8 +4092,9 @@ const COMMANDS: CommandDoc[] = [
     name: 'render',
     usage: [
       'rigc render --candidate <dir | skeleton.json> [--animation <name>] [--skin <name>] [--fps 12] [--max 256] [--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', 'fps', 'max', 'out'],
+    flags: ['candidate', 'atlas', 'animation', 'skin', 'slot', 'hide', '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})` },
@@ -3632,9 +4102,22 @@ const COMMANDS: CommandDoc[] = [
   },
   {
     name: 'preview',
-    usage: ['rigc preview --candidate <dir | skeleton.json> [--animation <name>] [--out preview.html]'],
+    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"',
@@ -3723,6 +4206,21 @@ const COMMANDS: CommandDoc[] = [
       },
     },
   },
+  {
+    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);
@@ -3829,6 +4327,13 @@ const USAGE = [
   '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.',
@@ -3866,10 +4371,11 @@ try {
   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);
+  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}`);
@@ -3940,5 +4446,13 @@ try {
     console.error(`rigc: ${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;
 }