summer-engine 3.7.0 → 4.0.0

package/library/skills/sound-effect/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/sound-effect
 kind: skill
 version: 1.1.0
-summary: "Make SFX one-shots and timed sequences (swings, hits, whooshes, reloads, UI) - offer three model versions to pick from, then wire them as AudioStreamPlayers."
+summary: "Make sound effects (swings, hits, whooshes, reloads, UI): three versions to pick from, then wire them."
 use_when:
   - generating short SFX one-shots — footsteps, weapon swings, UI clicks, hit impacts, environmental cues
   - an action, impact, or UI interaction is silent and needs a short one-shot sound wired to it

package/library/skills/spatial-placement/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: spatial-placement
-description: "Place 3D objects and modular kit pieces from measured geometry — inspect, place, starcast, measure, correct; floor, wall, facade, pipe and alcove recipes."
+description: "Place 3D objects and modular kit pieces from measured geometry: floors, walls, facades, pipes, alcoves."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: scene-and-project
@@ -108,17 +108,25 @@ with its back `-z` and open loops at both ends; `wall_lamp` has its back `-z`;
 `wall_clamp` is small with its back `-z`. Scene `res://facade_test.tscn` with a
 `Facade` Node3D at the origin.
 
+Place every piece at a rough pose in one `summer_batch`, then let the measured
+tools seat each one:
+
 ```text
-summer_instantiate_scene {scenePath:"res://facade_test.tscn", parent:"./Facade",
-  scene:"res://kit/wall_double.tscn", name:"G1", position:[0,0,0]}
-summer_instantiate_scene {..., scene:"res://kit/window_double.tscn", name:"G2", position:[2,0,0]}
+summer_batch {scenePath:"res://facade_test.tscn", receipt:"summary", ops:[
+  {op:"InstantiateScene", parent:"./Facade", scene:"res://kit/wall_double.tscn", name:"G1", position:[0,0,0]},
+  {op:"InstantiateScene", parent:"./Facade", scene:"res://kit/window_double.tscn", name:"G2", position:[2,0,0]},
+  {op:"InstantiateScene", parent:"./Facade", scene:"res://kit/window_double.tscn", name:"U1", position:[0,3,0]},
+  {op:"InstantiateScene", parent:"./Facade", scene:"res://kit/window_double.tscn", name:"U2", position:[2,3,0]},
+  {op:"InstantiateScene", parent:"./Facade", scene:"res://kit/gutter_section.tscn", name:"Pipe_1", position:[2.15,0.1,0.5]},
+  {op:"InstantiateScene", parent:"./Facade", scene:"res://kit/gutter_section.tscn", name:"Pipe_2", position:[2.15,1.1,0.1]},
+  {op:"InstantiateScene", parent:"./Facade", scene:"res://kit/wall_lamp.tscn", name:"Lamp", position:[1,2.6,0.5]}]}
+    -> one compact receipt: the seven nodes and their poses
+
 summer_place_adjacent {scenePath:"res://facade_test.tscn", subject:"./Facade/G2",
   reference:"./Facade/G1", axis:"x", side:"max", alignOtherAxes:{y:"min", z:"max"}}
     -> verify {gap:0, residuals:{y:0, z:0}}
-summer_instantiate_scene {..., scene:"res://kit/window_double.tscn", name:"U1", position:[0,3,0]}
 summer_place_adjacent {..., subject:"./Facade/U1", reference:"./Facade/G1",
   axis:"y", side:"max", alignOtherAxes:{x:"min", z:"max"}}
-summer_instantiate_scene {..., scene:"res://kit/window_double.tscn", name:"U2", position:[2,3,0]}
 summer_place_adjacent {..., subject:"./Facade/U2", reference:"./Facade/U1",
   axis:"x", side:"max", alignOtherAxes:{y:"min", z:"max"}}
 summer_measure {scenePath:"res://facade_test.tscn", mode:"plane",
@@ -127,11 +135,9 @@ summer_measure {scenePath:"res://facade_test.tscn", mode:"plane",
 
 summer_raycast {scenePath:"res://facade_test.tscn", origin:[2.15,0.5,1], direction:[0,0,-1]}
     -> hit ./Facade/G2, normal [0,0,1]: the wall front, by physics
-summer_instantiate_scene {..., scene:"res://kit/gutter_section.tscn", name:"Pipe_1", position:[2.15,0.1,0.5]}
 summer_attach_to_surface {scenePath:"res://facade_test.tscn", subject:"./Facade/Pipe_1",
   ray:{origin:[2.15,0.5,1], direction:[0,0,-1]}, backAxis:"-z", upAxis:"+y", standoff:0.02}
     -> seated_on "Facade/G2", final_gap 0.02, back_face_gap 0.02; the pipe keeps y 0.1
-summer_instantiate_scene {..., scene:"res://kit/gutter_section.tscn", name:"Pipe_2", position:[2.15,1.1,0.1]}
 summer_connect_ports {scenePath:"res://facade_test.tscn", subject:"./Facade/Pipe_2", subjectPort:"-Y",
   target:"./Facade/Pipe_1", targetPort:"+Y"}
     -> tilt_degrees 0, verify {distance:0, angle_degrees:0}, other_ports [{id:"+Y", direction:[0,1,0]}]
@@ -139,7 +145,6 @@ summer_repeat_along {scenePath:"res://facade_test.tscn", template:"res://kit/wal
   parent:"./Facade", start:[2.15,0.3,0.02], end:[2.15,1.9,0.02], spacing:0.45}
     -> count 4, created ["Facade/wall_clamp_1", ...]
 
-summer_instantiate_scene {..., scene:"res://kit/wall_lamp.tscn", name:"Lamp", position:[1,2.6,0.5]}
 summer_attach_to_surface {scenePath:"res://facade_test.tscn", subject:"./Facade/Lamp",
   surface:"./Facade/G1", backAxis:"-z", standoff:0}
 summer_starcast {scenePath:"res://facade_test.tscn", path:"./Facade/Lamp", directionSpace:"local"}

package/library/skills/spatial-placement/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/spatial-placement
 kind: skill
 version: 1.1.0
-summary: Place 3D objects and modular kit pieces from measured geometry — inspect, place, starcast, measure, correct; floor, wall, facade, pipe and alcove recipes.
+summary: "Place 3D objects and modular kit pieces from measured geometry: floors, walls, facades, pipes, alcoves."
 use_when:
   - positioning a prop, character, collider, or platform so it sits flush, avoids overlap, or keeps clearance
   - placing something against a wall, inside an alcove, or on a shelf and needing to know which side is blocked and by how much

package/library/skills/sprite-sheet/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: sprite-sheet
-description: "Generate animated 2D character sprites laid out as a sprite sheet — walk cycle, attack, idle, death — wired into AnimatedSprite2D / SpriteFrames."
+description: "Generate animated 2D character sprite sheets (walk, attack, idle, death) for AnimatedSprite2D."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: 2d-assets
 user-invocable: true
-allowed-tools: Read Grep Glob Write Edit summer_generate_image summer_slice_asset_sheet summer_get_studio_workflow summer_search_assets summer_import_from_url summer_import_asset_by_id summer_set_resource_property summer_write_file summer_add_node summer_set_prop summer_save_scene
+allowed-tools: Read Grep Glob Write Edit summer_assets_generate_image summer_assets_slice_sheet summer_assets_search summer_import_from_url summer_import_from_url_batch summer_import_asset_by_id summer_set_resource_property summer_write_file summer_add_node summer_set_prop summer_save_scene summer_call
 paths: ["assets/**", "sprites/**", "art/sprites/**"]
 ---
 
@@ -18,10 +18,10 @@ Sprite-sheet generation from a single text-to-image call is **unreliable**. Mode
 This skill therefore offers **three paths**, ranked by reliability:
 
 1. **Per-frame img2img** (most reliable) — generate the base pose, then generate each subsequent frame via `referenceImageUrl` with a small pose delta. Composite the frames into a sheet externally or wire each as a separate `SpriteFrames` entry.
-2. **Single-call sheet + auto-slice** (fast; sheet coherence is the gamble, not the cutting) — one prompt asks for the grid, then `summer_slice_asset_sheet` cuts it into individual frame assets server-side. Worth trying once for short cycles (4 frames or fewer) before falling back to (1).
+2. **Single-call sheet + auto-slice** (fast; sheet coherence is the gamble, not the cutting) — one prompt asks for the grid, then `assets.slice_sheet` cuts it into individual frames server-side. Worth trying once for short cycles (4 frames or fewer) before falling back to (1).
 3. **Manual authoring** (most reliable, slowest) — hand-author in **Aseprite** or **Piskel**. For pixel art at 32×32, this is often faster than fixing AI generations.
 
-There is no single "generate a sprite sheet" tool, but there **is** a shared two-tool sheet pipeline, and it is the same one Studio's Guided "sprite-sheet" workflow runs: `summer_generate_image` produces one sheet, then `summer_slice_asset_sheet({ assetId })` runs the server-side vision slicer that removes the background, detects each frame's bounding box, crops, and uploads every frame as its own asset. Call `summer_get_studio_workflow({ workflowId: "sprite-sheet" })` for the current ordered recipe and its stated limitations. Only Studio's frame-preview and visual timing-review UI is unreachable from MCP — the generation and the slicing both are reachable.
+There is no single "generate a sprite sheet" operation, but there **is** a shared two-step sheet pipeline, and it is the same one Studio's Guided "sprite-sheet" workflow runs: `assets.generate_image` produces one sheet, then `assets.slice_sheet({ assetId })` runs the server-side vision slicer that removes the background, detects each frame's bounding box, crops, and uploads every frame as its own image (one URL per slice). Call `summer_call({ op: "docs.workflows", input: { workflowId: "sprite-sheet" } })` for the current ordered recipe and its stated limitations. Only Studio's frame-preview and visual timing-review UI is unreachable from MCP — the generation and the slicing both are reachable.
 
 So do not tell the user to cut a generated sheet by hand or in ImageMagick. The cutting is automated; what is unreliable is inter-frame *consistency* inside the generated sheet.
 
@@ -38,7 +38,7 @@ So do not tell the user to cut a generated sheet by hand or in ImageMagick. The
 - The character is 3D — use `generate-motion` for skeletal animation.
 - The user wants a single static sprite → `pixel-art` or `character-portrait`.
 - The user wants UI animation (loading spinner, button hover) — animate via `AnimationPlayer` rotating/tweening a static texture instead. Don't sprite-sheet UI.
-- The user has 12+ frames per animation and 4+ animations. That is dozens to hundreds of generations, each using credits. Pause and agree on scope first.
+- The user has 12+ frames per animation and 4+ animations. That is dozens to hundreds of generations, each using credits. Pause and agree on scope first; `dryRun: true` on one frame's call shows its credits.
 
 ## Steps
 
@@ -69,16 +69,16 @@ State the path before starting: "I'll do per-frame img2img: 6 generations. The f
 Generate frame 1 (or use existing base). For each subsequent frame, prompt the pose delta and pass the previous frame as `referenceImageUrl`:
 
 ```
