summer-engine 4.3.0 → 4.5.0

package/dist/mcp/tools/local-project-tools.js

@@ -0,0 +1,33 @@
+import { z } from "zod";
+import { createLocalProject, LocalProjectError, localProjectFailure, openLocalProject, } from "../../core/capabilities/projects-local.js";
+import { EngineNotRunningError } from "../../core/error-codes.js";
+import { bindMcpProject, currentMcpEngineSelection, logEngineSelfStart } from "../server.js";
+import { textJson } from "./text-json.js";
+import { engineNotRunningResult } from "./with-engine.js";
+async function localProjectResult(operation) {
+    try {
+        return textJson(await operation());
+    }
+    catch (error) {
+        if (error instanceof LocalProjectError)
+            return textJson(localProjectFailure(error), true);
+        if (error instanceof EngineNotRunningError)
+            return engineNotRunningResult(error);
+        throw error;
+    }
+}
+/**
+ * projects.create_local and projects.open_local: what `summer dev` does, for
+ * agents with no shell (core/capabilities/projects-local.ts).
+ */
+export function registerLocalProjectTools(server) {
+    server.tool("summer_projects_create_local", "Create a Summer project on this computer from a template, with no shell: the built-in 3d-basic (sky, sun, ground and a hero; no download) unless template names another. Writes it into dir, or into <name> next to the session's project, in the session's folder, or in ~/Documents/Summer; never inside another project. A folder that already holds project.godot is left as it is. Returns projectPath. Next: summer_projects_open_local with that path.", {
+        template: z.string().max(80).optional().describe("Template slug (docs.search finds them): 3d-basic (default), empty, 3d-third-person-controller, 2d-platformer, ..."),
+        name: z.string().max(80).optional().describe("The project's name and folder name. Default my-game (or the template's name)."),
+        dir: z.string().max(1000).optional().describe("The project folder: a new or empty folder, not inside another project; ~ is home. Default <name> next to the session's project, in the session's folder, or in ~/Documents/Summer."),
+    }, async (args) => localProjectResult(() => createLocalProject(args, currentMcpEngineSelection()?.cwd)));
+    server.tool("summer_projects_open_local", "Open a project on this computer in Summer Engine, in the background, and wait until it connects (an editor that has it open is used as it is); this session's engine tools then work on it. When Summer Engine is not installed it answers engine_not_running: ask the person, and only with their yes call again with install: true (about 660 MB, free). A first open can take a few minutes: the answer says to call again. It adds summer-preview to the session folder's .claude/launch.json (Claude Code Desktop's Browser pane), and preview.url is where the game shows. Next: summer_get_project_context.", {
+        path: z.string().max(1000).optional().describe("The project folder (holds project.godot), e.g. projectPath from summer_projects_create_local. Default this session's project."),
+        install: z.boolean().default(false).describe("Install Summer Engine first when it is missing. Set true only after the person said yes."),
+    }, async (args) => localProjectResult(() => openLocalProject(args, currentMcpEngineSelection(), { log: logEngineSelfStart }, (root, client) => bindMcpProject(root, client))));
+}

package/dist/mcp/tools/navigation-tools.js

