@energy8platform/golem 0.6.0 → 0.7.0

package/editor.html

@@ -1,3 +1,3 @@
 <!doctype html>
-<html><head><meta charset="utf-8"><title>rig editor</title><link rel="stylesheet" href="/dist/editor.css"></head>
-<body><div id="app"></div><script type="module" src="/dist/editor.js"></script></body></html>
+<html><head><meta charset="utf-8"><title>rig editor</title><link rel="stylesheet" href="dist/editor.css"></head>
+<body><div id="app"></div><script type="module" src="dist/editor.js"></script></body></html>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@energy8platform/golem",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "AI-first 2D rigging for slot games: rig.json format, PixiJS v8 runtime, MCP tools and a browser editor",
   "license": "MIT",
   "repository": {
@@ -49,7 +49,9 @@
     "playwright": "^1.50.0",
     "pngjs": "^7.0.0",
     "preact": "^10.29.8",
-    "zod": "^3.24.0"
+    "schemastery": "^3.18.0",
+    "zod": "^3.24.0",
+    "zod-to-json-schema": "^3.25.2"
   },
   "devDependencies": {
     "@esotericsoftware/spine-core": "^4.2.109",
@@ -73,12 +75,19 @@
     "dist/editor.js",
     "dist/editor.css",
     "editor.html",
-    "bin"
+    "bin",
+    "skills",
+    "!skills/**/__pycache__"
   ],
   "bin": {
     "golem": "bin/golem.js"
   },
   "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/lib/e8/host.d.ts",
+      "import": "./dist/lib/e8-host.js"
+    },
     "./runtime": {
       "types": "./dist/lib/runtime.d.ts",
       "import": "./dist/lib/runtime.js"
@@ -94,9 +103,35 @@
     "./interactive-editor": {
       "types": "./dist/lib/interactive-editor.d.ts",
       "import": "./dist/lib/interactive-editor.js"
+    },
+    "./e8/runtime": {
+      "types": "./dist/lib/e8/runtime.d.ts",
+      "import": "./dist/lib/e8-runtime.js"
+    },
+    "./e8/agent": {
+      "types": "./dist/lib/e8/agent.d.ts",
+      "import": "./dist/lib/e8-agent.js"
     }
   },
   "peerDependencies": {
     "pixi.js": "^8.6.0"
+  },
+  "e8": {
+    "runtime": {
+      "entry": "./dist/lib/e8-runtime.js",
+      "schema": "./dist/lib/e8-schema.js"
+    },
+    "agent": {
+      "entry": "./dist/lib/e8-agent.js",
+      "skills": "./skills"
+    },
+    "client": {
+      "entry": "./dist/lib/e8-client.js",
+      "inject": [
+        "viewers",
+        "history",
+        "connection"
+      ]
+    }
   }
 }

package/skills/e8-golem/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: e8-golem
+description: Use in an e8-engine project to build, animate and place Golem rigs — the rig_* tools, the golem scene node, the rig editor tab and undo.
+---
+
+# Golem rigs in e8
+
+The `golem1` row (`@energy8platform/golem`) gives the agent every `rig_*` tool, registers the `golem` scene node type and opens `rig.json` files in the rig editor inside the IDE. Rigging and animation craft lives in `golem-symbol-animation` (and `golem-symbol-cutting` for flat art); this skill is how that work lands in an e8 project.
+
+## Where rigs live
+
+One directory per rig under `assets/` (the build copies only `assets/`):
+
+```
+assets/rigs/<name>/rig.json        the document
+assets/rigs/<name>/layers/*.png    parts (or one atlas.png after rig_export)
+```
+
+`path` in every `rig_*` call is project-relative (`assets/rigs/gem/rig.json`); other file arguments (`layersDir`, `image`, `outDir`…) are relative to the rig's directory. Anything outside the project is refused.
+
+## Build a rig
+
+1. `files_list` — find the layers (PNG parts) or the single symbol image.
+2. One image: `rig_create_symbol` with `{ "path": "assets/rigs/gem/rig.json", "image": "../../symbols/6.png" }`. Layers: `rig_create`, then `rig_import_layers` with `{ "layersDir": "layers" }`.
+3. Animate with `rig_apply_preset` / `rig_set_keys` (see `golem-symbol-animation`), checking each step with `rig_render_preview` — it answers with a picture.
+4. `rig_check` before placing it.
+
+## Place it
+
+A `golem` node goes in a scene document (`e8-scenes`) or a symbol state (`e8-symbols`). Its props:
+
+- `rig` (required) — the `rig.json`, project-relative;
+- `animation` — empty means the rig's first animation;
+- `loop` (default true), `speed` (default 1);
+- `controls` — expression controls by id, `{ "smile": 0.8 }`. A set control overrides that control's animated track; an empty map gives the tracks back.
+
+The node's origin is the centre of the rig's canvas (`meta.width` × `meta.height`), so `x`/`y` place that centre.
+
+### In `base_game`
+
+`scenes_get` with `{ "id": "base_game" }`, append the node, `scenes_put` the whole document:
+
+```json
+{ "id": "gem_hero", "type": "golem", "props": { "rig": "assets/rigs/gem/rig.json", "animation": "idle", "x": 400, "y": 260 } }
+```
+
+### A symbol that wins with a rig
+
+`symbols_get`; give the symbol a `win` state and `symbols_put` the whole document:
+
+```json
+{ "id": "6", "name": "gem",
+  "static": { "type": "image", "props": { "src": "assets/symbols/6.png" } },
+  "win": { "type": "golem", "props": { "rig": "assets/rigs/gem/rig.json", "animation": "win", "loop": false } } }
+```
+
+As a symbol state the node plays its `animation` once to the end.
+
+## Live editing and undo
+
+- A `rig_*` write reaches the open rig tab and the running preview without a reload.
+- Each of your writes is one undo step in the IDE: Mod+Z on the rig's tab runs `rig_undo` for the latest, again for the one before, and redo walks forward. A step is refused, file untouched, when the rig changed since (a human edit, or your own `rig_undo`).
+- Your `rig_undo`, `rig_redo` and `rig_export` calls are not IDE steps. Ctrl+Z inside the editor and `rig_undo` walk the same history.
+- `rig_render_preview`, `rig_export_video` and `rig_verify_render` need Chromium on the host machine (`npx playwright install chromium`).
+
+## Traps
+
+- An `animation` the rig does not have falls back to the first animation, silently. `rig_get` lists the ids.
+- A `.json` that is not a rig (no `"format": "energy8.rig"`) is an error on the node.
+- Replacing a PNG by hand does not refresh a placed rig; a `rig_*` call that rewrites `rig.json` does.
+- `anchor` does nothing on a `golem` node.

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

