summer-engine 3.8.0 → 4.2.0

package/library/skills/audio-direction/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: audio-direction
-description: "Define the game's sonic identity — music style, instruments, SFX vocabulary, dynamic music plan — output as an audio bible at .summer/audio-bible.md."
+description: "Define the game's sound (music style, SFX vocabulary, dynamic music) as .summer/audio-bible.md."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: audio
 user-invocable: true
-allowed-tools: Read Grep Glob Write Edit summer_get_project_context summer_get_scene_tree summer_inspect_node summer_add_node summer_project_setting summer_generate_audio
+allowed-tools: Read Grep Glob Write Edit summer_get_project_context summer_get_scene_tree summer_inspect_node summer_add_node summer_project_setting summer_assets_generate_audio summer_call
 paths: [".summer/**", "project.godot", "**/*.tscn", "audio/**"]
 ---
 
@@ -206,9 +206,9 @@ Ask:
 If the user wants to start generating, propose 3-5 SFX seeds aligned with the vocabulary. These are starting points, not finals. Generate them with the `sound-effect` skill: the first sound effect in a chat starts with its question (three versions from three models, picked by ear in Summer Studio), and its prompt shape is the one that tested well.
 
 ```
-summer_generate_audio(capability="sound_effects", text="Foley one-shot: a fingertip taps a small wooden button, soft woody click, no tail, close-mic, dry, no reverb, no music, no voices.", durationSeconds=0.5)
-summer_generate_audio(capability="sound_effects", text="Foley one-shot: a small gold coin drops onto a wooden table, bright metallic ting with a short ring, close-mic, dry, no music, no voices.", durationSeconds=0.5)
-summer_generate_audio(capability="sound_effects", text="Foley one-shot: a fist hits a padded leather vest, low-mid thump, no tail, close-mic, dry, no reverb, no music, no voices.", durationSeconds=0.5)
+assets.generate_audio({ capability: "sound_effects", text: "Foley one-shot: a fingertip taps a small wooden button, soft woody click, no tail, close-mic, dry, no reverb, no music, no voices.", durationSeconds: 0.5 })
+assets.generate_audio({ capability: "sound_effects", text: "Foley one-shot: a small gold coin drops onto a wooden table, bright metallic ting with a short ring, close-mic, dry, no music, no voices.", durationSeconds: 0.5 })
+assets.generate_audio({ capability: "sound_effects", text: "Foley one-shot: a fist hits a padded leather vest, low-mid thump, no tail, close-mic, dry, no reverb, no music, no voices.", durationSeconds: 0.5 })
 ```
 
 `capability` is required; `sound_effects` reads from `text` (not `prompt`), and the length argument is `durationSeconds` (not `duration`) with a floor of 0.5 s (1 s for Stable Audio 3 SFX). Leave out `modelId` so the person's approved default model runs. Ask for the character you want inside the text and let the player only use the front of the clip — you cannot request 80 ms.
@@ -239,11 +239,11 @@ End with:
 | Pure sine "ding" for pickup | Reads as cheap mobile game. Use a major-third interval with character. |
 | Same footstep sample for all surfaces | Players hear footsteps constantly; material-aware steps carry much of the perceived audio quality. |
 | No master ceiling / true peak | Audio clips on console builds without `-1 dBTP` ceiling. Always set it. |
-| Assuming SetResourceProperty fails silently on inline sub_resources | It does not — inline targets work, and the structural failures (`node not found`, `property is not a resource`, `resource is null`) are explicit errors. What *is* silent on current engines is a bad value shape: a JSON object instead of an engine literal string, a misspelled `subProperty`, or a wrong-typed value returns `ok:true` yet no-ops or coerces destructively. Pass class names and literal strings, and confirm in the saved `.tres`/`.tscn`, never from `ok` alone. See `../../references/mcp-tools-reference/mcp-tools-reference.md`. |
+| Assuming SetResourceProperty fails silently on inline sub_resources | It does not — inline targets work, and the structural failures (`node not found`, `property is not a resource`, `resource is null`) are explicit errors. What *is* silent on current engines is a bad value shape: a JSON object instead of an engine literal string, a misspelled `subProperty`, or a wrong-typed value returns `ok:true` yet no-ops or coerces destructively. Pass class names and literal strings, and confirm in the saved `.tres`/`.tscn`, never from `ok` alone. See `summer_docs_read` id `reference/mcp-tools-reference`. |
 
 ## Collaborative protocol
 
-This skill writes one bible (`.summer/audio-bible.md`), creates a bus layout (`audio/default_bus_layout.tres`), modifies `project.godot`, and may generate audio (metered). Always ask before writing or generating. See `../../references/collaborative-protocol/collaborative-protocol.md`.
+This skill writes one bible (`.summer/audio-bible.md`), creates a bus layout (`audio/default_bus_layout.tres`), modifies `project.godot`, and may generate audio (metered). Always ask before writing or generating. See `summer_docs_read` id `reference/collaborative-protocol`.
 
 ## Want a working starter?
 
