@energy8platform/golem 0.6.0 → 0.8.0

package/skills/golem-symbol-animation/scripts/image_gates.py

@@ -0,0 +1,143 @@
+#!/usr/bin/env python3
+"""Image QA for current runtime captures. Pillow + numpy, no character-specific thresholds.
+
+image_gates.py CONFIG.json REPORT.json
+Config: {rig,renderer,frames,reference,times:[...],animation:null|id,mode:'rest'|'holes',
+         scale:1,region?:[x,y,w,h],maxMean:2,maxP99:12,maxTileMean:6,maxBoundsDelta:2,
+         maxHolePixels:20,maxExcludedArea:0.05,maxExcludedFrames:0.1,
+         exceptions:[{reason,frames:[indices],mask}], debugFrames?:directory}
+Paths relative to config. Captures must come from rig_render_preview(framesDir,transparent:true).
+Every expected frame is verified and measured. Exceptions are masks with reasons, not skipped frames.
+"""
+import argparse
+from collections import deque
+import hashlib
+import json
+from pathlib import Path
+import numpy as np
+from PIL import Image
+
+
+def sha(p):return hashlib.sha256(Path(p).read_bytes()).hexdigest()
+def image(p):return np.array(Image.open(p).convert('RGBA'))
+
+
+def labels(m):
+    h,w=m.shape;lab=np.zeros(m.shape,np.int32);count=0
+    for y,x in zip(*np.nonzero(m)):
+        if lab[y,x]:continue
+        count+=1;q=deque([(y,x)]);lab[y,x]=count
+        while q:
+            cy,cx=q.popleft()
+            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 lab[ny,nx]:lab[ny,nx]=count;q.append((ny,nx))
+    return lab,count
+
+
+def holes(alpha):
+    clear=alpha<5;lab,n=labels(clear)
+    outside=set(np.unique(np.concatenate([lab[0],lab[-1],lab[:,0],lab[:,-1]])))-{0}
+    enclosed=(lab>0)&~np.isin(lab,list(outside))
+    # Partial-alpha cracks fully surrounded by artwork. Boundary antialiasing is not a crack.
+    from PIL import ImageFilter
+    exterior=np.isin(lab,list(outside))
+    border=np.array(Image.fromarray(exterior.astype('uint8')*255).filter(ImageFilter.MaxFilter(5)))>0
+    seams=(alpha>=5)&(alpha<250)&~border
+    return enclosed|seams
+
+
+def capture(folder,rig,renderer,times,animation,scale=1,region=None,debug=False):
+    m=json.loads((folder/'manifest.json').read_text())
+    if m.get('version')!=1 or not m.get('frames') or m.get('times')!=times or m.get('animation')!=animation:raise ValueError('capture does not cover requested animation/times')
+    if not m.get('transparent'):raise ValueError('image gates require transparent frames')
+    opts=m.get('render')
+    if opts is None:raise ValueError('capture lacks render settings; capture fresh frames')
+    if opts.get('overlayBones') or opts.get('onionSkin') or opts.get('weightBone'):raise ValueError('image gates require artwork without overlays')
+    if m.get('scale')!=scale or opts.get('region')!=region:raise ValueError('capture scale/crop differs from declared comparison')
+    if bool(opts.get('debugFillMasks'))!=debug:raise ValueError('wrong debug fill mode')
+    if sha(rig)!=m.get('rigFile'):raise ValueError('stale rig render')
+    if sha(renderer)!=m['identity']['renderer']:raise ValueError('stale renderer')
+    current=json.loads(rig.read_text())
+    for a in current['assets']:
+        if sha(rig.parent/a['src'])!=m['identity']['assets'].get(a['src']):raise ValueError('stale asset: '+a['src'])
+    for p,h in m['identity'].get('masks',{}).items():
+        if sha(rig.parent/p)!=h:raise ValueError('stale fill mask: '+p)
+    names=[f['file'] for f in m['frames']]
+    if len(names)!=len(times) or len(set(names))!=len(names) or sorted(names)!=sorted(p.name for p in folder.glob('*.png')):raise ValueError('missing, duplicate or unmanifested frames')
+    import re
+    for f in m['frames']:
+        if not re.fullmatch(r'\d{6}\.png',f['file']) or sha(folder/f['file'])!=f['sha256']:raise ValueError('changed/invalid frame '+f['file'])
+    return m
+
+
+def composite(a,bg):
+    alpha=a[...,3:4].astype(float)/255
+    return a[...,:3]*alpha+bg*(1-alpha)
+
+
+def run(cfg,base):
+    if cfg.get('mode') not in ('rest','holes'):raise ValueError('mode must be rest or holes')
+    times=cfg['times']
+    if not times or any(not np.isfinite(t) or t<0 for t in times) or any(b<=a for a,b in zip(times,times[1:])):raise ValueError('expected times must be nonempty and strictly increasing')
+    folder=base/cfg['frames'];rig=base/cfg['rig'];renderer=base/cfg['renderer'];animation=cfg.get('animation')
+    m=capture(folder,rig,renderer,times,animation,cfg.get('scale',1),cfg.get('region'))
+    ref=image(base/cfg['reference']);live=ref[...,3]>0
+    if not live.any():raise ValueError('empty reference')
+    baseline=holes(ref[...,3]);exceptions=cfg.get('exceptions',[]);excluded_frames=set();rows=[]
+    debug=base/cfg['debugFrames'] if cfg.get('debugFrames') else None
+    if debug:capture(debug,rig,renderer,times,animation,cfg.get('scale',1),cfg.get('region'),True)
+    for i,f in enumerate(m['frames']):
+        got=image(folder/f['file'])
+        if got.shape!=ref.shape:raise ValueError('reference and capture dimensions differ')
+        if not (got[...,3]>8).any():raise ValueError(f'frame {i}: artwork is empty')
+        allowed=np.zeros(live.shape,bool)
+        for e in exceptions:
+            if not e.get('reason','').strip() or not e.get('frames'):raise ValueError('exceptions need an explicit reason and frame indices')
+            if any(j<0 or j>=len(times) for j in e['frames']):raise ValueError('exception names an absent frame')
+            if i in e['frames']:
+                mask=np.array(Image.open(base/e['mask']).convert('L'))>127
+                if mask.shape!=live.shape:raise ValueError('exception mask dimensions differ')
+                allowed|=mask
+        scope=live|(got[...,3]>0)
+        fraction=float((allowed&scope).sum()/max(1,scope.sum()))
+        if fraction>cfg.get('maxExcludedArea',.05):raise ValueError(f'frame {i}: excluded area {fraction:.1%} exceeds declared budget')
+        if allowed.any():excluded_frames.add(i)
+        compare=scope&~allowed
+        if not compare.any():raise ValueError('no pixels left to judge')
+        d=np.maximum(np.abs(composite(ref,0)-composite(got,0)),np.abs(composite(ref,255)-composite(got,255))).mean(axis=2)
+        worst_tile=0.0;worst_xy=[0,0]
+        for y in range(0,ref.shape[0],16):
+            for x in range(0,ref.shape[1],16):
+                take=compare[y:y+16,x:x+16]
+                if take.any():
+                    mean=float(d[y:y+16,x:x+16][take].mean())
+                    if mean>worst_tile:worst_tile=mean;worst_xy=[x,y]
+        def bounds(a):
+            yy,xx=np.nonzero(a[...,3]>8)
+            return np.array([xx.min(),yy.min(),xx.max(),yy.max()]) if len(xx) else None
+        rb,gb=bounds(ref),bounds(got)
+        bounds_delta=float(np.max(np.abs(rb-gb))) if rb is not None and gb is not None else float('inf')
+        # Baseline gaps are exempt pixel by pixel, never by any-overlap component matching.
+        # Consequently a large new hole touching one approved curl cannot be waived wholesale.
+        marks=holes(got[...,3])&~baseline&~allowed
+        row={'frame':i,'time':times[i],'mean':float(d[compare].mean()),'p99':float(np.percentile(d[compare],99)), 'extra_hole_pixels':int(marks.sum()),'excluded_area':fraction,'worst_tile':worst_tile,'worst_tile_xy':worst_xy,'bounds_delta':bounds_delta}
+        if debug:
+            dbg=image(debug/f['file'])
+            if dbg.shape!=ref.shape:raise ValueError('debug capture dimensions differ')
+            pink=(dbg[...,0]>200)&(dbg[...,1]<60)&(dbg[...,2]>200)&(dbg[...,3]>128)&~allowed
+            row['visible_fill_pixels']=int(pink.sum())
+        row['pass']=(row['mean']<=cfg.get('maxMean',2) and row['p99']<=cfg.get('maxP99',12) and worst_tile<=cfg.get('maxTileMean',6) and bounds_delta<=cfg.get('maxBoundsDelta',2)) if cfg['mode']=='rest' else row['extra_hole_pixels']<=cfg.get('maxHolePixels',20)
+        row['pass'] &= row.get('visible_fill_pixels',0)==0
+        rows.append(row)
+    share=len(excluded_frames)/len(times)
+    if share>cfg.get('maxExcludedFrames',.1):raise ValueError(f'exceptions affect {share:.1%} of frames, over the declared budget')
+    return {'pass':all(r['pass'] for r in rows),'inspected':len(rows),'expected':len(times),'excluded_frame_fraction':share,'reference_sha256':sha(base/cfg['reference']),'config':cfg,'frames':rows}
+
+
+def main():
+    ap=argparse.ArgumentParser(description=__doc__,formatter_class=argparse.RawDescriptionHelpFormatter);ap.add_argument('config',type=Path);ap.add_argument('report',type=Path);a=ap.parse_args()
+    try:res=run(json.loads(a.config.read_text()),a.config.parent)
+    except Exception as e:res={'pass':False,'error':str(e)}
+    a.report.write_text(json.dumps(res,indent=2));print(json.dumps({k:v for k,v in res.items() if k!='frames'}));raise SystemExit(0 if res['pass'] else 1)
+
+if __name__=='__main__':main()