@@ -0,0 +1,87 @@
+---
+name: golem-symbol-animation
+description: Build or continue editable symbol and full-character rigs and animations in Golem from prepared PNG layers, an atlas, or an existing rig. Use for motion briefs, layered rigging, playback verification, Golem exports and integration with @energy8platform/game-engine. Use golem-symbol-cutting when flat artwork needs animation-driven separation or hidden-surface repair.
+---
+
+# Golem symbol animation
+
+Create an editable Golem rig, animation tracks matching the requested performance, and reviewable playback. Use Golem's tool registry for rig operations.
+
+## Inputs
+
+Accept prepared layers, an atlas with any available metadata, an assembled reference, or an existing Golem rig. Preserve source artwork. For follow-up changes, continue from the working rig and retain useful tracks rather than rebuilding unnecessarily. If the user supplies a Spine skeleton and atlas, inspect `rig_import_spine` and its warnings before deciding what must be reconstructed manually.
+
+## Establish the performance before rigging
+
+Reuse the supplied animation plan, prepared `layers/layers.json` sidecar and extraction provenance. Establish each action's trigger, emotional intent, main beats, extreme poses, duration or timing constraints, loop behavior and entry/exit state. Include display size, contact point and intended FX. When the rig will run in a game, identify the actual engine lifecycle hook for every action; an animation existing in `rig.json` does not make the game call it. Ask only for missing decisions that materially affect the work; use stated working assumptions when the user delegates creative direction.
+
+Map each beat to required controls and visibility changes. If flat art needs separation, hidden surfaces are missing, or a new action exceeds the prepared art's coverage, use [golem-symbol-cutting](../golem-symbol-cutting/SKILL.md) for the affected parts. Pass back the same brief and preserve decisions that remain valid. If that sibling is unavailable, document the required preparation and complete what the available art supports.
+
+Do not infer the original animation set, emotion or FX sequence from atlas packing. An existing brief takes priority over the illustrative `land`/`idle`/`win` patterns below.
+
+## Establish the working surface
+
+Locate Golem through the workspace checkout or the installed `@energy8platform/golem` package. Read applicable repository instructions and inspect package exports/scripts before choosing commands: the installed `golem` binary may expose only the editor, while the checkout has a separate rig CLI. If neither is available, ask for the Golem environment rather than silently substituting another product.
+
+Read [references/golem-authoring.md](references/golem-authoring.md) before building the rig or writing tracks. When the target is an `@energy8platform/game-engine` project, also read [references/game-engine-integration.md](references/game-engine-integration.md). Verify needed tool schemas and package exports against the current installation. Use a connected Golem MCP, the supported rig CLI, or `callTool` from `@energy8platform/golem/tools` (checkout: `src/rig-api.ts`); these share mutation validation and history. Do not hand-write the finished rig around the tools.
+
+Keep authoring work outside the delivered rig directory, for example in `art/symbol-work/<id>/`. The delivered symbol directory contains exactly `rig.json` and one `atlas.png` shared by all its actions, expression variants and FX. No layers, scripts, QA, history, duplicate rig or nested `packed/` directory belongs there. Read [references/packed-delivery.md](references/packed-delivery.md) before creating output paths; it defines staging, history preservation, packing and package verification. Use the user's destination and preserve unrelated work and existing deletions.
+
+## Editable in-page previews
+
+When the user requests a preview they can adjust with the mouse, read [the interactive editor workflow](references/interactive-editor.md) and verify that the installed package exports `@energy8platform/golem/interactive-editor` before using it. Group coupled artwork under one logical control so, for example, a hand and its companion layers stay registered during edits. Keep editor patches separate from the canonical rig and animation keys; export and reapply them explicitly through the documented workflow rather than claiming that a preview adjustment has rewritten the source animation.
+
+After editing, check selection and manipulation at the actual display size, replay affected actions at normal speed, and inspect extremes, overlaps and contacts with the patch reapplied. Record the patch and its limitations outside the packed rig directory. An editable Golem preview or patch is not a Spine project or proof of Spine export compatibility.
+
+## Reconstruct the artwork
+
+1. Inspect supplied layers/atlas and assembled reference. Use a light/checker background: black strokes and transparent cutouts are easily missed on black. Record actual pixel dimensions; convert resized inspection coordinates back to original pixels.
+2. Reuse verified source metadata and the cutting manifest before making new visual guesses. Keep extraction rectangles separate from document placement, joints, parents and slot draw order. A horn or ear can span several atlas regions. Preserve the handoff's side convention; otherwise use viewer-left/right consistently.
+3. If extraction is still needed, use `scripts/atlas_parts.py` for checker inspection and deterministic rectangular crops. Run `--help`. It requires Pillow, preserves decoded RGBA values and performs no rotation, masking or reconstruction. Undo packing rotation separately. Skip re-extraction when prepared layers already exist.
+4. Fit translations, rotations and scale using the supplied assembled PNG. Optional pixel matching must tolerate occluded surfaces, try quadrant rotations, and remain subordinate to visual inspection. A low matching error alone does not prove correct part identity or assembly.
+5. Inspect each crop, then a Golem rest render. Check missing tips, truncated contours, doubled strokes, neighboring atlas fragments and seams at overlaps. Do not globally discard small alpha components: fangs, chin strokes, spark fragments and lower eyelids may be intentional. Make any cleanup local, reversible and documented.
+
+Without an assembled reference, use a clearly stated interpretation of the visible parts; do not invent claims of exact original reconstruction. Ask only when ambiguity prevents a usable symbol.
+
+## Author motion
+
+For Spine imports, flexible full characters or interacting expression/motion layers, read [references/spine-rive-study.md](references/spine-rive-study.md). Verify selected skins, inherited deformation, clipping spans, component curves and actual runtime transitions before claiming fidelity.
+
+For reusable adjustable eyes, gaze and mouth expressions, read [facial-controls.md](references/facial-controls.md). It covers optional Golem 0.4 parameter grids, ownership, editor keyforms and combined-pose validation.
+
+Read [motion-craft.md](references/motion-craft.md) for continuous curves, minimum-jerk contacts,
+planted-foot IK, cloth/hair chains, mesh limits, grip changes and baked secondary motion.
+Use a pilot containing the hardest extreme and transition before multiplying the approach
+across animations or characters. Seek user review when the brief calls for it or the pilot
+changes approved appearance; existing approval remains valid.
+
+
+For independently generated facial parts or corrections to scale, placement or FX, read [registration-and-motion.md](../golem-symbol-cutting/references/registration-and-motion.md). Verify every expression in the composed rig before polishing motion. Equal PNG dimensions, a shared scale factor or matching bbox centers do not establish matching facial proportions. Prefer a clean head base plus local feature controls for local expression changes; use full-head swaps only when the performance needs a whole-head redraw.
+
+Build controls around the actual artwork and performance. For a bust with a cell landing, this often means a contact-point root, a head pivot near the neck, and controls for independently moving features. Other symbols may need a different hierarchy. Keep fragments of one rigid part registered to the same logical control; put simultaneously visible images in separate slots. Use one slot for mutually exclusive variants where appropriate. Check painted overlap and facial backing against the planned extreme poses before polishing timing.
+
+Match the user's requested set and tone. If the request matches the usual three-state slot workflow, use these as starting points, not fixed timings or universal presets:
+
+- `land`: quick descent, readable contact compression, restrained rebound and settling of ears/horns. Maintain a believable cell contact point and leave room above the symbol.
+- `idle`: small breathing and head/ear movement with an occasional blink. Make t=0 the approved setup pose unless the brief explicitly defines another base; match first/last pose and velocity, including attachment visibility and other animated channels.
+- `win`: anticipation, a clear celebratory accent, expression change if the atlas supports it, secondary motion and a return suitable for idle. Effects should support the face and remain legible at cell size.
+
+Author local motion where the performance calls for it; a deliberate whole-symbol pulse does not require artificial facial movement. Use meshes where bending or surface deformation is part of the brief. If the prepared art cannot support a required extreme, return that specific issue to cutting/repair or explicitly revise the brief instead of silently reducing the requested action.
+
+For blinks, coordinate lids and eye visibility; squashing the eyeball alone can leave a white hairline. Keep the mouth cavity behind an open-mouth cutout throughout its movement. Verify facial landmark registration and companion-slot visibility on both sides of an expression switch. Hide transient effects in setup and outside their active interval, unless the brief specifies a persistent effect. Use supplied FX only with a verified or explicitly authored sequence and stable frame alignment; packing order is not playback order.
+
+When mouth opening requires jaw travel, animate the lower face/chin with a suitable mesh or jaw control and coordinate the mouth, cavity and teeth with it. Anchor the upper face and nose unless the brief calls for their movement; a moving mouth sticker alone does not move the jaw. Inspect opening, maximum extension, closing and return for folds, detached contours and pops. Do not add a mesh merely to increase the vertex count.
+
+## Verify and deliver
+
+Use [quantitative-qa.md](references/quantitative-qa.md) for reproducible numerical gates and current render evidence. Run `rig_validate` and `rig_check` and read their text: a successful tool invocation alone does not mean there are no findings. Render setup and the meaningful phases of the actual brief, including extremes and frames around visibility switches. Inspect at intended symbol size as well as larger detail views. Refine until assembly and motion are visually sound.
+
+Play each action at its actual speed and intended cell size. Check that idle is perceptible without zooming or scrubbing and that the main beat and secondary motion read clearly; restrained does not mean invisible. A contact sheet, error-free load, build or checker result cannot establish this. For a reported visual defect, compare before/after at the same framing, inspect all affected variants and both sides of switches, and state what was observed. Do not declare a visual issue fixed from PNG measurements or technical checks alone.
+
+Resolve clipping, broken references, folds, unintentional discontinuities and loop seams. Investigate `motion_pop` warnings with nearby frames and timing: a deliberate fast impact can trigger the heuristic, but warnings are not automatically harmless. Preserve any accepted findings with their concrete explanation; never claim all checks pass while leaving unexamined warnings.
+
+Compare loop endpoints and action-to-action transitions across transforms, constraint channels, deformations, attachments, alpha, colors and draw order. Inspect motion immediately around loop boundaries as well as matching values. A looping preview at exactly its duration wraps to the start; inspect the true terminal keys/pose separately as described in the authoring reference. Matching bone matrices alone does not establish a seamless transition. Use denser sampling when brief extrema could be missed, through the supported preview options or the direct checker API described in the reference.
+
+Deliver one editable packed rig and one atlas through the workflow in [packed-delivery.md](references/packed-delivery.md). Packing is required for each delivered revision, including follow-up fixes. Render representative setup, expression, deformation and FX states from the packed package against the working rig and inspect meaningful differences. For a game-engine target, load this same pair through the engine entry point. Keep requested GIF/MP4 previews and demonstrations outside the rig directory.
+
+Record sources, placement decisions, durations, animation IDs, trigger mappings, reproducible scripts and limitations in the external authoring workspace. Open the delivered packed rig in Golem when a local editor is available; reuse its server before starting another, and do not terminate somebody else's process. Keep the editor and game pointed at the same canonical package; use a staging copy for further mutations. Report visual, authoring, package and integration checks separately. Link the rig, atlas and external preview in the final response.

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Golem Symbol Animation"
+  short_description: "Rig, animate and integrate Golem characters and symbols"
+  default_prompt: "Use $golem-symbol-animation to build or continue a Golem symbol rig, animate it according to the supplied motion brief, and integrate it with the game engine when requested."

