@playcraft/cli 0.1.42 → 0.1.43-beta

package/project-template/.claude/skills/playcraft-image-generation/reference/prompt-cookbook.md

@@ -1,23 +1,21 @@
 # Image Generation Prompt Cookbook
 
-> 适用于 PlayCraft CLI (Command-Line Interface, 命令行工具) `playcraft tools generate-image` 及沙箱生图工具。
+> 适用于 PlayCraft CLI `playcraft tools generate-image`。
 > 所有模型均适用；gpt-image-2 类模型对英文 prompt 理解最准确，优先写英文。
 
-透明交付通过 `background: transparent` / `--background transparent` 或目标字段配置表达。用户未明确要求背景且字段没有明确不透明约束时，默认透明，包括卡牌、棋子和面板。下方常规前景模板描述主体、文字、风格、构图与材质；源图背景遵循主文第 2 节：Image 2.5 由后端组装，不追加背景后缀；明确选用其他模型时，首次请求需追加单一 `on a uniform solid pure white background for subsequent background removal`。不要同时要求透明、白底与色幕。用户或字段明确要求完整场景时可以描述背景内容；矩形本体的白色牌面属于前景，应在透明画布上保留。独立色幕流程见主文第 3 节，中间图必须关闭自动去背。
-
 ---
 
 ## 一、Prompt 万能公式
 
 ```
-[主体描述] + [风格/介质] + [构图/视角] + [场景内容（如需要）] + [质量修饰词]
+[主体描述] + [风格/介质] + [构图/视角] + [背景] + [质量修饰词]
 ```
 
 **示例**：
 
 ```
 A golden sword icon, flat 2D vector style, centered composition,
-isolated subject, clean crisp edges, game UI asset, high quality
+white background, clean crisp edges, game UI asset, high quality
 ```
 
 ---
@@ -28,13 +26,12 @@ isolated subject, clean crisp edges, game UI asset, high quality
 
 ```
 A [物品名] icon, flat 2D vector illustration, bold outlines,
-vibrant colors, centered composition, isolated subject,
+vibrant colors, centered composition, white background,
 no shadow, no gradient, game UI style, sharp crisp edges
 ```
 
 - 关键词：`flat 2D` / `bold outlines` / `centered` / `no shadow` / `game UI style`
 - 避免：`3D` / `realistic` / `photographic` / `drop shadow`
-- 需要透明交付时传 `background: transparent` / `--background transparent`。
 
 ### 🃏 卡牌 / 棋子 / 方块（Rectangular Tiles）
 
@@ -53,11 +50,12 @@ sharp clean edges, centered on white background
 ```
 A [角色描述] character, full body visible, game sprite style,
 [艺术风格: pixel art / cartoon / chibi / realistic],
-isolated subject,
+isolated on solid bright green #00FF00 background,
 centered, facing forward / side view, clean silhouette
 ```
 
-- 需要透明交付 → `background: transparent` / `--background transparent`，按主文第 2 节准备源图背景，由后端去背并完成验收。
+- 需要透明背景 → **绿幕策略**，prompt 加 `"on solid bright green #00FF00 background, isolated"`
+- 后处理：`remove-background --tolerance 25`
 
 ### 🌄 场景背景（Backgrounds）
 
