summer-engine 3.8.0 → 4.2.0

package/library/skills/remote-deploy/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: remote-deploy
-description: "Run or test the game on a real device — phone, tablet, another computer — via the Remote Deploy button, runnable export presets, and on-device debugging."
+description: "Run or test the game on a real phone, tablet or computer with Remote Deploy and on-device debugging."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: deployment
@@ -137,3 +137,17 @@ never replaces the proof.
 | Greyed, "No Remote Deploy export presets configured." | No runnable preset **or** no detected device | Add a Runnable preset; connect/authorize a device |
 | Enabled, dropdown lists devices | Ready to deploy | Pick a device to build + run |
 | Deploy fails in result dialog | Templates/toolchain/signing/device issue | Read the dialog; install the named missing piece |
+
+<!-- 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_export_templates` | `summer engine export-templates` |
+| `summer_get_console` | `summer engine get-console` |
+| `summer_get_diagnostics` | `summer engine get-diagnostics` |
+| `summer_get_script_errors` | `summer engine get-script-errors` |
+| `summer_project_setting` | `summer engine project-setting` |
+<!-- /shell-commands -->

package/library/skills/remote-deploy/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/remote-deploy
 kind: skill
 version: 1.0.2
-summary: Run or test the game on a real device — phone, tablet, another computer — via the Remote Deploy button, runnable export presets, and on-device debugging.
+summary: "Run or test the game on a real phone, tablet or computer with Remote Deploy and on-device debugging."
 use_when:
   - the user wants to run or test the game on a real target instead of the editor — a phone, tablet, or another computer
   - the Remote Deploy button is greyed out and the user wants to know why

package/library/skills/retarget/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: retarget
-description: "Apply existing animation clips from one rigged character to a different rigged character — same library, multiple models, no regeneration."
+description: "Apply animation clips from one rigged character to another: one clip library, many models."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: animation
 user-invocable: false
-allowed-tools: Read Grep summer_search_assets summer_inspect_resource summer_generate_motion summer_get_scene_tree summer_set_resource_property summer_save_scene
+allowed-tools: Read Grep summer_assets_search summer_inspect_resource summer_assets_generate_motion summer_get_scene_tree summer_set_resource_property summer_save_scene summer_jobs_wait summer_call
 paths: ["**/*.tscn", "**/*.tres"]
 ---
 
@@ -22,7 +22,7 @@ Two real paths exist. Pick by whether the target rig is Meshy-rigged.
 
 | Situation | Path |
 |---|---|
-| Target is Meshy-rigged and the clip name is on the curated list | Re-run `summer_generate_motion` against the target's `rigAssetId`. Same clip, ~30s, uses credits. |
+| Target is Meshy-rigged and the clip name is on the curated list | Re-run `assets.generate_motion` against the target's `rigAssetId`. Same clip, ~30s, uses credits. |
 | Target is not Meshy-rigged, or the clip is hand-authored / Mixamo / bought | In-engine retargeting: `BoneMap` + `SkeletonProfileHumanoid` + `RetargetModifier3D`. No credits, no network, but you configure the bone mapping. |
 
 The rest of this skill covers both.
@@ -45,12 +45,12 @@ The rest of this skill covers both.
 ## Path A — regenerate on the target rig (Meshy-rigged targets)
 
 This is the path for the common case: several characters that all came out of
-`summer_generate_3d(... rig: true)`.
+`assets.generate_3d({ ..., rig: true })`.
 
 ### 1. Find the source clip names
 
 ```
-summer_search_assets(query: "<source character>", assetType: "animation", source: "my_assets")
+assets.search({ query: "<source character>", assetType: "animation", scope: "mine" })
 ```
 
 You want the *names* (`idle`, `walk`, `run`, ...), not the asset IDs — the IDs
@@ -59,33 +59,36 @@ belong to the source rig and cannot be transplanted.
 ### 2. Find the target rig
 
 ```
