@hypersoniclabs/helix-mcp 0.2.5 → 0.2.12

package/skills/helix-avatars/references/contract.md

@@ -0,0 +1,166 @@
+# The avatar contract: skeleton, frame, LODs and budgets
+
+An avatar is a universal item with `kind: avatar`. It is one GLB holding a `helix-humanoid@1`
+character, normally three LOD scenes, with optional face and dynamics manifests in scene extras. The
+platform's shared locomotion clips drive it by bone name. A foreign rig T-poses: a raw Meshy or
+Mixamo rig is refused at upload as "convert first".
+
+## Skeleton: `helix-humanoid@1`
+
+**68 canonical joints**:
+- `root`, `pelvis`, `spine_01`–`spine_05`, `neck_01`, `neck_02`, `head`;
+- per side: `clavicle`, `upperarm`, `lowerarm`, `hand`, three segments for each of the five fingers,
+  plus the importer-owned metacarpals;
+- twist joints: `upperarm_twist_01/02`, `lowerarm_twist_01/02`, `thigh_twist_01`, `calf_twist_01`;
+- legs: `thigh`, `calf`, `foot`, `ball`, all suffixed `_l` / `_r`.
+
+**Bones each gate requires:**
+- **Publish preflight:** `root`, `pelvis`, `spine_01`, `head`, `hand_l`, `hand_r`, `foot_l`,
+  `foot_r`.
+- **Backend:** `pelvis`, `spine_01`/`03`/`05`, `neck_01` and `head`, plus `clavicle`, `upperarm`,
+  `lowerarm`, `hand`, `thigh`, `calf` and `foot` on both sides.
+- **Optional:** fingers, twists, `ball`, `spine_02`/`04` and `neck_02`. A missing bone is skipped
+  silently by the clips.
+
+**Auxiliary joints are allowed under canonical parents**: hair, tails, physics. Add them **after**
+import, because the importer rebuilds the canonical 68. See `dynamics`.
+
+## Frame, units and rest pose
+
+| Property | Value |
+| --- | --- |
+| Units | Metres |
+| Up | +Y |
+| Forward | **+Z** |
+| Character left | +X |
+| Feet | On Y = 0 |
+| Rest pose | The canonical **A-pose**: arms about 45° down, not a T-pose. Gate: each upper arm is bound at least 17° from straight down (Base Female 36°); the Marketplace walk adducts ~24° from the clip's A-pose, so a bind nearer the body walks into it (`avatar.bind_pose`) |
+
+Orientation is gated at upload. The skeleton yaw and the skinned-geometry yaw are measured
+separately, and each must face forward within **15°**.
+
+## LODs: one GLB, one scene per level
+
+- Scene *i* is LOD *i*, nearest first. The importer names the scenes `lod1`–`lod3`. Match on the
+  scene index, never on the name.
+- The runtime switches at 0 / 8 / 15 m by default.
+- **Every LOD scene must carry its own skeleton copy.** A GLB whose LOD scenes share one skeleton
+  loads with undefined bones in three.js. The importer asserts self-contained scenes. To repair a file
+  that broke this, run `helix character repair-lod-skeletons`.
+- At runtime, lower LODs are rebound onto LOD0's skeleton by bone name. So every edit you make after
+  import, whether weights, auxiliary joints or a dynamics or face manifest, must be made **identically
+  on every LOD**.
+- A healthy imported avatar has **3 skins and 6 meshes**: the body plus a `FaceMesh` per LOD.
+  `FaceMesh` is the head slice that the importer cuts so the first-person camera can hide it. It
+  is an index-only slice: it shares the body's vertex accessors (`POSITION`, `JOINTS_0`,
+  `WEIGHTS_0`), so edit each accessor once, not once per primitive.
+
+## Budgets (upload gate)
+
+Every count is summed across the **whole file**, which means **every LOD**.
+
+| Limit | Avatar | Source |
+| --- | --- | --- |
+| Triangles, all LODs together | **60,000** | `AVATAR_MAX_TRIANGLES` |
+| Draw calls, all LODs together | **12** | `AVATAR_MAX_DRAW_CALLS`: each primitive × the nodes that instance it |
+| File size | **10 MiB** | `AVATAR_MAX_FILE_BYTES` |
+| Materials | **8** | `AVATAR_MAX_MATERIALS` |
+| Texture edge | **2048 px** | |
+
+How they bite:
+- **Draw calls.** One material over three LODs, each with a body and a `FaceMesh`, is 6 draws. Every
+  extra material or separate mesh costs 3 draws, once per LOD. A helmet as its own mesh took Daft
+  Punk to 9.
+- **Triangles.** Splits that shipped:
+
+  | Avatar | LOD0 | LOD1 | LOD2 |
+  | --- | ---: | ---: | ---: |
+  | Unitree G1 | 35k | 14.5k | 5k |
+  | C-3PO | 39k | 14k | 5.6k |
+  | T-800 | 47.8k | 7.8k | 3.8k |
+  | Cream Hoodie | 30k | 15k | 5k |
+
+  The importer's default is `10000,5000,1500`. Set `--lod-tris` to use the budget.
+- **File size.** KTX2 makes a 2048 atlas affordable. A UASTC normal map plus an ETC1S base came to
+  9.75 MiB on Iron Man, just under the cap.
+- **Materials.** `helix character import` does **not** merge materials. A many-material source
+  imports cleanly and is then refused at publish, so atlas the materials first.
+
+Run the structure, budget and motion checks in the avatar `qa` reference before sealing the
+Character Package Version through the Creator's approved Publications workflow.
+
+**Preflight errors** (blocking):
+- `triangles`, `materials`, `texture-edge`, `draw-calls`, `file-size`;
+- `no-skin`;
+- `skeleton` (a required joint is missing);
+- `rig-scale` (the skeleton spans more than 10 m).
+
+**Preflight warnings:**
+- `no-dynamics`;
+- `no-face`;
+- `no-first-person-hide`.
+
+Every publish also runs three guards on the materials:
+- the base colour must not be a normal map;
+- normal maps must be valid;
+- rest frames must deviate no more than 100° from canonical.
+
+Do not set their bypass environment variables. Fix the asset.
+
+## Height and the short-body locomotion gate
+
+- Body height is LOD0's bounding-box height.
+- The visual-QA avatar route accepts drawn heights of 0.5–3.5 m, and warns when the drawn height is
+  outside 0.8–1.25× the declared height.
+- **Under 1.35 m, locomotion is retargeted only if** (pelvis height − foot height) / 0.877 is below
+  0.65. Otherwise the human clips play unscaled and the feet sink.
+  - The 1.32 m Unitree G1 had a natural ratio of 0.74. Its feet sank 2–5.7 cm.
+  - Lowering the authored pelvis joint to 0.60 m (ratio 0.62) fixed it.
+  - Tall bodies (C-3PO at 1.67 m, Iron Man at 1.98 m) are not affected.
+
+## Feet and toes
+
+- The conform stage never aims the feet and authors the toes ground-flat at canonical rest. Clips
+  then keep the soles flat only if the ankle sits where the canonical foot pitch expects it.
+- Iron Man's fix was to re-pose the source feet by **yaw only**, so the soles stayed flat.
+- The visual-QA avatar route **warns** when the toes point more than 75° off forward. Meshy's
+  foot-joint placement typically lands about 25° off, which is inside the gate but visible in close-up.
+  Check the feet in the walk frames.
+
+## First-person hide
+
+- The camera hides meshes whose names contain an entry in `scene.extras.helixAvatar.firstPersonHide`
+  (up to 64 names).
+  - With no list at all, the runtime falls back to `["FaceMesh"]`.
+  - `helix character import` writes no list, and the preflight then warns `no-first-person-hide`.
+    Write `{ "firstPersonHide": ["FaceMesh"] }` yourself, plus anything else in front of the eyes.
+  - The VRM route writes the list for you.
+- A helmet, hood or hair mesh in front of the eyes must be listed too, on **every scene**. Daft Punk
+  lists `["HelmetFaceMesh", "FaceMesh"]`.
+- Dynamics keep running while a mesh is hidden.
+
+## Face and dynamics manifests
+
+| Manifest | Location | Contract |
+| --- | --- | --- |
+| Face | `scene.extras.helixFace` | `helix/avatar-face@1`: see the `face` reference and `read_doc({ name: "avatar-face" })` |
+| Dynamics | `scene.extras.helixDynamics` | `helix/dynamics@1`: see `dynamics` |
+
+Both must ride the GLB **at publish**. Nothing at runtime adds them later.
+
+## The import receipt
+
+`helix character import` writes `<name>.avatar-import.json` (`helix/avatar-import-receipt@1`). It
+records:
+- the source counts and sha256;
+- the output sha256;
+- LOD triangle counts;
+- the face capability;
+- the bone map;
+- `conformed.restAimed` and `jointsRebuilt`;
+- the KTX2 modes;
+- `splitFace`.
+
+Pass `--provenance <json>` with `sourceUrl`, `license` (SPDX) and `licenseUrl` (optionally
+`attribution`, `author`, `model`, `version`) so the receipt pins where the source came from. Keep the
+receipt in your ledger: it is the record of what you shipped.

