summer-engine 3.8.0 → 4.2.0

package/library/skills/scene-scripting/references/recipes-3d.md

@@ -0,0 +1,280 @@
+# scene-scripting: 3D recipes
+
+Every recipe below is the `source` of one call: `summer_run_script(scenePath="res://<the scene>.tscn", source=<the recipe>)`. Name the scene every time; it is opened first when it is not the edited one, and the person's tab comes back after the run. The core helpers (`add_node`, `find`, `add_mesh`, `make_material`, `save_scene` ...) are in the `scene-scripting` skill itself.
+
+## Scatter N instances with randomized transforms
+
+```gdscript
+func run(ctx):
+    var root = ctx.get_scene_root()
+    var rng := RandomNumberGenerator.new()
+    rng.seed = 12345                       # deterministic re-runs
+    var source: PackedScene = load("res://props/tree.tscn")
+    for i in range(40):
+        var tree := source.instantiate()
+        root.add_child(tree)
+        ctx.set_owner_recursive(tree)      # owns the whole instanced subtree
+        tree.position = Vector3(rng.randf_range(-20, 20), 0, rng.randf_range(-20, 20))
+        tree.rotation.y = rng.randf_range(0, TAU)
+        var s := rng.randf_range(0.8, 1.3)
+        tree.scale = Vector3(s, s, s)
+    ctx.report("scattered", 40)
+```
+
+## Procedural mesh via SurfaceTool
+
+```gdscript
+func run(ctx):
+    var root = ctx.get_scene_root()
+    var st := SurfaceTool.new()
+    st.begin(Mesh.PRIMITIVE_TRIANGLES)
+    st.set_normal(Vector3.UP)
+    st.add_vertex(Vector3(0, 0, 0))
+    st.add_vertex(Vector3(1, 0, 0))
+    st.add_vertex(Vector3(0, 0, 1))
+    var mesh := st.commit()                 # ArrayMesh
+    var mi := MeshInstance3D.new()
+    mi.mesh = mesh
+    mi.name = "GeneratedMesh"
+    root.add_child(mi)
+    ctx.set_owner_recursive(mi)
+    ctx.report("surfaces", mesh.get_surface_count())
+```
+
+For grids/heightfields, build `PackedVector3Array`s and feed `ArrayMesh.add_surface_from_arrays` directly. Call `st.generate_normals()` before `commit()` when you did not set normals by hand.
+
+## CSG primitives (fast blockouts)
+
+```gdscript
+func run(ctx):
+    var root = ctx.get_scene_root()
+    var body := CSGCombiner3D.new()
+    body.name = "Blockout"
+    root.add_child(body)
+    var box := CSGBox3D.new()
+    box.size = Vector3(6, 3, 6)
+    body.add_child(box)
+    var hole := CSGCylinder3D.new()
+    hole.operation = CSGShape3D.OPERATION_SUBTRACTION
+    hole.radius = 1.0
+    hole.height = 7.0
+    body.add_child(hole)
+    ctx.set_owner_recursive(body)           # owner is the SCENE root, not the parent
+```
+
+Live CSG nodes are the **older-engine fallback** — they re-evaluate every frame and should be converted before shipping (`scene-composition`). On a geometry-tier engine prefer `ctx.boolean(...)`, which bakes to a plain ArrayMesh and leaves no CSG nodes behind.
+
+## Boolean blockout — carve a doorway (geometry tier)
+
+Box minus box, baked. The inputs are consumed; only the result remains.
+
+```gdscript
+func run(ctx):
+    var wall = ctx.add_mesh("box", "Wall", null, {"size": Vector3(6, 3, 0.3)})
+    var hole = ctx.add_mesh("box", "DoorHole", null, {"size": Vector3(1.0, 2.1, 0.5)})
+    hole.position = Vector3(0, -0.45, 0)          # sink the opening to floor level
+    var carved = ctx.boolean(wall, hole, "difference")
+    if carved == null:
+        return                                     # reports carry the reason — read them
+    carved.name = "WallWithDoorway"
+    ctx.uv_box(carved)                             # boolean output needs UVs to take a texture
+    ctx.report("doorway", str(carved.get_path()))
+```
+
+Then `summer_snapshot_diff` must show `Wall` and `DoorHole` GONE and `WallWithDoorway` added — leftover inputs mean the boolean failed and returned null. Screenshot to check the opening is where you meant.
+
+## Lathe a goblet / pillar (geometry tier)
+
+`lathe` revolves a 2D profile (x = radius, y = height) around Y. Design the profile from the axis outward.
+
+```gdscript
+func run(ctx):
+    var profile := PackedVector2Array([
+        Vector2(0.0, 0.0),  Vector2(0.45, 0.0),   # foot
+        Vector2(0.08, 0.1), Vector2(0.08, 0.55),  # stem
+        Vector2(0.35, 0.7), Vector2(0.4, 1.1),    # bowl
+        Vector2(0.0, 1.15),
+    ])
+    var goblet = ctx.lathe(profile, "Goblet", null, 360.0, 48)
+    ctx.set_smooth(goblet, 40.0)                  # lathes look faceted without it
+    ctx.apply_material(goblet, ctx.make_material({"albedo_color": Color(0.85, 0.7, 0.2), "metallic": 0.8, "roughness": 0.25}))
+```
+
+A square-ish profile with `sides: 8` and `spin_degrees: 360` makes a chamfered pillar; `spin_degrees: 180` makes an apse/half-dome.
+
+## Sweep a rail / pipe (geometry tier)
+
+`sweep` extrudes a 2D cross-section along a 3D polyline.
+
+```gdscript
+func run(ctx):
+    var section := PackedVector2Array([        # small circle-ish octagon, the pipe wall
+        Vector2(0.05, 0), Vector2(0.035, 0.035), Vector2(0, 0.05), Vector2(-0.035, 0.035),
+        Vector2(-0.05, 0), Vector2(-0.035, -0.035), Vector2(0, -0.05), Vector2(0.035, -0.035),
+    ])
+    var path := PackedVector3Array([
+        Vector3(0, 1, 0), Vector3(4, 1, 0), Vector3(6, 1, 2), Vector3(6, 3, 6),
+    ])
+    var pipe = ctx.sweep(section, path, "SteamPipe")
+    ctx.set_smooth(pipe, 45.0)
+```
+
+Rails, roads, cables, gutters — same recipe, different cross-section. Keep path points a reasonable distance apart; hairpin corners self-intersect.
+
+## Terrain with collision (geometry tier)
+
+```gdscript
+func run(ctx):
+    var ground = ctx.terrain(Vector2(64, 64), 6.0, 1337, "Terrain")
+    ctx.apply_material(ground, ctx.make_material({"albedo_color": Color(0.35, 0.5, 0.25), "roughness": 1.0}))
+    ctx.report("terrain", ctx.summary())
+```
+
+Collision arrives automatically (a `StaticBody3D` + `HeightMapShape3D` child), already owned. Same seed → same terrain, so re-runs are deterministic. Pass `image_path` to drive heights from a grayscale heightmap instead of noise. Verify with `summer_screenshot framing:"camera"` — terrain reads wrong from preset framings' top-down angles.
+
+## Text signage (geometry tier)
+
+`add_mesh` accepts `torus` and `text` on geometry-tier engines:
+
+```gdscript
+func run(ctx):
+    var sign = ctx.add_mesh("text", "ExitSign", null, {"text": "EXIT", "depth": 0.08})
+    sign.position = Vector3(0, 2.6, -4)
+    ctx.apply_material(sign, ctx.make_material({"albedo_color": Color(1, 0.2, 0.2), "emission_enabled": true, "emission": Color(1, 0.1, 0.1), "emission_energy_multiplier": 3.0}))
+```
+
+Emissive text only proves itself in a `framing:"camera"` screenshot — preset framings substitute the environment and mute emission.
+
+## Decimate for LOD, convex collision for props (geometry tier)
+
+Dense generated/imported meshes (Meshy-class output) want both before they ship:
+
+```gdscript
+func run(ctx):
+    var prop = ctx.find("AncientStatue")         # e.g. a generated import
+    if prop == null:
+        ctx.report("error", "AncientStatue not found")
+        return
+    ctx.decimate(prop, 0.35)                      # keep ~35% of the triangles
+    var body = ctx.convex_collision(prop, true)  # V-HACD multi-shape for concave props
+    ctx.report("collision_body", str(body.get_path()))
+```
+
+`decimate` returns `false` (with a report entry) instead of ruining the mesh when the ratio is out of range. `convex_collision` owns every body it creates — the diff after `save_scene` is your receipt that nothing was silently dropped. Simple convex props (crates, rocks): leave `decompose` false, one hull is cheaper.
+
+## Mirror symmetry (geometry tier)
+
+```gdscript
+func run(ctx):
+    var left_tower = ctx.find("Tower")
+    var right_tower = ctx.mirror(left_tower, "x")   # mirrored duplicate, owned
+    right_tower.name = "TowerMirrored"
+```
+
+The mirror is a real duplicate with flipped winding/normals — edit either side independently afterward.
+
+## Animate — camera flythrough and a door-open (geometry tier)
+
+`animate` collapses the AnimationPlayer/library/track boilerplate into one call per property. Multiple calls with the same `anim_name` append tracks to the same clip.
+
+```gdscript
+func run(ctx):
+    var cam = ctx.add_camera(Vector3(0, 4, 12), Vector3.ZERO, true)
+    ctx.animate(cam, "position", [
+        [0.0, Vector3(0, 4, 12)],
+        [4.0, Vector3(8, 5, 4)],
+        [8.0, Vector3(0, 6, -10)],
+    ], "flythrough")
+    ctx.animate(cam, "rotation_degrees", [
+        [0.0, Vector3(-10, 0, 0)],
+        [4.0, Vector3(-12, 60, 0)],
+        [8.0, Vector3(-15, 175, 0)],
+    ], "flythrough")                               # same clip — second track appended
+
+    var door = ctx.find("Door")
+    ctx.animate(door, "rotation_degrees", [
+        [0.0, Vector3(0, 0, 0)],
+        [0.8, Vector3(0, 110, 0)],
+    ], "open")
+```
+
+Pass plain `position` / `rotation_degrees` values — the helper picks the right track type and handles the quaternion conversion for rotation. Verify by playing: `summer_play`, trigger the clip (or set autoplay), `summer_screenshot target:"game"`, `summer_stop`.
+
+## make_shader — dissolve / glow FX with the compile-error loop (geometry tier)
+
+`make_shader` is the safe lane for text shaders because compile errors come back **verbatim** in the result (the `make_shader_errors` report entry, with the line number) instead of failing silently to a magenta material:
+
+```gdscript
+func run(ctx):
+    var mat = ctx.make_shader("""
+shader_type spatial;
+uniform float threshold : hint_range(0.0, 1.0) = 0.3;
+uniform vec4 edge_color : source_color = vec4(1.0, 0.55, 0.1, 1.0);
+void fragment() {
+    float n = fract(sin(dot(UV * 12.0, vec2(12.9898, 78.233))) * 43758.5453);
+    if (n < threshold) { discard; }
+    ALBEDO = vec3(0.8);
+    EMISSION = edge_color.rgb * smoothstep(threshold + 0.08, threshold, n) * 4.0;
+}
+""", {"threshold": 0.35})
+    ctx.apply_material(ctx.find("Crystal"), mat)
+```
+
+The loop when it fails: read the exact compile error (line number included) from the `make_shader_errors` report entry → fix that line → re-run. Do not guess-and-mutate; the error text names the line and identifier. For production-grade dissolve/fire/glow (FBM noise include, controllers, cookbook variants) use the `vfx-<effect>` recipes — `make_shader` is the fast lane for one-off FX and for iterating on a shader before writing it to a file.
+
+## GridMap fills
+
+```gdscript
+func run(ctx):
+    var root = ctx.get_scene_root()
+    var grid: GridMap = root.get_node("GridMap")   # needs mesh_library assigned
+    for x in range(16):
+        for z in range(16):
+            grid.set_cell_item(Vector3i(x, 0, z), 0)     # item = MeshLibrary index
+    ctx.report("cells", 256)
+```
+
+Cells serialize into packed data — scripting is the ONLY sane way to fill them; never hand-edit `tile_map_data`-style fields as text.
+
+## 3-point lighting rig
+
+```gdscript
+func run(ctx):
+    var root = ctx.get_scene_root()
+    var rig := Node3D.new()
+    rig.name = "LightRig"
+    root.add_child(rig)
+
+    var key := DirectionalLight3D.new()
+    key.name = "KeyLight"
+    key.light_energy = 1.2
+    key.shadow_enabled = true
+    key.rotation_degrees = Vector3(-45, -30, 0)
+
+    var fill := OmniLight3D.new()
+    fill.name = "FillLight"
+    fill.light_energy = 0.4
+    fill.position = Vector3(-4, 2, 4)
+
+    var rim := SpotLight3D.new()
+    rim.name = "RimLight"
+    rim.light_energy = 0.8
+    rim.position = Vector3(0, 3, -5)
+    rim.rotation_degrees = Vector3(-20, 180, 0)
+
+    for light in [key, fill, rim]:
+        rig.add_child(light)
+    ctx.set_owner_recursive(rig)
+```
+
+Then `summer_screenshot` — lighting is exactly the kind of change you cannot judge without pixels.
+
+## Pitfalls
+
+| Pitfall | Reality |
+|---|---|
+| Hand-building CSG node trees on a geometry-tier engine | `ctx.boolean/lathe/sweep/extrude_polygon` bake clean ArrayMeshes with no live CSG left behind. |
+| Re-running a failed `make_shader` with a guessed fix | The compile error is in the `make_shader_errors` report verbatim, with the line. Read it, fix that line. |
+| Hand-writing AnimationPlayer/library/track plumbing | `ctx.animate` is one call per property and dodges the quaternion trap. |
+| Heavy batch loop in `summer_run_script` | It blocks the live editor. Move project-wide work to `summer_run_editor_script`. |
+

