akari-video 0.1.0

package/vendor/skills/overlay-authoring/thumbnail.md

@@ -0,0 +1,126 @@
+# サムネイル設計
+
+サムネイルは静止画として **1280×720** で出力する。候補は複数作り、タイトル文字の差分も見せて編集判断レポートの先頭へ置く。候補数の一律閾値は契約にないため、依頼と比較したい仮説から決め、根拠のない「標準個数」を発明しない。
+
+## 状況から型を選ぶ
+
+| 状況・ジャンル | 第一候補の型 | 注意点 |
+|---|---|---|
+| 操作解説・ソフトウェア | UI の証拠フレーム + 注目箇所 + 結果を示す短い見出し | UI 全景を縮小せず、見せたい部分を crop する |
+| 商品・機能発表 | product hero + ベネフィット + 小さな category tag | ロゴ、形状、UI を生成で変形しない |
+| 対談・人物解説 | 表情の読める人物 + 論点または対立軸 | 顔を過度に加工せず、視線の先に文字余白を作る |
+| 比較・レビュー | split / versus + 比較対象 + 判断語 | 左右の縮尺と条件をそろえ、勝敗を捏造しない |
+| before / after | 同条件の二面比較 + 変化点 | 撮影条件が違う素材を同一条件のように見せない |
+| リスト・まとめ | 主役 1 点 + 数やカテゴリを示す badge | 小要素を並べすぎず、本文の一覧と混同しない |
+| 事件・ストーリー・ドキュメンタリー | key object / place + 緊張を作る短い問い | 本文にない断定や偽の出来事を描かない |
+
+型はジャンル名だけで決めず、「何がクリック後に証明されるか」を基準にする。サムネイル単独で成立し、動画内容と約束が一致するものだけ採用する。
+
+## デザイン語彙
+
+### 背景処理
+
+| 技法名 | 用途 | HTML/CSS 実装ヒント |
+|---|---|---|
+| crop / focal crop | 主役を大きく見せる | `<img>` の `object-fit: cover` と `object-position` を変数化する |
+| gradient wash | 文字側のコントラストを作る | 疑似要素の linear / radial gradient を使う |
+| vignette | 周辺を落として中央へ集める | 疑似要素の radial-gradient。CSS blur は使わない |
+| duotone / color wash | シリーズ感を統一する | 半透明の blend layer を重ね、元の証拠を潰さない |
+| cutout silhouette | 人物・商品を背景から分離する | 事前生成した alpha PNG / HEVC を使い、輪郭を検品する |
+| split field | 比較対象を一目で分ける | Grid の 2 region と境界線を使う |
+
+背景ぼかしが必要なら、静止画像を事前処理する。動画 overlay の禁止事項である `filter: blur()` / `backdrop-filter` をデザインの前提にしない。
+
+### FX
+
+| 技法名 | 用途 | HTML/CSS 実装ヒント |
+|---|---|---|
+| outline / keyline | 主役の輪郭分離 | alpha cutout の背面へ複製 silhouette をずらして置く |
+| halftone | 情報・コミック感 | radial-gradient の pattern layer |
+| speed lines | 勢い・方向 | repeating-conic / repeating-linear gradient |
+| accent ray | 注目点から放射 | conic-gradient を mask して不透明度を抑える |
+| hard offset shadow | 奥行き・ポップ感 | blur の小さい box/text shadow または複製 layer の translate |
+| sticker / tape | 補助ラベル | transform した小さな tag。本文より強くしない |
+
+### 文字強調
+
+| 技法名 | 用途 | HTML/CSS 実装ヒント |
+|---|---|---|
+| stroke | 背景から分離 | `-webkit-text-stroke` と通常色を併用する |
+| highlight band | キーワードだけ強調 | inline span の背景色と padding |
+| two-tone keyword | 意味の対比 | キーワード span の `--accent` を差し替える |
+| condensed stack | 短い見出しを大きく積む | 明示改行と line-height。自動折返し任せにしない |
+| label + headline | 種別と主張を分離 | 小 tag と大見出しを別 hierarchy にする |
+| hard shadow | 小サイズでも輪郭を残す | 複製文字を `aria-hidden` で背面へ offset する |
+
+日本語の最終文字は HTML で組む。画像生成モデルへ見出し、ロゴ、UI の正確な描画を任せない。
+
+## 経路を選ぶ
+
+### 経路 A — 実フレーム + HTML 文字組
+
+次の場合に選ぶ。
+
+- 動画内に顔、商品、UI、結果などの強い証拠フレームがある。
+- 日本語、数字、ロゴ、UI を正確に見せる必要がある。
+- 生成による事実改変を避ける必要がある。
+
+実フレームを crop / grade し、文字、badge、矢印、比較線だけを HTML/CSS で重ねる。
+
+### 経路 B — Codex 画像生成
+
+次の場合に選ぶ。
+
+- 使用可能な実フレームがない。
+- 抽象概念、世界観、イラストが主役で、写真の証拠性を要求しない。
+- 生成物であることと provenance を記録できる。
+
+文字なしの構図を生成し、生成手、prompt、日時を記録する。API key の直叩きへ fallback しない。画像生成が使えなければ A または制作保留に戻す。
+
+> **実測済み（2026-07-14）**: `codex exec --skip-git-repo-check` 経由で 16:9・文字なしの背景 PNG（1664×936、1.7MB）が約 93 秒で実ファイル出力されることを視認確認済み。呼び出し形・事前確認・既知の失敗モード（アカウント使用量上限）は [edit-plan/approvals-and-generation.md](../edit-plan/approvals-and-generation.md) の「手 1（Codex 画像生成）の実働確認」を参照。
+
+### 混成 — B の背景 + A の文字
+
+独自背景は必要だが、日本語、ブランド、数値は正確に保つ場合に選ぶ。B では文字・ロゴ・UI を入れず余白を指定し、A の HTML layer で最終文字と正式 asset を置く。
+
+## `examples/` の HTML → スクショ手順
+
+現在はサムネ専用 CLI がないため、既存 `scripts/render-overlays.mjs` の static Chrome と同じ方式を使う。`render-overlays.mjs` 自体は manifest 必須の overlay renderer であり、サムネ用 CLI として直接呼ばない。
+
+1. `examples/local/thumbnails/<slug>/index.html` を作る。`examples/local/` は gitignore 対象の試作場所である。
+2. `html, body` と単一 sheet を 1280×720、margin 0、overflow hidden にする。背景を明示し、画像・font は同ディレクトリ以下のローカル相対 URL にする。
+3. 文字、色、crop、accent を CSS 変数化する。日本語は HTML text として置く。
+4. font と画像が load 済みになる構造にし、headless Chrome の virtual time 内で安定するようにする。
+5. 次の実装済み flags で単発 PNG を撮る。
+
+```sh
+CHROME="${AKARI_CHROME_BIN:-/Applications/Google Chrome.app/Contents/MacOS/Google Chrome}"
+test -x "$CHROME"
+"$CHROME" --headless \
+  --allow-file-access-from-files \
+  --disable-background-networking \
+  --force-device-scale-factor=1 \
+  --hide-scrollbars \
+  --no-first-run \
+  --no-default-browser-check \
+  --window-size=1280,720 \
+  --virtual-time-budget=10000 \
+  --run-all-compositor-stages-before-draw \
+  --screenshot="$PWD/examples/local/thumbnails/<slug>/thumbnail.png" \
+  "file://$PWD/examples/local/thumbnails/<slug>/index.html"
+```
+
+6. `sips -g pixelWidth -g pixelHeight .../thumbnail.png` で **1280×720** を確認する。
+7. PNG を実見し、文字欠け、font fallback、crop、コントラスト、誤字、safe zone を確認する。採用 PNG は gitignore 外の案件成果物へ移す。
+
+YouTube 広告向けの公式 thumbnail 推奨値も 1280×720、16:9 であるが、このスキルではユーザー指定の AKARI 出力契約として 1280×720 を固定する。出典: [Google Ads Help — About video ad specs](https://support.google.com/google-ads/answer/13547298?hl=en)
+
+## よくある間違い
+
+- 本文にない結果、感情、人物、UI を生成して事実のように見せる。
+- 日本語やロゴを画像生成モデルに描かせる。
+- 背景、人物、文字、矢印、badge をすべて同じ強さにする。
+- 実フレーム全景を縮小して、小さな UI を読ませようとする。
+- 16:9 sheet を CSS transform で拡縮し、最終 PNG の実寸を確認しない。
+- network font / CDN 画像へ依存し、headless で欠落する。
+- `examples/local` の試作 PNG を最終成果物の保存先と思い込む。

package/vendor/skills/render-cut/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: render-cut
+description: 承認済み edit.json と edit-lint PASS を入力に、最終 MP4 の計画、明示承認、ローカル書き出し、ffprobe 検証、キーフレーム視認を完了する。編集が承認済みで、納品用動画の書き出しや最終レンダーを求められたときに使う。
+---
+
+# 承認済み編集を書き出す
+
+> **Language**: Respond in the user's language — 対話・質問・承認確認・レポートはユーザーの使用言語に合わせる（例: 英語で話しかけられたら英語で応答する）。
+
+## ハードルール
+
+1. **edit.json を正本に決定的コマンド生成。自然言語からの即興 ffmpeg 禁止**
+   （エージェントが ffmpeg コマンドを手書きして「これで書き出しました」は契約違反）
+2. **plan なしの render 禁止**（validate→plan→承認→render の順を飛ばさない）
+3. **edit-lint FAIL のままの render 禁止**（override は承認ゲート + render.json 記録）
+4. **レンダー後の ffprobe 機械検証必須**。verify fail の成果物を納品可能と報告しない
+5. **既定はローカル ffmpeg のみ**。クラウド有償 API（Rendi 等）は v0 不採用
+   （将来はオプトイン + manage-connections の承認ゲート経由でのみ検討）
+6. **原本 source からレンダ**（proxy を最終レンダに使わない）
+7. **状態は render.json・HTML は可視化のみ**（新規サーフェス機構を輸入しない）
+8. **外部候補のコード転写禁止**（Kinocut / json-to-ffmpeg は構造参考のみ）
+9. **既存成果物の silent 上書き禁止**
+10. カット連結・合成・verify の ffmpeg / ffprobe は**本体直叩き**（ラッパーライブラリ
+    禁止。分析・書き出し・検証の各工程で共通の方針）。
+    **例外は HTML ラスタライズ段の HyperFrames のみ**（依存は
+    `packages/render-cut/` 内に隔離し、リポの他所へ波及させない）
+11. **3D overlay は puppeteer-core 経路で焼かれる**（HyperFrames より速度差があり得る点に注意）
+
+## 実行手順
+
+1. 対象プロジェクトの `edit.json` が承認済みで、`.akari/lint.json` の `verdict` が `pass` であることを確認する。PASS でなければ `edit-lint` を実行して修正する。`--force` は lint 結果を上書きする明示承認を得た場合だけ使う。
+2. リポジトリルートから plan だけを生成する。
+
+   ```sh
+   node packages/render-cut/bin/render-cut.mjs <project-root> --plan-only
+   ```
+
+3. `<project>/.akari/render.json` と `<project>/.akari/reports/render-report.html` を読み、予測尺、出力先、ffmpeg コマンド列、中間物、ラスタライズ候補、入力ハッシュを提示する。
+4. **今回の書き出し実行に対する人間の明示承認を得て停止を解除する。** 無応答、過去の包括承認、plan 以前の承認を今回の承認に読み替えない。
+5. 承認後だけ書き出しを実行する。
+
+   ```sh
+   node packages/render-cut/bin/render-cut.mjs <project-root>
+   ```
+
+   出力を明示する場合だけ `--out <path>` を加える。CLI の validate → plan → render → verify を分解して手作業で代替しない。
+6. exit code と `.akari/render.json` を確認する。`0` は完走して verify PASS、`1` は拒否または verify FAIL、`2` は実行エラーを表す。`provenance.rasterizer` で採用手段と上位候補を落とした理由を確認する。
+7. verify PASS 後に成果物から少なくとも冒頭、各カット境界の前後、各オーバーレイまたは字幕の表示中をキーフレームとして抽出し、実画像を視認する。カット元時刻、文字、位置、欠落、透明合成を確認する。
+8. 機械検証値、成果物 SHA-256、採用したラスタライズ手段、フォールバック理由、キーフレーム視認結果を報告する。verify FAIL の場合は納品可能と表現せず、`.akari/render-tmp/` を保持して原因を報告する。
+
+## 出力契約
+
+- 成果物は既定で `<project>/exports/<source-name>.mp4` に置く。既存名があれば連番を使う。
+- 状態の正本は `<project>/.akari/render.json` とする。HTML レポートは可視化専用とする。
+- 成功時だけ `<project>/.akari/render-tmp/` を削除する。失敗時は診断用に保持する。
+- 字幕は `captions.json` から決定的な HTML へ生成し、他のオーバーレイと同じ経路で焼き込む。
+- 視認用に抽出するキーフレーム静止画は `<project>/.akari/reports/` へ置く。CLI 自身が使う
+  `.akari/render-tmp/` とは別に、確認用の一時スクリプトや実験的な中間生成物を人が作る場合は
+  `<project>/.akari/work/` へ置く（[project-structure-v0 契約](../../docs/contract-2026-07-25-project-structure-v0.md) §1）。
+  いずれもプロジェクトルート直下には置かない。
+
+## 公開契約
+
+- [edit.json v0 と書き出し段構成](../../docs/contract-2026-07-13-m1-m4.md)
+- [edit.json v1 拡張メモ](../../docs/notes-2026-07-13-edit-json-v1.md)
+- [字幕とカット編集](../../docs/notes-2026-07-14-captions-and-cut-editing.md)

package/vendor/skills/research-plan/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: research-plan
+description: 動画の企画・調査工程（ネタ出し → ターゲット/競合/トレンド調査 → 企画書・構成案・絵コンテ・撮影リスト）を headless で一周するときに発動する router。ネタ選定と構成の確定は decision-cards 型承認ゲート（HTML レポート + decisions.json）で人間の判断を受け取る。
+---
+
+# 企画・調査を一周する
+
+> **Language**: Respond in the user's language — 対話・質問・承認確認・レポートはユーザーの使用言語に合わせる（例: 英語で話しかけられたら英語で応答する）。
+
+> 本スキルは暫定で雛形同梱（v0）。スキルカタログ + setup インストール機構が立った時点で参照配布へ移行する。同梱は暫定運用であり、leaf を含めテキストのみ・バイナリ資産なし。
+
+## ハードルール
+
+1. **有償 API を呼ぶ前に想定コストを明示し、状態ファイル（`.decisions.json` 等）の承認後にのみ実行する。** チャット上の承認だけで課金を実行しない。
+2. **接続は [manage-connections](../manage-connections/SKILL.md)（`.akari/connections.json`）経由のみを使う。** `.env` 探索・API キー直書きをしない。
+3. **出力は JSON + HTML に限定し、GUI アプリを起動しない**（headless-first 不変条件。アプリを一切インストールしなくても本工程が完結する）。
+4. **参考にした外部スキル・リポジトリのコード・文面を転記しない。** Hub/Hero/Help 分類、並列ギャップ分析、収益化ポテンシャル付きランキングといった**工程分解の型だけ**を抽出する（例外は検証済み MIT/Apache のみ）。出力スキーマは自社統一。
+5. **日本語 SNS 事情を必須調査軸に含める。** `research-plan.json` の `target.japan_sns.notes` を空にしない（無償手段で確認できない場合もその旨と理由を書く）。
+6. **CLAUDE.md / AGENTS.md に触らない。**
+7. **無償枠のみで一周が成立する既定にする。** 有償手段が使えない環境でも停止しない（結果は劣化してよいが、完走はする）。
+8. **差し戻しはチャットと `plan-comments.json` の二重経路。** 承認チェックポイントの再提示前は、チャット返信の解釈より先に `<plan-dir>/plan-comments.json`（在れば）を読む（[storyboard.md](storyboard.md) §5）。
+9. **ネタ出しの冒頭で recipe の recall を行う。** [ideate.md](ideate.md) の手順に入る前に、`workflow: "research"` のレシピ（[edit-plan/recipe.md](../edit-plan/recipe.md) の recall 手順と同じ規律）が `~/.akari/recipes/` に在るか確認し、在れば出所付きの推奨として添える。今回の依頼を上書きせず、必須調査軸（§5 の日本語 SNS 事情等）をスキップさせない。
+10. **同じ冒頭で memory connection の読み合わせを行う。** `.akari/connections.json` に `memory` 宣言（[contract-2026-07-25-memory-connection-v0.md](../../docs/contract-2026-07-25-memory-connection-v0.md)）があれば、`entry`（省略時 `INDEX.md`）起点で `include`/`exclude` の範囲だけを読み、参照したファイルパスを `research-plan.json` の `sources[]` に出所として記録する。全文投入は禁止。宣言が無ければ何もしない（error にしない）。
+
+## 実行順と目次
+
+現在の工程に必要なリーフだけを読み、後工程を先回りして実行しない。
+
+1. [ideate.md](ideate.md) を読み、ネタ出し（Hub/Hero/Help 分類 + 収益化ポテンシャル軸）で候補をランキングする。`topic.candidates[]` に落とす。
+2. [competitor.md](competitor.md) を読み、ターゲットと競合を調査・構造化する（4 並列ギャップ分析 + 日本語 SNS 事情）。`target` に落とす。
+3. [trends.md](trends.md) を読み、無償手段を既定にトレンドを取得する。知見は専用フィールドを持たず、候補の `rationale` / 競合の `gap` に溶け込ませ、出典だけ `sources[]` に残す。
+4. レポートを起票し（下記「レポートと承認ゲート」）、`topic-select` 決定カードで**ネタ選定**の承認を人間から受ける。`completedAt` が入るまで次工程へ進まない。
+5. [storyboard.md](storyboard.md) を読み、承認済みネタから企画書・構成案・絵コンテのショットカードを作る（`structure.chapters[]` / `structure.shots[]`）。同じレポートに `structure-confirm` 決定カードを追加し、**構成の確定**の承認を受ける。
+6. [shotlist.md](shotlist.md) を読み、確定した絵コンテから撮影リスト・収録チェックリストを作る（`shot_list[]`）。
+7. `research-plan.json` へ確定内容を書き、`node packages/schemas/bin/validate-research-plan.mjs <パス>` で検証する（exit 0 を確認するまで完了扱いにしない）。
+
+## レポートと承認ゲート（decision-cards 型の再利用）
+
+新しい承認機構は作らない。[edit-plan](../edit-plan/SKILL.md) が使う仕組みをそのまま再利用する。
+
+- [report-template.html](../../packages/decision-cards/report-template.html) を複製し、`node packages/decision-cards/report-helper.mjs <レポートパス>` で提示する。カードの data 属性・雛形の書式・「全部おまかせ」+ 要約ビュー必須・`decision_log` 追記専用の規律は [edit-plan/report-guide.md](../edit-plan/report-guide.md) と同型（`byDefault` / `completedAt` / ポーリング / ヘルパー不通時のチャット代替も同じ）。
+- レポートは固定 5 面を順守する（空でも省略せず理由を書く）:
+  1. **候補ネタランキング表**（[ideate.md](ideate.md) の証拠。`topic-select` カードが載る）
+  2. **競合分析サマリー**（[competitor.md](competitor.md) の証拠。日本語 SNS 事情を含む。決定カードは持たない評価面）
+  3. **構成案タイムライン**（[storyboard.md](storyboard.md) の証拠。`structure-confirm` カードの一部）
+  4. **絵コンテのショットカード**（[storyboard.md](storyboard.md) の証拠。`structure-confirm` カードの一部）
+  5. **撮影チェックリスト**（[shotlist.md](shotlist.md) の証拠。決定カードは持たない評価面 — 変更したい場合は `shot_list` を直接編集し、次ラウンドの状態差分として拾う）
+- 決定カードは 2 枚のみ（契約上の判断点は「ネタ選定」「構成の確定」の 2 点で固定）。
+  - `topic-select`: `answer` は `{ "choice": "<topic.candidates[].id>", "requestMore": false, "note": null }`。AI 推奨（ランキング 1 位の候補）に `data-default="true"` を付ける。
+  - `structure-confirm`: `answer` は `{ "chapters": [{ "id": "<structure.chapters[].id>", "adopt": true }], "openingHook": "<key>" | null }`。
+- `completedAt` が非 null になるまで、当該チェックポイント以降の工程（`topic-select` なら競合/トレンド確定後の企画着手、`structure-confirm` なら撮影リスト作成）に進まない。ヘルパー不通・decisions.json 破損時はチャットの明示承認で代替し、その旨をレポート内の `decision_log` に記録する。
+- 未承認のまま `research-plan.json` の `topic.selected` / `structure.confirmed` を書かない。`decided_at` / `confirmed_at` は decision-cards の確定時刻（またはチャット承認時刻）をそのまま転記する。
+
+## 成果物
+
+プロジェクトの `planning/` 配下に置く。
+
+```
+planning/
+├── research-plan-report.html               # 固定 5 面のレポート
+├── research-plan-report.html.decisions.json
+└── research-plan.json                      # 企画の SSOT。version 必須
+```
+
+- **由来記録**: 外部調査の出典（URL・取得日時・無償/有償の別）を `research-plan.json` の `sources[]` に残す。トレンド調査専用のフィールドは持たない。
+- **後段接続**: `research-plan.json` は撮影後の footage 突合、編集構成案の参照から読める形にする。配信後分析からの還流フィールドは `feedback`（`reserved: true`）に予約のみで、v0 では実装しない。
+
+## よくある間違い
+
+- Hub/Hero/Help や 4 並列ギャップ分析の**説明文まで**参考ソースから転記する（型だけを自分の言葉で書く）。
+- `topic.selected` を人間の承認前に埋める、または `decided_at` を確定時刻より前に記入する。
+- `target.japan_sns.notes` を空にする、または「省略」で済ませる。
+- 有償トレンド API・有償検索 API を承認前に呼ぶ。
+- レポートの 5 面のうち評価専用の面（競合分析サマリー・撮影チェックリスト）にも決定カードを追加し、承認ゲートを 2 点から増やす。
+- `research-plan.json` を書いた後に `validate-research-plan.mjs` を通さない。

package/vendor/skills/research-plan/competitor.md

@@ -0,0 +1,50 @@
+# ターゲット・競合調査
+
+[SKILL.md](SKILL.md) の実行順 2. からだけ読む。成果物は `target`（`audience` / `competitors[]` / `japan_sns`）。[ideate.md](ideate.md) の候補出しと相互に参照してよい（競合調査で見つけた隙間が新しい候補の根拠になり、候補の方向性がここで見る競合の絞り込みに使われる）。
+
+## 1. ターゲットを絞る
+
+依頼文脈から次を埋め、`target.audience` に 1〜2 文でまとめる。情報が薄い場合は無理に確定させず、`null` のまま次工程へ進み理由をレポートに残してよい。
+
+- 年齢層・属性
+- 抱えている悩み・欲求
+- 主にどのプラットフォームで動画を見るか
+
+## 2. 競合を収集する
+
+対象ジャンルの競合を 3〜5 件程度、無償で確認できる範囲（公開チャンネル・公開動画・検索結果）で集める。各競合について `target.competitors[]` に次を記録する。
+
+- `name`: チャンネル名・発信者名
+- `url`: 公開ページの URL。オフライン観察のみで URL が特定できない場合は `null` にし、`notes` に出所を書く
+- `notes`: 観察できた事実（更新頻度・尺・演出の傾向など）
+- `gap`: 次節の 4 軸ギャップ分析の所見
+
+外部調査で使った出典は `sources[]` に URL・取得日時・`cost`（`free` / `paid`）を記録する。有償の調査ツール・API を使う前に [manage-connections](../manage-connections/SKILL.md) の承認ゲートを通す。
+
+## 3. 4 並列ギャップ分析
+
+競合を並べて次の 4 軸で同時に見比べ、自分たちが取れる隙間を `gap` に書く。軸ごとの厳密な enum は持たず自由記述にする（表現の幅を残す）。
+
+1. **コンテンツテーマ**: 競合が扱っていない切り口・悩みがあるか
+2. **フォーマット・尺**: 競合の尺・構成に対して短尺/長尺どちらの隙間があるか
+3. **投稿頻度**: 競合の更新間隔に対して自分たちが優位を取れるか
+4. **訴求軸**: 競合のサムネ・タイトルの打ち出し方に対する差別化点はあるか
+
+ヒットしない軸があっても空欄にせず「差分なし」と明記する。捏造した優位性を書かない。
+
+## 4. 日本語 SNS 事情（必須調査軸）
+
+`target.japan_sns` は空にできない必須フィールドである（ハードルール）。次を埋める。
+
+- `platforms`: ターゲット層が実際に使っているプラットフォーム（例: X、Instagram、TikTok、YouTube Shorts、LINE VOOM 等）
+- `notes`: 日本語圏特有の傾向（プラットフォームごとの温度感、季節性、短尺再編集の需要など）。**無償手段で確認できる範囲**（公開トレンドページ、プラットフォーム公式の急上昇一覧、既存の一般知識）で埋め、有償のソーシャルリスニングツールは [manage-connections](../manage-connections/SKILL.md) の承認ゲートを経てオプトインで使う。
+
+無償手段でも一切確認できなかった場合は、`notes` に「無償手段で確認できず、理由は〜」と正直に書く。空文字・省略は validate-research-plan.mjs でエラーになる。
+
+## よくある間違い
+
+- 競合を 1 件しか見ず「ギャップ分析」と称する。
+- 4 軸のうち都合の良い軸だけ書き、残りを省略する。
+- `japan_sns.notes` を「調査中」で済ませて先へ進む。
+- 有償ソーシャルリスニング API を承認前に叩く。
+- 見つからなかった競合の URL を推測で埋める。

package/vendor/skills/research-plan/ideate.md

@@ -0,0 +1,56 @@
+# ネタ出しと候補ランキング
+
+[SKILL.md](SKILL.md) の実行順 1. からだけ読む。ここでの成果物は `topic.candidates[]`（配列順 = ランキング順、最有力を先頭に置く）と `topic.selected` / `topic.decided_at`（decision-cards の `topic-select` カード確定後にのみ埋める）。
+
+## 0. recipe の recall（候補を出す前に一度）
+
+候補出しに入る前に、[edit-plan/recipe.md](../edit-plan/recipe.md) の recall 手順と同じ規律で
+`~/.akari/recipes/` を確認する。`workflow: "research"` のレシピだけを対象にし、無ければ
+何もせず通常どおり進む（error にしない）。見つかれば `confirmed`（`target_duration_band` /
+`aspect` / `overlay_kinds` 等）を出所付きの推奨としてチャットで添えるが、**今回の依頼を
+上書きせず**、候補出し・競合調査・日本語 SNS 事情確認などの必須工程をスキップさせない。
+採用は人間が「前回と同じで」等を明示したときだけ、対応フィールドを一括で反映してよい。
+
+## 1. 候補を出す
+
+依頼の主題・チャンネルの既存傾向・[competitor.md](competitor.md) / [trends.md](trends.md) の途中知見があればそれも踏まえ、候補を複数（目安 3〜7 件）出す。候補ゼロや 1 件だけで確定しない。根拠のない候補を「調査済み」と偽らない — 依頼文脈からの推測は推測と明記する。
+
+各候補に次を記録する。
+
+- `id`: 候補を指す短い識別子（他の候補と重複しない）
+- `title`: 動画の仮タイトル
+- `category`: 下記の分類
+- `monetization_potential`: `high` / `medium` / `low`
+- `rationale`: 分類・収益ポテンシャルの判断根拠。トレンド調査で得た知見を使った場合は根拠に含め、出典は `sources[]` に記録する
+
+## 2. Hub/Hero/Help で分類する
+
+チャンネル運用でよく使われる 3 分類の型を使う。
+
+- **Hub**: 定期配信でファン化・関係構築を狙う企画。単体の収益貢献は弱くてよい
+- **Hero**: 話題性・拡散を狙う一点突破企画。バズれば新規流入が跳ねるが再現性は低い
+- **Help**: 検索・具体的な悩み解決を狙う企画。息の長い流入源になりやすい
+
+3 分類のバランスを見て、既存チャンネルに欠けている分類があれば `rationale` にその旨を書く。全候補が同じ分類に偏っている場合も黙って進めず、理由を残す。
+
+## 3. 収益化ポテンシャル軸でランキングする
+
+`monetization_potential` は次のような観点の合成で判断し、`rationale` にどの観点を重く見たかを書く。厳密な数式は持たない（v0 は推定ランキングまでで、実データ連携は非スコープ）。
+
+- 広告主・商材との親和性（レビュー導線・アフィリエイト導線が作りやすいか）
+- 息の長さ（季節性・一過性のトレンド依存か、通年で効くか）
+- 制作コストとの釣り合い（収録・生成の手間に見合うリターンか）
+- 既存チャンネル資産との相乗効果（過去動画・登録者属性と噛み合うか）
+
+ランキングは `topic.candidates[]` の配列順で表現する（`rank` フィールドは持たない）。最有力候補を先頭に置き、レポートの候補ネタランキング表もこの順で描画する。
+
+## 4. 承認を受けるまで確定しない
+
+`topic.selected` / `topic.decided_at` は [SKILL.md](SKILL.md) の `topic-select` 決定カードが確定する（`completedAt` 非 null、またはチャット明示承認）までは書かない。AI 推奨（配列先頭の候補）を `data-default="true"` にした候補選択カードを用意し、人間の選択がそのまま候補になる設計にする。
+
+## よくある間違い
+
+- 候補を 1 件だけ出して「これで確定」と即断する。
+- Hub/Hero/Help の分類根拠を書かず、ラベルだけ貼る。
+- `monetization_potential` を勘だけで決め、`rationale` に判断材料を残さない。
+- 承認前に `topic.selected` を仮埋めし、後から書き換える運用にする（承認ゲートの意味が消える）。

package/vendor/skills/research-plan/shotlist.md

@@ -0,0 +1,46 @@
+# 撮影リスト・収録チェックリスト
+
+[SKILL.md](SKILL.md) の実行順 6. からだけ読む。`structure-confirm` カードの `completedAt` が非 null（またはチャット明示承認）になり、`structure.confirmed` が確定した後にだけ着手する。成果物は `shot_list[]`。承認済みの絵コンテショットカード（`structure.shots[]`）を撮影実務に落とす工程であり、ここでは新しい表現判断を作らない。
+
+## 1. ショットごとに実務項目を書く
+
+`structure.shots[]` の各ショットに対応する実務エントリを `shot_list[]` に書く（1 ショット = 1 エントリが基本。同一ショットを複数カット割りする場合はエントリを増やしてよい）。
+
+- `id`: エントリを指す短い識別子
+- `ref_shot_id`: 対応する `structure.shots[].id`。企画段階に無い撮り増しカットなら `null`
+- `location`: 撮影場所。未定なら `null`
+- `equipment`: 必要機材（三脚・照明・マイク等）の配列
+- `checklist`: 収録時に確認する項目の配列（下記のたたき台を対象に応じて増減する）
+- `status`: `planned`（既定）/ `ok`（撮影済み・OK）/ `ng`（撮り直し必要）
+
+## 2. チェックリストのたたき台
+
+対象の性質に応じて増減してよいが、次の観点は落とさない。
+
+- 音声レベル（環境音・声量が適切か）
+- 画角・水平（意図した構図で撮れているか）
+- 光量・ホワイトバランス
+- NG 時の撮り直し方針（同ポジションで撮り直すか、別カットで代替するか）
+
+外部ツール（ExifTool・ffprobe 等でメタデータを機械的に吸い上げる撮影支援）は本スキルの対象外。それらとの ID 共有は将来の別スキルの領分であり、ここでは `ref_shot_id` を安定した参照キーとして残すことだけを担う。
+
+## 3. `status` は撮影後の運用に委ねる
+
+v0 では `status` の初期値は常に `planned`。実際の撮影結果に応じた `ok` / `ng` への更新は、本スキルの一周が終わった後の運用（人間による直接編集、または将来の撮影支援スキル）で行う。ここで架空の撮影結果を書かない。
+
+## 4. 最終確認
+
+`research-plan.json` に `topic` / `target` / `structure` / `shot_list` / `sources` / `feedback` の全フィールドを書き終えたら、必ず検証する。
+
+```sh
+node packages/schemas/bin/validate-research-plan.mjs <research-plan.json のパス>
+```
+
+exit code が `0` になるまで完了扱いにしない（warning は許容されるが完了報告に列挙する）。
+
+## よくある間違い
+
+- `structure.confirmed` が確定する前に撮影リストを作り始める。
+- `status` に撮影していない結果を推測で書く。
+- `ref_shot_id` を書かず、絵コンテとの対応関係が追えなくする。
+- `validate-research-plan.mjs` を通さずに完了報告する。

package/vendor/skills/research-plan/storyboard.md

@@ -0,0 +1,48 @@
+# 企画書・構成案・絵コンテ
+
+[SKILL.md](SKILL.md) の実行順 5. からだけ読む。`topic-select` カードの `completedAt` が非 null（またはチャット明示承認）になり、`topic.selected` が確定した後にだけ着手する。成果物は `structure`（`chapters[]` / `shots[]` / `opening_hook` / `confirmed` / `confirmed_at`）。
+
+## 1. 構成案（チャプター）を組む
+
+確定したネタから、動画の構成ビートを `structure.chapters[]` に配列順（= タイムライン順）で書く。各チャプターに次を持たせる。
+
+- `id`: チャプターを指す短い識別子
+- `title`: チャプター名
+- `duration_estimate_seconds`: 想定尺（秒）。未確定なら `null`
+- `notes`: 演出方針・テロップ方針など
+
+[ideate.md](ideate.md) で分類した Hub/Hero/Help の型に沿ったテンポ・尺を意識する（例: Hero は冒頭フックを強く、Help は手順の網羅性を優先する）。
+
+## 2. オープニングフックを決める
+
+`opening_hook` に、視聴継続を左右する冒頭の見せ方を 1 文で書く（例: 「完成映像を最初の 3 秒で見せる」）。採らない場合は `null` にし、理由をレポート本文に残す。
+
+## 3. 絵コンテのショットカードを作る
+
+各チャプターに対応する主要ショットを `structure.shots[]` に書く。ショットは映像の設計図であり、次節の撮影実務リスト（[shotlist.md](shotlist.md)）とは別物 — ここでは「何をどう見せるか」だけを扱う。
+
+- `id`: ショットを指す短い識別子
+- `chapter_id`: 対応する `structure.chapters[].id`。未割当なら `null`
+- `shot_type`: ショットサイズ・アングルの自由記述（例: `close-up` / `overhead` / `wide`）。厳密な enum にしない
+- `description`: 画面に映るものの説明
+- `duration_estimate_seconds`: 想定尺（秒）。未確定なら `null`
+- `image_path`: 任意の概念画像パス。**v0 の既定は文字だけのショットカード**（無償・headless 完結を優先）。概念画像を生成する場合だけ [edit-plan/approvals-and-generation.md](../edit-plan/approvals-and-generation.md) の Decision Communication Contract（対象・使う手・理由・代替案・影響の宣言）と手の優先順（Codex 画像生成 → Akari Cloud）に従い、provenance を記録する。画像なしなら `null` のままにする
+
+## 4. 承認を受けるまで確定しない
+
+`structure.confirmed` / `structure.confirmed_at` は [SKILL.md](SKILL.md) の `structure-confirm` 決定カードが確定するまで書かない。カードの `answer` はチャプターの採否（`chapters[].adopt`）とオープニングフックの選択を持つ。人間が一部チャプターを不採用にした場合も、`structure.chapters[]` からは削除せず、レポートの `decision_log` に不採用の記録を残す運用にする（削除すると採否の経緯が消える）。
+
+## 5. `structure-confirm` の差し戻し受領手順（plan-comments.json）
+
+`structure-confirm` 決定カードの再提示に着手する前に、`<plan-dir>/plan-comments.json` の有無を確認する（**チャット返信の解釈より先に本ファイルを読む**）。ライフサイクル・データ形の正本は [contract-2026-07-25-plan-comments-v0.md](../../docs/contract-2026-07-25-plan-comments-v0.md)。
+
+- `pass: "structure"` の `plan-comments.json` が在れば、`comments[].target_kind: "shot"` で名指しされた `structure.shots[]`（配列インデックスが `target_id`）**だけ**を改訂する。名指しされていないチャプター・ショットは無変更のまま次の提示に進む。
+- 改訂が終わったら **`plan-comments.json` を削除**してから、更新後の `structure-confirm` 決定カードを再提示する。
+- ファイルが無い回は、従来どおりチャットの差し戻し指示のみを解釈する。
+
+## よくある間違い
+
+- 承認前に `structure.confirmed: true` を書く。
+- 絵コンテのショットカードと撮影実務リストを混同し、`shot_type` に機材名や撮影地を書く。
+- 概念画像の生成前に Decision Communication Contract を宣言しない。
+- 想定尺が不明なのに `duration_estimate_seconds` へ根拠のない数値を入れる（`null` にして「未確定」と明記する方が正直）。

package/vendor/skills/research-plan/trends.md

@@ -0,0 +1,33 @@
+# トレンド取得
+
+[SKILL.md](SKILL.md) の実行順 3. からだけ読む。**専用の `trends` フィールドは持たない。** ここで得た知見は [ideate.md](ideate.md) の `topic.candidates[].rationale` や [competitor.md](competitor.md) の `target.competitors[].gap` に溶け込ませ、出典だけを `sources[]` に残す。トレンドそのものを別セクションとしてレポートに独立掲載しない（候補ネタランキング表・競合分析サマリーの根拠として吸収される）。
+
+## 1. 無償手段を既定にする（ハードルール）
+
+既定のトレンド取得は無償枠のみで完結させる。
+
+- 一般公開されているトレンドページ・急上昇一覧の閲覧
+- 検索エンジンの一般公開結果
+- 既に持っている一般知識（学習時点の傾向。取得日時が不明な場合はその旨を `sources[]` の `note` に明記し、`url` は `null` にする）
+
+無償手段だけでも一周は成立させる。有償のトレンド API（有償枠のソーシャルリスニング・キーワードボリュームツール等)が使えない、または承認が得られない環境でも、ここで停止せず「無償手段のみで確認した」範囲を明記して次工程へ進む。
+
+## 2. 有償手段はオプトイン
+
+有償のトレンド取得手段を使う場合は、[manage-connections](../manage-connections/SKILL.md) の承認ゲート（対象・使う手・理由・代替案・見積費用・待ち時間・外部送信の宣言 → 明示承認）を先に通す。承認が無いまま有償呼び出しをしない。承認後に使った場合は `sources[]` の `cost` に `paid` を記録する。
+
+## 3. 出典を残す
+
+トレンド調査で参照した情報は必ず `sources[]` に 1 件として記録する。
+
+- `url`: 参照ページの URL。URL の無い一般知識由来なら `null`
+- `retrieved_at`: 取得日時（ISO 8601）。不明なら `null`
+- `cost`: `free` / `paid`
+- `note`: 何を確認したか、どの候補・競合の根拠に使ったか
+
+## よくある間違い
+
+- トレンド調査結果を独立したレポート面として作り、固定 5 面から逸脱する。
+- 有償トレンド API を承認前に呼ぶ、または承認ゲートを経ずに「無償枠だから」と誤認して有償枠を使う。
+- 取得日時不明の知見を、あたかも今調べたかのように `retrieved_at` を捏造する。
+- 無償手段で何も見つからなかった場合に、そのまま `sources[]` へ何も残さず知見だけ書く（出典なしの主張を作らない）。

