@hypersoniclabs/helix-mcp 0.2.4 → 0.2.12

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

@@ -0,0 +1,69 @@
+# Reference package: the live Porsche 911 (993)
+
+The reference is the complete `helix.vehicle-package/2` of a car that passes the platform's visual
+QA gate and drives live: a two-door, rear-engined, naturally aspirated, rear-wheel-drive coupé.
+It is about 72k characters of JSON, so it ships as a file, never as tool output. Get it with:
+
+```
+get_vehicle_reference_package({ out: "/abs/car/vehicle-package.json" })
+```
+
+That copies it to your path and prints a one-line summary of each block. Read the file block by
+block. Then replace **every** number with your car's sourced values. Do not keep a 993 number
+because it "looks plausible". Edit the citations first, then the values that cite them.
+
+The copy is cleaned for reuse:
+
+- every audio slot `note` and car-specific `reason` starts with `REWRITE`;
+- the 993's own recordings (engine ladder, shifts, clutch, limiter, backfire) are reduced to the
+  authoring form, `name` + `file`, so they fail `check_vehicle_audio` until you supply your WAVs;
+- the generic one-shots (`bg_*.wav`) keep their public URLs only as shape examples: they are
+  **another car's recordings, not your car's sound**. Replace each with a sound from your car's sim
+  mod or the BeamNG base game (`import_vehicle_audio`) with its provenance (every slot is sourced;
+  the only empty slot is `absent: "not-fitted"` for a component the real car lacks); do not ship a
+  `bg_*` row under your car.
+
+**Rewrite every slot note for your car.** A note is provenance: it says what was recorded, from
+which engine, and where it came from. Round 1's F40 shipped notes about a Subaru EJ257 because it
+copied rows without reading them.
+
+## What to keep, change or delete
+
+| Block | Do |
+| --- | --- |
+| `id`, `displayName`, `make`, `model`, `years`, `market` | Change. `id` is a stable slug, and it is locked after the first publish. |
+| `provenance` | Change `note` to your source chain. `distributable` must be `true`. |
+| `citations` | Replace them all. `kind` is one of `manufacturer`, `instrumented-test`, `reference-database`, `measured-fixture`, `engineering-literature`, or `reference`. |
+| `mesh.classId` | One of `sedan`, `supercar`, `pickup`, `suv`, `van`, `truck`, `bus`, `cruiser`, `kart` (or `lightplane`). It sets the preset fallbacks and **how many seat rows the cabin derives**: `supercar` and `kart` have one row, `sedan` has two. An unknown id falls back to `sedan` with a warning. The 993's `coupe` is such a fallback, which is why it derives rear seats it does not declare. Choose deliberately. |
+| `mesh.ref` | Leave `$self`. The platform binds it to your item id. |
+| `mesh.wheelVisuals` | `author-static` when your GLB carries real wheels. |
+| `mesh.parts` | List your node names. Wheels are never parts. |
+| `mesh.visual` | Keep it whole. `format`, the five `tiers` and the `source` rendition are canonical, and the `target-web` derived rendition carries the `encodings`/`sourceRenditionId`/`textureMaxDimension` that `publish_vehicle` re-pins to the GLB it uploads (it updates `artifactRef`, `checksumSha256` and `byteLength` — the stale 993 pointer is never served). Update `triangleBudget` on both renditions to your GLB's triangle count. Deleting this block breaks the fresh mint: `validate_vehicle` accepts only a materialised `target-web`, and the publish path pushes one the sealed-root validator then rejects. |
+| `mesh.articulation.panels` | Change the hinge pivots and axes to your car's, measured in your model frame. Keep one panel per opening, and match the signals to the specialty component actions. |
+| `physics`, `simulation.land`, `targets` | Replace with your car's values (`physics-from-specs`), then run `simulate_vehicle` until every target is met. The 993 is ungoverned (`speedLimiterKph` is `null`, `topSpeedKph` equals `ungovernedTopSpeedKph`) and its curve sits on the maker's declared crank figures: keep both rules ("Top speed: governed vs ungoverned", "Torque: target the declared crank figures"). Its `simulation.land.driveline` is rear-drive only; an AWD car adds `front` and `centre` ("All-wheel drive"). |
+| `audio` | Replace the whole block with your car's sound from the most accurate sim mod, extracted by `import_vehicle_audio` (never synthesised), and give every slot its `provenance` (`audio`). |
+| `lights` | Shape only. Nothing at runtime reads `lights.lamps`, but keep it truthful: node names and colours. |
+| `vfx` | Keep the declared-but-unconsumed slots, with their reasons. |
+| `specialty` | Keep `module` (the `helix-convertible` bundle id, version and checksum) and the action list. Rename `seatVars` keys to the seats you declare, the `componentBuild` row `slot`s to your lamp node names, and the `articulators` to your panel nodes. **Keep every signal and action.** An action your car lacks (fog, with no fog lamps) lights nothing, which is harmless. Removing one changes the compiled `componentActions`, which must exactly equal the protocol compiled from `componentBuild`. Recompute `componentBuild.digest` after any row edit. |
+
+## componentBuild digest (the backend refuses a mismatch)
+
+`validate_vehicle` prints the computed digest (`COMPONENT_BUILD_DIGEST_MISMATCH`) and the compiled
+`componentActions` (`COMPONENT_ACTIONS_MISMATCH`) whenever they disagree with what you declared:
+paste them. For reference, this is a port of the backend's `digestOf`; it computes
+`607b38b594eeccc9` for the 993.
+
+```js
+function stable(v){if(v===null||typeof v!=='object')return JSON.stringify(v)??'null';if(Array.isArray(v))return `[${v.map(stable).join(',')}]`;return `{${Object.keys(v).sort().map(k=>`${JSON.stringify(k)}:${stable(v[k])}`).join(',')}}`;}
+function fnv1a64(s){let a=0x811c9dc5,b=0x01000193;for(let i=0;i<s.length;i++){const c=s.charCodeAt(i);a=Math.imul(a^c,0x01000193);b=Math.imul(b^(c+i),0x85ebca6b);}return (a>>>0).toString(16).padStart(8,'0')+(b>>>0).toString(16).padStart(8,'0');}
+function digestOf(cb){const parts=cb.signals.map(s=>`s:${stable(s)}`);const rows=[];
+  for(const f of ['articulators','interacts','lights','materials','attachments','vfx','patterns','carried','unsupported'])
+    for(const r of cb[f]??[]) rows.push(`r:${r.type}/${r.id}:${stable(r)}`);
+  parts.push(...rows.sort()); return fnv1a64(parts.join('\n'));}
+```
+
+## Audio URLs
+
+A runtime audio row needs `url`, `checksumSha256` and `bytes`, and the URL must serve exactly
+those bytes. **A row with only a `cid` and no `url` plays nothing.** Author your own rows as
+`name` + `file`; `publish_vehicle` uploads each WAV and writes the rest. Seal your own WAVs the same way; never reuse a `bg_*` row's URL.

