@rig-c/core 2.40.1 → 2.42.0

package/README.md

@@ -41,6 +41,7 @@ installed.
 | the same, and one texture instead of many | `rigc build --pack` | the parts arranged onto shared atlas pages, written beside the skeleton — losslessly, so the picture is the picture |
 | a pack somebody already made | `rigc build --atlas-in` | the same skeleton, with every part resolved to a region of that atlas — or a named refusal, never a part that silently does not draw |
 | a compiled rig | `rigc render` | every animation as PNG frames, plus one labelled contact sheet of the whole shot |
+| a compiled rig and a question about its geometry | `rigc inspect` | one picture of its bones, axes, mesh edges and hulls, one bone's weights, the draw order, a world grid or a declared axis over the art — at the setup pose, one time or a sheet of several, zoomed to a bone or a slot, or beside a second build on one transform — and a legend that puts every mark back in world units |
 | a compiled rig | `rigc preview` | one self-contained `.html` that plays it in Spine's own web player |
 | two to four compiled rigs | `rigc vote` | one ballot page a human picks from, and the answer checked into a ledger |
 | a picture of a key pose | `rigc pose` | where each loose part PNG sits in it, in spec coordinates — the movement between two poses is then yours to key ([docs/MOTION.md](docs/MOTION.md)) |
@@ -402,8 +403,26 @@ second package, no server.
 ```bash
 rigc render  --candidate spine          # PNG frames + a contact sheet, in render/
 rigc preview --candidate spine          # one .html file that plays it: preview.html
+rigc inspect --candidate spine --show art,bones,names --dim   # inspect.png + inspect.json
 ```
 