package/skills/golem-symbol-cutting/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: golem-symbol-cutting
+description: Prepare animation-ready raster parts and atlases for Golem. Preserve approved art with contour cuts and generated hidden surfaces, generate complete parts when requested, or reuse supplied layers and atlases. Include expression swaps, registered assembly and joint coverage checks. Use golem-symbol-animation for subsequent rigging and animation in Golem.
+---
+
+# Golem symbol cutting
+
+Design the artwork for the intended performance: actions and extreme poses → motion controls → complete painted parts → registered assembly. Choose extraction, hidden-surface generation, or complete-part generation to preserve the approved appearance and cover the required motion. A logical body part may use several images; several painted features may stay in one image when they move together.
+
+## Establish the animation brief
+
+Inspect the source art, assembled reference, existing animation sheets, layers, atlas metadata and skeleton data that are actually available. Preserve originals and keep preparation files in an authoring workspace such as `art/symbol-work/<id>/`, outside the delivered rig directory. Read applicable workspace instructions. A delivered rig folder contains only `rig.json` and one `atlas.png` for all of that symbol's parts and animations; preparation layers, manifests, prompts and QA stay outside it.
+
+Reuse the user's existing brief. Establish actions, emotions, transitions, loops, display size, motion range and permitted artwork changes. If an unanswered question would change the required artwork, ask it while continuing independent inspection. If the user delegates creative direction, propose and use a clearly stated working brief. Do not require approval again for decisions already authorized.
+
+For each action, describe setup → anticipation → main action → secondary motion → exit pose/transition, as applicable. Mark maximum joint rotations, facial changes, occlusion changes and newly exposed surfaces. Names such as `land`, `idle` and `win` are examples, not a mandatory animation set. An atlas alone does not establish the original choreography or FX frame order.
+
+## Plan the construction
+
+For new characters, major bends/turns, or Spine/Rive references, read [references/spine-rive-construction.md](references/spine-rive-construction.md). It connects source mechanisms to cuts, joint backing, topology and registered variants; runtime playback does not reveal all authoring geometry.
+
+Read [references/cutting-workflow.md](references/cutting-workflow.md) for cuts, overlap, facial states and the handoff contract. Read [references/h1-example.md](references/h1-example.md) when using the H1 teaching example; do not transfer its anatomy or assumed actions to unrelated characters.
+
+Make an action-to-parts table: action → changing feature → control method → required images. Choose group transforms, separate rigid parts, mesh deformation or attachment swaps according to the performance. Do not separate spots, highlights and strokes solely because they are separable. For full characters, also consider planted feet, separate moving hair, clothing chains, grip swaps, props and changing front/back relationships. Pilot the hardest contact and occlusion change before scaling the method to the full cast.
+
+For facial variants, FX registration or a reported size/placement defect, read [references/registration-and-motion.md](references/registration-and-motion.md) before preparing replacements. Local expression changes normally need isolated features on a clean base, not independently regenerated complete heads. Define the semantic foreground occluder at each joint: a collar covering a neck must contain the intended collar/hood, not a rectangular chunk of torso. When generation is required, generate that actual part with its hidden continuation.
+
+Before generation or extraction, record each part's identity, reference/source, animation purpose, preparation method, orientation, placement, pivot, parent control, slot/draw order, visibility states and overlap requirements. Distinguish measured facts, working assumptions and missing artwork. Use this plan to produce Golem's `layers/layers.json` import sidecar; keep generation/extraction provenance separate from document placement.
+
+## Prepare the artwork
+
+For adjustable facial expressions, read [facial-layers.md](references/facial-layers.md) before separating eyes or mouth. It covers measured eyelids, matching skin backing, transparent holes and coordinate transforms.
+
+Choose the workflow supported by the inputs:
+
+- **Layers available:** preserve source registration and usable hidden artwork; extend only surfaces required by the planned movement.
+- **Atlas available:** use textual `.atlas` metadata for region names, bounds, rotation and trim offsets, and skeleton data for assembly and animation. Without these, reconstruct manually against the reference and state uncertainties. Packing position does not specify draw order or chronology.
+- **Approved flat art / likeness must match:** use the hybrid workflow in [references/hybrid-workflow.md](references/hybrid-workflow.md). Assign visible source pixels by semantic contours, generate hidden continuations, and regenerate a complete prop only when its exposed shape needs it. Hybrid is a first-class deliverable, not a degraded generation mode. Preserve source registration and audit every departure from approved pixels.
+- **Explicitly requested fully generated atlas or permitted redesign:** generate complete isolated parts and backing using [references/generation-workflow.md](references/generation-workflow.md). Do not silently substitute source cuts for that request.
+- **Extraction only / strict pixel preservation:** isolate visible pixels deterministically. Where the requested motion exposes absent surfaces, identify that conflict; do not invent recovered pixels or silently change the artwork.
+
+For a whole-symbol transform with no changing occlusion, do not create unnecessary parts or regenerate artwork solely to satisfy a cutting workflow. Preserve the user's requested preparation method.
+
+Measure reference and generated/source image dimensions separately. Inspect transparency on checker, light and dark backgrounds. Record crop rectangles in the actual image being cropped, accounting for resized inspection displays; a generated image need not retain the reference's framing or scale. Preserve black outlines and small disconnected alpha components such as fangs, eyelid strokes and sparks unless visual evidence justifies local cleanup.
+
+For ink-aware partition, repair guides, landmark fitting, background masks, tone/edge cleanup and registered hybrid assembly, use `scripts/hybrid_parts.py --help` and the hybrid reference. It requires Pillow and numpy. It preserves small islands and has no character-specific canvas constants.
+
+For rectangular extraction from a prepared atlas, use the standalone `scripts/atlas_parts.py` (Python and Pillow). Run `--help`. Its manifest is a JSON list of objects such as `{"id":"head_base","rect":[x,y,width,height]}`. Without a manifest it only creates an inspection image. It preserves decoded RGBA pixel values; it does not rotate, mask, remove neighbors, infer part identities or restore hidden artwork.
+
+```sh
+python3 <skill-dir>/scripts/atlas_parts.py <atlas.png> <output-dir> --manifest <crops.json>
+```
+
+Undo packing rotations separately; quarter turns can use lossless pixel transposes. Document the direction and operation. Do not mirror asymmetric paired parts by default. Preserve registration when trimming or resizing. Transparent padding cannot replace painted overlap beneath a joint.
+
+Use an available image-generation skill/tool for regeneration; trimming, registration, packing and assembly of the generated parts should remain deterministic. Verify generated artwork against the reference style, outline, color, identity and pose. Do not claim unseen surfaces were recovered exactly from a flat source or silently substitute a source-cut/hybrid package for a fully generated one. If generation is unavailable, report that limitation and complete independent planning rather than claim regeneration succeeded.
+
+## Verify and hand off
+
+Reassemble setup using recorded placements and draw order. Compare silhouette, expression, scale and contours with the reference. A matching setup alone does not prove joint coverage. Test the planned extremes and intermediate movement: joint bends, head tilt, open mouth, closed eyes and expression switches, as required by the brief. Inspect joint closeups in motion as well as the symbol at cell size. Static pose mockups can validate artwork coverage; they do not establish native rig or runtime correctness, and a clean numerical checker does not prove textures have no seams.
+
+Use the numerical gates in [quantitative-qa.md](../golem-symbol-animation/references/quantitative-qa.md) when claiming setup equivalence or motion coverage; preserve current render hashes, complete sample counts and bounded exceptions.
+
+Fix gaps, doubled contours, cut-off tips, neighboring fragments and registration jumps. Check FX frames for complete disconnected fragments and stable alignment. If the planned motion exposes missing artwork, repair that part or revise the motion brief explicitly; do not hide the limitation behind a successful setup render.
+
+For a cutting task, keep RGBA layers, a ready-to-import `layers/layers.json` sidecar, brief, provenance and QA in the external authoring workspace. Deliver the verified setup as `rig.json` plus one `atlas.png` using the packing contract in [references/golem-handoff.md](references/golem-handoff.md). The sidecar and loose layers are preparation inputs, not extra files in the final rig folder. For a planning-only task, deliver the plan and label unperformed preparation, packing and QA accurately. Report concrete unresolved items.
+
+When Golem animation is requested, pass the existing brief and art package to [golem-symbol-animation](../golem-symbol-animation/SKILL.md). Preserve IDs, coordinate conventions, registration and limitations; do not restart creative planning without a reason. If the sibling is unavailable, deliver the same handoff contract without claiming animation is complete.
+
+Read [references/golem-handoff.md](references/golem-handoff.md) before exporting the layers or verifying their import. Golem is the target tool and its current schemas define the deliverable. The workflow uses bones, slots, attachments and meshes similar to Spine, but validation and delivery happen in Golem.