package/skills/helix-vehicles/references/source-beamng.md

@@ -0,0 +1,167 @@
+# Source bridge: BeamNG mods
+
+The HELIX vehicle system is modelled on BeamNG, so most fields map directly. The trap is
+**budget**. BeamNG cars are built for a desktop simulator, and a raw conversion runs to roughly
+200k triangles and 100–400 draws. The platform wall is 90k triangles and 24 draws, so the work is
+mostly *restructuring*, not converting.
+
+## 1. Pick and inventory the mod
+
+- Download it with a real browser. Cloudflare blocks headless downloads from several mod hosts.
+  Unpack it fully.
+- **Measure from the extracted files, never from the mod's listing page.** Count the `.jbeam` part
+  definitions, `.pc` configurations, DAE objects and materials, and the `art/sound` WAVs.
+- Score the candidates:
+  - cabin as separate objects;
+  - doors and lids as separate objects, with jbeam hinges;
+  - each lamp separable (its own `glowMap` materials);
+  - real part slots, meaning options that change both numbers *and* visuals;
+  - mesh and texture quality.
+
+  A feature the request needs but no source has decides the pick. The F355 was rejected because
+  no obtainable mod had a separable Spider roof.
+- Expect large data. The 993 mod had a 559 MB DAE, 605 parts, 122 slot types and 9 configs, and
+  76 of its 128 stock flexbody references had no geometry.
+
+## 2. Import with Bridge
+
+`source` may be the mod's `.zip` exactly as downloaded: the CLI extracts it to a temp directory
+(refusing path traversal, duplicate entries and zip bombs), and the plan key is the same as for the
+unpacked folder.
+
+```
+bridge_detect({ source: "/abs/mod.zip" })
+bridge_plan({ source, plugins: ["hypersonic.beamng-vehicle"], pluginDirs: ["<cli>/plugins/beamng-vehicle"],
+              inputs: { palette: "/abs/helix-materials/palette.json", beamngCommon: "/abs/beamng-common.json" } })
+bridge_import({ source, output: "/abs/new-dir", inputs: {…}, expectedPlanKey: "<deterministicKey>",
+                allowPermissions: ["filesystem.read-source","filesystem.write-output","spawn-process","blender","unrestricted-host-execution"] })
+```
+
+- The plugin is external. It ships inside the CLI package under `plugins/beamng-vehicle`, needs
+  **Blender** on the host, and requires a reviewed plan key. Read
+  `read_doc({ name: "bridge" })` for the permission model.
+- The **`palette` input is required**: `helix-palette/4` or `/3`.
+- **`beamngCommon`** indexes the base game's `vehicles/common` (the shared tyres and textures). It
+  is built once with `node plugins/beamng-vehicle/bin/index-beamng-common.mjs <unpacked basegame>`.
+  Without it, base-game textures go missing and the parts ship flat grey.
+- **Cylinder count** drives the engine sound's firing frequency. The importer takes the first of
+  these that the mod declares:
+  1. the `beamngEngine` input (a JSON file such as `{ "cylinders": 6 }`);
+  2. a numeric field in the engine jbeam (`cylinderCount`, `fundamentalFrequencyCylinderCount`,
+     `firingOrder`);
+  3. a layout in the engine part's name (`I6`, `V8`, `Flat-6`);
+  4. a layout in the sound names (`box4_2006`).
+
+  If none of these exist, it falls back to 4. **Check `functionalVehicle.engineCylinders` in
+  `beamng-import-report.json`.** Mods mislabel engines. The mmbng 993 calls its flat six a "3.2L
+  V8 Engine", so its import needs `inputs: { beamngEngine: "/abs/engine.json" }` with
+  `{ "cylinders": 6 }`.
+- Jbeam that BeamNG itself accepts also loads here, including a stray `},}` after the root object
+  and runs of commas. The report counts what was ignored.
+- The importer refuses a mod with several `.pc` configurations or duplicate jbeam part names. Make
+  a reduced copy that holds **one `.pc`** (usually `Stock.pc`), its jbeam closure, and only the DAE
+  nodes it uses. Extract the add-on parts separately from the full mod.
+- It emits `<id>.glb`, `vehicle-package.json` (`helix.vehicle-package/2`), `vehicle-addons.json`,
+  `vehicle-build.json`, `vehicle-source.json` and `vehicle-lowering.json`, plus an import report.
+- Its acceptance gate allows 25k–300k triangles. **That is not the publish budget.**
+
+## 3. Field mapping
+
+| BeamNG | HELIX |
+| --- | --- |
+| DAE object per part (`inf993_door_FL`…) | GLB node; rename to contract names (`door_lf`, `bonnet`, `boot`, `rim_lf`, `steering`) |
+| jbeam hinge and latch break groups on doors, hood and trunk | `mesh.articulation.panels[]`, with the hinge pivot and axis measured in the HELIX frame |
+| Wheel nodes, hubRadius, tyre meshes in `vehicles/common` | `rim_*` nodes (rim + tyre + disc merged), `chassis.wheelRadius` |
+| `.pc` paints[0] | Baked paint in the atlas, plus `helixVehicleRole: "paint"` |
+| Material stages (`*.materials.json`, 4 stages) | Baked PBR. **Strip paint-slot tags (`name [SECONDARY]`) before lookup.** Watch for a later `null` stage factor overriding a real one. |
+| `glowMap` materials (`*_lowhi`, `*_brak`, `*_revik`, `*_sigL`…) | **One node and material per lamp function** (see section 5) |
+| `instanceDiffuse` body parts | Need the host paint carried as a solid colour (they are a neutral mask) |
+| Engine torque curve, idle and limiter, gearbox, final drive, diffs | `physics.engine` / `gearbox`, and `simulation.land.driveline`. **Calibrate to the real car's published figures.** Mod engines are often renamed templates. |
+| `pressureWheels` tyre and brake values | Starting points for `grip`, `tyreByAxle` and `brakes`. Tyre-shape coefficients are HELIX priors. |
+| Coilover and strut spring/damper leaves | `suspension`. Torsion bars and swaybar construction beams do not map. |
+| Part slots (wheels, wings, bumpers, ECUs, exhausts…) | Add-ons; derive op ratios from option vs stock jbeam values |
+| `soundConfig.sampleName` → `art/sound/blends/<name>.sfxBlend2D.json` and its recordings | `audio.bank` ladders with the source's own rpm rungs; the WAVs are written beside the package (Bridge plugin ≥ 0.7.0). `import_vehicle_audio` does this with per-slot provenance and also resolves stock FMOD events |
+| Electrics and lights | Specialty actions and `componentBuild` rows (see the `reference-package` reference) |
+
+Frame: BeamNG axes are converted to HELIX +X left, +Y up, +Z forward. If a result comes out with
+the rear at +Z, re-convert it. The importer mirrors such a result automatically.
+
+## 4. Restructure to the contract (Blender, headless)
+
+1. **Inspect every Bridge part for geometry stacked at the origin.** Unapplied flexbody transforms
+   leave calipers and similar parts there. Drop them or re-place them.
+2. **Fix stance against real dimensions.** The jbeam wheelbase can disagree with the mesh's own
+   arches (2.60 m against 2.28 m). Find each arch opening from the lowest body vertex per Z slice,
+   and put the wheels there. Check the body height against the real car: the 993 mod sat 6–8 cm
+   low.
+3. **Pivot every wheel at its hub** (translation only), with rim, tyre and disc merged into one
+   mesh per corner.
+4. **Merge everything static** into `bodyshell`: the shell, trim, interior, engine bay and static
+   gauges. Keep these separate: `glass`, the doors and door glasses, `bonnet`, `boot`, `steering`,
+   the four wheels, one node per lamp function, `exhaust`, and every add-on hide target.
+5. **Decimate to about 85k triangles with a normal-aware weld first**, so trim cannot tear into
+   spikes. The 993 went from 218,504 to 84,548.
+6. **Fix arch clearance.** If raising the body exposes the mod's inner arch liners, build a closed
+   matte-black liner tub per wheel and cut the body to it. Merely raising the body left torn shards
+   that failed `render.intact`.
+7. Drop transmission, clearcoat and similar extensions so each node is one render state.
+
+## 5. Lamps
+
+A BeamNG lamp housing is one mesh whose functions are separate glow materials. Split each function
+into its own node: classify each triangle by its source material, or by its centroid against the
+source DAE. Then author the emissive as the contract describes (`emissiveFactor`, strength 0, a
+white emissive map).
+
+Ship only the lamps the mod has. The Subaru mod had no fog lamp, CHMSL or DRL, and BeamNG
+generates its number plate at runtime.
+
+## 6. Atlas and textures
+
+Give each node **one atlas material**. Size the atlas cells to the UV *repeat*, not to the
+texture: tiling materials such as leather grain repeat tens of times. Bake the source's
+**uncompressed** images, not a KTX2 round-trip, or the cells fall back to flat colours.
+
+Encode KTX2 with mips, keep data maps linear, and declare `KHR_texture_basisu`. Expect more
+materials out than in. That is fine: draws are counted per primitive.
+
+The engine team's atlas tool (`tools/vehicle-pipeline` in the engine repository) does exactly
+this and verifies the result. It is not published as a package. If you cannot run it, do the same
+steps in Blender: bake each node to its own atlas page region, then encode with `toktx`.
+
+## 7. Physics, audio and add-ons
+
+- **Physics.** Take the importer's `vehicle-package.json` as a draft. Re-cite and re-calibrate
+  every number to the real car (`physics-from-specs`), and author or keep `simulation.land`.
+- **Audio.** This mod's sound is the first candidate for the car's audio, not automatically the
+  answer: the audio comes from the **most accurate simulator mod of this exact car**, chosen by
+  measuring against real recordings (`audio`, "Which mod is most accurate?"). Never synthesise.
+  The importer extracts the mod's own engine recordings as PCM WAV files and writes the
+  `audio.bank` ladders and the `engineLadder`/`exhaustLadder` slots, with rows that have no `url`
+  yet; `publish_vehicle` uploads them and fills the URLs. Check `sampleCylinderCount`: BeamNG does
+  not record it, so it defaults to 4 (the 993 is a flat-six). One-shots (starter, horn) and engines
+  that only name a stock BeamNG FMOD event ship no recording in the bridge output: run
+  `import_vehicle_audio({ source: <mod>, out: <car dir>, sim: "beamng", beamngRoot: <BeamNG.drive> })`
+  to resolve the stock blends and banks (`art_sound.zip`, `audio.zip`, `vehicles/common.zip`) with
+  provenance, and fill what is still missing in the `audio` reference's order.
+- **Add-ons.** `vehicle-addons.json` records are **not publishable as emitted**: they have empty
+  `requires` and no `fits.only.items`. Build each add-on as the `addons` reference describes.
+  Derive the ops from the jbeam option values against stock. Wheel options that share
+  hubRadius, offset and width are geometry-only.
+
+## Known traps (each one cost a revision)
+
+- Calipers stacked at the origin.
+- Wheelbase from jbeam instead of the arches.
+- A body 6–8 cm too low.
+- Lamp housings lit whole.
+- An sRGB-tagged roughness atlas.
+- A paint mask on add-ons.
+- Parts missing UVs.
+- Base-game maps missing.
+- `[SECONDARY]` painting the wheels white.
+- A mod engine stronger than the real car.
+- Seat H-points that were not checked against the mod's low roof: heads went through it.
+- A final GLB without `asset.extras.HELIX_vehicle`: after your last Blender or gltf-transform pass,
+  check it is still there (`validate_vehicle` refuses it otherwise). The importer's geometry
+  receipt holds the measured sockets; write them with the `host-manifest` reference.

