@hypersoniclabs/helix-mcp 0.2.5 → 0.2.12

package/docs/terrain.md

@@ -0,0 +1,173 @@
+# Terrain — the ground a scene world stands on
+
+**Terrain is a level feature of a scene world.** A scene world does not place its environment in `main.ts`: it points
+at a sealed HELIX Scene document, and the platform streams that document in as the world. Terrain is the ground
+inside such a document — a grid of heightfield tiles the platform streams and textures for you (a tile is 256 cells
+square: 256 m at the default 1 m sample spacing, 1 km at 4 m), so a world can be a kilometre of walkable outdoors
+without a single hand-modelled mesh. The player walks on it, collides with it, and the runtime lights it like any
+other geometry.
+
+**You do not model it — you author it as data.** Either GENERATE a landform from one of six built-in presets (a
+seed, a preset and a size; `terrain_generate`), or IMPORT a heightmap you already have — a real-world elevation
+tile, a sculpted export — and paint it with the same presets (`terrain_import`; it authors at 0.5, 1, 2, 4 or 8 m
+per sample — `outputMetresPerSample`, default 1 — a source posting coarser than that grid is upsampled with a
+slope-continuous cubic, and the ground should be shifted so its lowest point sits near 0 m, with `heightRange` on a
+png16/r16 source or `heightOffset` on an f32 one in absolute metres, where the sky, the height fog and the precision
+of the world all expect it). Both write the same thing:
+a **terrain source folder** holding the per-tile heights, the painted surface weights, and a `terrain.json` that
+describes them. The folder also carries the always-resident coarse layer — the far picture past the streamed tiles —
+with its own surface weights and baked normal map at 2 m per texel or coarser (that is the floor; a large grid or a
+coarse sample spacing widens it). Generation is deterministic — the same preset, seed and size always produce the
+same bytes — so a re-run is free, a diff is real, and two agents scaffolding the same world get the same ground.
+
+**Reach for it only when the world genuinely wants open ground.** Terrain belongs to `kind: "scene"` worlds; an
+interior, an arena, a diorama or any bounded space is better and cheaper as ordinary geometry, and a character or
+multiplayer world you build yourself has no document to put terrain in. It is also not editable at runtime: the
+ground is authored once, published with the world, and identical for every player. If you want a small patch of
+outdoors under a building, place a mesh — terrain earns its cost at hundreds of metres and up.
+
+## The recipe
+
+**1. Scaffold it with the world.** The terrain flag belongs to the scene scaffold, so the ground and the document
+that streams it are written together and are already consistent:
+
+```
+scaffold_world({ directory, title, slug, kind: "scene", terrain: "alpine" })
+```
+
+That returns `helix init <dir> --kind scene --terrain alpine`. Running it writes the usual scene project plus a
+generated **4 x 4-tile (1 km x 1 km)** landform under `public/scene/mall/terrain/`, paints it from the preset, lifts
+the starter mall onto the flat plateau at the spawn, and declares the terrain in the sealed document. The scaffolded
+`public/.helixignore` already covers `terrain/` — those bytes are a dev override, not bundle payload.
+
+Adding ground to a scene world you already have is the same generator without the scaffold:
+
+```
+terrain_generate({ out: "<world>/public/scene/<folder>/terrain", preset: "meadow", tiles: "8x8", seed: 12 })
+```
+
+then declare it in the document (a `terrain` element in the `scene-elements` source names the folder).
+
+**2. Inspect before anything else.** `terrain_inspect({ dir })` reports what the folder would actually ship: extent,
+tile count, delivered bytes split into heights and surface weights, the height range, and every warning — an
+over-cap tile, an unbaked folder, a grid past the cap, and which surface roles the paint had to FOLD together on
+which tiles. The bytes count the coarse layer beside the tiles, its surface weights and baked normal map included —
+those two are painted at 2 m per texel or coarser, the far picture past the streamed tiles. None of that is visible
+in a screenshot and none of it is reported at publish time.
+
+**3. Adjust, then re-inspect.** Three dials, cheapest first: a different `seed` for another world of the same
+character; a different `preset` for another character entirely; a different size (`tiles` or `sizeKm`) for another
+scale. To change only the SURFACES — which materials go where, how big they tile, how sharply they blend — copy a
+preset to a JSON file, edit it, and re-paint the existing landform in place, leaving the heights untouched:
+
+```
+helix terrain bake <dir> --preset ./my-preset.json
+```
+
+**4. Validate.** `npm run build`, then `validate_world` on `dist/` and `helix verify-subpath dist`, as for any world.
+A terrain world must stay on dynamic lighting (below), and this is the step that says so out loud: `validate_world`
+(and `helix validate <dist>`) reports a VALID bundle and then warns when that bundle is a terrain world whose lighting
+contract declares `"baked"` — read past the ✔.
+
+**5. Publish.** Terrain rides with the DOCUMENT, never in the world bundle — that is what `.helixignore` is for. So
+the scene document (terrain included) publishes first and the world second, exactly as for any scene world.
+
+## The presets
+
+A preset is two things at once: the **landform** it generates, and the **surfaces** it paints onto it. Surfaces are
+assigned by ROLE, computed from the shape of the ground itself — `base` is the ordinary flat ground, `slope` the
+steep faces, `peak` the high ground, `low` the bottoms and basins, `cavity` the concave creases where water and
+debris would collect, and `accent` a scattered second surface that breaks up uniformity.
+
+| Preset | The landform | base | slope | peak | low | cavity | accent |
+|---|---|---|---|---|---|---|---|
+| `meadow` | gentle rolling grassland, a soft rise and a hollow (up to ~80 m) | grass | rock | — | mud | dry dirt | leafy grass |
+| `alpine` | three massifs and a valley between them; the tallest terrain (up to ~900 m) | grass | granite | snow | gravel | dry dirt | — |
+| `desert` | wind-aligned dunes with two mesas standing out of them (up to ~140 m) | sand | sandstone | limestone | dry dirt | gravel | pebble |
+| `coast` | a shoreline along one edge climbing inland, with a headland (−14 to ~90 m) | grass | rock | — | sand | mud | leafy grass |
+| `forest` | two wooded ridges around a sheltered glen (up to ~160 m) | leafy grass | rock | — | mud | dry dirt | gravel |
+| `volcanic` | a crater cone with spatter mounds around it (up to ~600 m) | basalt | rock | gravel | slate stone | dry dirt | pebble |
+
+Two things follow from the table. A preset may declare **six** roles but each tile ships **four**, so on tiles where
+a role carries almost no weight the paint folds it into a kept role — normal, and reported by `terrain_inspect` so
+you can tell "folded a role that was never visible there" from "lost the snow line". And `coast` is the one preset
+with ground below zero: it floods to sea level by default, and `seaLevel` on the other presets floods them the same
+way.
+
+## Lighting
+
+**A terrain world is a dynamic-GI world, always.** Its `public/helix.visuals.json` stays on `mode: "dynamic"` with
+sky fallback on and no pinned probe box: the lighting runtime scrolls its probe volume with the camera, which is the
+only thing that covers a kilometre of ground. **There is no baked mode for terrain** — do not call
+`bake_world_lighting` on one, and do not hand-edit the contract to `"baked"` — `validate_world` warns when a terrain
+world declares it. One consequence is worth knowing before you frame a shot: the sun shadow is a camera-following box
+about 200 m across, so near ground casts and receives real sun shadows and distant ridges do not.
+
+## The caps
+
+| | |
+|---|---|
+| tile | 257 samples square (256 cells): 256 m at 1 m per sample, 1 km at 4 m |
+| sample spacing | 0.5, 1, 2, 4 or 8 m — `terrain_generate` always writes 1 m, `terrain_import` picks it (`outputMetresPerSample`) |
+| default size | 4 x 4 tiles = 1 km x 1 km at 1 m per sample (~2.4 MiB) |
+| maximum size | 16 x 16 tiles = 4 km x 4 km at 1 m per sample (~39 MiB, ~25 s to generate) |
+| surfaces | 6 roles per preset, 4 per tile |
+| sizing | pass `tiles` (`"8x8"`) or `sizeKm`, never both — `sizeKm` rounds to whole tiles |
+
+Bigger is not better: bytes are delivered to the player, and 4 km of empty ground plays worse than 1 km of ground
+with something on it. Start at the scaffold default and grow it only when the world runs out of room.
+
+## The two mistakes to avoid
+
+1. **Baking the lighting.** Terrain worlds are the case the baked path was never built for — the bake volume cannot
+   cover open ground, and a world that ships `"baked"` terrain lights wrongly rather than loudly. Leave the mode
+   dynamic. (See above; this is also why `bake_world_lighting` is not part of the recipe here, though it remains the
+   right call for a bounded interior in a world that has one.) A baked terrain world is still a VALID bundle, so
+   `validate_world` prints its `⚠` AFTER the ✔ line — a pass is not a clean bill of health here.
+2. **Publishing before running `terrain_inspect`.** Folded roles, an unbaked folder that would ship untextured, and
+   an over-cap grid are all silent everywhere else — the world builds, validates and renders. Inspect the folder
+   every time you generate, import or re-paint it, and read the warnings before you publish.
+
+## Commands and tools
+
+| Do this | MCP | CLI ({{CLI_PKG}}) |
+|---|---|---|
+| scaffold a scene world with ground | `scaffold_world({ kind: "scene", terrain })` | `helix init <dir> --kind scene --terrain <preset>` |
+| generate a landform | `terrain_generate` | `helix terrain generate --out <dir> --preset <id>` |
+| import a heightmap | `terrain_import` | `helix terrain import <file> --out <dir> --preset <id>` |
+| re-paint an existing landform | — | `helix terrain bake <dir> --preset <id-or-path>` |
+| report what would ship | `terrain_inspect` | `helix terrain inspect <dir> [--json]` |
+
+## Trees, grass and rocks
+
+Use placements_bake with a helix.placements-source/1 JSON file and a prepared helix.placements-assets/1 catalog.
+The catalog must pin renderable GLB LODs, external KTX2 textures, small/full texture families, root-normalized wind gradients,
+explicit simple colliders and optional static GI proxies. Use content whose rights permit your intended distribution.
+The evaluation assets in the maintainer capstone are not a public catalog dependency.
+
+A minimal source (paths relative to this JSON file):
+
+```json
+{
+  "schema": "helix.placements-source/1",
+  "terrain": "terrain",
+  "catalog": "prepared/catalog.json",
+  "layers": [
+    { "id": "trees", "prototype": "douglas-fir", "seed": 42, "spacing": 16, "minSpacing": 12 },
+    { "id": "grass", "prototype": "meadow-grass", "seed": 9, "spacing": 2, "minSpacing": 1,
+      "exclude": [[[-12, -12], [12, -12], [12, 12], [-12, 12]]] }
+  ]
+}
+```
+
+Run placements_inspect on the output. In Scene Elements, add placements: { source: "placements" } beside terrain;
+buildings may be an empty array. Set runtimePolicy.memoryBudgetMiB deliberately for textured terrain plus vegetation
+(the old default is 64 MiB), then inspect the actual runtime reservations and budget rejections.
+Continuum scratch descriptions use a root { id: "vegetation", type: "placements", source: "<baked-folder>" }.
+Publication keeps the exact binary closure. Objects above 1 MiB use verified staged binary ingestion, capped at 32 MiB per object.
+
+This requires an installed scene runtime with helix.scene-placements/1 and its module-worker sidecar.
+The optional scene/visual attachment adds weather wind; static scene rendering works without the visual peer.
+Trees/rocks keep stable placement and collision across tiers. Grass uses nested density subsets and may disappear on minimal.
+The separate native Home renderer does not support this capability and must reject such a scene explicitly.
+Do not advertise native Home support, a released package version, or mobile performance based on the local engine capstone.

