@hypersoniclabs/helix-mcp 0.2.5 → 0.2.12

package/dist/vehicleTools.js

@@ -0,0 +1,229 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MINIMUM_VEHICLE_PARTS = exports.VEHICLE_AUDIO_RULE = exports.VEHICLE_OUTPUT_LIMIT = void 0;
+exports.reportVehicleRun = reportVehicleRun;
+exports.displayArg = displayArg;
+exports.displayCommand = displayCommand;
+exports.audioImportArgs = audioImportArgs;
+exports.vehicleUnavailableText = vehicleUnavailableText;
+exports.summariseReferencePackage = summariseReferencePackage;
+exports.summariseVehicleHost = summariseVehicleHost;
+exports.summariseCustomizerGuard = summariseCustomizerGuard;
+// Pure helpers behind the vehicle tools in server.ts: how an executed `helix vehicle …` run is reported back, what
+// the reference-package copy tool says about the file it wrote, and how a host's slot board + add-on rail are
+// summarised. No I/O beyond the log file a long run spills into, so smoke tests can drive them directly.
+//
+// Why the vehicle tools EXECUTE rather than hand back a command (round-1 F40 forensics §14): a DELEGATED
+// `validate_vehicle` sent the agent hunting for the CLI inside the MCP's npm cache, after which it used the raw CLI
+// for everything — skipping the MCP wrappers and pinning a stale QA harness. Running the bundled CLI here keeps an
+// agent on the MCP path, and the exit code is the gate result.
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+/** Above this many characters a run's output is cut to its head and tail; the whole of it goes to a log file. */
+exports.VEHICLE_OUTPUT_LIMIT = 30_000;
+const HEAD_CHARS = 6_000;
+function spill(label, body, logDir) {
+    try {
+        const dir = logDir ?? (0, node_path_1.join)((0, node_os_1.tmpdir)(), 'helix-mcp-vehicle');
+        (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+        const file = (0, node_path_1.join)(dir, `${label.replace(/[^a-z0-9]+/gi, '-').toLowerCase()}-${Date.now()}.log`);
+        (0, node_fs_1.writeFileSync)(file, body);
+        return file;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Turn an executed CLI run into the tool result. Exit 0 is a pass; any other exit is returned as `isError` with the
+ * full output (never a throw), because the output IS the list of things to fix.
+ */
+function reportVehicleRun(label, run, options = {}) {
+    const limit = options.limit ?? exports.VEHICLE_OUTPUT_LIMIT;
+    const minutes = (run.elapsedMs / 60_000).toFixed(1);
+    let status;
+    if (run.spawnError)
+        status = `${label}: COULD NOT RUN (${run.spawnError})`;
+    else if (run.timedOut)
+        status = `${label}: TIMED OUT after ${minutes} min — the CLI was stopped; nothing after that point happened. Re-run the same call (vehicle publish steps resume from their ledger).`;
+    else if (run.exitCode === 0)
+        status = `${label}: exit 0 (${options.exitMeaning?.[0] ?? 'pass'}) in ${minutes} min`;
+    else {
+        const meaning = run.exitCode === null ? undefined : options.exitMeaning?.[run.exitCode];
+        status = `${label}: FAILED — exit ${run.exitCode}${meaning ? ` (${meaning})` : ''} in ${minutes} min. The output below says what to fix.`;
+    }
+    const sections = [run.stdout.trim(), run.stderr.trim() ? `--- stderr ---\n${run.stderr.trim()}` : ''].filter(Boolean);
+    let body = sections.join('\n\n') || '(no output)';
+    if (body.length > limit) {
+        const file = spill(label, `$ ${run.command}\n${status}\n\n${body}\n`, options.logDir);
+        const tail = limit - HEAD_CHARS;
+        body = `${body.slice(0, HEAD_CHARS)}\n\n… ${body.length - limit} characters omitted${file ? ` — the full output is in ${file}` : ''} …\n\n${body.slice(-tail)}`;
+    }
+    const ok = !run.spawnError && !run.timedOut && run.exitCode === 0;
+    const text = [`$ ${run.command}`, status, '', body, ok && options.next ? `\nNext: ${options.next}` : ''].filter((s) => s !== '').join('\n');
+    return { text, isError: !ok };
+}
+/** Shell-quote one argument for display (the run itself never goes through a shell). */
+function displayArg(value) {
+    return /^[A-Za-z0-9_./:=@%+-]+$/.test(value) ? value : `'${value.replaceAll("'", "'\\''")}'`;
+}
+function displayCommand(args) {
+    return ['helix', ...args.map(displayArg)].join(' ');
+}
+// ---- vehicle audio: the hard rule, and the audio-import call ---------------------------------------------------
+/** The standing rule every vehicle-audio tool description and route note repeats, so no agent reaches it second-hand. */
+exports.VEHICLE_AUDIO_RULE = 'HARD RULE: NEVER generate or synthesise vehicle sound (no resynthesis, no generate_audio, not even for a slot nothing provides, and never rely on the platform\'s default sounds: the synthesised fallback engine, the generated default sound pack, runtime noise); ALWAYS source real recordings, from BeamNG mods as much as possible, and a car ships a sourced recording for EVERY one of the 31 runtime slots (the only empty slots are a component the real car physically lacks, declared consumed:false, absent:"not-fitted" plus a reason, and exhaustLadder absent:"combined-with-engine" beside a sourced engine ladder; doors are required). Audio step one, whatever the mesh source: find the most accurate simulator mod of that exact car (BeamNG first; Assetto Corsa/ACC, rFactor 2, Automobilista 2 where theirs is more accurate), choose 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.';
+/**
+ * The argv for `helix vehicle audio-import <source> --out <dir>` (sim-audio-cli lane's interface). `beamngRoot`
+ * (the BeamNG.drive install that holds the stock FMOD banks and blends a mod refers to by name) is `--beamng-root`;
+ * the rest map one to one onto the flags documented in helix-creator-cli docs/vehicle-audio-import.md.
+ */
+function audioImportArgs(a, resolvePath) {
+    return [
+        'vehicle', 'audio-import', resolvePath(a.source),
+        '--out', resolvePath(a.out),
+        ...(a.sim ? ['--sim', a.sim] : []),
+        ...(a.vehicle ? ['--vehicle', a.vehicle] : []),
+        ...(a.config ? ['--config', a.config.includes('/') ? resolvePath(a.config) : a.config] : []),
+        ...(a.map ? ['--map', resolvePath(a.map)] : []),
+        ...(a.beamngRoot ? ['--beamng-root', resolvePath(a.beamngRoot)] : []),
+        ...(a.cylinders ? ['--cylinders', String(a.cylinders)] : []),
+        ...(a.prefer ? ['--prefer', a.prefer] : []),
+        ...(a.acNativeRungs ? ['--ac-native-rungs'] : []),
+        ...(a.modUrl ? ['--mod-url', a.modUrl] : []),
+        ...(a.basePackage ? ['--base-package', resolvePath(a.basePackage)] : []),
+        ...(a.json ? ['--json'] : []),
+    ];
+}
+/** What the tools answer when the bundled CLI lacks a vehicle command, so a stale CLI never reads as a crash. */
+function vehicleUnavailableText(kind, path, tool) {
+    const command = `helix ${path.join(' ')}`;
+    if (kind === 'audio-import') {
+        return [
+            `${tool}: NOT AVAILABLE in the CLI bundled with this MCP — \`${command}\` does not exist in it.`,
+            'Nothing was done. Run check_for_updates: a newer MCP bundles a CLI that has it.',
+            `${exports.VEHICLE_AUDIO_RULE}`,
+            'Until then the rule still holds. Do NOT synthesise, generate or resynthesise the sound to fill the gap, and do not omit audio.bank or a slot to fall back on a platform default; check_vehicle_audio and publish_vehicle fail an empty or default-falling-back slot (AUDIO_SLOT_UNSOURCED) and a car without sourced engine audio. Extract the mod by hand (BeamNG art/sound blends + .flac rungs, Assetto Corsa .bank via vgmstream-cli), record each slot\'s provenance { kind, sim, mod, modUrl, sourceFile, sourceSha256, extractor } yourself, and report the import as blocked on the CLI.',
+        ].join('\n');
+    }
+    return [
+        `${tool}: NOT AVAILABLE in the CLI bundled with this MCP — \`${command}\` does not exist in it.`,
+        'Minting a new vehicle or vehicle add-on item is unavailable during the Package-first publication cutover. Nothing was done.',
+        'What still works: every offline gate (validate_vehicle, simulate_vehicle, check_vehicle_audio, preview_vehicle, check_vehicle_addon), check_vehicle_host, visual QA, distributions on existing items, and a NEW VERSION of an existing car: seal it staged with publish_continuum_package, pass visual_qa_item on that version, then activate it by re-running `helix vehicle publish <dir> --item <itemId> --package-version <v> --reason "<why>"` once the bundled CLI has it (the resume moves the pin and properties.vehiclePackage together). NEVER `helix item set-version` for a vehicle: it moves the Continuum pin but not properties.vehiclePackage, so the car keeps serving its old package (until the CLI says otherwise) (read_skill({ name: "helix-vehicles", reference: "publish" }), "A new version of an existing car").',
+        'Finish every gate, keep the directory ready, and REPORT the mint as blocked. Do not improvise it with raw API calls, an older CLI, or publish_item. Run check_for_updates: a newer MCP may bundle a CLI that has the command again.',
+    ].join('\n');
+}
+const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/** One line per top-level block: its size and what it holds, so the agent can open the file block by block. */
+function summariseReferencePackage(pkg) {
+    if (!isRecord(pkg))
+        return ['(not a JSON object)'];
+    const lines = [];
+    for (const [key, value] of Object.entries(pkg)) {
+        const chars = JSON.stringify(value)?.length ?? 0;
+        let what = '';
+        if (Array.isArray(value))
+            what = `${value.length} entries`;
+        else if (isRecord(value)) {
+            const keys = Object.keys(value);
+            what = `${keys.length} keys: ${keys.slice(0, 12).join(', ')}${keys.length > 12 ? ', …' : ''}`;
+        }
+        else
+            what = JSON.stringify(value);
+        if (key === 'audio' && isRecord(value)) {
+            const slots = Array.isArray(value.slots) ? value.slots.length : 0;
+            const assets = isRecord(value.bank) && Array.isArray(value.bank.assets) ? value.bank.assets.length : 0;
+            what += ` (${slots} slots, ${assets} bank samples)`;
+        }
+        lines.push(`- ${key} (${chars.toLocaleString('en-GB')} chars): ${what}`);
+    }
+    return lines;
+}
+// ---- vehicle host board + add-on rail --------------------------------------------------------------------------
+/**
+ * The parts set a car must ship before it is done (helix-vehicles step "Add-ons"). Slot types are the backend's
+ * `helix/vehicle-base@2` pack ids. `spoiler` is required only when the real car has a wing or aftermarket ones exist,
+ * so it is reported, never counted as missing.
+ */
+exports.MINIMUM_VEHICLE_PARTS = [
+    { slotType: 'vehicle.wheel@1', part: 'wheel set (rims + tyres)', required: true },
+    { slotType: 'vehicle.exhaust@1', part: 'exhaust', required: true },
+    { slotType: 'vehicle.ecu@1', part: 'ECU', required: true },
+    { slotType: 'vehicle.transmission@1', part: 'gearbox', required: true },
+    { slotType: 'vehicle.suspension@1', part: 'suspension (coilovers)', required: true },
+    { slotType: 'vehicle.brakes@1', part: 'brakes', required: true },
+    { slotType: 'vehicle.arb@1', part: 'anti-roll bars', required: true },
+    { slotType: 'vehicle.engine@1', part: 'engine / powertrain (where the real car has a swappable engine or a well-known upgrade)', required: false },
+    { slotType: 'vehicle.spoiler@1', part: 'spoiler / wing (where the real car has one or a well-known aftermarket one exists)', required: false },
+];
+function summariseVehicleHost(itemId, board, rail) {
+    const lines = [];
+    const b = isRecord(board) ? board : {};
+    const surface = isRecord(b.surface) ? b.surface : {};
+    const count = (k) => (Array.isArray(surface[k]) ? surface[k].length : 0);
+    const sockets = count('sockets');
+    const nodes = count('nodes');
+    const paths = count('paths');
+    const hostKind = typeof b.hostKind === 'string' ? b.hostKind : null;
+    const grants = isRecord(b.hostGrantExtensions) ? b.hostGrantExtensions : {};
+    const problems = [];
+    lines.push(`Vehicle host ${itemId}`);
+    lines.push(`- slot board: hostKind ${hostKind ?? 'none'}, use ${String(b.use ?? '—')}, ${Number(b.slotCount ?? 0)} slots`);
+    lines.push(`- measured surface: ${sockets} sockets, ${nodes} nodes, ${paths} tunable paths, ${count('materialSlots')} material slots`);
+    lines.push(`- hide grants: ${Object.keys(grants).length ? JSON.stringify(grants) : 'none (only the standard *_stock_* globs)'}`);
+    const repair = 'The board is derived ONCE, at mint, from the GLB\'s asset.extras.HELIX_vehicle, the vehicle package and its hostGrantExtensions; a version move does not rebuild it. Today the repair is a fresh car minted with the manifest (read_skill helix-vehicles reference "publish", section 2): delist this one and report it.';
+    if (hostKind !== 'vehicle')
+        problems.push(`the item is not a vehicle host: its GLB carried no asset.extras.HELIX_vehicle at upload (read_skill helix-vehicles reference "host-manifest"). ${repair}`);
+    if (hostKind === 'vehicle' && sockets === 0)
+        problems.push(`the board has no sockets, so wheel, wing and exhaust add-ons fit nothing: asset.extras.HELIX_vehicle.sockets was empty. ${repair}`);
+    if (hostKind === 'vehicle' && nodes === 0)
+        problems.push('the board has no nodes, so no add-on can hide a stock part.');
+    if (hostKind === 'vehicle' && paths === 0)
+        problems.push(`the board has no tunable paths, so no performance part (ECU, gearbox, brakes, suspension, anti-roll bars) can fit. ${repair}`);
+    const r = isRecord(rail) ? rail : {};
+    const items = Array.isArray(r.items) ? r.items.filter(isRecord) : [];
+    const total = typeof r.total === 'number' ? r.total : items.length;
+    lines.push(`- add-ons that fit it (the customizer's list): ${total}${r.truncated ? ' (truncated)' : ''}`);
+    const bySlot = new Map();
+    for (const item of items) {
+        const slotType = typeof item.slotType === 'string' ? item.slotType : 'unknown';
+        bySlot.set(slotType, [...(bySlot.get(slotType) ?? []), item]);
+    }
+    for (const [slotType, rows] of [...bySlot.entries()].sort()) {
+        lines.push(`  - ${slotType}: ${rows.map((i) => `${String(i.title)}${i.distributionId ? ` (${String(i.priceLix ?? '?')} LIX)` : ' (not for sale)'}`).join('; ')}`);
+    }
+    lines.push('', 'Minimum parts set:');
+    const missing = [];
+    for (const want of exports.MINIMUM_VEHICLE_PARTS) {
+        const rows = bySlot.get(want.slotType) ?? [];
+        const sold = rows.filter((i) => i.distributionId).length;
+        const mark = rows.length ? (sold ? '✔' : '◐') : want.required ? '✖' : '·';
+        lines.push(`  ${mark} ${want.part} — ${want.slotType}: ${rows.length} fitting, ${sold} for sale`);
+        if (want.required && sold === 0)
+            missing.push(want.part);
+    }
+    if (missing.length)
+        problems.push(`the minimum parts set is not complete and for sale: ${missing.join(', ')}.`);
+    if (problems.length)
+        lines.push('', 'Not done:', ...problems.map((p) => `- ${p}`));
+    else
+        lines.push('', 'The host board is complete and every required part fits and is for sale. Now open the customizer and look at each part fitted.');
+    return { text: lines.join('\n'), ok: problems.length === 0 };
+}
+/**
+ * The customizer-guard half of `check_vehicle_host`: the CLI's `checkHostAddOns` verdicts (every add-on on the car's rail
+ * judged by the web customizer's own guard) as a section of the report. Any refused add-on, or a rail truncated before
+ * every add-on could be checked, fails the host check; the message names each add-on and quotes the customizer's text.
+ */
+function summariseCustomizerGuard(formatted, verdicts, truncated) {
+    const refused = verdicts.filter((v) => !v.ok);
+    const lines = ['Web customizer guard (the same check the customizer runs when a buyer stages each part):', ...formatted.split('\n').map((l) => `  ${l}`)];
+    if (refused.length) {
+        lines.push('', 'Not done:', ...refused.map((v) => `- add-on ${v.itemId} "${v.title ?? '?'}" would be refused by the web customizer ("${v.error}"): it cannot be equipped or saved there, so it is not a shipped part. Republish it as a new Package Version the customizer accepts (read_skill helix-vehicles reference "addons").`));
+    }
+    if (truncated)
+        lines.push('', 'Not done:', '- the add-on rail was truncated, so not every add-on could be checked against the customizer guard.');
+    return { text: lines.join('\n'), ok: refused.length === 0 && !truncated };
+}
+//# sourceMappingURL=vehicleTools.js.map

package/dist/vehicleTools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vehicleTools.js","sourceRoot":"","sources":["../src/vehicleTools.ts"],"names":[],"mappings":"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"}

package/docs/avatar-face.md

@@ -0,0 +1,115 @@
+# Avatar faces — lip-sync, blink and expressions
+
+A HELIX character speaks with its mouth only if the GLB it was published from carries a
+`helix/avatar-face@1` manifest. Nothing at runtime, in the world, or in the shell can add one later.
+An avatar that arrives without it is **permanently mute**: it will stand in a voice chat with a closed
+mouth and never blink, and no error is raised anywhere.
+
+That is the whole trap this document exists for. Everything else here is detail.
+
+## What actually drives the mouth
+
+Face V1 is a **receiver-local presentation layer**. No facial weight, microphone sample or derived
+biometric is ever sent through HELIX multiplayer state:
+
+- Each client analyses the remote voice audio **it already plays** and solves visemes locally.
+- The local player's own avatar is driven from their **own microphone analyser** — nobody is
+  subscribed to their own track, and that mouth is visible in third person, in mirrors and through
+  the in-world camera.
+- Both lanes are gated by publish-mute × the sensitivity gate, so a muted player does not mouth
+  silently at everyone.
+
+**No world authoring is required.** `mp.attachVoice(Helix.voice, ...)` wires replica faces, the local
+face, the screen-space face LOD and pad push-to-talk in one call. Do not build a face system, do not
+network viseme weights, and do not drive morph targets from world code.
+
+## The capability ladder
+
+`helix character import` prints a `face:` line and the avatar preflight reports the same capability.
+It degrades in this order, and each rung is honest about what the asset can do:
+
+| capability | what the asset carries | what a speaker looks like |
+|---|---|---|
+| `viseme15` | the 15 Oculus visemes | full lip-sync |
+| `vowel5` | the five VRM/VRoid vowels | lip-sync folded onto five shapes (the runtime does the fold — a 15-viseme solver drives a 5-vowel asset) |
+| `jaw` | a `jawOpen` morph or jaw bone | the jaw opens with speech amplitude |
+| `none` | nothing | **closed mouth, forever** |
+
+Blink channels (`blink.left` / `blink.right`) and gaze channels are separate from the ladder. With
+them the runtime blinks and idles the eyes on its own; without them the eyes are dead. V1 never
+fabricates blink motion for an asset that has no explicit targets.
+
+Screen-space LOD: full facial work above 96 projected avatar pixels, jaw-only from 32, nothing below.
+
+## Getting a face onto an imported character
+
+### VRM (`.vrm`) — automatic, use the Bridge
+
+`bridge_import` routes a `.vrm` through the `helix.character.vrm.import` capability, which carries the
+five vowels, both blinks and the six expression presets across on its own. It runs in-process on
+read/write permissions alone and needs no reviewed plan key. **Never hand-roll a VRM conversion.**
+
+### A GLB/FBX biped — `faceMap`, or it is probably mute
+
+`import_character` (and `helix character import`) detects only **exact, established** morph names —
+`viseme_*`, VRChat's `vrc.v_*`, plain `aa/ih/ou/ee/oh`, `jawOpen`/`mouthOpen`, `blinkLeft`/`Blink_L`
+and their obvious spellings. It deliberately does not guess from arbitrary names, so a rig whose
+shapes are called anything else — including a **VRoid model exported as GLB rather than VRM**, whose
+shapes are `Fcl_MTH_A`, `Fcl_EYE_Close_L`, … — imports with `face: none` unless you say otherwise.
+
+So: after any character import, **read the `face:` line**. If it says `none` and the source model has
+blend shapes, inspect their names and pass `faceMap` — a JSON file mapping HELIX semantics onto the
+morphs the asset actually has:
+
+```json
+{
+  "contract": "helix/avatar-face@1",
+  "channels": {
+    "vowel.aa":   { "kind": "morph", "name": "Fcl_MTH_A", "scale": 1 },
+    "vowel.ih":   { "kind": "morph", "name": "Fcl_MTH_I", "scale": 1 },
+    "vowel.ou":   { "kind": "morph", "name": "Fcl_MTH_U", "scale": 1 },
+    "vowel.ee":   { "kind": "morph", "name": "Fcl_MTH_E", "scale": 1 },
+    "vowel.oh":   { "kind": "morph", "name": "Fcl_MTH_O", "scale": 1 },
+    "blink.left": { "kind": "morph", "name": "Fcl_EYE_Close_L", "scale": 1 },
+    "blink.right":{ "kind": "morph", "name": "Fcl_EYE_Close_R", "scale": 1 }
+  },
+  "lod": { "fullMinPixels": 96, "jawMinPixels": 32 }
+}
+```
+
+A `jawOpen` channel may instead be a **bone**: `{ "kind": "bone", "name": "FACIAL_C_Jaw", "axis": "y",
+"maxDegrees": 18 }`. The importer verifies every declared morph or bone exists after conversion and
+fails loudly if one does not, so a face map cannot silently name nothing.
+
+A stylised avatar with no mouth shapes at all is legitimately `none` — say so plainly rather than
+inventing channels.
+
+### MetaHuman / Unreal
+
+Supply the source through Bridge with `type: "character"` and the face as the named `face` input, and
+the head/eye material path is preserved. A MetaHuman legacy head can carry 800+ blend shapes; the
+importer drops every delta the manifest cannot drive, so declaring the channels is also what keeps the
+web asset small.
+
+## Add-ons do not carry faces
+
+`helix.character.addon.import` packages a modular wearable (`character.<slot>@1`) against a validated
+base avatar. A hat, a jacket or a pair of ears is not a face and never declares face channels — the
+face belongs to the base body the add-on is worn on. If the base is `none`, installing add-ons does
+not change that.
+
+## Honest limits, as of this writing
+
+- **Face V1 is a `0.3`-line runtime feature.** A world published on the older `^0.2` engine line
+  resolves to `0.2.x` and has no face runtime at all. Re-publishing on the current line is the only
+  way such a world gains lip-sync.
+- **The stock Base Female body ships with no face channels.** Base Male carries the full 21-channel
+  `viseme15` set; the female face pack currently has no morph targets and no facial rig, so she is
+  `none` — mute and unblinking. Do not tell a human that "the default avatars lip-sync"; only the male
+  one does.
+- The portable browser solver reaches 8 of the 15 viseme shapes from its acoustic features
+  (`sil, pp, ff, th, kk, ss, rr, aa`). The remaining shapes exist in the asset and are reachable by a
+  better solver, not by this one.
+- Expressions (`happy`/`angry`/`sad`/`relaxed`/`surprised`/`neutral`) ride the same manifest as a
+  separate `expressions` block and a separate driver. They are carried by the VRM path and are not
+  driven by speech.

package/docs/bridge.md

@@ -0,0 +1,98 @@
+# HELIX Bridge — agent workflow
+
+Bridge is the one path for turning an existing external asset, character, animation, scene, mod export, or engine project into HELIX content. Do not invent a one-off conversion shell script before asking Bridge what is installed.
+
+## Default loop
+
+1. `bridge_detect` fingerprints the source.
+2. `bridge_inspect` returns the structural evidence and viable goals.
+3. `bridge_plan` resolves the capability graph without writing or executing anything.
+4. If the plan has blockers, use `bridge_plugins_list` and `bridge_plugin_inspect`; install a plugin only when the requested source path is available and its declared permissions match the task.
+5. For any command-backed capability, pass the reviewed plan's `deterministicKey` back as `expectedPlanKey`, approve every exact permission in `requiredPermissions`, and call `bridge_import`. An in-process built-in-only route with no command needs no additional acknowledgement.
+6. Read every warning and output digest, then call `bridge_validate` on the artifact or provenance record.
+7. Publish through the existing HELIX package, item, scene, or world path. Bridge conversion is not publication authority.
+
+For the common case, `bridge_import` performs the first three steps internally. Use the explicit detect/inspect/plan sequence when the source is unfamiliar, an engine project, or a community plugin would run.
+
+## What Bridge can actually convert
+
+`bridge_plugins_list` and `bridge_doctor` are the authority — read them before planning, because a
+plugin can be installed or absent on this machine. The HELIX Verified set the CLI ships with is:
+
+| plugin | capability | accepts → produces |
+|---|---|---|
+| `helix.formats` | `helix.asset.copy` | glb / gltf / fbx / obj / usd / usdz / vrm / image / audio → a checksummed package input (preserved, not converted) |
+| `helix.characters` | `helix.character.import` | glb / fbx biped → `helix-humanoid@1` character (retarget, conform, LODs, KTX2) |
+| `helix.characters` | `helix.character.vrm.import` | **`.vrm` → `helix-humanoid@1`**, carrying SpringBone physics, the five vowel visemes, both blinks and the expression presets |
+| `helix.characters` | `helix.animation.retarget` | glb / fbx clip → `helix-humanoid@1` animation |
+| `helix.characters` | `helix.character.addon.import` | glb / fbx part + a published host → a modular add-on and its runtime `character.<slot>@1` contract |
+| `helix.metahuman` | `metahuman.face.materials` | a MetaHuman face → a character-face package with the eyes preserved |
+| `helix.scenes` | `helix.scene.package` | glb / fbx / obj → a deterministic HELIX Scene package |
+| `helix.engines` | `unity.project.extract`, `godot.project.extract` | a Unity or Godot **project** → extracted assets |
+| `helix.bridge.unreal` | `unreal.project.extract` | an Unreal **project** → FBX assets (launches Unreal Editor) |
+
+Shipped alongside, but **not** HELIX Verified: `hypersonic.beamng-vehicle`
+(`beamng.vehicle.import`, trust `local-untrusted`) converts a BeamNG vehicle directory to a glb. It
+spawns Blender, so it requires `spawn-process`, `blender` and `unrestricted-host-execution` plus a
+reviewed plan key and a named `palette` input — approve it deliberately, never as a formality.
+
+**The VRM route is in-process** — a VRM is a glTF and the whole conversion is TypeScript over
+`gltf-transform` — so `helix bridge import avatar.vrm` runs on read-source/write-output alone and
+needs no reviewed plan key. A **VRChat Unity avatar is the opposite case** and belongs to a
+Unity-permissioned extraction, not this capability; some creators ship a `.vrm` alongside, and when
+they do, the VRM capability handles it and the Unity adapter is not needed at all.
+
+**There is no bridge for most game formats.** Cities: Skylines, Source, Bethesda archives, and the
+rest have no capability today. When nothing accepts the source, say so plainly — do not hand-roll a
+converter, and do not route the source through an unrelated capability because it is the only one
+that would accept the file extension.
+
+## Faces
+
+A character imported through any of these routes is **mute unless a `helix/avatar-face@1` manifest
+rides its GLB**, and nothing downstream can add one later. The VRM capability carries a face across on
+its own. `helix.character.import` detects only established morph names, so a rig named anything else —
+including a VRoid model exported as GLB rather than VRM — needs an explicit face map. An add-on never
+carries a face; the face belongs to the base body. Read `read_doc({ name: "avatar-face" })` before
+importing any character a human will speak through.
+
+## Safety and permissions
+
+Plugin installation and plugin execution are separate decisions. Installed plugins are discoverable, but every command-backed capability—including a packaged HELIX Verified adapter—runs only when `allowPermissions` contains every permission in the selected plan.
+
+Never add permission names merely to make a plan green. Report the plugin id, capability, requested permissions, and why they are needed. A plan may be inspected safely without permission grants.
+
+Command-backed execution is bound to the reviewed plan. `bridge_import` rejects a missing or changed `expectedPlanKey` before reserving output, snapshotting content, or starting a process. If the source, plugin digest, route, target, tool identity, or inputs change, call `bridge_plan` again and review the new key.
+
+Pass the same `headTexture`, `eyeTexture`, `canonical`, `boneMap`, and named `inputs` to both `bridge_plan` and `bridge_import`. Bridge fingerprints them before planning, so changing any auxiliary file or a safe FBX/glTF sidecar changes the reviewed key.
+
+Bridge executes plugins without a shell, bounds runtime and stdout, requires artifacts to remain inside the output directory, and re-hashes outputs itself. Command-backed capabilities must request `unrestricted-host-execution` in addition to process and filesystem permissions. That name is deliberate: until an isolated runner ships, approval grants the adapter the authority of a local process rather than pretending the narrower declarations are an OS sandbox. Prefer HELIX Verified capabilities when they satisfy the plan, while still approving the exact permissions they request.
+
+## MetaHuman and Unreal character material path
+
+The official MetaHuman face capability carries the eye-material safeguard migrated from `helix-web-engine-new` PR #99:
+
+- provide the baked head texture with `headTexture`;
+- omit `eyeTexture` to use the CLI-packaged canonical bake, or supply an explicit override;
+- Bridge refuses textureless `MI_EyeL_Baked` / `MI_EyeR_Baked` materials;
+- validate a combined base avatar with `bridge_validate({ baseAvatar: true })` before publication.
+
+## Official Unreal and modular-character path
+
+The bundled CLI packages `helix.bridge.unreal`, a HELIX Verified, command-backed Unreal skeletal-mesh adapter. Supply an Unreal asset or asset-set profile as the named `unrealAsset` input. Use `type: "extract"` to retain every FBX from a batch, then run each retained asset through its character or add-on import. Because the adapter launches Unreal Editor, its plan requires a reviewed plan key plus the exact filesystem, process, host-execution, and `unreal-editor` permissions reported by `bridge_plan`.
+
+Use `type: "addon"` with named `host` and `addon` inputs to package a modular wearable against a validated base avatar. The add-on profile carries the runtime `character.<slot>@1` contract used by the customizer. Split body and face exports can use `type: "character"` with the face supplied as the named `face` input; Bridge preserves the shared rig, LODs, morphs, and material roles in the composed package.
+
+## Tool boundary
+
+Bridge implementation lives in `{{CLI_PKG}}`. These MCP tools either execute that bundled CLI or return its output. Do not port converter logic into the MCP server.
+
+The canonical schemas are:
+
+- `helix.bridge-detection/1`
+- `helix.bridge-plan/1`
+- `helix.bridge-plugin/1`
+- `helix.bridge-plugin-request/1`
+- `helix.bridge-provenance/1`
+
+Use `bridge_doctor` to see in-process plugins, the packaged official Unreal adapter, and optional engine adapters. Engine projects can always be detected and planned; execution requires an eligible extraction capability and every permission reported by that plan.

package/docs/bring-your-world.md

@@ -0,0 +1,117 @@
+# Bring your world to HELIX — adopt the platform in an existing three.js project
+
+Follow this when a game **already exists outside HELIX** — a plain three.js/vite project, a game-jam build, a
+port from another platform — and you want it published as a HELIX Instant world. You do NOT rewrite it into a
+scaffold shape: adoption is **staged**, each stage ships value on its own, and your scene/loop/code stay yours
+throughout. (Converting a world that is already HELIX-shaped from single-player to multiplayer? Skip to the
+hub's conversion section: `get_started({ kind: "multiplayer" })`.)
+
+**The three stages:**
+
+1. **Become a world** — your game runs on the platform as-is (own character/controller, single-player).
+2. **Adopt the character** — swap your controller for the `humanoid-character` system (avatars, abilities).
+3. **Go multiplayer** — one facade call + the manifest opt-in, then the authority audit.
+
+Stop at any stage; each is a publishable world.
+
+## Stage 1 — Become a world
+
+A HELIX world is a **static bundle** (an `index.html` entry + assets) plus a **manifest** (`public/helix.json`).
+If your project builds to a static `dist/` with vite (or any bundler), it qualifies already.
+
+1. **Start with `scaffold_world`** to get the CLI command and recipe for your EXISTING project directory. The CLI does not overwrite by
+   default, so it only adds what you're missing:
+   - `public/helix.json` — the manifest (title/slug/entry/permissions). Start `kind: "character"` even if you
+     keep your own controller; trim what doesn't apply.
+   - `index.html` — if you have one, keep yours and copy over the TWO platform pieces from the scaffolded
+     reference: the `helix:three` import-map markers (only if you adopt the character in stage 2) and the
+     `#loading` overlay + `src/loading.ts` (optional but recommended — count-based progress off
+     `THREE.DefaultLoadingManager`, which your existing loaders already feed).
+2. **`Helix.init()` first.** Add `"@hypersoniclabs/helix-sdk": "{{SDK_DEP_SPEC}}"` to dependencies and call
+   `await Helix.init()` before your game boots. Not embedded → `{ embedded: false }` and your game runs exactly
+   as before (the standalone path must keep working — the golden rule).
+3. **Check the platform rules that bite existing games:**
+   - **HUD placement**: the player shell overlays chrome across the top-center (~top 56px: Exit / Save /
+     helixOS). Move any top-center UI to a corner or the bottom.
+   - **Build shape**: `base: './'` in vite config (relative asset URLs); no server-side anything — the bundle
+     is static.
+   - **NO ROOT-ABSOLUTE URLs into your own bundle.** This is the one that bites ported games hardest: a
+     published world is served from `…/instant-worlds/<id>/<build>/`, so every `'/assets/x.glb'`,
+     `fetch('/data.json')` or `new Audio('/theme.mp3')` your game already has resolves against the SITE
+     root, 404s, and usually throws. Rewrite each one against the document —
+     `new URL('assets/x.glb', document.baseURI).href` — before you publish.
+   - **Big assets**: they bundle as-is at this stage; that's fine. (Character assets in stage 2 stream from
+     the platform CDN instead.)
+4. **Build + publish**: `npm run build` → `validate_world` on `dist/` (fix every problem) →
+   **`helix verify-subpath dist`** (REQUIRED — serves the bundle from a nested path and catches exactly the
+   root-absolute 404s above; local preview serves from the origin root and cannot see them) → `whoami` →
+   `publish_world`. Your game is now a HELIX world.
+
+## Stage 2 — Adopt the character (required for multiplayer presence)
+
+Swap your hand-rolled controller for the platform character: physics-driven chassis, locomotion + animation,
+first/third-person cameras, ability host, and every player's **universal avatar**.
+
+1. Pin it in the manifest: `"systems": { "humanoid-character": "^0.3" }`, then **`install_world_packages`**
+   (resolves the pin into `public/helix_modules/`, rewrites the import map, generates `src/helix.runtime.ts`).
+   Add the vite alias + tsconfig path from the character recipe §3–4.
+2. **Externalize Three, Rapier, and platform systems** (`build.rollupOptions.external: (id) =>
+   id === 'three' || id === '@dimforge/rapier3d-compat' || id.startsWith('@helix/')`, plus the import-map
+   markers): the platform hosts the single shared Three; two copies break `instanceof` and
+   silently corrupt rendering. The character system imports `@dimforge/rapier3d-compat` by bare specifier, and
+   `helix install` maps it to the platform-hosted physics engine instead of baking ~2 MB into your bundle.
+   Your code keeps importing both normally — only the resolution changes. `three` moves to devDependencies
+   and onto the platform's line (`^0.185.1`, what `^0.3` of the system hosts — an older devDep bundles
+   mismatched jsm addons against it); `@dimforge/rapier3d-compat` goes there too (types + `helix dev`), never
+   to dependencies. Compatible
+   `@helix/*` systems update safely on fresh launch; validation and publish refuse a system-bearing build
+   that leaves them bundled.
+3. Replace your controller with the facade in single-player mode — your scene, camera, and loop stay:
+
+   ```ts
+   import { CharacterMultiplayer, RapierBody } from '@helix/humanoid-character';
+   import { SYSTEM_ASSET_BASE, TRANSCODER_PATH } from './helix.runtime';
+
+   const body = await RapierBody.create({ position: SPAWN });
+   // Rebuild your walkable surfaces as static colliders on this body (box/capsule approximations are fine):
+   body.addStaticCuboid({ x: 24, y: 0.5, z: 24 }, { x: 0, y: -0.5, z: 0 });
+
+   const mp = await CharacterMultiplayer.create({
+     helix: Helix, renderer, scene, camera, body,
+     assetBase: SYSTEM_ASSET_BASE, transcoderPath: TRANSCODER_PATH, spawn: SPAWN,
+     join: false, // stage 2: character only — flip to multiplayer in stage 3
+   });
+   // your loop: mp.update(dt) each frame, before your game logic.
+   ```
+
+   Map your old controller's feel onto the character **config** (camera mode/pitch, movement axis, speeds —
+   character recipe §8a; top-down and side-on are config, not code). Your old NON-movement key handling
+   (attack, dash, interact, menus — any raw `addEventListener('keydown', …)`) moves onto the input router:
+   create ONE `InputService`, pass it as `input` to the create call, and re-home each verb with
+   `input.registerAction` / the standard ids (character recipe §8c) — that's what makes them gamepad-ready,
+   rebindable, and menu-context aware. Delete your controller code last, once the feel matches.
+4. Rebuild, `validate_world`, republish. Players now walk your world as their avatar.
+
+## Stage 3 — Go multiplayer
+
+1. Manifest: `helixVersion: "0.3"`, `maxPlayers > 1`, add the `"multiplayer"` permission and
+   `"multiplayer": { "authoritative": true }`.
+2. Delete `join: false` — the facade now joins when embedded, and brings replicas, nameplates, and the
+   reconciler with it. That's presence done.
+3. **The authority audit** — the step that makes or breaks a conversion. Your existing game code is full of
+   self-authority multiplayer must not keep (client-side teleports, local score state, local round resets).
+   Work through the hub's conversion sequence steps 3–7 (`get_started({ kind: "multiplayer" })`): every
+   position write becomes a server `respawn`/`teleport` rule; shared values move into declared `state` read via
+   the typed accessors; **verify with two browser windows**.
+4. Game logic (zones, timers, entities, scores) is declared DATA in the manifest — `read_doc({ name:
+   "multiplayer-logic" })` + the closest template from the hub's index.
+
+## The rules that matter (adoption)
+
+- **Each stage must leave the standalone path working** — `Helix.init()` returning `embedded: false` is your
+  game exactly as it was.
+- **Never two copies of three** after stage 2 — externalize + import map, or rendering corrupts silently.
+  `@dimforge/rapier3d-compat` is external and import-mapped for the same reason: one hosted instance, never bundled.
+- **Your geometry/visuals/loop are never the platform's business.** The platform owns identity (login, avatars),
+  the character system, and the multiplayer room; everything else stays your code.
+- **Publish early** — stage 1 is a real release; feedback on the platform beats a big-bang conversion.