@hypersoniclabs/helix-mcp 0.2.4 → 0.2.12

package/skills/helix-assets/references/asset-sources.md

@@ -0,0 +1,143 @@
+# CC0 asset sources — query recipes and traps
+
+The five sources the skill body lists, in enough detail to fetch from without a round of
+trial and error. Every endpoint and count here was re-verified against the live service; if
+one starts 404ing, say so in the report rather than inventing a replacement.
+
+## Poly Haven — `https://api.polyhaven.com`
+
+Free, no key, CORS-open, **CC0**. HDRIs, textures and models by a small paid-in-house team,
+which is why the licence is uniform rather than per asset.
+
+```bash
+curl -s https://api.polyhaven.com/types                         # ["hdris","textures","models"]
+curl -s https://api.polyhaven.com/categories/models             # 45 categories
+curl -s "https://api.polyhaven.com/assets?type=models&categories=furniture"   # 85 records
+curl -s https://api.polyhaven.com/info/wooden_table_02          # one record
+curl -s https://api.polyhaven.com/files/wooden_table_02         # download URLs, per format/res
+```
+
+There is **no free-text search**. Filter by `categories=` (comma-separated, AND-ed) and match
+`tags` yourself from the list response — it already contains every field you need, so this
+costs one request, not one per asset.
+
+**Budget before you download.** All 521 model records carry `polycount` and
+`max_resolution`; texture and HDRI records carry `max_resolution`. Nothing else in this list
+lets you reject an asset on triangle count without fetching it first. Filter the list
+response, *then* hit `/files`.
+
+```js
+const models = await (await fetch('https://api.polyhaven.com/assets?type=models')).json();
+const affordable = Object.entries(models)
+  .filter(([, m]) => m.polycount < 8000)      // ArmChair_01 is 5,626; wooden_table_02 is 196
+  .map(([slug]) => slug);
+```
+
+`/files/<slug>` returns a nested `format → resolution → { url, size, md5 }`. For models take
+`gltf.1k.gltf` (or `2k`) — an object with a `url` plus an `include` map of every sibling file
+(`.bin`, `textures/*.jpg`) with its own URL and size. **Download the `include` map too**; the
+`.gltf` alone is a manifest pointing at files you did not fetch, and it fails at load with a
+404 per texture, not a clear error.
+
+Pick resolution by what the surface does: `1k` textures are ~120–180 KB each as JPEG,
+`4k` is ~10× that against a 50 MB bundle cap.
+
+**Container form:** `.gltf` + `.bin` + `textures/` — the second form `helix assets check-loaders`
+reads. One provenance row on the containing **directory** covers the whole set.
+
+**Attribution:** CC0 needs none, but `authors` is in every record (`{"Serhii Khromov":
+"All"}`) and `helix assets credits` will render it if you put it in the row's `attribution`.
+Crediting a CC0 author is free and correct.
+
+## ambientCG — `https://ambientcg.com/api/v2/full_json`
+
+Free, no key, **CC0**. 2,004 PBR materials (`numberOfResults` on an unfiltered
+`type=Material` query), plus 3D models, decals and HDRIs under other `type=` values.
+
+```bash
+curl -s "https://ambientcg.com/api/v2/full_json?type=Material&q=asphalt&limit=3"   # 78 hits
+curl -s "https://ambientcg.com/api/v2/full_json?type=Material&q=asphalt&limit=1&include=downloadData"
+```
+
+`q` is real full-text search over the asset's tags — this is the source to reach for when
+you know the surface by name ("asphalt", "paving stones", "rusted metal") and want maps that
+tile.
+
+Downloads live under `include=downloadData` →
+`foundAssets[].downloadFolders.default.downloadFiletypeCategories.zip.downloads[]`, one entry
+per resolution with a `fileName`, an `attribute` (`1K-JPG`, `2K-JPG`, …) and a **`size` in
+bytes**. Read `size` before you fetch:
+
+| attribute | example size (`PavingStones151`) |
+| --- | --- |
+| `1K-JPG` | 8.7 MB |
+| `2K-JPG` | 28.8 MB |
+| `4K-JPG` | 111 MB |
+| `8K-JPG` | 431 MB |
+
+**The bundle cap is 50 MB total.** A single 4K material blows it and an 8K material is 8× it.
+(The same restraint applies one rung up: the platform pack's `--resolution` lets you ask for 2K,
+which is for hero surfaces the camera gets close to — not a default to apply across a scene.)
+Take `1K-JPG`, `2K-JPG` only for a hero surface, and keep only the maps you actually bind
+(`_Color`, `_NormalGL`, `_Roughness`; skip `_Displacement` unless you are tessellating).
+The zips also carry `_NormalDX` — that is the flipped-green convention; three.js wants the
+**GL** one, and picking wrong reads as lighting that comes from the wrong side.
+
+One provenance row with a `*` covers the set: `assets/materials/asphalt_*.jpg`.
+
+## Kenney — `kenney.nl`
+
+No API. Per-pack ZIPs from the pack page, **CC0**, one named author. Low-poly modular kits
+(city, nature, dungeon, space), UI sprite sheets, and the SFX packs that **rung 2 of the
+audio chain** depends on — this is the "curated allowlist pack, licensor demonstrably the
+author" the audio section names.
+
+Packs ship `.obj` + `.mtl` alongside `.glb`/`.gltf` — take the glTF; the runtime loader
+allowlist has no OBJLoader. Kits are grid-aligned and share one palette texture, so pieces
+snap together and the whole kit is a handful of draw calls when instanced.
+
+## Quaternius — `quaternius.com`
+
+No API. Per-pack ZIPs, **CC0**, one named author. Stylized low-poly kits — characters,
+nature, vehicles, modular buildings — **atlas-textured**: an entire pack shares one small
+texture, which is the cheapest thing in this document against the texture budget. Some
+character packs ship rigged; check the skeleton against the 75-bone character budget before
+committing to one as a hero.
+
+## Poly Pizza — `https://api.poly.pizza/v1`
+
+**Free key required**, and it fails loudly and unhelpfully without one:
+
+```bash
+curl -s "https://api.poly.pizza/v1/search/chair"
+# 401 {"error":"You need an API key to do that dingus"}
+```
+
+That is a missing header, **not** a dead source — read it that way. Request a key at
+poly.pizza and send it as `x-auth-token`. 10,600+ low-poly models, including the rescued
+Google Poly archive, which is the reason to bother: it is the largest low-poly corpus in this
+list by an order of magnitude.
+
+**Licence is per asset, in a `licence` field: CC-BY 3.0 or CC0.** Do not assume the pile is
+CC0 — read the field on every asset you take, and record the exact value in the provenance
+row.
+
+A CC-BY row obliges attribution **that reaches the player** — in an in-world credits panel or
+a screen the player can open, not only in `ASSET-CREDITS.md` in the repo. And CC-BY **3.0**
+has no cure period: 4.0 lets you fix a breach within 30 days and reinstates automatically,
+3.0 does not. So a rendering bug that hides the credits panel is not a lapse you patch — it
+terminates the licence for that asset. If a world's credits surface is not built yet, take
+the CC0 rows and leave the CC-BY ones.
+
+## Not these
+
+| Source | Why not |
+| --- | --- |
+| Sketchfab | Mixed licence, with **NonCommercial and NoDerivs** in the pile. Per-asset checking at scale, and two of the licences in it are unusable to us at any price. |
+| Objaverse / Objaverse-XL | Largely GitHub and web scrapes with **no licence filtering** applied. Provenance you cannot record honestly is provenance you do not have. |
+| Freesound, OpenGameArt | **User-upload.** A "CC0" tag is an unverified assertion by an anonymous uploader — the same distinction the audio chain draws at rung 2. |
+| Anything a search engine handed you | No licence, no author, no record. |
+
+The line is not "free" versus "paid". It is **whether the licensor is demonstrably the
+author**. Poly Haven, ambientCG, Kenney and Quaternius publish their own work. A
+user-upload platform republishes a claim.

