summer-engine 4.5.0 → 4.8.0

package/library/skills/README.md

@@ -1,6 +1,6 @@
 # Summer skills
 
-> 132 skills, grouped by their primary domain. **Generated** by `npm run generate:registry` from each skill's `resource.yaml`; `--check` fails when this file and the library disagree. Do not edit by hand.
+> 133 skills, grouped by their primary domain. **Generated** by `npm run generate:registry` from each skill's `resource.yaml`; `--check` fails when this file and the library disagree. Do not edit by hand.
 
 The folder is flat on purpose (`docs/design/DECISIONS.md`, D3): a skill usually belongs to several domains, so categories live in each skill's `facets.domains` and this index is rendered from them. The first domain listed is the primary one. `summer skills list --by-domain` prints the same grouping; `summer skills info <slug>` shows one skill.
 
@@ -13,7 +13,7 @@ Status: **stable** unless marked; *preview* = not yet exercised in-engine by the
 - [agent-workflow](#agent-workflow) (19)
 - [ai](#ai) (2)
 - [animation](#animation) (7)
-- [assets](#assets) (4)
+- [assets](#assets) (5)
 - [audio](#audio) (6)
 - [character-controller](#character-controller) (2)
 - [creator](#creator) (7)
@@ -89,8 +89,8 @@ Status: **stable** unless marked; *preview* = not yet exercised in-engine by the
 
 | skill | when to use | also |
 |---|---|---|
-| [*ai-characters-in-games*](./ai-characters-in-games/SKILL.md) (preview) | Safe AI characters in published games: no keys in the build, Summer's player AI gateway, moderation, caps. | npc |
 | [design-npc](./design-npc/SKILL.md) ★ | Design enemy, NPC, boss or companion behavior: perception, state machine, telegraphs, script stub. | npc |
+| [*summer-router*](./summer-router/SKILL.md) (preview) | AI characters for games on Summer Games: Summer Router replies, tools, speech, images. | npc, multiplayer |
 
 ## animation
 
@@ -111,7 +111,8 @@ Status: **stable** unless marked; *preview* = not yet exercised in-engine by the
 | [asset-strategy](./asset-strategy/SKILL.md) ★ | Route any 'I need a [thing]' asset request to the right skill: 2D, 3D, audio, video, VFX or animation. | pipeline |
 | [*lumera-single-image-scene-reconstruction*](./lumera-single-image-scene-reconstruction/SKILL.md) (preview) (library only) | Lumera-style single image to editable 3D scene — VLM-parsed object boxes and parametric lights, per-object meshes, HDR probe, .tscn assembly, refinement loop. | pipeline, 3d, scenes |
 | [*skintokens-auto-rigging*](./skintokens-auto-rigging/SKILL.md) (preview) (library only) | Offline auto-rigging with skin-tokens.cpp (GGML SkinTokens/TokenRig port) — skeleton and skin weights from a static GLB mesh on CPU/Vulkan, into Summer Engine. | pipeline, 3d, animation |
-| [summer-assets](./summer-assets/SKILL.md) | Make game assets with Summer, no Summer Engine: find, generate and download 3D models, images, audio and video for any engine or app. | agent-workflow |
+| [*summer-api*](./summer-api/SKILL.md) (preview) | Summer API game assets: models, estimate, one job or a batch, download the files. | agent-workflow |
+| [summer-assets](./summer-assets/SKILL.md) | Game assets for any engine, no Summer Engine: find, generate and download them. | agent-workflow |
 
 ## audio
 
@@ -207,7 +208,7 @@ Status: **stable** unless marked; *preview* = not yet exercised in-engine by the
 
 | skill | when to use | also |
 |---|---|---|
-| [navigate-summer](./navigate-summer/SKILL.md) ★ | Open a Summer web page or editor surface for the user (billing, their games, a scene) with studio.open. | agent-workflow, meta |
+| [navigate-summer](./navigate-summer/SKILL.md) ★ | Open a Summer page or editor view for the person: studio.open, and engine.view_set while you work. | agent-workflow, meta |
 
 ## performance
 

package/library/skills/design-npc/SKILL.md

@@ -493,7 +493,7 @@ For an animated NPC in a runnable project: `summer create 3d-fps-simple-animated
 ## See also
 
 - `animation-tree` — wire the action states to animation clips
-- `ai-characters-in-games` — NPCs that answer free-form player text
+- `summer-router` — NPCs that answer free-form player text in a game on Summer Games
 - `vfx-hit-spark` — hit flash recipe
 - `vfx-dissolve` — death dissolve recipe
 - `game-feel` — screen-feel discipline (camera shake, hit-stop)

package/library/skills/design-npc/resource.yaml

@@ -1,6 +1,6 @@
 id: skill/design-npc
 kind: skill
-version: 1.0.2
+version: 1.0.3
 summary: "Design enemy, NPC, boss or companion behavior: perception, state machine, telegraphs, script stub."
 use_when:
   - designing an enemy, NPC, boss, companion, civilian, or wave-spawned mob's behavior — perception, intent, state machine, telegraphs, defeat handling
@@ -21,6 +21,7 @@ related:
     - skill/game-feel
     - skill/vfx-dissolve
     - skill/vfx-hit-spark
+    - skill/summer-router
 source: official
 license: MIT
 status: stable

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

@@ -48,7 +48,7 @@ These rules from the playbooks apply to every genre:
 
 - **2D scales to the viewport.** Set `display/window/stretch/mode = canvas_items` and `stretch/aspect = expand`; UI uses Control anchors; code-positioned nodes compute from `get_viewport_rect().size`. Never hardcode 1920x1080.
 - **Playable slice, not tech demo.** Name the core loop in one sentence; every input gets feedback (tween, sound, particle, flash, shake); progression is visible; a restart exists. The bar is "feels good for 30 seconds".
-- **Fast first draft when someone is waiting.** The first playable version uses shapes, the palette and any template art, plus at most one or two generated assets the person specifically asked for; generation takes minutes, so it never blocks the first play. Say plainly that it is a first draft to get a feel for the game, that the art is not final, and ask if this is the direction they want. Generate the rest of the art in later passes.
+- **The first playable already looks good.** People judge Summer by the first frame of their first game, so the first version looks finished even when they ask for a quick prototype: keep the features they asked for and raise the look. Sky and sun with shadows, tonemapping and a little fog; a texture on every surface; real models for the player, characters and main props from the starter project or the Summer asset library (`summer_assets_search`), never capsules or boxes as final art; one colour palette; a styled UI font. Generation takes minutes, so it never blocks the first play: use starter and library art first, plus at most one or two generated assets the person asked for, and generate the rest in later passes. Before you say it is ready, play it and look at a screenshot of the running game, not the editor (the editor shows a preview sky and sun that the game does not have).
 - **A way back to the title.** From inside play, a pause menu or a **Leave** button returns to the title screen without quitting the app.
 - **Text the default font can show.** No emoji or symbols (▲ ◀ ★ ♥ ✓) in UI text: they render as boxes with hex codes. Use words or icons; see `ui-basics`.
 
@@ -201,7 +201,7 @@ Repeat until every mechanic in the plan is implemented OR the user calls cut.
 
 ## Phase 5: Layer (look + sound)
 
-**Goal**: the game stops looking like a programmer art prototype.
+**Goal**: deepen the look and add sound. The first playable already looks good (see "The first playable already looks good" above); this phase writes the art bible, replaces the remaining stand-in art and adds audio.
 
 ```
 Skill: art-direction
@@ -276,7 +276,7 @@ If the brief said "jam" or "prototype", skip this phase. If the brief said "game
 |---|---|
 | Skip the brainstorm because the user said "FPS" | Even with the genre named, you need the scope cut list. Otherwise mechanic 4 quietly sneaks in and the game never ships. |
 | Let mechanic 2 start before mechanic 1 is verified clean | Compounding bugs. You'll spend the rest of the session debugging which mechanic broke what. |
-| Stack art direction on top of unfinished mechanics | Art changes are reversible only if the underlying scene structure is stable. Get mechanics done first. |
+| Change the art style while mechanics are unfinished | Art changes are reversible only if the underlying scene structure is stable. Get mechanics done before a new style; the first playable still starts good-looking. |
 | Treat "polish" as required | If the brief says "jam in 2 days", polish is a cut item. Respect the brief. |
 | Run all phases without confirming | The user owns scope. Stop at every checkpoint. |
 | Ship online play behind a setting nobody changes | Hosted join is never exercised, so it breaks without anyone noticing. Reachable by default, or the owner joins online before every release. |
@@ -313,7 +313,7 @@ No Summer MCP tools in this session? Run each one as a command; when `summer --v
 
 | In this skill | Command |
 |---|---|
-| `assets.search` | `summer assets search` |
+| `assets.search`, `summer_assets_search` | `summer assets search` |
 | `summer_docs_read` | `summer docs read` |
 | `summer_add_node` | `summer engine add-node` |
 | `summer_batch` | `summer engine batch` |

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

@@ -1,11 +1,11 @@
 ---
 name: navigate-summer
-description: "Open a Summer web page or editor surface for the user (billing, their games, a scene) with studio.open."
+description: "Open a Summer page or editor view for the person: studio.open, and engine.view_set while you work."
 license: MIT
 compatibility: [Cursor, Claude Code, Codex, Windsurf, Gemini, OpenCode, Factory, Copilot]
 category: _meta
 user-invocable: true
-allowed-tools: summer_call summer_get_project_context summer_is_running
+allowed-tools: summer_call summer_get_project_context summer_is_running summer_view_set summer_frame_shot
 paths: ["**/project.godot", "**/*.tscn", "**/.summer/**"]
 ---
 
@@ -55,6 +55,26 @@ Use `open: false` (CLI: `--print`) and paste the `url` (or `login_url`) when the
 
 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.
 
+## While you work: what to open when
+
+When you drive Summer Engine from outside (Claude Code, Codex, Cursor, the `summer` CLI), the person is not using the in-app chat. The editor is their window onto your work. A line at the bottom of it names your app and says what you are doing ("Claude Code · Placing 12 trees"). You choose what they see with `engine.view_set` (3.x `summer_view_set`): `view` (`3d`, `2d`, `script`, `game`, `chat`, `home`, `studio`), optional `rail` (`scene`, `inspector`, `files`, `output`, `none`), optional `focus` and optional `frame`. A node path in `focus` selects that node; a `res://` script or scene opens. `frame` lists the nodes to frame the camera on. Switching is instant and changes nothing in the game.
+
+| You are about to… | Show |
+|---|---|
+| Edit a scene (place, move, remove nodes) | `{"view": "3d", "rail": "scene", "focus": "<the node or group you edit>", "frame": ["<it>"]}`; a 2D game uses `"2d"` |
+| Write or fix a script | `{"view": "script", "focus": "res://<the script>.gd"}` |
+| Tune one node's properties | `{"view": "3d", "rail": "inspector", "focus": "<that node>"}` |
+| Playtest | `{"view": "game"}`, then play the game |
+| Review how it looks | a `summer_frame_shot` of the result |
+| Read errors or logs with the person | `{"view": "3d", "rail": "output"}` |
+| Finish | the best view of the result: the game in `game` for gameplay work, the framed scene in `3d` or `2d` for level and art work, the script for code-only changes |
+
+- Open the view before the first edit of a step, so the person watches the change happen.
+- Focus what you change, not the scene root; for a group, focus its parent.
+- Make one call when the kind of work changes, not one per edit.
+- End on the result, never on an empty or unrelated view.
+- When the person is using the in-app chat, let them choose the view.
+
 ## Anti-patterns
 
 - Opening `billing` or `pricing` when the user asked about a **feature**, not money.
@@ -75,6 +95,7 @@ No Summer MCP tools in this session? Run each one as a command; when `summer --v
 | `summer_is_running` | `summer engine is-running` |
 | `summer_play` | `summer engine play` |
 | `summer_screenshot` | `summer engine screenshot` |
+| `engine.view_set`, `summer_view_set` | `summer engine view-set` |
 | `store.publish` | `summer store publish` |
 | `studio.open`, `summer_open` | `summer studio open` |
 <!-- /shell-commands -->

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

@@ -1,11 +1,12 @@
 id: skill/navigate-summer
 kind: skill
-version: 1.0.0
-summary: "Open a Summer web page or editor surface for the user (billing, their games, a scene) with studio.open."
+version: 1.0.1
+summary: "Open a Summer page or editor view for the person: studio.open, and engine.view_set while you work."
 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
+  - deciding whether to open a surface (a page of the website) for the user or to do the work through Summer tools or an API
   - handing the user a link (headless, remote, or the user prefers a link) instead of launching a browser
+  - "you drive Summer Engine from outside (Claude Code, Codex, Cursor, the summer CLI) and the editor should show what you work on: the view, rail and focus for editing, scripting, playtesting, review and the end result"
 do_not_use_when:
   - the user wants a change made — add/set/remove nodes, publish, generate; use the build skills and mutation tools
   - opening a project directory in the engine — `summer run <path>`
@@ -25,6 +26,7 @@ compatibility:
 related:
   tools:
     - tool/open
+    - tool/view-set
   references:
     - reference/product-map
   skills:

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

@@ -0,0 +1,198 @@
+---
+name: summer-api
+description: "Summer API game assets: models, estimate, one job or a batch, download the files."
+license: MIT
+compatibility: [Cursor, Claude Code, Codex, Windsurf, Gemini, OpenCode, Factory, Copilot]
+category: _meta
+user-invocable: false
+allowed-tools: Bash Read Write summer_api_models summer_api_estimate summer_api_run summer_api_batch summer_api_job
+---
+
+# Summer API: game assets for any agent
+
+The Summer API makes game assets from curated models tested for games: 3D models (GLB), images, video, voice lines, dialogue, sound effects and music. Each finished file is saved to the person's Summer library and downloads into their project. Every model runs at the provider's list price, with no markup on assets.
+
+Use this skill when the person asks for the Summer API, or wants asset files for any engine, app or pipeline from a script, a batch or a coding agent. Inside a running Summer Engine project, the asset skills (`prop-model`, `character-model`, `sound-effect`, ...) import the asset into the scene for you; use them there.
+
+Two ways in, with the same calls and the same answers:
+
+| You have | Use |
+|---|---|
+| A shell | `summer api ...` commands. If `summer --version` is missing or below 4.8, write `npx -y summer-engine@latest` in place of `summer`. |
+| Summer's local MCP server | The tools `summer_api_models`, `summer_api_estimate`, `summer_api_run`, `summer_api_batch` and `summer_api_job` |
+
+Your own code calls the same API over HTTP. The HTTP guide, the OpenAPI document and copy-paste code are on docs.summerengine.com/api (quickstart, jobs, errors).
+
+## 1. Sign in once
+
+```bash
+summer login
+```
+
+The browser opens the Summer sign-in page. The person signs in, picks a spend limit for this app and chooses **Allow**. Tell them the browser opens, and wait for them. The sign-in renews itself; do it once per computer. There are no API keys.
+
+- `summer token` prints a one-hour access token from the same sign-in, for the person's own HTTP code. Keep tokens out of game code, builds and commits.
+- Listing models and estimating need no sign-in. Running a job does.
+- The person sees and changes each app's spend limit, or revokes it, in Settings > Connected apps on summerengine.com.
+
+## 2. Pick a model
+
+```bash
+summer api models --capability 3d
+summer api models 3d/default
+```
+
+MCP: `summer_api_models({ capability: "3d" })`, `summer_api_models({ model: "3d/default" })`.
+
+- Capabilities: `image`, `3d`, `video`, `voice`, `dialogue`, `sound`, `music`.
+- `<capability>/default` (such as `3d/default`) runs the model Summer tests first for that job. A job answer names the model that ran in `model`, so you can run the same model again.
+- Each model lists its `inputSchema` (the exact fields), `outputFormats`, typical time and `price`. Read prices from this list every time, never from memory.
+- Voice and dialogue models list `voices` (`voiceId` and `name`). Use one of those ids.
+
+## 3. Price it, then ask
+
+```bash
+summer api estimate 3d/default --input '{"kind": "text-to-3d", "prompt": "a stylized treasure chest, game prop"}'
+```
+
+MCP: `summer_api_estimate({ model: "3d/default", input: { kind: "text-to-3d", prompt: "a stylized treasure chest, game prop" } })`.
+
+The answer has `price` (US dollars as a decimal string), `atMost` (`true`: the most it can cost, the charge can be lower), a `breakdown`, and a `quoteId` that holds the price for 15 minutes. Estimates are free.
+
+Before you spend: tell the person what you will make, how many, and the total. Wait for a yes. Jobs spend their paid Summer credits (plan credits and top-ups).
+
+## 4. Run one job
+
+```bash
+summer api run 3d/default \
+  --input '{"kind": "text-to-3d", "prompt": "a stylized treasure chest, game prop"}' \
+  --quote <quoteId> --download assets/props
+```
+
+MCP: `summer_api_run({ model: "3d/default", input: { kind: "text-to-3d", prompt: "a stylized treasure chest, game prop" }, quoteId: "<quoteId>", out: "assets/props" })`.
+
+- `--download <dir>` (MCP `out`) follows the job to the end and saves every file as `<assetId>.<ext>`. `--wait` (MCP `wait: true`) follows it without saving.
+- `--quote` (MCP `quoteId`): Summer refuses to charge more than the quote. If the price went up, the job does not start and nothing is charged (`conflict`): estimate again.
+- Images, voice and sound usually finish inside the call. 3D and video take minutes: one MCP call follows a job for about a minute, then answers `next`. Call `summer_api_job({ jobId, wait: true })` until the job finishes. The CLI follows it to the end by itself.
+- In Windows PowerShell or cmd, write the input to a file and pass `--input "@input.json"`: those shells break quotes inside `'{...}'`.
+- Each run sends its own idempotency key, so a retried request never runs twice. To retry the same run by hand, pass the same `--idempotency-key` (MCP `idempotencyKey`).
+
+## 5. Run many: a batch
+
+For a set of assets (props for a level, every UI icon, a sound pack), send one batch instead of many runs. One batch takes up to 500 jobs, all or none.
+
+```jsonl
+{"model": "3d/default", "input": {"kind": "text-to-3d", "prompt": "a wooden barrel with iron bands, game prop"}}
+{"model": "3d/default", "input": {"kind": "text-to-3d", "prompt": "a mossy stone well, game prop"}}
+{"model": "image/default", "input": {"prompt": "a red health potion icon, flat fantasy style, centered", "removeBackground": true}}
+{"model": "sound/default", "input": {"text": "glass potion bottle uncorked, short pop", "durationSeconds": 1}}
+```
+
+```bash
+summer api run --batch jobs.jsonl --download assets
+```
+
+MCP: `summer_api_batch({ jobs: [{ model: "3d/default", input: { kind: "text-to-3d", prompt: "a wooden barrel with iron bands, game prop" } }], out: "assets" })`. Read it again with `summer_api_batch({ batchId: "<id>", wait: true, out: "assets" })`.
+
+- Every job is priced when the batch arrives. When the paid credits and the app's limit cover all of them, all are accepted at once and run in order; each holds its price (`estimatedPrice` on the job, the total on the batch). When they do not, nothing runs: the error's `details` say how many fit (`fits`) and how much more is needed (`shortUsd`).
+- The batch answers its jobs in the order you sent them. Give each job a `title` where the model takes one (3D and image models do): it names the asset in the person's library.
+- A batch takes no `quoteId`. Estimate each distinct request first (same model and input, same price), add them up, and give the person the total for the whole batch.
+- Each line may carry its own `idempotencyKey`; the batch has one too (`--idempotency-key`). To pick up a batch after the terminal closed, run the same command with the same `--idempotency-key`: it answers the batch it already made and follows it. MCP: `summer_api_batch({ batchId, wait: true })`.
+
+## 6. Follow and read
+
+```bash
+summer api jobs <jobId> --download assets   # follow it and save its files
+```
+
+MCP: `summer_api_job({ jobId: "<jobId>", out: "assets" })`.
+
+A Summer API job runs to the end once it is accepted, queued or running: it cannot be cancelled. A job that fails costs nothing. So confirm the list with the person before you send it.
+
+| `state` | Means | Do |
+|---|---|---|
+| `queued` | Waiting for one of the account's running slots; its price is held | Keep following; it starts in order |
+| `running` | Working; `progress` 0 to 100 when known | Keep following |
+| `done` | Finished; `result.assets` has the files | Download them |
+| `failed` | It did not work; nothing is charged | Show `error.message`; change the input or the model |
+| `cancelled`, `expired`, `stale`, `declined` | Stopped without a result | Start a new job if the person still wants it |
+
+A finished job has `result.assets`: one entry per file, each with `assetId`, `fileUrl` and `thumbnailUrl`. The file type is the extension of `fileUrl` (the model's `outputFormats` lists them). Job ids may hold a colon (`gen:...`, `q:...`); send them as they are.
+
+With `--json`, or when its output is piped, every command prints the API's own answer: `{"job": {...}}` for a run or a job (plus `"files"` with `--download`), `{"batch": {...}}` for a batch, the estimate's fields at the top level, and `{"ok": false, "error": {"code", "message", "details"}}` on an error. In a terminal it prints a short summary.
+
+## Limits: money only
+
+- **No rate limits on paid usage.** Send as much work as the person agrees to pay for.
+- **Running slots.** Each account runs 10 jobs at once at the start, and up to 40 as it buys more credits. Jobs past the slots answer `queued` (their id starts with `q:`) and start in order as slots free up. Queued work is not an error; do not resend it.
+- **Two money limits**, both checked before any work starts: the person's paid balance and this app's own spend limit. Queued and running jobs hold their price against both until they are charged.
+- **A failed job costs nothing.** A retry with the same idempotency key never charges twice.
+
+## Errors
+
+Every error has a stable `code` and a `message` written for the person. Branch on the code; show the message.
+
+| Code | Means | Do |
+|---|---|---|
+| `not_signed_in` | No sign-in, the app was revoked, or a `summer token` older than an hour | CLI and MCP: run `summer login`, then retry. Own HTTP code: get a new `summer token` |
+| `no_credits` | The paid balance cannot cover the job or the batch | Show the message: it links where to add credits. Do not retry until the person tops up |
+| `over_limit` | This app's own spend limit is reached | Show the message: the person raises the limit in Connected apps, or waits for it to reset |
+| `invalid_input` | The input does not match the model, or the `quoteId` expired | Fix the field the message names (`param`); read the model's `inputSchema`. An expired quote: estimate again |
+| `not_found` | No such model, job or batch | Model ids come from `summer api models` |
+| `conflict` | The price went up since your quote | Estimate again; nothing was charged |
+| `idempotency_conflict` | The key was used for a different request | Use a new key for a new job |
+| `in_progress` | The first request with this key is still running | Send the same request again shortly |
+| `outcome_unknown` | Summer could not tell if the work started | Send the same request with the same key; never start a new job |
+| `unavailable` | A model or service is down for a moment | Retry with backoff, or pick another model for the same job |
+| `unsupported` | The job cannot do that (a cancel) | Let the job finish |
+
+`no_credits` and `over_limit` are answers about money, not failures: stop, show the person the message and its link, and continue when they say so.
+
+## Prompts that work, per asset type
+
+Write prompts as plain descriptions of the thing itself. Put the style in every prompt of a set, word for word, so the assets match.
+
+| Asset | Model | Input that works |
+|---|---|---|
+| Prop | `3d/default` | `{"kind": "text-to-3d", "prompt": "a wooden treasure chest with iron trim, stylized low-poly, game prop"}`. One object per job. Add `"targetPolycount": 3000` for a light mesh. |
+| Character | `3d/default` | `{"kind": "text-to-3d", "assetIntent": "character", "poseMode": "a-pose", "rig": true, "animationNames": ["Idle", "Walk", "Run"], "prompt": "a dwarf blacksmith, full body, stylized"}`. Full body, one character, neutral pose. |
+| 3D from concept art | `3d/default` | `{"kind": "image-to-3d", "imageUrl": "<public URL>"}`. A clean picture of one object on a plain background. |
+| Concept art, key art | `image/default` | `{"prompt": "...", "aspectRatio": "16:9"}`. Name the subject, the setting, the light and the style. |
+| Icon, sprite, item | `image/default` | `{"prompt": "a red health potion, centered, flat fantasy style", "removeBackground": true}`. One object, centered; a transparent PNG comes back. |
+| Matching set | `image/default` | Send the first image's `fileUrl` as `referenceImageUrl` in the next jobs, and keep the same `seed` and style words. |
+| Sound effect | `sound/default` | `{"text": "heavy wooden door creaks open, stone hall echo", "durationSeconds": 2}`. Source, action, material, space. `"loop": true` for ambience. |
+| Voice line | `voice/default` | `{"text": "Halt! Who goes there?", "voiceId": "<from the model's voices>"}`. Punctuation sets the delivery. |
+| Conversation | `dialogue/default` | `{"inputs": [{"text": "...", "voiceId": "..."}, {"text": "...", "voiceId": "..."}]}`. One entry per line, up to 40. |
+| Music | `music/default` | `{"prompt": "calm medieval village theme, lute and flute, 90 bpm, loopable", "durationSeconds": 60}`. Genre, mood, instruments, tempo. |
+| Video | `video/default` | `{"prompt": "slow camera push toward a castle at dawn", "duration": 5}`, or `imageUrl` to animate key art. One shot per job. |
+
+A picture input (`imageUrl`, `referenceImageUrl`) is a public URL, such as the `fileUrl` of an earlier job. For a file on the person's computer, the docs' jobs page shows the upload (`/v1/files`).
+
+## Without Summer Engine
+
+This whole skill runs without Summer Engine: the CLI, the MCP tools and the HTTP API need only the Summer sign-in. The files work in any engine or app. Stop at the files; skip any step that imports into a Summer project.
+
+## Use the files
+
+- Save files inside the project (`--download assets/...`), and keep each `assetId`: in Summer Engine, an asset imports by its id.
+- GLB files are Y up and not at real-world size. Scale them in the engine (a door about 2 m, a person about 1.7 m).
+- Assets made through the API are private to the person's Summer library. A `fileUrl` downloads without a sign-in, so share it only where the file may be seen.
+
+## Pitfalls
+
+| Pitfall | Do this instead |
+|---|---|
+| Typing a price from memory | Read `summer api models`, then `summer api estimate` |
+| Spending before the person agreed | Estimate, say the total, wait for a yes |
+| Many single runs for a set of assets | One batch: all or none, priced up front |
+| Resending a job that answered `queued` | It is accepted and its price is held. Follow it. |
+| Treating `no_credits` or `over_limit` as a bug to retry | Show the message and its link; wait for the person |
+| A new idempotency key on a retry after a timeout | The same key: it returns the first job, never a second charge |
+| A token or a sign-in in game code | Only the developer's tools sign in. A shipped game uses Summer Router (the `summer-router` skill). |
+| Several objects in one 3D prompt | One object per job; place them in the engine |
+
+## Done means
+
+- Every job you started is `done`, or you told the person which failed and why.
+- The files are in the folder the person asked for, and you told them the paths and formats.
+- You told the person what it cost (`price` on each job, or the batch's `estimatedPrice`).

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

@@ -0,0 +1,38 @@
+id: skill/summer-api
+kind: skill
+version: 1.0.0
+summary: "Summer API game assets: models, estimate, one job or a batch, download the files."
+use_when:
+  - generating asset files (3D models, images, sounds, voice, music, video) from a script, a pipeline or a coding agent outside Summer Engine
+  - making a set of assets in one go (a level's props, every UI icon, a sound pack) as one batch
+  - choosing a generation model, pricing a job before it runs, or reading a job's state and files
+  - a generation job answered no_credits, over_limit, not_signed_in or queued
+do_not_use_when:
+  - generating inside a running Summer Engine project, where the asset skills import into the scene (asset-strategy)
+  - AI that a shipped game calls while people play (summer-router)
+facets:
+  lifecycle:
+    - build
+  domains:
+    - assets
+    - agent-workflow
+  modalities:
+    - 3d-models
+    - images
+    - audio
+    - video
+related:
+  tools:
+    - tool/api-models
+    - tool/api-estimate
+    - tool/api-run
+    - tool/api-batch
+    - tool/api-job
+  skills:
+    - skill/summer-assets
+    - skill/summer-cli
+    - skill/asset-strategy
+    - skill/summer-router
+source: official
+license: MIT
+status: preview

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

@@ -1,6 +1,6 @@
 ---
 name: summer-assets
-description: "Make game assets with Summer, no Summer Engine: find, generate and download 3D models, images, audio and video for any engine or app."
+description: "Game assets for any engine, no Summer Engine: find, generate and download them."
 license: MIT
 compatibility: [Cursor, Claude Code, Codex, Windsurf, Gemini, OpenCode, Factory, Copilot]
 category: _meta

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

@@ -1,7 +1,7 @@
 id: skill/summer-assets
 kind: skill
-version: 1.0.1
-summary: "Make game assets with Summer, no Summer Engine: find, generate and download 3D models, images, audio and video for any engine or app."
+version: 1.0.2
+summary: "Game assets for any engine, no Summer Engine: find, generate and download them."
 use_when:
   - starting a session that has the Summer assets profile (generation tools, no engine tools)
   - the person wants assets for their own engine or web app, not a game built in Summer Engine
@@ -26,6 +26,7 @@ related:
     - tool/get-asset-download-url
   skills:
     - skill/asset-strategy
+    - skill/summer-api
     - skill/sound-effect
     - skill/prop-model
     - skill/concept-art