@energy8platform/golem 0.5.0 → 0.7.0

package/skills/golem-symbol-cutting/references/hybrid-workflow.md

@@ -0,0 +1,119 @@
+# Approved artwork with generated hidden surfaces
+
+Use this route when identity, silhouette, expression and visible ink must match approved art.
+A complete generated atlas is a different brief. Parts may mix approved visible pixels,
+generated hidden continuations, and explicitly redrawn props; record this per part.
+
+## Partition by ownership, not rectangles
+
+Measure the original canvas. Mark semantic paint regions using seeds and polygons along
+ink. Order layers back to front before cutting: the shared line travels with the foreground
+part. Give a thick contour enough `inkPx` to retain its whole stroke; inspect both sides of
+that contour in motion. A polygon may split one unbroken paint region (`raw`, optionally
+`within` a prior owner). Use `minus` to correct the claim locally.
+
+Run `scripts/hybrid_parts.py partition plan.json masks/`. Example plan (illustrative coordinates):
+
+```json
+{
+  "source": "approved.png",
+  "ink": 40,
+  "layers": [
+    {"id": "coat", "seeds": [[110, 160]], "inkPx": 3},
+    {"id": "sleeve", "seeds": [[175, 150]], "inkPx": 4}
+  ]
+}
+```
+
+The script produces one ownership mask per part and a report of unassigned pixels, areas
+and island counts. Every nonzero-alpha source pixel must have one owner. It assigns nearby
+unclaimed ink deterministically; this is not semantic recognition. Inspect the result and
+correct seeds/polygons when another feature gets assigned to the wrong part.
+
+Do not automatically give all small islands to a neighbour: eyelashes, fang tips and sparks
+can be meaningful. Transfer a confirmed stray through explicit masks, retaining the source.
+If the mesh tracer would omit an intentional island, use `rig_mesh_from_image`
+`minIslandRatio: 0` or a separate registered attachment; do not alter the approved drawing
+just to satisfy a tracer threshold.
+
+## Repair hidden anatomy and ragged props
+
+Define each part's complete silhouette separately from its visible ownership. The repair
+region is the complete shape hidden by foreground layers, with real overlap through the
+planned joint range. It is not an arbitrary dilation into neighbouring anatomy.
+
+`hybrid_parts.py guide approved.png own.png hidden.png guide.png` preserves the owned
+pixels and marks the repair in magenta. The guide is an authoring aid; use the approved art
+as an additional style reference. Prompt templates and known failure modes are in
+[generation-workflow.md](generation-workflow.md). Explicitly say that the removed occluder
+must not be reconstructed. Judge scale and colour after generation, not from the prompt.
+
+Keep stable, non-collinear landmarks away from the changed region (two distinct points
+suffice for a similarity fit; three or more expose inconsistency). For example:
+
+```json
+{"source": [[70,90],[160,90],[100,180]], "generated": [[74,92],[168,92],[105,186]]}
+```
+
+Run `hybrid_parts.py extract approved.png generated.png hidden.png own.png landmarks.json fill.png`.
+Optional `--background-mask`, `--tone-mask`, `--ink-mask`, `--feather` and `--max-fit-error`
+control the ordered cleanup. Masks use source-canvas coordinates after fitting:
+
+1. Fit scale/rotation/translation; fail if the landmark residual exceeds the declared limit.
+2. Clear only reviewed background pixels. White skin highlights and eye whites remain art.
+3. Measure tone correction in unchanged opaque host material, never neighbouring skin/fabric.
+4. Blend the repair boundary toward the nearest owned colour, preserving its alpha.
+5. Replace a pale outline fringe only in a reviewed ink mask using the host's ink.
+
+The final repair is clipped to the explicit region and fails on remaining guide magenta.
+A fit report records scale, angle, residual and colour shift. This does not establish that the
+painted hidden anatomy is correct: inspect the full output and exposed motion frames.
+
+For a ragged prop, generate the entire object and register it with the same landmarks.
+Declare it as `replacement` in assembly, with its approved contour change recorded. A rigid
+camera housing and flexible strap usually need separate controls/weights. A closed eyelid
+can be an authored stroke or source-derived variant if the art supports that; do not regenerate
+a whole head solely to blink. Every variant must retain shared facial landmarks.
+
+## Assemble without revealing backing
+
+Run `hybrid_parts.py assemble assembly.json work/`. Example part:
+
+```json
+{
+  "source": "approved.png",
+  "parts": [
+    {"id":"coat", "own":"masks/coat.png", "shape":"shapes/coat.png",
+     "fill":"fills/coat.png", "joint":[120,180], "parent":"root", "underlap":2},
+    {"id":"sleeve", "own":"masks/sleeve.png", "shape":"shapes/sleeve.png",
+     "joint":[170,120], "parent":"coat", "underlap":2}
+  ]
+}
+```
+
+`parts` are back to front. Canvas dimensions come from the source, not fixed character
+constants. The script writes trimmed RGBA layers, `layers/layers.json`, debug fill masks,
+an assembled PNG and provenance. The import document uses the source canvas coordinates;
+resize/offset once in the rig hierarchy if the game canvas differs.
+Debug masks include generated fills, deterministic underlap and all backing pixels, so the
+rest-pose visibility check measures every hidden repair rather than only generator output.
+
+Underlap uses the part's own colour, stays inside its complete silhouette, and lies beneath
+fully opaque foreground pixels. Generated fills sit deeper than the antialiased edge. Do not
+copy the front layer's ink into the backing: it becomes a ghost contour when the front moves.
+A static underpainting is optional and must remain well inside the silhouette, composed only
+from declared stable surfaces. It must not contain a rest copy of a moving leg, tail or scarf.
+Prefer local repair where a static underpainting would conceal a legitimate changing gap.
+For a justified static backing, the assembly plan accepts
+`"backing": {"id":"underpaint","parts":["coat"],"inset":12,"joint":[120,180],"bone":"root"}`.
+The inset is in source pixels and must be positive; choose it from the motion clearance,
+then inspect inward swings for exposed ghost surfaces.
+
+Render the normal and magenta-debug assembly at rest and at joint extrema. Generated fill
+pixels should be invisible in approved rest art, except explicitly reviewed replacement
+regions. Test the actual rig, including semitransparent edges and texture resampling; an
+ownership partition alone does not prove a clean composite.
+
+Pass placements and provenance directly into animation. See
+[quantitative-qa.md](../../golem-symbol-animation/references/quantitative-qa.md) for current
+capture verification, reference holes, exclusion limits and negative tests.