package/skills/golem-symbol-cutting/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Golem Symbol Cutting"
+  short_description: "Generate and prepare animation-ready parts for Golem"
+  default_prompt: "Use $golem-symbol-cutting to prepare registered animation-ready parts for Golem, preserving approved visible art with contour cuts and generated hidden surfaces, or generating complete parts when requested."

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

@@ -0,0 +1,92 @@
+# Cutting decisions and animation handoff
+
+## Map actions to artwork
+
+| Planned action | Construction | Required artwork |
+|---|---|---|
+| Whole symbol bounces | Group/root transform | No extra cuts solely for this movement |
+| Head tilts against torso | Head control with neck pivot | Neck and head base continuing under the overlap |
+| Ear or horn settles after an impact | Rigid part or a small mesh | Complete contour, hidden base and coverage at maximum deflection |
+| Blink | Eyelid control or closed-eye swap with coordinated eye visibility | Closed state and a clean backing surface; no remaining white hairline |
+| Gaze shifts | Separate pupil only if required | Complete eye white and a way to contain the pupil within the eye |
+| Brow changes expression | Separate brow, deformation or replacement | Skin restored beneath the original brow |
+| Mouth opens widely | Local mouth swap plus jaw/face deformation when articulation is required | Clean base, mouth cavity, lips and teeth/tongue; continuous lower face for jaw travel |
+| Elbow or knee bends | Segments or a weighted mesh | Joint coverage in extreme poses; continuous clothing at the seam |
+| Hand changes grip | Registered attachment variants | Hand states and prop pieces drawn in front of/behind fingers as needed |
+| Hair, cloth or tail bends | Mesh/bone chain or several parts | Enough painted surface to deform; one image per bone is not required |
+| Flash or smoke plays | Separate FX control and, where appropriate, frame swaps | Every fragment of each frame and a stable registration point |
+
+Apply only rows supported by the brief. Large out-of-plane turns may require new views; stretching a single view does not reveal correctly drawn hidden anatomy. Split only for independent movement, deformation, replacement or changing occlusion.
+
+## Overlap and outlines
+
+Put seams where another part covers them throughout the intended movement. Preserve visible external outlines without inventing a second outline inside a covered joint. Extending alpha alone does not reconstruct the color and texture of hidden surfaces.
+
+Choose painted overlap from the pivot and motion range at the working scale. Avoid a universal pixel margin. Treat transparent space for sampling/meshing/packing separately from painted continuation needed for articulation.
+
+After extracting a moving facial feature from flat art, remove its duplicate from the base and restore the underlying surface where needed. A rectangular skin patch can appear pasted on when rotated; use an appropriate mask or replace a larger registered facial region. Alternate full-face images should not be visible together unless the transition deliberately requires a compositing treatment.
+
+## Handoff contract
+
+Store this preparation package outside the delivered rig directory, for example
+in `art/symbol-work/<id>/`. Only `rig.json` and one shared `atlas.png` belong in
+the final rig folder. See [golem-handoff.md](golem-handoff.md) for packing.
+
+A practical package contains:
+
+- `animation-plan.md`: actions, phases, expressions, ranges, loop/transition behavior, and assumptions.
+- `parts-plan.json`: source provenance, image registration and control/slot plan when these are not already recorded elsewhere.
+- When generation is used: full generated references and exact prompts, with generated/source/hybrid provenance per final part.
+- `layers/layers.json`: the Golem import sidecar generated from that plan, with document placement, joints and attachment variants.
+- `crops.json`: only `id` and `rect` entries when using the crop helper.
+- `layers/`: final RGBA PNGs, with orientation and trim documented.
+- `qa/`: contact sheet, setup comparison and tested extreme poses.
+
+Use the project's existing equivalent files when available. Do not create empty deliverables. Keep source-atlas coordinates separate from assembled-document coordinates.
+
+Define canvas dimensions, units, axis directions, angle sign, side naming, and transformation order once. For a simple pixel-space plan, use X right, Y down and viewer-left/right. Preserve another established convention when supplied and document the conversion.
+
+The following record is illustrative, not measured H1 data or an importer schema. It assumes no setup rotation or scale; the image pivot lands at document `[138,283]`:
+
+```json
+{
+  "id": "ear_viewer_left",
+  "file": "layers/ear_viewer_left.png",
+  "source": "atlas.png",
+  "extraction": {"method": "crop", "rect": [100, 200, 80, 120]},
+  "orientation": {"unpackRotationDegCW": 0, "mirror": false},
+  "placement": {"topLeft": [72, 198], "pivotLocal": [66, 85]},
+  "parentControl": "head",
+  "slot": "ear_viewer_left",
+  "drawOrder": 20,
+  "setupVisible": true,
+  "usedBy": ["idle"],
+  "overlap": "The head covers the ear base throughout the tested range.",
+  "status": "example_only"
+}
+```
+
+`rect` refers to the original source PNG. `pivotLocal` refers to the final extracted image after unpacking/trimming. `topLeft` places that image in the assembly. If scale/rotation are needed, record a complete transform with a defined pivot instead of leaving the order ambiguous. In this internal convention, draw-order numbers increase from back to front. They are separate from bone hierarchy and atlas region positions.
+
+Record named slots and mutually exclusive attachment variants. One slot shows one attachment or none; features visible together require separate slots. Several images belonging to one rigid horn may share a logical control, but need separate slots if they must be visible simultaneously. Preserve their relative transforms.
+
+Different-sized expression variants must align by facial landmarks, not just bounding-box centers. Specify the default state, coordinated visibility of companion parts and the registration of every variant. Do not assume a separated eye image includes a separately controllable pupil.
+
+For independent facial generation or repeated size/placement corrections, apply
+[registration-and-motion.md](registration-and-motion.md). Verify each state in
+the composed rig; copying the neutral mouth's scale to every generated variant
+does not establish that all mouths match the reference.
+
+Before delivery, translate this authoring plan into Golem's `layers/layers.json` as described in [golem-handoff.md](golem-handoff.md). The animation skill should consume the prepared sidecar rather than repeat this conversion. Update the plan and sidecar together when placement changes. Pass existing decisions forward and revise only parts invalidated by a changed action or failed pose test.
+
+## Meaningful QA
+
+Use setup overlays/differences and visual comparison. A small aggregate pixel error does not excuse a wrong fang or expression. If the assembled reference has another resolution, record the chosen scale; atlas page dimensions do not define character scale.
+
+Test silhouette, joint coverage, outline continuity, eye/mouth placement, draw order and duplicate features in maximum-action poses. Identify mockups as mockups. Check both sides of attachment switches; for continuous movement inspect intermediate poses too, since coverage can fail between endpoints.
+
+Inspect closeups of the joints that actually change occlusion, together with native motion/cell-size playback when available. Numerical checks establish schema, references and sampled geometry; they do not detect a painted seam or prove hidden skin/fabric coverage. Describe visual QA separately and limit conclusions to the inspected movement range.
+
+When making pixel-equality claims for an extraction workflow, compare all channels explicitly and distinguish visible differences from hidden RGB at alpha zero. A difference image's alpha bounding box alone can miss RGB changes when alpha is unchanged. For regenerated artwork, assess style, landmarks and assembly rather than treating original-pixel equality as the acceptance criterion.
+
+Connected-component detection finds alpha islands, not semantic parts or FX frames. A flash can contain dozens of islands. Group fragments by the actual frame, preserve offsets or a shared canvas, and verify alignment in playback. Without timing/sequence evidence, label any proposed FX order as authored rather than recovered.

