summer-engine 3.8.0 → 4.2.0

package/library/skills/multiplayer-publish/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: multiplayer-publish
-description: "Ship a hosted Summer multiplayer game: the summer.games bundle, server preset, pre-upload checks, and a new Build."
+description: "Ship a hosted Summer multiplayer game: the bundle, server preset, pre-upload checks, a new Build."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: multiplayer-and-networking
 user-invocable: true
-allowed-tools: Read Grep Glob Edit Write summer_read_file summer_write_file summer_project_setting summer_open
+allowed-tools: Read Grep Glob Edit Write summer_read_file summer_write_file summer_project_setting summer_call
 paths: ["export_presets.cfg", "summer.build.json", "world.json", "source-domains.json", "runtime-manifest.json", "project.godot"]
 ---
 
@@ -246,16 +246,17 @@ empty window. Re-export with the current Summer release.
    `summer.build.json` must be its id. The export leaves `gameId` out of the
    bundle, and the game code calls `Summer.initialize()` with no ID: a
    literal or fallback ID fails hosted with `game_identity_mismatch`.
-2. Open the game's Builds page: `summer_open` with target `game`,
+2. Open the game's Builds page: `studio.open` with target `game`,
    `gameId` and section `builds`, or summerengine.com → Studio → your game →
    Builds.
 3. Upload the `.zip` as a new Build. Summer checks it again: unknown fields,
    queue rules, both packs, and the composition match. From an agent:
-   `summer_export_game`, then `summer_publish_build` with `gameId` and
+   `summer_export_game`, then `store.upload_file` with `gameId` and
    `clientVersion`; it asks for confirmation first and needs
-   `summer login --store`. If it answers `store_auth_refused`, upload in
-   Studio.
-4. Release the Build to an environment. Its queues go live there, and
+   `summer login --store`. If the store refuses this machine's sign-in,
+   upload in Studio.
+4. Release the Build to an environment (`store.release` releases the Build
+   the owner approved with `store.publish`). Its queues go live there, and
    clients join them with `Summer.client.join(SummerJoinTarget.queue(...))`.
    The code is the same as in Local Play.
 
@@ -316,3 +317,20 @@ Use step 4d to see which scene runs.
 | Export with a development build of Summer | Export with the released editor from the download page, again after every update | Players run the pack on the released Summer of the stamped version; newer APIs fail to compile and the game opens to an empty window |
 | Read an empty server log as a hang | Run step 4d | A release server holds back its output until it exits |
 | Export a patch | Export Project, or Export PCK/ZIP without Export As Patch | summer.games takes complete bundles or packs |
+
+<!-- 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_game` | `summer engine export-game` |
+| `summer_project_setting` | `summer engine project-setting` |
+| `summer_read_file` | `summer engine read-file` |
+| `summer_write_file` | `summer engine write-file` |
+| `store.publish` | `summer store publish` |
+| `store.release` | `summer store release` |
+| `store.upload_file` | `summer store upload-file` |
+| `studio.open` | `summer studio open` |
+<!-- /shell-commands -->

package/library/skills/multiplayer-publish/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/multiplayer-publish
 kind: skill
-version: 1.0.0
-summary: "Ship a hosted Summer multiplayer game: the summer.games bundle, server preset, pre-upload checks, and a new Build."
+version: 1.0.1
+summary: "Ship a hosted Summer multiplayer game: the bundle, server preset, pre-upload checks, a new Build."
 use_when:
   - "publishing a hosted Summer multiplayer game online so other players can join it"
   - "making the summer.games bundle of a hosted game: client.pck, server.pck and the Linux server preset"
@@ -25,5 +25,5 @@ related:
     - skill/release-readiness
 source: official
 license: MIT
-status: preview
+status: stable
 recommended: false

package/library/skills/multiplayer-state/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: multiplayer-state
-description: "Authority-owned game state in Summer multiplayer: shared and private State groups, validated Commands, and Events."
+description: "Authority-owned state in Summer multiplayer: shared and private State groups, Commands, Events."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: multiplayer-and-networking
@@ -436,3 +436,19 @@ Run Local Play with 2 players and network emulation (`multiplayer-testing`):
 ## Next
 
 `multiplayer-testing`: bots and a bad network. Then `multiplayer-publish`.
+
+<!-- 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_play` | `summer engine play` |
+| `summer_project_setting` | `summer engine project-setting` |
+| `summer_read_file` | `summer engine read-file` |
+| `summer_stop` | `summer engine stop` |
+| `summer_write_file` | `summer engine write-file` |
+<!-- /shell-commands -->

