akari-video 0.1.7 → 0.1.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akari-video",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "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

@@ -33,6 +33,9 @@
     "docs/contract-2026-08-05-fx-v0.md",
     "docs/contract-2026-08-11-analysis-vision-tracks-v0.md",
     "docs/contract-2026-08-11-review-session-ui-events.md",
+    "docs/contract-2026-08-12-chat-approval-v0.md",
+    "docs/contract-2026-08-12-color-range-normalization-v0.md",
+    "docs/contract-2026-08-12-region-filter-layer-v0.md",
     "packages/akari-launcher/bin/akari.mjs",
     "packages/akari-launcher/package.json",
     "packages/akari-launcher/README.md",
@@ -51,6 +54,8 @@
     "packages/bake-layer/bin/bake-layer.mjs",
     "packages/bake-layer/package.json",
     "packages/bake-layer/README.md",
+    "packages/chat-bridge/package.json",
+    "packages/chat-bridge/src/telegram.mjs",
     "packages/creator-root/package.json",
     "packages/decision-cards/package.json",
     "packages/decision-cards/README.md",
@@ -158,6 +163,9 @@
     "skills/setup-audio-library/gallery.md",
     "skills/setup-audio-library/SKILL.md",
     "skills/setup-audio-library/store-unlock.md",
+    "skills/setup-chat-approval/setup-token.md",
+    "skills/setup-chat-approval/SKILL.md",
+    "skills/setup-chat-approval/smoke-test.md",
     "skills/setup-library/fetch-and-validate.md",
     "skills/setup-library/SKILL.md",
     "skills/setup-library/starter-pack.md",

package/vendor/docs/contract-2026-08-02-setup-remote-v0.md

@@ -25,7 +25,7 @@ OK / 差し戻しを言う」だけ — その閲覧と素材の受け渡しを
 
 | 論点 | 決定 |
 |---|---|
-| 手段 | **Tailscale**（tailnet 限定）。閲覧 = `tailscale serve` でプレビューサーバーを tailnet 限定 HTTPS 化。素材 = **Taildrop**（共有シートからデバイス直送。クラウド不経由・実用上サイズ無制限・画質劣化なし） |
+| 手段 | **Tailscale**（tailnet 限定）。閲覧 = `tailscale serve` でプレビューサーバーと承認レポートヘルパーを tailnet 限定 HTTPS 化。素材 = **Taildrop**（共有シートからデバイス直送。クラウド不経由・実用上サイズ無制限・画質劣化なし） |
 | 不採用 / 保留 | Cloudflare Tunnel + Access（tailnet 外の人への共有が要件になったときの**別契約**。「公開してからゲートで守る」構造は既定にしない）。Cloudflare Pages（レポートはローカル随時生成のため噛み合わない） |
 | 素材搬送路の優先順位 | **Taildrop（v0 で実装）** → Dropbox カメラアップロード → iCloud 写真 → Google Drive（順次。v0 では選択肢として提示のみ）。Google フォトは対象外（Library API 制限により自動取得不可） |
 | 対応 OS | macOS / Windows 両対応を前提に書く（Tailscale / Taildrop とも両対応。手順の分岐は SKILL.md 側） |
@@ -37,7 +37,17 @@ OK / 差し戻しを言う」だけ — その閲覧と素材の受け渡しを
 2. **導入ガイド — 人間手番の受け渡し**: インストーラーの sudo・GUI ログイン・スマホ側アプリ導入は
    **自動化しない**（macOS の cask は .pkg で sudo 対話必須 — 実測済み）。スキルは
    「ここはあなたの番」を明確に指示 → 完了を doctor で確認 → 次へ進む、を繰り返す構造とする