package/library/skills/scene-scripting/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/scene-scripting
 kind: skill
-version: 1.1.1
-summary: One GDScript in the live editor (summer_run_script) builds scenes, 2D levels, HUDs and gameplay wiring instead of CRUD chains; verify with diff + screenshot.
+version: 1.2.0
+summary: "Build scenes, levels, HUDs and wiring with one editor GDScript (summer_run_script) instead of call chains."
 use_when:
   - a scene change needs 3+ related ops or any computed placement — scattering, grids, rings, procedural meshes, geometry helpers, terrain, lighting rigs, keyframe animation, shader FX
   - a 2D level (tilemap paint, bodies, camera limits, parallax), an animated sprite, a HUD or Control tree, a persisted signal connection, an attached script, a prefab, input actions, an autoload, or the main scene should be built in one script
@@ -11,7 +11,7 @@ do_not_use_when:
   - a single property tweak — summer_set_prop is cheaper
   - one signal, one input binding, or one project setting — summer_connect_signal, summer_input_map_bind, summer_project_setting are one call each and ship today
   - "the engine build lacks RunSceneScript (Summer Engine 0.5.66 or newer; older engines return engine_lacks_op) — RunEditorScript and RunVerification DO ship today, so fall back to summer_run_editor_script or the scene tools"