package/library/skills/multiplayer-state/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/multiplayer-state
 kind: skill
 version: 1.0.0
-summary: "Authority-owned game state in Summer multiplayer: shared and private State groups, validated Commands, and Events."
+summary: "Authority-owned state in Summer multiplayer: shared and private State groups, Commands, Events."
 use_when:
   - "score, health, doors, rounds, inventories or wallets in a Summer multiplayer game, and who owns them"
   - "players need to collect, buy, use, open or trade things and the authority must validate it"

package/library/skills/multiplayer-testing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: multiplayer-testing
-description: "Test a Summer multiplayer game with Local Play: several players, a bad network, bots, and what a passing run shows."
+description: "Test a Summer multiplayer game with Local Play: several players, bad network, bots, a passing run."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: multiplayer-and-networking
@@ -247,3 +247,18 @@ gaps on the `.zip` you upload.
 ## Next
 
 `multiplayer-publish`: export the summer.games bundle and upload it as a Build.
+
+<!-- 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_console` | `summer engine get-console` |
+| `summer_get_diagnostics` | `summer engine get-diagnostics` |
+| `summer_play` | `summer engine play` |
+| `summer_project_setting` | `summer engine project-setting` |
+| `summer_screenshot` | `summer engine screenshot` |
+| `summer_stop` | `summer engine stop` |
+<!-- /shell-commands -->

package/library/skills/multiplayer-testing/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/multiplayer-testing
 kind: skill
 version: 1.0.0
-summary: "Test a Summer multiplayer game with Local Play: several players, a bad network, bots, and what a passing run shows."
+summary: "Test a Summer multiplayer game with Local Play: several players, bad network, bots, a passing run."
 use_when:
   - "running or testing a Summer multiplayer game locally with several players (Local Play)"
   - "testing multiplayer under latency, jitter or packet loss, or with bots"

package/library/skills/music-track/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: music-track
-description: "Generate a looped or cinematic music track — loops authored at >=30s with a marked loop point, cinematic tracks at >=60s linear."
+description: "Generate a music track: game loops of 30s or more with a loop point, or linear cinematic cues."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: audio
 user-invocable: true
-allowed-tools: Read Grep Glob Write Edit summer_generate_audio summer_search_assets summer_import_from_url summer_add_node summer_set_prop summer_inspect_node
+allowed-tools: Read Grep Glob Write Edit summer_assets_generate_audio summer_assets_search summer_import_from_url summer_add_node summer_set_prop summer_inspect_node summer_call
 paths: ["audio/music/**", "scripts/**", "**/*.tscn"]
 ---
 
@@ -126,18 +126,18 @@ Show the prompt:
 > `85 BPM, D minor, 4/4, solo cello and detuned upright piano, sparse, melancholic exploration loop, no drums, gentle reverb, 60s loop`
 > Duration 60s. This uses credits. Generate?
 
-The `music` capability reads the description from **`prompt`**, not `text` — the mirror image of `sound_effects`. Passing `text` here is a 400 `prompt_required`.
+The `music` capability reads the description from **`prompt`**, not `text` — the mirror image of `sound_effects`. Without `prompt` the call is refused (`prompt_required`).
 
 ```