-3. **serve 設定**: `tailscale serve` でプレビューサーバー（4567）を tailnet 限定 HTTPS URL にする
+3. **serve 設定**: `tailscale serve` で許可リスト（§3）の 2 件を tailnet 限定 HTTPS URL にする。
+   外部から見える口を安定させるため、**外部ポートを固定し内部ポートを写像する**形を既定とする:
+
+   | 外部 | 内部 | 中身 |
+   |---|---|---|
+   | `https://<host>.ts.net/` | 4567 | プレビューサーバー |
+   | `https://<host>.ts.net:8443/` | ヘルパーの動的ポート | 承認レポート + `decisions.json` |
+
+   レポートヘルパーの内部ポートは起動ごとに変わりうるが、外部 URL は固定される（チャットに
+   貼ったリンクが起動のたびに死なない）。パス分岐（`--set-path /report`）はプレフィックス
+   除去の挙動を実測してから選択肢に加える — 未実測の間は既定にしない
 4. **Taildrop 受信設定**: 受信先フォルダを固定し、作業場の `inbox/` へ接続する
    （直接指定できる場合は直接、できない場合は受信箱 → `inbox/` への移送手順を案内）
 5. **疎通確認**: 別デバイスから (a) serve URL が開ける (b) テストファイルを Taildrop 送信して
@@ -47,7 +57,13 @@ OK / 差し戻しを言う」だけ — その閲覧と素材の受け渡しを
 
 - 既定は **tailnet 限定のみ**。公開インターネットへ出す `tailscale funnel` は**既定で使わない・
   提案もしない**。ユーザーが明示的に要求した場合のみ、リスク説明 + 明示承認を経て扱う
-- serve の対象は**プレビューサーバーのみ**。ファイルシステムや他ポートを serve しない
+- serve してよい対象は**次の許可リスト 2 件に限る**（2026-08-12 拡張）:
+  - (a) **プレビューサーバー**（`akari --preview`、既定 4567）
+  - (b) **decision-cards レポートヘルパー**（`packages/decision-cards/report-helper.mjs`。
+    承認レポートの配信と `decisions.json` の read / write / commit を担う。`127.0.0.1` バインド）
+
+  これ以外のポート・アプリ・ファイルシステムは serve しない。許可リストを増やすときは
+  **本契約を改訂してから**行う（スキル側の判断で足さない）
 - secrets を作業場・プロジェクトに書かない（creator-root v1 の原則。Tailscale の認証情報は
   Tailscale 側が管理し、スキルは一切保持しない）
 - スキルが勝手にインストールを完遂しない（§2-2 の人間手番）。ネットワーク設定の変更は
@@ -68,8 +84,9 @@ OK / 差し戻しを言う」だけ — その閲覧と素材の受け渡しを
 
 - **L0**: SKILL.md の体裁・スキル lint が通る
 - **L1**: doctor が 3 状態（未導入 / 未ログイン / 構成済み）を正しく判定する
-- **L2**: 実機スモーク — 別デバイスから serve URL が開ける + Taildrop のテストファイルが
-  `inbox/` に現れる（§2-5 の疎通確認そのもの）
+- **L2**: 実機スモーク — 別デバイスから (a) プレビューの serve URL が開ける
+  (b) 承認レポートを開いて決定を保存 → `decisions.json` が実際に更新される
+  (c) Taildrop のテストファイルが `inbox/` に現れる（§2-5 の疎通確認そのもの）
 
 ## 6. 将来（非スコープの明示）
 
@@ -79,3 +96,45 @@ OK / 差し戻しを言う」だけ — その閲覧と素材の受け渡しを
 - tailnet 外への共有（クライアント・協力者にブラウザだけで見せる）: Cloudflare Tunnel +
   Access（One-time PIN）系の別契約
 - `inbox/` からの自動素材選択規約（直近 N 件）と create-project / analyze-footage への自動接続
