summer-engine 3.7.0 → 4.0.0

package/library/skills/environment-kit/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: environment-kit
-description: "Generate a modular environment kit — wall pieces, floor tiles, pillars, doors, arches, corners — snap-together meshes sharing one visual style."
+description: "Generate a modular environment kit: walls, floor tiles, pillars, doors, arches in one visual style."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: 3d-assets
 user-invocable: true
-allowed-tools: Read Grep summer_search_assets summer_list_my_assets summer_get_asset summer_import_asset_by_id summer_generate_3d summer_generate_image summer_import_from_url summer_add_node summer_set_prop summer_inspect_node summer_get_scene_tree summer_save_scene
+allowed-tools: Read Grep summer_assets_search summer_assets_get summer_import_asset_by_id summer_assets_generate_3d summer_assets_generate_image summer_import_from_url summer_add_node summer_set_prop summer_inspect_node summer_get_scene_tree summer_save_scene summer_jobs_wait summer_call
 paths: ["assets/kits/**", "assets/models/**", "**/*.tscn", "**/*.gd"]
 ---
 
@@ -13,7 +13,7 @@ paths: ["assets/kits/**", "assets/models/**", "**/*.tscn", "**/*.gd"]
 
 A kit is a *family* of meshes — wall, floor, door, pillar, corner, arch — that the level designer snaps together to build interiors and exteriors. The skill exists to solve **one specific failure mode**: generating each piece with a fresh prompt produces six pieces that look like they came from six different games. The fix is the **style anchor pattern** — generate one piece first, lock its prompt suffix, and reuse that exact suffix for every subsequent piece.
 
