@hypersoniclabs/helix-cli 0.1.7 → 0.1.24-helix3.438

package/README.md

@@ -4,6 +4,12 @@
 backend. It shares bundle validation with the server via `@hypersoniclabs/helix-manifest`, so "validate passed but
 publish failed" can't happen for contract reasons.
 
+## Architecture boundary
+
+All creator feature and operational logic, validation, file mutation, network behavior, and tests
+live here. MCP packages may expose transport schemas, resources, instructions, and thin delegation
+to these commands, but must not reimplement this logic.
+
 ## Install
 
 ```bash
@@ -21,26 +27,270 @@ The token is stored in `~/.helix/credentials.json` (mode `600`). It's sent as
 `GET /api/v1/users/me` before saving and reads the token's `exp` so the CLI knows when it lapses.
 
 > **The backend & website default to the build's environment:** the published `@hypersoniclabs/*`
-> CLI targets production (`api.helixgame.com` / `helixgame.com`); the staging `@helixdev/*` CLI targets
-> the staging backend (`helix-backend-staging.up.railway.app`) + staging website (`next.helixgame.com`).
+> CLI (built from `helix3`, see [docs/npm-publishing.md](docs/npm-publishing.md)) currently targets the
+> helix3 backend + website (`helix-backend-api-helix3.up.railway.app` / `new.helixgame.com`; HYPR-5040,
+> until the production cutover repoints it). The retired `@helix3/*` and `@helixdev/*` CLIs target helix3
+> and staging respectively.
 > Override per run with `--api-url`/`HELIX_API_URL` and `--web-url`/`HELIX_WEB_URL` (e.g. a local/dev backend).
 
 ## Commands
 
 | Command | What it does |
 |---|---|
+| `helix bridge detect\|inspect\|plan\|import\|validate\|doctor` | Universal plugin-driven intake for assets, characters, animations, scenes, and engine projects. Produces deterministic plans, HELIX-native outputs, and checksummed provenance. See [`docs/bridge.md`](docs/bridge.md). |
+| `helix bridge plugins create\|test\|list\|inspect\|install\|remove` | Build and manage local/community Bridge Plugins using the versioned capability and permission contract. |
 | `helix login [--api-url <url>] [--web-url <url>] [--token <t>] [--no-browser]` | Sign in via the browser (`/cli-login`), or `--token` for CI/headless. Stores the client token. |
 | `helix logout` | Remove the stored token. |
 | `helix whoami` | Show current login status. |
-| `helix init <dir>` | Scaffold a minimal Three.js world (`helix.json` + `index.html` + `main.js`). |
-| `helix install [--update]` | Resolve a world's `systems`/`abilities` pins (a v0.2 **or v0.3** manifest) → materialize the modules, the `three` import map, and `helix.runtime.ts`. |
+| `helix init <dir> [--kind character\|multiplayer\|scene]` | Scaffold a complete, build-ready Vite + TypeScript world. `--kind scene` emits a multiplayer world whose ENVIRONMENT is a sealed HELIX Scene v2 document — the starter document is compiled offline into `public/scene/mall/`, pinned in `public/helix.json`'s `scene` field, kept out of the bundle by `public/.helixignore`, and lit by `public/helix.visuals.json` through the `scene` + `visual` system pins. |
+| `helix install [--update] [--asset-pack <slug@range>]` | Resolve a world's `systems`/`abilities` pins (a v0.2 **or v0.3** manifest) → materialize the modules, the `three` import map, and `helix.runtime.ts`. Repeat `--asset-pack` to constrain specific system assets for this resolution. |
 | `helix validate [dir]` | Validate a bundle locally — the exact rules the server enforces. |
-| `helix publish [dir]` | Validate → resolve/create the world → upload files → finalize → print the play URL. |
+| `helix publish [dir] [--thumbnail <file>] [--upload-source] [--source-dir <path>]` | Validate → resolve/create the world → upload files → finalize → set the cover image → print the play URL. `--upload-source` additionally sends the project's source through a separate private channel so the world can be edited on the website later — **off by default**. |
 | `helix list` | List your worlds. |
+| `helix vehicle simulate <dir\|vehicle-package.json> [--item <id>] [--spec <file>] [--offline] [--json]` | Drive the package offline with the platform's **own** engine instrument (the runtime `^0.3` serves today, cached by sha; offline = last cached, labelled) and judge 0-100 km/h, 0-60 mph, quarter mile, top speed, 100-0 km/h / 60-0 mph braking, skidpad g, turbo lag and the rest pose against the package `targets` and `--spec`. Exit `0` pass, `1` a figure out of tolerance, `2` could not simulate. See [docs/vehicle-simulate.md](docs/vehicle-simulate.md). |
+| `helix vehicle validate <vehicle-package.json> [--glb <model.glb>] [--no-simulate] [--json]` | One-second local gate for a hand-authored Universal Vehicle, run before Package publication. Checks the package against the engine's own validator (vendored, pinned to an engine commit), the engine publish gate, the backend pin requirements, `groundToBodyOrigin` vs `wheelRadius + staticRideHeight`, and the `componentBuild` digest; with `--glb` also resolves the four wheel nodes, checks each wheel node's origin is at its hub (`WHEEL_PIVOT_NOT_AT_HUB`), the +X-left / +Z-forward frame, the vehicle publish budgets the articulation nodes and the add-on host manifest (`asset.extras.HELIX_vehicle`); drives packages that declare `targets` (`helix vehicle simulate`). Exit `0` no errors, `1` errors, `2` unreadable input. See [Vehicle validate](#vehicle-validate). |
+| `helix vehicle publish <dir> --content-rating <r> [--item <id> --package-version <v> --reason <t>] [--json]` | Package-first vehicle publication: validate, upload the model and samples, seal a public Vehicle Package (root pins the model; `publish.json` `hostGrantExtensions` sealed beside it), make the Item from that exact Version, read back pin, identity, audio and the host board (sockets, tunable paths). Resumable; `--item` stages a new Version and moves the car. Exit `0`/`1`/`2`. See [docs/vehicle-publish.md](docs/vehicle-publish.md). |
+| `helix vehicle addon publish <dir> --content-rating <r> [--json]` | Package-first vehicle add-on publication: the full `vehicle addon check`, seal a public addon Package (a tune-only part seals no model), make the Item, read back pin, backend fit and each host's add-on rail. Exit `0`/`1`/`2`. |
+| `helix vehicle preview [<dir-or-package.json>] [--glb <model.glb>] [--addon <dir>]… [--item <id>] [--tolerance-cm <cm>] [--out <dir>] [--proxy-item <id>] [--json]` | Render a vehicle that is **not published yet** headless in the real runtime (hosted test grounds, Try Now through a published proxy vehicle whose car is swapped for your package + GLB, served from disk; nothing uploaded or recorded) and measure it: body-origin height against the declared `groundToBodyOrigin` (the number that locks at first mint), wheels on their hubs, arch clearance, rolling radius vs `wheelRadius`, steering, doors, seats. Prints a numeric summary with PASS/FAIL per check and writes frames, a contact sheet, `bundle.json` and `preview.json`. Boards with the candidate's own seat ids. With `--addon <dir>` (repeatable) it previews unpublished vehicle **add-ons** instead: fits each to the candidate car or a published car and measures the drawn geometry in world space against its anchor (wheels within 1 cm of each hub, socket/host-framed parts at their mount, not at the car's origin; tune-only ops read back from the live tuning). Exit `0` pass, `1` fail, `2` could not measure. See [docs/vehicle-preview.md](docs/vehicle-preview.md). |
+| `helix continuum publish-glb <mesh.glb> --title <t> [--package-type asset\|character] [--offer marketplace\|world --price-lix <n> --content-rating <rating>]` | Seal a Package first; optional offer makes it ownable. See [Package-first GLB publication](#package-first-glb-publication). |
+| `helix continuum make-item --package-id <id> --package-version <v> --manifest-cid <cid> --content-rating <rating> [--offer marketplace\|world --price-lix <n>]` | Project one exact sealed Package Version into an Item, with an optional first offer. |
+| `helix continuum publish-owned-item <item-id> --package-id <id> --package-version <v> --manifest-cid <cid> --content-rating <rating> --accept-rating-attestation` | Publish an existing personal Item from its unchanged public sealed Package pin. Offers are separate. |
+| `helix vehicle audio-import <mod dir\|mod .zip\|AC car dir\|.bank> --out <dir> [--sim beamng\|ac\|auto] [--vehicle <id>] [--config <file.pc>] [--map <slot-map.json>] [--beamng-root <dir>] [--cylinders N] [--base-package <vehicle-package.json>] [--json]` | Takes a car's sounds from the sim mod that carries them, never synthesised: a BeamNG mod's own ladders and every sound its parts name (stock FMOD events resolved in the install's banks with `--beamng-root`, which also supplies what the game itself plays for unnamed slots), or an Assetto Corsa car's FMOD bank. Writes `audio/*.wav` (16-bit PCM, malformed headers repaired) and `audio.json` (the package `audio` block, all 31 slots, `provenance` on every slot, bank sample and blend). `--map` merges slots from several sources. The block always carries the runtime's mix fields (gains, load mix, muffling): from `--base-package` to keep a car's current mix, else the mod's soundConfig, else the engine's defaults. Exit `1` when a slot stays empty. See [docs/vehicle-audio-import.md](docs/vehicle-audio-import.md). |
+| `helix vehicle audio-check <dir\|package.json\|audio.json\|item-id> [--reference <clip>]... [--json]` | Proves every sound the runtime will select resolves, is PCM WAV and is audible (pre-publish on local files, or read-back on a published item), and that no two roles share one recording (shift up = shift down, an exhaust rung = an engine rung) and the rev limiter is a short crack the runtime can retrigger. Prints each slot's provenance and FAILS synthesised or generated audio (`AUDIO_SYNTHESISED`), a car without a recorded engine ladder (`AUDIO_ENGINE_UNSOURCED`), a missing or empty slot (`AUDIO_SLOT_UNSOURCED`, except `absent: "not-fitted"` / `"combined-with-engine"`), recordings without provenance (`AUDIO_PROVENANCE_MISSING`) and a not-fitted claim the physics contradicts (`AUDIO_SLOT_FITMENT_MISMATCH`) and an audio block without finite mix fields (`AUDIO_MIX_FIELDS_MISSING`: a NaN gain freezes the car in Try Now); `vehicle publish` refuses the same. `--reference <clip>` (repeatable; `slot=clip` for a slot) compares the idle voice's centroid and firing roughness with a real-car recording. |
+| `helix vehicle addon check <dir> [--json]` | Add-on fit gate for local source and host compatibility, including the web customizer's meshless guard (`ADDON_CUSTOMIZER_REFUSES`: a part with no `model.glb` must be a verified tune-only/sound-only definition). |
+| `helix vehicle addon check --item <addOnId>... / --host <vehicleId>... [--json]` | Published mode (public reads, no sign-in): reads each add-on Item's exact Package pin and runs exactly what the web customizer runs; `--host` checks every add-on on the car's rail. Exit `1` = the customizer would refuse a part, with its message. |
+| `helix item list-slots [--json]` | Print the Character-Creator vocabulary a wearable declares: the cosmetic slot tags, and the genders. |
+
+| `helix item distribution create\|list\|update\|disable …` | Manage Marketplace/World Claim or Buy routes without republishing the item or paying another publish fee. |
+| `helix item visual-qa <item-id> [--submit] [--local-critic] [--storage-state <file>] [--host <id…>]` | Render the item's current package version headless in the real runtime (test-grounds world for vehicles and whole avatars, the customiser for add-ons and wearables on every declared host/base, the item viewer for props), measure it, and with `--submit` record the backend's verdict (numeric asserts + vision critic) against that exact version. **Marketplace/Vault listing, distributions and version moves on a public item require a pass.** See [docs/visual-qa.md](docs/visual-qa.md). |
+| `helix item visual-qa <item-id> --package-version <v> [--vehicle-package <file>]` | Render a version the item is **not pinned to yet**, so a refused version move can pass the gate before the pointer moves. Vehicles and avatars go through Try Now (vehicles also need the move's vehicle package), add-ons and wearables through the customiser; the bundle names the candidate, and the vehicle checksum is the one the server minted for that trial. Never falls back to the current version. See [docs/visual-qa-candidate-versions.md](docs/visual-qa-candidate-versions.md). With `--submit`, a PASS prints the next command (`helix item set-version …`); a 403 for a non-creator says so on the first line; `--status` also lists the item's pending (sealed, not current) versions. |
+| `helix item set-version <item-id> --package-version <v> --reason <text> [--expected-current-version-id <uuid>] [--as-admin] [--json]` | Move an item to a sealed Package Version of its own package (pin resolved from the public Package API; `POST /api/v1/universal-items/<id>/versions`). The flow for a **listed** item: `continuum publish-package` seals vN → `item visual-qa <id> --package-version vN --submit` → `item set-version`. A refusal prints the server's message first (it names the next command), then the remedy and any hosted render it queued. An unknown version lists the sealed ones. A **vehicle** moves its car with the pin: the version's sealed root (role `vehicle-definition`) is verified against the manifest and sent as `vehiclePackage`, the same rider `vehicle publish --item` sends; a version without one is refused with a pointer to that resume. A version the item **already had** is a rollback: `PUT /api/v1/universal-items/<id>/versions/current { revision, reason }` (the server restores that revision's retained `vehiclePackage`; a pin-only revision has none and is refused). `--as-admin` (platform admins, for an item another account created) posts the same body to `POST /api/v1/admin/universal-items/<id>/versions`: same gates (visual QA included, no override), `--reason` recorded with you as the actor. |
+| `helix item thumbnail refresh <item-id> [--force] [--dry-run] [--json]` | Re-render a published item's canonical thumbnail from its **active Package Version** with the standard server renderer (`POST /api/v1/universal-items/<id>/thumbnail/regenerate`, owner or admin). Prints the status (`generated` / `current` / `dry-run`), old -> new thumbnail URL, renderer version and the source lane + Package Version. `--dry-run` writes nothing; `--force` re-renders even when the stored thumbnail is current. Moving an item to a new Package Version now refreshes the thumbnail automatically unless you uploaded one. An older backend answers 404 and the CLI says it does not support thumbnail refresh yet. Not the world `helix thumbnail set <slug>` command. |
+| `helix item thumbnail set <item-id> <image> [--json]` | Upload your own thumbnail (png/jpg/webp, up to 10 MiB, checked locally) for a published item (`PUT /api/v1/universal-items/<id>/thumbnail`, moderated). A creator upload stays in place across version moves until you run `thumbnail refresh --force`. 403 = you are not the item's owner. |
+| `helix device create <dir> --id <slug> --title <t> --model <mesh.glb> --template standing-desk\|clock\|television` | Scaffold a GLB-backed `helix.device/1` definition, including the interactive TV/media-player template. There is intentionally no website Device editor. |
+| `helix device validate [dir] [--json]` | Validate the definition, GLB bytes and named-node bindings, typed state/controls, capabilities, and Home+World compatibility, including [declarative character hand reach](docs/device-hand-reach.md). |
+| `helix device test [dir] [--mode single\|multiplayer\|both] [--json]` | Exercise every interaction, persistence remount, and deterministic one-/two-client authority convergence. |
+| `helix world scene-elements compile <input> --output <scene>` | Compile typed Scene v2 authoring, including exact Continuum Device pins, instances, and locally validated typed links. See [`examples/scene-elements-devices.json`](examples/scene-elements-devices.json). |
+| `helix preview-video <slug> <youtube-url>` | Set or clear a published world's YouTube preview. |
+| `helix thumbnail set <slug> <file>` | Upload a thumbnail or preview image through the CLI-owned media path. |
+| `helix assets search\|get\|versions\|track\|install\|update` | Search the typed Vault with explainable ranking; inspect/manage annotations and immutable versions; install by durable ID with verified SHA-256 receipts. Material installs default to lean runtime KTX2 maps; use `--material-renditions source` for source PNGs or `all` for both families. |
+| `helix assets start\|status\|generate\|resume` | Start or poll generation without duplicates. Props/characters use the main Dreamer path; standalone assets use the shared broker and report the auto-published `vaultAssetId`. `generate` and `resume` block waiting for the job (see `--timeout`/`--poll-interval` below). |
+| `helix assets voices [--search <text>] [--category premade\|professional] [--page-size <n>] [--page-token <token>] [--json]` | Discover safe text-to-speech voices through the authenticated HELIX catalog, including language, labels, preview, default/recommended selection, and pagination. |
+| `helix assets generate-image\|generate-material\|generate-audio\|generate-environment` | Run the supported standalone generation adapters. Material is a validated PBR bundle (1K default, explicit 2K); splats declare object/environment scope. Animation remains an explicit unavailable boundary. |
+| `helix assets start-reference\|generate-reference` | Start or fully drive a character job from a local four-view PNG/JPEG/WebP. The backend validates and reuses the exact sheet; it skips image generation while preserving mesh, texture, rig, LOD, thumbnail, billing, and Vault publication. `generate-reference` blocks waiting for the job (see `--timeout`/`--poll-interval` below). |
+| `helix assets generate\|generate-reference\|resume [--timeout <ms>] [--poll-interval <ms>]` | These three drive a Dreamer prop/character job to completion (concept → mesh → texture → rig → publish) and block until it finishes. `--timeout` bounds how long the CLI process waits before giving up (default **1200000ms / 20min**, unchanged if omitted); `--poll-interval` sets how often it checks job status while waiting (default **2000ms**). A timeout is a CLIENT-SIDE giveup, not a job failure — the Dreamer job keeps running server-side. The error prints the exact `helix assets resume <job-id>` command to check on or continue it; on a genuinely slow stage (e.g. mesh generation), rerun with a larger `--timeout`, or just poll separately with `helix assets status <job-id> --pipeline dreamer`. |
+| `helix assets materials [--resolution <res>] [--no-resolve] [--human]` | Discover the small built-in material palette. `--resolution` keeps only materials carrying that texture resolution. Each entry also carries the Scene v2 `vault` pin and the `continuum` package ref; `--no-resolve` skips those lookups. |
+| `helix assets material <id> [--resolution <res>] [--no-resolve] [--human]` | Resolve one material to its immutable map URLs at the resolution you pick (default: the pack's own default), plus its `vault` pin and `continuum` ref. |
+| `helix assets credits\|check-loaders` | Render asset credits from provenance and reject models requiring unsupported loaders. |
+| `helix character import <body.glb> [--map <json>] [--fit source\|canonical] [--provenance <json>]` | Convert one self-contained third-party humanoid through the public `helix-humanoid@1` pipeline. The command rejects external/remote resources and resource bombs before parsing, generates bounded LODs, and emits a source/license/transformation/checksum receipt beside the output. `--fit canonical` aligns the rest skeleton/proportions; it does not prove that Base Male-targeted garments fit a different body surface. Hands fused to the thighs (an A-pose mesher merging touching surfaces) are cut free and re-weighted per side, gated on a walk-stride stretch measure; `--limb-bridges report` only logs what it would change, `off` skips it. |
+| `helix character fit <addon.glb> --body <base.glb> -o <out.glb> (--slot-type <character.x@1>\|--hidden-regions <globs\|none>) [--clearance-mm 3]` | Pose-aware poke-through fit for a packaged character add-on (every LOD): across the canonical pose set, pushes garment geometry out along the body-facing normal to a minimum clearance, smoothed so hems and silhouettes keep their shape. Gated inside the stage by the poke-through measurement: the output is the fitted mesh only when it is strictly better (exit 0), otherwise a byte-identical copy of the input (exit 3). Bridge add-on imports run the same stage automatically; use the fitted output in a new sealed Package Version. |
+| `helix character ear-clearance <addon.glb> --body <base.glb> (-o <out.glb>\|--check) [--target-mm 4] [--trigger-mm 1.5] [--max-push-mm 18] [--json]` | Head-zone check and fix for headwear / mask / hair / eyewear: finds the base body's ears, measures the clearance to the OUTERMOST garment layer around each (horizontal ray from the head axis, per LOD; only samples the garment wraps on all four sides count, so a mask that stops in front of the ear or a cap above it is not a defect) and, when a wrapped ear has < 1.5 mm, pushes the garment smoothly outward (Gaussian field, sigma 22 mm, horizontal only, <= 18 mm total, every LOD). Kept only when no ear pokes afterwards. `--check` writes nothing and exits 3 when an ear pokes through. `helix character fit` runs it automatically for head-zone slot types (`--no-ear-clearance` skips it; `--ear-clearance` forces it); seal the corrected mesh in a new Package Version. The pose-aware fit cannot do this job on a thin head shell. |
+| `helix character derive-hide <addon.glb> --body <base.glb> --slot-type <character.x@1> [--threshold 98] [--ops-out ops.json] [--json]` | Measures which of the slot's granted body regions the garment fully occludes (bind pose; a body vertex counts when garment is in front of it along its outward normal within 60 mm; the least-covered LOD decides) and prints the `hide` ops that follow, with the measured share of every region left visible. A region is hidden only at >= 98 % AND when no triangle the hide would collapse (engine rule: >= 2 corners hidden) reaches a body vertex the garment does not cover (the sawtooth under a hem or collar); partly covered regions stay visible and the pose-aware fit keeps their skin from poking through. Bridge add-on conform does this automatically when the profile names no `hideRegions`; include the resulting operations in the new sealed Package Version before moving the Item. |
+| `helix character retarget-animation <clip.fbx\|clip.glb>` | Retarget a raw Mixamo/Meshy clip directly to `helix-humanoid@1`. FBX conversion is deterministic and runs inside the CLI; no hidden Blender/DCC pre-export is required. |
+| `helix pack scaffold\|validate <dir>` | Scaffold and validate locomotion clip sources offline. Seal an add-on Package before any Item or offer is created. |
+| `helix world audit\|source-audit\|perf-gate\|prove-live` | Run the blocking world QA, performance, and deployed-build identity gates. |
+| `helix world performance-report [bundle] [--scene <scene-v2.json>] [--package <package-version.json>] [--snapshot <inspect.json>] [--perf <receipt.json>]` | Analyze exact declared scene resources and existing reference-profile budgets, while keeping authored geometry/material/delivery estimates separate from supplied runtime claims. Prints actionable instancing, Palette, lighting, transfer, and visual-QA guidance; it never predicts FPS from static counts. |
+| `helix world scene-source inventory\|compile <helsinki\|bistro> <archive>` | Verify and safely inventory a known CC BY source archive, then compile deterministic local proxy/detail GLBs and an existing-schema Scene v2 package. |
+| `helix world scene-source publish <world-id> <package-dir> [--publish]` | Validate the Scene v2 package and print its multipart build receipt. Execution remains dry-run-only until backend private-pin entitlement lands; `--publish` currently fails closed, and access control never changes CC BY rights. |
+| `helix continuum publish-source-map\|publish-scratch\|publish-package\|publish-glb\|make-item\|publish-owned-item` | Resume exact-CID object adoption/ingestion, Package lease/seal, optional explicitly authorized Listing, and WorldRelease publication through one creator-owned pipeline. |
+| `helix continuum receipt <job-id>` | Read the sanitized durable receipt for a completed Continuum publication. |
+| `helix unreal init\|validate\|doctor\|package [project]` | Create and gate a shared-runtime or native-game publish manifest, check optional editor MCP, and assemble a local upload-shaped package. |
+| `helix unreal publish <candidate> --world <slug>` | Upload a **cooked** Unreal world to HELIX: verify the candidate, presign, upload every artifact, finalize, and promote it as the world's active build. |
 | `helix doctor [--project <dir>]` | Print the environment + whether the @helix toolchain (CLI/MCP/SDK/manifest) is current. |
 
+### Constraining system assets during installation
+
+To update system code while deliberately selecting a compatible asset version:
+
+```bash
+# helix.json keeps the range, e.g. humanoid-character: "^0.3"; only the asset pack is constrained
+helix install --update --asset-pack humanoid-character-assets@0.1.4
+```
+
+`--asset-pack <slug@range>` is repeatable for different asset slugs. Supported ranges
+are exact versions, `^`/`~` ranges (partial versions are padded as for system pins),
+`latest`, and `*`. Resolution selects the highest active version satisfying both
+the explicit constraint and the system envelope's asset requirement. Complete exact
+pins use the authoritative public version-detail endpoint, including active staged
+versions. Incorrect kinds/identities, unused slugs, duplicates, invalid ranges,
+missing versions, and incompatible constraints fail before installer writes.
+
+These constraints apply to **this invocation**. An existing lock requires `--update`;
+a fresh install can use the option without a lock. The installer resolves from the
+catalog and writes the exact asset URL/version and unchanged envelope `range` into
+the lock, with invocation intent recorded in top-level `assetPackConstraints`.
+It does not reuse unverified asset metadata
+from an old lock. Normal `helix install` then replays that generated lock as usual.
+
+A subsequent `helix install --update` without the option refreshes all dependencies
+from their ordinary requirements, including previously constrained assets. Repeat the
+option in your update command to retain the constraint. It is not a world manifest
+field or a permanent asset freeze, and cannot be combined with local first-party
+installation. Generated locks, import maps and runtime modules remain installer-owned.
+
+## Unreal runtime projects
+
+`helix unreal init <project> --mode shared-runtime|native-game` creates `helix.unreal.json`.
+Shared-runtime projects ship cooked content/Blueprints against a pinned HELIX runtime; native-game
+projects ship separate signed client/server builds and may use custom C++ and plugins. Both require
+Unreal 5.8, the HelixSDK plugin, and HelixPlatform identity/session integration.
+
+Networking is explicit: `unreal-native`, `helixnet`, `custom`, or `none`. Only `helixnet` requires
+contract v21; blank Unreal projects using arbitrary GameMode/Pawn classes and native networking do
+not need Lyra Experiences, Colyseus, or the HelixNet contract.
+
+`helix unreal validate` is the publish gate and does not require MCP. `helix unreal doctor` adds the
+loopback/editor-only Unreal MCP authoring checks. `helix unreal package` copies validated cooked or
+native artifacts into a local checksummed staging directory — it is a local assembly step, not a
+publish.
+
+### Publishing a cooked world
+
+`helix unreal publish <candidate> --world <slug-or-id>` takes the directory the Unreal
+`HelixWorldPublish` commandlet writes — `world-build-manifest.json`, its `.sha256` receipt,
+`cook-plan.json`, and `artifacts/<role>/…` — and gets it live in one command:
+
+```
+helix unreal publish Saved/HelixPublish --world my-world --max-players 32 --visibility unlisted
+```
+
+It verifies the candidate against the bytes on disk (every digest recomputed — a manifest is a
+claim, not evidence), registers the Build and presigns each artifact, streams the uploads,
+finalizes so the server re-verifies every byte by size and SHA-256 and countersigns the manifest,
+then promotes the Build as the world's active release. `--no-promote` stops after verification;
+`--verify-delivery` additionally checks what a client would actually download.
+
+The idempotency key defaults to the cooked manifest's own digest, so re-running after a dropped
+connection resumes the same Build rather than minting a second one.
+
+Only **shared-runtime** worlds publish this way. A World Build may not contain creator
+executables, so `native-game` builds are a separate distribution path.
+
+## Working in a git worktree? Run this first
+
+```
+npm run check:dev-links
+```
+
+`package.json` links its sibling HELIX packages by relative path
+(`file:../helix-manifest`, `file:../helix-web-sdk`). That is right in the canonical
+layout, where the siblings sit beside this clone — but in a **git worktree** `../` is
+the worktree parent, so the links resolve to whatever happens to be there: a checkout
+parked on an older branch, or nothing at all.
+
+The symptom is not "broken dev link". It is **a branch that looks broken**: `tsc`
+reporting `has no exported member …` in files your change never touched, and whole
+suites failing at import (`could not find the dev shell in @hypersoniclabs/helix-sdk`).
+People have concluded a PR was broken on the strength of exactly this.
+
+`check:dev-links` names which link is wrong, which imported symbols the linked sibling
+does not export, and how to fix it without repointing a shared directory other
+worktrees resolve through.
+
 ## Publish flow
 
+### Platform system updates
+
+`helix install` records platform-owned systems in `public/helix.runtime.json`.
+Compatible ranges such as `^0.2` are externalized and resolved to an active,
+immutable catalog module when a world launches, so a compatible platform fix can
+reach an already-published world without creator edits or republishing. A new
+runtime version reaches no world until the platform deliberately publishes it to
+the catalog and it goes active there — building or merging one changes nothing on
+its own, and there is no rolling "latest".
+
+**Engine systems are ranges.** Declare `"systems": { "humanoid-character": "^0.3", "engine-core": "^0.1", "scene": "^0.3", "visual": "^0.1" }`
+so a World loads the latest *promoted* engine at launch. An exact version such as
+`0.3.178` maps to the immutable catalog URL and freezes the World on that build
+forever, so `helix validate` and `helix publish` **refuse** it. If an engine fix
+is staged but not yet promoted, **promote it** (`POST /api/v1/instant-packages/<slug>/versions/<version>/rollout`,
+`{"rolloutPercent":100,"reason":"…"}`); do not pin Worlds to it. The one escape
+hatch is deliberate and audited:
+
+```bash
+helix publish dist --allow-exact-engine-pin "<why this World must stay frozen>"
+```
+
+The reason is required (an empty one is refused), a loud warning is printed, and the
+override (reason, slug, pinned versions) is appended to
+`~/.helix/engine-pin-overrides.jsonl` (`HELIX_ENGINE_PIN_OVERRIDE_LOG` relocates it).
+`helix validate` takes the same flag. A custom Vite config is never rewritten: install reports
+`legacy-bundled` until the creator explicitly externalizes `@helix/*`.
+`helix validate`, `helix publish`, and the publish API refuse that legacy mode
+too. `latest` and `*` are not accepted publish ranges because they
+can cross a compatibility boundary.
+
+The platform runtime is on three **0.185.1**. The version is a property of the
+pinned system — `humanoid-character@^0.3` resolves to an envelope declaring it —
+and `helix install` bakes it into the import map immutably, so an already-published
+world keeps running whatever it baked. A world behind that line still publishes:
+`helix validate` and `helix publish` only warn, naming the upgrade path (re-pin
+`^0.3`, `helix install --update`, rebuild, republish), and `helix doctor` reports it
+(and a local devDep `three` that has drifted off the platform runtime) before you build.
+
+That update contract is deliberately narrower than "the SDK updates itself":
+
+| World dependency | What the built bytes contain | What can advance without republishing |
+| --- | --- | --- |
+| Platform systems (`@helix/humanoid-character`, `@helix/engine-core` and declared subpaths) with a compatible range | Bare imports plus a generated import-map entry | The compatible catalog target on the next fresh launch |
+| Platform systems with an exact version (**refused** by validate/publish without `--allow-exact-engine-pin "<reason>"`) | Bare imports plus the exact immutable catalog URL | Nothing; the pin stays byte-identical |
+| Creator SDK (`@hypersoniclabs/helix-sdk`) | The SDK module graph bundled into the world's own JavaScript | Nothing; SDK changes require rebuilding and republishing the world |
+| Installed abilities (`public/helix_modules/*`) | Verified ability code/assets copied into the world build and indexed by `installed.json` | Nothing; update/install and republish are explicit creator actions |
+| Creator game code and assets | The world's own immutable build files | Nothing; the platform never rewrites a published creator bundle |
+
+The generated import map, `helix.runtime.json`, and
+`helix_modules/installed.json` are the authoritative way to inspect which side
+of this boundary a particular build uses. Browser or proxy caching may serve a
+previous compatible resolver response during a transient outage; the descriptor's
+`lastKnownGood` field is provenance metadata, not an executable in-world fallback.
+Without a cached resolver response, a cold resolver failure fails closed.
+
+Native features remain individually overridable without pinning the whole
+character runtime. The character system's **native avatar features** — carried
+emotes and the radial wheel (including its Customize door), x-ray, pointing,
+sitting, the avatar camera, the two camera legs, and rendering each player's
+universal avatar — are constructed by the character chassis itself, so every
+character World has them whether it was built on `Character` or on
+`CharacterMultiplayer`, and a World published today receives ones added later on
+its next fresh launch.
+
+A World refuses what it does not want by NAME, in the character config it passes
+at create time — not in `helix.json`, and nothing here is a publish-time concern:
+
+```ts
+config: { character: { native: { disabled: ['xray', 'pointing'] } } }
+```
+
+Ids: `emotes`, `emote-wheel`, `xray`, `pointing`, `sitting`, `avatar-camera`,
+`camera-first-person`, `camera-third-person`, `universal-avatar`. It is a
+**blocklist, never an allow-list**, for the same reason this whole delivery
+contract exists: an allow-list would freeze every already-published World out of
+every feature added afterwards. A refusal also removes the feature's key,
+controller button, touch pad and prompt; `universal-avatar` is the top switch and
+takes emotes, the wheel, x-ray, pointing, sitting and the avatar camera with it
+(the camera legs survive — a World still needs a camera); refusing BOTH camera
+legs throws at create; and an unrecognised id is kept with a warning rather than
+rejected, because it may belong to a newer runtime. The older switches still
+work and route into the same resolver: `CharacterMultiplayer.create`'s
+`emotes: false`, `emoteWheel: false` and `universalAvatars: false`, and the
+config keys `character.emote.enabled`, `character.emote.wheel`,
+`character.xray.enabled`, `character.universalAvatar.enabled`. (`localControl:
+false` is not one of these — it declares a spectator body the World drives its
+own camera and input for.) Every other compatible native fix continues to update
+normally.
+
+This surface needs `@helix/humanoid-character` **0.2.54** or newer; an older
+runtime ignores `character.native.disabled` silently, so confirm against the
+resolved system's config schema rather than assuming. The full creator reference
+is the character world recipe in the HELIX MCP docs
+(`read_doc({ name: "character-world" })`, section 8g); the authoritative id list
+and defaults are that config schema, readable from the installed system
+manifest.
+
+The runtime descriptor is mandatory for bundles that declare systems. It makes
+the delivery boundary inspectable by the CLI, MCP, backend, and fleet census;
+it does not execute code or silently rewrite an old minified bundle.
+
 `helix publish` maps directly onto the backend's Instant World API:
 
 1. `checkBundle` validates `helix.json` + files via `@hypersoniclabs/helix-manifest`.
@@ -51,14 +301,387 @@ The token is stored in `~/.helix/credentials.json` (mode `600`). It's sent as
 5. `POST /api/v1/instant-worlds/:id/builds/:buildId/finalize` → byte-exact verify, activate, publish.
 6. `GET /api/v1/instant-worlds/:slug` → the play URL.
 
-The programmatic surface (`publishWorld`, `checkBundle`, `whoAmI`, …) is exported from the package
-main, so an MCP server can drive the exact same code paths an agent would.
+`helix.json`'s fields are the shared manifest's, not the CLI's — including the optional v0.3 `scene`
+pin (`{kind, id, revision, integrity:{sha256}}`, or a `continuum-scene` package triple) naming the
+sealed Scene document a world streams as its environment; `integrity.sha256` is the authority and
+`id`/`revision` are display text. Reference: `docs/helix-scene-v2.md` in `@hypersoniclabs/helix-manifest`.
+
+### .helixignore
+
+An optional gitignore-style exclude list read at the **bundle root**. Matching paths are left out of
+the upload and out of the 50 MB / 200-file budgets, and the file itself is never uploaded.
+`helix validate` and `helix publish` print `excluded N path(s) via .helixignore` when it drops anything.
+
+- Blank lines and `#` comments are ignored.
+- `scene/` — a trailing slash matches a directory and everything under it.
+- `scene/pin.json` — a plain path, relative to the bundle root, forward slashes.
+- `*.map` and `**/notes.txt` — `*` stays inside one path segment, `**/` crosses segments.
+- `!keep.json` re-includes: rules apply in order and the last match wins. As in git, nothing under an
+  excluded directory can be re-included.
+
+It must land at the bundle root, so a Vite world keeps it at `public/.helixignore` and the build copies
+it into `dist/`. `node_modules`, `.git`, `.vscode`, `.idea` and `screenshots` are dropped regardless and
+need no rule.
+
+The case it exists for: a `@helix/scene` world keeps its dev-only Scene document and source GLBs under
+`public/scene/`, which Vite copies verbatim. One `scene/` line keeps megabytes of authoring bytes out of
+every player's download.
+
+### Opt-in source upload
+
+A published world ships only its **built bundle**, so there is nothing on the server to edit later.
+`--upload-source` adds a second, separate upload that fixes that:
+
+7. `POST /api/v1/instant-worlds/:id/source` → a presigned PUT into a **private** bucket (this call
+   also adopts the world into a project, which is the key its future workspace hangs from).
+8. `helix-source.tar.gz` PUT with `cache-control: no-store`.
+9. `POST /api/v1/instant-worlds/:id/source/finalize` → the server verifies the stored byte count
+   equals the declared one, then records the version.
+
+- **Off by default.** Source is never sent unless you pass the flag. Not a prompt — an interactive
+  confirm would break CI and agent-driven publishes.
+- **What goes in**: the project directory, honouring `.gitignore`, always excluding `node_modules`,
+  `.git`, `dist` and `.vite` — the same exclude set the website's own workspace checkpoints use.
+- **Which directory**: `[dir]` is the BUILT bundle, so the source defaults to its parent. Override
+  with `--source-dir <path>`.
+- **Never part of the build.** The bundle's content-type allowlist rejects archives, raw `.ts` is
+  excluded from a bundle by design, the bundle size budget is the playable budget, and every build
+  file lands on a public CDN path with a year-long immutable cache. Source uses its own private
+  channel for exactly that reason.
+- **Limit**: 128 MiB compressed, checked locally before anything is uploaded.
+
+Before upload, multiplayer worlds that install modules are checked for server realizability. A
+module with a `bank` reference must name a bank that is published with the declared checksum (bank
+modules belong to the default `multiplayer` block; the manifest validator refuses one inside a room
+type). A module without `bank` is inline: its rules are in the manifest, so there is nothing to
+resolve. The modules of every program (the default block and each `multiplayer.roomTypes` entry)
+must then fit the 100,000 tick-node ceiling at the number of players that program's room holds: 24
+for a standard default block, a room type's own `maxPlayers` up to 24, and the declared `maxPlayers`
+up to 64 with `capacityClass: "large"`, never fewer than 2. Fix the named module or bank when this
+gate refuses a publish. For exceptional recovery only, `--skip-realizability-check` bypasses this
+check; worlds without modules are unaffected.
+
+The programmatic surface (`publishWorld`, `checkBundle`, `whoAmI`, …) is exported for other CLI
+modules. Agent integrations should instruct or delegate to the `helix` commands above rather than
+reimplementing operational behavior in a transport package.
+
+## Vault lifecycle
+
+Use the durable Vault UUID as the handle. Search results include independent lexical, hard-filter,
+measured-performance, reuse, and availability explanations; they do not collapse those signals into
+a made-up score. `helix assets install` resolves an immutable version, follows the `/download`
+indirection, verifies its server checksum and byte count, installs related material maps, and writes
+`public/helix.assets.json`. Material installs keep the descriptor and default to the runtime KTX2
+map family only; choose source PNGs with `--material-renditions source`, or both families with
+`--material-renditions all`. Reinstalling with a different selection removes the stale opposite
+family. Non-material assets keep their existing related-artifact behavior. For a reproducible agent build, pass `--asset-version`,
+`--checksum-sha256`, and `--size-bytes` together; a partial pin or any metadata/download mismatch
+fails before a provenance receipt is written.
+
+Generation is source-agnostic at the backend:
+
+- `prop` and `character` start through the main Dreamer route, which seals a Package
+  before any optional Item offer.
+- `image`, `material`, `audio`, and `gaussian_splat` start through the shared asset route.
+  Gaussian splats must declare `object` or `environment` scope.
+- `animation` fails locally with `CAPABILITY_UNAVAILABLE`; it never starts a chargeable job.
+
+Run `helix assets status <job-id> --pipeline dreamer|asset` to poll an existing job. A successful
+default-on generation reports `vaultAssetId` and `vaultAutoPublish: "published"`; an explicit
+creator opt-out reports `"disabled"`.
+
+For `.helix-scene.json`, the open Vault catalog is not the scene-local budget. Reuse a small
+material palette and instance repeated assets. The canonical ceilings are:
+
+| 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 |
+
+These are publish-contract ceilings, not frame-rate promises; world runtime QA still applies.
+
+The lifecycle acceptance harness intentionally has no CLI-local demo. Point it
+at a built world in `helix-web-demo-worlds` that consumes the published SDK and
+humanoid runtime:
+
+```bash
+npm run qa:vault-lifecycle -- \
+  --world-template /path/to/helix-web-demo-worlds/worlds/sdk-showcase
+```
+
+Publishing is an explicit release-only action and additionally requires a new
+approved slug:
+
+```bash
+npm run qa:vault-lifecycle -- \
+  --world-template /path/to/helix-web-demo-worlds/worlds/sdk-showcase \
+  --publish --world-slug ch1146-vault-lifecycle-qa-<unique-suffix>
+```
+
+The publish receipt requires one usage increment, one world association, and
+an idempotent second publish with no additional increment.
+
+### Audio generation
+
+All three audio modes use the same authenticated Dreamer route and automatically publish the
+completed MP3 to Vault. The command waits up to 30 minutes so a ten-minute music request has enough
+time to render, ingest, and publish. It prints the durable `vaultAssetId`, measured Spark charge,
+provider cost, and server-stamped `billingEvidence`. It does not download another local copy unless
+`--output` is supplied.
+
+```bash
+# Sound effect
+helix assets generate-audio "heavy metal door slamming shut" \
+  --mode sound_effect --duration-seconds 3 --prompt-influence 0.4 --output door.mp3
+
+# Music
+helix assets generate-audio "hopeful orchestral exploration theme" \
+  --mode music --duration-seconds 180 --force-instrumental
+
+# Text to speech
+helix assets voices --search narrator --page-size 10
+helix assets generate-audio --mode text_to_speech \
+  --text "Welcome to HELIX." --voice-id <id-from-catalog> \
+  --language-code en --stability 0.5 --speaker-boost
+```
+
+Use the opaque `--page-token` printed by a page to continue. Voice cloning and
+voice administration are deliberately not exposed.
+
+Use a deterministic four-view sheet when you already have approved FRONT, BACK,
+LEFT, and RIGHT character art and do not want Dreamer to generate another image:
+
+```bash
+helix assets generate-reference ./character-four-views.png \
+  "compact friendly service robot, game-ready humanoid proportions" \
+  --title "Service Robot" \
+  --target-polycount 12000
+```
+
+The reference endpoint is character-only. The file is image-guarded, normalized,
+checksum-bound to the job, semantically validated, and mirrored before approval.
+Retries reuse those same bytes and never invoke or charge the image provider.
+
+## Material texture resolution
+
+A platform material can ship more than one texture resolution. `--resolution` picks which one you
+get; without it you get the pack's declared default, byte-for-byte what every earlier CLI returned.
+
+```bash
+helix assets material brick-block                      # the pack's default resolution
+helix assets material brick-block --resolution 2k      # the 2K variant's map URLs
+helix assets material brick-block --resolution 2048    # same thing — numeric spelling
+helix assets materials --resolution 2k --human         # only materials that carry 2K
+```
+
+Accepted values are the keys the catalog itself declares (`1k`, `2k`, …), case-insensitively, plus
+the numeric aliases `1024`/`2048`, which map onto the variant authored at that pixel edge.
+
+Both commands print JSON by default (agents and the MCP delegation parse it); `--human` prints a
+readable summary instead. Either way the output states **which resolution was resolved and which
+ones the material offers**, under `resolution`:
+
+```jsonc
+"resolution": {
+  "requested": "2k", "resolved": "2k", "pixels": 2048, "default": "1k",
+  "available": [{ "key": "1k", "pixels": 1024 }, { "key": "2k", "pixels": 2048 }],
+  "applicable": true
+}
+```
+
+Three rules make this safe to rely on:
+
+- **No silent fallback, ever.** Asking for a resolution the material does not carry is an error that
+  names the ones it does. You never receive a different resolution than the one you asked for.
+- **Old packs keep working.** A catalog with no `resolutions` block (`schemaVersion: 1`) is treated
+  as having exactly one resolution, keyed `default`, derived from its existing `maps`. Such a pack
+  never claims to be "1k" — it does not say how big its textures are, so neither do we.
+- **Procedural materials are not an error.** `glass` and `procedural_water` carry no texture maps;
+  a resolution request against them is ignored and the output says so in `resolution.note`.
+
+`helix assets install` has no resolution flag: Vault related-artifact roles are semantic
+(`source.albedo`, `runtime.ktx2.normal`, `sky.backdrop`), never resolution-tagged, so a filter there
+would filter nothing.
+
+## Pinning a platform material — the Vault pin and the Continuum ref
+
+A catalog `id` such as `white-marble` is a pack-local name. No scene format accepts it, so both
+material commands also return the two identities an author actually writes down:
+
+```jsonc
+"vault": { "assetId": "6d7ac215-…", "revision": 2 },
+"continuum": {
+  "packageId": "3970d36f-9374-56f9-9be8-576bfa70fa8d",
+  "listingId": "33a5a6bc-…",
+  "version": "1.0.1",
+  "manifestCid": "cid:sha256:b7a3206f…"
+}
+```
+
+**`vault` is the Scene v2 identity.** A `materials[]` entry must resolve to a `material` resource
+whose source is an immutable Vault pin (`helix-manifest/src/scene-v2.ts:1627-1628`), so the pin is
+written on the resource and the material points at it:
+
+```jsonc
+"resources": [{
+  "id": "res-white-marble",
+  "kind": "material",
+  "source": { "kind": "vault", "assetId": "6d7ac215-…", "revision": 2 },
+  "integrity": { "sha256": "…" },
+  "mimeType": "application/vnd.helix.material+json"
+}],
+"materials": [{
+  "id": "mat-white-marble",
+  "resource": "res-white-marble",
+  "defaults": { "tint": "#ffffff", "repeatPerMeter": 1, "roughnessScale": 1, "metalnessScale": 1 }
+}]
+```
+
+**`continuum` is the semantic-scene identity.** A `sceneDocument.materialBindings[].binding`
+(`helix-manifest/src/continuum/material.ts:111-136`) references a Package Version and never owns
+maps:
+
+```jsonc
+{
+  "id": "white-marble",
+  "binding": {
+    "schema": "helix.continuum.material-binding/1",
+    "material": { "packageId": "3970d36f-…", "version": "1.0.1", "manifestCid": "cid:sha256:…" },
+    "slot": "white-marble",
+    "tint": [1, 1, 1, 1],
+    "opacity": 1,
+    "roughnessScale": 1, "metallicScale": 1, "normalScale": 1, "emissiveScale": 1,
+    "uv": { "set": 0, "offset": [0, 0], "scale": [1, 1], "rotationDeg": 0, "tiling": [1, 1] }
+  }
+}
+```
+
+The same `{ packageId, version, manifestCid }` triple is what a scratch descriptor's
+`source.materials[].sourcePackage` and every entry of `compilation.dependencyClosures[]` require.
+
+How each field is resolved, and what a null means:
+
+| Field | Route | Login |
+| --- | --- | --- |
+| `vault` | `GET /api/v1/vault/assets?q=platform-material:<id>&kind=material&match=narrow` | not needed — the route is public and the CLI sends no token |
+| `continuum.listingId` / `version` / `manifestCid` | `GET /api/v1/vault/catalog?packageType=material&q=<id, hyphens as spaces>` | not needed — public |
+
+- `continuum.packageId` is a **pure function of the catalog id** — no lookup, always present, stable
+  forever: `deterministicContinuumUuid("helix.material.catalog/1\0" + id)`. The catalog page is
+  filtered on that derived id, never on a title, so a same-named Listing cannot become a wrong pin.
+- `vault: null` means the platform tag matched zero **or several** assets — exactly one match is the
+  only pinnable state (the same rule the Home scene loader applies). Several also sets
+  `vaultWarning: "ambiguous: N matches"`.
+- `version: null` means no sealed public Package Version for that id on this lane.
+- A failed lookup never masquerades as an absence: it sets `vaultWarning` / `continuumWarning` to
+  `lookup failed: …` and leaves the rest of the catalog intact.
+- `--no-resolve` makes no request at all. Entries then carry only the derived `continuum.packageId`
+  and **no `vault` key** — absent, not `null`, so "not looked up" cannot be read as "not there".
+- Lookups run at most 8 in flight and are cached for the life of the process.
+
+## Vehicle validate
+
+`helix vehicle validate <vehicle-package.json> [--glb <model.glb>] [--no-simulate] [--offline] [--json]` needs no login.
+This local gate checks the vehicle Package and optional GLB before any publication. When the package declares
+`targets` it also drives the car with the platform's engine instrument (`helix vehicle simulate`; the runtime is
+fetched once and cached, `--offline` uses the cache, `--no-simulate` skips the drive) and reports every figure
+outside its tolerance as `SIMULATED_PERFORMANCE_OUT_OF_TOLERANCE`.
+
+Every finding prints as `CODE  path — message` plus a `fix:` line; `--json` returns
+`{ ok, errors, warnings, issues: [{ code, level, path, message, fix }], engineCommit }`.
+
+| Layer | Codes |
+|---|---|
+| Engine validator (all its errors and warnings) | `ENGINE_VALIDATOR`, `ENGINE_VALIDATOR_CRASH` |
+| Publish gate + backend pin | `PACKAGE_NOT_OBJECT`, `PACKAGE_VERSION_UNSUPPORTED`, `SCHEMA_VERSION_MISMATCH`, `REQUIRED_FIELD_MISSING`, `REQUIRED_BLOCK_MISSING`, `MESH_CLASS_ID_MISSING`, `MESH_PARTS_MISSING`, `WHEEL_VISUALS_MISSING`, `WHEEL_VISUALS_INVALID`, `NOT_DISTRIBUTABLE`, `MESH_SOURCE_FIXTURE`, `PUBLISH_GATE` |
+| Cross-field | `GROUND_TO_BODY_ORIGIN_MISMATCH` (> 5 mm; fix the ride height, the field is locked after first publish), `COMPONENT_BUILD_DIGEST_MISMATCH` (prints the computed digest), `COMPONENT_ACTIONS_MISMATCH` (prints the compiled protocol), `COMPONENT_BUILD_INVALID`, `PANEL_SIGNAL_NO_ACTION` (warn), `SEAT_SOCKET_UNKNOWN` (warn) |
+| Drive (package `targets`) | `SIMULATED_PERFORMANCE_OUT_OF_TOLERANCE` (figure, simulated, target, error, tolerance, engine version), `SIMULATED_REST_POSE_INVALID`, `SIMULATION_UNAVAILABLE` (warn: no runtime reachable or cached) |
+| `--glb` host manifest | `HOST_MANIFEST_MISSING`, `HOST_MANIFEST_MISPLACED` (found in scene/document/node extras; the backend reads only `asset.extras.HELIX_vehicle`), `HOST_MANIFEST_EMPTY`, `HOST_MANIFEST_DIVERGENT`, `HOST_MANIFEST_SOCKET_INVALID`, `HOST_MANIFEST_SOCKET_NAME_INVALID`, `HOST_MANIFEST_SOCKET_NODE_MISSING`. `helix continuum publish-package` refuses a `vehicle` Package descriptor whose model GLB has any of these errors before sealing. See [docs/vehicle-simulate.md](docs/vehicle-simulate.md#host-manifest) |
+| `--glb` host-frame bind contract | `HOST_BIND_ROOT_MISSING` (no `vehicle_root` node), `HOST_BIND_MOUNT_NODE_MISSING` (an offered `boot`/`bonnet` socket with no node to mount on), `HOST_BIND_ROOT_NOT_OWNER` (the lid node is outside `vehicle_root`): a host that offers a lid socket must carry the nodes a host-frame add-on binds to, or the runtime throws while composing the car and it is never presented. `vehicle addon check --host`, `vehicle addon check <dir>` and `vehicle preview --addon` apply the same rule to the add-ons' own `bind { socket, root }`; `vehicle preview` refuses before launching a browser and fails at once on a `[helix-vehicle] composition failed` console line or a page error |
+| `--glb` | `WHEEL_NODES_MISSING`, `WHEEL_PIVOT_NOT_AT_HUB` (origin > 2 cm from the centre of its geometry — the wheel add-on anchor lands there), `WHEEL_ORIGINS_NOT_DISTINCT`, `WHEEL_FRAME_MIRRORED_X`, `WHEEL_FRAME_FRONT_NOT_PLUS_Z`, `WHEEL_NODE_EMPTY` (warn), `LENGTH_NOT_ALONG_Z` (warn), `PANEL_NODE_MISSING`, `PANEL_ROLE_MISSING_DOOR` / `PANEL_ROLE_NO_NODE_BONNET` / `PANEL_ROLE_NO_NODE_BOOT` / `PANEL_ROLE_UNDECLARED_BONNET` / `PANEL_ROLE_UNDECLARED_BOOT` (warn: a four-wheeled car should articulate its doors, bonnet and boot / engine cover), the lamp-coverage gate on the lit geometry (`LAMP_INDICATOR_REAR_MISSING` / `LAMP_INDICATOR_FRONT_MISSING` / `LAMP_INDICATOR_SIDE_UNLIT` / `LAMP_INDICATOR_NO_ROWS` / `LAMP_NODE_UNLIT` / `LAMP_REPEATER_UNLIT` / `LAMP_FUNCTION_NO_ROW` errors, `LAMP_ROW_NO_TARGET` / `LAMP_NO_LIGHTING_ROWS` / `LAMP_INDICATOR_REAR_OPTED_OUT` warns; the documented opt-out for a car that really has no rear indicators is `lights.noRearIndicators: "<why, with source>"`), `VEHICLE_BUDGET_TRIANGLES` / `_MATERIALS` / `_TEXTURE_EDGE` / `_DRAW_CALLS` / `_FILE_SIZE` |
+
+The model frame is glTF: +X is the vehicle's left, +Y up, +Z forward, metres. Wheel nodes are found by name with
+the engine's own resolver (`wheel_lf` / `wheel_rf` / `wheel_lr` / `wheel_rr` and the usual aliases); all four must
+resolve. The engine validator is vendored by `scripts/vendor-vehicle-package-v2.mjs` (see `vendor/README.md`).
+
+## Package-first GLB publication
+
+`helix continuum publish-glb <mesh.glb> --title <name>` seals a Prop Package Version through
+`POST /api/v1/publications/upload`. `--package-type character` seals a Character Package.
+A Package-only publish creates no Item, Distribution or creator inventory copy. The receipt prints
+the exact `{ packageId, version, manifestCid }` pin and a retryable intent UUID.
+Use `--private` for source resources that should remain private; private Packages cannot open a public offer.
+
+To make a Prop or Character claimable or saleable, explicitly request the first Marketplace or World offer:
+
+```bash
+helix continuum publish-glb ./postcard.glb --title "Harbor Postcard" \
+  --offer marketplace --price-lix 0 --content-rating everyone --json
+helix continuum publish-glb ./trophy.glb --title "Season One Trophy" \
+  --offer world --world-id <world-uuid> --distribution-key season_one \
+  --price-lix 0 --collectible-supply 500 --content-rating everyone --json
+helix continuum publish-glb ./avatar.glb --title "Harbor Avatar" \
+  --package-type character --offer marketplace --price-lix 0 \
+  --content-rating everyone --json
+```
+
+The server seals the Package first, then creates the Package-backed Item and requested offer. An
+active first offer issues one creator copy; a future or visual-QA-deferred offer issues none until
+activation. The CLI checks that the response includes the sealed pin, an Item pinned to those
+exact bytes when an offer was requested, and an opened, scheduled, or explicitly deferred route. It
+never falls back to a legacy Item upload. Use `--intent-id <uuid>` to resume a request whose result
+was lost; inspect a partial receipt before retrying with a new intent.
+Use `--starts-at <ISO-date>` to schedule a future offer and `--ends-at <ISO-date>` to close it.
+
+For a sealed Package Version authored through `helix continuum publish-package`, use its exact
+receipt to create the Item projection. This is the Package-first route for specialized Package
+types when the backend supports their validated root contract:
+
+```bash
+helix continuum make-item --package-id <uuid> --package-version 1.0.0 \
+  --manifest-cid cid:sha256:<64-hex> --title "Finished Build" \
+  --content-rating everyone --json
+helix continuum make-item --package-id <uuid> --package-version 1.0.0 \
+  --manifest-cid cid:sha256:<64-hex> --title "Finished Build" \
+  --offer marketplace --price-lix 0 --content-rating everyone --json
+```
+
+Creating an Item without an active offer grants no creator copy. The same intent UUID resumes an
+interrupted call. The backend derives specialized Item metadata from the sealed Package root;
+client supplied host, fit, operation and rider metadata is never trusted.
+
+An Item created with `make-item --personal` keeps its identity when published later. First make
+its Package public and confirm the current sealed pin, then attest its rating and publish that
+existing Item. Publishing opens no acquisition route or creator copy; create a Marketplace or
+World Distribution afterward when it should become available:
+
+```bash
+helix continuum publish-owned-item <item-uuid> --package-id <uuid> \
+  --package-version 1.0.0 --manifest-cid cid:sha256:<64-hex> \
+  --content-rating everyone --accept-rating-attestation --json
+```
+
+Use `--intent-id <uuidv4>` to retry an interrupted promotion safely. The server requires the
+Package to be public, sealed, current, owned by the creator, and pinned to that Item. A private
+Package cannot be promoted through this Item command.
+
+Existing Item reads, distributions, visual QA and Package Version moves remain available. The
+former Item-first authoring commands are retired from CLI discovery.
+Vehicle, add-on, locomotion and interactive definition authors must seal the appropriate Package
+before creating an Item from its exact pin; the Prop/Character GLB route does not accept those
+specialized formats.
+
+## Distant tree bakes
+
+Create compact tree silhouettes for unloaded cells with `helix placements impostors`, then attach them to a matching
+scene using `helix placements attach-impostors`. See [the reusable baker and runtime workflow](docs/distant-trees.md).
 
 ## Develop
 
 ```bash
 npm install
-npm test       # jest
+npm test       # build current source, then Jest
 npm run build  # tsc → dist/ (bin: dist/index.js)
 npm run lint
 ```