summer-engine 3.8.0 → 4.2.0

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

@@ -1,11 +1,11 @@
 ---
 name: summer-apps
-description: "Build a Summer App, a team tool inside Summer Studio (balance table, quest editor, tracker, pick grid): build loop, Layout vs code, data as API, agent tools."
+description: "Build a Summer App, a team tool inside Summer Studio (balance table, quest editor, tracker), data and tools."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: tools
 user-invocable: true
-allowed-tools: Read Write Edit Glob summer_app_guide summer_app_list summer_app_create summer_app_publish summer_app_get summer_app_update summer_app_events summer_app_page summer_app_screenshot summer_app_data summer_app_tools summer_app_call summer_app_dock summer_app_report_gap
+allowed-tools: Read Write Edit Glob summer_apps_guide summer_apps_list summer_apps_create summer_apps_publish summer_apps_get summer_apps_update summer_apps_events summer_apps_page summer_apps_use_page summer_apps_screenshot summer_apps_read_data summer_apps_write_data summer_apps_tools summer_apps_call summer_apps_report_gap summer_call
 ---
 
 # Summer Apps
@@ -14,23 +14,27 @@ A Summer App is a tool the person's team uses inside Summer Studio: shared with
 the workspace, live on its assets, game data and engine, dockable in the editor.
 You build it in minutes; the team keeps it.
 
+A call written `area.action({...})` is one operation: use the tool `summer_area_action` when
+your client lists it, else `summer_call({ op: "area.action", input: {...} })`.
+`summer_search` finds any operation and its exact input.
+
 ## First: does Summer already do it?
 
 A custom app is something the team has to maintain. Before you build one, check whether
 Summer already does the job: Studio features (the asset library with its collections and
-groups, Pick one and sound choices, Grow dashboards, Team) and the existing `summer_*` MCP
-tools. If it does, use that and tell the person where it lives.
+groups, Pick one and sound choices, Grow dashboards, Team) and the existing Summer
+operations (`summer_search` finds them). If it does, use that and tell the person where it lives.
 
 Build an app only when the need is real and Summer lacks it, or as a Scratch throwaway (a
 quick asset review, a UI prototype) that you call throwaway when you make it, and archive
-when it is done (`summer_app_update {appId, status: "archived"}`). When
-something is missing natively, report it with `summer_app_report_gap` (and
-`summer_library_feedback` when a library entry fell short), so Summer can build it for
+when it is done (`apps.update({ appId, status: "archived" })`). When
+something is missing natively, report it with `apps.report_gap` (and
+`summer_call` with `docs.feedback` when a library entry fell short), so Summer can build it for
 everyone.
 
 | Ask | Do |
 | --- | --- |
-| "Let me pick from these 12 sword sounds" | Pick one: `summer_generate_sfx_choices`, or put the sounds in a library collection. No app. |
+| "Let me pick from these 12 sword sounds" | Pick one: `assets.generate_sfx_choices`, or put the sounds in a library collection. No app. |
 | "Group our Studio assets into a moodboard for the forest level" | Organize them with the asset library's collections and groups. No app. |
 | "A weapon balance table that writes res://data/weapons.json" | Build an app: nothing in Summer edits game data with the team's balance rules. |
 
@@ -60,13 +64,13 @@ Read these before writing code; they are exact:
   return shape.
 - [manifest.md](manifest.md): every manifest field.
 - The kit's component catalog (every `<summer-*>` element with attributes, events and a
-  copyable example) is `summer_app_guide` section `kit`, also at `/summer-ui/v1/catalog.json`
+  copyable example) is `apps.guide({ section: "kit" })`, also at `/summer-ui/v1/catalog.json`
   on the app host. Copy its examples instead of inventing markup.
 
-To see an app, publish it and call `summer_app_screenshot {appId}`: Summer renders it headless
+To see an app, publish it and call `apps.screenshot({ appId })`: Summer renders it headless
 with the person's data and returns the picture plus the console, uncaught errors, refused calls
 and the fields and buttons it declared. No Studio tab needed; the person sees it at
-`/studio/apps/<appId>` (`summer_app_create` opens it for them). Opening `index.html` on its own
+`/studio/apps/<appId>` (`apps.create` opens it for them). Opening `index.html` on its own
 never connects. There is no offline host: do not build one or mock the SDK.
 
 The app is served from its own host, apps.summerengine.app. Load the SDK and the kit as
@@ -76,30 +80,33 @@ the first call, and reach data only through `summer.data.collection(name)`.
 
 ## The loop
 