package/skills/golem-symbol-cutting/references/registration-and-motion.md

@@ -0,0 +1,89 @@
+# Register features before accepting motion
+
+Use when generating facial parts, adding expression variants/FX, or fixing size,
+placement and overlap. The acceptance target is the composed character in motion.
+
+## Establish a measured reference
+
+1. Inspect the supplied setup art and existing action references before generating.
+   For a spritesheet, identify its cell dimensions and the relevant expression
+   frames; sheet packing alone does not establish timing or action semantics.
+2. Record the reference-to-document transform using stable landmarks: eye centers,
+   nose base, mouth corners/upper lip, chin, neck contact and clothing anchors as
+   relevant. Distinguish reference pixels, generated pixels, document pixels and
+   rendered cell pixels. Atlas dimensions are not a scale reference.
+3. For each variant record its intended width relative to the face, upper-lip or
+   other fixed anchor, center/baseline offset, and allowed contour changes. Use the
+   matching reference frame when available. Without a matching frame, use accepted
+   neighboring states and the brief, and label the choice as authored. Do not claim
+   to have measured an expression that the reference does not contain.
+
+A crop's opaque bbox is useful for detecting padding, but teeth height, cavity
+shape and painted cheek content affect perceived size. Equal bbox dimensions or
+centers do not guarantee equal mouth size or vertical registration. A common scale
+factor works only if the variants already share verified registration; independent
+generations must each be fitted to the same landmark system. Prefer uniform scaling
+for intact parts; inspect any nonuniform fitting for unintended distortion.
+
+For a layer containing paired features, measure and register each feature separately.
+Shrinking the pair's bounding box also shrinks the distance between the features;
+small replacement pupils or symbols should normally keep the accepted eye spacing.
+Use independent atlas regions/attachments or preserve their document-space offsets
+on a shared canvas. Match each feature's anchor, not only the pair's centre.
+
+## Construct local changes and actual occluders
+
+- A mouth-only variant contains the intended line/lips/cavity/teeth/tongue, not
+  unrelated cheeks, nose, beard or a new face silhouette. Specify these exclusions
+  in generation prompts and inspect the result. Remove the original mouth from the
+  base and restore its backing. Reject or regenerate oversized semantic patches
+  instead of merely shrinking their unwanted face pixels.
+- Keep the accepted head silhouette and stable landmarks. Full-head replacements
+  are appropriate for a required view or global expression change; for a local
+  mouth/blink, prefer local attachments or deformation. A shared generation canvas
+  is not proof that independently generated heads match.
+- Define draw order for the actual overlap, for example back hood/torso → neck →
+  front collar → head/beard → mouth/FX. This is an anatomy-dependent example, not a
+  universal hierarchy. Generate a front collar when required, not a torso crop
+  masquerading as one. Check that it covers the neck without cutting the chin or
+  beard through the planned rotations and translations.
+- Register eye glow to the final fitted eye locations, and horn highlights to the
+  final horn. Parent them to the corresponding control. Recompute their local
+  placement after changing the base or expression registration. Inspect every
+  state where the effect is visible; one aligned setup does not prove the swaps.
+
+## Account for articulation and the composed transform
+
+Fit features after accounting for attachment size/center, bone hierarchy and keyed
+scale/translation/deformation. A PNG that fits the head at setup can still spill
+outside it during an action. Unless the brief calls for expansion, keep mouth
+corners within the intended cheek contour and align the stable upper-lip/nose
+relationship; increasing openness need not increase outer width or move the whole
+mouth upward.
+
+When the intended performance opens the jaw, prepare continuous lower-face/chin
+art and a mouth cavity that cover the motion. In animation, use a suitable mesh or
+jaw control with a smooth influence into the lower face. Keep nose/upper-face
+landmarks anchored unless their movement is deliberate. Coordinate the mouth with
+the moving surface and check the whole opening/closing path, not only its peak.
+Mesh topology and vertex counts do not themselves establish correct articulation.
+
+## Review a complete correction
+
+For each affected action, render a comparison using the same camera, background
+and scale, with setup, every expression, both sides of each switch and extremes.
+Include a face/joint closeup and playback at actual cell size and speed. Check:
+
+- silhouette/proportions and stable landmarks against the reference;
+- all variants, including the largest mouth, and simultaneous FX;
+- mouth backing, neck/collar coverage and absence of duplicate outlines;
+- interpolation, mesh folds, jaw closing, loop seams and return to idle;
+- whether idle and the intended accent are perceptible in normal playback.
+
+After a user reports a defect, turn it into an observable criterion, for example
+“upper lip stays below the nose and mouth corners remain inside both cheeks during
+all three states.” Preserve accepted parts and correct the failed relationship.
+If the same defect survives a correction, revisit the reference transform,
+landmarks, runtime transforms or semantic part boundary before trying another
+arbitrary percentage. Do not report “matches exactly” from a bbox measurement or
+“fixed” from a build/rig checker. Describe the visual evidence and remaining limits.