package/skills/golem-symbol-cutting/references/facial-layers.md

@@ -0,0 +1,44 @@
+# Preparing a face for adjustable expressions
+
+Preserve the approved face/eye pixels where visible. Record each feature's source region,
+measured eye corners and neutral placement; generated hidden eyelids, mouth interiors and
+backing are new artwork, not recovered source pixels. Do not reuse another character's
+landmarks or assume asymmetric eyes are mirrored.
+
+Track source pixels → crop-local pixels → logical document placement → atlas texels →
+normalized UVs separately. Cropping changes registration; resizing changes measured
+landmarks. Keep those transforms in the preparation recipe. Atlas placement is not a
+facial landmark. Current Golem does not support replacing an atlas with a larger image
+without updating its sampling metadata; do not promise geometry-preserving HD replacement.
+
+For a moving mouth, keep surrounding skin on a matching face base. The movable layer
+contains the lip line or mouth interior, not a rectangular patch of skin. Verify that
+base + extracted feature reconstruct the original neighborhood. For antialiased lines,
+color thresholding alone can leave a halo: account for compositing against the measured
+base, and bound unstable low-alpha recovery. This is preparation guidance, not an
+automatic extraction capability of the current Golem tools.
+
+For small expressions without newly exposed surfaces, a continuous local face mesh can
+retain lips, ink and skin in one texture. Pin its perimeter and taper the deformation
+inside it; this differs from moving a rigid rectangle of painted skin. Separate features
+and prepare backing when the motion needs independent overlap or an opening mouth.
+
+Adjacent mesh patches can show antialiasing cracks despite coincident boundary vertices.
+A narrow source-derived underlap inside an undeformed boundary band can cover them.
+Keep that underlap out of soft hair/chin silhouettes: duplicating their partial alpha
+darkens the contour. Measure the source's interior alpha first; compressed art can have
+252–254 alpha in apparently solid skin. Check both added gaps in motion and neutral
+composites after any coverage correction; do not globally force the artwork opaque.
+
+Prepare complete closed-eye backing and an uninterrupted eyelid/lash where the open
+source is occluded by hair. Measure open and closed endpoints on each side. Pass the
+measurements and required intermediate states to rigging. Verify both opening and closing,
+including near-open states, a wink, gaze and head motion together.
+
+Distinguish genuinely transparent holes (between hair strands, accessory cutouts) from
+hidden regions needing new paint. A repair must not fill the former. Keep repair masks
+and source provenance separate, and inspect alpha compositing on light and dark backgrounds.
+
+The handoff records roles, side convention, coordinate transforms, landmarks, backing,
+supported ranges and unresolved coverage. Use the animation skill's facial-controls
+reference for optional parameter grids and combined-pose render checks.

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