-1. `summer_app_guide` (whole once per session; later one `section`). Load the
-   `summer-apps-design` skill for how it must look.
-2. `summer_app_create {name, purpose, format}`. The person's Studio tab opens it.
-3. Write the files in a local folder, then `summer_app_publish {appId, dir, manifest, note}`
-   (or `layout`). Each publish is an immutable version the tab boots. A publish
-   error names the file or rule: fix it and publish again.
-4. Seed starter data with `summer_app_data` (`ops` plus `"as": "seed"`) when the app should
+1. `apps.guide({ section: "overview" })` first, then `examples` and the sections the app needs.
+   Load the `summer-apps-design` skill for how it must look.
+2. `apps.create({ name, purpose, format })`. The person's Studio tab opens it.
+3. Write the files in a local folder, then `apps.publish({ appId, files, manifest, note })` with
+   every file as `{ path, content, encoding }` (`index.html` at the root; or `layout` for a layout
+   app). Each publish is an immutable version the tab boots. A publish error names the file or
+   rule: fix it and publish again.
+4. Seed starter data with `apps.write_data({ appId, ops, as: "seed" })` when the app should
    start full. Seed rows belong to the team and show no author.
-5. Look at it: `summer_app_screenshot {appId}`, then `width: 390` (phone) and `theme: "dark"`.
+5. Look at it: `apps.screenshot({ appId })`, then `width: 390` (phone) and `theme: "dark"`;
+   `steps: [{click: "#edit"}]` or `[{press: "<action id>"}]` shows a dialog or a second state.
+   Fix the publish `warnings` too.
    Fix every error and console line it reports, publish again, look again. It is read-only:
    writes, sends and paid calls are refused there and work in Studio.
-6. `summer_app_events {appId, after}` waits for what the app sends you
+6. `apps.events({ appId, after })` waits for what the app sends you
    (`summer.agent.send`), errors (uncaught and `console.error`) and feedback. Act on them;
    pass the cursor on.
-7. Change the app by publishing again; `summer_app_get` returns the current files.
+7. Change the app by publishing again; `apps.get({ appId })` returns the current files.
 
 ## Data is the API
 
-Read and write an app's shared collections with `summer_app_data`. It works with
+Read an app's shared collections with `apps.read_data` and write them with `apps.write_data`. Both work with
 no app open, and everyone in the app sees your edits live. "Nerf the bow in our
 balance sheet" is a data write, not a click.
 
-Declare each collection's record shape in the manifest `collections`; `summer_app_tools`
-and `summer_app_data` reads return it, so any agent knows what a record looks like.
+Declare each collection's record shape in the manifest `collections`; `apps.tools`
+and `apps.read_data` return it, so any agent knows what a record looks like.
 
 ```json
 { "appId": "<id>", "ops": [
@@ -109,8 +116,9 @@ and `summer_app_data` reads return it, so any agent knows what a record looks li
 ] }
 ```
 
-Up to 100 ops per call. Without `ops`, `summer_app_data` reads (`collection`, `after`, `limit`);
-removed records are not returned. Your writes are recorded as `actor { kind: "agent" }` (and
+That is the input of `apps.write_data`: up to 100 ops per call. Send an `idempotencyKey` and reuse it
+only to retry the same write, so it applies once. `apps.read_data({ appId, collection, limit, cursor })`
+reads records (`items`, then `nextCursor` for the next page); removed records are not returned. Your writes are recorded as `actor { kind: "agent" }` (and
 as `createdBy` on records you create), so the app can show which rows an agent made. Add
 `"as": "seed"` for starter data that belongs to the team (`kind: "seed"`, no author). `patch` merges keys
 (`null` removes one); `ifRevision` guards against overwriting a newer change.
@@ -119,8 +127,11 @@ as `createdBy` on records you create), so the app can show which rows an agent m
 
 Logic that lives in the app (a balance formula, an export) can be exposed in the
 manifest `agentTools` and implemented with `summer.agent.tool(name, handler)`.
-`summer_app_tools` lists them; `summer_app_call` runs one inside the person's open
-app and answers `app_not_open` otherwise. Prefer data for plain reads and edits.
+`apps.tools` lists them; `apps.call({ appId, tool, input })` runs one inside the person's open
+app and answers a `conflict` error when the app is not open (its `next` is the app's link for the
+person). Prefer data for plain reads and edits. `apps.page` reads the fields and buttons an open app
+declared, and `apps.use_page({ appId, fill, press })` fills and presses them; the ones the app marks
+critical are the person's to press.
 
 ## Rules
 
@@ -141,12 +152,46 @@ app and answers `app_not_open` otherwise. Prefer data for plain reads and edits.
 - Call `summer.page.declare` so agents can read and use the UI; mark delete,
   publish, pay and send actions `critical`.
 - When the SDK cannot do what the app needs, say so and call