-summer_generate_image(
-  prompt="goblin warrior, walk cycle frame 2 of 6, right leg forward, slight bob upward, identical character, same costume, same palette. Not a different character, not a different costume, no scene background.",
-  referenceImageUrl="<frame 1 fileUrl>",
-  model="nano-banana-2",
-  style="<same as base>",
-  removeBackground=true
-)
+assets.generate_image({
+  prompt: "goblin warrior, walk cycle frame 2 of 6, right leg forward, slight bob upward, identical character, same costume, same palette. Not a different character, not a different costume, no scene background.",
+  referenceImageUrl: "<frame 1 fileUrl>",
+  model: "nano-banana-2",
+  style: "<same as base>",
+  removeBackground: true
+})
 ```
 
-`summer_generate_image` has no size argument; put negations in the prompt text. `removeBackground: true` gives you real alpha instead of a prompted "transparent background" that the model may paint as a literal checkerboard. `referenceImageUrl` only works on edit-capable models (`nano-banana-2`, `seedream-5-pro`, `nano-banana-lite`, `gpt-image-2`, `gemini-flash`, `flux-2`); `grok-imagine` has no edit endpoint and returns `edit_not_supported`.
+Keep `aspectRatio` (and `width` / `height`, if you set them) the same for every frame; put negations in the prompt text. `removeBackground: true` gives you real alpha instead of a prompted "transparent background" that the model may paint as a literal checkerboard. `referenceImageUrl` only works on edit-capable models (`nano-banana-2`, `seedream-5-pro`, `nano-banana-lite`, `gpt-image-2`, `gemini-flash`, `flux-2`); `grok-imagine` has no edit endpoint and returns `edit_not_supported`.
 
 Repeat for each frame. Save each as `goblin_walk_01.png`, `goblin_walk_02.png`, etc.
 
@@ -89,23 +89,24 @@ composite them into one sheet image.
 ### 3b. Path 2 — Single-call sheet, then auto-slice
 
 ```