package/skills/helix-assets/references/vault-api.md

@@ -0,0 +1,105 @@
+# Vault — the asset library API
+
+The Vault is HELIX's shared asset library: a GIN-indexed full-text search over title,
+description and tags, plus structured filters. It is the step between "the catalog has no
+ability for this" and "generate something".
+
+An agent does not browse. It asks a precise question — *a humanoid-rigged character I can
+use in a web world* — and needs a small, correct answer. That is why every filter is
+structured; free text alone cannot express "rigged to the skeleton my world already uses".
+
+## Probe before you rely on it
+
+These endpoints may not be deployed on the lane you are running against. Probe, and degrade
+honestly — a 404 means "this capability is not here", not "there are no assets".
+
+```bash
+curl -sS -o /dev/null -w '%{http_code}\n' "$HELIX_API/api/v1/vault/assets?limit=1"
+```
+
+- `200` → Vault is available; use it.
+- `404`/`501` → unavailable on this lane. Record the probe output in the ledger as the skip
+  reason, drop to the next rung of the source order, and say so in the report.
+- Anything else → a real error. Record the status and the body; do not infer.
+
+Never write "Vault had nothing" when what happened was a 404. Those are different facts and
+only one of them is about the library.
+
+## Endpoints
+
+```
+GET /api/v1/vault/assets                    @Public
+GET /api/v1/vault/assets/:assetId           @Public
+GET /api/v1/vault/assets/:assetId/versions  @Public
+GET /api/v1/vault/assets/:assetId/download  @Public — 302 redirect. THE ONLY download route.
+GET /api/v1/vault/artifacts/*key            @Public — local-disk serve, dev only
+```
+
+## Search parameters
+
+| Param | Values | Notes |
+| --- | --- | --- |
+| `q` | free text ≤200 chars | matched against title, description **and** tags |
+| `kind` | `prop` · `character` · `animation` · `audio` · `texture` · `material` · `environment` · `terrain` · `vfx` · `decal` · `sky` · `gaussian_splat` · `scene` · `interactive_item` · `unreal_package` | repeatable or comma-separated |
+| `subtype` | typed subtype such as `emote` | use `kind=interactive_item&subtype=emote` for executable/ownable emotes |
+| `engine` | `web` · `unreal` | **reach for `engine=web` by default** |
+| `skeleton` | `humanoid` · `quadruped` | meaningful for characters and animations |
+| `origin` | `generated` · `uploaded` | see the audio rung in the skill body |
+| `license` | licence enum | |
+| `source` | publish-source enum | `world_generation` isolates agent-produced assets |
+| `creatorId` | uuid | |
+| `page` / `limit` | limit ≤100, default 20 | |
+
+`kind` is a **builder's** taxonomy — what you can do with the asset — deliberately
+orthogonal to the shopper-facing item kinds (wear / place / hold). An audio loop is neither
+worn nor placed nor held, which is exactly why this axis exists.
+
+An emote spans three layers without collapsing them: its reusable clip is
+`kind=animation`; its validated executable wrapper is `kind=interactive_item,
+subtype=emote`; the player-facing product is a Universal Item of kind `emote`.
+Generic worlds search/install the animation. Global inventory emotes use the
+wrapper and product pipeline rather than manually installing bytes.
+
+## Skeleton gating
+
+`character` and `animation` must declare a standard skeleton to be published: `humanoid`
+(maps onto `helix-humanoid@1`, verified by parsing the GLB's joint names) or `quadruped`
+(`helix-quadruped@1`, one generic rig — dog, horse and big cat all retarget onto it). A rig
+declaring a skeleton it does not conform to is refused publication.
+
+For a world running the `humanoid-character` system, `skeleton=humanoid` is the filter that
+makes a character result actually drivable by the platform's locomotion clips. A character
+that is not on the canonical skeleton renders but does not animate.
+
+`GET /api/v1/vault/skeletons/spec-gaps` returns the standard specs as data — the bone list
+to author against — rather than leaving a refused creator to guess.
+
+## Downloading — the rule, and the reason
+
+```
+GET /api/v1/vault/assets/:assetId/download[?version=N]   → 302 → artifact
+```
+
+Always this route. Never a CDN URL lifted from a search result, even though one is right
+there and would work today. The redirect is where entitlement resolution and paid-asset
+gating land; it is unconditional *now* precisely so no caller has to change later. Code
+that bypasses it works until the day it silently serves a paid asset to someone who has not
+bought it — and the failure lands on the creator, not on the agent that wrote the shortcut.
+
+`/artifacts/*key` is a dev-only local-disk serve, used when storage is not R2. Never build
+a world against it.
+
+## After download — record it
+
+`helix assets install` writes `public/helix.assets.json` with one row per asset
+(`assetId`, `version`, `kind`, `artifactKey`, `integrity`). Whole-file writes only; absence
+means unknown, never empty. Full reasoning in the skill body — it is about payouts, not
+tidiness, and it is the reason the rows do not live in `helix.lock.json`.
+
+For `material` assets, installation defaults to `--material-renditions runtime`: the lean KTX2
+map family only. Choose `source` for editable PNG maps or `all` for both; reinstalling with another
+selection removes the stale opposite family. The selector does not change non-material assets.
+
+If `helix assets install` is not available on this lane, probe it the same way, and record the
+downloads in the same schema by hand — noting in the ledger that the file was hand-written,
+so a reviewer knows which artifact they are trusting.

package/skills/helix-avatar-qa/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: helix-avatar-qa
+description: Publish a HELIX avatar (a whole character Package) that renders with its real textures and deforms cleanly when it walks, in the world and on the Marketplace page, and know exactly what the visual-QA gate measured. Use whenever you publish, republish or version an avatar, when an avatar is "held for visual QA", when visual QA fails an avatar, or when an avatar looks white, grey, glowing, untextured, twisted, "not rigged properly", walks with its arms inside the body, tears open at the side, or has hair standing off as a slab.
+---
+
+# HELIX Avatar QA
+
+**Mandatory before any publish, new version, listing or "done": the `helix-gauntlet` loop** (`read_skill({ name: "helix-gauntlet" })`). The passing visual-QA verdict below is necessary, not sufficient: look at every frame yourself beside the reference images, and get a fresh blind critic's verdict where you can spawn one. Ship only on its PASS.
+
+An avatar is **not visible to anyone but its creator until a visual-QA run of its current Package version passes.**
+Publishing creates it *held* (`publicationDeferred.reason = visual_qa_required`); a passing run releases it to Published.
+There is no admin override for avatars. "Published", "uploaded", "the CLI exited 0" and "the thumbnail looks fine" are
+not evidence that an avatar works: the only evidence is a passing `helix item visual-qa` verdict, recorded by the backend.
+
+## The loop
+
+1. Seal the avatar's Continuum Package Version through the Creator's approved Publications workflow.
+   Add an Item and public offer only when explicitly requested. Expect the avatar to remain held
+   until its current version passes visual QA.
+2. Judge it: `visual_qa_item` (local, `--submit`) or `visual_qa_item_hosted`; follow a hostedRun with
+   `visual_qa_item_status`. Exit 0 = pass, 1 = fail, 2 = harness error (never a pass).
+3. On a fail, read **every** reason and open the contact sheet. Fix the avatar's FILE, publish a new version, re-run.
+   Never re-run hoping for a different answer, and never ask an admin to override — the route refuses it for avatars.
+
+## What the route (avatar@3) measures — all blocking
+
+Stage 1 is the Try Now world walk (the `avatar@2` asserts); stage 2 is the production Marketplace item page's own walk.
+
+| Assert | What fails it | Usual cause, and the fix |
+| --- | --- | --- |
+| `avatar.materials_resolved` | a drawn primitive with no material, a texture bound but never decoded, base-colour textures the GLB declares that never reached the renderer, the model request failing | broken/unsupported KTX2, a material slot dropped by an import step — re-export with valid textures |
+| `avatar.no_emissive_washout` | > 25 % of the surface emitting a flat colour (emissive >= 0.5 with **no emissive map**) | Meshy/AI exports carry `emissiveFactor [1,1,1]` with an emissive map; if the map is lost the body glows white. Remove the emissive factor or keep its map |
+| `avatar.colour_matches_albedo` | the lit render is washed out (much brighter than its own base colour while losing its colour or contrast), black, or flat | the same wash-out, metalness 1 with no metalness map, missing base-colour maps |
+| `avatar.limbs_untwisted` | a limb bone twists about its own axis past 50-55 deg while walking, or a knee bends away from forward | bone roll / rest orientation that disagrees with the HELIX humanoid skeleton — re-rig to the canonical skeleton |
+| `avatar.skin_intact` | skinned triangles collapsing, stretching or tearing at the joints while walking | bad skin weights (vertices bound to the wrong bone), candy-wrapper joints |
+| `avatar.skinned`, `avatar.grounded`, common four | not skinned, sinking/floating, NaN/invisible, untextured placeholder, wrong scale | — |
+
+### Stage 2: the Marketplace walk (new in `avatar@3`)
+
+The item page is where buyers look, and it plays the walk differently from Try Now: the shared walk clip is retargeted
+onto your skeleton, and the arms swing **from the clip's A-pose**, which is about 24 deg more adducted than a bind of 36.
+The gate pauses that real walk at 16 phases and reads the vertices the page draws. Cream Hoodie Anime Girl 1.0.6 passed
+`avatar@2` and was broken there: forearms inside the hoodie, the side torn open as an arm swung back, a strand at the
+waist, the back hair a rigid slab.
+
+| Assert | What fails it | Usual cause, and the fix |
+| --- | --- | --- |
+| `avatar.bind_pose` | an upper arm bound less than 17 deg from straight down (Base Female 36), or another canonical bone far outside its envelope of Base Female's bind direction | Meshy/auto-rig arms bound nearly at the sides (the hoodie: 13-15 deg). **Re-bind the arms near the standard A-pose**: the hoodie rework re-bound them to Base Female's A-pose + 6 deg (oversized sleeves) and walked clean. Rotation-only re-bind of upperarm/lowerarm, baked into POSITION/NORMAL/TANGENT, with IBMs and node rotations rewritten on every LOD |
+| `avatar.preview.arms_clear` | on average over the walk cycle, more than 13 % of the forearm/hand surface lies 3 cm or more inside the torso/hips (good avatars <= 8.5 %, Pastel Cyberpunk with arms bound at 20 deg; 1.0.6: 18 %) | the same low bind; also sleeves weighted to the torso. Fix the bind first |
+| `avatar.preview.surface_closed` | two sides of one surface that touch at rest part by more than 5 cm in the walk (a slit opening: good <= 0.8 cm, 1.0.6: 36 cm) | **Never cut fused sleeve-to-torso (or cuff-to-hip) triangles.** That surface is real cloth and the cut leaves a hole the arm swing opens. Keep the triangles and fix the weights so the cloth follows its own part (re-weight hem and inner-sleeve vertices; no forearm weight on the hem) |
+| `avatar.preview.silhouette` | hair, ears, capes or anything hung from the head or a non-skeleton bone stands more than 35 cm (at 1.70 m) behind or beside the torso's outline (good avatars <= 28 cm: Kemonomimi's flaring hair and cape) | hair chains with a wide cone, a collider that pushes the sheet off the hood. Tighten cones and drop the offending collider. This catches only gross outliers: a slab like 1.0.6's is below it, so **the critic judges that on the side frames** |
+| `avatar.mesh.no_strands` | a thin fragment (over 5 cm long) floating more than 2 cm clear of every other surface | stray generation debris. Delete the loose piece from the mesh before import |
+| `avatar.preview.posture` | neck or torso lean through the walk more than 25 / 15 deg from Base Female's | neck/head bind that differs from canonical, so the head pitches forward or droops with the walk delta. Bind neck and head at the canonical orientation |
+
+Hair rule behind the slab: **hair weights belong on the head and the hair chains only.** Meshy leaves arm and clavicle
+weights in the hair, and a heavy share of the mesh on a few stiff hair joints reads as a rigid sheet. Zero the arm and
+clavicle weights in the hair, spread it over more chains with real cones, and let shoulder strands that are bound to an
+arm stay rigid rather than swinging.
+
+Frames for the critic: `motion.preview.{left,right,back}.{a,b}`, the walk paused with the left (`a`) and right (`b`) arm
+swung furthest back, from the avatar's true left side, true right side and back. The critic is shown each next to the
+height-matched Base body and a clothed control from the same phase and camera, and fails hair, hood, cloth or a strand
+standing stiffly away from the body, a forearm or hand sunk in the torso, hips or a pocket, a hole or see-through gap, and
+a head hanging forward. Stylised proportions, wide skirts, capes and swaying hair are not defects.
+
+**`not measured` is a failure.** If the harness could not read one of these (the preview walk never played, the page did
+not draw the avatar), the run fails with `not measured`, never a quiet pass. Find out why it could not be read (an
+avatar the page will not draw or animate is as much a defect as one that tears) and fix that before re-running. The one exception: `wear.walk.no_holes` / `wear.walk.no_poke_through` on a
+single-surface avatar (no separate outfit to measure) now report `not measured` as a warning, not a pass, and do not
+block: the stage-2 asserts measure tears and buried limbs on the avatar's own surface.
+
+The backend's vision critic also answers `avatar.textures` (lit frames vs the unlit **Reference: unlit base colour**
+frame), `avatar.rig_distortion` (the **stride** frames: the walk paused mid-step, from the side, three-quarter and at the
+legs) and `avatar.preview_walk` (the Marketplace frames above). Every check must pass.
+
+## Reading a result honestly
+
+- The `reference.albedo` frame is a diagnostic render with lighting off. It is supposed to look flat; compare the lit
+  frames against it.
+- A harness error (exit 2) is not a verdict about the avatar. Fix the harness cause (sign-in, Try Now refusal) and
+  re-run; it never counts as a pass and cannot be overridden.
+- A run with `HELIX_VQA_FIXTURE_MODEL` set is a proof harness for the asserts themselves and is always an error.
+- A pass is a floor, not a verdict on quality. Open the `motion.preview.*` frames and look at the side and back views
+  yourself: a hair slab, a pinched sleeve or a stiff cape can sit inside every threshold.
+- Re-judge after every new version: a pass binds to one exact Package version and manifest CID.