package/skills/golem-symbol-animation/references/facial-controls.md

@@ -0,0 +1,48 @@
+# Parametric facial animation
+
+Use this workflow when several actions reuse independently adjustable eyes, gaze,
+mouth opening or expression. Confirm the installed Golem supports `rig_set_control`,
+`rig_set_control_binding` and `rig_sweep_controls` (0.4+). Existing attachment swaps
+remain appropriate for fully redrawn expressions.
+
+Keep the approved neutral face. Plan controls and ranges from the requested performance;
+measure each side separately. A smile and an opening mouth often need a joint 2D grid,
+not the sum of two independent deformations. Use one owner per output channel. The grid
+contains absolute bone/alpha values and mesh vertex offsets, with the first axis varying
+fastest. Axes span the full declared ranges. Match the default keyform to approved setup.
+
+Author through the registry. `rig_set_control` declares id/label/min/max/default;
+`rig_set_control_binding` declares 1–2 axes and channels. Supported outputs are bone
+transforms, slot alpha and mesh/path vertex offsets. Key `target: control`, `prop: value`
+with existing track tools. Direct keys on bound channels are rejected. Constraints run
+after controls; check ownership when both affect a bone. Keyform editing and temporary
+preview sliders are in the editor's expressions mode; record a preview with Key expression.
+
+Check mouth form × mouth opening, separate winks, near-open eyes, gaze extremes and
+head/body counter-motion relevant to this rig. For `rig_sweep_controls`, pass explicit
+probe arrays and a new output directory outside the packed rig. Add samples on both
+sides of geometry/opacity handoffs; the 256-pose budget is a bound, not a coverage target.
+The report binds listed cases to actual PNG/rig/texture/renderer hashes. A geometric
+effect or numerical pass does not prove visible pixel movement or attractive artwork.
+Inspect the frames at cell size and facial closeups, and play the actual animation.
+
+For blinks, coordinate a continuous eyelid curve with eye-white/iris coverage and closed
+lashes. Two overlapping half-alpha strokes yield 0.75 coverage, so a naive crossfade can
+create a pale seam. Evaluate the actual composite around handoffs. Avoid zero-area mesh
+triangles; hide a fully closed aperture with explicit opacity/masking if needed.
+
+An opaque closed-lash repair should enter when the aperture and lash are already aligned.
+Fading it across a still-white opening can create a grey band even when geometry passes.
+Sample densely near that handoff. For boundary-pinned surface patches, check actual
+rendered alpha during head rotation as well as setup; see the cutting skill's facial-layer
+reference for source-derived underlap that preserves soft external contours.
+
+For neutral and packed comparisons, retain raw RGBA diagnostics and also compare composites
+over black and white. Unpremultiplication can amplify tiny RGB errors at low alpha. An
+unmodified source rendered through the same pipeline helps distinguish those errors from
+an authoring change; retain the raw-source comparison too, and report concrete tolerances.
+
+Use `RigPlayer.setControls(values)` for runtime manual input; each call replaces the input
+set, and `resetControls()` returns ownership to animation/defaults. Generic preset export
+currently lists control tracks as skipped; do not claim automatic transfer to other faces.
+Pack and compare the working/packed expressions through the normal delivery workflow.