+
+## 7. L2 実測記録（2026-08-12・オーナー実機 iPhone + macOS）
+
+**通った項目**:
+
+| 検証 | 結果 |
+|---|---|
+| 別デバイスからのプレビュー閲覧 | ✓ tailnet 経由で表示。体感速度は「十分すぎる」（WireGuard 直結のため） |
+| **レポート内に埋めた動画の再生** | ✓ iOS 実機で再生・**シーク成功**（H.264 640x360 / 6 秒） |
+| Taildrop 着弾 | ✓ 受信先の実パス = **`~/Downloads/`**（macOS GUI 版・実測で確定） |
+| Taildrop の無劣化性 | ✓ 92MB / HEVC / 1180x2556 / 60fps / **15.7Mbps のまま**再エンコードなし |
+| Taildrop → 作業場 `inbox/` | ✓ **移送運用**で接続（`~/Akari/inbox/`）。macOS スタンドアロン版は受信先を設定変更できないため、直接指定ではなく移送を採る（§2-4 の想定どおり） |
+| **承認の往復（`decisions.json`）** | ✓ スマホのタップが Mac のファイルへ書き戻ることを実測。単選カード（`thumbnail`: 既定 → 別候補）・整数スライダ（`direction.intensity`: 50 → 75）・**確定（`completedAt` 記入）** の 3 経路が通過。`byDefault: false` / `answeredAt` も期待どおり更新され、ファイルは `0600` を維持 |
+
+- Taildrop の実測は「チャット添付は搬送路として筋が悪い」（§非スコープの根拠）を裏づけた —
+  同じ 92MB は Telegram Bot API 標準（受信 20MB）では原理的に通らない
+- 受信物が HEVC だった点は、プレビューサーバー側の H.264 自動プロキシ層が実運用で必要になることの実例
+
+**未達の項目（L2 は未クローズ）**:
+
+| 未達 | 状況 |
+|---|---|
+| HTTPS | **`tailscale serve` の TLS が未成立**。上記の実測は tailnet 内の平文 HTTP で代替した（WireGuard 内側のため機密性は保たれるが、secure context を要する機能は使えない）。**平文 HTTP を既定にはしない** |
+
+**HTTPS 失敗の切り分け結果（2026-08-12）** — スキル側・serve 設定側の不備ではないと確定:
+
+- tailnet で HTTPS は有効（`tailscale status --json` の `CertDomains` に当該ドメインあり）
+- serve の設定自体は正常（同じ経路が平文 HTTP では 200 / 0.28 秒で応答する）
+- CAA は発行を許可している（`ts.net` に `issue "letsencrypt.org"`）
+- Let's Encrypt の注文が毎回 `status: invalid`（注文 ID は毎回新規 = レート制限ではなく検証失敗）
+- **`_acme-challenge.<host>.<tailnet>.ts.net` に使い捨て TXT が 5 件累積**していた。
+  DNS-01 の検証失敗と符合する（現行トークンが正しく公開されていない疑い）
+- → **tailnet 側（Tailscale の DNS / 制御プレーン）の問題**。再試行を重ねても TXT が増えるだけで
+  好転しないため、打ち切って次の一手に回す。候補: (a) マシン名を変更して
+  `_acme-challenge` の名前ごと作り直す（serve URL が変わる）(b) Tailscale サポートに問い合わせる
+
+## 8. 改訂履歴
+
+| 日付 | 変更 | 理由 |
+|---|---|---|
+| 2026-08-02 | v0 初版 | — |
+| 2026-08-12 | §3 serve 許可リストを 1 件 → 2 件へ拡張（decision-cards レポートヘルパーを追加）。§2-3 に外部ポート写像を明記。§5 L2 に承認往復の実測を追加 | 元のスコープ（§0「レポートを見て OK / 差し戻しを言う」）は最初から承認を含んでいたが、ハードルールが `serve = プレビューのみ` と狭すぎ、**承認レポートを配信する経路が契約上ふさがっていた**。スコープの拡大ではなくスコープとハードルールの不整合の是正 |

package/vendor/docs/contract-2026-08-11-review-session-ui-events.md

@@ -48,6 +48,7 @@
 | `timeline:cut:<n>` | タイムラインのカット（cuts[] index） | `timeline:cut:3` |
 | `timeline:overlay:<id>` | タイムラインのオーバーレイ | `timeline:overlay:o-0002` |
 | `asset:<path>` | 素材（プロジェクト相対 or カタログ id） | `asset:assets/broll/city.mp4` |