package/skills/helix-avatars/references/dynamics.md

@@ -0,0 +1,367 @@
+# Dynamics: physics bones for hair, cloth, tails, ears and soft tissue
+
+Secondary motion is what makes an avatar read as a character instead of a mannequin. On HELIX it is
+**data in the GLB**, solved by the engine. You never write a solver, and nothing about it is
+networked: every client simulates the chains locally.
+
+**Do this last, on the imported file.** `helix character import` rebuilds the skeleton to the 68
+canonical joints (`transforms.conformed.jointsRebuilt: 68` in the receipt), so helper or physics
+joints in a non-VRM source do not survive the import. Add dynamics to the imported `*.web.glb`, then
+publish that file.
+
+## The contract: `helix/dynamics@1`
+
+The declaration lives in `scene.extras.helixDynamics`. Write an **identical copy on every LOD
+scene.** A manifest on LOD0 only drops physics on the lower levels.
+
+```json
+{
+  "contract": "helix/dynamics@1",
+  "chains": [{
+    "id": "hair-long-l",
+    "root": "hair_long_l_1",
+    "importance": "high",
+    "stiffness": [0.6, 0.42],
+    "damping": [0.8, 0.75],
+    "inertia": [0.7, 0.65],
+    "gravity": 0.04,
+    "limit": { "kind": "cone", "maxDegrees": [18, 22] },
+    "radius": 0.012,
+    "colliders": ["head", "shoulders"],
+    "endpoint": [-0.085, 0, 0]
+  }],
+  "colliders": [
+    { "id": "head", "bone": "head", "shape": "sphere", "offset": [0.09, 0, 0], "radius": 0.115 },
+    { "id": "shoulders", "bone": "spine_04", "shape": "capsule", "offset": [0.04, 0, 0], "tail": [0.21, 0, 0], "radius": 0.085 }
+  ],
+  "lod": { "minPixels": 14 }
+}
+```
+
+### Top level
+
+The only allowed keys are `contract`, `chains`, `colliders` and `lod`.
+
+### Chain fields
+
+| Field | Required | Meaning |
+| --- | --- | --- |
+| `id` | yes | Stable and authored, `[A-Za-z0-9_.-]{1,64}`, unique in the manifest. Never derive it from a bone path. |
+| `root` | yes | The first **simulated** bone. Its parent is the anchor and never moves. |
+| `importance` | yes | `critical`, `high`, `normal` or `decorative`. It ranks the chain in the frame budget. |
+| `stiffness` | yes | 0..1, mapped to ω = 2 + 38·t² rad/s. 2 is a heavy cape; 40 is a taut wire. |
+| `damping` | yes | 0..1. It is the damping ratio, so 1 is critical (no overshoot). |
+| `inertia` | no, default 0 | 0..1. The share of the anchor's motion the chain carries without generating velocity. 1 is carried rigidly. This field is what stops hair flying backwards when running. |
+| `gravity` | no, default 0 | −8..8, a multiplier on 9.81 m/s². Leave it out and nothing droops. |
+| `gravityDir` | no, default (0, −1, 0) | A world-space vector. |
+| `limit` | no, default none | `{ "kind": "cone", "maxDegrees": … }` or `{ "kind": "hinge", "maxDegrees": …, "axis": [x, y, z] }`, with degrees 0..180. A hinge needs `axis`. There is no polar limit. |
+| `radius` | yes if `colliders` is non-empty | The per-joint collision radius in metres. |
+| `colliders` | no | Up to 8 collider ids, each declared in `colliders`. |
+| `endpoint` | in practice, yes | The tip offset in the **last joint's local frame**. Without it, the last joint has nothing to aim at and the chain ends one bone early. |
+| `exclude` | no | Bone names to skip while walking the chain. |
+
+**Curves.** `stiffness`, `damping`, `inertia`, `radius` and `limit.maxDegrees` each take either a
+scalar or an array of 1–8 evenly spaced stops from root to tip. `[0.8, 0.3]` gives stiff-at-the-scalp,
+loose-at-the-tip hair.
+
+**How a chain is walked.** From `root`, the solver follows single bone children. **A branch point
+ends the chain**, so give a skirt one chain per panel. It treats bones as spheres at the tail, not as
+swept capsules.
+
+**Do not root a chain on these:**
+- a bone a face channel drives;
+- a ragdoll bone;
+- a twist-driver bone.
+
+Two writers on one quaternion is undefined. Your own auxiliary joints are always safe.
+
+### Collider fields
+
+| Field | Meaning |
+| --- | --- |
+| `id` | Required and unique. |
+| `bone` | Required. Any bone in the skeleton, usually canonical: `head`, `spine_03`–`spine_05`, `pelvis`, `thigh_l`/`thigh_r`, `upperarm_*`. |
+| `shape` | `sphere`, `capsule` or `plane`. |
+| `offset` | Bone-local metres. |
+| `radius` | Required for a sphere or capsule. |
+| `tail` | **Required for a capsule** and **forbidden on a sphere**. It is the far end, in bone-local metres. |
+| `normal` | A plane only. A plane takes no `radius` and no `tail`. |
+| `inside` | Boolean. It keeps joints inside the shape instead of out of it. |
+
+Colliders are never generated for you. Declare only the colliders a chain uses: **collision checks
+(joints × colliders, summed over chains) are the cost that explodes.**
+
+### Axes: every vector is in the bone's own frame
+
+`endpoint`, `offset`, `tail` and `normal` are **bone-local** (`gravityDir` alone is world space), and on `helix-humanoid@1` bone-local is not world-aligned. These
+are the measured bind frames:
+
+| Bones | local +X | local +Y | local +Z |
+| --- | --- | --- | --- |
+| `pelvis`, `spine_01`–`spine_05`, `neck_*`, `head` | up | the character's **right** (world −X) | forward (world +Z) |
+| Limb bones | along the bone, toward its child | | |
+
+A new auxiliary joint takes its parent's bind orientation. So:
+- a strand hanging straight down from `head` has `endpoint` `[-L, 0, 0]`, and about that from
+  `spine_05`, which leans a few degrees;
+- a sphere 9 cm above the head bone is `offset` `[0.09, 0, 0]`.
+
+**Compute every vector from LOD0's inverse bind matrices**: local = inverse(bind world of the bone) ×
+world point. Do not type them by hand.
+
+Earlier avatars wrote `[0, -L, 0]`. That includes the anime lane's values and the engine's own
+reference build. On this skeleton it points the tip **sideways**, to the character's left. The strict
+parse accepts it, so nothing warns. The values in this file are axis-corrected.
+
+### The parse is strict, and failure is silent
+
+The engine's reader returns `null` for the **whole** manifest when it meets any of these:
+- an unknown key at any level;
+- a value out of range;
+- a duplicate id;
+- a collider id a chain names but the manifest does not declare;
+- `colliders` without `radius`;
+- a hinge with no axis;
+- a capsule with no tail, or a sphere with a tail.
+
+When that happens the avatar loads with **no physics at all**. The only signal is one browser console
+line:
+
+```
+[dynamics] ignored a malformed helixDynamics block on: <name>
+```
+
+Nothing checks the manifest offline:
+- The publish preflight only counts chains, and warns `no-dynamics` when there are none.
+- The backend does not validate the manifest at upload.
+
+So check it yourself before publishing with the engine's own parser (step 6 below), and watch the
+console in the live preview.
+
+**Caps.** If a count is over its cap, the whole manifest is dropped.
+
+| Cap | Value |
+| --- | --- |
+| Chains | 64 |
+| Joints per chain | 32 |
+| Total joints | 192 |
+| Colliders | 64 |
+| Colliders per chain | 8 |
+| Collision checks | 1024 |
+
+Real avatars are many short chains (VRoid ears and tail: 48 chains, 128 joints, 352 checks), and
+that is fine. The runtime enforces a scene-wide frame budget: it lowers rate (60 → 30 → 15 Hz) and
+only then switches a chain off, ranked by `importance` and screen size.
+
+`lod.minPixels` passes the parse but **nothing in the runtime reads it today**. Every lane writes
+`14`; keep doing so for forward compatibility.
+
+## Where the bones come from
+
+| Source | What you do |
+| --- | --- |
+| **VRM** | `bridge_import` converts SpringBone to this contract for you. Audit the result; see `source-vrm`. |
+| **Separate hair, ears or tail** that you can sell or swap | Make it a character **add-on** that carries its own bones and `helixDynamics`. The engine collects every manifest on the dressed character by traversal. When a chain id is duplicated, **the declaration attached later wins** and the other is dropped, so an add-on beats the body that wears it. |
+| **Everything else**: Meshy, Dreamer, game rips, hand-made | Insert auxiliary joints and author the manifest yourself, as below. |
+
+## Authoring chains on a non-VRM avatar
+
+**No CLI or MCP command does this yet.** That is a known gap: `helix-creator-cli` issue #295
+proposes `helix character dynamics apply|validate`. Until it lands, write a small
+`@gltf-transform/core` script that follows these steps exactly. Every one of them is a failure that
+already shipped.
+
+1. **Choose the chains from the geometry, not from the wish list.**
+   - A strand, lock or panel must exist as its own surface, or at least as a separable band of
+     vertices.
+   - Meshy and Dreamer output is **one fused shell**: hair, hood, face and body are welded. You can
+     move the hair band, but only if the transition into the hood or neck stretches smoothly.
+   - Plan the chains you can move without tearing:
+
+     | Feature | Chains | Joints per chain |
+     | --- | --- | --- |
+     | Back hair fall | 3–11 | 2–4 |
+     | Long side locks | 1 each | 2 |
+     | Bob hair | 4 | 1 |
+     | Skirt | 1 per panel | 3 |
+     | Tail | 1 | 4–6 |
+     | Ears | 1 each | 1–2 |
+     | Soft tissue | breast or glute pair | 1 |
+
+2. **Select the vertices per LOD.** Each LOD has its own geometry, so compute the selection on each
+   one. Two methods have worked:
+   - **Anatomical sphere-steal.** Use it when the region is spatially distinct: soft tissue, a bob
+     clear of the shoulders. Give each joint a sphere (`center`, `radius`, `maxWeight`). Take weight
+     **proportionally and only from a declared `stealFrom` set of bones**, so a wrist passing through
+     the chest at bind time donates nothing. Values that shipped are in the table below.
+   - **Mask and weight field.** Use it on a fused shell. Sphere-steal grabbed the hood on the hoodie
+     avatar. Classify hair vertices from that LOD's own base colour at each UV:
+     - dark means luminance below 0.30;
+     - exclude a face box (eyes, brows and lashes are dark too);
+     - require a height band below the crown;
+     - keep a vertex only if more than 50 % of its welded neighbours are also hair. That removes
+       stray dark texels on clothing.
+
+     Then build a smooth weight field (smoothstep between head and joint 1, and between joint 1 and
+     joint 2, with lateral hat functions between neighbouring chains). Blend it in through a
+     "dynamicness" scalar diffused 3 rings over the welded mesh graph, so the boundary stretches
+     instead of tearing. Classify from a PNG import (`--no-ktx2`) of byte-identical geometry when the
+     KTX2 colour is not readable.
+
+3. **Insert the joints into every LOD skin with identical names.**
+   - At runtime, lower LODs are rebound onto LOD0's skeleton by bone name, and springs are solved
+     once, on LOD0's bones. Yet the file must still give each LOD scene its own skeleton copy (see
+     `contract`).
+   - Place joint heads in bind space, in metres, in the canonical frame (+Y up, +Z forward,
+     character left = +X).
+   - New joints take their parent's bind orientation.
+   - **Pick the anchor that the geometry actually rides on.**
+     - The hoodie's back hair lies on the hood, and the source had bound that region to the
+       clavicles, upper arms and `spine_03`. Hung from `head`, the arm swing dragged it.
+     - Hung from `spine_05`, it rides the torso and only lags.
+     - Hair that sits on the skull hangs from `head`.
+     - Soft tissue hangs from `spine_04` (breasts) or `pelvis` (glutes).
+
+4. **Write the weights.**
+   - Keep at most 4 influences per vertex and renormalise to a sum of 1. When blending hair weight
+     into a vertex that already has 4 influences, keep the 4 largest after blending: the hair joints
+     displace the smallest body influences, never `head` or `spine_05`.
+   - **Rewrite `JOINTS_0` and `WEIGHTS_0` in place.** Appending new accessors leaves the old
+     interleaved bytes in the buffer and pushed one avatar over the 10 MiB cap.
+   - **Body and `FaceMesh` primitives share one `POSITION` accessor**, and usually their
+     `JOINTS_0` and `WEIGHTS_0` too. `FaceMesh` is an index-only slice of the same vertex buffer.
+     Track the accessors you have already processed. A refit applied once per primitive moved one
+     avatar's hair twice as far as intended, so that version had to be rejected.
+
+5. **Write the manifest on every scene.**
+   - `endpoint` and collider offsets are in each bone's local frame. Compute them from LOD0's
+     inverse bind matrices and reuse them for every LOD.
+   - Chain and joint names must be identical in every LOD.
+
+6. **Check before publishing, using the engine's own parser.**
+   - A throwaway character world gives you the engine's own module:
+     `helix init /tmp/avatar-harness --kind character`, then `npm install`, then `helix install`.
+     It is the same harness as `qa` step 3.
+   - Its `readDynamicsManifest` is the strict parser the runtime uses. It cannot tell a sideways
+     endpoint from a downward one, so check the axes yourself (see "Axes"). Run this from the harness
+     directory:
+
+     ```js
+     // Offline helix/dynamics@1 check with the engine's own strict parser (from a scratch world's `helix install`).
+     import { readFileSync } from 'node:fs';
+     const { readDynamicsManifest } = await import('./public/helix_modules/humanoid-character/index.js');
+     const glb = readFileSync(process.argv[2]);
+     const json = JSON.parse(glb.subarray(20, 20 + glb.readUInt32LE(12)).toString('utf8'));
+     const scenes = json.scenes ?? [];
+     const skins = (json.skins ?? []).map((s) => new Set(s.joints.map((j) => json.nodes[j].name)));
+     const raw0 = JSON.stringify(scenes[0]?.extras?.helixDynamics);
+     let ok = scenes.length > 0;
+     scenes.forEach((scene, i) => {
+       const raw = scene.extras?.helixDynamics;
+       const m = readDynamicsManifest(raw);
+       if (!m) { ok = false; return console.log(`scene ${i} ${scene.name}: ${raw ? 'REJECTED by the strict parse' : 'no helixDynamics'}`); }
+       if (JSON.stringify(raw) !== raw0) { ok = false; console.log(`scene ${i} ${scene.name}: differs from scene 0`); }
+       const names = [...m.chains.flatMap((c) => [c.root, ...(c.exclude ?? [])]), ...(m.colliders ?? []).map((c) => c.bone)];
+       skins.forEach((joints, k) => names.filter((n) => !joints.has(n)).forEach((n) => { ok = false; console.log(`skin ${k}: missing joint ${n}`); }));
+       const checks = m.chains.reduce((sum, c) => sum + (c.colliders?.length ?? 0), 0);
+       console.log(`scene ${i} ${scene.name}: ${m.chains.length} chains, ${m.colliders?.length ?? 0} colliders, ${checks} collider refs`);
+     });
+     process.exit(ok ? 0 : 1);
+     ```
+
+   - Exit 0 means every LOD scene carries an identical manifest that the runtime accepts, and every
+     named bone exists in every skin.
+   - Also check that weights sum to 1 with at most 4 influences, and that the dry run is still inside
+     the triangle, draw and byte budgets.
+
+7. **Measure it moving.** Run the motion probe in `qa` step 3. It drives the engine's `DynamicsLayer` on the platform's own walk and run clips, and reports the swing of every auxiliary bone. A chain that parses can still smear, so render the run frames too.
+
+## Worked layout: long straight hair on a fused shell
+
+This is the commonest request, and the one with the most ways to go wrong.
+
+1. **Make a mask twin.** Import the same source a second time with the same flags plus `--no-ktx2`.
+   - The geometry, UVs and vertex order come out byte-identical. Assert that `POSITION` matches.
+   - A vertex mask computed on the twin then indexes the KTX2 file directly.
+   - The twin is about twice the size. Never publish it.
+   - Its textures are JPEG or PNG. Decode them in Node with `sharp` or `jpeg-js`.
+2. **Find the hair band.** Classify hair vertices on every LOD (step 2 above).
+   - Histogram them in 5 cm height bands, and across x behind the head.
+   - The free hang starts where the hair leaves the skull, below the occiput.
+   - It ends at the lowest band that still holds hair.
+3. **Lay out the chains.**
+   - Use 3–5 columns across the back fall, about 6–7 cm apart. The hoodie used 3, at x = −0.065,
+     0 and +0.065.
+   - Give each column 2 joints:
+     - joint 1 at the top of the free hang;
+     - joint 2 about halfway down;
+     - the tip at the hair's end, as `endpoint`.
+   - Place the joints just inside the hair surface, on its midline. The hoodie's joints sat at
+     y 1.47 and 1.37 with the tip at 1.26, z about −0.13 to −0.15.
+4. **Choose the anchor.**
+   - Hang from `head` when the fall hangs free of clothing.
+   - Hang from `spine_05` when its lower part rests on a hood, collar or back.
+5. **Front locks.** On a fused shell, the front locks sit inside `FaceMesh`, the head slice. If you
+   add no chain, they stay rigid on `head`. From the front they are the most visible hair, so if the
+   user asked for visible sway, say plainly when you leave them rigid, and why.
+   - That is the right call on a hood or high collar: they smeared there.
+   - With open shoulders, give each side one 2-joint long-lock chain, with the `head` and
+     `shoulders` colliders from the table below.
+6. **Pick the feel, then measure it.** The hood set below is restrained on purpose: it reads 6–9°,
+   which is barely visible. If the user wants visible sway and nothing is in the way, start from the
+   long-lock values. Then:
+   - run the `qa` step 3 probe;
+   - render side and back frames while running;
+   - check nothing passes through the shoulders or back.
+
+## Parameters that shipped, and why
+
+| Use | stiffness | damping | inertia | gravity | limit | Notes |
+| --- | --- | --- | --- | --- | --- | --- |
+| Back hair on a fused Meshy shell (3 chains, 2 joints each; anchor `spine_05`) | [0.78, 0.70] | [0.88, 0.85] | [0.85, 0.80] | 0.02 | cone [7, 9]° | `radius` 0.012. Collider `upper-back`: a capsule on `spine_05` spanning bind-space y 1.30–1.47 m just behind the spine, radius 0.10 (convert the two ends to `spine_05`-local `offset` and `tail`). About 8° of swing walking and 9° running. Live on Cream Hoodie Anime Girl. |
+| Long side locks (2 joints; anchor `head`) | [0.6, 0.42] | [0.8, 0.75] | [0.7, 0.65] | 0.04 | cone [18, 22]° | `radius` 0.012. Colliders: `head` (sphere, `offset` [0.09, 0, 0], r 0.115) and `shoulders` (capsule on `spine_04`, `offset` [0.04, 0, 0], `tail` [0.21, 0, 0], r 0.085). Axis-corrected: they shipped as `[0, y, 0]`. |
+| Bob hair (4 chains, 1 joint; anchor `head`) | 0.54 | 0.4 | 0.72 | 0.035 | cone 30° | Sphere-steal from `head`: radius 0.078, `maxWeight` 0.8. |
+| Breasts (anchor `spine_04`) | 0.85 | 0.9 | 0.9 | 0.008 | cone 7° | Sphere radius about 0.09, `maxWeight` 0.45. `stealFrom` `spine_01`, `spine_03`, `spine_04`, `spine_05` and the clavicle on that side. Earlier values (0.52 / 0.43 / 0.62, cone 18°) were too loose. |
+| Glutes (anchor `pelvis`) | 0.8 | 0.9 | 0.9 | 0.008 | cone 7° | Sphere radius about 0.095, `maxWeight` 0.45. `stealFrom` `pelvis`, `spine_01` and the thigh on that side. |
+| Short ears (8 cm, 1–2 joints) | 1.0 | 0.5 | 0.97 | – | cone 22° | 13° walking, 16° turning and 22° sprinting, at every frame rate. With inertia 0.6, damping 0.17 and no limit, the ears swung 100°+. |
+| Skirt panel (engine reference, 3 joints; anchor `pelvis`) | [0.62, 0.42] | [0.78, 0.66] | [0.72, 0.5] | 0.55 | hinge 24° about the panel's tangent | Colliders: hips and both thighs. A cone lets panels swing sideways like tentacles. Panels must overlap, because neighbours swing independently. |
+| Ribbon hair (engine reference, 4 joints) | [0.72, 0.30] | [0.5, 0.28] | [0.55, 0.2] | 0.9 | cone [30, 55]° | Free strands with generated ribbon geometry, not hair glued to a shell. |
+
+The rules behind those numbers:
+
+- **Short chains want** inertia near 1, stiffness near the top of the range, damping about 0.5, and
+  a cone limit as the guarantee. A frame-rate-independent solver does not make a loose spring stiff.
+- **Hair modelled already hanging needs almost no gravity.** Its rest pose is already the drape, and
+  real gravity pulls the tips into the back or hood. The lanes used 0.02–0.04. Free ribbons that rest
+  horizontal are the exception that wants about 0.9.
+- **Soft tissue should lag, not swing.** Use damping near 0.9, a small cone, and a `maxWeight` of
+  0.45 or less, so the surface never detaches.
+- **Long chains want high inertia.** On a 13 cm two-joint back-hair chain, measured with the `qa`
+  probe:
+  - inertia 0.7 / 0.65 lagged into the cone limit even walking, which reads as hair stuck out
+    behind, not swaying;
+  - 0.9 / 0.85 separated walking (about 10–25°) from running.
+  Below about 0.8, a chain on a moving body lags steadily rather than swinging.
+- **Tune for the run, not the idle.** Every smear in the record appeared while running.
+
+## Failure modes and fixes
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| No motion, and the preview console shows `[dynamics] ignored a malformed helixDynamics block` | The strict parse rejected the manifest: an unknown key, colliders without radius, a missing collider id, and so on. | Fix the field. One bad field kills every chain. |
+| No motion, no warning | The manifest is on LOD0 only, or the root bone is missing from the skin, or the chain roots on a bone that has no weighted descendants. | Write it on every scene. Check joint names in every skin. |
+| Front locks smear into the hood or collar while running | A fused shell, with front hair resting on the collar. | **Drop front chains on hooded or high-collar avatars.** The hoodie shipped back hair only. |
+| Hair detaches from the back and leaves a gap while walking | A rest gap between the lock and the body, plus a loose cone. | Pull the lock toward the body in the source (a one-off rest warp; 9 cm closed a 4.5–7 cm gap). Tighten the cone, and add a `shoulders` collider. The measured walking gap fell from 9.8 to 3.2 cm. |
+| Hair dragged by arm swing | The anchor or the source weights tie hair to the arms or clavicles. | Re-anchor on the bone the hair actually rests on, and strip arm weight from the hair band. |
+| Ears, tail or hair swing 90°+ when sprinting | Inertia too low (0.6 is what the VRM importer writes for a `center` node), and no limit. | Use inertia 0.95–1, stiffness 1.0, and a cone limit. |
+| Chest dents or bulges with arm swing | Upper-arm weight on torso vertices (Meshy auto-rig). | Fix the weights before adding dynamics. See `source-generated`. |
+| Goes bald, or stops moving, at distance | The lower LOD skins lack the joints or the weights. | Identical joints and weights on every LOD. |
+| An add-on's tuning update is ignored | A duplicate chain id, so the body's copy won. | Engine 0.3.156+ makes the later-attached declaration win. Keep ids unique unless an override is intended. |
+| Ears grafted after spawn never move | Engine ≤ 0.3.146 scanned for chains only at construction. | Fixed in 0.3.147. Check the engine version the world resolves. |
+| Swing differs at 30 and 60 fps | Engine before 0.3.154. | Fixed by the first-order-hold solver. Confirm the version your world resolved (`^0.3` serves the promoted one); if it is older, get the fix promoted — never exact-pin helix.json. |
+
+## Changing dynamics after publish
+
+Package Versions are immutable. Changing any value means a new Package Version and a version move;
+see `publish`. On a package-backed avatar, the character pin-correction route accepts only stiffness
+and damping changes, not inertia or limit. **Get the values right before the first publish.**

