@playcraft/cli 0.0.40 → 0.0.42

package/project-template/.claude/agents/refs/designer-color-audio-recipes.md

@@ -0,0 +1,153 @@
+> 本文件是按游戏类型的配色方案和音频情绪弧设计参数参考。核心心理设计原则见 `playcraft-ad-psychology` skill。
+
+# 按游戏类型配色方案
+
+## 休闲消除（Match-3 / 泡泡射击）
+
+```
+主色（60%）：柔和中性背景（奶油色 #FFF8E7 / 浅蓝 #E8F4FD / 薰衣草 #F0E8FF）
+辅色（30%）：高饱和暖色游戏元素（橙 #FF6B35、黄 #FFD700、粉 #FF69B4、绿 #5BE584）
+强调色（10%）：纯金色 CTA #F5A623 或 亮橙 #FF4800
+```
+
+**情感定位**：愉悦、轻松、"下一局会更好"。避免深色和高对比（降低决策压力）。
+
+**代表作参考**：Candy Crush（King）的高饱和糖果色
+
+---
+
+## 策略 / 战争 / 建设
+
+```
+主色（60%）：深色场景背景（深蓝 #0D1B2A / 深绿 #1A2F1A / 暗褐 #2D1B00）
+辅色（30%）：金属质感+金色（铁灰 #4A4A4A、青铜 #8B6914、深红 #8B1A1A）
+强调色（10%）：纯金色 #FFD700 或 亮红 #FF3B30（冲突感）
+```
+
+**情感定位**：权威、力量、"成为最强"。深色背景使金色 CTA 对比最强。
+
+**代表作参考**：Clash of Clans（Supercell）的深色+金色
+
+---
+
+## 益智 / 解谜 / 文字
+
+```
+主色（60%）：冷色中性背景（深蓝紫 #1A1A3E / 浅蓝灰 #F0F4F8 / 白 #FFFFFF）
+辅色（30%）：蓝紫色系游戏元素（钴蓝 #0066CC、紫 #7B4ACA、青 #00B4D8）
+强调色（10%）：鲜绿 #00C851 或 亮黄 #FFCE00（思维活跃感）
+```
+
+**情感定位**：清晰、专注、智慧。冷色调降低情绪噪音，有助于玩家专注于解谜逻辑。
+
+---
+
+## RPG / 奇幻 / 冒险
+
+```
+主色（60%）：神秘背景（深紫 #1A0033 / 夜蓝 #0A0028 / 森林绿 #0D2818）
+辅色（30%）：魔法色彩（紫 #8A2BE2、金 #FFD700、魔法蓝 #4169E1）
+强调色（10%）：火红/橙 #FF4500 或 魔法光 #00FFFF（史诗感）
+```
+
+**情感定位**：神秘、史诗、"踏上冒险"。渐变背景（深色 -> 稍亮）增加空间感和纵深感。
+
+---
+
+# 音频情绪弧设计参数
+
+> 80%+ 的应用内展示以**静音模式**播放——视觉必须独立成立。音频是增强层，不是信息传递主渠道。用 SFX 强化关键交互，而非依赖 BGM 传递情绪。
+
+## BGM：30 秒广告各阶段参数
+
+| 阶段         | 时段   | BPM 范围 | 编排密度               | 乐器推荐               |
+| ------------ | ------ | -------- | ---------------------- | ---------------------- |
+| **Hook**     | 0-3s   | 120-140  | 全层（立即冲击）       | 打击 + 合成铅音 + 低音 |
+| **Tutorial** | 3-10s  | 90-110   | 稀疏（旋律 + 轻打击）  | 木琴/钢片琴 + 轻鼓     |
+| **Gameplay** | 10-25s | 110-135  | 逐层递增（随难度渐进） | 渐进加入贝斯、弦乐     |
+| **EndCard**  | 25-30s | 125-145  | 全层高潮（驱动 CTA）   | 铜管 + 全打击 + 合唱   |
+
+**垂直重编排技术（Vertical Re-orchestration）**：同一段音乐保持相同 BPM / 调号 / 拍号，通过增减轨道层数控制情绪强度，确保阶段切换平滑无割裂感。
+
+```
+情绪强度
+ ▲
+5|      *            /--*  <- EndCard 高潮（全层）
+4|     / \          /
+3|    /   \--------/       <- Gameplay 渐进叠层
+2|   /     Tutorial        <- 降速 / 稀疏编排
+1|  /  ^Hook（立即全层）
+ └──────────────────────────> 时间(秒)
+  0    3      10    18  24  30
+```
+
+**按游戏类型的 BPM 基准**：
+
+| 游戏类型 | 休闲/益智 | RPG/模拟 | 跑酷/平台 | 动作/射击 |
+| -------- | --------- | -------- | --------- | --------- |
+| BPM 区间 | 90-115    | 100-125  | 120-150   | 130-160   |
+
+**Designer 生成 BGM 时的组合写法**：
+
+```bash
+# 示例：休闲消除游戏，Tutorial 阶段风格
+playcraft tools generate-bgm \
+  --prompt "casual match-3 puzzle game, tutorial section, gentle and encouraging, marimba and light percussion, simple melody" \
+  --bpm 100
+
+# EndCard 高潮风格（同一游戏，BPM 提升，编排加密）
+playcraft tools generate-bgm \
+  --prompt "casual match-3 puzzle game, victory climax, full orchestra, triumphant but brief, drives install action" \
+  --bpm 130
+```
+
+> **实践建议**：生成一条 30 秒完整 BGM（以 Gameplay BPM 为基准），再用 `playcraft audio trim` 裁剪出 Hook 段和 EndCard 段。比生成多条独立 BGM 更能保证风格连贯。
+
+---
+
+## SFX：各游戏事件时长标准
+
+| 游戏事件           | 建议时长   | 设计要点                   |
+| ------------------ | ---------- | -------------------------- |
+| UI 点击 / 按钮确认 | 50-100ms   | 轻快无干扰，不抢注意力     |
+| 卡牌翻转           | 100-200ms  | 纸张/塑料质感，干脆利落    |
+| 金币单个收集       | 80-150ms   | 金属叮当，高频悦耳         |
+| Match-3 单次消除   | 150-300ms  | 清脆短促，满足感           |
+| Match-3 连锁 Combo | 300-500ms  | 音阶递增，每次 combo +50ms |
+| 批量奖励 / 金币雨  | 300-800ms  | 叮当序列 + 收尾音          |
+| CTA 按钮弹出       | 200-400ms  | 吸引注意力但不惊吓         |
+| 关卡完成           | 500-1200ms | 凯旋感，可含短旋律片段     |
+| 失败 / 重试提示    | 300-600ms  | 下行音阶，不过度沮丧       |
+
+**SFX Prompt 对应写法**（结合 `playcraft-audio-generation` Skill 使用）：
+
+```bash
+# Match-3 消除 SFX
+playcraft tools generate-sfx \
+  --prompt "satisfying match-3 tile elimination sound, crisp pop with sparkle tail, game UI, clean no reverb" \
+  --duration 0.25
+
+# 连锁 Combo（第 2 连）
+playcraft tools generate-sfx \
+  --prompt "combo chain sound, ascending tone, brighter and higher than previous, game feedback" \
+  --duration 0.4
+
+# CTA 弹出
+playcraft tools generate-sfx \
+  --prompt "call-to-action button appear sound, attention-grabbing chime, positive and inviting, mobile game UI" \
+  --duration 0.3
+```
+
+---
+
+## 音频-视觉对齐检查清单
+
+Designer 完成音频生成后，对照以下清单验证情绪一致性：
+
+- [ ] Hook BGM 第一个节拍 <= 0.5s 内出现（不要淡入铺垫）
+- [ ] Tutorial 段 BPM 比 Gameplay 低 15-30（有感知上的降速）
+- [ ] EndCard 音量/编排密度是全广告中最高点
+- [ ] 每个关键交互（消除/收集/胜利）都有配套 SFX
+- [ ] BGM 经过 `playcraft audio loop --crossfade 1.0` 处理，无缝循环
+- [ ] SFX 文件 <= 50KB（`playcraft audio info` 验证）
+- [ ] BGM 文件 <= 300KB（压缩后）