package/skills/helix-vehicles/references/source-concept.md

@@ -0,0 +1,38 @@
+# Source bridge: images, concepts, fictional cars
+
+Use this when all you have is a Midjourney concept, a sketch, a photo set, or a name with no
+downloadable model.
+
+## What AI image-to-3D can and cannot do
+
+**Do not ship an AI-generated car body.** Five rebuilds of a generated sedan body all failed the
+platform's `render.intact` gate. The critic saw a "lumpy, warped body, torn hood, crumpled rear
+quarter": generator surface noise plus real holes at panel seams. A blind A/B picked the
+candidate over the old model at 8/10, yet it still failed the gate. Picking the better of two is
+not the gate; the gate asks "is it intact".
+
+Generated 3D is still useful for:
+
+- a **proportion blockout**: rough volume to trace over;
+- **small detail props**, such as a mirror, a light housing or a wheel centre, after cleanup;
+- **reference renders** from new angles.
+
+## The route
+
+1. **Pin down the design.** Produce or collect orthographic views: front, side, rear and top.
+   `generate_image` can turn a concept into consistent orthographic views. Lock in the
+   proportions: length, width, height, wheelbase, track and wheel size. For a fictional car,
+   choose a real analogue and say so ("proportions of a 1990s mid-engine supercar, 4.4 m").
+2. **Model clean geometry over the blueprints** in Blender. Follow the `source-scratch` reference
+   and build to the contract from the start: separate wheels with hub origins, doors, lids,
+   glass, lamp functions, and a simple interior with seats, dash and steering wheel.
+3. **Texture it.** Use PBR paint, trim and glass, with lamp emissive. Project the concept's
+   graphics (livery, badges) as decals into the atlas.
+4. **Physics** comes from the named real analogue, each value `derivedFrom` it
+   (`physics-from-specs`). **Audio** is sourced, never synthesised: the most accurate simulator mod of an analogous real
+   engine, extracted with `import_vehicle_audio` (`audio`).
+5. **Host manifest.** Write `asset.extras.HELIX_vehicle` into the final GLB (the `host-manifest`
+   reference).
+6. **QA** against the concept images, not photos of a real car: the `appearance` method, with the
+   concept's views as the reference set. Judge proportion, stance and wheel fitment from the same
+   angles as the concept.

