wave3d-agent-sdk 0.2.14 → 0.2.16

package/dist/cli.js

@@ -531,6 +531,7 @@ var PROJECT_ASSET_ACCESSOR_BUCKETS = [
   "materials",
   "textures",
   "animations",
+  "vertexAnimations",
   "poses",
   "audios",
   "instruments",
@@ -545,17 +546,14 @@ var PROJECT_ASSET_ACCESSOR_BUCKETS = [
 ];
 
 // ../../wave-engine/dist/src/core/coreAbstractions/objectModel/waveModelMetadataKeys.js
-var WAVE_MODEL_PART_ID_METADATA_KEY = "waveModelPartId";
-var WAVE_MODEL_PART_NAME_METADATA_KEY = "waveModelPartName";
-var WAVE_MODEL_PART_METADATA_KEY = "waveModelPartMetadata";
 var WAVE_MODEL_RIG_GRAPH_METADATA_KEY = "waveModelRigGraphMetadata";
+var WAVE_MODEL_OBJECT_MODEL_METADATA_KEY = "waveModelObjectModel";
 
 // ../../wave-engine/dist/src/core/coreAbstractions/objectModel/waveModelPartTypes.js
 var WaveModelPartScope;
 (function(WaveModelPartScope2) {
   WaveModelPartScope2["Available"] = "available";
   WaveModelPartScope2["Created"] = "created";
-  WaveModelPartScope2["Promoted"] = "promoted";
   WaveModelPartScope2["All"] = "all";
 })(WaveModelPartScope || (WaveModelPartScope = {}));
 var WaveModelPartLifecycleState;
@@ -41609,7 +41607,7 @@ var DEFAULT_PHYSICS = {
 };
 
 // ../../src/lib/waveStudio/assets/contracts/waveStudioEngineAssetContracts.ts
-var WAVE_STUDIO_ENGINE_ACCESSOR_BUCKET_EXTENSIONS = ["cubeMaps", "poses"];
+var WAVE_STUDIO_ENGINE_ACCESSOR_BUCKET_EXTENSIONS = ["cubeMaps", "poses", "vertexAnimations"];
 function withAccessorBucketExtensions(buckets) {
   const existingBuckets = new Set(buckets);
   return Object.freeze([
@@ -41620,10 +41618,11 @@ function withAccessorBucketExtensions(buckets) {
 var WAVE_STUDIO_ENGINE_ASSET_TYPES = PROJECT_ASSET_TYPES;
 var WAVE_STUDIO_ENGINE_ACCESSOR_BUCKETS = withAccessorBucketExtensions(PROJECT_ASSET_ACCESSOR_BUCKETS);
 var WAVE_STUDIO_MODEL_METADATA_KEYS = Object.freeze({
-  partId: WAVE_MODEL_PART_ID_METADATA_KEY,
-  partName: WAVE_MODEL_PART_NAME_METADATA_KEY,
-  partMetadata: WAVE_MODEL_PART_METADATA_KEY,
-  rigGraph: WAVE_MODEL_RIG_GRAPH_METADATA_KEY
+  objectModel: WAVE_MODEL_OBJECT_MODEL_METADATA_KEY,
+  rigGraph: WAVE_MODEL_RIG_GRAPH_METADATA_KEY,
+  partMetadata: "partMetadata",
+  partId: "partId",
+  partName: "partName"
 });
 
 // ../../src/lib/waveStudio/assets/contracts/waveStudioSerializedDataAssetContracts.ts
@@ -41996,23 +41995,36 @@ var WAVE_STUDIO_PRIMARY_ASSET_BUCKET_SPECS = Object.freeze([
   },
   {
     bucket: "animations",
-    assetTypes: ["animation", "vertexAnimation"],
+    assetTypes: ["animation"],
     label: "Animation",
     pluralLabel: "Animations",
     defaultExtension: ".anim.json",
     baseCategoryAliases: [
       "animations",
       "animation",
-      "fbx_animation",
+      "fbx_animation"
+    ],
+    pathFolderAliases: ["animations"],
+    pathExtensions: ["anim.json", "glb", "gltf", "fbx"],
+    assetManagerAlias: "animationNames",
+    monaco: { interfaceName: "AnimationNames", propertyName: "animationNames" }
+  },
+  {
+    bucket: "vertexAnimations",
+    assetTypes: ["vertexAnimation"],
+    label: "Vertex Animation",
+    pluralLabel: "Vertex Animations",
+    defaultExtension: ".vat.json",
+    baseCategoryAliases: [
       "vertexanimation",
       "vertexanimations",
       "vertex_animation",
       "vat"
     ],
-    pathFolderAliases: ["animations"],
-    pathExtensions: ["anim.json", "vat.json", "glb", "gltf", "fbx"],
-    assetManagerAlias: "animationNames",
-    monaco: { interfaceName: "AnimationNames", propertyName: "animationNames" }
+    pathFolderAliases: ["vertexAnimations", "vertexanimations"],
+    pathExtensions: ["vat.json"],
+    assetManagerAlias: "vertexAnimationNames",
+    monaco: { interfaceName: "VertexAnimationNames", propertyName: "vertexAnimationNames" }
   },
   {
     bucket: "poses",
@@ -42520,8 +42532,8 @@ function normalizeWaveGenieAssetUploadRequest(request) {
 
 // ../../src/lib/waveStudio/aiAssist/bridge/localAgentSdkContract.ts
 var WAVE3D_AGENT_SDK_PACKAGE_NAME = "wave3d-agent-sdk";
-var WAVE3D_AGENT_SDK_REQUIRED_VERSION = "0.2.14";
-var WAVE3D_AGENT_SDK_REQUIRED_BUILD = "agent-sdk-20260625.2";
+var WAVE3D_AGENT_SDK_REQUIRED_VERSION = "0.2.16";
+var WAVE3D_AGENT_SDK_REQUIRED_BUILD = "agent-sdk-20260627.2";
 var WAVE3D_AGENT_SDK_PACKAGE_SPEC = `${WAVE3D_AGENT_SDK_PACKAGE_NAME}@${WAVE3D_AGENT_SDK_REQUIRED_VERSION}`;
 var WAVE3D_AGENT_SDK_START_COMMAND = `npx -y ${WAVE3D_AGENT_SDK_PACKAGE_SPEC} start`;
 var WAVE3D_AGENT_SDK_TOKEN_ENV_VAR = "WAVE3D_MCP_TOKEN";
@@ -43559,7 +43571,7 @@ function buildWaveMcpTaskRouteRecommendedNextToolCall(route) {
     if (route.editIntent === "modifyAssets") {
       return {
         tool: "find_wave_assets_by_category | upload_wave_asset | create_wave_asset_upload | rename_wave_asset | delete_wave_asset",
-        arguments: { category: "<models|textures|materials|audios|hdr|animations|...>" },
+        arguments: { category: "<models|textures|materials|audios|hdr|animations|vertexAnimations|...>" },
         note: "Use category first to reduce search space."
       };
     }
@@ -44249,14 +44261,14 @@ var WAVE_AUTHORING_CORE_INTENT_STAMPS = [
   "State/mode/phase: entity state APIs such as enter/whenIn/onEnter/onExit/toggle/cycle/blockEnterFor before boolean flag machines.",
   "Reaction/observation: when(...).do(...), whenAccelerating()/whenDecelerating(), distance/speed/threshold/rate builders before manual polling or speed-delta state.",
   "Chance/variety: atChanceOf, cycleThrough, and choice APIs before raw Math.random gates.",
-  "Player/controller movement: wave.physics.kinematic-controller-authoring, waveKinematicActor<TState>, and actor-level asHumanoid/asVehicle/asFlight builders before Actor/waveActor, raw input polling, rigid-body forces, or per-tick movement loops.",
+  "Player/controller movement: wave.physics.kinematic-controller-authoring, waveHumanoid for normal humanoid players, waveKinematicActor<TState> for vehicle/flight/generic controllers, and actor-level asHumanoid/asVehicle/asFlight builders before Actor/waveActor, raw input polling, rigid-body forces, or per-tick movement loops.",
   "Repetition/placement: repeat, placeAround, spawnAround, grid/group placement before manual spatial loops.",
   "Terrain/world population: wave.world.world-elements and scene.world/world bootstrap builders for forests, grass, rocks, water, entities, or custom content tied to terrain/streaming world surfaces. Prefer scene.world.scatter(...).renderAs(...).density(...).randomScale(...).apply() or world.scatter(...) before local spawn loops, scene placement, or instancing/batching.",
   "Terrain vs ground: myScene.terrain owns terrain recipe/controller state; myScene.ground is the camera-local live tile entity for visual overlays, callbacks, transform/tooling, and inspection only.",
   "Multiplicity/performance: wave.group.instancing-and-batching for local repeated model-backed objects; classify per-instance needs before choosing real entities, InstanceMeshGroup/waveInstanceGroup/waveInstanceMesh, or waveThinBatch. Count alone never chooses thin batch. Terrain/world/streamed population is a separate world-elements route.",
   'Soft custom geometry: wave.geometry.sdf-surface and assetManager.createSdfSurface("assetName") recipes for buns, cushions, puffy/squishy toys, and organic rounded forms before plain primitives, raw mesh buffers, or vertex editing.',
   "Path-bound surface geometry: wave.geometry.surface-ribbons and wavePathSurface for roads, trails, walkways, bridge decks, waterfalls, and continuous strips before asset-manager factories, scattered planes/cubes, or raw mesh buffers.",
-  "Asset argument vs authoring: typed refs such as models.<asset>, textures.<asset>, materials.<asset>, audios.<asset>, hdr.<asset>, cubeMaps.<asset>, and animations.<asset> for existing assets; waveMaterial for material handles; assetManager only when an exact skill/API requires a low-level generated asset factory."
+  "Asset argument vs authoring: typed refs such as models.<asset>, textures.<asset>, materials.<asset>, audios.<asset>, hdr.<asset>, cubeMaps.<asset>, animations.<asset>, and vertexAnimations.<asset> for existing assets; waveMaterial for material handles; assetManager only when an exact skill/API requires a low-level generated asset factory."
 ];
 var WAVE_AUTHORING_CORE_INTENT_PASS_QUICK_GUIDE = [
   WAVE_AUTHORING_CORE_RULES.coreIntentPass,
@@ -44359,7 +44371,7 @@ function buildWaveMcpAuthoringReminder(kind) {
         ...base,
         nextStep: "Use exact asset refs as method inputs, then return to the authoring strategy.",
         checklist: [
-          "Use returned code refs exactly, such as models.X, textures.X, materials.X, audios.X, or animations.X.",
+          "Use returned code refs exactly, such as models.X, textures.X, materials.X, audios.X, animations.X, or vertexAnimations.X.",
           "For authoring new materials, prefer waveMaterial; quote materials.X only for existing material assets.",
           "If a newly referenced asset changes bootstrap needs, let Studio hot reload escalate internally."
         ],
@@ -44465,7 +44477,7 @@ var WAVE_MCP_AGENT_BRIEF = [
   "VFS modules: scene-root modules and their owned helpers run inside the Studio authoring context, but helpers should stay pure or parameterized. Put live object ownership in scene-root/feature files, not shared helpers.",
   'VFS HTML sketches: for diagram/chart/doc-sketch requests, create or edit an exact `.html` file with Studio VFS tools. Mermaid renders from `<div class="mermaid">flowchart TD ...</div>` when that HTML file is active in the editor/coding pane; HTML sketches must never replace the live engine preview iframe. Do not put Mermaid in markdown fences unless user specifically wants markdown text.',
   'VFS hot reload ownership: Studio hot reload targets the active/open edited file when safe. Editing `/main.ts` reloads the main graph; editing a scene-root module reloads that root; bootstrap/scene registry/assets/network/ambiguous helper surfaces escalate. In multi-file projects, standalone `hot_reload_wave_preview` follows the active Studio editor file, so do not expect it to reload an arbitrary unopened module by path. Put heavy world loading in bootstrap or a coarse world module. Static VFS/package/asset-surface changes can be detected from file/package diffs and Studio may upgrade the tier automatically. Runtime-authored UI state changes cannot be inferred from files; if UI in `main.ts` changes bootstrap/world-provider/runtime-envelope state, store the state and call `waveStudio.reloadPreview({ reason, invalidates: ["world-provider"] })`. Valid invalidations are `bootstrap`, `world-provider`, and `runtime-envelope`. Do not call `myScene.hotReload(...)` from Studio-authored code because it bypasses Studio VFS/package/source-patch orchestration. For intentional cross-module live entities, the owner module calls `waveStudio.exportEntity("Name", entity)` and importer modules call `waveStudio.importEntity<T>("Name")`; Studio restores the exported baseline and replays active importer overlays during source hot reload. Source execution order is dependency-driven: exporter roots run before importer roots; an exporter root runs before `main.ts` when main imports it; importer overlays run after exporter/main baseline. Entity names must be static string literals, unique, and acyclic or run/hot reload stops before execution. Keep shared helpers pure or parameterized.',
-  "Assets: when quoting or passing an existing asset, use typed bare refs in main files: `models.X`, `textures.X`, `materials.X`, `audios.X`, `hdr.X`, `cubeMaps.X`, `animations.X`, etc. Do not paste raw paths or edit Studio-managed generated files just to register assets. If the exact ref is not already visible, call category-first asset discovery (`find_wave_assets_by_category`, alias `list_wave_assets_by_category`, alias `search_wave_assets_by_category`, or tolerant `list_wave_assets`) with required `category` from user intent, semantic `query`, and small `limit` before editing code; category-filtered results can still be capped/truncated, so refine query before concluding absence. Use `list_wave_explorer_assets` only for uploaded library metadata, rename/delete, URL, path, size, or display/ref-name management.",
+  "Assets: when quoting or passing an existing asset, use typed bare refs in main files: `models.X`, `textures.X`, `materials.X`, `audios.X`, `hdr.X`, `cubeMaps.X`, `animations.X`, `vertexAnimations.X`, etc. Do not paste raw paths or edit Studio-managed generated files just to register assets. If the exact ref is not already visible, call category-first asset discovery (`find_wave_assets_by_category`, alias `list_wave_assets_by_category`, alias `search_wave_assets_by_category`, or tolerant `list_wave_assets`) with required `category` from user intent, semantic `query`, and small `limit` before editing code; category-filtered results can still be capped/truncated, so refine query before concluding absence. Use `list_wave_explorer_assets` only for uploaded library metadata, rename/delete, URL, path, size, or display/ref-name management.",
   "Asset authoring facade split: typed refs quote existing assets; `waveMaterial` authors material handles; `assetManager` is only for exact asset-pipeline/generated-asset APIs that a local SDK skill or API lookup names, such as SDF surfaces or surface ribbons. Do not treat `assetManager` as the default creative facade for materials or normal asset arguments.",
   "Material authoring: when creating, configuring, forking, or intentionally editing material handles, route to `wave.material.authoring` and start from `waveMaterial` (`createWater`, `createGrid`, `createSplatMaterial`, `createFromAsset`, `editAsset`). If a material handle later needs runtime sync, `assetManager` may be passed as the sync target; it is still not the authoring root.",
   "Preview: default to hot reload after code changes. On the final edit use `awaitHotReload: true` when you want edit + hot reload + diagnostics in one response; `requestHotReload:true` now also waits for diagnostics by default unless paired with `awaitHotReload:false`. Standalone `run_wave_preview` / `hot_reload_wave_preview` wait by default and return same-call bounded diagnostics in `runtimeVerification`; set `awaitRuntimeResult:false` only for intentional fire-and-poll. Wave Studio may upgrade the hot-reload tier internally for asset/bootstrap/runtime-surface changes, including a full scene rebuild only when required. Caveat: standalone `hot_reload_wave_preview` mirrors the toolbar button and reloads the currently open/active TypeScript file in multi-file projects; it does not take a target path or reload every user-created .ts module. Use `pause_wave_preview` / `resume_wave_preview` for toolbar-equivalent engine pause/resume.",
@@ -44487,8 +44499,8 @@ var WAVE_MCP_AUTHORING_GLOBALS_GUIDE = [
   "- Intent/loop/time values: `Animate`, `Snapshot`, `Repeat`, `ToTrue`, `ToFalse`, `Flips`, `FirstTime`, `EveryTime`, `PerSecond`, `PerTick`, `Ticks`, `Seconds`, `UnitsPerSecond`, `DegreesPerSecond`. For immediate transform/property changes, omit the mode argument; `Apply` is internal transform plumbing, not a public authoring token.",
   "- Direction and input enum-style globals: `Direction.X/Y/Z`, `Direction.Left/Right/Up/Down/Forward/Backward`, `Keyboard`, `MouseButton`, `GamepadButton`, `InputPhase`, `MovementMode`, `RotationMode`.",
   "- Colors/materials/fx helpers: `COLOR`, `PALETTE`, `waveCOLOR`, `waveMaterial`, `shaderUniform`, `waveFx`, `waveFxPresets`, `FxAnchor`, `FxCondition`.",
-  "- Controller movement helpers: `waveKinematicActor`, `netKinematicActor`, `KinematicHumanoidMovementState`, `KinematicVehicleMovementState`, and `KinematicFlightMovementState`. Use actor-level `.asHumanoid(...)`, `.asVehicle(...)`, or `.asFlight(...)` for player/controller movement.",
-  "- Asset maps: use category-first refs returned by `find_wave_assets_by_category`, commonly `models`, `gaussianSplats`, `animations`, `materials`, `guis`, `textures`, `audios`, `instruments`, `videos`, `hdr`, `fonts`, `serializedData`, `terrains`, `fx`, and `particles`.",
+  "- Controller movement helpers: `waveHumanoid`, `netHumanoid`, `waveKinematicActor`, `netKinematicActor`, `KinematicHumanoidMovementState`, `KinematicVehicleMovementState`, and `KinematicFlightMovementState`. Use `waveHumanoid` plus `.useDefaultLocomotionAnimations()` for normal humanoid players; use `.asVehicle(...)` or `.asFlight(...)` on `waveKinematicActor<TState>` for vehicle/flight controllers.",
+  "- Asset maps: use category-first refs returned by `find_wave_assets_by_category`, commonly `models`, `gaussianSplats`, `animations`, `vertexAnimations`, `materials`, `guis`, `textures`, `audios`, `instruments`, `videos`, `hdr`, `fonts`, `serializedData`, `terrains`, `fx`, and `particles`.",
   '- Scene/runtime handles: prefer `myScene` for scene composition and `waveStudio` for Studio operations. If authored UI changes bootstrap/world-provider/runtime-envelope state and needs the Studio preview package to rebuild, call `waveStudio.reloadPreview({ reason, invalidates: ["world-provider"] })`, not `myScene.hotReload(...)`. Valid invalidations are `bootstrap`, `world-provider`, and `runtime-envelope`; use the narrowest true reason. `assetManager` is available, but use it only when an exact skill/API names an asset-pipeline or generated-asset factory; do not use it as the default facade for existing asset refs or material authoring. Use lower-level `ctx`, `engine`, or `scene` only when existing code or an exact API requires them.',
   "- Authoring systems/presets: `waveEventBus`, `waveRig`, `waveValueCurve`, `waveValueCurvePresets`, `waveMotionSignal`, `waveParam`, `WaveParam`, `WaveChoice`, `prefabModels`, `effectPrefabs`, and prefab helpers such as `rocketPrefab`.",
   "- Lowercase constructors: `prop`, `marker`, `sphere`, `point`, `cube`, `box`, `cylinder`, `capsule`, `cone`, `torus`, `plane`, `ground`, `line`, `arc`, `path`, and related shape helpers.",
@@ -44514,14 +44526,14 @@ var WAVE_MCP_CODING_GUARDRAIL = [
   "4d. For terrain/world population such as forests, grass, rocks, water, streamed entities, or environmental scatter tied to terrain/streaming surfaces, route to `wave.world.world-elements`: use `scene.world.scatter(...)`/`myScene.world.scatter(...)` for live scene code or `world.scatter(...)` inside `scene.withWorldStreaming(...)` for bootstrap streaming declarations. Prefer fluent verbs like `.renderAs(...)`, `.density(...)`, `.randomScale(...)`, `.colors(...)`, `.linkedTo(...)`, `.usePartitionedLOD(...)`, `.distanceBands(...)`, `.lodModels(...)`, then `.apply()`. Do not hand-roll spawn loops or use local instancing/batching when declarative world scatter fits.",
   '4e. For many local repeated model-backed objects such as a fleet, crowd, stars, decorations, or "1000 spaceships", route to `wave.group.instancing-and-batching` and classify per-instance needs before constructors. Use `waveThinBatch` only for visual-only mass sharing one mesh with per-instance transform/color/GPU animation. Use `waveInstanceMesh`, `InstanceMeshGroup`, or scene `waveInstanceGroup` when each copy needs picking, click/hover interaction, labels/tool overlays, visibility toggles, selection, or individual identity. Use real `Prop`/`Actor` entities when each copy needs rigid bodies, gravity, audio, AI, weapons, damage state, independent lifecycle, or rich behavior. Count alone never chooses thin batch; mixed hero/background intent should use a hybrid.',
   '4e1. For visual-model voxelization, route to `wave.model.voxelization`. Prefer `source.model.voxelizing().relativeSize(0.05).surfaceOnly().onWorkerThread().usingCubes().asThinBatch().applyAsync()` only when async/worker authored code is explicitly acceptable; otherwise use synchronous `onMainThread().apply()` only for tiny local voxel work where blocking is acceptable. Never use Promise chains such as `.apply().then(...)` in authored Studio code because hot-reload safety rejects `.then/.catch/.finally`. Use `relativeSize(ratio)` for model-scale-independent voxel size, `size(value)` only for absolute world units, `usingCubes()`/`usingSpheres()`/`usingCylinders()`/`usingCapsules()` for shape, and the one-shot `voxelize({ size: { mode: "relative", ratio: 0.05, basis: "longestAabbEdge" }, execution: "workerThread", shape: "cube", surfaceOnly: true })` only for serializable recipe code. For thin-batch voxel interactions, use `detectNear(target).within(radius)`, `batchTransform.getColorAt(index)` before color restore, `whenIndexClicked(index => voxelBatch.at(index).enlargeBy(1.2).done().commitBuffers())`, and `castToProp(index); prop.enablePhysics()` only when a full prop is needed. Do not use removed `voxelizeHeavy`, `voxelize({ voxelSize })`, `withVoxelSize`, `sharedBox`, `atIndex`, or low-level worker/adapter internals in authored scene code.',
-  "4f. For player/controller movement, route to `wave.physics.kinematic-controller-authoring`: use `waveKinematicActor<TState>` or `netKinematicActor` and actor-level `.asHumanoid(...)`, `.asVehicle(...)`, or `.asFlight(...)` builders. Do not start from `Actor`/`waveActor`, raw input polling, rigid-body forces, per-tick movement loops, or direct `movementController.useFlightScheme(...)` unless the user explicitly asks for low-level component tuning or nearby working code already uses that component-level pattern.",
-  "4f1. For basic public humanoid locomotion animation, follow the kinematic-obby pattern: `new waveKinematicActor<KinematicHumanoidMovementState>().useModel(models.wave3dFemale)`, then `.asHumanoid({ baseSpeed, jumpForce }).useIdleAnimation(animations.Idle).useWalkingAnimation(animations.Walking).useJumpAnimation(animations.Jump).apply()`. Do not use `animator.addLocalAnimations()`, `getClipNames()`, or `resolveClipName(...)` as the first-choice setup when public `animations.*` refs fit.",
+  "4f. For player/controller movement, route to `wave.physics.kinematic-controller-authoring`: use `waveHumanoid`/`netHumanoid` for humanoid player characters, and use `waveKinematicActor<TState>`/`netKinematicActor` with `.asVehicle(...)` or `.asFlight(...)` for vehicle/flight/generic controller movement. Do not start from `Actor`/`waveActor`, raw input polling, rigid-body forces, per-tick movement loops, or direct `movementController.useFlightScheme(...)` unless the user explicitly asks for low-level component tuning or nearby working code already uses that component-level pattern.",
+  "4f1. For basic public humanoid locomotion animation, follow the kinematic-obby pattern: `new waveHumanoid().useModel(models.wave3dFemale).useDefaultLocomotionAnimations()`. For custom locomotion tuning or clip options, use `.asHumanoid({ baseSpeed, jumpForce }).useIdleAnimation(animations.Idle).useWalkingAnimation(animations.Walking).useJumpAnimation(animations.Jump).apply()`. Do not use `animator.addLocalAnimations()`, `getClipNames()`, or `resolveClipName(...)` as the first-choice setup when public `animations.*` refs fit.",
   "4g. For obbies/course obstacles, split the intent: the controlled player uses `wave.physics.kinematic-controller-authoring`; static platforms, moving platforms, sliding gates, sweepers, ferries, and hazards use `wave.physics.rigid-body-authoring` on geometry/props with static or kinematic rigid bodies, then transform/animate/current-code motion. Do not use `waveKinematicActor` for a platform unless it is itself player/controller-driven.",
   '4h. For semantic touch lifecycle such as "when contact starts/stops", "exactly once when touching begins/ends", "on hit", or projectile/target impact reactions, use `onContactBegin(...)`, `onContactContinue(...)`, `onContactEnd(...)`, or tag/target variants. Do not use removed `onCollision*` callback aliases; collision-named surfaces are for filtering, masks, groups, and actuation internals.',
   `4i. ${WAVE_AUTHORING_CORE_RULES.syncUserCode}`,
   `4j. ${WAVE_AUTHORING_CORE_RULES.terrainGroundRouting}`,
   "5. Use `get_wave_session` and `list_wave_files` to know active file context. `/main.ts` and scene `*/main.ts` get convenience globals: write against `myScene`, not a hand-created scene.",
-  `6. ${WAVE_AUTHORING_CORE_RULES.assetResolution} In main files, use bare asset maps like \`models.Foo\`, \`gaussianSplats.Room\`, \`textures.Grass\`, \`materials.Wood\`, \`animations.Idle\`, \`audios.Click\`, \`hdr.daylight\`, \`cubeMaps.studio\`, \`fonts.Poppins_Regular\`, \`serializedData.SomeJson\`. Do not add \`ASSET_WAREHOUSE.\` unless raw warehouse access is explicitly needed.`,
+  `6. ${WAVE_AUTHORING_CORE_RULES.assetResolution} In main files, use bare asset maps like \`models.Foo\`, \`gaussianSplats.Room\`, \`textures.Grass\`, \`materials.Wood\`, \`animations.Idle\`, \`vertexAnimations.HorseGallopVat\`, \`audios.Click\`, \`hdr.daylight\`, \`cubeMaps.studio\`, \`fonts.Poppins_Regular\`, \`serializedData.SomeJson\`. Do not add \`ASSET_WAREHOUSE.\` unless raw warehouse access is explicitly needed.`,
   `6a. For authoring constants, prefer bare runtime globals declared by the Studio authoring environment. Common examples: ${WAVE_AUTHORING_COMMON_GLOBAL_EXAMPLES_TEXT}. The generated globals surface has many more values; use local-SDK \`query_wave_api\` before inventing namespace-qualified paths such as \`TransformVerbMode.Animate\` in authored code. HTTP Gateway hides/retires skill/API lookup.`,
   "6b. Asset facade split: passing an existing asset uses typed refs such as `models.X`, `textures.X`, `materials.X`, or `audios.X`; material authoring starts from `waveMaterial`; `assetManager` is reserved for exact low-level generated-asset/asset-pipeline APIs named by a local SDK skill or API lookup. Do not use `assetManager` as the default material, asset-ref, or path-surface authoring root.",
   '7. Use category-first asset discovery before referencing uploaded user assets, project aliases, or ambiguous built-in assets. Preferred tool: `find_wave_assets_by_category`; aliases: `list_wave_assets_by_category`, `search_wave_assets_by_category`, tolerant `list_wave_assets`. Choose category from user intent first, then query: `list_wave_assets_by_category({ category:"materials", query:"grass", limit:50 })`. For sound use `audios`, for 3D objects use `models`, for sky/HDR use `hdr`, for cube-map sky/environment use `cubeMaps`, for images use `textures`. Category-filtered responses can still be capped/truncated; absence there is not absence in the library. Only use asset refs returned by this tool. If the current code already contains the exact ref and the user asks for a small pattern-preserving edit, you may reuse that visible ref.',
@@ -44533,7 +44545,7 @@ var WAVE_MCP_CODING_GUARDRAIL = [
   '11. After the final code edit, default to hot reload. Prefer `awaitHotReload: true` on the edit tool when you want one MCP response with edit result + hot reload + bounded diagnostics. `requestHotReload:true` also waits for diagnostics by default unless paired with `awaitHotReload:false`. Standalone `run_wave_preview` / `hot_reload_wave_preview` also wait by default and return `runtimeVerification`; set `awaitRuntimeResult:false` only for intentional fire-and-poll. Caveat: standalone `hot_reload_wave_preview` mirrors the toolbar button and reloads the currently open/active TypeScript file in multi-file projects; it does not take a target path or reload every user-created .ts module. That hot-reload request may internally upgrade from `patchMain` to `preserveScene` or hard `rebuildScene` when assets/bootstrap/scene surface changed; do not manually force bootstrap sync. Runtime-authored UI that changes bootstrap/world-provider/runtime-envelope state must call `waveStudio.reloadPreview({ reason, invalidates: ["world-provider"] })` because Studio cannot infer that from static file diffs. Use `run_wave_preview` only when diagnostics show no successful preview yet (`hasRunSucceeded: false`), the user explicitly asks for a full run/restart, or hot reload/polling fails and a full restart is the last resort. `pause_wave_preview` and `resume_wave_preview` are direct preview controls mirroring the toolbar pause/resume buttons.',
   '12. After run/hot reload, use returned `runtimeVerification` when present; otherwise call `get_wave_runtime_diagnostics` repeatedly until `runtimeBusy` is false and `lastRuntimeOutcome` is `success` or `error`. Use `previewExecutionPhase` to distinguish Studio preparing work from the preview iframe executing it. `isRunning` is only the Studio scheduling flag, not the final runtime completion gate. If the edit/runtime tool returned `requestedAt` or `runtimeActionRequestedAt`, ignore diagnostics whose `lastRuntimeOutcomeAt` is older than that timestamp. Treat `latestError` as current only when `lastRuntimeOutcome` is `error`; older error lines can remain in returned logs as history. Treat `editorErrorCount > 0` as blocking Monaco/linter/compile failure and read `editorDiagnostics` before claiming success, even when `lastRuntimeOutcome` is `success`. If `lastRuntimeOutcome` is `success` and `editorErrorCount` is 0, verify visually with `capture_wave_screenshot({ resolution: "L" })` or structurally with `get_wave_runtime_entity_snapshot({ variableName, filePath? })` instead of declaring failure from old log text. Same-machine screenshots usually return `localPath`; hosted screenshots return exact field `dataBase64`, not `imageBase64`.',
   "12a. Marker waypoint workflow: when the human asks to use preview marking tools such as `clickToMark()`, route with `marker.use` plus the code/project intent, then call `list_wave_runtime_markers`. Treat marker records as runtime observation data, write marker `worldPosition`/`worldRotation` into the appropriate path/waypoint/placement code, hot reload, and verify with screenshot or marker re-read. One marker read may happen before routing only when needed to decide the code intent. Use path/placement skills only when current code does not reveal the marker-to-code pattern.",
-  `13. To use locally generated assets in code, prefer \`create_wave_asset_upload\` for local files when available: pass assetKind from the Wave Studio upload policy SSOT (${getWaveStudioBridgeAssetUploadKindHelpText()}), stat the file first, pass exact byte size, get \`uploadUrl\` + \`uploadHeaders\`, upload raw bytes with plain HTTP PUT using every returned header exactly, keep \`clientToken\`/\`uploadHeaders.Authorization\` out of logs, call \`get_wave_asset_upload_status\` until \`receivedBytes === sizeBytes\`, then call \`commit_wave_asset_upload\` with the same uploadId, assetKind, filename, contentType, and sizeBytes from the create response. No local Python, Vercel package, or Blob SDK is required. On hosted MCP this uses hosted temporary object storage; on same-machine local MCP it uses the local SDK as temporary staging. If direct upload is unavailable, use \`stage_wave_asset_upload_chunk\` plus \`commit_wave_asset_chunk_upload\`: omit uploadId only for chunkIndex 0, then reuse the returned uploadId for every later chunk and for commit. Use \`upload_wave_asset\` with exactly one of \`dataBase64\` or \`dataUrl\` only for small inline assets. If staging is abandoned before commit, call \`abort_wave_asset_upload\` with the uploadId. Do not abort after commit returns pending or completed; the Studio browser cleans committed staging after execution. Hosted MCP cannot read local filesystem paths through inline upload. All flows stage bytes outside the command queue, cap staged bytes at 300 MB, and return \`asset.bareRef\`, for example \`textures.Albedo\`, \`cubeMaps.Studio\`, \`materials.Wood\`, \`audios.Click\`, \`models.Robot\`, \`animations.Run\`, \`fonts.Title\`, or \`serializedData.Config\`. If the name already exists, the upload result returns \`skipped: true\` and the existing asset. Staged chunks/blobs are also swept lazily after about 24 hours. Model-family uploads enable meshoptimizer by default unless \`useMeshoptimizer\` is false.`,
+  `13. To use locally generated assets in code, prefer \`create_wave_asset_upload\` for local files when available: pass assetKind from the Wave Studio upload policy SSOT (${getWaveStudioBridgeAssetUploadKindHelpText()}), stat the file first, pass exact byte size, get \`uploadUrl\` + \`uploadHeaders\`, upload raw bytes with plain HTTP PUT using every returned header exactly, keep \`clientToken\`/\`uploadHeaders.Authorization\` out of logs, call \`get_wave_asset_upload_status\` until \`receivedBytes === sizeBytes\`, then call \`commit_wave_asset_upload\` with the same uploadId, assetKind, filename, contentType, and sizeBytes from the create response. No local Python, Vercel package, or Blob SDK is required. On hosted MCP this uses hosted temporary object storage; on same-machine local MCP it uses the local SDK as temporary staging. If direct upload is unavailable, use \`stage_wave_asset_upload_chunk\` plus \`commit_wave_asset_chunk_upload\`: omit uploadId only for chunkIndex 0, then reuse the returned uploadId for every later chunk and for commit. Use \`upload_wave_asset\` with exactly one of \`dataBase64\` or \`dataUrl\` only for small inline assets. If staging is abandoned before commit, call \`abort_wave_asset_upload\` with the uploadId. Do not abort after commit returns pending or completed; the Studio browser cleans committed staging after execution. Hosted MCP cannot read local filesystem paths through inline upload. All flows stage bytes outside the command queue, cap staged bytes at 300 MB, and return \`asset.bareRef\`, for example \`textures.Albedo\`, \`cubeMaps.Studio\`, \`materials.Wood\`, \`audios.Click\`, \`models.Robot\`, \`animations.Run\`, \`vertexAnimations.HorseGallopVat\`, \`fonts.Title\`, or \`serializedData.Config\`. If the name already exists, the upload result returns \`skipped: true\` and the existing asset. Staged chunks/blobs are also swept lazily after about 24 hours. Model-family uploads enable meshoptimizer by default unless \`useMeshoptimizer\` is false.`,
   "14. Project tools: use `list_wave_project_templates` before `new_wave_project({ templateId? })`; use `list_wave_projects` before `rename_wave_project({ projectId, name })` or `open_wave_project({ projectId })`. Use `read_wave_project` to learn from example packs without replacing the current editor workspace: pass exact `projectId` from `list_wave_projects` for listed/saved projects, or pass a shared/published project `url` directly for silent URL reads. Shared URL reads support old `/waveStudio?share=<uuid>` links and new shared alias links; published URL reads support old/new `/p/<user>/<id>` links. Rename updates saved project display metadata only. New/open replace the live workspace. If there are unsaved changes they return `unsaved_changes` unless you save first or explicitly pass `discardUnsavedChanges: true`; only use exact ids returned by list tools for open/rename.",
   "15. `save_wave_project` quick-saves an existing saved project and ignores name/description. For a new unsaved project, pass name/description when available; otherwise Studio generates defaults and returns whether each field was defaulted.",
   "16. `share_wave_project` runs the same Share Project menu pipeline, returns a 30-day share `url`, and requires write pairing plus the signed-in share policy. Always send the returned `url` back to the user.",
@@ -44552,7 +44564,7 @@ var WAVE_MCP_CODING_GUARDRAIL_SUMMARY = [
   "4. Prefer natural, intent-preserving public APIs and aliases such as Actor, Prop, Cube, Sphere, waveMaterial, semantic directions, Animate/Seconds/DegreesPerSecond, and fluent WaveEngine DSLs.",
   `4a. ${WAVE_AUTHORING_CORE_RULES.hotReloadCallbackSafety} edit_wave_file/apply_wave_patch/create_wave_file preflight this rule and runtime bundling blocks violations before authored code runs.`,
   "4b. For model voxelization, route to `wave.model.voxelization`; use `model.voxelizing().relativeSize(0.05).surfaceOnly().onWorkerThread().usingCubes().asThinBatch().applyAsync()` only when async/worker authored code is explicitly acceptable, or `onMainThread().apply()` only for tiny local synchronous voxel work. Never use `.apply().then(...)` or Promise callback chains. Use `detectNear`, `getColorAt`, and `whenIndexClicked(index => voxelBatch.at(index).enlargeBy(1.2).done().commitBuffers())` for thin-batch voxel interaction. Do not use `voxelizeHeavy`, `voxelize({ voxelSize })`, `withVoxelSize`, `sharedBox`, or stale `atIndex`.",
-  "5. Resolve assets explicitly. Use category-first bare refs returned by `find_wave_assets_by_category` or alias `list_wave_assets_by_category`: models.X, textures.X, materials.X, audios.X, hdr.X, animations.X. Do not guess refs, raw paths, or infer absence from a capped list.",
+  "5. Resolve assets explicitly. Use category-first bare refs returned by `find_wave_assets_by_category` or alias `list_wave_assets_by_category`: models.X, textures.X, materials.X, audios.X, hdr.X, animations.X, vertexAnimations.X. Do not guess refs, raw paths, or infer absence from a capped list.",
   "6. `project.assetrefs.ts`, `project.scene.ts`, `project.scenes.ts`, and `project.execution.ts` are Studio-managed read-only. `bootstrap.ts` is normally managed too; edit it only with a confident `managedFileEditReason` for world streaming/terrain provider, render/runtime backend, media consent/capture, external AI/TTS backend, scene/template baseline, pre-main baseline setup, or stale bootstrap API update to latest. Never edit bootstrap for asset loaders/manifests, instruments, scene registry, or execution manifest.",
   "7. Use safest VFS tool: read first, default to edit_wave_file for small one-file edits, let it auto-resolve baseHash, use apply_wave_patch({ operations }) with explicit baseHash for grouped/advanced work, and inspect skips/partials.",
   "8. For obby/platform tasks, controlled players use kinematic-controller authoring; moving platforms and hazards use rigid-body kinematic geometry/props plus transform/animate/current-code motion.",
@@ -44623,12 +44635,12 @@ var WAVE_MCP_FILE_CONTEXT_GUIDE = [
   "Wave Studio file-context rules:",
   "- Normal scene edit path: use the active `*/main.ts`, write against `myScene`, use bare asset refs, and do not edit Studio-managed generated files.",
   "- Studio-managed generated files are MCP read-only for agents: `project.assetrefs.ts`, `project.scene.ts`, `project.scenes.ts`, and `project.execution.ts`. `bootstrap.ts` / scene `*/bootstrap.ts` is normally Studio-managed too; edit it only when you can confidently pass `managedFileEditReason` as one of: `world_streaming_or_terrain_provider`, `render_profile_or_runtime_backend`, `media_consent_or_capture_plan`, `external_ai_or_tts_backend`, `scene_envelope_or_template_baseline`, `baseline_setup_before_user_main`, `stale_api_update_to_latest`. Never edit bootstrap for assets/loaders, instruments, scene registry, or execution manifest; Studio owns those.",
-  "- `main.ts` / scene `*/main.ts`: user scene authoring code. Prefer `myScene` for the active scene. Also available: `assetManager`, `waveEngine`, `waveStudio`, `models`, `gaussianSplats`, `fbxModels`, `animations`, `materials`, `guis`, `textures`, `audios`, `instruments`, `videos`, `hdr`, `cubeMaps`, `generatedModels`, `fonts`, `serializedData`, `terrains`, `fx`, `particles`.",
+  "- `main.ts` / scene `*/main.ts`: user scene authoring code. Prefer `myScene` for the active scene. Also available: `assetManager`, `waveEngine`, `waveStudio`, `models`, `gaussianSplats`, `fbxModels`, `animations`, `vertexAnimations`, `materials`, `guis`, `textures`, `audios`, `instruments`, `videos`, `hdr`, `cubeMaps`, `generatedModels`, `fonts`, `serializedData`, `terrains`, `fx`, `particles`.",
   `- Studio also injects many authoring constants/functions as bare globals. ${WAVE_AUTHORING_BARE_GLOBALS_RULE} Do not add imports or guessed namespaces. Treat listed globals as examples and use local-SDK \`query_wave_api\` for the complete generated authoring surface. HTTP Gateway hides/retires skill/API lookup.`,
   "- Project code does not need to live in one monolith. Use `create_wave_file`, `rename_wave_file`, and `delete_wave_file` for VFS `.ts` modules and folders, for example `/actors/player.ts` or `/systems/movingPlatforms.ts`. New `.ts/.tsx` files are runnable source roots by default, so top-level scene code in them runs on Run/hot reload; pass `runnable:false` only for pure helper modules that should not execute on their own.",
   '- Studio VFS also supports non-code `.html` sketch files. Use `create_wave_file({ path: "/docs/diagram.html", content })` for Mermaid diagrams, charts, and lightweight docs; put Mermaid source inside `<div class="mermaid">...</div>`, not markdown fences. When that `.html` file is active, the editor/coding pane renders it as an HTML sketch and auto-loads Mermaid if `class="mermaid"` is present. HTML sketches must never replace the live engine preview iframe.',
   "- `list_wave_files` and `read_wave_file` return a full-file `contentHash`. Primary simple edit tool `edit_wave_file` can omit `baseHash`; Studio resolves the latest mirror hash and still performs browser-side stale-write checks. It accepts `edits:[{startLine,endLine,text}]` or `edits:[{rangeOffset,rangeLength,text}]` for one-file multi-edits. Use explicit `baseHash` for advanced `apply_wave_patch({ operations: [...] })` compact operations (`lineEdits`, `textEdits`, strict `searchReplace`, or `unifiedDiff`) and existing-file `writeFile` unless `forceOverwrite: true`. This hash is a cooperative stale-write check, not a security boundary. Prefer forgiving `edit_wave_file` over full-file `writeFile` when only a small span changes. Stale hashes and ambiguous replacements are skipped instead of guessed. `textEdits` offsets are zero-based UTF-16 offsets in the full file, even if you used a scoped line read; line edits use 1-based full-file line numbers. Scoped reads and line edits clamp oversized endLine to lineCount but still reject startLine beyond the file. If you need multiple compact changes in one file, use `edit_wave_file({ path, edits:[...] })` or combine them into one advanced patch operation; re-read between separate operations.",
-  "- Main-file asset refs should be bare: `models.Car`, `gaussianSplats.Room`, `textures.Grass`, `materials.Metal`, `animations.Idle`. Omit `ASSET_WAREHOUSE.` for authored code.",
+  "- Main-file asset refs should be bare: `models.Car`, `gaussianSplats.Room`, `textures.Grass`, `materials.Metal`, `animations.Idle`, `vertexAnimations.HorseGallopVat`. Omit `ASSET_WAREHOUSE.` for authored code.",
   "- Asset facade split: existing asset inputs use typed refs; material authoring starts from `waveMaterial`; `assetManager` is for explicit generated-asset/asset-pipeline APIs named by a local SDK skill or API lookup, not the default place to invent new material or asset code.",
   "- Use `find_wave_assets_by_category({ category, query?, limit? })` to inspect the current live asset surface. Fill category from user intent first. It includes public assets, uploaded user assets, and project aliases, with `source` telling where each ref came from.",
   "- Wave Studio auto-maintains bootstrap/project asset/scene wiring for normal `main.ts` edits. Do not write or modify bootstrap or generated project registry files just to make an asset ref or scene entry available; use the returned bare refs in main code and let Studio sync boot/assets/scenes. Hot reload is the default preview path after code edits and can automatically upgrade its internal tier when new assets or bootstrap-surface changes require it.",
@@ -44683,13 +44695,13 @@ var WAVE_MCP_STUDIO_TOOL_GUIDE = [
   '- Local parity rule: WaveEngine Agent SDK `tools/list` mirrors the HTTP Gateway Studio-operation catalog, then adds local SDK lookup/session-discovery extras. Direct local live-session tools include VFS edits, assets/uploads, project save/open/new/read/share, preview run/hot reload/pause/resume, diagnostics, performance, screenshots, entity snapshots, and runtime markers. Local browser-backed calls wait directly for browser results. Only call `get_wave_command_result` if a tool returns `status:"pending"` plus `requestId`; on local it normally exists only for catalog parity and reports no local pending-command queue.',
   `- MCP topology: same-machine agents should run \`${WAVE3D_AGENT_SDK_START_COMMAND}\`, check /health, and update/restart SDK if version is stale, tools are missing, or SDK prints secrets; after restart recheck /health and tools/list. If restart happens after Copy-to-Agent, preserve MCP_TOKEN with \`${WAVE3D_AGENT_SDK_TOKEN_PRESERVING_START_COMMAND}\` using the current MCP_TOKEN value without printing it, otherwise the SDK may be healthy but unable to authorize the copied local pairing secret. Current SDK start reuses a current same-token peer, replaces verified stale/different-token SDK peers on localhost, and refuses to kill non-SDK port owners. Same-machine stale/missing tools/401-with-Gateway-success means repair local SDK first, not HTTP Gateway first. Same-machine HTTP Gateway is degraded fallback only after SDK cannot run, update, or adopt. Different-machine/cloud/sandbox agents should use \`MCP_HTTP_GATEWAY_FALLBACK_URL\` directly; starting WaveEngine Agent SDK there binds localhost beside the agent, not beside the user browser. Stale SDK/cache are not reasons to use HTTP Gateway fallback; wrong-machine localhost is a topology mismatch.`,
   `- MCP cache priorities: Priority 1 is active role/context cache: keep role, guardrails, authoring workflow, asset/VFS/hot-reload rules, prompt version, and prompt hash in active LLM context. Priority 2 is WaveEngine SDK Cache: production HTTP Gateway/local-SDK onboarding must not claim normal cached success until SDK cache is prepared or accept proof passes. If accept returns \`wave_engine_sdk_cache_not_ready\`, update/restart \`wave3d-agent-sdk\` or run \`${WAVE_MCP_CORPUS_CACHE_COMMAND_TEMPLATE}\`, then retry accept. If local cache cannot work because sandbox/no filesystem/no Node/npm/user refusal/refresh failure, explicitly accept degraded fallback with \`waveEngineSdkFallbackMode:"studio_ops_only"\`, a valid \`waveEngineSdkUnavailableReason\`, and \`studioOpsOnlyFallbackAccepted:true\`; warn user HTTP Gateway is Studio-ops-only and skill/API lookup requires local SDK/cache repair. This cache command reinstalls the package-bundled SDK locally; it is not WaveEngine Agent SDK transport. Never run it to switch MCP transport; never treat cache failure as local transport failure.`,
-  "- Main-file globals include `myScene`, `assetManager`, `waveEngine`, `waveStudio`, and direct asset maps such as `models`, `gaussianSplats`, `textures`, `materials`, `animations`, `audios`, `hdr`, `cubeMaps`, `fonts`, `serializedData`, `terrains`, `fx`, `particles`. Availability is not endorsement: choose the intent-owned facade/skill before using a global.",
+  "- Main-file globals include `myScene`, `assetManager`, `waveEngine`, `waveStudio`, and direct asset maps such as `models`, `gaussianSplats`, `textures`, `materials`, `animations`, `vertexAnimations`, `audios`, `hdr`, `cubeMaps`, `fonts`, `serializedData`, `terrains`, `fx`, `particles`. Availability is not endorsement: choose the intent-owned facade/skill before using a global.",
   `- Bare authoring globals: common examples include ${WAVE_AUTHORING_COMMON_GLOBAL_EXAMPLES_TEXT}, \`waveMaterial\`, \`waveFx\`, \`waveValueCurve\`, and \`waveParam\`. Use them directly in \`main.ts\`; do not import or namespace-qualify them. If the task is unfamiliar, retrieve the relevant local-SDK \`wave.*\` skill first; for the full generated exact-global surface, call local-SDK \`query_wave_api\`.`,
   "- MCP VFS edit tools: primary tool is forgiving `edit_wave_file({ path, ... })`; it infers replaceLines from startLine/endLine, multi-edit from edits:[...], replaceText from oldText, and whole-file replace from text/content. It handles line-based edits, exact string changes, one-file edit arrays, whole-file replacement, omitted baseHash, common aliases, and oversized endLine clamping. Use `apply_wave_patch({ operations: [...] })` only for grouped/multi-file edits and advanced operations; a single operation is tolerated but operations:[...] is preferred. Simple edit tools can omit baseHash; advanced patch operations should pass it.",
   `- MCP hot-reload safety rule: ${WAVE_AUTHORING_CORE_RULES.hotReloadCallbackSafety} edit_wave_file, create_wave_file, and apply_wave_patch preflight this rule before writing.`,
   "- MCP generated-file rule: `project.assetrefs.ts`, `project.scene.ts`, `project.scenes.ts`, and `project.execution.ts` are Studio-managed read-only. `bootstrap.ts` / scene `*/bootstrap.ts` is normally managed too; edit it only when you can confidently pass `managedFileEditReason` as `world_streaming_or_terrain_provider` (Google Maps 3D tiles included), `render_profile_or_runtime_backend`, `media_consent_or_capture_plan`, `external_ai_or_tts_backend`, `scene_envelope_or_template_baseline`, `baseline_setup_before_user_main`, or `stale_api_update_to_latest`. Never edit bootstrap for asset manifests/loaders, instruments, scene registry, or execution manifest; Studio owns those.",
   '- MCP VFS file tools: `create_wave_file({ path, content, requestHotReload? })`, `rename_wave_file({ fromPath, toPath, requestHotReload? })`, and `delete_wave_file({ path, requestHotReload? })` are direct Operate tools for exact live VFS paths, including project `.ts` modules and `.html` sketch files. New `.ts/.tsx` files are standalone runnable source roots by default, so top-level scene code runs on Run/hot reload; pass `runnable:false` only for pure helper modules that should not execute on their own. For Mermaid/diagram/chart requests, create a `.html` file containing a block like `<div class="mermaid">flowchart TD\\n  A --> B</div>`; active `.html` files render in the editor/coding pane as HTML sketches and auto-load Mermaid when `class="mermaid"` is present. HTML sketches must never replace the live engine preview iframe. On the final code edit, `awaitHotReload:true` implies hot reload and returns bounded runtime diagnostics in the same response. These tools manage VFS files, not uploaded asset-library blobs. If the user gives a vague target, call `list_wave_files`/`read_wave_file` or ask before mutating. Scene-root modules and owned helpers run in the Studio authoring context; keep shared helpers pure or parameterized, and keep live object ownership in feature files. Rename/move rewrites relative imports; delete is permanent unless you rewrite the file and refuses files still imported by other VFS code.',
-  "- MCP asset resolution rule: if code needs an existing asset argument, reuse an exact visible typed ref or call category-first asset discovery before editing: `find_wave_assets_by_category({ category, query?, sources?, limit? })`, alias `list_wave_assets_by_category`, alias `search_wave_assets_by_category`, or tolerant `list_wave_assets`. Fill `category` from user intent first: sound/audio -> `audios`, 3D object/character/prop -> `models`, material -> `materials`, image/texture -> `textures`, sky/HDR -> `hdr`, cube-map sky/environment -> `cubeMaps`, animation -> `animations`, JSON/CSV/YAML/XML/ROS data -> `serializedData`. It returns refs safe to use in authored code, ordered projectAlias -> user -> public. In `main.ts`, pass typed bare refs such as `models.X`, `textures.X`, `materials.X`, `audios.X`, `hdr.X`, `cubeMaps.X`, `animations.X`, `videos.X`, `fonts.X`, `serializedData.X`, or `terrains.X`; do not paste raw paths.",
+  "- MCP asset resolution rule: if code needs an existing asset argument, reuse an exact visible typed ref or call category-first asset discovery before editing: `find_wave_assets_by_category({ category, query?, sources?, limit? })`, alias `list_wave_assets_by_category`, alias `search_wave_assets_by_category`, or tolerant `list_wave_assets`. Fill `category` from user intent first: sound/audio -> `audios`, 3D object/character/prop -> `models`, material -> `materials`, image/texture -> `textures`, sky/HDR -> `hdr`, cube-map sky/environment -> `cubeMaps`, skeletal animation -> `animations`, baked vertex/VAT animation -> `vertexAnimations`, JSON/CSV/YAML/XML/ROS data -> `serializedData`. It returns refs safe to use in authored code, ordered projectAlias -> user -> public. In `main.ts`, pass typed bare refs such as `models.X`, `textures.X`, `materials.X`, `audios.X`, `hdr.X`, `cubeMaps.X`, `animations.X`, `vertexAnimations.X`, `videos.X`, `fonts.X`, `serializedData.X`, or `terrains.X`; do not paste raw paths.",
   "- MCP asset-authoring facade rule: quoting or passing existing assets uses typed refs such as `models.X`, `textures.X`, `materials.X`, and `audios.X`; creating/configuring/forking/editing material handles starts from `waveMaterial` and `wave.material.authoring`; path-bound surfaces start from `wavePathSurface`; `assetManager` is reserved for exact low-level asset-pipeline/generated-asset APIs named by a local SDK skill or API lookup.",
   "- MCP material authoring rule: quoting an existing material uses `materials.X`; authoring a material handle uses `waveMaterial`. Do not call internal procedural material lifecycle methods such as `_sync(...)`, `_bindAutoSync(...)`, or `_release(...)` in authored code; apply procedural handles through `entity.useMaterial(...)`, geometry, terrain paint, or shader `.useTexture(...)`. `WaveMaterialAssetEditHandle.sync(assetManager)` remains the explicit commit step for intentional loaded-material asset edits.",
   `- MCP explorer asset tools: \`list_wave_explorer_assets({ query?, assetTypes?, limit? })\`, \`create_wave_asset_upload({ assetKind, filename, contentType?, sizeBytes })\`, \`commit_wave_asset_upload({ assetKind, uploadId, filename, contentType?, sizeBytes, useMeshoptimizer?, useKtx2Compression? })\`, \`get_wave_asset_upload_status({ uploadId, totalChunks? })\`, \`upload_wave_asset({ assetKind, filename, dataBase64? | dataUrl?, contentType?, useMeshoptimizer?, useKtx2Compression? })\`, \`stage_wave_asset_upload_chunk({ uploadId?, chunkIndex, totalChunks, dataBase64 })\`, \`commit_wave_asset_chunk_upload({ assetKind, uploadId, filename, contentType?, totalChunks, totalSizeBytes, useMeshoptimizer?, useKtx2Compression? })\`, \`abort_wave_asset_upload({ uploadId })\`, \`rename_wave_asset({ path, name })\`, and \`delete_wave_asset({ path })\` operate on uploaded user assets shown by the asset explorer. \`assetKind\` values come from the Wave Studio upload policy SSOT: ${getWaveStudioBridgeAssetUploadKindHelpText()}. Status and abort require the same write token, but can still run after the active Studio write grant expires. Read \`resultSummary\` first: asset tools report ASSET ... OK, ASSET ... FAILED, or ASSET ... PENDING in the same response.`,
@@ -44767,8 +44779,8 @@ var WAVE_MCP_TOOL_CATALOG_GUIDE = [
   "- Marker waypoint recipe: direct marker position/rotation questions are Observe and call `list_wave_runtime_markers` directly. When the user asks to use clicked/marked points in code, start a route with `marker.use` plus `code.author` or the fitting fast-lane code kind, then call `list_wave_runtime_markers`. Read the target file, use marker `worldPosition`/`worldRotation` as waypoint/path/placement inputs, and verify with screenshot or marker re-read. Retrieve a path/placement skill only when current code does not reveal the pattern.",
   "",
   "studio.assets - refs, uploads, and asset library:",
-  "- Asset resolution rule: before writing an asset-map input, reuse an exact ref already visible in code or call category-first asset discovery (`find_wave_assets_by_category`, alias `list_wave_assets_by_category`) with required `category`, semantic `query`, and small `limit`; do not invent `models.<asset>`, `textures.<asset>`, `materials.<asset>`, `audios.<asset>`, `hdr.<asset>`, `cubeMaps.<asset>`, or `animations.<asset>` keys from memory. Do not infer absence from a capped category list.",
-  "- Existing asset arguments should be typed bare refs in main files, such as `models.Robot`, `textures.Grass`, `materials.Wood`, `audios.Click`, `hdr.StudioSky`, `cubeMaps.studio`, `animations.Run`, `videos.Intro`, `fonts.Title`, `serializedData.UnitreePose`, or `terrains.Alpine`.",
+  "- Asset resolution rule: before writing an asset-map input, reuse an exact ref already visible in code or call category-first asset discovery (`find_wave_assets_by_category`, alias `list_wave_assets_by_category`) with required `category`, semantic `query`, and small `limit`; do not invent `models.<asset>`, `textures.<asset>`, `materials.<asset>`, `audios.<asset>`, `hdr.<asset>`, `cubeMaps.<asset>`, `animations.<asset>`, or `vertexAnimations.<asset>` keys from memory. Do not infer absence from a capped category list.",
+  "- Existing asset arguments should be typed bare refs in main files, such as `models.Robot`, `textures.Grass`, `materials.Wood`, `audios.Click`, `hdr.StudioSky`, `cubeMaps.studio`, `animations.Run`, `vertexAnimations.HorseGallopVat`, `videos.Intro`, `fonts.Title`, `serializedData.UnitreePose`, or `terrains.Alpine`.",
   "- Asset authoring facade split: quote existing assets as typed refs (`models.X`, `textures.X`, `materials.X`, `audios.X`, etc.); author material handles through `waveMaterial` and `wave.material.authoring`; use `assetManager` only for exact generated-asset/asset-pipeline APIs named by a local SDK Wave skill or API lookup.",
   '- `find_wave_assets_by_category`: category-first refs safe to write in code, such as `models.Robot`, `textures.Grass`, `materials.Wood`, `audios.Click`. Aliases: `list_wave_assets_by_category`, `search_wave_assets_by_category`, tolerant `list_wave_assets`. Examples: `{ category:"models", query:"sparrow", limit:50 }`, `{ category:"audios", query:"footstep", limit:50 }`, `{ category:"materials", query:"grass", limit:50 }`.',
   "- `list_wave_explorer_assets`: uploaded asset library metadata for management: path, URL, display/ref name, type, size. May be empty; not a fallback for built-in/public refs.",
@@ -45961,6 +45973,18 @@ function normalizeKnownDimensionsMm(value) {
   }
   return Object.keys(result).length > 0 ? result : null;
 }
+function duplicateStrings(items) {
+  const seen = /* @__PURE__ */ new Set();
+  const duplicates = /* @__PURE__ */ new Set();
+  for (const item of items) {
+    if (seen.has(item)) {
+      duplicates.add(item);
+    } else {
+      seen.add(item);
+    }
+  }
+  return [...duplicates];
+}
 function parseModelingJobArgs(args) {
   const sourcePrompt = normalizeOptionalString(args?.sourcePrompt) ?? normalizeOptionalString(args?.prompt) ?? normalizeOptionalString(args?.description);
   if (!sourcePrompt) {
@@ -45977,6 +46001,14 @@ function parseModelingJobArgs(args) {
       "`knownDimensionsMm` must be a JSON object with only JSON-safe values."
     );
   }
+  const requiredParts = optionalStringArray(args?.requiredParts) ?? [];
+  const duplicateRequiredParts = duplicateStrings(requiredParts);
+  if (duplicateRequiredParts.length > 0) {
+    return errorToolResult(
+      "invalid_arguments",
+      `\`requiredParts\` names must be unique because Wave getPart(name) requires unambiguous public part names. Duplicates: ${duplicateRequiredParts.join(", ")}.`
+    );
+  }
   return {
     assetName: sanitizeAssetName(rawAssetName),
     sourcePrompt,
@@ -45984,7 +46016,7 @@ function parseModelingJobArgs(args) {
     referenceImagePaths: optionalStringArray(args?.referenceImagePaths) ?? [],
     targetStyle: normalizeOptionalString(args?.targetStyle) ?? null,
     intendedUse: normalizeOptionalString(args?.intendedUse) ?? null,
-    requiredParts: optionalStringArray(args?.requiredParts) ?? [],
+    requiredParts,
     knownDimensionsMm
   };
 }
@@ -45992,7 +46024,36 @@ function markdownList(items, emptyText) {
   if (items.length === 0) return `- ${emptyText}`;
   return items.map((item) => `- ${item}`).join("\n");
 }
+var WAVE_OBJECT_MODEL_PARTS_CONTRACT = `## WaveEngine objectModel SSOT contract
+
+When requiredParts is non-empty, or the user asks for named/selectable/collidable/material-addressable parts, the GLB must carry Wave objectModel metadata. Mesh names, ordered mesh arrays, and per-mesh part metadata are not source of truth.
+
+Required GLB shape for part-aware output:
+
+- Add an empty/transform node named \`__wave_model_object_model\`; it must have no children.
+- Put \`waveModelObjectModel\` in that node's metadata/extras.
+- The value must be a valid WaveModelObjectModel JSON object:
+  - \`version: 1\`
+  - \`modelId\`: stable asset id/name
+  - \`revision\`: stable revision string for this generated artifact
+  - \`meshes\`: one record per render mesh with stable \`id\`, \`displayName\`, and \`order\`
+  - \`parts\`: one record per user-facing part with stable \`id\`, public \`name\`, \`order\`, optional \`parentPartId\`, optional \`rotationPivot\`, optional \`visualFrame\`
+  - \`meshPartBindings\`: explicit bindings from mesh id to part id with role \`visual\` or \`collision\`
+  - \`parentPartId\` on child part records when parts have authored parent/child relationships
+  - \`topology\`: include \`rootPartIds\` and \`joints: []\` only when a rig/joint topology is needed
+  - \`materialSlots\` and \`materialBindings\`: canonical material targets when materials are meant to be changed by mesh or part
+
+Rules:
+
+- If user did not ask for parts, do not invent parts for every mesh. Output mesh-only GLB.
+- If a visual part contains multiple meshes, bind all meshes to the same part id.
+- Preserve authored pivots/origins as objectModel \`rotationPivot\` and \`visualFrame\`, not by baking them away.
+- Do not write old per-mesh part projection keys, legacy metadata part arrays, mesh-name-derived part ids, or positional part arrays.
+- Validate before upload: every required part name appears in \`objectModel.parts[].name\`, and every part-owned mesh has a matching \`meshPartBindings[]\` record.
+`;
 function buildModelingSupportFiles(input) {
+  const requestedPartsText = input.requiredParts.length > 0 ? input.requiredParts.join(", ") : "none explicitly requested; keep output mesh-only unless the source request itself asks for named/selectable/collidable/material-addressable parts";
+  const visiblePartsInstruction = input.requiredParts.length > 0 ? "- Named visible parts matching requiredParts exactly." : "- Mesh/object breakdown only; do not invent Wave parts unless the source request itself asks for named/selectable/collidable/material-addressable parts.";
   const briefJson = JSON.stringify({
     assetName: input.assetName,
     sourcePrompt: input.sourcePrompt,
@@ -46005,7 +46066,22 @@ function buildModelingSupportFiles(input) {
     outputContract: {
       preferredModelFile: `${input.assetName}.glb`,
       optionalCadFile: `${input.assetName}.step`,
-      waveStudioImport: "Use create_wave_asset_upload/upload_wave_asset after GLB exists, then author code with models.<assetName>."
+      waveStudioImport: "Use create_wave_asset_upload/upload_wave_asset after GLB exists, then author code with models.<assetName>.",
+      objectModelSSOT: input.requiredParts.length > 0 ? {
+        required: true,
+        envelopeNodeName: "__wave_model_object_model",
+        envelopeMetadataKey: "waveModelObjectModel",
+        forbiddenLegacyTruth: [
+          "old per-mesh part projection keys",
+          "legacy metadata part arrays",
+          "mesh-name-derived part ids",
+          "ordered mesh arrays as part truth"
+        ]
+      } : {
+        required: false,
+        conditionalRequirement: "Embed objectModel SSOT only if the source request itself asks for named/selectable/collidable/material-addressable parts.",
+        rule: "Do not invent objectModel parts for raw multi-mesh GLB unless user explicitly requests parts."
+      }
     }
   }, null, 2);
   const parameterTemplate = JSON.stringify({
@@ -46017,7 +46093,7 @@ function buildModelingSupportFiles(input) {
       overall_height: input.knownDimensionsMm?.overall_height ?? 500,
       bevel_radius: 12
     },
-    parts: input.requiredParts.length > 0 ? input.requiredParts.map((partName) => ({ name: partName, materialHint: "default" })) : [{ name: "body", materialHint: "default" }]
+    parts: input.requiredParts.length > 0 ? input.requiredParts.map((partName) => ({ name: partName, materialHint: "default" })) : []
   }, null, 2);
   return [
     {
@@ -46045,8 +46121,9 @@ ${markdownList(input.referenceImagePaths, "No reference image paths provided.")}
 2. Fill \`parameters.template.json\`.
 3. Run \`python build_step.py parameters.template.json out\` after installing CadQuery/OCP locally.
 4. Convert the STEP/mesh result to GLB with your approved modeling pipeline.
-5. Upload the GLB through Wave Studio MCP asset upload tools.
-6. Author scene code with \`models.${input.assetName}\`.
+5. If parts are requested, embed and validate the Wave objectModel SSOT contract before upload.
+6. Upload the GLB through Wave Studio MCP asset upload tools.
+7. Author scene code with \`models.${input.assetName}\`.
 
 ## Safety
 
@@ -46068,15 +46145,17 @@ Asset name: ${input.assetName}
 Request: ${input.sourcePrompt}
 Target style: ${input.targetStyle ?? "match source/reference"}
 Intended use: ${input.intendedUse ?? "WaveEngine scene asset"}
-Required parts: ${input.requiredParts.length > 0 ? input.requiredParts.join(", ") : "infer minimal public-facing parts"}
+Required parts: ${requestedPartsText}
+
+${WAVE_OBJECT_MODEL_PARTS_CONTRACT}
 
 Use the screenshots/reference images as visual evidence. Return:
 
 - Orthographic front/side/top proportions.
-- Named visible parts.
+${visiblePartsInstruction}
 - Dimensions in millimeters.
 - Bevels, thickness, symmetry, repeating details.
-- Material/color hints only. Do not invent private engine internals.
+- Material/color hints. Do not invent engine internals beyond the Wave objectModel SSOT contract.
 - A JSON parameter block compatible with parameters.template.json.
 `
     },
@@ -46098,7 +46177,6 @@ Use the screenshots/reference images as visual evidence. Return:
           },
           parts: {
             type: "array",
-            minItems: 1,
             items: {
               type: "object",
               required: ["name"],
@@ -46190,7 +46268,11 @@ if __name__ == "__main__":
 
 - Silhouette matches source screenshots from front/side/top.
 - Scale is correct for WaveEngine world use.
-- Parts are named for future objectModel/part authoring where useful.
+- If parts were requested, GLB contains \`waveModelObjectModel\` on the \`__wave_model_object_model\` node metadata/extras.
+- If parts were requested, every required part is present in \`objectModel.parts[].name\`.
+- If parts were requested, every part mesh has explicit \`meshPartBindings[]\`; no per-mesh part metadata, legacy metadata part arrays, or mesh-name fallback is used.
+- If no parts were requested, raw multi-mesh GLB remains mesh-only and does not eagerly invent parts.
+- Part pivots/origins, if authored, survive as \`rotationPivot\` and \`visualFrame\`.
 - Material slots are clean and simple.
 - GLB loads in Wave Studio before code authoring.
 - Uploaded asset appears as \`models.${input.assetName}\`.
@@ -46223,7 +46305,9 @@ async function createWave3dModelingJobTool(args) {
     nextActions: [
       "Use cad-sheet-prompt.md plus screenshots/reference images to produce a CAD parameter spec.",
       "Fill parameters.template.json and run the Python scaffold only in a local modeling environment with CadQuery installed.",
-      "Convert generated model output to GLB, then upload with create_wave_asset_upload/upload_wave_asset.",
+      "Convert generated model output to GLB.",
+      "If parts are requested, embed and validate the Wave objectModel SSOT contract before upload.",
+      "Upload with create_wave_asset_upload/upload_wave_asset.",
       `After upload, author WaveEngine scene code with models.${parsed.assetName}.`
     ],
     caveats: [
@@ -46241,7 +46325,7 @@ function buildWaveAssetListGuidance(input) {
   const hasFilters = hasQuery || hasBuckets || hasSources;
   const hasMore = input.summary.total > input.summary.returned;
   const guidance = [
-    "Use category-first asset discovery for code-safe refs such as models.X, textures.X, materials.X, audios.X, hdr.X, cubeMaps.X, and animations.X. Callable names: `find_wave_assets_by_category`, `list_wave_assets_by_category`, `search_wave_assets_by_category`, or tolerant `list_wave_assets`.",
+    "Use category-first asset discovery for code-safe refs such as models.X, textures.X, materials.X, audios.X, hdr.X, cubeMaps.X, animations.X, and vertexAnimations.X. Callable names: `find_wave_assets_by_category`, `list_wave_assets_by_category`, `search_wave_assets_by_category`, or tolerant `list_wave_assets`.",
     "Choose category from user intent first, then search semantically with `query`; do not browse a broad slice and infer absence."
   ];
   if (hasMore && !hasQuery) {
@@ -46278,7 +46362,7 @@ function buildWaveExplorerAssetListGuidance(input) {
   const hasMore = input.summary.total > input.summary.returned;
   const guidance = [
     "`list_wave_explorer_assets` is for uploaded user-asset management metadata: path, URL, size, display/ref name, rename, and delete.",
-    "It is not the fallback for built-in/public code refs. Use category-first asset discovery (`find_wave_assets_by_category` or alias `list_wave_assets_by_category`) when code needs models.X, textures.X, materials.X, audios.X, hdr.X, cubeMaps.X, or animations.X."
+    "It is not the fallback for built-in/public code refs. Use category-first asset discovery (`find_wave_assets_by_category` or alias `list_wave_assets_by_category`) when code needs models.X, textures.X, materials.X, audios.X, hdr.X, cubeMaps.X, animations.X, or vertexAnimations.X."
   ];
   if (input.summary.total === 0 && !hasQuery && !hasAssetTypes) {
     guidance.push("Empty explorer does not mean no code assets exist; it only means this uploaded-user library view has no returned items.");
@@ -47982,7 +48066,7 @@ var ASSET_CODE_REF_DISCOVERY_INPUT_SCHEMA = {
   properties: {
     category: {
       type: "string",
-      description: `Preferred asset category or alias. Use user intent to fill this first. Supported categories/aliases from Wave Studio asset SSOT: ${ASSET_CATEGORY_HELP}. Examples: sound/audio -> audios, 3D model/character -> models, material -> materials, texture/image -> textures, HDR sky -> hdr, cube-map sky/environment -> cubeMaps, animation -> animations.`
+      description: `Preferred asset category or alias. Use user intent to fill this first. Supported categories/aliases from Wave Studio asset SSOT: ${ASSET_CATEGORY_HELP}. Examples: sound/audio -> audios, 3D model/character -> models, material -> materials, texture/image -> textures, HDR sky -> hdr, cube-map sky/environment -> cubeMaps, skeletal animation -> animations, baked vertex/VAT animation -> vertexAnimations.`
     },
     bucket: {
       type: "string",
@@ -48712,7 +48796,7 @@ function buildHostedWaveStudioMcpToolDefinitions() {
     },
     {
       name: "find_wave_assets_by_category",
-      description: `[studio.assets] Canonical category-first discovery for code refs. Use when code needs an existing asset: choose an asset category from the user intent first (model/sound/material/texture/sky/animation/etc.), then search the paired Wave Studio asset surface: public assets, uploaded user assets, and project aliases. Preferred shape: { category:"materials", query:"grass", limit:50 }. Friendly aliases \`list_wave_assets_by_category\`, \`search_wave_assets_by_category\`, and \`list_wave_assets\` route here. Returned bare refs are safe in code, e.g. models.Car, textures.Grass, materials.Wood, audios.Click, hdr.Sky, animations.Run. The category-filtered response can still be capped; do not infer absence without semantic query refinement.${BROWSER_COMMAND_PENDING_NOTE}`,
+      description: `[studio.assets] Canonical category-first discovery for code refs. Use when code needs an existing asset: choose an asset category from the user intent first (model/sound/material/texture/sky/animation/VAT/etc.), then search the paired Wave Studio asset surface: public assets, uploaded user assets, and project aliases. Preferred shape: { category:"materials", query:"grass", limit:50 }. Friendly aliases \`list_wave_assets_by_category\`, \`search_wave_assets_by_category\`, and \`list_wave_assets\` route here. Returned bare refs are safe in code, e.g. models.Car, textures.Grass, materials.Wood, audios.Click, hdr.Sky, animations.Run, vertexAnimations.HorseGallopVat. The category-filtered response can still be capped; do not infer absence without semantic query refinement.${BROWSER_COMMAND_PENDING_NOTE}`,
       inputSchema: ASSET_CODE_REF_DISCOVERY_INPUT_SCHEMA
     },
     {
@@ -48759,7 +48843,7 @@ function buildHostedWaveStudioMcpToolDefinitions() {
     },
     {
       name: "upload_wave_asset",
-      description: `[studio.assets] Small inline upload only: upload bytes already loaded by the agent as base64/data URL. This tool does not read local paths. Upload decision tree: tiny bytes already in memory -> upload_wave_asset; local file path/normal size -> create_wave_asset_upload + raw PUT + commit_wave_asset_upload; direct_upload_unavailable or chunk-only environment -> stage_wave_asset_upload_chunk + commit_wave_asset_chunk_upload. assetKind values come from the Wave Studio upload policy SSOT: ${BRIDGE_ASSET_UPLOAD_KIND_HELP}. Meshoptimizer defaults on for model-family uploads only; useMeshoptimizer is ignored for non-model assets unless explicitly supported by the browser pipeline. Pass exactly one of dataBase64 or dataUrl. Returns typed refs such as textures.Albedo, cubeMaps.Studio, materials.Wood, audios.Click, models.Robot, animations.Run, fonts.Title, or serializedData.Config.${WRITE_PAIRING_REQUIRED_NOTE}${BROWSER_COMMAND_PENDING_NOTE}`,
+      description: `[studio.assets] Small inline upload only: upload bytes already loaded by the agent as base64/data URL. This tool does not read local paths. Upload decision tree: tiny bytes already in memory -> upload_wave_asset; local file path/normal size -> create_wave_asset_upload + raw PUT + commit_wave_asset_upload; direct_upload_unavailable or chunk-only environment -> stage_wave_asset_upload_chunk + commit_wave_asset_chunk_upload. assetKind values come from the Wave Studio upload policy SSOT: ${BRIDGE_ASSET_UPLOAD_KIND_HELP}. Meshoptimizer defaults on for model-family uploads only; useMeshoptimizer is ignored for non-model assets unless explicitly supported by the browser pipeline. Pass exactly one of dataBase64 or dataUrl. Returns typed refs such as textures.Albedo, cubeMaps.Studio, materials.Wood, audios.Click, models.Robot, animations.Run, vertexAnimations.HorseGallopVat, fonts.Title, or serializedData.Config.${WRITE_PAIRING_REQUIRED_NOTE}${BROWSER_COMMAND_PENDING_NOTE}`,
       inputSchema: {
         type: "object",
         properties: {
@@ -50018,7 +50102,7 @@ function getReadToolDefinitions() {
     },
     {
       name: "create_wave_3d_modeling_job",
-      description: "[wave.modeling] Create a local SDK 3D-modeling job scaffold from a prompt and optional screenshots/reference image paths. Writes README, CAD prompt, JSON parameter template/schema, Python CadQuery STEP scaffold, and validation checklist into a temp job folder. Does not generate/upload a GLB by itself; use asset upload tools after a real model file exists. Aliases: generate_wave_3d_model, create_wave_3d_model, create_wave_3d_model_from_screenshots.",
+      description: "[wave.modeling] Create a local SDK 3D-modeling job scaffold from a prompt and optional screenshots/reference image paths. Writes README, CAD prompt, JSON parameter template/schema, Python CadQuery STEP scaffold, and validation checklist into a temp job folder. Does not generate/upload a GLB by itself; use asset upload tools after a real model file exists. If requiredParts is supplied, the resulting GLB must embed Wave objectModel SSOT metadata via waveModelObjectModel on a __wave_model_object_model node; raw mesh names, per-mesh part metadata, legacy metadata part arrays, or positional mesh arrays are not part truth. Aliases: generate_wave_3d_model, create_wave_3d_model, create_wave_3d_model_from_screenshots.",
       inputSchema: {
         type: "object",
         properties: {
@@ -50059,7 +50143,7 @@ function getReadToolDefinitions() {
           requiredParts: {
             type: "array",
             items: { type: "string" },
-            description: "Optional named visible parts the generated model should preserve."
+            description: "Optional public part names the generated GLB must preserve in objectModel SSOT. When non-empty, model output must include waveModelObjectModel on a __wave_model_object_model node with parts, meshPartBindings, parentPartId/topology/material data as needed, and no per-mesh part metadata projection keys."
           },
           knownDimensionsMm: {
             type: "object",
@@ -51050,7 +51134,7 @@ async function callReadTool(name, args, context) {
         "studio.preview: hot_reload_wave_preview (alias: hotreload_wave_preview), run_wave_preview (alias: run_project), pause_wave_preview (alias: pause_wave_engine), resume_wave_preview (alias: resume_wave_engine), get_wave_runtime_diagnostics (alias: get_wave_errors), get_wave_runtime_performance_snapshot (alias: get_wave_runtime_performance)",
         "studio.capture: capture_wave_screenshot (alias: get_wave_screenshot), get_wave_runtime_entity_snapshot (alias: get_wave_entity_snapshot), list_wave_runtime_markers (alias: list_wave_markers)",
         "wave.authoring: list_wave_skill_families, query_wave_skills, get_wave_skill, query_wave_api",
-        "wave.modeling: create_wave_3d_modeling_job (aliases: generate_wave_3d_model, create_wave_3d_model, create_wave_3d_model_from_screenshots) creates local SDK support files; upload generated GLB later with asset tools"
+        "wave.modeling: create_wave_3d_modeling_job (aliases: generate_wave_3d_model, create_wave_3d_model, create_wave_3d_model_from_screenshots) creates local SDK support files; if parts are requested the generated GLB must embed waveModelObjectModel on a __wave_model_object_model node before upload"
       ],
       rules: [
         "studio.* labels are categories, not callable tools.",

package/dist/sdk/README.md

@@ -3,6 +3,6 @@
 Bundled public-safe WaveEngine SDK lookup cache for wave3d-agent-sdk.
 Generated from sanitized public API/skill corpus during package build.
 
-cacheKey: 2026-06-24.4.wMh4twvnrJPgyEgJhV6QtcSQvoZClKr3
-bundleHash: wMh4twvnrJPgyEgJhV6QtcSQvoZClKr3
-zip: wave-engine-sdk-2026-06-24.4.wMh4twvnrJPgyEgJhV6QtcSQvoZClKr3.zip
+cacheKey: 2026-06-24.4.63mahXl1wJFsVypHTa3YZmbYXIrToIkG
+bundleHash: 63mahXl1wJFsVypHTa3YZmbYXIrToIkG
+zip: wave-engine-sdk-2026-06-24.4.63mahXl1wJFsVypHTa3YZmbYXIrToIkG.zip

package/dist/sdk/manifest.json

@@ -1,21 +1,21 @@
 {
-  "version": "2026-06-24.4.wMh4twvnrJPgyEgJhV6QtcSQvoZClKr3",
+  "version": "2026-06-24.4.63mahXl1wJFsVypHTa3YZmbYXIrToIkG",
   "formatVersion": "2026-06-24.4",
-  "cacheKey": "2026-06-24.4.wMh4twvnrJPgyEgJhV6QtcSQvoZClKr3",
-  "bundleFileName": "wave-engine-sdk-2026-06-24.4.wMh4twvnrJPgyEgJhV6QtcSQvoZClKr3.zip",
-  "bundleHash": "wMh4twvnrJPgyEgJhV6QtcSQvoZClKr3",
+  "cacheKey": "2026-06-24.4.63mahXl1wJFsVypHTa3YZmbYXIrToIkG",
+  "bundleFileName": "wave-engine-sdk-2026-06-24.4.63mahXl1wJFsVypHTa3YZmbYXIrToIkG.zip",
+  "bundleHash": "63mahXl1wJFsVypHTa3YZmbYXIrToIkG",
   "generatedAt": "2026-06-06T00:00:00.000Z",
   "sourceVersions": {
     "onboarding": {
       "promptVersion": "2026-06-22.1",
-      "promptHash": "2lzzgYNUy3U2WxPm5UY9z3ZiaUWUlh-Y"
+      "promptHash": "jvKiC2UCRvVbpVc7IGen5RvQk3V9vRA-"
     },
     "apiHandbook": {
       "version": "1",
-      "contentHash": "d59512be9755b0ae"
+      "contentHash": "58fdedcd747f52b9"
     },
-    "waveSkillCorpusHash": "dcHw5Ebcnx59z7qt9kfN_G23nlxvZSqi",
-    "sdkLookupCorpusHash": "chkQiqOkodizLUk-HrdoQ1HXd428XP7k"
+    "waveSkillCorpusHash": "ol6UwQmeF1EZGOW3uz8NWVzESWOrkc7P",
+    "sdkLookupCorpusHash": "ZJvWnfNdCRcoLSwB6tz3ehkJzGGYeTVd"
   },
   "cacheContract": {
     "llmContextCacheOnly": [
@@ -35,14 +35,14 @@
       "searchDocuments"
     ],
     "rule": "Priority 1 always-on sections must stay in LLM chat/system context. The WaveEngine SDK local cache is public-safe retrieval data, never the only memory for core policy.",
-    "defaultRefreshCommand": "npx -y wave3d-agent-sdk@0.2.14 cache refresh",
+    "defaultRefreshCommand": "npx -y wave3d-agent-sdk@0.2.16 cache refresh",
     "refreshRule": "When using WaveEngine SDK local cache, compare cacheKey, bundleHash, and sourceVersions before trusting local lookup. If any value differs, update the SDK package or reinstall its bundled SDK cache and rebuild local indexes. Do not fetch a remote SDK zip.",
     "onlineFallback": "HTTP Gateway does not provide cloud API lookup. If local Node/npm or cache is refused/unavailable, use only concrete Studio operations and already-known code; repair the local WaveEngine SDK before unfamiliar API authoring."
   },
   "corpus": {
     "skillCount": 67,
-    "apiEntryCount": 4257,
-    "apiMethodGroupCount": 4520,
+    "apiEntryCount": 4260,
+    "apiMethodGroupCount": 4522,
     "apiInheritanceCount": 741
   },
   "files": [
@@ -51,14 +51,14 @@
       "mediaType": "application/json",
       "role": "lookup-guide",
       "bytes": 1311,
-      "hash": "t7FXq-o34BD84aetwe5v7IFwq1V4jg9l"
+      "hash": "YeAaiCkYLuKoMCDXE2XQneoonBtuzAjQ"
     },
     {
       "path": "skills/wave-skills.jsonl",
       "mediaType": "application/jsonl",
       "role": "skill-corpus",
-      "bytes": 559047,
-      "hash": "kpe36hRxZfjMfHU5cKZvjamB0KC8DQ7K"
+      "bytes": 559362,
+      "hash": "qBYj0pNBjtFbA6NPXOeEs8JzOJeoKH4j"
     },
     {
       "path": "skills/foundations.jsonl",
@@ -78,15 +78,15 @@
       "path": "api/entries.jsonl",
       "mediaType": "application/jsonl",
       "role": "api-corpus",
-      "bytes": 4219479,
-      "hash": "5e3mI73T35gOyU-6ufdk317kSedy3nHi"
+      "bytes": 4221610,
+      "hash": "AVX0mRAkXs-jpLsVTwD5x8NGX5U_ApJb"
     },
     {
       "path": "api/method-groups.jsonl",
       "mediaType": "application/jsonl",
       "role": "api-corpus",
-      "bytes": 1420068,
-      "hash": "ZLgLqDrvbF1qO5JitaCM9j_lROa2TfZu"
+      "bytes": 1420909,
+      "hash": "zIVI7FTFXfNe6NqVJmVtqJty_ybf92A-"
     },
     {
       "path": "api/inheritance.jsonl",
@@ -100,14 +100,14 @@
       "mediaType": "application/json",
       "role": "api-corpus",
       "bytes": 219,
-      "hash": "ENc3SeS9IYG6suD3rz4aJv0z3dfE8RaT"
+      "hash": "IkwK7b__4lrVlSlDL5-M2uDiZqcLrpy_"
     },
     {
       "path": "search/search-documents.jsonl",
       "mediaType": "application/jsonl",
       "role": "search-index",
-      "bytes": 3976607,
-      "hash": "e2h7kHS3b6nNtSpRIze7eB6j03lBddXQ"
+      "bytes": 3978654,
+      "hash": "QLsswU10LbjXeHtgS5PziZZ9sHlOBCY4"
     },
     {
       "path": "README.md",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wave3d-agent-sdk",
-  "version": "0.2.14",
+  "version": "0.2.16",
   "description": "WaveEngine Agent SDK for same-machine Wave Studio MCP plus bundled WaveEngine lookup.",
   "type": "module",
   "license": "UNLICENSED",