@@ -251,11 +251,27 @@ No template — this is a workflow that produces the bible the rest of the proje
 
 ## See also
 
-- `../../references/collaborative-protocol/collaborative-protocol.md`
-- `../../references/godot-version/godot-version.md` — Summer compatibility and
+- `summer_docs_read` id `reference/collaborative-protocol`
+- `summer_docs_read` id `reference/godot-version` — Summer compatibility and
   version-sensitive audio API notes
-- `../../references/mcp-tools-reference/mcp-tools-reference.md`
+- `summer_docs_read` id `reference/mcp-tools-reference`
 - `brainstorm-game` — produces the brief that anchors the bible
 - `art-direction` — the visual counterpart; audio must rhyme with it
 - `adaptive-music` — implements the dynamic music plan
 - `sound-effect`, `music-track`, `ambient-bed`, `voice-line` — generate the audio the bible describes
+
+<!-- shell-commands: generated from the operation catalog by npm run generate:registry; do not edit by hand -->
+## From a shell
+
+No Summer MCP tools in this session? Run each one as a command; when `summer --version` is missing or below 4.0, use `npx -y summer-engine@latest` in place of `summer`. Fields are flags in kebab-case (`--scene-path res://main.tscn`) or one `--input '<json>'`, and `summer ops describe <op>` prints the exact input. The `summer-cli` skill has the rest.
+
+| In this skill | Command |
+|---|---|
+| `summer_assets_generate_audio` | `summer assets generate-audio` |
+| `summer_docs_read` | `summer docs read` |
+| `summer_add_node` | `summer engine add-node` |
+| `summer_get_project_context` | `summer engine get-project-context` |
+| `summer_get_scene_tree` | `summer engine get-scene-tree` |
+| `summer_inspect_node` | `summer engine inspect-node` |
+| `summer_project_setting` | `summer engine project-setting` |
+<!-- /shell-commands -->

package/library/skills/audio-direction/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/audio-direction
 kind: skill
 version: 1.0.7
-summary: Define the game's sonic identity — music style, instruments, SFX vocabulary, dynamic music plan — output as an audio bible at .summer/audio-bible.md.
+summary: "Define the game's sound (music style, SFX vocabulary, dynamic music) as .summer/audio-bible.md."
 use_when:
   - defining the sonic identity — music style, instruments, SFX vocabulary, dynamic music plan
   - starting audio work with no audio bible, or soundtrack and SFX requests keep drifting in style

package/library/skills/auto-fire-targeting/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: auto-fire-targeting
-description: "Design or fix auto-fire weapon targeting (survivors, top-down ARPG, tower defense) — the pending-damage pattern that prevents over-commit and overkill."
+description: "Fix auto-fire targeting (survivors, ARPG, tower defense) with pending damage to stop overkill."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: gameplay-mechanics
@@ -194,3 +194,17 @@ Do **not** reach for `SimulateInput` here. It is only reachable from the
 in-editor chat bridge; an MCP or CLI caller gets
 `{ok: false, failure_reason: "unsupported_transport"}` back. Drive input from
 inside the probe with `press()` / `key()` instead.
+
+<!-- shell-commands: generated from the operation catalog by npm run generate:registry; do not edit by hand -->
+## From a shell
+
+No Summer MCP tools in this session? Run each one as a command; when `summer --version` is missing or below 4.0, use `npx -y summer-engine@latest` in place of `summer`. Fields are flags in kebab-case (`--scene-path res://main.tscn`) or one `--input '<json>'`, and `summer ops describe <op>` prints the exact input. The `summer-cli` skill has the rest.
+
+| In this skill | Command |
+|---|---|
+| `summer_batch` | `summer engine batch` |
+| `summer_game_probe` | `summer engine game-probe` |
+| `summer_get_diagnostics` | `summer engine get-diagnostics` |
+| `summer_inspect_node` | `summer engine inspect-node` |
+| `summer_inspect_runtime_node` | `summer engine inspect-runtime-node` |
+<!-- /shell-commands -->

package/library/skills/auto-fire-targeting/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/auto-fire-targeting
 kind: skill
 version: 1.0.0
-summary: Design or fix auto-fire weapon targeting (survivors, top-down ARPG, tower defense) — the pending-damage pattern that prevents over-commit and overkill.
+summary: "Fix auto-fire targeting (survivors, ARPG, tower defense) with pending damage to stop overkill."
 use_when:
   - designing or fixing the targeting system for an auto-fire weapon (survivors-genre, top-down ARPG, tower-defense)
   - bullet flight time longer than fire rate causes wasted bullets or overkill

package/library/skills/bounded-engine-runs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bounded-engine-runs
-description: "Run Summer headless or offscreen safely from an agent: time limits, one engine per project, muted runs, import passes, tests that fail on crashes."
+description: "Run Summer headless or offscreen safely: time limits, one engine per project, import passes, crash checks."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: workflow

package/library/skills/bounded-engine-runs/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/bounded-engine-runs
 kind: skill
 version: 1.0.0