package/skills/helix-vehicles/references/source-model.md

@@ -0,0 +1,100 @@
+# Source bridge: downloaded or ripped models
+
+This covers Sketchfab, store assets, game rips, CAD exports and any GLB, FBX, OBJ or USD file.
+Such models are usually built to *look* right from outside: one merged mesh, wheels welded in,
+no interior, and scale and axes anywhere. Your job is to make them *work*.
+
+## First choice: for a real named car, download the exact car first
+
+**For a REAL named car, download a quality CC0/licensed Sketchfab model of that exact car first.**
+A good existing model of the named car — cleaned up and re-split to the contract — beats modelling
+the body from scratch, which has read as a crude kit-car across three rounds. Search the exact
+model name before deciding to build. Only fall back to `source-scratch` when **no** model of the
+named car exists, or the car is fictional. Whatever you download, **verify the licence (CC0, or
+otherwise redistributable for a package you sell) and set `provenance.distributable`** — that is
+already a publish gate. Then continue with the cleanup and splitting below.
+
+## 1. Choose the model
+
+Score each candidate before downloading the expensive one:
+
+| Criterion | Why |
+| --- | --- |
+| Separate objects for each wheel, door, lid, steering wheel and the glass | Splitting a merged mesh is the costliest step |
+| Real interior: seats, dash, steering wheel | First-person view, and occupants |
+| Separate lamp lenses | Working lights |
+| Clean topology, no holes at panel seams | Holes fail visual QA's `render.intact` |
+| Triangle count | Under 300k is workable; you will reduce to about 85k |
+| PBR textures you can bake | |
+
+A model that is one merged mesh with thousands of disconnected islands (3,026 on one sedan) is
+not convertible by splitting. It needs a rebuild, or it ships as a static prop item instead of a
+vehicle.
+
+## 2. Normalise (Blender, headless)
+
+1. Import the model, apply every transform, and **bake scale and rotation into the vertices**.
+2. Orient it with the nose at +Z, left at +X and up at +Y. Convert to metres. Check the real
+   length.
+3. If the model is off-size, **scale it uniformly**, anchored on the real **width**. Never scale
+   per axis: round wheels become ellipses. Anchoring on length turned one sedan into a 2.44 m-wide
+   van.
+4. Centre it on X and Z, and put the lowest tyre point at Y = 0.
+5. Delete what the platform does not use: animation, armatures, cameras, lights, hidden and
+   damage-state duplicates, co-located variants (z-fighting), and the 1 mm inner twins of
+   double-sided panes. Delete enclosed parts nobody can see, unless something can open to reveal
+   them.
+
+## 3. Split into contract parts
+
+- **Wheels.** Separate each wheel: rim, tyre and disc as one object per corner. Set the origin at
+  the centre of the tyre cylinder, which you can fit from the tread vertices. Name them
+  `rim_lf`, `rim_rf`, `rim_lr` and `rim_rr`.
+- **Merged mesh.** If the wheels were welded into the body, select by connected component, by
+  the cylinder around each hub, or by material, then separate.
+- **Doors, lids, steering wheel, glass and each lamp function** each become their own objects
+  (contract section 2).
+  - If a door is fused to the body, cut it along its panel gap and cap the hole behind it.
+  - If you cannot make a clean opening, **do not declare the panel**. A static door is better
+    than a torn one.
+- **Everything else** merges into `bodyshell`. Cabin parts may stay in it.
+- **Seats.** Measure the H-point of each seat: the hip joint, about 0.1 m above the compressed
+  cushion and 0.1–0.15 m forward of the backrest. Write it into `mesh.sockets` and the host
+  manifest. A model with no real interior needs one built to the `cabin` reference.
+
+## 4. Materials
+
+Bake each node's materials to one atlas material, and use KTX2. Then:
+
+- set the paint role and the semantic family ids;
+- set up lamp emissive per the contract;
+- fix the tyres: metallic 0, roughness about 0.6.
+
+Check each material:
+
+- Is a normal map bound as base colour?
+- Are any metallic values at 1?
+- Does any primitive bind a texture with no UVs?
+
+Look at the renders: the lavender sheen of a normal map read as albedo is unmistakable once seen.
+
+## 5. The host manifest
+
+Write the class and every socket position (seats, wheel hubs, steering, engine, exhaust, lamps,
+`boot`, `bonnet`) into the final GLB's **`asset.extras.HELIX_vehicle`**. A downloaded model never
+has one, and Blender's exporter cannot put one there: patch the exported file with a snippet from
+the `host-manifest` reference. Without it the car mints as a non-host and no add-on can ever fit.
+
+## 6. Appearance acceptance
+
+A downloaded model's materials were tuned for another renderer. Render the fixed poses with
+`preview_vehicle`, put each beside the reference photo at the same pose, and overlay the side,
+front and top silhouettes. Check the lamp pods, the wheels and the tail against detail photos, and
+retune the paint to its targets (linear `baseColorFactor`). Judge the platform render, never the
+source viewer. The method is in the `appearance` reference.
+
+## 7. Then follow the skill from step 5
+
+A downloaded model has no physics or audio, so `physics-from-specs` and `audio` do all of that
+work. The audio never follows the mesh: find the most accurate simulator mod of the exact car
+(BeamNG first) and extract it with `import_vehicle_audio`; never synthesise.