-summer_generate_image(
-  prompt="goblin warrior walk cycle, sprite sheet, 6 frames in a horizontal row, identical character across frames, side view, frames clearly separated with empty space between them, consistent lighting, consistent palette. No scene background, no varying lighting, not a different character per frame.",
-  model="nano-banana-2",
-  style="none",
-  removeBackground=true
-)
+assets.generate_image({
+  prompt: "goblin warrior walk cycle, sprite sheet, 6 frames in a horizontal row, identical character across frames, side view, frames clearly separated with empty space between them, consistent lighting, consistent palette. No scene background, no varying lighting, not a different character per frame.",
+  model: "nano-banana-2",
+  style: "none",
+  aspectRatio: "21:9",
+  removeBackground: true
+})
 ```
 
-There is no `"pixel"` style preset (`style` is `realistic | cartoon | anime | none`; anything else is coerced to `none`) and no size argument; the layout and the negations have to be in the prompt.
+There is no `"pixel"` style preset (`style` is `realistic | cartoon | anime | none`). A wide `aspectRatio` gives a row of frames room; the layout and the negations have to be in the prompt.
 
 Then cut it with the same server-side slicer Studio uses, passing the asset id the generation returned:
 
 ```
-summer_slice_asset_sheet(assetId="<generated sheet assetId>")
+assets.slice_sheet({ assetId: "<generated sheet assetId>" })
 ```
 
-It returns the source dimensions plus per-slice URLs, names, categories, and bounding boxes. Import the frames you want by id with `summer_import_asset_by_id`.
+It returns `source` (the sheet's width and height) and `slices`: each slice's `url`, `name`, `category` and `bbox`. The slices are image URLs, not assets: import the frames you want with `summer_import_from_url_batch`.
 
 Inspect the result. If the frames are coherent and the count matches, proceed. If anatomy morphs across the row, or the slicer returns one giant box (items touching / no gaps), fall back to Path 1 or Path 3 — re-prompting with more separation between frames is the first thing to try.
 
@@ -202,7 +203,7 @@ func _physics_process(delta):
 - **Wiring an inconsistent sheet anyway** because you don't want to regenerate. Ship the inconsistency and the player notices the morphing limbs immediately. Cut the frame count or hand-author instead.
 - **Sprite-sheeting things that don't need to be sprite-sheeted.** UI animation, simple bobs, fades — use `AnimationPlayer` to tween a static texture instead. Sprite sheets are for character animation specifically.
 - **Pretending Aseprite is a failure.** Hand-authoring 4 pixel-art frames takes 10 minutes and looks better than 8 AI generations. Don't oversell AI here.
-- **Sending the user to ImageMagick or Aseprite to *cut* a generated sheet.** `summer_slice_asset_sheet` does that server-side. Hand off the creative work, not the mechanical work.
+- **Sending the user to ImageMagick or Aseprite to *cut* a generated sheet.** `assets.slice_sheet` does that server-side. Hand off the creative work, not the mechanical work.
 
 ## Edge cases
 
@@ -212,14 +213,18 @@ func _physics_process(delta):
 - **User wants a turn-around (rotating in place over 8 frames).** Same as 8-direction; generate single-frame per angle as anchor, accept that AI rotation won't be perfectly consistent.
 - **Animation needs to loop seamlessly.** Make frame N+1 explicitly bridge back to frame 1 in your prompt. Or generate one extra "bridge" frame and drop it.
 
+## Without Summer Engine
+
+In a session without Summer Engine tools (the assets profile; the `summer-assets` skill has the whole loop), do steps 1-3 and skip steps 4-6 (import, `AnimatedSprite2D`, trigger code). Pass `out` with the person's folder for each frame, or slice a sheet with `assets.slice_sheet` and save each piece with `assets.get` and `out` (the `summer-assets` skill says how). Tell the person the frame order and the frame rate you planned.
+
 ## Fallback (no MCP)
 
 Print the per-frame call sequence:
 
 ```