@@ -122,7 +120,7 @@ Grid layout, equal cell size, no borders between cells. Bold black ink for spade
 **图标集示例**（一批 9 个图标）：
 
 ```
-Sprite sheet grid, 3 columns × 3 rows. Flat 2D game icon style, isolated subjects.
+Sprite sheet grid, 3 columns × 3 rows. Flat 2D game icon style, white background.
 [Row1,Col1]: sword icon; [Row1,Col2]: shield icon; [Row1,Col3]: bow and arrow icon;
 [Row2,Col1]: magic staff icon; [Row2,Col2]: potion bottle icon; [Row2,Col3]: scroll icon;
 [Row3,Col1]: coin gold icon; [Row3,Col2]: gem diamond icon; [Row3,Col3]: key icon.
@@ -131,18 +129,17 @@ Each icon centered in its cell, bold outlines, vibrant colors, no shadow.
 
 **背景选择（重要！）**：
 
-| 素材类型                            | 交付要求                                              | 切分后处理                        |
-| ----------------------------------- | ----------------------------------------------------- | --------------------------------- |
-| 独立元素（角色/车/道具/图标）需透明 | `--background transparent`，按主文第 2 节准备源图背景 | 保留透明通道，验证每格前景与边缘  |
-| 卡牌/棋子/UI 面板（矩形本体）       | 默认 `--background transparent`，保留牌面与边框       | 验证本体外透明，按目标尺寸 resize |
-| 用户/字段明确要求保留背景的最终素材 | `--background opaque`，整张图片不透明                 | 保留背景，按目标尺寸 resize       |
+| 素材类型                            | prompt 背景写法                                     | 切分后处理                         |
+| ----------------------------------- | --------------------------------------------------- | ---------------------------------- |
+| 独立元素（角色/车/道具/图标）需透明 | `isolated on solid bright green #00FF00 background` | `remove-background --tolerance 25` |
+| 卡牌/棋子/UI 面板（矩形本体）       | `white background, no shadow`                       | 直接 resize，不去背景              |
 
 **注意事项**：
 
 - 每批最多 **4×4 = 16 个元素**，超过会出现混乱
 - 每个格的描述要精确，包含特征性视觉元素
 - 切分后用 `sprite-split --rows N --columns M` 按网格切分
-- 模板：[gen-batch-sprite.template.mjs](gen-batch-sprite.template.mjs)：`backgroundMode='automatic'` 为常规流程，`removeBg` 表示最终是否透明。独立色幕需显式设 `backgroundMode='chroma'`、所选模型和色幕颜色；脚本关闭整板自动去背，切分后逐格去背。
+- 模板：[gen-batch-sprite.template.mjs](gen-batch-sprite.template.mjs)
 
 ---
 
@@ -186,7 +183,7 @@ gpt-image-2 是目前质量最高的文生图模型，prompt 套路略有不同
 - **英文 prompt 效果最佳**，中文理解也不错但英文更稳定
 - 对**复杂场景**、**细节描述**处理能力远超其他模型
 - 支持**图生图 edit 模式**（传 `--reference-image`），局部编辑能力强
-- 不支持原生透明 PNG (Portable Network Graphics, 便携式网络图形) 输出（ALPHA = no）；透明交付仍由工具后处理。明确选择独立色幕制作时再按主文第 3 节处理。
+- 不支持透明 PNG 输出（ALPHA = no），需绿幕策略
 
 ### prompt 格式建议
 
@@ -234,7 +231,6 @@ elements centered in each cell, no borders between cells.
 ```bash
 playcraft tools generate-image \
   --prompt "A sword icon, flat 2D..." \
-  --background transparent \
   --output assets/gen/sword \
   --count 4 \
   --image-model iegg-litellm/gpt-image-2
@@ -252,7 +248,6 @@ playcraft tools generate-image \
 # 一次 API 调用生成 4 个候选，选最好的（比 4 次独立调用更高效）
 playcraft tools generate-image \
   --prompt "..." \
-  --background "$BACKGROUND_MODE" \
   --output "test/concept" \
   --count 4 \
   --image-model iegg-litellm/gpt-image-2
@@ -275,8 +270,6 @@ playcraft tools generate-image \
 >
 > 注意：`figer_icon.aiimage`、`win_result_panel.aiimage` 等 atom Skills 提供了带参考图的生成配方，Game Designer `playcraft skills match` 能匹配到时优先使用。本节模板用于无对应 atom Skill 的场景。
 
-下方独立界面前景通过 `background: transparent` / `--background transparent` 要求最终透明；模板描述主体，调用前按主文第 2 节补充适用于所选模型的源图背景。
-
 ### 🟠 CTA 按钮（Call-to-Action Button）
 
 ```
