akari-video 1.5.0-beta.2 → 1.5.0-beta.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akari-video",
-  "version": "1.5.0-beta.2",
+  "version": "1.5.0-beta.3",
   "description": "AKARI Video launcher CLI — start an AI-edited video project from any directory: scaffold, connection check, then hand over to Claude Code (or opencode). AKARI Video を opencode や Claude Code で、どのディレクトリからでも始めるための `akari` ランチャー CLI。接続確認（doctor）→ 未セットアップならプロジェクト雛形を作成 → AI エージェントを起動する。外部 npm 依存ゼロ（Node.js 組み込みモジュールのみ）。",
   "type": "module",
   "bin": {

package/vendor/.akari-capability-sources.json

@@ -91,6 +91,7 @@
     "docs/contract-2026-10-11-ui-i18n.md",
     "docs/contract-2026-10-12-caption-look-v1.md",
     "docs/contract-2026-10-15-playbook-v0.md",
+    "docs/contract-2026-10-15-script-lines-v0.md",
     "packages/akari-ear/package.json",
     "packages/akari-ear/README.md",
     "packages/akari-launcher/package.json",

package/vendor/docs/contract-2026-10-15-playbook-v0.md

@@ -48,7 +48,8 @@ updated: 2026-10-15
 | 確認シート | `<project>/.akari/reports/playbook-sheet.html`（読み取り専用・派生） | `akari new --from` |
 
 - 一覧の解決順は **チャンネル → 手元** の 2 択だけ（`create-project` の雛形解決と同じ規律。他の経路を作らない）
-- `preview/` は任意。`cover.png` か `sample.mp4` を 1 つまで。無ければ画面は文字だけで出す
+- `preview/` は任意（下の項）
+- `preview` のパスはすべて **playbook.json からの相対**。棚（手元・チャンネル）では `preview/cover.png`（任意）と `preview/frames/01.png`〜`05.png`（重要な場面のコマ 3〜5 枚・長辺 640px 以下・作り方の画面比）を置く。表紙が無ければ `frames` の 1 枚目を表紙にする。動画（sample.mp4）は持たない（重いため）。プロジェクトの中では `planning/playbook-preview/frames/` に置く
 - `<id>` は英小文字・数字・ハイフン。同じ `id` は版で区別する（`version` 整数）
 
 ## 2. 形 — playbook.json
@@ -94,6 +95,8 @@ updated: 2026-10-15
 - 必須: `version`（0 固定。原則 1）・`kind`（`"akari-playbook"`）・`id`・`name`・`playbookVersion`・`depth`・
   `category`・`steps[]`・`settings`・`license`・`provenance`。`tags` / `requires` / `placeholders` / `parts` は
   省略可（depth 1 では `placeholders` と `parts` を持たない）
+- 任意: `preview`（`{ "cover"?: string, "frames"?: string[] }`。パスは上の規則）・`example`（`true` なら見本として配る例。画面に「例」の印を出す）
+- 任意: `beats`（`{ id, at, duration, title, note?, placeholder? }[]`・秒。作り方の内訳。始めたとき空のキャンバスと台本の予定の行になる。script-lines-v0 §5）
 - `category` は 1 つだけ。語彙は閉じる: `film` / `short-drama` / `mv` / `explainer` / `product` / `vlog` / `cm` /
   `education` / `clip` / `logo`。足すときは本表に追記してから
 - `tags` の 8 軸は開いた語彙（自由に足せる）。軸の名前だけ固定: `form` / `length` / `technique` / `tools` /
@@ -118,6 +121,7 @@ updated: 2026-10-15
 ## 流れ                     ← steps を番号つきで。確認点は「☑ ここで確認」と明記
 ## 設定値                   ← settings を表で（キー / 値 / 意味）
 ## 必要な素材（仮枠）        ← placeholders を表で（役割 / 種類 / 尺の目安 / 見本）
+## 内訳                     ← beats を表で（時刻 / 見出し / メモ / 仮枠）
 ## 使った部品               ← parts を表で（種類 / 名前 / 入手先 / ライセンス）
 ## 要る道具                 ← requires（CLI の版・道具・スキル）。無いときの代案を 1 行
 ## ライセンス               ← license と、外部由来を仮枠にした旨
@@ -125,6 +129,7 @@ updated: 2026-10-15
 ```
 
 章の追加は末尾のみ（additive-only）。章の名前は上の表記で固定し、読み手はこの見出しで章を引く。
+例外として「内訳」の 1 章だけは「必要な素材（仮枠）」の直後に置く。
 
 ## 4. 記録する — プロジェクト → 作り方（`record-playbook` スキル）
 

package/vendor/docs/contract-2026-10-15-script-lines-v0.md

@@ -0,0 +1,67 @@
+---
+lifecycle: accepted
+created: 2026-10-15
+updated: 2026-10-15
+---
+
+# script-lines-v0（台本の「予定」と「メモ」の行）契約
+
+- 日付: 2026-10-15
+- 状態: **v0 受理（2026-10-15 オーナー GO）**
+- 前提: `contract-2026-07-25-project-structure-v0.md`（`planning/` は企画・プランの層）/ `contract-2026-09-24-caption-runs-v0.md`（字幕は `captions.json`）/
+  `contract-2026-10-15-playbook-v0.md`（作り方。本契約の「予定」は作り方の内訳 `beats` から作られる）/ `contract-2026-09-25-canvas-v0.md`（空のキャンバス = 区間を持つ仮枠）
+- 発端: 台本パネルは字幕の行しか持たず、「ここに何を入れる予定か」「気づいたメモ」を時刻つきで残せない。作り方の内訳（何秒に何を）も、台本とタイムラインに出す場所が無い
+- スコープ: 予定とメモの行の **置き場・形・台本パネルとタイムラインでの見せ方・作り方からの生成**
+- 非スコープ: 字幕（`captions.json`）の形の変更 / 予定の行から自動でカットを作ること / 複数人の同時編集
+
+## 0. 位置づけ
+
+台本の行は 3 種類。**字幕**（`captions.json`。今のまま）・**予定**（ここに何を入れるつもりか）・**メモ**（気づき・指示）。
+予定とメモは `planning/script.json` に持ち、台本パネルは 3 種を時刻順に 1 本の列で見せる。字幕は今までどおり `captions.json` が正本で、本契約は触らない。
+
+## 1. 置き場
+
+- `<project>/planning/script.json`（無ければ予定もメモも無い。台本パネルは字幕だけで今までどおり動く）
+- シーンを持つプロジェクト（project-manifest v0）では `scenes/<scene>/planning/script.json`。台本パネルは開いているシーンの 1 本を読む
+
+## 2. 形
+
+```json
+{
+  "version": 0,
+  "kind": "akari-script",
+  "lines": [
+    { "id": "p-hook",  "kind": "plan", "at": 0,  "duration": 3,  "text": "つかみ: 結論を先に言う", "placeholder": "talking-head", "beat": "hook" },
+    { "id": "p-body",  "kind": "plan", "at": 3,  "duration": 40, "text": "本題: 3 つのポイント", "placeholder": "screen", "done": false },
+    { "id": "m-01",    "kind": "memo", "at": 12.5, "text": "ここで図解を差し込む" }
+  ]
+}
+```
+
+- `version`: 整数 0（原則 1）。`kind`: 固定 `"akari-script"`
+- `lines[]`: 必須（空でよい）。各行は `id`（ファイル内で一意）・`kind`（`plan` / `memo`）・`at`（秒・0 以上）・`text`（1〜500 文字）が必須
+- 任意: `duration`（秒・0 より大。予定の区間）/ `placeholder`（作り方の仮枠の `id`）/ `beat`（作り方の内訳の `id`）/ `done`（予定が済んだか）/ `author`（`user` / `ai` / `playbook`）
+- 並び: `at` → `id` の安定ソートで保存。書き込みは tmp + rename。読み手は tolerant（未知フィールドは保持、壊れた行は捨てて残りを読む）
+- スキーマ: `packages/schemas/script.schema.json`（closed object・additive-only）と `validate-script.mjs`
+
+## 3. 台本パネル（右ドックの「台本」）
+
+- 字幕・予定・メモを `at` の順に 1 本の列で出す。行の頭に種類の印（字幕 / 予定 / メモ）。予定は `duration` があれば区間（`0:00–0:03`）を出し、`done` はチェックで切り替える
+- 「＋ メモ」で今の再生位置にメモを足す（`author: user`）。予定・メモの文字はその場で直せる。削除はメニューから
+- 行を押すとその時刻へ移動（字幕の行と同じ）。字幕の既存の操作（字幕を作る・カットを整える・QC）は変えない
+- 表示の切り替え: 「予定とメモを出す」のオン / オフ（既定オン）。オフなら今までの字幕だけの台本
+
+## 4. タイムライン
+
+- タイムラインの最上段に「台本」の段を 1 本足し、予定を区間の帯、メモを点の印で出す（`script.json` が無ければ段を出さない）。押すとその時刻へ移動。ここでは編集しない（直すのは台本パネル）
+
+## 5. 作り方からの生成
+
+- 作り方（playbook.json）の任意項目 `beats[]`（`{ id, at, duration, title, note?, placeholder? }`・秒）を、`applyPlaybook` が
+  予定の行（`kind: plan`・`text` = `title`（`note` があれば「title: note」）・`author: playbook`）として `planning/script.json` に書く。
+  同時に、内訳 1 つ = 空のキャンバス 1 つ（名前 = title・`canvas.intent` = note か title）にして仮枠の段に並べる（`beats` が無いときは従来どおり仮枠ごとに 1 つ）
+- `record-playbook` は、終わったプロジェクトの `planning/script.json` の予定の行（あれば）と章・見出しから `beats` を起こす
+
+## 6. 開けた問い
+
+1. 予定の行を「済」にしたら、対応する空のキャンバスを畳むか（v0 は何もしない）

package/vendor/packages/akari-launcher/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akari-video",
-  "version": "1.5.0-beta.2",
+  "version": "1.5.0-beta.3",
   "description": "AKARI Video launcher CLI — start an AI-edited video project from any directory: scaffold, connection check, then hand over to Claude Code (or opencode). AKARI Video を opencode や Claude Code で、どのディレクトリからでも始めるための `akari` ランチャー CLI。接続確認（doctor）→ 未セットアップならプロジェクト雛形を作成 → AI エージェントを起動する。外部 npm 依存ゼロ（Node.js 組み込みモジュールのみ）。 [akari-video npm vendor: bin/akari.mjs is reference-only. These CLI entrypoints are not included in the akari-video npm package. Use `akari doctor --json` and run the path reported in `render_cut.path`. Full installations provide it in a monorepo checkout, ~/.akari/app, /Applications/AKARI Video.app/Contents/Resources/packages, or %LOCALAPPDATA%\\Programs\\@akari-videoshell\\resources\\packages.]",
   "type": "module",
   "files": [

package/vendor/packages/edit-lint/src/lint/intake.mjs

@@ -1,4 +1,5 @@
 import { readFile } from "node:fs/promises";
+import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { addFinding, isPositiveNumber, isRecord, relativePath } from "./shared.mjs";
 import { t } from "../../../akari-tools/src/decision-log/i18n.mjs";
@@ -152,12 +153,20 @@ export function validateIntake(intake, findings, paths) {
         `${intakeRelative}#submitted_at`,
       );
     }