-Frame 1: summer_generate_image(prompt="<base>", model="nano-banana-2", style="none", ...)
-Frame 2: summer_generate_image(prompt="<base + delta>", referenceImageUrl="<frame 1>", ...)
-Frame 3: summer_generate_image(prompt="<base + delta>", referenceImageUrl="<frame 2>", ...)
+Frame 1: assets.generate_image({ prompt: "<base>", model: "nano-banana-2", style: "none", ... })
+Frame 2: assets.generate_image({ prompt: "<base + delta>", referenceImageUrl: "<frame 1>", ... })
+Frame 3: assets.generate_image({ prompt: "<base + delta>", referenceImageUrl: "<frame 2>", ... })
 ...
 ```
 
@@ -241,4 +246,4 @@ After the animation is wired:
 - `character-portrait` — base portrait for higher-res characters.
 - `generate-motion` — 3D-skeletal counterpart.
 - `sound-effect` — frame-synced SFX.
-- `../../references/mcp-tools-reference/mcp-tools-reference.md` — `summer_generate_image` schema.
+- `summer_docs_read` id `reference/mcp-tools-reference` — how to call `assets.generate_image`.

package/library/skills/sprite-sheet/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/sprite-sheet
 kind: skill
 version: 1.0.4
-summary: Generate animated 2D character sprites laid out as a sprite sheet — walk cycle, attack, idle, death — wired into AnimatedSprite2D / SpriteFrames.
+summary: "Generate animated 2D character sprite sheets (walk, attack, idle, death) for AnimatedSprite2D."
 use_when:
   - generating animated 2D character sprites laid out as a grid of frames — walk cycle, attack frames, idle bob, death sequence
   - a 2D sprite needs its frames laid out as one grid image for AnimatedSprite2D or SpriteFrames

package/library/skills/store-art/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: store-art
-description: "Make Summer Games store art per slot and flow: key art, covers, icons, screenshots, trailer: size, shape, text rules, fallbacks."
+description: "Make Summer Games store art per slot: key art, covers, icons, screenshots, trailer, size and text rules."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: deployment
 user-invocable: true
-allowed-tools: summer_read_library
+allowed-tools: summer_docs_read
 ---
 
 # /store-art — store art
@@ -14,7 +14,7 @@ This skill covers every store art slot per flow (desktop and mobile): size, shap
 
 Its current text lives on the hosted Summer Engine MCP, the same text the Studio agent reads, so it changes with the store and is never stale here. Load it before you act:
 
-1. `summer_read_library` with id `skill/store-art` returns the current text when this machine has a store sign-in (`summer login --store`).
+1. `summer_docs_read` with id `skill/store-art` returns the current text when this machine is signed in (`summer login`).
 2. A host that shows MCP prompts or resources has it as the `store-art` prompt and the resource `summer://skills/store-art`.
 3. Without a store sign-in: https://docs.summerengine.com/llms.txt lists every docs page; fetch any page as .md.
 

