@bitmagic/cli 0.1.65 → 0.1.66-dev.10

package/README.md

@@ -217,7 +217,7 @@ browser reloads itself on every change and the assets panel shows each generatio
 | `bitmagic trailer publish <file.mp4> [--no-attach]` | Upload a trailer (`.mp4`/`.webm`, ≤ 200 MiB, header-checked so a renamed image is refused before upload) to the CDN under `game-media/<gameId>/` and put it at the front of the game page gallery. Re-running replaces the previous trailer (remembered in `.bitmagic/trailer/published.json`); the page is capped at 12 media items. Works before the first publish — the page goes live on the first `bitmagic publish --visibility public`. `--no-attach` uploads only. |
 | `bitmagic forge --prompt "..." [--city\|--dungeon\|--platformer\|--freeform] [--name <name>] [--resume <jobId>]` | Design and bake a whole playable level into `world.json`. Costs sparks, and takes many minutes — the bake alone can take twenty. `--resume <jobId>` picks a failed run back up from the last step that finished, rather than redoing the whole thing. |
 | `bitmagic forge --edit "..." [--level <id or name>]` | Change a detail of a level this project forged — a door style, the light fixtures, a prop — without re-forging it. The stored design is patched and only what the change touches is re-made; the level is replaced in place. See [Editing a forged level](#editing-a-forged-level). |
-| `bitmagic tools <list\|path\|install> [bundle]` | The script bundles the CLI ships for skills that drive Blender or Python (`blender-level`, `unity-import`): what they are, where this install keeps them, and `install` to copy one into the project's `tools/`. Local, no network, no sparks. |
+| `bitmagic tools <list\|path\|install> [bundle]` | The script bundles the CLI ships for skills that drive Blender, Python or Node (`blender-level`, `unity-import`, `metahuman`): what they are, where this install keeps them, and `install` to copy one into the project's `tools/`. Local, no network, no sparks. |
 | `bitmagic levels <list\|add\|rename\|set-start\|remove> ...` | Manage the levels `forge` creates: which one boots, their names, registering a bake you already have, deleting one. Local, no network, no sparks. See **Managing levels** below. |
 
 Every command exits non-zero on failure with a single-line message (no stack trace) and, where a
@@ -531,6 +531,32 @@ before. Without a prior user gesture the browser blocks autoplay, and the engine
 immediately — so the cutscene silently does not run. `engine/agent-docs/video-cutscenes.md` covers
 that and what to freeze while a cutscene plays.
 
+## Spoken lines
+
+`bitmagic generate speech --text "Halt, traveler. You shall not pass."` speaks a line, writes it
+into `world.json` as an audio asset, and prints the `engine.playSound("<id>")` call that plays it.
+Unlike a music bed it is registered as a **one-shot, not a loop** — dialogue plays when something
+triggers it.
+
+`--voice` picks who says it: `narrator` (the default), `male`, `female`, or a raw Eleven Labs
+`voice_id` if you have cloned one of your own. `--model` switches model, and `--stability`,
+`--similarity-boost`, `--style` and `--speed` are passed through to Eleven Labs when you want them;
+leave them alone and Eleven Labs' own defaults apply.
+
+It is **billed per second of audio produced**, not per character of text. A sentence costs about a
+spark. The estimate charged up front comes from the length of the text; what you actually pay comes
+from the finished audio.
+
+Like `generate music`, it can write a file instead of a game asset:
+
+```bash
+bitmagic generate speech --text "Halt, traveler." --out line.mp3 --no-world
+```
+
+`--out` saves the MP3, `--no-world` leaves `world.json` untouched. That pair is the input to the
+MetaHuman lip-sync tool (`tools/lipsync/make_line.py --audio line.mp3`), where a spoken line is
+cut into mouth cues rather than played as-is. Use `--out` on its own to keep both.
+
 ## Reference image
 
 When a game has a strong setting — a tropical island, a neon city — one accepted concept image can
@@ -1198,6 +1224,7 @@ parametric builder produces the model; the engine voxelizes it and derives its p
 
 ```bash
 bitmagic generate vehicle --prompt "a rusty orange pickup with flame decals"
+bitmagic generate vehicle --preset ?              # list the free presets
 bitmagic generate vehicle --preset VAN            # a standard vehicle: skips the designer, free
 ```
 
@@ -1306,6 +1333,15 @@ by the engine's `MeshLevel`. The scaffolded `building-levels-in-blender` skill w
 its first section says when that path applies (a frontier model, and Blender installed) and sends
 everything else to `bitmagic forge`.
 
+## Importing a MetaHuman
+
+An Epic MetaHuman (a UE 5.7 glTF export from the smorchj/metahuman-to-glb pipeline) can be the
+game's playable high-res character without voxelization. The scaffolded `importing-metahumans` skill
+carries the whole path — `bitmagic tools install metahuman` lands the GLB preparation scripts, the
+runtime module (`src/work/metahuman/`), the lip-sync tool and a headless verification rig — and names
+each failure a raw export produces (arms crossed into the chest, a torn shirt, hair left behind by a
+head turn, tinted skin, black eyes) with the fix that resolved it.
+
 ## Art style
 
 A 3D game is voxel-built unless `src/work/game.json` says otherwise:

package/assets/blender-level/find_blender.py

@@ -21,7 +21,9 @@ CANDIDATES = [
 INSTALL_HINT = (
     'Blender was not found. `building-levels-in-blender` builds the level with it — install it '
     '(macOS: brew install --cask blender · Debian/Ubuntu: sudo apt install blender · '
-    'Windows: winget install BlenderFoundation.Blender) and set BLENDER=<path> if it lives somewhere else.'
+    'Windows: winget install BlenderFoundation.Blender) and set BLENDER=<path> if it lives somewhere else. '
+    'If installing it is not an option here, take the forge route instead: `bitmagic forge` builds the level '
+    'without Blender (see the level rows in choosing-asset-pipelines).'
 )
 
 

package/assets/character-rigging/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: rigging-characters
+description: Rig an unrigged character or diagnose and repair a deforming character in local Blender, including skeletal fit, skin weights, hands and optional appendages. Use for GLB character animation problems, not level construction or paid mesh generation.
+---
+
+# Rigging and repairing characters
+
+Produce a reusable animated character whose exported file survives real motion. This is an
+agent-guided workflow, not a universal automatic rigger. It requires local Blender and an agent
+that can inspect rendered images. It uses no paid service, private asset catalog or hosted tool.
+With no visual inspection capability, produce a technical diagnostic and leave visual QA pending.
+
+## Start with a small, explicit workspace
+
+Read the project's AGENTS.md and identify the input GLB or blend file, desired animation clips,
+runtime skeleton constraints and output location. Infer these from the project before asking.
+Copy the source to a per-character work directory; never overwrite the only original. Record its
+SHA-256. Keep the repair profile, scripts, candidate, review images and verdict together there.
+Do not put per-character work inside this shipped skill: GDK upgrade refreshes its files.
+
+Find Blender with `blender --version`, BLENDER_BIN, or the installed application executable
+(macOS commonly `/Applications/Blender.app/Contents/MacOS/Blender`; Windows installations commonly
+live under Program Files/Blender Foundation). Quote paths. The helpers run in Blender's Python;
+they need no pip packages. Check operator availability in the installed version instead of
+assuming all exporters have identical flags. Do not install or switch an engine as a side effect.
+
+Run the bundled helper using its actual location in this skill:
+
+```sh
+blender --background --factory-startup --python-exit-code 1 --python /path/to/rigging-characters/scripts/rig_tool.py -- inspect --input /path/to/source.glb --output /path/to/work/inspect.json
+```
+
+The inspection reports Blender-space bounds, rest bones, actions, materials and skin-weight
+problems. Its `technical_only` result is not a visual approval. Render a baseline with the same
+helper's `render` command; use `--help` for view, frame and named-action options. Inspect front,
+side and back views with both mesh and skeleton visible in Blender when diagnosing placement.
+The helper's default front is Blender -Y; verify the imported character actually faces it.
+
+## Pick the smallest repair that addresses the observed defect
+
+- **No usable rig:** read [new rigs and animation compatibility](references/new-rig.md).
+- **Existing rig, bad motion:** read [diagnosis and targeted repairs](references/repairs.md).
+- **Hands, eyes, tails or wings:** use the relevant section of
+  [secondary articulation](references/articulation.md), only if the task needs it.
+
+Separate source-anatomy errors from skeleton placement, rest-pose mismatch, weight leakage and
+animation/retargeting errors. A good T-pose alone proves none of these. Do not regenerate an
+expensive mesh to solve a joint or skinning defect. Do not replace a custom skeleton with a
+standard one merely to make a tool accept it. Preserve the game's bone-name and clip contract.
+
+Change one causal variable at a time. Keep bind data and mesh rest pose consistent when changing
+bones. For weight-only repairs, preserve positions, topology, UVs, materials and animations;
+normalize after editing, and measure displacement of regions that should stay still.
+
+## Review the exported result, then deliver
+
+Read [verification and runtime handoff](references/verification.md). Reimport the candidate GLB
+into a fresh Blender process and inspect it under the requested clips. Test both left and right
+strides, intermediate phases, idle, and an extreme required motion such as punching or kicking.
+Inspect hands close up during open/fist/grip, not only in a full-body render. Check the actual
+runtime as well when available: bind matrices, coordinate conversion and clip application can
+differ from the authoring scene. Keep numerical and visual verdicts distinct.
+
+Record accepted limitations explicitly. A failed repair remains a candidate; do not relabel a
+passing body stage as a fully approved character while eyes or fingers still fail. If meaningful
+iterations stop improving the result, explain the remaining defect and recommend reconstruction
+or rejection according to the user's tolerance. Do not silently remove defining anatomy.
+
+Report the source and final hashes, skeleton/animation compatibility, changed regions, verified
+motions and remaining limitations. Deliver the candidate GLB and reproducible repair files.
+Publishing or replacing a catalog entry is a separate action governed by the user's instructions.
+
+## Keep work bounded and context small
+
+Load only the relevant reference. Execute inspection/rendering/validation in scripts and read
+compact reports; do not repeatedly paste whole meshes, logs or full project histories. Save the
+current finding and next experiment per character so another agent can resume without the chat.
+Reuse unchanged hash-bound evidence; rerun affected checks and the final integration check after
+a change. Parallel workers need separate outputs and exclusive ownership of each character.
+Separate headless Blender processes can coexist; bound them by available memory and CPU.

package/assets/character-rigging/references/articulation.md

@@ -0,0 +1,55 @@
+# Secondary articulation
+
+## Fingers
+
+Count the actual digits on each hand, including the thumb. Four-digit characters are valid;
+never add an invisible fifth finger just to match a human naming convention. Fit a chain inside
+each separated digit (usually up to three joints); use fewer for short or rigid digits. Parent
+chains to the hand, derive curl axes from the palm plane and each digit's rest direction, and
+calibrate left/right signs separately. The thumb needs opposition as well as curl.
+
+Assign weights by connected anatomy/geodesic neighborhood, not nearest bone alone: adjacent
+fingers are close in space. Keep palm influence at the knuckles and smooth between phalanges.
+Inspect both hands in open, half curl, fist and grip; test punch and walk with fists. Look for
+flipped triangles, stretched strips, palm collapse and thumb penetration. Limit range where
+appropriate and record it. Fused digits may support a grouped paddle, but label that capability
+honestly; independent fingers require geometry that can deform independently.
+
+## Tails and wings
+
+Keep the original appendage as a separate skinned mesh, partitioned at its anatomical root.
+Preserve source materials, UVs and rest alignment. Cap the body opening; when hidden there must
+not be a long stump, hole or stretched strip. Fit enough segments to represent the appendage's
+curvature and intended bend. Parent a tail root to pelvis/hips; wing roots commonly attach to
+chest/upper spine. A four-wing character needs four identifiable chains, not two accidental
+groups. Do not infer movement behavior from bone count; runtime decides cat-tail versus
+crocodile-tail motion. Keep main-body animation from accidentally animating added chains.
+
+Test visible/hidden, root alignment in walking, maximum intended bend/flap and folds. Partition
+fused geometry conservatively: if anatomy cannot be separated without damaging body silhouette,
+leave it unresolved and explain rather than claiming a finished optional attachment.
+
+## Eyes
+
+Preserve separate original-eye objects for a static alternative. Cut at the actual convex eye
+surface/socket boundary, using shape, depth, normals and painted features together. White-only
+selection misses pupils that meet the boundary; a bounding ellipse can cut eyelids and cheeks.
+Do not include the upper socket wall in the pupil surface. Avoid a visibly protruding spherical
+replacement when the original eye is shallow or oval.
+
+An oval fixed eye can move its iris/pupil in surface coordinates or a procedural material while
+keeping geometry stationary. Rotating a stretched sphere distorts the fit. Wet reflections need
+a suitable glossy/clearcoat material and actual lighting/environment in runtime, not a painted
+white dot. Preserve the original pupil style unless asked to change it. Blinking needs eyelid
+geometry/morphs or a carefully fitted mask; gaze support does not imply blink support.
+
+## Metadata handoff
+
+Inspect any existing asset metadata and preserve its schema. Do not invent a Bitmagic engine
+API or assume support merely because GLB extras can store data. For a new contract, provide a
+versioned sidecar manifest and optional mirrored GLB extras with exact object/bone names:
+body nodes, static/dynamic eye nodes, gaze mechanism, material parameters, blink availability,
+hand digit chains/curl axes/ranges, appendage nodes/chains/root parents and default visibility.
+State the coordinate space and angle units. Include a capability as false when unsupported.
+Runtime may need code to hide alternatives, drive eyes or animate added bones; a manifest alone
+does not implement those controls. Keep a usable neutral appearance without custom shaders.

package/assets/character-rigging/references/new-rig.md

@@ -0,0 +1,51 @@
+# New rigs and animation compatibility
+
+## Establish coordinates and anatomy first
+
+glTF uses Y-up; Blender imports into Z-up. Measure in one named space and transform explicitly.
+Report units and the asset's front direction. Do not infer hips from half of the total bounding
+height: hats, antennae, capes and tails distort it. Locate pelvis, leg sockets, knees, ankles,
+shoulder sockets, elbows and wrists from front AND side images. Put joints inside the limb volume.
+Use asymmetric coordinates if the source is asymmetric; do not mirror a bad fit blindly.
+
+Choose an existing compatible project rig/animation as the reference when available. There is
+no skeleton bundled here and no assumed private Mixamo file. Without a reference, construct a
+simple anatomical rig using Blender edit bones: root/hips, spine/chest, neck/head, bilateral
+upper/lower arms/hands and upper/lower legs/feet. Add toes or fingers only when needed. Record
+each bone's parent, head, tail and roll in a JSON profile, in armature-local Blender coordinates.
+Create bones with `armature.edit_bones.new`, assign head/tail, then parents in a second pass.
+Use connected bones only where heads really coincide with parent tails.
+
+For a fresh rig, identity object transforms in a common coordinate space simplify binding. If
+transforms are applied, apply them before binding and verify the visible shape is unchanged.
+Never blindly apply transforms to an already animated skeleton or copy its rest matrices into a
+different coordinate space. Preserve the input and build a new candidate.
+
+Automatic weights (`bpy.ops.object.parent_set(type='ARMATURE_AUTO')`, mesh selected and armature
+active in Object mode) are a starting point. They can fail or leak across touching garments,
+fingers and appendages. Check the armature modifier, actual deform groups, unweighted vertices,
+weight sums and influence count. Diagnose failures rather than exporting an unbound mesh.
+Split semantic accessories before weighting when their topology confuses the body solution.
+
+## Shared clips with per-character skeletons
+
+Custom bone lengths and joint positions can share animation semantics, but identical names are
+not sufficient. Retarget rotations relative to each source and target rest orientation, mapping
+parents in hierarchy order. Keep target rest translations for limb lengths. Treat root motion
+and scale separately; scaling all local bone translations is not a safe retargeting method.
+Validate mapping, missing bones, handedness and rotation order with one diagnostic pose before
+baking a clip. If using world-space rotation deltas, solve each target local rotation from the
+already evaluated target parent; do not apply the source world rotation as a local quaternion.
+
+Do not copy raw quaternion channels between different rest rolls. Bake an evaluated compatible
+action when the target engine cannot reproduce constraints or retargeting. The GLB must carry
+the correct inverse bind matrices for the final rest skeleton. Reimport it and check the same
+poses; Blender constraints and drivers are not an engine contract.
+
+## Rest-pose correction
+
+Wide stance often needs narrower hip-to-ankle placement and rebinding, or a mesh rest correction
+baked with an Armature modifier followed by a new matching rest skeleton. Keep the original
+surface intact as far as possible and inspect the crotch and knees after the change. Moving
+only pose bones does not fix the underlying bind pose. Likewise, an A-pose mesh cannot be bound
+as if it were a T-pose without reconciling the two.

package/assets/character-rigging/references/repairs.md

@@ -0,0 +1,44 @@
+# Diagnose before editing
+
+Use the same camera, clip and phases before/after. First inspect the skeleton overlay; then
+isolate bone rotations and paint weights to distinguish bad pivots from influence leakage.
+
+| Symptom | Check | Typical bounded repair |
+|---|---|---|
+| Feet stay wide during walk | Rest ankle spacing, hip socket positions, imported clip rest convention | Narrow/rest-correct and rebind, or retarget to the real target stance; inspect crotch/knee folds |
+| Palms face forward at idle | Forearm roll, wrist axes, mesh palm normal, source animation convention | Distribute twist along forearm and hand while preserving their alignment; derive sign/angle from geometry |
+| Waist bends as part of thigh | Upper-leg heads too high, pelvis placement, abdomen thigh weights | Lower anatomical leg sockets and move pelvis/garment weights out of the thighs |
+| Arms disappear into torso | Shoulder span, elbow positions, chest/back accessories affecting fit | Fit actual arm sockets; separate cape/feathers from anatomy when calculating weights |
+| Upper back swings sideways | Opposite-arm weights on chest/back, shoulder hierarchy, cape influence | Remove cross-arm influence from the affected region; retain appropriate spine/shoulder motion |
+| Long triangular fans | Sparse topology spanning different moving regions, fused anatomy, sharp weight seam | Smooth a bounded weight transition or separate semantic geometry; do not mask a topological bridge with more weights |
+| Bent wrist while presenting fist | Shoulder/elbow path versus hand orientation | Move the upper arm outward for clearance, rotate forearm around its long axis, keep wrist aligned; overlap transitions |
+
+These are diagnoses to test, not fixed prescriptions. A 90-degree palm correction that worked
+on one mesh can break another with different bone roll. A shoulder pose that clears a jacket
+in one animation is not a structural repair for incorrect jacket weights in every animation.
+
+## Weight edits
+
+Select regions using anatomy plus geometry/material evidence. World-space boxes alone can
+accidentally include a touching hand or back accessory. Inspect front/side/back masks. Work on
+the actual deforming mesh, not a duplicate displayed only in one scene. Keep unmapped vertices
+explicitly flagged. Normalize weights after each change; limit influences to the target engine's
+budget (commonly four), without discarding a necessary influence merely to pass a check.
+
+Weight-only edits should leave vertex positions, faces, UVs and material assignments unchanged.
+Use spatial correspondence with documented tolerance when export duplicates seam vertices;
+vertex indices need not survive GLB re-export. Compare bone influence by name, not numeric joint
+index, because exporters can reorder the joint array. Measure the maximum drift, not only means.
+
+If moving a joint in Edit mode, reconcile the rest pose and bind matrices. Existing animation
+channels may need retargeting/rebaking. First prove bind-pose equivalence, then verify the clips.
+Keep an independent numeric test of regions outside the edit mask. Do not repeatedly widen the
+mask until a local symptom disappears at the expense of the rest of the body.
+
+## Choosing when to stop
+
+Retain failed trials and write why each failed. Set a small initial experiment budget, expand it
+only when the latest trial demonstrates progress. Fused cape/abdomen-to-thigh bridges, missing
+fingers and self-overlapping eye surfaces may require reconstruction beyond a skinning repair.
+Explain that distinction. Minor creases may meet the user's tolerance; collapsed anatomy does
+not become acceptable because technical checks pass.

package/assets/character-rigging/references/verification.md

@@ -0,0 +1,49 @@
+# Verification and runtime handoff
+
+## Technical checks
+
+Verify finite vertices and transforms; valid indices; material/texture availability; a usable
+armature modifier and deform weights; no unweighted skin vertices; normalized nonnegative
+weights; engine influence budget; acyclic bone hierarchy; rest alignment and inverse binds.
+The bundled inspection helper reports common Blender-side issues, not an exhaustive glTF
+validator. Run a glTF validator when available, particularly after editing GLB bytes directly.
+An invalid buffer length must not be ignored just because one viewer tolerates it.
+
+Compare unchanged regions and data against the source. For weight-only work, compare positions,
+UVs, triangles and materials; after topology changes, use bidirectional surface distance and
+texture correspondence with a stated tolerance. Check every intended clip survives export and
+that constraints have been baked when necessary. Never sum cached approvals for different file
+hashes as evidence for the current candidate.
+
+## Visual pass
+
+Use a fresh import of the exported file. Render the same source/candidate poses under neutral
+lighting with front, side and back views, fit the complete animated bounds, and inspect enlarged
+problem areas. Select stages that expose the failure, not only flattering camera angles.
+For ordinary locomotion, sample both strides and intermediate frames; 12 evenly spaced walk
+phases and 12 run phases are a useful baseline, not a universal success threshold. Add idle,
+punch, kick and jump when those clips are actually available/required. Missing clips must be
+reported; procedural joint probes are diagnostics, not equivalent animation coverage.
+
+`rig_tool.py render` can select an imported action and frame. Its actions are Blender import
+names: inspect first. Multi-armature scenes require explicit armature selection for action
+assignment. glTF import may also create NLA tracks; the helper disables these when selecting an
+action so two clips do not blend accidentally. If layered-action slot assignment is ambiguous,
+it stops; select the slot explicitly rather than rendering the wrong pose.
+
+Load the final file in the target runtime if accessible. Test existing shared animations,
+root motion, materials, static/dynamic alternatives, finger controls and hidden appendages.
+Record the loaded hash/URL so a stale cached asset cannot pass the new repair. For KTX2 or other
+texture conversion, compare decoded appearance and confirm the geometry, skin, clips and extras
+remain intact. Texture compression is optional packaging, not a reason to rebuild a passing rig.
+
+## Durable review record
+
+Keep a small JSON or Markdown report alongside the deliverable: input/candidate SHA-256, Blender
+version, units/front direction, diagnosed cause, changes, numeric results and tolerances,
+reviewed image paths and clip phases, runtime checks, limitations, and verdict. Distinguish
+technical_pass, visual_pending, needs_changes and accepted_with_limits. Explicit user rejection
+overrides older approval. Do not replace the production asset until the intended scope passes.
+
+Prefer a compact per-character profile and executable repair over a transcript of experiments.
+This lets the next agent reproduce the result without loading the entire batch history.

package/assets/character-rigging/scripts/rig_tool.py

@@ -0,0 +1,197 @@
+"""Local Blender inspection/render helper. No edits to input files, no network."""
+import argparse
+import hashlib
+import json
+import math
+from pathlib import Path
+import sys
+
+import bpy
+from mathutils import Vector
+
+
+def load_asset(path):
+    if path.suffix.lower() == '.blend':
+        # Never load startup UI/scripts from an asset file.
+        bpy.ops.wm.open_mainfile(filepath=str(path), load_ui=False, use_scripts=False)
+    elif path.suffix.lower() in ('.glb', '.gltf'):
+        bpy.ops.wm.read_factory_settings(use_empty=True)
+        bpy.ops.import_scene.gltf(filepath=str(path))
+    else:
+        raise ValueError('Input must be .blend, .glb or .gltf')
+
+
+def bounds(objects):
+    depsgraph = bpy.context.evaluated_depsgraph_get()
+    points = []
+    for obj in objects:
+        evaluated = obj.evaluated_get(depsgraph)
+        mesh = evaluated.to_mesh()
+        try:
+            points.extend(evaluated.matrix_world @ v.co for v in mesh.vertices)
+        finally:
+            evaluated.to_mesh_clear()
+    if not points:
+        raise ValueError('No mesh vertices')
+    if any(not math.isfinite(x) for p in points for x in p):
+        raise ValueError('Nonfinite evaluated vertices')
+    return [min(p[i] for p in points) for i in range(3)], [max(p[i] for p in points) for i in range(3)]
+
+
+def inspect(meshes, armatures, limit):
+    result = {'technical_only': True, 'coordinate_space': 'Blender world; Z up',
+              'unit_scale': bpy.context.scene.unit_settings.scale_length,
+              'bounds': bounds(meshes), 'meshes': [], 'armatures': [],
+              'actions': [{'name': a.name, 'frames': list(a.frame_range),
+                           'slots': [s.identifier for s in getattr(a, 'slots', [])]}
+                          for a in bpy.data.actions]}
+    for obj in meshes:
+        mesh = obj.data
+        mesh.calc_loop_triangles()
+        rigs = [m.object for m in obj.modifiers if m.type == 'ARMATURE' and m.object]
+        deform = {b.name for rig in rigs for b in rig.data.bones if b.use_deform}
+        groups = {g.index for g in obj.vertex_groups if g.name in deform}
+        unweighted = nonunit = excessive = invalid = 0
+        for v in mesh.vertices:
+            weights = [g.weight for g in v.groups if g.group in groups and g.weight > 0]
+            unweighted += not weights
+            nonunit += bool(weights) and abs(sum(weights) - 1) > 1e-4
+            excessive += len(weights) > limit
+            invalid += any(not math.isfinite(g.weight) or g.weight < 0 for g in v.groups)
+        result['meshes'].append({'name': obj.name, 'vertices': len(mesh.vertices),
+                                'triangles': len(mesh.loop_triangles),
+                                'armatures': [r.name for r in rigs],
+                                'unweighted_vertices': unweighted,
+                                'nonunit_weight_vertices': nonunit,
+                                'excess_influences_vertices': excessive,
+                                'invalid_weight_vertices': invalid,
+                                'materials': [m.name if m else None for m in mesh.materials],
+                                'uv_layers': [u.name for u in mesh.uv_layers]})
+    for rig in armatures:
+        result['armatures'].append({'name': rig.name, 'matrix_world': [list(r) for r in rig.matrix_world],
+            'bones': [{'name': b.name, 'parent': b.parent.name if b.parent else None,
+                       'head_local': list(b.head_local), 'tail_local': list(b.tail_local),
+                       'matrix_local': [list(r) for r in b.matrix_local], 'deform': b.use_deform}
+                      for b in rig.data.bones]})
+    return result
+
+
+def select_action(args, armatures):
+    if not args.action:
+        return
+    rigs = [a for a in armatures if not args.armature or a.name == args.armature]
+    if len(rigs) != 1:
+        raise ValueError('Action selection requires exactly one armature; use --armature')
+    action = bpy.data.actions.get(args.action)
+    if action is None:
+        raise ValueError('Unknown action: ' + args.action)
+    rig = rigs[0]
+    animation = rig.animation_data_create()
+    for track in animation.nla_tracks:
+        track.mute = True
+    animation.action = action
+    slots = list(getattr(action, 'slots', []))
+    if slots:
+        choices = [s for s in slots if s.identifier == args.slot] if args.slot else slots
+        if len(choices) != 1:
+            raise ValueError('Action has ambiguous slots; use --slot from inspection output')
+        animation.action_slot = choices[0]
+
+
+def render(args, meshes, armatures, output):
+    select_action(args, armatures)
+    bpy.context.scene.frame_set(args.frame)
+    # Remove source cameras/lights from rendering only; never save back to source.
+    for obj in list(bpy.context.scene.objects):
+        if obj.type in ('LIGHT', 'CAMERA'):
+            bpy.data.objects.remove(obj, do_unlink=True)
+    lo, hi = bounds(meshes)
+    center = (Vector(lo) + Vector(hi)) * .5
+    extent = max(hi[i] - lo[i] for i in range(3))
+    if extent <= 0:
+        raise ValueError('Degenerate bounds')
+    front = Vector({'-Y': (0, -1, 0), '+Y': (0, 1, 0), '+X': (1, 0, 0), '-X': (-1, 0, 0)}[args.front])
+    direction = {'front': front, 'back': -front, 'side': Vector((-front.y, front.x, 0)),
+                 'three-quarter': (front + Vector((-front.y, front.x, .2))).normalized()}[args.view]
+    camera_data = bpy.data.cameras.new('ReviewCamera')
+    camera = bpy.data.objects.new('ReviewCamera', camera_data)
+    bpy.context.scene.collection.objects.link(camera)
+    camera.location = center + direction * extent * 3
+    camera.rotation_euler = (center - camera.location).to_track_quat('-Z', 'Y').to_euler()
+    camera_data.type = 'ORTHO'
+    camera_data.ortho_scale = extent * 1.35
+    camera_data.clip_start = max(extent / 10000, .00001)
+    camera_data.clip_end = extent * 20
+    scene = bpy.context.scene
+    scene.camera = camera
+    try:
+        scene.render.engine = 'BLENDER_EEVEE_NEXT'  # Blender 4.x
+    except TypeError:
+        scene.render.engine = 'BLENDER_EEVEE'  # Blender 5.x (and 3.x)
+    scene.render.resolution_x = scene.render.resolution_y = args.size
+    scene.render.resolution_percentage = 100
+    scene.render.image_settings.file_format = 'PNG'
+    scene.render.filepath = str(output)
+    scene.render.film_transparent = False
+    world = bpy.data.worlds.new('ReviewWorld')
+    world.use_nodes = True
+    world.node_tree.nodes['Background'].inputs[0].default_value = (.12, .12, .12, 1)
+    world.node_tree.nodes['Background'].inputs[1].default_value = .5
+    scene.world = world
+    for i, offset in enumerate([front * 2 + Vector((0, 0, 3)), -front + Vector((2, 0, 1))]):
+        light_data = bpy.data.lights.new('ReviewLight', 'AREA')
+        light_data.energy = extent * extent * (180 if i == 0 else 90)
+        light_data.shape = 'DISK'
+        light_data.size = extent * 2
+        light = bpy.data.objects.new('ReviewLight', light_data)
+        scene.collection.objects.link(light)
+        light.location = center + offset * extent
+        light.rotation_euler = (center - light.location).to_track_quat('-Z', 'Y').to_euler()
+    bpy.ops.render.render(write_still=True)
+    return {'visual_review': 'pending', 'action': args.action, 'armature': args.armature,
+            'frame': args.frame, 'view': args.view, 'front': args.front,
+            'bounds': [lo, hi], 'image': str(output)}
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('command', choices=['inspect', 'render'])
+    parser.add_argument('--input', required=True, type=Path)
+    parser.add_argument('--output', required=True, type=Path)
+    parser.add_argument('--max-influences', type=int, default=4)
+    parser.add_argument('--action')
+    parser.add_argument('--armature')
+    parser.add_argument('--slot')
+    parser.add_argument('--frame', type=int, default=1)
+    parser.add_argument('--front', choices=['-Y', '+Y', '-X', '+X'], default='-Y')
+    parser.add_argument('--view', choices=['front', 'back', 'side', 'three-quarter'], default='front')
+    parser.add_argument('--size', type=int, default=768)
+    args = parser.parse_args(sys.argv[sys.argv.index('--') + 1:] if '--' in sys.argv else [])
+    source, output = args.input.resolve(), args.output.resolve()
+    sidecar = output.with_suffix(output.suffix + '.json')
+    if source in (output, sidecar) or output.exists() or (args.command == 'render' and sidecar.exists()):
+        raise ValueError('Use a fresh output path; input and existing results are never overwritten')
+    if args.size < 64 or args.max_influences < 1:
+        raise ValueError('Invalid render size or influence budget')
+    digest = hashlib.sha256(source.read_bytes()).hexdigest()
+    load_asset(source)
+    armatures = [o for o in bpy.context.scene.objects if o.type == 'ARMATURE']
+    custom_shapes = {bone.custom_shape for rig in armatures for bone in rig.pose.bones if bone.custom_shape}
+    meshes = [o for o in bpy.context.scene.objects if o.type == 'MESH' and o not in custom_shapes]
+    for shape in custom_shapes:
+        shape.hide_render = True
+    output.parent.mkdir(parents=True, exist_ok=True)
+    result = inspect(meshes, armatures, args.max_influences) if args.command == 'inspect' else render(args, meshes, armatures, output)
+    result.update(source=str(source), source_sha256=digest, blender=bpy.app.version_string)
+    result['excluded_bone_display_shapes'] = sorted(o.name for o in custom_shapes)
+    if hashlib.sha256(source.read_bytes()).hexdigest() != digest:
+        raise ValueError('Input changed during review')
+    target = output if args.command == 'inspect' else sidecar
+    with target.open('x') as stream:
+        json.dump(result, stream, indent=2)
+        stream.write('\n')
+    print(json.dumps({'report': str(target), 'source_sha256': digest}))
+
+
+if __name__ == '__main__':
+    main()

package/assets/character-skin-authoring/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: character-skin-authoring
+description: Use vision to author and review exposed-skin maps on textured 3D characters, including faces, hands and bodies. Prepare exact model views, annotate visible anatomy, project evidence into UV space, and review skin detail placement. Eye construction is a separate workflow.
+---
+
+# Vision-led character skin authoring
+
+The local agent makes anatomical/material decisions from images. Do not replace those decisions with RGB thresholds, world-height cutoffs, race/name rules, or another automated classifier. Deterministic tools handle projection and bookkeeping. The creator's existing agent subscription supplies vision; this workflow requires no hosted segmentation service.
+
+## Establish evidence
+
+Locate the model, its physical height, materials, texture resolution and rig. Keep the original immutable and write a separate material revision. Inspect the original generated image when available, but make the **actual mesh and its textures** authoritative: the generated mesh may differ from that image.
+
+Use the local `scripts/skin_views.py` helper to create unlit, occlusion-correct views with their UV correspondences. Read [the projection contract](references/projection.md) for commands and formats. It requires local Blender and a Python environment with NumPy/Pillow. The helper performs no semantic recognition. Verify orientation from the resulting images; its axes are not anatomical labels.
+
+Start with a full-body survey from opposite directions. Then frame each exposed region closely enough to see its boundaries. Inspect the face from front and both sides; inspect both hands from palm and dorsal sides and oblique angles showing finger webs. Inspect ears, neck, chest, arms, legs, feet or any other exposed region actually present. Add cameras when existing views cannot show a surface. Do not infer a hidden palm from a dorsal hand image or project a front silhouette through to the back.
+
+## Author the maps using vision
+
+For each viewed surface, annotate pixel polygons as `skin`, `dorsal_hand`, `palm`, `sole`, `lips`, `eyes`, `hair`, `nails`, or `non_skin`. `unknown` is explicit unresolved evidence. Use separate polygons for exclusions, ordered after enclosing polygons. Do not give an indistinct nail facial pores merely because the rest of the hand is clear. Record why a boundary is ambiguous; obtain a closer/different view before resolving it. Scars, freckles, tattoos and makeup usually remain skin with appearance annotations, not separate non-skin regions. Tight cloth is still cloth; green skin is still skin. If garment colour spills onto anatomically visible skin in the source albedo, record a texture defect separately from the semantic mask. A correct skin label cannot repair that colour.
+
+Review the colored annotation overlay on the **same source image**, then review the **baked atlas reprojected onto every prepared view**, including unannotated side views. Use the dense visibility bake at a resolution appropriate to the source atlas; sparse splatting is a diagnostic, not a finished mask. Include the filename, image dimensions and source hash with every annotation set. If a tool displays a resized image, convert coordinates back to the recorded dimensions. Never claim to have visually reviewed an image you have not opened.
+
+The helper deliberately leaves unobserved UV texels unknown and reports contradictory labels. Do not grow a skin mask across unknown areas to make a coverage statistic look good. Get additional views, increase sampling resolution, or use a reviewed Blender texture-paint correction. Mirrored/overlapping UVs can make conflicting anatomical labels impossible in one atlas: document that and create separate material/UV regions rather than average the labels.
+
+## Apply region-appropriate detail
+
+For material application and engine integration, read [material application](references/materials.md). The [installed exporters](references/exporters.md) assemble reviewed inputs in an explicit external workspace. After coverage passes review, register landmarks and surface scale for each detail patch. Use licensed exemplars and retain attribution and modification provenance. The b3662 face pilot in this repository demonstrates registered scan detail; its coordinates are **not** a universal face template.
+
+- Face: region-specific pores, fine relief, oiliness and pigment. Exclude eye surfaces, lashes, brows, lips and facial hair from the ordinary pore layer; preserve actual folds and identity.
+- Dorsal hands/fingers: knuckle folds, tendons and finer hand texture. Nails receive their own response.
+- Palms/soles: glabrous skin with appropriate creases/ridges and roughness; do not stamp facial follicles onto it.
+- Neck, torso, limbs, ears: use suitable regional detail and scale. Preserve the character's natural variation; do not transplant a donor's beard, identity marks or complexion.
+
+Blend patch boundaries in surface space and check physical scale. A silhouette or clothing boundary needs a coverage edge; two adjacent skin patches need a continuous transition. Keep skin nonmetallic and preserve clothing/armor materials. Use the existing registered detail/SSS renderer where available; do not invent new renderer hooks or claim the projection helper installs materials by itself.
+
+## Review and handoff
+
+Inspect colored material regions and final shaded results separately. Use fixed cameras under diffuse, specular, side, studio and back lighting. Check full-body, face-sized and close detail views, plus a representative pose when the model is rigged. Confirm both hands, finger webs, nails, ears and every other exposed area; inspect clothing edges without revisiting unrelated deferred edits.
+
+Record results per character and region: `reviewed`, `needs_view`, `conflict`, or `needs_detail_asset`. Archive source hashes, views, annotations, projected labels, atlas registration, licenses and review images together. Only call a character complete when its exposed regions are reviewed and the **applied** maps have been inspected. A parseable annotation file or a successful bake is not semantic validation.
+
+Review the face and ocular exclusion before eye geometry/shading work; use the separate [optical-eye workflow](references/eyes.md) when that work is requested. Eye progress does not mark unresolved body skin as complete. This workflow is maintained in the GDK CLI assets and installed into supported agent skill directories from the same source. Keep per-character evidence and candidates outside those refreshed directories.