+    let emptyProject = false;
+    try {
+      const edit = JSON.parse(readFileSync(paths.editPath, "utf8"));
+      const hasMedia = (items) => Array.isArray(items) && items.some(item =>
+        item?.source?.kind === "media" || hasMedia(item?.items));
+      emptyProject = (edit.sources === undefined || (Array.isArray(edit.sources) && edit.sources.length === 0))
+        && !edit.tracks?.some(track => hasMedia(track?.items));
+    } catch { /* If edit.json cannot be read, retain the existing warning. */ }
     intakeFinding(
       findings,
       "intake.status",
       "intake.json is still a draft; the plan is not confirmed yet — settle tasks / target / autonomy with the user (form or conversation) before following it",
       intakeRelative,
-      "warning",
+      emptyProject ? "info" : "warning",
     );
   }
 }

package/vendor/packages/i18n/locales/en/annotations.json

@@ -1029,6 +1029,7 @@
   "annotations.timeline.text.thisTransitionWillNotBeExportedBecauseThere": "This transition will not be exported because there is a gap between it and the next clip.",
   "annotations.timeline.text.thumbnailsAndWaveformsAreNotDisplayedBecauseFfmpeg": "Thumbnails and waveforms are not displayed because ffmpeg is not found (other operations can be used normally)",
   "annotations.timeline.text.timeline": "Timeline",
+  "annotations.timeline.text.script": "Script",
   "annotations.timeline.text.timelineEmptyState": "Timeline empty state",
   "annotations.timeline.text.trackDeleted": "Track deleted.",
   "annotations.timeline.text.trackNameChanged": "Track name changed.",

package/vendor/packages/i18n/locales/en/project.json

@@ -65,6 +65,7 @@
   "project.editCheck.result.checkCountIssuesAction_other": "Check: {count} issues",
   "project.editCheck.result.checkingStatus": "Checking…",
   "project.editCheck.result.checkNoIssuesAction": "Check: No issues",
+  "project.editCheck.result.checkNoIssuesWithInfoAction": "Check: No issues (info {count})",
   "project.editCheck.result.checkNotRunAction": "Check: Not run",
   "project.editCheck.result.editCheckLengthIssuesLabel_one": "[Edit check] {length} issue:\n{value2}",
   "project.editCheck.result.editCheckLengthIssuesLabel_other": "[Edit check] {length} issues:\n{value2}",

package/vendor/packages/i18n/locales/en/transcript.json

@@ -227,6 +227,18 @@
   "transcript.daihon.dock.linesSelectedWithCountLabel_one": "{value1} line selected",
   "transcript.daihon.dock.linesSelectedWithCountLabel_other": "{value1} lines selected",
   "transcript.daihon.editor.add0point5SecPauseLabel": "Add a 0.5 sec pause",
+  "transcript.daihon.scriptLines.caption": "Caption",
+  "transcript.daihon.scriptLines.plan": "Plan",
+  "transcript.daihon.scriptLines.memo": "Memo",
+  "transcript.daihon.scriptLines.addMemo": "+ Memo",
+  "transcript.daihon.scriptLines.addMemoAtPlayhead": "Add a memo at the playhead",
+  "transcript.daihon.scriptLines.newMemo": "New memo",
+  "transcript.daihon.scriptLines.show": "Show plans and memos",
+  "transcript.daihon.scriptLines.checkedShow": "✓ Show plans and memos",
+  "transcript.daihon.scriptLines.done": "Done",
+  "transcript.daihon.scriptLines.actions": "Line actions",
+  "transcript.daihon.scriptLines.edit": "Edit text",
+  "transcript.daihon.scriptLines.delete": "Delete",
   "transcript.daihon.editor.added0point5SecPauseBeforeWithValueNotice": "Added a 0.5 sec pause before “{value1}”.",
   "transcript.daihon.editor.addedMarkAnnotationsTabNotice": "Added a mark to the Annotations tab.",
   "transcript.daihon.editor.addLineBelowLabel": "Add line below",

package/vendor/packages/i18n/locales/ja/annotations.json

@@ -1029,6 +1029,7 @@
   "annotations.timeline.text.thisTransitionWillNotBeExportedBecauseThere": "このトランジションは次のクリップとの間にすき間があるため書き出されません。",
   "annotations.timeline.text.thumbnailsAndWaveformsAreNotDisplayedBecauseFfmpeg": "ffmpeg が見つからないため、サムネイルと波形は表示されません（他の操作は通常どおり使えます）",
   "annotations.timeline.text.timeline": "タイムライン",
+  "annotations.timeline.text.script": "台本",
   "annotations.timeline.text.timelineEmptyState": "タイムライン空状態",
   "annotations.timeline.text.trackDeleted": "トラックを削除しました。",
   "annotations.timeline.text.trackNameChanged": "トラック名を変更しました。",

package/vendor/packages/i18n/locales/ja/project.json

@@ -65,6 +65,7 @@
   "project.editCheck.result.checkCountIssuesAction_other": "チェック: 指摘 {count} 件",
   "project.editCheck.result.checkingStatus": "確認中…",
   "project.editCheck.result.checkNoIssuesAction": "チェック: 問題なし",
+  "project.editCheck.result.checkNoIssuesWithInfoAction": "チェック: 問題なし（情報 {count}）",
   "project.editCheck.result.checkNotRunAction": "チェック: 未実行",
   "project.editCheck.result.editCheckLengthIssuesLabel_one": "【編集内容のチェック】{length} 件の指摘:\n{value2}",
   "project.editCheck.result.editCheckLengthIssuesLabel_other": "【編集内容のチェック】{length} 件の指摘:\n{value2}",

package/vendor/packages/i18n/locales/ja/transcript.json

@@ -227,6 +227,18 @@
   "transcript.daihon.dock.linesSelectedWithCountLabel_one": "{value1} 行を選択中",
   "transcript.daihon.dock.linesSelectedWithCountLabel_other": "{value1} 行を選択中",
   "transcript.daihon.editor.add0point5SecPauseLabel": "0.5 秒の間を追加",
+  "transcript.daihon.scriptLines.caption": "字幕",
+  "transcript.daihon.scriptLines.plan": "予定",
+  "transcript.daihon.scriptLines.memo": "メモ",
+  "transcript.daihon.scriptLines.addMemo": "＋ メモ",
+  "transcript.daihon.scriptLines.addMemoAtPlayhead": "今の再生位置にメモを追加",
+  "transcript.daihon.scriptLines.newMemo": "新しいメモ",
+  "transcript.daihon.scriptLines.show": "予定とメモを出す",
+  "transcript.daihon.scriptLines.checkedShow": "✓ 予定とメモを出す",
+  "transcript.daihon.scriptLines.done": "済",
+  "transcript.daihon.scriptLines.actions": "行の操作",
+  "transcript.daihon.scriptLines.edit": "文字を編集",
+  "transcript.daihon.scriptLines.delete": "削除",
   "transcript.daihon.editor.added0point5SecPauseBeforeWithValueNotice": "「{value1}」の前に 0.5 秒の間を入れました",
   "transcript.daihon.editor.addedMarkAnnotationsTabNotice": "注釈タブにマークを追加しました",
   "transcript.daihon.editor.addLineBelowLabel": "下に行を足す",