package/library/skills/store-art/resource.yaml

@@ -1,10 +1,10 @@
 id: skill/store-art
 kind: skill
 version: 1.0.0
-summary: "Make Summer Games store art per slot and flow: key art, covers, icons, screenshots, trailer: size, shape, text rules, fallbacks."
+summary: "Make Summer Games store art per slot: key art, covers, icons, screenshots, trailer, size and text rules."
 use_when:
   - "making or choosing store art for Summer Games: key art, cover, icon, screenshots, trailer"
-  - "summer_store_set_art rejects an image for its shape or size, or summer_store_get_listing says an art slot is missing"
+  - "store.set_art rejects an image for its shape or size, or store.get_listing says an art slot is missing"
   - "deciding whether a store image may carry text, and which slot falls back to which"
 facets:
   lifecycle:

package/library/skills/store-listing/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: store-listing
-description: "Write a Summer Games store page per flow (desktop, mobile): targets, title, tagline, descriptions, tags, and what never to write."
+description: "Write a Summer Games store page: title, tagline, descriptions, tags, per platform, and what never to write."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: deployment
 user-invocable: true
-allowed-tools: summer_read_library
+allowed-tools: summer_docs_read
 ---
 
 # /store-listing — store listing
@@ -14,7 +14,7 @@ This skill covers the store page text per flow (desktop and mobile): targets, ti
 
 Its current text lives on the hosted Summer Engine MCP, the same text the Studio agent reads, so it changes with the store and is never stale here. Load it before you act:
 
