@energy8platform/golem 0.5.0 → 0.7.0

package/skills/golem-symbol-animation/references/motion-craft.md

@@ -0,0 +1,113 @@
+# Motion craft for symbols and full characters
+
+## Curves that carry motion through keys
+
+A key is not automatically a stop. Golem's legacy `ease_in_out` eases every interval separately,
+so a chain of such keys brakes to zero at every waypoint. Set `interpolation: "pchip"` on a
+numeric track for shared shape-preserving cubic tangents. This works for scalar and numeric
+array channels. Extrema and holds settle; intermediate monotonic keys keep moving. Explicit
+`step` still means a cut. Older runtimes lack this field: verify support before delivery.
+
+```json
+{"target":"bone","id":"hand_target","prop":"x","interpolation":"pchip",
+ "keys":[{"t":0,"v":120},{"t":0.3,"v":150},{"t":0.8,"v":220},{"t":1.2,"v":220}]}
+```
+
+PCHIP gives continuous velocity, not continuous acceleration. For a deliberate contact or
+rest-to-rest reach, use `ease: "minimum_jerk"`: `10u³−15u⁴+6u⁵`. Key x/y with the same normalized
+phase to follow a straight path; author a curved spatial path when the action needs it. Put
+minimum-jerk segment boundaries only at real stops, not every sampled waypoint. For longer
+custom trajectories, sample a differentiable function into explicit linear keys at a rate
+that passes acceleration/jerk measurements; do not re-ease each sample.
+
+For idle, t=0 is the approved setup pose unless the established brief says otherwise. Author
+both endpoint values and velocities across every channel. PCHIP wraps endpoint tangents only
+when a loop's keys span exactly `[0,duration]` with matching endpoint values. Inspect the
+unwrapped terminal pose too; a looping player seeks duration back to zero.
+
+## Full-body construction and planted feet
+
+Build controls in the order dictated by contacts: planted-foot targets, hips/torso, hand and
+prop contacts, then independent cloth/hair. Place IK targets under a stable world/root control
+rather than a body control that sways. A root translating the entire character also translates
+its child targets; use a stationary scene control when world planting must survive root motion.
+
+`rig_add_ik_chain` makes a one/two-bone limb by default. Supply `bones` in parent-to-tip order
+for a longer chain; `rig_set_ik` also accepts long chains. One/two-bone solving is analytical;
+three or more bones use iterative CCD with `iterations` and `tolerance`. Check reach error,
+bend direction, extreme poses and playback; an unreachable target cannot be fixed by more
+iterations. For tail/scarf shape control, a path constraint can be easier than tip-only IK.
+The long-chain solver currently rotates the chain; its stretch/compress/softness flags are
+for the analytic short-chain solver. Do not assume stretch on a long chain without checking.
+
+Make independently moving hair a separate attachment and control chain. Curl pixels inside
+an otherwise rigid head mesh often receive head-only weights and remain frozen. Cloak hems,
+scarf ends and hair can share the torso's broad motion while adding local lag. Specify which
+bones must show local secondary motion in `rig_check.secondaryBones`.
+
+A single 2D limb mesh has a limited useful bend range. Around 40–60 degrees is a practical
+inspection trigger, not an engine limit: topology, silhouette and artwork determine the
+actual boundary. If a fold or shortened limb appears, split upper/lower segments with real
+joint backing, use an alternate drawn pose, or change topology and weights. Do not silently
+shrink the requested action or accept a fold because most triangles remain valid.
+
+Use `rig_gradient_weights` for an ordered chain, `rig_smooth_weights` for adjacency smoothing
+with `locked` vertex indices, and `rig_pin_weights` for rigid selections or a document-space
+rectangle. Preserve setup geometry. Review any dropped deform tracks when changing influence
+layout. The editor's weights mode already provides a heat map and brush; preview `weightBone`
+exports the same kind of inspection for a chosen bone.
+
+Clipping uses `rig_set_slot {clip: closedPathAttachmentId}`. Create a closed path with
+`rig_set_path_attachment` on a suitable control; its posed/skinned/deformed geometry masks the
+slot's active image. Several slots can share a mask. A mask can contain a pupil or trim hair
+at a collar; it cannot invent missing painted surfaces. Hidden path slots can still define
+masks, since the explicit mask reference is independent of path-slot visibility.
+
+## Contact, grip swaps and constraint order
+
+The runtime solves constraints in ascending `order`; equal orders use IK → transform → path
+array order. A follower must read a hand after that hand's IK has run. `rig_check` reports
+`constraint_order`; `rig_order_constraints` computes a stable dependency order and refuses
+cycles. Dependencies include target ancestors, constrained parents and skinned path weights.
+Inspect deliberately competing constraints instead of dismissing warnings globally.
+
+For a handoff:
+
+1. Animate the receiving hand to contact while the prop follows its current owner.
+2. At the actual contact time, call `rig_attach_to_bone {animation,bone,target,t}`. It evaluates
+   the current pose, computes offsets in the new target frame, disables previous generated
+   followers and keys the new transform constraint after the existing solve order.
+3. Key the grip/hand attachment swap and relevant front/back ordering at that same instant.
+   Match semantic landmarks on both drawings; matching bbox centres is insufficient.
+4. Inspect before/at/after contact, then moving frames after transfer, including rotation and
+   scale. Author successive contacts in time order. For a release into free motion, fade/disable
+   the follower and bake or key the prop's world-equivalent pose before continuing.
+
+Transform offset x/y/rotation/scale/shear are keyable in the current checkout. Bone local angles
+must respect `inherit`: `noRotationOrReflection` suppresses the parent's rotation; subtracting
+that rotation again produces a wrong world angle. Use actual evaluated matrices.
+
+## Baked secondary motion
+
+Drive lag from speed or acceleration, not absolute driver position: a held tilted pose should
+settle rather than hold its scarf bent forever. `rig_bake_secondary` samples the evaluated
+driver rotation and integrates damped oscillators for the supplied bones, with increasing
+lag along the list. `frequency`, `damping`, `gain`, `maxAngle` and `fps` are controls to tune,
+not universal presets. It writes ordinary editable PCHIP rotation tracks. Loop simulations
+settle to a repeated state before baking, then recenter their first pose to setup.
+The driver must already close at the loop boundary. Followers cannot include the driver or
+its ancestors. Recentering is amplitude-limited as a whole, so it cannot exceed `maxAngle`.
+
+Test that the driver actually changes and each intended follower has visible local amplitude.
+For translation-led motion use `driverProp: "x"` or `"y"`; the default `"rotation"` uses angular velocity. Tune gain for the driver’s units (pixels or degrees). Inspect loop velocity and acceleration, and
+confirm that local secondary motion still reads at display size. Baked keys require no runtime
+spring state, so engine entry/exit is reproducible.
+
+## Pilot and semantic review
+
+For a new full character, first author one representative idle and the hardest contact/gesture.
+Check foot sliding, hem-over-leg order, face visibility, independent hair, grip registration,
+prop rigidity, and flash timing (e.g. a camera flash only while the raised camera points forward).
+Use a brief-specific numerical rule for each claim; a generic geometry check cannot infer a
+camera's narrative readiness. Present the pilot for user review when visual direction or the
+brief requires it, then preserve accepted choices while scaling to the remaining actions/cast.