-  `summer_app_report_gap`.
-- `summer_app_dock` docks an app in the editor; on engines without app docks it
-  returns `engine_lacks_op`: open the app in the Studio tab instead.
+  `apps.report_gap`.
+- `apps.dock` docks an app in the editor (it runs in the Summer MCP on this computer); on engines
+  without app docks it returns `engine_lacks_op`: open the app in the Studio tab instead.
+- Keep, archive, restore, rename and pin with `apps.update` (`status`, `name`, `folder`, `pinned`);
+  copy one with `apps.duplicate`; add a starter app with `apps.add_starter`; send the makers a note
+  with `apps.feedback`. `apps.delete` asks the person, and `apps.rollback` (an older version goes
+  live) and `apps.update_starter` ask the app's owner: each answers `needs_approval` with a link to
+  give them, and nothing changes until they approve (`jobs.wait` on the job).
 
 ## Done means
 
-The app is published; `summer_app_screenshot` shows it with real data in light, dark and at
+The app is published; `apps.screenshot` shows it with real data in light, dark and at
 390 px with no errors; its states (loading, empty, error) work; and the person knows what it
 does and where its data goes.
+
+<!-- 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 |
+|---|---|
+| `apps.call`, `summer_apps_call` | `summer apps call` |
+| `apps.create`, `summer_apps_create` | `summer apps create` |
+| `apps.dock` | `summer apps dock` |
+| `apps.events`, `summer_apps_events` | `summer apps events` |
+| `apps.get`, `summer_apps_get` | `summer apps get` |
+| `apps.guide`, `summer_apps_guide` | `summer apps guide` |
+| `summer_apps_list` | `summer apps list` |
+| `apps.page`, `summer_apps_page` | `summer apps page` |
+| `apps.publish`, `summer_apps_publish` | `summer apps publish` |
+| `apps.read_data`, `summer_apps_read_data` | `summer apps read-data` |
+| `apps.report_gap`, `summer_apps_report_gap` | `summer apps report-gap` |
+| `apps.screenshot`, `summer_apps_screenshot` | `summer apps screenshot` |
+| `apps.tools`, `summer_apps_tools` | `summer apps tools` |
+| `apps.update`, `summer_apps_update` | `summer apps update` |
+| `apps.use_page`, `summer_apps_use_page` | `summer apps use-page` |
+| `apps.write_data`, `summer_apps_write_data` | `summer apps write-data` |
+| `assets.generate_sfx_choices` | `summer assets generate-sfx-choices` |
+| `docs.feedback` | `summer docs feedback` |
+| `jobs.wait` | `summer jobs wait` |
+| `summer_search` | `summer ops search "<what you want>"` |
+<!-- /shell-commands -->

package/library/skills/summer-apps/manifest.md

@@ -1,6 +1,6 @@
 # The Summer App manifest
 
-Sent as `manifest` on every `summer_app_publish` and written into the app as
+Sent as `manifest` on every `apps.publish` and written into the app as
 `summer.app.json`. Unknown keys and unknown permissions are refused with a message that
 names them. Every field:
 

package/library/skills/summer-apps/minimal-app.md