-summer_generate_audio(
+assets.generate_audio({
   capability: "music",
   prompt: "85 BPM, D minor, 4/4, solo cello and detuned upright piano, sparse, melancholic exploration loop, no drums, gentle reverb, 60s loop",
   durationSeconds: 60
-)
-// Then: summer_import_from_url(url: "<fileUrl>", path: "res://audio/music/calm_exploration.mp3")
+})
+// Then: summer_import_from_url(url: "<asset.fileUrl>", path: "res://audio/music/calm_exploration.mp3")
 ```
 
-`durationSeconds` is clamped to 3–600. Music comes back as MP3 (`audio/mpeg`), so a `.mp3` target path is correct.
+`durationSeconds` is clamped to 3–600, and a longer track costs more: `dryRun: true` returns the `estimate` in credits first. Music comes back as MP3 (`audio/mpeg`), so a `.mp3` target path is correct.
 
 ### 7. Mark the loop point in Summer Engine
 
@@ -161,14 +161,19 @@ For seamless looping, the cleaner option is to ask the model to generate a cell
 
 ### 8. Wire it as `AudioStreamPlayer` on the `Music` bus
 
-Every scene-mutating tool takes an explicit `scenePath`, node paths are relative to the scene root (`./`), and the property argument is named `key`, not `property`:
+One script adds the player with its settings; `scenePath` is the exact scene to change:
 
 ```
-summer_add_node(scenePath="res://main.tscn", parent=".", type="AudioStreamPlayer", name="MusicCalm")
-summer_set_prop(scenePath="res://main.tscn", path="./MusicCalm", key="stream", value="res://audio/music/calm_exploration.mp3")
-summer_set_prop(scenePath="res://main.tscn", path="./MusicCalm", key="bus", value="Music")
-summer_set_prop(scenePath="res://main.tscn", path="./MusicCalm", key="volume_db", value=-8.0)
-summer_set_prop(scenePath="res://main.tscn", path="./MusicCalm", key="autoplay", value=true)
+summer_run_script(scenePath="res://main.tscn", source="""
+func run(ctx):
+    ctx.add_node("AudioStreamPlayer", "MusicCalm", null, {
+        "stream": load("res://audio/music/calm_exploration.mp3"),
+        "bus": "Music",
+        "volume_db": -8.0,
+        "autoplay": true,
+    })
+    ctx.save_scene()
+""")
 ```
 
 Music is `AudioStreamPlayer` (not 2D / 3D) — non-positional. The bible's `Music -8 dB` mix sits the music behind SFX where it belongs.
@@ -257,6 +262,10 @@ Cutscene (cinematic):   varies tempo, D minor, 4/4, solo piano opens,
 - **Track sounds nothing like the references.** Re-read the bible; the prompt may be missing the anchor instrument. Add it explicitly.
 - **Track has unexpected vocals.** Add `no vocals, instrumental only` to the prompt.
 
+## Without Summer Engine
+
+In a session without Summer Engine tools (the assets profile; the `summer-assets` skill has the whole loop), do steps 1-6 and skip steps 7-9 (loop point, `AudioStreamPlayer`, crossfade script). Save the file where the person asked with `out` (the `summer-assets` skill says how), and tell them the path and format. For a loop track, tell them it is made to loop.
+
 ## Fallback (no MCP)
 
 Print the prompt and instruct the user to run via the Summer dashboard, then `summer_import_from_url` the rendered MP3.
@@ -274,3 +283,19 @@ Print the prompt and instruct the user to run via the Summer dashboard, then `su
 - `adaptive-music` — wiring stems to game state
 - `sound-effect` — short stings
 - `ambient-bed` — non-melodic location bed