package/vendor/packages/project-scaffold/src/index.mjs

@@ -558,6 +558,7 @@ function renderPlaybookSheetHtml(playbook, missingTools) {
     const list = (items) => items.length ? `<ul>${items.map(item => `<li>${escapeHtml(item)}</li>`).join('')}</ul>` : '<p>なし</p>';
     const steps = playbook.steps.map((step, index) => `${index + 1}. ${step.title}${step.checkpoint ? ' ☑ ここで確認' : ''}`);
     const placeholders = (playbook.placeholders ?? []).map(item => `${item.role} / ${item.kind} / 見本 ${item.sample ? `あり (${item.sample.category}/${item.sample.id})` : 'なし'}`);
+    const beats = (playbook.beats ?? []).map(beat => `${beat.at}–${beat.at + beat.duration} 秒 / ${beat.title}${beat.note ? ` / ${beat.note}` : ''}`);
     const parts = (playbook.parts ?? []).map(item => `${item.kind}: ${item.id} / ${item.source} / ${item.license} / Pro ${item.tier === 'pro' ? '要' : item.tier === 'free' ? '不要' : '不明'}`);
     const settings = Object.entries(playbook.settings).map(([key, value]) => `${key}: ${JSON.stringify(value)}`);
     const provenance = playbook.provenance;
@@ -581,6 +582,7 @@ ${REPORT_STYLE}
       ${row('流れ（確認点つき）', list(steps))}
       ${row('設定値の数と主な値', `<p>${settings.length} 件</p>${list(settings)}`)}
       ${row('仮枠（役割・種類・見本の有無）', list(placeholders))}
+      ${playbook.beats?.length ? row('内訳', list(beats)) : ''}
       ${row('使った部品（入手先・ライセンス・Pro 要否）', list(parts))}
       ${row('要る道具（持っていないものを明記）', list((playbook.requires?.tools ?? []).map(tool => `${tool}: ${missingTools.includes(tool) ? '無い' : 'あり'}`)))}
       ${row('ライセンス', escapeHtml(playbook.license))}
@@ -711,26 +713,71 @@ function applySettings(edit, settings) {
     }
 }
 