package/skills/helix-vehicles/references/source-scratch.md

@@ -0,0 +1,60 @@
+# Source bridge: building a car from scratch
+
+**Use this for a fictional car, a concept with no production model, or a real car for which no
+licensed/CC0 base mesh exists. It is NOT the default for a real named car.** For a real named car,
+download a quality CC0/licensed model of that exact car and re-split it (`source-model`) — the
+from-scratch body has read as a crude kit-car across three rounds. Model from primitives only when
+there is genuinely no source (and `source-concept` covers a fictional car from images).
+
+Build to the contract from the first primitive, so there is nothing to restructure later. Work in
+Blender with headless Python scripts, and keep the script as the source of truth so the build
+can be re-run.
+
+## Order of work
+
+1. **Set up the frame.** Use metres, a +Z-forward nose and +X left. In Blender, which is
+   −Y-forward and Z-up, author in Blender axes and export glTF with +Y up. Check the exported
+   nose is +Z by measuring the GLB.
+2. **Block in the volumes** from the real dimensions or the analogue's: length, width, height,
+   wheelbase and both tracks. Place the wheels first, and build the body around their arches.
+3. **Build the wheels.**
+   - Model one wheel (rim, tyre and disc) **centred at the origin, with its axle along X**.
+   - Instance it at the four hubs as `rim_lf`, `rim_rf`, `rim_lr` and `rim_rr`, with the
+     origins at the hubs. Mirror the right side.
+   - Size the tyre from the tyre code: radius = (rim_in × 25.4 / 2 + width × aspect / 100) / 1000.
+4. **Build the body.**
+   - Make it one `bodyshell` with real wheel arches. Leave at least 10 mm of tyre clearance at
+     full lock plus 0.07 m of bump, and keep the lowest body point at least 5 cm off the road.
+   - Make the doors (`door_lf`, `door_rf`, …), `bonnet` and `boot` separate, with clean cut lines
+     and capped edges.
+   - Make `glass` separate, as blended material.
+   - Give each lamp function its own node: `headlamps`, `taillamps`, `reverselights`,
+     `indicator_l`, `indicator_r`, and so on.
+5. **Build the interior** to the interior reference photos: seat shells, dash and binnacle,
+   legible gauges, the real steering wheel design (`steering`, origin at the column), pedals,
+   door cards, floor and roof lining. Place the seat H-points where the real seats put the hips,
+   so that an adult's crown clears the roof lining by at least 10 mm and the driver's hands reach
+   the rim. The rules and thresholds are in the `cabin` reference.
+6. **Keep the budget in mind as you model.** The node list is the draw budget: aim for 12–22
+   draws, with about 60–85k triangles, most of them in the body and wheels.
+7. **Materials.** Use one material per node, baked into atlas pages of 2048 px or smaller, and
+   KTX2. Add the paint role and family ids, and the lamp emissive setup.
+8. **Export, then measure** the GLB as the `qa` reference describes before writing the package.
+9. **Write the host manifest into `asset.extras.HELIX_vehicle`** of the final GLB: the class and
+   every socket position (seats, wheel hubs, steering, engine, exhaust, lamps, `boot`, `bonnet`).
+   Blender's exporter writes custom properties to node and scene `extras`, never to
+   `asset.extras`, so patch the exported file. The snippets are in the `host-manifest` reference.
+   Without it the car mints as a non-host and no add-on can ever fit it.
+10. **Appearance acceptance — the reference-overlay gate.** Render the fixed poses with
+    `preview_vehicle`, then, for `side`, `front` and `top`, blend each render onto its reference
+    photo at the same pose and read the silhouette IoU and landmarks against the thresholds. Check
+    the lamp treatment (recessed lamps and body-colour panels where the reference has them), the
+    panel relief, the wheel design and the tail against detail photos, and the paint against the
+    sampled-from-reference targets. Judge the platform render, never the Blender viewport. The
+    checklist, thresholds and paint values are in the `appearance` reference. Mint only when every
+    overlay passes.
+
+A from-scratch car has every design choice in your hands. The commonest misses are wheels
+slightly small for the arches, a body sitting too low, and a roof too low for an adult occupant.
+All three are visible in a side-on render next to a real reference photo. Make that render first,
+and repeat the full pose comparison after every change.