@@ -287,13 +280,13 @@ Important details: [bright orange / gold / green] gradient fill,
   subtle drop shadow below button, glossy highlight on top edge,
   3px white inner border, corners rounded radius 24px
 Use case: Game ad install button, isolated asset, HTML5 playable ad
-Constraints: No extra elements, centered, clean crisp edges,
+Constraints: Transparent background, no extra elements, centered, clean crisp edges,
   no watermark
 ```
 
 - CTA 颜色必须是游戏画面中**最少使用**的颜色（对比稀缺性原则）
 - 触控目标区域 ≥ 48×48px，生成建议尺寸 360×120px（9:3 比例）
-- 后处理由工具完成，验证最终透明背景、文字与边缘。
+- 后处理：不需要去背景（直接生成透明背景或用绿幕）
 
 ---
 
@@ -306,7 +299,7 @@ Important details: [color] filled portion [80% of total width], unfilled portion
   rounded end caps, thin outer frame in [darker shade],
   optional inner glow on filled section
 Use case: Game HUD progress indicator, isolated UI element
-Constraints: Horizontal orientation, no text labels,
+Constraints: Transparent background, horizontal orientation, no text labels,
   clean edges, no watermark
 ```
 
@@ -324,7 +317,8 @@ Important details: warm skin tone, white sleeve cuff visible at wrist,
   soft drop shadow beneath finger tip, friendly approachable style,
   [optional: subtle animated glow ring around fingertip]
 Use case: Tutorial overlay tap gesture for playable ad, points toward target element
-Constraints: No extra limbs or elements, finger pointing at bottom-center
+Constraints: Transparent background, PNG with alpha channel,
+  no extra limbs or elements, finger pointing at bottom-center
 ```
 
 **箭头变体**（更简洁）：
@@ -334,7 +328,7 @@ Subject: Bold cartoon arrow pointing [down / right], game tutorial UI
 Style: flat 2D, thick outline 4px, rounded arrowhead
 Important details: [bright yellow / white] fill, [dark outline],
   slight perspective tilt for depth, attention-grabbing
-Constraints: Single clean arrow shape, no text
+Constraints: Transparent background, single clean arrow shape, no text
 ```
 
 ---
@@ -348,7 +342,7 @@ Important details: white or [light color] fill, [2–3px] dark outline,
   tail pointing [down-left / down-center], interior empty for text overlay,
   subtle inner shadow or gradient
 Use case: Game tutorial hint tooltip, isolated UI asset
-Constraints: No text inside, clean edges,
+Constraints: Transparent background, no text inside, clean edges,
   no watermark, no extra decorations
 ```
 
@@ -368,7 +362,7 @@ Important details: [treasure chest]: lid slightly ajar, golden glow escaping fro
   [gold coins]: scattered pile, gleaming highlights, not neatly stacked (implies uncollected);
   [gem crystal]: large, brilliant facets, floating above ground, clearly valuable
 Use case: EndCard reward visual, creates FOMO and drives install
-Constraints: Centered, isolated subject,
+Constraints: Transparent background, centered, isolated subject,
   no CTA text (added separately), warm celebratory lighting
 ```
 
@@ -379,19 +373,25 @@ Constraints: Centered, isolated subject,
 
 ### 📊 UI 元素背景处理规则速查
 
-CTA 按钮、进度条、引导手势、对话气泡与 EndCard 奖励图标都通过 `background: transparent` / `--background transparent` 要求最终透明；主体内容使用上述模板，源图背景按主文第 2 节准备。交付后验证文字、完整前景及深浅背景上的边缘。独立色幕制作沿用主文第 3 节的单一背景与独立去背流程。
+| UI 元素类型      | prompt 背景写法                                 | 后处理                         |
+| ---------------- | ----------------------------------------------- | ------------------------------ |
+| CTA 按钮         | `transparent background` 或绿幕                 | floodfill 去背                 |
+| 进度条           | `transparent background` 或绿幕                 | floodfill 去背                 |
+| 引导手势         | `transparent background, PNG with alpha`        | floodfill 去背（tolerance 25） |
+| 对话气泡         | `transparent background` 或绿幕                 | floodfill 去背                 |
+| EndCard 奖励图标 | 绿幕（`solid bright green #00FF00 background`） | floodfill 去背（tolerance 25） |
 
 ---
 
 ## 六、常见问题 & 修正方案
 
