@hypersoniclabs/helix-mcp 0.2.5 → 0.2.12

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

@@ -0,0 +1,339 @@
+# Appearance acceptance (before the first mint)
+
+The car must look like the real one **on the platform**, at the poses people will see it from.
+An earlier car judged its own renders in local Blender and still shipped wrong: on the platform its
+paint read washed-out, its nose had flat panels where the reference has recessed lamps, and its
+wheels were generic. None of that shows up in a number.
+
+Run this before the first mint and after every mesh or material change. It reads
+`preview_vehicle`'s renders of your unpublished car in the real HELIX runtime, never a DCC
+viewport.
+
+## 1. Collect the reference set (research step)
+
+Gather photos of the real car, in the same configuration you are building, at these poses:
+
+| Pose | What to match |
+| --- | --- |
+| `front` | Eye height, straight on: lamp shapes, grille and intakes, track, stance. |
+| `side` | Both sides if they differ: wheelbase, overhangs, roof line, glass line, ride height. |
+| `rear` | Lamps, vents, exhausts, wing, track. |
+| `top` | Plan view, or a manufacturer blueprint: the body's plan shape and the glasshouse. |
+| `front34`, `rear34` | The views buyers see first: surfaces, shut lines, lamp depth. |
+| `cockpit` | The driver's view: dash, gauges, steering wheel (the `cabin` reference). |
+
+Add **detail photos**: each lamp pod lit and unlit, a wheel square-on (spoke count and design),
+the tail, the door cards and the seats. Prefer manufacturer press photos and side-on blueprints.
+
+## 2. Render the same poses
+
+`preview_vehicle({ target: <dir> })` always writes the fixed appearance poses `pose.front`,
+`pose.side`, `pose.rear`, `pose.top`, `pose.front34`, `pose.rear34` and `pose.cockpit` under
+`<out>/poses/`, with `poses.jpg` as a sheet. Crop each reference photo to the same framing.
+
+## 3. The reference-overlay gate (run it before the first publish)
+
+This is a **pass/fail gate**, not a suggestion. For each pose produce `overlay_<pose>.png` — the
+candidate render and the reference photo aligned and blended at 50 % — record the number, and run
+it before the first publish and after every mesh or material change. Also put each render beside
+its photo and write down every difference in proportion, shape, detail and colour.
+
+### The checklist (run it blind, in order, for `side`, `front` and `top`)
+
+1. **Align on a datum.** Scale and shift the reference photo so the shared datum spans the same
+   pixels as the render: the wheelbase (front and rear wheel centres) for `side` and `top`; the
+   track (outer tyre faces) and the ground line for `front`. Never align on a bounding box.
+2. **Cut both silhouettes** against the background (threshold the render's alpha; cut the photo's
+   body out of its background).
+3. **Blend at 50 %** into `overlay_<pose>.png`, for example `magick render.png photo.png -compose
+   dissolve -define compose:args=50 -composite overlay.png`.
+4. **Measure the silhouette as intersection over union (IoU)** of the two cut-outs, and measure the
+   **landmarks**: every wheel centre, the roof apex, the lamp-pod centres, the tail edge.
+5. **Record both numbers** per pose in the ledger.
+6. **Pass or fail** against the thresholds; a fail is a modelling error to fix before minting — do
+   not proceed.
+
+| Pose | Aligned on | IoU | Landmarks |
+| --- | --- | --- | --- |
+| `side` | wheelbase | ≥ 0.92 | each wheel centre within 1.5 % of image width; roof apex within 1 % |
+| `front` | track + ground line | ≥ 0.90 | track within 1.5 %; lamp-pod centres within 1 % |
+| `top` | wheelbase + centreline | ≥ 0.90 | body centreline within 1 %; plan width within 2 % |
+
+### What a pass and a fail look like (reproduce this each round)
+
+Read the blend: on a **pass** the two silhouettes share one edge — a single crisp line with at most
+a hairline double — and the landmarks sit on top of one another. On a **fail** a band of a single
+colour runs along an edge (one silhouette proud of the other) or a whole feature is ghosted (a
+second roof line, a second arch).
+
+```
+PASS  overlay_side.png   IoU 0.94   wheel centres 0/2 px off                 — mint
+FAIL  overlay_side.png   IoU 0.83   rear arch 14 px proud; roof line 9 px high — fix, do not mint
+```
+
+A wheel-centre offset, or a band you can see, fails at any IoU. The numbers confirm what your eyes
+already found; they never replace looking.
+
+**Detail checks** (each is a defect that has shipped):
+
+- **Lamp treatment — match the reference, generically.** If the reference has **recessed** lamps —
+  pop-up headlamps, lamp pods set into the body, covers or flaps over them — model exactly that:
+  the pod recessed below the surface, the lens shape, the bezel, the number of elements, lit and
+  unlit, and **body-colour covers/flaps where the reference shows them** (closed or open), painted
+  the body colour, never left white, clear or a default material. If the reference has exposed
+  round lamps, fixed units or a light bar, model that instead. A flat, flush lamp panel where the
+  reference has a recess (or the reverse) is a fail. **The rule: match the reference's lamp
+  treatment, panel relief and paint.**
+- **Panel relief and shut lines.** Where the reference has raised or recessed panels, vents,
+  louvers, scoops, flaps or covers, the model carries the same relief in the same place, and any
+  body-colour panel (a flap, a cover, a louver) is painted the body colour. Where the panel gaps
+  run; tinted, clear or louvred glass.
+- **Wheels**: the design, spoke count, dish, centre-lock or lug pattern, and the tyre sidewall
+  height for each axle (`physics-from-specs`, "Staggered tyres").
+- **Tail**: the lamp count and shape, the vents, the wing and its supports, the exhaust tips.
+
+## 4. Paint, materials, lamps and interior (an executable recipe — run it, do not eyeball it)
+
+The silhouette overlay alone is not enough. Round 3 passed every overlay (side IoU 0.952) and still
+shipped flat salmon paint, a hard white bloom on the nose, roof and wheel hub, two solid white
+glowing lamp panels, and a grey placeholder dash. IoU cannot see any of that. This section can, and
+each item below is a pass/fail with a named failure and a check.
+
+### 4.1 Paint — sample the code, convert to linear, then verify on the render
+
+1. **Sample the paint code from the reference photos — do not name it.** Pick body pixels from a
+   lit face, a shadowed face and a top surface, average the unshaded ones, and record the sampled
+   **sRGB** value (0–255 per channel) in the ledger.
+2. **Convert to linear.** glTF `baseColorFactor` is **linear**, not sRGB. Writing a photo's sRGB
+   value straight into it makes every colour lighter and paler: a red reads salmon. Convert each
+   channel first:
+   `linear = c ≤ 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ^ 2.4` (c in 0–1). A base-colour
+   texture must be tagged sRGB (KTX2 `--assign_oetf srgb`); data maps stay linear.
+   **The conversion is necessary, not sufficient.** A photo's pixel is a *lit* colour; the Try Now
+   daylight (strong sun plus the test grounds' stage lights, tone-mapped) is much hotter than a
+   photo's exposure, so the correct linear value of the photo colour still renders pastel (see
+   "The daylight paint gate" below, where the round-8 F40 did the conversion right and still
+   shipped salmon).
+3. **Clear-coat as a single layer.** `KHR_materials_clearcoat` is forbidden (the vehicle contract,
+   section 2). Reproduce the clear-coated look with a single layer: `roughness` **0.25–0.35,
+   UNIFORM — no roughness texture noise on the body** and `metallic` per the table below (a plain
+   `metallic` 0 gives white glints that wash a saturated colour in the daylight gate). Lumpy
+   reflections come from faceted or uneven geometry, not from the material: use weighted normals and enough panel resolution, and
+   never a noisy normal map on paint. Top surfaces show the sky as a soft reflection, and the
+   colour survives on the sides.
+4. **Verify on the platform render.** Sample the same body area in the `preview_vehicle` render and
+   compare it to the reference photo **at the same pose, under the same lighting**. Put the two
+   crops side by side and **write down both sampled sRGB values** — that plus the side-by-side is
+   the evidence; no ΔE formula is required.
+   - **The named failure — a "salmon" red.** A saturated red that renders flat, pale and
+     unsaturated (salmon) means a **wrong linear conversion** (the sRGB value written straight into
+     `baseColorFactor`) or a **wrong base colour** (sampled in shadow or from the wrong paint).
+     Fix the conversion maths first, then re-sample the unshaded body. If the conversion is
+     already right and the daylight gate still fails, the albedo is too hot for the runtime's light:
+     darken it by the amount the gate's measurement calls for (below), never by eye.
+   - **Pass:** the render's lit body face reads as the reference photo's lit body face.
+
+**The daylight paint gate (run it, don't eyeball it).** Pass the sampled reference colour to the
+preview: `preview_vehicle({ target: <dir>, referencePaint: "#rrggbb" })` (the CLI is
+`helix vehicle preview --reference-paint "#rrggbb"`). Sample the reference as the **median of the
+body-paint pixels across several reference photos** (strongly coloured, not a highlight, not a
+shadow), not one photo's brightest face. The preview then renders the **body paint alone** (every
+other mesh hidden) from the six exterior pose cameras in the real test-grounds world with its sun,
+environment, exposure, tone mapping **and local lights** untouched (the appearance poses switch the
+local lights off, so they cannot show the bonnet hotspot Try Now shows), and judges those pixels
+against the reference. Round 8's F40 passed the old hue-only check (8 degrees off) and shipped
+salmon with a white bonnet: hue is the weakest of the signals, so it is now one of four.
+
+| Assert | Chromatic reference (saturation >= 0.2) | Neutral reference (white, silver, grey, black) |
+| --- | --- | --- |
+| `vehicle.paint.hue` | circular hue within 12 degrees (`paintTolerance`) | not judged: hue is undefined |
+| `vehicle.paint.saturation` | rendered median >= 0.75 x the reference's | rendered <= reference + 0.15 (no tint) |
+| `vehicle.paint.lightness` | rendered value >= 0.55 x the reference's (not maroon) | within 0.25 of the reference's (a white or silver may not exceed it) |
+| `vehicle.paint.glare` | mean share of paint pixels washed toward white <= 30% | dark and mid neutrals only: share of near-white pixels <= 30% (white is allowed to be white) |
+
+The numbers are medians over the six views. "Washed" is a bright pixel (value >= 0.8) whose
+saturation fell below half the reference's. A body that is correct in the shaded views but blown on
+the bonnet and roof fails `glare`; the stage light's own hotspot on a *correct* paint stays under the
+limit (the round-8 F40 with corrected paint measured 14-18%; as published, 42%).
+
+**How to FIX a fail: change the paint material, never the exposure, the tone mapping or an emissive
+hack.** The failing message prints the material's real values and the target. In order:
+
+1. **Base colour, in linear.** `baseColorFactor` is the *linear* value (the message prints the
+   reference's linear value; a converted sRGB is `c <= 0.04045 ? c/12.92 : ((c+0.055)/1.055)^2.4`).
+   The runtime's daylight is hot, so author roughly **0.4-0.6x of the reference's linear value**,
+   not the value itself. The round-8 F40 had `0.445, 0.010, 0.007` for a `#bf141c` reference (linear
+   `0.521, 0.007, 0.012`): correct conversion, yet 0.85x of it rendered salmon. With a base-colour
+   texture, scale the factor (a `baseColorFactor` multiplies the texture) rather than repainting.
+2. **Metallic for a solid colour too.** At `metallic` 0 a highlight is the dielectric's white
+   (specular F0 0.04), so every glint is white and the tone mapper pushes the red toward pink. At
+   `metallic` **0.5-0.7** the highlight carries the paint's own colour. Do not go to 1: this world's
+   environment light is weak, so full metal renders near-black on the sides (value < 0.4).
+3. **Roughness about 0.3.** Lower than 0.2 makes a small, intense hotspot; a rougher lobe (0.45+)
+   spreads white wash across the whole panel and measured *worse* on a non-metal.
+4. **Specular / IOR.** `KHR_materials_ior` and `KHR_materials_specular` are honoured (the runtime
+   loads a `MeshPhysicalMaterial`); `ior` 1.2-1.3 with `specularFactor` 0.5 cut the dielectric
+   glint. Alone they did **not** cure the washed bonnet (the diffuse light is the cause), so use
+   them with 1-2, never instead of them. `KHR_materials_clearcoat` stays forbidden.
+5. **Re-run the gate; stop at pass.** Proven on the round-8 F40 (only the paint material changed):
+   `baseColorFactor 0.30, 0.0065, 0.005` + `metallic 0.7` + `roughness 0.3`, and
+   `0.22, 0.005, 0.0035` + `metallic 0.5` + `roughness 0.3` + `ior 1.3`, both PASS all four asserts
+   (saturation 0.75-0.77 vs 0.61 as published) and read as a proper red in the Try Now frame;
+   `0.16, 0.004, 0.003` + `metallic 0.9` passes saturation but renders a maroon (value 0.42).
+
+A car with no material named `*paint*` (name every body panel's material `<node>__vehicle-paint-solid`
+or `-metallic`, contract section 2), or with fewer than 3000 paint pixels over the six views, **fails
+as unjudgeable** instead of passing silently. Record the reference colour, the photos it came from
+and the four results in the ledger — a body-colour pass/fail, not a linter.
+
+| Paint | `metallic` | `roughness` | Base colour |
+| --- | --- | --- | --- |
+| Solid gloss, such as a racing red | 0.5–0.7 (a plain 0 renders white glints; it passes only with a much darker base) | 0.25–0.35 uniform | The paint code's colour, converted to linear, **times 0.4–0.6** (the daylight gate decides) |
+| Metallic or pearl | 0.6–0.9 | 0.25–0.40 | The flake colour, a little lighter than the face colour |
+| Matte or satin wrap | 0 | 0.55–0.75 | As solid |
+| Carbon or Kevlar weave | 0 | 0.30–0.45 | The weave texture, sRGB, with a fine normal map |
+
+### 4.2b Wheel design — spoke count, finish and centre cap against a real close-up
+
+The geometry gates prove the wheels sit on the hubs and spin; they do not know **what the wheel
+looks like**. A car whose wheel has the wrong spoke count, finish or no cap passes every one of
+them and loses the buyer at a glance. Take one **face-on close-up of the real wheel** (a
+`wheel-closeup` photo: the whole rim in frame, shot as square-on as you can find) and pass it:
+
+`preview_vehicle({ target: <dir>, referenceWheel: { image: "<photo>", spokeCount?, finish?, centreCap?, crop? } })`
+(the CLI is `helix vehicle preview --reference-wheel <photo> [--reference-wheel-spokes n]
+[--reference-wheel-finish silver|chrome|gunmetal|black|bronze|gold|coloured]
+[--reference-wheel-cap yes|no] [--reference-wheel-crop cx,cy,r]`).
+
+The preview renders the candidate's front-left wheel square-on (`wheelface/candidate.jpg`, the
+tyre centred) and reads the same three things from both images: the **spoke count** (the lowest
+harmonic family of the rim face's brightness around the hub), the **finish** (the lit rim colour,
+classed), and whether there is a **centre cap** (a hub disc carrying a badge or logo; a plain boss with lug holes is not a cap). Look at
+`wheelface/candidate.jpg` beside the photo; the numbers are in `preview.json` (`facts.wheelDesign`).
+
+| Assert | Fails when |
+| --- | --- |
+| `vehicle.wheels.design.spokes` | the candidate reads as a different spoke count (blocking) |
+| `vehicle.wheels.design.finish` | a different finish class (blocking); a neighbouring one (silver / chrome, silver / gunmetal, bronze / silver, bronze / gold) warns |
+| `vehicle.wheels.design.centre_cap` | the reference has a cap and the candidate's hub is open or plain, or the reverse (blocking) |
+
+- **Declare what you know.** Values you pass (`spokeCount`, `finish`, `centreCap`) override what is read
+  from the photo: do it whenever the photo is oblique, tight or the rim is two-tone. Count by the
+  repeats the eye sees (a twin-spoke wheel is read as its number of spoke pairs).
+- **`crop`** tells the gate where the wheel is in the photo: centre x of the width, centre y of the
+  height, and the **tyre's outer** radius as a fraction of the shorter side (default `0.5,0.5,0.45`).
+  If the photo cuts the tyre off, take the rim's outer radius divided by 0.72.
+- A solid dish or a mesh has no spoke pattern: the gate then says it did not judge the count (a
+  warning, not a pass). Read the render yourself.
+- Build the wheel face from the **reference's design**, not a generic spoke fan: its spoke count, the
+  spoke width relative to the gaps, a separate centre-cap disc with the badge, and the finish as a
+  metallic material (not a flat grey).
+
+### 4.2 Bloom — no white blob on the body
+
+A specular highlight must **not blow to pure white** on the nose, the roof or a wheel hub. On a real
+car those surfaces show the sky as a soft, *coloured* reflection; a clipped white blob is a
+materials/lighting error, not a highlight.
+
+- **Find the brightest body pixels in the render.** If they clip to pure white (255) where the
+  reference photo still shows colour, zero any errant emissive first. For the body paint itself the
+  fix is the material, in the daylight paint gate's order (4.1: lower linear base colour, `metallic`
+  0.5–0.7, `roughness` about 0.3) — never the light, the exposure or the tone mapping, and not a
+  rougher lobe alone (0.45+ on a non-metal spread the white wash and measured worse).
+- **Flag errant emissive.** A glowing white orb at the **steering-wheel hub**, or any surface
+  glowing that the reference does not show lit, is an **emissive material mis-set, not a light**.
+  Set its emissive to black (or the correct lamp material) before minting. Round 3's cabin shipped
+  exactly this — a bright white orb at the wheel hub.
+
+### 4.3 Lamp pods — recessed, never a flat emissive panel
+
+When the reference has pop-up or recessed lamps, author a **recessed pod = a body-colour housing
+plus a distinct lens**, never a flat emissive panel. Round 3 shipped two solid white glowing panels
+where the F40 has closed body-colour pop-up flaps.
+
+- **Lamps off in daylight must read as closed body-colour flaps** (a pop-up car) or **chrome-bezel
+  lenses** (a 993-style round lamp) — **never a glowing panel.** Model the flap in the body colour,
+  with the lens and bezel behind it.
+- **Fixed clear-lens projector or reflector lamps** (the common modern case: a faired-in headlamp
+  with a clear cover) are a third shape. Off in daylight they read as **a clear cover over a
+  chrome or silver reflector, with the projector bowls and a bezel visible behind the lens** —
+  light, glinting and detailed, **never black slats or a dark slit** (a black lamp reads as a hole).
+  Model the cover as its own glass lens node, the reflector and each projector bowl as bright
+  metal parts behind it, and the bezel as a rim. Judge it **off, in daylight, against the
+  reference photo's lamp (`headlight-detail`)**: same number of lenses, same light interior, same
+  outline.
+- Each lamp function is its own node (contract section 2), and each is **emissive on command only**
+  — bright when low/high/fog is commanded, dark otherwise.
+- A flat, flush emissive panel where the reference has a recess (or the reverse) is a fail.
+- Which of the three shapes is it? Look at the reference lamp **unlit**: a body-colour flap over
+  it is a pop-up; a chrome ring round a round lens is a bezel lamp; a clear cover over visible
+  reflector and bowls is a projector lamp. Do not carry the shape over from another car.
+
+### 4.4 The interior finish gate (the interior's own pass/fail gate)
+
+The exterior material gate above has no interior twin, and round 4 shipped a car whose cabin was
+the least finished surface on it — a grey slab dash, bare tunnel and door cards, and a glowing orb
+at the wheel hub — with the exterior cleared. The cabin is the surface a buyer looks at every time
+they sit in the car, so it gets its own gate, run at the `cockpit` and dash poses beside interior
+photos of the real car (`cabin`).
+
+**The bar.** In the `preview_vehicle` render, all of these must be true:
+
+- **The reference's interior *treatment* — colour, material and style — not a generic cockpit.**
+  The cabin must read as *this car's* interior, not "a finished interior": the F40's bare-black
+  felt dash, black Momo wheel, red cloth buckets and exposed gated shifter; a tan-leather GT's tan
+  and wood; whatever the reference photos show. A clean grey/tan cockpit that is merely "finished"
+  fails — round 7's F40 passed every structural assert yet the critic read it as a "generic
+  grey/tan cockpit" and scored the interior 4 against the real bare-black cabin.
+- **A legible instrument binnacle.** The tachometer and speedometer read as dials with **numerals
+  and needles** at the render resolution, and every gauge the real car has is present — the
+  **turbo boost gauge** on a turbo car, oil/water/volt where the car has them. Two or three dials is
+  not "a blank panel with a couple of dials"; the faces and needles must read.
+- **Real seat shells**, not featureless grey planes: the real seat's shape and material (bucket,
+  bolsters, headrest, upholstery colour), with cushion and backrest where the H-point says (`cabin`).
+- **A real dash and door cards**: the dash's shape and layout (binnacle, vents, centre console) and
+  a finished inside face for each door, not a flat plane.
+- **The controls present and legible**: pedals (throttle/brake/clutch pads), the shifter or gate
+  plate, and the steering wheel — the F40's gate plate and alloy pedals are part of the car.
+- **No flat grey placeholder and no glowing orb at the wheel hub** (the §4.2 emissive defect). A
+  bare plane where the real car has a finished surface fails even when every assert passes.
+
+**Run it, do not eyeball it:** put the `cockpit` pose and the dash render beside the matching
+interior reference photos, count what is present against the bar, and record the pass/fail in the
+ledger. The reference pair is in §4.5.
+
+### 4.5 The pass/fail reference pair (reuse these poses every round)
+
+**Materials, paint and lamps:**
+
+| | Evidence | What it teaches |
+| --- | --- | --- |
+| **FAIL** | `/Users/jack/Developer/helix-workspace/asset-lab/vehicle-pipeline/rounds/f40-r3/owner-proxy/B-front.png` (blown white lamp panels) and the critic's `/Users/Shared/vehicle-blind-runs/_packets/f40-r3/pairs/stock--front__A.jpg` | Two solid white glowing panels where the F40 has closed body-colour pop-up flaps; the whole front washes out around the lamps. |
+| **FAIL** | `/Users/jack/Developer/helix-workspace/asset-lab/vehicle-pipeline/rounds/f40-r3/owner-proxy/B-top-down.png` ("pale-pink wash") | Over-exposed paint plus a white bloom over the engine cover — the paint never reads as Rosso Corsa. |
+| **FAIL** | `/Users/jack/Developer/helix-workspace/asset-lab/vehicle-pipeline/rounds/f40-r3/owner-proxy/B-front-3q.png` (bloom on nose) | A clipped specular highlight on the nose. |
+| **FAIL** | the critic's `/Users/Shared/vehicle-blind-runs/_packets/f40-r3/pairs/stock--dash__A.jpg` | Flat grey dash, no cluster, a light orb at the wheel hub. |
+| **PASS (the bar)** | the live 993's materials, described in `/Users/jack/Developer/helix-workspace/asset-lab/vehicle-pipeline/rounds/f40-r3/critic-verdict.md` (`better_product` = B) | Clear-coat reflections that read as paint, correct round lamps in chrome bezels, a fully modelled five-dial cluster and centre console — the finish the candidate must reach. |
+
+**Interior (round 4 — the finish gate of §4.4):**
+
+| | Evidence | What it teaches |
+| --- | --- | --- |
+| **FAIL** | the F40 round-4 cabin (interior 5): `/Users/Shared/vehicle-blind-runs/_packets/f40-r4/pairs/stock--cockpit__A.jpg` and `stock--dash__A.jpg` | The dash face, tunnel and door cards read as bare flat planes, no seat shells read, and the wheel-hub badge glows as an orb — a slab cabin the critic called the least finished surface on the car. |
+| **FAIL** | the F40 round-7 cabin (interior 4): `/Users/Shared/vehicle-blind-runs/_packets/f40-r7/pairs/stock--cockpit__A.jpg` and `stock--dash__A.jpg` | A *finished but generic* cockpit — light tan/beige dash top, carpet and door trim, a plain grey three-spoke wheel, thin generic instruments — against the F40's bare-black felt cabin, black Momo wheel, red cloth buckets and gated shifter. "Not a slab" is not the bar; matching the reference's treatment is. |
+| **PASS (the bar)** | the live 993's cabin (interior 8): `/Users/Shared/vehicle-blind-runs/_packets/f40-r4/pairs/stock--cockpit__B.jpg` and `stock--dash__B.jpg` (item `280e49b0-39e9-40cd-9d41-4cc4d9ef7ab5`) | A complete five-gauge cluster with numerals and needles, a centre console with vents and controls, a door pull, a finished wheel and shifter — the interior finish the candidate must reach. |
+
+Also: tyres at metallic 0 and roughness about 0.6; rims at metallic ≤ 0.6 with the albedo lifted
+to 0.55–0.6 (metallic 1 renders black without a rich environment); glass blended, with no
+transmission.
+
+## 5. Gate
+
+The gate is concrete and pass/fail. Record in your ledger, per pose: the render, the reference
+photo, the `overlay_<pose>.png`, its IoU and landmark numbers with the pass/fail, the detail checks
+(lamp treatment, panel relief, wheels, tail), **the daylight paint gate (`referencePaint`: hue, saturation, lightness and glare pass/fail)**, **the brightest
+body-pixel check (no highlight blows to white)**, **the wheel-design gate (§4.2b: spoke count, finish and centre cap against a face-on close-up)**, **the lamp-pod check (closed body-colour flaps, bezel lenses or a clear cover over visible reflector and bowls in daylight, never black slats or a glowing panel)** and **the interior finish gate (§4.4: a legible
+binnacle with tach/speedo/turbo, real seat shells, a real dash and door cards, the controls; no flat
+grey placeholder, no wheel-hub orb)**. **Mint only when every overlay passes
+its thresholds, the paint matches the reference when sampled, no body highlight clips to white, the
+lamps read closed in daylight, the interior clears the gate, and a person seeing the pose sheet
+beside the photos would name the car at once and find no part that reads wrong.**

