wave3d-agent-sdk 0.2.5 → 0.2.6

package/dist/cli.js

@@ -662,8 +662,8 @@ PerformanceConfigurator.MatrixTrackedMatrices = [];
 
 // ../../node_modules/@babylonjs/core/Misc/devTools.js
 var WarnedMap = {};
-function _WarnImport(name, warnOnce2 = false) {
-  if (warnOnce2 && WarnedMap[name]) {
+function _WarnImport(name, warnOnce = false) {
+  if (warnOnce && WarnedMap[name]) {
     return;
   }
   WarnedMap[name] = true;
@@ -11907,6 +11907,11 @@ var WavePlane;
 // ../../wave-engine/dist/src/core/coreAbstractions/objectModel/waveModelRigPose.js
 var DEFAULT_REVOLUTE_RANGE = Math.PI / 3;
 
+// ../../wave-engine/dist/src/core/coreAbstractions/geometryKernel/pathMath.js
+var PATH_FORWARD = new Vector3(0, 0, 1);
+var PATH_UP = new Vector3(0, 1, 0);
+var PATH_RIGHT = new Vector3(1, 0, 0);
+
 // ../../node_modules/@babylonjs/core/tslib.es6.js
 function __decorate(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
@@ -40697,63 +40702,6 @@ var Ticks = createWaveTimeUnit("tick");
 var Seconds = createWaveTimeUnit("second");
 var UnitsPerSecond = createWaveRateUnit("unitsPerSecond");
 var DegreesPerSecond = createWaveRateUnit("degreesPerSecond");
-var LogOnceManager = class {
-  loggedMessages = /* @__PURE__ */ new Map();
-  cooldownMs = 6e4;
-  maxCacheSize = 500;
-  callsSinceCleanup = 0;
-  _logWithLevel(level, message) {
-    const now = Date.now();
-    const cacheKey = `${level}:${message}`;
-    const lastLoggedAt = this.loggedMessages.get(cacheKey);
-    const shouldLog = lastLoggedAt === void 0 || now - lastLoggedAt >= this.cooldownMs;
-    if (shouldLog) {
-      console[level](message);
-      this.loggedMessages.set(cacheKey, now);
-    }
-    this.callsSinceCleanup += 1;
-    if (this.callsSinceCleanup >= 100) {
-      this._cleanup(now);
-      this.callsSinceCleanup = 0;
-    }
-  }
-  _cleanup(now) {
-    const cutoff = now - this.cooldownMs;
-    for (const [key, timestamp] of this.loggedMessages.entries()) {
-      if (timestamp < cutoff) {
-        this.loggedMessages.delete(key);
-      }
-    }
-    if (this.loggedMessages.size > this.maxCacheSize) {
-      const entries = Array.from(this.loggedMessages.entries()).sort((a, b) => a[1] - b[1]);
-      const toRemove = entries.slice(0, entries.length - this.maxCacheSize);
-      for (const [key] of toRemove) {
-        this.loggedMessages.delete(key);
-      }
-    }
-  }
-  /** Log once at `console.log` level. */
-  logOnce(message) {
-    this._logWithLevel("log", message);
-  }
-  /** Log once at `console.info` level. */
-  infoOnce(message) {
-    this._logWithLevel("info", message);
-  }
-  /** Log once at `console.warn` level. */
-  warnOnce(message) {
-    this._logWithLevel("warn", message);
-  }
-  /** Log once at `console.error` level. */
-  errorOnce(message) {
-    this._logWithLevel("error", message);
-  }
-  /** Clear retained suppression state. */
-  clear() {
-    this.loggedMessages.clear();
-  }
-};
-var globalLogOnce = new LogOnceManager();
 function validateNonZeroFinite(label, value) {
   if (!Number.isFinite(value) || Math.abs(value) <= Number.EPSILON) {
     throw new Error(`[WaveTime] ${label} requires a finite value whose magnitude is greater than 0.`);
@@ -41467,6 +41415,7 @@ var WorldElementKind;
   WorldElementKind2["Entity"] = "entity";
   WorldElementKind2["Water"] = "water";
   WorldElementKind2["Surface"] = "surface";
+  WorldElementKind2["GrassCarpet"] = "grassCarpet";
   WorldElementKind2["Custom"] = "custom";
   WorldElementKind2["POI"] = "poi";
   WorldElementKind2["Trigger"] = "trigger";
@@ -41493,6 +41442,7 @@ var SUPPORTED_WORLD_ELEMENT_KINDS = [
   WorldElementKind.Entity,
   WorldElementKind.Water,
   WorldElementKind.Surface,
+  WorldElementKind.GrassCarpet,
   WorldElementKind.Custom,
   WorldElementKind.POI
 ];
@@ -42533,8 +42483,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.5";
-var WAVE3D_AGENT_SDK_REQUIRED_BUILD = "agent-sdk-20260617.6";
+var WAVE3D_AGENT_SDK_REQUIRED_VERSION = "0.2.6";
+var WAVE3D_AGENT_SDK_REQUIRED_BUILD = "agent-sdk-20260620.1";
 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";
@@ -42808,7 +42758,7 @@ var WAVE_MCP_TOOL_CONTRACTS = {
   query_wave_skills: { workMode: "author", domain: "code", safety: "readOnly", targetPolicy: "none", requiresTaskRoute: false, supportsTaskRoute: true },
   get_wave_skill: { workMode: "author", domain: "code", safety: "readOnly", targetPolicy: "none", requiresTaskRoute: false, supportsTaskRoute: true },
   list_wave_projects: { workMode: "observe", domain: "project", safety: "readOnly", targetPolicy: "none", requiresTaskRoute: false, supportsTaskRoute: true },
-  read_wave_project: { workMode: "observe", domain: "project", safety: "readOnly", targetPolicy: "exactProjectIdRequired", requiresTaskRoute: false, supportsTaskRoute: true },
+  read_wave_project: { workMode: "observe", domain: "project", safety: "readOnly", targetPolicy: "projectIdOrUrlRequired", requiresTaskRoute: false, supportsTaskRoute: true },
   list_wave_project_templates: { workMode: "observe", domain: "project", safety: "readOnly", targetPolicy: "none", requiresTaskRoute: false, supportsTaskRoute: true },
   get_wave_runtime_diagnostics: { workMode: "observe", domain: "runtime", safety: "readOnly", targetPolicy: "none", requiresTaskRoute: false, supportsTaskRoute: true },
   get_wave_runtime_performance_snapshot: { workMode: "observe", domain: "runtime", safety: "readOnly", targetPolicy: "none", requiresTaskRoute: false, supportsTaskRoute: true },
@@ -44442,35 +44392,35 @@ var WAVE_MCP_AGENT_BRIEF = [
   "0a. Do not invent MCP tool names. After onboarding, call `tools/list` (or read the returned tool catalog) and use concrete names. Common aliases and safe high-confidence typos are tolerated; destructive/write fuzzy matches require an exact follow-up call. There is no `get_wave_current_project`; use `get_wave_session` for current project/session/active-file context.",
   `0b. Transport rule: choose topology first. Same-machine agent + same Wave Studio browser computer -> use copied \`MCP_URL\` WaveEngine Agent SDK (\`http://127.0.0.1:47231/mcp\`). On localhost, MCP_TOKEN is a local pairing secret, not account/cloud auth. If localhost is refused/unreachable, start exact SDK \`${WAVE3D_AGENT_SDK_START_COMMAND}\` when your runtime allows shell/Node/npm. If SDK is stale, missing tools, printing secrets, or local 401 follows an SDK restart, stop it and restart while preserving MCP_TOKEN as the local pairing secret with \`${WAVE3D_AGENT_SDK_TOKEN_PRESERVING_START_COMMAND}\`; use the current MCP_TOKEN value without printing it. Then recheck /health and tools/list. Same-machine stale/missing tools/401-with-Gateway-success means repair local SDK first, do not use HTTP Gateway first. Same-machine HTTP Gateway is degraded fallback only after SDK cannot run, update, or adopt; convenience, habit, or successful Gateway auth is not a valid fallback reason. Different machine, remote container, cloud agent, sandbox without shell/Node/npm, or localhost points to the agent machine -> use \`MCP_HTTP_GATEWAY_FALLBACK_URL\` directly, where MCP_TOKEN is an HTTP Gateway bearer. Do not start WaveEngine Agent SDK on the wrong machine.`,
   "0b-recovery. If connection/session/onboarding/cache/mirror/timeout state is unclear, call `get_wave_mcp_health` (aliases `mcp_health`, `mcp_status`) first for status, then call `recover_wave_connection({ lastErrorCode?, failedTool?, symptom? })` and follow its `nextAction` exactly. Use recovery after `agent_onboarding_required`, `session_not_found`, `command_timeout`, `command_lease_expired`, `workspace_mirror_not_ready`, `hosted_mcp_proxy_failed`, local/HTTP Gateway fallback confusion, or sleeping-tab symptoms. If local HTTP returns 401 but HTTP Gateway accepts the same MCP_TOKEN, update/restart WaveEngine Agent SDK first. If every endpoint returns 401/bridge_auth_invalid before any tool result, ask user for fresh Copy to Agent.",
-  `0c. Cache priorities: Priority 1 is active role/context cache. Keep the role, coding guardrails, authoring workflow, full intent taxonomy (${WAVE_MCP_TASK_INTENT_KIND_VALUES.join(", ")}), Studio tool policy, assets/VFS/hot-reload rules, prompt version, and prompt hash in active LLM context as system-prompt-like rules. Priority 2 is WaveEngine SDK Cache. Production HTTP Gateway/local-SDK onboarding must not claim normal cached success until SDK cache is prepared or explicit accept proof passes. If cache cannot work because sandbox/no filesystem/no Node/npm/user refusal/refresh failure, accept degraded fallback explicitly with \`waveEngineSdkFallbackMode:"studio_ops_only"\` plus \`waveEngineSdkUnavailableReason\` plus \`studioOpsOnlyFallbackAccepted:true\`, and warn user HTTP Gateway is Studio-ops-only and exact API lookup requires local SDK/cache repair. Keep live transport and retrieval cache separate: \`wave3d-agent-sdk start\` is long-running MCP transport; \`wave3d-agent-sdk cache refresh\` reinstalls the package-bundled SDK locally. Never use cache refresh to switch MCP transport, and never treat cache failure as local transport failure. Use SDK Cache for unfamiliar authoring skill/API lookup when Node/npm/local cache are allowed.`,
-  '0d. Local parity rule: WaveEngine Agent SDK `tools/list` mirrors the HTTP Gateway catalog plus SDK session discovery extras. Live-session tools run through the paired browser. Local calls wait directly for browser results. Only call `get_wave_command_result` when a tool response actually includes `status:"pending"` and `requestId`; on local it is normally catalog parity only.',
-  '0e. Agent behavior harness: choose MECE work mode first. Observe = read/inspect/answer only; call read tools directly. Operate = direct Studio command with no code/design choice; call concrete tools directly without `start_wave_task` for run preview, hot reload, save/share, exact VFS create/rename/delete, asset upload/rename/delete, new project, project rename, and open project by exact projectId. Author = create/change behavior/content through code/API; call `start_wave_task`, gather evidence, optionally fast-start with `nextPhase:"execute"` and editPlan, then edit. Diagnose = find root cause first; observe/read first, then transition to Operate or Author. General = not concrete Wave work; use `agent.general`. `query_wave_api`, `edit_wave_file`, `apply_wave_patch`, and code authoring fast lanes remain route-bound. Exact target rule: never invent paths, asset paths, or project ids; list/read/ask first.',
+  `0c. Cache priorities: Priority 1 is active role/context cache. Keep the role, coding guardrails, authoring workflow, full intent taxonomy (${WAVE_MCP_TASK_INTENT_KIND_VALUES.join(", ")}), Studio tool policy, assets/VFS/hot-reload rules, prompt version, and prompt hash in active LLM context as system-prompt-like rules. Priority 2 is WaveEngine SDK Cache. Production HTTP Gateway/local-SDK onboarding must not claim normal cached success until SDK cache is prepared or explicit accept proof passes. If cache cannot work because sandbox/no filesystem/no Node/npm/user refusal/refresh failure, accept degraded fallback explicitly with \`waveEngineSdkFallbackMode:"studio_ops_only"\` plus \`waveEngineSdkUnavailableReason\` plus \`studioOpsOnlyFallbackAccepted:true\`, and warn user HTTP Gateway is Studio-ops-only and skill/API lookup requires local SDK/cache repair. Keep live transport and retrieval cache separate: \`wave3d-agent-sdk start\` is long-running MCP transport; \`wave3d-agent-sdk cache refresh\` reinstalls the package-bundled SDK locally. Never use cache refresh to switch MCP transport, and never treat cache failure as local transport failure. Use SDK Cache for unfamiliar authoring skill/API lookup when Node/npm/local cache are allowed.`,
+  '0d. Local parity rule: WaveEngine Agent SDK `tools/list` mirrors the HTTP Gateway Studio-operation catalog, then adds local SDK lookup/session-discovery extras. Live-session tools run through the paired browser. Local calls wait directly for browser results. Only call `get_wave_command_result` when a tool response actually includes `status:"pending"` and `requestId`; on local it is normally catalog parity only.',
+  '0e. Agent behavior harness: choose MECE work mode first. Observe = read/inspect/answer only; call read tools directly. Operate = direct Studio command with no code/design choice; call concrete tools directly without `start_wave_task` for run preview, hot reload, save/share, exact VFS create/rename/delete, asset upload/rename/delete, new project, project rename, and open project by exact projectId. Author = create/change behavior/content through code/API; call `start_wave_task`, gather evidence, optionally fast-start with `nextPhase:"execute"` and editPlan, then edit. Diagnose = find root cause first; observe/read first, then transition to Operate or Author. General = not concrete Wave work; use `agent.general`. Local-SDK `query_wave_api`, `edit_wave_file`, `apply_wave_patch`, and code authoring fast lanes remain route-bound. Exact target rule: never invent paths, asset paths, or project ids; list/read/ask first.',
   "0f. Diagnose-only tasks use `code.debug`; bug-fix tasks use both `code.debug` and `code.author` so evidence can lead to edits.",
-  "0g. Skill onion rule: for normal Author work, do not use raw user prose as a skill/API query. Triage intent -> choose skill family with `list_wave_skill_families` -> call `query_wave_skills` with selected `families`/`familyId` and a small within-family phrase -> call `get_wave_skill` -> call local-SDK `query_wave_api` only for exact signature/global/value uncertainty. HTTP Gateway hides/retires cloud API lookup. Example: \u201Cturn continuously left\u201D routes to `wave.transform` plus possibly `wave.animate`, then skill query \u201Ccontinuous rotation semantic left\u201D.",
+  "0g. Skill onion rule: for normal Author work, do not use raw user prose as a skill/API query. On the local SDK endpoint, triage intent -> choose skill family with `list_wave_skill_families` -> call `query_wave_skills` with selected `families`/`familyId` and a small within-family phrase -> call `get_wave_skill` -> call `query_wave_api` only for exact signature/global/value uncertainty. HTTP Gateway hides/retires cloud skill/API lookup. Example: \u201Cturn continuously left\u201D routes to `wave.transform` plus possibly `wave.animate`, then skill query \u201Ccontinuous rotation semantic left\u201D.",
   "Shared authoring workflow:",
   ...buildWaveMcpAuthoringWorkflowLines(),
-  "First MCP calls after transport selection: initialize the chosen endpoint, read onboarding, accept it, read the tiny ready summary, then call `tools/list`, `get_wave_session`, and `list_wave_files`; call `get_wave_tool_map` only when the tool menu is unclear. Use the package-bundled WaveEngine SDK Cache for unfamiliar authoring lookup. For each user request, choose Observe/Operate/Author/Diagnose/General. Do not route direct Operate commands just to run/save/hot-reload/create/delete exact targets. Always route before exact API lookup or code edits. Use fast-lane route kinds when the code-authoring request is already exact or visibly pattern-preserving.",
-  'Code-edit loop: assess with `read_wave_file`/skills/assets as needed -> `start_wave_task`; if enough context is already read, include `nextPhase:"execute"` plus editPlan to skip a separate `advance_wave_task` call. For exact one-file line/text edits, start the route and call `edit_wave_file` directly with exact `path` plus `startLine`/`endLine`/`text`, `edits:[{startLine,endLine,text}]`, or `oldText`/`newText`; no advance call needed. Use `advance_wave_task({ nextPhase:"lookup" })` only if exact API facts are missing. On final simple edit, prefer `edit_wave_file({ ..., awaitHotReload: true })` to combine edit + hot reload + bounded diagnostics in one call; use `requestHotReload: true` only when you intentionally want fire-and-poll. Use `apply_wave_patch` only for grouped/multi-file work. Fast lane examples: \u201Ccall showDirection on Amy\u201D -> `code.direct_edit`; `cube.setColor(COLOR.RED)` plus \u201Cmake cube blue\u201D -> `code.semantic_guess_edit` with no `query_wave_api` unless uncertain/failing. \u201CPlace cubes in a line\u201D writes new layout code, so it is `code.author`, and should prefer WaveEngine-native APIs such as `myScene.placeInline(...)` over manual coordinates.',
+  "First MCP calls after transport selection: initialize the chosen endpoint, read onboarding, accept it, read the tiny ready summary, then call `tools/list`, `get_wave_session`, and `list_wave_files`; call `get_wave_tool_map` only when the tool menu is unclear. Use the package-bundled WaveEngine SDK Cache for unfamiliar authoring lookup. For each user request, choose Observe/Operate/Author/Diagnose/General. Do not route direct Operate commands just to run/save/hot-reload/create/delete exact targets. Always route before local SDK exact API lookup or code edits. Use fast-lane route kinds when the code-authoring request is already exact or visibly pattern-preserving.",
+  'Code-edit loop: assess with `read_wave_file`/local-SDK skills/assets as needed -> `start_wave_task`; if enough context is already read, include `nextPhase:"execute"` plus editPlan to skip a separate `advance_wave_task` call. For exact one-file line/text edits, start the route and call `edit_wave_file` directly with exact `path` plus `startLine`/`endLine`/`text`, `edits:[{startLine,endLine,text}]`, or `oldText`/`newText`; no advance call needed. Use `advance_wave_task({ nextPhase:"lookup" })` only if exact API facts are missing. On final simple edit, prefer `edit_wave_file({ ..., awaitHotReload: true })` to combine edit + hot reload + bounded diagnostics in one call; `requestHotReload:true` also waits by default unless paired with `awaitHotReload:false`. Use `apply_wave_patch` only for grouped/multi-file work. Fast lane examples: \u201Ccall showDirection on Amy\u201D -> `code.direct_edit`; `cube.setColor(COLOR.RED)` plus \u201Cmake cube blue\u201D -> `code.semantic_guess_edit` with no local-SDK `query_wave_api` unless uncertain/failing. \u201CPlace cubes in a line\u201D writes new layout code, so it is `code.author`, and should prefer WaveEngine-native APIs such as `myScene.placeInline(...)` over manual coordinates.',
   "Code-edit hotreload safety: avoid raw unmanaged callback roots in authored .ts/.js files: no timers, RAF, listeners, Promise chains, observers, workers, sockets, channels, eventBus/myScene raw subscriptions, or raw event-handler property assignments. Use Wave-owned callbacks/Animate/tick/state/Director APIs. Edit tools preflight this rule and runtime bundling blocks violations before authored code runs.",
   "Asset-upload Operate loop: `create_wave_asset_upload` -> raw PUT with every returned header -> `get_wave_asset_upload_status` until receivedBytes matches -> `commit_wave_asset_upload` -> if the commit response is pending, poll `get_wave_command_result` -> category-first asset discovery (`find_wave_assets_by_category` or alias `list_wave_assets_by_category`) with the returned asset category before writing the ref into code. If upload is part of Author work, keep the route id; otherwise direct Operate is fine.",
-  "Project Operate loops: save with `save_wave_project`; share with `share_wave_project` and send returned `url`; list/read examples with `list_wave_projects` -> `read_wave_project`; rename saved project metadata with `list_wave_projects` -> `rename_wave_project`; open only when user wants workspace replacement and you have exact projectId from `list_wave_projects`; new project with `list_wave_project_templates` -> `new_wave_project`.",
+  "Project Operate loops: save with `save_wave_project`; share with `share_wave_project` and send returned `url`; silently read shared/published links with `read_wave_project({ url })` without opening; list/read saved examples with `list_wave_projects` -> `read_wave_project({ projectId })`; rename saved project metadata with `list_wave_projects` -> `rename_wave_project`; open only when user wants workspace replacement and you have exact projectId from `list_wave_projects`; new project with `list_wave_project_templates` -> `new_wave_project`.",
   "Studio families: `studio.vfs` for files, `studio.assets` for uploads/library refs, `studio.project` for save/rename/open/new/share, `studio.preview` for hot reload/run/diagnostics, `studio.capture` for screenshot/snapshot, `studio.mcp` for session/pending commands/policy, `studio.export` for output workflows.",
   "Geometry skill routes: for soft custom forms such as a rounded bun, cushion, puffy/squishy toy, or organic rounded prop, route to `wave.geometry.sdf-surface`: create an SDF surface asset, compose recipe primitives, call `.apply()`, then bind the generated asset with `useModel(...)`.",
   "Surface skill routes: for roads, trails, highways, walkways, lanes, bridge decks, waterfalls, or other path-bound surfaces, route to `wave.geometry.surface-ribbons`: author a `wavePathSurface` with `.along(...)` or `.between(...)`, then compose material, collider, terrain attachment, center samples, and navigation on that surface as needed.",
   "World population route: for forests, grass, rocks, water, streamed entities, or environmental scatter tied to terrain/streaming surfaces, route to `wave.world.world-elements`: prefer `scene.world.scatter(...)` or bootstrap `world.scatter(...).renderAs(...).density(...).randomScale(...).apply()` before local placement, spawn loops, or instancing/batching.",
   "Obby/platform route: controlled humanoid/vehicle/flight players use `wave.physics.kinematic-controller-authoring`; static and 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.",
   "Multiplicity skill route: for many local repeated model-backed objects, route to `wave.group.instancing-and-batching`: classify per-instance needs first. Use `waveThinBatch` only for visual-only mass, `waveInstanceMesh`/`InstanceMeshGroup`/`waveInstanceGroup` for selectable/interactive repeated instances, and real `Prop`/`Actor` entities for physics, AI, audio, damage state, or rich lifecycle. Count alone never chooses thin batch; terrain/world population is the world-elements route.",
-  "Model voxelization route: for voxelize/voxelized/volexize model requests, route to `wave.model.voxelization`. Use `source.model.voxelizing().relativeSize(0.05).surfaceOnly().onWorkerThread().usingCubes().asThinBatch().applyAsync()` only when async/worker authored code is explicitly acceptable. If code must stay synchronous, use `onMainThread().apply()` only for tiny local voxel work. Never use `.apply().then(...)` or Promise callback chains. Use `voxelBatch.detectNear(explorer).within(5)` for local proximity, `voxelBatch.batchTransform.getColorAt(index)` before highlight/restore, and `voxelBatch.whenIndexClicked(index => voxelBatch.atIndex(index).enlargeBy(1.2))` for per-index clicks. Do not use `voxelizeHeavy`, `voxelize({ voxelSize })`, `withVoxelSize`, or `sharedBox`.",
+  "Model voxelization route: for voxelize/voxelized/volexize model requests, route to `wave.model.voxelization`. Use `source.model.voxelizing().relativeSize(0.05).surfaceOnly().onWorkerThread().usingCubes().asThinBatch().applyAsync()` only when async/worker authored code is explicitly acceptable. If code must stay synchronous, use `onMainThread().apply()` only for tiny local voxel work. Never use `.apply().then(...)` or Promise callback chains. Use `voxelBatch.detectNear(explorer).within(5)` for local proximity, `voxelBatch.batchTransform.getColorAt(index)` before highlight/restore, and `voxelBatch.whenIndexClicked(index => voxelBatch.at(index).enlargeBy(1.2).done().commitBuffers())` for per-index clicks. Do not use `voxelizeHeavy`, `voxelize({ voxelSize })`, `withVoxelSize`, `sharedBox`, or stale `atIndex`.",
   "VFS edits: primary tool is forgiving `edit_wave_file`; it infers exact-text, line-range, one-file `edits:[...]`, or whole-file replacement from arguments and tolerates common field aliases. Use `apply_wave_patch({ operations: [...] })` only for grouped/multi-file/strict diff work.",
   "VFS managed files: project.assetrefs.ts, project.scene.ts, project.scenes.ts, and project.execution.ts are Studio-managed read-only. 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 asset_manifest_or_loader, instrument_registry, scene_registry, or execution_manifest; Studio owns those paths.",
   "VFS hashes: simple edit tools auto-resolve the latest mirror `contentHash`; pass `baseHash` only when you already have it or when using advanced `apply_wave_patch`. Always inspect `changedFiles`, `changedPaths`, `partial`, and `skippedOperations` after edits.",
   "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 Studio preview; do not put Mermaid in markdown fences unless user specifically wants markdown text.',
+  '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. 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.",
-  "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 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.",
+  "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; use `requestHotReload: true` for fire-and-poll, or call `hot_reload_wave_preview` for standalone preview refresh. Standalone `run_wave_preview` / `hot_reload_wave_preview` can use `awaitRuntimeResult: true` for same-call bounded diagnostics. 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.",
+  "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.",
   "Preview fallback: if an edit result says `hotReloadRequested: false`, the preview did not refresh; inspect `hotReloadSkippedReason`/skips, then call `hot_reload_wave_preview` or `run_wave_preview` only as appropriate. Use `run_wave_preview` only when diagnostics show no successful preview yet (`hasRunSucceeded: false`), to honor an explicit full-restart request, or as the last resort after hot reload/polling fails or gets stuck.",
   'Verification: never report completion immediately after edit, run, or hot reload. If a tool returns `status:"pending"` plus `requestId`, poll `get_wave_command_result`; otherwise continue to diagnostics. Poll diagnostics until `runtimeBusy` is false and `lastRuntimeOutcome` is `success` or `error`; ignore terminal outcomes older than the edit/runtime `requestedAt` or `runtimeActionRequestedAt`. `editorErrorCount > 0` means Monaco/linter/compile errors still block the code; read `editorDiagnostics` and do not report success.',
   'Observation: logs are history. If outcome is success, choose one relevant proof tool when needed: `capture_wave_screenshot({ resolution: "L" })` for visual changes (WaveEngine Agent SDK returns `localPath`; HTTP Gateway returns exact `dataBase64`, not `imageBase64`), `get_wave_runtime_entity_snapshot` for live transform/state, or `list_wave_runtime_markers` for clicked marker positions/rotations.',
@@ -44484,9 +44434,9 @@ var WAVE_MCP_AGENT_BRIEF = [
 // ../../src/lib/waveStudio/aiAssist/bridge/hosted/mcpResources/authoringGlobals.ts
 var WAVE_MCP_AUTHORING_GLOBALS_GUIDE = [
   "Wave Studio bare authoring globals, common examples only:",
-  "- This guide is a compact memory aid, not an exhaustive list. Engine authoring globals come from the generated `waveStudio-globals.d.ts` surface indexed by `query_wave_api`; Studio wrapper conveniences such as `waveStudio`, `waveEngine`, and live asset overlays are documented by MCP guardrails/tools and the current session asset/file tools.",
+  "- This guide is a compact memory aid, not an exhaustive list. Engine authoring globals come from the generated `waveStudio-globals.d.ts` surface indexed by local-SDK `query_wave_api`; Studio wrapper conveniences such as `waveStudio`, `waveEngine`, and live asset overlays are documented by MCP guardrails/tools and the current session asset/file tools.",
   "- Runtime values injected into Studio-authored `main.ts` files should be used bare. Do not import them and do not qualify them with guessed namespaces. Query when unsure.",
-  "- Intent/loop/time values: `Apply`, `Animate`, `Snapshot`, `Repeat`, `ToTrue`, `ToFalse`, `Flips`, `FirstTime`, `EveryTime`, `PerSecond`, `PerTick`, `Ticks`, `Seconds`, `UnitsPerSecond`, `DegreesPerSecond`.",
+  "- 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.",
@@ -44494,8 +44444,8 @@ var WAVE_MCP_AUTHORING_GLOBALS_GUIDE = [
   "- Scene/runtime handles: prefer `myScene` for scene composition and `waveStudio` for Studio operations. `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.",
-  "- Type names are not import paths. If the handbook shows a type like `TransformVerbMode` or `WaveRateUnit`, look for the matching bare runtime value such as `Animate` or `DegreesPerSecond` before writing code.",
-  '- If you are unsure whether an engine global exists, query it first, for example `query_wave_api({ query: "DegreesPerSecond" })`, `query_wave_api({ query: "waveMaterial createWater" })`, or `query_wave_api({ query: "Keyboard enum" })`. For asset refs, use `find_wave_assets_by_category` instead of guessing property names.',
+  "- Type names are not import paths. If the handbook shows a type like `TransformVerbMode` or `WaveRateUnit`, look for the matching bare runtime value such as `Animate` or `DegreesPerSecond` before writing code. Transform `Snapshot` calls return a snapshot builder; call `.take()` before passing the pose to `transitionTo(...)`.",
+  '- If you are unsure whether an engine global exists, query it first on the local SDK endpoint, for example `query_wave_api({ query: "DegreesPerSecond" })`, `query_wave_api({ query: "waveMaterial createWater" })`, or `query_wave_api({ query: "Keyboard enum" })`. HTTP Gateway hides/retires skill/API lookup. For asset refs, use `find_wave_assets_by_category` instead of guessing property names.',
   "- Good pattern: `cube.keepRotatingAround(Direction.Right).atRateOf(70, DegreesPerSecond).for(50, Seconds).play()`."
 ].join("\n");
 
@@ -44505,7 +44455,7 @@ var WAVE_MCP_CODING_GUARDRAIL = [
   "1. Author user code for Wave Studio runtime, not engine internals. Do not use sys_*, BaseEngine internals, private fields, underscored members, worker/adapter/debug/store/cache APIs, or generated implementation details.",
   "2. Prefer public natural names. Use `Prop`, `Actor`, `Cube`, `Sphere`, etc. instead of `waveProp`, `waveActor`, `waveCube`, `waveSphere` when aliases exist. Drop the `wave` prefix in authored examples.",
   "2a. MCP access policy is set by the user in chat. If the user says read-only, inspect only and avoid mutating tools. If no write intent is given, inspect first. If the user says read-write or asks you to edit, run, upload, save, open, create, rename, or delete, use the write tools needed for that task.",
-  '2b. MCP is an agent behavior harness with MECE work modes. Observe = read/inspect/answer only; call read tools directly (session, files, assets, diagnostics, performance, screenshot, snapshots, markers). Operate = direct Studio command with no code/design choice; call concrete tools directly without `start_wave_task` for run preview, hot reload, save/share, exact VFS create/rename/delete, asset upload/rename/delete, new project, project rename, and open project by exact projectId. Author = create/change behavior/content through code/API; call `start_wave_task`, gather evidence, optionally fast-start execute with `nextPhase:"execute"` plus editPlan, then edit. Exact one-file line/text edits can call `edit_wave_file` immediately after route start when exact path and replacement args are present, including `edits:[{startLine,endLine,text}]`; no advance call needed. Diagnose = find root cause first; observe/read first, then transition to Operate or Author when cause and action are clear. General = not concrete Wave work; classify `agent.general`. `query_wave_api`, `edit_wave_file`, `apply_wave_patch`, code.direct_edit, code.semantic_guess_edit, and code.author are route-bound Author/Diagnose work. Direct Operate still keeps safety: exact path/id/path target required for delete/rename/open; resolve project names with `list_wave_projects`, resolve vague file/asset names with list/read tools or ask. If an edit adds code, creates objects, switches API, or chooses a WaveEngine pattern such as placement/layout/material/animation, it is `code.author`, not semantic guess. Fast lanes skip broad lookup, not file safety/verification, and usually skip `query_wave_api` unless exact spelling/signature/value uncertainty remains or an edit failed.',
+  '2b. MCP is an agent behavior harness with MECE work modes. Observe = read/inspect/answer only; call read tools directly (session, files, assets, diagnostics, performance, screenshot, snapshots, markers). Operate = direct Studio command with no code/design choice; call concrete tools directly without `start_wave_task` for run preview, hot reload, save/share, exact VFS create/rename/delete, asset upload/rename/delete, new project, project rename, and open project by exact projectId. Author = create/change Wave behavior/content through code/API; call `start_wave_task`, gather evidence, optionally fast-start execute with `nextPhase:"execute"` plus editPlan, then edit. Exact one-file line/text edits can call `edit_wave_file` immediately after route start when exact path and replacement args are present, including `edits:[{startLine,endLine,text}]`; no advance call needed. Diagnose = find root cause first; observe/read first, then transition to Operate or Author when cause and action are clear. General = not concrete Wave work; classify `agent.general`. Local-SDK `query_wave_api`, `edit_wave_file`, `apply_wave_patch`, code.direct_edit, code.semantic_guess_edit, and code.author are route-bound Author/Diagnose work. Direct Operate still keeps safety: exact path/id/path target required for delete/rename/open; resolve project names with `list_wave_projects`, resolve vague file/asset names with list/read tools or ask. If an edit adds code, creates objects, switches API, or chooses a WaveEngine pattern such as placement/layout/material/animation, it is `code.author`, not semantic guess. Fast lanes skip broad lookup, not file safety/verification, and usually skip local-SDK `query_wave_api` unless exact spelling/signature/value uncertainty remains or an edit failed.',
   '2c. Use `code.debug` alone only for diagnose/report-only tasks. For "fix this" or "make the error go away", include both `code.debug` and `code.author` so the same route can diagnose root cause and then edit code.',
   `2d. ${WAVE_AUTHORING_CORE_RULES.hotReloadCallbackSafety} The MCP edit tools preflight this rule and the runtime bundler blocks violations before authored code runs. Rewrite to Wave-owned callbacks instead of attempting to bypass the guard.`,
   "3. Wave Studio also injects lowercase call-style helpers such as `prop(...)`, `cube(...)`, `sphere(...)`, `ground(...)`. These are Studio-only authoring conveniences, not wave-engine package exports.",
@@ -44515,7 +44465,7 @@ var WAVE_MCP_CODING_GUARDRAIL = [
   '4c. For roads, trails, highways, walkways, lanes, bridge decks, waterfalls, or cloth/path strips, route to `wave.geometry.surface-ribbons`: author a live visible `wavePathSurface` with `.along(...)` for centerline+width or `.between(...)` for two rails, then use its methods such as `.snapTo(...)`, `.heightAboveSurface(...)`, `.withDistanceUvs(...)`, and `.withSampleSpacing(...)`. For streaming terrain elements, author a pure spec with `new WavePathSurfaceDefinition("name").along(...)` or `.between(...)` and pass it to `world.surface(name).from(surface)` or `world.water(name).course(surface).depth(...)`; streamed water courses require `.depth(...)`. Do not fake continuous roads by scattering planes/cubes or generating raw mesh buffers when `wavePathSurface` fits.',
   "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.atIndex(index).enlargeBy(1.2))`, and `castToProp(index); prop.enablePhysics()` only when a full prop is needed. Do not use removed `voxelizeHeavy`, `voxelize({ voxelSize })`, `withVoxelSize`, `sharedBox`, or low-level worker/adapter internals in authored scene code.',
+  '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.",
   "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.",
@@ -44524,19 +44474,19 @@ var WAVE_MCP_CODING_GUARDRAIL = [
   `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.`,
-  `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 \`query_wave_api\` before inventing namespace-qualified paths such as \`TransformVerbMode.Animate\` in authored code.`,
-  "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 skill or API lookup. Do not use `assetManager` as the default material, asset-ref, or path-surface authoring root.",
+  `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.',
   "7a. Use `list_wave_explorer_assets` when you need uploaded asset explorer metadata such as path, URL, size, or display/ref name for rename/delete/library work. It is not a fallback for built-in/public code refs and may be empty while `find_wave_assets_by_category` has many usable refs.",
   "8. Wave Studio automations: `project.assetrefs.ts`, `project.scene.ts`, `project.scenes.ts`, and `project.execution.ts` are automatically managed by Wave Studio and are MCP read-only for agents. `bootstrap.ts` / scene `*/bootstrap.ts` is normally managed too. Edit bootstrap only when you can confidently pass `managedFileEditReason` as one of: `world_streaming_or_terrain_provider` (including Google Maps 3D tiles), `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_manifest_or_loader`, `instrument_registry`, `scene_registry`, or `execution_manifest`; Studio owns those. Do not edit managed files to register/preload assets, wire scenes, execution order, or force bootstrap sync; write user-authored scene code in `main.ts` or feature modules with bare refs like `models.Robot` or `textures.Grass`, then let Studio sync bootstrap/asset/scene/execution wiring. Hot reload is the normal way to see code changes. If the hot-reload path discovers new asset/bootstrap/scene-surface needs, Studio automatically upgrades the reload tier internally (`patchMain`, `preserveScene`, or hard `rebuildScene`). Only the hard rebuild tier performs a full bundled scene run.",
   "9. Use `waveStudio.*` only for Studio host services. Check `waveStudio.capabilities.assetSave` before save/bake calls.",
-  '10. Make deterministic file edits through the simplest fitting tool. Default to forgiving `edit_wave_file`: oldText infers exact replace, startLine/endLine infers line replace, `edits:[{startLine,endLine,text}]` or `edits:[{rangeOffset,rangeLength,text}]` performs one-file multi-edit, and path+text/content with no oldText infers whole-file replace. It is the primary simple edit tool and can omit `baseHash`; Studio resolves the latest hosted VFS mirror contentHash and still applies browser-side stale-write checks. Prefer canonical fields: `path` for file path, `text` for line/whole-file content, and `newText` for text replacement; `filePath`, `replacement`, and `content` are accepted as aliases where useful. Use `apply_wave_patch({ operations: [...] })` for multi-file edits, grouped cross-file edits, unified diffs, or full rewrites; a single bare operation is tolerated for mistake recovery but operations:[...] is preferred. Use `create_wave_file`, `rename_wave_file`, and `delete_wave_file` to split projects into `.ts` modules such as `/actors/player.ts`, `/systems/obstacles.ts`, and `/levels/obby.ts` instead of growing one giant `main.ts`; newly created `.ts/.tsx` files are standalone 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. These same VFS tools also create `.html` sketch files for diagrams/charts/docs, with Mermaid rendered from `<div class="mermaid">...</div>` when the HTML file is active in Studio preview. Scene-root modules and their owned helpers run inside the Studio authoring context, but helpers should stay pure or parameterized. Studio hot reload targets the active/open edited file when safe: `/main.ts` reloads the whole main graph, scene-root modules reload that root, and bootstrap/scene registry/assets/network/ambiguous helper surfaces escalate. Standalone `hot_reload_wave_preview` has no target path and follows the currently open/active Studio editor file in multi-file projects. A feature file should own the objects, callbacks, promoted GLB parts, and appearance mutations it wants to iterate on. For intentional live entity reuse across modules, the owner calls `waveStudio.exportEntity("Name", entity)` and importers call `waveStudio.importEntity<T>("Name")`; do not pass live entities through shared helper exports. Use exact VFS paths from `list_wave_files`; read target file before writing. `contentHash` is a cooperative stale-write fingerprint, not a security boundary. For advanced compact `apply_wave_patch` operations, pass the latest full-file `contentHash` as `baseHash`: one `lineEdits`, one `textEdits`, one strict `searchReplace`, or one `unifiedDiff`. Do not send multiple compact ops for the same file with the same baseHash; the first edit changes the file hash and later compact ops skip as stale. Scoped `read_wave_file` line ranges do not change the `textEdits` offset base; they do pair naturally with line-based edits. Existing-file `writeFile` requires `baseHash` unless `forceOverwrite: true`; force overwrite is only for intentional stale overwrites.',
+  '10. Make deterministic file edits through the simplest fitting tool. Default to forgiving `edit_wave_file`: oldText infers exact replace, startLine/endLine infers line replace, `edits:[{startLine,endLine,text}]` or `edits:[{rangeOffset,rangeLength,text}]` performs one-file multi-edit, and path+text/content with no oldText infers whole-file replace. It is the primary simple edit tool and can omit `baseHash`; Studio resolves the latest hosted VFS mirror contentHash and still applies browser-side stale-write checks. Prefer canonical fields: `path` for file path, `text` for line/whole-file content, and `newText` for text replacement; `filePath`, `replacement`, and `content` are accepted as aliases where useful. Use `apply_wave_patch({ operations: [...] })` for multi-file edits, grouped cross-file edits, unified diffs, or full rewrites; a single bare operation is tolerated for mistake recovery but operations:[...] is preferred. Use `create_wave_file`, `rename_wave_file`, and `delete_wave_file` to split projects into `.ts` modules such as `/actors/player.ts`, `/systems/obstacles.ts`, and `/levels/obby.ts` instead of growing one giant `main.ts`; newly created `.ts/.tsx` files are standalone 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. These same VFS tools also create `.html` sketch files for diagrams/charts/docs, with Mermaid rendered from `<div class="mermaid">...</div>` when the HTML file is active in the editor/coding pane; HTML sketches must never replace the live engine preview iframe. Scene-root modules and their owned helpers run inside the Studio authoring context, but helpers should stay pure or parameterized. Studio hot reload targets the active/open edited file when safe: `/main.ts` reloads the whole main graph, scene-root modules reload that root, and bootstrap/scene registry/assets/network/ambiguous helper surfaces escalate. Standalone `hot_reload_wave_preview` has no target path and follows the currently open/active Studio editor file in multi-file projects. A feature file should own the objects, callbacks, promoted GLB parts, and appearance mutations it wants to iterate on. For intentional live entity reuse across modules, the owner calls `waveStudio.exportEntity("Name", entity)` and importers call `waveStudio.importEntity<T>("Name")`; do not pass live entities through shared helper exports. Use exact VFS paths from `list_wave_files`; read target file before writing. `contentHash` is a cooperative stale-write fingerprint, not a security boundary. For advanced compact `apply_wave_patch` operations, pass the latest full-file `contentHash` as `baseHash`: one `lineEdits`, one `textEdits`, one strict `searchReplace`, or one `unifiedDiff`. Do not send multiple compact ops for the same file with the same baseHash; the first edit changes the file hash and later compact ops skip as stale. Scoped `read_wave_file` line ranges do not change the `textEdits` offset base; they do pair naturally with line-based edits. Existing-file `writeFile` requires `baseHash` unless `forceOverwrite: true`; force overwrite is only for intentional stale overwrites.',
   "10a. Always inspect `changedFiles`, `changedPaths`, `partial`, `skippedOperations`, `hotReloadRequested`, `hotReloadSkippedReason`, and `runtimeVerification`; treat skipped operations, no-content-change skips, unscheduled hot reloads, runtime verification errors, and `runtimeVerification.diagnostics.editorErrorCount > 0` as work still needing attention.",
-  "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. Use `requestHotReload: true` for fire-and-poll, or call `hot_reload_wave_preview` as a standalone refresh; pass `awaitRuntimeResult: true` on standalone run/hot reload when you want same-call bounded diagnostics. 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. 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 `awaitHotReload: true` or `awaitRuntimeResult: true`; 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`.',
+  "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. 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.`,
-  "14. Project tools: use `list_wave_project_templates` before `new_wave_project({ templateId? })`; use `list_wave_projects` before `read_wave_project({ projectId })`, `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. 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.",
+  "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.",
   "17. `rename_wave_asset` changes the uploaded asset display/ref name only; it does not move the stored blob path. Re-list assets before writing code with the new ref.",
@@ -44549,11 +44499,11 @@ var WAVE_MCP_CODING_GUARDRAIL_SUMMARY = [
   "Wave Studio MCP compact guardrails:",
   "1. Author WaveStudio user code only; avoid engine internals, private fields, generated implementation details, and low-level sys_/worker/store APIs.",
   "2. Use exact listed MCP tool names only. `studio.*` names are families, not tools. There is no `get_wave_current_project`; use `get_wave_session` for current project/session/active-file context.",
-  "3. Choose MECE work mode before tools: Observe reads directly; Operate direct Studio commands directly; Author/Diagnose route with `start_wave_task`; General avoids Wave tools. Operate examples: run project -> `run_wave_preview`, hot reload/refresh preview -> `hot_reload_wave_preview`, save/persist -> `save_wave_project`, rename saved project -> `rename_wave_project`, exact file create/delete/rename -> VFS operation, marker/FPS/screenshot reads -> Observe tools. Author examples: make/change/fix behavior, choose APIs, add scene objects, or edit existing code -> route, read context, skill/API lookup only as needed, advance, edit, verify. Diagnose-only uses `code.debug`; bug-fix uses `code.debug` plus `code.author`. Direct Operate exact-target rule: never invent paths, asset paths, or project ids; list/read/ask first.",
+  "3. Choose MECE work mode before tools: Observe reads directly; Operate direct Studio commands directly; Author/Diagnose route with `start_wave_task`; General avoids Wave tools. Operate examples: run project -> `run_wave_preview`, hot reload/refresh preview -> `hot_reload_wave_preview`, save/persist -> `save_wave_project`, rename saved project -> `rename_wave_project`, exact file create/delete/rename -> VFS operation, marker/FPS/screenshot reads -> Observe tools. Author examples: make/change/fix behavior, choose APIs, add scene objects, or edit existing code -> route, read context, local SDK skill/API lookup only as needed, advance, edit, verify. Diagnose-only uses `code.debug`; bug-fix uses `code.debug` plus `code.author`. Direct Operate exact-target rule: never invent paths, asset paths, or project ids; list/read/ask first.",
   "3a. If the request is irrelevant or too broad for one concrete Wave milestone, classify `agent.general`, do not force Wave tools, and politely guide the user back to a scoped project/code/asset/debug/runtime/visual task.",
   "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(...enlargeBy(1.2))` for thin-batch voxel interaction. Do not use `voxelizeHeavy`, `voxelize({ voxelSize })`, `withVoxelSize`, or `sharedBox`.",
+  "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.",
   "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.",
@@ -44595,7 +44545,7 @@ var WAVE_MCP_EDIT_RECIPES = [
   "Large rewrite or generated module:",
   '- Existing file: `apply_wave_patch({ operations: [{ type: "writeFile", path, baseHash, content }] })` if you have the latest hash; use `forceOverwrite: true` only for intentional stale overwrite.',
   '- New runnable scene file: `create_wave_file({ path: "/systems/name.ts", content, awaitHotReload: true })`. New `.ts/.tsx` files are standalone runnable source roots by default, so top-level scene code in them runs on Run/hot reload without editing `project.execution.ts`. Pass `runnable:false` only for pure helper modules; then import helper functions normally from a runnable scene file.',
-  '- HTML sketch file: `create_wave_file({ path: "/docs/diagram.html", content })` for diagrams/charts/lightweight docs. For Mermaid, put source in `<div class="mermaid">...</div>`; Studio preview renders active `.html` files and auto-loads Mermaid when `class="mermaid"` is present.',
+  '- HTML sketch file: `create_wave_file({ path: "/docs/diagram.html", content })` for diagrams/charts/lightweight docs. For Mermaid, put source in `<div class="mermaid">...</div>`; the editor/coding pane renders active `.html` files and auto-loads Mermaid when `class="mermaid"` is present. HTML sketches must never replace the live engine preview iframe.',
   "",
   "Preview verification:",
   "- Default after code changes: hot reload. Let Studio choose the internal reload tier. Use `run_wave_preview` only for first start/full restart or as last resort when hot reload does not complete correctly.",
@@ -44626,17 +44576,17 @@ var WAVE_MCP_FILE_CONTEXT_GUIDE = [
   "- 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`.",
-  `- 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 \`query_wave_api\` for the complete generated authoring surface.`,
+  `- 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, Studio preview renders it as an HTML sketch and auto-loads Mermaid if `class="mermaid"` is present.',
+  '- 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.",
-  "- 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 skill or API lookup, not the default place to invent new material or asset 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.",
   '- Wave Studio auto-binds top-level VFS entity variables to runtime refs during run/hot reload. Use `get_wave_runtime_entity_snapshot({ variableName: "amy", filePath?: "/main.ts" })` to query live transform data; if ambiguous, retry with a returned `runtimeRef`.',
   "- Use `create_wave_asset_upload` for generated local asset files when available, upload bytes with plain HTTP PUT to the returned `uploadUrl` using every `uploadHeaders` entry exactly, keep `clientToken`/`Authorization` out of logs, verify `receivedBytes` with `get_wave_asset_upload_status`, then `commit_wave_asset_upload` with the create response metadata and use the returned bare ref like `textures.Albedo`, `cubeMaps.Studio`, `materials.Wood`, `audios.Click`, or `models.Robot` in code. If direct upload is unavailable, use `stage_wave_asset_upload_chunk` plus `commit_wave_asset_chunk_upload`: omit uploadId only on chunkIndex 0, then reuse the returned uploadId for all later chunks and commit. Use `upload_wave_asset` only for small inline base64/data URL assets. Call `abort_wave_asset_upload` only if a staged upload will not be committed. Existing names are idempotent and return `skipped: true`.",
-  "- Use `list_wave_project_templates()` then `new_wave_project({ templateId?, discardUnsavedChanges? })` to start a new unsaved workspace from a template. Use `list_wave_projects()` then `read_wave_project({ projectId })` to inspect bridge-readable project code without opening it, `rename_wave_project({ projectId, name })` to update saved project display metadata, or `open_wave_project({ projectId, discardUnsavedChanges? })` to replace the live workspace. If the user gives a project name, resolve the exact projectId with `list_wave_projects`; do not pass guessed names as ids. New/open replace the live workspace; save first when needed. If dirty, these tools fail with `unsaved_changes` unless discard is explicit.",
+  "- Use `list_wave_project_templates()` then `new_wave_project({ templateId?, discardUnsavedChanges? })` to start a new unsaved workspace from a template. Use `read_wave_project({ url })` to silently inspect shared/published links without opening them; this supports old/new shared links and old/new published links. Use `list_wave_projects()` then `read_wave_project({ projectId })` to inspect listed project code without opening it, `rename_wave_project({ projectId, name })` to update saved project display metadata, or `open_wave_project({ projectId, discardUnsavedChanges? })` to replace the live workspace. If the user gives a project name, resolve the exact projectId with `list_wave_projects`; do not pass guessed names as ids. New/open replace the live workspace; save first when needed. If dirty, these tools fail with `unsaved_changes` unless discard is explicit.",
   "- Use `save_wave_project({ name?, description? })` to persist the live project. Existing saved projects quick-save with current metadata. New projects use provided metadata or generated defaults.",
   "- Use `share_wave_project()` to create a 30-day share link for the current live project through the same Share Project menu pipeline, then return the `url` to the user.",
   "- Use `list_wave_explorer_assets` to inspect the uploaded asset explorer library with paths, URLs, display names, and ref keys. `rename_wave_asset` changes the display/ref name only; it does not move the stored blob path.",
@@ -44651,7 +44601,7 @@ var WAVE_MCP_STUDIO_SKILL_MAP_GUIDE = [
   "Core rule: skills are the map; MCP tools are the buttons. `studio.vfs`, `studio.assets`, and friends are not callable tool names. Choose a `studio.*` family to narrow intent, then call the concrete MCP tool listed under it.",
   "",
   "Namespace split:",
-  "- `wave.*`: WaveEngine code-authoring knowledge: families, skill cards, public authoring objects, one-shot calls, fluent builders, callbacks, globals, and scene APIs. Use `code.direct_edit` for exact power-user code commands, `code.semantic_guess_edit` only for changing an existing visible API call/argument/literal/value, and `list_wave_skill_families` -> selected family ids -> `query_wave_skills({ families/familyId, query })` -> `get_wave_skill` for normal uncertain authoring direction; use local-SDK `query_wave_api` for exact symbols/signatures/globals after direction is known. HTTP Gateway hides/retires cloud API lookup.",
+  "- `wave.*`: WaveEngine code-authoring knowledge: families, skill cards, public authoring objects, one-shot calls, fluent builders, callbacks, globals, and scene APIs. Use `code.direct_edit` for exact power-user code commands, `code.semantic_guess_edit` only for changing an existing visible API call/argument/literal/value, and local-SDK `list_wave_skill_families` -> selected family ids -> `query_wave_skills({ families/familyId, query })` -> `get_wave_skill` for normal uncertain authoring direction; use local-SDK `query_wave_api` for exact symbols/signatures/globals after direction is known. HTTP Gateway hides/retires cloud skill/API lookup.",
   "- `studio.*`: WaveStudio product operations around that code: sessions, VFS, assets, project state, preview, capture, export, and MCP policy.",
   "- Work modes: Observe reads directly, Operate calls concrete Studio commands directly, Author/Diagnose routes through `start_wave_task`, General avoids Wave tools. Direct Operate still requires exact paths/asset paths/project ids for destructive or replacing actions.",
   "",
@@ -44666,8 +44616,8 @@ var WAVE_MCP_STUDIO_SKILL_MAP_GUIDE = [
   "",
   "Common mixed workflow:",
   "1. Use `studio.vfs` tools to read/edit code.",
-  "2. For exact receiver/method/action commands, use `code.direct_edit`. For changing an existing visible call/value only, use `code.semantic_guess_edit`. For unseen, ambiguous, new-code, API-switching, layout/placement/material/animation, or cross-family work, use `code.author` plus `list_wave_skill_families` -> choose families -> `query_wave_skills({ families/familyId, query })` -> `get_wave_skill`. Never raw-query the skill corpus with the full user request.",
-  "3. Use local-SDK `query_wave_api` only after current-code or skill routing when exact method/global/API facts are uncertain. HTTP Gateway is not an API lookup path.",
+  "2. For exact receiver/method/action commands, use `code.direct_edit`. For changing an existing visible call/value only, use `code.semantic_guess_edit`. For unseen, ambiguous, new-code, API-switching, layout/placement/material/animation, or cross-family work, use `code.author` plus local-SDK `list_wave_skill_families` -> choose families -> `query_wave_skills({ families/familyId, query })` -> `get_wave_skill`. Never raw-query the skill corpus with the full user request.",
+  "3. Use local-SDK `query_wave_api` only after current-code or skill routing when exact method/global/API facts are uncertain. HTTP Gateway is not a skill/API lookup path.",
   "4. Use `studio.assets` to resolve exact refs before writing `models.X`, `textures.X`, `materials.X`, `audios.X`, or other asset-map inputs that are not already visible in current code.",
   "5. Use `studio.preview` to hot reload by default.",
   "6. Use `studio.capture` to prove the result with one relevant tool: an `L` screenshot for visual changes, runtime entity snapshot for live transform/state, or `list_wave_runtime_markers` for clickToMark/world marker poses.",
@@ -44679,23 +44629,23 @@ var WAVE_MCP_STUDIO_SKILL_MAP_GUIDE = [
 var WAVE_MCP_STUDIO_TOOL_GUIDE = [
   "Wave Studio runtime and MCP tool guide:",
   "- First choose a `studio.*` family for product operations, then call the concrete MCP tool. See `wave://studio-skill-map` for the concise family-to-tool router.",
-  "- Use MECE work modes before tools: Observe reads directly; Operate direct Studio commands directly; Author/Diagnose route with `start_wave_task`; General avoids Wave tools. Direct Operate includes run/hot reload, save/share, exact VFS create/rename/delete, asset upload/rename/delete, new project, project rename, and open project by exact projectId. Use `wave.*` skill tools for WaveEngine code-authoring decisions: `list_wave_skill_families`, `query_wave_skills`, and `get_wave_skill`. Use local-SDK `query_wave_api` only for exact API/global/signature lookup after current-code or skill routing; HTTP Gateway hides/retires cloud API lookup. For exact power-user edits use `code.direct_edit`; for changing an existing API call/argument/literal/value use `code.semantic_guess_edit`; for new code, API switching, or WaveEngine pattern choice use `code.author`. Fast lanes skip broad lookup, not edit/hot-reload/verification. Use `studio.*` labels for operating WaveStudio around that code; those labels are categories, not callable MCP tool names.",
+  "- Use MECE work modes before tools: Observe reads directly; Operate direct Studio commands directly; Author/Diagnose route with `start_wave_task`; General avoids Wave tools. Direct Operate includes run/hot reload, save/share, exact VFS create/rename/delete, asset upload/rename/delete, new project, project rename, and open project by exact projectId. Use local-SDK `wave.*` lookup tools for WaveEngine code-authoring decisions: `list_wave_skill_families`, `query_wave_skills`, `get_wave_skill`, and `query_wave_api`. HTTP Gateway hides/retires cloud skill/API lookup. For exact power-user edits use `code.direct_edit`; for changing an existing API call/argument/literal/value use `code.semantic_guess_edit`; for new code, API switching, or WaveEngine pattern choice use `code.author`. Fast lanes skip broad lookup, not edit/hot-reload/verification. Use `studio.*` labels for operating WaveStudio around that code; those labels are categories, not callable MCP tool names.",
   "- MCP names: HTTP Gateway = Next/Vercel endpoint for remote/sandbox Studio operations; WaveEngine Agent SDK = same-machine live MCP transport from long-running `wave3d-agent-sdk start`; WaveEngine SDK Cache = package-bundled local skill/API docs retrieval; VFS Mirror = HTTP Gateway workspace snapshot. Do not confuse these modules. On same machine, HTTP Gateway is degraded fallback only after SDK cannot run/update/adopt; do not choose it because it is already reachable or easier.",
   "- MCP recovery: when connection/session/onboarding/cache/mirror/timeout state is unclear, call `recover_wave_connection({ lastErrorCode?, failedTool?, symptom? })` first and follow its returned `nextAction`. This is the explicit recovery path for sleeping tabs, local/HTTP Gateway confusion, mirror-not-ready, onboarding-required, command timeout/lease expiry, and hosted proxy/cache failures.",
-  '- Local parity rule: WaveEngine Agent SDK `tools/list` mirrors the HTTP Gateway catalog plus SDK 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.',
+  '- 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 new SDK may be healthy but unable to authorize the copied local pairing secret. 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 exact 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.`,
+  `- 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.",
-  `- 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 \`wave.*\` skill first; for the full generated exact-global surface, call local-SDK \`query_wave_api\`.`,
+  `- 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 Studio preview as HTML sketches and auto-load Mermaid when `class="mermaid"` is present. 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 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-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 skill or API lookup.",
+  "- 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.`,
-  "- MCP project tools: `list_wave_project_templates()`, `new_wave_project({ templateId?, discardUnsavedChanges? })`, `list_wave_projects()`, `read_wave_project({ projectId })`, `rename_wave_project({ projectId, name })`, `open_wave_project({ projectId, discardUnsavedChanges? })`, `save_wave_project({ name?, description? })`, and `share_wave_project()`. Save/share/rename/new/open are direct Operate tools. Use read for example packs because it does not open or replace the editor workspace. Rename updates saved project display metadata without rewriting VFS/code. New/open replace the current live workspace and require write pairing; dirty workspaces require save first or explicit discard. If the user gives a project name, resolve exact projectId with `list_wave_projects` before renaming or opening. Share returns a 30-day `url`; send that URL back to the user.",
+  `- 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.`,
+  "- MCP project tools: `list_wave_project_templates()`, `new_wave_project({ templateId?, discardUnsavedChanges? })`, `list_wave_projects()`, `read_wave_project({ projectId | url })`, `rename_wave_project({ projectId, name })`, `open_wave_project({ projectId, discardUnsavedChanges? })`, `save_wave_project({ name?, description? })`, and `share_wave_project()`. Save/share/rename/new/open are direct Operate tools. Use read for example packs because it does not open or replace the editor workspace. For listed/saved projects pass exact projectId from `list_wave_projects`; for shared/published links pass `url` directly. Silent URL read supports old `/waveStudio?share=<uuid>` links, new shared alias links, old/new `/p/<user>/<id>` published links, and `/waveStudio?source=published&user=<user>&id=<id>`. Rename updates saved project display metadata without rewriting VFS/code. New/open replace the current live workspace and require write pairing; dirty workspaces require save first or explicit discard. If the user gives a project name, resolve exact projectId with `list_wave_projects` before renaming or opening. Share returns a 30-day `url`; send that URL back to the user. Read `resultSummary` first: project tools report PROJECT ... OK, PROJECT ... FAILED, or PROJECT ... PENDING in the same response.",
   "- MCP diagnostics tool: `get_wave_runtime_diagnostics({ limit? })` reads the same embedded Wave Studio console visible in the coding IDE, structured runtime state, and Monaco/editor diagnostics. Use `runtimeBusy`, `previewExecutionPhase`, `lastRuntimeOutcome`, `editorErrorCount`, and `editorDiagnostics`; logs are history and may include old errors. `editorErrorCount > 0` blocks clean success even when runtime outcome says success.",
   "- MCP performance tool: direct Observe `get_wave_runtime_performance_snapshot()` (alias `get_wave_runtime_performance`) reads live FPS/performance stats, memory/RAM/heap, tick rate, tab visibility, Babylon scene counts, Wave entity/component counts, and JS heap when Chromium exposes it. It does not enable or show the debug overlay.",
   '- MCP runtime entity tool: direct Observe `get_wave_runtime_entity_snapshot({ runtimeRef? , variableName?, filePath?, sceneId? })` (alias `get_wave_entity_snapshot`) answers "where is Amy?" and reads the live world transform for VFS-created source variables. Prefer exact `runtimeRef` when known; otherwise pass `variableName` and add `filePath` if candidates are ambiguous.',
@@ -44712,7 +44662,7 @@ var WAVE_MCP_STUDIO_TOOL_GUIDE = [
   "- `waveStudio.exportEntity(name, entity)`: declare a live entity owned by the current source module for intentional modular reuse. `name` must be a static string literal and unique across runnable roots.",
   "- `waveStudio.importEntity<T>(name)`: import an exported live entity into the current source module; Studio restores the exporter baseline and prunes/replays importer callbacks/overlays during source hot reload. Studio orders source roots by export/import dependencies: exporter before importer; exporter before `main.ts` if main imports it; overlay importers after exporter/main baseline. Missing, duplicate, dynamic, or cyclic entity names stop run/hot reload before execution.",
   '- MCP command result rule: poll `get_wave_command_result({ requestId })` only when the previous tool response includes `status:"pending"` plus `requestId`. HTTP Gateway browser-backed tools may return pending and need that poll. WaveEngine Agent SDK browser-backed tools wait directly and return final results; its `get_wave_command_result` is a catalog-parity no-op unless a pending result was explicitly returned.',
-  "- MCP preview tools: `hot_reload_wave_preview` (alias `hotreload_wave_preview`) is the default standalone way to view code changes in an already-running preview; `run_wave_preview` (alias `run_project`) is for first start when diagnostics show `hasRunSucceeded: false`, explicit full restart requests, or last-resort recovery after hot reload/polling fails; `pause_wave_preview` / `resume_wave_preview` mirror the toolbar pause/resume buttons. All require write pairing because they mutate live Studio runtime state. Patch/runtime-action responses report that work was requested/scheduled, not that execution finished unless the edit tool used `awaitHotReload:true` or standalone run/hot reload used `awaitRuntimeResult:true`. `hot_reload_wave_preview` mirrors the Wave Studio toolbar button and has no path argument: in multi-file VFS projects it reloads the currently open/active TypeScript file when safe, not every user-created .ts module. For a specific module, make that file active in Studio before calling the standalone hot-reload tool, or use the edit tool `awaitHotReload:true` immediately after the final edit. Main entries reload the main graph, source-root modules reload that root, and bootstrap/scene registry/assets/network/ambiguous helper surfaces escalate. Agents should organize feature-owned objects, callbacks, promoted parts, and appearance mutations into the file they expect to hot reload; use `waveStudio.exportEntity`/`waveStudio.importEntity` only when a live entity intentionally crosses module boundaries. Hot reload may internally choose `patchSource`, `patchMain`, `preserveScene`, or hard `rebuildScene`; agents should inspect returned `runtimeVerification` or poll diagnostics instead of manually guessing the tier. Poll `get_wave_runtime_diagnostics` until `runtimeBusy` is false and `lastRuntimeOutcome` is `success` or `error`, require `editorErrorCount === 0`, then choose one relevant proof tool if needed: screenshot, runtime entity snapshot, markers, or performance snapshot."
+  "- MCP preview tools: `hot_reload_wave_preview` (alias `hotreload_wave_preview`) is the default standalone way to view code changes in an already-running preview; `run_wave_preview` (alias `run_project`) is for first start when diagnostics show `hasRunSucceeded: false`, explicit full restart requests, or last-resort recovery after hot reload/polling fails; `pause_wave_preview` / `resume_wave_preview` mirror the toolbar pause/resume buttons. All require write pairing because they mutate live Studio runtime state. Runtime-triggering tools wait by default and return same-call `runtimeVerification`; set `awaitRuntimeResult:false` only when intentionally fire-and-polling. `hot_reload_wave_preview` mirrors the Wave Studio toolbar button and has no path argument: in multi-file VFS projects it reloads the currently open/active TypeScript file when safe, not every user-created .ts module. For a specific module, make that file active in Studio before calling the standalone hot-reload tool, or use the edit tool `awaitHotReload:true` immediately after the final edit. Main entries reload the main graph, source-root modules reload that root, and bootstrap/scene registry/assets/network/ambiguous helper surfaces escalate. Agents should organize feature-owned objects, callbacks, promoted parts, and appearance mutations into the file they expect to hot reload; use `waveStudio.exportEntity`/`waveStudio.importEntity` only when a live entity intentionally crosses module boundaries. Hot reload may internally choose `patchSource`, `patchMain`, `preserveScene`, or hard `rebuildScene`; agents should inspect returned `runtimeVerification` or poll diagnostics instead of manually guessing the tier. Poll `get_wave_runtime_diagnostics` only when `runtimeVerification` is absent, timed out, or ambiguous; require `editorErrorCount === 0`, then choose one relevant proof tool if needed: screenshot, runtime entity snapshot, markers, or performance snapshot."
 ].join("\n");
 
 // ../../src/lib/waveStudio/aiAssist/bridge/hosted/mcpResources/toolCatalog.ts
@@ -44720,7 +44670,7 @@ var WAVE_MCP_TOOL_CATALOG_GUIDE = [
   "Wave Studio MCP tool catalog:",
   "",
   "Read this as skill families first, concrete MCP tools second. The `studio.*` family names are not callable tools; they are the routing map that tells you which concrete `*_wave_*` tool to use.",
-  'WaveEngine Agent SDK `tools/list` mirrors the HTTP Gateway catalog plus SDK session discovery extras. Its live-session tools run through the paired browser and wait directly for browser results. Use `get_wave_command_result` only after a response with `status:"pending"` and `requestId`; locally it normally exists only for catalog parity.',
+  'WaveEngine Agent SDK `tools/list` mirrors the HTTP Gateway Studio-operation catalog, then adds local SDK lookup/session-discovery extras. Its live-session tools run through the paired browser and wait directly for browser results. Use `get_wave_command_result` only after a response with `status:"pending"` and `requestId`; locally it normally exists only for catalog parity.',
   "",
   "studio.mcp - session, policy, pending commands:",
   "- `get_wave_coding_guardrails`: call after onboarding acceptance; returns policy, file context, tool catalog, and recipes.",
@@ -44728,11 +44678,11 @@ var WAVE_MCP_TOOL_CATALOG_GUIDE = [
   "- `get_wave_tool_map`: stable complete concrete MCP tool menu grouped by family plus policy flags. Use only when `tools/list` feels truncated or unclear.",
   `- Transport topology rule: 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 Copy-to-Agent, restart with \`${WAVE3D_AGENT_SDK_TOKEN_PRESERVING_START_COMMAND}\` using the current MCP_TOKEN value without printing it so the copied local pairing secret still works. After restart recheck /health and tools/list. 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; never use it because it is familiar, already authenticated, or avoids SDK repair. Different-machine/cloud/sandbox agents should use \`MCP_HTTP_GATEWAY_FALLBACK_URL\` directly. Stale SDK/cache are local setup issues, not fallback triggers; wrong-machine localhost is a topology mismatch.`,
   "- `recover_wave_connection`: direct Observe recovery tool. Call after onboarding required, session missing, command timeout/lease expired, mirror not ready, hosted proxy/cache failure, local/HTTP Gateway confusion, or sleeping-tab symptoms. It returns exact next action: re-onboard, get session, wake tab, update/restart SDK, wait mirror, retry, use HTTP Gateway fallback, or ask fresh Copy to Agent.",
-  '- WaveEngine SDK Cache: normal API/skill lookup lives inside the local `wave3d-agent-sdk` SDK package. Update/restart SDK when SDK is stale or missing. HTTP Gateway is Studio-ops-only and does not provide cloud API lookup. If local SDK 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 exact API lookup requires local SDK repair. This is retrieval cache, not WaveEngine Agent SDK transport. Never treat SDK cache failure as local transport failure. Keep Priority 1 role, guardrails, workflow, assets/VFS/hot-reload rules, prompt version, and prompt hash in active LLM context.',
+  '- WaveEngine SDK Cache: normal skill/API lookup lives inside the local `wave3d-agent-sdk` SDK package. Update/restart SDK when SDK is stale or missing. HTTP Gateway is Studio-ops-only and does not provide cloud skill/API lookup. If local SDK 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 skill/API lookup requires local SDK repair. This is retrieval cache, not WaveEngine Agent SDK transport. Never treat SDK cache failure as local transport failure. Keep Priority 1 role, guardrails, workflow, assets/VFS/hot-reload rules, prompt version, and prompt hash in active LLM context.',
   "- Work-mode rule: Observe reads directly; Operate direct Studio commands directly; Author/Diagnose routes through `start_wave_task`; General avoids Wave tools. Operate tools include run/hot reload, save/share, VFS create/rename/delete exact files, asset upload/rename/delete exact assets, new project, project rename, and open project by exact projectId.",
-  "- `start_wave_task`: begin one Author/Diagnose route for code behavior/content changes, debugging, exact API lookup, semantic/direct code edits, and multi-step investigations. Use `code.direct_edit` for exact power-user receiver/method/action commands; use `code.semantic_guess_edit` only when changing an existing API call/argument/literal/value already visible in code; use `code.author` for normal/uncertain authoring and any new code/API/pattern choice. If the user request is irrelevant/too broad, use `agent.general` and guide the user toward one concrete Wave milestone.",
+  "- `start_wave_task`: begin one Author/Diagnose route for code behavior/content changes, debugging, local SDK skill/API lookup, semantic/direct code edits, and multi-step investigations. Use `code.direct_edit` for exact power-user receiver/method/action commands; use `code.semantic_guess_edit` only when changing an existing API call/argument/literal/value already visible in code; use `code.author` for normal/uncertain authoring and any new code/API/pattern choice. If the user request is irrelevant/too broad, use `agent.general` and guide the user toward one concrete Wave milestone.",
   "- Diagnose taxonomy: `code.debug` alone means diagnose/report only. For bug-fix requests, include both `code.debug` and `code.author`; otherwise the route may correctly stay read-only/debug-only.",
-  '- `advance_wave_task`: move an Author/Diagnose route to lookup, execute, or verify after evidence is gathered. Required before `query_wave_api`, broad `edit_wave_file`, `apply_wave_patch`, and final route verification unless `start_wave_task` already fast-started with `nextPhase:"execute"` and editPlan. Not required for exact `edit_wave_file` line/text edits that already provide path plus startLine/endLine/text, edits:[...], or oldText/newText. Do not advance merely to run a direct Operate tool.',
+  '- `advance_wave_task`: move an Author/Diagnose route to lookup, execute, or verify after evidence is gathered. Required before local-SDK `query_wave_api`, broad `edit_wave_file`, `apply_wave_patch`, and final route verification unless `start_wave_task` already fast-started with `nextPhase:"execute"` and editPlan. Not required for exact `edit_wave_file` line/text edits that already provide path plus startLine/endLine/text, edits:[...], or oldText/newText. Do not advance merely to run a direct Operate tool.',
   "- `get_wave_task_route`: inspect current route, phase, and evidence when you are unsure why a tool is blocked.",
   "- `get_wave_session`: current paired Studio tab, active file, token/session status, visible agent clients.",
   '- `get_wave_command_result`: use only after a tool response contains `status:"pending"` and `requestId`. On HTTP Gateway, this polls pending browser-backed command results until final. On WaveEngine Agent SDK, this is normally catalog parity because local browser-backed calls wait directly.',
@@ -44745,17 +44695,18 @@ var WAVE_MCP_TOOL_CATALOG_GUIDE = [
   "- `apply_wave_patch`: advanced tool for grouped edits, multi-file changes, `lineEdits`, `textEdits`, `searchReplace`, `unifiedDiff`, full rewrites, create/rename/delete in one command. Prefer an `operations` array; a single `operation` or bare operation object is tolerated for recovery. Compact edit operations should include explicit `baseHash`.",
   "- Bootstrap exception: `bootstrap.ts` is not a normal authoring file. `edit_wave_file`/`apply_wave_patch` require `managedFileEditReason` for bootstrap writes. Allowed reasons are world streaming/terrain provider (including Google Maps 3D tiles), render/runtime backend, media consent/capture, external AI/TTS backend, scene/template baseline, pre-main baseline setup, or stale bootstrap API update to latest. Asset manifests/loaders, instruments, scene registry, and execution manifest are blocked because Studio manages those automatically.",
   "- Hot-reload safety preflight: edit_wave_file/create_wave_file/apply_wave_patch reject raw unmanaged callback roots before writing, including timers, RAF, listeners, Promise chains, observers, workers, sockets, channels, eventBus/myScene raw subscriptions, and raw event-handler assignments. Use Wave-owned callbacks/Animate/tick/state/Director APIs.",
-  '- `create_wave_file`, `rename_wave_file`, `delete_wave_file`: direct Operate VFS file management for exact `.ts` module paths and `.html` sketch files. Prefer these for project structure changes, diagrams, Mermaid charts, and lightweight docs. For Mermaid, create `.html` with `<div class="mermaid">...</div>`; active HTML files preview in Studio and auto-load Mermaid when `class="mermaid"` is present. 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. If target is vague, call `list_wave_files` or ask before mutating.',
+  '- `create_wave_file`, `rename_wave_file`, `delete_wave_file`: direct Operate VFS file management for exact `.ts` module paths and `.html` sketch files. Prefer these for project structure changes, diagrams, Mermaid charts, and lightweight docs. For Mermaid, create `.html` with `<div class="mermaid">...</div>`; active HTML files preview in the editor/coding pane and auto-load Mermaid when `class="mermaid"` is present. HTML sketches must never replace the live engine preview iframe. 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. If target is vague, call `list_wave_files` or ask before mutating.',
   "",
-  "wave.* support - code-authoring facts:",
-  "- `list_wave_skill_families`: complete family router for WaveEngine authoring direction after intent chunking/Core Intent Pass. Call this before skill/API lookup when current code does not already show the pattern.",
-  "- `query_wave_skills`: search compact generated skill cards only after family selection. Do not pass raw user prose. Call with `families`/`familyId` from `list_wave_skill_families` plus a small within-family query, or exact `skillIds`.",
-  "- `get_wave_skill`: read one compact skill card with routing hints, preferred APIs, supporting skills, examples, and anti-patterns.",
-  "- `query_wave_api`: gated exact lookup, not assessment. Search public authoring APIs for exact methods, options, enums, bare runtime globals, aliases, members, and return chains after current-code or skill routing. Fast-lane routes call this only when spelling/signature/value uncertainty remains or an edit failed.",
+  "local-SDK wave.* lookup - code-authoring facts:",
+  "- HTTP Gateway tools/list hides/retires `list_wave_skill_families`, `query_wave_skills`, `get_wave_skill`, and `query_wave_api`. Use these only on the local WaveEngine Agent SDK endpoint.",
+  "- `list_wave_skill_families`: local SDK complete family router for WaveEngine authoring direction after intent chunking/Core Intent Pass. Call this before skill/API lookup when current code does not already show the pattern.",
+  "- `query_wave_skills`: local SDK compact generated skill-card search only after family selection. Do not pass raw user prose. Call with `families`/`familyId` from `list_wave_skill_families` plus a small within-family query, or exact `skillIds`.",
+  "- `get_wave_skill`: local SDK compact skill-card read with routing hints, preferred APIs, supporting skills, examples, and anti-patterns.",
+  "- `query_wave_api`: local SDK gated exact lookup, not assessment. Search public authoring APIs for exact methods, options, enums, bare runtime globals, aliases, members, and return chains after current-code or skill routing. Fast-lane routes call this only when spelling/signature/value uncertainty remains or an edit failed.",
   "",
   "studio.preview - run loop and diagnostics:",
-  "- `hot_reload_wave_preview` (alias `hotreload_wave_preview`): direct Operate tool for hot reload, reload preview, or refresh preview after edit. It is also the default way to view code changes in an already-running preview. It mirrors the Wave Studio toolbar button and has no path argument: in multi-file VFS projects it reloads the currently open/active TypeScript file when safe, not every user-created .ts module. Studio may upgrade the internal reload tier automatically when assets/bootstrap/runtime surface changed. Pass `awaitRuntimeResult:true` for one-call request + bounded diagnostics.",
-  "- `run_wave_preview` (alias `run_project`): direct Operate tool for run project, start preview, or full restart. Use when diagnostics show `hasRunSucceeded: false`, the user asks for a full run/restart, or hot reload is stuck/failing and you need a last-resort restart. Pass `awaitRuntimeResult:true` for one-call request + bounded diagnostics.",
+  "- `hot_reload_wave_preview` (alias `hotreload_wave_preview`): direct Operate tool for hot reload, reload preview, or refresh preview after edit. It is also the default way to view code changes in an already-running preview. It mirrors the Wave Studio toolbar button and has no path argument: in multi-file VFS projects it reloads the currently open/active TypeScript file when safe, not every user-created .ts module. Studio may upgrade the internal reload tier automatically when assets/bootstrap/runtime surface changed. It waits by default and returns one-call bounded diagnostics in `runtimeVerification`; set `awaitRuntimeResult:false` only for intentional fire-and-poll.",
+  "- `run_wave_preview` (alias `run_project`): direct Operate tool for run project, start preview, or full restart. Use when diagnostics show `hasRunSucceeded: false`, the user asks for a full run/restart, or hot reload is stuck/failing and you need a last-resort restart. It waits by default and returns one-call bounded diagnostics in `runtimeVerification`; set `awaitRuntimeResult:false` only for intentional fire-and-poll.",
   "- `pause_wave_preview` / `resume_wave_preview` (aliases `pause_wave_engine`, `resume_wave_engine`): direct Operate tools for the Wave Studio toolbar pause/resume engine controls. No task route needed; preview must already be running.",
   "- `get_wave_runtime_diagnostics`: poll until `runtimeBusy` is false and `lastRuntimeOutcome` is `success` or `error`. If your edit/run tool returned `requestedAt` or `runtimeActionRequestedAt`, ignore older `lastRuntimeOutcomeAt`. Logs are history; use structured outcome first. Also inspect `editorErrorCount`/`editorDiagnostics`; editor errors mean linter/compile failure even if runtime outcome says success.",
   "- `get_wave_runtime_performance_snapshot` (alias `get_wave_runtime_performance`): direct Observe tool for live FPS/performance stats, memory/RAM/heap, hidden-tab throttling, scene weight, mesh/material/texture counts, Wave entity/component counts, and JS heap. No `start_wave_task` needed.",
@@ -44769,7 +44720,7 @@ var WAVE_MCP_TOOL_CATALOG_GUIDE = [
   "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 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 Wave skill or API lookup.",
+  "- 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.",
   "- `create_wave_asset_upload` -> raw HTTP PUT -> `get_wave_asset_upload_status` -> `commit_wave_asset_upload`: best path for local files; no local npm package required.",
@@ -44780,7 +44731,8 @@ var WAVE_MCP_TOOL_CATALOG_GUIDE = [
   "",
   "studio.project - workspace lifecycle:",
   "- `list_wave_project_templates` -> `new_wave_project`: start a new workspace. Save first or pass explicit discard.",
-  "- `list_wave_projects` -> `read_wave_project`: read a bridge-readable project VFS/code payload without opening it. Use for example packs, style learning, and pattern comparison.",
+  "- `read_wave_project({ url })`: silently read shared/published project links without opening them. Supports old `/waveStudio?share=<uuid>` and new shared alias links, old/new `/p/<user>/<id>` published links, and `/waveStudio?source=published&user=<user>&id=<id>`.",
+  "- `list_wave_projects` -> `read_wave_project({ projectId })`: read a listed/saved bridge-readable project VFS/code payload without opening it. Use for example packs, style learning, and pattern comparison.",
   "- `list_wave_projects` -> `rename_wave_project`: rename a saved project by exact projectId without opening it or rewriting VFS/code.",
   "- `list_wave_projects` -> `open_wave_project`: open a bridge-readable project by exact projectId and replace the live workspace. If user gives a name, resolve it through `list_wave_projects`; never pass a guessed name as projectId. Save first or pass explicit discard.",
   "- `save_wave_project`: quick-save existing saved projects; for new projects, pass name/description or let Studio generate defaults.",
@@ -44791,7 +44743,7 @@ var WAVE_MCP_TOOL_CATALOG_GUIDE = [
   "",
   "Cross-family rules:",
   "- Hosted browser-backed tools can return pending with `requestId`; poll `studio.mcp` tool `get_wave_command_result` only in that case. WaveEngine Agent SDK waits directly and normally does not use a pending-command queue.",
-  "- Fast-lane code routes: exact user command naming a receiver/method/action -> `code.direct_edit`; changing an existing visible API call/argument/literal/value only -> `code.semantic_guess_edit`. New lines, new objects, API switching, or WaveEngine pattern choice -> `code.author`. Fast lanes skip broad skill/API lookup, not deterministic edit tools, hot reload, or verification. They usually skip `query_wave_api` too; use exact lookup only for uncertainty/failure. For unfamiliar work, retrieve `wave.*` skills before exact API facts.",
+  "- Fast-lane code routes: exact user command naming a receiver/method/action -> `code.direct_edit`; changing an existing visible API call/argument/literal/value only -> `code.semantic_guess_edit`. New lines, new objects, API switching, or WaveEngine pattern choice -> `code.author`. Fast lanes skip broad skill/API lookup, not deterministic edit tools, hot reload, or verification. They usually skip local-SDK `query_wave_api` too; use exact lookup only for uncertainty/failure. For unfamiliar work, retrieve local SDK `wave.*` skills before exact API facts.",
   "- After `studio.vfs` edits, inspect `changedFiles`, `changedPaths`, `partial`, `skippedOperations`, `hotReloadRequested`, and `hotReloadSkippedReason`.",
   "- After code changes, use `studio.preview` hot reload by default, then `studio.capture` to prove the result.",
   "- Proactive help rule: after meaningful progress, suggest at most one relevant Studio capability if it helps: screenshot, entity snapshot, markers, performance snapshot, asset tools, or project share/save/open. Do not dump tool menus."
@@ -44867,7 +44819,7 @@ var LOCAL_MCP_AGENT_READY_SUMMARY = {
     "Primary code edit tool is edit_wave_file. Use apply_wave_patch only for grouped/multi-file/strict diff work.",
     'VFS supports non-code files too: create `.html` sketches for diagrams/charts/docs; active HTML files preview in Studio, and Mermaid renders from `<div class="mermaid">...</div>` blocks.',
     "Hot-reload safety: avoid raw unmanaged callback roots such as timers/RAF/listeners/Promise chains/observers/workers/sockets/channels/event-handler assignments. Edit tools and runtime bundling block violations before authored code runs; use Wave-owned callbacks/Animate/tick/state/Director APIs.",
-    "After final code edit, prefer awaitHotReload:true for one-call edit + hot reload + bounded diagnostics; inspect changedFiles/changedPaths/partial/skippedOperations/hotReloadRequested/hotReloadSkippedReason/runtimeVerification.",
+    "After final code edit, prefer awaitHotReload:true for one-call edit + hot reload + bounded diagnostics; requestHotReload:true also waits unless awaitHotReload:false; inspect changedFiles/changedPaths/partial/skippedOperations/hotReloadRequested/hotReloadSkippedReason/runtimeVerification.",
     "Studio-managed generated files are read-only; bootstrap.ts needs a confident managedFileEditReason and is never for assets/loaders/instruments/scene registry/execution manifest.",
     "Production/HTTP-Gateway pairing path must have WaveEngine SDK Cache prepared before onboarding accept succeeds; SDK comes bundled in the npm SDK package."
   ],
@@ -44913,14 +44865,14 @@ var LOCAL_MCP_AGENT_ONBOARDING_PROMPT = [
   "6. For code edits, use `edit_wave_file` as the primary forgiving one-file edit tool. It accepts one exact text edit, one line range, whole-file replacement, or one-file `edits:[...]` arrays. Use `apply_wave_patch` only for grouped/multi-file/strict diff work.",
   "7. 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` is normally Studio-managed too; edit it only with a confident `managedFileEditReason`: `world_streaming_or_terrain_provider` (including Google Maps 3D tiles), `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 assets/loaders, instruments, scene registry, or execution manifest; Studio owns those.",
   '7a. VFS non-code note: `.html` files are supported HTML sketches. For Mermaid diagrams/charts, create or edit an exact `.html` file containing `<div class="mermaid">...</div>`. Active HTML files preview in Studio and auto-load Mermaid when `class="mermaid"` is present.',
-  "8. After the final code edit, prefer `awaitHotReload:true` when the preview already ran so the edit response includes hot reload plus bounded diagnostics. Use `requestHotReload:true` only for intentional fire-and-poll. Use standalone `hot_reload_wave_preview` only for explicit preview refresh with no edit.",
+  "8. After the final code edit, prefer `awaitHotReload:true` when the preview already ran so the edit response includes hot reload plus bounded diagnostics. `requestHotReload:true` also waits for diagnostics by default unless paired with `awaitHotReload:false`. Standalone `run_wave_preview` / `hot_reload_wave_preview` wait by default and return `runtimeVerification`; set `awaitRuntimeResult:false` only for intentional fire-and-poll.",
   "9. Always inspect mutation results: changedFiles, changedPaths, partial, skippedOperations, hotReloadRequested, and hotReloadSkippedReason.",
   "10. Marker waypoint workflow: when the human asks to use preview marking tools such as `clickToMark()`, route with `marker.use` plus code/project intent, then call `list_wave_runtime_markers` and write marker worldPosition/worldRotation into waypoint/path/placement code. One marker read may happen before routing only when needed to decide intent.",
   "11. After meaningful progress, suggest at most one relevant Studio capability when helpful: screenshot, runtime entity snapshot, runtime markers, performance snapshot, asset tools, or project save/share/open. Do not dump a menu.",
   "",
   "WaveEngine Agent SDK scope:",
-  'This endpoint mirrors the HTTP Gateway tool catalog plus local SDK session-discovery extras. Live-session Studio tools for VFS, preview, capture, runtime probes, assets, uploads, project save/share/open/new/read, and file operations run through the connected browser. Local browser-backed calls wait for the browser result directly. Only call `get_wave_command_result` when a tool result actually contains `status:"pending"` plus `requestId`; otherwise local `get_wave_command_result` exists only for catalog parity and reports that no local pending-command queue is used. Skill/API/guardrail tools read the bundled WaveEngine SDK Cache prepared by the SDK package. Do not treat SDK cache miss as local transport failure.',
-  `Recovery rule: \`recover_wave_connection\` is the first tool after \`agent_onboarding_required\`, \`session_not_found\`, \`command_timeout\`, \`command_lease_expired\`, \`hosted_mcp_proxy_failed\`, unclear local/HTTP Gateway fallback, or sleeping-tab symptoms. If local HTTP refuses, start/restart WaveEngine Agent SDK and retry 10 seconds. If local HTTP returns 401 but HTTP Gateway accepts the same MCP_TOKEN, SDK is stale/not adopted: restart with \`${WAVE3D_AGENT_SDK_TOKEN_PRESERVING_START_COMMAND}\` using the current MCP_TOKEN value hidden, then retry local. If every endpoint rejects MCP_TOKEN before a tool result, ask user for fresh Copy to Agent.`
+  'This endpoint publishes canonical Wave MCP tools only when this Agent SDK build has a real local handler, plus local SDK session-discovery extras. Live-session Studio tools for VFS, preview, capture, runtime probes, assets, uploads, project save/share/open/new/read, and file operations run through the connected browser. Local browser-backed calls wait for the browser result directly. Only call `get_wave_command_result` when a tool result actually contains `status:"pending"` plus `requestId`; otherwise local `get_wave_command_result` exists only for catalog parity and reports that no local pending-command queue is used. Skill/API/guardrail tools read the bundled WaveEngine SDK Cache prepared by the SDK package. Do not treat SDK cache miss as local transport failure.',
+  `Recovery rule: \`recover_wave_connection\` is the first tool after \`agent_onboarding_required\`, \`session_not_found\`, \`command_timeout\`, \`command_lease_expired\`, \`local_sdk_tool_not_implemented\`, \`wave_engine_sdk_cache_required\`, unclear local/HTTP Gateway fallback, or sleeping-tab symptoms. If local HTTP refuses, start/restart WaveEngine Agent SDK and retry 10 seconds. If local HTTP returns 401 but HTTP Gateway accepts the same MCP_TOKEN, SDK is stale/not adopted: restart with \`${WAVE3D_AGENT_SDK_TOKEN_PRESERVING_START_COMMAND}\` using the current MCP_TOKEN value hidden, then retry local. If every endpoint rejects MCP_TOKEN before a tool result, ask user for fresh Copy to Agent.`
 ].join("\n");
 
 // ../../scripts/wavegenie-sdk/mcp/referenceTools.ts
@@ -44966,6 +44918,100 @@ function summarizePaths(paths) {
 function readNumber(value) {
   return typeof value === "number" && Number.isFinite(value) ? value : null;
 }
+function readString(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+function readBoolean2(value) {
+  return typeof value === "boolean" ? value : null;
+}
+function summarizeCount(count, singular, plural = `${singular}s`) {
+  return `${count} ${count === 1 ? singular : plural}`;
+}
+function summarizeActionLabel(value) {
+  return value.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/[_-]+/g, " ").trim().toUpperCase();
+}
+function summarizeToolFailure(value) {
+  const error = readRecord(value.error);
+  const message = readString(value.message) ?? readString(error?.message) ?? readString(value.error);
+  return message ? `OPERATION FAILED: ${message}` : "OPERATION FAILED";
+}
+function summarizePendingToolResult(value) {
+  const status = readString(value.status);
+  if (!status) return null;
+  const requestId = readString(value.requestId) ?? readString(value.commandId);
+  const action = readString(value.action);
+  const label = action ? summarizeActionLabel(action) : "OPERATION";
+  if (status === "pending") {
+    return `${label} PENDING${requestId ? `: requestId ${requestId}` : ""}; NEXT: poll get_wave_command_result`;
+  }
+  return `${label} ${status.toUpperCase()}${requestId ? `: requestId ${requestId}` : ""}`;
+}
+function summarizeProjectOrAssetOperation(value) {
+  const ok = readBoolean2(value.ok);
+  if (ok === false) return summarizeToolFailure(value);
+  const pending = summarizePendingToolResult(value);
+  if (pending) return pending;
+  if (ok !== true) return null;
+  const templates = Array.isArray(value.templates) ? value.templates : null;
+  if (templates) return `PROJECT TEMPLATES OK: ${summarizeCount(templates.length, "template")}`;
+  const projects = Array.isArray(value.projects) ? value.projects : null;
+  if (projects) {
+    const total = readNumber(value.total) ?? projects.length;
+    return `PROJECT LIST OK: ${summarizeCount(total, "project")}`;
+  }
+  const assets = Array.isArray(value.assets) ? value.assets : null;
+  if (assets) return `ASSET LIST OK: ${summarizeCount(assets.length, "asset")}`;
+  const uploadId = readString(value.uploadId);
+  if (uploadId) {
+    const chunkIndex = readNumber(value.chunkIndex);
+    const totalChunks = readNumber(value.totalChunks);
+    if (chunkIndex !== null && totalChunks !== null) {
+      return `ASSET UPLOAD CHUNK OK: chunk ${chunkIndex + 1}/${totalChunks}; uploadId ${uploadId}`;
+    }
+    const receivedBytes = readNumber(value.receivedBytes);
+    if (receivedBytes !== null) {
+      return `ASSET UPLOAD STATUS OK: ${summarizeCount(receivedBytes, "byte")} received; uploadId ${uploadId}`;
+    }
+    if (readNumber(value.deletedCount) !== null) {
+      return `ASSET UPLOAD ABORT OK: staging cleaned for uploadId ${uploadId}`;
+    }
+    if (readString(value.uploadUrl)) {
+      return `ASSET UPLOAD URL OK: uploadId ${uploadId}; NEXT: upload bytes, check status, then commit_wave_asset_upload`;
+    }
+    return `ASSET UPLOAD STEP OK: uploadId ${uploadId}`;
+  }
+  const action = readString(value.action);
+  if (action === "shareProject" || readString(value.shareUrl) || readString(value.url)) {
+    const url = readString(value.shareUrl) ?? readString(value.url);
+    return url ? `PROJECT SHARE OK: ${url}` : "PROJECT SHARE OK";
+  }
+  if (action) {
+    const label = summarizeActionLabel(action);
+    const project2 = readRecord(value.project);
+    const asset2 = readRecord(value.asset);
+    const projectName = readString(project2?.name) ?? readString(value.name);
+    const assetPath = readString(value.path);
+    if (action.toLowerCase().includes("project") || project2) {
+      return `${label} OK${projectName ? `: ${projectName}` : ""}`;
+    }
+    if (action === "rename" || action === "delete" || action === "uploadAsset" || asset2 || assetPath) {
+      if (value.skipped === true) {
+        const message = readString(value.message);
+        return `ASSET ${label} SKIPPED${message ? `: ${message}` : ""}`;
+      }
+      return `ASSET ${label} OK${assetPath ? `: ${assetPath}` : ""}`;
+    }
+    return `${label} OK`;
+  }
+  const project = readRecord(value.project);
+  if (project) {
+    const projectName = readString(project.name);
+    return `PROJECT OK${projectName ? `: ${projectName}` : ""}`;
+  }
+  const asset = readRecord(value.asset);
+  if (asset || readString(value.assetKind)) return "ASSET OK";
+  return null;
+}
 function readRuntimeVerificationEditorErrorCount(value) {
   const verification = readRecord(value.runtimeVerification);
   const directCount = readNumber(verification?.editorErrorCount);
@@ -45010,12 +45056,46 @@ function summarizeHotReloadVerification(value) {
   if (verificationOutcome === "error") return "; HOT RELOAD ERROR: read runtimeVerification.diagnostics";
   return null;
 }
+function summarizeRuntimeActionVerification(value, action) {
+  const verification = readRecord(value.runtimeVerification);
+  if (!verification) return null;
+  const editorErrorCount = readRuntimeVerificationEditorErrorCount(value);
+  if (editorErrorCount > 0) {
+    return `${action} BLOCKED: ${editorErrorCount} editor/linter error${editorErrorCount === 1 ? "" : "s"}; NEXT: read runtimeVerification.diagnostics.editorDiagnostics before reporting success`;
+  }
+  if (verification.timedOut === true) {
+    return `${action} PENDING: diagnostics timed out; poll get_wave_runtime_diagnostics`;
+  }
+  const verificationOutcome = verification.verificationOutcome;
+  if (verificationOutcome === "success") return `${action} OK`;
+  if (verificationOutcome === "error") return `${action} ERROR: read runtimeVerification.diagnostics`;
+  return null;
+}
 function buildWaveMcpToolResultNextAction(value) {
   const changedPaths = readStringArray2(value.changedPaths);
   const changedFiles = readPathArray(value.changedFiles);
   const editedPaths = changedPaths.length > 0 ? changedPaths : changedFiles;
   const skippedReasons = readSkippedReasons(value.skippedOperations);
   const directEditorErrorCount = readDirectEditorErrorCount(value);
+  if (value.ok === false) {
+    return "Operation failed. Read the returned error/message, fix the input or session state, then retry.";
+  }
+  if (readString(value.status) === "pending") {
+    return "Browser command is still pending. Poll get_wave_command_result with the returned requestId before reporting completion.";
+  }
+  if (value.action === "hotReload" || value.action === "run") {
+    const editorErrorCount = readRuntimeVerificationEditorErrorCount(value);
+    if (editorErrorCount > 0) {
+      return "Editor/linter errors block this preview action. Read runtimeVerification.diagnostics.editorDiagnostics, fix those errors, then re-run hot reload or preview.";
+    }
+    const verification = readRecord(value.runtimeVerification);
+    if (verification?.timedOut === true) {
+      return "Runtime verification timed out. Poll get_wave_runtime_diagnostics until runtimeBusy is false and lastRuntimeOutcome is success or error.";
+    }
+    if (verification?.verificationOutcome === "error") {
+      return "Runtime action failed. Read runtimeVerification.diagnostics.latestError and editorDiagnostics before retrying.";
+    }
+  }
   if (directEditorErrorCount !== null && directEditorErrorCount > 0) {
     return "Editor/linter errors block this code. Read editorDiagnostics, fix those errors, then re-run hot reload or preview.";
   }
@@ -45040,6 +45120,8 @@ function buildWaveMcpToolResultNextAction(value) {
 }
 function waveMcpToolResultNeedsAttention(value, nextAction) {
   if (nextAction) return true;
+  if (value.ok === false) return true;
+  if (readString(value.status) === "pending") return true;
   const verificationOk = readRuntimeVerificationOk(value);
   if (verificationOk === false) return true;
   const directEditorErrorCount = readDirectEditorErrorCount(value);
@@ -45071,8 +45153,10 @@ function buildWaveMcpToolResultSummary(value) {
   if (value.action === "hotReload" || value.action === "run") {
     const action = value.action === "run" ? "RUN" : "HOT RELOAD";
     if (value.requested === false || value.ok === false) return `${action} NOT REQUESTED`;
-    return `${action} REQUESTED: not proof of runtime success; poll get_wave_runtime_diagnostics until runtimeBusy is false and lastRuntimeOutcome is success or error`;
+    return summarizeRuntimeActionVerification(value, action) ?? `${action} REQUESTED: not proof of runtime success; poll get_wave_runtime_diagnostics until runtimeBusy is false and lastRuntimeOutcome is success or error`;
   }
+  const operationSummary = summarizeProjectOrAssetOperation(value);
+  if (operationSummary) return operationSummary;
   if (changedFiles.length > 0) {
     return `EDIT APPLIED: ${summarizePaths(changedFiles)} changed`;
   }
@@ -45165,11 +45249,6 @@ function errorToolResult(code, message, details) {
     isError: true
   };
 }
-function readToolResultErrorCode(result) {
-  const error = result.structuredContent?.error;
-  if (!isRecord2(error)) return null;
-  return typeof error.code === "string" ? error.code : null;
-}
 
 // ../../scripts/wavegenie-sdk/mcp/referenceTools.ts
 function getLocalCorpusCacheRoot() {
@@ -45772,7 +45851,7 @@ async function prepareLocalCorpusForOnboarding(context) {
     commandTemplate: WAVE_MCP_CORPUS_CACHE_COMMAND_TEMPLATE
   };
 }
-async function localReferenceTool(input) {
+async function localSdkLookupTool(input) {
   if (input.name === "list_wave_skill_families") return await localListWaveSkillFamilies(input.args, input.context);
   if (input.name === "query_wave_skills") return await localQueryWaveSkills(input.args, input.context);
   if (input.name === "get_wave_skill") return await localGetWaveSkill(input.args, input.context);
@@ -45780,19 +45859,16 @@ async function localReferenceTool(input) {
   if (input.name === "get_wave_coding_guardrails") return await localGetWaveCodingGuardrails();
   return null;
 }
-async function proxyHostedReferenceTool(input) {
-  const localResult = await localReferenceTool({
+async function runLocalSdkLookupTool(input) {
+  const localResult = await localSdkLookupTool({
     name: input.name,
     args: input.args,
     context: input.context
   });
-  const localErrorCode = localResult ? readToolResultErrorCode(localResult) : null;
-  if (localResult && localErrorCode !== "wave_engine_sdk_cache_required") {
-    return localResult;
-  }
-  return localResult ?? errorToolResult(
-    "wave_engine_sdk_cache_required",
-    `${input.name} needs the bundled WaveEngine SDK Cache from the local wave3d-agent-sdk package. Update/restart SDK or run the bundled SDK repair command. HTTP Gateway is not an API/skill lookup fallback.`
+  if (localResult) return localResult;
+  return errorToolResult(
+    "local_sdk_lookup_handler_missing",
+    `${input.name} is listed as a local SDK lookup tool but has no local handler. Update wave3d-agent-sdk; HTTP Gateway is not an API/skill lookup fallback.`
   );
 }
 
@@ -46517,7 +46593,10 @@ function normalizeEditWaveFileMode(value) {
   return void 0;
 }
 function shouldAwaitHotReloadDiagnostics(args) {
-  return args?.awaitHotReload === true || args?.awaitRuntimeDiagnostics === true || args?.returnRuntimeDiagnostics === true;
+  if (args?.awaitHotReload === false || args?.awaitRuntimeDiagnostics === false || args?.returnRuntimeDiagnostics === false || args?.awaitDiagnostics === false) {
+    return false;
+  }
+  return args?.awaitHotReload === true || args?.awaitRuntimeDiagnostics === true || args?.returnRuntimeDiagnostics === true || args?.awaitDiagnostics === true || args?.requestHotReload === true;
 }
 function runtimeVerificationArgs(args) {
   const awaitHotReload = shouldAwaitHotReloadDiagnostics(args);
@@ -47481,7 +47560,7 @@ var HOT_RELOAD_RUNTIME_DIAGNOSTIC_SCHEMA_PROPERTIES = {
   awaitHotReload: {
     type: "boolean",
     default: false,
-    description: "Set true on the final edit to combine edit + hot reload + bounded runtime diagnostics in one MCP call. Implies requestHotReload. Response includes runtimeVerification with latest diagnostics or timedOut:true."
+    description: "Set true on the final edit to combine edit + hot reload + bounded runtime diagnostics in one MCP call. Implies requestHotReload. requestHotReload:true uses this wait behavior by default; set awaitHotReload:false only for intentional fire-and-poll."
   },
   awaitRuntimeDiagnostics: {
     type: "boolean",
@@ -47496,7 +47575,7 @@ var HOT_RELOAD_RUNTIME_DIAGNOSTIC_SCHEMA_PROPERTIES = {
     minimum: 500,
     maximum: 15e3,
     default: 6e3,
-    description: "Only used with awaitHotReload. Maximum wait for fresh runtime success/error diagnostics."
+    description: "Maximum wait for fresh runtime success/error diagnostics when awaitHotReload is true or requestHotReload triggers the default wait behavior."
   },
   awaitTimeoutMs: {
     type: "integer",
@@ -47509,7 +47588,7 @@ var HOT_RELOAD_RUNTIME_DIAGNOSTIC_SCHEMA_PROPERTIES = {
     minimum: 1,
     maximum: 200,
     default: 80,
-    description: "Only used with awaitHotReload. Console/runtime log limit in returned diagnostics."
+    description: "Console/runtime log limit returned with runtime diagnostics when awaitHotReload is true or requestHotReload triggers the default wait behavior."
   }
 };
 var ASSET_CODE_REF_DISCOVERY_INPUT_SCHEMA = {
@@ -47521,12 +47600,12 @@ var ASSET_CODE_REF_DISCOVERY_INPUT_SCHEMA = {
     },
     bucket: {
       type: "string",
-      description: "Legacy alias for category. Accepted only to tolerate older agent memory; prefer category in new calls."
+      description: "Accepted synonym for category. Prefer category in new calls."
     },
     buckets: {
       type: "array",
       items: { type: "string" },
-      description: "Legacy alias for category; first recognized item is used. Accepted only to tolerate older agent memory; prefer category in new calls."
+      description: "Accepted synonym for category; first recognized item is used. Prefer category in new calls."
     },
     query: {
       type: "string",
@@ -47610,7 +47689,7 @@ function buildHostedWaveStudioMcpToolDefinitions() {
     },
     {
       name: "accept_wave_agent_onboarding",
-      description: '[studio.mcp] Required acknowledgement after reading `get_wave_agent_onboarding`. Call only after keeping the role, coding guardrails, intent taxonomy, authoring workflow, and Studio tool policy in active LLM context. Requires exact promptVersion/promptHash, acceptedRole true, required cachedSections, full intentKindsCached, exact waveEngineSdkCacheCommandCached, and all context-cache booleans true. Production HTTP Gateway may also require local WaveEngine SDK cache proof before normal cached success. If SDK cache cannot work because sandbox/no filesystem/no Node/npm/user refusal/refresh failure, explicitly pass waveEngineSdkFallbackMode:"studio_ops_only", a valid waveEngineSdkUnavailableReason, and studioOpsOnlyFallbackAccepted:true, then warn user HTTP Gateway is Studio-ops-only and exact API lookup requires local SDK/cache repair. After success, stay in Wave Studio authoring-agent role and briefly confirm role accepted.',
+      description: '[studio.mcp] Required acknowledgement after reading `get_wave_agent_onboarding`. Call only after keeping the role, coding guardrails, intent taxonomy, authoring workflow, and Studio tool policy in active LLM context. Requires exact promptVersion/promptHash, acceptedRole true, required cachedSections, full intentKindsCached, exact waveEngineSdkCacheCommandCached, and all context-cache booleans true. Production HTTP Gateway may also require local WaveEngine SDK cache proof before normal cached success. If SDK cache cannot work because sandbox/no filesystem/no Node/npm/user refusal/refresh failure, explicitly pass waveEngineSdkFallbackMode:"studio_ops_only", a valid waveEngineSdkUnavailableReason, and studioOpsOnlyFallbackAccepted:true, then warn user HTTP Gateway is Studio-ops-only and skill/API lookup requires local SDK/cache repair. After success, stay in Wave Studio authoring-agent role and briefly confirm role accepted.',
       inputSchema: {
         type: "object",
         properties: {
@@ -47677,7 +47756,7 @@ function buildHostedWaveStudioMcpToolDefinitions() {
           },
           studioOpsOnlyFallbackAccepted: {
             type: "boolean",
-            description: "Required true with waveEngineSdkFallbackMode. Agent must warn user that HTTP Gateway is Studio-ops-only without local SDK cache; exact API lookup requires local SDK/cache repair."
+            description: "Required true with waveEngineSdkFallbackMode. Agent must warn user that HTTP Gateway is Studio-ops-only without local SDK cache; skill/API lookup requires local SDK/cache repair."
           },
           agentName: { type: "string" },
           agentProvider: { type: "string" }
@@ -47746,7 +47825,7 @@ function buildHostedWaveStudioMcpToolDefinitions() {
     },
     {
       name: "start_wave_task",
-      description: '[studio.mcp] Start the Wave Agent Behavior Harness for Author or Diagnose work: code authoring, debugging, exact API lookup, semantic edits, and multi-step investigations. Do not use this for Observe requests (read/inspect) or Operate requests (direct Studio commands such as run preview, hot reload, save, share, open project by resolved projectId, create/delete/rename exact files/assets). Classify routed intent chunks across project/code/direct-edit/semantic-guess/debug/VFS/asset/runtime/visual/marker/preview/general, then use returned taskRouteId in route-bound authoring tools. Canonical examples: run project -> preview.control direct Operate, no route; delete exact /foo.ts -> vfs.manage direct Operate, no route; call showDirection on cube -> code.direct_edit route; change existing cube color red to blue -> code.semantic_guess_edit route; add mountain or place objects in line -> code.author route; investigate runtime error -> code.debug route. Common casing/punctuation variants are normalized, but canonical kind values are preferred. Use code.direct_edit for exact power-user commands such as \u201Ccall showDirection on Amy\u201D. Use code.semantic_guess_edit only to change an existing API call/argument/literal/value such as COLOR.RED -> COLOR.BLUE; if the edit adds lines, creates objects, switches API, or chooses a WaveEngine pattern such as placement/layout, use code.author. If request is irrelevant or too broad, use agent.general and guide user toward a concrete Wave milestone instead of forcing Wave tools. Use code.debug alone for diagnose/report-only; for bug-fix requests include both code.debug and code.author. Fast start: when you already read enough context and know the edit, include nextPhase:"execute" plus editPlan/verificationPlan in this same call. Even faster: for exact line/text edits, start the route then call edit_wave_file directly with path plus exact startLine/endLine/text, edits:[...], or oldText/newText; no separate advance_wave_task needed.',
+      description: '[studio.mcp] Start the Wave Agent Behavior Harness for Author or Diagnose work: code authoring, debugging, local SDK skill/API lookup, semantic edits, and multi-step investigations. Do not use this for Observe requests (read/inspect) or Operate requests (direct Studio commands such as run preview, hot reload, save, share, open project by resolved projectId, create/delete/rename exact files/assets). Classify routed intent chunks across project/code/direct-edit/semantic-guess/debug/VFS/asset/runtime/visual/marker/preview/general, then use returned taskRouteId in route-bound authoring tools. Canonical examples: run project -> preview.control direct Operate, no route; delete exact /foo.ts -> vfs.manage direct Operate, no route; call showDirection on cube -> code.direct_edit route; change existing cube color red to blue -> code.semantic_guess_edit route; add mountain or place objects in line -> code.author route; investigate runtime error -> code.debug route. Common casing/punctuation variants are normalized, but canonical kind values are preferred. Use code.direct_edit for exact power-user commands such as \u201Ccall showDirection on Amy\u201D. Use code.semantic_guess_edit only to change an existing API call/argument/literal/value such as COLOR.RED -> COLOR.BLUE; if the edit adds lines, creates objects, switches API, or chooses a WaveEngine pattern such as placement/layout, use code.author. If request is irrelevant or too broad, use agent.general and guide user toward a concrete Wave milestone instead of forcing Wave tools. Use code.debug alone for diagnose/report-only; for bug-fix requests include both code.debug and code.author. Fast start: when you already read enough context and know the edit, include nextPhase:"execute" plus editPlan/verificationPlan in this same call. Even faster: for exact line/text edits, start the route then call edit_wave_file directly with path plus exact startLine/endLine/text, edits:[...], or oldText/newText; no separate advance_wave_task needed.',
       inputSchema: {
         type: "object",
         properties: {
@@ -47997,7 +48076,7 @@ function buildHostedWaveStudioMcpToolDefinitions() {
     },
     {
       name: "advance_wave_task",
-      description: "[studio.mcp] Advance an Author/Diagnose task route after evidence is gathered. taskRouteId is recommended, but if omitted Studio uses this MCP session\u2019s active route and still enforces phase/intent checks; routeId and nested route.taskRouteId/id are accepted. Phase aliases targetPhase and phase are accepted. Use before query_wave_api (lookup), broad authoring edits/apply_patch (execute), and final route verification. Do not advance just to run direct Operate tools such as run_wave_preview, hot_reload_wave_preview, save_wave_project, or create_wave_file when the user asked for that operation directly. Fast-lane direct/semantic code routes can skip lookup and advance straight to execute when exact user wording or current code is enough. This is the checkpoint that prevents jump-to-API/jump-to-edit behavior.",
+      description: "[studio.mcp] Advance an Author/Diagnose task route after evidence is gathered. taskRouteId is recommended, but if omitted Studio uses this MCP session\u2019s active route and still enforces phase/intent checks; routeId and nested route.taskRouteId/id are accepted. Phase aliases targetPhase and phase are accepted. Use before local-SDK query_wave_api (lookup), broad authoring edits/apply_patch (execute), and final route verification. Do not advance just to run direct Operate tools such as run_wave_preview, hot_reload_wave_preview, save_wave_project, or create_wave_file when the user asked for that operation directly. Fast-lane direct/semantic code routes can skip lookup and advance straight to execute when exact user wording or current code is enough. This is the checkpoint that prevents jump-to-API/jump-to-edit behavior.",
       inputSchema: {
         type: "object",
         properties: {
@@ -48116,7 +48195,7 @@ function buildHostedWaveStudioMcpToolDefinitions() {
     },
     {
       name: "list_wave_skill_families",
-      description: "[wave.*] Complete family router for WaveEngine code-authoring. Use after intent chunking/Core Intent Pass and before query_wave_skills/query_wave_api. Pick one or more families from this list first, e.g. continuous left turning -> wave.transform plus possibly wave.animate. This selects authoring direction; it does not inspect exact signatures.",
+      description: "[wave.*] Local WaveEngine SDK family router for code-authoring. HTTP Gateway hides/retires this lookup. Use after intent chunking/Core Intent Pass and before query_wave_skills/query_wave_api. Pick one or more families from this list first, e.g. continuous left turning -> wave.transform plus possibly wave.animate. This selects authoring direction; it does not inspect exact signatures.",
       inputSchema: {
         type: "object",
         properties: {
@@ -48130,7 +48209,7 @@ function buildHostedWaveStudioMcpToolDefinitions() {
     },
     {
       name: "query_wave_skills",
-      description: '[wave.*] Search compact WaveEngine skill cards only after skill-family selection. Do not pass the raw user request as a broad query. First call list_wave_skill_families, choose families from intent chunks/Core Intent Pass, then call this with families/familyId plus a small within-family query such as "continuous rotation" or "semantic direction". Use skillIds only for exact known skill ids.',
+      description: '[wave.*] Local WaveEngine SDK skill-card lookup. HTTP Gateway hides/retires this lookup. Search compact WaveEngine skill cards only after skill-family selection. Do not pass the raw user request as a broad query. First call list_wave_skill_families, choose families from intent chunks/Core Intent Pass, then call this with families/familyId plus a small within-family query such as "continuous rotation" or "semantic direction". Use skillIds only for exact known skill ids.',
       inputSchema: {
         type: "object",
         properties: {
@@ -48181,7 +48260,7 @@ function buildHostedWaveStudioMcpToolDefinitions() {
     },
     {
       name: "get_wave_skill",
-      description: "[wave.*] Read one generated WaveEngine skill card by skillId, id, or name. Use after list_wave_skill_families/query_wave_skills to inspect routing, examples, supporting skills, and anti-patterns.",
+      description: "[wave.*] Local WaveEngine SDK skill-card read. HTTP Gateway hides/retires this lookup. Read one generated WaveEngine skill card by skillId, id, or name. Use after list_wave_skill_families/query_wave_skills to inspect routing, examples, supporting skills, and anti-patterns.",
       inputSchema: {
         type: "object",
         properties: {
@@ -48545,19 +48624,27 @@ function buildHostedWaveStudioMcpToolDefinitions() {
     },
     {
       name: "read_wave_project",
-      description: `[studio.project] Read a bridge-readable Wave Studio project's VFS/code content without opening it in the paired editor. Use this to learn from example packs or compare patterns before editing the live project. It does not replace the current workspace, does not change dirty state, and does not run preview. projectId/id/project must be an exact project id from list_wave_projects, not a fuzzy project name; resolve names by listing first. Prefer projectId; id/project are accepted aliases.${BROWSER_COMMAND_PENDING_NOTE}`,
+      description: `[studio.project] Read a Wave Studio project's VFS/code content without opening it in the paired editor. Use this to learn from example packs or compare patterns before editing the live project. It does not replace the current workspace, does not change dirty state, and does not run preview. For saved/listed projects, pass exact projectId/id/project from list_wave_projects, not a fuzzy project name. For shared or published links, pass url/projectUrl/shareUrl/publishedUrl directly; silent URL reading supports old shared URLs like /waveStudio?share=<uuid>, new shared alias URLs, old/new published /p/<user>/<id> URLs, and /waveStudio?source=published&user=<user>&id=<id>. Prefer url for links and projectId for listed ids.${BROWSER_COMMAND_PENDING_NOTE}`,
       inputSchema: {
         type: "object",
         properties: {
           projectId: { type: "string" },
           id: { type: "string" },
           project: { type: "string" },
+          url: { type: "string" },
+          projectUrl: { type: "string" },
+          shareUrl: { type: "string" },
+          publishedUrl: { type: "string" },
           idempotencyKey: { type: "string" }
         },
         anyOf: [
           { required: ["projectId"] },
           { required: ["id"] },
-          { required: ["project"] }
+          { required: ["project"] },
+          { required: ["url"] },
+          { required: ["projectUrl"] },
+          { required: ["shareUrl"] },
+          { required: ["publishedUrl"] }
         ],
         additionalProperties: false
       }
@@ -48723,7 +48810,7 @@ function buildHostedWaveStudioMcpToolDefinitions() {
           },
           includeDataUrl: {
             type: "boolean",
-            description: 'Legacy alias for returnMode:"dataUrl". When true, also return dataUrl. Default false avoids duplicating large base64 output.'
+            description: 'Accepted synonym for returnMode:"dataUrl". When true, also return dataUrl. Default false avoids duplicating large base64 output.'
           },
           saveToLocalFile: {
             type: "boolean",
@@ -48770,7 +48857,7 @@ function buildHostedWaveStudioMcpToolDefinitions() {
     },
     {
       name: "edit_wave_file",
-      description: `[studio.vfs] PRIMARY forgiving one-file edit tool. Use this first for simple code edits: replace exact text, replace/delete a 1-based inclusive full-file line range, apply several one-file line/text edits through edits:[...], replace/delete a statement/fluent block by containing text, replace an inclusive fromText/toText range, or replace a whole file. For exact code.direct_edit/code.semantic_guess_edit/vfs.manage edits, this can run right after start_wave_task in context phase when args include exact path plus startLine/endLine/text, edits:[...], oldText/newText, deleteStatementContaining, replaceBlockContaining, blockContaining, or replaceBetween; no separate advance_wave_task is needed. mode is optional: oldText infers replaceText, edits:[{startLine,endLine,text}] infers multiLineEdits, edits:[{rangeOffset,rangeLength,text}] infers multiTextEdits, startLine/endLine infers replaceLines, block/between fields infer block line replacement, and path+text/content with no oldText infers whole-file replacement. Do not pass baseHash for simple edits; Studio resolves the latest file contentHash and still applies stale-write checks. Empty replacement text deletes. Prefer blockContaining/deleteStatementContaining over fragile line numbers when editing fluent Wave chains. Use ensureBlankLineAfter:true when replacing a line block that should keep one blank separator before the following code. Prefer text/newText; replacement/content are accepted aliases. Response begins with resultSummary: EDIT APPLIED or EDIT NOT APPLIED, and includes editMode/editTarget plus changedPaths/changedFiles. After the final code edit, prefer awaitHotReload:true so preview refresh and bounded diagnostics return in the same response; use requestHotReload:true only when you want fire-and-poll. Inspect changedPaths/changedFiles/partial/skippedOperations/hotReloadRequested/hotReloadSkippedReason/runtimeVerification; ok:true can still mean no content changed.${HOT_RELOAD_UNSAFE_CALLBACK_NOTE}${MANAGED_STUDIO_FILE_READONLY_NOTE}${WRITE_PAIRING_REQUIRED_NOTE}${BROWSER_COMMAND_PENDING_NOTE}`,
+      description: `[studio.vfs] PRIMARY forgiving one-file edit tool. Use this first for simple code edits: replace exact text, replace/delete a 1-based inclusive full-file line range, apply several one-file line/text edits through edits:[...], replace/delete a statement/fluent block by containing text, replace an inclusive fromText/toText range, or replace a whole file. For exact code.direct_edit/code.semantic_guess_edit/vfs.manage edits, this can run right after start_wave_task in context phase when args include exact path plus startLine/endLine/text, edits:[...], oldText/newText, deleteStatementContaining, replaceBlockContaining, blockContaining, or replaceBetween; no separate advance_wave_task is needed. mode is optional: oldText infers replaceText, edits:[{startLine,endLine,text}] infers multiLineEdits, edits:[{rangeOffset,rangeLength,text}] infers multiTextEdits, startLine/endLine infers replaceLines, block/between fields infer block line replacement, and path+text/content with no oldText infers whole-file replacement. Do not pass baseHash for simple edits; Studio resolves the latest file contentHash and still applies stale-write checks. Empty replacement text deletes. Prefer blockContaining/deleteStatementContaining over fragile line numbers when editing fluent Wave chains. Use ensureBlankLineAfter:true when replacing a line block that should keep one blank separator before the following code. Prefer text/newText; replacement/content are accepted aliases. Response begins with resultSummary: EDIT APPLIED or EDIT NOT APPLIED, and includes editMode/editTarget plus changedPaths/changedFiles. After the final code edit, prefer awaitHotReload:true so preview refresh and bounded diagnostics return in the same response; requestHotReload:true also waits by default unless awaitHotReload:false is passed intentionally. Inspect changedPaths/changedFiles/partial/skippedOperations/hotReloadRequested/hotReloadSkippedReason/runtimeVerification; ok:true can still mean no content changed.${HOT_RELOAD_UNSAFE_CALLBACK_NOTE}${MANAGED_STUDIO_FILE_READONLY_NOTE}${WRITE_PAIRING_REQUIRED_NOTE}${BROWSER_COMMAND_PENDING_NOTE}`,
       inputSchema: {
         type: "object",
         properties: {
@@ -48867,7 +48954,7 @@ function buildHostedWaveStudioMcpToolDefinitions() {
           requestHotReload: {
             type: "boolean",
             default: false,
-            description: "Default false. Set true on the final code edit when preview should update through hot reload. If the result returns hotReloadRequested false, no preview refresh was scheduled."
+            description: "Default false. Set true on the final code edit when preview should update through hot reload. Also waits for bounded diagnostics unless awaitHotReload:false is passed intentionally. If hotReloadRequested is false, no preview refresh was scheduled."
           },
           ...HOT_RELOAD_RUNTIME_DIAGNOSTIC_SCHEMA_PROPERTIES,
           idempotencyKey: { type: "string" }
@@ -48879,7 +48966,7 @@ function buildHostedWaveStudioMcpToolDefinitions() {
     },
     {
       name: "create_wave_file",
-      description: `[studio.vfs] Create/add one exact file path in the paired live Wave Studio browser VFS, including new TypeScript modules such as /actors/player.ts and HTML sketches such as /docs/diagram.html. Natural-language aliases: add file, create ts file, create html file, make module, make diagram, make chart. Requires exact path and full initial content; if either is missing, ask or read context instead of inventing. New .ts/.tsx files are standalone runnable source roots by default, so top-level scene code in a new file runs on Run/hot reload; set runnable:false only for pure helper modules that must not execute on their own. For Mermaid chart requests, create a .html file containing a \`<div class="mermaid">...</div>\` block; active HTML files preview in Studio and auto-load Mermaid when \`class="mermaid"\` is present. Helper modules imported by main files may not receive Studio wrapper globals; export functions that accept myScene, asset refs, or entities from main unless current code proves otherwise. Creates missing folders, refuses existing file/folder paths unless overwrite:true is explicitly supplied, and requires a write-capable pairing. Prefer awaitHotReload:true so create + hot reload + bounded diagnostics return in one response; use requestHotReload:true only for fire-and-poll.${HOT_RELOAD_UNSAFE_CALLBACK_NOTE}${MANAGED_STUDIO_FILE_READONLY_NOTE}${BROWSER_COMMAND_PENDING_NOTE}`,
+      description: `[studio.vfs] Create/add one exact file path in the paired live Wave Studio browser VFS, including new TypeScript modules such as /actors/player.ts and HTML sketches such as /docs/diagram.html. Natural-language aliases: add file, create ts file, create html file, make module, make diagram, make chart. Requires exact path and full initial content; if either is missing, ask or read context instead of inventing. New .ts/.tsx files are standalone runnable source roots by default, so top-level scene code in a new file runs on Run/hot reload; set runnable:false only for pure helper modules that must not execute on their own. For Mermaid chart requests, create a .html file containing a \`<div class="mermaid">...</div>\` block; active HTML files preview in the editor/coding pane and auto-load Mermaid when \`class="mermaid"\` is present. They must never replace the live engine preview iframe. Helper modules imported by main files may not receive Studio wrapper globals; export functions that accept myScene, asset refs, or entities from main unless current code proves otherwise. Creates missing folders, refuses existing file/folder paths unless overwrite:true is explicitly supplied, and requires a write-capable pairing. Prefer awaitHotReload:true so create + hot reload + bounded diagnostics return in one response; requestHotReload:true also waits by default unless awaitHotReload:false is passed intentionally.${HOT_RELOAD_UNSAFE_CALLBACK_NOTE}${MANAGED_STUDIO_FILE_READONLY_NOTE}${BROWSER_COMMAND_PENDING_NOTE}`,
       inputSchema: {
         type: "object",
         properties: {
@@ -48913,7 +49000,7 @@ function buildHostedWaveStudioMcpToolDefinitions() {
           },
           requestHotReload: {
             type: "boolean",
-            description: "Fire-and-poll hot reload flag. Prefer awaitHotReload:true when the created file is already imported by the running scene and the response should include bounded runtime diagnostics."
+            description: "Set true when the created file affects the running scene and preview should refresh through hot reload. Also waits for bounded diagnostics unless awaitHotReload:false is passed intentionally."
           },
           ...HOT_RELOAD_RUNTIME_DIAGNOSTIC_SCHEMA_PROPERTIES,
           idempotencyKey: { type: "string" }
@@ -48944,7 +49031,7 @@ function buildHostedWaveStudioMcpToolDefinitions() {
           to: { type: "string" },
           requestHotReload: {
             type: "boolean",
-            description: "Set true when the moved/renamed module affects the running scene and the preview should refresh through hot reload."
+            description: "Set true when the moved/renamed module affects the running scene and preview should refresh through hot reload. Also waits for bounded diagnostics unless awaitHotReload:false is passed intentionally."
           },
           ...HOT_RELOAD_RUNTIME_DIAGNOSTIC_SCHEMA_PROPERTIES,
           idempotencyKey: { type: "string" }
@@ -48970,7 +49057,7 @@ function buildHostedWaveStudioMcpToolDefinitions() {
           },
           requestHotReload: {
             type: "boolean",
-            description: "Set true when the deleted module affects the running scene after imports have been updated and the preview should refresh through hot reload."
+            description: "Set true when the deleted module affects the running scene after imports have been updated and preview should refresh through hot reload. Also waits for bounded diagnostics unless awaitHotReload:false is passed intentionally."
           },
           ...HOT_RELOAD_RUNTIME_DIAGNOSTIC_SCHEMA_PROPERTIES,
           idempotencyKey: { type: "string" }
@@ -48981,7 +49068,7 @@ function buildHostedWaveStudioMcpToolDefinitions() {
     },
     {
       name: "apply_wave_patch",
-      description: `[studio.vfs] ADVANCED grouped edit tool. Use only for grouped/multi-file operations, strict searchReplace, unifiedDiff, or complex stale-checked edits. For simple one-file edits use edit_wave_file. Prefer operations:[...], but a single operation object is accepted via operation or as a bare call for agent mistake recovery. Existing-file writeFile requires baseHash unless forceOverwrite is true. Do not send multiple compact ops for the same file with the same baseHash; the first edit changes the file hash and later compact ops will skip as stale. ok:true can still be a no-op or partial result; always inspect changedFiles, changedPaths, partial, skippedOperations, hotReloadRequested, hotReloadSkippedReason, and runtimeVerification. After the final grouped code edit, prefer awaitHotReload:true when preview already ran; use requestHotReload:true only when you want fire-and-poll. Studio may upgrade that hot-reload request internally to patchMain, preserveScene, or hard rebuildScene; do not edit bootstrap manually just to register assets. Use run_wave_preview only if diagnostics show hasRunSucceeded false, the user explicitly asked for a full restart, or hot reload is stuck/failing.${HOT_RELOAD_UNSAFE_CALLBACK_NOTE}${MANAGED_STUDIO_FILE_READONLY_NOTE}${WRITE_PAIRING_REQUIRED_NOTE}${BROWSER_COMMAND_PENDING_NOTE}`,
+      description: `[studio.vfs] ADVANCED grouped edit tool. Use only for grouped/multi-file operations, strict searchReplace, unifiedDiff, or complex stale-checked edits. For simple one-file edits use edit_wave_file. Prefer operations:[...], but a single operation object is accepted via operation or as a bare call for agent mistake recovery. Existing-file writeFile requires baseHash unless forceOverwrite is true. Do not send multiple compact ops for the same file with the same baseHash; the first edit changes the file hash and later compact ops will skip as stale. ok:true can still be a no-op or partial result; always inspect changedFiles, changedPaths, partial, skippedOperations, hotReloadRequested, hotReloadSkippedReason, and runtimeVerification. After the final grouped code edit, prefer awaitHotReload:true when preview already ran; requestHotReload:true also waits by default unless awaitHotReload:false is passed intentionally. Studio may upgrade that hot-reload request internally to patchMain, preserveScene, or hard rebuildScene; do not edit bootstrap manually just to register assets. Use run_wave_preview only if diagnostics show hasRunSucceeded false, the user explicitly asked for a full restart, or hot reload is stuck/failing.${HOT_RELOAD_UNSAFE_CALLBACK_NOTE}${MANAGED_STUDIO_FILE_READONLY_NOTE}${WRITE_PAIRING_REQUIRED_NOTE}${BROWSER_COMMAND_PENDING_NOTE}`,
       inputSchema: {
         type: "object",
         properties: {
@@ -48989,7 +49076,7 @@ function buildHostedWaveStudioMcpToolDefinitions() {
           requestHotReload: {
             type: "boolean",
             default: false,
-            description: "Default false. Set true after the final code edit when preview should update through hot reload. If the result returns hotReloadRequested false, no preview refresh was scheduled; inspect hotReloadSkippedReason/skippedOperations."
+            description: "Default false. Set true after the final code edit when preview should update through hot reload. Also waits for bounded diagnostics unless awaitHotReload:false is passed intentionally. If hotReloadRequested is false, inspect hotReloadSkippedReason/skippedOperations."
           },
           ...HOT_RELOAD_RUNTIME_DIAGNOSTIC_SCHEMA_PROPERTIES,
           idempotencyKey: { type: "string" },
@@ -49189,14 +49276,14 @@ function buildHostedWaveStudioMcpToolDefinitions() {
     },
     {
       name: "hot_reload_wave_preview",
-      description: `[studio.preview] Default standalone tool for seeing code-change results in an already-running Wave Studio preview when no edit tool is being called. Natural-language aliases: hot reload, reload preview, refresh preview after edit, refresh scene. Trigger the same hot-reload path as Wave Studio's toolbar button through the paired browser session. In multi-file VFS projects, this tool has no file path argument and reloads the currently open/active TypeScript file when safe, not every user-created .ts module. Before calling it for a specific module, make sure that module is the active Studio editor file. For code edits, prefer the edit tool's awaitHotReload:true on the final edit to pair the change, hot reload, and bounded diagnostics in one MCP response; use requestHotReload:true only for intentional fire-and-poll. Studio may upgrade this same request internally to patchMain, preserveScene, or hard rebuildScene when asset/bootstrap/runtime-surface changes require it; agents should not manually guess the tier. This tool confirms the request was accepted, not that runtime execution has finished; use returned requestedAt and poll diagnostics until lastRuntimeOutcomeAt is newer and lastRuntimeOutcome is success or error, then inspect latestError/screenshot/entity snapshots. If hot reload gets stuck or fails, run_wave_preview is the last-resort full restart.${WRITE_PAIRING_REQUIRED_NOTE}${BROWSER_COMMAND_PENDING_NOTE}`,
+      description: `[studio.preview] Default standalone tool for seeing code-change results in an already-running Wave Studio preview when no edit tool is being called. Natural-language aliases: hot reload, reload preview, refresh preview after edit, refresh scene. Trigger the same hot-reload path as Wave Studio's toolbar button through the paired browser session. In multi-file VFS projects, this tool has no file path argument and reloads the currently open/active TypeScript file when safe, not every user-created .ts module. Before calling it for a specific module, make sure that module is the active Studio editor file. For code edits, prefer the edit tool's awaitHotReload:true on the final edit to pair the change, hot reload, and bounded diagnostics in one MCP response. Studio may upgrade this same request internally to patchMain, preserveScene, or hard rebuildScene when asset/bootstrap/runtime-surface changes require it; agents should not manually guess the tier. By default this tool waits for bounded runtime diagnostics and returns runtimeVerification; set awaitRuntimeResult:false only for intentional fire-and-poll. If hot reload gets stuck or fails, run_wave_preview is the last-resort full restart.${WRITE_PAIRING_REQUIRED_NOTE}${BROWSER_COMMAND_PENDING_NOTE}`,
       inputSchema: {
         type: "object",
         properties: {
           idempotencyKey: { type: "string" },
           awaitRuntimeResult: {
             type: "boolean",
-            description: "When true, wait in the same MCP call for bounded runtime diagnostics after the hot-reload request. Response includes runtimeVerification."
+            description: "Default true. Wait in the same MCP call for bounded runtime diagnostics after the hot-reload request. Set false only for intentional fire-and-poll."
           },
           awaitDiagnostics: {
             type: "boolean",
@@ -49210,14 +49297,14 @@ function buildHostedWaveStudioMcpToolDefinitions() {
     },
     {
       name: "run_wave_preview",
-      description: `[studio.preview] Trigger a full Wave Studio preview run/start through the paired browser session. Natural-language aliases: run project, start preview, start project, full restart, restart scene, kick the scene again. Do not use this as the normal post-edit path; use edit-tool awaitHotReload:true after edits or standalone hot_reload_wave_preview for preview refresh first. Use run only when diagnostics show hasRunSucceeded false, the user explicitly asks for a full restart, or hot reload/polling fails and a full restart is the last resort. This tool confirms the request was accepted, not that runtime execution has finished; use returned requestedAt and poll diagnostics until lastRuntimeOutcomeAt is newer and lastRuntimeOutcome is success or error, then inspect latestError/screenshot/entity snapshots.${WRITE_PAIRING_REQUIRED_NOTE}${BROWSER_COMMAND_PENDING_NOTE}`,
+      description: `[studio.preview] Trigger a full Wave Studio preview run/start through the paired browser session. Natural-language aliases: run project, start preview, start project, full restart, restart scene, kick the scene again. Do not use this as the normal post-edit path; use edit-tool awaitHotReload:true after edits or standalone hot_reload_wave_preview for preview refresh first. Use run only when diagnostics show hasRunSucceeded false, the user explicitly asks for a full run/restart, or hot reload/polling fails and a full restart is the last resort. By default this tool waits for bounded runtime diagnostics and returns runtimeVerification; set awaitRuntimeResult:false only for intentional fire-and-poll.${WRITE_PAIRING_REQUIRED_NOTE}${BROWSER_COMMAND_PENDING_NOTE}`,
       inputSchema: {
         type: "object",
         properties: {
           idempotencyKey: { type: "string" },
           awaitRuntimeResult: {
             type: "boolean",
-            description: "When true, wait in the same MCP call for bounded runtime diagnostics after the run request. Response includes runtimeVerification."
+            description: "Default true. Wait in the same MCP call for bounded runtime diagnostics after the run request. Set false only for intentional fire-and-poll."
           },
           awaitDiagnostics: {
             type: "boolean",
@@ -49330,10 +49417,10 @@ function buildHostedWaveStudioMcpToolDefinitions() {
 }
 
 // ../../scripts/wavegenie-sdk/mcp/toolDefinitions.ts
-var CANONICAL_HOSTED_TOOL_NAMES = new Set(
+var CANONICAL_WAVE_MCP_TOOL_NAMES = new Set(
   buildHostedWaveStudioMcpToolDefinitions().map((definition) => definition.name)
 );
-var HOSTED_REFERENCE_TOOL_NAMES = /* @__PURE__ */ new Set([
+var LOCAL_SDK_LOOKUP_TOOL_NAMES = /* @__PURE__ */ new Set([
   "get_wave_coding_guardrails",
   "list_wave_skill_families",
   "query_wave_skills",
@@ -49399,6 +49486,28 @@ var LOCAL_OPTIONAL_SESSION_TOOL_NAMES = /* @__PURE__ */ new Set([
   "resume_wave_preview",
   "resume_wave_engine"
 ]);
+var LOCAL_SDK_CONTROL_TOOL_NAMES = /* @__PURE__ */ new Set([
+  "get_wave_agent_onboarding",
+  "accept_wave_agent_onboarding",
+  "self_check_wave_mcp",
+  "list_wave_sessions",
+  "get_active_wave_session",
+  "recover_wave_connection",
+  "start_wave_task",
+  "advance_wave_task",
+  "get_wave_task_route",
+  "get_wave_tool_map",
+  "get_wave_mcp_health",
+  "get_wave_command_result"
+]);
+var LOCAL_SDK_IMPLEMENTED_CANONICAL_TOOL_NAMES = /* @__PURE__ */ new Set([
+  ...LOCAL_SDK_CONTROL_TOOL_NAMES,
+  ...LOCAL_SDK_LOOKUP_TOOL_NAMES,
+  ...[...LOCAL_OPTIONAL_SESSION_TOOL_NAMES].map((name) => canonicalizeWaveMcpToolName(name))
+]);
+function isLocalMcpToolImplemented(name) {
+  return LOCAL_SDK_IMPLEMENTED_CANONICAL_TOOL_NAMES.has(canonicalizeWaveMcpToolName(name));
+}
 function getReadToolDefinitions() {
   return [
     {
@@ -49554,13 +49663,13 @@ function localizeHostedToolDefinition(definition, localOverrides) {
   if (definition.name === "get_wave_session") {
     description = "[studio.mcp] Return the Wave Studio browser session paired through the WaveEngine Agent SDK.";
   } else if (definition.name === "recover_wave_connection") {
-    description = "[studio.mcp] Direct Observe recovery tool for WaveEngine Agent SDK. Call after session_not_found, command_timeout, command_lease_expired, agent_onboarding_required, hosted_mcp_proxy_failed, or local/HTTP Gateway/cache confusion. Returns exact next action: re-onboard, get session, wake Wave Studio tab, update/restart SDK, retry same tool, use HTTP Gateway fallback, or ask fresh Copy to Agent only if token is rejected everywhere.";
+    description = "[studio.mcp] Direct Observe recovery tool for WaveEngine Agent SDK. Call after session_not_found, command_timeout, command_lease_expired, agent_onboarding_required, local_sdk_tool_not_implemented, wave_engine_sdk_cache_required, or local/HTTP Gateway/cache confusion. Returns exact next action: re-onboard, get session, wake Wave Studio tab, update/restart SDK, retry same tool, use HTTP Gateway fallback, or ask fresh Copy to Agent only if token is rejected everywhere.";
   } else if (definition.name === "get_wave_command_result") {
     description = '[studio.mcp] Use only when a prior tool response includes status:"pending" plus requestId. Catalog-parity tool for agents trained on the HTTP Gateway. WaveEngine Agent SDK browser-backed tools normally wait for the Studio browser result directly, so this usually reports that no local pending-command queue is used.';
   } else if (definition.name === "get_wave_coding_guardrails") {
     description = "[studio.mcp] Return compact Wave Studio coding guardrails. WaveEngine Agent SDK answers from bundled SDK/onboarding. HTTP Gateway remains Studio-ops-only and has no cloud API lookup.";
   } else if (definition.name === "get_wave_tool_map") {
-    description = "[studio.mcp] Stable local MCP tool map. Always returns the full concrete local/hosted-parity catalog grouped by family plus policy flags.";
+    description = "[studio.mcp] Stable local MCP tool map. Returns the concrete local SDK catalog grouped by family plus handler-parity and policy flags.";
   } else if (definition.name === "get_wave_mcp_health") {
     description = "[studio.mcp] Read-only WaveEngine Agent SDK health/status. Reports actual local SDK version/build, tool catalog hash/count, current transport, paired browser sessions, onboarding state, active route, and WaveEngine SDK Cache existence/version/staleness. Aliases: mcp_health, mcp_status, get_wave_mcp_status.";
   } else if (definition.name === "list_wave_skill_families") {
@@ -49594,25 +49703,35 @@ function localizeHostedToolDefinition(definition, localOverrides) {
 }
 function mergeLocalToolDefinitions(canonicalDefinitions) {
   const localOverrides = getLocalOverrideToolDefinitions();
-  const localizedDefinitions = canonicalDefinitions.map((definition) => localizeHostedToolDefinition(definition, localOverrides));
+  const localizedDefinitions = canonicalDefinitions.filter((definition) => isLocalMcpToolImplemented(definition.name)).map((definition) => localizeHostedToolDefinition(definition, localOverrides));
   const byName = new Map(localizedDefinitions.map((definition) => [definition.name, definition]));
   for (const definition of localOverrides.values()) {
     byName.set(definition.name, definition);
   }
   const definitions = [...byName.values()];
-  assertLocalToolDefinitionParity(canonicalDefinitions, definitions);
+  assertLocalToolDefinitionHandlerParity(definitions);
   return definitions;
 }
-function assertLocalToolDefinitionParity(canonicalDefinitions, localDefinitions) {
-  const localNames = new Set(localDefinitions.map((definition) => definition.name));
-  const missingNames = canonicalDefinitions.map((definition) => definition.name).filter((name) => !localNames.has(name));
-  if (missingNames.length > 0) {
-    throw new Error(`Local MCP tool catalog missing canonical Hosted MCP tools: ${missingNames.join(", ")}`);
+function assertLocalToolDefinitionHandlerParity(localDefinitions) {
+  const unimplementedNames = localDefinitions.map((definition) => definition.name).filter((name) => !isLocalMcpToolImplemented(name));
+  if (unimplementedNames.length > 0) {
+    throw new Error(`Local MCP tool catalog includes tools without local handlers: ${unimplementedNames.join(", ")}`);
   }
 }
 function getLocalToolDefinitions() {
   return mergeLocalToolDefinitions(buildHostedWaveStudioMcpToolDefinitions());
 }
+function getLocalToolImplementationSummary() {
+  const canonicalToolNames = [...CANONICAL_WAVE_MCP_TOOL_NAMES].sort();
+  const implementedCanonicalToolNames = canonicalToolNames.filter((name) => isLocalMcpToolImplemented(name));
+  return {
+    canonicalToolCount: canonicalToolNames.length,
+    implementedCanonicalToolCount: implementedCanonicalToolNames.length,
+    localExtraToolNames: [...LOCAL_EXTRA_TOOL_DEFINITION_NAMES].sort(),
+    localLookupToolNames: [...LOCAL_SDK_LOOKUP_TOOL_NAMES].sort(),
+    omittedCanonicalToolNames: canonicalToolNames.filter((name) => !isLocalMcpToolImplemented(name))
+  };
+}
 function getLocalToolCatalogHash() {
   const tools = getLocalToolDefinitions().map((definition) => ({
     name: definition.name,
@@ -49626,6 +49745,16 @@ function getLocalToolCatalogHash() {
 function nowIso() {
   return (/* @__PURE__ */ new Date()).toISOString();
 }
+function localSdkLookupStatus(waveEngineSdkCache) {
+  const corpusCacheReady = waveEngineSdkCache.ready === true;
+  return {
+    source: "package_bundled_wave_engine_sdk_cache",
+    corpusCacheReady,
+    apiAndSkillQueryAvailable: corpusCacheReady,
+    cacheMissAffectsLiveStudioTransport: false,
+    lookupToolNames: [...LOCAL_SDK_LOOKUP_TOOL_NAMES].sort()
+  };
+}
 function jsonRpcToolIdempotencyKey(toolName, requestId) {
   if (typeof requestId !== "string" && typeof requestId !== "number") return null;
   return `jsonrpc:${toolName}:${String(requestId)}`;
@@ -49814,7 +49943,12 @@ function localConnectionRecoveryResult(args, context) {
     nextAction = "Read tools can continue. For write/run/hot reload, user must make the Studio MCP session read-write/adopt WaveEngine Agent SDK, then retry same local endpoint and MCP_TOKEN pairing secret or paste fresh Copy to Agent if the secret changed.";
     nextTool = "get_wave_session";
     requiresUserAction = true;
-  } else if (lastErrorCode === "hosted_mcp_proxy_failed" || lastErrorCode === "wave_engine_sdk_cache_required") {
+  } else if (lastErrorCode === "local_sdk_tool_not_implemented" || lastErrorCode === "local_sdk_lookup_handler_missing") {
+    state = "local_sdk_handler_missing";
+    nextAction = "This SDK build lacks a local handler for the requested canonical tool. Call tools/list and use a listed tool, or update/restart the exact SDK package.";
+    nextTool = "tools/list";
+    steps.push("Do not treat missing local handler as WaveEngine SDK Cache failure.");
+  } else if (lastErrorCode === "wave_engine_sdk_cache_required") {
     state = "wave_engine_sdk_cache_unavailable";
     nextAction = "Live Studio tools can continue. Skill/API lookup cache failed; update/restart the exact SDK package or run the bundled SDK repair command. HTTP Gateway is Studio-ops-only.";
     nextTool = "get_wave_session";
@@ -49869,6 +50003,24 @@ function localConnectionRecoveryResult(args, context) {
     ]
   });
 }
+function localSdkToolNotImplementedResult(name) {
+  return errorToolResult(
+    "local_sdk_tool_not_implemented",
+    `${name} is a canonical Wave MCP tool, but this WaveEngine Agent SDK build has no local handler for it. It is intentionally omitted from tools/list until implemented; update wave3d-agent-sdk or use a listed tool.`,
+    {
+      toolName: name,
+      localSdk: true,
+      missingLocalHandler: true,
+      affectsLiveStudioTransport: false,
+      affectsWaveEngineSdkCache: false,
+      recovery: [
+        "Call tools/list and choose one of the listed local tools.",
+        "Update/restart the exact wave3d-agent-sdk package when you need this canonical tool locally.",
+        "Do not treat this as wave_engine_sdk_cache_required; SDK cache repair cannot add a missing live-tool handler."
+      ]
+    }
+  );
+}
 function taskRouteToolResult(route) {
   return successToolResult({
     ok: true,
@@ -49989,6 +50141,9 @@ function normalizeRuntimeDiagnosticsTimeoutMs2(value) {
   if (typeof value !== "number" || !Number.isFinite(value)) return void 0;
   return Math.min(Math.max(500, Math.trunc(value)), 15e3);
 }
+function shouldAwaitRuntimeActionDiagnostics(args) {
+  return args?.awaitRuntimeResult !== false && args?.awaitDiagnostics !== false && args?.returnRuntimeDiagnostics !== false;
+}
 function resolveAssetCategoryBucket(value) {
   if (typeof value !== "string" || !value.trim()) return null;
   return getWaveStudioAssetBucketFromCategory(value.trim());
@@ -50142,12 +50297,15 @@ async function enqueueLocalAssetUploadCommand(input) {
 }
 async function callReadTool(name, args, context) {
   if (name === "get_wave_agent_onboarding") {
+    const waveEngineSdkCache = await inspectLocalCorpusCacheForContext(context);
     return successToolResult({
       ok: true,
       promptVersion: LOCAL_MCP_AGENT_ONBOARDING_VERSION,
       promptHash: LOCAL_MCP_AGENT_ONBOARDING_PROMPT_HASH,
       prompt: LOCAL_MCP_AGENT_ONBOARDING_PROMPT,
       localSdk: true,
+      waveEngineSdkCache,
+      waveEngineSdkLookup: localSdkLookupStatus(waveEngineSdkCache),
       onboardingPhases: [
         { phase: -1, required: true, action: "Treat Copy-to-Agent as bootstrap only", fallback: "Use this MCP response as the current source of truth for phased setup, recovery, routing, cache, and tool policy. If clipboard text and MCP response differ, prefer MCP response." },
         { phase: 0, required: false, action: "WaveEngine Agent SDK preflight", fallback: "Already satisfied because this endpoint is local." },
@@ -50302,6 +50460,8 @@ async function callReadTool(name, args, context) {
   }
   if (name === "self_check_wave_mcp") {
     const toolDefinitions = getLocalToolDefinitions();
+    const toolImplementation = getLocalToolImplementationSummary();
+    const waveEngineSdkCache = await inspectLocalCorpusCacheForContext(context);
     const sessions = getAuthorizedSessions(context);
     const activeRoute = getLocalActiveTaskRoute(context);
     const expectedVersion = normalizeOptionalString(args?.expectedVersion);
@@ -50331,8 +50491,12 @@ async function callReadTool(name, args, context) {
         hasHotReload: toolDefinitions.some((definition) => definition.name === "hot_reload_wave_preview"),
         hasPauseResume: toolDefinitions.some((definition) => definition.name === "pause_wave_preview") && toolDefinitions.some((definition) => definition.name === "resume_wave_preview"),
         hasAssetCategorySearch: toolDefinitions.some((definition) => definition.name === "find_wave_assets_by_category"),
-        hasProjectRename: toolDefinitions.some((definition) => definition.name === "rename_wave_project")
+        hasProjectRename: toolDefinitions.some((definition) => definition.name === "rename_wave_project"),
+        listedToolsHaveLocalHandlers: true,
+        implementation: toolImplementation
       },
+      waveEngineSdkCache,
+      waveEngineSdkLookup: localSdkLookupStatus(waveEngineSdkCache),
       sessions: {
         pairedStudioSessionCount: sessions.length,
         readwriteSessionCount: sessions.filter((session) => session.accessMode === "readwrite").length
@@ -50347,6 +50511,7 @@ async function callReadTool(name, args, context) {
   }
   if (name === "get_wave_mcp_health") {
     const toolDefinitions = getLocalToolDefinitions();
+    const toolImplementation = getLocalToolImplementationSummary();
     const sessions = getAuthorizedSessions(context);
     const activeRoute = getLocalActiveTaskRoute(context);
     const waveEngineSdkCache = await inspectLocalCorpusCacheForContext(context);
@@ -50388,7 +50553,9 @@ async function callReadTool(name, args, context) {
         hasPauseResume: toolDefinitions.some((definition) => definition.name === "pause_wave_preview") && toolDefinitions.some((definition) => definition.name === "resume_wave_preview"),
         hasAssetCategorySearch: toolDefinitions.some((definition) => definition.name === "find_wave_assets_by_category"),
         hasMcpHealth: toolDefinitions.some((definition) => definition.name === "get_wave_mcp_health"),
-        hasProjectRename: toolDefinitions.some((definition) => definition.name === "rename_wave_project")
+        hasProjectRename: toolDefinitions.some((definition) => definition.name === "rename_wave_project"),
+        listedToolsHaveLocalHandlers: true,
+        implementation: toolImplementation
       },
       onboarding: {
         accepted: onboardingAccepted,
@@ -50396,6 +50563,7 @@ async function callReadTool(name, args, context) {
         promptHash: LOCAL_MCP_AGENT_ONBOARDING_PROMPT_HASH
       },
       waveEngineSdkCache,
+      waveEngineSdkLookup: localSdkLookupStatus(waveEngineSdkCache),
       sessions: {
         pairedStudioSessionCount: sessions.length,
         readwriteSessionCount: sessions.filter((session) => session.accessMode === "readwrite").length,
@@ -50425,6 +50593,7 @@ async function callReadTool(name, args, context) {
       stableToolMap: true,
       toolCatalogHash: getLocalToolCatalogHash(),
       toolCount: toolDefinitions.length,
+      toolImplementation: getLocalToolImplementationSummary(),
       toolCatalogSummary: buildWaveMcpToolCatalogSummary(toolDefinitions),
       studioSkillMap: [
         "studio.mcp: get_wave_mcp_health (aliases: mcp_health, mcp_status), get_wave_session, recover_wave_connection, get_wave_command_result, get_wave_coding_guardrails, get_wave_tool_map",
@@ -50447,8 +50616,8 @@ async function callReadTool(name, args, context) {
   if (name === "recover_wave_connection") {
     return localConnectionRecoveryResult(args, context);
   }
-  if (HOSTED_REFERENCE_TOOL_NAMES.has(name)) {
-    return await proxyHostedReferenceTool({
+  if (LOCAL_SDK_LOOKUP_TOOL_NAMES.has(name)) {
+    return await runLocalSdkLookupTool({
       context,
       name,
       args
@@ -50575,7 +50744,7 @@ async function callReadTool(name, args, context) {
       command: {
         type: "runtimeAction",
         action,
-        awaitRuntimeResult: args?.awaitRuntimeResult === true || args?.awaitDiagnostics === true,
+        awaitRuntimeResult: shouldAwaitRuntimeActionDiagnostics(args),
         ...runtimeDiagnosticsTimeoutMs !== void 0 ? { runtimeDiagnosticsTimeoutMs } : {},
         ...runtimeDiagnosticsLimit !== void 0 ? { runtimeDiagnosticsLimit } : {}
       }
@@ -50982,8 +51151,8 @@ async function callReadTool(name, args, context) {
     if (!session) {
       return errorToolResult("session_not_found", LOCAL_SESSION_NOT_FOUND_MESSAGE);
     }
-    const projectId = requireNonEmptyString(stringAliasArg(args, ["projectId", "id", "project"]));
-    if (!projectId) return errorToolResult("invalid_arguments", "`read_wave_project` requires a non-empty `projectId`.");
+    const projectId = requireNonEmptyString(stringAliasArg(args, ["projectId", "id", "project", "url", "projectUrl", "shareUrl", "publishedUrl"]));
+    if (!projectId) return errorToolResult("invalid_arguments", "`read_wave_project` requires a non-empty `projectId` or shared/published project URL.");
     return await enqueueBrowserCommand({
       context,
       session,
@@ -51028,12 +51197,8 @@ async function callReadTool(name, args, context) {
       timeoutMs: 3e4
     });
   }
-  if (CANONICAL_HOSTED_TOOL_NAMES.has(name)) {
-    return await proxyHostedReferenceTool({
-      context,
-      name,
-      args
-    });
+  if (CANONICAL_WAVE_MCP_TOOL_NAMES.has(name)) {
+    return localSdkToolNotImplementedResult(name);
   }
   return errorToolResult("tool_not_found", `Unknown WaveEngine Agent SDK tool: ${name}.`);
 }
@@ -51075,7 +51240,7 @@ async function handleWaveGenieMcpRequest(request, context) {
     });
     return createJsonRpcResult(request.id ?? null, {
       nextRecommendedTool: onboardingAccepted ? !hasPairedStudioSession ? "recover_wave_connection" : activeRoute ? activeRoute.phase === "lookup" ? "query_wave_api" : activeRoute.phase === "execute" ? "edit_wave_file" : "get_wave_task_route" : "get_wave_session" : "get_wave_agent_onboarding",
-      nextRecommendedAction: onboardingAccepted ? !hasPairedStudioSession ? "Call recover_wave_connection, then follow its nextAction to pair/wake the Wave Studio tab. Reference/cache tools can still run without a tab." : activeRoute ? activeRoute.phase === "lookup" ? "Lookup is unlocked; call query_wave_api only for exact symbol/signature/global uncertainty." : activeRoute.phase === "execute" ? "Execute is unlocked; call the specific edit/operate tool now." : "Inspect get_wave_task_route, then advance when enough evidence is collected." : "Call get_wave_session, then use observe tools or start_wave_task for authoring work." : "Call get_wave_agent_onboarding, accept the returned role/guardrails, then call tools/list again.",
+      nextRecommendedAction: onboardingAccepted ? !hasPairedStudioSession ? "Call recover_wave_connection, then follow its nextAction to pair/wake the Wave Studio tab. SDK lookup/cache tools can still run without a tab." : activeRoute ? activeRoute.phase === "lookup" ? "Lookup is unlocked; call query_wave_api only for exact symbol/signature/global uncertainty." : activeRoute.phase === "execute" ? "Execute is unlocked; call the specific edit/operate tool now." : "Inspect get_wave_task_route, then advance when enough evidence is collected." : "Call get_wave_session, then use observe tools or start_wave_task for authoring work." : "Call get_wave_agent_onboarding, accept the returned role/guardrails, then call tools/list again.",
       requiresOnboarding: !onboardingAccepted,
       requiresStudioSessionForLiveTools: true,
       hasPairedStudioSession,
@@ -51088,6 +51253,10 @@ async function handleWaveGenieMcpRequest(request, context) {
         preTaskEvidence: activeRoute ? null : getLocalPreTaskEvidence(context),
         rule: WAVE_MCP_BEHAVIOR_HARNESS_RULE
       },
+      toolImplementation: {
+        listedToolsHaveLocalHandlers: true,
+        ...getLocalToolImplementationSummary()
+      },
       toolCatalogSummary: buildWaveMcpToolCatalogSummary(tools),
       tools
     });