-summary: "Run Summer headless or offscreen safely from an agent: time limits, one engine per project, muted runs, import passes, tests that fail on crashes."
+summary: "Run Summer headless or offscreen safely: time limits, one engine per project, import passes, crash checks."
 use_when:
   - running the engine from a shell or agent for tests, imports, captures or bots
   - several agents or processes share one project

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

@@ -1,6 +1,6 @@
 ---
 name: brainstorm-game
-description: "Turn a vague idea into a buildable plan — genre, scope, core loop, mechanics, art direction — written as a 1-page brief to .summer/GameSoul.md."
+description: "Turn a vague game idea into a 1-page brief (genre, scope, core loop, mechanics) in .summer/GameSoul.md."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: scene-and-project
@@ -206,3 +206,16 @@ No template — this is a workflow that produces the brief that drives template
 - `art-direction` — turn the one-phrase look into a full bible
 - `audio-direction` — sonic identity
 - `make-game` — scaffold the project once the brief is locked
+
+<!-- shell-commands: generated from the operation catalog by npm run generate:registry; do not edit by hand -->
+## From a shell
+
+No Summer MCP tools in this session? Run each one as a command; when `summer --version` is missing or below 4.0, use `npx -y summer-engine@latest` in place of `summer`. Fields are flags in kebab-case (`--scene-path res://main.tscn`) or one `--input '<json>'`, and `summer ops describe <op>` prints the exact input. The `summer-cli` skill has the rest.
+
+| In this skill | Command |
+|---|---|
+| `summer_get_project_context` | `summer engine get-project-context` |
+| `summer_get_scene_tree` | `summer engine get-scene-tree` |
+| `summer_read_file` | `summer engine read-file` |
+| `summer_write_file` | `summer engine write-file` |
+<!-- /shell-commands -->

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

@@ -1,7 +1,7 @@
 id: skill/brainstorm-game
 kind: skill
 version: 1.0.3
-summary: Turn a vague idea into a buildable plan — genre, scope, core loop, mechanics, art direction — written as a 1-page brief to .summer/GameSoul.md.
+summary: "Turn a vague game idea into a 1-page brief (genre, scope, core loop, mechanics) in .summer/GameSoul.md."
 use_when:
   - the user wants help deciding what game to make, scoping a new project, or turning a vague idea into a buildable plan
   - the user has a genre, theme, or one-line pitch but no core loop, scope, or brief yet

package/library/skills/brainstorming/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: brainstorming
-description: "Explore user intent, requirements, and design before implementation — must run before any creative work: features, components, mechanics, behavior."
+description: "Explore user intent, requirements and design before any creative work: features, mechanics, behavior."
 ---
 
 # Brainstorming Ideas Into Designs

package/library/skills/brainstorming/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/brainstorming
 kind: skill
 version: 1.0.3
-summary: "Explore user intent, requirements, and design before implementation — must run before any creative work: features, components, mechanics, behavior."
+summary: "Explore user intent, requirements and design before any creative work: features, mechanics, behavior."
 use_when:
   - starting creative work — designing a game, picking a mechanic, building features or components, modifying behavior
   - a request is ambiguous about goals or constraints and work would otherwise start on guesses

package/library/skills/browse-templates/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: browse-templates
-description: "List available Summer Engine project templates, present the choices, and create a project from the chosen one via summer create."
+description: "List Summer Engine project templates, present the choices, and create a project from the chosen one."
 license: MIT
 compatibility: [Cursor, Claude Code, Codex, Windsurf, Gemini, OpenCode]
 category: scene-and-project
@@ -103,3 +103,13 @@ Once the project is created and running, hand off cleanly. The next skill that f
 - 2D platformer → `design-mechanic` for the platforming feel, then `design-level`.
 
 Don't auto-fire the next skill — wait for the user to say what they want to change first.
+
+<!-- shell-commands: generated from the operation catalog by npm run generate:registry; do not edit by hand -->
+## From a shell
+
+No Summer MCP tools in this session? Run each one as a command; when `summer --version` is missing or below 4.0, use `npx -y summer-engine@latest` in place of `summer`. Fields are flags in kebab-case (`--scene-path res://main.tscn`) or one `--input '<json>'`, and `summer ops describe <op>` prints the exact input. The `summer-cli` skill has the rest.
+
+| In this skill | Command |
+|---|---|
+| `summer_get_project_context` | `summer engine get-project-context` |
+<!-- /shell-commands -->

package/library/skills/browse-templates/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/browse-templates
 kind: skill
 version: 1.0.5
-summary: List available Summer Engine project templates, present the choices, and create a project from the chosen one via summer create.
+summary: "List Summer Engine project templates, present the choices, and create a project from the chosen one."
 use_when:
   - the user wants to see available Summer Engine project templates, start from an existing template, or asks what templates exist
   - picking a starting point and unsure which starter templates already exist

package/library/skills/camera-rigs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: camera-rigs
-description: "Camera rigs for 2D and 3D: Camera2D follow with limits, first-person head camera, SpringArm3D third-person, orthographic top-down, FOV guidance."
+description: "Camera rigs: Camera2D follow with limits, first-person head, SpringArm3D third-person, top-down, FOV."
 license: MIT
 compatibility: [Cursor, Claude Code, Codex, Windsurf, Gemini, OpenCode]
 category: scene-and-project