-summer_search_assets(query: "<target character>", assetType: "3d_model", source: "my_assets")
+assets.search({ query: "<target character>", assetType: "3d_model", scope: "mine" })
 ```
 
-Confirm a `rigAssetId` is present. If it is null the model was never rigged —
-stop and propose `summer_generate_3d({ kind: "image-to-3d", imageUrl: "...", rig: true })`
+The rigged model's `assetId` is its `rigAssetId`. Search results do not say whether
+a model is rigged: run step 4's call with `dryRun: true`, which refuses a model that
+is not rigged (`invalid_input` on `rigAssetId`). Then the model was never rigged —
+stop and propose `assets.generate_3d({ kind: "image-to-3d", imageUrl: "...", rig: true })`
 first, or route to `asset-strategy`.
 
 ### 3. Confirm with user before spending
 
-Regeneration is a real generation per clip per character, and each one uses credits. Say the total count.
+Regeneration is a real generation per clip per character, and each one uses credits. Say the total count; `dryRun: true` on the call below gives the credits for all its clips at once.
 
 > I'm about to generate 12 clips (idle, walk, run, attack, ...) on `orc_rigged`.
 > That is 12 generations, a few minutes total. OK?
 
-### 4. Loop the generation calls
+### 4. One generation call for all the clips
 
 ```
-for name in source_clip_names:
-  summer_generate_motion(
-    rigAssetId: "<target_rigAssetId>",
-    backend: "meshy-library",
-    motionName: name          // exact curated name — see generate-motion's list
-  )
-  // returns animationAssetId in the job result
+assets.generate_motion({
+  rigAssetId: "<target_rigAssetId>",
+  backend: "meshy-library",
+  motionNames: source_clip_names   // exact curated names — see generate-motion's list
+})
+jobs.wait({ jobId: "<job.id>", timeoutSeconds: 50 })   // again until finished
 ```
 
-Save the returned IDs as a map `{ name: animationAssetId }` for the target.
+`motionNames` takes up to 12 names in one call. The finished job's `result` holds
+the new clips' asset ids; when the target already has every clip, the answer is
+`done` at once with `reused` and nothing is charged. Save the IDs as a map `{ name: animationAssetId }` for the target.
 
 ### 5. Attach to the target's AnimationPlayer
 
@@ -176,7 +179,7 @@ same rigged `.glb`, nothing needs retargeting — instance the scene.
 - Calling a `summer_retarget_motion` / `summer_retarget_*` tool. None exists.
 - Passing an asset ID to `summer_inspect_resource`. That tool takes a `res://`
   **path** to a resource in the project, not a cloud asset ID. Use
-  `summer_get_asset(assetId: ...)` for asset metadata.
+  `assets.get({ assetId: ... })` for asset metadata.
 - Generating motion on each enemy separately when they are instances of the same
   rig. Instance the scene; the library comes with it.
 
@@ -187,7 +190,7 @@ same rigged `.glb`, nothing needs retargeting — instance the scene.
   to re-author per character.
 - **Target rig is a different Meshy skeleton generation.** Symptom: bone-count
   mismatch even though both are Meshy. Re-rig the target with a fresh
-  `summer_generate_3d({ kind: "image-to-3d", rig: true })` call.
+  `assets.generate_3d({ kind: "image-to-3d", imageUrl: "...", rig: true })` call.
 - **The clip the user wants is not on the curated list.** Path A cannot produce
   it. Either hand-author it, or import a Mixamo clip and take Path B.
 
@@ -215,3 +218,23 @@ The upstream engine docs cover this under "Retargeting 3D Skeletons".
 - `asset-strategy` — getting characters rigged in the first place.
 - `animation-tree` — wire the clips into a state machine.
 - `procedural-animation` — fix proportional mismatches with foot IK.
+
+<!-- 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 assets generate-motion` |
+| `assets.get` | `summer assets get` |
+| `summer_assets_search` | `summer assets search` |
+| `summer_add_node` | `summer engine add-node` |
+| `summer_get_scene_tree` | `summer engine get-scene-tree` |
+| `summer_inspect_resource` | `summer engine inspect-resource` |
+| `summer_save_scene` | `summer engine save-scene` |
+| `summer_set_prop` | `summer engine set-prop` |
+| `summer_set_resource_property` | `summer engine set-resource-property` |
+| `summer_jobs_wait` | `summer jobs wait` |
+<!-- /shell-commands -->

package/library/skills/retarget/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/retarget
 kind: skill
 version: 1.0.3
-summary: Apply existing animation clips from one rigged character to a different rigged character — same library, multiple models, no regeneration.
+summary: "Apply animation clips from one rigged character to another: one clip library, many models."
 use_when:
   - applying existing animation clips from one rigged character to a different rigged character — sharing one animation library across models
   - the same clips must play on several differently proportioned rigs without regenerating them

package/library/skills/running-in-the-cloud/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: running-in-the-cloud
-description: "Run Summer Engine on a Linux box with no display — install it, launch headless, know when xvfb + software GL are needed, authenticate without a browser."
+description: "Run Summer Engine on a Linux box with no display: install, launch headless, xvfb, sign in without a browser."
 ---
 
 # Running in the Cloud
@@ -101,3 +101,13 @@ Treat it as a secret: env-inject it from the runner's secret store, never bake i
 - `headless-scripting` — the headless invocation contract, exit-code traps, and what scripts unlock.
 - `playtesting-a-feature` — the verify instance and probes (run them under xvfb in the cloud).
 - `verification-before-completion` — judging work by artifacts, which matters more when nobody can see a screen.
+
+<!-- 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_screenshot` | `summer engine screenshot` |
+<!-- /shell-commands -->