-  - "the 2D/UI/gameplay-code ctx helpers (Summer Engine 0.5.66 or newer) are missing on the engine — the skill's fallback table names what works everywhere"
+  - "the 2D/UI/gameplay-code ctx helpers (Summer Engine 0.5.66 or newer) are missing on the engine — the fallback table in its references/ctx-api.md names what works everywhere"
 facets:
   lifecycle:
     - build
@@ -52,7 +52,7 @@ related:
     - template/2d-platformer
 source: official
 license: MIT
-status: preview
+status: stable
 recommended: true
 aliases:
   - skills/workflow/scene-scripting

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

@@ -1,11 +1,11 @@
 ---
 name: scene-to-level
-description: "Go from a scene reference image or concept art to a playable scene — orchestrates concept, asset pack, terrain, composition, and scene assembly."
+description: "Turn a reference image or concept art into a playable scene: concept, asset pack, terrain, assembly."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: level-design
 user-invocable: true
-allowed-tools: Read Grep Glob Write Edit summer_create_scene summer_open_scene summer_add_node summer_set_prop summer_set_resource_property summer_save_scene summer_get_scene_tree summer_inspect_node summer_search_assets summer_import_from_url
+allowed-tools: Read Grep Glob Write Edit summer_create_scene summer_open_scene summer_add_node summer_set_prop summer_set_resource_property summer_save_scene summer_get_scene_tree summer_inspect_node summer_assets_search summer_import_from_url summer_call
 paths: ["**/*.tscn", "**/*.gd", "assets/**", ".summer/**", "levels/**"]
 ---
 
