@hypersoniclabs/helix-mcp 0.2.5 → 0.2.12

package/skills/helix-avatars/references/source-rigid.md

@@ -0,0 +1,90 @@
+# Source: rigid bodies (robots, CAD and URDF, scanned or segmented kits, armour)
+
+Lanes:
+- **Unitree G1**: a URDF with CAD STL meshes.
+- **C-3PO**: a geometry-only scan in 242 welded parts, ripped from a web viewer.
+- **T-800**: hard-surface plates on a skinned source.
+
+A rigid avatar uses no dynamics. Its quality comes from the pivots, the pose and the materials.
+
+## Bind 1:1 to bones
+
+Every part gets weight 1.0 on **exactly one** `helix-humanoid@1` bone:
+
+| Parts | Bone |
+| --- | --- |
+| Pelvis shell | `pelvis` |
+| Torso and chest plates | `spine_05` |
+| Head | `head` |
+| Shoulder bell and upper arm | `upperarm_*` |
+| Forearm | `lowerarm_*` |
+| Hand and fingers | `hand_*`, unless you build finger joints |
+| Thigh, knee drum and shin, foot | `thigh_*`, `calf_*`, `foot_*` |
+
+- **Put the joints at the mechanical pivots.** On a URDF, these are the joint origins.
+- Author the bones with canonical names and pass an identity `--map`.
+- Exceptions:
+  - **Pistons** that span two bones are split along the rod, and each half binds to its own bone, so
+    they telescope.
+  - **Cables, wires and hoses** keep a two-bone blend: pelvis to `spine_05` by height, for example.
+
+**Segmenting a welded scan.** Assign each connected component to the nearest bone capsule, using the
+source's own joint positions. Keep an override file for components the heuristic gets wrong
+(drop / forearm / piston), and read `JOINTS_0` back per LOD afterwards.
+
+## Pose to the canonical A-pose
+
+Source poses vary: URDF zero pose, hands on hips, a T-pose. Re-pose **per segment**:
+1. Map each segment's measured frame onto its canonical frame. For a limb, use the bone direction plus
+   the hinge plane. For a hand, the finger direction plus the palm normal. For a leg, the leg
+   direction plus the foot heading.
+2. Find the pelvis, torso and head from a mirror-plane symmetry search.
+
+The importer's rest aim then comes out as identity, and the shared clips play as designed. Unitree G1
+solved its rest pose by optimisation: arms rotated +8° and thighs splayed 3.1° to match the canonical
+A-pose.
+
+## Size, and the short-body gate
+
+- Scale to the real height. Do not stretch to human height: Unitree G1 is 1.32 m.
+- **Under 1.35 m, locomotion retargets only if (pelvis − foot) / 0.877 < 0.65.** Measure that ratio
+  before you publish.
+  - G1's natural ratio was 0.74, so the clips ran unscaled and the feet sank 2–5.7 cm.
+  - Placing the pelvis joint 7.5 cm lower, at 0.60 m (ratio 0.62), fixed it.
+  - The mesh did not move. Only the pivot did.
+
+## Materials without textures
+
+A CAD or scan source with no textures gets **one palette atlas material**. Rules map faces to
+colours, with dark variants in occluded crevices:
+- C-3PO's palette was 4 × 4 at 256 px;
+- Unitree G1's atlas was 256 px, holding base, metal/rough and emissive.
+
+The cost is one material: 6 draws across three LODs, with a few MB of file.
+
+Do not attempt a unique-UV normal bake on thousands of small parts. C-3PO's attempt produced about
+8,000 islands at 9–31 % coverage and noisy normals. Transfer normals from the high-poly mesh onto the
+decimated one instead.
+
+## Geometry
+
+- Weld and smooth normals at about 40°.
+- Ray-test and cull hidden faces outside the moving limbs (about 16k on C-3PO).
+- Decimate per segment toward a shared triangle total.
+- Replace brackets that decimate badly with convex hulls.
+
+Budgets that shipped:
+
+| Avatar | Triangles | Draws | File |
+| --- | --- | --- | --- |
+| Unitree G1 | 34,998 / 14,531 / 4,944 | 6 | 4.49 MB |
+| C-3PO | 38,999 / 13,993 / 5,646 | 6 | 3.39 MB |
+
+## Taste
+
+- A 5 % head scale-up read as stocky.
+- Pale cream eyes and pale gold read as washed out.
+- Judge against real photographs, using the same viewer for each candidate. For Unitree G1, the
+  URDF's own render served as the baseline.
+
+The critic plateaued at about 6/10 on these lanes. Say which exit you took.