package/project-template/.claude/agents/refs/designer-deliverable-spec.md

@@ -0,0 +1,191 @@
+# Designer — Deliverable spec (designer-handoff-v2)
+
+> **When to read**: Before generating Master Composite, ASR, audio, or digit strip. Cross-reference `playcraft-storyboard`, `playcraft-asset-state-sheet`, `playcraft-text-rendering`, `playcraft-image-generation`, and `refs/designer-handoff-v2-checklist.md`.
+
+## Resolution Strategy
+
+AI image models support up to **4K output** (~4096px per side). Individual game assets only need **~720p**. Pack multiple assets into one generation for style consistency and fewer API calls. TA achieves per-asset dimensions via crop/resize from MC/ASR.
+
+All image generation MUST use maximum supported resolution.
+
+## Text-as-Image Strategy
+
+All visible text is image assets — **zero font files**. Static text is baked into the MC concept panel; dynamic numbers use a Digit Sprite Strip.
+
+> **Invoke `playcraft-text-rendering`** for static-text extraction (TA default) and digit strip (Designer Phase 2).
+
+### Static text (default)
+
+| Step                           | Role                                        |
+| ------------------------------ | ------------------------------------------- |
+| Bake into MC                   | Designer (concept panel)                    |
+| Extract to `layout-spec` paths | TA (`crop` / `segment`)                     |
+| Extract fails                  | ICP → Designer **one isolated PNG** per row |
+
+### Background (default)
+
+| Step                                  | Role                                                             |
+| ------------------------------------- | ---------------------------------------------------------------- |
+| Extract from MC concept panel         | TA → `layout-spec` bg path                                       |
+| 2.5D / hero bg needs dedicated sample | PM marks VisualAtom `assignTo: Designer` → ICP isolated PNG only |
+
+## Phase 1 Deliverables
+
+Gate #2a: **one MC per option** + Experience Flow text. Gate #2b (after `selectedMcOption`): **ASR dual sheets** + **Handoff Pack** (below).
+
+| #   | Deliverable                       | Format | Spec                                                       |
+| --- | --------------------------------- | ------ | ---------------------------------------------------------- |
+| 1   | **Master Composite**              | PNG 4K | 5 panels: concept + 4 storyboard scenes                    |
+| 2a  | **UI State Reference Sheet**      | PNG 4K | UI/HUD per interaction state                               |
+| 2b  | **Element State Reference Sheet** | PNG 4K | Gameplay elements per event/special state                  |
+| 3   | **Experience Flow Design**        | Text   | `style-exploration.md`                                     |
+| 4   | **Gate #2b Handoff Pack**         | Text   | `designer-log.md` + Motion Notes in `style-exploration.md` |
+
+> **ASR** = authoring-time reference sprite sheets. **Not** runtime `.webp` + `.json` atlases (TA in `production`).
+
+Every generation outputs a sidecar `.json` (prompt + parameters).
+
+---
+
+### Deliverable 1: Master Composite
+
+> **Skills**: `playcraft-storyboard` + `refs/designer-master-composite-recipes.md`
+
+| #   | Panel              | Content                                              |
+| --- | ------------------ | ---------------------------------------------------- |
+| 1   | Main Gameplay      | Full game shot: all element types + static text + UI |
+| 2   | Key Hook           | 0–3s highlight                                       |
+| 3   | Onboarding HUD     | Tutorial + finger                                    |
+| 4   | End Card           | Win + Install CTA                                    |
+| 5   | CTA Always Visible | In-game CTA persistent                               |
+
+Paths: `assets/images/storyboard/master_composite_option_[A|B|C].png`
+
+**MC options count**: ≥2 before Gate #2a (see option table in prior spec — 2 or 3 by clarity).
+
+---
+
+### Deliverable 2: ASR
+
+> **Skill**: `playcraft-asset-state-sheet`
+
+Only after `selectedMcOption` is set. `--reference-image` = confirmed MC.
+
+```
+assets/images/reference/ui_state_sheet_[X].png
+assets/images/reference/element_state_sheet_[X].png
+```
+
+---
+
+### Gate #2b Handoff Pack (mandatory before `#2b` STOP)
+
+> **Checklist**: `refs/designer-handoff-v2-checklist.md`
+
+#### 1. ASR Coverage Matrix (`logs/designer-log.md`)
+
+One row per contract item from `layout-spec.md`:
+
+| Contract id                     | Type   | ASR sheet    | Grid    | State(s)     | TA extends? |
+| ------------------------------- | ------ | ------------ | ------- | ------------ | ----------- |
+| `elementId` from assetMapping   | visual | ui / element | row,col | e.g. default | yes/no      |
+| `staticTextId` from Text Assets | text   | ui / MC crop | —       | baked        | yes/no      |
+
+**100% rule**: every `elementId` in `assetMapping` and every static text id must have a row. Empty ASR slot → `TA extends? = yes` + note in Style Intent Notes.
+
+#### 2. Palette Locked (`logs/designer-log.md`)
+
+- 6–10 hex swatches sampled from confirmed MC (background, accent, CTA, key elements).
+- One line: **delta vs `layout-spec` Color Palette** (match / PM update needed).
+
+#### 3. Motion Notes (`docs/style-exploration.md`)
+
+Per transition (Hook→Tutorial, Tutorial→Gameplay, Gameplay→EndCard):
+
+| Field            | Example                                      |
+| ---------------- | -------------------------------------------- |
+| Transition type  | fade / zoom / swipe / burst                  |
+| Duration band    | ~200ms / ~500ms / ~1s                        |
+| Audio cue tie-in | optional ref to Experience Flow audio rhythm |
+
+No per-frame animation assets — VFX/Animation atoms remain TA.
+
+#### 4. Style Intent + Anti-Pattern Notes
+
+Existing `designer-log` sections — required for TA Step 0c.
+
+---
+
+### Phase 1 exception: True 3D
+
+When `design-brief` dimension = True 3D, Designer also delivers (Phase 1, same Gate #2b):
+
+- 2D reference texture PNG at path noted in `designer-log` (see `refs/designer-dimension-axis.md`).
+- TA runs `generate-3d`; Designer does **not** output GLB.
+
+---
+
+## Phase 2 Deliverables — Audio + Digit + Atom status
+
+**Designer does not batch-export visual samples at `assetMapping` paths in v2.** Visual baseline = Phase 1 MC + ASR.
+
+### Phase 2 Skill Preflight (mandatory, before production)
+
+Before generating any audio or digit strip, read relevant Skills:
+
+```bash
+cat .claude/skills/playcraft-audio-generation/SKILL.md   # BGM/SFX generation patterns
+cat .claude/skills/playcraft-text-rendering/SKILL.md     # Digit strip green/blue screen strategy
+cat .claude/skills/playcraft-image-generation/SKILL.md   # §3 background decision tree (for digit)
+```
+
+**mediaGroups check** (mandatory): Read `atom-plan.json` → `skillsMatch.mediaGroups` for any `.aiaudio` matches. If matched → `playcraft skills link --atom <atomId>` → verify quality/mood → mark `status: done`. Skip only when mood/style mismatch (document in `dagRevisions`).
+
+Record in `logs/designer-log.md` § Skill Preflight:
+
+```markdown
+## Skill Preflight
+
+| Skill                      | 已读 | 关键决策摘要                                         |
+| -------------------------- | ---- | ---------------------------------------------------- |
+| playcraft-audio-generation | ✅   | BGM=ambient lo-fi; SFX 用 prompt 模板                |
+| playcraft-text-rendering   | ✅   | 数字用蓝幕；描边保护                                 |
+| mediaGroups (audio)        | ✅   | bg_music.aiaudio linked; click_sfx 需重做 (风格不符) |
+```
+
+| #   | Deliverable            | Format | Spec                                  |
+| --- | ---------------------- | ------ | ------------------------------------- |
+| 1   | **BGM**                | MP3    | Mood matches locked MC                |
+| 2   | **SFX**                | MP3    | One per interaction in `assetMapping` |
+| 3   | **Digit sprite strip** | PNG    | `layout-spec` `textAssets.digitStrip` |
+| 4   | **VisualAtom status**  | —      | See below                             |
+
+### VisualAtom rules (`atom-plan.json` → `atoms[]`)
+
+For each `assignTo: Designer` VisualAtom:
+
+| Condition                           | `status`  | `actualOutput`                                                                      |
+| ----------------------------------- | --------- | ----------------------------------------------------------------------------------- |
+| Type covered in ASR Coverage Matrix | `done`    | `ASR:ui_state_sheet_[X]:R{row}C{col}` or `ASR:element_state_sheet_[X]:R{row}C{col}` |
+| Not covered; ICP gap                | `blocked` | ICP id + path when file delivered                                                   |
+| ICP supplementary PNG delivered     | `done`    | file path                                                                           |
+
+**Forbidden**: mark VisualAtom `done` without ASR row or supplementary file.
+
+Run **`playcraft-style-qa` §1** only for **ICP supplementary** image files (not for ASR sheets themselves).
+
+### TA ownership in Phase 2 (not Designer)
+
+- Static text extraction → contract paths
+- Background webp
+- VisualAtom completions, sprite sheets, 3D, VFX, atlases
+
+### Bundle Structure (audio)
+
+```
+assets/bundles/<atomId>.aiaudio/
+  ├── manifest.json
+  └── <filename>.mp3
+```
+
+Supplementary images (ICP only): `.aiimage/` bundle format.

package/project-template/.claude/agents/refs/designer-dimension-axis.md

@@ -0,0 +1,27 @@
+# Designer Dimension Axis Workflow
+
+> Read in Phase 1 after confirming Dimension Axis from `docs/design-brief.md`. **designer-handoff-v2**: visual baseline = MC + ASR (not scattered sample PNGs). TA handles mass production.
+
+## Flat 2D (Standard)
+
+- **MC** concept panel shows all element types + UI + static text.
+- **ASR** element sheet: 2–3 states per type (idle / selected / matched).
+- TA: bg extract, completions, atlases, VFX.
+
+## 2.5D Visual (Depth Layers)
+
+- MC concept panel: perspective scene + layered elements.
+- ASR: angled sprites in element sheet; note depth layers in Style Intent Notes.
+- Background: default **TA extract from MC**; dedicated bg sample only if PM atom `assignTo: Designer` via ICP.
+
+## Isometric
+
+- ASR element sheet: representative isometric tiles (2–3 states).
+- Optional: `playcraft tools search-image` for reference.
+- TA: remaining tiles, atlas, animation.
+
+## True 3D
+
+- Designer does **not** output GLB.
+- Phase 1 Gate #2b: 2D reference texture PNG (path in `designer-log`) per `designer-deliverable-spec.md` § Phase 1 exception.
+- TA: `generate-3d`, GLB, flip sprites.

package/project-template/.claude/agents/refs/designer-handoff-v2-checklist.md

@@ -0,0 +1,68 @@
+# Designer Handoff v2 — Gate #2b checklist
+
+> Read at **Step 5** of `designer-style-exploration-flow.md` before `gates.#2b = pending` STOP.
+
+## Prerequisites
+
+- [ ] `workflowSpecVersion` = `designer-handoff-v2` in `project-state.md` (or migrating per `workflow-changelog.md`)
+- [ ] `selectedMcOption` set (Gate #2a passed)
+- [ ] MC path: `assets/images/storyboard/master_composite_option_[X].png`
+- [ ] ASR paths exist and pass zero-overlap visual check
+
+## 1. ASR Coverage Matrix (100%)
+
+In `logs/designer-log.md` § ASR Coverage Matrix:
+
+1. List every `elementId` from `layout-spec.md` § Asset Mapping (and atlas `frameId` groups count as one row per logical element).
+2. List every static text `id` from § Text Assets → Static Text.
+3. For each row: `ASR sheet` = `ui` | `element` | `MC-crop` | `ICP-pending`.
+4. `TA extends?` = `no` only when ASR shows final representative state; else `yes`.
+
+**Stop rule**: any row missing → do not set `#2b` pending.
+
+## 2. Palette Locked
+
+```markdown
+## Palette Locked (from MC option [X])
+
+| Role       | Hex       | Notes |
+| ---------- | --------- | ----- |
+| bg_primary | #**\_\_** |       |
+| accent     | #**\_\_** |       |
+| cta        | #**\_\_** |       |
+| element_1  | #**\_\_** |       |
+
+**Delta vs layout-spec**: match | PM update: <one line>
+```
+
+## 3. Motion Notes
+
+In `docs/style-exploration.md` under confirmed option:
+
+| Transition          | Type | Duration | Notes |
+| ------------------- | ---- | -------- | ----- |
+| Hook → Tutorial     |      |          |       |
+| Tutorial → Gameplay |      |          |       |
+| Gameplay → End Card |      |          |       |
+
+## 4. Phase 2 VisualAtom decision tree
+
+```
+For each atom-plan row where assignTo = Designer:
+├─ VisualAtom + covered in Coverage Matrix?
+│   └─ yes → status=done, actualOutput=ASR:...
+├─ AudioAtom?
+│   └─ deliver MP3 at path → done
+├─ Gap / TA extract failed (ICP)?
+│   └─ generate one PNG → done with path, or blocked until answered
+└─ Never: done with only "will extract later"
+```
+
+## 5. Files to verify before STOP
+
+| File                                                  | Contains                                                    |
+| ----------------------------------------------------- | ----------------------------------------------------------- |
+| `docs/style-exploration.md`                           | MC paths, Motion Notes, Experience Flow                     |
+| `logs/designer-log.md`                                | Coverage Matrix, Palette Locked, Style Intent, Anti-Pattern |
+| `assets/images/reference/ui_state_sheet_[X].png`      | exists                                                      |
+| `assets/images/reference/element_state_sheet_[X].png` | exists                                                      |

package/project-template/.claude/agents/refs/designer-master-composite-recipes.md

@@ -0,0 +1,208 @@
+# Master Composite — 游戏类型 Prompt 配方 & 参考
+
+> 本文件供 Designer 在生成 Master Composite 时按需查阅。核心规则见 `playcraft-storyboard` skill。
+
+## 模型策略（MC 专用 — 仅高质量模型）
+
+Master Composite **禁止**使用低档或实验性模型。生成前可运行 `playcraft tools list-image-models` 核对 capability，但 **MC 只允许下表**：
+
+| 允许 `--image-model`           | 典型分配                                        |
+| ------------------------------ | ----------------------------------------------- |
+| **`mulerouter/gpt-image-2`**   | Option A（主推）；Option C 可复用 + 不同 prompt |
+| **`mulerouter/nano-banana-2`** | Option B；或 A/B 各用一模型做画风对比           |
+
+**禁止用于 MC**：`gemini-*`、`flux-*`、`hy-image-*`、`wan*`、`qwen*`、裸 `gpt-image-2`、以及上表以外的任何模型。
+
+> 多方案差异应来自 **prompt / 配色 / 构图**，不是换弱模型。ASR 双板 `--image-model` 须与已选 MC **完全一致**（见 `playcraft-asset-state-sheet` skill）。
+
+### 模型特性速查（仅白名单内）
+
+| 模型                       | 特点                          | 适合                                |
+| -------------------------- | ----------------------------- | ----------------------------------- |
+| `mulerouter/gpt-image-2`   | 细节、光影、复杂 UI、中文元素 | 写实、半写实、精细卡通、麻将/汉字类 |
+| `mulerouter/nano-banana-2` | 色彩、构图、速度快            | 明亮卡通、简洁 UI、快速迭代第二方案 |
+
+> `--reference-image` 只能用于 CAPABILITY 为 `text+image` 或 `image→image` 的模型；白名单内两模型均支持图生图。
+
+---
+
+## 游戏类型 Prompt 配方
+
+以下模板可直接复制修改。所有模板遵循 skill 中的 5 面板并排结构 + 编号标签。
+
+### Match-3 消除游戏
+
+```bash
+playcraft tools generate-image \
+  --prompt "Mobile game UI design sheet, 5 panels side by side in a horizontal row, each panel is a complete portrait-oriented mobile game screenshot for a match-3 puzzle game. Each panel has a numbered label at the top.
+
+Panel 1 '1. Main Gameplay': Complete game screenshot — colorful candy gem grid on [BG_DESCRIPTION], all gem types visible ([TYPE_LIST]), HUD strip showing score and moves counter, 'Play Now' CTA button at bottom. [MASCOT_DESCRIPTION].
+
+Panel 2 '2. Key Hook': Gems exploding in chains, dynamic burst VFX, score [HIGH_SCORE], combo text visible, vivid colors, dramatic moment, high contrast, minimal UI.
+
+Panel 3 '3. Onboarding HUD': Finger tap icon pointing at two matching gems, soft glow highlight on target pair, simplified board, score reset, friendly guidance arrow, speech bubble with hint text.
+
+Panel 4 '4. End Card': Victory celebration — [DARK_BG], '[WIN_TEXT]', treasure chest with rewards, reward amount visible, 'Install Now' CTA button prominent, confetti.
+
+Panel 5 '5. CTA Always Visible': Mid-game screenshot showing normal gameplay in progress, with 'Play Now' CTA button clearly visible at bottom-right during active play, proving CTA is always accessible.
+
+[STYLE_KEYWORDS]. All 5 panels are portrait-oriented mobile screenshots arranged left-to-right. Every panel has complete game UI (HUD bar, score display, buttons). Consistent art style across all panels. Thin vertical dividers between panels. Each panel has its numbered label at the top." \
+  --output assets/images/storyboard/master_composite_option_A.png \
+  --image-model mulerouter/gpt-image-2 \
+  --image-size 4K
+```
+
+---
+
+### 跑酷 / 平台跳跃游戏
+
+```bash
+playcraft tools generate-image \
+  --prompt "Mobile game UI design sheet, 5 panels side by side in a horizontal row, each panel is a complete portrait-oriented mobile game screenshot for an endless runner game. Each panel has a numbered label at the top.
+
+Panel 1 '1. Main Gameplay': Complete game screenshot — character running through [ENVIRONMENT], coin trail ahead, obstacles visible, HUD showing distance and coins collected, 'Play Now' button at bottom.
+
+Panel 2 '2. Key Hook': Character at maximum speed, motion blur, dynamic camera angle, dramatic lighting, speed lines, high contrast, minimal HUD.
+
+Panel 3 '3. Onboarding HUD': Jump arrow icon showing first obstacle, character highlighted with glow, simple environment, clear guidance text bubble.
+
+Panel 4 '4. End Card': Dark background, distance record display, 'Install Now' CTA button prominent, reward chest, achievement badges.
+
+Panel 5 '5. CTA Always Visible': Mid-game screenshot with character dodging obstacles, 'Play Now' button clearly visible at bottom-right during active play.
+
+[STYLE_KEYWORDS]. All 5 panels are portrait-oriented mobile screenshots arranged left-to-right. Every panel has complete game UI. Consistent art style across all panels. Thin vertical dividers. Numbered labels at top." \
+  --output assets/images/storyboard/master_composite_option_A.png \
+  --image-model mulerouter/gpt-image-2 \
+  --image-size 4K
+```
+
+---
+
+### 卡牌 / 麻将游戏
+
+```bash
+playcraft tools generate-image \
+  --prompt "Mobile game UI design sheet, 5 panels side by side in a horizontal row, each panel is a complete portrait-oriented mobile game screenshot for a Mahjong Solitaire game. Each panel has a numbered label at the top.
+
+Panel 1 '1. Main Gameplay': Complete game screenshot — Mahjong tile grid on dark green felt table, tiles with Chinese symbols, cute mascot character, HUD showing score and timer, 'Play Now' button at bottom. Rich warm lighting.
+
+Panel 2 '2. Key Hook': Near-win combo state — high score, combo text with golden sparkles, most tiles matched with golden borders, mascot excited expression, warm amber glow, dramatic tension.
+
+Panel 3 '3. Onboarding HUD': Clean simplified board, finger tap icon pointing at two matching tiles, speech bubble 'Tap matching tiles', score reset, progress indicator, mascot encouraging smile.
+
+Panel 4 '4. End Card': Victory — dark elegant background, '恭喜通关!' text in gold, treasure chest, reward amount with coin icon, 'Install Now' CTA button in contrasting color, golden confetti.
+
+Panel 5 '5. CTA Always Visible': Mid-game screenshot showing active gameplay with tiles on board, score and timer visible, 'Play Now' button clearly visible at bottom-right during play.
+
+Premium casual style, warm amber lighting, traditional Chinese aesthetic with modern UI, glossy tile surfaces. All 5 panels portrait-oriented, left-to-right. Every panel has complete game UI. Consistent art style. Thin vertical dividers. Numbered labels." \
+  --output assets/images/storyboard/master_composite_option_A.png \
+  --image-model mulerouter/gpt-image-2 \
+  --image-size 4K
+```
+
+---
+
+### 射击 / 动作游戏
+
+```bash
+playcraft tools generate-image \
+  --prompt "Mobile game UI design sheet, 5 panels side by side in a horizontal row, each panel is a complete portrait-oriented mobile game screenshot for a casual shooting game. Each panel has a numbered label at the top.
+
+Panel 1 '1. Main Gameplay': Complete game screenshot — player aiming at enemies in [ENVIRONMENT], weapon visible, HUD showing ammo/health/score, 'Play Now' button at bottom.
+
+Panel 2 '2. Key Hook': Target reticle locking on enemy, muzzle flash, dramatic action lighting, high contrast, speed lines, minimal HUD.
+
+Panel 3 '3. Onboarding HUD': Aim crosshair tutorial overlay, slow-motion visual hint, simple enemy highlighted with marker, guidance text.
+
+Panel 4 '4. End Card': Dark background, victory text, loot box with rewards, 'Install Now' CTA button prominent.
+
+Panel 5 '5. CTA Always Visible': Mid-game screenshot with active combat, 'Play Now' button clearly visible at bottom-right during play.
+
+[STYLE_KEYWORDS]. All 5 panels portrait-oriented left-to-right. Every panel has complete game UI. Consistent art style. Thin vertical dividers. Numbered labels at top." \
+  --output assets/images/storyboard/master_composite_option_A.png \
+  --image-model mulerouter/gpt-image-2 \
+  --image-size 4K
+```
+
+---
+
+## 故障恢复
+
+### 问题：模型拒绝生成（content policy）
+
+```bash
+# 移除触发审查的词语，改用间接描述
+# "explosion, fire, destruction" → "dramatic burst effect, particle shower, vivid energy release"
+```
+
+### 问题：面板内容混淆（相邻面板之间内容串了）
+
+```bash
+# 方案 1：强化编号标签
+"Panel 1 '1. Main Gameplay' (leftmost):..., Panel 2 '2. Key Hook' (second from left):..."
+
+# 方案 2：加描述性分隔符
+"5 panels separated by clear vertical white dividers. Each panel has bold numbered header."
+```
+
+### 问题：面板间风格不统一
+
+```bash
+# 强化风格约束词
+# 原始："Consistent art style across all panels."
+# 强化版："All 5 panels MUST use identical art style, color palette, and character design. Same rendering style throughout. All panels depict the SAME game."
+```
+
+### 问题：某帧内容不清晰
+
+发现某帧表达不清晰时，**不必重新生成整张**，而是在 `style-exploration.md` 的 Experience Flow Design 章节补充文字说明。
+
+### 问题：Concept Panel 缺少某些元素类型
+
+```bash
+# 方案 1：在 prompt Panel 1 段明确列出 "all [N] element types visible: [逐个列出]"
+# 方案 2：接受当前 MC，由 ASR 双板补足（ASR 是 TA 的主要提取源）
+```
+
+---
+
+## Reference-Image 与多方案策略
+
+### 首个方案（无 reference）
+
+Master Composite 是 Phase 1 的**第一张生成图**，通常无前序图可作 reference：
+
+```bash
+playcraft tools generate-image \
+  --prompt "<5-panel prompt>" \
+  --output assets/images/storyboard/master_composite_option_A.png \
+  --image-model mulerouter/gpt-image-2 \
+  --image-size 4K
+```
+
+### 后续方案（可选 reference）
+
+后续方案可用已生成的方案 A 作为风格参考：
+
+```bash
+playcraft tools generate-image \
+  --prompt "<方案 B prompt>" \
+  --output assets/images/storyboard/master_composite_option_B.png \
+  --reference-image assets/images/storyboard/master_composite_option_A.png \
+  --image-model mulerouter/nano-banana-2 \
+  --image-size 4K
+```
+
+### 输出命名规范
+
+```
+assets/images/storyboard/master_composite_option_A.png  ← 方案 A
+assets/images/storyboard/master_composite_option_B.png  ← 方案 B
+assets/images/storyboard/master_composite.png           ← Gate #2 确认后复制
+```
+
+Gate #2 确认后：
+
+```bash
+cp assets/images/storyboard/master_composite_option_[X].png assets/images/storyboard/master_composite.png
+```