summer-engine 3.8.0 → 4.2.0

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

@@ -1,7 +1,7 @@
 id: skill/concept-art
 kind: skill
 version: 1.0.2
-summary: Explore art direction with 3-4 rough concept variants of a character, environment, or prop to pick a vibe before committing to a final asset.
+summary: "Explore art direction with 3-4 rough concept variants of a character, environment or prop."
 use_when:
   - exploring art direction with rough variants before committing to a final asset
   - the user wants a mood board, rough sketches, or 'what could this look like'

package/library/skills/concept-to-level/SKILL.md

@@ -0,0 +1,258 @@
+---
+name: concept-to-level
+description: "Take a 3D map from concept art to a shippable level: questions for the user, owned lanes, render checks, collision kept in step."
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: level-design
+user-invocable: true
+allowed-tools: Read Grep Glob Write Edit Bash summer_assets_generate_image summer_assets_generate_3d summer_jobs_wait summer_call summer_screenshot summer_get_scene_tree summer_inspect_node summer_set_prop summer_save_scene summer_get_diagnostics summer_get_script_errors
+paths: ["**/*.tscn", "**/*.gdshader", "**/*.gdshaderinc", "level/**", "levels/**", "docs/**", ".summer/**"]
+---
+
+# concept-to-level — from concept art to a polished level
+
+Use this when a 3D map has to go from "here is the idea" to a level that
+looks finished, plays right online and offline, and runs well. It is the
+process and the judgment; the specialist skills it names do the leaf work.
+
+Distilled from one long build of a 1v1 arena duel map (a white-marble drill
+yard on a mountain peak above the clouds, with god hands that change the
+map mid-match). Its mistakes are the reason most rules below exist.
+
+**Core principle:** agree the look before you build it, build in lanes that
+each own their files, and never call a lane done without a render you have
+opened for the user.
+
+## When to use
+
+- "Turn this concept art into the real map." (3D, shipping quality)
+- "Rework this level's theme, keep the layout."
+- "Polish this map: materials, props, sky, effects."
+- Several agents will work on one map at once.
+
+## When NOT to use
+
+- A 2D or quick playable scene from a reference image: `scene-to-level`.
+- Designing layout, pacing and encounters on paper: `design-level`.
+- One asset: `prop-model`, `environment-kit`, `organic-model`.
+- Only picking a style: `concept-art`, `art-direction`.
+
+## Ask these before you build
+
+Ask in batches of two or three, not all at once. Record the answers in the
+design doc. Each line says why it matters and what broke when it was not
+asked.
+
+**Theme and fantasy**
+- [ ] What is this place, who owns it, what is the player there? *Drives every
+  prop and material choice. "A drill yard where players are guests" gave
+  the map its whole prop list.*
+- [ ] Which reference frames are the bar? Show 3-4 generated options and get
+  a pick. *A god power built from a text brief was rejected twice; three
+  concept images got a clear pick in one reply.*
+
+**Layout and gameplay**
+- [ ] What layout stays, what may change? May colliders, spawns and zones
+  move? *Decides whether you must recompile server collision and update
+  tests.*
+- [ ] Which surfaces are walkable, lethal, or "risky perches"? Where are the
+  ring-outs? *Fall zones need their own checks.*
+- [ ] Should dynamic events (moving hazards, raised platforms, collapsing
+  walls) feel big and slow or quick? Should the warning show where it lands?
+  *The first sliding-hazard warning drew the whole path on the floor; the
+  user found it too easy to dodge.*
+- [ ] What should the fight feel like? *"A battle for the high ground" turned
+  a vague light platform into layered plates with jump routes.*
+
+**Quality and readability**
+- [ ] What is the quality bar for close-ups? *Users inspect props at arm's
+  length: flat untextured parts, floating chains and sticks clipping
+  surfaces all got flagged.*
+- [ ] What must stay readable? Set a number (we used: player silhouettes keep
+  at least 60% of clean brightness under every effect).
+- [ ] How dark or saturated may effects get? *"Dark and evil, red only in thin
+  veins" was a rule we had to learn after a too-red pass.*
+
+**Platform and runtime**
+- [ ] Target hardware and platforms (mobile? integrated laptops?) and frame
+  budget. *Measure early; one decorative set cost a quarter of all triangles.*
+- [ ] Does the map run online? What does the online build strip? *Our online
+  map build removed particle nodes and ran no map scripts.*
+- [ ] What must be baked versus procedural? (Baked = no CPU, cannot react;
+  procedural = can aim and track.) *The floating statue had to be baked; the
+  god hands had to aim procedurally.*
+
+**Rules and process**
+- [ ] Game rules that limit design (rewards, odds, trading, licences)? Which
+  files are off-limits to you?
+- [ ] Deadlines and demos? *Before a demo: stop background work, commit only
+  verified lanes, keep fallbacks.*
+- [ ] Commit, push and PR policy.
+
+## The pipeline
+
+### 1. Frames first
+
+Generate several cheap options with `assets.generate_image` (see
+`concept-art`): an aerial overview, eye level, one per hero element. Get a
+pick. Save the picked frames in the repo next to the design doc and check
+every lane's renders against them. When a lane stalls on taste, generate
+three directions for that element and ask again; do not iterate blind.
+
+### 2. Design doc
+
+One markdown file per map: theme, layout and what is kept, floor, walls,
+backdrop, props, materials rule, effects, dynamic events, performance
+budget, open questions. Every user answer goes in. Lanes read it; you
+update it when the user changes direction.
+
+### 3. Blockout
+
+Rough geometry for everything at final scale, with a visible "not final"
+material. Remaining blockout material is the to-do list. Keep a stand-in
+player capsule for scale in every render.
+
+### 4. Lanes
+
+Split by system, one owner each:
+
+| Lane | Owns |
+|---|---|
+| Floor | ground materials, inlays, spawn floors |
+| Walls / kit | modular kit, ring or room assembly, wall collision |
+| Backdrop | sky, distant terrain, clouds, fog, kill height |
+| Props | cover pieces, set dressing, shared material library |
+| Cloth | banners and flags with sway |
+| Lighting and effects | sun, fire, glows, corruption-style map states |
+| Events | dynamic hazards, their visuals, spec for the server |
+
+The map scene is shared: every lane edits it only through the live editor,
+saves only its own changes, and reports what it touched. See "Running it
+with parallel agents" below.
+
+### 5. Materials rule
+
+No flat, unshaded surface on any model. Every surface gets real PBR textures
+or procedural detail. Specific rules that came from user feedback:
+
+- Bake a cavity/edge mask per prop, and scale edge wear by part thickness:
+  thin bars and chain links read as clean grey plastic otherwise.
+- Wood: plank UVs at real scale, grain along each board's long axis, darker
+  end grain, grime in the joints. Triplanar noise reads as cork.
+- Forged iron near black, rough (0.6-0.8) so curved bands do not mirror the
+  sky; rust only in recesses.
+- Brass: dark tarnish base, polish only on high points and real wear.
+- One shared material library for the map; props reuse it.
+
+### 6. Verify every lane with renders
+
+After each change, render fixed angles: the user's own angle if they sent a
+screenshot, eye level from the play space, a far view, from above. Open the
+images for the user. Compare to the frames. A lane is done when its renders
+pass, not when its script ran.
+
+### 7. Keep gameplay in step
+
+After any collider, spawn or zone change: recompile the server collision
+artifact, update tests that hard-code positions, run the covering tests,
+and only then commit. Moving a structure means re-running everything placed
+relative to it (see the reference file).
+
+### 8. Commit per verified lane
+
+Commit each lane when its renders and tests pass. Stage only that lane's
+files. Never commit files the editor rewrites on its own unless you meant to
+change them.
+
+## Hard-won technical rules
+
+Short list; details and reasons in
+[references/technical-rules.md](references/technical-rules.md).
+
+1. Never run heavy or reloading scripts in the live editor (recoding
+   shaders, reloading scenes, instantiating or freeing what an open scene
+   uses). It hung and crashed the editor. Build headless; import named files.
+2. Render previews from a separate short-lived engine process that loads
+   from disk; call `RenderingServer.force_draw()` before reading the image.
+3. One heavy process at a time, at low priority. Stop everything for demos.
+4. Online builds may strip particle nodes and map scripts. Make fire, sparks
+   and motes from shader-driven meshes; bake map animation into vertex
+   animation textures and set `custom_aabb`.
+5. Edit an open scene only through the live editor; never text-edit it on
+   disk while it is open.
+6. The editor rewrites some project files on its own. Commit surgically.
+7. Keep a fallback scene when swapping in an experimental asset.
+8. Generated 3D models need cleanup and a notices entry; third-party
+   textures need their source and licence recorded.
+9. Modular kits: zero coplanar overlaps, sealed seams, no see-through holes.
+10. Measure render cost early: triangles, draw calls, shadow casters, lights.
+
+## Running it with parallel agents
+
+- One lane per agent, with the files it owns written down. Shared files (the
+  map scene, a shared material library) have one owner per change.
+- Agents report with renders and exact file lists; the coordinator opens the
+  renders, checks them against the frames, and commits per lane.
+- Relay user feedback with concrete fixes ("thin parts read as grey plastic:
+  scale edge wear by thickness"), not the raw complaint alone.
+- When an agent cannot do something (a permission check blocked it), ask the
+  user; do not route around it.
+- Keep the machine cool: one heavy job at a time across all agents.
+- Before a demo: tell every agent to stop, commit only verified work, and
+  keep experiments out of the map.
+
+See `dispatching-parallel-agents` for the general pattern.
+
+## Definition of polished
+
+- [ ] Every surface has a real material; no blockout material left.
+- [ ] No floating, clipping or interpenetrating parts at close range
+      (chains, cloth, props on floors, decals on walls).
+- [ ] Renders from all fixed angles match the reference frames.
+- [ ] Players stay readable under every effect and event.
+- [ ] Spawns are centred, symmetric where the mode needs it, and face play.
+- [ ] Collision matches the visuals (within a few cm); server collision
+      recompiled; tests pass.
+- [ ] Fall zones kill, safe zones are safe, nothing catches falling players.
+- [ ] Works with the online build's limits (no particles or scripts if
+      stripped).
+- [ ] Render cost measured, biggest offenders known, low-end notes written.
+- [ ] Third-party sources and generated assets recorded in the notices.
+- [ ] Design doc matches what shipped.
+
+## Common mistakes
+
+- Building a hero effect before agreeing its look. Generate options first.
+- Splitting or regenerating a kit piece and overwriting the repo copy before
+  the scene that uses it is updated: parts vanish in the live map.
+- Fixing one banner when all banners share the cause. Check the whole set.
+- Calling a lane done from a headless log. Open a render.
+- Moving a room and forgetting the decals, banners, rock and spawns placed
+  around it.
+
+## See also
+
+- `concept-art`, `art-direction`, `design-level`, `scene-to-level`
+- `environment-kit`, `fabricating-assets`, `prop-model`, `tileable-texture`
+- `3d-lighting`, `vfx-fire`, `vfx-dissolve`, `procedural-animation`
+- `headless-scripting`, `bounded-engine-runs`, `verifying-scenes`
+- `tune-performance`, `dispatching-parallel-agents`
+
+<!-- shell-commands: generated from the operation catalog by npm run generate:registry; do not edit by hand -->
+## From a shell
+
+No Summer MCP tools in this session? Run each one as a command; when `summer --version` is missing or below 4.0, use `npx -y summer-engine@latest` in place of `summer`. Fields are flags in kebab-case (`--scene-path res://main.tscn`) or one `--input '<json>'`, and `summer ops describe <op>` prints the exact input. The `summer-cli` skill has the rest.
+
+| In this skill | Command |
+|---|---|
+| `summer_assets_generate_3d` | `summer assets generate-3d` |
+| `assets.generate_image`, `summer_assets_generate_image` | `summer assets generate-image` |
+| `summer_get_diagnostics` | `summer engine get-diagnostics` |
+| `summer_get_scene_tree` | `summer engine get-scene-tree` |
+| `summer_get_script_errors` | `summer engine get-script-errors` |
+| `summer_inspect_node` | `summer engine inspect-node` |
+| `summer_save_scene` | `summer engine save-scene` |
+| `summer_screenshot` | `summer engine screenshot` |
+| `summer_set_prop` | `summer engine set-prop` |
+| `summer_jobs_wait` | `summer jobs wait` |
+<!-- /shell-commands -->