package/skills/golem-symbol-animation/references/game-engine-integration.md

@@ -0,0 +1,133 @@
+# Integrating a Golem rig with game-engine
+
+Use this workflow when the target project depends on
+`@energy8platform/game-engine` and `@energy8platform/golem`. Verify the installed
+package versions and their current exports before changing game code; the
+examples describe the implemented 0.43/0.1 integration and may evolve.
+
+## Deliver one canonical package
+
+The editable package loaded by the game is:
+
+```text
+public/assets/rigs/<symbol-id>/
+  rig.json
+  atlas.png
+```
+
+Every asset `src` resolves to this same `atlas.png`; frame metadata selects each
+part. All actions share the pair. Keep layers, working rigs, scripts, previews
+and history outside the delivered rig directory, following
+[packed-delivery.md](packed-delivery.md). Stage edits there, export and verify,
+then update the canonical pair. Do not keep an editable/packed duplicate inside
+`public/assets/rigs/<symbol-id>/`.
+
+Prefer the project's `npm run rigs` and inspect its configured root. With
+`golem editor --root public/assets/rigs`, the query is
+`editor.html?rig=<symbol-id>/rig.json`; with a root at the symbol directory it is
+`editor.html?rig=rig.json`. Do not give users different rigs for editor and game.
+Use a staging copy for mutations and preserve its `.rig-history/` for undo.
+
+For production builds, verify no authoring files or `.rig-history/` reach the
+output. If the game has an engine history-strip plugin, keep it enabled, but a
+build filter does not replace the clean source-package check.
+
+## Load through the engine entry point
+
+In game code, use the engine adapter so the rig shares the game's PixiJS and
+the `SymbolView` contract:
+
+```ts
+import {
+  loadRigs,
+  RigSymbol,
+  type Rig,
+} from '@energy8platform/game-engine/golem';
+
+const rigIds = ['h1'] as const;
+let rigs: Record<string, Rig> = {};
+
+export async function loadSymbolRigs() {
+  rigs = await loadRigs(Object.fromEntries(
+    rigIds.map(id => [id, `assets/rigs/${id}/rig.json`]),
+  ));
+}
+
+export const resolveSymbol = (id: string) => rigs[id]
+  ? new RigSymbol(rigs[id].doc, rigs[id].textures, { size: 110 })
+  : createOrdinarySymbol(id);
+```
+
+Call the loader before the first symbol resolution. List rigged symbols
+explicitly: `loadRigs` rejects missing named files rather than probing 404s.
+Do not import the Node tools or editor entry into browser game code. Avoid a
+second PixiJS installation; `@energy8platform/golem` uses the game's `pixi.js`
+as a peer.
+
+For a character outside the reels, create a `RigPlayer`, add `player.view` to a
+Pixi container and advance `player.tick(seconds)` from the scene update.
+`RigSymbol` advances itself with a ticker and removes its callback on destroy.
+
+## Map animations to game lifecycle
+
+`RigSymbol` defaults to these animation IDs:
+
+- `idle`: looping base state used by `playIdle()`.
+- `win`: non-looping action used by `playWin()`; the returned promise resolves
+  on completion, and playback returns to the base state when one is established.
+- `dim`: optional held state used by `setDim(true)`.
+
+Different IDs can be mapped with
+`animations: { idle: 'breath', win: 'celebrate', dim: 'lose' }`. Verify that the
+mapped actions have the required loop and terminal behavior. `showStatic()`
+clears animation state and displays the rig's setup pose.
+
+`land`, `hit`, overlays and other custom actions are not automatic
+`SymbolView` lifecycle hooks. Record and implement their game-owned trigger,
+for example through `symbol.player.state.play('land')` or the scene's own
+controller. Do not call an action integrated merely because it exists and plays
+inside Golem.
+
+## Verify in the real container
+
+In addition to `rig_validate`, `rig_check` and Golem previews:
+
+1. Load the rig with `loadRig`/`loadRigs` from the game-engine entry.
+2. Mount `RigSymbol` in a real `SymbolCell` or the project's actual resolver.
+3. Exercise `playIdle`, `playWin`, `showStatic`, `resize` and destruction.
+4. Test both a square numeric size and a rectangular `{ width, height }` size.
+   The rig canvas is fitted and centered, so inspect cell clipping, perceived
+   scale, contact point and motion margins rather than only type success.
+5. Exercise every custom game trigger and the transition back to idle.
+6. Run the Golem checkout's `npm run verify:engine` when its expected sibling
+   engine or target game is available, then run the target game's typecheck and
+   relevant build/test command.
+
+Report exactly which layers were checked: Golem authoring, packed equivalence,
+engine adapter loading, real-cell lifecycle, target-game typecheck and
+production build are separate claims.
+
+## Transition and animation-ID contract
+
+Inspect the runtime actually installed in the game. In the updated checkout, `RigPlayer`
+defaults to a 0.18-second mix and `play()` inherits the constructor mix unless overridden;
+`mix: 0` is an explicit hard cut. Older versions force `play()` to mix 0 even when the
+constructor supplies another mix. Always pass the intended mix at the game call site when
+supporting those versions. `AnimationState.play()` also accepts a per-call mix; direct state
+calls and player calls must be tested separately when the game uses both.
+
+The updated runtime warns for an unknown animation and drops the invalid request, resolving
+pending work and returning to its existing base (or setup if no base exists). For strict QA,
+construct the player/state with `missingAnimation: "throw"`; `onWarning` can capture warnings
+in a game log. Older versions throw on missing IDs unconditionally. Runtime recovery is not
+permission to deploy an incomplete action set: before replacing the game's canonical pair,
+compare every lifecycle mapping and custom trigger against the delivered document's IDs.
+Stage a partial pilot outside the game until its required action contract is complete.
+
+Transition gates must execute the real `AnimationState`, or `RigPlayer` where wrapper options
+matter. Use the same base, overlays, priorities, explicit/default mixes and update cadence as
+the scene. Exercise action → base, action interruption, missing IDs, visibility swaps, colour,
+constraint mixes, draw order and deform arrays. Do not replace this with a handwritten lerp:
+it can pass a transition the game never performs. In a mixed transition, newly introduced
+numeric channels blend from setup; discrete channels remain at the previous state until the
+mix ends. Inspect those actual intermediate poses for contact and layering problems.