package/skills/helix-avatars/references/source-vrm.md

@@ -0,0 +1,61 @@
+# Source: a VRM (`.vrm`, VRoid and VRM 0.x / 1.0)
+
+VRM is the only source that arrives with a humanoid map, spring bones and a face. **Never hand-roll a
+VRM conversion.** The bridge does it in-process:
+
+```
+bridge_import({ source: "/abs/avatar.vrm", type: "character", canonical: "/abs/base.web.glb", output: "/abs/out-vrm" })
+# CLI: helix bridge import avatar.vrm --type character --canonical base.web.glb -o out-vrm
+```
+
+`canonical` is **required, with no default**. It is the base body `*.web.glb` that the canonical
+skeleton is fitted from: the stock `body-f-default.web.glb` or `body-m-default.web.glb` from a
+throwaway character world's asset pack (`qa` step 3). The base you fit to is part of the result, so
+record which one you used.
+
+The output is `<slug>.glb` plus `vrm-conversion-receipt.json`. There is no `*.avatar-import.json` for
+this route.
+
+## What it does
+
+| Area | Result |
+| --- | --- |
+| Skeleton | Read from the file's own humanoid map, handling the thumb-name difference between VRM 0.x and 1.0. It is flipped to +Z forward and conformed to `helix-humanoid@1`. Spring-bone joints survive as auxiliary joints. |
+| Dynamics | SpringBone becomes `helix/dynamics@1`, with real unit conversion, on every scene. A chain survives only if its root survived the conform **and** something in its subtree is weighted. Set `VRM_DEBUG_CHAINS=1` to print kept and dropped chains. |
+| Colliders | Used colliders are kept and renamed onto canonical bones. VRM 1.0 sphere and capsule shapes import. VRM 0.x is sphere only. |
+| Face | Expressions become `helix/avatar-face@1`, capability `vowel5`, with both blinks and the expression presets. **No `jawOpen` is declared**, on purpose. Undeclared blend shapes are pruned; a VRoid face drops from 57 shapes to 13. |
+| First-person hide | Written automatically: meshes with at least 80 % head weight. |
+| Budget | **A single scene: no LOD chain.** It decimates to 15,000 triangles, textures to 512 px, and atlases to 8 materials or fewer. |
+
+## Audit the conversion before you publish
+
+1. **Read the receipt's warnings**: dropped collider shapes, clamped stiffness or damping, guessed
+   importance.
+2. **Check every `center` chain.**
+   - VRoid writes a `center` on most spring groups by default. The CLI approximates it as
+     `inertia: 0.6`.
+   - On short chains (ears, bangs, accessories), 0.6 lets them swing 90°–120° at a sprint.
+   - Retune them to the short-chain values in `dynamics`: inertia about 0.97, stiffness 1.0, damping
+     0.5, a 22° cone.
+3. **Per-joint variation is lost.** Only each spring's first joint values are used. Where the source
+   tapered stiffness along a strand, write a curve (`[root, tip]`).
+4. **Heavily dragged chains all clamp to critical damping** and stop looking different from each
+   other. If the hair reads as one stiff mass, lower damping on the long strands.
+5. **Look at it running** (see `qa`). VRM tuning assumed three-vrm's frame-rate-dependent integrator,
+   and HELIX's solver is exact. The same numbers can read differently.
+
+Edit only the `helixDynamics` JSON in place, on every scene. The catears lane's approach was to
+rewrite just the GLB JSON chunk and copy the binary chunk verbatim. Never re-import to change tuning.
+
+## Limits of this route
+
+- One LOD at 15k triangles. That is far under the 60k budget, but it means no near-field detail.
+- A VRoid model exported as **GLB** instead of VRM loses all of this. It imports through
+  `import_character` with `face: none`, unless you pass a `faceMap`, and with no dynamics.
+  - Get the `.vrm` if one exists.
+  - If not, write the `faceMap` (`read_doc({ name: "avatar-face" })`) and author dynamics per
+    `dynamics`.
+- Cutting a **wearable** from a VRM (`keepMaterials`) uses the same converter at a smaller budget
+  (8k triangles, 4 materials). Chains with no garment geometry under them are dropped.
+- A published package-backed VRM base cannot have its mesh replaced. The pin-correction route admits
+  stiffness and damping changes only. Tune before the first publish.