@@ -0,0 +1,109 @@
+# Preparing parts through generation
+
+Use for complete parts and hidden-surface repairs where generation is chosen, or when
+the user explicitly requests a generated atlas. For approved flat art whose visible
+appearance must remain fixed, start with [hybrid-workflow.md](hybrid-workflow.md). A visible-pixel cut can match
+setup perfectly while leaving a missing neck, detached wrist or duplicate
+contour as soon as the rig moves. Local patches only under the setup silhouette
+may still leave those joints uncovered.
+
+## Generate the required painted surfaces
+
+Use the reference to preserve identity, pose, proportions, ink weight, palette
+and lighting. Specify the isolated part, its hidden continuation, intended
+joint/occlusion, and a genuinely transparent background. Include enough margin
+to retain extremities, but distinguish that margin from painted overlap.
+
+Generate each independently authored asset through the available image tool.
+Keep the full generated outputs and exact prompts. In a fully generated package,
+final painted pixels come from generated artwork; the original supplies the
+reference, not crop pixels. In a requested hybrid package, record which parts
+remain original and which surfaces were regenerated.
+
+Choose connected surfaces around the performance, for example:
+
+- A tilting bust may need a head with a continuous complete neck, plus a clean
+  torso whose collar covers the neck base. Do not stop the head at the chin.
+- A hand raising a held carton may need one continuous grip/carton/wrist/sleeve
+  image and coat backing underneath. Do not stop the arm at the wrist. Keep the
+  grip rigid when the brief does not change it; bend only the intended fabric.
+- A blink or smirk normally uses isolated eyelid/mouth artwork on a clean accepted
+  head base. Request only the required feature and backing; exclude unrelated
+  cheek, nose or beard pixels. A full-head edit may serve as a generation reference,
+  but use full-head runtime swaps only when the performance needs a whole-head
+  redraw. Verify every state's landmarks with `registration-and-motion.md`.
+
+These examples are construction choices, not a mandatory anatomy or part count.
+For each actual joint, require real skin/fabric and outline continuation through
+the planned range. A straight ink stroke across a hidden part end can become a
+visible seam; do not add one just to make the part look closed on a contact sheet.
+
+## Register and plan occlusion
+
+Measure generated dimensions and fit parts using landmarks and joint positions.
+Do not reuse reference crop coordinates or trust equal canvas sizes/bounding
+boxes as proof of alignment. Check that independent generation has not moved a
+collar, enlarged a hand or changed the head angle before rigging around it.
+
+Plan front/back relations explicitly. A head may need to draw in front of the
+coat while its neck draws behind the collar. When one continuous generated
+painting spans both relations, derive semantic front/back regions from it with
+painted overlap and coordinated controls. Do not pack a rectangular chunk of
+neighboring face art as a supposedly isolated neck. Packing and bone hierarchy
+do not establish the right draw order.
+
+Plan framing before requesting long hidden extensions. A sleeve base can anchor
+to the torso while its wrist moves, using a mesh where fabric bending is part of
+the brief. Meshes cannot supply missing pixels. Do not silently crush a long
+forearm into a thin strip to fit the cell: inspect folds, proportions and base
+contours, and regenerate or revise placement if fitting introduces artifacts.
+Determine overlap from the actual pivot/motion; H2's pixel margins, weights and
+timings are not general presets.
+
+## Verify the generated assembly
+
+Use a temporary Golem rig to test joint rotations and translations through
+extremes and intervening frames, following `golem-handoff.md`. Inspect neck/collar,
+wrist/cuff and sleeve/body joins on checker/light/dark backgrounds and in native
+playback where available. Look for gaps, doubled outlines, exposed crop edges,
+flattened fabric, neighboring fragments and attachment jumps. Fix the artwork,
+draw order, pivot or weights responsible; do not reduce the action silently.
+
+Compare the regenerated assembly visually with the reference and disclose
+material pose/identity changes. Pixel identity with the original is not the goal
+of regeneration. Save the native closeups/phase checks that support the accepted
+motion range, not only a contact sheet or checker success message.
+
+## Repair prompts and extraction
+
+Generation may recreate an occluder that was removed, add an opaque page, shift palette,
+leave a pale fringe, or alter scale. These are possible outcomes to inspect, not guaranteed
+model behaviours. Equal canvas dimensions do not prove registration. Use measured landmarks.
+
+Hidden-surface prompt template:
+
+> Complete only the exposed continuation of [part/material] in the marked region.
+> The [removed sleeve/hand/prop] has deliberately been removed; do not draw it again.
+> Continue the host part's existing contour, lighting and ink weight through the hidden area.
+> Keep the surrounding reference as a registration guide. Small differences outside the
+> repair are acceptable: the final assembly will retain the approved original pixels there.
+> Return the complete repaired part on a transparent background, with no guide colour.
+
+Complete-prop template:
+
+> Paint the whole [prop] as one isolated object, including [occluded edge/loop/handle].
+> Match the reference landmarks [list], proportions, ink thickness and palette.
+> Keep [rigid housing] rigid; supply [flexible strap] as a separate surface if it moves independently.
+> No hand, sleeve, body or cast shadow from neighbouring parts; transparent background.
+
+These templates describe the deliverable, not a way around tool restrictions. Follow the
+available generator's instructions and inspect the actual result. Do not attribute a failed
+save to one phrase in a prompt without reproducible tool evidence.
+
+For a hybrid repair, use this order: fit to unchanged landmarks → remove background only
+inside a reviewed background mask → match tone from comparable opaque host material →
+feather into the host part's own colour → repair a pale fringe only inside a reviewed ink mask.
+Preserve whites of eyes and enclosed highlights. Do not globally remove light pixels or
+paint every soft edge black. `hybrid_parts.py extract` performs these deterministic steps;
+its fit residual and remaining guide-magenta checks fail explicitly. Keep full generations,
+landmarks, masks, exact prompts and fit reports outside the delivered rig folder.

