rig-parts 1.46.0 → 1.48.0

package/cli.ts

@@ -14,7 +14,7 @@
 import { spawnSync } from 'node:child_process';
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { basename, dirname, extname, join } from 'node:path';
+import { basename, dirname, extname, join, resolve } from 'node:path';
 import { DEFAULT_PROJECT_RULE, DEFAULT_SEAM_RULE, HOLES_LISTED, PROJECT_RULES, type ProjectRule, proposeFields, proposePlan, proposeSinglePlan, SEAM_RULES, type SeamRule } from './src/assemble.ts';
 import { type AlternateCliInput, assembleStage, build, checkStage, ERROR_MAP_FILE, loopStage, readRuns, readSource, rigStage, suppliedCheckFlag } from './src/build.ts';
 import { ACCEPTABLE_BARS, DEFAULT_PACK_SHAPE, DEFAULT_PAGE_EDGES, findRigc, PACK_SHAPES, rigcRunnerAt, type PackShape, PAGE_EDGES, type PageEdges, PARTS_HOME_SENTENCE, RIGC_GEOMETRY_VERSION, rigcRanClause, type RigcRunner, NO_PARTS_SENTENCE, SEAM_MEAN_BAR, SOURCE_SENTENCE, SEAM_PX_BAR, SEAM_PX_LEVEL, SPINEBOY_YARDSTICK, TEXTURE_STRETCH_CEILING } from './src/check.ts';
@@ -29,7 +29,8 @@ import { depthSkipLine, exportLayers, figuresPhrase, hiddenLayerLine, implausibl
 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, proposeWithBasis, readPartSet, serializeProposal, withTurn, WRIST_ON_PART_PX } from './src/propose.ts';
 import { BASIS_FILE, BASIS_SPEC, basisFile, basisLine, coverageLines, serializeBasis } from './src/diagnostics.ts';
-import { BEND_DEGREES, BEND_WORST_SHARE, DUST_MAX_PX, DUST_MAX_SHARE, IDLE_BOUND_PX, MESH_DRAFT_REPORT, MESH_DRAFT_SPEC, meshDraftStage, MORE_TRIANGLES_FLAG, TOLERANCE_FIGURE_DIVISOR } from './src/meshdraft.ts';
+import { BEND_DEGREES, BEND_WORST_SHARE, DUST_MAX_PX, DUST_MAX_SHARE, IDLE_BOUND_PX, MESH_DRAFT_REPORT, MESH_DRAFT_SPEC, meshDraftStage, MORE_TRIANGLES_FLAG, relativeConfigPaths, TOLERANCE_FIGURE_DIVISOR } from './src/meshdraft.ts';
+import { clothConfigEdits, editPaths, writtenClothConfig } from './src/clothconfig.ts';
 import { PROVENANCE_FILE, REMESH_SPEC, remeshStage } from './src/remesh.ts';
 import { RETUNE_FILE, RETUNE_SPEC, retuneStage } from './src/retune.ts';
 import { checkPainting } from './src/paintcheck.ts';
@@ -225,6 +226,22 @@ usage:
       a LINT line names each drafted radius and both figures. Without --cloth
       nothing changes.
 
+  rig-parts propose … --cloth <config.json> [--write-config <out.json>]
+      Also write the --cloth config's own text with what the recipe drafts
+      spliced in (issue #537), the way mesh-draft writes its config, so that
+      rig --config <out.json> builds it. What is spliced is measured: the
+      same parts drafted again without the recipe, and each config section
+      that differs — bones and constraints whole (a hand-added bone does not
+      survive), meshes.<part>, regions.<part> and motion.tracks entry by
+      entry; a section the input lacks is inserted; every other byte as
+      read. The text is written as stated, so a relative path in it
+      resolves against <out.json>'s directory (a note names each when that
+      is not the input's). Only with --cloth and not with --from-config
+      (usage errors); refused, before anything is written, when <out.json>
+      exists or is a file this run writes (PROPOSE_WRITE_CONFIG_FRESH), or
+      when the spliced text does not parse to the config with the sections
+      set, naming the first key that moved (PROPOSE_WRITE_CONFIG_SPLICE).
+
   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
@@ -412,7 +429,7 @@ usage:
   rig-parts check --rig <dir> --out <dir> [--parts <dir>] [--source <painting.png>]
                     [--page-edges pot|free] [--pack-shape rect|polygon]
                     [--requirements <file.json>] [--seam-pairs] [--keep-stills]
-                    [--set <name> | --all-sets]
+                    [--set <name> | --all-sets] [--environment <schedule.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.
@@ -530,6 +547,29 @@ usage:
       follow no frame of which reaches its least drive) is
       CHECK_REQUIREMENT_MEASURABLE, and the run is not PASS. Without the flag
       nothing is read, written or printed for it.
+      --environment <schedule.json> takes the readings in the world a person
+      watched: a rigc-environment/1 schedule ({ "spec": "rigc-environment/1",
+      "steps": [{ "t": <seconds>, "wind"?: [x, y], "gravity"?: [x, y] }, ...] },
+      x right, y down — what rigc render --environment reads, and what the
+      review editor exports). It is read once, by rig-c's own reader, before
+      anything is built; a malformed one, or a path with nothing at it, is
+      refused, CHECK_ENVIRONMENT, rigc's sentence verbatim, and --out is not
+      written. Every render a bar or a warning reads with the physics on is
+      posed under it — the idle (TIP_OVER_ROOT, STILL_REGIONS_DARK,
+      TEXTURE_STRETCH, CLOTH_SETTLES), the physics-on half of
+      ANIMATIONS_DO_NOT_FOLD, the parts BREATH_VISIBLE renders alone,
+      SEAM_OVER_MOTION and the --requirements renders; the physics-off renders
+      (the loop's, the fold bar's other half, STRESS_OFF_CHAIN,
+      SEAM_OVER_RANGE), the setup-pose stills and build's loop take none. What
+      rigc render refuses of the schedule on this rig (no physics constraint,
+      a half no constraint answers, a step after the last frame) is
+      CHECK_ENVIRONMENT with rigc's line. The world before the first step is
+      the runtime's, wind [1, 0] and gravity [0, 1]: a schedule stating that
+      reads what a run without the flag reads, and wind [0, 0] is a calm, not
+      the default (AUTHORING §6, The world the readings are taken in). One
+      environment: line names the path, the step count and the sha256's first
+      16 hex; check.json's environment holds path (as given), sha256 and
+      steps. Without the flag no key and no render argument moves.
 
   rig-parts loop --frames <dir> --out <file.png | file.gif> [--palette]
       Encode a frame set rigc render wrote (its --out directory, or the set
@@ -646,6 +686,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>]
       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
@@ -668,6 +709,9 @@ usage:
       and check's artifact, take them). --requirements is forwarded to check
       (as for check); the file's own shape is read before assemble runs, and
       its names resolve against the rig in the check, before it builds.
+      --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.
       --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:
@@ -861,15 +905,15 @@ const TAKES = {
   layers: { valued: ['--export', '--template', '--canvas'], switches: [] },
   sheet: { valued: ['--source', '--layers', '--out', '--cell', '--cols'], switches: [] },
   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'], switches: ['--head-box', '--no-back-hair'] },
+  propose: { valued: ['--parts', '--source', '--out', '--from-config', '--compare', '--full', '--head', '--canvas', '--keypoints', '--person', '--wrist-snap', '--grid-rule', '--cloth', '--write-config'], switches: ['--head-box', '--no-back-hair'] },
   compare: { valued: ['--left', '--right', '--map'], switches: [] },
-  check: { valued: ['--rig', '--out', '--parts', '--source', '--page-edges', '--pack-shape', '--requirements', '--set'], switches: ['--seam-pairs', '--keep-stills', '--all-sets'] },
+  check: { valued: ['--rig', '--out', '--parts', '--source', '--page-edges', '--pack-shape', '--requirements', '--set', '--environment'], switches: ['--seam-pairs', '--keep-stills', '--all-sets'] },
   loop: { valued: ['--frames', '--out'], switches: ['--palette'] },
   assemble: { valued: ['--source', '--full', '--head', '--config', '--out', '--seam', '--project', '--alt'], 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'], 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'], 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'] },
   remesh: { valued: ['--rig', '--config', '--parts', '--part', '--mesh', '--delta', '--out', '--requirements', '--idle-keys', '--page-edges', '--pack-shape'], switches: [] },
@@ -1140,7 +1184,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 },
+      { 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 } : {}) },
       rigcRunner(bin),
       bin,
       console.log,
@@ -1258,6 +1302,16 @@ function cmdPropose(args: string[]): number {
     // 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');
+    // 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 && clothArg === undefined) return usage('--write-config writes the --cloth config with what its recipe drafts spliced in; give --cloth <config.json>');
+    if (writeArg !== undefined) {
+      const ours = ['proposal.json', BASIS_FILE].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` }]);
+      }
+    }
     const cloth = clothArg === undefined ? null : loadClothConfig(clothArg).cloth;
     const partsDir = existsSync(partsArg) && statSync(partsArg).isFile() ? dirname(partsArg) : partsArg;
     if (!existsSync(source)) {
@@ -1295,6 +1349,15 @@ function cmdPropose(args: string[]): number {
         : withTurn(drafted, draftTurn(P, { ...(fullRun === undefined ? {} : { full: readLayers(fullRun) }), ...(headRun === undefined ? {} : { head: readLayers(headRun) }) }, drafted));
     // Emit only after green: a proposal the config loader would refuse is not written, nor a basis record that does not hold to it.
     checkProposal(P, prop);
+    // Issue #537: the sections the recipe moves, measured against the same parts drafted without it, spliced before anything is written.
+    const written =
+      writeArg === undefined || clothArg === undefined
+        ? null
+        : (() => {
+            const edits = clothConfigEdits(drafted, proposeWithBasis(P, joints, wristSnap, gridRule, null).proposal);
+            const text = readFileSync(clothArg, 'utf8');
+            return { at: writeArg, text: writtenClothConfig(clothArg, text, edits), paths: editPaths(edits), relative: relativeConfigPaths(dirname(resolve(clothArg)), JSON.parse(text) as Record<string, unknown>) };
+          })();
     const bfile = basisFile(P, prop, basis, cfg === null || cmpPath === undefined ? null : { where: cmpPath, config: cfg });
     const img = drawLandmarks(P, painting, prop.bones, 'PROPOSAL - CORRECT ME');
     mkdirSync(render, { recursive: true });
@@ -1302,10 +1365,20 @@ function cmdPropose(args: string[]): number {
     writeFileSync(join(out, BASIS_FILE), serializeBasis(bfile));
     writePng(join(render, 'landmarks.png'), img.full);
     if (img.head !== null) writePng(join(render, 'landmarks_head.png'), img.head);
+    if (written !== null) {
+      mkdirSync(dirname(written.at), { recursive: true });
+      writeFileSync(written.at, written.text);
+    }
     console.log(`wrote proposal.json (${prop.bones.length} bone entries, ${Object.keys(prop.meshes).length} meshes) and render/landmarks.png (+_head) under ${out}`);
     for (const n of prop.notes) console.log(`note: ${n}`);
     printLint(P, prop, joints, draftLint);
     console.log(basisLine(bfile, out));
+    if (written !== null && clothArg !== undefined) {
+      console.log(`wrote ${written.at}: ${clothArg}'s text with ${written.paths.join(', ')} spliced in from the draft; every other byte as read`);
+      if (written.relative.length > 0 && dirname(resolve(written.at)) !== dirname(resolve(clothArg))) {
+        console.log(`note: ${written.relative.map((r) => `${r.at} "${r.value}"`).join(', ')} written as stated; the loader resolves each against the directory the config sits in, ${dirname(written.at)} for ${written.at}, not ${dirname(clothArg)}; put the config beside ${clothArg} or rewrite them`);
+      }
+    }
     if (cfg !== null) for (const l of compareLines(compare(prop.bones, cfg.bones))) console.log(l);
     return EXIT_OK;
   } catch (err) {
@@ -1612,7 +1685,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') },
+      { 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 } : {}) },
       { rig: rigcRunner(bin), check: rigcRunner(bin), checkBin: bin, scratch: join(scratch, 'rig-gate') },
       console.log,
     );

package/docs/AUTHORING.md