@@ -125,3 +125,25 @@ Expect about 30 minutes for the asset packs (in parallel) and another 15 for sce
 - **Auto-tiling terrain.** The pipeline node exists in the decision tree but the leaf skill that implements it is not built.
 - **Animation orchestration.** Per-character `sprite-sheet` is invoked manually; no auto-pairing of characters with their animation pipelines yet.
 - **Gameplay code.** Player movement, interactions, win conditions — those are level-design + gameplay-mechanics skills, not this one.
+
+<!-- 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_search` | `summer assets search` |
+| `summer_add_node` | `summer engine add-node` |
+| `summer_create_scene` | `summer engine create-scene` |
+| `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_import_from_url` | `summer engine import-from-url` |
+| `summer_inspect_node` | `summer engine inspect-node` |
+| `summer_open_scene` | `summer engine open-scene` |
+| `summer_play` | `summer engine play` |
+| `summer_save_scene` | `summer engine save-scene` |
+| `summer_set_prop` | `summer engine set-prop` |
+| `summer_set_resource_property` | `summer engine set-resource-property` |
+<!-- /shell-commands -->

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

@@ -1,7 +1,7 @@
 id: skill/scene-to-level
 kind: skill
 version: 1.0.3
-summary: Go from a scene reference image or concept art to a playable scene — orchestrates concept, asset pack, terrain, composition, and scene assembly.
+summary: "Turn a reference image or concept art into a playable scene: concept, asset pack, terrain, assembly."
 use_when:
   - going from a scene reference image or concept art to a playable Summer Engine scene populated with the right assets and terrain
   - the user shares concept art or a reference screenshot and wants that location built as a playable scene

package/library/skills/skill-create/resource.yaml

@@ -21,5 +21,6 @@ related:
 source: official
 license: MIT
 status: stable
+bundled: false
 aliases:
   - skills/workflow/skill-create

package/library/skills/skill-improve/resource.yaml

@@ -21,5 +21,6 @@ related:
 source: official
 license: MIT
 status: stable
+bundled: false
 aliases:
   - skills/workflow/skill-improve

package/library/skills/skill-test/SKILL.md

@@ -23,7 +23,7 @@ For a single skill at `library/skills/<slug>/`, run these checks:
 4. **Collaborative protocol.** If the skill triggers user-visible writes, body must contain at least one of: `May I`, `I'm about to`, `Continue?`, `OK?`, `Proceed?`. Skills that only inspect/read are exempt.
 5. **Template-id resolved.** If the skill's frontmatter declares `template-id: <id>`, that id must exist in the template registry: `library/templates/<id>/resource.yaml` (see `library/templates/README.md`).
 6. **Behavioral spec.** If the skill has a spec (`evals/skills/specs/<slug>.md` or `tests/spec.md` in the skill folder), it has at least one `## Case` heading. A missing spec is a WARN, not a FAIL.
