# Thumbnail

> Thumbnail is an Agent Skill for design published in the daiki-beppu/youtube-automation repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Use when コレクションの YouTube サムネイル（thumbnail.jpg）を CTR 最適化し、textless main.png/jpg を先行生成して実フォント合成するとき。「サムネイル生成」「画像生成」「アイキャッチ」で発動。伸びた動画起点の改善ループは /thumbnail-iterate、競合の勝ちパターン分析は /thumbnail-research、320px 視認性比較は /thumbnail-compare、単独の Studio A/B 設計・結果記録は /thumbnail-test、SVG・汎用画像生成には使わない

- Skill name: `thumbnail`
- Category: [Design](https://www.openparable.com/skill/design/1)
- Source: https://github.com/daiki-beppu/youtube-automation/blob/HEAD/.claude/skills/thumbnail/SKILL.md
- Repository: daiki-beppu/youtube-automation (161 GitHub stars when collected)

## SKILL.md

## 前後工程

- `前工程`: `/collection-ideate`, `/wf-new`, `/thumbnail-iterate`
- `後工程`: `/loop-video`, `/thumbnail-compare`, `/alignment-check`, `/thumbnail-test`

## Overview

コレクション用サムネイルを `config/skills/thumbnail.yaml`（skill-config）に基づいて生成する。
チャンネルごとにスタイル・キャラ・参照画像が異なり、すべて skill-config から動的に読み取る。
画像生成プロバイダー（Gemini / OpenAI / codex）は `image_generation.provider` で切り替え可能。

> imagegen taxonomy 対応: `Use case: product-mockup (YouTube thumbnail variant)`（imagegen の 19 スラグでは product-mockup に相当）。

## 設定読み込みゲート

前提確認や Step 1 に入る前に、以下を必ず Read（Codex では同等のファイル閲覧）で開く。SKILL.md の説明や記憶から設定値を推測しない。

1. `.claude/skills/thumbnail/config.default.yaml`
2. `config/skills/thumbnail.yaml`（存在する場合）

読み込み後は `youtube_automation.utils.skill_config.load_skill_config("thumbnail")` と同じ deep-merge 前提で、チャンネル上書きを優先して扱う。存在しない override は未設定として扱い、勝手に作成しない。このスキルが別 skill の skill-config を直接参照する段階では、その skill の `config.default.yaml` と `config/skills/<skill>.yaml` も同じ手順で読む。

**Hard Gate**: `archive.enabled: true` の場合、確定直後のアーカイブが設定不正・確定サムネ欠落・シンボリックリンク・コピー失敗で失敗したら後工程へ進まず停止する。ギャラリー保存を成功したように扱わない。

## 前提

`config/channel/` が存在すること（`load_config()` でロード可能）。

`config/skills/thumbnail.yaml` はオプション。`yt-skills sync` で配布される `config.default.yaml` がそのまま使われるため、default 動作で問題なければ作成不要。カスタマイズしたい場合のみ `config.default.yaml` をコピーして `config/skills/thumbnail.yaml` に置き、必要な値だけ上書きする（deep-merge される）。

`config/channel/` が存在しない場合、ユーザーに確認:
- **新規チャンネル** → `/channel-new` を案内
- **既存チャンネル**（YouTube で既に運営中）→ `/channel-new`（既存チャンネル取り込みモード）を案内

## 完了条件

- `10-assets/thumbnail.jpg`（テキスト付き YouTube サムネ）と `10-assets/main.png`（または `main.jpg`、textless 動画背景）が**別成果物として**確定済み。`auto_selection.mode: full` 以外ではそれぞれユーザー承認済み。`ab_test.enabled: true` の場合は全 `thumbnail-<name>.jpg` も確定済み（`full` 以外では個別承認済み）で、`thumbnail.jpg` が先頭 pattern と同一内容
- テキスト付きサムネは `mode: full` 以外では承認前に、`full` では自動確定後に `/thumbnail-compare` の 320px 視認性検証を通過している
- `20-documentation/thumbnail-prompts.md` に textless 背景用プロンプトと、テキスト付きサムネの生成記録（標準: `yt-thumbnail-text` の合成パラメータ、AI 焼き込み fallback: テキスト付き生成プロンプト）を保存済み
- `workflow-state.json` の `thumbnail.approved = true` に更新済み
- `archive.enabled: true` の場合は `assets/thumbnail-gallery/<collection-dir-name>.<ext>` に確定サムネを保存済み

**全自動 Hard Gate**: deep-merge 後の `image_generation.auto_selection.enabled: true` かつ `mode: full` のときだけ、テーマ確認・生成可否（`confirm_cost()`）・textless 背景承認・テキスト付き候補承認の 4 ゲートをすべて省略する。`enabled: true` でも `mode` が未設定または `selection_only` なら候補承認だけを省略し、残り 3 ゲートは従来どおり実行する。`enabled: false` / 未設定なら全ゲートを維持する。`full` でテーマを一意に解決できない、生成コマンドが非 0、期待成果物がない、または自動選択に失敗した場合は silent fallback せず、後述の「full モード失敗時の手動切替」に従って停止する。

## Subagent Contract

subagent として呼ぶ場合、メインエージェントは対象コレクションと生成対象（`thumbnail` / `main`）をリポジトリルート相対パスまたは値で入力に含める。候補画像生成前の承認が必要なら、メインが承認を得るまで subagent を起動しない。subagent は `workflow-state.json` を読み書きせず、`AskUserQuestion` を実行しない。候補画像の完了報告には `status: success | failure`、生成した `10-assets/thumbnail-vN.jpg/png` または `10-assets/main-vN.png/jpg` と `20-documentation/thumbnail-prompts.md` の絶対パス一覧、エラーを含める。メインは報告されたファイルの存在と生成対象を検証し、候補承認後の確定コピーと state 更新を行う。直接実行時は既存の承認・state 更新手順を変更しない。

## 勝ちパターン参照ゲート

最初に `data/thumbnail-iterate/champion.json` の有無を確認する。存在する場合は `.claude/skills/thumbnail-iterate/references/state-contract.md` を読み、`file` が repository 内の実ファイル（symlink 不可）で、現在の SHA-256 が `sha256` と一致することを検証する。失敗時は黙って external TTP へ fallback せず対象と不一致を表示して停止する。検証済み champion は **internal TTP** として external benchmark より先に参照画像と `validated_elements` をプロンプトへ反映する。このスキルから champion JSON を作成・更新しない。

プロンプト構築前に `collections/planning/*/20-documentation/thumbnail-test-history.json` と `collections/live/*/20-documentation/thumbnail-test-history.json` を列挙する。存在する各ファイルは `.claude/skills/thumbnail-test/references/history-schema.md` の `### Completed history` にある履歴構造検証コマンドだけで確認し、検証に失敗した履歴は黙って無視せず、対象パスとエラーを表示して修正を案内する。そのファイルを集計から除外してよいが、未検証値をプロンプトへ入れない。

検証済み entry のうち `result.status == "winner"` だけを対象に、`result.result_candidate_id` と一致する candidate の `composition.subject_position` / `composition.subject_scale` / `color_palette[]` / `text_amount` を値ごとに集計する。自由記述の `composition.scene` は結果説明にだけ使い、反復集計しない。

- 同じ値が 2 entry 以上で反復: 「検証済み勝ちパターン」として件数を示し、`Historical winners: subject_position=<value>, subject_scale=<value>, colors=<values>, text_amount=<value>.` のうち反復した field だけをプロンプト末尾へ追加する。既存の config 展開結果と TTP / anatomy / IP safety clause は変更・削除しない。
- 1 entry だけ: 「単発観測」として表示するが、プロンプトの必須方針にはしない。
- Winner が 0 件または履歴ファイルが 0 件: 「勝ちパターン履歴なし」と表示し、既存のプロンプト方針だけで続行する。

履歴の `performed_same` / `inconclusive` は強い方針へ還元しない。履歴の作成・追記は `/thumbnail-test` の責務であり、このスキルから変更しない。

**読み順**: 標準フローは「ワークフロー > 標準生成順序とファイル契約」から読む。「フォント安定化」章は標準経路（決定的合成）の設定詳細としてあわせて読む。「codex 経由の生成」章は `image_generation.provider: codex` のチャンネルのみ、「自動選択」章は該当機能を明示的に使うチャンネルのみ参照すればよい。

## 蓄積 insights 参照（lever=thumbnail）

プロンプト構築前に、過去サイクルの検証済みの学び（`data/insights.jsonl`、schema は `.claude/skills/analytics-analyze/references/insights-entry.schema.json` が単一ソース）のうちサムネイルに効くものを参照する。これは前提ガードではない。

```bash
jq -c 'select(.status == "open" and .lever == "thumbnail")' data/insights.jsonl
```

- 該当エントリがある場合は、生成前に `finding` / `recommended_action` / `evidence` をユーザーへ提示し、差分プロンプトの方針（テキストサイズ・構図・配色など）へ反映する。既存の config 展開結果と TTP / anatomy / IP safety clause は変更・削除しない
- `data/insights.jsonl` が存在しない、または該当エントリが 0 件の場合は「thumbnail insights なし」と表示して既存フローで続行する
- 本スキルは insights を提示・参照するだけで、`status` を含むエントリの書き換え・追記はしない（status 反映は `/collection-ideate`、追記は `/analytics-analyze` と `/flop-analysis` の責務）

## When to Use

- コレクションが確定し、サムネイル制作に着手するとき
- CTR 最適化されたサムネイルが必要なとき

## Quick Reference

| 引数 | 説明 | 例 |
|------|------|-----|
| `$ARGUMENTS` | テーマ・活動指定（省略可） | `/thumbnail fiddle playing` |
| 未指定 | `mode: full` は config → collection metadata の順で自動決定。それ以外は従来のテーマ確認 | `/thumbnail` |

## 想定 API call 数

| API | call 数 / 実行 | 変動要因 |
|---|---|---|
| 画像生成（Gemini / OpenAI、`image_generation.provider` で切替） | 候補 1 枚あたり max_attempts × 1 call（既定 1、失敗時の内部リトライで最大 ×3） | max_attempts / 候補枚数 / 再生成回数。provider が codex / gemini_cli は API 経路外で課金なし |
| 画像生成（textless 背景 main.png/jpg） | 承認後の再生成で +1 call | 再生成回数 |
| Vertex AI Gemini Vision（yt-thumbnail-check） | 画像 1 枚 = 1 call | `self_check.enabled: false` なら 0 |

- 上限 / 承認: 生成前に `confirm_cost()` が `cost_per_image_usd × attempts` を提示して y/N 確認する。`auto_selection.mode: full` では全自動 opt-in を事前同意として `-y` でこの質問を省略する。それ以外は従来どおり確認する。`self_check.enabled: false` で check をスキップできる。

## プロバイダー切り替え

`config/skills/thumbnail.yaml` の `image_generation.provider` で選択する:

| provider | 特徴 | 必要なシークレット |
|---|---|---|
| `gemini` | Gemini Image (Nano Banana 系) | ADC (`GOOGLE_CLOUD_PROJECT` は任意で上書き可) |
| `openai` | OpenAI gpt-image 系（CJK 文字描画が綺麗、16:9/9:16 ネイティブ対応） | `OPENAI_API_KEY` |
| `codex` | `codex-image.sh` 経由で ChatGPT サブスク認証を使う（GCP 課金なし） | `codex login status` が `Logged in using ChatGPT` |

OpenAI provider 使用時は `image_generation.openai.aspect_ratio` を `"16:9"` または `"9:16"` のいずれかに設定（thumbnail スキルは内部で 16:9 固定）。`image_generation.openai.quality` の既定は `medium`。`high` は 1 枚あたりの単価が数倍高いため、コストを許容できるチャンネルのみ `quality: high` を明示指定する。

`config/skills/thumbnail.yaml` の `image_generation.provider` が未設定の場合、デフォルトは `gemini`。channel-config 側で `image_generation.provider` が明示されている場合はそちらが優先される（既存の切り替え挙動は変更しない）。

## 障害時の provider fallback

Gemini API 障害、GCP 課金切れ、ADC 認証不備、quota 超過が疑われる場合は、自動切替せずに provider を明示変更して再実行する。

GCP 課金なしで進める場合:

```yaml
# config/skills/thumbnail.yaml
image_generation:
  provider: codex
```

その後、`uv run yt-generate-image` ではなく codex wrapper を使う:

```bash
bash .claude/skills/thumbnail/references/codex-image.sh --require-reference \
  "<thumbnail prompt>" \
  <collection-path>/10-assets/thumbnail-codex-v1.png \
  <reference-image-1>
```

OpenAI API に切り替える場合:

```yaml
image_generation:
  provider: openai
  openai:
    aspect_ratio: "16:9"
    # quality 未指定時の既定は medium。high は単価が数倍高いので明示 opt-in のみ
    # quality: high
```

Gemini / OpenAI の CLI 経路で全 attempt が失敗した場合、`uv run yt-generate-image` はこの fallback 章を案内する。生成物の品質差が出るため、自動で provider を切り替えて上書きすることはしない。

## codex 経由の生成

`image_generation.provider: codex` のチャンネルでは、`uv run yt-generate-image` ではなく `codex-image.sh` を正規の生成経路として使う。`ImageProvider` API 実装は持たないため、`uv run yt-generate-image` に誤配線した場合は明示エラーでこの shell 経路へ誘導される。

前提:
- codex CLI 0.131 系以降（旧 stdout プロトコル `generated image <id> <base64>` は 0.131 で削除済み）
- `codex login status` が `Logged in using ChatGPT` を返す
- `jq` が PATH 上にある（`--json` の JSONL 解析に使う）
- wrapper は生成前に最小 `codex exec --json` プローブで codex CLI とサーバー側デフォルトモデルの互換性を確認する。非互換時は生成を試みず、CLI version・検出モデル・アップグレード手順を stderr に出して停止する
- TTP 生成のため、3 引数目以降に参照画像を 1 件以上渡す
- ChatGPT サブスクの fair-use 上限は明文化されていないため、大量生成には使わない

直接実行例:

```bash
bash .claude/skills/thumbnail/references/codex-image.sh --require-reference \
  "TTP this reference thumbnail, then improve it into a stronger original thumbnail for cozy cafe morning coffee. Keep the winning layout and make the title readable on mobile." \
  collections/planning/sample/10-assets/thumbnail-codex-v1.png \
  data/thumbnail_compare/benchmark/<channel>/<reference>.jpg
```

複数候補を作る場合でも、1 回の `codex-image.sh --require-reference` 呼び出しには候補に対応する参照画像 1 枚だけを渡す。TTP 生成では参照画像 0 件で停止する。DistroKid cover などの汎用 codex 生成は `--require-reference` を付けない。

2 件以上の候補を同時生成する場合は、`id` / `prompt` / `output` / 任意の `reference` を持つ JSON 配列を manifest に保存し、batch launcher を使う。互換 preflight は batch 全体で 1 回だけ実行され、各 job は独立した出力先で単発 `codex-image.sh` の stale-artifact / PNG / MD5 gate を通る。一部失敗時も残りを完走し、最後に失敗一覧と非 0 exit を返す。

```bash
bash .claude/skills/thumbnail/references/codex-image-batch.sh \
  --manifest /tmp/codex-thumbnail-jobs.json
# 実行単位で上書きする場合だけ: --max-parallel 2
```

同時起動数は `image_generation.codex.max_parallel`（default `2`）で制御する。ChatGPT サブスクの fair-use 上限は非公開なので大量生成には使わない。通常は default `2` を維持し、rate limit / 利用制限を示す失敗時は `1` に下げる。`3` 以上はユーザーが今回の実行について明示した場合だけ使う。

TTP 参照画像から上位互換サムネを作る場合は、長い個別指定ではなく
`image_generation.codex.default_prompt_template` を使う。参照画像は mood reference
ではなく winning template として扱い、変える要素は `{title}` と品質改善
（mobile readability / face impact / no logos / no watermarks / no broken hands）に限定する。
日本語方針は「TTPを徹底してテキスト付き thumbnail を先に確定する」。

Codex 経路でも `image_generation.gemini.composition_rules` は自動的にプロンプトへ注入される。
`legend_motif` と `allowed_actions` を含む設定は参照画像より優先されるため、`{title}` に
レジェンド名や楽器・ポーズを手書きで重複指定しない。設定されたルールが Codex に渡らないまま
参照被写体を踏襲することは許容しない。

codex 経路でも標準ファイル契約は同じ:

1. ベンチマーク参照画像から、テキスト付き候補を `10-assets/thumbnail-codex-v1.png` に生成する。
2. 承認後、PNG 候補を JPEG に変換して `10-assets/thumbnail.jpg` として確定する（例: `sips -s format jpeg 10-assets/thumbnail-codex-v1.png --out 10-assets/thumbnail.jpg`）。`thumbnail.png` のまま確定する場合も、YouTube アップロード用の文字入りサムネであり、動画背景には使わない。確定直後に `uv run python .claude/skills/thumbnail/references/archive-approved-thumbnail.py <collection-path>` を実行する。
3. 確定した `thumbnail.jpg`（または `thumbnail.png`）を参照画像にして、テキストなし背景候補を `10-assets/main-v1.png` に AI 再生成する。
4. 承認後、`cp 10-assets/main-v1.png 10-assets/main.png` で textless 動画背景として確定する。

既定テンプレート:

```text
TTP this reference thumbnail, then improve it into a stronger original thumbnail.
Keep the winning layout, typography feel, character scale, color mood, texture, and energy.
Make it cleaner, more readable on mobile, stronger face impact, no logos, no watermarks, no broken hands.
Use the title {title}.
```

このテンプレートは `config.default.yaml` の `image_generation.codex.default_prompt_template` と完全一致させる（`tests/test_thumbnail_skill_assets.py` で機械担保）。

**`{title}` の意味論**: `{title}`（`codex-prompt.py` の `title` 引数）に渡すのは**サムネに焼くテキスト（見出し + 短いサブタイトル）だけ**。動画タイトル全文を渡さない — 旧テンプレート運用時に動画タイトル全文がそのまま画像に焼き込まれた事故があり、その再発防止のための契約。

内部実装の要約:

- wrapper は `codex --version` で CLI version を控え、ログイン確認後に `codex exec --json --skip-git-repo-check -- "Reply with exactly codex-model-compat-ok."` の最小プローブを実行する。互換性エラーなら本番生成を呼ばず、`npm install -g @openai/codex@latest` / `brew upgrade codex` / `bun add -g @openai/codex@latest` を案内して非0終了する
- wrapper は `codex exec --json --sandbox workspace-write --add-dir <out_dir> --skip-git-repo-check` で起動する
- 受け取った prompt 末尾に `Generate a new image with the image_generation tool. Do not copy any provided reference image; produce a freshly generated PNG. After generation, copy the produced PNG to <out>. Then reply with exactly <out>.` を自動付与する（後述の reference cp failure mode を抑止するため、tool 呼び出しと「reference を copy するな」を明示）
- agent 自身が `~/.codex/generated_images/<thread_id>/ig_*.png` から `<out>` へ `cp` し、最終 `agent_message.text` で `<out>` を返す
- wrapper は事前に `rm -f <out>` で stale artifact を確実に削除してから `codex exec` を起動する
- wrapper は JSONL を `jq` でフィルタし、`tail -n 1` で最後の `agent_message.text` を取得。これを JSON プロトコル契約として `<out>` と完全一致することを検証し（不一致なら非0終了）、その後 `<out>` の存在・サイズと PNG ヘッダ（`89504e470d0a1a0a`）を検証する
- reference 画像を渡したときは、wrapper が事前に各 reference の MD5 を控えておき、最終的に `<out>` の MD5 と一致したら「agent が `image_generation` tool を skip して reference をそのまま cp した」failure mode として非0終了する
- wrapper 側で指定した `<out>` がそのまま最終 path として使えるので、生成後に呼び出し側で path 解決し直す必要はない

運用上の注意:

- **prompt は短く保つ**: 長すぎる prompt は agent が `image_generation` tool 呼び出しを skip して path だけ echo する failure mode に陥る。TTP 参照画像つきでは `image_generation.codex.default_prompt_template` を使い、`{title}` だけを差し替える。失敗したら短縮を最優先で試す
- **reference 画像つきは prompt で「変更点」を明示する**: 「reference を参考に」程度の弱い指示だと agent が `image_generation` tool を skip して reference を `<out>` に cp するだけで終わる failure mode がある。wrapper の自動付与文 + MD5 一致検証で抑止しているが、prompt 側でも reference からの差分（色味の参考 / 構図だけ流用 / 主役を差し替え 等）を明示しておくと安定する
- 失敗時 wrapper は codex CLI version・デフォルトモデル推定値・`agent_message (最終)`・codex stderr の末尾 30 行を診断 dump するので、これを見て CLI upgrade / prompt 短縮 / 参照画像見直しに切り替える
- **NG ワード事前検査 (#1664)**: wrapper は `codex exec` 起動前に prompt を `image_generation.gemini.forbid_keywords` と照合し、ヒットしたら即エラー終了する。キーワードは環境変数 `CODEX_IMAGE_FORBID_KEYWORDS`（改行区切り）が非空ならそれを優先し、未設定なら `uv run python` で merged skill-config から自動解決する。チャンネルリポジトリ外での単体実行など config 文脈が無い場合は従来どおり no-op

この経路のスコープ:
- `uv run yt-generate-image` の API 呼び出しは使わない
- `ImageProvider` 実装は持たない
- wrapper 自体のリトライなし
- GCP 課金なし。ChatGPT サブスクの fair-use 対象で、`cost_per_image_usd` は通常 `null`
- `cost_tracker` 連携なし。生成回数は shell 実行ログで確認する

## Channel Adaptation

**すべての設定は `config/skills/thumbnail.yaml` から読み取る。**
スキル内にチャンネル固有のハードコードはしない。作業前に Read tool（Codex では同等のファイル閲覧）で
`.claude/skills/thumbnail/config.default.yaml` とチャンネル側上書きの `config/skills/thumbnail.yaml`
を開き、deep-merge 後の実効値を確認する。

実行前に以下を確認:

1. `image_generation.provider` → 使用するプロバイダー（`gemini` / `openai` / `codex`）
2. `image_generation.gemini.model` → 使用する Gemini モデル
3. `image_generation.gemini.style` → スタイル説明（参照画像ベース）
4. `image_generation.gemini.prompt_prefix` → プロンプト冒頭の固定文（キャラ描写等）
5. `image_generation.gemini.reference_images.default` → 同じベンチマークチャンネル内の参照画像リスト（single_step では必須）
6. `image_generation.gemini.fixed_character` → 固定キャラの設定（あればキャラ固定モード）
7. `image_generation.gemini.composition_rules` → 構図ルール（既定は `text_lines` のみ。旧個別キーは deprecated、意図は `diff_prompt_template` 本文へ）
8. `image_generation.gemini.thumbnail_text` → テキストオーバーレイの設定（`text_overlay_prompt` が単一の入口。旧個別フィールドは deprecated）
9. `image_generation.gemini.generation_mode` → 生成モード（後述）
10. `image_generation.gemini.brand_background` → チャンネル統一背景色（single_step / diff_from_reference で使用）
11. `image_generation.gemini.color_themes` → テーマ別カラーパレット（single_step モードで差し替え）
12. `archive.enabled` → 承認済みサムネイルのギャラリー保存（既定 `false`）
13. `image_generation.gemini.forbid_keywords` → NG ワードリスト（最終プロンプトに大小文字無視で部分一致すると生成前にエラー停止。未設定・空リストなら no-op。provider 非依存で Gemini / codex の両入口に効く）
14. `image_generation.auto_selection.enabled` / `mode` → 承認ゲートの分岐（`mode` 未設定時は `selection_only`）
15. `ab_test.enabled` / `ab_test.patterns` → Studio Test & compare 用 pattern（既定 `false`。有効時は 1〜3 件の `name` / `variation`）

## 生成モード判定

`image_generation.gemini.generation_mode` を確認:

| モード | 説明 |
|---|---|
| `single_step`（**デフォルト**・TTP 推奨）| テキスト付き参照画像から差分のみ指示し、YouTube 用のテキスト付きサムネ候補を 1 ステップで生成。ベンチマーク模倣（TTP）の標準実装 |
| `diff_from_reference` | 既存キャラ画像を参照に差分指示 |
| `two_phase` | 従来方式フォールバック。既存参照を選択 → テキスト付き `thumbnail.jpg` 確定 → 承認済み `thumbnail.jpg` から textless `main.png/jpg` 再生成 |

### 参照画像モード（必須）

参照画像を渡して TTP の勝ちパターンを踏襲する方式。`single_step` では参照画像なしの生成は行わない。

```bash
uv run yt-generate-image \
  --ttp-strict-references \
  --prompt "<prompt_prefix を含むプロンプト>" \
  --reference <channel_dir>/<reference_images.default> \
  --output <collection-path>/10-assets/thumbnail-v1.jpg -y
```

**参照画像の選択ロジック**:
- `reference_images.default` には同じベンチマークチャンネル内の別サムネイル画像を並べる
- `--max-attempts N` のときは N 枚以上のユニーク参照画像が必要。不足・重複・同一参照の再利用はエラー
- `--reference-index N` を指定した場合のみ単一参照固定になり、attempt 数は 1 に固定される
- `path_base: "channel_dir"` の場合、パスはプロジェクトルートからの相対パス
- `--reference` 使用時は `composition_prefix` が自動スキップされる（generate_image.py 修正済み）

## プロンプト構築

プロンプト指示の解説はこのセクションを単一ソースとし、各モードの節（Single-Step / Two-Phase）には差分だけを書く。補足の原則は `references/prompting.md`、短い差分プロンプト例は `references/sample-prompts.md` を参照する。

**原則: 参照画像主導 + 最小限のキーワード。** TTP では勝ちパターンは参照画像が運ぶ。プロンプトに指示を積むほど参照画像の支配力が薄れるため、プロンプトにはテーマ・主題・スタイルなど最小限のキーワードと、サムネに焼くタイトルだけを書く。

**既定の組み立て（provider 共通）:**

1. `image_generation.gemini.diff_prompt_template`（TTP 方針行 + `{title_line1}` / `{title_line2}`）のプレースホルダを置換する
2. 既定で展開する clause は `${ip_safety_clause}` の 1 つだけ（#569、TTP で常時挿入必須）

opt-in clause（`variation_clause` / `style_lock_clause` / `text_strip_clause` / `anatomy_clause` / `typography_clause`）は既定空文字。必要なチャンネルだけ `config/skills/thumbnail.yaml` に本文を設定し、自前の `diff_prompt_template` で展開する（推奨文面は `config.default.yaml` のコメント参照）。複数の clause を同時に積み上げない — バリエーション vs スタイル固定 vs テキスト除去の指示は相互に打ち消し合い、参照画像の支配力を薄める。

**最終プロンプト例（TTP / 既定 config でプロバイダーへ渡る全文）:**

```text
TTP this reference thumbnail, then improve it into a stronger original thumbnail.
Keep the winning layout, typography feel, character scale, color mood, texture, and energy.
Make it cleaner, more readable on mobile, stronger face impact, no logos, no watermarks, no broken hands.
Use the title Midnight Jazz Rainy Tokyo Mood.
Do not reproduce any signature, autograph, handwritten name, watermark,
logo, brand mark, channel badge, copyright notice, or identifying mark
from the reference image. Keep all corners clean and free of such marks.
```

参照画像 + この最小プロンプトだけで TTP は機能する。テーマ固有の差分（色・オブジェクト）を足す場合も 1〜2 文にとどめる。

**モード別差分:**

- **single_step（テキスト付き thumbnail 候補）**: 既定の組み立てをそのまま使う。手順の詳細は「Single-Step / TTP モード > プロンプト構築」
- **textless main 再生成**: 承認済み `thumbnail.jpg` を参照し、除去指示（`text_strip_clause` を設定していれば展開、未設定なら `Remove all text` 相当を明記）だけを足す
- **two_phase（テキストオーバーレイ）**: `thumbnail_text.text_overlay_prompt` が単一の入口。旧個別フィールド（`channel_name_style` / `title_format` / `title_prefix` / `copy_position` / `color` / `decoration`）は deprecated で、位置・色・装飾の意図は `text_overlay_prompt` の本文に直接書く（段階的廃止 #1702。override は当面 deep-merge され続けるが、config ロード時に DeprecationWarning が出る）

> 将来検討（issue #654）: imagegen の 14 項目 Shared prompt schema 形式と既存 skill-config の bridge ヘルパが `references/prompt-schema.md` および `youtube_automation.utils.image_provider.prompt_schema` に試験導入されている。実本番フローからは未接続。設計判断は `docs/skill-design/ADR-001-thumbnail-prompt-schema.md`。

## ワークフロー

### 標準生成順序とファイル契約

`/thumbnail` の標準手順は、**textless 動画背景の生成 → `yt-thumbnail-text` による実フォント合成**の 2 段構成で進める（#1907）。タイトル文字は AI に焼き込ませず、承認済みの textless 背景へ実フォント（Pillow 描画）で決定的に合成する。同一の背景・テキスト・設定なら常に同一出力になり、AI っぽい書体の揺れが発生しない。

`docs/benchmarks/thumbnail-analysis.md` が存在する場合は、生成前に Read（Codex では同等のファイル閲覧）で開き、`## /thumbnail への TTP 推奨事項` の「維持する構造」「テーマに合わせて差し替える要素」「避ける要素」「参照候補」を、参照画像選定と差分プロンプトの入力にする。存在せず競合サムネイルの勝ちパターンを先に深掘りする場合は `/thumbnail-research` を実行する。

1. 「thumbnail-text-profile 適用」節の手順で、フォント選定・コピー生成制約・配置を確定する（profile 不在なら実効デフォルト値のまま進む。エラーにしない）。
2. ベンチマーク先サムネを参照画像にして、`thumbnail-analysis.md` がある場合はその勝ちパターンも使い、構図・色温度・主役スケール・背景テクスチャを踏襲した textless 背景候補 `main-v*.png/jpg` を生成する。差分プロンプトには `single_step.text_strip_clause` 相当の除去指示を展開し、タイトル文字・字幕・ロゴ・透かしを焼き込ませない（参照画像の選定・プロンプト構築・CLI 引数は「Single-Step / TTP モード」章の機構を流用する）。
3. 背景候補を `open` と `uv run yt-thumbnail-check <collection-path>/10-assets/main-v1.png --json` で確認する。`mode: full` では `open` と AskUserQuestion を省略し、check が exit 0 かつ期待した画像ファイルが存在するときに `cp main-v1.png main.png` で確定する。それ以外では従来どおりユーザー承認後に `10-assets/main.png` または `10-assets/main.jpg` として確定する。
4. 承認済み textless 背景に、profile 適用済みの実効 config で実フォントのタイトルを合成し、テキスト付き候補を作る:

```bash
uv run yt-thumbnail-text \
  --background <collection-path>/10-assets/main.png \
  --title "<Title Line 1>" --title "<Title Line 2>" \
  --channel-name "<channel_name>" \
  --output <collection-path>/10-assets/thumbnail-v1.jpg
```

5. テキスト付き最終サムネを `10-assets/thumbnail.jpg` として確定する。`mode: full` では候補承認を求めず「自動選択」章の `yt-thumbnail-auto-select <collection-path> --apply` で確定する。それ以外では `/thumbnail-compare` で 320px 視認性検証後にユーザー承認し、`cp thumbnail-v1.jpg thumbnail.jpg` で確定して `uv run python .claude/skills/thumbnail/references/archive-approved-thumbnail.py <collection-path>` を実行する。自動確定後の `/thumbnail-compare` は省略せず別途実行する。
6. `config/skills/loop-video.yaml::enabled: true` のチャンネルでは、テキストなし `main.png/jpg` を `/loop-video` に渡して `loop.mp4` を生成する。
7. `config/skills/loop-video.yaml::enabled: false` のチャンネルでは Veo を実行せず、テキストなし `main.png/jpg` を静止画背景として `/videoup` に渡す。

`thumbnail.jpg` はアップロード用の文字入りサムネイル、`main.png/jpg` は動画背景・loop-video 入力用の文字なし素材として扱う。両者を同一画像で代用しない。決定的合成では同一の textless 背景がテキスト合成の入力と動画背景を兼ねるが、成果物としては別ファイルで確定する。

**AI 焼き込み経路（fallback・非既定）**: 手書き風タイポグラフィなど実フォントで再現できない表現を運用者が明示的に選んだときだけ、従来の「テキスト付き YouTube サムネ → 承認済みサムネから textless 動画背景」の順で Single-Step / Two-Phase / codex 章のテキスト付き候補生成手順を使う（経路は残すが #1907 では改修しない）。この場合、書体の厳密な再現は保証されないことをユーザーに伝える。

### Test & compare 用 A/B pattern（opt-in）

`ab_test` 未設定または `enabled: false` では、この節を実行せず標準の `thumbnail.jpg` 1 枚だけを確定する。既存コマンド・ファイル・承認・state 契約は変えない。

有効化はチャンネル側 `config/skills/thumbnail.yaml` で行う。`patterns` は YouTube Studio の上限に合わせて 1〜3 件、`name` は英小文字・数字・ハイフン・アンダースコアの一意な名前、`variation` は空でない pattern 固有 clause とする。0 件・4 件以上・不正 name・重複 name・空 variation は、画像生成 API を呼ぶ前に `ConfigError` で理由付き停止する。

```yaml
ab_test:
  enabled: true
  patterns:
    - name: a
      variation: "Use a close-up composition with a larger subject."
    - name: b
      variation: "Keep the composition and use a cool blue color palette."
    - name: c
      variation: "Keep the visual treatment and use a shorter title copy."
```

有効時は次の順序で進める。

1. 各 pattern の base prompt は同じ `image_generation.gemini.diff_prompt_template` 合成結果を使う。`yt-generate-image --ab-pattern <name>` が対応する `variation` をその最終プロンプト末尾へ追加する。pattern 間で base prompt、TTP / anatomy / IP safety clause を削除・変更しない。
2. pattern ごとに候補を別名で生成する。AI 焼き込み経路の例:

```bash
uv run yt-generate-image \
  --ttp-strict-references \
  --reference <ref-a> --prompt "<diff_prompt_template 展開済み base prompt>" \
  --ab-pattern a --output <collection-path>/10-assets/thumbnail-a-v1.jpg -y
```

   決定的合成経路では `variation` の構図・配色を textless 背景候補の生成へ反映し、コピー差分は pattern ごとの `yt-thumbnail-text --title ... --output thumbnail-<name>-v1.jpg` に反映する。`mode: full` 以外では各 pattern で `/thumbnail-compare` と目視確認を行い、個別にユーザー承認を得る。`full` では AskUserQuestion を省略し、期待候補が存在することを検証して自動確定した後、全 pattern を `/thumbnail-compare` へ回す。
3. `full` 以外では承認済み候補だけを、`full` では存在検証に成功した候補だけを `10-assets/thumbnail-<name>.jpg` へ確定する。全 pattern の承認が揃うまでは `thumbnail.approved` を `true` にしない（`full` では全 pattern の自動確定完了を承認完了として扱う）。
4. 全 pattern 確定後、先頭 pattern を互換出力へコピーする（例: `cmp thumbnail-a.jpg thumbnail.jpg` が成功する内容にする）。`/video-upload` は従来どおり `thumbnail.jpg` を使うため変更不要。
5. `20-documentation/thumbnail-prompts.md` の `A/B Test Pattern Prompts` に、全 pattern の name / final output / variation / API へ渡した最終プロンプトを保存する。
6. YouTube Studio で対象動画のサムネイル編集を開き、**Test & compare** から最大 3 枚の `thumbnail-<name>.jpg` を手動登録する。公式 API はないため、このスキルから自動登録しない。

### thumbnail-text-profile 適用（#1907）

`/channel-new` 分析モードが生成する `docs/benchmarks/thumbnail-text-profile.md`（`schema_version: 1`。見出し・キーの単一ソースは `.claude/skills/channel-new/references/analysis-mode.md` の Step 4）を読み、決定的合成の入力へ変換する。

これは前提ガードではない。ファイルが存在しない、またはスキーマの見出し・必須キーを満たさない場合は「thumbnail-text-profile なし」と表示し、`config.default.yaml` の現行デフォルト値（チャンネル上書きがあれば deep-merge 後の実効値)のまま標準フローを続行する。エラーで停止しない。

profile が存在する場合、3 セクションを次のとおり適用する:

| profile セクション | 適用先 | 変換 |
|---|---|---|
| `## font_tendency` | `image_generation.gemini.thumbnail_text.overlay.font.title`（必要なら `overlay.title.stroke_width` / `stroke_color` も） | 下流環境の既存ローカルフォント（日本語対応 .ttf/.otf/.ttc）から `typeface_classification` / `weight` に近い書体を選定する。`outline: present` なら縁取り（`stroke_width` > 0）を維持する |
| `## text_content_pattern` | `--title` に渡すコピー生成の制約（config 変更なし） | タイトル行を `line_count_range` / `languages` / `character_count_range` / `copy_pattern` に従って生成する。競合のチャンネル名・コレクション名・シリーズ名・コピー原文（固有の文言）は使わない |
| `## placement_tendency` | `overlay.layout.anchor` / `margin_x` / `margin_y` | `anchor_position` を 9 アンカー（`top|center|bottom` - `left|center|right`、中央は `center`）のいずれかへ、`margin` をピクセル値へ変換する |

- 値が `unknown` のキーは適用せず、該当項目は実効デフォルト値のまま進む
- フォント選定は**ローカルに既にあるファイルだけ**を対象にする（`fc-list :lang=ja file family style`、`/System/Library/Fonts/`・`~/Library/Fonts/`・`<channel_dir>/assets/fonts/` の列挙など）。フォントファイルの同梱・自動ダウンロードはしない。日本語対応の候補が見つからない場合は入手先（Google Fonts 等）と配置先 `<channel_dir>/assets/fonts/` を案内し、配置を待つか AI 焼き込み経路へ fallback するかをユーザーに確認する
- profile 不在でも `overlay.font.title` が未設定の場合は、同じローカルフォント選定手順で日本語対応フォントを 1 つ選んで設定してから合成に進む（profile 由来の傾向は適用しない。これにより分析モード未実行チャンネルでもフォントの揺れだけは解消される）
- 変換した値は `config/skills/thumbnail.yaml` の該当キーへ、設定内容と根拠（profile のどの傾向か）をユーザーへ提示し承認を得てから書き込む。「設定読み込みゲート」の「勝手に作成しない」は読み取り時の原則であり、この手順は承認を得た明示的な更新として扱う。書き込み後は deep-merge 後の実効値を再確認してから合成に進む

### 承認済みサムネイルのアーカイブ

`archive.enabled: false` が既定で、従来どおりギャラリーを作成しない。過去作サムネを TTP テンプレートとして蓄積するチャンネルだけ、`config/skills/thumbnail.yaml` で opt-in する:

```yaml
archive:
  enabled: true
```

決定的合成（フォント固定・標準）、AI 焼き込みの手動承認、codex、Two-Phase の各経路では、それぞれの既存の検証・承認順序を変えず、最終 `10-assets/thumbnail.jpg` または `thumbnail.png` の確定直後に次の共通コマンドを 1 回実行する:

```bash
uv run python .claude/skills/thumbnail/references/archive-approved-thumbnail.py <collection-path>
```

自動選択では、既存どおりユーザー承認を省略し、`yt-thumbnail-auto-select --apply` が確定直後にこの処理を内部で実行してから workflow-state を更新する。有効時は `assets/thumbnail-gallery/<collection-dir-name>.<ext>` へ元の拡張子と内容のままコピーする。同じコレクションを再承認した場合は最新の確定サムネで置き換える。無効時は副作用なしで正常終了する。設定不正、確定サムネ欠落、シンボリックリンク、コピー失敗は明示エラーで停止し、アーカイブ成功として扱わない。アーカイブまたは workflow-state 更新の失敗時、自動選択は確定サムネイル、ギャラリー、workflow-state を元に戻す。自動確定後の `/thumbnail-compare` と後工程の順序は従来どおり変更しない。

### Single-Step / TTP モード（`generation_mode: "single_step"`、デフォルト・推奨）

> **#1907 以降の位置づけ**: 標準フローはこの章の TTP 機構（参照画像選定・差分プロンプト構築・CLI 引数）を **textless 背景候補 `main-v*.png/jpg` の生成**に流用し、テキストは `yt-thumbnail-text` で合成する。この章に書かれた「テキスト付き候補を先に生成 → 承認済み `thumbnail.jpg` から textless 再生成」の順序は **AI 焼き込み経路（fallback・非既定）**の手順であり、運用者が明示的に選んだときだけ使う。

ベンチマーク模倣（**TTP**: trace / imitate）の標準実装。テキスト付きベンチマーク参照画像（背景テクスチャ・オブジェクト配置・主役スケール・文字レイアウトを含む）を参照にして、**維持する勝ちパターンと差し替えるタイトルだけ**をプロンプトで指示する。1 回目の生成では、YouTube 用のテキスト付き `thumbnail-v*.jpg/png` 候補を作る。承認後、その `thumbnail.jpg` から textless `main-v*.png/jpg` を再生成する。

**重要**: 参照画像と同じ要素（レイアウト、固定オブジェクト、テキスト配置）はプロンプトに含めない。差分のみを指示することで、参照画像のクオリティを維持しつつ変更が正しく反映される。コピーではなくバリエーションを作るのがゴール。

**IP / 版権セーフティ (#569)**: TTP は参照画像のレイアウト・テクスチャ・オブジェクト配置を強く転写するため、ベンチマーク側に焼き込まれた**署名（サイン）・透かし・ロゴ・チャンネルバッジ・著作権表記等の識別マークがそのまま再現される事故が起きやすい**。プロンプト構築時は必ず標準除外 clause `no signature, no autograph, no watermark, no logo, no brand mark, clean corners` を含めること（config: `image_generation.gemini.single_step.ip_safety_clause`）。**参照元の識別マークはコピーしない — 版権 / IP リスクを生むため**、たとえ参照画像のスタイルガイドとして優秀でもサインや筆記体の署名は転写対象から外す。

#### プリフライト

`generation_mode: "single_step"` で `--reference` を指定せずに `uv run yt-generate-image` を起動するとエラー中断する。次の対処が必要:

1. **skill-config に `reference_images.default` が未設定** → `config/skills/thumbnail.yaml` の `image_generation.gemini.reference_images.default` にベンチマークサムネのパス（文字列 1 件 or list 複数件）を設定
2. **設定はあるが CLI 引数に展開していない** → `--reference <path>` で渡す。list なら `--reference A --reference B --reference C` のように複数指定
3. **`--max-attempts N` に参照画像が足りない** → 同じベンチマークチャンネル内の別サムネイル画像を N 枚以上に増やす。ローテーションで同じ参照へ戻す運用はしない

#### 参照画像（複数 + ローテーション）

`reference_images.default` は同じベンチマークチャンネル内の複数サムネ候補を list で指定する。`--max-attempts N` で N 候補を出す場合、各 attempt は別参照画像 1 枚を使う。参照画像が N 枚未満、同じ画像の重複、`--no-rotate` による先頭固定はいずれもエラーになる。

`reference_images.dedup_recent_collections`（既定 `5`）は、各 collection の `20-documentation/thumbnail-prompts.md` に保存された `Reference Assignments` をローテーション履歴として使う。参照プールが候補数より大きい場合は、全参照が採用候補になる前に同じ先頭候補を再利用しない。プール自体が候補数未満なら参照画像の追加を促すエラーで停止し、履歴のない旧コレクションは無視、履歴ファイルの読取障害はエラーで停止する。`0` で履歴による除外を無効化できる。選定ロジックの正は `youtube_automation.utils.thumbnail_references.plan_ttp_reference_assignments` とする。

別チャンネル由来の参照画像や stock 画像を混ぜる場合は、TTP 参照プールとは別スコープとして扱う。混在させるなら `config/skills/thumbnail.yaml` 側で明示し、生成ログの `benchmark_channel=` と `thumbnail-prompts.md` の attempt 別参照欄で追跡できるようにする。

| CLI 引数 | 用途 |
|---|---|
| `--max-attempts N` | 試行回数。各 attempt で別参照を 1 枚ずつ割当、出力は `-vN` で別保存 |
| `--no-rotate` | single_step の複数候補では使用不可（同一参照再利用になるためエラー） |
| `--reference-index N` | 特定の参照のみ使用（ローテーション無効、attempt=1） |

config 側のデフォルトは `image_generation.gemini.single_step.{max_attempts, rotate}` で設定可能。

#### プロンプト構築

TTP 生成方針は provider によらず共通: 参照サムネを winning template として扱い、winning layout を維持したまま品質改善（mobile readability / face impact / no logos / no watermarks / no broken hands）だけを指示する（codex 節の「既定テンプレート」と同じ方針。#2070）。`config.default.yaml` の `image_generation.gemini.diff_prompt_template` 既定値はこの方針行を codex 既定テンプレートと同期しており、チャンネル側 `config/skills/thumbnail.yaml` の `diff_prompt_template` があればそちらが常に優先される。`provider: gemini_cli`（サブスク認証の gemini CLI 経由）も同じ `diff_prompt_template` とこの構築手順を共有し、CLI ラッパーはプロンプトを方針を変えずそのまま透過する（model / CLI protocol のみ異なる。#2071、`tests/test_image_provider_gemini_cli.py` の contract test で機械担保）。

1. `image_generation.gemini.color_themes` からテーマのカラー設定を取得
2. `image_generation.gemini.diff_prompt_template` のプレースホルダーを置換してプロンプト構築:
   - `{background}`: カラーテーマの背景色（未指定時は `image_generation.gemini.brand_background` を使用）
   - `{candle}`, `{cocktail_description}` などオブジェクト系プレースホルダ: `ideate.objects` や `color_themes` 配下の値
   - `{title_line1}`, `{title_line2}`: コレクションタイトル
3. 既定で展開する clause は `${ip_safety_clause}` の 1 つだけ。**`ip_safety_clause` (#569) は TTP モードで常時挿入必須** — チャンネル側で `diff_prompt_template` を組み立てる場合も必ず展開し、参照元の署名・透かし・ロゴが焼き込まれないようにする。空文字に上書きしての無効化は版権 / IP リスクを生むため非推奨。その他の opt-in clause（`variation_clause` / `style_lock_clause` / `typography_clause` / `anatomy_clause`）は既定空文字で、必要なチャンネルだけ override に本文を設定して展開する。キャラ + 手が写る構図で指の破綻（融合・本数異常・溶融）が出る場合は `anatomy_clause` を設定して展開する（#570）。複数 clause の同時積み上げは避ける（「プロンプト構築」章の原則参照）
4. textless `main-v*.png/jpg` 再生成用プロンプトは、承認済み `thumbnail.jpg` を参照してから `single_step.text_strip_clause`（設定時）/ `Remove all text` 相当の除去指示を明示する。テキスト付き `thumbnail-v*.jpg/png` の初回生成プロンプトには展開しない

#### 生成コマンド

`reference_images.default` から `--reference` 引数を組み立てる。default では同じベンチマークチャンネル内の別サムネイル画像のみを使う。
`config/skills/thumbnail.yaml` の `image_generation.gemini.reference_images.default` を Read tool で確認し、
各パス（`CHANNEL_DIR` 相対）を絶対パスに解決して `--reference` を列挙する:

```bash
uv run yt-generate-image \
  --reference <CHANNEL_DIR>/<default[0]> \
  --reference <CHANNEL_DIR>/<default[1]> \
  --ttp-strict-references \
  --max-attempts 3 \
  --prompt "<diff_prompt_template を置換したプロンプト>" \
  --output <collection-path>/10-assets/thumbnail-v1.jpg -y
```

stock 画像を別スコープとして混ぜたい場合だけ、`config/skills/thumbnail.yaml` の `image_generation.gemini.reference_images.stock.enabled: true` を明示し、採用ログ stderr の `[INFO] stock 採用: ...` を保存する。stock を混ぜると「同じベンチマークチャンネルの別サムネ」ではなくなるため、生成後の `thumbnail-prompts.md` に attempt ごとの参照元を必ず記録する。

4. `open` でプレビュー → `/thumbnail-compare` で 320px 視認性検証 → ユーザー承認 → `cp thumbnail-v1.jpg thumbnail.jpg` → `uv run python .claude/skills/thumbnail/references/archive-approved-thumbnail.py <collection-path>`
5. 承認済み `thumbnail.jpg` を参照画像にして、textless 動画背景を AI 再生成:

```bash
COLLECTION_PATH="<collection-path>"
TEXTLESS_PROMPT="$(cat <<'PROMPT'
<textless background regeneration prompt>
PROMPT
)"

uv run yt-generate-image \
  --reference "${COLLECTION_PATH}/10-assets/thumbnail.jpg" \
  --prompt "$TEXTLESS_PROMPT" \
  --output "${COLLECTION_PATH}/10-assets/main-v1.png" -y
```

textless 再生成プロンプトでは、承認済みサムネの構図・主役スケール・光・色温度・背景テクスチャを維持し、タイトル文字・字幕・ロゴ・透かし・タイポグラフィだけを除去する。新しい文字や主役を追加しないことを明示する。

6. `open` でプレビュー → `uv run yt-thumbnail-check <collection-path>/10-assets/main-v1.png --json` → ユーザー承認 → `cp main-v1.png main.png`（JPEG で確定する運用では `main-v1.jpg` → `main.jpg` に揃える。拡張子を偽装しない）
7. `20-documentation/thumbnail-prompts.md` に、テキストなし背景生成プロンプトとテキスト付き生成プロンプトの両方を保存する

#### 運用上の注意

- **リトライ前提**: 画像生成プロバイダーは同一プロンプトでも瞬発的にエラーを返す。各 attempt 内で内蔵リトライ最大 2 回が走る
- **テキスト付き版の先行確定**: `thumbnail.jpg` は文字入り YouTube サムネとして最初に承認する。`main.png/jpg` は承認済み `thumbnail.jpg` から後続生成する動画背景素材
- **テキスト除去**: textless 再生成では、承認済みサムネ内のタイトル・字幕・チャンネル名・ロゴ・タイポグラフィが残りやすい。`text_strip_clause` / `Remove all text` を明示し、文字情報は `thumbnail.jpg` だけで扱う
- **コスト**: 事前見積もりは `config/skills/thumbnail.yaml` の `image_generation.<provider>.cost_per_image_usd` を指定したときのみ CLI 表示に出る。未指定なら「不明」と表示され、実コストは GCP Cloud Console > Billing で確認する（`max_attempts × 1 リクエスト` ＋ 各 attempt で内蔵リトライ最大 2 回）

#### 失敗時の対処

雰囲気が出ない場合、ChatGPT 等の外部ツールで手動生成して `main.png` にコピーする運用は廃止。ツール内で完結する代替策:

1. `--reference-index N` で特定のベンチマーク参照に固定して試す
2. `reference_images.default` の list を見直し、別のベンチマーク候補を追加
3. `diff_prompt_template` の差分指示を見直し（特に `variation_clause` / `style_lock_clause` のオン/オフ）

差分プロンプトの具体例は skill-config の `image_generation.gemini.diff_prompt_template` を参照し、チャンネル固有のオブジェクト・カラーを埋める。

> **参考（オペレーター向け・実行時は無視してよい）**: `daiki-beppu/rjn` の `config/skills/thumbnail.yaml` が参考になる（jazzgak チャンネルの 5 サムネを `color_themes.<theme>.reference_image` で多軸切替）。private リポジトリのため下流リポジトリの実行者はアクセスできない。取得を試みないこと。

#### TTP プリフライト・チェックリスト

コレクション着手時は、本章上部のプロンプト構築や生成コマンドへ進む**前**に必ずここを通す。1 項目でも欠けると TTP モードの再現性が落ちる。

- [ ] `reference_images.default` が設定済みで、同じベンチマークチャンネル内の別サムネイル画像を `--max-attempts` 以上の枚数だけ指している（`config/skills/thumbnail.yaml` の `image_generation.gemini.reference_images.default` を Read tool で確認する）
- [ ] `image_generation.gemini.generation_mode` が `generation_mode: "single_step"` になっている。`two_phase` / `diff_from_reference` を使うなら理由を明示する
- [ ] 同じ参照画像の重複、参照不足、`--no-rotate` による複数候補生成になっていない
- [ ] `diff_prompt_template` に参照と重複する要素（レイアウト・固定オブジェクト・テキスト配置・既知の色味）を書いていない。差分のみを記述する
- [ ] `diff_prompt_template` に `${ip_safety_clause}` 相当の除外句（`no signature, no autograph, no watermark, no logo, no brand mark, clean corners`）を含めている (#569)。参照元ベンチマークサムネに署名・サイン・透かし・チャンネルロゴ等の識別マークがある場合は特に必須
- [ ] `workflow-state.json::planning.music.*`（`atmosphere` / `style` 等）は**音楽用フィールド**であり、その値を image prompt に転写していない (#1664)。画像の情景・被写体は `diff_prompt_template` とチャンネル規約（`fixed_character` / `composition_rules`）から組み立てる。音楽ムードを画像に反映したい場合も文言をそのままコピーせず、チャンネル規約に適合する表現へ翻訳する
- [ ] `image_generation.gemini.forbid_keywords` にチャンネル規約違反の NG ワード（過去に混入事故のあった表現）が登録されているか確認した。未登録のチャンネルは no-op のまま進めてよい
- [ ] stock 合成（#364）の扱いを確認し、`image_generation.gemini.reference_images.stock.enabled` が意図どおりになっている
- [ ] ベンチマーク参照からテキスト付き `thumbnail-v1.jpg/png` を生成し、構図・色温度・背景テクスチャ・タイトル可読性をユーザー承認する段取りになっている
- [ ] 承認済み `thumbnail.jpg` を参照して textless `main-v1.png/jpg` を再生成する段取りになっている
- [ ] サムネ承認**前**に `/thumbnail-compare` を実行し、320px 縮小時の文字可読性・コントラスト・主役認識を検証する段取りになっている
- [ ] `20-documentation/thumbnail-prompts.md` にテキストなし背景生成プロンプトとテキスト付き生成プロンプトの両方を保存する段取りになっている

チェック通過後に本章上部の手順へ戻って `/thumbnail` を進める。CLI エラーで止まったときは、このチェックリストではなく本章上部の `#### プリフライト` を参照する。

### Two-Phase モード（従来方式・フォールバック）

Two-Phase は旧チャンネル向けのフォールバック。使う場合も、テキスト付き `thumbnail.jpg` を先に承認し、承認済み `thumbnail.jpg` から textless `main.png/jpg` を後続生成する。最終契約は `thumbnail.jpg`（テキスト付き YouTube サムネ）と `main.png/jpg`（テキストなし動画背景）を別成果物として確定する。

#### Phase 1: 既存参照の選択（新規生成しない）

既存 `main.png/jpg`、`planning-preview.png`、または `reference_images` は、Phase 2 のテキスト付き候補生成の参照素材としてだけ使う。ここでは `yt-generate-image` を実行せず、textless 動画背景として承認・確定もしない。最終 `main.png/jpg` は Phase 3 で承認済み `thumbnail.jpg` から AI 再生成する。

参照素材を選ぶ場合:
1. テーマに合う既存 `main.png/jpg`、`planning-preview.png`、または `reference_images` から 1 枚以上を選択する
2. `open` でプレビューし、Phase 2 のテキスト付き候補生成の参照に使えるかだけ確認する
3. 参照素材を `main.png/jpg` へコピーしない。`main.png/jpg` は Phase 3 でだけ確定する

#### Phase 2: テキストオーバーレイ（thumbnail.jpg）

1. `image_generation.gemini.thumbnail_text` からテキスト設定を取得
2. テキストオーバーレイプロンプトを構築:

**`thumbnail_text.text_overlay_prompt` が定義されている場合（推奨）:**
テンプレート内の `{title_line1}`, `{title_line2}`, `{channel_name}` をコレクションのタイトルとチャンネル名で置換して使用。

**未定義の場合（フォールバック）:** `references/sample-prompts.md` の「Two-Phase モードのテキストオーバーレイ・フォールバックプロンプト」を使用する。

`text_overlay_prompt` が実質単一の入口。旧個別フィールド（`channel_name_style` / `title_format` / `title_prefix` / `copy_position` / `color` / `decoration`）は deprecated で、位置・色・装飾の意図は `text_overlay_prompt` の本文に直接書く（段階的廃止 #1702）。

3. 生成: `uv run yt-generate-image --reference <既存参照画像> --prompt <テキスト指示> --output 10-assets/thumbnail-v1.jpg -y`
4. `open` でプレビュー → ユーザー承認 → `cp thumbnail-v1.jpg thumbnail.jpg` → `uv run python .claude/skills/thumbnail/references/archive-approved-thumbnail.py <collection-path>`

#### Phase 3: 承認済み thumbnail から textless main を再生成

1. 承認済み `thumbnail.jpg` を参照して textless `main-v1.png` を AI 再生成する。
2. `open` でプレビュー → ユーザー承認 → `cp main-v1.png main.png` で動画背景を確定する（JPEG で確定する運用では `main-v1.jpg` → `main.jpg` に揃える）。

## フォント安定化（#1332 / #1907）

「サムネの文字フォントが毎回バラバラになる」問題への対処。フォントの扱いは 2 経路あり、#1907 以降は決定的合成経路が標準フローの既定になった。

| 経路 | 仕組み | フォント再現性 |
|---|---|---|
| **決定的合成経路**（`yt-thumbnail-text`・**既定**） | textless 背景に実フォントファイル（.ttf/.otf/.ttc）を Pillow で描画 | **完全に安定**。同一の背景・テキスト・設定なら常に同一出力 |
| **AI プロンプト経路**（fallback・非既定） | テキスト付きサムネ生成プロンプトで書体の雰囲気を指示（`thumbnail_text.font` / `single_step.typography_clause`） | **保証されない**。AI 画像生成はフォント名を厳密に再現できず、同じ指示でも生成ごとに書体が揺れる |

### AI プロンプト経路でのフォント指示（fallback）

- **single_step（TTP）**: 初回 `diff_prompt_template` はテキスト付き `thumbnail-v*.jpg/png` 候補生成用。書体の一貫性を高めたい場合は、override に本文を設定（既定空文字の opt-in）した上で `single_step.typography_clause` を展開し、`{font_description}` を `thumbnail_text.font.copy` の値で置換する。承認済み `thumbnail.jpg` から作る textless 再生成プロンプトには、`${typography_clause}` やタイトル文字の描画指示を入れない
- **two_phase**: Phase 2 のオーバーレイプロンプトで `thumbnail_text.font.copy` / `font.genre_tag` の記述が使われる

いずれも改善であって保証ではない。「同一チャンネルで常に同じフォント」が必要なら決定的合成経路を使う。

### 決定的合成経路（yt-thumbnail-text・標準）

標準 `/thumbnail` フローの既定テキスト描画経路（#1907）。textless 背景 `main.png/jpg` の生成・承認から、`yt-thumbnail-text` 合成 → `/thumbnail-compare` → `thumbnail.jpg` 確定までの手順は「標準生成順序とファイル契約」に従う。フォント選定・コピー生成制約・配置へのプロファイル反映は「thumbnail-text-profile 適用」節に従う。

`config/skills/thumbnail.yaml` にフォントファイルを設定する:

```yaml
image_generation:
  gemini:
    thumbnail_text:
      overlay:
        font:
          title: "assets/fonts/NotoSansJP-Bold.ttf"   # channel_dir 相対 or 絶対パス
```

フォントファイルは Google Fonts 等から入手し `<channel_dir>/assets/fonts/` に置く運用を推奨（フォントのライセンス条項を確認すること）。サイズ・色・縁取り・配置は `overlay.title` / `overlay.channel_name` / `overlay.layout` で調整する（デフォルト値は `config.default.yaml` 参照）。

決定的合成はテキスト描画だけを担う。`--background` に渡す textless 背景は AI 焼き込みテキストを含まない状態で先に確定しておく。AI 焼き込み経路で確定した過去コレクションのサムネを実フォントで作り直す場合も、承認済み `thumbnail.jpg` から textless `main-v*.png/jpg` を AI 再生成・承認してから合成する（文字入り画像を `--background` に流用しない）。

### フォント指定に失敗した場合

`yt-thumbnail-text` は失敗理由と代替手順を明示して終了コード 1 で停止する:

- **`image_generation.gemini.thumbnail_text.overlay.font.title` 未設定** → `config/skills/thumbnail.yaml` に .ttf/.otf/.ttc のパスを設定する
- **フォントファイルが存在しない** → パスを確認（相対パスは channel_dir 起点）。フォントを `<channel_dir>/assets/fonts/` に配置し直す
- **ファイルが壊れている・フォントとして読めない** → 別のフォントファイルを用意する

決定的合成を使わない判断をした場合は、AI プロンプト経路（上記 `typography_clause` / two_phase の `thumbnail_text.font`）へフォールバックする。その場合フォントの厳密な再現は保証されないことをユーザーに伝えること。

## 自動選択（auto-selection・opt-in）

TTP 参照画像が固定されているチャンネルでは、候補生成後のユーザー承認を省略し、`uv run yt-thumbnail-auto-select` で `10-assets/thumbnail.jpg` を自動確定できる。自動化範囲は deep-merge 後の `auto_selection.mode` で分岐する。

| 実効設定 | テーマ確認 | 生成可否 | textless 背景承認 | 候補承認 |
|---|---|---|---|---|
| `enabled: false` / 未設定 | 実行 | 実行 | 実行 | 実行 |
| `enabled: true`, `mode: selection_only` または mode 未設定 | 実行 | 実行 | 実行 | **省略**（#1370 の従来挙動） |
| `enabled: true`, `mode: full` | **省略** | **省略**（生成 CLI に `-y`） | **省略** | **省略** |

`selection_only` の既存手順は変更しない。`auto_selection.enabled` が false / 未設定のチャンネルも従来の手動承認フローを使う。

有効化（チャンネル側 `config/skills/thumbnail.yaml`）:

```yaml
image_generation:
  auto_selection:
    enabled: true          # opt-in。false / 未設定なら従来の手動承認フロー
    mode: selection_only   # selection_only（既定）| full（4 ゲートを省略）
    min_width: 1280        # 候補の最小解像度
    min_height: 720
    aspect_tolerance: 0.01 # 16:9 判定の許容誤差
```

### `mode: full` のテーマ自動決定

`$ARGUMENTS` があればその値を最優先し、テーマ確認は行わない。`$ARGUMENTS` 省略時は次の順で 1 件に決定する。空値や複数候補を推測で補完しない。

1. **config のテーマ設定**: deep-merge 後の `image_generation.gemini.color_themes` にキーが 1 件だけなら、そのキーを使う。複数キーの場合は、collection ディレクトリ名または `workflow-state.json::collection_name` に完全なハイフン区切り語として一致するキーが 1 件だけならそれを使う
2. **collection metadata**: 1 で決まらない場合は対象 collection の `workflow-state.json::theme` を使う

解決した値とソース（`arguments` / `config.color_themes` / `workflow-state.theme`）をログへ 1 行表示して生成へ進む。候補が 0 件、複数一致、metadata 欠落、または config のテーマキーと metadata が矛盾する場合は質問で解決せず、「full モード失敗時の手動切替」を表示して停止する。

### 実行手順

`auto_selection.enabled: true` のチャンネルのみ実行する。無効チャンネルで実行すると終了コード 2 の明示エラーになる。

1. `mode: selection_only` は候補生成前のテーマ・生成可否・textless 背景承認を従来どおり実行する。`mode: full` はテーマを上記手順で自動決定し、生成 CLI に `-y` を渡す。生成コマンドが非 0 または期待候補が 0 件なら手動切替を表示して停止する。
2. 候補生成後、dry-run で採点とランキングを確認する:

```bash
uv run yt-thumbnail-auto-select <collection-path> --dry-run
```

3. dry-run が成功したら、どちらの mode も質問を挟まず apply で確定する（`--json` で選択理由を構造化出力できる）:

```bash
uv run yt-thumbnail-auto-select <collection-path> --apply
```

選択ロジック（deterministic・学習なし）:

- `image_generation.gemini.reference_images.default` の各参照画像から特徴量（brightness / contrast / saturation / dominant_hue / colorfulness）を抽出して centroid を作る
- `10-assets/` の候補（`thumbnail-v*.jpg` / `thumbnail-v*.png` / `thumbnail-codex-v*.png`）を採点し、16:9・最小解像度を満たす候補のうち centroid に最も近いもの（distance 最小）を選ぶ
- apply 時は選択候補を `thumbnail.jpg` にコピー（PNG 候補は JPEG 変換）し、`workflow-state.json` があれば `thumbnail_auto_selection` キーに選択候補・distance・ランキング・実行時刻を記録する

失敗時は silent fallback しない（終了コード 1 / 2 の明示エラー）:

- 候補なし / 参照画像なし / 適格候補なし（全候補が 16:9 逸脱・解像度不足）
- 確定済み `thumbnail.jpg` / `thumbnail.png` が既に存在（上書きは `--force` の明示が必要）
- `auto_selection.enabled` が false のまま実行

### full モード失敗時の手動切替

`mode: full` でテーマ解決、画像生成、dry-run、または apply のいずれかが失敗したら、確定済みとして state を更新せず次を表示して停止する。

1. `config/skills/thumbnail.yaml` の `image_generation.auto_selection.mode` を `selection_only` に変更する（または `mode` を削除して既定へ戻す）
2. `/thumbnail <theme>` を再実行し、テーマ確認・生成可否・textless 背景承認を含む手動フローで候補を再生成する。候補確定だけは従来どおり自動選択される
3. 自動選択自体を使わず候補も手動承認する場合は `image_generation.auto_selection.enabled: false` にして `/thumbnail <theme>` を再実行する

CLI が「適格候補がありません」と返した場合も、エラー内の `selection_only` / 手動フロー案内と同じこの手順を使う。設定を自動で書き換えたり、不適格候補を `--force` で採用したりしない。

自動確定後も `/thumbnail-compare` の 320px 視認性検証と下記の品質チェックリストは通すこと。textless `main.png` 再生成以降の後工程は従来どおり。

## 品質チェック

textless 背景候補の自動セルフチェック（#489）:

```bash
uv run yt-thumbnail-check <collection-path>/10-assets/main-v1.png --json
```

`uv run yt-thumbnail-check` は `main-v1.png` / `main-v1.jpg` のような **テキストなし背景候補**を対象にする。Gemini Vision で `collection-ideate.yaml` の `objects.fixed` と
`self_check.no_logo_guard` から YES/NO チェックリストを組み立て、画像に対する合否を
JSON で返す（終了コード 0=合格 / 1=不合格）。手作業チェックの前段スクリーニングとして、
TTP 構図逸脱（wet_runway 不在・矩形ロゴ混入・テキスト burned-in 等）を機械的に検出する。

テキスト付き thumbnail 候補生成後（`thumbnail-v1.jpg` / `thumbnail-codex-v1.png`）:
- [ ] ベンチマーク参照の構図・主役スケール・光・色温度・背景テクスチャが維持されているか
- [ ] `/thumbnail-compare` で 320px 縮小時のタイトル可読性・コントラスト・主役認識を確認したか
- [ ] タイトルテキストが `composition_rules.text_lines` の制約内か
- [ ] `thumbnail_text.channel_name` が表示されているか
- [ ] 参照元の署名・サイン・透かし・ロゴ・ブランドマークが焼き込まれていないか
- [ ] `image_generation.gemini.style` に記載されたスタイルが維持されているか
- [ ] `fixed_character` の外見が維持されているか（ある場合）
- [ ] キャラの顔が見えているか（`fixed_character.face` の指示通り）
- [ ] **解剖学チェック（手・指）**: キャラが写っている場合、手・指が解剖学的に正しいか（各手 5 本指・指の分離が明瞭・指の融合や本数異常・溶融が無い・プロポーションが破綻していない）。**特に楽器持ちキャラ・指を伸ばす/握るポーズでは Gemini が破綻しやすい**ため必ず Read ツールで等倍プレビューを開いて目視確認する。NG なら `anatomy_clause` を強調 / 再生成 / プロバイダー切り替え（codex は人体破綻に強い傾向）で対応する（#570）

textless main 候補生成後（`main-v1.png` / `main-v1.jpg`）:
- [ ] 承認済み `thumbnail.jpg` の構図・主役スケール・光・色温度・背景テクスチャが textless 背景として維持されているか
- [ ] タイトル文字、字幕、ロゴ、透かし、タイポグラフィ、チャンネル名が残っていないか
- [ ] 新しい文字や記号が追加されていないか
- [ ] `uv run yt-thumbnail-check <collection-path>/10-assets/main-v1.png --json` を通したか（JPEG 候補なら `main-v1.jpg` を指定）
- [ ] `/loop-video` 入力や `/videoup` 静止背景として使える textless 背景になっているか

> **Note (#570)**: キャラ + 手が写る構図で指の破綻が出るチャンネルは、`image_generation.gemini.single_step.anatomy_clause` に本文を設定（既定空文字の opt-in、推奨文面は `config.default.yaml` のコメント）してプロンプト末尾に `${anatomy_clause}` として展開すると、Gemini の手・指破綻（指の融合・本数異常・溶融）の発生率を下げられる。`/collection-ideate` の single_step プレビューは企画参照素材であり最終 thumbnail には流用しないが、参照素材として採用する前にも最低限の QA（手・指 / 署名 / ロゴ）を通すこと。

## 視認性検証と整合性監査の役割分担

`/thumbnail-compare` と `/alignment-check` は並走で使うが、見る対象とタイミングが異なる。

| スキル | 役割 | スコープ | 主指標 | 実行タイミング |
|---|---|---|---|---|
| `/thumbnail-compare` | 視認性検証 | 単体サムネ × ベンチマーク | 320px 縮小可読性・コントラスト・キャラ認識 | サムネ承認**前**（TTP プリフライトでも確認） |
| `/alignment-check` | 整合性監査 | コレクション全体（音楽 × サムネ × タイトル） | ムード / ビジュアル / タイトル訴求の一致 | 公開**後**、または方向性見直し時 |

1. `/thumbnail` で候補生成後、承認前に `/thumbnail-compare` を実行して視認性検証を通す。
2. 承認・公開後、または方向性見直し時に `/alignment-check` でコレクション全体の整合性監査を行う。
3. `/alignment-check` で不整合が出たコレクションは `/thumbnail` で再生成し、再度 `/thumbnail-compare` で 320px 視認性を確認する。

## プロンプト保存

プロンプトは `20-documentation/thumbnail-prompts.md` に保存:

```markdown
# Thumbnail Prompts - <コレクション名>

*プロバイダー: {image_generation.provider}*
*スタイル: {image_generation.gemini.style}*
*モデル: {image_generation.gemini.model}*

## Reference Assignments

| attempt | output | reference_image | benchmark_channel |
|---:|---|---|---|
| 1 | `10-assets/thumbnail-v1.jpg` | `<参照画像 1>` | `<benchmark_channel>` |
| 2 | `10-assets/thumbnail-v2.jpg` | `<参照画像 2>` | `<benchmark_channel>` |
| 3 | `10-assets/thumbnail-v3.jpg` | `<参照画像 3>` | `<benchmark_channel>` |

## Text-Included Thumbnail Prompt (thumbnail.jpg)

\```
<ベンチマーク参照画像からテキスト付きサムネを生成したプロンプト>
\```

## Textless Background Prompt (main.png/main.jpg)

\```
<承認済み thumbnail.jpg からテキストなし背景を生成したプロンプト>
\```

## A/B Test Pattern Prompts

| pattern | final output | variation |
|---|---|---|
| `a` | `10-assets/thumbnail-a.jpg` | `<pattern a variation>` |
| `b` | `10-assets/thumbnail-b.jpg` | `<pattern b variation>` |

### Pattern a Final Prompt

\```
<diff_prompt_template 展開結果 + pattern a variation>
\```

### Pattern b Final Prompt

\```
<diff_prompt_template 展開結果 + pattern b variation>
\```
```

## ファイル命名ルール（上書き禁止）

| ファイル | 用途 |
|---------|------|
| `thumbnail.jpg` | YouTube アップロード用のテキスト付き最終サムネ |
| `thumbnail-<name>.jpg` | `ab_test.enabled: true` の Test & compare 用最終サムネ（最大 3 枚） |
| `thumbnail-<name>-v{N}.jpg` / `.png` | pattern 別の承認前候補 |
| `thumbnail-v{N}.jpg` / `thumbnail-v{N}.png` / `thumbnail-codex-v{N}.png` | テキスト付き候補 |
| `main.png` / `main.jpg` | 動画背景・`/loop-video` 入力用のテキストなし最終画像 |
| `main-v{N}.png` / `main-v{N}.jpg` | テキストなし背景候補 |
| `loop.mp4` | `loop-video` 有効チャンネルだけで生成する動画背景。無効チャンネルでは作らない |

### クリーンアップ（承認後に必ず実行・stock 退避）

不採用候補は `<channel_dir>/assets/stock/<theme>/` に隣接メタデータ付きで退避する（#364）。

```bash
THEME="<theme-slug>"   # 例: tavern / library / jazz-bar
uv run yt-stock-archive \
  10-assets/main-v*.png 10-assets/main-v*.jpg \
  10-assets/thumbnail-v*.jpg 10-assets/thumbnail-v*.png 10-assets/thumbnail-codex-v*.png \
  --theme "$THEME" \
  --source-collection "$(pwd)" \
  --source-role thumbnail_candidate \
  --meta-json - <<JSON
{
  "provider": "<provider>",
  "model": "<model>",
  "generation_mode": "<mode>",
  "prompt": "<最終生成プロンプト>",
  "reference_images": ["<参照画像 1>", "<参照画像 2>"]
}
JSON
```

`config/skills/thumbnail.yaml` の `image_generation.stock.enabled: false` に設定するとこの CLI は退避せず単純削除（従来挙動）に戻る。

### `workflow-state.json` 更新

画像確認・承認後、`thumbnail.approved = true` を更新する。`mode: full` では目視確認と AskUserQuestion を省略し、既存の自動確定成功を承認完了として扱う。`ab_test.enabled: true` の場合は、設定された全 pattern の `thumbnail-<name>.jpg` が存在し、各 pattern の承認（`full` では自動確定）が完了し、`thumbnail.jpg` が先頭 pattern と同一内容であることを確認してからだけ更新する。一部 pattern の承認・確定に失敗した状態では `false` のままにする。

`yt-thumbnail-auto-select --apply` で確定した場合は、選択候補・distance・ランキング・実行時刻が `thumbnail_auto_selection` キーに監査ログとして自動記録される（#1370）。

## stock 退避と再利用

不採用画像は `<channel_dir>/assets/stock/<theme-slug>/` に画像本体 + 隣接 `<image>.meta.json` で退避される（schema_version=1）。メタには prompt / provider / model / generation_mode / source_collection / reference_images / generated_at / rejected_at を保存し、将来別コレクションの参照画像として再利用できる。

stock の操作 CLI:

| CLI | 用途 |
|---|---|
| `uv run yt-stock-list [--theme T] [--source-role R] [--limit N] [--format table\|json]` | stock 一覧（新しい順） |
| `uv run yt-stock-preview [--theme T] [--limit N]` | macOS `open` でプレビュー起動 |
| `uv run yt-stock-prune [--retention-days N] [--max-per-theme N] [--dry-run]` | 古い画像 / 上限超過分を削除（config 既定値あり） |

`config/skills/thumbnail.yaml` の `image_generation.stock`:

```yaml
image_generation:
  stock:
    enabled: true          # false で退避を無効化（unlink のみ）
    retention_days: 90     # uv run yt-stock-prune の保持日数
    max_per_theme: 50      # uv run yt-stock-prune の上限
```

### stock 再利用（参照画像プールへの自動合成）

PR-B (#364): stock 画像は `reference_images.default` とは別スコープの参照プールとして扱う。TTP single_step の標準フローでは同じベンチマークチャンネル内の別サムネだけを使い、`--ttp-strict-references` では stock 混在を拒否するため、stock 合成は default OFF。必要なチャンネルだけ `enabled: true` を明示し、TTP strict ではない汎用参照生成に限って `resolve_stock_refs()` の結果を `--reference` に追加する。

- **デフォルト動作**: `enabled: false` で stock は混ぜない。
- **有効化**: `config/skills/thumbnail.yaml` で `image_generation.gemini.reference_images.stock.enabled: true` を明示する。TTP strict 候補生成では使わない。
- **採用ログ**: 1 枚採用ごとに stderr へ `[INFO] stock 採用: <path> (theme=<t>, role=thumbnail_candidate)` を出力。監査時は stderr を grep。
- **チューニング**: `max_count` / `shuffle` / `theme_match: "any"` / `source_role: null` (role フィルタなし) などをチャンネル側で調整。

```yaml
image_generation:
  gemini:
    reference_images:
      stock:
        enabled: false
        max_count: 3
        theme_match: "exact"     # "any" で全テーマ横断
        source_role: "thumbnail_candidate"
        shuffle: true
        seed: null
        fallback_when_empty: true
```

## 長時間処理の取り扱い

`uv run yt-generate-image` は Gemini / OpenAI への API 同期呼び出しで **10〜30 秒** ブロックする。`--max-attempts N` でローテーション生成する場合は `N × 10〜30 秒` かかる。**必ず Bash ツールを `run_in_background=true` で起動する**。これによりユーザーは処理中も同じセッションで質問できる（Claude Code は完了時に自動でメッセージ通知するため、`sleep` ループや `until` での自前ポーリングは禁止）。

spawn 例:

```bash
uv run yt-generate-image \
	  --ttp-strict-references \
	  --reference <ref> --prompt "<prompt>" \
	  --output <collection-path>/10-assets/thumbnail-v1.jpg -y \
	  > /tmp/thumbnail-$(date +%s).log 2>&1
```

これを `Bash run_in_background=true` で投げ、spawn 直後に次のメッセージを返す:

> ⏳ サムネイル画像を生成中（推定 N × 10〜30 秒）。完了まで他の質問にもお答えできます。
> ログ: /tmp/thumbnail-*.log

cmux 環境下（`$CMUX_WORKSPACE_ID` あり）であれば補助で `cmux set-status "thumbnail" "running" --icon "hourglass" --color "#f59e0b"`、完了で `cmux clear-status "thumbnail"` + `cmux notify --title "thumbnail 完了"` を呼ぶ（非 cmux 環境では skip）。

完了通知が届いたらログ末尾から結果サマリー（生成された `thumbnail-vN.jpg/png` または `main-vN.png/jpg` のパス、attempt 回数、内部リトライ有無）をユーザーへ返す。プロバイダーが瞬発エラーを返した場合はそのエラー行を抜き出して報告する。

## 障害時ガイダンス

| 状況 | 兆候 | 対処 |
|---|---|---|
| GCP ADC 未取得/失効 | `ConfigError` / ADC 認証エラー | `gcloud auth application-default login`（必要なら `set-quota-project`）を再実行 |
| Vertex AI rate | HTTP 429 | 時間を置いて再実行。並列実行を避け順次処理する |
| API 障害 / サービス停止 | HTTP 503 / タイムアウト | Google Cloud（Vertex AI）のステータスを確認し、時間を置いて再実行 |
| 画像 provider 障害 | 片方の provider のエラー | `image_generation.provider` を `gemini` ↔ `openai` で切り替える |

## Next Step

サムネイル確定後:
- Suno チャンネル: `/suno <theme>` で音楽プロンプト生成
- Lyria チャンネル: `/lyria <theme>` でマスター音源生成（`/suno` 系工程は不要）

---

Source: https://www.openparable.com/skill/design/thumbnail (OpenParable). Cite the canonical URL above.