package/skills/helix-avatars/references/face.md

@@ -0,0 +1,50 @@
+# Faces: lip-sync, blink and expressions
+
+The full contract is `read_doc({ name: "avatar-face" })`. Read it before you decide what the face
+does. This page covers the avatar-specific decisions.
+
+**The rule:** a face works only if `scene.extras.helixFace` (`helix/avatar-face@1`) rides the GLB
+**at publish**. Nothing adds one later. With no face:
+- the avatar stands in voice chat with a closed mouth;
+- it never blinks;
+- no error is raised. The preflight only warns `no-face`.
+
+## What each source gets
+
+| Source | Face |
+| --- | --- |
+| VRM | Automatic, through `bridge_import`: capability `vowel5`, both blinks, and the six expressions. No `jawOpen`, on purpose: binding it to the "aa" morph opened the A shape on every vowel. |
+| GLB or FBX whose morphs use established names (`viseme_*`, `vrc.v_*`, `aa`/`ih`/`ou`/`ee`/`oh`, `jawOpen`, `blinkLeft`/`Blink_L`) | Detected by `helix character import`. Read its `face:` line. |
+| GLB or FBX with morphs named anything else (a VRoid GLB export, a game face rig) | **Mute unless you pass `faceMap`.** The map assigns HELIX semantics to the morphs or bones the asset has. The importer fails if a declared morph or bone does not exist. |
+| Dreamer or Meshy output, rigid robots, helmets | No morphs: `face: none`. All lanes so far shipped mute. A helmet or robot reads fine mute. A human face does not. |
+
+## The capability ladder
+
+| Capability | What the asset needs |
+| --- | --- |
+| `viseme15` | All 15 visemes |
+| `vowel5` | All 5 vowels; consonants fold into vowels at runtime |
+| `jaw` | `jawOpen` only, as a morph or a bone (`axis` and `maxDegrees` ≤ 45) |
+| `none` | Nothing |
+
+Blink (`blink.left` / `blink.right`) and gaze are separate channels. With them, the runtime blinks on
+its own, about every 3.2–5.3 s, at the full LOD rung only. Without them, the eyes are dead. **The
+runtime never fakes a blink for an asset that has no blink targets.**
+
+## Adding a face to a mesh that has none
+
+The cheapest honest rung is a **jaw bone**: one channel, `jawOpen`, as a bone channel on a jaw joint
+weighted to the lower face.
+
+- An auxiliary jaw joint follows the same rules as a dynamics joint: identical names in every LOD
+  skin, with weights rewritten in place.
+- **A face channel and a dynamics chain must never drive the same bone.**
+
+Blend shapes are better, but authoring 15 visemes is a modelling job. If you skip both, say in the
+listing that the avatar does not lip-sync.
+
+## First-person
+
+The importer splits the head into `FaceMesh` on every LOD, and the camera hides it by default. Anything
+else in front of the eyes must be added to `helixAvatar.firstPersonHide` on every scene: a helmet, a
+visor, a hood brim, front hair.