+
+<!-- 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_assets_search` | `summer assets search` |
+| `summer_add_node` | `summer engine add-node` |
+| `summer_import_from_url` | `summer engine import-from-url` |
+| `summer_inspect_node` | `summer engine inspect-node` |
+| `summer_run_script` | `summer engine run-script` |
+| `summer_set_prop` | `summer engine set-prop` |
+<!-- /shell-commands -->

package/library/skills/music-track/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/music-track
 kind: skill
 version: 1.0.2
-summary: Generate a looped or cinematic music track — loops authored at >=30s with a marked loop point, cinematic tracks at >=60s linear.
+summary: "Generate a music track: game loops of 30s or more with a loop point, or linear cinematic cues."
 use_when:
   - generating a looped or cinematic music track — main theme, boss music, title screen, exploration loop, combat track
   - a game has no music yet or needs a new track for a level, a cutscene, or the credits

package/library/skills/navigate-summer/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: navigate-summer
-description: "When to open a Summer web page or editor surface FOR the user (billing, their games, the scene just built) versus acting through the API, using summer_open."
+description: "Open a Summer web page or editor surface for the user (billing, their games, a scene) with studio.open."
 license: MIT
 compatibility: [Cursor, Claude Code, Codex, Windsurf, Gemini, OpenCode, Factory, Copilot]
 category: _meta
 user-invocable: true
-allowed-tools: summer_open summer_get_project_context summer_is_running
+allowed-tools: summer_call summer_get_project_context summer_is_running
 paths: ["**/project.godot", "**/*.tscn", "**/.summer/**"]
 ---
 
@@ -13,7 +13,9 @@ paths: ["**/project.godot", "**/*.tscn", "**/.summer/**"]
 
 ## Overview
 
-Summer has two surfaces the user looks at: **summerengine.com** (Studio, games, billing, templates, guides, docs) and the **Summer Engine editor** (scenes, nodes, docks). `summer_open` — the same behavior as `summer open <target>` in a shell — takes an intent ("billing", "my games", "the scene I'm editing", "res://player.gd") and opens the exact page or panel, or prints the URL / engine op so you can hand it over. The **product map** reference (`../../references/product-map/product-map.md`) is the full table of destinations with their intent phrases, required context, and what the user will see.
+Summer has two surfaces the user looks at: **summerengine.com** (Studio, games, billing, templates, guides, docs) and the **Summer Engine editor** (scenes, nodes, docks). `studio.open` — the same behavior as `summer open <target>` in a shell, run by the Summer MCP on this computer — takes an intent ("billing", "my games", "the scene I'm editing", "res://player.gd") and opens the exact page or panel, or prints the URL / engine op so you can hand it over. The **product map** reference (`summer_docs_read` id `reference/product-map`) is the full table of destinations with their intent phrases, required context, and what the user will see.
+
+A call written `studio.open({...})` is `summer_call({ op: "studio.open", input: {...} })` (3.x name: `summer_open`). The fields below are in the answer's `result`.
 
 Rigid skill: follow the rules below exactly.
 
@@ -21,18 +23,18 @@ Rigid skill: follow the rules below exactly.
 
 | The user wants to… | Do |
 |---|---|
-| **see / check / decide** — plan and billing (money), their published games and releases, usage, pricing, the MCP setup guide for their agent, docs, the scene or node you just built ("show me") | **Open the surface** with `summer_open` |
-| **get a result** — add a node, set a property, import an asset, run the game, publish | **Act through Summer tools** (mutation tools, `summer_play`, `summer_publish_build`); do not open the editor to do by hand what a tool does |
+| **see / check / decide** — plan and billing (money), their published games and releases, usage, pricing, the MCP setup guide for their agent, docs, the scene or node you just built ("show me") | **Open the surface** with `studio.open` |
+| **get a result** — add a node, set a property, import an asset, run the game, publish | **Act through Summer tools** (mutation tools, `summer_play`, `store.publish`); do not open the editor to do by hand what a tool does |
 | **both** ("add a camera and show me") | act first, then open the scene / select the node so the user sees the result |
 
 Never open a browser or switch the editor's tab as a side effect of building. Opening is a user-visible action — do it because the user asked to look, and say what will open before it opens.
 
 ## How to call it
 
-1. **Resolve first when unsure.** `summer_open({ target: "change my plan", open: false })` returns the matched target, the URL (and `login_url` if login is required), or the engine op — nothing opens. If `action` is `ambiguous`, pick from `matches` and call again with the `id`.
-2. **Open.** `summer_open({ target: "billing" })` opens the browser at Studio → Billing. `summer_open({ target: "scene", params: { path: "res://levels/level_1.tscn" } })` opens the scene in the running editor. `summer_open({ target: "node", params: { node: "Player/Camera3D" } })` selects the node. `summer_open({ target: "res://player.gd" })` routes by extension.
+1. **Resolve first when unsure.** `studio.open({ target: "change my plan", open: false })` returns the matched target, the URL (and `login_url` if login is required), or the engine op — nothing opens. If `action` is `ambiguous`, pick from `matches` and call again with the `id`.
+2. **Open.** `studio.open({ target: "billing" })` opens the browser at Studio → Billing. `studio.open({ target: "scene", params: { path: "res://levels/level_1.tscn" } })` opens the scene in the running editor. `studio.open({ target: "node", params: { node: "Player/Camera3D" } })` selects the node. `studio.open({ target: "res://player.gd" })` routes by extension.
 3. **Fill the slots the target declares.** `game` needs `params.gameId` (and an optional `section` such as `builds`, `releases`, `store-page`, `analytics`); `mcp-guide` takes `params.guide` as an agent name (`cursor`, `claude-code`, `codex`, `gemini`, …); `profile` takes `username`; `changelog` takes `version`.
-4. **List when you do not know the id.** `summer_open({})` returns every target with `surface`, `status`, and `requires`. In a shell: `summer open --list`.
+4. **List when you do not know the id.** `studio.open({})` returns every target with `surface`, `status`, and `requires`. In a shell: `summer open --list`.
 
 ## Read the result honestly
 
@@ -51,7 +53,7 @@ Use `open: false` (CLI: `--print`) and paste the `url` (or `login_url`) when the
 
 ## Editor targets
 
-The editor owns its own table of destinations (the `Navigate` op) and tells the tool which ids it can open. `summer_open({})` lists every editor id with `availability`: `available` (Navigate op), `legacy` (an older engine serving it through its original op), `unavailable` (update Summer Engine), `unknown` (engine not running). Ids: `scene` (default = the project's main scene), `main-scene`, `node`, `script` (with `line`), `file`, `files`, `scene-tree`, `inspector`, `import-dock`, `signals-dock`, `changes-dock`, `screen-2d/3d/script/game/assetlib`, `viewport-show/hide`, `assistant`, `project-settings`, `editor-settings`, `output`, `debugger`, `editor-window`. On a legacy engine, `script` opens without taking focus — mention it if the user does not see it.
+The editor owns its own table of destinations (the `Navigate` op) and tells the tool which ids it can open. `studio.open({})` lists every editor id with `availability`: `available` (Navigate op), `legacy` (an older engine serving it through its original op), `unavailable` (update Summer Engine), `unknown` (engine not running). Ids: `scene` (default = the project's main scene), `main-scene`, `node`, `script` (with `line`), `file`, `files`, `scene-tree`, `inspector`, `import-dock`, `signals-dock`, `changes-dock`, `screen-2d/3d/script/game/assetlib`, `viewport-show/hide`, `assistant`, `project-settings`, `editor-settings`, `output`, `debugger`, `editor-window`. On a legacy engine, `script` opens without taking focus — mention it if the user does not see it.
 
 ## Anti-patterns
 
@@ -59,3 +61,18 @@ The editor owns its own table of destinations (the `Navigate` op) and tells the
 - Opening the scene in the editor **before** the change landed ("show me" comes after the mutation and its screenshot).
 - Guessing a `gameId`. Open `my-games` and let the user pick, or read the id from a URL they gave you.
 - Describing a page you did not open. If `ok` is false, the user saw nothing.
+
+<!-- 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_get_project_context` | `summer engine get-project-context` |
+| `summer_is_running` | `summer engine is-running` |
+| `summer_play` | `summer engine play` |
+| `store.publish` | `summer store publish` |
+| `studio.open`, `summer_open` | `summer studio open` |
+<!-- /shell-commands -->