@@ -128,7 +128,7 @@ read by no CPU stage).
 | `stops` | rig (handed to rig-c as `rig.json`'s `stops`, and moves slots, mesh weights and child bones on stopped links onto `<link>_d`); `propose --from-config` (`LINT stop on <chain> …`) | **authored**, optional (issues #404, #447): `[{chain, links?, against, at, inward, outward, lower?: {inward, outward}}]` — rig-c's leg stops (`RigStop`, rig-c 2.56.0, `rig-c/src/stop.ts`). `chain` is a chain `bones` declares (`CONFIG_NAME_RESOLVES`, `RIG_NAME_RESOLVES`); `links`, optional, is a non-empty list of links of that chain (`CONFIG_NAME_RESOLVES`, `CONFIG_FIELD_TYPE`), or absent for every link of `chain` in chain order; `against` is a bone `bones` declares, a chain link as `<chain><i>` (`CONFIG_NAME_RESOLVES`, `RIG_NAME_RESOLVES`); `at` is `[x, y]` in `against`'s local space, as rig-c's stop takes it (`CONFIG_FIELD_TYPE`): since each chain link (`leg_r0`, `leg_r1`) is turned to point along its segment (`+x` from origin to next link or tip, `+y` 90° counter-clockwise in Spine world), `at: [d, n]` sits `d` px from `against`'s origin toward its end and `n` px perpendicular to it; `inward`, `outward` and `lower.inward`, `lower.outward` are finite numbers (`CONFIG_FIELD_TYPE`). Every other stop rule — non-negative bounds, each stopped link written by a constraint, `against` not under the stopped chain, the aim not degenerate, `\|rest\| + outward <= 180°` (`RIG_STOP_BOUNDS`) — is rigc's to accept or refuse at the rig stage's gate, in rigc's words (`RIG_RIGC_GREEN`). **Rising-limb / prone geometry (issue #447):** rig-c's `expandStops` aims `<chain>_rest` from `links[0]`'s setup origin at `<chain>_touch` (`at` in `against`'s local frame) and clamps `<link>_d` inside `[rest − inward, rest + outward]`; Spine wraps rotation at `±180°`, so `\|rest\| + outward <= 180°` is required (`RIG_STOP_BOUNDS`). Whenever `<chain>_touch` lies **above** `links[0]`'s root in rig pixels (`ty < y0`, i.e. higher Spine `y` — e.g. stopping a hanging cloth chain against a rising shin `leg_<s1>` in a prone or kneeling pose where the knee sits below `links[0]` and the ankle above it, so positive `at[0]` walks upward along the shin past `links[0]`'s root), `rest` lands in the upper half-plane (`\|rest\| > 90°`) and `\|rest\| + outward` exceeds `180°`. Stop against the descending thigh (`leg_<s0>`), set `links` to start at a link whose root sits above `<chain>_touch`, or omit the stop when the rising shin sits outside the hanging chain's sweep; `propose --from-config` prints `LINT stop on <chain> …` with the exact coordinates and angles when `<chain>_touch` lies above `links[0]`'s root or `\|rest\| + outward > 180°`. For every stopped link `<link>`, the rig stage moves any slot on `<link>`, any mesh weight on `<link>`, and any bone whose parent is `<link>` (a branched cloth tree's branches hanging from `<trunk_last>`, before `--idle-keys ctl` adds `<bone>_ctl` and before `turn` adds `turn_<part>_<bone>`) onto `<link>_d`, the drawn link bone rig-c's `expandStops` creates at `<link>`'s setup frame to carry the clamped rotation. Absent, `rig.json` carries no `stops` and no byte of any output moves |
 | `turn` | rig (adds the turn control) | **proposed** only with `propose --full`/`--head` (issue #251), then corrected: `{pivot, depths, deform?, band?, radius?, surface?: {radius?}, head?: {pivot?, radius?}}`. `depths` holds, per part, the See-through layer's `depth_median` the part came from (larger = further back), read from the run the part was assembled from; a `painting:` patch has none and is not carried. A rider (issue #271) — a part from an `eyewhite`, `irides`, `eyelash`, `eyebrow`, `nose` or `mouth` layer — is drafted at the `face` part's depth, 0.001 nearer when parts.json draws it after the face and 0.001 further when before: See-through makes no depth of its own for the eye group (it cuts them from one depth map of the combined eyes) and clamps nose and mouth to the face's median − 0.001, and the two runs' own medians for these layers disagreed by up to 0.47 and swapped their order against the face. Every other layer — ears, headwear and earwear included — keeps its own median, unless it rides another part's bone. With no `face` part, or more than one, the riders keep their own and a note says so. A rider by bone (issue #535) — a part every *ownable* bone of which (a chain link, or a bone no other bone hangs from; `head`, `chest` and any bone with a child are shared and never count on their own) is *hosted* by another carried part, the host of a bone being the carried part that binds it (its region's bone; a mesh's `segments`, `contour` and `auto` regions' bones) with the most `opaque_px`, the earlier in parts.json on a tie, and which hosts no bone itself — is drafted at its host's depth, 0.001 nearer when drawn after the host and 0.001 further when before, and a note names the host, the bones and its own median: a pin, clip or ornament on the back hair's links travels with the back hair, not with its own layer's depth. `propose` reads the proposal's own `bones`, `meshes` and `regions`; the face riders are read by their tag first and never by their bones. A part bound to two hosts' bones rides neither and a note says so. In the rig stage, an authored depth on a rider by bone whose fraction differs from its host's by more than 0.1 of the dial (`TURN_RIDER_APART`, a share of `pivot − nearest`) is refused (`CONFIG_TURN_RIDER_DEPTH`); the host is read off `parts.json`'s `opaque_px`, so the config loader cannot see it. One note lists each part's depth and where it came from; a carrier the other run places more than 10 % of `pivot − nearest` away gets a note naming both values and the run read — the two runs are not reconciled. `pivot` is the depth that stays put; `propose` drafts the mean of the parts' depths weighted by `opaque_px`, the one depth at which the painted pixels' centroid does not slide under the dial. The rig stage adds a bone `turn` under `root` at its origin that nothing keys — its local x is the dial, in rig px — and carries each part by `(pivot − depth) / (pivot − nearest depth)` of it: the nearest part all of it, a part behind the pivot the other way, a part at the pivot not at all. Each part rides leaf twins (`turn_<part>_<bone>`, an identity child of every bone its slot and weights bind) moved by one `transform` constraint (`turn_<part>`, after the config's own); the idle's keys, the `<bone>_ctl` controls and a physics constraint stay on the bones, and the dial moves none of them. Optional `deform` (`Partial<FaceDeformFractions>`, issue #436) overrides the Set B ×2.5 face surface deformation table (`FACE_DEFORM_FRACTIONS`, checked against `FACE_DEFORM_RANGES` by `CONFIG_TURN_DEFORM_RANGE`); when `applyFaceSurfaceDeform` runs on a rig whose `motion` carries `tilt` or `turn` slider `derive` keys, it requires `config.turn` (`CONFIG_TURN_REQUIRED`, issue #478; `propose --full`/`--head` drafts it), promotes `face` on `head` (or `turn_face_head` when `turn` is declared) to the uneven 5×5 grid mesh, keys `face`, `hair_front` and `hair_back` deform timelines and ear/topknot tracks from `evalPitchFaceSurface` and `evalYawFaceSurface`, and samples the same deform field across each `features` member's rest span (`featRx = (24 / 106) · W`, `featRy = (12 / 128) · H`) with its depth fraction `z / zRef` as the field's angle input and chord foreshortening (`scalex` narrowing on the leading side and widening on the trailing side, `scaley` on pitch) so every feature's bounding box stays inside the deformed face plate across the rated band (issue #468). On yaw (`issue #479`), `evalYawFaceSurface` evaluates a **cylinder projection** (`cylinderYawDx`: `Δx(x, θ, R) = R · (sin(clamp(arcsin(clamp(x / R, −1, 1)) − θ, −π/2, π/2)) − clamp(x / R, −1, 1))`) of radius `R` (`turnSurfaceRadius`: `turn.surface.radius ?? turn.radius ?? turn.head.radius`, positive rig px checked by `CONFIG_FIELD_TYPE`, defaulting to half the face plate's opaque width `W / 2`) tapered by a cubic Hermite outline weight (`wOutline = 1` for `\|ux\| <= 0.7`, reaching `0` at `\|ux\| = 1.0`) so features slide across a fixed outline (`iris` shift within `±2%` of `cylinderYawDx`), the trailing cheek strip widens (`>= 1.54×` at `±15°`), and the leading jaw edge holds fixed (`0 px` shift) unless explicit horizontal `turn.deform` overrides (`turn_mid_x`, `turn_lead_compress_x`, `turn_trail_shift_x`) request the flat yaw table. On yaw (`issue #478`), `applyFaceSurfaceDeform` also derives a **head-only pivot** (`headTurnPivot`: `turn.head.pivot` when authored, otherwise the `opaque_px`-weighted mean of `depths[part]` across the head parts `DEFAULT_HEAD_TURN_PARTS` — `face`, `hair_front`, `hair_back`, `ear_r`, `ear_l`, `hairpin` — from `parts.json`, falling back to `turn.pivot`) so a forward torso or arm in `turn.depths` does not pull the head's rotation axis in front of `face`: `hair_back` (`depth_median > headPivot`, negative `headTurnFraction`) and `hairpin` behind `headPivot` translate opposite to the face's turn (`dx = s · turn_face_center_x · W · (headPivot − depth) / (headPivot − nearestHeadDepth)`), emerging on the trailing side to compensate for the leading-cheek foreshortening and keeping the combined head silhouette width near-constant across `±15°` without any same-sign `turn_hair_back_cheek_x` term. Optional `band` (`number` or `{yaw?, pitch?}`, positive degrees, issue #472) declares the rig's rated face turn band (default `FACE_RATED_BAND`: `yaw <= 15°`, `pitch <= 12°`); declaring a `turn.band` or a `motion.animations_from` `turn`/`tilt` `derive.degrees` above `±15°` yaw or `±12°` pitch without an `assemble.alternates` entry that replaces `face` is refused (`CONFIG_FACE_BAND_EXCEEDED`), and on a single-plate rig `applyFaceSurfaceDeform` adds self-targeting transform constraints `yaw_clamp` (`[-15, 15]`) and `pitch_clamp` (`[-12, 12]`) ahead of the slider constraints so driving `yaw` or `pitch` beyond the rated band clamps at the boundary. At rest: with `turn` declared, no pixel differs by more than 1 level at dial 0 (not byte-identical; the cause is float noise in the identity child bones, and the constraints add nothing); without `turn`, byte-identical. Neither `pivot` nor `depths` has a default (`CONFIG_FIELD_PRESENT`); `pivot` and `head.pivot` must lie behind the nearest part (`CONFIG_TURN_PIVOT_BEHIND_NEAREST`). Absent, no control is added and no byte of any output moves |
 | `scene` | assemble (the recomposite, its holes and the figure's mask); check, through `parts.json`'s `scene` block (`RECOMPOSITE_HOLES`, the seam) | **authored**, optional; `propose` writes none (issue #242). `{}` declares the painting a scene: the figure and its surroundings in one image, See-through's full run holding only the figure. With it, `assemble` reads the recomposite figures, the hole list and the `uncovered:` lines inside the figure — the rig pixels where any full-run layer's alpha is above 8 (`OPAQUE_ALPHA_ABOVE`, the cut every layer's painted pixels are read by) — each line starting `inside the figure (config.scene: …, <n> of <m> rig px)`; writes that figure as `figure_rig.png` (white on black) beside the recomposite, and a `scene` block in `parts.json`; flags error pixels on the error map inside it only (outside, the painting grey); and `check` leaves out of the seam every frame pixel whose composite sample reaches the painting's outermost row or column, saying how many (`seam_border` in `check.json`, and on the seam line). It takes no field: the figure and its threshold are derived. A key in it other than a record or an annotation is `CONFIG_KEY_KNOWN`. Absent, no byte of any output moves |
-| `cloth` | `propose --cloth` only; no other stage reads it, so it moves no byte of any build | **authored**, optional (issue #364): one recipe per tag, `{"bottomwear": {…}, "back hair": {…}, "front hair": {…}}`, each `{chains, links, wind, gravity, split?, length_ratio?, strength?, damping?, alternate_damping?, translate?, swing?, part?, influence?}`. `influence` (issue #518) — `{across, max, shape, radius?}`: the parts this recipe meshes are drafted in the influence mode (`meshes.<part>.influence` above) at their lattice's cell, with `across`, `max` and `shape` as declared (each required — the reading behind the radius did not vary them) and `radius` as declared or, absent, drafted as the farthest vertex's distance plus 3 cells (the `influence.radius` row); without it the parts keep their lattice. `chains` — trees across the piece (for `back hair`, per side of the eye axis), a whole number, 1 or more; `links` — links from root to tip on every path, 1 or more; `split` — `{at, into}`: the first `at` links are the trunk, which forks into `into` (2 or more) branches; `at` below `links` (`CONFIG_CLOTH_SPLIT_BEFORE_TIP`); `length_ratio` — a path's last link over its first, above 0, default 0.5; `strength` — `{trunk, branch, edge}`, each above 0 and below the spring's stability bound (`CONFIG_CLOTH_SPRING_STABLE`), default 100 / 100 / 50; `damping` — in [0, 1], absent: rig-c's default; `alternate_damping` — the odd trees' damping, in [0, 1], beside `damping` and different from it (`CONFIG_CLOTH_ALTERNATE_DIFFERS`); `wind`, `gravity` — `[root, tip]`, each 0 or more, tip at or above root (`CONFIG_CLOTH_RESPONSE_GROWS_TO_TIP`); `translate` — the x and y mix of a dangling end's flutter, above 0 and at most 1; `swing` — `bottomwear` only, `{scales}`, one positive scale per tree (`CONFIG_CLOTH_SWING_SCALE_PER_TREE`); `part` — `bottomwear` only (`CONFIG_CLOTH_PART_ON_BOTTOMWEAR`), a non-empty part or cut-piece name: the `topwear` part that holds a skirt See-through returned inside it (a dress), or its skirt piece cut by `assemble.cuts`, which takes the skirt's trees (issue #402, *A skirt inside topwear* below; the part is checked by `propose`, `PROPOSE_CLOTH_PART`). The two defaults are the recipe's own, measured on its synthetic fixture (the recipe below). The recipe below says what each field drafts |
+| `cloth` | `propose --cloth` only; no other stage reads it, so it moves no byte of any build | **authored**, optional (issue #364): one recipe per tag, `{"bottomwear": {…}, "back hair": {…}, "front hair": {…}}`, each `{chains, links, wind, gravity, split?, length_ratio?, strength?, damping?, alternate_damping?, translate?, swing?, part?, influence?}`. `influence` (issue #518) — `{across, max, shape, radius?}`: the parts this recipe meshes are drafted in the influence mode (`meshes.<part>.influence` above) at their lattice's cell, with `across`, `max` and `shape` as declared (each required — the reading behind the radius did not vary them) and `radius` as declared or, absent, drafted as the farthest vertex's distance plus 3 cells (the `influence.radius` row); without it the parts keep their lattice. `chains` — trees across the piece (for `back hair`, per side of the eye axis), a whole number, 1 or more; `links` — links from root to tip on every path, 1 or more; `split` — `{at, into}`: the first `at` links are the trunk, which forks into `into` (2 or more) branches; `at` below `links` (`CONFIG_CLOTH_SPLIT_BEFORE_TIP`); `length_ratio` — a path's last link over its first, above 0, default 0.5; `strength` — `{trunk, branch, edge}`, each above 0 and below the spring's stability bound (`CONFIG_CLOTH_SPRING_STABLE`), default 100 / 100 / 50; `damping` — in [0, 1], absent: rig-c's default; `alternate_damping` — the odd trees' damping, in [0, 1], beside `damping` and different from it (`CONFIG_CLOTH_ALTERNATE_DIFFERS`); `wind`, `gravity` — `[root, tip]`, each 0 or more, tip at or above root (`CONFIG_CLOTH_RESPONSE_GROWS_TO_TIP`); `translate` — the x and y mix of a dangling end's flutter, above 0 and at most 1; `swing` — `bottomwear` only, `{scales}`, one positive scale per tree (`CONFIG_CLOTH_SWING_SCALE_PER_TREE`); `part` — `bottomwear` only (`CONFIG_CLOTH_PART_ON_BOTTOMWEAR`), a non-empty part or cut-piece name: the `topwear` part that holds a skirt See-through returned inside it (a dress), or its skirt piece cut by `assemble.cuts`, which takes the skirt's trees (issue #402, *A skirt inside topwear* below; the part is checked by `propose`, `PROPOSE_CLOTH_PART`). The two defaults are the recipe's own, measured on its synthetic fixture (the recipe below). The recipe below says what each field drafts. The config written: `propose --cloth <config.json> --write-config <out.json>` (issue #537) writes this config's own text back with the sections the recipe drafts spliced in — `bones` and `constraints` whole, `meshes.<part>`, `regions.<part>` and `motion.tracks` entry by entry — and every other byte as read (*The config written*, under the recipe below) |
 | `proposed_rig_scale` | assemble, rig, build, `propose --from-config`/`--compare` | **proposed** by `propose` (issue #354): `parts.json`'s `scale_rig_per_source`, the `assemble.rig_scale` the rig sections (`bones`, `meshes`, `limbs`, `motion`) were drafted at. Held equal to `assemble.rig_scale` when present (`CONFIG_PROPOSED_RIG_SCALE`; 0, negative or not a number: `CONFIG_FIELD_TYPE`). Absent on a hand-authored config, where no byte of any output moves |
 
 **One drawing, one band; beyond it, another drawing (issue #472).** A single front-facing
@@ -1643,6 +1643,33 @@ idle key: the drafted idle keys none of the trees. A recipe that drafts nothing
 its tag on no part, or `back hair` that ends above the shoulders (a bun) — is refused,
 `PROPOSE_CLOTH_DRAFTED`.
 
+**The config written (issue #537).** `propose --cloth <config.json> --write-config
+<out.json>` writes, beside `proposal.json`, the `--cloth` config's own text with what the
+recipe drafts spliced in, the way `mesh-draft` writes its config: `rig --config <out.json>`
+builds it, and an editor that changes a recipe rebuilds through it rather than merging
+the proposal itself. What is spliced is measured on each run, not listed: the same parts
+are drafted again without the recipe, and each config section whose value differs is
+the recipe's. An object section is spliced entry by entry — `meshes.<part>` and
+`regions.<part>` for each part the recipe moved (a part it takes from `regions` into
+`meshes` leaves `regions`), `motion.tracks` and nothing else under `motion`, so
+`duration`, `blink` and `animations_from` keep their bytes — and `bones` and
+`constraints` whole: **the drafted array replaces the input's**, so a bone or a
+constraint added by hand does not survive a `--write-config`, as a hand-edited lattice
+does not survive `mesh-draft`. Every other byte is the input's; a section the input
+lacks (a config holding only `key` and `cloth`) is inserted. On the selftest's cloth
+fixture (CL201 prints the figures) the recipe moves `bones`, `meshes.hair_back`,
+`meshes.hair_front`, `meshes.skirt`, `motion.tracks` and `constraints`; `limbs` is not
+moved on the public `wind` example with its keypoints, whose tracked config the flag
+wrote back byte for byte (measured once, when the flag landed). The text is written as stated: a relative path in it
+(`motion.animations_from`, `generation.control.skeleton`) resolves against the directory
+the written config sits in, so the out path belongs beside the input, and when it is not
+a note names each such path. Refused before anything is written: `--write-config`
+without `--cloth` or beside `--from-config` (`USAGE`), an out path that exists or that
+the run writes itself (`PROPOSE_WRITE_CONFIG_FRESH`), and a text whose splice does not
+parse to the config with the sections set — a key stated twice
+(`PROPOSE_WRITE_CONFIG_SPLICE`); a recipe that drafts nothing is
+`PROPOSE_CLOTH_DRAFTED` as without the flag.
+
 **A skirt inside topwear (issue #402).** The recipe finds a skirt by the `bottomwear`
 tag alone. When See-through returns the skirt inside `topwear` (a dress), nothing is
 tagged `bottomwear`, and the proposer does not pick the dress by its shape: with
@@ -1834,8 +1861,9 @@ rigc render --candidate out/check/build --animation idle --fps 12 --max 640 --ge
 Read by `CLOTH_SETTLES`'s own definition on the `geometry.json` that writes, none of the
 16 chains settles. The nine that settle under the default world keep moving to the last
 frame: the skirt's eight trees end at 7.66 to 23.79 rig px/s, and the swing at 2.778
-(selftest `CH21` holds this). `check` itself always reads the default world, so `wind`'s
-`check.json` keeps its WARN. The WARN states what the rig does with nothing driving it;
+(selftest `CH21` holds this). `check` without `--environment` reads the default world, so
+`wind`'s tracked `check.json` keeps its WARN; `check --environment examples/wind/breeze.json`
+takes every reading under the breeze instead (§6, *The world the readings are taken in*). The WARN states what the rig does with nothing driving it;
 it is not a fault (`CH20` holds that the idle keys no hip and that the chains which
 settle are exactly the ones no idle key drives). A soft region with no wind response,
 such as `reference-sample`'s `hip_jiggle`, is not reached by an environment at all:
@@ -2850,6 +2878,8 @@ says why each requirement exists and what breaks without it.
 | <a id="PROPOSE_LIMB_PARTS"></a>`PROPOSE_LIMB_PARTS` | `parts.json` holds a standalone or incomplete limb part `config.limbs` cut at its joints (issues #349, #440) that cannot be reassembled into the source part `of` (a missing segment or `cap` record, or `of` still present beside the limb parts); a complete `assemble` output with `config.limbs` reconstructs its pre-limb parts in the same run | `--parts` a complete `assemble` output (every segment of each limb, with its `cap` record) or a build assembled with `config.limbs` left out; `propose --from-config` reads the config's bones on either build |
 | <a id="PROPOSE_CLOTH_DRAFTED"></a>`PROPOSE_CLOTH_DRAFTED` | with `--cloth` (issue #364): the config's `cloth` block holds a recipe for a tag the proposer drafts no chain on — no part has that tag, or every `back hair` part ends above the shoulders (a bun bone, no chain). A `bottomwear` recipe with no `bottomwear` part names every `topwear` part shaped like a skirt (issue #402) | leave that recipe out, or assemble the layer it is for, or declare the named part in `cloth.bottomwear.part` |
 | <a id="PROPOSE_CLOTH_PART"></a>`PROPOSE_CLOTH_PART` | with `--cloth` (issues #402, #437): `cloth.bottomwear.part` (a string) names no part, a part or cut piece whose source is not `topwear` (a `bottomwear` part takes the recipe by its tag already), or a target whose box ends above the hip + 0.25 face heights, the topwear rule's waist line; or `cloth.<tag>.parts` (or `part` as a list, issue #437) names a part not in `parts.json`, a part no link of the drafted tree crosses (`spanCrosses == 0`), or parts out of root-to-tip depth order along the chain | name the `topwear` part or its cut skirt piece that holds the skirt (or leave `part` out), or list only parts in `parts.json` that the drafted tree links cross in root-to-tip order |
+| <a id="PROPOSE_WRITE_CONFIG_FRESH"></a>`PROPOSE_WRITE_CONFIG_FRESH` | with `--write-config` (issue #537): the out path exists, or is a file the run writes itself (`proposal.json`, `basis.json` under `--out`); the config is written to a new file, never over the `--cloth` config or an earlier one | name a file that does not exist yet, beside the `--cloth` config |
+| <a id="PROPOSE_WRITE_CONFIG_SPLICE"></a>`PROPOSE_WRITE_CONFIG_SPLICE` | with `--write-config` (issue #537): the `--cloth` config's text with the drafted sections spliced in does not parse to that config with them set, and the message names the first key that moved — the text states a key twice, so the splice lands on the first and the parse keeps the last | state each key once in the `--cloth` config |
 | <a id="PROPOSE_CLOTH_BACK_HAIR_CHAINS"></a>`PROPOSE_CLOTH_BACK_HAIR_CHAINS` | with `--cloth` (issues #390, #445, #461): `cloth."back hair".chains` exceeds what the narrower side's opaque width at the eye-line root row holds at the part's mesh grid (`max(1, min(floor(w_r / grid), floor(w_l / grid)))`), or places a tree root outside the 15 px dilated art mask of the `back hair` part (e.g. an inner twin-tail root over the face where the hair has no pixel); the message names the part, each side's root-row width, the grid spacing, and any off-art root with its pixel alpha | lower `cloth."back hair".chains` to at most the max fit named in the message, or omit `chains` so `propose --cloth` derives the tree count per visible hair mass on each side from its root-row width |
 | <a id="PROPOSE_ACCESSORY_BODY"></a>`PROPOSE_ACCESSORY_BODY` | an accessory has nothing above its pendant rows to hang its bone on | that part's plan entry, or author its bones by hand |
 | <a id="PROPOSE_TURN_RUN_GIVEN"></a><a id="PROPOSE_TURN_LAYER_PRESENT"></a><a id="PROPOSE_TURN_DEPTH_PRESENT"></a>`PROPOSE_TURN_RUN_GIVEN`, `PROPOSE_TURN_LAYER_PRESENT`, `PROPOSE_TURN_DEPTH_PRESENT` | with `--full`/`--head` (issue #251): a part came from a run whose layers were not given, the run given holds no layer of the part's tag, or its layer carries no `depth_median` while another part's layer carries one; a run with no depth on any part's layer (a PSD, or an export of one) is not refused — the turn is skipped, and the note says `turn: SKIP` and names the run (issue #359) | give the run the parts were assembled from, as the wrapper's `layers.json` |
@@ -3086,8 +3116,41 @@ documents do not ship). Each is an input this package built; none is an author's
 | <a id="REQUIREMENTS_MAY_FOLD"></a>`REQUIREMENTS_MAY_FOLD` | a `may_fold` entry names a slot with no mesh attachment — a region is one quad and cannot fold (issue #320). Refused before anything is built. Before issue #333 an entry naming the idle was refused here too; the bar reads the idle now, and `idle` is an animation name like any other | a mesh slot |
 | <a id="REQUIREMENTS_NOT_PLANTED"></a>`REQUIREMENTS_NOT_PLANTED` | a `not_planted` name is a part `check` does not read as a planted foot — it does not come from a See-through `footwear` layer — or there is no `parts.json` to choose the feet by (issue #231). Refused before anything is built | a `footwear` part's name |
 | <a id="REQUIREMENTS_TIP_EXCEPTION"></a>`REQUIREMENTS_TIP_EXCEPTION` | a `not_swinging`, `rises` or `rests` name is a part `TIP_OVER_ROOT` does not read — not from a See-through `handwear` or `bottomwear` layer — or there is no `parts.json` (refused before anything is built); or a `rises` part is not carried by a chain that rises: the chain's **last link**, at the setup pose, runs other than up — from its origin along its `length` (the extent the rig stage turns a link to), or, a last link with no length, from the link before's origin to its own — the detail giving the link read and the direction measured (refused after the idle is rendered, before `check.json` is written) (issues #231, #322; until #322 it read the chain's first link's origin to its last's, which refused a folded arm — a link that hangs, then a forearm raised) | a swinging part's name; for `rises`, a part whose chain does rise |
+| <a id="CHECK_ENVIRONMENT"></a>`CHECK_ENVIRONMENT` | `check --environment` (or `build --environment`, forwarded): the schedule is refused, the detail rigc's own sentence verbatim. Read once by rig-c's reader (`readEnvironmentSchedule`, `rig-c/src/environment.ts`) before anything is built — nothing at the path, a file that is not JSON or not an object, a `spec` other than `rigc-environment/1`, a key besides `spec`, `steps` or a step's `t`, `wind`, `gravity`, no step, a `t` not finite, below 0 or not after the step before, a `wind` or `gravity` not a pair of finite numbers (JSON's `1e999` reads as `Infinity` and is refused), a step stating neither — and `--out` is not written (`build` refuses under `[assemble]`, before it assembles). After the build, what `rigc render --environment` refuses of a well-formed schedule on this rig, quoted from its `--environment <path>:` line: no physics constraint, a half no constraint answers, two steps on one frame at 12 fps, a step after the last frame of the animation rendered. Also refused before anything is built: a `motion.json` with no animation, where no render `check` makes could pose the schedule | the schedule — rigc's sentence names the entry, the field, the value found and the value required; for a rig with no physics constraint, drop the flag: no world moves it |
 | <a id="REQUIREMENTS_SEAM"></a>`REQUIREMENTS_SEAM` | a `seam` cannot be read against the rig: there is no `parts.json` (a merged rig, §7 *Measuring a rig rig-parts did not assemble*), or the two parts' art does not meet at the setup pose (no 4-adjacent pair). Refused before anything is built | two parts whose art touches, on a rig with its `parts.json` |
 
+**The world the readings are taken in** (`--environment`, issue #538). A physics chain
+answers the world as well as the bones above it, and `check` without the flag reads
+rigc's default world, wind (1, 0) and gravity (0, 1) — not the one a person watched in
+the review editor. `check --environment <schedule.json>` hands a `rigc-environment/1`
+schedule (§3, *What moves them*) to every render whose frames a bar or a warning reads,
+and to none that writes a product: the idle render (`TIP_OVER_ROOT`, `STILL_REGIONS_DARK`,
+`TEXTURE_STRETCH`, `CLOTH_SETTLES`), the physics-on half of `ANIMATIONS_DO_NOT_FOLD`, the
+parts `BREATH_VISIBLE` renders alone, `SEAM_OVER_MOTION` and the `--requirements`
+renders. The renders with the physics left out — the loop's keyed render, the fold
+bar's physics-off half, `STRESS_OFF_CHAIN`'s turned copy and `SEAM_OVER_RANGE`'s bent
+copy — take none: no world moves a skeleton with no physics constraint, and
+`rigc render` refuses a schedule on one (`the skeleton declares no physics constraint,
+so no environment moves anything in it`, rig-c 2.60.0, measured on the fold bar's off
+half). The setup-pose stills (the seam, `BLINK_NO_HOLE`, `SETUP_POSE_VS_SOURCE`) take
+none either: each is a 0.1 s animation read at its first frame, and rigc refuses a step
+after its last (`entry 1's t 0.5 falls after the last frame of every set drawn`,
+measured). `build --loop` encodes a product and takes none. One line,
+`environment: <path>, rigc-environment/1, <n> step(s), sha256 <16 hex>`, says which
+schedule, and `check.json` carries `environment` — `path` as the command line gave it,
+the `sha256` of the bytes read, `steps` — after `pack_mode`; without the flag neither
+is written and no render argument moves.
+
+The world before the first step is the runtime's, so a still schedule is the one that
+states it: `{ "t": 0, "wind": [1, 0], "gravity": [0, 1] }` reads what a run without the
+flag reads — on the cloth fixture (selftest `CK514`), the same idle frames and the same
+`check.json` but for its `environment` key. Wind `[0, 0]` is not that world but a calm,
+and it moves the readings: on the same fixture `TEXTURE_STRETCH` 1.382 → 1.214 and
+`TIP_OVER_ROOT`'s ratio 15.061 → 7.216. A gust that moves the chains moves the bars:
+wind (1, 0), then (40, 0) from 0.5 s, reads `TEXTURE_STRETCH` 32.181 (FAIL, `hair_back`
+triangle 258), two meshes folding under `ANIMATIONS_DO_NOT_FOLD` (FAIL; none without the
+flag) and 8 `CLOTH_SETTLES` warnings for 9 (selftest `CK515`).
+
 ### compose
 
 Every refusal below is collected with the others and printed at once, under

package/docs/STABILITY.md

@@ -53,12 +53,12 @@ defaults are the help's too, and none is guessed from the art.
 | `comfy` | `seethrough`: `--image`, `--out`; optional `--resolution`, `--steps`, `--seed`, `--prefix`, `--offload`, `--lama`, `--nf4`, `--host`, `--wait`, `--timeout`, `--poll` |
 | `assemble` | `--propose-plan` with `--source`, `--full`, `--config`, optional `--head`; or `--source`, `--full`, `--config`, `--out`, optional `--head` (without it, one run: issue #359), `--seam` (near-white, silhouette), `--project` (core, visible), `--alt` (repeatable `<name>=<source>:<full>[:<head>]`, issue #454) |
 | `propose` | `--head-box` with `--full`, `--canvas`; optional `--no-back-hair` |
-| `propose` | `--parts`, `--source`, `--out`; optional `--compare` or `--from-config` (one of them), `--keypoints`, `--person` and `--wrist-snap` (each with `--keypoints`), `--full`, `--head` (the turn control's depths; not with `--from-config`), `--grid-rule` (`figure` or `part`, the drafted lattice's spacing; not with `--from-config`), `--cloth` (a config whose `cloth` block is the recipe, issue #364; not with `--from-config`) |
+| `propose` | `--parts`, `--source`, `--out`; optional `--compare` or `--from-config` (one of them), `--keypoints`, `--person` and `--wrist-snap` (each with `--keypoints`), `--full`, `--head` (the turn control's depths; not with `--from-config`), `--grid-rule` (`figure` or `part`, the drafted lattice's spacing; not with `--from-config`), `--cloth` (a config whose `cloth` block is the recipe, issue #364; not with `--from-config`), `--write-config` (a new file, with `--cloth` and not with `--from-config`, issue #537 — additive: without it nothing `propose` writes changes) |
 | `compare` | `--left`, `--right`; optional `--map` |
 | `rig` | `--config`, `--parts`, `--out`; optional `--idle-keys` (ctl, direct), `--page-edges` (pot, free), `--pack-shape` (rect, polygon) |
-| `check` | `--rig`, `--out`; optional `--parts`, `--source`, `--page-edges`, `--pack-shape`, `--requirements`, `--seam-pairs`, `--keep-stills`, `--set` or `--all-sets` (issue #454) |
+| `check` | `--rig`, `--out`; optional `--parts`, `--source`, `--page-edges`, `--pack-shape`, `--requirements`, `--seam-pairs`, `--keep-stills`, `--set` or `--all-sets` (issue #454), `--environment` (issue #538, additive) |
 | `loop` | `--frames`, `--out`; optional `--palette` |
-| `build` | `--config`, `--source`, `--full`, `--out`; optional `--head` (as for `assemble`), `--seam`, `--project`, `--page-edges`, `--pack-shape`, `--loop`, `--lead-in`, `--requirements`, `--idle-keys`, `--seam-pairs`, `--keep-stills`, `--alt` (as for `assemble`, issue #454), `--set` or `--all-sets` (as for `check`, issue #454) |
+| `build` | `--config`, `--source`, `--full`, `--out`; optional `--head` (as for `assemble`), `--seam`, `--project`, `--page-edges`, `--pack-shape`, `--loop`, `--lead-in`, `--requirements`, `--idle-keys`, `--seam-pairs`, `--keep-stills`, `--alt` (as for `assemble`, issue #454), `--set` or `--all-sets` (as for `check`, issue #454), `--environment` (as for `check`, issue #538, additive) |
 | `compose` | `--scene`, `--out`; optional `--requirements`, `--accept` |
 | `mesh-draft` | `--config`, `--parts`, `--out`; optional `--requirements`, `--idle-keys` (ctl, direct), `--page-edges` (pot, free), `--pack-shape` (rect, polygon), `--more-triangles` |
 | `remesh` | `--rig`, `--config`, `--parts`, `--part`, `--out`, and one of `--mesh` or `--delta` (issue #526); optional `--requirements`, `--idle-keys` (ctl, direct), `--page-edges` (pot, free), `--pack-shape` (rect, polygon) |
@@ -193,11 +193,12 @@ every number) are AUTHORING §3's tables, and the loader refuses any other by na
 | `parts.json`, `parts/<name>.png` | `assemble`, `build` | one record per part: `from` (`<run>:<tag>` with a See-through v3 tag, `<run>:author:<label>` for a layer the author made — issue #256, read by no role rule — or `painting:<name>` for a patch), `cut_from` on a cut's piece only (the plan part it was cut from, issue #230), `limb` on a limb segment's part only (issue #349: `name`, `segment`, `of`, `bone`, and below a joint `joint`, `range` when the config segment declares one (issue #360), and `cap` — `at`, `width`, `radius`, `box`, `layer_px`, `image_px` with a cap image, `image_layer` after it when that image was a hidden-art layer — issue #359, `<run>:<layer>:hidden` — `missing_px`, then `shape` and `upper_px` under the segment's `cap_shape`, and `edge`, `feather_radius` and `feathered_px` under its `edge`, and `cut_band`, `cut_offset`, `cut_at`, `cut_crossed`, `joint_crossed`, `band_px` and `stroke_luma_max` (when the band has a split) under its `cut_band`, issue #360), the box `x`, `y`, `w`, `h` (rig px), the pixel counts `src/parts.ts` documents (`opaque_px`, `visible_px`, `occluded_px`, `projected_core_px`, `source_px_taken`, `visible_not_projected_px`, `refused_drift_px`, `merged_px`, `seam_override_px`, and `fringe_pushed_back` when not empty); `rig_size`, `scale_rig_per_source`, `ghost_px`, `recomposite`, and `scene` (`figure_alpha_above`, `figure_px`, `figure_mask`) under `config.scene` only, with the figure's mask `figure_rig.png` beside the recomposite (issue #242); `single_run_pad` (`file_size`, `side`, `left`, `top`) last, only for one run whose file is not the `seethrough.resolution` square (issue #366) |
 | `rig/rig.json`, `rig/motion.json`, `rig/images/` | `rig`, `build`, `compose` | rig-c's rig spec and motion spec, `spec` `rigc-rig/1` and `rigc-motion/1`: the format is rig-c's, and this package writes only what rig-c's parser accepts; a bone carries `inherit` only where config.bones declares one, rig-c's mode name as written (issue #348) |
 | `rig/mesh_report.json` | `rig`, `build` | one row per mesh: `part`, `vertices`, `triangles`, `hull`, `bones`, `max_influences`, `mean_influences`, `art_coverage`, then `grid` (a lattice); `mode` "contour" with `params`, `contour`, `regions` (`params.maxEdge` and `contour.outlineCut` only when the mesh declares `contour.maxEdge`; `params.bridges` and `contour.bridges` — `islands`, `units`, `joins`, and `faint` only when an island was left out as faint — only when it declares `contour.bridges`); or `mode` "influence" with `influence` (as declared), `reach` (`farthest`, `at`, `nearest`, `capped`, `widest`) and `lattice` (rig-c's `SegmentsLatticeReport`: `cols`, `rows`, `artCells`, `keptCells`, `passes`, `islands`) (issue #378); or `mode` "auto" with `settings`, `source`, `result`, `residuals`, `worst_residual`, `worst_region`, `motion_amplitude`, `termination`, `weights`, `regions`, `deformation`, `quality_report` (rig-c's `mesh-quality-report/1` document whole), `motion_report`, and, only when they apply, `stray_cleared` (after `source`, when `source.stray` is declared), `skinning_residual` and `replay` (`AutoMeshReport` in `src/rig.ts`); in every mode, `exponent` when the mesh declares one (after `grid`, or after `mode`); `influences`, as declared, when a lattice or contour mesh declares it (after `exponent`, or where `exponent` would be); `stray` and `stray_cleared` when a lattice mesh declares `stray` (after `influences`, or where `influences` would be); `ribs` when a contour or auto mesh declares them (after `exponent`, or after `mode`), and then `contour.ribs` (`source.contour.ribs` in the automatic mode) |
-| `check/check.json` and the rest of `check/` | `check`, `build`, `compose` | the reference's fields in its order (`gate_spine_html_green`, `rigc_entry`, `pack_mode`, `loop_max_diff`, the seam figures — `seam_mean`, `seam_px_over_40`, `seam_px_over_80` and, from issue #216, `seam_frame_scale`, the frame scale the bar divides the count by), `loop_physics` after `loop_max_diff` when the rig declares a physics constraint, `seam_border` after the seam figures when `parts.json` declares a scene (issue #242), `seam_pairs` after the seam figures when the seam bar fails or `--seam-pairs` asks (each row's picture under `check/seam/`; `--keep-stills` leaves the setup-pose still and its `frames.json` under `check/setup_still/`), then the judgement lines (`BREATH_VISIBLE`, `BLINK_NO_HOLE`, `CHAIN_LAG`, `TIP_OVER_ROOT`, `STILL_REGIONS_DARK`, `TEXTURE_STRETCH`), `ANIMATIONS_DO_NOT_FOLD` after them when `motion.json` holds an animation, the idle included — on every rig with an idle since issue #333 (issues #320, #363: `status`, `animations`, `fps`, `physics_left_out`, `folding` — each `animation`, `slot`, `attachment`, `frames`, `worst_frame`, `worst_triangles`, `triangles`, `physics_on`, `physics_off`, `physics_constraints`, `declared`, `line` — `folding_undeclared`, `declared_not_folding`, `bar`), `FEET_STAY_LEVEL` after it when a `footwear` part rides a bone that hangs from another and `motion.json` holds an animation (issue #348: `status`, `reason` on a SKIP only, `animations`, `fps`, `physics_left_out`, `bar_degrees`, `bar`, `feet` — each `part`, `bone`, `hangs_from`, `status`, `frames_posed`, `worst`), `LIMB_ONE_BONE` after it (and after `STRESS_OFF_CHAIN` where that is written) when `parts.json` holds a limb segment's part (issue #349: `status`, `parts` — each `part`, `limb`, `bone`, `status`, `others`), `SEAM_OVER_RANGE` after it when a limb record carries a `range` (issue #360: `status`, `frame_scale`, `physics_left_out`, `bar` — `mean`, `rig_px_over_40`, `level` — and `joints`, each `part`, `limb`, `segment`, `joint`, `bone`, `range`, `at`, `radius`, `under_px`, `status`, `poses` — each `degrees`, `status`, `mean`, `px_over_40`, `px_over_80`, `rig_px_over_40` — and `unread` on a joint not read), `SEAM_OVER_MOTION` after it when `parts.json` holds a limb segment or `--requirements` a `seam` (issue #493, a warning and not a bar: `status` — `WARN`, `CLEAR` or `SKIP` — `reason` on a SKIP only, `fps`, `floor`, `pairs` — each `pair`, `a`, `b`, `declared`, and `unread` on a pair not read — `animations`, `warnings`, `rows` — each `pair`, `animation`, `status`, `drawn`, `banded`, `opens`, `px`, `max_px`, `under_floor`), `CLOTH_SETTLES` after it when the rig declares a physics constraint and has an idle (issue #501, a warning and not a bar: `status` — `WARN` or `CLEAR` — `fps`, `frames`, `duration`, `floor_rig_px_per_s`, `floor`, `levers`, `warnings`, `rows` — each `tip`, `root`, `links`, `point`, `settles_at`, `max_rig_px_per_s`, `min_rig_px_per_s`), `RECOMPOSITE_HOLES` (its first figure `declared_scene` when `parts.json` declares a scene), `SETUP_POSE_VS_SOURCE`, `skipped`, a `requirements` block under `--requirements`, and `PASS`; `check/build/skeleton.json`, `.atlas` and `.png` are the packed artifact rig-c writes |
+| `check/check.json` and the rest of `check/` | `check`, `build`, `compose` | the reference's fields in its order (`gate_spine_html_green`, `rigc_entry`, `pack_mode`, `environment` after it under `--environment` only (issue #538, additive: `path` as given, `sha256`, `steps`), `loop_max_diff`, the seam figures — `seam_mean`, `seam_px_over_40`, `seam_px_over_80` and, from issue #216, `seam_frame_scale`, the frame scale the bar divides the count by), `loop_physics` after `loop_max_diff` when the rig declares a physics constraint, `seam_border` after the seam figures when `parts.json` declares a scene (issue #242), `seam_pairs` after the seam figures when the seam bar fails or `--seam-pairs` asks (each row's picture under `check/seam/`; `--keep-stills` leaves the setup-pose still and its `frames.json` under `check/setup_still/`), then the judgement lines (`BREATH_VISIBLE`, `BLINK_NO_HOLE`, `CHAIN_LAG`, `TIP_OVER_ROOT`, `STILL_REGIONS_DARK`, `TEXTURE_STRETCH`), `ANIMATIONS_DO_NOT_FOLD` after them when `motion.json` holds an animation, the idle included — on every rig with an idle since issue #333 (issues #320, #363: `status`, `animations`, `fps`, `physics_left_out`, `folding` — each `animation`, `slot`, `attachment`, `frames`, `worst_frame`, `worst_triangles`, `triangles`, `physics_on`, `physics_off`, `physics_constraints`, `declared`, `line` — `folding_undeclared`, `declared_not_folding`, `bar`), `FEET_STAY_LEVEL` after it when a `footwear` part rides a bone that hangs from another and `motion.json` holds an animation (issue #348: `status`, `reason` on a SKIP only, `animations`, `fps`, `physics_left_out`, `bar_degrees`, `bar`, `feet` — each `part`, `bone`, `hangs_from`, `status`, `frames_posed`, `worst`), `LIMB_ONE_BONE` after it (and after `STRESS_OFF_CHAIN` where that is written) when `parts.json` holds a limb segment's part (issue #349: `status`, `parts` — each `part`, `limb`, `bone`, `status`, `others`), `SEAM_OVER_RANGE` after it when a limb record carries a `range` (issue #360: `status`, `frame_scale`, `physics_left_out`, `bar` — `mean`, `rig_px_over_40`, `level` — and `joints`, each `part`, `limb`, `segment`, `joint`, `bone`, `range`, `at`, `radius`, `under_px`, `status`, `poses` — each `degrees`, `status`, `mean`, `px_over_40`, `px_over_80`, `rig_px_over_40` — and `unread` on a joint not read), `SEAM_OVER_MOTION` after it when `parts.json` holds a limb segment or `--requirements` a `seam` (issue #493, a warning and not a bar: `status` — `WARN`, `CLEAR` or `SKIP` — `reason` on a SKIP only, `fps`, `floor`, `pairs` — each `pair`, `a`, `b`, `declared`, and `unread` on a pair not read — `animations`, `warnings`, `rows` — each `pair`, `animation`, `status`, `drawn`, `banded`, `opens`, `px`, `max_px`, `under_floor`), `CLOTH_SETTLES` after it when the rig declares a physics constraint and has an idle (issue #501, a warning and not a bar: `status` — `WARN` or `CLEAR` — `fps`, `frames`, `duration`, `floor_rig_px_per_s`, `floor`, `levers`, `warnings`, `rows` — each `tip`, `root`, `links`, `point`, `settles_at`, `max_rig_px_per_s`, `min_rig_px_per_s`), `RECOMPOSITE_HOLES` (its first figure `declared_scene` when `parts.json` declares a scene), `SETUP_POSE_VS_SOURCE`, `skipped`, a `requirements` block under `--requirements`, and `PASS`; `check/build/skeleton.json`, `.atlas` and `.png` are the packed artifact rig-c writes |
 | `layers.json`, `<index>_<name>.png` | `layers --export` | the wrapper form `layers` reads (issue #359): `width`, `height`, then `layers` — each `name`, `filename`, `left`, `top`, `right`, `bottom`, `depth_median` (the input's own; `null` for a PSD, the manifest's order then being the draw order) — drawn layers in draw order, then the hidden-art layers; a PNG's name is its index and its layer's name, and the manifest, not the file name, says which layer it is |
 | the template `.psd` | `layers --template` | one empty layer per name `templateLayerNames` (`src/layers.ts`) holds, bottom first; the same canvas writes the same bytes |
 | `proposal.json`, `render/landmarks*.png` | `propose` | the config's four rig sections, `constraints` with `--cloth` (issue #364: a physics constraint per tree link named `<bone>_physics`, a dangling end's `<bone>_translate`, and a skirt swing's transforms `<swing>_<tree>`), `turn` with `--full`/`--head`, `proposed_rig_scale` (issue #354), and `notes` |
 | `basis.json` | `propose` | spec `spine-parts-basis/1` |
+| the `--write-config` file | `propose --cloth … --write-config` | the `--cloth` config read, byte for byte, but for the sections the recipe drafts (issue #537): `bones` and `constraints` whole, and `meshes.<part>`, `regions.<part>` and `motion.tracks` for each entry the recipe moves, measured against the same parts drafted without it; a section the input lacks is inserted |
 | `config.json`, `mesh_draft.json` | `mesh-draft` | `config.json` is the config read, byte for byte, but for each drafted part's `meshes` entry; `mesh_draft.json` is spec `rig-parts-mesh-draft/1`: `rules`, `lattice_check`, `draft_check`, `figure_overdraw`, and per lattice part `part`, `mode`, `lattice`, `candidate` (with `bridges` — `units`, `joins` of `span` and `area_px2`, `area_px2`, `overdraw`, and `faint` only when an island was left out as faint — only when the candidate is a bridged one, issue #326), `delta` (under `--more-triangles` only), `readings`, `gate` (each line's `reading`, `pass`, `text`, `margin`), `note`; and `not_compared` (issue #307), only when the config holds an `auto` or `contour` entry: per such entry, in config order, `part`, `mode` and `note` — the part was neither drafted nor compared, and a config of lattices alone writes no such key |
 | `rig.json`, `motion.json`, `mesh_report.json`, `images/`, `remesh.json` | `remesh` | the input revision's files, `rig.json` and `mesh_report.json` with the part's attachment and row replaced (under `--delta` the row is the input's with its counts, `bones` and influences recomputed and `mode` "delta"), every other file byte for byte; `remesh.json` is spec `rig-parts-remesh/1`: `request` (`part`, `mesh`, `mesh_sha256`, `idle_keys`, `page_edges`, `pack_shape`; under `--delta`, issue #526: `part`, `delta` — the mesh edit as read — `delta_sha256`, `ops`, `applied` — `moved`, `added`, `removed`, `constrained` — `idle_keys`, `page_edges`, `pack_shape`), `versions` (`parts`, `rigc`), `input` (`rig` — `path`, `bytes`, `sha256` per file — `config_sha256`, `parts_json_sha256`), `baseline` (`reproduced`, `not_compared`; under `--delta` `reproduced` holds one sentence: no config is built, the input is the baseline), `target` (`before`, `after`: `vertices`, `triangles`, `hull`), `preserved` (`identical`, `spliced`), `revision` (per file as `input.rig`), `check` (`input`, `revision`: `pass`, `measured`, `not_met`, `skipped`, `physics`; `scope`) |
 | `rig.json`, `motion.json`, `mesh_report.json`, `images/`, `retune.json` | `retune` | the input revision's files, `rig.json` with `constraints` and `invariants.detached` replaced and `motion.json` with `animations.idle` replaced by the config's build, every other file byte for byte; `retune.json` is spec `rig-parts-retune/1`: `request` (`idle_keys`, `page_edges`, `pack_shape`), `versions` (`parts`, `rigc`), `input` (`rig` — `path`, `bytes`, `sha256` per file — `config_sha256`, `parts_json_sha256`), `held` (`compared`, `not_compared`), `changed` (`constraints` — each `name`, `type`, `fields` — `added`, `removed`, `idle`: `tracks_changed`, `duration` as before and after), `preserved` (`identical`, `spliced`), `revision` (per file as `input.rig`), `check` (`input`, `revision`: `pass`, `measured`, `not_met`, `skipped`, `physics`; `scope`) |

package/package.json

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

package/src/build.ts

@@ -70,7 +70,7 @@ import {
   splitSchedule,
   untestedIntervals,
 } from './autoreplay.ts';
-import { besideIdleLine, CLOTH_LINE, type ClothLine, clothWarnText, frameRuns, MOTION_SEAM_LINE, type MotionSeamLine, type MotionSeamPlant, motionSeamWarnText, FOLD_LINE, type FoldsLine, LEVEL_LINE, type LevelLine, LIMB_LINE, type LimbLine, STRESS_LINE, SWEEP_LINE, type SweepLine, buildGateLines, causeLines, IDLE_FPS, IDLE_MAX_PX, maxRgbDiff, REQUIREMENTS_DIR, type CheckReport, type PackLine, DEFAULT_PACK_SHAPE, DEFAULT_PAGE_EDGES, GATE_PROFILE, JUDGEMENT_LINES, type JudgementLine, packedBuildArgs, packedBuildLabel, type PackMode, type PackShape, type PageEdges, readFrameSet, rigcFailed, rigcIdentity, rigcRanClause, REPORTED_LINES, type ReportedLine, type RigcRunner, runCheck, SEAM_DIR, SEAM_MEAN_BAR, seamPairText, seamRigPxText, SOURCE_LINE, SEAM_PX_BAR, SEAM_PX_LEVEL, SEAM_PX_LEVEL_HIGH, SPINEBOY_YARDSTICK, STILL_DIR } from './check.ts';
+import { besideIdleLine, CLOTH_LINE, type ClothLine, clothWarnText, frameRuns, MOTION_SEAM_LINE, type MotionSeamLine, type MotionSeamPlant, motionSeamWarnText, FOLD_LINE, type FoldsLine, LEVEL_LINE, type LevelLine, LIMB_LINE, type LimbLine, STRESS_LINE, SWEEP_LINE, type SweepLine, buildGateLines, causeLines, environmentLine, IDLE_FPS, IDLE_MAX_PX, maxRgbDiff, REQUIREMENTS_DIR, type CheckReport, type PackLine, DEFAULT_PACK_SHAPE, DEFAULT_PAGE_EDGES, GATE_PROFILE, JUDGEMENT_LINES, type JudgementLine, packedBuildArgs, packedBuildLabel, type PackMode, readCheckEnvironment, type PackShape, type PageEdges, readFrameSet, rigcFailed, rigcIdentity, rigcRanClause, REPORTED_LINES, type ReportedLine, type RigcRunner, runCheck, SEAM_DIR, SEAM_MEAN_BAR, seamPairText, seamRigPxText, SOURCE_LINE, SEAM_PX_BAR, SEAM_PX_LEVEL, SEAM_PX_LEVEL_HIGH, SPINEBOY_YARDSTICK, STILL_DIR } from './check.ts';
 import { type Cut, type Extend, type Limb, loadConfig, loadConfigAndAnimations, loadEarlyConfig, type Patch, type PlanEntry } from './config.ts';
 import { failLine, PartsError, type Problem, refuseIfAny } from './errors.ts';
 import type { MeshQualityReport, MotionSchedule } from 'rig-c/mesh';
@@ -1359,6 +1359,11 @@ export interface CheckStageInput {
   set?: string;
   /** `check --all-sets` (issue #454): measure every declared alternate set's setup-pose seam and recomposite figures. */
   allSets?: boolean;
+  /**
+   * `check --environment <file>` (issue #538): a `rigc-environment/1` schedule every render a bar or a warning reads
+   * with the physics on is posed under; absent, no render argument and no byte of `check.json` moves.
+   */
+  environment?: string;
 }
 
 /**
@@ -1581,7 +1586,8 @@ export function checkStage(input: CheckStageInput, rigc: RigcRunner, bin: string
   const entryLine = versionLines.find((l) => l.startsWith('entry:'));
   log(`  ${rigcIdentity(bin, v)}${entryLine === undefined ? '' : `; ${entryLine}`}`);
   const mode: PackMode = { pageEdges: input.pageEdges ?? DEFAULT_PAGE_EDGES, packShape: input.packShape ?? DEFAULT_PACK_SHAPE };
-  const r = runCheck(input.rig, input.out, rigc, input.parts, mode, input.source, input.requirements, input.seamPairs === true, input.keepStills === true, input.set, input.allSets === true);
+  const r = runCheck(input.rig, input.out, rigc, input.parts, mode, input.source, input.requirements, input.seamPairs === true, input.keepStills === true, input.set, input.allSets === true, input.environment);
+  if (r.figures.environment !== undefined) log(`  ${environmentLine(r.figures.environment)}`);
   log(`  gate rig-play (rigc ${packedBuildLabel(mode)}), verbatim:`);
   for (const l of r.gateHtml) log(l);
   for (const l of packLines(r)) log(`  ${l}`);
@@ -1920,6 +1926,8 @@ export interface BuildInput {
   set?: string;
   /** `--all-sets`, forwarded to the check as `check` takes it (issue #454). */
   allSets?: boolean;
+  /** `--environment <file>`, forwarded to the check as `check` takes it (issue #538): read before assemble runs, so a schedule check would refuse is refused first; absent, nothing moves. */
+  environment?: string;
 }
 
 /** What `build` does with one flag `check` takes: hands it to its check stage, takes it as its own, or refuses it because build supplies the value itself. */
@@ -1946,6 +1954,7 @@ export const CHECK_FLAGS_IN_BUILD: Readonly<Record<string, CheckFlagInBuild>> =
   '--all-sets': { as: 'forwarded' },
   '--seam-pairs': { as: 'forwarded' },
   '--keep-stills': { as: 'forwarded' },
+  '--environment': { as: 'forwarded' },
 };
 
 /** The `build` refusal of a `check` flag build supplies itself ({@link CHECK_FLAGS_IN_BUILD}), or null for any other flag. */
@@ -2039,6 +2048,8 @@ export function build(input: BuildInput, run: BuildRunners, log: Log): BuildResu
     loadConfig(input.config);
     // The same for the requirements file's own shape; its names resolve against the rig, in the check, before it builds.
     if (input.requirements !== undefined) readRequirements(input.requirements);
+    // And the schedule (issue #538), by rigc's own reader, as check reads it.
+    if (input.environment !== undefined) readCheckEnvironment(input.environment);
     assembleStage(
       { source: input.source, full: input.full, head: input.head, config: input.config, seam: input.seam, project: input.project, ...(input.alts === undefined ? {} : { alts: input.alts }) },
       { partsJson: join(out, 'parts.json'), partsDir: join(out, 'parts'), recomposite: join(out, 'recomposite_rig.png'), errorMap: join(out, ERROR_MAP_FILE) },
@@ -2056,7 +2067,7 @@ export function build(input: BuildInput, run: BuildRunners, log: Log): BuildResu
 
   let report: CheckReport;
   try {
-    report = checkStage({ rig: join(out, 'rig'), parts: out, out: join(out, 'check'), pageEdges: input.pageEdges, packShape: input.packShape, ...(input.requirements === undefined ? {} : { requirements: input.requirements }), seamPairs: input.seamPairs === true, keepStills: input.keepStills === true, ...(input.set === undefined ? {} : { set: input.set }), allSets: input.allSets === true }, run.check, run.checkBin, prefixed('check'));
+    report = checkStage({ rig: join(out, 'rig'), parts: out, out: join(out, 'check'), pageEdges: input.pageEdges, packShape: input.packShape, ...(input.requirements === undefined ? {} : { requirements: input.requirements }), seamPairs: input.seamPairs === true, keepStills: input.keepStills === true, ...(input.set === undefined ? {} : { set: input.set }), allSets: input.allSets === true, ...(input.environment === undefined ? {} : { environment: input.environment }) }, run.check, run.checkBin, prefixed('check'));
   } catch (err) {
     return refused('check', err);
   }

package/src/check.ts

@@ -77,6 +77,7 @@
  * the last idle frame is refused unless it sits at t = duration (within
  * `TIME_SLACK`, issue #244).
  */
+import { createHash } from 'node:crypto';
 import { copyFileSync, cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { basename, delimiter, dirname, join, resolve } from 'node:path';
 import { measureRecomposite, type RecompositeFigures, recompositeRecord, scenePhrase, sourceInRig } from './assemble.ts';
@@ -158,6 +159,7 @@ import {
 } from './requirements.ts';
 import { RIG_BONE_INHERIT, type RigSpec as RigcRigSpec } from 'rig-c/src/rig.ts';
 import { expandStops } from 'rig-c/src/stop.ts';
+import { ENVIRONMENT_SPEC, EnvironmentError, readEnvironmentSchedule } from 'rig-c/src/environment.ts';
 import { alphaComposite } from './raster/composite.ts';
 import { readPng, writePng } from './raster/png.ts';
 import { newFloatImage, newRaster, type Raster } from './raster/types.ts';
@@ -1814,6 +1816,12 @@ export interface CheckFigures {
   rigc_entry: RigcEntryRecord;
   /** How the artifact's page was packed: the `--page-edges` and `--pack-shape` rigc was handed, which its pack line was read to agree with ({@link packEdgeProblems}). Provenance, not a bar. */
   pack_mode: { page_edges: PageEdges; pack_shape: PackShape };
+  /**
+   * Written only under `--environment` (issue #538): the `rigc-environment/1` schedule every measured render was posed
+   * under — the path as the command line gave it, the sha256 of the bytes read, and how many steps rigc's reader read
+   * off them ({@link readCheckEnvironment}). Provenance, not a bar; without the flag no key is written.
+   */
+  environment?: CheckEnvironment;
   /** Null when the rig has no idle (issue #77); `skipped.loop` then says why. */
   loop_max_diff: number | null;
   /**
@@ -3577,6 +3585,61 @@ export function rigcFailed(what: string, call: RigcCall, lines: readonly string[
   return quoted.map((l) => ({ code: 'CHECK_RIGC_GREEN', object, detail: `exit ${call.status}: ${l}${ran}` }));
 }
 
+// ---------------------------------------------------------------------------
+// the world the readings are taken in (issue #538)
+// ---------------------------------------------------------------------------
+
+/** The refusal of a schedule `check --environment` names: rigc's reader's sentence, or rigc render's, verbatim. */
+export const ENVIRONMENT_RULE = 'CHECK_ENVIRONMENT';
+
+/** What `check.json` records of the schedule under `--environment`: provenance, not a bar. */
+export interface CheckEnvironment {
+  /** The path as the command line gave it — never resolved, so the record holds no directory the caller did not type. */
+  path: string;
+  /** The sha256 of the file's bytes as read, the bytes rigc's reader read. */
+  sha256: string;
+  /** How many steps rigc's reader read off it. */
+  steps: number;
+}
+
+function environmentRefused(given: string, sentence: string): PartsError {
+  return new PartsError([{ code: ENVIRONMENT_RULE, object: given, detail: sentence }]);
+}
+
+/**
+ * `--environment <file>` read once, before anything is built (issue #538): the file's bytes hashed and handed to
+ * rig-c's own reader, `readEnvironmentSchedule` (`rig-c/src/environment.ts`), which refuses every malformed schedule
+ * — a `spec` other than {@link ENVIRONMENT_SPEC}, a key it does not read, no step, a `t` that is not finite, at or
+ * above 0 and after the step before, a `wind` or `gravity` that is not a pair of finite numbers, a step that changes
+ * nothing — by entry, field, the value found and the value required. Nothing here reads the schedule's meaning: its
+ * sentence is carried as {@link ENVIRONMENT_RULE}'s detail, verbatim, and a path with no file at it is worded as
+ * `rigc render --environment` words it. What a well-formed schedule cannot do to this rig — move a rig with no
+ * physics constraint, change a half no constraint answers, fall after the last frame drawn — is rigc render's to
+ * refuse, and {@link runCheck} carries that sentence the same way.
+ */
+export function readCheckEnvironment(given: string): CheckEnvironment {
+  const path = resolve(given);
+  if (!existsSync(path) || !statSync(path).isFile()) throw environmentRefused(given, `--environment ${given}: nothing at ${path} — it takes a schedule file { "spec": "${ENVIRONMENT_SPEC}", "steps": [...] }`);
+  let bytes: Buffer;
+  try {
+    bytes = readFileSync(path);
+  } catch (err) {
+    throw environmentRefused(given, `--environment ${given}: not readable — ${(err as Error).message}`);
+  }
+  try {
+    const steps = readEnvironmentSchedule(bytes.toString('utf8'), given);
+    return { path: given, sha256: createHash('sha256').update(bytes).digest('hex'), steps: steps.length };
+  } catch (err) {
+    if (err instanceof EnvironmentError) throw environmentRefused(given, err.message);
+    throw err;
+  }
+}
+
+/** The line `check` prints under `--environment`, beside rigc's identity: which schedule, by path and digest, and which renders it poses. */
+export function environmentLine(env: CheckEnvironment): string {
+  return `environment: ${env.path}, ${ENVIRONMENT_SPEC}, ${env.steps} step(s), sha256 ${env.sha256.slice(0, 16)} — every render a bar or a warning reads with the physics on is posed under it; the physics-off, setup-pose and loop renders are not`;
+}
+
 /**
  * Run the whole check. Refuses (throws a PartsError) when the inputs are
  * unreadable or a rigc step that everything after it depends on is red — the
@@ -3603,23 +3666,28 @@ export function rigcFailed(what: string, call: RigcCall, lines: readonly string[
  * MEASURABLE is a problem. Without it nothing here reads, writes or prints
  * anything it did not before.
  */
-export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, partsHome?: string, mode: PackMode = DEFAULT_PACK_MODE, source?: string, requirements?: string, seamPairsAsked = false, keepStills = false, set?: string, allSets = false): CheckReport {
+export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, partsHome?: string, mode: PackMode = DEFAULT_PACK_MODE, source?: string, requirements?: string, seamPairsAsked = false, keepStills = false, set?: string, allSets = false, environment?: string): CheckReport {
   let inp: CheckInputs;
   let reqFile: RequirementsFile | null = null;
   let seams: Map<string, SeamPair[]> | null = null;
-  if (requirements === undefined) inp = readCheckInputs(rigDir, partsHome, source, set, allSets);
-  else {
-    // Both readers collect every problem; one refusal names both sets.
-    const refused: Problem[] = [];
-    const take = <T>(read: () => T): T | null => {
-      try {
-        return read();
-      } catch (err) {
-        if (!(err instanceof PartsError)) throw err;
-        refused.push(...err.problems);
-        return null;
-      }
-    };
+  // Every reader collects every problem; one refusal names every set.
+  const refused: Problem[] = [];
+  const take = <T>(read: () => T): T | null => {
+    try {
+      return read();
+    } catch (err) {
+      if (!(err instanceof PartsError)) throw err;
+      refused.push(...err.problems);
+      return null;
+    }
+  };
+  // Issue #538: the schedule is read once, first, by rigc's own reader; refused, nothing is built or written.
+  const env = environment === undefined ? null : take(() => readCheckEnvironment(environment));
+  if (requirements === undefined) {
+    const got = take(() => readCheckInputs(rigDir, partsHome, source, set, allSets));
+    refuseIfAny(refused);
+    inp = got as CheckInputs;
+  } else {
     const got = take(() => readCheckInputs(rigDir, partsHome, source, set, allSets));
     reqFile = take(() => readRequirements(requirements));
     refuseIfAny(refused);
@@ -3638,7 +3706,29 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
     }
     refuseIfAny(refused);
   }
+  // Issue #538: a motion with no animation gives check no render a schedule could pose — every frame it reads would be
+  // the setup still's — so the flag is refused rather than recorded over readings it did not move.
+  if (env !== null && !(isRecord(inp.motion.animations) && Object.keys(inp.motion.animations).length > 0)) {
+    throw environmentRefused(env.path, `${inp.motionPath} holds no animation, so check renders no frame a schedule could pose — the setup-pose stills take none; rigc render reads a schedule only over an animation's frames`);
+  }
   const rigcEntry = readRigcEntry(requireRigcVersion(rigc));
+  /**
+   * Issue #538: a render whose frames a bar or a warning reads, with the physics on — posed under the schedule when
+   * `--environment` names one (the path as given; rigc reads the file the same way). A refusal rigc render prints of
+   * the schedule against this rig (its `--environment <path>:` line) is carried as {@link ENVIRONMENT_RULE}, verbatim;
+   * any other failure is the call site's to name. Without the flag it is `rigc`, and no argument moves.
+   */
+  const measured: RigcRunner =
+    env === null
+      ? rigc
+      : (args) => {
+          const call = rigc([...args, '--environment', env.path]);
+          if (call.status !== 0) {
+            const said = call.out.split('\n').map((l) => l.trim()).find((l) => l.startsWith(`rigc: --environment ${env.path}: `));
+            if (said !== undefined) throw environmentRefused(env.path, `${said.slice('rigc: '.length)}${rigcRanClause(call)}`);
+          }
+          return call;
+        };
   const out = resolve(outDir);
   mkdirSync(out, { recursive: true });
   const buildDir = join(out, 'build');
@@ -3709,7 +3799,7 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
   const levelProblems: Problem[] = [];
   try {
     if (inp.idleDuration !== null) {
-      const render = rigc(['render', '--candidate', buildDir, '--animation', 'idle', '--fps', String(IDLE_FPS), '--max', String(IDLE_MAX_PX), '--geometry', '--out', idleDir]);
+      const render = measured(['render', '--candidate', buildDir, '--animation', 'idle', '--fps', String(IDLE_FPS), '--max', String(IDLE_MAX_PX), '--geometry', '--out', idleDir]);
       if (render.status !== 0) refuseIfAny(rigcFailed('render --animation idle --geometry', render, render.out.split('\n').filter((l) => l.includes('FAIL') || l.includes('rigc:'))));
       idle = readFrameSet(idleDir);
       const last = idle.frames[idle.frames.length - 1];
@@ -3784,7 +3874,7 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
         // Issue #348: with a foot to read, the keyed render writes each animation's geometry as well.
         const geometry = feet.length > 0 ? ['--geometry'] : [];
         if (stripped === null) {
-          const fr = rigc(['render', '--candidate', buildDir, '--folds', ...geometry, '--fps', String(fps), '--max', String(FOLD_RENDER_MAX), '--out', foldDir]);
+          const fr = measured(['render', '--candidate', buildDir, '--folds', ...geometry, '--fps', String(fps), '--max', String(FOLD_RENDER_MAX), '--out', foldDir]);
           if (fr.status !== 0) refuseIfAny(rigcFailed(`render --folds${geometry.map((g) => ` ${g}`).join('')} --fps ${fps}`, fr, fr.out.split('\n').filter((l) => l.includes('FAIL') || l.includes('rigc:'))));
           const readings = filterFolds(readFoldSets(foldDir, animationNames, fps, fr.out));
           folds = foldsLine(animationNames, fps, 0, readings, mayFoldForRun, reqFile === null ? null : reqFile.path, foldProblems, readings, inp.rig, []);
@@ -3800,8 +3890,10 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
         } else {
           const onDir = join(foldDir, 'on');
           const offDir = join(foldDir, 'off');
-          const frOn = rigc(['render', '--candidate', buildDir, '--folds', '--fps', String(fps), '--max', String(FOLD_RENDER_MAX), '--out', onDir]);
+          const frOn = measured(['render', '--candidate', buildDir, '--folds', '--fps', String(fps), '--max', String(FOLD_RENDER_MAX), '--out', onDir]);
           if (frOn.status !== 0) refuseIfAny(rigcFailed(`render --folds --fps ${fps}`, frOn, frOn.out.split('\n').filter((l) => l.includes('FAIL') || l.includes('rigc:'))));
+          // The physics-off half takes no schedule (issue #538): its candidate declares no physics constraint, so no
+          // world moves it, and rigc render refuses a schedule on it by name.
           const frOff = rigc(['render', '--candidate', keyedBuild('the animations with their physics constraint(s) left out'), '--folds', ...geometry, '--fps', String(fps), '--max', String(FOLD_RENDER_MAX), '--out', offDir]);
           if (frOff.status !== 0) refuseIfAny(rigcFailed(`render --folds${geometry.map((g) => ` ${g}`).join('')} --fps ${fps} (physics constraint(s) left out)`, frOff, frOff.out.split('\n').filter((l) => l.includes('FAIL') || l.includes('rigc:'))));
           const readingsOn = filterFolds(readFoldSets(onDir, animationNames, fps, frOn.out));
@@ -3828,7 +3920,7 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
   // 3b. the parts a judgement reads alone: each rendered by its own slots, on the whole rig's grid
   const isolated = (label: string, ps: readonly PartRecord[]): FrameSet => {
     const dir = join(isoDir, label);
-    const r = rigc(['render', '--candidate', buildDir, '--animation', 'idle', '--fps', String(IDLE_FPS), '--max', String(IDLE_MAX_PX), '--slot', ps.map((p) => p.name).join(','), '--out', dir]);
+    const r = measured(['render', '--candidate', buildDir, '--animation', 'idle', '--fps', String(IDLE_FPS), '--max', String(IDLE_MAX_PX), '--slot', ps.map((p) => p.name).join(','), '--out', dir]);
     if (r.status !== 0) refuseIfAny(rigcFailed(`render --animation idle --slot ${ps.map((p) => p.name).join(',')}`, r, r.out.split('\n').filter((l) => l.includes('FAIL') || l.includes('rigc:'))));
     return readFrameSet(dir);
   };
@@ -3853,7 +3945,7 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
     if (b.status !== 0) refuseIfAny(rigcFailed(`${packedBuildLabel(mode)} (BREATH_VISIBLE's copy, the idle beside it with its breath tracks held at rest)`, b, buildGateLines(b.out)));
     const slots = ps.map((p) => p.name).join(',');
     const render = (animation: string, label: string): FrameSet => {
-      const r = rigc(['render', '--candidate', join(dir, 'build'), '--animation', animation, '--fps', String(IDLE_FPS), '--max', String(IDLE_MAX_PX), '--slot', slots, '--out', join(dir, label)]);
+      const r = measured(['render', '--candidate', join(dir, 'build'), '--animation', animation, '--fps', String(IDLE_FPS), '--max', String(IDLE_MAX_PX), '--slot', slots, '--out', join(dir, label)]);
       if (r.status !== 0) refuseIfAny(rigcFailed(`render --animation ${animation} --slot ${slots} (BREATH_VISIBLE's copy)`, r, r.out.split('\n').filter((l) => l.includes('FAIL') || l.includes('rigc:'))));
       return readFrameSet(join(dir, label));
     };
@@ -4003,7 +4095,7 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
       rmSync(seamMotionDir, { recursive: true, force: true });
       try {
         const list = read.map((p) => `${p.a}:${p.b}`).join(',');
-        const r = rigc(['render', '--candidate', buildDir, '--seam', list, '--fps', String(fps), '--max', String(FOLD_RENDER_MAX), '--out', seamMotionDir]);
+        const r = measured(['render', '--candidate', buildDir, '--seam', list, '--fps', String(fps), '--max', String(FOLD_RENDER_MAX), '--out', seamMotionDir]);
         if (r.status !== 0) refuseIfAny(rigcFailed(`render --seam ${list} --fps ${fps}`, r, r.out.split('\n').filter((l) => l.includes('FAIL') || l.includes('rigc:'))));
         motionSeam = motionSeamLine(pairs, animationNames, fps, readMotionSeams(seamMotionDir, animationNames, fps, read));
       } finally {
@@ -4183,7 +4275,7 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
 
   // 5. the scene's declared requirements (issue #93), only under --requirements
   const reqProblems: Problem[] = [];
-  const reqBlock = reqFile === null ? null : measureRequirements(inp, reqFile, buildDir, out, rigc, reqProblems, seams ?? new Map());
+  const reqBlock = reqFile === null ? null : measureRequirements(inp, reqFile, buildDir, out, rigc, reqProblems, seams ?? new Map(), measured);
 
   const skipped: { loop?: string; seam?: string } = {};
   if (inp.noIdle !== null) skipped.loop = inp.noIdle;
@@ -4192,6 +4284,7 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
     gate_spine_html_green: htmlGreen,
     rigc_entry: rigcEntry,
     pack_mode: { page_edges: mode.pageEdges, pack_shape: mode.packShape },
+    ...(env === null ? {} : { environment: env }),
     loop_max_diff: loop === null ? null : loop.max,
     ...(loopPhysics === null ? {} : { loop_physics: loopPhysics }),
     seam_mean: seam === null ? null : round3(seam.mean),
@@ -4329,7 +4422,7 @@ const REQUIREMENTS_SCRATCH = '_requirements';
  * `CHECK_RIGC_GREEN`, quoting rigc. Lines go into the returned block; each
  * FAIL and NOT MEASURABLE into `problems`.
  */
-export function measureRequirements(inp: CheckInputs, file: RequirementsFile, buildDir: string, out: string, rigc: RigcRunner, problems: Problem[], seams: ReadonlyMap<string, readonly SeamPair[]> = new Map()): RequirementsBlock {
+export function measureRequirements(inp: CheckInputs, file: RequirementsFile, buildDir: string, out: string, rigc: RigcRunner, problems: Problem[], seams: ReadonlyMap<string, readonly SeamPair[]> = new Map(), render: RigcRunner = rigc): RequirementsBlock {
   const reqDir = join(out, REQUIREMENTS_DIR);
   const scratch = join(out, REQUIREMENTS_SCRATCH);
   for (const d of [reqDir, scratch]) rmSync(d, { recursive: true, force: true });
@@ -4350,7 +4443,7 @@ export function measureRequirements(inp: CheckInputs, file: RequirementsFile, bu
     return b.dir;
   };
   const posesOf = (candidate: string, animation: string, dir: string, label: string): { poses: Poses; geo: IdleGeometry; path: string } => {
-    const r = rigc(['render', '--candidate', candidate, '--animation', animation, '--fps', String(file.fps), '--max', String(IDLE_MAX_PX), '--geometry', '--out', dir]);
+    const r = render(['render', '--candidate', candidate, '--animation', animation, '--fps', String(file.fps), '--max', String(IDLE_MAX_PX), '--geometry', '--out', dir]);
     if (r.status !== 0) refuseIfAny(rigcFailed(`render --animation ${animation} --geometry (${label})`, r, r.out.split('\n').filter((l) => l.includes('FAIL') || l.includes('rigc:'))));
     const set = readFrameSet(dir);
     if (set.written !== set.sampled || set.stride !== 1) {

package/src/clothconfig.ts

@@ -0,0 +1,67 @@
+/**
+ * `propose --cloth … --write-config <out.json>` (issue #537): the `--cloth` config's own text with the sections the
+ * recipe drafts spliced in, the way `mesh-draft` writes its config ({@link splicedEdits}). The producer is the one
+ * writer of its own config; a reviewer that edits a recipe rebuilds through it.
+ *
+ * What is spliced is measured, not listed: the same parts drafted twice, once with the recipe and once without it
+ * (`cloth: null`), and each config section of the proposal ({@link PROPOSAL_CONFIG_SECTIONS}) whose value differs
+ * between the two is drafted ({@link clothConfigEdits}). An object section (`meshes`, `regions`, `motion`) is
+ * spliced entry by entry — `meshes.<part>` and `regions.<part>` for each part the recipe moved, `motion.tracks` and
+ * not the author's `animations_from` — and an array section (`bones`, `constraints`) whole: the drafted array
+ * replaces the input's, so a bone the author added by hand does not survive a write. A section the recipe does not
+ * move keeps the input's bytes.
+ */
+
+import { PartsError } from './errors.ts';
+import { type ConfigEdit, splicedEdits } from './meshdraft.ts';
+import { PROPOSAL_CONFIG_SECTIONS, type Proposal } from './propose.ts';
+
+function isPlain(v: unknown): v is Record<string, unknown> {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/**
+ * The edits that turn a config holding the draft without the recipe (`plain`) into one holding the draft with it
+ * (`drafted`): for each config section whose value differs, an object section entry by entry (an entry the recipe
+ * removed, such as a part it took from `regions` into `meshes`, is removed) and any other section whole.
+ */
+export function clothConfigEdits(drafted: Proposal, plain: Proposal): ConfigEdit[] {
+  const edits: ConfigEdit[] = [];
+  const d = drafted as unknown as Record<string, unknown>;
+  const p = plain as unknown as Record<string, unknown>;
+  for (const section of PROPOSAL_CONFIG_SECTIONS) {
+    const a = p[section];
+    const b = d[section];
+    if (JSON.stringify(a) === JSON.stringify(b)) continue;
+    if (isPlain(a) && isPlain(b)) {
+      for (const k of [...Object.keys(b), ...Object.keys(a).filter((k) => !(k in b))]) {
+        if (JSON.stringify(a[k]) !== JSON.stringify(b[k])) edits.push({ path: [section, k], value: b[k] });
+      }
+    } else edits.push({ path: [section], value: b });
+  }
+  return edits;
+}
+
+/**
+ * The config `--write-config` writes: `text` (the `--cloth` config at `where`) with {@link clothConfigEdits} spliced
+ * in. Refused, `PROPOSE_WRITE_CONFIG_SPLICE`, when the spliced text does not parse to the input with those edits
+ * made — the text states a key twice, so the edit lands on one and the parse keeps the other.
+ */
+export function writtenClothConfig(where: string, text: string, edits: readonly ConfigEdit[]): string {
+  const r = splicedEdits(text, edits);
+  if (r.moved !== null) {
+    throw new PartsError([
+      {
+        code: 'PROPOSE_WRITE_CONFIG_SPLICE',
+        object: where,
+        detail: `the drafted sections spliced into this text do not parse to the config with them set: ${r.moved} moved (the text states a key twice, so the splice lands on the first and the parse keeps the last); state each key once`,
+      },
+    ]);
+  }
+  return r.text;
+}
+
+/** The paths the edits name, dotted, in order: what the write line prints. */
+export function editPaths(edits: readonly ConfigEdit[]): string[] {
+  return edits.map((e) => e.path.join('.'));
+}

package/src/meshdraft.ts

@@ -483,8 +483,11 @@ export function partsNamed(p: Problem, among: readonly string[], seams: { draft:
 // the config written: the input's own text, with the drafted entries spliced in
 // ---------------------------------------------------------------------------
 
-/** Where a JSON value starts and ends in a text, by a path of object keys. Throws when the path does not resolve. */
-export function jsonValueSpan(text: string, path: readonly string[]): { start: number; end: number } {
+/**
+ * Where a JSON value starts and ends in a text, by a path of object keys, and (for a non-empty path) where the key
+ * naming it starts (`key`, its opening quote). Throws when the path does not resolve.
+ */
+export function jsonValueSpan(text: string, path: readonly string[]): { start: number; end: number; key?: number } {
   let i = 0;
   const ws = (): void => {
     while (i < text.length && /\s/.test(text[i])) i++;
@@ -530,22 +533,27 @@ export function jsonValueSpan(text: string, path: readonly string[]): { start: n
     }
     while (i < text.length && !/[\s,}\]]/.test(text[i])) i++;
   };
-  const find = (depth: number): { start: number; end: number } => {
+  let keyAt: number | undefined;
+  const find = (depth: number): { start: number; end: number; key?: number } => {
     ws();
     if (depth === path.length) {
       const start = i;
       skip();
-      return { start, end: i };
+      return keyAt === undefined ? { start, end: i } : { start, end: i, key: keyAt };
     }
     if (text[i] !== '{') throw new Error(`jsonValueSpan: ${path.slice(0, depth).join('.') || 'the document'} is not an object`);
     i++;
     for (;;) {
       ws();
       if (text[i] === '}') throw new Error(`jsonValueSpan: no key "${path[depth]}" at ${path.slice(0, depth).join('.') || 'the top'}`);
+      const at = i;
       const key = str();
       ws();
       i++; // ':'
-      if (key === path[depth]) return find(depth + 1);
+      if (key === path[depth]) {
+        keyAt = at;
+        return find(depth + 1);
+      }
       skip();
       ws();
       if (text[i] === ',') i++;
@@ -554,25 +562,111 @@ export function jsonValueSpan(text: string, path: readonly string[]): { start: n
   return find(0);
 }
 
+/** One edit {@link splicedEdits} makes: the value at `path` set (replaced, or inserted when absent), or, `undefined`, removed. */
+export interface ConfigEdit {
+  path: readonly string[];
+  value: unknown;
+}
+
+/** The span at `path`, or null where the path does not resolve (a key absent, or a step that is not an object). */
+function spanOrNull(text: string, path: readonly string[]): { start: number; end: number; key?: number } | null {
+  try {
+    return jsonValueSpan(text, path);
+  } catch {
+    return null;
+  }
+}
+
+/** The white space a line starts with, for the line `at` lies on. */
+function indentAt(text: string, at: number): string {
+  const lineStart = text.lastIndexOf('\n', at) + 1;
+  return /^[ \t]*/.exec(text.slice(lineStart))?.[0] ?? '';
+}
+
+/** One edit on `text`; every byte it does not name is the input's. */
+function spliceOne(text: string, path: readonly string[], value: unknown): string {
+  const at = spanOrNull(text, path);
+  if (value === undefined) {
+    if (at === null || at.key === undefined) return text;
+    // The member and one comma beside it: the one before it, or (the first member) the one after it.
+    let before = at.key - 1;
+    while (before >= 0 && /\s/.test(text[before])) before--;
+    if (text[before] === ',') return `${text.slice(0, before)}${text.slice(at.end)}`;
+    let after = at.end;
+    while (after < text.length && /\s/.test(text[after])) after++;
+    if (text[after] === ',') {
+      after++;
+      while (after < text.length && /\s/.test(text[after])) after++;
+      return `${text.slice(0, at.key)}${text.slice(after)}`;
+    }
+    return `${text.slice(0, at.key)}${text.slice(at.end)}`;
+  }
+  if (at !== null) {
+    const body = JSON.stringify(value, null, 2).split('\n').join(`\n${indentAt(text, at.start)}`);
+    return `${text.slice(0, at.start)}${body}${text.slice(at.end)}`;
+  }
+  const parentPath = path.slice(0, -1);
+  const parent = spanOrNull(text, parentPath);
+  // A parent the text lacks is inserted whole, holding this one member.
+  if (parent === null) return spliceOne(text, parentPath, { [path[path.length - 1]]: value });
+  if (text[parent.start] !== '{') throw new Error(`splicedEdits: ${parentPath.join('.') || 'the document'} is not an object`);
+  const indent = `${indentAt(text, parent.start)}  `;
+  const member = `"${path[path.length - 1]}": ${JSON.stringify(value, null, 2).split('\n').join(`\n${indent}`)}`;
+  let last = parent.end - 2;
+  while (last > parent.start && /\s/.test(text[last])) last--;
+  if (last === parent.start) return `${text.slice(0, parent.start + 1)}\n${indent}${member}\n${indentAt(text, parent.start)}${text.slice(parent.end - 1)}`;
+  return `${text.slice(0, last + 1)},\n${indent}${member}${text.slice(last + 1)}`;
+}
+
+/** The first path, depth first in the intended document's key order, where `got` and `want` differ. */
+function firstMoved(got: unknown, want: unknown, path: readonly string[]): string | null {
+  const plain = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v);
+  if (plain(got) && plain(want)) {
+    for (const k of [...Object.keys(want), ...Object.keys(got).filter((k) => !(k in want))]) {
+      const m = firstMoved(got[k], want[k], [...path, k]);
+      if (m !== null) return m;
+    }
+    return null;
+  }
+  return JSON.stringify(got) === JSON.stringify(want) ? null : path.join('.') || 'the document';
+}
+
 /**
- * The config written: `text` with `meshes.<part>` replaced for every part in `drafted`, each entry as
- * `JSON.stringify(entry, null, 2)` indented to the line its key starts on. Every other byte is the input's, so a
- * config with nothing drafted is written byte for byte as read, and a part that keeps its lattice keeps its text.
- * The result is parsed and held to the intended document before it is returned.
+ * The input's own text with each edit made in order: a value present is replaced, as `JSON.stringify(value, null, 2)`
+ * indented to the line it starts on; one absent is inserted as the last member of its object (an absent parent
+ * inserted with it); `undefined` removes the member. Every other byte is the input's. The result is parsed and held
+ * to the intended document — the input parsed with the same edits made on it — and `moved` names the first path
+ * where it is not (a key the text states twice is the way it is not: the edit lands on the first, the parse keeps the
+ * last); null when it is.
  */
-export function splicedConfig(text: string, drafted: ReadonlyMap<string, unknown>): string {
-  const spans = [...drafted.keys()].map((part) => ({ part, ...jsonValueSpan(text, ['meshes', part]) })).sort((a, b) => b.start - a.start);
+export function splicedEdits(text: string, edits: readonly ConfigEdit[]): { text: string; moved: string | null } {
   let out = text;
-  for (const s of spans) {
-    const lineStart = out.lastIndexOf('\n', s.start) + 1;
-    const indent = /^\s*/.exec(out.slice(lineStart, s.start))?.[0] ?? '';
-    const body = JSON.stringify(drafted.get(s.part), null, 2).split('\n').join(`\n${indent}`);
-    out = `${out.slice(0, s.start)}${body}${out.slice(s.end)}`;
+  for (const e of edits) out = spliceOne(out, e.path, e.value);
+  const want = JSON.parse(text) as Record<string, unknown>;
+  for (const e of edits) {
+    let o = want;
+    for (const k of e.path.slice(0, -1)) {
+      if (typeof o[k] !== 'object' || o[k] === null) o[k] = {};
+      o = o[k] as Record<string, unknown>;
+    }
+    const last = e.path[e.path.length - 1];
+    if (e.value === undefined) delete o[last];
+    else o[last] = e.value;
   }
-  const want = JSON.parse(text) as { meshes: Record<string, unknown> };
-  for (const [part, entry] of drafted) want.meshes[part] = entry;
-  if (JSON.stringify(JSON.parse(out)) !== JSON.stringify(want)) throw new Error('splicedConfig: the spliced text does not parse to the intended config');
-  return out;
+  return { text: out, moved: firstMoved(JSON.parse(out), want, []) };
+}
+
+/**
+ * The config written: `text` with `meshes.<part>` replaced for every part in `drafted`, each entry as
+ * `JSON.stringify(entry, null, 2)` indented to the line its key starts on ({@link splicedEdits}). Every other byte is
+ * the input's, so a config with nothing drafted is written byte for byte as read, and a part that keeps its lattice
+ * keeps its text. The result is parsed and held to the intended document before it is returned.
+ */
+export function splicedConfig(text: string, drafted: ReadonlyMap<string, unknown>): string {
+  for (const part of drafted.keys()) jsonValueSpan(text, ['meshes', part]);
+  const r = splicedEdits(text, [...drafted].map(([part, entry]) => ({ path: ['meshes', part], value: entry })));
+  if (r.moved !== null) throw new Error('splicedConfig: the spliced text does not parse to the intended config');
+  return r.text;
 }
 
 /** A path in a config the loader resolves against the config's directory, and how to set it. */