summer-engine 1.5.0 → 2.2.0

package/skills/2d-assets/concept-art/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: concept-art
+description: Use when the user is exploring art direction — wants 3-4 rough variants of a character, environment, or prop to pick a vibe before committing to a final asset. Generates a batch of evocative concept images, not finals. Trigger on "concept art", "art direction", "explore the look", "give me some variants", "what could this character look like", "mood board", "rough sketches".
+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
+paths: ["assets/**", "art/**", "concepts/**"]
+---
+
+# concept-art — Batch-of-Variants for Art Direction
+
+This skill produces **3-4 rough concept images** of the same subject under different stylistic interpretations. The goal is not the final asset — the goal is to give the user something visual to react to so they can lock a direction. Variants are deliberately divergent (different palette, mood, framing, era) so the user has real choices, not four near-identical takes.
+
+If the user wants ONE polished image (a dialogue portrait, a hero card), this is the wrong skill — route to `summer:2d-assets/character-portrait`. The `summer:asset-pipeline/asset-strategy` meta-router uses the disambiguation phrase **"Quick check — exploring the look (3-4 variants for art direction) or generating a final character portrait for dialogue UI?"** to send users to one of the two. If you arrived here without that question being asked, ask it before generating.
+
+## When to use
+
+- "I'm not sure what this character should look like — give me some options."
+- "Show me 3-4 directions for the witch."
+- "I want a mood board for the swamp level."
+- Early-project art direction, before the GameSoul.md visual style is locked.
+- The user describes a vibe ("dark fantasy", "Ghibli-esque", "Mobius") and wants to see it rendered.
+
+## When NOT to use
+
+- The user wants a single locked portrait for a dialogue UI → `summer:2d-assets/character-portrait`.
+- The user wants pixel art specifically → `summer:2d-assets/pixel-art`.
+- The user wants a UI icon or HUD element → `summer:2d-assets/ui-graphics`.
+- The user wants a tileable wall/floor texture → `summer:2d-assets/tileable-texture`.
+- The user wants an image-to-3D reference → `summer:asset-pipeline/asset-strategy` (the 3D pipeline has its own prompt suffix).
+
+## Steps
+
+### 1. Confirm exploration vs final
+
+Before generating, ask once:
+
+> Quick check — exploring the look (3-4 variants for art direction) or generating a final character portrait for dialogue UI?
+
+If "final" → hand off to `summer:2d-assets/character-portrait`. If "explore" → continue.
+
+### 2. Search for prior concepts
+
+```
+summer_search_assets(query="<subject> concept", filter={ kind: "image" })
+```
+
+If something already exists, ask if the user wants to riff on it (img2img via `referenceImageUrl`) or start fresh.
+
+### 3. Pick a variant axis
+
+Variants must differ on **one explicit axis**, not noise. Pick one:
+
+| Axis | Use when |
+|---|---|
+| Palette / mood | "Should this feel grim or hopeful?" |
+| Era / setting | "Medieval, sci-fi, modern, post-apoc?" |
+| Stylization | "Painterly, anime, photoreal, Mobius line-art?" |
+| Silhouette / proportions | Character design — slim/bulky/childlike/monstrous |
+| Time of day / lighting | Environment — dawn/noon/dusk/night |
+
+State the axis to the user before generating: "I'll vary on **stylization** — painterly, anime, line-art, photoreal. OK?"
+
+### 4. Generate the batch
+
+Issue 3-4 calls in parallel, one per variant. Use the same subject phrasing across all four; only the style-modifier changes.
+
+```
+summer_generate_image(
+  prompt="<subject>. <axis variant 1>. concept art, evocative, rough painterly, atmospheric lighting",
+  model="nano-banana-2",
+  style="none",
+  options={ image_size: "landscape_16_9" }
+)
+```
+
+`style: "none"` is intentional — concept art doesn't want the default "realistic" or "cartoon" preset overriding the prompt's stylistic direction.
+
+### 5. Present the batch
+
+After all 4 return, show the user the thumbnails (link `thumbnailUrl` for each) and ask:
+
+> Which direction lands? I can generate variants on the chosen one, or hand off to `character-portrait` for a final.
+
+Do NOT import any of these as `res://` assets yet. Concept art is reference, not shipped art. Only import once the user picks a winner — then either it goes to `character-portrait` for a polished version or directly to `summer_import_from_url` if they want to use it as-is as a reference.
+
+## Prompt patterns
+
+The structure: **subject + axis variant + "concept art" + lighting/atmosphere**. Keep prompts under 30 words.
+
+| Goal | Prompt that works | Why |
+|---|---|---|
+| Character — palette axis | `young witch with raven familiar. <warm autumn palette / cold blue moonlit palette / sickly green swamp palette / monochrome ash palette>. concept art, painterly, atmospheric` | Locked subject + four explicit palettes |
+| Character — silhouette axis | `goblin warrior. <slim wiry / hulking brute / childlike imp / multi-limbed mutant>. concept art, full body, rough painterly` | Forces real shape variation |
+| Environment — mood axis | `swamp village at dusk. <hopeful warm lanterns / oppressive fog / abandoned ruins / overgrown nature reclaim>. concept art, wide shot, atmospheric` | Mood drives composition |
+| Environment — stylization axis | `mountain temple. <Studio Ghibli soft painterly / Mobius clean line-art / dark Berserk ink / Hayao detailed wash>. concept art, wide establishing shot` | Names real reference styles the model recognizes |
+| Prop — era axis | `royal sword. <bronze age / medieval / ornate baroque / sci-fi energy>. concept art, three-quarter view, neutral background` | Era as the only varying dimension |
+| Creature — physiology axis | `forest spirit. <deer-like elegant / fungal grotesque / jellyfish floating / branch-and-moss elemental>. concept art, atmospheric, painterly` | Forces real morphological divergence |
+
+### Bad prompts (and why)
+
+| Bad | Failure mode |
+|---|---|
+| `cool fantasy character` | No subject, no axis. All 4 variants will look interchangeable. |
+| `make 4 different witches` | Model doesn't render "4 of"; you must call 4 times. |
+| `epic concept art masterpiece trending on artstation` | Adjective soup. Trending-on-artstation is a 2022 cliche; modern models render it as bland slop. |
+| `same character but different` | "Different" is undefined. Pick an axis and name it. |
+
+## Anti-patterns
+
+- **Generating 4 near-identical variants** because you didn't pick a real axis. The user can't choose between four images that all look like the same painting.
+- **Importing concept art as final assets.** These are exploration. The polished version comes from `character-portrait` after a direction is picked.
+- **Using `style: "realistic"` or `style: "cartoon"`** — the preset fights the prompt's stylistic direction. Use `style: "none"` for concept art.
+- **Skipping the disambiguation question.** If you don't ask, you'll get yelled at when you generate 4 portraits and the user wanted one polished bust.
+- **Generating before the GameSoul.md is written.** If `.summer/GameSoul.md` exists, read it first — its visual-style section narrows the axis.
+
+## Edge cases
+
+- **User says "just one" after you propose 4.** That's a `character-portrait` job. Hand off.
+- **User wants 8+ variants.** Generate 4 first; if the user wants more on the same axis, generate 4 more. Don't dump 8 at once — overload paralyzes choice.
+- **Subject is a fully described scene, not an asset.** You're producing key art, not asset reference. Use `image_size: "landscape_16_9"` and bias toward atmospheric.
+- **User wants the final to be 3D.** After they pick a direction, route to `summer:asset-pipeline/asset-strategy` — concept-art images are not 3D-ready references (they have backgrounds, scene context, dramatic lighting baked in). The 3D pipeline needs its own clean white-background reference.
+
+## Fallback (no MCP)
+
+Print the 4 prompts and the call for each:
+
+```
+summer_generate_image(prompt="<variant 1>", model="nano-banana-2", style="none", options={ image_size: "landscape_16_9" })
+summer_generate_image(prompt="<variant 2>", ...)
+...
+```
+
+Tell the user to run via the Summer dashboard, then come back and `summer_import_from_url` the winning variant.
+
+## Handoff
+
+Once the user picks a direction:
+
+- **Character / NPC final** → `summer:2d-assets/character-portrait` (use the picked variant as `referenceImageUrl`).
+- **3D model from this concept** → `summer:asset-pipeline/asset-strategy` (regenerate a 3D-ready reference; concept art is not 3D-ready as-is).
+- **Tileable texture from this mood** → `summer:2d-assets/tileable-texture`.
+- **Pixel-art version** → `summer:2d-assets/pixel-art`.
+- **Lock the visual direction** → write the choice into `.summer/GameSoul.md` under `## Visual style` so future asset skills inherit it.
+
+## See also
+
+- `summer:asset-pipeline/asset-strategy` — meta-router that delegates here vs other 2d-assets skills.
+- `summer:2d-assets/character-portrait` — the polished single-image counterpart.
+- `_shared/mcp-tools-reference.md` — `summer_generate_image` parameter schema.