+| `asset:<category>/<id>` | 素材（カタログ由来カード。key = `<category>/<id>`） | `asset:still/br-typing-laptop` |
 
 - **登録機構**: 記録対象の要素は `data-akari-ui="<target-id>"` 属性で opt-in する。
   クリック解決は capture-phase のリスナー 1 本で行い、**最近傍の登録済み祖先**に丸める。
@@ -80,10 +81,21 @@
 - 回帰: 新イベント入りの events.jsonl を旧読み手（compile-review-session の手順）が
   処理してもエラーにならないこと
 
-## 6. 予約（次段の実装契約で確定）
-
-- review.json `annotations[].target` への **`ui:<element-id>`** 追加（選択ツール経由の
-  UI 要素注釈の着地形）。§2 と同一の id 空間を使う
-- 書き出し済み MP4 への注釈は新 target 種を作らず既存 `src` 機構で扱う方針（要検証:
-  プロジェクト外ファイルの src 正規化）
-- 音への注釈（`sourceRange` + トラック指定）の形
+## 6. 注釈の着地契約
+
+- review.json `annotations[].target` の **`ui:<element-id>`** は、選択ツール経由の UI 要素注釈に
+  使う。§2 と同一の id 空間を使い、たとえばオーバーレイは
+  `ui:timeline:overlay:<id>` に着地する
+- render-cut は検証に成功した書き出し成果物を、edit.json v1 の `sources[]` へ自動追記する。
+  `path` はプロジェクトルート相対、`proxy` は `null` とし、同じ `path` が既にあれば追記しない。
+  既存 id と衝突しない出力 stem 由来の id を使い、既存フィールドと整形は書き換えない。
+  edit.json を再読込・パースできない場合は警告だけを残し、書き出し成功を取り消さない。
+  v0 は schema 上 `sources` を持てないため自動追記せず、同様に警告する
+- `sources[].path` に一致する動画ファイルを raw preview で開き、そのタブがフォーカスされて
+  いる間の注釈は、`src = sources[].id` と raw preview の現在再生位置を source 秒とする
+  `sourceT` に着地する。コンポーザーは対象を `🎞 <source id>` チップで表示する。
+  一致しないファイルは従来どおり `src: null` の通常注釈とし、新しい target 種は作らない
+- 音の素材区間は新しい `audio:` target を作らず、`src = sources[].id` と半開区間
+  `sourceRange: [start, end)` を使う。BGM 等のオーバーレイ音は既存の `overlay:<id>` または
+  `ui:timeline:overlay:<id>` で扱う。音声ファイルは専用 audio preview で開かれるため、raw video
+  preview の現在位置接続とは別であり、区間選択 UI は本契約の対象外とする

package/vendor/docs/contract-2026-08-12-chat-approval-v0.md

