@hypersoniclabs/helix-mcp 0.2.4 → 0.2.12

package/skills/helix-vehicles/SKILL.md

@@ -0,0 +1,218 @@
+---
+name: helix-vehicles
+description: Make, convert and publish a drivable HELIX vehicle item and its add-ons from any source — a real car by name, a BeamNG or other game mod, a downloaded model, a concept image, or from scratch — so it works on the first publish. Use for any request to create, import, fix, republish or add parts to a car, kart, truck or other land vehicle.
+---
+
+# HELIX Vehicles
+
+A vehicle is a published **item**, not a world: a GLB that follows the part contract, plus a
+`helix.vehicle-package/2` JSON with sourced physics, audio and controls, sealed into a Continuum
+Package, visually verified, listed, and sold with a parts set. The rules are the **HELIX Vehicle
+Contract**: `read_doc({ name: "vehicles" })`; read it once before step 3. This skill is the order
+of work and the gates. Each step names its reference:
+`read_skill({ name: "helix-vehicles", reference: "<name>" })`.
+
+**The default failure** is a car that passes every structural check and is still wrong when
+someone looks at it, drives it or opens its customizer. Every gate below reads an artifact, and
+the last gate is your own eyes on real-runtime renders beside photos of the real car.
+
+**Run `check_for_updates()` first.** The vehicle tools run the CLI bundled with this MCP; an old
+MCP means an old QA harness.
+
+**The gauntlet is mandatory: `read_skill({ name: "helix-gauntlet" })` now.** Steps 10, 11, 12 and 13 run
+its loop: a bar of real-car photos, the fixed inspection set rendered in the real runtime (every seat
+occupied, the driver steering left/centre/right, still hands), your own look at every sheet, a fresh blind
+critic where you can spawn one, and no publish, version or listing without its PASS. Updating a car that
+is already listed starts and ends with `check_listed_items({ itemIds: [<id>], rerun: true })`.
+
+## The workflow
+
+Keep a ledger file. For each step, record the artifact that proves the step passed.
+
+1. **Research the real vehicle** (`physics-from-specs`). Cite dimensions, tyre sizes per axle,
+   mass and distribution, the torque curve, gearing, Cd and area, and the performance figures
+   (0–100, quarter mile, top speed, braking, lateral g; several tests each, take the median).
+   Collect reference photos at the fixed poses (front, side, rear, top, both 3/4 views, cockpit)
+   plus lamp, wheel, tail and interior details (`appearance`), and collect real recordings of the
+   car (idle, a steady high-rpm hold, the limiter, a cold start) as the **measuring reference**
+   for the audio step (`audio`). **Gate:** citations, a photo folder, a list of recordings.
+2. **Acquire the mesh.** For a **real named car, prefer a quality licensed/CC0 base mesh of that
+   exact car** and clean it up (`source-model`) over modelling the body from scratch — the
+   from-scratch body has come out crude across three rounds. In order of preference:
+   (1) a **licensed/CC0 base mesh** of the exact car (Sketchfab, CC0, or equivalent) — first choice
+   for a real named car (`source-model`); (2) a **BeamNG or other game mod** (`source-beamng`);
+   (3) a **downloaded or ripped model** (`source-model`); (4) **from scratch** (`source-scratch`)
+   **only for a fictional or no-source car** — never the default for a real named car. Images or a
+   concept: `source-concept`, for fictional cars. Whatever the source, **check its licence/CC0 and
+   set `provenance.distributable`** (already a publish gate). Never plan around an AI-generated car
+   body: every one has failed `render.intact`. **Gate:** the source on disk, with its inventory and
+   licence.
+3. **Separate into contract parts** (contract sections 1–5): few nodes, one material each; wheel
+   origins at the hubs, each axle's tyre at its real size; doors, lids, steering, glass and one node
+   per lamp function separate; +X left, +Y up, +Z forward, metres, tyres on Y = 0. Do not invent
+   parts the source lacks. Split every lid the real car opens (bonnet, boot, engine cover) and give
+   each indicator side a front AND a rear lens (`validate_vehicle` warns `PANEL_ROLE_*`, fails
+   `LAMP_INDICATOR_REAR_MISSING`). **Gate:** a numbers file against the real dimensions.
+4. **Build the cabin** (`cabin`): the real seats, dash, legible gauges, steering wheel, pedals and
+   door cards, with H-points where the real seats put the hips. **Gate:** the **interior finish
+   gate** (`appearance` section 4.4) at the cockpit and dash poses beside interior photos — a
+   legible binnacle (tach/speedo/turbo), real seat shells, a real dash and door cards, and the
+   controls; a flat grey slab cabin fails. Every occupant assert from `preview_vehicle` passes — posture
+   (`torso_angle`, `knees_up`, `head_in_wings`) and the hands over time (`hands_on_wheel_steering`,
+   `hands_follow_wheel`, `hands_at_nine_and_three`, `fingers_still`, `hands_still`, `seat_rig_warnings`)
+   — and the `seat-*`, `driver-steering` and `stillness` sheets show a person sitting properly in every
+   seat with the hands on the rim turning with it. Fix the seat, footwell and wheel geometry, not a
+   number (`cabin`). Every declared seat counts, rear rows included: run
+   `check_vehicle_cabin({ target: <dir> })` after every cabin edit (seconds, offline) and clear every
+   FAIL, then confirm with `preview_vehicle({ target: <dir> })`, which boards every declared seat
+   (`cabin`, "A rear row").
+5. **Materials and budgets** (contract sections 7–8, paint in `appearance`): baked PBR, KTX2 with
+   mips, linear `baseColorFactor`, ≤ 24 draws, ≤ 90k triangles, ≤ 48 materials, ≤ 2048 px, one
+   drawn GLB. **Gate:** the counted primitives, triangles and materials.
+6. **Write the host manifest** (`host-manifest`) into the final GLB's
+   **`asset.extras.HELIX_vehicle`**: class and every socket position. Without it the car mints as
+   a non-host and no add-on can ever fit it. **Gate:** re-read the final GLB: `asset.extras`
+   lists every socket (`validate_vehicle` refuses a GLB without it).
+7. **Write the package** from the reference (`get_vehicle_reference_package({ out })`, then
+   `reference-package`): replace every number with your sourced values, author
+   `simulation.land`, set `groundToBodyOrigin = wheelRadius + staticRideHeight`, declare every
+   seat, keep every specialty signal and action. **Gate:** `validate_vehicle({ vehiclePackage,
+   glb })` exits 0.
+8. **Simulate** (`physics-from-specs`): `simulate_vehicle({ target: <dir> })` until every target
+   is met within its tolerance. The platform car runs **ungoverned**: a market or gentlemen's-agreement
+   speed governor is not physics, so `targets.topSpeedKph` is the ungoverned figure and the torque
+   curve sits on the maker's declared crank figures, with losses in `drivetrainEfficiency` and drag
+   (`physics-from-specs`, "Top speed" and "Torque"). An AWD car follows "All-wheel drive" there. A turbo car's lag is authored into the curve. It also runs the
+   **keyboard launch** (full-throttle W, A/D taps, hands-off yaw probe): a FAIL means the car spins
+   under a keyboard player; tune it only with sourced levers, or author `simulation.land.tractionControl`
+   (the real system, or a declared playability aid) (`physics-from-specs`, "Drivable on a keyboard"
+   and "Traction control"). **Gate:** the figures beside the targets, and the keyboard-launch verdict.
+9. **Audio** (`audio`): **never generate or synthesise vehicle sound; always source real
+   recordings, from BeamNG mods as much as possible**, whatever the mesh source. Find the most
+   accurate simulator mod of that exact car (BeamNG first; Assetto Corsa/ACC, rFactor 2 or
+   Automobilista 2 where theirs is more accurate), **pick it by measuring** candidates against
+   real recordings of the car (firing-fundamental pitch track vs rpm, spectral centroid,
+   roughness, idle character, limiter cadence), and extract it with
+   `import_vehicle_audio` (`helix vehicle audio-import`). Fill a slot the best mod lacks from, in
+   order, another BeamNG mod of the same engine or family (then the BeamNG base game's stock
+   banks), another sim's mod, a real recording of the car; never another car's sound. **Every one of
+   the 31 runtime slots carries a sourced recording**, with its provenance; the only empty slots are
+   a component the real car physically lacks (`absent: "not-fitted"` plus a reason: turbo on an NA
+   car, reverse beep, clutch on an automatic, combustion slots on an EV) and `exhaustLadder`
+   `absent: "combined-with-engine"` when the mod records one combined set. Doors are required. Never rely on the platform's default sounds: the gate fails
+   a car that would fall back to one (`AUDIO_SLOT_UNSOURCED`). **Gate:** a slot table with each slot's source, the measurements that chose the mod,
+   the **rung-pitch self-check** on every rung (`audio`, "The rung-pitch self-check"), and
+   `check_vehicle_audio({ target: <dir> })` exits 0: every slot sourced, no
+   `AUDIO_SYNTHESISED`, no `AUDIO_SLOT_UNSOURCED`, no content warnings left unexplained (`audio`, "Content gates").
+10. **Preview and accept the look — the gauntlet** (`helix-gauntlet`, `appearance`, `qa`, `cabin`):
+    `preview_vehicle({ target: <dir> })` (occupants and the inspection set are on by default) and read
+    EVERY sheet under `<out>/inspection/` beside the bar photos, then the blind critic. Then run the reference-overlay gate: compare each fixed pose with
+    the reference photo at the same pose, blend the silhouettes and read the IoU and landmarks
+    against the thresholds, and check the lamp treatment, panel relief, wheels and tail. Pass
+    `referencePaint` (the median body colour of the reference photos) so the **daylight paint
+    gate** judges hue, saturation, lightness and glare as Try Now draws the car, and
+    `referenceWheel` (a face-on close-up of the real wheel) so the **wheel-design gate** judges
+    spoke count, finish and centre cap, and confirm
+    `vehicle.lamps.each_function_lights` passes (every lamp key lights its lens). Then run
+    the **concrete material gate** (`appearance` section 4): sample the render's body sRGB beside
+    the reference photo, confirm no specular highlight blows to white, confirm the lamp pods read
+    closed in daylight (body-colour flaps, bezel lenses, or a clear cover over chrome reflectors and projector bowls; never black slats or glowing panels), and clear the
+    **interior finish gate** (`appearance` section 4.4). Fix the cabin until nothing moves. The
+    first mint locks the stance and the slot board. **Gate:** a pass on every overlay and on the
+    material gate, the pose sheet beside the photos, the clearance and cabin numbers, and a gauntlet
+    PASS in the ledger (every sheet looked at and PASS, the critic's `MATCHES` on every sheet).
+11. **Publish** (`publish`): `publish_vehicle({ dir, dryRun: true })`, then for real;
+    `check_vehicle_host({ itemId })`; pass `visual_qa_item_hosted`;
+    `create_item_distribution` — **list the base car and price it** (section 5 of `publish`).
+    **Activate a later version only by re-running `publish_vehicle({ dir, itemId, version, reason })`
+    after visual QA passes; never `helix item set-version` on a car** (it moves the pin, not
+    `properties.vehiclePackage`, so the car keeps serving its old package).
+    A car left unlisted is not obtainable; the owner cannot buy a `NOT FOR SALE` car, so it is
+    not a shipped product. To change anything later, stage a new version of the same item.
+    If a publish tool answers NOT AVAILABLE, the mint is blocked: finish every gate and report it.
+    **Gate:** a PASS record for the exact pinned version, and a live marketplace listing with a
+    price.
+12. **Add-ons: required** (`addons`). Ship 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
+    performance parts are tune-only: no model, every op a `tune` (an engine part also gets a bay mesh
+    when the engine is visible from outside; `addons`). Each one: `check_vehicle_addon`
+    (it must fit and measurably change the drive), `preview_vehicle({ target, addon: [<dir>] })`
+    for any part with a model, `publish_vehicle_addon`, its own visual QA, then **list and price
+    it** (`create_item_distribution`). Every add-on must be listed for sale, not left dry
+    (`--dry-run` only, pricing "to the owner") — round 7 shipped all nine add-ons `NOT LISTED`
+    and nothing was buyable.
+    **Gate:** `check_vehicle_host({ itemId })` shows every required part fitting **and for sale**
+    (a `distributionId` and a price) and passing the web customizer's own guard (it fails, naming
+    the part, when the customizer would refuse to equip one — round 8's four tune-only parts), and
+    the customizer shows them buyable.
+13. **Owner QA on the live item** (`qa`, `helix-gauntlet`): `preview_vehicle({ item: <id> })` on the
+    published car and `check_listed_items({ itemIds: [<id>], rerun: true })` (CURRENT and PASS); then buy it
+    with a QA account, spawn it in a hosted world with kerbs, board every seat, drive it against the
+    targets beside a control car, work the doors and lights at night, fit each add-on, listen.
+    **Gate:** live evidence per check, and the gauntlet's inspection of the LIVE car passing. Do not
+    report done before this.
+
+## Hard rules (each one prevents a failure that already shipped)
+
+- **Accuracy wins over a gate artefact.** Never move the car off the real one's figures to satisfy
+  a check; prove the artefact and report it (`qa`).
+- **Only a submitted or hosted visual-QA run is a gate result.** A local pass runs no critic.
+- **`asset.extras.HELIX_vehicle`, nowhere else.** Scene and root `extras` are ignored at mint.
+- **Never mint a second copy, and never re-run a mint to change a model.** Stage a version of the
+  same item. Locked fields stay byte-identical, `note` included.
+- **Wheel nodes have their origin at the hub**, or wheel add-ons render at the car's centre.
+- **Look at add-ons on the host from several angles, including inboard and x-ray.**
+- **Check the car parked and unboarded, not only boarded.**
+- **Every seat occupied, every time.** A posture, hands or fingers defect blocks the listing; it is never
+  "minor". The F40 went on sale with its driver lying back, hands off the wheel and fingers twitching
+  because an owner-proxy called "reclined, knees up" non-blocking and nobody looked at the hands.
+- **A listed car is re-checked when you touch it** (`check_listed_items`): its record can predate today's gates.
+- **Calibrate physics to the real car, not to a source mod.** (Audio is the opposite: the sound
+  comes from the most accurate sim mod, chosen by measurement.)
+- **Never synthesise or generate vehicle audio, and never rely on the platform's default sounds**
+  (the synthetic fallback engine, the generated default sound pack). A car ships its own sourced
+  sound for every slot; `check_vehicle_audio` and `publish_vehicle` fail an empty or
+  default-falling-back slot (`AUDIO_SLOT_UNSOURCED`) and a car without sourced engine audio.
+- **Vehicle add-ons are not auto-sealed by `publish_item`**: use `publish_vehicle_addon`.
+- **If you re-frame the host, republish every add-on authored in the host's frame.**
+- **Give the car GLB an empty `vehicle_root` over every top-level node, with the lids under it.**
+  Host-frame add-ons bind to it; without it the car is never presented (`validate_vehicle`
+  HOST_BIND_*; `host-manifest`).
+
+## Tools
+
+- **Discovery:** `search_items` (`kind: "vehicle"`, `hostKind: "vehicle"`), `search_vault`
+  (`packageType: "vehicle" | "addon"`).
+- **BeamNG import:** `bridge_detect`, `bridge_plan`, `bridge_import`.
+- **Build and check (these run the CLI and return its output and exit code):**
+  `get_vehicle_reference_package`, `validate_vehicle`, `simulate_vehicle`, `check_vehicle_cabin`, `import_vehicle_audio`,
+  `check_vehicle_audio`,
+  `preview_vehicle`, `check_vehicle_addon`.
+- **Publish:** `publish_vehicle`, `publish_vehicle_addon`,
+  `check_vehicle_host`, `visual_qa_item`, `visual_qa_item_hosted`, `visual_qa_item_status`,
+  `create_item_distribution`, `delist_item`, `check_listed_items` (re-judge listed cars against today's gates). Never hand-write a vehicle or add-on descriptor.
+- **Audio:** `import_vehicle_audio` (extract a sim mod's audio with provenance), then
+  `check_vehicle_audio`. **Never `generate_audio` for a vehicle**, for the engine or for any
+  one-shot: vehicle sound is sourced, not generated.
+
+Mesh work happens in Blender (headless) and `@gltf-transform/cli`; install them if missing
+(`toktx` from KTX-Software for KTX2).
+
+## References
+
+| Reference | Covers |
+| --- | --- |
+| `physics-from-specs` | Research, every physics field from published specs, staggered tyres, turbo lag, targets and `simulate_vehicle`. |
+| `source-beamng` | BeamNG mods: the importer, the field mapping, atlas and lamp splitting, known traps. |
+| `source-model` | **First choice for a real named car:** download a quality CC0/licensed base mesh of that exact car, then cleanup, splitting, pivots, scale. Also downloaded/ripped models. |
+| `source-concept` | Images, concepts and fictional cars. |
+| `source-scratch` | Building a car from primitives in Blender to the contract — for fictional or no-source cars, **not** the default for a real named car. |
+| `host-manifest` | `asset.extras.HELIX_vehicle`: the shape and tested export snippets. |
+| `cabin` | Interior parts, how the runtime seats occupants, `cabinFit`, the occupant thresholds, and the interior finish gate. |
+| `appearance` | The reference-overlay gate (fixed poses, IoU + landmark pass/fail), lamp treatment and panel relief, and the concrete paint/bloom/lamp-pod gate and the **interior finish gate** (sections 4.1–4.5). |
+| `audio` | The hard rule (never synthesise; always source real recordings), finding and measuring the most accurate sim mod, `import_vehicle_audio`, the slot map and per-slot fallback order, provenance, the **rung-pitch self-check**, content gates, the URL and package closure. |
+| `audio-import` | The details of `import_vehicle_audio`: BeamNG's own base-game defaults per slot, the `--map` slot-map file (several sources, trims, concats, recordings, not-fitted), Assetto Corsa specifics. |
+| `addons` | The required parts set, kinds of part, frames, ops from source data. |
+| `publish` | The order of calls, the slot board, Try Now and versions, visual QA, selling. |
+| `qa` | The render and drive checks, the full visual-QA assert list, gate artefacts. |
+| `reference-package` | What to keep or change in the reference package, and the componentBuild digest. |

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

@@ -0,0 +1,212 @@
+# Vehicle add-ons
+
+The contract is in section 11 of `read_doc({ name: "vehicles" })`. This reference is the method.
+**Plan the add-on set before you finalise the host mesh.** Every node an add-on hides must exist
+on the host as its own primitive, and every add-on authored in the host's frame breaks if the host
+moves later.
+
+## Required: the minimum parts set
+
+**A car is not done until its customizer sells a parts set.** Buyers expect to change wheels and
+tune the car; round 1's F40 shipped with "0 compatible" parts and failed the owner's check for it.
+Every car ships at least:
+
+| Part | Slot type | Kind |
+| --- | --- | --- |
+| A wheel set (rims and tyres), more than one where the real car had factory or period options | `vehicle.wheel@1` | geometry, socket frame |
+| Exhaust | `vehicle.exhaust@1` | geometry, host frame, hides `exhaust`, **and a tune op that changes the drive** (or a sound `mount`) — see the rule below |
+| ECU | `vehicle.ecu@1` | tune only |
+| Gearbox | `vehicle.transmission@1` | tune only |
+| Suspension (coilovers) | `vehicle.suspension@1` | tune only |
+| Brakes | `vehicle.brakes@1` | tune only |
+| Anti-roll bars | `vehicle.arb@1` | tune only |
+| Engine / powertrain, where the real car has a swappable engine or a well-known upgrade path (turbo kit, cam, bigger displacement) | `vehicle.engine@1` | geometry (visible engine bay) and/or tune only |
+| Spoiler or wing, where the real car has one or a well-known aftermarket one exists | `vehicle.spoiler@1` | geometry, host frame, bound to `boot` |
+
+**Cover the reference car's obvious upgrades.** The two upgrades a buyer of that car expects must be
+present, or the set is incomplete:
+
+- **Engine/powertrain** — where the real car has a swappable engine or a well-known tuning path (the
+  F40's is the twin-turbo V8), ship a `vehicle.engine@1` part (a visible engine-bay mesh and/or a
+  torque/limiter tune), sourced like every other part.
+- **Spoiler/wing** — where the real car has one, ship a `vehicle.spoiler@1` part even when the wing is
+  part of the body mesh. Author a wing-replacement add-on that **hides the body wing** (a `hide` op on
+  the host's `wing_*` node, granted via the host's `hostGrantExtensions`) and adds its own wing mesh plus
+  aero ops. "The wing is body-mesh" is not a reason to skip the slot.
+
+**Engine add-ons: tune-only by default; a mesh only where the buyer can see the engine.** An engine
+upgrade is a performance part, so its tune ops are what the buyer pays for, and a tune-only engine is
+a complete product (the live 993's Guntherwerks 4.0 is tune-only). Owners do notice an "engine
+upgrade" that changes nothing they can see, so give it a mesh when, and only when, the stock engine is
+visible from outside: through glass or a louvred cover (mid-engined cars such as the F40, Carrera GT or
+NSX), in an open bay, or under a lid the car articulates (`mesh.articulation.panels[]` role `bonnet` or
+`boot`). In that case:
+
+- model only the parts that visibly change (turbos, intercoolers, plenum, cam covers, strut brace),
+  in the host frame, with `bind { socket: <the lid or "engine">, … }` when it sits under a moving lid;
+- `hide` the stock node it replaces (`engine` or the named bay part) so the two never overlap;
+- prove it with `preview_vehicle({ target, addon: [<dir>] })` from the pose that shows the bay
+  (top-down through the glass, or with the lid open). This path is in the contract but has no live
+  example yet, so do not ship it on the strength of the contract alone.
+
+When the engine is hidden (a front-engined car with a closed bonnet that does not open), ship it
+tune-only and say so in the description ("performance part: no visible change"), rather than adding a
+mesh nobody can see that costs draws.
+
+Add more where the car has them (a body kit, an exhaust note). The live 993 sells
+13 parts across these slots. Each part's ops come from real data (below).
+
+**An exhaust is a performance part.** A `vehicle.exhaust@1` add-on must change the drive — at least one
+`tune` op that measurably moves a figure (power or weight: `drivetrain.engine.torqueCurve` /
+`limiterRpm`, or `chassis.mass`) — or be sold as a sound part with a `mount { type: "sound" }`. A hide +
+mesh with no tune op and no sound is refused by `check_vehicle_addon` (`ADDON_PERFORMANCE_NO_EFFECT`):
+round 5 shipped a "competition triple-outlet exhaust" that changed nothing about how the car drove.
+
+**Gate:** `check_vehicle_host({ itemId: <the car> })` lists every required slot type with at
+least one fitting part **for sale**, and the customizer on the car's item page shows that many
+compatible parts. Open it, fit each part, and look. It also runs the web customizer's own guard on
+every fitting add-on's exact Package pin and **fails, naming the part and the customizer's message,
+when the customizer would refuse to equip or save one**. "Fits" and "for sale" alone prove only
+what the backend rail lists: round 8 sold four tune-only parts that the rail listed and every
+older check passed while the customizer showed "could not be previewed" and disabled Save.
+
+**A part with no `model.glb` is meshless, and the customizer equips a meshless part only when its
+sealed definition is verified.** The root must be `helix.vehicle-addon-definition/1` (or the legacy
+`helix.vehicle-addon/1`) with `mesh: null` and an ops array, and no op may be a `mount` of anything
+but a sound. `check_vehicle_addon` runs that guard on the exact definition publish would seal
+(`ADDON_CUSTOMIZER_REFUSES`; an `addon.json` `definition` override that restores a `mesh` or
+changes the schema is the usual cause), and `helix vehicle addon check --item <id>` / `--host <id>`
+runs it on what is already published.
+
+The car must be an add-on host first: its GLB carries `asset.extras.HELIX_vehicle` (the
+`host-manifest` reference) and its board has sockets, nodes and tunable paths.
+
+## Kinds of part
+
+| Kind | Geometry | Frame | Ops | Example (live, Porsche 993) |
+| --- | --- | --- | --- | --- |
+| Wheel set | Rim, tyre and disc as **one mesh per wheel**, a single mesh serving all four corners, at about 9–11k triangles | `socket`, outboard `+x` | `hide rim_*` (the host's wheel nodes) | HRE 501, Guntherwerks 5-spoke, deep-dish |
+| Wing / spoiler | Wing mesh in the host's coordinates | `host` with `bind { socket: "boot", root: "vehicle_root", matrix: identity }`, so it follows the lid | aero `add` downforce, `mul` drag, `add` mass | RWB wing |
+| Lip, kit, bumper | Panel mesh in the host's coordinates | `host` (with `bind` if mounted on a moving panel) | aero, mass, and `hide` of the stock panel | RWB lip |
+| Exhaust | Exhaust mesh in the host's coordinates | `host` | `hide exhaust` **(a replacing part must hide what it replaces)**, mass | RWB exhaust |
+| Engine | Visible engine-bay mesh, or none | `host` | torque curve `add`, limiter `add`, coast `mul`, mass | Guntherwerks 4.0 |
+| ECU / gearbox / coilovers / sway bars / brakes | **None** (0 draws, glyph tile) | — | tune only | Stage 3 ECU, short-ratio gearbox, race coilovers |
+| Exhaust note / blow-off | None. A sound `mount` row with WAV assets of its own package | — | `mount { type: "sound", … }` | — |
+
+## Frames (the anchor decides where the part appears)
+
+Declare the frame in 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 hub.
+  - Model the **left** wheel; the axle runs along X, and +X is the outboard face.
+  - The runtime turns it to face outward on the right side.
+  - The mesh anchors to the socket node's origin, which is why the host's wheel origins must be
+    at the hubs.
+  - Match the host tyre's radius: scale the add-on radially to the host's `wheelRadius`, as the
+    993 set did with a factor of 1.0274.
+- **`{ "authoringFrame": "host", "bind": { "socket", "root", "matrix" } }`**
+  - The vertices sit in the host's final model frame.
+  - `bind` makes the part follow a moving socket. Without it, the part sits static at the root.
+  - **If the host is ever re-framed (raised, re-centred or re-scaled), shift every host-frame
+    add-on and republish it.**
+- Seat a body part on the host by measurement, not by eye. The mod's wings floated 0.09–0.29 m
+  above the 993's stock lid and each had to be lowered by its measured minimum gap.
+
+## Deriving the ops
+
+- Ops address the v1 tuning tree: `drivetrain.engine.*`, `drivetrain.gearbox.*`,
+  `drivetrain.brakes.*`, `contacts.*.suspension.*`, `land.antiRollBar.*`, `chassis.aero.*` and
+  `chassis.mass`. On a car with `simulation.land` the engine and gearbox deltas are projected into
+  the v2 solver automatically. What stays inert is listed in section 11 of the contract.
+- Use **ratios from source data**: the mod's jbeam option against its stock value, or a
+  manufacturer's tuning-kit figure against stock. Record each derivation in the package's
+  `addon-definition` root.
+- **Limits:**
+  - `mul` and `add` only. `set` on a number is first-party only.
+  - An array op takes a scalar, so a per-gear ratio change becomes its mean.
+  - `contacts.*` is one wildcard over all four corners. When the front and rear ratios differ,
+    take the **smaller**.
+  - A `mul` on 0 does nothing; use `add`.
+  - A `mul` on a block the host lacks is refused at fit. A turbo kit on an NA car cannot ship,
+    because there is no `provides` verb.
+- **Test the part live against stock.** A shorter gearbox made the 993 *slower* to 100 km/h
+  (5.49 → 5.60 s), because it added two 0.25 s shifts. Tuning `shiftTime ×0.6` and
+  `finalDrive ×0.92` fixed it, and both factors were chosen by sweeping live. A part whose only
+  effect is drag-limited, such as an ECU on a car that never reaches its limiter, shows nothing on
+  a 0–100 run. Say so in its description.
+- **No add-on controls a speed limiter.** The platform car runs ungoverned and the live solver never applies
+  `physics.engine.speedLimiterKph`; the ECU slot's tune paths (`torqueCurve`, `limiterRpm`, …) have no limiter path and the
+  backend refuses one. An ECU's honest effects are torque and rev limit: say that, not "removes the speed limiter".
+  `check_vehicle_addon` measures the drive effect **ungoverned** (0–100, top speed, quarter mile), so an engine, gearbox or ECU
+  part shows its top-speed change even on a package that still carries a limiter.
+
+## Geometry hygiene (each item made a published add-on grey, black or invisible)
+
+- **KTX2 with mips** on every texture. New add-ons without them are refused at upload.
+- **Every textured primitive has `TEXCOORD_0`.** Recover lost UVs from the source; never
+  synthesise an unwrap onto a borrowed atlas.
+- **Paint parts:**
+  - Give them `extras.helixVehicleRole: "paint"` on the material, and the host must have a paint
+    role too.
+  - Inheritance copies only the host's colour, roughness and metalness, never its texture. So
+    carry a solid base colour, not a neutral paint mask.
+- **Base-game textures** that live outside a mod must be supplied. For BeamNG, pass the
+  `beamngCommon` input. Otherwise the part ships flat grey.
+- **No metallic 1 on tyres.** Use 0 with roughness about 0.6; rims at metallic ≤ 0.6 with lifted
+  albedo.
+- **Rim faces must be visible from inboard.** One wheel set whose far side culled the rim faces
+  showed only a tyre ring and failed visual QA.
+- Strip BeamNG paint-slot tags from material names before lookup (`name [SECONDARY]`). Otherwise
+  slot 2 paints the wheel faces white.
+
+## The item
+
+Each add-on is a directory: `addon.json` and `model.glb`. A tune-only part has **no**
+`model.glb` and every op is a `tune`: ECU, gearbox, driveline, brakes, sway bars, coilovers or
+steering, and optionally engine, intake, induction, exhaust or tyre compound.
+
+```json
+{ "title": "<part name>", "description": "<what it is>",
+  "fits": { "slotType": "vehicle.wheel@1",
+            "requires": { "sockets": ["wheel_lf","wheel_rf","wheel_lr","wheel_rr"], "nodes": ["rim_*"], "paths": [], "pointers": [], "skeleton": null },
+            "only": { "items": ["<host item id>"] } },
+  "ops": [{ "v": "hide", "nodes": ["rim_*"] }],
+  "provenance": { "kind": "authored|imported|generated", "source": "<source>" } }
+```
+
+Example `fits` for a wing (`ops` is the aero and mass tunes):
+
+```json
+{ "slotType": "vehicle.spoiler@1",
+  "requires": { "sockets": ["boot"], "nodes": [], "paths": ["chassis.aero.downforceCoefficient","chassis.aero.dragCoefficient","chassis.mass"], "pointers": [], "skeleton": null },
+  "only": { "items": ["<host item id>"] } }
+```
+
+At most 32 ops (64 for a clip-set slot). Then:
+
+1. `check_vehicle_addon({ dir })` until it exits 0. It proves the anchoring (a socket-frame part
+   centred on its mount; the host's wheel origins at its hubs), that every hide target exists and
+   is granted on the host's board, that the host exposes every required tunable path, and the
+   backend's own count of hosts the part fits, and (for a part with no model) that the web
+   customizer's guard accepts the exact definition publish would seal. For `tune` ops it measures the drive effect on each
+   host with the live runtime's physics. A part that changes nothing it governs fails, and an op
+   that cancels another is named (contract section 11). Size the ops so the figure moves the way
+   the real part moves it. Then `preview_vehicle({ target: <car dir>, addon: [<dir>] })`, or
+   `{ item: <published car id>, addon: [<dir>] }`, fits the unpublished part in the real runtime
+   and checks it lands on its anchor (each wheel on its hub), not at the car centre. Look at the
+   render.
+2. `publish_vehicle_addon({ dir })`. It runs the full check, uploads the part's model (none for a
+   tune-only part), seals its `addon` Package, makes the item from that Version (pinned, unlisted)
+   and reads back that each host lists it. A hide the host has not granted stops it: the host car
+   seals its grants (`hostGrantExtensions` in its `publish.json`, the `publish` reference).
+3. Visual QA on each host, then distribute.
+
+## Proof (per add-on, per host)
+
+1. In the customizer, stage the part alone. Capture the front 3/4, rear 3/4, side, a close-up, and
+   each corner for wheels.
+2. **Wheel copies must sit within ±1 cm of the four stock hub centres.** Measure it; a "seated"
+   flag is not proof.
+3. Drive with it fitted. Wheel add-ons must spin and steer with the hub.
+4. For performance parts, run a live A/B against stock, a median of 3, in the same world.