package/skills/2d-assets/pixel-art/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: pixel-art
+description: Use when generating pixel-art assets — sprites, items, tiles, portraits in a pixel style at a specific resolution (32×32, 64×64, 128×128). Pixel-perfect grid, limited palette, retro feel. Trigger on "pixel art", "8-bit art", "16-bit sprite", "pixel sprite", "retro tileset", "pixel icon", "pixel portrait".
+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
+paths: ["assets/**", "art/pixel/**", "sprites/**"]
+---
+
+# pixel-art — Pixel-Perfect Sprites and Tiles
+
+This skill generates pixel-art assets — sprites, items, tiles, icons, portraits — at a target resolution (32×32, 64×64, 128×128, etc.). Pixel art has hard constraints (grid alignment, limited palette, no anti-aliased edges) that diffusion models violate by default. This skill encodes the prompt patterns and post-processing discipline that makes the output actually look like pixel art and not "blurry small image."
+
+**Backing tool:** `summer_generate_image` with `style: "pixel"` and an explicit pixel-art prompt. Pass `options.image_size: "square_hd"` and have the agent enforce pixel-perfect by setting the project's default texture filter to Nearest (and downscaling to the target resolution post-gen). Output is upscaled by the model — you generally request a small generation (or downscale post-gen) to get crisp pixels.
+
+## When to use
+
+- "Generate a 32×32 sword icon for the inventory."
+- "I need a pixel-art portrait of the merchant for the dialogue UI."
+- "Make a 64×64 enemy sprite — a slime monster."
+- "Generate a tileset for a grass / dirt / stone biome at 16×16 per tile."
+- The game has a pixel-art aesthetic and the user wants assets in-style.
+
+## When NOT to use
+
+- The user wants a high-resolution painterly portrait → `summer:2d-assets/character-portrait`.
+- The user wants animated frames (walk cycle, attack) → `summer:2d-assets/sprite-sheet` (pixel art is harder for sprite sheets — read that skill's caveats).
+- The user wants a tileable seamless texture (not pixel art) → `summer:2d-assets/tileable-texture`.
+- The game is 3D / non-pixel — verify the user actually wants pixel before generating.
+
+## Steps
+
+### 1. Lock the resolution and palette
+
+Ask the user (or read `.summer/GameSoul.md`):
+
+- **Resolution per asset:** 16×16, 32×32, 64×64, 128×128 are standard. Sprites usually 32 or 64; portraits 64 or 128; icons 16 or 32.
+- **Palette:** named retro palette (NES 56-color, Game Boy 4-color green, PICO-8 16-color, Sweetie-16) OR custom hex list OR "no palette restriction."
+- **Outline:** hard black outline, colored outline, or no outline?
+
+Write to `.summer/pixel-anchor.md` so the rest of the cast/tileset stays consistent:
+
+```
+## Pixel anchor
+
+base resolution: 32x32 per sprite
+palette: PICO-8 16-color
+outline: hard 1px dark outline (NOT pure black — use the palette's darkest color)
+shading: 3-tone (light, mid, shadow), no gradients, no AA
+```
+
+### 2. Search for existing assets
+
+```
+summer_search_assets(query="<subject> pixel", filter={ kind: "image" })
+```
+
+### 3. Build the prompt
+
+Pattern:
+
+```
+pixel art <subject>, <resolution>, <palette>, <outline rule>, <shading rule>, no anti-aliasing, no blur, sharp pixel edges, transparent background
+```
+
+The model can't actually generate at 32×32 — it generates at 1024×1024 with pixel-art *style*. You then downscale to the target resolution post-import for crisp pixels.
+
+### 4. Generate
+
+```
+summer_generate_image(
+  prompt="pixel art slime monster, 32x32 sprite, PICO-8 palette, hard 1px outline in palette's darkest color, 3-tone shading, no anti-aliasing, no blur, sharp pixel edges, transparent background, front-facing",
+  model="nano-banana-2",
+  style="pixel",
+  options={
+    image_size: "square_hd",
+    negative_prompt: "blurry, smooth gradients, anti-aliasing, photorealistic, 3D render, soft edges"
+  }
+)
+```
+
+`negative_prompt` is critical for pixel art — without it the model smuggles in soft edges and gradients.
+
+### 5. Downscale to target resolution
+
+The generated image is 1024×1024 pixel-style. To get true crisp pixels at 32×32:
+
+- Import to the engine, then in the import dock set `Filter: Nearest` (no smoothing).
+- For a true 32×32 atlas/icon, downscale in an external editor (Aseprite, GIMP "nearest neighbor") to 32×32 before importing. Aseprite's "Sprite > Sprite Size" with Nearest gives the cleanest result.
+- In Godot, set `Project Settings → Rendering → Textures → Default Texture Filter: Nearest` if the entire game is pixel-art. This kills bilinear smoothing project-wide.
+
+### 6. Import and wire
+
+```
+summer_import_from_url(url="<fileUrl>", path="res://sprites/slime.png")
+```
+
+For a `Sprite2D`:
+
+```
+summer_set_resource_property(
+  nodePath="/root/Game/Slime/Sprite2D",
+  resourceProperty="texture",
+  value="res://sprites/slime.png"
+)
+```
+
+Confirm `Filter: Nearest` is set in the import dock OR project-wide.
+
+## Prompt patterns
+
+| Goal | Prompt that works | Why |
+|---|---|---|
+| Item icon (32×32) | `pixel art iron sword icon, 32x32, NES palette, hard outline, 3-tone shading, no AA, sharp edges, transparent background, three-quarter view` | Three-quarter view reads better than pure side at 32px |
+| Character sprite (64×64) | `pixel art knight character sprite, 64x64, PICO-8 palette, hard 1px outline, 3-tone shading, front-facing idle pose, no AA, sharp edges, transparent background` | Specifying "idle pose" prevents action poses that don't tile into a sheet |
+| Pixel portrait (128×128) | `pixel art portrait of a young witch, 128x128, custom muted fantasy palette, hard outline, 4-tone shading, bust framing, looking forward, no AA, no blur, transparent background` | Higher resolution allows 4-tone shading; 32px is too small for that |
+| Tileset (16×16/tile) | `pixel art top-down tileset, grass-to-dirt transition, 16x16 per tile, 3x3 grid layout, NES palette, hard outline between tiles, 3-tone shading, no AA, sharp edges` | Tilesets render best in a labeled grid layout |
+| Background object (64×64) | `pixel art mossy boulder, 64x64, fantasy palette, hard outline, 3-tone shading, no AA, transparent background, three-quarter view` | Background props benefit from three-quarter for depth |
+| GB-style asset (Game Boy) | `pixel art skeleton enemy, 32x32, Game Boy 4-color green palette (#0f380f, #306230, #8bac0f, #9bbc0f), hard 1px outline, 2-tone shading, no AA` | Naming the 4 hex codes locks the palette |
+
+### Bad prompts (and why)
+
+| Bad | Failure mode |
+|---|---|
+| `8-bit sword` | "8-bit" is interpreted loosely. Returns a smooth render of a sword with vague pixel feel. Specify resolution + palette + "no AA" explicitly. |
+| `pixel art knight, photorealistic` | Conflicting directives. Model averages and gives you neither. |
+| `pixel art at 32x32` (no negative_prompt) | Model adds soft edges and gradient shading. Always add negative prompt for AA / blur / gradients. |
+| `pixel sprite walk cycle` | Walk cycles need consistent frames — single-prompt sprite sheets fail. Route to `summer:2d-assets/sprite-sheet`. |
+| `cute pixel art` | "Cute" without subject is undefined. Specify what. |
+
+## Anti-patterns
+
+- **Skipping the downscale.** The model returns a 1024×1024 pixel-style image. If you import that as a 1024 texture, the "pixels" are actually 32-pixel blocks of soft color. Downscale to true target resolution OR set `Filter: Nearest` so the up-rendering doesn't smooth.
+- **No `Filter: Nearest`.** Default Godot texture filtering is bilinear. Pixel art bilinearly filtered looks like garbage. Set it on import or project-wide.
+- **No negative prompt.** Without `blurry, anti-aliasing, gradients, soft edges` in the negative, ~50% of generations are off-style.
+- **Inconsistent palette across the cast.** Pick a named palette (PICO-8, NES, custom hex list) and re-use across every asset in the project. Different palettes = the project doesn't read as one game.
+- **Generating walk-cycle frames as one image.** Sprite sheets via single-prompt are unreliable. Route to `summer:2d-assets/sprite-sheet`.
+
+## Edge cases
+
+- **User wants animated pixel sprites.** Generate base sprite here, then per-frame variants via img2img with the base as `referenceImageUrl`. For more than 2-3 frames, route to `summer:2d-assets/sprite-sheet` (and read its caveats).
+- **User wants the entire game in pixel art.** Set `Project Settings → Rendering → Textures → Default Texture Filter: Nearest` once. Saves you from re-setting it on every import.
+- **User wants a high-res "pixel art" portrait that's not actually pixelated** (faux-pixel-aesthetic at full resolution). That's `summer:2d-assets/character-portrait` with a "pixel art aesthetic" prompt — not this skill.
+- **User specifies a palette like "Sweetie-16" or "Endesga-32" and the model ignores it.** Name the hex codes explicitly. Palette names alone are unreliable below the top 5-10 famous ones.
+- **Tilesets need to tile cleanly.** Pixel-art tile-edge cleanliness from raw generation is poor. Generate the tile grid, then manually fix edge seams in Aseprite. The AI gets you 80% there.
+
+## Fallback (no MCP)
+
+Print the call:
+
+```
+summer_generate_image(
+  prompt="<pixel art prompt with full anchor>",
+  model="nano-banana-2",
+  style="pixel",
+  options={ image_size: "square_hd", negative_prompt: "blurry, smooth gradients, anti-aliasing" }
+)
+```
+
+Tell the user to run via the Summer dashboard, downscale in Aseprite/GIMP to true target resolution with nearest-neighbor, then `summer_import_from_url` (or drop into `res://sprites/`) and set `Filter: Nearest`.
+
+If MCP is offline entirely: open Aseprite or Piskel and hand-author the asset. For pixel art at small resolutions, hand-authoring is often faster than fixing a generation.
+
+## Handoff
+
+After the asset is wired:
+
+- **More assets in the same style** → re-invoke this skill, re-use the pixel anchor.
+- **Animation frames for the sprite** → `summer:2d-assets/sprite-sheet` with the base sprite as anchor.
+- **Pixel UI** → re-invoke with UI subjects (icons, button frames) at appropriate resolution.
+- **Tilemap setup** → `summer:scene-composition` for `TileMap` / `TileMapLayer` wiring.
+
+## See also
+
+- `summer:2d-assets/sprite-sheet` — animated pixel frames.
+- `summer:2d-assets/character-portrait` — high-res counterpart.
+- `summer:asset-pipeline/asset-strategy` — meta-router.
+- `_shared/mcp-tools-reference.md` — `summer_generate_image` schema.

package/skills/2d-assets/skybox-panorama/SKILL.md

@@ -0,0 +1,207 @@
+---
+name: skybox-panorama
+description: Use when generating a 360° panoramic sky image for use as a Sky resource (PanoramaSkyMaterial) in a 3D scene. Equirectangular projection, 2:1 aspect. Wires into WorldEnvironment.sky. Trigger on "skybox", "sky panorama", "360 background", "environment sky", "HDRI sky", "panoramic background", "panorama sky".
+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_add_node summer_set_prop summer_inspect_node
+paths: ["assets/**", "art/sky/**", "environments/**"]
+---
+
+# skybox-panorama — 360° Sky for WorldEnvironment
+
+This skill generates a single equirectangular panoramic image (2:1 aspect, e.g. 2048×1024 or 4096×2048) suitable for Godot's `PanoramaSkyMaterial`. Wires it into a `Sky` resource on a `WorldEnvironment` node so the sky is visible from every camera angle in your 3D scene.
+
+The single biggest failure mode is **non-equirectangular output**. Diffusion models default to flat 2D scenes; if you don't explicitly demand "equirectangular projection," the result looks fine in a thumbnail but distorts brutally when wrapped onto a sphere — horizon bows, zenith pinches, the sun stretches into a smear. This skill encodes the prompt suffix and the import discipline that produces a usable sky on the first or second try.
+
+## When to use
+
+- "Generate a fantasy sky for the level."
+- "I need a sci-fi nebula skybox."
+- "Make a sunset panorama for the desert scene."
+- "Stormy night sky for the haunted level."
+- The 3D scene needs a visible sky (not just a flat color background).
+
+## When NOT to use
+
+- The user wants a 2D parallax background → that's a separate `Sprite2D` job, not a panorama.
+- The user wants a HDRI for environment lighting (not just visual sky) → AI panoramas are LDR by default. For real IBL/HDR, use Polyhaven HDRIs (free CC0). Mention this to the user if lighting realism matters.
+- The user wants a 3D-modeled sky-dome with geometry (clouds-as-meshes) → out of scope; use a `Sphere` mesh + custom shader.
+- The scene is 2D → no sky needed.
+
+## Steps
+
+### 1. Search for an existing sky
+
+```
+summer_search_assets(query="<vibe> sky panorama", filter={ kind: "image" })
+```
+
+Polyhaven (`polyhaven.com/hdris`) hosts hundreds of free CC0 HDRIs that beat AI generation for realism and provide IBL data. For realistic exterior scenes, prefer Polyhaven; for stylized / fantasy / sci-fi, AI generation wins.
+
+### 2. Build the prompt — sky description + equirectangular suffix
+
+Pattern:
+
+```
+<sky description>, 360 degree panoramic equirectangular projection, seamless horizontal wrap, no visible seam at left and right edges, distortion-correct for sphere mapping, no foreground objects, no ground horizon line, sky and clouds and atmosphere only
+```
+
+Load-bearing phrases:
+
+- **`360 degree panoramic equirectangular projection`** — primes the model for the right format.
+- **`seamless horizontal wrap, no visible seam at left and right edges`** — the left and right edges of the image meet when wrapped. If they don't match, you see a vertical seam in the sky.
+- **`no foreground objects, no ground horizon line`** — skies show only sky. If you include a horizon, it warps weirdly when sphere-mapped and kills the illusion that the sky is at infinite distance.
+- **`distortion-correct for sphere mapping`** — reminds the model that the top/bottom of the image map to the zenith/nadir.
+
+### 3. Generate at 2:1 aspect
+
+```
+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, seamless horizontal wrap, no visible seam, no foreground objects, sky only",
+  model="nano-banana-2",
+  style="realistic",
+  options={
+    aspectRatio: "2:1",
+    image_size: "landscape_16_9",
+    negative_prompt: "vertical seam, ground objects, horizon-level details, distorted, warped, characters, buildings"
+  }
+)
+```
+
+`aspectRatio: "2:1"` is critical. Equirectangular MUST be 2:1 (width = 2× height). If the model returns 16:9 or 4:3, the wrap will be wrong.
+
+### 4. Verify the seam and projection
+
+Before wiring, inspect:
+
+- **Left edge ↔ right edge:** mentally place them side-by-side. They should match continuously. If there's a cloud cut in half on the left and a different cloud on the right, regenerate with stronger emphasis on `seamless horizontal wrap`.
+- **Top stretching:** the top 10% of the image stretches enormously when mapped to the zenith. If there are tight features (a sun, a cloud edge) high up, they'll smear. Generations with diffuse, soft top regions wrap better than crisp ones.
+- **Bottom:** same applies to the nadir. Most skies don't show much bottom anyway since the camera sits below the horizon — but avoid generating tight features at the very bottom.
+
+If the image fails seam check, regenerate. Some models support `seed` for variation while keeping prompt — bump the seed.
+
+### 5. Import to project
+
+```
+summer_import_from_url(url="<fileUrl>", path="res://art/sky/fantasy_sunset.png")
+```
+
+In the import dock:
+
+- `Repeat: Disabled` (panoramas don't tile — they wrap once via the material).
+- `Filter: Linear with mipmaps` (smoother as the camera turns).
+- `Mipmaps: Enabled`.
+- `Compress: VRAM Compressed` for ship.
+
+### 6. Wire into WorldEnvironment (3 lines)
+
+```
+summer_add_node(parentPath="/root/Game", type="WorldEnvironment", name="WorldEnvironment")
+
+summer_set_resource_property(
+  nodePath="/root/Game/WorldEnvironment",
+  resourceProperty="environment:background_mode",
+  value=2  # BG_SKY
+)
+
+summer_set_resource_property(
+  nodePath="/root/Game/WorldEnvironment",
+  resourceProperty="environment:sky:sky_material",
+  value="<new PanoramaSkyMaterial with panorama: res://art/sky/fantasy_sunset.png>"
+)
+```
+
+Then, if the user wants the sky to also light the scene (image-based lighting):
+
+```
+summer_set_resource_property(
+  nodePath="/root/Game/WorldEnvironment",
+  resourceProperty="environment:ambient_light_source",
+  value=3  # AMBIENT_SOURCE_SKY
+)
+```
+
+Note: AI-generated panoramas are LDR (8-bit per channel). For physically-correct IBL with bright suns, the lighting is muted compared to true HDRI. Mention this to the user if they expect strong IBL.
+
+### 7. Verify in scene
+
+```
+summer_inspect_node(path="/root/Game/WorldEnvironment")
+```
+
+Then `summer_play` and look around. Sun in the right place? Seam invisible? Top/bottom okay?
+
+## Prompt patterns
+
+| Goal | Prompt that works | Why |
+|---|---|---|
+| Fantasy sunset | `dramatic fantasy sky at golden hour, large purple and orange clouds, soft god-rays, distant mountain silhouettes at very bottom only, 360 degree panoramic equirectangular projection, seamless horizontal wrap, no visible seam, no foreground, sky only` | Soft top, distant horizon = clean wrap |
+| Sci-fi space nebula | `vast space nebula, deep blue and magenta gas clouds, scattered bright stars, distant galaxy disc, 360 degree panoramic equirectangular projection, seamless horizontal wrap, no visible seam, no foreground objects, no ground` | Space skies wrap easily; no horizon issues |
+| Stormy night | `dark stormy night sky, heavy rolling clouds, distant lightning flashes, full moon partly obscured, 360 degree panoramic equirectangular, seamless wrap, no foreground` | Diffuse cloud structure tolerates wrapping well |
+| Clear blue day | `bright clear blue sky with scattered cumulus clouds, midday sun upper left, 360 degree panoramic equirectangular projection, seamless horizontal wrap, no visible seam, no ground` | Tight sun feature warps; place sun off-center |
+| Alien planet sky | `alien planet sky, two suns one large red one small white, swirling green-purple atmosphere, distant ringed planet at horizon, 360 panoramic equirectangular, seamless wrap, no foreground` | Multi-sun setups wrap if features stay diffuse |
+| Underwater (caustic dome) | `underwater scene seen from below, sun rays piercing water surface, deep blue gradient downward to black, 360 panoramic equirectangular, seamless wrap` | Treat ocean surface as the "sky"; works for underwater levels |
+| Stylized painterly sky | `Studio Ghibli painterly sky, soft cumulus clouds at sunset, warm pastel palette, 360 panoramic equirectangular, seamless wrap, no foreground` (style: "none") | Style preset would fight painterly |
+
+### Bad prompts (and why)
+
+| Bad | Failure mode |
+|---|---|
+| `beautiful sky` | No equirectangular suffix. Returns flat 16:9 photograph. Wrap looks broken. |
+| `sky with mountains and trees and a castle` | Foreground objects. Horizon-level details warp catastrophically when sphere-mapped. |
+| `360 sky` (without 2:1 aspect) | Aspect mismatch. Wrap is misaligned. |
+| `panoramic sky in 4k` | "4k" implies 3840×2160 (16:9), not 2:1. Specify aspect. |
+| `sky with the sun in the center top` | Sun at zenith stretches into a smear. Place sun off-axis. |
+
+## 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.
+- **Not specifying 2:1 aspect.** A 16:9 panorama wrapped equirectangular has obvious horizontal compression. Always `aspectRatio: "2:1"`.
+- **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.
+- **Visible vertical seam on the wrap.** If left/right edges don't match, regenerate with seed bump or fix the seam in Photoshop/GIMP via the offset trick (offset by 50% horizontally → heal the new visible seam → offset back).
+
+## Edge cases
+
+- **Animated sky (clouds drift).** AI gives one frame. Animate via shader (UV scroll on the panorama texture) or layer two panoramas with `ProceduralSkyMaterial` for the base + a transparent cloud layer.
+- **Day/night cycle.** Generate two panoramas (day + night). Cross-fade the `sky_material` via shader blend or by swapping `panorama` over a tween. Two LDR panoramas + a blend = serviceable cycle.
+- **First-person VR.** AI panoramas at 2048×1024 are too low-res for VR (visible pixels). Generate at 4096×2048 if the model supports it; otherwise use Polyhaven HDRIs at 8K.
+- **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.
+
+## 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",
+  options={ aspectRatio: "2:1", negative_prompt: "vertical seam, foreground, distorted, warped, characters, buildings" }
+)
+```
+
+User runs via Summer dashboard, then `summer_import_from_url` to `res://art/sky/<name>.png`, sets `Repeat: Disabled`, and wires the WorldEnvironment manually.
+
+If MCP is offline entirely: Polyhaven (`polyhaven.com/hdris`) has hundreds of free CC0 HDRIs ready to drop into `PanoramaSkyMaterial`. Often a better choice than AI for realistic exteriors anyway.
+
+## Handoff
+
+After the sky is wired:
+
+- **Add atmospheric fog matching the sky's mood** → `summer:scene-composition` (fog is on the same Environment resource).
+- **Add a directional `DirectionalLight3D` matching the sun position in the panorama** → `summer:3d-lighting` for sun + shadows.
+- **Day/night cycle** → re-invoke this skill for the night sky, then write a small tween between the two `panorama` properties.
+- **Tileable ground texture for the level floor** → `summer:2d-assets/tileable-texture`.
+
+## See also
+
+- `summer:3d-lighting` — sun, ambient, fog wired alongside the sky.
+- `summer:2d-assets/tileable-texture` — ground/floor counterpart.
+- `summer:scene-composition` — WorldEnvironment placement and configuration.
+- `summer:asset-pipeline/asset-strategy` — meta-router.
+- `_shared/mcp-tools-reference.md` — `summer_generate_image` schema.