-1. `summer_read_library` with id `skill/store-listing` returns the current text when this machine has a store sign-in (`summer login --store`).
+1. `summer_docs_read` with id `skill/store-listing` returns the current text when this machine is signed in (`summer login`).
 2. A host that shows MCP prompts or resources has it as the `store-listing` prompt and the resource `summer://skills/store-listing`.
 3. Without a store sign-in: https://docs.summerengine.com/llms.txt lists every docs page; fetch any page as .md.
 

package/library/skills/store-listing/resource.yaml

@@ -1,10 +1,10 @@
 id: skill/store-listing
 kind: skill
 version: 1.0.0
-summary: "Write a Summer Games store page per flow (desktop, mobile): targets, title, tagline, descriptions, tags, and what never to write."
+summary: "Write a Summer Games store page: title, tagline, descriptions, tags, per platform, and what never to write."
 use_when:
   - "writing or fixing a game's store page text on Summer Games: title, tagline, description, tags"
-  - "summer_store_update_listing or summer_store_get_listing says a text field is missing or wrong"
+  - "store.update_listing or store.get_listing says a text field is missing or wrong"
   - "choosing the targets (web, Mac, Windows, Linux, iPhone, Android) that decide the desktop and mobile store flows"
 facets:
   lifecycle:

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

@@ -5,11 +5,11 @@ license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: multiplayer-and-networking
 user-invocable: true
-allowed-tools: Read Grep Edit Write summer_get_script_errors summer_play summer_stop summer_get_diagnostics summer_open
+allowed-tools: Read Grep Edit Write summer_get_script_errors summer_play summer_stop summer_get_diagnostics summer_call
 paths: ["**/*.gd"]
 ---
 