package/library/skills/concept-to-level/references/technical-rules.md

@@ -0,0 +1,150 @@
+# concept-to-level: technical rules in detail
+
+Each rule says what to do, why, and what went wrong without it. They come
+from one long 3D arena build in Summer Engine with several agents working
+on one map.
+
+## The live editor
+
+**Do not run heavy or reloading scripts in the live editor.** Recoding a
+shader, reloading a scene, or instantiating and freeing a scene that an open
+tab uses can hang the editor's main thread or crash it. We lost the editor
+twice to a clearance checker run inside it, and once more to a script that
+re-set shader code to refresh the cache ("Attempted to free invalid ID"
+spam, main thread stuck). Use the editor for small property edits and
+saves. Build meshes, bake data and run checks headless (see
+`headless-scripting`), then let the editor import the named files.
+
+**The editor keeps old shaders cached.** After a shader file changes on
+disk, the open editor may still draw the old version. Do not force a reload
+there; render from a fresh process instead.
+
+**Edit an open scene only through the live editor.** If you text-edit the
+`.tscn` on disk while it is open, the editor overwrites your change on its
+next save, or saves its stale copy over yours. The reverse also happens:
+pressing Play can save a stale open tab and resurrect deleted nodes. Close
+tabs you are not editing.
+
+**The editor rewrites some files on its own** (the project settings file,
+some scenes and resources it touches on load). Check `git diff` before every
+commit and stage only what you meant to change. To change one line of such a
+file, build the commit content from the last commit plus that line rather
+than staging the editor's whole rewrite.
+
+## Rendering previews
+
+**Render from a separate, short-lived engine process** that loads the map
+from disk, takes the frames, and exits. It sees the current shaders and
+meshes, cannot disturb the editor, and frees its memory when done.
+
+**Call `RenderingServer.force_draw()` before reading the viewport image.**
+Without it, later frames can come back identical to an earlier one when the
+window stops drawing in the background.
+
+**Watch for in-game UI covering the camera.** A level script may open a menu
+(class select, lobby) that hides the scene. Render the scene with that
+script disabled, or from an isolated viewport.
+
+**Fixed angles.** Keep a small set of saved cameras per map: overview, eye
+level from each spawn, each hero element close, from above. Reuse them so
+before and after renders are comparable.
+
+## Load
+
+One heavy process at a time across all agents (imports, Blender, headless
+runs, renders), at low priority. The machine overheating or the editor
+freezing during a demo costs more than the time saved. See
+`bounded-engine-runs` for time limits and muted runs.
+
+## Online constraints
+
+Check what the online build does to a map scene before designing effects.
+In our project the online client rebuilt the map's visuals, turned any node
+whose type contains "Particles" into a plain node, and ran no map scripts.
+Consequences:
+
+- Fire, sparks, smoke, motes: camera-facing mesh layers driven by shaders,
+  with soft depth fades. No particle nodes.
+- Animated set pieces (a statue floating against taut chains): bake the
+  motion into a vertex animation texture and play it in the vertex shader.
+  Set `custom_aabb` so the moving mesh is not culled. Zero CPU.
+- Dynamic events: the server owns the state (timings, collision on or off);
+  a client presenter drives the shader parameters from that state. Write the
+  spec for the server with timings in ticks and the exact collision bodies.
+- Lights survive, so cheap flickering lights are fine.
+
+## Baked versus procedural
+
+Bake what only needs to loop (statue, cloth idle). Make procedural what must
+aim or react: god hands that point their beams at a moving target need an
+aim layer (look-at or two-bone IK with damped, slightly overshooting motion)
+on top of the base pose, with one API all events call.
+
+## Fallbacks
+
+When you swap an experimental asset into the map (the floating statue), keep
+the previous scene file and say how to swap back. Do not swap untested
+assets in right before a demo unless the user asks.
+
+## Generated and third-party assets
+
+Generated 3D models need cleanup: decimate to a budget, check normals and
+inside-out meshes, merge or split parts deliberately, ground them on their
+support, give every surface a real material (a chain that rendered white
+had lost its material on import). Record each in the notices file with the
+tool named and its terms marked "not confirmed" until checked.
+
+Every third-party texture: source page, author, licence, download date,
+what was changed. Never guess a licence.
+
+## Modular kits
+
+After every kit rebuild check: zero coplanar overlapping faces, all seams
+welded (no gaps where pieces meet), a see-through scan with rays from inside
+the play space, and the collision against the visible faces (within a few
+cm). Rebuilds can change random block tones and baked shading on pieces you
+did not mean to change: compare against the committed version and restore.
+
+When splitting a kit piece out (to make it removable), copy its triangles
+out of the exported files instead of regenerating it, prove the split looks
+identical, and install the new pieces and the scene that uses them together.
+Overwriting a repo piece first made parts of the live map vanish.
+
+## Moving things
+
+Moving a room or structure moves the job, not one node. Re-run or re-check
+everything placed relative to it: decals (snap to the actual surface, drop
+what no longer fits), banners and their hooks, backdrop rock under it,
+spawn markers, collision, lights. Re-measure clearances, including cloth at
+full sway against the floor below.
+
+## Gameplay sync
+
+After a collider, spawn or zone change: recompile the server's collision
+artifact, update tests that hard-code positions, run the rules tests and the
+contract check, and read their PASS lines. Spawns: centred on the axis,
+mirrored exactly between teams (an exact 180 degree turn, not 180.56),
+evenly spaced, facing the play space.
+
+## Render cost
+
+Count early and after each lane: vertices, triangles, mesh instances, draw
+calls, shadow-casting surfaces, lights (and which cast shadows), decals.
+Know the biggest offenders by group. In our map, eight decorative figures
+seen only through bars were a quarter of all triangles; the fix was a
+low-end note to hide them and a planned decimation. Typical cuts: decimate
+hidden detail, merge kit pieces into fewer draws, no shadows on small
+props, shorter sun shadow distance, half-resolution post effects.
+
+## Dynamic events
+
+- Agree the feel first: scale, speed, how long it stays, what the warning
+  reveals. Big things move slowly, with anticipation and a held impact.
+- Telegraph fairly but not too precisely: a warning that draws the exact
+  path is too easy to dodge.
+- Check the event never makes the play space impassable and never kills
+  without warning.
+- Make what the player sees match what happens: a hole that is open in the
+  collision but painted over by a glow reads as solid floor.
+- In a showcase or demo loop, reset destroyed pieces so the effect can be
+  watched again.