package/skills/golem-symbol-animation/references/golem-authoring.md

@@ -0,0 +1,138 @@
+# Golem authoring mechanics
+
+Use this as guidance, then check the current checkout's schemas. Golem APIs can change.
+
+## Tool entry points
+
+First distinguish a Golem source checkout from a game with the installed package.
+The commands below require the checkout's `rig` npm script. The published `golem`
+binary currently exposes `editor`, not `list` or `rig list`. In a game, inspect its
+scripts and use `@energy8platform/golem/tools` for registry operations:
+
+```js
+import { tools, callTool, closeTools } from '@energy8platform/golem/tools';
+const entry = tools.find(tool => tool.name === 'rig_import_layers');
+console.log(entry?.description, entry?.input.shape);
+```
+
+Use the exported schema's `safeParse` to check arguments; do not repeatedly guess
+CLI variants or dump bundled source maps. Installed packages may contain only
+`dist/lib`, not `src`, and may not export `package.json` as a module subpath. Resolve
+the supported `tools` entry and inspect the package files from there if necessary.
+
+```sh
+npm run rig -- list
+npm run rig -- rig_validate '{"path":"symbols/example/rig.json"}'
+```
+
+For many related calls, place an authoring TypeScript script inside the checkout and import its current registry with the appropriate relative path:
+
+```ts
+import { callTool, closeTools } from '../../src/rig-api';
+const path = 'symbols/example/rig.json';
+async function tool(name: string, args: Record<string, unknown> = {}) {
+  const result = await callTool(name, { path, ...args });
+  if (result.isError) throw new Error(result.text);
+  // Persist request + response in the authoring log.
+  return result;
+}
+try {
+  await tool('rig_create', { name: 'Example', width: 640, height: 640 });
+  // Add bones, import authored layers, place attachments, set tracks.
+} finally {
+  await closeTools();
+}
+```
+
+Use `node --import tsx path/to/authoring.ts`. Apply dependent mutations sequentially. Stop on `isError`; a failed operation must not be treated as saved. Rebuilding starts from `rig_create` and reapplies the authored steps; do not rerun only a stage that adds already-existing IDs.
+
+The wrapper above catches invocation/mutation failures. `rig_validate` can return validation problems in `text` without `isError`; `rig_check` also returns findings as text. Read both reports. For programmatic checks, `validate` in `src/rig-format.ts` returns validation errors and `checkRig` in `src/rig-check.ts` returns structured findings. Do not use CLI exit status alone as a quality gate. Creating at an existing path replaces the rig after saving history, so use a fresh output path for experiments.
+
+## Editing setup after animation exists
+
+Setup changes and animation changes are distinct. Bone keys are absolute: moving a
+setup bone does not rebase its keyed x/y/rotation. Before accepting an editor fix,
+compare the new setup with every track addressing the changed control, including
+unkeyed actions and inherited child motion. For a translation-only registration
+change, add the setup delta to the affected absolute keys while preserving timing
+and motion offsets; do not apply that shortcut to a changed parent, pivot, scale or
+rotation without re-evaluating world-space poses. Check both action entry/exit and
+all loop channels, then re-render the current file. Previous QA is stale after an
+editor mutation even when its atlas did not change.
+
+## Coordinates and layer import
+
+Resolve `layersDir` from the rig's directory, not the shell working directory.
+`relPrefix` independently describes how `asset.src` reaches those same PNGs from
+the rig. For a staging rig `work/rig.json` and layers at `work/layers/`, both are
+`layers`; passing `art/symbol-work/id/work/layers` again would duplicate the path.
+Check that both resolved locations agree and exist before calling the importer.
+
+Golem uses pixels, origin top-left, positive Y downward, and degrees clockwise. Bone transforms and animation values are local to parents. Bone key values are **absolute**, not deltas: if setup Y is -115, an offset of -4 means a key value of -119.
+
+`rig_create` starts the root at bottom-center. Reposition it deliberately before importing. Leave canvas margins for the entire motion, including rotated rectangle corners and effects, not only setup opaque bounds.
+
+`rig_import_layers` reads an agent-authored `layers/layers.json` sidecar, for example:
+
+```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]
+  }
+]
+```
+
+These `bbox` and `joint` values describe **placement in the document**, not source-atlas crop coordinates. Keep extraction rectangles in a separate authoring manifest. Use original source rectangles as provenance, not as document placement.
+
+The current importer uses the full evaluated host matrix and its inverse for both joints and images, including parent rotations, scales, reflections and shear. `bbox` is the intended document-space rectangle; its width/height may differ from the PNG size and determine the drawn size. When the host would require shear that a region cannot express, the importer creates a four-vertex mesh preserving all corners. Check the assembled result under the actual constraints. Legacy releases added translations only and treated `bbox` as provenance: for those, import with neutral parent transforms or place attachments explicitly; do not assume the new behavior until the installed tool is verified.
+
+The cutting skill delivers this sidecar together with its animation brief and extraction provenance. Use it directly after checking paths and dimensions. If only an older `parts-plan.json` is available, convert it: for an unrotated, unscaled crop at `[x,y]` with final PNG dimensions `[w,h]` and local pivot `[px,py]`, use `bbox: [x,y,w,h]` and `joint: [x+px,y+py]`. Source-atlas `rect` stays in provenance. Keep `parent`, `bone` and `slot` references valid, and ensure `relPrefix` points from the rig directory to the actual PNG folder. Validate JSON before import: the current importer uses filename inference only when the sidecar is absent; malformed JSON fails. Older versions may silently fall back.
+
+`rig_set_attachment` x/y are image-center coordinates in the slot bone's space. Rotation on the attachment preserves a convenient bone axis for animation. Use `rig_get_pose` to inspect placements numerically; its slot bbox is `[minX,minY,maxX,maxY]`, unlike the importer's `[x,y,width,height]`. Hidden swap layers use `swap: true`; a new swap slot starts empty, while importing swaps into an existing slot leaves its current attachment selected. Explicitly choose setup visibility with `rig_set_slot`. Attachment IDs may differ from asset IDs; slot attachment keys select attachment IDs.
+
+Use a feature hierarchy such as root → head → ear or root → head → horn_base → horn_tip. Face switches can reuse a head slot. For effects, a dedicated bone avoids accidentally scaling all face geometry to enlarge a flash.
+
+## Tracks and visibility
+
+`rig_set_tracks` accepts `animation`, `duration`, `loop` and an array of tracks:
+
+```json
+{
+  "target": "bone", "id": "root", "prop": "scaleY",
+  "keys": [
+    {"t": 0, "v": 1, "ease": "ease_in"},
+    {"t": 0.2, "v": 0.9, "ease": "ease_out"},
+    {"t": 0.5, "v": 1}
+  ]
+}
+```
+
+Easing belongs to the interval **from this key into the next key**; omitted easing defaults to `ease_in_out`, which gives zero velocity at both ends of every segment. For continuous pass-through motion set track `interpolation: "pchip"`; it calculates shared tangents across numeric keys and still honours `step`. Use `minimum_jerk` easing only at deliberate stops (zero endpoint velocity and acceleration). See [motion-craft.md](motion-craft.md). Use explicit `step` for discrete attachments and intentional continuous curves for motion. Give entry and endpoint values explicitly. Sampling before the first key already returns that first key's value: a delayed FX activation needs a null/hidden key at t=0.
+
+With `merge: false` (default), each addressed track's keys are replaced, but unrelated tracks remain. With `merge: true`, keys at supplied times are replaced and other times remain. Inspect for obsolete tracks when revising. If rebuilding an animation is necessary, preserve its desired tracks, events and loop/timing settings, then use `rig_remove_animation` and recreate it through tools. Do not mistake a partial `rig_set_tracks` call for replacement of the entire animation.
+
+Slot `attachment` tracks take attachment IDs or null; alpha is a separate numeric channel. Both affect visibility. A hidden effect bone can have a nontrivial transform without making the effect visible; check its slot too. Background mouth art must cover the full aperture throughout the animation, not merely at setup.
+
+## Rendering and export
+
+Use `rig_render_preview` with explicit `times`, `scale`, `sheetColumns` and `saveTo`. Create the output directory first. Use close-ups or onion skin only when they answer a concrete assembly/motion question. The registry's preview calls include rig-check findings; read them. The tool exposes `background`, `transparent`, `weightBone`, `debugFillMasks` and `framesDir`. Transparent mode writes actual alpha; opaque mode is needed to assess additive/multiply blending against the game background. `framesDir` saves frames and a capture manifest for `rig_verify_render`.
+
+For individual frames, the current `src/preview/render-preview.ts` exports `renderPreview`. It takes a parsed document plus `assetsDir`, explicit sample times, scale and optional background, returning `frames` and a contact `sheet`. Use `rig_export_video` for MP4 at `fps: 60` (local ffmpeg required), or its returned frames for another encoder. MP4 output is opaque and duration is rounded to a whole frame, then reported. Close the preview browser in `finally`. A preview video may have an opaque presentation background while the source PNGs and exported atlas retain transparency.
+
+For loop playback, use N evenly spaced times `D*i/N`, `i=0..N-1`, where `N=max(1,round(D*F))`. This covers `[0,D)` without duplicating the start. An encoder running at F FPS gives duration N/F; if D*F is not integral, explicitly choose whether to quantize duration or adjust the encoding rate. A presentation hold is separate from game timing.
+
+At `t=D`, the current preview player wraps looping animations to t=0. It therefore cannot reveal a mismatched terminal pose by rendering `[0,D]` on the loop unchanged. Use `rig_get_pose` and direct `poseOf(animation,D)`/`evaluate` for unwrapped inspection. For a visual terminal check, pass an in-memory document copy with that animation's `loop: false` to `renderPreview`; do not change the saved animation solely for QA. Render just before/at/after the wrap for playback continuity. Also inspect terminal slot state, deformations, constraint values and draw order; `rig_get_pose` does not expose every animated channel.
+
+The `rig_check` tool accepts `path`, optional `animation`, `fps`, `deformFps`, `secondaryBones`, `frontOf`, `landmarks` and `landmarkTolerance`. The same options work in direct `checkRig`. Semantic rules and landmark maps come from the brief, not inferred anatomy. Explicit preview times should include short extrema and both sides of attachment changes, which a uniform grid may miss.
+
+`rig_export` takes an output directory relative to the rig directory (or absolute). It packs PNG assets into one Golem `atlas.png` and writes Golem `rig.json`. Export to external staging, compare with the working copy, then install only the verified pair in the delivery folder. Follow [packed-delivery.md](packed-delivery.md); packing is required for each delivered revision.
+
+Check both rig schema and motion. Compare setup/endpoint bone matrices **and** the visible slot state, deformations and draw order. Render packed and working documents at the same time, scale and background; measure differing pixels and maximum channel deltas, then inspect any meaningful difference.
+
+Chromium may need normal execution permission outside a restrictive sandbox. Use the environment's permission mechanism when necessary; do not change renderer semantics or disable checks to conceal a launch failure. If a local editor port is occupied, check whether the existing editor already serves the intended checkout.

