rig-parts 1.64.0 → 1.66.0

package/README.md

@@ -272,7 +272,7 @@ Use the graph's node classes and the host's `/object_info` when checking the ada
 ```sh
 rig-parts inputs --source painting.png --config config.json --out inputs   # st_input_full.png; the config needs assemble.rig_scale
 #    See-through on st_input_full.png (external, or `rig-parts comfy seethrough`) -> layers/full
-rig-parts layers layers/full                      # every layer: box, opaque px, depth, plausibility figures; WARN lines
+rig-parts layers layers/full                      # drawn(a>8)/opaque(a>=250) boxes, CORE body-group height in input-canvas px, WARNs
 rig-parts propose --head-box --full layers/full --canvas 1664x2432
 #    -> seethrough.head_box into config.json
 rig-parts inputs --source painting.png --config config.json --out inputs   # now st_input_head.png too
@@ -291,7 +291,8 @@ rig-parts propose --parts work/rig --source painting.png --out work
 #       (limbs only with --keypoints, constraints only with --cloth, turn only with --full/--head;
 #       a limbs block left out is refused next)
 rig-parts propose --parts work/rig --source painting.png --out work --from-config config.json
-#    -> LINT lines; exit 1 while any remain
+#    -> LINT lines; exit 1 while any remain (takes --parts, --source, --out, --from-config and optional --keypoints [--person] only;
+#       proposes nothing, so --full, --head, --cloth, --write-config, --wrist-snap, --grid-rule, --only-missing and --compare are refused)
 rig-parts build --config config.json --source painting.png --full layers/full --head layers/head --out out --loop
 #    -> read out/check/check.json; every FAIL line names what has to change
 ```
@@ -333,7 +334,7 @@ agent skill.
 | `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>` | print every layer of a decomposition: draw order, name, tag group, box, size, opaque pixels, depth, and its translucent, background and area figures; a `WARN` line for a layer `--propose-plan` will leave out |
+| `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 |
@@ -341,7 +342,7 @@ agent skill.
 | `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 … --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 … --from-config <config>` | draw and LINT the config's current bones (by the joints too, given `--keypoints`) |
+| `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*) |

package/cli.ts

@@ -28,7 +28,7 @@ import { GUIDE_DOC, type GuideAnswer, guideRule, guideSection } from './src/guid
 import { proposeHeadBox } from './src/headbox.ts';
 import { makeInputs } from './src/inputs.ts';
 import { idleKeysOf, isIdleKeys } from './src/rig.ts';
-import { depthSkipLine, exportLayers, figuresPhrase, hiddenLayerLine, implausibleRules, layerFigures, type LayerSet, layerSetDiff, pct, readLayers, readWrapperLayers, ruleSummary, templateLayerNames, templatePsdBytes, times } from './src/layers.ts';
+import { bodyCoreBox, bodyOpaqueBox, CORE_ALPHA, depthSkipLine, exportLayers, figuresPhrase, hiddenLayerLine, implausibleRules, layerCoreBox, layerFigures, layerOpaqueBox, type LayerSet, layerSetDiff, type OpaqueBox, OPAQUE_ALPHA_ABOVE, pct, readLayers, readWrapperLayers, ruleSummary, templateLayerNames, templatePsdBytes, times } from './src/layers.ts';
 import { checkImageSize, choosePerson, KEYPOINTS_SPEC, loadKeypoints, type RigJoints, toRigJoints } from './src/keypoints.ts';
 import { basisLines, branchSqueezeLine, checkProposal, compare, compareLines, DEFAULT_GRID_RULE, draftTurn, drawLandmarks, FIGURE_GRID_DIVISOR, FRINGE_STEP_PX, GRID_RULES, type GridRule, HIP_MIN_FRACTION, type DraftLintFinding, lint, lintLine, type PartSet, PROPOSAL_CONFIG_SECTIONS, proposalAsConfig, proposeWithBasis, readPartSet, serializeProposal, withTurn, WRIST_ON_PART_PX } from './src/propose.ts';
 import { BASIS_FILE, BASIS_SPEC, basisFile, basisLine, coverageLines, legChainChoice, serializeBasis } from './src/diagnostics.ts';
@@ -79,6 +79,11 @@ usage:
       where something covers it: listed apart, never drawn, never a part. An
       input with no depth (a PSD, or depth_median null on every layer, whose
       manifest order is then the draw order) prints one SKIP depth line.