package/library/skills/navigate-summer/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/navigate-summer
 kind: skill
 version: 1.0.0
-summary: When to open a Summer web page or editor surface FOR the user (billing, their games, the scene just built) versus acting through the API, using summer_open.
+summary: "Open a Summer web page or editor surface for the user (billing, their games, a scene) with studio.open."
 use_when:
   - the user asks to see, check, or decide something — "show me my billing", "where do I change my plan", "open my games", "let me look at the scene", "take me to the MCP guide for Cursor"
   - deciding whether to open a surface for the user or to do the work through Summer tools

package/library/skills/new-project/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: new-project
-description: "Create a fresh blank Summer Engine project — asks one question (project name) and runs summer create empty."
+description: "Create a blank Summer Engine project: ask for the project name and run summer create empty."
 license: MIT
 compatibility: [Cursor, Claude Code, Codex, Windsurf, Gemini, OpenCode]
 category: scene-and-project
@@ -102,3 +102,14 @@ Ask: "Project is open. What do you want to build?"
 ## Closing
 
 End with: "Project `<name>` is created and open. What do you want to build 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` |
+| `summer_replace_node` | `summer engine replace-node` |
+<!-- /shell-commands -->

package/library/skills/new-project/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/new-project
 kind: skill
 version: 1.0.4
