thumbnail

前後工程

• 前工程: /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 が単一ソース）のうちサムネイルに効くものを参照する。これは前提ガードではない。

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

想定 API call 数

• 上限 / 承認: 生成前に 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 で選択する:

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 課金なしで進める場合:

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

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

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 に切り替える場合:

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 .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 .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 動画背景として確定する。

既定テンプレート:

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 を確認:

参照画像モード（必須）

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

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 でプロバイダーへ渡る全文）:

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 で実フォントのタイトルを合成し、テキスト付き候補を作る:

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 で理由付き停止する。

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 焼き込み経路の例:

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 セクションを次のとおり適用する:

• 値が 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 する:

archive:
  enabled: true

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

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 別参照欄で追跡できるようにする。

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 を列挙する:

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 再生成:

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 以降は決定的合成経路が標準フローの既定になった。

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 にフォントファイルを設定する:

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 で分岐する。

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

有効化（チャンネル側 config/skills/thumbnail.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 で採点とランキングを確認する:

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

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

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）:

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 は並走で使うが、見る対象とタイミングが異なる。

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

プロンプト保存

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

# 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>
\```

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

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

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

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:

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

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 フィルタなし) などをチャンネル側で調整。

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 例:

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 回数、内部リトライ有無）をユーザーへ返す。プロバイダーが瞬発エラーを返した場合はそのエラー行を抜き出して報告する。

障害時ガイダンス

Next Step

サムネイル確定後:

• Suno チャンネル: /suno <theme> で音楽プロンプト生成
• Lyria チャンネル: /lyria <theme> でマスター音源生成（/suno 系工程は不要）