package/skills/helix-avatars/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: helix-avatars
+description: Turn any character source — a VRM, a Dreamer/Meshy image-to-3D character, a rigged game model or rip, a CAD robot or scanned kit — into a published HELIX avatar that moves, looks right and passes visual QA on the first publish, including physics bones (helix/dynamics@1) for hair, tails, ears, cloth and soft tissue. Use for any request to make, import, convert, rig, fix, republish or add hair/cloth physics to an avatar or playable character body.
+---
+
+# HELIX Avatars
+
+**Mandatory before any publish, new version, listing or "done": the `helix-gauntlet` loop** (`read_skill({ name: "helix-gauntlet" })`). Bar: the reference sheet or photos of the character; renders: the visual-QA turnaround, walk and Marketplace preview walk; your own look at every frame beside the bar, then a fresh blind critic. Ship only on its PASS.
+
+An avatar is a Character Package, optionally projected as an Item, not a world. You ship one GLB:
+- on the `helix-humanoid@1` skeleton;
+- normally with three LOD scenes;
+- carrying its face and dynamics manifests in scene extras.
+
+It is validated, sealed into a Character Package, visually verified, then offered when requested. The rules are
+in `read_skill({ name: "helix-avatars", reference: "contract" })`. Read that once before step 3. This
+file is the order of work and its gates.
+
+**The default failure** is an avatar that passes every gate and is still broken the moment it moves.
+Cream Hoodie 1.0.0 passed the backend verifier, the engine bind check and visual QA, and at the same
+time:
+- its chest dented with every arm swing;
+- one edge stretched into a 16 cm spike at the hip;
+- a dozen Dreamer drafts around it rendered flat glowing white.
+
+The rest pose hides all of it. So every gate below reads an artifact, and the last ones are your own
+eyes on the avatar walking and running, close up, in the real runtime.
+
+## The workflow
+
+Keep a ledger file. For each step, record the artifact that proves it passed.
+
+1. **Collect the reference.** Use whichever applies:
+   - photographs of the real robot, actor or costume;
+   - the source game's own renders;
+   - the concept art or turnaround.
+
+   Record the real height, and decide what must move: hair, tail, ears, skirt, coat, soft tissue.
+   **Gate:** a reference folder, the height, and a list of the moving parts.
+
+2. **Acquire the source and pick its bridge.**
+
+   | You have | Reference |
+   | --- | --- |
+   | A `.vrm` (VRoid or VRM 0.x/1.0) | `source-vrm`: spring bones and face convert automatically |
+   | Only an image or concept, or a Dreamer/Meshy GLB | `source-generated` |
+   | A rigged game model, rip, mod or downloaded FBX/GLB | `source-model` |
+   | A robot, CAD or URDF, an untextured scan, armour | `source-rigid` |
+
+   Score the candidate sources before committing:
+   - real skinning;
+   - textures;
+   - the right variant;
+   - triangle headroom;
+   - separable hair or cloth if they must move.
+
+   Record what the source lacks, and do not invent it. Prefer a VRM whenever one exists. A VRoid
+   model exported as GLB loses its face and physics.
+   **Gate:** the source is on disk, with an inventory: nodes, skins, joints, materials, triangles,
+   morph names, and what is absent.
+
+3. **Rig onto `helix-humanoid@1`.** Read `rigging`. Choose:
+   - rigid 1:1 binding for mechanical parts;
+   - kept and folded game weights for a clean skinned rig;
+   - repaired weights for auto-rigs.
+
+   Then pose to the canonical A-pose and check the short-body gate.
+   **Gate:** a JSON readback, per LOD after import, of which joint **names** carry weight on each
+   region, and of how far each influencing bone sits from its vertex. A T-pose render is not
+   evidence.
+
+4. **Import, materials and budgets.** Run `import_character` (CLI `helix character import`) with:
+   - `--fit source`;
+   - `--lod-tris` set to use the budget;
+   - `--no-bake` when the source has its own UVs.
+
+   Then check the budget, **counted across every LOD**:
+   - ≤ 60,000 triangles and ≤ 12 draws;
+   - ≤ 10 MiB, ≤ 8 materials, ≤ 2048 px;
+   - each LOD scene with its own skeleton;
+   - no emissive factor without its map.
+
+   **Gate:** the import receipt (`*.avatar-import.json`) plus the structure, budget and motion checks in `qa`.
+
+5. **Dynamics, if anything should move.** Read `dynamics`.
+   - A VRM arrives with chains. Audit its `center` chains, which come in at inertia 0.6.
+   - Anything else needs auxiliary joints and a `helix/dynamics@1` manifest on every LOD scene, added
+     **after** import.
+
+   **Gate:**
+   - the manifest obeys the strict-parse rules;
+   - every chain root exists in every skin;
+   - cost is within caps;
+   - a walk-and-**run** measurement of swing and body gap (`qa` step 3).
+
+6. **Face.** Read `face` and `read_doc({ name: "avatar-face" })`. The face is either:
+   - VRM-automatic;
+   - detected by exact morph names;
+   - mapped with `faceMap`;
+   - or honestly `none`, said in the listing.
+
+   List everything in front of the eyes in `helixAvatar.firstPersonHide`.
+   **Gate:** the importer's `face:` line, and the first-person hide list.
+
+7. **Check before upload.** Run `qa` steps 1–3:
+   - structure;
+   - static renders against the reference;
+   - the offline motion probe against the stock body, on the platform's own clips and the engine's
+     own dynamics solver.
+
+   A throwaway `helix init` + `helix install` world supplies all three. No GPU is needed.
+   **Gate:** a structure report, a contact sheet you have looked at, and limb-rotation, sole and
+   stretch numbers against the control.
+
+8. **Upload and run visual QA.** Read `publish`. Steps 0–3 there:
+   - render a thumbnail. The upload requires one; `item_thumbnail` can re-render or replace it later;
+   - seal the Character Package Version through the Creator's approved Publications workflow;
+   - `visual_qa_item_hosted`, or `visual_qa_item` with `--submit`.
+
+   The avatar stays held, visible only to you, until a run passes. The gate's asserts and fixes are
+   in `read_skill({ name: "helix-avatar-qa" })`. **No admin overrides.** Route `avatar@3` also walks
+   the avatar on the Marketplace item page and judges it from the side and back; a `not measured`
+   assert fails the run.
+   **Gate:** a PASS record, and the contact sheet opened, `motion.preview.*` side and back frames
+   included. A pass is not proof the avatar looks right.
+
+9. **Live close-ups and the critic.** Run `qa` steps 5–6:
+   - Marketplace preview **and** in-world Try Now;
+   - face, hands, feet, and hair or tail at idle, walking and running;
+   - LODs at distance;
+   - then a blind critic against the reference.
+
+   **Gate:** live captures, and a critic ledger that names the exit taken (win or plateau). Anything
+   that fails goes back to the step that owns it, as a new Package Version.
+
+10. **Offer when requested.** Use the Creator's approved Publications workflow to create an optional
+    Item and Marketplace or World offer from the sealed Package Version. Package publication alone
+    creates no Item or creator copy.
+
+    **Gate:** verify the published Package Version and, when an offer was requested, verify the
+    offer and an owner-style claim with a QA account that ends with the avatar worn in a world.
+
+## Hard rules (each prevents a failure that already shipped)
+
+- **Judge it moving, against a control body.** A rest pose hides wrong skin indices and bad weights,
+  and no platform gate checks the weights themselves.
+- **Bind the arms near the canonical A-pose and never cut fused sleeve/torso triangles.** The Marketplace
+  walk adducts the arms ~24°; arms bound under 17° from straight down walk into the body, and a cut
+  sleeve opens as a hole. Fix weights, keep hair weights on the head and hair chains only. See `rigging`
+  and `source-generated`.
+- **Every edit after import is made on every LOD.** That covers joints, weights, manifests and
+  first-person hide. Each LOD scene keeps its own skeleton copy.
+- **Budgets count every LOD.** 60k triangles and 12 draws are totals for the file, not per level.
+- **Strip a generated source's emissive factor together with its map.** Otherwise the avatar glows
+  flat white.
+- **Count arm<->leg triangles on a generated character before you trust it.** A hand fused to the
+  thigh tears into a sheet in the walk. The importer cuts it (`--limb-bridges repair`, the default),
+  but a draft built before that step needs a re-import. See `source-generated`.
+- **Never let the importer rebake a source that has its own good UVs.** Pass `--no-bake`. The rebake
+  smeared a mouth into a chin.
+- **A malformed dynamics manifest silently kills all physics.** The only signal is one console line,
+  and nothing validates the manifest offline.
+- **Tune dynamics for the run, not the idle.** Every smear into a hood or collar appeared at a run.
+- **Under 1.35 m, check (pelvis − foot) / 0.877 < 0.65,** or the feet sink.
+- **Set the dynamics values before the first publish.** After it, changing inertia or limits needs a
+  new Package Version.
+- **Write endpoints and collider offsets in the bone's own axes.** On `helix-humanoid@1`, a spine or
+  head bone's local +X points up, so "straight down" is `[-L, 0, 0]`, not `[0, -L, 0]`. The parser
+  accepts the wrong axis silently. See `dynamics`.
+
+## Tools you will use
+
+| Purpose | Tools |
+| --- | --- |
+| Discovery | `search_items({ kind: "avatar" })` for published avatars and their thumbnails. `search_items({ hostKind: "character" })` for character add-ons. |
+| Import | `bridge_import`, for VRM. `import_character`, for everything else. |
+| Generation | `generate_asset({ kind: "character", referenceSheetPath })` |
+| Validation | Structure, budget and motion checks in `qa`; the Creator publication workflow validates the Package Version |
+| Publishing | `publish_continuum_package`, `publish_owned_item`, `visual_qa_item`, `visual_qa_item_hosted`, `visual_qa_item_status`, `item_thumbnail`, `disable_item_distribution`, `delist_item` |
+
+Some steps are CLI-only:
+- `helix continuum publish-package --stage`;
+- `helix item set-version`;
+- `helix character repair-lod-skeletons`.
+
+Mesh, pose and weight work happens in headless Blender and `@gltf-transform/core`. If either is
+missing, install it. Dynamics authoring has no CLI step yet (`helix-creator-cli` #295), so script it
+against the contract. Validate it with the engine's own parser, and measure it with the probe in
+`qa`. Both run from a throwaway world that `helix init --kind character` and `helix install` create. Everything the platform executes is a `helix …` command. Run it; never re-implement it.
+
+## References
+
+`read_skill({ name: "helix-avatars", reference: "<name>" })`:
+
+| Reference | Covers |
+| --- | --- |
+| `contract` | Skeleton, frame, A-pose, LOD scenes with their own skeletons, budgets over all LODs, the preflight, short-body gate, feet, first-person hide, the import receipt. |
+| `rigging` | Bone maps, the canonical rest, rigid vs skinned binding, helper folding, weight sanity, why a T-pose hides skin-index bugs. |
+| `dynamics` | The `helix/dynamics@1` schema and strict parse, authoring chains on non-VRM sources, parameters that shipped, failure modes (smearing, clipping, LOD drift). |
+| `face` | What each source gets, the capability ladder, adding a jaw, first-person. |
+| `source-vrm` | The bridge route, what converts, auditing `center` chains and damping. |
+| `source-generated` | Dreamer and Meshy: sheet layout, visibility, emissive, `--no-bake`, auto-rig weight repair, hands fused to thighs, fused-shell hair, pale/glossy outfits. |
+| `source-model` | Game rips and downloads: acquisition, posing, material conversion, UASTC normals, hard-surface LODs. |
+| `source-rigid` | Robots, CAD and scans: 1:1 binding, pistons, segmentation, palette atlas, the short-body gate. |
+| `publish` | Thumbnail, preflight, upload, visual QA, seal and pin, distribute, new versions, pausing. |
+| `qa` | Structure checks, motion against a control body, live close-ups in both surfaces, the blind critic, and what eyes caught. |