+      Trailing boxes name both source-alpha cuts: drawn(a>8), and opaque
+      (a>=250, CORE_ALPHA). The legacy opaque_px still counts alpha above 8.
+      Right/bottom are exclusive, in INPUT-CANVAS px; absent boxes are named.
+      The body-group union height uses alpha >=250, with the >8 union shown
+      separately: no cleanup, ownership, anatomical height or painting map.
       Refuses, by name, a missing file, an unknown tag, a PNG whose
       size is not its box, and anything else outside the input contract —
       never a WARN.
@@ -268,9 +273,10 @@ usage:
 
   rig-parts propose --parts <dir> --source <painting.png> --out <dir> --from-config <config.json>
       Draw the config's CURRENT bones instead (<out>/render/landmarks_config.png
-      and _head) and LINT them (by the joints too, given --keypoints), with the
-      coverage lines after them; no ${BASIS_FILE}, as nothing is proposed.
-      Exits 1 when any LINT line is printed.
+      and _head) and LINT them (by the joints too, given --keypoints [--person]), with the
+      coverage lines after them; no ${BASIS_FILE}, as nothing is proposed (takes
+      --parts, --source, --out, --from-config and optional --keypoints [--person]
+      only). Exits 1 when any LINT line is printed.
 
   rig-parts propose … --write-config <config.json>
       Without --cloth, update an existing config with the whole proposal's
