@hypersoniclabs/helix-mcp 0.2.4 → 0.2.12

package/skills/README.md

@@ -0,0 +1,91 @@
+# HELIX Agent Skills
+
+Nine first-party skills for agents building HELIX Instant worlds, vehicles and avatars. They ship inside
+`@hypersoniclabs/helix-mcp` and are served to MCP-only agents by `read_skill` (SKILL.md and
+`references/*.md`); executable behavior ships separately in the creator CLI.
+
+## The doctrine
+
+**Tools own capability. Docs own the contract. Skills own judgment. Every gate reads an
+artifact.**
+
+The MCP server teaches and routes; the creator CLI does things — scaffold, install, validate, inspect, measure,
+capture, publish — and already *states* things, in 26 docs served by `read_doc` and
+`read_template`. These skills duplicate neither. They carry the part that is neither a
+capability nor a contract: what to do first, what "good" means, what blocks shipping, and
+how you prove it.
+
+The gate rule is the whole design. A gate in these skills never asks the agent to certify
+its own diligence. It names a thing that exists outside the agent's output — a validator
+result, a JSON snapshot, a pixel count, a file on disk, an HTTP response, a process exit
+code — and passes or fails on that. Where a rule could only be satisfied by the agent
+asserting it did the work, we either turned it into a CLI command that exits non-zero on
+failure or cut it. Checklists survive as prompts for what to look at; none of them unlocks
+"done".
+
+**The gate rule has a second half, learned by dogfooding these skills on two real worlds:
+a gate must measure the OUTCOME, not a proxy for it.** Every defect those two builds found in
+this skill set was the same shape — a check that read something correlated with the thing it
+claimed to verify, and passed when it had measured nothing at all. `prove-live` looked for a
+build number at three paths the API does not have, found none, warned, and exited 0. The
+genre-gate check grepped the source for `allowModeToggle` and confirmed the *string* was
+present, on a world where the runtime was ignoring the whole config block. The fallback check
+counted honest-fallback log *sites*, so writing the fallback correctly earned a permanent
+warning on a world where none ever fired.
+
+So the question to ask of any check here is: **what would I have to observe to know this is
+true, and am I observing that or something that correlates with it?** Where the honest answer
+is "a proxy", the check either moves to where the outcome is observable — the runtime — or
+says so about itself in the output. A gate that cannot prove its claim now exits non-zero; a
+gate that measured nothing says `measured NOTHING` rather than staying silent.
+
+**The third lesson, and the expensive one: a labelled proxy is still wrong, and the outcome you
+refuse to gate on is the one that ships broken.** Both dogfooded worlds went live running
+badly — Night Market at 25.5 ms p50 / 92.7 ms p95, 26% of frames over 33 ms — with every gate
+green. QA measured triangles, bundle size and draw calls, printed frame rate as an
+*informational line*, and never failed on it, so a world could run at 10 fps and pass. Worse,
+the one metric that would have caught the cause was a regex: `lighting.census` counted
+`new THREE.PointLight(` call sites and reported `PointLight×4` for a scene holding 18 point
+lights and 4 spot lights — four sites inside loops, off by 4.5× in the direction that passes.
+It was classified as an acceptable "labelled proxy". It was not. Frame time is now a blocking
+gate (`helix world perf-gate`), the census walks the live scene, and the lighting rules that push toward
+more lights are paired with a measured ceiling that pushes back.
+
+This is a deliberate departure from the reference skill sets we studied. Theirs gate on
+self-report — an auditor that greps the agent's own prose for the phrase "art direction",
+a credential probe whose script cannot emit the string its checker looks for, a
+"report new failures separately from baseline" rule repeated in four skills with no
+baseline file anywhere. Each of those looks like rigor and enforces nothing. Where we kept
+an idea from them, we kept the mechanism and threw away the ceremony.
+
+## The nine
+
+| Skill | Owns | Triggers on |
+| --- | --- | --- |
+| `helix-world-director` | The world end to end: phase ledger, ordering, what blocks what, when to stop. The only skill that decides a world is finished. | "build me a world", "make a HELIX game", any multi-phase world request, or resuming an unfinished world |
+| `helix-world-build` | Discovery-first authoring. Catalog before code, config before API, manifest schema-valid, layout measured not eyeballed. | scaffolding, scene authoring, character configuration, placement, HUD, input, gestures |
+| `helix-multiplayer` | The declarative DSL's real boundary — what `when`/`if`/`then` can express, what it provably cannot, and which escape hatch each gap takes. | multiplayer, co-op, PvP, shared state, rooms, entities, zones, teams, voice, single-player→multiplayer conversion |
+| `helix-assets` | Reuse before generate. Vault search, provenance, budgets, loader allowlist, LIX cost, and the audio source chain. | sourcing models/textures/audio, "find an asset", generating assets, bundle-size problems, load failures |
+| `helix-avatar-qa` | Publishing an avatar that renders with its textures and walks without twisting or tearing (in the world and on the Marketplace page): the hold-until-pass rule, what each visual-QA assert measures, and how to fix what it fails. | publishing or versioning an avatar, "held for visual QA", an avatar that looks white/grey/glowing/untextured/twisted |
+| `helix-world-qa` | Proving the world plays — and that it plays at 60 fps. Mobile-first, artifact-gated, with the blocking metrics (including frame time) computed by script. | "is it ready", QA, playtest, pre-publish review, "why does it look flat", "why does it run badly" |
+| `helix-vehicles` | A drivable vehicle item and its add-ons from any source — real car by name, BeamNG mod, downloaded model, concept image, from scratch — to a published, visually verified listing. The rules live in `read_doc({name:"vehicles"})`; the skill is the order of work and its gates. | "make me a <car>", convert/import a vehicle or mod, vehicle add-ons (wheels, kits, performance parts), republish or fix a car; routed by `get_started({kind:"vehicle"})` |
+| `helix-avatars` | A published avatar from any source — VRM, Dreamer/Meshy image-to-3D, rigged game model or rip, robot/CAD/scan — rigged onto `helix-humanoid@1`, inside the all-LOD budgets, with `helix/dynamics@1` physics bones for hair, tails, ears and cloth, and verified moving against a control body. The face contract stays in `read_doc({name:"avatar-face"})`. | "make me an avatar of <character>", import/convert a VRM, game model or generated character, hair or cloth physics, fix or republish an avatar; routed by `get_started({kind:"avatar"})` |
+| `helix-gauntlet` | **Mandatory** acceptance before any publish, new version, listing or "done", for every kind: an external bar (photos and specs of the real thing), the fixed inspection set rendered in the real runtime (for a car: every seat occupied, the driver steering, still hands), the agent's own look at every sheet, a fresh blind critic, two rounds per approach then diagnose, ship only on a pass; and re-checking listed items against today's gates. | before `publish_*`, `create_item_distribution`, a new version, "is it done"; updating a listed car; loaded by every publishing skill |
+
+## Reading order for a fresh agent
+
+`helix-world-director` first — it loads the others at phase entry and owns the ledger.
+Everything else is loaded by the phase that needs it. A narrow request ("fix the lighting")
+can load `helix-world-build` + `helix-world-qa` directly without the director.
+
+## Retention rule
+
+A skill survives only when it changes orchestration or judgment, or requires artifact-gated
+behavior that the docs alone do not provide. Repeated command references and product contract
+text belong in `read_doc`; executable checks belong in the CLI. Skills never package scripts.
+
+## What these skills never do
+
+Name a generation vendor, call a provider API, ask for an API key, or reason about
+moderation. Asset generation, provider selection, moderation, LIX metering and publishing
+are backend-owned. A skill that reaches around the platform for those is a bug.