package/skills/helix-vehicles/references/audio-import.md

@@ -0,0 +1,138 @@
+# Vehicle audio import: base-game defaults, slot maps, Assetto Corsa
+
+The companion of the `audio` reference (read that first: the hard rule, picking the most accurate
+mod, the slot table, provenance, the gates). This covers the details of
+`import_vehicle_audio` / `helix vehicle audio-import` that the car lanes keep needing.
+
+## Options, decode tools and the mix fields
+
+- `config` picks the car configuration whose `soundConfig` is wanted (a trim can use a
+  different engine blend); `vehicle` the BeamNG vehicle id inside a mod that holds several.
+- `beamngRoot` (or `HELIX_BEAMNG_ROOT`) is the BeamNG.drive install: its `art_sound.zip` FMOD
+  banks resolve every stock event a mod names, `vehicles/common.zip` the common parts a vehicle
+  selects (the soundscape horn), its stock blends fill a mod that uses a stock engine sound, and
+  slots no part names get what the game itself plays (table below). For a non-BeamNG car it
+  fills the slots that car lacks with BeamNG's generic stock recordings.
+- `cylinders` is the **recorded** engine's cylinder count (the ladder pitch model). It is
+  derived from the BeamNG engine part when the part says; it is **required for an Assetto Corsa
+  car and for any BeamNG mod whose count would only be a guess** (the import tells you).
+- `prefer exterior|interior` picks the microphone set when a mod has both; `acNativeRungs` keeps
+  only Assetto Corsa rungs that need no varispeed; `modUrl` records where the mod was fetched.
+- FMOD decoding uses `vgmstream-cli` (`HELIX_VGMSTREAM` points at it; needed for Vorbis and
+  FADPCM banks) and `ffmpeg` (`HELIX_FFMPEG`) for OGG/FLAC. Without `vgmstream-cli`, PCM banks
+  decode byte for byte and Vorbis banks via `pip install fsb5`; anything else is refused with an
+  install message.
+- `basePackage` (`--base-package <vehicle-package.json | dir | audio.json>`): an existing package's
+  audio block, so re-importing a **published** car keeps its mix. Use it whenever you re-import a car
+  that already exists.
+- **The audio block always carries the five mix fields the runtime reads**: `engineGainDb`,
+  `exhaustGainDb`, `minLoadMix`, `maxLoadMix`, `muffling`. Each comes from, in order: the `--map` top
+  level; `--base-package`; the BeamNG mod's selected `soundConfig` (`mainGain`, `minLoadMix`,
+  `maxLoadMix`, `intakeMuffling`) and `soundConfigExhaust.mainGain`; else the engine's own BeamNG
+  defaults (-8 dB, -5 dB, 0.15, 1, 0.25). `audio-import.json` says where each came from (`mix`).
+  Missing or non-finite gains, or a mix/muffling outside 0..1, fail as `AUDIO_MIX_FIELDS_MISSING`:
+  the runtime feeds them to Web Audio, and a NaN gain throws in the frame loop (a car shipped
+  without them froze in Try Now).
+- `publish_vehicle` uploads and seals the assets of **every** slot, consumed or not (the runtime
+  closure must be complete); `audio-check` verifies each unconsumed one loads without judging it as a
+  played sound.
+
+## Electric cars
+
+An EV is detected **from the physics** (`physics.engine.cylinders` 0, an electric motor declaration,
+or a motor ladder's provenance), never from `audio.drivetrain: "electric"`: that switches the
+runtime to its synthesised motor voice and ignores recorded ladders, so it fails as
+`AUDIO_SYNTHESISED`.
+
+- The motor is still a **recorded engine ladder** (`AUDIO_ENGINE_UNSOURCED` otherwise). BeamNG's
+  electric motors name a stock blend with no rung samples (`ElectricMotor_02` ->
+  `event:>Engine>Bands>Real>electric_eng_02`, one loop re-pitched by an `RPM` automation);
+  `import_vehicle_audio` builds the ladder from that stock event (rungs at 1,000 rpm then every
+  2,000 rpm to the motor's `maxRPM`, each the recording at the rate the automation plays it there,
+  recorded as `fmod-pitch-automation-varispeed`). A map can name it: `"engineLadder": { "event":
+  "event:/Engine/Bands/Real/electric_eng_02" }`. No cylinder count is asked for.
+- `not-fitted` is allowed for every combustion slot (`exhaustLadder`, `idle`, `startup`, `shutdown`,
+  `clutch`, `turboSpool`, `blowOff`, `intake`, `revLimiter`, `backfire`) and, on a single-speed
+  drive, `shiftUp` / `shiftDown`. **`transmissionWhine` stays required**: the reduction gear whines.
+- The firing-fundamental pitch gate does not apply to a motor ladder, and rungs the source itself
+  re-pitched from one take are not called copies.
+
+## What BeamNG itself plays when no part names a sound
+
+With `beamngRoot`, `import_vehicle_audio` fills a slot no mod part names with what the game's own
+Lua plays (evidence is the game's code). These are the stock events it takes, all real base-game
+recordings:
+
+| Slot | Stock event | Slot | Stock event |
+| --- | --- | --- | --- |
+| `startup` | `Engine/Starter/Old_V2` | `tyreRollSlow` / `tyreRollFast` | `Surfaces/roll_rigid_v2` |
+| `backfire` | `Vehicle/Afterfire/01_Single_EQ1` | `impactLight`/`Medium`/`Heavy` | `Destruction/Vehicle/vehicle_part_impact` |
+| `transmissionWhine` | `Vehicle/Transmission/helical_01/twine_in` | `suspension` | `Vehicle/Suspension/car_modn_med_01/spring_compress_01` |
+| `shiftUp` / `shiftDown` | `Vehicle/Interior/Gearshift/manual_modern_01_in` / `_out` | `doorOpen` / `doorClose` | `Vehicle/Latches/Door/modern_03_open` / `_close` |
+| `brakeSqueal` | `Vehicle/Failures/failure_brakes_normal` | `handbrake` | `Vehicle/Interior/Handbrake_Ratchet/Ratchet_01_Ratchet` |
+| `tyreScrub` / `tyreSpin` / `skid` | `Surfaces/skid_rigid_v2` | `indicatorTick` | `Vehicle/Interior/Indicator/AU3_Click` |
+| `turboSpool` / `blowOff` (turbo cars) | `Vehicle/Forced_Induction/Turbo_01/turbo_spin` / `turbo_bov` | | |
+
+**`shutdown`, `clutch`, `intake` and `revLimiter` have no base-game default**: BeamNG plays nothing
+for them unless a part names one, so they stay empty (and the gate fails) until a `--map` source
+provides them: another mod of the same engine, another sim's event, or a real recording. A stock
+default is a real recording but a generic one: prefer the car's own mod event where it has one, and
+the provenance says `baseGameDefault`.
+
+## `--map`: one car from several sources
+
+```json
+{
+  "sources": {
+    "ac":   { "path": "/…/assettocorsa/content/cars/ferrari_f40", "sim": "ac" },
+    "euan": { "path": "../mods/f40-mod.zip", "sim": "beamng", "vehicle": "f40", "config": "LM (EU).pc", "modUrl": "https://…" },
+    "bng":  { "path": "/…/BeamNG.drive", "sim": "beamng-base" },
+    "rec":  { "path": "../reference-sound", "sim": "recording", "mod": "cold start, field recording", "modUrl": "https://youtu.be/…" }
+  },
+  "slots": {
+    "engineLadder": { "source": "euan", "blend": "art/sound/blends/f40engine.sfxBlend2D.json" },
+    "startup":   { "source": "euan", "sample": "F40_LM_Start" },
+    "blowOff":   { "source": "euan", "sample": "bovf40", "trim": { "startS": 0, "endS": 0.9 } },
+    "doorClose": { "source": "ac", "sample": "door_close" },
+    "shutdown":  { "event": "event:>Engine>Shutoff>v8flat_1986_eng", "sample": "<one exact stock take>" },
+    "intake":    { "source": "rec", "file": "intake-1.mp3" },
+    "horn": { "concat": [ { "event": "event:>Vehicle>Electrics>Horns>BM1_V1", "sample": "<start>" },
+                          { "event": "event:>Vehicle>Electrics>Horns>BM1_V1", "sample": "<loop>", "repeat": 9 },
+                          { "event": "event:>Vehicle>Electrics>Horns>BM1_V1", "sample": "<end>" } ] },
+    "reverseBeep": { "absent": "not-fitted", "reason": "the real car has no reverse beeper" }
+  },
+  "ladder": { "rpm": { "F40_ex_on_mid": 5700 }, "prefer": "exterior", "nativeRungs": false },
+  "cylinders": 8, "strokes": 4, "crankLayout": "flat-plane", "bankId": "ferrari-f40", "modUrl": "https://…"
+}
+```
+
+- The positional `source` of the command is `main`; a slot the map does not name comes from `main`
+  (then, with `beamngRoot`, the base game's default). Paths are relative to the map file.
+- On a BeamNG mod, `sample` / `field` is a jbeam field, the value it names, or a recording the mod
+  ships (a path, or a bare stem such as `F40_LM_Start`; extension-less jbeam references resolve the
+  same way). On an Assetto Corsa source `sample` is the FMOD subsound name (`event` narrows it).
+- `event` names a BeamNG stock FMOD event (`event:>A>B>C`, `event:/A/B/C` or `A/B/C`); `sample`
+  then picks one take of it exactly. A stock event with no `source` resolves in the `beamngRoot`
+  install.
+- `blend` (on a ladder slot, or `ladder.blend` / `ladder.engineBlend` / `ladder.exhaustBlend`)
+  picks a blend the mod ships that no selected part names (an export whose jbeam names a stale
+  `sampleName`).
+- `trim { startS, endS }` keeps a window of a longer real recording; `concat` plays pieces in
+  order (`repeat` per piece), e.g. a stock horn's start + loop + end. Both are recorded in
+  `provenance.transforms` and `pieces`.
+- `sim: "recording"` sources take real recordings of the car (`file`) with `kind: "recording"`.
+- `absent: "not-fitted"` + `reason` (or `notFitted: "<reason>"`) declares a part the real car
+  lacks; `empty: "<reason>"` leaves a slot empty on purpose, and the gate still fails it.
+
+## Assetto Corsa / ACC
+
+`content/cars/<car>/sfx/<car>.bank` (FMOD Studio 1.x) with `content/sfx/GUIDs.txt` (a bank
+without GUIDs maps by sample name). `engine_ext` (preferred) or `engine_int` gives the ladder
+(combined with the exhaust, so `exhaustLadder` is `combined-with-engine`); `backfire`, `door`
+(open and close by sample name), `gear` (shiftUp / shiftDown), `horn`, `limiter`, `skid`,
+`transmission`, `turbo` (spool and blow-off), `wheel` map to their slots. The ladder comes from
+the event's `rpms` sheet. Kunos spreads several takes recorded at one rpm across the rev range by
+auto-pitch; a HELIX rung is one recording per rpm, so a rung is either the recording at its own
+reference rpm, or the recording as FMOD plays it at its plateau anchor (a recorded varispeed,
+`fmod-autopitch-varispeed`). `acNativeRungs` keeps only unchanged rungs. `cylinders` is required.
+