@hypersoniclabs/helix-mcp 0.2.5 → 0.2.12

package/docs/catalog.md

@@ -1,4 +1,4 @@
-# Platform catalog — systems, abilities, asset-packs
+# Platform catalog — packages and Vault assets
 
 HELIX Instant publishes reusable **packages** that worlds consume, distinct from worlds themselves:
 
@@ -21,6 +21,74 @@ HELIX Instant publishes reusable **packages** that worlds consume, distinct from
 3. The response also carries `codeBaseUrl` (the downloadable code) and `assetBaseUrl` (the CDN the
    code streams animations/textures from). Assets are never embedded in a consumer's bundle.
 
+## Vault assets
+
+Vault is the durable resource catalog for things a world composes: `prop`, `character`, `animation`,
+`audio`, `texture`, `material`, `environment`, `terrain`, `vfx`, `decal`, `sky`,
+`gaussian_splat`, `scene`, `interactive_item` (an executable definition: subtype `emote` for a global
+emote, or a weapon/other interaction — see `read_doc({ name: "shooter-worlds" })`), and
+`unreal_package`. Raw reusable emote motion remains kind `animation`; the executable, ownable wrapper
+is `interactive_item` with subtype `emote`. A URL is a resolved rendition; the UUID
+returned as `assetId` is the handle a world or agent keeps.
+
+Use this ladder:
+
+1. `list_materials` for the small platform-default surface palette, then `use_material` for one
+   material's map URLs. Both take an optional `resolution` (e.g. `"1k"`, `"2k"`; `1024`/`2048` are
+   accepted aliases) to pick which texture resolution you get; omit it for the material's default.
+   The output names the resolved resolution and every one the material offers. A resolution the
+   material does not carry is an error listing the valid values — it is never silently swapped for
+   a different one, so a `2k` request that returns `1k` maps cannot happen. Only photographed or
+   scanned materials are offered: procedural glass and water are not, the listing names them under
+   `unlisted`, and `use_material` on one is an error saying why. Apply a material with the visual
+   system (`read_doc({ name: "world-look" })`), using the `assetBaseUrl` in `use_material`'s output.
+2. `search_assets` with typed filters. For a browser world, normally include `engine: "web"`.
+   Add `origin: "generated"` when the trust boundary matters, and `official: true` to narrow to the
+   platform-vouched tier first (widen only when it has no fit). Each result carries separate
+   `selectionExplanation` components for lexical matches, hard filters, measured performance,
+   observed reuse, and unavailable signals. Do not collapse those into an invented score.
+3. `get_asset` for the complete typed metadata and resolved artifact; `list_asset_versions` for
+   immutable history; `track_asset` for observed world use.
+4. `install_asset` to download the served version and related artifacts into the world. The CLI
+   verifies SHA-256 and byte count before writing `public/helix.assets.json`. For materials,
+   `materialRenditions` defaults to `runtime` (lean KTX2 maps); choose `source` for editable PNG
+   maps or `all` only when both families are required. Non-material installs are unchanged.
+5. **USE the installed artifact according to its kind — install alone renders nothing.** Props and
+   characters need the world's KTX2-aware GLB loader before `scene.add`. Animations are reusable
+   clips: bind them to a compatible character with `THREE.AnimationMixer`; never `scene.add` an
+   animation. An `interactive_item` is a descriptor, not geometry. A subtype `emote` wrapper that is
+   published as a global owned emote is inventory-driven and should not be manually installed into a
+   world. There is currently no public `loadVaultAsset`/`listVaultAssets` helper; do not import one.
+
+For emotes, use two explicit discovery queries:
+
+- reusable motion for a generic world: `search_assets({ kinds: ["animation"], skeleton: "humanoid" })`
+- executable/ownable global emotes: `search_assets({ kinds: ["interactive_item"], subtype: "emote" })`
+
+The wrapper metadata says `joinMode` (`partner`, `sync`, or `none`), playback, participants, roles,
+phases, authored alignment, portability, and ownership requirements. A collectible changes who may
+equip/initiate it; a nearby participant may still join without ownership.
+6. Generate only when search found nothing appropriate. `start_asset_generation` returns a job id;
+   record it and call `poll_asset_generation` instead of starting another job after a disconnect.
+
+Generation routes remain explicit:
+
+- Prop and character use main Dreamer because their final artifact passes the universal-item mesh
+  lane.
+- Image, material, audio, and Gaussian splat use the shared asset broker. Materials are validated
+  PBR bundles (1K default, explicit 2K), and splats declare `object` or `environment`.
+- Animation generation is unavailable and fails before a chargeable job is created. Search for or
+  upload a skeleton-gated animation instead.
+
+For text-to-speech, call `list_voices` before `generate_audio`. Choose a returned voice id and one
+of its supported language codes; follow `pageInfo.nextPageToken` for more results. HELIX exposes
+only safe selection metadata and previews, never vendor credentials, cloning, or voice
+administration.
+
+A successful default-on job reports `vaultAssetId` and `vaultAutoPublish: "published"`. An explicit
+creator preference can return `"disabled"`. Provider/deployment absence is an error, never a
+placeholder success.
+
 ## What you cannot do here
 
 Publishing systems/abilities/asset-packs is **internal/first-party only** — there is no publish tool