package/docs/upgrades.md

@@ -0,0 +1,324 @@
+# HELIX Instant — World Upgrades
+
+This is the migration ledger for **existing worlds**: change-specific steps for bringing an older world up to
+current platform capabilities. You normally arrive here because `check_for_updates({ projectDir })` reported a
+finding — its result already inlines the steps for exactly the entries that apply to your world, so read this full
+document only when you want the surrounding context.
+
+**The policy, always:** upgrades are the user's call. Report findings, suggest the fix, and stop — never edit pins,
+run installs, or migrate world code until the user says yes. In-range staleness (`locked 0.2.9 → catalog 0.2.11
+within the pin`) is the one low-ceremony case: a single re-run of `install_world_packages` plus a rebuild, still
+suggested first.
+
+**How to read entries:** each entry is **cumulative** — it takes a world from *any* older state to current in one
+pass. Never chain multiple entries for the same system; the newest applicable entry is the whole path.
+
+---
+
+## Engine-core split — humanoid-character 0.2.11 / engine-core 0.1.0
+
+**Applies if:** the world's `helix.json` has no `engine-core` entry in `systems` (typical for worlds published
+before engine-core existed), or `helix.lock.json` resolves `humanoid-character` below `0.2.11`.
+
+**What changed:** the screenshot helper and the in-world photo camera moved out of `@helix/humanoid-character` into
+their own system, `@helix/engine-core`. A world without it cannot declare screenshot shots, cannot be captured by
+`capture_world_screenshot` (blind mode excepted), and cannot offer the photo camera.
+
+**Steps (safe from any older state):**
+
+1. In `helix.json`, make the systems block include both pins (keep anything else already there):
+   ```json
+   "systems": { "humanoid-character": "^0.2.11", "engine-core": "^0.1.0" }
+   ```
+2. Run `install_world_packages` (terminal: `helix install`) — it resolves both pins and lays the code into
+   `public/helix_modules/`.
+3. If `vite.config.ts` predates engine-core, add these aliases — subpath entries **must precede** any root entry
+   (the aliaser substitutes prefixes in order; a root-only alias mangles subpath imports into broken paths):
+   ```ts
+   '@helix/engine-core/screenshot': fileURLToPath(new URL('./public/helix_modules/engine-core/screenshot/index.js', import.meta.url)),
+   '@helix/engine-core/world-camera': fileURLToPath(new URL('./public/helix_modules/engine-core/world-camera/index.js', import.meta.url)),
+   '@helix/engine-core': fileURLToPath(new URL('./public/helix_modules/engine-core/index.js', import.meta.url)),
+   ```
+   If the project typechecks, mirror them in tsconfig `paths` — the exact block is in `read_doc({ name: "screenshots" })`.
+4. To enable capture, add the declared shot + ready call to world code — the three lines in
+   `read_doc({ name: "screenshots" })` section 1.
+5. Rebuild (`npm run build`), check the bundle with `validate_world`, capture with `capture_world_screenshot`, and
+   republish the world when the user is ready.
+
+**Nothing else changes:** existing `@helix/humanoid-character` imports keep working — 0.2.11 removed only the two
+moved subpaths, which no published world ever successfully imported.
+
+---
+
+## Hosted Rapier runtime — humanoid-character 0.2.35
+
+**Applies if:** the world's `package.json` lists `@dimforge/rapier3d-compat` under `dependencies` (the pre-0.2.35
+scaffold shape), or its vite config lacks `'@dimforge/rapier3d-compat'` in `build.rollupOptions.external`.
+
+**What changed:** the platform now hosts Rapier the way it hosts three. `helix install` against
+humanoid-character 0.2.35+ writes an import-map entry for the bare specifier `@dimforge/rapier3d-compat` pointing at
+`runtime/rapier/<ver>/rapier.es.js` on the platform CDN, and that module streams its WASM from a sibling URL. A world
+that externalizes rapier drops ~2 MB from its bundle and lets warm reloads skip the WASM compile. A world that keeps
+bundling rapier continues to work — it just ships the duplicate copy and recompiles it on every load.
+
+**Steps (safe from any older state; do them together — externalizing without the new import map leaves the bare
+import unresolvable in a served bundle):**
+
+1. In `helix.json`, raise the pin: `"humanoid-character": "^0.2.35"` (keep everything else).
+2. Run `install_world_packages` (terminal: `helix install`) — the lock re-resolves and the `index.html` import map
+   gains the `@dimforge/rapier3d-compat` entry. The pin raise is what forces re-resolution; a bare re-install of an
+   unchanged pin replays the old lock and adds nothing.
+3. In `package.json`, move `@dimforge/rapier3d-compat` from `dependencies` to `devDependencies` — types and
+   `helix dev` still resolve the npm copy (Vite dev ignores build externals, so local dev is unchanged).
+4. In the vite config, add `'@dimforge/rapier3d-compat'` to `build.rollupOptions.external`, beside `'three'`.
+5. Rebuild (`npm run build`) — the ~2 MB rapier chunk disappears from `dist/`. Then `validate_world` and republish
+   when the user is ready. In a played world the network panel shows `runtime/rapier/<ver>/rapier.es.js` plus
+   `rapier_wasm3d_bg.wasm`, one fetch each.
+
+**Nothing else changes:** world code and imports (`RapierBody`, physics config, ragdoll) are untouched — hosting only
+changes where the module's bytes come from. Worlds without a rapier dependency (no physics) have nothing to do.
+
+---
+
+## Weapon definition pins — the arsenal moves without you
+
+**Applies if:** `check_for_updates` reported a weapon definition pinned below its current published version, or
+its two config copies disagreeing. Any gun world qualifies eventually: `multiplayer.weaponItems` pins are
+IMMUTABLE `assetId@version` references. Publishing a newer definition version never moves a consuming world.
+
+**What changed (the waves so far):** `@2` embedded each weapon's ejected shell casing in the prop; `@3` added
+`damage.headMultiplier` (2.0 on every hitscan category in the official arsenal). A world using the
+`weaponDamage` `part` slot gets NO headshot bonus until it pins `@3` or newer — the multiplier lives in the
+definition, absent = ×1, silently.
+
+**Steps:**
+
+1. `item-def inspect <assetId>` per pinned definition — the resolve answers the current version and the
+   numbers behind it (`check_for_updates` already names which pins are behind).
+2. Edit the version in BOTH config copies — the `multiplayer` block in `helix.json` AND
+   `public/multiplayer.json`. They must stay identical: the room fetches one, the publish validator reads the
+   other, and a pin present in only one publishes clean then resolves to nothing at runtime.
+3. Grep both configs for the OLD pin string: any `itemDamage` op naming it must move too — a pin named by
+   `itemDamage` but absent from `weaponItems` fails publish validation.
+4. Rebuild (`npm run build`), `validate_world`, republish when the user is ready.
+
+**Nothing else changes:** the engine consumes whatever the definition serves — no code edit, no re-install,
+no system pin movement.
+
+---
+
+## Installed Vault assets & interactables — the catalog moves without you
+
+**Applies if:** `check_for_updates` reported an installed Vault asset behind its current Vault version
+(`public/helix.assets.json`), or an installed interactable whose Marketplace reference moved
+(`helix_interactables/installed.json`).
+
+**The policy first — item updates are OPTIONAL and consented separately from system updates.** A user who asked
+to "update the world" or "update systems" has NOT asked to update items: the installed bytes are already in the
+bundle and keep working exactly as published, so nothing is broken by staying put. Ask the user specifically,
+per item, before re-installing or re-adding anything — and skip the ask entirely unless they showed interest.
+
+**What "behind" means here:** Vault artifact versions are immutable, so installing wrote an exact version into
+the world and the Vault re-versioning since then moved nothing locally. A stale row is an offer, not a defect.
+`unresolved` usually means the receipt was written against another backend (dev-stack ids checked on live) — the
+bundled copy still works; only re-installs need the original backend.
+
+**Steps (only for items the user said yes to):**
+
+- **Vault asset:** `install_asset({ assetId })` (terminal: `helix assets install <assetId>`) — re-downloads the
+  current version, verifies checksums, rewrites the receipt entry. Then rebuild and republish when the user is ready.
+- **Interactable:** `helix update-interactable <slug-or-item-id>` (terminal) updates every installed instance in
+  place: it subtracts the old bundle's composed rules and declarations, re-composes the new version under the SAME
+  namespace and placement (world-authored references to `itx…_` names keep working), moves `installed.json` and the
+  generated glue, and swaps the vendored `helix_interactables/` directory. If a composed rule was hand-edited since
+  install, the update aborts and names it rather than guessing — restore the rule (or remove the instance by hand)
+  and retry. Never adopt by re-running `helix add-interactable` on its own: that installs a SECOND instance whose
+  rules run alongside the old ones.
+- **checksum-drift** (an interactable's Marketplace version unchanged but its bundle bytes differ): treat as
+  suspect — surface it to the user and do not re-add until the registry story is understood.
+
+---
+
+## Platform runtime externalization — publish now rejects bundled system delivery
+
+**Applies if:** validate or publish fails with any of `platform systems are declared but helix.runtime.json is
+missing`, `helix.runtime.json is legacy-bundled`, `is not a safe platform runtime range`, `is missing from the built
+HTML import map`, or the publish server's `the built JavaScript never imports @helix/…` /
+`the platform runtime resolver cannot currently serve @helix/<slug>@<range>`. Enforced today on the **helix3 lane
+only** (CLI 0.1.13-helix3.126+, manifest 0.3.19-helix3.52+, and the helix3 backend); the production and staging
+scopes do not enforce it yet. Unlike item updates this is **not optional** on an enforcing lane — publish stays
+blocked until the world migrates — but the suggest-first policy still holds: report the findings and the steps, and
+apply them only when the user agrees.
+
+**What changed:** platform systems (`@helix/humanoid-character`, `@helix/engine-core`, and every declared system)
+must be delivered through the platform import map, never bundled into the world's JavaScript. Three declarations are
+cross-checked and must agree: the `systems` block in `helix.json`, `public/helix.runtime.json` (generated by
+`helix install`), and the import map in the built entry HTML. The publish server additionally verifies that the built
+JavaScript still contains bare `@helix/…` imports (an import map nothing imports is inert) and that every pinned
+range actually resolves on the runtime resolver — so a world can pass local validation and still be rejected at
+publish. The server is authoritative.
+
+**Steps:**
+
+1. `helix.json` — every `systems` value must be a `^`/`~` range (never an exact version: `validate_world`/`publish_world`
+   refuse it — to ship an unpromoted engine fix, promote it, do not pin), AND must resolve to a published
+   version. The current scaffold pins `"humanoid-character": "^0.3", "engine-core": "^0.1.2"`; `^0.1` or `^0.4` for
+   humanoid-character resolve to nothing and fail at the server.
+2. `vite.config.ts` — the build must externalize the platform packages; the generated form is this line:
+   ```ts
+   rollupOptions: { external: (id) => id === 'three' || id === '@dimforge/rapier3d-compat' || id.startsWith('@helix/') },
+   ```
+   Current CLIs recognize ANY formatting that keeps the `.startsWith('@helix/')` external predicate (single- or
+   double-quoted), so reformatting the object — wrapping it, adding an `output` key — is safe. CLIs at
+   0.1.13-helix3.135 and below matched this line as a LITERAL SUBSTRING: on those, any reformatting makes the next
+   `helix install` classify the world `legacy-bundled` and the next publish fails — keep it byte-identical there.
+3. `index.html` — the marker block must exist verbatim:
+   ```html
+   <!-- helix:three:start -->
+   <script type="importmap">
+   { "imports": { "three": "" } }
+   </script>
+   <!-- helix:three:end -->
+   ```
+   `helix install` rewrites everything between the markers, including the `@helix/*` entries. Never hand-write an
+   `@helix/*` import-map entry — a stray one is its own validation error.
+4. `package.json` — `three`, `@types/three` and `@dimforge/rapier3d-compat` belong under `devDependencies`; the
+   bundle must not carry them.
+5. Run `install_world_packages` with `update: true` (terminal: `helix install --update`) and READ the printed
+   `platform runtime delivery -> compatible` line. If it prints `legacy-bundled`, step 2 did not take — fix the vite
+   line first.
+6. `npm run build`, then confirm `dist/helix.runtime.json` exists and the dist JS still contains bare `@helix/…`
+   import specifiers.
+7. `validate_world` (terminal: `helix validate`), then republish when the user is ready.
+
+**What install automates:** it always (re)writes `public/helix.runtime.json` and the import map between the markers.
+It rewrites `vite.config.ts` ONLY when that file still contains the byte-exact legacy generated line
+`rollupOptions: { external: ['three', '@dimforge/rapier3d-compat'] },`. It never edits `package.json`, the ranges in
+`helix.json`, or an `index.html` that is missing the markers.
+
+---
+
+## three r185 + humanoid-character 0.3 — the platform runtime moved to three 0.185.1
+
+**Applies if:** `src/helix.runtime.ts` says a `THREE_VERSION` below `0.185.1` (a world installed before this wave
+says `0.172.0`), or `helix.json` pins `humanoid-character` on the `^0.2` line — `check_for_updates` reports either.
+
+**What changed:** the platform runtime moved to **three 0.185.1 (r185)**, hosted per world through the import map
+exactly as before, and `humanoid-character` **0.3.0** is the line built against it. `helix install` bakes whatever
+three the resolved system declares, so the system pin is what chooses the version: `^0.2` keeps giving you three
+0.172, `^0.3` gives 0.185.1. **A world behind that line still publishes** — `helix validate` / `helix publish`
+only warn, naming these steps — so this entry, like the others, is an upgrade to suggest rather than a blocker.
+Nothing that is already published moves: bundles and the hosted runtime URLs are immutable, so live worlds keep
+running on the three they baked, forever. New scaffolds start on the 0.3 line and three 0.185.1 already.
+
+**Steps (safe from any older state):**
+
+1. In `helix.json`, raise the pin: `"humanoid-character": "^0.3"` (keep everything else). This supersedes the lower
+   `^0.2.x` pins named by the older entries above — those are the versions where each change landed, not a ceiling,
+   and 0.3 carries all of them.
+2. Check the abilities pinned beside it with `get_package_manifest({ slug })`: an ability declares the system range
+   it was built against and refuses to load at runtime outside it, so a world moving to the 0.3 system line needs
+   ability versions that declare it.
+3. Run `install_world_packages` with `update: true` (terminal: `helix install --update`) — it re-resolves the pin,
+   rewrites `helix.lock.json`, the `index.html` import map, `public/helix.runtime.json` and `src/helix.runtime.ts`
+   (`THREE_VERSION` becomes `0.185.1` and `TRANSCODER_PATH` moves to `runtime/basis/three-0.185.1/`). The pin raise
+   is what forces re-resolution; a bare re-install of an unchanged pin replays the old lock.
+4. In `package.json`, move the `three` and `@types/three` devDependencies to `^0.185.1`. Do not skip this: the three
+   CORE loads from the import map, but Vite bundles the `three/examples/jsm/...` addons out of your local copy and
+   `helix dev` runs that copy too — a stale devDep ships r172 addons against an r185 core and makes local dev
+   disagree with the published build.
+5. Delete any hardcoded `runtime/three/<ver>` or `runtime/basis/three-<ver>` URL in world code and read
+   `src/helix.runtime.ts` instead (`THREE_VERSION`, `THREE_MODULE_URL`, `TRANSCODER_PATH`) — those are rewritten by
+   install, a hand-written copy is not.
+6. `npm run build`, then `validate_world`, then republish when the user is ready. Confirm `dist/helix.runtime.json`
+   and the built import map name `0.185.1`.
+
+**Expect a slight look shift, and accept it.** three's physically-based materials changed between r172 and r185
+(energy conservation on rough/metallic surfaces landed in r181): the same scene reads a little brighter, mostly on
+rough materials. It is the new correct result, not a regression — re-check exposure and tone mapping after the
+rebuild rather than chasing individual materials back to their old values. Tell the user to expect it before you
+republish a world they know well.
+
+**Nothing else changes:** world code and imports are untouched — the character, ability, physics and SDK APIs are
+the same. Worlds that pin no system have no hosted three to move and are outside the gate.
+
+---
+
+## The visual runtime — platform-owned lighting, and the publish-time bake
+
+**Applies if:** the world's `src/` never calls `createVisualRuntime` and its `helix.json` has no `visual` entry in
+`systems` — true of every world scaffolded before the visual system published, since the scaffold wrote a hand-built
+`WebGLRenderer` plus a `HemisphereLight`/`DirectionalLight` pair.
+
+**What changed:** lighting is platform-owned by default. The `visual` system's `createVisualRuntime` owns the
+renderer, sky, sun, shadow rig, tone mapping (AgX + a calibrated colour grade), AO, fog, auto-exposure, probe GI and
+the time-of-day clock; the world declares HOW it is lit in `public/helix.visuals.json`. Bounded, static-geometry
+worlds then ship **baked** lighting: `bake_world_lighting` computes the light field once at publish and it imports
+in milliseconds at boot instead of converging live.
+
+**The policy — this upgrade is OPTIONAL, twice over.** Nothing is broken by staying put: a hand-lit world keeps
+rendering exactly as published. And a world with its own deliberate visual identity — a custom renderer or post
+chain, a stylized look — is a legitimate **opt-out** and should NOT migrate. Suggest it for worlds that want the
+platform look (and the baked boot) — expect a look shift when the calibrated pipeline replaces the two hand lights,
+and tell the user to expect it before republishing a world they know well.
+
+**Steps (the full conversion is `read_doc({ name: "lighting-world" })` — this is the shape):**
+
+1. In `helix.json`, add the pin: `"visual": "^0.1"` (keep everything else); run `install_world_packages` with `update: true`.
+2. Author `public/helix.visuals.json` (`version: 1`, `mode: "dynamic"`, your `timeOfDay`/`grade`) — the FILE,
+   fetched at boot, never an inlined const (the bake patches the file).
+3. In `src/main.ts`, delete the renderer-construction block AND both hand-placed lights; construct the runtime from
+   a canvas, hand `visuals.renderer` to whatever used the old renderer (the character facade takes it), replace
+   `renderer.render(...)` with `visuals.tick(dt)`, and wire `visuals.setSize` + `visuals.catchUp()`.
+4. `npm run build`, then — bounded static world — `bake_world_lighting`, then `validate_world`, and republish when
+   the user is ready. Re-bake whenever geometry or lights change; there is no staleness detector. **A bounded
+   INTERIOR authors `probes: { center, size }` in `helix.visuals.json` before baking**: the default bake volume is
+   sized for open ground, and an unfitted one lands most of its probe layers outside the room.
+
+**Nothing else changes:** character, ability, physics and SDK APIs are untouched — only who owns the renderer moves.
+
+---
+
+## World look — the material library, texture gates, and the asset-truth pass
+
+**Applies if:** `validate_world` reports texture warnings (mip-less KTX2, or a glTF sampler with a non-mipmap
+`minFilter`); or world code hand-wires pack textures — sets `texture.repeat` arithmetic itself, passes scalar
+`roughness`/`metalness` overrides that drop the maps, binds an albedo without its ORM triple; or the world imports
+third-party GLBs and shows the classic defect signatures (dark oddly-tinted surfaces where GI seems to do nothing,
+shimmer no quality setting fixes, wrong-scale props against the avatar). `check_for_updates` does not detect this
+entry yet — the signals above are yours to spot, mostly from `validate_world` output and captures.
+
+**What changed:** the craft this entry applies is `read_doc({ name: "world-look" })`. Concretely: the visual
+system now ships a material library (`loadMaterialLibrary` → `apply(mesh, id)`) that derives per-axis repeat from
+each material's calibrated physical size and binds the full ORM — replacing exactly the hand wiring that older
+worlds got subtly wrong; the platform pack's tile sizes were re-calibrated, so hand-derived repeat values from the
+old catalog data render mis-sized; and mip-less KTX2 is now rejected at Vault upload while **world bundles only
+warn** — plus Vault assets published before the gate are grandfathered, so an older world can legally keep
+shimmering until its assets are re-published through the pipeline.
+
+**The policy — OPTIONAL, look-only.** Nothing functional breaks by staying put, and every step changes how the
+world reads: capture before/after and let the user judge. A stylized world whose look is deliberate is not a
+defect — this entry is for worlds that want to read better, not a compliance pass.
+
+**Steps (each independent — apply what the world needs):**
+
+1. **Texture hygiene:** run `validate_world` and read the texture warnings. Hand-encoded or mip-less KTX2 in the
+   bundle: replace it by feeding the pipeline source images (PNG/JPG/WebP) instead of shipping your own encode. A
+   non-mipmap `minFilter` in a glTF sampler: remove it (it silently disables mips AND anisotropy). A shimmering
+   Vault asset that predates the mip gate: the immutable asset is grandfathered. Do not attempt a direct
+   Vault byte upload/version move; when the supported Package import path is available, re-author and publish
+   a corrected Package, then install its pinned content.
+2. **Material consumption:** if the world hand-wires pack textures, either adopt the library (`loadMaterialLibrary`
+   → `apply` — it needs the `visual` system, so this pairs naturally with the visual-runtime entry above) or fix
+   the hand wiring by the world-look rules: per-axis repeat from world size, scalars as multipliers with maps kept
+   bound, the whole ORM triple.
+3. **Asset truth:** run the world-look import checklist over the world's third-party GLBs — `metallicFactor`
+   present, roughness varying, normal maps with a real blue channel, alpha modes per material, scale proven against
+   a known-size object, stray GLB lights stripped.
+4. Rebuild, `validate_world`, capture before/after with `capture_world_screenshot`, and republish when the user is
+   ready.
+
+---
+
+*Retired entries (whose "applies if" can no longer match any supported world) move out of this document so it stays
+small; this ledger holds only live migrations.*