package/skills/golem-symbol-cutting/references/golem-handoff.md

@@ -0,0 +1,62 @@
+# Delivering cut artwork to Golem
+
+Golem is the authoring and validation target. Locate the checkout through `package.json`, `src/rig-api.ts` and `src/rig-import-layers.ts`, or use the installed `@energy8platform/golem/tools` registry in a game. Verify current schemas before invoking tools; the installed editor CLI does not necessarily expose the checkout's rig CLI commands. External animation formats do not define this contract.
+
+## Art package
+
+Keep the animation brief, RGBA PNGs and a `layers/layers.json` sidecar ready for `rig_import_layers` in the external authoring workspace, not the delivered rig folder. Keep generated originals and exact prompts, source rectangles, masks, unpacking operations and reconstruction notes there as applicable. The animation skill consumes these decisions directly.
+
+For ordinary unrotated cutouts, use the final image dimensions in `bbox`, its top-left in Golem document pixels, and the desired joint in the same document space. Golem uses X right, Y down and clockwise-positive degrees. Thus a crop at `[x,y]` with a local pivot `[px,py]` has `joint: [x+px,y+py]`.
+
+This illustrative sidecar assumes two 280 × 280 PNGs registered to the same face landmarks:
+
+```json
+[
+  {
+    "id": "head",
+    "file": "head.png",
+    "parent": "root",
+    "z": 10,
+    "bbox": [170, 140, 280, 280],
+    "joint": [310, 400]
+  },
+  {
+    "id": "smile",
+    "file": "smile.png",
+    "bone": "head",
+    "slot": "head",
+    "swap": true,
+    "z": 10,
+    "bbox": [170, 140, 280, 280],
+    "joint": [310, 400]
+  }
+]
+```
+
+`file` is relative to the layers directory. `bbox` is `[x,y,width,height]` in the assembled document, never a source-atlas rectangle. IDs and references must be unique/valid for their object types. Use explicit `parent`, `bone`, `slot` and `z` when inference would be ambiguous. A semantic label in a planning document does not create a bone: every referenced control must exist or be created during import/setup.
+
+A normal layer creates an asset, bone, slot and attachment. `bone` attaches artwork to an existing control without creating another bone. `swap: true` adds an attachment without selecting it: a new slot starts empty; an existing slot keeps its current selection. Choose the setup attachment explicitly afterward. One slot shows one attachment or none; simultaneously visible parts need separate slots even if they move with the same bone. Larger `z` draws in front unless animated draw order overrides it.
+
+The current checkout imports document-space `bbox` and `joint` through the full evaluated
+host matrix, including rotation, scale, reflection and shear. `bbox` width/height specify the
+drawn document size; they may differ from PNG dimensions. A sheared local placement becomes
+a four-vertex mesh so the image remains exact in document space. Existing bones and swap
+slots keep their host. On older installations with the translation-only importer, import
+under neutral bones and apply the complete placement afterward; feature-check the installation.
+Bone angles follow their `inherit` mode: under a rotated parent,
+`noRotationOrReflection` removes inherited rotation, so its authored angle cannot be
+computed by always subtracting the parent's angle. Verify the world matrix with `rig_get_pose`.
+
+For detailed tools, visibility and preview mechanics, read [golem-authoring.md](../../golem-symbol-animation/references/golem-authoring.md). If the sibling reference is unavailable, inspect the current Golem tool schemas and importer directly.
+
+## Verify the handoff
+
+For a completed cutting task, validate the sidecar JSON and PNG dimensions, then import into a temporary Golem setup rig when the checkout is available. Use the registry, CLI or `callTool`; preserve the source artwork and any existing production rig. `rig_import_layers` takes `layersDir` and `relPrefix`: the latter must resolve from the rig directory to the actual image directory. The current importer falls back to filenames only when the sidecar is absent; invalid JSON fails. Older versions also fell back on parse errors. Inspect the resulting IDs, parents and slots rather than trusting invocation success alone.
+
+Render setup and compare it with the reference. Use temporary transforms or short test tracks to inspect the planned extremes, intermediate joint movement and both sides of swaps. These are art-coverage checks, not a substitute for authoring the requested animations. Save native joint closeups as well as whole-symbol views. Fix missing surfaces, seams, wrong pivots, visibility and registration before declaring the parts ready. A static image mockup can support coverage checks, but does not replace import validation when Golem is available. If import or motion coverage could not be checked, report that specific limitation.
+
+Run `rig_validate` and `rig_check` and read their reports; findings can appear in a successful tool response. In numerical QA, note that `rig_get_pose` returns slot bounds as `[minX,minY,maxX,maxY]`, unlike the import sidecar's rectangle format.
+
+For delivery, export the verified setup through `rig_export` to external staging, compare its render and install exactly `rig.json` plus one `atlas.png` in the destination. Keep the loose-layer handoff and QA outside that folder. Follow [packed-delivery.md](../../golem-symbol-animation/references/packed-delivery.md) for packing, package checks and history preservation. If the sibling is unavailable, inspect the current export schema and check that the destination contains only the pair and every asset references a valid frame in `atlas.png`.
+
+Continue with `golem-symbol-animation` when performance authoring or game integration is requested; carry the verified parts and brief forward, then pack the complete animated revision. A setup-only export is not a completed animation. Keep packing separate from extraction and only claim stages actually completed.

