@playcraft/cli 0.0.44 → 0.0.46

package/project-templates/threejs/.claude/agents/refs/artist-deliverable-spec.md

@@ -0,0 +1,230 @@
+# Artist — Deliverable spec (artist-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 `.claude/agents/refs/artist-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 (Artist Phase 2).
+
+### Static text (default)
+
+| Step                           | Role                                      |
+| ------------------------------ | ----------------------------------------- |
+| Bake into MC                   | Artist (concept panel)                    |
+| Extract to `layout-spec` paths | TA (`crop` / `segment`)                   |
+| Extract fails                  | ICP → Artist **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 | Game Designer routes ICP supplementary art request → isolated PNG only |
+
+## Phase 1 Deliverables — Image production (MC + ASR)
+
+Ring 3 clarify: **one MC per option** + Experience Flow text. Ring 3 build (after `selectedMcOption`): **ASR dual sheets** + **Handoff Pack** (below).
+
+> **Phase 1 scope = images only.** Audio/digit strip is **Phase 2** after ring 3 verify — see § Phase 2 Deliverables.
+
+| #   | 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   | **Ring 3 Handoff Pack**           | Text   | `artist-log.md` + Motion Notes in `style-exploration.md` |
+
+> **ASR** = authoring-time reference sprite sheets. **Not** runtime `.webp` + `.json` atlases (TA in ring 4 build).
+
+Every generation outputs a sidecar `.json` (prompt + parameters).
+
+---
+
+### Deliverable 1: Master Composite
+
+> **Skills**: `playcraft-storyboard` + `.claude/agents/refs/artist-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 ring 3 Ring Gate (see option table in prior spec — 2 or 3 by clarity).
+
+---
+
+### Deliverable 2: ASR
+
+> **Skill**: `playcraft-asset-state-sheet` + `playcraft-image-generation` §3.1 (ASR branch)
+
+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
+# optional when types > 12:
+assets/images/reference/element_state_sheet_[X]_2.png
+```
+
+**ASR whole PNG is opaque by design** — TA crops cells then `remove-background`. Artist must deliver **isolated elements per cell** (no white box / scene inside cells).
+
+#### Three-layer coverage model
+
+| CoverageLayer  | Meaning                             | Matrix columns                              |
+| -------------- | ----------------------------------- | ------------------------------------------- |
+| **on-asr**     | Physical slot on ASR PNG (`R#C#`)   | `ASR sheet` + `Grid`                        |
+| **mc-crop**    | Visible in MC Panel 1, no ASR slot  | `ASR sheet` = `MC-crop` + note Panel region |
+| **ta-extends** | Color variant / extra states for TA | `TA extends? = yes` + Style Intent line     |
+
+**100% Matrix rows** = every `assetMapping` elementId + every static text id has **one row**.  
+**NOT** every row needs a physical ASR slot — use layers above.
+
+**Type representative rule**: each **element type** (from `layout-spec` § Element Type Registry or Matrix `elementType` column) must appear in **on-asr** or **mc-crop** at least once.
+
+Physical slot budget: **8–12 slots per sheet**; overflow → second element sheet or mc-crop + ta-extends.
+
+---
+
+### Ring 3 Handoff Pack (mandatory before ring 3 verify STOP)
+
+> **Checklist**: `.claude/agents/refs/artist-handoff-v2-checklist.md`
+
+#### 1. ASR Coverage Matrix (`logs/artist-log.md`)
+
+One row per contract item from `layout-spec.md`:
+
+| Contract id                     | elementType | Type   | CoverageLayer                 | ASR sheet              | Grid | State(s)     | TA extends? |
+| ------------------------------- | ----------- | ------ | ----------------------------- | ---------------------- | ---- | ------------ | ----------- |
+| `elementId` from assetMapping   | `tile`      | visual | on-asr / mc-crop / ta-extends | ui / element / MC-crop | R1C1 | e.g. default | yes/no      |
+| `staticTextId` from Text Assets | —           | text   | mc-crop or on-asr             | ui / MC-crop           | —    | baked        | yes/no      |
+
+**100% rule**: every `elementId` in `assetMapping` and every static text id must have a row.
+
+**CoverageLayer rules**:
+
+- **on-asr**: must have valid `Grid` (R#C#) and matching PNG slot; mirror to `atom-tree.json` → `asrSlot`
+- **mc-crop**: MC Panel 1 shows type; document region in Style Intent Notes
+- **ta-extends**: color variants / full state sets; `TA extends? = yes` + one-line extension hint
+
+**Forbidden**: missing rows; all rows `ta-extends` with no on-asr/mc-crop type representative; overlapping ASR slots.
+
+#### 2. Palette Locked (`logs/artist-log.md`)
+
+- 6–10 hex swatches sampled from confirmed MC (background, accent, CTA, key elements).
+- One line: **delta vs `layout-spec` Color Palette** (match / Game Designer 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 `artist-log` sections — required for TA Step 0c.
+
+---
+
+### Phase 1 exception: True 3D
+
+When `design-brief` dimension = True 3D, Artist also delivers (Phase 1, same ring 3 verify):
+
+- 2D reference texture PNG at path noted in `artist-log` (see `.claude/agents/refs/artist-dimension-axis.md`).
+- TA runs `generate-3d`; Artist does **not** output GLB.
+
+---
+
+## Phase 2 Deliverables — Audio + Digit + Atom status
+
+**Artist 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-tree.json` → `skillsMatch.mediaGroups` for any `.aiaudio` matches. If matched → `playcraft skills link --atom <atomId>` → verify quality/mood → record linked path and decision in `artist-log.md` / `handoffContext`. Skip only when mood/style mismatch (document in `artist-log.md`).
+
+Record in `logs/artist-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   | **Production handoff context** | —      | `artist-log.md` + `handoffContext`    |
+
+### Production handoff rules
+
+For each Artist-owned production item:
+
+| Condition                           | Record in `artist-log.md` / `handoffContext` |
+| ----------------------------------- | -------------------------------------------- |
+| Type covered in ASR Coverage Matrix | ASR sheet + grid slot or MC crop region      |
+| Not covered; ICP gap                | ICP id + path when file delivered            |
+| ICP supplementary PNG delivered     | file path                                    |
+
+**Forbidden**: write execution status or produced output paths into `atom-tree.json`.
+
+#### ICP supplementary PNG — when (and only when) to produce
+
+Artist Phase 2 supplementary PNGs are a **fallback path**, not a default. Produce one **only if all three** are true:
+
+1. **TA Step 0c Style Interpretation** marks that atom's `confidence = low` in `logs/ta-log.md` (i.e. Artist's MC/ASR didn't tell TA enough).
+2. **Crop / segment from ASR or MC failed** — TA tried `playcraft image crop` (grid coord from ASR Coverage Matrix) and `playcraft image segment --boxes` / `--text` on the MC concept panel, and the extracted region is unusable (chroma residue, partial element, wrong perspective).
+3. **TA opens an ICP entry** in `docs/intent-clarifications.md` with `routeTo: artist`, citing both ① the failed extraction command and ② the specific style ambiguity.
+
+If any of ①②③ is missing, the fix lives elsewhere (TA tool chain, Artist Style Intent Notes patch, or Game Designer contract patch) — not a supplementary PNG. Document the chosen route in `artist-log.md`.
+
+Run **`playcraft-style-qa` §1** only for **ICP supplementary** image files (not for ASR sheets themselves).
+
+### TA ownership in Phase 2 (not Artist)
+
+- 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-templates/threejs/.claude/agents/refs/artist-dimension-axis.md

@@ -0,0 +1,27 @@
+# Artist Dimension Axis Workflow
+
+> Read in Phase 1 after confirming Dimension Axis from `docs/design-brief.md`. **artist-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 Game Designer routes an ICP supplementary art request.
+
+## Isometric
+
+- ASR element sheet: representative isometric tiles (2–3 states).
+- Optional: `playcraft tools search-image` for reference.
+- TA: remaining tiles, atlas, animation.
+
+## True 3D
+
+- Artist does **not** output GLB.
+- Phase 1 ring 3 verify: 2D reference texture PNG (path in `artist-log`) per `artist-deliverable-spec.md` § Phase 1 exception.
+- TA: `generate-3d`, GLB, flip sprites.

package/project-templates/threejs/.claude/agents/refs/artist-handoff-v2-checklist.md

@@ -0,0 +1,76 @@
+# Artist Handoff v2 — Ring 3 verify checklist
+
+> Read at **Step 5** of `artist-style-exploration-flow.md` before ring 3 verify STOP (`ringGate: pending`).
+
+## Prerequisites
+
+- [ ] `workflowSpecVersion` = `growth-rings-v1` in `npm run state:get -- --json`
+- [ ] `selectedMcOption` set (ring 3 Ring Gate — MC selection passed)
+- [ ] MC path: `assets/images/storyboard/master_composite_option_[X].png`
+- [ ] ASR paths exist and pass zero-overlap visual check
+- [ ] ASR cells: isolated elements, no white box / scene inside cells (whole sheet opaque is OK)
+- [ ] § **Image Production Preflight** filled (ring 3 build — three Skills read)
+
+## 1. ASR Coverage Matrix (100% rows)
+
+In `logs/artist-log.md` § ASR Coverage Matrix:
+
+1. List every `elementId` from `layout-spec.md` § Asset Mapping (atlas `frameId` groups = one row per logical element).
+2. List every static text `id` from § Text Assets → Static Text.
+3. **Row count** must equal assetMapping + static text id count (verify before STOP).
+4. For each row, set **CoverageLayer** = `on-asr` | `mc-crop` | `ta-extends`.
+5. For each row: `ASR sheet` = `ui` | `element` | `element_2` | `MC-crop` | `ICP-pending`.
+6. `TA extends?` = `no` only when on-asr shows final representative state; else `yes`.
+7. **Sheet grid metadata** table filled with real numbers (not `{{placeholder}}`).
+
+**Type representative rule**: each distinct **elementType** (Matrix column or `layout-spec` § Element Type Registry) must have at least one row with CoverageLayer `on-asr` or `mc-crop`.
+
+**Stop rule**: any contract row missing → do not set `ringGate: 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 | Game Designer 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 production handoff decision tree
+
+```
+For each Artist-owned production item:
+├─ VisualAtom + covered in Coverage Matrix?
+│   └─ yes → record ASR sheet/grid or MC crop in artist-log + handoffContext
+├─ AudioAtom?
+│   └─ deliver MP3 at path → record in artist-log + handoffContext
+├─ Gap / TA extract failed (ICP)?
+│   └─ generate one PNG → record path, or block until answered
+└─ Never: write execution status or output paths into atom-tree.json
+```
+
+## 5. Files to verify before STOP
+
+| File                                                    | Contains                                                                  |
+| ------------------------------------------------------- | ------------------------------------------------------------------------- |
+| `docs/style-exploration.md`                             | MC paths, Motion Notes, Experience Flow                                   |
+| `logs/artist-log.md`                                    | Image Production Preflight, Coverage Matrix, Palette Locked, Style Intent |
+| `assets/images/reference/ui_state_sheet_[X].png`        | exists                                                                    |
+| `assets/images/reference/element_state_sheet_[X].png`   | exists                                                                    |
+| `assets/images/reference/element_state_sheet_[X]_2.png` | if types > 12 / overflow                                                  |

package/project-templates/threejs/.claude/agents/refs/artist-legacy-fallback.md

@@ -0,0 +1,14 @@
+# Artist Legacy Fallback
+
+Use this reference only when `dispatchPacket` is null and `sliceState` is empty.
+
+This preserves the older visual handoff path for existing projects. It is not part of slice-axis dispatch.
+
+Legacy behavior:
+
+- Read `npm run state:get -- --json` and follow the disclosed current action.
+- Use the existing Artist reference guides only when the orchestrator-disclosed task asks for them.
+- Produce visual handoff context and artifact references, not runtime implementation.
+- Route missing design or asset contract gaps instead of guessing.
+
+When `sliceState` exists, return to the main Artist role contract.

package/project-templates/threejs/.claude/agents/refs/artist-master-composite-recipes.md

@@ -0,0 +1,208 @@
+# Master Composite — 游戏类型 Prompt 配方 & 参考
+
+> 本文件供 Artist 在生成 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           ← ring 3 Ring Gate 确认后复制
+```
+
+ring 3 Ring Gate 确认后：
+
+```bash
+cp assets/images/storyboard/master_composite_option_[X].png assets/images/storyboard/master_composite.png
+```

package/project-templates/threejs/.claude/agents/refs/artist-style-exploration-flow.md

@@ -0,0 +1,55 @@
+# Artist — Style exploration flow (Phase 1: ASR + Handoff Pack)
+
+> **Scope**: After MC is delivered by storyboard subagent and `selectedMcOption` is set (ring 3 Ring Gate passed), follow this document for **ASR production** through ring 3 verify STOP. **Exit criteria**: see `agents/artist.md` Goals § Success criteria.
+>
+> **Deliverable shapes & tables**: `.claude/agents/refs/artist-deliverable-spec.md`.
+>
+> **Pre-condition**: `npm run state:get -- --json` reports `selectedMcOption` (MC already exists at `assets/images/storyboard/master_composite_option_[X].png`).
+
+**Trigger**: `state:get` reports `iteration: 3`, `loop: build`, `selectedMcOption` set.
+
+## Step 1 — Image Production Preflight (before ASR)
+
+Fill `logs/artist-log.md` § **Image Production Preflight**:
+
+1. Read `playcraft-asset-state-sheet`, `playcraft-image-generation` (§3 + §3.1)
+2. Mark each Skill row ✓ with one-line decision summary
+3. Read `layout-spec.md` — count assetMapping rows + note Element Type Registry (if present)
+
+**Do not generate ASR until this section is complete.**
+
+## Step 2 — Generate ASR sheets（仅针对 state `selectedMcOption`）
+
+- Read `selectedMcOption` from `npm run state:get -- --json` — if missing, **STOP**
+- **Re-read** `playcraft-asset-state-sheet` + `playcraft-image-generation` §3.1 (cell chroma / isolated)
+- 输出：`ui_state_sheet_[X].png` + `element_state_sheet_[X].png`（类型 >12 时可加 `element_state_sheet_[X]_2.png`）
+- `--reference-image` = `master_composite_option_[selectedMcOption].png`；`--image-model` 与 MC 一致
+- Prompt：sheet `#808080` 或统一色幕；每格 **one isolated element**；金/橙格用蓝幕
+- 生成后 `playcraft image info`；目视：零重叠、格内无白盒/场景底
+- **Do not** `remove-background` on ASR — TA handles post-crop
+
+## Step 3 — Ring 3 Handoff Pack
+
+> **Checklist**: `.claude/agents/refs/artist-handoff-v2-checklist.md`
+
+1. 补全 `docs/style-exploration.md`（ASR 路径、**Motion Notes**、Experience Flow）
+2. 更新 `logs/artist-log.md`：
+   - **ASR Coverage Matrix** — 100% contract rows + **CoverageLayer** column
+   - 每种 **elementType** ≥1 行 `on-asr` 或 `mc-crop`
+   - **Palette Locked**、Style Intent / Anti-Pattern
+   - Mirror `on-asr` rows → `atom-tree.json` → `meta.selectedAtoms.asrSlot`
+3. **Self-check before STOP**:
+
+```bash
+# MC ratio (confirm MC from storyboard subagent is valid)
+playcraft image info --input assets/images/storyboard/master_composite_option_[X].png
+
+# Count contract rows (adjust grep to your layout-spec format)
+grep -c 'elementId\|"id":' docs/layout-spec.md   # approximate — Matrix row count must match
+
+# ASR files exist
+ls assets/images/reference/ui_state_sheet_[X].png assets/images/reference/element_state_sheet_[X].png
+```
+
+4. 更新 handoff + `ringGate: pending`
+5. **STOP** — 禁止 Phase 2 音频与批量视觉样本 PNG