@@ -416,7 +422,8 @@ usage:
   rig-parts mesh-stats --config <config.json> --parts <dir>
       Print the vertices and triangles of every mesh the config states, as the
       rig stage would make them from the parts in --parts (the directory
-      holding parts.json and parts/<name>.png), and their total, in seconds:
+      holding parts.json and parts/ — work/rig from assemble --out work, or
+      out from build --out out), and their total, in seconds:
       the rig stage's own mesh construction, without rigc, without assemble
       and without check (issue #566). One line per mesh in parts.json's order,
       "mesh-stats: <part> — <mode> <V> vertices, <T> triangles" (mode lattice,
@@ -523,6 +530,7 @@ usage:
                     [--page-edges pot|free] [--pack-shape rect|polygon]
                     [--requirements <file.json>] [--seam-pairs] [--keep-stills]
                     [--set <name> | --all-sets] [--environment <schedule.json>]
+                    [--wind-band <spec.json>]
       Build, gate, render and measure a rig through rig-c's CLI (the rigc at
       node_modules/.bin/rigc, or on PATH). --rig holds rig.json and motion.json:
       a rig spec, which rigc build compiles, not a compiled skeleton.json.
@@ -671,6 +679,14 @@ usage:
       response or no band is SKIP; no pair or animation gives no worlds.
       Nonphysics output is unchanged. In rig-play environment(null) returns
       to the default world, not still air (AUTHORING, Physics seam environments).
+      --wind-band <spec.json> sweeps steady wind [x, 0], gravity [0, 1] at t = 0
+      over [min, max] in step increments through rigc render --seam (spec
+      "rig-parts-wind-band/1"; every field required: spec, min, max, step, fps,
+      max_gap, max_ghost, pairs; refused by CHECK_WIND_BAND before anything is
+      written). Prints WIND_BAND: REPORTED with the steady-wind band and one
+      WIND_BAND: line per pair that breaks inside [min, max], and records
+      WIND_BAND in check.json. Steady wind only; it does not measure gusts or
+      transient overshoot (AUTHORING §6, Steady-wind seam band).
 
   rig-parts loop --frames <dir> --out <file.png | file.gif> [--palette]
       Encode a frame set rigc render wrote (its --out directory, or the set
@@ -788,7 +804,7 @@ usage:
                     [--pack-shape rect|polygon] [--loop] [--requirements <file.json>]
                     [--idle-keys ctl|direct] [--lead-in <periods>] [--seam-pairs] [--keep-stills]
                     [--alt <name>=<source>:<full>[:<head>]] [--set <name> | --all-sets]
-                    [--environment <schedule.json>]
+                    [--environment <schedule.json>] [--wind-band <spec.json>]
       assemble, then rig, then check, in one process, each stage's own lines
       printed under [assemble], [rig] and [check]; the first stage that refuses
       stops the build with its own FAIL lines. The config must already carry
@@ -819,6 +835,9 @@ usage:
       --environment is forwarded to check (as for check); the schedule is read
       by rig-c's reader before assemble runs, so a malformed one is refused,
       CHECK_ENVIRONMENT, under [assemble] before anything is assembled.
+      --wind-band is forwarded to check (as for check); the spec is read before
+      assemble runs, so a malformed one is refused, CHECK_WIND_BAND, under
+      [assemble] before anything is assembled.
       --seam-pairs and --keep-stills are forwarded to check (as for check:
       the seam split by pair on a pass too, under check/seam/; the setup-pose
       still under check/setup_still/). check's --rig and --parts are refused:
@@ -981,10 +1000,29 @@ function printLayerTable(set: LayerSet): void {
   const head = ['order', 'name', 'group', 'left,top', 'right,bottom', 'size', 'opaque_px', 'depth', 'translucent', 'background', 'area'];
   const widths = head.map((h, i) => Math.max(h.length, ...rows.map((r) => r[i].length)));
   const line = (cells: string[]): string => `  ${cells.map((c, i) => c.padEnd(widths[i])).join('  ')}`.trimEnd();
-  console.log(line(head));
-  for (const r of rows) console.log(line(r));
+  // Keep every legacy line byte-for-byte as a prefix; size the trailing fields separately.
+  const legacy = [line(head), ...rows.map(line)];
+  const legacyWidth = Math.max(...legacy.map(l => l.length));
+  const drawn = `drawn(a>${OPAQUE_ALPHA_ABOVE})`;
+  const opaque = `opaque(a>=${CORE_ALPHA})`;
+  const boxes = set.layers.map(l => [layerOpaqueBox(l), layerCoreBox(l)] as const);
+  const opaqueHead = [drawn, opaque].flatMap(label => [`${label}_left,top`, `${label}_right,bottom`, `${label}_size`]);
+  const opaqueRows = boxes.map(pair => pair.flatMap(b => b === null ? ['none', 'none', 'none'] : [`${b.left},${b.top}`, `${b.right},${b.bottom}`, `${b.right - b.left}x${b.bottom - b.top}`]));
+  const opaqueWidths = opaqueHead.map((h, i) => Math.max(h.length, ...opaqueRows.map(r => r[i].length)));
+  for (const [i, cells] of [opaqueHead, ...opaqueRows].entries()) {
+    console.log(`${legacy[i].padEnd(legacyWidth)}  ${cells.map((c, j) => c.padEnd(opaqueWidths[j])).join('  ')}`.trimEnd());
+  }
   const painted = set.layers.filter((l) => l.opaquePx > 0).length;
   console.log(`  ${set.layers.length} layer(s): ${painted} with opaque pixels, ${set.layers.length - painted} with none`);
+  console.log(`  source-alpha boxes: ${drawn}, ${opaque}; legacy opaque_px remains alpha > ${OPAQUE_ALPHA_ABOVE}; INPUT-CANVAS px; right/bottom exclusive`);
+  for (const [i, [drawnBox, coreBox]] of boxes.entries()) {
+    if (drawnBox === null) console.log(`  layer "${set.layers[i].name}": no ${drawn} box (no pixels with alpha > ${OPAQUE_ALPHA_ABOVE})`);
+    if (coreBox === null) console.log(`  layer "${set.layers[i].name}": no ${opaque} box (no pixels with alpha >= ${CORE_ALPHA})${drawnBox === null ? '' : `; ${drawn} box is present`}`);
+  }
+  const bodyBounds = (body: OpaqueBox | null): string => body === null ? 'none; height unavailable INPUT-CANVAS px' : `${body.left},${body.top} to ${body.right},${body.bottom}; size ${body.right - body.left}x${body.bottom - body.top}; height ${body.bottom - body.top} INPUT-CANVAS px`;
+  console.log(`  body-group union [${opaque}]: ${bodyBounds(bodyCoreBox(set))}; source alpha >= ${CORE_ALPHA} only, not an owned/eroded core or anatomical height`);
+  console.log(`  body-group union [${drawn}]: ${bodyBounds(bodyOpaqueBox(set))}; source alpha > ${OPAQUE_ALPHA_ABOVE} only; not an anatomical height`);
+  console.log('  body-group population: drawn group=body (includes hair/head/wings/objects; excludes face/headwear, author and hidden art); before cleanup, resampling or painting registration');
   // Issue #256: a layer the author made is said to be one, so it never reads as See-through's. None, no line.
   for (const l of set.layers) if (l.tag.group === 'author') console.log(`  ${authorLayerLine(l.name)}`);
   // Issue #359: a hidden-art layer is listed apart, never in the drawn table. None, no line.
@@ -1014,13 +1052,13 @@ const TAKES = {
   rig: { valued: ['--config', '--parts', '--out', '--idle-keys', '--page-edges', '--pack-shape'], switches: [] },
   propose: { valued: ['--parts', '--source', '--out', '--from-config', '--compare', '--full', '--head', '--canvas', '--keypoints', '--person', '--wrist-snap', '--grid-rule', '--cloth', '--write-config', '--from'], switches: ['--head-box', '--no-back-hair', '--only-missing'] },
   compare: { valued: ['--left', '--right', '--map'], switches: [] },
-  check: { valued: ['--rig', '--out', '--parts', '--source', '--page-edges', '--pack-shape', '--requirements', '--set', '--environment'], switches: ['--seam-pairs', '--keep-stills', '--all-sets'] },
+  check: { valued: ['--rig', '--out', '--parts', '--source', '--page-edges', '--pack-shape', '--requirements', '--set', '--environment', '--wind-band'], switches: ['--seam-pairs', '--keep-stills', '--all-sets'] },
   loop: { valued: ['--frames', '--out'], switches: ['--palette'] },
   assemble: { valued: ['--source', '--full', '--head', '--config', '--out', '--seam', '--project', '--alt', '--write-config'], switches: ['--propose-plan'] },
   'comfy seethrough': { valued: ['--image', '--out', '--resolution', '--steps', '--seed', '--prefix', '--host', '--wait', '--timeout', '--poll'], switches: ['--offload', '--lama', '--nf4'] },
   'comfy paint': { valued: ['--config', '--out', '--seeds', '--seed0', '--host', '--wait', '--timeout', '--poll'], switches: [] },
   inputs: { valued: ['--source', '--config', '--out'], switches: [] },
-  build: { valued: ['--config', '--source', '--full', '--head', '--out', '--seam', '--project', '--page-edges', '--pack-shape', '--requirements', '--idle-keys', '--lead-in', '--alt', '--set', '--environment'], switches: ['--loop', '--seam-pairs', '--keep-stills', '--all-sets'] },
+  build: { valued: ['--config', '--source', '--full', '--head', '--out', '--seam', '--project', '--page-edges', '--pack-shape', '--requirements', '--idle-keys', '--lead-in', '--alt', '--set', '--environment', '--wind-band'], switches: ['--loop', '--seam-pairs', '--keep-stills', '--all-sets'] },
   compose: { valued: ['--scene', '--out', '--requirements', '--accept'], switches: [] },
   'mesh-draft': { valued: ['--config', '--parts', '--out', '--requirements', '--idle-keys', '--page-edges', '--pack-shape'], switches: ['--more-triangles'] },
   'mesh-stats': { valued: ['--config', '--parts'], switches: [] },
@@ -1271,7 +1309,7 @@ function cmdCheck(args: string[]): number {
   try {
     const bin = findRigc(import.meta.dir, process.env.PATH ?? '');
     const r = checkStage(
-      { rig, parts: f.get('--parts'), source: f.get('--source'), out, pageEdges: edges, packShape: shape, requirements: f.get('--requirements'), seamPairs: seamPairs === 1, keepStills: keepStills === 1, ...(f.has('--set') ? { set: f.get('--set') as string } : {}), allSets: allSets === 1, ...(f.has('--environment') ? { environment: f.get('--environment') as string } : {}) },
+      { rig, parts: f.get('--parts'), source: f.get('--source'), out, pageEdges: edges, packShape: shape, requirements: f.get('--requirements'), seamPairs: seamPairs === 1, keepStills: keepStills === 1, ...(f.has('--set') ? { set: f.get('--set') as string } : {}), allSets: allSets === 1, ...(f.has('--environment') ? { environment: f.get('--environment') as string } : {}), ...(f.has('--wind-band') ? { windBand: f.get('--wind-band') as string } : {}) },
       rigcRunner(bin),
       bin,
       console.log,
@@ -1339,11 +1377,12 @@ function cmdPropose(args: string[]): number {
   }
   // Issue #671: --only-missing adds entries to an existing config for the parts it attaches by neither section; it
   // belongs to the ordinary proposal's --write-config alone.
+  const fromConfigTakes = '(takes --parts, --source, --out, --from-config and optional --keypoints [--person] only)';
   if (onlyMissing) {
     const mode = 'propose --parts … --write-config <config.json> --only-missing';
     if (headBox) return usage(`--only-missing belongs to ${mode}; --head-box writes seethrough.head_box only`);
     if (!flags.has('--parts')) return usage(`--only-missing belongs to ${mode}; give --parts <dir>, the parts the entries are drafted from`);
-    if (flags.has('--from-config')) return usage(`--only-missing belongs to ${mode}; --from-config proposes nothing`);
+    if (flags.has('--from-config')) return usage(`--only-missing belongs to ${mode}; --from-config proposes nothing ${fromConfigTakes}`);
     if (flags.has('--cloth')) return usage(`--only-missing belongs to ${mode}; --cloth writes a new config with the recipe's entries spliced in`);
     if (!flags.has('--write-config')) return usage(`--only-missing belongs to ${mode}; give --write-config <config.json>, the existing config the entries are added to`);
   }
@@ -1388,17 +1427,17 @@ function cmdPropose(args: string[]): number {
     if (partsArg === undefined) return usage('propose needs --parts <dir>, the directory holding parts.json and parts/');
     if (source === undefined) return usage('propose needs --source <painting.png>, drawn under the overlay');
     if (out === undefined) return usage('propose needs --out <dir>');
-    if (flags.has('--from-config') && flags.has('--compare')) return usage('--from-config and --compare are two modes; give one');
+    if (flags.has('--from-config') && flags.has('--compare')) return usage(`--from-config and --compare are two modes; give one (--from-config ${fromConfigTakes.slice(1, -1)})`);
     if (flags.has('--person') && !flags.has('--keypoints')) return usage('--person names a person in the --keypoints file; give --keypoints <file>');
     // Issue #251: the See-through runs the turn control's depths are read from; without them nothing is drafted.
-    if (flags.has('--from-config') && (flags.has('--full') || flags.has('--head'))) return usage('--full and --head draft the turn control while proposing; --from-config proposes nothing');
+    if (flags.has('--from-config') && (flags.has('--full') || flags.has('--head'))) return usage(`--full and --head draft the turn control while proposing; --from-config proposes nothing ${fromConfigTakes}`);
     // Issue #199: a declared tolerance for a wrist on no handwear part. Whole px above the built-in one: the distance is
     // counted in whole px, so a fraction would bind what its floor binds, and a value at or under the built-in binds nothing.
     const snapArg = flags.get('--wrist-snap');
     let wristSnap: number | null = null;
     if (snapArg !== undefined) {
       if (!flags.has('--keypoints')) return usage('--wrist-snap binds a wrist joint to a handwear part; give --keypoints <file>');
-      if (flags.has('--from-config')) return usage('--wrist-snap binds a wrist while proposing; --from-config proposes nothing');
+      if (flags.has('--from-config')) return usage(`--wrist-snap binds a wrist while proposing; --from-config proposes nothing ${fromConfigTakes}`);
       if (!/^[0-9]+$/.test(snapArg) || Number(snapArg) <= WRIST_ON_PART_PX) {
         return usage(`--wrist-snap ${snapArg} is not an integer above ${WRIST_ON_PART_PX}, the px within which a wrist already holds a part`);
       }
@@ -1406,15 +1445,15 @@ function cmdPropose(args: string[]): number {
     }
     // Issue #265: the drafted lattice's spacing; the figure's unless the reference's per-part rule is asked for.
     const ruleArg = flags.get('--grid-rule');
-    if (ruleArg !== undefined && flags.has('--from-config')) return usage('--grid-rule chooses the drafted spacing; --from-config proposes nothing');
+    if (ruleArg !== undefined && flags.has('--from-config')) return usage(`--grid-rule chooses the drafted spacing; --from-config proposes nothing ${fromConfigTakes}`);
     if (ruleArg !== undefined && !(GRID_RULES as readonly string[]).includes(ruleArg)) return usage(`--grid-rule ${ruleArg}; one of ${GRID_RULES.join(', ')} is required`);
     const gridRule = (ruleArg ?? DEFAULT_GRID_RULE) as GridRule;
     // Issue #364: the cloth and hair recipe, read from a config's cloth block; without it nothing changes.
     const clothArg = flags.get('--cloth');
-    if (clothArg !== undefined && flags.has('--from-config')) return usage('--cloth drafts trees while proposing; --from-config proposes nothing');
+    if (clothArg !== undefined && flags.has('--from-config')) return usage(`--cloth drafts trees while proposing; --from-config proposes nothing ${fromConfigTakes}`);
     // Issue #537: the --cloth config's own text with what its recipe drafts spliced in, beside proposal.json.
     const writeArg = flags.get('--write-config');
-    if (writeArg !== undefined && flags.has('--from-config')) return usage('--write-config writes what the recipe drafts into its config; --from-config proposes nothing');
+    if (writeArg !== undefined && flags.has('--from-config')) return usage(`--write-config writes what the recipe drafts into its config; --from-config proposes nothing ${fromConfigTakes}`);
     // Issue #571: the config the recipe is changed from; an entry equal to its recipe's draft is the recipe's, not a hand edit.
     const fromArg = flags.get('--from');
     if (fromArg !== undefined && writeArg === undefined) return usage('--from names the config the recipe is changed from, for --write-config; give --write-config <out.json>');
@@ -1422,7 +1461,7 @@ function cmdPropose(args: string[]): number {
     if (writeArg !== undefined && clothArg !== undefined) {
       const ours = ['proposal.json', BASIS_FILE, 'render/landmarks.png', 'render/landmarks_head.png'].map((f) => resolve(out, f));
       if (existsSync(writeArg) || ours.includes(resolve(writeArg))) {
-        throw new PartsError([{ code: 'PROPOSE_WRITE_CONFIG_FRESH', object: writeArg, detail: existsSync(writeArg) ? 'exists; the config is written to a new file, never over the --cloth config or an earlier one' : `is a file this run writes under ${out}; name another file` }]);
+        throw new PartsError([{ code: 'PROPOSE_WRITE_CONFIG_FRESH', object: writeArg, detail: existsSync(writeArg) ? 'exists; the config is written to a new file, never over the --cloth config or an earlier one (unlike assemble --propose-plan and propose without --cloth, which update an existing --config in place)' : `is a file this run writes under ${out}; name another file` }]);
       }
       separateConfigWriteTarget({ path: resolve(writeArg) }, ours, 'PROPOSE_WRITE_CONFIG_FRESH');
     }
@@ -1630,7 +1669,7 @@ function cmdAssemble(args: string[]): number {
   const [source, full, config] = ['--source', '--full', '--config'].map((f) => flags.get(f) as string);
   const head = flags.get('--head') ?? null;
   const writePath = flags.get('--write-config');
-  if (writePath !== undefined && resolve(writePath) !== resolve(config)) return usage('--write-config must name the same file as --config for assemble --propose-plan');
+  if (writePath !== undefined && resolve(writePath) !== resolve(config)) return usage('--write-config must name the same file as --config for assemble --propose-plan (assemble --propose-plan updates --config in place; only propose --cloth --write-config writes to a new file)');
   let staged: StagedConfigWrite | null = null;
   try {
     if (propose) {
@@ -1857,7 +1896,7 @@ function cmdBuild(args: string[]): number {
   const scratch = mkdtempSync(join(tmpdir(), 'rig-parts-build-'));
   try {
     const r = build(
-      { config, source, full, head, out, seam: seam as SeamRule, project: project as ProjectRule, loop, pageEdges: edges, packShape: shape, ...(flags.has('--requirements') ? { requirements: flags.get('--requirements') as string } : {}), idleKeys: keys, ...(leadText === undefined ? {} : { leadIn: Number(leadText) }), seamPairs: on.has('--seam-pairs'), keepStills: on.has('--keep-stills'), ...(alts.length === 0 ? {} : { alts }), ...(flags.has('--set') ? { set: flags.get('--set') as string } : {}), allSets: on.has('--all-sets'), ...(flags.has('--environment') ? { environment: flags.get('--environment') as string } : {}) },
+      { config, source, full, head, out, seam: seam as SeamRule, project: project as ProjectRule, loop, pageEdges: edges, packShape: shape, ...(flags.has('--requirements') ? { requirements: flags.get('--requirements') as string } : {}), idleKeys: keys, ...(leadText === undefined ? {} : { leadIn: Number(leadText) }), seamPairs: on.has('--seam-pairs'), keepStills: on.has('--keep-stills'), ...(alts.length === 0 ? {} : { alts }), ...(flags.has('--set') ? { set: flags.get('--set') as string } : {}), allSets: on.has('--all-sets'), ...(flags.has('--environment') ? { environment: flags.get('--environment') as string } : {}), ...(flags.has('--wind-band') ? { windBand: flags.get('--wind-band') as string } : {}) },
       { rig: rigcRunner(bin), check: rigcRunner(bin), checkBin: bin, scratch: join(scratch, 'rig-gate'), stages: {
         assemble: (input, outputs) => runBuildProcess({ stage: 'assemble', bin, input, outputs }, join(scratch, 'workers')),
         rig: (input, _rigc, gateScratch) => runBuildProcess({ stage: 'rig', bin, input, scratch: gateScratch }, join(scratch, 'workers')),