@@ -0,0 +1,99 @@
+# chat-approval 契約 v0（チャット通知 + ボタン承認）
+
+- 日付: 2026-08-12
+- 状態: **v0 ドラフト・要オーナーレビュー**
+- 前提: `contract-2026-08-02-setup-remote-v0.md`（tailnet 限定の閲覧経路。レポート URL の供給元）、
+  `contract-2026-07-25-project-structure-v0.md`（承認レポートの実体）、
+  `packages/decision-cards/report-helper.mjs`（`decisions.json` の read / write / commit の唯一の実装）、
+  `skills/manage-connections`（接続レジストリと credentials の唯一の入口）
+- スコープ: 承認ゲート到達を**チャットへ通知**し、**ボタンのタップだけで**承認を返せるようにする
+- 非スコープ: チャットからの自由文指示、エージェントの起動・操作、素材のチャット搬送、
+  複数チャネル対応（v0 は Telegram 1 本）
+
+## 0. 位置づけ — 一言で言い切る
+
+**チャットは配管であって頭脳ではない。** 運ぶのは「できました」という通知・レポートへのリンク・
+画像・そして**列挙可能な承認の返事**だけ。編集の判断は従来どおり AKARI のパイプラインが持ち、
+承認の記録は `decisions.json` が持つ。チャット層は SSOT を一切持たない。
+
+## 1. 決定事項
+
+| 論点 | 決定 |
+|---|---|
+| 何を足すか | **通知と承認だけ**。エージェントをチャットから起動しない（別契約） |
+| 書き込み経路 | ブリッジは `decisions.json` を**自分で書かない**。report-helper の HTTP API（`POST /api/state` / `POST /api/commit`）を 127.0.0.1 経由で叩く。書き込みの原子性・検証・`0600`・二重確定の 409 は既存実装のまま効く |
+| 受信方式 | **long polling**（`getUpdates`）。公開エンドポイント・webhook・トンネルを作らない（受信口をインターネットに開けない） |
+| 入力語彙 | **閉じた語彙のみ**。`callback_data` が既定の集合に一致するものだけ処理し、自由文は処理しない |
+| チャネル | Telegram のみ（v0）。実装は `packages/chat-bridge/` に置き、後で LINE / Discord を足せる形にする |
+
+## 2. なぜ自由文を入れないか（この契約の中心）
+
+自由文をエージェントへ通すと、`planning`（非公開）の信頼境界契約が扱う prompt injection の
+窓口がそのまま開く。ボタンの `callback_data` は**発行側が定義した有限集合**であり、
+受信側は集合に無い値を捨てるだけでよい。v0 はこの性質を設計の土台にする。
+
+- 差し戻しは「確定しない + レポートを開くリンクを返す」で表現する。理由の自由記述はレポート側で行う
+- 自由文メッセージを受けたら、処理せず「レポートで操作してください」と定型文を返す
+
+## 3. 安全規律（ハードルール）
+
+1. **トークンを git 管理下・レポート・ログ・会話に出さない。** 置き場は
+   `~/.config/akari-video/credentials.env`（`600`）のみ。エージェントは値を読まず、KEY 名だけ案内する
+2. **チャット ID の許可リストを必須にする。** 登録済み chat ID 以外からの update は
+   一切処理せず破棄する（bot のユーザー名は誰でも到達できるため、これが無いと第三者が承認できる）
+3. **ブリッジはポートを listen しない。** 送信も受信も outbound の long polling のみ
+4. **`decisions.json` を直接書かない**（§1 の決定）。report-helper 経由のみ
+5. **update の重複処理をしない。** `update_id` で冪等化する（Telegram は再配信しうる）
+6. **送ってよいのはレポートの画像とテキストのみ。** 撮影素材の原本・secrets・パスの内部構造を送らない
+7. **疎通確認（実機への通知到達 + ボタンで `decisions.json` 更新）が取れるまで完了と言わない**
+
+## 4. 構成要素
+
+| 要素 | 置き場 | 役割 |
+|---|---|---|
+| ブリッジ本体 | `packages/chat-bridge/telegram.mjs` | 通知送信 + long polling + report-helper API 呼び出し |
+| セットアップスキル | `skills/setup-chat-approval/` | doctor → BotFather 案内（人間手番）→ chat ID 取得 → 疎通確認。`setup-remote` と同じ型 |
+| 接続登録 | `.akari/connections.json` | `manage-connections` の管轄（§5 の判断待ち） |
+
+### 送るメッセージの形
+
+```
+🎬 <プロジェクト名> — 承認をお願いします
+<要約 1〜2 行>
+[キーフレーム画像 数枚]
+
+[ レポートを開く (URL) ] [ おまかせで確定 ] [ あとで ]
+```
+
+- 「レポートを開く」は URL ボタン（tailnet 限定 URL。Telegram のサーバーからは到達できないため
+  リンクプレビューは出ない → `disable_web_page_preview` を付ける）
+- 「おまかせで確定」は全カード既定値のまま `POST /api/commit`（レポート側の `accept-all` と同義）
+- v1 の拡張余地: カードごとに選択肢ボタンを展開する（`data-option` は有限集合なので §2 と両立する）
+
+## 5. 判断待ち — `connections.json` の `kind` 拡張
+
+現行スキーマの `kind` は `genai / image / video / tts / music / sns / analytics` の閉じた enum で、
+**通知系の枠が無い**。`manage-connections` のハードルール 7（レジストリに無い接続を使わない）を
+守るには、いずれかを選ぶ必要がある:
+
+| 案 | 内容 | 評価 |
+|---|---|---|
+| **A. `notify` を enum に追加** | スキーマ + 検証 + 例 + `apps/shell` 側ミラーを更新 | **推奨**。通知は既存のどの kind とも性質が違う（発信ではなく往復）。将来の LINE / Discord も同じ枠に入る |
+| B. 既存の `sns` を流用 | 変更ゼロ | `sns` は「SNS へ投稿する」枠であり、承認の往復とは別物。意味が濁る |
+| C. レジストリに載せない | credentials.env だけで完結 | ハードルール 7 違反。採らない |
+
+## 6. 成果物と受け入れ基準
+
+- **L0**: スキル lint / スキーマ検証 / 既存テストが green
+- **L1**: 決定論の単体テスト — 許可外 chat ID の破棄・未知の `callback_data` の破棄・
+  `update_id` の冪等化・自由文の非処理・トークンが出力に混じらないこと
+- **L2**: 実機 — スマホへ通知が届き、ボタンのタップで `decisions.json` が更新される
+
+## 7. 将来（非スコープの明示）
+
+- カードごとの選択肢ボタン展開（v1）
+- 複数チャネル（LINE / Discord / Slack）
+- チャットからのエージェント起動・自由文指示（信頼境界の別契約が前提。常駐エージェント
+  = Hermes 等の検討もここに属する）
+- 承認待ちのエージェント側の再開機構（現状は人間が「続けて」と言う前提。ファイル待ちの
+  ポーリングを挟む設計は別途）