package/skills/golem-symbol-animation/references/packed-delivery.md

@@ -0,0 +1,88 @@
+# One rig, one atlas, a clean directory
+
+Every delivered symbol revision uses one atlas shared by all its actions, swaps,
+mesh textures and FX. It remains an editable Golem rig. Do not create a second
+runtime/packed rig beneath it or leave loose layers beside it.
+
+```text
+public/assets/rigs/<id>/
+  rig.json
+  atlas.png
+
+art/symbol-work/<id>/          # outside the delivered rig directory
+  layers/                    # import sidecar and prepared parts
+  work/                      # staging rig, temporary assets and editor history
+  qa/                        # comparisons, playback and reports
+  ...                        # source art, prompts, plans and build scripts as needed
+```
+
+Paths are examples. Keep the user's chosen destination and equivalent authoring
+workspace. One atlas means one per delivered symbol rig, not one per action and
+not a requirement to combine unrelated symbols into a game-wide texture.
+
+## Build, pack, verify, then replace
+
+1. Create or continue a working copy outside the destination. Use the current rig
+   as the source of accepted changes; an older build script must not overwrite
+   later editor edits. Inspect diffs/history before a rebuild. Put generated
+   layers, scripts, logs and `.rig-history` beside this working copy only.
+2. Run authoring and visual checks on that copy. Export through `rig_export` to a
+   fresh staging directory outside the delivered rig folder. Inspect the schema:
+   `outDir` is absolute or relative to the source rig directory. Use sufficient
+   padding and a supported `maxSize`. If packing fails, inspect oversized parts,
+   redundant full-head variants and padding; fit/trim with preserved registration
+   or choose a supported larger page. Do not silently produce multiple atlases or
+   downscale artwork until it changes the accepted appearance.
+3. Verify the exported pair with `rig_validate`, `rig_check`, and
+   `python3 <skill-dir>/scripts/check_package.py <staging-dir>`. This helper uses
+   only Python's standard library. All asset `src` values
+   must reference the same `atlas.png`; frame rectangles must fit the atlas. This
+   directory check supplements Golem validation, it does not replace it.
+4. Render the working and exported rigs at identical times/scale/background:
+   setup, all expressions, active FX, deformation extremes and transitions. Inspect
+   meaningful differences. Test actual playback at cell size. For game delivery,
+   exercise the adapter and lifecycle using this exported rig.
+5. Install the verified `rig.json` and `atlas.png` together at the canonical path.
+   Preserve the previous pair outside the rig folder until replacement is checked.
+   Update game/editor references that used a former nested `packed/rig.json`. Avoid
+   exposing a half-updated pair to a live reader; use the project's staging/swap
+   mechanism or pause the task-owned reader during the two-file replacement.
+6. Run the package check on the destination and load that exact path again. Link
+   this pair as the final rig and keep previews in the external QA workspace.
+
+The current exporter can repack assets with `frame` data, so a packed rig is a
+usable starting point for later edits. Verify version behavior for rotated or
+trimmed imported regions; normalize them in staging when the exporter does not
+support their metadata. Never hand-edit frame coordinates to pretend packing ran.
+
+## Make verification apply to the installed revision
+
+Record hashes of the source rig and its textures before staging edits. Before
+replacement, compare the live package to that source snapshot; if it changed,
+preserve and reconcile the new edits instead of installing an older build over it.
+Bind visual review, checker findings and packed-equivalence results to the exact
+rig/texture hashes tested. A timestamped narrative report alone cannot establish
+that the current package was reviewed.
+
+Build/install scripts must inspect validation results and checker findings, not
+only tool invocation success. Fail on validation errors and unreviewed warnings.
+If a warning is deliberately accepted, record the exact finding, concrete reason
+and visual evidence for that revision; do not blanket-ignore its category. A
+truncated checker summary is not a complete finding list. Keep the checker active
+and reject newly introduced findings. Require this verification before install.
+
+## History and existing clutter
+
+Golem mutations currently write `.rig-history` beside the edited rig. Mutate a
+staging copy to keep the delivery folder clean. A read-only preview does not need
+a history directory. If a user edits the delivered rig in the editor, retain the
+new rig and preserve the resulting history in the external authoring workspace
+when finalizing that revision; keep a complete working package so undo remains
+usable. Do not disable Golem history or discard manual changes.
+
+For an existing cluttered rig folder, identify referenced textures and inspect
+game/editor paths first. Move task-owned layers, scripts, QA, duplicate exports
+and history to the external workspace only after the new self-contained pair is
+verified and consumers use its canonical path. Do not recursively delete unknown
+files. If ownership is unclear, report the specific unresolved files rather than
+claiming the clean-directory check passed.