package/library/skills/concept-to-level/resource.yaml

@@ -0,0 +1,44 @@
+id: skill/concept-to-level
+kind: skill
+version: 1.0.1
+summary: "Take a 3D map from concept art to a shippable level: questions for the user, owned lanes, render checks, collision kept in step."
+use_when:
+  - polishing a 3D map or arena from concept art to shipping quality, with real materials, props, sky and effects
+  - reworking a level's theme and art while keeping its gameplay layout, with several agents working on one map
+  - deciding which questions to ask the user before building or polishing a level
+do_not_use_when:
+  - a quick 2D or playable scene from one reference image — skill/scene-to-level
+  - designing layout, pacing and encounters on paper — skill/design-level
+  - generating a single prop or kit — skill/prop-model or skill/environment-kit
+facets:
+  lifecycle:
+    - build
+  domains:
+    - level-design
+    - 3d
+    - world-building
+    - agent-workflow
+  modalities:
+    - scenes
+    - assets
+    - shaders
+    - docs
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/concept-art
+    - skill/art-direction
+    - skill/design-level
+    - skill/scene-to-level
+    - skill/environment-kit
+    - skill/fabricating-assets
+    - skill/headless-scripting
+    - skill/bounded-engine-runs
+    - skill/verifying-scenes
+    - skill/tune-performance
+    - skill/dispatching-parallel-agents
+source: official
+license: MIT
+status: preview
+recommended: false