-function addPlaceholders(edit, placeholders) {
+function addPlaceholders(edit, placeholders, beats) {
     const fps = edit.output.fps;
-    const track = { id: 'playbook-placeholders', lane: 'visual', items: [] };
+    const hasBeats = Array.isArray(beats) && beats.length > 0;
+    const track = { id: 'playbook-placeholders', name: '仮枠（映像）', lane: 'visual', items: [] };
+    const audioTrack = { id: 'playbook-placeholders-audio', name: '仮枠（音）', lane: 'visual', items: [] };
     let at = 0;
+    if (hasBeats) {
+        for (const beat of [...beats].sort((a, b) => a.at - b.at || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))) {
+            const start = Math.round(beat.at * fps);
+            const duration = Math.max(1, Math.round(beat.duration * fps));
+            track.items.push({
+                id: `playbook-${beat.id}`, at: start, duration, name: beat.title,
+                source: { kind: 'group', canvas: { origin: 'plan', durationMode: 'fixed', intent: beat.note || beat.title,
+                    background: { type: 'none' } } }, items: []
+            });
+            at = Math.max(at, start + duration);
+        }
+    } else {
+        for (const placeholder of placeholders) {
+            if (placeholder.kind === 'audio') continue;
+            const duration = Math.max(1, Math.round((placeholder.durationHintSec ?? 5) * fps));
+            // Empty planned canvas items are valid edit-v2 nodes without a media path. A
+            // sample is a catalog reference, never an asset copied into the project.
+            track.items.push({
+                id: `playbook-${placeholder.id}`, at, duration,
+                name: placeholder.sample
+                    ? `${placeholder.role} (${placeholder.sample.category}/${placeholder.sample.id})`
+                    : placeholder.role,
+                source: { kind: 'group', canvas: { origin: 'plan', durationMode: 'fixed', intent: placeholder.role,
+                    background: { type: 'none' } } }, items: []
+            });
+            at += duration;
+        }
+    }
+    if (track.items.length) edit.tracks.push(track);
     for (const placeholder of placeholders) {
-        const duration = Math.max(1, Math.round((placeholder.durationHintSec ?? 5) * fps));
-        // Empty planned canvas items are valid edit-v2 nodes without a media path. A
-        // sample is a catalog reference, never an asset copied into the project.
-        track.items.push({
-            id: `playbook-${placeholder.id}`, at, duration,
+        if (placeholder.kind !== 'audio') continue;
+        const duration = at || Math.max(1, Math.round((placeholder.durationHintSec ?? edit.output.target_duration_sec ?? 5) * fps));
+        audioTrack.items.push({
+            id: `playbook-${placeholder.id}`, at: 0, duration,
             name: placeholder.sample
                 ? `${placeholder.role} (${placeholder.sample.category}/${placeholder.sample.id})`
                 : placeholder.role,
             source: { kind: 'group', canvas: { origin: 'plan', durationMode: 'fixed', intent: placeholder.role,
                 background: { type: 'none' } } }, items: []
         });
-        at += duration;
     }
-    if (track.items.length) edit.tracks.push(track);
-    return placeholders.length;
+    if (audioTrack.items.length) edit.tracks.push(audioTrack);
+    return hasBeats ? beats.length + placeholders.filter(item => item.kind === 'audio').length : placeholders.length;
+}
+
+function mergePlaybookScript(existing, beats) {
+    const lines = (Array.isArray(existing?.lines) ? existing.lines : []).filter(line => line?.author !== 'playbook');
+    const ids = new Set(lines.map(line => line.id));
+    for (const beat of beats) {
+        const base = `p-${beat.id}`;
+        let id = base;
+        for (let suffix = 2; ids.has(id); suffix++) id = `${base}-${suffix}`;
+        ids.add(id);
+        lines.push({ id, kind: 'plan', at: beat.at, duration: beat.duration,
+            text: beat.note ? `${beat.title}: ${beat.note}` : beat.title,
+            ...(beat.placeholder ? { placeholder: beat.placeholder } : {}), beat: beat.id, author: 'playbook' });
+    }
+    lines.sort((a, b) => a.at - b.at || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    return { ...(existing ?? {}), version: 0, kind: 'akari-script', lines };
 }
 
 /** Apply a validated playbook to an already scaffolded project. */
@@ -744,8 +791,17 @@ export async function applyPlaybook({ projectDir, playbookDir, now = new Date(),
     ]);
     const required = ['version', 'kind', 'id', 'name', 'playbookVersion', 'depth', 'category', 'steps', 'settings', 'license', 'provenance'];
     const headings = ['目的とできあがり', '流れ', '設定値', '必要な素材（仮枠）', '使った部品', '要る道具', 'ライセンス', '出どころ'];
+    const beats = playbook.beats;
+    const invalidBeats = beats !== undefined && (!Array.isArray(beats) || new Set(beats.map(beat => beat?.id)).size !== beats.length
+        || beats.some(beat => !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(beat?.id ?? '')
+            || !Number.isFinite(beat.at) || beat.at < 0 || !Number.isFinite(beat.duration) || beat.duration <= 0
+            || typeof beat.title !== 'string' || !beat.title.trim()
+            || (beat.note !== undefined && (typeof beat.note !== 'string' || !beat.note.trim()))
+            || (beat.placeholder !== undefined && typeof beat.placeholder !== 'string')
+            || (beat.note ? `${beat.title}: ${beat.note}` : beat.title).length > 500));
     if (required.some(key => playbook[key] === undefined) || playbook.version !== 0 || playbook.kind !== 'akari-playbook'
         || !Array.isArray(playbook.steps) || !playbook.provenance
+        || invalidBeats
         || (playbook.placeholders ?? []).some(item => ['own', 'site'].includes(item.sample?.source))
         || (playbook.parts ?? []).some(item => ['own', 'site'].includes(item.source))
         || headings.some(heading => !new RegExp(`^## ${heading}$`, 'm').test(markdown))) {
@@ -764,7 +820,14 @@ export async function applyPlaybook({ projectDir, playbookDir, now = new Date(),
     }
     playbook.provenance.appliedFrom = { path: source, playbookVersion: playbook.playbookVersion, appliedAt: now.toISOString() };
     applySettings(edit, playbook.settings);
-    const placeholdersAdded = addPlaceholders(edit, playbook.placeholders ?? []);
+    const activeBeats = playbook.beats?.length ? playbook.beats : undefined;
+    const placeholdersAdded = addPlaceholders(edit, playbook.placeholders ?? [], activeBeats);
+    const scriptPath = path.join(planning, 'script.json');
+    const existingScript = activeBeats ? await fs.readFile(scriptPath, 'utf8').then(JSON.parse).catch(error => {
+        if (error.code === 'ENOENT') return null;
+        throw error;
+    }) : null;
+    const script = activeBeats ? mergePlaybookScript(existingScript, activeBeats) : null;
     const missingTools = [];
     for (const tool of playbook.requires?.tools ?? []) if (!await hasTool(tool)) missingTools.push(tool);
     await fs.mkdir(planning, { recursive: true });
@@ -772,6 +835,7 @@ export async function applyPlaybook({ projectDir, playbookDir, now = new Date(),
     await fs.writeFile(playbookMdPath, markdown, { flag: 'wx' });
     await writeJsonAtomic(playbookJsonPath, playbook);
     await writeJsonAtomic(editPath, edit);
+    if (script) await writeJsonAtomic(scriptPath, script);
     await fs.writeFile(sheetPath, renderReportHtml(null, { playbook, missingTools }), { flag: 'wx' });
     return { playbookJsonPath, playbookMdPath, sheetPath, placeholdersAdded, missingTools };
 }

package/vendor/packages/schemas/playbook.schema.json

@@ -13,6 +13,14 @@
     "playbookVersion": { "type": "integer", "minimum": 1 },
     "depth": { "enum": [1, 2] },
     "category": { "enum": ["film", "short-drama", "mv", "explainer", "product", "vlog", "cm", "education", "clip", "logo"] },
+    "preview": {
+      "type": "object", "additionalProperties": false,
+      "properties": {
+        "cover": { "type": "string" },
+        "frames": { "type": "array", "maxItems": 5, "items": { "type": "string" } }
+      }
+    },
+    "example": { "type": "boolean" },
     "tags": {
       "type": "object", "additionalProperties": false,
       "properties": {
@@ -50,6 +58,18 @@
         "sample": { "$ref": "#/$defs/sample" }
       }
     } },
+    "beats": { "type": "array", "items": {
+      "type": "object", "additionalProperties": false,
+      "required": ["id", "at", "duration", "title"],
+      "properties": {
+        "id": { "$ref": "#/$defs/id" },
+        "at": { "type": "number", "minimum": 0 },
+        "duration": { "type": "number", "exclusiveMinimum": 0 },
+        "title": { "$ref": "#/$defs/text" },
+        "note": { "$ref": "#/$defs/text" },
+        "placeholder": { "$ref": "#/$defs/id" }
+      }
+    } },
     "parts": { "type": "array", "items": {
       "type": "object", "additionalProperties": false,
       "required": ["kind", "id", "source", "license"],

package/vendor/packages/schemas/script.schema.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:akari-video:schema:script:v0",
+  "title": "AKARI Video script lines v0",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "kind", "lines"],
+  "properties": {
+    "version": { "const": 0 },
+    "kind": { "const": "akari-script" },
+    "lines": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "kind", "at", "text"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "kind": { "enum": ["plan", "memo"] },
+          "at": { "type": "number", "minimum": 0 },
+          "text": { "type": "string", "minLength": 1, "maxLength": 500 },
+          "duration": { "type": "number", "exclusiveMinimum": 0 },
+          "placeholder": { "type": "string" },
+          "beat": { "type": "string" },
+          "done": { "type": "boolean" },
+          "author": { "enum": ["user", "ai", "playbook"] }
+        }
+      }
+    }
+  }
+}

package/vendor/packages/schemas/test/validate-playbook.test.mjs

@@ -32,3 +32,29 @@ test('own part fails, unknown skill warns, missing heading fails', async () => {
   assert.match(result.errors.join(' '), /要る道具/);
   assert.match(result.warnings.join(' '), /no-such-skill/);
 });
+test('relative preview paths and example pass', async () => {
+  const value = structuredClone(sample);
+  value.preview = { cover: 'preview/cover.png', frames: ['preview/frames/01.png', 'preview/frames/02.png', 'preview/frames/03.png'] };
+  value.example = true;
+  assert.equal((await validatePlaybook(value, { markdown })).ok, true);
+});
+test('parent traversal in preview fails', async () => {
+  const value = structuredClone(sample);
+  value.preview = { frames: ['../outside.png'] };
+  assert.equal((await validatePlaybook(value, { markdown })).ok, false);
+});
+test('beats accept seconds and warn about an unknown placeholder', async () => {
+  const value = structuredClone(sample);
+  value.beats = [{ id: 'hook', at: 0, duration: 3, title: 'つかみ', placeholder: 'missing' }];
+  const result = await validatePlaybook(value, { markdown: `${markdown}\n## 内訳\n` });
+  assert.equal(result.ok, true, result.errors.join('; '));
+  assert.match(result.warnings.join(' '), /missing/);
+});
+test('beats reject negative starts and nonpositive durations', async () => {
+  const value = structuredClone(sample);
+  value.beats = [{ id: 'hook', at: -1, duration: 0, title: 'つかみ' }];
+  const result = await validatePlaybook(value, { markdown: `${markdown}\n## 内訳\n` });
+  assert.equal(result.ok, false);
+  assert.match(result.errors.join(' '), /beats\/0\/at/);
+  assert.match(result.errors.join(' '), /beats\/0\/duration/);
+});

package/vendor/packages/schemas/test/validate-script.test.mjs

@@ -0,0 +1,29 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { readScript, validateScript } from '../validate-script.mjs';
+
+const sample = { version: 0, kind: 'akari-script', lines: [
+  { id: 'p-hook', kind: 'plan', at: 0, duration: 3, text: 'Hook', placeholder: 'talking-head', beat: 'hook' },
+  { id: 'm-01', kind: 'memo', at: 12.5, text: 'Add diagram' }
+] };
+
+test('valid script passes', () => assert.equal(validateScript(sample).ok, true));
+test('missing required field fails', () => {
+  const value = structuredClone(sample); delete value.lines[0].text;
+  assert.equal(validateScript(value).ok, false);
+});
+test('kind outside vocabulary fails', () => {
+  const value = structuredClone(sample); value.lines[0].kind = 'caption';
+  assert.equal(validateScript(value).ok, false);
+});
+test('tolerant reader skips broken lines and keeps unknown fields', () => {
+  const value = { ...sample, extension: { future: true }, lines: [
+    { id: 'bad', kind: 'memo', at: -1, text: 'bad' },
+    { ...sample.lines[1], extra: 42 }, sample.lines[0],
+    { ...sample.lines[1], text: 'duplicate' }
+  ] };
+  const read = readScript(value);
+  assert.deepEqual(read.lines.map(line => line.id), ['p-hook', 'm-01']);
+  assert.equal(read.lines[1].extra, 42);
+  assert.deepEqual(read.extension, { future: true });
+});

package/vendor/packages/schemas/validate-playbook.mjs

@@ -15,9 +15,25 @@ export async function validatePlaybook(playbook, { markdown, skillsDir = path.re
   if (!checkSchema(playbook)) {
     errors.push(...checkSchema.errors.map(error => `${error.instancePath || '/'} ${error.message}`));
   }
+  for (const previewPath of [playbook?.preview?.cover, ...(Array.isArray(playbook?.preview?.frames) ? playbook.preview.frames : [])]) {
+    if (typeof previewPath !== 'string') continue;
+    if (!previewPath || path.isAbsolute(previewPath) || /^[a-zA-Z]:[\\/]/.test(previewPath)
+      || previewPath.includes('..') || previewPath.startsWith('\\\\')) {
+      errors.push(`preview のパスは playbook.json からの相対パスで、.. を含められません: ${previewPath}`);
+    }
+  }
   for (const [index, item] of (Array.isArray(playbook?.placeholders) ? playbook.placeholders : []).entries()) {
     if (['own', 'site'].includes(item?.sample?.source)) errors.push(`placeholders[${index}].sample に own / site は使えません`);
   }
+  const placeholderIds = new Set((Array.isArray(playbook?.placeholders) ? playbook.placeholders : []).map(item => item?.id));
+  const beatIds = new Set();
+  for (const [index, beat] of (Array.isArray(playbook?.beats) ? playbook.beats : []).entries()) {
+    if (beatIds.has(beat?.id)) errors.push(`beats[${index}].id は重複できません`);
+    beatIds.add(beat?.id);
+    if (beat?.placeholder && !placeholderIds.has(beat.placeholder)) {
+      warnings.push(`beats[${index}].placeholder が見つかりません: ${beat.placeholder}`);
+    }
+  }
   for (const [index, item] of (Array.isArray(playbook?.parts) ? playbook.parts : []).entries()) {
     if (['own', 'site'].includes(item?.source)) errors.push(`parts[${index}] に own / site は使えません`);
   }
@@ -30,6 +46,7 @@ export async function validatePlaybook(playbook, { markdown, skillsDir = path.re
   if (markdown !== undefined) {
     const found = [...markdown.matchAll(/^## (.+?)\s*$/gmu)].map(match => match[1].trim());
     for (const heading of headings) if (!found.includes(heading)) errors.push(`playbook.md に見出しがありません: ${heading}`);
+    if (playbook?.beats && !found.includes('内訳')) errors.push('playbook.md に見出しがありません: 内訳');
   }
   return { ok: errors.length === 0, errors, warnings };
 }

package/vendor/packages/schemas/validate-script.mjs

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import Ajv2020 from 'ajv/dist/2020.js';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const schema = JSON.parse(await fs.readFile(path.join(here, 'script.schema.json'), 'utf8'));
+const check = new Ajv2020({ allErrors: true, strict: false }).compile(schema);
+
+export function validateScript(value) {
+  const errors = [];
+  if (!check(value)) errors.push(...check.errors.map(error => `${error.instancePath || '/'} ${error.message}`));
+  if (Array.isArray(value?.lines)) {
+    const seen = new Set();
+    value.lines.forEach((line, index) => {
+      if (typeof line?.id !== 'string') return;
+      if (seen.has(line.id)) errors.push(`/lines/${index}/id must be unique`);
+      seen.add(line.id);
+    });
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+/** Tolerant reader: unknown fields survive; malformed and duplicate lines are skipped. */
+export function readScript(value) {
+  const source = value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+  const seen = new Set();
+  const lines = (Array.isArray(source.lines) ? source.lines : []).filter(line => {
+    if (!line || typeof line !== 'object' || Array.isArray(line)) return false;
+    if (typeof line.id !== 'string' || !line.id || seen.has(line.id)) return false;
+    if (line.kind !== 'plan' && line.kind !== 'memo') return false;
+    if (typeof line.at !== 'number' || !Number.isFinite(line.at) || line.at < 0) return false;
+    if (typeof line.text !== 'string' || line.text.length < 1 || line.text.length > 500) return false;
+    if (line.duration !== undefined && (typeof line.duration !== 'number' || !Number.isFinite(line.duration) || line.duration <= 0)) return false;
+    if (line.done !== undefined && typeof line.done !== 'boolean') return false;
+    if (line.author !== undefined && !['user', 'ai', 'playbook'].includes(line.author)) return false;
+    if (line.placeholder !== undefined && typeof line.placeholder !== 'string') return false;
+    if (line.beat !== undefined && typeof line.beat !== 'string') return false;
+    seen.add(line.id);
+    return true;
+  }).sort((a, b) => a.at - b.at || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+  return { ...source, version: 0, kind: 'akari-script', lines };
+}
+
+if (process.argv[1] && await fs.realpath(path.resolve(process.argv[1])).catch(() => '') === await fs.realpath(fileURLToPath(import.meta.url))) {
+  if (!process.argv[2]) { console.error('Usage: node packages/schemas/validate-script.mjs <script.json>'); process.exitCode = 2; }
+  else {
+    try {
+      const result = validateScript(JSON.parse(await fs.readFile(process.argv[2], 'utf8')));
+      if (result.ok) console.log(`OK: ${process.argv[2]}`);
+      else { for (const error of result.errors) console.error(`ERROR: ${error}`); process.exitCode = 1; }
+    } catch (error) { console.error(error.message); process.exitCode = 1; }
+  }
+}

package/vendor/skills/record-playbook/SKILL.md

@@ -13,12 +13,13 @@ description: Record a finished AKARI Video project's workflow as planning/playbo
 2. Read `edit.json` through a script, following `docs/guides/edit-json-access.md`. Do not read the entire file into agent context. Never copy source media, source paths, or the original edit into the playbook.
 3. Group sources by their role. Sum the duration hints for sources serving the same role. For `own` and `site` material, write an empty placeholder without a sample. Do not put `own` or `site` items in `parts`.
 4. Ask the person once for `name`, `category`, and `license` only. Use `CC0-1.0` as the proposed license. Do not ask for each step, role, setting, or part. Fill uncertain wording with `要確認` and refine it from observed evidence.
-5. Keep the eight fixed Markdown headings and the JSON schema in sync. For an existing playbook, increment `playbookVersion`. Use atomic writes.
+5. Keep the Markdown headings, including `## 内訳` after `## 必要な素材（仮枠）`, and the JSON schema in sync. For an existing playbook, increment `playbookVersion`. Use atomic writes.
 
 ## Procedure
 
 1. Inspect `decisions.json`, the documents in `planning/`, and report types in `.akari/reports/` for the steps and human checkpoints. If the steps cannot be recovered, use four defaults: place media, confirm script, refine cut, export. Mark uncertain `what` text `要確認`.
 2. Extract starting values from `edit.json`: aspect, fps, target duration, caption style, default transition, and audio roles. Record settings as values to start the next project, not as a copy of every cut.
-3. Examine `edit.json` sources and available `analysis.json` tags or speaker observations to name placeholder roles. Use `.akari/asset-references.json` and `.akari/style-usage.json` to identify reusable parts and licenses. Keep only `builtin`, `lab`, and `ai` parts. Check used skills and recipe `requires` for required tools and skills.
-4. Run `node skills/record-playbook/bin/record-playbook.mjs <project-root> --name <name> --category <category> [--license <license>]` from a repository checkout, or use `.claude/skills/record-playbook/bin/record-playbook.mjs` from a scaffolded project. The helper writes deterministic structure and `要確認` defaults. Refine the step wording and role names in both files where evidence supports better names; preserve role grouping and validate after editing with `node packages/schemas/validate-playbook.mjs <project-root>/planning/playbook.json` when the repository checkout is available.
-5. Summarize the flow, placeholder count, part count, and required tools on one screen.
+3. Examine `edit.json` sources and available `analysis.json` tags or speaker observations to name placeholder roles. Use `.akari/asset-references.json` and `.akari/style-usage.json` to identify reusable parts and licenses. Keep only `builtin`, `lab`, and `ai` parts. Check used skills and recipe `requires` for required tools and skills. Derive `beats` from plan lines in `planning/script.json` when present; otherwise use chapter headings in captions or `planning/plan.md` together with visual cut boundaries. Write the `## 内訳` table in `playbook.md`.
+4. Run `node skills/record-playbook/bin/record-playbook.mjs <project-root> --name <name> --category <category> [--license <license>]` from a repository checkout, or use `.claude/skills/record-playbook/bin/record-playbook.mjs` from a scaffolded project. The helper writes deterministic structure and `要確認` defaults. If a video exists in `exports/`, it uses `ffmpeg` and `ffprobe` from PATH to extract 3–5 representative PNG frames into `planning/playbook-preview/frames/` and records relative paths in `preview.frames`. `AKARI_FFMPEG` and `AKARI_FFPROBE` can override those commands. If no export or tool is available, or extraction fails, the helper warns and the outcome section says to record again after export. It clears old PNG frames before each extraction. You may review and replace frame choices while keeping 3–5 frames, the playbook aspect ratio, and a maximum long edge of 640 px. Refine the step wording and role names in both files where evidence supports better names; preserve role grouping and validate after editing with `node packages/schemas/validate-playbook.mjs <project-root>/planning/playbook.json` when the repository checkout is available.
+5. Show the playbook and preview frames to the person, then run `node skills/record-playbook/bin/record-playbook.mjs <project-root> --install` if they want the reviewed files copied to their local shelf at `~/.akari/playbooks/<id>/`. This standalone install does not record again, so reviewed frame choices survive. The helper changes preview paths to `preview/frames/0N.png` in the shelf copy and replaces an existing copy only when `playbookVersion` is higher.
+6. Summarize the flow, placeholder count, part count, and required tools on one screen.

package/vendor/skills/record-playbook/bin/record-playbook.mjs

@@ -1,12 +1,15 @@
 #!/usr/bin/env node
 import fs from 'node:fs/promises';
 import { createHash } from 'node:crypto';
+import { execFile } from 'node:child_process';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import { promisify } from 'node:util';
 
 const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../..');
 const categories = new Set(['film', 'short-drama', 'mv', 'explainer', 'product', 'vlog', 'cm', 'education', 'clip', 'logo']);
+const execFileAsync = promisify(execFile);
 
 async function readOptional(file, fallback = {}) {
   try { return JSON.parse(await fs.readFile(file, 'utf8')); }
@@ -35,7 +38,7 @@ async function validateOutput(book, markdown) {
     if (book.version !== 0 || book.kind !== 'akari-playbook' || !book.name || !categories.has(book.category)) errors.push('必須項目または category が不正です');
     if (book.placeholders.some(item => ['own', 'site'].includes(item.sample?.source))) errors.push('own / site の見本は使えません');
     if (book.parts.some(item => ['own', 'site'].includes(item.source))) errors.push('own / site の部品は使えません');
-    for (const heading of ['目的とできあがり', '流れ', '設定値', '必要な素材（仮枠）', '使った部品', '要る道具', 'ライセンス', '出どころ']) {
+    for (const heading of ['目的とできあがり', '流れ', '設定値', '必要な素材（仮枠）', ...(book.beats ? ['内訳'] : []), '使った部品', '要る道具', 'ライセンス', '出どころ']) {
       if (!markdown.includes(`## ${heading}`)) errors.push(`見出しがありません: ${heading}`);
     }
     return { ok: errors.length === 0, errors, warnings: [] };
@@ -163,13 +166,208 @@ function settingsFromEdit(edit) {
     ...(Object.keys(gains).length ? { audio: { roles: gains } } : {}) };
 }
 
+function collectBeats(edit, analysis, script, planMarkdown, captions, placeholders) {
+  const fps = edit.output?.fps || 30;
+  const available = new Set(placeholders.map(item => item.id));
+  const visualTracks = asArray(edit.tracks).filter(track => track.lane === 'visual' && track.id !== 'playbook-placeholders-audio');
+  const mainTrack = visualTracks.find(track => track.id === 'playbook-placeholders')
+    ?? visualTracks.reduce((best, track) => {
+      const mediaCount = candidate => asArray(candidate.items).filter(item => item.source?.kind === 'media' && item.source?.src).length;
+      return !best || mediaCount(track) > mediaCount(best) ? track : best;
+    }, null);
+  const visualCuts = asArray(mainTrack?.items).filter(item => Number.isFinite(item.at) && Number.isFinite(item.duration) && item.duration > 0)
+    .sort((a, b) => a.at - b.at || String(a.id).localeCompare(String(b.id)));
+  const end = Math.max(0, ...visualCuts.map(item => (item.at + item.duration) / fps));
+  const plans = asArray(script?.lines).filter(line => line?.kind === 'plan' && Number.isFinite(line.at) && line.at >= 0 && typeof line.text === 'string' && line.text.trim())
+    .sort((a, b) => a.at - b.at || String(a.id).localeCompare(String(b.id)));
+  const used = new Set();
+  const uniqueId = (value) => {
+    const base = slug(value);
+    let candidate = base;
+    for (let n = 2; used.has(candidate); n++) candidate = `${base}-${n}`;
+    used.add(candidate);
+    return candidate;
+  };
+  if (plans.length) return plans.map((line, index) => {
+    const next = plans[index + 1]?.at ?? end;
+    const [titlePart, ...noteParts] = line.text.split(/:\s*/u);
+    const title = titlePart.trim() || line.text.trim();
+    const note = noteParts.join(': ').trim();
+    return { id: uniqueId(line.beat || line.id || title), at: line.at,
+      duration: line.duration > 0 ? line.duration : Math.max(0.01, next - line.at || 5),
+      title, ...(note ? { note } : {}),
+      ...(available.has(line.placeholder) ? { placeholder: line.placeholder } : {}) };
+  });
+
+  const headings = [];
+  for (const match of String(planMarkdown).matchAll(/^#{2,4}\s+(.+)$/gmu)) {
+    const timed = /^(?:(\d+):)?(\d{1,2}):(\d{2})\s*[—–-]?\s*(.+)$/u.exec(match[1].trim());
+    const at = timed ? Number(timed[1] ?? 0) * 3600 + Number(timed[2]) * 60 + Number(timed[3]) : undefined;
+    headings.push({ at, timed: Boolean(timed), title: (timed ? timed[4] : match[1]).trim() });
+  }
+  const captionRows = Array.isArray(captions) ? captions : asArray(captions?.captions);
+  for (const item of captionRows) {
+    const chapterText = /^(?:#{1,4}\s*|第[一二三四五六七八九十0-9]+章\s*)/u.exec(item?.text ?? '');
+    if (!['chapter', 'heading'].includes(item?.kind ?? item?.type) && !chapterText) continue;
+    const at = item.at ?? item.start;
+    const title = (item.title ?? item.text)?.replace(/^(?:#{1,4}\s*)/u, '');
+    if (Number.isFinite(at) && typeof title === 'string' && title.trim()) headings.push({ at, timed: true, title: title.trim() });
+  }
+  for (const [index, heading] of headings.filter(item => !item.timed).entries()) heading.at = visualCuts[index]?.at / fps;
+  headings.sort((a, b) => (a.at ?? Infinity) - (b.at ?? Infinity));
+  const sources = new Map(asArray(edit.sources).map(source => [source.id, source]));
+  const observations = asArray(analysis.sources ?? analysis.assets ?? analysis.observations);
+  const placeholderForCut = cut => {
+    const source = sources.get(cut.source?.src);
+    const role = source ? sourceRole(source, observations) : cut.source?.canvas?.intent;
+    return placeholders.find(item => item.role === role)?.id;
+  };
+  const timedHeadings = headings.filter(heading => heading.timed);
+  if (timedHeadings.length) {
+    const chapters = timedHeadings.filter((heading, index) => index === 0 || heading.at !== timedHeadings[index - 1].at);
+    return chapters.map((heading, index) => {
+      const at = heading.at;
+      const until = chapters[index + 1]?.at ?? Math.max(end, at + 5);
+      const overlapByRole = new Map();
+      for (const cut of visualCuts) {
+        const overlap = Math.max(0, Math.min(until, (cut.at + cut.duration) / fps) - Math.max(at, cut.at / fps));
+        const placeholder = placeholderForCut(cut);
+        if (overlap > 0 && placeholder) overlapByRole.set(placeholder, (overlapByRole.get(placeholder) ?? 0) + overlap);
+      }
+      const placeholder = [...overlapByRole].sort((a, b) => b[1] - a[1])[0]?.[0];
+      return { id: uniqueId(heading.title), at, duration: Math.max(0.01, until - at), title: heading.title,
+        ...(placeholder ? { placeholder } : {}) };
+    });
+  }
+  if (!visualCuts.length) return headings.filter(heading => Number.isFinite(heading.at)).map((heading, index, timed) => ({
+    id: uniqueId(heading.title), at: heading.at,
+    duration: Math.max(0.01, (timed[index + 1]?.at ?? end) - heading.at || 5), title: heading.title }));
+  return visualCuts.map((cut, index) => {
+    const at = cut.at / fps;
+    const heading = headings.find(item => item.at === at);
+    const placeholder = placeholderForCut(cut);
+    const role = placeholders.find(item => item.id === placeholder)?.role;
+    const title = heading?.title || cut.name || role || `カット ${index + 1}`;
+    return { id: uniqueId(cut.id || title), at, duration: cut.duration / fps, title,
+      ...(placeholder ? { placeholder } : {}) };
+  });
+}
+
 function table(rows) { return `| ${rows.map(row => row.map(value => String(value ?? '—').replaceAll('|', '\\|')).join(' | ')).join(' |\n| ')} |`; }
 function renderMarkdown(book) {
   const steps = book.steps.map((step, index) => `${index + 1}. **${step.title}** — ${step.what}${step.checkpoint ? ' ☑ ここで確認' : ''}`).join('\n');
   const settings = table([['キー', '値', '意味'], ['---', '---', '---'], ...Object.entries(book.settings).map(([key, value]) => [key, JSON.stringify(value), '次のプロジェクトの初期値'])]);
   const placeholders = table([['役割', '種類', '尺の目安', '見本'], ['---', '---', '---', '---'], ...asArray(book.placeholders).map(item => [item.role, item.kind, item.durationHintSec ?? '—', item.sample ? `${item.sample.category}/${item.sample.id}` : 'なし'])]);
+  const beats = book.beats?.length
+    ? table([['時刻（秒）', '見出し', 'メモ', '仮枠'], ['---', '---', '---', '---'], ...book.beats.map(item => [`${item.at}–${item.at + item.duration}`, item.title, item.note ?? '—', item.placeholder ?? '—'])])
+    : 'なし';
   const parts = table([['種類', '名前', '入手先', 'ライセンス'], ['---', '---', '---', '---'], ...asArray(book.parts).map(item => [item.kind, item.id, item.source, item.license])]);
-  return `# ${book.name}\n\n${book.category} の作り方。流れと仮枠を再利用できます。\n\n## 目的とできあがり\n\n${book.category}、${book.settings.aspect}、目標 ${book.settings.targetDurationSec} 秒。\n\n## 流れ\n\n${steps}\n\n## 設定値\n\n${settings}\n\n## 必要な素材（仮枠）\n\n${placeholders}\n\n## 使った部品\n\n${parts}\n\n## 要る道具\n\nCLI ${book.requires.cli}。道具: ${book.requires.tools.join('、') || 'なし'}。スキル: ${book.requires.skills.join('、') || 'なし'}。無い道具は別の道具または手作業で補います。\n\n## ライセンス\n\n${book.license}（要確認）。外部由来の素材は見本を付けず仮枠にしました。\n\n## 出どころ\n\n${book.provenance.fromProject} / ${book.provenance.recordedAt} / AKARI ${book.provenance.akariVersion}\n`;
+  return `# ${book.name}\n\n${book.category} の作り方。流れと仮枠を再利用できます。\n\n## 目的とできあがり\n\n${book.category}、${book.settings.aspect}、目標 ${book.settings.targetDurationSec} 秒。${book.preview?.frames?.length ? '' : '\n\n見本のコマはまだ（書き出し後に記録し直す）'}\n\n## 流れ\n\n${steps}\n\n## 設定値\n\n${settings}\n\n## 必要な素材（仮枠）\n\n${placeholders}\n\n## 内訳\n\n${beats}\n\n## 使った部品\n\n${parts}\n\n## 要る道具\n\nCLI ${book.requires.cli}。道具: ${book.requires.tools.join('、') || 'なし'}。スキル: ${book.requires.skills.join('、') || 'なし'}。無い道具は別の道具または手作業で補います。\n\n## ライセンス\n\n${book.license}（要確認）。外部由来の素材は見本を付けず仮枠にしました。\n\n## 出どころ\n\n${book.provenance.fromProject} / ${book.provenance.recordedAt} / AKARI ${book.provenance.akariVersion}\n`;
+}
+
+async function latestExport(project) {
+  const directory = path.join(project, 'exports');
+  let files;
+  try { files = await fs.readdir(directory); }
+  catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+  const videos = await Promise.all(files.filter(file => /\.(mp4|mov|m4v|webm)$/i.test(file)).map(async file => {
+    const fullPath = path.join(directory, file);
+    const stat = await fs.stat(fullPath);
+    return stat.isFile() ? { path: fullPath, modified: stat.mtimeMs } : null;
+  }));
+  return videos.filter(Boolean).sort((a, b) => b.modified - a.modified)[0]?.path ?? null;
+}
+
+function frameTimes(edit, outputDuration) {
+  const fps = edit.output?.fps || 30;
+  const cuts = asArray(edit.tracks).filter(track => track.lane === 'visual')
+    .flatMap(track => asArray(track.items))
+    .filter(item => item.source?.kind === 'media' && Number.isFinite(item.at) && Number.isFinite(item.duration) && item.duration > 0);
+  const editDuration = Math.max(0, ...cuts.map(item => (item.at + item.duration) / fps));
+  const count = Math.min(5, Math.max(3, cuts.length));
+  return Array.from({ length: count }, (_, index) => {
+    const start = outputDuration * index / count;
+    const end = outputDuration * (index + 1) / count;
+    const selected = cuts.map(item => ({ duration: item.duration,
+      midpoint: (item.at + item.duration / 2) / fps * outputDuration / (editDuration || outputDuration) }))
+      .filter(item => item.midpoint >= start && item.midpoint < end)
+      .sort((a, b) => b.duration - a.duration)[0];
+    return Math.min(outputDuration - 0.05, Math.max(0, selected?.midpoint ?? (start + end) / 2));
+  });
+}
+
+async function clearPreviewFrames(directory) {
+  await fs.mkdir(directory, { recursive: true });
+  for (const file of await fs.readdir(directory)) {
+    if (file.toLowerCase().endsWith('.png')) await fs.rm(path.join(directory, file));
+  }
+}
+
+async function createPreview(project, edit) {
+  const video = await latestExport(project);
+  if (!video) return undefined;
+  const ffmpeg = process.env.AKARI_FFMPEG ?? 'ffmpeg';
+  const ffprobe = process.env.AKARI_FFPROBE ?? 'ffprobe';
+  const directory = path.join(project, 'planning', 'playbook-preview', 'frames');
+  await clearPreviewFrames(directory);
+  try {
+    const { stdout } = await execFileAsync(ffprobe, ['-v', 'error', '-show_entries', 'format=duration', '-of', 'default=noprint_wrappers=1:nokey=1', video]);
+    const duration = Number(stdout.trim());
+    if (!Number.isFinite(duration) || duration <= 0) throw new Error(`書き出しの尺を取得できません: ${video}`);
+    const width = edit.output?.width || 1920;
+    const height = edit.output?.height || 1080;
+    const frameWidth = width >= height ? 640 : Math.max(1, Math.round(640 * width / height));
+    const frameHeight = height >= width ? 640 : Math.max(1, Math.round(640 * height / width));
+    const frames = [];
+    for (const [index, at] of frameTimes(edit, duration).entries()) {
+      const filename = `${String(index + 1).padStart(2, '0')}.png`;
+      await execFileAsync(ffmpeg, ['-hide_banner', '-loglevel', 'error', '-y', '-ss', String(at), '-i', video,
+        '-frames:v', '1', '-vf', `scale=${frameWidth}:${frameHeight}:force_original_aspect_ratio=increase,crop=${frameWidth}:${frameHeight}`,
+        path.join(directory, filename)]);
+      frames.push(`playbook-preview/frames/${filename}`);
+    }
+    return { frames };
+  } catch (error) {
+    await clearPreviewFrames(directory);
+    throw error;
+  }
+}
+
+async function installPlaybook(project, book) {
+  const destination = path.join(process.env.AKARI_HOME ?? path.join(os.homedir(), '.akari'), 'playbooks', book.id);
+  const installed = await readOptional(path.join(destination, 'playbook.json'), null);
+  if (installed && installed.playbookVersion >= book.playbookVersion) return false;
+  await fs.mkdir(destination, { recursive: true });
+  await fs.cp(path.join(project, 'planning', 'playbook.md'), path.join(destination, 'playbook.md'));
+  await fs.rm(path.join(destination, 'preview'), { recursive: true, force: true });
+  const shelfBook = structuredClone(book);
+  if (book.preview?.frames?.length) {
+    const frameDirectory = path.join(destination, 'preview', 'frames');
+    await fs.mkdir(frameDirectory, { recursive: true });
+    shelfBook.preview.frames = [];
+    for (const frame of book.preview.frames) {
+      const filename = path.basename(frame);
+      await fs.cp(path.join(project, 'planning', frame), path.join(frameDirectory, filename));
+      shelfBook.preview.frames.push(`preview/frames/${filename}`);
+    }
+  }
+  if (book.preview?.cover) {
+    await fs.mkdir(path.join(destination, 'preview'), { recursive: true });
+    await fs.cp(path.join(project, 'planning', book.preview.cover), path.join(destination, 'preview', 'cover.png'));
+    shelfBook.preview.cover = 'preview/cover.png';
+  }
+  await writeAtomic(path.join(destination, 'playbook.json'), `${JSON.stringify(shelfBook, null, 2)}\n`);
+  return true;
+}
+
+export async function installExistingPlaybook(projectRoot) {
+  const project = path.resolve(projectRoot);
+  const planning = path.join(project, 'planning');
+  const book = JSON.parse(await fs.readFile(path.join(planning, 'playbook.json'), 'utf8'));
+  const markdown = await fs.readFile(path.join(planning, 'playbook.md'), 'utf8');
+  const validation = await validateOutput(book, markdown);
+  if (!validation.ok) throw new Error(`作り方が不正です: ${validation.errors.join('; ')}`);
+  return installPlaybook(project, book);
 }
 
 async function writeAtomic(file, data) {
@@ -191,7 +389,7 @@ async function planningEvidence(project) {
   return docs;
 }
 
-export async function recordPlaybook(projectRoot, { name, category, license = 'CC0-1.0', now = new Date() }) {
+export async function recordPlaybook(projectRoot, { name, category, license = 'CC0-1.0', now = new Date(), install = false }) {
   if (!name || !categories.has(category)) throw new Error('name と category（定義済み語彙）が必要です');
   const project = path.resolve(projectRoot);
   const edit = await readOptional(path.join(project, 'edit.json'));
@@ -202,6 +400,12 @@ export async function recordPlaybook(projectRoot, { name, category, license = 'C
   const prior = await readOptional(path.join(project, 'planning', 'playbook.json'), null);
   const packageJson = await readOptional(path.join(repoRoot, 'packages', 'akari-launcher', 'package.json'));
   const planningDocs = await planningEvidence(project);
+  const script = await readOptional(path.join(project, 'planning', 'script.json'));
+  const captions = await readOptional(path.join(project, 'captions.json'));
+  const planMarkdown = await fs.readFile(path.join(project, 'planning', 'plan.md'), 'utf8').catch(error => {
+    if (error.code === 'ENOENT') return '';
+    throw error;
+  });
   const recordedSteps = planningDocs.flatMap(doc => asArray(doc.steps)).filter(step => step.id && step.title && step.what);
   const steps = recordedSteps.length ? recordedSteps.map(step => ({ id: slug(step.id), title: String(step.title), what: String(step.what),
     ...(step.skill ? { skill: slug(step.skill) } : {}), checkpoint: Boolean(step.checkpoint) })) : defaultSteps(decisions);
@@ -218,6 +422,14 @@ export async function recordPlaybook(projectRoot, { name, category, license = 'C
     license, provenance: { fromProject: path.basename(project), recordedAt: now.toISOString(),
       akariVersion: packageJson.version ?? '0.0.0', recordedBy: 'record-playbook' }
   };
+  const beats = collectBeats(edit, analysis, script, planMarkdown, captions, book.placeholders);
+  if (beats.length) book.beats = beats;
+  try {
+    book.preview = await createPreview(project, edit);
+  } catch (error) {
+    console.warn(`WARN: 見本のコマを作れませんでした: ${error.message}`);
+  }
+  if (!book.preview) delete book.preview;
   const markdown = renderMarkdown(book);
   book.tags.tools = tools;
   const validation = await validateOutput(book, markdown);
@@ -226,6 +438,7 @@ export async function recordPlaybook(projectRoot, { name, category, license = 'C
   await fs.mkdir(planning, { recursive: true });
   await writeAtomic(path.join(planning, 'playbook.json'), `${JSON.stringify(book, null, 2)}\n`);
   await writeAtomic(path.join(planning, 'playbook.md'), markdown);
+  if (install) await installPlaybook(project, book);
   return book;
 }
 
@@ -233,15 +446,22 @@ if (process.argv[1] && await fs.realpath(path.resolve(process.argv[1])).catch(()
   const args = process.argv.slice(2);
   const project = args.shift();
   const options = {};
-  for (let index = 0; index < args.length; index += 2) {
+  for (let index = 0; index < args.length;) {
+    if (args[index] === '--install') { options.install = true; index += 1; continue; }
     if (!['--name', '--category', '--license'].includes(args[index]) || !args[index + 1]) {
-      console.error('使い方: record-playbook.mjs <project-root> --name <name> --category <category> [--license <license>]');
+      console.error('使い方: record-playbook.mjs <project-root> --name <name> --category <category> [--license <license>] [--install]');
       process.exit(2);
     }
     options[args[index].slice(2)] = args[index + 1];
+    index += 2;
   }
   if (!project) { console.error('プロジェクトの場所が必要です'); process.exit(2); }
   try {
+    if (options.install && !options.name && !options.category) {
+      const installed = await installExistingPlaybook(project);
+      console.log(installed ? '作り方を手元の棚へ写しました' : '手元の棚には同じ版か新しい版があります');
+      process.exit(0);
+    }
     const result = await recordPlaybook(project, options);
     console.log(`作り方: ${path.join(path.resolve(project), 'planning', 'playbook.md')} / 流れ ${result.steps.length}、仮枠 ${result.placeholders.length}、部品 ${result.parts.length}、要る道具 ${result.requires.tools.length}`);
   } catch (error) { console.error(error.message); process.exitCode = 1; }

package/vendor/skills/record-playbook/test/record-beats.test.mjs

@@ -0,0 +1,108 @@
+import assert from 'node:assert/strict';
+import { cp, mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import test from 'node:test';
+import { validatePlaybookFiles } from '../../../packages/schemas/validate-playbook.mjs';
+import { recordPlaybook } from '../bin/record-playbook.mjs';
+
+const repo = join(dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+const fixture = join(repo, 'packages', 'project-scaffold', 'test', 'fixtures', 'finished-project-sample');
+
+test('record-playbook prefers planned lines and falls back to cut boundaries and plan headings', async () => {
+  const scratch = await mkdtemp(join(tmpdir(), 'akari-record-beats-'));
+  try {
+    const withScript = join(scratch, 'script');
+    await cp(fixture, withScript, { recursive: true });
+    await mkdir(join(withScript, 'planning'), { recursive: true });
+    await writeFile(join(withScript, 'planning', 'script.json'), JSON.stringify({ version: 0, kind: 'akari-script', lines: [
+      { id: 'm-1', kind: 'memo', at: 1, text: 'メモ' },
+      { id: 'p-intro', kind: 'plan', at: 0, duration: 10, text: '導入: 結論', beat: 'intro' },
+      { id: 'p-body', kind: 'plan', at: 10, duration: 15, text: '本題', beat: 'body' }
+    ] }));
+    const fromScript = await recordPlaybook(withScript, { name: '台本あり', category: 'explainer' });
+    assert.deepEqual(fromScript.beats.map(beat => [beat.id, beat.at, beat.duration, beat.title, beat.note]), [
+      ['intro', 0, 10, '導入', '結論'], ['body', 10, 15, '本題', undefined]
+    ]);
+    assert.match(await readFile(join(withScript, 'planning', 'playbook.md'), 'utf8'), /## 必要な素材（仮枠）[\s\S]*## 内訳[\s\S]*## 使った部品/);
+    assert.equal((await validatePlaybookFiles(join(withScript, 'planning', 'playbook.json'))).ok, true);
+
+    const withoutScript = join(scratch, 'cuts');
+    await cp(fixture, withoutScript, { recursive: true });
+    await mkdir(join(withoutScript, 'planning'), { recursive: true });
+    await writeFile(join(withoutScript, 'planning', 'plan.md'), '## 00:00 導入\n\n## 00:10 本題\n');
+    const fromCuts = await recordPlaybook(withoutScript, { name: 'カットから', category: 'explainer' });
+    assert.deepEqual(fromCuts.beats.map(beat => [beat.at, beat.duration, beat.title]), [
+      [0, 10, '導入'], [10, 15, '本題']
+    ]);
+    assert.equal((await validatePlaybookFiles(join(withoutScript, 'planning', 'playbook.json'))).ok, true);
+  } finally { await rm(scratch, { recursive: true, force: true }); }
+});
+
+test('overlay tracks do not add cut-based beats', async () => {
+  const scratch = await mkdtemp(join(tmpdir(), 'akari-record-overlays-'));
+  try {
+    const project = join(scratch, 'finished');
+    await cp(fixture, project, { recursive: true });
+    const editPath = join(project, 'edit.json');
+    const edit = JSON.parse(await readFile(editPath, 'utf8'));
+    edit.tracks.unshift({ id: 'overlays', lane: 'visual', items: [
+      { id: 'o1', at: 0, duration: 100, source: { kind: 'media', src: 'talk-a' } },
+      { id: 'o2', at: 100, duration: 100, source: { kind: 'group' } },
+      { id: 'o3', at: 200, duration: 100, source: { kind: 'group' } }
+    ] });
+    await writeFile(editPath, JSON.stringify(edit));
+    const book = await recordPlaybook(project, { name: '重ねあり', category: 'explainer' });
+    assert.deepEqual(book.beats.map(beat => [beat.at, beat.duration]), [[0, 10], [10, 15]]);
+  } finally { await rm(scratch, { recursive: true, force: true }); }
+});
+
+test('timed chapter headings combine cuts and use the longest visible role', async () => {
+  const scratch = await mkdtemp(join(tmpdir(), 'akari-record-chapters-'));
+  try {
+    const project = join(scratch, 'finished');
+    await cp(fixture, project, { recursive: true });
+    await mkdir(join(project, 'planning'), { recursive: true });
+    const editPath = join(project, 'edit.json');
+    const edit = JSON.parse(await readFile(editPath, 'utf8'));
+    edit.sources.push({ id: 'screen', path: 'assets/screen.mp4' });
+    edit.tracks.find(track => track.id === 'v1').items = [
+      { id: 'a', at: 0, duration: 150, source: { kind: 'media', src: 'talk-a' } },
+      { id: 'b', at: 150, duration: 150, source: { kind: 'media', src: 'screen' } },
+      { id: 'c', at: 300, duration: 150, source: { kind: 'media', src: 'screen' } },
+      { id: 'd', at: 450, duration: 300, source: { kind: 'media', src: 'talk-b' } }
+    ];
+    await writeFile(editPath, JSON.stringify(edit));
+    const analysisPath = join(project, 'analysis.json');
+    const analysis = JSON.parse(await readFile(analysisPath, 'utf8'));
+    analysis.sources.push({ sourceId: 'screen', role: '画面収録', kind: 'video', source: 'own' });
+    await writeFile(analysisPath, JSON.stringify(analysis));
+    await writeFile(join(project, 'planning', 'plan.md'), '## 00:00 導入\n\n## 00:12 本題\n');
+    const book = await recordPlaybook(project, { name: '章あり', category: 'explainer' });
+    const byRole = new Map(book.placeholders.map(item => [item.role, item.id]));
+    assert.deepEqual(book.beats.map(beat => [beat.at, beat.duration, beat.title, beat.placeholder]), [
+      [0, 12, '導入', byRole.get('画面収録')],
+      [12, 13, '本題', byRole.get('話している本人の寄り')]
+    ]);
+    assert.equal((await validatePlaybookFiles(join(project, 'planning', 'playbook.json'))).ok, true);
+  } finally { await rm(scratch, { recursive: true, force: true }); }
+});
+
+test('record-playbook omits beats when no plan, heading, or visual cut yields one', async () => {
+  const scratch = await mkdtemp(join(tmpdir(), 'akari-record-no-beats-'));
+  try {
+    const project = join(scratch, 'finished');
+    await cp(fixture, project, { recursive: true });
+    const editPath = join(project, 'edit.json');
+    const edit = JSON.parse(await readFile(editPath, 'utf8'));
+    edit.tracks.find(track => track.id === 'v1').items = [];
+    await writeFile(editPath, JSON.stringify(edit));
+    const book = await recordPlaybook(project, { name: '内訳なし', category: 'explainer' });
+    assert.equal(Object.hasOwn(book, 'beats'), false);
+    const saved = JSON.parse(await readFile(join(project, 'planning', 'playbook.json'), 'utf8'));
+    assert.equal(Object.hasOwn(saved, 'beats'), false);
+    assert.match(await readFile(join(project, 'planning', 'playbook.md'), 'utf8'), /## 内訳\n\nなし\n\n## 使った部品/);
+    assert.equal((await validatePlaybookFiles(join(project, 'planning', 'playbook.json'))).ok, true);
+  } finally { await rm(scratch, { recursive: true, force: true }); }
+});