summer-engine 1.5.0 → 2.2.0

package/dist/lib/with-engine.js

@@ -0,0 +1,109 @@
+import { EngineApiClient } from "./api-client.js";
+import { getAuthToken } from "./auth.js";
+const GATEWAY_URL = process.env.SUMMER_GATEWAY_URL || "https://www.summerengine.com";
+export function extractOpError(result) {
+    if (!result || typeof result !== "object")
+        return null;
+    const op = result;
+    if (op.status === "error" && op.error)
+        return op.error;
+    const firstFailed = op.results?.find((r) => r.ok === false && r.error);
+    return firstFailed?.error ?? null;
+}
+export function buildActionHint(message) {
+    const normalized = message.toLowerCase();
+    if (normalized.includes("no scene open") || normalized.includes("no edited scene")) {
+        return "No scene is currently open. Run `summer project context` first, then `summer project open-main` (or `summer scene open` with a known .tscn path).";
+    }
+    if (normalized.includes("failed to open scene")) {
+        return "Scene path could not be opened. Run `summer project context` to get mainScene, then open that exact path. Avoid guessing scene filenames.";
+    }
+    if (normalized.includes("writefile cannot edit .tscn/.scn")) {
+        return "Cannot write .tscn/.scn directly. Use summer scene commands for scene-tree operations, and file-edit tools for .gd scripts.";
+    }
+    return null;
+}
+export async function checkQuota() {
+    const token = await getAuthToken();
+    if (!token) {
+        return {
+            allowed: false,
+            message: "Not signed in. Run: summer login\nOr open: https://www.summerengine.com/login\nEngine tools require a Summer Engine account (free to create).",
+        };
+    }
+    try {
+        const res = await fetch(`${GATEWAY_URL}/api/mcp/log-local-call`, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${token}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({}),
+            signal: AbortSignal.timeout(10000),
+        });
+        const data = (await res.json().catch(() => ({})));
+        if ([401, 402, 403, 429].includes(res.status)) {
+            return {
+                allowed: false,
+                message: data.message || "Quota check failed. Try again.",
+            };
+        }
+        // Soft-fail on service/gateway issues so local tools keep working.
+        if (!res.ok) {
+            return { allowed: true };
+        }
+        if (data.allowed === false) {
+            return {
+                allowed: false,
+                message: data.message || "Call limit reached. Upgrade at https://summerengine.com/pricing",
+            };
+        }
+        return { allowed: true };
+    }
+    catch {
+        // Network/transient errors should not brick local usage.
+        return { allowed: true };
+    }
+}
+let cachedClient = null;
+export function getClient() {
+    if (cachedClient)
+        return Promise.resolve(cachedClient);
+    return EngineApiClient.connect().then((c) => {
+        cachedClient = c;
+        return c;
+    });
+}
+export function resetClient() {
+    cachedClient = null;
+}
+/**
+ * Connect to the engine, check quota, and run the given function.
+ * Throws on errors (quota, connection, op errors).
+ */
+export async function withEngineClient(fn) {
+    const quota = await checkQuota();
+    if (!quota.allowed) {
+        throw new Error(quota.message || "Quota exceeded");
+    }
+    try {
+        const client = await getClient();
+        const result = await fn(client);
+        const opError = extractOpError(result);
+        if (opError) {
+            const hint = buildActionHint(opError);
+            throw new Error(hint ? `${opError}\n\nHint: ${hint}` : opError);
+        }
+        return result;
+    }
+    catch (err) {
+        // Reset client on connection errors so next call retries
+        if (err instanceof Error &&
+            (err.message.includes("not running") ||
+                err.message.includes("not responding") ||
+                err.message.includes("ECONNREFUSED"))) {
+            resetClient();
+        }
+        throw err;
+    }
+}

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