package/library/skills/create-asset-sheet/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: create-asset-sheet
-description: "Generate a pack of 2D game assets from one prompt — tile sheet, UI kit, character pack, or biome set — sliced, classified, and saved as one pack ArtAsset."
+description: "Generate a pack of 2D assets from one prompt (tile sheet, UI kit, character pack, biome), sliced."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: 2d-assets
 user-invocable: true
-allowed-tools: Read Grep Glob Write Edit summer_get_studio_workflow summer_generate_image summer_slice_asset_sheet summer_search_assets summer_import_asset_by_id summer_import_from_url
+allowed-tools: Read Grep Glob Write Edit summer_assets_generate_image summer_assets_slice_sheet summer_assets_search summer_import_asset_by_id summer_import_from_url summer_import_from_url_batch summer_call
 paths: ["assets/**", "art/**", "sprites/**"]
 ---
 
@@ -42,7 +42,7 @@ Categories the classifier outputs (used to route into downstream pipelines):
 
 ## The cleanest path: the studio wizard
 
-The most reliable way to run this flow is the **Create Asset Sheet** wizard in Summer Studio's guided workflows. Open it for the user with `summer open workflows` (or `summer_open`) if they're working in the browser. The wizard:
+The most reliable way to run this flow is the **Create Asset Sheet** wizard in Summer Studio's guided workflows. Open it for the user with `summer open workflows` (or `studio.open`) if they're working in the browser. The wizard:
 
 - Offers a 2D / 3D mode toggle (2D is the slice flow described here; 3D is a soft pointer to `concept-art` + per-asset image-to-3D for now)
 - Surfaces six prompt templates (tile sheet, UI kit, menu, character pack, biome, freeform)