-7. **Relative links resolve.** Every `](../references/...)`, `](../../references/...)`, `](./references/...)`, and `](./examples/...)` link must point at an existing file (FAIL if broken). Links to other skills should use the bare slug (`design-mechanic`), not a path.
+7. **Links stay inside the skill folder.** Every relative link (`](./references/...)`, `](./examples/...)`) must point at an existing file in the skill's own folder (FAIL if broken). `summer setup` copies each skill folder alone, so a path that climbs out of it (`../`) breaks after install: name a shared reference by its library id (`summer_docs_read` id `reference/<slug>`) and another skill by its bare slug (`design-mechanic`).
 
 Output:
 
@@ -80,7 +80,17 @@ This skill is **read-only**. It never writes. No "May I" needed.
 
 ## See also
 
-- `../../references/collaborative-protocol/collaborative-protocol.md`
+- `summer_docs_read` id `reference/collaborative-protocol`
 - the template registry: `library/templates/<id>/resource.yaml` (see `library/templates/README.md`)
 - `tests/runner.md`
 - `evals/skills/specs/` — per-skill behavioral specs
+
+<!-- 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` |
+<!-- /shell-commands -->

package/library/skills/skill-test/resource.yaml

@@ -22,5 +22,6 @@ related:
 source: official
 license: MIT
 status: stable
+bundled: false
 aliases:
   - skills/workflow/skill-test

package/library/skills/skintokens-auto-rigging/resource.yaml

@@ -32,6 +32,7 @@ source: official
 license: MIT
 status: preview
 recommended: false
+bundled: false
 lint_exceptions:
   - url-allowlist
   - credential-pattern

package/library/skills/skybox-panorama/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: skybox-panorama
-description: "Generate a 360-degree equirectangular sky panorama and wire it as a PanoramaSkyMaterial Sky resource on WorldEnvironment in a 3D scene."
+description: "Generate a 360-degree sky panorama and wire it as a PanoramaSkyMaterial Sky resource on WorldEnvironment."
 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_search_assets summer_import_from_url summer_set_resource_property summer_write_file summer_add_node summer_set_prop summer_save_scene summer_inspect_node
+allowed-tools: Read Grep Glob Write Edit summer_assets_generate_image summer_assets_search summer_import_from_url summer_set_resource_property summer_write_file summer_add_node summer_set_prop summer_save_scene summer_inspect_node summer_call
 paths: ["assets/**", "art/sky/**", "environments/**"]
 ---
 
@@ -38,7 +38,7 @@ The most common failure is **non-equirectangular output**. Image models default
 ### 1. Search for an existing sky
 
 ```
