rig-parts 1.83.1 → 1.84.0

package/README.md

@@ -184,26 +184,7 @@ pads a non-square upload before resizing; the centre-crop reported in
 `st_input_full.png` supplies the explicit white padding that rig-parts maps back
 to the original painting. This is a source inspection, not a new demo run.
 
-**The head run is needed on every route that was read.** See-through's model
-already separates the head in a second stage of its own: it crops the head the
-first stage found, runs the face tags on that crop at the same `resolution`, and
-pastes the result back **resized to the full image's scale**. So the face comes
-back at the full run's pixel density whichever route ran it, and the separate
-head run on `st_input_head.png` is what gives the eyes more pixels
-(read on 2026-09-28 at see-through `a25a549` and wrapper 0.5.0 `98d754b`):
-
-- *Hugging Face Space* — the same two-stage code, with `resolution` capped at
-  1280 (768 by default): the head run is still needed.
-- *ModelScope demo* — its code was not read, so what the head run adds on that
-  route has not been measured.
-- *Upstream CLI* — the `.psd` frame is the `resolution`-sided square the first
-  stage ran on (1280 by default), and the head stage is pasted into it at that
-  scale: the head run is still needed.
-- *ComfyUI wrapper* — `SeeThrough_GenerateLayers` runs both stages with no input
-  to change the second, at most `resolution` 2048, which on the examples' 2432 px
-  square is 1.19 source px per layer px against 0.77 and 0.47 for their head
-  crops; at the 1024 the examples ran, the full run's right eye white is 22×13 px
-  and the head run's 60×38: the head run is still needed.
+The [head-run source reading](docs/AUTHORING.md#see-through-head-run-source-reading) explains why a separate head crop is needed.
 
 **See-through is required; ComfyUI is not.** The wrapper is one route among
 four, and `rig-parts comfy` is only a convenience for that route: every
@@ -329,86 +310,29 @@ agent skill.
 
 ## Commands
 
+Command details and config saving are in the [command reference](docs/AUTHORING.md#command-reference) and [stable interface](docs/STABILITY.md#commands-and-flags).
+
 | command | does |
 | --- | --- |
-| `inputs --source <png> --config <json> --out <dir>` | the two images See-through is fed: the painting on a white square, and the head box's crop once the config has one |
-| `comfy paint --config --out [--host]` | optional: generate the painting on a ComfyUI box from the config's `generation` block |
-| `comfy seethrough --image --out [--host]` | optional: run the ComfyUI See-through wrapper on one image and write the form `layers` reads |
-| `layers <dir \| layers.json \| file.psd>` | keep the existing columns (`opaque_px` still means alpha >8) and append source-alpha boxes `drawn(a>8)` / `opaque(a>=250)` with exclusive right/bottom; name absent boxes, report the existing body-group union height at **CORE_ALPHA (>=250)** in **input-canvas px**, and show its >8 union separately; no anatomical height, ownership/erosion or painting registration is inferred ([units and rig-scale guidance](docs/AUTHORING.md#4-the-command-order)) |
-| `sheet --source <png> --layers <path>… --out <png>` | a labelled contact sheet of the painting and every layer or part |
-| `assemble --propose-plan … [--write-config <config>]` | propose `assemble.plan` and `extend_below_crop` from the two runs, leaving out an implausible layer with a note naming the rule, naming in a note any full-run body no planned part covers, and naming every layer no row takes with why (empty, taken from the other run only, a plausibility rule; `nose`, never planned, with the row that lets `propose` read the head's pitch) |
-| `assemble --source --full --head --config --out [--seam] [--project]` | merge the two runs into rig-space parts, `parts.json`, the recomposite and its error map, and list the uncovered holes |
-| `propose --head-box --full <run> --canvas WxH [--no-back-hair] [--write-config <config>]` | propose `seethrough.head_box` from the full run, held inside the painting; `--no-back-hair` leaves the back-hair layer out of that proposal |
-| `propose --parts --source --out [--compare <config>] [--write-config <config> [--only-missing]]` | propose bones, meshes, regions and an idle; draw the overlay; print, per bone, which check read it or that none did and why (its role, its kind of segment), and write `basis.json` beside the proposal — what each bone rests on (a joint, a part's mask, a ratio, other bones) and, with `--compare`, whether the config's bone differs |
-| `propose … --keypoints <file> [--person <id>]` | read a posed figure's joints from one explicit file (space, image size, people, each joint observed, occluded or missing, its source): a joint with a position places the neck, hip, chest or a sleeve chain as given, a note says how every joint was used or which rule stood in, and LINT reads the torso and sleeves along the joints instead of by screen y ([AUTHORING §3](docs/AUTHORING.md)) |
-| `propose … --full <run> --head <run> --write-config <config>` | [draft an independent neck](docs/AUTHORING.md#a-neck-that-moves-on-its-own) in an existing sampled body turn and reassemble its full-run source under `<out>/rig` |
-| `propose … --grid-rule figure\|part` | how each drafted lattice's spacing is chosen: `figure` (the default) one spacing for the figure, round(H / 37) rig px, a part already coarser keeping its own, with a note on its calibration and cost; `part` the reference's rule, a tenth of the part's short side (the oracle examples are proposed under it) |
-| `propose --parts --source --out --from-config <config> [--keypoints <file> [--person <id>]]` | draw and LINT the config's current bones (by the joints too, given `--keypoints`); proposes nothing, so takes only these flags (not `--full`, `--head`, `--cloth`, `--write-config`, `--wrist-snap`, `--grid-rule`, `--only-missing` or `--compare`) |
-| `compare --left <file> --right <file> [--map <bonemap.json>]` | compare two skeletons — a config, a proposal or a `rig.json` — bone by bone: origin, parent, tip, length and direction per pair, the bones neither side pairs, the required ones missing, and each side's roles read off the spec; no frame is guessed, and nothing pairs by resemblance (`propose --compare` reads origins only) |
-| `rig --config --parts --out [--idle-keys ctl\|direct]` | author `rig.json` + `motion.json`, written only after rig-c's gate is green; each mesh is in the mode its config entry names — `grid` (the lattice, what `propose` writes), `contour` (the traced outline with declared interior points) or `auto` (the contour mesh at alpha 1 and above, reduced and locally refined by rig-c's `reduceMesh` under the author's declared bounds, written only when its motion against the unreduced source on the idle passes the author's `motion` bounds through rig-c's `compareMeshesInMotion`; [AUTHORING §3](docs/AUTHORING.md)); every chain link is turned along its chain and carries its `length`, so a physics constraint added later has a lever, with every offset under it in the turned frame so nothing moves; `--idle-keys` says whether the idle's keys on mesh-driving bones go through `<bone>_ctl` parents (default) or stay on the bones with `invariants.idleDrivesMeshes` declared; the config's `constraints` go to rigc as written, and a two-bone ik over keyed links needs `--idle-keys direct` (on `rig` or `build`) |
-| `check --rig --out [--parts] [--source] [--requirements]` | build packed, gated under `rig-play`, render the idle, measure seam, loop and the six judgement lines (mesh texture stretch among them, from the idle's `render --geometry`), and report the recomposite's holes from `parts.json`; on a rig spec with no `parts.json` or no `idle` (a merged rig, issue #77) the gate still runs and every line that needs the missing input says SKIP by name; `--source <painting.png>` adds `SETUP_POSE_VS_SOURCE`, the setup pose against the painting by assemble's recomposite figures; `--requirements <scene.json>` measures what a scene declares of the motion — a contact, a follow fraction, an aim, a joint range, a mesh's stretch, the seam between two parts over the motion — each against the author's own bar, from rig-c's posed frames, one line each, PASS, FAIL or NOT MEASURABLE (AUTHORING §7, *Declared requirements*) |
-| `loop --frames <dir> --out <file.gif \| file.png> [--palette]` | encode a rendered idle as a looping GIF, lossless APNG, or indexed APNG (`--palette`) |
-| `build --config --source --full --head --out [--seam] [--project] [--loop] [--lead-in <periods>] [--requirements] [--seam-pairs] [--keep-stills] [--idle-keys ctl\|direct]` | assemble, rig and check in one process, stopping at the first refusal; `--requirements`, `--seam-pairs` and `--keep-stills` are forwarded to check, `--idle-keys` to rig; `--lead-in` (with `--loop`) encodes the loop from the last of n + 1 idle periods played back to back, for a rig whose physics does not end where the render starts it |
-| `compose --scene <scene.json> --out [--requirements] [--accept]` | bind several characters' green builds into one rig (or, under `--accept`, builds failing only the bars named — for looking, not shipping): every name prefixed `<id>:` under one shared root, each character's offset added at its first-level bones, an optional background plate (its provenance recorded, judged by nothing) drawn first, and the draw order between the characters' slots as the scene file declares it — nothing inferred, nothing scaled; gated through rig-c as `rig` is, then checked ([AUTHORING §7](docs/AUTHORING.md), *Composing several characters*) |
-| `mesh-draft --config <json> --parts <dir> --out <dir>` | draft contour meshes for configured lattices, keeping each only where it holds against its lattice through rig-c; write the revised config and measurement report |
-| `mesh-stats --config <json> --parts <dir>` | print each configured mesh's vertex and triangle counts and their total through the rig stage's construction; write nothing |
-| `painting --keypoints <json> [--person <id>] <png>` | before See-through, read the painting against its declared joints and refuse named background, joint or limb-gap problems; write nothing |
-| `remesh --rig <dir> --config <json> --parts <dir> --part <name> --out <dir>` | with exactly one of `--mesh <entry.json>` or `--delta <mesh-edit.json>`, re-fit one part of a gated rig into a fresh revision, preserving the input |
-| `retune --rig <dir> --config <json> --parts <dir> --out <dir>` | splice the config's constraints and idle onto a gated rig in a fresh revision, carrying its attachments over as bytes |
-| `guide <RULE \| §<n> \| §<n>.<m> \| §<n>.<m>.<k>>` | print the one row of [docs/AUTHORING.md](docs/AUTHORING.md) that names a rule (a refusal and the bar it enforces, `CHECK_<LINE>` and `<LINE>`, print together), or one section, `###` subsection or `####` under it, read from the installed file when it runs |
-
-`rig-parts --help` has every flag. Exit codes: 0 done, 1 input refused (every
-reason is a FAIL line), 2 a usage error or a command this version does not implement.
-Every FAIL line ends with `(see rig-parts guide <RULE>)`, the command that prints the
-guide's row for that rule, and each row is anchored on the web as
-`docs/AUTHORING.md#<RULE>`.
-
-What 1.0.0 holds stable — these commands and their flags, the config
-fields, the files a build writes and their spec ids, the environment, and what this
-package relies on in rig-c — and what is not, is [docs/STABILITY.md](docs/STABILITY.md).
-Coming from 0.16.0: [docs/MIGRATION.md](docs/MIGRATION.md).
-
-`--write-config <config.json>` saves the proposals above into an existing
-regular config file: `seethrough.head_box`, `assemble.plan` plus
-`assemble.extend_below_crop`, or the present config sections of an ordinary
-proposal. The [neck draft](docs/AUTHORING.md#a-neck-that-moves-on-its-own)
-(`propose … --full --head --write-config`) is another writer: for an existing
-`turn.body` config with one neck plan row, it selects the full-run neck, drafts a
-rigid unit and its depth, and reassembles parts under `<out>/rig`.
-For `assemble --propose-plan`, the destination must name `--config`
-itself; a different destination is a usage error. Other fields and absent optional
-sections remain; proposal notes are not copied. Changed whole values are spliced
-into the original text, preserving untouched bytes. Stage loaders validate the candidate, including `proposed_rig_scale`,
-before atomic replacement. Relative paths keep the config's directory as their
-base. Changes are listed on stderr; the head-box and plan JSON on stdout remain.
-An identical update leaves bytes and mtime untouched. Without the flag no config
-is changed. This commits the config file, not a transaction across the proposal
-artifacts.
-
-With `--cloth <config.json>`, the flag requires a **new** destination and applies
-the recipe's entry ownership: recipe-owned entries are spliced into the cloth
-config while hand entries and unrelated text survive; conflicts are refused.
-The destination must also be separate from all four artifacts under `--out`:
-`proposal.json`, `basis.json`, `render/landmarks.png`, `render/landmarks_head.png`.
-Aliases, including directory symlinks and hardlinks, count as collisions too.
-Fresh output is published without overwriting a file created while the command
-runs. Its already-checked splice text may be a partial config; it is not passed
-through the full-config loader. If removing the staged temporary fails after
-publication, the error may accompany an already-published complete config.
-`--from <previous.json>` retains the previous-recipe comparison.
-With `--only-missing` (issue #671), an ordinary proposal's `--write-config` adds
-only `meshes.<part>` or `regions.<part>` for each proposed part the config
-attaches by neither, entry by entry, and, for a part the 1.37.0 arm split makes
-(`full:drape-<s>`, `full:hand-<s>`) that `assemble.plan` does not name, its plan
-row beside the arm's row; every existing row and entry and every other byte
-stays as read, and nothing else of the proposal is written. The candidate passes
-the full loader first, so an entry on a bone the config does not declare is
-refused naming the part and the bone; nothing missing leaves bytes and mtime
-untouched. It is the upgrade path for a config proposed before the 1.37.0 arm
-split ([MIGRATION](docs/MIGRATION.md#after-1370-merged-arm-layers-are-split-issue-490)),
-and a usage error with `--head-box`, `--cloth` or `--from-config`.
-`--from-config` proposes nothing and cannot be combined with `--write-config`.
-[AUTHORING §4](docs/AUTHORING.md#4-the-command-order) describes all four modes.
+| `inputs` | [Prepare the two See-through input images](docs/AUTHORING.md#command-reference) |
+| `comfy` | [Drive an optional ComfyUI painting or layer job](docs/AUTHORING.md#command-reference) |
+| `layers` | [Inspect wrapper layers or a PSD](docs/AUTHORING.md#command-reference) |
+| `sheet` | [Make a contact sheet](docs/AUTHORING.md#command-reference) |
+| `assemble` | [Merge layers into measured parts](docs/AUTHORING.md#command-reference) |
+| `propose` | [Draft or inspect a character config](docs/AUTHORING.md#command-reference) |
+| `compare` | [Compare two skeletons by name](docs/AUTHORING.md#command-reference) |
+| `rig` | [Author gated rig and motion specs](docs/AUTHORING.md#command-reference) |
+| `check` | [Build, render and measure a rig](docs/AUTHORING.md#command-reference) |
+| `loop` | [Encode rendered frames as GIF or APNG](docs/AUTHORING.md#command-reference) |
+| `build` | [Assemble, rig and check in one process](docs/AUTHORING.md#command-reference) |
+| `compose` | [Combine character builds into a scene](docs/AUTHORING.md#command-reference) |
+| `mesh-draft` | [Draft and compare contour meshes](docs/AUTHORING.md#command-reference) |
+| `mesh-stats` | [Count mesh vertices and triangles](docs/AUTHORING.md#command-reference) |
+| `painting` | [Check a painting against declared joints](docs/AUTHORING.md#command-reference) |
+| `remesh` | [Revise one mesh in a gated rig](docs/AUTHORING.md#command-reference) |
+| `retune` | [Revise constraints and idle in a gated rig](docs/AUTHORING.md#command-reference) |
+| `guide` | [Read the installed authoring reference](docs/AUTHORING.md#command-reference) |
+
 
 ## What it does not do
 
@@ -539,15 +463,7 @@ selftest and CI do; `check.json`'s `rigc_entry` records which one gated a build.
 
 ## Licence posture
 
-rig-parts is MIT. It writes rig-c's input, and rig-c writes Spine skeleton data. If a
-product integrates a Spine Runtime to play that data, the integration is under Esoteric
-Software's Spine Runtimes License: permitted under Section 2 of the Spine Editor License
-Agreement, or otherwise on the condition that each user of the product obtains their own
-Spine Editor license. What those terms turn on is the integration, as rig-c's
-[NOTICE.md](https://github.com/rig-c/core/blob/main/NOTICE.md) states it, not the data as
-a file. Neither package installs `spine-core`; this repository uses it in development,
-for the round trip in its selftest and CI. [NOTICE.md](NOTICE.md) records that chain and every other
-third-party term this package touches, See-through's included.
+MIT; see [NOTICE.md](NOTICE.md) for third-party terms and the Spine runtime licence posture.
 
 ## Development
 
@@ -579,43 +495,14 @@ records the generated default-cap case and its preservation controls.
 practice, [RELEASING.md](RELEASING.md) the cut, [docs/STABILITY.md](docs/STABILITY.md)
 the interface it holds.
 
-## Licence
-
-MIT — see [LICENSE](LICENSE). Third-party terms: [NOTICE.md](NOTICE.md).
+## Depth-driven rigging
 
+See the [depth-driven rigging reference](docs/AUTHORING.md#depth-driven-rigging) for sampled head and body turns and unit-depth precedence.
 
 ### Per-layer depth input
 
-`config.depth` explicitly enables scalar input. Without it, `depth_filename`
-is a legacy hint: no depth-file I/O, validation, fetch, reference or output is
-activated, even when files or in-memory sheets exist. Active See-through sheets
-are read as opaque grayscale source data. Declare positive finite `depth.zScale`;
-eight bits do not supply world units. See-through far-high encoding is explicitly `near: "black"`. User
-per-layer/run-canvas fallbacks declare image, near and zScale themselves; a
-missing declared file is an error, not a fallback. The ordering median remains
-separate, and its agreement reading cannot certify an image's polarity.
-
-Assembly emits registered part sheets and references; rig emits PAD4 sheets and
-`depth_sheets.json`. Since 1.68.0 (#777), [config.turn.roles](docs/AUTHORING.md#3-configjson-field-by-field)
-uses depth sheets for 2.5D head turns with grid or authored weighted surfaces and `yaw_dial`/`pitch_dial`
-controls; see [`CONFIG_TURN_ROLE_UNKNOWN`](docs/AUTHORING.md#CONFIG_TURN_ROLE_UNKNOWN)
-and [`CONFIG_TURN_SURFACE_REQUIRED`](docs/AUTHORING.md#CONFIG_TURN_SURFACE_REQUIRED).
-`turn.body.roles` adds independent body yaw. A weighted mesh declared as
-`"surface"` in either group and blending head and torso bones receives both
-fields in proportion to its skin weights. Inside the existing setup alpha
-overlap with a single-group neighbour, a blended attachment's vertex takes
-that neighbour's existing emitted triangle field at its setup position (#804), without changing skin weights,
-setup or idle. A `motion.blink.still` unit neighbour supplies both emitted
-pieces, each on its own bone and resolved depth; transparent padding does not
-let either piece lend its field to the other's art (#807). Missing emitted
-split support is refused by name. Conflicting neighbour groups are refused by name. Each sibling island takes only its
-own group; parts without a blended attachment keep their existing role behavior
-and output bytes. Unlisted meshes do not consume turn depth sheets. See the
-[blended surface contract](docs/AUTHORING.md#per-layer-depth-sheets-773).
-This copies the field at vertices; different triangle partitions can still
-differ between vertices. The [corrected #804 acceptance](https://github.com/rig-c/parts/issues/804#issuecomment-6478778123)
-checks vertex correspondence and reports those residuals per fixture; the
-contract records the measured grid residual and preserves its seam readings.
-No-image builds keep the legacy output bytes. `comfy seethrough --config <file> --depth-run <full|head>`
-uses the same opt-in; its default captures art only. Standalone authored part
-references remain active declarations. See [the input contract and refusals](docs/AUTHORING.md#per-layer-depth-sheets-773).
+See the [per-layer depth input contract](docs/AUTHORING.md#per-layer-depth-input) for opt-in sheets, calibration and their consumers.
+
+## Licence
+
+MIT — see [LICENSE](LICENSE). Third-party terms: [NOTICE.md](NOTICE.md).

package/docs/AUTHORING.md

@@ -70,6 +70,29 @@ model stack. The wrapper README and the adapter graph use different node names
 and depth-model identifiers; [the adapter notes](../README.md#the-optional-comfyui-adapter)
 name the graph actually sent.
 
+### See-through head-run source reading
+
+**The head run is needed on every route that was read.** See-through's model
+already separates the head in a second stage of its own: it crops the head the
+first stage found, runs the face tags on that crop at the same `resolution`, and
+pastes the result back **resized to the full image's scale**. So the face comes
+back at the full run's pixel density whichever route ran it, and the separate
+head run on `st_input_head.png` is what gives the eyes more pixels
+(read on 2026-09-28 at see-through `a25a549` and wrapper 0.5.0 `98d754b`):
+
+- *Hugging Face Space* — the same two-stage code, with `resolution` capped at
+  1280 (768 by default): the head run is still needed.
+- *ModelScope demo* — its code was not read, so what the head run adds on that
+  route has not been measured.
+- *Upstream CLI* — the `.psd` frame is the `resolution`-sided square the first
+  stage ran on (1280 by default), and the head stage is pasted into it at that
+  scale: the head run is still needed.
+- *ComfyUI wrapper* — `SeeThrough_GenerateLayers` runs both stages with no input
+  to change the second, at most `resolution` 2048, which on the examples' 2432 px
+  square is 1.19 source px per layer px against 0.77 and 0.47 for their head
+  crops; at the 1024 the examples ran, the full run's right eye white is 22×13 px
+  and the head run's 60×38: the head run is still needed.
+
 ## 2. The folder
 
 Nothing in rig-parts requires a layout; every command takes paths. The one the
@@ -3608,6 +3631,90 @@ artifacts under `--out`: `proposal.json`, `basis.json`, `render/landmarks.png` a
 existing hardlinks are refused before artifact output; the ordinary mode names
 `CONFIG_WRITE_TARGET`, and the cloth mode `PROPOSE_WRITE_CONFIG_FRESH`.
 
+### Command reference
+
+| command | does |
+| --- | --- |
+| `inputs --source <png> --config <json> --out <dir>` | the two images See-through is fed: the painting on a white square, and the head box's crop once the config has one |
+| `comfy paint --config --out [--host]` | optional: generate the painting on a ComfyUI box from the config's `generation` block |
+| `comfy seethrough --image --out [--host]` | optional: run the ComfyUI See-through wrapper on one image and write the form `layers` reads |
+| `layers <dir \| layers.json \| file.psd>` | keep the existing columns (`opaque_px` still means alpha >8) and append source-alpha boxes `drawn(a>8)` / `opaque(a>=250)` with exclusive right/bottom; name absent boxes, report the existing body-group union height at **CORE_ALPHA (>=250)** in **input-canvas px**, and show its >8 union separately; no anatomical height, ownership/erosion or painting registration is inferred ([units and rig-scale guidance](AUTHORING.md#4-the-command-order)) |
+| `sheet --source <png> --layers <path>… --out <png>` | a labelled contact sheet of the painting and every layer or part |
+| `assemble --propose-plan … [--write-config <config>]` | propose `assemble.plan` and `extend_below_crop` from the two runs, leaving out an implausible layer with a note naming the rule, naming in a note any full-run body no planned part covers, and naming every layer no row takes with why (empty, taken from the other run only, a plausibility rule; `nose`, never planned, with the row that lets `propose` read the head's pitch) |
+| `assemble --source --full --head --config --out [--seam] [--project]` | merge the two runs into rig-space parts, `parts.json`, the recomposite and its error map, and list the uncovered holes |
+| `propose --head-box --full <run> --canvas WxH [--no-back-hair] [--write-config <config>]` | propose `seethrough.head_box` from the full run, held inside the painting; `--no-back-hair` leaves the back-hair layer out of that proposal |
+| `propose --parts --source --out [--compare <config>] [--write-config <config> [--only-missing]]` | propose bones, meshes, regions and an idle; draw the overlay; print, per bone, which check read it or that none did and why (its role, its kind of segment), and write `basis.json` beside the proposal — what each bone rests on (a joint, a part's mask, a ratio, other bones) and, with `--compare`, whether the config's bone differs |
+| `propose … --keypoints <file> [--person <id>]` | read a posed figure's joints from one explicit file (space, image size, people, each joint observed, occluded or missing, its source): a joint with a position places the neck, hip, chest or a sleeve chain as given, a note says how every joint was used or which rule stood in, and LINT reads the torso and sleeves along the joints instead of by screen y ([AUTHORING §3](AUTHORING.md)) |
+| `propose … --full <run> --head <run> --write-config <config>` | [draft an independent neck](AUTHORING.md#a-neck-that-moves-on-its-own) in an existing sampled body turn and reassemble its full-run source under `<out>/rig` |
+| `propose … --grid-rule figure\|part` | how each drafted lattice's spacing is chosen: `figure` (the default) one spacing for the figure, round(H / 37) rig px, a part already coarser keeping its own, with a note on its calibration and cost; `part` the reference's rule, a tenth of the part's short side (the oracle examples are proposed under it) |
+| `propose --parts --source --out --from-config <config> [--keypoints <file> [--person <id>]]` | draw and LINT the config's current bones (by the joints too, given `--keypoints`); proposes nothing, so takes only these flags (not `--full`, `--head`, `--cloth`, `--write-config`, `--wrist-snap`, `--grid-rule`, `--only-missing` or `--compare`) |
+| `compare --left <file> --right <file> [--map <bonemap.json>]` | compare two skeletons — a config, a proposal or a `rig.json` — bone by bone: origin, parent, tip, length and direction per pair, the bones neither side pairs, the required ones missing, and each side's roles read off the spec; no frame is guessed, and nothing pairs by resemblance (`propose --compare` reads origins only) |
+| `rig --config --parts --out [--idle-keys ctl\|direct]` | author `rig.json` + `motion.json`, written only after rig-c's gate is green; each mesh is in the mode its config entry names — `grid` (the lattice, what `propose` writes), `contour` (the traced outline with declared interior points) or `auto` (the contour mesh at alpha 1 and above, reduced and locally refined by rig-c's `reduceMesh` under the author's declared bounds, written only when its motion against the unreduced source on the idle passes the author's `motion` bounds through rig-c's `compareMeshesInMotion`; [AUTHORING §3](AUTHORING.md)); every chain link is turned along its chain and carries its `length`, so a physics constraint added later has a lever, with every offset under it in the turned frame so nothing moves; `--idle-keys` says whether the idle's keys on mesh-driving bones go through `<bone>_ctl` parents (default) or stay on the bones with `invariants.idleDrivesMeshes` declared; the config's `constraints` go to rigc as written, and a two-bone ik over keyed links needs `--idle-keys direct` (on `rig` or `build`) |
+| `check --rig --out [--parts] [--source] [--requirements]` | build packed, gated under `rig-play`, render the idle, measure seam, loop and the six judgement lines (mesh texture stretch among them, from the idle's `render --geometry`), and report the recomposite's holes from `parts.json`; on a rig spec with no `parts.json` or no `idle` (a merged rig, issue #77) the gate still runs and every line that needs the missing input says SKIP by name; `--source <painting.png>` adds `SETUP_POSE_VS_SOURCE`, the setup pose against the painting by assemble's recomposite figures; `--requirements <scene.json>` measures what a scene declares of the motion — a contact, a follow fraction, an aim, a joint range, a mesh's stretch, the seam between two parts over the motion — each against the author's own bar, from rig-c's posed frames, one line each, PASS, FAIL or NOT MEASURABLE (AUTHORING §7, *Declared requirements*) |
+| `loop --frames <dir> --out <file.gif \| file.png> [--palette]` | encode a rendered idle as a looping GIF, lossless APNG, or indexed APNG (`--palette`) |
+| `build --config --source --full --head --out [--seam] [--project] [--loop] [--lead-in <periods>] [--requirements] [--seam-pairs] [--keep-stills] [--idle-keys ctl\|direct]` | assemble, rig and check in one process, stopping at the first refusal; `--requirements`, `--seam-pairs` and `--keep-stills` are forwarded to check, `--idle-keys` to rig; `--lead-in` (with `--loop`) encodes the loop from the last of n + 1 idle periods played back to back, for a rig whose physics does not end where the render starts it |
+| `compose --scene <scene.json> --out [--requirements] [--accept]` | bind several characters' green builds into one rig (or, under `--accept`, builds failing only the bars named — for looking, not shipping): every name prefixed `<id>:` under one shared root, each character's offset added at its first-level bones, an optional background plate (its provenance recorded, judged by nothing) drawn first, and the draw order between the characters' slots as the scene file declares it — nothing inferred, nothing scaled; gated through rig-c as `rig` is, then checked ([AUTHORING §7](AUTHORING.md), *Composing several characters*) |
+| `mesh-draft --config <json> --parts <dir> --out <dir>` | draft contour meshes for configured lattices, keeping each only where it holds against its lattice through rig-c; write the revised config and measurement report |
+| `mesh-stats --config <json> --parts <dir>` | print each configured mesh's vertex and triangle counts and their total through the rig stage's construction; write nothing |
+| `painting --keypoints <json> [--person <id>] <png>` | before See-through, read the painting against its declared joints and refuse named background, joint or limb-gap problems; write nothing |
+| `remesh --rig <dir> --config <json> --parts <dir> --part <name> --out <dir>` | with exactly one of `--mesh <entry.json>` or `--delta <mesh-edit.json>`, re-fit one part of a gated rig into a fresh revision, preserving the input |
+| `retune --rig <dir> --config <json> --parts <dir> --out <dir>` | splice the config's constraints and idle onto a gated rig in a fresh revision, carrying its attachments over as bytes |
+| `guide <RULE \| §<n> \| §<n>.<m> \| §<n>.<m>.<k>>` | print the one row of [docs/AUTHORING.md](AUTHORING.md) that names a rule (a refusal and the bar it enforces, `CHECK_<LINE>` and `<LINE>`, print together), or one section, `###` subsection or `####` under it, read from the installed file when it runs |
+
+`rig-parts --help` has every flag. Exit codes: 0 done, 1 input refused (every
+reason is a FAIL line), 2 a usage error or a command this version does not implement.
+Every FAIL line ends with `(see rig-parts guide <RULE>)`, the command that prints the
+guide's row for that rule, and each row is anchored on the web as
+`docs/AUTHORING.md#<RULE>`.
+
+What 1.0.0 holds stable — these commands and their flags, the config
+fields, the files a build writes and their spec ids, the environment, and what this
+package relies on in rig-c — and what is not, is [docs/STABILITY.md](STABILITY.md).
+Coming from 0.16.0: [docs/MIGRATION.md](MIGRATION.md).
+
+### Writing proposed config fields
+
+`--write-config <config.json>` saves the proposals above into an existing
+regular config file: `seethrough.head_box`, `assemble.plan` plus
+`assemble.extend_below_crop`, or the present config sections of an ordinary
+proposal. The [neck draft](AUTHORING.md#a-neck-that-moves-on-its-own)
+(`propose … --full --head --write-config`) is another writer: for an existing
+`turn.body` config with one neck plan row, it selects the full-run neck, drafts a
+rigid unit and its depth, and reassembles parts under `<out>/rig`.
+For `assemble --propose-plan`, the destination must name `--config`
+itself; a different destination is a usage error. Other fields and absent optional
+sections remain; proposal notes are not copied. Changed whole values are spliced
+into the original text, preserving untouched bytes. Stage loaders validate the candidate, including `proposed_rig_scale`,
+before atomic replacement. Relative paths keep the config's directory as their
+base. Changes are listed on stderr; the head-box and plan JSON on stdout remain.
+An identical update leaves bytes and mtime untouched. Without the flag no config
+is changed. This commits the config file, not a transaction across the proposal
+artifacts.
+
+With `--cloth <config.json>`, the flag requires a **new** destination and applies
+the recipe's entry ownership: recipe-owned entries are spliced into the cloth
+config while hand entries and unrelated text survive; conflicts are refused.
+The destination must also be separate from all four artifacts under `--out`:
+`proposal.json`, `basis.json`, `render/landmarks.png`, `render/landmarks_head.png`.
+Aliases, including directory symlinks and hardlinks, count as collisions too.
+Fresh output is published without overwriting a file created while the command
+runs. Its already-checked splice text may be a partial config; it is not passed
+through the full-config loader. If removing the staged temporary fails after
+publication, the error may accompany an already-published complete config.
+`--from <previous.json>` retains the previous-recipe comparison.
+With `--only-missing` (issue #671), an ordinary proposal's `--write-config` adds
+only `meshes.<part>` or `regions.<part>` for each proposed part the config
+attaches by neither, entry by entry, and, for a part the 1.37.0 arm split makes
+(`full:drape-<s>`, `full:hand-<s>`) that `assemble.plan` does not name, its plan
+row beside the arm's row; every existing row and entry and every other byte
+stays as read, and nothing else of the proposal is written. The candidate passes
+the full loader first, so an entry on a bone the config does not declare is
+refused naming the part and the bone; nothing missing leaves bytes and mtime
+untouched. It is the upgrade path for a config proposed before the 1.37.0 arm
+split ([MIGRATION](MIGRATION.md#after-1370-merged-arm-layers-are-split-issue-490)),
+and a usage error with `--head-box`, `--cloth` or `--from-config`.
+`--from-config` proposes nothing and cannot be combined with `--write-config`.
+[AUTHORING §4](AUTHORING.md#4-the-command-order) describes all four modes.
 ## 5. After each stage: what to read
 
 | stage | read | green looks like | a common red |
@@ -4994,7 +5101,7 @@ and stay absent).
 | <a id="DEPTH_SOURCE_AMBIGUOUS"></a>`DEPTH_SOURCE_AMBIGUOUS` | writer/user or layer/canvas declarations overlap | select one authoritative route explicitly |
 | <a id="DEPTH_SOURCE_RESOLVES"></a>`DEPTH_SOURCE_RESOLVES` | user key names no source layer | use the exact source tag in the selected run |
 | <a id="DEPTH_SOURCE_BASE"></a>`DEPTH_SOURCE_BASE` | a direct assembler caller supplied user paths without config base | pass the actual config-directory base |
-| <a id="DEPTH_PART_SUPPORT"></a>`DEPTH_PART_SUPPORT` | exact copied/generated material lacks source depth or compatible units | provide a declared scalar source/registration; do not infer or fill depth |
+| <a id="DEPTH_PART_SUPPORT"></a>`DEPTH_PART_SUPPORT` | exact copied/generated material lacks source depth or compatible units | provide a declared scalar source/registration; do not infer or fill depth; declare the part `unit` with an explicit authored `unitDepths` value when its material includes authored under-art |
 | <a id="PARTS_DEPTH_REFERENCE"></a>`PARTS_DEPTH_REFERENCE` | persisted fields/provenance violate the reference shape | restore image, near, positive zScale and exact source records |
 | <a id="DEPTH_SILHOUETTE_SIZE_MISMATCH"></a>`DEPTH_SILHOUETTE_SIZE_MISMATCH` | `extendDepthSilhouette` or `padTurnDepthSheet` received a source depth sheet and artwork raster of different dimensions | supply the part's matching unpadded depth sheet and artwork raster |
 | <a id="CONFIG_TURN_COUNTER_RANGE"></a>`CONFIG_TURN_COUNTER_RANGE` | `config.turn.counter` (or `config.turn.body.counter`) is outside `[0, 1]` | supply a non-negative rear counter-translation fraction in `[0, 1]` |
@@ -5011,6 +5118,7 @@ and stay absent).
 | <a id="RIG_TURN_SURFACE_OVERLAP_DEPTH"></a>`RIG_TURN_SURFACE_OVERLAP_DEPTH` | same-group overlap neighbours demand incompatible emitted offsets at one target setup point | separate the conflicting support or provide coincident neighbour fields; the refusal names the fields and target vertex |
 | <a id="RIG_TURN_SURFACE_MESH_BINDINGS"></a>`RIG_TURN_SURFACE_MESH_BINDINGS` | an authored surface mesh has unresolved/nonclosing weights or shares a frame moved by a unit/rear turn carrier; declared stop draw aliases resolve to their links for setup sampling | provide weighted bindings closing at 1 in the authored frame; `<link>_d` resolves only for links declared in `config.stops`; use independent chains for parts with different roles |
 | <a id="RIG_TURN_SURFACE_MESH_ATTACHMENT"></a>`RIG_TURN_SURFACE_MESH_ATTACHMENT` | a surface mesh has an alternate drawing without its own registered depth sampling frame | use the base attachment; explicit islands retain their own slot, attachment and bindings |
+| <a id="RIG_TURN_BODY_UNCOVERED"></a>`RIG_TURN_BODY_UNCOVERED` | **Warning:** a shown part without a body role overlaps a moved `turn.body` surface at setup alpha >= 128 and has different emitted endpoint displacement | declare the intended body role and inspect both endpoints; no role or depth is inferred |
 | <a id="RIG_TURN_SURFACE_DEPTH_REQUIRED"></a>`RIG_TURN_SURFACE_DEPTH_REQUIRED` | a part with role `"surface"` in `config.turn.roles` or `config.turn.body.roles` carries no depth sheet in `parts.json` | run `assemble` with `config.depth` or provide `<part>_depth.png` in `parts.json` |
 | <a id="RIG_TURN_GRID_BUDGET"></a>`RIG_TURN_GRID_BUDGET` | a `"surface"` grid exceeds 2,400 triangles on one slot or 4,000 triangles across all `"surface"` slots | lower `config.turn.grid` / `config.turn.body.grid` `[cols, rows]` within the per-slot and total budgets |
 | <a id="RIG_TURN_HEAD_BONE"></a>`RIG_TURN_HEAD_BONE` | `buildRig` found no `"head"` (or body turn root) bone when emitting 2.5D turn carriers | declare `"head"` (or the body turn root bone) in `config.bones` |
@@ -5913,6 +6021,71 @@ on a bone of length 0 are NOT MEASURABLE and the run is not PASS (`CK68`–`CK79
 frame the slide peaks; a seam on a rig with no `parts.json` is refused before anything
 is built (`CK83`–`CK85`, `RQ30`–`RQ35`).
 
+### Art joints on a fixed skeleton
+
+When art is fitted to a skeleton whose setup must stay fixed, declare
+`fixed_skeleton` in the existing `--requirements` file (issue #880):
+
+```json
+{
+  "spec": "spine-parts-requirements/1",
+  "fps": 12,
+  "requirements": [],
+  "fixed_skeleton": {
+    "source": "independent joint measurements on the fitted art",
+    "within_px": 4,
+    "joints": [
+      { "name": "shoulder", "bone": "upper_arm", "at": [26, 57] }
+    ]
+  }
+}
+```
+
+The block explicitly identifies this as a fixed-skeleton comparison; a generation
+control pose does not. `source` is required nonempty provenance text, recorded
+without interpretation. Each `at` is an independently measured point on the art
+**as placed on the rig's stage**, in stage pixels from its top-left, x right and y
+down, the same space as a requirement's `target.stage`. Convert painting/source
+coordinates through the actual placement before declaring them: raw source pixels,
+bone-local offsets and normalized coordinates are not stage pixels. Each nonempty
+`name` is unique and each `bone` explicitly names its matching bone origin in
+`rig.json`. No anatomical names, hidden joints, correspondences or positions are
+inferred; only the listed measurements are covered. An unmeasured joint must not
+be supplied as the bone's own position.
+
+`check` uses the existing setup-still renderer, requesting `--geometry`, and reads
+`geometry.json`'s `setup.bones` through its existing geometry reader. It converts
+the renderer's setup-world origin to stage pixels through the coordinate door;
+it never substitutes an animation's first frame or a bone's parent-local `x,y`.
+This also works for an external `rig.json` with no `parts.json` or idle. The
+Euclidean distance, art point and setup origin are printed **for every declared
+joint** and written to `check.json`'s `ART_JOINT_DISTANCE`, along with `source`,
+`instrument` and `within_px`. This is a setup-placement check, not a motion check
+or automatic detection of joints in an image.
+
+`within_px` is optional and, when present, must be finite and nonnegative. The
+example's `4` is an authored demonstration, not a calibrated or default tolerance.
+Distance **greater than** the declared limit fails; equality passes. Without a
+limit, the block and every joint are **SKIP**, with the measured distances and
+`within_px: null`; this line is excluded from measured bars and contributes no
+PASS. Other independent checks may still pass. With no `fixed_skeleton` block,
+this measurement adds no output or render call. `fps` and `requirements` remain
+required by the enclosing file; they do not change this setup measurement.
+
+| rule | change |
+| --- | --- |
+| <a id="CHECK_ART_JOINT_DISTANCE"></a>`CHECK_ART_JOINT_DISTANCE` | The named joint is farther from its setup bone origin than `fixed_skeleton.within_px`; the message gives distance and limit. Correct a wrong art measurement or bone correspondence, or supply art aligned to the fixed skeleton. Choose any changed limit explicitly from the consumer's requirement; bones and art are never moved by this check. |
+| <a id="CHECK_ART_JOINT_MEASURED"></a>`CHECK_ART_JOINT_MEASURED` | Supply a finite renderer setup origin and a finite measurable distance; missing geometry is never taken as zero. The existing `CHECK_GEOMETRY_FILE` refusal names missing/malformed geometry. |
+
+`REQUIREMENTS_FIELD` and `REQUIREMENTS_RESOLVES` cover malformed declarations:
+supply nonempty provenance and a nonempty joint list, unique joint names, finite
+`[x, y]` points, known bone names and an explicit valid limit or omit the limit.
+Unknown fields are refused.
+
+| line | measures | bar | SKIP |
+| --- | --- | --- | --- |
+| <a id="ART_JOINT_DISTANCE"></a>`ART_JOINT_DISTANCE` | Each independently measured art joint versus its explicitly named bone's renderer setup origin, in stage pixels; printed and recorded per joint | distance <= the declared `fixed_skeleton.within_px`, with no rounding slack | no limit declared: every row and the block retain their distances as SKIP, never a pass; no declaration: no line |
+
 ## 8. What one character costs
 
 | step | reference-sample | reference-demo | source |
@@ -6216,6 +6389,62 @@ art. An authored `parts.json` depth reference remains an active standalone
 `rig` declaration even without config opt-in: its file/size/color/opacity
 guards still apply. With binding inactive there is no added reference, file or
 legacy-byte change. #773 adds no image generation, geometry or motion model.
+
+### Missing body-turn coverage
+
+`RIG_TURN_BODY_UNCOVERED` warns when a shown part without a
+`turn.body.roles` entry overlaps a moved body surface. It names both parts,
+both endpoint times, their actual emitted displacement vectors and the maximum
+relative displacement at a setup painting-pixel centre. Both drawings require
+alpha >= 128 and actual covering setup triangles; bounding boxes and transparent
+pixels alone do not count. Excluded alpha does not count. The diagnostic reads
+positive bindings in the declared torso subtree, excluding head/neck subtrees.
+Explicit body roles and bindings wholly inheriting an emitted body-turn carrier
+count as declared coverage; identical inherited motion needs no second role. Differences no larger than the producer's six-place
+encoding unit (0.000001 rig px) are ignored. This is a warning about a missing
+declaration, not an automatic seam verdict or a rule for limb crossings.
+
+Warnings belong to the stage report only. They add no rig, motion or PNG field
+and never assign a role, depth, binding or draw order. A part already bound to
+`chest` does not inherit a weighted topwear surface's per-vertex deform. Declare
+its actual intended role, then inspect setup, both turn endpoints and their diff;
+an explicit role alone does not establish that two drawings remain coincident.
+
+### Unit depth precedence
+
+For `"unit"` roles, a transported part's sheet is recorded and validated but is not
+necessarily the depth used to move its bone. `turn.unitDepths` (and the body
+map `turn.body.unitDepths`, which inherits the head map when omitted) uses
+calibrated world depths. An explicit `0` is a value, not a request to sample.
+With active depth binding, assembly skips scalar transport only when every declared turn group makes the part `unit` with explicit part or carried-bone `unitDepths` covering every still piece, records the resolved values in `provenance.depth` as `{kind: "authored-unit", values: [...]}`, and retains input-sheet validation and every implicit-unit or sampled-surface refusal.
+For each carried unit bone, the existing producer resolves depth in this order:
+
+1. `unitDepths.<part>`; when both names are present, the part entry wins.
+2. `unitDepths.<bone>`, using the carried bone's name.
+3. The primary surface's extended sheet at the unit's setup landmark. The
+   head group prefers the `face` surface, otherwise the first declared surface;
+   the body group uses its first declared surface. This depth is relative to
+   that surface's reference and the group's pivot. A unit mesh uses its child
+   landmarks, or its part centre when those landmarks are absent.
+4. Only if still unresolved, the unit's own sheet's opaque-art median. This
+   lower-level fallback is not an authoring switch: the documented config
+   reader requires a surface in each active group and supplies declared region
+   landmarks or a mesh sampling position. No documented configuration is
+   provided here to bypass primary sampling and select the own sheet instead.
+
+Outside or nonopaque primary support produces
+[`RIG_TURN_UNIT_DEPTH_SUPPORT`](#RIG_TURN_UNIT_DEPTH_SUPPORT), retains the
+extended primary sample, and does not select the own sheet. Removing all
+surfaces is refused by
+[`CONFIG_TURN_SURFACE_REQUIRED`](#CONFIG_TURN_SURFACE_REQUIRED).
+Consequently, removing `unitDepths` alone does not make an own-sheet change
+move a unit: primary-surface sampling can still mask it. In that case the own
+sheet remains in `depth_sheets.json` and its padded PNG, but is not consumed
+for that unit's turn geometry. Author an explicit calibrated `unitDepths`
+entry to control its rigid depth; change the primary surface only when that
+shared sampled field is what should change. A `"surface"` part's own sampled
+geometry is a separate consumer described above.
+
 ### Explicit source-derived waist pivot stage
 
 `withWaistPivot` is a pure, explicit candidate-stage operation over an already
@@ -6335,3 +6564,51 @@ they do not certify a new toolchain, input or packaging build. No tuning to meet
 | <a id="CONFIG_WAIST_NAME_FREE"></a>`CONFIG_WAIST_NAME_FREE` | The generated bone name already exists; declare an unused name | declare an unused name |
 | <a id="RIG_WAIST_DECLARATION"></a>`RIG_WAIST_DECLARATION` | Actual provenance, pair bindings or drawing ownership do not match the bounded declaration; supply the declared base two-bone mesh/rigid-region pair | supply the declared base pair |
 | <a id="RIG_WAIST_MOTION"></a>`RIG_WAIST_MOTION` | Imported tracks drive the generated waist frame; retain their original authored targets | retain the original authored targets |
+
+### Depth-driven rigging
+
+Registered per-part depth sheets drive sampled head yaw/pitch through
+`turn.roles` and independent body yaw through `turn.body.roles`. Region
+surfaces use depth-bearing grids; authored weighted surfaces keep their
+skinning and receive per-influence deform offsets sampled at setup positions.
+These controls are exercised on public synthetic fixtures. Unit parts use the
+[documented depth precedence](AUTHORING.md#unit-depth-precedence), so a
+recorded unit sheet does not by itself promise different turn geometry.
+See the [authoring contract](AUTHORING.md#per-layer-depth-sheets-773)
+and the [getting-started guide](https://github.com/rig-c/getting-started).
+
+### Per-layer depth input
+
+`config.depth` explicitly enables scalar input. Without it, `depth_filename`
+is a legacy hint: no depth-file I/O, validation, fetch, reference or output is
+activated, even when files or in-memory sheets exist. Active See-through sheets
+are read as opaque grayscale source data. Declare positive finite `depth.zScale`;
+eight bits do not supply world units. See-through far-high encoding is explicitly `near: "black"`. User
+per-layer/run-canvas fallbacks declare image, near and zScale themselves; a
+missing declared file is an error, not a fallback. The ordering median remains
+separate, and its agreement reading cannot certify an image's polarity.
+
+Assembly emits registered part sheets and references; rig emits PAD4 sheets and
+`depth_sheets.json`. Since 1.68.0 (#777), [config.turn.roles](AUTHORING.md#3-configjson-field-by-field)
+uses depth sheets for 2.5D head turns with grid or authored weighted surfaces and `yaw_dial`/`pitch_dial`
+controls; see [`CONFIG_TURN_ROLE_UNKNOWN`](AUTHORING.md#CONFIG_TURN_ROLE_UNKNOWN)
+and [`CONFIG_TURN_SURFACE_REQUIRED`](AUTHORING.md#CONFIG_TURN_SURFACE_REQUIRED).
+`turn.body.roles` adds independent body yaw. A weighted mesh declared as
+`"surface"` in either group and blending head and torso bones receives both
+fields in proportion to its skin weights. Inside the existing setup alpha
+overlap with a single-group neighbour, a blended attachment's vertex takes
+that neighbour's existing emitted triangle field at its setup position (#804), without changing skin weights,
+setup or idle. A `motion.blink.still` unit neighbour supplies both emitted
+pieces, each on its own bone and resolved depth; transparent padding does not
+let either piece lend its field to the other's art (#807). Missing emitted
+split support is refused by name. Conflicting neighbour groups are refused by name. Each sibling island takes only its
+own group; parts without a blended attachment keep their existing role behavior
+and output bytes. Unlisted meshes do not consume turn depth sheets. See the
+[blended surface contract](AUTHORING.md#per-layer-depth-sheets-773).
+This copies the field at vertices; different triangle partitions can still
+differ between vertices. The [corrected #804 acceptance](https://github.com/rig-c/parts/issues/804#issuecomment-6478778123)
+checks vertex correspondence and reports those residuals per fixture; the
+contract records the measured grid residual and preserves its seam readings.
+No-image builds keep the legacy output bytes. `comfy seethrough --config <file> --depth-run <full|head>`
+uses the same opt-in; its default captures art only. Standalone authored part
+references remain active declarations. See [the input contract and refusals](AUTHORING.md#per-layer-depth-sheets-773).

package/docs/STABILITY.md

@@ -80,6 +80,10 @@ command's flag union; `comfy paint` and `comfy seethrough` are checked separatel
 Required combinations within a mode remain the CLI's; the `cli` suite's controls
 read them from the help.
 
+The [command reference](AUTHORING.md#command-reference) describes each mode;
+[writing proposed config fields](AUTHORING.md#writing-proposed-config-fields)
+records the existing-file and fresh-file destinations and byte-preservation rules.
+
 ## The config contract
 
 `src/config.ts` is the schema and the loader, and
@@ -478,6 +482,22 @@ Assembly's optional part `depth` reference holds `image`, `near`, `zScale` and
 active binding. Persisted authored part references remain active for standalone
 rig reading regardless of config opt-in. `rig` adds padded measurement PNGs and the `rig-parts-depth-sheets/1`
 `depth_sheets.json` companion only with references (each output `part`, actual
-padded `size`, and `depth`; a still split names both slices). Current weighted meshes do
-not acquire a Core field or change geometry; #763 owns the generator consumer.
+padded `size`, and `depth`; a still split names both slices). Passive references
+add these companions without changing weighted geometry. Active `"surface"`
+roles in `turn.roles` and `turn.body.roles` consume registered sheets:
+region surfaces emit Core grid generators with `generator.depth`; authored
+weighted surfaces keep their topology and bindings and emit sampled per-influence
+inverse-bind deform offsets in motion, without adding a Core attachment depth
+field. Head yaw/pitch and independent body yaw use their existing turn groups.
+Blended surfaces retain the documented per-group masks and setup-overlap
+neighbour field rules in [AUTHORING](AUTHORING.md#per-layer-depth-sheets-773).
+`RIG_TURN_BODY_UNCOVERED` is a report-only warning for a shown torso part
+without a body role that has opaque setup-triangle overlap with a moved body
+surface and different emitted endpoint displacement. It names the part, surface,
+times, vectors and relative travel. Head/neck bindings, transparent/excluded
+alpha, explicit/inherited body roles and identical inherited motion are excluded as
+described in [AUTHORING](AUTHORING.md#missing-body-turn-coverage). It assigns
+no role or depth and changes no emitted file bytes.
+The unit-depth precedence and its primary-surface sampling are documented in
+[AUTHORING](AUTHORING.md#unit-depth-precedence).
 The separate ordering scalar is unchanged. No-image outputs retain legacy bytes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rig-parts",
-  "version": "1.83.1",
+  "version": "1.84.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": {
@@ -58,6 +58,7 @@
   "scripts": {
     "fetch-examples": "bash scripts/fetch-examples.sh",
     "selftest": "bun selftest.ts",
+    "check:readme": "bun scripts/readme_policy.ts",
     "selftest:pre": "bun selftest.ts --pre",
     "smoke": "bun scripts/install_smoke.ts",
     "typecheck": "bunx tsc --noEmit",