package/docs/character-animation.md

@@ -0,0 +1,442 @@
+# Character animation — author gestures as JSON (the pose DSL)
+
+Read this only when a world needs CUSTOM character animation. Most worlds never do: the humanoid-character
+system already ships locomotion, jumps and the standard emote set. Reach for the pose DSL when you want a
+gesture the platform does not provide — a wave, a salute, a world-specific ritual — without exporting a GLB.
+
+Worlds define and play their own character gestures as **JSON keyframe poses** — no GLB export, no
+platform publish. Registration validates everything at once; playback replicates by default in
+multiplayer (see the multiplayer-world doc — oneshots relay, loops sync so late joiners see them).
+
+**Prerequisite — the world's INSTALLED humanoid-character must be ≥ 0.2.12** (where the gesture DSL was
+added). On a world you did not scaffold this session, run `check_for_updates({ projectDir })` FIRST: an
+older install shows as in-range-stale, and the fix is just `install_world_packages` + rebuild — any
+existing `^0.2` pin already allows 0.2.12, so no helix.json edit is needed. For gestures to REPLICATE
+(not just play locally) the same check also flags a stale project SDK — update it and rebuild too.
+Compile-time `ik` keys and runtime IK (both below) need **≥ 0.2.15**: on an older install an `ik` field is
+silently ignored when the key also has `bones`, so the tools refuse it with a version message — same fix,
+`install_world_packages` + rebuild. **After any install that moves the system version, RESTART the dev
+server and this MCP session** — a running process keeps serving the previously loaded module, which reads
+as "ik keys don't evaluate" long after the upgrade. Prefer **≥ 0.2.18** for `ik` authoring — each older
+tier has a known, fixed solver defect that upgrading beats hand-tuning around: 0.2.15 rolls the forearm
+on chest-front goals (no humerus roll); 0.2.16–0.2.17 mangle DEEP elbow folds (close-to-shoulder / sip
+range: `[±160, −80s, ∓160]` eulers + clamp warnings + an off-target hand) and silently ignore `item`
+intents. The tools gate `item` on the installed system's capability.
+
+## SCOPE — what this tool is and is not for (read before you start)
+
+This is for **short, simple, upper-body-led motion**. It is NOT an animation authoring suite, and trying to
+build complex full-body choreography with it wastes a lot of your effort for a poor result.
+
+**Good fits — these land quickly, often first try:**
+
+- Player actions: wave, salute, point, sip, knock, throw a lever, offer an item.
+- Tool and weapon actions: a mining swing, a one-handed melee strike, a chop, a hammer blow.
+- Stances and held poses: hurt/clutching, carrying, cold/shivering, slumped, alert.
+- One-shot accents: nod, shrug, flinch, headshake, recoil, a wince.
+- Additive overlays that ride locomotion: a limp, a hunch, a drunken sway, a breathing idle.
+
+**Bad fits — do NOT attempt these here:**
+
+- **Dances.** Real choreography needs weight transfer, footwork and full-body timing; it is normally
+  motion-captured. A simple 4-beat arm routine is reachable, anything more is not.
+- **Fight choreography and acrobatics** — combos, spins, ninja jumps, rolls, flips, sweeps.
+- **Anything where the feet must step, plant, pivot, or leave the ground.**
+- **Anything needing the character to travel through space.**
+
+**Why, concretely — these are hard limits, not tuning problems:** a gesture is *bone rotations only*,
+layered over the locomotion system. There is **no root motion** (the character cannot move), **no foot
+planting or leg IK** (feet slide or float if you rotate the legs), and **no weight shift**, because the
+locomotion graph owns the lower body. (The arm `ik` keys below solve HAND placement — they change none of
+this.) Add that joint-space posing has no notion of balance, and a convincing dance or fight move is
+simply outside what the format represents.
+
+**The signal you have gone too far:** you are keying legs *and* arms *and* torso to hit the same beat, you
+are past ~6 keys of full-body coordination, or you are on your third visual iteration and it still reads
+wrong. Stop and pick a different approach.
+
+**What to use instead:** the platform's shipped locomotion and emote clips, or an authored/motion-captured
+GLB clip. Text-to-animation generation is planned as a separate API for exactly this gap — when a world
+needs a real dance or fight move, that is the route, not this DSL.
+
+## Put each clip in its OWN .json file — never inline them in world code
+
+**This is not a style preference.** A single clip runs to 100–300 lines of bone values; three of them inlined
+in `main.ts` triples the file and buries the world's actual logic in coordinate soup. Worse for you: every
+later edit to that file forces you to re-read poses you are not touching, so a one-line gameplay change
+costs you the whole gesture library in context. Keep them out of the way:
+
+```
+src/
+  main.ts                    ← stays about the world
+  gestures/
+    wave.json
+    hurt-belly.json
+```
+
+```js
+import wave from './gestures/wave.json';
+import hurtBelly from './gestures/hurt-belly.json';
+
+for (const clip of [wave, hurtBelly]) mp.registerAnimation(clip);
+```
+
+Vite inlines the JSON at build, so this costs nothing at runtime. When you iterate on a pose, you edit ONE
+small file and re-read only that, and `inspect_gesture` measures that file directly — no build required.
+The `multiplayer-hangout` template does exactly this.
+
+The worked one-shot, `gestures/wave.json`. Solved by MEASUREMENT, not by eye: `upperarm x=-60` puts the
+elbow's swing plane frontal, so the elbow hinge alone sweeps the hand sideways with no vertical drift;
+shoulder+clavicle add a smaller same-direction swing and LEAD by 50 ms via their own key times, so the chain
+overlaps instead of snapping together. Fingers key BOTH knuckle rows (`*_01` + `*_02`) — unkeyed fingers
+keep the rig's rest curl and read as a half-fist:
+
+```json
+{
+  "name": "wave", "duration": 1.6, "play": "oneshot", "compose": "override", "mask": "rightArm",
+  "keys": [
+    { "t": 0, "ease": "ease", "bones": { "clavicle_r": [0,0,0], "upperarm_r": [0,0,0], "lowerarm_r": [0,0,0], "hand_r": [0,0,0],
+      "index_01_r": [0,0,0], "index_02_r": [0,0,0], "middle_01_r": [0,0,0], "middle_02_r": [0,0,0], "ring_01_r": [0,0,0],
+      "ring_02_r": [0,0,0], "pinky_01_r": [0,0,0], "pinky_02_r": [0,0,0], "thumb_01_r": [0,0,0], "thumb_02_r": [0,0,0] } },
+    { "t": 0.3, "ease": "ease", "bones": { "clavicle_r": [0,0,15.5], "upperarm_r": [-60,0,28] } },
+    { "t": 0.35, "ease": "ease", "bones": { "lowerarm_r": [0,-88,0], "hand_r": [-10,0,0],
+      "index_01_r": [0,-12,0], "index_02_r": [0,-5,0], "middle_01_r": [0,-12,0], "middle_02_r": [0,-5,0], "ring_01_r": [0,-12,0],
+      "ring_02_r": [0,-5,0], "pinky_01_r": [0,-12,0], "pinky_02_r": [0,-5,0], "thumb_01_r": [0,-25,0], "thumb_02_r": [0,-5,0] } },
+    { "t": 0.6, "ease": "ease", "bones": { "clavicle_r": [0,0,12.5], "upperarm_r": [-60,0,22] } },
+    { "t": 0.65, "ease": "ease", "bones": { "lowerarm_r": [0,-52,0] } },
+    { "t": 0.9, "ease": "ease", "bones": { "clavicle_r": [0,0,15.5], "upperarm_r": [-60,0,28] } },
+    { "t": 0.95, "ease": "ease", "bones": { "lowerarm_r": [0,-88,0] } },
+    { "t": 1.2, "ease": "ease", "bones": { "clavicle_r": [0,0,12.5], "upperarm_r": [-60,0,22] } },
+    { "t": 1.25, "ease": "ease", "bones": { "lowerarm_r": [0,-52,0], "hand_r": [-10,0,0],
+      "index_01_r": [0,-12,0], "index_02_r": [0,-5,0], "middle_01_r": [0,-12,0], "middle_02_r": [0,-5,0], "ring_01_r": [0,-12,0],
+      "ring_02_r": [0,-5,0], "pinky_01_r": [0,-12,0], "pinky_02_r": [0,-5,0], "thumb_01_r": [0,-25,0], "thumb_02_r": [0,-5,0] } },
+    { "t": 1.6, "ease": "ease", "bones": { "clavicle_r": [0,0,0], "upperarm_r": [0,0,0], "lowerarm_r": [0,0,0], "hand_r": [0,0,0],
+      "index_01_r": [0,0,0], "index_02_r": [0,0,0], "middle_01_r": [0,0,0], "middle_02_r": [0,0,0], "ring_01_r": [0,0,0],
+      "ring_02_r": [0,0,0], "pinky_01_r": [0,0,0], "pinky_02_r": [0,0,0], "thumb_01_r": [0,0,0], "thumb_02_r": [0,0,0] } }
+  ]
+}
+```
+
+```js
+import wave from './gestures/wave.json';
+mp.registerAnimation(wave);           // → { warnings } ; throws with EVERY issue listed at once
+mp.playAnimation('wave');             // local player, replicated by default
+mp.playAnimation('sway', { loop: true }); // synced loop — late joiners see it
+mp.stopAnimation();                   // fade out + clear the replicated loop
+```
+
+The rules that make gestures work:
+
+- **Every value is REST-RELATIVE**: `[x°, y°, z°]` Euler degrees, composed twist-first (internally 'ZYX' —
+  X applies first, so the swing carries the twist), and `[0,0,0]` = the character's rest
+  pose (a relaxed A-pose, arms ~55° down) for EVERY bone in BOTH modes. `compose: "override"` replaces
+  the animation on keyed bones (mask required — it is the conflict unit: a new override fades out any
+  overlapping one); `compose: "additive"` stacks deltas on top of whatever plays (nod over walk).
+  Unkeyed mask bones keep the underlying animation. Twist bones cannot be keyed.
+- Masks: `upperBody`, `lowerBody`, `leftArm`, `rightArm`, `spine`, `armsHead` — also usable as `overrideMask`
+  to mix compose modes in one clip (below). Caps: ≤ 24 keys, ≤ 10 s,
+  names `[A-Za-z0-9][A-Za-z0-9_\-.:]*` ≤ 64. `ease` per key: `linear` | `ease` | `hold` (toward the
+  next key); loops wrap last→first continuously.
+- **Trigger from input/interaction handlers** (they run only on the acting player), never from
+  replicated-state observers (they run on every client — everyone would gesture).
+
+**The axis reference — read it with `gesture_axis_table`, do not guess.** Every bone group has a verified
+human-terms meaning per Euler axis plus an advisory natural range; outside that range the compiler WARNS
+(still compiles) because that is where poses start looking broken. **A warning means "look at this", not
+"wrong"** — the ranges were validated by grid-searching a real gesture against measured criteria: the
+unconstrained best `upperarm_r x` was −70, and clamping to the natural −60 cost 1.7% of pose quality while
+the range still correctly rejected the far tail. Stay inside them unless measurement says otherwise.
+
+The table is NOT reproduced here on purpose — it lives in one place, the character system itself, so what
+you read is what YOUR pinned version actually lints against. Two ways to get it, no shell needed:
+**`gesture_axis_table({ world })`** for the whole table (call it BEFORE picking rotation values — guessing
+costs a revise cycle per bone), and `inspect_gesture` prints the rows for the bones your clip keys alongside
+every warning, which is when you need them again.
+
+The shape worth memorising: **X twists along the bone; −Y is the "bend" family (elbow, knee, bow, nod);
++Z is the lateral plane (raise, split, tilt, shrug)**. Same values on `_l`/`_r` bones = mirrored motion.
+And the rule that overrides all of it: **these meanings hold FROM REST ONLY.** Rotations chain, so once a
+parent has rotated, a child's "raises the arm" axis points wherever the parent carried it — that is what
+`inspect_gesture` with `axes: true` measures, and why a value that "should" work sometimes does not.
+
+**Worked MIXED example — `hurt-belly`** (loop 1.2 s, `compose: 'additive'` + `overrideMask: 'rightArm'`):
+the bow rides the locomotion while the arm ignores its swing. Fist clutched across the abdomen, head
+down, spine bowed, slow wince. `spine_02/_03 [0,−12,0]`, `neck_01 [0,−10,0]`, `head [0,−25,0]`,
+`clavicle_r [0,−8,0]`, `upperarm_r [60,−10,−20]`, `lowerarm_r [0,−60,0]`, fingers fisted (`*_01 y 75..78`,
+`*_02 y 82..88`, `thumb_01 [0,40,0]`); deepen everything ~3–5° at t=0.6 and let the loop wrap back.
+Measured: forearm near-horizontal across the body, hand ~4 cm clear of the belly, fingertips closed 50–60%,
+face 59° below horizontal. Composes over `walk` — legs keep striding, the torso bow rides the walk, the fist stays put.
+
+Practical recipes: arm overhead ≈ `upperarm z 145`; hanging at the side ≈ `z −35`; hand-to-mouth (mug hold)
+≈ `clavicle [0,−10,0]` + `upperarm [−15,−35,5]` + `lowerarm [0,−108,0]` + `hand [0,0,40]` + curled fingers;
+sit ≈ `thigh [0,90,0]` + `calf [0,−90,0]`; bow ≈ distribute across the spine (`spine_02/_03 [0,−20,0]` each —
+never one bone at −40) + `head [0,−50,0]`.
+
+**Timing and structure — the rules that bite on ACTIONS (tool swings, strikes, gestures):**
+
+- **A one-shot and a loop of the same action are DIFFERENT clips.** A one-shot must start AND end at rest,
+  or it snaps when it finishes. A loop must contain NO rest pose, or the character returns to neutral
+  between repetitions and the action stutters. Do not play a one-shot on loop and expect a repeating
+  action: author the loop separately, keeping the same poses and timings and dropping the rest bookends —
+  the wrap segment (last key back to the first) carries the recovery.
+- **Punch comes from key SPACING, not from `hold`.** `hold` means "do not interpolate to the next key", so
+  across a large movement it TELEPORTS. Give the strike a short segment (0.12–0.16s) and the recovery a
+  longer one (0.3s+); keep `ease` throughout. Reserve `hold` for small accents and for freezing a grip
+  through a dwell.
+- **A swing needs the TORSO, not just the arm.** Coil the spine one way in the wind-up and uncoil it
+  through the strike (`spine_02/_03` x, ±15–20), with the other arm counter-swinging. An arm swinging alone
+  reads as a flail.
+- **Two-handed grips: author BOTH hands as `ik` goals on the implied handle, then CHECK THE SPACING.**
+  Give each hand a position goal a fixed offset apart along the handle instead of placing two independent
+  joint-space arms and hoping they meet. The verification still stands: measure hand-to-hand distance at
+  EVERY key; it must stay roughly constant or the handle visibly stretches. The shipped pickaxe swing holds
+  20.6 / 21.5 / 17.8 cm across wind-up, strike and follow-through.
+
+**Composition is where authoring fails — respect these rules:**
+
+- **ROTATIONS CHAIN — the table is only valid near rest.** The biggest trap, and the reason blind authoring
+  fails. Every axis meaning was probed with the parents at bind pose; once a parent rotates it carries the
+  child's frame with it, so "raises the arm out/up" or "waves the fingers inward" mean *different world
+  motions* at a posed shoulder. A value that was right at rest is wrong the moment anything above it moves.
+  **Never author a large multi-joint pose from the table alone — measure the posed chain** (tooling below).
+  Measured examples, all counter-intuitive:
+  - Rest is an **A-pose, arms down and slightly forward**, so `upperarm_r z ≈ 100` ("raise out/up") carries
+    the arm up *and backward* and parks the hand behind the head — invisible head-on, obvious from the side.
+  - At a ~95° raise the forearm **cannot be made to point up by twist at all** (swept the full 360°: best
+    vertical component 0.03). Elevation must come from the upper arm, not from folding the elbow.
+  - `hand_r` rotations **do not move the wrist position**, only its orientation — probe a fingertip. To
+    MOVE the wrist, use an `ik` key (below): a position goal is exactly what that is for.
+- The table is exact only near rest and per-axis. Values COMPOSE (twist first, then Y, then Z): a raised
+  arm's **elbow-fold plane and palm** end up wherever the composition puts them — tune the upperarm X twist
+  *at the raised pose* until the elbow pit and palm face the intended way (not predictable from the table).
+- **Move the CHAIN, not one joint** — a single-joint sweep reads robotic. Give neighbouring joints a smaller
+  same-direction contribution (verify the sign; it is often counter-intuitive) and their **own key times,
+  30–60 ms ahead** of the driving joint so the motion overlaps through the chain. Amplitudes shrink as you
+  move away from the driver. Worked example: the wave is **elbow-driven** (a real wave pivots at the elbow),
+  with the shoulder and clavicle adding ±3/±1.5 and leading by 50 ms.
+- **Open hands must key the fingers.** Unkeyed fingers keep the rig's rest curl and read as a half-fist;
+  extend with negative Y (`*_01 y −12`, `*_02 y −5`, `thumb_01 y −25`).
+- **Shoulder girdle participates**: raises past horizontal add `clavicle z +10..15`; forward reaches add
+  `clavicle y −10..15` — without it the shoulder looks dislocated.
+- **Sparse tracks**: a bone interpolates between its OWN keys — to hold it still while others move, repeat
+  its value at the end of the hold (see the wave's fingers, repeated at t=1.25), or it sags.
+- Head/spine/finger/leg gestures land first-try; **arm poses with position/orientation intent take 2–3
+  visual rounds in joint space — author those with `ik` keys instead (next block).** Either way, verify
+  close-up from the FRONT and the SIDE (forward-lean hides frontally), checking the palm and elbow-pit
+  directions specifically, and play it in motion before shipping.
+
+**Position-intent arm poses: author the GOAL with an `ik` key, not a joint-space search (≥ 0.2.15).**
+When a key's intent is "hand HERE, palm facing THAT" — touch the face, plant a hand on a rail, meet a
+handle — state it directly and let registration solve the rotations:
+
+```js
+{ "t": 0.9, "ease": "hold", "ik": { "hand_r": { "position": [-0.05, 1.55, 0.14], "palm": "back", "elbow": "down" } } }
+```
+
+- `position` is CHARACTER-space meters (+x = the character's left, y up from the feet, +z forward). `palm`
+  hints the facing (`inward|outward|up|down|forward|back`); `elbow` the fold (`down|out|up` — omit for the
+  adaptive default, which wings cross-body reaches naturally). Both hands can carry goals in one key.
+- **Holding a prop? Orient the ITEM, not the palm (`item`, ≥ 0.2.18).** The grip socket is the item frame
+  (+y = the item's up, +z = where it points): `item: { up: 'up' }` carries a mug level,
+  `item: { up: [0, 0.7, -0.7] }` tips it toward the mouth for a sip, `item: { point: 'forward' }` aims a
+  beam/tip. One axis per goal (direction word or character-space vector); mutually exclusive with `palm`
+  (both drive the wrist). The solve puts natural forearm pronation (≤30°) into the roll and the wrist
+  takes the rest, guard-capped. Verify with the `up=`/`itemUp` readouts — palm hints are TOUCH semantics
+  and cannot express "keep the cup level"; probing them for that is wasted turns.
+- **When ik fights you, drop to joint space — that is the design, not a workaround.** ik states simple
+  intent (hand here, palm there, item level); an exact articulation you already know is a `bones` euler
+  key, and an ik `position` WITHOUT palm/item leaves `hand_*` free to euler-key in the same key. Mixing
+  the two in one key is the intended authoring style.
+- **Reachable envelope (canonical rig):** each shoulder joint sits ≈1.44 m up and 0.19 m off center; the
+  arm chain is 0.278 m (upper) + 0.273 m (forearm) = **0.55 m shoulder→wrist**. A goal farther than that
+  from the shoulder cannot land — the solve clamps and `inspect_gesture` warns with the cm shortfall.
+  Useful heights: hips 0.96, chest 1.35, shoulders ≈1.44, chin ≈1.55.
+- **`position` places the WRIST (the `hand_*` bone origin), not the fingertips.** The hand extends ≈15–19
+  cm beyond it (curl-dependent; palm center ≈7 cm). To touch a surface with the fingers, author the goal
+  ≈10–15 cm short of the contact point — a goal ON the surface buries the hand in it.
+- Solved ANALYTICALLY at registration into ordinary joint keys — deterministic, so every client compiles
+  the identical clip; playback and the wire never know ik existed.
+- Rules: an ik-solved bone must be override (compose `override`, or inside `overrideMask`), must sit in
+  the mask, and a bone cannot be euler-keyed AND ik-solved in the same key. Author the key's OTHER bones
+  (torso lean, fingers) first — the solve runs against them, so a spine bend is compensated for free.
+- The numeric loop is closed for you: `inspect_gesture` prints an **ik goals** section — the target, the
+  resolved joint eulers, and where the hand actually LANDS with its cm error — plus a `hands:` landmark
+  line per frame; out-of-reach targets and joint-limit clamps warn with `keys[N].ik` labels. Expect
+  first-try landings.
+
+**Measure first, look second — and never trust one camera angle.** Screenshot-guessing an arm pose costs
+~8 rounds even with vision; measuring got a full-body additive pose right in zero. `inspect_gesture` runs the real compiler and player against the real rig and
+reports where the bones actually landed. Three modes, one per question you cannot see the answer to:
+
+```
+inspect_gesture({ clip, world, t: [0.35], bones: ["hand_r"] })   → where the bones ARE (+ palm/finger facing)
+inspect_gesture({ clip, world, motion: true,                     → what the clip DOES over time
+                  motionWindow: [0.35, 1.25] })
+inspect_gesture({ clip, world, axes: true, probe: "hand_r" })    → what each keyed axis does AT this pose
+```
+
+- **`t`** — per bone: world position, direction down the bone, landmark English ("0.08m above head, 0.28m
+  to the character-right, 0.14m in front, points up"), plus **palm/finger facing** for hands.
+- **`motion`** — path extent split lateral / vertical / depth, dominant axis, purity, reversals. **A static
+  frame cannot show this.** It is what catches a gesture moving along the wrong axis: the broken wave read
+  *"0.14m front-to-back"*, the fixed one *"0.21m side-to-side"*. Always pass `motionWindow`, or the
+  rest→pose→rest travel swamps the gesture itself.
+- **`axes`** — for each keyed axis, the world motion a `+10°` edit produces **at the posed chain**: the
+  question the table cannot answer. Use it to find which axis does what you want BEFORE guessing values.
+
+The inspect tools deliberately contain **no goal-seeking search** — they report measurements and never
+judge. The sanctioned solver is the `ik` key above: analytic, at registration, for hand-position goals.
+Hand-roll a search over the returned numbers only if a gesture needs something beyond that.
+
+**The measure-first recipe** (this authored a full-body additive pose in ZERO visual rounds). Do not write a
+clip, call it done, and hand it to a human to judge — that costs them a round trip per mistake and they
+cannot tell you WHY it is wrong.
+
+**The order is a rule, not a preference: measure until the numbers are right, THEN look, THEN hand it over.**
+Steps 0–6 are `inspect_gesture` and cost milliseconds; step 7 is `capture_gesture` and costs a browser launch.
+Looking first wastes the expensive call on a clip whose problems the numbers would have named for free.
+
+0. **Compile it before anything else.** `inspect_gesture({ clip, world })` returns compile errors and
+   natural-range warnings, each quoting the axis meaning. A clip that warns on five bones is not ready to
+   look at. This step needs no `t`, no `motion` — just the clip.
+1. **Probe the landmarks** — inspect any trivial clip with `bones: ["pelvis","spine_01","spine_02","head"]` to learn
+   where the body actually is on this rig. Do not assume.
+2. **Measure the mesh** if clearance matters — bones say nothing about the body's SURFACE.
+3. **Pose the TORSO FIRST, then solve the arm against it.** The load-bearing step: arms hang off the spine,
+   so an arm solved against an unbent torso is wrong the moment the spine bends. Same chaining rule, one
+   level up.
+4. **Target relative to a landmark** (hand relative to `spine_02`), not absolute world space, so the target
+   survives the torso moving.
+5. **Verify with `t` and `motion`.** Two traps: leaf bones like `head` have NO child, so `dir` is
+   `null` — take the world quaternion instead; and never measure the axis the rotation turns ABOUT (a nod
+   is about the head's local Y, so comparing local Y reads 0° and looks like the key did nothing).
+6. **When a value that SHOULD work does not, measure the chain.** `axes: true` reports what a +10° edit to
+   each keyed axis does at the posed chain — the one question the table cannot answer, and usually the
+   answer: at a ~95° shoulder raise the forearm cannot be made to point up by twist at all, so elevation
+   has to come from the upper arm.
+7. **Then LOOK at it yourself** — `capture_gesture({ clip, world })` renders the clip as a contact sheet
+   (front and one side, five times across it) and returns it as an image. Judge the silhouette and the limb
+   relationships. Read both rows: a limb displaced sideways overlaps the body in the SIDE view purely by
+   projection, so the front row shows lateral separation and the side row shows depth — that pair is what
+   catches an arm raised behind the head, which reads as a perfect wave from the front alone.
+
+   **`at` captures ONE moment instead of a sequence** — the two views then sit side by side at ~1.8x the
+   size. Reach for it when a human asks you to fix one specific thing: the whole image goes to that instant
+   instead of a fifth of it, which is the difference between guessing at a hand's orientation and reading it.
+
+   **You almost never need `views`,** because the default is chosen per mode and each is right for its job.
+   A sequence gets front + whichever side the clip actually keys (derived from its bones and mask, so a
+   left-handed gesture is never rendered from the flank its own torso hides) — the ORTHOGONAL pair, which is
+   what makes "moves side-to-side, not front-to-back" readable. A single moment gets front + `three-quarter`,
+   40° off the front on the clip's active side, because that lifts a limb CLEAR of the torso instead of
+   hiding it behind: a pure side view of a laterally displaced arm overlaps the head by projection and cannot
+   tell you in-front from behind. Override for a reach behind the body (`back`). Never pair front with back,
+   or left with right — each looks down ONE axis, so neither view shows depth; a `three-quarter` never has
+   that problem because it mixes both.
+   **What the render can and cannot answer.** Trust it for silhouette, which limb is where, joint bend
+   direction and gross orientation — the "does this read as a person doing X" judgement, which is the whole
+   reason to look. Do NOT read distances or which body part moved off it. Both are measurably unreliable:
+   in testing, an elbow sitting 0.20 m FORWARD of the torso was read as "tucked against the ribs", and a
+   wind-up where the TORSO had leaned 0.19 m back was read as "the arms are behind the head" — the gestalt
+   was right, the attribution wrong. Depth *magnitude* is the weak axis, and the `three-quarter` does not fix
+   it; it fixes in-front-versus-behind *ordering*. And a natural-range violation is invisible in a render
+   entirely — the `pickaxe-swing` sheet looks fine while breaking the shoulder's swing limit by 10°. So when
+   the image raises a question, go back to `inspect_gesture` for the answer, never look harder at the image.
+
+8. **Only then hand it to a human**, saying what you measured. If 0–7 were done, their first look confirms
+   rather than corrects.
+
+`capture_gesture` costs a headless browser launch — seconds, against milliseconds for `inspect_gesture`. So
+it is the CLOSING check, once per clip, not the inner loop.
+
+**Additive cannot guarantee CONTACT.** The base clip keeps moving the limb under your delta, so a pose that
+touches the body at rest drifts off while walking. Floating poses tolerate it ("fist held across the belly"
+survives the walk swing); "palm resting ON the stomach" needs `overrideMask` on that limb.
+
+**Mixing both modes in ONE clip — `overrideMask`.** For a gesture that must ride the locomotion AND hold a
+limb still:
+
+```js
+{ compose: 'additive', overrideMask: 'rightArm', keys: [{ t: 0, bones: {
+    spine_02: [0,-12,0], head: [0,-25,0],             // additive — bow rides the walk
+    upperarm_r: [60,-10,-20], lowerarm_r: [0,-60,0],  // override — arm ignores the walk's swing
+} }] }
+```
+
+Keyed bones inside `overrideMask` override; the rest stay additive. Only valid with `compose: 'additive'`.
+
+**Never hand-split this into two clips.** It looks right in single-player and is BROKEN in multiplayer: the
+wire carries one loop slot per player, so two simultaneous looping clips replicate only whichever started
+second — remote players and late joiners see half the gesture. Oneshots are unaffected.
+
+**`weight` is not a substitute** and works oppositely per mode: on override it blends base→pose (a real
+strength knob); on additive it scales the delta toward nothing, so lowering it gives MORE base motion.
+
+**Then verify in motion**, from the FRONT and the SIDE, checking the palm and elbow-pit directions — a good
+scrub frame can still swing wrong.
+
+**Runtime IK is a separate thing from clips (≥ 0.2.15, replicates).** For LIVE world targets — press a wall
+button, hold a door handle, glance at an object — do not author a clip at all: the character reaches with
+its arm chain at runtime, and other players see it (the target point replicates; every client runs the
+same solver locally).
+
+```js
+mp.local.ik.reach('right', buttonMesh, { press: true });              // one-off: touch, hold ~0.12 s, withdraw
+const grab = mp.local.ik.reach('right', handleMesh, { engage: {} });  // holds while near + facing; auto re-grabs
+mp.local.ik.lookAt(handleMesh);                                       // interaction gaze; lookAt(null) clears
+grab.release();                                                       // when the interaction is over for good
+```
+
+`engage` takes `{ maxDistanceM, maxAngleDeg, from: 'shoulder'|'character' }` (default distance: arm reach
++ 0.25 m); `press` and `engage` are mutually exclusive. The facing arc (≥ 0.2.17) is the **reaching arm's
+workspace, not a forward cone**: per arm the window runs from ~15° across the body midline to ~135° on
+that arm's own side (`maxAngleDeg`, default 75, is the half-width around a center leaned 60° toward the
+arm). Facing the target directly always engages, the same-side flank engages even somewhat behind the
+shoulder line, cross-body and the deep back never do — so pick the hand on the target's side. The arc is
+measured from the **character model's forward, never the camera** — in third person the camera orbits
+independently, so a camera-based facing check is wrong; gate custom prompts with the character forward too
+(`new THREE.Vector3(0,0,1).applyQuaternion(mp.local.model.quaternion)`, flattened horizontally — the
+character-world doc has the full snippet).
+
+**`orientMatch: true` adopts the target's world frame as the HAND-BONE frame, verbatim** (85° wrist-guard
+cap) — nothing about it is palm-aware. The canonical hand-bone frame, measured: fingers run along local
+**+x** (left hand; −x right) and the relaxed palm normal is ≈ local `[0.1, 0.5, -0.85]` (left; fully
+negated right) — not a clean axis, so do NOT derive palm-on-surface rotations by hand. The working
+pattern: place a helper `Object3D` at the contact point, calibrate its rotation by eye once, and reach
+for the helper with `orientMatch: true`. Off (the default), the solve leaves the wrist to the
+animation/grip — correct for engage-grabs of free props. Runtime reach orientation has no numeric
+readback yet (`inspect_gesture` covers clips only) — verify orientMatch poses visually.
+
+A press can gate ITSELF (≥ 0.2.16): `press: { when: {} }` takes the same envelope shape and defaults as
+`engage`, evaluated once at the moment of the request — out of range or facing away, **nothing fires**
+(no arm motion, no reach-through-the-body) and the returned handle reports `fired: false`:
+
+```js
+const h = mp.local.ik.reach('right', pressPoint, { press: { holdS: 0.1, when: {} } });
+if (!h.fired) hud.flash('too far away');
+``` One reach slot per hand — a new reach
+replaces the old — and an active reach overrides whatever a clip does to that arm (IK solves after
+gestures). Drive ONLY `mp.local` from interaction handlers; remote players' arms are driven by replication.
+
+**Rig reach numbers — place interactables with these, do not measure in-world.** On the canonical rig the
+arm chain is **0.55 m shoulder→wrist** (0.278 + 0.273), shoulders ≈1.44 m up and ±0.19 m off center, so
+the default engage envelope is **≈0.80 m from the shoulder** (the runtime measures each avatar's own
+chain, so non-standard avatars self-adjust). Practical placement: put grab/press targets **0.4–0.7 m**
+from where the character will stand, at 0.9–1.3 m height. Beyond the envelope an `engage` stays armed but
+never grabs, and a `press` reaches full extension then gives up after `timeoutS`. Separate wire caps
+(replication validity, not reach): a reach target must be ≤ **3 m** from the player and a look target
+≤ **50 m**, or that frame's upload is skipped.
+
+**The reach target is the WRIST, not the fingertips.** The solver drives the `hand_*` bone origin onto
+the target; fingers extend ≈15–19 cm beyond it (palm ≈7 cm). To **press** a button with the fingers, do
+not target the button itself — target a point ≈**10–15 cm in front of its face** (offset along the
+surface normal), or the wrist lands on the button and the hand punches through:
+
+```js
+const pressPoint = button.position.clone().addScaledVector(buttonFaceNormal, 0.12);
+mp.local.ik.reach('right', pressPoint, { press: true });
+```
+
+Targeting the object directly IS right for `engage` grabs of free-standing props (handle, orb, lever) —
+the object should end up in the palm, and the grip finger poses do the wrapping.
+