package/skills/golem-symbol-cutting/references/spine-rive-construction.md

@@ -0,0 +1,73 @@
+# Construction lessons from Spine and Rive
+
+Use this reference for a new character, large joint motion, turns, reuse of a public rig,
+or a decision between cuts and meshes. These are construction choices, not a fixed recipe.
+The examples below were inspected on 2026-10-05; distinguish source-file measurements,
+runtime observation and an interpretation of a finished image.
+
+## Obtain evidence before cutting
+
+A Spine reference is useful when its skeleton JSON, text atlas and all page images are
+available together. Keep the exporter version, selected skin, animation names and source
+URL. A `.spine` project contains authoring information; a rendered GIF only shows the
+result. For Rive, preserve the `.riv`, artboard and named timeline/state machine. Loading
+a `.riv` in a runtime reveals playback and exposed inputs; it does not prove recovery of
+the editor's paths, bone weights or original layered artwork. Do not describe observation
+of a finished animation as measurement of its topology.
+
+Public availability is not permission to redistribute artwork. Record its actual license
+or reuse terms with the source. Use examples to learn mechanisms; keep downloaded source
+art outside a production delivery unless its use is authorized.
+
+## Choose the smallest construction that carries the action
+
+| Example / source | Construction lesson | Application to cutting |
+|---|---|---|
+| [Spine Raptor](https://esotericsoftware.com/spine-examples-raptor) | A continuous weighted surface spans several bones; independent controls preserve contacts | A thigh need not become one PNG per bone. Keep the joint's painted continuation and blend only where it should bend |
+| [Spine Stretchyman](https://esotericsoftware.com/spine-examples-stretchyman) | IK controls endpoints while paths shape flexible limbs | Prepare a continuous limb strip with stable ends and inspect its most compressed curve before committing to a mesh |
+| [Spine Spineboy](https://esotericsoftware.com/spine-examples-spineboy) | Rigid parts, deformation, attachment swaps and clipping coexist | Keep rigid hands/props rigid, prepare local swaps, and draw the complete masked object rather than cutting the currently visible fragment |
+| [Spine Mix and Match](https://esotericsoftware.com/spine-examples-mix-and-match) | Appearance variants share controls and placeholders | Register variants to joints and semantic landmarks; do not assemble arbitrary first attachments from different skins |
+| [Rive bones](https://rive.app/docs/editor/manipulating-shapes/bones) | Parenting moves a whole element; binding deforms raster vertices or vector points/handles | Choose rigid parenting for shoes/hands, weighted deformation for sleeves; vector curves are not a raster atlas to crop |
+| [Rive meshes](https://rive.app/docs/editor/manipulating-shapes/meshes) | A raster image can retain its mesh while its image changes | Reuse only when dimensions, landmarks and intended deformation correspond; shared topology does not guarantee matching artwork |
+| [Rive Solos](https://rive.app/docs/editor/manipulating-shapes/solos) | Mutually exclusive drawings occupy one logical control | Place eyelid, mouth or grip alternatives in one swap slot when they replace each other; isolate simultaneously visible teeth/tongue separately |
+
+For every required extreme, record: which edge becomes visible, which feature is rigid,
+which surface bends, what remains in contact, what changes drawing and what crosses an
+occluder. This defines the cuts more reliably than naming anatomical parts first.
+
+## Coverage, mesh topology and variants
+
+Separate three margins: painted joint backing covers articulation; transparent padding
+allows texture sampling; packing extrusion protects atlas edges. They solve different
+problems. A mask changes visibility and cannot provide missing skin, cloth or outline.
+
+Keep triangles local to the material they deform. Do not bridge an open mouth, the gap
+between legs, a disconnected spark or a silhouette notch just to obtain a smaller mesh.
+Put enough vertices around a bend to retain volume, then use few enough to remain editable.
+Pin rigid tips and landmarks; blend adjacent bones around the joint rather than smearing
+weights over the entire image. Auto tracing/weights are starting points; inspect the bind
+pose and both bending directions. Do not transfer numerical weights between unrelated rigs.
+
+A torso, forearm or head changing front/back orientation may need alternate views or
+registered segment swaps. Mark the switching pose and matching landmarks during cutting.
+Design the front/back layer relationship at contact: a prop may need a rear body and a
+foreground grip so fingers can cross it without changing the bone hierarchy.
+
+For a face, define the clean backing, eyelid coverage, pupil containment, mouth cavity,
+and expression ownership. A local expression should not change the head silhouette by
+accident. Test combined gaze × blink × emotion × mouth opening, not only isolated drawings.
+Rive's public `look.riv` and `birb.riv` demonstrate independent named facial/motion timelines;
+their runtime playback alone does not establish whether a particular feature uses a swap
+or deformation internally.
+
+## Atlas evidence and handoff
+
+Spine attachment keys are skin placeholders. An attachment's `path`, or its `name` override,
+can select a different texture region. Linked meshes share geometry while using another
+image. Sequence numbering has a declared start (Spine defaults to 1); never infer frame
+chronology from packing coordinates. Retain original size, trim offset, packed rotation,
+page and source-to-document placement independently.
+
+Choose a coherent skin explicitly before validating the setup. Record inaccessible source
+layers and absent views as missing evidence. Include the hardest bend, the occlusion crossing
+and the swap boundary in the cutting QA handoff; pass that same brief to animation.

package/skills/golem-symbol-cutting/scripts/atlas_parts.py

@@ -0,0 +1,87 @@
+#!/usr/bin/env python3
+"""Inspect a PNG and crop parts using an agent-authored manifest; requires Pillow."""
+import argparse
+import hashlib
+import json
+import re
+from pathlib import Path
+from PIL import Image, ImageDraw
+
+
+def checker(size):
+    bg = Image.new('RGBA', size, '#b7bcc4')
+    draw = ImageDraw.Draw(bg)
+    for y in range(0, size[1], 20):
+        for x in range(0, size[0], 20):
+            if (x // 20 + y // 20) % 2:
+                draw.rectangle((x, y, x + 19, y + 19), fill='#e5e7eb')
+    return bg
+
+
+def run():
+    parser = argparse.ArgumentParser(description=__doc__, epilog='Manifest: [{"id":"head","rect":[x,y,width,height]}, ...]. Coordinates are ORIGINAL PNG pixels, manually selected from raster inspection. Output PNG crops preserve all RGBA values, without trimming, rotation or alpha cleanup.')
+    parser.add_argument('atlas', type=Path)
+    parser.add_argument('out_dir', type=Path)
+    parser.add_argument('--manifest', type=Path, help='Agent-authored JSON crop list; omit for inspection only')
+    parser.add_argument('--inspection-width', type=int, default=1600)
+    parser.add_argument('--overwrite', action='store_true', help='Replace only this invocation\'s named outputs')
+    args = parser.parse_args()
+    if args.inspection_width < 1:
+        parser.error('--inspection-width must be positive')
+    with Image.open(args.atlas) as source:
+        if source.format != 'PNG':
+            parser.error('input must be a PNG')
+        image = source.convert('RGBA')
+    specs = json.loads(args.manifest.read_text()) if args.manifest else []
+    if not isinstance(specs, list):
+        parser.error('manifest must be a list of {id, rect} objects')
+    ids = set()
+    for item in specs:
+        if not isinstance(item, dict) or set(item) != {'id', 'rect'}:
+            parser.error('each part must contain exactly id and rect')
+        name, rect = item['id'], item['rect']
+        if not isinstance(name, str) or not re.fullmatch(r'[a-z][a-z0-9_]*', name) or name in ids:
+            parser.error('part IDs must be unique snake_case names')
+        ids.add(name)
+        if not isinstance(rect, list) or len(rect) != 4 or any(type(v) is not int for v in rect):
+            parser.error(f'{name}: rect must contain four integers')
+        x, y, w, h = rect
+        if x < 0 or y < 0 or w < 1 or h < 1 or x + w > image.width or y + h > image.height:
+            parser.error(f'{name}: rectangle is outside {image.width}x{image.height}')
+    outputs = [args.out_dir / 'inspection.jpg', args.out_dir / 'source-record.json']
+    if specs:
+        outputs += [args.out_dir / 'parts.jpg'] + [args.out_dir / 'layers' / f'{s["id"]}.png' for s in specs]
+    protected = {args.atlas.resolve()}
+    if args.manifest:
+        protected.add(args.manifest.resolve())
+    for output in outputs:
+        if output.resolve() in protected:
+            parser.error(f'output would overwrite an input: {output}')
+        if output.exists() and not args.overwrite:
+            parser.error(f'output exists: {output}; choose another directory or --overwrite')
+    args.out_dir.mkdir(parents=True, exist_ok=True)
+    inspection = checker(image.size)
+    inspection.alpha_composite(image)
+    inspection.thumbnail((args.inspection_width, image.height))
+    inspection.convert('RGB').save(outputs[0], quality=92)
+    record = {'source': str(args.atlas.resolve()), 'sha256': hashlib.sha256(args.atlas.read_bytes()).hexdigest(), 'size': list(image.size), 'inspectionSize': list(inspection.size), 'sourcePixelsPerInspectionPixel': [image.width / inspection.width, image.height / inspection.height], 'parts': specs, 'operations': 'RGBA crop only; no trim, alpha cleanup, rotation'}
+    if specs:
+        (args.out_dir / 'layers').mkdir(exist_ok=True)
+        sheet = checker((1000, ((len(specs) + 3) // 4) * 240))
+        draw = ImageDraw.Draw(sheet)
+        for i, item in enumerate(specs):
+            x, y, w, h = item['rect']
+            part = image.crop((x, y, x + w, y + h))
+            part.save(args.out_dir / 'layers' / f'{item["id"]}.png')
+            part.thumbnail((230, 190))
+            sx, sy = (i % 4) * 250, (i // 4) * 240
+            sheet.alpha_composite(part, (sx + (250 - part.width) // 2, sy + 42))
+            draw.text((sx + 7, sy + 5), item['id'], fill='black')
+            draw.text((sx + 7, sy + 20), f'{x},{y}  {w}x{h}', fill='black')
+        sheet.convert('RGB').save(args.out_dir / 'parts.jpg', quality=92)
+    outputs[1].write_text(json.dumps(record, indent=2) + '\n')
+    print(json.dumps({'out': str(args.out_dir.resolve()), 'size': list(image.size), 'parts': len(specs)}))
+
+
+if __name__ == '__main__':
+    run()

package/skills/golem-symbol-cutting/scripts/hybrid_parts.py

@@ -0,0 +1,279 @@
+#!/usr/bin/env python3
+"""Approved art + generated hidden surfaces. Dependencies: Pillow, numpy.
+
+Run --help. All masks and landmarks use ORIGINAL source-canvas pixels. No character-specific sizes.
+Partition plans: {source, layers:[{id,seeds:[[x,y]],polys:[[[x,y],...]],raw:[...],minus:[...],inkPx:4}]}
+Layers are back-to-front. Shared ink belongs to the foreground claimant; islands are preserved.
+Assembly plans: {source, parts:[{id,own,shape,fill?,replacement?,joint:[x,y],bone?,parent?,underlap:2}]}.
+Paths are relative to the plan. own/shape are grayscale masks on the source canvas; fill/replacement RGBA.
+"""
+import argparse
+from collections import deque
+import hashlib
+import json
+from pathlib import Path
+import re
+import numpy as np
+from PIL import Image, ImageDraw, ImageFilter
+
+
+def rgba(path):
+    return np.array(Image.open(path).convert('RGBA'))
+
+
+def mask(path, shape):
+    a = np.array(Image.open(path).convert('L')) > 127
+    if a.shape != shape:
+        raise ValueError(f'mask {path}: dimensions differ from source')
+    return a
+
+
+def polygon(shape, polys):
+    im = Image.new('L', (shape[1], shape[0]))
+    draw = ImageDraw.Draw(im)
+    for p in polys:
+        draw.polygon([tuple(x) for x in p], fill=255)
+    return np.array(im) > 0
+
+
+def dilate(m, radius):
+    if radius < 0 or int(radius) != radius:
+        raise ValueError('dilation radius must be a nonnegative integer')
+    return np.array(Image.fromarray(m.astype('uint8') * 255).filter(ImageFilter.MaxFilter(radius * 2 + 1))) > 0 if radius else m.copy()
+
+
+def labels(m):
+    """Four-connected components, preserving small islands; returns labels and areas."""
+    h, w = m.shape
+    out = np.zeros((h, w), np.int32)
+    sizes = [0]
+    for y, x in zip(*np.nonzero(m)):
+        if out[y, x]:
+            continue
+        i = len(sizes)
+        q = deque([(y, x)])
+        out[y, x] = i
+        size = 0
+        while q:
+            cy, cx = q.popleft()
+            size += 1
+            for ny, nx in ((cy-1,cx),(cy+1,cx),(cy,cx-1),(cy,cx+1)):
+                if 0 <= ny < h and 0 <= nx < w and m[ny, nx] and not out[ny, nx]:
+                    out[ny, nx] = i
+                    q.append((ny, nx))
+        sizes.append(size)
+    return out, np.array(sizes)
+
+
+def nearest(own):
+    """Deterministic nearest (Manhattan distance) source indices and distance; empty source is an error."""
+    if not own.any():
+        raise ValueError('nearest-colour source mask is empty')
+    h, w = own.shape
+    iy, ix = np.indices(own.shape)
+    dist = np.full(own.shape, -1, np.int32)
+    dist[own] = 0
+    edge = own & dilate(~own, 1)
+    q = deque(zip(*np.nonzero(edge)))
+    while q:
+        y, x = q.popleft()
+        for ny, nx in ((y-1,x),(y+1,x),(y,x-1),(y,x+1)):
+            if 0 <= ny < h and 0 <= nx < w and dist[ny, nx] < 0:
+                dist[ny,nx] = dist[y,x] + 1
+                iy[ny,nx], ix[ny,nx] = iy[y,x], ix[y,x]
+                q.append((ny,nx))
+    return iy, ix, dist
+
+
+def partition(ref, layers, ink=40):
+    visible = ref[...,3] > 0
+    inkm = visible & (ref[...,:3].max(axis=2) < ink)
+    lab, size = labels(visible & ~inkm)
+    owner = np.full(visible.shape, -1, np.int32)
+    claims = []
+    ids = [p['id'] for p in layers]
+    if len(set(ids)) != len(ids) or any(not re.fullmatch('[a-z][a-z0-9_]*', i) for i in ids):
+        raise ValueError('part ids must be unique snake_case')
+    for i, p in enumerate(layers):
+        c = np.zeros_like(visible)
+        for x,y in p.get('seeds', []):
+            if not (0 <= y < lab.shape[0] and 0 <= x < lab.shape[1]) or not lab[y,x]:
+                raise ValueError(f'{ids[i]}: seed {x},{y} is outside paint or on ink')
+            c |= lab == lab[y,x]
+        if p.get('polys'):
+            hit = np.bincount(lab[polygon(visible.shape,p['polys'])], minlength=len(size))
+            take = (size > 0) & (hit * 2 >= size)
+            take[0] = False
+            c |= take[lab]
+        c |= polygon(visible.shape,p.get('raw',[])) & visible
+        c |= polygon(visible.shape,p.get('rawInk',[])) & inkm
+        c &= ~polygon(visible.shape,p.get('minus',[]))
+        if p.get('within'):
+            j = ids.index(p['within'])
+            if j >= i: raise ValueError('within must name an earlier layer')
+            c &= owner == j
+        owner[c & ~inkm] = i
+        claims.append(c)
+    for i,c in enumerate(claims):
+        owner[inkm & dilate(c, layers[i].get('inkPx',4))] = i
+    if (owner >= 0).any():
+        iy,ix,_ = nearest(owner >= 0)
+        rest = visible & (owner < 0)
+        owner[rest] = owner[iy[rest],ix[rest]]
+    return {p['id']: owner == i for i,p in enumerate(layers)}, visible & (owner < 0)
+
+
+def fit_similarity(generated, source):
+    """Least-squares similarity from explicit corresponding landmarks; reports fit error, never guesses scale."""
+    g, s = np.array(generated,float), np.array(source,float)
+    if g.shape != s.shape or g.ndim != 2 or g.shape[1] != 2 or len(g) < 2 or not np.isfinite(g).all() or not np.isfinite(s).all():
+        raise ValueError('need at least two finite matching landmark pairs')
+    a,b = g-g.mean(0),s-s.mean(0)
+    if (a*a).sum() < 1e-9: raise ValueError('generated landmarks coincide')
+    u,sv,vt = np.linalg.svd(a.T @ b)
+    fix = np.diag([1, np.linalg.det(u @ vt)])
+    rot = u @ fix @ vt
+    scale = float((sv * np.diag(fix)).sum() / (a*a).sum())
+    if scale <= 0: raise ValueError('invalid fitted scale')
+    offset = s.mean(0)-g.mean(0) @ (scale*rot)
+    predicted = g @ (scale*rot)+offset
+    residual = float(np.max(np.linalg.norm(predicted-s,axis=1)))
+    # Pillow maps each output/source point back into the generated image.
+    inv = np.linalg.inv(scale*rot)
+    shift = -offset @ inv
+    coeff = (inv[0,0],inv[1,0],shift[0],inv[0,1],inv[1,1],shift[1])
+    return coeff, {'scale':scale,'rotation_degrees':float(np.degrees(np.arctan2(rot[0,1],rot[0,0]))),'max_residual':residual}
+
+
+def extract(ref, gen, region, own, pairs, background=None, tone=None, ink=None, feather=4, max_error=2):
+    coeff, stats = fit_similarity(pairs['generated'],pairs['source'])
+    if stats['max_residual'] > max_error: raise ValueError(f'landmark residual exceeds {max_error}: {stats}')
+    im = Image.fromarray(gen).convert('RGBa').transform((ref.shape[1],ref.shape[0]),Image.Transform.AFFINE,coeff,Image.Resampling.BICUBIC).convert('RGBA')
+    out = np.array(im)
+    if background is not None: out[background,3] = 0  # explicit background mask; never globally delete white paint
+    if tone is not None:
+        band = tone & own & (out[...,3]>240) & (ref[...,3]>240)
+        if not band.any(): raise ValueError('tone mask contains no comparable opaque approved pixels')
+        offset = np.median(ref[band,:3].astype(float)-out[band,:3],axis=0)
+        out[...,:3] = np.clip(out[...,:3].astype(float)+offset,0,255).astype('uint8')
+        stats['tone_offset'] = offset.tolist()
+    iy,ix,dist = nearest(own)
+    if feather:
+        w = np.clip(dist/max(feather,1),0,1)[...,None]
+        paint = region & (out[...,3]>0)
+        out[paint,:3] = (out[paint,:3]*w[paint]+ref[iy[paint],ix[paint],:3]*(1-w[paint])).astype('uint8')
+    if ink is not None:
+        known = own & (ref[...,:3].max(axis=2)<60)
+        ky,kx,_ = nearest(known)
+        fix = ink & region & (out[...,3]>0)
+        out[fix,:3] = ref[ky[fix],kx[fix],:3]
+    out[~region] = 0
+    pink = region & (out[...,3]>0) & (out[...,0]>220) & (out[...,1]<70) & (out[...,2]>220)
+    stats['magenta_pixels'] = int(pink.sum())
+    if pink.any(): raise ValueError(f'generation still contains guide magenta: {stats}')
+    return out, stats
+
+
+def underlap(ref, own, front, shape, radius):
+    """Only extend the part's own colour, inside its complete silhouette and under fully opaque foreground."""
+    iy,ix,dist = nearest(own)
+    use = (dist>0) & (dist<=radius) & front & shape
+    out = np.zeros_like(ref)
+    out[use,:3] = ref[iy[use],ix[use],:3]
+    out[use,3] = 255
+    return out
+
+
+def assemble(plan, base, outdir):
+    ref = rgba(base/plan['source']); shape = ref.shape[:2]; parts = plan['parts']
+    ids = [p['id'] for p in parts]
+    if not ids or len(set(ids)) != len(ids) or any(not re.fullmatch('[a-z][a-z0-9_]*', i) for i in ids):
+        raise ValueError('assembly part ids must be unique snake_case')
+    owns = [mask(base/p['own'],shape) for p in parts]
+    coverage = np.sum(owns,axis=0)
+    if (coverage>1).any(): raise ValueError('approved pixel ownership overlaps')
+    if ((ref[...,3]>0)&(coverage==0)).any(): raise ValueError('approved pixels are unassigned')
+    layers = outdir/'layers'; debug = outdir/'debug-masks'
+    layers.mkdir(parents=True,exist_ok=True);debug.mkdir(exist_ok=True)
+    entries=[]; completed={}; composite=Image.new('RGBA',(shape[1],shape[0]))
+    for i,p in enumerate(parts):
+        own=owns[i]; front=np.any(owns[i+1:],axis=0) if i+1<len(parts) else np.zeros(shape,bool)
+        front &= ref[...,3] == 255
+        complete=mask(base/p['shape'],shape)
+        if (own & ~complete).any(): raise ValueError(f"{p['id']}: complete shape excludes approved pixels")
+        img=underlap(ref,own,front,complete,p.get('underlap',2))
+        fillmask=img[...,3]>0
+        if p.get('fill'):
+            fill=rgba(base/p['fill'])
+            if fill.shape!=ref.shape: raise ValueError('fill canvas mismatch')
+            paint=(fill[...,3]>0)&~own&complete&front&~dilate(~front,1)
+            img[paint]=fill[paint];fillmask|=paint
+        img[own]=ref[own]
+        if p.get('replacement'):
+            replacement=rgba(base/p['replacement'])
+            if replacement.shape!=ref.shape: raise ValueError('replacement canvas mismatch')
+            # A fully generated part is an explicitly declared departure from source-pixel identity.
+            img=replacement.copy();fillmask=img[...,3]>0
+        yy,xx=np.nonzero(img[...,3])
+        if not len(xx): raise ValueError(f"empty part {p['id']}")
+        x,y,x1,y1=int(xx.min()),int(yy.min()),int(xx.max()+1),int(yy.max()+1)
+        Image.fromarray(img[y:y1,x:x1]).save(layers/f"{p['id']}.png")
+        Image.fromarray((fillmask[y:y1,x:x1]*255).astype('uint8')).save(debug/f"{p['id']}.png")
+        completed[p['id']]=img.copy()
+        composite.alpha_composite(Image.fromarray(img))
+        e={'id':p['id'],'file':p['id']+'.png','bbox':[x,y,x1-x,y1-y],'joint':p['joint'],'z':i,'inpainted':bool(p.get('fill') or p.get('replacement'))}
+        for k in ['bone','parent','slot','swap']:
+            if k in p:e[k]=p[k]
+        entries.append(e)
+    if plan.get('backing'):
+        b=plan['backing']; back=Image.new('RGBA',(shape[1],shape[0]))
+        if not b.get('parts') or b.get('inset',0)<=0: raise ValueError('backing requires stable part ids and a positive inset')
+        for lid in b['parts']:
+            if lid not in completed: raise ValueError('unknown backing part '+lid)
+            back.alpha_composite(Image.fromarray(completed[lid]))
+        pixels=np.array(back);inside=~dilate(ref[...,3]<255,int(b['inset']))
+        pixels[~inside]=0; yy,xx=np.nonzero(pixels[...,3])
+        if not len(xx): raise ValueError('backing inset leaves no painted pixels')
+        x,y,x1,y1=int(xx.min()),int(yy.min()),int(xx.max()+1),int(yy.max()+1)
+        lid=b.get('id','underpaint')
+        if lid in ids or not re.fullmatch('[a-z][a-z0-9_]*',lid): raise ValueError('backing id must be unique snake_case')
+        Image.fromarray(pixels[y:y1,x:x1]).save(layers/(lid+'.png'))
+        Image.fromarray(((pixels[y:y1,x:x1,3]>0)*255).astype('uint8')).save(debug/(lid+'.png'))
+        entries.insert(0,{'id':lid,'file':lid+'.png','bbox':[x,y,x1-x,y1-y],'joint':b['joint'],'bone':b['bone'],'z':-1})
+        back=Image.fromarray(pixels);back.alpha_composite(composite);composite=back
+    composite.save(outdir/'assembly.png')
+    (layers/'layers.json').write_text(json.dumps(entries,indent=2))
+    (outdir/'provenance.json').write_text(json.dumps({'source_sha256':hashlib.sha256((base/plan['source']).read_bytes()).hexdigest(),'plan':plan},indent=2))
+
+
+def main():
+    ap=argparse.ArgumentParser(description=__doc__,formatter_class=argparse.RawDescriptionHelpFormatter)
+    sub=ap.add_subparsers(dest='cmd',required=True)
+    for cmd in ['partition','assemble']:
+        p=sub.add_parser(cmd);p.add_argument('plan',type=Path);p.add_argument('output',type=Path)
+    p=sub.add_parser('guide');p.add_argument('source',type=Path);p.add_argument('own',type=Path);p.add_argument('region',type=Path);p.add_argument('output',type=Path)
+    p=sub.add_parser('extract');p.add_argument('source',type=Path);p.add_argument('generated',type=Path);p.add_argument('region',type=Path);p.add_argument('own',type=Path);p.add_argument('landmarks',type=Path);p.add_argument('output',type=Path)
+    for name in ['background','tone','ink']:p.add_argument('--'+name+'-mask',type=Path)
+    p.add_argument('--feather',type=int,default=4);p.add_argument('--max-fit-error',type=float,default=2)
+    a=ap.parse_args()
+    if a.cmd in ['partition','assemble']:
+        plan=json.loads(a.plan.read_text());base=a.plan.parent;a.output.mkdir(parents=True,exist_ok=True)
+        if a.cmd=='assemble': assemble(plan,base,a.output);return
+        ref=rgba(base/plan['source']);masks,missing=partition(ref,plan['layers'],plan.get('ink',40))
+        for k,m in masks.items():
+            if not m.any():raise ValueError(f'empty part {k}')
+            Image.fromarray((m*255).astype('uint8')).save(a.output/(k+'.png'))
+        report={'unassigned':int(missing.sum()),'parts':{k:int(m.sum()) for k,m in masks.items()},'islands':{k:len(labels(m)[1])-1 for k,m in masks.items()}}
+        (a.output/'partition.json').write_text(json.dumps(report,indent=2));print(json.dumps(report))
+        if missing.any():raise ValueError('unassigned source pixels')
+    else:
+        ref=rgba(a.source);shape=ref.shape[:2];own=mask(a.own,shape);region=mask(a.region,shape)
+        if a.cmd=='guide':
+            out=np.zeros_like(ref);out[own]=ref[own];out[region]=(255,0,255,255);Image.fromarray(out).save(a.output)
+        else:
+            get=lambda name:mask(getattr(a,name+'_mask'),shape) if getattr(a,name+'_mask') else None
+            out,stats=extract(ref,rgba(a.generated),region,own,json.loads(a.landmarks.read_text()),get('background'),get('tone'),get('ink'),a.feather,a.max_fit_error)
+            Image.fromarray(out).save(a.output);a.output.with_suffix('.fit.json').write_text(json.dumps(stats,indent=2));print(json.dumps(stats))
+
+
+if __name__=='__main__':main()