@hypersoniclabs/helix-mcp 0.2.4 → 0.2.12

package/skills/helix-vehicles/references/cabin.md

@@ -0,0 +1,225 @@
+# The cabin and its occupants
+
+A buyer spends most of their time looking at the cabin: from the driver's seat, through the
+windows, and with the doors open. Visual QA seats an adult avatar in every declared seat and
+judges it. Round 1's F40 shipped a placeholder cabin and spent seven versions (1.0.3–1.0.9) on an
+occupant model nobody had documented. Design the cabin once, against the rules below.
+
+## The quality bar
+
+Judge the cabin against **interior reference photos of the real car**: the dash from the driver's
+eye, the seats, the door cards, the pedal box and the steering wheel. Put `preview_vehicle`'s
+`cockpit` pose beside the matching photo, as for the exterior (the `appearance` reference). A
+blocky stand-in for any of these parts fails the bar, even when every assert passes.
+
+**Match the reference's interior *treatment*, not just "not a flat slab".** The bar is the real
+cabin's colour, material and style — a bare-black race interior with a black Momo wheel and red
+cloth buckets, a tan-leather GT with wood, whatever the car actually has. A finished but *generic*
+cabin (grey/tan plastic, plain wheel, featureless seats) fails the bar exactly as a flat slab does:
+round 7's F40 passed every assert and still read as a "generic grey/tan cockpit" against the
+F40's bare-black felt dash, black Momo wheel, red cloth buckets and exposed gated shifter, and the
+critic scored the interior 4. The gate is: **does this cabin read as the reference's cabin?** —
+the trim colour, the seat material, the wheel, the shifter and the dash finish, beside the photo.
+
+This is a **pass/fail gate** with a reference pair, not a taste call. The **interior finish gate**
+in `appearance` (section 4.4) is the concrete version — the bar (a legible binnacle with
+tach/speedo/turbo, real seat shells, a real dash and door cards, the controls present, all in the
+reference's colour and material) and the round-4 PASS/FAIL pair: the live 993's cabin passes
+(interior 8), the round-4 F40's flat grey slab fails (interior 5). Run it at the `cockpit` and
+dash poses before the first mint.
+
+Required interior parts (static ones merge into `bodyshell`, or a separate `cabin` node):
+
+| Part | Bar |
+| --- | --- |
+| Seat shells | The real seat's design and material: bucket, sports or bench shape, bolsters, headrest, upholstery or shell colour. Seat cushion and backrest are surfaces an occupant sits on, so model them where the H-point says. |
+| Dash and instrument binnacle | The real dash's shape and layout: binnacle, vents, centre console. |
+| Gauges | Legible dial faces at the cockpit pose: the real faces, numerals and needle positions in the atlas. A flat grey disc fails. |
+| Steering wheel (`steering`) | The real wheel's design: spoke count and shape, rim thickness, boss and badge. Origin on the column axis, at the hub. |
+| Pedals | Two or three pads (`pedal_throttle`, `pedal_brake`, `pedal_clutch`, or merged) where the real pedal box is. |
+| Gear lever and gate | Where the real one is (`gearshift` socket or node). |
+| Door cards | The inside of each door, on the door's own node, so an open door shows a finished panel. |
+| Floor, footwells, roof lining, firewall, pillars | Closed surfaces. A missing panel shows the road or the sky through the cabin. |
+
+Never fabricate a part the real car does not have; ship what the car has.
+
+## How the runtime seats an occupant
+
+- **One anchor: the H-point.** A seat socket (`seat_dside_f`, `seat_pside_f`, `seat_dside_r1`, …)
+  is the occupant's hip joint in the model frame. Declare it in the package's `mesh.sockets` and in
+  the GLB's `asset.extras.HELIX_vehicle.sockets` (the `host-manifest` reference), with the same
+  value in both.
+- **Everything is measured from the H-point**: the steering rim (`steering` socket; by default
+  about 0.38 m ahead, its lower edge 0.16 m above the hip so the thighs pass under), the pedals
+  (`pedal_throttle`, `pedal_brake`, `pedal_clutch`; by default about 0.84 m ahead and 0.26–0.32 m
+  below), the gearshift and the ignition.
+- **The occupant is fixed, never scaled**: about 0.78 m hip to crown reclined, a 0.86 m leg. The
+  rig puts the pelvis on the H-point, reclines 8–32° until the measured crown clears the roof by
+  40 mm, grips the rim with both hands (driver), and plants the feet on the pedals or the floor,
+  never closer than 0.32 m to the hip.
+- **`cabinFit` moves your seats** (engine 0.3.168 and later) when the drawn cabin cannot hold that
+  occupant. It raycasts the bodywork you draw, then, in this order:
+  1. moves the seat row **aft** until there is roof height to seat someone;
+  2. **lowers** the hip until the crown clears the measured ceiling by 40 mm, never lower than
+     0.12 m over the underbody. The ceiling is the roof's **inner surface** (the headliner), not
+     the outer skin: a thick roof panel is measured through, so a ~40 mm-thick shell does not read
+     its own thickness as headroom and squeeze the head against the lining (round 7's F40 read 2 mm
+     of real clearance where the fit had placed the crown 40 mm under the *outer* skin);
+  3. moves the steering wheel and pedals with the hip;
+  4. nudges the rim (kept ≥ 0.32 m from the hip, radius ≥ 0.08 m) and the pedals clear of the skin.
+
+  It does this silently in the live runtime: round 1's F40 had both seats moved 0.16 m aft and
+  nobody was told. A seat the shell cannot hold at all is **refused**, and nobody can sit there.
+- **`preview_vehicle` shows it** (occupants are on by default). Its CABIN FIT section prints, per seat,
+  your authored H-point, the H-point the runtime used, the move (aft, lowered), headroom and crown
+  clearance, plus rim and pedal moves and the runtime's warnings. The check
+  `preview.occupants.cabin_fit` **fails** when the runtime moved a seat more than 30 mm from its
+  authored H-point, or refused it, and names the H-point the runtime used.
+- **Design so that `cabinFit` moves nothing.** If it moved a seat, your cabin disagrees with your
+  H-point. If the runtime's H-point is right, declare it (move the seat socket everywhere it is
+  declared); otherwise open the cabin (roof, floor, bulkhead) so an adult fits where you authored
+  it. Never build the cabin
+  around where the runtime moved the occupant: round 1's F40 moved its bulkhead and seats to follow
+  a 0.16 m aft shift, and the cabin stopped matching the car.
+
+## The measured thresholds (visual QA, on the drawn occupant)
+
+| Check | Threshold |
+| --- | --- |
+| The engine seats occupants correctly (`engine_current`) | engine ≥ 0.3.169 |
+| Every declared seat boards with the real E key (`boarded`) | all seated |
+| Crown to the first surface above it (`head_clearance`) | ≥ 10 mm |
+| Buttocks above the cushion (`hips_on_seat`) | ≤ 0.12 m hovering, ≤ 0.02 m through the seat base |
+| Soles to the floor, sill or pedal pad (`feet_on_floor`) | between 0.05 m below and 0.30 m above |
+| Driver's nearest hand bone to the rim (`hands_on_wheel`) | ≤ 0.07 m, both hands |
+| Pelvis to the seat the engine says it is on | ≤ 0.03 m |
+| Torso angle, hip → neck base from vertical (`torso_angle`) | 5°–32° (warn outside 10°–28°). SAE J826: sedans 20–25°, sports 25–30° |
+| Thigh, hip → knee against horizontal (`knees_up`) | −25° to +35° (warn above +30°); the knee height over the hip and the hip and knee angles are printed |
+| Head held in wings (`head_in_wings`) | the car within 60 mm of the skull, below the crown, on **two or more** of back / left / right fails (one side, a plain restraint, passes) |
+| **Penetration** (`vehicle.occupants.penetration`, required) | A connected patch of body through one cabin mesh fails when at least 3 points are more than 8 mm deep over at least 4 cm², or more than 25 mm deep over at least 1.5 cm². A hand on the rim and a sole on a pedal fail only beyond 20 mm. Hair, ears and cloth flaps are not judged. |
+
+Warn only: `hips_sink_depth` beyond 0.10 m, `near_contact` beyond 1 mm. The critic then looks at
+the occupant frames (head clearance, seat contact, no clipping, the driver's hands on the rim),
+but only in a submitted or hosted visual-QA run, never in a preview.
+
+## Seat posture: how the occupant reads, and what to change in the GLB
+
+The fit checks above ask whether an adult fits. The three posture checks ask whether the **drawn
+avatar looks like a person sitting in the car**: round 8's F40 passed every fit check while both
+occupants sat laid back with their knees up and their heads in the seat wings. They are measured on
+the posed skeleton and skull (`preview_vehicle` prints each with its numbers),
+so none of them is a number you can declare. You change the *geometry* around the H-point. Measured
+on the live 993 (pass) against round 8's F40 (fail):
+
+| Check | 993 | F40 | What drives it |
+| --- | --- | --- | --- |
+| `torso_angle` | 12° / 12° | 20.5° / 20.5° (inside the band: this one does not fail) | headroom over the H-point |
+| `knees_up` | driver 3°, passenger 26° | driver 6°, **passenger 44°** (knee 0.23 m over the hip) | footwell depth and floor height under the dash |
+| `head_in_wings` | 133–207 mm on every side | driver **1 / 54 / 36 mm** back / left / right | headrest and wing shape at head height |
+
+**There is no seat-back-angle field.** The rig reclines the occupant from 8° to 32° only as far as
+the headroom over the H-point needs (crown 40 mm under the lining), then spreads it over the spine.
+A recline that reads too far back means the roof leaves too little height above the hip: the engine
+prints "the roof allows an H-point only X m above the measured floor where a seating package wants
+0.34 m" in the CABIN FIT warnings. Fix it with geometry, not a socket: sink the seat bucket into the
+floor pan (lower the cushion, keep the H-point on the cushion top), raise the roof lining over the
+seat (the real car's roof stays, its inner lining and any roll-hoop trim can give), and model the
+backrest leaning at the torso angle the preview prints, so the back meets the surface it is
+resting on.
+
+**Where the seat goes.** Place the `seat_*` socket (the hip joint) on the cushion's **top surface**
+at the point where the pelvis rests, about 0.12–0.15 m ahead of the backrest face, centred
+laterally between the bolsters, and the same value in `mesh.sockets` and the GLB
+`HELIX_vehicle.sockets`. `hips_sink_depth` warns when it is more than 0.10 m under the cushion top,
+which is what a socket at the seat's floor mount rather than at the cushion produces. Cushion height:
+the runtime asks for an H-point 0.34 m above the floor pan under it; the 993 passes at 0.25 m, the
+F40 had 0.21 m ("seated race-low with a shallow footwell": the legs lie out along a bench and the
+roof forces the recline).
+
+**`knees_up` fix (the thigh is rising to the knee).** The sole lands on the first up-facing
+surface under a point at least 0.32 m ahead of the hip, so the thigh angle is set by how far below
+the hip that floor is and how far ahead it starts. The passenger's footwell needs a floor pan at least
+0.25 m under the H-point (the runtime asks for 0.34 m) and a pedal-box depth near 0.26 m, open for about 0.6 m ahead of the hip; a dash, glovebox or bulkhead closer than that
+shortens the shin and folds the knee up to the chest (the F40 passenger had 0.275 m of shin travel
+and a knee angle of 92°; the 993's is 120°). Deepen the footwell (floor pan lower, dash and footwell
+bulkhead further forward, or the H-point further aft), or fit a footrest ramp the sole can land on
+lower than the toe board.
+
+**`head_in_wings` fix.** A head against one headrest is normal; a head in a pocket is not. Keep the
+inner faces of the wings at head height at least **0.15 m either side of the seat socket's x**
+(a skull is about 0.17 m wide, so that leaves 60 mm), and the headrest face behind the head no
+closer than the avatar's own head-back (the check reports the mesh it is against). Either lower
+the wings below the ear line (the head bone's height, about 0.55 m over the cushion top) or open
+them out; a separate `seat_*_headrest` mesh keeps the wing, ear and shoulder shapes
+under your control. The real F40's seat is a pocketing race shell: keep its look, widen the
+pocket enough that the avatar's head is not wedged in it.
+
+Preview, read the three posture lines and the `seat-<seat>` inspection
+sheets (first person, side glass, over the shoulder, windscreen), fix the geometry, and re-run. The posture checks are
+measured on the QA account's avatar, so judge the angle values (they are the skeleton's) and treat
+the head gaps as ±10 mm.
+
+## A rear row (2+2, four, five, seven seats)
+
+Rear seats are the long pole: a four-seat build spent about 4.7 of its 8.5 hours on them because
+each try was a 15-minute hosted run. Design the rear row against these numbers and iterate with
+`check_vehicle_cabin` (seconds, offline), not with versions.
+
+- **Declare every seat you model.** `seat_dside_r1` / `seat_pside_r1` (`r2` for a third row) are
+  hip sockets exactly like the front pair, in `mesh.sockets`, the GLB manifest **and**
+  `specialty.module.seatVars`. A seat the package does not declare cannot be boarded and is not judged.
+- **Rear H-point against the roofline.** The roof slopes down over the back row, so the rear hip is
+  the one that comes out race-low. Height of the hip over the floor under the feet: a saloon or
+  wagon 0.28–0.34 m, a 2+2 coupe 0.20–0.26 m; the runtime asks for 0.34 m and warns below, and
+  `check_vehicle_cabin` warns under 0.15 m and fails under 0.08 m. Crown clearance is the roof's
+  inner surface over the hip minus about 0.71 m (reclined crown over hip): keep it at least 30 mm
+  (warn) and never under 10 mm. Gain headroom by raising the lining over the rear seat or sinking the
+  cushion into the floor pan, not by dropping the socket onto the floor.
+- **Knee clearance to the front seat back.** The rear knee sits about 0.43 m ahead of the hip and
+  at about the hip's height. Put the rear hip roughly 0.75–0.90 m behind the front hip and slim the
+  front seat backs where the knees meet them; the knee must clear them by at least 15 mm.
+- **A rear footwell under the front seats.** Rear feet are planted 0.6–0.84 m ahead of the rear hip
+  (the fit picks the clear reach), which is under the front seat bases. Leave at least 0.11 m of free
+  height over the rear floor under each front seat base (a foot is 90 mm thick, plus 20 mm), open the
+  floor pan there, and keep the front seat base up on rails rather than boxed to the floor.
+- **Tunnel clearance for rear feet.** Each foot stands 0.11 m inboard and outboard of its hip's x
+  (a hip at x 0.30 puts the inboard foot at x 0.19). The tunnel or console sides, and the inner
+  faces of the front seat bases, must stay at least 15 mm outside that foot and the shin above it.
+  Narrow the tunnel skirt aft of the front seats or move the rear hips outboard.
+- **The loop for a rear row:** edit the cabin, run `check_vehicle_cabin` (per seat: H-point, head,
+  knee, shin, foot, seat ahead, tunnel, footwell, each PASS / WARN / FAIL with millimetres; also
+  `validate_vehicle` with `cabin: true`), repeat until no rear row FAILs and the WARNs are
+  deliberate, then confirm once with `preview_vehicle({ target: <dir> })`, which boards and seats
+  an avatar in **every** seat, rear included. A rear seat is granted locally in the preview's page
+  (the stand-in room has no rear seats), so the preview is single-client; the fit, the occupant rig and
+  every gate are the real ones. The legs `check_vehicle_cabin` seats are the runtime's canonical
+  legs in clothes, so trust a FAIL, and treat a WARN of a few millimetres as the real avatar's
+  margin.
+
+## The loop
+
+1. Model the cabin to the reference photos, with the H-points where the real seats put the hips.
+2. `check_vehicle_cabin({ target: <dir> })` after each cabin edit: it judges every declared seat
+   offline in seconds. Fix every FAIL; for a rear row see the section above.
+3. `preview_vehicle({ target: <dir> })` seats an avatar in every seat (rear included), measures every
+   threshold above, prints the CABIN FIT moves, and writes the `seat-*`, `driver-steering` and
+   `stillness` inspection sheets. Open every one (`helix-gauntlet`).
+   **Hands.** With the wheel held at left lock, centred and right lock, both of the driver's hands
+   must stay ON the rim — nearest finger joint ≤ 30 mm from the rim's ring and the grip ≤ 90 mm from
+   the tube (`hands_on_wheel_steering`; a hand dropped to the thigh beside the bottom of the rim is
+   ~50 mm away and fails), one hand must turn the wheel, travelling
+   round with it by at least a quarter of its turn while the other holds and lets the rim slide (push-pull;
+   `hands_follow_wheel` — two hands that stay put while the wheel turns fail), sit at about 9 and 3 when centred (`hands_at_nine_and_three`: left
+   7:30–11:30, right 0:30–4:30), and every occupant's finger joints must move ≤ 4 mm and turn ≤ 3° and hands ≤ 12 mm
+   over a held window (`fingers_still`, `hands_still`). The seat rig must log no `[vehicle-seat]` warning
+   (`seat_rig_warnings`: it logs a rim no hand can reach, and parks that hand on the thigh). A hand that cannot reach the rim rests on the
+   thigh, which fails: move the wheel toward the driver (the steering column's rake and reach) or the
+   seat forward, as the real car's dimensions allow.
+4. Fix the geometry until `cabin_fit` passes (no seat moved or refused) and every threshold
+   passes. Design the cabin once against these numbers; never iterate published versions against
+   the hosted gate.
+5. Compare the `cockpit` pose with the interior reference photos. Fix what does not match.
+
+A car too low for an adult (some real supercars are) still keeps its real roof height. Lower the
+seat and recline as the real car does. If a gate measurement is wrong for a correct car, follow
+"When the gate, not the car, is wrong" in the `qa` reference.

package/skills/helix-vehicles/references/host-manifest.md

@@ -0,0 +1,174 @@
+# The host manifest: `asset.extras.HELIX_vehicle`
+
+A vehicle GLB states what it is, and where its sockets are, in **one** object at the glTF
+document's **`asset.extras.HELIX_vehicle`**. The backend reads that exact location, and only that
+location, when the item is minted. From it, and from the vehicle package, it derives the car's
+slot board:
+
+- the host kind (`vehicle`);
+- the sockets add-ons mount on;
+- the node names add-ons may hide;
+- the tunable paths performance parts may change (these come from the package's physics).
+
+**The board is derived once, at mint.** A car minted without the manifest is published as a silent
+non-host: the upload reports `verification.ok`, but the customizer shows "0 compatible", and no
+wheel, wing, exhaust, ECU or brake part can ever fit it. A later Package Version does not
+re-derive the board. Round 1's F40 lost its whole add-on set this way: the manifest was written to
+the scene's `extras` and the root `extras`, and `asset.extras` was empty.
+
+The runtime also reads the manifest from scene `extras` or root `extras`, which is why a manifest
+in the wrong place still "works" in a local preview. Write it to `asset.extras` only. If it is in
+more than one place, the runtime warns.
+
+## The shape
+
+```json
+"asset": {
+  "version": "2.0",
+  "generator": "…",
+  "extras": {
+    "HELIX_vehicle": {
+      "version": 1,
+      "class": "supercar",
+      "mass": 1100,
+      "wheelRadius": 0.3236,
+      "sockets": {
+        "seat_dside_f": [0.33, 0.29, -0.10], "seat_pside_f": [-0.33, 0.29, -0.10],
+        "steering": [0.32, 0.64, 0.34], "engine": [0, 0.43, -1.50], "exhaust": [0, 0.30, -2.20],
+        "cam_cockpit": [0.33, 0.94, -0.16], "cam_chase": [0, 0.93, -6.9], "cam_hood": [0, 0.81, 1.86],
+        "wheel_lf": [0.80, 0.32, 1.22], "wheel_rf": [-0.80, 0.32, 1.22],
+        "wheel_lr": [0.80, 0.33, -1.20], "wheel_rr": [-0.80, 0.33, -1.20],
+        "headlight_l": [0.59, 0.50, 1.75], "headlight_r": [-0.59, 0.50, 1.75],
+        "taillight_l": [0.52, 0.45, -1.94], "taillight_r": [-0.52, 0.45, -1.94],
+        "boot": [0, 0.65, -1.63], "bonnet": [0, 0.54, 1.30]
+      }
+    }
+  }
+}
+```
+
+- `sockets` maps each socket id to a **position in the model frame** (metres, +X left, +Y up,
+  +Z forward), measured off your final GLB. The numbers above are an example only.
+- Declare **every seat** (`seat_*`, the H-point), the four `wheel_*` hub centres, `steering`,
+  `engine`, `exhaust`, the lamp sockets you have, and `boot` / `bonnet` if wings or bonnets will
+  bind to them. A socket the manifest omits is not on the board, so no add-on can mount there.
+- Keep these positions equal to the package's `mesh.sockets`. Change both together.
+- The node list on the board is read from the GLB's own nodes, not from the manifest. Every node an
+  add-on hides (`rim_*`, `exhaust`, a wing) must exist as a node.
+- Socket and node names must match `[A-Za-z0-9_.-]{1,64}`. At most 128 are kept.
+
+## Every slot's bind root must exist in the GLB
+
+A manifest socket is a position, but the runtime composes an add-on against **nodes**. A meshed
+add-on authored in the host frame carries `helixMeshFrame.bind { socket, root, matrix }`, and the
+runtime requires all three of these in the car's GLB before it draws anything:
+
+- a node that resolves to `bind.socket` (a lid socket like `boot` or `bonnet` needs a node named
+  for it, the lid itself or an empty node on its hinge line);
+- a node named `bind.root` (the host-frame root, `vehicle_root` by convention: an **empty node at
+  the origin that is the parent of every top-level node**);
+- that root must contain the mount node.
+
+When one is missing the runtime throws while composing the car: the car is **never presented**,
+the page raises no error, and a preview hangs until its timeout. Round after round lost an hour to
+this (a wing bound to an absent `vehicle_root`; a missing `boot` node). Add the empty root before
+you export, and keep every lid node under it:
+
+```text
+vehicle_root            (empty, identity transform)
+├─ bodyshell
+├─ boot                 (origin on the hinge line)
+├─ bonnet
+└─ …every other top-level node
+```
+
+`validate_vehicle({ vehiclePackage, glb })` refuses a host that offers a `boot` or `bonnet` socket
+and lacks any of the three:
+
+- `HOST_BIND_ROOT_MISSING`: no `vehicle_root` node;
+- `HOST_BIND_MOUNT_NODE_MISSING`: the offered lid socket has no node to mount on;
+- `HOST_BIND_ROOT_NOT_OWNER`: the lid node is outside `vehicle_root`.
+
+The same codes come back from `check_vehicle_host({ itemId })`, which also reads **every published
+add-on on the car's rail** against the car's own GLB (the message names the node, the slot and the
+add-on), from `check_vehicle_addon` against each host, and from `preview_vehicle` before it opens a
+browser. A preview whose page logs `[helix-vehicle] composition failed` (or raises any page error)
+before the car appears now fails at once with that message.
+
+## Writing it
+
+Patch the **final** GLB, after every other tool has run. `gltf-transform` keeps `asset.extras`;
+other optimisers may drop it.
+
+**Node (no dependencies).** This rewrites the JSON chunk in place:
+
+```js
+// node write-host-manifest.mjs model.glb manifest.json
+import { readFileSync, writeFileSync } from 'node:fs';
+const [, , glbPath, manifestPath] = process.argv;
+const glb = readFileSync(glbPath);
+const jsonLen = glb.readUInt32LE(12);
+const gltf = JSON.parse(glb.subarray(20, 20 + jsonLen).toString('utf8'));
+const rest = glb.subarray(20 + jsonLen); // the BIN chunk, untouched
+gltf.asset.extras = { ...(gltf.asset.extras ?? {}), HELIX_vehicle: JSON.parse(readFileSync(manifestPath, 'utf8')) };
+for (const holder of [gltf, ...(gltf.scenes ?? [])]) if (holder.extras) delete holder.extras.HELIX_vehicle;
+let json = Buffer.from(JSON.stringify(gltf), 'utf8');
+json = Buffer.concat([json, Buffer.alloc((4 - (json.length % 4)) % 4, 0x20)]);
+const header = Buffer.alloc(20);
+header.writeUInt32LE(0x46546c67, 0); header.writeUInt32LE(2, 4);
+header.writeUInt32LE(20 + json.length + rest.length, 8);
+header.writeUInt32LE(json.length, 12); header.writeUInt32LE(0x4e4f534a, 16);
+writeFileSync(glbPath, Buffer.concat([header, json, rest]));
+```
+
+**Python (inside Blender, after `bpy.ops.export_scene.gltf`).** Blender writes object and scene
+custom properties to node and scene `extras`, never to `asset.extras`, so patch the exported file:
+
+```python
+import json, struct
+
+def write_host_manifest(glb_path, manifest):
+    data = open(glb_path, 'rb').read()
+    json_len = struct.unpack_from('<I', data, 12)[0]
+    gltf = json.loads(data[20:20 + json_len])
+    rest = data[20 + json_len:]
+    gltf.setdefault('asset', {}).setdefault('extras', {})['HELIX_vehicle'] = manifest
+    for holder in [gltf, *gltf.get('scenes', [])]:
+        holder.get('extras', {}).pop('HELIX_vehicle', None)
+    body = json.dumps(gltf, separators=(',', ':')).encode('utf8')
+    body += b' ' * ((4 - len(body) % 4) % 4)
+    header = struct.pack('<III', 0x46546C67, 2, 20 + len(body) + len(rest)) + struct.pack('<II', len(body), 0x4E4F534A)
+    open(glb_path, 'wb').write(header + body + rest)
+```
+
+**gltf-transform (script).**
+
+```js
+import { NodeIO } from '@gltf-transform/core';
+import { ALL_EXTENSIONS } from '@gltf-transform/extensions';
+const io = new NodeIO().registerExtensions(ALL_EXTENSIONS); // KTX2 textures need the extensions
+const doc = await io.read('model.glb');
+const asset = doc.getRoot().getAsset();
+asset.extras = { ...(asset.extras ?? {}), HELIX_vehicle: manifest };
+for (const holder of [doc.getRoot(), ...doc.getRoot().listScenes()]) {
+  const { HELIX_vehicle, ...rest } = holder.getExtras(); // keep it in asset.extras only
+  holder.setExtras(rest);
+}
+await io.write('model.glb', doc);
+```
+
+## Proving it
+
+- `validate_vehicle({ vehiclePackage, glb })` and `publish_vehicle` refuse, before any mint:
+  `HOST_MANIFEST_MISSING` (none anywhere), `HOST_MANIFEST_MISPLACED` (only in scene, root or node
+  `extras`; the message says where), `HOST_MANIFEST_EMPTY` (no valid socket),
+  `HOST_MANIFEST_SOCKET_INVALID` (a value that is not a finite `[x, y, z]`),
+  `HOST_MANIFEST_SOCKET_NAME_INVALID` (a name the backend would drop),
+  `HOST_MANIFEST_SOCKET_NODE_MISSING` (a `socketNodes` entry naming no node) and
+  `HOST_MANIFEST_DIVERGENT` (a scene or root copy that differs from the asset copy: the runtime
+  would read one and the backend the other), and the bind-root codes above
+  (`HOST_BIND_ROOT_MISSING`, `HOST_BIND_MOUNT_NODE_MISSING`, `HOST_BIND_ROOT_NOT_OWNER`).
+- After the mint, `publish_vehicle` reads the board back (`readBack.board`: host kind, sockets,
+  paths and grants), and `check_vehicle_host({ itemId })` must report
+  `hostKind vehicle` with non-zero sockets, nodes and tunable paths. If it does not, see section 2
+  of the `publish` reference: the board is fixed at mint.