@@ -55,7 +55,7 @@ Same as above minus the platformer edge-lock urgency. Zoom out to show the field
 ## 3D first-person camera
 
 Camera is a child of a `Head` node on the player. Body yaws, Head pitches. See
-the `character-movement` skill (its `../character-movement/references/movement-3d.md`) or
+the `character-movement` skill (its 3D movement reference: `summer_docs_read` id `skill/character-movement/references/movement-3d.md`) or
 `fps-controller` for the look script. FOV 70-75, near 0.05.
 
 ```
@@ -126,3 +126,23 @@ camera, not the game's.
 | Shows past level edge | No 2D limits | Set `limit_*` to level bounds |
 | Wrong facing (3D) | rotation.y off | y: 0 = forward, 180 = backward |
 | Everything tiny/huge (ortho) | `size` wrong | Tune `size`, not `position.y` |
+
+<!-- shell-commands: generated from the operation catalog by npm run generate:registry; do not edit by hand -->
+## From a shell
+
+No Summer MCP tools in this session? Run each one as a command; when `summer --version` is missing or below 4.0, use `npx -y summer-engine@latest` in place of `summer`. Fields are flags in kebab-case (`--scene-path res://main.tscn`) or one `--input '<json>'`, and `summer ops describe <op>` prints the exact input. The `summer-cli` skill has the rest.
+
+| In this skill | Command |
+|---|---|
+| `summer_docs_read` | `summer docs read` |
+| `summer_add_node` | `summer engine add-node` |
+| `summer_batch` | `summer engine batch` |
+| `summer_get_diagnostics` | `summer engine get-diagnostics` |
+| `summer_get_scene_tree` | `summer engine get-scene-tree` |
+| `summer_inspect_node` | `summer engine inspect-node` |
+| `summer_play` | `summer engine play` |
+| `summer_save_scene` | `summer engine save-scene` |
+| `summer_screenshot` | `summer engine screenshot` |
+| `summer_set_prop` | `summer engine set-prop` |
+| `summer_stop` | `summer engine stop` |
+<!-- /shell-commands -->

package/library/skills/camera-rigs/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/camera-rigs
 kind: skill
 version: 1.0.0
-summary: "Camera rigs for 2D and 3D: Camera2D follow with limits, first-person head camera, SpringArm3D third-person, orthographic top-down, FOV guidance."
+summary: "Camera rigs: Camera2D follow with limits, first-person head, SpringArm3D third-person, top-down, FOV."
 use_when:
   - black screen on play, or the camera shows past the level edge
   - jerky camera follow, wrong FOV, or the third-person camera clips into walls

package/library/skills/celeste-momentum-platforming/resource.yaml

@@ -31,3 +31,4 @@ source: official
 license: MIT
 status: preview
 recommended: false
+bundled: false

package/library/skills/character-animation-wiring/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: character-animation-wiring
-description: "Wire a rigged, animated character end to end — inspect real clips and bones, locomotion state machine, method-track events, poses, blend shapes, root motion."
+description: "Wire a rigged character end to end: real clips and bones, locomotion states, method tracks, root motion."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: animation
@@ -11,7 +11,7 @@ paths: ["**/*.gd", "**/*.tscn", "**/*.glb"]
 
 # Character Animation Wiring — Rigged GLB to Living Character
 
-The game-critical path: a rigged, animated character lands in the scene — from `summer_generate_3d({options:{rig:true}})` + `summer_generate_motion`, or an imported GLB — and nothing moves yet. This skill wires it end to end: inspect what actually arrived, build locomotion, fire gameplay events off animation frames, add poses and head tracking, key the face, and handle root motion. Then **prove it in a playtest** — a wired tree that was never played is a claim, not a result.
+The game-critical path: a rigged, animated character lands in the scene — from `assets.generate_3d({ ..., rig: true })` + `assets.generate_motion`, or an imported GLB — and nothing moves yet. This skill wires it end to end: inspect what actually arrived, build locomotion, fire gameplay events off animation frames, add poses and head tracking, key the face, and handle root motion. Then **prove it in a playtest** — a wired tree that was never played is a claim, not a result.
 
 Two lanes throughout:
 
@@ -85,7 +85,7 @@ Read the reports. Every later step quotes these exact strings. If the clip list
 ```gdscript
 func run(ctx):
     var character = ctx.find("Goblin")
-    var tree := ctx.anim_state_machine(character, {
+    var tree = ctx.anim_state_machine(character, {
         "states": {"idle": "idle", "walk": "walk", "run": "run"},
         "transitions": [
             ["idle", "walk", {"blend_s": 0.2}],
@@ -150,7 +150,7 @@ func run(ctx):
 Head tracking — one call creates the owned `LookAtModifier3D` under the skeleton:
 
 ```gdscript