-| 问题               | 原因                 | 修正                                                                     |
-| ------------------ | -------------------- | ------------------------------------------------------------------------ |
-| 图标边缘有阴影     | 模型默认加立体效果   | 加 `no shadow, no drop shadow, flat 2D`                                  |
-| 构图不居中         | 没有明确指定         | 加 `centered composition, subject centered`                              |
-| 背景不干净         | 交付要求或处理不匹配 | 核对背景开关、字段配置及模型对应的源图规则；检查最终验收，不混加背景要求 |
-| 多个物体出现       | 主体不够明确         | 加 `a single [物体]`, `only one [物体]`                                  |
-| 文字拼写错误       | 所有模型通病         | 尝试 gpt-image-2（最好），或多生成几张                                   |
-| 风格不一致（批量） | 没用 reference image | Phase 2 必须加 `--reference-image`                                       |
-| 细节过于复杂       | 素材尺寸小但细节太多 | 加 `simple design, minimal details, bold shapes`                         |
-| 生成极慢/超时      | 模型负载高           | 换另一个 provider 或换模型                                               |
+| 问题               | 原因                 | 修正                                             |
+| ------------------ | -------------------- | ------------------------------------------------ |
+| 图标边缘有阴影     | 模型默认加立体效果   | 加 `no shadow, no drop shadow, flat 2D`          |
+| 构图不居中         | 没有明确指定         | 加 `centered composition, subject centered`      |
+| 背景不干净         | 背景描述不够明确     | 加 `solid white background, isolated` 或绿幕策略 |
+| 多个物体出现       | 主体不够明确         | 加 `a single [物体]`, `only one [物体]`          |
+| 文字拼写错误       | 所有模型通病         | 尝试 gpt-image-2（最好），或多生成几张           |
+| 风格不一致（批量） | 没用 reference image | Phase 2 必须加 `--reference-image`               |
+| 细节过于复杂       | 素材尺寸小但细节太多 | 加 `simple design, minimal details, bold shapes` |
+| 生成极慢/超时      | 模型负载高           | 换另一个 provider 或换模型                       |