-The backing tool is `summer_generate_3d`, called once per piece. A 6-piece kit is six generations and about 5 minutes. Generation uses credits, so confirm scope before starting.
+The backing operation is `assets.generate_3d`, called once per piece; each call answers with a job that `jobs.wait` follows. A 6-piece kit is six generations and about 5 minutes. Generation uses credits, so confirm scope before starting (`dryRun: true` on one piece's call gives its credits).
 
 ## When to use
 
@@ -63,7 +63,7 @@ Kit pieces only feel modular if they snap to a fixed grid. Pick the grid before
 | **2m** | Standard interiors (homes, taverns, offices) | Wall = 2×3×0.3m. Floor = 2×2m. Halves piece count. |
 | **4m** | Exteriors and large halls (temples, warehouses, throne rooms) | Wall = 4×4×0.4m. Floor = 4×4m. Quarter the piece count for the same area. |
 
-**Critical:** include the dimensions in the prompt. `summer_generate_3d` doesn't enforce them, but Hunyuan respects scale cues — `2 meter tall wall section` produces a mesh that imports near 2m tall. Then verify with `summer_inspect_resource` and scale-correct in the editor if needed.
+**Critical:** include the dimensions in the prompt. `assets.generate_3d` doesn't enforce them, but Hunyuan respects scale cues — `2 meter tall wall section` produces a mesh that imports near 2m tall. Then verify with `summer_inspect_resource` and scale-correct in the editor if needed.
 
 ## Steps
 
@@ -76,13 +76,13 @@ Kit pieces only feel modular if they snap to a fixed grid. Pick the grid before
 Use the prop-style prompt with explicit dimensions:
 
 ```
-summer_generate_3d(
-  prompt="A 2 meter wide by 3 meter tall stone dungeon wall section, mossy granite blocks with iron reinforcements, torch-bracket sconce, weathered surface. Game asset, centered, stylized low-poly game art, warm torchlight palette, white background, isolated object.",
-  model="hunyuan",
-  options={ target_polycount: 1500 },
-  wait=true
-)
-summer_get_asset(assetId="<assetId>")
+assets.generate_3d({
+  prompt: "A 2 meter wide by 3 meter tall stone dungeon wall section, mossy granite blocks with iron reinforcements, torch-bracket sconce, weathered surface. Game asset, centered, stylized low-poly game art, warm torchlight palette, white background, isolated object.",
+  model: "hunyuan",
+  targetPolycount: 1500
+})
+jobs.wait({ jobId: "<job.id>", timeoutSeconds: 50 })   // again until finished; result.assetId
+assets.get({ assetId: "<assetId>" })
 summer_import_asset_by_id(assetId="<assetId>", path="res://assets/kits/dungeon/wall.glb")
 ```
 
@@ -90,19 +90,19 @@ Show the result to the user. **Iterate the anchor until approved** — every oth
 
 ### 3. Lock the suffix and generate the remaining pieces
 
-Once the user says "yes, that's the look", store the locked suffix and crank through the rest. Same model, same polycount, same `options`. Only the object description changes.
+Once the user says "yes, that's the look", store the locked suffix and crank through the rest. Same model, same `targetPolycount` scale. Only the object description changes. Start every piece first, then wait on the jobs: they run side by side.
 
 ```
 # Floor
-summer_generate_3d(prompt="A 2 by 2 meter square stone dungeon floor tile, mossy granite blocks with iron reinforcements, weathered surface. Game asset, centered, stylized low-poly game art, warm torchlight palette, white background, isolated object.", model="hunyuan", options={ target_polycount: 800 })
+assets.generate_3d({ prompt: "A 2 by 2 meter square stone dungeon floor tile, mossy granite blocks with iron reinforcements, weathered surface. Game asset, centered, stylized low-poly game art, warm torchlight palette, white background, isolated object.", model: "hunyuan", targetPolycount: 800 })
 
 # Pillar
-summer_generate_3d(prompt="A 3 meter tall stone dungeon pillar, square base, fluted shaft, mossy granite blocks with iron reinforcements, weathered surface. Game asset, ...", model="hunyuan", options={ target_polycount: 1500 })
+assets.generate_3d({ prompt: "A 3 meter tall stone dungeon pillar, square base, fluted shaft, mossy granite blocks with iron reinforcements, weathered surface. Game asset, ...", model: "hunyuan", targetPolycount: 1500 })
 
-# Door, Corner, Arch — same pattern.
+# Door, Corner, Arch — same pattern. Then jobs.wait on each job id.
 ```
 
-For each completed generation, capture the returned `assetId`, then import that
+For each finished job, capture the returned `assetId`, then import that
 exact ID with `summer_import_asset_by_id`. Do not search for generated pieces by
 name after creating them; exact IDs are the production path.
 
@@ -149,6 +149,10 @@ Check the AABB. If the wall is 1.85m tall when you asked for 3m, scale it in the
 - **Sci-fi kit (corridors, doors, terminals).** The style suffix becomes critical — `clean panels, soft cyan emissive trim, brushed metal, white background, isolated object`. Hard surfaces drift more than organic ones; review every piece.
 - **The user wants to add a piece later.** The locked suffix lives in the kit's notes (drop it in `assets/kits/dungeon/STYLE.md` if the user wants persistence). Reuse it verbatim for any addition — never re-derive.
 
+## Without Summer Engine
+
+In a session without Summer Engine tools (the assets profile; the `summer-assets` skill has the whole loop), do steps 1-3 and skip steps 4-5 (staging in a kit scene). Save the file where the person asked with `out` (the `summer-assets` skill says how), and tell them the path and format. Tell the person the grid from step 1, so they can check scale and pivots in their own engine.
+
 ## Fallback (no MCP)
 
 1. Run each prompt at the Summer dashboard (or Hunyuan / Trellis web UIs), keeping the locked suffix.

package/library/skills/environment-kit/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/environment-kit
 kind: skill
 version: 1.0.3
-summary: Generate a modular environment kit — wall pieces, floor tiles, pillars, doors, arches, corners — snap-together meshes sharing one visual style.
+summary: "Generate a modular environment kit: walls, floor tiles, pillars, doors, arches in one visual style."
 use_when:
   - generating a modular environment kit of snap-together pieces that form a level — dungeon kit, modular walls, interior pieces
   - building a dungeon, interior, or town kit from repeatable pieces that snap together in one style

package/library/skills/export-and-ship/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: export-and-ship
-description: "Assess and prepare a game export: inventory installed templates and targets, validate release assets and config, produce supported builds after approval."
+description: "Prepare a game export: check templates and targets, validate release assets, build after approval."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: deployment
@@ -295,7 +295,7 @@ For each build:
 
 Per platform, point the user at the correct upload path:
 
-- **summer.games:** `summer_export_game` writes the summer.games `.zip`; `summer_publish_build` uploads it to the game's store listing after the user confirms the exact game, file and version (needs `summer login --store`). If it answers `store_auth_refused`, the user uploads the `.zip` in Studio instead.
+- **summer.games:** `summer_export_game` writes the summer.games `.zip`; `store.upload_file` uploads it to the game's store listing after the user confirms the exact game, file and version (needs `summer login --store`; through `summer_call` when your client does not list it). If the store refuses this machine's sign-in, the user uploads the `.zip` in Studio instead. The `publish-your-game` skill takes it from there to `store.publish`.
   - Per platform, the store takes: iPhone, Android, macOS and Windows in the Summer apps = one summer.games bundle (`summer_export_game` `targets`, format `bundle`; no template, no signing; a game without a server targets `ios`/`android` only). Web = an HTML5 `.zip` on Summer's WebGPU Forward+ template (`targets:["web"]`; the project must render with Forward+ or Mobile). A macOS or Windows download for the store page = `targets:["macos"]` or `["windows"]` with format `download`. Download exports need the template: `summer_export_templates` `install` fetches it from Summer's CDN.
   - Hosted games: if `summer_export_game` fails with "… is in the source graph's authority_engine domain, which the client pack leaves out", an authority root in `source-domains.json` holds a file the client loads (often the composition `.tres`). Narrow that root to the server-only files, or move the shared file under a `shared` path, then export again. Every exporter message is in the `multiplayer-publish` skill's export-errors.md; the folder rules are in `multiplayer-project`.
   - Every summer.games bundle: export with the released Summer editor from the download page, never a development build, and export again after updating Summer. Otherwise its scripts can fail to compile on players' devices and the game opens to an empty window, though every upload check passes. `release-readiness` check 7 proves it.
@@ -358,7 +358,7 @@ Use this as a one-shot grep before any export:
 
 ## Collaborative protocol
 
-This skill produces release artifacts. Always ask before each build is invoked. Group platforms — "I'm about to build Windows + Mac + Linux release configs into `build/`. OK?". See `../../references/collaborative-protocol/collaborative-protocol.md`.
+This skill produces release artifacts. Always ask before each build is invoked. Group platforms — "I'm about to build Windows + Mac + Linux release configs into `build/`. OK?". See `summer_docs_read` id `reference/collaborative-protocol`.
 
 ## Want a working starter?
 
@@ -366,9 +366,9 @@ No template — this is a workflow. Each project's export config and store asset
 
 ## See also
 
-- `../../references/mcp-tools-reference/mcp-tools-reference.md` — full MCP tool list
-- `../../references/godot-version/godot-version.md` — Summer compatibility and
+- `summer_docs_read` id `reference/mcp-tools-reference` — full MCP tool list
+- `summer_docs_read` id `reference/godot-version` — Summer compatibility and
   export-template versioning
-- `../../references/collaborative-protocol/collaborative-protocol.md` — "May I write" pattern
+- `summer_docs_read` id `reference/collaborative-protocol` — "May I write" pattern
 - `headless-scripting` — the headless CLI pattern the export command follows
 - `tune-performance` — pre-ship performance pass

package/library/skills/export-and-ship/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/export-and-ship
 kind: skill
 version: 1.0.3
-summary: "Assess and prepare a game export: inventory installed templates and targets, validate release assets and config, produce supported builds after approval."
+summary: "Prepare a game export: check templates and targets, validate release assets, build after approval."
 use_when:
   - the user wants to assess or prepare a Summer game export — Steam, itch, HTML5, iOS, Android targets as available in the installed build
   - the user says 'publish my game', 'release it', or 'ship a build to players' — produce the build they will upload

package/library/skills/fabricating-assets/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fabricating-assets
-description: "Fabricate meshes with a bpy script in the user's own Blender (summer_fabricate_3d) — kits with exact dimensions, VFX meshes, post-processing generated models."
+description: "Fabricate meshes with a Blender script (summer_fabricate_3d): exact-size kits, VFX meshes, post-processing."
 ---
 
 # Fabricating Assets
@@ -22,10 +22,10 @@ Three facts shape every use:
 | Asset class | First route | Second | Why |
 |---|---|---|---|
 | Blockout / placeholder | `scene-scripting` primitives or CSG | fabricate | Must be instant and in-scene; no process spawn is justified |
-| Generic hard-surface prop ("a barrel") | `summer_search_assets` → `summer_import_asset` (`prop-model`) | `summer_generate_3d` | The free library plus `target_size` beats paid generation and a 2-minute wait, in a consistent style |
-| Bespoke prop ("the artifact from our GDD") | `summer_generate_3d` | fabricate | Image-to-3D is exactly what generation is for; fabricate when exact dimensions or parametric variants matter |
+| Generic hard-surface prop ("a barrel") | `assets.search` → `summer_import_asset` (`prop-model`) | `assets.generate_3d` | The free library plus `target_size` beats paid generation and a 2-minute wait, in a consistent style |
+| Bespoke prop ("the artifact from our GDD") | `assets.generate_3d` | fabricate | Image-to-3D is exactly what generation is for; fabricate when exact dimensions or parametric variants matter |
 | **Modular kit** (walls, pipes, fences, rails that snap) | **fabricate** | generated kit (`environment-kit`) | Generation cannot hold dimensions and style across 30 pieces; array + boolean + bevel + one material is the classic kit workflow |
-| Characters (rigged, animated) | `summer_generate_3d` (`character-model`) | library | Scripted organic modelling is the documented failure mode; fabrication has no path to competitive organics blind |
+| Characters (rigged, animated) | `assets.generate_3d` (`character-model`) | library | Scripted organic modelling is the documented failure mode; fabrication has no path to competitive organics blind |
 | Environments / terrain | in-engine terrain + library set dressing | generation for landmarks | Terrain wants interactive tools; dressing wants scatter |
 | Materials / textures / skies | library (`summer_import_hdri`, texture packs) | generation | Fabricate only to bake a procedural material to images |
 | **VFX meshes** (shatter pieces, trails, sweeps, LOD chains) | **fabricate** | in-engine | Bisect/fracture, curve sweeps, decimate are one-liners in bpy and absent in the engine |
@@ -146,7 +146,7 @@ Factory startup disables add-ons, so cell-fracture operators are not available.
 
 | `failure_reason` | What happened | Do |
 |---|---|---|
-| `engine_lacks_op` | This engine build predates FabricateMesh (nothing was sent) | Route to `summer_generate_3d`, `summer_search_assets` / `summer_import_asset`, or `summer_run_script` blockout geometry; tell the user an engine update enables fabrication |
+| `engine_lacks_op` | This engine build predates FabricateMesh (nothing was sent) | Route to `assets.generate_3d`, `assets.search` / `summer_import_asset`, or `summer_run_script` blockout geometry; tell the user an engine update enables fabrication |
 | `blender_not_found` | No usable Blender executable (see `tried`) | Relay the one-line decision above; never guess a path or install anything |
 | `blender_launch_failed` | The executable exists but did not start (permissions, broken install, wrong architecture) | Show the `error` and `output` tail to the user; a different `blender_path` or a reinstall is their call |
 | `script_error` | Your bpy raised (`traceback_tail`, `script_line`, `blender_version`) | Fix the named line against the reported version; `script_line` maps to your `source` |
@@ -169,14 +169,14 @@ Every failure leaves the project untouched except `import_failed` / `instantiate
 - **Output is unencumbered.** Meshes made with Blender belong to the user; the `.glb` in their project carries no Blender licence obligation.
 - **Scripts you write here are created on the user's machine and never distributed by Summer.** If you adapt a bpy snippet from elsewhere, respect its licence — prefer your own code or CC0 sources, and record the origin in `.summer/memory/decisions/` when it matters for the project.
 - **Trademark.** "Blender" is a trademark of the Blender Foundation. Refer to it factually as the dependency ("requires Blender"); never describe the feature as powered by, built on, or branded with Blender, and never use its logo. Summer's name for this capability is *mesh fabrication*.
-- Imported library assets keep their own licences (`summer_search_assets` results carry `licenseType`); fabrication does not change that.
+- Imported library assets keep their own licences (`assets.search` results carry `license`); fabrication does not change that.
 
 ## Red Flags — STOP
 
 | Red flag | Reality |
 |---|---|
 | Fabricating a barrel, a crate, a chair | Library first, generation second. Fabricate is for kits, VFX meshes, and post-processing |
-| Fabricating a character or creature | Scripted organic modelling is the documented failure mode; `summer_generate_3d` with rigging |
+| Fabricating a character or creature | Scripted organic modelling is the documented failure mode; `assets.generate_3d` with rigging |
 | A script that calls `export_scene.gltf`, saves, or quits | Breaks the contract; the bootstrap exports |
 | A material that is not a Principled BSDF | Exports grey; the `warnings` list said so |
 | Procedural roughness or normal maps left unbaked | Not baked automatically — set constants or bake in the script |

package/library/skills/fabricating-assets/resource.yaml

@@ -1,17 +1,17 @@
 id: skill/fabricating-assets
 kind: skill
 version: 1.0.0
-summary: Fabricate meshes with a bpy script in the user's own Blender (summer_fabricate_3d) — kits with exact dimensions, VFX meshes, post-processing generated models.
+summary: "Fabricate meshes with a Blender script (summer_fabricate_3d): exact-size kits, VFX meshes, post-processing."
 use_when:
   - writing a Blender Python (bpy) script for summer_fabricate_3d and deciding whether fabrication, generation, or the free library is the right route for an asset
   - a parametric hard-surface set with exact dimensions, booleans, bevels, and shared materials that must stay consistent across many pieces
   - VFX meshes — shatter fragments, curve sweeps, trails, LOD chains — or decimating, UV-unwrapping, and baking a generated model before it goes into the scene
   - a fabrication failed (blender_not_found, script_error, export_empty, import_failed, busy, timeout) and the result needs to be read correctly
 do_not_use_when:
-  - a generic prop — search the free library first (summer_search_assets, prop-model), then generate (summer_generate_3d)
+  - a generic prop — search the free library first (assets.search, prop-model), then generate (assets.generate_3d)
   - a character or any organic shape — character-model / organic-model; scripted organic modelling is the documented failure mode
   - a blockout or placeholder — scene-scripting primitives/CSG are instant and in-scene
-  - "the engine build lacks FabricateMesh (Summer Engine 0.5.66 or newer); older engines return engine_lacks_op — route to summer_generate_3d / summer_search_assets / summer_run_script instead"
+  - "the engine build lacks FabricateMesh (Summer Engine 0.5.66 or newer); older engines return engine_lacks_op — route to assets.generate_3d / assets.search / summer_run_script instead"
 facets:
   lifecycle:
     - build

package/library/skills/facial-and-lipsync/SKILL.md

@@ -1,21 +1,21 @@
 ---
 name: facial-and-lipsync
-description: "Make a character's mouth move with a voice-over — phoneme extraction from audio, viseme blendshape mapping, and emotional facial expressions."
+description: "Make a character's mouth move with a voice-over: phonemes, viseme blendshapes, facial expressions."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: animation
 user-invocable: false
-allowed-tools: Read Grep Edit Write summer_search_assets summer_inspect_resource summer_inspect_node summer_generate_audio summer_generate_motion summer_run_script summer_add_node summer_set_prop summer_set_resource_property summer_save_scene summer_get_script_errors
+allowed-tools: Read Grep Edit Write summer_assets_search summer_inspect_resource summer_inspect_node summer_assets_generate_audio summer_assets_generate_motion summer_run_script summer_add_node summer_set_prop summer_set_resource_property summer_save_scene summer_get_script_errors summer_jobs_wait summer_call
 paths: ["**/*.gd", "**/*.tscn", "**/*.tres"]
 ---
 
 # Facial Animation & Lipsync
 
-Half generative, half authored. The *generative* half: an audio file (TTS via `summer_generate_audio` with `capability: "text_to_speech"`) goes through a phoneme-extraction tool (Summer does NOT wrap one — you run it externally), out comes a viseme timeline — a list of `{ phoneme, start_time, duration }` triples. The *authored* half: the character's face mesh must have BlendShapes named for the standard viseme set, or the timeline has nothing to drive. Without both halves, you get a talking robot.
+Half generative, half authored. The *generative* half: an audio file (TTS via `assets.generate_audio` with `capability: "text_to_speech"`) goes through a phoneme-extraction tool (Summer does NOT wrap one — you run it externally), out comes a viseme timeline — a list of `{ phoneme, start_time, duration }` triples. The *authored* half: the character's face mesh must have BlendShapes named for the standard viseme set, or the timeline has nothing to drive. Without both halves, you get a talking robot.
 
 The pipeline:
 
-1. **Audio in** — `.wav`/`.mp3` from `summer_generate_audio({capability: "text_to_speech", ...})` or imported VO.
+1. **Audio in** — `.wav`/`.mp3` from `assets.generate_audio({ capability: "text_to_speech", ... })` or imported VO.
 2. **Phoneme extraction** — done OUTSIDE Summer. Recommended: **Rhubarb Lip Sync** (open source, widely used for game lipsync; outputs JSON with mouth-shape cues over time). Alternatives: gentle, allosaurus, or a Whisper-phoneme model on Replicate / Hugging Face. There is no `summer_*` MCP for this in the current engine.
 3. **Viseme mapping** — phonemes / Rhubarb cues → Oculus / Apple ARKit viseme set (15 standard shapes covers English).
 4. **BlendShape driver** — at runtime, lerp the mesh's BlendShape weights along the timeline, synced to audio playback.
@@ -32,7 +32,7 @@ The pipeline:
 ## When NOT to use this skill
 
 - Character has no face / no BlendShapes (helmeted soldier, robot, mascot). Hard-skip to body language via `generate-motion`.
-- The dialogue is written but not yet voiced — generate audio first via `summer_generate_audio({capability: "text_to_speech", ...})`. Lipsync without audio has nothing to sync to.
+- The dialogue is written but not yet voiced — generate audio first via `assets.generate_audio({ capability: "text_to_speech", ... })`. Lipsync without audio has nothing to sync to.
 - Pre-rendered cinematic from external DCC. Lipsync is in the rendered video, not the engine.
 
 ## Steps
@@ -47,27 +47,26 @@ Look for `mesh.blend_shape_count` > 0 and a list of names. An ARKit-52 head has
 
 If the head has zero BlendShapes, stop. Tell the user: "This head mesh has no BlendShapes — facial animation needs shape keys on the mesh. Options: use an emotional body-language overlay instead, author shape keys in Blender and re-import, or hand the character to a 3D artist." Don't proceed.
 
-Do **not** promise a `face_blendshapes` generation option. `summer_generate_3d`
-has no such parameter and nothing in the Summer generation pipeline handles one
-— `options` is an untyped passthrough, so a bogus key is accepted by the schema
-and then silently ignored by the backend. Regenerating will not add BlendShapes.
+Do **not** promise a `face_blendshapes` generation option. `assets.generate_3d`
+has no such field and nothing in the Summer generation pipeline handles one; a
+field the operation does not list does nothing. Regenerating will not add BlendShapes.
 Shape keys come from the mesh author (Blender / an ARKit-52 source mesh), not
 from a rig pass.
 
 ### 2. Get the audio
 
-If the user has VO already, use it. If not, generate via TTS. The `voiceId` is an ElevenLabs voice ID — the user has to pick one from the ElevenLabs voice library (https://elevenlabs.io/app/voice-library) or upload/clone their own. There is no "voice name" string; it's always an ID like `21m00Tcm4TlvDq8ikWAM` (Rachel) or a custom-cloned ID.
+If the user has VO already, use it. If not, generate via TTS. On the ElevenLabs models the `voiceId` must be one of Summer's game-cast voices (the `voice-line` skill lists them with their ids); any other id is refused. There is no "voice name" string; it's always an ID like `IKne3meq5aSn9XLyUdCD` (Charlie, the hero).
 
 ```
-summer_generate_audio({
+assets.generate_audio({
   capability: "text_to_speech",
   text: "Welcome to the village, traveler.",
-  voiceId: "<elevenlabs_voice_id>"
+  voiceId: "<cast voice id>"
 })
-// returns { jobId, ... } — poll with summer_check_job for the audio asset
+// answers at once with asset: { assetId, fileUrl, durationSeconds }
 ```
 
-If the user hasn't picked a voice yet, stop and ask: "Which ElevenLabs voice ID should I use? You can browse the library at elevenlabs.io/app/voice-library and copy the ID, or paste a custom-clone ID from your account."
+If the user hasn't picked a voice yet, stop and ask which cast voice fits the character (see `voice-line`).
 
 ### 3. Extract phonemes (the generative step — runs OUTSIDE Summer)
 
@@ -296,7 +295,7 @@ production speech recognition or photoreal lip sync.
 
 ## Handoff
 
-- For voice generation upstream, `voice-line` (which wraps `summer_generate_audio({capability: "text_to_speech", ...})`).
+- For voice generation upstream, `voice-line` (which wraps `assets.generate_audio({ capability: "text_to_speech", ... })`).
 - For dialogue scripts and conversation flow, `design-npc`.
 - For the AnimationTree this layer composes into, `animation-tree`.
 - For idle blinks, saccades, and head-tracking that complement lipsync, `procedural-animation`.

package/library/skills/facial-and-lipsync/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/facial-and-lipsync
 kind: skill
 version: 1.0.2
-summary: Make a character's mouth move with a voice-over — phoneme extraction from audio, viseme blendshape mapping, and emotional facial expressions.
+summary: "Make a character's mouth move with a voice-over: phonemes, viseme blendshapes, facial expressions."
 use_when:
   - the user has (or wants) a voice-over and needs the character's mouth to move with the words
   - adding emotional facial expressions (smile, frown, surprise)

package/library/skills/fps-controller/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: fps-controller
-description: "Production-quality first-person controller — WASD, mouse look, jump, coyote time, jump buffering, air control, and external-velocity handling."
+description: "First-person controller: WASD, mouse look, jump, coyote time, jump buffering, air control."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: character-controllers
 user-invocable: false
 template-id: template-3d-fps-old-school
-allowed-tools: Read Grep summer_get_scene_tree summer_add_node summer_set_prop summer_set_resource_property summer_input_map_bind summer_save_scene summer_get_script_errors
+allowed-tools: Read Grep summer_get_scene_tree summer_run_script summer_add_node summer_set_prop summer_set_resource_property summer_input_map_bind summer_save_scene summer_get_script_errors
 paths: ["**/*.gd", "**/*.tscn"]
 ---
 
@@ -32,52 +32,44 @@ The Head/Camera split is the standard: yaw rotates the body, pitch rotates only
 
 Always call `summer_get_scene_tree` before mutating. If `World/Player`, `World/PlayerOld`, or any existing CharacterBody3D is present, ASK the user how to proceed before adding nodes.
 
-### 2. Add the Player root
+### 2. Build the Player rig in one script
 
-```
-summer_add_node(scenePath="res://main.tscn", parent="./World", type="CharacterBody3D", name="Player")
-summer_set_prop(scenePath="res://main.tscn", path="./World/Player", key="position", value="Vector3(0, 1, 0)")
-```
-
-### 3. Add the collision shape and size it
+The body, its capsule, the head pivot and the camera are one `summer_run_script`
+call (one undo step):
 
 ```
-summer_add_node(scenePath="res://main.tscn", parent="./World/Player", type="CollisionShape3D", name="Collision")
-summer_set_prop(scenePath="res://main.tscn", path="./World/Player/Collision", key="shape", value="CapsuleShape3D")
-summer_set_resource_property(scenePath="res://main.tscn", nodePath="./World/Player/Collision", resourceProperty="shape", subProperty="radius", value="0.4")
-summer_set_resource_property(scenePath="res://main.tscn", nodePath="./World/Player/Collision", resourceProperty="shape", subProperty="height", value="1.8")
+summer_run_script(scenePath="res://main.tscn", source="""
+func run(ctx):
+    var player = ctx.add_node("CharacterBody3D", "Player", ctx.find("World"), {"position": Vector3(0, 1, 0)})
+    var capsule = CapsuleShape3D.new()
+    capsule.radius = 0.4
+    capsule.height = 1.8
+    ctx.add_node("CollisionShape3D", "Collision", player, {"shape": capsule, "position": Vector3(0, 0.9, 0)})
+    var head = ctx.add_node("Node3D", "Head", player, {"position": Vector3(0, 1.6, 0)})
+    ctx.add_node("Camera3D", "Camera", head)
+    ctx.save_scene()
+""")
 ```
 
-Two rules for these calls:
-
-- **`scenePath` is required** on `summer_add_node`, `summer_set_prop`,
-  `summer_set_resource_property` and `summer_save_scene`. Omit it and the call
-  never reaches the engine. (`summer_input_map_bind` is the exception — it edits
-  `project.godot`, not a scene, and takes only `name` + `events`.)
-- **This inline-resource sequence is the supported pattern, not a trap.**
-  `summer_set_prop` with a class-name string instantiates a scene-embedded
-  (`[sub_resource]`) resource, and `summer_set_resource_property` then reads that
-  property off the node and writes the sub-property straight onto it. Embedded
-  and external `.tres` resources take the same path. Structural failures are
-  explicit — `node not found`, `property is not a resource`, or `resource is
-  null` when the property was never assigned — but a bad value shape is silent
-  on current engines: a JSON object instead of an engine variant string, a
-  misspelled `key`/`subProperty`, or a wrong-typed value returns `ok:true` yet
-  no-ops or coerces destructively. Assign the resource first, pass class names
-  and `Vector3(...)`/`Color(...)` strings, and confirm in the saved `.tscn`,
-  never from `ok` alone.
-
-### 4. Add the Head pivot + Camera
+Eye height of 1.6 sits the camera right at the top of a 1.8-tall capsule (capsule center 0.9, plus 0.7 to the eye). Tweak per art style.
 
-```
-summer_add_node(scenePath="res://main.tscn", parent="./World/Player", type="Node3D", name="Head")
-summer_set_prop(scenePath="res://main.tscn", path="./World/Player/Head", key="position", value="Vector3(0, 1.6, 0)")
-summer_add_node(scenePath="res://main.tscn", parent="./World/Player/Head", type="Camera3D", name="Camera")
-```
+Two rules:
 
-Eye height of 1.6 sits the camera right at the top of a 1.8-tall capsule (capsule center 0.9, plus 0.7 to the eye). Tweak per art style.
+- **`scenePath` is required** on `summer_run_script` and on every scene tool
+  (`summer_set_prop`, `summer_set_resource_property`, `summer_save_scene`).
+  Omit it and the call never reaches the engine. (`summer_input_map_bind` is
+  the exception — it edits `project.godot`, not a scene, and takes only
+  `name` + `events`.)
+- **Build and size a shape before you assign it.** Tuning one value later is
+  one `summer_set_resource_property` call on the assigned resource. Structural
+  failures there are explicit — `node not found`, `property is not a resource`,
+  or `resource is null` when the property was never assigned — but a bad value
+  shape is silent on current engines: a JSON object instead of an engine
+  variant string, a misspelled `subProperty`, or a wrong-typed value returns
+  `ok:true` yet no-ops or coerces destructively. Pass `Vector3(...)`/`Color(...)`
+  strings and confirm in the saved `.tscn`, never from `ok` alone.
 
-### 5. InputMap actions
+### 3. InputMap actions
 
 ```
 summer_input_map_bind(name="move_forward", events=[{type:"key", key:"W"}])
@@ -88,7 +80,7 @@ summer_input_map_bind(name="jump",         events=[{type:"key", key:"Space"}])
 summer_input_map_bind(name="sprint",       events=[{type:"key", key:"Shift"}])
 ```
 
-### 6. Attach the controller script
+### 4. Attach the controller script
 
 Ask before writing: "May I create `scripts/player_controller.gd` and attach it to `./World/Player`?" Then `Write` the file with the skeleton in the next section, attach via inspector, and finish with `summer_save_scene(scenePath="res://main.tscn")` + `summer_get_script_errors(path="res://scripts/player_controller.gd")` (that tool checks one file and requires `path`).
 

package/library/skills/fps-controller/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/fps-controller
 kind: skill
 version: 1.0.4
-summary: Production-quality first-person controller — WASD, mouse look, jump, coyote time, jump buffering, air control, and external-velocity handling.
+summary: "First-person controller: WASD, mouse look, jump, coyote time, jump buffering, air control."
 use_when:
   - building an FPS, first-person movement, or a 3D character that walks, jumps, and reacts to external forces
   - a first-person prototype needs solid movement feel — coyote time, jump buffering, air control

package/library/skills/game-feel/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: game-feel
-description: "Add juice: hit-flash, trauma-based camera shake, and audio ducking wired so one hit fires all three — for games that feel flat or lack impact."
+description: "Add juice: hit-flash, trauma camera shake and audio ducking, one hit fires all three."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: visual-effects
@@ -117,7 +117,7 @@ func flash() -> void:
 
 **Tunable knobs:** `duration` 0.06–0.12s — under 0.06 reads as a flicker, over 0.12 looks slow. `emission_energy_multiplier` 1.5–3.0.
 
-> Note: `summer_set_prop(key="material_override", value="StandardMaterial3D")` creates an inline `StandardMaterial3D` sub_resource that `summer_set_resource_property(resourceProperty="material_override", subProperty="albedo_color", value="Color(r, g, b, a)")` then edits and `summer_save_scene` persists — so the inline route, the script above, and a saved `materials/flash.tres` are all valid. What breaks is the value *shape*: a JSON object instead of a Godot literal string, a misspelled `key`/`subProperty`, or a wrong-typed value returns `ok:true` yet silently no-ops or destructively coerces on current engines (dict → material cleared; dict → `Color(0,0,0,1)`; newer engines reject these with `unknown_property` / `bad_value_shape` / `type_mismatch`). Always pass class names and `Color(...)`/`Vector3(...)` strings, and confirm the result in the saved `.tscn` or a snapshot diff — never from `ok` alone. See `../../references/mcp-tools-reference/mcp-tools-reference.md`.
+> Note: `summer_set_prop(scenePath="res://levels/world.tscn", path="./World/Enemy/Mesh", key="material_override", value="StandardMaterial3D")` creates an inline `StandardMaterial3D` sub_resource that `summer_set_resource_property(scenePath="res://levels/world.tscn", nodePath="./World/Enemy/Mesh", resourceProperty="material_override", subProperty="albedo_color", value="Color(r, g, b, a)")` then edits and `summer_save_scene` persists — so the inline route, the script above, and a saved `materials/flash.tres` are all valid. What breaks is the value *shape*: a JSON object instead of a Godot literal string, a misspelled `key`/`subProperty`, or a wrong-typed value returns `ok:true` yet silently no-ops or destructively coerces on current engines (dict → material cleared; dict → `Color(0,0,0,1)`; newer engines reject these with `unknown_property` / `bad_value_shape` / `type_mismatch`). Always pass class names and `Color(...)`/`Vector3(...)` strings, and confirm the result in the saved `.tscn` or a snapshot diff — never from `ok` alone. See `summer_docs_read` id `reference/mcp-tools-reference`.
 
 ## Step 5 — Install Section 2 (Trauma Camera Shake)
 
@@ -370,12 +370,12 @@ Tune one knob at a time:
 | Equal pitch/yaw shake | `yaw_factor ≤ 0.5` | Eyes are sensitive to vertical motion; equal axes feel mechanical |
 | `Engine.time_scale` for every hit | Reserve hit-stop for big events only (boss hits, deaths) | Time-scale dips on every hit feel laggy, not impactful |
 | A JSON object (or a misspelled key) as the `summer_set_prop` / `summer_set_resource_property` value — e.g. `value={"type": "StandardMaterial3D", ...}` through `summer_batch`, which forwards ops verbatim | `value="StandardMaterial3D"` to create the inline material, then `summer_set_resource_property(... value="Color(r, g, b, a)")` per field; confirm in the saved `.tscn` | Current engines return `ok:true` and silently no-op or coerce destructively — dict → material cleared, dict → `Color(0,0,0,1)`. The inline sub_resource itself is fine |
-| `summer_set_prop(key="groups", value='["player_camera"]')` | `add_to_group(&"player_camera")` in `_ready()`, or a `groups = [...]` line in the `.tscn` | `Node` has no `groups` property, and `summer_set_prop` takes only string/number/boolean — never an array |
+| `summer_set_prop(scenePath="res://levels/world.tscn", path="./World/Player/Camera3D", key="groups", value='["player_camera"]')` | `add_to_group(&"player_camera")` in `_ready()`, or a `groups = [...]` line in the `.tscn` | `Node` has no `groups` property, and `summer_set_prop` takes only string/number/boolean — never an array |
 | `BaseMaterial3D.new()` | `StandardMaterial3D.new()` | `BaseMaterial3D` is abstract; constructing it is a parse error that kills the whole script |
 
 ## Collaborative protocol
 
-This skill writes 3 GDScript files and adds 1 node + 1 autoload entry. Always ask before each section is applied. Group related writes into one ask: "I'm about to add HitFlash + CameraShake + AudioDucker autoload, wire one signal. OK?" See `../../references/collaborative-protocol/collaborative-protocol.md`.
+This skill writes 3 GDScript files and adds 1 node + 1 autoload entry. Always ask before each section is applied. Group related writes into one ask: "I'm about to add HitFlash + CameraShake + AudioDucker autoload, wire one signal. OK?" See `summer_docs_read` id `reference/collaborative-protocol`.
 
 ## When NOT to use this skill
 
@@ -386,11 +386,11 @@ This skill writes 3 GDScript files and adds 1 node + 1 autoload entry. Always as
 
 ## See also
 
-- `../../references/mcp-tools-reference/mcp-tools-reference.md` — full MCP tool list, especially `summer_set_resource_property` on inline sub_resources and which failures are loud vs. silent
-- `../../references/godot-version/godot-version.md` — Summer compatibility and
+- `summer_docs_read` id `reference/mcp-tools-reference` — full MCP tool list, especially `summer_set_resource_property` on inline sub_resources and which failures are loud vs. silent
+- `summer_docs_read` id `reference/godot-version` — Summer compatibility and
   version-sensitive API notes
-- `../../references/collaborative-protocol/collaborative-protocol.md` — "May I write" pattern
-- `../../references/gd-style/gd-style.md` — typed GDScript conventions
+- `summer_docs_read` id `reference/collaborative-protocol` — "May I write" pattern
+- `summer_docs_read` id `reference/gd-style` — typed GDScript conventions
 - `audio-direction` — bus layout setup (prerequisite for ducking)
 - `vfx-hit-spark` — particles to layer on top of the trio
 - `debugging-game-feel` — when the trio is installed and it still feels wrong

package/library/skills/game-feel/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/game-feel
 kind: skill
 version: 1.0.2
-summary: "Add juice: hit-flash, trauma-based camera shake, and audio ducking wired so one hit fires all three — for games that feel flat or lack impact."
+summary: "Add juice: hit-flash, trauma camera shake and audio ducking, one hit fires all three."
 use_when:
   - a Summer game feels flat, lacks impact, needs juice or punch
   - the user asks for hit feedback, screen shake, camera shake, or audio ducking

package/library/skills/gameskill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gameskill
-description: "Capture what a game-dev session just learned as a reusable skill (project, user or Summer library) so the next session starts smarter."
+description: "Capture what a game-dev session learned as a reusable skill (project, user or Summer library) for next time."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: workflow
@@ -17,7 +17,7 @@ Summer resolves skills in this order: the game project, then the user's agent sk
 
 1. **The game project** (default). Write `SKILL.md` into the project-scoped skills directory of the agent you are running in: `.claude/skills/<slug>/` for Claude Code, `.agents/skills/<slug>/` for Codex, Cursor, Devin Desktop and the other agents that read the shared folder. `summer skills install --scope project` shows the exact path for the current agent. Commit it with the game.
 2. **The user's agent skills directory** when the lesson applies to every project on this machine (`~/.claude/skills/<slug>/`, `~/.agents/skills/<slug>/`). Do not edit skills that Summer installed there; they are overwritten on the next `summer setup`.
-3. **The Summer library** when the lesson is general enough for every Summer user. Only possible inside a checkout of the `summerengine/summer` repository: add `library/skills/<slug>/resource.yaml` and `library/skills/<slug>/SKILL.md` (flat slugs, no category folders), then run `npm run generate:registry` and `npm run validate:library`. Everything under `registry/generated/` and every plugin manifest is generated from `library/`; never hand-edit them. Outside that checkout, send the lesson through `summer_library_feedback` (or `summer tool library-feedback`) with the id of the closest existing skill so the maintainers can fold it in.
+3. **The Summer library** when the lesson is general enough for every Summer user. Only possible inside a checkout of the `summerengine/summer` repository: add `library/skills/<slug>/resource.yaml` and `library/skills/<slug>/SKILL.md` (flat slugs, no category folders), then run `npm run generate:registry` and `npm run validate:library`. Everything under `registry/generated/` and every plugin manifest is generated from `library/`; never hand-edit them. Outside that checkout, send the lesson through `summer_call` `{"op":"docs.feedback"}` (or `summer tool library-feedback`) with the id of the closest existing skill so the maintainers can fold it in.
 
 Read the current project as ground truth. Working code from the real project beats invented examples.
 
@@ -25,7 +25,7 @@ Read the current project as ground truth. Working code from the real project bea
 
 1. One short sentence to the user: "Capturing learnings from this session into a skill." No plan dump.
 
-2. Probe. Check which skills directories exist for this agent and project, and search the bundled library first (`summer_search_library "<topic>"`, or `summer skills list`) so you extend an existing skill instead of duplicating it.
+2. Probe. Check which skills directories exist for this agent and project, and search the bundled library first (`summer_docs_search "<topic>"`, or `summer skills list`) so you extend an existing skill instead of duplicating it.
 
 3. Recap the session. Pull out learnings that are non-obvious AND general, things a future agent could not derive from reading the codebase. Examples that count:
    - A working shader (the actual code)
@@ -36,7 +36,7 @@ Read the current project as ground truth. Working code from the real project bea
    - A spawning, AI or enemy pattern that worked
    - A performance fix with measured before and after
    - An asset workflow that beat the alternatives
-   - A Summer tool that steered you wrong: report that with `summer_library_feedback` on the tool's id, in addition to any skill
+   - A Summer tool that steered you wrong: report that with `summer_call` `{"op":"docs.feedback"}` on the tool's id, in addition to any skill
 
    Examples that do NOT count: one-off code with no general lesson, things already documented in an existing skill or the project's agent instructions, personal preferences without reasoning, anything manufactured to fill space.
 

package/library/skills/gameskill/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/gameskill
 kind: skill
 version: 1.0.2
-summary: Capture what a game-dev session just learned as a reusable skill (project, user or Summer library) so the next session starts smarter.
+summary: "Capture what a game-dev session learned as a reusable skill (project, user or Summer library) for next time."
 use_when:
   - finishing a game-development session with learnings worth capturing as a reusable skill
   - a session found a technique, workaround, or convention worth reusing across Summer sessions

package/library/skills/gdscript-patterns/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gdscript-patterns
-description: "GDScript conventions — type hints, signals, exports, onready, lifecycle methods, get_node vs $NodePath, naming."
+description: "GDScript conventions: type hints, signals, exports, onready, lifecycle methods, node paths, naming."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: scripting-patterns

package/library/skills/gdscript-patterns/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/gdscript-patterns
 kind: skill
 version: 1.0.3
-summary: GDScript conventions — type hints, signals, exports, onready, lifecycle methods, get_node vs $NodePath, naming.
+summary: "GDScript conventions: type hints, signals, exports, onready, lifecycle methods, node paths, naming."
 use_when:
   - writing or refactoring GDScript — type hints, signals, exports, onready, lifecycle methods, naming conventions
   - reviewing GDScript for idiomatic signals, exports, @onready usage, node references, and naming