@@ -58,31 +58,32 @@ calls the same server-side slicer as the Studio wizard.
 ## Programmatic path (chat / agent driving the engine)
 
 1. **Load the exact current recipe.** Call
-   `summer_get_studio_workflow({workflowId: "asset-pack"})`. Follow its ordered
+   `summer_call({op: "docs.workflows", input: {workflowId: "asset-pack"}})`. Follow its ordered
    steps and report any `manual` handoff instead of pretending it ran.
 
-2. **Generate the sheet.** Call `summer_generate_image` with a prompt like:
+2. **Generate the sheet.** Call `assets.generate_image` with a prompt like:
 
    ```
    <theme> asset sheet: <comma-separated list of items>. Each item isolated with empty space around it, transparent or neutral background.
    ```
 
    - Pick model by style: pixel art → `grok-imagine`, painterly / illustrative / structured grids → `gpt-image-2`.
-   - 1024x1024 is the sweet spot. Larger sheets fragment in the slicer when individual assets get below ~64px.
+   - Square (`aspectRatio: "1:1"`, the default, about 1024x1024) is the sweet spot. Larger sheets fragment in the slicer when individual assets get below ~64px.
    - Keep the asset list to 6–20 items per sheet. Past 20, model attention degrades and slices get muddy.
 
 3. **Slice, remove background, detect, name, classify, crop, and save.** Pass
    the returned image asset id to:
 
    ```
-   summer_slice_asset_sheet({ assetId: "<generated asset id>" })
+   assets.slice_sheet({ assetId: "<generated asset id>" })
    ```
 