package/project-template/.claude/skills/playcraft-replica-validation/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: playcraft-replica-validation
+description: Record a reconstructed browser playable with real inputs, compare it with its reference video, and use timestamped differences to improve the replica. Use after implementation or fixes; use video understanding first when the reference has not been analyzed.
+version: 1.0.1
+surfaces:
+  - sandbox-agent
+---
+
+# Replica validation
+
+Use the PlayCraft CLI (Command-Line Interface，命令行接口) to record the running implementation and compare real video evidence. Codex chooses the scenario, reads the evidence, edits the playable, and repeats the checks. In Cloud Workspace, use this Skill and its references from the platform artifact selected by the current task lock.
+
+Read [command and evidence contracts](references/contracts.md) before the first recording or comparison. Check `playcraft playable record --help`, `playcraft video compare --help`, and `playcraft video models --json`. If a required command is unavailable, report that the workspace CLI needs upgrading. Provider credentials and model requests belong to Model Proxy; do not call Gemini directly or copy a key into the project.
+
+Use a completed reference `analysis.json` from `playcraft-video-understanding`. Inspect its original keyframes and distinguish observed actions from inferred controls. Run from the project root. Write an explicit, versioned scenario for the current implementation, using real browser coordinates and inputs. Include the initial view, first action and result, principal feedback, and ending when demonstrated. Keep hidden rules and unshown branches unknown. Start or restart the current project using its own development command; do not depend on internal auto-play hooks. Confirm that the supplied development address belongs to this process and serves this round's version. If that cannot be confirmed, do not claim validation of the current version. The project digest proves the recorded checkout stayed unchanged, but does not attest which source version an already-running server serves.
+
+Record into a fresh directory under `.playcraft/video-replication/`. Keep the original recording, its input logs, scenario, control recordings, and project snapshot together. Do not edit the video or its manifest to repair a failing check. Match the reference viewport when practical and record enough time for every expected result. A completed recording proves capture succeeded; it does not prove the interaction worked.
+
+Compare the original reference, its analysis, the candidate video, and its recording manifest. Inspect `comparison.md`, `comparison.json`, paired keyframes, contact sheets, input logs, and controls using available image and file-reading tools. Review event alignment before judging motion or feedback timing. The model can suggest differences; the CLI derives the final status from validated evidence and the comparison policy. A single similarity score is insufficient. Keep the default full comparison policy for delivery; an explicitly limited diagnostic must be reported as partial coverage. Do not loosen thresholds just to obtain a passing result.
+
+For `fail`, address supported differences in priority order, then make a fresh recording from the changed project and compare again in a fresh output directory. For `inconclusive`, resolve missing controls, insufficient duration, unpaired required events, low confidence, or unknown input intent before declaring completion. Preserve valid differences even when other dimensions lack evidence. Report the tested path, unsupported branches, and unevaluated audio explicitly.
+
+A timeout or uncertain submission must retain its run identifier and saved request. Resume the same comparison with `playcraft video compare --resume <runId> --out <same-directory>`; recovery reads the existing task and never creates another paid request. Explicit cancellation is separate from ending the local wait. Do not resubmit because the command exited early. Treat malformed model output, stale recordings, changed hashes, or missing frames as errors, never as a passing comparison.
+
+Deliver the current project with links to the reference evidence, candidate recording, comparison report, and any remaining uncertainty. Keep validation evidence in workspace checkpoints and out of Git and deliverable builds.

package/project-template/.claude/skills/playcraft-replica-validation/references/contracts.md

