summer-engine 2.3.0 → 2.6.0

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

@@ -1,4 +1,6 @@
 import { z } from "zod";
+import { ASSET_POLICIES, GAME_TASK_MODES, GAME_TASK_TARGETS, VERIFICATION_LEVELS, buildGameTaskPlan, } from "../../lib/game-task-plan.js";
+import { getProjectMemorySummary } from "../../lib/project-memory.js";
 import { withEngine } from "./with-engine.js";
 function asRecord(value) {
     return value && typeof value === "object" && !Array.isArray(value)
@@ -35,9 +37,10 @@ function getProjectSetting(projectState, keys) {
     }
     return null;
 }
-function getProjectPath(projectState) {
+function getProjectPath(projectState, health) {
     const root = asRecord(projectState);
     const data = getProjectData(projectState);
+    const healthRoot = asRecord(health);
     return (pickString(data, [
         "projectPath",
         "project_path",
@@ -47,13 +50,16 @@ function getProjectPath(projectState) {
         "root_path",
     ]) ??
         pickString(root, ["projectPath", "project_path", "projectRoot", "project_root"]) ??
+        pickString(healthRoot, ["project_path", "projectPath", "projectRoot", "project_root"]) ??
         null);
 }
-function getProjectName(projectState) {
+function getProjectName(projectState, health) {
     const root = asRecord(projectState);
     const data = getProjectData(projectState);
+    const healthRoot = asRecord(health);
     return (pickString(data, ["projectName", "project_name", "name"]) ??
         pickString(root, ["projectName", "project_name", "name"]) ??
+        pickString(healthRoot, ["project_name", "projectName", "name"]) ??
         getProjectSetting(projectState, ["application/config/name", "config/name"]));
 }
 function getMainScene(projectState) {
@@ -66,20 +72,59 @@ function getMainScene(projectState) {
             "run/main_scene",
         ]));
 }
-function getCurrentScene(projectState, sceneState) {
+function getCurrentScene(projectState, sceneState, health) {
     const sceneRoot = asRecord(sceneState);
     const sceneData = asRecord(sceneRoot?.data);
     const sceneProvenance = asRecord(sceneRoot?.provenance);
     const projectRoot = asRecord(projectState);
     const projectData = getProjectData(projectState);
     const projectProvenance = asRecord(projectRoot?.provenance);
+    const healthRoot = asRecord(health);
     return (pickString(sceneProvenance, ["scenePath", "scene_path"]) ??
         pickString(sceneData, ["scenePath", "scene_path", "currentScene", "current_scene"]) ??
         pickString(projectData, ["currentScene", "current_scene", "scenePath", "scene_path"]) ??
         pickString(projectProvenance, ["scenePath", "scene_path"]) ??
+        pickString(healthRoot, ["scene", "scenePath", "scene_path"]) ??
         null);
 }
 export function registerProjectTools(server) {
+    server.tool("summer_start_game_task", `Start here for any substantial AI game-building task.
+
+Takes the user's goal and returns the recommended Summer workflow: skill routes,
+MCP tool groups, host-file boundaries, asset policy, user confirmation gates,
+and verification steps. This is the router before deep skills and before
+mutating the project.`, {
+        goal: z.string().describe("The user's game-building goal or task."),
+        mode: z
+            .enum(GAME_TASK_MODES)
+            .default("auto")
+            .describe("Optional task mode override."),
+        target: z
+            .enum(GAME_TASK_TARGETS)
+            .default("auto")
+            .describe("Optional content/system target override."),
+        assetPolicy: z
+            .enum(ASSET_POLICIES)
+            .default("ask-before-paid-generation")
+            .describe("How aggressively to use paid asset generation."),
+        verification: z
+            .enum(VERIFICATION_LEVELS)
+            .default("full")
+            .describe("How much engine verification the agent should plan for."),
+    }, async ({ goal, mode, target, assetPolicy, verification }) => ({
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(buildGameTaskPlan({
+                    goal,
+                    mode,
+                    target,
+                    assetPolicy,
+                    verification,
+                }), null, 2),
+            },
+        ],
+    }));
     server.tool("summer_get_agent_playbook", `AI-first operating guide for Summer Engine MCP.
 
 Call this at the start of a fresh chat before touching scenes.
@@ -89,26 +134,33 @@ It returns the safe workflow, anti-patterns, and recovery steps.`, {}, async ()
                 type: "text",
                 text: JSON.stringify({
                     startupChecklist: [
-                        "Decide first: file edit or engine operation.",
-                        "Write .gd/.cs/.json/docs/simple config with host file-edit tools directly.",
-                        "Use Summer MCP for live scene state, inspector/node edits, imports, play/stop, diagnostics, screenshots/verification.",
-                        "Call summer_get_project_context first.",
-                        "If no scene is open, call summer_open_main_scene.",
-                        "Call summer_get_scene_tree before structural edits.",
-                        "Call summer_save_scene after edits.",
+                        "Understand the request and outline a brief plan before reaching for tools.",
+                        "Default medium is host file tools: write/edit .gd/.cs/.tscn/.tres/.json/docs/config directly as text.",
+                        "Use Summer MCP only when you need the LIVE engine: play/stop, diagnostics, screenshots/verification, navmesh or light bake, runtime inspect, or asset import.",
+                        "Call summer_get_project_context first so you do not guess scene paths or the project language.",
+                        "Use projectMemory from summer_get_project_context to decide which .summer Markdown files to read before creative/audio/dialogue/level/character work.",
+                        "After writing code, PLAY the scene you just made and read summer_get_diagnostics; iterate until it launches clean instead of waiting for the user to navigate to it.",
                     ],
                     safeDefaults: [
-                        "Never guess scene filenames (main.tscn/Main.tscn).",
-                        "Do not route ordinary script, JSON, docs, or simple config edits through MCP when direct file tools are available.",
-                        "Never remove multiple top-level nodes unless user explicitly requests destructive edits.",
-                        "Use MCP for scene-tree mutations and inspector-visible values instead of hand-editing live scene state.",
+                        "Never guess scene filenames (main.tscn/Main.tscn) -- get them from summer_get_project_context.",
+                        "Edit files (including .tscn/.tres) with host file tools by default. Reach for MCP scene-ops only for live-engine needs (bake, play, runtime inspect) or when you want the editor to manage node ids / instancing.",
+                        "If you hand-edit a .tscn that is OPEN in the editor, reload it there afterward -- the editor's open tab can overwrite your file (clobber).",
+                        "Write GDScript by default; use C# only if the project already uses it.",
+                        "Never remove multiple top-level nodes unless the user explicitly requests destructive edits.",
+                        "Never change priority: locked .summer memory, voice IDs, canon, or provider bindings without explicit user confirmation.",
+                    ],
+                    buildFlow: [
+                        "1. Understand what the user wants (one pass, no tool spelunking first).",
+                        "2. Outline the plan fast and briefly; proceed once it is clearly right.",
+                        "3. Execute in pure code -- edit .gd/.tscn/.tres as text (GDScript by default, C# only if the project already uses it).",
+                        "4. Play the scene/game (start with the scene you just made), read console + script/debugger errors via summer_get_diagnostics, fix, and repeat until it launches clean.",
                     ],
-                    preferredFlow: [
+                    liveEngineFlow: [
+                        "Use this flow ONLY when you genuinely need live engine state (navmesh/light bake, instancing into an already-open scene, runtime inspect):",
                         "summer_get_project_context",
                         "summer_open_main_scene (if needed)",
                         "summer_get_scene_tree",
-                        "edit via summer_add_node / summer_set_prop / summer_set_resource_property",
-                        "write scripts/data/docs/simple config directly with host file-edit tools",
+                        "summer_add_node / summer_set_prop / summer_set_resource_property",
                         "summer_save_scene",
                         "summer_get_diagnostics",
                     ],
@@ -116,6 +168,7 @@ It returns the safe workflow, anti-patterns, and recovery steps.`, {}, async ()
                         "If you see 'no scene open': run summer_open_main_scene.",
                         "If open_scene fails: re-check mainScene from summer_get_project_context.",
                         "If save fails: verify scene is open and game is not running.",
+                        "If a .tscn you wrote keeps reverting: the editor has that scene open -- reload or close the tab, then write again.",
                     ],
                 }, null, 2),
             },
@@ -126,6 +179,7 @@ It returns the safe workflow, anti-patterns, and recovery steps.`, {}, async ()
 - project name and project path when exposed by project state
 - current scene path (if available)
 - main scene path from project settings
+- lightweight .summer project memory summary when project path is available
 
 Use this first in every fresh chat to avoid guessing scene filenames or editing the wrong scene.`, {}, async () => withEngine(async (client) => {
         const [health, projectState, sceneState] = await Promise.all([
@@ -136,10 +190,10 @@ Use this first in every fresh chat to avoid guessing scene filenames or editing
                 error: err instanceof Error ? err.message : String(err),
             })),
         ]);
-        const projectPath = getProjectPath(projectState);
-        const projectName = getProjectName(projectState);
+        const projectPath = getProjectPath(projectState, health);
+        const projectName = getProjectName(projectState, health);
         const mainScene = getMainScene(projectState);
-        const currentScene = getCurrentScene(projectState, sceneState);
+        const currentScene = getCurrentScene(projectState, sceneState, health);
         return {
             health,
             project: projectState,
@@ -148,10 +202,11 @@ Use this first in every fresh chat to avoid guessing scene filenames or editing
             projectPath,
             currentScene,
             mainScene,
+            projectMemory: getProjectMemorySummary(projectPath),
             guidance: mainScene
                 ? "Use `summer_open_scene` with `mainScene` if no scene is open."
                 : "Main scene not found in project state. Open a known scene path explicitly.",
-            fileEditingGuidance: "Write .gd/.cs/.json/docs/simple config directly with host file tools. Use MCP for live scene state, inspector/node edits, imports, play/stop, diagnostics, and visual verification.",
+            fileEditingGuidance: "Edit files (including .gd/.cs/.tscn/.tres/.json/docs) with host file tools by default. Use MCP only for live engine state: play/stop, diagnostics, screenshots/verification, navmesh or light bake, runtime inspect, and asset import. If you edit a .tscn that is open in the editor, reload it there afterward so the editor's tab does not overwrite your changes.",
         };
     }));
     server.tool("summer_open_main_scene", `Open the project's configured main scene from project settings.

package/dist/mcp/tools/with-engine.d.ts

@@ -6,5 +6,19 @@ type ToolResult = {
     }[];
     isError?: boolean;
 };
+/**
+ * Decide whether an engine result envelope represents a FAILURE, and if so
+ * return a model-visible message. Returns null only for genuine success.
+ *
+ * Guards the two web bug classes (publicsummerengine cf17134f + contract.ts
+ * `isFailureSignal`):
+ *   - a failure `terminalState` (anything other than applied/no_op) is a failure
+ *     even when results[] is absent — the cf17134f "no-results envelope looked
+ *     applied" masking. The poll loop surfaces timed_out/etc. here.
+ *   - an explicit ok:false / status:"error" / failed op inside results[].
+ *
+ * Exported for unit tests.
+ */
+export declare function extractOpError(result: unknown): string | null;
 export declare function withEngine<T>(fn: (client: Awaited<ReturnType<typeof getClient>>) => Promise<T>): Promise<ToolResult>;
 export {};

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

@@ -1,15 +1,60 @@
 import { getClient, resetClient } from "../server.js";
 import { recordMcpSession } from "../../lib/telemetry.js";
-function extractOpError(result) {
+// 0.5.34 Block E contract (publicsummerengine src/lib/tools/contract.ts §0.1).
+// The async lifecycle (async-op-lifecycle.ts pollOpToTerminal) merges
+// terminalState/errorClass onto the apply dict it returns. ONLY these two are
+// "applied something / applied nothing-on-purpose" — every other terminal state
+// means the op did NOT land and must be surfaced as a failure, not masked.
+const SUCCESS_TERMINAL_STATES = new Set(["applied", "no_op"]);
+// Human-readable fallback when the engine reports a failure terminalState but no
+// `error` string (queue-full / lease-reject / identity-mismatch / no-progress
+// timeout frequently arrive with terminalState set and results[] absent).
+const TERMINAL_STATE_MESSAGES = {
+    timed_out: "Engine operation timed out (terminalState: timed_out). Nothing was applied.",
+    not_connected: "Summer Engine is not connected (terminalState: not_connected). Nothing was applied.",
+    identity_mismatch: "Operation rejected — wrong project/instance (terminalState: identity_mismatch). Nothing was mutated.",
+    content_mismatch: "Operation rejected — content changed since last read (terminalState: content_mismatch). Nothing was applied.",
+    denied: "Operation denied (terminalState: denied). Nothing was applied.",
+    canceled: "Operation canceled (terminalState: canceled). Nothing was applied.",
+};
+/**
+ * Decide whether an engine result envelope represents a FAILURE, and if so
+ * return a model-visible message. Returns null only for genuine success.
+ *
+ * Guards the two web bug classes (publicsummerengine cf17134f + contract.ts
+ * `isFailureSignal`):
+ *   - a failure `terminalState` (anything other than applied/no_op) is a failure
+ *     even when results[] is absent — the cf17134f "no-results envelope looked
+ *     applied" masking. The poll loop surfaces timed_out/etc. here.
+ *   - an explicit ok:false / status:"error" / failed op inside results[].
+ *
+ * Exported for unit tests.
+ */
+export function extractOpError(result) {
     if (!result || typeof result !== "object")
         return null;
     const op = result;
-    if (op.ok === false && op.error)
-        return op.error;
-    if (op.status === "error" && op.error)
-        return op.error;
-    const firstFailed = op.results?.find((r) => r.ok === false && r.error);
-    return firstFailed?.error ?? null;
+    // Failure terminalState takes precedence — it is set by the async lifecycle
+    // exactly when the op did not land (timeout, backpressure, lease/identity
+    // rejection, cancellation), often with NO results[] to inspect.
+    const ts = op.terminalState;
+    if (typeof ts === "string" && ts.length > 0 && !SUCCESS_TERMINAL_STATES.has(ts)) {
+        if (typeof op.error === "string" && op.error.length > 0)
+            return op.error;
+        return TERMINAL_STATE_MESSAGES[ts] ?? `Engine operation failed (terminalState: ${ts}).`;
+    }
+    // An explicit ok:false / status:"error" is a failure even when the engine
+    // omitted an error string — surface it rather than mask it (matches the web
+    // contract `isFailureSignal`).
+    if (op.ok === false)
+        return op.error || "Engine operation failed (ok: false).";
+    if (op.status === "error")
+        return op.error || "Engine operation failed (status: error).";
+    const firstFailed = op.results?.find((r) => r.ok === false);
+    if (firstFailed) {
+        return firstFailed.error || `Engine op failed${firstFailed.op ? ` (${firstFailed.op})` : ""}.`;
+    }
+    return null;
 }
 function buildActionHint(message) {
     const normalized = message.toLowerCase();

package/gemini-extension.json

@@ -1,7 +1,7 @@
 {
   "name": "summer",
-  "version": "2.0.1",
-  "description": "Superpowers for AI game dev. MCP bridge to the local Summer Engine plus a context primer that teaches Gemini the 24 Summer skills. Use with the npm CLI for skill files on disk.",
+  "version": "2.5.1",
+  "description": "Agent tooling for Summer Engine: MCP bridge, context primer, and game-dev skills. Use with the npm CLI for skill files on disk.",
   "contextFileName": "GEMINI.md",
   "mcpServers": {
     "summer-engine": {
@@ -13,7 +13,7 @@
   "settings": [
     {
       "name": "enable_pre_commit_doctor",
-      "description": "Block git commits on summer doctor FAIL (off by default)",
+      "description": "Block git commits when summer doctor needs attention (off by default)",
       "envVar": "SUMMER_PRE_COMMIT_DOCTOR",
       "sensitive": false
     }

package/package.json

@@ -1,31 +1,43 @@
 {
   "name": "summer-engine",
-  "version": "2.3.0",
-  "description": "Summer — superpowers for AI game dev. CLI, skills, and MCP tools for Summer Engine.",
+  "version": "2.6.0",
+  "description": "Summer CLI and MCP server for Summer Engine, the AI game engine. Install the engine, connect Claude Code, Cursor, Codex, Gemini, and other agents, and build real games. Skills, hooks, and plugins included.",
   "keywords": [
+    "summer-engine",
+    "summer-cli",
+    "summer-mcp",
+    "summer-agent",
+    "summer-engine-agent",
     "game-engine",
+    "ai-game-engine",
     "godot",
-    "ai",
+    "godot-ai",
     "mcp",
+    "mcp-server",
+    "claude-code",
+    "cursor",
+    "codex",
     "gamedev",
+    "game-development",
     "3d",
-    "summer-engine"
+    "ai"
   ],
   "homepage": "https://summerengine.com",
   "repository": {
     "type": "git",
-    "url": "https://github.com/SummerEngine/summer"
+    "url": "git+https://github.com/SummerEngine/summer-engine-agent.git"
   },
   "license": "MIT",
   "author": "Summer Engine <founders@summerengine.com>",
   "type": "module",
   "main": ".opencode/plugins/summer.js",
   "bin": {
-    "summer": "./dist/bin/summer.js"
+    "summer": "dist/bin/summer.js"
   },
   "files": [
     "dist/",
     "skills/",
+    "commands/",
     "hooks/",
     "assets/",
     "_persona/",
@@ -44,7 +56,8 @@
     "CLAUDE.md"
   ],
   "scripts": {
-    "build": "tsc",
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "npm run clean && tsc",
     "dev": "tsc --watch",
     "summer": "node dist/bin/summer.js",
     "test": "vitest run",

package/skills/2d-assets/character-portrait/SKILL.md

@@ -193,4 +193,4 @@ After the portrait is wired:
 - `summer:2d-assets/concept-art` — explore the look first if not yet locked.
 - `summer:asset-pipeline/asset-strategy` — meta-router and the 3D pipeline.
 - `summer:scene-composition` — wiring the portrait into a dialogue UI scene.
-- `_shared/mcp-tools-reference.md` — `summer_generate_image` parameter schema.
+- `references/mcp-tools-reference.md` — `summer_generate_image` parameter schema.

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

@@ -149,4 +149,4 @@ Once the user picks a direction:
 
 - `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.
+- `references/mcp-tools-reference.md` — `summer_generate_image` parameter schema.

package/skills/2d-assets/create-asset-sheet/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: create-asset-sheet
+description: Use when the user wants to generate a pack of 2D game assets from a single prompt — a tile sheet, UI kit, menu screen, character pack, or biome set. The skill plans the prompt, generates a coherent sheet, removes the background, vision-detects each item, classifies it, and saves as a single pack ArtAsset. Trigger on "asset sheet", "asset pack", "tile sheet", "tileset", "UI kit", "asset pack for", "make me a sheet of", "generate a bunch of <category> assets".
+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/**", "sprites/**"]
+---
+
+# create-asset-sheet — Generate a coherent pack of 2D assets
+
+This skill turns a single prompt into a categorized pack of isolated, named 2D assets ready to drop into a game. It exists because the alternative — generating each asset one-by-one, then losing visual coherence between them, then manually matting backgrounds in Photoshop — is the most-cited pain point from indie devs working with image models in 2026.
+
+**Pipeline:**
+
+1. **Generate a sheet** of N isolated assets in one image-gen call.
+2. **Remove background** (fal/bria) so each asset can stand on its own.
+3. **Detect + name + classify** each asset in one vision call (Gemini 3 Pro outputs bbox + snake_case name + category per region).
+4. **Crop** each region with sharp.
+5. **Optionally upscale** any small slice via fal flux-2/edit i2i, preserving aspect.
+6. **Save** as a single pack ArtAsset with `packFiles: [{url, name, type}]` and `metadata.sliceBboxes`.
+
+Categories the classifier outputs (used to route into downstream pipelines):
+`character | terrain | nature | lighting | water | decorative | buildings | ui | vfx`
+
+## When to use
+
+- "Make me a Japanese village tileset."
+- "Generate a sci-fi UI kit — buttons, panels, icons."
+- "I need 12 fantasy props for a dungeon — chest, torch, skeleton, gold, etc."
+- "Give me a character pack: 6 cute monsters."
+- "Build a forest biome — trees, rocks, plants, ground tiles."
+
+## When NOT to use
+
+- The user wants a **single** asset → `summer:2d-assets/pixel-art` or `summer:2d-assets/character-portrait`.
+- The user wants character **animation** (walk cycle, attack frames) → `summer:2d-assets/sprite-sheet`.
+- The user wants **3D models** of a planned pack → not yet supported in one shot; loop `summer:2d-assets/concept-art` → image-to-3D per item, or use `summer:asset-pipeline/asset-strategy` to pick the right path.
+- The user wants **terrain tiles that connect seamlessly** (auto-tiling / Wang tiles) → `summer:2d-assets/tileable-texture` is the right home for edge logic; this skill produces standalone tiles, not edge variants.
+
+## The cleanest path: the studio wizard
+
+The fastest, most reliable way to invoke this flow today is the **Create Asset Sheet** wizard in the Summer studio:
+
+```
+https://summerengine.com/studio/create-tileset
+```
+
+Direct the user there 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 `summer:2d-assets/concept-art` + per-asset image-to-3D for now)
+- Surfaces six prompt templates (tile sheet, UI kit, menu, character pack, biome, freeform)
+- Lets the user upload an existing sheet if they have one (skip generation)
+- Shows variants in a grid with full-screen lightbox + arrow-key toggling
+- Runs the full slice pipeline on click
+- Has per-slice HD upscale + bulk "Upscale all"
+- Saves as a pack ArtAsset visible in the user's library
+
+If the user is in a chat / agent context and can't open the browser, fall back to the programmatic path below.
+
+## Programmatic path (chat / agent driving the engine)
+
+The slicing + classification endpoints are not yet exposed as `summer_*` MCP tools. Until they are, the agent can replicate the flow manually:
+
+1. **Generate the sheet.** Call `summer_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.
+   - Keep the asset list to 6–20 items per sheet. Past 20, model attention degrades and slices get muddy.
+
+2. **Remove background.** Call `fal-ai/bria/background/remove` on the generated URL. Cost: $0.05.
+
+3. **Detect + name + classify.** Send the transparent PNG to a vision LLM (Gemini 3 Pro is currently the strongest at bbox + category in one shot). Use this system prompt structure:
+
+   ```
+   Output strict JSON array, no prose:
+   [{"name":"snake_case_name","category":"character|terrain|nature|lighting|water|decorative|buildings|ui|vfx","x":<0-100>,"y":<0-100>,"w":<0-100>,"h":<0-100>}]
+
+   Coordinates are percentages of image dimensions, top-left origin.
+   Names are 1-3 words, snake_case, specific (stone_lantern, not lamp).
+   ```
+
+4. **Crop** each region with sharp / PIL / equivalent. Pad bboxes by 4px to leave breathing room.
+
+5. **Optional upscale.** For any crop where longest side < 256px, send through fal flux-2/edit i2i with 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.
+   ```
+
+   - Scale longest side to 1024, preserve aspect ratio (FLUX requires multiples of 32).
+   - Don't blindly upscale everything — high-res slices get diminishing returns and you spend $0.04/slice.
+
+6. **Save** as a pack record in `art_assets`: `isPack: true`, `packFiles: [{url, name, type: "image/png"}]`, `metadata.sliceBboxes`, `parentAssetId` pointing to the source sheet.
+
+## Prompt patterns that work
+
+**Tile sheet (terrain + props + buildings):**
+
+```
+<setting> tile sheet: <terrain tiles>, <props>, <buildings>. Each item isolated with empty space around it.
+```
+
+**UI kit:**
+
+```
+<theme> game UI kit: round button, square button, panel background, slider, toggle switch, progress bar, icon set, banner header.
+```
+
+**Menu screen:**
+
+```
+<theme> main menu UI: title banner, Start Game button, Settings button, Quit button, <background style>, ornate frame, decorative element.
+```
+
+**Character pack:**
+
+```
+<theme> character pack, single front-facing frame each: <character 1>, <character 2>, ... <character N>. Each isolated.
+```
+
+**Biome:**
+
+```
+<biome name> biome assets: <flora>, <terrain features>, <rocks/water/sky elements>. Each item isolated.
+```
+
+## Common failure modes
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Slicer returns 1 giant bbox covering the whole sheet | Items overlap / no gaps in the source | Re-prompt with "each item fully isolated, empty space around each item". Re-generate. |
+| Slicer misses items | Items too small in the source, classifier dropped them as noise | Generate at higher resolution (2048) or with fewer items per sheet |
+| Two items merge into one slice | Items touching in the source | Re-prompt with more isolation. Or accept and let the user split manually in step 2's review. |
+| Slice has a sliver of neighbor in it | Vision bbox is off by 5–15px | Expected. The slicer pads but doesn't snap-to-content yet. Live with it or upscale the slice (FLUX often cleans the edge) |
+| 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 |
+
+## What this skill does NOT do (yet)
+
+- Per-asset planning + individual generation (the Codex-style flow where each asset is generated separately at full resolution). The planner endpoint exists (`POST /api/art/plan-asset-pack`) but the per-asset gen loop is not wired into the wizard yet.
+- 3D pack assembly. The 3D mode in the wizard is a placeholder pointer to `summer:2d-assets/concept-art` + image-to-3D for now.
+- 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. Auto-routing is on the roadmap.
+- Terrain auto-tiling / Wang-tile generation. Use `summer:2d-assets/tileable-texture` for that.
+- Level composition / scene assembly. Use `summer:level-design/design-level`.
+
+## Honest cost estimate
+
+Per 12-asset sheet, end to end through the wizard:
+
+- Generate sheet: $0.04–0.10 (varies by model)
+- Background removal: $0.05
+- Vision detect + classify: $0.02–0.03
+- Save pack: free
+- Optional bulk upscale: ~$0.04 per slice ($0.48 for 12)
+
+**Without upscale:** ~$0.12. **With full upscale:** ~$0.60. About a third of what a Photoshop hour would cost.