-   This is the same cloud slicing pipeline used by the Studio flow. Keep the
-   returned slice ids/names/categories; do not reimplement the vision boxes
-   locally.
+   This is the same cloud slicing pipeline used by the Studio flow. It answers
+   `slices` (each with `url`, `name`, `category`, `bbox`) and `source`; keep the
+   names and categories, and do not reimplement the vision boxes locally. Slicing
+   spends credits: `dryRun: true` shows how many.
 
-4. **Optional upscale.** The Studio wizard has per-slice HD upscale. Over MCP, for any crop where the longest side is under 256px, call `summer_generate_image` with the slice as `referenceImageUrl` and this prompt:
+4. **Optional upscale.** The Studio wizard has per-slice HD upscale. Over MCP, for any crop where the longest side is under 256px, call `assets.generate_image` with the slice `url` as `referenceImageUrl` and this prompt:
 
    ```
    Recreate this exact <name> at high resolution. Preserve every detail, the exact pose, the exact style. Sharper edges, more detail. Transparent background. Single isolated asset, no scene.
@@ -90,8 +91,9 @@ calls the same server-side slicer as the Studio wizard.
 
    - Don't upscale everything: each upscale is a paid generation, and large slices gain little.
 
-5. **Import what the game needs.** Use the returned asset ids with
-   `summer_import_asset_by_id`. Keep the source pack in My Assets so the agent
+5. **Import what the game needs.** The slices are image URLs, not assets: import
+   them with `summer_import_from_url_batch` (upscaled ones by their `assetId` with
+   `summer_import_asset_by_id`). Keep the source pack in My Assets so the agent
    and the human Studio session see the same result.
 
 ## Prompt patterns that work
@@ -137,6 +139,10 @@ calls the same server-side slicer as the Studio wizard.
 | Upscaled slice looks invented | Source was too small / too ambiguous | Don't upscale slices below ~32×32. Or accept the hallucination and edit |
 | Detection returns wrong category | Model misjudged context | User can override in the review step; not a blocker |
 
+## Without Summer Engine
+
+In a session without Summer Engine tools (the assets profile; the `summer-assets` skill has the whole loop), the studio wizard path works as written. On the programmatic path, stop after `assets.slice_sheet` and skip `summer_import_asset_by_id`: save each piece where the person asked with `assets.get` and `out` (the `summer-assets` skill says how), and tell them the paths.
+
 ## What this skill does NOT do (yet)
 
 - Per-asset planning and individual generation, where each asset is generated separately at full resolution.
@@ -144,3 +150,21 @@ calls the same server-side slicer as the Studio wizard.
 - Character animation routing. Once a slice is classified as `character`, the next step (sprite-sheet generation) is a separate skill that the user has to invoke manually.
 - Terrain auto-tiling / Wang-tile generation. Use `tileable-texture` for that.
 - Level composition / scene assembly. Use `design-level`.
+
+<!-- shell-commands: generated from the operation catalog by npm run generate:registry; do not edit by hand -->
+## From a shell
+
+No Summer MCP tools in this session? Run each one as a command; when `summer --version` is missing or below 4.0, use `npx -y summer-engine@latest` in place of `summer`. Fields are flags in kebab-case (`--scene-path res://main.tscn`) or one `--input '<json>'`, and `summer ops describe <op>` prints the exact input. The `summer-cli` skill has the rest.
+
+| In this skill | Command |
+|---|---|
+| `assets.generate_image`, `summer_assets_generate_image` | `summer assets generate-image` |
+| `assets.get` | `summer assets get` |
+| `summer_assets_search` | `summer assets search` |
+| `assets.slice_sheet`, `summer_assets_slice_sheet` | `summer assets slice-sheet` |
+| `docs.workflows` | `summer docs workflows` |
+| `summer_import_asset_by_id` | `summer engine import-asset-by-id` |
+| `summer_import_from_url` | `summer engine import-from-url` |
+| `summer_import_from_url_batch` | `summer engine import-from-url-batch` |
+| `studio.open` | `summer studio open` |
+<!-- /shell-commands -->