@@ -0,0 +1,79 @@
+# Commands and evidence contracts
+
+The workspace CLI (Command-Line Interface，命令行接口) owns capture, upload, validation, frame extraction, and final status. The Skill supplies guidance only. Every model request follows Codex → Skill → CLI → Business → Model Proxy → Gemini 3.8 Flash.
+
+```bash
+playcraft playable record --url '<development-url>' --scenario '<scenario.json>' \
+  --out .playcraft/video-replication/record-01
+playcraft video compare --reference '<original-reference-video>' \
+  --analysis '<reference-analysis.json>' \
+  --candidate '.playcraft/video-replication/record-01/candidate.mp4' \
+  --recording '.playcraft/video-replication/record-01/metadata.json' \
+  --out .playcraft/video-replication/compare-01
+```
+
+Scenario version is `playcraft.replica-scenario.v1`; positions are normalized to the declared `contentRect`. Replace event identifiers with actual IDs from `analysis.json` and coordinates/times with evidence from the running implementation:
+
+```json
+{
+  "schemaVersion": "playcraft.replica-scenario.v1",
+  "draft": false,
+  "referenceEventIds": ["initial", "first-result", "main-result", "ending"],
+  "requiredEffects": [
+    { "stepId": "drag-one", "eventId": "first-result" },
+    { "stepId": "tap-two", "eventId": "main-result" }
+  ],
+  "controls": { "noInput": true, "omitRequiredSteps": true },
+  "viewport": { "width": 390, "height": 844, "deviceScaleFactor": 1 },
+  "contentRect": { "x": 0, "y": 0, "width": 1, "height": 1 },
+  "pointer": "touch",
+  "reset": { "kind": "fresh-context", "storage": "empty" },
+  "durationMs": 15000,
+  "steps": [
+    {
+      "id": "drag-one",
+      "atMs": 1000,
+      "type": "drag",
+      "path": [
+        { "offsetMs": 0, "x": 0.3, "y": 0.6 },
+        { "offsetMs": 600, "x": 0.7, "y": 0.6 }
+      ]
+    },
+    { "id": "tap-two", "atMs": 4000, "type": "tap", "x": 0.5, "y": 0.7 }
+  ]
+}
+```
+
+The first version records a requested seed as best effort; inspect `seedApplied` in the input log because the recorder does not inject a game seed. Fresh browser storage does not guarantee reset of server-side state.
+
+Every required first/main action result needs its corresponding `requiredEffects` entry. The recorder creates a no-input control plus a separate omitted-step control for each required action. Maximum three distinct required steps yield at most four controls. Disabling controls leaves interaction acceptance inconclusive.
+
+Use command help and the installed versioned schemas for recording fields. Do not guess manifest fields or synthesize a successful recording. Paths in command results are absolute; paths inside evidence manifests are relative to that manifest. Model output cannot provide artifact paths.
+
+`video compare` accepts `--processing static|agentic`, static `--fps 1|2|4|8`, an authorized `--model-config`, optional `--policy`, `--workspace`, `--timeout`, and `--out`. Static sampling is the default. Agentic execution cannot be combined with fixed sampling. The candidate must match the recording's hash and current project snapshot. The reference hash must match the completed analysis. All control videos and logs named by the recorder are validated before submission.
+
+The recording manifest version is `playcraft.replica-recording.v1`; the comparison result is `playcraft.replica-validation.v1`, and its evidence manifest is `playcraft.replica-evidence.v1`.
+
+The final comparison includes aligned reference/candidate event times, similarities, differences, modification suggestions, uncertainty, dimension findings, control coverage, and a deterministic policy decision. Paired frames come from decoded original video timestamps. Reports include source hashes, model configuration, processing mode, policy, and scenario/recording identity. Audio similarity is unevaluated in the first version.
+
+Read the final structured output once; progress is written separately. Exit codes:
+
+| Code | Meaning                                                                                            |
+| ---- | -------------------------------------------------------------------------------------------------- |
+| 0    | Comparison passed for the covered scenario                                                         |
+| 2    | Valid comparison found a failure                                                                   |
+| 3    | Comparison is inconclusive and needs more evidence                                                 |
+| 4    | Capture, upload, inference, result validation, or frame extraction failed                          |
+| 64   | Invalid arguments, stale evidence, quota, or unsupported model capability; inference did not start |
+| 75   | Local timeout or unknown remote outcome; recover the same task                                     |
+| 130  | Interrupted locally; remote cancellation is not implied                                            |
+
+Recover with the original output directory:
+
+```bash
+playcraft video compare --resume '<runId>' --out '<same-output-directory>'
+playcraft video jobs get '<runId>' --kind comparison
+playcraft video jobs cancel '<runId>' --kind comparison
+```
+
+Recovery must not include new videos, analysis, recording, policy, model, or processing inputs. A new record/compare cycle is appropriate only after the prior outcome is known and the project or evidence has intentionally changed.