package/vendor/docs/contract-2026-08-12-color-range-normalization-v0.md

@@ -0,0 +1,59 @@
+# Color range normalization v0
+
+## 1. 背景と目的
+
+full-range（`color_range=pc` / `yuvj420p`）の入力をそのまま H.264 出力へ伝播させると、配信向けの limited range を期待する再生・検証環境で階調とメタデータが一致しない。本契約は Render の全エンコード工程を limited range（FFmpeg の `tv`）へ正規化し、最終成果物と中間生成物の一貫性を保証する。
+
+この不具合の起点と再現条件は [公開 issue #21](https://github.com/AkariLabs/akari-video/issues/21) を参照する。
+
+## 2. 最終出力の保証
+
+MP4 / H.264 の最終映像ストリームは次を満たさなければならない。
+
+- pixel format は `yuv420p`
+- `color_range` は `tv`（limited range）
+
+この組み合わせを AKARI Video の配信標準出力とする。
+
+## 3. 値変換とメタデータの不変条件
+
+色域レンジの正規化は、画素値の変換と映像ストリームへのメタデータのタグ付けを常に対で行う。
+
+- 各 video filter chain は出力直前に `scale=out_range=tv` 相当の値変換を行う。
+- 各 H.264 encode は `-color_range tv` 相当のメタデータを付ける。
+- full-range の画素値を残したまま `tv` タグだけを付けることを禁止する。
+- 値だけを limited range へ変換し、タグ付けを省略することも禁止する。
+
+入力がすでに tv range の場合、`scale=out_range=tv` はレンジ変換について no-op として扱う。
+
+## 4. 工程不変
+
+cut、tail padding、track stack、layers、overlay composite を含む各エンコード工程の出力フレームは常に tv range とする。これは最終成果物だけでなく、後続工程へ渡す中間生成物にも適用する。
+
+複数ソースの cut では、ソースごとの前処理チェーンで tv range へ正規化してから concat / transition へ入力する。これにより pc / tv range が混在したフレームを同じ concat へ直接渡さない。さらに、LUT や合成後の工程出力も終端で tv range に正規化する。
+
+映像を再エンコードしない audio-only mux と、alpha を運ぶ非 H.264 overlay 中間生成物は本契約の対象外とする。
+
+## 5. Probe と provenance
+
+入力ソースの `pix_fmt` と `color_range` を ffprobe の映像ストリームから取得し、既存の duration、audio 有無、width、height、fps と同じ provenance 情報として記録する。ffprobe が入力の `color_range` を報告しない場合は `null` として記録し、推測値で置き換えない。
+
+## 6. Verify 契約
+
+レンダープランの期待値へ `color_range: "tv"` を追加し、official verify は `verify.color-range` を報告する。
+
+- 実測 `color_range` が `pc` の場合は error とする。
+- 実測が `tv` の場合は pass とする。
+- ffprobe が `color_range` を報告しない場合は、H.264 の仕様既定（未指定は limited range）に従って tv とみなし pass とする。
+
+`verify.pixel-format` の期待値 `yuv420p` は維持し、`verify.color-range` と独立に判定する。
+
+## 7. 予約（今回のスコープ外）
+
+次の事項は別契約で扱い、本契約 v0 では実装しない。
+
+- BT.601 から BT.709 などの colorspace 変換
+- `-colorspace` / `-color_primaries` / `-color_trc` による colorspace メタデータの正規化
+- 10bit および HDR 入力の変換、tone mapping、出力形式
+
+本契約の `tv` 正規化は color range のみに限定され、上記の色域・伝達特性変換を暗黙に保証しない。

package/vendor/docs/contract-2026-08-12-region-filter-layer-v0.md

@@ -0,0 +1,98 @@
+# Region filter layer v0
+
+## 1. 背景
+
+finger-frame の中心表現を、別映像の corner-pin 合成だけでなく、指で作った枠の内側だけベース映像自身のルックを切り替える表現へ拡張する。この用途では貼り込み素材を入力せず、ベース映像からフィルター済みの映像を作り、指定 region の内側だけへ戻す。
+
+本書は `edit.json` の additive な拡張である `layers[].kind: "filter"` の v0 契約を定める。
+
+## 2. 意味論
+
+- `kind: "filter"` の layer は `src` を持たない。ベース映像以外の貼り込み入力を追加しない。
+- `filter` は region の内側にだけ適用し、region の外側はベース映像をそのまま保つ。
+- layer の発動時間窓は既存どおり `t` と `duration` で表す。
+- `opacity`、`track`、および `keyframes[].perspective` は既存 layer の共通フィールドを再利用する。
+- `src`、`chroma_key`、`blend`、`crop`、`transform` は `kind: "filter"` では使用できない。
+
+## 3. Region source v0
+
+v0 の region source は `perspective.corners` の quad である。表現、4 隅の順序、値域、退化四角形の制約は既存の `layerPerspective` をそのまま再利用する。`keyframes[].perspective` がある場合は既存の perspective keyframe 展開規約に従い、時間区間ごとの静的 quad として合成する。
+
+## 4. 凍結インターフェース
+
+```jsonc
+{
+  "id": "finger-frame-1",
+  "kind": "filter",
+  "t": 12.0,
+  "duration": 2.4,
+  "filter": { "type": "invert" },
+  // または { "type": "lut", "id": "<presets/luts の id>", "intensity": 1.0 }
+  // または { "type": "saturation", "value": 1.6 }
+  "perspective": { "corners": [[0, 0], [1, 0], [0, 1], [1, 1]] },
+  "keyframes": [
+    {
+      "t": 0.1,
+      "perspective": { "corners": [[0, 0], [1, 0], [0, 1], [1, 1]] }
+    }
+  ],
+  "opacity": 1.0
+}
+```
+
+`filter` は次の closed union とする。
+
+```jsonc
+{
+  "type": "object",
+  "required": ["type"],
+  "oneOf": [
+    {
+      "properties": { "type": { "const": "invert" } },
+      "required": ["type"],
+      "additionalProperties": false
+    },
+    {
+      "properties": {
+        "type": { "const": "lut" },
+        "id": { "type": "string", "minLength": 1, "pattern": "\\S" },
+        "intensity": { "type": "number", "minimum": 0, "maximum": 1 }
+      },
+      "required": ["type", "id"],
+      "additionalProperties": false
+    },
+    {
+      "properties": {
+        "type": { "const": "saturation" },
+        "value": { "type": "number", "minimum": 0, "maximum": 3 }
+      },
+      "required": ["type", "value"],
+      "additionalProperties": false
+    }
+  ]
+}
+```
+
+LUT の `intensity` 省略時は `1` として描画する。
+
+## 5. 予約（今回のスコープ外）
+
+- region source `mask`: ピクセル単位のマットを region として使用する予約。v0 では schema、CLI、renderer のいずれにも実装しない。
+- filter type `"pixelate"`: face-mosaic の将来の移行先として予約する。v0 の closed union には含めず、指定された場合は拒否する。
+
+予約名は現在利用可能であることを意味しない。
+
+## 6. Additive 原則
+
+この契約は既存の `kind: "baked"` / `kind: "video"` に対する additive な拡張である。既存 kind の必須フィールド、合成順、フィルターチェーン、examples / fixtures の妥当性と出力は変更しない。filter layer を含まない既存入力は従来とバイト等価に扱う。
+
+## 7. 実装対応
+
+- `packages/render-cut/src/layers.mjs`: ベース映像の split、ルック適用、白 quad mask、`maskedmerge` による region 内合成を行う。filter layer は追加の `-i` を作らない。
+- `packages/akari-tools/bin/finger-frame.mjs`: `--kind filter --filter invert|lut:<id>|saturation:<value>` から、既存と同じ gesture window と corner keyframes を持つ layer を生成する。
+
+## 8. 検証
+
+L0 では schemas、akari-tools、render-cut の各 `node --test`、docs-sync、既存 baked / video の非回帰を確認する。ffmpeg コマンド生成テストは filter layer が追加 `-i` を作らず、3 種の filter と perspective keyframe 展開が決定論的なグラフを生成することを確認する。
+
+12 秒 window の実素材による invert / LUT の見た目、所要時間、入力数の実測は別途実施し、検証報告へ記録する。

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

@@ -1,6 +1,6 @@
 {
   "name": "akari-video",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "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/packages/analysis-report/render-analysis-report.mjs

@@ -135,6 +135,21 @@ function validateAnalysisStructure(analysis, label) {
     ) {
       errors.push("tracks.person_matte は string か null である必要があります");
     }
+    for (const field of ["face_landmarks", "hand_pose"]) {
+      if (!hasOwn(analysis.tracks, field)) continue;
+      const pointer = analysis.tracks[field];
+      if (!isRecord(pointer) || !isNonEmptyString(pointer.path) || !(Number(pointer.sample_fps) > 0)) {
+        errors.push(`tracks.${field} は path(空でない文字列)・sample_fps(正数) を持つ object である必要があります`);
+        continue;
+      }
+      if (hasOwn(pointer, "features") && (
+        !Array.isArray(pointer.features)
+        || pointer.features.some((feature) => !isNonEmptyString(feature))
+        || new Set(pointer.features).size !== pointer.features.length
+      )) {
+        errors.push(`tracks.${field}.features は重複のない空でない文字列配列である必要があります`);
+      }
+    }
   }
   for (const [index, kf] of (analysis.keyframes || []).entries()) {
     if (!isRecord(kf)) {

package/vendor/packages/chat-bridge/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@akari-video/chat-bridge",
+  "version": "0.0.0",
+  "private": true,
+  "description": "承認ゲートの通知 + ボタン承認ブリッジ v0（Telegram）。decisions.json は report-helper の HTTP API 経由でのみ更新し、ポートは listen しない。外部 npm 依存ゼロ（Node.js 組み込みモジュールのみ）。",
+  "type": "module",
+  "bin": {
+    "akari-chat-bridge": "src/telegram.mjs"
+  },
+  "scripts": {
+    "start": "node src/telegram.mjs",
+    "test": "node --test"
+  }
+}