package/library/skills/create-asset-sheet/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/create-asset-sheet
 kind: skill
 version: 1.0.3
-summary: Generate a pack of 2D game assets from one prompt — tile sheet, UI kit, character pack, or biome set — sliced, classified, and saved as one pack ArtAsset.
+summary: "Generate a pack of 2D assets from one prompt (tile sheet, UI kit, character pack, biome), sliced."
 use_when:
   - generating a pack of 2D game assets from a single prompt — a tile sheet, UI kit, menu screen, character pack, or biome set
   - many matching sprites, tiles, or UI pieces are needed in one consistent style at once

package/library/skills/debug/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: debug
-description: "Disciplined bug/crash/error loop for Summer projects — script errors, console, debugger, hypothesis, fix, verify — before making code or scene changes."
+description: "Disciplined bug, crash and error loop: script errors, console, debugger, hypothesis, fix, verify."
 license: MIT
 compatibility: [Cursor, Claude Code, Codex, Windsurf, Gemini, OpenCode]
 category: debugging
@@ -143,7 +143,7 @@ Surface the proposed fix in plain language and ask permission. Two patterns:
 
 - For GDScript edits: `Read` the 20–40 lines around the error, `Edit` the exact change. Don't read the whole file. Don't reformat. Don't rename other things.
 - For scene edits: use the appropriate `summer_*` tool (`summer_add_node`, `summer_set_prop`, `summer_replace_node`). Group multi-step changes in `summer_batch` for one undo step.