+**`inspect`** answers a question about geometry rather than appearance — *is this
+bone where the art is*, *which way does it squash*, *where in rig units is this
+point*, *is this axis held*. It draws the build's art, framed as `render` frames it,
+and over it any of `bones` (origin to tip, a bone of length 0 marked as one),
+`names` (one label per pixel), `axes` (each bone's world x and y), `mesh` and `hull`
+(each mesh's edges and outline), `weights:<bone>` (what that bone moves, as a heat),
+`slots` (the draw order at the pose), `grid` (in world units) and `declared`
+(each `invariants.axes` line and the bones held to it), at the setup pose, at
+`--animation <name> --at <s[,s…]>` — one picture, or a sheet — or zoomed with
+`--zoom <bone|slot>[:pad]` or `--viewport x,y,w,h`; `--bone`/`--hide-bone` pick the
+bones by glob, and `--compare <dir>` draws a second build beside the first on one
+transform, to see what a change moved. Beside the PNG it writes a legend:
+the world-to-pixel transform both ways, what each colour means, and every bone's
+origin and tip in world units and in pixels, so a position read off the picture goes
+straight back into the spec. [AUTHORING §13](docs/AUTHORING.md#13-asking-the-picture-a-question--rigc-inspect)
+maps each question to its view.
+
 **`render`** samples every animation at 12 fps and writes `render/<animation>/f0000.png…`
 with a `contact.png` beside them — every frame of the shot as one labelled grid,
 which is the picture to open first, because spacing is a comparison *across*

package/docs/AUTHORING.md

@@ -126,6 +126,12 @@ bun cli.ts preview --candidate path/to/spine    # one .html that plays it in Spi
 #   ↳ a green build ends by naming this command for its own --out; repeat
 #     --candidate for a pane per candidate on one page
 
+# …and when the question is about geometry — is this bone where the art is, which
+# way does it squash — draw the bones over the art and read the legend beside it:
+bun cli.ts inspect --candidate path/to/spine --show art,bones,names --dim --out look.png
+#   ↳ look.png and look.json: every bone's origin and tip in world units and in
+#     pixels, and the transform between them — §13
+
 # …and where you have several green candidates and no instrument that separates
 # them, ask a human — the one loop step this toolchain cannot run for you:
 bun cli.ts vote --candidate path/to/spine-a --candidate path/to/spine-b   # -> ballot.html
@@ -235,10 +241,11 @@ What the flags mean:
 | `--cuts` | the `cuts.json` `--cut` names. Required beside it — `--cut` alone is refused, with no guess at where the table lives |
 | `--profile` | `spine` = the 35 validity rules (**the default**) · `spine-html` = all 51, opt-in |
 | `--report` | `build` and `repack`: also write the gate's report as a JSON document (`build-report/1`) to this file — every gate's `PASS`, `SKIP` and `FAIL` rows, its summary figures and stats line, which supplier judged it, and every `pack:` line's figures. Written when the command writes `--out` and when a gate is red, before the exit; a file already at the path is removed first, so a compile error or a refused repack leaves none. Never inside `--out`, refused by name. The printed lines are byte-identical with it and without it — **§5.3** |
-| `--candidate` | `check`, `bench`, `render`, `preview`, `chainfit` and `vote` only: a **compiled** artifact — the directory `build --out` wrote, or a `skeleton.json` path. A directory holding no `skeleton.json`, or a path with nothing at it, is refused `nothing at <path>`, exit 2, nothing written, by every command that takes a build — `validate <dir>` and a directory given to `diff` included (`RC27`). `--atlas <path>` names the atlas when it does not sit beside the skeleton. On `render` and `check` a rigc build whose `skeleton.model.json` is `rigc-compiled/3` or `/2` needs no atlas at all: with no `--atlas` and no atlas beside it, it is drawn from the document's `pages`, the same frames, geometry and figures as with it, and the `atlas` line says `— not there`. An atlas that is there is still read, and held to `pages`: one that differs (edited after the build) is drawn through spine-core, and the `poser` line names the first difference. A build drawn through an atlas that is not there — a `rigc-compiled/1` document, or a build the core refuses — is refused `nothing at <the atlas>: … is drawn through its atlas (<why>)`, exit 2, nothing written; a Spine export without its atlas is refused `nothing at <the atlas>` as it always was. A directory whose files are not one build — a `skeleton.json` or a `skeleton.atlas` from another build beside this one's `skeleton.model.json` — is drawn through spine-core where the runtime can load the pair, the `poser` line naming the two digests or the atlas's first difference; where it cannot, it is refused `<skeleton> does not load against <the atlas>: spine-core draws this pair (<the poser line's why>) and could not resolve it — "<the runtime's own words>". <dir> is not one build: …`, exit 2, nothing written (`RC18`) — another build's skeleton beside this build's atlas typically ends `"Region not found in atlas: <region> (attachment: <name>)"`. Rebuild, or put the build's own three files back beside each other. A Spine export beside an atlas it was not exported with is refused in the same words, ending `The skeleton and the atlas are not one pair`. An atlas copied from another build's directory usually stops earlier, at its pages — their paths are relative to the directory it was written in — and is refused naming the first one: `nothing at <the page>: <the atlas> names it as a page, and spine-core draws this pair through that atlas (<why>). … <dir> is not one build: …`, exit 2, nothing written (`RC18`); an export whose atlas names a page that is not there is refused the same way, ending `and the page has to be there`. A build moved or copied whole away from the directory it was built in stops at the same place, on either poser, and is refused naming the page and the file that names it: `nothing at <the page>: <the skeleton.model.json> names it as a page, and the core draws this build from it. A page path is relative to the build's directory, so a build moved or copied away from the directory it was built in names pages that are not here — build it again where it is, or build it with --copy-images, which writes its pages beside it` (under `--poser spine`, `<the atlas> names it as a page, and spine-core draws this pair through that atlas (--poser spine)` with the same ending), exit 2, nothing written (`RC21`); only where the core refused the files does a page refusal say the directory is not one build. `bench --bones` and `rigc bonedist` — on its `--candidate` and on its `--reference` — refuse a pair the runtime cannot load in the words above with `spine-core poses this pair (bonedist's candidate: …)` or `(bonedist's reference: …)`, exit 2, nothing written (`RC20`); they read no page image, so a build whose pages are elsewhere is measured as it is in place. A `skeleton.json` that is not JSON is refused `rigc: cannot read <the file>: <the parser's words> (line N, column N)`, exit 2, by `render`, `check`, `bench` and `bonedist` as by every other command that reads one (`RC22`). With the atlas gone, `check` on a `rigc-compiled/3` build reads its pages' `scale:` lines off the document, so its texture note and `check.json`'s `textureFrom.candidateScales` are what they are with the atlas; on a `/2` build its texture note says whether the atlas declares a `scale:` line is not read (that document does not state one), and `candidateScales` is `null` (`RC13`). **`vote` and `preview` take it more than once**: `vote` 2–4 times, one per pane, labelled A, B, C, D in the order given; `preview` any number of times, one pane per candidate in the order given, each headed by its path and its gate line, and the same skeleton twice (a directory and its `skeleton.json` are one) is refused by name. `--atlas` goes with one candidate only. Everywhere else a repeat is a typo and is refused |
+| `--candidate` | `check`, `bench`, `render`, `inspect`, `preview`, `chainfit` and `vote` only: a **compiled** artifact — the directory `build --out` wrote, or a `skeleton.json` path. A directory holding no `skeleton.json`, or a path with nothing at it, is refused `nothing at <path>`, exit 2, nothing written, by every command that takes a build — `validate <dir>` and a directory given to `diff` included (`RC27`). `--atlas <path>` names the atlas when it does not sit beside the skeleton. On `render` and `check` a rigc build whose `skeleton.model.json` is `rigc-compiled/3` or `/2` needs no atlas at all: with no `--atlas` and no atlas beside it, it is drawn from the document's `pages`, the same frames, geometry and figures as with it, and the `atlas` line says `— not there`. An atlas that is there is still read, and held to `pages`: one that differs (edited after the build) is drawn through spine-core, and the `poser` line names the first difference. A build drawn through an atlas that is not there — a `rigc-compiled/1` document, or a build the core refuses — is refused `nothing at <the atlas>: … is drawn through its atlas (<why>)`, exit 2, nothing written; a Spine export without its atlas is refused `nothing at <the atlas>` as it always was. A directory whose files are not one build — a `skeleton.json` or a `skeleton.atlas` from another build beside this one's `skeleton.model.json` — is drawn through spine-core where the runtime can load the pair, the `poser` line naming the two digests or the atlas's first difference; where it cannot, it is refused `<skeleton> does not load against <the atlas>: spine-core draws this pair (<the poser line's why>) and could not resolve it — "<the runtime's own words>". <dir> is not one build: …`, exit 2, nothing written (`RC18`) — another build's skeleton beside this build's atlas typically ends `"Region not found in atlas: <region> (attachment: <name>)"`. Rebuild, or put the build's own three files back beside each other. A Spine export beside an atlas it was not exported with is refused in the same words, ending `The skeleton and the atlas are not one pair`. An atlas copied from another build's directory usually stops earlier, at its pages — their paths are relative to the directory it was written in — and is refused naming the first one: `nothing at <the page>: <the atlas> names it as a page, and spine-core draws this pair through that atlas (<why>). … <dir> is not one build: …`, exit 2, nothing written (`RC18`); an export whose atlas names a page that is not there is refused the same way, ending `and the page has to be there`. A build moved or copied whole away from the directory it was built in stops at the same place, on either poser, and is refused naming the page and the file that names it: `nothing at <the page>: <the skeleton.model.json> names it as a page, and the core draws this build from it. A page path is relative to the build's directory, so a build moved or copied away from the directory it was built in names pages that are not here — build it again where it is, or build it with --copy-images, which writes its pages beside it` (under `--poser spine`, `<the atlas> names it as a page, and spine-core draws this pair through that atlas (--poser spine)` with the same ending), exit 2, nothing written (`RC21`); only where the core refused the files does a page refusal say the directory is not one build. `bench --bones` and `rigc bonedist` — on its `--candidate` and on its `--reference` — refuse a pair the runtime cannot load in the words above with `spine-core poses this pair (bonedist's candidate: …)` or `(bonedist's reference: …)`, exit 2, nothing written (`RC20`); they read no page image, so a build whose pages are elsewhere is measured as it is in place. A `skeleton.json` that is not JSON is refused `rigc: cannot read <the file>: <the parser's words> (line N, column N)`, exit 2, by `render`, `check`, `bench` and `bonedist` as by every other command that reads one (`RC22`). With the atlas gone, `check` on a `rigc-compiled/3` build reads its pages' `scale:` lines off the document, so its texture note and `check.json`'s `textureFrom.candidateScales` are what they are with the atlas; on a `/2` build its texture note says whether the atlas declares a `scale:` line is not read (that document does not state one), and `candidateScales` is `null` (`RC13`). **`vote` and `preview` take it more than once**: `vote` 2–4 times, one per pane, labelled A, B, C, D in the order given; `preview` any number of times, one pane per candidate in the order given, each headed by its path and its gate line, and the same skeleton twice (a directory and its `skeleton.json` are one) is refused by name. `--atlas` goes with one candidate only. Everywhere else a repeat is a typo and is refused |
 | `--animation` | `render`, `preview` and `vote` only: which animation to show. The default is **every** one for `render`, the **first** for `preview` (each candidate's own first, with several), and for `vote` the first of candidate A. A name the skeleton does not have is refused, with the ones it does have listed — and for `vote` and a several-candidate `preview`, so is a name that only *some* candidates have, naming the one that lacks it |
+| `--show`, `--dim`, `--at`, `--zoom` | `inspect` only — what it draws, whether the art is faded, which times of `--animation` it poses and the bone or slot it frames to; §13 says each, with the refusals |
 | `--geometry` | `render` only: also write a `geometry.json` into each frame directory — per frame, every bone's world transform and every slot's region or mesh vertices in world units after skinning, plus each attachment's rest geometry and topology, on the frames' own grid and viewport. Every other file is byte for byte what the render writes without it. Refused with `--slot`/`--hide`, because the geometry is the whole pose whatever is drawn — **§8.2** |
-| `--poser` | `render`, `check` and `explain`: `core` or `spine` — on `render` and `check`, which implementation poses the frames (on `check`, the candidate's; the reference side is pixels either way). By default a **rigc build** (the `skeleton.model.json` `build` writes; its atlas, when one is named or present, the one beside it) is posed by rigc's own core and a **Spine export** by spine-core; the render prints a `poser` line saying which and why, and so does the check report (`check.json`'s `poser`, and the pictures' `frames.json` under `--out`; `bench --frames` prints the same line). A concave or an inverse clip is posed by the core, and so is a build rendered with no `--skin` whose default skin names a skin-required bone or constraint, or whose skins name no `default` one — posed as a fresh skeleton is, no skin's bones or constraints applied (the default skin's included) and every slot resolved through the default skin alone, so the second draws nothing and stops at `there is nothing to draw` (exit 2) under either poser (issue #1051). Where the input cannot carry the core, or the core refuses it, the render poses it through spine-core and the `poser` line says why, in one of these words: `no skeleton.model.json beside` (a Spine export) · `is not beside` (`--atlas` names an atlas outside the build's directory) · `does not describe` (a model document whose bones, slots or animations are not the skeleton's) · `is not the skeleton.json` (a `skeleton.json` whose SHA-256 is not the `spine.sha256` its model document records — edited or replaced after the build — both digests named) · `the polygon is not simple` (a clip polygon two of whose edges cross or touch, the slot named) · `depends on the runtime's previous pass` (a constraint moves a posed bone from a bone that a constraint writes into while that bone is inactive, all four named) · `--poser spine` (asked for). Any other refusal of the core's — an unreadable model document among them — reads `the core refused` and then the core's own words. `--poser core` on an input that cannot carry it is refused in the same words (exit 2, nothing written); `--poser spine` forces the runtime. A fallback whose pair the runtime cannot load — another build's `skeleton.json` or atlas beside this build's document, or an export beside an atlas it was not exported with — is not drawn: it is refused `… does not load against <the atlas>: spine-core draws this pair (<why>) and could not resolve it — "<the runtime's own words>"` — or, where the atlas names a page that is not there, `nothing at <the page>: …` — exit 2, nothing written, on `render`, `render --geometry`, `check` and `bench --frames` alike; under `--poser core` the same pair is that flag's refusal, in the words above (`RC18`; the `--candidate` row says what to change). The repository's selftest renders one probe per reason above and holds this list to the lines they print (`RC09`). Both posers draw the same frames, geometry and framing box to the bit on every corpus (issue #968), and `check` through either writes the same report, `check.json` and pictures but for the poser it names on every tree row. A rigc build the core poses reads nothing through spine-core on `render`, `render --geometry` and `check`, `--texture-from` included (and the check `bench --frames` folds in; `bench`'s own `validate`, like `build`'s, is the runtime's round trip by design): its bone tree, slot list and slot roster come off its model document; so do the order its animations and skins are listed in, its stage and its pages' `scale:` lines, on a `rigc-compiled/3` document (`editorOrder`, `stage`, `pages`) — a `/2` or `/1` document states none of those, so they come off its own `skeleton.json` and atlas, and the `poser` line then says `a rigc-compiled/2 document, which does not state the order its skins and animations are listed in or its stage, read from` and names both files; where each region sits and the page images it draws off the document's `pages` (a `rigc-compiled/1` document's off the atlas beside it, and the `poser` line then says `a rigc-compiled/1 document, which does not state where each region sits on its page: that is read from` and names the atlas); and a `--texture-from` atlas off rigc's own atlas reader. The runtime is loaded for a Spine export, `--poser spine` and a fallback the `poser` line names; a run that cannot load it there is refused naming the input and why it needs the runtime (exit 1; `RC11`, `RC13`, `RC34`). On the entry that links none of spine-core — the installed `rigc` without the runtime beside it, `bun cli_core.ts` in a clone — that refusal ends on the route to the entry that does (``the entry that links it runs them — installed, the same `rigc` once @esotericsoftware/spine-core is installed beside the package; from a source checkout, `bun cli.ts` ``); a runtime that is installed and fails to load is refused without it, since installing it is not what that reader has to do. On `explain` the flag chooses the `DEFORM` block's survey (§4.11.2): `core`, the default, reads the skeleton's structure — its deform timelines and their keys, curves and slots, the skin each is keyed under, the sliders — off the model document the compile writes and poses it through the core, and spine-core is not touched (`RC15`); `spine` parses and poses the Spine skeleton through spine-core. The two are the same survey to the byte on every corpus row (`DM12`). Where the core refuses the document, the survey falls back to spine-core and the block says so on a line of its own (`read and posed through spine-core: …`); `--poser core` there is refused instead (exit 2), and a run that cannot load the runtime where it needs it is refused naming the survey and why (exit 1), ending on the same route where the entry links none of it |
+| `--poser` | `render`, `inspect`, `check` and `explain`: `core` or `spine` — on `render`, `inspect` and `check`, which implementation poses the frames (on `check`, the candidate's; the reference side is pixels either way). By default a **rigc build** (the `skeleton.model.json` `build` writes; its atlas, when one is named or present, the one beside it) is posed by rigc's own core and a **Spine export** by spine-core; the render prints a `poser` line saying which and why, and so does the check report (`check.json`'s `poser`, and the pictures' `frames.json` under `--out`; `bench --frames` prints the same line). A concave or an inverse clip is posed by the core, and so is a build rendered with no `--skin` whose default skin names a skin-required bone or constraint, or whose skins name no `default` one — posed as a fresh skeleton is, no skin's bones or constraints applied (the default skin's included) and every slot resolved through the default skin alone, so the second draws nothing and stops at `there is nothing to draw` (exit 2) under either poser (issue #1051). Where the input cannot carry the core, or the core refuses it, the render poses it through spine-core and the `poser` line says why, in one of these words: `no skeleton.model.json beside` (a Spine export) · `is not beside` (`--atlas` names an atlas outside the build's directory) · `does not describe` (a model document whose bones, slots or animations are not the skeleton's) · `is not the skeleton.json` (a `skeleton.json` whose SHA-256 is not the `spine.sha256` its model document records — edited or replaced after the build — both digests named) · `the polygon is not simple` (a clip polygon two of whose edges cross or touch, the slot named) · `depends on the runtime's previous pass` (a constraint moves a posed bone from a bone that a constraint writes into while that bone is inactive, all four named) · `--poser spine` (asked for). Any other refusal of the core's — an unreadable model document among them — reads `the core refused` and then the core's own words. `--poser core` on an input that cannot carry it is refused in the same words (exit 2, nothing written); `--poser spine` forces the runtime. A fallback whose pair the runtime cannot load — another build's `skeleton.json` or atlas beside this build's document, or an export beside an atlas it was not exported with — is not drawn: it is refused `… does not load against <the atlas>: spine-core draws this pair (<why>) and could not resolve it — "<the runtime's own words>"` — or, where the atlas names a page that is not there, `nothing at <the page>: …` — exit 2, nothing written, on `render`, `render --geometry`, `check` and `bench --frames` alike; under `--poser core` the same pair is that flag's refusal, in the words above (`RC18`; the `--candidate` row says what to change). The repository's selftest renders one probe per reason above and holds this list to the lines they print (`RC09`). Both posers draw the same frames, geometry and framing box to the bit on every corpus (issue #968), and `check` through either writes the same report, `check.json` and pictures but for the poser it names on every tree row. A rigc build the core poses reads nothing through spine-core on `render`, `render --geometry` and `check`, `--texture-from` included (and the check `bench --frames` folds in; `bench`'s own `validate`, like `build`'s, is the runtime's round trip by design): its bone tree, slot list and slot roster come off its model document; so do the order its animations and skins are listed in, its stage and its pages' `scale:` lines, on a `rigc-compiled/3` document (`editorOrder`, `stage`, `pages`) — a `/2` or `/1` document states none of those, so they come off its own `skeleton.json` and atlas, and the `poser` line then says `a rigc-compiled/2 document, which does not state the order its skins and animations are listed in or its stage, read from` and names both files; where each region sits and the page images it draws off the document's `pages` (a `rigc-compiled/1` document's off the atlas beside it, and the `poser` line then says `a rigc-compiled/1 document, which does not state where each region sits on its page: that is read from` and names the atlas); and a `--texture-from` atlas off rigc's own atlas reader. The runtime is loaded for a Spine export, `--poser spine` and a fallback the `poser` line names; a run that cannot load it there is refused naming the input and why it needs the runtime (exit 1; `RC11`, `RC13`, `RC34`). On the entry that links none of spine-core — the installed `rigc` without the runtime beside it, `bun cli_core.ts` in a clone — that refusal ends on the route to the entry that does (``the entry that links it runs them — installed, the same `rigc` once @esotericsoftware/spine-core is installed beside the package; from a source checkout, `bun cli.ts` ``); a runtime that is installed and fails to load is refused without it, since installing it is not what that reader has to do. On `explain` the flag chooses the `DEFORM` block's survey (§4.11.2): `core`, the default, reads the skeleton's structure — its deform timelines and their keys, curves and slots, the skin each is keyed under, the sliders — off the model document the compile writes and poses it through the core, and spine-core is not touched (`RC15`); `spine` parses and poses the Spine skeleton through spine-core. The two are the same survey to the byte on every corpus row (`DM12`). Where the core refuses the document, the survey falls back to spine-core and the block says so on a line of its own (`read and posed through spine-core: …`); `--poser core` there is refused instead (exit 2), and a run that cannot load the runtime where it needs it is refused naming the survey and why (exit 1), ending on the same route where the entry links none of it |
 | `--record` | `vote` only: a saved vote to check against its ballot and append to the ledger, instead of writing a ballot. This is the command's second mode; it takes no `--candidate` |
 | `--ballot` | `vote --record` only: the ballot the vote answers (default `ballot.html`). Its embedded manifest is what the vote is checked against, so the ballot file is the record of the question |
 | `--ledger` | `vote --record` only: the append-only JSONL the vote lands in (default `votes.jsonl`), one vote per line |
@@ -10048,3 +10055,163 @@ simply unused; a name the directory lacks is refused `no-part-image` by name.
   is a given condition and once your spec states it there is nothing left to be
   close to. Every threshold in the report is a reporting threshold. There is no pass
   bar and `caveats` says so in the file.
+
+## 13. Asking the picture a question — `rigc inspect`
+
+The gate answers everything a number can say, and a geometric judgement is not
+one of those: *the bones around the head look odd* is a sentence about a picture.
+`inspect` draws that picture of a green build — the art, and over it the rig's own
+geometry at one moment — and writes a **legend** beside it that turns every mark
+back into world units. The picture is for reading; the legend is for acting on what
+was read, because a position taken off it goes straight into a spec.
+
+```bash
+bun cli.ts inspect --candidate gallery/look/build --show art,bones,names --dim --max 640 --out look.png
+# rigc inspect
+#   ..    skeleton …/gallery/look/build/skeleton.json
+#   ..    atlas    …/gallery/look/build/skeleton.atlas
+#   ..    poser    rigc core — …/skeleton.model.json
+#   ..    view     art,bones,names over dimmed art — the setup pose
+#   ..    box      world x -35.2..835.2, y -35.2..915.2 at 0.6734 px per unit — 1 tile(s) of 586x640px (exact in the legend)
+# rigc: wrote …/look.png
+# rigc: wrote …/look.json
+```
+
+It poses through the poser `render` would pose the candidate with, and the `poser`
+line says which — rigc's core for a build with its `skeleton.model.json`, spine-core
+for an export or a named fallback (the `--poser` row in §0). Without `--zoom` or
+`--viewport` the picture is framed exactly as `render` frames the build at the same
+`--max`, so with nothing drawn over it the art **is** `render`'s frame, pixel for
+pixel (`IN09`).
+
+### 13.1 Which question, which view
+
+| The question | The view | What to read |
+| --- | --- | --- |
+| Is this bone where the art is? | `--show art,bones,names --dim` | each bone as a line from its origin to its tip, the origin a filled square, the tip a hollow one; a bone of length 0 is a hollow 5x5 square around its origin, so a joint nobody gave a length is not mistaken for a point on another bone. Three fringe chains drawn as evenly spaced page verticals is the kind of thing this shows at a glance |
+| Which way does this bone squash? | `--show art,axes --zoom <bone>` | the bone's world **x** axis (red) and **y** axis (green), each 24 px long at a world scale of 1 — longer or shorter as the bone scales. A `scaley` key squashes along the green one; if that is the page's vertical on a face painted at an angle, the blink squashes along the page |
+| Where in rig units is this point? | `--show art,grid --zoom <bone or slot>` or `--viewport x,y,w,h` | grid lines at whole multiples of a step in **world units**, each labelled with its value, the lines through 0 darker. The legend's transform converts any pixel exactly; the grid is for reading by eye |
+| Is this axis declared, and held? | `--show art,declared,bones` | each `invariants.axes` line (§3.7) through its two bones' origins, drawn across the whole tile, and the bones it holds drawn in their own colour; the legend states each held bone's world x axis and how far off the line it lies, as `A51` measures it, at the pose drawn |
+| Did it break during the move? | any of the above `--animation <name> --at <s,s,…>` | one tile per time, left to right on one grid, each labelled with its time and frame |
+| What does this bone move? | `--show art,mesh,weights:<bone> --dim` | the bone's weight over every region and mesh it moves, as a heat: a pixel whose centre lies in a triangle is painted the ramp's colour at the blend of its corners' weights — blue near 0, yellow at 0.5, red at 1 (the stops are in the legend) — and a weight of 0 is not painted, so the art shows where the bone does not reach. A region and an unweighted mesh are moved whole by their slot's bone. The weights are read off `skeleton.json`, the file both posers skin from; a bone that weights nothing paints nothing and the run says so on a line of its own |
+| How is this part triangulated? | `--show art,mesh,hull --zoom slot:<slot>` | each mesh's triangle edges, and over them its hull — vertex 0 to 1 to … to `hull − 1` and back. Regions are not drawn: a region is not a mesh. The legend lists every vertex in world units and in pixels |
+| Which is drawn over which? | `--show art,slots` | each slot that shows a region or mesh numbered by its place in the draw order **at the pose drawn** (0 is drawn first), on a white box at the centre of its attachment's box — so a `drawOrder` key (§4.7) shows from the first frame `render` draws it on |
+| Did this change move anything? | `--compare <dir>` beside any view | the same view of a second build beside the first, at the same times, on **one** world box and one transform, each half labelled `A`/`B` with the poser that posed it. A mark on a different pixel in the two halves is at a different place in the two rigs |
+
+### 13.2 Where it looks
+
+- **The setup pose** by default.
+- **One time, or several** — `--animation <name> --at <s[,s…]>`. A time is a frame
+  of the grid `render --fps <n>` draws the animation on (default 12): the pose at
+  `--at 0.5` is `render`'s `f0006.png`, the same continuous trajectory stepped the
+  same way, physics included. A time off that grid is refused naming the frames
+  either side (`--at 0.3 is not on the 12 fps frame grid … the frames either side
+  are 3 (0.2500s) and 4 (0.3333s)`); pass `--fps` for another grid. A time past the
+  end is refused naming the animation's length. Several times are a sheet: tiles
+  left to right, eight to a row, a one-pixel rule between them, all on one world box
+  so a mark that moves between two tiles moved in the rig.
+- **The whole rig**, framed as `render` frames it; **a box** — `--viewport x,y,w,h`
+  in world units, y up, `x,y` its bottom-left corner; or **one bone or slot** —
+  `--zoom <name>[:<pad>]`, the bone's origin and tip or the slot's attachment
+  vertices over every time drawn, padded by `<pad>` world units on every side
+  (default a quarter of the box's longer side). A name that is both a bone and a slot
+  is refused until it is written `bone:<name>` or `slot:<name>`; a bone of length 0
+  with no pad is one point, and is refused asking for one.
+- **Two builds** — `--compare <dir | skeleton.json>`. The second build is loaded as
+  the first is (its own poser, chosen by what it carries, on a `poser    B:` line),
+  posed at the same times, and drawn beside it: one time is two halves side by side,
+  several are pairs, four to a row. The box is the one `--viewport` names, or the
+  union of what `--zoom` names in **both** builds, or — with neither — the union of
+  `render`'s framing of each, so a half is `render`'s frame of its build only where
+  the two framings agree. A name either build lacks is refused naming that build.
+- `--max` is each tile's longer side in pixels (default 256), as on `render`.
+- `--dim` fades the art toward white (each channel keeps 0.4 of its distance from
+  white) so what is drawn over it reads.
+
+### 13.3 Labels, and which bones are drawn
+
+- **One label per pixel.** Bones whose origins land on one pixel — a `_ctl` bone and
+  its identity child, a chain's joint — are one label: the first by declaration
+  order, then `+N` for the rest (`leg0_ctl +2`). The pixel is the unit because it is
+  what overprints: two origins a third of a pixel apart print their names on each
+  other as surely as two that coincide. The legend's `labels` lists every bone of
+  each label, and `bones` keeps every bone.
+- **No label over another.** Labels are placed in declaration order (slot numbers
+  first); one that would touch an earlier label moves down a text line at a time
+  until it is clear, and a grey leader joins it to its origin. After 16 lines it
+  stays where it began and the legend marks it `overlaps`.
+- **`--bone <glob[,glob…]>`** draws only the bones a pattern matches, and
+  **`--hide-bone <glob[,glob…]>`** none of the ones it matches, applied after
+  `--bone` — so `--bone 'bang_*' --hide-bone '*_ctl,*_px'` is the fringe chains
+  without their control bones. A pattern is a glob — `*` any run of characters, `?`
+  one, matched against the whole name — rather than a regular expression: bone names
+  are identifiers, the patterns are comma-separated, and a glob needs no escaping in
+  the shell. The filter is on `bones`, `axes` and `names`; every bone stays in the
+  legend, and a left-out one says which flag left it out in `undrawn`. A pattern
+  that matches no bone is refused naming the bones there are.
+
+### 13.4 The legend
+
+`<out>.json` beside `<out>.png`, `rigc-inspect/1`. What it states:
+
+- `coordinates` — the two spaces and the transform, in both directions, as text:
+  `px = x0 + (x - minX) * scale; py = y0 + (maxY - y) * scale` and
+  `x = minX + (px - x0) / scale; y = maxY - (py - y0) / scale`. World is Spine's, y up;
+  the picture is y down from its top-left corner, and pixel (i, j) covers
+  `[i, i+1) x [j, j+1)` — a position's pixel is its floor.
+- `viewport` — the world box every tile is a picture of and its size in pixels;
+  `size` — the whole picture's.
+- `tiles[]` — per tile: `animation`, `frame` and `time` (`frame / fps`), its `box` in
+  the picture, its own `transform` (`minX`, `maxY`, `scale`, and `x0`, `y0`, its
+  top-left pixel), and `bones[]` — every bone in declaration order with its
+  `parent`, `length`, `zeroLength`, `origin` and `tip` each as `{ world, pixel }`,
+  `undrawn` (why it is not drawn — its world matrix is 0 at this time, unposed by the
+  skin or scaled to 0, or a `--bone`/`--hide-bone` pattern left it out — or `null`),
+  and with `axes` shown, the two axis ends. With `grid`, the step and every line's
+  value; with `declared`, each entry's line in degrees, its two points, and each held
+  bone's angle and how far off the line it is. With `names`, `labels[]`: each label's
+  `text`, the `bones` it stands for, its `anchor` pixel, the `box` it is drawn in,
+  and whether it was `moved` or `overlaps`. With `mesh`, `hull` or `weights`,
+  `meshes[]`: every region and mesh the pose shows, in draw order, with its `kind`,
+  `vertexCount`, `triangleCount`, `hull` (a mesh's hull vertex count), its unique
+  triangle `edges` as vertex pairs, every posed vertex in `world` and `pixel`, and
+  with `weights` the bone's weight at each vertex. With `slots`, `slots[]`: each
+  slot's `order`, `slot`, `attachment`, `bone`, its `anchor` and number's `box`.
+  On a sheet or a compare, `label` — the tile's label text and box; with `--compare`,
+  `build` — `A` or `B`.
+- `colours` — every colour the picture draws, as RGBA, with what it means.
+- `poser`, `show`, `dim`, `skin`, `animation`, `fps` and `framing` — what was drawn
+  and how it was framed (`shot`, `zoom` with the bone or slot, the pad and whether it
+  was stated, or `viewport`).
+- `weights` — with `weights:<bone>`: the bone, the ramp's stops as RGBA, the floor
+  below which nothing is painted, and how a pixel's weight is read.
+- `boneFilter` — `--bone` and `--hide-bone` as given.
+- `builds` — with `--compare`: each build (`A`, `B`), the poser that posed it, and
+  its `skeleton.json`'s sha256. `poser` is build `A`'s.
+
+Every number is `JSON.stringify`'s, the double the pose produced, not a rounding of
+it. The same build and flags write the same bytes (`IN10`).
+
+### 13.5 What it refuses
+
+Each of these exits 2, writes nothing, and names what exists: a bone or slot the
+build does not have (both rosters listed), an animation or skin it does not declare,
+a `--show` word it does not draw, a flag it does not take, a time off the frame grid
+or past the end, `--at` without `--animation` and the reverse, `--zoom` beside
+`--viewport`, `--show declared` on a skeleton with no `skeleton.model.json`
+beside it whose `spine.sha256` is its own — a Spine export states no rig invariants —
+`weights` with no bone or with a bone the build lacks (the bones listed), a
+`--bone`/`--hide-bone` pattern that matches no bone (the bones listed), and, with
+`--compare`, any of these that holds of the second build, said as `the --compare
+build: …`.
+A rig that declares no `invariants.axes` is not refused: the picture draws nothing
+for `declared` and the run says so on a line of its own.
+
+### 13.6 What it is not
+
+- **Not a score.** Nothing in it is a pass bar; the picture is read, and what is read
+  is acted on in the spec.
+- **Not a player.** It is one still, or a sheet of stills. A person watches
+  `@rig-c/play` or `rigc preview`.
+- **Not a second poser.** Everything it draws is a pose `render` would have drawn at
+  the same frame; where it disagrees with `render --geometry`, it is wrong (`IN04`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rig-c/core",
-  "version": "2.40.1",
+  "version": "2.42.0",
   "description": "AI-authored 2D rigging and animation, verified before it is written. rigc compiles a rig spec into skeleton data in the Spine 4.3 format, gates it with named assertions held to a spine-core round trip's verdicts, and emits nothing that fails. Ships as an agent skill.",
   "type": "module",
   "bin": {

package/skills/rigc/SKILL.md

@@ -74,6 +74,11 @@ row for each.
    cover a feature the art shows — and answer each with `render --hide <slot>` (or
    `--slot <slot,…>`), which draws the frame again without that part on the same
    grid, so the two frames say which part a pixel is. AUTHORING §0 holds the three.
+   When the question is geometry — is this bone where the art is, which way does it
+   squash, where in rig units is this point — `rigc inspect --candidate <out> --show
+   art,bones,names --dim` draws the bones over the art and writes a legend beside the
+   picture that puts every mark back in world units; AUTHORING §13 maps each
+   question to its view.
 5. `rigc check --candidate <out> --frames <dir>` when you have reference pictures
    (`--out <dir>` writes the picture each of its numbers came from — open the worst).
    Read its output from the top: the framing block says whether the figures under

package/src/cli/core_commands.ts

@@ -1,6 +1,6 @@
 /**
  * The bodies of the commands that reach nothing of spine-core — `explain`,
- * `ingest`, `diff`, `check`, `render`, `pose`, `chainfit` and `skills` —
+ * `ingest`, `diff`, `check`, `render`, `inspect`, `pose`, `chainfit` and `skills` —
  * moved here unchanged from `cli.ts` (issue #1052, step 4e of #380), with the
  * helpers only they call. Both entries register them (`CORE_COMMAND_RUNS`):
  * `cli.ts` beside the runtime's, `cli_core.ts` alone. And the body
@@ -30,12 +30,13 @@ import { ingest, INGEST_GUTTERS, type IngestFinding, IngestSpecRefused, type Ing
 import { PARSER_DEFAULTS, parserReading } from '../keyorder.ts';
 import { MODEL_DOCUMENT_FILE, modelDocument } from '../model.ts';
 import { parseMotionSpec } from '../motion.ts';
+import { type InspectCompare, type InspectFrame, InspectError, inspectCandidate, INSPECT_DEFAULT_FPS, legendText, readBonePatterns, readShow, readTimes, readZoom } from '../inspect.ts';
 import { estimatePose, poseLines, type PoseOptions } from '../pose.ts';
 import { BACKGROUND, contactSheet, type Frame, FRAMES_SIDECAR, FRAMES_SPEC, type FrameSet, type FramesSidecar, framingViewport, GEOMETRY_FILE, geometryFileOf, geometryText, loadCandidate, POSER_NAMES, type PoserName, PROTOCOL_FPS, refuseUnchosen, renderFrame, sampleAll, sampleAnimation, SETUP_POSE_DIR, SHEET_FILE, SHEET_TILE, sidecarViewport, type SkeletonFacts, type SlotSubset, SlotSubsetError, throughPoser } from '../render_shared.ts';
 import { type CompileResult } from '../types.ts';
 import { attachmentRegionJoins } from '../region_joins.ts';
 import { cmdRepack } from './repack.ts';
-import { ATLAS_ABSENT, COMMANDS, type CommandRun, resolveBuild, type BuildGate, runBuild, PACKAGE_ROOT, DEFAULT_CHAINFIT_OUT, DEFAULT_POSE_OUT, DEFAULT_SKILLS_DIR, ExplainError, meshBudget, meshDepthNote, meshFit, meshInfluenceNote, PAGE_GRID_UNLOCATED, readAnimationFlag, readJsonFile, readPoserFlag, readSkeletonText, readVersion, resolveCut, resolveDrawable, runCheck, SkillsInstallError, STAGELESS_FRAMING, UsageError, writeJson, documentStageBeside } from './shared.ts';
+import { ATLAS_ABSENT, COMMANDS, type CommandRun, modelTextBeside, resolveBuild, type BuildGate, runBuild, PACKAGE_ROOT, DEFAULT_CHAINFIT_OUT, DEFAULT_POSE_OUT, DEFAULT_SKILLS_DIR, ExplainError, meshBudget, meshDepthNote, meshFit, meshInfluenceNote, PAGE_GRID_UNLOCATED, readAnimationFlag, readJsonFile, readPoserFlag, readSkeletonText, readVersion, resolveCut, resolveDrawable, runCheck, SkillsInstallError, STAGELESS_FRAMING, UsageError, writeJson, documentStageBeside } from './shared.ts';
 import { 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';
 
@@ -648,6 +649,118 @@ export function cmdRender(flags: Record<string, string>): void {
   console.log(`rigc: wrote ${join(outRoot, FRAMES_SIDECAR)}`);
 }
 
+/** Where `inspect` writes when `--out` is not given, and the name it takes inside a directory `--out` names. */
+export const DEFAULT_INSPECT_OUT = 'inspect.png';
+
+/**
+ * inspect — one moment of a build drawn for an agent to read, and the legend
+ * that turns its pixels back into world units (issue #1357). The view is
+ * `src/inspect.ts`'s; this reads the flags, loads the candidate the way
+ * `render` loads it and writes the two files.
+ *
+ * ⚠️ A flag this command does not take is refused by name here rather than
+ * ignored: the parser accepts any `--word value`, and a view asked for with a
+ * flag that does nothing would be a picture of something other than what the
+ * caller asked about.
+ */
+export function cmdInspect(flags: Record<string, string>): void {
+  const doc = COMMANDS.find((c) => c.name === 'inspect');
+  const accepted = [...(doc?.flags ?? []), 'help'];
+  const stray = Object.keys(flags).filter((name) => !accepted.includes(name));
+  if (stray.length > 0) {
+    throw new InspectError(`inspect takes no --${stray.join(', --')}; it takes --${accepted.filter((f) => f !== 'help').join(', --')}`);
+  }
+  if (flags.candidate === undefined) {
+    throw new UsageError('inspect needs --candidate <dir | skeleton.json> — the directory `build --out` wrote');
+  }
+  if (flags.zoom !== undefined && flags.viewport !== undefined) {
+    throw new InspectError('--zoom and --viewport both choose the box the picture is of; give one of them');
+  }
+  const { show, weightsBone } = readShow(flags.show);
+  const include = readBonePatterns('bone', flags.bone);
+  const exclude = readBonePatterns('hide-bone', flags['hide-bone']);
+  const boneFilter = include === undefined && exclude === undefined ? undefined : { ...(include === undefined ? {} : { include }), ...(exclude === undefined ? {} : { exclude }) };
+  const times = readTimes(flags.at);
+  const fps = readPositiveNumber(flags, 'fps', INSPECT_DEFAULT_FPS, 1);
+  const maxSide = readPositiveNumber(flags, 'max', 256, 16);
+  let frame: InspectFrame = { kind: 'shot' };
+  if (flags.zoom !== undefined) frame = { kind: 'zoom', ...readZoom(flags.zoom) };
+  if (flags.viewport !== undefined) {
+    const parts = flags.viewport.split(',').map((s) => Number(s.trim()));
+    if (parts.length !== 4 || parts.some((n) => !Number.isFinite(n))) {
+      throw new UsageError('--viewport takes four numbers: <x>,<y>,<width>,<height> — the world box, y up');
+    }
+    if (parts[2] <= 0 || parts[3] <= 0) throw new UsageError('--viewport width and height must be positive');
+    frame = { kind: 'viewport', x: parts[0], y: parts[1], width: parts[2], height: parts[3] };
+  }
+  const target = resolve(flags.out ?? DEFAULT_INSPECT_OUT);
+  const out = existsSync(target) && statSync(target).isDirectory() ? join(target, DEFAULT_INSPECT_OUT) : target;
+  if (!out.endsWith('.png')) throw new InspectError(`--out ${flags.out}: the picture is a PNG, so --out names a .png file (its legend is written beside it as .json)`);
+  const legendPath = `${out.slice(0, -'.png'.length)}.json`;
+
+  const { skeletonPath, atlasPath, atlasText } = resolveDrawable(flags.candidate, flags.atlas);
+  const skeletonText = readSkeletonText(skeletonPath);
+  console.log('rigc inspect');
+  console.log(`  ..    skeleton ${skeletonPath}`);
+  console.log(`  ..    atlas    ${atlasPath}${atlasText === null ? ` — not there (${ATLAS_ABSENT})` : ''}`);
+  // `render`'s loading, in `render`'s order (issue #1014): the poser is chosen before anything is read off the candidate.
+  const candidate = loadCandidate(
+    { skeletonText, atlasText, atlasDir: dirname(atlasPath), label: skeletonPath },
+    { skeleton: skeletonPath, atlas: atlasPath },
+    posersAsked(flags),
+  );
+  const animation = readAnimationFlag(flags, [...candidate.facts.animations]) ?? null;
+  readPoserFlag(flags);
+  refuseUnchosen(candidate.choice);
+  // `--compare`: the second build, loaded the way the first was — its own poser chosen by what it carries, and said.
+  let compare: InspectCompare | undefined;
+  if (flags.compare !== undefined) {
+    const other = resolveDrawable(flags.compare, undefined);
+    const otherText = readSkeletonText(other.skeletonPath);
+    console.log(`  ..    compare  ${other.skeletonPath}`);
+    const otherCandidate = loadCandidate(
+      { skeletonText: otherText, atlasText: other.atlasText, atlasDir: dirname(other.atlasPath), label: other.skeletonPath },
+      { skeleton: other.skeletonPath, atlas: other.atlasPath },
+      posersAsked(flags),
+    );
+    refuseUnchosen(otherCandidate.choice);
+    compare = { candidate: otherCandidate, texts: { skeletonText: otherText, modelText: modelTextBeside(other.skeletonPath, otherText) } };
+  }
+  const result = inspectCandidate(
+    candidate,
+    { skeletonText, modelText: modelTextBeside(skeletonPath, skeletonText) },
+    {
+      show,
+      ...(weightsBone === undefined ? {} : { weightsBone }),
+      ...(boneFilter === undefined ? {} : { boneFilter }),
+      dim: flags.dim !== undefined,
+      animation,
+      times,
+      fps,
+      skin: flags.skin,
+      frame,
+      maxSide,
+    },
+    {},
+    compare,
+  );
+  const { legend } = result;
+  console.log(`  ..    poser    ${compare === undefined ? '' : 'A: '}${result.poserNote}`);
+  if (result.comparePoserNote !== undefined) console.log(`  ..    poser    B: ${result.comparePoserNote}`);
+  const when = animation === null ? 'the setup pose' : `${animation} at ${legend.tiles.filter((t) => t.build !== 'B').map((t) => `${t.time.toFixed(4)}s (frame ${t.frame})`).join(', ')}, ${fps} fps grid`;
+  console.log(`  ..    view     ${legend.show.join(',')}${legend.dim ? ' over dimmed art' : ''} — ${when}`);
+  const v = legend.viewport;
+  // Four places for reading; the legend carries every number exactly.
+  const f = (n: number): string => String(Number(n.toFixed(4)));
+  console.log(`  ..    box      world x ${f(v.minX)}..${f(v.maxX)}, y ${f(v.minY)}..${f(v.maxY)} at ${f(v.scale)} px per unit — ${legend.tiles.length} tile(s) of ${v.width}x${v.height}px (exact in the legend)`);
+  for (const note of result.notes) console.log(`  ..    ${note}`);
+  mkdirSync(dirname(out), { recursive: true });
+  result.plate.writePng(out);
+  writeFileSync(legendPath, legendText(legend));
+  console.log(`rigc: wrote ${out}`);
+  console.log(`rigc: wrote ${legendPath}`);
+}
+
 /** `--scale 0.5,2` / `--rotation -30,30` — a pair of numbers, low first. */
 function readRange(flags: Record<string, string>, key: string): { low: number; high: number } | undefined {
   const raw = flags[key];
@@ -1621,6 +1734,7 @@ export const CORE_COMMAND_RUNS: Readonly<Record<string, CommandRun>> = {
   diff: ({ flags, lists, positional }) => cmdDiff(flags, lists, positional),
   check: ({ flags }) => cmdCheck(flags),
   render: ({ flags }) => cmdRender(flags),
+  inspect: ({ flags }) => cmdInspect(flags),
   pose: ({ flags }) => cmdPose(flags),
   chainfit: ({ flags }) => cmdChainFit(flags),
   skills: ({ flags, positional }) => cmdSkills(flags, positional),

package/src/cli/shared.ts

@@ -56,6 +56,7 @@ import { BallotError } from '../ballot.ts';
 import { ChainFitError } from '../chainfit.ts';
 import { CheckError } from '../check.ts';
 import { IngestError, type IngestStage } from '../ingest.ts';
+import { InspectError, DEFAULT_SHOW, DIM_KEEP, INSPECT_DEFAULT_FPS, ON_GRID_FRAMES, SHOW_SPELLINGS } from '../inspect.ts';
 import { NotAPngError } from '../png.ts';
 import { PoseError } from '../pose.ts';
 import { RepackError } from '../repack.ts';
@@ -125,7 +126,7 @@ export { PACKAGE_ROOT, readPackageMeta, readVersion };
  * needs a value` (issue #328). `CLI10`/`CLI11` in `selftest.ts` now hold the two
  * halves together by reading `--help` rather than by naming a flag.
  */
-const BOOLEAN_FLAGS = new Set(['all-frames', 'all-bones', 'help', 'copy-images', 'again', 'pack', 'copy', 'geometry', 'accept-skeleton-differences', 'keep-pages']);
+const BOOLEAN_FLAGS = new Set(['all-frames', 'all-bones', 'help', 'copy-images', 'again', 'pack', 'copy', 'geometry', 'accept-skeleton-differences', 'keep-pages', 'dim']);
 
 /**
  * The flags a command is allowed to spell more than once.
@@ -996,7 +997,7 @@ const FLAG_MEANINGS: Record<string, string> = {
     "slot's region or mesh vertices in world units after skinning, plus each attachment's rest geometry — on the " +
     'frames\' own grid and viewport. Not with --slot/--hide: the geometry is the whole pose whatever is drawn',
   poser:
-    "`render` and `check`: which implementation poses the frames (on `check`, the candidate's) — `core` (rigc's own, reading the skeleton.model.json a " +
+    "`render`, `inspect` and `check`: which implementation poses the frames (on `check`, the candidate's) — `core` (rigc's own, reading the skeleton.model.json a " +
     'build writes beside the pair) or `spine` (spine-core). Default: `core` when that document and the atlas sit ' +
     "beside the skeleton and the skeleton is the one the document records (spine.sha256), `spine` otherwise and wherever the core refuses the input by name; the `poser` " +
     'line of the render or the check report says which and why. `--poser core` on an input that cannot carry it is refused by name. ' +
@@ -1061,6 +1062,36 @@ const FLAG_MEANINGS: Record<string, string> = {
     '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)',
+  show:
+    `what \`inspect\` draws, comma-separated, from [${SHOW_SPELLINGS.join(', ')}] (default \`${DEFAULT_SHOW.join(',')}\`): art = the ` +
+    "build's own frame; grid = lines at whole multiples of a step in world units, labelled; weights:<bone> = that bone's " +
+    'weight over every region and mesh it moves, as a heat on a ramp the legend states; mesh = each mesh\'s triangle edges; ' +
+    "hull = each mesh's hull outline; declared = each invariants.axes " +
+    "line through its two bones' origins, its held bones drawn in their own colour; bones = each bone from origin to tip, " +
+    'a bone of length 0 marked as one; axes = each bone\'s world x and y axes; slots = each slot\'s place in the posed ' +
+    'draw order; names = the bones\' names, one label per pixel (bones sharing an origin pixel are "first +N"). Any other word ' +
+    'is refused naming these',
+  dim: `fade the art toward white (each channel keeps ${DIM_KEEP} of its distance from white), so what is drawn over it reads`,
+  at:
+    `the times of --animation to draw, in seconds, comma-separated — one is a picture, several a sheet of tiles on one ` +
+    `grid in the order given. Each must be a frame of the --fps grid render draws the animation on (within ` +
+    `${ON_GRID_FRAMES} of a frame), and is refused naming the frames either side otherwise; without --animation the ` +
+    'picture is the setup pose and --at is refused',
+  zoom:
+    'frame the picture to one bone (origin to tip) or one slot (its attachment\'s vertices) over every time drawn, padded ' +
+    'by <pad> world units on every side (default: a quarter of the box\'s longer side). A name that is both a bone and a ' +
+    'slot is refused until written bone:<name> or slot:<name>; a name that is neither lists both rosters. Not with --viewport',
+  bone:
+    "draw only the bones these globs match (`*` any run of characters, `?` one, the whole name; comma-separated) — on `inspect`, " +
+    "for bones, axes and names; every bone stays in the legend, a left-out one saying why in `undrawn`. A pattern that matches no " +
+    'bone is refused naming the bones there are',
+  'hide-bone':
+    "draw none of the bones these globs match — `--bone` the other way round, applied after it, so `--bone 'bang_*' " +
+    "--hide-bone '*_ctl'` is the fringe chains without their control bones",
+  compare:
+    'a second build to draw beside --candidate, the same view at the same times on one world box and one transform — the union ' +
+    'of both framings unless --zoom or --viewport pins it — each half labelled with its build and the poser that posed it. A ' +
+    'name, animation or skin the second build lacks is refused naming it',
   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}\`)`,
@@ -1158,6 +1189,12 @@ const FLAG_VALUES: Record<string, string> = {
   slot: '<name[,name…]>',
   hide: '<name[,name…]>',
   max: '<px>',
+  show: '<view[,view…]>',
+  at: '<s[,s…]>',
+  zoom: '<name>[:<pad>]',
+  bone: '<glob[,glob…]>',
+  'hide-bone': '<glob[,glob…]>',
+  compare: '<dir|skeleton.json>',
   record: '<result.json>',
   ballot: '<ballot.html>',
   ledger: '<votes.jsonl>',
@@ -1536,6 +1573,38 @@ export const COMMANDS: CommandDoc[] = [
       fps: { meaning: `frames per second to sample the animation at (default ${PROTOCOL_FPS})` },
     },
   },
+  {
+    name: 'inspect',
+    runtime: false,
+    spineFormat: false,
+    usage: [
+      'rigc inspect --candidate <dir | skeleton.json> [--show art,bones,…] [--dim] [--max 256] [--poser core|spine] [--out inspect.png]   (the setup pose)',
+      'rigc inspect … --animation <name> --at <s[,s…]> [--fps 12] [--skin <name>]   (one time, or a sheet of several on one grid)',
+      'rigc inspect … --zoom <bone|slot>[:<pad>] | --viewport <x,y,w,h>   (a box, in world units)',
+      "rigc inspect … --bone 'bang_*' --hide-bone '*_ctl'   (which bones bones, axes and names draw)",
+      'rigc inspect … --compare <dir | skeleton.json>   (a second build beside the first, on one transform)',
+    ],
+    flags: ['candidate', 'atlas', 'show', 'dim', 'animation', 'at', 'fps', 'skin', 'zoom', 'viewport', 'bone', 'hide-bone', 'compare', 'max', 'poser', 'out'],
+    overrides: {
+      animation: { meaning: 'the animation --at reads its times from (default: the setup pose, with no --at)' },
+      fps: { meaning: `the frame grid --at is read on, which is the grid \`render --fps\` draws (default ${INSPECT_DEFAULT_FPS})` },
+      viewport: { meaning: 'frame the picture to this world box, y up — x,y its bottom-left corner — instead of render\'s framing of the whole rig' },
+      out: {
+        value: '<file.png>',
+        meaning:
+          'the picture to write (default `inspect.png`; a directory means that name in it), and beside it the legend, the same ' +
+          'path with .json for .png: the world-to-pixel transform both ways, what each colour means, and every bone\'s origin ' +
+          'and tip in world units and in pixels',
+      },
+    },
+    notes: [
+      'inspect draws one moment of the build for an agent to read, and its legend says',
+      'where every mark is in world units and in pixels. It poses through the poser',
+      'render would pose the candidate with, and the poser line says which. Without',
+      '--zoom or --viewport the picture is framed as render frames the build, so its',
+      'art is render\'s frame at the same time and --max. Nothing in it is a score.',
+    ],
+  },
   {
     name: 'preview',
     runtime: { for: "its gate line is the round trip's, and it names the pages it embeds through spine-core's atlas reader" },
@@ -2704,6 +2773,12 @@ function refuse(err: unknown, command: string | undefined, USAGE: string, entry:
   // 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.
+  // A view refused before anything was drawn (issue #1357): a name the build does not have, a time off render's
+  // frame grid, a box with no size. The message lists what exists; the usage under it would bury that.
+  if (err instanceof InspectError) {
+    console.error(`rigc inspect: ${err.message}`);
+    process.exit(2);
+  }
   if (err instanceof ChainFitError) {
     console.error(`rigc chainfit: ${err.message}`);
     process.exit(2);