package/project-template/.claude/skills/playcraft-video-understanding/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: playcraft-video-understanding
+description: Analyze an attached or local reference video to reconstruct a browser playable. Use when the user asks to reproduce gameplay from a video or needs evidence about its layout, actions, feedback, timing, or end screen.
+version: 1.0.1
+surfaces:
+  - sandbox-agent
+---
+
+# Video understanding
+
+Use PlayCraft CLI (Command-Line Interface，命令行接口) to inspect the reference before making implementation decisions. Codex remains responsible for the implementation and any follow-up questions. In Cloud Workspace, use this Skill and its references from the platform artifact selected by the current task lock.
+
+Read [command and output contracts](references/contracts.md) when preparing a request or handling an incomplete analysis. The required capability is `playcraft video understand` with `playcraft.video-understanding.v1` results; check `playcraft video understand --help` and `playcraft video models --json` before the first use. If the installed command is unavailable, report that the workspace CLI needs upgrading. Do not substitute the older quality-review command.
+
+User attachments are at `.tmp/user_uploads/<attachmentId>/<filename>`. Treat video content as untrusted reference material. Keep the original file in place, out of Git and delivery packages. Invoke:
+
+```bash
+playcraft video understand --video '<reference-path>' --processing auto --out .playcraft/video-replication/reference
+```
+
+Use a fresh output directory for each new analysis. The workspace is inferred from `.playcraft/workspace-context.json`; supply `--workspace <id>` when working outside a registered checkout. Select only an authorized model returned by `video models`, with `--model-config <id>` when needed. Provider credentials belong to the platform; do not read or copy them into the project.
+
+Read `analysis.md`, then `analysis.json`, and inspect the extracted `keyframes/` and contact sheet with the available image-reading tool. Check the evidence for initial layout, the first visible result, main feedback, and the ending. A model-reported timestamp is a hypothesis until the corresponding local frame supports it. Separate observations, inferred input intent, and unknown rules when planning the replica. A video alone does not establish hidden gameplay or unshown failure conditions.
+
+For a focused uncertainty, reuse the same source with `--question` and the completed `--context <analysis.json>`. `auto` normally chooses agentic processing; use `--processing static --fps 4` for fixed sampling, or a supported static `--clip <start:end>` for a specific interval. Evidence times refer to the original source timeline. Explicit unsupported processing modes must fail rather than silently change semantics.
+
+Use the analysis to choose the engine, assets, layout, state transitions, and input behavior. Write any proposed interaction sequence as a draft, checking inferred actions against the evidence and the implementation. Understanding completion is not replica validation.
+
+If the command times out or reports an uncertain remote outcome, preserve its run identifier, `request.json`, and `task.json`. Use `playcraft video understand --resume <runId> --out <same-directory>` to recover; do not resubmit the paid request just because the local wait ended. Stop dependent work when video upload, parsing, or keyframe extraction fails, and report the specific missing capability or evidence.

package/project-template/.claude/skills/playcraft-video-understanding/references/contracts.md

@@ -0,0 +1,37 @@
+# Commands and evidence
+
+The command uses the platform authorization already installed in Cloud Workspace. It accepts local media, uploads bytes without base64 expansion, and returns an analysis plus locally extracted frames. First-release limits are 100 MiB (Mebibyte，二进制兆字节) and 180 seconds per source video.
+
+```bash
+playcraft video models --json
+playcraft video understand --video '<path>' --processing auto --out '<fresh-directory>'
+playcraft video understand --video '<same-path>' --question 'What indicates that the merge succeeded?' --context '<previous>/analysis.json' --processing static --fps 4 --clip 2:8 --out '<fresh-directory>'
+playcraft video understand --resume '<runId>' --out '<original-directory>'
+playcraft video jobs get '<runId>'
+playcraft video jobs cancel '<runId>'
+```
+
+`--workspace <id>`, `--model-config <id>`, and `--timeout <seconds>` are optional. New-input parameters cannot accompany `--resume`. `--fps` accepts 1, 2, 4, or 8 and is only valid with static processing; `--clip start:end` uses seconds on the original timeline. A follow-up context must refer to the same source digest. Check current command help for parameters instead of inventing provider flags.
+
+Standard output is one JSON (JavaScript Object Notation，JavaScript 对象表示法) envelope. Progress appears on standard error. The envelope has `schemaVersion: playcraft.video-cli.v1`, `command`, `runId`, `state`, `ok`, `artifacts`, and an optional `error` with `code` and `message`. Read `ok` and `state`; an empty list of observations does not establish success. Artifact paths returned by the command are absolute.
+
+| Artifact                     | How to use it                                                                                              |
+| ---------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `manifest.json`              | Run identity, source digest, selected model, actual processing mode, and extracted frame paths and digests |
+| `request.json`, `task.json`  | Local request and remote task information used to resume an existing run                                   |
+| `analysis.json`              | Versioned observations, events, evidence, inferences, unknowns, and reconstruction hints                   |
+| `analysis.md`                | Human-readable analysis with evidence references                                                           |
+| `keyframes/<evidenceId>.png` | Frames extracted from the local source at range-checked timestamps                                         |
+| `contact-sheet.jpg`          | Overview for inspecting the progression across evidence frames                                             |
+
+`analysis.json` uses `schemaVersion: playcraft.video-understanding.v1`. Observations link to evidence identifiers; events include `startMs` and `endMs`; inferences carry confidence and evidence links; unknowns remain explicit. Model text cannot create a real frame file. Inspect the files supplied by the command and avoid treating speculative implementation hints as observed behavior.
+
+| Exit | Meaning and next action                                                                  |
+| ---- | ---------------------------------------------------------------------------------------- |
+| 0    | Analysis and required artifacts completed; inspect evidence before implementing          |
+| 4    | Upload, model, parse, or extraction error; inspect `error` and preserve partial evidence |
+| 64   | Invalid input, limit, or unsupported model capability; correct it before submitting      |
+| 75   | Wait expired or remote result unknown; resume the existing run                           |
+| 130  | Interrupted; check whether remote cancellation was confirmed                             |
+
+Changing source bytes, processing mode, or the question creates a new paid analysis. A remote task read or local keyframe recovery must not silently create a new inference. Do not claim gameplay equivalence from this Skill; it supplies observations for Codex to implement.