-# /summer-analytics — game events you can chart later
+# /summer-analytics — game events you read in Grow
 
 ## Overview
 
@@ -105,9 +105,11 @@ On the client, after a menu choice:
 
 ### 4. Read the results
 
-Open the game's analytics in Studio: `summer_open` with target `game` and
-params `gameId` (your game's id) and `section: "analytics"`. Events show up
-there after a short delay.
+`analytics.summary` (hosted, after `summer login`) returns the
+game's top custom events next to its store page views, launches and play
+time; the `grow-analytics` skill says how to read them. In Studio:
+`studio.open` with target `game`, params `gameId` (your game's id) and
+`section: "analytics"`. Events show up after a short delay.
 
 ## Result codes
 

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

@@ -1,6 +1,6 @@
 id: skill/summer-analytics
 kind: skill
-version: 1.0.0
+version: 1.0.1
 summary: "Send game events to Summer analytics from the authority or client: fire-and-forget, never blocking gameplay."
 use_when:
   - "adding analytics, telemetry or event tracking to a Summer game: level completed, coin collected, tutorial funnel"
@@ -25,5 +25,5 @@ related:
     - skill/grow-analytics
 source: official
 license: MIT
-status: preview
+status: stable
 recommended: false

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

@@ -0,0 +1,168 @@
+---
+name: summer-apps
+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_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
+
+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
+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 (`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: `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. |
+
+## When to build one
+
+- The person asks for a tool ("build us a loot balance tool", "track every creature
+  from concept to in-engine", "a board to review playtest clips").
+- They need a UI to decide or edit something they will come back to.
+- Not for a one-off answer: reply in chat instead.
+- Not when Summer already does it (above).
+
+## Layout or code
+
+- **Layout** (`format: "layout"`): a JSON layout of kit nodes. Quick, throwaway,
+  always on brand. Use it to ask the person to pick, rate or fill something now.
+- **Code** (default): `index.html` + JS/CSS with the Summer SDK and UI kit. Use it
+  for state, editing, shared data, generation or engine access.
+
+## Start from the working app
+
+Read these before writing code; they are exact:
+
+- [minimal-app.md](minimal-app.md): a complete working app (manifest, `index.html`,
+  `app.js`) built from kit components, using shared data, live changes, the viewer, `page.declare`, an
+  agent event, an agent tool and frame-move state. Copy it and change it.
+- [sdk-reference.md](sdk-reference.md): every SDK call with its exact arguments and
+  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 `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 `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>` (`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
+ES modules with root paths: `<script type="module" src="/summer-sdk/v1.js">` and
+`<script type="module" src="/summer-ui/v1/ui.js">`. Then `await summer.ready` before
+the first call, and reach data only through `summer.data.collection(name)`.
+
+## The loop
+
+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: `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. `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; `apps.get({ appId })` returns the current files.
+
+## Data is the API
+
+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`; `apps.tools`
+and `apps.read_data` return it, so any agent knows what a record looks like.
+
+```json
+{ "appId": "<id>", "ops": [
+  { "op": "patch", "collection": "items", "recordId": "bow", "patch": { "damage": 36 }, "ifRevision": 4 },
+  { "op": "put", "collection": "notes", "recordId": "n-17", "data": { "text": "Boss too long", "status": "open" } },
+  { "op": "remove", "collection": "notes", "recordId": "n-3" }
+] }
+```
+
+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.
+
+## Agent tools
+
+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)`.
+`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
+
+- Declare only the permissions the app uses; declare every `engineFiles` path and
+  every `agentEvents` name. A missing one fails at runtime with `permission_missing`.
+- The app runs sandboxed (`allow-scripts allow-forms allow-popups allow-modals
+  allow-downloads`, never `allow-same-origin`): no cookies, no `localStorage`, no network
+  unless the workspace allows a domain. Keep state in `summer.data`.
+- Paid SDK calls spend the credits of the person using the app. Say so before
+  building an app that generates.
+- Use real data (`summer.data`, `summer.assets`, `summer.engine.readFile`), never
+  placeholder numbers.
+- Studio moves an idle app to a fresh frame every few minutes. Keep UI state you care
+  about in shared data, or return it from `summer.app.onSnapshot(() => state)` (up to
+  256 KB) and read it back from `(await summer.ready).restored`. Wrap Web Audio playback
+  in `summer.app.busy(true)` / `summer.app.busy(false)` so a long sound is not cut;
+  `<audio>` and `<video>` count on their own.
+- 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
+  `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; `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.

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

@@ -0,0 +1,57 @@
+# The Summer App manifest
+
+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:
+
+```json
+{
+  "name": "Loot table",
+  "purpose": "Balance item stats and write them to res://data/items.json",
+  "permissions": ["data", "assets:read", "generate", "ai", "team:read", "engine:read", "engine:write"],
+  "engineFiles": ["res://data/items.json"],
+  "collections": {
+    "items": {
+      "description": "One weapon or armour piece",
+      "fields": {
+        "name": { "type": "string", "required": true },
+        "damage": { "type": "number", "description": "Damage per hit" },
+        "speed": { "type": "number", "description": "Attacks per second" },
+        "tags": { "type": "array" }
+      }
+    }
+  },
+  "agentEvents": ["items.written"],
+  "agentTools": [
+    {
+      "name": "nerf_item",
+      "description": "Lower one item's damage by a percent",
+      "input": {
+        "type": "object",
+        "properties": { "id": { "type": "string" }, "percent": { "type": "number" } },
+        "required": ["id", "percent"]
+      }
+    }
+  ],
+  "surface": "both",
+  "dock": { "preferred": "bottom" },
+  "plugin": { "name": "loot_tools" }
+}
+```
+
+| Key | Rules |
+|---|---|
+| `name` | Required, 1-80 characters. |
+| `purpose` | Up to 280 characters: what the tool does and where its data goes. |
+| `permissions` | Only these: `data`, `assets:read`, `assets:write`, `generate`, `ai`, `projects:read`, `team:read`, `grow:read`, `engine:read`, `engine:write`, `choices`. `engine:write` includes `engine:read`; `assets:write` includes `assets:read`. No permission is needed for `app.*`, `agent.*`, `page.*` and `team.presence`. |
+| `engineFiles` | Up to 50 `res://` paths `engine.readFile` / `writeFile` may touch. |
+| `collections` | Up to 50, keyed by collection name (lowercase `a-z 0-9 _ . -`). Each: `description`, `fields` (up to 50, name `[A-Za-z_][A-Za-z0-9_]*`) with `type` (`string`, `number`, `integer`, `boolean`, `object`, `array`, `any`), `description`, `required`. Descriptive: agents and people read it; writes are not rejected for it. |
+| `agentEvents` | Up to 50 names (`a-z 0-9 _ . -`) the app sends with `summer.agent.send`. |
+| `agentTools` | Up to 20: `name` (`a-z 0-9 _`, max 64), `description` (max 1,000), `input` (JSON Schema, up to 8 KB). |
+| `surface` | `page` (the Studio app page, default), `dock` (an editor dock) or `both`. A dock layout must work from 320 px wide; docked apps get selection and scene events (`summer.engine.onEvent`). |
+| `dock` | `{ "preferred": "left" \| "right" \| "bottom" }`. |
+| `plugin` | `{ "name": "<folder>" }`: the app may also write `res://addons/<folder>/`. |
+| `entry` | Always `index.html` (you can leave it out). |
+
+The whole manifest is at most 200 KB. A code app's bundle: `index.html` at the root, at most
+300 files, 10 MB, 5 MB per file.