package/skills/golem-symbol-animation/references/quantitative-qa.md

@@ -0,0 +1,106 @@
+# Reproducible gates without false passes
+
+Visual playback and measurements answer different questions. For a new action, record its
+expected poses, semantic rules, minimum visible motion, allowed departures and required
+animation IDs before tuning thresholds. A successful tool call is not a passed gate.
+
+## Capture identity and coverage
+
+Render explicit times with `rig_render_preview`, using `transparent:true` and a new `framesDir`
+for alpha QA. The directory receives `manifest.json`: the exact input document/file, textures,
+renderer, optional fill masks, sample times and output frames are hashed. Then call
+`rig_verify_render` with the rig, directory, animation and the independently expected times.
+It fails for changed inputs, changed renderer, changed frames, missing/extra frames or the wrong
+animation/time set. A stale file modification timestamp is not a reliable substitute for hashes.
+Keep capture directories outside the delivered package.
+The manifest also records scale, crop, backgrounds and diagnostic overlays. Image gates reject
+bone/weight/onion overlays, an undeclared crop/scale, missing settings or a normal capture
+passed off as a fill-debug capture. Re-capture old frames that lack these settings.
+
+For loops sample `[0,D)` at the chosen frame rate and separately inspect the unwrapped endpoint.
+Include extrema and frames immediately before/at/after attachment, grip, flash and draw-order
+changes. Explicit expected samples are the contract; never silently inspect whichever PNGs
+happen to be on disk. A matching manifest establishes provenance, not complete sampling of
+all mathematically possible motion.
+
+## Which measurements support which claims
+
+| Claim | Measurement / evidence |
+|---|---|
+| Setup matches approved art | Premultiplied/composited RGB difference on black and white, silhouette/bounds, local worst regions, face landmarks |
+| Hidden repairs remain hidden at rest | Render with `debugFillMasks` (source-file → grayscale-mask file); count visible magenta outside reviewed replacement regions |
+| No holes or seams | True alpha across all expected frames; compare against the approved art's own holes, never discard large holes |
+| Motion reads | Required bone/landmark amplitude at display size; velocity, acceleration and jerk with units and sample interval |
+| No teleports | World positions on adjacent frames and denser samples around a suspect change; isolate sharp outliers from a smooth fast swing |
+| Loop closes | Values and one-sided velocity for every numeric channel; exact attachments, visibility, colour and draw order; true terminal pose |
+| Anatomy stays sound | Landmark ratios, rigid-prop distances, planted-foot drift, mesh folds and silhouette review |
+| Face/hem order | Brief-specific `frontOf` slot pairs plus rendered overlap; do not label intended hair overlap a defect |
+| One drawing per slot | Schema plus active attachment state; simultaneous layers require distinct slots |
+| Secondary exists | Declared `secondaryBones` local motion and visible amplitude; frozen local rotations should not pass because the torso moved |
+| Flash/contact is valid | Sample actual game/animation state around the trigger and verify the required pose/visibility conditions |
+| Swaps are registered | Shared named UV landmarks via `rig_check.landmarks`, including both sides of the switch |
+| Transitions work in game | Drive the real `AnimationState`/`RigPlayer` with actual mix settings and all mapped IDs |
+
+`rig_check` adds `pass_key_stop`, `velocity_jump`, `acceleration_jump`, `loop_velocity`,
+`secondary_frozen`, `draw_order_rule` and `attachment_landmark_jump` to existing geometry
+checks. Acceleration findings are informational: PCHIP is C1, not C2. `motion_pop` looks for
+an isolated displacement spike relative to neighbouring frames; a smooth fast gesture alone
+is not evidence of a teleport. Source-atlas bboxes are provenance, not document placement:
+mark `asset.origin.bboxSpace: "source"` so `patch_offset` does not compare unrelated spaces.
+
+For image gates run `scripts/image_gates.py config.json report.json` (Pillow + numpy).
+Its `--help` gives the schema. `rest` compares RGB over black/white, worst 16-pixel tile,
+silhouette bounds and optional debug fill
+visibility; `holes` measures added enclosed gaps/partial-alpha cracks of any size. It verifies
+rig, texture, renderer and frame hashes before judging pixels. Supply a reference already
+registered at the capture's exact scale. Use current transparent captures by preference.
+Declare that scale in the gate configuration (`scale:1` by default) and `region` when explicitly
+comparing a crop. An empty art frame fails even though it has no enclosed holes.
+For an older opaque-only renderer, reconstruct alpha from the same pose over two contrasting
+backgrounds and validate that the material uses ordinary alpha compositing; additive/multiply
+content can invalidate that reconstruction.
+
+## Brief-specific motion gates
+
+`rig_run_gates` returns explicit pass/fail results with the expected and inspected sample counts.
+Use `motion` rules for minimum amplitude, maximum speed/acceleration/jerk/step and setup drift
+(planted feet); `distances` for rigid-prop proportions or contact tolerances; `conditions` to
+require a visible flash only within a valid camera pose; `requiredAnimations` for the complete
+game contract; and `transitions` to measure real AnimationState playback rather than a substitute
+lerp. Conditions include key-switch times and fail if their supposedly required effect never
+appears. Motion thresholds carry units and depend on the declared fps.
+An empty gate configuration or measurement rule without any threshold is an error. Transition
+steps include bone endpoints and unchanged attachment outlines; swaps use their declared landmarks.
+
+```json
+{"animation":"idle","fps":60,"requiredAnimations":["idle","win"],
+ "motion":[{"bone":"hair_tip","channel":"rotation","space":"local","minAmplitude":1},
+           {"bone":"foot_left","maxSetupDrift":0.5}],
+ "transitions":[{"from":"idle","to":"win","mix":0.18,"maxStep":8}]}
+```
+
+These numbers illustrate the schema, not universal pass limits. Combine semantic gates with
+`rig_check` front-order/landmark rules and current rendered image gates. A numeric “foot” or
+“hair” id does not verify that its artwork is anatomically the correct feature.
+
+## Exclusions are measured, not silent skips
+
+Every exception needs a concrete reason, explicit mask and frame indices. The report includes
+excluded pixel fraction and fraction of affected frames. Limits `maxExcludedArea` and
+`maxExcludedFrames` are chosen for the brief and recorded in the configuration; exceeding them
+fails. An all-excluded frame, absent frames, empty reference, stale render or wrong image size
+also fails. Never raise limits solely until a defect passes. A new large hole touching one
+approved curl does not make the entire connected component exempt: baseline gaps are compared
+pixel by pixel, and new exposed area remains measured.
+
+A rest-pose negative space may move during animation. Model that legitimate moving opening
+explicitly or register its local reference; do not grow a global exemption rectangle until
+most action frames disappear from QA. Likewise a regenerated prop is reviewed by shape and
+landmarks, not silently zeroed out of the entire setup-difference image.
+
+Before relying on a gate, inject representative failures into temporary inputs: remove one
+frame, modify the rig/texture, introduce a large internal gap, freeze the secondary track,
+break a discrete loop endpoint, move one swap landmark, or misorder the IK follower. The gate
+must fail for that reason. Restore original inputs afterward. Report exact checked sample counts,
+accepted exceptions and remaining visual uncertainty; “16 green gates” is not meaningful if
+those gates never observed the current rig or excluded the affected action.