package/library/skills/running-in-the-cloud/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/running-in-the-cloud
 kind: skill
 version: 1.0.3
-summary: Run Summer Engine on a Linux box with no display — install it, launch headless, know when xvfb + software GL are needed, authenticate without a browser.
+summary: "Run Summer Engine on a Linux box with no display: install, launch headless, xvfb, sign in without a browser."
 use_when:
   - Summer Engine runs in a cloud container, CI job, remote agent sandbox, or any Linux machine with no desktop
   - installing the engine on Linux, or a tool reports "engine not running" in an environment that has no display

package/library/skills/save-load/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: save-load
-description: "Persist game state in Summer Engine: user:// paths, JSON progress vs ConfigFile settings, a versioned save schema with migration, autosave hooks."
+description: "Save and load game state: user:// paths, JSON progress vs ConfigFile settings, versioned saves, autosave."
 license: MIT
 compatibility: [Cursor, Claude Code, Codex, Windsurf, Gemini, OpenCode]
 category: scripting-patterns
@@ -154,3 +154,18 @@ Set `get_tree().set_auto_accept_quit(false)` so you control the quit.
   instead: a `RunVerification` probe (see `playtesting-a-feature`) that calls
   `save_game()`, changes a value, calls `load_game()`, and `report()`s the
   restored value.
+
+<!-- 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_diagnostics` | `summer engine get-diagnostics` |
+| `summer_get_script_errors` | `summer engine get-script-errors` |
+| `summer_project_setting` | `summer engine project-setting` |
+| `summer_read_file` | `summer engine read-file` |
+| `summer_replace_text` | `summer engine replace-text` |
+| `summer_write_file` | `summer engine write-file` |
+<!-- /shell-commands -->

package/library/skills/save-load/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/save-load
 kind: skill
 version: 1.0.0
-summary: "Persist game state in Summer Engine: user:// paths, JSON progress vs ConfigFile settings, a versioned save schema with migration, autosave hooks."
+summary: "Save and load game state: user:// paths, JSON progress vs ConfigFile settings, versioned saves, autosave."
 use_when:
   - persisting progress, settings, high scores, checkpoints, or save slots
   - deciding between JSON and ConfigFile for a save or settings file

package/library/skills/scene-composition/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: scene-composition
-description: "Scene structure conventions — node hierarchy, when to extract sub-scenes, reusable prefab patterns, and instance-versus-add-node decisions."
+description: "Scene structure: node hierarchy, when to extract sub-scenes, reusable prefabs, instance vs add node."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: scene-and-project
@@ -165,3 +165,20 @@ Don't skip the player mask update. If you only move foliage to layer 9 without a
 ## Collaborative protocol
 
 This skill creates and mutates scene files. Always ask before applying: "May I create `res://scenes/player.tscn` and instantiate it under `./World`?".