package/skills/golem-symbol-cutting/references/h1-example.md

@@ -0,0 +1,46 @@
+# H1: reference artwork and atlas analysis
+
+The teaching inputs are bundled with this skill:
+
+- [Assembled reference](../assets/h1/h1.png)
+- [Source atlas](../assets/h1/h1.atlas.png)
+
+Use these bundled files only for the H1 teaching example. In another task, use the user's supplied art and do not transfer H1's appearance, anatomy or atlas layout to a different character.
+
+![H1 assembled reference](../assets/h1/h1.png)
+
+The atlas is intentionally shown at a reduced display size in Markdown. Measurements and crop coordinates must use the original bundled 2048 × 2048 file rather than the rendered preview.
+
+![H1 source atlas](../assets/h1/h1.atlas.png)
+
+## Observed facts
+
+- `h1.png` is a 512 × 512 RGBA PNG showing an assembled red character bust with horns, ears, eyes and a smirk.
+- `h1.atlas.png` is a 2048 × 2048 RGBA PNG containing irregularly packed artwork, not a uniform frame grid.
+- Checker inspection reveals a transparent opening inside the smiling face variant's mouth. It needs correctly registered cavity artwork behind it if the intended mouth is opaque.
+- Visible candidates include face bases, eyes, ears, horns or horn fragments, a nose, mouth/teeth regions, neck/clothing, and many flash/smoke shapes. Narrow dark strokes are easy to miss on black.
+- Facial marks remain painted on the large face images. Do not infer that every facial feature can move independently without further preparation.
+- Only the two PNGs were supplied in `h1` at validation. No textual `.atlas`, skeleton JSON or source layers establish region names, packing rotation, trim offsets, assembly transforms or animation timing.
+
+These are visual observations, not a completed semantic segmentation. Exact part rectangles, side assignments of thin strokes, horn assembly and FX chronology still need measurement and reconstruction checks. Never derive original-pixel rectangles from a resized display without accounting for scale.
+
+## Illustrative performance brief
+
+The user has not specified H1's actual actions. The following is one possible brief, not recovered author intent:
+
+| Action | Performance | Cutting implications |
+|---|---|---|
+| `land` | Arrival/contact, compression, small rebound and settling | Root, head/neck, optional ear/horn secondary controls, covered bases throughout tilt |
+| `idle` | Restrained breathing, slight head motion and a blink | Clean eye backing and coordinated open/closed states; separate ears only if they move independently |
+| `win` | Anticipation, smile/open mouth, accent and return | Compatible face/mouth variants with registered landmarks; cavity and teeth as needed; FX only if part of the chosen action |
+
+Replace this table when the brief calls for speech, surprise, attack, impact or another performance. Explosions in the atlas do not establish `hit`, `win`, disappearance or frame order. If skeleton data becomes available, use it to replace assumptions with evidence.
+
+## Lessons to carry forward
+
+1. Match atlas candidates against the assembled image before assigning final names. The horns are asymmetric; do not mirror one to fabricate the other. Test whether a logical horn comprises multiple packed pieces.
+2. Separate logical controls from images. Horn fragments that form one rigid object should retain their relative placement; skin spots can stay on the base.
+3. Inspect eye and eyelid artwork before choosing a blink. A separate eye image does not prove a separate pupil; gaze shifts may require a new cut and reconstruction of the eye white.
+4. A full-face switch must not retain incompatible old mouth artwork, move facial landmarks or expose the background through the mouth. Preserve intentional outlines around the opening.
+5. Treat each FX frame as a whole, including disconnected sparks. Confirm or explicitly author its order and registration before assigning sequential names.
+6. Distinguish analysis, measured extraction and a verified rig. This reference documents analysis only; it does not provide final crops or claim exact reconstruction of H1.