-- **Nested resource properties:** `summer_set_resource_property` works against inline `sub_resource` targets too — pass `nodePath`, `resourceProperty`, and `subProperty` (there is no dotted `"mesh.size"` form). Structural failures (`node not found`, `property is not a resource`, `resource is null`) are explicit errors; a bad value shape is not — a JSON object instead of an engine literal string, a misspelled `key`/`subProperty`, or a wrong-typed value returns `ok:true` yet silently no-ops or coerces destructively on current engines (dict → material cleared; dict → `Color(0,0,0,1)`; newer engines reject these with `unknown_property` / `bad_value_shape` / `type_mismatch`). Pass class names and `Color(...)`/`Vector3(...)` strings, and confirm the fix in the saved `.tscn` or a snapshot diff, never from `ok` alone. See `../../references/mcp-tools-reference/mcp-tools-reference.md`.
+- **Nested resource properties:** `summer_set_resource_property` works against inline `sub_resource` targets too — pass `nodePath`, `resourceProperty`, and `subProperty` (there is no dotted `"mesh.size"` form). Structural failures (`node not found`, `property is not a resource`, `resource is null`) are explicit errors; a bad value shape is not — a JSON object instead of an engine literal string, a misspelled `key`/`subProperty`, or a wrong-typed value returns `ok:true` yet silently no-ops or coerces destructively on current engines (dict → material cleared; dict → `Color(0,0,0,1)`; newer engines reject these with `unknown_property` / `bad_value_shape` / `type_mismatch`). Pass class names and `Color(...)`/`Vector3(...)` strings, and confirm the fix in the saved `.tscn` or a snapshot diff, never from `ok` alone. See `summer_docs_read` id `reference/mcp-tools-reference`.
 
 ### 6. Verify — re-run the diagnostic that found it
 
@@ -248,3 +248,35 @@ When you've made code changes and want to declare them "verified":
 A typical cautionary scenario: many parallel agents write thousands of lines of game code in one batch with verification static-only. The build is "diagnostic-clean" yet the running game has telegraph meshes that render the wrong axis, parse-valid scripts that crash on first autoload because of a guard pattern that doesn't compile, projectile tracers sized so they read as straight lines instead of projectiles, transform-leaked colliders from a copied scene, and `@onready` paths that throw on every boot when the script is loaded into a sibling scene that lacks one of the referenced children. None of these surface in `summer_get_diagnostics` until something actually plays the game — which is exactly what a `RunVerification` probe does, and why "I had no way to test it" is not an available excuse.
 
 Static analysis is necessary but never sufficient.
+
+<!-- shell-commands: generated from the operation catalog by npm run generate:registry; do not edit by hand -->
+## From a shell
+
+No Summer MCP tools in this session? Run each one as a command; when `summer --version` is missing or below 4.0, use `npx -y summer-engine@latest` in place of `summer`. Fields are flags in kebab-case (`--scene-path res://main.tscn`) or one `--input '<json>'`, and `summer ops describe <op>` prints the exact input. The `summer-cli` skill has the rest.
+
+| In this skill | Command |
+|---|---|
+| `summer_docs_read` | `summer docs read` |
+| `summer_add_node` | `summer engine add-node` |
+| `summer_batch` | `summer engine batch` |
+| `summer_clear_console` | `summer engine clear-console` |
+| `summer_create_debug_report` | `summer engine create-debug-report` |
+| `summer_game_probe` | `summer engine game-probe` |
+| `summer_get_console` | `summer engine get-console` |
+| `summer_get_debugger_errors` | `summer engine get-debugger-errors` |
+| `summer_get_debugger_warnings` | `summer engine get-debugger-warnings` |
+| `summer_get_diagnostics` | `summer engine get-diagnostics` |
+| `summer_get_runtime_tree` | `summer engine get-runtime-tree` |
+| `summer_get_scene_tree` | `summer engine get-scene-tree` |
+| `summer_get_script_errors` | `summer engine get-script-errors` |
+| `summer_inspect_node` | `summer engine inspect-node` |
+| `summer_inspect_resource` | `summer engine inspect-resource` |
+| `summer_inspect_runtime_node` | `summer engine inspect-runtime-node` |
+| `summer_is_running` | `summer engine is-running` |
+| `summer_play` | `summer engine play` |
+| `summer_replace_node` | `summer engine replace-node` |
+| `summer_screenshot` | `summer engine screenshot` |
+| `summer_set_prop` | `summer engine set-prop` |
+| `summer_set_resource_property` | `summer engine set-resource-property` |
+| `summer_stop` | `summer engine stop` |
+<!-- /shell-commands -->

package/library/skills/debug/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/debug
 kind: skill
 version: 1.0.4
-summary: Disciplined bug/crash/error loop for Summer projects — script errors, console, debugger, hypothesis, fix, verify — before making code or scene changes.
+summary: "Disciplined bug, crash and error loop: script errors, console, debugger, hypothesis, fix, verify."
 use_when:
   - the user reports a bug, crash, error, or unexpected behavior in a Summer project, before making code or scene changes
   - the player falls through the floor or clips through walls