package/vendor/skills/setup-audio-library/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: setup-audio-library
+description: BGM・効果音の音源ライブラリを増やしたいときに発動する。フリー配布元の候補リスト HTML を生成し、ユーザー自身が手動でダウンロードしたファイルをドロップフォルダから照合・登録し、試聴ギャラリーで keep/drop するまでの半自動セットアップを行う。setup-library / harvest-asset の姉妹スキル（音源だけ流儀が異なるため独立）。
+---
+
+# FORBIDDEN 級ハードルール
+
+> **Language**: Respond in the user's language — 対話・質問・承認確認・レポートはユーザーの使用言語に合わせる（例: 英語で話しかけられたら英語で応答する）。
+
+次のいずれかに違反する形で音源セットアップを進めない。詳細リーフより常に優先する。
+
+1. **AI による自動取得は、ユーザーの明示指示がある場合に限り、条件付きで許可する**
+   （2026-07-22 オーナー裁定により改訂。旧ルール「AI は自動・一括ダウンロードしない」を
+   置き換え）。既定はやはり「候補リスト HTML を生成する」「ドロップフォルダを走査する」
+   だけであり、以下の全条件を満たさない限り `curl` 等で配布元から直接音声を取得しない:
+   - **ユーザー本人が当該取得タスクを明示的に指示していること**（「候補を見て後で自分で
+     ダウンロードする」という既定フローを AI が勝手に取得フローへ切り替えない）
+   - **bot/自動収集を規約で明記禁止するサイト、および robots.txt で自動化ボット向けに
+     アクセス制限を明示しているサイトへは一切アクセスしない。** `robots.txt` は毎回
+     取得前に確認すること。ToS が自動化について沈黙している「候補一覧上の許可サイト」
+     であっても、`robots.txt` が named bot（`ClaudeBot` 等 AI クローラ名を含む）に対して
+     個別に `Disallow` を明記している場合は、一般 UA を騙って回避してはいけない
+     （2026-07-22 の実地確認で、効果音ラボの `robots.txt` が `ClaudeBot` を含む主要 AI
+     ボットに対し `Disallow: /*.mp3$` を明記していたことが判明。ToS 沈黙だけで
+     「許可サイト」と判定してはいけない教訓として記録）
+   - **直列取得・リクエスト間 3〜5 秒スリープ・通常ブラウザ相当 UA・失敗はリトライ 1 回
+     まで。** 一括・並列取得はしない
+   - **取得元ページ URL・取得日時・ライセンス・クレジット要否を来歴として必ず記録する**
+     （`~/.akari/assets/audio/_staging/<site>/<id>/` 等の評価用ステージングに
+     `.meta.json` を添える）
+   - **評価後、keep 以外は破棄する。** 取得はあくまで「まとめて試聴して選ぶ」ための
+     一時ステージングであり、無条件の永続保存ではない
+   - ページからファイル URL を実際に読み取れた曲のみ取得する。**当て推量で URL を
+     組み立てて取得しない**（本ルール自体は不変）
+   - フォーム送信・Referer 付与など「実ブラウザが行う標準的な操作の忠実な再現」は
+     許容されるが、認証回避・レート制限回避・robots.txt 迂回を目的にしたヘッダー偽装や
+     UA 偽装は行わない
+2. **候補リストのリンクは必ずダウンロードページ URL にする。** 音声ファイルへの直リンクは
+   張らない（効果音ラボ・甘茶の音楽工房・H/MIX GALLERY 等の「直リンク禁止」規約対応）。
+3. **在庫・実在を捏造しない。** `catalog/audio/candidates.json` に無いサイト・URL・
+   ライセンス表記を発明しない。ページの実在やファイル名を確認できない場合は
+   `confidence: "blocked_unverifiable"` 等、不確かである旨をそのまま記録する。
+4. **`ai_training_allowed` を安全側に倒す。** 配布元の規約が AI 学習利用を明示的に許可して
+   いない限り `false` にする（未許諾を許可とみなさない）。CC0 明記のみ `true`。
+5. **音声実体を本リポにコミットしない。** 実ファイルは常にリポジトリ外
+   （`~/.akari/assets/audio/<id>/` 等の user スコープ）へ置く。`catalog/audio/` には
+   `remote: true` の参照メタしか置かない。
+6. **既存の `catalog/audio/<id>/` を無断で上書きしない。** id が衝突したら書き込みをスキップし
+   ログに残す（harvest-asset / setup-library と同じ規律）。
+7. **`node packages/schemas/bin/validate-asset.mjs` を通さずに「登録完了」と報告しない。**
+   （library scope の実体エントリのみ対象。`remote: true` のカタログ参照エントリは
+   validator 側の設計で preview.png チェックが免除される）
+
+# 実行順リーフ
+
+1. [candidate-list.md](candidate-list.md) — `catalog/audio/candidates.json` を元に候補リスト
+   HTML を生成する。既所有（catalog 登録済み）はグレーアウト表示になる
+2. [drop-folder.md](drop-folder.md) — ユーザーがドロップフォルダへ保存したファイルを走査し、
+   候補と照合してライブラリ配置 + catalog メタ登録、または隔離する
+3. [gallery.md](gallery.md) — 登録済み音源を試聴し、keep/drop を記録する
+
+詳細を先読みせず、現在の工程に対応するファイルだけを読む。
+
+## setup-library / harvest-asset との関係（意図的に独立スキルにした理由）
+
+このスキルは `../setup-library/` や `../harvest-asset/` の meta.json v0 契約・スコープ階層
+（`local` / `shared` / `user` / `builtin`）・validator をそのまま流用する。**ただし取得フロー
+そのものは別スキルとして独立させた**。理由:
+
+- `setup-library` は「その場でカタログを提示 → 承認 → 直接取得 or ログイン誘導」という
+  単一セッション完結のフローを前提にしている。音源は「候補リストを見て、後日ゆっくり
+  ダウンロードして、気づいたときにまとめて登録する」という**非同期・複数セッション**の
+  運用になり、フローの形が本質的に異なる（`starter-pack.md` / `fetch-and-validate.md`
+  へ無理に追記すると分岐が増えすぎる）。
+- ドロップフォルダ走査・ファイル名照合・隔離（出典不明リスト）・試聴ギャラリーは、
+  他カテゴリ（3d/font/broll 等）には無い音源固有の機構。
+- 既存 2 スキルのファイルは変更していない（`setup-library/SKILL.md` にこのスキルへの
+  参照リンクを追加することは今回のタスク境界外のため見送った。ユーザー・オーナーが
+  必要と判断すれば別途追加できる）。
+
+## 根拠
+
+- 内部リサーチ: `research/2026-07-22-free-sfx-bgm-sources.md`（内部リポ、配布元ごとの
+  規約判定・自動化適性・52 候補の一次情報）
+- 公開契約: [`docs/contract-2026-07-13-asset-library.md`](../../docs/contract-2026-07-13-asset-library.md)
+  「カタログと取得スキル」§・「アセットのスコープ階層」§
+- 同型の既存実装（node:http ヘルパー + 静的 HTML の流儀）:
+  [`packages/decision-cards/`](../../packages/decision-cards/README.md)、
+  [`packages/intake-form/`](../../packages/intake-form/README.md)
+- ドロップフォルダによる半自動取得の先例:
+  [`../generate-narration/voice-profile-setup.md`](../generate-narration/voice-profile-setup.md)
+  （mtime ベースの拾いルール。本スキルはファイル名照合ベースだが「ユーザーに取得させ、
+  後からエージェントが拾う」という設計思想は同じ）