-summer_search_assets(query="<vibe> sky panorama", assetType="2d_image", source="all")
+assets.search({ query: "<vibe> sky panorama", assetType: "2d_image", scope: "all" })
 ```
 
 Polyhaven (`polyhaven.com/hdris`) hosts hundreds of free CC0 HDRIs. They look more realistic than generated skies and carry real HDR lighting data. Prefer Polyhaven for realistic exteriors; generate for stylized, fantasy or sci-fi skies.
@@ -60,23 +60,24 @@ Load-bearing phrases:
 
 ### 3. Generate, then fix the aspect yourself
 
-Equirectangular MUST be 2:1 (width = 2× height). **`summer_generate_image` cannot give you that.** The tool takes only `prompt`, `model`, `style`, `referenceImageUrl`, `removeBackground` and `options`; there is no aspect or size argument, so every MCP image comes back at the server's 1:1 default. `aspectRatio` and `image_size` inside `options` are not recognized and are dropped without an error; the underlying provider does support 2:1-class aspect ratios, but nothing on this surface lets you request one.
+Equirectangular MUST be 2:1 (width = 2× height). **`assets.generate_image` has no 2:1 `aspectRatio`**: the closest are `16:9` and `21:9`. Generate at `16:9`. For a larger sky, leave `model` out and add `width: 2048, height: 1152`: a model that reaches that size is picked.
 
 ```