@@ -24,7 +24,8 @@ Result: { ok, action: opened | printed | listed | ambiguous | unsupported | engi
 - ambiguous: several destinations match; call again with one of matches[].id.
 Only summerengine.com (and subdomains) are ever opened — a gateway configured elsewhere is refused (blocked_origin); res:// paths with .. or other escapes are refused; a machine with no browser gets open_failed with the url to hand over.`, openArgsShape, async (args) => {
         const result = await runOpen(args, {
-            engine: () => getClient(),
+            // Lists and prints must not open the editor (no side effects).
+            engine: () => getClient({ launch: false }),
             openUrl: (url) => open(url),
             isLoggedIn: async () => (await getAuthToken()) !== null,
             gatewayUrl: resolveGatewayUrl,

package/dist/mcp/tools/project-tools.js

@@ -5,6 +5,7 @@ import { buildProjectContext, projectContextInputShape, resolveMainScene, } from
 import { getCachedBootDriftNotice } from "../boot-notice.js";
 import { appendMcpLogEvent } from "../../core/mcp-log.js";
 import { withEngine } from "./with-engine.js";
+import { importUrls } from "../../core/capabilities/video-ogv.js";
 import { asRecord, stringFrom } from "../../core/util/json.js";
 // One skew log line per MCP process — the warning itself stays in every
 // summer_get_project_context payload.
@@ -245,20 +246,16 @@ Use this for:
 - 3D models (.glb, .gltf, .obj)
 - Textures (.png, .jpg, .webp)
 - Audio (.ogg, .wav, .mp3)
+- Video (.mp4, .mov, .webm, .ogv): Summer Engine plays only Ogg Theora, so any other video is converted to .ogv first and lands at the path with .ogv; the answer names it.
 
 The path is auto-inferred from the URL filename if not specified. After import, the asset is immediately usable in scenes.`, {
         url: z.string().describe("HTTP(S) URL to download from"),
         path: z.string().optional().describe("Target path in project, e.g. 'res://assets/player.glb'. Auto-inferred from URL if omitted."),
-    }, async ({ url, path }) => withEngine(async (client) => {
-        const op = { op: "ImportFromUrl", url };
-        if (path)
-            op.path = path;
-        return client.executeOps([op]);
-    }));
-    server.tool("summer_import_from_url_batch", "Download multiple files from URLs in one operation. Performs a single filesystem scan after all downloads, which is faster than importing one at a time.", {
+    }, async ({ url, path }) => withEngine(async (client) => importUrls(client, [{ url, ...(path ? { path } : {}) }], { batch: false })));
+    server.tool("summer_import_from_url_batch", "Download multiple files from URLs in one operation. Performs a single filesystem scan after all downloads, which is faster than importing one at a time. A video (.mp4, .mov, .webm) is converted to Ogg Theora first and lands at its path with .ogv.", {
         imports: z.array(z.object({
             url: z.string().describe("URL to download"),
             path: z.string().describe("Target path in project"),
         })).describe("Array of {url, path} objects"),
-    }, async ({ imports }) => withEngine(async (client) => client.executeOps([{ op: "ImportFromUrlBatch", imports }])));
+    }, async ({ imports }) => withEngine(async (client) => importUrls(client, imports, { batch: true })));
 }

package/dist/mcp/tools/seeing-tools.js

@@ -54,7 +54,7 @@ Returns the grid + caption. ${COMMON}`, debugViewsShape, run(debugViews));
     server.tool("summer_zoom", `High-resolution close look at part of a frame: region [x, y, w, h] (fractions of the frame) or mark N from a marks render of the same pose. The camera renders the EXACT sub-frustum of that region at full output resolution, so you see real texture detail, seams, gaps and floating pieces, not upscaled pixels. A region is honoured exactly (no pad by default, never widened to an aspect ratio: the image takes the region's own aspect, with dark bars only for extreme shapes); a mark gets pad 0.15.
 
 Use after a sheet or debug view shows something suspicious. view picks beauty or a debug view. Returns the zoomed image + caption (the real zoom factor, the rendered region, widened_because when it is larger than asked, mark -> node path and a warning when that node is hidden). ${COMMON}`, zoomShape, run(zoom));
-    server.tool("summer_frame_shot", `Smart framing: find good camera poses for a shot type automatically, measured in-engine against the real geometry.
+    server.tool("summer_frame_shot", `Smart framing: find good camera poses for a shot type automatically, measured in-engine against the real geometry. It runs in the open editor; use it to look at the scene as a player would.
 
 shot: establishing (wide), eye_level (from a spawn node at player eye height), low_angle (hero, near the ground looking up: the camera moves closer and widens its FOV instead of sinking into the ground), detail (close-up), corridor (down a lane or corridor found inside the subject by a free-space scan, preferring the view in from its open end, walls on both sides).
 

package/dist/mcp/tools/visual-tools.js

@@ -103,7 +103,7 @@ function teachPreviewFailure(snap) {
 export function registerVisualTools(server) {
     server.tool("summer_screenshot", `Capture a frame from Summer Engine and return it as an image you can look at directly.
 
-Use this to visually verify your work: scene layout, asset placement, scale, framing, missing/untextured assets, or runtime gameplay state. You see the actual pixels — no description layer in between. Lighting and materials are only truthfully shown by the "viewport" and "game" targets — see the note on "scene" below.
+Use this to visually verify your work (it reads the real open editor or game window; that is allowed and expected): scene layout, asset placement, scale, framing, missing/untextured assets, or runtime gameplay state. You see the actual pixels — no description layer in between. Lighting and materials are only truthfully shown by the "viewport" and "game" targets — see the note on "scene" below.
 
 target:
   "viewport" (default) — the editor's CURRENT view (whatever scene/tab is open). No game boot. Use for edit-time checks of how the scene looks right now.

package/dist/mcp/tools/with-engine.js

@@ -162,7 +162,7 @@ export async function withEngine(fn, opts) {
 export function engineNotRunningResult(error) {
     return {
         isError: true,
-        content: [{ type: "text", text: JSON.stringify(codedFailure(error.code, error.message, { hint: ENGINE_FREE_NOTE }), null, 2) }],
+        content: [{ type: "text", text: JSON.stringify(codedFailure(error.code, error.message, { hint: ENGINE_FREE_NOTE }, error.recovery), null, 2) }],
     };
 }
 const PRE_APPLY_FAILURE_REASON = {

package/gemini-extension.json

@@ -1,7 +1,7 @@
 {
   "_generated": "GENERATED from integrations/gemini — do not edit; npm run generate:registry",
   "name": "summer",
-  "version": "4.3.0",
+  "version": "4.5.0",
   "description": "The game engine built for AI. Any agent makes a multiplayer game and publishes it. The Summer Engine MCP server, context primer and game-dev skills.",
   "contextFileName": "GEMINI.md",
   "mcpServers": {
@@ -72,6 +72,7 @@
     "./library/skills/in-game-purchases/",
     "./library/skills/instantiate-asset-pack/",
     "./library/skills/investigating-bugs/",
+    "./library/skills/make-content/",
     "./library/skills/make-game/",
     "./library/skills/multiplayer/",
     "./library/skills/multiplayer-movement/",
@@ -89,6 +90,7 @@
     "./library/skills/procedural-animation/",
     "./library/skills/prop-model/",
     "./library/skills/publish-your-game/",
+    "./library/skills/release-checklist/",
     "./library/skills/release-readiness/",
     "./library/skills/remote-deploy/",
     "./library/skills/retarget/",

package/library/references/mcp-tools-reference/mcp-tools-reference.md

@@ -19,7 +19,16 @@
 
 **Rule of thumb:** project reads/writes go through Summer; live hierarchy/inspector changes use scene tools; process-level work remains with the host.
 
-## Tool surface (119 tools)
+## Tool surface (125 tools)
+
+### Local projects (2)
+
+No shell needed (Claude Desktop, chat apps); the `summer dev` command does both in one step from a shell.
+
+| Tool | Use |
+|---|---|
+| `summer_projects_create_local` | Write a new project from a template to this computer (`3d-basic` by default: sky, sun, ground and a hero). `dir`, or `name` next to the session's project, in the session's folder, or in `~/Documents/Summer`; never inside another project. A folder that already holds `project.godot` is left as it is. Returns `projectPath`. |
+| `summer_projects_open_local` | Open a project in Summer Engine in the background and wait until it connects; the session's engine tools then work on it. Engine missing: answers `engine_not_running`; ask the person, and only with their yes call again with `install: true` (about 660 MB, free). A slow first open answers "call again in 30 seconds". It registers `summer preview` in the session folder's `.claude/launch.json`; `preview.url` is where the game shows. |
 
 ### Project files (4)
 
@@ -253,13 +262,17 @@ Each spends the person's credits. `dryRun: true` returns `preview.estimate` (`cr
 | `summer_call` `{"op":"summer_get_agent_playbook"}` | Daily operating contract (observe-first loop, content routing, invariants, verification ritual) — read at start of session. Also served natively as the `summer_agent_playbook` MCP prompt. |
 | `plans.get` (3.x `summer_get_board`) | Read the person's game plan (look, characters, place, storyboard, picks): every item with its id, picture URL and revision, to compare screenshots against. `projects.get({ projectId })` gives the project's `planId` from the project id in the build brief; works without the engine. |
 
-### Creator platform (4)
+### Creator platform (8)
 
 | Tool | Use |
 |---|---|
 | `summer_export_game` | Export the game in the file the Summer Games store takes, headless (no window), no running editor needed. `format:"bundle"` (default): the `summer.games` `.zip` the Summer apps run; `targets` picks `ios`, `android`, `macos`, `windows` (a game without a server: phones only) through a named `summer.games <targets>` preset in `export_presets.cfg`. `format:"download"` with one target: `web` (HTML5 `.zip` on Summer's WebGPU Forward+ template; refuses Compatibility projects), `macos` (ad hoc signed `.app` zip, `macos-universal`) or `windows` (`.exe` with embedded pack, zipped, `windows-x64`). Returns path, sha256, size, bundle manifest or store platform, warnings. |
 | `summer_export_templates` | `list` or `install` export templates from Summer's CDN (`downloads.summer.games/engine-templates/<summerVersion>/manifest.json`) into the engine's user template folder (`<data>/Godot/export_templates/<FULL_CONFIG>/`), sha256-checked. Only download exports need them; store bundles need none. `summerVersion` is read on macOS, passed elsewhere. |
-| `store.upload_file` (3.x `summer_publish_build`; through `summer_call`) | Upload that `.zip` to the creator's game through Studio's store upload: confirm-gated preview first, then declare, part upload from disk, seal, wait for the Build; `publish:true` also approves it. Needs `summer login --store`; a retry with the same file and version continues the same upload. Without a shell, `store.upload_begin`, `store.upload_sign_parts` and `store.upload_complete` take the bytes in parts. |
+| `store.upload_file` (3.x `summer_publish_build`; through `summer_call`) | Upload that `.zip` to the creator's game through Studio's store upload: confirm-gated preview first, then declare, part upload from disk, seal, wait for the Build and for Summer's automated checks on each platform (`checks`: passed, or failed with `code`, `owner` and `fix`); `publish:true` also makes the Build available to players. Needs `summer login --store`; a retry with the same file and version continues the same upload. Without a shell, `store.upload_begin`, `store.upload_sign_parts` and `store.upload_complete` take the bytes in parts. |
+| `store.go_live` (`summer_go_live`; through `summer_call`) | Take the store game live: release the uploaded bundle Build to the platforms that passed their checks and publish the store page, through the same store routes Studio uses, then watch until players get it. Confirm-gated: the plan first (or `live`, `blocked` with each failure's fix, `needs_changes` with Summer's feedback). It needs no owner approval link while the person's Agent permissions allow Publish (the default; otherwise `needs_permission`). `waiting` names what it waits on (`automated_checks`, `activation`, or `summer`: a hold on Summer's side that needs nothing from the creator). Call again to keep watching; nothing is asked twice. Run the `release-checklist` skill first. |
+| `store.set_details` (`summer_store_set_details`; through `summer_call`) | The store page sections `store.update_listing` does not edit, on the draft: `genres`, `features`, `credits`, `languageSupport`, `systemRequirements`, `contentSurvey` (the age questionnaire) and `aiDisclosure`. A section given replaces it, `null` clears it. Never publishes. |
+| `economy.sync_items` (`summer_sync_items`; through `summer_call`) | Bring the store game's items in line with `summer.items.json` in the project root, matched by slug, so staging and production carry the same items. Confirm-gated: the plan first (create, update with the changed fields, unchanged, blocked), then the changed images are uploaded and the plan goes to the owner, who approves it in Studio; the items are then created or revised, priced in Sparks and submitted for review. One approval takes at most 50 changed items (a larger plan lists `batches`; confirm each with `slugs`); a new item needs at least one image. Never activates or releases an item. Needs `summer login --store`. Staging or production is the gateway setting: switching takes `SUMMER_GATEWAY_URL` and `SUMMER_MCP_RESOURCE_URL`, then `summer login --store --force` (one store sign-in per machine). |
+| `content.make` (`summer_content_make`; through `summer_call`) | Make one finished piece of content for a game on this computer and put it in the team's Review: picks the reference that fits today (a format the game has not posted, what changed in the repo), studies its cuts and caption look, maps each reference shot to a footage window with motion, cuts to its timings, draws its captions, puts a song on the beat, mixes at -14 LUFS, checks hook, motion per shot, safe zones, length and loudness, renders the reference side by side and saves the piece (failed checks: a draft). It never writes words: `needs_words` lists the beats, call again with `workDir` and `lines`; a reference that speaks also needs `voiceFile` in the team's voice (`needs_voice`). Same `workDir` continues where it stopped. Needs ffmpeg and ImageMagick (Whisper for a voice-over). |
 | `summer_capture_gameplay` | Real gameplay frames without a running editor: starts the game (main scene or `scene`) in the engine's offscreen verify instance (`--summer-verify`, real renderer, window parked offscreen, no focus) (`--summer-offscreen`) at `resolution` (default `1920x1080`), waits `waitSeconds`, runs `steps` (`press` a button by text, `key`, `action`, `click`, `drag`, `wait`, `shot`), saves `frames` PNGs (HUD included; with a `shot` step, one per shot) to `<project>/.summer/captures/<time>/`. `args` are the game's own flags, passed after `--` (e.g. `["--autostart"]` to skip the title screen). Imports the project first when `.godot/` is missing. Returns each path with its real width and height; warns when the stretch settings render another size. For store screenshots. |
 
 ### Hosted store, publishing and Grow tools
@@ -267,9 +280,9 @@ Each spends the person's credits. `dryRun: true` returns `preview.estimate` (`cr
 These come from the hosted Summer server (the one ChatGPT and Claude connect to) and are mounted into the local MCP after `summer login`; `summer tool <name>` reaches them too.
 
 - **Store page:** `summer_store_list_games`, `summer_store_create_game`, `summer_store_get_listing` (the page, the checklist and `availableTags`), `summer_store_update_listing` (text, tags, long description, support contact, release date, content rating), `summer_store_set_art`, `summer_store_set_trailer`, `summer_store_set_sound`, `summer_store_preview_link`, `summer_store_jams` and `summer_store_enter_jam`.
-- **Builds and release:** `summer_build_begin_upload` / `_sign_parts` / `_complete_upload` / `_status` (the local `summer_publish_build` does these from disk), `summer_store_version_*` for web and native downloads, `summer_store_submit` (one approval link for the owner), `summer_store_cancel_submission`, `summer_store_review`, `summer_store_releases`, `summer_build_release`.
+- **Builds and release:** `summer_build_begin_upload` / `_sign_parts` / `_complete_upload` / `_status` (the local `summer_publish_build` does these from disk), `summer_store_version_*` for web and native downloads, `summer_store_submit` (one approval link for the owner, for a person whose Agent permissions have Publish off; otherwise the local `summer_go_live` takes the game live), `summer_store_cancel_submission`, `summer_store_review`, `summer_store_releases`, `summer_build_release`. The engine profile leaves out `summer_store_releases` and `summer_store_version_status`: `summer_go_live` reports what players get and each download's state.
 - **Grow:** `summer_grow_overview` and `summer_grow_analytics` (store page views, launches, play sessions, play time, custom events), `summer_grow_event_catalog`, `summer_grow_event_trend`, `summer_grow_event_funnel`, `summer_grow_members`, `summer_grow_ab_tests`, `summer_grow_prices`, `summer_grow_event_limit`, `summer_grow_apply` and `summer_grow_applications`.
-- **Guides:** the `publish-your-game`, `store-listing`, `store-art` and `grow-analytics` skills (`summer_docs_read`).
+- **Guides:** the `publish-your-game`, `release-checklist`, `store-listing`, `store-art` and `grow-analytics` skills (`summer_docs_read`).
 
 ### Library search (2)
 

package/library/skills/README.md

@@ -1,6 +1,6 @@
 # Summer skills
 
-> 128 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.
+> 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.
 
 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.
 
@@ -8,7 +8,7 @@ Status: **stable** unless marked; *preview* = not yet exercised in-engine by the
 
 ## Domains
 
-- [2d](#2d) (10)
+- [2d](#2d) (11)
 - [3d](#3d) (6)
 - [agent-workflow](#agent-workflow) (19)
 - [ai](#ai) (2)
@@ -16,7 +16,7 @@ Status: **stable** unless marked; *preview* = not yet exercised in-engine by the
 - [assets](#assets) (4)
 - [audio](#audio) (6)
 - [character-controller](#character-controller) (2)
-- [creator](#creator) (4)
+- [creator](#creator) (7)
 - [debug](#debug) (1)
 - [deployment](#deployment) (3)
 - [editor](#editor) (1)
@@ -42,6 +42,7 @@ Status: **stable** unless marked; *preview* = not yet exercised in-engine by the
 | [concept-art](./concept-art/SKILL.md) ★ | Explore art direction with 3-4 rough concept variants of a character, environment or prop. | assets |
 | [create-asset-sheet](./create-asset-sheet/SKILL.md) | Generate a pack of 2D assets from one prompt (tile sheet, UI kit, character pack, biome), sliced. | assets |
 | [instantiate-asset-pack](./instantiate-asset-pack/SKILL.md) | Lay out a whole create-asset-sheet pack in the scene: composites, paint order, Sprite2D and NinePatch. | assets |
+| [*painted-25d-world*](./painted-25d-world/SKILL.md) (preview) (library only) | Build a 2D or 2.5D game as a painted world: a 3D blockout under one fixed camera, an AI paint-over projected onto it, sprite characters. | level-design, rendering, assets |
 | [pixel-art](./pixel-art/SKILL.md) ★ | Generate pixel-art sprites, items, tiles and portraits at a set resolution with a limited palette. | assets |
 | [skybox-panorama](./skybox-panorama/SKILL.md) | Generate a 360-degree sky panorama and wire it as a PanoramaSkyMaterial Sky resource on WorldEnvironment. | assets |
 | [sprite-sheet](./sprite-sheet/SKILL.md) | Generate animated 2D character sprite sheets (walk, attack, idle, death) for AnimatedSprite2D. | assets |
@@ -135,9 +136,12 @@ Status: **stable** unless marked; *preview* = not yet exercised in-engine by the
 | skill | when to use | also |
 |---|---|---|
 | [grow-analytics](./grow-analytics/SKILL.md) | Read a creator's Summer Grow numbers (page views, launches, sessions, play time), compare windows. | deployment |
-| [publish-your-game](./publish-your-game/SKILL.md) | Publish a game on Summer Games through MCP: store page, art, build upload, submit, owner approval link. | deployment |
-| [store-art](./store-art/SKILL.md) | Make Summer Games store art per slot: key art, covers, icons, screenshots, trailer, size and text rules. | assets |
-| [store-listing](./store-listing/SKILL.md) | Write a Summer Games store page: title, tagline, descriptions, tags, per platform, and what never to write. | product-language |
+| [*launch-ready*](./launch-ready/SKILL.md) (preview) (library only) | Get a game ready to launch on Summer Games and take it live: upload, real screenshots, store art and listing, gathered and filled in. | deployment, assets |
+| [make-content](./make-content/SKILL.md) | Make a finished, postable video of your game, cut per platform and saved for review. | video |
+| [publish-your-game](./publish-your-game/SKILL.md) | Publish a game on Summer Games over MCP: store page, art, build upload, go live. | deployment |
+| [*release-checklist*](./release-checklist/SKILL.md) (preview) | Pre-launch check for Summer Games: export, upload checks, store art, listing fields. | deployment |
+| [store-art](./store-art/SKILL.md) | Make Summer Games store art per slot: key art, icons, screenshots, trailer, sizes. | assets |
+| [store-listing](./store-listing/SKILL.md) | Write a Summer Games store page: title, tagline, descriptions, tags, what never to write. | product-language |
 
 ## debug
 
@@ -150,7 +154,7 @@ Status: **stable** unless marked; *preview* = not yet exercised in-engine by the
 | skill | when to use | also |
 |---|---|---|
 | [export-and-ship](./export-and-ship/SKILL.md) ★ | Prepare a game export: check templates and targets, validate release assets, build after approval. | project |
-| [*release-readiness*](./release-readiness/SKILL.md) (preview) | Before releasing a Summer game version, prove players can play it: server, online join, progress, files. | multiplayer, playtest |
+| [*release-readiness*](./release-readiness/SKILL.md) (preview) | Prove players can play a Summer release: server, online join, progress, files. | multiplayer, playtest |
 | [remote-deploy](./remote-deploy/SKILL.md) ★ | Run or test the game on a real phone, tablet or computer with Remote Deploy and on-device debugging. | project |
 
 ## editor
@@ -195,7 +199,7 @@ Status: **stable** unless marked; *preview* = not yet exercised in-engine by the
 | [*summer-matchmaking*](./summer-matchmaking/SKILL.md) (preview) | Get players into matches with Summer matchmaking: queues, teams, accept prompts, join progress and failures. | ux |
 | [*summer-parties*](./summer-parties/SKILL.md) (preview) | Let a Summer party play together: the leader presses Play, members follow into the same match. Hosted only. | ui |
 | [summer-player-data](./summer-player-data/SKILL.md) | Save a player's progress so it follows them to every match: authority load and commit, autosave, safe retries. | scripting |
-| [*summer-store*](./summer-store/SKILL.md) (preview) | Sell Summer items for Sparks in a multiplayer game: shop, checkout, owned items, authority entitlement checks. | gameplay |
+| [*summer-store*](./summer-store/SKILL.md) (preview) | Sell Summer items for Sparks: shop, checkout, item slugs, bundles and sales, owned items, summer.items.json sync, authority checks. | gameplay |
 | [*summer-world-chat*](./summer-world-chat/SKILL.md) (preview) | Add match chat to a Summer game: one World channel shared by everyone in the match. Hosted only. | ui |
 | [*summer-world-saves*](./summer-world-saves/SKILL.md) (preview) | Keep a persistent Summer World between restarts: checkpoint saves, restore before join, the final save. | scripting |
 

package/library/skills/animated-loop/SKILL.md

@@ -107,23 +107,14 @@ If three regenerations don't seam-close, accept a small crossfade in the engine:
 
 ### 6. Import and wire as a looping VideoStreamPlayer
 
-**Transcode to Ogg Theora first.** The generated clip is an `.mp4`, and Summer Engine cannot load `.mp4`. `.ogv` is the only video container in the build — there is no bundled WebM or MP4 plugin, and nothing transcodes on your behalf. Measured against the shipped binary (4.6.1):
+**Import the `.mp4` as it is; the import converts it.** Summer Engine plays video only as Ogg Theora (`.ogv`) — there is no MP4 or WebM loader in the build — so every Summer import tool converts a video on the way in: `summer_import_from_url`, its batch, `summer_import_asset_by_id` and `summer_import_asset`. A clip Summer generated or stores converts on Summer's media host; any other video converts with ffmpeg on this computer when it has Theora, else on summerengine.com. The `.ogv` lands at the path you asked for with the extension swapped, and the answer names it in `videoConversions` and `note`:
 
 ```
-$ Summer --headless --path <proj> -s res://probe.gd
-VideoStream exts: ["ogv", "tres", "res"]
-ERROR: No loader found for resource: res://clip.mp4 (expected type: unknown)
+summer_import_asset_by_id(assetId="<the clip's asset id>", path="res://assets/video/loops/title_screen_bg.mp4")
+→ importedTo: res://assets/video/loops/title_screen_bg.ogv
 ```
 
-`summer_import_from_url` downloads the bytes, runs the engine's import pipeline, and *fails the import* if the file never becomes a loadable resource — so importing the `.mp4` does not quietly half-work, it is rejected and rolled back. Convert first:
-
-```
-ffmpeg -i title_screen_bg.mp4 -c:v libtheora -q:v 8 -an title_screen_bg.ogv
-```
-
-```
-summer_import_from_url(url="<hosted .ogv url>", path="res://assets/video/loops/title_screen_bg.ogv")
-```
+Load the `.ogv` path from the answer, never the `.mp4`.
 
 Then wire it in one script. `scenePath` is the exact scene to change:
 
@@ -188,11 +179,12 @@ Pattern: `<subject> + <ambient loopable motion> + <constant lighting> + "looping
 - **Forgetting `loop=true` on the `VideoStreamPlayer`.** The clip will play once and freeze on the last frame.
 - **Forgetting to mute baked audio.** If audio is on, the loop point becomes audible even if it's invisible.
 - **Expecting `aspectRatio` to reframe an image-to-video call.** It is applied on the text-to-video path only. A portrait splash needs a portrait *reference image* — the argument does nothing here.
-- **Importing the `.mp4` as-is.** `.ogv` is the only video container the engine can load; there is no bundled WebM or MP4 plugin. An un-transcoded import fails and is rolled back.
+- **Loading the `.mp4` path after an import.** The import converted the clip to `.ogv` and saved it under that name; `load()` the `.ogv` path the answer names.
+- **Converting by hand.** The import tools convert; a hand-made ffmpeg command also fails on builds without libtheora (Homebrew's default ffmpeg has none).
 
 ## Edge cases
 
-- **Splash loop must be tiny in build size.** Loops compress aggressively because of low motion. Target ≤2MB by exporting at 720p, low bitrate, in DaVinci. Studio's import doesn't re-encode by default.
+- **Splash loop must be tiny in build size.** Loops compress aggressively because of low motion. Target ≤2MB by exporting at 720p, low bitrate, in DaVinci. The import's conversion keeps quality high (Theora at quality 8, at most 1080p), so a small file starts from a 720p clip.
 - **Mobile portrait splash.** The reference image must be portrait — `aspectRatio` is ignored on the image-to-video path, and MCP image generation is square-only, so make the reference in the Summer dashboard or crop it. Anchors preset 15 still works.
 - **Loop must sync to a music beat.** The video model doesn't know your BPM. Generate at the duration matching one bar at the menu music tempo (e.g. 120 BPM × 4 beats = 2s, or 8 beats = 4s) and confirm visually.
 - **Loop is behind translucent UI.** Generate with extra contrast headroom — the model tends toward mid-grey, and translucent UI on mid-grey reads muddy. Push for `high contrast cinematic` in the prompt.
@@ -209,7 +201,7 @@ If the MCP server isn't running, route the user to the Summer dashboard:
 1. Image tab → generate the reference still (the loop's "neutral frame").
 2. Video tab → image-to-video with `ltx`, duration 5s, aspect ratio per target.
 3. Prompt with the loopable-motion vocabulary above and `"looping, seamless"`.
-4. Download the result, transcode to `.ogv` if needed, place under `assets/video/loops/`.
+4. Import the clip's URL from a shell while Summer Engine runs: `summer tool import-from-url --args '{"url":"<clip url>","path":"res://assets/video/loops/<name>.ogv"}'`. It converts the clip to Ogg Theora (`.ogv`), the only video Summer Engine plays.
 
 Print the exact prompt + model + duration + aspect ratio so the user can paste it into the dashboard.
 
@@ -244,6 +236,8 @@ No Summer MCP tools in this session? Run each one as a command; when `summer --v
 | `summer_assets_search` | `summer assets search` |
 | `summer_docs_read` | `summer docs read` |
 | `summer_add_node` | `summer engine add-node` |
+| `summer_import_asset` | `summer engine import-asset` |
+| `summer_import_asset_by_id` | `summer engine import-asset-by-id` |
 | `summer_import_from_url` | `summer engine import-from-url` |
 | `summer_run_script` | `summer engine run-script` |
 | `summer_set_prop` | `summer engine set-prop` |

package/library/skills/cinematic-cutscene/SKILL.md

@@ -126,24 +126,11 @@ Lip-sync caveat: if the video shows the character clearly mouthing words and the
 
 ### 7. Import and wire as a VideoStreamPlayer
 
-**Transcode to Ogg Theora first.** The generated clip is an `.mp4`, and Summer Engine cannot load `.mp4` — the only video container in the build is `.ogv`. Measured against the shipped binary (4.6.1):
+**Import the `.mp4` as it is; the import converts it.** Summer Engine plays video only as Ogg Theora (`.ogv`), so every Summer import tool (`summer_import_from_url`, its batch, `summer_import_asset_by_id`, `summer_import_asset`) converts a video on the way in and saves it at the path you asked for with `.ogv`. The answer names the file in `videoConversions` and `note`:
 
 ```
-$ Summer --headless --path <proj> -s res://probe.gd
-VideoStream exts: ["ogv", "tres", "res"]
-ERROR: No loader found for resource: res://clip.mp4 (expected type: unknown)
-```
-
-Nothing transcodes for you — `summer_import_from_url` downloads the bytes, runs the engine's import pipeline, and *fails the import* if the file never becomes a loadable resource. Convert with ffmpeg or DaVinci before importing:
-
-```
-ffmpeg -i intro_shot_01.mp4 -c:v libtheora -q:v 8 -an intro_shot_01.ogv
-```
-
-Then:
-
-```
-summer_import_from_url(url="<hosted .ogv url>", path="res://assets/video/cinematics/intro_shot_01.ogv")
+summer_import_asset_by_id(assetId="<the shot's asset id>", path="res://assets/video/cinematics/intro_shot_01.mp4")
+→ importedTo: res://assets/video/cinematics/intro_shot_01.ogv
 ```
 
 Build a controller scene at `res://cinematics/Intro.tscn`: create it, then build its nodes in one script (`scenePath` names the new scene; the editor's open tab comes back afterwards):
@@ -204,7 +191,7 @@ Pattern: `<subject> + <action> + <camera move> + <lighting> + <stylistic anchor>
 - **Using `kling` for blocking iterations.** Validate framing and prompt on the cheaper `ltx` first; move to `kling` once the composition lands.
 - **Putting the cutscene on a `VideoStreamPlayer` without a fade.** Cuts straight from gameplay to video are jarring. Always wrap in a `ColorRect` fade in/out.
 - **Treating `assets.generate_video` as finished.** It answers `{ status: "running", job }` and no URL. Wait with `jobs.wait` until the job is done before there is anything to show or import.
-- **Importing the `.mp4` as-is.** The engine has no MP4 or WebM loader — only Ogg Theora (`.ogv`). Transcode first; an un-transcoded import fails and is rolled back.
+- **Loading the `.mp4` path after an import.** The engine has no MP4 or WebM loader; the import saved the shot as `.ogv`. `load()` the `.ogv` path the answer names.
 - **Asking `ltx` or `kling` for `duration: 3` or `duration: 8`.** On those two only 5 and 10 exist; anything else renders 5.
 - **Pairing `imageUrl` with `kling-turbo` or `veo3`.** Neither has an image-to-video endpoint — that combination is a 400.
 
@@ -227,7 +214,7 @@ If the MCP server isn't running, the user can do all of this in the Summer dashb
 1. Generate a reference image in the Image tab.
 2. Open the Video tab, paste the reference URL into the image-to-video field.
 3. Set model, duration, aspect ratio, and prompt as listed above.
-4. Download the `.mp4`, transcode it to Ogg Theora (`ffmpeg -i in.mp4 -c:v libtheora -q:v 8 -an out.ogv`), and drop the `.ogv` into `assets/video/cinematics/`. Summer Engine has no MP4 or WebM loader — `.ogv` is the only video container it can open.
+4. Import the shot's URL from a shell while Summer Engine runs: `summer tool import-from-url --args '{"url":"<shot url>","path":"res://assets/video/cinematics/<name>.ogv"}'`. It converts the `.mp4` to Ogg Theora (`.ogv`), the only video container Summer Engine can open.
 
 Print the exact prompt + model + duration + aspect ratio so the user can paste it into the dashboard verbatim.
 
@@ -265,6 +252,8 @@ No Summer MCP tools in this session? Run each one as a command; when `summer --v
 | `summer_docs_read` | `summer docs read` |
 | `summer_add_node` | `summer engine add-node` |
 | `summer_create_scene` | `summer engine create-scene` |
+| `summer_import_asset` | `summer engine import-asset` |
+| `summer_import_asset_by_id` | `summer engine import-asset-by-id` |
 | `summer_import_from_url` | `summer engine import-from-url` |
 | `summer_run_script` | `summer engine run-script` |
 | `summer_set_prop` | `summer engine set-prop` |

package/library/skills/headless-scripting/SKILL.md

@@ -48,14 +48,14 @@ Exit codes lie in both directions here.
 - **`--write-movie` under `--headless` is a deterministic crash**, not a graceful failure. `MovieWriter::add_frame()` dereferences a null image from the dummy renderer on frame one. Headless has no pixels, so there is no safe form of this. Frame capture needs the windowed verify instance below.
 - **`--quit-after 1`** hits the fast-exit path and aborts during static destruction. Use `--headless --quit-after 60` if you need a bounded editor run — with `--headless`, never without.
 
-### Never put a window on the user's screen
+### Never put an extra window on the user's screen from a shell
 
 <EXTREMELY-IMPORTANT>
-**Every engine launch you make is `--headless`.** The user did not ask you to open anything. A window that appears unasked steals focus, interrupts whatever they were doing, and is indistinguishable from a crash or a bug from their side. This is a product rule, not a convenience.
+**Every engine process you start from a shell is `--headless`.** The user did not ask you to open anything. A window that appears unasked steals focus, interrupts whatever they were doing, and is indistinguishable from a crash or a bug from their side. This is a product rule, not a convenience.
 
 The one exception is the verify instance, and it is safe precisely because it is not visible: `--summer-verify` opens a real rendering window that is **hidden, `NO_FOCUS`, and positioned at `(-32000,-32000)`**. That is why it can produce real pixels without ever appearing. Never reproduce the "I need a renderer" reasoning by launching a plain windowed editor — use `--summer-verify`.
 
-If you genuinely believe the user needs to see the editor, ask them first.
+This rule is about extra engine processes you start from a shell. Opening the Summer editor and playing the game in a window through the Summer tools is allowed and expected: `summer_play`, then `summer_screenshot` or `summer_frame_shot` to see the result. Close what you opened when you are done; one editor at a time.
 </EXTREMELY-IMPORTANT>
 
 ### Finding the binary — do not guess
@@ -401,7 +401,7 @@ Keep scripts in the project (`res://` is required for `-s`), but name them so th
 | Killing an import at 3s | Measured 0/8 assets registered. The floor is ~5s. |
 | A long-lived `--headless --editor` as a file watcher | It never rescans. Boot, act, exit. |
 | Adding `--quiet` | Swallows your own print() output. |
-| Launching the editor without `--headless` | Pops a window onto the user's screen unasked. |
+| A shell script run without `--headless` | Pops an extra window onto the user's screen unasked. To see the game, use `summer_play` and `summer_screenshot` in the open editor. |
 | Ignoring `ResourceSaver.save()`'s return value | Non-zero is a silent failure that ships. |
 | `pack()` without setting `.owner` on every node | Two success codes, nodes missing from the file. |
 | Verifying a write by reading the object you just wrote | In-memory read-back passes whether or not it landed. |
@@ -420,8 +420,11 @@ No Summer MCP tools in this session? Run each one as a command; when `summer --v
 
 | In this skill | Command |
 |---|---|
+| `summer_frame_shot` | `summer engine frame-shot` |
 | `summer_get_project_context` | `summer engine get-project-context` |
 | `summer_import_from_url` | `summer engine import-from-url` |
+| `summer_play` | `summer engine play` |
 | `summer_run_script` | `summer engine run-script` |
+| `summer_screenshot` | `summer engine screenshot` |
 | `summer_write_file` | `summer engine write-file` |
 <!-- /shell-commands -->

package/library/skills/in-game-purchases/SKILL.md

@@ -25,6 +25,11 @@ checkout fails with `insufficient_funds`, tell the player they need more
 Sparks and that they can get them in the Summer app, then let them press Buy
 again.
 
+This skill covers the purchase sheet and granting an effect on a server.
+For the rest of the store, use the `summer-store` skill: where items come
+from and how one becomes buyable, item slugs, `summer.items.json`, bundles
+and sales, owned items, and the authority's entitlement check.
+
 ## When to sell with Sparks
 
 - Sell anything that persists across sessions or devices (cosmetics, unlocks,
@@ -89,12 +94,20 @@ The operation returned by `request_checkout` also completes: ok on
 
 ## Minimal complete example
 
+Items are named by **slug** (Studio's "Item key", e.g. `sword`), which is
+the same in staging and production. Definition ids (`item_…`) differ between
+them, so never hard-code one. The slug getters need a Summer version that
+carries them (newer than 0.7.3); on an older one, use each environment's
+definition id with `has_owned_definition()` and `get_definition_id()`. The
+`summer-store` skill shows how to check.
+
 ```gdscript
 extends Node
 ## A one-item shop. Buys `offer_id` and unlocks from inventory.
 
-@export var offer_id := "offer_sword"
-@export var definition_id := "item_sword"
+## From the store listing: item.price.offer_id of the item whose get_slug() is item_slug.
+@export var offer_id := ""
+@export var item_slug := "sword"
 
 signal message(text: String)
 var _seen := {}
@@ -137,7 +150,7 @@ func _on_checkout(status: SummerCheckoutStatus) -> void:
 			pass
 
 func _sync_owned() -> void:
-	if Summer.client.items.has_owned_definition(definition_id):
+	if Summer.client.items.has_owned_slug(item_slug):
 		message.emit("Sword unlocked.") # the only place the item is granted
 ```
 
@@ -156,7 +169,7 @@ items. The client sends the authority only an owned item ID. The authority:
 
 1. reads that player's inventory with
    `Summer.authority.items.inventory_for_session(session)` and checks the
-   item is there, owned, and of the right definition;
+   item is there, owned, and the right item (its slug);
 2. checks its own record of redeemed item IDs, kept in the player's secret
    player data (`Summer.authority.player_data`), so the item grants once per
    player in every world;
@@ -165,7 +178,7 @@ items. The client sends the authority only an owned item ID. The authority:
 
 ```gdscript
 # On the dedicated authority.
-const EFFECT_DEFINITION := "item_grow_now"
+const EFFECT_SLUG := "grow_now"
 
 func redeem(session: SummerSession, owned_item_id: String) -> void:
 	var inv := Summer.authority.items.inventory_for_session(session)
@@ -176,7 +189,7 @@ func redeem(session: SummerSession, owned_item_id: String) -> void:
 	for candidate in inv.items:
 		if candidate.get_owned_item_id() == owned_item_id:
 			item = candidate
-	if item == null or not item.is_owned() or item.get_definition_id() != EFFECT_DEFINITION:
+	if item == null or not item.is_owned() or item.get_slug() != EFFECT_SLUG:
 		return # not owned by this player: never grant
 
 	var load_op := Summer.authority.player_data.load(session)
@@ -228,8 +241,11 @@ The game code is identical on every surface.
 
 ## Testing
 
-- Test against Summer staging, which runs in sandbox mode. *Why:* no real
-  money moves and results are identical to production.
+- Test against Summer staging, where Sparks come from test payments
+  (sandbox Sparks). *Why:* no real money moves and results are identical to
+  production. Use a staging account that bought Sparks in the staging Summer
+  app. The `summer-store` skill covers staging access and what makes an item
+  buyable there.
 - Walk every state: decline the sheet, let it expire, buy with too few
   Sparks, get Sparks in the Summer app, then buy the item. Kill the game while
   a checkout is pending and relaunch; the result must still arrive once.
@@ -255,6 +271,7 @@ Sparks in the Summer app.
 
 ## See also
 
+- summer-store: items, slugs, bundles, owned items and the authority check
 - multiplayer-state
 - ui-basics
 

package/library/skills/in-game-purchases/resource.yaml

@@ -1,6 +1,6 @@
 id: skill/in-game-purchases
 kind: skill
-version: 1.0.0
+version: 1.1.0
 summary: "Sell items for Sparks via the Summer purchase sheet: checkout, not enough Sparks, unlocks, grants."
 use_when:
   - "adding a shop, buy button or paid item to a Summer game and wiring request_checkout"
@@ -21,6 +21,7 @@ compatibility:
   engine: ">=4.6"
 related:
   skills:
+    - skill/summer-store
     - skill/multiplayer-state
     - skill/ui-basics
 source: official