@hypersoniclabs/helix-mcp 0.2.5 → 0.2.12

package/docs/world-inspect.md

@@ -0,0 +1,156 @@
+# HELIX Instant — World Inspection (layout as data)
+
+Screenshots answer "does this read as a plaza"; they measurably cannot answer "is the bench 0.4 m in the
+air" — distances and depth read off an image are unreliable on exactly the axis placement lives on.
+`inspect_world` gives you the world's geometry as data instead: one headless boot returns a serialized
+snapshot of the scene — world positions, extents, oriented boxes, visibility, physics colliders — and every
+placement question is answered from that snapshot with numbers.
+
+**The loop: measure with `inspect_world` until the numbers are right, then `capture_world_screenshot` once
+before handing to a human.** Do not answer placement questions by looking harder at a render.
+
+## 1. The one-line integration
+
+One import and one call, a cheap no-op during normal play — it only activates when the page is loaded with
+`?helixInspect=1`, which `inspect_world` (and the `helix world inspect` CLI command) do for you:
+
+```ts
+import { world } from '@helix/engine-core/inspect';
+// ...at the END of your world's async boot, after the scene is fully built:
+world.ready({ scene, body, spawn: SPAWN });
+```
+
+`scaffold_world` already wires this in `src/main.ts`. `scene` is required; `body` (your `RapierBody`) enables
+the collider report — without it the snapshot still covers the render side and says so honestly
+(`sources.colliders: "absent"`); `spawn` is optional context. Timing is forgiving: the snapshot walks the
+live scene when taken, so registering early still captures everything built afterwards.
+
+Needs `engine-core >= 0.1.2` (and `humanoid-character >= 0.2.13` for the collider report).
+
+## 2. What a report contains
+
+- **anomalies** (the default section) — placement findings, each with the measured numbers, the method that
+  produced it, and a confidence: floating / sunk geometry (vs the character's 0.35 m step height),
+  intersecting geometry (true oriented-box overlap, not loose bounding boxes), collider-vs-visual divergence
+  — including the classic half-extent/full-size slip, where a collider is exactly 2× its visual because full
+  sizes were passed where half-extents belong — orphan colliders (invisible walls) and un-collided visuals,
+  mirrored or degenerate transforms, and stray far-away coordinates (a `1e6` typo).
+- **roster** — the grouped object inventory: 60 identical trees collapse to one row with a count, size,
+  triangle count, and spread. Ask for it when you need to know what is actually in the scene and where.
+- **colliders** — the physics roster: every collider with shape, extents, and position. The only way to SEE
+  collision geometry — colliders never render, so a screenshot cannot debug an invisible wall.
+- **zones** — the declared `multiplayer.json` trigger volumes, each with its extents, the geometry it touches,
+  and its **rest surfaces** (surfaces a standing player could occupy while inside it). Zones are doubly
+  invisible — they never render AND they are usually off-camera — so this is the only check that catches a
+  kill band the pit floor misses, a checkpoint volume floating in empty space, or a zone centered on a stray
+  coordinate. Zone findings (`zone-empty`, `zone-fly-through`, `zone-out-of-bounds`, spawn-inside-zone) join
+  the anomalies section automatically whenever the bundle carries a `multiplayer.json`. The same
+  intent rule applies: a tall abyss band under a floorless arena is a design pattern, not a bug — the report
+  says which reading applies.
+
+Request sections via `report: ["anomalies", "roster", "colliders"]`; `json: true` returns the raw
+`{ snapshot, analysis }` for programmatic follow-up on exact numbers.
+
+## 3. Findings are measurements, not verdicts
+
+Every finding is a true statement about geometry — whether it is a PROBLEM depends on what you meant.
+Perfectly good worlds keep warnings on purpose:
+
+- a collectible gem hovering 1.2 m above the ground → an intended float, not a floating bug;
+- a tilted ramp whose base dips below the ground plane → an intended embed, not sunk;
+- arena walls overlapping at their ends → corner joints, standard construction (uniform-depth overlaps are
+  collapsed into one summary line for exactly this reason).
+
+**The rule: a warn that matches what you meant needs no fix; a warn that surprises you is the bug.** Never
+edit geometry just to silence a finding — that trades real design for a quiet report. What the checks are
+FOR is the surprise: the bench you believed was grounded but floats, the platform whose collider is twice
+its size, the wall segment left at the origin.
+
+Two mechanisms keep a dense hand-built world readable instead of drowning the one real defect:
+
+- **Run collapse (automatic).** Three or more same-parent siblings with the same finding against the same
+  support and uniform gaps fold into one line — `33 children of Group#12 floating 1.75–1.96 m above
+  Mesh#38 … adjudicate as one`. A member that breaks the run's gap band keeps its own line, because in a
+  hanging run the bulb 2 m below its siblings IS the finding. Composite-model internals collapse per model
+  the same way.
+- **The baseline (your adjudication, made durable).** After checking the findings against intent, pass
+  `writeBaseline: true` once — every finding is accepted into `inspect.baseline.json` beside the project.
+  From then on inspect reports only what CHANGED: new findings, plus accepted entries that no longer occur
+  (prune those with a fresh `writeBaseline`). Entries key on rule + world-space anchor — never on paths —
+  so they survive rebuilds. Suggest the write to the user before doing it: accepting findings is a
+  judgement, not a reflex. `showAccepted: true` renders the hidden ones when you need the full picture.
+
+Object paths in reports are **canonicalized** — auto-named `Type#N` segments are renumbered in content
+order (by each subtree's centroid), not scene-traversal order, so the same object keeps the same path
+across runs even when async loads shift traversal. Coordinates remain the strongest cross-run handle.
+
+## 4. What this cannot tell you
+
+Whether the scene READS as intended: materials, lighting mood, color, animation, art direction, atmosphere.
+That is the closing `capture_world_screenshot` check. The snapshot also reads bounding boxes, not exact
+surfaces — non-box shapes are over-approximated, and each finding's stated method and confidence say so.
+
+## 5. Checking ONE object — the focus lens
+
+After placing or moving a single object, you do not need the whole report — focus the lens on the spot you
+just wrote into the code:
+
+```
+inspect_world({ directory, focusNear: [10, 0.5, 3] })
+```
+
+You get back exactly what is at that coordinate: each matching object's geometry/color, exact position, size,
+world AABB, its FACING — yaw plus the world direction its +Z forward points, and horizontal
+`TOWARD / AWAY from / side-on to` relations against the nearest objects (floors are skipped — you stand on
+them, you do not face them). A chair rotated 180° from its table reads `faces: AWAY from table (0.8 m)` —
+orientation defects are invisible in a position/AABB listing and easy to miss in a screenshot. Also reported:
+whether any collider touches it ("walk-through unless intended" when none does), and only the
+findings that involve it — with the world's total finding count stated so nothing is silently hidden. If
+nothing matches, the three nearest objects are listed with distances, which answers both failure modes at once
+(the object landed somewhere else vs it never made it into the scene). Analysis always runs whole-world —
+correctness is relational — the lens only scopes the report.
+
+No naming is required: you know the coordinates because you wrote them. Unnamed meshes report as `Mesh#N`;
+imported GLB assets keep their authoring-tool node names for free. Optionally set `mesh.name = 'bench'` on a
+few landmark objects if you want findings and `focus: "bench"` to read by name — but do not name everything;
+it is authoring noise the tools do not need.
+
+## 6. Sizing geometry BEFORE you place it — `world_metrics`
+
+`world_metrics({ projectDir })` returns the traversal/movement reference from the world's own installed
+character system: capsule height/radius, the 0.35 m step height (taller blocks; shorter auto-steps), the 50°
+walkable slope limit, movement speeds, and the derived jump envelope — air time and the maximum flat-ground
+gap at run and sprint speed — plus corridor and ceiling clearances. Read it instead of guessing whether a gap
+is jumpable or a doorway fits; values are the system defaults a world starts from (worlds may override via
+config). The CLI pair is `helix world metrics -C <projectDir>`.
+
+## 7. Comparing before and after an edit
+
+`inspect_world({ json: true })` returns the raw snapshot; the CLI pair `helix world inspect <dist> --out
+a.json` … `helix world diff a.json b.json` reports what moved (per-axis deltas), what appeared/disappeared,
+and which findings appeared or cleared — the regression check for a layout edit.
+
+## 8. Timing and determinism
+
+The snapshot is taken after a settle delay (default 750 ms past world-ready). A world whose props animate
+into place may need more: pass `settleMs`. Objects that animate forever (a spinning pickup) snapshot at
+whatever pose they hold that frame — expect their numbers to differ between runs.
+
+## 9. Adding the helper to an existing world
+
+Almost every world scaffolded before the inspect helper existed is missing the `world.ready` call — and a
+fix-up session on such a world cannot measure anything until it lands. `check_for_updates({ projectDir })`
+reports the wiring state up front ("engine-core is pinned but src never calls world.ready"), which is cheaper
+than discovering it through an inspect timeout. The upgrade is small and additive:
+
+1. `"engine-core": "^0.1.2"` in `public/helix.json` → `systems` (alongside `humanoid-character`), then
+   `install_world_packages` (or the CLI's `helix install`).
+2. If `vite.config.ts` predates the alias, add this line to `resolve.alias` BEFORE the root
+   `@helix/engine-core` entry — subpath aliases must precede the root alias, or rollup's prefix
+   substitution mangles the import into an ENOENT:
+
+   ```ts
+   '@helix/engine-core/inspect': fileURLToPath(new URL('./public/helix_modules/engine-core/inspect/index.js', import.meta.url)),
+   ```
+
+3. The two lines from §1 in `src/main.ts`, then rebuild (`npm run build`) and `inspect_world` as usual.

package/docs/world-look.md

@@ -0,0 +1,241 @@
+# The look of a world — from raw assets to good
+
+The QA gates can tell you a world fails to look right (`materials.default-plastic`, `composition.primitive-dominant`,
+`lighting.unmotivated`). This page is how to make it look right: the process the platform maintainers converged on
+while calibrating real production scenes (Amazon's Bistro, Crytek and Intel Sponza) against the visual runtime — and
+the mistakes they made first, so you do not repeat them. Every number below was measured on those scenes.
+
+Territory: lighting itself — the runtime, `helix.visuals.json`, baked vs dynamic, quality tiers — is
+`read_doc({ name: "lighting-world" })`. Where assets COME FROM (the sourcing ladder, budgets, loaders) is the
+`helix-assets` skill; the six build non-negotiables are `helix-world-build`; what blocks a ship is `helix-world-qa`.
+This page owns what sits between: **asset truth, material consumption, texture hygiene, scene assembly, composition,
+and judging your own captures.** The platform doctrine is *measure first, look last* — this page is the LOOK half.
+
+## Fix defects before taste
+
+Raw assets are usually **broken**, not merely unstyled. Bistro — a professionally authored, industry-standard
+showcase scene — shipped to the calibration bench with the wrong scale, all-metal materials, dead normal maps and
+mip-less textures. Styling on top of defects teaches you wrong numbers everywhere downstream: you crank a light to
+fight metalness, then crank the grade to fight the light. The maintainers' rule, verbatim: **a knob that does nothing
+or behaves nonlinearly is a defect signal, not a tuning challenge.** Find the defect; do not compensate.
+
+So the work has a fixed order, and taste comes last:
+
+```
+1. ASSET TRUTH      — the import checklist below, per asset, before anything is styled
+2. GEOMETRY + SUN   — measure the space, then aim the light at it
+3. MATERIALS        — consumed correctly (per-axis repeat, multiplier semantics, whole ORM)
+4. GRADE, LAST      — and inside the grade: power (contrast) first, saturation second, slope last
+5. VERIFY           — captures from more than one camera; on a cycling world, more than one hour
+```
+
+Iterate with one knob at a time, and re-look after each change. And the meta-rule that has paid for itself more than
+any other: **measure whether a knob reaches the frame — do not trust a comment, including your own.** Take a capture,
+change the value, take another; if nothing moved, you found a defect (or the knob is not yours — see the
+lighting-world DO/DON'T table).
+
+## Asset truth — the import checklist
+
+Run this on every imported GLB or third-party asset before styling. Each row is a defect that shipped in a
+professional scene and survived until someone measured.
+
+1. **Scale, proven — never assumed.** The platform is metric and the avatar is a real ~1.8 m human; shadow bias, fog
+   density and the probe volume are all metre-derived, so a mis-scaled world silently degrades all of them. Bistro's
+   exterior shipped **1.6× oversized** — proven by a shared liquor-bottle mesh measuring 0.580 m in one sub-scene and
+   0.364 m in another. Prove scale with a known-size object: a bottle, a table (~0.75 m), a doorway (~2.1 m).
+2. **`metallicFactor` present.** glTF's default for a MISSING `metallicFactor` is **1.0** — full metal, no diffuse
+   term at all. All 132 of Bistro's materials omitted it: cobbles, plaster, foliage and fabric arrived as mirrors
+   with their base colour re-read as specular tint, and — because diffuse GI lights only diffuse surfaces — the
+   probe field lit **literally nothing**: the frame rendered byte-identical with the GI removed. If an imported
+   world looks dark, oddly tinted, and GI seems to do nothing, check metalness FIRST. Set `metalness: 0` on
+   everything that is not actually metal.
+3. **Roughness varies.** One global roughness constant across a whole asset (Bistro: 0.5527864 on all 132 materials)
+   is a conversion artifact, not authoring. Expect a roughness map or per-material values.
+4. **Normal maps carry a real blue channel.** Bistro's normal maps were two-channel with blue zeroed — the decoded
+   normal pointed INTO the surface, so up-facing geometry refused sun. Symptom: surface detail lit from the wrong
+   direction, or normal maps that seem to darken. The cheap convention test (DirectX vs OpenGL green): flip
+   `material.normalScale.y` and see whether the detail snaps right.
+5. **Colorspaces are per texture.** Albedo/emissive = sRGB; normal, ORM, roughness, anything data = linear. A linear
+   albedo reads washed out; an sRGB normal map reads lumpy. Platform materials arrive correctly tagged; hand-wired
+   textures are where this goes wrong.
+6. **Alpha mode is a per-material decision.** Near-binary foliage alpha → `alphaTest` (MASK); liquids and glass stay
+   BLEND — Bistro's wine and beer forced to cutout render as garbage. And do not assume foliage means alpha at all:
+   Intel's ivy is opaque modelled geometry with no alpha channel. Blended foliage on thousands of triangles will
+   sort-artifact; that is what MASK is for.
+7. **No stray lights, no double-counting.** Imported GLBs carry lights you did not ask for (Intel's Sponza ships 24)
+   — strip them on load. Never hide one with `visible = false`: a glTF light node may PARENT its fixture's meshes,
+   and an invisible node's children stop rendering with it. Remove the light from the scene or layer-mask it. And
+   never represent one light twice — an emissive mesh is not a light source (it glows, it does not illuminate), and
+   a hand-placed "sun" on a runtime-lit world double-lights the whole frame.
+
+## Geometry first, then the sun
+
+Aim the light at the space you actually built — measured, not eyeballed. A courtyard, atrium, alley or roofed street
+has an **elevation floor**: a sun below it never reaches the ground, and the transition is a cliff, not a slider.
+Sponza's courtyard measures 16 × 5.6 m at 14.4 m deep — a well; direct sun reaches its pavement only above ~61°
+elevation, and the first auto-derived sun left **0.14 % of the frame lit**, with the whole scene running on blue sky
+ambient. That is the "flat, dim, bluish" signature: not a grade problem, an aim problem.
+
+On a runtime-lit world you aim with two fields in `helix.visuals.json`: `noonAzimuthDeg` (the one knob that aligns
+the sun path to YOUR geometry — set it first) and `hours`. Sanity-check against the shadows you want: pick the
+façade the sun should rake, verify the interior you care about actually receives light at your chosen hour, and
+re-check at a second hour if the world cycles. If an interior must read sunlit, the opening it receives sun through
+is part of your geometry design, not something the grade can fake later. And if the aim is right but a bounded
+interior still reads washed and flat, the defect is the sun-to-ambient RATIO, not the aim and not the grade — the
+fix is the transport knobs, in lighting-world's "Calibrating a high-contrast interior" recipe. The same recipe
+covers the opposite complaint: an interior that reads too DARK once its bake is honest is short of BOUNCES, not of
+exposure — `probes.bounces` 2–3 and `sky.irradianceScale` are the dials, and `exposure.key` / `exposure.postGain`
+develop the result afterwards.
+
+Two scene-side facts complete the picture:
+
+- **Scene-side dynamic range is half the job.** The tone mapper cannot manufacture contrast the render does not
+  contain: a scene where grass, cobble and concrete all sit near the same albedo, with no deep shade anywhere,
+  measured ~1 stop of usable range against Bistro's 3.5–4. Vary your albedos and build real occluded volumes —
+  doorways, overhangs, interiors — or the world will read flat under any grade.
+- **Sealed interiors.** A single-sided or paper-thin wall lets sky light leak into shaded space (the bake samples
+  through backfaces): the signature is a blue-white wash on surfaces that should be in shadow. Give interior shells
+  thickness or double-sided walls, keep large geometry off exact probe-grid planes, and expect thin cards and
+  single-quad walls to need deliberate shadow treatment (`material.shadowSide`, or `castShadow = false` on a shell
+  that would otherwise fill the shadow map with its own far face). An interior that will BAKE also has to fit the
+  probe volume to its room (`probes: { center, size }` in `helix.visuals.json`): placement and extent are authorable,
+  the probe budget is not — which is why a very large map, spreading the same probes thinner, ships `dynamic`
+  instead. The numbers, and the ceiling-wash defect this prevents, are in `read_doc({ name: "lighting-world" })`.
+
+## Platform materials — consuming them correctly
+
+A real HELIX agent once built a world on the platform material pack and it still looked wrong. The audit found the
+textures were fine — the agent had re-implemented a material library by hand, got ~80 % right, and the subtle 20 %
+ruined it: tiling written as if UVs were metres, scalar overrides that silently discarded the roughness/metalness
+maps, the AO channel never bound. Every rule below exists because of that world or one like it.
+
+**The taught path** — the visual system ships a material library that gets all of it right by construction.
+Setup, once per world: add `"visual": "^0.1"` to the `systems` block in `helix.json`, then run
+`install_world_packages` with `update: true` (terminal: `helix install --update`) — a newly added pin is refused
+until the lock is re-resolved.
+
+```ts
+import { loadMaterialLibrary } from '@helix/visual';
+
+// assetBaseUrl = the pack base: `assetBaseUrl` in use_material's output (`helix assets material <id>`).
+const materials = await loadMaterialLibrary(assetBaseUrl, { renderer });
+
+// A 20 x 12 m floor: apply() measures the mesh (and its world scale) and derives per-axis repeat
+// from the material's physical tile size — no repeat arithmetic in world code, ever.
+// Boxes, planes, spheres, cylinders and capsules are measured exactly.
+const floor = new THREE.Mesh(new THREE.PlaneGeometry(20, 12));
+materials.apply(floor, 'cobblestone');
+
+// Imported geometry with unknown UVs: state the metres its 0..1 UV span covers. Without `size`, apply()
+// can only estimate from the bounding box, which stretches anything whose UVs are not laid out that way.
+materials.apply(importedWall, 'painted-wood', { size: [8, 3] });
+
+// Hand the library's readiness to the visual runtime (the assetsReady option in the boot snippet)
+// so no lighting is computed from half-loaded textures.
+await materials.ready();
+```
+
+Worlds not on the visual system load the same catalog through the SDK — `Helix.materials.load(assetBaseUrl)`, then
+`library.resolve(id)` for absolute map URLs and authored defaults — and wire the maps themselves. If you do that,
+these are the rules the hand-rolled library broke:
+
+| DON'T | DO | Why |
+|---|---|---|
+| `texture.repeat.set(s, s)` with s derived from "tiles per metre" | derive repeat PER AXIS from world size: `repeat = faceMetres / tileMetres` for each axis | stock geometry UVs span 0..1 across the whole face — they are not metres. The square set() smeared ~45 % of ONE tile across a 34 m slab, and ignores face aspect, stretching every non-square face |
+| pass `roughness: 0.8` and drop the map (or null it "to be safe") | keep the maps bound; scalars are three.js MULTIPLIERS over them — with real maps bound, set the scalars to 1 | nulling the map throws the authored data away; and a catalog value authored as an absolute double-attenuates when multiplied into the map |
+| bind only the albedo | bind the whole ORM triple — one texture into `aoMap`, `roughnessMap` AND `metalnessMap` | the pack's ORM is R=occlusion, G=roughness, B=metalness; binding one channel wastes the other two (the r185 rule "aoMap needs uv2" is dead — every map samples through `.channel`) |
+| grab Vault `kind=texture` results as world textures | the material pack is the FIRST rung (`list_materials` → `use_material`) | Vault loose textures are flat single images, several with baked-in lighting — a diffuse photo applied as `map` on a default material is exactly "supposed to be PBR but does not look PBR" |
+| request 2K everywhere | 2K on hero surfaces the camera gets close to; the default elsewhere | resolution is a budget; distant and background surfaces cannot show the difference |
+
+The pack's authored values (`roughness`, `metalness`, `normalScale`, the physical tile size, glass/water parameters)
+are calibrated as a set — trust them first, and tune only after the checklist above is clean.
+
+## Texture hygiene
+
+The single highest-leverage image-quality fact on the platform: **mips + anisotropy measured +5.06 dB / +0.153 SSIM
+— about three times the benefit of the entire anti-aliasing ladder.** Shimmer, moiré and texture crawl are texture
+defects; no AA setting fixes them. Check these before ever blaming the quality tier:
+
+- **Mips must live inside the KTX2 container.** three cannot generate mipmaps for compressed textures — a mip-less
+  KTX2 shimmers at grazing angles and reads full-resolution at any distance, forever. 622 of Bistro's 637 textures
+  shipped mip-less. Vault uploads of mip-less KTX2 are now rejected at publish (a hard error), but **world bundles
+  only WARN** at `helix validate` — a shimmering file ships legally, so read your warnings.
+- **Never hand-encode KTX2 into a bundle.** The platform importers pass the mip flag, cap sizes and pad correctly;
+  hand-encoded files are how mip-less textures happen. Feed the pipeline source images (PNG/JPG/WebP) instead.
+- **Never a non-mipmap `minFilter`.** With `minFilter: LinearFilter` the driver ignores anisotropy entirely —
+  anisotropy 1, 8 and 16 render byte-identical. Inside a glTF the sampler wins over the loader, so an exporter can
+  commit this silently; `helix validate` warns on it.
+- **Alpha-tested foliage needs coverage-preserving alpha mips**, or leaves thin out and vanish with distance —
+  a separate defect from cutout edge-crawl, and `alphaToCoverage` does not fix it.
+- **Old Vault assets predating the mip gate still shimmer** — they are grandfathered, not fixed. Re-publishing the
+  asset through the pipeline is the fix.
+
+On runtime-lit worlds, anisotropy itself is the runtime's job (set per quality tier at construction) — your job is
+not to break it with the two DON'Ts above.
+
+## Composition — building a frame worth capturing
+
+This is the territory the QA scorecard grades (rows 3–5) and nothing else teaches:
+
+- **Layer the space: foreground, midground, background.** A flat plane with objects scattered at one distance reads
+  as a diorama. Give the camera something near, something at play distance, and something far (a skyline, a wall
+  with depth cues, terrain) — and include **scale cues** the player reads instinctively: doorways, railings,
+  furniture, lamps, all at real metric sizes against the ~1.8 m avatar.
+- **Repeated scenery ships instanced — mesh count is the ceiling, not triangles.** Every draw call costs
+  roughly constant main-thread dispatch (~15 µs, measured) however small the mesh: the platform's ≤300-call
+  budget is already ~4.5 ms of a 16.7 ms frame, and every extra hundred calls is another ~1.5 ms gone before
+  a pixel shades. An agent-built world shipped its skyline as ~1,200 individual meshes — every lit tower
+  window and water glint its own object — for only 72k triangles and 19.7 ms of draw dispatch: **45 fps
+  facing the windows, 60 looking away.** So anything you place in a loop (windows, glints, star fields,
+  foliage cards, crowds of repeated props) is ONE `InstancedMesh` per material family, per-instance colour
+  for variety — the same frame, a handful of draws. When frames are slow, **count draw calls first** (the
+  `?perf=1` handle and `helix world perf-gate` both report them) and remedy in order: instance repeated
+  families, merge static same-material geometry, and only then reach for resolution or quality levers. The
+  cost only shows when the camera FACES the population, so captures pointed elsewhere read clean — which is
+  why this is authored up front, not discovered at QA.
+- **Material ROLES, not per-object one-offs.** Good scenes reuse a small palette by role — one floor family, one
+  wall family, a trim material on edges and openings, an accent — with wear where hands and feet actually go. A
+  world where every object carries its own unrelated material reads as noise; the scorecard's "cohesive material
+  language" is this, and reuse is also what keeps the texture budget honest.
+- **Contrast is authored.** Deep shade, bright openings, albedo variation between families (see "scene-side dynamic
+  range" above). If every surface is mid-grey, no lighting or grading rescues it.
+- **Practical lights follow the budget patterns** — the emissive-mesh-plus-real-light pairing, the layer-masked
+  night rig, and the eight-light ceiling are in the `helix-world-build` skill and the lighting-world night note;
+  composition-wise the rule is that light placement is motivated by fixtures the player can see.
+
+## Judging your own captures
+
+`capture_world_screenshot` is the closing check — after the numbers (placement via `inspect_world`, traversal via
+`world_metrics`) are already right. When you look, know what a capture can and cannot answer, and iterate honestly:
+
+- **One well-chosen angle beats a burst.** Frame the world at active-play framing (what a player actually sees),
+  not a turntable beauty angle. Check the mobile viewport too — composition that reads at desktop can collapse at
+  390 px wide.
+- **Change one knob, capture before/after, compare.** A look opinion formed across two captures with three changes
+  between them attributes improvement to the wrong knob.
+- **What to look for**, in order: Is anything obviously BROKEN (black surfaces = missing maps or all-metal; lit
+  interior walls that should be dark = leaks; wrong-scale props against the avatar)? Does the frame have depth
+  layers and deep shade? Do materials read as their substance at play distance? Does light direction match the
+  fixtures and sky the player can see? Only then: mood, grade, art direction.
+- **References have limited authority.** A photograph settles *relative* falloff and material behaviour, never
+  absolute brightness (your exposure is auto-derived — bias or pin it through lighting-world's `exposure` block,
+  not by matching a photo's levels); an engine-demo screenshot settles sun side and gross framing
+  and is often a LOW quality bar, not an aspiration; a render made without GI answers framing only — never brightness
+  or colour. Do not tune your world to match a reference's property that the reference cannot testify about.
+
+## The hard boundary — no fake light transport
+
+The platform's ground rule, and it is craft, not just a gate: **light in a HELIX world is real transport.** No fill
+lights standing in for GI — the runtime provides real indirect light (sky, probes, bounces); a hand-placed fill
+"because the corner is dark" fights it and reads wrong the moment the sun moves. (The sanctioned dials for the
+GLOBAL balance are the transport knobs — `sun.intensityScale`, `sky.irradianceScale`, `environment.intensity`,
+`shadows.opacity` and, for indirect light specifically, `probes.bounces` in lighting-world — plus `exposure.key` /
+`exposure.postGain` to develop the frame. Never an extra light: a second bounce is something the bake can compute,
+and a fill light is a guess at it.) No fog, darkness, bloom or particle
+soup hiding missing geometry — the scorecard fails it on sight, and it always reads as what it is. If a corner is
+too dark, the fixes are real: an opening that admits light, a practical fixture with a real light, a lighter albedo,
+or accepting that some corners are dark because that is what makes the lit parts read.
+
+Where to go deeper: `read_doc({ name: "lighting-world" })` for everything the light rig itself does;
+`list_materials` / `use_material` for the palette; the `helix-assets` skill for sourcing anything you do not have;
+the `helix-world-qa` skill for proving the result.

package/docs/world-recipe.md

@@ -1,5 +1,7 @@
 # HELIX Instant — World Project Recipe
 
+After the first build or Scene import, call `analyze_scene_performance` before visual polish. It returns estimated reference-budget utilization and concrete fixes while leaving unknown runtime costs unknown. Repeat it with the final Scene, Package, inspection snapshot, and performance receipt; `read_doc({ name: "scene-performance" })` defines every counter and the matched fullscreen visual QA.
+
 Follow this recipe exactly to generate a **publishable HELIX Instant world**. A world is a static web app (Vite-built) that runs sandboxed in the HELIX portal and talks to the platform only through `@hypersoniclabs/helix-sdk`.
 
 ## Project layout
@@ -27,11 +29,11 @@ my-world/
     "build": "vite build"
   },
   "dependencies": {
-    "@hypersoniclabs/helix-sdk": "{{SDK_DEP_SPEC}}",
-    "three": "^0.172.0"
+    "@hypersoniclabs/helix-sdk": "{{SDK_DEP_SPEC}}"
   },
   "devDependencies": {
-    "@types/three": "^0.172.0",
+    "@types/three": "^0.185.1",
+    "three": "^0.185.1",
     "typescript": "~5.7.3",
     "vite": "^6.0.0"
   }
@@ -40,6 +42,8 @@ my-world/
 
 Three.js is the usual choice but any web stack works — the only hard requirements are the manifest, the SDK, and a static `dist/` output.
 
+`three` belongs under `devDependencies`, not `dependencies`: nothing installs a world's npm tree at runtime. Either Vite bundles three into `dist/` (a bare scene like this one) or the platform hosts it and `helix install` import-maps the bare specifier (any world that pins a system — see the character recipe). Keep it on the platform's line, **0.185.1**: a world that pins a system and targets an older three still publishes, but `helix validate`/`publish` warn and name the upgrade path.
+
 ## vite.config.ts — `base: './'` is REQUIRED
 
 ```ts
@@ -52,6 +56,13 @@ export default defineConfig({
 });
 ```
 
+**And never write a root-absolute URL for anything inside your own bundle.** `base: './'` only fixes the
+URLs *Vite* emits. Any path you write by hand — `fetch('/data.json')`, `new Audio('/theme.mp3')`,
+`loader.load('/models/ship.glb')` — still resolves against the SITE root, which is not where a published
+world lives (`…/instant-worlds/<id>/<build>/`). It 404s and usually throws, while working perfectly in
+local preview. Resolve against the document instead: `new URL('models/ship.glb', document.baseURI).href`.
+`verify-subpath` (below) is what proves you got them all.
+
 ## public/helix.json — the manifest
 
 ```json
@@ -91,6 +102,10 @@ Rules that commonly bite:
 </html>
 ```
 
+**On-screen UI (HUD).** The player shell overlays a chrome bar across the **top-center** of every world (~top 56px:
+Exit / Save Progress / helixOS — user-hideable, but shown by default). Any HUD / DOM overlay you add must stay OUT of
+that strip: anchor it to a corner (top-left/right) or the bottom, never top-center, or it renders behind the chrome.
+
 ## src/main.ts — SDK integration pattern
 
 ```ts
@@ -129,9 +144,53 @@ npm install
 npm run build          # → dist/ (contains helix.json, index.html, assets/)
 ```
 
-Then use the MCP tools, in order:
+Then, in order:
 1. `validate_world` with the **absolute path to `dist/`** — fix every reported problem.
-2. `whoami` — confirm a creator login exists (if not, the human must run `helix login`).
-3. `publish_world` with the same dist path — returns the public play URL.
+2. `npx -y {{CLI_PKG}}@latest verify-subpath dist` — **REQUIRED.** A published world is served from
+   `…/instant-worlds/<id>/<build>/`, never the origin root, but `npm run preview`, `validate_world` and
+   `inspect_world` all serve `dist/` from a root. So they all pass a bundle whose root-absolute URL 404s
+   and throws in production. This gate serves the same bytes from a nested path and fails on a throw, a
+   404, or a blank render — it is the only local check that sees the difference.
+3. `whoami` — confirm a creator login exists (if not, the human must run `helix login`).
+4. `publish_world` with the same dist path — returns the public play URL.
 
 Budget: ≤ 200 files, ≤ 25 MB per file, ≤ 50 MB total. Allowed types include html/js/css/json/wasm, images (png/jpg/webp/svg/ktx2), models (glb/gltf/bin), audio (mp3/ogg/wav), fonts.
+
+## Verify placement by measurement — see the world-inspect doc
+
+To check WHERE things actually landed, do not squint at screenshots — `inspect_world` on `dist/` returns the
+scene as data (positions, extents, placement findings), and `focusNear: [x, y, z]` checks just the object you
+placed at that coordinate. Works on a bare scene too (no character system needed — the collider report simply
+says it has nothing to read). Full workflow:
+
+```
+read_doc("world-inspect")
+```
+
+## In development: scene-streamed worlds — opt-in, only when the creator asks for one
+
+The `scene` scaffold kind is a platform feature still in development. Do NOT pick it for "a scene", "a bare scene" or
+"a world with no character" — those are the plain recipe above, or a `character` / `multiplayer` scaffold whose
+geometry you place yourself. Use it ONLY when the creator explicitly asks for a world whose environment is a streamed HELIX Scene
+v2 document, or names a Scene document / Scene Package to stream — and say so in your plan before scaffolding.
+
+A **scene world** is the opposite trade from the recipe above: instead of placing geometry in `main.ts`, the world's
+environment is a sealed **HELIX Scene v2** document that the platform's `scene` system streams and the `visual` system
+lights. `scaffold_world({ kind: "scene" })` — `helix init <dir> --kind scene` — writes one: a starter document
+compiled offline into `public/scene/mall/` next to its `pin.json`, that same pin in `public/helix.json`'s `scene`
+field, a `public/helix.visuals.json` lighting contract, a `public/.helixignore` that keeps `scene/` out of the
+uploaded bundle, and a `src/main.ts` that boots in the one order that works: document → visual runtime → scene world
+→ character facade. There is no floor, no props and no lights in that file — geometry, materials, authored lights,
+spawn and collision all come from the document. Underneath it is a multiplayer world (presence + proximity voice), so
+the multiplayer recipe still applies on top.
+
+Two things differ at publish time: `install_world_packages` must resolve the extra `scene` and `visual` system pins,
+and a published world resolves its environment from the `scene` pin against the backend — so the **document has to be
+published before the world** (`helix world scene-source publish`). Locally, `?scene=<folder>` picks between the
+documents under `public/scene/`.
+
+**Terrain** — open ground for a scene world — is the one environment piece you author as DATA rather than place:
+`scaffold_world({ kind: "scene", terrain: "alpine" })` generates a 1 km x 1 km heightfield into the scaffolded
+document, and `terrain_generate` / `terrain_import` / `terrain_inspect` author, adopt and measure it afterwards. It
+is a scene-world feature only, it stays on dynamic lighting (never bake a terrain world), and the folder must be
+inspected before publishing. The whole recipe, the six presets and the caps: `read_doc({ name: "terrain" })`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypersoniclabs/helix-mcp",
-  "version": "0.2.5",
+  "version": "0.2.12",
   "description": "HELIX Instant MCP server — gives AI coding agents the platform contract: world recipes, manifest schema, validation, catalog discovery, and publishing.",
   "type": "commonjs",
   "main": "dist/server.js",
@@ -9,15 +9,26 @@
   },
   "files": [
     "dist",
-    "docs"
+    "docs",
+    "scaffold",
+    "skills"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "lint": "eslint \"src/**/*.ts\"",
-    "test": "node scripts/smoke.mjs"
+    "test": "npm run build && node scripts/smoke.mjs && node scripts/legacy-publish-negative-smoke.mjs && node scripts/continuum-canary-smoke.mjs && node scripts/continuum-pull-smoke.mjs && node scripts/item-distribution-smoke.mjs && node scripts/item-thumbnail-smoke.mjs && node scripts/builds-smoke.mjs && node scripts/looks-smoke.mjs && node scripts/device-smoke.mjs && node scripts/engine-pin-smoke.mjs && node scripts/publish-source-smoke.mjs && node scripts/codex-smoke.mjs --schema-only",
+    "test:codex": "npm run build && node scripts/smoke.mjs && node scripts/publish-source-smoke.mjs && node scripts/codex-smoke.mjs",
+    "test:package": "npm run build && node scripts/package-smoke.mjs",
+    "verify": "npm run test:codex && node scripts/package-smoke.mjs",
+    "e2e": "node scripts/e2e-inspect.mjs",
+    "test:vault-live": "node scripts/test-vault-live.mjs",
+    "test:looks-live": "npm run build && node scripts/looks-live-smoke.mjs"
+  },
+  "helix": {
+    "minCliVersion": "0.1.23-helix3.433"
   },
   "dependencies": {
-    "@hypersoniclabs/helix-cli": "^0.1.7",
+    "@hypersoniclabs/helix-cli": "^0.1.23",
     "@modelcontextprotocol/sdk": "^1.12.0",
     "zod": "^3.24.0"
   },