-summer_generate_image(
-  prompt="dramatic fantasy sky, golden hour, large purple-orange clouds, distant mountains silhouetted at very bottom, soft god-rays, 360 degree panoramic equirectangular projection, wide 2:1 panoramic framing, seamless horizontal wrap, no visible seam, no foreground objects, sky only. No vertical seam, no ground objects, no horizon-level detail, not distorted or warped, no characters, no buildings.",
-  model="nano-banana-2",
-  style="realistic"
-)
+assets.generate_image({
+  prompt: "dramatic fantasy sky, golden hour, large purple-orange clouds, distant mountains silhouetted at very bottom, soft god-rays, 360 degree panoramic equirectangular projection, wide panoramic framing, seamless horizontal wrap, no visible seam, no foreground objects, sky only. No vertical seam, no ground objects, no horizon-level detail, not distorted or warped, no characters, no buildings.",
+  model: "nano-banana-2",
+  style: "realistic",
+  aspectRatio: "16:9"
+})
 ```
 
-Asking for "2:1 panoramic framing" in the prompt biases the composition; it does not change the returned pixel dimensions. So one of these has to happen before the image is usable as a panorama:
+The result reports its real `width` and `height`. Then one of these has to happen before the image is usable as a panorama:
 
-- **Generate in the Summer dashboard instead**, which does expose aspect ratio, and bring the 2:1 result back with `summer_import_from_url`. This is the right path when the sky matters.
-- **Or crop the 1:1 result to 2:1** in any image editor before importing. You lose the top and bottom, which is usually acceptable for sky-only content — the zenith and nadir are the least informative regions — but it will clip a sun placed high in frame.
+- **Crop the 16:9 result to 2:1** by trimming the top and bottom (about 11% of the height) before importing. The width stays whole, so the horizontal wrap the prompt asked for survives; the zenith and nadir are the least informative regions of a sky anyway.
+- **Or generate in the Summer dashboard**, which offers 2:1, and bring the result back with `summer_import_from_url`.
 - **Or use a Polyhaven HDRI**, already 2:1 and better for realistic exteriors.
 
-Do not import a 1:1 image as a `PanoramaSkyMaterial` panorama and call it done — it wraps with obvious horizontal compression.
+Do not import a 16:9 or 1:1 image as a `PanoramaSkyMaterial` panorama and call it done — it wraps with obvious horizontal compression. Never crop the sides: that breaks the seamless wrap.
 
 ### 4. Verify the seam and projection
 
@@ -154,7 +155,7 @@ Then `summer_play` and look around. Sun in the right place? Seam invisible? Top/
 ## Anti-patterns
 
 - **Including foreground or horizon.** Mountains, trees, buildings at horizon level warp weirdly when sphere-mapped (the "swimming horizon" effect). Skies show ONLY sky. If the level needs distant mountains, model them as low-poly meshes in the scene, not in the sky texture.
-- **Assuming `options.aspectRatio` gave you 2:1.** It is silently ignored — the call succeeds and hands you a square image. A 1:1 or 16:9 panorama wrapped equirectangular has obvious horizontal compression. Crop it, or generate in the dashboard where the control exists.
+- **Assuming the image is 2:1.** `aspectRatio` has no 2:1 value; read the returned `width` and `height`. A 1:1 or 16:9 panorama wrapped equirectangular has obvious horizontal compression. Crop the top and bottom, or generate in the dashboard where 2:1 exists.
 - **Tight features at zenith/nadir.** Anything in the top or bottom 10% of the image gets pinched. Bias toward soft, diffuse features there.
 - **Expecting HDR / IBL quality.** AI panoramas are 8-bit. If the user needs realistic environment lighting from the sky, point them at Polyhaven HDRIs (CC0). AI is for visual sky, not for lighting.
 - **Forgetting `Repeat: Disabled` on import.** Panoramas wrap once via the material; if `Repeat` is on, you can get duplicate-tile artifacts at the seam.
@@ -167,19 +168,24 @@ Then `summer_play` and look around. Sun in the right place? Seam invisible? Top/
 - **Indoor scene.** Skyboxes are wasted indoors — use `BG_COLOR` or a flat black background. Don't generate a sky for a windowless dungeon.
 - **Visible vertical seam after generation.** Fix in Photoshop/GIMP: `Filter → Other → Offset` by 50% horizontally → the seam moves to the center → heal with content-aware fill or clone stamp → offset back to 0. Or regenerate with seed bump and `seamless horizontal wrap, no visible seam at left and right edges` repeated twice in the prompt.
 
+## Without Summer Engine
+
+In a session without Summer Engine tools (the assets profile; the `summer-assets` skill has the whole loop), do steps 1-4 and skip steps 5-7 (import, `WorldEnvironment`, scene check). Pass `out` with the person's folder so the image lands there (the `summer-assets` skill says how). Tell them it is a 2:1 equirectangular panorama, the shape most engines take for a sky.
+
 ## Fallback (no MCP)
 
 Print the call:
 
 ```