package/skills/golem-symbol-animation/references/spine-rive-study.md

@@ -0,0 +1,87 @@
+# Applying Spine and Rive mechanisms in Golem
+
+Read for imported rigs, flexible full characters, combined expression controls or interactive
+motion. Official reference exports and playback were inspected on 2026-10-05. Source
+mechanisms and Golem capability are separate facts: check the current schemas and warnings.
+
+## Map mechanisms to controls
+
+| Source mechanism | Golem construction | Verification |
+|---|---|---|
+| Spine region / Rive parented rigid element | Region attachment under a bone | Prop/hand outline remains rigid at maximum rotation |
+| Weighted mesh | Mesh with normalized influence weights; rigid selections pinned | Bind pose, bend in both directions, compression and triangle/silhouette review |
+| IK endpoint + path shape | Stable endpoint targets plus a path-controlled chain | Contacts stay planted while hips move; constraint order and chain spacing remain valid |
+| Attachment timeline / Rive Solo | One slot for mutually exclusive attachments; step keys | Before/at/after switch; landmarks, visibility and local alpha agree |
+| Draw-order keys / Rive draw-order rules | Golem drawOrder track independent of hierarchy | Hands, clothing and props cross correctly at contact |
+| Joystick / blend state | Semantic controls and bindings, or explicit runtime logic | Combined values and transitions; each output property has one intended owner |
+| State-machine layers | Base/main animations and named overlays where semantics match | Interrupt, queue, release, transition and replay, not only direct timeline seeking |
+
+The [Spine examples](https://esotericsoftware.com/spine-examples) provide editable/exported
+rigs for inspecting bones, weights and constraints. [Rive bones](https://rive.app/docs/editor/manipulating-shapes/bones),
+[meshes](https://rive.app/docs/editor/manipulating-shapes/meshes) and
+[joysticks](https://rive.app/docs/editor/manipulating-shapes/joysticks) explain the distinction
+between rigid parenting, deformation and reusable pose controls.
+
+## Import fidelity before motion polish
+
+Inspect `rig_import_spine` warnings. In updated Golem, `skin` selects a coherent setup and
+attachment lookup, with default-skin fallback. Other skins' attachments remain editable
+variants; this is not a dynamic Spine skin API. Linked meshes lower to independent editable
+mesh attachments with inherited deform keys. Texture lookup follows `path`, then an explicit
+attachment `name`, then the placeholder key. Sequences lower to attachment switches.
+File import resolves all named pages of a multi-page atlas; pack to the established one-atlas
+delivery afterward. A single `image` override applies only to a one-page source.
+
+Spine clipping lowers to a closed path with `clipping: {end?: slotId}`. Its active attachment
+starts a clipping span in the current draw order, ending after the named slot. Removing that
+attachment disables the span. Golem's explicit `slot.clip` is a separate authoring mask and
+can use a hidden path. Do not replace animated span semantics with a fixed list of masked
+slots, or make all explicit masks depend on path-slot visibility.
+
+Keys may contain `componentEase`, one easing per numeric-array component. Preserve it when
+editing imported RGBA keys: alpha and RGB may have different curves. Independent component
+easing is segment interpolation; do not replace it with PCHIP without intending to change
+the source motion. Equal numeric endpoints do not imply a hold: an absolute Spine Bézier
+curve can leave that value and return. The importer lowers such scalar excursions to its
+ten linear sampling segments.
+
+Warnings identify partial import. Spine physics constraints/timelines and dark two-color
+tint are not reproduced by Golem; baking secondary motion is an authoring alternative,
+not a proof that it matches the original physics. `.riv` import/export is not implemented.
+Recreate supported controls from reference evidence without claiming Rive compatibility.
+Treat zero-scale path poses as special fidelity checks: orientation can become ambiguous
+and differ from Spine even when all bone origins match. Inspect the rendered silhouette.
+
+## Build motion through extremes and transitions
+
+Use [Spineboy](https://esotericsoftware.com/spine-examples-spineboy) to study IK contacts,
+rigid props, visibility and portal clipping; [Raptor](https://esotericsoftware.com/spine-examples-raptor)
+for continuous weighted surfaces; [Stretchyman](https://esotericsoftware.com/spine-examples-stretchyman)
+for endpoint/shape control; [Mix and Match](https://esotericsoftware.com/spine-examples-mix-and-match)
+for variants. Compare a setup, anticipation, maximum bend, contact, follow-through and
+settled pose rather than copying the entire hierarchy into another character.
+
+Put secondary controls under the part that carries them, but contact targets under a stable
+space. Choose overlapping cuts or an alternate view when one weighted image loses its
+silhouette. Bake purposeful lag only after the driver's beats and contacts read clearly.
+Hold a driven pose long enough to verify settling; include reverse travel and loop endpoints.
+
+Rive [layers](https://rive.app/docs/editor/state-machine/layers) and
+[transitions](https://rive.app/docs/editor/state-machine/transitions) show why a working clip
+does not establish working interaction. Write the event/input → action mapping. Declare
+ownership of blink, gaze, expression, mouth, head turn and body channels; avoid two overlays
+silently replacing the same property. Exercise interruptions and entry/exit while an overlay
+is active. Joystick scrubbing and time playback are different uses of an authored timeline.
+
+## Evidence for a quality claim
+
+Use a matching source runtime for numerical fidelity checks: origins, full matrices, visible
+attachment identity, skinned/deformed vertices, draw order and color/alpha. Enumerate every
+source clip and selected skin, and include samples either side of discrete changes. Float32
+key times can place two runtimes on different sides of an exact boundary; sample a bounded
+epsilon before/after and report it. Do not suppress real jumps with a large tolerance.
+
+Numerical agreement does not prove seam-free artwork. Inspect normal-speed playback at the
+intended size, plus joint closeups, masks, pupil edges, swaps and transition extremes. A
+contact sheet is pose evidence, not continuous playback evidence. Preserve source URLs,
+versions, tested coverage and concrete exceptions in QA outside the packed delivery.

package/skills/golem-symbol-animation/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-animation/scripts/check_package.py

@@ -0,0 +1,71 @@
+#!/usr/bin/env python3
+"""Check the two-file Golem delivery contract; run rig_validate separately."""
+
+import argparse
+import json
+import struct
+from pathlib import Path
+
+
+def check_package(directory):
+    directory = Path(directory)
+    if not directory.is_dir():
+        return [f"Not a directory: {directory}"]
+    errors = []
+    expected = {"rig.json", "atlas.png"}
+    actual = {p.name for p in directory.iterdir()}
+    if actual != expected:
+        errors.append(f"Expected only rig.json + atlas.png; missing={sorted(expected - actual)}, extra={sorted(actual - expected)}")
+    for name in expected:
+        path = directory / name
+        if path.is_symlink() or not path.is_file():
+            errors.append(f"{name} must be a regular file inside the package")
+    if any(not (directory / name).is_file() or (directory / name).is_symlink() for name in expected):
+        return errors
+    try:
+        with (directory / "atlas.png").open("rb") as stream:
+            header = stream.read(24)
+        if len(header) != 24 or header[:16] != b"\x89PNG\r\n\x1a\n\x00\x00\x00\x0dIHDR":
+            raise ValueError("invalid PNG header")
+        width, height = struct.unpack(">II", header[16:24])
+        if width == 0 or height == 0:
+            raise ValueError("empty atlas dimensions")
+        doc = json.loads((directory / "rig.json").read_text())
+    except (OSError, ValueError) as error:
+        return errors + [str(error)]
+    assets = doc.get("assets") if isinstance(doc, dict) else None
+    if not isinstance(assets, list) or not assets:
+        return errors + ["rig.json must contain a nonempty assets array"]
+    for index, asset in enumerate(assets):
+        if not isinstance(asset, dict):
+            errors.append(f"assets[{index}] must be an object")
+            continue
+        label = asset.get("id", f"assets[{index}]")
+        if asset.get("src") != "atlas.png":
+            errors.append(f"{label}: src must be atlas.png")
+        frame = asset.get("frame")
+        if not isinstance(frame, list) or len(frame) != 4 or any(type(v) is not int for v in frame):
+            errors.append(f"{label}: expected integer frame [x, y, width, height]")
+            continue
+        x, y, w, h = frame
+        if x < 0 or y < 0 or w <= 0 or h <= 0 or x + w > width or y + h > height:
+            errors.append(f"{label}: frame {frame} is outside {width}x{height} atlas")
+    return errors
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("directory", type=Path)
+    args = parser.parse_args()
+    errors = check_package(args.directory)
+    if errors:
+        for error in errors:
+            print(f"ERROR: {error}")
+        return 1
+    print("Package OK: rig.json + one atlas.png; all asset frames are in bounds.")
+    print("Run Golem validation and packed playback QA separately.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())