package/skills/helix-avatars/references/publish.md

@@ -0,0 +1,76 @@
+# Publishing an avatar Package and shipping a new version
+
+Finish `qa` steps 1–3 before publication. Package Versions are immutable. New
+authored content enters HELIX through a sealed Continuum Package Version; MCP
+does not expose loose-mesh Item creation.
+
+## 0. Prepare the avatar
+
+Render a thumbnail from the final GLB in a headless three.js page with
+`GLTFLoader`, `KTX2Loader`, an environment map such as `RoomEnvironment`, and a
+front three-quarter view that shows the whole avatar. Compare with live avatars
+from `search_items({ kind: "avatar" })`.
+
+## 1. Seal the Character Package Version
+
+Create a self-contained Continuum publication descriptor for the Character
+Package and include the final GLB and its dependent objects. Seal it with
+`publish_continuum_package` or the Creator CLI's approved Package publication
+workflow. Package publication does not create an Item or creator copy. MCP does
+not define Publications request or receipt fields; use the Creator workflow's
+response as the authority for the result.
+
+The upcoming Creator CLI commands `helix continuum publish-glb` and
+`helix continuum make-item` are intended to seal a GLB and optionally create an
+Item through the approved Publications workflow. Use them only after that CLI
+release is available; consult its help for arguments and rely on its response
+for the result. For an already existing creator-owned Item, `publish_owned_item`
+moves it to an exact sealed Package Version after explicit content-rating
+attestation; it does not create an Item or an offer.
+
+Public Vault or Marketplace Listings require owner policy or explicit human
+confirmation. Read `read_doc({ name: "continuum" })` before making one public.
+
+## 2. Add an Item or offer only when requested
+
+When the avatar needs to be claimable or purchasable, use the Creator's approved
+Publications workflow to create the optional Item and Marketplace or World offer
+from the exact sealed Package Version. A Package or Vault Listing alone creates
+no creator copy. Do not use a loose GLB upload to create an Item.
+
+## 3. Visual QA
+
+```js
+visual_qa_item_hosted({ itemId }) // the platform renders it
+visual_qa_item({ itemId })        // local render with a QA sign-in
+```
+
+Use `visual_qa_item_status` to follow a hosted run. The avatar remains held from
+public visibility until its current Package Version passes. Read
+`read_skill({ name: "helix-avatar-qa" })` before the first run and after any
+failure. The route (`avatar@3`) covers the Try Now walk and the Marketplace
+item page's walk seen from the sides and back, and a `not measured` assert
+fails. It does not replace checking dynamics, face, first-person hide, and
+motion against the control body in the `qa` reference.
+
+## 4. Refresh the thumbnail
+
+```js
+item_thumbnail({ action: "refresh", itemId, dryRun: true })
+item_thumbnail({ action: "set", itemId, imagePath: "/abs/thumbnail.png" })
+```
+
+`refresh` renders from the active Package Version. `set` uploads a moderated
+PNG, JPEG or WebP and keeps it across version moves until a forced refresh.
+
+## 5. Ship a corrected version
+
+Changes to weights, dynamics, textures or manifests require a new immutable
+Character Package Version. Build and seal the version through the Creator's
+approved Package publication workflow, pass visual QA for that exact version,
+then move the Item to it through the Creator's approved version workflow. Do
+not replace the mesh through a legacy Item upload route. Re-run the live
+close-ups and motion checks from `qa` after the move.
+
+**A dynamics-only change is still a new version.** Tune inertia and limits before
+sealing the first version.