@@ -6,9 +6,9 @@ the host, shared data (list, put, live changes), who changed a row (person or ag
 an edit flow (dialog + form with setValues), status badges, an error with Try again, the
 page declaration, an agent event, an agent tool and frame-move state.
 
-Publish it with `summer_app_publish {appId, dir, manifest, note}` where `dir` holds
-`index.html` and `app.js`, or pass the same two as `files`. The page, sections, inputs,
-table, notice and empty text are kit components (`summer_app_guide` section `kit`, or
+Publish it with `apps.publish({ appId, files, manifest, note })` where `files` holds
+`index.html` and `app.js` as `{ path, content }`. The page, sections, inputs,
+table, notice and empty text are kit components (`apps.guide({ section: "kit" })`, or
 `/summer-ui/v1/catalog.json` on the app host); no app CSS is needed.
 
 ## The manifest (send it as `manifest`)
@@ -145,7 +145,7 @@ form.addEventListener("submit", async (event) => {
 // Live: every change by a teammate or an agent arrives as { revision, actor, ops } (or { reset: true }).
 notes.subscribe(() => load());
 
-// Agent tool: summer_app_call { tool: "add_note", input: { text, level } } runs this while the app is open.
+// Agent tool: apps.call({ appId, tool: "add_note", input: { text, level } }) runs this while the app is open.
 // Its writes are recorded as the calling agent's (actor.kind "agent", via "agent-tool").
 summer.agent.tool("add_note", async ({ text, level }, { agent }) => {
   const id = crypto.randomUUID();
@@ -153,7 +153,7 @@ summer.agent.tool("add_note", async ({ text, level }, { agent }) => {
   return { id };
 });
 
-// What agents can read and use with summer_app_page.
+// What agents can read with apps.page and use with apps.use_page.
 summer.page.declare({ actions: [{ id: "add", label: "Add note", run: () => openEditor(null) }] });
 
 // Frame moves: Studio moves an idle app to a fresh frame every few minutes. Shared data survives on
@@ -178,6 +178,6 @@ source's `onended`.
 { "appId": "<id>", "ops": [{ "op": "put", "collection": "notes", "recordId": "n-1", "data": { "text": "Boss fight too long", "level": "boss", "status": "open", "author": "agent" } }] }
 ```
 
-That is a `summer_app_data` write: it works with the app closed, and the open app shows it
-through `notes.subscribe`. `summer_app_tools` and `summer_app_data` reads return the
+That is an `apps.write_data` input: it works with the app closed, and the open app shows it
+through `notes.subscribe`. `apps.tools` and `apps.read_data` return the
 `collections` above, so an agent knows the record shape.

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

@@ -1,7 +1,7 @@
 id: skill/summer-apps
 kind: skill
 version: 0.1.0
-summary: "Build a Summer App, a team tool inside Summer Studio (balance table, quest editor, tracker, pick grid): build loop, Layout vs code, data as API, agent tools."
+summary: "Build a Summer App, a team tool inside Summer Studio (balance table, quest editor, tracker), data and tools."
 use_when:
   - the person asks for a tool for their team ("build us a loot balance tool", "a board to track creatures")
   - the person needs a UI to decide, rate or edit something they will come back to

package/library/skills/summer-apps/sdk-reference.md

@@ -67,21 +67,21 @@ exist); otherwise the call rejects with `conflict`. Record ids: letters, digits,
 ### Who changed it
 
 `actor.userId` is the account the write ran as, the same id as `ready.viewer.userId` and
-`app.viewer().userId`. `kind: "agent"` marks writes an agent made with `summer_app_data`, and
-writes your own code made while running an agent tool for `summer_app_call` (those also have
+`app.viewer().userId`. `kind: "agent"` marks writes an agent made with `apps.write_data`, and
+writes your own code made while running an agent tool for `apps.call` (those also have
 `via: "agent-tool"`). Show agent-made rows (a small "by agent" label) so people know.
 
 `actor` is the last writer. `createdBy` (same shape) is who created the record and does not
 change on later edits, so take the "by agent" label from `createdBy.kind === "agent"`: it
 survives a person's edit. `kind: "seed"` is starter data an agent wrote for the team
-(`summer_app_data` with `as: "seed"`): show no author for it.
+(`apps.write_data` with `as: "seed"`): show no author for it.
 
 ## Agents
 
 | Call | Returns |
 |---|---|
-| `summer.agent.send(name, payload)` | `{ seq }`. `name` must be in `manifest.agentEvents`. Agents read it with `summer_app_events`. |
-| `summer.agent.tool(name, async (input, { agent }) => result)` | stop function. `name` must be in `manifest.agentTools`; `agent` is the calling agent's name. Data writes the handler makes are recorded as that agent's (`via: "agent-tool"`). `summer_app_call` runs it; return JSON (under 100 KB); a throw becomes `tool_failed`. |
+| `summer.agent.send(name, payload)` | `{ seq }`. `name` must be in `manifest.agentEvents`. Agents read it with `apps.events`. |
+| `summer.agent.tool(name, async (input, { agent }) => result)` | stop function. `name` must be in `manifest.agentTools`; `agent` is the calling agent's name. Data writes the handler makes are recorded as that agent's (`via: "agent-tool"`). `apps.call` runs it; return JSON (under 100 KB); a throw becomes `tool_failed` (the agent sees an `unavailable` error). |
 | `summer.agent.onMessage((message) => …)` | stop function |
 | `summer.page.declare({ fields, actions })` | promise. `fields: [{ id, label, kind: "text"\|"long-text"\|"number"\|"toggle"\|"choice", value, options?: [{ value, label }] (for choice), max?, hint?, set(value) }]`, `actions: [{ id, label, description?, critical?, run() }]`. Call it again when values change. Critical actions are pressed only by the person. |
 

package/library/skills/summer-apps-design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: summer-apps-design
-description: "How a Summer App should look - page layout, Summer UI kit components, tables, charts, media, boards, states and a pre-ship checklist."
+description: "How a Summer App should look: layout, Summer UI kit components, tables, charts, states, pre-ship check."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: tools

package/library/skills/summer-apps-design/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/summer-apps-design
 kind: skill
 version: 0.1.0
-summary: How a Summer App should look - page layout, Summer UI kit components, tables, charts, media, boards, states and a pre-ship checklist.
+summary: "How a Summer App should look: layout, Summer UI kit components, tables, charts, states, pre-ship check."
 use_when:
   - building or changing the UI of a Summer App (agent-built team tool inside Summer Studio)
   - an app looks generic, cluttered or off-brand

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

@@ -0,0 +1,86 @@
+---
+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."
+license: MIT
+compatibility: [Cursor, Claude Code, Codex, Windsurf, Gemini, OpenCode, Factory, Copilot]
+category: _meta
+user-invocable: false
+---
+
+# Summer assets without the engine
+
+Use this skill when the session has the Summer **assets profile**: the generation and asset library tools are there, the Summer Engine tools are not (no `summer_get_project_context`, `summer_add_node`, `summer_play` or `summer_screenshot`). The person wants files for their own engine or web app. You deliver files, not scenes.
+
+A call written `area.action({...})` is one operation: use the tool `summer_area_action` when your client lists it, else `summer_call({ op: "area.action", input: {...} })`. `summer_search` finds any operation and its exact input.
+
+## What this session has
+
+| Job | Operations |
+|---|---|
+| Find how to do it | `summer_docs_search`, then `summer_docs_read` the skill |
+| Find an existing asset | `assets.search({ query, scope })` (`scope`: `library` (default), `mine` for the person's own, `all`), then `assets.get({ assetId })` |
+| Make a new asset | `assets.generate_image`, `assets.generate_3d`, `assets.generate_audio`, `assets.generate_sfx_choices` with `assets.choices`, `assets.generate_video`, `assets.generate_motion`, `assets.slice_sheet` |
+| Wait for a job | `jobs.wait({ jobId, timeoutSeconds: 50 })` with the `job.id` a generation returned |
+| Get the file | `out` on the generate call, `jobs.wait` or `assets.get`: the file is saved there and the answer gives `localPath` |
+| More generators | `makers.<tool>` (for example `makers.npc_voice`, `makers.trailer_forge`); `summer_search` lists them |
+
+## The loop
+
+1. **Ask what the asset is for**, once, in one message: the engine or app, the file format, the size or scale, the style, how many.
+2. **Reuse first.** `assets.search({ scope: "mine" })`, then `assets.search({ query, scope: "all" })`. Generate only when nothing fits.
+3. **Read the asset's skill**: sound effect `sound-effect`, music `music-track`, ambience `ambient-bed`, voice `voice-line`, image or style `concept-art`, UI `ui-graphics`, texture `tileable-texture`, sprites `sprite-sheet` or `pixel-art`, sky `skybox-panorama`, 3D prop `prop-model`, character `character-model`, creature or plant `organic-model`, vehicle `vehicle-model`, modular kit `environment-kit`, animation `generate-motion`, video `trailer-shot`. Follow it up to the point where the asset exists. Its **Without Summer Engine** section says where to stop: skip every step that imports the asset into a project or adds nodes to a scene.
+4. **Confirm before you spend.** Generation uses the person's Summer credits. `dryRun: true` on the generate call returns the estimate (`credits`, `balance`, `enough`) and makes nothing. Say what you will make and how many versions, and wait for a yes.
+5. **Generate, then wait.** 3D, video and animation answer at once with `{ status: "running", job }`: call `jobs.wait` until `finished` is true. Never continue on a running job.
+6. **Use the returned id.** `assets.get` with the asset id the finished job's `result` holds. Do not search by name right after a generation.
+7. **Check it.** Look at the preview image or thumbnail you received. For audio, the person listens. Describe only what you actually received.
+8. **Hand it over.** Pass `out` with the folder the person named (or a file path): on the generate call, on `jobs.wait` for 3D, video and animation, or on `assets.get` for an asset you already have. The file is saved there and the answer gives `localPath`. Without `out`, a file made in a game project lands in its asset folder (Godot `assets/`, Unity `Assets/Summer`, Unreal `Content/Summer`, three.js `public/assets`). Tell the person the path and format. Connected only to Summer's hosted server, there is no `out`: download `downloadUrl` from `assets.get` with your own shell.
+
+## Formats
+
+Each asset is a normal file in the person's Summer library: GLB for 3D models, PNG, JPG or WebP for images, MP3 or WAV for audio, MP4 for video. GLB is Y up. Generated models are not at real-world size: give the person the target size (a door about 2 m, a person about 1.7 m). Tell them if their engine needs a conversion step, and let them choose the tool for it.
+
+## Done means
+
+- The job finished without an error.
+- You saw the preview, or the person heard the sound.
+- The file is where the person asked, and you told them the path and format.
+
+## Pitfalls
+
+| Pitfall | Do this instead |
+|---|---|
+| Following an asset skill into its scene steps (`summer_import_asset_by_id`, `summer_add_node`, `AudioStreamPlayer`, `MeshInstance3D`) | Stop at the file. Those tools are not in this session. |
+| Generating before you checked the person's own assets | `assets.search({ scope: "mine" })` first |
+| Generating the same asset again to get the file | `assets.get` with `out` on the asset you already have |
+| Telling the person the asset looks right without a preview | Say what you received, or that no preview came back |
+| The person wants a whole game, not assets | Say that this needs Summer Engine and the full setup: `npx -y summer-engine@latest setup <agent> --yes` |
+
+<!-- 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.choices` | `summer assets choices` |
+| `assets.generate_3d` | `summer assets generate-3d` |
+| `assets.generate_audio` | `summer assets generate-audio` |
+| `assets.generate_image` | `summer assets generate-image` |
+| `assets.generate_motion` | `summer assets generate-motion` |
+| `assets.generate_sfx_choices` | `summer assets generate-sfx-choices` |
+| `assets.generate_video` | `summer assets generate-video` |
+| `assets.get` | `summer assets get` |
+| `assets.search` | `summer assets search` |
+| `assets.slice_sheet` | `summer assets slice-sheet` |
+| `summer_docs_read` | `summer docs read` |
+| `summer_docs_search` | `summer docs search` |
+| `summer_add_node` | `summer engine add-node` |
+| `summer_get_project_context` | `summer engine get-project-context` |
+| `summer_import_asset_by_id` | `summer engine import-asset-by-id` |
+| `summer_play` | `summer engine play` |
+| `summer_screenshot` | `summer engine screenshot` |
+| `jobs.wait` | `summer jobs wait` |
+| `makers.npc_voice` | `summer makers npc-voice` |
+| `makers.trailer_forge` | `summer makers trailer-forge` |
+| `summer_search` | `summer ops search "<what you want>"` |
+<!-- /shell-commands -->

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

@@ -0,0 +1,34 @@
+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."
+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
+  - an asset skill ends with Summer Engine steps that this session cannot run
+facets:
+  lifecycle:
+    - build
+  domains:
+    - assets
+    - agent-workflow
+  modalities:
+    - 3d-models
+    - images
+    - audio
+    - video
+related:
+  tools:
+    - tool/search-assets
+    - tool/list-my-assets
+    - tool/check-job
+    - tool/get-asset
+    - tool/get-asset-download-url
+  skills:
+    - skill/asset-strategy
+    - skill/sound-effect
+    - skill/prop-model
+    - skill/concept-art
+source: official
+license: MIT
+status: stable

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

@@ -0,0 +1,133 @@
+---
+name: summer-cli
+description: "Summer as shell commands, no MCP: sign in, find and run operations, follow jobs, save files, drive the engine."
+license: MIT
+compatibility: [Cursor, Claude Code, Codex, Windsurf, Gemini, OpenCode, Factory, Copilot]
+category: _meta
+allowed-tools: Bash Read
+---
+
+# Summer from the shell
+
+Use this skill when the session has no `summer_*` MCP tools (Summer was set up with `summer setup <agent> --cli`), or when a script or CI job runs Summer. Every Summer capability is an operation named `area.action`, and every operation is one command: `summer <area> <action>`. The commands run the same code as the MCP tools and give the same answers.
+
+First run `summer --version`. If the shell does not find `summer`, or the version is below 4.0 (an old global install, which has no `summer <area> <action>` commands), put `npx -y summer-engine@latest` in place of `summer`, with the same arguments. In Windows PowerShell, write `npx.cmd`.
+
+## The five commands in a game project
+
+<!-- project-commands: the AGENTS.md that summer create and summer setup write copies this list -->
+1. `summer run .` opens the project in Summer Engine. An agent's run stays in the background.
+2. `summer engine get-project-context` (MCP: `summer_get_project_context`) reads the project, its main scene and the engine version. Run it first.
+3. `summer engine play`, then `summer engine get-diagnostics` (MCP: `summer_play`, `summer_get_diagnostics`), runs the game and reads its errors. `summer engine stop` (`summer_stop`) ends it.
+4. `summer engine screenshot` (MCP: `summer_screenshot`) saves an image of the editor or the running game. Open its `localPath` to look.
+5. `summer ops search "<what you want>"` (MCP: `summer_search`) finds any other operation. Run it as `summer <area> <action>` (MCP: `summer_call`), with `--dry-run` first for a change.
+<!-- /project-commands -->
+
+## 1. Sign in once
+
+```bash
+summer login     # opens the browser: the Summer account, then the store and cloud operations
+summer whoami    # who is signed in, and their credits
+```
+
+Cloud operations (generation, the asset library, the store, publishing, analytics) need the sign-in. Engine commands do not. Run `summer login` in the foreground, once. Tell the person that their browser opens, and wait for them.
+
+## 2. Find the operation
+
+```bash
+summer ops search "make a sound effect"       # the best matches: name, effect, title
+summer ops describe assets.generate_audio     # the exact input: fields, types, which are required
+```
+
+Describe the job in plain words. `--area assets` keeps one area. Without a sign-in, search and describe still find every operation: a cloud one shows `(needs sign-in)` and runs after `summer login`.
+
+For a guide instead of an operation, search the library: `summer docs search --query "<the task>"`, then `summer docs read --id <id>`. Both work offline. Then follow the skill it names.
+
+Each Summer skill ends with a **From a shell** table: the command for each MCP tool and operation the skill names. A skill that says `summer_play` or `assets.generate_image` means `summer engine play` or `summer assets generate-image`.
+
+## 3. Run it
+
+```bash
+summer assets generate-image --dry-run --prompt "a cozy pixel-art tavern" --aspect-ratio 16:9
+summer engine set-prop --scene-path res://main.tscn --path Player --key position --value "Vector3(0, 1, 0)"
+summer store status --game-id <id> --json
+```
+
+- Actions and fields are kebab-case: `aspectRatio` is `--aspect-ratio`, `look_at` is `--look-at`.
+- `--<field>` alone sets a boolean field to true; `--no-<field>` sets it to false. Repeat a flag to give a list.
+- Objects, and anything hard to quote, go in `--input '<json>'`. A flag wins over the same key in `--input`.
+- `--dry-run` checks the input and changes nothing. For a spend it shows the estimate in credits. Put it right after the action: after `summer setup <agent> --cli --allow-rules --yes` (run that only when the person asks for it), Claude Code and Codex run it without asking (and the reads). Before each generation or other spend: dry-run it, tell the person what you will make, and wait for a yes.
+- `--idempotency-key <key>` makes a retry safe: Summer runs a change once per key.
+- `--json` prints only the answer: `{"ok":true,"status":"done","result":{...}}`. The exit code is 0 for every `ok` answer and 1 for an error.
+
+## 4. Long jobs
+
+3D, video, animation, builds and uploads answer `Started: job <id>` with the command that follows the job.
+
+```bash
+summer assets generate-3d --prompt "a wooden barrel" --wait          # runs, then follows the job to the end
+summer jobs wait --job-id <id> --timeout-seconds 50                  # run it again until finished is true
+```
+
+Do not run the same change again to get its result. Wait on the job.
+
+## 5. Approvals
+
+A publish or another live change can answer `Needs approval` with a link. Give the person that link: nothing changes until they approve. Follow it with `summer jobs wait --job-id <id>` (or `--wait` on the call) until it ends: `done`, `declined`, `expired` or `stale`. Never approve for the person.
+
+## 6. Files
+
+- `--out <folder or file>` on a generate command, on `summer jobs wait` or on `summer assets get` saves the file there. In a Godot project, `res://` paths work. The answer adds `localPath`.
+- Without `--out`, a generation run inside a game project saves into its asset folder: Godot `assets/`, Unity `Assets/Summer`, Unreal `Content/Summer`, three.js `public/assets`. Outside a project, give `--out`.
+- `summer assets get --asset-id <id>` saves only with `--out`.
+- A save never overwrites a file. Tell the person the `localPath`.
+
+## 7. The engine
+
+Engine commands (`summer engine …`) drive the Summer Engine app on this machine. The app must run with the project open.
+
+```bash
+summer status                                              # is the engine up, and the sign-in
+summer run ./my-game                                       # opens the project; for an agent, in the background
+summer engine get-project-context                          # first call: project, main scene, engine version
+summer engine get-scene-tree --scene-path res://main.tscn --depth 2
+summer engine screenshot                                   # the answer's localPath is an image: open it to look
+```
+
+- Values are engine value strings, not JSON: `"Vector3(0, 10, 0)"`, `"Color(1, 0.5, 0, 1)"`. A resource is its class name: `"BoxMesh"`.
+- Name the scene in every change: `--scene-path res://<scene>.tscn`.
+- 3 or more scene edits are one script, not a chain of commands. Write a `func run(ctx):` that ends with `ctx.save_scene()` to a file, then run `summer engine run-script --scene-path res://main.tscn --source "$(cat build.gd)"`. The `scene-scripting` skill has the script API.
+- With more than one editor open, set `SUMMER_ENGINE_PROJECT` to the project folder so the command picks the right one.
+- `summer tool <slug> --args '<json>'` runs an engine tool by its 3.x name too. `summer tool --list` lists them.
+
+## Without Summer Engine
+
+Everything except section 7 works without the app: the sign-in, the library, generation, assets and files, the store and analytics. Skip the `summer engine …` commands; there they answer `engine_not_running`. For assets for another engine or a web app, follow the `summer-assets` skill and stop at the file.
+
+## 8. Errors
+
+An error prints `Error (<code>): <message>` and one `Next:` step, and exits 1. Do the next step. Retry only when the table says so.
+
+| Code | Do this |
+|---|---|
+| `not_signed_in` | Run the command in `Next` (`summer login`), then the same command again. |
+| `engine_not_running` | Open the project in Summer Engine, or `summer run <project-path>`. Then run it again. |
+| `engine_lacks_op` | This engine build is too old for the command. Use the fallback the message names, or ask the person to update Summer Engine. |
+| `invalid_input` | `summer ops describe <op>`, fix the flags, run it again. |
+| `no_credits` | Give the person the link in `Next`. Do not run it again until they say they added credits. |
+| `forbidden` | Summer refused this account. The person checks it in Summer Studio. |
+| `not_found` | Check the id (the area's `list` command), or find the right operation with `summer ops search`. |
+| `rate_limited`, `unavailable` | Nothing ran. Wait a minute and run it again. If it repeats, tell the person the message. |
+| `outcome_unknown` | The change may have run. Run it again only with the same `--idempotency-key`, or check first. |
+| `in_progress` | The same change is still running. Wait, then follow its job or run it again with the same `--idempotency-key`. |
+| `idempotency_conflict` | That key was used for a different input. A new change needs a new key. |
+| `conflict` | The state changed, or a job or approval ended without running (declined, expired, stale or cancelled). Check the current state; start again only if the person wants it. |
+| `over_limit` | A plan limit or cap was reached. Give the person the message and the link in `Next`. Do not retry. |
+| `unsupported` | Summer cannot do this yet, or not here. Tell the person the message. Do not retry. |
+| `internal` | Summer failed on its side. Run it once more; if it fails again, tell the person the message. |
+
+## Done means
+
+- You ran each command and read its answer. Do not report an answer you did not get.
+- Every spend had a dry run and a yes from the person first.
+- Every file you made is saved, and you told the person its `localPath`.

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

@@ -0,0 +1,31 @@
+id: skill/summer-cli
+kind: skill
+version: 1.0.1
+summary: "Summer as shell commands, no MCP: sign in, find and run operations, follow jobs, save files, drive the engine."
+use_when:
+  - the session has no summer_* MCP tools, or Summer was set up with summer setup <agent> --cli
+  - running a Summer operation, a generation or an engine change from a shell, a script or CI
+  - a skill names an MCP tool or an operation and you need the summer command that runs it
+do_not_use_when:
+  - the session lists Summer's MCP tools; call them directly (the using-summer skill)
+facets:
+  lifecycle:
+    - build
+  domains:
+    - agent-workflow
+    - assets
+    - tools
+  modalities:
+    - docs
+related:
+  tools:
+    - tool/search-library
+    - tool/read-library
+  skills:
+    - skill/using-summer
+    - skill/summer-assets
+    - skill/scene-scripting
+source: official
+license: MIT
+status: preview
+recommended: true

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

@@ -224,3 +224,17 @@ and revoke access in the Summer app, and watch `access_changed`.
 - `summer-world-chat`: chat inside a match
 - `multiplayer-publish`: `summer.build.json` and publishing a Build
 - `multiplayer-testing`: what Local Play can and can't test
+
+<!-- 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_stop` | `summer engine stop` |
+<!-- /shell-commands -->

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

@@ -229,3 +229,19 @@ on them.
 - `summer-match-results` — concluding matches, which moves ratings
 - `summer-matchmaking` — declaring rated queues and teams
 - `summer-player-data` — saving per-player progress that isn't a ranking
+
+<!-- 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_read_file` | `summer engine read-file` |
+| `summer_replace_text` | `summer engine replace-text` |
+| `summer_stop` | `summer engine stop` |
+| `summer_write_file` | `summer engine write-file` |
+<!-- /shell-commands -->