akari-video 0.1.71 → 0.1.73

package/bin/akari.mjs

@@ -16,6 +16,7 @@ import { runDoctorCommand } from '../src/doctor-command.mjs';
 import { runGenerateCommand } from '../src/generate-command.mjs';
 import { runStoryboardCommand } from '../src/storyboard-command.mjs';
 import { runWorldCommand } from '../src/world-command.mjs';
+import { runSkillsCommand, refreshEntrySkillOnLaunch } from '../src/skills-command.mjs';
 import { resolveRuntimePaths } from '../src/runtime-diagnostics.mjs';
 import { maybeApplyPendingUpdateOnLaunch, resolveInstalledVersionInfo } from '../src/update-check.mjs';
 import { describeCliHelp, describeInstalledVersions } from '../src/messages.mjs';
@@ -38,7 +39,8 @@ async function printVersion() {
 // `--help` は claude/opencode へそのまま転送されてしまっていた — AKARI Video 自身の
 // コマンド一覧が一度も出ない行き止まりだったため新設した）。
 async function printCliHelp() {
-  for (const line of [...describeCliHelp(), '  world                    ワールド地図を検査・生成・プレビュー・停留所移動']) {
+  for (const line of [...describeCliHelp(), '  world                    ワールド地図を検査・生成・プレビュー・停留所移動',
+    '  skills                   入口スキルを配置・削除・確認（install/remove --entry, status --json）']) {
     console.log(line);
   }
   return { exitCode: 0 };
@@ -60,6 +62,7 @@ try {
 } catch (error) {
   console.error(`自動更新の適用確認でエラーが発生しました（続行します）: ${error instanceof Error ? error.message : String(error)}`);
 }
+refreshEntrySkillOnLaunch({ env: process.env });
 
 // `akari update` / `akari init` / `akari new` / `akari narration` / `akari internal` /
 // `akari sounds` / `akari status` / `akari accept` / `akari capability` / `akari store` /
@@ -73,6 +76,7 @@ const invoke = (argv[0] === '--version' || argv[0] === '-v') ? printVersion()
   : argv[0] === 'update' ? runUpdateCommand(argv.slice(1))
   : argv[0] === 'init' ? runInitCommand(argv.slice(1))
   : argv[0] === 'new' ? runNewCommand(argv.slice(1))
+  : argv[0] === 'skills' ? runSkillsCommand(argv.slice(1))
   : argv[0] === 'narration' ? runNarrationCommand(argv.slice(1))
   : argv[0] === 'internal' ? runInternalCommand(argv.slice(1))
   : argv[0] === 'sounds' ? runSoundsCommand(argv.slice(1))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akari-video",
-  "version": "0.1.71",
+  "version": "0.1.73",
   "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/src/skills-command.mjs

@@ -0,0 +1,160 @@
+import { cpSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '../../..');
+export const ENTRY_VERSION_FILE = '.akari-entry-version';
+const usage = `使い方: akari skills install --entry [--target <dir>]...
+        akari skills remove --entry [--target <dir>]...
+        akari skills status --json
+--target は入口スキル自体の配置先（例: ~/.codex/skills/akari）。既定の 2 か所に追加する。`;
+
+function stat(path) {
+  try { return lstatSync(path); } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+function canonicalBase(path) {
+  return stat(path) ? realpathSync(path) : resolve(path);
+}
+
+export function entryTargets(env = process.env, extra = []) {
+  const home = canonicalBase(env.HOME || homedir());
+  return [...new Set([
+    join(home, '.claude', 'skills', 'akari'),
+    join(home, '.agents', 'skills', 'akari'),
+    ...extra.map(path => resolve(path)),
+  ])];
+}
+
+export function resolveEntrySource({ env = process.env, repoRoot = REPO_ROOT } = {}) {
+  const home = env.HOME || homedir();
+  for (const root of [join(env.AKARI_HOME || join(home, '.akari'), 'app'), repoRoot]) {
+    const source = join(root, 'skills', 'akari');
+    if (!stat(join(source, 'SKILL.md'))?.isFile()) continue;
+    const version = JSON.parse(readFileSync(join(root, 'packages', 'akari-launcher', 'package.json'), 'utf8')).version;
+    if (typeof version !== 'string' || !version.trim()) throw new Error(`ランチャー版が不正です: ${root}`);
+    return { source, version };
+  }
+  throw new Error('入口スキル skills/akari/SKILL.md が見つかりません。');
+}
+
+// ディレクトリだけでなく配下の SKILL.md / 版印、親の skills がリンクの場合も触らない。
+function hasLinkedAncestor(path) {
+  for (let current = path; ; current = dirname(current)) {
+    if (stat(current)?.isSymbolicLink()) return true;
+    if (dirname(current) === current) return false;
+  }
+}
+
+function hasLinkedContent(path) {
+  const info = stat(path);
+  if (!info) return false;
+  if (info.isSymbolicLink()) return true;
+  return info.isDirectory() && readdirSync(path).some(name => hasLinkedContent(join(path, name)));
+}
+
+function inspectTarget(path, currentVersion) {
+  const info = stat(path);
+  const symlink = hasLinkedAncestor(path);
+  const marker = join(path, ENTRY_VERSION_FILE);
+  const managed = !symlink && info?.isDirectory() === true && stat(marker)?.isFile() === true;
+  const version = managed ? readFileSync(marker, 'utf8').trim() : null;
+  return { path, exists: info !== null, managed, symlink, version, stale: managed && version !== currentVersion };
+}
+
+export function entryStatus(options = {}) {
+  const { version } = resolveEntrySource(options);
+  return { version, targets: entryTargets(options.env).map(path => inspectTarget(path, version)) };
+}
+
+function installTarget(path, source, version, warn) {
+  if (hasLinkedAncestor(path) || hasLinkedContent(path) || hasLinkedContent(source)) {
+    warn(`symlink は変更しません: ${path}`);
+    return false;
+  }
+  const state = inspectTarget(path, version);
+  if (state.exists && !state.managed) {
+    warn(`入口スキルの版印がないため変更しません: ${path}`);
+    return false;
+  }
+  mkdirSync(path, { recursive: true });
+  cpSync(source, path, {
+    recursive: true,
+    filter: entry => {
+      const relativePath = relative(source, entry);
+      if (!relativePath) return true;
+      const parts = relativePath.split(sep);
+      return parts[0] !== 'test' && !parts.some(part => part.startsWith('.'));
+    },
+  });
+  // コピーに失敗した場合は旧版印を維持して次の起動で再試行する。
+  writeFileSync(join(path, ENTRY_VERSION_FILE), `${version}\n`);
+  return true;
+}
+
+/** 明示 install 済みの既定先だけを更新する。起動を止めず、出力もしない。 */
+export function refreshEntrySkillOnLaunch(options = {}) {
+  try {
+    const paths = entryTargets(options.env);
+    if (!paths.some(path => inspectTarget(path, null).managed)) return;
+    const { source, version } = resolveEntrySource(options);
+    for (const path of paths) {
+      try {
+        if (inspectTarget(path, version).stale) installTarget(path, source, version, () => {});
+      } catch { /* 次回起動で再試行 */ }
+    }
+  } catch { /* 入口の更新失敗で他のコマンドを止めない */ }
+}
+
+export async function runSkillsCommand(args, options = {}) {
+  const log = options.log ?? console.log;
+  const warn = options.logError ?? console.error;
+  if (args.includes('--help') || args.includes('-h')) {
+    log(usage);
+    return { exitCode: 0 };
+  }
+  try {
+    const [command, ...flags] = args;
+    const extra = [];
+    let entry = false;
+    let json = false;
+    for (let i = 0; i < flags.length; i++) {
+      if (flags[i] === '--entry') entry = true;
+      else if (flags[i] === '--json') json = true;
+      else if (flags[i] === '--target' && flags[i + 1] && !flags[i + 1].startsWith('-')) extra.push(flags[++i]);
+      else throw new Error(usage);
+    }
+    if (command === 'status' && json && !entry && !extra.length) {
+      log(JSON.stringify(entryStatus(options), null, 2));
+      return { exitCode: 0 };
+    }
+    if (!['install', 'remove'].includes(command) || !entry || json) throw new Error(usage);
+    const paths = entryTargets(options.env, extra);
+    const source = command === 'install' ? resolveEntrySource(options) : null;
+    let skipped = false;
+    for (const path of paths) {
+      if (command === 'install') {
+        if (installTarget(path, source.source, source.version, warn)) log(`入口スキルを配置しました: ${path}`);
+        else skipped = true;
+      } else {
+        if (!stat(path)) continue;
+        const state = inspectTarget(path, null);
+        if (!state.managed || hasLinkedContent(path)) {
+          warn(`版印がない、または symlink のため削除しません: ${path}`);
+          skipped = true;
+          continue;
+        }
+        rmSync(path, { recursive: true });
+        log(`入口スキルを削除しました: ${path}`);
+      }
+    }
+    return { exitCode: skipped ? 1 : 0 };
+  } catch (error) {
+    warn(error instanceof Error ? error.message : String(error));
+    return { exitCode: 1 };
+  }
+}

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

@@ -119,6 +119,7 @@
     "packages/schemas/package.json",
     "packages/word-book/package.json",
     "skills/address-review/SKILL.md",
+    "skills/akari/SKILL.md",
     "skills/analyze-footage/analysis-json.md",
     "skills/analyze-footage/bin/face-expression/vendor/tasks-vision-0.10.17/README-AKARI.md",
     "skills/analyze-footage/events-and-hooks.md",

package/vendor/docs/contract-2026-07-25-r6-audio-tracks-and-trim.md

@@ -1,114 +1,123 @@
-# R6 契約 — タイムライン配置原則・音源複数トラック化・音源トリム・ソーストリマー
-
-- 日付: 2026-07-25
-- 状態: draft（裁定は確定。実装と並走で approved 化）。本書は技術仕様のみ。
-  判断経緯・実装レーンの運用は非公開の内部記録で管理する（本リポには置かない方針）
-- 前提: `contract-2026-07-14-edit-json-v1-audio.md`（audio スキーマ正本）、
-  `contract-2026-07-17-data-contract-versioning.md`（三原則）
-
-## 1. 確定事項（2026-07-25 裁定）
-
-1. **タイムライン配置原則 = Premiere 型を正式採用**:
-   - 音源グループは**最下段固定**（並べ替え不可）
-   - cuts 帯（Video）はその上の縦中心。上に layers / captions（重ね物）
-   - 映像系トラック内の縦順は従来どおり**上の行ほど前面**（z 順裁定は不変）
-   - ルーラー（メモリ）位置は現状のまま固定
-   - 既定スタック（下から audio→cuts→layers→captions）と整合。本裁定はこれを
-     「固定の配置原則」として明文化するもの
-2. **音源の重なり解消 = 複数音声トラック化**:
-   - sfx の `track` フィールド（schema 既存）を UI で解放し、音声もトラックを増やせるようにする
-   - 従来の「audio は当面 ref 0 固定（単一トラック）」運用を本裁定で変更
-   - `timelineTrack` は kind:'audio' の複数宣言を既に許容（schema 変更不要）。
-     音声トラック群は配置原則 1 により常に最下段グループ内で増減する
-3. **ソーストリマーの入口 = タイムラインのクリップ dblclick**:
-   - クリップをダブルクリック → カット外部分を薄く表示し、左右スライドで in/out 調整
-   - 素材ファイルの dblclick = 素のソース再生、とは両立（入口が別）
-
-## 2. 音源トリム（schema 拡張）
-
-### schema
-
-- `sfxItem` に optional `in` / `out` を追加（**素材秒**。`in` ≥ 0 省略時 0、
-  `out` > `in` 省略時 素材末尾）。再生区間 = 素材の [in, out)、
-  タイムライン上の開始は従来どおり `t`（timeline 秒）、表示尺 = out − in
-- `narrationItem` にも同じ optional `in` / `out` を追加する。再生区間・素材秒・既定値・
-  `out > in` の検証分担は sfx と同一で、タイムライン上の開始は narration の `t` とする
-- `bgm` に optional `in` を追加（BGM ファイル内の開始オフセット素材秒。ループ・全体尺
-  トリムの既存意味論は不変）
-- edit-lint: `out <= in` を error。実尺越えの検知は lint では行わない
-  （lint は ffprobe を持たない — クランプは消費側の責務）
-- cuts 側の語彙に倣い、$comment に意味論を明記する
-
-### 消費（render-cut + preview）
-
-- render-cut: sfx の [in, out) 切り出しを出力に反映。bgm の `in` オフセット反映
-- render-cut: narration の [in, out) 切り出しも出力に反映する。`in` が素材実尺以上なら 0 へ、
-  `out` が素材実尺を超えれば素材末尾へクランプして warning を出す。クランプ後に `out <= in` なら
-  その narration 要素だけを skip する。`in` / `out` の有無にかかわらず、各 narration 要素は
-  デコード可否の判定を兼ねて実尺を従来と同じ 1 回だけ probe し、デコードできなければ従来どおり
-  その要素だけを skip して warning を出す一方、両方省略された要素には `atrim` を前置きせず、
-  従来とバイト同一のフィルタ文字列を保つ
-- preview（previewAudio）: 同意味論で再生。実尺越え in/out は素材末尾へクランプ
-
-### UI
-
-- 音源バーの端ドラッグでトリム（in/out 書き戻し）。動画クリップのトリムと同じ操作感
-- 複数音声トラック行の表示・追加・アイテムのトラック間移動（裁定 2）
-- 配置原則（裁定 1）の実装: audio グループ最下段固定・cuts 縦中心・上に重ね物。ルーラー無移動
-
-## 3. ソーストリマー
-
-- 入口: クリップ dblclick（裁定 3）。トリマーモード中はカット外を薄く表示し、
-  左右スライドで in/out を調整。解除は Esc / 再 dblclick / 他クリップ選択
-- サムネイルは素材全体のフィルムストリップを 1 回だけ焼き、窓移動は CSS
-  background-position のみで行う（トリム / スリップ操作で再焼成しない設計）
-
-## 4. 受け入れの軸
-
-- schema: schemas / edit-lint テスト全数 green
-- 消費: in/out 付き sfx の出力音声を ffprobe / 波形で実測（切り出し位置・尺一致）。
-  preview 側も同 fixture で聴感 + 実測。クランプ動作の実測
-- UI: 実機で (a) 配置原則どおりの表示 (b) 音声トラック追加とアイテム移動が edit.json に
-  書き戻る (c) 音源バー端ドラッグで in/out 書き戻り・リロード後保持 (d) トリマーの
-  表示・調整が機能 (e) 既存トラック UI・z 順の無退行
-
-## 5. §2 追記 — sfx フェード（audio-clip-fades, 2026-08-18・オーナー裁定「クリップ主義」T2）
-
-BGM をクリップ化する裁定（内部リポ `akari-video-internal` の該当タスク）に伴い、
-「音楽をクリップ（audio.sfx[]）として置いても BGM ベッドと同じフェード表現ができる」を
-満たすため、`sfxItem` に optional の `fade_in` / `fade_out`（秒・0 以上）を追加のみ拡張する
-（`version` 不変・`contract-2026-07-17-data-contract-versioning.md` の原則に従う）。
-
-### schema
-
-- `sfxItem.fade_in` / `fade_out`: 秒・省略時 0（フェードなし）。`audio.bgm.fadeIn` /
-  `fadeOut`（camelCase）とは異なり **snake_case**（既存の `gain_db` と同じ命名系列）
-- フェード対象はこのクリップの実効再生窓 `[t, t + 実効尺)`。実効尺は §2 の `[in, out)` が
-  既知なら `out − in`、`in`/`out` 省略時は素材尺（消費側が実尺を解決できた場合のみ）
-- クランプ規則は `audio.bgm.fadeIn`/`fadeOut` と同型: `fade_in`/`fade_out` それぞれ独立に
-  実効尺の半分までクランプ（render-cut が実装、edit-lint は `in`/`out` が両方既知のときだけ
-  警告できる — lint は ffprobe を持たないため実尺越えの検知は消費側の責務、という §2 本文の
-  既存原則をフェードにもそのまま適用）
-
-### 消費（render-cut + preview 3 面）
-
-- render-cut: sfx の afade を volume の直後・adelay の直前に挿入する（adelay 後だと
-  `st=0` が delay 由来の無音区間を指してしまうため）。`in`/`out` 併用時は atrim/asetpts で
-  尺をリセットした後の実効尺基準で afade を計算する
-- シェルプレビュー（akari-preview）: sfx は 1 回きりの `BufferSourceNode` 再生のため、
-  bgm の毎 tick 再計算（fadeMultiplier）ではなく、schedule 時点で
-  `gain.gain.setValueAtTime`/`linearRampToValueAtTime` によるブレークポイント列を組む
-  （`sfxFadeGainSchedule`、シーク再開時は経過秒からブレークポイントを再構成）
-- Web UI（preview-server）: bgm と同じ毎 tick 再計算方式。ただしこの層は現状 sfx の
-  `in`/`out` トリム自体を未実装のため、フェードの実効尺は常にデコード済み素材全長を使う
-  （トリム実装時に合わせて見直す）
-
-### インスペクター
-
-- akari-annotations: sfx 選択時に bgm と同じ「フェード」タブ（`fadeIn`/`fadeOut` ノブ）を出す。
-  ducking は bgm 概念のため sfx には出さない
-- 正本は `packages/edit-store`（edit.json テキスト手術）だが、本追記の実装レーン
-  （task 2026-08-18-audio-clip-fades）のファイル境界が `packages/edit-store` を含まないため、
-  書き戻りは `apps/shell/extensions/akari-annotations/src/common/sfx-fade-store.ts` に
-  境界内で完結する独立実装として置いた（`updateArrayElementByIndex` 等 edit-store の
-  export 済みユーティリティは再利用）。将来 edit-store 側の担当タスクが正本へ統合してよい
+# R6 契約 — タイムライン配置原則・音源複数トラック化・音源トリム・ソーストリマー
+
+- 日付: 2026-07-25
+- 状態: draft（裁定は確定。実装と並走で approved 化）。本書は技術仕様のみ。
+  判断経緯・実装レーンの運用は非公開の内部記録で管理する（本リポには置かない方針）
+- 前提: `contract-2026-07-14-edit-json-v1-audio.md`（audio スキーマ正本）、
+  `contract-2026-07-17-data-contract-versioning.md`（三原則）
+
+## 1. 確定事項（2026-07-25 裁定）
+
+1. **タイムライン配置原則 = Premiere 型を正式採用**:
+   - 音源グループは**最下段固定**（並べ替え不可）
+   - cuts 帯（Video）はその上の縦中心。上に layers / captions（重ね物）
+   - 映像系トラック内の縦順は従来どおり**上の行ほど前面**（z 順裁定は不変）
+   - ルーラー（メモリ）位置は現状のまま固定
+   - 既定スタック（下から audio→cuts→layers→captions）と整合。本裁定はこれを
+     「固定の配置原則」として明文化するもの
+2. **音源の重なり解消 = 複数音声トラック化**:
+   - sfx の `track` フィールド（schema 既存）を UI で解放し、音声もトラックを増やせるようにする
+   - 従来の「audio は当面 ref 0 固定（単一トラック）」運用を本裁定で変更
+   - `timelineTrack` は kind:'audio' の複数宣言を既に許容（schema 変更不要）。
+     音声トラック群は配置原則 1 により常に最下段グループ内で増減する
+3. **ソーストリマーの入口 = タイムラインのクリップ dblclick**:
+   - クリップをダブルクリック → カット外部分を薄く表示し、左右スライドで in/out 調整
+   - 素材ファイルの dblclick = 素のソース再生、とは両立（入口が別）
+
+## 2. 音源トリム（schema 拡張）
+
+### schema
+
+- `sfxItem` に optional `in` / `out` を追加（**素材秒**。`in` ≥ 0 省略時 0、
+  `out` > `in` 省略時 素材末尾）。再生区間 = 素材の [in, out)、
+  タイムライン上の開始は従来どおり `t`（timeline 秒）、表示尺 = out − in
+- `narrationItem` にも同じ optional `in` / `out` を追加する。再生区間・素材秒・既定値・
+  `out > in` の検証分担は sfx と同一で、タイムライン上の開始は narration の `t` とする
+- `bgm` に optional `in` を追加（BGM ファイル内の開始オフセット素材秒。ループ・全体尺
+  トリムの既存意味論は不変）
+- edit-lint: `out <= in` を error。実尺越えの検知は lint では行わない
+  （lint は ffprobe を持たない — クランプは消費側の責務）
+- cuts 側の語彙に倣い、$comment に意味論を明記する
+
+### 消費（render-cut + preview）
+
+- render-cut: sfx の [in, out) 切り出しを出力に反映。bgm の `in` オフセット反映
+- render-cut: narration の [in, out) 切り出しも出力に反映する。`in` が素材実尺以上なら 0 へ、
+  `out` が素材実尺を超えれば素材末尾へクランプして warning を出す。クランプ後に `out <= in` なら
+  その narration 要素だけを skip する。`in` / `out` の有無にかかわらず、各 narration 要素は
+  デコード可否の判定を兼ねて実尺を従来と同じ 1 回だけ probe し、デコードできなければ従来どおり
+  その要素だけを skip して warning を出す一方、両方省略された要素には `atrim` を前置きせず、
+  従来とバイト同一のフィルタ文字列を保つ
+- preview（previewAudio）: 同意味論で再生。実尺越え in/out は素材末尾へクランプ
+
+### UI
+
+- 音源バーの端ドラッグでトリム（in/out 書き戻し）。動画クリップのトリムと同じ操作感
+- 複数音声トラック行の表示・追加・アイテムのトラック間移動（裁定 2）
+- 配置原則（裁定 1）の実装: audio グループ最下段固定・cuts 縦中心・上に重ね物。ルーラー無移動
+
+## 3. ソーストリマー
+
+- 入口: クリップ dblclick（裁定 3）。トリマーモード中はカット外を薄く表示し、
+  左右スライドで in/out を調整。解除は Esc / 再 dblclick / 他クリップ選択
+- サムネイルは素材全体のフィルムストリップを 1 回だけ焼き、窓移動は CSS
+  background-position のみで行う（トリム / スリップ操作で再焼成しない設計）
+
+## 4. 受け入れの軸
+
+- schema: schemas / edit-lint テスト全数 green
+- 消費: in/out 付き sfx の出力音声を ffprobe / 波形で実測（切り出し位置・尺一致）。
+  preview 側も同 fixture で聴感 + 実測。クランプ動作の実測
+- UI: 実機で (a) 配置原則どおりの表示 (b) 音声トラック追加とアイテム移動が edit.json に
+  書き戻る (c) 音源バー端ドラッグで in/out 書き戻り・リロード後保持 (d) トリマーの
+  表示・調整が機能 (e) 既存トラック UI・z 順の無退行
+
+## 5. §2 追記 — sfx フェード（audio-clip-fades, 2026-08-18・オーナー裁定「クリップ主義」T2）
+
+BGM をクリップ化する裁定（内部リポ `akari-video-internal` の該当タスク）に伴い、
+「音楽をクリップ（audio.sfx[]）として置いても BGM ベッドと同じフェード表現ができる」を
+満たすため、`sfxItem` に optional の `fade_in` / `fade_out`（秒・0 以上）を追加のみ拡張する
+（`version` 不変・`contract-2026-07-17-data-contract-versioning.md` の原則に従う）。
+
+### schema
+
+- `sfxItem.fade_in` / `fade_out`: 秒・省略時 0（フェードなし）。`audio.bgm.fadeIn` /
+  `fadeOut`（camelCase）とは異なり **snake_case**（既存の `gain_db` と同じ命名系列）
+- フェード対象はこのクリップの実効再生窓 `[t, t + 実効尺)`。実効尺は §2 の `[in, out)` が
+  既知なら `out − in`、`in`/`out` 省略時は素材尺（消費側が実尺を解決できた場合のみ）
+- クランプ規則は `audio.bgm.fadeIn`/`fadeOut` と同型: `fade_in`/`fade_out` それぞれ独立に
+  実効尺の半分までクランプ（render-cut が実装、edit-lint は `in`/`out` が両方既知のときだけ
+  警告できる — lint は ffprobe を持たないため実尺越えの検知は消費側の責務、という §2 本文の
+  既存原則をフェードにもそのまま適用）
+
+### 消費（render-cut + preview 3 面）
+
+- render-cut: sfx の afade を volume の直後・adelay の直前に挿入する（adelay 後だと
+  `st=0` が delay 由来の無音区間を指してしまうため）。`in`/`out` 併用時は atrim/asetpts で
+  尺をリセットした後の実効尺基準で afade を計算する
+- シェルプレビュー（akari-preview）: sfx は 1 回きりの `BufferSourceNode` 再生のため、
+  bgm の毎 tick 再計算（fadeMultiplier）ではなく、schedule 時点で
+  `gain.gain.setValueAtTime`/`linearRampToValueAtTime` によるブレークポイント列を組む
+  （`sfxFadeGainSchedule`、シーク再開時は経過秒からブレークポイントを再構成）
+- 同・会話音声（narration / 音声レーンの `role:'speech'`）: 2026-09-18 追記。上と同じ
+  ブレークポイント列の仕組みに乗せる（`buildWebAudioSchedule` は kind に依らず
+  `fadeGainEvents` を通す）。**窓の取り方だけが sfx と非対称**で、sfx は item の実効尺を
+  そのまま使う一方、narration は `min(track.durationSec, max(0, duration − track.t))` と
+  タイムライン末尾で切る。これは `render-cut/src/plan.mjs` の実際の扱いに合わせたもので、
+  揃えると sfx が書き出しと食い違う。クランプ規則（実効尺の半分まで独立に）は共通
+- なお cuts / layers の撮影素材音声（プレビューの kind `'speech'`）は宣言にフェード項目を
+  持たず、書き出し側も cut 音声に afade を掛けない。ここにフェードを足すと逆に
+  書き出しとの食い違いを作るため、**意図的に対象外**とする
+- Web UI（preview-server）: bgm と同じ毎 tick 再計算方式。ただしこの層は現状 sfx の
+  `in`/`out` トリム自体を未実装のため、フェードの実効尺は常にデコード済み素材全長を使う
+  （トリム実装時に合わせて見直す）
+
+### インスペクター
+
+- akari-annotations: sfx 選択時に bgm と同じ「フェード」タブ（`fadeIn`/`fadeOut` ノブ）を出す。
+  ducking は bgm 概念のため sfx には出さない
+- 正本は `packages/edit-store`（edit.json テキスト手術）だが、本追記の実装レーン
+  （task 2026-08-18-audio-clip-fades）のファイル境界が `packages/edit-store` を含まないため、
+  書き戻りは `apps/shell/extensions/akari-annotations/src/common/sfx-fade-store.ts` に
+  境界内で完結する独立実装として置いた（`updateArrayElementByIndex` 等 edit-store の
+  export 済みユーティリティは再利用）。将来 edit-store 側の担当タスクが正本へ統合してよい

package/vendor/docs/contract-2026-08-02-preview-parity.md

@@ -76,6 +76,14 @@ cut 境界の選択は宣言順ではなく解決済みタイムラインと z-o
   語彙は `"source"` の 1 つだけで、マーカーが立つのは「今 fit 基準で描かれている全 media item に `scale × fit`
   （`fit = min(outputW / srcW, outputH / srcH)`・srcW / srcH は表示回転後）を一度だけ焼き込んだ」ことを意味する
   （部分適用は禁止。移行は `packages/edit-store/bin/normalize-geometry.mjs`）。x / y / rotate は両基準で同じ意味なので触らない。
+  **「ソース実寸」= 原本の論理寸法（表示回転後）であり、復号フレームの画素寸法ではない（2026-09-18 追記）**。
+  プロキシを復号していてもこの基準は動かない。ここが曖昧だったため、ベースカットのクロップ計算が
+  復号フレーム＝プロキシ寸法を使い、追加レイヤーと寸法基準が食い違っていた（不具合メモ 第10項:
+  1920×1080 原本 / 960×540 プロキシで crop 幅 0.5・scale 1 が 960×1080 ではなく 480×540 になる）。
+  frame-engine 側は `NativeFrameSource.logicalSize` の宣言を基準に使い、宣言が無い / 壊れている
+  ときだけ復号寸法へ退避する（`compositionSourceSize`）。したがってプロキシを復号し得る呼び出し側は
+  原本メタデータから `logicalSize` を宣言する責務を負う。宣言を足すのと、プロキシ差し替えに伴う
+  倍率補償を外すのは、二重補正を避けるため**同一の作業単位**で行う。
   **G1（マーカー・移行・lint の warning `geometry.fit-compat`）ではエンジンはこのマーカーを読まず、描画は 1 バイトも変わらない。
   描画へ反映するのは G2**。cross ref: `docs/contract-2026-07-22-render-basics.md` §4-1（#6 画角操作）。
 

package/vendor/docs/contract-2026-08-03-caption-display-encoding-qc-v1.md

@@ -10,9 +10,30 @@
 `packages/edit-store/src/caption-display.ts` is the only resolver for the opt-in
 `display_policy.mode: "single_line_sequential"` contract. It projects source captions through a
 linear cut/speed/multi-source timeline, then resolves one or two fragments, timing, source
-provenance, merged style variables, and reference-pixel geometry. Render-cut, preview-server, and
-the shell backend consume that result. Browser code only selects already-resolved timeline cues; it
-must not call `Intl.Segmenter` or implement the split algorithm.
+provenance, merged style variables, and reference-pixel geometry. Browser code only selects
+already-resolved timeline cues; it must not call `Intl.Segmenter` or implement the split algorithm.
+
+Every consumer reaches that kernel through one shared entry point,
+`packages/render-cut/src/caption-resolve.mjs` (`resolveCaptionPlan`), which also owns the steps in
+front of it: style-preset resolution, excluded-cue filtering, word-book protected terms, and cut
+normalization. The consumers are render-cut's internal render path, preview-server, gpu-export,
+and osr-export. Naming the kernel alone was not enough: until 2026-09-20 each consumer assembled
+that front half itself, so preview-server handed the kernel a v2 edit with no derived `cuts` and
+resolved zero display cues, while gpu-export and osr-export never consulted `display_policy` at all
+and re-split captions through the legacy overlay generator. A consumer that calls the kernel
+directly, or rebuilds any of those front-half steps, is a deviation.
+
+**Known remaining deviation — the shell backend.** `AkariPreviewService.resolveCaptionDisplay`
+(`apps/shell/extensions/akari-preview/src/node/akari-preview-service.ts`) still calls the kernel
+directly and rebuilds the front half on its own: its own preset resolution, its own cut
+normalization (`captionCompatibleCuts`, computed in frames off `internal.tracks` rather than the
+shared `captionDisplayEdit`), and its own word-book lookup that walks up from `__dirname` and
+silently degrades to no protected terms on any failure. **It never applies excluded-cue
+filtering**, so a cue excluded through `tracks[].items[].source.exclude` still appears in the
+in-app preview while the other four paths drop it. This is a preview-parity hazard of the same
+class as the two defects above. It is listed here rather than silently tolerated; the shell is
+bundled by Theia and cannot assume `packages/` sits next to it, so routing it through
+`resolveCaptionPlan` is a packaging question, not a one-line import.
 
 The policy rejects unsupported `at`, `track`, transition, and timeline winner semantics; caption
 style/emphasis conflicts; non-NFC or trimmed text; invalid manual fragments; unresolved long text;