@@ -65,14 +65,6 @@ async function searchAssetsApi(params) {
     });
     const data = (await res.json());
     if (!res.ok) {
-        if (res.status === 402) {
-            return {
-                error: "upgrade_required",
-                message: (data.message || "Asset search requires a Pro subscription.") +
-                    "\nUpgrade at: https://www.summerengine.com/pricing\nFree tier includes all other MCP tools (scene editing, debugging, etc).",
-                plan: data.plan,
-            };
-        }
         if (res.status === 401) {
             return {
                 error: "unauthorized",
@@ -80,6 +72,13 @@ async function searchAssetsApi(params) {
                     " The user needs to re-authenticate:\n  npx summer-engine login --force",
             };
         }
+        if (res.status === 429) {
+            return {
+                error: "rate_limited",
+                message: (data.message || "Asset search rate limit hit. Wait a moment and try again.") +
+                    " The public library is free, but rate-limited per user to prevent bulk scraping.",
+            };
+        }
         return {
             error: data.error || "Search failed",
             message: data.message || "Asset search failed",
@@ -88,17 +87,17 @@ async function searchAssetsApi(params) {
     return data;
 }
 export function registerAssetTools(server) {
-    server.tool("summer_search_assets", `Search for game assets in the Summer Engine ecosystem.
+    server.tool("summer_search_assets", `Search for game assets in the Summer Engine ecosystem. **Free for all users** with rate limits.
 
 Sources:
-  - "library" (default) — Public asset library (25k+ community assets). Requires Pro plan.
-  - "my_assets" — Your own generated/uploaded assets. Free for all users. Query is optional.
+  - "library" (default) — Public asset library (25k+ community assets). Free.
+  - "my_assets" — Your own generated/uploaded assets. Free. Query is optional.
   - "all" — Search both library and your assets.
 
 Uses hybrid search: keywords + semantic similarity. Finds assets by name AND by meaning.
 Returns asset names, types, preview URLs, and import-ready file URLs.
 
-Requires authentication: run 'npx summer-engine login' first.`, {
+Requires authentication (so we can attribute usage and apply per-user rate limits): run 'npx summer-engine login' first.`, {
         query: z.string().describe("Natural language search, e.g. 'low-poly tree', 'sci-fi weapon'. For my_assets, can be empty to list recent."),
         assetType: z.enum(["2d_image", "animation", "3d_model", "audio", "music", "all"]).default("all").describe("Filter by asset type"),
         limit: z.number().default(10).describe("Max results (1-20)"),
@@ -110,7 +109,7 @@ Requires authentication: run 'npx summer-engine login' first.`, {
                 content: [
                     {
                         type: "text",
-                        text: JSON.stringify({ error: result.error, message: result.message, plan: result.plan }, null, 2),
+                        text: JSON.stringify({ error: result.error, message: result.message }, null, 2),
                     },
                 ],
                 isError: true,

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

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { withEngine } from "./with-engine.js";
+import { shapeEngineLogResponse } from "../../lib/log-filters.js";
 export function registerDebugTools(server) {
     server.tool("summer_get_diagnostics", `Quick overview of all errors and warnings from both the editor console and the runtime debugger. Returns error counts and a guidance message.
 
@@ -10,27 +11,49 @@ Typical workflow after making changes:
 2. If errors: summer_get_console or summer_get_debugger_errors for details
 3. Fix the issues
 4. summer_get_diagnostics again to verify`, {}, async () => withEngine(async (client) => client.getDiagnostics()));
-    server.tool("summer_get_console", "Read recent messages from the editor's Output panel. Shows print statements, warnings, and errors from both the editor and scripts. Use after summer_get_diagnostics indicates console issues.", {
-        max_lines: z.number().optional().default(100).describe("Max lines to return (default 100)"),
+    server.tool("summer_get_console", `Read recent messages from the editor's Output panel.
+
+Output is post-processed for token economy: consecutive identical messages collapse into one entry with a "(×N)" count suffix, and the response carries a "_filter" summary so you can see what was hidden. Use errors_only=true (default) to drop info/std noise; use raw=true to bypass all shaping.
+
+Use after summer_get_diagnostics indicates console issues.`, {
+        max_lines: z.number().optional().default(100).describe("Max lines to return after dedupe (default 100)"),
         filter: z.string().optional().describe("Only return lines containing this string"),
-        type: z.enum(["error", "warning", "std", "editor"]).optional().describe("Filter by message type"),
-    }, async ({ max_lines, filter, type }) => withEngine(async (client) => {
+        type: z.enum(["error", "warning", "std", "editor"]).optional().describe("Filter by message type at the engine level"),
+        errors_only: z.boolean().optional().default(true).describe("Drop info/std noise, keep errors and warnings (default true)"),
+        strict_errors: z.boolean().optional().default(false).describe("Drop warnings too — return errors only"),
+        raw: z.boolean().optional().default(false).describe("Bypass dedupe and level filtering — return engine output verbatim"),
+    }, async ({ max_lines, filter, type, errors_only, strict_errors, raw }) => withEngine(async (client) => {
         const op = { op: "GetConsoleOutput", max_lines };
         if (filter)
             op.filter = filter;
         if (type)
             op.type = type;
-        return client.executeOps([op]);
+        const engineResult = await client.executeOps([op]);
+        if (raw)
+            return engineResult;
+        const { result } = shapeEngineLogResponse(engineResult, {
+            errorsOnly: errors_only,
+            errorsOnlyStrict: strict_errors,
+            maxEntries: max_lines,
+        });
+        return result;
     }));
     server.tool("summer_clear_console", "Clear the editor's Output panel. Useful before running the game to get a clean slate for error checking.", {}, async () => withEngine(async (client) => client.executeOps([{ op: "ClearConsoleOutput" }])));
-    server.tool("summer_get_debugger_errors", "Read runtime errors and warnings from the debugger. These are errors that occur while the game is running (null references, missing nodes, physics errors). Different from console output — these come from the debugger, not print statements.", {
-        max_errors: z.number().optional().default(50).describe("Max errors to return"),
+    server.tool("summer_get_debugger_errors", `Read runtime errors and warnings from the debugger. These are errors that occur while the game is running (null references, missing nodes, physics errors). Different from console output — these come from the debugger, not print statements.
+
+Output is deduped: identical errors firing every frame collapse into one entry with a "(×N)" count suffix. A "_filter" summary tells you exactly what was collapsed or truncated. Use raw=true to bypass shaping when you really need every entry.`, {
+        max_errors: z.number().optional().default(50).describe("Max errors to return after dedupe"),
         include_stack: z.boolean().optional().describe("Include stack traces for each error"),
-    }, async ({ max_errors, include_stack }) => withEngine(async (client) => {
+        raw: z.boolean().optional().default(false).describe("Bypass dedupe — return engine output verbatim"),
+    }, async ({ max_errors, include_stack, raw }) => withEngine(async (client) => {
         const op = { op: "GetDebuggerErrors", max_errors };
         if (include_stack !== undefined)
             op.include_stack = include_stack;
-        return client.executeOps([op]);
+        const engineResult = await client.executeOps([op]);
+        if (raw)
+            return engineResult;
+        const { result } = shapeEngineLogResponse(engineResult, { maxEntries: max_errors });
+        return result;
     }));
     server.tool("summer_play", `Start running the game in the engine. The game runs inside Summer Engine's viewport.
 

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

@@ -273,6 +273,20 @@ Available kinds:
   - "image-to-3d" — From your own image. Requires 'imageUrl'.
   - "texture" — Generate textures for a model. Requires 'imageUrl'.
 
+Optional rig pass (image-to-3d only):
+  Set options.rig = true to add an auto-rig pass via Meshy v6. The result
+  job (poll via summer_check_job) will include rigAssetId — the asset ID
+  of the rigged glb. Use that rigAssetId with summer_generate_motion to
+  add animation clips. Adds ~$0.30 and ~60s to the job.
+
+Example:
+  summer_generate_3d({
+    kind: "image-to-3d",
+    imageUrl: "https://...",
+    options: { rig: true }
+  })
+  // Returns jobId; poll until result includes { assetId, rigAssetId }.
+
 By default, waits for completion (up to 5 min) and returns the result directly.
 Set wait=false to get the jobId immediately and poll manually with summer_check_job.
 
@@ -419,4 +433,91 @@ Requires authentication: run 'npx summer-engine login' first.`, {
             return errorResult(`Job status check failed: ${msg}`);
         }
     });
+    // ========================================================================
+    // summer_generate_motion
+    //
+    // NOTE (2026-05-10): only the "meshy-library" backend is exposed today.
+    // The "hunyuan-custom" path exists in the Studio route but has not been
+    // tested end-to-end on a user's rig (Hunyuan returns a generic skeleton
+    // FBX that isn't retargeted onto the caller's character). The schema and
+    // call are kept commented-out below — re-enable by restoring the wider
+    // zod enum, the prompt/durationSeconds params, the validation branch, and
+    // the relevant description lines once the path is verified.
+    // ========================================================================
+    server.tool("summer_generate_motion", `Generate an animation clip for a Meshy-rigged humanoid character via Summer Engine Studio.
+
+Backend:
+  - "meshy-library" — picks a clip from a curated mocap set by name (idle, walk,
+    run, attack_sword, jump, ~70 standard names). Fast (~30s), cheap (~$0.10),
+    real mocap quality.
+
+Requires a Meshy-rigged humanoid as the target. The 'rigAssetId' must come from
+a prior summer_generate_3d call with options.rig=true.
+
+By default, waits for completion (up to 5 min) and returns the result directly.
+Set wait=false to get the jobId immediately and poll manually with summer_check_job.
+
+Common motion names:
+  Locomotion: idle, idle_alert, idle_combat, walk, walk_back, run, sprint,
+              crouch_idle, crouch_walk, jump, jump_loop, jump_land
+  Combat: attack_sword, attack_punch, attack_kick, attack_bow, attack_cast,
+          block, dodge_left, dodge_right, hit_react, death
+  Social: wave, dance, sit_idle
+
+Cost: ~$0.10 per clip. Confirm with user before spending.
+
+Custom prompt-driven motion is on the roadmap; not yet shipped. For one-off
+signature moves not on the curated list, fall back to hand-authoring in the
+Godot editor or importing from Mixamo.
+
+Requires authentication: run 'npx summer-engine login' first.`, {
+        rigAssetId: z
+            .string()
+            .describe("Asset ID of a rigged character (from summer_generate_3d with options.rig=true)"),
+        backend: z
+            .enum(["meshy-library"])
+            .default("meshy-library")
+            .describe("Backend: meshy-library (only option today)"),
+        motionName: z
+            .string()
+            .describe("Curated motion name: walk, run, attack_sword, idle, jump, etc."),
+        // prompt + durationSeconds reserved for the hunyuan-custom backend (not
+        // shipped yet — see header comment).
+        wait: z
+            .boolean()
+            .default(true)
+            .describe("Wait for completion (default true, up to 5 min). Set false to get jobId immediately."),
+        options: z
+            .record(z.any())
+            .optional()
+            .describe("Backend-specific passthrough"),
+    }, async ({ rigAssetId, backend, motionName, wait, options }) => {
+        // Client-side validation
+        if (!motionName) {
+            return errorResult("motionName is required (e.g. 'walk', 'run', 'attack_sword'). See the tool description for the curated list.");
+        }
+        const body = {
+            rigAssetId,
+            backend,
+            motionName,
+            options,
+        };
+        const result = await mcpGenerate("/api/mcp/generate/motion", body);
+        if (result.error) {
+            return errorResult(result.error, result.data);
+        }
+        const jobId = result.data?.jobId;
+        if (!wait || !jobId) {
+            return successResult(result.data);
+        }
+        const pollResult = await pollJob(jobId);
+        if (pollResult.error) {
+            return errorResult(pollResult.error, { ...pollResult.data, jobId });
+        }
+        return successResult({
+            ...pollResult.data,
+            jobId,
+            message: "Motion generation complete. animationAssetId is in result.",
+        });
+    });
 }

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

@@ -1,4 +1,5 @@
 import { getClient, resetClient } from "../server.js";
+import { recordMcpSession } from "../../lib/telemetry.js";
 function extractOpError(result) {
     if (!result || typeof result !== "object")
         return null;
@@ -24,6 +25,9 @@ function buildActionHint(message) {
     return null;
 }
 export async function withEngine(fn) {
+    // Best-effort, fire-and-forget: count this MCP session as DAU for attribution.
+    // No await, no throw, no quota gating.
+    recordMcpSession();
     try {
         const client = await getClient();
         const result = await fn(client);

package/gemini-extension.json

@@ -1,7 +1,7 @@
 {
   "name": "summer",
-  "version": "1.4.0",
-  "description": "AI game-dev studio for Godot: MCP bridge to the local Summer Engine plus a context primer that teaches Gemini the 19 Summer skill names. Use with the npm CLI for skill files on disk.",
+  "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.",
   "contextFileName": "GEMINI.md",
   "mcpServers": {
     "summer-engine": {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "summer-engine",
-  "version": "1.5.0",
-  "description": "CLI and MCP tools for Summer Engine — the AI-native game engine",
+  "version": "2.2.0",
+  "description": "Summer — superpowers for AI game dev. CLI, skills, and MCP tools for Summer Engine.",
   "keywords": [
     "game-engine",
     "godot",
@@ -14,11 +14,12 @@
   "homepage": "https://summerengine.com",
   "repository": {
     "type": "git",
-    "url": "https://github.com/SummerEngine/summer-engine-cli"
+    "url": "https://github.com/SummerEngine/summer"
   },
   "license": "MIT",
   "author": "Summer Engine <founders@summerengine.com>",
   "type": "module",
+  "main": ".opencode/plugins/summer.js",
   "bin": {
     "summer": "./dist/bin/summer.js"
   },
@@ -26,16 +27,21 @@
     "dist/",
     "skills/",
     "hooks/",
+    "assets/",
+    "_persona/",
     ".claude-plugin/",
     ".cursor-plugin/",
     ".codex-plugin/",
+    ".factory-plugin/",
     ".opencode/",
     "gemini-extension.json",
-    "marketplace.json",
     ".mcp.json",
     "README.md",
     "LICENSE",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "AGENTS.md",
+    "GEMINI.md",
+    "CLAUDE.md"
   ],
   "scripts": {
     "build": "tsc",

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

@@ -0,0 +1,196 @@
+---
+name: character-portrait
+description: Use when generating a single, polished bust/portrait of a character for dialogue UI, character-select screens, lore cards, or codex entries. One character, locked composition, VN-style. Trigger on "character portrait", "dialogue portrait", "VN portrait", "character bust", "headshot", "character select image", "lore card art".
+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/portraits/**", "ui/portraits/**"]
+---
+
+# character-portrait — Locked Bust for Dialogue UI
+
+This skill produces ONE polished character portrait — bust or shoulders-up framing, neutral or stylized background, designed to drop into a dialogue UI, character-select screen, or lore card. It is the **opposite** of `summer:2d-assets/concept-art`: concept art explores; this skill commits.
+
+The single biggest failure mode is **inconsistency across a cast**. Generating five party members one at a time without a locked anchor produces five images that look like they're from five different games — different lighting, different angle, different palette, different rendering style. This skill makes you write a **locked anchor suffix** the first time and re-use it verbatim for every subsequent portrait.
+
+If the user is still exploring the look, this is the wrong skill — route to `summer:2d-assets/concept-art` first, lock a direction, then come back here. The `summer:asset-pipeline/asset-strategy` meta-router asks **"Quick check — exploring the look (3-4 variants for art direction) or generating a final character portrait for dialogue UI?"** to disambiguate.
+
+## When to use
+
+- "Generate a portrait for the merchant NPC."
+- "I need a character-select image for the four playable heroes."
+- "Make a lore-card image of the king."
+- "Add a VN-style dialogue portrait for Aria."
+- The cast is locked and the visual direction is locked; you're producing finals.
+
+## When NOT to use
+
+- The user is still exploring → `summer:2d-assets/concept-art`.
+- The user wants pixel art → `summer:2d-assets/pixel-art`.
+- The user wants a full-body 3D model → `summer:asset-pipeline/asset-strategy`.
+- The user wants 4+ animated expressions of the same character — generate one base portrait here, then use img2img with the base as `referenceImageUrl` for each expression.
+
+## Steps
+
+### 1. Read or establish the locked anchor
+
+Check `.summer/portrait-anchor.md` first.
+
+```
+Read .summer/portrait-anchor.md
+```
+
+If it doesn't exist, this is the first portrait in the cast — you must define the anchor now. Ask the user (or infer from `.summer/GameSoul.md`):
+
+- **Framing:** bust (chest up) or shoulders-up?
+- **Angle:** straight-on, three-quarter left, three-quarter right?
+- **Lighting:** soft front, dramatic side, rim-lit, golden-hour?
+- **Background:** flat color, soft gradient, painterly blur, in-world environment?
+- **Rendering style:** painterly, anime, semi-realistic, line-art-with-flat-color?
+
+Write the anchor to `.summer/portrait-anchor.md`:
+
+```
+## Portrait anchor (re-use verbatim for every cast member)
+
+framing: bust, shoulders to crown of head visible
+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
+```
+
+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" })
+```
+
+Reuse beats regenerate. If the user wants to iterate on an existing one, pull its URL and pass it as `referenceImageUrl` for img2img.
+
+### 3. Build the prompt — character + anchor
+
+Pattern:
+
+```
+<character description>. <anchor framing/angle/lighting/background/style>
+```
+
+The character description should include: identity (age, build, hair, distinctive features), expression, costume/equipment, any signature prop. Keep it under 60 words including the anchor.
+
+### 4. Confirm and call
+
+> Generating Aria the witch portrait — 1 image, ~$0.02, model nano-banana-2, anchor locked from `.summer/portrait-anchor.md`. OK?
+
+```
+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"` because the anchor's "semi-realistic painterly" already specifies style; the preset would fight it.
+
+### 5. Import and wire into UI
+
+```
+summer_import_from_url(
+  url="<fileUrl from generation>",
+  path="res://ui/portraits/aria.png"
+)
+```
+
+For dialogue UI nodes, wire the texture into a `TextureRect`:
+
+```
+summer_set_resource_property(
+  nodePath="/root/UI/DialogueBox/PortraitRect",
+  resourceProperty="texture",
+  value="res://ui/portraits/aria.png"
+)
+```
+
+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
+
+If the user wants the portrait tweaked ("smaller smile", "darker robes"), use img2img with the existing image as `referenceImageUrl`. Preserves identity and lighting.
+
+```
+summer_generate_image(
+  prompt="<original prompt> with a smaller, more subtle smile",
+  referenceImageUrl="<previous fileUrl>",
+  model="nano-banana-2",
+  style="none"
+)
+```
+
+## Prompt patterns
+
+| Goal | Prompt skeleton (subject part only — append anchor verbatim) | Why |
+|---|---|---|
+| Generic NPC | `<name>, <age> <build>, <hair>, <eyes>, <expression>, wearing <costume>` | Identity-first; no scene context |
+| Hero / protagonist | `<name>, <age> <build>, <hair>, <distinctive feature>, confident <expression>, wearing <signature outfit>, holding <signature prop>` | Adds prop for memorability |
+| Antagonist | `<name>, <imposing detail>, <unsettling expression>, wearing <costume with menacing detail>, <signature scar/mark>` | Antagonists need visual asymmetry |
+| Lore card / king | `<name>, <age>, regal <expression>, wearing <ornate detail>, <crown/insignia>, formal portrait pose` | Formal pose overrides anchor's three-quarter |
+| Expression variant | `<previous prompt> with <new expression: angry / surprised / sad / laughing>` + `referenceImageUrl: <base portrait>` | img2img preserves identity |
+| Younger / older variant | `<character> as a <child / elder>` + `referenceImageUrl: <base>` | For flashback / time-skip portraits |
+
+### Bad prompts (and why)
+
+| Bad | Failure mode |
+|---|---|
+| `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. |
+| `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
+
+- **No anchor file.** Every cast member generated ad-hoc looks unrelated. Define the anchor on portrait #1, re-use for the rest of the cast.
+- **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.
+
+## Edge cases
+
+- **Character has a non-human silhouette (lizardfolk, demon, robot).** The anchor still applies — framing, lighting, background, rendering style. Only the subject description changes. Verify the model can hold the silhouette under "bust framing" — some models default to humanoid.
+- **Player wants to swap costumes mid-game.** Generate one base portrait per costume (`aria_traveler.png`, `aria_robes.png`, `aria_armored.png`) and switch by index. Use img2img from the base for consistency.
+- **Cast of 12+ characters.** Anchor discipline gets harder as fatigue sets in. Print the anchor as a header in your generation script and don't write any prompt without it.
+- **User wants the portrait to "read at small size" (32×32 in a portrait list).** That's pixel-art territory; route to `summer:2d-assets/pixel-art`.
+
+## Fallback (no MCP)
+
+Print the prompt and the call:
+
+```
+summer_generate_image(prompt="<character + anchor>", model="nano-banana-2", style="none", options={ image_size: "portrait_4_3" })
+```
+
+Tell the user to run via the Summer dashboard, then `summer_import_from_url` the result to `res://ui/portraits/<name>.png`.
+
+## Handoff
+
+After the portrait is wired:
+
+- **More cast members** → re-invoke this skill with the same anchor. Don't redefine.
+- **Expression variants** → re-invoke with `referenceImageUrl` set to the base portrait.
+- **Pixel-art version of the same character** → `summer:2d-assets/pixel-art`.
+- **3D model of the same character** → `summer:asset-pipeline/asset-strategy` (the portrait is NOT a usable 3D reference; generate a separate T-pose).
+- **Dialogue system wiring** → `summer:scene-composition` for the UI hierarchy.
+
+## See also
+
+- `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.