-summer_generate_image(
-  prompt="<sky> 360 degree panoramic equirectangular projection, seamless horizontal wrap, no visible seam, no foreground objects, sky only",
-  model="nano-banana-2",
-  style="realistic"
-)
+assets.generate_image({
+  prompt: "<sky> 360 degree panoramic equirectangular projection, seamless horizontal wrap, no visible seam, no foreground objects, sky only",
+  model: "nano-banana-2",
+  style: "realistic",
+  aspectRatio: "16:9"
+})
 ```
 
-The dashboard is the better surface for this skill: it exposes aspect ratio and a real negative prompt, which MCP does not. Tell the user to set 2:1 and a negative of `vertical seam, foreground, distorted, warped, characters, buildings`, then `summer_import_from_url` to `res://art/sky/<name>.png`, set `Repeat: Disabled`, and wire the WorldEnvironment.
+The dashboard is the better surface for this skill: it offers 2:1 and a real negative prompt, which the asset operations do not. Tell the user to set 2:1 and a negative of `vertical seam, foreground, distorted, warped, characters, buildings`, then `summer_import_from_url` to `res://art/sky/<name>.png`, set `Repeat: Disabled`, and wire the WorldEnvironment.
 
 If MCP is offline entirely: Polyhaven (`polyhaven.com/hdris`) has hundreds of free CC0 HDRIs ready to drop into `PanoramaSkyMaterial`, and often the better choice for realistic exteriors.
 
@@ -198,4 +204,24 @@ After the sky is wired:
 - `tileable-texture` — ground/floor counterpart.
 - `scene-composition` — WorldEnvironment placement and configuration.
 - `asset-strategy` — meta-router.
-- `../../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`.
+
+<!-- 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` |
+| `summer_assets_search` | `summer assets search` |
+| `summer_docs_read` | `summer docs read` |
+| `summer_add_node` | `summer engine add-node` |
+| `summer_import_from_url` | `summer engine import-from-url` |
+| `summer_inspect_node` | `summer engine inspect-node` |
+| `summer_play` | `summer engine play` |
+| `summer_save_scene` | `summer engine save-scene` |
+| `summer_set_prop` | `summer engine set-prop` |
+| `summer_set_resource_property` | `summer engine set-resource-property` |
+| `summer_write_file` | `summer engine write-file` |
+<!-- /shell-commands -->

package/library/skills/skybox-panorama/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/skybox-panorama
 kind: skill
 version: 1.0.3
-summary: Generate a 360-degree equirectangular sky panorama and wire it as a PanoramaSkyMaterial Sky resource on WorldEnvironment in a 3D scene.
+summary: "Generate a 360-degree sky panorama and wire it as a PanoramaSkyMaterial Sky resource on WorldEnvironment."
 use_when:
   - generating a 360-degree panoramic sky image for use as a Sky resource (PanoramaSkyMaterial) in a 3D scene
   - a 3D scene has a flat or default sky and needs a 360-degree backdrop matching the art direction