rig-parts 1.57.1 → 1.58.0

package/NOTICE.md

@@ -122,6 +122,28 @@ redistributed.
 The [parts-examples](https://github.com/rig-c/parts-examples) README records
 both, beside each character's generation record.
 
+### Models named by the optional painting graph
+
+**[observed 2026-10-22]** In `src/graphs.ts`, the intended OpenPose ControlNet is
+[xinsir/controlnet-openpose-sdxl-1.0](https://huggingface.co/xinsir/controlnet-openpose-sdxl-1.0/blob/23f966cd5cfdd3f7729c903e243d87152162d2b7/README.md).
+That revision's card declares `license: apache-2.0`. Its
+[`diffusion_pytorch_model.safetensors`](https://huggingface.co/xinsir/controlnet-openpose-sdxl-1.0/blob/23f966cd5cfdd3f7729c903e243d87152162d2b7/diffusion_pytorch_model.safetensors)
+is the source for the host-local name `controlnet-openpose-sdxl-1.0.safetensors`.
+The graph uses that name only when `generation.control` is configured and
+`generation.control.model` is absent; a configured model filename replaces it.
+The local filename alone does not identify or verify the installed weights.
+
+**[observed 2026-10-22]** The graph always names `4x-AnimeSharp.pth` for model
+upscaling, followed by Lanczos resizing. The source is
+[Kim2091/AnimeSharp at `7696d95`](https://huggingface.co/Kim2091/AnimeSharp/blob/7696d95ced82b0c1f2a41f6ac73336133f0a90e1/4x-AnimeSharp.pth),
+and the [creator's card at that revision](https://huggingface.co/Kim2091/AnimeSharp/blob/7696d95ced82b0c1f2a41f6ac73336133f0a90e1/README.md)
+declares CC BY-NC-SA 4.0, including its NonCommercial condition. rig-parts ships
+neither model and grants no additional rights to their weights. These observations
+record the models' declared terms; they do not assign a blanket licence to output
+images. The existing upscaler selection is unchanged. Whether to require explicit
+selection is the separate, deferred owner decision in
+[#428](https://github.com/rig-c/parts/issues/428).
+
 ## 4. Behaviour reimplemented, not code copied
 
 The raster operations in `src/raster/` reproduce the documented behaviour of

package/README.md

@@ -1,7 +1,10 @@
 # rig-parts
 
 **AI-authored 2D character rigs from one anime painting, verified before they
-are written.** rig-parts takes a single character painting and the layers
+are written.** rig-parts generates no images. The painting and See-through layers
+come from models the user runs on their GPU or a web demo; this package ships no
+weights. The optional `comfy` adapter drives the user's own ComfyUI host and models.
+rig-parts takes a single character painting and the layers
 [See-through](https://github.com/shitagaki-lab/see-through) decomposed it into,
 merges them into measured rig-space parts, authors weighted meshes, bone chains
 and a looping idle over them in [rig-c](https://github.com/rig-c/core)'s
@@ -168,11 +171,19 @@ rig-parts at what it wrote:
 
 | Route | Where | Output rig-parts reads |
 | --- | --- | --- |
-| Hugging Face Space | [24yearsold/see-through-demo](https://huggingface.co/spaces/24yearsold/see-through-demo) (ZeroGPU; upstream states 1-2 extractions a day for a registered user) | the `.psd` it produces |
+| Hugging Face Space | [24yearsold/see-through-demo](https://huggingface.co/spaces/24yearsold/see-through-demo) (ZeroGPU) | the `.psd` it produces; upload `st_input_full.png`, the white-padded square from `inputs`, for the full run, and `st_input_head.png` for the separate head run |
 | ModelScope demo | [ljsabc/See-Through](https://modelscope.cn/studios/ljsabc/See-Through), linked from the upstream README | the `.psd` it produces |
 | Upstream CLI | `python inference/scripts/inference_psd.py --srcp <image> --save_to_psd` in a checkout of [shitagaki-lab/see-through](https://github.com/shitagaki-lab/see-through) | the `.psd` in `workspace/layerdiff_output/` |
 | ComfyUI wrapper | [jtydhr88/ComfyUI-See-through](https://github.com/jtydhr88/ComfyUI-See-through) on your own ComfyUI box; the optional `comfy` adapter (`rig-parts comfy seethrough`) drives it | the `layers.json` + PNGs it writes |
 
+Use the square `inputs` outputs on the Space too. Its [app calls `apply_layerdiff`](https://huggingface.co/spaces/24yearsold/see-through-demo/blob/049a1ab07908e404aad03f73431dd1a98f88202c/app.py#L110-L118),
+which [calls `center_square_pad_resize`](https://huggingface.co/spaces/24yearsold/see-through-demo/blob/049a1ab07908e404aad03f73431dd1a98f88202c/common/utils/inference_utils.py#L78-L83).
+That [preprocessing function](https://huggingface.co/spaces/24yearsold/see-through-demo/blob/049a1ab07908e404aad03f73431dd1a98f88202c/common/utils/cv.py#L254-L274)
+pads a non-square upload before resizing; the centre-crop reported in
+[#356](https://github.com/rig-c/parts/issues/356) is not the current source path.
+`st_input_full.png` supplies the explicit white padding that rig-parts maps back
+to the original painting. This is a source inspection, not a new demo run.
+
 **The head run is needed on every route that was read.** See-through's model
 already separates the head in a second stage of its own: it crops the head the
 first stage found, runs the face tags on that crop at the same `resolution`, and
@@ -217,10 +228,10 @@ commands drive it; nothing else in the pipeline needs one:
 
 ```sh
 rig-parts comfy paint --config config.json --out <dir> --host http://<box>:8188
-rig-parts comfy seethrough --image st_input_full.png --out layers/full --host http://<box>:8188 --offload
+rig-parts comfy seethrough --image st_input_full.png --out layers/full --host http://<box>:8188
 ```
 
-`comfy paint` generates `painting_<seed>.png` from the config's inline
+`comfy paint` asks the user's models to generate `painting_<seed>.png` from the config's inline
 `generation` block — checkpoint, LoRAs, sampler, and an optional OpenPose
 control skeleton it draws itself — and records the prompts verbatim beside it.
 `comfy seethrough` runs the [ComfyUI-See-through](https://github.com/jtydhr88/ComfyUI-See-through)
@@ -230,6 +241,32 @@ the graph is checked against the box's `/object_info`, so a missing node class
 or model is refused by name, and the adapter waits for an empty queue rather
 than queueing behind someone else's job.
 
+The painting graph uses `4x-AnimeSharp.pth`, then Lanczos resizing. The
+[creator's card](https://huggingface.co/Kim2091/AnimeSharp/blob/7696d95ced82b0c1f2a41f6ac73336133f0a90e1/README.md)
+declares CC BY-NC-SA 4.0. When `generation.control` is set, the intended OpenPose
+ControlNet is [xinsir/controlnet-openpose-sdxl-1.0](https://huggingface.co/xinsir/controlnet-openpose-sdxl-1.0/blob/23f966cd5cfdd3f7729c903e243d87152162d2b7/README.md),
+whose card declares Apache-2.0. Install its `diffusion_pytorch_model.safetensors`
+on the host as `controlnet-openpose-sdxl-1.0.safetensors`, or select its installed
+filename with `generation.control.model`. A filename alone does not verify the
+weights. [NOTICE](NOTICE.md#models-named-by-the-optional-painting-graph) pins the
+sources and records their declared terms; those declarations do not assign a
+blanket licence to output images. The graph's automatic upscaler selection is
+unchanged; the owner decision is tracked separately in [#428](https://github.com/rig-c/parts/issues/428).
+
+`--offload` selects the wrapper's CUDA group-offload path on the **ComfyUI host**:
+its [LayerDiff and depth loaders](https://github.com/jtydhr88/ComfyUI-See-through/blob/98d754bf04f668647919ab750eccb0e0640faa81/nodes.py#L395-L475)
+call `enable_group_offload('cuda', ...)`. Omit it for a local Mac/MPS host. A Mac
+running this CLI may pass it to a remote CUDA host. This describes that offload
+path; it is not a claim that the remaining model stack has been verified on MPS.
+
+The [wrapper README at `98d754b`](https://github.com/jtydhr88/ComfyUI-See-through/blob/98d754bf04f668647919ab750eccb0e0640faa81/README.md#L22-L28)
+describes a combined Decompose node and names `24yearsold/seethroughv0.0.1_marigold`
+for depth. The shipped `workflows/seethrough.json` instead sends
+`SeeThrough_GenerateLayers`, `SeeThrough_GenerateDepth` and `SeeThrough_PostProcess`,
+and selects `layerdifforg/seethroughv0.0.1_marigold`, matching the wrapper's
+[implemented depth default](https://github.com/jtydhr88/ComfyUI-See-through/blob/98d754bf04f668647919ab750eccb0e0640faa81/nodes.py#L82-L85).
+Use the graph's node classes and the host's `/object_info` when checking the adapter.
+
 ## The loop, for an agent
 
 ```sh
@@ -261,8 +298,10 @@ rig-parts build --config config.json --source painting.png --full layers/full --
 
 At each step the config holds only what that step reads; the one table of what
 that is, step by step, is [docs/AUTHORING.md §4](docs/AUTHORING.md#4-the-command-order).
-The selftest runs this block in order, command by command, on each fetched example,
-from a config holding only what the first step reads (`RL01`). On `demo` the
+The command-order controls exercise the hand-copy route above on each fetched
+example from a config holding only what the first step reads (`RL01`). The optional
+`--write-config` forms below save the proposed fields; `RL01` does not exercise
+that flag. On `demo` the
 proposal pasted uncorrected stops at the last step, naming its `bottomwear` on
 `CHECK_TIP_OVER_ROOT` — the correction its tracked config records there, the two outer
 skirt chains moved (issue #227, [its README](examples/demo/README.md)); on `scarf`,
@@ -296,10 +335,10 @@ agent skill.
 | `comfy seethrough --image --out [--host]` | optional: run the ComfyUI See-through wrapper on one image and write the form `layers` reads |
 | `layers <dir \| layers.json \| file.psd>` | print every layer of a decomposition: draw order, name, tag group, box, size, opaque pixels, depth, and its translucent, background and area figures; a `WARN` line for a layer `--propose-plan` will leave out |
 | `sheet --source <png> --layers <path>… --out <png>` | a labelled contact sheet of the painting and every layer or part |
-| `assemble --propose-plan …` | propose `assemble.plan` and `extend_below_crop` from the two runs, leaving out an implausible layer with a note naming the rule, naming in a note any full-run body no planned part covers, and naming every layer no row takes with why (empty, taken from the other run only, a plausibility rule; `nose`, never planned, with the row that lets `propose` read the head's pitch) |
+| `assemble --propose-plan … [--write-config <config>]` | propose `assemble.plan` and `extend_below_crop` from the two runs, leaving out an implausible layer with a note naming the rule, naming in a note any full-run body no planned part covers, and naming every layer no row takes with why (empty, taken from the other run only, a plausibility rule; `nose`, never planned, with the row that lets `propose` read the head's pitch) |
 | `assemble --source --full --head --config --out [--seam] [--project]` | merge the two runs into rig-space parts, `parts.json`, the recomposite and its error map, and list the uncovered holes |
-| `propose --head-box --full <run> --canvas WxH` | propose `seethrough.head_box` from the full run, held inside the painting |
-| `propose --parts --source --out [--compare <config>]` | propose bones, meshes, regions and an idle; draw the overlay; print, per bone, which check read it or that none did and why (its role, its kind of segment), and write `basis.json` beside the proposal — what each bone rests on (a joint, a part's mask, a ratio, other bones) and, with `--compare`, whether the config's bone differs |
+| `propose --head-box --full <run> --canvas WxH [--no-back-hair] [--write-config <config>]` | propose `seethrough.head_box` from the full run, held inside the painting; `--no-back-hair` leaves the back-hair layer out of that proposal |
+| `propose --parts --source --out [--compare <config>] [--write-config <config>]` | propose bones, meshes, regions and an idle; draw the overlay; print, per bone, which check read it or that none did and why (its role, its kind of segment), and write `basis.json` beside the proposal — what each bone rests on (a joint, a part's mask, a ratio, other bones) and, with `--compare`, whether the config's bone differs |
 | `propose … --keypoints <file> [--person <id>]` | read a posed figure's joints from one explicit file (space, image size, people, each joint observed, occluded or missing, its source): a joint with a position places the neck, hip, chest or a sleeve chain as given, a note says how every joint was used or which rule stood in, and LINT reads the torso and sleeves along the joints instead of by screen y ([AUTHORING §3](docs/AUTHORING.md)) |
 | `propose … --grid-rule figure\|part` | how each drafted lattice's spacing is chosen: `figure` (the default) one spacing for the figure, round(H / 37) rig px, a part already coarser keeping its own, with a note on its calibration and cost; `part` the reference's rule, a tenth of the part's short side (the oracle examples are proposed under it) |
 | `propose … --from-config <config>` | draw and LINT the config's current bones (by the joints too, given `--keypoints`) |
@@ -322,10 +361,40 @@ fields, the files a build writes and their spec ids, the environment, and what t
 package relies on in rig-c — and what is not, is [docs/STABILITY.md](docs/STABILITY.md).
 Coming from 0.16.0: [docs/MIGRATION.md](docs/MIGRATION.md).
 
+`--write-config <config.json>` saves the three proposals above into an existing
+regular config file: `seethrough.head_box`, `assemble.plan` plus
+`assemble.extend_below_crop`, or the present config sections of an ordinary
+proposal. For `assemble --propose-plan`, the destination must name `--config`
+itself; a different destination is a usage error. Other fields and absent optional
+sections remain; proposal notes are not copied. Changed whole values are spliced
+into the original text, preserving untouched bytes. Stage loaders validate the candidate, including `proposed_rig_scale`,
+before atomic replacement. Relative paths keep the config's directory as their
+base. Changes are listed on stderr; the head-box and plan JSON on stdout remain.
+An identical update leaves bytes and mtime untouched. Without the flag no config
+is changed. This commits the config file, not a transaction across the proposal
+artifacts.
+
+With `--cloth <config.json>`, the flag requires a **new** destination and applies
+the recipe's entry ownership: recipe-owned entries are spliced into the cloth
+config while hand entries and unrelated text survive; conflicts are refused.
+The destination must also be separate from all four artifacts under `--out`:
+`proposal.json`, `basis.json`, `render/landmarks.png`, `render/landmarks_head.png`.
+Aliases, including directory symlinks and hardlinks, count as collisions too.
+Fresh output is published without overwriting a file created while the command
+runs. Its already-checked splice text may be a partial config; it is not passed
+through the full-config loader. If removing the staged temporary fails after
+publication, the error may accompany an already-published complete config.
+`--from <previous.json>` retains the previous-recipe comparison.
+`--from-config` proposes nothing and cannot be combined with `--write-config`.
+[AUTHORING §4](docs/AUTHORING.md#4-the-command-order) describes all four modes.
+
 ## What it does not do
 
 These are limits of the approach, stated so nobody reads more into a green run:
 
+- **rig-parts generates no images.** The painting and See-through layers are made
+  by models the user runs on their GPU or a web demo. No weights ship here; the
+  optional `comfy` adapter drives the user's own ComfyUI host and models.
 - **One depth value per layer.** See-through gives each layer a single depth, so a
   layer that is in front of another in one place and behind it in another is drawn
   right in the still (the painting's own pixels are projected onto it) and wrong once
@@ -354,7 +423,10 @@ These are limits of the approach, stated so nobody reads more into a green run:
   file of joints comes from any pose
   estimator or a hand; this package does not estimate a pose itself, and its
   keypoint support has been measured on generated figures and on files read off the
-  examples' own configs, never on an estimator's output.
+  examples' own configs, and on one reported estimator output: RTMPose whole-body
+  through rtmlib on one painting built green with the estimated file unedited
+  ([#356](https://github.com/rig-c/parts/issues/356)). That is one measurement,
+  not an estimator success rate; it has not been re-run here.
 - **The proposer reads tags, not pictures.** A swinging element painted inside another
   layer (a sash tail in the skirt), hair that is none of the shapes it knows, and
   whether an accessory swings are the corrector's to add. The one accessory shape it

package/cli.ts

@@ -20,6 +20,7 @@ import { type AlternateCliInput, assembleStage, build, checkStage, ERROR_MAP_FIL
 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';
 import { ComfyClient, resolveHost, runPainting, runSeeThrough } from './src/comfy/index.ts';
 import { type CharacterConfig, loadClothConfig, loadConfig, loadEarlyConfig, loadPaintConfig } from './src/config.ts';
+import { configWriteLines, readConfigWriteTarget, separateConfigWriteTarget, stageConfigWrite, type StagedConfigWrite } from './tools/configwrite.ts';
 import { failLine, guidePointer, PartsError } from './src/errors.ts';
 import { GUIDE_DOC, type GuideAnswer, guideRule, guideSection } from './src/guide.ts';
 import { proposeHeadBox } from './src/headbox.ts';
@@ -27,8 +28,8 @@ import { makeInputs } from './src/inputs.ts';
 import { idleKeysOf, isIdleKeys } from './src/rig.ts';
 import { depthSkipLine, exportLayers, figuresPhrase, hiddenLayerLine, implausibleRules, layerFigures, type LayerSet, layerSetDiff, pct, readLayers, readWrapperLayers, ruleSummary, templateLayerNames, templatePsdBytes, times } from './src/layers.ts';
 import { 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, proposalAsConfig, 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 { basisLines, branchSqueezeLine, checkProposal, compare, compareLines, DEFAULT_GRID_RULE, draftTurn, drawLandmarks, FIGURE_GRID_DIVISOR, FRINGE_STEP_PX, GRID_RULES, type GridRule, HIP_MIN_FRACTION, type DraftLintFinding, lint, lintLine, type PartSet, PROPOSAL_CONFIG_SECTIONS, proposalAsConfig, proposeWithBasis, readPartSet, serializeProposal, withTurn, WRIST_ON_PART_PX } from './src/propose.ts';
+import { BASIS_FILE, BASIS_SPEC, basisFile, basisLine, coverageLines, legChainChoice, serializeBasis } from './src/diagnostics.ts';
 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 { meshStatsStage } from './src/meshstats.ts';
 import { chainsLeftBehind, clothConfigEdits, editPaths, plainCount, previousCount, writtenClothConfig } from './src/clothconfig.ts';
@@ -269,13 +270,24 @@ usage:
       coverage lines after them; no ${BASIS_FILE}, as nothing is proposed.
       Exits 1 when any LINT line is printed.
 
+  rig-parts propose … --write-config <config.json>
+      Without --cloth, update an existing config with the whole proposal's
+      present config sections, including proposed_rig_scale; notes stay in the
+      proposal. Absent optional sections and all other fields are kept. The
+      full config loader validates a same-directory candidate before atomic
+      replacement; relative paths resolve beside the config. An equal update
+      keeps the original bytes and mtime. A changed source, an artifact alias
+      or a failed write is refused by name. Change lines go to stderr.
+
   rig-parts propose --head-box --full <dir | layers.json | file.psd> --canvas <W>x<H> [--no-back-hair]
+                         [--write-config <config.json>]
       Propose seethrough.head_box (source px, square) from the full run's
       layers for a painting of WxH px (portrait or landscape: the full run is
       mapped back through the pad inputs added), held inside the painting; a
       shift is printed when one was needed. When "back hair" contributes, prints
       the box without it and how much of the side and area it took;
-      --no-back-hair leaves "back hair" out of the box.
+      --no-back-hair leaves "back hair" out of the box. --write-config updates
+      only seethrough.head_box in an existing config through the layers loader.
 
   rig-parts compare --left <file> --right <file> [--map <bonemap.json>]
       Compare two skeletons bone by bone. Each file is a config, a proposal.json
@@ -697,7 +709,7 @@ usage:
       ${DEFAULT_PROJECT_RULE}.
 
   rig-parts assemble --propose-plan --source <painting.png> --full <dir|psd>
-                       [--head <dir|psd>] --config <config.json>
+                       [--head <dir|psd>] --config <config.json> [--write-config <config.json>]
       Print {plan, extend_below_crop, notes} for config.assemble, from the two
       runs. A layer \`layers\` WARNs about (PLAN_LAYER_TRANSLUCENT,
       PLAN_LAYER_BACKGROUND, PLAN_LAYER_OVERSIZED) is not proposed, and a note
@@ -709,7 +721,8 @@ usage:
       config.seethrough.resolution and config.assemble.rig_scale — the rest of
       the config need not exist yet. With no --head, the one run is held as
       assemble holds it and every row is written from it, and the first note
-      says so.
+      says so. --write-config must name --config itself; it updates the whole
+      assemble.plan and assemble.extend_below_crop through the assemble loader.
 
   rig-parts inputs --source <painting.png> --config <config.json> --out <dir>
       Cut the two images See-through is fed: <out>/st_input_full.png (the
@@ -975,7 +988,7 @@ const TAKES = {
   compare: { valued: ['--left', '--right', '--map'], switches: [] },
   check: { valued: ['--rig', '--out', '--parts', '--source', '--page-edges', '--pack-shape', '--requirements', '--set', '--environment'], switches: ['--seam-pairs', '--keep-stills', '--all-sets'] },
   loop: { valued: ['--frames', '--out'], switches: ['--palette'] },
-  assemble: { valued: ['--source', '--full', '--head', '--config', '--out', '--seam', '--project', '--alt'], switches: ['--propose-plan'] },
+  assemble: { valued: ['--source', '--full', '--head', '--config', '--out', '--seam', '--project', '--alt', '--write-config'], switches: ['--propose-plan'] },
   'comfy seethrough': { valued: ['--image', '--out', '--resolution', '--steps', '--seed', '--prefix', '--host', '--wait', '--timeout', '--poll'], switches: ['--offload', '--lama', '--nf4'] },
   'comfy paint': { valued: ['--config', '--out', '--seeds', '--seed0', '--host', '--wait', '--timeout', '--poll'], switches: [] },
   inputs: { valued: ['--source', '--config', '--out'], switches: [] },
@@ -1267,7 +1280,7 @@ function parseCanvas(v: string): { w: number; h: number } | null {
   return m === null ? null : { w: Number(m[1]), h: Number(m[2]) };
 }
 
-function printLint(P: PartSet, spec: { bones: CharacterConfig['bones']; meshes: CharacterConfig['meshes']; regions: CharacterConfig['regions']; motion: CharacterConfig['motion']; constraints?: CharacterConfig['constraints'] }, joints?: RigJoints, drafted: readonly DraftLintFinding[] = []): number {
+function printLint(P: PartSet, spec: { bones: CharacterConfig['bones']; meshes: CharacterConfig['meshes']; regions: CharacterConfig['regions']; motion: CharacterConfig['motion']; constraints?: CharacterConfig['constraints']; limbs?: CharacterConfig['limbs']; notes?: readonly string[] }, joints?: RigJoints, drafted: readonly DraftLintFinding[] = []): number {
   const res = lint(P, spec, joints, drafted);
   // Under --keypoints only: which rule set read the torso and the chains, and on what basis.
   if (res.basis !== undefined) for (const l of basisLines(res.basis)) console.log(l);
@@ -1285,7 +1298,7 @@ function printLint(P: PartSet, spec: { bones: CharacterConfig['bones']; meshes:
   }
   console.log(`${res.findings.length} LINT line(s) over ${Object.keys(spec.meshes).length - res.unknownMeshes.length} mesh(es) and the hip`);
   // Issue #86: after every line above, which check read each bone, or why none did.
-  for (const l of coverageLines(res.coverage)) console.log(l);
+  for (const l of coverageLines(res.coverage, legChainChoice(P, spec, joints))) console.log(l);
   return res.findings.length;
 }
 
@@ -1311,17 +1324,24 @@ function cmdPropose(args: string[]): number {
     flags.set(flag, value);
     i++;
   }
+  let staged: StagedConfigWrite | null = null;
   try {
     if (headBox) {
-      const stray = [...flags.keys()].filter((f) => f !== '--full' && f !== '--canvas');
-      if (stray.length > 0) return usage(`--head-box takes --full and --canvas only; got ${stray.join(', ')}`);
+      const stray = [...flags.keys()].filter((f) => f !== '--full' && f !== '--canvas' && f !== '--write-config');
+      if (stray.length > 0) return usage(`--head-box takes --full, --canvas and optional --write-config only; got ${stray.join(', ')}`);
       const full = flags.get('--full');
       const canvasArg = flags.get('--canvas');
       if (full === undefined) return usage('--head-box needs --full <dir | layers.json | file.psd>, the full run\'s layers');
       if (canvasArg === undefined) return usage('--head-box needs --canvas <W>x<H>, the painting\'s size in px');
       const canvas = parseCanvas(canvasArg);
       if (canvas === null) return usage(`--canvas ${canvasArg} is not <W>x<H> in integer px`);
+      const target = flags.has('--write-config') ? readConfigWriteTarget(flags.get('--write-config') as string) : null;
       const r = proposeHeadBox(readLayers(full), canvas, { backHair: !noBackHair });
+      if (target !== null) {
+        staged = stageConfigWrite(target, { kind: 'head-box', head_box: r.head_box });
+        staged.commit();
+        for (const line of configWriteLines(target, staged.changes)) console.error(line);
+      }
       console.log(`rig-parts propose --head-box: ${full}`);
       console.log(`  painting ${canvas.w}x${canvas.h}; head layers ${r.layers.map(([n, c]) => `${n} ${c} px`).join(', ')}`);
       if (r.shift[0] !== 0 || r.shift[1] !== 0) {
@@ -1372,16 +1392,21 @@ function cmdPropose(args: string[]): number {
     // 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>');
     // Issue #571: the config the recipe is changed from; an entry equal to its recipe's draft is the recipe's, not a hand edit.
     const fromArg = flags.get('--from');
     if (fromArg !== undefined && writeArg === undefined) return usage('--from names the config the recipe is changed from, for --write-config; give --write-config <out.json>');
-    if (writeArg !== undefined) {
-      const ours = ['proposal.json', BASIS_FILE].map((f) => resolve(out, f));
+    if (fromArg !== undefined && clothArg === undefined) return usage('--from names a previous cloth recipe; give --cloth <config.json>');
+    if (writeArg !== undefined && clothArg !== undefined) {
+      const ours = ['proposal.json', BASIS_FILE, 'render/landmarks.png', 'render/landmarks_head.png'].map((f) => resolve(out, f));
       if (existsSync(writeArg) || ours.includes(resolve(writeArg))) {
         throw new PartsError([{ code: 'PROPOSE_WRITE_CONFIG_FRESH', object: writeArg, detail: existsSync(writeArg) ? 'exists; the config is written to a new file, never over the --cloth config or an earlier one' : `is a file this run writes under ${out}; name another file` }]);
       }
+      separateConfigWriteTarget({ path: resolve(writeArg) }, ours, 'PROPOSE_WRITE_CONFIG_FRESH');
     }
+    // The existing cloth writer keeps its fresh-file, per-entry splice contract.
+    // Without --cloth, #356 updates only an existing config through the stage loader.
+    const target = writeArg === undefined || clothArg !== undefined ? null : readConfigWriteTarget(writeArg);
+    if (target !== null) separateConfigWriteTarget(target, [join(out, 'proposal.json'), join(out, BASIS_FILE), join(out, 'render', 'landmarks.png'), join(out, 'render', 'landmarks_head.png')]);
     const cloth = clothArg === undefined ? null : loadClothConfig(clothArg).cloth;
     const previousCloth = fromArg === undefined ? null : loadClothConfig(fromArg).cloth;
     const partsDir = existsSync(partsArg) && statSync(partsArg).isFile() ? dirname(partsArg) : partsArg;
@@ -1455,14 +1480,16 @@ function cmdPropose(args: string[]): number {
     })();
     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');
+    if (target !== null) staged = stageConfigWrite(target, { kind: 'proposal', proposal: prop, sections: PROPOSAL_CONFIG_SECTIONS });
+    else if (written !== null) staged = stageConfigWrite({ kind: 'fresh', path: written.at, text: written.text });
     mkdirSync(render, { recursive: true });
     writeFileSync(join(out, 'proposal.json'), serializeProposal(prop));
     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);
+    if (staged !== null) {
+      staged.commit();
+      if (target !== null) for (const line of configWriteLines(target, staged.changes)) console.error(line);
     }
     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}`);
@@ -1484,7 +1511,12 @@ function cmdPropose(args: string[]): number {
     if (cfg !== null) for (const l of compareLines(compare(prop.bones, cfg.bones))) console.log(l);
     return EXIT_OK;
   } catch (err) {
+    if (staged !== null) {
+      try { staged.abort(err); } catch (combined) { return printRefusal(combined); }
+    }
     return printRefusal(err);
+  } finally {
+    staged?.cancel();
   }
 }
 
@@ -1566,6 +1598,7 @@ function cmdAssemble(args: string[]): number {
   // --head is optional (issue #359): without it the full run is the one run, and it must hold the face.
   for (const f of ['--source', '--full', '--config']) if (!flags.has(f)) return usage(`assemble needs ${f}`);
   if (propose && (flags.has('--out') || flags.has('--seam') || flags.has('--project') || alts.length > 0)) return usage('--propose-plan prints to the console; it takes none of --out, --seam, --project, --alt');
+  if (!propose && flags.has('--write-config')) return usage('--write-config belongs to assemble --propose-plan');
   if (!propose && !flags.has('--out')) return usage('assemble needs --out <dir>');
   const seam = flags.get('--seam') ?? DEFAULT_SEAM_RULE;
   if (!(SEAM_RULES as readonly string[]).includes(seam)) return usage(`--seam ${seam}; one of ${SEAM_RULES.join(', ')} is required`);
@@ -1573,13 +1606,22 @@ function cmdAssemble(args: string[]): number {
   if (!(PROJECT_RULES as readonly string[]).includes(project)) return usage(`--project ${project}; one of ${PROJECT_RULES.join(', ')} is required`);
   const [source, full, config] = ['--source', '--full', '--config'].map((f) => flags.get(f) as string);
   const head = flags.get('--head') ?? null;
+  const writePath = flags.get('--write-config');
+  if (writePath !== undefined && resolve(writePath) !== resolve(config)) return usage('--write-config must name the same file as --config for assemble --propose-plan');
+  let staged: StagedConfigWrite | null = null;
   try {
     if (propose) {
+      const target = writePath === undefined ? null : readConfigWriteTarget(writePath);
       const src = readSource(source);
       const runs = readRuns(full, head);
       const g = proposeFields(loadEarlyConfig(config, 'layers'), runs.single ? { w: src.width, h: src.height } : null);
       const geometry = { sourceW: src.width, sourceH: src.height, ...g };
       const proposal = runs.single ? proposeSinglePlan(runs.full, geometry) : proposePlan(runs.full, runs.head, geometry);
+      if (target !== null) {
+        staged = stageConfigWrite(target, { kind: 'assemble-plan', plan: proposal.plan, extend_below_crop: proposal.extend_below_crop });
+        staged.commit();
+        for (const line of configWriteLines(target, staged.changes)) console.error(line);
+      }
       console.log(JSON.stringify(proposal, null, 2));
       return EXIT_OK;
     }
@@ -1591,7 +1633,12 @@ function cmdAssemble(args: string[]): number {
     );
     return EXIT_OK;
   } catch (err) {
+    if (staged !== null) {
+      try { staged.abort(err); } catch (combined) { return printRefusal(combined); }
+    }
     return printRefusal(err);
+  } finally {
+    staged?.cancel();
   }
 }
 

package/docs/AUTHORING.md

@@ -47,7 +47,17 @@ with `flattenRig(built)`, not with the built file.
 
 The painting is yours to bring: a PNG of one character, front-facing, full body,
 taller than wide, on a plain light background. How it was made is not read by any
-stage (`config.generation` is recorded for the optional adapter only).
+stage (`config.generation` is recorded for the optional adapter only). rig-parts
+ships no weights and generates no images itself. The optional `comfy` adapter
+drives models on the user's own ComfyUI host. The default OpenPose ControlNet
+and upscaler sources, pinned model cards and declared terms are in
+[NOTICE](../NOTICE.md#models-named-by-the-optional-painting-graph).
+`comfy seethrough --offload` selects the wrapper's CUDA group offload on that
+host; omit it for a local Mac/MPS host. A Mac CLI may drive a remote CUDA host.
+This offload limitation does not establish MPS compatibility for the rest of the
+model stack. The wrapper README and the adapter graph use different node names
+and depth-model identifiers; [the adapter notes](../README.md#the-optional-comfyui-adapter)
+name the graph actually sent.
 
 ## 2. The folder
 
@@ -2046,10 +2056,13 @@ moved on the public `wind` example with its keypoints, whose tracked config the
 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`, and `--from` without `--write-config`
-(`USAGE`), an out path that exists or that
-the run writes itself (`PROPOSE_WRITE_CONFIG_FRESH`), a hand edit to an entry the
+a note names each such path. These are the cloth mode's rules; the three other
+`--write-config` modes are described in §4. Refused before anything is written:
+`--write-config` beside `--from-config`, and `--from` without both `--cloth` and `--write-config`
+(`USAGE`), an out path that exists or collides with any of the four artifacts
+under `--out` (`proposal.json`, `basis.json`, `render/landmarks.png`,
+`render/landmarks_head.png`), including directory-symlink and hardlink aliases
+(`PROPOSE_WRITE_CONFIG_FRESH`), a hand edit to an entry the
 recipe owns (`PROPOSE_WRITE_CONFIG_CONFLICT`), 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
@@ -2446,21 +2459,28 @@ full loader before its assemble stage writes anything.
    a painting padded to a square by hand, whose padding becomes part of the rig.
    Config: the `layers` row, `head_box` not yet. A translucent painting is refused
    (`INPUTS_PAINTING_OPAQUE`).
-2. **See-through, full run** (external).
+2. **See-through, full run** (external), on `inputs/st_input_full.png`. Upload
+   that white-padded square to the Hugging Face Space too. Its [current source](https://huggingface.co/spaces/24yearsold/see-through-demo/blob/049a1ab07908e404aad03f73431dd1a98f88202c/common/utils/cv.py#L254-L274)
+   pads non-square images before resizing; the earlier centre-crop report is not
+   the current source path. The explicit white square keeps the input consistent
+   with rig-parts' full-run coordinate map.
 3. `rig-parts layers inputs/layers/full` — read it. A refusal here is about the
    files, not the art (§6, *Reading the inputs*). A `WARN` line is about the art: a
    layer See-through made that is not plausibly part of the figure, which step 6
    leaves out (§6, *Plausibility*). It refuses nothing.
-4. `rig-parts propose --head-box --full inputs/layers/full --canvas <W>x<H>` →
-   `seethrough.head_box`. Run `rig-parts inputs` again: it now also writes
+4. `rig-parts propose --head-box --full inputs/layers/full --canvas <W>x<H> --write-config config.json`
+   saves `seethrough.head_box` in the existing config. `<W>x<H>` is the original
+   painting's size, not the padded square's. The existing optional `--no-back-hair`
+   leaves the back-hair layer out of the head-box proposal; without it that layer
+   contributes to the box. Run `rig-parts inputs` again: it now also writes
    `st_input_head.png`, the painting cropped to that box at its exact size.
 5. **See-through, head run** (external), on that crop. See-through's own second,
    head stage does not replace it: that stage's layers are pasted back at the full
    run's scale on every route that was read (README *Getting See-through layers*),
    so the full run's eyes stay at its density — 22×13 px for reference-demo's right eye
    white at `resolution` 1024, against 60×38 px in the head run.
-6. `rig-parts assemble --propose-plan --source … --full … --head … --config config.json`
-   → paste `plan` and `extend_below_crop` into `config.assemble`. Config: the
+6. `rig-parts assemble --propose-plan --source … --full … --head … --config config.json --write-config config.json`
+   saves `assemble.plan` and `assemble.extend_below_crop`. Config: the
    `layers` row, with `head_box`.
    Read `notes`: every layer not planned — each tag a layer of either run holds that no
    row takes — is named there once, `<tag>: in no plan row — …`, with why, run by run: the
@@ -2491,8 +2511,8 @@ full loader before its assemble stage writes anything.
 7. `rig-parts assemble … --out work` — read its `uncovered hole` and `uncovered:` lines and look at
    `work/render/recomposite_error_rig.png` (§5): red is painting no part holds, which
    no later stage can see — then
-   `rig-parts propose --parts work/rig --source inputs/painting.png --out work` →
-   `work/proposal.json` and `work/render/landmarks.png` (+ `_head`). Copy
+   `rig-parts propose --parts work/rig --source inputs/painting.png --out work --write-config config.json` →
+   `work/proposal.json` and `work/render/landmarks.png` (+ `_head`). The flag saves
    each of `bones`, `meshes`, `regions`, `limbs`, `motion`, `constraints`, `turn` and `proposed_rig_scale` it
    wrote into the config: `limbs` is written only with `--keypoints`, `constraints`
    only with `--cloth` and `turn` only with `--full`/`--head` (`PROPOSAL_CONFIG_SECTIONS` in `src/propose.ts` is the list,
@@ -2508,6 +2528,13 @@ full loader before its assemble stage writes anything.
    `[bone, from, to]` segment (the off-art check reads only chain links), a
    region, a mesh that names no part, a torso bone absent, a chain the joints
    declare no line for — and a `coverage:` summary counts the three apart.
+   Before the totals, `coverage leg-chain choice:` reports the `leg_r` and
+   `leg_l` chains declared by the supplied proposal or config, their count and
+   recorded source/part bindings, or why none was selected. A missing source is
+   `not recorded`, a chain with no bound parts says `none bound`; nothing is
+   inferred to fill either. The line is selection only, not a checked verdict.
+   Read it and the per-part notes again when changing keypoint sources: a bone
+   map for two leg chains does not cover a proposal that bound only one.
    A `not checked` bone is one nothing verified: look at it on
    `landmarks.png`. `work/basis.json` (spec `spine-parts-basis/1`) says, per
    proposed bone, what its origin and its stated tip rest on: `joint` (which,
@@ -2637,9 +2664,13 @@ full loader before its assemble stage writes anything.
     relative `motion.animations_from` or `generation.control.skeleton` keeps its
     text, so it resolves against `draft/`; the command says so.
 
-The selftest runs this order, with the README's flags, on each fetched example from
-a config holding only `key`, `seethrough` and `assemble.rig_scale`, pasting each
-proposal in as the steps above say (`RL01`); every step must exit 0.
+The command-order selftest runs these stages on each fetched example from a
+config holding only `key`, `seethrough` and `assemble.rig_scale` (`RL01`). For
+the proposal step, copy `bones`, `meshes`, `regions`, `limbs`, `motion`,
+`constraints`, `turn` and `proposed_rig_scale` into the config, each section the
+proposal wrote. `RL01` exercises that manual route and does not execute
+`--write-config`. The save forms above write the fields owned by their mode;
+a saved draft still needs validation.
 
 ### Counting the triangles before a build (`mesh-stats`, issue #566)
 
@@ -2796,6 +2827,43 @@ file's figure, and every part is the clean file's but `hair_back`, which keeps a
 one of them occluded, so nothing shows it at rest; paint it there if the face will
 move off it (`AS245`).
 
+**Saving proposed config fields (`--write-config`, issue #356).** The flag is a
+valued destination path. Its modes have different ownership:
+
+| proposal mode | destination | fields written |
+| --- | --- | --- |
+| `propose --head-box` | existing regular config | `seethrough.head_box` |
+| `assemble --propose-plan` | existing regular config; must name `--config` itself | `assemble.plan`, `assemble.extend_below_crop` |
+| ordinary `propose --parts` without `--cloth` | existing regular config | each present `PROPOSAL_CONFIG_SECTIONS` value: `bones`, `meshes`, `regions`, `limbs`, `motion`, `constraints`, `turn`, `proposed_rig_scale` |
+| `propose --cloth <input.json>` | new file | the recipe's edits spliced into the cloth config; §3, *The config written*, gives entry ownership, hand-edit conflicts and `--from <previous.json>` |
+
+For the first three modes, each selected field replaces its whole value; other
+fields and optional proposal sections not emitted are retained. Changed whole
+values are spliced into the original text through `splicedEdits`, preserving
+untouched bytes. `notes` stays in the proposal. The stage's loader validates a same-directory candidate before
+replacement, so relative file references keep their base and invalid retained
+references are refused. A scale mismatch retains `CONFIG_PROPOSED_RIG_SCALE`;
+the writer does not change `assemble.rig_scale` to hide it. An unchanged update
+keeps the original bytes and mtime. A final source-change check precedes atomic
+replacement; this is a config-file commit, not a transaction over every artifact
+of the proposing command. A refusal leaves the target config unchanged. The
+writer lists changes on stderr, keeping the existing head-box and plan JSON on
+stdout. Without the flag, no config is changed. `--from-config` proposes nothing
+and refuses this flag; `--from` belongs to the cloth mode only.
+All four modes use one file-writing adapter. Fresh cloth output keeps its
+already-checked splice text and intentional partial-config contract; the full
+loader is not imposed on it. Publication links the complete same-directory
+staged file into a destination that must still be absent, so an intervening
+creator is refused without overwrite. Removing the staged temporary happens
+after publication: if that cleanup fails, `CONFIG_WRITE_FAILED` may accompany
+an already-published complete config. Inspect both named paths before retrying. A different
+`--write-config` destination for `assemble --propose-plan` is a usage error.
+For ordinary and cloth proposals, the destination must be separate from all four
+artifacts under `--out`: `proposal.json`, `basis.json`, `render/landmarks.png` and
+`render/landmarks_head.png`. Matching paths, directory-symlink aliases and
+existing hardlinks are refused before artifact output; the ordinary mode names
+`CONFIG_WRITE_TARGET`, and the cloth mode `PROPOSE_WRITE_CONFIG_FRESH`.
+
 ## 5. After each stage: what to read
 
 | stage | read | green looks like | a common red |
@@ -3301,9 +3369,12 @@ See-through with another seed.
 
 | rule | means | change |
 | --- | --- | --- |
+| <a id="CONFIG_WRITE_TARGET"></a>`CONFIG_WRITE_TARGET` | ordinary `propose … --write-config` would overwrite its config through one of its own four artifact paths under `--out`: `proposal.json`, `basis.json`, `render/landmarks.png`, `render/landmarks_head.png`; the collision check resolves existing path ancestors and compares existing file identity, so directory-symlink aliases and hardlinks count too. Refused before artifact output; the cloth mode names the same collision `PROPOSE_WRITE_CONFIG_FRESH` | choose a config outside all four artifact paths and their aliases |
+| <a id="CONFIG_WRITE_CHANGED"></a>`CONFIG_WRITE_CHANGED` | the existing destination no longer matches the snapshot read for `--write-config` when the writer is ready to commit: it is absent, no longer a regular file, or its permissions or text differ. The writer refuses to replace the current destination | keep the current config, reconcile any concurrent edit, and rerun against it |
+| <a id="CONFIG_WRITE_FAILED"></a>`CONFIG_WRITE_FAILED` | a proposed-value splice moved an unintended field, or a config-writing operation failed: reading, checking collisions, staging, writing proposal artifacts, publishing or replacing the destination, or removing the staged temporary. The message names the action and path. Cleanup failures retain the primary failure and name the stranded temporary. Fresh cloth publication precedes temporary cleanup, so a cleanup failure may leave the complete new config present; there is no transaction over every proposal artifact | inspect the named action, destination and temporary; restore access or permissions as needed; remove only the specifically reported stranded temporary, and inspect any published config before retrying |
 | <a id="CONFIG_FILE_PRESENT"></a><a id="CONFIG_IS_JSON"></a>`CONFIG_FILE_PRESENT`, `CONFIG_IS_JSON` | no such file, or not JSON; for a file the config names (`motion.animations_from`, `requirements`), the path is read relative to the config's directory, and the `motion.animations_from` line names the path as typed, that directory and what the two resolved to (issue #569) | `--config`; a file the config names: put it at the resolved path, or write the path from the config's directory |
 | <a id="CONFIG_KEY_KNOWN"></a><a id="CONFIG_KEY_RETIRED"></a><a id="CONFIG_FIELD_PRESENT"></a><a id="CONFIG_FIELD_TYPE"></a>`CONFIG_KEY_KNOWN`, `CONFIG_KEY_RETIRED`, `CONFIG_FIELD_PRESENT`, `CONFIG_FIELD_TYPE` | an unknown key (a retired one says what replaces it), a missing one (a `motion.animations_from` file with no `spec` is told to write `"spec": "rigc-motion/1"` and the whole file's shape, issue #569), a wrong type (`bones[i].link_inherit` must be an object whose values are strings); a project's own record under a plain key, or an annotation (`note`, `<name>_note`) holding something other than a string; in `meshes.<part>.auto` (§3, *An automatic mesh*), a missing or out-of-range number, a Stage B opt-in that is not exactly a value rig-c accepts, or a field the mode does not have — a bound on one of the five allocation rows, or an authored `motionAmplitude` (it is derived, never written); under `comfy paint`, `CONFIG_FIELD_PRESENT` on `config.generation`: a config with no `generation` block (the line names the fields it holds) | the named field; a record goes under a key beginning `x-` (any JSON, read by nothing), a remark under `note` or `<name>_note` (a string) — §3; under `comfy paint`, `config.generation` |
-| <a id="CONFIG_KEY_UNIQUE"></a>`CONFIG_KEY_UNIQUE` | a key written twice in one object of a file the config names — the pose file `generation.control.skeleton` names, or the `motion.animations_from` file; JSON keeps only the last value, so every other would be dropped without a word | that file: each key once |
+| <a id="CONFIG_KEY_UNIQUE"></a>`CONFIG_KEY_UNIQUE` | a key written twice in an existing config updated by `--write-config`, or in one object of a file the config names — the pose file `generation.control.skeleton` names, or the `motion.animations_from` file; JSON keeps only the last value, so every other would be dropped without a word | that file: each key once |
 | <a id="CONFIG_ANIMATION_NAME_FREE"></a>`CONFIG_ANIMATION_NAME_FREE` | the `motion.animations_from` file holds an animation named `idle`, the animation `config.motion` writes | rename that animation |
 | <a id="CONFIG_HEAD_BOX_SQUARE"></a>`CONFIG_HEAD_BOX_SQUARE` | `seethrough.head_box` is not a non-empty square | `head_box` — take `propose --head-box`'s |
 | <a id="CONFIG_TAG_KNOWN"></a><a id="CONFIG_PART_NAME"></a><a id="CONFIG_PART_UNIQUE"></a>`CONFIG_TAG_KNOWN`, `CONFIG_PART_NAME`, `CONFIG_PART_UNIQUE` | a plan or extend entry names neither a v3 tag nor `author:<label>` (an `author:` tag with a malformed label says what the label must be), a part name that is not a file name, or a part or layer twice — a patch named like a plan part or another patch, and a cut's `into` named like a plan part, a patch or another cut's, included | `assemble.plan`, `assemble.patches`, `assemble.cuts` |
@@ -3439,7 +3510,7 @@ says why each requirement exists and what breaks without it.
 | <a id="PROPOSE_FIGURE_LAYER"></a>`PROPOSE_FIGURE_LAYER` | with `--keypoints` (issue #577): a limb is drafted from the figure layer (no handwear or legwear part over 500 px for it), and two or more `topwear` parts each hold every joint and the trunk bones' origins within 15 px with the same opaque px in the 31x31 squares about them, so nothing says which is the figure; or the only `topwear` parts that hold them are named by a cloth recipe (`config.cloth.<tag>.part` or `.parts`, issue #631), whose mesh a limb would take (§3, *A figure of one material*) | leave the others out of `assemble.plan`, or give the arms and legs their own handwear and legwear layers; for a recipe's part, take it out of the recipe |
 | <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_FRESH"></a>`PROPOSE_WRITE_CONFIG_FRESH` | with `--cloth … --write-config` (issues #537, #356): the out path exists or collides with one of the four artifacts under `--out` — `proposal.json`, `basis.json`, `render/landmarks.png`, `render/landmarks_head.png` — including directory-symlink and hardlink aliases; 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 and separate from all four artifact paths and their aliases |
 | <a id="PROPOSE_WRITE_CONFIG_CONFLICT"></a>`PROPOSE_WRITE_CONFIG_CONFLICT` | with `--write-config` (issue #552): an entry of `bones`, `constraints` or `motion.tracks` the recipe re-drafts or removes was changed by hand in the `--cloth` config — it equals neither the draft with the recipe nor the draft without it — so the write would drop the hand edit; the object is the entry (`config.constraints[40] "skirt0a_0_physics"` in CL207), the detail names the first field the hand edit holds and what the draft writes there. With `--from <previous config>` (issue #571) an entry equal to the previous recipe's draft is the recipe's too, and the conflict is an entry that equals neither the draft, the draft without the recipe, nor the previous recipe's draft: the detail says so and reads the first differing field against the previous recipe's draft. Also a name the config states twice where the recipe drafts it. Every conflict is named at once and nothing is written | take the draft by removing the hand edit (or the entry), or leave the recipe out for that part (its `cloth` block); state a name once |
 | <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 |

package/docs/STABILITY.md

@@ -37,7 +37,10 @@ this version does not implement. No command is unimplemented at 1.0.0 (`LATER`
 in `cli.ts` is empty). A refusal line has the shape
 `  FAIL  <RULE>: <object> — <value found>; <value required> (see rig-parts guide <RULE>)`:
 the rule name is a stable identifier, the pointer at the end is fixed text, and the
-detail between them is prose that may be reworded. A command
+detail between them is prose that may be reworded. Existing named or child core
+guide pointers in relayed compile-error text are preserved verbatim. Only a bare
+core compile-error line receives `(see rigc guide §5.1)` inside the enclosing
+rig-parts refusal; no core error code is invented. A command
 also answers to the alias `spine-parts` as long as the install keeps it
 ([MIGRATION.md](MIGRATION.md)). `-h`, `help` and `-v` are the short forms of
 `--help` and `--version`. The flags' meanings are `rig-parts --help`'s; their
@@ -51,9 +54,9 @@ defaults are the help's too, and none is guessed from the art.
 | `inputs` | `--source`, `--config`, `--out` |
 | `comfy` | `paint`: `--config`, `--out`; optional `--seeds`, `--seed0`, `--host`, `--wait`, `--timeout`, `--poll` |
 | `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`), `--write-config` (a new file, with `--cloth` and not with `--from-config`, issue #537 — additive: without it nothing `propose` writes changes), `--from` (the config the recipe is changed from, only with `--write-config`, issue #571 — additive: without it nothing `--write-config` writes changes) |
+| `assemble` | `--propose-plan` with `--source`, `--full`, `--config`, optional `--head`, `--write-config` (must name `--config` itself, issue #356); 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`, `--write-config` (existing config, issue #356) |
+| `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` (existing config for an ordinary proposal, issue #356; a new file with `--cloth`, issue #537; not with `--from-config` — additive: without it nothing `propose` writes changes), `--from` (the config the recipe is changed from, only with `--write-config`, issue #571 — additive: without it nothing `--write-config` 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), `--environment` (issue #538, additive) |
@@ -201,7 +204,8 @@ every number) are AUTHORING §3's tables, and the loader refuses any other by na
 | 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 entries the recipe drafts (issue #537), measured against the same parts drafted without it: `meshes.<part>` and `regions.<part>` for each part the recipe moves, and `bones`, `constraints` and `motion.tracks` entry by entry by name (issue #552) — an entry the recipe drafts replaced or inserted, one it replaces removed, every other entry kept with its bytes and its place, and a hand edit to an entry the recipe owns refused by name (`PROPOSE_WRITE_CONFIG_CONFLICT`) rather than dropped; a section the input lacks is inserted; with `--from <previous config>` (issue #571) an entry equal to the previous recipe's draft is the recipe's as well |
+| an existing config named by `--write-config` | `propose --head-box`, `assemble --propose-plan`, ordinary `propose` | issue #356, additive: `assemble --propose-plan` must update `--config` itself; only the selected proposed fields are replaced by whole-value text splices, preserving untouched bytes; absent optional proposal sections and other fields remain; the stage loader validates before atomic replacement, relative paths keep their base, an unchanged update preserves bytes and mtime, and stderr lists changes; no multi-artifact transaction is promised |
+| a new `--write-config` file | `propose --cloth … --write-config` | complete checked splice text published without overwrite; an intervening creator is refused, while cleanup failure after publication may leave the complete new file present; intentional partial configs retain their existing contract; the `--cloth` config read, byte for byte, but for the entries the recipe drafts (issue #537), measured against the same parts drafted without it: `meshes.<part>` and `regions.<part>` for each part the recipe moves, and `bones`, `constraints` and `motion.tracks` entry by entry by name (issue #552) — an entry the recipe drafts replaced or inserted, one it replaces removed, every other entry kept with its bytes and its place, and a hand edit to an entry the recipe owns refused by name (`PROPOSE_WRITE_CONFIG_CONFLICT`) rather than dropped; a section the input lacks is inserted; with `--from <previous config>` (issue #571) an entry equal to the previous recipe's draft is the recipe's as well |
 | `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`, then `line` and `status` — issue #541, additive, the spec stays `rig-parts-remesh/1`: `line` is the last line `check` prints on that tree, byte for byte, and `status` every block's status as that tree's `check.json` records it, by name in the file's order — `gate`, `loop` and `seam` read from their figures, every other block its own `status`, a block the file does not write absent; `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`, then `line` and `status` — issue #541, additive, the spec stays `rig-parts-retune/1`: `line` is the last line `check` prints on that tree, byte for byte, and `status` every block's status as that tree's `check.json` records it, by name in the file's order — `gate`, `loop` and `seam` read from their figures, every other block its own `status`, a block the file does not write absent; `scope`) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rig-parts",
-  "version": "1.57.1",
+  "version": "1.58.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": {
@@ -39,6 +39,7 @@
   "files": [
     "bin/rig-parts.cjs",
     "cli.ts",
+    "tools/configwrite.ts",
     "src",
     "workflows",
     "docs/AUTHORING.md",

package/src/build.ts

@@ -73,7 +73,7 @@ import {
 } from './autoreplay.ts';
 import { besideIdleLine, checkSummaryLine, inputFileRecord, type InputFileRecord, 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, loadConfigAndAnimations, loadConfigWithBytes, loadEarlyConfig, type Patch, type PlanEntry } from './config.ts';
-import { failLine, PartsError, type Problem, refuseIfAny } from './errors.ts';
+import { coreCompileGuideLine, failLine, PartsError, type Problem, refuseIfAny } from './errors.ts';
 import type { MeshQualityReport, MotionSchedule } from 'rig-c/mesh';
 import { encodeGif } from './gif.ts';
 import { CONTROL_SUFFIX, withAnimations } from './motion.ts';
@@ -817,7 +817,8 @@ function gateRun(label: string, rigc: RigcRunner, args: string[]): GateRun {
   const r = rigc(args);
   const lines = r.out.split('\n').filter((l) => /^ {2}FAIL {2}/.test(l) || /assertions: \d+ measured/.test(l) || /^rigc compile error/.test(l) || DECLARED_SKIP.test(l) || HERE_LINE.test(l));
   const failed = lines.some((l) => /^ {2}FAIL {2}/.test(l) || /^rigc compile error/.test(l));
-  return { label, status: r.status, lines: r.status !== 0 && !failed ? [...lines, ...causeLines(r.out)] : lines, ...(r.ran === undefined ? {} : { ran: r.ran }) };
+  const quoted = r.status !== 0 && !failed ? [...lines, ...causeLines(r.out)] : lines;
+  return { label, status: r.status, lines: quoted.map(coreCompileGuideLine), ...(r.ran === undefined ? {} : { ran: r.ran }) };
 }
 
 /**

package/src/check.ts

@@ -83,7 +83,7 @@ import { basename, delimiter, dirname, join, resolve } from 'node:path';
 import { measureRecomposite, type RecompositeFigures, recompositeRecord, scenePhrase, sourceInRig } from './assemble.ts';
 import { type BoneTransform, computeExactFrameTransforms, cropToSpineY, normaliseDegrees, toBoneLocal } from './coords.ts';
 import { capBox, inDisc } from './limbs.ts';
-import { PartsError, type Problem, refuseIfAny } from './errors.ts';
+import { coreCompileGuideLine, PartsError, type Problem, refuseIfAny } from './errors.ts';
 import { framesInside, IDLE_FPS, TIME_SLACK } from './motion.ts';
 import {
   blinkFigures,
@@ -818,7 +818,8 @@ const HERE_LINE = /^\.\.\s+here: /;
 export function buildGateLines(out: string): string[] {
   return out
     .split('\n')
-    .filter((l) => (l.trim().startsWith('..') && (l.includes(' assertions: ') || l.includes('pages=') || l.includes('pack:') || HERE_LINE.test(l.trim()))) || l.includes('FAIL') || l.includes('compile error'));
+    .filter((l) => (l.trim().startsWith('..') && (l.includes(' assertions: ') || l.includes('pages=') || l.includes('pack:') || HERE_LINE.test(l.trim()))) || l.includes('FAIL') || l.includes('compile error'))
+    .map(coreCompileGuideLine);
 }
 
 /**
@@ -3848,7 +3849,7 @@ export function clothWarnText(r: ClothRow, duration: number): string {
  */
 export function rigcFailed(what: string, call: RigcCall, lines: readonly string[]): Problem[] {
   const named = lines.filter((l) => l.includes('FAIL') || l.includes('compile error'));
-  const quoted = named.length > 0 ? named.map((l) => l.trim()) : causeLines(call.out);
+  const quoted = (named.length > 0 ? named.map((l) => l.trim()) : causeLines(call.out)).map(coreCompileGuideLine);
   const object = `\`rigc ${what}\``;
   const ran = rigcRanClause(call);
   if (quoted.length === 0) return [{ code: 'CHECK_RIGC_GREEN', object, detail: `exit ${call.status}, and it printed nothing${ran}` }];

package/src/configwrite.ts

@@ -0,0 +1,117 @@
+/**
+ * The three config updates proposed by the CLI (issue #356). Pure JSON merge:
+ * no file reads/writes and no substitute for the stage's existing validator.
+ * A present proposal section replaces that whole field; an absent optional
+ * section is retained. The caller supplies the proposer's own section tuple,
+ * avoiding a second policy list or a runtime import of the proposer graph.
+ */
+import type { PlanProposal } from './assemble.ts';
+import type { HeadBoxProposal } from './headbox.ts';
+import type { Proposal, PROPOSAL_CONFIG_SECTIONS } from './propose.ts';
+import { PartsError } from './errors.ts';
+import type { ConfigEdit } from './meshdraft.ts';
+
+export type ConfigJson = null | boolean | number | string | ConfigJson[] | ConfigObject;
+export interface ConfigObject { [key: string]: ConfigJson }
+export type ConfigWritePatch =
+  | { kind: 'head-box'; head_box: HeadBoxProposal['head_box'] }
+  | { kind: 'assemble-plan'; plan: PlanProposal['plan']; extend_below_crop: PlanProposal['extend_below_crop'] }
+  | { kind: 'proposal'; proposal: Proposal; sections: typeof PROPOSAL_CONFIG_SECTIONS };
+export interface ConfigWriteChange {
+  path: string;
+  kind: 'added' | 'replaced' | 'removed';
+}
+export interface ConfigWriteResult {
+  config: ConfigObject;
+  /** Semantic changes only, in destination key order, then new key order. */
+  changes: ConfigWriteChange[];
+  /** Whole owned values, applied by the same splicedEdits engine as cloth. */
+  edits: ConfigEdit[];
+}
+const own = (o: object, key: string): boolean => Object.prototype.hasOwnProperty.call(o, key);
+const object = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v);
+function field(parent: string, key: string): string {
+  return /^[A-Za-z_][A-Za-z0-9_-]*$/.test(key) ? `${parent}${parent === '' ? '' : '.'}${key}` : `${parent}[${JSON.stringify(key)}]`;
+}
+function refuse(path: string, detail: string): never {
+  throw new PartsError([{ code: 'CONFIG_FIELD_TYPE', object: path, detail }]);
+}
+/** Clone JSON without dropping undefined, accepting non-finite numbers or following cycles. */
+function clone(value: unknown, path: string, ancestors = new Set<object>()): ConfigJson {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return value;
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
+  if (typeof value !== 'object' || value === null) return refuse(path, `is ${typeof value}; a finite JSON value is required`);
+  if (ancestors.has(value)) return refuse(path, 'contains a cycle; JSON values cannot refer to their ancestors');
+  const proto = Object.getPrototypeOf(value);
+  if (!Array.isArray(value) && proto !== Object.prototype && proto !== null) return refuse(path, 'is not a plain JSON object');
+  ancestors.add(value);
+  let result: ConfigJson;
+  if (Array.isArray(value)) {
+    result = Array.from(value, (v, i) => clone(v, `${path}[${i}]`, ancestors));
+  } else {
+    // fromEntries keeps a JSON key named __proto__ as data, never as a setter.
+    result = Object.fromEntries(Object.entries(value).map(([k, v]) => [k, clone(v, field(path, k), ancestors)]));
+  }
+  ancestors.delete(value);
+  return result;
+}
+function equal(a: ConfigJson, b: ConfigJson): boolean {
+  if (a === b) return true;
+  if (Array.isArray(a) || Array.isArray(b)) return Array.isArray(a) && Array.isArray(b) && a.length === b.length && a.every((v, i) => equal(v, b[i]));
+  if (!object(a) || !object(b)) return false;
+  const ak = Object.keys(a), bk = Object.keys(b);
+  return ak.length === bk.length && ak.every((k) => own(b, k) && equal(a[k], b[k]));
+}
+function changes(before: ConfigObject, after: ConfigObject, parent = ''): ConfigWriteChange[] {
+  const result: ConfigWriteChange[] = [];
+  for (const [key, a] of Object.entries(before)) {
+    const path = field(parent, key);
+    if (!own(after, key)) result.push({ path, kind: 'removed' });
+    else if (!equal(a, after[key])) {
+      if (object(a) && object(after[key])) result.push(...changes(a, after[key] as ConfigObject, path));
+      else result.push({ path, kind: 'replaced' });
+    }
+  }
+  for (const key of Object.keys(after)) if (!own(before, key)) result.push({ path: field(parent, key), kind: 'added' });
+  return result;
+}
+
+/** The caller validates the returned candidate through its existing config door before saving it. */
+export function mergeConfigProposal(raw: unknown, patch: ConfigWritePatch): ConfigWriteResult {
+  if (!object(raw)) return refuse('config', 'is not an object; an existing config JSON object is required');
+  const before = clone(raw, 'config') as ConfigObject;
+  const config = clone(before, 'config') as ConfigObject;
+  const edits: ConfigEdit[] = [];
+  switch (patch.kind) {
+    case 'head-box': {
+      if (!object(config.seethrough)) return refuse('config.seethrough', 'is absent or not an object; the existing See-through settings are required before writing head_box');
+      const previous = config.seethrough.head_box;
+      config.seethrough.head_box = clone(patch.head_box, 'proposal.head_box');
+      if (!equal(previous, config.seethrough.head_box)) edits.push({ path: ['seethrough', 'head_box'], value: config.seethrough.head_box });
+      break;
+    }
+    case 'assemble-plan': {
+      if (!object(config.assemble)) return refuse('config.assemble', 'is absent or not an object; the existing assembly settings are required before writing its plan');
+      const previousPlan = config.assemble.plan, previousExtend = config.assemble.extend_below_crop;
+      config.assemble.plan = clone(patch.plan, 'proposal.plan');
+      config.assemble.extend_below_crop = clone(patch.extend_below_crop, 'proposal.extend_below_crop');
+      if (!equal(previousPlan, config.assemble.plan)) edits.push({ path: ['assemble', 'plan'], value: config.assemble.plan });
+      if (!equal(previousExtend, config.assemble.extend_below_crop)) edits.push({ path: ['assemble', 'extend_below_crop'], value: config.assemble.extend_below_crop });
+      break;
+    }
+    case 'proposal': {
+      for (const key of patch.sections) {
+        // This is the caller's checked Proposal, with the proposer's own tuple.
+        // Optional absent fields are retained rather than erased by a narrower run.
+        if (patch.proposal[key] !== undefined) {
+          const previous = config[key];
+          config[key] = clone(patch.proposal[key], `proposal.${key}`);
+          if (!equal(previous, config[key])) edits.push({ path: [key], value: config[key] });
+        }
+      }
+      break;
+    }
+    default: return refuse('write-config', 'has no supported operation; head-box, assemble-plan or proposal is required');
+  }
+  return { config, changes: changes(before, config), edits };
+}

package/src/diagnostics.ts

@@ -32,6 +32,8 @@
  * write the same bytes.
  */
 import { type Problem, refuseIfAny } from './errors.ts';
+import type { BoneEntry, Limb } from './config.ts';
+import type { RigJoints } from './keypoints.ts';
 import { BASIS_KINDS, type BasisKind, type BoneBasis, type BoneCoverage, COVERAGE_OUTCOMES, coverageOutcome, expand, FRAME_KEYS, type FrameBasis, type FrameKey, type PartSet, type Placement, type Proposal, type ProposalBasis } from './propose.ts';
 import { BONE_ROLES, type BoneRole, compareStructure, readSkeleton } from './structure.ts';
 
@@ -175,8 +177,66 @@ export function basisLine(f: BasisFile, out: string): string {
   return `wrote ${BASIS_FILE} (${f.bones.length} bone record(s) by the basis of their origin: ${kinds}${cmp}) under ${out}`;
 }
 
+/** The leg choice actually declared by the supplied proposal/config. Placement
+ * and coverage are distinct: selecting a chain never claims its links were checked.
+ */
+export interface LegChainChoice {
+  chains: Array<{ chain: string; sources: string[]; parts: string[] }>;
+  /** Present when no chain was selected; null never stands for a guessed cause. */
+  none: string | null;
+}
+
+export function legChainChoice(P: PartSet, spec: { bones: readonly BoneEntry[]; meshes: Proposal['meshes']; regions?: Proposal['regions']; limbs?: Readonly<Record<string, Limb>>; notes?: readonly string[] }, joints?: RigJoints): LegChainChoice {
+  const chains: LegChainChoice['chains'] = [];
+  for (const entry of spec.bones) {
+    if (!('chain' in entry) || !/^leg_[rl]$/.test(entry.chain)) continue;
+    const links = new Set(entry.points.map((_, i) => `${entry.chain}${i}`));
+    const sources = new Set<string>();
+    const parts = new Set<string>();
+    for (const limb of Object.values(spec.limbs ?? {})) {
+      for (const segment of limb.segments) if (links.has(segment.bone)) {
+        sources.add(segment.from);
+        parts.add(segment.part);
+      }
+    }
+    const hasSourceBinding = sources.size > 0;
+    const bound = (part: string): void => {
+      parts.add(part);
+      if (!hasSourceBinding && P.recs.some((p) => p.name === part)) sources.add(part);
+    };
+    for (const [part, mesh] of Object.entries(spec.meshes)) {
+      if (mesh.segments.some((s) => typeof s === 'string' ? s === entry.chain || links.has(s) : links.has(s[0]))) bound(part);
+    }
+    for (const [part, bone] of Object.entries(spec.regions ?? {})) if (links.has(bone)) bound(part);
+    chains.push({ chain: entry.chain, sources: [...sources], parts: [...parts] });
+  }
+  if (chains.length > 0) return { chains, none: null };
+  if (joints === undefined) return { chains, none: 'no keypoints supplied; leg placement requires hip, knee and ankle positions' };
+  const recorded = spec.notes?.find((n) => n.includes(': no leg chain — '));
+  if (recorded !== undefined) return { chains, none: recorded };
+  const gaps: string[] = [];
+  for (const side of ['r', 'l'] as const) {
+    const missing = ([`${side}_hip`, `${side}_knee`, `${side}_ankle`] as const).filter((key) => joints.joints[key].at === null);
+    if (missing.length > 0) gaps.push(`${missing.join(', ')} ${missing.length === 1 ? 'has' : 'have'} no position`);
+    else {
+      const hip = joints.joints[`${side}_hip`].at as [number, number];
+      const knee = joints.joints[`${side}_knee`].at as [number, number];
+      if (hip[0] === knee[0] && hip[1] === knee[1]) gaps.push(`${side}_hip and ${side}_knee are one point; the thigh has no direction`);
+    }
+  }
+  if (gaps.length === 2) return { chains, none: gaps.join('; ') };
+  if (!P.byTag('legwear', undefined, true).some((p) => p.opaque_px > 500)) return { chains, none: 'no legwear part over 500 opaque px; the proposal declares no leg chain' };
+  return { chains, none: 'no leg_r or leg_l chain declared; the supplied spec records no leg-placement refusal' };
+}
+
+export function legChainChoiceLine(choice: LegChainChoice): string {
+  if (choice.chains.length === 0) return `coverage leg-chain choice: 0 chains — ${choice.none ?? 'no placement reason recorded'}`;
+  const named = (values: readonly string[]): string => values.map((v) => JSON.stringify(v)).join(', ');
+  return `coverage leg-chain choice: ${choice.chains.length} ${choice.chains.length === 1 ? 'chain' : 'chains'} — ${choice.chains.map((c) => `${c.chain}: source ${c.sources.length === 0 ? 'not recorded' : named(c.sources)}; parts ${c.parts.length === 0 ? 'none bound' : named(c.parts)}`).join(' | ')}; selection only, not a checked verdict`;
+}
+
 /** One coverage line per bone, then the summary. Every line starts `coverage`. */
-export function coverageLines(coverage: readonly BoneCoverage[]): string[] {
+export function coverageLines(coverage: readonly BoneCoverage[], legChoice?: LegChainChoice): string[] {
   const out: string[] = [];
   for (const c of coverage) {
     const role = c.role === null ? 'role not read' : c.role.role;
@@ -184,6 +244,7 @@ export function coverageLines(coverage: readonly BoneCoverage[]): string[] {
     if (outcome === 'not checked') out.push(`coverage ${c.bone} [${role}]: not checked — ${c.why.join('; ')}`);
     else out.push(`coverage ${c.bone} [${role}]: ${outcome} — read by ${c.read.join(', ')}${c.lint > 0 ? `; named by ${c.lint} LINT line(s)` : ''}`);
   }
+  if (legChoice !== undefined) out.push(legChainChoiceLine(legChoice));
   const by = (o: (typeof COVERAGE_OUTCOMES)[number]): number => coverage.filter((c) => coverageOutcome(c) === o).length;
   const roles: Record<BoneRole, number> = { target: 0, deforms: 0, control: 0, unclassified: 0 };
   let unread = 0;

package/src/errors.ts

@@ -34,6 +34,18 @@ export function guidePointer(code: string): string {
   return ` (see rig-parts guide ${code})`;
 }
 
+/**
+ * Complete only a bare relayed core compile refusal (issue #356). Current core
+ * names a guide rule; older callers may name the compile section or a child.
+ * Keep those pointers and all non-compile lines verbatim. The parts rule's
+ * outer pointer remains failLine's responsibility.
+ */
+export function coreCompileGuideLine(line: string): string {
+  if (!/^\s*rigc compile error\b/.test(line) || /\(see rigc guide (?:§5\.1(?:\.\d+)*|[A-Z][A-Z0-9_]*)\)/.test(line)) return line;
+  const body = line.trimEnd();
+  return `${body} (see rigc guide §5.1)${line.slice(body.length)}`;
+}
+
 /** A refusal as it is printed: `  FAIL  RULE: object — detail (see rig-parts guide RULE)`. */
 export function failLine(p: Problem): string {
   return `  FAIL  ${problemLine(p)}${guidePointer(p.code)}`;

package/src/propose.ts

@@ -5486,6 +5486,14 @@ function lintBasis(bones: readonly BoneEntry[], joints: RigJoints): LintBasis {
     if (from[0] === to[0] && from[1] === to[1]) return { chain, joints: [a, b], line: null, why: `${a} and ${b} are one point, ${fmtAt(from)}, so they declare no line` };
     return { chain, joints: [a, b], line: { from, to }, why: null };
   });
+  // Leg joints place a bent chain; projecting all links onto hip -> ankle is
+  // not a rule for that bend. Say why that check does not read these chains.
+  for (const side of ['r', 'l'] as const) {
+    const chain = `leg_${side}`;
+    if (bones.some((e) => 'chain' in e && e.chain === chain)) {
+      chains.push({ chain, joints: [`${side}_hip`, `${side}_ankle`], line: null, why: 'chain-not-advancing reads sleeve chains only; a bent knee need not advance along hip -> ankle' });
+    }
+  }
   return { person: joints.person, torso, chains };
 }
 

package/tools/configwrite.ts

@@ -0,0 +1,203 @@
+/** Same-directory staging for every CLI config writer (issue #356).
+ * Ownership is pure; this adapter alone owns files. Existing updates use their
+ * stage loaders; fresh cloth text retains its intentional partial-config contract.
+ */
+import { closeSync, fchmodSync, linkSync, mkdirSync, lstatSync, openSync, readFileSync, realpathSync, statSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { basename, dirname, join, resolve } from 'node:path';
+import { loadConfigAndAnimations, loadEarlyConfig, repeatedKeys } from '../src/config.ts';
+import { mergeConfigProposal, type ConfigWriteChange, type ConfigWritePatch } from '../src/configwrite.ts';
+import { PartsError, type Problem } from '../src/errors.ts';
+import { splicedEdits } from '../src/meshdraft.ts';
+
+export interface ConfigWriteTarget { path: string; original: string; mode: number; raw: unknown }
+/** Cloth supplies already checked splice text; a partial config is intentional. */
+export interface FreshConfigWrite { kind: 'fresh'; path: string; text: string }
+export interface ConfigWriteFiles {
+  /** Narrow filesystem operations, supplied only by failure controls; CLI uses the real defaults. */
+  replace?: (from: string, to: string) => void;
+  remove?: (path: string) => void;
+  publish?: (from: string, to: string) => void;
+}
+export interface StagedConfigWrite {
+  changes: readonly ConfigWriteChange[];
+  commit(): void;
+  cancel(): void;
+  /** Combine a caller artifact failure with cleanup before its catch prints it. */
+  abort(error: unknown): never;
+}
+function refusal(code: string, path: string, detail: string): never {
+  throw new PartsError([{ code, object: path, detail }]);
+}
+function ioProblem(path: string, action: string, error: unknown): Problem {
+  return { code: 'CONFIG_WRITE_FAILED', object: path, detail: `${action}: ${error instanceof Error ? error.message : String(error)}; check the destination directory and permissions` };
+}
+function ioFailure(path: string, action: string, error: unknown): never {
+  throw new PartsError([ioProblem(path, action, error)]);
+}
+function failedOperation(path: string, action: string, error: unknown, cancel: () => void): never {
+  const problems = error instanceof PartsError ? [...error.problems] : [ioProblem(path, action, error)];
+  try { cancel(); }
+  catch (cleanup) { problems.push(...(cleanup instanceof PartsError ? cleanup.problems : [ioProblem(path, 'removing the staged config failed', cleanup)])); }
+  throw new PartsError(problems);
+}
+export function readConfigWriteTarget(path: string): ConfigWriteTarget {
+  const target = resolve(path);
+  let stat: ReturnType<typeof lstatSync>;
+  try { stat = lstatSync(target); }
+  catch (error) { return refusal('CONFIG_FILE_PRESENT', target, `cannot read the existing config: ${error instanceof Error ? error.message : String(error)}`); }
+  if (!stat.isFile()) return refusal('CONFIG_FIELD_TYPE', target, 'is not a regular file (symlinks are not replaced); --write-config updates an existing config file in place');
+  let original: string;
+  try { original = readFileSync(target, 'utf8'); }
+  catch (error) { return ioFailure(target, 'reading the destination failed', error); }
+  let raw: unknown;
+  try { raw = JSON.parse(original); }
+  catch (error) { return refusal('CONFIG_IS_JSON', target, `does not parse as JSON: ${error instanceof Error ? error.message : String(error)}`); }
+  if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) return refusal('CONFIG_FIELD_TYPE', target, 'must hold a config JSON object');
+  const duplicates = repeatedKeys(original);
+  if (duplicates.length > 0) throw new PartsError(duplicates.map((r) => ({ code: 'CONFIG_KEY_UNIQUE', object: `config${r.at === '' ? '' : `.${r.at}`}`, detail: `names ${JSON.stringify(r.key)} ${r.count} times; each key must occur once before an in-place update` })));
+  return { path: target, original, raw, mode: stat.mode & 0o777 };
+}
+/** Resolve existing ancestors too: an output parent may be an alias or not exist yet. */
+function canonical(path: string): string {
+  let at = resolve(path);
+  const tail: string[] = [];
+  for (;;) {
+    try { return join(realpathSync(at), ...tail); }
+    catch (error) {
+      if (!(error instanceof Error) || !('code' in error) || error.code !== 'ENOENT') throw error;
+      const parent = dirname(at);
+      if (parent === at) throw error;
+      tail.unshift(basename(at));
+      at = parent;
+    }
+  }
+}
+/** Refuse before ordinary propose writes any artifact that could overwrite its config. */
+export function separateConfigWriteTarget(target: Pick<ConfigWriteTarget, 'path'>, artifacts: readonly string[], code = 'CONFIG_WRITE_TARGET'): void {
+  try {
+    let identity: ReturnType<typeof statSync> | null = null;
+    try { identity = statSync(target.path); }
+    catch (error) {
+      if (!(error instanceof Error) || !('code' in error) || error.code !== 'ENOENT') throw error;
+    }
+    const targetPath = canonical(target.path);
+    for (const artifact of artifacts) {
+      let alias = canonical(artifact) === targetPath;
+      try {
+        const existing = statSync(artifact);
+        alias ||= identity !== null && existing.dev === identity.dev && existing.ino === identity.ino;
+      } catch (error) {
+        if (!(error instanceof Error) || !('code' in error) || error.code !== 'ENOENT') throw error;
+      }
+      if (alias) refusal(code, target.path, `is also the proposal output ${resolve(artifact)}; choose a config outside the command's proposal, basis and landmark artifact paths — nothing was written`);
+    }
+  } catch (error) {
+    if (error instanceof PartsError) throw error;
+    ioFailure(target.path, 'checking output collisions failed', error);
+  }
+}
+
+function unchanged(target: ConfigWriteTarget): void {
+  let same = false;
+  try {
+    const stat = lstatSync(target.path);
+    same = stat.isFile() && (stat.mode & 0o777) === target.mode && readFileSync(target.path, 'utf8') === target.original;
+  } catch { /* Removal is also a change, never a reason to create a new config. */ }
+  if (!same) refusal('CONFIG_WRITE_CHANGED', target.path, 'changed after it was read; nothing was replaced — rerun against the current config');
+}
+/** One file-writing adapter for all --write-config modes. Existing-file ownership
+ * produces whole-value edits for splicedEdits, the engine clothConfigEdits uses.
+ * Fresh cloth text already passed writtenClothConfig's splice check: it is never
+ * sent through a full loader that would reject an intentional partial config.
+ */
+export function stageConfigWrite(target: ConfigWriteTarget | FreshConfigWrite, patch?: ConfigWritePatch, files: ConfigWriteFiles = {}): StagedConfigWrite {
+  const fresh = 'kind' in target;
+  const path = resolve(target.path);
+  let text: string;
+  let changes: readonly ConfigWriteChange[];
+  if (fresh) {
+    text = target.text;
+    changes = [];
+  } else {
+    if (patch === undefined) return refusal('CONFIG_FIELD_TYPE', path, 'has no config patch; a supported proposal operation is required');
+    const merged = mergeConfigProposal(target.raw, patch);
+    const spliced = merged.changes.length === 0 ? { text: target.original, moved: null } : splicedEdits(target.original, merged.edits);
+    if (spliced.moved !== null) return refusal('CONFIG_WRITE_FAILED', path, `spliced proposal values moved ${spliced.moved}; the original was not replaced`);
+    text = spliced.text;
+    changes = merged.changes;
+  }
+  const freshAbsent = (): void => {
+    try { lstatSync(path); }
+    catch (error) {
+      if (error instanceof Error && 'code' in error && error.code === 'ENOENT') return;
+      return ioFailure(path, 'checking the fresh destination failed', error);
+    }
+    refusal('PROPOSE_WRITE_CONFIG_FRESH', path, 'exists; the config is written to a new file, never over the --cloth config or an earlier one');
+  };
+  if (fresh) freshAbsent();
+  const temp = join(dirname(path), `.${basename(path)}.rig-parts-${randomBytes(8).toString('hex')}.tmp`);
+  let owned = false;
+  const cancel = (): void => {
+    if (!owned) return;
+    owned = false;
+    try { if (files.remove === undefined) rmSync(temp, { force: true }); else files.remove(temp); }
+    catch (error) { ioFailure(temp, 'removing the staged config failed; remove this temporary after restoring directory permissions', error); }
+  };
+  let fd: number | undefined;
+  try {
+    if (fresh) mkdirSync(dirname(path), { recursive: true });
+    fd = openSync(temp, 'wx', fresh ? 0o666 : target.mode);
+    owned = true;
+    writeFileSync(fd, text);
+    if (!fresh) fchmodSync(fd, target.mode);
+    closeSync(fd);
+    fd = undefined;
+    if (!fresh) {
+      if (patch?.kind === 'head-box') loadEarlyConfig(temp, 'layers');
+      else if (patch?.kind === 'assemble-plan') loadEarlyConfig(temp, 'assemble');
+      else loadConfigAndAnimations(temp);
+    }
+  } catch (error) {
+    if (fd !== undefined) {
+      try { closeSync(fd); }
+      catch (cleanup) {
+        const primary = error instanceof PartsError ? [...error.problems] : [ioProblem(path, 'staging the config failed', error)];
+        error = new PartsError([...primary, ioProblem(temp, 'closing the staged config failed', cleanup)]);
+      }
+    }
+    return failedOperation(path, 'staging the config failed; the destination was not written', error, cancel);
+  }
+  return {
+    changes,
+    cancel,
+    abort(error: unknown): never {
+      return failedOperation(path, 'writing proposal artifacts failed', error, cancel);
+    },
+    commit(): void {
+      try {
+        if (fresh) {
+          freshAbsent();
+          // Linking the same-directory staged file publishes complete bytes and
+          // refuses an intervening creator atomically; rename would overwrite it.
+          try { (files.publish ?? linkSync)(temp, path); }
+          catch (error) {
+            if (error instanceof Error && 'code' in error && error.code === 'EEXIST') refusal('PROPOSE_WRITE_CONFIG_FRESH', path, 'exists; the config is written to a new file, never over the --cloth config or an earlier one');
+            throw error;
+          }
+          cancel();
+        } else {
+          unchanged(target);
+          if (changes.length > 0) { (files.replace ?? renameSync)(temp, path); owned = false; }
+          else cancel();
+        }
+      } catch (error) {
+        failedOperation(path, 'committing the config failed', error, cancel);
+      }
+    },
+  };
+}
+/** Print to stderr so proposal JSON on stdout remains machine-readable. */
+export function configWriteLines(target: ConfigWriteTarget, changes: readonly ConfigWriteChange[]): string[] {
+  return changes.length === 0 ? [`config ${target.path}: unchanged`] : changes.map((c) => `config ${target.path}: ${c.kind} ${c.path}`);
+}