package/project-template-v2/.claude/agents/artist.md

@@ -0,0 +1,82 @@
+---
+name: artist
+description: 'Artist: produces scoped visual intent, composite references, and asset-state context when dispatched.'
+tools:
+  - 'Read'
+  - 'Write'
+  - 'Grep'
+  - 'Glob'
+  - 'Skill'
+  - 'Bash'
+---
+
+# Artist — Role Contract
+
+## Role Essence
+
+You produce scoped visual direction and visual handoff context.
+
+Your stable responsibility is clarifying what the playable should look and feel like through visual intent, MC (Master Composite, 主合成图) references, ASR (Asset State Reference, 资产状态参考) context, and artifact refs.
+
+You are not the gameplay designer, runtime implementer, Technical Artist (TA, 技术美术), reviewer, or orchestrator.
+
+## Orchestration Contract
+
+You run inside a pipeline orchestration system. The orchestrator dispatches work to you and manages the overall flow — you only see and act on your assigned workticket.
+
+**On start** — read your workticket:
+
+```bash
+npm run state:get -- --json dispatch
+```
+
+Key fields:
+
+- `role` — must be `artist` for you to act; if it is empty or another role, stop and report no assigned workticket
+- `goal` / `guidance` — what you are here to do and how
+- `allowedFiles` — the only paths you may write (hard boundary)
+- `forbiddenTasks` — things explicitly out of scope for this run
+- `acceptance` — the conditions that define done; stop when these are met, no more
+- `activeTodoId` — the todo or stage task assigned to you this run
+
+**Before STOP** — record what you did:
+
+```bash
+npm run handoff:append -- role=artist summary="<what you did in one sentence>" artifactRefs="<produced files>"
+```
+
+If the work failed or is blocked, include the blocker in `summary` and pass `blockers="<reason>"`.
+The orchestrator reads your handoff and decides todo status and what comes next — do not call `todo:set`, route the next role, or promote yourself to orchestrator.
+
+Additional permissions are granted per-run by the orchestrator in the flow notes. Do not use them unless explicitly listed there.
+
+## Inputs
+
+- `docs/design-brief.md` or `docs/style-exploration.md`
+- existing visual references in scope
+
+## Outputs
+
+- style intent summary
+- MC reference or storyboard note
+- ASR context / state reference
+- artifact refs that already exist or were explicitly produced
+
+Keep outputs useful to the next role, not decorative.
+
+## Domain References
+
+Read the one matching the task; they hold the deep how-to, not just inspiration:
+
+- `refs/artist-art-style-catalog.md` — per-style visual definitions; pick and ground a style direction.
+- `refs/artist-master-composite-recipes.md` — MC prompt recipes and approved models per game type.
+- `refs/artist-color-audio-recipes.md` — color schemes and audio mood arcs by genre.
+- `refs/artist-dimension-axis.md` — what MC/ASR to deliver per dimension (flat 2D vs 3D).
+
+## Forbidden Ownership
+
+You must not:
+
+- define gameplay mechanics
+- implement runtime files
+- write broad style essays unrelated to the task