akari-video 0.1.0

package/vendor/skills/edit-plan/report-guide.md

@@ -0,0 +1,192 @@
+# 編集判断 — 分析レポートを読み、方針をチャットで決める
+
+> **2026-07-22 改訂（縮退）**: 本スキルが固定 6 章の編集判断レポート（`editing-report.html` +
+> 決定カード）を自ら生成する役割は退いた。オーナー裁定（2026-07-22）「正式なレポート文書として
+> 残るのは分析レポートのみ。方向性の引き出しは完全にチャットへ」の帰結であり、事実 + 素材の
+> 読みは [analyze-project](../analyze-project/SKILL.md) の分析レポート（読み取り専用・
+> 決定 UI なし）が担う。edit-plan はその分析レポートを一次証拠として読み、方針・素材計画・
+> 実行の各判断をチャットで提示して人間の明示承認を得る側になった。
+>
+> 変わらないもの: **decision_log の記録慣行**（[decision_log](#decision_log) 節。置き場所だけ
+> `decision-log.md` という独立ファイルへ変更）、**カット判断一覧・素材計画の三択という実務手順**
+> （[カット判断一覧](#カット判断一覧)・[素材計画](#素材計画)節）、**3 段階チェックポイント**
+> （[approvals-and-generation.md](approvals-and-generation.md)）。変わったのは「これらを 1 つの
+> HTML レポートへ焼き込むか、チャットで提示するか」という提示形式だけであり、記録義務・
+> 根拠提示・承認ゲートの厳格さは緩めていない。
+
+## 目次
+
+- [分析レポートを読む](#分析レポートを読む)
+- [方針をチャットで決める](#方針をチャットで決める)
+- [サムネイル案](#サムネイル案)
+- [カット判断一覧](#カット判断一覧)
+- [素材計画](#素材計画)
+- [decision_log](#decision_log)
+- [汎用カード機構（他スキルが参照する仕様）](#汎用カード機構他スキルが参照する仕様)
+- [自己完結 HTML を作る場合の安全性](#自己完結-html-を作る場合の安全性)
+- [よくある間違い](#よくある間違い)
+
+## 分析レポートを読む
+
+[analyze-project](../analyze-project/SKILL.md) が作る `analysis-report.html`
+（`interpretation.json` + 各素材の `analysis.json` から生成される読み取り専用レポート）を
+一次証拠として読む。レポートが無い、または対象素材が反映されていない場合は、先に
+analyze-project を実行するよう促す（analyze-project 自身は edit-plan の一部ではないため、
+別スキルとして呼び出す）。
+
+分析レポートが持つもの（事実 + 素材の読み + 客観的関係 + 取材台帳 + 来歴）はそのまま証拠として
+引用してよい。分析レポートに**構成案（arc）は表示されない**（`interpretation.json` の
+データとしては存在するが、対話フェーズでの提案の種として意図的に非表示 — analyze-project の
+設計）。編集方針・構成の組み立ては、この節以降で edit-plan がチャット上で行う。
+
+## 方針をチャットで決める
+
+方針（サムネイル案・カット強度・字幕方針・章立て採否・オープニングフック）は、分析レポートの
+根拠を踏まえて **推奨案 + 代替案 + 各案の利点/欠点/失うもの + 推奨理由** をチャットで提示し、
+人間の明示回答を得る。「どうしますか」と選択を丸投げする聞き方はしない（推奨を示した上で
+承認・修正・却下を求める）。
+
+カードに載せていた**決定レベル / 操作レベルの線引きは変えない**: word 単位のカット採否や
+字幕セグメントの一覧はチャットにもレポートにも出さない。それらはアプリ（ビューワー）側の
+領分であり、この線引きは
+[notes-2026-07-14](../../docs/notes-2026-07-14-captions-and-cut-editing.md) 追記部の不変条項。
+
+チャットでの提示 → 回答は [approvals-and-generation.md](approvals-and-generation.md) の
+Checkpoint 1（方針）として運用し、確定内容を `decision-log.md`（[decision_log](#decision_log) 節の慣行）へ追記する。
+
+## サムネイル案
+
+3 経路（実フレーム / Codex 生成 / 混成）の候補画像を作り、チャットで比較提示する。
+
+- **経路 A**: 視認済み実フレーム + [thumbnail authoring](../overlay-authoring/thumbnail.md) に従う HTML 文字組。source と時刻を記す。
+- **経路 B**: Codex 画像生成。手、prompt、生成日時を記す。
+- **混成**: B で背景を作り、A の HTML 文字組で日本語タイトルを載せる。両工程の provenance を分ける。
+
+可能なら 3 経路を 1 案以上ずつ比較する。経路 B または混成が利用不能でも架空画像を置かず、複数の A 案を提示して利用不能理由を記す。この `3` は M5 契約の 2 経路 + 混成から導く比較数で、プラットフォームの成功閾値ではない。
+
+上位タスクの指示で経路 A/B/混成の一部にしかスコープが与えられていない場合は、**未実施**と**利用不能**を区別して記録する。「利用不能」は経路を試みたが実行できなかった場合に使い、「未実施（スコープ外）」は上位タスクの指示によって最初からその経路を対象外にした場合に使う。両者を区別しないと、後続工程が「生成を試みて失敗した」のか「そもそも指示されていない」のかを判別できない。
+
+対象外の経路は、チャット提示でも比較の枠自体は残したまま架空画像を置かず、`未実施（スコープ外: <上位タスクが指定した範囲の要約>）` の 1 行に置き換える。`decision-log.md` には `(thumbnail, route-a)` / `(thumbnail, route-b)` / `(thumbnail, route-mixed)` のうち対象外の経路をキーに、決定を `未実施（スコープ外）`、理由に上位タスクの指示文またはその要約を記録する。
+
+画像生成の前には [approvals-and-generation.md](approvals-and-generation.md) の宣言を行う。
+
+## カット判断一覧
+
+各行に素材 ID、source の `start/end`、`keep` または `drop`、根拠 event、根拠 anchor、理由を書く。keep range は source ごとに昇順・非重複にする。カット後 timeline 時刻と source 時刻を混ぜない。ここに並ぶのは決定レベルの keep/drop であり、word 単位の採否はアプリ側で操作する。
+
+この一覧はチャットでの提示に使うと同時に、`edit.json.cuts` を組み立てる直接の一次証拠になる。`decision-log.md` の `cut` category にまとめて記録する（1 行 1 区間、または要約 + 詳細は生成物として別途保存してもよい）。トレーラー・オープニングフックなど本編と別に切り出す**切り出し・先出しクリップの `in/out` は、見せ場スコア位置の機械窓のままにせず、クリップ内発話へスナップして呼吸 0.5s を残す**（発話スナップの規則は [execution.md](execution.md) §2）。
+
+## 素材計画
+
+全体枠とシーン枠を分ける。
+
+- **全体**: BGM、字幕（全文字幕の方針）。目的、入り・抜け、ライセンスまたは生成可否を扱う。
+- **シーン単位**: SFX、B ロール、テロップスタイル、特殊表現。対象 scene と時刻を付ける。
+
+**字幕枠は方針レベルだけを扱う**（セグメント単位の内容一覧はチャットにもレポートにも載せない。確認・修正はアプリの字幕リストと contenteditable で行う）。字幕枠の方針としてチャットで提示・決定する事項:
+
+- 付ける / 付けない / 選択的（重要箇所のみ）の別と理由
+- スタイル（配置・行数・1 行文字数目安・地と文字色。telop.md の字幕原則に従う）
+- **カットとの従属関係**: 字幕はカット後タイムラインに従属し、カットで除去された発話は字幕ごと消える（字幕を理由にカットを変えない。変えたい場合はカット判断の修正として扱う）
+- 長文の分割・時間按分の規則（word タイムスタンプがある場合はそれを優先）。**表示区間は実発話区間に一致させ、segment 境界を敷き詰めない**（隙間の原則。実発話が終われば字幕も終わる。区間の作り方は [execution.md](execution.md) §4）
+- 修正の運用: ASR 生テキストの誤りはアプリ内で直す前提（将来のエージェント整え機能はスコープ外なら明記）
+- カラオケ表示・強調ポップの採否（既定は不使用）
+
+各枠は次の三択から **1 つ**を明記する。この `3` は M5 契約の判断肢であり、運用上の推測値ではない。
+
+1. **あれば提案**: 実際のライブラリ検索結果、権利条件、プレビュー画像または試聴参照を示す。検索は全スコープ層を近い順（プロジェクト `assets/` → 上位ディレクトリの `.akari/assets/` → `~/.akari/assets/` → 製品リポ `assets/` → `catalog/`）に行い、提案にはどの層のヒットかを明記する。同一 id は近い層を採る。
+2. **なければ生成**: prompt、生成する手、生成済み静止プレビュー、provenance を示す。動画 B ロールはまず静止画だけを作る。
+3. **使わない**: 無理に埋めず、非採用理由を示す。
+
+候補が見つからないことを「あれば提案」と記録しない。BGM と SFX は `audio`、ナレーションは `audio.narration[]`、動画 B ロールは v1 の `sources[]` + `cuts[].src` へ格納できる（[execution.md](execution.md) §1）。公開契約のどのフィールドでも表せない演出だけ、計画上の採用と `edit.json` への格納可否を分けて提示する。単一中間マスターへ焼き込む場合は実行承認の対象にする。
+
+ナレーションの話者がアバターのときは、原稿を書く前に [avatar-resolution.md](avatar-resolution.md#台本生成への接続persona-注入s2-具体化) の persona 注入手順（ペルソナ要約の反映・NG 遵守）に従う。
+
+このチャット提示は Checkpoint 2（素材計画）として運用し（[approvals-and-generation.md](approvals-and-generation.md)）、確定内容を `decision-log.md` の `material` category に記録する。
+
+## decision_log
+
+`(category, subject)` を判断対象のキーとして、時刻順に追記する。各行に ISO 8601 日時、category、subject、決定、理由、決定者、関連 checkpoint を持たせる。同じキーの方針が変わっても過去行を直さず、新しい行を追加して以前の決定を参照する。
+
+**置き場所**（2026-07-22 改訂）: 固定 6 章 HTML の 1 節として埋め込む運用は retired。プロジェクト直下の独立ファイル `decision-log.md` に追記する（[analyze-project の decision-record.md](../analyze-project/decision-record.md) と共有する単一 SSOT — analyze-project の 2 パス目判断・取材 Q&A と、edit-plan の承認・生成判断が同じファイルへ時系列に積み重なる）。フィールド構成・追記専用の規律はここで変えていない。
+
+次を決定として記録する。
+
+- 方針、素材計画、実行の承認・却下・修正要求
+- 生成手の選択と fallback
+- `使わない` を含む明示的な非採用
+- source 構成の選択（v1 マルチソース / v0 単一 source / 中間マスターへ conform）
+- overlay-authoring 不在時の CLAUDE.md fallback
+- 上位タスクの指示によるサムネ経路 A/B/混成の未実施（スコープ限定）
+- チャットでの方針確定内容（推奨どおりか、修正が入ったか。差分を記録する）
+
+## 汎用カード機構（他スキルが参照する仕様）
+
+以下は選択肢式の質問対話に使う汎用カード機構の仕様である。**edit-plan は自身の方針決定に
+この機構を使わない**（方針はチャットで決める。上の各節を参照）。ただし
+[research-plan](../research-plan/SKILL.md) の候補選定カードや [plan-json.md](plan-json.md) の
+質問対話（素材ゼロからの企画起点フロー）はこの機構をそのまま使い続けるため、仕様は SSOT として
+維持する。
+
+### カードの data 属性
+
+カードの DOM は [report-template.html](../../packages/decision-cards/report-template.html) に従う。ランタイム（ヘルパーが注入する JS）が次の data 属性だけを解釈して UI 化する。カード種別のハードコードはしない。
+
+| 属性 | 置く要素 | 意味 |
+|---|---|---|
+| `data-card="<id>"` | カードコンテナ | 1 決定。id は decisions[].id と一致 |
+| `data-question="<文>"` | カードコンテナ | 質問文（要約画面で使う） |
+| `data-option="<key>"` | 選択肢要素 | 単選の選択肢 |
+| `data-default="true"` | 選択肢要素 | AI 推奨（初期選択）。カード内に必ず 1 個 |
+| `data-check="<key>"` | チェック要素 | 追加の複数選択（任意） |
+| `data-note` | textarea 等 | 自由記入（任意） |
+| `data-action="accept-all"` | ボタン | 全カード既定値のまま要約画面へ |
+| `data-action="commit"` | ボタン | 確定 → completedAt 記入 |
+| `data-view="summary"` | コンテナ | 確定内容の要約画面 |
+
+- 上記以外の見た目・構成は自由 HTML。エンジンが解釈するのは data 属性だけ。
+- 根拠・証拠・詳細は `<details>` の折りたたみに置く。カード表面には質問と選択肢だけを残す。
+
+### decisions.json 雛形
+
+カードを使うスキルは、レポートと対になる `<レポートパス>.decisions.json` の雛形を併せて書く。雛形は全カードの `answer` に AI 推奨の既定値を入れ、`byDefault: true` / `answeredAt: null`、トップレベルの `completedAt: null` とする。
+
+```jsonc
+{
+  "version": 0,
+  "report": "<レポートへの相対パス>",
+  "createdAt": "<ISO8601>",
+  "completedAt": null,
+  "decisions": [
+    { "id": "<data-card と一致>", "answer": { }, "byDefault": true, "answeredAt": null }
+  ]
+}
+```
+
+- `answer` の形はカード種別ごとに使用側スキルが宣言する（HTML と decisions 雛形が SSOT）。
+- 人間の操作はヘルパーが `answer` / `byDefault: false` / `answeredAt` を更新する。雛形を上書きせず、ラウンドごとにレポート + decisions の組を増やす。
+- decisions.json が無い・破損している場合、使用側スキルはチャットの明示承認で代替する。
+
+### おまかせと要約ビュー
+
+「全部おまかせ」ボタン（`data-action="accept-all"`）と要約ビュー（`data-view="summary"`）は必須。おまかせでも即開始は禁止。必ず要約 1 画面を挟んでから確定する。確定（commit）でヘルパーが `completedAt` を記入し、使用側スキルはそれをもって進行してよい。
+
+## 自己完結 HTML を作る場合の安全性
+
+edit-plan がサムネイル候補シートなど自己完結 HTML を作る場合は次を守る。
+
+- CSS、画像、根拠 transcript を HTML 内へ入れ、外部 CSS、font、script、remote image を参照しない。
+- 実フレームと生成画像は `data:image/...;base64,...` として埋め、意味のある `alt` を付ける。
+- transcript、所見、タイトル、prompt、path を文脈に合わせてエスケープする。未検証 HTML、`javascript:` URL、event handler を挿入しない。
+- 状態を色だけで表現せず、`未承認`、`承認`、`却下` を文字で表示する。
+
+## よくある間違い
+
+- analyze-project の分析レポートを読まずに方針を組み立てる（根拠のない推奨案を作る）。
+- ライブラリの実ヒットがないのにプレビューを捏造する。
+- 生成画像へ prompt は残すが、手や日時を残さない。
+- 最新判断で `decision-log.md` の過去行を上書きする。
+- remote image を貼り、自己完結成果物に見せる。
+- スコープ外で未実施の経路を「利用不能」と書き、試みて失敗したかのように見せる。
+- word 単位のカット採否や字幕セグメント一覧をチャットに載せる（決定レベル/操作レベルの線引き違反）。
+- 「どうしますか」と選択を丸投げし、推奨案・代替案・理由を示さない。

package/vendor/skills/edit-plan/workflow.md

@@ -0,0 +1,108 @@
+# 分析収集と統合ワークフロー
+
+## 原則
+
+素材ごとの観察と、素材横断の編集判断を分離する。各分析はその素材だけを扱い、統合エージェントだけがサムネイル、方向性、カット、素材計画を比較する。
+
+## 1. 入力と出力先を固定する
+
+入力として、素材パス、既存 `analysis.json`、希望する出力先を列挙する。出力先の指定がなければ、素材群の共通プロジェクトディレクトリ直下の `edit-plan/` を提案し、採用理由を完了報告に残す。別プロジェクトの既存レポートや `decision-log.md` を混ぜない。
+
+標準出力は次の形とする（2026-07-22 改訂: `editing-report.html` は生成しない。分析レポートは
+[analyze-project](../analyze-project/SKILL.md) がプロジェクト直下に作る `analysis-report.html` を
+指し、edit-plan はそれを読む側になる）。
+
+```text
+<plan-dir>/
+├── decision-log.md            # analyze-project と共有・追記専用（判断記録）
+├── edit.json                  # 実行承認後だけ
+├── overlays/                  # 実行承認後だけ
+└── generated/                 # 生成した静止画等の原本（provenance 込み）
+```
+
+生成物の原本と provenance は再検証できるよう残す。方針・素材計画の証拠は analyze-project の
+分析レポート（読み取り専用・自己完結 HTML）を参照する。
+
+## 2. 素材の有無で分岐する
+
+### 録画素材がある場合
+
+素材ごとに次の順で既存分析を探す。
+
+1. ユーザーが明示した `analysis.json`
+2. `<source-dir>/analysis/<source-stem>/analysis.json`
+3. 素材専用ディレクトリであると確認できる場合だけ `<source-dir>/analysis/analysis.json`
+
+相対 `source`、`keyframes[].path`、`tracks.person_matte` は、それぞれの `analysis.json` 所在ディレクトリを基準に解決する。パス文字列を分析レポートや `decision-log.md` の場所から解決し直さない。
+
+有効な分析がない素材は、1 素材 = 1 サブエージェントとして `analyze-footage` を実行する。複数素材なら、利用可能なサブエージェントへ同時に割り当ててから全件を待つ。各依頼には source の絶対パス、リポジトリルート、[analyze-footage](../analyze-footage/SKILL.md) を渡し、他素材や共有成果物を編集させない。逐次実行へ変えた場合は理由を報告する。
+
+既存分析を再利用するときも `source` が対象素材を指すことを確認する。新旧判定に必要な hash や解析日時は v0 Schema にないため、鮮度を推測しない。素材が更新された疑いがあれば再分析するか、人間へ差分を示す。
+
+### 素材がゼロの場合
+
+`analysis.json` を捏造しない。「リサーチ → 台本 → 生成計画」モードとし、録画素材がないこと・
+採用した根拠・台本の版をチャットで提示し、`decision-log.md` に記録する（analyze-project は
+素材の analysis.json を前提とするスキルであり、素材ゼロのこの分岐では使わない）。静止コンセプト
+も同様にチャットで提示し、動画生成は承認工程まで保留する。生成後に複数クリップとなる場合も、
+実行時には [execution.md](execution.md) §1 の source 構成規則を適用する（複数クリップは v1 の `sources[]` + `cuts[].src` が第一選択肢）。
+
+方針決めは [plan-json.md](plan-json.md) の手順で行う: 選択肢式の質問対話で深掘り、確定した構成ビートと制約を `<plan-dir>/plan.json`（仮枠タイムライン。[contract-2026-07-20-plan-json-v0.md](../../docs/contract-2026-07-20-plan-json-v0.md)）へ落としてからチャットでの方針提示に入る（[report-guide.md](report-guide.md) 参照）。以降の提示は plan.json の slot id を根拠として参照する。
+
+## 3. 各 analysis.json を検証する
+
+[analysis.schema.json](../../packages/schemas/analysis.schema.json) を Draft 2020-12 対応 validator で検証する。validator を得るための無断ネットワーク導入はしない。併せて次を確認する。
+
+- `source` と全 keyframe path が解決できる。
+- すべての区間で `end > start`、時刻が source duration 内である。
+- face box の `x + width <= 1`、`y + height <= 1` が成立する。
+- transcript、event、track の speaker ID が矛盾しない。
+- `transcript: []` が「無発話」なのか「文字起こし未取得」なのか、分析エージェントの報告で区別できる。
+
+不正な分析を黙って修復して統合しない。再分析、当該素材の除外、根拠不足のまま限定利用、の得失を示し、人間の選択を `decision-log.md` に追記する。
+
+## 4. 素材横断の証拠索引を作る
+
+素材 ID、source path、duration、transcript 区間、keyframe、event を対応付ける表を作る。チャット提示や `decision-log.md` から参照できる安定した ID を割り当て、引用箇所を明確にする。
+
+カット候補は source ごとに keep/drop と根拠 event を作る。この時点では `edit.json` を作らない。複数素材を 1 本のタイムラインへ並べる順序も、編集方針の承認対象にする。
+
+## 5. チェックポイントを進める
+
+段階の運びは変わらないが、各段階の証拠は「レポートを更新する」のではなく「analyze-project の
+分析レポートを読み、チャットで提示する」形に変わった（[report-guide.md](report-guide.md) 参照）。
+
+Checkpoint 1 の提示に着手する前に、[recipe.md](recipe.md) の recall 手順で
+`~/.akari/recipes/`（`workflow: "edit"`）を確認する。見つかれば出所付きの推奨として添え、
+今回の方針提示を上書きしない（採用は人間の明示宣言があったときだけ）。
+
+1. サムネイル案・編集方針・カット案をチャットで提示し、Checkpoint 1（方針）で停止する。
+2. 承認された方針に沿って素材計画（BGM/字幕/SFX/B ロールの三択）と静止プレビューをチャットで
+   提示し、Checkpoint 2（素材計画）で停止する。
+3. 出力仕様、source 構成の選択（v1 マルチソース / v0 単一 source / 中間マスターへ conform）、生成・conform・overlay の実行一覧を提示し、
+   Checkpoint 3（実行）で停止する。
+4. 承認後だけ `edit.json` と最終 overlay を作る。完了処理として [recipe.md](recipe.md) の
+   freeze 手順を確認し、そのプロジェクトでまだ申し出ていなければ一度だけ（offer-once）
+   レシピ化を人間に申し出る。
+
+各チェックポイントの承認内容・修正指示は `decision-log.md` へ追記する（既存行は変更・削除
+せず、新しい行を末尾へ追加する）。カット判断一覧（素材 ID・source の start/end・keep/drop・
+根拠 event・理由）と素材計画の三択結果（あれば提案 / なければ生成 / 使わない）は、
+`decision-log.md` の該当 category（`cut`/`material`）の下に一覧として記録し、`edit.json` 生成時
+の一次証拠にする。
+
+## 6. 出力先の補足
+
+ad-hoc な検証スクリプトや、統合判断のための一時的な比較・実験生成物は、プロジェクトルート
+直下や `<plan-dir>/` 直下に書かず、`.akari/work/` へ置く
+（[project-structure-v0 契約](../../docs/contract-2026-07-25-project-structure-v0.md) §1）。
+`decision-log.md`・`edit.json`・`overlays/`・`generated/` 等、正式な生成物の出力先（§1）は変わらない。
+
+## よくある間違い
+
+- 複数素材を 1 サブエージェントへ渡し、素材ごとの証拠境界を失う。
+- `analysis.json` から見た相対パスを、分析レポートや `decision-log.md` から見た相対パスとして開く。
+- `transcript: []` を無音と断定する。
+- 素材ゼロなのに架空の分析 event を作る。
+- チャットでの提示より先に `edit.json` や最終 overlay を作る。
+- analyze-project の分析レポートを読まずに方針を組み立てる（根拠のない推奨案を作る）。

package/vendor/skills/generate-narration/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: generate-narration
+description: 原稿テキストから VOICEVOX（ローカル・ゼロ円の既製声）または fal Qwen3-TTS（自声クローン）でナレーション音声を生成し、edit.json の audio.narration[] へ書き込むスキル。ナレーションを作ってほしいと頼まれたとき、仮ナレ（下書き試聴）が欲しいとき、声プロファイルを新規に作りたいとき、または既存のナレーションをエンジンや声で差し替えたいときに使う。
+---
+
+# ナレーション音声を生成する
+
+> **Language**: Respond in the user's language — 対話・質問・承認確認・レポートはユーザーの使用言語に合わせる（例: 英語で話しかけられたら英語で応答する）。
+
+# FORBIDDEN 級ハードルール
+
+次の規則は詳細手順より常に優先する。
+
+1. **人声クローンはプロファイル所有者本人の声のみ。** consent 記録が無いプロファイルは使用しない
+2. **参照音声を外部送信する前のローカル whisper 照合ガード必須。** スキップはオーナー明示指示時のみ、
+   かつその旨を記録する
+3. **生成には読み原稿（かな化）を使い、script / reading を両方 edit.json に記録する**
+4. **有償レーン（fal）は費用宣言 → 明示承認後のみ実行する。** ElevenLabs は凍結中 — 選択肢として
+   提示すること自体をしない
+5. **API キー直叩き禁止・manage-connections 経由のみ。** doctor が `ok` でないレーンは提示しない
+6. **provenance を毎回記録する。** VOICEVOX 系の声は credit 欄（例「VOICEVOX:ずんだもん」）が必須
+
+## 実行順と目次
+
+1. [engines.md](engines.md) を読み、エンジンアダプタ（voicevox / fal-qwen3）の使い方、選び方、
+   仮ナレ→本番の二段運用を確認する。ナレーション音声の生成そのものはここで行う。
+2. 声プロファイルがまだ無く自声クローンを使いたい場合だけ [voice-profile-setup.md](voice-profile-setup.md)
+   を読み、原稿提示 → 録音 → whisper 照合ガード → fal クローン → 保存 → 耳検収の手順を踏む。
+3. 表示原稿を読み原稿（かな化）に変換する前処理は [reading-text.md](reading-text.md) を読み、
+   規約に沿って行う。
+4. 話者がアバターのときは [avatar-voice.md](avatar-voice.md) を読み、`voice/voice.json` の `lane`/`ref` を上記エンジンへ解決する。
+
+現在の工程に対応するファイルだけを読み、先読みしない。
+
+## 根拠
+
+- データ契約: [docs/contract-2026-07-20-edit-json-v1-narration.md](../../docs/contract-2026-07-20-edit-json-v1-narration.md)
+- 音声契約（BGM/SFX・ducking の前提）: [docs/contract-2026-07-14-edit-json-v1-audio.md](../../docs/contract-2026-07-14-edit-json-v1-audio.md)
+- 接続・doctor・費用承認の統治: [../manage-connections/SKILL.md](../manage-connections/SKILL.md)（編集はしない）
+- クラウド送信の模範実装: [../analyze-footage/bin/transcribe-cloud.mjs](../analyze-footage/bin/transcribe-cloud.mjs)

package/vendor/skills/generate-narration/assets/reading-script-v1.md

@@ -0,0 +1,18 @@
+# 朗読原稿 v1（声プロファイル setup 用）
+
+- バージョン: v1
+- 文字数: 約 330 字
+- 想定尺: 45〜60 秒
+- 用途: 声プロファイル作成時の参照録音（`reference_text` と完全一致させるため、この本文を人間が改変しない）
+
+この本文は正文であり、書き換えない。訂正が必要な場合は v2 として新しいファイルを追加し、
+`voice-profile-setup.md` から参照するバージョンを切り替える（プロファイルの `meta.json` に
+`script_version` を記録し、どのバージョンで作られたプロファイルかを追跡する）。
+
+## 本文（v1）
+
+こんにちは。これは、AKARI Video のナレーション用ボイスプロファイルを作るための録音です。普段の話し方より、少しだけ丁寧に、ゆっくり読み上げてください。
+朝の光が窓から差し込み、街はゆっくりと動き出します。コーヒーを一杯淹れて、今日の計画を立てましょう。
+新しい技術は、私たちの毎日を静かに変えていきます。動画の編集も、資料の作成も、これからはもっと自由になります。
+数字の読み方も確認します。1、2、3、4、5。2026年7月20日、気温は28度、湿度は65パーセント。
+最後に、いつもの調子でひとこと。今日もいい一日にしましょう。以上で録音は終わりです。ありがとうございました。

package/vendor/skills/generate-narration/avatar-voice.md

@@ -0,0 +1,54 @@
+# アバターの声を narration-tts レーンへ自動解決する（S2 新設）
+
+台本の話者がアバター（[edit-plan/avatar-resolution.md](../edit-plan/avatar-resolution.md) で
+解決済み）のとき、そのアバターの `voice/voice.json`（L2。このときだけ読む — 他のアバターの
+`voice/` は読まない）を読み、`lane` / `ref` / `credit` を [engines.md](engines.md) の 3 レーンへ
+そのまま渡す。**アバター専用の新しいエンジン・新しいフィールドは発明しない** — voice-tts
+契約の既存 3 レーンをアバターの登録値で呼び出すだけの薄い解決層である。
+
+## 解決手順
+
+1. `voice/voice.json`（無ければ `avatar.json` の `voice` オブジェクト。同内容）から
+   `lane` / `ref` / `credit` を読む
+2. `lane` に応じて engines.md のコマンドへ引数を組み立てる（下表）
+3. 生成後、`credit` が非 null なら [credit の転写](#credit-の転写) の手順で `provenance.credit`
+   に反映されていることを確認する
+4. `edit.json` のスキーマは変更しない — `audio.narration[].provenance.voice` にはアバターの
+   `voice.ref`（`speaker:3(ずんだもん/ノーマル)` / `profile:owner-ja` のような narration-tts
+   契約と同型の参照文字列）がそのまま入るだけであり、アバター ID を指す新フィールドは追加しない
+
+## lane ごとの解決
+
+| `voice.lane` | 解決先 | 承認ゲート | 備考 |
+|---|---|---|---|
+| `voicevox` | `--engine voicevox --speaker <ref から取り出した id>` | 不要（ゼロ円・宣言のみ。ハードルール 4 の対象外 — engines.md の voicevox アダプタと同じ） | `ref` の形式 `speaker:<id>(<名前>)` から先頭の整数を取り出して `--speaker` に渡す |
+| `fal-clone` | `--engine fal-qwen3 --profile <ref から取り出した profile 名>` | **必要**（費用宣言 → 明示承認後のみ実行。ハードルール 4） | まず `--dry-run` で見積り費用を提示し、承認を得てから `--yes --apply` 相当を実行する。本人以外の声を無断で使わない（ハードルール 1 は generate-narration 本体が担保） |
+| `recorded` | TTS 呼び出しなし | 該当なし | 人間が用意した音声ファイルをそのまま `audio.narration[].path` に置き、`provenance.provider: "human"` として記録する（generate-narration.mjs は使わない） |
+
+`ref` の取り出し方（正規表現の目安）:
+
+- `voicevox`: `ref` が `speaker:3(ずんだもん/ノーマル)` の形なら `speaker:` の直後から次の `(` まで
+  の数字が `--speaker` の値
+- `fal-clone`: `ref` が `profile:owner-ja` の形なら `profile:` の直後が `--profile` の値
+
+## credit の転写
+
+`voice.credit`（非 null のとき）は narration の `provenance.credit` へ転写する。
+
+- **`voicevox` レーン**: `generate-narration.mjs` は生成のたびに VOICEVOX エンジンへ `/speakers`
+  を問い合わせて話者名を解決し、`credit: "VOICEVOX:<話者名>"` を自動で `provenance` に埋める
+  （[engines.md](engines.md#voicevox-アダプタ)）。通常はこの自動値がアバターの登録 `credit` と
+  一致する（同じ speaker id を指しているため）。**一致することを確認し**、値が空でないことだけ
+  検査すればよい（手で書き直す必要はない）
+- **`fal-clone` レーン**: `generate-narration.mjs` の fal 経路は `credit` を `provenance` に
+  自動で埋めない（自声クローンには通常クレジット義務が無いため）。もしアバターの `voice.credit`
+  が非 null のまま fal-clone を使うケースがあれば（例外的な third-party クローン）、生成後の
+  `entry.provenance.credit` にアバターの `voice.credit` を手動で追記してから `edit.json` へ
+  反映し、`validate-edit.mjs` を再実行する
+
+## 出力の確認
+
+`--apply` を付けない場合、標準出力の `entry` JSON（`provenance` 含む）で `voice` / `credit` が
+アバターの登録値と一致することを確認できる。`--apply` する場合は
+[approvals-and-generation.md](../edit-plan/approvals-and-generation.md) のチェックポイント運用に
+従う。