package/skills/helix-gauntlet/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: helix-gauntlet
+description: MANDATORY before any HELIX item is published, given a new version, listed, repriced into sale or reported done — vehicles, add-ons, avatars, wearables, props and worlds. Pick an external bar (photos and specs of the real thing), render the candidate in the real runtime from a fixed inspection set, look at every render against the bar, get a fresh blind critic's verdict where you can spawn subagents, fix and re-render, and ship only on a pass. Also for re-checking an item that is already listed when the gates change or you update it.
+---
+
+# HELIX Gauntlet
+
+Every gate in the other skills measures something. This one makes you **look**, against something real.
+
+**Why it exists.** A Ferrari F40 passed every measured gate, a submitted visual-QA run and an owner-proxy
+ACCEPT, and went on sale. Its owner then opened it and found the driver lying almost flat, both hands off
+the steering wheel, the fingers twitching, and the passenger folded with the knees at the chest. The
+proxy had written "reclined, knees up" in its notes and called it non-blocking; nobody looked at the
+hands. A Porsche 993 shipped with its wheels tucked into the arches because QA read numbers and never
+looked at the car. Both defects were obvious in one picture. Neither picture was looked at against the
+real car.
+
+## The rule
+
+- **No publish, new version, listing or "done" without a PASS from this loop.** Not your belief that it
+  passes: the artifacts below, written to the ledger.
+- **A defect you can see is a FAIL even when every number passes.** There is no "minor" for posture,
+  hands, fingers, clipping, floating, missing or wrong-coloured parts. "Reclined", "knees up", "hands off
+  the rim", "fingers moving" are FAIL reasons, never notes.
+- **Every executable assert is blocking.** A tool exit 1 is a FAIL; fix it before you spend a critic.
+- **Only the real runtime counts.** Judge renders from the HELIX runtime (`preview_vehicle`, visual QA),
+  never Blender viewport shots, a GLB viewer, or the source code.
+
+## The loop
+
+Keep `gauntlet/` beside the item's source: `bar/`, `round-1/`, `round-2/`…, and `LEDGER.md`.
+
+1. **Pick the bar, once.** The bar is the real thing: reference photos of the exact car / character /
+   object at the inspection poses (front, both 3/4 views, both sides, rear, top, cockpit and interior,
+   wheel, lamp and detail close-ups) plus its published specs. Save them in `gauntlet/bar/` with
+   `INDEX.md` naming each photo's pose and source. A fictional item's bar is its concept art plus a named
+   real product of the same kind ("the Ferrari F40's cabin" for a fictional supercar's cabin). Never a
+   rubric you wrote. Freeze it: every round is judged against the same photos.
+2. **Render the fixed inspection set in the real runtime** (the set per kind is below). Same cameras every
+   round — the tool owns them; never hand-pick flattering angles.
+3. **Gate on the executable asserts first.** Every blocking assert the tool prints must pass. Fix
+   failures now; a critic on a car that fails its asserts is wasted.
+4. **Look — yourself — at every sheet.** Open each sheet the tool lists, in order, beside the matching
+   bar photo. Each sheet carries a LOOK question; answer it in `LEDGER.md` per sheet: `PASS` or `FAIL`
+   plus every defect you see. Do not skip a sheet because its numbers passed.
+5. **Get a blind verdict.** If your client can spawn subagents, spawn a FRESH one that never saw the build
+   and give it only: the sheets at the size the tool wrote them (copied into a neutral folder, renamed
+   `sheet-01.jpg`…, nothing in a name or path that says which item, round or author), the bar photos,
+   and the critic brief below. A sheet the critic says it cannot judge (too dark, hidden, too small) is
+   a FAIL of the inspection, not a pass: fix the render, not the verdict. If you
+   cannot spawn one, re-read only the brief and the images and judge again from cold, and say in the
+   report that the critic was not independent.
+6. **Fix every defect the asserts, your look and the critic name; re-render; re-judge.** Keep the best
+   render set (the ratchet): a round replaces it only when it wins on every sheet it touches.
+   **Two rounds per approach, then diagnose**: name each remaining defect tunable or structural, and for a
+   structural one ask what the bar has that this approach cannot produce, and whether you can reuse the
+   bar's own machinery (a real licensed mesh of the car, the platform's seat rig and H-points, the
+   engine's own fold) instead of imitating it. Change approach; do not tune a third round.
+7. **Exit, and say which exit.** `PASS`: every blocking assert passes, every sheet PASS in your look, and
+   the critic picks `MATCHES` on every sheet with an overall score ≥ 8. Anything else is not a pass: a
+   round or budget limit is a **brake** — do not publish or list; report the item blocked with its top
+   unresolved defect and the sheet that shows it.
+
+## Updating or re-checking a listed item
+
+A listed item is never re-judged when a gate is added, so a car on sale can be running on a record that
+predates the gate that would fail it. **Before and after you touch a listed car, run
+`check_listed_items({ itemIds: [<id>], rerun: true })`.** STALE (a current gate never ran) or FAIL means
+the car is on sale broken: run this loop on it, stage a new version of the SAME item, pass hosted visual
+QA on that version, and until then delist it (`delist_item`). With no ids it re-checks every listed
+vehicle.
+
+## The vehicle inspection set (fixed; `preview_vehicle` renders all of it)
+
+`preview_vehicle({ target: <dir> })` for a candidate, `preview_vehicle({ item: <id> })` for a published
+car. Occupants and the inspection set are ON by default; `occupants: false` / `inspection: false` are for
+a quick iteration only and are never a gate result. It writes `<out>/inspection/index.json` and these
+sheets (≈1280 px JPEGs, one LOOK question each):
+
+| Sheet | What is in it |
+| --- | --- |
+| `exterior-day` | 8 angles: front, front-left 3/4, left, rear-left 3/4, rear, rear-right 3/4, right, front-right 3/4 |
+| `exterior-night` | the same 8 at night, low beam on |
+| `lamps-night` | every lamp function lit: high beam, fog, brake, reverse, each indicator front and rear, hazards |
+| `wheels` | each wheel close-up, low and square-on |
+| `panels-open` | every door and lid at full open |
+| `seat-<seat>` | **every seat occupied**, each from first person, through the side glass, over the shoulder, through the windscreen |
+| `seat-<seat>-detail` | the same occupant: cutaway, head to roof, hips, feet, door open |
+| `driver-steering` | the driver steering left / centre / right: hands view and first person |
+| `stillness` | three frames 0.3 s apart of every occupant's hands |
+| add-ons | every add-on fitted: `preview_vehicle({ target or item, addon: [<dir>] })` per part, its contact sheet |
+
+What a PASS looks like, per occupant: torso at a normal driving recline (not lying back), thighs about
+level (knees not at the chest), head clear of the roof and not wedged in the seat wings, feet on the
+pedals or floor, nothing through the bodywork; the driver's hands **on the rim at about 9 and 3 and
+turning with it** at both locks; fingers and hands identical across the stillness frames (any twitch or
+"grasping" is a FAIL). The blocking asserts behind those: `vehicle.occupants.torso_angle`, `knees_up`,
+`head_in_wings`, `head_clearance`, `hips_on_seat`, `feet_on_floor`, `penetration`,
+`hands_on_wheel_steering`, `hands_follow_wheel`, `hands_at_nine_and_three`, `fingers_still`,
+`hands_still`, `seat_rig_warnings` (the seat rig logged a rim out of reach and parked a hand in the lap), and `preview.inspection.complete` (a sheet with a frame missing is not an inspection).
+When an occupant assert fails, fix the cabin (seat H-point, cushion, footwell, wheel position and reach:
+`read_skill({ name: "helix-vehicles", reference: "cabin" })`), never the threshold.
+
+## Other kinds
+
+The loop is the same; the inspection set comes from the kind's own tools.
+
+- **Avatars** (`helix-avatars`, `helix-avatar-qa`): bar = the reference sheet or photos of the character
+  at front, side, back and 3/4; inspection = the visual-QA turnaround, the walk frames and the
+  Marketplace preview walk, on both base bodies where relevant.
+- **Wearables, props and other items** (`helix-assets`): bar = product photos at matched angles;
+  inspection = the `visual_qa_item` frames (fitted on the body or placed in the scene).
+- **Worlds** (`helix-world-qa`): bar = the named reference art or a comparable published world;
+  inspection = the fixed-camera screenshots and the mobile frames from the QA pass, plus frame time.
+
+## Critic brief (give it verbatim with the sheets and the bar photos)
+
+> You are judging renders of a product against photos of the real thing. You did not make it and you do
+> not know who did. For EACH sheet, in order: (1) first write `MATCHES` or `DOES NOT MATCH` the reference
+> — decide before you write anything else; (2) list every visible defect: wrong shape or proportion,
+> missing or extra parts, wrong colour or material, anything floating, clipping, see-through, black or
+> glowing where it should not; for any seated person, posture (reclined, knees up, head jammed against
+> the roof or wedged in the seat wings), hands not on the steering wheel or not turning with it, fingers
+> that change between frames, feet not on the floor or pedals; (3) score the sheet 0–10, where any
+> posture, hands or fingers defect caps the score at 3. Then give an overall score 0–10 and the three
+> defects that matter most, each with the sheet that shows it. Be harsh: you are protecting a buyer.
+
+Record the critic's picks, defects and scores per round in `LEDGER.md`, and keep its raw answer.

package/skills/helix-multiplayer/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: helix-multiplayer
+description: Design HELIX multiplayer against what the declarative rule DSL can actually express — and recognise early when a mechanic falls outside it, before it is half-built. Use for any shared-space or shared-game world, for converting a single-player world to multiplayer, and whenever a proposed mechanic involves hit detection, pathfinding, hidden information, persistence or physics.
+---
+
+# HELIX Multiplayer
+
+Multiplayer on HELIX is **declarative and server-authoritative**. You declare state and
+`when`/`if`/`then` rules as data in `helix.json`; a platform-owned room interprets them at a
+fixed 20 Hz. **Your world ships no server code.** There is no server file to write, and no
+place to put one.
+
+That is a genuine constraint, not a temporary gap. This skill exists so you find the edge
+of the DSL during design, not after you have built three-quarters of a mechanic it cannot
+express.
+
+## Read the contract, do not reconstruct it
+
+`read_doc("multiplayer-world")` is the hub. `read_doc("multiplayer-logic")` is the full
+grammar — 17 rule events, 25 effects, the expression language, the caps. `list_templates`
++ `read_template` give you complete worked worlds. **Every verb, op and event you write is
+validated at publish; one that is not in the grammar is rejected with a did-you-mean.**
+Do not author the block from memory.
+
+This skill covers what those docs deliberately do not: the boundary, and what to do at it.
+
+## The capability boundary
+
+### Expressible today
+Shared numbers/strings/booleans/vec3/refs/lists/counterMaps · per-player and per-room state
+· zones (enter / exit / inside, static or entity-attached) · timers, keyed or room-scoped ·
+a phase state machine with late-join policy · server-authoritative entity motion
+(`linear`/`orbit`/`seek`/`waypoints`) · client-hosted entities with ownership transfer ·
+networked physics (dynamic rigid bodies, authority-transfer or dual-sim) · turn order and
+elimination · teams · server→client broadcasts and client→server validated actions ·
+proximity or global voice with channels · `playerContact` at a radius — the tag primitive.
+
+### Not expressible — and the DSL will not tell you nicely
+| You want | Why it cannot be declared | What to do instead |
+| --- | --- | --- |
+| "in front of me", a facing cone, a direction vector | There is **no vec3 arithmetic.** Vec3 exists only as a literal, `distance`, and `randomPoint`. No dot, cross, normalise, add or subtract. | Reduce to a distance test (`playerContact`, a zone), or resolve client-side and send a declared `action` the rules validate. |
+| Raycast, hitscan, line of sight, cover | No raycast primitive exists at any layer of the DSL. | Client detects, sends `action`; the rule validates distance + cooldown + phase before applying. Accepts that the client is trusted about *aim*, never about *outcome*. |
+| Navmesh pathfinding, obstacle avoidance, "decide" AI | `seek` is a straight line. Navigating *around* things is not in the grammar. | `authority: "owner"` entity, simulated client-side. Spoofable by design — never let it write another player's state. |
+| Progress that survives the session — currency, inventory, unlocks | Room state is per-instance and dies with the room. | `Helix.dataStore` (get/set/delete/list). **No multi-key transaction** — design so no two keys must move together. |
+| Fog of war, hidden roles, a private hand, secret objectives | **Every value in room state is broadcast to every client.** A "hidden" playerVar is readable in devtools by every player in the room. There is no per-player-private state. | Redesign to open information, or keep the secret client-side and accept it is unenforceable. Do not ship a social-deduction game on this and call the secret secure. |
+| Server-authoritative hit resolution | Follows from no raycast + no vec3 math. The server cannot independently confirm a hit. | The `claimHit` pattern: a declared action carrying the target ref, validated in the rule for distance, cooldown and phase, then writing through `{ref: action.args.target, var: "health"}`. Cheat-*resistant*, not cheat-proof. Say which you have. |
+
+Full construct-by-construct map with the escape hatch for each:
+`references/dsl-capability-map.md`.
+
+## The three escape hatches, in order of preference
+
+1. **A declared `action`.** Client sends intent, the server validates args and applies the
+   consequence in a rule. **This is the cheat-resistant path and the correct default for
+   anything that affects another player.**
+2. **An `authority: "owner"` entity.** A client simulates and uploads; the server
+   sanity-checks `maxSpeed` and relays. The escape hatch for motion the server cannot
+   compute. Spoofable — never use it as an authority over other players.
+3. **Redesign the mechanic.** Usually the right answer for hidden information and for
+   precise hit resolution. Cheaper than a half-working version of a game the platform
+   cannot host.
+
+## The cross-player write firewall — a publish-time error, not a runtime one
+
+Publish **statically blocks** owner-entity logic from any cross-player write **or read**:
+no `set`/`add`/`teleport`/`respawn`/`destroyEntity`/collection mutation/ownership
+verb/keyed timer/`broadcast` aimed at another member, and no dereferencing a client-supplied
+ref to *read* another member's var. This fails the publish, not a code review. Design around
+it up front.
+
+## The #1 conversion bug — client-side teleport
+
+A client that moves its own body across the map trips the room's movement gate. The gate
+holds the seat's last plausible position and **never self-heals**: you keep playing locally,
+and every other player sees you frozen or vanished at the old spot. **Solo testing cannot
+surface this.**
+
+Every kill-plane, checkpoint, round reset, portal, out-of-bounds handler and "play again"
+flow becomes a server `respawn`/`teleport` effect. Round resets are one rule
+(`forEachPlayer` → `respawn`), never a broadcast each client answers by teleporting itself
+— that is one copy of the bug per player.
+
+**Artifact check.** Every local transform write must be inside a single-player branch:
+
+```bash
+grep -nE "\.(teleport|respawn)\(" src/*.ts src/**/*.ts
+```
+
+Each hit is either inside `if (!mp.room) { … }` or it is a bug. `source-audit.mjs` runs this
+and fails on an unguarded hit in a world whose manifest declares `multiplayer`.
+
+## Verify with two clients — a delta assertion, not a final-state check
+
+Authority bugs are invisible solo, and a final-state check passes on a disconnected client.
+Assert the **change**, in the *other* window:
+
+```js
+// A and B are two browser contexts on the built preview, both joined.
+const before = await B.evaluate(() => window.__helixMpProbe.remote(0).position.z);
+await A.evaluate(() => window.__helixMpProbe.requestRespawn());   // triggers the SERVER rule
+await expect.poll(() => B.evaluate(() => window.__helixMpProbe.remote(0).position.z))
+           .toBeGreaterThan(before + 0.5);                        // B saw A move. Magnitude, not truthiness.
+```
+
+Expose `window.__helixMpProbe` from world code behind a query param, the same pattern
+`world.ready()` and `screenshots.register()` use — a no-op during normal play. Without a
+probe you are asserting on pixels, which cannot distinguish "moved" from "repainted".
+
+**The gate:** the artifact is the test's exit code plus both screenshots, written to
+`qa/mp-two-client/`. A passing description of a two-window test is not the test.
+
+## Voice is on by default
+
+Every multiplayer world ships voice unless it has a reason not to. `scaffold_world` already
+declares `voice.proximity` and writes the fail-soft join. A deliberately silent world opts
+out by removing **both** the permission and the block.
+
+```ts
+if (mp.room) {
+  try { if (await Helix.voice.join()) mp.attachVoice(Helix.voice, manifest.multiplayer.voice); }
+  catch (err) { console.info('voice unavailable:', err); }   // never blocks play
+}
+```
+
+Tuning lives in the manifest `multiplayer.voice` block, not in code. Declare
+`"spatial": true` when *presence* is the product — social spaces, horror, hide-and-seek,
+stealth. Skip it for announcer-shaped or competitive-callout voice. Channels are
+**exclusive**: a player is in the ambient space or in exactly one channel. Mic behavior
+(mode, device, volumes, mutes) belongs to the player via the platform tablet — **a world
+never renders mic UI.**
+
+## Rules that bite
+
+- **It must work solo.** Guests, standalone and failed joins all still play. The facade
+  sets up your local player unconditionally and layers multiplayer on only when a join
+  succeeds. Gate any "needs 2 players" logic explicitly.
+- **Read state through the typed accessors, fresh each frame** — `room.vars.num('x')`,
+  `room.me.str('team')`, `room.player(id)`, `room.phase()`. Colyseus maps are mutated in
+  place: copy values you cache, never alias. Guard against the pre-first-patch empty state.
+- **Skip your own `sessionId`** when spawning remotes.
+- **Mirror `maxSpeed`** between the DSL and the `EntityScene` options — the reconcile clamp
+  reads the client copy.
+- **`maxReplicas` is a real budget** (each replica is a full character); keep it equal to
+  `maxPlayers`. 2–8 is the sweet spot. `uploadHz: 20` caps `maxPlayers` at 12; the platform
+  caps concurrent players per room at 24 regardless.
+- **Never call `room.uploadEntity` directly** — register through `EntityScene`.
+- **Gestures replicate by default.** Trigger them from input handlers, never from
+  replicated-state observers, or every client fires its own copy.
+- **The per-tick evaluation budget is static.** A too-large `forEach` fan-out or nested
+  `aggregate`/`nearest*` fails publish before it ever runs. Simplify or spread across ticks.

package/skills/helix-multiplayer/references/dsl-capability-map.md

@@ -0,0 +1,107 @@
+# The DSL capability map
+
+A design-time lookup: can the declarative rule DSL express this, and if not, which escape
+hatch does it take. The authoritative grammar is `read_doc("multiplayer-logic")` — this file
+is the judgment layer on top of it.
+
+Read the middle column as the *mechanism*, not as a rule of thumb. An agent that knows why
+a thing is impossible handles the case this table does not list.
+
+## Expression language — what you can compute in an `if`
+
+| Available | Notes |
+| --- | --- |
+| `+ - * /` | **numbers only** |
+| `== != < <= >= >` | `==`/`!=` on same-typed scalars (not vec3); ordering ops require numbers |
+| `and` / `or` / `not` | |
+| `distance(a, b)` | the **only** vec3 operation that produces a number |
+| `randomPoint(min, max)` | the only op that produces a vec3 |
+| `playerCount` · `random` · `now` · `timeInState` | leaf generators |
+| `aggregate` (`count`/`sum`/`min`/`max`/`avg`/`argmax`/`argmin`) over players, a zone, or an entity kind | with an optional `where` filter |
+| `timerRemaining` | |
+| `listLength` · `listAt` · `count` · `listCount` · `listIndexOf` | collections |
+| `controlledBy` · `hostLoad` · `sameRef` | ownership |
+
+**Not available at any depth:** vec3 addition/subtraction, dot, cross, normalise, length of
+a difference, angle between, min/max of two scalars, string concatenation, modulo, sqrt,
+trigonometry, nested collections, free-form JSON.
+
+The consequence that catches people: **you cannot compute a direction.** Every mechanic
+phrased as "in front of", "facing", "behind", "within a cone", "line of sight" reduces to a
+distance test or leaves the DSL entirely.
+
+## Mechanic → verdict
+
+| Mechanic | Verdict | Route |
+| --- | --- | --- |
+| Score, lives, teams, rounds | ✅ | `roomVars` / `playerVars` + rules |
+| Pickups, collectibles | ✅ | `spawnEntity` (server authority) + zone or `playerContact` |
+| Capture points, king of the hill | ✅ | zone `zoneInside` + `aggregate` over `zone:<id>` |
+| Checkpoints, obby, race | ✅ | ordered zones + a per-player checkpoint var + `respawn` |
+| Patrolling NPC, moving platform, homing pickup | ✅ | entity `motion: waypoints`/`seek`/`orbit`, `authority: "server"` |
+| Timed waves, day cycle, crop growth | ✅ | timers + `{op:"now"}` + phases |
+| Turn-based / board game | ✅ | `states` + `advanceTurn` + `eliminate` |
+| Cards, hand, inventory (in-session) | ✅ | `list` of flat records + `forEachInList` |
+| Ball, puck, bumper cars | ✅ | `physics` on an `authority:"owner"` kind; `claimOnContact` for one contested body, `dualSimOnContact` for player-driven bodies |
+| Tag / touch-based elimination | ✅ | `playerContact` at a radius |
+| Walkie-talkies, private calls, team radio | ✅ | `multiplayer.voice.channels` + `Helix.voice.setChannel` |
+| Enemy that paths around a wall | ❌ no pathfinding | `authority:"owner"` entity, client-simulated |
+| Shooting with server-confirmed hits | ❌ no raycast, no vec3 math | declared `action` + rule-side distance/cooldown/phase validation. Cheat-**resistant**. |
+| Melee arc / cone attack | ❌ no facing math | `playerContact` radius, or a client-detected `action` |
+| Fog of war, hidden roles, secret hand | ❌ all state is broadcast | redesign to open information, or keep it client-side and say plainly that it is unenforceable |
+| Saved currency, progression, unlocks | ❌ room state is per-instance | `Helix.dataStore` — **no multi-key transaction** |
+| Persistent world edits between sessions | ❌ | `Helix.dataStore`, reloaded on join |
+| Anti-cheat on client-simulated entities | ❌ by design | the server validates `maxSpeed` plausibility and nothing more |
+
+## Why "hidden information" is the hardest no
+
+Room state syncs to every connected client. A `playerVars` entry named `role` with value
+`"traitor"` arrives in every player's browser and is one devtools expand away. There is no
+per-recipient filtering in the broadcast path and no private channel for state.
+
+`broadcast` with `to: <ref>` or `to: {team: "..."}` targets a **message**, not state — so a
+one-shot secret *reveal* can be directed. That is enough for "you are the traitor, told
+once at round start" **only if** nothing in synced state ever encodes it afterwards. The
+moment a rule writes the role into a var to make a later rule work, it is public. Design
+accordingly, and never describe such a world as having secure hidden roles.
+
+## Entity authority — declare `motion` first
+
+- `authority: "server"` (default) — deterministic, cheat-proof, never freezes. Reach for it
+  first. Covers straight-line `seek`, `waypoints`, `orbit`, `linear`, `static`.
+- `authority: "owner"` — a client simulates and uploads; requires `maxSpeed`. The escape
+  hatch, spoofable by design.
+- `shared: true` + `ownerLifecycle: "hostMigrate"` — game-owned, host re-elected on leave.
+  This is how a swarm spreads its simulation across clients.
+
+Physics cross-field rules that publish enforces: a `physics` block **requires**
+`authority: "owner"`; `claimOnContact` ⇒ `transferPolicy: "takeover"`; `dualSimOnContact` ⇒
+`transferPolicy: "fixed"`; `collidesWith` names declared kinds. Cap: 8 physics kinds.
+
+## Caps — publish rejects an over-cap config with a precise message
+
+`roomVars`/`playerVars` 384 · `rules` 768 · effects per `then` 16 · `if` depth 8 / 64 nodes ·
+entity kinds 32 · entities per kind 256 · entity vars 64 · zones 256 · timers 192 · phases 64 ·
+events 256 · actions 256 · list `maxLen` 256 · counterMap keys 64 · record fields 8 · string
+`maxLen` 1024 · physics kinds 8 · enum values 64 · cascade depth 16 · `tickNodeBudget`
+100 000 (computed statically from rules × loop fan-out × cascade depth — the declaration caps
+were raised, this budget was NOT, and it binds long before any declaration ceiling).
+
+Nearing a cap is a design signal, not a tuning problem: a mechanic that wants hundreds of
+rules probably wants a phase machine, a collection, or a `forEach` instead.
+
+## Ordering semantics you will trip over
+
+Rules evaluate in **declared order**; effects within a `then` apply in order; later rules
+see earlier rules' writes within the same tick. Effects that fire secondary events
+(`transitionTo`, `spawnEntity`, `destroyEntity`, ownership verbs) queue and drain
+breadth-first **after** the primary rules. `varReached` is edge-checked once at the **end**
+of the rule phase and is not part of the cascade. Publish rejects cascades that could cycle.
+
+## Zone box sizing — the slip that costs an afternoon
+
+A `zones[]` box takes `size` as **full dimensions**. A `physics.shape` box takes
+`halfExtents`. They look identical and differ by 2×. `inspect_world` reads the declared
+zones from the bundle and checks each against real geometry — the only way to catch a kill
+band the pit floor misses or a checkpoint volume floating in empty space, because zones
+never render.