-    var mod := ctx.look_at_modifier(skel, ctx.find("Player"), {"bone_name": "Head"})
+    var mod = ctx.look_at_modifier(skel, ctx.find("Player"), {"bone_name": "Head"})
 ```
 
 Unknown props land in `prop_warnings` — read them. Angle limits, influence fade-out by distance, and spine-chain distribution are the difference between alive and possessed: tune per `procedural-animation` (A1/A2).
@@ -247,3 +247,27 @@ Method tracks raw: `anim.add_track(Animation.TYPE_METHOD)` + `track_set_path(idx
 
 - `scene-scripting` — the ctx stdlib contract, owner rules, budgets, undo/rollback.
 - `verifying-scenes` — snapshot/diff/screenshot/runtime-read discipline this skill leans on.
+
+<!-- shell-commands: generated from the operation catalog by npm run generate:registry; do not edit by hand -->
+## From a shell
+
+No Summer MCP tools in this session? Run each one as a command; when `summer --version` is missing or below 4.0, use `npx -y summer-engine@latest` in place of `summer`. Fields are flags in kebab-case (`--scene-path res://main.tscn`) or one `--input '<json>'`, and `summer ops describe <op>` prints the exact input. The `summer-cli` skill has the rest.
+
+| In this skill | Command |
+|---|---|
+| `assets.generate_3d` | `summer assets generate-3d` |
+| `assets.generate_motion` | `summer assets generate-motion` |
+| `summer_api_docs` | `summer docs engine-api` |
+| `summer_get_runtime_tree` | `summer engine get-runtime-tree` |
+| `summer_get_scene_tree` | `summer engine get-scene-tree` |
+| `summer_get_script_errors` | `summer engine get-script-errors` |
+| `summer_inspect_node` | `summer engine inspect-node` |
+| `summer_inspect_runtime_node` | `summer engine inspect-runtime-node` |
+| `summer_play` | `summer engine play` |
+| `summer_run_script` | `summer engine run-script` |
+| `summer_save_scene` | `summer engine save-scene` |
+| `summer_screenshot` | `summer engine screenshot` |
+| `summer_snapshot_diff` | `summer engine snapshot-diff` |
+| `summer_stop` | `summer engine stop` |
+| `summer_world_snapshot` | `summer engine world-snapshot` |
+<!-- /shell-commands -->

package/library/skills/character-animation-wiring/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/character-animation-wiring
 kind: skill
 version: 1.0.1
-summary: Wire a rigged, animated character end to end — inspect real clips and bones, locomotion state machine, method-track events, poses, blend shapes, root motion.
+summary: "Wire a rigged character end to end: real clips and bones, locomotion states, method tracks, root motion."
 use_when:
   - a rigged GLB or Meshy rig with generated clips is in the scene and needs idle/walk/run wiring with blend times
   - footstep or attack-frame events, head tracking, still poses, blend-shape facial keys, or root motion must be hooked up

package/library/skills/character-model/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: character-model
-description: "Generate a rigged humanoid — player, NPC, enemy, boss — via T-pose reference, user-gated preview, and Meshy auto-rig, wired as CharacterBody3D or Node3D."
+description: "Generate a rigged humanoid (player, NPC, enemy, boss) from a T-pose reference, previewed before rigging."
 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_image summer_generate_3d summer_import_from_url summer_add_node summer_set_prop summer_set_resource_property summer_inspect_node summer_inspect_resource summer_get_scene_tree summer_save_scene summer_check_job summer_generate_motion
+allowed-tools: Read Grep summer_assets_search summer_assets_get summer_import_asset_by_id summer_assets_generate_image summer_assets_generate_3d summer_import_from_url summer_add_node summer_set_prop summer_set_resource_property summer_inspect_node summer_inspect_resource summer_get_scene_tree summer_save_scene summer_jobs_wait summer_assets_generate_motion summer_call
 paths: ["assets/characters/**", "assets/models/**", "**/*.tscn", "**/*.gd"]
 ---
 
@@ -16,16 +16,18 @@ This is the canonical auto-rig pipeline. It produces a humanoid `.glb` with a sk
 The whole flow:
 
 ```
-1. T-pose reference image    →  summer_generate_image                          (~10s)
-2. Un-rigged 3D mesh         →  summer_generate_3d(image-to-3d)                (~60s)
+1. T-pose reference image    →  assets.generate_image                          (~10s)
+2. Un-rigged 3D mesh         →  assets.generate_3d(image-to-3d)  → a job       (~60s)
 3. ── USER REVIEW GATE ──
-4. Rigged .glb               →  summer_generate_3d(image-to-3d, rig=true)      (~90s)
+4. Rigged .glb               →  assets.generate_3d(image-to-3d, rig) → a job   (~90s)
 5. Import → editor RESTART → wire as CharacterBody3D / Node3D
 6. Hand off to generate-motion for clips
 ```
 
 The animation skill (`generate-motion`) requires a rigged humanoid; a static `.glb` won't drive motion.
 
+`assets.generate_3d` always answers at once with a job (`{ status: "running", job: { id } }`); `jobs.wait({ jobId, timeoutSeconds: 50 })` follows it, called again until `finished` is true. The finished job's `result` holds the asset ids. Both passes spend the person's credits: `dryRun: true` on any call returns the estimate (`credits`, `balance`, `enough`) and changes nothing.
+
 ## When to use
 
 - "Make a knight character for the player to control."
@@ -46,11 +48,11 @@ The animation skill (`generate-motion`) requires a rigged humanoid; a static `.g
 
 | Role | Tris | Pass via |
 |---|---|---|
-| Hero character (player, close camera) | 8k–15k | `target_polycount: 12000` |
-| Grunt enemy (mid-range, multiple onscreen) | 3k–6k | `target_polycount: 5000` |
-| Crowd / background NPC (LOD-able) | 1k–2k | `target_polycount: 1500` |
-| Mobile-game character | 1k–3k | `target_polycount: 2000` |
-| Cinematic hero (no realtime constraint) | 20k–40k | `target_polycount: 30000` |
+| Hero character (player, close camera) | 8k–15k | `targetPolycount: 12000` |
+| Grunt enemy (mid-range, multiple onscreen) | 3k–6k | `targetPolycount: 5000` |
+| Crowd / background NPC (LOD-able) | 1k–2k | `targetPolycount: 1500` |
+| Mobile-game character | 1k–3k | `targetPolycount: 2000` |
+| Cinematic hero (no realtime constraint) | 20k–40k | `targetPolycount: 30000` |
 
 Pass at the **mesh-generation step** (step 2). The rig pass preserves the topology; you can't reduce polycount after rigging without breaking weights.
 
@@ -61,10 +63,11 @@ Pass at the **mesh-generation step** (step 2). The rig pass preserves the topolo
 The rig pass requires a **front-facing T-pose** with arms out and legs slightly apart. If the reference is in an action pose, the rig will bend wrong and locomotion clips will look broken (knees inverted, elbows snapped — common Meshy failure mode).
 
 ```
-summer_generate_image(
-  prompt="A fantasy knight in full plate armor, red cape, T-pose, arms straight out horizontal, legs slightly apart, front-facing, neutral expression. Game character asset, stylized, clean white background, soft studio lighting, full body in frame, ready for 3D mesh generation.",
-  model="nano-banana-2"
-)
+assets.generate_image({
+  prompt: "A fantasy knight in full plate armor, red cape, T-pose, arms straight out horizontal, legs slightly apart, front-facing, neutral expression. Game character asset, stylized, clean white background, soft studio lighting, full body in frame, ready for 3D mesh generation.",
+  model: "nano-banana-2",
+  aspectRatio: "3:4"
+})
 ```
 
 The phrase `T-pose, arms straight out horizontal, legs slightly apart, front-facing` is load-bearing — drop any of those and the model will drift toward A-pose or a hero stance.
@@ -72,7 +75,7 @@ The phrase `T-pose, arms straight out horizontal, legs slightly apart, front-fac
 If the user already has a concept image in an action pose, re-pose it to T-pose via img2img without re-rolling the design:
 
 ```
-summer_generate_image({
+assets.generate_image({
   referenceImageUrl: "<existing concept image>",
   prompt: "<character> in T-pose, arms extended horizontally, neutral facing camera, white background, clean lighting"
 })
@@ -85,20 +88,20 @@ Show the image to the user:
 ### 2. Generate the un-rigged 3D mesh
 
 ```
-summer_generate_3d(
-  kind="image-to-3d",
-  imageUrl="<image url from step 1>",
-  model="hunyuan",
-  options={ target_polycount: 12000 },
-  wait=true
-)
+assets.generate_3d({
+  kind: "image-to-3d",
+  imageUrl: "<image url from step 1>",
+  model: "hunyuan",
+  targetPolycount: 12000
+})
+jobs.wait({ jobId: "<job.id>", timeoutSeconds: 50 })   // again until finished
 ```
 
-Returns a job result with `assetId` and `fileUrl` — an un-rigged static `.glb`.
+The finished job's `result` has `assetId` and `fileUrl` — an un-rigged static `.glb`.
 Use the asset ID as the stable handle. Import it for preview only:
 
 ```
-summer_get_asset(assetId="<assetId>")
+assets.get({ assetId: "<assetId>" })
 summer_import_asset_by_id(
   assetId="<assetId>",
   path="res://assets/characters/knight_unrigged.glb"
@@ -120,25 +123,25 @@ If the user wants changes, loop back to step 1 or 2. Do NOT silently run the rig
 ### 4. Run the rig pass
 
 ```
-summer_generate_3d({
+assets.generate_3d({
   kind: "image-to-3d",
   imageUrl: "<image url from step 1>",
   rig: true,
-  options: { target_polycount: 12000 }
+  targetPolycount: 12000
 })
+jobs.wait({ jobId: "<job.id>", timeoutSeconds: 50 })   // again until finished
 ```
 
-`rig` is a **top-level boolean argument** on `summer_generate_3d` (the tool also merges it into `options.rig`, so `options: { rig: true }` works too). There is no `polyTarget` — the polycount key is `target_polycount` inside `options`, exactly as in step 2. Related top-level arguments worth knowing here: `riggingHeightMeters` for character height, and `animationNames` / `actionIds` to have the shared animated-character pipeline produce clips in the same job instead of a separate `summer_generate_motion` pass.
+`rig` and `targetPolycount` are plain fields of `assets.generate_3d` (there is no `options` object and no `polyTarget`). Related fields worth knowing here: `riggingHeightMeters` for character height, and `animationNames` / `actionIds` to have the shared animated-character pipeline produce clips in the same job instead of a separate `assets.generate_motion` pass.
 
-Returns a job whose result includes `assetId`, `fileUrl`, and `rigAssetId`.
-If you ran with `wait: false`, poll via `summer_check_job(jobId)`. The
+The finished job's `result` includes `assetId`, `fileUrl`, and `rigAssetId`. The
 `rigAssetId` is the handle `generate-motion` needs — store it.
 Resolve it before import so the agent has the viewer/download metadata:
 
 Import the rigged version, replacing the un-rigged file:
 
 ```
-summer_get_asset(assetId="<rigAssetId>")
+assets.get({ assetId: "<rigAssetId>" })
 summer_import_asset_by_id(
   assetId="<rigAssetId>",
   path="res://assets/characters/knight.glb"
@@ -162,27 +165,28 @@ No programmatic workaround is known. Tell the user, wait, then continue.
 | Pure-visual character (background extra, dialogue head) | `Node3D` | Same as above |
 | Ragdoll-on-death enemy | `CharacterBody3D` while alive, swap to `RigidBody3D` skeleton on death | Two-mode rig; see `procedural-animation` |
 
-Four things the call shapes below encode:
+Three things the call shapes below encode:
 
-- **Every scene-mutating tool takes an explicit `scenePath`** and the scene need not be the active editor tab.
-- **Node paths are relative to that scene's root (`./`)**, not absolute `/root/...` runtime paths.
-- **`summer_set_prop`'s property argument is named `key`**, not `property`.
-- **A `.glb` is instantiated, not assigned.** There is no `scene` property on `Node3D`, and an imported `.glb` is a scene rather than a `Mesh` — on the shipped 4.6.1 binary `ResourceLoader.get_recognized_extensions_for_type("Mesh")` returns `["tres", "mesh", "res"]`, with no `glb`. Use `summer_instantiate_scene`.
+- **Every scene tool, `summer_run_script` included, takes an explicit `scenePath`**, and the scene need not be the active editor tab.
+- **A character is several nodes: build it in one `summer_run_script`**, not a chain of single calls.
+- **A `.glb` is instantiated, not assigned.** There is no `scene` property on `Node3D`, and an imported `.glb` is a scene rather than a `Mesh` — on the shipped 4.6.1 binary `ResourceLoader.get_recognized_extensions_for_type("Mesh")` returns `["tres", "mesh", "res"]`, with no `glb`. Use `ctx.instance_scene` in a script, or `summer_instantiate_scene` for one model.
 
 **CharacterBody3D wiring (player / enemy):**
 
 ```
-summer_add_node(scenePath="res://main.tscn", parent="./World", type="CharacterBody3D", name="Knight")
-summer_set_prop(scenePath="res://main.tscn", path="./World/Knight", key="position", value="Vector3(0, 0, 0)")
-summer_instantiate_scene(scenePath="res://main.tscn", parent="./World/Knight", scene="res://assets/characters/knight.glb", name="Mesh")
-summer_add_node(scenePath="res://main.tscn", parent="./World/Knight", type="CollisionShape3D", name="Collider")
-summer_set_prop(scenePath="res://main.tscn", path="./World/Knight/Collider", key="shape", value="CapsuleShape3D")
-summer_set_resource_property(scenePath="res://main.tscn", nodePath="./World/Knight/Collider", resourceProperty="shape", subProperty="height", value=1.7)
-summer_set_resource_property(scenePath="res://main.tscn", nodePath="./World/Knight/Collider", resourceProperty="shape", subProperty="radius", value=0.4)
-summer_save_scene(scenePath="res://main.tscn")
+summer_run_script(scenePath="res://main.tscn", source="""
+func run(ctx):
+    var knight = ctx.add_node("CharacterBody3D", "Knight", ctx.find("World"), {"position": Vector3(0, 0, 0)})
+    ctx.instance_scene("res://assets/characters/knight.glb", knight, "Mesh")
+    var capsule := CapsuleShape3D.new()
+    capsule.height = 1.7
+    capsule.radius = 0.4
+    ctx.add_node("CollisionShape3D", "Collider", knight, {"shape": capsule})
+    ctx.save_scene()
+""")
 ```
 
-Assigning a bare class name like `"CapsuleShape3D"` to a resource property auto-instantiates it, which is how you get a shape you can then size. `summer_set_resource_property` needs all five of `scenePath`, `nodePath`, `resourceProperty`, `subProperty`, `value`.
+Build the shape as a real resource and size it before you assign it. Later, one size change on that shape is one `summer_set_resource_property` (`nodePath`, `resourceProperty="shape"`, `subProperty`, `value`, plus `scenePath`).
 
 **Node3D wiring (cinematic NPC):**
 
@@ -198,8 +202,8 @@ The imported `.glb` includes its own `Skeleton3D` and `AnimationPlayer` (empty l
 > Knight is wired at `./World/Knight` with an auto-rigged skeleton. `rigAssetId` saved.
 >
 > Next: `generate-motion` to add idle / walk / run / attack
-> clips. Example call: `summer_generate_motion(rigAssetId: "<saved id>",
-> backend: "meshy-library", motionName: "walk")`. For custom actions, use
+> clips. Example call: `assets.generate_motion({ rigAssetId: "<saved id>",
+> backend: "meshy-library", motionNames: ["walk"] })`. For custom actions, use
 > `text-to-motion` (`backend: "text-to-motion"`).
 
 ## Anti-patterns
@@ -220,6 +224,10 @@ The imported `.glb` includes its own `Skeleton3D` and `AnimationPlayer` (empty l
 - **First-person hands-only character.** Generate just hands + forearms in T-pose; rig pass still works. See `fps-controller` for first-person wiring.
 - **Stylized non-human (goblin, orc, halfling).** Works fine as long as the silhouette is bipedal with two arms, two legs, one head. Quadrupeds and centaurs do not.
 
+## Without Summer Engine
+
+In a session without Summer Engine tools (the assets profile; the `summer-assets` skill has the whole loop), do steps 1-4, including the review gate, and stop when the rig pass finishes. Skip steps 5-6 (editor restart, scene wiring). Save the rigged GLB (`rigAssetId`; the unrigged mesh is `assetId`) where the person asked with `out` on `jobs.wait` or `assets.get` (the `summer-assets` skill says how), and tell them the path. Step 7 still applies: `generate-motion` runs without the engine.
+
 ## Fallback (no MCP)
 
 1. Generate the T-pose reference in the Summer dashboard.
@@ -248,4 +256,32 @@ After the rigged character is wired:
 - `asset-strategy` — meta-router; this skill is the canonical drill-down of its "Image-to-3D for characters" path.
 - `prop-model` — for non-character props.
 - `scene-composition` — for the CharacterBody3D + Mesh + Collider parent pattern.
-- `../../references/mcp-tools-reference/mcp-tools-reference.md` — full parameter schemas for `summer_generate_3d`, `summer_generate_image`, and `summer_generate_motion`.
+- `summer_docs_read` id `reference/mcp-tools-reference` — how to call `assets.generate_3d`, `assets.generate_image` and `assets.generate_motion`; `summer_search` returns each one's exact input.
+
+<!-- shell-commands: generated from the operation catalog by npm run generate:registry; do not edit by hand -->
+## From a shell
+
+No Summer MCP tools in this session? Run each one as a command; when `summer --version` is missing or below 4.0, use `npx -y summer-engine@latest` in place of `summer`. Fields are flags in kebab-case (`--scene-path res://main.tscn`) or one `--input '<json>'`, and `summer ops describe <op>` prints the exact input. The `summer-cli` skill has the rest.
+
+| In this skill | Command |
+|---|---|
+| `assets.generate_3d`, `summer_assets_generate_3d` | `summer assets generate-3d` |
+| `assets.generate_image`, `summer_assets_generate_image` | `summer assets generate-image` |
+| `assets.generate_motion`, `summer_assets_generate_motion` | `summer assets generate-motion` |
+| `assets.get`, `summer_assets_get` | `summer assets get` |
+| `summer_assets_search` | `summer assets search` |
+| `summer_docs_read` | `summer docs read` |
+| `summer_add_node` | `summer engine add-node` |
+| `summer_get_scene_tree` | `summer engine get-scene-tree` |
+| `summer_import_asset_by_id` | `summer engine import-asset-by-id` |
+| `summer_import_from_url` | `summer engine import-from-url` |
+| `summer_inspect_node` | `summer engine inspect-node` |
+| `summer_inspect_resource` | `summer engine inspect-resource` |
+| `summer_instantiate_scene` | `summer engine instantiate-scene` |
+| `summer_run_script` | `summer engine run-script` |
+| `summer_save_scene` | `summer engine save-scene` |
+| `summer_set_prop` | `summer engine set-prop` |
+| `summer_set_resource_property` | `summer engine set-resource-property` |
+| `jobs.wait`, `summer_jobs_wait` | `summer jobs wait` |
+| `summer_search` | `summer ops search "<what you want>"` |
+<!-- /shell-commands -->

package/library/skills/character-model/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/character-model
 kind: skill
 version: 1.0.2
-summary: Generate a rigged humanoid — player, NPC, enemy, boss — via T-pose reference, user-gated preview, and Meshy auto-rig, wired as CharacterBody3D or Node3D.
+summary: "Generate a rigged humanoid (player, NPC, enemy, boss) from a T-pose reference, previewed before rigging."
 use_when:
   - generating a humanoid character ready for animation — player avatar, NPC, enemy, boss, companion
   - the user asks for a rigged humanoid or a model with a skeleton