package/skills/helix-assets/SKILL.md

@@ -0,0 +1,491 @@
+---
+name: helix-assets
+description: Source assets for a HELIX world in the right order — platform packages, platform materials, Vault reuse, generation, then vetted CC0 — recording provenance that a script can verify and keeping the bundle inside platform budgets. Use whenever a world needs models, images, materials, environments or audio, when asking where to get an asset or which library is safe to take it from, when deciding whether to generate or reuse, when a model fails to load, or when the bundle is over budget.
+---
+
+# HELIX Assets
+
+**Mandatory before any publish, new version, listing or "done": the `helix-gauntlet` loop** (`read_skill({ name: "helix-gauntlet" })`). For an item you publish (a wearable, prop or add-on): bar = product photos at matched angles; renders = its visual-QA frames fitted or placed in the runtime; your own look at each, then a fresh blind critic. Ship only on its PASS.
+
+The default failure here is building a world out of grey boxes because sourcing felt like a
+detour. It is not a detour. **Sourcing happens before authoring**, because a scene authored
+around primitives does not get retrofitted with real assets — it gets rebuilt.
+
+## Existing external content uses Bridge
+
+When the human supplies an existing model, character, animation, scene, mod export, or engine
+project—or asks to bring one into HELIX—use the Bridge tools before writing a converter:
+
+1. `bridge_detect`
+2. `bridge_inspect`
+3. `bridge_plan` with every auxiliary input that the import will use
+4. `bridge_import` with the reviewed `deterministicKey` as `expectedPlanKey` and every reported permission whenever a command-backed capability will run, including a packaged official adapter
+5. `bridge_validate`
+
+Read `read_doc({ name: "bridge" })` for plugin permissions, capability replacement, provenance,
+and the MetaHuman eye-material path. Bridge is CLI-owned; do not recreate its conversion logic
+inside a world or the MCP package. A command-backed adapter's
+`unrestricted-host-execution` request means exactly that: only pass it when the human's task
+authorizes running the reviewed adapter, even when it is packaged and HELIX Verified.
+
+## Order of resort
+
+1. **Platform packages** — `list_systems`, `list_abilities`. A behavior that exists as a
+   published ability is never re-implemented.
+2. **Platform material pack** — `helix assets materials`, then `helix assets material <id>`. These are versioned,
+   validated surface definitions with stable map URLs. Search here before downloading or
+   generating any surface look. Keep the working palette bounded (the tool defaults to 12);
+   that is a per-world/runtime budget, never a cap on the global catalog or Vault.
+   A material may ship several texture resolutions — **you choose which one you get**, see
+   **Picking a material's texture resolution** below.
+3. **Vault** — the shared asset library. Run `helix assets search --engine web` before you generate
+   anything. See `references/vault-api.md`.
+4. **Generate** — backend-owned and LIX-metered. `helix assets generate` makes a prop or
+   character. When approved four-view character art already exists, use
+   `helix assets generate-reference <sheet> <prompt>` (or `generate_asset` with
+   `referenceSheetPath`) so the backend reuses the checksum-bound sheet and does not invoke
+   image generation. If transport fails after a paid job starts, resume that exact job with
+   `helix assets resume <job-id>`; it is idempotent and must never be replaced by a second
+   generation request. `helix assets generate-image` makes a standalone image;
+   `helix assets generate-audio` makes a sound effect, music track, or spoken line; and
+   `helix assets generate-material` makes a validated portable PBR bundle;
+   `helix assets generate-environment` makes an experimental SPZ environment for a
+   compatible renderer. Animation generation is an explicit unavailable boundary. There is
+   no animation generation fallback: reuse a skeleton-gated Vault clip or import one.
+5. **A curated CC0 source** — a named author or team publishing their own work. Five of them,
+   with query recipes, in **Where CC0 assets actually come from** below.
+6. **Procedural / primitive** — collision proxies, invisible volumes, blockout. Not a look.
+
+Descending this list is normal. **Skipping a rung is the defect.** Apply the order separately
+to every identity-bearing asset family: players and avatars, creatures, vehicles, weapons,
+signature props, hero environment kits, and signature audio cue sets. A search or generation
+receipt for one family says nothing about another family.
+
+Before authoring one of those families, add one row to the world's asset plan with: family name,
+typed Vault query and result, installed asset id or HELIX generation job receipt, and final
+representation. “We loaded another model” and a passing world-wide loaded-mesh percentage are
+not substitutes for that row. A mesh assembled from Three.js primitives is procedural geometry,
+not a custom model.
+
+## Never, in any skill or any world
+
+Name a generation vendor. Call a provider API. Ask for or read an API key. Reason about
+moderation policy. Asset generation, provider selection, moderation and LIX metering are
+backend-owned; the platform surface is the whole surface. A world that reaches around it is
+a bug, not a shortcut. **A missing vendor key is never evidence that HELIX generation is
+unavailable.** Only the HELIX tool's own failure or capability-unavailable receipt can establish
+that, because any provider credentials HELIX needs belong on the backend.
+
+## Vault — search it first
+
+Full endpoint contract, query parameters and the capability probe:
+`references/vault-api.md`. The three things that matter most:
+
+- **`engine=web` is the default filter.** It directly answers "give me something usable in
+  a web world" and stops you downloading Unreal packages the runtime cannot load.
+- **`kind=audio` exists** — but audio has its own source chain below, which is *not* simply
+  "search Vault". Read it.
+- **Install with `helix assets install`.** It downloads through
+  `GET /api/v1/vault/assets/:assetId/download`, writes the immutable asset id into the
+  world path, and records the receipt. Never grab a raw CDN
+  URL, even when the search response hands you one. The 302 is deliberate indirection: it is
+  where entitlement and paid-asset gating land. Code that grabs the CDN URL directly breaks
+  silently the day paid assets ship, and it breaks for the *creator*, not for you.
+- **Material installs are lean by default.** `install_asset` / `helix assets install` selects the
+  runtime KTX2 family. Use `materialRenditions: "source"` / `--material-renditions source` only
+  when you need editable PNG maps, or `all` only when the project truly needs both. Selection stays
+  in the CLI so checksums, sizes, receipts, and stale-family cleanup remain one authoritative path.
+
+The Vault endpoints may not exist on the lane you are running against. **Probe before you
+rely on them** and fall back honestly — never fail the phase because a capability is not
+deployed yet, and never claim you searched a library that returned 404.
+
+## Where CC0 assets actually come from
+
+Vault is the first reuse path, not the only one, and when that probe returns 404 it is not a
+path at all — so "reuse before you generate" has to mean something else, and it means these.
+All five were exercised end-to-end by two worlds; the counts are live, read from the
+endpoints below, not estimates.
+
+| Source | Endpoint | Key | Holds | Licence |
+| --- | --- | --- | --- | --- |
+| **Poly Haven** | `https://api.polyhaven.com` | none | 980 HDRIs · 786 textures · 521 models | CC0 |
+| **ambientCG** | `https://ambientcg.com/api/v2/full_json` | none | 2,004 PBR materials | CC0 |
+| **Kenney** | `kenney.nl` — no API, per-pack ZIP | none | low-poly kits, UI, and the SFX packs the audio chain's rung 2 depends on | CC0 |
+| **Quaternius** | `quaternius.com` — no API, per-pack ZIP | none | stylized low-poly kits, atlas-textured — cheapest against the texture budget | CC0 |
+| **Poly Pizza** | `https://api.poly.pizza/v1` | **free key required** | 10,600+ low-poly models incl. the rescued Google Poly archive | **mixed** CC-BY 3.0 / CC0, per asset |
+
+Query recipes, response shapes and the per-source traps: `references/asset-sources.md`. Three
+things worth knowing before you open it:
+
+- **Poly Haven is the only source you can budget against before downloading.** All 521 model
+  records carry `polycount` and `max_resolution` (`ArmChair_01` is 5,626 tris against an 8k
+  character budget) — filter the list response, then fetch. Everywhere else you download first
+  and find out second. No free-text search: filter `categories=` and match `tags`. Models come
+  as `.gltf` + `.bin` + `textures/`, so fetch the whole `include` map from `/files`, not just
+  the `.gltf`; one provenance row on the directory covers the set.
+- **ambientCG ships one material at up to 431 MB.** Its `downloads[]` entries carry `size` in
+  bytes — `1K-JPG` is 8.7 MB, `4K-JPG` is 111 MB, against a **50 MB whole-bundle cap**. Take
+  1K unless the surface is a hero, and take `_NormalGL`, not `_NormalDX`.
+- **Poly Pizza 401s without a key** — literally `{"error":"You need an API key to do that
+  dingus"}`. That is a missing `x-auth-token`, not a dead source; one build read it as
+  unavailable and skipped 10,600 models. Its per-asset `licence` is CC-BY 3.0 **or** CC0, so
+  read it per asset. CC-BY obliges attribution the *player* can see, and **3.0 has no cure
+  period** — where 4.0 reinstates after a fix, a rendering bug that drops the credits panel
+  terminates 3.0. No credits surface yet ⇒ take only the CC0 rows.
+
+**Not these:** **Sketchfab** — mixed licence with NonCommercial and NoDerivs in it.
+**Objaverse-XL** — largely GitHub scrapes, no licence filtering. **Freesound**,
+**OpenGameArt** — user-upload, so "CC0" is an unverified assertion by an anonymous uploader,
+the same distinction the audio chain draws at rung 2. The line is not free-versus-paid; it is
+**whether the licensor is demonstrably the author**.
+
+**Three licence questions, and agents reliably ask only the first:**
+
+1. **Commercial use?** — kills NonCommercial.
+2. **Modification?** — kills NoDerivs, and this is the one that gets missed. We decimate,
+   generate LOD chains and atlas textures; each is plausibly a derivative. **CC-BY-ND permits
+   commercial use and still bars us**, so "it's fine, it's commercial-OK" is not an answer.
+3. **Can the world shipping it stay proprietary?** — kills ShareAlike and GPL.
+
+CC0 clears all three. Everything else gets checked against all three, per asset.
+
+## Provenance — recorded, and verified by a script
+
+Every asset in the world carries one of these values. This vocabulary exists so an agent
+cannot describe a file it never shipped:
+
+| Value | Means |
+| --- | --- |
+| `vault` | downloaded from Vault through the `/download` endpoint |
+| `generated` | produced this session by the platform's generation path |
+| `curated` | from a named allowlist source; the licensor is the author |
+| `procedural` | authored by code or algorithm — no third-party source to attribute. Either built at runtime (no file ships) or baked to a file offline |
+| `declared, not shipped` | **source references a path that is not in the bundle** |
+
+`declared, not shipped` is the whole point of the enum. It names the exact failure where a
+world's code points at `assets/hero.glb`, the report says the hero was sourced, and the file
+does not exist.
+
+**The axis this vocabulary splits on is *what authored the asset*, not *whether a file
+ships*.** That is why `procedural` covers both a noise bed synthesised at runtime and the same
+bed baked to a `.wav` at build time: the question provenance answers is "whose work is this,
+and under what licence" — and for both of those the answer is "ours, none needed". Splitting
+them into two values would divide the set along an axis nobody consuming provenance cares
+about, while leaving the licence question exactly where it was. Ship-or-not is already
+recorded, precisely, by whether the row's `path` resolves in `dist/`.
+
+**Where it is recorded:** `public/helix.assets.json`, in **two arrays that answer different
+questions**.
+
+```json
+{ "version": 1,
+  "vaultAssets": [
+    { "assetId": "…", "version": 3, "kind": "prop",
+      "artifactKey": "vault-assets/…/v3/model.glb", "integrity": "sha256-…" }
+  ],
+  "assets": [
+    { "path": "assets/models/relic/relic.glb", "provenance": "generated",
+      "source": "generation job <id>", "licence": "platform-generated",
+      "notes": "6,037 tris · 4 textures" },
+    { "path": "assets/models/moon_rock_02", "provenance": "curated",
+      "source": "<named CC0 pack / author page>", "licence": "CC0",
+      "attribution": "<author names>" },
+    { "path": "assets/audio/wind.wav", "provenance": "procedural",
+      "source": "synthesised in-session — pink noise, filtered, loop-faded" },
+    { "assetId": "…", "path": "assets/props/lamp.glb", "provenance": "vault",
+      "source": "Vault", "licence": "<as returned by Vault>" }
+  ] }
+```
+
+- **`vaultAssets[]` is a locked machine contract** — `helix assets install` writes it and the Vault
+  session consumes it at publish to attribute usage. Its shape does not change. Never add
+  fields to it.
+- **`assets[]` is the provenance table**, one row per asset, and it is the only place four of
+  the five provenance values can be recorded at all. `path` is bundle-relative and may name a
+  **directory** to cover everything under it (a Poly Haven model is a `.gltf` + a `.bin` + a
+  textures folder; one row) or contain a **`*`** to cover a set from one source
+  (`assets/materials/asphalt_*.jpg` — one licence, three maps). `procedural` rows omit `path`
+  when nothing ships.
+
+`helix world audit --assets` verifies the **whole table, in both directions**: every declared
+row must resolve to something in `dist/`, and every media file in `dist/` must be covered by
+a row. It fails on an unknown provenance value, on a `curated` row with no source or licence,
+on an explicit `declared, not shipped`, and on an absent table when the bundle ships media.
+An asset nobody wrote down is exactly as much of a gap as a row that points at nothing.
+
+**Credits are generated, never hand-written:**
+
+```bash
+helix assets credits --out ASSET-CREDITS.md
+```
+
+Writing a credits file by hand and recording provenance in a schema is the same work done
+twice, and the hand-written copy is the one that goes stale. The JSON is the source of truth;
+the markdown is a render of it.
+
+**Not in `helix.lock.json`, and this is load-bearing.** `install_world_packages` wipes and
+rebuilds its own outputs deterministically, so a Vault section inside the lockfile would be
+erased by a routine `--update`. At publish time that erasure is indistinguishable from the
+creator having deleted every asset — which would zero their usage counts and later their
+payouts. A sibling file we own cannot be wiped by a tool that does not know it exists.
+
+`public/` is copied verbatim into `dist/` and `json` is in the manifest extension allowlist,
+so the file reaches the bundle by the same route `public/helix.json` already takes.
+
+**Two invariants, rules not suggestions:**
+
+- **Written whole or not at all.** On any mid-install failure, leave the previous file
+  untouched rather than writing a partial one. A present, valid, empty array must genuinely
+  mean "this world uses no Vault assets".
+- **Absence is never destructive.** A missing or unparseable file means *unknown*, never
+  *empty*. Anything consuming it treats absence as "change nothing".
+
+**Where Vault is deployed, generated assets auto-publish to it by default**
+(`vaultAutoPublishGeneratedAssets`, database default true); only an explicit false turns it off at
+`/account#vault-auto-publish` under "Vault". This is shipped behaviour, not
+forthcoming — but it is gated by the **same capability probe** as the rest of Vault
+(`references/vault-api.md`), and on a lane where that probe 404s the generation job parks at
+`preview_ready` with `publish` still queued and `publishedItemId` null.
+
+So: **read `vaultAssetId` before you say an asset is in the library.** `publishedItemId`
+identifies the storefront/product row and is not the reusable Vault handle. A default-on
+registration failure is a failed operation, not a green generation with a warning; an
+explicit opt-out is reported as `vaultAutoPublish: "disabled"`.
+
+## Audio — an ordered chain, and a hard safety rail
+
+Jack's rule stands: every player action, pickup, hit, UI press, state change and ambience
+has a sound. A silent world is a defect. But *where* the sound comes from is gated.
+
+**The reason, so you can handle a case this list does not cover:** audio is currently
+unmoderated on the platform, on the assumption that it was moderated upstream by the
+generation provider. That assumption holds only for audio we can confirm was generated.
+
+Take the first rung that works:
+
+1. **Generated in-session with `helix assets generate-audio`.** Provenance known by construction.
+   Preferred. Choose `--mode sound_effect` for one-shots/loops, `--mode music` for a track, or
+   `--mode text_to_speech --text ... --voice-id ...` for spoken audio. The CLI owns the
+   long-running job and default-on Vault publication; the MCP tool invokes that same packaged
+   command rather than carrying a second provider client. Before text-to-speech, call
+   `list_voices`, select a returned id, and use one of that voice's supported language codes.
+   Follow the opaque next-page token when needed; never invent an id or attempt cloning. TTS
+   language codes are lowercase two-letter codes, output is one of the portable MP3 formats, and
+   pronunciation dictionary ids must be unique (maximum three). If the backend reports that audio
+   generation is not configured, continue down this chain; never call a provider directly.
+2. **A curated allowlist pack** — a single named author publishing hand-authored packs
+   (Kenney's SFX packs; see the source table above). The licensor is demonstrably the
+   author. Categorically different from a
+   user-upload site where the licence is an unverified assertion by an anonymous uploader;
+   apply that distinction, do not pattern-match on the string "CC0".
+3. **Synthesised Web Audio.** A short procedural blip from an `OscillatorGain` envelope.
+   Always available, always safe, and it fully satisfies "every interaction has a sound".
+   This is a correct answer, not a placeholder.
+4. **Vault `kind=audio`** — **only when the asset's origin is verifiably `generated`.**
+   Direct byte-first Vault uploads are retired. Generated assets are the supported route here;
+   Vault audio is trusted only when the server confirms its generated origin. Use
+   `GET /api/v1/vault/assets?kind=audio&engine=web&origin=generated` — filter server-side,
+   never fetch broadly and filter in the client. **A missing or unknown `origin` reads as
+   `uploaded`, not `generated`**: backfilled rows whose origin cannot be determined are
+   deliberately assigned the less-trusted value, and a safety field that guesses in the
+   trusting direction is decorative. If the response carries no `origin` field at all, this
+   rung is unavailable on this lane — drop to rung 3.
+
+**Never:** arbitrary internet audio, arbitrary user-uploaded audio, a general-purpose upload
+platform. If you find yourself weighing whether a source is probably fine, it is rung 3.
+
+## Picking a material's texture resolution
+
+A platform material can carry more than one texture resolution. Pass `resolution` to
+`list_materials` / `use_material` (or `--resolution` to `helix assets materials` / `helix assets
+material <id>`) to choose. Omit it and you get the pack's declared default.
+
+```bash
+helix assets material brick-block                    # the pack's default
+helix assets material brick-block --resolution 2k    # the 2K variant's map URLs
+helix assets material brick-block --resolution 2048  # same — numeric spelling
+helix assets materials --resolution 2k --limit 12    # only materials carrying 2K
+```
+
+Valid values are the keys the catalog declares (`1k`, `2k`, …), case-insensitively, plus `1024`
+and `2048` as aliases. Every material in the output carries a `resolution` block naming what was
+resolved and what else exists, so **read it instead of assuming**:
+
+```jsonc
+"resolution": {
+  "requested": "2k", "resolved": "2k", "pixels": 2048, "default": "1k",
+  "available": [{ "key": "1k", "pixels": 1024 }, { "key": "2k", "pixels": 2048 }],
+  "applicable": true
+}
+```
+
+Three behaviors you can rely on, and must not work around:
+
+- **A resolution the material does not carry is an error** that lists the ones it does. You will
+  never be handed a different resolution than the one you asked for. If you get that error, pick
+  from the listed values — do not retry blindly and do not assume the pack is broken.
+- **A pack with a single resolution reports it as `default`**, not `1k`. Older packs
+  (`schemaVersion: 1`) do not state their texture size, so neither does the tooling. `--resolution
+  1k` against such a pack fails on purpose rather than guessing.
+- **Procedural materials (`kind: glass`, `procedural_water`) are not offered.** The listing names
+  them under `unlisted`, and resolving one by id is an error saying why. Pick a photographed or
+  scanned material instead; `--include-unlisted` exists for maintainers, not for world building.
+
+Bigger is not better: texture memory is a published budget (see the device-profile table below).
+Reach for 2K on hero surfaces the camera gets close to, and leave background surfaces at the
+default.
+
+## Choosing a representation
+
+| Need | Representation |
+| --- | --- |
+| Hero character, player, named NPC | sourced or generated rigged mesh; verify skeleton and scale |
+| Environment kit, architecture, terrain dressing | sourced environment/prop set; instance repeats |
+| Non-identity support prop whose sockets, collision or code-driven variants matter | procedural three.js geometry, deliberately |
+| Repeated background filler | one sourced mesh, instanced — not twelve near-duplicates |
+| Surface look | a real PBR material: `map` + `roughness` + `metalness`, or a sourced material |
+| Collision proxy, trigger volume, blockout | primitive — invisible or temporary |
+
+## The honest fallback
+
+For an identity-bearing family, “unavailable” means that family's typed Vault search found no
+suitable result **and** that family's HELIX generation call returned a real failure or
+capability-unavailable result. Record both receipts. A missing external-provider key, another
+family's receipt, or a favorable whole-world primitive ratio proves nothing.
+
+Only then may a placeholder preserve **footprint, height, pivot, collider, sockets, facing,
+motion timing and state readability**. It must be visually unmistakable and log itself exactly
+once:
+
+```ts
+console.warn('[helix-assets] fallback: hero — Vault returned no engine=web character; using blockout capsule');
+```
+
+The log line is the artifact — and it is checked **at runtime, not in your source**. Writing
+the fallback exactly as prescribed creates a log *site*; only a site that *fired* means a
+placeholder actually stood in. `helix world source-audit --console qa/playtest/console.txt` reads the
+console output your playtest captured and fails when a fallback fired there. (An earlier
+version counted log sites in source, so following this section earned a permanent warning
+claiming placeholders were standing in on a world where none ever ran. A gate that fires on
+correct code teaches agents to stop writing correct code.) **Never silently substitute a
+mismatched asset, and never call placeholder visuals production-ready.**
+
+## Loader allowlist — GLTFLoader + KTX2Loader, and nothing else
+
+A Draco- or meshopt-compressed model **fails to load at runtime**. Treat it as a blocking
+error the moment you obtain the file, never as a warning to revisit:
+
+```bash
+helix assets check-loaders public/assets    # exits non-zero on the first blocker
+```
+
+It reads **both** container forms, which is the point: `.glb` is a binary wrapper whose JSON
+chunk length sits at byte 12, and `.gltf` is plain JSON beside a `.bin`. Poly Haven — the
+most obvious CC0 model source there is — ships the second form, and a `readUInt32LE(12)`
+one-liner throws on it rather than reporting anything.
+
+Signatures: `KHR_draco_mesh_compression` or `EXT_meshopt_compression` in
+`extensionsRequired`; at runtime, `THREE.GLTFLoader: No DRACOLoader instance provided`.
+Textures ship as KTX2 or as png/jpg/webp — nothing else transcodes.
+
+**`gltf-transform optimize` compresses with meshopt by default** — the exact compression this
+runtime cannot decode. It is the tool you will reach for the moment you need to hit a poly or
+texture budget, and it silently produces a model that does not load:
+
+```bash
+gltf-transform optimize in.glb out.glb --compress false --instance false
+```
+
+Both flags are mandatory here. Run `helix assets check-loaders` after any pipeline step that rewrites
+a model, not just after downloading one.
+
+## Portable environment formats
+
+**`.hdr` and `.exr` are first-class bundle formats.** Use `.hdr` when RGBE radiance is
+enough and `.exr` when the source needs half/float precision or additional channels.
+Keep the native radiance file for lighting and add a small tone-mapped JPEG/PNG only when
+the UI needs a quick thumbnail:
+
+```bash
+# Lighting artifact: load with RGBELoader/EXRLoader + PMREM
+# Thumbnail: deliberately tone-map a separate preview
+ffmpeg -i sky.hdr -vf "tonemap=hable,scale=2048:1024" -q:v 3 public/assets/env/sky.jpg
+```
+
+Do not disguise HDR bytes as `.bin`: the extension is now allowlisted and native MIME
+metadata is part of the portable contract. Record any tone-map transform in the preview
+provenance row.
+
+**Probe your encoders before choosing an audio format.** `.ogg` is in the allowlist, but a
+given ffmpeg build may have no Vorbis encoder — `libvorbis` is a build-time option, and its
+absence surfaces as a bare "Unknown encoder" mid-pipeline:
+
+```bash
+ffmpeg -hide_banner -encoders | grep -E 'libvorbis|libmp3lame|vorbis'
+```
+
+Without it: **`.wav` for anything that loops** (an ambient bed, an engine hum) because it is
+uncompressed and therefore gapless, and **`.mp3` for one-shots** where its encoder-delay
+padding is inaudible. Never use `.mp3` for a gapless loop — the padding is the click you will
+then spend an hour chasing. Budget for the size: a 10 s stereo `.wav` bed is ~1.7 MB against
+a 50 MB bundle cap.
+
+## Budgets
+
+**Bundle** (enforced by `validate_world` at validate *and* publish): ≤200 files, ≤25 MB per
+file, ≤50 MB total, no empty files, extension allowlist only.
+
+**Scene-local resources** (enforced for `.helix-scene.json` publishes). Every reference is
+an immutable `{assetId, version, checksumSha256}` pin. The backend downloads and hashes that
+exact version, validates the referenced Vault kind, and derives these totals from stored
+artifacts; client-supplied totals are only estimates and cannot attest compliance:
+
+| Device profile | Unique materials | Draw calls | Decoded texture memory | Triangles | Particles |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| mobile | 48 | 300 | 256 MiB | 750,000 | 5,000 |
+| desktop | 128 | 1,200 | 1 GiB | 4,000,000 | 50,000 |
+| cinematic | 256 | 4,000 | 4 GiB | 15,000,000 | 250,000 |
+
+The Vault catalog can grow without limit; a world cannot. Start from the small built-in
+material palette, reuse the same materials and texture sets across related surfaces, and
+instance repeated meshes. Do not interpret “Vault contains thousands of materials” as
+permission to use thousands of unique materials in one scene. These descriptor limits are
+publish-contract ceilings, not performance promises; the live world performance gate still
+applies and may be stricter for a specific runtime.
+
+**VFX resources** use the renderer-neutral `.helix-vfx.json` draft and immutable texture or
+decal pins with the same exact-version/checksum validation. They do not claim Unreal support:
+no Unreal executor exists yet. Current hard ceilings are intentionally bounded:
+
+| Device profile | Live particles | Spawn rate/sec | Max lifetime |
+| --- | ---: | ---: | ---: |
+| mobile | 1,250 | 500 | 15 s |
+| desktop | 12,500 | 2,500 | 30 s |
+| cinematic | 62,500 | 10,000 | 60 s |
+
+The backend also rejects `spawn rate × maximum lifetime > live particles`, so a short burst
+cannot smuggle in an unbounded steady-state effect.
+
+**Platform assets are REJECTED if bundled.** Character bodies, faces, the 46 locomotion
+clips and system textures stream from the CDN. A `.glb` or `.ktx2` under `helix_modules/`
+fails validation — only installed *code* lives there. The built bundle of a character world
+contains no `.glb` and no `.ktx2` from the platform.
+
+**Characters** (what `import_character` targets, and what a sourced rig must meet): 8k
+triangles, 75 bones, 4 skin influences per vertex, 3 draw calls. Textures capped at 1024px
+after optimization. `import_character` conforms an external biped onto `helix-humanoid@1`
+at its own proportions, generates the LOD chain and KTX2-encodes textures — use it rather
+than hand-conforming a rig.
+
+**LIX.** Generation is metered. Budget it: search Vault first, generate once with a good
+prompt rather than three times with vague ones, and reuse across surfaces where the asset
+genuinely fits. Do not regenerate to explore. The cost is the creator's.
+
+## Definition of done
+
+`public/helix.assets.json` exists and parses · every non-`procedural` provenance row resolves
+to a path in `dist/` · **every media file in `dist/` is covered by a provenance row** ·
+`ASSET-CREDITS.md` regenerated from it · `validate_world` passes the bundle budget · no model
+in the bundle requires Draco or meshopt (`helix assets check-loaders` exit 0) · every audio cue
+referenced in code resolves to a file that ships, or is synthesised.