@hypersoniclabs/helix-mcp 0.2.4 → 0.2.12

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

@@ -0,0 +1,251 @@
+# Avatar QA: what to measure, what to look at
+
+**The rule:** nothing ships until you have looked at the avatar **moving** in the real HELIX runtime,
+close up. Every gate passed Cream Hoodie 1.0.0, and in that version:
+- the chest dented with arm swing;
+- a hem edge stretched 16 cm into a spike at the hip.
+
+Every gate also passed a dozen Dreamer drafts that rendered flat white. A rest-pose render proves
+almost nothing: **a T-pose or A-pose hides wrong skin indices**, because every bone sits at its bind.
+
+Run every browser headless, on your own profile directory, with `--use-mock-keychain
+--password-store=basic`. Record the GPU adapter you rendered with.
+
+## 1. Structure (offline, before upload)
+
+Read the final GLB with `@gltf-transform/core` and assert each of these. Every one is a defect that
+has already shipped.
+
+| Check | Pass |
+| --- | --- |
+| Scenes vs skins | One skin per LOD scene, each scene self-contained. Normally 3 skins and 6 meshes. |
+| Joint names | Identical in every LOD skin, including every auxiliary joint. |
+| Weighted joint names per region | Head vertices on `head`/`neck_*`, hands on `hand_*`, no foot or thigh weight above the pelvis, no arm weight on the central torso. Read the **names**, not the indices. |
+| Influences | ≤ 4 per vertex, summing to 1 ± 1e-3. No influence from a bone more than 0.3 m from the vertex. |
+| Emissive | No material has an `emissiveFactor` above 0 without an `emissiveTexture`. |
+| Metallic | No `metallicFactor` of 1 without a metallic map; glTF's default turns untextured parts black chrome. |
+| Manifests | `helixDynamics`, `helixFace` and `helixAvatar` are identical on every scene. `helixDynamics` obeys every rule in `dynamics`. |
+| Budgets | The Character Package's avatar validation passes: ≤ 60k triangles and ≤ 12 draws across all LODs, ≤ 10 MiB, ≤ 8 materials, ≤ 2048 px. |
+| Short body | Height ≥ 1.35 m, or (pelvis − foot) / 0.877 < 0.65. |
+
+## 2. Static render (offline)
+
+Render in headless three.js:
+- `GLTFLoader` with `KTX2Loader` and the basis transcoder;
+- a neutral environment;
+- a ground plane at Y = 0.
+
+Look at:
+- a turnaround (front, back, both sides, both three-quarters);
+- face, hands and feet close-ups;
+- LOD1 and LOD2 at their switch distances (8 m and 15 m), checking that no part goes missing and
+  nothing becomes a shard or a smear.
+
+Compare against the reference images at matched angles.
+
+## 3. Motion against a control body (offline, no GPU)
+
+This is the check that catches rig bugs, and the one an agent most often skips. Run it before the
+upload: once a version is published it cannot be deleted.
+
+The control is the stock body on the same skeleton, played through the platform's own clips and the
+engine's own dynamics solver. All three come from a throwaway character world:
+
+```
+helix init /tmp/avatar-harness --kind character && cd /tmp/avatar-harness
+npm install && helix install            # the engine module lands in public/helix_modules/humanoid-character/
+npm i --no-save @gltf-transform/core @gltf-transform/extensions
+```
+
+`helix.lock.json` then names the asset pack: `systems[0].assetBaseUrl` for `humanoid-character`.
+Download these into one directory:
+- `<assetBaseUrl>/body-f-default.web.glb` and `<assetBaseUrl>/body-m-default.web.glb`, the control
+  bodies;
+- `<assetBaseUrl>/anims/clip-meta.json`;
+- `<assetBaseUrl>/anims/locomotion.idle.glb`, `locomotion.walk.glb` and `locomotion.run.glb`.
+
+Use a browser user agent; a bare request can be refused. Then run this probe from the harness
+directory, with the avatar, the control, and the clip directory as arguments:
+
+```js
+// node probe.mjs <avatar.web.glb> <control.web.glb> <clipDir> [framesOut.json]   (run inside the harness world)
+import { readFileSync, writeFileSync } from 'node:fs';
+import * as THREE from 'three';
+import { NodeIO } from '@gltf-transform/core';
+import { ALL_EXTENSIONS } from '@gltf-transform/extensions';
+import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
+const { DynamicsLayer } = await import('./public/helix_modules/humanoid-character/index.js');
+
+async function load(path) {               // Node cannot decode KTX2: drop textures, keep skins + extras
+  const io = new NodeIO().registerExtensions(ALL_EXTENSIONS);
+  const doc = await io.readBinary(new Uint8Array(readFileSync(path)));
+  for (const t of doc.getRoot().listTextures()) t.dispose();
+  for (const e of doc.getRoot().listExtensionsUsed()) if (/texture|basisu|webp/i.test(e.extensionName)) e.dispose();
+  const glb = await io.writeBinary(doc);
+  return new GLTFLoader().parseAsync(glb.buffer.slice(glb.byteOffset, glb.byteOffset + glb.byteLength), '');
+}
+const [avatarPath, controlPath, clipDir, framesOut] = process.argv.slice(2);
+const avatar = (await load(avatarPath)).scenes[0], control = (await load(controlPath)).scenes[0]; // LOD0
+const LIMBS = ['spine_03', 'head', ...['upperarm', 'lowerarm', 'hand', 'thigh', 'calf', 'foot'].flatMap((b) => [`${b}_l`, `${b}_r`])];
+const bone = (root, n) => { let b = null; root.traverse((o) => { if (!b && o.isBone && o.name === n) b = o; }); return b; };
+const canonical = new Set(); control.traverse((o) => o.isBone && canonical.add(o.name));
+const meta = JSON.parse(readFileSync(`${clipDir}/clip-meta.json`, 'utf8'));
+const report = {}, frames = {};
+for (const name of ['locomotion.idle', 'locomotion.walk', 'locomotion.run']) {
+  const clip = (await load(`${clipDir}/${name}.glb`)).animations[0];
+  const speed = meta.find((m) => m.name === name)?.strideSpeed ?? 0, dt = 1 / 60;
+  const mixers = [avatar, control].map((m) => { const x = new THREE.AnimationMixer(m); x.clipAction(clip).play(); return x; });
+  avatar.position.set(0, 0, 0);
+  const dyn = new DynamicsLayer(avatar, { isLocal: true });
+  const aux = []; avatar.traverse((o) => { if (o.isBone && !canonical.has(o.name)) aux.push(o); });
+  // Each aux bone's aim, in its own local frame: toward its child bone, or the chain's endpoint.
+  const endpoints = new Map();
+  for (const sc of [avatar]) for (const ch of sc.userData.helixDynamics?.chains ?? []) {
+    let b = bone(avatar, ch.root); while (b && b.children.filter((c) => c.isBone).length === 1) b = b.children.find((c) => c.isBone);
+    if (b && ch.endpoint) endpoints.set(b, new THREE.Vector3(...ch.endpoint));
+  }
+  const aim = new Map(aux.map((b) => [b, (b.children.find((c) => c.isBone)?.position.clone() ?? endpoints.get(b) ?? new THREE.Vector3(-1, 0, 0)).normalize()]));
+  const rest = new Map(aux.map((b) => [b, b.quaternion.clone()]));
+  let worstAt = null;
+  const skinned = []; avatar.traverse((o) => o.isSkinnedMesh && skinned.push(o));
+  const edges = skinned.map((m) => {      // unique edges with their bind lengths
+    const idx = m.geometry.index.array, pos = m.geometry.attributes.position, seen = new Set(), out = [];
+    for (let t = 0; t < idx.length; t += 3) for (const [a, b] of [[idx[t], idx[t + 1]], [idx[t + 1], idx[t + 2]], [idx[t + 2], idx[t]]]) {
+      const k = Math.min(a, b) * 1e7 + Math.max(a, b); if (seen.has(k)) continue; seen.add(k);
+      out.push([a, b, new THREE.Vector3().fromBufferAttribute(pos, a).distanceTo(new THREE.Vector3().fromBufferAttribute(pos, b))]);
+    }
+    return out;
+  });
+  let limb = 0, stretch = 0; const swing = {};
+  for (let i = 0; i < Math.round((2 * clip.duration) / dt); i++) {
+    mixers.forEach((x) => x.update(dt));
+    avatar.position.z += speed * dt;      // carry the body forward so springs feel the anchor's velocity
+    avatar.updateMatrixWorld(true); control.updateMatrixWorld(true);
+    dyn.update({ dt, cameraDistance: null, gate: 1 }, 1);
+    avatar.updateMatrixWorld(true);
+    for (const n of LIMBS) {
+      const a = bone(avatar, n), c = bone(control, n); if (!a || !c) continue;
+      limb = Math.max(limb, THREE.MathUtils.radToDeg(a.getWorldQuaternion(new THREE.Quaternion()).angleTo(c.getWorldQuaternion(new THREE.Quaternion()))));
+    }
+    if (i * dt < 1) continue;             // skip the spawn warm-up
+    for (const b of aux) swing[b.name] = Math.max(swing[b.name] ?? 0, +THREE.MathUtils.radToDeg(aim.get(b).clone().applyQuaternion(b.quaternion).angleTo(aim.get(b).clone().applyQuaternion(rest.get(b)))).toFixed(1));
+    if (framesOut && i % 6 === 0) (frames[name] ??= []).push(Object.fromEntries(aux.concat(LIMBS.map((n) => bone(avatar, n)).filter(Boolean))
+      .map((b) => [b.name, b.quaternion.toArray().map((x) => +x.toFixed(5))])));
+    if (i % 15) continue;                 // 4 Hz: worst edge stretch of the skinned surface
+    skinned.forEach((m, k) => {
+      const cache = new Map(), at = (v) => cache.get(v) ?? cache.set(v, m.getVertexPosition(v, new THREE.Vector3())).get(v);
+      for (const [a, b, len] of edges[k]) {
+        const d = at(a).distanceTo(at(b)) - len;
+        if (d > stretch) { stretch = d; worstAt = { mesh: m.name, vertex: a, bindY: +m.geometry.attributes.position.getY(a).toFixed(2), bindX: +m.geometry.attributes.position.getX(a).toFixed(2) }; }
+      }
+    });
+  }
+  report[name] = { limbDegVsControl: +limb.toFixed(2), stretchCm: +(stretch * 100).toFixed(1), worstEdgeAt: worstAt, dynamics: { active: dyn.active, rejected: dyn.rejected, ...dyn.cost }, swingDeg: swing };
+}
+if (framesOut) writeFileSync(framesOut, JSON.stringify(frames));   // local quaternions every 0.1 s, for rendering
+console.log(JSON.stringify(report, null, 2));
+```
+
+Read the report for each clip:
+
+| Field | Meaning | Pass |
+| --- | --- | --- |
+| `limbDegVsControl` | Worst world-rotation difference of any limb bone against the control. | ≤ 2°. The stock body against itself reads 0.01 / 0.48 / 0.8° (idle / walk / run). That is the noise floor. More than 5° means a rest-frame or bone-map error. |
+| `stretchCm`, `worstEdgeAt` | Worst growth of any mesh edge over its bind length, and where: the mesh, vertex and bind x/y. | Close to the control. Stock Base Female reads 1.3 / 2.1 / 4.4 cm. Loose cloth stretches more: Cream Hoodie's armpit and sleeve cloth shipped at 5.8 cm walking and 8.9 cm running, by the lane's own probe. **10 cm or more:** look up where it is. If it sits between two body parts (inner thighs, cuff to hip, chest to arm), it is a weight bridge, so fix the weights (`source-generated` step 5). If it is cloth stretching over a joint, render that frame and judge it. |
+| `dynamics.active`, `rejected` | Whether the engine accepted the manifest. | `active: true` and `rejected: []`. A rejected manifest means **no physics anywhere**. |
+| `swingDeg` | Peak deflection of each auxiliary bone's aim (toward its child, or its chain's `endpoint`) from rest, after warm-up. | Inside its cone, and enough to read. Restrained hood hair read 6–9°; visible long hair 10–25° walking. A value pinned at the cone limit while walking means too little inertia. Near 0° walking means too stiff to notice. |
+
+The probe cannot see two things: a strand passing through the body or collar, and the look of it.
+**Render the frames it solved.**
+1. Pass a fourth argument, for example `frames.json`. The probe writes every auxiliary and limb
+   bone's local quaternion every 0.1 s, per clip.
+2. In a **headless** three.js page (`GLTFLoader` with `KTX2Loader` and the basis transcoder), load the
+   avatar's LOD0 scene.
+3. For each frame, copy those quaternions onto the bones by name, then render a side, back and
+   three-quarter view of the head and shoulders.
+4. Look at the running frames for hair passing through the hood, collar or shoulders.
+
+The live surfaces in step 5 are the final word.
+
+## 4. Platform visual QA
+
+Run `visual_qa_item_hosted({ itemId })` (or `visual_qa_item` with a QA sign-in). It must pass, with
+no override. What each assert measures, and how to fix a failure, is in
+`read_skill({ name: "helix-avatar-qa" })`.
+
+The gate has two stages. Stage 1 is the Try Now walk in the world. Stage 2 (route `avatar@3`) is the
+Marketplace item page's own walk, seen from the true sides and back: it blocks arms bound too close to
+the body (the walk adducts ~24° from the clip's A-pose, so bind them near the standard 36°), forearms
+buried in the torso, a surface that opens at the side as an arm swings, stray strands, and a hung
+silhouette or leaning posture. A `not measured` result fails the run. Your own run of step 3 does not
+replace it: the probe's controls measure rig noise, the gate measures what a buyer sees.
+
+**Open the contact sheet anyway**, especially the `motion.preview.*` side and back frames. A pass says
+the avatar renders, walks and does not tear in those frames. It says nothing about:
+- dynamics;
+- the face;
+- first-person hide;
+- how close the avatar is to the reference.
+
+Cream Hoodie 1.0.0 passed an earlier version of the gate with a 9 cm hip spike, so keep measuring
+`stretchCm` yourself. Cream Hoodie Anime Girl 1.0.6 passed `avatar@2` with arms bound at 13-15° that
+walked inside the hoodie, a torn side and a rigid hair slab; that is what stage 2 now blocks, and the
+hair slab is still the critic's call on the side frames, not a number.
+
+## 5. Live close-ups, in both surfaces
+
+Capture both. Each one uses a different code path.
+
+- **The Marketplace item preview.** It runs every dynamics chain at 60 Hz with no budget, on the
+  WebGPU renderer.
+  - Headless macOS Chromium drew nothing for the earlier lanes: Tint "swizzle view instruction still
+    has usages after lowering". Cream Hoodie rendered headless on a real Metal adapter.
+  - Record the adapter. If you get no frames, render on a machine with a discrete GPU instead.
+- **In-world, through Try Now.** Use a signed-in QA account in the test grounds.
+  - Check that the GLB sha256 the world downloaded matches your file.
+  - Record the ready time, distance walked, idle arm angle and sole range.
+  - Capture close-ups: face, hands, feet, and hair or tail at idle, at mid-stride walking, and
+    running.
+  - **Headless camera gotchas:**
+    - The camera starts behind the character, and pointer-lock orbit does not work headless. Walk
+      toward the camera for front shots, or re-aim the world camera from a render hook.
+    - Take walk frames at ≥ 92 % of the stride's own maximum foot separation. A mid-hop frame decided
+      one critic round.
+  - Record the engine version the world resolved while you test (the served `…/runtime/^0.3/…` redirect and the
+    bundle's `VERSION`). Worlds pick up the live `^0.3` range, so an engine release mid-run can change the result —
+    compare runs by that recorded version. Do NOT exact-pin helix.json to freeze it: publish refuses exact engine
+    pins. For a one-off local comparison use the visual-QA engine override (`HELIX_VQA_ENGINE_RUNTIME=<version>`).
+
+## 6. Blind critic against the reference
+
+The bar is the real reference: photographs of the real robot, actor or prop, the source game's own
+renders, or the concept art.
+
+1. Render a fixed set of 11–12 frozen frames per candidate, deterministic so that two runs diff to
+   0. Include a turnaround, face, hands, feet and the dressed close-ups, plus a walk frame with
+   dynamics running.
+2. Give a fresh critic agent that never saw the build an X/Y pair with the labels shuffled. Keep the
+   key outside the packet.
+3. The critic must **pick a side before scoring**, with no ties.
+4. Keep the incumbent unless the challenger wins head-to-head. Always re-anchor on the true
+   incumbent: one lane paired two losers by mistake.
+
+Every avatar lane exited on a **plateau** of 6–7/10, not a win. Generated sources plateau lower.
+Report which exit you took.
+
+## What eyes caught that numbers missed
+
+- A flat white avatar: an emissive factor left without its map.
+- A smeared mouth and blocky hair: the importer's rebake.
+- Forearms walking inside the hoodie, the side torn open as an arm swung back, back hair standing off
+  as a slab, a strand at the waist: seen only from the side in the Marketplace walk. Arms bound at
+  13-15°, fused sleeve/torso triangles cut into holes, hair weighted to arm and clavicle bones.
+- A dented chest with arm swing, and a spike at the hip: auto-rig weights. The verifier, the bind
+  check and visual QA all passed it.
+- A 60 cm chest spike, invisible in the game's own clips: chest vertices weighted to a foot.
+- Feet sinking 2–5.7 cm on a short robot: the short-body gate skipped retargeting.
+- Hair smearing into the hood while running, but fine while walking.
+- Ears swinging 100°+ at a sprint: loose inertia and no limit.
+- Chrome rendering near black: metallic 1.0 under the world sky.
+- A normal map reading as hammered foil: ETC1S on the normal map.
+- Hard-surface LODs tearing into shards: collapse decimation.

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

@@ -0,0 +1,88 @@
+# Rigging: getting any mesh onto `helix-humanoid@1`
+
+The importer, `helix character import` (or MCP `import_character`), does the last step. It maps the
+source skeleton onto the canonical 68 joints, conforms them to rest, builds LODs and KTX2, and splits
+`FaceMesh`. Your job is to hand it a source it can map: a skinned mesh in the canonical frame, close
+to the A-pose, with bones it can name.
+
+## Bone maps
+
+- `--map <json>` takes `{ "name", "version", "comment", "map": { "<sourceBone>": "<helixBone>" } }`.
+- Without `--map`, the importer picks MetaHuman when it recognises it, or else the best of its
+  built-in Meshy, Mixamo and Mixamo-FBX maps. A Meshy or Dreamer rig needs no map.
+- If you author the rig yourself (in Blender, from a CAD tree or a game rig), **name the bones with
+  the canonical helix names** and pass an identity map. Leave fingers and twists unmapped if you did
+  not build them. The importer then leaves them at rest, and fingers ride rigidly on `hand_*`.
+- `--fit source` keeps the model's own proportions and embeds the canonical skeleton at its joints.
+  Every lane used it. `--fit canonical` re-poses the model to canonical proportions instead.
+
+## The canonical rest, as data
+
+To aim limbs at the A-pose, you need the canonical rest transforms: per bone, the parent, the
+position and the rotation, at the 1.7 m canonical body's metre scale. Read them from a base avatar's
+LOD0 skin: the stock `body-m-default.web.glb` or `body-f-default.web.glb`. Download them from the
+asset pack of a throwaway character world; `qa` step 3 gives the commands.
+
+Aim these at the canonical directions:
+- **upper arm, forearm, thigh and calf:** by bone direction plus the elbow or knee hinge plane;
+- **hands:** by direction plus the palm axis;
+- **feet:** by **yaw only**, so the soles stay flat.
+
+Then bake the pose into the mesh. If you skip this, `conformed.restAimed` does the aiming, and a
+hard-surface part bound to a moved bone will shear.
+
+## Pick the binding that matches the source
+
+| Source | Binding | Lane |
+| --- | --- | --- |
+| Rigid mechanical parts (a robot, CAD, armour plates) | **Rigid 1:1.** Every part is weighted 1.0 to exactly one bone. Joints sit at the mechanical pivots. Parts spanning two bones are split, or become **pistons**: each half is rigid to its own bone, so they telescope. Thin cables keep blended weights. | Unitree G1, C-3PO, T-800 |
+| A properly skinned game character on an Epic- or Valve-style skeleton | **Keep its weights.** Rename the canonical joints and **fold every helper joint** into its nearest canonical ancestor. Helper joints are twist helpers, `deform_*`, `Dyn_*` physics joints, `attach_*`, `*_end`, metacarpals. The game's weights survive. | Daft Punk (Fortnite), Iron Man (Valve biped, shoulder pads split 50/50 between clavicle and upper arm) |
+| Skinned, but posed in the mesh, or carrying bad weights | **Aim to the A-pose, then bind per part:** rigid if one bone carries at least 90 % of the part, piston if it spans two bones, blended otherwise. | T-800 |
+| Meshy or Dreamer auto-rig | **Keep the weights, then repair them.** The auto-rig bleeds arm weight into the torso and hips. See `source-generated`. | Cream Hoodie |
+| VRM | Do not rig. The bridge reads the file's own humanoid map. | See `source-vrm` |
+
+**Weight sanity.** Apply these on every non-trivial source:
+- **Drop any influence from a bone whose segment (from the joint to its child) is more than 0.3 m
+  from the vertex.** Measure to the segment, not the joint head: a long thigh's own vertices sit
+  further than 0.3 m from its head. MK11's chest vertices weighted
+  to the right foot drew a 60 cm spike, and it was invisible in the game's own clips.
+- Hard-surface plates dominated by one bone at 75 % or more get one constant blend. Otherwise they
+  bend like rubber.
+
+## T-pose hides skin-index bugs
+
+Wrong `JOINTS_0` indices look perfect at bind, because every joint is at its bind pose and the error
+multiplies out to identity. They show only when a clip moves the bones. So read back, for each LOD:
+- **the names** of the joints that carry weight on each region;
+- whether any vertex is weighted to an implausible bone (a foot on the chest, a hand on the hip);
+- the worst edge stretch over walk and run frames, compared against a base body playing the same clip
+  (see `qa`).
+
+Most bad weights get past the platform gates:
+- the backend verifier passed Cream Hoodie 1.0.0;
+- the engine bind check passed it;
+- visual QA passed it too, with a 9 cm spike at the hip while walking (16 cm running).
+
+Route `avatar@3` now catches three rig faults in the Marketplace walk: **arms bound too near straight
+down** (under 17°; standard 36°), **a surface that opens at the seams** as a limb swings, and **forearms
+sunk in the torso**. Bind arms near the canonical A-pose, and never cut fused sleeve/torso triangles to
+hide a bad weight; fix the weight (`source-generated` step 5). Spike and stretch faults still need your
+own probe.
+
+## Proportion edits
+
+- Scale to the real height: Unitree G1 1.32 m, C-3PO 1.67 m, T-800 1.88 m, Iron Man 1.98 m.
+- Widen girdles only from measured reference proportions, and move whole limb chains rigidly. T-800's
+  shoulders were widened 12 % and its pelvis 8 %.
+- A 5 % head scale-up read as stocky and lost the critic round.
+
+## Tooling
+
+- Use headless Blender for posing, binding and baking.
+- Use `@gltf-transform/core` for JSON and accessor surgery.
+- Use `meshoptimizer` or the importer for LODs. **Hard-surface plates decimated with Blender's
+  collapse tear into shards.** Two fixes worked:
+  - per-region meshoptimizer ratios (T-800);
+  - voxel-remeshed closed shells (12 mm / 20 mm) for LOD1 and LOD2, baked the same way as LOD0
+    (Iron Man).
+- Brackets that decimate badly can be replaced with convex hulls (Unitree G1).

package/skills/helix-avatars/references/source-generated.md

@@ -0,0 +1,190 @@
+# Source: generated characters (Dreamer image-to-3D, or any Meshy-rigged GLB)
+
+Generated characters are the fastest source and the most deceptive. Every gate passed the first
+Cream Hoodie build while it:
+- glowed flat white in drafts;
+- had a smeared mouth;
+- had a dented chest;
+- had a 9 cm spike at the hip.
+
+Plan for every step below. The template lane is Cream Hoodie Anime Girl (helix3, 2026-10-03), the
+first avatar through the visual-QA avatar route with no override.
+
+## 1. The input image
+
+- Image-to-3D wants a clean **four-view A-pose turnaround**: front, back, left and right. A single
+  small illustration does not work; 214 × 395 px was too small. Make or edit a turnaround first.
+- **Layout: 2×2, 1×4 or 4×1, in the order front, back, left, right** (row left to right, column top
+  to bottom, grid reading order), with **exactly one figure per view**. Dreamer finds each figure
+  against the background, cuts the sheet through the empty gutters between them, and **refuses the
+  upload before anything is created or charged** when it cannot: the error says how many figure
+  columns and rows it found (`found 3 figure column(s) …`) or which panel is empty or holds two
+  figures. A figure that touches or crosses its neighbour leaves no gutter, so keep a visible gap and
+  turn the two profiles to face opposite ways.
+- **Make the figures stand out from the background.** Detection works from the colour distance to a
+  flat background; a cream outfit on light grey is only about 40 levels away, white on white is
+  invisible. Use a **mid or dark neutral grey** (or a clean flat colour unlike the clothes), no
+  gradients, no frames, no captions touching the figures. A clean sheet reads fine on light grey; a
+  pale one on a pale background does not.
+- **Open the sheet and look at it before you generate:** four panels, one figure each, a visible gap
+  between them. Passing the layout check is not a promise the semantic gate agrees on which view is
+  which.
+- Why this is written down: on 2026-10-06 a 1536×1024 four-in-a-row sheet of a cream figure on light
+  grey was read as a 2×2 grid, Meshy was given the front and back figures as one view and built a
+  two-figure mesh (123 LIX). The detector has been fixed; the same sheet is now read as 1×4. When you
+  cannot get a clean row, re-lay the figures yourself as a 2×2 on a darker grey (that is what worked).
+- Lower legs, boots and the back that the source does not show are inferred. Say so in the item
+  description if they matter.
+- **Generative variance is real.** A second generation from a corrected sheet lost to the first, 5.0
+  vs 7.0. Do not re-run hoping for luck: fix what you have.
+
+## 2. Generate
+
+```
+generate_asset({ kind: "character", prompt, title, referenceSheetPath: "/abs/sheet.png", visibility: "private" })
+# CLI: helix assets generate-reference sheet.png "<prompt>" --visibility private
+```
+
+The server runs mesh, texture, rig, LOD, thumbnail and publication; 123 LIX in the lanes. Two
+problems with the draft it publishes:
+
+- **Visibility.** Pass `visibility: "private"` for a draft you will rebuild. Until 2026-10-03 the
+  server ignored it and listed drafts publicly. That is fixed, but confirm with `search_items` after
+  generation anyway. A raw draft that did go public gets `delist_item` before anyone buys it.
+- **The draft is not your avatar.** The server imported it with the automatic rebake. Treat the draft
+  as a source.
+  - For a hero result, rebuild from the **raw rigged GLB** with the steps below.
+  - Dreamer does not keep the raw rig; a platform operator can re-fetch it by the job's rigging task.
+  - If you cannot get it, repair the draft in place, applying steps 4–6 to every LOD. The rebake
+    damage stays.
+
+## 3. Strip the emissive before import
+
+The raw material carries a **black emissive map with `emissiveFactor [1, 1, 1]`**.
+
+- An importer that drops the map but keeps the factor renders the **whole avatar glowing flat
+  white**. This was a stop-ship.
+- That is fixed in the importer: CLI `0.1.18-helix3.351` and later never keep an emissive factor
+  whose map was dropped, and strip flat-black emissive maps. The visual-QA gate's emissive wash-out
+  assert also fails it now.
+- Strip both from the source anyway. It costs nothing, and it keeps the material honest for any tool
+  you run before the importer.
+
+After import, check that no material keeps an `emissiveFactor` without an `emissiveTexture`.
+
+## 4. Import without the rebake
+
+```
+helix character import raw.glb -o out --name <slug> --lod-tris 30000,15000,5000 --tex-size 2048 --no-bake --ktx-mode etc1s
+```
+
+- `import_character` passes `bake: false`, `ktxMode` and `lodTris`. The default Meshy bone map is
+  picked automatically.
+- The source's micro-chart atlas **triggers the automatic weld, unwrap and rebake**. On Cream Hoodie
+  that smeared the mouth into the chin and turned hair strands into blocks. `--no-bake` keeps the
+  source UVs, and it beat the rebake 6.5 to 5.0 in the blind critic round.
+- ETC1S at 2048 kept Cream Hoodie at 7.06 MB, normal map included. That is fine for soft cloth
+  and skin. The "hammered foil" ETC1S artefact (`source-model`) shows on glossy hard surfaces, so
+  judge it in close-ups.
+- A generated source has no external URL or licence. Leave `--provenance` off, and record the Dreamer
+  job id in your ledger.
+
+Texture retouching (colour grading cloth or irises, projecting a clean face) is done on the source
+atlas before import. Gain-match it to the skin, and judge it in the critic loop. Colour-only tweaks
+oscillated between "too warm" and "too cold".
+
+## 5. Repair the auto-rig weights
+
+Three Meshy defects only show in the Marketplace walk, seen from the side and back
+(`avatar.bind_pose`, `avatar.preview.*`, see `helix-avatar-qa`):
+- **Arms bound near straight down** (13-15° on the hoodie; standard is 36°). The walk adducts the arm
+  ~24° from the clip's A-pose, so the forearms walk inside the body. Re-bind the arms near Base Female's
+  A-pose (the rework used +6° for oversized sleeves): a rotation-only re-bind of upperarm/lowerarm,
+  baked into POSITION/NORMAL/TANGENT, with IBMs and node rotations rewritten on every LOD.
+- **Arm and clavicle weights in the hair.** Hair belongs to the head and the hair chains only. A big share
+  of the mesh on a few stiff joints reads as a rigid slab behind the back.
+- **Neck and head bound off canonical**, so the head droops or pushes forward with the walk.
+
+The auto-rig blends arm weight into the torso and fuses sleeve cuffs to the hips. Cream Hoodie's raw
+rig had:
+- 4,121 central-torso vertices with more than 10 % upper-arm weight, so the chest dented with every
+  arm swing;
+- hem vertices weighted to the forearm and thigh, one at 0.51 / 0.32, which stretched an edge 9 cm
+  walking and 16 cm running. It showed as a thin line out of the hip in the Marketplace preview.
+
+The fix that worked:
+1. Change only vertices that carry **both** arm weight (upper arm, lower arm, hand, fingers) **and**
+   body weight (spine, pelvis, legs, clavicle).
+2. Classify each one by **geometry**. It is arm surface if it lies within sleeve radius of its side's
+   arm bones (0.095 m for the upper arm, 0.08 m for the forearm and hand) **and** its normal faces
+   away from the arm axis. Otherwise it is body.
+3. Classify per **welded vertex group**, not per vertex. Seam duplicates have different normals, so
+   classifying them separately leaves 0.5 / 0.5 blends. Then diffuse the arm share over the welded
+   mesh so the boundary does not crease, but **only above the hem**. Diffusing across the cuff-to-hip
+   contact spread the bridge and made the stretch worse: 17 / 28 cm. The cut-off was about
+   y = 1.2 m on a 1.75 m body; find yours by sweeping it against the probe.
+4. Keep the old relative weights inside each group.
+5. **Do not cut the fused sleeve/torso surface.** The 1.0.x lane cut the cuff-to-hip bridge below the armpit
+   (364 / 203 / 79 triangles per LOD). It was real cloth: the cut left holes, and the hoodie's side tore open as
+   an arm swung back in the Marketplace walk (`avatar.preview.surface_closed`, 36 cm). Keep every triangle and
+   fix the **weights** so the sleeve follows the arm and the hem the hip. Hard or geodesic arm/body splits and
+   cut-and-cap also tore the shared armpit and hem (10-23 cm); the rework that passed kept the surface whole,
+   re-bound the arms (above) and left a residual cuff/hem stretch of ~10 cm, hidden behind the arm.
+6. Rewrite `JOINTS_0` and `WEIGHTS_0` **in place**, identically on every LOD. Leave `POSITION` alone.
+
+**Hands fused to the thighs.** Meshy generates in an A-pose with the hands resting on the thighs, and
+its mesher merges the two surfaces. A strip of triangles then runs from the inside of the hand and
+forearm to the outside of the thigh, and the rigger spreads thigh weight over the hand and hand weight
+over the thigh. Standing, it looks fine. In the walk the arm swings forward as the leg swings back, and
+the strip tears into a sheet from the wrist to the knee, or into a "sleeve sheet" from the forearm.
+- Measure it before trusting a render. Count triangles with one corner owned (>= 0.5 weight) by an arm
+  and another by a leg. Clean Meshy rigs have 0–8. Dreamer item 4400fe58 had 342: skin_intact read
+  4.5% stretched (limit 1.5%), and the critic saw a smeared sheet from the arm to the rear leg.
+- The importer repairs it. `helix character import` cuts the bridge, closes both holes, and strips the
+  other limb's weight from each side, on the full mesh and again on every LOD. It is on by default
+  (`--limb-bridges repair`); `--limb-bridges report` logs what it would change and changes nothing.
+  It sides contact vertices by geometry, because the bled weights cannot tell the thigh under the hand
+  from the hand. It keeps the cut only when a two-stride stretch measure falls. It never cuts any other
+  pair, so skirts, pockets, capes and sleeves are left alone.
+- A Dreamer draft built before the importer had this step keeps the defect. Re-fetch the raw rig and
+  re-import it. 4400fe58 re-imported this way fell from 4.5% to 0.09% edge stretch and passed visual
+  QA.
+- The caps are flat patches under the arm, in one cloth colour. They are hidden in normal play. Look
+  at them close up anyway: a cap that folds or takes a seam texel reads as a dark shard at the hip.
+
+**The legs fuse too.** Inner-thigh vertices often carry both `thigh_l` and `thigh_r` weight. That
+gave 14 cm of stretch at a run after the arms were fixed. Snap each welded group to the leg on its
+side of the mid-plane, and cut the crotch bridge triangles. Check the front of the crotch in a
+render afterwards: the cut can leave a small notch.
+
+Measure the result against a base body; see `qa`. Torso vertices with upper-arm weight fell from
+4,121 to 169. Worst stretch fell from 9.1 to 5.8 cm walking and from 16.1 to 8.9 cm running, against
+Base Female's 0 and 4.4 cm on the same probe.
+
+## 6. Dynamics
+
+A generated character is **one fused shell**: hair, hood, face and body are welded together. So:
+- select hair by its baked colour per LOD, and blend weights through a diffused field;
+- anchor back hair on the bone it rests on (`spine_05` on a hood);
+- **drop front locks on hooded or high-collar characters**. They smeared into the collar while
+  running.
+
+The full method and values are in `dynamics`.
+
+## 7. What you cannot fix, so say so
+
+- **Some outfits come out pale and glossy.** The material ships roughness around 0.45, so a
+  cream or white hoodie reads washed out and near-glowing under the engine's lights, against its own
+  albedo. The critic fails `avatar.textures` for it, and its verdict varies run to run. Check the
+  roughness the import kept before blaming the lights.
+- **Thumbnails may come back flat-shaded.** The server thumbnail renderer may draw triangles
+  flat-shaded, which makes a smooth avatar look faceted in listings. That is still being checked.
+  Judge shading in the visual-QA frames, not in the thumbnail.
+
+- The face carries no blink or viseme channels: `face: none`. The avatar is mute in voice chat. A
+  projected, calm closed-mouth face texture reads better than a smeared one.
+- Generated texture flaws (smeared eye or brow texels, ribbed hair, melted laces, fringe texels)
+  survive every tuning pass. Both generated lanes exited their critic loop on a plateau of 5.8–7.0,
+  not a win. Report that honestly.
+- Toes usually point about 25° off forward because of where the foot joint was placed. It is a
+  visual-QA **warning**, not a failure. Check the feet in the walk frames.

package/skills/helix-avatars/references/source-model.md

@@ -0,0 +1,90 @@
+# Source: a rigged game or downloaded character (rips, mods, Sketchfab, FBX/GLB)
+
+Lanes: Daft Punk (Fortnite rips), T-800 (a Mortal Kombat 11 model from the SFM workshop), Iron Man
+Mark III (a Garry's Mod player model).
+
+## Acquire, and score the candidates
+
+- **Prefer a skinned, textured source on an Epic- or Valve-style biped.** The deciding features are:
+  - real skinning;
+  - textures at 1–2k;
+  - the right variant (outfit, mark, era);
+  - enough triangles to decimate from: 100k–450k worked.
+- **Reject** these:
+  - a low-poly console rip when a better source exists (Iron Man passed over a 10k PS3 rip);
+  - a model of the wrong variant;
+  - a model you cannot download.
+- **Tools that worked:**
+  - Workshop items: `steamcmd +login anonymous +workshop_download_item <app> <id>`.
+  - Source-engine `.mdl`: Blender with SourceIO.
+  - Textures: `srctools` to decode VTF.
+  - A viewer-only web model: hook WebGL in a headless page and decode its buffers. This reproduced
+    C-3PO's 120,988 triangles exactly.
+- **Record what is missing.** Daft Punk's sequin outfit was separate geometry the rip lacked, so the
+  leather outfit shipped. Do not invent parts.
+
+## Pose and rig
+
+Choose by what the source gives you. The full table is in `rigging`.
+
+| Source | Approach |
+| --- | --- |
+| Clean game skinning on a mannequin-like skeleton (Fortnite) | Keep the weights. Rename the 68 canonical joints, and fold every helper (twist helpers, `deform_*`, `Dyn_*`, `attach_*`, metacarpals, `*_end`) into its nearest canonical ancestor. |
+| A posed mesh with dubious weights (MK11) | Aim the limbs at the canonical A-pose, then bind **per part**. Drop influences from bones more than 0.3 m away. |
+| A Valve biped (GMod) | Re-pose to the A-pose: aim each segment, roll the hands onto the canonical palm axis (60 % forearm twist, 40 % wrist), and **yaw the feet only**. Then build a fresh rig with the Valve weights renamed. Split shoulder pads 50/50 between clavicle and upper arm, and make plates rigid at a 75 % dominant share. |
+
+Before import, lift the soles to just above Y = 0. T-800 used 1 cm and Iron Man 8 mm, measured
+against a canonical idle.
+
+## Materials
+
+Convert the game material model to glTF PBR and keep it to **1–2 materials**, because draws are
+paid once per LOD.
+
+| Source maps | glTF |
+| --- | --- |
+| Diffuse | Base colour |
+| Spec/gloss or a packed S map (R = spec, G = roughness, B = metallic) | ORM |
+| DirectX-convention normals | **Flip green** to the OpenGL convention |
+| Glowing parts: visors, eyes, reactors, displays | An emissive map. Paint animated displays the export lost, through a UV-to-surface probe. |
+
+Lessons from the critic rounds:
+- Fully metallic 1.0 chrome renders **near black** under the world sky. 0.9–0.92 beat 1.0.
+- A slightly darker chrome lost its round. Keep the source's value unless the reference says
+  otherwise.
+- **The normal map needs UASTC.** An ETC1S normal or base map reads as hammered foil under the
+  marketplace's room lighting. ETC1S is fine for ORM, emissive, and every LOD1/LOD2 map.
+
+## Geometry and LODs
+
+- Cull what can never be seen. An embree visibility pass kept 53 % of Iron Man's triangles.
+- Close see-through gaps between plates with a dark undersuit shell. A near-black underlayer read as
+  holes in the critic round; gunmetal won.
+- LOD0 can be a baked low-poly. Use Blender collapse with area-weighted normals, then a Cycles bake
+  of base colour, normal, ORM and emissive onto an xatlas atlas.
+- **Hard-surface LOD1 and LOD2 tear into shards when decimated directly.** Use either:
+  - per-region meshoptimizer ratios (T-800: head 0.55, hands 0.6, feet 0.3, body 0.3); or
+  - voxel-remeshed closed shells at 12 mm and 20 mm, decimated and baked the same way (Iron Man).
+- **The importer's own LODs scramble a many-chart atlas.** On Iron Man they kept only 49 % and 37 %
+  UV coherence. Fixes:
+  - pass `--no-bake`;
+  - pass `--lock-border` to stop seams opening;
+  - or build LOD1/LOD2 yourself and swap them into the imported file by joint name, then run the
+    importer's own finishing checks again (self-contained scenes, canonical geometry, split face).
+
+## Import
+
+```
+helix character import src.glb --map identity-map.json --fit source -o imp --name <slug> \
+  --lod-tris 48000,8000,3900 --tex-size 2048 --ktx-mode etc1s --ktx-quality 255 --no-bake --lock-border
+```
+
+`import_character` exposes these flags too: `map`, `fit`, `bake`, `lockBorder`, `ktxMode`. Stay under
+60k triangles across all LODs, 12 draws and 10 MiB. Iron Man shipped at 9.75 MiB with a UASTC normal
+map.
+
+## A helmet or a mask
+
+Keep a helmet as its own mesh if it needs its own material, and list it in
+`helixAvatar.firstPersonHide` on **every scene**, for example `["HelmetFaceMesh", "FaceMesh"]`.
+Otherwise the first-person camera looks out through the inside of the helmet.