summer-engine 2.6.6 → 2.8.0

package/references/mcp-tools-reference.md

@@ -0,0 +1,199 @@
+# Summer MCP Tools — Canonical Reference
+
+> Use this as the single source of truth for which Summer MCP tool to call. Skills should reference tool names exactly as written here.
+
+## When to use Summer MCP vs. host tools
+
+**Use Summer MCP for** anything that needs the live editor or Godot's import pipeline:
+- Scene graph mutation (`.tscn`)
+- Node properties and resources (`.tres`)
+- Project settings (`project.godot`) and InputMap
+- Asset import (Godot's import pipeline must run)
+- Play / stop / runtime state
+- Diagnostics, console, debugger output, script errors
+- Project text reads and guarded writes (`.gd`, `.cs`, `.tscn`, `.tres`, JSON, docs, config)
+
+**Use host tools for** git, shell, grep, and non-project work. External host file writes bypass Summer's project-identity, sha256, and editor-reload safeguards and should not be used for project mutations while MCP is available.
+
+**Rule of thumb:** project reads/writes go through Summer; live hierarchy/inspector changes use scene tools; process-level work remains with the host.
+
+## Tool surface (62 tools)
+
+### Project files (3)
+
+| Tool | Use |
+|---|---|
+| `summer_read_file` | Read project text plus a full-file sha256 receipt. |
+| `summer_write_file` | Create-only or sha256-guarded complete file write. |
+| `summer_replace_text` | Unique (or explicit replace-all) text mutation with read/sha guard. |
+
+### Scene graph (11)
+
+| Tool | Use |
+|---|---|
+| `summer_get_scene_tree` | Read current scene graph. Always do this before mutating. |
+| `summer_open_main_scene` | Open the project's main scene. |
+| `summer_open_scene` | Open a specific `.tscn`. |
+| `summer_create_scene` | Create a new scene. |
+| `summer_instantiate_scene` | Add an existing scene or 3D model as a child node. |
+| `summer_inspect_node` | Read a single node's properties. |
+| `summer_add_node` | Add a node to the explicit `scenePath`; the tab need not be open. |
+| `summer_remove_node` | Remove a node from the explicit `scenePath`. |
+| `summer_replace_node` | Swap a node's type in the explicit `scenePath`, preserving children. |
+| `summer_select_node` | Set editor selection (visual feedback for the user). |
+| `summer_save_scene` | Explicitly save/save-as a `scenePath`; mutation tools already append one final save. |
+
+### Properties / resources (4)
+
+| Tool | Use |
+|---|---|
+| `summer_set_prop` | Set a typed property in an explicit `scenePath` using Godot's `str_to_var()`. |
+| `summer_set_resource_property` | Set a nested resource property in an explicit `scenePath`. |
+| `summer_inspect_resource` | Read a resource's properties. |
+| `summer_connect_signal` | Wire a signal between nodes. |
+
+### Project & input (2)
+
+| Tool | Use |
+|---|---|
+| `summer_project_setting` | Modify `project.godot` settings (rendering, physics). |
+| `summer_input_map_bind` | Bind input actions in InputMap. Folds in the legacy `add_action` step. |
+
+### Import pipeline (2)
+
+| Tool | Use |
+|---|---|
+| `summer_import_from_url` | Download a `.glb`/`.png`/etc and run Godot's full import pipeline. |
+| `summer_import_from_url_batch` | Same, batched (single filesystem scan). |
+
+### Play / runtime (3)
+
+| Tool | Use |
+|---|---|
+| `summer_play` | Run the game. |
+| `summer_stop` | Stop the running game. |
+| `summer_is_running` | Check play state before deciding to call `summer_stop`. |
+
+### Visual capture (1)
+
+| Tool | Use |
+|---|---|
+| `summer_screenshot` | Capture a frame and return it as an image the agent sees directly — editor viewport (`target:"viewport"`, default; no play needed) or running game (`target:"game"`). Use to visually verify scene layout, asset placement, scale, framing, lighting, or runtime state. On macOS the running game is a floating window that can't be captured; prefer `viewport`. |
+
+### Diagnostics (7)
+
+| Tool | Use |
+|---|---|
+| `summer_create_debug_report` | Create a support-ready Markdown report for `/summer debug`. |
+| `summer_get_diagnostics` | Aggregate error/warning summary. Call after every change. |
+| `summer_get_console` | Engine output panel. |
+| `summer_clear_console` | Clear before a fresh play, so post-run output is clean. |
+| `summer_get_debugger_errors` | Runtime errors with stack traces. |
+| `summer_get_debugger_warnings` | Runtime warnings from the debugger panel. |
+| `summer_get_script_errors` | Script compilation errors. |
+
+### Asset library (6)
+
+| Tool | Use |
+|---|---|
+| `summer_search_assets` | Free public asset search (community library + user's own). Sources: `library`, `community`, `my_assets`, `all`. |
+| `summer_list_my_assets` | List/search the signed-in user's generated and uploaded assets. Empty query lists recent assets. |
+| `summer_get_asset` | Fetch one exact asset by ID with file URL, download URL, viewer URL, metadata, license, and visibility. |
+| `summer_get_asset_download_url` | Get the primary or thumbnail download URL for a specific asset. Stable shape for future signed URLs. |
+| `summer_import_asset` | Search, choose the top match, download, run Godot import, and optionally instantiate 3D models. |
+| `summer_import_asset_by_id` | Import one exact Summer asset ID. Use after generation jobs or when the user selects a specific asset. |
+
+### Asset generation (5 — metered)
+
+| Tool | Use |
+|---|---|
+| `summer_generate_image` | AI image gen. |
+| `summer_generate_3d` | Image-to-3D. |
+| `summer_generate_audio` | SFX / music gen. |
+| `summer_generate_video` | Video gen. |
+| `summer_generate_motion` | Generate/apply 3D skeletal motion from a rigged asset. |
+
+### Job tracking (2)
+
+| Tool | Use |
+|---|---|
+| `summer_check_job` | Poll a generation job. |
+| `summer_batch` | Run multiple ops as a transaction. |
+
+### Meta (3)
+
+| Tool | Use |
+|---|---|
+| `summer_start_game_task` | Route a user goal into the right workflow, skills, MCP tool groups, asset policy, gates, and verification path. |
+| `summer_get_project_context` | Project, scene, and `.summer` memory summary — call at start of session. |
+| `summer_get_agent_playbook` | Daily operating contract — call at start of session. |
+
+### Cloud sync (7)
+
+| Tool | Use |
+|---|---|
+| `summer_cloud_init` | Enable Summer Cloud for a project. |
+| `summer_cloud_status` | Show Summer Cloud sync status. |
+| `summer_cloud_push` | Push local project changes to Summer Cloud. |
+| `summer_cloud_pull` | Pull Summer Cloud changes into the local project. |
+| `summer_cloud_restore` | Restore a retained cloud version, or a local pre-sync checkpoint. |
+| `summer_cloud_checkpoints` | List local pre-sync checkpoints. |
+| `summer_cloud_conflicts` | List conflict sets, or restore a preserved conflict file. |
+
+### Creator platform (4)
+
+| Tool | Use |
+|---|---|
+| `summer_creator_publish` | Compute the exact `.pck` digest and size, require user confirmation, then run versioned prepare → write-once upload → finalize. The server independently verifies `publish` scope, ownership, bytes, and review state. |
+| `summer_creator_releases` | List real creator-owned releases from `summer.creator.v1`, with opaque cursor pagination. |
+| `summer_creator_logs` | Read runtime logs for a project or release. Remains fail-closed until a durable platform log source exists. |
+| `summer_creator_config` | Read or confirm updates to the shared non-secret `~/.summer/config.json`. It never accepts or returns tokens. |
+
+## Common pattern
+
+Every scene-touching skill should follow this loop:
+
+1. `summer_start_game_task` — route the goal into skills/tools/gates.
+2. `summer_get_project_context` — orient.
+3. `summer_get_agent_playbook` — read the rules.
+4. Resolve the exact `res://` scene path; open it only for an intentional current-tab read/UI action.
+5. Pass that `scenePath` to mutations (`summer_add_node`, `summer_set_prop`, `summer_connect_signal`, ...).
+6. Mutation tools append one final `SaveScene`; use `summer_save_scene` directly only for a standalone save/save-as.
+7. `summer_get_script_errors` — catch GDScript breakage.
+8. `summer_play` → `summer_get_debugger_errors` → `summer_screenshot` (see what's on screen) → `summer_stop` if verifying runtime.
+
+Every asset-generation skill should follow this loop:
+
+1. `summer_search_assets` or `summer_list_my_assets` — reuse before generating when reasonable.
+2. `summer_generate_image` / `summer_generate_3d` / `summer_generate_audio` — metered creation.
+3. `summer_check_job` if the generation was async.
+4. `summer_get_asset` — resolve the returned `assetId`, `rigAssetId`, or `animationAssetId`.
+5. `summer_import_asset_by_id` — import the exact result into Godot's pipeline.
+6. `summer_get_asset_download_url` — only when the user explicitly wants a downloadable file/link.
+
+## summer_set_resource_property — nested properties
+
+Use it to reach a property *of a resource attached to a node* — mesh size, shape radius, material colour — the thing `summer_set_prop` cannot reach.
+
+```
+summer_add_node(parent="/", type="MeshInstance3D", name="Box", scenePath="res://main.tscn")
+summer_set_prop(path="Box", key="mesh", value="BoxMesh", scenePath="res://main.tscn")
+summer_set_resource_property(
+    nodePath="Box", resourceProperty="mesh", subProperty="size",
+    value="Vector3(2, 2, 2)", scenePath="res://main.tscn")
+```
+
+`nodePath`, `resourceProperty` and `subProperty` are all required and canonical. There is no dotted `"mesh.size"` form.
+
+**Inline `sub_resource` targets work.** An earlier revision of this file claimed the op silently fails on an inline sub-resource and told you to save the resource as a standalone `.tres` first. That was wrong, and it propagated into nine skills. The implementation reads `node->get(resourceProperty)` and sets the sub-property on whatever comes back (`modules/1summer_engine/editor/ops/scene_ops.cpp:1273-1400`) — there is no inline-versus-external branch anywhere in it. The canonical example in the shipped `summer_batch` description does exactly this against an inline mesh.
+
+Failures are explicit, never silent:
+
+| Error | Meaning |
+|---|---|
+| `no edited scene` | Nothing open — pass `scenePath`. |
+| `node not found: <path>` | `nodePath` is wrong; it is relative to the scene root. |
+| `property is not a resource` | `resourceProperty` names a plain value, not a resource. |
+| `resource is null` | The node has the property but nothing is assigned yet. Assign it first. |
+
+If you get none of those and the value still did not change, that is a bug worth reporting — not expected behaviour to design around.

package/references/public-surface-language.md

@@ -0,0 +1,30 @@
+# Summer public-surface language boundary
+
+Summer Engine is the creator product. Users make a **Summer game** with the
+**Summer SDK**, normally in **GDScript**. Headlines, onboarding, CLI errors,
+shipped skill descriptions, and generated prompts use those names.
+
+Godot Engine remains relevant in narrow technical and legal contexts:
+
+- upstream compatibility and continuous-upstream maintenance;
+- migration of existing projects;
+- extension APIs, class references, file formats, and import behavior;
+- literal paths and filenames such as `project.godot` and `.godot/`;
+- upstream contributions, attribution, copyright, and licenses.
+
+The current technical base is 4.6.1 and the approved next target is 4.7.1. The
+source of truth is the repository compatibility contract. Neither number is a
+permanent Summer identity, so creator prompts and skills should not pin
+themselves to one upstream release.
+
+Run the focused regression guard and inventory with:
+
+```bash
+npm run test:public-language
+```
+
+The guard blocks known Godot-led identity phrases and stale fixed-4.5 scaffold
+language across shipped surfaces. It also prints the remaining Godot-reference
+inventory grouped by file. This is intentionally not a semantic linter: a human
+must still review those references and confirm that each is technical,
+migration-related, attribution, or legal context.

package/references/summer-folder.md

@@ -0,0 +1,90 @@
+# `.summer/` Folder Convention
+
+> The canonical layout for project-scoped Summer state. Read this if you're authoring a skill that writes durable design output, locked project memory, or agent-readable design notes.
+
+## Files at the root of `.summer/`
+
+- `GameSoul.md` — the project brief. Created by `/summer:brainstorm-game`. Contains: name, one-sentence pitch, core loop, 3 mechanics max, art direction summary, scope. Updated whenever the game's high-level direction changes.
+- `art-bible.md` — visual style reference. Created by `/summer:art-direction`. Contains: palette (6–15 hex codes), mood adjectives, lighting plan, post-processing notes, do/don't list, references.
+- `audio-bible.md` — sonic identity. Created by `/summer:audio-direction`. Contains: music style + tempo range, SFX vocabulary (8 classes), dynamic music FSM, bus layout reference.
+- `build-plan.md` — implementation plan derived from `GameSoul.md`. Created by `/summer:make-game` before scaffold/build work.
+
+## Subdirectories
+
+- `mechanics/<mechanic-name>.md` — one file per designed mechanic (e.g., `double-jump.md`, `parry.md`). Created by `/summer:design-mechanic`. Contains: input → response → feedback → failure modes → tunable parameters.
+- `levels/<level-name>.md` — one file per designed level. Created by `/summer:design-level`. Contains: teaching goal, pacing curve (5 beats), encounters, secrets, reward gating.
+- `npcs/<npc-name>.md` — one file per designed NPC. Created by `/summer:design-npc`. Contains: archetype, perception model, decision tree, escalation, defeat sequence.
+- `memory/` — structured project memory for durable facts that must survive future sessions. Use this for locked cast decisions, character facts, provider IDs, world canon, and conflict notes.
+- `skills/` — installed project-scoped Summer skills. Do not put game design memory here.
+
+## Structured memory
+
+Use `.summer/memory/` when the fact is more specific than a bible, must be re-used by many skills, or must not silently drift. Examples:
+
+- `memory/casting/voices.md` — stable character-to-voice assignments, including ElevenLabs voice IDs.
+- `memory/characters/<character-name>.md` — canonical character facts, aliases, personality, visual/audio constraints, linked assets.
+- `memory/world/canon.md` — lore and setting facts that dialogue, quests, levels, and art should not contradict.
+- `memory/systems/<system-name>.md` — gameplay rules and implementation decisions that cross scenes/scripts.
+- `memory/decisions/<yyyy-mm-dd-topic>.md` — rationale for important choices.
+- `memory/conflicts/open.md` — unresolved conflicts between memory and implementation.
+
+Markdown is canonical. Optional generated indexes such as `memory/index.json` may exist for UI/search speed, but agents must treat the Markdown files as the source of truth.
+
+Locked facts should use short YAML frontmatter:
+
+```yaml
+---
+id: casting.voice.main-cast
+type: casting
+status: active
+priority: locked
+stable: true
+applies_to:
+  - character:bob
+  - character:sarah
+providers:
+  - elevenlabs
+---
+```
+
+Then write the fact in normal Markdown so users can inspect and edit it:
+
+```markdown
+# Main Voice Cast
+
+| Character | Provider | Voice ID | Stability |
+|---|---|---|---|
+| Bob | ElevenLabs | `voice_bob_id` | locked |
+| Sarah | ElevenLabs | `voice_sarah_id` | locked |
+```
+
+## Conventions
+
+- All filenames are lowercase, hyphens not underscores.
+- Skills MUST ask "May I write/update `.summer/<file>`?" before any write to this folder.
+- Skills MAY read existing files in `.summer/` without permission to ground their output in prior decisions.
+- The folder lives in the project root (sibling to `project.godot`).
+- Add `.summer/` to `.gitignore` if the user prefers it private; default is to commit it (game design lives with the game).
+- Changing a `priority: locked` memory requires explicit user confirmation. If implementation data conflicts with locked memory, stop and ask whether to update memory or fix the implementation.
+
+## Skills that write here
+
+| Skill | Writes |
+|---|---|
+| `/summer:brainstorm-game` | `.summer/GameSoul.md` |
+| `/summer:art-direction` | `.summer/art-bible.md` |
+| `/summer:audio-direction` | `.summer/audio-bible.md` |
+| `/summer:design-mechanic` | `.summer/mechanics/<name>.md` |
+| `/summer:design-level` | `.summer/levels/<name>.md` |
+| `/summer:design-npc` | `.summer/npcs/<name>.md` |
+| `/summer:voice-line` | `.summer/memory/casting/voices.md` |
+| `/summer:debug` | does NOT write here |
+| `/summer:play` | does NOT write here |
+| `/summer:vfx` | does NOT write here (VFX edits scenes/scripts) |
+| `/summer:tune-performance` | optionally writes `.summer/perf-notes.md` if user requests |
+| `/summer:setup-multiplayer` | optionally writes `.summer/multiplayer-architecture.md` |
+| `/summer:export-and-ship` | does NOT write here (writes export configs in `project.godot`) |
+
+## Linter check (future)
+
+Once `workflow/skill-test` gains an executable mode, it should validate that any skill writing to `.summer/` is documented in the table above.

package/references/template-registry.md

@@ -0,0 +1,73 @@
+# Template Registry
+
+> Skills cross-link to template repos via the `template-id` frontmatter field.
+>
+> **This file is a convenience snapshot, not the source of truth.** Templates are discovered live from the GitHub org, so this table goes stale the moment a template is added. Ask the CLI instead:
+>
+> ```bash
+> summer list templates
+> ```
+
+## How discovery actually works
+
+`summer list templates` queries `github.com/SummerEngine` for repos named `template-*`, and **strips the `template-` prefix to produce the slug** (`src/lib/remote-templates.ts`). So the repo `template-2d-platformer` is created with:
+
+```bash
+summer create 2d-platformer my-game
+```
+
+There is no `summer template clone` command. `summer create <slug> [dir]` is the only bootstrap path, and it takes the stripped slug, not the repo name.
+
+## Snapshot — verified against `summer list templates`
+
+Built-in, no download required:
+
+| slug | Description |
+|---|---|
+| `empty` | Empty 3D project with just a root node |
+| `3d-basic` | 3D scene with camera, light, and floor |
+
+Community templates, all at `https://github.com/SummerEngine/template-<slug>`:
+
+| slug | Description |
+|---|---|
+| `2d-brario-platformer` | 2D platformer starter |
+| `2d-grid-puzzle` | Grid-based puzzle starter |
+| `2d-plants-and-zombies-tower-defense` | Lane tower-defense starter |
+| `2d-platformer` | 2D platformer starter (TileMap, CharacterBody2D, parallax) |
+| `2d-rpg` | 2D top-down RPG starter (built on GDQuest's open-source work) |
+| `2d-vampire-survivor-roguelike` | Survivors-like roguelike starter |
+| `3d-fps-old-school` | Retro first-person shooter starter |
+| `3d-fps-simple-animated-npc` | FPS starter with an animated NPC |
+| `3d-lan-multiplayer-starter` | 3D LAN multiplayer starter (built on GDQuest's open-source work) |
+| `3d-open-world-explore-tps` | Third-person open-world exploration starter |
+| `3d-racing-game` | Racing starter |
+| `3d-royale-clash-type` | Auto-battler / lane-pusher starter |
+| `3d-third-person-controller` | 3D third-person character controller (built on GDQuest's open-source work) |
+| `3d-voxel-sandbox` | Voxel sandbox (chunked world, face culling, mining/building, seeded gen) |
+
+If a slug you expect is missing here, it is this file that is out of date, not the CLI. Run `summer list templates`.
+
+## Convention
+
+Each template is its own GitHub repo under the `SummerEngine` org, MIT licensed, kept small (< 50 MB), and named `template-<slug>`. Templates ship working code; skills describe patterns. A skill links to the matching template via:
+
+```markdown
+## Want a working starter?
+
+This skill describes the pattern. For a runnable project, use the template:
+
+→ **template-id**: `template-2d-platformer`
+→ **Repo**: https://github.com/SummerEngine/template-2d-platformer
+→ **Bootstrap**: `summer create 2d-platformer my-game`
+```
+
+## Linter check
+
+The `workflow/skill-test/SKILL.md` static linter validates that any `template-id:` declared in a skill's frontmatter exists in the table above. Because the table is a snapshot, a linter failure may mean the table is stale rather than the skill being wrong — check `summer list templates` before editing the skill.
+
+## Adding a template
+
+1. Create a new repo under the `SummerEngine` org named `template-<slug>`, MIT license.
+2. It appears in `summer list templates` automatically — no registration step.
+3. Add it to the snapshot above and reference the `template-id` from any relevant skill.

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

@@ -60,15 +60,16 @@ angle: three-quarter view, slight turn to character's left
 lighting: soft warm key from upper right, cool fill from left, gentle rim
 background: muted painterly gradient, dark teal to deep brown, no scene detail
 style: semi-realistic painterly, soft edges, oil-painting feel
-aspect: portrait_4_3
 ```
 
+Note there is no aspect line. `summer_generate_image` has no size or aspect argument — every MCP image comes back at the server's 1:1 default. Bust framing reads fine square, which is why this skill works over MCP at all; if the cast needs true portrait framing, generate in the Summer dashboard (which exposes aspect ratio) and bring the results back with `summer_import_from_url`, or crop after. Whichever you pick, do it for the *whole* cast — mixed aspect is as visible as mixed lighting.
+
 Every subsequent portrait in this cast appends the anchor to the prompt verbatim. **Do not edit the anchor mid-cast** unless the user explicitly says "I want the new ones to look different."
 
 ### 2. Search for an existing portrait
 
 ```
-summer_search_assets(query="<character name> portrait", filter={ kind: "image" })
+summer_search_assets(query="<character name> portrait", assetType="2d_image", source="all")
 ```
 
 Reuse beats regenerate. If the user wants to iterate on an existing one, pull its URL and pass it as `referenceImageUrl` for img2img.
@@ -91,12 +92,13 @@ The character description should include: identity (age, build, hair, distinctiv
 summer_generate_image(
   prompt="Aria, young witch, mid-twenties, pale skin, long black hair with silver streak, sharp green eyes, half-smile, wearing dark indigo robes with silver embroidery, raven on shoulder. <anchor verbatim>",
   model="nano-banana-2",
-  style="none",
-  options={ image_size: "portrait_4_3" }
+  style="none"
 )
 ```
 
-`style: "none"` because the anchor's "semi-realistic painterly" already specifies style; the preset would fight it.
+`style: "none"` because the anchor's "semi-realistic painterly" already specifies style. Be clear about what the preset actually does though: only `cartoon` and `anime` append anything to the prompt, and `realistic` / `none` append nothing — any other value is coerced to `none`. So the preset cannot "fight" a painterly anchor; it just does nothing either way, and every bit of the look has to be in the prompt.
+
+`options={ image_size: ... }` is dropped without an error — see the anchor note above.
 
 ### 5. Import and wire into UI
 
@@ -110,13 +112,16 @@ summer_import_from_url(
 For dialogue UI nodes, wire the texture into a `TextureRect`:
 
 ```
-summer_set_resource_property(
-  nodePath="/root/UI/DialogueBox/PortraitRect",
-  resourceProperty="texture",
+summer_set_prop(
+  scenePath="res://ui/dialogue.tscn",
+  path="./DialogueBox/PortraitRect",
+  key="texture",
   value="res://ui/portraits/aria.png"
 )
 ```
 
+`texture` is a property on the node, so this is `summer_set_prop` — which needs an explicit `scenePath`, a node path relative to that scene's root (`./`), and a `key` argument, not `property`. `summer_set_resource_property` is for reaching one level *inside* a resource the node already holds and requires all five of `scenePath`, `nodePath`, `resourceProperty`, `subProperty`, `value`.
+
 For character-select with multiple portraits, name files consistently: `aria.png`, `borin.png`, `cael.png`, `dara.png`. Index-able from code via `"res://ui/portraits/%s.png" % character_id`.
 
 ### 6. Iterate (img2img) instead of regenerating from scratch
@@ -150,7 +155,7 @@ summer_generate_image(
 | `cool warrior portrait` | No identity, no anchor. Returns generic stock art. |
 | `the witch but make her sad` (no img2img ref) | Without `referenceImageUrl`, you get a *different* witch who is sad. Identity drift. |
 | Anchor inconsistent across cast | Each portrait looks like a different game. The cast doesn't read as a cast. |
-| `full body portrait` | "Portrait" implies bust. If you want full body, say so explicitly AND switch to `image_size: "portrait_4_3"` framed full-body — but that's a different asset class; consider `concept-art` or 3D pipeline. |
+| `full body portrait` | "Portrait" implies bust. If you want full body, say so explicitly in the prompt — there is no size argument to reframe with, and full body in a square frame is a different asset class anyway; consider `concept-art` or the 3D pipeline. |
 | `transparent background` for a painterly portrait | Painterly + transparent fails on most models. Use a flat or gradient background, then alpha-cut in an editor if you must. |
 
 ## Anti-patterns
@@ -159,7 +164,7 @@ summer_generate_image(
 - **Editing the anchor mid-cast.** If you change lighting from "warm key" to "dramatic side" halfway through, the cast splits visually. Either commit to the change and regenerate everyone, or stick with the anchor.
 - **Regenerating from scratch when img2img would do.** Identity drifts every regen. Iterate via `referenceImageUrl`.
 - **Using the portrait as a 3D reference.** Portraits have dramatic lighting, painterly backgrounds, and cropped framing — all of which corrupt 3D generation. For 3D, generate a separate clean white-bg full-body T-pose via `summer:asset-pipeline/asset-strategy`.
-- **Using `style: "realistic"` or `"cartoon"`** when the anchor already names a style. The preset overrides the anchor.
+- **Expecting `style` to carry the look.** Only `cartoon` and `anime` append anything; `realistic` and `none` append nothing and any other value is coerced to `none`. If the anchor names the style, `"none"` is correct — but the anchor text is doing all the work, not the preset.
 
 ## Edge cases
 
@@ -173,7 +178,7 @@ summer_generate_image(
 Print the prompt and the call:
 
 ```
-summer_generate_image(prompt="<character + anchor>", model="nano-banana-2", style="none", options={ image_size: "portrait_4_3" })
+summer_generate_image(prompt="<character + anchor>", model="nano-banana-2", style="none")
 ```
 
 Tell the user to run via the Summer dashboard, then `summer_import_from_url` the result to `res://ui/portraits/<name>.png`.
@@ -193,4 +198,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.
-- `references/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

@@ -44,7 +44,7 @@ If "final" → hand off to `summer:2d-assets/character-portrait`. If "explore"
 ### 2. Search for prior concepts
 
 ```
-summer_search_assets(query="<subject> concept", filter={ kind: "image" })
+summer_search_assets(query="<subject> concept", assetType="2d_image", source="all")
 ```
 
 If something already exists, ask if the user wants to riff on it (img2img via `referenceImageUrl`) or start fresh.
@@ -69,14 +69,15 @@ Issue 3-4 calls in parallel, one per variant. Use the same subject phrasing acro
 
 ```
 summer_generate_image(
-  prompt="<subject>. <axis variant 1>. concept art, evocative, rough painterly, atmospheric lighting",
+  prompt="<subject>. <axis variant 1>. concept art, evocative, rough painterly, atmospheric lighting, wide cinematic framing",
   model="nano-banana-2",
-  style="none",
-  options={ image_size: "landscape_16_9" }
+  style="none"
 )
 ```
 
-`style: "none"` is intentional — concept art doesn't want the default "realistic" or "cartoon" preset overriding the prompt's stylistic direction.
+`style: "none"` is intentional, but be precise about why: only `cartoon` and `anime` append anything to the prompt, `realistic` and `none` append nothing, and any other value is coerced to `none`. So the preset cannot override the prompt's stylistic direction — it just contributes nothing, which is what concept art wants. All four variants' divergence has to come from the prompt.
+
+There is no `image_size` argument, and `options` only recognizes Nano Banana provider keys plus `removeBackground` — an unrecognized key is dropped without an error. Every MCP image comes back at the server's 1:1 default. For wide key art, ask for "wide cinematic framing" in the prompt and accept the square canvas, or generate in the Summer dashboard where aspect ratio is exposed. Since these are exploration images the user reacts to and throws away, square is usually fine.
 
 ### 5. Present the batch
 
@@ -112,7 +113,7 @@ The structure: **subject + axis variant + "concept art" + lighting/atmosphere**.
 
 - **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.
+- **Treating `style` as the variant axis.** The presets are `realistic | cartoon | anime | none`, and only two of them append anything. Four "stylization" variants have to differ in their prompt text, not in the `style` argument.
 - **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.
 
@@ -120,7 +121,7 @@ The structure: **subject + axis variant + "concept art" + lighting/atmosphere**.
 
 - **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.
+- **Subject is a fully described scene, not an asset.** You're producing key art, not asset reference. Ask for wide cinematic framing in the prompt and bias toward atmospheric — you cannot set an aspect ratio over MCP.
 - **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)
@@ -128,7 +129,7 @@ The structure: **subject + axis variant + "concept art" + lighting/atmosphere**.
 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 1>", model="nano-banana-2", style="none")
 summer_generate_image(prompt="<variant 2>", ...)
 ...
 ```
@@ -149,4 +150,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.
-- `references/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

@@ -5,7 +5,7 @@ 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
+allowed-tools: Read Grep Glob Write Edit summer_get_studio_workflow summer_generate_image summer_slice_asset_sheet summer_search_assets summer_import_asset_by_id summer_import_from_url
 paths: ["assets/**", "art/**", "sprites/**"]
 ---
 
@@ -58,13 +58,16 @@ Direct the user there if they're working in the browser. The wizard:
 - 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.
+If the user is in a chat / agent context, use the programmatic path below. It
+now calls the same server-side slicer as the Studio wizard.
 
 ## 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. **Load the exact current recipe.** Call
+   `summer_get_studio_workflow({workflowId: "asset-pack"})`. Follow its ordered
+   steps and report any `manual` handoff instead of pretending it ran.
 
-1. **Generate the sheet.** Call `summer_generate_image` with a prompt like:
+2. **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.
@@ -74,21 +77,18 @@ The slicing + classification endpoints are not yet exposed as `summer_*` MCP too
    - 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:
+3. **Slice, remove background, detect, name, classify, crop, and save.** Pass
+   the returned image asset id to:
 
    ```
-   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).
+   summer_slice_asset_sheet({ assetId: "<generated asset id>" })
    ```
 
-4. **Crop** each region with sharp / PIL / equivalent. Pad bboxes by 4px to leave breathing room.
+   This is the same cloud slicing pipeline used by the Studio flow. Keep the
+   returned slice ids/names/categories; do not reimplement the vision boxes
+   locally.
 
-5. **Optional upscale.** For any crop where longest side < 256px, send through fal flux-2/edit i2i with prompt:
+4. **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.
@@ -97,7 +97,9 @@ The slicing + classification endpoints are not yet exposed as `summer_*` MCP too
    - 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.
+5. **Import what the game needs.** Use the returned asset ids with
+   `summer_import_asset_by_id`. Keep the source pack in My Assets so the agent
+   and the human Studio session see the same result.
 
 ## Prompt patterns that work