@rig-c/parts 1.14.0 → 1.16.0

package/docs/MIGRATION.md

@@ -148,3 +148,65 @@ nothing else.
 What to do: install with `npm i -D @rig-c/parts` (or `npm install -g @rig-c/parts`);
 command lines do not change. A dependant that names `rig-parts` keeps receiving
 every release under it (#222).
+
+## After 1.14.0: the idle is read for folds
+
+| | 1.14.0 | after 1.14.0 |
+| --- | --- | --- |
+| `check.json`'s `ANIMATIONS_DO_NOT_FOLD` | written only when `motion.json` holds an animation beside the idle; its `animations` lists those | written whenever `motion.json` holds an animation, a rig of the idle alone included; its `animations` lists every one read, the idle first (#333) |
+| the console's fold line | `N animation(s) beside the idle read by rigc render --folds …` | `N animation(s) read by rigc render --folds …`, the idle counted and named |
+| the summary of a rig with an idle and no other animation | `… of 9 bar(s) measured …` | `… of 10 bar(s) measured …` |
+| `may_fold` naming `"animation": "idle"` | refused, `REQUIREMENTS_MAY_FOLD` (the bar did not read the idle) | accepted like any animation name; a fold it names is listed with its why and not held, and one that does not fold fails the bar |
+
+The reading is the one #320 made for the other animations — one `rigc render --folds` at
+12 fps over the build with its physics constraints left out — and now takes the idle in
+the same run. A rig whose idle turns a mesh triangle over against the setup pose, which
+`check` passed before, fails it, naming the idle and quoting rigc's line. On the four
+public examples and the trailer no idle folds [measured for #333, rig-c 2.47.1], so no
+verdict moved; every example's `expected/check.json` moved by the key and nothing else.
+`reference-demo`, an idle alone, gains the whole key after `TEXTURE_STRETCH`:
+
+```diff
+@@ -259,6 +259,18 @@
+     "severity": 1.074
+    }
+   ]
++ },
++ "ANIMATIONS_DO_NOT_FOLD": {
++  "status": "PASS",
++  "animations": [
++   "idle"
++  ],
++  "fps": 12,
++  "physics_left_out": 0,
++  "folding": [],
++  "folding_undeclared": 0,
++  "declared_not_folding": [],
++  "bar": 0
+  },
+  "RECOMPOSITE_HOLES": {
+```
+
+and `demo`, `scarf` and `reference-sample` gain `"idle"` as the first entry of its
+`animations`.
+
+What to do: nothing for a rig whose idle does not fold. A consumer that reads
+`check.json` finds the key on every rig with an animation. An idle that folds on purpose
+is declared, `"may_fold": [{ "slot": …, "animation": "idle", "why": … }]`, in the
+`--requirements` file.
+
+## After 1.14.0: faint islands under `contour.bridges`
+
+`contour.bridges` shipped in 1.14.0 meshing every island past `stray` and bridging it.
+The patch after it reads islands in a fixed order (issue #326, HQ's ruling): dust first
+(`stray`), then **faint** islands — every pixel's alpha under 64 — left out and named,
+then every visible island bridged whatever its bridge costs. No field was added and
+no declared form changed.
+
+| change | what moved | measured |
+| --- | --- | --- |
+| #326, faint islands left out | only a part that declares `contour.bridges` and holds a faint island (not the largest): its mesh, its `mesh_report.json` row (`contour.bridges.faint`, and `art_coverage`, which counts those pixels as art not covered) and, from `mesh-draft`, its written entry's note and `mesh_draft.json`'s `candidate.bridges.faint`. A part without a faint island writes the bytes 1.14.0 wrote | demo `earring` (the only such part a `mesh-draft` of the public examples drafts): its 8, 2 and 1 px specks, brightest alpha 17, 17 and 11, are left out — 33 → 26 triangles, overdraw 4.82 → 1.94; the idle rendered at scale 1.01 differs from the build of #335 (the change 1.14.0 carries) by at most 9 of 255 levels on at most 38 px where the specks were (4 frames; elsewhere 158 px differ by 1 level, as they do with the earring slot hidden), and `check`'s seam bar reads 0 px over 40 on both |
+
+What to do: nothing for a config without `contour.bridges`. A part that declares it and
+holds a faint island no longer draws that island; if those pixels matter, keep the
+lattice for that part.

package/docs/STABILITY.md

@@ -35,8 +35,9 @@ Exit codes are part of the interface: **0** the command did what it says, **1**
 refused its input (every reason a `FAIL` line), **2** a usage error or a command
 this version does not implement. No command is unimplemented at 1.0.0 (`LATER`
 in `cli.ts` is empty). A refusal line has the shape
-`  FAIL  <RULE>: <object> — <value found>; <value required>`: the rule name is a
-stable identifier, and the detail after it is prose that may be reworded. A command
+`  FAIL  <RULE>: <object> — <value found>; <value required> (see rig-parts guide <RULE>)`:
+the rule name is a stable identifier, the pointer at the end is fixed text, and the
+detail between them is prose that may be reworded. A command
 also answers to the alias `spine-parts` as long as the install keeps it
 ([MIGRATION.md](MIGRATION.md)). `-h`, `help` and `-v` are the short forms of
 `--help` and `--version`. The flags' meanings are `rig-parts --help`'s; their
@@ -60,6 +61,7 @@ defaults are the help's too, and none is guessed from the art.
 | `build` | `--config`, `--source`, `--full`, `--head`, `--out`; optional `--seam`, `--project`, `--page-edges`, `--pack-shape`, `--loop`, `--lead-in`, `--requirements`, `--idle-keys`, `--seam-pairs`, `--keep-stills` |
 | `compose` | `--scene`, `--out`; optional `--requirements`, `--accept` |
 | `mesh-draft` | `--config`, `--parts`, `--out`; optional `--requirements`, `--idle-keys` (ctl, direct), `--page-edges` (pot, free), `--pack-shape` (rect, polygon), `--more-triangles` |
+| `guide` | one positional argument: a rule name, `§<n>`, `§<n>.<m>` or `§<n>.<m>.<k>` |
 | (none) | `--version`, `--help` |
 <!-- /stable:commands -->
 
@@ -171,11 +173,11 @@ every number) are AUTHORING §3's tables, and the loader refuses any other by na
 | --- | --- | --- |
 | `parts.json`, `parts/<name>.png` | `assemble`, `build` | one record per part: `from` (`<run>:<tag>` with a See-through v3 tag, `<run>:author:<label>` for a layer the author made — issue #256, read by no role rule — or `painting:<name>` for a patch), `cut_from` on a cut's piece only (the plan part it was cut from, issue #230), the box `x`, `y`, `w`, `h` (rig px), the pixel counts `src/parts.ts` documents (`opaque_px`, `visible_px`, `occluded_px`, `projected_core_px`, `source_px_taken`, `visible_not_projected_px`, `refused_drift_px`, `merged_px`, `seam_override_px`, and `fringe_pushed_back` when not empty); `rig_size`, `scale_rig_per_source`, `ghost_px`, `recomposite`, and `scene` (`figure_alpha_above`, `figure_px`, `figure_mask`) under `config.scene` only, with the figure's mask `figure_rig.png` beside the recomposite (issue #242) |
 | `rig/rig.json`, `rig/motion.json`, `rig/images/` | `rig`, `build`, `compose` | rig-c's rig spec and motion spec, `spec` `rigc-rig/1` and `rigc-motion/1`: the format is rig-c's, and this package writes only what rig-c's parser accepts |
-| `rig/mesh_report.json` | `rig`, `build` | one row per mesh: `part`, `vertices`, `triangles`, `hull`, `bones`, `max_influences`, `mean_influences`, `art_coverage`, then `grid` (a lattice); `mode` "contour" with `params`, `contour`, `regions` (`params.maxEdge` and `contour.outlineCut` only when the mesh declares `contour.maxEdge`; `params.bridges` and `contour.bridges` — `islands`, `units`, `joins` — only when it declares `contour.bridges`); or `mode` "auto" with `settings`, `source`, `result`, `residuals`, `worst_residual`, `worst_region`, `motion_amplitude`, `termination`, `weights`, `regions`, `deformation`, `quality_report` (rig-c's `mesh-quality-report/1` document whole), `motion_report`, and, only when they apply, `stray_cleared` (after `source`, when `source.stray` is declared), `skinning_residual` and `replay` (`AutoMeshReport` in `src/rig.ts`); in every mode, `exponent` when the mesh declares one (after `grid`, or after `mode`); `influences`, as declared, when a lattice or contour mesh declares it (after `exponent`, or where `exponent` would be); `stray` and `stray_cleared` when a lattice mesh declares `stray` (after `influences`, or where `influences` would be); `ribs` when a contour or auto mesh declares them (after `exponent`, or after `mode`), and then `contour.ribs` (`source.contour.ribs` in the automatic mode) |
-| `check/check.json` and the rest of `check/` | `check`, `build`, `compose` | the reference's fields in its order (`gate_spine_html_green`, `rigc_entry`, `pack_mode`, `loop_max_diff`, the seam figures — `seam_mean`, `seam_px_over_40`, `seam_px_over_80` and, from issue #216, `seam_frame_scale`, the frame scale the bar divides the count by), `loop_physics` after `loop_max_diff` when the rig declares a physics constraint, `seam_border` after the seam figures when `parts.json` declares a scene (issue #242), `seam_pairs` after the seam figures when the seam bar fails or `--seam-pairs` asks (each row's picture under `check/seam/`; `--keep-stills` leaves the setup-pose still and its `frames.json` under `check/setup_still/`), then the judgement lines (`BREATH_VISIBLE`, `BLINK_NO_HOLE`, `CHAIN_LAG`, `TIP_OVER_ROOT`, `STILL_REGIONS_DARK`, `TEXTURE_STRETCH`), `ANIMATIONS_DO_NOT_FOLD` after them when `motion.json` holds an animation beside the idle (issue #320: `status`, `animations`, `fps`, `physics_left_out`, `folding`, `folding_undeclared`, `declared_not_folding`, `bar`), `RECOMPOSITE_HOLES` (its first figure `declared_scene` when `parts.json` declares a scene), `SETUP_POSE_VS_SOURCE`, `skipped`, a `requirements` block under `--requirements`, and `PASS`; `check/build/skeleton.json`, `.atlas` and `.png` are the packed artifact rig-c writes |
+| `rig/mesh_report.json` | `rig`, `build` | one row per mesh: `part`, `vertices`, `triangles`, `hull`, `bones`, `max_influences`, `mean_influences`, `art_coverage`, then `grid` (a lattice); `mode` "contour" with `params`, `contour`, `regions` (`params.maxEdge` and `contour.outlineCut` only when the mesh declares `contour.maxEdge`; `params.bridges` and `contour.bridges` — `islands`, `units`, `joins`, and `faint` only when an island was left out as faint — only when it declares `contour.bridges`); or `mode` "auto" with `settings`, `source`, `result`, `residuals`, `worst_residual`, `worst_region`, `motion_amplitude`, `termination`, `weights`, `regions`, `deformation`, `quality_report` (rig-c's `mesh-quality-report/1` document whole), `motion_report`, and, only when they apply, `stray_cleared` (after `source`, when `source.stray` is declared), `skinning_residual` and `replay` (`AutoMeshReport` in `src/rig.ts`); in every mode, `exponent` when the mesh declares one (after `grid`, or after `mode`); `influences`, as declared, when a lattice or contour mesh declares it (after `exponent`, or where `exponent` would be); `stray` and `stray_cleared` when a lattice mesh declares `stray` (after `influences`, or where `influences` would be); `ribs` when a contour or auto mesh declares them (after `exponent`, or after `mode`), and then `contour.ribs` (`source.contour.ribs` in the automatic mode) |
+| `check/check.json` and the rest of `check/` | `check`, `build`, `compose` | the reference's fields in its order (`gate_spine_html_green`, `rigc_entry`, `pack_mode`, `loop_max_diff`, the seam figures — `seam_mean`, `seam_px_over_40`, `seam_px_over_80` and, from issue #216, `seam_frame_scale`, the frame scale the bar divides the count by), `loop_physics` after `loop_max_diff` when the rig declares a physics constraint, `seam_border` after the seam figures when `parts.json` declares a scene (issue #242), `seam_pairs` after the seam figures when the seam bar fails or `--seam-pairs` asks (each row's picture under `check/seam/`; `--keep-stills` leaves the setup-pose still and its `frames.json` under `check/setup_still/`), then the judgement lines (`BREATH_VISIBLE`, `BLINK_NO_HOLE`, `CHAIN_LAG`, `TIP_OVER_ROOT`, `STILL_REGIONS_DARK`, `TEXTURE_STRETCH`), `ANIMATIONS_DO_NOT_FOLD` after them when `motion.json` holds an animation, the idle included — on every rig with an idle since issue #333 (issue #320: `status`, `animations`, `fps`, `physics_left_out`, `folding`, `folding_undeclared`, `declared_not_folding`, `bar`), `RECOMPOSITE_HOLES` (its first figure `declared_scene` when `parts.json` declares a scene), `SETUP_POSE_VS_SOURCE`, `skipped`, a `requirements` block under `--requirements`, and `PASS`; `check/build/skeleton.json`, `.atlas` and `.png` are the packed artifact rig-c writes |
 | `proposal.json`, `render/landmarks*.png` | `propose` | the config's four rig sections, `turn` with `--full`/`--head`, and `notes` |
 | `basis.json` | `propose` | spec `spine-parts-basis/1` |
-| `config.json`, `mesh_draft.json` | `mesh-draft` | `config.json` is the config read, byte for byte, but for each drafted part's `meshes` entry; `mesh_draft.json` is spec `rig-parts-mesh-draft/1`: `rules`, `lattice_check`, `draft_check`, `figure_overdraw`, and per lattice part `part`, `mode`, `lattice`, `candidate` (with `bridges` — `units`, `joins` of `span` and `area_px2`, `area_px2`, `overdraw` — only when the candidate is a bridged one, issue #326), `delta` (under `--more-triangles` only), `readings`, `gate` (each line's `reading`, `pass`, `text`, `margin`), `note`; and `not_compared` (issue #307), only when the config holds an `auto` or `contour` entry: per such entry, in config order, `part`, `mode` and `note` — the part was neither drafted nor compared, and a config of lattices alone writes no such key |
+| `config.json`, `mesh_draft.json` | `mesh-draft` | `config.json` is the config read, byte for byte, but for each drafted part's `meshes` entry; `mesh_draft.json` is spec `rig-parts-mesh-draft/1`: `rules`, `lattice_check`, `draft_check`, `figure_overdraw`, and per lattice part `part`, `mode`, `lattice`, `candidate` (with `bridges` — `units`, `joins` of `span` and `area_px2`, `area_px2`, `overdraw`, and `faint` only when an island was left out as faint — only when the candidate is a bridged one, issue #326), `delta` (under `--more-triangles` only), `readings`, `gate` (each line's `reading`, `pass`, `text`, `margin`), `note`; and `not_compared` (issue #307), only when the config holds an `auto` or `contour` entry: per such entry, in config order, `part`, `mode` and `note` — the part was neither drafted nor compared, and a config of lattices alone writes no such key |
 | the scene report | `compose` | spec `spine-parts-scene-report/1` |
 | `idle.png`, `idle-indexed.png`, `idle.gif` | `loop`, `build --loop` | APNG and GIF encodings of the rendered idle |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rig-c/parts",
-  "version": "1.14.0",
+  "version": "1.16.0",
   "description": "AI-authored 2D character parts from one anime painting and its See-through layer decomposition: measured parts, weighted-mesh rig specs, verified through rig-c before anything is written. A CLI for agents that cannot see the image.",
   "type": "module",
   "bin": {

package/skills/rig-parts/SKILL.md

@@ -13,6 +13,13 @@ rig-c, which compiles, gates, packs and renders. You cannot see the painting,
 the layers or the rig. The printed lines, `docs/AUTHORING.md` and the files each
 stage writes are the whole interface.
 
+**A FAIL line ends with the command that prints its row of the guide:**
+`FAIL  RULE: object — detail (see rig-parts guide RULE)`. Run that command before
+anything else. It prints the one row of `docs/AUTHORING.md` that maps the rule to
+what has to change, read from the installed file. `rig-parts guide §<n>` prints a
+section, `§<n>.<m>` the m-th `###` under it and `§<n>.<m>.<k>` the k-th `####`
+under that.
+
 ## Non-negotiables
 
 - **rig-c's gate is never bypassed.** rig-parts writes no Spine data
@@ -26,7 +33,7 @@ stage writes are the whole interface.
   because the tool refused.
 - **The refusal is the instruction.** `FAIL  RULE: object — detail` names the object,
   the value found and the value required; AUTHORING §6 maps every rule to the field
-  or input that has to change.
+  or input that has to change, and `rig-parts guide RULE` prints that row.
 - **Green is not "looks right".** `check` measures the gates, the seam, the loop and
   six judgement lines (`BREATH_VISIBLE`, `BLINK_NO_HOLE`, `CHAIN_LAG`,
   `TIP_OVER_ROOT`, `STILL_REGIONS_DARK` — its face half in the head's own frame —

package/src/build.ts

@@ -70,9 +70,9 @@ import {
   splitSchedule,
   untestedIntervals,
 } from './autoreplay.ts';
-import { besideIdleLine, FOLD_LINE, type FoldsLine, buildGateLines, causeLines, IDLE_FPS, IDLE_MAX_PX, maxRgbDiff, REQUIREMENTS_DIR, type CheckReport, type PackLine, DEFAULT_PACK_SHAPE, DEFAULT_PAGE_EDGES, JUDGEMENT_LINES, type JudgementLine, packedBuildArgs, packedBuildLabel, type PackMode, type PackShape, type PageEdges, readFrameSet, rigcFailed, REPORTED_LINES, type ReportedLine, type RigcRunner, runCheck, SEAM_DIR, SEAM_MEAN_BAR, seamPairText, seamRigPxText, SOURCE_LINE, SEAM_PX_BAR, SEAM_PX_LEVEL, SEAM_PX_LEVEL_HIGH, SPINEBOY_YARDSTICK, STILL_DIR } from './check.ts';
+import { besideIdleLine, FOLD_LINE, type FoldsLine, buildGateLines, causeLines, IDLE_FPS, IDLE_MAX_PX, maxRgbDiff, REQUIREMENTS_DIR, type CheckReport, type PackLine, DEFAULT_PACK_SHAPE, DEFAULT_PAGE_EDGES, JUDGEMENT_LINES, type JudgementLine, packedBuildArgs, packedBuildLabel, type PackMode, type PackShape, type PageEdges, readFrameSet, rigcFailed, rigcIdentity, rigcRanClause, REPORTED_LINES, type ReportedLine, type RigcRunner, runCheck, SEAM_DIR, SEAM_MEAN_BAR, seamPairText, seamRigPxText, SOURCE_LINE, SEAM_PX_BAR, SEAM_PX_LEVEL, SEAM_PX_LEVEL_HIGH, SPINEBOY_YARDSTICK, STILL_DIR } from './check.ts';
 import { type Cut, loadConfig, loadConfigAndAnimations, loadEarlyConfig } from './config.ts';
-import { PartsError, type Problem, problemLine, refuseIfAny } from './errors.ts';
+import { failLine, PartsError, type Problem, refuseIfAny } from './errors.ts';
 import type { MeshQualityReport, MotionSchedule } from 'rig-c/mesh';
 import { encodeGif } from './gif.ts';
 import { CONTROL_SUFFIX, withAnimations } from './motion.ts';
@@ -277,6 +277,8 @@ export interface GateRun {
    * {@link causeLines} says name why.
    */
   lines: string[];
+  /** Which rigc ran it, when the runner said ({@link RigcCall.ran}; issue #337). */
+  ran?: string;
 }
 
 /**
@@ -295,7 +297,7 @@ function gateRun(label: string, rigc: RigcRunner, args: string[]): GateRun {
   const r = rigc(args);
   const lines = r.out.split('\n').filter((l) => /^ {2}FAIL {2}/.test(l) || /assertions: \d+ measured/.test(l) || /^rigc compile error/.test(l) || DECLARED_SKIP.test(l) || HERE_LINE.test(l));
   const failed = lines.some((l) => /^ {2}FAIL {2}/.test(l) || /^rigc compile error/.test(l));
-  return { label, status: r.status, lines: r.status !== 0 && !failed ? [...lines, ...causeLines(r.out)] : lines };
+  return { label, status: r.status, lines: r.status !== 0 && !failed ? [...lines, ...causeLines(r.out)] : lines, ...(r.ran === undefined ? {} : { ran: r.ran }) };
 }
 
 /**
@@ -490,7 +492,7 @@ export function motionGates(
             {
               code: 'AUTO_MESH_MOTION_INPUT',
               object: c.object,
-              detail: `the candidate with the declared stimulus (the rig as written, its motion carrying the stimulus animations) ${candidate.status !== 0 ? `is refused by rigc's gate, exit ${candidate.status}${candidate.lines.length > 0 ? `: ${candidate.lines.map((l) => l.trim()).join(' | ')}` : ''}` : `built green and wrote no ${RIGC_MODEL_DOCUMENT}`}; a candidate that is not gated is not evidence, and nothing is built in the part's place`,
+              detail: `the candidate with the declared stimulus (the rig as written, its motion carrying the stimulus animations) ${candidate.status !== 0 ? `is refused by rigc's gate, exit ${candidate.status}${candidate.lines.length > 0 ? `: ${candidate.lines.map((l) => l.trim()).join(' | ')}` : ''}${rigcRanClause(candidate)}` : `built green and wrote no ${RIGC_MODEL_DOCUMENT}`}; a candidate that is not gated is not evidence, and nothing is built in the part's place`,
             },
           ],
           notCompared: 'the stimulus candidate build is red',
@@ -520,7 +522,7 @@ export function motionGates(
           {
             code: 'AUTO_MESH_MOTION_INPUT',
             object: c.object,
-            detail: `the reference (the rig with "${c.part}" as its unreduced source mesh) ${gate.status !== 0 ? `is refused by rigc's gate, exit ${gate.status}${gate.lines.length > 0 ? `: ${gate.lines.map((l) => l.trim()).join(' | ')}` : ''}` : `built green and wrote no ${RIGC_MODEL_DOCUMENT}`}; a reference that is not gated is not evidence, and nothing is built in the part's place`,
+            detail: `the reference (the rig with "${c.part}" as its unreduced source mesh) ${gate.status !== 0 ? `is refused by rigc's gate, exit ${gate.status}${gate.lines.length > 0 ? `: ${gate.lines.map((l) => l.trim()).join(' | ')}` : ''}${rigcRanClause(gate)}` : `built green and wrote no ${RIGC_MODEL_DOCUMENT}`}; a reference that is not gated is not evidence, and nothing is built in the part's place`,
           },
         ],
         notCompared: 'the reference build is red',
@@ -642,7 +644,7 @@ export function replaySearch(
       fatal = {
         code: 'AUTO_MESH_MOTION_INPUT',
         object: c.object,
-        detail: `the replay to accepted step ${step} (the rig with "${c.part}" as that step's mesh) ${gate.status !== 0 ? `is refused by rigc's gate, exit ${gate.status}${gate.lines.length > 0 ? `: ${gate.lines.map((l) => l.trim()).join(' | ')}` : ''}` : `built green and wrote no ${RIGC_MODEL_DOCUMENT}`}; a candidate that is not gated is not evidence, and nothing is built in the part's place`,
+        detail: `the replay to accepted step ${step} (the rig with "${c.part}" as that step's mesh) ${gate.status !== 0 ? `is refused by rigc's gate, exit ${gate.status}${gate.lines.length > 0 ? `: ${gate.lines.map((l) => l.trim()).join(' | ')}` : ''}${rigcRanClause(gate)}` : `built green and wrote no ${RIGC_MODEL_DOCUMENT}`}; a candidate that is not gated is not evidence, and nothing is built in the part's place`,
       };
       return refused(`rigc exit ${gate.status}`);
     }
@@ -897,7 +899,7 @@ export function rigStage(input: RigStageInput, rigc: RigcRunner, scratch: string
     const problems: Problem[] = red.map((g) => ({
       code: 'RIG_RIGC_GREEN',
       object: `rigc ${g.label}`,
-      detail: `exited ${g.status}${g.lines.length > 0 ? `: ${g.lines.map((l) => l.trim()).join(' | ')}` : ', and it printed nothing'}; ${ctlRemedies(g.lines, rig.controls, input.command ?? 'rig').map((s) => `${s}; `).join('')}exit 0 is required before anything is written, and nothing was`,
+      detail: `exited ${g.status}${g.lines.length > 0 ? `: ${g.lines.map((l) => l.trim()).join(' | ')}` : ', and it printed nothing'}${rigcRanClause(g)}; ${ctlRemedies(g.lines, rig.controls, input.command ?? 'rig').map((s) => `${s}; `).join('')}exit 0 is required before anything is written, and nothing was`,
     }));
     throw new PartsError(problems);
   }
@@ -1031,14 +1033,14 @@ export function judgementLine(name: string, line: JudgementLine | ReportedLine):
 }
 
 /**
- * The fold line (issue #320) as the console prints it: the status, what was
+ * The fold line (issues #320, #333) as the console prints it: the status, what was
  * read and at what rate, and then each folding mesh on a line of its own,
  * rigc's own words, with the declaration's why where `may_fold` takes it.
  */
 export function foldsLines(line: FoldsLine): string[] {
   const physics = line.physics_left_out === 0 ? '' : `, its ${line.physics_left_out} physics constraint(s) left out`;
   const head =
-    `${FOLD_LINE}: ${line.status} — ${line.animations.length} animation(s) beside the idle read by rigc render --folds at ${line.fps} fps${physics} (${line.animations.join(', ')}): ` +
+    `${FOLD_LINE}: ${line.status} — ${line.animations.length} animation(s) read by rigc render --folds at ${line.fps} fps${physics} (${line.animations.join(', ')}): ` +
     `${line.folding.length} folding mesh(es), ${line.folding_undeclared} not declared in may_fold (<= ${line.bar})` +
     (line.declared_not_folding.length === 0 ? '' : `; may_fold declares ${line.declared_not_folding.map((d) => `slot "${d.slot}" in "${d.animation}"`).join(', ')}, which do(es) not fold`);
   return [head, ...line.folding.map((r) => `  folds  ${r.line}${r.declared === null ? '' : ` — declared in may_fold: ${r.declared}`}`)];
@@ -1060,7 +1062,7 @@ export function checkStage(input: CheckStageInput, rigc: RigcRunner, bin: string
   log(`rig-parts check: ${input.rig} -> ${input.out}`);
   const versionLines = v.out.trim().split('\n');
   const entryLine = versionLines.find((l) => l.startsWith('entry:'));
-  log(`  rigc ${versionLines[0]} at ${bin}${entryLine === undefined ? '' : `; ${entryLine}`}`);
+  log(`  ${rigcIdentity(bin, v)}${entryLine === undefined ? '' : `; ${entryLine}`}`);
   const mode: PackMode = { pageEdges: input.pageEdges ?? DEFAULT_PAGE_EDGES, packShape: input.packShape ?? DEFAULT_PACK_SHAPE };
   const r = runCheck(input.rig, input.out, rigc, input.parts, mode, input.source, input.requirements, input.seamPairs === true, input.keepStills === true);
   log(`  gate spine-html (rigc ${packedBuildLabel(mode)}), verbatim:`);
@@ -1093,7 +1095,7 @@ export function checkStage(input: CheckStageInput, rigc: RigcRunner, bin: string
   }
   log(`  gate: spine-html ${fig.gate_spine_html_green ? 'green' : 'RED'} (${fig.rigc_entry.entry}${fig.rigc_entry.spine_core === null ? ', rigc\'s own validator' : `, the spine-core ${fig.rigc_entry.spine_core} round trip`})`);
   log(`  wrote ${r.written.map((w) => join(input.out, w)).join(', ')}, ${join(input.out, 'build')}/${r.idle === null ? '' : `, ${join(input.out, 'idle_frames')}/`}${r.requirements === null ? '' : `, ${join(input.out, REQUIREMENTS_DIR)}/`}${fig.seam_pairs === undefined ? '' : `, ${join(input.out, SEAM_DIR)}/`}${existsSync(join(input.out, STILL_DIR)) ? `, ${join(input.out, STILL_DIR)}/` : ''}`);
-  for (const p of r.problems) log(`  FAIL  ${problemLine(p)}`);
+  for (const p of r.problems) log(failLine(p));
   const reqNotPass = r.requirements === null ? 0 : r.requirements.summary.declared - r.requirements.summary.pass;
   const notMet = r.requirements === null ? `${r.problems.length} bar(s) not met` : `${r.problems.length - reqNotPass} bar(s) not met, ${reqNotPass} declared requirement(s) not PASS`;
   log(`${fig.PASS ? 'check: PASS' : `check: FAIL — ${notMet}`}; ${barsSummary(r)}`);
@@ -1464,7 +1466,7 @@ export function build(input: BuildInput, run: BuildRunners, log: Log): BuildResu
   const refused = (stage: BuildStage, err: unknown, check: CheckReport | null = null): BuildResult => {
     if (!(err instanceof PartsError)) throw err;
     const say = prefixed(stage);
-    for (const p of err.problems) say(`  FAIL  ${problemLine(p)}`);
+    for (const p of err.problems) say(failLine(p));
     say(`refused: ${err.problems.length} problem(s)`);
     log(`build: stopped at ${stage}; no later stage ran`);
     return { stoppedAt: stage, check, artifact: [] };

package/src/check.ts

@@ -56,9 +56,9 @@
  * uncovered holes `assemble` recorded in `parts.json`'s `recomposite` block,
  * copied into `check.json` because the seam cannot see them — it compares the
  * setup pose with the flat stack of parts, and a pixel no part holds is
- * missing from both. When `motion.json` holds an animation beside the idle,
- * one more bar, `ANIMATIONS_DO_NOT_FOLD` (issue #320): rigc's own
- * `render --folds` over every animation, physics constraints left out
+ * missing from both. When `motion.json` holds an animation, one more bar,
+ * `ANIMATIONS_DO_NOT_FOLD` (issues #320, #333): rigc's own `render --folds`
+ * over every animation, the idle included, physics constraints left out
  * ({@link FOLD_LINE}). The part-alone renders, the shut-eye still, the keyed
  * build and the fold render are scratch (`_isolated/`, `_still/`, `_loop/`,
  * `_folds/`), removed before the stage returns.
@@ -317,10 +317,58 @@ export interface RigcCall {
   status: number;
   /** stdout then stderr. */
   out: string;
+  /**
+   * Which rigc ran the call, as {@link rigcIdentity} words it (`rigc <version> at <path>`), from a runner that knows
+   * its binary ({@link rigcRunnerAt}): set on every call that exited non-zero and on every `--version` call, so a
+   * refusal quoting the call names the binary and its version (issue #337). Absent from a runner that does not know.
+   */
+  ran?: string;
 }
 
 export type RigcRunner = (args: readonly string[]) => RigcCall;
 
+/** The process primitive {@link rigcRunnerAt} is given: `src/` spawns nothing, so the caller's spawn is injected. */
+export type RigcSpawn = (bin: string, args: readonly string[]) => RigcCall;
+
+/**
+ * A rigc binary as what it says it is: `rigc <version> at <path>`, the version being the first line `--version`
+ * printed — the line `check` prints before it builds (`checkStage`). A `--version` run that exited non-zero or
+ * printed nothing is said so, with the path, rather than read as a version.
+ */
+export function rigcIdentity(bin: string, version: RigcCall): string {
+  const first = version.out.trim().split('\n')[0] ?? '';
+  if (version.status === 0 && first !== '') return `rigc ${first} at ${bin}`;
+  return `rigc (\`--version\` exited ${version.status}${first === '' ? ' and printed nothing' : `, printing ${JSON.stringify(first)}`}) at ${bin}`;
+}
+
+/** The clause a refusal quoting a rigc call ends with: which rigc ran it ({@link RigcCall.ran}), or nothing when the runner did not say. */
+export function rigcRanClause(call: { ran?: string }): string {
+  return call.ran === undefined ? '' : `; ${call.ran} ran it`;
+}
+
+/**
+ * The runner every stage is given (issue #337): `bin` spawned through `spawn`, each call that exited non-zero, and
+ * each `--version` call, carrying {@link RigcCall.ran}. The identity is read once per runner, off its first
+ * `--version` call or, when a call fails before any, off one `--version` run then — so a green run spawns nothing
+ * extra, and a failure names the binary and version that produced it rather than leaving the reader to guess
+ * which rigc a path resolved to.
+ */
+export function rigcRunnerAt(bin: string, spawn: RigcSpawn): RigcRunner {
+  let identity: string | null = null;
+  return (args) => {
+    const call = spawn(bin, args);
+    const version = args.length === 1 && args[0] === '--version';
+    if (version) {
+      const own = rigcIdentity(bin, call);
+      identity ??= own;
+      return { ...call, ran: own };
+    }
+    if (call.status === 0) return call;
+    identity ??= rigcIdentity(bin, spawn(bin, ['--version']));
+    return { ...call, ran: identity };
+  };
+}
+
 /** A line in which a rigc run that stopped says why: Bun's own `error: …`, rigc's `rigc <command>: …` refusals, a `usage: …` line. */
 const CAUSE = /^(error: |rigc[\w -]*: |usage: )/;
 
@@ -396,6 +444,27 @@ export function readRigcEntry(versionOut: string): RigcEntryRecord {
   throw new Error('unreachable');
 }
 
+/**
+ * This package's own rigc: `node_modules/.bin/rigc` under `root` and nowhere else — no directory above it and no
+ * PATH, which {@link findRigc} walks (issue #337). The selftest's suites run rigc through it from the package root,
+ * so a fixture in a temp directory, or a tree nested inside another checkout (a harness worktree under
+ * `.claude/worktrees/`) whose own install is missing, cannot reach another tree's rigc. A miss is refused naming
+ * the one path looked at.
+ */
+export function packageRigc(root: string): string {
+  const bin = join(resolve(root), 'node_modules', '.bin', 'rigc');
+  if (!existsSync(bin)) {
+    refuseIfAny([
+      {
+        code: 'CHECK_RIGC_PACKAGE',
+        object: bin,
+        detail: `does not exist; this package's own rigc is required here and no other is looked for — not in a directory above ${resolve(root)}, not on PATH (\`bun install\` puts it there)`,
+      },
+    ]);
+  }
+  return bin;
+}
+
 /**
  * Where the `rigc` binary is: `node_modules/.bin/rigc` in `from` or any
  * directory above it (a clone has it beside the package; an install has it in
@@ -1646,7 +1715,7 @@ export interface CheckFigures {
   TIP_OVER_ROOT: JudgementLine;
   STILL_REGIONS_DARK: JudgementLine;
   TEXTURE_STRETCH: JudgementLine;
-  /** Written only when motion.json holds an animation beside the idle (issue #320): {@link FoldsLine}. */
+  /** Written whenever motion.json holds an animation, the idle included (issues #320, #333): {@link FoldsLine}. */
   [FOLD_LINE]?: FoldsLine;
   RECOMPOSITE_HOLES: ReportedLine;
   /** Written only under `--source` (issue #77): the setup pose against the painting, REPORTED. */
@@ -1672,8 +1741,9 @@ export interface RequirementsBlock {
 }
 
 /**
- * The bar over the animations beside the idle (issue #320): no mesh triangle
- * turned over against the setup pose on any frame, on rig-c's own reading —
+ * The bar over every animation, the idle included (issues #320, #333): no mesh
+ * triangle turned over against the setup pose on any frame, on rig-c's own
+ * reading —
  * `rigc render --folds`, one run over every animation the build holds — and
  * not a reading of this package's. A fold the art means is declared in the
  * requirements file's `may_fold`, by slot and animation with its why, and is
@@ -1689,8 +1759,12 @@ export interface RequirementsBlock {
  * not tracked]. The keys and weights fold at every rate or at none that the
  * sampling resolves; the rate a consumer steps physics at is the scene's.
  *
- * The idle is not read here: written only when the motion holds an animation
- * beside it, so a rig of the idle alone writes and prints what it did.
+ * The idle is read like any other animation (issue #333): `TEXTURE_STRETCH`
+ * reads how far the idle's triangles stretch, and a triangle that turns inside
+ * out is this bar's. Written whenever the motion holds an animation, so a rig
+ * of the idle alone writes it too; on the public examples and the trailer no
+ * idle folds, keys only [measured for issue #333, rigc 2.47.1, a scratch run,
+ * not tracked].
  */
 export const FOLD_LINE = 'ANIMATIONS_DO_NOT_FOLD';
 
@@ -1777,7 +1851,7 @@ export function besideIdleLine(names: readonly string[]): string | null {
 }
 
 // ---------------------------------------------------------------------------
-// the animations beside the idle, read for folds (issue #320)
+// every animation, the idle included, read for folds (issues #320, #333)
 // ---------------------------------------------------------------------------
 
 /**
@@ -1792,7 +1866,7 @@ export const FOLD_RENDER_MAX = 16;
 /** The fold render, under `--out`; removed before the stage returns. */
 const FOLD_SCRATCH = '_folds';
 
-/** One mesh that folds in one animation beside the idle: rigc's figures, the declaration that takes it if any, and rigc's own line. */
+/** One mesh that folds in one animation: rigc's figures, the declaration that takes it if any, and rigc's own line. */
 export interface FoldRow {
   animation: string;
   slot: string;
@@ -1811,10 +1885,10 @@ export interface FoldRow {
   line: string;
 }
 
-/** `check.json`'s `ANIMATIONS_DO_NOT_FOLD`: written only when the motion holds an animation beside the idle. */
+/** `check.json`'s `ANIMATIONS_DO_NOT_FOLD`: written whenever the motion holds an animation, the idle included. */
 export interface FoldsLine {
   status: 'PASS' | 'FAIL';
-  /** Every animation beside the idle, in motion.json's order: each one read. */
+  /** Every animation, the idle included, in motion.json's order: each one read. */
   animations: string[];
   fps: number;
   /** How many physics constraints the read build left out ({@link withoutPhysics}); 0 when the rig has none. */
@@ -1957,8 +2031,9 @@ export function rigcFailed(what: string, call: RigcCall, lines: readonly string[
   const named = lines.filter((l) => l.includes('FAIL') || l.includes('compile error'));
   const quoted = named.length > 0 ? named.map((l) => l.trim()) : causeLines(call.out);
   const object = `\`rigc ${what}\``;
-  if (quoted.length === 0) return [{ code: 'CHECK_RIGC_GREEN', object, detail: `exit ${call.status}, and it printed nothing` }];
-  return quoted.map((l) => ({ code: 'CHECK_RIGC_GREEN', object, detail: `exit ${call.status}: ${l}` }));
+  const ran = rigcRanClause(call);
+  if (quoted.length === 0) return [{ code: 'CHECK_RIGC_GREEN', object, detail: `exit ${call.status}, and it printed nothing${ran}` }];
+  return quoted.map((l) => ({ code: 'CHECK_RIGC_GREEN', object, detail: `exit ${call.status}: ${l}${ran}` }));
 }
 
 /**
@@ -2065,7 +2140,7 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
   let loopSet: FrameSet | null = null;
   let loopPhysics: LoopPhysics[] | null = null;
   // The keyed build (issues #183, #320): with a physics constraint, the same rig and motion with every one left out,
-  // built once the same way, which the loop and the folds of the animations beside the idle are both read from.
+  // built once the same way, which the loop and the folds of every animation are both read from.
   const stripped = withoutPhysics(inp.rig, inp.motion);
   let keyed: string | null = null;
   const keyedBuild = (what: string): string => {
@@ -2080,7 +2155,8 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
     keyed = join(loopDir, 'build');
     return keyed;
   };
-  const named = isRecord(inp.motion.animations) ? Object.keys(inp.motion.animations).filter((n) => n !== 'idle') : [];
+  const animationNames = isRecord(inp.motion.animations) ? Object.keys(inp.motion.animations) : [];
+  const named = animationNames.filter((n) => n !== 'idle');
   let folds: FoldsLine | null = null;
   const foldProblems: Problem[] = [];
   try {
@@ -2133,15 +2209,15 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
       written.push('motion_heat.png');
     }
 
-    // 3a. the animations beside the idle, read for folds by rigc (issue #320) — only when there is one; at the idle's
-    // rate whatever --requirements says, so a requirements file moves only what it declares (CK78), from the keyed build
-    if (named.length > 0) {
+    // 3a. every animation, the idle included, read for folds by rigc (issues #320, #333) — only when there is one; at
+    // the idle's rate whatever --requirements says, so a requirements file moves only what it declares (CK78), from the keyed build
+    if (animationNames.length > 0) {
       const fps = IDLE_FPS;
       try {
-        const fr = rigc(['render', '--candidate', keyedBuild('the animations beside the idle with their physics constraint(s) left out'), '--folds', '--fps', String(fps), '--max', String(FOLD_RENDER_MAX), '--out', foldDir]);
+        const fr = rigc(['render', '--candidate', keyedBuild('the animations with their physics constraint(s) left out'), '--folds', '--fps', String(fps), '--max', String(FOLD_RENDER_MAX), '--out', foldDir]);
         if (fr.status !== 0) refuseIfAny(rigcFailed(`render --folds --fps ${fps}${stripped === null ? '' : ' (physics constraint(s) left out)'}`, fr, fr.out.split('\n').filter((l) => l.includes('FAIL') || l.includes('rigc:'))));
-        const readings = readFoldSets(foldDir, named, fps, fr.out);
-        folds = foldsLine(named, fps, stripped === null ? 0 : stripped.physics.length, readings, reqFile === null ? [] : reqFile.may_fold, reqFile === null ? null : reqFile.path, foldProblems);
+        const readings = readFoldSets(foldDir, animationNames, fps, fr.out);
+        folds = foldsLine(animationNames, fps, stripped === null ? 0 : stripped.physics.length, readings, reqFile === null ? [] : reqFile.may_fold, reqFile === null ? null : reqFile.path, foldProblems);
       } finally {
         rmSync(foldDir, { recursive: true, force: true });
       }
@@ -2334,7 +2410,7 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
     const l = figures[n];
     tally(n, l.status === 'SKIP' ? l.reason : null);
   }
-  // Issue #320: the fold bar is counted only where it is written, so a rig of the idle alone counts what it counted.
+  // Issues #320, #333: the fold bar is counted where it is written — on every rig whose motion holds an animation.
   if (folds !== null) tally(FOLD_LINE, null);
   return {
     figures,
@@ -3511,7 +3587,7 @@ export function requireRigcVersion(rigc: RigcRunner): string {
       {
         code: 'CHECK_RIGC_VERSION',
         object: '`rigc --version`',
-        detail: `${got === null ? `exit ${v.status}, printed ${JSON.stringify(v.out.trim().split('\n')[0] ?? '')} — no version` : `is ${got.join('.')}`}; rig-c ${RIGC_GEOMETRY_VERSION} or later is required — its \`render --geometry\` writes the skinned mesh vertices TEXTURE_STRETCH is measured from (\`bun install\` puts this package's own rig-c at node_modules/.bin/rigc)`,
+        detail: `${got === null ? `exit ${v.status}, printed ${JSON.stringify(v.out.trim().split('\n')[0] ?? '')} — no version` : `is ${got.join('.')}`}${rigcRanClause(v)}; rig-c ${RIGC_GEOMETRY_VERSION} or later is required — its \`render --geometry\` writes the skinned mesh vertices TEXTURE_STRETCH is measured from (\`bun install\` puts this package's own rig-c at node_modules/.bin/rigc)`,
       },
     ]);
   }

package/src/contour.ts

@@ -380,8 +380,31 @@ export interface ContourBridges {
   units: number[][];
   /** One per unit but unit 0, in the order they were joined. */
   joins: ContourBridge[];
+  /**
+   * Only when one was left out (HQ's ruling on #326): each faint island — every pixel's alpha under
+   * {@link FAINT_ALPHA} — largest first. Its pixels stay in the image and are not meshed, so not drawn, as `stray`
+   * leaves dust; `artPixels` does not count them.
+   */
+  faint?: ContourFaintIsland[];
+}
+
+/** A faint island a bridged mesh left out (issue #326): its art px, its brightest pixel's alpha, and its box in part-image px `[x, y, w, h]`. */
+export interface ContourFaintIsland {
+  art: number;
+  maxAlpha: number;
+  box: [number, number, number, number];
 }
 
+/**
+ * Issue #326, HQ's ruling: under `bridges`, an island whose every pixel has alpha below this is faint, left out and
+ * named; any island with one pixel at or above it is visible and bridged, whatever the bridge costs. 64/255 is a
+ * quarter of full opacity — a faint pixel moves the composite by at most 63/255 of the colour beneath it — and it
+ * sits below the 128 that assemble and `check` read as covered (`FRONT_ALPHA`, `COVERED_ALPHA`, check's coverage),
+ * so nothing those readings count as drawn is left out. Read over what a bridged draft reaches on the public figures
+ * (the four examples and rig-c/trailer 6e2de45), the faint islands peak at 11–17 and the visible ones at 255.
+ */
+export const FAINT_ALPHA = 64;
+
 export interface ContourMesh {
   /** Part-image px, y down, every value a multiple of 1/{@link GRID}; the first `hull` are the outline, in walk order. */
   vertices: Array<[number, number]>;
@@ -2010,8 +2033,11 @@ interface BridgeUnit {
  * The bridged mesh (issue #326, Stage B; `bridges: true`). Stage A (`docs/evidence/island-draft.md`) measured the
  * join this builds by hand: rig-c reads one closed outline per mesh, and a bridge is what a join costs.
  *
- * 1. **Islands.** Every 4-connected island of the art is kept, but an island that is not the largest (nor tied
- *    with it) and holds `stray` art px or fewer, which is left out as the one-island rule leaves it out.
+ * 1. **Islands**, in this order. Dust first: an island that is not the largest (nor tied with it) and holds `stray`
+ *    art px or fewer is left out as the one-island rule leaves it out. Then faint islands: one that is not the
+ *    largest and whose every pixel has alpha under {@link FAINT_ALPHA} is left out the same way and named in
+ *    `bridges.faint`. Every other island is kept, and step 3 bridges it whatever its bridge costs — overdraw is
+ *    reported (`joins[].area`), never a reason to drop art.
  * 2. **Silhouettes, in the trace.** The kept islands with their holes filled grow together by the margin
  *    ({@link growSilhouette}, its pinch fill included), and each 4-connected piece of the grown set is one unit,
  *    traced on its own. Islands closer than about twice the margin grow into one unit and are traced as one
@@ -2044,17 +2070,26 @@ function bridgedMesh(part: string, mask: AlphaMask, params: ContourParams, comp:
   for (let l = 1; l <= n; l++) largest = Math.max(largest, comp.stats[l].area);
   const leave: number[] = [];
   for (let l = 1; l <= n; l++) if (comp.stats[l].area !== largest && params.stray !== undefined && comp.stats[l].area <= params.stray) leave.push(l);
+  // Issue #326 (HQ's ruling): after dust, a faint island — every pixel's alpha under FAINT_ALPHA — is left out and
+  // named; every other island is bridged whatever its bridge costs. The largest island (or a tie for it) is never left out.
+  const peak = new Array<number>(n + 1).fill(0);
+  for (let i = 0; i < comp.labels.length; i++) if (comp.labels[i] > 0) peak[comp.labels[i]] = Math.max(peak[comp.labels[i]], mask.alpha[i]);
+  const faint: number[] = [];
+  for (let l = 1; l <= n; l++) if (comp.stats[l].area !== largest && !leave.includes(l) && peak[l] < FAINT_ALPHA) faint.push(l);
   let meshed = mask;
   let strayPixels = 0;
-  if (leave.length > 0) {
-    const out = new Set(leave);
+  if (leave.length > 0 || faint.length > 0) {
+    const out = new Set([...leave, ...faint]);
     const alpha = new Uint8Array(mask.alpha);
     for (let i = 0; i < alpha.length; i++) if (out.has(comp.labels[i])) alpha[i] = 0;
     meshed = { width: w, height: h, alpha };
     for (const l of leave) strayPixels += comp.stats[l].area;
   }
   const keptIslands = new Set<number>();
-  for (let l = 1; l <= n; l++) if (!leave.includes(l)) keptIslands.add(l);
+  for (let l = 1; l <= n; l++) if (!leave.includes(l) && !faint.includes(l)) keptIslands.add(l);
+  const left: ContourFaintIsland[] = faint
+    .map((l) => ({ art: comp.stats[l].area, maxAlpha: peak[l], box: [comp.stats[l].left, comp.stats[l].top, comp.stats[l].width, comp.stats[l].height] as [number, number, number, number] }))
+    .sort((a, b) => b.art - a.art || a.box[1] - b.box[1] || a.box[0] - b.box[0]);
 
   const island = artMask(meshed, threshold);
   const filled = fillHoles(island);
@@ -2269,6 +2304,7 @@ function bridgedMesh(part: string, mask: AlphaMask, params: ContourParams, comp:
         islands: [...keptIslands].map((l) => comp.stats[l].area).sort((a, b) => b - a),
         units: units.map((u) => u.islands),
         joins: joins.map((j, i) => ({ ...j, vertices: quads[i].map(at) as [number, number, number, number] })),
+        ...(left.length === 0 ? {} : { faint: left }),
       },
     },
   };

package/src/errors.ts

@@ -23,6 +23,22 @@ export function problemLine(p: Problem): string {
   return `${p.code}: ${p.object} — ${p.detail}`;
 }
 
+/**
+ * The end of every FAIL line: the command that prints the guide's row for its
+ * rule (issue #343). This is the one place that writes it, so every line has the
+ * same form, and rig-c's lines have the same form with its own command. A line
+ * that quotes a rigc failure keeps rigc's pointer inside the quote, and this one
+ * goes after it.
+ */
+export function guidePointer(code: string): string {
+  return ` (see rig-parts guide ${code})`;
+}
+
+/** A refusal as it is printed: `  FAIL  RULE: object — detail (see rig-parts guide RULE)`. */
+export function failLine(p: Problem): string {
+  return `  FAIL  ${problemLine(p)}${guidePointer(p.code)}`;
+}
+
 export class PartsError extends Error {
   readonly problems: readonly Problem[];