spine-rigc 0.25.4 → 0.25.6

package/README.md

@@ -146,15 +146,17 @@ because they are written from a clone of this repository (`bun install`, then ru
 the CLI in place); the two are interchangeable — `rigc build …` is
 `bun cli.ts build …`.
 
-Two commands are repository workflows rather than package ones: `bench` and
-`check` measure against Spine's official example projects — fetched, never
-committed — and against reference frames this project renders from them, which
-**are** committed, each example's own `license.txt` beside them under the
-redistribution grant those files carry; the images stay **non-commercial only**.
-The reasoning is in
+One command is a repository workflow rather than a package one: `bench` measures
+against Spine's official example projects — fetched, never committed — and against
+reference frames this project renders from them, which **are** committed, each
+example's own `license.txt` beside them under the redistribution grant those files
+carry; the images stay **non-commercial only**. The reasoning is in
 [`bench/reference/README.md`](https://github.com/firejune/rigc/blob/main/bench/reference/README.md)
-and the terms in [NOTICE.md](NOTICE.md). Both commands need a clone and `bun run
-fetch-examples`, and say so by name when the corpus is absent.
+and the terms in [NOTICE.md](NOTICE.md). It needs a clone and `bun run
+fetch-examples`, and says so by name when the corpus is absent. `check` is not one
+of them: it reads whatever frames you point it at, so it runs from the installed
+package on pictures of your own — which is what *Where to go next* below tells you
+to do with it, and it is the one instrument here that can see a wrong animation.
 
 ### Install it into your agent
 
@@ -405,6 +407,17 @@ that does not belong to it. See
   could. If you have reference pictures of the shot,
   `rigc check --candidate spine --frames <dir>` is the half of the loop that can
   see a wrong animation — AUTHORING.md §9.
+- 🧭 **No reference pictures, because the rig is your own?** Then make them:
+  `rigc render` the first build you are happy with and keep those frames. Every
+  later build is checked against them, and the first such check — the same build
+  against frames of itself — is the floor the rest are read against, because
+  `check` grades nothing and has no pass mark. It is the same instrument and the
+  same commands; what changes is that the reference is a build of yours you have
+  already looked at, so what it measures is **what your edit did**. Every drift
+  the report prints carries the bound its own match gives it on the line under
+  it, so a figure is read against that rather than against a number from a page;
+  AUTHORING.md §9.2 says what the two halves of that bound are and why the floor
+  is not zero.
 - [docs/LADDER.md](https://github.com/firejune/rigc/blob/main/docs/LADDER.md) is the benchmark: the same job, from a brief
   and rendered frames, scored. [docs/PILOT.md](https://github.com/firejune/rigc/blob/main/docs/PILOT.md) is how to run an
   agent through it and score what comes back.
@@ -511,19 +524,24 @@ commands take it and what its default is.
 | `pose --images <dir> --frame <png>` | reads part placements **out of** a picture |
 | `chainfit --candidate <dir> --images <dir> --frame <png>` | reads the parts `pose` refuses, through the candidate's own draw order and hierarchy: masked residuals over **visible** pixels, one hinge per child instead of four degrees of freedom, and the `rotate` key value each answer implies. A bone with two or more anchored descendants is **determined** rather than searched, and the residual that over-determination leaves is reported |
 | `diff <candidate.json> <reference.json>` | structural comparison of two skeletons, one ratio per measure and deliberately no combined score |
+| `bonedist --candidate … --reference … --bones …` | per-frame, per-bone world-transform distance against another skeleton — the ladder's stage 3, run on its own. `--bones <correspondence.json \| identity>` is required rather than defaulted: a candidate is entitled to its own bone names, so the pairing is stated |
 | `check --candidate <dir> --frames <dir>` | the candidate against reference pictures — the only instrument here that can see a *wrong animation* |
 | `bench <rung> --candidate <dir>` | one rung of the benchmark ladder |
 
-`diff`, `check` and `bench` measure against something you were given; the first two
-work on any frames you have, and `bench` is a repository workflow that needs a clone
-and `bun run fetch-examples`. The reasoning behind all three is in
+`diff`, `bonedist`, `check` and `bench` measure against something you were given; the
+first three work on any reference you have, and `bench` is a repository workflow that needs a clone
+and `bun run fetch-examples`. The reasoning behind them is in
 [the benchmark dossier](https://github.com/firejune/rigc/blob/main/docs/BENCHMARK.md).
 
 `build` and `validate` both default to `--profile spine` — the 28 validity rules, which
 ask *is this valid Spine 4.3 that any runtime plays correctly?* `--profile spine-html`
 adds all 43: the other 15 are one renderer's policy and one canvas budget's, and they
-fire on perfectly correct editor-produced Spine data, so reach for that profile when
-you are shipping into *that* project rather than to be thorough. A report always names
+fire on perfectly correct editor-produced Spine data, which is why they are opt-in.
+⇒ **That reason is about foreign data and does not carry to a rig you are authoring
+yourself: author under `--profile spine-html` and read the extra 15 as findings, and
+gate the release under `--profile spine`.** A `deform` key that folds a mesh inside
+out is written out under the default and refused by name under `spine-html`, which
+is the shape of what that split buys you. A report always names
 the profile it ran and lists what that profile left out.
 
 Several cuts can also be registered in a `cuts.json` and built by name
@@ -666,6 +684,7 @@ letting `A17` blame the editor for the harness's own doing.
 | 🎓 **[the benchmark dossier](https://github.com/firejune/rigc/blob/main/docs/BENCHMARK.md)** | **why you can trust the output.** The yardstick, `diff` and `check` and what neither can see, the eight-rung ladder and the spineboy graduation exam, the run viewer, the 43 named assertions with their profiles, and the selftest that has watched every one of them fire. Repository material — it is not in the npm package |
 | 📋 [LADDER.md](https://github.com/firejune/rigc/blob/main/docs/LADDER.md) · [GATE.md](https://github.com/firejune/rigc/blob/main/docs/GATE.md) · [PILOT.md](https://github.com/firejune/rigc/blob/main/docs/PILOT.md) | the live rung ledger, the clause statements a candidate is graded against, and how to run an agent through the ladder and score what comes back |
 | 🗺️ [ROADMAP.md](https://github.com/firejune/rigc/blob/main/ROADMAP.md) | where this is going, and where it has been. What 1.0 has to mean before the number is claimed — conditions rather than a feature list, because direction here comes from what users hit |
+| 📐 [CLAUDE.md](https://github.com/firejune/rigc/blob/main/CLAUDE.md) | **the doctrine** — why the validator's messages are the product, why nothing reaches disk before green, why no number is ever invented, and what a change has to keep. [CONTRIBUTING.md](https://github.com/firejune/rigc/blob/main/CONTRIBUTING.md) calls it worth ten minutes before a first patch. Repository material |
 
 ## Why you can trust the output
 

package/cli.ts

@@ -57,7 +57,7 @@ import {
   type BoneDistReport,
 } from './src/bonedist.ts';
 import { checkAgainstFrames, checkLines, CheckError, type CheckOptions, type CheckReport } from './src/check.ts';
-import { compile, CompileError, relativeImagesPath, type CompileOptions } from './src/compile.ts';
+import { compile, CompileError, droppedStateReason, relativeImagesPath, type CompileOptions } from './src/compile.ts';
 import {
   skeletonDataFromText,
   surveyDeformKeys,
@@ -67,9 +67,9 @@ import {
   type DeformSpan,
 } from './src/deformmeasure.ts';
 import { diffLines, diffSkeletons, reportedFigures, sectionFigures, type DiffReport } from './src/diff.ts';
-import { ingest, IngestError, type IngestFindingKind, type IngestStage } from './src/ingest.ts';
-import { copyAtlasImages } from './src/emit.ts';
-import { DEFAULT_PADDING, DEFAULT_PAGE_SIZE, packAtlas } from './src/atlas.ts';
+import { ingest, IngestError, INGEST_GUTTERS, type IngestStage } from './src/ingest.ts';
+import { copyAtlasPages } from './src/emit.ts';
+import { DEFAULT_PADDING, DEFAULT_PAGE_SIZE, packAtlas, parseAtlasText } from './src/atlas.ts';
 import { parseJsonWithPosition } from './src/json-position.ts';
 import { KEY_TIME_EPSILON } from './src/timelines.ts';
 import { findRung, RUNG_IDS, type RungSkeleton } from './src/ladder.ts';
@@ -117,6 +117,7 @@ import {
 } from './src/render.ts';
 import {
   assertionCountForProfile,
+  attachmentRegionJoins,
   CLI_DEFAULT_PROFILE,
   reportLines,
   validate,
@@ -125,7 +126,7 @@ import {
 } from './src/validate.ts';
 import { parseMotionSpec } from './src/motion.ts';
 import { depthStepLevels, type FoldLimit, type TurnCeiling } from './src/depth.ts';
-import type { CompileResult } from './src/types.ts';
+import type { CompileResult, DroppedState } from './src/types.ts';
 
 /**
  * One entry of a cuts.json, every path relative to the cuts.json file.
@@ -148,6 +149,14 @@ export type CutTable = Record<string, CutEntry>;
 
 class UsageError extends Error {}
 
+/**
+ * `explain` refusing a pair it cannot pose — a usage error in kind, printed
+ * without the usage block for `PoseError`'s and `IngestError`'s reason: the
+ * message names an attachment, a region and two flags, and reprinting every
+ * command's usage under it buries the one line that says what to change.
+ */
+class ExplainError extends Error {}
+
 // ---------------------------------------------------------------------------
 // package metadata — the installed version and repository, for `--version`
 // and for naming a remedy `bench` can only give from a repo checkout.
@@ -1133,6 +1142,19 @@ function readIntFlag(flags: Record<string, string>, name: string, fallback: numb
   return Number(raw);
 }
 
+/**
+ * One `DROP` line, written once because two outcomes print it.
+ *
+ * A build that succeeds prints it in its report; a build that REFUSES prints it
+ * under the refusal (issue #671), and the two have to be the same line or the
+ * failing run would be quoting a different fact from the one the green run
+ * shows. What it names — a file or a region — is `droppedStateReason`'s, in the
+ * compiler, beside the code that decided which of the two was consulted.
+ */
+function dropLine(dropped: DroppedState): string {
+  return `  DROP  ${dropped.slot}/${dropped.state}: ${droppedStateReason(dropped)} (state not emitted)`;
+}
+
 function cmdBuild(flags: Record<string, string>): void {
   const { label, opts } = resolveCut(flags);
   const profile = readProfile(flags);
@@ -1195,9 +1217,7 @@ function cmdBuild(flags: Record<string, string>): void {
             : ` scale ${img.atlasScale} (${img.atlas.originalWidth}x${img.atlas.originalHeight} texels)`);
     console.log(`  ..      ${img.region.padEnd(24)} ${img.width}x${img.height}  <- ${where}`);
   }
-  for (const d of result.droppedStates) {
-    console.log(`  DROP  ${d.slot}/${d.state}: ${d.why ?? `no PNG at ${d.path}`} (state not emitted)`);
-  }
+  for (const d of result.droppedStates) console.log(dropLine(d));
   // "The optional slots are optional" is a claim about this code path, so this
   // code path says which ones it left out rather than being silently right.
   for (const a of result.absentParts) {
@@ -1231,14 +1251,21 @@ function cmdBuild(flags: Record<string, string>): void {
   // correct for a build sitting beside the project it came from and breaks the
   // moment the directory is zipped, committed or moved on its own (issue #217).
   // Opt-in only: the default stays exactly what it has always been.
+  //
+  // What is copied is what the ATLAS names, not what the image list holds: under
+  // `--atlas-in` the two are different lists, and rebuilding the text from the
+  // second wrote a file the pack never contained — zero bytes for a rig that
+  // declares no parts, one fabricated page per part for a rig that does, both of
+  // them green here because the gate above had already read the compile's own
+  // text (issue #693, `src/emit.ts`).
   let atlasText = result.atlasText;
   if (flags['copy-images'] !== undefined) {
-    const copied = copyAtlasImages(result.images, opts.outDir);
+    const copied = copyAtlasPages(atlasText, 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}`);
+      const note = p.to === basename(p.from) ? '' : '  (renamed — basename collision)';
+      console.log(`  ..      ${p.to.padEnd(24)} <- ${p.from}  (${p.regions} region(s))${note}`);
     }
   }
 
@@ -2423,6 +2450,81 @@ function cmdBoneDist(flags: Record<string, string>): void {
   if (flags.json !== undefined) writeJson(flags.json, report);
 }
 
+/**
+ * Refuse a compiled pair whose art `explain` cannot pose through, by name.
+ *
+ * 🚨 `explain` poses the rig — `deformReportLines` loads the emitted pair through
+ * `spine-core` to measure what each deform key did — and a pose resolves EVERY
+ * attachment against the atlas, whether or not anything deforms it. On the specs
+ * `ingest --art none` writes there is nothing to resolve against: the entries
+ * state a size and name no `image`, so the compile atlases nothing, and the load
+ * threw the runtime's own `Region not found in atlas: rear-upper-arm (attachment:
+ * rear-upper-arm)` with a spine-core stack trace under it and exit 1 (measured on
+ * `examples/spineboy/export/spineboy-ess.json`, issue #697). That is the tool
+ * telling an agent about its own internals instead of about the rig, on the one
+ * input `docs/INGEST.md` §2.0 documents as the route through a foreign skeleton.
+ *
+ * ⭐ Both halves of the join are rigc's own readers rather than a second opinion
+ * on somebody else's format: the walk is `attachmentRegionJoins`, which `PS127`
+ * measures against the loader's own `findRegion` calls, and the region names come
+ * from `parseAtlasText`, which is what `--atlas-in` already resolves against.
+ * Names are compared EXACTLY — as `A08` compares them and as `findRegion`
+ * matches them — so a padded region name is a miss on both sides.
+ *
+ * ⚠️ What it deliberately does not do is catch the pose. A blanket `try` around
+ * `skeletonDataFromText` would convert any exception the runtime raises into a
+ * sentence claiming the cause is missing art, and a rigc defect reported under
+ * somebody else's name is the doctrine's second bullet inverted. This refuses
+ * the case it can NAME, before a line of the report is printed, and leaves
+ * anything else to arrive as itself.
+ */
+function refuseUnposableArt(result: CompileResult, opts: CompileOptions): void {
+  const regionNames = parseAtlasText(result.atlasText).pages.flatMap((page) => page.regions.map((region) => region.name));
+  const have = new Set(regionNames);
+  const misses: Array<{ at: string; attachment: string; lookup: string }> = [];
+  let lookups = 0;
+  for (const join of attachmentRegionJoins(JSON.parse(result.skeletonText))) {
+    // A `sequence` this walk will not guess at names no region it can check, and
+    // `A08` passes over it for the same reason.
+    if (join.lookups === null) continue;
+    for (const lookup of join.lookups) {
+      lookups++;
+      if (!have.has(lookup)) {
+        misses.push({
+          at: `skin "${join.skin}" slot "${join.slot}" placeholder "${join.placeholder}"`,
+          attachment: join.name,
+          lookup,
+        });
+      }
+    }
+  }
+  if (misses.length === 0) return;
+  const first = misses[0];
+  // Reported because it was measured, and absent where there is none — `A08`'s
+  // own near-miss clause, in `A08`'s own words.
+  const near = regionNames.find((region) => region.trim().toLowerCase() === first.lookup.toLowerCase());
+  const has =
+    regionNames.length === 0
+      ? 'it declares no region at all'
+      : `it declares ${regionNames.length} region(s) and none of them is that${
+          near === undefined ? '' : `, though it does have ${JSON.stringify(near)}`
+        }`;
+  const remedy =
+    opts.atlasInPath === undefined
+      ? 'Art reaches a compile two ways and this run took neither: `--atlas-in <pack.atlas>` resolves the parts ' +
+        'against a pack somebody already made, and an "image" per attachment resolves them as loose PNGs under ' +
+        '`--images <dir>` — a spec that states a size and names no image is what `ingest --art none` writes, and ' +
+        '`--atlas-in` is what reads it'
+      : `Either the spec's region name or ${opts.atlasInPath} is the one that moved: fix the name, or point ` +
+        '`--atlas-in` at the pack that has it';
+  throw new ExplainError(
+    `${first.at}: attachment ${JSON.stringify(first.attachment)} wants region ${JSON.stringify(first.lookup)}, ` +
+      `which this build's atlas does not have (${has}). \`explain\` poses the rig to measure its deform keys and a ` +
+      `pose resolves every attachment against the atlas, so there is nothing to pose it against. ${remedy}. ` +
+      `${misses.length} of ${lookups} attachment lookup(s) here resolve to no region.`,
+  );
+}
+
 function cmdExplain(flags: Record<string, string>): void {
   const { label, opts } = resolveCut(flags);
   console.log(`rigc explain ${label}`);
@@ -2431,6 +2533,13 @@ function cmdExplain(flags: Record<string, string>): void {
   console.log(`  ..    rig    ${opts.rigPath}`);
   console.log(`  ..    motion ${opts.motionPath}`);
   const result = compile(opts);
+  // Before a line of the report, rather than at the pose two hundred lines in:
+  // the blocks that need the art — DEFORM, meshes, dropped states — all sit
+  // BELOW the pose, so a run that printed the bone and timeline dump and then
+  // refused would be a report missing everything the missing art decides, with
+  // the sentence saying so scrolled off the top. It is the invocation that has
+  // to change, so it is refused before the report it cannot finish (issue #697).
+  refuseUnposableArt(result, opts);
   // `compile` has already parsed this file, so the read below cannot fail — but
   // it goes through the same parser rather than a cast, because the cast was the
   // last one in the repository and issue #307 was about exactly that.
@@ -2720,8 +2829,12 @@ function cmdExplain(flags: Record<string, string>): void {
   }
 
   if (result.droppedStates.length) {
-    console.log('\ndropped states (listed in the manifest, no PNG on disk)');
-    for (const d of result.droppedStates) console.log(`  ${d.slot}/${d.state}  ${d.path}`);
+    // The heading said "no PNG on disk" and the line printed the path, on a
+    // command that takes `--atlas-in` like `build` does — so an explain of a
+    // pack build named a file it never opened. Same renderer as the other two
+    // printers now, for the same reason they share one (issue #671).
+    console.log('\ndropped states (listed in the manifest, no art behind them)');
+    for (const d of result.droppedStates) console.log(`  ${d.slot}/${d.state}  ${droppedStateReason(d)}`);
   }
 
   console.log('\nmix table (player config, not skeleton JSON)');
@@ -2829,10 +2942,13 @@ function cmdIngest(flags: Record<string, string>, positional: string[]): void {
   // Grouped by kind rather than printed in discovery order: a blocker is what
   // decides the exit code, and a reader scanning for one should not have to
   // read past a hundred DURATION lines to find it.
-  const GUTTER: Record<IngestFindingKind, string> = { blocker: 'BLOCK', judgement: 'JUDGE', lossy: 'LOSS ' };
+  // The gutter words are `INGEST_GUTTERS`, which is also the column
+  // `docs/INGEST.md` §2.0's finding-code table is keyed on (issue #675); the
+  // pad to one width is this printer's, so the codes line up.
+  const width = Math.max(...Object.values(INGEST_GUTTERS).map((gutter) => gutter.length));
   for (const kind of ['blocker', 'judgement', 'lossy'] as const) {
     for (const finding of result.findings.filter((f) => f.kind === kind)) {
-      console.log(`  ${GUTTER[kind]} ${finding.code}: ${finding.where} — ${finding.detail}`);
+      console.log(`  ${INGEST_GUTTERS[kind].padEnd(width)} ${finding.code}: ${finding.where} — ${finding.detail}`);
     }
   }
   console.log(`rigc: wrote ${join(outDir, 'rig.json')}`);
@@ -3049,6 +3165,18 @@ interface CommandDoc {
    * nine, and nothing had ever compared the two.
    */
   overrides?: Record<string, { value?: string; meaning?: string }>;
+  /**
+   * Lines printed under the flag table: what this command's own figures mean.
+   *
+   * ⚠️ Not a second place to describe a flag. It exists for what is true of the
+   * **command** and of no flag it takes — and the case that earned it is issue
+   * #678: `pose` and `chainfit` each say *"it is a reporting threshold, not a
+   * pass bar"* on the flag that carries their threshold, and `check` has no such
+   * flag, so its page said nothing at all about whether any of its figures is a
+   * bar to beat. An agent reading `slot drift worst 3.7 px` off a correct rig had
+   * no page to consult and no exit code to read it in.
+   */
+  notes?: string[];
 }
 
 const COMMANDS: CommandDoc[] = [
@@ -3078,8 +3206,20 @@ const COMMANDS: CommandDoc[] = [
   },
   {
     name: 'explain',
-    usage: ['rigc explain  (same arguments as build, minus --profile — it never gates)'],
-    flags: ['rig', 'motion', 'out', 'manifest', 'images', 'cut', 'cuts'],
+    usage: [
+      'rigc explain --rig <path> --motion <path> --out <dir> [--manifest <path>] [--images <dir>]   (it never gates, and writes nothing)',
+      'rigc explain … --atlas-in <skeleton.atlas>                  (resolve the parts against a pack somebody already made, as build does)',
+      'rigc explain --cut <name> --cuts <cuts.json>',
+    ],
+    flags: ['rig', 'motion', 'out', 'manifest', 'images', 'atlas-in', 'cut', 'cuts'],
+    notes: [
+      'this line said "the same arguments as build, minus --profile" and was false in both',
+      'directions (issue #697): --atlas-in was not listed here, so the one flag that lets this',
+      'command read what `ingest --art none` writes was reachable and undocumented, while',
+      '--pack, --page-size, --padding and --copy-images are build\'s and do nothing here —',
+      'they decide what is WRITTEN, and this command writes nothing. What it takes is listed',
+      'above, and that is now the whole of it.',
+    ],
   },
   {
     name: 'validate',
@@ -3126,6 +3266,19 @@ const COMMANDS: CommandDoc[] = [
           'REFUSED by name, and one that records none says so in the report rather than pretending to agree',
       },
     },
+    notes: [
+      'every figure here is a reporting threshold, not a pass bar. Nothing in this report',
+      'grades, no number has to beat anything, and the exit code says only whether the',
+      'comparison could be MADE: 0 when it ran — including the build with every easing',
+      'reversed, which is the defect this command exists for — 1 when it could not (frames',
+      'that are not there, a skin the frames do not record, a candidate that will not load),',
+      '2 on the flags.',
+      '',
+      'So read a figure against a floor you measured yourself: render the first green build',
+      'and keep its frames, then check every later build against them. The identity run of',
+      'that pair is the floor, and it is not zero — docs/AUTHORING.md §9.2 states it, what',
+      'it comes from, and which column separates a wrong curve from a moved key.',
+    ],
   },
   {
     name: 'bench',
@@ -3267,9 +3420,14 @@ function commandHelp(name: string): string {
   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',
-  );
+  return [
+    'usage:',
+    ...doc.usage.map((u) => `  ${u}`),
+    '',
+    'flags:',
+    ...keys.map((key, i) => `  ${labels[i].padEnd(width)}${meaning(key)}`),
+    ...(doc.notes === undefined ? [] : ['', ...doc.notes]),
+  ].join('\n');
 }
 
 const USAGE = [
@@ -3410,6 +3568,13 @@ try {
   }
   if (err instanceof CompileError) {
     console.error(`rigc compile error: ${err.message}`);
+    // The drops the compile recorded before it stopped, in the same line the
+    // green build prints (issue #671). They were reported from the compile
+    // RESULT alone, so the run that failed BECAUSE a file was missing was the
+    // one run that never named the file. On stderr with the refusal rather than
+    // on stdout, so redirecting one stream does not separate a fact from the
+    // sentence it explains.
+    for (const dropped of err.droppedStates ?? []) console.error(dropLine(dropped));
     process.exit(1);
   }
   if (err instanceof CheckError) {
@@ -3427,6 +3592,13 @@ try {
     console.error(`rigc pose: ${err.message}`);
     process.exit(2);
   }
+  // A refusal of the invocation, like the two below it, and exit 2 for the same
+  // reason: nothing was posed and nothing was written, so it is the command line
+  // that has to change (issue #697).
+  if (err instanceof ExplainError) {
+    console.error(`rigc explain: ${err.message}`);
+    process.exit(2);
+  }
   // Same kind as a PoseError, and printed the same way for the same reason: the
   // messages name a path, a bone or an attachment, and reprinting the whole
   // usage under them buries the one line that says what to change.