+
+<!-- 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_add_node` | `summer engine add-node` |
+| `summer_create_scene` | `summer engine create-scene` |
+| `summer_get_scene_tree` | `summer engine get-scene-tree` |
+| `summer_import_from_url` | `summer engine import-from-url` |
+| `summer_instantiate_scene` | `summer engine instantiate-scene` |
+| `summer_open_scene` | `summer engine open-scene` |
+| `summer_save_scene` | `summer engine save-scene` |
+| `summer_set_prop` | `summer engine set-prop` |
+<!-- /shell-commands -->

package/library/skills/scene-composition/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/scene-composition
 kind: skill
 version: 1.0.3
-summary: Scene structure conventions — node hierarchy, when to extract sub-scenes, reusable prefab patterns, and instance-versus-add-node decisions.
+summary: "Scene structure: node hierarchy, when to extract sub-scenes, reusable prefabs, instance vs add node."
 use_when:
   - "building or organizing Summer Engine scenes: node hierarchy conventions, sub-scene extraction, prefab patterns, PackedScene decisions"
   - deciding whether to extract a sub-scene, instance a prefab, or add nodes inline as a scene grows

package/library/skills/scene-hierarchy-design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: scene-hierarchy-design
-description: "Structure Summer Engine scenes by access pattern — asset vs live hierarchies, wrapper nodes per operation, sub-scenes for reuse, path-agnostic logic."
+description: "Structure scenes by access pattern: asset vs live hierarchies, wrapper nodes, sub-scenes, path-agnostic code."
 license: MIT
 category: workflow
 tags:
@@ -74,7 +74,7 @@ Rules of thumb:
 
 Follow the canonical scene loop from the Summer MCP reference: route → orient → read rules → resolve `scenePath` → mutate → verify.
 
-1. **Orient.** `summer_start_game_task` to route the goal; `summer_get_project_context`; `summer_get_agent_playbook`.
+1. **Orient.** `summer_call` `{"op":"docs.plan"}` to route the goal; `summer_get_project_context`; `summer_call` `{"op":"summer_get_agent_playbook"}`.
 2. **Read before writing.** `summer_get_scene_tree` on the exact `res://...tscn`. Never mutate blind, and never edit `.tscn` text while the engine is running — use the MCP tools.
 3. **Pick the access pattern.** For each planned cluster decide: operated as a subtree (→ wrapper parent), queried by type across the scene (→ flat siblings + group), or unique (→ inline under root container).
 4. **Build asset hierarchies first.** For reusable setups create the sub-scene (`summer_create_scene` / build inline then `summer_save_scene(scenePath="res://main.tscn", path="res://scenes/<name>.tscn")`), then bring them in with `summer_instantiate_scene(scenePath="res://main.tscn", parent="./<Wrapper>", scene="res://scenes/<name>.tscn", name="<Role>_01")`.
@@ -100,3 +100,27 @@ Follow the canonical scene loop from the Summer MCP reference: route → orient
 3. Deleting a wrapper parent (`summer_remove_node`) removes exactly its subtree — the recursive-despawn feature works.
 4. No script references a path deeper than one or two segments; group/signal/NodePath used instead.
 5. `summer_get_script_errors` and (if played) `summer_get_debugger_errors` are clean; `summer_screenshot` matches the intended layout.
+
+<!-- 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 |
+|---|---|
+| `docs.plan` | `summer docs plan` |
+| `summer_add_node` | `summer engine add-node` |
+| `summer_connect_signal` | `summer engine connect-signal` |
+| `summer_create_scene` | `summer engine create-scene` |
+| `summer_get_debugger_errors` | `summer engine get-debugger-errors` |
+| `summer_get_project_context` | `summer engine get-project-context` |
+| `summer_get_scene_tree` | `summer engine get-scene-tree` |
+| `summer_get_script_errors` | `summer engine get-script-errors` |
+| `summer_instantiate_scene` | `summer engine instantiate-scene` |
+| `summer_play` | `summer engine play` |
+| `summer_remove_node` | `summer engine remove-node` |
+| `summer_save_scene` | `summer engine save-scene` |
+| `summer_screenshot` | `summer engine screenshot` |
+| `summer_stop` | `summer engine stop` |
+| `summer_get_agent_playbook` | `summer tool get-agent-playbook` |
+<!-- /shell-commands -->

package/library/skills/scene-hierarchy-design/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/scene-hierarchy-design
 kind: skill
 version: 0.1.1
-summary: "Structure Summer Engine scenes by access pattern — asset vs live hierarchies, wrapper nodes per operation, sub-scenes for reuse, path-agnostic logic."
+summary: "Structure scenes by access pattern: asset vs live hierarchies, wrapper nodes, sub-scenes, path-agnostic code."
 use_when:
   - "how should I structure the node hierarchy for this level or character"
   - "reorganize a scene that grew ad hoc — long node chains, duplicated clusters, hard-to-delete groups"