package/skills/golem-symbol-animation/references/interactive-editor.md

@@ -0,0 +1,17 @@
+# Editable in-page previews
+
+Use this workflow when the user wants to adjust artwork with the mouse while keeping the existing Golem animation. Verify the installed package exports `@energy8platform/golem/interactive-editor`; a package version number alone does not prove that the new module is available. The complete API reference is `docs/interactive-editor.md` in the corresponding [Golem source checkout](https://github.com/Energy8Platform/golem). This skill-local reference remains available when the skill is installed separately from that checkout.
+
+Import `createInteractiveEditor` from that entry and give it the current `RigPlayer`, a dedicated transparent canvas overlay, and a stable `documentId` derived from the rig **and group configuration**. Size the overlay in renderer logical pixels and align its CSS rectangle with the rendered viewport. Keep playback and Pixi rendering in the host application; pause playback with `onGestureStart` when the user needs a stable pose for dragging. For custom cameras, provide matching `screenToDocument` and `documentToOverlay` conversions.
+
+Use `groups: [{ id, members, pivotBone }]` to couple attachments such as palm/finger layers or both halves of a collar. `members` are attachment IDs, not bone or slot IDs. An attachment can belong to only one group. The optional pivot bone defines the local space for adjustments; otherwise the first member's bone is used. Test groups at the requested extreme poses: grouping does not automatically preserve a weapon grip or solve IK.
+
+The returned editor supports `select`, `setTransform`, `undo`, `redo`, `reset`, `exportPatch` and `importPatch`. Patches store local X/Y, rotation in degrees and scaleX/scaleY. `setEnabled(false)` disables manipulation while retaining edits; `setVisible(false)` temporarily compares against the unedited pose. Call `dispose()` before destroying the player or scene.
+
+Keep exported `golem.interactive-edits` patches outside the packed `rig.json`/`atlas.png` directory and separate from animation keys. Import validates the format, version, document identity, part IDs and transforms. Saving or downloading belongs to the host UI; do not imply that the module saved a file, uploaded anything, or changed the canonical rig unless that action was actually performed. It does not export a Spine project or bake edits into animation tracks.
+
+Verify selection through transparent pixels, related-part registration, drag/scale/rotation, undo/redo, patch roundtrip and disposal in the real preview. Replay affected actions at normal speed and inspect contacts, seams, clipping and action switches at the intended display size. Alpha picking requires readable same-origin/CORS texture sources; use `alphaFallback: 'geometry'` only as an explicit documented fallback. Report unsupported texture sources or camera setups rather than calling a technically loading preview visually verified.
+
+For editable bone support points and numeric coordinates, use `createInteractiveBoneEditor` from the same entry. It adds local pose offsets before native skinning; it does not rebind artwork or change bind pivots. A direct chain edit may disable that chain's IK, while editing its target or shared ancestor preserves IK. Combine part and bone patches only after validating both; expose an explicit “Apply edits” action when the user wants localStorage persistence. Restore only a matching document identity after reload, and keep failure atomic. Do not replace a request for support-point editing with controls that only move images.
+
+With expression controls (Golem 0.5+), the frame order is animation → manual control inputs → control bindings → bone edits → constraints/skinning → part edits. Bone offsets add to resolved keyforms: a 1.5° head-tilt control plus a 5° bone edit must render at 6.5°. Use `setControls` for control inputs; `onBeforePose` receives resolved output channels. Check animated and manual expressions, reset/hide/dispose, and repeated `refreshPose()` together: offsets must neither disappear nor accumulate. Keep control-driven alpha and mesh deformations active during these checks.