@hypersoniclabs/helix-mcp 0.2.4 → 0.2.12

package/docs/vehicles.md

@@ -0,0 +1,727 @@
+# HELIX Vehicle Contract
+
+The rules a drivable vehicle item and its add-ons must meet to work the first time on the live
+platform. Every rule here was checked against the engine, backend and CLI code as of October 2026.
+Each one names the failure it prevents. The workflow that applies these rules is the
+`helix-vehicles` skill: run `get_started({ kind: "vehicle" })`.
+
+**Vocabulary.**
+
+- **Vehicle item**: a universal item of kind `vehicle`. It is one GLB plus a **vehicle package**,
+  which is `helix.vehicle-package/2` JSON.
+- **Continuum Package**: the sealed, content-addressed closure that holds the item's model, its
+  package JSON and its audio. Every item that is drawn, listed or sold is *pinned* to an exact
+  Package Version.
+- **Add-on**: a separate item of kind `add_on`. It fits a vehicle slot and is sealed into its own
+  `addon` Package.
+- **landV2**: the v2 drivetrain solver, with a clutch, differentials, ABS and a brush tyre model. A
+  car runs on landV2 **only if its package authors `simulation.land`**.
+
+---
+
+## 1. Frame, units, scale
+
+| Rule | Prevents |
+| --- | --- |
+| The model frame is glTF **+X = vehicle LEFT, +Y up, +Z FORWARD**, in metres. The nose faces +Z. | A mirrored or backwards car. Left and right seats, doors and lamps swap. |
+| Bake real-world size into the vertices. The item is placed at scale 1, and placement scale must be exactly 1. | A refused spawn: "physics does not support placement scale". |
+| Keep every node scale at 1 and put no scale on the node chain. Bake scale and rotation into the vertex data. Moving parts keep only a *translation* to their pivot (see section 3). | The publish verifier measuring bounds wrongly. It reported a scale-1.4 car as 2.16 × 1.68 × 4.06 m instead of 1.82 × 1.54 × 3.57 m. |
+| Centre the car on X and Z and put its lowest point at Y = 0 *before* upload. Author every socket in that same frame. | The upload door (`centerAndGroundSnapGlb`, tolerance 2 mm) re-centring a `vehicle` GLB. That moves the geometry under sockets you quoted in the old frame, and the driver ends up sitting underground. |
+| Use a real length. The runtime flags a length outside 0.5–2× its class range as "check export scale (cm vs m?)". The longest horizontal axis must be Z. | A car exported in centimetres, or rotated 90°. |
+| The tyre bottoms sit at Y = 0 at rest, and the wheel radius is the measured rolling radius of what is actually drawn. A car with **staggered tyres** (wider or taller at the rear) draws each axle at its own size and sets `simulation.land.tyreByAxle[].radius` per axle (section 9). | Floating or sunk tyres. A nominal 0.314 m radius on a rim-only mesh floated a car by 80 mm. Equalising staggered tyres to one size makes the car wrong. |
+
+## 2. Mesh parts and node names
+
+A vehicle is **few nodes, one material each**. The runtime moves, hides or lights each named node
+independently. Everything that does none of those things merges into the body.
+
+Each separately addressed node costs at least one draw call, because draws are counted per glTF
+primitive per placing node (see section 8). **The node list is the draw budget.**
+
+| Part | Node | Required | Rule, and the failure it prevents |
+| --- | --- | --- | --- |
+| Body | `bodyshell`, for everything static: shell, trim, underbody, engine bay, static interior, dash, seats, gauges and housings. | yes | Merge, don't pad. Every extra static node is a draw for nothing. |
+| Wheels | Four nodes that resolve to `wheel_lf/rf/lr/rr`. Canonical names are `rim_lf`, `rim_rf`, `rim_lr`, `rim_rr`, each holding rim + tyre + disc in one mesh. The suffix is side then end: `lf` is left-front. | yes | **All four or none.** The runtime discards a partial set (1–3 wheels) and draws placeholder cylinders, while your wheels stay welded to the body. These names never count as wheels: `arch`, `well`, `liner`, `flare`, `guard`, `mudguard`, `mudflap`, `fender`, `cover`, `hubcap`, `spare`, `nut`, `bolt`. |
+| Brake calipers | Merge into the body, or leave them out. | no | Calipers are not claimed by the wheel, so they stay body-fixed and do not steer. A caliper that lands at the origin, as happens with unapplied BeamNG flexbodies, must be dropped. |
+| Steering wheel | `steering` | strongly | Rotates with steering input in first-person view. If it is missing, the runtime derives a socket and nothing turns. |
+| Pedals and gearshift | `pedal_throttle`, `pedal_brake`, `pedal_clutch`, `gearshift` | no | If they are missing, the runtime derives sockets. **Never fabricate parts the source lacks** (pedals, fog lamps, gauge needles). Ship without them and record that. |
+| Doors | `door_lf`, `door_rf` (plus `door_lr` and `door_rr`). Door glass is its own node, such as `doorglass_lf`. | for opening doors | Each moving panel is its own node. Glass that blends cannot share a primitive with opaque paint. |
+| Bonnet and boot | `bonnet`, `boot`. Aliases: `hood`, `trunk`, `tailgate`. On a rear-engined car, `boot` is the engine lid. | for opening lids | Separate nodes; hinge data goes in the package (section 6). |
+| Glass | `glass`, the static glazing in one node, with `alphaMode: BLEND`. | yes, if it has windows | Glass never casts a shadow and is protected from the cabin distance gate. |
+| Lamps | One node per light **function**, each with its own unshared material. Section 4 lists them. | for working lights | A shared lamp material lit the whole headlight when only the indicator should have lit. |
+| Exhaust | `exhaust` | if an exhaust add-on should replace it | An add-on can only hide nodes that exist. |
+| Add-on hide targets | Any node that an add-on replaces, such as an engine cover, intercooler or wing. | per add-on plan | Each one costs a draw. **Plan the add-on set before merging.** |
+| Cabin | Interior geometry may live in `bodyshell`. A separate cabin node must be named `cabin`, never `interior`. | no | `interior` is the engine's own cabin root name, so the node collides with it. |
+
+- Names are normalised before matching. The runtime strips a common prefix (`subik_door_FL` →
+  `door_FL`), Blender `.001` suffixes and namespaces. `_fl` ≡ `_lf`. `wheel_0..3` are lf, rf, lr, rr.
+  Near-miss names produce warnings, so read them.
+- Do not use these reserved names: `chassis`, `vehicle`, `interior`, `road-wheel`, `helix-rootparts`.
+- Make every material inside one node agree on render state: glass nodes blend and everything else
+  is opaque. Drop `KHR_materials_transmission`, `ior`, `clearcoat`, `volume`, `specular` and
+  `sheen`. Prevents: one node drawing twice, and transmission re-rendering the whole scene.
+- A node referenced by the package (in parts, articulation or `componentBuild`) must exist in the
+  **default scene**. Prevents: a spoiler that existed in the GLB but never rendered.
+
+## 3. Pivots and origins
+
+| Node | Origin must be | Prevents |
+| --- | --- | --- |
+| Each wheel (`rim_*`, and `tyre_*` if separate) | **The hub centre.** That is the centre of the tyre cylinder, with geometry local to it, spinning about local X. Mirror the right side by geometry or by a 180° Y rotation. | **Wheel add-ons appearing at the vehicle centre.** A socket-frame add-on anchors at the hidden node's origin, in both the customizer and the world. The 993 baked every wheel at an identity node, so all four add-on copies landed at (0,0,0) while every structural check passed. |
+| The wheel group's bounding-box centre | The hub. The runtime re-pivots the adopted wheel group on its box centre. | Wheels orbiting the axle as they spin. |
+| Steering wheel | Its hub, on the column axis. | A wheel that orbits instead of turning. |
+| Doors and lids | Anything you like. The hinge is declared numerically in the package (section 6). | — |
+| Parts that add-ons bind to (`boot` for wings) | Keep the node; add-ons use a `bind` matrix against it. | A wing that does not follow the lid. |
+
+**Measure camber from a fit of the tread cylinder plus a spin sweep at runtime, never from a PCA
+of the rim's vertices.** Spoke and dish asymmetry fakes 2–3° of camber on a straight wheel.
+
+## 4. Lamps
+
+- **One node per light function**, each with its **own** material that no other node shares.
+  The 993's set was `headlamps`, `foglights`, `taillamps`, `chmsl`, `reverselights`,
+  `indicator_l`, `indicator_r` and `numberplate`. Merge left and right of one function into one
+  node when they use the same image.
+- **Material authoring.** Set `emissiveFactor` to the lit colour,
+  `KHR_materials_emissive_strength: 0` so the lamp is untouched when off, and give it an explicit
+  `emissiveTexture`: a white 8×8, or the source's on-state map in the same UV space. This prevents
+  two failures. The presenter only raises `emissiveIntensity` and never writes a colour, so a lamp
+  with no `emissiveFactor` lights black. And with no emissive map it borrows the albedo, so a
+  dark atlas texel lights dark.
+- **What actually lights a lens** is a row in `specialty.componentBuild.materials` that drives
+  `emissive` from a signal. The row's `slot` matches a mesh name, a material name or **any named
+  ancestor**. Never point a row at a housing node that has lamp children, or every lamp under it
+  lights together.
+- **Coronas and beams.** Additive glow sprites are drawn at lamp *sockets*, and up to two spotlight
+  beams are drawn on the camera's own car. The socket names are `headlight_l/r`, `lowbeam_l/r`,
+  `highbeam_l/r`, `taillight_l/r`, `brakelight_l/r/c`, `reverselight_l/r`, `indicator_lf/rf/lr/rr`,
+  `foglight_fl/fr/r`, `plate_light`, `interiorlight` and `beacon_1..4`. Corona colours come from a
+  preset and cannot be authored.
+- **`lights.lamps[]` in the package is validated but nothing reads it at runtime.** Fill it
+  honestly, but it lights nothing.
+- Brake, reverse, tail and plate lamps are derived from driving state. Headlights, indicators,
+  hazards and fog lamps need specialty actions (section 6).
+- **Indicators cover the whole car, both ends of each side.** A real car flashes at the front,
+  the rear and, where it has them, the side repeaters. `indicator_l` and `indicator_r` must each
+  contain a front lens and a rear lens (one node per side holding both meshes, as the 993's do),
+  and every repeater-like lens is either inside that node or has its own `signal_L` / `signal_R`
+  row. Judge the **lit geometry**, not node names: the bounds of the meshes the indicator rows
+  resolve to must reach the front and the rear quarter of the car. An amber rear lens painted into
+  the body texture can never flash (round 8's F40 lit its front pair only; the owner found it by
+  pressing the hazard key and looking at the back). `validate_vehicle` fails
+  `LAMP_INDICATOR_REAR_MISSING` (naming any unlit amber lens at the rear), `LAMP_NODE_UNLIT` /
+  `LAMP_REPEATER_UNLIT` (a lens-like node no row lights) and `LAMP_FUNCTION_NO_ROW` (a lamp node
+  without the rows its function needs: low and high beam, fog, tail and brake, reverse), and
+  `preview_vehicle` presses each lamp key and fails `vehicle.lamps.each_function_lights` naming
+  the lens that stays dark. Model the rear lens as its own mesh with its own emissive material.
+- **A car that genuinely has no rear indicators** (rare) sets
+  `lights.noRearIndicators` to a sentence saying why, with its source. It turns the error into a
+  warning that quotes the reason. It never hides a rear lens the model does carry.
+- **Brake lamp at a standstill is expected with a driver seated.** The platform holds the brake
+  for a seated driver who touches nothing (auto-hold, `VehicleDriveAbility` `AUTO_HOLD`), and the
+  brake lamp follows the applied brake, as on a car with Auto Hold: lit at a stop, off the moment
+  the car is driven or reversed (measured on the 993 and the F40). An unoccupied parked car's brake
+  lamp is off. This is not an authoring defect and no gate flags it; do not remove the brake
+  rows to hide it. (Known platform nit: the hold, and so the lamp, also stays on with the
+  ignition off while the driver is seated.)
+- Keep a saturated red emissive below about 2, because ACES tone mapping drifts it orange. Ship
+  only the lamps the source actually has.
+
+## 5. Seats, sockets and the cabin
+
+- A seat socket is the occupant's **H-point (hip joint)**. It is not the cushion and not the
+  floor. Ids are `seat_dside_f` (driver, on the +X / left side), `seat_pside_f`, `seat_dside_r1`
+  and `seat_pside_r1`. Only `seat_dside_f` drives.
+- **Declare every seat in `mesh.sockets`** and in the GLB's host manifest,
+  `asset.extras.HELIX_vehicle.sockets` (section 12), in the model frame. The class preset derives seats from the cabin anyway; a sedan derives four. If the seat
+  nearest an approaching player is undeclared, the player cannot board. A boat with two declared
+  seats was unboardable this way.
+- **Seats only grow.** A declared seat can never be removed in a later version, and the backend
+  refuses it (`vehicle_identity_changed`). Add rear seats only if an adult's head clears the glass.
+- Authored H-points are trusted down to 0.12 m above the floor. Aim for: crown to roof lining
+  ≥ 10 mm (20 mm achieved on the 993), pelvis ≤ 0.12 m above the cushion, soles within
+  −0.05 to +0.30 m of the floor, and the driver's hand within 0.07 m of the rim. These are the
+  visual-QA occupant thresholds.
+- To lower an occupant, move the seat socket. Change it everywhere it is declared: the package
+  `mesh.sockets`, the GLB's `asset.extras.HELIX_vehicle.sockets` and any `seat_*` node.
+- The cabin around the seats (seat shells, dash, legible gauges, the real steering wheel design,
+  pedals, door cards) and how the runtime's `cabinFit` moves a seat that does not fit are in
+  `read_skill({ name: "helix-vehicles", reference: "cabin" })`.
+- Other anchors are `engine`, `exhaust`, `cam_chase`, `cam_hood`, `numberplate`, `gearshift` and
+  `ignition`. Socket resolution priority is: manifest `sockets` > named node > skin joint >
+  auto-detected > class preset. A mesh with no recognised names still spawns, with preset
+  geometry.
+- **The exit point** is half the car's width plus 0.7 m outward from the seat side, at ground
+  level.
+- **Seat occupancy lives on the vehicle entity**, never on the player. Read the vehicle to know
+  who sits where.
+
+## 6. Controls, doors and the specialty block
+
+- A package **without `specialty`** gets the platform default controls, which are Drive and Exit
+  only. Its light, horn, wiper, ignition and door keys do nothing, and **its declared doors and
+  lids can never open**.
+- Opening a panel requires `specialty.componentActions.actions[<panel signal>]`. Panels come from
+  `mesh.articulation.panels[]`:
+
+  ```
+  { id, role: door|bonnet|boot, signal, nodes[], hinge{pivot, axis, closedDeg, openDeg},
+    collider{kind:'visual-bounds-box', minHalfExtentM}, dynamics{detents[], latchFraction, latchAngularSpeedRadS},
+    fidelity{physical[], detachable[]} }
+  ```
+
+  The pivot is in the model frame, and the axis is unit length to within ±1e-3. **A node may
+  belong to only one panel.** Doors use axis Y, so a left door opens to about −62°. Lids use
+  axis X. Keep `mesh.parts` consistent with `panels[].nodes`, or two code paths disagree about
+  which nodes swing.
+- **Articulate every panel the real car opens**: both doors, the bonnet or hood (or front
+  clamshell), the boot, trunk or tailgate, and the engine cover or rear clamshell (those last
+  three all declare `role: "boot"`). Each is its own node split from the body shell, with the
+  **node origin on the hinge line**, then declared with `role`, axis `[1, 0, 0]`, a `pivot` on
+  that line and `openDeg` of about 50 to 60 in the sign that lifts the free edge, plus the `hood`
+  or `trunk` action. A lid left in the body shell can never open: round 8's F40 articulated only
+  its doors and the owner's bonnet and boot keys did nothing. `validate_vehicle` WARNS
+  (`PANEL_ROLE_MISSING_DOOR`, `PANEL_ROLE_NO_NODE_BONNET` / `_BOOT` when the model has no separate
+  lid, `PANEL_ROLE_UNDECLARED_BONNET` / `_BOOT` when it has one nobody articulates), each naming the
+  missing role with hinge guidance. It stays a warning because a model that lacks lid geometry is a
+  lesser car, not an invalid one; fix it by splitting the lid. The preview sweeps every declared
+  panel to its limit, so a declared lid is exercised and an undeclared one is not.
+- When the specialty carries a `componentBuild`, its `articulators` rows drive the panels instead
+  of `mesh.articulation`. Keep the two consistent: the gate reads the declared panels, and the car
+  moves by the rows.
+- **The practical route** is to reuse the published `helix-convertible` control bundle, as the
+  993, Subaru and Gavril do. Copy a reference package's whole `specialty` block, then rename its
+  node and seat references to yours. The reference is
+  `read_skill({ name: "helix-vehicles", reference: "reference-package" })`.
+- `specialty.componentActions` must **exactly equal** the protocol compiled from
+  `componentBuild` (its interacts and signal bit spans); the backend refuses any difference. The
+  safe edit is: keep every signal and action, and only rename row `slot`s and articulator nodes to
+  yours. An action your car lacks (fog with no fog lamp) then lights nothing, which is harmless. If
+  you do remove rows or signals, paste the `componentActions` and digest that `validate_vehicle`
+  prints.
+- `componentBuild.digest` must equal the digest of its rows and signals. It is fnv1a64 over sorted
+  `stable` JSON, and the algorithm is in the reference. Any edit to a row changes it. A wrong
+  digest is refused.
+- Hand-authoring a new control bundle requires a registry bundle and its sha256. Ids beginning
+  `helix-vehicle-controls-*` are reserved.
+- Platform keys, which work only when the specialty declares the matching call:
+
+  | Key | Action |
+  | --- | --- |
+  | L | headlights |
+  | K | fog |
+  | `,` | indicator left |
+  | `.` | indicator right |
+  | `/` | hazards |
+  | H | horn |
+  | J | wipers |
+  | U | cabin light |
+  | Y | ignition |
+  | O, P, `;`, 0 | doors |
+  | `-` | bonnet |
+  | `=` | boot |
+
+## 7. Materials, paint and Palette
+
+- Ship **baked PBR in the GLB**. The platform vehicle path does not resolve Palette references at
+  runtime.
+- Use Palette families as the authoring vocabulary, especially for the BeamNG importer, which
+  requires `--input palette=`. Stamp each material with
+  `extras.helixVehicleMaterialSemantic = { contract: "helix.vehicle-material-semantic/1", familyId }`.
+
+  | familyId | Casts shadows |
+  | --- | --- |
+  | `vehicle-paint-solid`, `vehicle-paint-metallic`, `vehicle-paint-pearl`, `vehicle-paint-matte` | yes |
+  | `carbon-fiber`, `tire-rubber`, `aluminum-brushed` | yes |
+  | `vehicle-glass`, `headlamp-lens`, `taillamp-lens` | no |
+  | `chrome`, `stainless-steel`, `brake-rotor`, `brake-caliper-painted` | no |
+  | `vehicle-interior-plastic`, `vehicle-leather`, `vehicle-carpet`, `dashboard-soft-touch`, `vehicle-upholstery-fabric`, `vehicle-instrument-display` | no |
+  | `underbody-coating` | no |
+
+  **Do not collapse everything to one material.** If you do, every mesh reports one family, and a
+  one-piece car reads as "interior" and vanishes at distance. Draws are counted per primitive, so
+  more materials cost nothing extra.
+- **Paint.** Give the body paint material `extras.helixVehicleRole: "paint"`. Owner paint
+  overrides fan out to it, and add-ons that carry paint inherit the host's colour, roughness and
+  metalness from it. An add-on with a paint role on a host that has no paint role throws.
+  `baseColorFactor` is **linear**: an sRGB paint value written straight in reads pale (a red reads
+  salmon). Paint targets (metallic and roughness for solid, metallic and matte paint) and how a
+  single layer reads as clear-coated are in
+  `read_skill({ name: "helix-vehicles", reference: "appearance" })`.
+- Do not leave glTF's default metallic 1 on tyres or rims. They render black without a rich
+  environment. Use tyres at metallic 0 and roughness ~0.6, and rims at metallic ≤ 0.6 with the
+  albedo lifted to 0.55–0.6.
+- **Textures.**
+  - Use KTX2 with a full mip chain. Mipless KTX2 is refused for every kind.
+  - Declare `KHR_texture_basisu` in both `extensionsUsed` and `extensionsRequired`.
+  - Encode data maps (metallicRoughness, occlusion) as **linear**. An sRGB-tagged roughness atlas
+    sampled 0.20 as 0.033.
+  - Keep colour maps sRGB.
+  - Every primitive whose material binds a texture must have `TEXCOORD_0`, or it samples texel
+    (0,0) of whatever atlas it binds.
+- **Never bind a normal map as base colour.** The guard runs for add-ons, wearables and avatars,
+  but not for the vehicle host. Look at the render.
+- These canonical vehicle material slots are the only legal add-on `patch` targets:
+  `paint_primary`, `paint_secondary`, `trim`, `chrome`, `grille`, `glass`, `light_lens`,
+  `wheel_rim`, `wheel_tyre`, `caliper`, `interior_primary`, `interior_seats`, `engine_bay` and
+  `undercarriage`.
+
+## 8. Budgets
+
+| Limit | Vehicle | Add-on | Where it is enforced |
+| --- | --- | --- | --- |
+| Draw calls (one per glTF primitive per placing node) | **24** wall. Your floor is your node count (about 22 for a coupé); the platform's 12 "target" is rarely reachable for a full car | 8 | Upload door and Continuum seal. At seal they are **summed over every GLB in the closure**. |
+| Triangles | **90,000**, summed over the closure | 20,000 | Upload and seal |
+| Materials | 48 per GLB | 4 | Upload and seal |
+| Texture edge | 2048 px, never bypassed | 2048 px | Upload and seal |
+| File size | 16 MiB | 6 MiB | Upload |
+| Skin or animation | refused: a vehicle is a static mesh | warn | Upload |
+| Textures | KTX2 recommended | **KTX2 with mips required** for new add-ons | Upload |
+| Composed car | — | ≤ 12 realised add-on draw calls | Compose/save |
+
+- **Ship one drawn GLB** in the closure. Lower quality tiers belong in separate Packages, or must be
+  tagged with unique tier runtime-profile ids so that the seal judges them as alternatives.
+  Packages created from 2026-09-13 onwards get no legacy grace.
+- A realistic floor for a sports coupé is 22. The 993 used 22 nodes: body, glass, exhaust, 2 doors,
+  2 door glasses, 2 lids, steering, 4 wheels and 8 lamps, with 84,548 triangles under three
+  2048² KTX2 atlas pages.
+- Do not plan budgets around runtime batching. The seal counts per primitive.
+
+## 9. The vehicle package (`helix.vehicle-package/2`)
+
+```
+{ schemaVersion: "helix.vehicle-package/2", packageVersion: 2, id, displayName, make?, model?, years, market?,
+  provenance: { distributable: true, note }, citations: [{ id, kind, ... }],
+  mesh: { source: "universal-item", ref: "$self", classId, wheelVisuals, parts[], sockets?, visual?, articulation? },
+  physics: {...}, simulation?: { format: 1, fixedStepHz, qualityInvariant: true, land: {...} },
+  targets: {...}, audio: {...}, lights: {...}, vfx: [], specialty?: {...} }
+```
+
+- **Every number in `physics` and `targets` is `Sourced`:** `{ value, unit, sources: [citationIds] }`
+  or `{ value, unit, derivedFrom: "<the arithmetic>" }`, never neither. A cited id must exist in
+  `citations`. Citation kinds are `manufacturer`, `instrumented-test`, `reference-database`,
+  `measured-fixture` and `engineering-literature`. Label assumptions in `note`. Prevents: invented
+  physics that nobody can audit.
+- **The publish gate** requires `provenance.distributable: true`, a `mesh.source` that is not
+  `fixture`, and **`mesh.wheelVisuals` declared**. Use `"author-static"` when your GLB carries
+  real wheels; the runtime adopts them when all four resolve. The backend also requires `id`,
+  `displayName`, `years`, `mesh.classId` and `mesh.parts[]`. `classId` is one of `sedan`,
+  `supercar`, `pickup`, `suv`, `van`, `truck`, `bus`, `cruiser`, `kart` or `lightplane`; unknown
+  ids fall back to `sedan`. It decides the preset seat rows (`supercar` and `kart` have 1, `sedan`
+  has 2) and the plausible length range.
+  Each part is `{ id, node, role: body|door|bonnet|boot|glass|lamp|mirror|wing|interior|other,
+  consumed }`. Wheels are never parts.
+- **Validator errors stop the car from spawning, and publish does not catch them.** The rules:
+  - the torque curve has at least 2 points in strictly ascending rpm, and should reach the limiter
+  - `limiterRpm > idleRpm`
+  - `reverseRatio < 0`
+  - at least one forward gear
+  - `targets.*.tolerance` is in (0, 1)
+  - induction numbers are positive, with the wastegate ≤ maxBoost
+  - no boost is double-counted: if the curve already contains it, set `torqueCurveIncludesBoost`
+  - audio and lamp rules (section 10)
+  - articulation hinge axes are unit length
+
+  **Run `validate_vehicle` (the `helix vehicle validate` command) before every publish** (section 12).
+- **v1 vs v2.** With `simulation.land`, the car runs landV2 in every world. The platform **never
+  derives** `simulation.land` for you. Without it, the car runs v1: a lumped engine, an always-on
+  automatic gearbox and no manual mode. Brakes, suspension, steering, aero, mass and centre of mass
+  always come from `physics`.
+- **Fields.** All are SI units: m, kg, N·m, N/m, s.
+
+  | Block | Fields |
+  | --- | --- |
+  | `chassis` | `mass`, `weightDistributionFront`, `centreOfMassHeight` (above ground), `groundToBodyOrigin`, `wheelbase`, `trackFront`, `trackRear`, `length`, `width`, `height`, `wheelRadius`, `tyreSize`, `inertiaMultiplier` |
+  | `engine` | `torqueCurve` (`[rpm, N·m]` at the crank), `idleRpm`, `limiterRpm`, peak power and torque with their rpm, `drivetrainEfficiency`, `coastTorque`, `cylinders`, `strokes`, `speedLimiterKph` (informational; not enforced) |
+  | `induction?` | turbo or supercharger fields |
+  | `gearbox` | `ratios`, `reverseRatio`, `finalDrive`, `shiftTime`, `autoUpRpm`, `autoDownRpm` |
+  | `driveBiasFront` | nominal front share of drive torque at zero slip: 0 = RWD, 1 = FWD, AWD strictly between and equal to `centre.torqueSplit` |
+  | `brakes` | `maxTorque` (whole car), `biasFront`, `handbrakeTorque`, `handbrakeAxle` |
+  | `aero` | real `dragCoefficient`, `frontalArea`, `airDensity`, `downforceCoefficient` |
+  | `grip` | `peak`, `sliding`, `lateralMultiplier`, `biasFront`, `loadSensitivityExponent` |
+  | `suspension` | `rideHzFront`, `rideHzRear`, `dampingRatio`, `bumpScale`, `reboundScale`, `staticRideHeight`, `bumpTravel`, `antiRollBarFront`, `antiRollBarRear` |
+  | `steering` | `roadWheelLockDeg`, `rackTime` |
+  | top level | `linearDamping` **= 0 when aero is modelled** (0.02 removed 65 km/h of top speed), `angularDamping` |
+
+  In `simulation.land`, the driveline holds the engine LUTs and inertia, the clutch (capacity
+  ≈ 1.6 × peak torque), the gearbox kind (`manual` or `sequential` enables manual mode), shift
+  delay and auto rpms. Differentials (`front`, `rear`, `centre`) each take a type, a torque split
+  and a `gearRatio`; **the final drive lives on the diff in v2**. It also holds the optional
+  turbine, `abs`, optional `tractionControl` (engine 0.3.204+; see below), and `tyreByAxle[]` with `muLut` and **a `radius` per axle**: staggered tyres
+  are modelled there, with `physics.chassis.wheelRadius` at the driven axle's radius (it sets the
+  rolling radius and gearing; the physics contacts use it at all four corners, so the other axle's
+  contact sits off its drawn tyre by the radius difference). Visual QA judges spin per axle. Derivation is in
+  `read_skill({ name: "helix-vehicles", reference: "physics-from-specs" })`.
+- **Keyboard launch fails (wheelspin, wall hit, no clean 0-100)?** Author
+  `simulation.land.tractionControl` (opt-in; absent means none), e.g. `{ targetSlip: 0.2, cutRate: 25,
+  restoreRate: 3, minTorque: 0.45, upshiftTorqueRamp: true }`. Declare it as the real system or a
+  playability aid, then re-run `simulate_vehicle`; the report's `traction control:` line shows it.
+  When and how to tune: physics-from-specs, "Drivable on a keyboard" and "Traction control".
+- **`groundToBodyOrigin` must equal `wheelRadius + staticRideHeight`**, and it is **locked forever
+  after the first publish**. Your first mint fixes it, so measure ride height with
+  `preview_vehicle` before that mint. If a later version needs a different stance, keep the
+  equality by changing `staticRideHeight` (= locked value − `wheelRadius`). Never change the locked
+  field: the 993's version 1.0.2 did, and it was sealed but unusable.
+- **Targets.** These are the published behaviour with tolerances:
+
+  | Target | Notes |
+  | --- | --- |
+  | `zeroToSixtyMphS` | |
+  | `zeroToHundredKphS` | |
+  | `quarterMileS` | |
+  | `topSpeedKph` | the ungoverned figure (the platform car runs ungoverned) |
+  | `ungovernedTopSpeedKph` | |
+  | `lateralG` | |
+  | `brakingSixtyToZeroM` | |
+
+  Only `grip.peak` and `suspension.*` are ours to tune toward the targets. Everything else is the
+  real car's. The engine is the maker's **declared crank figure** (both torque curves, `peakTorqueNm`,
+  `peakPowerKw`): losses go in `drivetrainEfficiency` and drag, never an inflated curve
+  (`TORQUE_CURVE_EXCEEDS_DECLARED_CRANK_FIGURES`). An AWD car's split lives on `simulation.land.driveline.centre`
+  (`physics-from-specs`, "All-wheel drive").
+- Declare `chassis.length` and `chassis.width`. The spawn footprint search uses them to find a
+  pose clear of kerbs and walls; the default is 1.9 × 4.3 m.
+- The chassis collider is one full-length box with **0.16 m** kerb clearance.
+
+## 10. Audio
+
+- **Format.** WAV (`audio/wav`) only. Each runtime asset is
+  `{ name, url, checksumSha256, bytes, mediaType: "audio/wav" }`, where `url` is the public
+  content URL of that WAV as an object of the vehicle's own Continuum Package.
+  - **Author rows with only `name` and `file`** (the WAV beside the package or in `audio/`).
+    `publish_vehicle` uploads each file, verifies its public URL serves the exact bytes, and writes
+    `url`, `checksumSha256`, `bytes` and `cid` before the mint. Never hand-write a URL.
+  - **A `cid`-only row fails closed and the car is silent.** So does a 404, a re-encoded file or
+    an MP3. `check_vehicle_audio` catches all of these, decodes every sample the runtime selects,
+    and refuses digital silence. Run it before publishing and on the published item id.
+  - MP3, OGG and data URIs are not played.
+- **The hard rule: vehicle audio is sourced, never synthesised.** Never generate or synthesise a
+  vehicle sound: no resynthesis, no `generate_audio`, not even for a slot nothing provides.
+  Always use real recorded sound, from BeamNG mods as much as possible. Whatever the mesh source,
+  find the most accurate simulator mod of the exact car (BeamNG first; Assetto Corsa / ACC,
+  rFactor 2, Automobilista 2 where theirs is more accurate) and extract its audio with
+  `import_vehicle_audio` (`helix vehicle audio-import`). Every slot and bank carries a
+  `provenance` `{ kind: "sim-mod" | "sim-official" | "recording", sim, mod, modUrl?, sourceFile,
+  sourceSha256, event?, extractor }`. `check_vehicle_audio` reports it and **fails** audio that is
+  synthesised or generated (`AUDIO_SYNTHESISED`), a car whose engine audio is unsourced
+  (`AUDIO_ENGINE_UNSOURCED`), and **any empty slot or slot that would fall back to a platform
+  default** (`AUDIO_SLOT_UNSOURCED`); `publish_vehicle` refuses the same. **A car ships a sourced
+  recording for every one of the 31 slots below** (`engineLadder`, `exhaustLadder`, `idle`,
+  `startup`, `shutdown`, `shiftUp`, `shiftDown`, `clutch`, `transmissionWhine`, `turboSpool`,
+  `blowOff`, `intake`, `revLimiter`, `backfire`, `suspension`, `impactLight`, `impactMedium`,
+  `impactHeavy`, `tyreSqueal`, `tyreScrub`, `tyreSpin`, `tyreRollSlow`, `tyreRollFast`,
+  `indicatorTick`, `skid`, `brakeSqueal`, `handbrake`, `reverseBeep`, `horn`, `doorOpen`,
+  `doorClose`); the audio reference has the slot-by-slot sourcing table.
+- **Engine sound** is a bank:
+  - `audio.bank.assets[]` holds the WAVs, each with role `vehicle.audio.bank.sample`.
+  - `audio.bank.blends.<NAME>` is `{ eventName, samples: [[[file, rpm], …], …] }`: rpm-ordered
+    ladders crossfaded by load.
+  - `engineBlend` and `exhaustBlend` name the blends.
+  - `sampleCylinderCount`, `strokes` and `crankLayout` (`"flat-plane"` | `"cross-plane"`,
+    default `"flat-plane"`) describe the *recorded* engine and its crank. `crankLayout` selects
+    the firing fundamental `check_vehicle_audio` judges each rung's pitch against: `C·rpm/120`
+    even-firing (flat-plane, and every inline/boxer engine), or `rpm/60` for a cross-plane V8.
+    A rung an octave or more off its rpm label is refused.
+  - The mix knobs are `engineGainDb`, `exhaustGainDb`, `minLoadMix`, `maxLoadMix` and `muffling`.
+  - Every sample a selected blend names must be in `bank.assets`.
+  - The 993 used 11 recorded rungs from 1,768 to 6,388 rpm.
+- **Slots.** Every slot is declared as
+  `{ slot, buffers[], assets?[], consumed, reason?, absent? }`. An unconsumed slot **requires a
+  `reason`** and still carries its sourced recording. **The only empty slots** are
+  `consumed: false, absent: "not-fitted"` with a reason, for a component the real car physically
+  lacks (turbo slots without a turbo, `reverseBeep`, `clutch` on an automatic or CVT, combustion
+  slots on an EV, whose engine ladder is a recording of the real motor), and
+  `absent: "combined-with-engine"` for `exhaustLadder` alone, beside a sourced engine ladder, when
+  the mod records one combined set. Anything else empty is `AUDIO_SLOT_UNSOURCED`; a `not-fitted`
+  claim the physics contradicts is `AUDIO_SLOT_FITMENT_MISMATCH`. Slots played on the platform:
+
+  | Slot | Runtime trigger |
+  | --- | --- |
+  | `startup`, `shutdown` | ignition on/off |
+  | `shiftUp`, `shiftDown` | gear change |
+  | `clutch` | pedal click |
+  | `revLimiter` | repeats at the limiter |
+  | `turboSpool` | loop on shaft rpm |
+  | `blowOff` | boost dump edge |
+  | `backfire` | on-load → overrun edge |
+  | `suspension` | suspension events |
+  | `impactLight` / `Medium` / `Heavy` | collisions |
+  | `tyreSqueal`, `tyreScrub` | slip loop |
+  | `tyreSpin` | wheelspin loop |
+  | `tyreRollSlow` / `Fast` | speed crossfade |
+  | `skid` | skid onset |
+  | `brakeSqueal` | light braking at walking pace |
+  | `handbrake` | pull |
+  | `indicatorTick` | relay, twice per blink |
+  | `horn` | needs a specialty horn action |
+  | `engineLadder` / `exhaustLadder` | through the bank |
+
+  **Carried unconsumed:** `idle` (the runtime idles on the bottom rungs), `transmissionWhine` (played
+  only with a declared native pitch) and `intake` (no intake layer) still carry the car's own
+  sourced recording with `consumed: false` and the reason. **Doors are required**: `doorOpen` and
+  `doorClose` each carry a sourced recording (the engine lane is wiring the door edge). There is no
+  bonnet, boot or engine-cover slot yet, so a panel sound is not supported. The runtime's own default
+  reverse beep is a platform default and does not satisfy `reverseBeep`: source one, or declare it
+  `not-fitted`. Never author a stand-in.
+- **Find the most accurate sim mod, by measurement.** Compare candidate mods against real
+  recordings of the car (firing-fundamental pitch track vs rpm, spectral centroid, roughness,
+  idle character, limiter cadence) and take the one that matches; the commands are in
+  `read_skill({ name: "helix-vehicles", reference: "audio" })`.
+- **A slot the best mod lacks** is filled, in order, from another BeamNG mod of the same engine or
+  car family (then the BeamNG base game's stock banks and `vehicles/common` sounds), another
+  simulator's mod, a real recording of the car. Never another car's sound under this car's label,
+  and never a stand-in; a car with an unsourced slot is not publishable. Report it as blocked and
+  say what you tried.
+- **Platform defaults are never an answer.** With no `audio.bank` the runtime plays a synthesised
+  oscillator engine (bank `inline4` and the other generic banks in `engine-core`), and for any
+  slot a car leaves out it plays its own generated default sound pack, synthetic starter and
+  runtime noise for tyres, skids and the handbrake. None of that is a sound for a published car.
+  Do not rely on any of it and do not omit a bank or a slot to get it: the gate fails a car that
+  would fall back to one (`AUDIO_ENGINE_UNSOURCED`, `AUDIO_SLOT_UNSOURCED`).
+- **A world with no `@helix/engine-core/audio` import-map entry plays no car audio at all.**
+  Test sound in a platform-hosted world that has it.
+
+## 11. Add-ons
+
+- **A car ships with a parts set.** At least a wheel set, an exhaust, an ECU, a gearbox,
+  suspension, brakes and anti-roll bars, plus a spoiler where the real car has one. The car is not
+  done until its customizer shows them as compatible and for sale (`check_vehicle_host`). The list
+  and the method are in `read_skill({ name: "helix-vehicles", reference: "addons" })`.
+- An add-on is an `add_on` item. Required fields:
+  - `fits = { slotType, requires{ sockets[], paths[], pointers[], nodes[], skeleton: null }, only{ items: [<host item ids>] } }`
+  - `ops[]`, at most 32
+  - a Marketplace route or `noMarketplace`
+- **`fits.only.items` must name at least one host.** Universal add-ons are refused. Every op target
+  must also appear in `requires`.
+- **Op verbs.**
+  - `tune`: `{ v:"tune", path, op: "mul"|"add", value }`. Numeric paths take only `mul` or `add`;
+    `set` on a number is first-party only. Categorical paths, such as `drivetrain.forcedInduction.kind`,
+    take only `set`. A `mul`
+    on a value that is 0 does nothing, so use `add`. A `mul` on a block the host lacks is refused,
+    so a turbo on an NA car cannot ship; there is no `provides` verb for creators.
+  - `hide`: `{ v:"hide", nodes:[glob] }`
+  - `mount`: `{ v:"mount", row }`
+  - `patch`: `{ v:"patch", at:"/materials/<slot>/…" }`
+- **Main slot types.**
+
+  | Slot type | Mount socket |
+  | --- | --- |
+  | `vehicle.wheel@1` | fills all 4 of `wheel_*`; the 993 pattern hides `rim_*` |
+  | `vehicle.tyre@1` | — |
+  | `vehicle.spoiler@1` | `boot` |
+  | `vehicle.bodykit@1`, `bumper_f@1`, `bumper_r@1` | `bodyshell` |
+  | `vehicle.exhaust@1` | `exhaust` |
+  | `vehicle.engine@1` | `engine` / `bonnet` |
+  | `vehicle.ecu@1`, `transmission@1`, `driveline@1`, `suspension@1`, `brakes@1`, `arb@1`, `steering@1` | tune-only (no model) |
+  | `vehicle.exhaust_note@1`, `blowoff@1` | sound only |
+  | `vehicle.headlight@1`, `taillight@1` | lamp sockets |
+  | `vehicle.seats@1` | seat sockets |
+  | `vehicle.steering_wheel@1` | `steering` |
+  | `vehicle.plate@1` | `numberplate` |
+
+- **Anchoring is the add-on GLB's `scene.extras.helixMeshFrame`** (contract `helix.mesh-frame/1`).
+  - `{ authoringFrame: "socket", outboardAxis: "+x" }`: the mesh is metric and **centred on the
+    mount**, which is the hub for wheels. One mesh serves every corner, turned to face outboard.
+    It requires the host's wheel origins at the hubs (section 3).
+  - `{ authoringFrame: "host", bind: { socket, root, matrix } }`: the vertices are already in the
+    host's frame, as for wings, kits and exhausts. Without `bind`, the part stays static at the
+    root. **If the host is ever re-framed (raised or moved), every host-frame add-on must be
+    shifted and republished.**
+  - A socket that does not resolve is reported and not drawn.
+- **A hide needs a host grant, sealed into the car.** The standard slot board grants only
+  `wheel_stock_*` and `exhaust_stock_*`-style globs. To let add-ons hide your real node names
+  (`rim_*`, `exhaust`), declare them in the car's `publish.json`:
+  `"hostGrantExtensions": { "whl.wheel": { "hide": ["rim_*"] }, "pwr.exhaust": { "hide": ["exhaust"] } }`.
+  `publish_vehicle` seals them into the package root, and the backend checks each pattern against
+  the GLB's nodes. Without the grant, a wheel add-on whose `requires.nodes` lists `rim_*` fits zero
+  hosts; `check_vehicle_addon` reports it with the backend's own fit count, and
+  `publish_vehicle_addon` stops (`HOST_GRANT_MISSING`). The board (sockets, nodes, tunable paths,
+  grants) is derived **once, at mint**, from the GLB's `asset.extras.HELIX_vehicle`, the package's
+  physics and those grants (section 12). A version move does not rebuild it, so plan the add-on set
+  and its grants before the first mint.
+- **A replacing part must hide what it replaces.** An exhaust add-on hides `exhaust`. Hide
+  targets must exist on the host.
+- **Tune-only parts ship no model.** An ECU, gearbox, driveline, coilover kit, sway-bar set, brake
+  kit or steering rack draws nothing, so its directory holds only `addon.json`, with no
+  `model.glb`. Engine, intake, induction, exhaust and tyre-compound parts may also be tune-only.
+  The backend admits a meshless part in those slots when **every op is a `tune`**, with at least
+  one. A `hide`, `mount` or `patch` op needs a model. The server pictures the part with a slot
+  card. Never ship a placeholder box into a tune slot: a model saved into one once made the whole
+  car refuse to spawn.
+- **Every required path must be on the host.** A part fits only if each path in
+  `fits.requires.paths` is in the host board's `surface.paths`. Cars published since 2026-10-03
+  expose every path their vehicle package resolves. Older cars may expose none, so a performance
+  part fits zero hosts. `check_vehicle_addon` reports this as `HOST_PATHS_MISSING`.
+- **Prove the part does something before you publish it.** `check_vehicle_addon` measures every
+  `tune` op on each host with the live runtime's own physics and add-on fold. It judges each op on
+  a figure that op can move:
+
+  | Ops on | Judged on |
+  | --- | --- |
+  | engine, gearbox, induction, mass, aero drag | 0-100 km/h, 0-60 mph, quarter mile, top speed |
+  | `drivetrain.brakes.maxTorque` / `biasFront` | 60-0 mph at 30% pedal (torque-limited) and at full pedal (ABS, tyre-limited) |
+  | `drivetrain.brakes.handbrake*` | handbrake-only deceleration |
+  | `land.antiRollBar.*` | skidpad body roll (anti-roll bars barely move steady-state grip) |
+  | suspension, tyre grip, downforce | skidpad g and roll, braking, acceleration |
+
+  A part that moves nothing it governs is an error (`ADDON_DRIVE_NO_EFFECT`). An op that undoes
+  the rest of its part is a warning (`ADDON_DRIVE_OP_CANCELS`). For example, the 993's first brake
+  kit added +0.079 front bias. On its own that lengthened the full-pedal stop by 6%, which
+  cancelled the kit's 28% extra brake torque. Raising only `limiterRpm` gains little when the
+  torque curve ends at the old limiter, because the engine holds the last point flat. Give an ECU
+  a `torqueCurve` op as well.
+- **Performance on landV2.** Engine torque curve, limiter, idle, coast, efficiency, gear ratios,
+  reverse, shift time, final drive (lands on the diffs), drive bias (centre split, AWD only) and
+  turbo boost/wastegate/spool are projected into landV2. Brakes, suspension, anti-roll, mass, aero
+  and steering act directly.
+
+  These are **inert on landV2**: `densityLapse`, induction kind, `referenceRpm`, `gamma`,
+  `spoolDownTime`, turbo ops on a car with no `driveline.turbine`, and probably tyre-grip ops.
+  The live truth is `controller.landDriveline.spec`; `controller.tuning.drivetrain` is not proof.
+- **Gearing.** Judge a gearing change on the whole run, including shift count and shift time.
+  Shorter ratios made a 993 *slower* to 100 km/h because they added two 0.25 s shifts.
+- **Wheel sets.** Use the same radius as the host's tyre: refit radially, or tune
+  `contacts.*.radius`. Give them the material fixes from section 7.
+- The upload refuses add-on textures that are not KTX2 with mips. A primitive with a texture must
+  have UVs. **Never synthesise a new UV unwrap onto a borrowed atlas.**
+- `publish_item` **does not auto-seal vehicle add-ons** (only character add-ons). Publish them
+  with `publish_vehicle_addon`, which seals and pins the `addon` Package (section 12).
+
+## 12. Publish, pin, seal, list
+
+1. **Host manifest.** The final GLB carries **`asset.extras.HELIX_vehicle`**:
+   `{ version: 1, class, sockets: { <socket id>: [x, y, z], … } }` in the model frame, with every
+   seat, the four wheel hubs, `steering`, `engine`, `exhaust`, the lamp sockets and `boot` /
+   `bonnet`. The backend reads **only `asset.extras`** (scene or root `extras` are ignored at
+   upload, although the runtime reads them), and derives the car's slot board from it **once, at
+   mint**: host kind, sockets, node names, and the tunable paths the package's physics resolves.
+   Without it the car mints as a silent non-host whose customizer shows "0 compatible", and a
+   later version does not fix it. Export snippets:
+   `read_skill({ name: "helix-vehicles", reference: "host-manifest" })`.
+2. **Validate and simulate.** `validate_vehicle({ vehiclePackage, glb })` must exit 0; it refuses a
+   vehicle GLB with no host manifest. `simulate_vehicle` must meet every target within tolerance.
+   Audio rows backed by a local WAV are judged as if uploaded.
+3. **Preview, then fix the stance, the cabin and the look.** `preview_vehicle({ target: <dir> })`
+   renders the unpublished directory in the real runtime, prints ride height,
+   wheel-to-hub, arch and cabin numbers, and writes the fixed appearance poses to compare with
+   reference photos. The first mint locks `groundToBodyOrigin` and the slot board, so this is the
+   last cheap fix.
+4. **Publish.** `publish_vehicle({ dir, dryRun: true })`, then without `dryRun`. One command
+   uploads the WAVs and writes their URLs, seals the `vehicle` Package (the package as root, the
+   model, every WAV), makes the item pinned to it (the only door that writes the checksum-pinned
+   `properties.vehiclePackage`), and reads it all back, the slot board included. The seal
+   re-checks the budgets over the closure. It is resumable: after any failure, fix the cause and
+   re-run the same call. The descriptor it sealed is in `<dir>/.helix-publish/`. `publish.json`
+   `provenance.kind` is `authored`, `imported` or `generated`. **If it answers NOT AVAILABLE**
+   (the Package-first cutover), the bundled CLI has no vehicle mint: finish every gate and report
+   the mint as blocked; never improvise it.
+5. **Host check.** `check_vehicle_host({ itemId })`: host kind `vehicle`, non-zero sockets, nodes
+   and paths.
+6. **Visual QA.** Try Now, the customizer and visual QA draw the package's `mesh.visual` derived
+   rendition, which `publish_vehicle` pins to the GLB it uploaded (`artifactRef` = its absolute
+   `https` content URL; `mesh.ref` bound to the item). Visual QA
+   (`visual_qa_item_hosted`, or `visual_qa_item` with a QA sign-in) must pass before any Marketplace
+   listing, distribution or version move (`VISUAL_QA_REQUIRED`).
+7. **Distribute.** Call `create_item_distribution` with a price. The server enforces a minimum
+   price, which `quote` reports; the 993's parts sold at 250 LIX and up.
+8. **Add-ons** (required, section 11). For each, an `addon.json` (`title`, `fits`, `ops`) and
+   `model.glb` in a directory:
+   1. `check_vehicle_addon({ dir })`: contract, anchoring, host hubs, hide grants, the
+      backend's fit dry run and, for a part with no model, the web customizer's meshless guard on
+      the exact definition publish would seal (`ADDON_CUSTOMIZER_REFUSES`). It must say it fits
+      every host.
+   2. `publish_vehicle_addon({ dir })`: the full check, then it uploads the model (none for a
+      tune-only part), seals the `addon` Package, makes the item from it, and reads back that
+      each host lists it.
+   3. `visual_qa_item_hosted({ itemId: <add-on> })` renders it fitted on every host. Look at the
+      wheel close-ups.
+   4. Distribute, then `check_vehicle_host` on the car: every required part fits and is for sale,
+      and every part passes the web customizer's own guard (it names any part the customizer
+      would refuse to equip, with the customizer's message).
+9. **Changing a minted car: always a new version of the same item.** Never re-run a mint, never
+   mint a second item, and never use `publish_item` for a car that exists.
+   - The new version is POSTed with its pin and `vehiclePackage` **together**, plus a `reason`
+     of 1–500 characters. Moving one without the other draws stale bytes.
+   - These fields must stay identical: `id`, `mesh.source`, `mesh.ref`, `mesh.classId`,
+     `mesh.wheelVisuals`, specialty module id, bundle id and `driverSeat`, `groundToBodyOrigin`,
+     and whether `simulation.land` is present. **A locked `Sourced` field is compared as a whole
+     object, including `note`, `sources` and `derivedFrom`**: copy it byte for byte from the
+     published package. Editing only the note of `groundToBodyOrigin` was refused with a 409.
+   - These may only grow: parts ids, socket keys, renditions, panels, seat vars, actions and
+     signals.
+   - Versions cannot be deleted. Use the next patch version.
+   - `publish_vehicle({ dir, itemId, version, reason })` seals the version staged into the car's
+     own Package (a changed GLB is uploaded and pinned) and moves the item. On a listed item the
+     move first needs a pass from `visual_qa_item({ packageVersion, vehiclePackage })`; the tool
+     says so, prints the commands, and the same call resumes at the move.
+   - **Activate a car version only by that resume** (`helix vehicle publish <dir> --item <id>
+     --package-version <v> --reason ...`): it moves the pin and `properties.vehiclePackage`
+     together. **Never `helix item set-version` for a vehicle**: it moves the pin only, so the car
+     keeps serving its old package (until the CLI says otherwise).
+   - A version move does not rebuild the slot board: new sockets or hide grants need a fresh car.
+10. **The Package pin is what draws.** After a repair, check every surface: hosted world,
+    customizer, Try Now and thumbnail.
+
+## 13. Verification before publish (a gate, not advice)
+
+The platform's visual-QA gate passes a vehicle only when **every required measured assert is
+present and passes**: `vehicle.wheels.at_hubs` (within 3 cm), `vehicle.wheels.arch_clearance` (no
+body in the tyre volume; lowest body point ≥ 5 cm), `vehicle.wheels.spin_with_speed` (0.8–1.25,
+per wheel against its axle's `tyreByAxle` radius),
+`vehicle.steering.wheel_rotates` (front wheels ≥ 10°, steering wheel ≥ 30°),
+`vehicle.articulation.reaches_limits` (within 5° of declared travel), `vehicle.seats.addressable`,
+`vehicle.occupants.penetration` (on an occupant run), `frame.non_empty`,
+`scene.no_nan_or_invisible`, `render.textured` and `scale.sane_for_category` (1.2–30 m); the
+occupant asserts block whenever present (engine current, boarded, head clearance, hips on seat,
+feet on floor, hands on the wheel); **and** the vision critic passes every check (the item matches
+its title, intact render, textures, wheels seated, ride height, symmetry, cabin,
+articulation, steering, motion, and the occupant checks: head clearance, seat contact, no
+clipping, hands on the wheel). The full list, with thresholds, is in
+`read_skill({ name: "helix-vehicles", reference: "qa" })`; the cabin thresholds are in its
+`cabin` reference.
+
+- **Only a submitted or hosted run is a gate result.** `visual_qa_item_hosted`, or
+  `visual_qa_item` submitting with a QA sign-in, records the backend's verdict and runs the critic.
+  A local run never runs the critic, so its "PASS" proves nothing about the gate.
+- **When a gate artefact blocks a correct car, report it and never distort the car.** Accuracy
+  wins: keep the real dimensions, ride height and tyre sizes, record the evidence (verdict, frame,
+  measurement), and report it as a platform defect. Round 1's F40 raised its body 36 mm to lift a
+  QA camera over a test wall, still failed, and ended up less accurate.
+- The gate **passes vacuously on a car with no declared panels**. It **never plays audio** and
+  never checks physics against the real car. Those are on you.
+
+Before submitting:
+
+- **Preview before the first mint** (`preview_vehicle`), and **look at the renders yourself**:
+  the fixed poses beside reference photos at the same poses (front, side, rear, top, both 3/4
+  views, cockpit), every wheel close-up, inboard/x-ray, each door open, steering at lock, and every
+  seat occupied. Do it for the base car **and for each add-on fitted on it**. Before publishing an
+  add-on, `preview_vehicle({ target: <car dir>, addon: [<dir>] })` (or `{ item: <published car
+  id>, addon: [<dir>] }`) fits it in the real runtime and checks it lands on its anchor (every
+  wheel within 1 cm of its hub), not at the car centre. A platform flag
+  saying "parts seated" is not evidence. The 993's flags said seated while all four wheels sat at
+  the car centre.
+- Check the car **parked and unboarded** as well as boarded. Tyres within ±1 cm of the road, and no
+  tyre in the arch at rest, at 0.07 m bump, at full lock, and at lock with bump.
+- Drive it in a world **with kerbs**, and time 0–100 against `targets` beside a control car in the
+  same world. Discard any sample after a wheel leaves the ground.
+- Listen: in a world with vehicle audio, check ignition, idle ladder, revs under load, shifts,
+  limiter and horn.
+
+## 14. What the runtime does not do (do not promise these)
+
+- **Not rendered:** `lights.lamps[]`, lamp colour (corona colours are a preset), and
+  `speedLimiterKph`. The live car is ungoverned; only the `simulate_vehicle` instrument reads the
+  field, so author `null`, set `targets.topSpeedKph` to the ungoverned figure, and expect a
+  `SPEED_LIMITER_IS_A_MARKET_GOVERNOR` warning otherwise. No add-on can toggle a limiter.
+- **Audio slots whose package sample never plays:** door, idle, intake, whine and reverse-beep
+  (the runtime's own reverse beep still sounds).
+- **No Palette resolution at runtime.**
+- **Vehicles cannot float or fly** from a package. The air and water domains only change controls.
+- **Not available to creators:** a `provides` verb, so a turbo cannot be added to an NA car, and
+  `set` ops.
+- **Physics:** tyre-grip add-ons are probably inert on landV2, and `simulation.fixedStepHz` is
+  validated but has no confirmed consumer.
+- **Behaviours of the `multiplayer-vehicles` example world that published cars never get:** its
+  fixed node-name rig, its derived landV2, its Palette projection, its one-shot sound pack and its
+  speed governor. Never cite that template as proof a published vehicle will behave the same way.