-summary: Create a fresh blank Summer Engine project — asks one question (project name) and runs summer create empty.
+summary: "Create a blank Summer Engine project: ask for the project name and run summer create empty."
 use_when:
   - the user wants a fresh blank Summer Engine project — from scratch, blank canvas
   - starting a Summer Engine project with no template, only a name, ready for an empty main scene

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

@@ -1,11 +1,11 @@
 ---
 name: organic-model
-description: "Generate organic 3D shapes — trees, rocks, mushrooms, coral, plants, vines, crystals — where AI artifacts read as natural irregularity."
+description: "Generate organic 3D shapes (trees, rocks, mushrooms, plants, crystals) where irregularity looks natural."
 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/organic/**", "assets/models/**", "**/*.tscn", "**/*.gd"]
 ---
 
@@ -15,7 +15,7 @@ Organic shapes (trees, rocks, mushrooms, coral, alien flora, crystals, vines, bo
 
 This is the cheapest, fastest way to fill out a scene, and the first choice when the user says "this scene feels empty". The failure rate is the lowest of any 3D-asset family.
 
-Backing tool: `summer_generate_3d`. Default `hunyuan` works well here, but `trellis` is faster and the quality difference is hard to see on organic shapes. Pick `trellis` when generating many at once.
+Backing operation: `assets.generate_3d` (it answers with a job: `jobs.wait` until it finishes). Default `hunyuan` works well here, but `trellis` is faster and the quality difference is hard to see on organic shapes. Pick `trellis` when generating many at once.
 
 ## When to use
 
@@ -41,12 +41,12 @@ Organic geometry tolerates aggressive polycount cuts because the silhouette is i
 
 | Use case | Tris | Pass via |
 |---|---|---|
-| Hero tree (mid-distance, prominent) | 4k–8k | `target_polycount: 6000` |
-| Background tree (forest filler) | 1k–3k | `target_polycount: 2000` |
-| Distant tree (use billboard imposter) | 200–500 | `target_polycount: 400` |
-| Large rock / boulder | 800–2000 | `target_polycount: 1500` |
-| Small organic (mushroom, fruit, crystal) | 300–1000 | `target_polycount: 600` |
-| Vine / branch decoration | 200–500 | `target_polycount: 400` |
+| Hero tree (mid-distance, prominent) | 4k–8k | `targetPolycount: 6000` |
+| Background tree (forest filler) | 1k–3k | `targetPolycount: 2000` |
+| Distant tree (use billboard imposter) | 200–500 | `targetPolycount: 400` |
+| Large rock / boulder | 800–2000 | `targetPolycount: 1500` |
+| Small organic (mushroom, fruit, crystal) | 300–1000 | `targetPolycount: 600` |
+| Vine / branch decoration | 200–500 | `targetPolycount: 400` |
 
 Generating a forest? Make 3 hero trees + 5 background trees + 3 rocks at low polycount, then scatter via `MultiMeshInstance3D` for hundreds of copies at near-zero rendering cost.
 
@@ -55,7 +55,7 @@ Generating a forest? Make 3 hero trees + 5 background trees + 3 rocks at low pol
 ### 1. Search before generating
 
 ```
-summer_search_assets(query="<organic type>", assetType="3d_model", source="all")
+assets.search({ query: "<organic type>", assetType: "3d_model", scope: "all" })
 ```
 
 ### 2. Build the prompt
@@ -90,14 +90,16 @@ For batch generation, batch the confirmation:
 
 > About to generate 3 trees + 3 rocks + 5 mushrooms (11 generations, ~5 min). All low-poly via `trellis`. OK?
 
+`dryRun: true` on one call gives its credits (`estimate.credits`) for the batch confirmation. Start every generation of the batch first, then wait on the jobs.
+
 ```
-summer_generate_3d(
-  prompt="A tall pine tree with dense green needles and a straight trunk, slight lean. Game asset, stylized low-poly game art, white background, isolated object.",
-  model="trellis",
-  options={ target_polycount: 2000 },
-  wait=true
-)
-summer_get_asset(assetId="<assetId>")
+assets.generate_3d({
+  prompt: "A tall pine tree with dense green needles and a straight trunk, slight lean. Game asset, stylized low-poly game art, white background, isolated object.",
+  model: "trellis",
+  targetPolycount: 2000
+})
+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/organic/pine_tree_01.glb")
 ```
 
@@ -168,6 +170,10 @@ In a 200-tree forest, only the ~10 closest trees need to be real meshes; the oth
 - **Crystal/glass organic.** Mesh comes back opaque. Generate the geometry, then assign a `StandardMaterial3D` with `transparency = ALPHA` and emissive in the editor.
 - **Bones, skulls, dead trees.** All work; organic forgives them more than props would. Add `weathered, sun-bleached` for desert / tundra feel.
 
+## 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 and skip steps 5-6 (scene wiring, LOD). Save the file where the person asked with `out` (the `summer-assets` skill says how), and tell them the path and format. The file is GLB; level of detail and billboards are the person's engine's job.
+
 ## Fallback (no MCP)
 
 1. Run prompts at the Summer dashboard or any 3D-gen web playground (Hunyuan, Trellis, Meshy).
@@ -193,4 +199,28 @@ After the organic models are scattered:
 - `environment-kit` — pair with this skill: kit pieces give the architecture, organic gives the natural softness.
 - `asset-strategy` — meta-router; ground textures and skyboxes go to Pipeline 2 / panoramic gen.
 - `scene-composition` — MultiMeshInstance3D scatter pattern.
-- `../../references/mcp-tools-reference/mcp-tools-reference.md` — `summer_generate_3d` schema.
+- `summer_docs_read` id `reference/mcp-tools-reference` — how to call `assets.generate_3d`; `summer_search` returns its 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` |
+| `summer_assets_generate_image` | `summer assets generate-image` |
+| `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_instantiate_scene` | `summer engine instantiate-scene` |
+| `summer_save_scene` | `summer engine save-scene` |
+| `summer_set_prop` | `summer engine set-prop` |
+| `jobs.wait`, `summer_jobs_wait` | `summer jobs wait` |
+| `summer_search` | `summer ops search "<what you want>"` |
+<!-- /shell-commands -->

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

@@ -1,7 +1,7 @@
 id: skill/organic-model
 kind: skill
 version: 1.0.3
-summary: Generate organic 3D shapes — trees, rocks, mushrooms, coral, plants, vines, crystals — where AI artifacts read as natural irregularity.
+summary: "Generate organic 3D shapes (trees, rocks, mushrooms, plants, crystals) where irregularity looks natural."
 use_when:
   - generating organic shapes — trees, rocks, mushrooms, coral, bushes, alien plants, vines, crystals, fruit, bones
   - a level needs vegetation, rocks, or other natural shapes where irregularity reads as realism